@maverickcer/env-cap 0.7.3 → 0.7.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ADOPTION.md +106 -124
- package/AGENTS.md +14 -13
- package/CHANGELOG.md +23 -0
- package/CODE_REVIEW.md +69 -173
- package/CONTRIBUTING.md +57 -74
- package/GUIDE.md +393 -872
- package/README.md +82 -77
- package/RELEASING.md +17 -15
- package/SECURITY.md +76 -227
- package/SUPPORT.md +21 -45
- package/VERSIONING.md +68 -105
- package/benchmarks/READING-BENCHMARKS.md +13 -7
- package/benchmarks/WRITING-BENCHMARKS.md +1 -1
- package/dist/.dts/_ipc/build-fs.d.ts +9 -14
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
- package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
- package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
- package/dist/.dts/_ipc/glob.d.ts +6 -6
- package/dist/.dts/_ipc/no-node-fs.d.ts +0 -14
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/build/lifecycle-model.d.ts +8 -3
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts/build/sarif.d.ts.map +1 -1
- package/dist/.dts/helpers/index.d.ts +1 -1
- package/dist/.dts/runtime/create.d.ts +3 -0
- package/dist/.dts/runtime/create.d.ts.map +1 -1
- package/dist/.dts/runtime/document.d.ts +7 -4
- package/dist/.dts/runtime/document.d.ts.map +1 -1
- package/dist/.dts/runtime/index.d.ts +11 -10
- package/dist/.dts/runtime/index.d.ts.map +1 -1
- package/dist/.dts/runtime/types.d.ts +16 -0
- package/dist/.dts/runtime/types.d.ts.map +1 -1
- package/dist/.dts/runtime/validate.d.ts +14 -1
- package/dist/.dts/runtime/validate.d.ts.map +1 -1
- package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
- package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/_ipc/display-path.d.ts +27 -0
- package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/_ipc/glob.d.ts +22 -0
- package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/_ipc/typescript.d.ts +20 -0
- package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/assemble-project.d.ts +47 -0
- package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
- package/dist/.dts7/build/change-model.d.ts +63 -0
- package/dist/.dts7/build/change-model.d.ts.map +1 -0
- package/dist/.dts7/build/check-artifacts.d.ts +48 -0
- package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/citation-verification.d.ts +62 -0
- package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
- package/dist/.dts7/build/compatibility.d.ts +83 -0
- package/dist/.dts7/build/compatibility.d.ts.map +1 -0
- package/dist/.dts7/build/compiler-api.d.ts +12 -0
- package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/build/contract-model.d.ts +93 -0
- package/dist/.dts7/build/contract-model.d.ts.map +1 -0
- package/dist/.dts7/build/deep-equal.d.ts +9 -0
- package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
- package/dist/.dts7/build/deep-freeze.d.ts +20 -0
- package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-graph.d.ts +170 -0
- package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-model.d.ts +81 -0
- package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
- package/dist/.dts7/build/discover.d.ts +41 -0
- package/dist/.dts7/build/discover.d.ts.map +1 -0
- package/dist/.dts7/build/display-path.d.ts +6 -0
- package/dist/.dts7/build/display-path.d.ts.map +1 -0
- package/dist/.dts7/build/docs.d.ts +176 -0
- package/dist/.dts7/build/docs.d.ts.map +1 -0
- package/dist/.dts7/build/env-example.d.ts +85 -0
- package/dist/.dts7/build/env-example.d.ts.map +1 -0
- package/dist/.dts7/build/errors.d.ts +78 -0
- package/dist/.dts7/build/errors.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-cache.d.ts +74 -0
- package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-model.d.ts +50 -0
- package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-reference.d.ts +67 -0
- package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
- package/dist/.dts7/build/exclusive-group.d.ts +19 -0
- package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
- package/dist/.dts7/build/finding-model.d.ts +80 -0
- package/dist/.dts7/build/finding-model.d.ts.map +1 -0
- package/dist/.dts7/build/generate-documentation.d.ts +176 -0
- package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/generate-evidence.d.ts +77 -0
- package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
- package/dist/.dts7/build/generate-manifest.d.ts +101 -0
- package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
- package/dist/.dts7/build/generate-usage.d.ts +95 -0
- package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
- package/dist/.dts7/build/generated-banner.d.ts +43 -0
- package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/build/glob.d.ts +6 -0
- package/dist/.dts7/build/glob.d.ts.map +1 -0
- package/dist/.dts7/build/governance-fields.d.ts +34 -0
- package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
- package/dist/.dts7/build/humanize-key.d.ts +14 -0
- package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
- package/dist/.dts7/build/index.d.ts +105 -0
- package/dist/.dts7/build/index.d.ts.map +1 -0
- package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
- package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
- package/dist/.dts7/build/link.d.ts +223 -0
- package/dist/.dts7/build/link.d.ts.map +1 -0
- package/dist/.dts7/build/literal-eval.d.ts +24 -0
- package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
- package/dist/.dts7/build/live-expirations.d.ts +47 -0
- package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
- package/dist/.dts7/build/manifest.d.ts +31 -0
- package/dist/.dts7/build/manifest.d.ts.map +1 -0
- package/dist/.dts7/build/map-utils.d.ts +8 -0
- package/dist/.dts7/build/map-utils.d.ts.map +1 -0
- package/dist/.dts7/build/merge-documentation.d.ts +35 -0
- package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/ownership-model.d.ts +59 -0
- package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
- package/dist/.dts7/build/parse.d.ts +207 -0
- package/dist/.dts7/build/parse.d.ts.map +1 -0
- package/dist/.dts7/build/reference-projections.d.ts +170 -0
- package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
- package/dist/.dts7/build/sarif.d.ts +66 -0
- package/dist/.dts7/build/sarif.d.ts.map +1 -0
- package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
- package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
- package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
- package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
- package/dist/.dts7/build/source-position.d.ts +69 -0
- package/dist/.dts7/build/source-position.d.ts.map +1 -0
- package/dist/.dts7/build/tool-version.d.ts +8 -0
- package/dist/.dts7/build/tool-version.d.ts.map +1 -0
- package/dist/.dts7/build/types.d.ts +7 -0
- package/dist/.dts7/build/types.d.ts.map +1 -0
- package/dist/.dts7/build/typescript.d.ts +6 -0
- package/dist/.dts7/build/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/usage-report.d.ts +124 -0
- package/dist/.dts7/build/usage-report.d.ts.map +1 -0
- package/dist/.dts7/cli/filesystem.d.ts +7 -0
- package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
- package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
- package/dist/.dts7/evidence/define-projection.d.ts +52 -0
- package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
- package/dist/.dts7/evidence/index.d.ts +23 -0
- package/dist/.dts7/evidence/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/index.d.ts +135 -0
- package/dist/.dts7/helpers/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/processors.d.ts +32 -0
- package/dist/.dts7/helpers/processors.d.ts.map +1 -0
- package/dist/.dts7/helpers/validators.d.ts +68 -0
- package/dist/.dts7/helpers/validators.d.ts.map +1 -0
- package/dist/.dts7/node/index.d.ts +2 -0
- package/dist/.dts7/node/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/cache.d.ts +17 -0
- package/dist/.dts7/runtime/cache.d.ts.map +1 -0
- package/dist/.dts7/runtime/create.d.ts +23 -0
- package/dist/.dts7/runtime/create.d.ts.map +1 -0
- package/dist/.dts7/runtime/document.d.ts +223 -0
- package/dist/.dts7/runtime/document.d.ts.map +1 -0
- package/dist/.dts7/runtime/errors.d.ts +55 -0
- package/dist/.dts7/runtime/errors.d.ts.map +1 -0
- package/dist/.dts7/runtime/index.d.ts +25 -0
- package/dist/.dts7/runtime/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/registry.d.ts +12 -0
- package/dist/.dts7/runtime/registry.d.ts.map +1 -0
- package/dist/.dts7/runtime/reset.d.ts +8 -0
- package/dist/.dts7/runtime/reset.d.ts.map +1 -0
- package/dist/.dts7/runtime/types.d.ts +191 -0
- package/dist/.dts7/runtime/types.d.ts.map +1 -0
- package/dist/.dts7/runtime/validate.d.ts +27 -0
- package/dist/.dts7/runtime/validate.d.ts.map +1 -0
- package/dist/{build-LFHPVDQL.js → build-DNAYWD2B.js} +8 -5
- package/dist/build-DNAYWD2B.js.map +1 -0
- package/dist/build.cjs +7 -4
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +7 -4
- package/dist/build.js.map +1 -1
- package/dist/build.ts7.d.cts +1 -0
- package/dist/build.ts7.d.ts +1 -0
- package/dist/{chunk-ZW3BLAPD.js → chunk-HAGMVMN5.js} +2 -2
- package/dist/cli/index.js +3 -3
- package/dist/eslint-plugin/index.cjs +8 -5
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +8 -5
- package/dist/eslint-plugin/index.js.map +1 -1
- package/dist/eslint-plugin/index.ts7.d.cts +1 -0
- package/dist/eslint-plugin/index.ts7.d.ts +1 -0
- package/dist/evidence.ts7.d.cts +1 -0
- package/dist/evidence.ts7.d.ts +1 -0
- package/dist/helpers.ts7.d.cts +1 -0
- package/dist/helpers.ts7.d.ts +1 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/index.ts7.d.cts +1 -0
- package/dist/index.ts7.d.ts +1 -0
- package/dist/node.ts7.d.cts +1 -0
- package/dist/node.ts7.d.ts +1 -0
- package/examples/README.md +46 -80
- package/package.json +37 -6
- package/schemas/env-cap-report.schema.json +1 -1
- package/skills/env-cap/SKILL.md +1 -1
- package/skills/env-cap/references/api.md +1 -1
- package/specs/architecture.md +2 -2
- package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
- package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
- package/specs/generated-artifacts.md +14 -2
- package/dist/build-LFHPVDQL.js.map +0 -1
- /package/dist/{chunk-ZW3BLAPD.js.map → chunk-HAGMVMN5.js.map} +0 -0
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
import type { EnvSchema } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* Developer-supplied evidence assertions for one variable -- categorically
|
|
4
|
+
* different from every field on {@link VariableDocs}: those are
|
|
5
|
+
* declared-and-never-verified, while `dynamicAccess` is re-checked against
|
|
6
|
+
* reality on every run (fresh / stale / missing). Kept structurally separate,
|
|
7
|
+
* in `VariableDocs.evidence` rather than folded in alongside `description`/
|
|
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.
|
|
10
|
+
*/
|
|
11
|
+
export interface VariableEvidenceDocs {
|
|
12
|
+
/**
|
|
13
|
+
* Citation(s) of where this variable is actually read dynamically --
|
|
14
|
+
* somewhere env-cap's own static AST scan can't see (a shell script, a
|
|
15
|
+
* Docker entrypoint, a sibling service). Each entry is a
|
|
16
|
+
* `"<relative-path>:<line>:<column>"` citation.
|
|
17
|
+
*
|
|
18
|
+
* @remarks
|
|
19
|
+
* A developer's re-acknowledgment that access happens, never a claim
|
|
20
|
+
* env-cap itself observed anything -- tracked as its own independent fact
|
|
21
|
+
* and never folded into the AST-derived `VariableAccessStatus`. Re-verified
|
|
22
|
+
* every run: a citation whose file no longer exists, or whose content has
|
|
23
|
+
* visibly changed since it was last acknowledged, is flagged rather than
|
|
24
|
+
* trusted forever.
|
|
25
|
+
*/
|
|
26
|
+
dynamicAccess?: readonly string[];
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Per-variable documentation. Every field is optional and unconstrained on
|
|
30
|
+
* purpose -- there is no required shape, so documenting a variable never
|
|
31
|
+
* fights the type checker, and you can add a field the generator doesn't
|
|
32
|
+
* know about yet without it being rejected.
|
|
33
|
+
*/
|
|
34
|
+
export interface VariableDocs {
|
|
35
|
+
/** Human-readable explanation of what this variable is and what it controls. */
|
|
36
|
+
description?: string;
|
|
37
|
+
/** Who owns this variable (a team, a handle, whatever your org uses). Overrides the contract's own `owner` for this key. */
|
|
38
|
+
owner?: string;
|
|
39
|
+
/**
|
|
40
|
+
* How sensitive this variable's value is. Overrides the contract's own `sensitivity` for this
|
|
41
|
+
* key.
|
|
42
|
+
*
|
|
43
|
+
* @remarks
|
|
44
|
+
* Deliberately an open `string`, not a closed union: an org's own sensitivity vocabulary is its
|
|
45
|
+
* own, and a level env-cap doesn't recognize is always honored, never dropped. The generator
|
|
46
|
+
* still reports a `NONSTANDARD_SENSITIVITY_LEVEL` finding (severity `info`, never blocking) for
|
|
47
|
+
* anything outside `secret`/`credential`/`pii`/`config`, so vocabulary drift stays visible
|
|
48
|
+
* without being enforced.
|
|
49
|
+
*/
|
|
50
|
+
sensitivity?: string;
|
|
51
|
+
/** 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
|
+
expiresAt?: string;
|
|
53
|
+
/** How to get a new value before/when it expires (e.g. "Rotate in the Stripe dashboard, then redeploy."). */
|
|
54
|
+
refreshInstructions?: string;
|
|
55
|
+
/**
|
|
56
|
+
* The kind of authenticator/secret this variable holds (e.g. "api-key", "oauth-client-secret",
|
|
57
|
+
* "database-password", "tls-certificate") -- feeds the NIST SP 800-53 IA-5 rotation-status
|
|
58
|
+
* report's "authenticator type" column (IA-5's main statement requires an organization-defined
|
|
59
|
+
* rotation period "by authenticator type," so this is what a generator groups/labels by).
|
|
60
|
+
*
|
|
61
|
+
* @remarks
|
|
62
|
+
* Deliberately an open `string`, not a closed union -- same "open vocabulary" pattern as
|
|
63
|
+
* {@link sensitivity}: an org's own authenticator taxonomy is its own, and IA-5 itself never
|
|
64
|
+
* names a fixed set of types either.
|
|
65
|
+
*/
|
|
66
|
+
authenticatorType?: string;
|
|
67
|
+
/**
|
|
68
|
+
* How often this variable's value must be rotated, in organization-defined terms (e.g. "90
|
|
69
|
+
* days", "P90D", "6 months") -- IA-5's own "organization-defined time period" per authenticator
|
|
70
|
+
* type (the time-based half of IA-5's two-trigger rotation model). Paired with
|
|
71
|
+
* {@link lastRotatedAt} so a generator can compute whether rotation is actually current, rather
|
|
72
|
+
* than only recording that a period was declared; see `lifecycle-model.ts`'s
|
|
73
|
+
* `computeRotationStatus()` for exactly how the two combine with {@link expiresAt}. What comes
|
|
74
|
+
* out is a policy-window judgement over declared metadata ("within the declared period"), never
|
|
75
|
+
* a statement that a rotation happened or that a control is met: env-cap reads declarations, it
|
|
76
|
+
* does not check them against the secret store.
|
|
77
|
+
*/
|
|
78
|
+
rotationPeriod?: string;
|
|
79
|
+
/**
|
|
80
|
+
* ISO date string -- the last time this variable's value was actually rotated. Paired with
|
|
81
|
+
* {@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 -- a value can
|
|
83
|
+
* be freshly rotated and still have a near-term `expiresAt` (a short-lived token), or long overdue
|
|
84
|
+
* for rotation while its `expiresAt` (if any) is still comfortably in the future.
|
|
85
|
+
*/
|
|
86
|
+
lastRotatedAt?: string;
|
|
87
|
+
/**
|
|
88
|
+
* IA-5's event-based rotation triggers that apply to this variable (e.g. "suspected compromise",
|
|
89
|
+
* "personnel change", "system update") -- the event-based half of IA-5's two-trigger rotation
|
|
90
|
+
* model. Structured and additive alongside the existing free-text {@link refreshInstructions}
|
|
91
|
+
* rather than replacing it: this is a list a generator can render as its own column,
|
|
92
|
+
* `refreshInstructions` stays prose ("how to actually rotate it"). Presence-only -- env-cap has
|
|
93
|
+
* no way to observe whether a listed event actually occurred, so declaring this never by itself
|
|
94
|
+
* changes a computed rotation status (see `lifecycle-model.ts`); it only makes the
|
|
95
|
+
* event-based trigger's existence visible in generated output.
|
|
96
|
+
*/
|
|
97
|
+
rotationTriggerEvents?: readonly string[];
|
|
98
|
+
/**
|
|
99
|
+
* Explicit, actionable instructions for obtaining this variable's value the *first* time --
|
|
100
|
+
* where `refreshInstructions` is "how to rotate it once you already have one," this is "how to
|
|
101
|
+
* get one at all" (e.g. "Create a restricted API key in the Stripe dashboard under Developers ->
|
|
102
|
+
* API keys, scoped to read/write Charges."). A named field specifically so this can render as
|
|
103
|
+
* its own labeled line in generated docs, rather than requiring a `metadata.setup`-style
|
|
104
|
+
* convention with no dedicated rendering or type checking.
|
|
105
|
+
*/
|
|
106
|
+
setupInstructions?: string;
|
|
107
|
+
/** Documentation-level assertion that this variable must be set. Independent of how (or whether) a validator actually enforces it. */
|
|
108
|
+
required?: boolean;
|
|
109
|
+
/** Marks this variable as being phased out. Independent of `expiresAt` (a rotation/sunset date) and of the contract-level `active` switch (on/off, not a phase-out signal). */
|
|
110
|
+
deprecated?: boolean;
|
|
111
|
+
/** Why this variable is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
|
|
112
|
+
deprecatedReason?: string;
|
|
113
|
+
/** ISO date string -- by when a deprecated variable must be removed. Only meaningful alongside `deprecated: true`. */
|
|
114
|
+
removeBy?: string;
|
|
115
|
+
/** 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
|
+
renamedFrom?: string;
|
|
117
|
+
/** 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
|
+
purpose?: string;
|
|
119
|
+
/** 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
|
+
legalBasis?: string;
|
|
121
|
+
/** 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
|
+
retention?: string;
|
|
123
|
+
/** 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
|
+
dataResidency?: string | string[];
|
|
125
|
+
/** Documentation-level assertion that this variable's handling must be auditable. Overrides the contract's own `auditRequired` for this key. */
|
|
126
|
+
auditRequired?: boolean;
|
|
127
|
+
/**
|
|
128
|
+
* Developer-supplied evidence assertions for this variable -- verified over
|
|
129
|
+
* time, unlike every other field above, which is declared and never
|
|
130
|
+
* verified. Kept structurally separate for exactly that reason; see
|
|
131
|
+
* {@link VariableEvidenceDocs}.
|
|
132
|
+
*/
|
|
133
|
+
evidence?: VariableEvidenceDocs;
|
|
134
|
+
/**
|
|
135
|
+
* Structured, unsupported-key documentation -- any primitive or object value, for anything that
|
|
136
|
+
* doesn't warrant its own named field. A previously-supported top-level key belongs in a named
|
|
137
|
+
* field above instead of here once one exists for it.
|
|
138
|
+
*/
|
|
139
|
+
metadata?: Record<string, unknown>;
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* Contract-level documentation, plus everything {@link documentEnv}'s options used to carry that
|
|
143
|
+
* only the generator ever read.
|
|
144
|
+
*
|
|
145
|
+
* @remarks
|
|
146
|
+
* Generic over `S`, the exact schema type {@link documentEnv} infers from its `schema` argument --
|
|
147
|
+
* this is what makes `variables` below a closed, checked map (a typo'd or renamed key is a
|
|
148
|
+
* compile error, not a silent no-op) rather than an open `Record<string, VariableDocs>` any string
|
|
149
|
+
* would satisfy. `S` defaults to the widest possible schema so this type is still nameable on its
|
|
150
|
+
* own (e.g. in a helper function's own parameter type) without narrowing to one specific contract.
|
|
151
|
+
*/
|
|
152
|
+
export interface ContractDocs<S extends EnvSchema = EnvSchema> {
|
|
153
|
+
/** 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
|
+
name?: string;
|
|
155
|
+
/** Groups this contract under a heading in the generated docs' feature catalog. */
|
|
156
|
+
category?: string;
|
|
157
|
+
/** 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
|
+
exclusiveGroup?: string;
|
|
159
|
+
/** 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
|
+
active?: boolean;
|
|
161
|
+
/** Default owner for every variable in this contract that doesn't set its own `owner`. */
|
|
162
|
+
owner?: string;
|
|
163
|
+
/** 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
|
+
sensitivity?: string;
|
|
165
|
+
/** Whole-contract/feature sunset date, ISO date string. */
|
|
166
|
+
expiresAt?: string;
|
|
167
|
+
/** Marks this whole contract/feature as being phased out. Independent of `active` (on/off, not a phase-out signal). */
|
|
168
|
+
deprecated?: boolean;
|
|
169
|
+
/** Why this contract is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
|
|
170
|
+
deprecatedReason?: string;
|
|
171
|
+
/** Default reason this contract's variables' values are collected/used -- see {@link VariableDocs.purpose}. */
|
|
172
|
+
purpose?: string;
|
|
173
|
+
/** Default legal basis for this contract's variables -- see {@link VariableDocs.legalBasis}. */
|
|
174
|
+
legalBasis?: string;
|
|
175
|
+
/** Default retention policy for this contract's variables -- see {@link VariableDocs.retention}. */
|
|
176
|
+
retention?: string;
|
|
177
|
+
/** Default data residency for this contract's variables -- see {@link VariableDocs.dataResidency}. */
|
|
178
|
+
dataResidency?: string | string[];
|
|
179
|
+
/** Default audit-required assertion for this contract's variables -- see {@link VariableDocs.auditRequired}. */
|
|
180
|
+
auditRequired?: boolean;
|
|
181
|
+
/** Arbitrary contract-level documentation (e.g. `runbook`), rendered alongside this feature -- see {@link VariableDocs.metadata}. */
|
|
182
|
+
metadata?: Record<string, unknown>;
|
|
183
|
+
/**
|
|
184
|
+
* Per-variable documentation, keyed by variable name -- keys are checked against `S`'s own keys
|
|
185
|
+
* at compile time, so documenting a variable that was renamed or removed from `schema` (or a
|
|
186
|
+
* plain typo) is a type error here, not a silently-ignored entry the generator would otherwise
|
|
187
|
+
* have to report as "stale" after the fact. A schema key absent from `variables` entirely is
|
|
188
|
+
* still valid (not every variable needs documentation) and is reported as undocumented by the
|
|
189
|
+
* generator, exactly as before.
|
|
190
|
+
*/
|
|
191
|
+
variables?: {
|
|
192
|
+
readonly [K in keyof S]?: VariableDocs;
|
|
193
|
+
};
|
|
194
|
+
}
|
|
195
|
+
/**
|
|
196
|
+
* Documents a schema for the generator: explains values, assigns ownership,
|
|
197
|
+
* and describes lifecycle, feeding the generated docs artifact and
|
|
198
|
+
* `.env.example`. Pass it the *same* schema object given to {@link createEnv}, so
|
|
199
|
+
* the generator can statically link the two and verify every variable is
|
|
200
|
+
* documented -- and so TypeScript can check `docs.variables`' keys against
|
|
201
|
+
* `schema`'s own keys, the same object identity doing double duty for both
|
|
202
|
+
* the generator's static link and the type checker's.
|
|
203
|
+
*
|
|
204
|
+
* @remarks
|
|
205
|
+
* A no-op at runtime by design -- nothing passed here is retained anywhere,
|
|
206
|
+
* and this can never throw, no matter how malformed `schema`/`docs` are.
|
|
207
|
+
* Calling it is entirely optional: {@link createEnv} works identically whether or
|
|
208
|
+
* not a matching `documentEnv` call exists. The real "is everything
|
|
209
|
+
* documented?" check, and every artifact this data drives (the docs
|
|
210
|
+
* artifact's ownership matrix, dependency graph, lifecycle report, and
|
|
211
|
+
* security review; `.env.example`'s comments), runs entirely inside
|
|
212
|
+
* {@link build.generateEnvManifest}'s static analysis -- this function's only job at
|
|
213
|
+
* runtime is to exist as a safe, harmless marker the AST parser can find,
|
|
214
|
+
* and to give you type-checked argument shapes while writing it.
|
|
215
|
+
*
|
|
216
|
+
* `S` is inferred from `schema`, never written out by hand -- pass the
|
|
217
|
+
* schema object literal (or a `const`-inferred reference to it) directly for
|
|
218
|
+
* the strongest inference; an explicitly-widened `schema: EnvSchema`
|
|
219
|
+
* annotation loses the per-key literal type and falls back to accepting any
|
|
220
|
+
* string key in `docs.variables`, same as before this generic existed.
|
|
221
|
+
*/
|
|
222
|
+
export declare function documentEnv<S extends EnvSchema>(schema: S, docs: ContractDocs<S>): void;
|
|
223
|
+
//# sourceMappingURL=document.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../../src/runtime/document.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every error type here is constructed only from: the variable name, the
|
|
3
|
+
* declaring contract's name, the failure kind, and a message string that the
|
|
4
|
+
* *developer's own* processor/validator produced. Raw or processed environment
|
|
5
|
+
* values are never read into an error -- see the Security section in the README.
|
|
6
|
+
*
|
|
7
|
+
* Documentation (description, owner, etc.) never appears here, even when a
|
|
8
|
+
* {@link documentEnv} call exists for this variable -- `documentEnv` is
|
|
9
|
+
* build-time-only and its data is never retained anywhere {@link validateEnv}
|
|
10
|
+
* could read it back out. This is a deliberate consequence of keeping the
|
|
11
|
+
* runtime minimal, not an oversight.
|
|
12
|
+
*/
|
|
13
|
+
/** One variable's processing or validation failure, as recorded by {@link validateEnv}. */
|
|
14
|
+
export interface VariableFailure {
|
|
15
|
+
/** The schema key that failed. */
|
|
16
|
+
readonly variable: string;
|
|
17
|
+
/** The declaring contract's `name` (see {@link CreateEnvOptions}). */
|
|
18
|
+
readonly contractName: string;
|
|
19
|
+
/** `import.meta.url` (or similar) passed to `createEnv`'s `source` option, if any. Falls back to `contractName` when absent. */
|
|
20
|
+
readonly source: string | undefined;
|
|
21
|
+
/** Which stage produced the failure. */
|
|
22
|
+
readonly kind: "processor" | "validator";
|
|
23
|
+
/** The error message from the developer's own processor/validator, or the thrown error's message. */
|
|
24
|
+
readonly message: string;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Thrown by {@link validateEnv} when one or more variables fail processing or
|
|
28
|
+
* validation. Aggregates every failure across every contract in the batch --
|
|
29
|
+
* the caller sees the whole picture in one error, not one-at-a-time.
|
|
30
|
+
*
|
|
31
|
+
* @remarks
|
|
32
|
+
* `code` is a stable, Stable-tier discriminant for programmatic handling --
|
|
33
|
+
* prefer it over `.name`/`instanceof` when a message-independent switch is needed.
|
|
34
|
+
*/
|
|
35
|
+
export declare class EnvValidationError extends Error {
|
|
36
|
+
/** Stable discriminant for programmatic handling; always `"ENV_VALIDATION_FAILED"`. */
|
|
37
|
+
readonly code = "ENV_VALIDATION_FAILED";
|
|
38
|
+
/** Every variable failure across every contract in the batch. */
|
|
39
|
+
readonly failures: readonly VariableFailure[];
|
|
40
|
+
constructor(failures: readonly VariableFailure[]);
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Thrown when a contract's value is accessed via property access before
|
|
44
|
+
* {@link validateEnv} has completed successfully for it.
|
|
45
|
+
*
|
|
46
|
+
* @remarks
|
|
47
|
+
* `code` is a stable, Stable-tier discriminant for programmatic handling --
|
|
48
|
+
* prefer it over `.name`/`instanceof` when a message-independent switch is needed.
|
|
49
|
+
*/
|
|
50
|
+
export declare class EnvNotReadyError extends Error {
|
|
51
|
+
/** Stable discriminant for programmatic handling; always `"ENV_NOT_READY"`. */
|
|
52
|
+
readonly code = "ENV_NOT_READY";
|
|
53
|
+
constructor(contractName: string, key: string);
|
|
54
|
+
}
|
|
55
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,gIAAgI;IAChI,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAAA;IACxC,qGAAqG;IACrG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAwBD;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,uFAAuF;IACvF,QAAQ,CAAC,IAAI,2BAA0B;IACvC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;gBAEjC,QAAQ,EAAE,SAAS,eAAe,EAAE;CAMjD;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,mBAAkB;gBAEnB,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAS9C"}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The env-cap runtime entry point: declare contracts, validate them once at startup, and read
|
|
3
|
+
* typed values through the contract that owns them.
|
|
4
|
+
*
|
|
5
|
+
* It imports no Node module and reads no Node global; it takes values only from the `values`
|
|
6
|
+
* you pass to `validateEnv()`. `test/runtime/browser-bundle.test.ts` checks the built bundle for
|
|
7
|
+
* Node imports, `process.` and `Buffer.`, but a third-party import would pass unnoticed.
|
|
8
|
+
* Discovery and manifest generation live in `@maverickcer/env-cap/build`, never here.
|
|
9
|
+
*
|
|
10
|
+
* `documentEnv` is exported here, not from `./build`, because it is called inline in the same
|
|
11
|
+
* schema file as `createEnv`, which may end up in any bundle. It must be as cheap to import as
|
|
12
|
+
* `createEnv` (see `document.ts`).
|
|
13
|
+
*
|
|
14
|
+
* @packageDocumentation
|
|
15
|
+
*/
|
|
16
|
+
export type { CreateEnvOptions, DefaultValue, EnvContract, EnvDefinition, EnvSchema, InferEnvValue, Processor, RawEnv, validateEnvOptions, validateEnvResult, Validator, } from "./types.js";
|
|
17
|
+
export { createEnv } from "./create.js";
|
|
18
|
+
export { documentEnv } from "./document.js";
|
|
19
|
+
export type { ContractDocs, VariableDocs, VariableEvidenceDocs } from "./document.js";
|
|
20
|
+
export { EnvNotReadyError, EnvValidationError } from "./errors.js";
|
|
21
|
+
export type { VariableFailure } from "./errors.js";
|
|
22
|
+
export { isEnvContract } from "./registry.js";
|
|
23
|
+
export { resetEnvCache } from "./reset.js";
|
|
24
|
+
export { validateEnv } from "./validate.js";
|
|
25
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACT,MAAM,EACN,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,GACV,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { ContractInternals } from "./types.js";
|
|
2
|
+
/** Associates a contract object with its internal identity/schema. Called once, by `createEnv`. */
|
|
3
|
+
export declare function registerContract(contract: object, internals: ContractInternals): void;
|
|
4
|
+
/**
|
|
5
|
+
* Looks up a contract's internal identity/schema.
|
|
6
|
+
*
|
|
7
|
+
* @throws {TypeError} If `contract` wasn't returned by `createEnv` (and so was never registered).
|
|
8
|
+
*/
|
|
9
|
+
export declare function getContractInternals(contract: object): ContractInternals;
|
|
10
|
+
/** Type guard: `true` when `value` was created by `createEnv` (i.e. is a registered contract). */
|
|
11
|
+
export declare function isEnvContract(value: unknown): value is object;
|
|
12
|
+
//# sourceMappingURL=registry.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/runtime/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAUnD,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAErF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CASxE;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAK7D"}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Clears cached validation state. Intended for tests and dev tooling (e.g.
|
|
3
|
+
* `beforeEach(() => resetEnvCache())` in a test suite that re-validates with
|
|
4
|
+
* different fixture values per test) -- production applications validate
|
|
5
|
+
* once at startup and should not normally call this.
|
|
6
|
+
*/
|
|
7
|
+
export declare function resetEnvCache(): void;
|
|
8
|
+
//# sourceMappingURL=reset.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"reset.d.ts","sourceRoot":"","sources":["../../../src/runtime/reset.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Core contract types for env-cap.
|
|
3
|
+
*
|
|
4
|
+
* These types are intentionally minimal: an `EnvDefinition` describes how to
|
|
5
|
+
* turn one raw environment value into one typed, validated application
|
|
6
|
+
* value. There is no `optional`/`required` flag anywhere in this file --
|
|
7
|
+
* requiredness is just a validator that rejects `undefined`/empty values.
|
|
8
|
+
*
|
|
9
|
+
* Documentation fields (description, owner, expiresAt, category, ...) live
|
|
10
|
+
* entirely in {@link documentEnv} (see `document.ts`), not here -- this file is
|
|
11
|
+
* the runtime's whole vocabulary, and every field in it is read by
|
|
12
|
+
* `validate.ts`/`create.ts`/`errors.ts` at runtime. If a field is only ever
|
|
13
|
+
* read by the generator, it belongs in `document.ts`, not here. `context` is
|
|
14
|
+
* the one exception worth calling out: it's also read by the build package
|
|
15
|
+
* for documentation display (see ADR 0022), but it belongs here rather than
|
|
16
|
+
* in `documentEnv()` because `validate.ts` reads it too, to decide pipeline
|
|
17
|
+
* participation -- the same bar `default`/`processor`/`validator` already
|
|
18
|
+
* clear.
|
|
19
|
+
*/
|
|
20
|
+
/** The raw, unprocessed source of environment values (e.g. `process.env`, a resolved secrets bag). */
|
|
21
|
+
export type RawEnv = Readonly<Record<string, unknown>>;
|
|
22
|
+
/** Processes a raw value into a typed, ready-to-use application value. Must not read any other key. */
|
|
23
|
+
export type Processor<T> = (value: unknown) => T;
|
|
24
|
+
/**
|
|
25
|
+
* Validates an already-processed value; return `true` when valid, or a human-readable error
|
|
26
|
+
* string when invalid.
|
|
27
|
+
*
|
|
28
|
+
* @remarks
|
|
29
|
+
* Receives the full raw env for conditional validation (e.g. "required only if X").
|
|
30
|
+
*/
|
|
31
|
+
export type Validator<T> = (value: T, rawEnv: RawEnv) => true | string;
|
|
32
|
+
/**
|
|
33
|
+
* A default may be a literal value, or a zero-arg thunk evaluated lazily when the raw value is
|
|
34
|
+
* undefined.
|
|
35
|
+
*
|
|
36
|
+
* @remarks
|
|
37
|
+
* The union is redundant at the type level (`unknown` alone already accepts a
|
|
38
|
+
* function) -- it's kept because this type is public API, and collapsing it to bare `unknown`
|
|
39
|
+
* would erase the one thing a reader of the generated `.d.ts` needs to learn here.
|
|
40
|
+
*/
|
|
41
|
+
export type DefaultValue = unknown | (() => unknown);
|
|
42
|
+
/** Configuration for one schema entry: how to default, process, and validate a single raw environment value. */
|
|
43
|
+
export interface EnvDefinition<T> {
|
|
44
|
+
/** Literal fallback or lazy thunk used when the raw value is `undefined`. */
|
|
45
|
+
default?: DefaultValue;
|
|
46
|
+
/** Converts the raw (or defaulted) value to `T`; passed through unprocessed when omitted. */
|
|
47
|
+
processor?: Processor<T>;
|
|
48
|
+
/** Rejects an invalid processed value; return `true` to accept it. */
|
|
49
|
+
validator?: Validator<T>;
|
|
50
|
+
/**
|
|
51
|
+
* The validation context this variable belongs to (e.g. `"server"`,
|
|
52
|
+
* `"production"`, `"worker"`) -- entirely application-defined; env-cap
|
|
53
|
+
* never interprets, detects, or infers this string. Omitted (the
|
|
54
|
+
* default) means the variable participates in every {@link validateEnv}
|
|
55
|
+
* run regardless of `activeContexts`. A variable belongs to at most one
|
|
56
|
+
* validation context -- see ADR 0022 for why this is a single `string`
|
|
57
|
+
* and not `string[]`; do not widen it to an array to let one variable
|
|
58
|
+
* join multiple contexts, that reintroduces the AND/OR ambiguity this
|
|
59
|
+
* design deliberately avoids.
|
|
60
|
+
*
|
|
61
|
+
* @remarks
|
|
62
|
+
* Validation contexts are a participation filter only -- not
|
|
63
|
+
* authentication, authorization, or a bundling/security boundary. See
|
|
64
|
+
* ADR 0022's Formal Invariants.
|
|
65
|
+
*/
|
|
66
|
+
context?: string;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* A schema is a map of variable name -> definition.
|
|
70
|
+
*
|
|
71
|
+
* @remarks
|
|
72
|
+
* `EnvDefinition<any>` is used only as the generic *bound* here (never surfaced to consumers):
|
|
73
|
+
* TypeScript infers a precise, per-key literal type for `S` from the object passed to
|
|
74
|
+
* {@link createEnv}, so the resolved contract type (see {@link InferEnvValue}) stays fully
|
|
75
|
+
* strict. This is the same variance workaround used by schema libraries like zod/trpc for
|
|
76
|
+
* heterogeneous generic maps.
|
|
77
|
+
*/
|
|
78
|
+
export type EnvSchema = Record<string, EnvDefinition<any>>;
|
|
79
|
+
type UnwrapDefault<D> = D extends {
|
|
80
|
+
default: infer Def;
|
|
81
|
+
} ? Def extends () => infer R ? R : Def : never;
|
|
82
|
+
/**
|
|
83
|
+
* Resolves the application-facing type for one schema entry: processor return type, else the
|
|
84
|
+
* default's type, else `string` (the shape raw process.env values naturally arrive in).
|
|
85
|
+
*
|
|
86
|
+
* @remarks
|
|
87
|
+
* Same documented generic-bound variance workaround as {@link EnvSchema} above --
|
|
88
|
+
* `any` here is never surfaced to a consumer's inferred type.
|
|
89
|
+
*/
|
|
90
|
+
export type InferEnvValue<D extends EnvDefinition<any>> = D extends {
|
|
91
|
+
/** Narrows to the processor's return type when one is present. */
|
|
92
|
+
processor: Processor<infer P>;
|
|
93
|
+
} ? P : [UnwrapDefault<D>] extends [never] ? string : UnwrapDefault<D>;
|
|
94
|
+
/** The internal, non-enumerable identity + metadata attached to every contract created by `createEnv`. */
|
|
95
|
+
export interface ContractInternals<S extends EnvSchema = EnvSchema> {
|
|
96
|
+
readonly id: symbol;
|
|
97
|
+
readonly name: string;
|
|
98
|
+
readonly source: string | undefined;
|
|
99
|
+
readonly schema: S;
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* The object returned by {@link createEnv}. Each key is a lazily-resolved getter backed by the
|
|
103
|
+
* runtime cache -- there is no global env object, only per-feature contracts like this one.
|
|
104
|
+
*
|
|
105
|
+
* @remarks
|
|
106
|
+
* `toString()` is intersected in (rather than left to the ambient `Object.prototype`
|
|
107
|
+
* declaration) because `create.ts` genuinely overrides it to return a redacted
|
|
108
|
+
* `EnvContract("name")` representation, never resolved values -- see ADR 0006. Declaring
|
|
109
|
+
* it here means the type accurately describes what calling `String(contract)` returns.
|
|
110
|
+
*/
|
|
111
|
+
export type EnvContract<S extends EnvSchema> = {
|
|
112
|
+
readonly [K in keyof S]: InferEnvValue<S[K]>;
|
|
113
|
+
} & {
|
|
114
|
+
/** Returns the redacted `EnvContract("name")` representation, never resolved values -- see ADR 0006. */
|
|
115
|
+
toString(): string;
|
|
116
|
+
};
|
|
117
|
+
/**
|
|
118
|
+
* What {@link validateEnv} validates: the generated manifest, the raw values, and the active
|
|
119
|
+
* validation contexts.
|
|
120
|
+
*
|
|
121
|
+
* @remarks
|
|
122
|
+
* Only the first call in a process is used; later calls return its outcome, whatever options
|
|
123
|
+
* they pass. Call `resetEnvCache()` between runs in a test.
|
|
124
|
+
*/
|
|
125
|
+
export interface validateEnvOptions {
|
|
126
|
+
/** The raw source of environment values, e.g. `process.env` or a resolved secrets bag. */
|
|
127
|
+
values: RawEnv;
|
|
128
|
+
/**
|
|
129
|
+
* Every contract to validate -- typically the `contracts` array imported
|
|
130
|
+
* from a generated manifest (see {@link build.generateEnvManifest}). Pass all of them
|
|
131
|
+
* in one call: {@link validateEnv} only ever initializes once per process, so
|
|
132
|
+
* a second call returns the first call's cached result without
|
|
133
|
+
* re-running anything, even if it passes a different manifest.
|
|
134
|
+
*/
|
|
135
|
+
manifest: readonly EnvContract<any>[];
|
|
136
|
+
/**
|
|
137
|
+
* The validation contexts active for this run (e.g. `["server",
|
|
138
|
+
* "production"]`) -- entirely application-defined; env-cap never
|
|
139
|
+
* detects or infers these, the caller always computes and passes them
|
|
140
|
+
* explicitly. A variable whose `context` isn't in this list is skipped
|
|
141
|
+
* entirely (no default/processor/validator runs for it, and it stays in
|
|
142
|
+
* its not-ready state, exactly as if this run had never happened for
|
|
143
|
+
* it) -- see ADR 0022. A variable with no `context` always participates,
|
|
144
|
+
* regardless of what's passed here. Omitted (the default) behaves as an
|
|
145
|
+
* empty list: only variables with no `context` participate.
|
|
146
|
+
*
|
|
147
|
+
* @remarks
|
|
148
|
+
* Not part of the validation cache's identity -- {@link validateEnv}
|
|
149
|
+
* remains one-shot per process exactly as before this option existed. A
|
|
150
|
+
* second call does not re-evaluate `activeContexts`; it returns the
|
|
151
|
+
* first call's result outright. Different active contexts belong to
|
|
152
|
+
* different processes (e.g. a server process and a browser bundle),
|
|
153
|
+
* never to two calls within the same one.
|
|
154
|
+
*/
|
|
155
|
+
activeContexts?: readonly string[];
|
|
156
|
+
}
|
|
157
|
+
/** Aggregate counts from a completed {@link validateEnv} run. */
|
|
158
|
+
export interface validateEnvResult {
|
|
159
|
+
/** Number of contracts in the manifest that were validated. */
|
|
160
|
+
readonly contractCount: number;
|
|
161
|
+
/** Total number of variables validated across all contracts. */
|
|
162
|
+
readonly variableCount: number;
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* Options for {@link createEnv}: a display name for error messages and where the contract was
|
|
166
|
+
* declared.
|
|
167
|
+
*
|
|
168
|
+
* @remarks
|
|
169
|
+
* Purely for identification. Owners, descriptions and other documentation belong in
|
|
170
|
+
* `documentEnv()`.
|
|
171
|
+
*/
|
|
172
|
+
export interface CreateEnvOptions {
|
|
173
|
+
/**
|
|
174
|
+
* A short, stable label for this contract (e.g. "payments", "database").
|
|
175
|
+
* Used in error messages. Defaults to an auto-generated anonymous label if
|
|
176
|
+
* omitted -- providing one is strongly recommended for readable validation
|
|
177
|
+
* errors.
|
|
178
|
+
*/
|
|
179
|
+
name?: string;
|
|
180
|
+
/**
|
|
181
|
+
* Pass `import.meta.url` here so validation errors point at the file that
|
|
182
|
+
* declared the failing variable (e.g. "features/payments/env.schema.ts")
|
|
183
|
+
* instead of just the short `name` label. There is no portable way for
|
|
184
|
+
* `createEnv` to discover its caller's module URL on its own -- this is
|
|
185
|
+
* always correct and never goes stale, since it's supplied by the JS
|
|
186
|
+
* engine rather than hand-typed.
|
|
187
|
+
*/
|
|
188
|
+
source?: string;
|
|
189
|
+
}
|
|
190
|
+
export {};
|
|
191
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/runtime/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,sGAAsG;AACtG,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAEtD,uGAAuG;AACvG,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAA;AAEhD;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAA;AAEtE;;;;;;;;GAQG;AAEH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAA;AAEpD,gHAAgH;AAChH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACxB,sEAAsE;IACtE,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACxB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;GASG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAA;AAE1D,KAAK,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,GAAG,CAAA;CAAE,GACpD,GAAG,SAAS,MAAM,MAAM,CAAC,GACvB,CAAC,GACD,GAAG,GACL,KAAK,CAAA;AAET;;;;;;;GAOG;AAEH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS;IAClE,kEAAkE;IAClE,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAA;CAC9B,GACG,CAAC,GACD,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAChC,MAAM,GACN,aAAa,CAAC,CAAC,CAAC,CAAA;AAEtB,0GAA0G;AAC1G,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAChE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,SAAS,IAAI;IAC7C,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7C,GAAG;IACF,wGAAwG;IACxG,QAAQ,IAAI,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IAEH,QAAQ,EAAE,SAAS,WAAW,CAAC,GAAG,CAAC,EAAE,CAAA;IACrC;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB"}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import type { validateEnvOptions, validateEnvResult } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* Validates every variable in every contract in `options.manifest` against
|
|
4
|
+
* `options.values`, then caches the results.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Idempotent: the first successful (or failed) call is authoritative for the life of the
|
|
8
|
+
* process -- later calls return (or re-throw) that same outcome without re-running any
|
|
9
|
+
* processor or validator. Concurrent in-flight calls share one underlying run. Call
|
|
10
|
+
* `resetEnvCache()` to validate again, for example between test scenarios.
|
|
11
|
+
*
|
|
12
|
+
* The record of validated values is frozen, but only one level deep: an object, array or `URL`
|
|
13
|
+
* a processor returns stays mutable. A failure message carries variable and contract names and
|
|
14
|
+
* the message your processor or validator produced, never the value itself.
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```ts
|
|
18
|
+
* import { validateEnv } from "@maverickcer/env-cap"
|
|
19
|
+
* import { manifest } from "./generated/env.manifest"
|
|
20
|
+
*
|
|
21
|
+
* await validateEnv({ manifest, values: process.env })
|
|
22
|
+
* ```
|
|
23
|
+
*
|
|
24
|
+
* @throws {EnvValidationError} If any variable fails processing or validation.
|
|
25
|
+
*/
|
|
26
|
+
export declare function validateEnv(options: validateEnvOptions): Promise<validateEnvResult>;
|
|
27
|
+
//# sourceMappingURL=validate.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/runtime/validate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEvE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0BzF"}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import {
|
|
3
3
|
readToolVersion
|
|
4
|
-
} from "./chunk-
|
|
4
|
+
} from "./chunk-HAGMVMN5.js";
|
|
5
5
|
|
|
6
6
|
// src/build/evidence-snapshot.ts
|
|
7
7
|
import path3 from "path";
|
|
@@ -5098,15 +5098,18 @@ async function checkEnvArtifacts(options) {
|
|
|
5098
5098
|
function sarifLevel(severity) {
|
|
5099
5099
|
return severity === "info" ? "note" : severity;
|
|
5100
5100
|
}
|
|
5101
|
+
function uriReference(file) {
|
|
5102
|
+
return encodeURI(file).replace(/#/g, "%23").replace(/\?/g, "%3F");
|
|
5103
|
+
}
|
|
5101
5104
|
function sarifLocations(finding) {
|
|
5102
5105
|
const location = finding.location;
|
|
5103
|
-
const uri = location.model === "change" ? location.path : location.file;
|
|
5104
|
-
if (uri === void 0) return void 0;
|
|
5105
5106
|
const { position } = location;
|
|
5107
|
+
const file = position?.file ?? (location.model === "change" ? location.path : location.file);
|
|
5108
|
+
if (file === void 0) return void 0;
|
|
5106
5109
|
return [
|
|
5107
5110
|
{
|
|
5108
5111
|
physicalLocation: {
|
|
5109
|
-
artifactLocation: { uri },
|
|
5112
|
+
artifactLocation: { uri: uriReference(file) },
|
|
5110
5113
|
...position === void 0 ? {} : { region: { startLine: position.line, startColumn: position.column } }
|
|
5111
5114
|
}
|
|
5112
5115
|
}
|
|
@@ -5205,4 +5208,4 @@ export {
|
|
|
5205
5208
|
resolveRelativeImport,
|
|
5206
5209
|
writeEnvExample
|
|
5207
5210
|
};
|
|
5208
|
-
//# sourceMappingURL=build-
|
|
5211
|
+
//# sourceMappingURL=build-DNAYWD2B.js.map
|