cliguard 0.7.1 → 0.7.2

package/README.md

@@ -81,6 +81,28 @@ npx cliguard init ./bin/cli.js --adapter yargs
 
 Like `cac`, `yargs` itself is an optional dependency of cliguard - only installed if you actually use `--adapter yargs`.
 
+Built with Python's [Click](https://click.palletsprojects.com/) instead of a JS framework? Point cliguard straight at the `.py` file that defines your root command or group - no export needed, since Click's own `@click.command()`/`@click.group()` decorators already bind it as a module-level name:
+
+```py
+# cli.py
+import click
+
+@click.group()
+def cli():
+    pass
+
+@cli.command()
+@click.option("--target", "-t", required=True, help="build target")
+def build(target):
+    ...
+```
+
+```sh
+npx cliguard init ./cli.py --adapter click
+```
+
+Unlike the JS adapters, `click` needs a real Python interpreter: cliguard shells out to `python3` (falling back to `python`) with `click` installed in that same environment - there's no in-process way to introspect a Python object from Node. `pip install click` in whichever Python cliguard's shell can already reach is all that's required; nothing npm-installable covers this one.
+
 ### Entry files that build the CLI lazily
 
 Not every real CLI exports its instance - plenty build it inside a function that only runs when something actually calls it, or just never had a reason to export it. Pointing cliguard straight at a file like that would fail with "no instance found" under the rule above alone.
