@maverickcer/env-cap 0.7.4 → 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 +15 -0
- package/CODE_REVIEW.md +69 -173
- package/CONTRIBUTING.md +57 -74
- package/GUIDE.md +393 -872
- package/README.md +81 -76
- 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.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-6XFHJFQK.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-RL5KFVUT.js → chunk-HAGMVMN5.js} +2 -2
- package/dist/cli/index.js +3 -3
- package/dist/eslint-plugin/index.cjs.map +1 -1
- 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 +27 -4
- 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-6XFHJFQK.js.map +0 -1
- /package/dist/{chunk-RL5KFVUT.js.map → chunk-HAGMVMN5.js.map} +0 -0
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
import type { DynamicAccessCitationProblem } from "./citation-verification.js";
|
|
2
|
+
import type { ContractRef } from "./evidence-reference.js";
|
|
3
|
+
import type { ContractModelContract } from "./contract-model.js";
|
|
4
|
+
import type { EvidenceModel } from "./evidence-model.js";
|
|
5
|
+
import type { DiscoveredContract } from "./link.js";
|
|
6
|
+
import type { ParseWarning } from "./parse.js";
|
|
7
|
+
import type { DynamicAccessAssertion } from "./source-position.js";
|
|
8
|
+
import type { BuildFileSystem } from "./types.js";
|
|
9
|
+
/**
|
|
10
|
+
* The persisted evidence artifact and everything that reads/diffs it.
|
|
11
|
+
*
|
|
12
|
+
* Not a sibling of `env.manifest.ts`. `env.manifest.ts` is a *runtime build
|
|
13
|
+
* artifact* -- real TypeScript, imported and executed by the running
|
|
14
|
+
* application. This module's own artifact is a *CI/reporting artifact*: the
|
|
15
|
+
* literal `EvidenceModel` a caller gets back from `generateEvidenceModel()`,
|
|
16
|
+
* serialized to disk, read only by `--check`, by CI tooling, and by whatever
|
|
17
|
+
* a project's own reporting/projection code chooses to do with it -- never
|
|
18
|
+
* imported by anything under `src/runtime/`, never a build input to the
|
|
19
|
+
* application itself. Its location is never derived from a manifest's own
|
|
20
|
+
* output path (there is no `<manifest>.snapshot.json` sidecar mechanism
|
|
21
|
+
* anymore); a caller supplies it directly, independent of whether a `.ts`
|
|
22
|
+
* manifest is even being generated at all.
|
|
23
|
+
*
|
|
24
|
+
* Two jobs, one file: this is both (a) the baseline `diffContracts()`
|
|
25
|
+
* compares the current run's `ContractModel` against to produce
|
|
26
|
+
* `ManifestChangeReport`, and (b) the committed-baseline content-hash source
|
|
27
|
+
* `buildCitationSnapshots()` (`citation-verification.ts`) uses to tell a
|
|
28
|
+
* "fresh" developer dynamic-access citation from a "stale" one (ADR 0037).
|
|
29
|
+
* Whether a project commits this file to git or regenerates it fresh every CI
|
|
30
|
+
* run is that project's call -- a missing file is always treated as the normal
|
|
31
|
+
* first-run state, never an error.
|
|
32
|
+
*/
|
|
33
|
+
/** One field's before/after value in a {@link ManifestContractUpdate} or {@link ManifestVariableUpdate}. */
|
|
34
|
+
export interface ManifestFieldChange {
|
|
35
|
+
/** The changed field's name. */
|
|
36
|
+
readonly field: string;
|
|
37
|
+
/** The value from the previous snapshot, or `undefined` if the field was unset. */
|
|
38
|
+
readonly previous: string | undefined;
|
|
39
|
+
/** The value in the current run, or `undefined` if the field is now unset. */
|
|
40
|
+
readonly current: string | undefined;
|
|
41
|
+
}
|
|
42
|
+
/** Identifies one contract for {@link ManifestChangeReport} purposes -- see {@link ContractRef} for why neither a `contractName` nor a pre-formatted `identity` is carried here. */
|
|
43
|
+
export type ManifestContractRef = ContractRef;
|
|
44
|
+
/** Identifies one variable for {@link ManifestChangeReport} purposes -- its owning contract's identity plus its own key. See {@link ContractRef}. */
|
|
45
|
+
export interface ManifestVariableRef extends ContractRef {
|
|
46
|
+
/** The environment variable name. */
|
|
47
|
+
readonly key: string;
|
|
48
|
+
}
|
|
49
|
+
/** A contract present in both snapshots, with at least one changed field. */
|
|
50
|
+
export interface ManifestContractUpdate extends ManifestContractRef {
|
|
51
|
+
/** Every field that changed between the previous and current snapshot. */
|
|
52
|
+
readonly changes: readonly ManifestFieldChange[];
|
|
53
|
+
}
|
|
54
|
+
/** A variable present in both snapshots, with at least one changed field. */
|
|
55
|
+
export interface ManifestVariableUpdate extends ManifestVariableRef {
|
|
56
|
+
/** Every field that changed between the previous and current snapshot. */
|
|
57
|
+
readonly changes: readonly ManifestFieldChange[];
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* The result of diffing two `ContractModel.contracts` arrays -- see
|
|
61
|
+
* `diffContracts()`. Comprehensive by construction: every own field of
|
|
62
|
+
* `ContractModelContract`/`ContractModelVariable` (schema facts --
|
|
63
|
+
* `hasDefault`/`processorSource`/`validatorSource`/... -- alongside
|
|
64
|
+
* documented metadata) participates, and every discovered contract is
|
|
65
|
+
* covered, not only active ones. A field-by-field, hand-maintained diff
|
|
66
|
+
* (this module's previous design) would need updating by hand every time
|
|
67
|
+
* Contract Model gains a field; the generic differ below can't drift out of
|
|
68
|
+
* sync with the model it diffs.
|
|
69
|
+
*/
|
|
70
|
+
export interface ManifestChangeReport {
|
|
71
|
+
/** Contracts present now but not in the previous snapshot. */
|
|
72
|
+
readonly addedContracts: readonly ManifestContractRef[];
|
|
73
|
+
/** Contracts present in the previous snapshot but not now. */
|
|
74
|
+
readonly removedContracts: readonly ManifestContractRef[];
|
|
75
|
+
/** Variables present now but not in the previous snapshot. */
|
|
76
|
+
readonly addedVariables: readonly ManifestVariableRef[];
|
|
77
|
+
/** Variables present in the previous snapshot but not now. */
|
|
78
|
+
readonly removedVariables: readonly ManifestVariableRef[];
|
|
79
|
+
/** Contracts present in both snapshots with at least one changed field. */
|
|
80
|
+
readonly updatedContracts: readonly ManifestContractUpdate[];
|
|
81
|
+
/** Variables present in both snapshots with at least one changed field. */
|
|
82
|
+
readonly updatedVariables: readonly ManifestVariableUpdate[];
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Pure. `previous === undefined` (no snapshot last time, for any reason --
|
|
86
|
+
* see `EvidenceSnapshotReadResult`) reports everything in `current` as
|
|
87
|
+
* added, nothing as removed/updated.
|
|
88
|
+
*/
|
|
89
|
+
export declare function diffContracts(previous: readonly ContractModelContract[] | undefined, current: readonly ContractModelContract[]): ManifestChangeReport;
|
|
90
|
+
/** Distinguishes *why* there's no usable previous snapshot, rather than collapsing every case into a bare `undefined`. A missing file is the normal, silent, expected first-run/never-configured case. An unparseable file or a `schemaVersion` this build doesn't recognize are both real, diagnosable problems. */
|
|
91
|
+
export type EvidenceSnapshotReadResult = {
|
|
92
|
+
readonly status: "missing";
|
|
93
|
+
} | {
|
|
94
|
+
readonly status: "invalid-json";
|
|
95
|
+
readonly detail: string;
|
|
96
|
+
} | {
|
|
97
|
+
readonly status: "unsupported-version";
|
|
98
|
+
readonly foundVersion: unknown;
|
|
99
|
+
} | {
|
|
100
|
+
readonly status: "ok";
|
|
101
|
+
readonly snapshot: EvidenceModel;
|
|
102
|
+
};
|
|
103
|
+
export declare function readEvidenceSnapshot(snapshotPath: string, fs: BuildFileSystem): Promise<EvidenceSnapshotReadResult>;
|
|
104
|
+
export declare function writeEvidenceSnapshot(snapshotPath: string, snapshot: EvidenceModel, fs: BuildFileSystem): Promise<void>;
|
|
105
|
+
/**
|
|
106
|
+
* `snapshot`, with two fields normalized to a constant -- the comparison
|
|
107
|
+
* basis `--check` uses:
|
|
108
|
+
*
|
|
109
|
+
* - `provenance.generatedAt` is a live timestamp stamped fresh on every real
|
|
110
|
+
* `generate` run; comparing it byte-for-byte against a
|
|
111
|
+
* freshly-rendered-for-`--check` copy would report drift every single
|
|
112
|
+
* time, even with zero real changes, since the two renders' timestamps
|
|
113
|
+
* can never match. `toolVersion`/`commit` stay compared as-is -- both are
|
|
114
|
+
* real, meaningfully-stable provenance across a `--check` run and the
|
|
115
|
+
* `generate` run it's verifying, not something that varies on its own.
|
|
116
|
+
* - `change` describes "what's different from whatever snapshot was on disk
|
|
117
|
+
* the moment this run computed it" -- inherently not reproducible by a
|
|
118
|
+
* second computation, since by the time `--check` re-derives it, the file
|
|
119
|
+
* just written *is* the new baseline (the diff naturally comes back empty
|
|
120
|
+
* against itself). This isn't drift; it's `change`'s own definition, so
|
|
121
|
+
* `--check` doesn't attempt to re-verify it, the same treatment as
|
|
122
|
+
* `generatedAt`.
|
|
123
|
+
* - every `now`-relative expiry countdown -- `lifecycle.expiring[].daysRemaining`
|
|
124
|
+
* and the day-count inside an `EXPIRED`/`EXPIRING_SOON` finding message -- is
|
|
125
|
+
* the same class as `generatedAt`: a static `expiresAt` produces a different
|
|
126
|
+
* number every day, so a committed artifact would go "stale" with zero real
|
|
127
|
+
* edits. Normalized to a constant so `--check` (and the golden tests) verify
|
|
128
|
+
* the substance, not the calendar. The raw `expiresAt` strings stay compared.
|
|
129
|
+
*/
|
|
130
|
+
export declare function normalizeEvidenceSnapshotForComparison(snapshot: EvidenceModel): EvidenceModel;
|
|
131
|
+
/** Everything reading a previous evidence snapshot and diffing the current run against it produces, in one call. Never writes anything itself -- writing the fresh snapshot stays a separate, explicit step on the real write path. */
|
|
132
|
+
export interface EvidenceChangesComputation {
|
|
133
|
+
readonly report: ManifestChangeReport;
|
|
134
|
+
/** Set only when the previous snapshot existed but was unusable (corrupt JSON or an unrecognized `schemaVersion`) -- never set for the ordinary "no snapshot yet" first-run case. */
|
|
135
|
+
readonly readWarning: ParseWarning | undefined;
|
|
136
|
+
readonly dynamicAccessAcknowledgments: ReadonlyMap<string, readonly DynamicAccessAssertion[]>;
|
|
137
|
+
readonly dynamicAccessCitationProblems: readonly DynamicAccessCitationProblem[];
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* The one I/O-performing helper every caller wanting change/citation-freshness
|
|
141
|
+
* data shares: reads the previous evidence snapshot (if `snapshotPath` is
|
|
142
|
+
* given and a file exists there), diffs the current run's `ContractModel`
|
|
143
|
+
* against it, and re-checks every current `dynamicAccess` citation's
|
|
144
|
+
* freshness. `snapshotPath` is always caller-supplied, directly -- there is
|
|
145
|
+
* no derivation from a manifest's own output path.
|
|
146
|
+
*/
|
|
147
|
+
export declare function computeEvidenceChanges(root: string, snapshotPath: string, activeContracts: readonly DiscoveredContract[], currentContracts: readonly ContractModelContract[], readFile: (filePath: string) => Promise<string>, fs: BuildFileSystem): Promise<EvidenceChangesComputation>;
|
|
148
|
+
//# sourceMappingURL=evidence-snapshot.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"evidence-snapshot.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-snapshot.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { CompatibilityIssue } from "./compatibility.js";
|
|
2
|
+
import type { DiscoveredContract } from "./link.js";
|
|
3
|
+
/**
|
|
4
|
+
* Detects two *active* contracts declaring the same `exclusiveGroup` --
|
|
5
|
+
* e.g. two interchangeable database backends both left enabled at once.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* Unlike `detectCompatibilityIssues`, this is never a heuristic warning: an
|
|
9
|
+
* author explicitly declared these contracts mutually exclusive, so any
|
|
10
|
+
* violation is always a hard error, regardless of `onIncompatibility`. See
|
|
11
|
+
* ADR 0009 for why this doesn't follow 0005's warn-by-default policy.
|
|
12
|
+
*
|
|
13
|
+
* Inactive contracts are ignored entirely here (filtered internally, not by
|
|
14
|
+
* the caller) so this stays correct even when called directly via the
|
|
15
|
+
* `/build` export -- an inactive contract can share a group with an active
|
|
16
|
+
* one with no conflict, since it was never wired into anything.
|
|
17
|
+
*/
|
|
18
|
+
export declare function detectExclusiveGroupIssues(contracts: readonly DiscoveredContract[]): CompatibilityIssue[];
|
|
19
|
+
//# sourceMappingURL=exclusive-group.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"exclusive-group.d.ts","sourceRoot":"","sources":["../../../src/build/exclusive-group.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,kBAAkB,EAAE,CAuCtB"}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import type { ArtifactCheckFinding } from "./check-artifacts.js";
|
|
2
|
+
import type { CompatibilityIssue, CompatibilityIssueCode } from "./compatibility.js";
|
|
3
|
+
import type { EvidenceReference } from "./evidence-reference.js";
|
|
4
|
+
import type { DocumentationFindings } from "./generate-documentation.js";
|
|
5
|
+
import type { DynamicAccessCitationProblem } from "./citation-verification.js";
|
|
6
|
+
import type { AbandonedContractFinding, IndeterminateOwnershipFinding, UnconsumedOwnedVariableFinding, UnresolvedConsumerFinding } from "./usage-report.js";
|
|
7
|
+
/**
|
|
8
|
+
* The fourth of env-cap's seven canonical fact models (ADR 0024) -- every
|
|
9
|
+
* rule violation and derived risk signal, unified behind one shape, with a
|
|
10
|
+
* stable `code` and a structured {@link EvidenceReference} instead of four
|
|
11
|
+
* independently-shaped finding families. See ADR 0026.
|
|
12
|
+
*/
|
|
13
|
+
/** Every stable `code` a {@link Finding} can carry. A superset of {@link CompatibilityIssueCode} plus one code per non-compatibility source family this model adapts. */
|
|
14
|
+
export type FindingCode = CompatibilityIssueCode | "EXCLUSIVE_GROUP_VIOLATION" | "ARTIFACT_STALE" | "ARTIFACT_MISSING" | "UNDOCUMENTED_CONTRACT" | "UNDOCUMENTED_VARIABLE" | "STALE_DOC_ENTRY" | "EXPIRED" | "EXPIRING_SOON" | "UNRESOLVED_DOCUMENTENV_LINK" | "ABANDONED_CONTRACT" | "UNRESOLVED_CONSUMER" | "UNCONSUMED_OWNED_VARIABLE" | "INDETERMINATE_OWNERSHIP" | "MISSING_DYNAMIC_ACCESS_CITATION" | "STALE_DYNAMIC_ACCESS_CITATION" | "NONSTANDARD_SENSITIVITY_LEVEL";
|
|
15
|
+
/** Which source check produced a {@link Finding} -- coarser than `code`, for a consumer that only wants to filter by kind (e.g. "show me every documentation gap") without enumerating every individual code. */
|
|
16
|
+
export type FindingFamily = "compatibility" | "drift" | "documentation" | "ownership";
|
|
17
|
+
/** One rule violation or derived signal, in the Finding Model's canonical shape. */
|
|
18
|
+
export interface Finding {
|
|
19
|
+
/**
|
|
20
|
+
* `"error"` for a provable, always-blocking violation (e.g. an
|
|
21
|
+
* exclusive-group conflict); `"warning"` for everything gated by
|
|
22
|
+
* `onIncompatibility`/`onUndocumented`/`onOwnershipIssue`'s default "warn"
|
|
23
|
+
* behavior; `"info"` for an observation that is never actionable enough to
|
|
24
|
+
* block anything, even under `--strict` -- see `INFO_ONLY_CODES` in
|
|
25
|
+
* `generate-env-artifacts.ts`.
|
|
26
|
+
*/
|
|
27
|
+
readonly severity: "error" | "warning" | "info";
|
|
28
|
+
/** Stable, machine-readable identifier -- always set, unlike {@link CompatibilityIssue.code} which stays optional on that narrower, pre-existing type. */
|
|
29
|
+
readonly code: FindingCode;
|
|
30
|
+
/** Which source check produced this finding. */
|
|
31
|
+
readonly family: FindingFamily;
|
|
32
|
+
/** Human-readable explanation, reusing the source finding's own prose where one exists. */
|
|
33
|
+
readonly message: string;
|
|
34
|
+
/** Structured pointer back to what this finding is about. */
|
|
35
|
+
readonly location: EvidenceReference;
|
|
36
|
+
}
|
|
37
|
+
/** Bump only when a reader could misinterpret the new shape -- same discipline every other canonical model's `schemaVersion` follows. */
|
|
38
|
+
export declare const FINDING_MODEL_SCHEMA_VERSION = 3;
|
|
39
|
+
/** The versioned, JSON-serializable root of the Finding Model -- every rule violation and derived risk signal from this run, unified behind {@link Finding}'s one shape. See this module's own doc comment for the full picture. */
|
|
40
|
+
export interface FindingModel {
|
|
41
|
+
readonly schemaVersion: typeof FINDING_MODEL_SCHEMA_VERSION;
|
|
42
|
+
readonly findings: readonly Finding[];
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Every source a {@link buildFindingModel} call can adapt, all optional --
|
|
46
|
+
* a caller passes whichever of `generateEnvArtifacts()`'s `manifest`/`docs`/
|
|
47
|
+
* `usage` results it actually requested, exactly like that result's own
|
|
48
|
+
* top-level fields are each independently optional.
|
|
49
|
+
*/
|
|
50
|
+
export interface BuildFindingModelInput {
|
|
51
|
+
/** Every `EvidenceReference.file` below is rendered relative to this, matching every other rendered path in this package's output -- see `displayPath()`. */
|
|
52
|
+
readonly root: string;
|
|
53
|
+
/** From `detectCompatibilityIssues()`. */
|
|
54
|
+
readonly compatibilityIssues?: readonly CompatibilityIssue[];
|
|
55
|
+
/** From `detectExclusiveGroupIssues()` -- kept separate from `compatibilityIssues` since it never sets its own `code` yet (ADR 0009), so this adapter synthesizes `"EXCLUSIVE_GROUP_VIOLATION"` for every entry. */
|
|
56
|
+
readonly exclusiveGroupIssues?: readonly CompatibilityIssue[];
|
|
57
|
+
/** From `checkEnvArtifacts()`'s result. Only `"stale"`/`"missing"` findings become a `Finding` -- `"ok"` means nothing to report. */
|
|
58
|
+
readonly artifactCheckFindings?: readonly ArtifactCheckFinding[];
|
|
59
|
+
/** From `generateDocumentation()`'s result. */
|
|
60
|
+
readonly documentation?: DocumentationFindings;
|
|
61
|
+
/** From `generateUsageReport()`'s result. */
|
|
62
|
+
readonly abandonedContracts?: readonly AbandonedContractFinding[];
|
|
63
|
+
/** From `generateUsageReport()`'s result. */
|
|
64
|
+
readonly unresolvedConsumers?: readonly UnresolvedConsumerFinding[];
|
|
65
|
+
/** From `generateUsageReport()`'s result. */
|
|
66
|
+
readonly unconsumedOwnedVariables?: readonly UnconsumedOwnedVariableFinding[];
|
|
67
|
+
/** From `generateUsageReport()`'s result. */
|
|
68
|
+
readonly indeterminateOwnership?: readonly IndeterminateOwnershipFinding[];
|
|
69
|
+
/** From `computeManifestChanges()`'s result -- every `dynamicAccess` citation that's gone `"stale"` or `"missing"` since it was last acknowledged. See ADR 0037. */
|
|
70
|
+
readonly dynamicAccessCitationProblems?: readonly DynamicAccessCitationProblem[] | undefined;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Adapts every existing finding family into the Finding Model's unified
|
|
74
|
+
* shape -- an adapter over data that already exists, not a new source of
|
|
75
|
+
* truth. Order of the returned array mirrors the order sources are given
|
|
76
|
+
* above; a consumer wanting a specific order (by severity, by file, ...)
|
|
77
|
+
* sorts it themselves.
|
|
78
|
+
*/
|
|
79
|
+
export declare function buildFindingModel(input: BuildFindingModelInput): FindingModel;
|
|
80
|
+
//# sourceMappingURL=finding-model.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"finding-model.d.ts","sourceRoot":"","sources":["../../../src/build/finding-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAEpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAA;AACxE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAA;AAC9E,OAAO,KAAK,EACV,wBAAwB,EACxB,6BAA6B,EAC7B,8BAA8B,EAC9B,yBAAyB,EAC1B,MAAM,mBAAmB,CAAA;AAE1B;;;;;GAKG;AAEH,yKAAyK;AACzK,MAAM,MAAM,WAAW,GACnB,sBAAsB,GACtB,2BAA2B,GAC3B,gBAAgB,GAChB,kBAAkB,GAClB,uBAAuB,GACvB,uBAAuB,GACvB,iBAAiB,GACjB,SAAS,GACT,eAAe,GACf,6BAA6B,GAC7B,oBAAoB,GACpB,qBAAqB,GACrB,2BAA2B,GAC3B,yBAAyB,GACzB,iCAAiC,GACjC,+BAA+B,GAC/B,+BAA+B,CAAA;AAEnC,iNAAiN;AACjN,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,OAAO,GAAG,eAAe,GAAG,WAAW,CAAA;AAErF,oFAAoF;AACpF,MAAM,WAAW,OAAO;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;IAC/C,0JAA0J;IAC1J,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;CACrC;AAED,yIAAyI;AACzI,eAAO,MAAM,4BAA4B,IAAI,CAAA;AAE7C,oOAAoO;AACpO,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,4BAA4B,CAAA;IAC3D,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,6JAA6J;IAC7J,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC5D,oNAAoN;IACpN,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC7D,qIAAqI;IACrI,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;IAChE,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,qBAAqB,CAAA;IAC9C,6CAA6C;IAC7C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAA;IACjE,6CAA6C;IAC7C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACnE,6CAA6C;IAC7C,QAAQ,CAAC,wBAAwB,CAAC,EAAE,SAAS,8BAA8B,EAAE,CAAA;IAC7E,6CAA6C;IAC7C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAA;IAC1E,oKAAoK;IACpK,QAAQ,CAAC,6BAA6B,CAAC,EAAE,SAAS,4BAA4B,EAAE,GAAG,SAAS,CAAA;CAC7F;AA2CD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,YAAY,CAwN7E"}
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import type { ContractModelContract } from "./contract-model.js";
|
|
2
|
+
import type { CatalogContract, ExpiringEntry } from "./docs.js";
|
|
3
|
+
import type { EnvExampleOnExisting, EnvExampleResult } from "./env-example.js";
|
|
4
|
+
import type { DiscoveredContract, DiscoveredContractSummary, LinkResult } from "./link.js";
|
|
5
|
+
import type { LiveExpirationDates } from "./live-expirations.js";
|
|
6
|
+
import type { ParseWarning } from "./parse.js";
|
|
7
|
+
import type { BuildFileSystem } from "./types.js";
|
|
8
|
+
/** Options for {@link generateDocumentation}. */
|
|
9
|
+
export interface GenerateDocumentationOptions {
|
|
10
|
+
/** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
|
|
11
|
+
fs: BuildFileSystem;
|
|
12
|
+
/** Project root schema discovery is relative to. Defaults to `process.cwd()`. */
|
|
13
|
+
root?: string | undefined;
|
|
14
|
+
/** Output path for the Markdown docs artifact, relative to `root`. */
|
|
15
|
+
location: string;
|
|
16
|
+
/** Glob patterns for files to scan. Defaults to `defaultInclude()`. */
|
|
17
|
+
include?: string[] | undefined;
|
|
18
|
+
/** Glob patterns for files/directories to prune. Defaults to `defaultExclude()`. */
|
|
19
|
+
exclude?: string[] | undefined;
|
|
20
|
+
/** See `GenerateEnvManifestOptions.packages`; see ADR 0014. */
|
|
21
|
+
packages?: readonly string[] | undefined;
|
|
22
|
+
/** See `GenerateEnvManifestOptions.tsconfig`; see ADR 0023. */
|
|
23
|
+
tsconfig?: string | false | undefined;
|
|
24
|
+
/** How many days out counts as "expiring soon". Defaults to 30. */
|
|
25
|
+
expiringWithinDays?: number | undefined;
|
|
26
|
+
/**
|
|
27
|
+
* Also emit a `.env.example`-style file, relative to `root`. `onExisting`
|
|
28
|
+
* controls what happens when a file already exists there -- defaults to
|
|
29
|
+
* `"keep-sibling"` (never overwrites; see `EnvExampleOnExisting` and
|
|
30
|
+
* `EnvExampleResult`).
|
|
31
|
+
*/
|
|
32
|
+
envExample?: {
|
|
33
|
+
/** Output path for the `.env.example`-style file, relative to `root`. */
|
|
34
|
+
location: string;
|
|
35
|
+
/** What to do when a file already exists at `location`. Defaults to `"keep-sibling"`. */
|
|
36
|
+
onExisting?: EnvExampleOnExisting | undefined;
|
|
37
|
+
} | undefined;
|
|
38
|
+
/**
|
|
39
|
+
* Supplies expiration metadata from a live source as a post-discovery
|
|
40
|
+
* override, invoked exactly once with every discovered variable name after
|
|
41
|
+
* linking completes and before rendering. See `live-expirations.ts` and
|
|
42
|
+
* ADR 0012. Omitted: behavior is unchanged from a purely static `expiresAt`.
|
|
43
|
+
*/
|
|
44
|
+
liveExpirationDates?: LiveExpirationDates | undefined;
|
|
45
|
+
}
|
|
46
|
+
/** Everything {@link generateDocumentation} found that isn't fully documented or up to date -- never blocks generation; a team that wants to gate CI on this reads `Finding[]` (the "documentation" family) from the persisted evidence artifact and decides for itself. See ADR 0038. */
|
|
47
|
+
export interface DocumentationFindings {
|
|
48
|
+
/** Contracts with no linked `documentEnv()` call at all. */
|
|
49
|
+
readonly undocumentedContracts: readonly {
|
|
50
|
+
/** Absolute path of the file declaring the contract. */
|
|
51
|
+
readonly file: string;
|
|
52
|
+
/** The contract's exported binding name. */
|
|
53
|
+
readonly exportName: string;
|
|
54
|
+
}[];
|
|
55
|
+
/** Schema variables with no matching entry in their contract's linked documentation. */
|
|
56
|
+
readonly undocumentedVariables: readonly {
|
|
57
|
+
/** Absolute path of the file declaring the contract. */
|
|
58
|
+
readonly file: string;
|
|
59
|
+
/** The contract's exported binding name. */
|
|
60
|
+
readonly exportName: string;
|
|
61
|
+
/** The undocumented environment variable name. */
|
|
62
|
+
readonly key: string;
|
|
63
|
+
}[];
|
|
64
|
+
/** Documented variable entries with no matching schema variable (the schema key was removed or renamed). */
|
|
65
|
+
readonly staleDocEntries: readonly {
|
|
66
|
+
/** Absolute path of the file declaring the contract. */
|
|
67
|
+
readonly file: string;
|
|
68
|
+
/** The contract's exported binding name. */
|
|
69
|
+
readonly exportName: string;
|
|
70
|
+
/** The stale documented variable name. */
|
|
71
|
+
readonly key: string;
|
|
72
|
+
}[];
|
|
73
|
+
/** Variables whose `expiresAt` falls within the configured window. */
|
|
74
|
+
readonly expiringSoon: readonly ExpiringEntry[];
|
|
75
|
+
/** Contract- or variable-level `sensitivity` values outside {@link STANDARD_SENSITIVITY_LEVELS}. Advisory only -- the declared level is always honored verbatim; this exists purely so vocabulary drift across a repo stays visible. */
|
|
76
|
+
readonly nonstandardSensitivityLevels: readonly NonstandardSensitivityEntry[];
|
|
77
|
+
/** `documentEnv()` calls that couldn't be statically linked to a schema. */
|
|
78
|
+
readonly unresolvedLinks: readonly {
|
|
79
|
+
/** Absolute path of the file containing the unlinkable call. */
|
|
80
|
+
readonly file: string;
|
|
81
|
+
/** Human-readable explanation of why the link couldn't be resolved. */
|
|
82
|
+
readonly reason: string;
|
|
83
|
+
}[];
|
|
84
|
+
}
|
|
85
|
+
/** The result of a completed {@link generateDocumentation} run. */
|
|
86
|
+
export interface GenerateDocumentationResult {
|
|
87
|
+
/** Absolute path the Markdown docs artifact was written to. */
|
|
88
|
+
readonly docsPath: string;
|
|
89
|
+
/** Set only when `options.envExample` was passed. */
|
|
90
|
+
readonly envExample: EnvExampleResult | undefined;
|
|
91
|
+
/** Root-relative summary of every discovered contract, active or not. */
|
|
92
|
+
readonly contracts: readonly DiscoveredContractSummary[];
|
|
93
|
+
/** Same descriptive content as the generated Markdown Catalog, reshaped for
|
|
94
|
+
* programmatic consumers -- see `buildCatalog()` in `docs.ts`. */
|
|
95
|
+
readonly catalog: readonly CatalogContract[];
|
|
96
|
+
/** Parse-time warnings collected across every analyzed file (including allow-listed package resolution). */
|
|
97
|
+
readonly parseWarnings: readonly ParseWarning[];
|
|
98
|
+
/** Everything found that isn't fully documented or up to date. */
|
|
99
|
+
readonly documentation: DocumentationFindings;
|
|
100
|
+
}
|
|
101
|
+
/** Default value for {@link GenerateDocumentationOptions.expiringWithinDays}. */
|
|
102
|
+
export declare const DEFAULT_EXPIRING_WITHIN_DAYS = 30;
|
|
103
|
+
/**
|
|
104
|
+
* The sensitivity vocabulary env-cap's own docs, examples, and `.env.example`
|
|
105
|
+
* comments are written around. Purely advisory: `sensitivity` is an open
|
|
106
|
+
* `string` (see {@link runtime.VariableDocs.sensitivity}), any value is
|
|
107
|
+
* honored verbatim, and nothing here ever drops or rewrites a declared level.
|
|
108
|
+
* A level outside this set only produces a non-blocking
|
|
109
|
+
* `NONSTANDARD_SENSITIVITY_LEVEL` finding, so a team that deliberately runs
|
|
110
|
+
* its own vocabulary sees one advisory line rather than silent data loss --
|
|
111
|
+
* and a team that meant to write `"secret"` and typo'd `"secrets"` finds out.
|
|
112
|
+
*/
|
|
113
|
+
export declare const STANDARD_SENSITIVITY_LEVELS: ReadonlySet<string>;
|
|
114
|
+
/** One contract- or variable-level `sensitivity` declaring a level outside {@link STANDARD_SENSITIVITY_LEVELS}. */
|
|
115
|
+
export interface NonstandardSensitivityEntry {
|
|
116
|
+
/** Absolute path of the file declaring the contract. */
|
|
117
|
+
readonly file: string;
|
|
118
|
+
/** The contract's exported binding name. */
|
|
119
|
+
readonly exportName: string;
|
|
120
|
+
/** `undefined` for a contract-level `sensitivity`, set for a per-variable one. */
|
|
121
|
+
readonly key: string | undefined;
|
|
122
|
+
/** The declared level, exactly as written. */
|
|
123
|
+
readonly sensitivity: string;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Every contract- or variable-level `sensitivity` outside the standard set,
|
|
127
|
+
* in declaration order (contract first, then its own variables by key).
|
|
128
|
+
*
|
|
129
|
+
* @remarks
|
|
130
|
+
* A variable's *own* declared level only -- never the contract-inherited one
|
|
131
|
+
* `effectiveSensitivity()` would resolve to. Reporting the inherited value
|
|
132
|
+
* would fire this same finding once per variable on a contract that already
|
|
133
|
+
* produced its own contract-level entry, turning one real vocabulary
|
|
134
|
+
* question into N duplicates of it.
|
|
135
|
+
*/
|
|
136
|
+
export declare function findNonstandardSensitivityLevels(contracts: readonly DiscoveredContract[]): NonstandardSensitivityEntry[];
|
|
137
|
+
export interface DocumentationComputation {
|
|
138
|
+
readonly contractSummaries: readonly DiscoveredContractSummary[];
|
|
139
|
+
readonly catalog: readonly CatalogContract[];
|
|
140
|
+
readonly documentation: DocumentationFindings;
|
|
141
|
+
/** `ContractModel`'s own projection of the same contracts, built once here and reused by `writeDocumentation()` -- the shape `renderDocs()` itself takes (ADR 0038). */
|
|
142
|
+
readonly contractModelContracts: readonly ContractModelContract[];
|
|
143
|
+
}
|
|
144
|
+
/** Root-relative, POSIX-separated -- `RenderDocsOptions`'s own convention, matching `ContractModel`'s `file`. Exported so `check-artifacts.ts`'s drift check can convert the same `documentation.undocumentedContracts`/`undocumentedVariables` fields for its own `renderDocs()` call, identically. Delegates to `displayPath()` so this can never disagree with the `ContractModel` `file` values it's matched against by identity. */
|
|
145
|
+
export declare function relativizeRef<T extends {
|
|
146
|
+
file: string;
|
|
147
|
+
}>(root: string, ref: T): T;
|
|
148
|
+
/**
|
|
149
|
+
* Pure -- no I/O. Computes undocumented/stale/expiring findings against an
|
|
150
|
+
* already-discovered contract graph (active and inactive alike -- docs
|
|
151
|
+
* document everything, unlike the manifest). Never blocks -- see
|
|
152
|
+
* `DocumentationFindings`'s own doc comment. Shared by the standalone
|
|
153
|
+
* `generateDocumentation()` and `generate-env-artifacts.ts` (which also
|
|
154
|
+
* reuses this same call for Finding Model's documentation-family findings,
|
|
155
|
+
* ADR 0038 -- one computation, not two).
|
|
156
|
+
*/
|
|
157
|
+
export declare function computeDocumentation(root: string, linkResult: LinkResult, expiringWithinDays: number, generatedAt: Date): DocumentationComputation;
|
|
158
|
+
/** Writes the docs artifact and, if requested, the `.env.example` file. Callers must have already confirmed both output paths are safe and nothing is blocking. */
|
|
159
|
+
export declare function writeDocumentation(docsPath: string, envExamplePath: string | undefined, root: string, contracts: readonly DiscoveredContract[], contractModelContracts: readonly ContractModelContract[], documentation: DocumentationFindings, expiringWithinDays: number, generatedAt: Date, fs: BuildFileSystem, envExampleOnExisting?: EnvExampleOnExisting): Promise<{
|
|
160
|
+
envExample: EnvExampleResult | undefined;
|
|
161
|
+
}>;
|
|
162
|
+
/**
|
|
163
|
+
* Build-time only. Discovers and links `env.schema.ts` files (same static
|
|
164
|
+
* analysis as {@link generateEnvManifest}) and writes the rich Markdown "Catalog" --
|
|
165
|
+
* every variable, its description, default, processor/validator flags,
|
|
166
|
+
* owner, and expiry -- the single onboarding reference application
|
|
167
|
+
* developers use to see what configuration a feature needs and how to set
|
|
168
|
+
* it up. Optionally also writes a reconciling `.env.example`.
|
|
169
|
+
*
|
|
170
|
+
* @remarks
|
|
171
|
+
* Documents every discovered contract, active or not, unlike {@link generateEnvManifest}.
|
|
172
|
+
*
|
|
173
|
+
* @throws {EnvDocumentationGenerationError} If `location`/`envExample.location` escape `root`.
|
|
174
|
+
*/
|
|
175
|
+
export declare function generateDocumentation(options: GenerateDocumentationOptions): Promise<GenerateDocumentationResult>;
|
|
176
|
+
//# sourceMappingURL=generate-documentation.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"generate-documentation.d.ts","sourceRoot":"","sources":["../../../src/build/generate-documentation.ts"],"names":[],"mappings":"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"}
|