cliguard 0.6.0 → 0.7.0

package/dist/bin.js

@@ -2,28 +2,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
-const cac_adapter_1 = require("./adapters/cac.adapter");
-const commander_adapter_1 = require("./adapters/commander.adapter");
-const yargs_adapter_1 = require("./adapters/yargs.adapter");
+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 report_formats_1 = require("./core/report-formats");
 const storage_1 = require("./core/storage");
 const types_1 = require("./core/types");
-// Constructing an adapter here is cheap (no eager require of its
-// framework - CacAdapter only loads `cac` lazily, inside extract()), so
-// every adapter is always registered regardless of which one a given
-// invocation actually uses.
-const adapters = {
-    commander: new commander_adapter_1.CommanderAdapter(),
-    cac: new cac_adapter_1.CacAdapter(),
-    yargs: new yargs_adapter_1.YargsAdapter(),
-};
-function resolveAdapter(name) {
-    const adapter = adapters[name];
-    if (!adapter) {
-        throw new Error(`cliguard: unknown adapter "${name}". Available: ${Object.keys(adapters).join(", ")}.`);
-    }
-    return adapter;
-}
 const diffEngine = new diff_engine_1.DiffEngine();
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- package.json has no type declarations to import against; require() is the simplest correct read here
 const packageJson = require("../package.json");
@@ -37,20 +22,52 @@ const adapterOption = [
     "CLI framework adapter to use",
     "commander",
 ];
+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) {
+    const format = explicit ?? (jsonFlag ? "json" : "text");
+    return REPORT_FORMATS.includes(format) ? format : null;
+}
+/** Renders every format except "text" (which each command still prints itself, since its "nothing changed" message differs between `check` and `diff`). */
+function formatReport(diff, acceptedPaths, format, contractPath) {
+    if (format === "json") {
+        return JSON.stringify(toJsonResult(diff, acceptedPaths), null, 2);
+    }
+    const annotated = annotateChanges(diff, acceptedPaths);
+    switch (format) {
+        case "junit":
+            return (0, report_formats_1.toJUnitXml)(annotated);
+        case "gitlab-codequality":
+            return (0, report_formats_1.toGitLabCodeQuality)(annotated, contractPath);
+        case "rdjsonl":
+            return (0, report_formats_1.toRdjsonl)(annotated, contractPath);
+    }
+}
 program
     .command("init")
     .description("Capture the current CLI surface as the committed contract")
     .argument("<entry>", "path to the target CLI's entry file")
     .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.`);
         process.exit(1);
     }
     const exitCode = await withSuppressedExit(async () => {
-        const contract = await resolveAdapter(options.adapter).extract(entry);
+        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)()}.`);
+        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));
+                console.log(`✅ GitHub Actions workflow scaffolded at ${(0, storage_1.getCiWorkflowDisplayPath)()}.`);
+            }
+        }
         return 0;
     });
     process.exit(exitCode);
@@ -60,16 +77,24 @@ program
     .description("Compare the current CLI surface against the committed contract")
     .argument("<entry>", "path to the target CLI's entry file")
     .option(...adapterOption)
-    .option("--json", "print a machine-readable JSON result instead of text", false)
+    .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 oldContract = (0, storage_1.readContract)();
-        const newContract = await resolveAdapter(options.adapter).extract(entry);
-        const diff = diffEngine.compare(oldContract, newContract);
+        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 hasBreaking = diff.some((change) => change.type === types_1.ChangeType.BREAKING && !acceptedPaths.has(change.path));
-        if (options.json) {
-            console.log(JSON.stringify(toJsonResult(diff, acceptedPaths), null, 2));
+        if (format !== "text") {
+            console.log(formatReport(diff, acceptedPaths, format, (0, storage_1.getContractDisplayPath)()));
             return hasBreaking ? 1 : 0;
         }
         if (diff.length === 0) {
@@ -96,8 +121,8 @@ program
             return 1;
         }
         const oldContract = (0, storage_1.readContract)();
-        const newContract = await resolveAdapter(options.adapter).extract(entry);
-        const diff = diffEngine.compare(oldContract, newContract);
+        const newContract = await (0, registry_1.resolveAdapter)(options.adapter).extract(entry);
+        const diff = applyDeprecations(diffEngine.applyUnstableMarkers((0, config_1.applyConfig)(diffEngine.compare(oldContract, newContract), (0, config_1.loadConfig)()), oldContract, newContract), indexDeprecations((0, storage_1.readDeprecations)()));
         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);