@@ -155,6 +177,35 @@ module.exports = {
 
 `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.
 
+### Monorepos with multiple CLI entry points
+
+A monorepo shipping more than one CLI - a `packages/*` layout where two or three packages each have their own `bin` - doesn't need N separate `.cliguard/` directories and N hand-written CI steps. Declare every entry point once, as `targets` in `cliguard.config.js`:
+
+```js
+// cliguard.config.js
+module.exports = {
+  targets: [
+    { name: "cli-a", entry: "packages/cli-a/bin/index.js", adapter: "commander" },
+    { name: "cli-b", entry: "packages/cli-b/bin/index.js", adapter: "yargs" },
+  ],
+};
+```
+
+`init`/`check`/`update`/`accept` all pick it up - omit the entry argument to run against every configured target, or pass a target's `name` in its place to run just that one:
+
+```sh
+npx cliguard init            # initializes every target: .cliguard/cli-a/contract.json, .cliguard/cli-b/contract.json, ...
+npx cliguard check           # checks every target - exits 1 if ANY of them has an unacknowledged breaking change
+npx cliguard check cli-a     # just one, by name
+npx cliguard accept cli-a "root -> build -> option[--target]" --reason "..."  # accept is always single-target - see below
+```
+
+Each target's contract, accepted breaks, and deprecations live under their own `.cliguard/<name>/` directory, so two targets never collide on disk. Running more than one target at once prints a `== <name> ==` banner between them; checking a single named target (or the classic single-CLI flow below) prints exactly as it always has, with no banner at all.
+
+**This is additive, not a replacement for the single-CLI flow that's still most of cliguard's actual usage.** An explicit file-path entry (`npx cliguard check ./bin/cli.js`) keeps working exactly as it does today, `cliguard.config.js` or not - `targets` is only ever consulted when the entry argument is omitted, or when it exactly matches a configured target's `name`.
+
+`accept` is the one exception to "omit entry to run every target": accepting a specific breaking change is inherently a one-target operation (a `changePath` on one CLI's contract has nothing to do with another CLI's), so its entry argument stays required - a literal path or a target's `name`, same as `check`.
+
 ### 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:
@@ -207,6 +258,20 @@ It respects `.cliguard/accepted-breaks.json` the same way `check` does, and exit
 npx cliguard preview ./bin/cli.js --adapter yargs
 ```
 
+### Generating CLI reference docs that can't drift
+
+`cliguard docs <entry>` walks the same extracted contract `check` already fails CI over, and renders it as Markdown - one section per command, a table of its arguments, a table of its options (flag, default, description, whether it's required):
+
+```sh
+npx cliguard docs ./bin/cli.js > CLI.md
+```
+
+Commit `CLI.md` and add `--check` to catch it going stale the same way `check` catches the contract going stale - it exits `1` the moment the generated docs and the committed file disagree, instead of drifting silently the way hand-written or copy-pasted-from-`--help` docs do:
+
+```sh
+npx cliguard docs ./bin/cli.js --check CLI.md
+```
+
 ### 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:

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

@@ -0,0 +1,34 @@
+import type { Contract } from "../core/types";
+import type { CliAdapter } from "./adapter.interface";
+/**
+ * Extracts a Contract from a target Python file that defines a Click
+ * command or group at module level. Unlike every other adapter, this one
+ * can't load the target in-process (a Python object graph is unreachable
+ * from Node) - instead it pipes a small extractor script into `python -`
+ * as a subprocess, and that script does the actual introspection using
+ * Click's own object model (`.params`, `.commands`, `click.Option`/
+ * `click.Argument`), then prints one JSON object on stdout. Never parses
+ * `--help` output.
+ *
+ * The target file is imported (not executed as `__main__`), so its own
+ * `if __name__ == "__main__": cli()` guard never fires - only the
+ * module-level `@click.command()`/`@click.group()` decorations run, which
+ * is all that's needed to build the command tree. When more than one
+ * module-level Click command exists (e.g. both the root group and its own
+ * decorated subcommand functions are separately addressable module
+ * globals), the one whose own subtree (itself plus every nested
+ * subcommand) is largest wins - a real subcommand's subtree is always a
+ * strict subset of its parent group's, so the true root always scores
+ * highest.
+ */
+export declare class ClickAdapter implements CliAdapter {
+    readonly id = "click";
+    readonly limitations: readonly string[];
+    extract(entryPath: string): Promise<Contract>;
+    private runExtractor;
+    private mapCommand;
+    private mapOption;
+    private mapArgument;
+    /** "--dry-run" -> "dry_run", "-v" -> "v" - Click's own name-inference rule, used to find which raw flag is the option's primary/canonical form. */
+    private normalizeFlag;
+}

package/dist/adapters/click.adapter.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClickAdapter = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * Piped into `python -` (via stdin) rather than shipped as a separate .py
+ * file - keeps the extractor inside cliguard's own compiled dist/ output
+ * with zero extra packaging step, and guarantees the exact script that ran
+ * in this session's live testing is the one that ships.
+ *
+ * Verified live against a real Click CLI (group + nested group + required/
+ * repeatable/choice options + required/variadic arguments) before being
+ * embedded here - see the class doc comment below for what each design
+ * choice below is actually working around.
+ */
+const EXTRACT_SCRIPT = `
+import sys, os, json, importlib.util
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("cliguard: internal error: no entry path given to extractor", file=sys.stderr)
+        sys.exit(1)
+    entry_path = sys.argv[1]
+
+    try:
+        import click
+    except ImportError:
+        print(
+            "cliguard: the 'click' package is not installed in this Python environment. "
+            "Install it in the same environment cliguard's Python is running from "
+            "(e.g. \`pip install click\`).",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    module_name = "__cliguard_target__"
+    spec = importlib.util.spec_from_file_location(module_name, entry_path)
+    if spec is None or spec.loader is None:
+        print(f'cliguard: could not load "{entry_path}" as a Python module.', file=sys.stderr)
+        sys.exit(1)
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    sys.path.insert(0, os.path.dirname(os.path.abspath(entry_path)))
+    try:
+        spec.loader.exec_module(module)
+    except Exception:
+        import traceback
+
+        print(
+            f'cliguard: error importing "{entry_path}":\\n' + traceback.format_exc(),
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    candidates = [
+        (name, value) for name, value in vars(module).items() if isinstance(value, click.Command)
+    ]
+
+    if not candidates:
+        print(
+            f'cliguard: no Click command found in "{entry_path}". '
+            "Define one at module level with @click.command() or @click.group() "
+            "(e.g. \`@click.group()\\\\ndef cli(): ...\`).",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    def subtree_size(cmd):
+        size = 1
+        if isinstance(cmd, click.Group):
+            for sub in cmd.commands.values():
+                size += subtree_size(sub)
+        return size
+
+    preferred_names = {"cli", "main", "app", "entry_point", "cmd"}
+
+    def score(item):
+        name, cmd = item
+        return (subtree_size(cmd), 1 if name in preferred_names else 0)
+
+    best_name, best_cmd = max(candidates, key=score)
+
+    def safe_default(value):
+        try:
+            json.dumps(value)
+            return value
+        except TypeError:
+            return None
+
+    def dump_param(p):
+        if isinstance(p, click.Argument):
+            return {
+                "type": "Argument",
+                "name": p.name,
+                "required": bool(p.required),
+                "nargs": p.nargs,
+            }
+        return {
+            "type": "Option",
+            "name": p.name,
+            "opts": list(p.opts),
+            "secondary_opts": list(p.secondary_opts),
+            "required": bool(p.required),
+            "is_flag": bool(p.is_flag),
+            "multiple": bool(p.multiple),
+            "default": safe_default(p.default),
+            "help": p.help,
+        }
+
+    def dump_command(cmd, name):
+        result = {
+            "name": name,
+            "help": cmd.help,
+            "short_help": cmd.get_short_help_str(),
+            "params": [dump_param(p) for p in cmd.params],
+        }
+        if isinstance(cmd, click.Group):
+            result["commands"] = {
+                sub_name: dump_command(sub_cmd, sub_name) for sub_name, sub_cmd in cmd.commands.items()
+            }
+        return result
+
+    print(json.dumps(dump_command(best_cmd, best_cmd.name or best_name)))
+
+
+if __name__ == "__main__":
+    main()
+`;
+/**
+ * Extracts a Contract from a target Python file that defines a Click
+ * command or group at module level. Unlike every other adapter, this one
+ * can't load the target in-process (a Python object graph is unreachable
+ * from Node) - instead it pipes a small extractor script into `python -`
+ * as a subprocess, and that script does the actual introspection using
+ * Click's own object model (`.params`, `.commands`, `click.Option`/
+ * `click.Argument`), then prints one JSON object on stdout. Never parses
+ * `--help` output.
+ *
+ * The target file is imported (not executed as `__main__`), so its own
+ * `if __name__ == "__main__": cli()` guard never fires - only the
+ * module-level `@click.command()`/`@click.group()` decorations run, which
+ * is all that's needed to build the command tree. When more than one
+ * module-level Click command exists (e.g. both the root group and its own
+ * decorated subcommand functions are separately addressable module
+ * globals), the one whose own subtree (itself plus every nested
+ * subcommand) is largest wins - a real subcommand's subtree is always a
+ * strict subset of its parent group's, so the true root always scores
+ * highest.
+ */
+class ClickAdapter {
+    constructor() {
+        this.id = "click";
+        this.limitations = [
+            "CommandContract.aliases is always [] - Click's base Group/Command has no built-in alias concept (unlike Commander's .alias()).",
+            'ArgumentContract.description is always "" - Click\'s click.Argument carries no help/description field, only click.Option does.',
+            'OptionContract.valueType collapses every non-flag Click option (string, int, float, choice, path, ...) to "string" - Contract only distinguishes boolean vs. everything else, matching how CacAdapter/YargsAdapter already collapse their own richer type systems.',
+            "A --flag/--no-flag paired boolean toggle surfaces as one OptionContract, same as a plain is_flag option - the negative form is only visible informationally inside `flags`, not as a separate field.",
+            "Requires a `python3` or `python` on PATH with `click` installed in that same environment - unlike the JS adapters, which only need the target's own node_modules.",
+        ];
+    }
+    async extract(entryPath) {
+        const absolutePath = (0, path_1.resolve)(process.cwd(), entryPath);
+        if (!(0, fs_1.existsSync)(absolutePath)) {
+            throw new Error(`cliguard: no such file: "${absolutePath}".`);
+        }
+        const root = this.mapCommand(await this.runExtractor(absolutePath));
+        return {
+            contractVersion: 1,
+            adapter: this.id,
+            capturedAt: new Date().toISOString(),
+            root,
+        };
+    }
+    async runExtractor(absolutePath) {
+        for (const pythonExe of ["python3", "python"]) {
+            const result = (0, child_process_1.spawnSync)(pythonExe, ["-", absolutePath], {
+                input: EXTRACT_SCRIPT,
+                encoding: "utf8",
+            });
+            if (result.error && result.error.code === "ENOENT") {
+                continue;
+            }
+            if (result.status !== 0) {
+                throw new Error(`cliguard: failed to extract a Click contract from "${absolutePath}":\n` +
+                    (result.stderr.trim() || `${pythonExe} exited with code ${result.status}`));
+            }
+            try {
+                return JSON.parse(result.stdout);
+            }
+            catch {
+                throw new Error(`cliguard: internal error - the Click extractor's output wasn't valid JSON:\n${result.stdout}`);
+            }
+        }
+        throw new Error("cliguard: no Python interpreter found (tried `python3` and `python`). " +
+            "The click adapter needs Python 3 with `click` installed on PATH to introspect a Click CLI.");
+    }
+    mapCommand(json) {
+        return {
+            name: json.name,
+            // See class limitations: Click has no per-command alias concept.
+            description: json.help ?? json.short_help ?? "",
+            aliases: [],
+            options: json.params
+                .filter((param) => param.type === "Option")
+                .map((param) => this.mapOption(param)),
+            arguments: json.params
+                .filter((param) => param.type === "Argument")
+                .map((param) => this.mapArgument(param)),
+            subcommands: json.commands
+                ? Object.values(json.commands).map((sub) => this.mapCommand(sub))
+                : [],
+        };
+    }
+    mapOption(param) {
+        const opts = [...(param.opts ?? []), ...(param.secondary_opts ?? [])];
+        const primary = opts.find((flag) => this.normalizeFlag(flag) === param.name) ??
+            opts.find((flag) => flag.startsWith("--")) ??
+            opts[0];
+        return {
+            flags: opts.join(", "),
+            name: param.name,
+            aliases: opts.filter((flag) => flag !== primary),
+            description: param.help ?? "",
+            required: param.required,
+            valueType: param.is_flag ? "boolean" : "string",
+            variadic: param.multiple ?? false,
+            defaultValue: param.default ?? null,
+        };
+    }
+    mapArgument(param) {
+        return {
+            name: param.name,
+            required: param.required,
+            variadic: (param.nargs ?? 1) === -1,
+            // See class limitations: click.Argument has no help/description field.
+            description: "",
+        };
+    }
+    /** "--dry-run" -> "dry_run", "-v" -> "v" - Click's own name-inference rule, used to find which raw flag is the option's primary/canonical form. */
+    normalizeFlag(flag) {
+        return flag.replace(/^-+/, "").replace(/-/g, "_");
+    }
+}
+exports.ClickAdapter = ClickAdapter;

package/dist/adapters/registry.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.adapters = void 0;
 exports.resolveAdapter = resolveAdapter;
 const cac_adapter_1 = require("./cac.adapter");
+const click_adapter_1 = require("./click.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
@@ -16,6 +17,7 @@ exports.adapters = {
     commander: new commander_adapter_1.CommanderAdapter(),
     cac: new cac_adapter_1.CacAdapter(),
     yargs: new yargs_adapter_1.YargsAdapter(),
+    click: new click_adapter_1.ClickAdapter(),
 };
 function resolveAdapter(name) {
     const adapter = exports.adapters[name];

package/dist/bin.js

@@ -6,6 +6,7 @@ const path_1 = require("path");
 const registry_1 = require("./adapters/registry");
 const config_1 = require("./core/config");
 const diff_engine_1 = require("./core/diff.engine");
+const docs_1 = require("./core/docs");
 const report_formats_1 = require("./core/report-formats");
 const storage_1 = require("./core/storage");
 const types_1 = require("./core/types");
@@ -22,6 +23,38 @@ const adapterOption = [
     "CLI framework adapter to use",
     "commander",
 ];
+const ENTRY_ARGUMENT_DESCRIPTION = "path to the target CLI's entry file, or a configured cliguard.config.js target's name - " +
+    "omit to run every configured target (see cliguard.config.js's targets)";
+/** Shared by init/check/update/accept: resolves what to run against, or prints resolveTargets's own error and exits 1 - identical failure shape across all four. */
+function resolveTargetsOrExit(entry, cliAdapter) {
+    try {
+        return (0, config_1.resolveTargets)(entry, (0, config_1.loadConfig)(), cliAdapter);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+/**
+ * Runs `action` once per resolved target, printing a `== <name> ==` banner
+ * between them only when there's more than one - a single classic target
+ * (the common case: no cliguard.config.js, or one that matched no target
+ * name) prints exactly as it always has, with no banner at all. The
+ * overall exit code is 1 if ANY target's own action returned non-zero,
+ * matching `check`'s existing "any BREAKING change fails the build"
+ * semantics extended across targets instead of options/arguments.
+ */
+async function runAcrossTargets(targets, action) {
+    let exitCode = 0;
+    for (const target of targets) {
+        if (targets.length > 1)
+            console.log(`\n== ${target.namespace} ==`);
+        const code = await action(target);
+        if (code !== 0)
+            exitCode = 1;
+    }
+    return exitCode;
+}
 const REPORT_FORMATS = ["text", "json", "junit", "gitlab-codequality", "rdjsonl"];
 /** `--json` is a shorthand kept for backward compatibility - equivalent to `--format json` when no explicit `--format` is given. Returns null for an unrecognized `--format` value, distinct from every valid one including "text". */
 function resolveFormat(explicit, jsonFlag) {
@@ -46,55 +79,66 @@ function formatReport(diff, acceptedPaths, format, contractPath) {
 program
     .command("init")
     .description("Capture the current CLI surface as the committed contract")
-    .argument("<entry>", "path to the target CLI's entry file")
+    .argument("[entry]", ENTRY_ARGUMENT_DESCRIPTION)
     .option(...adapterOption)
     .option("--with-ci", "also scaffold a GitHub Actions workflow that runs cliguard on every pull request", false)
     .action(async (entry, options) => {
-    if ((0, storage_1.contractExists)()) {
-        console.warn(`A contract already exists. Run "cliguard update" to overwrite it.`);
+    const targets = resolveTargetsOrExit(entry, options.adapter);
+    if (options.withCi && targets.length > 1) {
+        console.error("cliguard: --with-ci supports a single target at a time - run " +
+            "`cliguard init <name> --with-ci` for one target, or write the workflow by hand " +
+            "for a multi-target project.");
         process.exit(1);
     }
-    const exitCode = await withSuppressedExit(async () => {
-        const contract = await (0, registry_1.resolveAdapter)(options.adapter).extract(entry);
-        (0, storage_1.writeContract)(contract);
-        console.log(`✅ CLI contract initialized successfully at ${(0, storage_1.getContractDisplayPath)()}.`);
+    const exitCode = await runAcrossTargets(targets, (target) => withSuppressedExit(async () => {
+        if ((0, storage_1.contractExists)(target.namespace)) {
+            const suffix = target.namespace ? ` ${target.namespace}` : "";
+            console.warn(`A contract already exists. Run "cliguard update${suffix}" to overwrite it.`);
+            return 1;
+        }
+        const contract = await (0, registry_1.resolveAdapter)(target.adapter).extract(target.entry);
+        (0, storage_1.writeContract)(contract, target.namespace);
+        console.log(`✅ CLI contract initialized successfully at ${(0, storage_1.getContractDisplayPath)(target.namespace)}.`);
         if (options.withCi) {
             if ((0, storage_1.ciWorkflowExists)()) {
                 console.log(`ℹ️  ${(0, storage_1.getCiWorkflowDisplayPath)()} already exists - left it untouched.`);
             }
             else {
-                const entryPath = (0, path_1.relative)(process.cwd(), (0, path_1.resolve)(entry)).split("\\").join("/");
-                (0, storage_1.writeCiWorkflow)(buildCiWorkflowYaml(entryPath, options.adapter));
+                const entryPath = (0, path_1.relative)(process.cwd(), (0, path_1.resolve)(target.entry)).split("\\").join("/");
+                (0, storage_1.writeCiWorkflow)(buildCiWorkflowYaml(entryPath, target.adapter));
                 console.log(`✅ GitHub Actions workflow scaffolded at ${(0, storage_1.getCiWorkflowDisplayPath)()}.`);
             }
         }
         return 0;
-    });
+    }));
     process.exit(exitCode);
 });
 program
     .command("check")
     .description("Compare the current CLI surface against the committed contract")
-    .argument("<entry>", "path to the target CLI's entry file")
+    .argument("[entry]", ENTRY_ARGUMENT_DESCRIPTION)
     .option(...adapterOption)
     .option("--json", "print a machine-readable JSON result instead of text (shorthand for --format json)", false)
     .option("--format <format>", `output format: ${REPORT_FORMATS.join(", ")}`)
     .option("--against <ref>", "compare against a git ref's committed contract (e.g. origin/main, a tag, a commit sha) instead of the .cliguard/contract.json on disk")
     .option("--strict", "enable extra rules for currently-silent risky changes (e.g. a positional argument reorder)", false)
     .action(async (entry, options) => {
-    const exitCode = await withSuppressedExit(async () => {
+    const targets = resolveTargetsOrExit(entry, options.adapter);
+    const exitCode = await runAcrossTargets(targets, (target) => withSuppressedExit(async () => {
         const format = resolveFormat(options.format, options.json);
         if (!format) {
             console.error(`cliguard: unknown --format "${options.format}". Use ${REPORT_FORMATS.join(", ")}.`);
             return 1;
         }
-        const oldContract = options.against ? (0, storage_1.readContractAtRef)(options.against) : (0, storage_1.readContract)();
-        const newContract = await (0, registry_1.resolveAdapter)(options.adapter).extract(entry);
-        const diff = applyDeprecations(diffEngine.applyUnstableMarkers((0, config_1.applyConfig)(diffEngine.compare(oldContract, newContract, { strict: options.strict }), (0, config_1.loadConfig)()), oldContract, newContract), indexDeprecations((0, storage_1.readDeprecations)()));
-        const acceptedPaths = indexAcceptedBreaks((0, storage_1.readAcceptedBreaks)());
+        const oldContract = options.against
+            ? (0, storage_1.readContractAtRef)(options.against, target.namespace)
+            : (0, storage_1.readContract)(target.namespace);
+        const newContract = await (0, registry_1.resolveAdapter)(target.adapter).extract(target.entry);
+        const diff = applyDeprecations(diffEngine.applyUnstableMarkers((0, config_1.applyConfig)(diffEngine.compare(oldContract, newContract, { strict: options.strict }), (0, config_1.loadConfig)()), oldContract, newContract), indexDeprecations((0, storage_1.readDeprecations)(target.namespace)));
+        const acceptedPaths = indexAcceptedBreaks((0, storage_1.readAcceptedBreaks)(target.namespace));
         const hasBreaking = diff.some((change) => change.type === types_1.ChangeType.BREAKING && !acceptedPaths.has(change.path));
         if (format !== "text") {
-            console.log(formatReport(diff, acceptedPaths, format, (0, storage_1.getContractDisplayPath)()));
+            console.log(formatReport(diff, acceptedPaths, format, (0, storage_1.getContractDisplayPath)(target.namespace)));
             return hasBreaking ? 1 : 0;
         }
         if (diff.length === 0) {
@@ -103,27 +147,30 @@ program
         }
         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("<entry>", "path to the target CLI's entry file, or a configured cliguard.config.js target's name - " +
+    "always required here (unlike check/init/update): accepting a change is inherently a " +
+    'one-target operation, so there\'s no sensible "omit to run every target" mode')
     .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)
     .option("--strict", "match against the same --strict rules used to find this change (e.g. a positional argument reorder) - required to accept one, since it's otherwise invisible to the default comparison", false)
     .action(async (entry, changePath, options) => {
-    const exitCode = await withSuppressedExit(async () => {
+    const targets = resolveTargetsOrExit(entry, options.adapter);
+    const exitCode = await runAcrossTargets(targets, (target) => 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 (0, registry_1.resolveAdapter)(options.adapter).extract(entry);
-        const diff = applyDeprecations(diffEngine.applyUnstableMarkers((0, config_1.applyConfig)(diffEngine.compare(oldContract, newContract, { strict: options.strict }), (0, config_1.loadConfig)()), oldContract, newContract), indexDeprecations((0, storage_1.readDeprecations)()));
+        const oldContract = (0, storage_1.readContract)(target.namespace);
+        const newContract = await (0, registry_1.resolveAdapter)(target.adapter).extract(target.entry);
+        const diff = applyDeprecations(diffEngine.applyUnstableMarkers((0, config_1.applyConfig)(diffEngine.compare(oldContract, newContract, { strict: options.strict }), (0, config_1.loadConfig)()), oldContract, newContract), indexDeprecations((0, storage_1.readDeprecations)(target.namespace)));
         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);
@@ -135,18 +182,18 @@ program
         }
         // 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 remaining = (0, storage_1.readAcceptedBreaks)(target.namespace).filter((accepted) => accepted.path !== changePath);
         const accepted = {
             path: changePath,
             reason,
             acceptedAt: new Date().toISOString(),
         };
-        (0, storage_1.writeAcceptedBreaks)([...remaining, accepted]);
+        (0, storage_1.writeAcceptedBreaks)([...remaining, accepted], target.namespace);
         console.log(`✅ Accepted: [${changePath}] ${match.message}`);
         console.log(`   Reason: ${reason}`);
-        console.log(`   Recorded in ${(0, storage_1.getAcceptedBreaksDisplayPath)()} - commit this file.`);
+        console.log(`   Recorded in ${(0, storage_1.getAcceptedBreaksDisplayPath)(target.namespace)} - commit this file.`);
         return 0;
-    });
+    }));
     process.exit(exitCode);
 });
 program
@@ -190,15 +237,16 @@ program
 program
     .command("update")
     .description("Overwrite the committed contract with the CLI's current surface")
-    .argument("<entry>", "path to the target CLI's entry file")
+    .argument("[entry]", ENTRY_ARGUMENT_DESCRIPTION)
     .option(...adapterOption)
     .action(async (entry, options) => {
-    const exitCode = await withSuppressedExit(async () => {
-        const contract = await (0, registry_1.resolveAdapter)(options.adapter).extract(entry);
-        (0, storage_1.writeContract)(contract);
+    const targets = resolveTargetsOrExit(entry, options.adapter);
+    const exitCode = await runAcrossTargets(targets, (target) => withSuppressedExit(async () => {
+        const contract = await (0, registry_1.resolveAdapter)(target.adapter).extract(target.entry);
+        (0, storage_1.writeContract)(contract, target.namespace);
         console.log("🔄 CLI contract updated successfully.");
         return 0;
-    });
+    }));
     process.exit(exitCode);
 });
 program
@@ -214,6 +262,40 @@ program
     });
     process.exit(exitCode);
 });
+program
+    .command("docs")
+    .description("Generate Markdown CLI reference docs from the current contract - guaranteed to match the real CLI surface, since it's the same model `check` fails CI over")
+    .argument("<entry>", "path to the target CLI's entry file")
+    .option(...adapterOption)
+    .option("--check <path>", "compare against a committed docs file instead of printing - exits 1 if it's stale")
+    .action(async (entry, options) => {
+    const exitCode = await withSuppressedExit(async () => {
+        const contract = await (0, registry_1.resolveAdapter)(options.adapter).extract(entry);
+        const markdown = (0, docs_1.renderMarkdownDocs)(contract, (0, path_1.basename)(entry));
+        if (!options.check) {
+            // process.stdout.write, not console.log - markdown already ends
+            // in exactly one trailing newline, and console.log would add a
+            // second one, so a file saved via `> CLI.md` would never again
+            // match itself under `--check` (the mismatch this comment is
+            // replacing was caught by a live round-trip test, not review).
+            process.stdout.write(markdown);
+            return 0;
+        }
+        const committed = (0, storage_1.readTextFileIfExists)(options.check);
+        if (committed === null) {
+            console.error(`cliguard: no such file: "${options.check}". Run \`cliguard docs ${entry} > ${options.check}\` first.`);
+            return 1;
+        }
+        if (committed === markdown) {
+            console.log(`✅ ${options.check} matches the current CLI surface.`);
+            return 0;
+        }
+        console.error(`cliguard: "${options.check}" is stale - it no longer matches the current CLI surface. ` +
+            `Regenerate with \`cliguard docs ${entry} > ${options.check}\`.`);
+        return 1;
+    });
+    process.exit(exitCode);
+});
 program
     .command("doctor")
     .description("Show every adapter's known limitations, or sanity-check one against a real entry file")

package/dist/core/config.d.ts

@@ -4,15 +4,47 @@ export interface SeverityOverride {
     readonly pattern: string | RegExp;
     readonly severity: ChangeType;
 }
+export interface ConfigTarget {
+    /** Unique within the config; namespaces this target's contract/accepted-breaks/deprecations under `.cliguard/<name>/` instead of `.cliguard/`, and is what `cliguard check <name>` matches against to run just this one target. */
+    readonly name: string;
+    readonly entry: string;
+    /** Defaults to "commander", same as the CLI's own `--adapter` default. */
+    readonly adapter?: string;
+}
 export interface CliguardConfig {
     /** A change whose DiffResult.path matches any of these is dropped from the report entirely - never shown, never counted, never fails the build. */
     readonly ignore?: readonly (string | RegExp)[];
     /** A change whose DiffResult.path matches `pattern` gets reclassified to `severity` - the first matching entry wins. */
     readonly severityOverrides?: readonly SeverityOverride[];
+    /** A monorepo's CLI entry points - `init`/`check`/`update`/`accept` run against every target when no entry is given on the command line, or against just one by passing its `name` in place of an entry path. An explicit file-path entry always keeps working exactly as it does today, config or no config - see resolveTargets. */
+    readonly targets?: readonly ConfigTarget[];
 }
 /** Display-only path of whichever config file was actually found, or the first candidate name if none was - only meaningful in an error message alongside `configExists()`. */
 export declare function getConfigDisplayPath(): string;
 export declare function configExists(): boolean;
+/** One target `init`/`check`/`update`/`accept` should run against - `namespace` is `null` for the classic single-CLI flow (no config, or an explicit file-path entry), and a target's own `name` when resolved from `cliguard.config.js`, namespacing that target's `.cliguard/` files under `.cliguard/<namespace>/`. */
+export interface ResolvedTarget {
+    readonly namespace: string | null;
+    readonly entry: string;
+    readonly adapter: string;
+}
+/**
+ * Turns a command-line `[entry]` (now optional - see bin.ts) plus whatever
+ * `cliguard.config.js` declared into the concrete list of targets a
+ * command should run against:
+ *
+ * - `entry` given and it matches no configured target's `name`: exactly
+ *   what happens today with zero config - one classic, unnamespaced
+ *   target, using `entry` as a literal file path. This is deliberate and
+ *   load-bearing: a project with no `targets` in its config (or no config
+ *   at all) is completely unaffected by this feature.
+ * - `entry` given and it DOES match a configured target's `name`: just
+ *   that one target, namespaced.
+ * - `entry` omitted and `targets` is configured: every configured target.
+ * - `entry` omitted and no `targets` configured: throws - there's nothing
+ *   to run against.
+ */
+export declare function resolveTargets(entry: string | undefined, config: CliguardConfig, cliAdapter: string): ResolvedTarget[];
 /** Returns `{}` (no policy applied) when no config file exists - a project with no `cliguard.config.js` behaves exactly as it always has. */
 export declare function loadConfig(): CliguardConfig;
 /**

package/dist/core/config.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getConfigDisplayPath = getConfigDisplayPath;
 exports.configExists = configExists;
+exports.resolveTargets = resolveTargets;
 exports.loadConfig = loadConfig;
 exports.applyConfig = applyConfig;
 const fs_1 = require("fs");
@@ -54,8 +55,64 @@ function validateConfig(raw, displayPath) {
             }
         }
     }
+    if (config.targets !== undefined) {
+        if (!Array.isArray(config.targets)) {
+            throw new Error(`cliguard: ${displayPath}'s "targets" must be an array.`);
+        }
+        const seenNames = new Set();
+        for (const entry of config.targets) {
+            const target = entry;
+            const nameOk = typeof target.name === "string" && target.name.length > 0;
+            const entryOk = typeof target.entry === "string" && target.entry.length > 0;
+            const adapterOk = target.adapter === undefined || typeof target.adapter === "string";
+            if (!nameOk || !entryOk || !adapterOk) {
+                throw new Error(`cliguard: ${displayPath}'s "targets" entries must look like ` +
+                    `{ name: string, entry: string, adapter?: string } - got ${JSON.stringify(entry)}.`);
+            }
+            if (seenNames.has(target.name)) {
+                throw new Error(`cliguard: ${displayPath}'s "targets" has more than one entry named "${target.name}" - ` +
+                    "names must be unique, since each one gets its own .cliguard/<name>/ directory.");
+            }
+            seenNames.add(target.name);
+        }
+    }
     return config;
 }
+/**
+ * Turns a command-line `[entry]` (now optional - see bin.ts) plus whatever
+ * `cliguard.config.js` declared into the concrete list of targets a
+ * command should run against:
+ *
+ * - `entry` given and it matches no configured target's `name`: exactly
+ *   what happens today with zero config - one classic, unnamespaced
+ *   target, using `entry` as a literal file path. This is deliberate and
+ *   load-bearing: a project with no `targets` in its config (or no config
+ *   at all) is completely unaffected by this feature.
+ * - `entry` given and it DOES match a configured target's `name`: just
+ *   that one target, namespaced.
+ * - `entry` omitted and `targets` is configured: every configured target.
+ * - `entry` omitted and no `targets` configured: throws - there's nothing
+ *   to run against.
+ */
+function resolveTargets(entry, config, cliAdapter) {
+    const targets = config.targets ?? [];
+    if (entry !== undefined) {
+        const named = targets.find((target) => target.name === entry);
+        if (named) {
+            return [{ namespace: named.name, entry: named.entry, adapter: named.adapter ?? "commander" }];
+        }
+        return [{ namespace: null, entry, adapter: cliAdapter }];
+    }
+    if (targets.length > 0) {
+        return targets.map((target) => ({
+            namespace: target.name,
+            entry: target.entry,
+            adapter: target.adapter ?? "commander",
+        }));
+    }
+    throw new Error("cliguard: no entry given and no targets configured. Pass an entry file path, " +
+        "or add `targets: [{ name, entry, adapter? }, ...]` to cliguard.config.js.");
+}
 /** Returns `{}` (no policy applied) when no config file exists - a project with no `cliguard.config.js` behaves exactly as it always has. */
 function loadConfig() {
     const path = resolveConfigPath();

package/dist/core/docs.d.ts

@@ -0,0 +1,14 @@
+import type { Contract } from "./types";
+/**
+ * Renders a Contract as Markdown CLI reference docs - one section per
+ * command, an arguments table and an options table for each. Walks the
+ * same recursive `CommandContract` tree `diff.engine.ts` walks, so a
+ * command that `check` can already see is a command these docs can already
+ * render; nothing here reads a live CLI or a specific adapter.
+ *
+ * The point of generating this from the Contract rather than hand-writing
+ * it: the moment the docs would go stale, `check` already fails CI for the
+ * same underlying reason (the CLI's surface changed) - these docs literally
+ * cannot drift from reality without cliguard itself catching it first.
+ */
+export declare function renderMarkdownDocs(contract: Contract, fallbackTitle: string): string;

package/dist/core/docs.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderMarkdownDocs = renderMarkdownDocs;
+/**
+ * Renders a Contract as Markdown CLI reference docs - one section per
+ * command, an arguments table and an options table for each. Walks the
+ * same recursive `CommandContract` tree `diff.engine.ts` walks, so a
+ * command that `check` can already see is a command these docs can already
+ * render; nothing here reads a live CLI or a specific adapter.
+ *
+ * The point of generating this from the Contract rather than hand-writing
+ * it: the moment the docs would go stale, `check` already fails CI for the
+ * same underlying reason (the CLI's surface changed) - these docs literally
+ * cannot drift from reality without cliguard itself catching it first.
+ */
+function renderMarkdownDocs(contract, fallbackTitle) {
+    const title = contract.root.name || fallbackTitle;
+    const lines = [`# ${title}`, ""];
+    if (contract.root.description) {
+        lines.push(contract.root.description, "");
+    }
+    renderCommandBody(contract.root, lines);
+    renderSubcommands(contract.root, 2, lines);
+    return (lines
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trimEnd() + "\n");
+}
+function renderSubcommands(cmd, depth, lines) {
+    const level = Math.min(depth, 6);
+    for (const sub of cmd.subcommands) {
+        lines.push(`${"#".repeat(level)} \`${commandSignature(sub)}\``, "");
+        if (sub.description)
+            lines.push(sub.description, "");
+        if (sub.aliases.length > 0) {
+            lines.push(`_Aliases: ${sub.aliases.map((alias) => `\`${alias}\``).join(", ")}_`, "");
+        }
+        renderCommandBody(sub, lines);
+        renderSubcommands(sub, depth + 1, lines);
+    }
+}
+/** `<default>` (see diff.engine.ts's own commandLabel) reads as a real, if odd, name; CAC's blank-name default command instead renders as just the CLI's own usage line with no distinct heading fragment. */
+function commandSignature(cmd) {
+    const args = cmd.arguments.map(argumentUsage).join(" ");
+    return [cmd.name, args].filter(Boolean).join(" ");
+}
+function argumentUsage(arg) {
+    const name = arg.variadic ? `${arg.name}...` : arg.name;
+    return arg.required ? `<${name}>` : `[${name}]`;
+}
+function renderCommandBody(cmd, lines) {
+    if (cmd.arguments.length > 0) {
+        lines.push("**Arguments**", "", "| Name | Required | Description |", "|---|---|---|");
+        for (const arg of cmd.arguments) {
+            lines.push(`| \`${escapeCell(argumentUsage(arg))}\` | ${arg.required ? "yes" : "no"} | ${escapeCell(arg.description)} |`);
+        }
+        lines.push("");
+    }
+    if (cmd.options.length > 0) {
+        lines.push("**Options**", "", "| Flag | Default | Description |", "|---|---|---|");
+        for (const option of cmd.options) {
+            lines.push(`| ${optionCell(option)} | ${defaultCell(option)} | ${descriptionCell(option)} |`);
+        }
+        lines.push("");
+    }
+}
+function optionCell(option) {
+    return `\`${escapeCell(option.flags)}\``;
+}
+/** A string default renders bare (`dist/out.js`) - readable as prose. Any other JSON-serializable shape (boolean, number, array) renders via JSON.stringify so it stays unambiguous (e.g. distinguishing the string "true" from the boolean true never comes up for a string default, but would for anything else). */
+function defaultCell(option) {
+    if (option.defaultValue === null || option.defaultValue === undefined)
+        return "-";
+    const rendered = typeof option.defaultValue === "string"
+        ? option.defaultValue
+        : JSON.stringify(option.defaultValue);
+    return `\`${escapeCell(rendered)}\``;
+}
+function descriptionCell(option) {
+    const description = escapeCell(option.description);
+    return option.required ? `${description} *(required)*` : description;
+}
+/** Markdown table cells break on a literal `|` or an embedded newline - both are possible in a framework-supplied description string. */
+function escapeCell(value) {
+    return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}

package/dist/core/storage.d.ts

@@ -1,11 +1,11 @@
 import type { AcceptedBreak, Contract, Deprecation } from "./types";
 /** Contract path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
-export declare function getContractDisplayPath(): string;
+export declare function getContractDisplayPath(namespace?: string | null): 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;
+export declare function getAcceptedBreaksDisplayPath(namespace?: string | null): string;
+export declare function contractExists(namespace?: string | null): boolean;
+export declare function readContract(namespace?: string | null): Contract;
+export declare function writeContract(contract: Contract, namespace?: string | null): void;
 /**
  * Reads a Contract from an arbitrary path, not the committed
  * `.cliguard/contract.json` - for `cliguard diff <a> <b>`, comparing two
@@ -23,15 +23,15 @@ export declare function readContractFile(path: string, displayPath?: string): Co
  * already names as the manual workaround (`git show <ref>:... > old.json`
  * piped into `cliguard diff`).
  */
-export declare function readContractAtRef(ref: string): Contract;
+export declare function readContractAtRef(ref: string, namespace?: string | null): 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;
+export declare function readAcceptedBreaks(namespace?: string | null): AcceptedBreak[];
+export declare function writeAcceptedBreaks(breaks: readonly AcceptedBreak[], namespace?: string | null): void;
 /** Deprecations path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
-export declare function getDeprecationsDisplayPath(): string;
+export declare function getDeprecationsDisplayPath(namespace?: string | null): string;
 /** Unlike readContract, a missing file is normal (most projects never deprecate anything) - returns [] rather than throwing. */
-export declare function readDeprecations(): Deprecation[];
-export declare function writeDeprecations(deprecations: readonly Deprecation[]): void;
+export declare function readDeprecations(namespace?: string | null): Deprecation[];
+export declare function writeDeprecations(deprecations: readonly Deprecation[], namespace?: string | null): void;
 /** CI workflow path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
 export declare function getCiWorkflowDisplayPath(): string;
 export declare function ciWorkflowExists(): boolean;
@@ -40,5 +40,7 @@ export declare function writeCiWorkflow(content: string): void;
 /** Hook path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
 export declare function getHookDisplayPath(hookName: string): string;
 export declare function hookExists(hookName: string): boolean;
+/** Reads an arbitrary user-supplied text file (not one of cliguard's own fixed `.cliguard/*` paths) - `null` when it doesn't exist, since "no committed docs yet" is a normal, expected state for `cliguard docs --check`, not an error. */
+export declare function readTextFileIfExists(path: string): string | null;
 /** Never called when hookExists() is true - install-hook checks first so a hand-edited hook is never clobbered. */
 export declare function writeHook(hookName: string, content: string): void;

package/dist/core/storage.js

@@ -17,30 +17,44 @@ exports.ciWorkflowExists = ciWorkflowExists;
 exports.writeCiWorkflow = writeCiWorkflow;
 exports.getHookDisplayPath = getHookDisplayPath;
 exports.hookExists = hookExists;
+exports.readTextFileIfExists = readTextFileIfExists;
 exports.writeHook = writeHook;
 const child_process_1 = require("child_process");
 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");
-const DEPRECATIONS_PATH = (0, path_1.join)(process.cwd(), ".cliguard", "deprecations.json");
+const CLIGUARD_DIR = (0, path_1.join)(process.cwd(), ".cliguard");
 const CI_WORKFLOW_PATH = (0, path_1.join)(process.cwd(), ".github", "workflows", "cliguard.yml");
+/**
+ * `namespace` is a config-resolved target's own `name` (see
+ * core/config.ts's `resolveTargets`) - `null` for the classic single-CLI
+ * flow, which keeps every path exactly what it always was
+ * (`.cliguard/contract.json`, not `.cliguard/null/contract.json`;
+ * `path.join` drops an empty segment the same way). A named target gets
+ * its own `.cliguard/<name>/` directory so two targets' contracts,
+ * accepted breaks, and deprecations never collide on disk.
+ */
+function targetPath(namespace, fileName) {
+    return (0, path_1.join)(CLIGUARD_DIR, namespace ?? "", fileName);
+}
 /** 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("/");
+function getContractDisplayPath(namespace = null) {
+    return (0, path_1.relative)(process.cwd(), targetPath(namespace, "contract.json")).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 getAcceptedBreaksDisplayPath(namespace = null) {
+    return (0, path_1.relative)(process.cwd(), targetPath(namespace, "accepted-breaks.json"))
+        .split("\\")
+        .join("/");
 }
-function contractExists() {
-    return (0, fs_1.existsSync)(CONTRACT_PATH);
+function contractExists(namespace = null) {
+    return (0, fs_1.existsSync)(targetPath(namespace, "contract.json"));
 }
-function readContract() {
-    if (!(0, fs_1.existsSync)(CONTRACT_PATH)) {
-        throw new Error(`cliguard: no contract found at "${getContractDisplayPath()}". Run \`cliguard init <entry.js>\` first.`);
+function readContract(namespace = null) {
+    const contractPath = targetPath(namespace, "contract.json");
+    if (!(0, fs_1.existsSync)(contractPath)) {
+        throw new Error(`cliguard: no contract found at "${getContractDisplayPath(namespace)}". Run \`cliguard init <entry.js>\` first.`);
     }
-    const raw = (0, fs_1.readFileSync)(CONTRACT_PATH, "utf-8");
+    const raw = (0, fs_1.readFileSync)(contractPath, "utf-8");
     try {
         return JSON.parse(raw);
     }
@@ -52,14 +66,15 @@ function readContract() {
         // fix (re-run init/update) turns a confusing crash into an
         // actionable message.
         const reason = error instanceof Error ? error.message : String(error);
-        throw new Error(`cliguard: "${getContractDisplayPath()}" is not valid JSON (${reason}). ` +
+        throw new Error(`cliguard: "${getContractDisplayPath(namespace)}" is not valid JSON (${reason}). ` +
             "If this file was hand-edited or came out of a bad merge, re-run " +
             "`cliguard update <entry.js>` to regenerate it.");
     }
 }
-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");
+function writeContract(contract, namespace = null) {
+    const contractPath = targetPath(namespace, "contract.json");
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(contractPath), { recursive: true });
+    (0, fs_1.writeFileSync)(contractPath, JSON.stringify(contract, null, 2) + "\n", "utf-8");
 }
 /**
  * Reads a Contract from an arbitrary path, not the committed
@@ -90,8 +105,8 @@ function readContractFile(path, displayPath = path) {
  * already names as the manual workaround (`git show <ref>:... > old.json`
  * piped into `cliguard diff`).
  */
-function readContractAtRef(ref) {
-    const contractGitPath = getContractDisplayPath();
+function readContractAtRef(ref, namespace = null) {
+    const contractGitPath = getContractDisplayPath(namespace);
     let raw;
     try {
         raw = (0, child_process_1.execFileSync)("git", ["show", `${ref}:${contractGitPath}`], {
@@ -117,10 +132,11 @@ function readContractAtRef(ref) {
     }
 }
 /** 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))
+function readAcceptedBreaks(namespace = null) {
+    const acceptedBreaksPath = targetPath(namespace, "accepted-breaks.json");
+    if (!(0, fs_1.existsSync)(acceptedBreaksPath))
         return [];
-    const raw = (0, fs_1.readFileSync)(ACCEPTED_BREAKS_PATH, "utf-8");
+    const raw = (0, fs_1.readFileSync)(acceptedBreaksPath, "utf-8");
     try {
         return JSON.parse(raw);
     }
@@ -128,37 +144,40 @@ function readAcceptedBreaks() {
         // 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}). ` +
+        throw new Error(`cliguard: "${getAcceptedBreaksDisplayPath(namespace)}" 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");
+function writeAcceptedBreaks(breaks, namespace = null) {
+    const acceptedBreaksPath = targetPath(namespace, "accepted-breaks.json");
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(acceptedBreaksPath), { recursive: true });
+    (0, fs_1.writeFileSync)(acceptedBreaksPath, JSON.stringify(breaks, null, 2) + "\n", "utf-8");
 }
 /** Deprecations path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
-function getDeprecationsDisplayPath() {
-    return (0, path_1.relative)(process.cwd(), DEPRECATIONS_PATH).split("\\").join("/");
+function getDeprecationsDisplayPath(namespace = null) {
+    return (0, path_1.relative)(process.cwd(), targetPath(namespace, "deprecations.json")).split("\\").join("/");
 }
 /** Unlike readContract, a missing file is normal (most projects never deprecate anything) - returns [] rather than throwing. */
-function readDeprecations() {
-    if (!(0, fs_1.existsSync)(DEPRECATIONS_PATH))
+function readDeprecations(namespace = null) {
+    const deprecationsPath = targetPath(namespace, "deprecations.json");
+    if (!(0, fs_1.existsSync)(deprecationsPath))
         return [];
-    const raw = (0, fs_1.readFileSync)(DEPRECATIONS_PATH, "utf-8");
+    const raw = (0, fs_1.readFileSync)(deprecationsPath, "utf-8");
     try {
         return JSON.parse(raw);
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
-        throw new Error(`cliguard: "${getDeprecationsDisplayPath()}" is not valid JSON (${reason}). ` +
+        throw new Error(`cliguard: "${getDeprecationsDisplayPath(namespace)}" 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 deprecate` for whatever was in it.");
     }
 }
-function writeDeprecations(deprecations) {
-    (0, fs_1.mkdirSync)((0, path_1.dirname)(DEPRECATIONS_PATH), { recursive: true });
-    (0, fs_1.writeFileSync)(DEPRECATIONS_PATH, JSON.stringify(deprecations, null, 2) + "\n", "utf-8");
+function writeDeprecations(deprecations, namespace = null) {
+    const deprecationsPath = targetPath(namespace, "deprecations.json");
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(deprecationsPath), { recursive: true });
+    (0, fs_1.writeFileSync)(deprecationsPath, JSON.stringify(deprecations, null, 2) + "\n", "utf-8");
 }
 /** CI workflow path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
 function getCiWorkflowDisplayPath() {
@@ -197,6 +216,10 @@ function getHookDisplayPath(hookName) {
 function hookExists(hookName) {
     return (0, fs_1.existsSync)((0, path_1.join)(resolveHooksDir(), hookName));
 }
+/** Reads an arbitrary user-supplied text file (not one of cliguard's own fixed `.cliguard/*` paths) - `null` when it doesn't exist, since "no committed docs yet" is a normal, expected state for `cliguard docs --check`, not an error. */
+function readTextFileIfExists(path) {
+    return (0, fs_1.existsSync)(path) ? (0, fs_1.readFileSync)(path, "utf-8") : null;
+}
 /** Never called when hookExists() is true - install-hook checks first so a hand-edited hook is never clobbered. */
 function writeHook(hookName, content) {
     const hookPath = (0, path_1.join)(resolveHooksDir(), hookName);

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { type CompareOptions, type DiffResult } from "./core/diff.engine";
 import type { Contract } from "./core/types";
 export type { CliAdapter } from "./adapters/adapter.interface";
 export { CacAdapter } from "./adapters/cac.adapter";
+export { ClickAdapter } from "./adapters/click.adapter";
 export { CommanderAdapter } from "./adapters/commander.adapter";
 export { YargsAdapter } from "./adapters/yargs.adapter";
 export { adapters, resolveAdapter } from "./adapters/registry";
@@ -9,6 +10,7 @@ export { applyConfig, configExists, loadConfig } from "./core/config";
 export type { CliguardConfig, SeverityOverride } from "./core/config";
 export { DiffEngine } from "./core/diff.engine";
 export type { CompareOptions, DiffResult } from "./core/diff.engine";
+export { renderMarkdownDocs } from "./core/docs";
 export { toGitLabCodeQuality, toJUnitXml, toRdjsonl } from "./core/report-formats";
 export type { ReportChange } from "./core/report-formats";
 export { ChangeType, type AcceptedBreak, type ArgumentContract, type CommandContract, type Contract, type Deprecation, type OptionContract, type OptionValueType, } from "./core/types";
@@ -27,5 +29,5 @@ export declare function extractContract(entryPath: string, adapterName?: string)
  * or a git ref by the caller's own code.
  */
 export declare function compareContracts(oldContract: Contract, newContract: Contract, options?: CompareOptions): DiffResult[];
-/** Every adapter name `extractContract`/the CLI's `--adapter` flag will accept, e.g. ["commander", "cac", "yargs"]. */
+/** Every adapter name `extractContract`/the CLI's `--adapter` flag will accept, e.g. ["commander", "cac", "yargs", "click"]. */
 export declare function listAdapters(): string[];

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ChangeType = exports.toRdjsonl = exports.toJUnitXml = exports.toGitLabCodeQuality = exports.DiffEngine = exports.loadConfig = exports.configExists = exports.applyConfig = exports.resolveAdapter = exports.adapters = exports.YargsAdapter = exports.CommanderAdapter = exports.CacAdapter = void 0;
+exports.ChangeType = exports.toRdjsonl = exports.toJUnitXml = exports.toGitLabCodeQuality = exports.renderMarkdownDocs = exports.DiffEngine = exports.loadConfig = exports.configExists = exports.applyConfig = exports.resolveAdapter = exports.adapters = exports.YargsAdapter = exports.CommanderAdapter = exports.ClickAdapter = exports.CacAdapter = void 0;
 exports.extractContract = extractContract;
 exports.compareContracts = compareContracts;
 exports.listAdapters = listAdapters;
@@ -16,6 +16,8 @@ const registry_1 = require("./adapters/registry");
 const diff_engine_1 = require("./core/diff.engine");
 var cac_adapter_1 = require("./adapters/cac.adapter");
 Object.defineProperty(exports, "CacAdapter", { enumerable: true, get: function () { return cac_adapter_1.CacAdapter; } });
+var click_adapter_1 = require("./adapters/click.adapter");
+Object.defineProperty(exports, "ClickAdapter", { enumerable: true, get: function () { return click_adapter_1.ClickAdapter; } });
 var commander_adapter_1 = require("./adapters/commander.adapter");
 Object.defineProperty(exports, "CommanderAdapter", { enumerable: true, get: function () { return commander_adapter_1.CommanderAdapter; } });
 var yargs_adapter_1 = require("./adapters/yargs.adapter");
@@ -29,6 +31,8 @@ Object.defineProperty(exports, "configExists", { enumerable: true, get: function
 Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_1.loadConfig; } });
 var diff_engine_2 = require("./core/diff.engine");
 Object.defineProperty(exports, "DiffEngine", { enumerable: true, get: function () { return diff_engine_2.DiffEngine; } });
+var docs_1 = require("./core/docs");
+Object.defineProperty(exports, "renderMarkdownDocs", { enumerable: true, get: function () { return docs_1.renderMarkdownDocs; } });
 var report_formats_1 = require("./core/report-formats");
 Object.defineProperty(exports, "toGitLabCodeQuality", { enumerable: true, get: function () { return report_formats_1.toGitLabCodeQuality; } });
 Object.defineProperty(exports, "toJUnitXml", { enumerable: true, get: function () { return report_formats_1.toJUnitXml; } });
@@ -60,7 +64,7 @@ async function extractContract(entryPath, adapterName = "commander") {
 function compareContracts(oldContract, newContract, options) {
     return diffEngine.compare(oldContract, newContract, options);
 }
-/** Every adapter name `extractContract`/the CLI's `--adapter` flag will accept, e.g. ["commander", "cac", "yargs"]. */
+/** Every adapter name `extractContract`/the CLI's `--adapter` flag will accept, e.g. ["commander", "cac", "yargs", "click"]. */
 function listAdapters() {
     return Object.keys(registry_1.adapters);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cliguard",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Snapshot-tests your CLI's contract (commands, flags, defaults) so you never ship a breaking change by accident.",
   "keywords": [
     "cli",
@@ -8,6 +8,7 @@
     "snapshot-testing",
     "commander",
     "yargs",
+    "click",
     "ci"
   ],
   "author": "Bryandero98",