repo-contract 0.1.0

package/dist/.dts/types.d.ts

@@ -0,0 +1,324 @@
+/**
+ * Public type surface for repo-contract. Evidence describes what happened;
+ * Verdict describes whether it was acceptable. They are deliberately
+ * separate concepts (see specs/architecture.md) even though
+ * `runRepoContract` returns both together.
+ */
+/** Output interpretation a check can explicitly request. No format requested means no parsing -- the consumer gets raw stdout/stderr only. */
+export type OutputFormat = "json" | "yaml" | "text";
+/**
+ * Why a check's process ended up in its terminal state. `"completed"` means
+ * the process ran to exit on its own -- the exit code may still be
+ * non-zero, and that is for the check's policy to interpret, never this
+ * package. The other five values all mean the process did not exit on its
+ * own; repo-contract terminated it, or it was terminated for a reason
+ * repo-contract can observe but did not cause.
+ *
+ * `"signaled"` specifically means a signal repo-contract did *not* itself request -- an
+ * externally-caused termination. A check killed because the *host* process running repo-contract
+ * received its own SIGINT/SIGTERM (see `run-checks.ts`'s termination-handler cleanup) is instead
+ * `"host_terminated"`: repo-contract did request that signal, just not via `options.signal` or
+ * `timeoutMs` (see `"aborted"`/`"timed_out"`), so it must not be conflated with an externally-caused
+ * `"signaled"`.
+ */
+export type CheckStatus = "completed" | "timed_out" | "signaled" | "host_terminated" | "spawn_error" | "aborted";
+/** A requested parse of a check's stdout succeeded. */
+export interface ParsedOutputSuccess<T> {
+    /** The format that was requested and successfully parsed. */
+    readonly format: OutputFormat;
+    /** Always `true`. */
+    readonly success: true;
+    /** The parsed value. */
+    readonly value: T;
+}
+/**
+ * A requested parse of a check's stdout failed. The raw stdout on the
+ * parent `CheckEvidence` is preserved unchanged -- a parse failure is never
+ * silently reinterpreted or discarded.
+ */
+export interface ParsedOutputFailure {
+    /** The format that was requested (and failed to parse). */
+    readonly format: OutputFormat;
+    /** Always `false`. */
+    readonly success: false;
+    /** The parse error's message. */
+    readonly error: string;
+}
+/** The result of a check's requested output-format parse: either a successful `ParsedOutputSuccess`, or a `ParsedOutputFailure`. */
+export type ParsedOutput<T> = ParsedOutputSuccess<T> | ParsedOutputFailure;
+/**
+ * What actually happened when one configured check ran. `output` is present
+ * only if that check's config requested a format, and is otherwise
+ * `undefined` -- a policy narrows with `ctx.result.output?.success` (or an
+ * `if (ctx.result.output) { ... }` guard) before reading `.value`/`.error`.
+ *
+ * `output.value` is typed `unknown` for every format, including `"text"`
+ * (even though `parseText` always produces a `string` at runtime) --
+ * neither repo-contract nor TypeScript's generic inference can reliably
+ * carry a specific check's own literal `output.format` through to that
+ * same check's `policy` parameter once several checks with heterogeneous
+ * formats live together in one `checks` record (a real TypeScript
+ * inference limitation hit and confirmed during implementation, not a
+ * hypothetical -- see specs/decisions/ for the isolated repro). A policy
+ * author narrows or casts `.value` themselves, exactly as they already must
+ * for `"json"`/`"yaml"` where no schema knowledge exists either way.
+ */
+export interface CheckEvidence {
+    /** The executable that was actually spawned (after tokenization, if `run` was a string). */
+    readonly command: string;
+    /** The arguments passed to `command`, exactly as spawned. */
+    readonly args: readonly string[];
+    /** ISO 8601 timestamp of when the process was spawned. */
+    readonly startedAt: string;
+    /** ISO 8601 timestamp of when the process reached its terminal state. */
+    readonly completedAt: string;
+    /** Wall-clock time from spawn to termination, in milliseconds. */
+    readonly durationMs: number;
+    /** `null` when the process never exited normally -- see `signal` and `status`. */
+    readonly exitCode: number | null;
+    /** The signal that terminated the process, if any. `null` for a normal exit or a spawn failure. */
+    readonly signal: NodeJS.Signals | null;
+    /** The process's raw standard output, captured verbatim up to an internal size cap (10 MiB); content beyond the cap is replaced with a truncation marker. */
+    readonly stdout: string;
+    /** The process's raw standard error, captured verbatim up to an internal size cap (10 MiB); content beyond the cap is replaced with a truncation marker. */
+    readonly stderr: string;
+    /** Why the process reached its terminal state; see `CheckStatus`. */
+    readonly status: CheckStatus;
+    /** Populated only for `status === "spawn_error"` -- the underlying Node error message (e.g. "spawn foo ENOENT"). Never populated for any other status. */
+    readonly spawnError?: string;
+    /** Populated only for `status === "spawn_error"` -- the underlying Node `ErrnoException`'s structured `.code` (e.g. `"ENOENT"`, `"EACCES"`), when Node provides one. Never populated for any other status. Distinguishes "the executable does not exist" from other spawn failures (permission denied, invalid executable format, etc.) without parsing `spawnError`'s free-text message. */
+    readonly spawnErrorCode?: string;
+    /** The parsed interpretation of `stdout`, present only if this check's config requested a `format`. */
+    readonly output?: ParsedOutput<unknown>;
+}
+/**
+ * Versioned, immutable record of one complete `runRepoContract` execution --
+ * every configured check's evidence, plus timing for the run as a whole.
+ * Says nothing about whether any of it was acceptable; see `Verdict`.
+ * Additive fields are a compatible change; changing or removing an existing
+ * field requires bumping this version number (see VERSIONING.md).
+ */
+export interface Evidence<TChecks extends CheckSchema = CheckSchema> {
+    /** Schema version of this shape; see VERSIONING.md. */
+    readonly version: 1;
+    /** ISO 8601 timestamp of when the run began. */
+    readonly startedAt: string;
+    /** ISO 8601 timestamp of when the last check finished. */
+    readonly completedAt: string;
+    /** Wall-clock time for the run as a whole, in milliseconds. */
+    readonly durationMs: number;
+    /** Each configured check's own evidence, keyed by check id. */
+    readonly checks: {
+        readonly [K in keyof TChecks]: CheckEvidence;
+    };
+}
+/**
+ * What a check's `policy` function is called with. `result` is that check's
+ * own evidence; `evidence` is the complete run's evidence, including every
+ * sibling check -- present so a policy can make cross-check decisions (e.g.
+ * "only enforce the mutation-score threshold if the tests check passed").
+ * By the time any policy runs, every check has already finished executing
+ * and every check's evidence has already been assembled -- no policy ever
+ * observes a partially-populated `evidence` (see specs/architecture.md).
+ */
+export interface PolicyContext<TChecks extends CheckSchema = CheckSchema> {
+    /** This check's own evidence. */
+    readonly result: CheckEvidence;
+    /** The complete run's evidence, including every sibling check. */
+    readonly evidence: Evidence<TChecks>;
+    /**
+     * This check's own declared `dependsOn` dependencies' evidence, keyed by
+     * check id -- a convenience view, fully derivable from `evidence.checks`
+     * plus this check's own `dependsOn`, provided so no policy has to do that
+     * lookup itself. `{}` for a check with no `dependsOn` -- always an
+     * object, never `undefined`, matching how `evidence.checks` is already
+     * used today (a policy narrows a specific key's presence, never the
+     * field itself). Evidence only, not policy outcomes -- a dependency's
+     * policy result stays visible only via the top-level `Verdict`, exactly
+     * as today; this keeps policy evaluation itself fully parallel and
+     * unaffected by `dependsOn`.
+     */
+    readonly dependencies: Readonly<Record<string, CheckEvidence>>;
+}
+/**
+ * `"pass"`: the repository-owned policy evaluated the captured evidence as
+ * satisfying its configured requirements. `"fail"`: the evidence did not
+ * satisfy them. `"warn"`: the evidence does not violate the policy's
+ * blocking requirements, but the policy has intentionally decided the
+ * condition is materially relevant and wants it surfaced -- not a synonym
+ * for "minor failure"; a `warn` never fails `Verdict.passed` (see
+ * `runPolicies` in `src/policy/run-policies.ts`).
+ */
+export type PolicyOutcome = "pass" | "fail" | "warn";
+/**
+ * A repository-owned policy's interpretation of one check's captured
+ * evidence -- fully JSON-serializable (a plain object of primitives only,
+ * never an `Error`, class instance, function, or tool-specific object) so it
+ * can be persisted, transmitted, aggregated across parallel checks, and
+ * consumed directly by a human or an AI without rerunning anything.
+ *
+ * `rationale` is mandatory and must contain enough actionable detail --
+ * specific file/line locations, rule ids, test names, counts -- for a
+ * consumer to understand *why* the policy reached its outcome from this
+ * value alone. A rationale like "see output above" or "check the report for
+ * details" defeats the purpose: it forces the consumer back to raw,
+ * unstructured command output, exactly what this type exists to avoid. See
+ * specs/architecture.md for the evidence/rationale/judgment distinction this
+ * type is built around: evidence answers "what happened?", `rationale`
+ * answers "what does the repository's policy conclude about what
+ * happened?", and a policy's `outcome` is not the final word -- a human or
+ * AI consumer still makes the final judgment call using both.
+ */
+export interface PolicyResult {
+    /** The policy's pass/fail/warn decision. */
+    readonly outcome: PolicyOutcome;
+    /** Why the policy reached `outcome`, in enough detail to act on without rerunning anything. */
+    readonly rationale: string;
+}
+/**
+ * A repository-owned decision about whether one check's evidence is
+ * acceptable. Returns a `PolicyResult` -- never a bare boolean or string --
+ * so a policy can communicate more than pass/fail even when the run is
+ * otherwise acceptable (see `PolicyResult`/`PolicyOutcome`). May be
+ * synchronous or return a `Promise`. repo-contract does not interpret
+ * `rationale` beyond storing and surfacing it verbatim; the package has no
+ * opinion about what makes a check pass, fail, or warrant a `warn`.
+ */
+export type Policy<TChecks extends CheckSchema = CheckSchema> = (ctx: PolicyContext<TChecks>) => PolicyResult | Promise<PolicyResult>;
+/** One partially configured check: how to run it, how (if at all) to interpret its output, and the policy that decides whether its evidence is acceptable. */
+export interface CheckDefinitionConfig {
+    /**
+     * The command to run. A `string` is tokenized into executable + arguments
+     * without invoking a shell -- shell operators (`;`, `&`, `|`, backticks,
+     * `$(`, `<`, `>`, newlines) are rejected with a configuration error rather
+     * than silently passed through as literal arguments, since a string
+     * containing one almost always reflects a mistaken assumption that shell
+     * interpretation is happening. Glob characters (`*`, `?`, `~`, `[`, `]`,
+     * `{`, `}`) are NOT rejected -- they are common, legitimate literal argv
+     * content (e.g. `eslint "src/**\/*.ts"`) that many CLI tools glob-expand
+     * internally, and carry no shell-injection risk when no shell is invoked.
+     * An array bypasses tokenization entirely and is used as argv verbatim.
+     */
+    readonly run: string | readonly string[];
+    /**
+     * Opt into real shell execution instead of the safe argv-only default.
+     * When `true`, `run` must be a `string` and is passed to the platform
+     * shell as-is (via cross-spawn's own `shell` option) -- shell metacharacter
+     * rejection does not apply. See SECURITY.md before enabling this.
+     */
+    readonly shell?: boolean;
+    /** Working directory for the spawned process. Defaults to the current process's `cwd`. */
+    readonly cwd?: string;
+    /** Additional environment variables for the spawned process, applied on top of (or, if `inheritEnv` is `false`, instead of) the inherited environment. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Whether the spawned process inherits `process.env`. Defaults to `true` -- most check commands (npm scripts, locally-installed CLIs) need `PATH` and similar to resolve at all. Set to `false` for a minimal environment containing only `env` (plus whatever the OS itself always provides). */
+    readonly inheritEnv?: boolean;
+    /** Maximum time to let this check's process run before it is terminated and recorded with `status: "timed_out"`. No timeout by default. */
+    readonly timeoutMs?: number;
+    /** Request that stdout be parsed as this format. Omit for no parsing -- the consumer gets raw stdout/stderr only. */
+    readonly output?: {
+        readonly format: OutputFormat;
+    };
+    /**
+     * A full scheduling barrier at this check's own position in the `checks` object: it does not
+     * spawn until every check declared *earlier* has reached a terminal status (nothing "currently in
+     * flight" when its turn comes can be anything other than an earlier-declared check, since nothing
+     * declared later has even been reached yet), and every check declared *after* it waits for it in
+     * turn -- so nothing overlaps it in either direction. Purely a scheduling primitive for a check
+     * whose own tooling spawns concurrent workers that would otherwise contend with the rest of the
+     * run for machine resources (e.g. Stryker's own worker pool); it expresses no need for any other
+     * check's evidence, only for the machine to itself, and never appears in a policy's
+     * `ctx.dependencies` or in a partial `options.checks` run's transitive closure on its own (an
+     * explicit `dependsOn` alongside it still works exactly as it would on any other check). Defaults
+     * to `false` -- unaffected, fully-parallel scheduling in declaration order, unchanged. Two
+     * isolated checks are always sequential relative to each other (whichever is declared second
+     * waits for the first, as one of the "every check declared earlier" it's barred behind). See
+     * specs/decisions/0002-dependson-and-isolated-are-two-scheduling-primitives.md.
+     */
+    readonly isolated?: boolean;
+    /** Decides whether this check's evidence is acceptable, once its process has finished running. */
+    readonly policy: Policy;
+}
+/** One fully configured check: how to run it, how (if at all) to interpret its output, and the policy that decides whether its evidence is acceptable. */
+export interface CheckDefinition extends CheckDefinitionConfig {
+    /**
+     * Other check ids (from this same `checks` record) that must reach a
+     * terminal status -- not necessarily a passing policy -- before this
+     * check's own process is spawned. Execution ordering only: whether a
+     * dependency's *policy* passed is never consulted by repo-contract to
+     * decide whether this check's process spawns -- that is this check's
+     * own command or policy's decision (see `ctx.dependencies` on
+     * `PolicyContext`). Omit, or an empty array, for no dependencies -- the
+     * default, fully-parallel behavior, unchanged. Validated before any
+     * process spawns: every named id must exist in `checks`, a check cannot
+     * depend on itself, and -- since declaration order in the `checks` object
+     * doubles as the required topological order -- every named id must be
+     * declared *earlier* than the check declaring `dependsOn` on it (a
+     * forward reference throws `DependencyDeclaredLaterError`; a cycle is
+     * consequently impossible, since no edge can ever point forward). See
+     * specs/decisions/0002-dependson-and-isolated-are-two-scheduling-primitives.md.
+     */
+    readonly dependsOn?: readonly string[];
+}
+/** The full set of checks in a `RepoContractConfig`, keyed by check id. */
+export type CheckSchema = Record<string, CheckDefinition>;
+/**
+ * Same shape as a check schema `T`, except each check's own `dependsOn` is
+ * narrowed from `readonly string[]` to only the *other* keys of that same
+ * `T` -- so a typo'd or self-referencing id fails to compile instead of
+ * only failing at runtime (`validate-config.ts` still enforces this at
+ * runtime too, for any config that reaches `runRepoContract` without having
+ * gone through `defineRepoContract`'s static checking first, e.g. one
+ * assembled dynamically from untyped data).
+ *
+ * Used as an additional constraint on `defineRepoContract`'s parameter,
+ * intersected with `RepoContractConfig<TChecks>` rather than substituted
+ * for it -- inferring `TChecks` from the *unwrapped* `RepoContractConfig<TChecks>`
+ * position first is what keeps every check's own `policy` callback
+ * contextually typed (a real TypeScript inference limitation: inferring
+ * `TChecks` directly from a mapped/conditional type over itself, as this
+ * type is, loses that contextual typing -- confirmed during implementation,
+ * not a hypothetical).
+ */
+export type ValidatedCheckSchema<T> = {
+    readonly [K in keyof T]: T[K] extends CheckDefinitionConfig ? Omit<T[K], "dependsOn"> & {
+        readonly dependsOn?: readonly (Exclude<keyof T, K> & string)[];
+    } : never;
+};
+/** Top-level configuration passed to `defineRepoContract`/`runRepoContract`. */
+export interface RepoContractConfig<TChecks extends CheckSchema = CheckSchema> {
+    /** Every check to run, keyed by check id. */
+    readonly checks: TChecks;
+    /** Maximum number of checks to execute concurrently. Defaults to `os.availableParallelism()`. Must be a positive integer. */
+    readonly concurrency?: number;
+}
+/** Optional per-run controls for `runRepoContract`. */
+export interface RunRepoContractOptions {
+    /** Abort the entire run. Checks already in flight are terminated; checks not yet started never spawn. Every configured check still receives a well-formed evidence entry (`status: "aborted"`) and still has its policy invoked. */
+    readonly signal?: AbortSignal;
+    /** Restrict this run to only these check ids (and whatever they `dependsOn`, transitively). Every configured check runs when omitted. */
+    readonly checks?: string[];
+}
+/**
+ * Versioned, immutable aggregate result of evaluating every configured
+ * check's policy against its evidence -- each check's own `PolicyResult`,
+ * verbatim, keyed by check id. `passed` is `true` only if every check's
+ * `outcome` is `"pass"` or `"warn"` -- `"fail"` is the only outcome that
+ * fails the run; one failing check never collapses into a single generic
+ * message, every check remains individually inspectable under `checks`.
+ * Versioned independently of `Evidence` (see VERSIONING.md's
+ * schema-versioning policy) -- `version: 2` reflects `checks[id]` changing
+ * shape from `{ passed, reason? }` to a full `PolicyResult`
+ * (`{ outcome, rationale }`); see ADR 0001.
+ */
+export interface Verdict<TChecks extends CheckSchema = CheckSchema> {
+    /** Schema version of this shape; see VERSIONING.md. */
+    readonly version: 2;
+    /** `true` only if every check's `outcome` is `"pass"` or `"warn"`. */
+    readonly passed: boolean;
+    /** Each configured check's own `PolicyResult`, verbatim, keyed by check id. */
+    readonly checks: {
+        readonly [K in keyof TChecks]: PolicyResult;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/.dts/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8IAA8I;AAC9I,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;AAEnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,WAAW,GACrB,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,iBAAiB,GAAG,aAAa,GAAG,SAAS,CAAA;AAExF,uDAAuD;AACvD,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,qBAAqB;IACrB,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;IACtB,wBAAwB;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,sBAAsB;IACtB,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;IACvB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,oIAAoI;AACpI,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,mBAAmB,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAA;AAE1E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,mGAAmG;IACnG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;IACtC,6JAA6J;IAC7J,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,4JAA4J;IAC5J,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,0JAA0J;IAC1J,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,6XAA6X;IAC7X,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,uGAAuG;IACvG,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;CACxC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW;IACjE,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,OAAO,GAAG,aAAa;KAAE,CAAA;CAClE;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW;IACtE,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IACpC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAA;CAC/D;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;AAEpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAC/B,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,MAAM,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW,IAAI,CAC9D,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC,KACxB,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;AAEzC,8JAA8J;AAC9J,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,0JAA0J;IAC1J,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/C,mSAAmS;IACnS,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;IAC7B,2IAA2I;IAC3I,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,qHAAqH;IACrH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;KAAE,CAAA;IACnD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,kGAAkG;IAClG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,0JAA0J;AAC1J,MAAM,WAAW,eAAgB,SAAQ,qBAAqB;IAC5D;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI;IACpC,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,qBAAqB,GACvD,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG;QACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,EAAE,CAAA;KAC/D,GACD,KAAK;CACV,CAAA;AAED,gFAAgF;AAChF,MAAM,WAAW,kBAAkB,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW;IAC3E,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,6HAA6H;IAC7H,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,uDAAuD;AACvD,MAAM,WAAW,sBAAsB;IACrC,oOAAoO;IACpO,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,yIAAyI;IACzI,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,OAAO,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW;IAChE,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,OAAO,GAAG,YAAY;KAAE,CAAA;CACjE"}

package/dist/index.cjs

@@ -0,0 +1,46 @@
+'use strict';
+
+var os = require('os');
+var crossSpawn = require('cross-spawn');
+var string_decoder = require('string_decoder');
+var child_process = require('child_process');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+function _interopNamespace(e) {
+	if (e && e.__esModule) return e;
+	var n = Object.create(null);
+	if (e) {
+		Object.keys(e).forEach(function (k) {
+			if (k !== 'default') {
+				var d = Object.getOwnPropertyDescriptor(e, k);
+				Object.defineProperty(n, k, d.get ? d : {
+					enumerable: true,
+					get: function () { return e[k]; }
+				});
+			}
+		});
+	}
+	n.default = e;
+	return Object.freeze(n);
+}
+
+var os__namespace = /*#__PURE__*/_interopNamespace(os);
+var crossSpawn__default = /*#__PURE__*/_interopDefault(crossSpawn);
+
+function defineRepoContract(config){return config}var RepoContractError=class extends Error{};var InvalidRepoContractConfigError=class extends RepoContractError{code="REPO_CONTRACT_INVALID_CONFIG";constructor(reason){super(`Invalid repo-contract config -- ${reason}`);this.name="InvalidRepoContractConfigError";}};var InvalidCheckConfigError=class extends RepoContractError{code="REPO_CONTRACT_INVALID_CHECK_CONFIG";checkId;constructor(checkId,reason){super(`Invalid check config for "${checkId}" -- ${reason}`);this.name="InvalidCheckConfigError";this.checkId=checkId;}};var UnknownCheckIdError=class extends RepoContractError{code="REPO_CONTRACT_UNKNOWN_CHECK_ID";checkId;constructor(checkId){super(`options.checks names "${checkId}", which is not a check id in this config's checks object.`);this.name="UnknownCheckIdError";this.checkId=checkId;}};var DependencyDeclaredLaterError=class extends RepoContractError{code="REPO_CONTRACT_DEPENDENCY_DECLARED_LATER";checkId;dependencyId;constructor(checkId,dependencyId){super(`Invalid check config for "${checkId}" -- dependsOn: ["${dependencyId}"], but "${dependencyId}" is declared later in the checks object. dependsOn may only reference a check declared earlier -- reorder the checks object so "${dependencyId}" is declared before "${checkId}".`);this.name="DependencyDeclaredLaterError";this.checkId=checkId;this.dependencyId=dependencyId;}};var ParserDependencyMissingError=class extends RepoContractError{code="REPO_CONTRACT_PARSER_DEPENDENCY_MISSING";checkId;format;constructor(checkId,format,cause){super(`Check "${checkId}" requested output.format: "${format}", but the optional "${format}" peer dependency is not installed -- run \`npm install ${format}\` to enable it.`,{cause});this.name="ParserDependencyMissingError";this.checkId=checkId;this.format=format;}};var PolicyThrewError=class extends RepoContractError{code="REPO_CONTRACT_POLICY_THREW";checkId;constructor(checkId,cause){super(`Policy for check "${checkId}" threw instead of returning a PolicyResult`,{cause});this.name="PolicyThrewError";this.checkId=checkId;}};var PolicyReadUnrequestedOutputError=class extends RepoContractError{code="REPO_CONTRACT_POLICY_READ_UNREQUESTED_OUTPUT";checkId;constructor(checkId,property,cause){super(`Policy for check "${checkId}" read \`result.output.${property}\`, but "${checkId}" never requested an output format, so \`result.output\` is undefined -- add \`output: { format: "json" }\` (or "yaml"/"text") to check "${checkId}"'s definition to parse its stdout, then narrow with \`result.output?.success\` before reading \`.value\`/\`.error\`.`,{cause});this.name="PolicyReadUnrequestedOutputError";this.checkId=checkId;}};var PolicyReadFailedParseValueError=class extends RepoContractError{code="REPO_CONTRACT_POLICY_READ_FAILED_PARSE_VALUE";checkId;constructor(checkId,property,cause){super(`Policy for check "${checkId}" read \`result.output.value.${property}\`, but "${checkId}"'s output failed to parse -- a failed parse has \`result.output.error\`, never \`.value\` -- check \`result.output.success\` before reading \`.value\`.`,{cause});this.name="PolicyReadFailedParseValueError";this.checkId=checkId;}};function consumeEscape(run,i,quote){if(run[i]!=="\\"||quote==="'")return void 0;const escaped=run[i+1];if(escaped===void 0)return void 0;return {value:escaped,next:i+2}}var UNQUOTED_SHELL_OPERATORS=new Set([";","&","|","`","<",">"]);function rejectUnquotedOperator(char,run,i,checkId){const reject=operator=>{throw new InvalidCheckConfigError(checkId,`run string contains an unquoted "${operator}" -- repo-contract never invokes a shell for string-form "run", so shell operators are not interpreted. Use "run: [...]" (array form) to pass "${operator}" as a literal argument, or set "shell: true" to opt into real shell execution.`)};if(char==="\n"||char==="\r")reject("newline");if(UNQUOTED_SHELL_OPERATORS.has(char))reject(char);if(char==="$"&&run[i+1]==="(")reject("$(");}function tokenizeRunString(run,checkId){const tokens=[];let current="";let hasCurrent=false;let quote=null;let i=0;for(let iterations=0;i<run.length&&iterations<=run.length;iterations+=1){const char=run[i];if(char===void 0)break;if(quote!==null){const escape2=consumeEscape(run,i,quote);if(escape2!==void 0){current+=escape2.value;i=escape2.next;continue}if(char===quote){quote=null;i+=1;continue}current+=char;i+=1;continue}if(char==="'"||char==='"'){quote=char;hasCurrent=true;i+=1;continue}const nextChar=run[i+1];if(char==="\\"&&(nextChar==="\n"||nextChar==="\r")){throw new InvalidCheckConfigError(checkId,`run string contains an unquoted line continuation (a backslash before a newline) -- repo-contract never invokes a shell for string-form "run". Use "run: [...]" (array form), or set "shell: true" to opt into real shell execution.`)}const escape=consumeEscape(run,i,null);if(escape!==void 0){current+=escape.value;hasCurrent=true;i=escape.next;continue}if(char===" "||char==="	"){if(hasCurrent){tokens.push(current);current="";hasCurrent=false;}i+=1;continue}rejectUnquotedOperator(char,run,i,checkId);current+=char;hasCurrent=true;i+=1;}if(quote!==null){throw new InvalidCheckConfigError(checkId,`run string has an unterminated ${quote} quote.`)}if(hasCurrent)tokens.push(current);if(tokens.length===0){throw new InvalidCheckConfigError(checkId,"run string is empty or contains only whitespace.")}return tokens}var OUTPUT_FORMATS=["json","yaml","text"];function validateRepoContractConfig(config){const untrusted=config;if(untrusted===null||typeof untrusted!=="object"){throw new InvalidRepoContractConfigError("config must be an object.")}const{checks,concurrency}=untrusted;if(checks===null||typeof checks!=="object"||Array.isArray(checks)){throw new InvalidRepoContractConfigError("checks must be an object mapping check id to check definition.")}if(concurrency!==void 0){if(typeof concurrency!=="number"||!Number.isInteger(concurrency)||concurrency<1){throw new InvalidRepoContractConfigError("concurrency must be a positive integer when provided.")}}for(const[checkId,check]of Object.entries(checks)){validateCheckDefinition(checkId,check);}validateDependencyGraph(checks);}function validateCheckDefinition(checkId,check){if(/^(?:0|[1-9]\d*)$/.test(checkId)){throw new InvalidCheckConfigError(checkId,"check id must not be an integer-like string -- JavaScript would reorder it ahead of every other key and break the declaration-order-is-topological-order contract.")}if(check===null||typeof check!=="object"){throw new InvalidCheckConfigError(checkId,"check definition must be an object.")}const fields=check;const usesShell=validateShell(checkId,fields.shell);validateRun(checkId,fields.run,usesShell);validateCwd(checkId,fields.cwd);validateEnv(checkId,fields.env);validateInheritEnv(checkId,fields.inheritEnv);validateTimeoutMs(checkId,fields.timeoutMs);validateOutput(checkId,fields.output);validateDependsOn(checkId,fields.dependsOn);validateIsolated(checkId,fields.isolated);validatePolicy(checkId,fields.policy);}function validateShell(checkId,shell){if(shell!==void 0&&typeof shell!=="boolean"){throw new InvalidCheckConfigError(checkId,"shell must be a boolean when provided.")}return shell===true}function validateRun(checkId,run,usesShell){if(typeof run!=="string"&&!Array.isArray(run)){throw new InvalidCheckConfigError(checkId,"run must be a string or an array of strings.")}if(typeof run==="string"){validateStringRun(checkId,run,usesShell);}else {validateArrayRun(checkId,run,usesShell);}}function validateStringRun(checkId,run,usesShell){if(!usesShell){const[executable]=tokenizeRunString(run,checkId);if(executable?.trim().length===0){throw new InvalidCheckConfigError(checkId,"run string's first token (the executable) is empty or contains only whitespace.")}return}if(run.trim().length===0){throw new InvalidCheckConfigError(checkId,"run string is empty or contains only whitespace.")}}function validateArrayRun(checkId,items,usesShell){if(usesShell){throw new InvalidCheckConfigError(checkId,"shell: true requires run to be a string -- an array of arguments is individually escaped for the shell and cannot express shell operators like pipes or redirects, so combining the two forms would silently do nothing useful.")}if(items.length===0){throw new InvalidCheckConfigError(checkId,"run array must not be empty.")}if(items.some(item=>typeof item!=="string")){throw new InvalidCheckConfigError(checkId,"run array must contain only strings.")}if(items[0].trim().length===0){throw new InvalidCheckConfigError(checkId,"run array's first element (the executable) is empty or contains only whitespace.")}}function validateCwd(checkId,cwd){if(cwd!==void 0&&typeof cwd!=="string"){throw new InvalidCheckConfigError(checkId,"cwd must be a string when provided.")}}function validateEnv(checkId,env){if(env===void 0)return;if(env===null||typeof env!=="object"||Array.isArray(env)){throw new InvalidCheckConfigError(checkId,"env must be an object mapping name to value when provided.")}for(const[key,value]of Object.entries(env)){if(typeof value!=="string"){throw new InvalidCheckConfigError(checkId,`env["${key}"] must be a string.`)}}}function validateInheritEnv(checkId,inheritEnv){if(inheritEnv!==void 0&&typeof inheritEnv!=="boolean"){throw new InvalidCheckConfigError(checkId,"inheritEnv must be a boolean when provided.")}}function validateTimeoutMs(checkId,timeoutMs){if(timeoutMs===void 0)return;if(typeof timeoutMs!=="number"||!Number.isFinite(timeoutMs)||timeoutMs<=0){throw new InvalidCheckConfigError(checkId,"timeoutMs must be a positive number when provided.")}}function validateOutput(checkId,output){if(output===void 0)return;if(output===null||typeof output!=="object"){throw new InvalidCheckConfigError(checkId,"output must be an object when provided.")}const{format}=output;if(typeof format!=="string"||!OUTPUT_FORMATS.includes(format)){throw new InvalidCheckConfigError(checkId,`output.format must be one of ${OUTPUT_FORMATS.map(f=>`"${f}"`).join(", ")}.`)}}function validatePolicy(checkId,policy){if(typeof policy!=="function"){throw new InvalidCheckConfigError(checkId,"policy must be a function.")}}function validateDependsOn(checkId,dependsOn){if(dependsOn===void 0)return;if(!Array.isArray(dependsOn)||dependsOn.some(id=>typeof id!=="string")){throw new InvalidCheckConfigError(checkId,"dependsOn must be an array of check ids (strings) when provided.")}if(dependsOn.includes(checkId)){throw new InvalidCheckConfigError(checkId,"dependsOn must not include the check's own id.")}}function validateIsolated(checkId,isolated){if(isolated!==void 0&&typeof isolated!=="boolean"){throw new InvalidCheckConfigError(checkId,"isolated must be a boolean when provided.")}}function validateDependencyGraph(checks){const ids=Object.keys(checks);const indexById=new Map(ids.map((id,index)=>[id,index]));for(const[index,id]of ids.entries()){const check=checks[id];for(const depId of check?.dependsOn??[]){const depIndex=indexById.get(depId);if(depIndex===void 0){throw new InvalidCheckConfigError(id,`dependsOn references unknown check id "${depId}".`)}if(depIndex>=index){throw new DependencyDeclaredLaterError(id,depId)}}}}function parseJson(stdout){try{return {format:"json",success:true,value:JSON.parse(stdout)}}catch(error){return {format:"json",success:false,error:error instanceof Error?error.message:String(error)}}}function parseText(stdout){return {format:"text",success:true,value:stdout.trim()}}async function parseYaml(stdout,checkId){let yamlModule;try{yamlModule=await import('yaml');}catch(error){throw new ParserDependencyMissingError(checkId,"yaml",error)}try{return {format:"yaml",success:true,value:yamlModule.parse(stdout)}}catch(error){return {format:"yaml",success:false,error:error instanceof Error?error.message:String(error)}}}async function parseOutput(format,stdout,checkId){switch(format){case "json":return parseJson(stdout);case "yaml":return parseYaml(stdout,checkId);case "text":return parseText(stdout)}}async function buildEvidence(results,startedAt,completedAt){const thrown=[];const entries=await Promise.all(results.map(async([checkId,check,raw])=>{if(check.output===void 0)return [checkId,check,raw];try{const output=await parseOutput(check.output.format,raw.stdout,checkId);return [checkId,check,{...raw,output}]}catch(error){thrown.push(error);return [checkId,check,raw]}}));if(thrown.length===1){const[only]=thrown;throw only}if(thrown.length>1){throw new AggregateError(thrown,`${String(thrown.length)} check output(s) failed to parse.`)}const evidence={version:1,startedAt:startedAt.toISOString(),completedAt:completedAt.toISOString(),durationMs:completedAt.getTime()-startedAt.getTime(),checks:Object.fromEntries(entries.map(([checkId,,checkEvidence])=>[checkId,checkEvidence]))};return {evidence,entries}}function composeSignals(signals){if(typeof AbortSignal.any==="function"){return {signal:AbortSignal.any(signals),dispose:()=>void 0}}const controller=new AbortController;const attached=[];for(const signal of signals){if(signal.aborted){controller.abort(signal.reason);break}const listener=()=>{controller.abort(signal.reason);};signal.addEventListener("abort",listener);attached.push({signal,listener});}return {signal:controller.signal,dispose:()=>{for(const{signal,listener}of attached)signal.removeEventListener("abort",listener);}}}async function runWithConcurrency(items,concurrency,worker){const results=[];const entries=items.map((item,index)=>[item,index]);const iterator=entries[Symbol.iterator]();let firstRejection;async function runNext(){for(let next=iterator.next();!next.done;next=iterator.next()){if(firstRejection!==void 0)return;const[item,index]=next.value;try{results[index]=await worker(item,index);}catch(error){firstRejection??={error};return}}}const effectiveConcurrency=Number.isFinite(concurrency)?concurrency:1;const workerCount=Math.max(1,Math.min(effectiveConcurrency,items.length));await Promise.all(Array.from({length:workerCount},()=>runNext()));if(firstRejection!==void 0){throw firstRejection.error}return results}async function runWithConcurrencyGraph(items,concurrency,dependencyIndexes,worker){if(items.length===0)return [];const dependencies=items.map((item,index)=>[...new Set(dependencyIndexes(item,index))].filter(depIndex=>Number.isInteger(depIndex)&&depIndex>=0&&depIndex<items.length));const remaining=dependencies.map(indexes=>indexes.length);const dependents=items.map(()=>[]);dependencies.forEach((indexes,index)=>{for(const depIndex of indexes){dependents[depIndex]?.push(index);}});const ready=remaining.flatMap((count,index)=>count===0?[index]:[]);const concurrencyIsUsable=Number.isFinite(concurrency);const results=Array.from({length:items.length});const effectiveConcurrency=concurrencyIsUsable?Math.max(1,concurrency):1;let active=0;let settled=0;let done=false;return new Promise((resolvePromise,rejectPromise)=>{if(ready.length===0){fail(new Error("runWithConcurrencyGraph: stalled before starting -- the dependency graph passed in is not acyclic."));return}function fail(error){if(done)return;done=true;rejectPromise(error);}function launchNext(){while(active<effectiveConcurrency&&ready.length>0){const index=ready.shift();if(index===void 0)break;const item=items[index];if(item===void 0)continue;active+=1;worker(item,index).then(result=>{results[index]=result;active-=1;settled+=1;for(const dependentIndex of dependents[index]??[]){const nextRemaining=(remaining[dependentIndex]??0)-1;remaining[dependentIndex]=nextRemaining;if(nextRemaining===0)ready.push(dependentIndex);}if(done)return;if(settled===items.length){resolvePromise(results);return}if(active===0&&ready.length===0){fail(new Error("runWithConcurrencyGraph: stalled with unsettled items remaining -- the dependency graph passed in is not acyclic."));return}launchNext();}).catch(fail);}}launchNext();})}function shouldSpawnDetached(){return process.platform!=="win32"}function isErrnoException(error){return error instanceof Error&&"code"in error}function killTree(pid,signal){if(!Number.isInteger(pid)||pid<=0){return}if(process.platform==="win32"){const result=child_process.spawnSync("taskkill",["/pid",String(pid),"/t","/f"],{stdio:"ignore"});if(result.error!==void 0)throw result.error;return}try{process.kill(-pid,signal);}catch(error){if(isErrnoException(error)&&(error.code==="ESRCH"||error.code==="EPERM"))return;throw error}}var MAX_CAPTURED_OUTPUT_BYTES=10*1024*1024;var SIGKILL_GRACE_PERIOD_MS=2e3;function createBoundedCollector(){const decoder=new string_decoder.StringDecoder("utf8");let value="";let byteCount=0;let truncated=false;return {append(chunk){if(truncated)return;byteCount+=chunk.byteLength;value+=decoder.write(chunk);if(byteCount>MAX_CAPTURED_OUTPUT_BYTES){truncated=true;value=`${value.slice(0,MAX_CAPTURED_OUTPUT_BYTES)}
+...[output truncated at ${String(MAX_CAPTURED_OUTPUT_BYTES)} bytes]`;}},value:()=>value}}function resolveCommand(checkId,check){const run=check.run;if(typeof run!=="string"){const[command2,...args2]=run;if(command2===void 0){throw new InvalidCheckConfigError(checkId,"run array must not be empty.")}return {command:command2,args:args2}}if(check.shell===true){return {command:run,args:[]}}const[command,...args]=tokenizeRunString(run,checkId);if(command===void 0){throw new InvalidCheckConfigError(checkId,"run string is empty or contains only whitespace.")}return {command,args}}function buildEnv(check){const base={};if(check.inheritEnv!==false){for(const[key,value]of Object.entries(process.env)){if(value!==void 0)base[key]=value;}}return {...base,...check.env}}function terminalEvidence(command,args,startedAt,status,exitCode,signal,stdout="",stderr="",spawnError,spawnErrorCode){const completedAt=new Date;return {command,args,startedAt:startedAt.toISOString(),completedAt:completedAt.toISOString(),durationMs:completedAt.getTime()-startedAt.getTime(),exitCode,signal,stdout,stderr,status,...spawnError!==void 0?{spawnError}:{},...spawnErrorCode!==void 0?{spawnErrorCode}:{}}}async function spawnCheck(checkId,check,runSignal,activeHandles){const startedAt=new Date;const{command,args}=resolveCommand(checkId,check);if(runSignal?.aborted===true){return terminalEvidence(command,args,startedAt,"aborted",null,null)}const env=buildEnv(check);let terminationReason=null;let timeoutHandle;const timeoutController=new AbortController;if(check.timeoutMs!==void 0){const MAX_TIMER_DELAY_MS=2147483647;const delay=Math.min(check.timeoutMs,MAX_TIMER_DELAY_MS);timeoutHandle=setTimeout(()=>{timeoutController.abort();},delay);}const{signal:effectiveSignal,dispose:disposeEffectiveSignal}=composeSignals(runSignal!==void 0?[runSignal,timeoutController.signal]:[timeoutController.signal]);return new Promise(resolve=>{const child=crossSpawn__default.default(command,args,{cwd:check.cwd,env,shell:check.shell===true,detached:shouldSpawnDetached(),windowsHide:true});const stdoutCollector=createBoundedCollector();const stderrCollector=createBoundedCollector();let handle;let escalationHandle;let hostTerminated=false;const bestEffortKillTree=(pid,signal)=>{try{killTree(pid,signal);}catch{}};const killWithEscalation=(pid,signal)=>{bestEffortKillTree(pid,signal);clearTimeout(escalationHandle);if(signal==="SIGKILL")return;escalationHandle=setTimeout(()=>{bestEffortKillTree(pid,"SIGKILL");},SIGKILL_GRACE_PERIOD_MS);};if(child.pid!==void 0){const pid=child.pid;handle={kill:signal=>{hostTerminated=true;killWithEscalation(pid,signal);}};activeHandles.add(handle);}child.stdout?.on("data",chunk=>{stdoutCollector.append(chunk);});child.stderr?.on("data",chunk=>{stderrCollector.append(chunk);});const onEffectiveAbort=()=>{terminationReason=runSignal?.aborted===true?"aborted":"timed_out";if(child.pid!==void 0)killWithEscalation(child.pid,"SIGTERM");};effectiveSignal.addEventListener("abort",onEffectiveAbort);const cleanup=()=>{clearTimeout(timeoutHandle);clearTimeout(escalationHandle);effectiveSignal.removeEventListener("abort",onEffectiveAbort);disposeEffectiveSignal();if(handle!==void 0)activeHandles.delete(handle);};child.once("error",error=>{cleanup();resolve(terminalEvidence(command,args,startedAt,"spawn_error",null,null,stdoutCollector.value(),stderrCollector.value(),error.message,error.code));});child.once("close",(code,signal)=>{cleanup();const status=hostTerminated?"host_terminated":terminationReason==="aborted"?"aborted":terminationReason==="timed_out"?"timed_out":code===null&&signal!==null?"signaled":"completed";resolve(terminalEvidence(command,args,startedAt,status,code,signal,stdoutCollector.value(),stderrCollector.value()));});})}var TERMINATION_SIGNALS=["SIGINT","SIGTERM"];var SELF_TERMINATE_DELAY_MS=SIGKILL_GRACE_PERIOD_MS+250;function installTerminationHandlers(activeHandles,hostAbortController){const handlers=new Map;for(const signal of TERMINATION_SIGNALS){const handler=()=>{hostAbortController.abort();const hadActiveChecks=activeHandles.size>0;for(const handle of activeHandles)handle.kill(signal);uninstall();if(!hadActiveChecks){process.kill(process.pid,signal);return}setTimeout(()=>{process.kill(process.pid,signal);},SELF_TERMINATE_DELAY_MS);};handlers.set(signal,handler);process.once(signal,handler);}function uninstall(){for(const[signal,handler]of handlers)process.removeListener(signal,handler);}return uninstall}function resolveCheckDependencies(checks,requestedChecks){const required=new Set;const visit=checkId=>{if(required.has(checkId))return;const check=checks[checkId];if(!check){throw new UnknownCheckIdError(checkId)}required.add(checkId);for(const dependency of check.dependsOn??[]){visit(dependency);}};for(const checkId of requestedChecks)visit(checkId);return Object.entries(checks).filter(([checkId])=>required.has(checkId))}async function runChecks(checks,concurrency,options){const entries=options?.checks?resolveCheckDependencies(checks,options.checks):Object.entries(checks);const activeHandles=new Set;const hostAbortController=new AbortController;const uninstall=installTerminationHandlers(activeHandles,hostAbortController);const{signal:runSignal,dispose:disposeRunSignal}=composeSignals(options?.signal!==void 0?[options.signal,hostAbortController.signal]:[hostAbortController.signal]);const worker=async([checkId,check])=>{const evidence=await spawnCheck(checkId,check,runSignal,activeHandles);return [checkId,check,evidence]};try{const hasDependencies=entries.some(([,check])=>(check.dependsOn?.length??0)>0||check.isolated===true);if(!hasDependencies){return await runWithConcurrency(entries,concurrency,worker)}const indexById=new Map(entries.map(([checkId],index)=>[checkId,index]));const isolatedIndexes=[];for(const[entryIndex,[,entryCheck]]of entries.entries()){if(entryCheck.isolated===true)isolatedIndexes.push(entryIndex);}const dependencyIndexesFor=([,check],index)=>{const declared=(check.dependsOn??[]).map(depId=>{const depIndex=indexById.get(depId);if(depIndex===void 0){throw new Error(`internal: dependsOn references unknown check id "${depId}".`)}return depIndex});if(check.isolated===true){const earlierIndexes=Array.from({length:index},(_,earlierIndex)=>earlierIndex);return [...new Set([...declared,...earlierIndexes])]}const earlierIsolated=isolatedIndexes.filter(isolatedIndex=>isolatedIndex<index);return [...new Set([...declared,...earlierIsolated])]};return await runWithConcurrencyGraph(entries,concurrency,dependencyIndexesFor,worker)}finally{uninstall();disposeRunSignal();}}var POLICY_OUTCOMES=["pass","fail","warn"];var OUTPUT_PROPERTIES=new Set(["success","value","error","format"]);function readPropertyOfUndefined(error){if(!(error instanceof TypeError))return void 0;const match=/^Cannot read properties of undefined \(reading '([^']+)'\)$/.exec(error.message);return match?.[1]}function unrequestedOutputProperty(error){const property=readPropertyOfUndefined(error);return property!==void 0&&OUTPUT_PROPERTIES.has(property)?property:void 0}function wrapPolicyFailure(checkId,output,error){if(output===void 0){const property=unrequestedOutputProperty(error);if(property!==void 0){return new PolicyReadUnrequestedOutputError(checkId,property,error)}}else if(!output.success){const property=readPropertyOfUndefined(error);if(property!==void 0){return new PolicyReadFailedParseValueError(checkId,property,error)}}return new PolicyThrewError(checkId,error)}function invalidPolicyResultReason(value){if(typeof value!=="object"||value===null){return `expected an object with "outcome" and "rationale", got ${value===null?"null":typeof value}`}const outcome=value.outcome;if(!POLICY_OUTCOMES.includes(outcome)){return `"outcome" must be "pass", "fail", or "warn", got ${typeof outcome==="string"?`"${outcome}"`:typeof outcome}`}const rationale=value.rationale;if(typeof rationale!=="string"){return `"rationale" must be a string, got ${typeof rationale}`}return void 0}async function runPolicies(entries,evidence){const thrown=[];const checkResults=[];await Promise.all(entries.map(async([checkId,check,checkEvidence],entryIndex)=>{const dependencies={};for(const depId of check.dependsOn??[]){const depEvidence=evidence.checks[depId];if(depEvidence!==void 0)dependencies[depId]=depEvidence;}let outcome;try{const rawResult=await check.policy({result:checkEvidence,evidence,dependencies});const invalidReason=invalidPolicyResultReason(rawResult);if(invalidReason!==void 0){throw new Error(`Policy for check "${checkId}" returned an invalid PolicyResult: ${invalidReason}.`)}outcome=rawResult;}catch(error){thrown.push(wrapPolicyFailure(checkId,checkEvidence.output,error));return}checkResults[entryIndex]=[checkId,outcome];}));if(thrown.length===1){const[only]=thrown;throw only}if(thrown.length>1){throw new AggregateError(thrown,`${String(thrown.length)} check policies threw instead of returning a PolicyResult.`)}const orderedResults=checkResults;const checks=Object.fromEntries(orderedResults);const passed=orderedResults.every(([,result])=>result.outcome!=="fail");return {version:2,passed,checks}}function runRepoContract(config,options){validateRepoContractConfig(config);return runRepoContractAfterValidation(config,options)}async function runRepoContractAfterValidation(config,options){const concurrency=config.concurrency??os__namespace.availableParallelism();const startedAt=new Date;const results=await runChecks(config.checks,concurrency,options);const completedAt=new Date;const{evidence,entries}=await buildEvidence(results,startedAt,completedAt);const verdict=await runPolicies(entries,evidence);return {evidence,verdict}}
+
+exports.DependencyDeclaredLaterError = DependencyDeclaredLaterError;
+exports.InvalidCheckConfigError = InvalidCheckConfigError;
+exports.InvalidRepoContractConfigError = InvalidRepoContractConfigError;
+exports.ParserDependencyMissingError = ParserDependencyMissingError;
+exports.PolicyReadFailedParseValueError = PolicyReadFailedParseValueError;
+exports.PolicyReadUnrequestedOutputError = PolicyReadUnrequestedOutputError;
+exports.PolicyThrewError = PolicyThrewError;
+exports.RepoContractError = RepoContractError;
+exports.UnknownCheckIdError = UnknownCheckIdError;
+exports.defineRepoContract = defineRepoContract;
+exports.runRepoContract = runRepoContract;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map