cliguard 0.3.1 → 0.5.0

package/README.md

@@ -23,7 +23,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 needs to **export** its Commander `Command` instance instead of calling `.parse()` itself:
+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:
 
 ```js
 // bin/cli.js
@@ -56,6 +56,36 @@ 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`/`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`.
+
+Either way, if the target's top-level code has its own real side effects when loaded - a `.parse()` call that matches a real command and runs it, a network request, spawning a process - running cliguard against it (directly or through a wrapper) triggers those too, exactly as `node ./bin/cli.js` would. cliguard neutralizes one specific danger this creates (a target calling `process.exit()` can't kill cliguard's own process or override its exit code), but doesn't sandbox anything else - see [SECURITY.md](./SECURITY.md).
+
 Then:
 
 ```sh
@@ -120,9 +150,9 @@ jobs:
 
 ## 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/cac.adapter.d.ts

@@ -19,6 +19,8 @@ export declare class CacAdapter implements CliAdapter {
     readonly id = "cac";
     extract(entryPath: string): Promise<Contract>;
     private loadCac;
+    /** Among every CAC instance captured during construction, the one that looks most like the real, fully-built root CLI. */
+    private pickBestCandidate;
     /** Handles `export default`, `module.exports = cli`, and named exports. */
     private findCac;
     /**

package/dist/adapters/cac.adapter.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CacAdapter = void 0;
+const construction_capture_1 = require("./construction-capture");
 const load_module_1 = require("./load-module");
 /**
  * Extracts a Contract from a target file that exports a `cac()` `CAC`
@@ -31,18 +32,39 @@ class CacAdapter {
         };
     }
     async loadCac(entryPath) {
+        // See CommanderAdapter.loadCommand's identical block: patched before
+        // the target loads, so a `new CAC()` or `cac()` call anywhere in its
+        // own top-level code gets captured even if the target never exports
+        // the result.
+        const captured = (0, construction_capture_1.captureConstructions)("cac", entryPath, "CAC", ["cac"]);
         const { viaImport, viaRequire } = await (0, load_module_1.loadModule)(entryPath);
-        const cli = this.findCac(viaImport.moduleExports) ?? this.findCac(viaRequire.moduleExports);
+        const cli = this.findCac(viaImport.moduleExports) ??
+            this.findCac(viaRequire.moduleExports) ??
+            this.pickBestCandidate(captured);
         if (cli)
             return cli;
         // See CommanderAdapter's identical block for why both real errors -
         // not a swallowed, generic guess - matter here.
         throw new Error(`cliguard: no CAC instance found in "${entryPath}". ` +
             "Export it as `export default cli`, `module.exports = cli`, " +
-            "or a named export (e.g. `export const cli = cac()`).\n" +
+            "or a named export (e.g. `export const cli = cac()`). If the file builds its " +
+            "CAC 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 CAC instance"}\n` +
             `  require() failed: ${viaRequire.error ?? "module loaded, but exported no CAC instance"}`);
     }