@@ -123,6 +148,44 @@ program
     });
     process.exit(exitCode);
 });
+program
+    .command("deprecate")
+    .description("Schedule a command/option/argument for removal ahead of time, so that removal counts as PATCH instead of BREAKING")
+    .argument("<entry>", "path to the target CLI's entry file")
+    .argument("<path>", 'the exact Contract path to deprecate, e.g. "root -> build -> option[--target]" - still present today, not yet removed')
+    .requiredOption("--remove-by <versionOrDate>", 'when this is expected to actually go away (e.g. "2.0.0" or "2026-12-01") - informational, never enforced by cliguard itself')
+    .option("-r, --reason <text>", "why this is being deprecated - shown once it's removed")
+    .option(...adapterOption)
+    .action(async (entry, path, options) => {
+    const exitCode = await withSuppressedExit(async () => {
+        const contract = await (0, registry_1.resolveAdapter)(options.adapter).extract(entry);
+        const validPaths = diffEngine.collectPaths(contract);
+        if (!validPaths.has(path)) {
+            console.error(`cliguard: no such path "${path}" in the current contract - it may already be ` +
+                "removed, or never existed. Run `cliguard preview <entry>` to see the current contract.");
+            return 1;
+        }
+        // Replaces any earlier deprecation at the same path rather than
+        // accumulating duplicates - re-running `deprecate` updates the
+        // remove-by/reason, same as `accept` does for its own reason.
+        const remaining = (0, storage_1.readDeprecations)().filter((existing) => existing.path !== path);
+        const deprecation = {
+            path,
+            removeBy: options.removeBy,
+            reason: options.reason,
+            deprecatedAt: new Date().toISOString(),
+        };
+        (0, storage_1.writeDeprecations)([...remaining, deprecation]);
+        console.log(`✅ Deprecated: [${path}]`);
+        console.log(`   Remove by: ${options.removeBy}`);
+        if (options.reason)
+            console.log(`   Reason: ${options.reason}`);
+        console.log(`   Recorded in ${(0, storage_1.getDeprecationsDisplayPath)()} - commit this file. ` +
+            "Its eventual removal will count as PATCH, not BREAKING.");
+        return 0;
+    });
+    process.exit(exitCode);
+});
 program
     .command("update")
     .description("Overwrite the committed contract with the CLI's current surface")
@@ -130,31 +193,108 @@ program
     .option(...adapterOption)
     .action(async (entry, options) => {
     const exitCode = await withSuppressedExit(async () => {
-        const contract = await resolveAdapter(options.adapter).extract(entry);
+        const contract = await (0, registry_1.resolveAdapter)(options.adapter).extract(entry);
         (0, storage_1.writeContract)(contract);
         console.log("🔄 CLI contract updated successfully.");
         return 0;
     });
     process.exit(exitCode);
 });
