repo-contract 0.3.0 → 0.3.2

package/dist/.dts/presets/shared/read-json-report.d.ts

@@ -0,0 +1,33 @@
+import type { PolicyResult } from "../../types.js";
+/** The report, already JSON-parsed and narrowed to `T`, or the fail `PolicyResult` to return verbatim when reading or parsing it failed. See `readJsonReport`. */
+type ReadJsonReportResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly result: PolicyResult;
+};
+/**
+ * Reads and JSON-parses a report a tool wrote to disk rather than printing to stdout -- the "read,
+ * fail with one rationale if the read itself fails, fail with a different rationale if the JSON is
+ * invalid" shape shared by every preset whose tool has no stdout JSON mode (jscpd,
+ * markdownlint-cli2, secretlint). Each failure takes its own caller-supplied rationale rather than a
+ * generic shared message, since a missing report and invalid JSON usually point a consumer at a
+ * different fix (a misconfigured reporter/output flag vs. a genuinely broken tool run), and each
+ * tool's own advice differs (markdownlint's own read-failure rationale, for instance, names the
+ * specific config field to check).
+ *
+ * Takes the read itself as a thunk (`readRaw`), rather than a `path` this function reads from
+ * directly, so every call site's own `readFile(LITERAL_PATH, "utf8")` stays written as a literal
+ * argument in the caller's own file -- required by this repo's `security/detect-non-literal-fs-filename`
+ * policy, which forbids suppressing that rule outright (see policy-config.ts's `eslint.rules["security/*"]`)
+ * and would otherwise flag a `path: string` function parameter threaded into `readFile` here as
+ * non-literal.
+ * @param readRaw - reads the report's raw text (typically `() => readFile(REPORT_PATH, "utf8")`).
+ * @param onReadFailed - the rationale to fail with if `readRaw` rejects.
+ * @param onParseFailed - the rationale to fail with if the read text isn't valid JSON.
+ * @returns `{ ok: true, value }` with the parsed JSON narrowed to `T`, or `{ ok: false, result }` with the fail `PolicyResult` to return verbatim.
+ */
+export declare function readJsonReport<T>(readRaw: () => Promise<string>, onReadFailed: string, onParseFailed: string): Promise<ReadJsonReportResult<T>>;
+export {};
+//# sourceMappingURL=read-json-report.d.ts.map

package/dist/.dts/presets/shared/read-json-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-json-report.d.ts","sourceRoot":"","sources":["../../../../src/presets/shared/read-json-report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAElD,kKAAkK;AAClK,KAAK,oBAAoB,CAAC,CAAC,IACzB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAA;AAElG;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EAC9B,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAclC"}

package/dist/.dts/presets/shared/terminal-status.d.ts

@@ -0,0 +1,25 @@
+import type { CheckEvidence, PolicyResult } from "../../types.js";
+/**
+ * The guard every preset needs immediately after `checkDependencyInstalled`
+ * and before its own pass/fail logic: a check whose process did not run to a
+ * normal exit on its own -- it timed out, was aborted via `options.signal`,
+ * was killed by a host `SIGINT`/`SIGTERM`, received an external signal, or
+ * failed to spawn for a reason other than a missing executable -- has a
+ * `null` `exitCode` and only whatever partial output the tool managed before
+ * termination. Interpreting that with an exit-code comparison or a JSON
+ * parse would present an operational failure to the consumer as a fabricated
+ * tool-specific verdict ("TypeScript reported type errors (exit code null)",
+ * "ESLint output could not be parsed as JSON"). This reports the real
+ * terminal cause instead.
+ *
+ * `"completed"` returns `undefined` -- the process reached its own exit and
+ * the preset interprets the (possibly non-zero) exit code itself. The
+ * ENOENT `"spawn_error"` case is already handled by `checkDependencyInstalled`;
+ * this catches the remaining spawn failures (`EACCES`, `ENOEXEC`) that
+ * `missing-dependency.ts` documents as falling through.
+ * @param result - the check's raw execution evidence to inspect.
+ * @param toolName - the tool's own display name for the rationale (e.g. "ESLint", "TypeScript").
+ * @returns a fail `PolicyResult` describing the abnormal termination, or `undefined` if the process ran to its own exit and the caller should proceed.
+ */
+export declare function checkTerminatedAbnormally(result: CheckEvidence, toolName: string): PolicyResult | undefined;
+//# sourceMappingURL=terminal-status.d.ts.map

