@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
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import type { EvidenceModel } from "../build/evidence-model.js";
|
|
2
2
|
/**
|
|
3
3
|
* A pure function from the full Evidence Model to one field of a
|
|
4
|
-
* projection's output shape. Must not mutate `evidence`
|
|
4
|
+
* projection's output shape. Must not mutate `evidence` (the membrane
|
|
5
5
|
* `defineEvidenceProjection()` wraps it in enforces that at runtime, see
|
|
6
|
-
* `createTrackingProxy()` below
|
|
6
|
+
* `createTrackingProxy()` below) and must not perform I/O; env-cap can
|
|
7
7
|
* enforce the read-only half of purity but not the "no side effects" half.
|
|
8
8
|
*/
|
|
9
9
|
export type EvidenceProjector<T> = (evidence: EvidenceModel) => T;
|
|
@@ -19,34 +19,33 @@ export interface EvidenceProjectionResult<T extends Record<string, unknown>> {
|
|
|
19
19
|
/**
|
|
20
20
|
* The function `defineEvidenceProjection()` returns. Callable directly for
|
|
21
21
|
* the common case (`projection(evidence)` -> `T`); `.project()` returns the
|
|
22
|
-
* same value alongside automatic provenance
|
|
22
|
+
* same value alongside automatic provenance: see ADR 0032.
|
|
23
23
|
*/
|
|
24
24
|
export interface EvidenceProjection<T extends Record<string, unknown>> {
|
|
25
25
|
(evidence: EvidenceModel): T;
|
|
26
|
-
/** Same computation as calling the projection directly, plus which `EvidenceModel` field paths fed each output key
|
|
26
|
+
/** Same computation as calling the projection directly, plus which `EvidenceModel` field paths fed each output key: see {@link EvidenceProjectionResult}. */
|
|
27
27
|
project(evidence: EvidenceModel): EvidenceProjectionResult<T>;
|
|
28
28
|
}
|
|
29
29
|
/**
|
|
30
30
|
* Declares a projection: a named, pure transform from the immutable
|
|
31
31
|
* `EvidenceModel` to any consumer-defined output shape, built entirely from
|
|
32
|
-
* `schema`'s independent per-field projector functions
|
|
32
|
+
* `schema`'s independent per-field projector functions; see ADR 0031/0032.
|
|
33
33
|
*
|
|
34
|
-
* env-cap
|
|
34
|
+
* The reference projections env-cap ships (`.env.example`, Environment
|
|
35
35
|
* Configuration Reference, Configuration Ownership, etc.) are built through
|
|
36
|
-
* this exact function, with no privileged internal path
|
|
36
|
+
* this exact function, with no privileged internal path. A consumer's own
|
|
37
37
|
* projection is a first-class citizen, not a lesser one.
|
|
38
38
|
*/
|
|
39
39
|
export declare function defineEvidenceProjection<T extends Record<string, unknown>>(schema: EvidenceProjectionSchema<T>): EvidenceProjection<T>;
|
|
40
40
|
/**
|
|
41
|
-
* The error every membrane write-trap below throws.
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
*
|
|
49
|
-
* "the engine's own invariant-violation message").
|
|
41
|
+
* The error every membrane write-trap below throws.
|
|
42
|
+
*
|
|
43
|
+
* @remarks
|
|
44
|
+
* It is a function, not a module-level `const`, because Stryker's `perTest`
|
|
45
|
+
* coverage cannot attribute a module-load string to the test that covers it.
|
|
46
|
+
* It is exported so a test can pin the exact message. A trap's
|
|
47
|
+
* `.toThrow(TypeError)` cannot: a mutated trap body still throws the engine's
|
|
48
|
+
* own Proxy invariant `TypeError`.
|
|
50
49
|
*/
|
|
51
50
|
export declare function readOnlyMembraneError(): TypeError;
|
|
52
51
|
//# sourceMappingURL=define-projection.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"define-projection.d.ts","sourceRoot":"","sources":["../../../src/evidence/define-projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAE/D;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,KAAK,CAAC,CAAA;AAEjE,6FAA6F;AAC7F,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACxE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACjD,CAAA;AAED,mHAAmH;AACnH,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;IACjB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;CAC/D;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACnE,CAAC,QAAQ,EAAE,aAAa,GAAG,CAAC,CAAA;IAC5B
|
|
1
|
+
{"version":3,"file":"define-projection.d.ts","sourceRoot":"","sources":["../../../src/evidence/define-projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAE/D;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,KAAK,CAAC,CAAA;AAEjE,6FAA6F;AAC7F,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACxE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACjD,CAAA;AAED,mHAAmH;AACnH,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;IACjB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;CAC/D;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACnE,CAAC,QAAQ,EAAE,aAAa,GAAG,CAAC,CAAA;IAC5B,6JAA6J;IAC7J,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,wBAAwB,CAAC,CAAC,CAAC,CAAA;CAC9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxE,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAClC,kBAAkB,CAAC,CAAC,CAAC,CAkBvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,IAAI,SAAS,CAIjD"}
|
|
@@ -1,21 +1,17 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Build your own views of the evidence file (`@maverickcer/env-cap/evidence`).
|
|
3
3
|
*
|
|
4
|
-
* `defineEvidenceProjection()`
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
* consumer-defined output shape, with automatic read-only enforcement and
|
|
9
|
-
* field-level provenance. See ADR 0031 (why a 5th entry point) and ADR 0032
|
|
10
|
-
* (the Proxy-based mechanism itself).
|
|
4
|
+
* `defineEvidenceProjection()` declares a pure transform from an `EvidenceModel` to a shape you define:
|
|
5
|
+
* a dashboard row, an inventory table or a CI comment. The projectors read the model
|
|
6
|
+
* through a read-only membrane, and `.project()` also returns which model fields fed each output field
|
|
7
|
+
* (ADR 0032). ADR 0031 explains why this is its own entry point.
|
|
11
8
|
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
* JSON-deserialized `EvidenceModel` with zero Node dependency.
|
|
9
|
+
* `generateEvidenceModel()` in `@maverickcer/env-cap/build` assembles the model at build time. This
|
|
10
|
+
* module imports no Node module and no TypeScript compiler, and takes the `EvidenceModel` shape as a
|
|
11
|
+
* type only. So a projection can run over a JSON-parsed evidence file outside Node; CI runs this
|
|
12
|
+
* entry under Bun, Deno and a Web-globals bundle.
|
|
13
|
+
*
|
|
14
|
+
* @packageDocumentation
|
|
19
15
|
*/
|
|
20
16
|
export type { EvidenceModel, EvidenceProvenance } from "../build/evidence-model.js";
|
|
21
17
|
export { defineEvidenceProjection } from "./define-projection.js";
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/evidence/index.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/evidence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACnF,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AACjE,YAAY,EACV,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,wBAAwB,CAAA"}
|
|
@@ -1,19 +1,16 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Optional
|
|
3
|
-
*
|
|
4
|
-
* no knowledge of this module and work identically without it.
|
|
2
|
+
* Optional processors and validators for common cases (`@maverickcer/env-cap/helpers`), such as
|
|
3
|
+
* `processors.toNumber()` and `validators.range(1, 65535)`.
|
|
5
4
|
*
|
|
6
|
-
*
|
|
5
|
+
* A contract works the same without them: `createEnv` and `validateEnv` never import this module. Any
|
|
6
|
+
* function with the `Processor<T>` or `Validator<T>` shape plugs in the same way.
|
|
7
7
|
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
* ship all of `validators`' code. A plain object literal of already-imported
|
|
15
|
-
* bindings has no such call in the way, so `import { processors } from
|
|
16
|
-
* "@maverickcer/env-cap/helpers"` alone drops `validators` entirely.
|
|
8
|
+
* The two objects are plain literals of named imports, not `export * as processors`. A bundler lowers
|
|
9
|
+
* `export * as` into a namespace helper call it cannot prove free of side effects. That call blocks
|
|
10
|
+
* tree-shaking in a consumer's own bundler, so importing `processors` alone would still ship
|
|
11
|
+
* `validators`. With plain literals, importing `processors` alone drops `validators` entirely.
|
|
12
|
+
*
|
|
13
|
+
* @packageDocumentation
|
|
17
14
|
*/
|
|
18
15
|
import { base64, parseJSON, split, toArray, toBigInt, toBoolean, toDate, toInteger, toLowerCase, toNumber, toRegExp, toString, toURL, toUpperCase, trim } from "./processors.js";
|
|
19
16
|
import { after, all, any, before, custom, email, endsWith, finite, future, includes, integer as integerValidator, length, matches, max, maxItems, maxLength, min, minItems, minLength, negative, not, oneOf, optional, past, positive, range, refine, required, safeInteger, unique, url as urlValidator, uuid, uuidVersion } from "./validators.js";
|
|
@@ -22,7 +19,7 @@ import { after, all, any, before, custom, email, endsWith, finite, future, inclu
|
|
|
22
19
|
* patterns (e.g. `processors.toNumber()`).
|
|
23
20
|
*
|
|
24
21
|
* @remarks
|
|
25
|
-
* Naming matches `data-cap`'s `helpers.processors
|
|
22
|
+
* Naming matches `data-cap`'s `helpers.processors`: but these
|
|
26
23
|
* throw with a formatted `Error` message on invalid input, where data-cap's
|
|
27
24
|
* silently return `undefined`. Do not assume the same failure mode when
|
|
28
25
|
* moving between packages.
|
|
@@ -69,13 +66,13 @@ export declare const validators: {
|
|
|
69
66
|
any: typeof any;
|
|
70
67
|
/** Passes when the date value is strictly before `date`. */
|
|
71
68
|
before: typeof before;
|
|
72
|
-
/** Identity wrapper for a hand-written `Validator<T
|
|
69
|
+
/** Identity wrapper for a hand-written `Validator<T>`: no behavior change, just a fluent entry point alongside the other helpers. */
|
|
73
70
|
custom: typeof custom;
|
|
74
71
|
/** Passes for a plausibly-shaped email address (`local@domain`). */
|
|
75
72
|
email: typeof email;
|
|
76
73
|
/** Passes when the string ends with `suffix`. */
|
|
77
74
|
endsWith: typeof endsWith;
|
|
78
|
-
/** Alias for `oneOf
|
|
75
|
+
/** Alias for `oneOf`: passes when the value is one of the `allowed` values. */
|
|
79
76
|
enum: typeof oneOf;
|
|
80
77
|
/** Passes when the number is finite (rejects `Infinity`/`-Infinity`/`NaN`). */
|
|
81
78
|
finite: typeof finite;
|
|
@@ -117,7 +114,7 @@ export declare const validators: {
|
|
|
117
114
|
range: typeof range;
|
|
118
115
|
/** Runs the wrapped validator but replaces its failure message with `message`. */
|
|
119
116
|
refine: typeof refine;
|
|
120
|
-
/** Alias for `matches
|
|
117
|
+
/** Alias for `matches`: passes when the string matches `pattern`. */
|
|
121
118
|
regex: typeof matches;
|
|
122
119
|
/** Passes when the value is defined and, unless `allowEmptyString` is set, non-empty. */
|
|
123
120
|
required: typeof required;
|
|
@@ -129,7 +126,7 @@ export declare const validators: {
|
|
|
129
126
|
url: typeof urlValidator;
|
|
130
127
|
/** Passes when the string is a valid UUID of one of the given `versions` (default: any of 1-8). */
|
|
131
128
|
uuid: typeof uuid;
|
|
132
|
-
/** Shorthand for `uuid([version])
|
|
129
|
+
/** Shorthand for `uuid([version])`: passes only for that exact UUID version. */
|
|
133
130
|
uuidVersion: typeof uuidVersion;
|
|
134
131
|
};
|
|
135
132
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/helpers/index.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,EACP,QAAQ,EACR,SAAS,EACT,MAAM,EACN,SAAS,EACT,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,WAAW,EACX,IAAI,EACL,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,EACL,GAAG,EACH,GAAG,EACH,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,OAAO,IAAI,gBAAgB,EAC3B,MAAM,EACN,OAAO,EACP,GAAG,EACH,QAAQ,EACR,SAAS,EACT,GAAG,EACH,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,GAAG,EACH,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,MAAM,EACN,QAAQ,EACR,WAAW,EACX,MAAM,EACN,GAAG,IAAI,YAAY,EACnB,IAAI,EACJ,WAAW,EACZ,MAAM,iBAAiB,CAAA;AAExB;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;IACrB,+CAA+C;;IAE/C,wEAAwE;;IAExE,qGAAqG;;IAErG,qHAAqH;;IAErH,qCAAqC;;IAErC,4GAA4G;;IAE5G,oCAAoC;;IAEpC,oEAAoE;;IAEpE,mEAAmE;;IAEnE,iHAAiH;;IAEjH,wCAAwC;;IAExC,oEAAoE;;IAEpE,0EAA0E;;IAE1E,mEAAmE;;IAEnE,0FAA0F;;CAE3F,CAAA;AACD,gIAAgI;AAChI,eAAO,MAAM,UAAU;IACrB,2DAA2D;;IAE3D,0FAA0F;;IAE1F,yDAAyD;;IAEzD,4DAA4D;;IAE5D,qIAAqI;;IAErI,oEAAoE;;IAEpE,iDAAiD;;IAEjD,+EAA+E;;IAE/E,+EAA+E;;IAE/E,+DAA+D;;IAE/D,6DAA6D;;IAE7D,4CAA4C;;IAE5C,6DAA6D;;IAE7D,8FAA8F;;IAE9F,iEAAiE;;IAEjE,yDAAyD;;IAEzD,2DAA2D;;IAE3D,oEAAoE;;IAEpE,0DAA0D;;IAE1D,4DAA4D;;IAE5D,mDAAmD;;IAEnD,oFAAoF;;IAEpF,4DAA4D;;IAE5D,yFAAyF;;IAEzF,gEAAgE;;IAEhE,mDAAmD;;IAEnD,uEAAuE;;IAEvE,kFAAkF;;IAElF,qEAAqE;;IAErE,yFAAyF;;IAEzF,yEAAyE;;IAEzE,qDAAqD;;IAErD,sDAAsD;;IAEtD,mGAAmG;;IAEnG,gFAAgF;;CAEjF,CAAA"}
|
|
@@ -7,7 +7,7 @@ export declare function all<T>(...validators: Validator<T>[]): Validator<T>;
|
|
|
7
7
|
export declare function any<T>(...validators: Validator<T>[]): Validator<T>;
|
|
8
8
|
/** Passes when the date value is strictly before `date`. */
|
|
9
9
|
export declare function before(date: Date): Validator<Date>;
|
|
10
|
-
/** Identity wrapper for a hand-written `Validator<T
|
|
10
|
+
/** Identity wrapper for a hand-written `Validator<T>`: no behavior change, just a fluent entry point alongside the other helpers. */
|
|
11
11
|
export declare function custom<T>(validator: Validator<T>): Validator<T>;
|
|
12
12
|
/** Passes for a plausibly-shaped email address (`local@domain`). */
|
|
13
13
|
export declare function email(): Validator<string>;
|
|
@@ -63,6 +63,6 @@ export declare function unique<T>(): Validator<T[]>;
|
|
|
63
63
|
export declare function url(): Validator<string>;
|
|
64
64
|
/** Passes when the string is a valid UUID of one of the given `versions` (default: any of 1-8). */
|
|
65
65
|
export declare function uuid(versions?: readonly number[]): Validator<string>;
|
|
66
|
-
/** Shorthand for `uuid([version])
|
|
66
|
+
/** Shorthand for `uuid([version])`: passes only for that exact UUID version. */
|
|
67
67
|
export declare function uuidVersion(number: number): Validator<string>;
|
|
68
68
|
//# sourceMappingURL=validators.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/helpers/validators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD,2DAA2D;AAC3D,wBAAgB,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAEjD;AAED,0FAA0F;AAC1F,wBAAgB,GAAG,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CASlE;AAED,yDAAyD;AACzD,wBAAgB,GAAG,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAQlE;AAED,4DAA4D;AAC5D,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAElD;AAED,
|
|
1
|
+
{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/helpers/validators.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,2 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Node file system adapter for the build entry (`@maverickcer/env-cap/node`).
|
|
3
|
+
*
|
|
4
|
+
* `@maverickcer/env-cap/build` never imports `node:fs` (ADR 0040), so every generator takes the file
|
|
5
|
+
* system as a required `fs` option. A Node build script passes `nodeBuildFileSystem`:
|
|
6
|
+
*
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { generateEnvArtifacts } from "@maverickcer/env-cap/build"
|
|
9
|
+
* import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"
|
|
10
|
+
*
|
|
11
|
+
* await generateEnvArtifacts({ fs: nodeBuildFileSystem, root, manifest: { ... } })
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* Like `bin` and `./eslint-plugin`, this entry runs only in Node, and it is the one place the build
|
|
15
|
+
* path loads `node:fs/promises`. In another runtime, implement the `BuildFileSystem` type that
|
|
16
|
+
* `./build` exports instead.
|
|
17
|
+
*
|
|
18
|
+
* @packageDocumentation
|
|
19
|
+
*/
|
|
1
20
|
export { nodeBuildFileSystem } from "../cli/filesystem.js";
|
|
2
21
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/node/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA"}
|
|
@@ -6,12 +6,12 @@ import type { CreateEnvOptions, EnvContract, EnvSchema } from "./types.js";
|
|
|
6
6
|
* @remarks
|
|
7
7
|
* `createEnv` is runtime-only: `processor`/`validator`/`default` are the
|
|
8
8
|
* whole vocabulary, because they're the only fields {@link validateEnv} actually
|
|
9
|
-
* reads. Documentation
|
|
10
|
-
* everything else that only exists to generate docs
|
|
9
|
+
* reads. Documentation (description, ownership, lifecycle, category, and
|
|
10
|
+
* everything else that only exists to generate docs) lives in a separate
|
|
11
11
|
* {@link documentEnv} call (see `document.ts`), which is entirely optional and
|
|
12
12
|
* never required for this to work.
|
|
13
13
|
*
|
|
14
|
-
* @returns An {@link EnvContract} exposing one read-only getter per key
|
|
14
|
+
* @returns An {@link EnvContract} exposing one read-only getter per key: there is no
|
|
15
15
|
* global env object, only per-feature contracts like `paymentsEnv.STRIPE_KEY`. Accessing a
|
|
16
16
|
* key throws until {@link validateEnv} has run successfully for the runtime this contract
|
|
17
17
|
* was passed to.
|
|
@@ -1,35 +1,29 @@
|
|
|
1
1
|
import type { EnvSchema } from "./types.js";
|
|
2
2
|
/**
|
|
3
|
-
* Developer-supplied evidence assertions for one variable
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
* `owner`/..., specifically so that different epistemic status is visible in
|
|
9
|
-
* the shape itself and not only in a doc comment. See ADR 0037.
|
|
3
|
+
* Developer-supplied evidence assertions for one variable. They differ in kind from every field on
|
|
4
|
+
* {@link VariableDocs}, which are declared and never verified. `dynamicAccess` is re-checked against
|
|
5
|
+
* reality on every run (fresh / stale / missing). It lives apart, in `VariableDocs.evidence`, not
|
|
6
|
+
* beside `description`, `owner` and the rest. So the shape itself shows the different status, not
|
|
7
|
+
* only a doc comment. See ADR 0037.
|
|
10
8
|
*/
|
|
11
9
|
export interface VariableEvidenceDocs {
|
|
12
10
|
/**
|
|
13
|
-
* Citation(s) of where this variable is
|
|
14
|
-
*
|
|
15
|
-
* Docker entrypoint, a sibling service). Each entry is a
|
|
11
|
+
* Citation(s) of where this variable is read dynamically, somewhere env-cap's static AST scan
|
|
12
|
+
* can't see (a shell script, a Docker entrypoint, a sibling service). Each entry is a
|
|
16
13
|
* `"<relative-path>:<line>:<column>"` citation.
|
|
17
14
|
*
|
|
18
15
|
* @remarks
|
|
19
|
-
* A developer's re-acknowledgment that access happens, never a claim
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
* visibly changed since it was last acknowledged, is flagged rather than
|
|
24
|
-
* trusted forever.
|
|
16
|
+
* A developer's re-acknowledgment that access happens, never a claim that env-cap observed
|
|
17
|
+
* anything. It is tracked as its own fact and never folded into the AST-derived
|
|
18
|
+
* `VariableAccessStatus`. It is re-verified every run. A citation whose file is gone, or whose
|
|
19
|
+
* content has visibly changed since it was acknowledged, is flagged rather than trusted forever.
|
|
25
20
|
*/
|
|
26
21
|
dynamicAccess?: readonly string[];
|
|
27
22
|
}
|
|
28
23
|
/**
|
|
29
|
-
* Per-variable documentation. Every field is optional and unconstrained on
|
|
30
|
-
*
|
|
31
|
-
*
|
|
32
|
-
* know about yet without it being rejected.
|
|
24
|
+
* Per-variable documentation. Every field is optional and unconstrained on purpose. With no
|
|
25
|
+
* required shape, documenting a variable never fights the type checker. A field the generator
|
|
26
|
+
* doesn't know yet is accepted, not rejected.
|
|
33
27
|
*/
|
|
34
28
|
export interface VariableDocs {
|
|
35
29
|
/** Human-readable explanation of what this variable is and what it controls. */
|
|
@@ -41,67 +35,65 @@ export interface VariableDocs {
|
|
|
41
35
|
* key.
|
|
42
36
|
*
|
|
43
37
|
* @remarks
|
|
44
|
-
* Deliberately an open `string`, not a closed union
|
|
45
|
-
*
|
|
38
|
+
* Deliberately an open `string`, not a closed union. An org's sensitivity vocabulary is its own,
|
|
39
|
+
* and a level env-cap doesn't recognize is always honored, never dropped. The generator
|
|
46
40
|
* still reports a `NONSTANDARD_SENSITIVITY_LEVEL` finding (severity `info`, never blocking) for
|
|
47
41
|
* anything outside `secret`/`credential`/`pii`/`config`, so vocabulary drift stays visible
|
|
48
42
|
* without being enforced.
|
|
49
43
|
*/
|
|
50
44
|
sensitivity?: string;
|
|
51
|
-
/** ISO date string (e.g. "2026-06-01")
|
|
45
|
+
/** ISO date string (e.g. "2026-06-01"): when this variable's current value stops being valid (a key rotation deadline, a sunset date, etc.). */
|
|
52
46
|
expiresAt?: string;
|
|
53
47
|
/** How to get a new value before/when it expires (e.g. "Rotate in the Stripe dashboard, then redeploy."). */
|
|
54
48
|
refreshInstructions?: string;
|
|
55
49
|
/**
|
|
56
50
|
* The kind of authenticator/secret this variable holds (e.g. "api-key", "oauth-client-secret",
|
|
57
|
-
* "database-password", "tls-certificate")
|
|
58
|
-
*
|
|
59
|
-
*
|
|
51
|
+
* "database-password", "tls-certificate"). It feeds the "authenticator type" column of the NIST
|
|
52
|
+
* SP 800-53 IA-5 rotation-status report. IA-5 requires an organization-defined rotation period
|
|
53
|
+
* "by authenticator type," so a generator groups and labels by this field.
|
|
60
54
|
*
|
|
61
55
|
* @remarks
|
|
62
|
-
* Deliberately an open `string`, not a closed union
|
|
63
|
-
*
|
|
64
|
-
* names a fixed set of types either.
|
|
56
|
+
* Deliberately an open `string`, not a closed union, like {@link sensitivity}. An org's
|
|
57
|
+
* authenticator taxonomy is its own, and IA-5 itself names no fixed set of types.
|
|
65
58
|
*/
|
|
66
59
|
authenticatorType?: string;
|
|
67
60
|
/**
|
|
68
61
|
* How often this variable's value must be rotated, in organization-defined terms (e.g. "90
|
|
69
|
-
* days", "P90D", "6 months")
|
|
62
|
+
* days", "P90D", "6 months"). This is IA-5's "organization-defined time period" per authenticator
|
|
70
63
|
* type (the time-based half of IA-5's two-trigger rotation model). Paired with
|
|
71
|
-
* {@link lastRotatedAt}
|
|
72
|
-
*
|
|
73
|
-
* `computeRotationStatus()`
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
64
|
+
* {@link lastRotatedAt}, it lets a generator compute whether rotation is current. Without it, a
|
|
65
|
+
* generator could only record that a period was declared. `lifecycle-model.ts`'s
|
|
66
|
+
* `computeRotationStatus()` shows how the two combine with {@link expiresAt}. The result is a
|
|
67
|
+
* policy-window judgement over declared metadata ("within the declared period"). It never states
|
|
68
|
+
* that a rotation happened or that a control is met. env-cap reads declarations; it does not
|
|
69
|
+
* check them against the secret store.
|
|
77
70
|
*/
|
|
78
71
|
rotationPeriod?: string;
|
|
79
72
|
/**
|
|
80
|
-
* ISO date string
|
|
73
|
+
* ISO date string: the last time this variable's value was actually rotated. Paired with
|
|
81
74
|
* {@link rotationPeriod} to compute whether rotation is within the declared period. Independent of {@link expiresAt}, which
|
|
82
|
-
* states when the *current* value stops being valid, not when it was last changed
|
|
83
|
-
* be freshly rotated and still have a near-term `expiresAt` (a short-lived token)
|
|
84
|
-
* for rotation while its `expiresAt` (if any) is still comfortably in the future.
|
|
75
|
+
* states when the *current* value stops being valid, not when it was last changed. A value can
|
|
76
|
+
* be freshly rotated and still have a near-term `expiresAt` (a short-lived token). It can also be
|
|
77
|
+
* long overdue for rotation while its `expiresAt` (if any) is still comfortably in the future.
|
|
85
78
|
*/
|
|
86
79
|
lastRotatedAt?: string;
|
|
87
80
|
/**
|
|
88
81
|
* IA-5's event-based rotation triggers that apply to this variable (e.g. "suspected compromise",
|
|
89
|
-
* "personnel change", "system update")
|
|
90
|
-
* model.
|
|
91
|
-
*
|
|
92
|
-
*
|
|
93
|
-
*
|
|
94
|
-
*
|
|
95
|
-
* event-based trigger's existence visible in generated output.
|
|
82
|
+
* "personnel change", "system update"): the event-based half of IA-5's two-trigger rotation
|
|
83
|
+
* model. It sits beside the free-text {@link refreshInstructions} and does not replace it. This
|
|
84
|
+
* is a list a generator can render as its own column; `refreshInstructions` stays prose ("how to
|
|
85
|
+
* actually rotate it"). It is presence-only: env-cap cannot observe whether a listed event
|
|
86
|
+
* occurred. So declaring it never changes a computed rotation status by itself (see
|
|
87
|
+
* `lifecycle-model.ts`). It only makes the event-based trigger visible in generated output.
|
|
96
88
|
*/
|
|
97
89
|
rotationTriggerEvents?: readonly string[];
|
|
98
90
|
/**
|
|
99
|
-
* Explicit, actionable instructions for obtaining this variable's value the *first* time
|
|
100
|
-
*
|
|
101
|
-
*
|
|
102
|
-
* API keys, scoped to read/write Charges.").
|
|
103
|
-
*
|
|
104
|
-
*
|
|
91
|
+
* Explicit, actionable instructions for obtaining this variable's value the *first* time.
|
|
92
|
+
* `refreshInstructions` is "how to rotate it once you already have one"; this is "how to get
|
|
93
|
+
* one at all" (e.g. "Create a restricted API key in the Stripe dashboard under Developers ->
|
|
94
|
+
* API keys, scoped to read/write Charges."). It is a named field so it renders as its own
|
|
95
|
+
* labeled line in generated docs. A `metadata.setup`-style convention would get no dedicated
|
|
96
|
+
* rendering or type checking.
|
|
105
97
|
*/
|
|
106
98
|
setupInstructions?: string;
|
|
107
99
|
/** Documentation-level assertion that this variable must be set. Independent of how (or whether) a validator actually enforces it. */
|
|
@@ -110,57 +102,56 @@ export interface VariableDocs {
|
|
|
110
102
|
deprecated?: boolean;
|
|
111
103
|
/** Why this variable is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
|
|
112
104
|
deprecatedReason?: string;
|
|
113
|
-
/** ISO date string
|
|
105
|
+
/** ISO date string: by when a deprecated variable must be removed. Only meaningful alongside `deprecated: true`. */
|
|
114
106
|
removeBy?: string;
|
|
115
107
|
/** The previous environment variable name this one replaces, if this declaration is the result of a rename. Lets the Change Model correlate a remove+add pair into a single rename entry instead of two unrelated changes. */
|
|
116
108
|
renamedFrom?: string;
|
|
117
|
-
/** Why this variable's value is collected/used
|
|
109
|
+
/** Why this variable's value is collected/used: a framework-agnostic fact (pairs with `legalBasis`; a specific citation like a GDPR article belongs in `metadata` instead). Overrides the contract's own `purpose` for this key. */
|
|
118
110
|
purpose?: string;
|
|
119
|
-
/** The legal basis this variable's collection/use relies on
|
|
111
|
+
/** The legal basis this variable's collection/use relies on: framework-agnostic (e.g. "user consent," "contractual necessity"), never a specific statute name. Overrides the contract's own `legalBasis` for this key. */
|
|
120
112
|
legalBasis?: string;
|
|
121
|
-
/** Descriptive retention policy (e.g. "delete after 90 days"). A policy statement, not a computed value
|
|
113
|
+
/** Descriptive retention policy (e.g. "delete after 90 days"). A policy statement, not a computed value: unlike `expiresAt`, nothing parses or evaluates this. Overrides the contract's own `retention` for this key. */
|
|
122
114
|
retention?: string;
|
|
123
115
|
/** Where this variable's value is/must be stored (a region, or a permitted set of regions). Overrides the contract's own `dataResidency` for this key. */
|
|
124
116
|
dataResidency?: string | string[];
|
|
125
117
|
/** Documentation-level assertion that this variable's handling must be auditable. Overrides the contract's own `auditRequired` for this key. */
|
|
126
118
|
auditRequired?: boolean;
|
|
127
119
|
/**
|
|
128
|
-
* Developer-supplied evidence assertions for this variable
|
|
120
|
+
* Developer-supplied evidence assertions for this variable: verified over
|
|
129
121
|
* time, unlike every other field above, which is declared and never
|
|
130
122
|
* verified. Kept structurally separate for exactly that reason; see
|
|
131
123
|
* {@link VariableEvidenceDocs}.
|
|
132
124
|
*/
|
|
133
125
|
evidence?: VariableEvidenceDocs;
|
|
134
126
|
/**
|
|
135
|
-
* Structured, unsupported-key documentation
|
|
136
|
-
* doesn't warrant its own named field. A
|
|
137
|
-
*
|
|
127
|
+
* Structured, unsupported-key documentation: any primitive or object value, for anything that
|
|
128
|
+
* doesn't warrant its own named field. A key that has a named field above belongs in that field,
|
|
129
|
+
* not here.
|
|
138
130
|
*/
|
|
139
131
|
metadata?: Record<string, unknown>;
|
|
140
132
|
}
|
|
141
133
|
/**
|
|
142
|
-
* Contract-level documentation
|
|
143
|
-
* only the generator ever read.
|
|
134
|
+
* Contract-level documentation. Only the generator reads these fields; validation never does.
|
|
144
135
|
*
|
|
145
136
|
* @remarks
|
|
146
|
-
* Generic over `S`, the exact schema type {@link documentEnv} infers from its `schema` argument
|
|
147
|
-
*
|
|
148
|
-
* compile error, not a silent no-op
|
|
149
|
-
*
|
|
150
|
-
*
|
|
137
|
+
* Generic over `S`, the exact schema type {@link documentEnv} infers from its `schema` argument.
|
|
138
|
+
* That makes `variables` below a closed, checked map, not an open `Record<string, VariableDocs>`
|
|
139
|
+
* any string would satisfy. A typo'd or renamed key is a compile error, not a silent no-op. `S`
|
|
140
|
+
* defaults to the widest possible schema. So this type is still nameable on its own (e.g. in a
|
|
141
|
+
* helper function's parameter type) without narrowing to one specific contract.
|
|
151
142
|
*/
|
|
152
143
|
export interface ContractDocs<S extends EnvSchema = EnvSchema> {
|
|
153
144
|
/** Overrides the auto-generated label used in generated docs. Purely cosmetic. Wins over `createEnv()`'s own `name` option, which in turn wins over the exported binding name. */
|
|
154
145
|
name?: string;
|
|
155
146
|
/** Groups this contract under a heading in the generated docs' feature catalog. */
|
|
156
147
|
category?: string;
|
|
157
|
-
/** The generator throws if two *active* contracts declare the same `exclusiveGroup
|
|
148
|
+
/** The generator throws if two *active* contracts declare the same `exclusiveGroup`: use it to mark interchangeable features (e.g. two database backends) as mutually exclusive. */
|
|
158
149
|
exclusiveGroup?: string;
|
|
159
|
-
/** When `false`, this contract is excluded from the generated manifest, docs' required section, and exclusiveGroup checks
|
|
150
|
+
/** When `false`, this contract is excluded from the generated manifest, docs' required section, and exclusiveGroup checks: it still appears, marked disabled, in the feature catalog. Defaults to `true`. */
|
|
160
151
|
active?: boolean;
|
|
161
152
|
/** Default owner for every variable in this contract that doesn't set its own `owner`. */
|
|
162
153
|
owner?: string;
|
|
163
|
-
/** Default sensitivity for every variable in this contract that doesn't set its own `sensitivity
|
|
154
|
+
/** Default sensitivity for every variable in this contract that doesn't set its own `sensitivity`: see {@link VariableDocs.sensitivity} for why this is an open `string`. */
|
|
164
155
|
sensitivity?: string;
|
|
165
156
|
/** Whole-contract/feature sunset date, ISO date string. */
|
|
166
157
|
expiresAt?: string;
|
|
@@ -168,25 +159,25 @@ export interface ContractDocs<S extends EnvSchema = EnvSchema> {
|
|
|
168
159
|
deprecated?: boolean;
|
|
169
160
|
/** Why this contract is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
|
|
170
161
|
deprecatedReason?: string;
|
|
171
|
-
/** Default reason this contract's variables' values are collected/used
|
|
162
|
+
/** Default reason this contract's variables' values are collected/used: see {@link VariableDocs.purpose}. */
|
|
172
163
|
purpose?: string;
|
|
173
|
-
/** Default legal basis for this contract's variables
|
|
164
|
+
/** Default legal basis for this contract's variables: see {@link VariableDocs.legalBasis}. */
|
|
174
165
|
legalBasis?: string;
|
|
175
|
-
/** Default retention policy for this contract's variables
|
|
166
|
+
/** Default retention policy for this contract's variables: see {@link VariableDocs.retention}. */
|
|
176
167
|
retention?: string;
|
|
177
|
-
/** Default data residency for this contract's variables
|
|
168
|
+
/** Default data residency for this contract's variables: see {@link VariableDocs.dataResidency}. */
|
|
178
169
|
dataResidency?: string | string[];
|
|
179
|
-
/** Default audit-required assertion for this contract's variables
|
|
170
|
+
/** Default audit-required assertion for this contract's variables: see {@link VariableDocs.auditRequired}. */
|
|
180
171
|
auditRequired?: boolean;
|
|
181
|
-
/** Arbitrary contract-level documentation (e.g. `runbook`), rendered alongside this feature
|
|
172
|
+
/** Arbitrary contract-level documentation (e.g. `runbook`), rendered alongside this feature: see {@link VariableDocs.metadata}. */
|
|
182
173
|
metadata?: Record<string, unknown>;
|
|
183
174
|
/**
|
|
184
|
-
* Per-variable documentation, keyed by variable name
|
|
185
|
-
* at compile time
|
|
186
|
-
*
|
|
187
|
-
*
|
|
188
|
-
* still valid (not every variable needs documentation)
|
|
189
|
-
*
|
|
175
|
+
* Per-variable documentation, keyed by variable name. Keys are checked against `S`'s own keys
|
|
176
|
+
* at compile time. Documenting a variable that was renamed or removed from `schema` (or a plain
|
|
177
|
+
* typo) is therefore a type error here. The generator never has to report it as "stale" after
|
|
178
|
+
* the fact. A schema key absent from `variables` entirely is
|
|
179
|
+
* still valid (not every variable needs documentation). The generator reports it as
|
|
180
|
+
* undocumented.
|
|
190
181
|
*/
|
|
191
182
|
variables?: {
|
|
192
183
|
readonly [K in keyof S]?: VariableDocs;
|
|
@@ -195,29 +186,29 @@ export interface ContractDocs<S extends EnvSchema = EnvSchema> {
|
|
|
195
186
|
/**
|
|
196
187
|
* Documents a schema for the generator: explains values, assigns ownership,
|
|
197
188
|
* and describes lifecycle, feeding the generated docs artifact and
|
|
198
|
-
* `.env.example`. Pass it the *same* schema object given to {@link createEnv}
|
|
199
|
-
*
|
|
200
|
-
* documented
|
|
201
|
-
* `schema`'s own keys, the same object identity
|
|
202
|
-
*
|
|
189
|
+
* `.env.example`. Pass it the *same* schema object given to {@link createEnv}.
|
|
190
|
+
* The generator then statically links the two and verifies every variable is
|
|
191
|
+
* documented. TypeScript also checks `docs.variables`' keys against
|
|
192
|
+
* `schema`'s own keys, so the same object identity serves both the
|
|
193
|
+
* generator's static link and the type checker.
|
|
203
194
|
*
|
|
204
195
|
* @remarks
|
|
205
|
-
* A no-op at runtime by design
|
|
196
|
+
* A no-op at runtime by design: nothing passed here is retained anywhere,
|
|
206
197
|
* and this can never throw, no matter how malformed `schema`/`docs` are.
|
|
207
198
|
* Calling it is entirely optional: {@link createEnv} works identically whether or
|
|
208
199
|
* not a matching `documentEnv` call exists. The real "is everything
|
|
209
|
-
* documented?" check
|
|
210
|
-
*
|
|
211
|
-
*
|
|
212
|
-
*
|
|
213
|
-
*
|
|
214
|
-
*
|
|
200
|
+
* documented?" check runs entirely inside {@link build.generateEnvManifest}'s
|
|
201
|
+
* static analysis. So does every artifact this data drives: the docs
|
|
202
|
+
* artifact's ownership matrix, dependency graph, lifecycle report and
|
|
203
|
+
* security review, and `.env.example`'s comments. At runtime this function
|
|
204
|
+
* only exists as a safe marker the AST parser can find, and gives you
|
|
205
|
+
* type-checked argument shapes while writing it.
|
|
215
206
|
*
|
|
216
|
-
* `S` is inferred from `schema`, never written out by hand
|
|
207
|
+
* `S` is inferred from `schema`, never written out by hand. Pass the
|
|
217
208
|
* schema object literal (or a `const`-inferred reference to it) directly for
|
|
218
|
-
* the strongest inference
|
|
219
|
-
* annotation loses the per-key literal type
|
|
220
|
-
* string key
|
|
209
|
+
* the strongest inference. An explicitly-widened `schema: EnvSchema`
|
|
210
|
+
* annotation loses the per-key literal type, so `docs.variables` then
|
|
211
|
+
* accepts any string key.
|
|
221
212
|
*/
|
|
222
213
|
export declare function documentEnv<S extends EnvSchema>(schema: S, docs: ContractDocs<S>): void;
|
|
223
214
|
//# sourceMappingURL=document.d.ts.map
|