cliguard 0.2.0 → 0.3.1

package/README.md

@@ -71,6 +71,25 @@ npx cliguard update ./bin/cli.js
 
 `cliguard check` exits `1` if it finds even one `BREAKING` change, and `0` otherwise - safe to drop straight into any CI pipeline.
 
+Pass `--json` to `check` for a machine-readable result instead of the emoji lines above - useful for a bot that comments on the PR, a dashboard, or any other script consuming the result instead of a human reading it:
+
+```sh
+npx cliguard check ./bin/cli.js --json
+```
+
+```json
+{
+  "ok": false,
+  "changes": [
+    { "type": "BREAKING", "path": "root -> build -> option[--target]", "message": "Option \"--target\" was removed." }
+  ],
+  "summary": { "breaking": 1, "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.
+
 ## How changes get classified
 
 | | Removed | Added | Required flipped | Value type / default changed |
@@ -115,6 +134,13 @@ Extracting a contract runs the target entry file's own top-level code, the same
 
 The CLI and core diffing engine are, and will stay, free and open-source. Planned next: a hosted add-on for teams that want more than a CI exit code - a dashboard with the history of contract changes across releases, and Slack/webhook alerts the moment a breaking change lands. See [issue: Webhook reporter for SaaS integration](https://github.com/Bryandero98/cliguard/issues) for the first building block.
 
+## Support this project
+
+cliguard is free and will stay free. If it's saving you from a broken release, a small tip helps keep it going:
+
+- **Ko-fi:** [ko-fi.com/bryandero98](https://ko-fi.com/bryandero98)
+- **USDT (TRC20):** `TEG4Kk2qXYMQ4mHNd7dPhSPRyT14CGr2or` — double-check the network is set to **TRC20** before sending; a transfer on the wrong network can't be recovered.
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md).

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

@@ -42,28 +42,33 @@ program
     .option(...adapterOption)
     .action(async (entry, options) => {
     if ((0, storage_1.contractExists)()) {
-        console.warn(`El contrato ya existe. Usa "cliguard update" para sobrescribirlo.`);
+        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(`✅ Contrato de CLI inicializado con éxito en ${(0, storage_1.getContractDisplayPath)()}.`);
+    console.log(`✅ CLI contract initialized successfully at ${(0, storage_1.getContractDisplayPath)()}.`);
 });
 program
     .command("check")
     .description("Compare the current CLI surface against the committed contract")
     .argument("<entry>", "path to the target CLI's entry file")
     .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("✅ El contrato de la CLI está intacto.");
+        console.log("✅ CLI contract is intact.");
         process.exit(0);
     }
     printDiff(diff);
-    const hasBreaking = diff.some((entry) => entry.type === types_1.ChangeType.BREAKING);
     process.exit(hasBreaking ? 1 : 0);
 });
 program
@@ -74,8 +79,23 @@ program
     .action(async (entry, options) => {
     const contract = await resolveAdapter(options.adapter).extract(entry);
     (0, storage_1.writeContract)(contract);
-    console.log("🔄 Contrato de CLI actualizado con éxito.");
+    console.log("🔄 CLI contract updated successfully.");
 });
+function toJsonResult(diff) {
+    const summary = {
+        breaking: diff.filter((entry) => entry.type === types_1.ChangeType.BREAKING).length,
+        additive: diff.filter((entry) => entry.type === types_1.ChangeType.ADDITIVE).length,
+        patch: diff.filter((entry) => entry.type === types_1.ChangeType.PATCH).length,
+    };
+    const suggestedBump = summary.breaking > 0
+        ? "major"
+        : summary.additive > 0
+            ? "minor"
+            : summary.patch > 0
+                ? "patch"
+                : null;
+    return { ok: summary.breaking === 0, changes: diff, summary, suggestedBump };
+}
 function printDiff(diff) {
     for (const entry of diff) {
         console.log(`${emojiFor(entry.type)} [${entry.path}] ${entry.message}`);

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "cliguard",
-  "version": "0.2.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", "contract-testing", "snapshot-testing", "commander", "ci"],
+  "keywords": [
+    "cli",
+    "contract-testing",
+    "snapshot-testing",
+    "commander",
+    "ci"
+  ],
   "author": "Bryandero98",
   "license": "MIT",
   "homepage": "https://github.com/Bryandero98/cliguard",
@@ -13,10 +19,13 @@
   "bugs": {
     "url": "https://github.com/Bryandero98/cliguard/issues"
   },
+  "funding": "https://ko-fi.com/bryandero98",
   "bin": {
     "cliguard": "dist/bin.js"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "lint": "eslint src --ext .ts",