+program
+    .command("preview")
+    .description("Extract the current CLI's contract and print it, without writing .cliguard/contract.json")
+    .argument("<entry>", "path to the target CLI's entry file")
+    .option(...adapterOption)
+    .action(async (entry, options) => {
+    const exitCode = await withSuppressedExit(async () => {
+        const contract = await (0, registry_1.resolveAdapter)(options.adapter).extract(entry);
+        console.log(JSON.stringify(contract, null, 2));
+        return 0;
+    });
+    process.exit(exitCode);
+});
+program
+    .command("doctor")
+    .description("Show every adapter's known limitations, or sanity-check one against a real entry file")
+    .argument("[entry]", "optional: path to a target CLI's entry file to actually test extraction")
+    .option(...adapterOption)
+    .action(async (entry, options) => {
+    if (!entry) {
+        printAdapterLimitations();
+        process.exit(0);
+    }
+    const exitCode = await withSuppressedExit(async () => {
+        const adapter = (0, registry_1.resolveAdapter)(options.adapter);
+        console.log(`Adapter: ${adapter.id}`);
+        if (adapter.limitations.length === 0) {
+            console.log("  No known limitations.");
+        }
+        else {
+            for (const limitation of adapter.limitations) {
+                console.log(`  ⚠️  ${limitation}`);
+            }
+        }
+        console.log("");
+        try {
+            const contract = await adapter.extract(entry);
+            const summary = summarizeCommand(contract.root);
+            console.log(`✅ Extraction succeeded: ${summary.commands} command(s), ` +
+                `${summary.options} option(s), ${summary.arguments} argument(s).`);
+            return 0;
+        }
+        catch (error) {
+            console.error(`❌ Extraction failed: ${error instanceof Error ? error.message : String(error)}`);
+            return 1;
+        }
+    });
+    process.exit(exitCode);
+});
+const HOOK_NAMES = ["pre-commit", "pre-push"];
+program
+    .command("install-hook")
+    .description("Install a git hook that runs `cliguard check` automatically, catching a breaking change before it ever reaches CI")
+    .argument("<entry>", "path to the target CLI's entry file")
+    .option(...adapterOption)
+    .option("--hook <name>", `which git hook to install: ${HOOK_NAMES.join(" or ")}`, "pre-push")
+    .action((entry, options) => {
+    if (!isHookName(options.hook)) {
+        console.error(`cliguard: --hook must be one of ${HOOK_NAMES.join(", ")} - got "${options.hook}".`);
+        process.exit(1);
+    }
+    if ((0, storage_1.hookExists)(options.hook)) {
+        console.log(`ℹ️  ${(0, storage_1.getHookDisplayPath)(options.hook)} already exists - left it untouched.`);
+        process.exit(0);
+    }
+    const entryPath = (0, path_1.relative)(process.cwd(), (0, path_1.resolve)(entry)).split("\\").join("/");
+    (0, storage_1.writeHook)(options.hook, buildHookScript(entryPath, options.adapter));
+    console.log(`✅ Git hook installed at ${(0, storage_1.getHookDisplayPath)(options.hook)}.`);
+    process.exit(0);
+});
 program
     .command("diff")
     .description("Compare two contract files directly, without running any CLI")
     .argument("<oldContract>", "path to the older contract JSON file")
     .argument("<newContract>", "path to the newer contract JSON file")
