cliguard 0.5.0 → 0.6.0

package/README.md

@@ -1,5 +1,10 @@
 # cliguard
 
+[![npm version](https://img.shields.io/npm/v/cliguard.svg)](https://www.npmjs.com/package/cliguard)
+[![npm downloads](https://img.shields.io/npm/dm/cliguard.svg)](https://www.npmjs.com/package/cliguard)
+[![CI](https://github.com/Bryandero98/cliguard/actions/workflows/ci.yml/badge.svg)](https://github.com/Bryandero98/cliguard/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/cliguard.svg)](https://github.com/Bryandero98/cliguard/blob/main/LICENSE)
+
 Snapshot testing for CLI contracts.
 
 ## The problem
@@ -23,7 +28,7 @@ The first line fails your CI. The second one doesn't - `--dry-run` is new and op
 npm install --save-dev cliguard
 ```
 
-Your CLI's entry file should **export** its Commander `Command` instance instead of calling `.parse()` itself - the cleanest way to adopt cliguard, since it never risks running any of your CLI's real logic:
+Point cliguard straight at your existing CLI's entry file - most real CLIs work unmodified, since cliguard automatically captures the framework instance they build at load time even if they never export it (see "Entry files that build the CLI lazily" below). Exporting the instance is still the cleanest way to adopt cliguard where you can, since it never risks running any of your CLI's real logic:
 
 ```js
 // bin/cli.js
@@ -113,13 +118,33 @@ npx cliguard check ./bin/cli.js --json
   "changes": [
     { "type": "BREAKING", "path": "root -> build -> option[--target]", "message": "Option \"--target\" was removed." }
   ],
-  "summary": { "breaking": 1, "additive": 0, "patch": 0 },
+  "summary": { "breaking": 1, "acknowledgedBreaking": 0, "additive": 0, "patch": 0 },
   "suggestedBump": "major"
 }
 ```
 
 `suggestedBump` is the semver bump this diff implies (`"major"`, `"minor"`, `"patch"`, or `null` if nothing changed) - a direct read of the same BREAKING/ADDITIVE/PATCH classification the emoji output already uses, so a release script never has to re-derive it.
 
+### Accepting an intentional breaking change
+
+Sometimes a `BREAKING` change is exactly what you meant to ship - a flag genuinely needed to go away in a major version. Running `cliguard update` after a real, intentional break re-baselines the *entire* contract silently; it doesn't leave a record of what changed or why. `cliguard accept` does:
+
+```sh
+npx cliguard accept ./bin/cli.js "root -> build -> option[--target]" --reason "removed in v2.0, replaced by --targets"
+```
+
+This only works against a change `check` would currently report as `BREAKING` - it reads the exact `path` from your own `check` output (text or `--json`), so there's nothing to guess. It writes `.cliguard/accepted-breaks.json` (commit this file); from then on, `check` still shows that change - now as a 🟣 acknowledged line with the reason attached - but stops counting it toward the `BREAKING` total that fails your build. Any *other*, un-accepted breaking change still fails CI as normal. Once you're done, `cliguard update` still re-baselines the contract to match reality, same as always.
+
+### Comparing two contracts directly
+
+`cliguard diff <old.json> <new.json>` runs the same comparison as `check`, but reads both sides straight off disk instead of running any CLI - useful for comparing two tags' committed contracts (`git show v1.0.0:.cliguard/contract.json > old.json`), or reviewing a contract change in a PR without a working copy of the target CLI at all:
+
+```sh
+npx cliguard diff old-contract.json new-contract.json --json
+```
+
+It respects `.cliguard/accepted-breaks.json` the same way `check` does, and exits `1` on an un-acknowledged `BREAKING` change.
+
 ## How changes get classified
 
 | | Removed | Added | Required flipped | Value type / default changed |
@@ -133,10 +158,14 @@ Full rules live in [`src/core/diff.engine.ts`](src/core/diff.engine.ts) - it's t
 
 ## CI integration
 
+The bundled GitHub Action (`Bryandero98/cliguard@v1`) is the recommended way to run this in CI: on top of the same exit-code gate as `npx cliguard check`, it posts the diff as a PR comment - updated in place on every push, not a new one each time - so a reviewer sees exactly what changed without opening the CI log:
+
 ```yaml
 # .github/workflows/cliguard.yml
 name: CLI contract
 on: [pull_request]
+permissions:
+  pull-requests: write # needed for the PR comment
 jobs:
   check:
     runs-on: ubuntu-latest
@@ -145,7 +174,17 @@ jobs:
       - uses: actions/setup-node@v4
         with: { node-version: 22.x }
       - run: npm ci
-      - run: npx cliguard check ./bin/cli.js
+      - uses: Bryandero98/cliguard@v1
+        with:
+          entry: ./bin/cli.js
+          # adapter: yargs        # default: commander
+          # comment-on-pr: false  # default: true
+```
+
+Set `comment-on-pr: false` to keep the exit-code gate without the comment, or use the raw CLI directly for a non-GitHub CI provider:
+
+```yaml
+- run: npx cliguard check ./bin/cli.js
 ```
 
 ## Supported frameworks

package/dist/bin.js

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

package/dist/core/storage.d.ts

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

package/dist/core/storage.js

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

package/dist/core/types.d.ts

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

package/package.json

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