package/dist/.dts/presets/shared/terminal-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-status.d.ts","sourceRoot":"","sources":["../../../../src/presets/shared/terminal-status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAGjE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,GACf,YAAY,GAAG,SAAS,CAyC1B"}

package/dist/.dts/presets/shared/vitest-json-policy.d.ts

@@ -0,0 +1,20 @@
+import type { ParsedOutput, PolicyResult } from "../../types.js";
+/**
+ * Interprets Vitest's own `--reporter=json` output shape -- and nothing
+ * else. Shared between the `test` preset (a single, un-categorized
+ * `vitest run --reporter=json`) and this repository's own
+ * `test-unit`/`test-integration`/`test-property`/`test-e2e` checks, whose
+ * `run` splits tests into four mutually exclusive categories via
+ * scripts/run-test-category.mjs -- a repository-specific concern this
+ * function knows nothing about. Each of those four checks owns its own
+ * category-specific semantics on top of this evaluator; this function must
+ * stay narrowly scoped to "parse Vitest's JSON reporter shape," never grow
+ * into a general "testing policy" abstraction. A category's own
+ * `output.success === false` (vitest crashed / produced unparseable output)
+ * is kept distinct from a substantive test failure, exactly as every other
+ * preset in this package already does via `ParsedOutput.success`.
+ * @param output - the vitest check's parsed `--reporter=json` output to evaluate.
+ * @returns the pass/fail outcome and its rationale.
+ */
+export declare function evaluateVitestJsonPolicy(output: ParsedOutput<unknown> | undefined): PolicyResult;
+//# sourceMappingURL=vitest-json-policy.d.ts.map

package/dist/.dts/presets/shared/vitest-json-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest-json-policy.d.ts","sourceRoot":"","sources":["../../../../src/presets/shared/vitest-json-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAMhE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,SAAS,GAAG,YAAY,CAsEhG"}

package/dist/.dts/presets/stylelint.d.ts

@@ -0,0 +1,17 @@
+import type { CheckDefinitionConfig } from "../types.js";
+/** Options accepted by {@link stylelint}. */
+interface StylelintOptions {
+    /** Glob passed straight through to stylelint as its positional target. Defaults to `"**\/*.{css,scss}"` -- adjust it for your own stylesheet file extensions (e.g. `.less`, `.vue`, `.svelte`). */
+    readonly glob?: string;
+}
+/**
+ * CSS/SCSS lint via stylelint, using whatever stylelint config the
+ * consumer's own repository already has. `severity: "error"` blocks;
+ * `severity: "warning"` is reported but never blocks, matching how the
+ * `lint` preset treats ESLint's own severities.
+ * @param options - configuration for this check; see {@link StylelintOptions}.
+ * @returns the configured check.
+ */
+export declare function stylelint(options?: StylelintOptions): CheckDefinitionConfig;
+export {};
+//# sourceMappingURL=stylelint.d.ts.map

package/dist/.dts/presets/stylelint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stylelint.d.ts","sourceRoot":"","sources":["../../../src/presets/stylelint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAqBxD,6CAA6C;AAC7C,UAAU,gBAAgB;IACxB,mMAAmM;IACnM,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,qBAAqB,CAiE/E"}

package/dist/.dts/presets/test.d.ts

@@ -0,0 +1,4 @@
+import type { CheckDefinitionConfig } from "../types.js";
+/** Unit/integration test execution via Vitest, reading its JSON reporter output. */
+export declare const test: CheckDefinitionConfig;
+//# sourceMappingURL=test.d.ts.map

