cliguard 0.5.0 → 0.7.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
@@ -92,6 +97,9 @@ Then:
 # Capture the current contract - commit .cliguard/contract.json
 npx cliguard init ./bin/cli.js
 
+# Same, plus scaffold .github/workflows/cliguard.yml so CI is wired up too
+npx cliguard init ./bin/cli.js --with-ci
+
 # In CI: fail the build on any breaking change
 npx cliguard check ./bin/cli.js
 
@@ -113,13 +121,153 @@ 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.
 
+### Marking something unstable right where it's declared
+
+`cliguard.config.js` is a separate file - useful for a blanket rule, but one more place to keep in sync as flags get renamed or removed. For a single command/option/argument that isn't stable yet, mark it in its own description instead:
+
+```js
+program.option("--fast", "skip checks [unstable]");
+```
+
+Any BREAKING change to a path whose own description contains `[unstable]` reports as PATCH instead - the marker travels with the code, so it can't silently point at a flag that no longer exists the way an external ignore list can.
+
+### Project-wide policy: ignoring or downgrading a whole class of change
+
+`accept`/`deprecate` handle one breaking change at a time. For a rule that applies to a whole class of changes - "alias changes are never breaking for us," "ignore everything under the `debug` subcommand" - write `cliguard.config.js` (or `.cjs`) instead:
+
+```js
+// cliguard.config.js
+module.exports = {
+  // Dropped from the report entirely - never shown, never fails the build.
+  ignore: ["root -> debug -> *"],
+
+  // Reclassified, not dropped - still visible, just not BREAKING anymore.
+  severityOverrides: [{ pattern: /alias/, severity: "PATCH" }],
+};
+```
+
+`pattern` in either field is a `RegExp` or a glob string (`*` matches any run of characters) matched against a change's path (the same string `check`'s own output shows, e.g. `"root -> build -> option[--target]"`). Applied before `accept`/`deprecate` ever run, so a change this config already downgraded has nothing left for either of those to act on. No `cliguard.config.js` present is a no-op - every project behaves exactly as it always has.
+
+### Comparing against a git ref instead of a local file
+
+`check` normally diffs against `.cliguard/contract.json` on disk, but a CI runner checking out a PR branch often doesn't have a freshly-updated one - `--against <ref>` reads the contract straight out of git instead, no local file required:
+
+```sh
+npx cliguard check ./bin/cli.js --against origin/main
+```
+
+Works with any ref `git show` understands - a branch, a tag, a commit sha. Combine with `--json` the same way as the file-based path.
+
+### 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.
+
+### Deprecating something ahead of its removal
+
+`accept` forgives a break that already happened. `deprecate` is the other half - announce a removal *before* it happens, so when it eventually does, it's a PATCH instead of a BREAKING change:
+
+```sh
+# The option still exists today - deprecate marks it for a future removal
+npx cliguard deprecate ./bin/cli.js "root -> build -> option[--target]" \
+  --remove-by 2.0.0 --reason "replaced by --targets"
+```
+
+This only works against a path that currently exists (it reads the same `path` shape `check`/`accept` use) - it writes `.cliguard/deprecations.json` (commit this file). From then on, whenever that command/option/argument actually gets removed, `check` reports it as PATCH, with the deprecation's reason and `--remove-by` folded into the message, instead of failing the build. Removing anything that was never deprecated first still fails exactly as before - deprecation has to be announced ahead of the break, not applied retroactively.
+
+`--remove-by` is informational only (a version or a date, whichever fits your release process) - cliguard never checks it against the clock or your `package.json` version, it's just carried through into the message so whoever's reading a changelog or a PR comment knows the plan.
+
+### 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.
+
+### Previewing a contract without committing it
+
+`cliguard preview <entry>` runs the same extraction `init` would, but prints the contract to stdout instead of writing `.cliguard/contract.json` - useful for sanity-checking what a new adapter or a lazily-built target CLI actually captures before you commit to it as the baseline:
+
+```sh
+npx cliguard preview ./bin/cli.js --adapter yargs
+```
+
+### Checking an adapter's real limitations, or sanity-checking one against your CLI
+
+Every adapter has a couple of real, framework-shape gaps (see "Supported frameworks" below) - `cliguard doctor` surfaces them directly instead of leaving them to a code comment only a maintainer would read:
+
+```sh
+npx cliguard doctor
+```
+
+Pass an entry file to also run a real extraction against it and get a quick structural summary (or the real failure, if extraction doesn't work) instead of a full contract dump:
+
+```sh
+npx cliguard doctor ./bin/cli.js --adapter yargs
+```
+
+### Catching a breaking change before it reaches CI
+
+`cliguard install-hook <entry>` installs a git hook (`pre-push` by default) that runs `cliguard check` automatically, so a breaking change is caught locally instead of waiting for CI to say so:
+
+```sh
+npx cliguard install-hook ./bin/cli.js
+# or, to gate every commit instead of every push:
+npx cliguard install-hook ./bin/cli.js --hook pre-commit
+```
+
+Never overwrites a hook that's already there - if you're already using [husky](https://typicode.github.io/husky/) or a similar tool, add the same `npx cliguard check ...` line to your existing hook instead.
+
+### `--strict`: catching changes the default rules can't see
+
+The default rules match commands/options/arguments by name, so a change that keeps every name the same is invisible to them - even when it can still break a caller. `--strict` adds rules for exactly that gap. Today, one: a pure reorder of a command's positional arguments.
+
+```js
+// before
+program.command("copy").argument("<src>").argument("<dest>");
+// after - same two arguments, swapped order
+program.command("copy").argument("<dest>").argument("<src>");
+```
+
+The default rules see no change at all here (`<src>` still exists, `<dest>` still exists). But `cli copy a.txt b.txt` now copies `b.txt` over `a.txt`, not the reverse - a real, silent break for anyone calling it positionally:
+
+```sh
+npx cliguard check ./bin/cli.js --strict
+```
+
+Off by default so it never changes behavior for an existing CI config - opt in per project.
+
+## Programmatic API
+
+Everything above is the CLI. The same extraction and diff logic is also available as a library, for a custom build script, monorepo tool, or bot that wants to embed a contract check without spawning `npx cliguard` as a subprocess:
+
+```js
+const { extractContract, compareContracts, ChangeType } = require("cliguard");
+
+const oldContract = await extractContract("./bin/cli.js"); // or read one off disk yourself
+const newContract = await extractContract("./bin/cli.js");
+const diff = compareContracts(oldContract, newContract, { strict: true });
+
+const breaking = diff.filter((change) => change.type === ChangeType.BREAKING);
+```
+
+`listAdapters()` returns every name `extractContract`'s second argument accepts. `DiffEngine`, every adapter class (`CommanderAdapter`/`CacAdapter`/`YargsAdapter`), and the `toJUnitXml`/`toGitLabCodeQuality`/`toRdjsonl` formatters are all exported too, for anything more custom than the two convenience functions cover.
+
 ## How changes get classified
 
 | | Removed | Added | Required flipped | Value type / default changed |
@@ -131,12 +279,38 @@ npx cliguard check ./bin/cli.js --json
 
 Full rules live in [`src/core/diff.engine.ts`](src/core/diff.engine.ts) - it's the one file worth reading if you want to know exactly why something was flagged.
 
+### Reports for non-GitHub CI
+
+The bundled GitHub Action is the recommended path on GitHub, but `check`/`diff` can also emit two other formats directly, no Action or bespoke reporter needed:
+
+```sh
+# JUnit XML - understood natively by Jenkins, CircleCI, Azure DevOps, and GitLab's own JUnit widget
+npx cliguard check ./bin/cli.js --format junit > cliguard-report.xml
+
+# GitLab Code Quality JSON - surfaced as inline annotations on a GitLab merge request
+npx cliguard check ./bin/cli.js --format gitlab-codequality > gl-code-quality-report.json
+```
+
+A third format, `--format rdjsonl`, emits [reviewdog](https://github.com/reviewdog/reviewdog)'s own Diagnostic Format instead of a report cliguard renders itself - hand it off to whichever platform reviewdog already has a reporter for:
+
+```sh
+npx cliguard check ./bin/cli.js --format rdjsonl | reviewdog -f=rdjsonl -reporter=github-pr-review
+```
+
+Same exit code either way - `1` on an unacknowledged BREAKING change, `0` otherwise - so any of the three drops straight into a CI job that already fails the build on a non-zero exit.
+
 ## CI integration
 
+`cliguard init --with-ci` scaffolds the workflow below for you - `git add .github/workflows/cliguard.yml` and you're done. Prefer to see it first, or wire it up by hand? Read on.
+
+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 +319,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/adapters/adapter.interface.d.ts

@@ -8,6 +8,16 @@ import type { Contract } from "../core/types";
 export interface CliAdapter {
     /** Adapter identifier stored in `Contract.adapter`, e.g. "commander". */
     readonly id: string;
+    /**
+     * Real, framework-shape limitations on what this adapter can populate in
+     * a Contract - not bugs, just things the target framework itself has no
+     * concept of (documented in more depth in each adapter's own doc
+     * comment). Empty for an adapter with no such gaps. Surfaced by
+     * `cliguard doctor` so a user hits this in a one-line summary instead of
+     * only discovering it by reading adapter source or being surprised by a
+     * `required` that's silently always `false`.
+     */
+    readonly limitations: readonly string[];
     /** Loads `entryPath` and extracts its full command surface as a Contract. */
     extract(entryPath: string): Promise<Contract>;
 }

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

@@ -17,6 +17,7 @@ import type { CliAdapter } from "./adapter.interface";
  */
 export declare class CacAdapter implements CliAdapter {
     readonly id = "cac";
+    readonly limitations: readonly string[];
     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. */

package/dist/adapters/cac.adapter.js

@@ -21,6 +21,11 @@ const load_module_1 = require("./load-module");
 class CacAdapter {
     constructor() {
         this.id = "cac";
+        this.limitations = [
+            'OptionContract.required is always false - CAC has no declarative "this option must be passed" concept.',
+            "CommandContract.subcommands is always [] - CAC's commands are a flat list, not a tree.",
+            'ArgumentContract.description is always "" - CAC\'s positional args carry no description field.',
+        ];
     }
     async extract(entryPath) {
         const cli = await this.loadCac(entryPath);

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

@@ -9,6 +9,8 @@ import type { CliAdapter } from "./adapter.interface";
  */
 export declare class CommanderAdapter implements CliAdapter {
     readonly id = "commander";
+    /** No known gaps - Commander's own object graph exposes everything a Contract needs directly. */
+    readonly limitations: readonly string[];
     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. */

package/dist/adapters/commander.adapter.js

@@ -13,6 +13,8 @@ const load_module_1 = require("./load-module");
 class CommanderAdapter {
     constructor() {
         this.id = "commander";
+        /** No known gaps - Commander's own object graph exposes everything a Contract needs directly. */
+        this.limitations = [];
     }
     async extract(entryPath) {
         const program = await this.loadCommand(entryPath);

package/dist/adapters/registry.d.ts

@@ -0,0 +1,3 @@
+import type { CliAdapter } from "./adapter.interface";
+export declare const adapters: Readonly<Record<string, CliAdapter>>;
+export declare function resolveAdapter(name: string): CliAdapter;

package/dist/adapters/registry.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adapters = void 0;
+exports.resolveAdapter = resolveAdapter;
+const cac_adapter_1 = require("./cac.adapter");
+const commander_adapter_1 = require("./commander.adapter");
+const yargs_adapter_1 = require("./yargs.adapter");
+// Constructing an adapter here is cheap (no eager require of its
+// framework - CacAdapter/YargsAdapter only load their framework lazily,
+// inside extract()), so every adapter is always registered regardless of
+// which one a given caller actually uses. Shared by bin.ts (the CLI) and
+// index.ts (the programmatic API) so both agree on exactly the same set
+// of adapters under exactly the same names, rather than two registries
+// that could silently drift apart.
+exports.adapters = {
+    commander: new commander_adapter_1.CommanderAdapter(),
+    cac: new cac_adapter_1.CacAdapter(),
+    yargs: new yargs_adapter_1.YargsAdapter(),
+};
+function resolveAdapter(name) {
+    const adapter = exports.adapters[name];
+    if (!adapter) {
+        throw new Error(`cliguard: unknown adapter "${name}". Available: ${Object.keys(exports.adapters).join(", ")}.`);
+    }
+    return adapter;
+}

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

@@ -19,6 +19,7 @@ import type { CliAdapter } from "./adapter.interface";
  */
 export declare class YargsAdapter implements CliAdapter {
     readonly id = "yargs";
+    readonly limitations: readonly string[];
     extract(entryPath: string): Promise<Contract>;
     private loadYargs;
     /**

package/dist/adapters/yargs.adapter.js

@@ -24,6 +24,9 @@ const YARGS_STRING_MARKER = "__yargsString__:";
 class YargsAdapter {
     constructor() {
         this.id = "yargs";
+        this.limitations = [
+            "Each command's options are read from a fresh, isolated yargs instance built by re-running that command's builder, not the shared instance the target CLI actually built - see this class's own doc comment for why.",
+        ];
     }
     async extract(entryPath) {
         const cli = await this.loadYargs(entryPath);