+    /** Among every CAC instance captured during construction, the one that looks most like the real, fully-built root CLI. */
+    pickBestCandidate(candidates) {
+        const valid = candidates.filter((candidate) => this.looksLikeCac(candidate));
+        if (valid.length === 0)
+            return undefined;
+        return valid.reduce((best, candidate) => candidate.commands.length + candidate.globalCommand.options.length >
+            best.commands.length + best.globalCommand.options.length
+            ? candidate
+            : best);
+    }
     /** Handles `export default`, `module.exports = cli`, and named exports. */
     findCac(moduleExports) {
         if (this.looksLikeCac(moduleExports)) {

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

@@ -11,6 +11,8 @@ export declare class CommanderAdapter implements CliAdapter {
     readonly id = "commander";
     extract(entryPath: string): Promise<Contract>;
     private loadCommand;
+    /** Among every Command captured during construction, the one that looks most like the real, fully-built root program - flags on this file's own top-level code sometimes constructing more than one incidentally. */
+    private pickBestCandidate;
     /** Handles `export default`, `module.exports = program`, and named exports. */
     private findCommand;
     /**

package/dist/adapters/commander.adapter.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommanderAdapter = void 0;
+const construction_capture_1 = require("./construction-capture");
 const load_module_1 = require("./load-module");
 /**
  * Extracts a Contract from a target file that exports a Commander.js
@@ -23,25 +24,49 @@ class CommanderAdapter {
         };
     }
     async loadCommand(entryPath) {
+        // Patched *before* the target loads, so a `new Command()` or
+        // `createCommand()` 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
+        // construction-capture.ts for why this is safe and what it can't
+        // reach.
+        const captured = (0, construction_capture_1.captureConstructions)("commander", entryPath, "Command", ["createCommand"]);
         const { viaImport, viaRequire } = await (0, load_module_1.loadModule)(entryPath);
-        const command = this.findCommand(viaImport.moduleExports) ?? this.findCommand(viaRequire.moduleExports);
+        const command = this.findCommand(viaImport.moduleExports) ??
+            this.findCommand(viaRequire.moduleExports) ??
+            this.pickBestCandidate(captured);
         if (command)
             return command;
-        // Neither attempt's exports contained a Command. One load attempt
-        // failing on its own is normal and expected (an ESM-only file can't
-        // require(), a CJS one may reject a bare import() on an older Node)
-        // - the interesting case is when the file simply never loaded at all
-        // (a syntax error, a missing dependency inside it), which the
-        // generic "no Command instance found" message below would otherwise
+        // Neither attempt's exports contained a Command, and nothing was
+        // captured during construction either. One load attempt failing on
+        // its own is normal and expected (an ESM-only file can't require(),
+        // a CJS one may reject a bare import() on an older Node) - the
+        // interesting case is when the file simply never loaded at all (a
+        // syntax error, a missing dependency inside it), which the generic
+        // "no Command instance found" message below would otherwise
         // misrepresent as "loaded fine, wrong export shape." Surface both
         // real reasons so the actual cause - a broken file vs. a genuinely
         // missing export - is never a guess.
         throw new Error(`cliguard: no Commander.js Command instance found in "${entryPath}". ` +
             "Export it as `export default program`, `module.exports = program`, " +
-            "or a named export (e.g. `export const program = new Command()`).\n" +
+            "or a named export (e.g. `export const program = new Command()`). If the file " +
+            "builds its Command 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 Command instance"}\n` +
             `  require() failed: ${viaRequire.error ?? "module loaded, but exported no Command instance"}`);
     }
+    /** Among every Command captured during construction, the one that looks most like the real, fully-built root program - flags on this file's own top-level code sometimes constructing more than one incidentally. */
+    pickBestCandidate(candidates) {
+        const valid = candidates.filter((candidate) => this.looksLikeCommand(candidate));
+        if (valid.length === 0)
+            return undefined;
+        return valid.reduce((best, candidate) => candidate.options.length + candidate.commands.length >
+            best.options.length + best.commands.length
+            ? candidate
+            : best);
+    }
     /** Handles `export default`, `module.exports = program`, and named exports. */
     findCommand(moduleExports) {
         if (this.looksLikeCommand(moduleExports)) {

package/dist/adapters/construction-capture.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Captures whatever instance a target file's own top-level code
+ * constructs from `packageName` - even when the target never exports
+ * that instance anywhere `module.exports` reaches. Many real CLIs build
+ * their Commander/CAC instance inside a function that only runs when
+ * something actually calls it (or just never bother exporting it, since
+ * they have no reason to) - `findCommand`/`findCac` alone only ever
+ * catch the minority that do.
+ *
+ * How: Node caches a CommonJS module by its resolved absolute path.
+ * Resolving `packageName` from the *target file's own directory* (not
+ * this package's - a different copy, per commander.adapter.ts's
+ * `looksLikeCommand` doc) and mutating the exact object at that cached
+ * path means the target's own later `require(packageName)` - resolving
+ * to the same path - returns this already-patched object. There's no
+ * way for the target to tell the difference: `new Command()` still
+ * returns a real `Command` (the patch is a construct-trapping `Proxy`
+ * around the real class, transparent to `instanceof` and to every
+ * static/instance member), it's just also recorded here as a side
+ * effect.
+ *
+ * Only reaches CommonJS construction - a direct `new ClassExport()`, or
+ * a named factory function that closes over the real class and returns
+ * `new ClassExport()` internally (commander's `createCommand`, cac's
+ * `cac()` - patching only the class export wouldn't catch these, since
+ * the factory's own closure still points at the *original* class, not
+ * whatever we later put in `moduleExports[classExportName]`). A target
+ * that's genuine ESM, reaching the framework via a static `import`
+ * rather than `require`, isn't reachable this way - Node's ESM module
+ * cache is separate and not patchable from CommonJS. That's a real,
+ * documented limit, not a bug: commander and cac both ship CJS-only, so
+ * even an ESM target almost always reaches them through interop's own
+ * require() underneath - the case this can't reach is the rare one.
+ */
+export declare function captureConstructions(packageName: string, entryPath: string, classExportName: string, factoryExportNames: readonly string[]): unknown[];

package/dist/adapters/construction-capture.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureConstructions = captureConstructions;
+const path_1 = require("path");
+/**
+ * Captures whatever instance a target file's own top-level code
+ * constructs from `packageName` - even when the target never exports
+ * that instance anywhere `module.exports` reaches. Many real CLIs build
+ * their Commander/CAC instance inside a function that only runs when
+ * something actually calls it (or just never bother exporting it, since
+ * they have no reason to) - `findCommand`/`findCac` alone only ever
+ * catch the minority that do.
+ *
+ * How: Node caches a CommonJS module by its resolved absolute path.
+ * Resolving `packageName` from the *target file's own directory* (not
+ * this package's - a different copy, per commander.adapter.ts's
+ * `looksLikeCommand` doc) and mutating the exact object at that cached
+ * path means the target's own later `require(packageName)` - resolving
+ * to the same path - returns this already-patched object. There's no
+ * way for the target to tell the difference: `new Command()` still
+ * returns a real `Command` (the patch is a construct-trapping `Proxy`
+ * around the real class, transparent to `instanceof` and to every
+ * static/instance member), it's just also recorded here as a side
+ * effect.
+ *
+ * Only reaches CommonJS construction - a direct `new ClassExport()`, or
+ * a named factory function that closes over the real class and returns
+ * `new ClassExport()` internally (commander's `createCommand`, cac's
+ * `cac()` - patching only the class export wouldn't catch these, since
+ * the factory's own closure still points at the *original* class, not
+ * whatever we later put in `moduleExports[classExportName]`). A target
+ * that's genuine ESM, reaching the framework via a static `import`
+ * rather than `require`, isn't reachable this way - Node's ESM module
+ * cache is separate and not patchable from CommonJS. That's a real,
+ * documented limit, not a bug: commander and cac both ship CJS-only, so
+ * even an ESM target almost always reaches them through interop's own
+ * require() underneath - the case this can't reach is the rare one.
+ */
+function captureConstructions(packageName, entryPath, classExportName, factoryExportNames) {
+    const captured = [];
+    let moduleExports;
+    try {
+        const targetDir = (0, path_1.dirname)((0, path_1.resolve)(process.cwd(), entryPath));
+        // eslint-disable-next-line @typescript-eslint/no-require-imports -- resolving/patching the target's own copy of a CJS package, not a static dependency of this file
+        const resolvedPath = require.resolve(packageName, { paths: [targetDir] });
+        // eslint-disable-next-line @typescript-eslint/no-require-imports -- see above
+        moduleExports = require(resolvedPath);
+    }
+    catch {
+        // The target doesn't have this package resolvable from its own
+        // location at all - nothing to patch, nothing to capture. The
+        // caller's existing "no instance found" error already covers this.
+        return captured;
+    }
+    const record = (instance) => {
+        if (instance && typeof instance === "object")
+            captured.push(instance);
+    };
+    const RealClass = moduleExports[classExportName];
+    if (typeof RealClass === "function") {
+        moduleExports[classExportName] = new Proxy(RealClass, {
+            construct(target, args, newTarget) {
+                const instance = Reflect.construct(target, args, newTarget);
+                record(instance);
+                return instance;
+            },
+        });
+    }
+    for (const factoryName of factoryExportNames) {
+        const realFactory = moduleExports[factoryName];
+        if (typeof realFactory === "function") {
+            moduleExports[factoryName] = (...args) => {
+                const instance = realFactory(...args);
+                record(instance);
+                return instance;
+            };
+        }
+    }
+    return captured;
+}

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];
@@ -45,9 +47,13 @@ program
         console.warn(`A contract already exists. Run "cliguard update" to overwrite it.`);
         process.exit(1);
     }
-    const contract = await resolveAdapter(options.adapter).extract(entry);
-    (0, storage_1.writeContract)(contract);
-    console.log(`✅ CLI contract initialized successfully at ${(0, storage_1.getContractDisplayPath)()}.`);
+    const exitCode = await withSuppressedExit(async () => {
+        const contract = await resolveAdapter(options.adapter).extract(entry);
+        (0, storage_1.writeContract)(contract);
+        console.log(`✅ CLI contract initialized successfully at ${(0, storage_1.getContractDisplayPath)()}.`);
+        return 0;
+    });
+    process.exit(exitCode);
 });
 program
     .command("check")
