repo-contract 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +1 -0
  3. package/package.json +1 -1
  4. package/dist/.dts/config/define-repo-contract.d.ts +0 -36
  5. package/dist/.dts/config/define-repo-contract.d.ts.map +0 -1
  6. package/dist/.dts/config/tokenize-command.d.ts +0 -33
  7. package/dist/.dts/config/tokenize-command.d.ts.map +0 -1
  8. package/dist/.dts/config/validate-config.d.ts +0 -32
  9. package/dist/.dts/config/validate-config.d.ts.map +0 -1
  10. package/dist/.dts/errors.d.ts +0 -155
  11. package/dist/.dts/errors.d.ts.map +0 -1
  12. package/dist/.dts/evidence/build-evidence.d.ts +0 -26
  13. package/dist/.dts/evidence/build-evidence.d.ts.map +0 -1
  14. package/dist/.dts/execution/abort-signals.d.ts +0 -29
  15. package/dist/.dts/execution/abort-signals.d.ts.map +0 -1
  16. package/dist/.dts/execution/concurrency-pool.d.ts +0 -14
  17. package/dist/.dts/execution/concurrency-pool.d.ts.map +0 -1
  18. package/dist/.dts/execution/dependency-scheduler.d.ts +0 -30
  19. package/dist/.dts/execution/dependency-scheduler.d.ts.map +0 -1
  20. package/dist/.dts/execution/process-tree.d.ts +0 -59
  21. package/dist/.dts/execution/process-tree.d.ts.map +0 -1
  22. package/dist/.dts/execution/run-checks.d.ts +0 -31
  23. package/dist/.dts/execution/run-checks.d.ts.map +0 -1
  24. package/dist/.dts/execution/spawn-check.d.ts +0 -49
  25. package/dist/.dts/execution/spawn-check.d.ts.map +0 -1
  26. package/dist/.dts/index.d.ts +0 -13
  27. package/dist/.dts/index.d.ts.map +0 -1
  28. package/dist/.dts/parsing/parse-json.d.ts +0 -8
  29. package/dist/.dts/parsing/parse-json.d.ts.map +0 -1
  30. package/dist/.dts/parsing/parse-output.d.ts +0 -10
  31. package/dist/.dts/parsing/parse-output.d.ts.map +0 -1
  32. package/dist/.dts/parsing/parse-text.d.ts +0 -8
  33. package/dist/.dts/parsing/parse-text.d.ts.map +0 -1
  34. package/dist/.dts/parsing/parse-yaml.d.ts +0 -21
  35. package/dist/.dts/parsing/parse-yaml.d.ts.map +0 -1
  36. package/dist/.dts/policy/run-policies.d.ts +0 -38
  37. package/dist/.dts/policy/run-policies.d.ts.map +0 -1
  38. package/dist/.dts/presets/arethetypeswrong.d.ts +0 -39
  39. package/dist/.dts/presets/arethetypeswrong.d.ts.map +0 -1
  40. package/dist/.dts/presets/broken-links.d.ts +0 -16
  41. package/dist/.dts/presets/broken-links.d.ts.map +0 -1
  42. package/dist/.dts/presets/commitlint.d.ts +0 -22
  43. package/dist/.dts/presets/commitlint.d.ts.map +0 -1
  44. package/dist/.dts/presets/dead-code.d.ts +0 -23
  45. package/dist/.dts/presets/dead-code.d.ts.map +0 -1
  46. package/dist/.dts/presets/duplication.d.ts +0 -14
  47. package/dist/.dts/presets/duplication.d.ts.map +0 -1
  48. package/dist/.dts/presets/e2e.d.ts +0 -4
  49. package/dist/.dts/presets/e2e.d.ts.map +0 -1
  50. package/dist/.dts/presets/format.d.ts +0 -4
  51. package/dist/.dts/presets/format.d.ts.map +0 -1
  52. package/dist/.dts/presets/index.d.ts +0 -31
  53. package/dist/.dts/presets/index.d.ts.map +0 -1
  54. package/dist/.dts/presets/license.d.ts +0 -4
  55. package/dist/.dts/presets/license.d.ts.map +0 -1
  56. package/dist/.dts/presets/lint.d.ts +0 -20
  57. package/dist/.dts/presets/lint.d.ts.map +0 -1
  58. package/dist/.dts/presets/markdownlint.d.ts +0 -23
  59. package/dist/.dts/presets/markdownlint.d.ts.map +0 -1
  60. package/dist/.dts/presets/publint.d.ts +0 -13
  61. package/dist/.dts/presets/publint.d.ts.map +0 -1
  62. package/dist/.dts/presets/security-deps.d.ts +0 -4
  63. package/dist/.dts/presets/security-deps.d.ts.map +0 -1
  64. package/dist/.dts/presets/security-secrets.d.ts +0 -4
  65. package/dist/.dts/presets/security-secrets.d.ts.map +0 -1
  66. package/dist/.dts/presets/shared/error-warning-pass-policy.d.ts +0 -13
  67. package/dist/.dts/presets/shared/error-warning-pass-policy.d.ts.map +0 -1
  68. package/dist/.dts/presets/shared/exit-code-fail-rationale.d.ts +0 -23
  69. package/dist/.dts/presets/shared/exit-code-fail-rationale.d.ts.map +0 -1
  70. package/dist/.dts/presets/shared/missing-dependency.d.ts +0 -19
  71. package/dist/.dts/presets/shared/missing-dependency.d.ts.map +0 -1
  72. package/dist/.dts/presets/shared/read-json-report.d.ts +0 -33
  73. package/dist/.dts/presets/shared/read-json-report.d.ts.map +0 -1
  74. package/dist/.dts/presets/shared/terminal-status.d.ts +0 -25
  75. package/dist/.dts/presets/shared/terminal-status.d.ts.map +0 -1
  76. package/dist/.dts/presets/shared/vitest-json-policy.d.ts +0 -20
  77. package/dist/.dts/presets/shared/vitest-json-policy.d.ts.map +0 -1
  78. package/dist/.dts/presets/stylelint.d.ts +0 -17
  79. package/dist/.dts/presets/stylelint.d.ts.map +0 -1
  80. package/dist/.dts/presets/test.d.ts +0 -4
  81. package/dist/.dts/presets/test.d.ts.map +0 -1
  82. package/dist/.dts/presets/typecheck.d.ts +0 -4
  83. package/dist/.dts/presets/typecheck.d.ts.map +0 -1
  84. package/dist/.dts/run-repo-contract.d.ts +0 -38
  85. package/dist/.dts/run-repo-contract.d.ts.map +0 -1
  86. package/dist/.dts/types.d.ts +0 -391
  87. package/dist/.dts/types.d.ts.map +0 -1
  88. package/dist/index.d.cts +0 -1
  89. package/dist/index.d.ts +0 -1
  90. package/dist/presets.d.cts +0 -1
  91. package/dist/presets.d.ts +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,32 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.3.0](https://github.com/MaverickCER/repo-contract/compare/repo-contract-v0.2.1...repo-contract-v0.3.0) (2026-09-03)
4
+
5
+
6
+ ### ⚠ BREAKING CHANGES
7
+
8
+ * defineRepoContract/runRepoContract now require spawn and env on the config (e.g. spawn: child_process.spawn, env: process.env). See ADR 0011 and README's "Supplying spawn/env" section for migration.
9
+
10
+ ### Features
11
+
12
+ * contract engine, self-hosting checks and CI workflows ([97ae128](https://github.com/MaverickCER/repo-contract/commit/97ae128bd96f2c631057f1150068af58cc66b224))
13
+ * contract engine, self-hosting checks and CI workflows ([22b2a3b](https://github.com/MaverickCER/repo-contract/commit/22b2a3b03fe4e44ad7a01b82342d86583926416a))
14
+ * make process spawning and env access consumer-supplied capabilities ([640a961](https://github.com/MaverickCER/repo-contract/commit/640a961b65fd73511586c3b4f6274284bf5172a9))
15
+
16
+
17
+ ### Bug Fixes
18
+
19
+ * clear Socket supply-chain alerts (unminified dist, no prepare script) ([71c9230](https://github.com/MaverickCER/repo-contract/commit/71c92306fcf00e3858f0596c2d56f3272199339d))
20
+ * publish the dist bundle unminified ([266ae47](https://github.com/MaverickCER/repo-contract/commit/266ae47919753c55f10364713fe0c7c5876815b7))
21
+ * remove the prepare install script from the published package ([9153540](https://github.com/MaverickCER/repo-contract/commit/9153540e4f0f1a069e07c12ddfee8ba62827ce5b))
22
+
23
+ ## [0.2.1](https://github.com/MaverickCER/repo-contract/compare/repo-contract-v0.2.0...repo-contract-v0.2.1) (2026-09-03)
24
+
25
+
26
+ ### Documentation
27
+
28
+ * add Socket security badge to README
29
+
3
30
  ## [0.2.0](https://github.com/MaverickCER/repo-contract/compare/repo-contract-v0.1.1...repo-contract-v0.2.0) (2026-09-03)
4
31
 
5
32
 
package/README.md CHANGED
@@ -6,6 +6,7 @@
6
6
  [![Coverage](https://img.shields.io/badge/coverage-%E2%89%A585%25-brightgreen)](scripts/coverage-thresholds.mjs)
7
7
  [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](tsconfig.json)
8
8
  [![Node](https://img.shields.io/node/v/repo-contract.svg)](package.json)
9
+ [![Socket Badge](https://badge.socket.dev/npm/package/repo-contract/latest)](https://badge.socket.dev/npm/package/repo-contract/latest)
9
10
 
10
11
  **Turn your repository's engineering standards into enforceable contracts.**
11
12
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "repo-contract",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Enforce your repository's own quality bar before CI even spins up. Configure arbitrary checks, capture what happened as evidence, and let repository-owned policies determine what passes. repo-contract provides the execution and evidence layer without becoming another CI system or imposing its own definition of code quality.",
5
5
  "keywords": [
6
6
  "contract",
@@ -1,36 +0,0 @@
1
- import type { CheckSchema, RepoContractConfig, ValidatedCheckSchema } from "../types.js";
2
- /**
3
- * Identity function whose only job is type inference: authoring a config
4
- * through `defineRepoContract` lets each check's `output` (present or
5
- * absent, and which format) flow into that same check's `policy` parameter
6
- * type, without the consumer writing any type annotations themselves. It
7
- * also statically validates every check's `dependsOn` against its sibling
8
- * check ids (see `ValidatedCheckSchema`) -- a typo'd or self-referencing id
9
- * fails to compile here rather than only failing at runtime. Performs no
10
- * other validation and no cloning -- `runRepoContract` validates whatever
11
- * config it is ultimately given, whether or not it passed through this
12
- * function first.
13
- *
14
- * `const TChecks` (TypeScript 5.0's `const` type parameter modifier) keeps
15
- * each check's own configuration -- notably whether `output` is present at
16
- * all -- from being widened during inference; without it, TypeScript's
17
- * inference for a `Record` of heterogeneous generic entries does not
18
- * reliably preserve that per-check shape once a callback property
19
- * (`policy`) is also present. See `InferParsedValue` in types.ts for the
20
- * related limitation this does not fully solve.
21
- *
22
- * `TChecks` is inferred from the plain, unwrapped `RepoContractConfig<TChecks>`
23
- * position -- the `ValidatedCheckSchema<TChecks>` constraint on `checks` is
24
- * intersected in afterward, computed from that already-inferred `TChecks`,
25
- * rather than substituted in its place. Inferring `TChecks` directly from a
26
- * mapped/conditional type over itself (as `ValidatedCheckSchema` is) loses
27
- * the contextual typing every check's `policy` callback otherwise gets --
28
- * another real, confirmed TypeScript inference limitation, distinct from
29
- * the `output`-to-`policy` one above.
30
- * @param config - the config to type-check and return unchanged.
31
- * @returns the same `config` object, untouched and uncloned.
32
- */
33
- export declare function defineRepoContract<const TChecks extends CheckSchema>(config: RepoContractConfig<TChecks> & {
34
- readonly checks: ValidatedCheckSchema<TChecks>;
35
- }): RepoContractConfig<TChecks>;
36
- //# sourceMappingURL=define-repo-contract.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"define-repo-contract.d.ts","sourceRoot":"","sources":["../../../src/config/define-repo-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,OAAO,SAAS,WAAW,EAClE,MAAM,EAAE,kBAAkB,CAAC,OAAO,CAAC,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAA;CAAE,GACvF,kBAAkB,CAAC,OAAO,CAAC,CAE7B"}
@@ -1,33 +0,0 @@
1
- /**
2
- * Splits a `run` string into argv (executable + arguments) without invoking
3
- * a shell -- no shell operator is ever executed, no glob is ever expanded by
4
- * this package, no environment variable is ever substituted. The result is
5
- * deterministic: the same input string always produces the same argv array.
6
- *
7
- * Quoting: `'...'` and `"..."` group whitespace into a single argument and
8
- * are themselves stripped from the resulting token. `\` escapes the next
9
- * character (and is itself stripped) when unquoted or inside a double-quoted
10
- * span; inside single quotes it is a literal character, exactly as in every
11
- * POSIX shell -- so a Windows path in single quotes survives intact.
12
- * Unquoted whitespace (space, tab) separates tokens.
13
- *
14
- * Rejected outright (throws `InvalidCheckConfigError`, checkId identifies
15
- * which check's `run` was invalid): any *unquoted* occurrence of a true
16
- * shell/multi-command operator -- `;`, `&`, `|`, a backtick, `$(`, `<`, `>`,
17
- * or a literal newline. A string containing one of these almost always
18
- * reflects a mistaken assumption that shell interpretation is happening;
19
- * the fix is either `run: [...]` (array form, bypasses tokenization
20
- * entirely) or explicit `shell: true`.
21
- *
22
- * Deliberately NOT rejected: glob characters (`*`, `?`, `~`, `[`, `]`, `{`,
23
- * `}`) and a bare `$`. These are common, legitimate literal argv content --
24
- * many CLI tools (eslint, prettier, tsc) accept and internally expand glob
25
- * patterns themselves, e.g. `eslint "src/**\/*.ts"` -- and since no shell is
26
- * ever invoked here, they carry zero shell-injection risk regardless of
27
- * where they appear in the string.
28
- * @param run - the command string to tokenize.
29
- * @param checkId - identifies which check's `run` was invalid, used in the thrown error message.
30
- * @returns the tokenized argv (executable followed by its arguments).
31
- */
32
- export declare function tokenizeRunString(run: string, checkId: string): readonly string[];
33
- //# sourceMappingURL=tokenize-command.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"tokenize-command.d.ts","sourceRoot":"","sources":["../../../src/config/tokenize-command.ts"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAwHjF"}
@@ -1,32 +0,0 @@
1
- import type { RepoContractConfig } from "../types.js";
2
- /**
3
- * Validates a `RepoContractConfig` structurally and throws before any
4
- * process spawns. A config with zero checks is valid (an empty `checks`
5
- * object vacuously satisfies "every check passed"); everything else here is
6
- * a genuine structural problem. Runtime checks are deliberately defensive
7
- * about field types rather than trusting the compile-time type, since a
8
- * config can arrive from plain JavaScript or a widened/cast value.
9
- * @param config - the config to validate; throws if structurally invalid.
10
- */
11
- export declare function validateRepoContractConfig(config: RepoContractConfig): void;
12
- /**
13
- * Whole-graph properties that can't be checked per-check in isolation --
14
- * run once, after every check's own `dependsOn` shape has already been
15
- * validated by `validateDependsOn` above, so this can walk every
16
- * `dependsOn` array without re-checking its shape.
17
- *
18
- * Declaration order in the `checks` object doubles as the required topological order (see
19
- * `CheckDefinition.dependsOn`'s own doc comment): every `dependsOn` id must name a check declared
20
- * earlier* than the check declaring it. This single backward-reference check subsumes what used
21
- * to be two separate passes (an unknown-id check, then a DFS cycle detector) -- a cycle is no
22
- * longer expressible at all once every edge is required to point backward, so there is nothing
23
- * left for a separate cycle detector to catch. `isolated` needs no validation-time edge computation
24
- * here: its own implied positional edges (see `run-checks.ts`'s `dependencyIndexesFor`) always
25
- * point backward (to earlier-declared checks) or are pointed at by later-declared checks, by
26
- * construction, so they can never introduce a cycle either.
27
- * @param checks - the full check map, keyed by check id, in declaration order.
28
- */
29
- export declare function validateDependencyGraph(checks: Record<string, {
30
- dependsOn?: readonly string[];
31
- }>): void;
32
- //# sourceMappingURL=validate-config.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"validate-config.d.ts","sourceRoot":"","sources":["../../../src/config/validate-config.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAgB,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAKnE;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAuE3E;AAqSD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC,GACxD,IAAI,CAoBN"}
@@ -1,155 +0,0 @@
1
- /**
2
- * Error hierarchy for repo-contract. Every concrete error carries a stable
3
- * `code` string for programmatic handling, and never embeds raw
4
- * stdout/stderr/env values in its message -- only check ids and field names
5
- * (see SECURITY.md).
6
- *
7
- * Three distinct failure classes are kept deliberately separate (see
8
- * specs/architecture.md):
9
- * - Structural config problems throw synchronously, before any process
10
- * spawns (`InvalidRepoContractConfigError`, `InvalidCheckConfigError`).
11
- * - Anything only discoverable by attempting execution becomes evidence,
12
- * never a throw (a bad `cwd`, a missing binary -- recorded as
13
- * `status: "spawn_error"` on that check's `CheckEvidence`).
14
- * - A policy function throwing or rejecting is a bug in consumer code, not
15
- * a check failing its contract -- it propagates as a rejected
16
- * `runRepoContract()` promise (`PolicyThrewError`), never silently
17
- * turned into a failed verdict entry.
18
- */
19
- export declare abstract class RepoContractError extends Error {
20
- /** Stable, machine-readable identifier for this error's specific failure mode. */
21
- abstract readonly code: string;
22
- }
23
- /** The top-level `RepoContractConfig` itself is structurally invalid -- e.g. `checks` is not an object, or `concurrency` is not a positive integer. (A `checks` object with zero entries is deliberately valid: the run produces an empty, passing `Verdict`.) Thrown synchronously by `runRepoContract`, before anything spawns -- not by `defineRepoContract`, which performs no runtime validation of its own (see its own doc comment). */
24
- export declare class InvalidRepoContractConfigError extends RepoContractError {
25
- /** Always `"REPO_CONTRACT_INVALID_CONFIG"`. */
26
- readonly code = "REPO_CONTRACT_INVALID_CONFIG";
27
- constructor(reason: string);
28
- }
29
- /** One check's `CheckDefinition` is structurally invalid -- e.g. an empty `run`, a `run` string containing an unquoted shell operator without `shell: true`, or a missing `policy`. Thrown synchronously, before that check (or any other) spawns. */
30
- export declare class InvalidCheckConfigError extends RepoContractError {
31
- /** Always `"REPO_CONTRACT_INVALID_CHECK_CONFIG"`. */
32
- readonly code = "REPO_CONTRACT_INVALID_CHECK_CONFIG";
33
- /** The id of the check whose configuration was invalid. */
34
- readonly checkId: string;
35
- constructor(checkId: string, reason: string);
36
- }
37
- /**
38
- * `RunRepoContractOptions.checks` (a partial-run request) names a check id that doesn't exist in
39
- * the configured `checks`. Unlike a `dependsOn` id (already validated to exist by
40
- * `validateRepoContractConfig` before any run starts), `options.checks` is only ever checked once
41
- * `runChecks` actually resolves it -- there is no earlier structural-validation pass for it.
42
- */
43
- export declare class UnknownCheckIdError extends RepoContractError {
44
- /** Always `"REPO_CONTRACT_UNKNOWN_CHECK_ID"`. */
45
- readonly code = "REPO_CONTRACT_UNKNOWN_CHECK_ID";
46
- /** The unrecognized check id named in `options.checks`. */
47
- readonly checkId: string;
48
- constructor(checkId: string);
49
- }
50
- /**
51
- * A check's `dependsOn` names a check declared *later* in the same `checks` object.
52
- * `dependsOn` may only reference a check declared earlier -- see `CheckDefinition.dependsOn`'s own
53
- * doc comment. Declaration order doubles as the required topological order, so this is the only
54
- * way an invalid dependency graph can arise; a real cycle is structurally impossible once every
55
- * edge points backward. Thrown synchronously, before any check spawns.
56
- */
57
- export declare class DependencyDeclaredLaterError extends RepoContractError {
58
- /** Always `"REPO_CONTRACT_DEPENDENCY_DECLARED_LATER"`. */
59
- readonly code = "REPO_CONTRACT_DEPENDENCY_DECLARED_LATER";
60
- /** The id of the check whose `dependsOn` names a later-declared check. */
61
- readonly checkId: string;
62
- /** The later-declared check id named in `checkId`'s `dependsOn`. */
63
- readonly dependencyId: string;
64
- constructor(checkId: string, dependencyId: string);
65
- }
66
- /** A check requested `output: { format: "yaml" }` but the optional `yaml` peer dependency is not installed. Thrown when that check's output is parsed, not at config-validation time (parsing only happens after the process has already run). */
67
- export declare class ParserDependencyMissingError extends RepoContractError {
68
- /** Always `"REPO_CONTRACT_PARSER_DEPENDENCY_MISSING"`. */
69
- readonly code = "REPO_CONTRACT_PARSER_DEPENDENCY_MISSING";
70
- /** The id of the check whose output could not be parsed. */
71
- readonly checkId: string;
72
- /** The output format that was requested but whose optional peer dependency is missing. */
73
- readonly format: OutputFormatForError;
74
- constructor(checkId: string, format: OutputFormatForError, cause: unknown);
75
- }
76
- type OutputFormatForError = "yaml";
77
- /**
78
- * A check's `policy` function threw synchronously, or returned a `Promise`
79
- * that later rejected. Both failure modes are wrapped identically. The
80
- * original thrown/rejected value is preserved verbatim via the native
81
- * `Error` `cause` chain -- never stringified, summarized, or discarded --
82
- * so a consumer catching this can still inspect exactly what their own
83
- * policy code did wrong.
84
- *
85
- * A policy throwing never stops any other check's policy from running --
86
- * every configured check's policy is invoked exactly once regardless of
87
- * what any other policy does. If more than one policy fails this way in the
88
- * same run, `runRepoContract()` rejects with a native `AggregateError` whose
89
- * `errors` array holds one error per failing check -- `PolicyThrewError`,
90
- * or one of its two narrower siblings below (`PolicyReadUnrequestedOutputError`,
91
- * `PolicyReadFailedParseValueError`) when the failure matches one of their
92
- * more specific shapes -- rather than surfacing only the first one found.
93
- */
94
- export declare class PolicyThrewError extends RepoContractError {
95
- /** Always `"REPO_CONTRACT_POLICY_THREW"`. */
96
- readonly code = "REPO_CONTRACT_POLICY_THREW";
97
- /** The id of the check whose policy threw or rejected. */
98
- readonly checkId: string;
99
- constructor(checkId: string, cause: unknown);
100
- }
101
- /**
102
- * A narrower `runPolicies` throws instead of `PolicyThrewError` when the
103
- * thrown `TypeError`'s own message shows it came from reading a
104
- * `result.output` property (`.success`, `.value`, `.error`, or `.format`),
105
- * and this check's `CheckEvidence.output` really is `undefined` -- which
106
- * happens only when its config never requested `output: { format: ... }` in
107
- * the first place (see `CheckEvidence.output` in types.ts). Detected from
108
- * the `TypeError`'s exact V8-produced message ("Cannot read properties of
109
- * undefined (reading '...')") cross-checked against that `undefined` fact,
110
- * so it is thrown only for a policy that plausibly hit this exact mistake --
111
- * any other `TypeError`, or a check that did request a format, still becomes
112
- * a plain `PolicyThrewError`. This is best-effort inference from the
113
- * `TypeError`'s message text, not a verified trace back to `result.output`
114
- * itself -- V8's message carries only the property name, so an unrelated
115
- * bug that happens to read the same property name off some other
116
- * `undefined` value can still be misclassified this way (see
117
- * `unrequestedOutputProperty` in run-policies.ts). `cause` still holds the
118
- * original `TypeError` verbatim, exactly as `PolicyThrewError` guarantees
119
- * for every other policy failure, so the true cause remains recoverable
120
- * either way.
121
- */
122
- export declare class PolicyReadUnrequestedOutputError extends RepoContractError {
123
- /** Always `"REPO_CONTRACT_POLICY_READ_UNREQUESTED_OUTPUT"`. */
124
- readonly code = "REPO_CONTRACT_POLICY_READ_UNREQUESTED_OUTPUT";
125
- /** The id of the check whose policy read `result.output` without requesting a format. */
126
- readonly checkId: string;
127
- constructor(checkId: string, property: string, cause: unknown);
128
- }
129
- /**
130
- * `PolicyThrewError`'s other special case, alongside
131
- * `PolicyReadUnrequestedOutputError`: this check *did* request
132
- * `output: { format: ... }`, but that parse itself failed
133
- * (`result.output.success === false` -- see `ParsedOutputFailure` in types.ts, which
134
- * has no `value` field, only `error`), and the policy read a property off
135
- * `result.output.value` anyway without checking `.success` first. Detected the same
136
- * way `runPolicies` detects the sibling case -- a thrown `TypeError` whose own
137
- * message shows a property read off `undefined` -- cross-checked against this
138
- * check's own evidence having `output.success === false`, so a genuinely unrelated
139
- * `TypeError`, or a check whose parse actually succeeded, still becomes a plain
140
- * `PolicyThrewError`. Unlike `PolicyReadUnrequestedOutputError`, the read property
141
- * isn't restricted to a known list here -- `result.output.value`'s shape is whatever
142
- * the external tool printed, entirely unknown to repo-contract -- so this match is
143
- * necessarily a little broader. `cause` still holds the original `TypeError`
144
- * verbatim; the message never repeats `result.output.error`'s own text, which may
145
- * contain raw stdout content (see SECURITY.md).
146
- */
147
- export declare class PolicyReadFailedParseValueError extends RepoContractError {
148
- /** Always `"REPO_CONTRACT_POLICY_READ_FAILED_PARSE_VALUE"`. */
149
- readonly code = "REPO_CONTRACT_POLICY_READ_FAILED_PARSE_VALUE";
150
- /** The id of the check whose policy read `result.output.value` after a failed parse. */
151
- readonly checkId: string;
152
- constructor(checkId: string, property: string, cause: unknown);
153
- }
154
- export {};
155
- //# sourceMappingURL=errors.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,iBAAkB,SAAQ,KAAK;IACnD,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAC/B;AAED,+aAA+a;AAC/a,qBAAa,8BAA+B,SAAQ,iBAAiB;IACnE,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,kCAAiC;gBAElC,MAAM,EAAE,MAAM;CAI3B;AAED,sPAAsP;AACtP,qBAAa,uBAAwB,SAAQ,iBAAiB;IAC5D,qDAAqD;IACrD,QAAQ,CAAC,IAAI,wCAAuC;IACpD,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,iBAAiB;IACxD,iDAAiD;IACjD,QAAQ,CAAC,IAAI,oCAAmC;IAChD,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,OAAO,EAAE,MAAM;CAO5B;AAED;;;;;;GAMG;AACH,qBAAa,4BAA6B,SAAQ,iBAAiB;IACjE,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,6CAA4C;IACzD,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;gBAEjB,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAUlD;AAED,kPAAkP;AAClP,qBAAa,4BAA6B,SAAQ,iBAAiB;IACjE,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,6CAA4C;IACzD,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;gBAEzB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,OAAO;CAU1E;AAMD,KAAK,oBAAoB,GAAG,MAAM,CAAA;AAElC;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gBAAiB,SAAQ,iBAAiB;IACrD,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,gCAA+B;IAC5C,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAK5C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gCAAiC,SAAQ,iBAAiB;IACrE,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,kDAAiD;IAC9D,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAY9D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,+BAAgC,SAAQ,iBAAiB;IACpE,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,kDAAiD;IAC9D,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAU9D"}
@@ -1,26 +0,0 @@
1
- import type { CheckExecutionEntry } from "../execution/run-checks.js";
2
- import type { CheckDefinition, CheckEvidence, Evidence } from "../types.js";
3
- /** One check's id, its original definition, and its final evidence (parsed output attached, if requested) -- the parsed-output counterpart to `CheckExecutionEntry`, consumed directly by the policy phase so it never needs to look a check up by id either. */
4
- export type ParsedCheckEntry = readonly [string, CheckDefinition, CheckEvidence];
5
- interface BuiltEvidence {
6
- readonly evidence: Evidence;
7
- readonly entries: readonly ParsedCheckEntry[];
8
- }
9
- /**
10
- * Attaches parsed output (if requested) to every check's raw execution
11
- * evidence and assembles the versioned, immutable `Evidence` object for the
12
- * run as a whole. Also returns the same information as a flat entries array
13
- * (see `ParsedCheckEntry`) for the policy phase to consume directly -- by
14
- * the time this function returns, every check's evidence -- including every
15
- * sibling check's -- is fully assembled; nothing here is generated lazily
16
- * or streamed, which is what makes it safe for a policy to read the full
17
- * `evidence` object, not just its own check's `result` (see
18
- * specs/architecture.md).
19
- * @param results - each check's id, definition, and raw execution evidence from the run phase
20
- * @param startedAt - when the overall run began, recorded on the assembled `Evidence`
21
- * @param completedAt - when the overall run finished, used with `startedAt` to compute the assembled `Evidence`'s `durationMs`
22
- * @returns the assembled `Evidence` for the whole run, plus the same checks as a flat `ParsedCheckEntry` array for the policy phase
23
- */
24
- export declare function buildEvidence(results: readonly CheckExecutionEntry[], startedAt: Date, completedAt: Date): Promise<BuiltEvidence>;
25
- export {};
26
- //# sourceMappingURL=build-evidence.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"build-evidence.d.ts","sourceRoot":"","sources":["../../../src/evidence/build-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAGrE,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3E,iQAAiQ;AACjQ,MAAM,MAAM,gBAAgB,GAAG,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,aAAa,CAAC,CAAA;AAIhF,UAAU,aAAa;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC9C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,SAAS,mBAAmB,EAAE,EACvC,SAAS,EAAE,IAAI,EACf,WAAW,EAAE,IAAI,GAChB,OAAO,CAAC,aAAa,CAAC,CAwDxB"}
@@ -1,29 +0,0 @@
1
- /** The composed signal, and a `dispose` to release any resources this composition holds once it's no longer needed. */
2
- interface ComposedSignal {
3
- readonly signal: AbortSignal;
4
- readonly dispose: () => void;
5
- }
6
- /**
7
- * Combines multiple signals into one that aborts as soon as any input does.
8
- * Prefers the native `AbortSignal.any()` where available; falls back to a
9
- * manual composition for engines without it. `AbortSignal.any` landed in
10
- * Node 20.3.0 -- genuinely newer than this package's `engines.node >=20.0.0`
11
- * floor, so the fallback is live code for a real gap (a 20.0-20.2 patch
12
- * release), not dead code kept out of caution.
13
- *
14
- * The native path's `dispose` is a no-op -- `AbortSignal.any` manages its own
15
- * source-signal listeners internally and doesn't leak them. The manual
16
- * fallback's `dispose` removes the "abort" listeners it added to each input
17
- * `signal`; without calling it, a long-lived input (like a whole run's shared
18
- * `AbortSignal`, composed fresh for every check the run spawns) would
19
- * accumulate one permanent, never-removed listener per composed signal for
20
- * the rest of its own lifetime, regardless of whether that particular
21
- * composition ever actually needed to abort. Callers should call `dispose()`
22
- * once the composed signal is no longer needed, whether or not it ever
23
- * aborted.
24
- * @param signals - the signals to combine; the composed signal aborts as soon as any one of them does
25
- * @returns the composed signal (aborting with that input's abort reason as soon as any signal in `signals` aborts), and a `dispose` to release this composition's own resources
26
- */
27
- export declare function composeSignals(signals: readonly AbortSignal[]): ComposedSignal;
28
- export {};
29
- //# sourceMappingURL=abort-signals.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"abort-signals.d.ts","sourceRoot":"","sources":["../../../src/execution/abort-signals.ts"],"names":[],"mappings":"AAAA,uHAAuH;AACvH,UAAU,cAAc;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,cAAc,CA4B9E"}
@@ -1,14 +0,0 @@
1
- /**
2
- * Runs `worker` over `items` with at most `concurrency` invocations in
3
- * flight at once, preserving each result at its original index regardless
4
- * of completion order. Has no knowledge of aborting, killing, or check
5
- * evidence -- a pure, reusable bounded-parallelism primitive; abort-
6
- * awareness lives entirely in the caller's `worker` function (see
7
- * spawn-check.ts).
8
- * @param items - the items to process, each passed to `worker` along with its index
9
- * @param concurrency - the maximum number of `worker` calls allowed in flight at once
10
- * @param worker - the async function run per item; its resolved value becomes that item's result
11
- * @returns the results, one per item, in the same order as `items` regardless of completion order
12
- */
13
- export declare function runWithConcurrency<T, R>(items: readonly T[], concurrency: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
14
- //# sourceMappingURL=concurrency-pool.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"concurrency-pool.d.ts","sourceRoot":"","sources":["../../../src/execution/concurrency-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,EAAE,CAAC,CA+Cd"}
@@ -1,30 +0,0 @@
1
- /**
2
- * Runs `worker` over `items` with at most `concurrency` invocations in
3
- * flight at once, like `concurrency-pool.ts`'s `runWithConcurrency`, but
4
- * additionally respecting a dependency graph: an item whose
5
- * `dependencyIndexes` are non-empty is not started until every one of
6
- * those indexes has settled. Has no knowledge of checks, evidence, or
7
- * abort semantics -- a pure, reusable bounded-parallelism-plus-ordering
8
- * primitive, kept in its own file rather than folded into
9
- * `concurrency-pool.ts` so that file's simpler, more heavily-used flat
10
- * primitive stays untouched.
11
- *
12
- * A reactive, event-driven scheduler (conceptually Kahn's algorithm run
13
- * incrementally): a completing item immediately re-evaluates and unblocks
14
- * its own dependents, with no artificial "wave" boundary -- a wave/layer
15
- * design was considered and rejected because it would stall a dependent
16
- * whose single dependency finished early behind an unrelated slow item
17
- * sharing its layer, a real regression for a diamond or fan-out shape.
18
- *
19
- * The caller is responsible for ensuring `dependencyIndexes` describes an
20
- * acyclic graph (see `validate-config.ts`'s cycle detection) -- this
21
- * function's own stall guard below exists only as defense in depth against
22
- * that invariant being violated, not as the primary means of catching it.
23
- * @param items - the items to process, each passed to `worker` and `dependencyIndexes` along with its index
24
- * @param concurrency - the maximum number of `worker` calls allowed in flight at once
25
- * @param dependencyIndexes - given an item and its index, returns the indexes into `items` that must settle first
26
- * @param worker - the async function run per item once its dependencies have settled; its resolved value becomes that item's result
27
- * @returns the results, one per item, in the same order as `items` regardless of completion order
28
- */
29
- export declare function runWithConcurrencyGraph<T, R>(items: readonly T[], concurrency: number, dependencyIndexes: (item: T, index: number) => readonly number[], worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
30
- //# sourceMappingURL=dependency-scheduler.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"dependency-scheduler.d.ts","sourceRoot":"","sources":["../../../src/execution/dependency-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAChD,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,iBAAiB,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,EAChE,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,EAAE,CAAC,CAsLd"}
@@ -1,59 +0,0 @@
1
- import type { SyncSpawner } from "../types.js";
2
- /**
3
- * Whether a check's process should be spawned with `detached: true`. On
4
- * POSIX this makes the spawned process the leader of a new process group
5
- * (sharing its own pid as the group id), which is what lets `killTree`
6
- * target the whole group rather than just the immediate child. On Windows,
7
- * process groups work differently and `detached: true` would instead launch
8
- * the process in its own console window -- not what's wanted here, since
9
- * Windows cleanup goes through `taskkill /t` instead (see `killTree`).
10
- * @returns true on POSIX (spawn as its own process group leader, killable via `killTree`); false on Windows
11
- */
12
- export declare function shouldSpawnDetached(): boolean;
13
- /**
14
- * Best-effort termination of an entire process tree rooted at `pid`, not
15
- * just the immediate process -- necessary because a check's command is
16
- * often itself a wrapper (`npm run test` spawns `npm`, which spawns the
17
- * actual test runner), and killing only the wrapper would orphan its
18
- * descendants. `spawn`'s own `timeout`/`signal` options only ever affect the
19
- * directly spawned process, never its descendants, which is why this exists
20
- * as a separate utility rather than relying on those.
21
- *
22
- * On POSIX, sends `signal` to the whole process group via the negative-pid
23
- * convention (requires the process to have been spawned with
24
- * `detached: true`, see `shouldSpawnDetached`) -- no process spawning
25
- * required, a single syscall via `process.kill`. On Windows, process groups
26
- * don't work the same way, so this shells out to `taskkill /pid <pid> /t
27
- * /f` -- the same technique the `tree-kill` package uses internally -- which
28
- * walks the system process table for descendants of `pid` regardless of how
29
- * it was spawned; that requires a synchronous spawn, which -- like every
30
- * other process-spawning capability in this package -- is a trusted
31
- * capability the caller supplies (`killProcessTree`, threaded from
32
- * `RepoContractConfig.killProcessTree`), never imported internally (see
33
- * specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md).
34
- * When `killProcessTree` is omitted on Windows, this function is a
35
- * documented no-op -- the caller (`spawn-check.ts`) falls back to
36
- * terminating just the tracked child process handle directly, which needs
37
- * no spawn at all.
38
- *
39
- * Swallows the expected best-effort-cleanup failures, but not every failure: a
40
- * process that has already exited (POSIX `ESRCH`, or `taskkill`'s "not found"
41
- * case) is a no-op, and a POSIX `EPERM` permission error is swallowed the same
42
- * way -- by the time cleanup runs the process may well have exited on its own,
43
- * and a failed cleanup should not crash the run. Any *other* failure is
44
- * rethrown: an unexpected POSIX errno, or (on Windows) a JS-level spawn failure
45
- * of `taskkill` itself (`result.error`, e.g. the tool missing from PATH), which
46
- * would otherwise silently leave an orphaned process tree behind.
47
- *
48
- * On Windows this always runs `taskkill` with `/f` regardless of which `signal` was requested --
49
- * not a partial implementation of POSIX's cooperative-SIGTERM-then-SIGKILL escalation, but a
50
- * reflection of a real platform difference: Windows has no signal-delivery mechanism for an
51
- * arbitrary process tree by pid at all (this is also why Node's own `ChildProcess.kill()` treats
52
- * every signal identically on Windows, per Node's own child_process documentation), so there is no
53
- * more-cooperative alternative to fall back to here the way there is on POSIX.
54
- * @param pid - the pid of the tree's root process (the process group id on POSIX, since it was spawned detached)
55
- * @param signal - the POSIX signal to send (on Windows, ignored -- see doc comment above)
56
- * @param killProcessTree - the consumer-supplied synchronous spawner used only on Windows; a no-op there when omitted (see doc comment above)
57
- */
58
- export declare function killTree(pid: number, signal: NodeJS.Signals, killProcessTree?: SyncSpawner): void;
59
- //# sourceMappingURL=process-tree.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"process-tree.d.ts","sourceRoot":"","sources":["../../../src/execution/process-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,WAAW,GAAG,IAAI,CAoDjG"}
@@ -1,31 +0,0 @@
1
- import type { CheckDefinition, CheckEvidence, CheckSchema, RunRepoContractOptions } from "../types.js";
2
- import type { ExecutionCapability } from "./spawn-check.js";
3
- /**
4
- * One check's id, its original definition, and its raw execution evidence,
5
- * threaded together as a triple rather than three separately-keyed maps --
6
- * every later stage (parsing, policy evaluation) consumes this directly
7
- * instead of re-looking a check up by id, which under `noUncheckedIndexedAccess`
8
- * would otherwise force handling an "undefined" case that can't actually
9
- * happen (every checkId here comes from the same `Object.entries(checks)`
10
- * that produced it).
11
- */
12
- export type CheckExecutionEntry = readonly [string, CheckDefinition, CheckEvidence];
13
- export declare const SELF_TERMINATE_DELAY_MS: number;
14
- /**
15
- * Executes every resolved check with at most `concurrency` running at once,
16
- * returning each check's raw evidence keyed by check id. For a full run
17
- * (`options.checks` omitted), every configured check id is resolved and
18
- * therefore appears in the result exactly once, regardless of whether it
19
- * ever actually spawned (see spawnCheck's documentation for the pre-aborted
20
- * case). When `options.checks` restricts execution to a subset, only the
21
- * requested ids and their transitive `dependsOn` are resolved (see
22
- * `resolveCheckDependencies` above) -- every other configured check id is
23
- * simply absent from the result, not present with some placeholder value.
24
- * @param checks - the full set of configured checks, keyed by id
25
- * @param concurrency - the maximum number of checks to run in parallel at once
26
- * @param execution - the run's trusted execution capabilities (`spawn`, `env`, resolved global `shell` default), forwarded to every `spawnCheck` call
27
- * @param options - run options; `options.checks` restricts execution to those ids (plus their dependencies), `options.signal` cancels the whole run
28
- * @returns each executed check's id, definition, and raw evidence, one entry per resolved check regardless of whether it actually spawned
29
- */
30
- export declare function runChecks(checks: CheckSchema, concurrency: number, execution: ExecutionCapability, options?: RunRepoContractOptions): Promise<readonly CheckExecutionEntry[]>;
31
- //# sourceMappingURL=run-checks.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"run-checks.d.ts","sourceRoot":"","sources":["../../../src/execution/run-checks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,WAAW,EACX,sBAAsB,EACvB,MAAM,aAAa,CAAA;AAIpB,OAAO,KAAK,EAAqB,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAG9E;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,aAAa,CAAC,CAAA;AAYnF,eAAO,MAAM,uBAAuB,QAAgC,CAAA;AAoJpE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,mBAAmB,EAC9B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC,CAkJzC"}
@@ -1,49 +0,0 @@
1
- import type { CheckDefinition, CheckEvidence, Spawner, SyncSpawner } from "../types.js";
2
- /**
3
- * The trusted execution capabilities a run supplies once (see
4
- * specs/decisions/0011-process-spawning-and-ambient-environment-access-are-consumer-supplied-capabilities-not-package-owned.md)
5
- * and every spawned check draws from -- `spawn`/`env` verbatim from
6
- * `RepoContractConfig`, `shell` already resolved to its effective global
7
- * default (`config.shell ?? false`). Internal only: not exported from
8
- * `src/types.ts` or `src/index.ts`. Grouped into one object, rather than
9
- * threaded as independent parameters through `run-repo-contract.ts` ->
10
- * `run-checks.ts` -> `spawn-check.ts`, purely to keep related
11
- * execution-capability concerns from drifting into unrelated positional
12
- * parameters as more get added later.
13
- */
14
- export interface ExecutionCapability {
15
- readonly spawn: Spawner;
16
- readonly env: NodeJS.ProcessEnv;
17
- readonly shell: boolean;
18
- readonly killProcessTree?: SyncSpawner;
19
- }
20
- export declare const SIGKILL_GRACE_PERIOD_MS = 2000;
21
- /** Handle a caller can use to forcibly terminate one in-flight check's process tree, independent of that check's own timeout/abort wiring -- used by run-checks.ts to clean up every active check when the host process itself receives SIGINT/SIGTERM. */
22
- export interface ActiveCheckHandle {
23
- kill(signal: NodeJS.Signals): void;
24
- }
25
- /**
26
- * Runs one configured check end to end: resolves its command, spawns it,
27
- * enforces its timeout (if any), reacts to the run-level `AbortSignal` (if
28
- * any), captures stdout/stderr, and resolves to a fully-formed
29
- * `CheckEvidence` no matter how the process ended -- this function never
30
- * rejects. `activeHandles` is a shared registry the caller (run-checks.ts)
31
- * uses to kill every in-flight check on a host-process SIGINT/SIGTERM; this
32
- * function adds its own handle once the process has a pid and removes it
33
- * once the process has settled.
34
- *
35
- * A check whose `runSignal` is already aborted before this function is even
36
- * invoked (queued behind the concurrency limit when the run was cancelled)
37
- * never spawns at all, but still resolves to a well-formed `status:
38
- * "aborted"` evidence entry -- every configured check gets evidence and a
39
- * policy invocation regardless of whether it ever ran (see
40
- * specs/architecture.md).
41
- * @param checkId - the check's id, used for logging and passed through to `resolveCommand`
42
- * @param check - the check definition to run (command, timeout, env, cwd, shell, etc.)
43
- * @param runSignal - the whole run's abort signal, if any; already-aborted before this is called means the check never spawns
44
- * @param activeHandles - the shared registry this check's kill handle is added to while running, so a host-process SIGINT/SIGTERM can terminate it
45
- * @param execution - the run's trusted execution capabilities (`spawn`, `env`, resolved global `shell` default) -- see `ExecutionCapability`
46
- * @returns a fully-formed `CheckEvidence` reflecting however the process ended; this function itself never rejects
47
- */
48
- export declare function spawnCheck(checkId: string, check: CheckDefinition, runSignal: AbortSignal | undefined, activeHandles: Set<ActiveCheckHandle>, execution: ExecutionCapability): Promise<CheckEvidence>;
49
- //# sourceMappingURL=spawn-check.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"spawn-check.d.ts","sourceRoot":"","sources":["../../../src/execution/spawn-check.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAe,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAIpG;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,WAAW,CAAA;CACvC;AA2BD,eAAO,MAAM,uBAAuB,OAAO,CAAA;AA6D3C,2PAA2P;AAC3P,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;CACnC;AAyHD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,WAAW,GAAG,SAAS,EAClC,aAAa,EAAE,GAAG,CAAC,iBAAiB,CAAC,EACrC,SAAS,EAAE,mBAAmB,GAC7B,OAAO,CAAC,aAAa,CAAC,CA4QxB"}
@@ -1,13 +0,0 @@
1
- /**
2
- * Public API of repo-contract. Curated barrel -- internal implementation
3
- * modules (src/execution/, src/parsing/, src/policy/, src/config/'s
4
- * lower-level pieces) are not re-exported here even though they exist as
5
- * real files; only the two functions and the types a consumer needs to
6
- * author a config and interpret its result are part of the public surface.
7
- * @packageDocumentation
8
- */
9
- export { defineRepoContract } from "./config/define-repo-contract.js";
10
- export { runRepoContract } from "./run-repo-contract.js";
11
- export { DependencyDeclaredLaterError, InvalidCheckConfigError, InvalidRepoContractConfigError, ParserDependencyMissingError, PolicyReadFailedParseValueError, PolicyReadUnrequestedOutputError, PolicyThrewError, RepoContractError, UnknownCheckIdError, } from "./errors.js";
12
- export type { CheckDefinition, CheckDefinitionConfig, CheckEvidence, CheckSchema, CheckStatus, Evidence, OutputFormat, ParsedOutput, ParsedOutputFailure, ParsedOutputSuccess, Policy, PolicyContext, PolicyOutcome, PolicyResult, RepoContractConfig, RunRepoContractOptions, Spawner, SyncSpawner, ValidatedCheckSchema, Verdict, } from "./types.js";
13
- //# sourceMappingURL=index.d.ts.map