cliguard 0.5.0 → 0.7.0

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;

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,6 +1,44 @@
-import type { 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. */
+export declare function getAcceptedBreaksDisplayPath(): string;
 export declare function contractExists(): boolean;
 export declare function readContract(): Contract;
 export declare function writeContract(contract: Contract): void;
+/**
+ * Reads a Contract from an arbitrary path, not the committed
+ * `.cliguard/contract.json` - for `cliguard diff <a> <b>`, comparing two
+ * contract files directly (e.g. two tags' committed contracts pulled via
+ * `git show`) without running any real CLI. `displayPath` is what error
+ * messages name; defaults to `path` itself since a caller-supplied path is
+ * 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

@@ -1,16 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getContractDisplayPath = getContractDisplayPath;
+exports.getAcceptedBreaksDisplayPath = getAcceptedBreaksDisplayPath;
 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("/");
 }
+/** 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 contractExists() {
     return (0, fs_1.existsSync)(CONTRACT_PATH);
 }
@@ -39,3 +61,153 @@ 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");
 }
+/**
+ * Reads a Contract from an arbitrary path, not the committed
+ * `.cliguard/contract.json` - for `cliguard diff <a> <b>`, comparing two
+ * contract files directly (e.g. two tags' committed contracts pulled via
+ * `git show`) without running any real CLI. `displayPath` is what error
+ * messages name; defaults to `path` itself since a caller-supplied path is
+ * already about as displayable as it gets.
+ */
+function readContractFile(path, displayPath = path) {
+    if (!(0, fs_1.existsSync)(path)) {
+        throw new Error(`cliguard: no such file: "${displayPath}".`);
+    }
+    const raw = (0, fs_1.readFileSync)(path, "utf-8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        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))
+        return [];
+    const raw = (0, fs_1.readFileSync)(ACCEPTED_BREAKS_PATH, "utf-8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        // 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}). ` +
+            "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");
+}
+/** 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.
+    }
+}