@maverickcer/env-cap 0.7.5 → 0.7.7
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 +36 -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-33O5SDTC.js} +37 -39
- package/dist/build-33O5SDTC.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-4D67AQFY.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 +20 -13
- 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/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +9 -0
- 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-4D67AQFY.js.map} +0 -0
package/skills/env-cap/SKILL.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: env-cap
|
|
3
|
-
description: Load when a task
|
|
3
|
+
description: env-cap contracts. Load when a task writes or edits an env.schema.ts, calls createEnv, documentEnv or validateEnv, or generates the manifest, docs or reports from them.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# @maverickcer/env-cap
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Each feature declares the environment variables it needs and their format. Your app validates them all in one place at startup, fails fast on a bad value, and reports how they should be rotated before they expire. A feature is a folder or an installable package; the docs also call it a capability.
|
|
9
9
|
|
|
10
10
|
Not for: loading .env files, storing secrets, or a single global env object.
|
|
11
11
|
|
|
@@ -49,17 +49,16 @@ From `examples/team-service/features/prisma/env.schema.ts`.
|
|
|
49
49
|
|
|
50
50
|
## Rules
|
|
51
51
|
|
|
52
|
-
- Write each schema as a static literal in the module that owns it
|
|
53
|
-
- Put `description`, `owner`, `expiresAt` and `category` in `documentEnv`. `createEnv` entries take `default`, `processor`, `validator`, `context`; its options `name` and `source: import.meta.url`.
|
|
54
|
-
- Read a value through its owning contract (`paymentsEnv.STRIPE_KEY`).
|
|
52
|
+
- Write each schema as a static literal in the module that owns it. Schemas are parsed, never executed, so spreads, factories and re-exports stay unresolved.
|
|
53
|
+
- Put `description`, `owner`, `expiresAt`, `refreshInstructions` and `category` in `documentEnv`. `createEnv` entries take `default`, `processor`, `validator`, `context`; its options `name` and `source: import.meta.url`.
|
|
54
|
+
- Read a value through its owning contract (`paymentsEnv.STRIPE_KEY`).
|
|
55
55
|
- Call `validateEnv` once at startup, directly. Run the `generate*` functions only in a build script or CI.
|
|
56
|
-
- Import only from package.json exports; `/build`, `/node` and `/eslint-plugin` are Node-only, never in browser code.
|
|
57
56
|
|
|
58
57
|
## Rely on
|
|
59
58
|
|
|
60
59
|
- Reading a contract before `validateEnv` has run throws `EnvNotReadyError`.
|
|
61
|
-
- Errors never
|
|
62
|
-
- `required: true` in `documentEnv` only documents a variable
|
|
60
|
+
- Errors carry names, never values. Keep values out of your processor and validator messages; spreading a contract reads every value.
|
|
61
|
+
- `required: true` in `documentEnv` only documents a variable; the validator must reject an empty value.
|
|
63
62
|
- `context` is a plain string your application activates, not a security boundary.
|
|
64
63
|
- Two contracts may declare one variable name. Conflicting processor return types and exclusive-group violations are errors; differing processor or validator sources warn, and block under `onIncompatibility: "throw"`.
|
|
65
64
|
|
|
@@ -67,15 +66,15 @@ From `examples/team-service/features/prisma/env.schema.ts`.
|
|
|
67
66
|
|
|
68
67
|
| Instead of | Do this |
|
|
69
68
|
| --- | --- |
|
|
70
|
-
| `createEnv({ ...base })`, or a schema built by a function |
|
|
69
|
+
| `createEnv({ ...base })`, or a schema built by a function | One literal object, passed by the same binding to `createEnv` and `documentEnv`. |
|
|
71
70
|
| `transformer` | `processor`. There is no alias. |
|
|
72
71
|
| A live expiry fetched inside `env.schema.ts` | Keep a static `expiresAt`; pass `liveExpirationDates` to the generator. |
|
|
73
72
|
|
|
74
73
|
## Verify
|
|
75
74
|
|
|
76
|
-
1.
|
|
77
|
-
2. After changing an `env.schema.ts`, update its `documentEnv()` entry and
|
|
78
|
-
3. Check imports against package.json exports
|
|
75
|
+
1. The project's type check and tests pass.
|
|
76
|
+
2. After changing an `env.schema.ts`, update its `documentEnv()` entry and rerun the generate script (`generate:env`, or `node scripts/generate-env.mjs`); it exits 0. Change generated files only through that script, and commit them only if the project does.
|
|
77
|
+
3. Check imports against package.json `exports`.
|
|
79
78
|
|
|
80
79
|
Report any check you could not run, and any assumption you made.
|
|
81
80
|
|
|
@@ -88,4 +87,4 @@ Report any check you could not run, and any assumption you made.
|
|
|
88
87
|
|
|
89
88
|
## Authority
|
|
90
89
|
|
|
91
|
-
Target `@maverickcer/env-cap@0.7.
|
|
90
|
+
Target `@maverickcer/env-cap@0.7.7`. The installed package's exports and type declarations are the API: use only what they declare. Its tests and examples establish its behaviour. When this skill and the code disagree, report the disagreement before acting on either.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @maverickcer/env-cap public API
|
|
2
2
|
|
|
3
|
-
Every export a consumer can import, by entry point, for version 0.7.
|
|
3
|
+
Every export a consumer can import, by entry point, for version 0.7.7. Generated from the package's committed API baselines; the type declarations in the installed package are the authority.
|
|
4
4
|
|
|
5
5
|
## `@maverickcer/env-cap`
|
|
6
6
|
|
package/specs/architecture.md
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
# Architecture
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
destination those decisions arrived at, not the argument for them. For the product overview and
|
|
3
|
+
This is the canonical current-state description of how `env-cap` is built and which invariants its
|
|
4
|
+
architecture holds. [`decisions/`](decisions/) holds the reasoning trail (the ADRs). This document is
|
|
5
|
+
the destination those decisions arrived at, not the argument for them. For the product overview and
|
|
6
6
|
integration guidance, see [README.md](../README.md) and [GUIDE.md](../GUIDE.md).
|
|
7
7
|
|
|
8
8
|
- [Purpose](#purpose)
|
|
9
9
|
- [Core invariants](#core-invariants)
|
|
10
10
|
- [The entry points](#the-entry-points)
|
|
11
|
-
- [`runtime
|
|
12
|
-
- [`build
|
|
13
|
-
- [`helpers
|
|
11
|
+
- [`runtime/`: define, validate, cache, and expose environment values](#runtime-define-validate-cache-and-expose-environment-values)
|
|
12
|
+
- [`build/`: discover, analyze, link, and generate artifacts](#build-discover-analyze-link-and-generate-artifacts)
|
|
13
|
+
- [`helpers/`: optional processors and validators](#helpers-optional-processors-and-validators)
|
|
14
14
|
- [Documentation is parallel to runtime, not part of runtime state](#documentation-is-parallel-to-runtime-not-part-of-runtime-state)
|
|
15
15
|
- [Data flow](#data-flow)
|
|
16
16
|
- [Module layout](#module-layout)
|
|
@@ -20,11 +20,13 @@ integration guidance, see [README.md](../README.md) and [GUIDE.md](../GUIDE.md).
|
|
|
20
20
|
|
|
21
21
|
`env-cap` treats an application's environment configuration as a set of capability-owned contracts,
|
|
22
22
|
not as loose strings read off `process.env`. It does not perform secret storage, rotation, or
|
|
23
|
-
retrieval itself
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
23
|
+
retrieval itself.
|
|
24
|
+
|
|
25
|
+
- A capability declares the environment variables it depends on (`createEnv()`). Optionally, it
|
|
26
|
+
also declares the documentation metadata that describes them (`documentEnv()`).
|
|
27
|
+
- At startup, `env-cap` validates those declarations against real values.
|
|
28
|
+
- Separately, at build time, it discovers every declared contract across a project. From those it
|
|
29
|
+
produces manifests, documentation, ownership reports, and a canonical Evidence Model.
|
|
28
30
|
|
|
29
31
|
The architecture keeps two concerns from collapsing into one:
|
|
30
32
|
|
|
@@ -35,86 +37,95 @@ build-time -> project-wide discovery, documentation, and ownership visib
|
|
|
35
37
|
|
|
36
38
|
The runtime never discovers anything; it only validates what a generated manifest already told it to
|
|
37
39
|
expect. Build-time tooling never runs at startup; it only ever runs as an explicit CI/npm-script step.
|
|
38
|
-
Neither one substitutes for the other, and a consumer can use either independently
|
|
39
|
-
|
|
40
|
-
validation
|
|
40
|
+
Neither one substitutes for the other, and a consumer can use either independently:
|
|
41
|
+
|
|
42
|
+
- validation with no generated artifacts at all (a hand-written manifest works);
|
|
43
|
+
- discovery/documentation with no runtime validation (a project that only wants the ownership
|
|
44
|
+
report).
|
|
41
45
|
|
|
42
46
|
## Core invariants
|
|
43
47
|
|
|
44
|
-
These are the
|
|
48
|
+
These are the invariants the rest of the design exists to uphold. Each links to the section that
|
|
45
49
|
describes its mechanics.
|
|
46
50
|
|
|
47
51
|
### Runtime and build-time are strictly separate
|
|
48
52
|
|
|
49
53
|
The runtime (`.`, `./helpers`) has zero npm dependencies, never touches the filesystem, never
|
|
50
54
|
discovers files, and never imports Node-specific APIs. `./build` is Node-only developer tooling,
|
|
51
|
-
never meant to reach a browser bundle
|
|
55
|
+
never meant to reach a browser bundle. Bundle-size and tree-shaking tests fail if runtime consumers
|
|
52
56
|
accidentally receive build tooling or unrelated helper code. See
|
|
53
|
-
[`runtime/`](#runtime
|
|
54
|
-
[`build/`](#build
|
|
57
|
+
[`runtime/`](#runtime-define-validate-cache-and-expose-environment-values) and
|
|
58
|
+
[`build/`](#build-discover-analyze-link-and-generate-artifacts) below, and
|
|
55
59
|
[ADR 0004](decisions/0004-no-client-server-package-split.md).
|
|
56
60
|
|
|
57
61
|
### The build tool never imports or executes a schema file
|
|
58
62
|
|
|
59
|
-
Discovery is AST analysis only (`build/parse.ts`, the TypeScript compiler API)
|
|
63
|
+
Discovery is AST analysis only (`build/parse.ts`, the TypeScript compiler API). A schema file's
|
|
60
64
|
`createEnv()`/`documentEnv()` calls are read as syntax, never imported or run. This preserves the
|
|
61
|
-
safety boundary required for CI environments and large monorepos
|
|
62
|
-
file can't execute code
|
|
63
|
-
[`build/`](#build
|
|
65
|
+
safety boundary required for CI environments and large monorepos. A malicious or merely broken
|
|
66
|
+
schema file can't execute code by being discovered. See
|
|
67
|
+
[`build/`](#build-discover-analyze-link-and-generate-artifacts) and
|
|
64
68
|
[ADR 0002](decisions/0002-static-analysis-never-execution.md).
|
|
65
69
|
|
|
66
70
|
### `./build` does not acquire filesystem access implicitly
|
|
67
71
|
|
|
68
|
-
`./build` never imports `node:fs` itself
|
|
72
|
+
`./build` never imports `node:fs` itself. Every public options object requires a caller-supplied
|
|
69
73
|
`BuildFileSystem` capability. The `env-cap` CLI (`src/cli/`) is the executable boundary that
|
|
70
|
-
constructs the real `node:fs/promises` adapter and hands it in
|
|
74
|
+
constructs the real `node:fs/promises` adapter and hands it in. A consumer running the generators
|
|
71
75
|
from their own Node script imports that same adapter from `@maverickcer/env-cap/node`. This is the
|
|
72
|
-
same discipline `repo-contract`'s ADR-0011 established for `spawn`/`env
|
|
73
|
-
not implicitly acquire a
|
|
76
|
+
same discipline `repo-contract`'s ADR-0011 established for `spawn`/`env`. A library surface should
|
|
77
|
+
not implicitly acquire a privileged ambient capability that a caller did not explicitly provide. See
|
|
74
78
|
[ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md).
|
|
75
79
|
|
|
76
80
|
### Documentation is inert at runtime
|
|
77
81
|
|
|
78
|
-
`documentEnv()` is a source-level marker the build system discovers through AST analysis
|
|
82
|
+
`documentEnv()` is a source-level marker the build system discovers through AST analysis. It stores
|
|
79
83
|
nothing in memory and adds no fields to a runtime contract. `createEnv()`'s runtime contracts and
|
|
80
|
-
`documentEnv()`'s documentation metadata are separate concerns
|
|
81
|
-
one pipeline. See
|
|
84
|
+
`documentEnv()`'s documentation metadata are separate concerns. They happen to share a source file,
|
|
85
|
+
but they are not one pipeline. See
|
|
82
86
|
[Documentation is parallel to runtime, not part of runtime state](#documentation-is-parallel-to-runtime-not-part-of-runtime-state).
|
|
83
87
|
|
|
84
88
|
### Runtime contracts are self-redacting
|
|
85
89
|
|
|
86
|
-
A contract's own `toString`/`console.log`/JSON representation never exposes resolved values
|
|
90
|
+
A contract's own `toString`/`console.log`/JSON representation never exposes resolved values.
|
|
87
91
|
`console.log(paymentsEnv)` prints `EnvContract("payments") { 1 variable(s) }`, never the underlying
|
|
88
92
|
secret. Explicit property access (`paymentsEnv.STRIPE_KEY`) remains required to read a value. See
|
|
89
93
|
[ADR 0006](decisions/0006-self-redacting-contracts.md) and [SECURITY.md](../SECURITY.md).
|
|
90
94
|
|
|
91
95
|
### Validation contexts gate participation, nothing else
|
|
92
96
|
|
|
93
|
-
A variable with no `context` participates in every run
|
|
94
|
-
when `activeContexts` contains that exact string
|
|
95
|
-
signals
|
|
96
|
-
[Validation context invariants](#validation-context-invariants)
|
|
97
|
-
[ADR 0022](decisions/0022-validation-contexts.md).
|
|
97
|
+
A variable with no `context` participates in every run. A variable with a `context` participates
|
|
98
|
+
only when `activeContexts` contains that exact string. There is no prefix matching and no inference
|
|
99
|
+
from ambient signals. A context has no effect on `EnvContract`'s TypeScript shape and carries no
|
|
100
|
+
authorization/bundling meaning. See [Validation context invariants](#validation-context-invariants)
|
|
101
|
+
below and [ADR 0022](decisions/0022-validation-contexts.md).
|
|
98
102
|
|
|
99
103
|
### Manifest compatibility is the one blocking category
|
|
100
104
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
105
|
+
Only manifest compatibility/exclusive-group issues ever block a generation run
|
|
106
|
+
(`EnvProjectGenerationError`, nothing written). A run can produce three finding categories, and only
|
|
107
|
+
the first one blocks:
|
|
108
|
+
|
|
109
|
+
1. manifest compatibility/exclusive-group issues;
|
|
110
|
+
2. documentation completeness;
|
|
111
|
+
3. dependency ownership.
|
|
112
|
+
|
|
113
|
+
Documentation and ownership issues are heuristic signals with real, common false-positive causes.
|
|
114
|
+
They're recorded as `Finding`s on the persisted Evidence Model instead. A consumer can gate on them
|
|
115
|
+
explicitly if they want that enforced. See [Data flow](#data-flow) and
|
|
116
|
+
[ADR 0038](decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md).
|
|
107
117
|
|
|
108
118
|
### The Evidence Model is always computed, independent of what's requested
|
|
109
119
|
|
|
110
|
-
`computeArtifacts()` always builds the full `EvidenceModel
|
|
111
|
-
flags only control which artifacts are additionally _written
|
|
112
|
-
model is computed. See [Data flow](#data-flow) and
|
|
120
|
+
`computeArtifacts()` always builds the full `EvidenceModel`. The
|
|
121
|
+
manifest/docs/ownership/`--evidence` flags only control which artifacts are additionally _written
|
|
122
|
+
to disk_, never whether the underlying model is computed. See [Data flow](#data-flow) and
|
|
113
123
|
[ADR 0038](decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md).
|
|
114
124
|
|
|
115
125
|
## The entry points
|
|
116
126
|
|
|
117
|
-
`package.json` `exports` is the authoritative list
|
|
127
|
+
`package.json` `exports` is the authoritative list. This section is the map of what each one is
|
|
128
|
+
for, and TypeDoc generates the reference for each.
|
|
118
129
|
|
|
119
130
|
```text
|
|
120
131
|
|
|
@@ -135,40 +146,46 @@ include the implementation of the others.
|
|
|
135
146
|
`build`, `eslint-plugin`, and `runtime` contain their own implementation with
|
|
136
147
|
zero cross-folder dependency, including internal utilities.
|
|
137
148
|
`globToRegExp()`, for example, is needed by both `build/discover.ts` and
|
|
138
|
-
`eslint-plugin/no-raw-process-env.ts
|
|
139
|
-
internal module both would depend on
|
|
140
|
-
|
|
141
|
-
considered").
|
|
142
|
-
|
|
143
|
-
`
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
`
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
149
|
+
`eslint-plugin/no-raw-process-env.ts`. Each directory owns its own copy
|
|
150
|
+
rather than sharing an internal module both would depend on:
|
|
151
|
+
`build/glob.ts` and `eslint-plugin/glob.ts` (see ADR 0017's "Alternatives
|
|
152
|
+
considered").
|
|
153
|
+
|
|
154
|
+
`helpers` and `evidence` each have exactly one cross-folder import, and both
|
|
155
|
+
are structural, not incidental:
|
|
156
|
+
|
|
157
|
+
- `helpers`' `processors.ts`/`validators.ts` import `Processor`/`Validator`
|
|
158
|
+
as types (erased at compile time) from `runtime/index.ts`. A helper's whole
|
|
159
|
+
job is producing a value that type-checks as the exact shape `createEnv()`
|
|
160
|
+
expects. That contract can't be expressed without referencing runtime's
|
|
161
|
+
own type.
|
|
162
|
+
- `evidence/define-projection.ts` imports `EvidenceModel` as a type (also
|
|
163
|
+
erased at compile time) from `build/evidence-model.ts`, for the same
|
|
164
|
+
reason. A projector's whole job is a function _of_ that shape, which can't
|
|
165
|
+
be named without referencing it (see ADR 0031).
|
|
166
|
+
|
|
167
|
+
Neither edge is an oversight. It's what lets any of these five directories
|
|
168
|
+
move to its own repository independent of the others. `helpers`/`evidence`
|
|
169
|
+
would gain `env-cap`/`env-cap-build` as an ordinary dependency, the way any
|
|
170
|
+
package depending on another package's published types would.
|
|
156
171
|
|
|
157
172
|
`src/cli/` (the `env-cap` bin, not a `package.json#exports` subpath) has the
|
|
158
|
-
same kind of real, intentional dependency on `build
|
|
173
|
+
same kind of real, intentional dependency on `build`. It imports
|
|
159
174
|
`@maverickcer/env-cap/build`'s public surface (`src/build/index.ts`)
|
|
160
|
-
directly, never an internal `build/*.ts` file
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
A split-out `cli` package would
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
This separation is enforced through automated checks
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
`
|
|
175
|
+
directly, never an internal `build/*.ts` file. Generating artifacts from the
|
|
176
|
+
command line requires the same engine `./build` exports. It is also the one
|
|
177
|
+
place `node:fs` is acquired to build the concrete `BuildFileSystem` adapter
|
|
178
|
+
`./build` requires (see [ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
|
|
179
|
+
A split-out `cli` package would declare `env-cap-build` as a normal npm
|
|
180
|
+
dependency.
|
|
181
|
+
|
|
182
|
+
This separation is enforced through automated checks:
|
|
183
|
+
|
|
184
|
+
- The tree-shaking tests and bundle-size checks fail if runtime consumers
|
|
185
|
+
accidentally receive build tooling or unrelated helper code.
|
|
186
|
+
- The `AmbientCapabilities` check fails if a published library entrypoint's
|
|
187
|
+
packed output reaches for `node:fs` outside the
|
|
188
|
+
CLI/`./node`/`./eslint-plugin` exceptions.
|
|
172
189
|
|
|
173
190
|
```mermaid
|
|
174
191
|
flowchart TB
|
|
@@ -213,13 +230,13 @@ flowchart TB
|
|
|
213
230
|
```
|
|
214
231
|
|
|
215
232
|
`build`, `eslint-plugin`, and `runtime` have no edges between them above
|
|
216
|
-
because none exist
|
|
233
|
+
because none exist. Each owns its own copy of shared internals (e.g.
|
|
217
234
|
`glob.ts`) rather than importing from another entry point. `helpers`' and
|
|
218
235
|
`evidence`'s single edges are both type-only and erased at compile time.
|
|
219
236
|
This is what the tree-shaking and bundle-size tests in the previous
|
|
220
237
|
paragraph actually verify.
|
|
221
238
|
|
|
222
|
-
## `runtime
|
|
239
|
+
## `runtime/`: define, validate, cache, and expose environment values
|
|
223
240
|
|
|
224
241
|
The runtime package contains only the functionality required while an
|
|
225
242
|
application is running.
|
|
@@ -236,19 +253,20 @@ environment values into validated application configuration.
|
|
|
236
253
|
|
|
237
254
|
`createEnv()` (`runtime/create.ts`) creates a feature-owned environment
|
|
238
255
|
contract. `validateEnv()` (`runtime/validate.ts`) executes every registered
|
|
239
|
-
contract's processing pipeline against the provided environment values
|
|
240
|
-
caches successful results through `runtime/cache.ts`.
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
256
|
+
contract's processing pipeline against the provided environment values. It
|
|
257
|
+
caches successful results through `runtime/cache.ts`.
|
|
258
|
+
|
|
259
|
+
Before running that pipeline for a given variable, `validateEnv()` first
|
|
260
|
+
checks whether the variable's `context` (if any) is in the run's
|
|
261
|
+
`activeContexts`. A variable that doesn't match is skipped entirely (no
|
|
262
|
+
default/processor/validator runs). It stays in its not-ready state, exactly
|
|
263
|
+
as if this run had never happened for it.
|
|
246
264
|
|
|
247
265
|
### Validation context invariants
|
|
248
266
|
|
|
249
267
|
A **validation context** is an application-defined string a variable may
|
|
250
268
|
declare (`context`) and a validation run may activate (`activeContexts`).
|
|
251
|
-
|
|
269
|
+
These strings are never interpreted, detected, or inferred by env-cap itself. The
|
|
252
270
|
application always computes and passes `activeContexts` explicitly. The
|
|
253
271
|
following invariants are load-bearing; none should be relaxed without a new
|
|
254
272
|
ADR (see [ADR 0022](decisions/0022-validation-contexts.md)):
|
|
@@ -261,14 +279,14 @@ ADR (see [ADR 0022](decisions/0022-validation-contexts.md)):
|
|
|
261
279
|
`activeContexts` from any ambient signal (`window`, `NODE_ENV`, a
|
|
262
280
|
bundler `define`, etc.). The application always computes and passes it
|
|
263
281
|
explicitly.
|
|
264
|
-
3. **Not cache identity.** `validateEnv()` stays one-shot per process
|
|
282
|
+
3. **Not cache identity.** `validateEnv()` stays one-shot per process. A
|
|
265
283
|
second call while already `"ready"` returns the first call's result
|
|
266
284
|
outright, without inspecting the second call's `activeContexts`. There
|
|
267
285
|
is no per-context cache dimension.
|
|
268
286
|
4. **Not a type-level concept.** Validation contexts affect participation
|
|
269
|
-
at `validateEnv()` time only
|
|
287
|
+
at `validateEnv()` time only. They do not alter `EnvContract`'s
|
|
270
288
|
TypeScript shape, `InferEnvValue`, or any generated type. Every schema
|
|
271
|
-
key remains a property of `EnvContract<S>` regardless of `context
|
|
289
|
+
key remains a property of `EnvContract<S>` regardless of `context`. An
|
|
272
290
|
out-of-context key throws `EnvNotReadyError` at access time, exactly
|
|
273
291
|
like any value read before `validateEnv()` has run.
|
|
274
292
|
5. **Not authorization.** Validation contexts are not an authentication,
|
|
@@ -276,7 +294,7 @@ ADR (see [ADR 0022](decisions/0022-validation-contexts.md)):
|
|
|
276
294
|
participation only, never who may read a resolved value.
|
|
277
295
|
6. **Not a bundling/security boundary.** Separate discovery/manifests (ADR 0004) remain the real mechanism for keeping server-only source out of
|
|
278
296
|
client-bound code. `activeContexts` filtering happens after the schema
|
|
279
|
-
is already wherever it's going to be
|
|
297
|
+
is already wherever it's going to be. It does not remove a variable's
|
|
280
298
|
definition (or its `default` value) from a bundle that imports it.
|
|
281
299
|
|
|
282
300
|
`runtime/registry.ts` maintains the internal relationship between created
|
|
@@ -297,7 +315,7 @@ The runtime package intentionally:
|
|
|
297
315
|
This keeps the runtime small, portable, and safe to include in browser,
|
|
298
316
|
edge, serverless, and Node environments.
|
|
299
317
|
|
|
300
|
-
## `build
|
|
318
|
+
## `build/`: discover, analyze, link, and generate artifacts
|
|
301
319
|
|
|
302
320
|
The build package contains developer tooling only. It exists to analyze a
|
|
303
321
|
project's environment schemas and generate artifacts; it is not part of an
|
|
@@ -312,13 +330,15 @@ The build pipeline is responsible for:
|
|
|
312
330
|
- detecting compatibility concerns (`build/compatibility.ts`,
|
|
313
331
|
`build/exclusive-group.ts`)
|
|
314
332
|
- scanning source files for variable access and deriving ownership findings
|
|
315
|
-
(`build/scan-dependencies.ts`, `build/dependency-graph.ts`)
|
|
316
|
-
purely-syntactic, per-file walk
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
333
|
+
(`build/scan-dependencies.ts`, `build/dependency-graph.ts`). This is a
|
|
334
|
+
purely-syntactic, per-file walk (see ADR 0039):
|
|
335
|
+
- it follows `contract.KEY` member access, object-destructuring, and one
|
|
336
|
+
level of file-unique `const` aliasing;
|
|
337
|
+
- it records every shape it can't follow (a rest/nested/computed-key
|
|
338
|
+
binding, a reassigned alias, the contract passed around as a value) as
|
|
339
|
+
an explicit `escape`;
|
|
340
|
+
- an `escape` widens a variable to `indeterminate`, never a false
|
|
341
|
+
`unconsumed`.
|
|
322
342
|
- resolving live expiration overrides for documentation (`build/live-expirations.ts`)
|
|
323
343
|
- generating output artifacts (`build/manifest.ts`, `build/docs.ts`,
|
|
324
344
|
`build/env-example.ts`, `build/usage-report.ts`)
|
|
@@ -340,11 +360,11 @@ See
|
|
|
340
360
|
for the reasoning behind AST analysis instead of dynamic imports.
|
|
341
361
|
|
|
342
362
|
Every public options object in `build/index.ts` also carries a required
|
|
343
|
-
`fs: BuildFileSystem` field
|
|
363
|
+
`fs: BuildFileSystem` field. `./build` itself never imports `node:fs`; see
|
|
344
364
|
[ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md) and the
|
|
345
365
|
[Core invariants](#core-invariants) above.
|
|
346
366
|
|
|
347
|
-
## `helpers
|
|
367
|
+
## `helpers/`: optional processors and validators
|
|
348
368
|
|
|
349
369
|
The helpers package provides reusable implementations of the
|
|
350
370
|
`Processor` and `Validator` function types defined by
|
|
@@ -472,26 +492,31 @@ flowchart TB
|
|
|
472
492
|
|
|
473
493
|
`generateEnvArtifacts()` and `checkEnvArtifacts()` share one
|
|
474
494
|
`computeArtifacts()` pass (discovery, parsing, linking, and blocking-finding
|
|
475
|
-
checks)
|
|
495
|
+
checks). They only diverge at the last step: write, or compare-and-report
|
|
496
|
+
(see
|
|
476
497
|
[ADR 0011](decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md)
|
|
477
498
|
and [ADR 0016](decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
|
|
499
|
+
|
|
478
500
|
Manifest, docs, `.env.example`, the ownership report, and the persisted
|
|
479
501
|
evidence artifact are each optional per `generateEnvArtifacts()`/
|
|
480
|
-
`checkEnvArtifacts()` call (`manifest`/`docs`/`usage`/`evidence` options)
|
|
481
|
-
only appear above when requested.
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
`
|
|
488
|
-
|
|
489
|
-
|
|
502
|
+
`checkEnvArtifacts()` call (`manifest`/`docs`/`usage`/`evidence` options).
|
|
503
|
+
They only appear above when requested.
|
|
504
|
+
|
|
505
|
+
- The `env-cap` CLI only exposes `--location`/`--evidence` of those four.
|
|
506
|
+
Docs/`.env.example`/the ownership report have no CLI flag at all (ADR
|
|
507
|
+
0046). They have no verified runtime consumer, so generating them is
|
|
508
|
+
application code calling `generateDocumentation()`/
|
|
509
|
+
`generateUsageReport()` directly, not a CLI concern.
|
|
510
|
+
- The exception is the `EvidenceModel` backing the persisted evidence
|
|
511
|
+
artifact. `computeArtifacts()` always builds it, regardless of whether
|
|
512
|
+
`evidence`/`--evidence` was requested. That option only controls whether
|
|
513
|
+
it's also written to disk (ADR 0038).
|
|
514
|
+
|
|
490
515
|
Manifest compatibility/exclusive-group issues are the one category that still
|
|
491
|
-
blocks (`CHECKS`, ADR 0009)
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
`env-cap --json` with.
|
|
516
|
+
blocks (`CHECKS`, ADR 0009). A documentation or ownership issue never does.
|
|
517
|
+
Both are surfaced as `Finding`s on the evidence artifact instead. A team can
|
|
518
|
+
gate on them in its own CI step if it wants that enforced. The GitHub Action
|
|
519
|
+
wraps whichever mode a workflow invokes `env-cap --json` with.
|
|
495
520
|
|
|
496
521
|
### 1. Author time
|
|
497
522
|
|
|
@@ -546,8 +571,8 @@ Validation happens once for the process lifetime.
|
|
|
546
571
|
Each contract, per variable:
|
|
547
572
|
|
|
548
573
|
1. checks whether the variable's `context` matches this run's
|
|
549
|
-
`activeContexts
|
|
550
|
-
moves to the next variable (see "Validation context invariants" above)
|
|
574
|
+
`activeContexts`. If not, it skips every remaining step entirely and
|
|
575
|
+
moves to the next variable (see "Validation context invariants" above).
|
|
551
576
|
2. reads its raw value
|
|
552
577
|
3. applies its default
|
|
553
578
|
4. runs its processor
|
|
@@ -586,10 +611,10 @@ contract.
|
|
|
586
611
|
|
|
587
612
|
The `src/` tree mirrors the entry points described above:
|
|
588
613
|
`runtime/`, `build/` (and `build/resolution/`), `helpers/`, `evidence/`,
|
|
589
|
-
`eslint-plugin/`, plus `cli/` (the `env-cap` bin) and `node/`
|
|
590
|
-
`@maverickcer/env-cap/node` executable-context entry
|
|
614
|
+
`eslint-plugin/`, plus `cli/` (the `env-cap` bin) and `node/`. `node/` is the
|
|
615
|
+
`@maverickcer/env-cap/node` executable-context entry. It ships the CLI's
|
|
591
616
|
concrete `BuildFileSystem` adapter as a value for a consumer's own build
|
|
592
|
-
script
|
|
617
|
+
script. See [The entry points](#the-entry-points) for the
|
|
593
618
|
dependency rules between them.
|
|
594
619
|
|
|
595
620
|
## Architectural decisions
|
|
@@ -5,6 +5,15 @@
|
|
|
5
5
|
Accepted. Implemented in `src/build/typescript.ts`. Supersedes the TypeScript 7 paragraph of
|
|
6
6
|
[ADR 0047](0047-supported-toolchain-node-22-and-typescript-5-6.md).
|
|
7
7
|
|
|
8
|
+
## Amendment
|
|
9
|
+
|
|
10
|
+
`bundleDependencies` lists `@typescript/typescript6` only. npm also bundles the dependencies of a
|
|
11
|
+
bundled package, so its `@typescript/old` payload still ships in the tarball. Listing
|
|
12
|
+
`@typescript/old` by name without a matching `dependencies` entry made npm add
|
|
13
|
+
`"@typescript/old": "*"` to the published manifest. The manifest then no longer matched the
|
|
14
|
+
tarball's package.json, which Socket reports as manifest confusion.
|
|
15
|
+
`test/build/typescript-bundled.test.ts` pins both facts.
|
|
16
|
+
|
|
8
17
|
## Context
|
|
9
18
|
|
|
10
19
|
The build-time scanner (`src/build/parse.ts`, `scan-dependencies.ts`, `literal-eval.ts`,
|