cliguard 0.3.0 → 0.3.1

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

@@ -21,6 +21,23 @@ export declare class CacAdapter implements CliAdapter {
     private loadCac;
     /** Handles `export default`, `module.exports = cli`, and named exports. */
     private findCac;
+    /**
+     * Structural check, not `instanceof CAC` - see CommanderAdapter's
+     * identical-purpose `looksLikeCommand` for why: the target project's
+     * own `cac` install is almost always a separate copy from any `cac`
+     * cliguard itself could resolve, even at the identical version, so
+     * `instanceof` fails by construction. This also removes the only
+     * reason this adapter ever needed `cac` installed in cliguard's own
+     * environment - `require("cac")` from cliguard's own (often
+     * `npx`-isolated) location previously gated every use of this adapter
+     * behind a package cliguard could rarely actually see, even when the
+     * target project had it. The target file's own `require("cac")` /
+     * `import("cac")`, resolved from *its* location by `loadModule`, is
+     * the only place `cac` needs to be installed now - and if it isn't,
+     * that failure surfaces below via the real load error, same as any
+     * other missing dependency.
+     */
+    private looksLikeCac;
     /**
      * CAC's root instance carries global options (`cli.option(...)`,
      * exposed via `globalCommand`) but no description of its own and no

package/dist/adapters/cac.adapter.js

@@ -2,23 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CacAdapter = void 0;
 const load_module_1 = require("./load-module");
-/**
- * `cac` is an optional peer dependency (see package.json) - a project
- * whose target CLI is built with Commander has no reason to install it.
- * Loaded lazily, only when this adapter actually runs, so importing this
- * file (which `bin.ts` does unconditionally, to register every adapter)
- * never requires `cac` to be present.
- */
-function loadCacClass() {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports -- deliberate lazy load of an optional peer dependency
-        const cacModule = require("cac");
-        return cacModule.CAC;
-    }
-    catch {
-        throw new Error("cliguard: the CAC adapter needs the `cac` package. Run `npm install --save-dev cac`.");
-    }
-}
 /**
  * Extracts a Contract from a target file that exports a `cac()` `CAC`
  * instance. Never parses --help output - every field comes straight from
@@ -48,10 +31,8 @@ class CacAdapter {
         };
     }
     async loadCac(entryPath) {
-        const CacClass = loadCacClass();
         const { viaImport, viaRequire } = await (0, load_module_1.loadModule)(entryPath);
-        const cli = this.findCac(viaImport.moduleExports, CacClass) ??
-            this.findCac(viaRequire.moduleExports, CacClass);
+        const cli = this.findCac(viaImport.moduleExports) ?? this.findCac(viaRequire.moduleExports);
         if (cli)
             return cli;
         // See CommanderAdapter's identical block for why both real errors -
@@ -63,22 +44,48 @@ class CacAdapter {
             `  require() failed: ${viaRequire.error ?? "module loaded, but exported no CAC instance"}`);
     }
     /** Handles `export default`, `module.exports = cli`, and named exports. */
