@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/ADOPTION.md
CHANGED
|
@@ -4,7 +4,7 @@ Adopting `env-cap` costs a build step and a declaration per variable; it needs N
|
|
|
4
4
|
|
|
5
5
|
## What problem this solves
|
|
6
6
|
|
|
7
|
-
Validation libraries answer one question: is this value well-formed? They do not say which team owns `STRIPE_WEBHOOK_SECRET`, what breaks if it disappears, or whether anything still reads it. `env-cap` lets each
|
|
7
|
+
Validation libraries answer one question: is this value well-formed? They do not say which team owns `STRIPE_WEBHOOK_SECRET`, what breaks if it disappears, or whether anything still reads it. `env-cap` lets each feature or package declare the variables it reads in a contract. A build-time analysis then reports owners, expiry dates and declared variables that nothing reads.
|
|
8
8
|
|
|
9
9
|
[`specs/migrations/README.md`](specs/migrations/README.md) compares it with each tool you may have, and says when not to switch.
|
|
10
10
|
|
|
@@ -22,7 +22,7 @@ Validation libraries answer one question: is this value well-formed? They do not
|
|
|
22
22
|
## What it needs
|
|
23
23
|
|
|
24
24
|
- Node.js `>=22`. CI tests 22 and 24 in blocking jobs.
|
|
25
|
-
- npm. pnpm, Yarn 1 and Yarn Berry are tested only for installing the tarball and importing every entry.
|
|
25
|
+
- npm. pnpm, Yarn 1 and Yarn Berry are tested only for installing the tarball and importing every entry. `required` waits for that job (`package-managers`), so a failure blocks a merge.
|
|
26
26
|
- TypeScript `moduleResolution` set to `node16`, `nodenext` or `bundler` if you type-check against the subpath exports.
|
|
27
27
|
- Your own TypeScript is optional. The build entry uses it when it is version 5 or 6, and the bundled TypeScript 6 otherwise.
|
|
28
28
|
- Schemas written as static object literals. A schema built by a function, or a spread at the top of a schema object, produces a parse warning. A spread nested inside a variable's definition or its `documentEnv()` entry is skipped without one. Nothing is guessed.
|
|
@@ -66,13 +66,13 @@ Installing `@maverickcer/env-cap` installs 1 package directly, and whatever it d
|
|
|
66
66
|
|
|
67
67
|
<!-- ipc:end dependencies -->
|
|
68
68
|
|
|
69
|
-
**Supply chain.** A merge to `main` requires a pull request, resolved review threads, and the `contract` and `
|
|
69
|
+
**Supply chain.** A merge to `main` requires a pull request, resolved review threads, and the `contract`, `lint` and `required` checks. The ruleset enforces that. The `BranchProtection` check fails if the ruleset stops requiring `contract` or `required`, or stops requiring resolved threads; it does not check `lint`. Admins can bypass, and no approving review is required. These gates run in the `contract` job:
|
|
70
70
|
|
|
71
71
|
- Typecheck, lint, tests with coverage floors, zero surviving mutants, and size budgets.
|
|
72
72
|
- Production dependency licences, `npm audit` and Socket alerts, each with a reviewed record when accepted.
|
|
73
73
|
- An install-and-import of the packed tarball, for every entry except `./eslint-plugin`.
|
|
74
74
|
|
|
75
|
-
Releases publish from CI over npm OIDC with a provenance attestation, so you can check that a version was built by this repository's workflow. The Bun and Deno runs, the examples and the package-manager smoke test run in CI
|
|
75
|
+
Releases publish from CI over npm OIDC with a provenance attestation, so you can check that a version was built by this repository's workflow. The Bun and Deno runs, the examples and the package-manager smoke test run in CI. The required `required` check fails when any of them fails.
|
|
76
76
|
|
|
77
77
|
## Versioning, stability, and long-term support
|
|
78
78
|
|
|
@@ -98,13 +98,13 @@ The install includes the bundled TypeScript 6 compiler. No check measures its si
|
|
|
98
98
|
|
|
99
99
|
## Architectural decisions worth knowing before you adopt
|
|
100
100
|
|
|
101
|
-
| Decision | What it means for you
|
|
102
|
-
| -------------------------------------------- |
|
|
103
|
-
| No global `env` object | Each
|
|
104
|
-
| One runtime, no `/client` or `/server` split | The same runtime entry serves server and browser code. Browser use is tested in a Web-globals VM, not a real browser
|
|
105
|
-
| Warn, not throw, by default | No documentation or ownership finding fails a run until a team passes a `--strict*` flag
|
|
106
|
-
| Exclusive-group violations are always errors | Two active contracts in one exclusive group fail the build, whatever the flags
|
|
107
|
-
| `--json` output is versioned and additive | New fields can appear in any release. A removed or
|
|
101
|
+
| Decision | What it means for you | ADR |
|
|
102
|
+
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
103
|
+
| No global `env` object | Each feature reads only the contract it owns | [0003](specs/decisions/0003-no-global-env-object.md) |
|
|
104
|
+
| One runtime, no `/client` or `/server` split | The same runtime entry serves server and browser code. Browser use is tested in a Web-globals VM, not a real browser | [0004](specs/decisions/0004-no-client-server-package-split.md) |
|
|
105
|
+
| Warn, not throw, by default | No documentation or ownership finding fails a run until a team passes a `--strict*` flag | [0005](specs/decisions/0005-warn-not-throw-by-default.md), [0044](specs/decisions/0044-strict-escalates-every-warning-family.md) |
|
|
106
|
+
| Exclusive-group violations are always errors | Two active contracts in one exclusive group fail the build, whatever the flags | [0009](specs/decisions/0009-exclusive-groups-are-always-errors.md) |
|
|
107
|
+
| `--json` output is versioned and additive | New fields can appear in any release. A removed, retyped or newly optional field must bump `schemaVersion`; `test/build/schema-version-bump.test.ts` fails otherwise | [0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md) |
|
|
108
108
|
|
|
109
109
|
The full list is in [`specs/architecture.md`](specs/architecture.md).
|
|
110
110
|
|
|
@@ -115,7 +115,7 @@ The full list is in [`specs/architecture.md`](specs/architecture.md).
|
|
|
115
115
|
| Raw `process.env` | [from-process-env.md](specs/migrations/from-process-env.md) | The lowest-friction start; adds validation and ownership where there was none |
|
|
116
116
|
| `dotenv` | [from-dotenv.md](specs/migrations/from-dotenv.md) | `dotenv` still loads `.env` files; `env-cap` validates and documents what is in them |
|
|
117
117
|
| `zod`-based validation | [from-zod.md](specs/migrations/from-zod.md) | Keep Zod; adopt `env-cap` only if ownership, not validation, is the pain |
|
|
118
|
-
| `envalid` | [from-envalid.md](specs/migrations/from-envalid.md) | Similar validation; the difference is per-
|
|
118
|
+
| `envalid` | [from-envalid.md](specs/migrations/from-envalid.md) | Similar validation; the difference is per-feature ownership |
|
|
119
119
|
| `t3-env` | [from-t3-env.md](specs/migrations/from-t3-env.md) | Both are type-safe; `t3-env` centralizes and `env-cap` does not |
|
|
120
120
|
| A hand-rolled centralized schema | [from-centralized-schema.md](specs/migrations/from-centralized-schema.md) | The closest fit for what this package changes |
|
|
121
121
|
|
package/AGENTS.md
CHANGED
|
@@ -1,114 +1,77 @@
|
|
|
1
1
|
# AGENTS.md
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
`env-cap
|
|
6
|
-
|
|
7
|
-
instead if your tooling supports it; this file is a self-contained distillation for
|
|
8
|
-
agents that don't.
|
|
3
|
+
Rules for coding agents working with `env-cap`, both in an application that uses it and in this
|
|
4
|
+
repository's own source. If your tooling loads skill files, load
|
|
5
|
+
[`skills/env-cap/SKILL.md`](skills/env-cap/SKILL.md) instead: it is the fuller version of the
|
|
6
|
+
application rules, generated from the package.
|
|
9
7
|
|
|
10
8
|
## What this package is
|
|
11
9
|
|
|
12
|
-
`env-cap
|
|
13
|
-
|
|
14
|
-
and
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
3.
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
- Spreading or `Object.entries()`-ing a whole contract "just to inspect it" —
|
|
78
|
-
`console.log(paymentsEnv)` is safe by design, but `{...paymentsEnv}` triggers every
|
|
79
|
-
getter and produces a plain object with every real value.
|
|
80
|
-
- Manually constructing a contract collection when a generated manifest is available —
|
|
81
|
-
regenerate it instead: run the project's `generate:env` script if one exists, or call
|
|
82
|
-
`generateEnvManifest({ location: "src/generated/env.manifest.ts" })` from
|
|
83
|
-
`@maverickcer/env-cap/build`, or run `npx env-cap --location
|
|
84
|
-
src/generated/env.manifest.ts` from the CLI. Never hand-assemble the collection it
|
|
85
|
-
produces.
|
|
86
|
-
- Validation managers, service locators, providers, registries, or other initialization
|
|
87
|
-
frameworks around `validateEnv()` — call it directly from the application's existing
|
|
88
|
-
startup path.
|
|
89
|
-
|
|
90
|
-
## Migrating an existing app onto env-cap
|
|
91
|
-
|
|
92
|
-
- Generated manifests are meant to be consumed by `validateEnv()` at runtime, and
|
|
93
|
-
generated artifacts (manifest, docs, `.env.example`, ownership report) are meant to be
|
|
94
|
-
consumed by tooling — prefer them over anything manually maintained, and treat them as
|
|
95
|
-
the source of truth.
|
|
96
|
-
- To generate a manifest: check for an existing `generate:env` (or similarly named) npm
|
|
97
|
-
script first and run that. If none exists, either call
|
|
98
|
-
`generateEnvManifest({ location: "src/generated/env.manifest.ts" })` (import from
|
|
99
|
-
`@maverickcer/env-cap/build`) from a build script, or run the CLI directly —
|
|
100
|
-
`npx env-cap --location src/generated/env.manifest.ts` (add `--evidence`, `--strict`,
|
|
101
|
-
etc. as needed; see the Public API map and `skills/env-cap/SKILL.md` for the full option
|
|
102
|
-
set). `--docs`/`--ownership`/`--env-example` are not CLI flags — the documentation
|
|
103
|
-
catalog, `.env.example`, and dependency-ownership report have no runtime consumer, so
|
|
104
|
-
generating them is a `generateEnvArtifacts()`/`generateDocumentation()`/
|
|
105
|
-
`generateUsageReport()` call from a build script instead (see ADR 0046). Commit the
|
|
106
|
-
generated file only if the project already commits generated artifacts; otherwise wire
|
|
107
|
-
the command into CI.
|
|
108
|
-
- Prefer migrations that are small, reviewable PRs covering one capability at a time,
|
|
109
|
-
preserve existing validation and runtime behavior, and avoid new infrastructure unless
|
|
110
|
-
it's actually required. See [`specs/migrations/`](specs/migrations/) for guide-by-guide
|
|
111
|
-
detail.
|
|
10
|
+
In `env-cap`, each feature (a folder or an installable package; the docs also call it a
|
|
11
|
+
capability) declares its environment variables in a **contract**: a static schema object passed to
|
|
12
|
+
`createEnv()` and `documentEnv()`. The application validates every contract once at startup. A build
|
|
13
|
+
step reads the contracts as source and writes the manifest, docs, `.env.example` and ownership
|
|
14
|
+
report. Values are always read through the contract that owns them.
|
|
15
|
+
|
|
16
|
+
## Contract rules
|
|
17
|
+
|
|
18
|
+
1. **Schemas are static literals, read as source.** The build entry (`@maverickcer/env-cap/build`)
|
|
19
|
+
parses `env.schema.ts` files as TypeScript syntax trees and never runs them. Only literal
|
|
20
|
+
expressions resolve. A spread, a factory call or a re-export resolves as "unknown" and surfaces
|
|
21
|
+
as a warning. So declare each schema as a literal object in the module that owns it, and pass
|
|
22
|
+
that one binding to `createEnv()` and `documentEnv()`.
|
|
23
|
+
2. **Each contract belongs to the module that declares it.** That module exports it (`paymentsEnv`,
|
|
24
|
+
`databaseEnv`), and code reads `paymentsEnv.STRIPE_KEY` from it. Keep contracts separate; a
|
|
25
|
+
merged or global env object defeats ownership.
|
|
26
|
+
3. **`createEnv()` holds runtime fields; `documentEnv()` holds documentation.** `createEnv(schema,
|
|
27
|
+
options)` reads only `default`, `processor`, `validator` and `context`. `documentEnv(schema, docs)`
|
|
28
|
+
is an inert second call over the same object: it returns `void` and exists only as a build-time
|
|
29
|
+
marker. So `description`, `owner` and `expiresAt` go in `documentEnv()`. The field is `processor`;
|
|
30
|
+
the old name `transformer` has no alias.
|
|
31
|
+
4. **Import from the public entry points only.** They are listed in the
|
|
32
|
+
[Public API map](#public-api-map) below. Internal paths (`dist/*.cjs`, `src/**/*.ts`, the
|
|
33
|
+
dependency-graph engine in `src/build/dependency-graph.ts`) are not public.
|
|
34
|
+
5. **Runtime and build stay apart.** `src/runtime` imports no Node module, has no filesystem access
|
|
35
|
+
and is held to a 3 KB gzip budget (`npm run size`). `src/build` uses `node:path` and
|
|
36
|
+
`typescript`, and takes a `BuildFileSystem` from its caller. Only `src/cli` imports `node:fs`
|
|
37
|
+
(ADR 0040). Runtime and browser code import neither `./build` nor `./node`.
|
|
38
|
+
6. **Errors and logs carry names, not values.** `console.log(paymentsEnv)` prints only
|
|
39
|
+
`EnvContract("payments") { N variable(s) }`. Validation errors are built from the variable name,
|
|
40
|
+
the contract name and source, the failure kind and your own message. Write processor and
|
|
41
|
+
validator messages that describe the expected shape without quoting the value. To inspect a
|
|
42
|
+
contract, log it; spreading it or calling `Object.entries()` on it reads every real value.
|
|
43
|
+
7. **`context` filters which variables take part in validation.** A schema entry may set
|
|
44
|
+
`context: "server"` or any application-defined string. `validateEnv({ activeContexts })` skips a
|
|
45
|
+
variable whose `context` is not listed: no default, processor or validator runs, and reading it
|
|
46
|
+
throws `EnvNotReadyError`. The application computes `activeContexts` and passes it explicitly;
|
|
47
|
+
the package never infers it. `context` is neither an access control nor a bundling boundary: a
|
|
48
|
+
client bundle that imports a manifest ships every definition in it. To keep a variable out of
|
|
49
|
+
client code, give it its own discovery run and manifest
|
|
50
|
+
([ADR 0004](specs/decisions/0004-no-client-server-package-split.md),
|
|
51
|
+
[ADR 0022](specs/decisions/0022-validation-contexts.md)).
|
|
52
|
+
|
|
53
|
+
## In an application
|
|
54
|
+
|
|
55
|
+
- Call `validateEnv()` once, directly from the application's existing startup path, before any
|
|
56
|
+
contract is read. Reading earlier throws `EnvNotReadyError`. Wrappers such as validation managers,
|
|
57
|
+
service locators or registries add nothing.
|
|
58
|
+
- Run the `generate*()` functions from an npm script or CI step; they are build-time only.
|
|
59
|
+
- Treat generated files as the source of truth. To change one, change its contract and regenerate
|
|
60
|
+
it, in this order of preference:
|
|
61
|
+
1. the project's `generate:env` script (or a similarly named one), if it exists;
|
|
62
|
+
2. `generateEnvManifest({ location: "src/generated/env.manifest.ts" })` from
|
|
63
|
+
`@maverickcer/env-cap/build`, called in a build script;
|
|
64
|
+
3. `npx env-cap --location src/generated/env.manifest.ts`, adding `--evidence` or `--strict` as
|
|
65
|
+
needed (`npx env-cap --help` lists every flag).
|
|
66
|
+
- The CLI writes only the manifest and the evidence file. The docs catalog, `.env.example` and the
|
|
67
|
+
ownership report come from `generateEnvArtifacts()`, `generateDocumentation()` or
|
|
68
|
+
`generateUsageReport()` in a build script (ADR 0046). There are no `--docs`, `--ownership` or
|
|
69
|
+
`--env-example` flags.
|
|
70
|
+
- Commit generated files only if the project already commits generated files; otherwise wire the
|
|
71
|
+
command into CI.
|
|
72
|
+
- Migrate one feature per pull request, keep its validation and runtime behavior unchanged, and
|
|
73
|
+
add infrastructure only when the migration needs it. [`specs/migrations/`](specs/migrations/) has
|
|
74
|
+
a guide per starting point (`dotenv`, a central schema, Zod, envalid, t3-env).
|
|
112
75
|
|
|
113
76
|
## Public API map
|
|
114
77
|
|
|
@@ -128,20 +91,22 @@ src/generated/env.manifest.ts` from the CLI. Never hand-assemble the collection
|
|
|
128
91
|
|
|
129
92
|
## Before finishing a change
|
|
130
93
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
94
|
+
Each step is done when its command exits 0 or its condition holds.
|
|
95
|
+
|
|
96
|
+
1. `npm run typecheck` and `npm test` pass.
|
|
97
|
+
2. If `src/runtime`, `src/helpers` or `src/evidence` changed, `npm run size` passes.
|
|
98
|
+
3. If a public export changed, the change is intended; otherwise the export is restored.
|
|
99
|
+
4. If an `env.schema.ts` changed, its `documentEnv()` entry matches, and the generated files are
|
|
100
|
+
regenerated by the project's `generate:env` script.
|
|
101
|
+
5. Every generated file was regenerated, not edited. A generated file starts with a comment that
|
|
102
|
+
says `GENERATED FILE -- do not edit by hand`, or, for `.env.example`, with the line
|
|
103
|
+
`# AUTO-GENERATED EXAMPLE FILE.`.
|
|
104
|
+
6. No secret or raw environment value appears in a thrown error message, a log or a committed
|
|
105
|
+
example file.
|
|
140
106
|
|
|
141
107
|
## Full reference
|
|
142
108
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
[
|
|
147
|
-
[`skills/env-cap/SKILL.md`](skills/env-cap/SKILL.md).
|
|
109
|
+
- Why the architecture is shaped this way: [`specs/architecture.md`](specs/architecture.md).
|
|
110
|
+
- Why a specific rule exists: [`specs/decisions/`](specs/decisions/).
|
|
111
|
+
- Moving an existing application onto env-cap: [`specs/migrations/`](specs/migrations/).
|
|
112
|
+
- Every option of the generators and the CLI: [GUIDE.md](GUIDE.md).
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,41 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.7.7
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- fde4ef4: The published manifest now matches the package.json inside the tarball. `bundleDependencies` lists
|
|
8
|
+
only `@typescript/typescript6`; its TypeScript 6 payload, `@typescript/old`, still ships as that
|
|
9
|
+
package's dependency. Listing `@typescript/old` separately made npm add `"@typescript/old": "*"` to
|
|
10
|
+
the registry manifest, which Socket reported as manifest confusion.
|
|
11
|
+
|
|
12
|
+
## 0.7.6
|
|
13
|
+
|
|
14
|
+
### Patch Changes
|
|
15
|
+
|
|
16
|
+
- aa38823: Documentation, help text and message wording only. No flag, export, exit code, error code or behaviour changed.
|
|
17
|
+
|
|
18
|
+
- Sentences that said a CI job "does not yet block a merge" now name the job and say that the `required` check depends on it. That is because the branch ruleset requires `required`.
|
|
19
|
+
- A failed benchmark job now fails `contract` as well, so it can no longer pass a merge by skipping the other gate jobs.
|
|
20
|
+
- VERSIONING says which exit codes the surface baseline covers (`--help` of the CLI and of `init`) and which a test pins instead.
|
|
21
|
+
- `env-cap --help` lists the exit codes (`0` and `1` and when each applies), so the surface baseline records them. The codes themselves did not change.
|
|
22
|
+
- SECURITY no longer says that no release has run on the current release workflow.
|
|
23
|
+
- The `rotationStatus` value `"compliant"` keeps its name; its TSDoc no longer promises a rename at 1.0, only that a rename would need a major release.
|
|
24
|
+
- `env-cap init --help` rewords one sentence about next steps; the surface baseline is refreshed to match.
|
|
25
|
+
- README's entry-point table is now generated from `package.json` and `docs/surface.json`.
|
|
26
|
+
- Messages and generated text no longer use `--` as a dash: error and warning messages, the `.env.example` notes (`Disabled: feature ...`, `Also declared by ... See ...`), the ownership report's section text, the `init` output and starter template, and the published JSON Schema descriptions. Only the wording changed; codes, keys, file names and the `GENERATED FILE -- do not edit by hand` banner are unchanged.
|
|
27
|
+
- A new test fails when a published JSON Schema removes, retypes or makes optional a field while its `schemaVersion` stays the same.
|
|
28
|
+
- SECURITY says the release requires both `contract` and `required`.
|
|
29
|
+
- The package description, keywords, README opening, landing page and agent skill now say in one sentence what env-cap is, what it reports, what it works alongside and what it does not do.
|
|
30
|
+
- `env-cap --help` opens with what the CLI writes ("the manifest your app passes to `validateEnv()`, an evidence file, or both") and calls the `--evidence` output the evidence file. The flags and exit codes are unchanged.
|
|
31
|
+
- Each entry point (`./build`, `./helpers`, `./node`, `./evidence`, `./eslint-plugin`) now has a module overview in the API reference.
|
|
32
|
+
- A test fails when a document's list of CI-tested Node versions differs from the `verify` matrix in ci.yml.
|
|
33
|
+
- The npm description, README, landing page and agent skill open with one pitch: each feature declares its variables and their format, and your app validates them at startup and reports how to rotate them before they expire. A test fails when the four copies differ.
|
|
34
|
+
- The README's first screen shows the startup error the `init` starter contract throws for a bad value. A test runs `validateEnv()` on that contract and fails when the excerpt differs.
|
|
35
|
+
- `PROMPT.md` is removed from the package; the agent skill and `AGENTS.md` carry its rules.
|
|
36
|
+
- The `ManifestChangeReport` description in the published JSON Schema no longer points at source code the reader cannot see.
|
|
37
|
+
- A new test runs the README quick start (`env-cap init`, then the scaffolded `scripts/generate-env.mjs`) against the built package, so the README and landing page no longer say CI skips it.
|
|
38
|
+
|
|
3
39
|
## 0.7.5
|
|
4
40
|
|
|
5
41
|
### Patch Changes
|
package/CODE_REVIEW.md
CHANGED
|
@@ -6,10 +6,10 @@ A change is safe to merge when CI is green, no invariant below has moved, and ev
|
|
|
6
6
|
|
|
7
7
|
A change is ready to merge when all of these hold:
|
|
8
8
|
|
|
9
|
-
- The `contract` and `
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
- `benchmark-pr`
|
|
9
|
+
- The `contract`, `lint` and `required` checks are green; the branch ruleset requires all three.
|
|
10
|
+
- `required` waits for every gate job in ci.yml: `verify`, `lint`, `contract`, `cross-runtime` (the Bun and Deno suite), `examples`, `integration-fixtures`, `typescript-5`, `typescript-compat`, `package-managers` and `benchmark-pr`.
|
|
11
|
+
- Three jobs are outside `required`. `verify-current` tries the newest Node and is informational. `badges` and `deploy` run only after a push to `main`.
|
|
12
|
+
- A `benchmark-pr` failure also fails `contract` in its first step, so it cannot pass as a skip.
|
|
13
13
|
- Every invariant in §2 that the change touches still holds, checked in the code, not the description.
|
|
14
14
|
- Any public-surface change (§3) is intended, explained, and carries the right changeset.
|
|
15
15
|
- Any generated artifact in the diff (§4) has been read as output.
|
|
@@ -70,7 +70,7 @@ A pull request written with an AI assistant gets the same scrutiny. Its common f
|
|
|
70
70
|
- **Tests that assert the bug:** a regenerated golden or a test that encodes whatever the code now does. Confirm the expected value independently.
|
|
71
71
|
- **Mutation gaming:** a test that kills a mutant but asserts nothing meaningful.
|
|
72
72
|
|
|
73
|
-
[`AGENTS.md`](AGENTS.md)
|
|
73
|
+
[`AGENTS.md`](AGENTS.md) and [`skills/env-cap/SKILL.md`](skills/env-cap/SKILL.md) are the rules an assistant works against; use the same list.
|
|
74
74
|
|
|
75
75
|
## 7. Required verification
|
|
76
76
|
|
package/CONTRIBUTING.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Contributing to env-cap
|
|
2
2
|
|
|
3
|
-
A change needs a branch, tests, a changeset and green `contract` and `
|
|
3
|
+
A change needs a branch, tests, a changeset and green `contract`, `lint` and `required` checks. The steps below go from clone to merge; [CODE_REVIEW.md](CODE_REVIEW.md) covers the reviewer's side.
|
|
4
4
|
|
|
5
5
|
## Development setup
|
|
6
6
|
|
|
@@ -58,17 +58,17 @@ npm run examples:update-golden
|
|
|
58
58
|
2. Make your change. If it touches a surface in [`VERSIONING.md`](VERSIONING.md)'s Stable tier, decide whether it is breaking, additive or a fix.
|
|
59
59
|
3. Add or update tests. `npm run test:coverage` fails below the floors in `vitest.config.ts`. Floors are raised in review when coverage improves. Lowering one is a reviewed change, never a silent one.
|
|
60
60
|
4. Run `npx changeset` and describe what changes for someone who installs the package. Pick `patch`, `minor` or `major` by [`VERSIONING.md`](VERSIONING.md). If you add none, the release workflow generates one from `feat`, `fix`, `perf` and `revert` commit messages; other types release nothing.
|
|
61
|
-
5. Open a pull request. A merge needs the `contract` and `
|
|
61
|
+
5. Open a pull request. A merge needs the `contract`, `lint` and `required` checks; `contract` fails when `verify` or `lint` fails.
|
|
62
62
|
|
|
63
|
-
|
|
63
|
+
The `required` check also waits for `cross-runtime` (Bun and Deno), `examples`, `integration-fixtures`, `typescript-5`, `typescript-compat` and `package-managers`, so a red one blocks a merge.
|
|
64
64
|
|
|
65
|
-
`benchmark-pr`
|
|
65
|
+
A `benchmark-pr` failure skips `lint` and `verify`. `contract` and `required` still run and fail on it, so it blocks a merge too.
|
|
66
66
|
|
|
67
67
|
## Adding an Architecture Decision Record (ADR)
|
|
68
68
|
|
|
69
69
|
`specs/decisions/` records why the project is shaped the way it is. `specs/architecture.md` summarizes the current state. Add an ADR when a change:
|
|
70
70
|
|
|
71
|
-
- introduces a constraint or
|
|
71
|
+
- introduces a constraint or promise an application could rely on, such as "warn, not throw, by default";
|
|
72
72
|
- closes off an approach a future contributor might reintroduce without knowing it was rejected; or
|
|
73
73
|
- moves the boundary of what the runtime, build or helpers entry points are responsible for.
|
|
74
74
|
|
package/GUIDE.md
CHANGED
|
@@ -21,7 +21,7 @@ For the overview and quick start, read [README.md](README.md). For the reasons b
|
|
|
21
21
|
|
|
22
22
|
### Capability-owned contracts
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
A capability is a feature of your code: a folder or an installable package. Each one declares the variables it owns, next to the validation it needs. This contract is illustrative. The contract CI runs is [`examples/application/src/env.ts`](https://github.com/MaverickCER/env-cap/blob/main/examples/application/src/env.ts).
|
|
25
25
|
|
|
26
26
|
```ts
|
|
27
27
|
// features/payments/env.schema.ts
|
|
@@ -329,7 +329,7 @@ The publishing package does two things:
|
|
|
329
329
|
1. Declare `"envCap": { "schema": "./src/env.schema.ts" }` in its `package.json`, and ship that `.ts` file in `files`.
|
|
330
330
|
2. Re-export the `createEnv()` contract under the same name from its main entry.
|
|
331
331
|
|
|
332
|
-
Resolution reads one `package.json` and one declared file per listed package, and never calls `readdir`. It rejects a symlink escaping the package and a file over the size cap (`test/build/resolution/resolve-package-schema.test.ts`). The runnable pair is [`paypal-addon`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/paypal-addon) and [`paypal-consumer`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/paypal-consumer); their CI job
|
|
332
|
+
Resolution reads one `package.json` and one declared file per listed package, and never calls `readdir`. It rejects a symlink escaping the package and a file over the size cap (`test/build/resolution/resolve-package-schema.test.ts`). The runnable pair is [`paypal-addon`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/paypal-addon) and [`paypal-consumer`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/paypal-consumer); `required` waits for their CI job, `integration-fixtures`.
|
|
333
333
|
|
|
334
334
|
An application can document a package's variable again with only its own fields, such as `expiresAt` and `owner`. Fields it leaves unset come from the package's declaration. A field both set differently is reported as `DUPLICATE_VARIABLE_DOCUMENTATION` ([ADR 0050](specs/decisions/0050-a-variable-declared-twice-is-documented-once.md)).
|
|
335
335
|
|
|
@@ -343,19 +343,33 @@ A contract imported through an alias such as `@/features/payments/env.schema.js`
|
|
|
343
343
|
|
|
344
344
|
### Requirements
|
|
345
345
|
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
|
351
|
-
|
|
|
352
|
-
|
|
|
346
|
+
The exact ranges, generated from `package.json`:
|
|
347
|
+
|
|
348
|
+
<!-- ipc:begin supported-versions -->
|
|
349
|
+
|
|
350
|
+
| Requirement | Range | Needed |
|
|
351
|
+
| -------------------------- | ---------------------------------- | -------- |
|
|
352
|
+
| Node.js | `>=22.0.0` | always |
|
|
353
|
+
| `@typescript-eslint/utils` | `^8.0.0` | optional |
|
|
354
|
+
| `eslint` | `^8.57.0 \|\| ^9.0.0 \|\| ^10.0.0` | optional |
|
|
355
|
+
| `typescript` | `^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0` | optional |
|
|
356
|
+
|
|
357
|
+
<!-- ipc:end supported-versions -->
|
|
358
|
+
|
|
359
|
+
The `verify` job tests Node.js 22 and 24 and blocks a merge. Node.js 26 runs in `verify-current`, which is informational.
|
|
360
|
+
|
|
361
|
+
| Need | Detail |
|
|
362
|
+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
|
363
|
+
| TypeScript (optional) | The build entry uses yours when it is 5 or 6, and otherwise the bundled TypeScript 6 (`test/build/typescript-bundled.test.ts`) |
|
|
364
|
+
| TypeScript versions in CI | The newest 5.x, 6.x and 7.x, in `typescript-5` and `typescript-compat`, which `required` waits for; the `^5.0.0` floor is not tested |
|
|
365
|
+
| `moduleResolution` | `node16`, `nodenext` or `bundler`, checked by the `TypeResolution` check; `node10` cannot resolve subpath exports |
|
|
366
|
+
| `./eslint-plugin` | Also needs `eslint` and `@typescript-eslint/utils`; versions in [ADOPTION's dependency table](ADOPTION.md#security--threat-model) |
|
|
353
367
|
|
|
354
368
|
The bundled TypeScript 6 compiler is the package's one dependency. Only the build entry loads it, and `compiler-isolation` fails the build if a runtime entry can reach it ([ADR 0049](specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md)). It is the price of scanning TypeScript 7 projects, whose compiler has no classic API.
|
|
355
369
|
|
|
356
370
|
### Package managers
|
|
357
371
|
|
|
358
|
-
npm is the supported package manager, and every CI job installs with it. The `package-managers` job checks pnpm, Yarn 1 and Yarn Berry with the `node-modules` linker. It checks one thing: the tarball installs and every entry imports as ESM and CommonJS.
|
|
372
|
+
npm is the supported package manager, and every CI job installs with it. The `package-managers` job checks pnpm, Yarn 1 and Yarn Berry with the `node-modules` linker. It checks one thing: the tarball installs and every entry imports as ESM and CommonJS. `required` waits for `package-managers`, so a failure blocks a merge. Yarn Plug'n'Play and non-hoisted pnpm are unsupported.
|
|
359
373
|
|
|
360
374
|
## CLI
|
|
361
375
|
|
|
@@ -437,7 +451,7 @@ The report's schema is [`schemas/env-cap-report.schema.json`](schemas/env-cap-re
|
|
|
437
451
|
|
|
438
452
|
- Real success, failure and `--check` payloads validate against it (`test/build/json-schema.test.ts`).
|
|
439
453
|
- The committed evidence files of two examples validate against its `EvidenceModel` definition, in the same test file.
|
|
440
|
-
- A
|
|
454
|
+
- A removed, retyped or newly optional field must bump `schemaVersion`. `test/build/schema-version-bump.test.ts` compares each schema with the last release's copy in the surface baseline and fails otherwise. A change of meaning that keeps the same shape is not detected. The `SurfaceContract` check enforces the changeset level.
|
|
441
455
|
|
|
442
456
|
### `--check`
|
|
443
457
|
|
|
@@ -506,16 +520,20 @@ How the Action behaves, and what tests it:
|
|
|
506
520
|
|
|
507
521
|
The report functions are unit-tested with a real CLI payload (`test/scripts/github-action-report.test.ts`). The `gh` calls that post comments and issues are not run in CI.
|
|
508
522
|
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
|
512
|
-
|
|
|
513
|
-
| `
|
|
514
|
-
| `
|
|
515
|
-
| `
|
|
516
|
-
| `
|
|
517
|
-
| `report-key` |
|
|
518
|
-
| `
|
|
523
|
+
<!-- ipc:begin action-inputs -->
|
|
524
|
+
|
|
525
|
+
| Input | Required | Default | What it does |
|
|
526
|
+
| ------------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
527
|
+
| `args` | yes | none | Arguments passed to `env-cap --json`, for example '--location src/generated/env.manifest.ts --evidence docs/env.evidence.json --strict-docs'. |
|
|
528
|
+
| `working-directory` | no | `.` | Directory to run env-cap from. |
|
|
529
|
+
| `version` | no | none | env-cap version to run through npx when the project does not install env-cap. |
|
|
530
|
+
| `comment` | no | `true` | Create or update one sticky summary comment on the PR. |
|
|
531
|
+
| `report-key` | no | none | Identifies this invocation's sticky comment, so several calls on one PR (for example one per package in a monorepo) do not overwrite each other. |
|
|
532
|
+
| `annotations` | no | `true` | Emit inline ::warning and ::error annotations for findings. |
|
|
533
|
+
| `rotation-alert` | no | `true` | On a run with no PR, such as a scheduled run, open or update an issue listing expiring variables. |
|
|
534
|
+
| `github-token` | no | `${{ github.token }}` | Token for the gh calls that post the PR comment and the rotation-alert issue. |
|
|
535
|
+
|
|
536
|
+
<!-- ipc:end action-inputs -->
|
|
519
537
|
|
|
520
538
|
### Monorepos
|
|
521
539
|
|
|
@@ -694,9 +712,9 @@ A project can start with one central contract and split it later; the runtime mo
|
|
|
694
712
|
|
|
695
713
|
² Except `processors.base64()`, which returns a Node `Buffer`.
|
|
696
714
|
|
|
697
|
-
³ `bun-version: latest` and Deno `v2.x`, in
|
|
715
|
+
³ `bun-version: latest` and Deno `v2.x`, in `cross-runtime`, which `required` waits for.
|
|
698
716
|
|
|
699
|
-
⁴ `./eslint-plugin`: unit tests block; its ESM and CJS import from the tarball runs only in the
|
|
717
|
+
⁴ `./eslint-plugin`: unit tests block; its ESM and CJS import from the tarball runs only in the `package-managers` job, which `required` waits for.
|
|
700
718
|
|
|
701
719
|
ESM and CommonJS builds ship for every entry point, and the `PackedConsumer` check imports each one from the packed tarball except `./eslint-plugin`. A dual-package split fails fast with a `TypeError` instead of validating against the wrong schema ([SECURITY.md](SECURITY.md#dual-package-hazard)).
|
|
702
720
|
|
|
@@ -716,7 +734,7 @@ Adopt env-cap one contract at a time, and keep what you have:
|
|
|
716
734
|
|
|
717
735
|
Validation runs once, at startup. After it, reading a value is a property lookup on the frozen record of validated values.
|
|
718
736
|
|
|
719
|
-
The [benchmark suite](./benchmarks/README.md) measures runtime and build-time cost as the number of variables grows. Pull requests from this repository are benchmarked, and a regression fails the `benchmark-pr` job
|
|
737
|
+
The [benchmark suite](./benchmarks/README.md) measures runtime and build-time cost as the number of variables grows. Pull requests from this repository are benchmarked, and a regression fails the `benchmark-pr` job, and `contract` fails with it, which blocks the merge. Fork and bot pull requests are not measured. The growth class of `createEnv` is not yet determined on CI, so this guide states no complexity bound.
|
|
720
738
|
|
|
721
739
|
## Documentation index
|
|
722
740
|
|