cliguard 0.5.0 → 0.7.0

package/dist/core/types.d.ts

@@ -51,6 +51,40 @@ export interface Contract {
     readonly capturedAt: string;
     readonly root: CommandContract;
 }
+/**
+ * A specific BREAKING change the maintainer has deliberately accepted -
+ * written by `cliguard accept` and committed to `.cliguard/accepted-breaks.json`
+ * so the decision is auditable in the repo, not a silent CLI flag. `check`
+ * matches these against a diff's `DiffResult.path` and stops counting a
+ * match toward its exit code, while still showing it in the output.
+ */
+export interface AcceptedBreak {
+    /** Must equal the DiffResult.path of the breaking change being accepted, e.g. "root -> build -> option[--target]". */
+    readonly path: string;
+    /** Why this break is intentional - required, never blank, shown alongside the change. */
+    readonly reason: string;
+    /** 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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cliguard",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Snapshot-tests your CLI's contract (commands, flags, defaults) so you never ship a breaking change by accident.",
   "keywords": [
     "cli",
@@ -24,6 +24,15 @@
   "bin": {
     "cliguard": "dist/bin.js"
   },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist"
   ],