-    findCac(moduleExports, CacClass) {
-        if (moduleExports instanceof CacClass) {
+    findCac(moduleExports) {
+        if (this.looksLikeCac(moduleExports)) {
             return moduleExports;
         }
         if (moduleExports && typeof moduleExports === "object") {
             const exportsObject = moduleExports;
-            if (exportsObject.default instanceof CacClass) {
+            if (this.looksLikeCac(exportsObject.default)) {
                 return exportsObject.default;
             }
             for (const value of Object.values(exportsObject)) {
-                if (value instanceof CacClass)
+                if (this.looksLikeCac(value))
                     return value;
             }
         }
         return undefined;
     }
+    /**
+     * Structural check, not `instanceof CAC` - see CommanderAdapter's
+     * identical-purpose `looksLikeCommand` for why: the target project's
+     * own `cac` install is almost always a separate copy from any `cac`
+     * cliguard itself could resolve, even at the identical version, so
+     * `instanceof` fails by construction. This also removes the only
+     * reason this adapter ever needed `cac` installed in cliguard's own
+     * environment - `require("cac")` from cliguard's own (often
+     * `npx`-isolated) location previously gated every use of this adapter
+     * behind a package cliguard could rarely actually see, even when the
+     * target project had it. The target file's own `require("cac")` /
+     * `import("cac")`, resolved from *its* location by `loadModule`, is
+     * the only place `cac` needs to be installed now - and if it isn't,
+     * that failure surfaces below via the real load error, same as any
+     * other missing dependency.
+     */
+    looksLikeCac(value) {
+        if (!value || typeof value !== "object")
+            return false;
+        const candidate = value;
+        return (Array.isArray(candidate.commands) &&
+            typeof candidate.globalCommand === "object" &&
+            candidate.globalCommand !== null &&
+            typeof candidate.command === "function" &&
+            typeof candidate.parse === "function");
+    }
     /**
      * CAC's root instance carries global options (`cli.option(...)`,
      * exposed via `globalCommand`) but no description of its own and no

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

@@ -13,6 +13,21 @@ export declare class CommanderAdapter implements CliAdapter {
     private loadCommand;
     /** Handles `export default`, `module.exports = program`, and named exports. */
     private findCommand;
+    /**
+     * Structural check, not `instanceof Command`. The target CLI almost
+     * always has its own separate install of `commander` - a different
+     * copy than the one this adapter imports, even at the identical
+     * version - because `npx cliguard` installs cliguard (and its pinned
+     * `commander`) into its own isolated location, unrelated to the target
+     * project's `node_modules`. Node gives every resolved copy of a
+     * package its own class identity ("dual package hazard"), so
+     * `instanceof` fails by construction in that - extremely common - case.
+     * Verified against a real external consumer project via `npx cliguard`
+     * with its own separate `commander` install, both at a different major
+     * version and at the identical version to this package's own
+     * `^12.1.0` - `instanceof` failed in both; this doesn't.
+     */
+    private looksLikeCommand;
     /** Recurses into `command.commands` so root and every subcommand at any depth go through the same mapping. */
     private mapCommand;
     private mapOption;

package/dist/adapters/commander.adapter.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommanderAdapter = void 0;
-const commander_1 = require("commander");
 const load_module_1 = require("./load-module");
 /**
  * Extracts a Contract from a target file that exports a Commander.js
@@ -45,21 +44,45 @@ class CommanderAdapter {
     }
     /** Handles `export default`, `module.exports = program`, and named exports. */
     findCommand(moduleExports) {
-        if (moduleExports instanceof commander_1.Command) {
+        if (this.looksLikeCommand(moduleExports)) {
             return moduleExports;
         }
         if (moduleExports && typeof moduleExports === "object") {
             const exportsObject = moduleExports;
-            if (exportsObject.default instanceof commander_1.Command) {
+            if (this.looksLikeCommand(exportsObject.default)) {
                 return exportsObject.default;
             }
             for (const value of Object.values(exportsObject)) {
-                if (value instanceof commander_1.Command)
+                if (this.looksLikeCommand(value))
                     return value;
             }
         }
         return undefined;
     }
+    /**
+     * Structural check, not `instanceof Command`. The target CLI almost
+     * always has its own separate install of `commander` - a different
+     * copy than the one this adapter imports, even at the identical
+     * version - because `npx cliguard` installs cliguard (and its pinned
+     * `commander`) into its own isolated location, unrelated to the target
+     * project's `node_modules`. Node gives every resolved copy of a
+     * package its own class identity ("dual package hazard"), so
+     * `instanceof` fails by construction in that - extremely common - case.
+     * Verified against a real external consumer project via `npx cliguard`
+     * with its own separate `commander` install, both at a different major
+     * version and at the identical version to this package's own
+     * `^12.1.0` - `instanceof` failed in both; this doesn't.
+     */
+    looksLikeCommand(value) {
+        if (!value || typeof value !== "object")
+            return false;
+        const candidate = value;
+        return (Array.isArray(candidate.options) &&
+            Array.isArray(candidate.commands) &&
+            typeof candidate.name === "function" &&
+            typeof candidate.action === "function" &&
+            typeof candidate.opts === "function");
+    }
     /** Recurses into `command.commands` so root and every subcommand at any depth go through the same mapping. */
     mapCommand(command) {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cliguard",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Snapshot-tests your CLI's contract (commands, flags, defaults) so you never ship a breaking change by accident.",
   "keywords": [
     "cli",