cliguard 0.6.0 → 0.7.1

package/README.md

@@ -97,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
 
@@ -125,6 +128,43 @@ npx cliguard check ./bin/cli.js --json
 
 `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:
@@ -135,6 +175,20 @@ npx cliguard accept ./bin/cli.js "root -> build -> option[--target]" --reason "r
 
 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:
@@ -145,6 +199,77 @@ 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.
+
+A `--strict`-only change is real BREAKING output, so `cliguard accept` needs the same flag to find it - `cliguard accept ./bin/cli.js "root -> copy" --strict --reason "..."` - without it, `accept` compares in default (non-strict) mode and won't see the change at all.
+
+## 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 |
@@ -156,8 +281,30 @@ It respects `.cliguard/accepted-breaks.json` the same way `check` does, and exit
 
 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
@@ -179,6 +326,7 @@ jobs:
           entry: ./bin/cli.js
           # adapter: yargs        # default: commander
           # comment-on-pr: false  # default: true
+          # strict: true          # default: false
 ```
 
 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:

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);