@maverickcer/env-cap 0.7.5 → 0.7.6
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 +12 -12
- package/AGENTS.md +85 -120
- package/CHANGELOG.md +27 -0
- package/CODE_REVIEW.md +5 -5
- package/CONTRIBUTING.md +5 -5
- package/GUIDE.md +42 -24
- package/README.md +52 -34
- package/RELEASING.md +78 -64
- package/SECURITY.md +15 -15
- package/VERSIONING.md +16 -15
- package/benchmarks/READING-BENCHMARKS.md +101 -85
- package/benchmarks/README.md +12 -9
- package/benchmarks/WRITING-BENCHMARKS.md +89 -79
- package/benchmarks/performance-buildtime/BENCHMARKS.md +20 -20
- package/benchmarks/performance-runtime/BENCHMARKS.md +107 -107
- package/dist/.dts/_ipc/build-fs.d.ts +3 -3
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
- package/dist/.dts/_ipc/display-path.d.ts +1 -1
- package/dist/.dts/_ipc/glob.d.ts +3 -2
- package/dist/.dts/_ipc/glob.d.ts.map +1 -1
- package/dist/.dts/_ipc/no-node-fs.d.ts +2 -2
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +16 -16
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/_ipc/typescript.d.ts +4 -4
- package/dist/.dts/build/assemble-project.d.ts +14 -15
- package/dist/.dts/build/assemble-project.d.ts.map +1 -1
- package/dist/.dts/build/change-model.d.ts +14 -14
- package/dist/.dts/build/change-model.d.ts.map +1 -1
- package/dist/.dts/build/check-artifacts.d.ts +4 -4
- package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
- package/dist/.dts/build/citation-verification.d.ts +13 -14
- package/dist/.dts/build/citation-verification.d.ts.map +1 -1
- package/dist/.dts/build/compatibility.d.ts +24 -24
- package/dist/.dts/build/compatibility.d.ts.map +1 -1
- package/dist/.dts/build/contract-model.d.ts +10 -10
- package/dist/.dts/build/contract-model.d.ts.map +1 -1
- package/dist/.dts/build/deep-equal.d.ts +2 -2
- package/dist/.dts/build/deep-freeze.d.ts +2 -2
- package/dist/.dts/build/dependency-graph.d.ts +48 -55
- package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
- package/dist/.dts/build/dependency-model.d.ts +18 -18
- package/dist/.dts/build/dependency-model.d.ts.map +1 -1
- package/dist/.dts/build/discover.d.ts +11 -11
- package/dist/.dts/build/discover.d.ts.map +1 -1
- package/dist/.dts/build/docs.d.ts +34 -38
- package/dist/.dts/build/docs.d.ts.map +1 -1
- package/dist/.dts/build/env-example.d.ts +13 -13
- package/dist/.dts/build/env-example.d.ts.map +1 -1
- package/dist/.dts/build/errors.d.ts +8 -8
- package/dist/.dts/build/evidence-cache.d.ts +23 -23
- package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
- package/dist/.dts/build/evidence-model.d.ts +3 -3
- package/dist/.dts/build/evidence-reference.d.ts +15 -15
- package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
- package/dist/.dts/build/evidence-snapshot.d.ts +47 -53
- package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
- package/dist/.dts/build/exclusive-group.d.ts +4 -4
- package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
- package/dist/.dts/build/finding-model.d.ts +12 -12
- package/dist/.dts/build/finding-model.d.ts.map +1 -1
- package/dist/.dts/build/generate-documentation.d.ts +19 -19
- package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
- package/dist/.dts/build/generate-env-artifacts.d.ts +43 -43
- package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
- package/dist/.dts/build/generate-evidence.d.ts +19 -19
- package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
- package/dist/.dts/build/generate-manifest.d.ts +11 -12
- package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
- package/dist/.dts/build/generate-usage.d.ts +23 -24
- package/dist/.dts/build/generate-usage.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +5 -5
- package/dist/.dts/build/governance-fields.d.ts +7 -7
- package/dist/.dts/build/humanize-key.d.ts +1 -1
- package/dist/.dts/build/humanize-key.d.ts.map +1 -1
- package/dist/.dts/build/index.d.ts +20 -36
- package/dist/.dts/build/index.d.ts.map +1 -1
- package/dist/.dts/build/lifecycle-model.d.ts +87 -85
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts/build/link.d.ts +38 -39
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/literal-eval.d.ts +2 -2
- package/dist/.dts/build/literal-eval.d.ts.map +1 -1
- package/dist/.dts/build/live-expirations.d.ts +14 -13
- package/dist/.dts/build/live-expirations.d.ts.map +1 -1
- package/dist/.dts/build/manifest.d.ts +6 -6
- package/dist/.dts/build/map-utils.d.ts +4 -4
- package/dist/.dts/build/merge-documentation.d.ts +9 -8
- package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
- package/dist/.dts/build/ownership-model.d.ts +14 -15
- package/dist/.dts/build/ownership-model.d.ts.map +1 -1
- package/dist/.dts/build/parse.d.ts +20 -21
- package/dist/.dts/build/parse.d.ts.map +1 -1
- package/dist/.dts/build/reference-projections.d.ts +36 -38
- package/dist/.dts/build/reference-projections.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-import.d.ts +18 -14
- package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-package-schema.d.ts +26 -26
- package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-within-root.d.ts +9 -9
- package/dist/.dts/build/sarif.d.ts +5 -5
- package/dist/.dts/build/sarif.d.ts.map +1 -1
- package/dist/.dts/build/scan-dependencies.d.ts +17 -16
- package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
- package/dist/.dts/build/sort-by-identity.d.ts +1 -1
- package/dist/.dts/build/source-position.d.ts +13 -13
- package/dist/.dts/build/tool-version.d.ts +1 -1
- package/dist/.dts/build/usage-report.d.ts +19 -19
- package/dist/.dts/build/usage-report.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/index.d.ts +16 -5
- package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
- package/dist/.dts/evidence/define-projection.d.ts +15 -16
- package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
- package/dist/.dts/evidence/index.d.ts +11 -15
- package/dist/.dts/evidence/index.d.ts.map +1 -1
- package/dist/.dts/helpers/index.d.ts +15 -18
- package/dist/.dts/helpers/index.d.ts.map +1 -1
- package/dist/.dts/helpers/validators.d.ts +2 -2
- package/dist/.dts/helpers/validators.d.ts.map +1 -1
- package/dist/.dts/node/index.d.ts +19 -0
- package/dist/.dts/node/index.d.ts.map +1 -1
- package/dist/.dts/runtime/create.d.ts +3 -3
- package/dist/.dts/runtime/document.d.ts +90 -99
- package/dist/.dts/runtime/document.d.ts.map +1 -1
- package/dist/.dts/runtime/errors.d.ts +5 -5
- package/dist/.dts/runtime/reset.d.ts +1 -1
- package/dist/.dts/runtime/types.d.ts +23 -24
- package/dist/.dts/runtime/types.d.ts.map +1 -1
- package/dist/.dts/runtime/validate.d.ts +1 -1
- package/dist/.dts7/_ipc/build-fs.d.ts +3 -3
- package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -1
- package/dist/.dts7/_ipc/display-path.d.ts +1 -1
- package/dist/.dts7/_ipc/glob.d.ts +3 -2
- package/dist/.dts7/_ipc/glob.d.ts.map +1 -1
- package/dist/.dts7/_ipc/no-node-fs.d.ts +2 -2
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +16 -16
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts7/_ipc/typescript.d.ts +4 -4
- package/dist/.dts7/build/assemble-project.d.ts +14 -15
- package/dist/.dts7/build/assemble-project.d.ts.map +1 -1
- package/dist/.dts7/build/change-model.d.ts +14 -14
- package/dist/.dts7/build/change-model.d.ts.map +1 -1
- package/dist/.dts7/build/check-artifacts.d.ts +4 -4
- package/dist/.dts7/build/check-artifacts.d.ts.map +1 -1
- package/dist/.dts7/build/citation-verification.d.ts +13 -14
- package/dist/.dts7/build/citation-verification.d.ts.map +1 -1
- package/dist/.dts7/build/compatibility.d.ts +24 -24
- package/dist/.dts7/build/compatibility.d.ts.map +1 -1
- package/dist/.dts7/build/contract-model.d.ts +10 -10
- package/dist/.dts7/build/contract-model.d.ts.map +1 -1
- package/dist/.dts7/build/deep-equal.d.ts +2 -2
- package/dist/.dts7/build/deep-freeze.d.ts +2 -2
- package/dist/.dts7/build/dependency-graph.d.ts +48 -55
- package/dist/.dts7/build/dependency-graph.d.ts.map +1 -1
- package/dist/.dts7/build/dependency-model.d.ts +18 -18
- package/dist/.dts7/build/dependency-model.d.ts.map +1 -1
- package/dist/.dts7/build/discover.d.ts +11 -11
- package/dist/.dts7/build/discover.d.ts.map +1 -1
- package/dist/.dts7/build/docs.d.ts +34 -38
- package/dist/.dts7/build/docs.d.ts.map +1 -1
- package/dist/.dts7/build/env-example.d.ts +13 -13
- package/dist/.dts7/build/env-example.d.ts.map +1 -1
- package/dist/.dts7/build/errors.d.ts +8 -8
- package/dist/.dts7/build/evidence-cache.d.ts +23 -23
- package/dist/.dts7/build/evidence-cache.d.ts.map +1 -1
- package/dist/.dts7/build/evidence-model.d.ts +3 -3
- package/dist/.dts7/build/evidence-reference.d.ts +15 -15
- package/dist/.dts7/build/evidence-reference.d.ts.map +1 -1
- package/dist/.dts7/build/evidence-snapshot.d.ts +47 -53
- package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -1
- package/dist/.dts7/build/exclusive-group.d.ts +4 -4
- package/dist/.dts7/build/exclusive-group.d.ts.map +1 -1
- package/dist/.dts7/build/finding-model.d.ts +12 -12
- package/dist/.dts7/build/finding-model.d.ts.map +1 -1
- package/dist/.dts7/build/generate-documentation.d.ts +19 -19
- package/dist/.dts7/build/generate-documentation.d.ts.map +1 -1
- package/dist/.dts7/build/generate-env-artifacts.d.ts +43 -43
- package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -1
- package/dist/.dts7/build/generate-evidence.d.ts +19 -19
- package/dist/.dts7/build/generate-evidence.d.ts.map +1 -1
- package/dist/.dts7/build/generate-manifest.d.ts +11 -12
- package/dist/.dts7/build/generate-manifest.d.ts.map +1 -1
- package/dist/.dts7/build/generate-usage.d.ts +23 -24
- package/dist/.dts7/build/generate-usage.d.ts.map +1 -1
- package/dist/.dts7/build/generated-banner.d.ts +5 -5
- package/dist/.dts7/build/governance-fields.d.ts +7 -7
- package/dist/.dts7/build/humanize-key.d.ts +1 -1
- package/dist/.dts7/build/humanize-key.d.ts.map +1 -1
- package/dist/.dts7/build/index.d.ts +20 -36
- package/dist/.dts7/build/index.d.ts.map +1 -1
- package/dist/.dts7/build/lifecycle-model.d.ts +87 -85
- package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts7/build/link.d.ts +38 -39
- package/dist/.dts7/build/link.d.ts.map +1 -1
- package/dist/.dts7/build/literal-eval.d.ts +2 -2
- package/dist/.dts7/build/literal-eval.d.ts.map +1 -1
- package/dist/.dts7/build/live-expirations.d.ts +14 -13
- package/dist/.dts7/build/live-expirations.d.ts.map +1 -1
- package/dist/.dts7/build/manifest.d.ts +6 -6
- package/dist/.dts7/build/map-utils.d.ts +4 -4
- package/dist/.dts7/build/merge-documentation.d.ts +9 -8
- package/dist/.dts7/build/merge-documentation.d.ts.map +1 -1
- package/dist/.dts7/build/ownership-model.d.ts +14 -15
- package/dist/.dts7/build/ownership-model.d.ts.map +1 -1
- package/dist/.dts7/build/parse.d.ts +20 -21
- package/dist/.dts7/build/parse.d.ts.map +1 -1
- package/dist/.dts7/build/reference-projections.d.ts +36 -38
- package/dist/.dts7/build/reference-projections.d.ts.map +1 -1
- package/dist/.dts7/build/resolution/resolve-import.d.ts +18 -14
- package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -1
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +26 -26
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -1
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts +9 -9
- package/dist/.dts7/build/sarif.d.ts +5 -5
- package/dist/.dts7/build/sarif.d.ts.map +1 -1
- package/dist/.dts7/build/scan-dependencies.d.ts +17 -16
- package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -1
- package/dist/.dts7/build/sort-by-identity.d.ts +1 -1
- package/dist/.dts7/build/source-position.d.ts +13 -13
- package/dist/.dts7/build/tool-version.d.ts +1 -1
- package/dist/.dts7/build/usage-report.d.ts +19 -19
- package/dist/.dts7/build/usage-report.d.ts.map +1 -1
- package/dist/.dts7/eslint-plugin/index.d.ts +16 -5
- package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -1
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +4 -4
- package/dist/.dts7/evidence/define-projection.d.ts +15 -16
- package/dist/.dts7/evidence/define-projection.d.ts.map +1 -1
- package/dist/.dts7/evidence/index.d.ts +11 -15
- package/dist/.dts7/evidence/index.d.ts.map +1 -1
- package/dist/.dts7/helpers/index.d.ts +15 -18
- package/dist/.dts7/helpers/index.d.ts.map +1 -1
- package/dist/.dts7/helpers/validators.d.ts +2 -2
- package/dist/.dts7/helpers/validators.d.ts.map +1 -1
- package/dist/.dts7/node/index.d.ts +19 -0
- package/dist/.dts7/node/index.d.ts.map +1 -1
- package/dist/.dts7/runtime/create.d.ts +3 -3
- package/dist/.dts7/runtime/document.d.ts +90 -99
- package/dist/.dts7/runtime/document.d.ts.map +1 -1
- package/dist/.dts7/runtime/errors.d.ts +5 -5
- package/dist/.dts7/runtime/reset.d.ts +1 -1
- package/dist/.dts7/runtime/types.d.ts +23 -24
- package/dist/.dts7/runtime/types.d.ts.map +1 -1
- package/dist/.dts7/runtime/validate.d.ts +1 -1
- package/dist/{build-DNAYWD2B.js → build-UEENZEUX.js} +37 -39
- package/dist/build-UEENZEUX.js.map +1 -0
- package/dist/build.cjs +36 -38
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +36 -38
- package/dist/build.js.map +1 -1
- package/dist/{chunk-HAGMVMN5.js → chunk-TBL3O7IG.js} +2 -2
- package/dist/cli/index.js +29 -28
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js.map +1 -1
- package/dist/evidence.cjs +1 -1
- package/dist/evidence.cjs.map +1 -1
- package/dist/evidence.js +1 -1
- package/dist/evidence.js.map +1 -1
- package/dist/helpers.cjs +4 -4
- package/dist/helpers.cjs.map +1 -1
- package/dist/helpers.js +4 -4
- package/dist/helpers.js.map +1 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.js.map +1 -1
- package/examples/README.md +1 -1
- package/package.json +18 -10
- package/schemas/contract-model.schema.json +7 -7
- package/schemas/env-cap-report.schema.json +88 -88
- package/skills/env-cap/SKILL.md +12 -13
- package/skills/env-cap/references/api.md +1 -1
- package/specs/architecture.md +145 -120
- package/specs/generated-artifacts.md +78 -70
- package/specs/migrations/README.md +6 -6
- package/specs/migrations/from-centralized-schema.md +1 -1
- package/specs/migrations/from-t3-env.md +9 -9
- package/PROMPT.md +0 -89
- package/dist/build-DNAYWD2B.js.map +0 -1
- /package/dist/{chunk-HAGMVMN5.js.map → chunk-TBL3O7IG.js.map} +0 -0
|
@@ -10,7 +10,7 @@ import type { ParseWarning } from "./parse.js";
|
|
|
10
10
|
import type { BuildFileSystem } from "./types.js";
|
|
11
11
|
/** Options for {@link generateEnvArtifacts}. */
|
|
12
12
|
export interface GenerateEnvArtifactsOptions {
|
|
13
|
-
/** The filesystem capability, shared across every requested pass
|
|
13
|
+
/** The filesystem capability, shared across every requested pass: `./build` never imports `node:fs` (ADR 0040). */
|
|
14
14
|
fs: BuildFileSystem;
|
|
15
15
|
/** Directory glob patterns are resolved against, shared across every requested pass. Defaults to `process.cwd()`. */
|
|
16
16
|
root?: string | undefined;
|
|
@@ -30,14 +30,14 @@ export interface GenerateEnvArtifactsOptions {
|
|
|
30
30
|
usage?: Omit<GenerateUsageReportOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig"> | false | undefined;
|
|
31
31
|
/**
|
|
32
32
|
* Where to write the persisted evidence artifact (the full, literal
|
|
33
|
-
* `EvidenceModel`, plus a paired `.fingerprint` sidecar
|
|
33
|
+
* `EvidenceModel`, plus a paired `.fingerprint` sidecar: see
|
|
34
34
|
* `evidence-cache.ts`), e.g. `docs/env.evidence.json`, relative to `root`.
|
|
35
|
-
* Independent of `manifest.location
|
|
35
|
+
* Independent of `manifest.location`: requesting this needs no other
|
|
36
36
|
* pass, and generating a manifest never requires it. `EvidenceModel`
|
|
37
|
-
* itself is always computed
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
37
|
+
* itself is always computed (ADR 0038, "free to compute, always real") and
|
|
38
|
+
* always returned as `result.evidence`. This option controls only whether
|
|
39
|
+
* it's also written to disk. Omitted: nothing is written, and
|
|
40
|
+
* `result.evidence` is still populated.
|
|
41
41
|
*/
|
|
42
42
|
evidence?: {
|
|
43
43
|
location: string;
|
|
@@ -45,21 +45,21 @@ export interface GenerateEnvArtifactsOptions {
|
|
|
45
45
|
/**
|
|
46
46
|
* Escalates every warning-severity `"documentation"`-family finding
|
|
47
47
|
* (undocumented contracts/variables, stale doc entries, expiring/expired
|
|
48
|
-
* entries, unresolvable `documentEnv()` links) into a blocking error
|
|
49
|
-
* run with any of them writes nothing and throws. Defaults to
|
|
50
|
-
* ADR 0038
|
|
48
|
+
* entries, unresolvable `documentEnv()` links) into a blocking error. A
|
|
49
|
+
* run with any of them then writes nothing and throws. Defaults to
|
|
50
|
+
* `"warn"`: per ADR 0038, documentation gaps never block by default.
|
|
51
51
|
*
|
|
52
52
|
* @remarks
|
|
53
53
|
* Scoped deliberately narrowly, unlike `manifest.onIncompatibility`, which
|
|
54
54
|
* gates only the compatibility family. `"info"`-severity findings are never
|
|
55
|
-
* escalated by either
|
|
55
|
+
* escalated by either: see `Finding.severity`.
|
|
56
56
|
*/
|
|
57
57
|
onUndocumented?: "warn" | "throw" | undefined;
|
|
58
58
|
/**
|
|
59
59
|
* Escalates every warning-severity `"ownership"`-family finding (abandoned
|
|
60
60
|
* contracts, unresolved consumers, unconsumed owned variables,
|
|
61
61
|
* indeterminate ownership, stale/missing `dynamicAccess` citations) into a
|
|
62
|
-
* blocking error. Defaults to `"warn"
|
|
62
|
+
* blocking error. Defaults to `"warn"`: see {@link onUndocumented}.
|
|
63
63
|
*/
|
|
64
64
|
onOwnershipIssue?: "warn" | "throw" | undefined;
|
|
65
65
|
/**
|
|
@@ -80,14 +80,14 @@ export interface GenerateEnvArtifactsResult {
|
|
|
80
80
|
readonly docs: GenerateDocumentationResult | undefined;
|
|
81
81
|
/** Set only when `options.usage` wasn't `false`. */
|
|
82
82
|
readonly usage: GenerateUsageReportResult | undefined;
|
|
83
|
-
/** Always populated, regardless of `options.evidence
|
|
83
|
+
/** Always populated, regardless of `options.evidence`: see that option's own doc comment. */
|
|
84
84
|
readonly evidence: EvidenceModel;
|
|
85
85
|
}
|
|
86
86
|
/**
|
|
87
87
|
* Every intermediate value both the write path (`generateEnvArtifacts()`
|
|
88
88
|
* below) and the drift-check path (`checkEnvArtifacts()` in
|
|
89
89
|
* `check-artifacts.ts`) need, computed exactly once. Internal/Private tier
|
|
90
|
-
* per `VERSIONING.md
|
|
90
|
+
* per `VERSIONING.md`: not re-exported from `./index.ts`.
|
|
91
91
|
*/
|
|
92
92
|
export interface ComputeArtifactsResult {
|
|
93
93
|
readonly root: string;
|
|
@@ -103,7 +103,7 @@ export interface ComputeArtifactsResult {
|
|
|
103
103
|
readonly path: string;
|
|
104
104
|
readonly envExamplePath: string | undefined;
|
|
105
105
|
} | undefined;
|
|
106
|
-
/** Always computed
|
|
106
|
+
/** Always computed: Finding Model needs it regardless of whether a `docs` pass was itself requested. See ADR 0038. */
|
|
107
107
|
readonly docsComputed: DocumentationComputation;
|
|
108
108
|
readonly docsContracts: readonly DiscoveredContract[];
|
|
109
109
|
/** Set only when a usage pass was requested; `reportPath` only when it also asked for a report file. */
|
|
@@ -111,7 +111,7 @@ export interface ComputeArtifactsResult {
|
|
|
111
111
|
readonly options: Omit<GenerateUsageReportOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig">;
|
|
112
112
|
readonly reportPath: string | undefined;
|
|
113
113
|
} | undefined;
|
|
114
|
-
/** Always computed
|
|
114
|
+
/** Always computed: Finding Model needs it regardless of whether a `usage` pass was itself requested. See ADR 0038. */
|
|
115
115
|
readonly usageComputed: UsageComputation;
|
|
116
116
|
readonly evidencePath: string | undefined;
|
|
117
117
|
readonly evidence: EvidenceModel;
|
|
@@ -123,26 +123,26 @@ export interface ComputeArtifactsResult {
|
|
|
123
123
|
}
|
|
124
124
|
/**
|
|
125
125
|
* Adapts every warning-severity finding of one family into the
|
|
126
|
-
* `CompatibilityIssue` shape `blocking`/`EnvProjectGenerationError` speak
|
|
127
|
-
* `--strict-docs`/`--strict-ownership` fail through
|
|
128
|
-
* `--strict
|
|
126
|
+
* `CompatibilityIssue` shape `blocking`/`EnvProjectGenerationError` speak.
|
|
127
|
+
* So `--strict-docs`/`--strict-ownership` fail through the same path as
|
|
128
|
+
* `--strict`, with no second failure mode.
|
|
129
129
|
*
|
|
130
130
|
* @remarks
|
|
131
131
|
* `"info"` findings are filtered out unconditionally and can never be
|
|
132
|
-
* escalated by any flag
|
|
133
|
-
* `Finding.severity`). `"error"` findings are excluded too
|
|
134
|
-
* block on their own, via the manifest pass
|
|
135
|
-
* report the same violation twice in one error message. `code` is left unset
|
|
136
|
-
*
|
|
132
|
+
* escalated by any flag: they're observations, not gaps (see
|
|
133
|
+
* `Finding.severity`). `"error"` findings are excluded too. They already
|
|
134
|
+
* block on their own, via the manifest pass. Re-adding them here would
|
|
135
|
+
* report the same violation twice in one error message. `code` is left unset:
|
|
136
|
+
* `CompatibilityIssueCode` is that check family's own closed vocabulary,
|
|
137
137
|
* and a `FindingCode` from another family is not a member of it.
|
|
138
138
|
*/
|
|
139
|
-
/** @internal Exported for direct unit coverage
|
|
139
|
+
/** @internal Exported for direct unit coverage: reached through `generateEnvArtifacts()`'s `--strict-docs`/`--strict-ownership` flags in production, but its filter/mapping logic isn't independently observable through that path alone (every mutant on it still needs a real `computeArtifacts()` call, discovery included, to reach it). */
|
|
140
140
|
export declare function escalatedFindings(findings: readonly Finding[], family: FindingFamily): CompatibilityIssue[];
|
|
141
|
-
/** The variable a finding is about, or a `"(contract) <name>"` label when it's contract-level
|
|
142
|
-
* @internal Exported for direct unit coverage
|
|
141
|
+
/** The variable a finding is about, or a `"(contract) <name>"` label when it's contract-level: matching `CompatibilityIssue.variable`'s own documented convention.
|
|
142
|
+
* @internal Exported for direct unit coverage: see {@link escalatedFindings}'s own doc comment for why. */
|
|
143
143
|
export declare function findingSubject(finding: Finding): string;
|
|
144
|
-
/** Every file a finding names, as `CompatibilityIssue.files
|
|
145
|
-
* @internal Exported for direct unit coverage
|
|
144
|
+
/** Every file a finding names, as `CompatibilityIssue.files`: empty when its location carries none (an ownership finding about a variable, which names no single file).
|
|
145
|
+
* @internal Exported for direct unit coverage: see {@link escalatedFindings}'s own doc comment for why. */
|
|
146
146
|
export declare function findingFiles(finding: Finding): string[];
|
|
147
147
|
/**
|
|
148
148
|
* A pass's options, or `undefined` when the pass is not requested: `false` skips a pass entirely,
|
|
@@ -152,26 +152,26 @@ export declare function findingFiles(finding: Finding): string[];
|
|
|
152
152
|
export declare function requestedPass<T extends object>(option: T | false | undefined): T | undefined;
|
|
153
153
|
/**
|
|
154
154
|
* Runs schema discovery, linking, and every requested pass's pure `compute*()`
|
|
155
|
-
* step
|
|
156
|
-
* immediately if any requested output location escapes `root
|
|
157
|
-
* fail-fast-before-any-work guarantee `generateEnvArtifacts()`
|
|
158
|
-
*
|
|
159
|
-
*
|
|
160
|
-
* `checkEnvArtifacts()`)
|
|
155
|
+
* step: but never writes anything to disk. Throws `EnvProjectGenerationError`
|
|
156
|
+
* immediately if any requested output location escapes `root`, the same
|
|
157
|
+
* fail-fast-before-any-work guarantee `generateEnvArtifacts()` gives.
|
|
158
|
+
* Otherwise returns every intermediate value without checking `blocking`
|
|
159
|
+
* findings. Each caller (the write path below, and `--check`'s
|
|
160
|
+
* `checkEnvArtifacts()`) decides when to throw on those.
|
|
161
161
|
*
|
|
162
162
|
* @remarks
|
|
163
163
|
* The six canonical fact models (Contract/Dependency/Ownership/Lifecycle/
|
|
164
164
|
* Finding/Change -> `EvidenceModel`) are composed on every call,
|
|
165
|
-
* unconditionally
|
|
166
|
-
*
|
|
165
|
+
* unconditionally. They reuse the builders `generateEvidenceModel()` calls,
|
|
166
|
+
* so there is no second implementation of the same assembly. See ADR 0038.
|
|
167
167
|
*/
|
|
168
168
|
export declare function computeArtifacts(options: GenerateEnvArtifactsOptions): Promise<ComputeArtifactsResult>;
|
|
169
169
|
/**
|
|
170
170
|
* Orchestrates {@link generateEnvManifest}/{@link generateDocumentation}/
|
|
171
|
-
* {@link generateUsageReport}, plus the persisted evidence artifact
|
|
172
|
-
*
|
|
173
|
-
*
|
|
174
|
-
*
|
|
171
|
+
* {@link generateUsageReport}, plus the persisted evidence artifact. It
|
|
172
|
+
* composes their shared private compute/write pipeline directly. Schema
|
|
173
|
+
* discovery+linking runs exactly once, however many outputs are requested.
|
|
174
|
+
* It is an orchestrator, not a new analysis engine (see ADR 0011).
|
|
175
175
|
*
|
|
176
176
|
* @remarks
|
|
177
177
|
* Two distinct atomicity guarantees, not one:
|
|
@@ -182,8 +182,8 @@ export declare function computeArtifacts(options: GenerateEnvArtifactsOptions):
|
|
|
182
182
|
* begin, each `fs.writeFile` is independent. A real I/O failure partway
|
|
183
183
|
* through (disk full, permissions changed mid-run) can leave some
|
|
184
184
|
* artifacts on disk and not others. Transactional (temp-file + rename)
|
|
185
|
-
* writes across all three artifacts
|
|
186
|
-
* disproportionate machinery for a rare failure mode
|
|
185
|
+
* writes across all three artifacts are not used. They would be
|
|
186
|
+
* disproportionate machinery for a rare failure mode: see ADR 0011.
|
|
187
187
|
*
|
|
188
188
|
* @throws {EnvProjectGenerationError} If any requested output location escapes `root`, or if any requested pass reports a blocking finding.
|
|
189
189
|
*/
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"generate-env-artifacts.d.ts","sourceRoot":"","sources":["../../../src/build/generate-env-artifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAM5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAOxD,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAMhE,OAAO,KAAK,EACV,wBAAwB,EACxB,4BAA4B,EAC5B,2BAA2B,EAC5B,MAAM,6BAA6B,CAAA;AAOpC,OAAO,KAAK,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,mBAAmB,EACpB,MAAM,wBAAwB,CAAA;AAE/B,OAAO,KAAK,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,gBAAgB,EACjB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAInD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,gDAAgD;AAChD,MAAM,WAAW,2BAA2B;IAC1C,
|
|
1
|
+
{"version":3,"file":"generate-env-artifacts.d.ts","sourceRoot":"","sources":["../../../src/build/generate-env-artifacts.ts"],"names":[],"mappings":"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"}
|
|
@@ -3,7 +3,7 @@ import type { LiveExpirationDates } from "./live-expirations.js";
|
|
|
3
3
|
import type { BuildFileSystem } from "./types.js";
|
|
4
4
|
/** Options for {@link generateEvidenceModel}. */
|
|
5
5
|
export interface GenerateEvidenceModelOptions {
|
|
6
|
-
/** The filesystem capability
|
|
6
|
+
/** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
|
|
7
7
|
fs: BuildFileSystem;
|
|
8
8
|
/** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
|
|
9
9
|
root?: string | undefined;
|
|
@@ -17,10 +17,10 @@ export interface GenerateEvidenceModelOptions {
|
|
|
17
17
|
tsconfig?: string | false | undefined;
|
|
18
18
|
/**
|
|
19
19
|
* Where a previously-persisted evidence artifact lives, relative to
|
|
20
|
-
* `root
|
|
20
|
+
* `root`: read (never written) as the baseline Change Model diffs
|
|
21
21
|
* against and dynamic-access citation freshness (ADR 0037) compares
|
|
22
22
|
* content hashes to. Independent of any `.ts` manifest a project may or
|
|
23
|
-
* may not also generate
|
|
23
|
+
* may not also generate: there is no derivation from a manifest's own
|
|
24
24
|
* location. Omitted: treated as the normal first-run state (everything
|
|
25
25
|
* reads as added, no citation-freshness baseline to compare against),
|
|
26
26
|
* never an error.
|
|
@@ -31,45 +31,45 @@ export interface GenerateEvidenceModelOptions {
|
|
|
31
31
|
/**
|
|
32
32
|
* Supplies expiration metadata from a live source as a post-discovery
|
|
33
33
|
* override, applied to Lifecycle Model's (and Finding Model's
|
|
34
|
-
* `expiring-soon` findings') data only
|
|
34
|
+
* `expiring-soon` findings') data only: Contract Model still reflects the
|
|
35
35
|
* schema's own static `expiresAt`. See `live-expirations.ts` and ADR 0012.
|
|
36
36
|
*/
|
|
37
37
|
liveExpirationDates?: LiveExpirationDates | undefined;
|
|
38
38
|
/**
|
|
39
39
|
* Resolves the commit SHA to stamp onto `EvidenceModel.provenance.commit`.
|
|
40
40
|
* Invoked at most once, after discovery/linking completes. env-cap never
|
|
41
|
-
* shells out to `git` itself
|
|
41
|
+
* shells out to `git` itself: see ADR 0012's callback precedent. Omitted:
|
|
42
42
|
* `commit` is `undefined`.
|
|
43
43
|
*/
|
|
44
44
|
commit?: (() => Promise<string | undefined>) | undefined;
|
|
45
45
|
}
|
|
46
46
|
/**
|
|
47
|
-
* Node-only assembly orchestrator (ADR 0024, ADR 0031)
|
|
47
|
+
* Node-only assembly orchestrator (ADR 0024, ADR 0031). It runs schema
|
|
48
48
|
* discovery and linking once (via `assembleProject()`, shared with
|
|
49
|
-
* `computeArtifacts()`)
|
|
50
|
-
* calling each model's own public builder directly
|
|
51
|
-
*
|
|
49
|
+
* `computeArtifacts()`). It then builds all seven canonical fact models by
|
|
50
|
+
* calling each model's own public builder directly. This function adds no
|
|
51
|
+
* derivation logic of its own, only sequencing and the shared
|
|
52
52
|
* discovery/linking every builder needs. The result is `deepFreeze()`-d
|
|
53
53
|
* before being returned.
|
|
54
54
|
*
|
|
55
55
|
* @remarks
|
|
56
56
|
* Deliberately never throws on a data-quality finding (a compatibility
|
|
57
|
-
* issue, an undocumented variable, an abandoned contract, ...)
|
|
57
|
+
* issue, an undocumented variable, an abandoned contract, ...): every one
|
|
58
58
|
* of those becomes a `Finding` in the returned model's `finding` field
|
|
59
|
-
* instead. This
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
* `EnvProjectGenerationError` for a genuine configuration error
|
|
59
|
+
* instead. This differs from `generateEnvManifest()`, which throws by
|
|
60
|
+
* default, because that is a "should I write this artifact" gate. Evidence
|
|
61
|
+
* Model assembly is a read-only snapshot. Its purpose is to represent such
|
|
62
|
+
* issues as data for a consumer's own projection to act on (see ADR 0024's
|
|
63
|
+
* mission statement). It still throws
|
|
64
|
+
* `EnvProjectGenerationError` for a genuine configuration error:
|
|
65
65
|
* `previousSnapshotLocation` escaping `root`.
|
|
66
66
|
*
|
|
67
67
|
* The dependency-graph scan underlying Dependency Model (via
|
|
68
68
|
* `buildDependencyModel()`) and the one underlying Finding Model's
|
|
69
69
|
* ownership-related findings (via `computeUsage()`) each run their own,
|
|
70
|
-
* independent pass over the repository
|
|
71
|
-
*
|
|
72
|
-
*
|
|
70
|
+
* independent pass over the repository. That cost is accepted: each half's
|
|
71
|
+
* already-tested public building block is called directly, rather than a
|
|
72
|
+
* second copy of either's logic being hand-derived here. Both are Node-only,
|
|
73
73
|
* dev/CI-time-only work (never a runtime hot path), so the redundant I/O is
|
|
74
74
|
* an honest tradeoff, not an oversight.
|
|
75
75
|
*/
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"generate-evidence.d.ts","sourceRoot":"","sources":["../../../src/build/generate-evidence.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAYxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C
|
|
1
|
+
{"version":3,"file":"generate-evidence.d.ts","sourceRoot":"","sources":["../../../src/build/generate-evidence.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAYxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,+EAA+E;IAC/E,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAA;IACrD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,aAAa,CAAC,CAyHxB"}
|
|
@@ -4,7 +4,7 @@ import { type DiscoveredContract, type DiscoveredContractSummary, type LinkResul
|
|
|
4
4
|
import type { ParseWarning } from "./parse.js";
|
|
5
5
|
/** Options for {@link generateEnvManifest}. */
|
|
6
6
|
export interface GenerateEnvManifestOptions {
|
|
7
|
-
/** The filesystem capability
|
|
7
|
+
/** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
|
|
8
8
|
fs: BuildFileSystem;
|
|
9
9
|
/** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
|
|
10
10
|
root?: string | undefined;
|
|
@@ -28,7 +28,7 @@ export interface GenerateEnvManifestOptions {
|
|
|
28
28
|
* whose `compilerOptions.paths`/`baseUrl` resolve aliased import specifiers (e.g.
|
|
29
29
|
* `"@/lib/env.schema.js"`) encountered during static analysis, so a contract or consumer
|
|
30
30
|
* reached only through an alias isn't misreported as abandoned/unresolved. Defaults to
|
|
31
|
-
* `"tsconfig.json"` at `root
|
|
31
|
+
* `"tsconfig.json"` at `root`: on automatically, no opt-in required, since (unlike
|
|
32
32
|
* `packages`) this never crosses a trust/versioning boundary: every resolved file is
|
|
33
33
|
* already local, already-trusted project source. Pass `false` to disable entirely. See
|
|
34
34
|
* ADR 0023.
|
|
@@ -54,14 +54,13 @@ export interface GenerateEnvManifestResult {
|
|
|
54
54
|
}
|
|
55
55
|
/**
|
|
56
56
|
* Default value for {@link GenerateEnvManifestOptions.include}. A function
|
|
57
|
-
* (not a bare module-level `const`) so every call gets its own fresh array
|
|
58
|
-
*
|
|
57
|
+
* (not a bare module-level `const`) so every call gets its own fresh array.
|
|
58
|
+
* A shared literal used from many files (`evidence-cache.ts`,
|
|
59
59
|
* `generate-documentation.ts`, `generate-evidence.ts`,
|
|
60
|
-
* `generate-env-artifacts.ts`, `generate-usage.ts`)
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
* drive's memory for the fully-documented limitation.
|
|
60
|
+
* `generate-env-artifacts.ts`, `generate-usage.ts`) attracts covered-static
|
|
61
|
+
* mutants under Stryker's `coverageAnalysis: perTest` + `ignoreStatic: true`.
|
|
62
|
+
* A mutant on module-load code that a test still references is run anyway
|
|
63
|
+
* and falsely reported "Survived".
|
|
65
64
|
*/
|
|
66
65
|
export declare function defaultInclude(): string[];
|
|
67
66
|
/** Default value for {@link GenerateEnvManifestOptions.exclude}. Same reasoning as {@link defaultInclude}. */
|
|
@@ -73,12 +72,12 @@ export interface ManifestComputation {
|
|
|
73
72
|
readonly blocking: readonly CompatibilityIssue[];
|
|
74
73
|
}
|
|
75
74
|
/**
|
|
76
|
-
* Pure
|
|
75
|
+
* Pure: no I/O. Runs compatibility (0005) and exclusive-group (0009,
|
|
77
76
|
* always-error, never gated by `onIncompatibility`) checks against an
|
|
78
77
|
* already-discovered contract graph and applies the `onIncompatibility` gate.
|
|
79
78
|
* Shared by the standalone `generateEnvManifest()` (which discovers its own
|
|
80
79
|
* graph) and `generate-env-artifacts.ts` (which discovers once and reuses it across
|
|
81
|
-
* manifest/docs/usage)
|
|
80
|
+
* manifest/docs/usage): see ADR 0011.
|
|
82
81
|
*/
|
|
83
82
|
export declare function computeManifest(root: string, linkResult: LinkResult, onIncompatibility: "warn" | "throw" | undefined): ManifestComputation;
|
|
84
83
|
/** Writes the manifest file. Callers must have already confirmed `outputPath` is safe and nothing is blocking. */
|
|
@@ -92,7 +91,7 @@ export declare function writeManifest(outputPath: string, activeContracts: reado
|
|
|
92
91
|
*
|
|
93
92
|
* @remarks
|
|
94
93
|
* Never call this at application startup or import it from
|
|
95
|
-
* runtime code
|
|
94
|
+
* runtime code: wire it into an npm script, a bundler plugin, or a CI
|
|
96
95
|
* step instead.
|
|
97
96
|
*
|
|
98
97
|
* @throws {EnvManifestGenerationError} If `location` escapes `root`, or if a blocking compatibility/exclusive-group issue is found.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"generate-manifest.d.ts","sourceRoot":"","sources":["../../../src/build/generate-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAG5D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EAChB,MAAM,WAAW,CAAA;AAElB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC
|
|
1
|
+
{"version":3,"file":"generate-manifest.d.ts","sourceRoot":"","sources":["../../../src/build/generate-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAG5D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EAChB,MAAM,WAAW,CAAA;AAElB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yGAAyG;IACzG,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CACjD;AAED,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACxD,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,4GAA4G;IAC5G,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;CAChD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AACD,8GAA8G;AAC9G,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAczC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,eAAe,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACvD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAChE,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,iBAAiB,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAC9C,mBAAmB,CAwBrB;AAED,kHAAkH;AAClH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAoCpC"}
|
|
@@ -8,12 +8,12 @@ import { type RenderUsageReportOptions } from "./usage-report.js";
|
|
|
8
8
|
/**
|
|
9
9
|
* Computes the full usage-scan surface: the local project root, plus (ADR
|
|
10
10
|
* 0036) each allow-listed `packages` (ADR 0014) name whose schema was
|
|
11
|
-
* successfully resolved
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
* `SCAN_INCLUDE`/`defaultExclude()` policy the local root
|
|
16
|
-
*
|
|
11
|
+
* successfully resolved. Each such package's `packageDir` becomes a bounded
|
|
12
|
+
* scan root. It is reused from `origins` (computed by
|
|
13
|
+
* `resolveAllowlistedPackages()` for contract discovery), not re-resolved
|
|
14
|
+
* here. That root is walked with the same `discoverFiles()` +
|
|
15
|
+
* `SCAN_INCLUDE`/`defaultExclude()` policy as the local root, never as a
|
|
16
|
+
* naive, unbounded walk of the package's whole directory. Shared by
|
|
17
17
|
* `generateUsageReport()` and `generateEvidenceModel()` so both agree on
|
|
18
18
|
* exactly the same scanned surface.
|
|
19
19
|
*/
|
|
@@ -23,11 +23,11 @@ export declare function computeScanSurface(root: string, exclude: readonly strin
|
|
|
23
23
|
}>;
|
|
24
24
|
/** Options for {@link generateUsageReport}. */
|
|
25
25
|
export interface GenerateUsageReportOptions {
|
|
26
|
-
/** The filesystem capability
|
|
26
|
+
/** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
|
|
27
27
|
fs: BuildFileSystem;
|
|
28
28
|
/** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
|
|
29
29
|
root?: string | undefined;
|
|
30
|
-
/** Schema-discovery glob, for the contract graph
|
|
30
|
+
/** Schema-discovery glob, for the contract graph: self-sufficient like the other two generator functions. */
|
|
31
31
|
include?: string[] | undefined;
|
|
32
32
|
/** Glob patterns to exclude, for both schema discovery and the usage scan. Defaults to node_modules/dist/.git. */
|
|
33
33
|
exclude?: string[] | undefined;
|
|
@@ -45,10 +45,10 @@ export interface GenerateUsageReportOptions {
|
|
|
45
45
|
* Public result of {@link generateUsageReport}.
|
|
46
46
|
*
|
|
47
47
|
* @remarks
|
|
48
|
-
* Composed from the building-block types `usage-report.ts` (the renderer) owns
|
|
49
|
-
* `GenerateDocumentationResult` composes from `docs.ts`'s `CatalogContract
|
|
50
|
-
*
|
|
51
|
-
*
|
|
48
|
+
* Composed from the building-block types `usage-report.ts` (the renderer) owns. That mirrors how
|
|
49
|
+
* `GenerateDocumentationResult` composes from `docs.ts`'s `CatalogContract`. It keeps the
|
|
50
|
+
* renderer importable without its orchestrator (see `RenderUsageReportOptions`'s own doc
|
|
51
|
+
* comment).
|
|
52
52
|
*/
|
|
53
53
|
export interface GenerateUsageReportResult extends RenderUsageReportOptions {
|
|
54
54
|
/** Absolute path the report was written to, or `undefined` if `options.report` wasn't passed. */
|
|
@@ -61,32 +61,31 @@ export interface UsageComputation {
|
|
|
61
61
|
}
|
|
62
62
|
/**
|
|
63
63
|
* Builds the dependency graph and maps it into the public, ownership-framed
|
|
64
|
-
* result. Never blocks
|
|
65
|
-
*
|
|
66
|
-
* `Finding[]` (the "ownership" family) from the persisted evidence artifact
|
|
67
|
-
*
|
|
64
|
+
* result. Never blocks: see the doc comments on `RenderUsageReportOptions`'s
|
|
65
|
+
* finding fields. A team that wants to gate CI on an ownership issue reads
|
|
66
|
+
* `Finding[]` (the "ownership" family) from the persisted evidence artifact.
|
|
67
|
+
* It then decides for itself. See ADR 0038.
|
|
68
68
|
*
|
|
69
69
|
* @remarks
|
|
70
70
|
* This mapping is the actual API boundary: internal AST vocabulary
|
|
71
71
|
* ("member accessed", "dynamic") becomes ownership vocabulary ("who owns
|
|
72
72
|
* it", "who consumes it", "abandoned", "unresolved"). The result is a
|
|
73
|
-
* renderer-agnostic domain model
|
|
74
|
-
*
|
|
75
|
-
* renderer.
|
|
73
|
+
* renderer-agnostic domain model. A future JSON or SARIF exporter would
|
|
74
|
+
* consume the same data; it is not coupled to the Markdown renderer.
|
|
76
75
|
*/
|
|
77
76
|
export declare function computeUsage(root: string, contracts: readonly DiscoveredContract[], scanFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, scannedSurfaces?: readonly ScannedSurface[], dynamicAccessAcknowledgments?: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): Promise<UsageComputation>;
|
|
78
77
|
/** Writes the Dependency & Ownership Report. Callers must have already confirmed `reportPath` is safe and nothing is blocking. */
|
|
79
78
|
export declare function writeUsageReport(reportPath: string, computed: Omit<GenerateUsageReportResult, "reportPath">, fs: BuildFileSystem): Promise<void>;
|
|
80
79
|
/**
|
|
81
80
|
* Build-time only. Answers who owns each contract, which features depend on
|
|
82
|
-
* it, and what the blast radius is if it changes
|
|
83
|
-
* {@link generateEnvManifest}'s "safer migrations" story
|
|
84
|
-
* wired up, or was abandoned mid-removal, shows up here instead of
|
|
85
|
-
* unnoticed.
|
|
81
|
+
* it, and what the blast radius is if it changes. It is the mirror image of
|
|
82
|
+
* {@link generateEnvManifest}'s "safer migrations" story. A schema that was
|
|
83
|
+
* never wired up, or was abandoned mid-removal, shows up here instead of
|
|
84
|
+
* sitting unnoticed.
|
|
86
85
|
*
|
|
87
86
|
* @remarks
|
|
88
87
|
* This is an additional, separate artifact, not a replacement for
|
|
89
|
-
* {@link generateDocumentation}'s Catalog
|
|
88
|
+
* {@link generateDocumentation}'s Catalog: the two serve different audiences
|
|
90
89
|
* (see ADR 0010).
|
|
91
90
|
*
|
|
92
91
|
* @throws {EnvUsageAnalysisError} If `report.location` escapes `root`.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"generate-usage.d.ts","sourceRoot":"","sources":["../../../src/build/generate-usage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAS5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAE3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAClE,OAAO,EAML,KAAK,wBAAwB,EAG9B,MAAM,mBAAmB,CAAA;AAE1B;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,EAC3C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,EAAE,cAAc,EAAE,CAAA;CAAE,CAAC,CAmCrE;AAED,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC
|
|
1
|
+
{"version":3,"file":"generate-usage.d.ts","sourceRoot":"","sources":["../../../src/build/generate-usage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAS5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAE3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAClE,OAAO,EAML,KAAK,wBAAwB,EAG9B,MAAM,mBAAmB,CAAA;AAE1B;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,EAC3C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,EAAE,cAAc,EAAE,CAAA;CAAE,CAAC,CAmCrE;AAED,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,6GAA6G;IAC7G,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,kHAAkH;IAClH,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC,mIAAmI;IACnI,MAAM,CAAC,EACH;QACE,sDAAsD;QACtD,QAAQ,EAAE,MAAM,CAAA;KACjB,GACD,SAAS,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IACzE,iGAAiG;IACjG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,qIAAqI;IACrI,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,wBAAwB,EAAE,eAAe,CAAC,CAAA;CACjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,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,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,EAC3C,4BAA4B,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,GACpF,OAAO,CAAC,gBAAgB,CAAC,CAsI3B;AAED,kIAAkI;AAClI,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,IAAI,CAAC,yBAAyB,EAAE,YAAY,CAAC,EACvD,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAkDpC"}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Regeneration instruction for a report the CLI does not write (ADR 0046)
|
|
2
|
+
* Regeneration instruction for a report the CLI does not write (ADR 0046): it is produced by the project's own
|
|
3
3
|
* script calling the `@maverickcer/env-cap/build` generators, so naming `npx env-cap` there would send a reader to a command that
|
|
4
4
|
* cannot regenerate it.
|
|
5
5
|
* @returns The instruction, as a sentence.
|
|
@@ -16,10 +16,10 @@ export declare function generatedBanner(format?: "ts" | "markdown", regenerate?:
|
|
|
16
16
|
* Whether `content` carries a {@link generatedBanner}-produced marker, in either format.
|
|
17
17
|
*
|
|
18
18
|
* @remarks
|
|
19
|
-
* Deliberately not a bare `content.startsWith(generatedBanner(...))
|
|
20
|
-
* license header pushes a real banner off line one
|
|
21
|
-
*
|
|
22
|
-
*
|
|
19
|
+
* Deliberately not a bare `content.startsWith(generatedBanner(...))`. A shebang, a `"use strict"` pragma, or a
|
|
20
|
+
* license header pushes a real banner off line one. A stricter check would then read a generated file as
|
|
21
|
+
* hand-written. The dependency scan would take that as "a real consumer imports this" and so permanently mask an
|
|
22
|
+
* abandoned contract. The marker is looked for across the first 20 non-empty lines instead,
|
|
23
23
|
* which clears every realistic preamble without scanning a whole file.
|
|
24
24
|
* @param content - A file's text.
|
|
25
25
|
* @returns `true` when the file is generated.
|
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The declared governance-metadata field set every pipeline-stage contract and
|
|
3
|
-
* variable type carries
|
|
4
|
-
* are identical at every stage (parse -> link -> contract-model -> docs)
|
|
5
|
-
* the surrounding context differs
|
|
6
|
-
* from a string literal, or `undefined`"
|
|
7
|
-
* is "from the linked `documentEnv()` call, or `undefined`"
|
|
3
|
+
* variable type carries: `owner` through `metadata`. The field names and types
|
|
4
|
+
* are identical at every stage (parse -> link -> contract-model -> docs). Only
|
|
5
|
+
* the surrounding context differs. A `parse`-stage value is "statically resolved
|
|
6
|
+
* from a string literal, or `undefined`". A `link`/`contract-model`-stage value
|
|
7
|
+
* is "from the linked `documentEnv()` call, or `undefined`". This is the single
|
|
8
8
|
* source of truth for the shape; each stage interface `extends` it.
|
|
9
9
|
*
|
|
10
10
|
* `metadata` is the open bag for keys `env-cap` has no named concept for (ADR
|
|
11
11
|
* 0037); `dataResidency`/`auditRequired`/`legalBasis`/`purpose`/`retention` are
|
|
12
12
|
* presence-only governance facts, never verified.
|
|
13
13
|
*
|
|
14
|
-
* Internal
|
|
14
|
+
* Internal: not re-exported from the public `.` barrel.
|
|
15
15
|
*/
|
|
16
16
|
export interface EnvGovernanceFields {
|
|
17
17
|
readonly owner: string | undefined;
|
|
@@ -26,7 +26,7 @@ export interface EnvGovernanceFields {
|
|
|
26
26
|
}
|
|
27
27
|
/**
|
|
28
28
|
* Copies exactly the `EnvGovernanceFields` out of a value that carries
|
|
29
|
-
* them
|
|
29
|
+
* them: for projecting one pipeline stage's contract/variable into the next
|
|
30
30
|
* (`link` -> `contract-model` -> `docs` catalog, ...) without re-listing all
|
|
31
31
|
* nine fields at every hop.
|
|
32
32
|
*/
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
*/
|
|
6
6
|
export declare function humanizeKey(key: string): string;
|
|
7
7
|
/**
|
|
8
|
-
* Formats a `metadata`/`dataResidency` value for display in generated docs/examples
|
|
8
|
+
* Formats a `metadata`/`dataResidency` value for display in generated docs/examples: a string
|
|
9
9
|
* renders as-is; anything else (ADR 0035 widened `metadata` to any value) renders as its JSON
|
|
10
10
|
* text, so an object/array value never prints `[object Object]`. Shared by `docs.ts` and
|
|
11
11
|
* `env-example.ts`, same rationale as {@link humanizeKey}.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"humanize-key.d.ts","sourceRoot":"","sources":["../../../src/build/humanize-key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,
|
|
1
|
+
{"version":3,"file":"humanize-key.d.ts","sourceRoot":"","sources":["../../../src/build/humanize-key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO/C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE1D"}
|