@maverickcer/env-cap 0.7.3 → 0.7.5
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/ADOPTION.md +106 -124
- package/AGENTS.md +14 -13
- package/CHANGELOG.md +23 -0
- package/CODE_REVIEW.md +69 -173
- package/CONTRIBUTING.md +57 -74
- package/GUIDE.md +393 -872
- package/README.md +82 -77
- package/RELEASING.md +17 -15
- package/SECURITY.md +76 -227
- package/SUPPORT.md +21 -45
- package/VERSIONING.md +68 -105
- package/benchmarks/READING-BENCHMARKS.md +13 -7
- package/benchmarks/WRITING-BENCHMARKS.md +1 -1
- package/dist/.dts/_ipc/build-fs.d.ts +9 -14
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
- package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
- package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
- package/dist/.dts/_ipc/glob.d.ts +6 -6
- package/dist/.dts/_ipc/no-node-fs.d.ts +0 -14
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/build/lifecycle-model.d.ts +8 -3
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts/build/sarif.d.ts.map +1 -1
- package/dist/.dts/helpers/index.d.ts +1 -1
- package/dist/.dts/runtime/create.d.ts +3 -0
- package/dist/.dts/runtime/create.d.ts.map +1 -1
- package/dist/.dts/runtime/document.d.ts +7 -4
- package/dist/.dts/runtime/document.d.ts.map +1 -1
- package/dist/.dts/runtime/index.d.ts +11 -10
- package/dist/.dts/runtime/index.d.ts.map +1 -1
- package/dist/.dts/runtime/types.d.ts +16 -0
- package/dist/.dts/runtime/types.d.ts.map +1 -1
- package/dist/.dts/runtime/validate.d.ts +14 -1
- package/dist/.dts/runtime/validate.d.ts.map +1 -1
- package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
- package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/_ipc/display-path.d.ts +27 -0
- package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/_ipc/glob.d.ts +22 -0
- package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/_ipc/typescript.d.ts +20 -0
- package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/assemble-project.d.ts +47 -0
- package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
- package/dist/.dts7/build/change-model.d.ts +63 -0
- package/dist/.dts7/build/change-model.d.ts.map +1 -0
- package/dist/.dts7/build/check-artifacts.d.ts +48 -0
- package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/citation-verification.d.ts +62 -0
- package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
- package/dist/.dts7/build/compatibility.d.ts +83 -0
- package/dist/.dts7/build/compatibility.d.ts.map +1 -0
- package/dist/.dts7/build/compiler-api.d.ts +12 -0
- package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/build/contract-model.d.ts +93 -0
- package/dist/.dts7/build/contract-model.d.ts.map +1 -0
- package/dist/.dts7/build/deep-equal.d.ts +9 -0
- package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
- package/dist/.dts7/build/deep-freeze.d.ts +20 -0
- package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-graph.d.ts +170 -0
- package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-model.d.ts +81 -0
- package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
- package/dist/.dts7/build/discover.d.ts +41 -0
- package/dist/.dts7/build/discover.d.ts.map +1 -0
- package/dist/.dts7/build/display-path.d.ts +6 -0
- package/dist/.dts7/build/display-path.d.ts.map +1 -0
- package/dist/.dts7/build/docs.d.ts +176 -0
- package/dist/.dts7/build/docs.d.ts.map +1 -0
- package/dist/.dts7/build/env-example.d.ts +85 -0
- package/dist/.dts7/build/env-example.d.ts.map +1 -0
- package/dist/.dts7/build/errors.d.ts +78 -0
- package/dist/.dts7/build/errors.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-cache.d.ts +74 -0
- package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-model.d.ts +50 -0
- package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-reference.d.ts +67 -0
- package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
- package/dist/.dts7/build/exclusive-group.d.ts +19 -0
- package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
- package/dist/.dts7/build/finding-model.d.ts +80 -0
- package/dist/.dts7/build/finding-model.d.ts.map +1 -0
- package/dist/.dts7/build/generate-documentation.d.ts +176 -0
- package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/generate-evidence.d.ts +77 -0
- package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
- package/dist/.dts7/build/generate-manifest.d.ts +101 -0
- package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
- package/dist/.dts7/build/generate-usage.d.ts +95 -0
- package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
- package/dist/.dts7/build/generated-banner.d.ts +43 -0
- package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/build/glob.d.ts +6 -0
- package/dist/.dts7/build/glob.d.ts.map +1 -0
- package/dist/.dts7/build/governance-fields.d.ts +34 -0
- package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
- package/dist/.dts7/build/humanize-key.d.ts +14 -0
- package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
- package/dist/.dts7/build/index.d.ts +105 -0
- package/dist/.dts7/build/index.d.ts.map +1 -0
- package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
- package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
- package/dist/.dts7/build/link.d.ts +223 -0
- package/dist/.dts7/build/link.d.ts.map +1 -0
- package/dist/.dts7/build/literal-eval.d.ts +24 -0
- package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
- package/dist/.dts7/build/live-expirations.d.ts +47 -0
- package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
- package/dist/.dts7/build/manifest.d.ts +31 -0
- package/dist/.dts7/build/manifest.d.ts.map +1 -0
- package/dist/.dts7/build/map-utils.d.ts +8 -0
- package/dist/.dts7/build/map-utils.d.ts.map +1 -0
- package/dist/.dts7/build/merge-documentation.d.ts +35 -0
- package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/ownership-model.d.ts +59 -0
- package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
- package/dist/.dts7/build/parse.d.ts +207 -0
- package/dist/.dts7/build/parse.d.ts.map +1 -0
- package/dist/.dts7/build/reference-projections.d.ts +170 -0
- package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
- package/dist/.dts7/build/sarif.d.ts +66 -0
- package/dist/.dts7/build/sarif.d.ts.map +1 -0
- package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
- package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
- package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
- package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
- package/dist/.dts7/build/source-position.d.ts +69 -0
- package/dist/.dts7/build/source-position.d.ts.map +1 -0
- package/dist/.dts7/build/tool-version.d.ts +8 -0
- package/dist/.dts7/build/tool-version.d.ts.map +1 -0
- package/dist/.dts7/build/types.d.ts +7 -0
- package/dist/.dts7/build/types.d.ts.map +1 -0
- package/dist/.dts7/build/typescript.d.ts +6 -0
- package/dist/.dts7/build/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/usage-report.d.ts +124 -0
- package/dist/.dts7/build/usage-report.d.ts.map +1 -0
- package/dist/.dts7/cli/filesystem.d.ts +7 -0
- package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
- package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
- package/dist/.dts7/evidence/define-projection.d.ts +52 -0
- package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
- package/dist/.dts7/evidence/index.d.ts +23 -0
- package/dist/.dts7/evidence/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/index.d.ts +135 -0
- package/dist/.dts7/helpers/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/processors.d.ts +32 -0
- package/dist/.dts7/helpers/processors.d.ts.map +1 -0
- package/dist/.dts7/helpers/validators.d.ts +68 -0
- package/dist/.dts7/helpers/validators.d.ts.map +1 -0
- package/dist/.dts7/node/index.d.ts +2 -0
- package/dist/.dts7/node/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/cache.d.ts +17 -0
- package/dist/.dts7/runtime/cache.d.ts.map +1 -0
- package/dist/.dts7/runtime/create.d.ts +23 -0
- package/dist/.dts7/runtime/create.d.ts.map +1 -0
- package/dist/.dts7/runtime/document.d.ts +223 -0
- package/dist/.dts7/runtime/document.d.ts.map +1 -0
- package/dist/.dts7/runtime/errors.d.ts +55 -0
- package/dist/.dts7/runtime/errors.d.ts.map +1 -0
- package/dist/.dts7/runtime/index.d.ts +25 -0
- package/dist/.dts7/runtime/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/registry.d.ts +12 -0
- package/dist/.dts7/runtime/registry.d.ts.map +1 -0
- package/dist/.dts7/runtime/reset.d.ts +8 -0
- package/dist/.dts7/runtime/reset.d.ts.map +1 -0
- package/dist/.dts7/runtime/types.d.ts +191 -0
- package/dist/.dts7/runtime/types.d.ts.map +1 -0
- package/dist/.dts7/runtime/validate.d.ts +27 -0
- package/dist/.dts7/runtime/validate.d.ts.map +1 -0
- package/dist/{build-LFHPVDQL.js → build-DNAYWD2B.js} +8 -5
- package/dist/build-DNAYWD2B.js.map +1 -0
- package/dist/build.cjs +7 -4
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +7 -4
- package/dist/build.js.map +1 -1
- package/dist/build.ts7.d.cts +1 -0
- package/dist/build.ts7.d.ts +1 -0
- package/dist/{chunk-ZW3BLAPD.js → chunk-HAGMVMN5.js} +2 -2
- package/dist/cli/index.js +3 -3
- package/dist/eslint-plugin/index.cjs +8 -5
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +8 -5
- package/dist/eslint-plugin/index.js.map +1 -1
- package/dist/eslint-plugin/index.ts7.d.cts +1 -0
- package/dist/eslint-plugin/index.ts7.d.ts +1 -0
- package/dist/evidence.ts7.d.cts +1 -0
- package/dist/evidence.ts7.d.ts +1 -0
- package/dist/helpers.ts7.d.cts +1 -0
- package/dist/helpers.ts7.d.ts +1 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/index.ts7.d.cts +1 -0
- package/dist/index.ts7.d.ts +1 -0
- package/dist/node.ts7.d.cts +1 -0
- package/dist/node.ts7.d.ts +1 -0
- package/examples/README.md +46 -80
- package/package.json +37 -6
- package/schemas/env-cap-report.schema.json +1 -1
- package/skills/env-cap/SKILL.md +1 -1
- package/skills/env-cap/references/api.md +1 -1
- package/specs/architecture.md +2 -2
- package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
- package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
- package/specs/generated-artifacts.md +14 -2
- package/dist/build-LFHPVDQL.js.map +0 -1
- /package/dist/{chunk-ZW3BLAPD.js.map → chunk-HAGMVMN5.js.map} +0 -0
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import type { GenerateEnvArtifactsOptions } from "./generate-env-artifacts.js";
|
|
2
|
+
/**
|
|
3
|
+
* `--check` / drift-guard support: computes every requested artifact exactly
|
|
4
|
+
* as a real run would, but never writes to any of the four real target
|
|
5
|
+
* paths. See ADR 0016.
|
|
6
|
+
*/
|
|
7
|
+
/** One artifact's drift status, as found by {@link checkEnvArtifacts}. */
|
|
8
|
+
export interface ArtifactCheckFinding {
|
|
9
|
+
/** Which generated artifact this finding is about. */
|
|
10
|
+
readonly artifact: "manifest" | "docs" | "envExample" | "usage" | "evidence";
|
|
11
|
+
/** Absolute path the artifact would be written to. */
|
|
12
|
+
readonly path: string;
|
|
13
|
+
/** `"missing"` if the file doesn't exist yet, `"stale"` if it exists but differs from what a real run would produce. */
|
|
14
|
+
readonly status: "ok" | "stale" | "missing";
|
|
15
|
+
/** Human-readable detail, set for `"stale"`/`"missing"` findings. */
|
|
16
|
+
readonly detail?: string;
|
|
17
|
+
}
|
|
18
|
+
/** The result of a completed {@link checkEnvArtifacts} run. */
|
|
19
|
+
export interface CheckEnvArtifactsResult {
|
|
20
|
+
/** `true` iff every requested artifact is `"ok"`. */
|
|
21
|
+
readonly ok: boolean;
|
|
22
|
+
/** One entry per requested artifact. */
|
|
23
|
+
readonly findings: readonly ArtifactCheckFinding[];
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Parses `text` as an `EvidenceModel` and re-serializes it with
|
|
27
|
+
* `provenance.generatedAt` normalized out (see `normalizeEvidenceSnapshotForComparison()`)
|
|
28
|
+
* -- so `--check` never reports drift solely because a fresh render's
|
|
29
|
+
* timestamp differs from the committed file's. A parse failure returns
|
|
30
|
+
* `text` unchanged, so a corrupted on-disk file simply fails to match
|
|
31
|
+
* `expected`'s normalized form (reported as `"stale"`), rather than
|
|
32
|
+
* crashing `--check` itself.
|
|
33
|
+
*/
|
|
34
|
+
/** @internal Exported for direct unit coverage -- reached through `checkEnvArtifacts()`'s `--evidence` pass in production, but the exact "returns text unchanged, not undefined/thrown" catch behavior isn't independently observable through that public path (any malformed `actual` already reads as "stale" against a well-formed `expected`, regardless of the catch's exact return value). */
|
|
35
|
+
export declare function normalizeEvidenceJsonForComparison(text: string): string;
|
|
36
|
+
/**
|
|
37
|
+
* Verifies every requested artifact (`manifest`/`docs`/`envExample`/`usage`)
|
|
38
|
+
* matches what a real {@link generateEnvArtifacts} run would produce, without
|
|
39
|
+
* writing anything.
|
|
40
|
+
*
|
|
41
|
+
* @remarks
|
|
42
|
+
* `--check` reports drift, it doesn't paper over a run that would otherwise fail --
|
|
43
|
+
* see `@throws` below.
|
|
44
|
+
*
|
|
45
|
+
* @throws {EnvProjectGenerationError} On the same blocking findings a real run would throw on.
|
|
46
|
+
*/
|
|
47
|
+
export declare function checkEnvArtifacts(options: GenerateEnvArtifactsOptions): Promise<CheckEnvArtifactsResult>;
|
|
48
|
+
//# sourceMappingURL=check-artifacts.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"check-artifacts.d.ts","sourceRoot":"","sources":["../../../src/build/check-artifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAA;AAU9E;;;;GAIG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,UAAU,CAAA;IAC5E,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wHAAwH;IACxH,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAA;IAC3C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,uBAAuB;IACtC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAA;CACnD;AAOD;;;;;;;;GAQG;AACH,oYAAoY;AACpY,wBAAgB,kCAAkC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvE;AAqBD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAwFlC"}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Re-verifies developer-declared `dynamicAccess` citations every run -- never
|
|
3
|
+
* trusted forever (ADR 0037). Two independent steps, kept as two separate
|
|
4
|
+
* functions rather than one, since they answer two different questions and
|
|
5
|
+
* the second is a pure read over the first's result:
|
|
6
|
+
*
|
|
7
|
+
* - `buildCitationSnapshots` (this run, I/O): for every currently-declared
|
|
8
|
+
* citation, resolves the cited file and computes a whole-file SHA-256, then
|
|
9
|
+
* compares it against the *previous* evidence snapshot's recorded hash to
|
|
10
|
+
* label the citation `"fresh"` / `"stale"` / `"missing"`. Existence is
|
|
11
|
+
* always re-checked live, never trusted from either snapshot. A citation
|
|
12
|
+
* with no previous baseline (the first time it's ever been seen) is
|
|
13
|
+
* `"fresh"` -- there is nothing to contradict it yet. Never throws on a
|
|
14
|
+
* missing file; that citation is simply labeled `"missing"`.
|
|
15
|
+
* - `verifyDynamicAccessCitations` (pure): flattens that result down to just
|
|
16
|
+
* the citations that need a human's attention -- every `"stale"`/`"missing"`
|
|
17
|
+
* assertion, enriched with the owning contract's display name. These are the
|
|
18
|
+
* direct input to `finding-model.ts`'s `STALE_DYNAMIC_ACCESS_CITATION` /
|
|
19
|
+
* `MISSING_DYNAMIC_ACCESS_CITATION` findings.
|
|
20
|
+
*
|
|
21
|
+
* Deliberately separate from `evidence-snapshot.ts`'s own `diffContracts()`,
|
|
22
|
+
* which stays synchronous and pure -- these are the only filesystem-touching,
|
|
23
|
+
* citation-specific part of the evidence-snapshot lifecycle. A citation is
|
|
24
|
+
* always a developer's *re-acknowledgment* that access happens, never a claim
|
|
25
|
+
* env-cap itself observed anything: nothing here ever folds into the
|
|
26
|
+
* AST-derived `VariableAccessStatus`.
|
|
27
|
+
*/
|
|
28
|
+
import type { EvidenceModel } from "./evidence-model.js";
|
|
29
|
+
import type { DiscoveredContract } from "./link.js";
|
|
30
|
+
import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
|
|
31
|
+
/** Stable key {@link buildCitationSnapshots} and `dependency-graph.ts`'s consumer of it agree on -- `file` must be root-relative, POSIX-separated on both sides for a lookup to ever hit. */
|
|
32
|
+
export declare function dynamicAccessVariableIdentity(file: string, exportName: string, key: string): string;
|
|
33
|
+
/**
|
|
34
|
+
* Re-checks every current `dynamicAccess` citation against the previous
|
|
35
|
+
* evidence snapshot's committed `contentHash` baseline. Existence is always
|
|
36
|
+
* re-checked live (never trusted from either snapshot); content drift is
|
|
37
|
+
* only detectable when a previous baseline exists at all -- a citation with
|
|
38
|
+
* no previous baseline (first time it's ever been seen) is reported
|
|
39
|
+
* `"fresh"`, matching the same "nothing to contradict yet" logic. See ADR
|
|
40
|
+
* 0037.
|
|
41
|
+
*/
|
|
42
|
+
export declare function buildCitationSnapshots(activeContracts: readonly DiscoveredContract[], previous: EvidenceModel | undefined, root: string, readFile: (filePath: string) => Promise<string>): Promise<ReadonlyMap<string, readonly DynamicAccessAssertion[]>>;
|
|
43
|
+
/** One `dynamicAccess` citation env-cap can no longer vouch for -- the direct input to `finding-model.ts`'s `"STALE_DYNAMIC_ACCESS_CITATION"`/`"MISSING_DYNAMIC_ACCESS_CITATION"` findings. See ADR 0037. */
|
|
44
|
+
export interface DynamicAccessCitationProblem {
|
|
45
|
+
readonly contractName: string;
|
|
46
|
+
/** Root-relative, POSIX-separated. */
|
|
47
|
+
readonly file: string;
|
|
48
|
+
readonly exportName: string;
|
|
49
|
+
/** The variable whose `dynamicAccess` citation this is. */
|
|
50
|
+
readonly key: string;
|
|
51
|
+
/** Where the citation points -- not the variable's own declaration. */
|
|
52
|
+
readonly position: SourcePosition;
|
|
53
|
+
readonly acknowledgment: "stale" | "missing";
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Flattens {@link buildCitationSnapshots}' result down to just the citations
|
|
57
|
+
* that need attention -- every `"stale"`/`"missing"` assertion, enriched with
|
|
58
|
+
* the owning contract's display name. `"fresh"` assertions are silently
|
|
59
|
+
* omitted -- nothing to report about a citation that's still trustworthy.
|
|
60
|
+
*/
|
|
61
|
+
export declare function verifyDynamicAccessCitations(activeContracts: readonly DiscoveredContract[], root: string, acknowledgments: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): readonly DynamicAccessCitationProblem[];
|
|
62
|
+
//# sourceMappingURL=citation-verification.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"citation-verification.d.ts","sourceRoot":"","sources":["../../../src/build/citation-verification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAOlF,6LAA6L;AAC7L,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GACV,MAAM,CAER;AAyBD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC9C,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,CAAC,CAmCjE;AAED,6MAA6M;AAC7M,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,GACtE,SAAS,4BAA4B,EAAE,CA6BzC"}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import type { DiscoveredContract } from "./link.js";
|
|
2
|
+
/**
|
|
3
|
+
* Every stable `code` a check in this file (or `exclusive-group.ts`) can
|
|
4
|
+
* emit. Documented as an enumerated union so a consumer filtering/linking on
|
|
5
|
+
* `code` has a closed list to switch over, rather than an arbitrary string --
|
|
6
|
+
* see ADR 0024/0026. `exclusive-group.ts`'s check does not (yet) set one; see
|
|
7
|
+
* that file's own comment for why.
|
|
8
|
+
*/
|
|
9
|
+
export type CompatibilityIssueCode = "PROCESSOR_RETURN_TYPE_CONFLICT" | "PROCESSOR_SOURCE_CONFLICT" | "VALIDATOR_SOURCE_CONFLICT" | "DUPLICATE_VARIABLE_DOCUMENTATION" | "DUPLICATE_VARIABLE_SHAPE_ACROSS_CONTRACTS";
|
|
10
|
+
/** One compatibility problem found between two or more declarations of the same variable, or an exclusive-group violation. */
|
|
11
|
+
export interface CompatibilityIssue {
|
|
12
|
+
/** `"error"` blocks generation regardless of `onIncompatibility`; `"warning"` blocks only when `onIncompatibility: "throw"`; `"info"` never blocks, under any flag. */
|
|
13
|
+
readonly severity: "error" | "warning" | "info";
|
|
14
|
+
/** The environment variable name, or `"(contract) <name>"` for a contract-level (e.g. exclusive-group) issue. */
|
|
15
|
+
readonly variable: string;
|
|
16
|
+
/**
|
|
17
|
+
* Every file declaring a conflicting definition. A pairwise comparison
|
|
18
|
+
* (compatibility.ts, exclusive-group.ts) always produces exactly two; a
|
|
19
|
+
* finding escalated from another family (generate-env-artifacts.ts's
|
|
20
|
+
* `escalatedFindings()`, via `findingFiles()`) can produce zero, one, or
|
|
21
|
+
* two, depending on what location information that finding actually
|
|
22
|
+
* carries -- genuinely variable arity, not a tuple.
|
|
23
|
+
*/
|
|
24
|
+
readonly files: readonly string[];
|
|
25
|
+
/** Human-readable explanation of the conflict. */
|
|
26
|
+
readonly reason: string;
|
|
27
|
+
/**
|
|
28
|
+
* Stable, machine-readable identifier for CI filtering / doc-linking /
|
|
29
|
+
* GitHub Action annotations / IDE integration. `undefined` only for checks
|
|
30
|
+
* that don't (yet) set one -- see {@link CompatibilityIssueCode} for the
|
|
31
|
+
* full enumerated list of values a check in this file can produce.
|
|
32
|
+
*/
|
|
33
|
+
readonly code?: CompatibilityIssueCode;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Flags cases where two contracts declare the same variable name but appear to
|
|
37
|
+
* disagree about its shape, so a human can confirm they're still meant to be "the same" var.
|
|
38
|
+
*
|
|
39
|
+
* @remarks
|
|
40
|
+
* Duplicate variable names across contracts are not a merge problem -- each
|
|
41
|
+
* contract independently processes its own copy of the raw value, there is no
|
|
42
|
+
* runtime merge at all. This is purely a build-time lint.
|
|
43
|
+
*
|
|
44
|
+
* Only one thing is treated as *provable* without executing code: two
|
|
45
|
+
* processors with explicit, differing `: T` return type annotations. That is
|
|
46
|
+
* a hard error. Everything else (differing processor/validator source text
|
|
47
|
+
* with no annotation, or none at all) is a warning -- we cannot prove
|
|
48
|
+
* semantic non-equivalence via static analysis alone, and the library never
|
|
49
|
+
* executes schema code to check further (see literal-eval.ts).
|
|
50
|
+
*/
|
|
51
|
+
export declare function detectCompatibilityIssues(contracts: readonly DiscoveredContract[]): CompatibilityIssue[];
|
|
52
|
+
/**
|
|
53
|
+
* Flags *differently-named* variables in different contracts that share an
|
|
54
|
+
* identical type shape -- a soft signal that two features may be
|
|
55
|
+
* independently modelling the same underlying configuration value under two
|
|
56
|
+
* names, worth a human glance before they drift apart.
|
|
57
|
+
*
|
|
58
|
+
* @remarks
|
|
59
|
+
* Always `severity: "info"`, and never escalated to blocking by any flag,
|
|
60
|
+
* including `--strict` -- an identical shape is genuinely common and
|
|
61
|
+
* frequently correct (two unrelated features can both take a `number` timeout
|
|
62
|
+
* with a validator, and that is not a defect). This is an observation offered
|
|
63
|
+
* to a reader, not a rule; making it blockable would make it noise a team has
|
|
64
|
+
* to suppress rather than a signal they can scan.
|
|
65
|
+
*
|
|
66
|
+
* Scope, deliberately narrow on every axis:
|
|
67
|
+
* - **Different keys only.** Same-key collisions across contracts are
|
|
68
|
+
* `detectCompatibilityIssues()`'s own, entirely separate concern above;
|
|
69
|
+
* reporting them here too would double-report one problem under two codes.
|
|
70
|
+
* - **Different contracts only.** Two same-shaped variables inside one
|
|
71
|
+
* contract are that contract's own deliberate design.
|
|
72
|
+
* - **Active contracts only.** An inactive contract is wired into nothing,
|
|
73
|
+
* so an overlap with it is not a live duplication.
|
|
74
|
+
* - **No exclusive-grouped contracts.** Members of an exclusive group are
|
|
75
|
+
* interchangeable alternatives by explicit authorial declaration --
|
|
76
|
+
* matching shapes there are the *point*, not a smell.
|
|
77
|
+
* - **Pairwise, never transitive.** Three mutually-matching variables emit
|
|
78
|
+
* three independent findings (A-B, A-C, B-C), never one merged "cluster":
|
|
79
|
+
* each pair is its own question a reader answers on its own, and a cluster
|
|
80
|
+
* would imply a transitive relationship this check never established.
|
|
81
|
+
*/
|
|
82
|
+
export declare function detectDuplicateVariableShapes(contracts: readonly DiscoveredContract[]): CompatibilityIssue[];
|
|
83
|
+
//# sourceMappingURL=compatibility.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../../../src/build/compatibility.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AAGvE;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAC9B,gCAAgC,GAChC,2BAA2B,GAC3B,2BAA2B,GAC3B,kCAAkC,GAClC,2CAA2C,CAAA;AAE/C,8HAA8H;AAC9H,MAAM,WAAW,kBAAkB;IACjC,uKAAuK;IACvK,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;IAC/C,iHAAiH;IACjH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,sBAAsB,CAAA;CACvC;AAkCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,kBAAkB,EAAE,CAqGtB;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,kBAAkB,EAAE,CAqDtB"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fails with a readable message when the resolved compiler lacks the classic API the scanner needs. The wording
|
|
3
|
+
* lives in `../_ipc/compiler-api.ts`, a managed copy of internal-package-contract's `runtime/compiler-api.ts`;
|
|
4
|
+
* this binds it to env-cap.
|
|
5
|
+
* @param compiler - The resolved compiler module (a parameter so a test can hand in a stand-in).
|
|
6
|
+
* @throws Error naming the installed version and how to restore the bundled compiler.
|
|
7
|
+
*/
|
|
8
|
+
export declare function assertCompilerApi(compiler: {
|
|
9
|
+
readonly createSourceFile?: unknown;
|
|
10
|
+
readonly version?: string;
|
|
11
|
+
}): void;
|
|
12
|
+
//# sourceMappingURL=compiler-api.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"compiler-api.d.ts","sourceRoot":"","sources":["../../../src/build/compiler-api.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE;IAC1C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B,GAAG,IAAI,CAEP"}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import { type EnvGovernanceFields } from "./governance-fields.js";
|
|
2
|
+
import type { DiscoveredContract } from "./link.js";
|
|
3
|
+
import type { DiscoveredVariableEvidence } from "./parse.js";
|
|
4
|
+
import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
|
|
5
|
+
import type { SourcePosition } from "./source-position.js";
|
|
6
|
+
/**
|
|
7
|
+
* The first of env-cap's seven canonical fact models (ADR 0024) -- a
|
|
8
|
+
* versioned, JSON-serializable projection of every declared environment
|
|
9
|
+
* variable's structural and documentation contract. See ADR 0025.
|
|
10
|
+
*
|
|
11
|
+
* @remarks
|
|
12
|
+
* Deliberately broader than the persisted evidence snapshot's
|
|
13
|
+
* (`evidence-snapshot.ts`) `ManifestChangeReport` scope: that diff is scoped
|
|
14
|
+
* to *active* contracts and *only* the `documentEnv()`-sourced fields,
|
|
15
|
+
* matching `renderManifest()`'s own scope (ADR 0021). This model includes
|
|
16
|
+
* every discovered contract regardless of `active`, plus the AST-derived
|
|
17
|
+
* schema facts (`hasDefault`/`hasProcessor`/etc.) the change report
|
|
18
|
+
* deliberately excludes -- both are load-bearing for downstream
|
|
19
|
+
* Finding/Evidence Model work.
|
|
20
|
+
*/
|
|
21
|
+
/** Bump only when a reader could misinterpret the new shape (a field changes
|
|
22
|
+
* type/meaning, or is removed) -- NOT for every additive field. Same
|
|
23
|
+
* discipline `evidence-model.ts`'s `EVIDENCE_MODEL_SCHEMA_VERSION` and
|
|
24
|
+
* `src/cli/json.ts`'s `JSON_SCHEMA_VERSION` already document. */
|
|
25
|
+
export declare const CONTRACT_MODEL_SCHEMA_VERSION = 3;
|
|
26
|
+
/**
|
|
27
|
+
* One variable's full statically-discoverable contract: schema-shaped facts plus linked documentation.
|
|
28
|
+
*
|
|
29
|
+
* @see {@link DependencyModelVariable} -- this same declared variable's access status.
|
|
30
|
+
* @see {@link OwnershipModelVariable} -- this same declared variable's effective owner.
|
|
31
|
+
* @see {@link LifecycleModelVariable} -- this same declared variable's lifecycle data.
|
|
32
|
+
* @see `CatalogVariable` (`docs.ts`) -- this same declared variable, reshaped for the generated
|
|
33
|
+
* docs catalog/JSON. Plain reference, not `{@link}`: `CatalogVariable` is intentionally not part
|
|
34
|
+
* of the public surface (see `typedoc.json`'s `intentionallyNotExported`).
|
|
35
|
+
*/
|
|
36
|
+
export interface ContractModelVariable extends EnvGovernanceFields {
|
|
37
|
+
readonly key: string;
|
|
38
|
+
readonly hasDefault: boolean;
|
|
39
|
+
readonly defaultValue: {
|
|
40
|
+
readonly ok: true;
|
|
41
|
+
readonly value: unknown;
|
|
42
|
+
} | {
|
|
43
|
+
readonly ok: false;
|
|
44
|
+
} | undefined;
|
|
45
|
+
readonly hasProcessor: boolean;
|
|
46
|
+
readonly processorSource: string | undefined;
|
|
47
|
+
readonly processorReturnType: string | undefined;
|
|
48
|
+
readonly hasValidator: boolean;
|
|
49
|
+
readonly validatorSource: string | undefined;
|
|
50
|
+
readonly context: string | undefined;
|
|
51
|
+
readonly description: string | undefined;
|
|
52
|
+
readonly refreshInstructions: string | undefined;
|
|
53
|
+
readonly setupInstructions: string | undefined;
|
|
54
|
+
readonly required: boolean | undefined;
|
|
55
|
+
readonly documented: boolean;
|
|
56
|
+
/** The `evidence` sub-object from this variable's linked documentation -- re-verified every run, unlike every declared-only field above. See {@link runtime.VariableEvidenceDocs} and ADR 0037. */
|
|
57
|
+
readonly evidence: DiscoveredVariableEvidence | undefined;
|
|
58
|
+
/** Where this variable's own schema property is declared. See ADR 0036. */
|
|
59
|
+
readonly declaration: SourcePosition;
|
|
60
|
+
}
|
|
61
|
+
/** One `createEnv()` contract's full statically-discoverable contract, active or not. */
|
|
62
|
+
export interface ContractModelContract extends EnvGovernanceFields {
|
|
63
|
+
/** Root-relative, POSIX-separated -- matches `DiscoveredContractSummary.file`. */
|
|
64
|
+
readonly file: string;
|
|
65
|
+
readonly exportName: string;
|
|
66
|
+
readonly contractName: string;
|
|
67
|
+
readonly active: boolean;
|
|
68
|
+
readonly category: string | undefined;
|
|
69
|
+
readonly exclusiveGroup: string | undefined;
|
|
70
|
+
readonly variables: readonly ContractModelVariable[];
|
|
71
|
+
readonly documented: boolean;
|
|
72
|
+
readonly packageOrigin: PackageOrigin | undefined;
|
|
73
|
+
/** Where this contract's `createEnv(...)` call is declared. Always present. See ADR 0036. */
|
|
74
|
+
readonly declaration: SourcePosition;
|
|
75
|
+
/** Where this contract's `documentEnv(...)` call is declared, if one exists. See ADR 0036. */
|
|
76
|
+
readonly documentation: SourcePosition | undefined;
|
|
77
|
+
}
|
|
78
|
+
/** The versioned, JSON-serializable root of the Contract Model -- every discovered `createEnv()` contract (active or not), each with its own full statically-discoverable shape. See {@link ContractModelContract}. */
|
|
79
|
+
export interface ContractModel {
|
|
80
|
+
readonly schemaVersion: typeof CONTRACT_MODEL_SCHEMA_VERSION;
|
|
81
|
+
readonly contracts: readonly ContractModelContract[];
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Projects every discovered contract (active or not) into the Contract
|
|
85
|
+
* Model's versioned, JSON-serializable shape.
|
|
86
|
+
*
|
|
87
|
+
* @remarks
|
|
88
|
+
* Sorted deterministically (by file, then exportName, then variable key), so
|
|
89
|
+
* `JSON.stringify` output is stable and diffs cleanly wherever this is
|
|
90
|
+
* persisted.
|
|
91
|
+
*/
|
|
92
|
+
export declare function buildContractModel(contracts: readonly DiscoveredContract[], root: string): ContractModel;
|
|
93
|
+
//# sourceMappingURL=contract-model.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"contract-model.d.ts","sourceRoot":"","sources":["../../../src/build/contract-model.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACrF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAmB1D;;;;;;;;;;;;;;GAcG;AAEH;;;kEAGkE;AAClE,eAAO,MAAM,6BAA6B,IAAI,CAAA;AAE9C;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,YAAY,EACnB;QAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;KAAE,GAAG,SAAS,CAAA;IACrF,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9C,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,mMAAmM;IACnM,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,GAAG,SAAS,CAAA;IACzD,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAA;CACrC;AAED,yFAAyF;AACzF,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAA;IACpD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,SAAS,CAAA;IACjD,6FAA6F;IAC7F,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAA;IACpC,8FAA8F;IAC9F,QAAQ,CAAC,aAAa,EAAE,cAAc,GAAG,SAAS,CAAA;CACnD;AAED,uNAAuN;AACvN,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,6BAA6B,CAAA;IAC5D,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAA;CACrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,IAAI,EAAE,MAAM,GACX,aAAa,CAmDf"}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Structural equality for JSON-safe values -- `documentEnv()`'s `metadata` can hold an
|
|
3
|
+
* object/array (ADR 0035), so two independently-declared-but-identical values are never `===`.
|
|
4
|
+
* Values compared here are always JSON-safe (string/number/boolean/null/array/object,
|
|
5
|
+
* recursively -- see `literal-eval.ts`), so this doesn't need to handle cycles, `Date`, `Map`, or
|
|
6
|
+
* anything else `evaluateLiteral()` can never produce.
|
|
7
|
+
*/
|
|
8
|
+
export declare function deepEqual(a: unknown, b: unknown): boolean;
|
|
9
|
+
//# sourceMappingURL=deep-equal.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"deep-equal.d.ts","sourceRoot":"","sources":["../../../src/build/deep-equal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAezD"}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Recursively freezes `value` and everything reachable from it (array
|
|
3
|
+
* elements, plain-object property values), so a mutation anywhere in the
|
|
4
|
+
* structure throws instead of silently succeeding.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Generalized from `live-expirations.ts`'s former `DiscoveredContract[]`-
|
|
8
|
+
* hardcoded `deepFreezeContracts()` (see ADR 0012) into a truly generic
|
|
9
|
+
* utility, so Evidence Model's own immutability guarantee (a later phase)
|
|
10
|
+
* can reuse it instead of duplicating the recursion.
|
|
11
|
+
*
|
|
12
|
+
* Only recurses into arrays and plain objects (`{}` or `Object.create(null)`)
|
|
13
|
+
* -- a `Map`, `Set`, or class instance is frozen at its own top level but not
|
|
14
|
+
* walked further. This codebase's fact models are plain JSON-serializable
|
|
15
|
+
* data, never class instances, so this is deliberately narrow rather than a
|
|
16
|
+
* general-purpose deep-freeze library. A `WeakSet` guards against infinite
|
|
17
|
+
* recursion if a cyclic reference is ever passed in.
|
|
18
|
+
*/
|
|
19
|
+
export declare function deepFreeze<T>(value: T): T;
|
|
20
|
+
//# sourceMappingURL=deep-freeze.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"deep-freeze.d.ts","sourceRoot":"","sources":["../../../src/build/deep-freeze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEzC"}
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
import type { EscapeReason } from "./scan-dependencies.js";
|
|
2
|
+
import type { ImportResolutionContext } from "./resolution/resolve-import.js";
|
|
3
|
+
import type { DiscoveredContract } from "./link.js";
|
|
4
|
+
import type { ParseWarning } from "./parse.js";
|
|
5
|
+
import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
|
|
6
|
+
/**
|
|
7
|
+
* What env-cap's static scan could prove about one variable's consumption:
|
|
8
|
+
* it was member-accessed somewhere (`"used"`), it was never accessed at all
|
|
9
|
+
* within the scanned surfaces (`"unconsumed"`), or a computed (dynamic)
|
|
10
|
+
* property access on the owning contract makes the answer unprovable
|
|
11
|
+
* (`"indeterminate"`).
|
|
12
|
+
*
|
|
13
|
+
* @remarks
|
|
14
|
+
* Deliberately narrower than `data-cap`'s equivalent, which
|
|
15
|
+
* splits the unprovable case further (an unresolved *consumer* vs. an
|
|
16
|
+
* indeterminate *field*). That split exists because a data-cap capability
|
|
17
|
+
* exposes many fields at once, so it has a real "we resolved the consumer,
|
|
18
|
+
* but can't tell which field it touched" state to name. env-cap's
|
|
19
|
+
* consumption model is one value per key: a contract member access either
|
|
20
|
+
* names the key statically (`"used"`) or it doesn't (`"indeterminate"`), and
|
|
21
|
+
* there is no intermediate case where the consumer is known but the thing
|
|
22
|
+
* consumed is ambiguous. Adding a fourth state here would be vocabulary
|
|
23
|
+
* borrowed from a model env-cap doesn't have -- see ADR 0010's
|
|
24
|
+
* "provable, not heuristic" rule. Developer-declared `dynamicAccess`
|
|
25
|
+
* citations stay a wholly separate fact and are never folded into this
|
|
26
|
+
* status (ADR 0037).
|
|
27
|
+
*/
|
|
28
|
+
export type VariableAccessStatus = "used" | "unconsumed" | "indeterminate";
|
|
29
|
+
/**
|
|
30
|
+
* Every reason `deriveOwnershipFindings` can cite for an `indeterminate`
|
|
31
|
+
* variable, cited on the {@link EscapeSite} the scanner actually observed --
|
|
32
|
+
* `EscapeReason` (destructuring/aliasing shapes the scanner declines to
|
|
33
|
+
* follow, see ADR 0039) plus `"reference"` for a tracked import/alias
|
|
34
|
+
* mentioned bare (passed as an argument, spread, assigned elsewhere, ...):
|
|
35
|
+
* a real, provable read of the contract that this single-file walk simply
|
|
36
|
+
* can't attribute to any specific key.
|
|
37
|
+
*/
|
|
38
|
+
type EscapeVia = EscapeReason | "reference";
|
|
39
|
+
/** One position where a tracked contract's value escaped this scanner's local dataflow analysis -- see {@link EscapeVia}. */
|
|
40
|
+
interface EscapeSite extends SourcePosition {
|
|
41
|
+
readonly via: EscapeVia;
|
|
42
|
+
}
|
|
43
|
+
interface VariableAccessInfo {
|
|
44
|
+
readonly status: VariableAccessStatus;
|
|
45
|
+
/** Internal only, never exposed publicly -- which AST evidence produced
|
|
46
|
+
* this status, so a future "why does env-cap think this is
|
|
47
|
+
* unconsumed" bug report is debuggable without re-deriving the AST walk
|
|
48
|
+
* by hand. */
|
|
49
|
+
readonly evidence: "member-access" | "dynamic-access" | "escape" | "no-access";
|
|
50
|
+
/** Every position where a member access was observed for this variable,
|
|
51
|
+
* aggregated across every consuming file -- empty unless
|
|
52
|
+
* `status === "used"`. Previously computed by `scan-dependencies.ts`'s
|
|
53
|
+
* `AccessSite` and discarded before reaching even this internal type;
|
|
54
|
+
* threaded through as of ADR 0027 (line only) and ADR 0036 (full
|
|
55
|
+
* position, one entry per file rather than a flat, file-less list of
|
|
56
|
+
* line numbers) so `dependency-model.ts` can publish it. */
|
|
57
|
+
readonly positions: readonly SourcePosition[];
|
|
58
|
+
/** Every developer-declared `dynamicAccess` citation's current freshness for this variable -- a wholly separate, independent fact from `status`/`evidence` above, never folded into them. Empty unless the linked `documentEnv()` call declared at least one citation for this key. See ADR 0037. */
|
|
59
|
+
readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
|
|
60
|
+
}
|
|
61
|
+
/** One named surface `buildDependencyGraph()`'s scan actually covered -- the
|
|
62
|
+
* application's own root, plus one entry per allow-listed `packages` (ADR
|
|
63
|
+
* 0014) name whose source was also scanned. See ADR 0036: a claim like
|
|
64
|
+
* "no consumer found" is only ever as strong as what was actually
|
|
65
|
+
* searched, and this is what lets a renderer say so explicitly instead of
|
|
66
|
+
* implying an unbounded guarantee it can't back up. */
|
|
67
|
+
export interface ScannedSurface {
|
|
68
|
+
/** `"application"` for the local project root, `"package:<name>"` for an allow-listed package's own source. */
|
|
69
|
+
readonly label: string;
|
|
70
|
+
/** Root-relative, POSIX-separated. */
|
|
71
|
+
readonly root: string;
|
|
72
|
+
}
|
|
73
|
+
interface ContractDependencySummary {
|
|
74
|
+
readonly file: string;
|
|
75
|
+
readonly exportName: string;
|
|
76
|
+
readonly contractName: string;
|
|
77
|
+
readonly imported: boolean;
|
|
78
|
+
readonly hasDynamicAccess: boolean;
|
|
79
|
+
/** Every declared key is always present. */
|
|
80
|
+
readonly variables: ReadonlyMap<string, VariableAccessInfo>;
|
|
81
|
+
/** Every file coupled to this contract -- contract-level "who depends on
|
|
82
|
+
* this," not proof any specific variable was read. See the
|
|
83
|
+
* consumer-vs-variable-access semantics note in `deriveOwnershipFindings`. */
|
|
84
|
+
readonly consumingFiles: readonly string[];
|
|
85
|
+
/** Files whose import of this contract's name couldn't be verified
|
|
86
|
+
* because it resolved through a file containing an unresolved wildcard
|
|
87
|
+
* re-export. */
|
|
88
|
+
readonly ambiguousBarrelFiles: readonly string[];
|
|
89
|
+
/** Every computed (dynamic) property-access site observed anywhere on
|
|
90
|
+
* this contract -- previously collapsed into `hasDynamicAccess` alone
|
|
91
|
+
* and discarded; threaded through as of ADR 0036 so a finding can cite
|
|
92
|
+
* exactly where the uncertainty comes from instead of just asserting it
|
|
93
|
+
* exists. */
|
|
94
|
+
readonly dynamicAccessSites: readonly SourcePosition[];
|
|
95
|
+
/** Every position where the contract's value flowed somewhere this
|
|
96
|
+
* scanner's local dataflow analysis can't follow -- see {@link
|
|
97
|
+
* EscapeVia} and ADR 0039. Like `dynamicAccessSites`, this widens every
|
|
98
|
+
* not-otherwise-accessed variable on the SAME contract to
|
|
99
|
+
* `indeterminate`, never `unconsumed`. */
|
|
100
|
+
readonly escapeSites: readonly EscapeSite[];
|
|
101
|
+
}
|
|
102
|
+
export interface DependencyGraph {
|
|
103
|
+
readonly contracts: readonly ContractDependencySummary[];
|
|
104
|
+
readonly warnings: readonly ParseWarning[];
|
|
105
|
+
/** Every surface actually scanned for usage -- see {@link ScannedSurface}. Always has at least one entry (the application root). */
|
|
106
|
+
readonly scannedSurfaces: readonly ScannedSurface[];
|
|
107
|
+
}
|
|
108
|
+
/** Sorts two positions by file, then line. @internal Exported for direct unit coverage. */
|
|
109
|
+
export declare function byPosition(a: SourcePosition, b: SourcePosition): number;
|
|
110
|
+
export declare function buildDependencyGraph(contracts: readonly DiscoveredContract[], scanFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, scannedSurfaces?: readonly ScannedSurface[], dynamicAccessAcknowledgments?: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): Promise<DependencyGraph>;
|
|
111
|
+
interface AbandonedOwnershipFinding {
|
|
112
|
+
readonly file: string;
|
|
113
|
+
readonly exportName: string;
|
|
114
|
+
readonly contractName: string;
|
|
115
|
+
}
|
|
116
|
+
interface UnresolvedConsumerOwnershipFinding extends AbandonedOwnershipFinding {
|
|
117
|
+
readonly reason: string;
|
|
118
|
+
}
|
|
119
|
+
interface UnconsumedOwnedVariableOwnershipFinding extends AbandonedOwnershipFinding {
|
|
120
|
+
readonly key: string;
|
|
121
|
+
}
|
|
122
|
+
interface IndeterminateAccessOwnershipFinding extends AbandonedOwnershipFinding {
|
|
123
|
+
readonly key: string;
|
|
124
|
+
readonly reason: string;
|
|
125
|
+
/** Every AST-observed dynamic-access site on this contract -- see ADR 0036. */
|
|
126
|
+
readonly dynamicAccessSites: readonly SourcePosition[];
|
|
127
|
+
/** Every AST-observed escape site on this contract -- see {@link EscapeVia} and ADR 0039. */
|
|
128
|
+
readonly escapeSites: readonly EscapeSite[];
|
|
129
|
+
}
|
|
130
|
+
/** A variable that would otherwise be `unconsumedOwned`/`indeterminate`, but has at least one `"fresh"` developer-declared `dynamicAccess` assertion -- the "asserted" category (ADR 0037). Never silently dropped: the raw `wouldBeStatus` is always shown alongside the assertion, per Design 7's "never let a claim overwrite an observation" rule. */
|
|
131
|
+
interface AssertedOwnershipFinding extends AbandonedOwnershipFinding {
|
|
132
|
+
readonly key: string;
|
|
133
|
+
readonly wouldBeStatus: "unconsumed" | "indeterminate";
|
|
134
|
+
readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
|
|
135
|
+
}
|
|
136
|
+
export interface OwnershipFindings {
|
|
137
|
+
readonly abandoned: readonly AbandonedOwnershipFinding[];
|
|
138
|
+
readonly unresolvedConsumers: readonly UnresolvedConsumerOwnershipFinding[];
|
|
139
|
+
readonly unconsumedOwned: readonly UnconsumedOwnedVariableOwnershipFinding[];
|
|
140
|
+
readonly indeterminate: readonly IndeterminateAccessOwnershipFinding[];
|
|
141
|
+
readonly asserted: readonly AssertedOwnershipFinding[];
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* Derives ownership findings from the graph. This is where the epistemic
|
|
145
|
+
* rules that matter most live:
|
|
146
|
+
* - A contract never imported anywhere, with no ambiguous barrel path
|
|
147
|
+
* either, is `abandoned` -- a feature's schema outliving the feature.
|
|
148
|
+
* - A contract never *directly* imported, but reachable only through an
|
|
149
|
+
* unresolved barrel re-export, is `unresolvedConsumers` -- never
|
|
150
|
+
* `abandoned`. Claiming "abandoned" here would be a false positive with
|
|
151
|
+
* real consequences.
|
|
152
|
+
* - A variable with no member access anywhere, on a contract with no
|
|
153
|
+
* dynamic access anywhere, is `unconsumedOwned` -- "no consumer found in
|
|
154
|
+
* this repository," not "provably dead." The scanned surfaces are named
|
|
155
|
+
* explicitly in the reason, per ADR 0036, so the claim is exactly as
|
|
156
|
+
* strong as what was actually searched.
|
|
157
|
+
* - A variable with no member access, but dynamic access observed
|
|
158
|
+
* *somewhere* on that contract, is `indeterminate` -- never
|
|
159
|
+
* `unconsumedOwned`. Uncertainty is never promoted to certainty in either
|
|
160
|
+
* direction. Every candidate dynamic-access site is cited by name.
|
|
161
|
+
* - A variable with at least one `"fresh"` {@link DynamicAccessAssertion}
|
|
162
|
+
* (ADR 0037) gets neither `unconsumedOwned` nor `indeterminate`, regardless
|
|
163
|
+
* of `status` -- a developer has re-acknowledged the access exists. The
|
|
164
|
+
* Dependency Model itself still keeps `status` and the assertion side by
|
|
165
|
+
* side, unedited; only *this* finding-suppression decision reads them
|
|
166
|
+
* together.
|
|
167
|
+
*/
|
|
168
|
+
export declare function deriveOwnershipFindings(graph: DependencyGraph): OwnershipFindings;
|
|
169
|
+
export {};
|
|
170
|
+
//# sourceMappingURL=dependency-graph.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../../../src/build/dependency-graph.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
import type { ContractRef } from "./evidence-reference.js";
|
|
2
|
+
import type { ScannedSurface, VariableAccessStatus } from "./dependency-graph.js";
|
|
3
|
+
import type { DiscoveredContract } from "./link.js";
|
|
4
|
+
import type { ParseWarning } from "./parse.js";
|
|
5
|
+
import type { ImportResolutionContext } from "./resolution/resolve-import.js";
|
|
6
|
+
import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
|
|
7
|
+
/**
|
|
8
|
+
* The second of env-cap's seven canonical fact models (ADR 0024) -- a
|
|
9
|
+
* versioned, JSON-serializable projection of the dependency-ownership
|
|
10
|
+
* engine's graph. See ADR 0027 and ADR 0036.
|
|
11
|
+
*
|
|
12
|
+
* @remarks
|
|
13
|
+
* `dependency-graph.ts`'s scanning/graph-building internals stay Private,
|
|
14
|
+
* unchanged, per ADR 0010 -- this is a fact-shaped *result* built on top of
|
|
15
|
+
* them, not a relaxation of that boundary. Graph-format rendering (DOT,
|
|
16
|
+
* Mermaid, a `{nodes, edges}` JSON export) is deliberately not here --
|
|
17
|
+
* that's presentation over this model's data, not the model itself.
|
|
18
|
+
*/
|
|
19
|
+
/** Bump only when a reader could misinterpret the new shape -- same discipline every other canonical model's `schemaVersion` follows. */
|
|
20
|
+
export declare const DEPENDENCY_MODEL_SCHEMA_VERSION = 2;
|
|
21
|
+
/**
|
|
22
|
+
* One variable's access status within a contract, plus every position it was found
|
|
23
|
+
* member-accessed at, aggregated across every consuming file.
|
|
24
|
+
*
|
|
25
|
+
* @see {@link ContractModelVariable} -- this same declared variable's canonical starting point.
|
|
26
|
+
*/
|
|
27
|
+
export interface DependencyModelVariable {
|
|
28
|
+
readonly key: string;
|
|
29
|
+
readonly status: VariableAccessStatus;
|
|
30
|
+
/** Empty unless `status === "used"`. Previously discarded before reaching any public type -- see ADR 0027 (line only) and ADR 0036 (full position, file included per entry). */
|
|
31
|
+
readonly positions: readonly SourcePosition[];
|
|
32
|
+
/** Every developer-declared `dynamicAccess` citation's current freshness for this variable -- a wholly separate, independent fact from `status` above, never folded into it. Empty when no citation was declared, or when no manifest snapshot baseline was available to check against (the manifest pass wasn't also requested). See ADR 0037. */
|
|
33
|
+
readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
|
|
34
|
+
}
|
|
35
|
+
/** One contract's dependency-ownership facts: which variables were accessed, which files consume it, and every dynamic/ambiguous access site found. See {@link DependencyModelVariable} for the per-variable breakdown. */
|
|
36
|
+
export interface DependencyModelContract {
|
|
37
|
+
/** Root-relative, POSIX-separated -- matches `ContractModelContract.file`. */
|
|
38
|
+
readonly file: string;
|
|
39
|
+
readonly exportName: string;
|
|
40
|
+
readonly contractName: string;
|
|
41
|
+
readonly imported: boolean;
|
|
42
|
+
readonly hasDynamicAccess: boolean;
|
|
43
|
+
readonly variables: readonly DependencyModelVariable[];
|
|
44
|
+
/** Every file coupled to this contract -- contract-level "who depends on this," not proof any specific variable was read. */
|
|
45
|
+
readonly consumingFiles: readonly string[];
|
|
46
|
+
/** Files whose import of this contract's name couldn't be verified because it resolved through a file containing an unresolved wildcard re-export. */
|
|
47
|
+
readonly ambiguousBarrelFiles: readonly string[];
|
|
48
|
+
/** Every computed (dynamic) property-access site observed anywhere on this contract -- see ADR 0036. */
|
|
49
|
+
readonly dynamicAccessSites: readonly SourcePosition[];
|
|
50
|
+
}
|
|
51
|
+
/** One contract, as referenced from the inverse (`consumers`) index -- see {@link ContractRef} for why no `contractName` is carried here. */
|
|
52
|
+
export type DependencyModelContractRef = ContractRef;
|
|
53
|
+
/** One consuming file, and every contract it depends on -- the inverse of `DependencyModelContract.consumingFiles`. */
|
|
54
|
+
export interface DependencyModelConsumer {
|
|
55
|
+
/** Root-relative, POSIX-separated. */
|
|
56
|
+
readonly file: string;
|
|
57
|
+
readonly contracts: readonly DependencyModelContractRef[];
|
|
58
|
+
}
|
|
59
|
+
/** The versioned, JSON-serializable root of the Dependency Model -- see this module's own doc comment for the full picture. */
|
|
60
|
+
export interface DependencyModel {
|
|
61
|
+
readonly schemaVersion: typeof DEPENDENCY_MODEL_SCHEMA_VERSION;
|
|
62
|
+
readonly contracts: readonly DependencyModelContract[];
|
|
63
|
+
/** Inverse of `contracts[].consumingFiles` -- one entry per file that consumes at least one contract, listing which contracts it reads. */
|
|
64
|
+
readonly consumers: readonly DependencyModelConsumer[];
|
|
65
|
+
readonly warnings: readonly ParseWarning[];
|
|
66
|
+
/** Every surface actually scanned for usage -- see ADR 0036. Always has at least one entry (the application root). */
|
|
67
|
+
readonly scannedSurfaces: readonly ScannedSurface[];
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Runs the dependency-ownership engine (`buildDependencyGraph()`, Private)
|
|
71
|
+
* and projects its result into the Dependency Model's versioned,
|
|
72
|
+
* JSON-serializable shape -- including the inverse file-\>contracts index
|
|
73
|
+
* neither `dependency-graph.ts` nor `usage-report.ts` exposes today.
|
|
74
|
+
*
|
|
75
|
+
* @param scannedSurfaces - See `buildDependencyGraph()`'s own parameter of
|
|
76
|
+
* the same name -- passed straight through to the published model.
|
|
77
|
+
* @param dynamicAccessAcknowledgments - See `buildDependencyGraph()`'s own
|
|
78
|
+
* parameter of the same name (ADR 0037) -- passed straight through.
|
|
79
|
+
*/
|
|
80
|
+
export declare function buildDependencyModel(contracts: readonly DiscoveredContract[], scanFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, root: string, scannedSurfaces?: readonly ScannedSurface[], dynamicAccessAcknowledgments?: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): Promise<DependencyModel>;
|
|
81
|
+
//# sourceMappingURL=dependency-model.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"dependency-model.d.ts","sourceRoot":"","sources":["../../../src/build/dependency-model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAElF;;;;;;;;;;;GAWG;AAEH,yIAAyI;AACzI,eAAO,MAAM,+BAA+B,IAAI,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;IACrC,gLAAgL;IAChL,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAA;IAC7C,mVAAmV;IACnV,QAAQ,CAAC,uBAAuB,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACpE;AAED,2NAA2N;AAC3N,MAAM,WAAW,uBAAuB;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD,6HAA6H;IAC7H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,sJAAsJ;IACtJ,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAA;IAChD,wGAAwG;IACxG,QAAQ,CAAC,kBAAkB,EAAE,SAAS,cAAc,EAAE,CAAA;CACvD;AAED,6IAA6I;AAC7I,MAAM,MAAM,0BAA0B,GAAG,WAAW,CAAA;AAEpD,uHAAuH;AACvH,MAAM,WAAW,uBAAuB;IACtC,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,SAAS,0BAA0B,EAAE,CAAA;CAC1D;AAED,+HAA+H;AAC/H,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,+BAA+B,CAAA;IAC9D,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD,2IAA2I;IAC3I,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;IAC1C,sHAAsH;IACtH,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAA;CACpD;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC/C,OAAO,EAAE,uBAAuB,EAChC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,EAC3C,4BAA4B,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,GACpF,OAAO,CAAC,eAAe,CAAC,CAmE1B"}
|