cliguard 0.4.0 → 0.6.0

package/README.md

@@ -1,5 +1,10 @@
 # cliguard
 
+[![npm version](https://img.shields.io/npm/v/cliguard.svg)](https://www.npmjs.com/package/cliguard)
+[![npm downloads](https://img.shields.io/npm/dm/cliguard.svg)](https://www.npmjs.com/package/cliguard)
+[![CI](https://github.com/Bryandero98/cliguard/actions/workflows/ci.yml/badge.svg)](https://github.com/Bryandero98/cliguard/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/cliguard.svg)](https://github.com/Bryandero98/cliguard/blob/main/LICENSE)
+
 Snapshot testing for CLI contracts.
 
 ## The problem
@@ -23,7 +28,7 @@ The first line fails your CI. The second one doesn't - `--dry-run` is new and op
 npm install --save-dev cliguard
 ```
 
-Your CLI's entry file should **export** its Commander `Command` instance instead of calling `.parse()` itself - the cleanest way to adopt cliguard, since it never risks running any of your CLI's real logic:
+Point cliguard straight at your existing CLI's entry file - most real CLIs work unmodified, since cliguard automatically captures the framework instance they build at load time even if they never export it (see "Entry files that build the CLI lazily" below). Exporting the instance is still the cleanest way to adopt cliguard where you can, since it never risks running any of your CLI's real logic:
 
 ```js
 // bin/cli.js
@@ -56,11 +61,31 @@ npx cliguard init ./bin/cli.js --adapter cac
 
 `cac` itself is an optional dependency of cliguard - only installed if you actually use `--adapter cac`.
 
+Built with [Yargs](https://github.com/yargs/yargs) instead? Export the instance the same way and pass `--adapter yargs`:
+
+```js
+// bin/cli.js
+const yargs = require("yargs/yargs");
+
+const cli = yargs([])
+  .command("build <entry>", "build the project", (y) =>
+    y.option("target", { alias: "t", describe: "build target", type: "string" }).demandOption("target"),
+  );
+
+module.exports = { cli };
+```
+
+```sh
+npx cliguard init ./bin/cli.js --adapter yargs
+```
+
+Like `cac`, `yargs` itself is an optional dependency of cliguard - only installed if you actually use `--adapter yargs`.
+
 ### Entry files that build the CLI lazily
 
 Not every real CLI exports its instance - plenty build it inside a function that only runs when something actually calls it, or just never had a reason to export it. Pointing cliguard straight at a file like that would fail with "no instance found" under the rule above alone.
 
-So when the direct export lookup finds nothing, cliguard tries one more thing automatically, no flag needed: it patches the exact copy of `commander`/`cac` your entry file will itself `require()`, so any `new Command()` (or CAC's `cac()`) call anywhere in your file's own top-level code is captured - even though nothing was ever exported. This covers most real CLIs, since even ones that never bother exporting still build (and often `.parse()`) at the top of their own file as a matter of course.
+So when the direct export lookup finds nothing, cliguard tries one more thing automatically, no flag needed: it patches the exact copy of `commander`/`cac`/`yargs` your entry file will itself `require()`, so any `new Command()` (or CAC's `cac()`, or a `yargs(...)` call) anywhere in your file's own top-level code is captured - even though nothing was ever exported. This covers most real CLIs, since even ones that never bother exporting still build (and often `.parse()`) at the top of their own file as a matter of course.
 
 It can't reach an instance built strictly *inside* a function that's only invoked later, never automatically at load time (a `main()` some other file calls, not the file cliguard is pointed at) - there's no safe, generic way for cliguard to know which function to call or with what arguments. For that shape, write a small wrapper file that reaches into the target's own internals to get (or construct) the instance, and point cliguard at the wrapper instead of the original entry file. The exact shape of that wrapper is inherently project-specific - it's standing in for whatever that project's own entry point would otherwise do - but the command stays the same either way: `cliguard init ./your-wrapper.mjs`.
 
@@ -93,13 +118,33 @@ npx cliguard check ./bin/cli.js --json
   "changes": [
     { "type": "BREAKING", "path": "root -> build -> option[--target]", "message": "Option \"--target\" was removed." }
   ],
-  "summary": { "breaking": 1, "additive": 0, "patch": 0 },
+  "summary": { "breaking": 1, "acknowledgedBreaking": 0, "additive": 0, "patch": 0 },
   "suggestedBump": "major"
 }
 ```
 
 `suggestedBump` is the semver bump this diff implies (`"major"`, `"minor"`, `"patch"`, or `null` if nothing changed) - a direct read of the same BREAKING/ADDITIVE/PATCH classification the emoji output already uses, so a release script never has to re-derive it.
 
+### Accepting an intentional breaking change
+
+Sometimes a `BREAKING` change is exactly what you meant to ship - a flag genuinely needed to go away in a major version. Running `cliguard update` after a real, intentional break re-baselines the *entire* contract silently; it doesn't leave a record of what changed or why. `cliguard accept` does:
+
+```sh
+npx cliguard accept ./bin/cli.js "root -> build -> option[--target]" --reason "removed in v2.0, replaced by --targets"
+```
+
+This only works against a change `check` would currently report as `BREAKING` - it reads the exact `path` from your own `check` output (text or `--json`), so there's nothing to guess. It writes `.cliguard/accepted-breaks.json` (commit this file); from then on, `check` still shows that change - now as a 🟣 acknowledged line with the reason attached - but stops counting it toward the `BREAKING` total that fails your build. Any *other*, un-accepted breaking change still fails CI as normal. Once you're done, `cliguard update` still re-baselines the contract to match reality, same as always.
+
+### Comparing two contracts directly
+
+`cliguard diff <old.json> <new.json>` runs the same comparison as `check`, but reads both sides straight off disk instead of running any CLI - useful for comparing two tags' committed contracts (`git show v1.0.0:.cliguard/contract.json > old.json`), or reviewing a contract change in a PR without a working copy of the target CLI at all:
+
+```sh
+npx cliguard diff old-contract.json new-contract.json --json
+```
+
+It respects `.cliguard/accepted-breaks.json` the same way `check` does, and exits `1` on an un-acknowledged `BREAKING` change.
+
 ## How changes get classified
 
 | | Removed | Added | Required flipped | Value type / default changed |
@@ -113,10 +158,14 @@ Full rules live in [`src/core/diff.engine.ts`](src/core/diff.engine.ts) - it's t
 
 ## CI integration
 
+The bundled GitHub Action (`Bryandero98/cliguard@v1`) is the recommended way to run this in CI: on top of the same exit-code gate as `npx cliguard check`, it posts the diff as a PR comment - updated in place on every push, not a new one each time - so a reviewer sees exactly what changed without opening the CI log:
+
 ```yaml
 # .github/workflows/cliguard.yml
 name: CLI contract
 on: [pull_request]
+permissions:
+  pull-requests: write # needed for the PR comment
 jobs:
   check:
     runs-on: ubuntu-latest
@@ -125,14 +174,24 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: 22.x }
       - run: npm ci
-      - run: npx cliguard check ./bin/cli.js
+      - uses: Bryandero98/cliguard@v1
+        with:
+          entry: ./bin/cli.js
+          # adapter: yargs        # default: commander
+          # comment-on-pr: false  # default: true
+```
+
+Set `comment-on-pr: false` to keep the exit-code gate without the comment, or use the raw CLI directly for a non-GitHub CI provider:
+
+```yaml
+- run: npx cliguard check ./bin/cli.js
 ```
 
 ## Supported frameworks
 
-[Commander.js](https://github.com/tj/commander.js) (default) and [CAC](https://github.com/cacjs/cac) (`--adapter cac`) today. The core (types + diff engine) is 100% framework-agnostic by design: every framework-specific detail lives behind the `CliAdapter` interface in [`src/adapters/`](src/adapters/), so adding a new adapter never touches the diffing logic. Yargs is the next open gap - see the [good first issue](https://github.com/Bryandero98/cliguard/labels/good%20first%20issue).
+[Commander.js](https://github.com/tj/commander.js) (default), [CAC](https://github.com/cacjs/cac) (`--adapter cac`), and [Yargs](https://github.com/yargs/yargs) (`--adapter yargs`) today. The core (types + diff engine) is 100% framework-agnostic by design: every framework-specific detail lives behind the `CliAdapter` interface in [`src/adapters/`](src/adapters/), so adding a new adapter never touches the diffing logic. Click, Clap, and Cobra are the next open gaps - see the [good first issue](https://github.com/Bryandero98/cliguard/labels/good%20first%20issue).
 
-A couple of `OptionContract`/`ArgumentContract` fields carry real, framework-specific limitations rather than a mapping gap - see [`src/adapters/cac.adapter.ts`](src/adapters/cac.adapter.ts)'s own doc comment for exactly which ones and why (CAC has no declarative "this flag must be passed" concept, and no per-argument description).
+A couple of `OptionContract`/`ArgumentContract` fields carry real, framework-specific limitations rather than a mapping gap - see [`src/adapters/cac.adapter.ts`](src/adapters/cac.adapter.ts)'s own doc comment for exactly which ones and why (CAC has no declarative "this flag must be passed" concept, and no per-argument description). Yargs's own real limitation is the opposite kind - see [`src/adapters/yargs.adapter.ts`](src/adapters/yargs.adapter.ts)'s doc comment for why each command's options are read from a fresh, isolated instance rather than the shared one the target CLI actually built.
 
 The current adapter mechanism loads the target CLI's entry file into the Node process (`import()`/`require()`) and reads its object graph directly, so the next targets are other Node frameworks. Cross-language support (Python's Click, Rust's Clap, Go's Cobra) is a real future direction, but needs a different extraction strategy first, since a compiled Clap/Cobra binary can't be `require()`'d into Node the way a JS CLI can - most likely each of those would introspect via a structured `--help` output (some frameworks support a JSON mode) rather than the same in-process approach.
 

package/dist/adapters/yargs.adapter.d.ts

@@ -0,0 +1,96 @@
+import type { Contract } from "../core/types";
+import type { CliAdapter } from "./adapter.interface";
+/**
+ * Extracts a Contract from a target file that builds a yargs CLI. Never
+ * parses --help output - every field comes straight from yargs's own
+ * `getOptions()`/`getInternalMethods()` object graph, matching
+ * CommanderAdapter/CacAdapter's approach.
+ *
+ * Yargs has no per-command object tree the way Commander does - every
+ * `.option()` call (wherever it happens) mutates one shared options bag on
+ * the instance, and a command's own options only get registered when its
+ * `builder` function actually runs (normally deferred until that command
+ * matches at real parse time). To read a command's options in isolation,
+ * this adapter calls each command's `builder` against a **fresh, empty**
+ * yargs instance rather than the shared one - the same thing yargs itself
+ * does internally via `getInternalMethods().reset()` before running a
+ * command's builder (verified in yargs's own `command.js`), just without
+ * needing yargs to have actually matched and parsed real argv first.
+ */
+export declare class YargsAdapter implements CliAdapter {
+    readonly id = "yargs";
+    extract(entryPath: string): Promise<Contract>;
+    private loadYargs;
+    /**
+     * Captures every instance produced by calling `require("yargs")` or
+     * `require("yargs/yargs")` as a function, from the target's own
+     * resolved copy of the package - real CLIs almost always reach yargs
+     * through one of these two calls (`yargs(hideBin(process.argv))` or
+     * `require("yargs/yargs")(args)`), usually without ever exporting the
+     * result.
+     *
+     * Unlike commander/cac's `captureConstructions` (which patches a
+     * *named property* on the required module, since `Command`/`cac` are
+     * named exports), yargs's own package export *is itself* the callable
+     * factory - `require("yargs")` returns a function directly, not a
+     * container object with a factory property on it. So this replaces the
+     * entire cached module's `.exports` with a `Proxy` around that
+     * function, trapping `apply` instead of `construct`: the proxy is
+     * still callable exactly like the original (and forwards every other
+     * property read/write straight through, since no `get`/`set` trap is
+     * defined - which is what makes `require("yargs")`'s other form, using
+     * it directly as a pre-built singleton instance without ever calling
+     * it, keep working unmodified). `require("yargs")` and
+     * `require("yargs/yargs")` resolve to two different files
+     * (`index.cjs` vs `yargs.cjs`), so both are patched independently -
+     * whichever the target actually uses is the one that ever fires.
+     */
+    private captureYargsFactoryCalls;
+    /** Among every instance captured during construction, the one that looks most like the real, fully-built root program. */
+    private pickBestCandidate;
+    private score;
+    /** Handles `export default`, `module.exports = cli`, and named exports. */
+    private findYargs;
+    /**
+     * Structural check, not `instanceof` - see CommanderAdapter's
+     * identical-purpose `looksLikeCommand` for why (the target's own
+     * `yargs` install is almost always a separate copy from cliguard's).
+     * `getInternalMethods` is fairly distinctive to yargs among CLI
+     * frameworks, so it's included alongside the more generic
+     * `command`/`option`/`getOptions` to keep this from ever
+     * false-matching a Commander or CAC instance.
+     */
+    private looksLikeYargs;
+    private mapRoot;
+    /**
+     * Runs `handler.builder` against a fresh, empty yargs instance rather
+     * than the shared one the target built - see this class's own doc
+     * comment for why. A side effect worth calling out: every fresh
+     * instance auto-registers its own `help`/`version` options (yargs's
+     * own default, not something this specific command declared), so
+     * those two names are always excluded below - matching
+     * CommanderAdapter/CacAdapter, neither of which surfaces their
+     * framework's built-in help/version as a regular option either.
+     */
+    private mapCommand;
+    private freshInstance;
+    private mapArguments;
+    /**
+     * Yargs stores an option's own name as a real entry in `options.string`
+     * / `options.boolean` *and* separately re-registers every alias as its
+     * own addressable entry in the same arrays (so `-o` shows up next to
+     * `output`, not just inside `output`'s own alias list) - excluded here
+     * via `aliasTargets` so each alias surfaces exactly once, nested under
+     * its canonical option, matching CommanderAdapter/CacAdapter's shape.
+     * Positional names go through this same shared bag too (`.positional()`
+     * is implemented in terms of the same option-registration machinery
+     * internally) - excluded via `positionalNames` so they surface only in
+     * `arguments`, never duplicated into `options`.
+     */
+    private mapOptions;
+    private describe;
+    /** `-x` for a single-character name, `--xray` otherwise - yargs's own alias lists carry neither dash. */
+    private dashPrefix;
+    /** Everything not declared `boolean`/`array`/`number` defaults to yargs's own "string" bucket - collapsed to this Contract's two-value OptionValueType the same way CacAdapter does. */
+    private inferValueType;
+}

package/dist/adapters/yargs.adapter.js

@@ -0,0 +1,286 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YargsAdapter = void 0;
+const path_1 = require("path");
+const load_module_1 = require("./load-module");
+const YARGS_STRING_MARKER = "__yargsString__:";
+/**
+ * Extracts a Contract from a target file that builds a yargs CLI. Never
+ * parses --help output - every field comes straight from yargs's own
+ * `getOptions()`/`getInternalMethods()` object graph, matching
+ * CommanderAdapter/CacAdapter's approach.
+ *
+ * Yargs has no per-command object tree the way Commander does - every
+ * `.option()` call (wherever it happens) mutates one shared options bag on
+ * the instance, and a command's own options only get registered when its
+ * `builder` function actually runs (normally deferred until that command
+ * matches at real parse time). To read a command's options in isolation,
+ * this adapter calls each command's `builder` against a **fresh, empty**
+ * yargs instance rather than the shared one - the same thing yargs itself
+ * does internally via `getInternalMethods().reset()` before running a
+ * command's builder (verified in yargs's own `command.js`), just without
+ * needing yargs to have actually matched and parsed real argv first.
+ */
+class YargsAdapter {
+    constructor() {
+        this.id = "yargs";
+    }
+    async extract(entryPath) {
+        const cli = await this.loadYargs(entryPath);
+        return {
+            contractVersion: 1,
+            adapter: this.id,
+            capturedAt: new Date().toISOString(),
+            root: this.mapRoot(cli),
+        };
+    }
+    async loadYargs(entryPath) {
+        // Patched *before* the target loads, so a `yargs(args)` or
+        // `require("yargs/yargs")(args)` call anywhere in its own top-level
+        // code gets captured as a side effect of loadModule() below - even if
+        // the target never exports the result anywhere. See
+        // captureYargsFactoryCalls's own doc for why this is safe.
+        const captured = this.captureYargsFactoryCalls(entryPath);
+        const { viaImport, viaRequire } = await (0, load_module_1.loadModule)(entryPath);
+        const cli = this.findYargs(viaImport.moduleExports) ??
+            this.findYargs(viaRequire.moduleExports) ??
+            this.pickBestCandidate(captured);
+        if (cli)
+            return cli;
+        // See CommanderAdapter's identical block for why both real load
+        // errors - not a swallowed, generic guess - matter here.
+        throw new Error(`cliguard: no yargs instance found in "${entryPath}". ` +
+            "Export it as `export default cli`, `module.exports = cli`, " +
+            "or a named export (e.g. `export const cli = yargs(hideBin(process.argv))`). If " +
+            "the file builds its yargs instance inside a function that only runs when " +
+            "something calls it (never at the top level), point cliguard at a small wrapper " +
+            "file that calls that function and exports the result instead - see the README's " +
+            '"Entry files that build the CLI lazily" section.\n' +
+            `  import() failed: ${viaImport.error ?? "module loaded, but exported no yargs instance"}\n` +
+            `  require() failed: ${viaRequire.error ?? "module loaded, but exported no yargs instance"}`);
+    }
+    /**
+     * Captures every instance produced by calling `require("yargs")` or
+     * `require("yargs/yargs")` as a function, from the target's own
+     * resolved copy of the package - real CLIs almost always reach yargs
+     * through one of these two calls (`yargs(hideBin(process.argv))` or
+     * `require("yargs/yargs")(args)`), usually without ever exporting the
+     * result.
+     *
+     * Unlike commander/cac's `captureConstructions` (which patches a
+     * *named property* on the required module, since `Command`/`cac` are
+     * named exports), yargs's own package export *is itself* the callable
+     * factory - `require("yargs")` returns a function directly, not a
+     * container object with a factory property on it. So this replaces the
+     * entire cached module's `.exports` with a `Proxy` around that
+     * function, trapping `apply` instead of `construct`: the proxy is
+     * still callable exactly like the original (and forwards every other
+     * property read/write straight through, since no `get`/`set` trap is
+     * defined - which is what makes `require("yargs")`'s other form, using
+     * it directly as a pre-built singleton instance without ever calling
+     * it, keep working unmodified). `require("yargs")` and
+     * `require("yargs/yargs")` resolve to two different files
+     * (`index.cjs` vs `yargs.cjs`), so both are patched independently -
+     * whichever the target actually uses is the one that ever fires.
+     */
+    captureYargsFactoryCalls(entryPath) {
+        const captured = [];
+        const record = (instance) => {
+            if (instance && typeof instance === "object")
+                captured.push(instance);
+        };
+        const targetDir = (0, path_1.dirname)((0, path_1.resolve)(process.cwd(), entryPath));
+        for (const packageName of ["yargs", "yargs/yargs"]) {
+            let resolvedPath;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports -- resolving the target's own copy of a CJS package, not a static dependency of this file
+                resolvedPath = require.resolve(packageName, { paths: [targetDir] });
+                // eslint-disable-next-line @typescript-eslint/no-require-imports -- ensures the module is loaded into require.cache before this patches it
+                require(resolvedPath);
+            }
+            catch {
+                // Not resolvable from the target's own location (e.g. the target
+                // only uses one of the two import styles) - nothing to patch.
+                continue;
+            }
+            const cacheEntry = require.cache[resolvedPath];
+            const original = cacheEntry?.exports;
+            if (!cacheEntry || typeof original !== "function")
+                continue;
+            cacheEntry.exports = new Proxy(original, {
+                apply(target, thisArg, args) {
+                    const instance = Reflect.apply(target, thisArg, args);
+                    record(instance);
+                    return instance;
+                },
+            });
+        }
+        return captured;
+    }
+    /** Among every instance captured during construction, the one that looks most like the real, fully-built root program. */
+    pickBestCandidate(candidates) {
+        const valid = candidates.filter((candidate) => this.looksLikeYargs(candidate));
+        if (valid.length === 0)
+            return undefined;
+        return valid.reduce((best, candidate) => this.score(candidate) > this.score(best) ? candidate : best);
+    }
+    score(instance) {
+        const options = instance.getOptions();
+        const handlerCount = Object.keys(instance.getInternalMethods().getCommandInstance().handlers).length;
+        return (handlerCount +
+            options.boolean.length +
+            options.string.length +
+            options.array.length +
+            options.number.length);
+    }
+    /** Handles `export default`, `module.exports = cli`, and named exports. */
+    findYargs(moduleExports) {
+        if (this.looksLikeYargs(moduleExports)) {
+            return moduleExports;
+        }
+        if (moduleExports && typeof moduleExports === "object") {
+            const exportsObject = moduleExports;
+            if (this.looksLikeYargs(exportsObject.default)) {
+                return exportsObject.default;
+            }
+            for (const value of Object.values(exportsObject)) {
+                if (this.looksLikeYargs(value))
+                    return value;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Structural check, not `instanceof` - see CommanderAdapter's
+     * identical-purpose `looksLikeCommand` for why (the target's own
+     * `yargs` install is almost always a separate copy from cliguard's).
+     * `getInternalMethods` is fairly distinctive to yargs among CLI
+     * frameworks, so it's included alongside the more generic
+     * `command`/`option`/`getOptions` to keep this from ever
+     * false-matching a Commander or CAC instance.
+     */
+    looksLikeYargs(value) {
+        if (!value || typeof value !== "object")
+            return false;
+        const candidate = value;
+        return (typeof candidate.command === "function" &&
+            typeof candidate.option === "function" &&
+            typeof candidate.getOptions === "function" &&
+            typeof candidate.getInternalMethods === "function");
+    }
+    mapRoot(cli) {
+        const commandInstance = cli.getInternalMethods().getCommandInstance();
+        const options = cli.getOptions();
+        const descriptions = cli.getInternalMethods().getUsageInstance().getDescriptions();
+        return {
+            name: cli.$0,
+            description: "",
+            aliases: [],
+            options: this.mapOptions(options, descriptions, new Set()),
+            arguments: [],
+            subcommands: Object.entries(commandInstance.handlers).map(([name, handler]) => this.mapCommand(name, handler, commandInstance.aliasMap)),
+        };
+    }
+    /**
+     * Runs `handler.builder` against a fresh, empty yargs instance rather
+     * than the shared one the target built - see this class's own doc
+     * comment for why. A side effect worth calling out: every fresh
+     * instance auto-registers its own `help`/`version` options (yargs's
+     * own default, not something this specific command declared), so
+     * those two names are always excluded below - matching
+     * CommanderAdapter/CacAdapter, neither of which surfaces their
+     * framework's built-in help/version as a regular option either.
+     */
+    mapCommand(name, handler, parentAliasMap) {
+        const scoped = this.freshInstance();
+        if (typeof handler.builder === "function") {
+            handler.builder(scoped, false);
+        }
+        else if (handler.builder && typeof handler.builder === "object") {
+            scoped.options(handler.builder);
+        }
+        const commandInstance = scoped.getInternalMethods().getCommandInstance();
+        const options = scoped.getOptions();
+        const descriptions = scoped.getInternalMethods().getUsageInstance().getDescriptions();
+        const positionals = [...handler.demanded, ...handler.optional];
+        const positionalNames = new Set(positionals.map((positional) => positional.cmd[0]));
+        return {
+            name,
+            description: handler.description || "",
+            aliases: Object.entries(parentAliasMap)
+                .filter(([, canonical]) => canonical === name)
+                .map(([alias]) => alias),
+            options: this.mapOptions(options, descriptions, positionalNames),
+            arguments: this.mapArguments(handler, descriptions),
+            subcommands: Object.entries(commandInstance.handlers).map(([subName, subHandler]) => this.mapCommand(subName, subHandler, commandInstance.aliasMap)),
+        };
+    }
+    freshInstance() {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports -- cliguard's own pinned copy, deliberately separate from the target's - this instance never touches the target's code, it's purely scratch space for reading one command's own builder output in isolation
+        const factory = require("yargs/yargs");
+        return factory([])
+            .exitProcess(false)
+            .fail(() => undefined);
+    }
+    mapArguments(handler, descriptions) {
+        const required = handler.demanded.map((positional) => ({ positional, required: true }));
+        const optional = handler.optional.map((positional) => ({ positional, required: false }));
+        return [...required, ...optional].map(({ positional, required: isRequired }) => ({
+            name: positional.cmd[0],
+            required: isRequired,
+            variadic: positional.variadic,
+            description: this.describe(descriptions, positional.cmd[0]),
+        }));
+    }
+    /**
+     * Yargs stores an option's own name as a real entry in `options.string`
+     * / `options.boolean` *and* separately re-registers every alias as its
+     * own addressable entry in the same arrays (so `-o` shows up next to
+     * `output`, not just inside `output`'s own alias list) - excluded here
+     * via `aliasTargets` so each alias surfaces exactly once, nested under
+     * its canonical option, matching CommanderAdapter/CacAdapter's shape.
+     * Positional names go through this same shared bag too (`.positional()`
+     * is implemented in terms of the same option-registration machinery
+     * internally) - excluded via `positionalNames` so they surface only in
+     * `arguments`, never duplicated into `options`.
+     */
+    mapOptions(options, descriptions, positionalNames) {
+        const aliasTargets = new Set(Object.values(options.alias).flat());
+        const allNames = new Set([
+            ...options.boolean,
+            ...options.string,
+            ...options.array,
+            ...options.number,
+        ]);
+        return [...allNames]
+            .filter((name) => name !== "help" && name !== "version")
+            .filter((name) => !positionalNames.has(name))
+            .filter((name) => !aliasTargets.has(name))
+            .map((name) => ({
+            flags: [
+                `--${name}`,
+                ...(options.alias[name] ?? []).map((alias) => this.dashPrefix(alias)),
+            ].join(", "),
+            name,
+            aliases: (options.alias[name] ?? []).map((alias) => this.dashPrefix(alias)),
+            description: this.describe(descriptions, name),
+            required: name in options.demandedOptions,
+            valueType: this.inferValueType(options, name),
+            variadic: options.array.includes(name),
+            defaultValue: name in options.default ? options.default[name] : null,
+        }));
+    }
+    describe(descriptions, name) {
+        const raw = descriptions[name] ?? "";
+        return raw.startsWith(YARGS_STRING_MARKER) ? raw.slice(YARGS_STRING_MARKER.length) : raw;
+    }
+    /** `-x` for a single-character name, `--xray` otherwise - yargs's own alias lists carry neither dash. */
+    dashPrefix(name) {
+        return name.length === 1 ? `-${name}` : `--${name}`;
+    }
+    /** Everything not declared `boolean`/`array`/`number` defaults to yargs's own "string" bucket - collapsed to this Contract's two-value OptionValueType the same way CacAdapter does. */
+    inferValueType(options, name) {
+        return options.boolean.includes(name) ? "boolean" : "string";
+    }
+}
+exports.YargsAdapter = YargsAdapter;

package/dist/bin.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const cac_adapter_1 = require("./adapters/cac.adapter");
 const commander_adapter_1 = require("./adapters/commander.adapter");
+const yargs_adapter_1 = require("./adapters/yargs.adapter");
 const diff_engine_1 = require("./core/diff.engine");
 const storage_1 = require("./core/storage");
 const types_1 = require("./core/types");
@@ -14,6 +15,7 @@ const types_1 = require("./core/types");
 const adapters = {
     commander: new commander_adapter_1.CommanderAdapter(),
     cac: new cac_adapter_1.CacAdapter(),
+    yargs: new yargs_adapter_1.YargsAdapter(),
 };
 function resolveAdapter(name) {
     const adapter = adapters[name];
@@ -64,20 +66,63 @@ program
         const oldContract = (0, storage_1.readContract)();
         const newContract = await resolveAdapter(options.adapter).extract(entry);
         const diff = diffEngine.compare(oldContract, newContract);
-        const hasBreaking = diff.some((entry) => entry.type === types_1.ChangeType.BREAKING);
+        const acceptedPaths = indexAcceptedBreaks((0, storage_1.readAcceptedBreaks)());
+        const hasBreaking = diff.some((change) => change.type === types_1.ChangeType.BREAKING && !acceptedPaths.has(change.path));
         if (options.json) {
-            console.log(JSON.stringify(toJsonResult(diff), null, 2));
+            console.log(JSON.stringify(toJsonResult(diff, acceptedPaths), null, 2));
             return hasBreaking ? 1 : 0;
         }
         if (diff.length === 0) {
             console.log("✅ CLI contract is intact.");
             return 0;
         }
-        printDiff(diff);
+        printDiff(diff, acceptedPaths);
         return hasBreaking ? 1 : 0;
     });
     process.exit(exitCode);
 });
+program
+    .command("accept")
+    .description("Record that a specific BREAKING change is intentional, so `check` stops failing CI for it")
+    .argument("<entry>", "path to the target CLI's entry file")
+    .argument("<changePath>", 'the exact DiffResult path to accept, e.g. "root -> build -> option[--target]"')
+    .requiredOption("-r, --reason <text>", "why this break is intentional - shown in check output")
+    .option(...adapterOption)
+    .action(async (entry, changePath, options) => {
+    const exitCode = await withSuppressedExit(async () => {
+        const reason = options.reason.trim();
+        if (!reason) {
+            console.error("cliguard: --reason can't be blank - it's the audit trail for why this break is OK.");
+            return 1;
+        }
+        const oldContract = (0, storage_1.readContract)();
+        const newContract = await resolveAdapter(options.adapter).extract(entry);
+        const diff = diffEngine.compare(oldContract, newContract);
+        const match = diff.find((change) => change.type === types_1.ChangeType.BREAKING && change.path === changePath);
+        if (!match) {
+            const breaking = diff.filter((change) => change.type === types_1.ChangeType.BREAKING);
+            console.error(`cliguard: no current BREAKING change at path "${changePath}".` +
+                (breaking.length === 0
+                    ? " There are no BREAKING changes right now - nothing to accept."
+                    : ` Currently breaking:\n${breaking.map((change) => `  - ${change.path}`).join("\n")}`));
+            return 1;
+        }
+        // Replaces any earlier acceptance at the same path rather than
+        // accumulating duplicates - re-running `accept` updates the reason.
+        const remaining = (0, storage_1.readAcceptedBreaks)().filter((accepted) => accepted.path !== changePath);
+        const accepted = {
+            path: changePath,
+            reason,
+            acceptedAt: new Date().toISOString(),
+        };
+        (0, storage_1.writeAcceptedBreaks)([...remaining, accepted]);
+        console.log(`✅ Accepted: [${changePath}] ${match.message}`);
+        console.log(`   Reason: ${reason}`);
+        console.log(`   Recorded in ${(0, storage_1.getAcceptedBreaksDisplayPath)()} - commit this file.`);
+        return 0;
+    });
+    process.exit(exitCode);
+});
 program
     .command("update")
     .description("Overwrite the committed contract with the CLI's current surface")
@@ -92,6 +137,33 @@ program
     });
     process.exit(exitCode);
 });
+program
+    .command("diff")
+    .description("Compare two contract files directly, without running any CLI")
+    .argument("<oldContract>", "path to the older contract JSON file")
+    .argument("<newContract>", "path to the newer contract JSON file")
+    .option("--json", "print a machine-readable JSON result instead of text", false)
+    .action((oldPath, newPath, options) => {
+    // No adapter, no target CLI ever loaded here - just two files off
+    // disk - so none of withSuppressedExit's process.exit-race concerns
+    // apply. A thrown Error (bad path, corrupt JSON) still surfaces via
+    // this program's own top-level parseAsync().catch() below.
+    const oldContract = (0, storage_1.readContractFile)(oldPath);
+    const newContract = (0, storage_1.readContractFile)(newPath);
+    const diff = diffEngine.compare(oldContract, newContract);
+    const acceptedPaths = indexAcceptedBreaks((0, storage_1.readAcceptedBreaks)());
+    const hasBreaking = diff.some((change) => change.type === types_1.ChangeType.BREAKING && !acceptedPaths.has(change.path));
+    if (options.json) {
+        console.log(JSON.stringify(toJsonResult(diff, acceptedPaths), null, 2));
+        process.exit(hasBreaking ? 1 : 0);
+    }
+    if (diff.length === 0) {
+        console.log("✅ Contracts are identical.");
+        process.exit(0);
+    }
+    printDiff(diff, acceptedPaths);
+    process.exit(hasBreaking ? 1 : 0);
+});
 /**
  * Runs `action` with `process.exit` neutralized, restoring the real one
  * the instant `action` settles - then the caller calls the *real*
@@ -123,9 +195,19 @@ async function withSuppressedExit(action) {
         process.exit = realExit;
     }
 }
-function toJsonResult(diff) {
+function indexAcceptedBreaks(accepted) {
+    return new Map(accepted.map((entry) => [entry.path, entry]));
+}
+function toJsonResult(diff, acceptedPaths) {
+    const changes = diff.map((entry) => {
+        if (entry.type !== types_1.ChangeType.BREAKING)
+            return entry;
+        const accepted = acceptedPaths.get(entry.path);
+        return accepted ? { ...entry, acknowledged: true, reason: accepted.reason } : entry;
+    });
     const summary = {
-        breaking: diff.filter((entry) => entry.type === types_1.ChangeType.BREAKING).length,
+        breaking: changes.filter((change) => change.type === types_1.ChangeType.BREAKING && !change.acknowledged).length,
+        acknowledgedBreaking: changes.filter((change) => change.type === types_1.ChangeType.BREAKING && change.acknowledged).length,
         additive: diff.filter((entry) => entry.type === types_1.ChangeType.ADDITIVE).length,
         patch: diff.filter((entry) => entry.type === types_1.ChangeType.PATCH).length,
     };
@@ -136,11 +218,17 @@ function toJsonResult(diff) {
             : summary.patch > 0
                 ? "patch"
                 : null;
-    return { ok: summary.breaking === 0, changes: diff, summary, suggestedBump };
+    return { ok: summary.breaking === 0, changes, summary, suggestedBump };
 }
-function printDiff(diff) {
+function printDiff(diff, acceptedPaths) {
     for (const entry of diff) {
-        console.log(`${emojiFor(entry.type)} [${entry.path}] ${entry.message}`);
+        const accepted = entry.type === types_1.ChangeType.BREAKING ? acceptedPaths.get(entry.path) : undefined;
+        if (accepted) {
+            console.log(`🟣 [${entry.path}] ${entry.message} (acknowledged: ${accepted.reason})`);
+        }
+        else {
+            console.log(`${emojiFor(entry.type)} [${entry.path}] ${entry.message}`);
+        }
     }
 }
 function emojiFor(type) {

package/dist/core/storage.d.ts

@@ -1,6 +1,20 @@
-import type { Contract } from "./types";
+import type { AcceptedBreak, Contract } from "./types";
 /** Contract path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
 export declare function getContractDisplayPath(): string;
+/** Accepted-breaks path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
+export declare function getAcceptedBreaksDisplayPath(): string;
 export declare function contractExists(): boolean;
 export declare function readContract(): Contract;
 export declare function writeContract(contract: Contract): void;
+/**
+ * Reads a Contract from an arbitrary path, not the committed
+ * `.cliguard/contract.json` - for `cliguard diff <a> <b>`, comparing two
+ * contract files directly (e.g. two tags' committed contracts pulled via
+ * `git show`) without running any real CLI. `displayPath` is what error
+ * messages name; defaults to `path` itself since a caller-supplied path is
+ * already about as displayable as it gets.
+ */
+export declare function readContractFile(path: string, displayPath?: string): Contract;
+/** Unlike readContract, a missing file is normal (most projects never accept a break) - returns [] rather than throwing. */
+export declare function readAcceptedBreaks(): AcceptedBreak[];
+export declare function writeAcceptedBreaks(breaks: readonly AcceptedBreak[]): void;

package/dist/core/storage.js

@@ -1,16 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getContractDisplayPath = getContractDisplayPath;
+exports.getAcceptedBreaksDisplayPath = getAcceptedBreaksDisplayPath;
 exports.contractExists = contractExists;
 exports.readContract = readContract;
 exports.writeContract = writeContract;
+exports.readContractFile = readContractFile;
+exports.readAcceptedBreaks = readAcceptedBreaks;
+exports.writeAcceptedBreaks = writeAcceptedBreaks;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const CONTRACT_PATH = (0, path_1.join)(process.cwd(), ".cliguard", "contract.json");
+const ACCEPTED_BREAKS_PATH = (0, path_1.join)(process.cwd(), ".cliguard", "accepted-breaks.json");
 /** Contract path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
 function getContractDisplayPath() {
     return (0, path_1.relative)(process.cwd(), CONTRACT_PATH).split("\\").join("/");
 }
+/** Accepted-breaks path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
+function getAcceptedBreaksDisplayPath() {
+    return (0, path_1.relative)(process.cwd(), ACCEPTED_BREAKS_PATH).split("\\").join("/");
+}
 function contractExists() {
     return (0, fs_1.existsSync)(CONTRACT_PATH);
 }
@@ -39,3 +48,45 @@ function writeContract(contract) {
     (0, fs_1.mkdirSync)((0, path_1.dirname)(CONTRACT_PATH), { recursive: true });
     (0, fs_1.writeFileSync)(CONTRACT_PATH, JSON.stringify(contract, null, 2) + "\n", "utf-8");
 }
+/**
+ * Reads a Contract from an arbitrary path, not the committed
+ * `.cliguard/contract.json` - for `cliguard diff <a> <b>`, comparing two
+ * contract files directly (e.g. two tags' committed contracts pulled via
+ * `git show`) without running any real CLI. `displayPath` is what error
+ * messages name; defaults to `path` itself since a caller-supplied path is
+ * already about as displayable as it gets.
+ */
+function readContractFile(path, displayPath = path) {
+    if (!(0, fs_1.existsSync)(path)) {
+        throw new Error(`cliguard: no such file: "${displayPath}".`);
+    }
+    const raw = (0, fs_1.readFileSync)(path, "utf-8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`cliguard: "${displayPath}" is not valid JSON (${reason}).`);
+    }
+}
+/** Unlike readContract, a missing file is normal (most projects never accept a break) - returns [] rather than throwing. */
+function readAcceptedBreaks() {
+    if (!(0, fs_1.existsSync)(ACCEPTED_BREAKS_PATH))
+        return [];
+    const raw = (0, fs_1.readFileSync)(ACCEPTED_BREAKS_PATH, "utf-8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        // See readContract's identical-purpose catch for why naming the file
+        // and the fix matters here too.
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`cliguard: "${getAcceptedBreaksDisplayPath()}" is not valid JSON (${reason}). ` +
+            "If this file was hand-edited or came out of a bad merge, fix it or delete it " +
+            "and re-run `cliguard accept` for whatever was in it.");
+    }
+}
+function writeAcceptedBreaks(breaks) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(ACCEPTED_BREAKS_PATH), { recursive: true });
+    (0, fs_1.writeFileSync)(ACCEPTED_BREAKS_PATH, JSON.stringify(breaks, null, 2) + "\n", "utf-8");
+}

package/dist/core/types.d.ts

@@ -51,6 +51,21 @@ export interface Contract {
     readonly capturedAt: string;
     readonly root: CommandContract;
 }
+/**
+ * A specific BREAKING change the maintainer has deliberately accepted -
+ * written by `cliguard accept` and committed to `.cliguard/accepted-breaks.json`
+ * so the decision is auditable in the repo, not a silent CLI flag. `check`
+ * matches these against a diff's `DiffResult.path` and stops counting a
+ * match toward its exit code, while still showing it in the output.
+ */
+export interface AcceptedBreak {
+    /** Must equal the DiffResult.path of the breaking change being accepted, e.g. "root -> build -> option[--target]". */
+    readonly path: string;
+    /** Why this break is intentional - required, never blank, shown alongside the change. */
+    readonly reason: string;
+    /** ISO-8601 timestamp of when `cliguard accept` recorded this. */
+    readonly acceptedAt: string;
+}
 /** Severity of a single detected difference between two contracts. */
 export declare enum ChangeType {
     /** Removes or narrows something a caller may already depend on. */

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "cliguard",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Snapshot-tests your CLI's contract (commands, flags, defaults) so you never ship a breaking change by accident.",
   "keywords": [
     "cli",
     "contract-testing",
     "snapshot-testing",
     "commander",
+    "yargs",
     "ci"
   ],
   "author": "Bryandero98",
@@ -39,16 +40,21 @@
     "commander": "^12.1.0"
   },
   "peerDependencies": {
-    "cac": "^6.0.0"
+    "cac": "^6.0.0",
+    "yargs": "^17.0.0"
   },
   "peerDependenciesMeta": {
     "cac": {
       "optional": true
+    },
+    "yargs": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/jest": "^29.5.13",
     "@types/node": "^22.7.4",
+    "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.8.0",
     "@typescript-eslint/parser": "^8.8.0",
     "cac": "^6.7.14",
@@ -57,7 +63,8 @@
     "jest": "^29.7.0",
     "prettier": "^3.3.3",
     "ts-jest": "^29.2.5",
-    "typescript": "^5.6.2"
+    "typescript": "^5.6.2",
+    "yargs": "^17.7.2"
   },
   "engines": {
     "node": ">=18"