cliguard 0.6.0 → 0.7.0

package/dist/core/diff.engine.js

@@ -10,7 +10,7 @@ const types_1 = require("./types");
  * either contract. `capturedAt` is intentionally never read.
  */
 class DiffEngine {
-    compare(oldContract, newContract) {
+    compare(oldContract, newContract, options = {}) {
         const results = [];
         if (oldContract.adapter !== newContract.adapter) {
             results.push({
@@ -26,10 +26,90 @@ class DiffEngine {
                 message: `Contract format version changed from ${oldContract.contractVersion} to ${newContract.contractVersion}.`,
             });
         }
-        results.push(...this.compareCommands(oldContract.root, newContract.root, "root"));
+        results.push(...this.compareCommands(oldContract.root, newContract.root, "root", options));
         return results;
     }
-    compareCommands(oldCmd, newCmd, path) {
+    /**
+     * 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) {
+        const paths = new Set();
+        this.walkCommand(contract.root, "root", paths);
+        return paths;
+    }
+    walkCommand(cmd, path, paths) {
+        paths.add(path);
+        for (const option of cmd.options) {
+            paths.add(`${path} -> option[--${option.name}]`);
+        }
+        for (const arg of cmd.arguments) {
+            paths.add(`${path} -> argument[<${arg.name}>]`);
+        }
+        for (const sub of cmd.subcommands) {
+            this.walkCommand(sub, `${path} -> ${this.commandLabel(sub.name)}`, paths);
+        }
+    }
+    /**
+     * 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, marker) {
+        const paths = new Set();
+        this.walkUnstable(contract.root, "root", marker, paths);
+        return paths;
+    }
+    walkUnstable(cmd, path, marker, paths) {
+        if (cmd.description.includes(marker))
+            paths.add(path);
+        for (const option of cmd.options) {
+            if (option.description.includes(marker))
+                paths.add(`${path} -> option[--${option.name}]`);
+        }
+        for (const arg of cmd.arguments) {
+            if (arg.description.includes(marker))
+                paths.add(`${path} -> argument[<${arg.name}>]`);
+        }
+        for (const sub of cmd.subcommands) {
+            this.walkUnstable(sub, `${path} -> ${this.commandLabel(sub.name)}`, marker, paths);
+        }
+    }
+    /**
+     * 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, oldContract, newContract, marker = "[unstable]") {
+        const unstable = new Set([
+            ...this.collectUnstablePaths(oldContract, marker),
+            ...this.collectUnstablePaths(newContract, marker),
+        ]);
+        if (unstable.size === 0)
+            return diff;
+        return diff.map((entry) => {
+            if (entry.type !== types_1.ChangeType.BREAKING || !unstable.has(entry.path))
+                return entry;
+            return {
+                ...entry,
+                type: types_1.ChangeType.PATCH,
+                message: `${entry.message} [unstable: exempt from breaking-change enforcement]`,
+            };
+        });
+    }
+    compareCommands(oldCmd, newCmd, path, options) {
         const results = [];
         if (oldCmd.description !== newCmd.description) {
             results.push({
@@ -40,11 +120,11 @@ class DiffEngine {
         }
         results.push(...this.compareAliases(oldCmd.aliases, newCmd.aliases, path, `command "${this.commandLabel(oldCmd.name)}"`));
         results.push(...this.compareOptions(oldCmd.options, newCmd.options, path));
-        results.push(...this.compareArguments(oldCmd.arguments, newCmd.arguments, path));
-        results.push(...this.compareSubcommands(oldCmd.subcommands, newCmd.subcommands, path));
+        results.push(...this.compareArguments(oldCmd.arguments, newCmd.arguments, path, options));
+        results.push(...this.compareSubcommands(oldCmd.subcommands, newCmd.subcommands, path, options));
         return results;
     }
-    compareSubcommands(oldSubs, newSubs, path) {
+    compareSubcommands(oldSubs, newSubs, path, options) {
         const results = [];
         const oldByName = this.indexByName(oldSubs);
         const newByName = this.indexByName(newSubs);
@@ -56,10 +136,11 @@ class DiffEngine {
                     type: types_1.ChangeType.BREAKING,
                     path: childPath,
                     message: `Command "${this.commandLabel(name)}" was removed.`,
+                    removal: true,
                 });
                 continue;
             }
-            results.push(...this.compareCommands(oldSub, newSub, childPath));
+            results.push(...this.compareCommands(oldSub, newSub, childPath, options));
         }
         for (const name of newByName.keys()) {
             if (oldByName.has(name))
@@ -88,6 +169,7 @@ class DiffEngine {
                     type: types_1.ChangeType.BREAKING,
                     path: optionPath,
                     message: `Option "--${name}" was removed.`,
+                    removal: true,
                 });
                 continue;
             }
@@ -162,7 +244,7 @@ class DiffEngine {
         }
         return results;
     }
-    compareArguments(oldArgs, newArgs, path) {
+    compareArguments(oldArgs, newArgs, path, options) {
         const results = [];
         const oldByName = this.indexByName(oldArgs);
         const newByName = this.indexByName(newArgs);
@@ -174,6 +256,7 @@ class DiffEngine {
                     type: types_1.ChangeType.BREAKING,
                     path: argPath,
                     message: `Argument "<${name}>" was removed.`,
+                    removal: true,
                 });
                 continue;
             }
@@ -198,8 +281,40 @@ class DiffEngine {
                 });
             }
         }
+        if (options.strict) {
+            results.push(...this.compareArgumentOrder(oldArgs, newArgs, path));
+        }
         return results;
     }
+    /**
+     * `--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).
+     */
+    compareArgumentOrder(oldArgs, newArgs, path) {
+        if (oldArgs.length !== newArgs.length)
+            return [];
+        const oldNames = oldArgs.map((arg) => arg.name);
+        const newNames = newArgs.map((arg) => arg.name);
+        if (oldNames.join("") === newNames.join(""))
+            return [];
+        const sameSet = new Set(oldNames).size === new Set(newNames).size &&
+            oldNames.every((name) => newNames.includes(name));
+        if (!sameSet)
+            return [];
+        return [
+            {
+                type: types_1.ChangeType.BREAKING,
+                path,
+                message: `[strict] Argument order changed: was <${oldNames.join(">, <")}>, ` +
+                    `now <${newNames.join(">, <")}>. Existing positional invocations may now bind values to the wrong argument.`,
+            },
+        ];
+    }
     compareArgument(oldArg, newArg, path) {
         const results = [];
         const label = `Argument "<${oldArg.name}>"`;

package/dist/core/report-formats.d.ts

@@ -0,0 +1,44 @@
+import { ChangeType } from "./types";
+/** The same annotated shape `check --json`/`diff --json` already produce - a BREAKING entry matched by `cliguard accept` gains `acknowledged`/`reason`. */
+export interface ReportChange {
+    readonly type: ChangeType;
+    readonly path: string;
+    readonly message: string;
+    readonly acknowledged?: boolean;
+    readonly reason?: string;
+}
+/**
+ * One <testsuite> named "cliguard", one <testcase> per changed path - the
+ * same shape ESLint/ruff's own JUnit reporters use, understood natively by
+ * Jenkins, CircleCI, Azure DevOps, and GitLab's own "JUnit report" widget.
+ * Only an unacknowledged BREAKING entry gets a <failure> child; ADDITIVE,
+ * PATCH, and an acknowledged BREAKING all report as a passing testcase,
+ * matching exactly which entries fail `check`'s own exit code.
+ *
+ * DiffResult.path can itself contain `<`/`>` (an argument path looks like
+ * "root -> build -> argument[<file>]") - every value here goes through
+ * escapeXml, not just the message, or this would emit invalid XML on the
+ * very first CLI that has a positional argument.
+ */
+export declare function toJUnitXml(changes: readonly ReportChange[]): string;
+/**
+ * GitLab's Code Quality report format (`artifacts: reports: codequality`),
+ * surfaced as inline annotations on a merge request. The format is
+ * inherently file+line shaped - a cliguard change has neither, so every
+ * entry points at the committed contract file (line 1) and puts the real
+ * location in the description instead. A best-effort mapping, not a
+ * perfect fit for what GitLab expects, but it gets cliguard's diff into
+ * GitLab's own MR widget with zero extra infra on GitLab's side.
+ */
+export declare function toGitLabCodeQuality(changes: readonly ReportChange[], contractPath: string): string;
+/**
+ * reviewdog's own Diagnostic Format, one JSON object per line (rdjsonl) -
+ * NOT a JSON array, reviewdog reads it as a stream. Piping this into
+ * `reviewdog -f=rdjsonl -reporter=<...>` hands off posting the diff to
+ * whichever platform reviewdog already has a reporter for (GitHub,
+ * GitLab, Bitbucket, a local checkstyle-style report), instead of
+ * cliguard maintaining a bespoke reporter per platform itself. Same
+ * file+line limitation and same fallback (the contract file, line 1) as
+ * `toGitLabCodeQuality` - reviewdog's format is just as file-shaped.
+ */
+export declare function toRdjsonl(changes: readonly ReportChange[], contractPath: string): string;

package/dist/core/report-formats.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJUnitXml = toJUnitXml;
+exports.toGitLabCodeQuality = toGitLabCodeQuality;
+exports.toRdjsonl = toRdjsonl;
+const crypto_1 = require("crypto");
+const types_1 = require("./types");
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * One <testsuite> named "cliguard", one <testcase> per changed path - the
+ * same shape ESLint/ruff's own JUnit reporters use, understood natively by
+ * Jenkins, CircleCI, Azure DevOps, and GitLab's own "JUnit report" widget.
+ * Only an unacknowledged BREAKING entry gets a <failure> child; ADDITIVE,
+ * PATCH, and an acknowledged BREAKING all report as a passing testcase,
+ * matching exactly which entries fail `check`'s own exit code.
+ *
+ * DiffResult.path can itself contain `<`/`>` (an argument path looks like
+ * "root -> build -> argument[<file>]") - every value here goes through
+ * escapeXml, not just the message, or this would emit invalid XML on the
+ * very first CLI that has a positional argument.
+ */
+function toJUnitXml(changes) {
+    const failures = changes.filter((change) => change.type === types_1.ChangeType.BREAKING && !change.acknowledged).length;
+    const testcases = changes.map((change) => {
+        const name = escapeXml(change.path);
+        const message = escapeXml(change.message);
+        const isFailure = change.type === types_1.ChangeType.BREAKING && !change.acknowledged;
+        if (!isFailure) {
+            return (`    <testcase name="${name}" classname="cliguard">\n` +
+                `      <system-out>${message}</system-out>\n` +
+                `    </testcase>`);
+        }
+        return (`    <testcase name="${name}" classname="cliguard">\n` +
+            `      <failure message="${message}" type="BREAKING">${message}</failure>\n` +
+            `    </testcase>`);
+    });
+    return (`<?xml version="1.0" encoding="UTF-8"?>\n` +
+        `<testsuites>\n` +
+        `  <testsuite name="cliguard" tests="${changes.length}" failures="${failures}">\n` +
+        (testcases.length > 0 ? `${testcases.join("\n")}\n` : "") +
+        `  </testsuite>\n` +
+        `</testsuites>\n`);
+}
+function severityFor(change) {
+    if (change.type === types_1.ChangeType.BREAKING)
+        return change.acknowledged ? "info" : "blocker";
+    if (change.type === types_1.ChangeType.PATCH)
+        return "minor";
+    return "info"; // ADDITIVE
+}
+/**
+ * GitLab's Code Quality report format (`artifacts: reports: codequality`),
+ * surfaced as inline annotations on a merge request. The format is
+ * inherently file+line shaped - a cliguard change has neither, so every
+ * entry points at the committed contract file (line 1) and puts the real
+ * location in the description instead. A best-effort mapping, not a
+ * perfect fit for what GitLab expects, but it gets cliguard's diff into
+ * GitLab's own MR widget with zero extra infra on GitLab's side.
+ */
+function toGitLabCodeQuality(changes, contractPath) {
+    const issues = changes.map((change) => ({
+        description: `[${change.type}] ${change.path}: ${change.message}`,
+        check_name: `cliguard/${change.type.toLowerCase()}`,
+        fingerprint: (0, crypto_1.createHash)("md5").update(`${change.path}|${change.message}`).digest("hex"),
+        severity: severityFor(change),
+        location: { path: contractPath, lines: { begin: 1 } },
+    }));
+    return JSON.stringify(issues, null, 2);
+}
+function rdjsonlSeverityFor(change) {
+    if (change.type === types_1.ChangeType.BREAKING)
+        return change.acknowledged ? "INFO" : "ERROR";
+    if (change.type === types_1.ChangeType.PATCH)
+        return "WARNING";
+    return "INFO"; // ADDITIVE
+}
+/**
+ * reviewdog's own Diagnostic Format, one JSON object per line (rdjsonl) -
+ * NOT a JSON array, reviewdog reads it as a stream. Piping this into
+ * `reviewdog -f=rdjsonl -reporter=<...>` hands off posting the diff to
+ * whichever platform reviewdog already has a reporter for (GitHub,
+ * GitLab, Bitbucket, a local checkstyle-style report), instead of
+ * cliguard maintaining a bespoke reporter per platform itself. Same
+ * file+line limitation and same fallback (the contract file, line 1) as
+ * `toGitLabCodeQuality` - reviewdog's format is just as file-shaped.
+ */
+function toRdjsonl(changes, contractPath) {
+    return changes
+        .map((change) => JSON.stringify({
+        message: `[${change.type}] ${change.message}`,
+        location: { path: contractPath, range: { start: { line: 1, column: 1 } } },
+        severity: rdjsonlSeverityFor(change),
+        code: { value: change.path },
+    }))
+        .join("\n");
+}

package/dist/core/storage.d.ts

@@ -1,4 +1,4 @@
-import type { AcceptedBreak, Contract } from "./types";
+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;
 /** Accepted-breaks path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
@@ -15,6 +15,30 @@ export declare function writeContract(contract: Contract): void;
  * already about as displayable as it gets.
  */
 export declare function readContractFile(path: string, displayPath?: string): Contract;
+/**
+ * Reads the committed contract as it existed at a git ref (a branch, tag,
+ * or commit sha) instead of the working tree - `cliguard check <entry>
+ * --against origin/main` needs no local `.cliguard/contract.json` at all,
+ * closing the CI-friction gap `readContractFile`'s own doc comment above
+ * already names as the manual workaround (`git show <ref>:... > old.json`
+ * piped into `cliguard diff`).
+ */
+export declare function readContractAtRef(ref: string): Contract;
 /** Unlike readContract, a missing file is normal (most projects never accept a break) - returns [] rather than throwing. */
 export declare function readAcceptedBreaks(): AcceptedBreak[];
 export declare function writeAcceptedBreaks(breaks: readonly AcceptedBreak[]): void;
+/** Deprecations path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
+export declare function getDeprecationsDisplayPath(): 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;
+/** 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;
+/** Never called when ciWorkflowExists() is true - `init --with-ci` checks first so a hand-edited workflow is never clobbered. */
+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;
+/** 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

@@ -6,12 +6,25 @@ exports.contractExists = contractExists;
 exports.readContract = readContract;
 exports.writeContract = writeContract;
 exports.readContractFile = readContractFile;
+exports.readContractAtRef = readContractAtRef;
 exports.readAcceptedBreaks = readAcceptedBreaks;
 exports.writeAcceptedBreaks = writeAcceptedBreaks;
+exports.getDeprecationsDisplayPath = getDeprecationsDisplayPath;
+exports.readDeprecations = readDeprecations;
+exports.writeDeprecations = writeDeprecations;
+exports.getCiWorkflowDisplayPath = getCiWorkflowDisplayPath;
+exports.ciWorkflowExists = ciWorkflowExists;
+exports.writeCiWorkflow = writeCiWorkflow;
+exports.getHookDisplayPath = getHookDisplayPath;
+exports.hookExists = hookExists;
+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 CI_WORKFLOW_PATH = (0, path_1.join)(process.cwd(), ".github", "workflows", "cliguard.yml");
 /** 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("/");
@@ -69,6 +82,40 @@ function readContractFile(path, displayPath = path) {
         throw new Error(`cliguard: "${displayPath}" is not valid JSON (${reason}).`);
     }
 }
+/**
+ * Reads the committed contract as it existed at a git ref (a branch, tag,
+ * or commit sha) instead of the working tree - `cliguard check <entry>
+ * --against origin/main` needs no local `.cliguard/contract.json` at all,
+ * closing the CI-friction gap `readContractFile`'s own doc comment above
+ * already names as the manual workaround (`git show <ref>:... > old.json`
+ * piped into `cliguard diff`).
+ */
+function readContractAtRef(ref) {
+    const contractGitPath = getContractDisplayPath();
+    let raw;
+    try {
+        raw = (0, child_process_1.execFileSync)("git", ["show", `${ref}:${contractGitPath}`], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (error) {
+        const stderr = error && typeof error === "object" && "stderr" in error
+            ? String(error.stderr).trim()
+            : undefined;
+        throw new Error(`cliguard: couldn't read "${contractGitPath}" at ref "${ref}"` +
+            (stderr ? ` (${stderr})` : ".") +
+            ` Make sure "${ref}" exists and has a contract committed at that path - ` +
+            `a shallow clone may need \`git fetch --deepen\` or \`git fetch origin ${ref}\` first.`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`cliguard: "${contractGitPath}" at ref "${ref}" is not valid JSON (${reason}).`);
+    }
+}
 /** Unlike readContract, a missing file is normal (most projects never accept a break) - returns [] rather than throwing. */
 function readAcceptedBreaks() {
     if (!(0, fs_1.existsSync)(ACCEPTED_BREAKS_PATH))
@@ -90,3 +137,77 @@ 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");
 }
+/** 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("/");
+}
+/** 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))
+        return [];
+    const raw = (0, fs_1.readFileSync)(DEPRECATIONS_PATH, "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}). ` +
+            "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");
+}
+/** CI workflow path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
+function getCiWorkflowDisplayPath() {
+    return (0, path_1.relative)(process.cwd(), CI_WORKFLOW_PATH).split("\\").join("/");
+}
+function ciWorkflowExists() {
+    return (0, fs_1.existsSync)(CI_WORKFLOW_PATH);
+}
+/** Never called when ciWorkflowExists() is true - `init --with-ci` checks first so a hand-edited workflow is never clobbered. */
+function writeCiWorkflow(content) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(CI_WORKFLOW_PATH), { recursive: true });
+    (0, fs_1.writeFileSync)(CI_WORKFLOW_PATH, content, "utf-8");
+}
+/**
+ * `git rev-parse --git-path hooks` rather than a hardcoded `.git/hooks` -
+ * correct even when a repo sets `core.hooksPath`, is a worktree (`.git` is
+ * a file, not a directory, pointing elsewhere), or is a submodule.
+ */
+function resolveHooksDir() {
+    let out;
+    try {
+        out = (0, child_process_1.execFileSync)("git", ["rev-parse", "--git-path", "hooks"], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+    }
+    catch {
+        throw new Error("cliguard: not a git repository (or git isn't installed) - install-hook needs one.");
+    }
+    return (0, path_1.resolve)(process.cwd(), out);
+}
+/** Hook path relative to cwd, normalized to forward slashes - display only, never used for I/O. */
+function getHookDisplayPath(hookName) {
+    return (0, path_1.relative)(process.cwd(), (0, path_1.join)(resolveHooksDir(), hookName)).split("\\").join("/");
+}
+function hookExists(hookName) {
+    return (0, fs_1.existsSync)((0, path_1.join)(resolveHooksDir(), hookName));
+}
+/** 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);
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(hookPath), { recursive: true });
+    (0, fs_1.writeFileSync)(hookPath, content, "utf-8");
+    try {
+        (0, fs_1.chmodSync)(hookPath, 0o755);
+    }
+    catch {
+        // Best-effort: Windows filesystems mostly ignore the Unix exec bit
+        // anyway, and Git for Windows runs hooks via its own shebang handling
+        // regardless - a failed chmod here shouldn't fail the whole command.
+    }
+}

package/dist/core/types.d.ts

@@ -66,6 +66,25 @@ export interface AcceptedBreak {
     /** ISO-8601 timestamp of when `cliguard accept` recorded this. */
     readonly acceptedAt: string;
 }
+/**
+ * A command/option/argument the maintainer has scheduled for removal ahead
+ * of time - written by `cliguard deprecate` and committed to
+ * `.cliguard/deprecations.json`. Unlike `AcceptedBreak` (which forgives a
+ * break that already happened), this is recorded *before* the removal:
+ * `check`/`diff` reclassify a matching BREAKING removal as PATCH instead
+ * of failing the build, but only because the deprecation was announced in
+ * advance - removing something with no prior `deprecate` still fails.
+ */
+export interface Deprecation {
+    /** Must equal the DiffResult.path of the eventual removal, e.g. "root -> build -> option[--target]". */
+    readonly path: string;
+    /** When this is expected to actually go away - a version ("2.0.0") or a date. Informational, never enforced by cliguard itself. */
+    readonly removeBy: string;
+    /** Why this is being deprecated - optional, shown alongside the change once it's removed. */
+    readonly reason?: string;
+    /** ISO-8601 timestamp of when `cliguard deprecate` recorded this. */
+    readonly deprecatedAt: string;
+}
 /** Severity of a single detected difference between two contracts. */
 export declare enum ChangeType {
     /** Removes or narrows something a caller may already depend on. */

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+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 { CommanderAdapter } from "./adapters/commander.adapter";
+export { YargsAdapter } from "./adapters/yargs.adapter";
+export { adapters, resolveAdapter } from "./adapters/registry";
+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 { 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";
+/**
+ * Loads `entryPath` and extracts its full command surface as a Contract -
+ * the same extraction `cliguard init`/`check`/`update` run, without going
+ * through a subprocess. `adapterName` defaults to "commander", matching
+ * the CLI's own default.
+ */
+export declare function extractContract(entryPath: string, adapterName?: string): Promise<Contract>;
+/**
+ * Compares two Contracts and returns every difference, classified
+ * BREAKING/ADDITIVE/PATCH - the exact same comparison `cliguard check`/`diff`
+ * run. Framework-agnostic: neither Contract needs to have come from
+ * `extractContract`, so this also works against contracts read from disk
+ * 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"]. */
+export declare function listAdapters(): string[];

package/dist/index.js

@@ -0,0 +1,66 @@
+"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.extractContract = extractContract;
+exports.compareContracts = compareContracts;
+exports.listAdapters = listAdapters;
+/**
+ * Programmatic entry point - `import { extractContract, compareContracts } from "cliguard"`.
+ * Everything here is the same code `bin.ts` itself calls; this file only
+ * adds the two convenience wrappers (`extractContract`/`compareContracts`)
+ * and re-exports the pieces a caller embedding cliguard in their own
+ * build script, monorepo tooling, or bot would need - never a second
+ * implementation of anything.
+ */
+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 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");
+Object.defineProperty(exports, "YargsAdapter", { enumerable: true, get: function () { return yargs_adapter_1.YargsAdapter; } });
+var registry_2 = require("./adapters/registry");
+Object.defineProperty(exports, "adapters", { enumerable: true, get: function () { return registry_2.adapters; } });
+Object.defineProperty(exports, "resolveAdapter", { enumerable: true, get: function () { return registry_2.resolveAdapter; } });
+var config_1 = require("./core/config");
+Object.defineProperty(exports, "applyConfig", { enumerable: true, get: function () { return config_1.applyConfig; } });
+Object.defineProperty(exports, "configExists", { enumerable: true, get: function () { return config_1.configExists; } });
+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 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; } });
+Object.defineProperty(exports, "toRdjsonl", { enumerable: true, get: function () { return report_formats_1.toRdjsonl; } });
+var types_1 = require("./core/types");
+Object.defineProperty(exports, "ChangeType", { enumerable: true, get: function () { return types_1.ChangeType; } });
+const diffEngine = new diff_engine_1.DiffEngine();
+/**
+ * Loads `entryPath` and extracts its full command surface as a Contract -
+ * the same extraction `cliguard init`/`check`/`update` run, without going
+ * through a subprocess. `adapterName` defaults to "commander", matching
+ * the CLI's own default.
+ */
+async function extractContract(entryPath, adapterName = "commander") {
+    // Deliberately `async` rather than returning resolveAdapter(...).extract(...)
+    // directly - resolveAdapter throws synchronously on an unknown name, and
+    // without `async` that throw would escape as a synchronous exception
+    // instead of a rejected Promise, breaking the "this always returns a
+    // Promise" contract the function's own return type promises.
+    return (0, registry_1.resolveAdapter)(adapterName).extract(entryPath);
+}
+/**
+ * Compares two Contracts and returns every difference, classified
+ * BREAKING/ADDITIVE/PATCH - the exact same comparison `cliguard check`/`diff`
+ * run. Framework-agnostic: neither Contract needs to have come from
+ * `extractContract`, so this also works against contracts read from disk
+ * or a git ref by the caller's own code.
+ */
+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"]. */
+function listAdapters() {
+    return Object.keys(registry_1.adapters);
+}