@maverickcer/env-cap 0.7.4 → 0.7.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (235) hide show
  1. package/ADOPTION.md +106 -124
  2. package/AGENTS.md +14 -13
  3. package/CHANGELOG.md +15 -0
  4. package/CODE_REVIEW.md +69 -173
  5. package/CONTRIBUTING.md +57 -74
  6. package/GUIDE.md +393 -872
  7. package/README.md +81 -76
  8. package/RELEASING.md +17 -15
  9. package/SECURITY.md +76 -227
  10. package/SUPPORT.md +21 -45
  11. package/VERSIONING.md +68 -105
  12. package/benchmarks/READING-BENCHMARKS.md +13 -7
  13. package/benchmarks/WRITING-BENCHMARKS.md +1 -1
  14. package/dist/.dts/_ipc/build-fs.d.ts +9 -14
  15. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  16. package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
  17. package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
  19. package/dist/.dts/_ipc/glob.d.ts +6 -6
  20. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
  21. package/dist/.dts/build/lifecycle-model.d.ts +8 -3
  22. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  23. package/dist/.dts/build/sarif.d.ts.map +1 -1
  24. package/dist/.dts/helpers/index.d.ts +1 -1
  25. package/dist/.dts/runtime/create.d.ts +3 -0
  26. package/dist/.dts/runtime/create.d.ts.map +1 -1
  27. package/dist/.dts/runtime/document.d.ts +7 -4
  28. package/dist/.dts/runtime/document.d.ts.map +1 -1
  29. package/dist/.dts/runtime/index.d.ts +11 -10
  30. package/dist/.dts/runtime/index.d.ts.map +1 -1
  31. package/dist/.dts/runtime/types.d.ts +16 -0
  32. package/dist/.dts/runtime/types.d.ts.map +1 -1
  33. package/dist/.dts/runtime/validate.d.ts +14 -1
  34. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  35. package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
  36. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
  37. package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
  38. package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
  39. package/dist/.dts7/_ipc/display-path.d.ts +27 -0
  40. package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
  41. package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
  42. package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
  43. package/dist/.dts7/_ipc/glob.d.ts +22 -0
  44. package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
  45. package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
  46. package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
  47. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  48. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  49. package/dist/.dts7/_ipc/typescript.d.ts +20 -0
  50. package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
  51. package/dist/.dts7/build/assemble-project.d.ts +47 -0
  52. package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
  53. package/dist/.dts7/build/change-model.d.ts +63 -0
  54. package/dist/.dts7/build/change-model.d.ts.map +1 -0
  55. package/dist/.dts7/build/check-artifacts.d.ts +48 -0
  56. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
  57. package/dist/.dts7/build/citation-verification.d.ts +62 -0
  58. package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
  59. package/dist/.dts7/build/compatibility.d.ts +83 -0
  60. package/dist/.dts7/build/compatibility.d.ts.map +1 -0
  61. package/dist/.dts7/build/compiler-api.d.ts +12 -0
  62. package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
  63. package/dist/.dts7/build/contract-model.d.ts +93 -0
  64. package/dist/.dts7/build/contract-model.d.ts.map +1 -0
  65. package/dist/.dts7/build/deep-equal.d.ts +9 -0
  66. package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
  67. package/dist/.dts7/build/deep-freeze.d.ts +20 -0
  68. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
  69. package/dist/.dts7/build/dependency-graph.d.ts +170 -0
  70. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
  71. package/dist/.dts7/build/dependency-model.d.ts +81 -0
  72. package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
  73. package/dist/.dts7/build/discover.d.ts +41 -0
  74. package/dist/.dts7/build/discover.d.ts.map +1 -0
  75. package/dist/.dts7/build/display-path.d.ts +6 -0
  76. package/dist/.dts7/build/display-path.d.ts.map +1 -0
  77. package/dist/.dts7/build/docs.d.ts +176 -0
  78. package/dist/.dts7/build/docs.d.ts.map +1 -0
  79. package/dist/.dts7/build/env-example.d.ts +85 -0
  80. package/dist/.dts7/build/env-example.d.ts.map +1 -0
  81. package/dist/.dts7/build/errors.d.ts +78 -0
  82. package/dist/.dts7/build/errors.d.ts.map +1 -0
  83. package/dist/.dts7/build/evidence-cache.d.ts +74 -0
  84. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
  85. package/dist/.dts7/build/evidence-model.d.ts +50 -0
  86. package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
  87. package/dist/.dts7/build/evidence-reference.d.ts +67 -0
  88. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
  89. package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
  90. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
  91. package/dist/.dts7/build/exclusive-group.d.ts +19 -0
  92. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
  93. package/dist/.dts7/build/finding-model.d.ts +80 -0
  94. package/dist/.dts7/build/finding-model.d.ts.map +1 -0
  95. package/dist/.dts7/build/generate-documentation.d.ts +176 -0
  96. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
  97. package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
  98. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
  99. package/dist/.dts7/build/generate-evidence.d.ts +77 -0
  100. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
  101. package/dist/.dts7/build/generate-manifest.d.ts +101 -0
  102. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
  103. package/dist/.dts7/build/generate-usage.d.ts +95 -0
  104. package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
  105. package/dist/.dts7/build/generated-banner.d.ts +43 -0
  106. package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
  107. package/dist/.dts7/build/glob.d.ts +6 -0
  108. package/dist/.dts7/build/glob.d.ts.map +1 -0
  109. package/dist/.dts7/build/governance-fields.d.ts +34 -0
  110. package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
  111. package/dist/.dts7/build/humanize-key.d.ts +14 -0
  112. package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
  113. package/dist/.dts7/build/index.d.ts +105 -0
  114. package/dist/.dts7/build/index.d.ts.map +1 -0
  115. package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
  116. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
  117. package/dist/.dts7/build/link.d.ts +223 -0
  118. package/dist/.dts7/build/link.d.ts.map +1 -0
  119. package/dist/.dts7/build/literal-eval.d.ts +24 -0
  120. package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
  121. package/dist/.dts7/build/live-expirations.d.ts +47 -0
  122. package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
  123. package/dist/.dts7/build/manifest.d.ts +31 -0
  124. package/dist/.dts7/build/manifest.d.ts.map +1 -0
  125. package/dist/.dts7/build/map-utils.d.ts +8 -0
  126. package/dist/.dts7/build/map-utils.d.ts.map +1 -0
  127. package/dist/.dts7/build/merge-documentation.d.ts +35 -0
  128. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
  129. package/dist/.dts7/build/ownership-model.d.ts +59 -0
  130. package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
  131. package/dist/.dts7/build/parse.d.ts +207 -0
  132. package/dist/.dts7/build/parse.d.ts.map +1 -0
  133. package/dist/.dts7/build/reference-projections.d.ts +170 -0
  134. package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
  135. package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
  136. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
  137. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
  138. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
  139. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
  140. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
  141. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
  142. package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
  143. package/dist/.dts7/build/sarif.d.ts +66 -0
  144. package/dist/.dts7/build/sarif.d.ts.map +1 -0
  145. package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
  146. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
  147. package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
  148. package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
  149. package/dist/.dts7/build/source-position.d.ts +69 -0
  150. package/dist/.dts7/build/source-position.d.ts.map +1 -0
  151. package/dist/.dts7/build/tool-version.d.ts +8 -0
  152. package/dist/.dts7/build/tool-version.d.ts.map +1 -0
  153. package/dist/.dts7/build/types.d.ts +7 -0
  154. package/dist/.dts7/build/types.d.ts.map +1 -0
  155. package/dist/.dts7/build/typescript.d.ts +6 -0
  156. package/dist/.dts7/build/typescript.d.ts.map +1 -0
  157. package/dist/.dts7/build/usage-report.d.ts +124 -0
  158. package/dist/.dts7/build/usage-report.d.ts.map +1 -0
  159. package/dist/.dts7/cli/filesystem.d.ts +7 -0
  160. package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
  161. package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
  162. package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
  163. package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
  164. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
  165. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
  166. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
  167. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
  168. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
  169. package/dist/.dts7/evidence/define-projection.d.ts +52 -0
  170. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
  171. package/dist/.dts7/evidence/index.d.ts +23 -0
  172. package/dist/.dts7/evidence/index.d.ts.map +1 -0
  173. package/dist/.dts7/helpers/index.d.ts +135 -0
  174. package/dist/.dts7/helpers/index.d.ts.map +1 -0
  175. package/dist/.dts7/helpers/processors.d.ts +32 -0
  176. package/dist/.dts7/helpers/processors.d.ts.map +1 -0
  177. package/dist/.dts7/helpers/validators.d.ts +68 -0
  178. package/dist/.dts7/helpers/validators.d.ts.map +1 -0
  179. package/dist/.dts7/node/index.d.ts +2 -0
  180. package/dist/.dts7/node/index.d.ts.map +1 -0
  181. package/dist/.dts7/runtime/cache.d.ts +17 -0
  182. package/dist/.dts7/runtime/cache.d.ts.map +1 -0
  183. package/dist/.dts7/runtime/create.d.ts +23 -0
  184. package/dist/.dts7/runtime/create.d.ts.map +1 -0
  185. package/dist/.dts7/runtime/document.d.ts +223 -0
  186. package/dist/.dts7/runtime/document.d.ts.map +1 -0
  187. package/dist/.dts7/runtime/errors.d.ts +55 -0
  188. package/dist/.dts7/runtime/errors.d.ts.map +1 -0
  189. package/dist/.dts7/runtime/index.d.ts +25 -0
  190. package/dist/.dts7/runtime/index.d.ts.map +1 -0
  191. package/dist/.dts7/runtime/registry.d.ts +12 -0
  192. package/dist/.dts7/runtime/registry.d.ts.map +1 -0
  193. package/dist/.dts7/runtime/reset.d.ts +8 -0
  194. package/dist/.dts7/runtime/reset.d.ts.map +1 -0
  195. package/dist/.dts7/runtime/types.d.ts +191 -0
  196. package/dist/.dts7/runtime/types.d.ts.map +1 -0
  197. package/dist/.dts7/runtime/validate.d.ts +27 -0
  198. package/dist/.dts7/runtime/validate.d.ts.map +1 -0
  199. package/dist/{build-6XFHJFQK.js → build-DNAYWD2B.js} +8 -5
  200. package/dist/build-DNAYWD2B.js.map +1 -0
  201. package/dist/build.cjs +7 -4
  202. package/dist/build.cjs.map +1 -1
  203. package/dist/build.js +7 -4
  204. package/dist/build.js.map +1 -1
  205. package/dist/build.ts7.d.cts +1 -0
  206. package/dist/build.ts7.d.ts +1 -0
  207. package/dist/{chunk-RL5KFVUT.js → chunk-HAGMVMN5.js} +2 -2
  208. package/dist/cli/index.js +3 -3
  209. package/dist/eslint-plugin/index.cjs.map +1 -1
  210. package/dist/eslint-plugin/index.js.map +1 -1
  211. package/dist/eslint-plugin/index.ts7.d.cts +1 -0
  212. package/dist/eslint-plugin/index.ts7.d.ts +1 -0
  213. package/dist/evidence.ts7.d.cts +1 -0
  214. package/dist/evidence.ts7.d.ts +1 -0
  215. package/dist/helpers.ts7.d.cts +1 -0
  216. package/dist/helpers.ts7.d.ts +1 -0
  217. package/dist/index.cjs.map +1 -1
  218. package/dist/index.js.map +1 -1
  219. package/dist/index.ts7.d.cts +1 -0
  220. package/dist/index.ts7.d.ts +1 -0
  221. package/dist/node.ts7.d.cts +1 -0
  222. package/dist/node.ts7.d.ts +1 -0
  223. package/examples/README.md +46 -80
  224. package/package.json +27 -4
  225. package/schemas/env-cap-report.schema.json +1 -1
  226. package/skills/env-cap/SKILL.md +1 -1
  227. package/skills/env-cap/references/api.md +1 -1
  228. package/specs/architecture.md +2 -2
  229. package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
  230. package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
  231. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
  232. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
  233. package/specs/generated-artifacts.md +14 -2
  234. package/dist/build-6XFHJFQK.js.map +0 -1
  235. /package/dist/{chunk-RL5KFVUT.js.map → chunk-HAGMVMN5.js.map} +0 -0
