@dtifx/diff

Overview

@dtifx/diff analyses DTIF token snapshots and turns them into actionable change reports. It powers
human-friendly summaries, machine-readable outputs, and CI gates that understand semantic impact.

Installation

``bash
pnpm add -D @dtifx/cli @dtifx/diff


or

`bash
pnpm exec dtifx diff compare tokens/base.json tokens/feature.json --format markdown --summary
pnpm exec dtifx diff compare tokens/base.json tokens/feature.json --fail-on-breaking --filter-type color
pnpm exec dtifx diff compare tokens/base.json tokens/feature.json --format html --output report.html
`

> [!NOTE] The CLI expects concrete file paths.
>
> If you prefer comparing Git refs, wrap the command with shell helpers such as
> pnpm exec dtifx diff compare <(git show main:tokens/index.json) tokens/index.json or extract the
> ref contents to temporary files before invoking the CLI.

Helpful flags:

- --format – Choose the output format.
- --output – Write the rendered diff to disk instead of stdout.
- --filter-type / --filter-impact / --filter-path – Narrow which
changes appear.
- --fail-on-breaking / --fail-on-changes – Enforce quality gates for CI pipelines.
- --summary / --mode – Control the verbosity of the report.

$3

`ts
import { createRunContext, createSessionTokenSourcePort, runDiffSession } from '@dtifx/diff';

const sources = {
previous: { kind: 'file', target: 'tokens/base.json' },
next: { kind: 'file', target: 'tokens/feature.json' },
};

const session = await runDiffSession(
{
tokenSource: createSessionTokenSourcePort(sources),
diagnostics: { emit: console.error },
},
{
filter: { types: ['color'] },
failure: { failOnBreaking: true },
},
);

const context = createRunContext({ sources, startedAt: new Date(), durationMs: 640 });
console.log(session.filteredDiff.breaking.length, context.previous);
``

Extend the behaviour with custom rename, impact, and summary strategies when needed.

Examples

- Diff workflow guide
- Quickstart

Further reading

- Diff API reference
- CLI reference

License

MIT