package/dist/.dts/presets/test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.d.ts","sourceRoot":"","sources":["../../../src/presets/test.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAKxD,oFAAoF;AACpF,eAAO,MAAM,IAAI,EAAE,qBAYlB,CAAA"}

package/dist/.dts/presets/typecheck.d.ts

@@ -0,0 +1,4 @@
+import type { CheckDefinitionConfig } from "../types.js";
+/** Type checking via `tsc --noEmit`. */
+export declare const typecheck: CheckDefinitionConfig;
+//# sourceMappingURL=typecheck.d.ts.map

package/dist/.dts/presets/typecheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typecheck.d.ts","sourceRoot":"","sources":["../../../src/presets/typecheck.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAKxD,wCAAwC;AACxC,eAAO,MAAM,SAAS,EAAE,qBAkBvB,CAAA"}

package/dist/.dts/run-repo-contract.d.ts

@@ -0,0 +1,38 @@
+import type { CheckSchema, Evidence, RepoContractConfig, RunRepoContractOptions, Verdict } from "./types.js";
+/**
+ * Executes every configured check, collects its evidence, optionally parses
+ * its output, evaluates every check's repository-owned policy against the
+ * complete evidence, and aggregates a verdict. Never calls `process.exit()`
+ * -- returns data; the caller decides what to do with `verdict.passed`.
+ *
+ * Structural configuration problems throw synchronously before any process
+ * spawns. Anything only discoverable by attempting execution (a missing
+ * binary, a bad `cwd`) becomes evidence on that check (`status:
+ * "spawn_error"`), never a throw. A policy function throwing or rejecting
+ * rejects this function's own returned promise (`PolicyThrewError`, or an
+ * `AggregateError` of them if more than one policy failed this way) --
+ * distinct from a policy that ran fine and simply returned a failure
+ * string. See `src/errors.ts` for the full distinction.
+ *
+ * Execution and policy evaluation are strictly phased: every check finishes
+ * running and every check's evidence is fully assembled before any policy
+ * is invoked (see specs/architecture.md) -- a policy can safely read
+ * `ctx.evidence` for any sibling check's result.
+ *
+ * Deliberately not declared `async`: validation runs and can throw before this function returns
+ * anything at all, so a config problem is a genuine synchronous exception to the caller (as
+ * documented above and on `InvalidRepoContractConfigError`/`InvalidCheckConfigError`/
+ * `DependencyDeclaredLaterError`) -- an `async function`'s body runs to its first `await` still
+ * inside the caller's own call stack, but any throw before that point is nonetheless converted by
+ * the language into a rejected `Promise`, never surfaced as a synchronous exception. Splitting
+ * validation out into this synchronous wrapper, with the rest of the work in the `async` function
+ * below, keeps the documented synchronous-throw guarantee actually true rather than aspirational.
+ * @param config - the repo-contract configuration to run: its checks, concurrency, and their policies
+ * @param options - run options; `options.checks` restricts execution to specific check ids, `options.signal` allows cancelling the run
+ * @returns the assembled `evidence` for every check together with the aggregated `verdict`
+ */
+export declare function runRepoContract<const TChecks extends CheckSchema>(config: RepoContractConfig<TChecks>, options?: RunRepoContractOptions): Promise<{
+    evidence: Evidence<TChecks>;
+    verdict: Verdict<TChecks>;
+}>;
+//# sourceMappingURL=run-repo-contract.d.ts.map

package/dist/.dts/run-repo-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-repo-contract.d.ts","sourceRoot":"","sources":["../../src/run-repo-contract.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,WAAW,EACX,QAAQ,EACR,kBAAkB,EAClB,sBAAsB,EACtB,OAAO,EACR,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,eAAe,CAAC,KAAK,CAAC,OAAO,SAAS,WAAW,EAC/D,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,EACnC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC,CAGrE"}