@@ -56,20 +62,23 @@ program
     .option(...adapterOption)
     .option("--json", "print a machine-readable JSON result instead of text", false)
     .action(async (entry, options) => {
-    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);
-    if (options.json) {
-        console.log(JSON.stringify(toJsonResult(diff), null, 2));
-        process.exit(hasBreaking ? 1 : 0);
-    }
-    if (diff.length === 0) {
-        console.log("✅ CLI contract is intact.");
-        process.exit(0);
-    }
-    printDiff(diff);
-    process.exit(hasBreaking ? 1 : 0);
+    const exitCode = await withSuppressedExit(async () => {
+        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);
+        if (options.json) {
+            console.log(JSON.stringify(toJsonResult(diff), null, 2));
+            return hasBreaking ? 1 : 0;
+        }
+        if (diff.length === 0) {
+            console.log("✅ CLI contract is intact.");
+            return 0;
+        }
+        printDiff(diff);
+        return hasBreaking ? 1 : 0;
+    });
+    process.exit(exitCode);
 });
 program
     .command("update")
@@ -77,10 +86,45 @@ program
     .argument("<entry>", "path to the target CLI's entry file")
     .option(...adapterOption)
     .action(async (entry, options) => {
-    const contract = await resolveAdapter(options.adapter).extract(entry);
-    (0, storage_1.writeContract)(contract);
-    console.log("🔄 CLI contract updated successfully.");
+    const exitCode = await withSuppressedExit(async () => {
+        const contract = await resolveAdapter(options.adapter).extract(entry);
+        (0, storage_1.writeContract)(contract);
+        console.log("🔄 CLI contract updated successfully.");
+        return 0;
+    });
+    process.exit(exitCode);
 });