-    .option("--json", "print a machine-readable JSON result instead of text", false)
+    .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("--strict", "enable extra rules for currently-silent risky changes (e.g. a positional argument reorder)", false)
     .action((oldPath, newPath, options) => {
     // No adapter, no target CLI ever loaded here - just two files off
     // disk - so none of withSuppressedExit's process.exit-race concerns
     // apply. A thrown Error (bad path, corrupt JSON) still surfaces via
     // this program's own top-level parseAsync().catch() below.
+    const format = resolveFormat(options.format, options.json);
+    if (!format) {
+        console.error(`cliguard: unknown --format "${options.format}". Use ${REPORT_FORMATS.join(", ")}.`);
+        process.exit(1);
+    }
     const oldContract = (0, storage_1.readContractFile)(oldPath);
     const newContract = (0, storage_1.readContractFile)(newPath);
-    const diff = diffEngine.compare(oldContract, newContract);
+    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 hasBreaking = diff.some((change) => change.type === types_1.ChangeType.BREAKING && !acceptedPaths.has(change.path));
-    if (options.json) {
-        console.log(JSON.stringify(toJsonResult(diff, acceptedPaths), null, 2));
+    if (format !== "text") {
+        console.log(formatReport(diff, acceptedPaths, format, newPath));
         process.exit(hasBreaking ? 1 : 0);
     }
     if (diff.length === 0) {
@@ -164,6 +304,81 @@ program
     printDiff(diff, acceptedPaths);
     process.exit(hasBreaking ? 1 : 0);
 });
+/**
+ * The same workflow the README's "CI integration" section documents by
+ * hand - generated here so `init --with-ci` never drifts from it. `entry`
+ * is expected already normalized (forward slashes, relative to cwd); the
+ * adapter line is only emitted for a non-default adapter, matching the
+ * Action's own `adapter` input default of "commander".
+ */
+function buildCiWorkflowYaml(entryPath, adapter) {
+    const lines = [
+        "# Generated by `cliguard init --with-ci` - edit freely, cliguard won't touch this file again.",
+        "name: CLI contract",
+        "on: [pull_request]",
+        "permissions:",
+        "  pull-requests: write # needed for the PR comment",
+        "jobs:",
+        "  check:",
+        "    runs-on: ubuntu-latest",
+        "    steps:",
+        "      - uses: actions/checkout@v4",
+        "      - uses: actions/setup-node@v4",
+        "        with: { node-version: 22.x }",
+        "      - run: npm ci",
+        "      - uses: Bryandero98/cliguard@v1",
+        "        with:",
+        `          entry: ./${entryPath}`,
+    ];
+    if (adapter !== "commander") {
+        lines.push(`          adapter: ${adapter}`);
+    }
+    return lines.join("\n") + "\n";
+}
+function printAdapterLimitations() {
+    console.log("Registered adapters and their known limitations:\n");
+    for (const adapter of Object.values(registry_1.adapters)) {
+        console.log(adapter.id + ":");
+        if (adapter.limitations.length === 0) {
+            console.log("  No known limitations.");
+        }
+        else {
+            for (const limitation of adapter.limitations) {
+                console.log(`  ⚠️  ${limitation}`);
+            }
+        }
+        console.log("");
+    }
+}
+function summarizeCommand(cmd) {
+    let commands = 1;
+    let options = cmd.options.length;
+    let args = cmd.arguments.length;
+    for (const sub of cmd.subcommands) {
+        const subSummary = summarizeCommand(sub);
+        commands += subSummary.commands;
+        options += subSummary.options;
+        args += subSummary.arguments;
+    }
+    return { commands, options, arguments: args };
+}
+function isHookName(value) {
+    return HOOK_NAMES.includes(value);
+}
+/**
+ * A minimal POSIX-sh script - Git for Windows runs hooks through its own
+ * bundled sh.exe via the shebang, same as any other platform, so one
+ * script body works everywhere without a separate Windows path.
+ */
+function buildHookScript(entryPath, adapter) {
+    const adapterFlag = adapter === "commander" ? "" : ` --adapter ${adapter}`;
+    return [
+        "#!/bin/sh",
+        "# Installed by `cliguard install-hook` - edit freely, cliguard won't touch this file again.",
+        `npx cliguard check "${entryPath}"${adapterFlag}`,
+        "",
+    ].join("\n");
+}
 /**
  * Runs `action` with `process.exit` neutralized, restoring the real one
  * the instant `action` settles - then the caller calls the *real*
@@ -198,13 +413,47 @@ async function withSuppressedExit(action) {
 function indexAcceptedBreaks(accepted) {
     return new Map(accepted.map((entry) => [entry.path, entry]));
 }
-function toJsonResult(diff, acceptedPaths) {
-    const changes = diff.map((entry) => {
+function indexDeprecations(deprecations) {
+    return new Map(deprecations.map((entry) => [entry.path, entry]));
+}
+/**
+ * Reclassifies a BREAKING removal at a deprecated path as PATCH, folding
+ * the deprecation's own record into the message - a scheduled, announced
+ * removal is no longer a surprise to whoever's relying on the flag, so it
+ * shouldn't fail the build the way an unannounced one still does. Only
+ * ever touches entries with `removal: true` (see DiffResult) - a
+ * *different* kind of BREAKING change at the same path (e.g. a default
+ * value change on an option that also happens to be deprecated) is left
+ * alone, since deprecating a removal says nothing about other changes.
+ */
+function applyDeprecations(diff, deprecations) {
+    return diff.map((entry) => {
+        if (entry.type !== types_1.ChangeType.BREAKING || !entry.removal)
+            return entry;
+        const deprecation = deprecations.get(entry.path);
+        if (!deprecation)
+            return entry;
+        return {
+            type: types_1.ChangeType.PATCH,
+            path: entry.path,
+            message: `${entry.message} Deprecated ${deprecation.deprecatedAt.slice(0, 10)}, ` +
+                `scheduled removal by ${deprecation.removeBy}` +
+                (deprecation.reason ? ` (${deprecation.reason})` : "") +
+                " - this removal was expected.",
+        };
+    });
+}
+/** A BREAKING entry matched by `cliguard accept` gains `acknowledged: true` and its recorded `reason`; every other entry passes through unchanged. Shared by --json, --format junit, and --format gitlab-codequality so all three agree on what "acknowledged" means. */
+function annotateChanges(diff, acceptedPaths) {
+    return diff.map((entry) => {
         if (entry.type !== types_1.ChangeType.BREAKING)
             return entry;
         const accepted = acceptedPaths.get(entry.path);
         return accepted ? { ...entry, acknowledged: true, reason: accepted.reason } : entry;
     });
+}
+function toJsonResult(diff, acceptedPaths) {
+    const changes = annotateChanges(diff, acceptedPaths);
     const summary = {
         breaking: changes.filter((change) => change.type === types_1.ChangeType.BREAKING && !change.acknowledged).length,
         acknowledgedBreaking: changes.filter((change) => change.type === types_1.ChangeType.BREAKING && change.acknowledged).length,

package/dist/core/config.d.ts

@@ -0,0 +1,24 @@
+import type { DiffResult } from "./diff.engine";
+import { ChangeType } from "./types";
+export interface SeverityOverride {
+    readonly pattern: string | RegExp;
+    readonly severity: ChangeType;
+}
+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[];
+}
+/** 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;
+/** 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;
+/**
+ * Applies project-wide policy before any per-instance override (`cliguard
+ * accept`/`deprecate`) gets a chance to run - an ignored or downgraded
+ * change simply isn't BREAKING by the time either of those look at it, so
+ * there's nothing left to accept or deprecate for it.
+ */
+export declare function applyConfig(diff: readonly DiffResult[], config: CliguardConfig): DiffResult[];

package/dist/core/config.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfigDisplayPath = getConfigDisplayPath;
+exports.configExists = configExists;
+exports.loadConfig = loadConfig;
+exports.applyConfig = applyConfig;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const types_1 = require("./types");
+const CANDIDATE_NAMES = ["cliguard.config.js", "cliguard.config.cjs"];
+function resolveConfigPath() {
+    for (const name of CANDIDATE_NAMES) {
+        const path = (0, path_1.join)(process.cwd(), name);
+        if ((0, fs_1.existsSync)(path))
+            return path;
+    }
+    return null;
+}
+/** 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()`. */
+function getConfigDisplayPath() {
+    const path = resolveConfigPath();
+    return path ? (0, path_1.relative)(process.cwd(), path).split("\\").join("/") : CANDIDATE_NAMES[0];
+}
+function configExists() {
+    return resolveConfigPath() !== null;
+}
+const VALID_SEVERITIES = [
+    types_1.ChangeType.BREAKING,
+    types_1.ChangeType.ADDITIVE,
+    types_1.ChangeType.PATCH,
+];
+function validateConfig(raw, displayPath) {
+    if (raw === null || typeof raw !== "object") {
+        throw new Error(`cliguard: ${displayPath} must export an object (module.exports = {...}).`);
+    }
+    const config = raw;
+    if (config.ignore !== undefined) {
+        if (!Array.isArray(config.ignore) ||
+            !config.ignore.every((entry) => typeof entry === "string" || entry instanceof RegExp)) {
+            throw new Error(`cliguard: ${displayPath}'s "ignore" must be an array of strings/RegExp.`);
+        }
+    }
+    if (config.severityOverrides !== undefined) {
+        if (!Array.isArray(config.severityOverrides)) {
+            throw new Error(`cliguard: ${displayPath}'s "severityOverrides" must be an array.`);
+        }
+        for (const entry of config.severityOverrides) {
+            const override = entry;
+            const patternOk = typeof override.pattern === "string" || override.pattern instanceof RegExp;
+            const severityOk = typeof override.severity === "string" && VALID_SEVERITIES.includes(override.severity);
+            if (!patternOk || !severityOk) {
+                throw new Error(`cliguard: ${displayPath}'s "severityOverrides" entries must look like ` +
+                    `{ pattern: string | RegExp, severity: "BREAKING" | "ADDITIVE" | "PATCH" } - got ${JSON.stringify(entry)}.`);
+            }
+        }
+    }
+    return config;
+}
+/** 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();
+    if (!path)
+        return {};
+    const displayPath = getConfigDisplayPath();
+    let raw;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports -- a config file is plain CommonJS by design, same convention as eslint.config.js/jest.config.js
+        raw = require(path);
+    }
+    catch (error) {
+        throw new Error(`cliguard: failed to load ${displayPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return validateConfig(raw, displayPath);
+}
+/** Glob-lite: `*` matches any run of characters, everything else is matched literally - just enough to write "root -> * -> option[--debug]" without a full glob dependency for one wildcard character. */
+function matchesGlob(pattern, path) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`).test(path);
+}
+function matches(pattern, path) {
+    return pattern instanceof RegExp ? pattern.test(path) : matchesGlob(pattern, path);
+}
+/**
+ * Applies project-wide policy before any per-instance override (`cliguard
+ * accept`/`deprecate`) gets a chance to run - an ignored or downgraded
+ * change simply isn't BREAKING by the time either of those look at it, so
+ * there's nothing left to accept or deprecate for it.
+ */
+function applyConfig(diff, config) {
+    const ignore = config.ignore ?? [];
+    const overrides = config.severityOverrides ?? [];
+    if (ignore.length === 0 && overrides.length === 0)
+        return diff;
+    return diff
+        .filter((entry) => !ignore.some((pattern) => matches(pattern, entry.path)))
+        .map((entry) => {
+        const override = overrides.find((candidate) => matches(candidate.pattern, entry.path));
+        if (!override || override.severity === entry.type)
+            return entry;
+        return {
+            ...entry,
+            type: override.severity,
+            message: `${entry.message} [config: severity overridden to ${override.severity}]`,
+        };
+    });
+}

package/dist/core/diff.engine.d.ts

@@ -5,6 +5,20 @@ export interface DiffResult {
     readonly path: string;
     /** Human-readable description of exactly what changed. */
     readonly message: string;
+    /** True only for "a command/option/argument was removed" - lets `cliguard deprecate` reclassify exactly this kind of BREAKING change, never any other kind at the same path. */
+    readonly removal?: true;
+}
+export interface CompareOptions {
+    /**
+     * Enables extra rules for changes that are currently silent (no diff
+     * entry at all) but can still break an existing caller - today, only a
+     * pure reorder of a command's positional arguments (same names, same
+     * required/variadic shape, different sequence), which the default,
+     * name-indexed comparison can't see since it never looks at position.
+     * Off by default so existing callers/CI configs keep today's behavior
+     * exactly - this is opt-in stricter enforcement, not a bug fix.
+     */
+    readonly strict?: boolean;
 }
 /**
  * Compares two Contracts and returns every difference between them,
@@ -14,7 +28,38 @@ export interface DiffResult {
  * either contract. `capturedAt` is intentionally never read.
  */
 export declare class DiffEngine {
-    compare(oldContract: Contract, newContract: Contract): DiffResult[];
+    compare(oldContract: Contract, newContract: Contract, options?: CompareOptions): DiffResult[];
+    /**
+     * Every valid DiffResult.path reachable from a Contract's root - the
+     * same path shapes `compareCommands`/`compareOptions`/`compareArguments`
+     * build ("root", "root -> build", "root -> build -> option[--target]",
+     * "root -> build -> argument[<file>]"). Used by `cliguard deprecate` to
+     * validate a path actually exists in the current contract before
+     * recording it, without duplicating the path-building logic here.
+     */
+    collectPaths(contract: Contract): Set<string>;
+    private walkCommand;
+    /**
+     * Every DiffResult.path whose own description contains `marker` - a
+     * command/option/argument the target CLI's own author has marked this
+     * way is signaling "not stable yet" right at the point where it's
+     * declared (inspired by `buf`'s `ignore_unstable_packages`), rather
+     * than through a separately maintained ignore list
+     * (`cliguard.config.js`) that can silently drift out of sync as flags
+     * get renamed, removed, or re-added under a different name.
+     */
+    collectUnstablePaths(contract: Contract, marker: string): Set<string>;
+    private walkUnstable;
+    /**
+     * Reclassifies a BREAKING change as PATCH when either side of the diff
+     * marks that path unstable - checking both the old *and* new contract
+     * matters because a removal only exists in the old one (the entry is
+     * simply gone from the new tree) while an added-then-changed entry only
+     * exists in the new one. `marker` defaults to `[unstable]`; every other
+     * kind of change (ADDITIVE, PATCH) is already non-blocking and left
+     * untouched either way.
+     */
+    applyUnstableMarkers(diff: readonly DiffResult[], oldContract: Contract, newContract: Contract, marker?: string): DiffResult[];
     private compareCommands;
     private compareSubcommands;
     /** CAC's default command (declared with no leading name, e.g. `cli.command("[...files]", ...)`) has name === "" - a blank path segment reads as a typo, not a real command. */
@@ -22,6 +67,16 @@ export declare class DiffEngine {
     private compareOptions;
     private compareOption;
     private compareArguments;
+    /**
+     * `--strict`-only: positional arguments are matched by name everywhere
+     * above, so a pure reorder (same names, same shape, different sequence)
+     * produces no diff at all under the default rules - but position is
+     * exactly what a caller passing values positionally relies on, so it's
+     * a real, silent break. Only fires when the two argument lists are the
+     * same *set* of names (any actual add/remove is already reported by the
+     * per-name loop above; this would just be redundant noise on top of it).
+     */
+    private compareArgumentOrder;
     private compareArgument;
     /** Shared by command aliases and option aliases - the rules are identical for both. */
     private compareAliases;