package/ADOPTION.md CHANGED
@@ -1,144 +1,126 @@
1
- # Adoption guide for technical decision-makers
1
+ # Adoption guide
2
2
 
3
- This document exists for one purpose: to let a Principal/Staff engineer,
4
- architect, or security reviewer evaluate `env-cap` for adoption at
5
- organizational scale without having to reconstruct the picture from
6
- `SECURITY.md`, `specs/architecture.md`, the ADRs in `specs/decisions/`, and six migration
7
- guides scattered across the repository tree. Everything here links back to
8
- the primary source it summarizes — nothing here is a new claim.
3
+ Adopting `env-cap` costs a build step and a declaration per variable; it needs Node 22 and npm. The sections below list each cost, need and refusal, with the check behind it.
9
4
 
10
5
  ## What problem this solves
11
6
 
12
- Most environment-variable tooling (`dotenv`, `zod`, `envalid`, `t3-env`)
13
- solves _validation_: is this value the right shape? None of them solve
14
- _ownership_: which team owns `STRIPE_WEBHOOK_SECRET`, what breaks if it
15
- disappears, and is it actually still read anywhere? As an application grows
16
- past a handful of features, environment configuration tends to converge on
17
- one growing, centrally-owned schema file that nobody wants to touch because
18
- nobody's sure what depends on what. `env-cap` lets each capability declare
19
- and validate the variables _it_ consumes, and adds a static-analysis layer
20
- that answers the ownership/blast-radius questions a validation-only library
21
- never asks. See [`specs/migrations/README.md`](specs/migrations/README.md)
22
- and its six per-tool guides for an honest, specific comparison — including
23
- when _not_ to switch.
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 capability declare the variables it consumes. A build-time analysis then reports owners, expiry dates and declared variables that nothing reads.
8
+
9
+ [`specs/migrations/README.md`](specs/migrations/README.md) compares it with each tool you may have, and says when not to switch.
10
+
11
+ ## What it costs
12
+
13
+ | Cost | Detail |
14
+ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
15
+ | A build step | The CLI or a script runs in development and CI to write the manifest your startup code imports |
16
+ | A declaration per variable | `createEnv()` for validation and `documentEnv()` for owners and dates. Reports are only as accurate as these declarations |
17
+ | Committed generated files | The manifest and the evidence file are committed, so changes show up as reviewable diffs |
18
+ | Install weight | A TypeScript 6 compiler, bundled in the tarball and used only by the build entry ([details](#bundle-size-and-performance)) |
19
+ | Runtime weight | The runtime entry stays under 3 KB gzip, helpers under 4 KB and evidence under 3 KB, enforced by the `Size` check |
20
+ | Pre-1.0 churn | A minor release may break the Stable tier before 1.0 ([versioning](#versioning-stability-and-long-term-support)) |
21
+
22
+ ## What it needs
23
+
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. That job does not yet block a merge.
26
+ - TypeScript `moduleResolution` set to `node16`, `nodenext` or `bundler` if you type-check against the subpath exports.
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
+ - 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.
29
+
30
+ ## What it refuses to do
31
+
32
+ | It will not | Enforced by | Limit |
33
+ | ------------------------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
34
+ | Load `.env` files or store, fetch or rotate secrets | No such code exists; keep `dotenv` and your secret manager | Not a check |
35
+ | Run your schema files during analysis | `test/build/parse.test.ts`: a throwing top-level statement never runs | Lint does not ban `import()` or `vm` in `src/build`; review covers that |
36
+ | Touch the filesystem from the runtime | Lint, and the `AmbientCapabilities` scan of the packed tarball | The scan is textual and skips bundled dependencies |
37
+ | Read `process.env` in the runtime | The `AmbientCapabilities` scan and the browser-bundle test | Textual; an indirect reference would evade both |
38
+ | Put a value in an error message | `test/runtime/validate.test.ts` | Your own validator or processor message is passed through |
39
+ | Guess a value it cannot resolve statically | `test/build/parse.test.ts`, `test/build/literal-eval.test.ts` | None found |
40
+ | Walk `node_modules` during discovery | `test/build/discover.test.ts` | Packages you list in `packages` are read, one file each |
41
+ | Fail a run on documentation or ownership findings by default | `test/cli/main.test.ts`, `test/build/generate-env-artifacts.test.ts` | Exclusive-group violations and conflicting explicit processor types always fail |
24
42
 
25
43
  ## Security & threat model
26
44
 
27
- Full detail: [`SECURITY.md`](SECURITY.md). The summary a security reviewer
28
- needs:
29
-
30
- - **The runtime has no dependencies.** The runtime entry points (`.` and `./helpers`) import
31
- nothing, so nothing is added to your application's production bundle. `package.json` has one
32
- `dependencies` entry: a bundled TypeScript 6 compiler (about 5 MB to download, about 24 MB unpacked in your
33
- `node_modules`), used only by the build entry so that TypeScript 7 projects can run the scanner
34
- ([ADR 0049](specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md)).
35
- `internal-package-contract tool compiler-isolation` fails the build if any runtime entry can reach it.
36
- - **The runtime never persists, retrieves, rotates, or logs secrets**, and
37
- never inserts raw or processed values into a thrown error — only variable
38
- names, contract names, and the _developer's own_ validator/processor
39
- message strings ever reach an `EnvValidationError`.
40
- - **Contracts self-redact.** `console.log`, `JSON.stringify`, and template-
41
- literal interpolation of a contract object all produce a redacted
42
- `EnvContract("name")` marker, never resolved values ([ADR
43
- 0006](specs/decisions/0006-self-redacting-contracts.md)).
44
- - **The build tool never executes discovered code.** Schema files are parsed
45
- as TypeScript ASTs (`ts.createSourceFile`), never `import()`ed, `require()`d,
46
- or `eval()`d — a build tool meant to run in CI against a team's own source
47
- tree does not become a second execution path for that source
48
- ([ADR 0002](specs/decisions/0002-static-analysis-never-execution.md)).
49
- This guarantee is enforced by a regression test proving a schema file with
50
- a throwing top-level statement never actually runs during discovery.
51
- - **Cross-package discovery (ADR 0014) does not weaken the
52
- above.** It is opt-in (an explicit `packages` allowlist, never an implicit
53
- scan of installed dependencies), never walks `node_modules` via `readdir`,
54
- and validates a resolved file's path, extension, symlink target, and size
55
- before ever parsing it — see
56
- [ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md) and the
57
- updated `SECURITY.md` section for the exact bounds.
58
- - **TypeScript path-alias resolution (ADR 0023) never crosses
59
- into `node_modules`.** Unlike cross-package discovery, this mechanism is on
60
- by default (a project's own `tsconfig.json` never crosses a
61
- trust/versioning boundary the way an installed package does), but the
62
- boundary between the two stays strict: any resolution landing inside
63
- `node_modules` is discarded, so bare package specifiers remain exclusively
64
- governed by the explicit `packages` allowlist above — see
65
- [ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md).
66
- - **Supply-chain posture:** dependency-free at runtime; CI enforces
67
- typecheck, lint, tests with coverage thresholds, cross-runtime conformance
68
- (Node/Bun/Deno), and a hard gzip size budget on every change; releases
69
- publish via npm's OIDC trusted publishing (no long-lived `NPM_TOKEN`) with
70
- provenance attestation, so a consumer can verify a published artifact was
71
- built by this repository's own CI, not a maintainer's laptop.
45
+ Full detail is in [`SECURITY.md`](SECURITY.md). The summary a reviewer needs:
46
+
47
+ - **The runtime imports no Node module.** The browser-bundle test rejects a `node:` import, a Node built-in `require`, `process.` or `Buffer.` in the bundle. It does not fail on a third-party import, which would be bundled silently.
48
+ - **The compiler stays out of the runtime.** `internal-package-contract tool compiler-isolation` fails the build if any runtime entry can reach the bundled compiler ([ADR 0049](specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md)). It reads the static import graph of `dist/` only.
49
+ - **Contracts redact themselves** under `console.log`, `String()`, `JSON.stringify` and template interpolation (`test/runtime/create.test.ts`, [ADR 0006](specs/decisions/0006-self-redacting-contracts.md)). Spreading a contract reads every value.
50
+ - **Cross-package discovery is opt-in.** It reads only packages you name, one `package.json` and one declared file each. It rejects symlink escapes and oversized files ([ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md)).
51
+ - **Path-alias resolution never lands in `node_modules`.** It is on by default, and any result inside `node_modules` is discarded ([ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md)).
52
+ - **No outbound network in env-cap's own code.** The `ipc/no-network` lint rule covers `src/`. It does not cover the bundled TypeScript compiler, which Socket flags for network access.
53
+
54
+ What installing the package adds, generated from `package.json` and `docs/surface.json`:
55
+
56
+ <!-- ipc:begin dependencies -->
57
+
58
+ Installing `@maverickcer/env-cap` installs 1 package directly, and whatever it depends on. It names 3 optional peers, which you install yourself when you use the part that needs them.
59
+
60
+ | Package | Kind | Range | Why |
61
+ | -------------------------- | ------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
62
+ | `@typescript/typescript6` | dependency | `^6.0.2` | The TypeScript 6 compiler the build entry parses schemas with when the project's own TypeScript is 7 or missing (ADR 0049). Bundled inside the tarball. No runtime entry can reach it (`compiler-isolation`). |
63
+ | `@typescript-eslint/utils` | optional peer | `^8.0.0` | Only for `@maverickcer/env-cap/eslint-plugin`; projects linting TypeScript already have it through `typescript-eslint`. |
64
+ | `eslint` | optional peer | `^8.57.0 \|\| ^9.0.0 \|\| ^10.0.0` | Only for `@maverickcer/env-cap/eslint-plugin`, which runs inside the project's own ESLint. CI runs the rules on ESLint 10 only. |
65
+ | `typescript` | optional peer | `^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0` | The project's own compiler, used by the build entry instead of `@typescript/typescript6` when it is version 5 or 6. CI tests the newest 5.x, 6.x and 7.x, not the 5.0 floor. |
66
+
67
+ <!-- ipc:end dependencies -->
68
+
69
+ **Supply chain.** A merge to `main` requires a pull request, resolved review threads, and the `contract` and `lint` checks. The ruleset and the `BranchProtection` check enforce that; admins can bypass, and no approving review is required. These gates run in the `contract` job:
70
+
71
+ - Typecheck, lint, tests with coverage floors, zero surviving mutants, and size budgets.
72
+ - Production dependency licences, `npm audit` and Socket alerts, each with a reviewed record when accepted.
73
+ - An install-and-import of the packed tarball, for every entry except `./eslint-plugin`.
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 but do not yet block a merge.
72
76
 
73
77
  ## Versioning, stability, and long-term support
74
78
 
75
- Full detail: [`VERSIONING.md`](VERSIONING.md). The three-tier model —
76
- **Stable** (semver-covered public runtime/build APIs, CLI flags, the `--json`
77
- schema, the generated manifest format, and every surface listed in
78
- [ADR 0045](specs/decisions/0045-promote-experimental-surfaces-to-stable.md)),
79
- **Experimental** (explicitly labeled new surfaces that may still change
80
- shape before being promoted -- nothing currently ships under this tier), and
81
- **Private** (internal implementation, never covered) — is what the eventual
82
- 1.0 stability promise will cover.
83
-
84
- **The honest gap or long-term support question, answered directly:**
85
- `env-cap` has not reached a 1.0 release, and today, per `SECURITY.md`,
86
- security fixes target the latest published `0.x` version only — there is
87
- no backport branch yet. **Starting at `1.0`**, `SECURITY.md` commits to
88
- backporting security fixes to the latest minor release of the previous
89
- major version for a minimum of six months after a new major ships (a
90
- window that can be extended, never shortened, once stated). An
91
- organization with a hard LTS/backport requirement today should treat the
92
- _current_ state as a real limitation — the `1.0` commitment is a forward
93
- policy, not something already exercised in production. It is offset by the
94
- same two structural factors as before: zero runtime dependencies, and a
95
- fully automated, OIDC-attested release pipeline plus documented governance
96
- that lower the bar for a successor maintainer or fork.
79
+ [`VERSIONING.md`](VERSIONING.md) lists every entry point and its tier. Every entry point is Stable today, and nothing ships as Experimental ([ADR 0045](specs/decisions/0045-promote-experimental-surfaces-to-stable.md)). The `ApiContract` and `SurfaceContract` checks diff the public surface against committed baselines and require a changeset at the matching level. Before 1.0, a breaking change needs only a minor release.
80
+
81
+ **Long-term support, stated plainly.** env-cap has not reached 1.0. Security fixes target the latest `0.x` only, and there is no backport branch. From 1.0, [`SECURITY.md`](SECURITY.md#supported-versions) commits to backporting security fixes to the previous major's latest minor for at least six months. That is a policy for a future release line; it has not been exercised. An organization with a backport requirement today should treat this as a real limitation.
82
+
83
+ Releases are automated after a person merges the release pull request ([RELEASING.md](RELEASING.md)). Commit-generated bumps stop below 1.0.0. Crossing it takes a hand-written `major` changeset, and the workflow only posts a notice when its release pull request is opened.
97
84
 
98
85
  ## Bundle size and performance
99
86
 
100
- The runtime entry point carries a **hard 3&nbsp;KB gzip budget** and the helpers a **hard 4&nbsp;KB** one,
101
- enforced at `prepublishOnly` — not an aspirational CI check a maintainer can
102
- ignore, a publish-blocking one ([ADR
103
- 0008](specs/decisions/0008-gzip-size-budget.md)). `sideEffects: false` is set
104
- and verified by a dedicated test that bundles the real `dist/helpers.js`
105
- output with esbuild and asserts unused exports are actually tree-shaken, not
106
- just assumed to be.
87
+ | Entry point | Gzip budget | Enforced by |
88
+ | ------------- | ----------- | ------------------------------------------------------------------------ |
89
+ | `.` (runtime) | 3 KB | The `Size` check in `contract`, and the release build's `npm run verify` |
90
+ | `./helpers` | 4 KB | The same |
91
+ | `./evidence` | 3 KB | The same |
107
92
 
108
- ## Architectural guarantees worth knowing before you adopt
93
+ Each budget measures the entry's own file, not your bundle. The release publishes with `--ignore-scripts`, so the budget blocks through those two steps, not `prepublishOnly` ([ADR 0008](specs/decisions/0008-gzip-size-budget.md)).
109
94
 
110
- Each of these is a locked-in product decision, not an implementation detail
111
- that might silently change:
95
+ `sideEffects: false` is set, and a test bundles the real `dist/helpers.js` with esbuild to check that unused helpers are dropped (`test/helpers/tree-shaking.test.ts`). Other bundlers are not tested.
112
96
 
113
- | Guarantee | Why it matters for adoption | ADR |
114
- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
115
- | No global `env` object — only per-capability contracts | Prevents the "one giant schema file nobody owns" failure mode this package exists to solve | [0003](specs/decisions/0003-no-global-env-object.md) |
116
- | One runtime, no `/client`/`/server` split | Works identically in Node, browser, edge, and serverless — no framework-specific build variant to maintain | [0004](specs/decisions/0004-no-client-server-package-split.md) |
117
- | Warn, not throw, by default | Adopting incrementally in a large codebase doesn't require fixing every finding on day one. `--strict-docs`/`--strict-ownership` opt into a stricter CI gate one family at a time, or `--strict` escalates all three provable-error families (compatibility, documentation, ownership) at once once a team is ready (ADR 0044). Nothing throws until a team opts in | [0005](specs/decisions/0005-warn-not-throw-by-default.md), [0038](specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md), [0044](specs/decisions/0044-strict-escalates-every-warning-family.md) |
118
- | Exclusive-group violations are always hard errors | A safety guarantee (e.g. "never activate two database backends at once") that can't be silently downgraded to a warning by a lenient CI setting | [0009](specs/decisions/0009-exclusive-groups-are-always-errors.md) |
119
- | `--json` output is a versioned, additive-only wire contract | Safe to build dashboards/CI integrations against; a `schemaVersion` bump is the only breaking-change signal to watch for | [0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md) |
97
+ The install includes the bundled TypeScript 6 compiler. No check measures its size, so run `npm pack --dry-run` on the version you evaluate. Only the build entry loads it, in development and CI.
120
98
 
121
- Full list: [`specs/architecture.md`](specs/architecture.md)'s decision table.
99
+ ## Architectural decisions worth knowing before you adopt
100
+
101
+ | Decision | What it means for you | ADR |
102
+ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
103
+ | No global `env` object | Each capability 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 or changed field is meant to bump `schemaVersion`, but no check enforces that yet | [0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md) |
108
+
109
+ The full list is in [`specs/architecture.md`](specs/architecture.md).
122
110
 
123
111
  ## Migration cost from what you likely have today
124
112
 
125
- | Coming from | Migration guide | One-line take |
126
- | -------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
127
- | Raw `process.env` | [from-process-env.md](specs/migrations/from-process-env.md) | Lowest-friction starting point; adds validation and ownership where there was none |
128
- | `dotenv` | [from-dotenv.md](specs/migrations/from-dotenv.md) | `dotenv` still loads `.env` files; `env-cap` validates and documents what's in them |
129
- | `zod`-based validation | [from-zod.md](specs/migrations/from-zod.md) | Keep Zod for request/response validation; only adopt `env-cap` if ownership/discovery, not validation, is the actual pain point |
130
- | `envalid` | [from-envalid.md](specs/migrations/from-envalid.md) | Similar validation ergonomics; the real delta is per-capability ownership vs. one central schema |
131
- | `t3-env` | [from-t3-env.md](specs/migrations/from-t3-env.md) | Both are type-safe; `t3-env` centralizes, `env-cap` deliberately doesn't |
132
- | A hand-rolled centralized schema | [from-centralized-schema.md](specs/migrations/from-centralized-schema.md) | The most direct fit for what this package changes about your architecture |
133
-
134
- Every guide above includes an explicit "when to keep what you have"
135
- section — these are not one-directional sales pitches; several actively
136
- recommend staying put for small or single-team applications.
137
-
138
- ## Questions this document doesn't answer
139
-
140
- If you need something not covered here — a specific compliance framework
141
- mapping, a formal SLA, or an LTS commitment beyond what `SECURITY.md`
142
- states — that is a real gap today, not an oversight in this document. Open
143
- an issue or reach the maintainer through the channels in `SECURITY.md`
144
- rather than assuming an answer either way.
113
+ | Coming from | Migration guide | One-line take |
114
+ | -------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
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
+ | `dotenv` | [from-dotenv.md](specs/migrations/from-dotenv.md) | `dotenv` still loads `.env` files; `env-cap` validates and documents what is in them |
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-capability ownership |
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
+ | A hand-rolled centralized schema | [from-centralized-schema.md](specs/migrations/from-centralized-schema.md) | The closest fit for what this package changes |
121
+
122
+ Each guide has a section on when to keep what you have.
123
+
124
+ ## Questions this document does not answer
125
+
126
+ There is no formal SLA, and no support commitment beyond [`SUPPORT.md`](SUPPORT.md) and [`SECURITY.md`](SECURITY.md). The generated documents support a review; they do not establish that any standard is met. Open an issue if you need something this document does not cover.
package/AGENTS.md CHANGED
@@ -36,10 +36,11 @@ and aggregated at build time. There is no global `env` object.
36
36
  per canonical fact model, e.g. `./schema/contract-model`), and `./package.json`. Import
37
37
  only from these — never `dist/*.cjs` internals, `src/**/*.ts` paths, or an unexported
38
38
  build internal (e.g. the dependency-graph engine).
39
- 5. **Runtime and build are strictly separated.** `src/build` uses `node:fs`/`node:path`/
40
- `typescript` and must never be imported from runtime/browser code. `src/runtime` has
41
- zero filesystem access and zero dependencies, and is held to a 3KB gzip budget
42
- (`npm run size`).
39
+ 5. **Runtime and build are strictly separated.** `src/build` uses `node:path` and
40
+ `typescript`, never `node:fs`. It takes a `BuildFileSystem` from its caller; only `src/cli`
41
+ may import `node:fs` (ADR 0040). It must never be imported from runtime or browser code.
42
+ `src/runtime` imports no Node module, has no filesystem access, and is held to a 3 KB gzip
43
+ budget (`npm run size`).
43
44
  6. **Contracts self-redact; errors never carry values.** `console.log(paymentsEnv)`
44
45
  prints only `EnvContract("payments") { N variable(s) }`. Validation errors are built
45
46
  from variable name, contract name/source, failure kind, and the developer's own error
@@ -113,15 +114,15 @@ src/generated/env.manifest.ts` from the CLI. Never hand-assemble the collection
113
114
 
114
115
  <!-- ipc:begin entry-points -->
115
116
 
116
- | Export | Source | Environment | Tier | Purpose |
117
- | ------------------------------------ | -------------------- | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
118
- | `@maverickcer/env-cap` | `src/runtime/` | isomorphic, zero deps | Stable | `createEnv`, `documentEnv`, `validateEnv`, `resetEnvCache`, error types, `isEnvContract` |
119
- | `@maverickcer/env-cap/build` | `src/build/` | Node-only, dev/CI | Stable | discovery, AST analysis, artifact generation (see `VERSIONING.md` — the four `generate*()` orchestrators and the lower-level primitives are all Stable, ADR 0045) |
120
- | `@maverickcer/env-cap/helpers` | `src/helpers/` | isomorphic, optional | Stable | `processors` / `validators` |
121
- | `@maverickcer/env-cap/node` | `src/node/` | Node-only, dev/CI | Stable | `nodeBuildFileSystem` — the ready-made `BuildFileSystem` adapter a build script hands to `./build` |
122
- | `@maverickcer/env-cap/evidence` | `src/evidence/` | isomorphic, optional | Stable | `defineEvidenceProjection` — pure transforms over the Evidence Model (Stable, see `VERSIONING.md`) |
123
- | `@maverickcer/env-cap/eslint-plugin` | `src/eslint-plugin/` | Node-only, optional | Stable | `no-raw-process-env` and `no-node-fs` lint rules |
124
- | `@maverickcer/env-cap/schema` | `schemas/` | static JSON | Stable | The published JSON Schema for `env-cap --json` output (`env-cap-report.schema.json`), plus the model schemas under `./schema/*` |
117
+ | Export | Source | Environment | Tier | Purpose |
118
+ | ------------------------------------ | -------------------- | ------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
119
+ | `@maverickcer/env-cap` | `src/runtime/` | No Node module or Node global | Stable | `createEnv`, `documentEnv`, `validateEnv`, `resetEnvCache`, `isEnvContract` and the error types |
120
+ | `@maverickcer/env-cap/build` | `src/build/` | Node only, in development and CI | Stable | Discovery, AST analysis and artifact generation. The four `generate*()` orchestrators and the lower-level primitives are Stable (ADR 0045, `VERSIONING.md`). |
121
+ | `@maverickcer/env-cap/helpers` | `src/helpers/` | No Node module; `processors.base64()` returns a Node `Buffer` | Stable | `processors` and `validators` |
122
+ | `@maverickcer/env-cap/node` | `src/node/` | Node only, in development and CI | Stable | `nodeBuildFileSystem`, the `BuildFileSystem` adapter a build script hands to `./build` |
123
+ | `@maverickcer/env-cap/evidence` | `src/evidence/` | No Node module or Node global | Stable | `defineEvidenceProjection`, pure transforms over the Evidence Model (Stable, see `VERSIONING.md`) |
124
+ | `@maverickcer/env-cap/eslint-plugin` | `src/eslint-plugin/` | Node only, inside the project's ESLint | Stable | The `no-raw-process-env` and `no-node-fs` lint rules |
125
+ | `@maverickcer/env-cap/schema` | `schemas/` | Static JSON | Stable | The JSON Schema for `env-cap --json` output (`env-cap-report.schema.json`) and the model schemas under `./schema/*` |
125
126
 
126
127
  <!-- ipc:end entry-points -->
127
128
 
package/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.7.5
4
+
5
+ ### Patch Changes
6
+
7
+ - 72cb72c: Documentation now describes the TypeScript 6 compiler as the package's one npm dependency, bundled inside the tarball and used only by the build entry, and says that installing your own TypeScript is optional. The rotation-log example quotes NIST SP 800-53 IA-5(f) verbatim and no longer calls itself a compliance artifact, and the enterprise example no longer describes its report as useful in litigation.
8
+
9
+ What installing the package adds is now generated into ADOPTION.md from `package.json` (`internal-package-contract generate`, reasons in `docs/surface.json`), and the standard-format documents it generates are a generated table in `specs/generated-artifacts.md` that cites the test checking each format. SARIF output is now validated in tests against the official OASIS 2.1.0 schema (a managed copy from internal-package-contract), and a finding with a position points at the cited file, percent-encoded.
10
+ - 72cb72c: Gates widened: the helpers and evidence entry points are executed under Bun and Deno in CI (not only the runtime); the TypeScript compat job parses all 23 committed schema fixtures under TypeScript 5, 6 and 7 roots and requires byte-identical results; the ambient-capability tarball scan also rejects `process.env` outside the CLI and the ESLint plugin; the `node:fs` import ban in `src/` is live again (two flat-config blocks had let the later one replace it); a `required` CI check stands for every job the ruleset could not name, and `contract` fails instead of skipping when `verify` or `lint` fails; `npm run setup` installs the shared git hooks.
11
+
12
+ Documentation now matches the gates behind it: coverage is described as fixed floors raised in review (not a self-moving ratchet); the compiler is described as bundled, about 24 MB; SECURITY names all six entry points in its no-network statement; VERSIONING's Private tier covers every entry point; the Action's `version` input is documented as required when env-cap is not installed, and the workflow examples install the package first; ADRs 0014 and 0023 carry their real status; `rotationStatus` is documented as a policy-window judgement, never a compliance statement, with the 1.0 rename announced. The Action's step summary is capped below GitHub's size limit.
13
+
14
+ TypeScript 7 consumers no longer need `skipLibCheck`: the build emits a second declaration tree (`dist/.dts7`) whose compiler-API types come from the bundled TypeScript 6, served only to TypeScript 7 through `types@>=7` export conditions; TypeScript 5 and 6 keep the declarations typed from their own `typescript`. The compat job type-checks every entry point but `./eslint-plugin` (typed through its `@typescript-eslint/utils` peer) with full library checking under all three and asserts which declaration set answered.
15
+
16
+ Every document is rewritten for its reader, with each promise naming the check behind it and the limit of that check in the same sentence: README as the map (an entry-point table and the output of `examples/application` as CI runs it), GUIDE by audience with one story per entry point, ADOPTION as the decision document (what it costs, needs and refuses to do), SECURITY as the reviewer's tables (mechanism, where it blocks, limit), VERSIONING with the real tier table, CONTRIBUTING and CODE_REVIEW to the real jobs and the hand-merged release pull request, and every example README with its command, exit code and the output line to look for. Claims the gates did not hold were narrowed or removed; a docs test now pins the size budgets, coverage floors and the dependency count the prose quotes.
17
+
3
18
  ## 0.7.4
4
19
 
5
20
  ### Patch Changes