cliguard 0.3.1 → 0.4.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,16 @@ npx cliguard init ./bin/cli.js --adapter cac
 
 `cac` itself is an optional dependency of cliguard - only installed if you actually use `--adapter cac`.
 
+### 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.
+
+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

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/bin.js

@@ -45,9 +45,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 +60,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 +84,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,6 +1,6 @@
 {
   "name": "cliguard",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Snapshot-tests your CLI's contract (commands, flags, defaults) so you never ship a breaking change by accident.",
   "keywords": [
     "cli",