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.
- package/CHANGELOG.md +27 -0
- package/README.md +1 -0
- package/package.json +1 -1
- package/dist/.dts/config/define-repo-contract.d.ts +0 -36
- package/dist/.dts/config/define-repo-contract.d.ts.map +0 -1
- package/dist/.dts/config/tokenize-command.d.ts +0 -33
- package/dist/.dts/config/tokenize-command.d.ts.map +0 -1
- package/dist/.dts/config/validate-config.d.ts +0 -32
- package/dist/.dts/config/validate-config.d.ts.map +0 -1
- package/dist/.dts/errors.d.ts +0 -155
- package/dist/.dts/errors.d.ts.map +0 -1
- package/dist/.dts/evidence/build-evidence.d.ts +0 -26
- package/dist/.dts/evidence/build-evidence.d.ts.map +0 -1
- package/dist/.dts/execution/abort-signals.d.ts +0 -29
- package/dist/.dts/execution/abort-signals.d.ts.map +0 -1
- package/dist/.dts/execution/concurrency-pool.d.ts +0 -14
- package/dist/.dts/execution/concurrency-pool.d.ts.map +0 -1
- package/dist/.dts/execution/dependency-scheduler.d.ts +0 -30
- package/dist/.dts/execution/dependency-scheduler.d.ts.map +0 -1
- package/dist/.dts/execution/process-tree.d.ts +0 -59
- package/dist/.dts/execution/process-tree.d.ts.map +0 -1
- package/dist/.dts/execution/run-checks.d.ts +0 -31
- package/dist/.dts/execution/run-checks.d.ts.map +0 -1
- package/dist/.dts/execution/spawn-check.d.ts +0 -49
- package/dist/.dts/execution/spawn-check.d.ts.map +0 -1
- package/dist/.dts/index.d.ts +0 -13
- package/dist/.dts/index.d.ts.map +0 -1
- package/dist/.dts/parsing/parse-json.d.ts +0 -8
- package/dist/.dts/parsing/parse-json.d.ts.map +0 -1
- package/dist/.dts/parsing/parse-output.d.ts +0 -10
- package/dist/.dts/parsing/parse-output.d.ts.map +0 -1
- package/dist/.dts/parsing/parse-text.d.ts +0 -8
- package/dist/.dts/parsing/parse-text.d.ts.map +0 -1
- package/dist/.dts/parsing/parse-yaml.d.ts +0 -21
- package/dist/.dts/parsing/parse-yaml.d.ts.map +0 -1
- package/dist/.dts/policy/run-policies.d.ts +0 -38
- package/dist/.dts/policy/run-policies.d.ts.map +0 -1
- package/dist/.dts/presets/arethetypeswrong.d.ts +0 -39
- package/dist/.dts/presets/arethetypeswrong.d.ts.map +0 -1
- package/dist/.dts/presets/broken-links.d.ts +0 -16
- package/dist/.dts/presets/broken-links.d.ts.map +0 -1
- package/dist/.dts/presets/commitlint.d.ts +0 -22
- package/dist/.dts/presets/commitlint.d.ts.map +0 -1
- package/dist/.dts/presets/dead-code.d.ts +0 -23
- package/dist/.dts/presets/dead-code.d.ts.map +0 -1
- package/dist/.dts/presets/duplication.d.ts +0 -14
- package/dist/.dts/presets/duplication.d.ts.map +0 -1
- package/dist/.dts/presets/e2e.d.ts +0 -4
- package/dist/.dts/presets/e2e.d.ts.map +0 -1
- package/dist/.dts/presets/format.d.ts +0 -4
- package/dist/.dts/presets/format.d.ts.map +0 -1
- package/dist/.dts/presets/index.d.ts +0 -31
- package/dist/.dts/presets/index.d.ts.map +0 -1
- package/dist/.dts/presets/license.d.ts +0 -4
- package/dist/.dts/presets/license.d.ts.map +0 -1
- package/dist/.dts/presets/lint.d.ts +0 -20
- package/dist/.dts/presets/lint.d.ts.map +0 -1
- package/dist/.dts/presets/markdownlint.d.ts +0 -23
- package/dist/.dts/presets/markdownlint.d.ts.map +0 -1
- package/dist/.dts/presets/publint.d.ts +0 -13
- package/dist/.dts/presets/publint.d.ts.map +0 -1
- package/dist/.dts/presets/security-deps.d.ts +0 -4
- package/dist/.dts/presets/security-deps.d.ts.map +0 -1
- package/dist/.dts/presets/security-secrets.d.ts +0 -4
- package/dist/.dts/presets/security-secrets.d.ts.map +0 -1
- package/dist/.dts/presets/shared/error-warning-pass-policy.d.ts +0 -13
- package/dist/.dts/presets/shared/error-warning-pass-policy.d.ts.map +0 -1
- package/dist/.dts/presets/shared/exit-code-fail-rationale.d.ts +0 -23
- package/dist/.dts/presets/shared/exit-code-fail-rationale.d.ts.map +0 -1
- package/dist/.dts/presets/shared/missing-dependency.d.ts +0 -19
- package/dist/.dts/presets/shared/missing-dependency.d.ts.map +0 -1
- package/dist/.dts/presets/shared/read-json-report.d.ts +0 -33
- package/dist/.dts/presets/shared/read-json-report.d.ts.map +0 -1
- package/dist/.dts/presets/shared/terminal-status.d.ts +0 -25
- package/dist/.dts/presets/shared/terminal-status.d.ts.map +0 -1
- package/dist/.dts/presets/shared/vitest-json-policy.d.ts +0 -20
- package/dist/.dts/presets/shared/vitest-json-policy.d.ts.map +0 -1
- package/dist/.dts/presets/stylelint.d.ts +0 -17
- package/dist/.dts/presets/stylelint.d.ts.map +0 -1
- package/dist/.dts/presets/test.d.ts +0 -4
- package/dist/.dts/presets/test.d.ts.map +0 -1
- package/dist/.dts/presets/typecheck.d.ts +0 -4
- package/dist/.dts/presets/typecheck.d.ts.map +0 -1
- package/dist/.dts/run-repo-contract.d.ts +0 -38
- package/dist/.dts/run-repo-contract.d.ts.map +0 -1
- package/dist/.dts/types.d.ts +0 -391
- package/dist/.dts/types.d.ts.map +0 -1
- package/dist/index.d.cts +0 -1
- package/dist/index.d.ts +0 -1
- package/dist/presets.d.cts +0 -1
- 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
|
[](scripts/coverage-thresholds.mjs)
|
|
7
7
|
[](tsconfig.json)
|
|
8
8
|
[](package.json)
|
|
9
|
+
[](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.
|
|
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"}
|
package/dist/.dts/errors.d.ts
DELETED
|
@@ -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"}
|
package/dist/.dts/index.d.ts
DELETED
|
@@ -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
|