package/dist/.dts/standard-schema/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Hand-vendored from `@standard-schema/spec@1.1.0` (https://standardschema.dev), pinned
+ * 2026-09-04 -- see specs/decisions/0012-hand-vendored-standard-schema-support-for-optional-output-validation.md for why this is
+ * vendored rather than an installed dependency, and for the version-pin/re-diff process. Pure type
+ * declarations, zero runtime code -- assigning any real Zod/Valibot/ArkType (etc.) schema to this
+ * type costs nothing at runtime. Only `StandardSchemaV1` (validation) is vendored here -- the
+ * separate, optional `StandardJSONSchemaV1` (JSON Schema conversion) extension
+ * (https://standardschema.dev/json-schema) is out of scope; see the ADR.
+ *
+ * Upstream's `StandardSchemaV1.Props` actually extends a shared `StandardTypedV1.Props` base
+ * (`version`/`vendor`/`types`); this vendored copy inlines those fields directly into one flat
+ * interface, since repo-contract has no use for the shared base on its own -- structurally
+ * identical for any real schema object assigned to it. Re-diff against
+ * `@standard-schema/spec`'s published `dist/index.d.ts` if this file is ever touched.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+/** Namespaced members of {@link StandardSchemaV1}: `Props`, `Result`, `SuccessResult`, `FailureResult`, `Issue`, `PathSegment`, `Types`, `InferInput`, `InferOutput`. */
+export declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown, options?: Options) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** Options passable to `validate`. */
+    interface Options {
+        /** Explicit support for additional vendor-specific parameters, if needed. */
+        readonly libraryOptions?: Record<string, unknown> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** A falsy value for `issues` indicates success. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: readonly Issue[];
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: readonly (PropertyKey | PathSegment)[] | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/.dts/standard-schema/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/standard-schema/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;IAC/D,sCAAsC;IACtC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;CAC5D;AAED,yKAAyK;AAEzK,MAAM,CAAC,OAAO,WAAW,gBAAgB,CAAC;IACxC,gDAAgD;IAChD,UAAiB,KAAK,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;QACpD,0CAA0C;QAC1C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;QACnB,6CAA6C;QAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,sCAAsC;QACtC,QAAQ,CAAC,QAAQ,EAAE,CACjB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,OAAO,KACd,MAAM,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;QAC7C,iDAAiD;QACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;KAClD;IAED,sCAAsC;IACtC,UAAiB,OAAO;QACtB,6EAA6E;QAC7E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;KAC9D;IAED,qDAAqD;IACrD,KAAY,MAAM,CAAC,MAAM,IAAI,aAAa,CAAC,MAAM,CAAC,GAAG,aAAa,CAAA;IAElE,mDAAmD;IACnD,UAAiB,aAAa,CAAC,MAAM;QACnC,8BAA8B;QAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;QACtB,oDAAoD;QACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAC5B;IAED,gDAAgD;IAChD,UAAiB,aAAa;QAC5B,uCAAuC;QACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAA;KAClC;IAED,iDAAiD;IACjD,UAAiB,KAAK;QACpB,sCAAsC;QACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;QACxB,qCAAqC;QACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,WAAW,CAAC,EAAE,GAAG,SAAS,CAAA;KACnE;IAED,+CAA+C;IAC/C,UAAiB,WAAW;QAC1B,2CAA2C;QAC3C,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;KAC1B;IAED,2CAA2C;IAC3C,UAAiB,KAAK,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;QACpD,oCAAoC;QACpC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;QACrB,qCAAqC;QACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KACxB;IAED,kDAAkD;IAClD,KAAY,UAAU,CAAC,MAAM,SAAS,gBAAgB,IAAI,WAAW,CACnE,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAC7B,CAAC,OAAO,CAAC,CAAA;IAEV,mDAAmD;IACnD,KAAY,WAAW,CAAC,MAAM,SAAS,gBAAgB,IAAI,WAAW,CACpE,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAC7B,CAAC,QAAQ,CAAC,CAAA;CACZ"}