+/**
+ * Runs `action` with `process.exit` neutralized, restoring the real one
+ * the instant `action` settles - then the caller calls the *real*
+ * `process.exit` immediately with cliguard's own, correct code.
+ *
+ * Why this exists: the fallback in commander.adapter.ts /
+ * cac.adapter.ts's construction-capture lets a target CLI's own
+ * top-level code run further than a plain export lookup ever did - real
+ * targets often call `.parse()`/`.run()` for real as a side effect of
+ * being loaded, sometimes asynchronously (an `await` inside their own
+ * main function, a dangling `.catch()` continuation still in flight).
+ * Node's `process.exit()` is immediate and unconditional - if that
+ * dangling target code calls it (even with an unrelated code, even
+ * *after* cliguard already computed the right answer), it kills this
+ * process with the target's exit code, not cliguard's. Restoring the
+ * real `process.exit` and calling it ourselves right away, synchronously,
+ * the moment `action` resolves closes the race: Node's exit is immediate
+ * and single-threaded, so nothing queued after that point - including
+ * whatever the target's own code was about to do - ever runs.
+ */
+async function withSuppressedExit(action) {
+    const realExit = process.exit.bind(process);
+    // eslint-disable-next-line @typescript-eslint/no-empty-function -- deliberately a no-op: see doc comment above
+    process.exit = (() => undefined);
+    try {
+        return await action();
+    }
+    finally {
+        process.exit = realExit;
+    }
+}
 function toJsonResult(diff) {
     const summary = {
         breaking: diff.filter((entry) => entry.type === types_1.ChangeType.BREAKING).length,

package/dist/core/diff.engine.d.ts

@@ -17,6 +17,8 @@ export declare class DiffEngine {
     compare(oldContract: Contract, newContract: Contract): DiffResult[];
     private compareCommands;
     private compareSubcommands;
+    /** CAC's default command (declared with no leading name, e.g. `cli.command("[...files]", ...)`) has name === "" - a blank path segment reads as a typo, not a real command. */
+    private commandLabel;
     private compareOptions;
     private compareOption;
     private compareArguments;

package/dist/core/diff.engine.js

@@ -35,10 +35,10 @@ class DiffEngine {
             results.push({
                 type: types_1.ChangeType.PATCH,
                 path,
-                message: `Description changed for command "${oldCmd.name}".`,
+                message: `Description changed for command "${this.commandLabel(oldCmd.name)}".`,
             });
         }
-        results.push(...this.compareAliases(oldCmd.aliases, newCmd.aliases, path, `command "${oldCmd.name}"`));
+        results.push(...this.compareAliases(oldCmd.aliases, newCmd.aliases, path, `command "${this.commandLabel(oldCmd.name)}"`));
         results.push(...this.compareOptions(oldCmd.options, newCmd.options, path));
         results.push(...this.compareArguments(oldCmd.arguments, newCmd.arguments, path));
         results.push(...this.compareSubcommands(oldCmd.subcommands, newCmd.subcommands, path));
@@ -49,13 +49,13 @@ class DiffEngine {
         const oldByName = this.indexByName(oldSubs);
         const newByName = this.indexByName(newSubs);
         for (const [name, oldSub] of oldByName) {
-            const childPath = `${path} -> ${name}`;
+            const childPath = `${path} -> ${this.commandLabel(name)}`;
             const newSub = newByName.get(name);
             if (!newSub) {
                 results.push({
                     type: types_1.ChangeType.BREAKING,
                     path: childPath,
-                    message: `Command "${name}" was removed.`,
+                    message: `Command "${this.commandLabel(name)}" was removed.`,
                 });
                 continue;
             }
@@ -66,12 +66,16 @@ class DiffEngine {
                 continue;
             results.push({
                 type: types_1.ChangeType.ADDITIVE,
-                path: `${path} -> ${name}`,
-                message: `Command "${name}" was added.`,
+                path: `${path} -> ${this.commandLabel(name)}`,
+                message: `Command "${this.commandLabel(name)}" was added.`,
             });
         }
         return results;
     }
+    /** CAC's default command (declared with no leading name, e.g. `cli.command("[...files]", ...)`) has name === "" - a blank path segment reads as a typo, not a real command. */
+    commandLabel(name) {
+        return name === "" ? "<default>" : name;
+    }
     compareOptions(oldOptions, newOptions, path) {
         const results = [];
         const oldByName = this.indexByName(oldOptions);

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "cliguard",
-  "version": "0.3.1",
+  "version": "0.5.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"