@maverickcer/env-cap 0.7.3 → 0.7.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (238) hide show
  1. package/ADOPTION.md +106 -124
  2. package/AGENTS.md +14 -13
  3. package/CHANGELOG.md +23 -0
  4. package/CODE_REVIEW.md +69 -173
  5. package/CONTRIBUTING.md +57 -74
  6. package/GUIDE.md +393 -872
  7. package/README.md +82 -77
  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 +0 -14
  21. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
  22. package/dist/.dts/build/lifecycle-model.d.ts +8 -3
  23. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  24. package/dist/.dts/build/sarif.d.ts.map +1 -1
  25. package/dist/.dts/helpers/index.d.ts +1 -1
  26. package/dist/.dts/runtime/create.d.ts +3 -0
  27. package/dist/.dts/runtime/create.d.ts.map +1 -1
  28. package/dist/.dts/runtime/document.d.ts +7 -4
  29. package/dist/.dts/runtime/document.d.ts.map +1 -1
  30. package/dist/.dts/runtime/index.d.ts +11 -10
  31. package/dist/.dts/runtime/index.d.ts.map +1 -1
  32. package/dist/.dts/runtime/types.d.ts +16 -0
  33. package/dist/.dts/runtime/types.d.ts.map +1 -1
  34. package/dist/.dts/runtime/validate.d.ts +14 -1
  35. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  36. package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
  37. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
  38. package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
  39. package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
  40. package/dist/.dts7/_ipc/display-path.d.ts +27 -0
  41. package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
  42. package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
  43. package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
  44. package/dist/.dts7/_ipc/glob.d.ts +22 -0
  45. package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
  46. package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
  47. package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
  48. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  49. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  50. package/dist/.dts7/_ipc/typescript.d.ts +20 -0
  51. package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
  52. package/dist/.dts7/build/assemble-project.d.ts +47 -0
  53. package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
  54. package/dist/.dts7/build/change-model.d.ts +63 -0
  55. package/dist/.dts7/build/change-model.d.ts.map +1 -0
  56. package/dist/.dts7/build/check-artifacts.d.ts +48 -0
  57. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
  58. package/dist/.dts7/build/citation-verification.d.ts +62 -0
  59. package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
  60. package/dist/.dts7/build/compatibility.d.ts +83 -0
  61. package/dist/.dts7/build/compatibility.d.ts.map +1 -0
  62. package/dist/.dts7/build/compiler-api.d.ts +12 -0
  63. package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
  64. package/dist/.dts7/build/contract-model.d.ts +93 -0
  65. package/dist/.dts7/build/contract-model.d.ts.map +1 -0
  66. package/dist/.dts7/build/deep-equal.d.ts +9 -0
  67. package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
  68. package/dist/.dts7/build/deep-freeze.d.ts +20 -0
  69. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
  70. package/dist/.dts7/build/dependency-graph.d.ts +170 -0
  71. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
  72. package/dist/.dts7/build/dependency-model.d.ts +81 -0
  73. package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
  74. package/dist/.dts7/build/discover.d.ts +41 -0
  75. package/dist/.dts7/build/discover.d.ts.map +1 -0
  76. package/dist/.dts7/build/display-path.d.ts +6 -0
  77. package/dist/.dts7/build/display-path.d.ts.map +1 -0
  78. package/dist/.dts7/build/docs.d.ts +176 -0
  79. package/dist/.dts7/build/docs.d.ts.map +1 -0
  80. package/dist/.dts7/build/env-example.d.ts +85 -0
  81. package/dist/.dts7/build/env-example.d.ts.map +1 -0
  82. package/dist/.dts7/build/errors.d.ts +78 -0
  83. package/dist/.dts7/build/errors.d.ts.map +1 -0
  84. package/dist/.dts7/build/evidence-cache.d.ts +74 -0
  85. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
  86. package/dist/.dts7/build/evidence-model.d.ts +50 -0
  87. package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
  88. package/dist/.dts7/build/evidence-reference.d.ts +67 -0
  89. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
  90. package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
  91. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
  92. package/dist/.dts7/build/exclusive-group.d.ts +19 -0
  93. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
  94. package/dist/.dts7/build/finding-model.d.ts +80 -0
  95. package/dist/.dts7/build/finding-model.d.ts.map +1 -0
  96. package/dist/.dts7/build/generate-documentation.d.ts +176 -0
  97. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
  98. package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
  99. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
  100. package/dist/.dts7/build/generate-evidence.d.ts +77 -0
  101. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
  102. package/dist/.dts7/build/generate-manifest.d.ts +101 -0
  103. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
  104. package/dist/.dts7/build/generate-usage.d.ts +95 -0
  105. package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
  106. package/dist/.dts7/build/generated-banner.d.ts +43 -0
  107. package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
  108. package/dist/.dts7/build/glob.d.ts +6 -0
  109. package/dist/.dts7/build/glob.d.ts.map +1 -0
  110. package/dist/.dts7/build/governance-fields.d.ts +34 -0
  111. package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
  112. package/dist/.dts7/build/humanize-key.d.ts +14 -0
  113. package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
  114. package/dist/.dts7/build/index.d.ts +105 -0
  115. package/dist/.dts7/build/index.d.ts.map +1 -0
  116. package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
  117. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
  118. package/dist/.dts7/build/link.d.ts +223 -0
  119. package/dist/.dts7/build/link.d.ts.map +1 -0
  120. package/dist/.dts7/build/literal-eval.d.ts +24 -0
  121. package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
  122. package/dist/.dts7/build/live-expirations.d.ts +47 -0
  123. package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
  124. package/dist/.dts7/build/manifest.d.ts +31 -0
  125. package/dist/.dts7/build/manifest.d.ts.map +1 -0
  126. package/dist/.dts7/build/map-utils.d.ts +8 -0
  127. package/dist/.dts7/build/map-utils.d.ts.map +1 -0
  128. package/dist/.dts7/build/merge-documentation.d.ts +35 -0
  129. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
  130. package/dist/.dts7/build/ownership-model.d.ts +59 -0
  131. package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
  132. package/dist/.dts7/build/parse.d.ts +207 -0
  133. package/dist/.dts7/build/parse.d.ts.map +1 -0
  134. package/dist/.dts7/build/reference-projections.d.ts +170 -0
  135. package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
  136. package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
  137. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
  138. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
  139. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
  140. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
  141. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
  142. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
  143. package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
  144. package/dist/.dts7/build/sarif.d.ts +66 -0
  145. package/dist/.dts7/build/sarif.d.ts.map +1 -0
  146. package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
  147. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
  148. package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
  149. package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
  150. package/dist/.dts7/build/source-position.d.ts +69 -0
  151. package/dist/.dts7/build/source-position.d.ts.map +1 -0
  152. package/dist/.dts7/build/tool-version.d.ts +8 -0
  153. package/dist/.dts7/build/tool-version.d.ts.map +1 -0
  154. package/dist/.dts7/build/types.d.ts +7 -0
  155. package/dist/.dts7/build/types.d.ts.map +1 -0
  156. package/dist/.dts7/build/typescript.d.ts +6 -0
  157. package/dist/.dts7/build/typescript.d.ts.map +1 -0
  158. package/dist/.dts7/build/usage-report.d.ts +124 -0
  159. package/dist/.dts7/build/usage-report.d.ts.map +1 -0
  160. package/dist/.dts7/cli/filesystem.d.ts +7 -0
  161. package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
  162. package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
  163. package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
  164. package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
  165. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
  166. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
  167. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
  168. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
  169. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
  170. package/dist/.dts7/evidence/define-projection.d.ts +52 -0
  171. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
  172. package/dist/.dts7/evidence/index.d.ts +23 -0
  173. package/dist/.dts7/evidence/index.d.ts.map +1 -0
  174. package/dist/.dts7/helpers/index.d.ts +135 -0
  175. package/dist/.dts7/helpers/index.d.ts.map +1 -0
  176. package/dist/.dts7/helpers/processors.d.ts +32 -0
  177. package/dist/.dts7/helpers/processors.d.ts.map +1 -0
  178. package/dist/.dts7/helpers/validators.d.ts +68 -0
  179. package/dist/.dts7/helpers/validators.d.ts.map +1 -0
  180. package/dist/.dts7/node/index.d.ts +2 -0
  181. package/dist/.dts7/node/index.d.ts.map +1 -0
  182. package/dist/.dts7/runtime/cache.d.ts +17 -0
  183. package/dist/.dts7/runtime/cache.d.ts.map +1 -0
  184. package/dist/.dts7/runtime/create.d.ts +23 -0
  185. package/dist/.dts7/runtime/create.d.ts.map +1 -0
  186. package/dist/.dts7/runtime/document.d.ts +223 -0
  187. package/dist/.dts7/runtime/document.d.ts.map +1 -0
  188. package/dist/.dts7/runtime/errors.d.ts +55 -0
  189. package/dist/.dts7/runtime/errors.d.ts.map +1 -0
  190. package/dist/.dts7/runtime/index.d.ts +25 -0
  191. package/dist/.dts7/runtime/index.d.ts.map +1 -0
  192. package/dist/.dts7/runtime/registry.d.ts +12 -0
  193. package/dist/.dts7/runtime/registry.d.ts.map +1 -0
  194. package/dist/.dts7/runtime/reset.d.ts +8 -0
  195. package/dist/.dts7/runtime/reset.d.ts.map +1 -0
  196. package/dist/.dts7/runtime/types.d.ts +191 -0
  197. package/dist/.dts7/runtime/types.d.ts.map +1 -0
  198. package/dist/.dts7/runtime/validate.d.ts +27 -0
  199. package/dist/.dts7/runtime/validate.d.ts.map +1 -0
  200. package/dist/{build-LFHPVDQL.js → build-DNAYWD2B.js} +8 -5
  201. package/dist/build-DNAYWD2B.js.map +1 -0
  202. package/dist/build.cjs +7 -4
  203. package/dist/build.cjs.map +1 -1
  204. package/dist/build.js +7 -4
  205. package/dist/build.js.map +1 -1
  206. package/dist/build.ts7.d.cts +1 -0
  207. package/dist/build.ts7.d.ts +1 -0
  208. package/dist/{chunk-ZW3BLAPD.js → chunk-HAGMVMN5.js} +2 -2
  209. package/dist/cli/index.js +3 -3
  210. package/dist/eslint-plugin/index.cjs +8 -5
  211. package/dist/eslint-plugin/index.cjs.map +1 -1
  212. package/dist/eslint-plugin/index.js +8 -5
  213. package/dist/eslint-plugin/index.js.map +1 -1
  214. package/dist/eslint-plugin/index.ts7.d.cts +1 -0
  215. package/dist/eslint-plugin/index.ts7.d.ts +1 -0
  216. package/dist/evidence.ts7.d.cts +1 -0
  217. package/dist/evidence.ts7.d.ts +1 -0
  218. package/dist/helpers.ts7.d.cts +1 -0
  219. package/dist/helpers.ts7.d.ts +1 -0
  220. package/dist/index.cjs.map +1 -1
  221. package/dist/index.js.map +1 -1
  222. package/dist/index.ts7.d.cts +1 -0
  223. package/dist/index.ts7.d.ts +1 -0
  224. package/dist/node.ts7.d.cts +1 -0
  225. package/dist/node.ts7.d.ts +1 -0
  226. package/examples/README.md +46 -80
  227. package/package.json +37 -6
  228. package/schemas/env-cap-report.schema.json +1 -1
  229. package/skills/env-cap/SKILL.md +1 -1
  230. package/skills/env-cap/references/api.md +1 -1
  231. package/specs/architecture.md +2 -2
  232. package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
  233. package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
  234. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
  235. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
  236. package/specs/generated-artifacts.md +14 -2
  237. package/dist/build-LFHPVDQL.js.map +0 -1
  238. /package/dist/{chunk-ZW3BLAPD.js.map → chunk-HAGMVMN5.js.map} +0 -0
package/GUIDE.md CHANGED
@@ -1,73 +1,27 @@
1
1
  # env-cap Guide
2
2
 
3
- The reference manual: capability-owned contracts in depth, the full generate/validate workflow, validation contexts, reusable packages, tsconfig path aliases, runtime/build-time architecture, migration notes, the security model, troubleshooting, the CLI, the GitHub Action, the ESLint plugin, and performance characteristics.
4
-
5
- For the pitch, quick start, and adoption reasoning, see [README.md](README.md). For why the package is built the way it is, see [specs/architecture.md](specs/architecture.md) and the [ADRs](specs/decisions/).
6
-
7
- - [Documented example](#documented-example)
8
- - [Capability-owned contracts](#capability-owned-contracts)
9
- - [Helpers](#helpers)
10
- - [Core workflow](#core-workflow)
11
- - [Runtime support matrix](#runtime-support-matrix)
12
- - [Validation contexts](#validation-contexts)
13
- - [Reusable packages](#reusable-packages)
14
- - [TypeScript path aliases (paths/baseUrl)](#typescript-path-aliases-pathsbaseurl)
15
- - [Architecture](#architecture)
16
- - [Migration](#migration)
17
- - [Security model](#security-model)
18
- - [Troubleshooting](#troubleshooting)
19
- - [CLI](#cli)
20
- - [GitHub Action](#github-action)
21
- - [ESLint plugin](#eslint-plugin)
22
- - [Performance characteristics](#performance-characteristics)
23
-
24
- ## Documented example
25
-
26
- Most applications start with a centralized environment configuration model:
3
+ Find your entry point in the table below; its section starts with the problem it solves and states each limit next to its promise. Snippets name the CI-run file they come from, or say they are illustrative.
27
4
 
28
- ```ts
29
- // src/env.ts
30
-
31
- import { createEnv } from "@maverickcer/env-cap"
32
-
33
- const schema = {
34
- DATABASE_URL: {
35
- validator(value: string) {
36
- return value.startsWith("postgres://") || "Expected a PostgreSQL connection string."
37
- },
38
- },
39
-
40
- STRIPE_KEY: {
41
- validator(value: string) {
42
- return value.startsWith("sk_") || 'Expected a Stripe secret key starting with "sk_".'
43
- },
44
- },
5
+ For the overview and quick start, read [README.md](README.md). For the reasons behind the design, read [specs/architecture.md](specs/architecture.md) and the [ADRs](specs/decisions/).
45
6
 
46
- SENDGRID_API_KEY: {
47
- validator(value: string) {
48
- return value.startsWith("SG.") || "Expected a SendGrid API key."
49
- },
50
- },
51
- }
52
-
53
- export const env = createEnv(schema)
54
- ```
7
+ ## Find your part
55
8
 
56
- This approach works well while one application owns all configuration decisions.
9
+ | You are | Entry point | Start at |
10
+ | -------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------- |
11
+ | An application developer bitten by an undefined variable | `@maverickcer/env-cap` | [The runtime](#application-developers-the-runtime) |
12
+ | The same developer writing processors and validators | `@maverickcer/env-cap/helpers` | [Helpers](#application-developers-helpers) |
13
+ | A platform engineer who owns the CI pipeline | `@maverickcer/env-cap/build`, the CLI, the GitHub Action | [Generating artifacts](#platform-engineers-generating-artifacts) |
14
+ | A reviewer who needs an inventory of secrets and owners | `@maverickcer/env-cap/evidence` | [Evidence](#reviewers-evidence) |
15
+ | A build-script author on Node | `@maverickcer/env-cap/node` | [The Node adapter](#build-script-authors-the-node-adapter) |
16
+ | A lint owner | `@maverickcer/env-cap/eslint-plugin` | [ESLint plugin](#eslint-plugin) |
57
17
 
58
- As applications grow, the challenge becomes understanding the relationship between configuration and the capabilities that depend on it:
18
+ ## Application developers: the runtime
59
19
 
60
- - Which feature requires `STRIPE_KEY`?
61
- - Can this variable be removed when a feature is removed?
62
- - Who owns its rotation?
63
- - Which service depends on this secret?
64
- - Is this configuration still required?
20
+ **What it solves:** your application fails at startup with every bad variable's name, never its value, instead of crashing later in a request.
65
21
 
66
- `env-cap` can move those contracts closer to the capabilities that consume them, while still generating a complete application-wide view when teams need operational visibility.
22
+ ### Capability-owned contracts
67
23
 
68
- ## Capability-owned contracts
69
-
70
- Each capability defines its own environment requirements while the application can still generate a complete project-wide view.
24
+ Each feature 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).
71
25
 
72
26
  ```ts
73
27
  // features/payments/env.schema.ts
@@ -82,138 +36,41 @@ const paymentsSchema = {
82
36
  },
83
37
  }
84
38
 
85
- export const paymentsEnv = createEnv(paymentsSchema, {
86
- name: "payments",
87
- })
39
+ export const paymentsEnv = createEnv(paymentsSchema, { name: "payments" })
88
40
 
89
41
  documentEnv(paymentsSchema, {
90
42
  category: "Payments",
91
43
  owner: "payments-team",
92
- metadata: {
93
- service: "Payment Processing API",
94
- criticality: "Production-critical",
95
- },
96
44
  variables: {
97
45
  STRIPE_KEY: {
98
- description:
99
- "Stripe secret API key used by the payment service to create charges and process refunds.",
46
+ description: "Stripe secret key used to create charges and process refunds.",
100
47
  owner: "payments-team",
101
48
  expiresAt: "2027-01-01",
102
- refreshInstructions: "Rotate in AWS Secrets Manager, then redeploy. Rotate every 90 days.",
49
+ refreshInstructions: "Rotate in AWS Secrets Manager, then redeploy.",
103
50
  sensitivity: "secret",
104
- metadata: {
105
- storageProvider: "AWS Secrets Manager",
106
- accessPolicy: "Restricted to payment service runtime credentials.",
107
- validationReason:
108
- "Ensures the payment service cannot start with missing or malformed Stripe credentials.",
109
- },
110
51
  },
111
52
  },
112
53
  })
113
54
  ```
114
55
 
115
- The application still receives one validated startup boundary:
56
+ `createEnv()` takes what validation needs: `default`, `processor`, `validator` and `context`. `documentEnv()` takes what people need: owners, descriptions and expiry dates. `documentEnv()` has no runtime effect (`test/runtime/document.test.ts`), but its literals ship in any bundle that imports the file.
116
57
 
117
- ```ts
118
- await validateEnv({
119
- manifest,
120
- values: process.env,
121
- })
122
- ```
123
-
124
- But ownership follows usage:
58
+ There is no global `env` object. Code reads a value through the contract that owns it:
125
59
 
126
60
  ```ts
127
61
  paymentsEnv.STRIPE_KEY
128
62
  ```
129
63
 
130
- The capability that owns the dependency owns access to it. There is no global configuration object requiring every capability to access configuration through a centralized namespace:
131
-
132
- ```ts
133
- env.payments.STRIPE_KEY
134
- ```
135
-
136
- Instead, each capability exposes only the configuration it owns.
137
-
138
- At application startup, `validateEnv()` provides fail-fast verification across the complete application when paired with a generated manifest:
139
-
140
- ```ts
141
- import { validateEnv } from "@maverickcer/env-cap"
142
- import { manifest } from "./generated/env.manifest"
143
-
144
- await validateEnv({
145
- manifest,
146
- values: process.env,
147
- })
148
- ```
149
-
150
- The generated manifest provides a complete project-wide view without requiring runtime centralization. `validateEnv()` discovers every registered capability contract, validates required environment dependencies before the application serves traffic, and aggregates failures into a single validation error.
151
-
152
- This allows teams to maintain local ownership while preserving operational visibility:
153
-
154
- - Missing variables are detected before the application serves traffic.
155
- - Invalid values across multiple capabilities are reported together instead of failing one at a time.
156
- - Each capability retains ownership of its validation rules.
157
- - Operations teams maintain visibility into application-wide configuration requirements.
158
-
159
- Runtime access remains capability-scoped, while validation remains application-wide.
160
-
161
- ## Helpers
162
-
163
- `@maverickcer/env-cap/helpers` provides optional convenience functions for common processor and validator patterns.
164
-
165
- Helpers are intentionally not the core `env-cap` workflow. They are provided for smaller applications, prototypes, and straightforward configuration requirements where a lightweight convenience API is useful.
166
-
167
- Already using Zod, envalid, or another validation library? Keep it and integrate it directly with env-cap contracts — helpers exist for when a lighter API is enough, not as a reason to switch.
168
-
169
- ```ts
170
- import { createEnv } from "@maverickcer/env-cap"
171
- import { processors, validators } from "@maverickcer/env-cap/helpers"
172
-
173
- export const databaseEnv = createEnv(
174
- {
175
- DATABASE_URL: {
176
- processor: processors.toURL(),
177
- validator: validators.required(),
178
- },
179
-
180
- PORT: {
181
- default: 5432,
182
- processor: processors.toNumber(),
183
- validator: validators.range(1, 65535),
184
- },
185
- },
186
- {
187
- name: "database",
188
- },
189
- )
190
- ```
191
-
192
- Available helpers include common processors and validators with composition utilities. They can be
193
- found at [src/helpers/index.ts](https://github.com/MaverickCER/env-cap/blob/main/src/helpers/index.ts)
194
-
195
- When possible, prefer validation rules that communicate domain intent directly alongside the capability contract. These may be custom `Processor<T>` and `Validator<T>` functions or existing validators from your application's validation stack.
196
-
197
- ```ts
198
- validator(value: string) {
199
- return value.startsWith("sk_") ||
200
- 'Expected a Stripe secret key starting with "sk_".';
201
- }
202
- ```
203
-
204
- A named validation rule explains why the dependency exists and gives future maintainers context that a generic helper cannot always provide.
205
-
206
- The helper package is optional and has no impact on the core runtime when unused. When all runtime features are included, the runtime entry point remains within its 3 KB gzip budget and `./helpers` within its 4 KB one. `createEnv()` and `validateEnv()` remain the core APIs and provide the foundation for capability-owned configuration, while helpers provide convenient building blocks for common processor and validator patterns.
207
-
208
- ## Core workflow
64
+ Validation stays application-wide. One `validateEnv()` call checks every contract in the generated manifest and reports every failure in one `EnvValidationError` (`test/runtime/validate.test.ts`).
209
65
 
210
- ### 1. Define your environment contract
66
+ ### Core workflow
211
67
 
212
- `env-cap` works with both centralized configuration and capability-owned contracts.
68
+ #### 1. Define your environment contract
213
69
 
214
- For existing applications, start by wrapping your current environment requirements:
70
+ Start with one central contract if that is what you have. This snippet is illustrative; [`examples/application/src/env.ts`](https://github.com/MaverickCER/env-cap/blob/main/examples/application/src/env.ts) is the central contract CI runs.
215
71
 
216
72
  ```ts
73
+ // src/env.ts
217
74
  import { createEnv } from "@maverickcer/env-cap"
218
75
 
219
76
  export const env = createEnv(
@@ -223,253 +80,81 @@ export const env = createEnv(
223
80
  return value.startsWith("postgres://") || "Expected a PostgreSQL connection string."
224
81
  },
225
82
  },
226
- PORT: {
227
- default: 3000,
228
- processor(value: string) {
229
- return Number(value)
230
- },
231
- },
232
- },
233
- {
234
- name: "application",
83
+ PORT: { default: 3000, processor: (value: string) => Number(value) },
235
84
  },
85
+ { name: "application" },
236
86
  )
237
87
  ```
238
88
 
239
- As applications grow, contracts can move closer to the capabilities that consume them:
240
-
241
- ```text
242
- src/
243
- ├── features/
244
- │ ├── payments/
245
- │ │ └── env.schema.ts
246
- │ ├── database/
247
- │ │ └── env.schema.ts
248
- │ └── notifications/
249
- │ └── env.schema.ts
250
- ```
251
-
252
- A capability can also be a reusable package:
89
+ Move contracts next to the features that consume them when ownership starts to matter. The runtime model does not change:
253
90
 
254
91
  ```text
255
- packages/
256
- └── paypal-addon/
257
- └── src/env.schema.ts
92
+ src/features/payments/env.schema.ts
93
+ src/features/database/env.schema.ts
94
+ packages/paypal-addon/src/env.schema.ts
258
95
  ```
259
96
 
260
- The ownership model is identical whether the contract belongs to the application, an internal package, or a published dependency.
97
+ [`examples/application`](https://github.com/MaverickCER/env-cap/tree/main/examples/application) keeps one contract; [`examples/team-service`](https://github.com/MaverickCER/env-cap/tree/main/examples/team-service) splits it per feature.
261
98
 
262
- ### 2. Generate the project view
99
+ #### 2. Generate the project view
263
100
 
264
- During development or CI:
101
+ A build step, run in development or CI, writes the manifest your startup code imports. The platform engineer's section covers the options; the short form is the CLI:
265
102
 
266
- ```ts
267
- import { generateEnvManifest } from "@maverickcer/env-cap/build"
268
-
269
- await generateEnvManifest({
270
- location: "src/generated/env.manifest.ts",
271
- })
103
+ ```sh
104
+ npx env-cap --location src/generated/env.manifest.ts --evidence docs/env.evidence.json
272
105
  ```
273
106
 
274
- The build process creates the application-wide view required for:
275
-
276
- - environment manifests
277
- - documentation
278
- - `.env.example` files
279
- - configuration reports
280
-
281
- Every one of these draws a hard line between **declared** facts (author
282
- metadata — `owner`, `sensitivity`, `expiresAt`, `retention` — presence is
283
- checked, correctness never is) and **proven** facts (AST-derived —
284
- `UNCONSUMED_OWNED_VARIABLE`, the dependency graph). See
285
- [`specs/generated-artifacts.md`](specs/generated-artifacts.md) for the full
286
- list of what's generated today, the seven canonical fact models each one
287
- projects from, and what's deliberately deferred.
288
-
289
- Schemas are analyzed statically.
290
-
291
- They are never imported or executed during discovery.
292
-
293
- This provides project-wide visibility without requiring runtime configuration to become centralized.
294
-
295
- #### Change tracking via the persisted evidence artifact
296
-
297
- `generateEnvManifest()` no longer tracks its own change history — that moved to a separate, optional
298
- artifact: the full `EvidenceModel`, env-cap's canonical fact model covering the contract graph,
299
- dependency/ownership findings, lifecycle data, and a change report diffed against whatever was
300
- previously persisted. `generateEnvArtifacts()` always computes it; passing `evidence` also writes it
301
- to disk:
302
-
303
- ```ts
304
- const result = await generateEnvArtifacts({
305
- manifest: { location: "src/generated/env.manifest.ts" },
306
- evidence: { location: "docs/env.evidence.json" },
307
- })
308
-
309
- console.log(result.evidence.change.manifest.addedVariables) // newly documented this run
310
- console.log(result.evidence.change.manifest.updatedVariables) // field-level before/after for anything that changed
311
- console.log(result.evidence.change.manifest.removedVariables) // no longer discovered at all
312
- ```
107
+ Schema files are parsed, never imported or run (`test/build/parse.test.ts`). 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.
313
108
 
314
- `evidence.location` is independent of `manifest.location` — requesting it needs no other pass, and a
315
- project with no `.ts` manifest at all can still generate a pure evidence report. Writing it also
316
- writes a paired `docs/env.evidence.json.fingerprint` sidecar, a cheap content hash a later read
317
- (`getEvidenceModel()`, for a report/projection script that doesn't want to pay for a full recompute
318
- on every invocation) uses to skip regenerating when nothing relevant has changed.
319
-
320
- **Commit both files, the same as you already commit `env.manifest.ts` itself.** "Since last
321
- execution" means since the last commit on your branch — that's what makes the diff meaningful in CI and
322
- reviewable in a pull request, not just a local curiosity. See
323
- [ADR 0038](specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md) for the
324
- full reasoning (superseding [ADR 0021](specs/decisions/0021-manifest-change-report-persisted-snapshot.md)'s
325
- original manifest-adjacent design).
326
-
327
- - **A diff is expected** any time a `documentEnv()` call's `description`/`owner`/`expiresAt`/
328
- `refreshInstructions`/`required`/`extra` changes, or a contract's `active`/`category`/`exclusiveGroup`
329
- changes — anything that isn't schema shape itself.
330
- - **Regeneration is automatic.** Every `generate:env`/CI run that passes `--evidence` already
331
- rewrites both files; there's no separate "update the snapshot" step to remember.
332
- - **A diff signals real drift worth a second look** when it shows up somewhere nobody meant to touch —
333
- an `updatedVariables` entry for a variable nobody intended to edit, or an `addedContracts`/
334
- `removedContracts` entry from a change that was supposed to be unrelated.
335
-
336
- The CLI's normal (non-`--check`) output prints the same summary as an "Evidence changes since the
337
- last persisted snapshot" section whenever `--evidence <path>` is passed; run with `--json --evidence
338
- <path>` for the same data in machine-readable form.
339
-
340
- Separately, when two _active_ contracts document the same variable key with different metadata (e.g. two
341
- features that happen to reuse a name, each with its own `description`/`owner`), that's reported as a
342
- `duplicate-variable-documentation` warning in `result.warnings` — always a warning, never a hard error
343
- (static analysis can't prove two descriptions are "wrong," only different), gated by the same
344
- `onIncompatibility` option as every other compatibility warning.
345
-
346
- ### 3. Validate once during startup
109
+ #### 3. Validate once during startup
347
110
 
348
111
  ```ts
349
112
  import { validateEnv } from "@maverickcer/env-cap"
350
113
  import { manifest } from "./generated/env.manifest"
351
114
 
352
- await validateEnv({
353
- manifest,
354
- values: process.env,
355
- })
356
- ```
357
-
358
- At startup, `validateEnv()` verifies the complete application environment boundary.
359
-
360
- After validation:
361
-
362
- ```ts
363
- env.DATABASE_URL
364
- ```
365
-
366
- or:
367
-
368
- ```ts
369
- paymentsEnv.STRIPE_KEY
115
+ await validateEnv({ manifest, values: process.env })
370
116
  ```
371
117
 
372
- returns the processed value according to the contract that owns it.
118
+ What happens, and where each rule is tested:
373
119
 
374
- Before validation completes:
120
+ | Situation | Result | Test |
121
+ | ---------------------------------------------- | --------------------------------------------------------------------- | ------------------------------- |
122
+ | A contract is read before `validateEnv()` ends | Throws `EnvNotReadyError` | `test/runtime/create.test.ts` |
123
+ | Several variables fail | One `EnvValidationError` lists every failure | `test/runtime/validate.test.ts` |
124
+ | A failure message | Carries variable and contract names and your message, never the value | `test/runtime/validate.test.ts` |
125
+ | `validateEnv()` is called again | Returns or rethrows the first outcome without re-running validators | `test/runtime/validate.test.ts` |
126
+ | A test needs a fresh run | `resetEnvCache()` clears the cached outcome | `test/runtime/reset.test.ts` |
375
127
 
376
- ```ts
377
- paymentsEnv.STRIPE_KEY
378
- ```
379
-
380
- throws:
381
-
382
- ```ts
383
- EnvNotReadyError
384
- ```
128
+ The record of validated values is frozen. The freeze is shallow: an object, array or `URL` that a processor returns stays mutable.
385
129
 
386
- Validation failures are aggregated:
387
-
388
- ```ts
389
- EnvValidationError
390
- ```
391
-
392
- so applications receive the complete startup failure state instead of discovering missing or invalid variables one at a time.
393
-
394
- Runtime access can remain centralized for simpler applications or become capability-scoped as ownership boundaries grow. Validation remains application-wide.
395
-
396
- `validateEnv()` is idempotent for the life of the process: the first call's outcome (success or `EnvValidationError`) is cached and returned by every later call, without re-running any processor or validator — by design, since a real application validates once at startup and every later read should see that same, stable outcome. A test suite or a script that intentionally validates different `values` in the same process (as opposed to a real app's single startup call) needs `resetEnvCache()` between runs:
130
+ A test suite that validates several scenarios in one process resets between them:
397
131
 
398
132
  ```ts
399
133
  import { resetEnvCache, validateEnv } from "@maverickcer/env-cap"
400
134
 
401
135
  await validateEnv({ manifest, values: scenarioA })
402
136
  resetEnvCache()
403
- await validateEnv({ manifest, values: scenarioB }) // re-runs validation from scratch
137
+ await validateEnv({ manifest, values: scenarioB })
404
138
  ```
405
139
 
406
- Without it, a second `validateEnv()` call with different `values` silently returns the first run's cached result instead of re-validating.
407
-
408
- ## Runtime support matrix
409
-
410
- | Environment | `.` (runtime) | `./helpers` | `./build` (CLI/tooling) |
411
- | -------------------------------------------------------------- | ----------------------------- | ----------- | ------------------------------------------------------------- |
412
- | Node.js 22+ (CJS or ESM) | ✅ | ✅ | ✅ |
413
- | Browser bundle (Webpack/Vite/esbuild/etc.) | ✅ | ✅ ¹ | ❌ not applicable — build-only, never bundle this into an app |
414
- | Edge/serverless (Cloudflare Workers, Vercel Edge, Deno Deploy) | ✅ | ✅ ¹ | ❌ not applicable |
415
- | Bun | ✅ (conformance-tested in CI) | ✅ | ✅ |
416
- | Deno | ✅ (conformance-tested in CI) | ✅ | ✅ |
417
-
418
- ¹ Except `processors.base64()`, which returns a Node `Buffer`: use it only where `Buffer` exists, or decode with your own processor elsewhere.
419
-
420
- The runtime (`.` and `./helpers`) has zero dependencies, never touches the filesystem, and never imports a Node module (the one Node global it uses is the `Buffer` that `processors.base64()` returns) — see [`specs/architecture.md`](specs/architecture.md). `./build` is Node-only developer tooling (uses `node:path` and the TypeScript compiler API — never `node:fs`, see [ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md)) meant for CI/npm-script use, never for shipping to a browser. Both ESM and CommonJS builds are published for every entry point (`package.json#exports`).
421
-
422
- ### Requirements
423
-
424
- Node.js `>=22`. TypeScript 5, 6 or 7 is only required for build-time manifest generation: a bundled TypeScript 6 parses the schemas when yours is 7, is bundled inside the package and used only by the build entry, and adds about 24 MB unpacked to the install. The runtime works in plain JavaScript. TypeScript consumers need `moduleResolution` set to `node16`, `nodenext` or `bundler` to resolve the subpath exports (`./build`, `./helpers`, ...); the legacy `node10` resolver is not supported. `@maverickcer/env-cap/eslint-plugin` also needs `@typescript-eslint/utils` installed (an optional peer).
425
-
426
- ## Validation contexts
140
+ Without `resetEnvCache()`, the second call returns the first call's result.
427
141
 
428
- A schema entry may declare which **validation context** it belongs to. `validateEnv()` accepts the validation
429
- contexts active for a given run, and skips every variable that doesn't match:
142
+ ### Validation contexts
430
143
 
431
- ```ts
432
- DATABASE_URL: {
433
- context: "server",
434
- validator: validators.required(),
435
- }
436
- ```
437
-
438
- ```ts
439
- await validateEnv({
440
- manifest,
441
- values: process.env,
442
- activeContexts: ["server"],
443
- })
444
- ```
445
-
446
- **Matching rule:** a variable with no `context` participates in every run. A variable with a `context`
447
- participates only when `activeContexts` contains that exact string — no prefix matching, wildcards, or
448
- hierarchy. A skipped variable never runs its `default`/`processor`/`validator`, and reading it throws
449
- `EnvNotReadyError`, exactly as if `validateEnv()` had never run for it.
450
-
451
- `context` is entirely application-defined — env-cap never interprets, detects, or infers it. `"server"` and
452
- `"client"` are just one example; a validation context can represent anything a validation run needs to
453
- distinguish:
144
+ A variable can belong to one validation context, a plain string your application chooses. These snippets are illustrative; the CI-run fixture is [`validation-contexts`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/team/validation-contexts).
454
145
 
455
146
  ```ts
456
147
  DATABASE_URL: { context: "server", validator: validators.required() }
457
148
  STRIPE_LIVE_KEY: { context: "production", validator: validators.required() }
458
149
  QUEUE_CONCURRENCY: { context: "worker", default: 4 }
459
- DEBUG_TRACE_ENDPOINT: { context: "development" }
460
150
  ```
461
151
 
462
- A run may activate more than one context at once — `activeContexts: ["server", "production"]` matches a
463
- variable declaring either. This works the same regardless of framework: `env-cap` never inspects `window` or
464
- `NODE_ENV` itself, the application computes `activeContexts` once, explicitly, before calling `validateEnv()`:
152
+ Pass the contexts that apply to this process:
465
153
 
466
154
  ```ts
467
- // Works the same in a Next.js, TanStack Start, or plain Node app -- env-cap
468
- // never inspects window/NODE_ENV itself; the application does, once, before
469
- // calling validateEnv().
470
155
  await validateEnv({
471
- values: typeof window === "undefined" ? process.env : window.__ENV__,
472
156
  manifest,
157
+ values: process.env,
473
158
  activeContexts: [
474
159
  typeof window === "undefined" ? "server" : "client",
475
160
  process.env.NODE_ENV === "production" ? "production" : "development",
@@ -477,412 +162,261 @@ await validateEnv({
477
162
  })
478
163
  ```
479
164
 
480
- When at least one variable declares a `context`, the generated manifest also exports every context it found,
481
- named to match `activeContexts` itself so it can be passed straight through:
165
+ A variable takes part in a run by these rules:
482
166
 
483
- ```ts
484
- // src/generated/env.manifest.ts (generated)
485
- export const activeContexts = ["client", "server"]
486
- export const manifest = [/* ... */]
487
- ```
488
-
489
- ```ts
490
- import { activeContexts, manifest } from "./generated/env.manifest"
491
-
492
- await validateEnv({ manifest, values: process.env, activeContexts })
493
- ```
167
+ 1. A variable with no `context` takes part in every run.
168
+ 2. A variable with a `context` takes part only when `activeContexts` contains that exact string.
169
+ 3. A skipped variable runs no default, processor or validator, and reading it throws `EnvNotReadyError`.
170
+ 4. env-cap never inspects `window` or `NODE_ENV`; your code computes `activeContexts`.
494
171
 
495
- This is every context the manifest has — a convenient starting point, not a pre-scoped default. Importing it
496
- unmodified into every process defeats the point of scoping contexts per deployment target in the first place;
497
- narrow it (or import it under another name and filter it) the same way `src/server.ts`/`src/client.ts` in
498
- [`test/integration/positive/team/validation-contexts`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/team/validation-contexts)
499
- each hand-write their own narrowed `activeContexts: ["server"]` / `["client"]` instead of using this
500
- export directly.
172
+ When any variable declares a context, the generated manifest also exports `activeContexts`, listing every context it found. Treat it as a starting point and narrow it per process, as [`validation-contexts`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/team/validation-contexts) does.
501
173
 
502
- > **Validation contexts are not a bundling or security boundary, and not authorization.** They control whether
503
- > `validateEnv()` processes a variable — nothing else. Putting a `context: "server"` variable in the same
504
- > schema as `context: "client"` variables, feeding one manifest that a client bundle imports, does **not**
505
- > keep the server-context variable's definition (including any literal `default`) out of that bundle —
506
- > `activeContexts` filtering happens after the schema is already wherever it's going to be. If a variable must
507
- > never reach a browser bundle at all, keep using separate discovery/generated manifests per contract (see
508
- > ["Runtime and build-time are intentionally separate"](#architecture)
509
- > and [ADR 0004](specs/decisions/0004-no-client-server-package-split.md)) — validation contexts are a
510
- > complement to that boundary, not a replacement for it. Likewise, a string like `context: "admin"` does not
511
- > restrict _who_ can read a value; it only decides whether a given run validates it. See
512
- > [ADR 0022](specs/decisions/0022-validation-contexts.md) for the full set of invariants this feature commits to.
174
+ **Contexts are not a security or bundling boundary.** They decide whether a run validates a variable, nothing else. A `context: "server"` variable in a schema that a client bundle imports still ships its definition and any literal `default`. Keep server-only variables in a separate schema and manifest ([ADR 0004](specs/decisions/0004-no-client-server-package-split.md), [ADR 0022](specs/decisions/0022-validation-contexts.md)).
513
175
 
514
- ## Reusable packages
176
+ ### Security model
515
177
 
516
- A configuration contract can ship as its own installable package instead of living only inside the consuming application's source tree.
517
-
518
- This works for both centralized application schemas and capability-owned contracts. A reusable package can expose the environment requirements it owns, allowing consuming applications to validate and generate visibility artifacts without manually copying configuration definitions.
519
-
520
- See [`test/integration/positive/enterprise/paypal-addon`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/paypal-addon)/[`test/integration/positive/enterprise/paypal-consumer`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/paypal-consumer) for a complete, runnable example (see [`examples/`](examples/) for the three flagship, human-facing examples, and [`test/integration/`](https://github.com/MaverickCER/env-cap/tree/main/test/integration) for every other runnable scenario).
521
-
522
- Discovery still never walks `node_modules` during its general file-discovery pass (`generateEnvManifest()`'s `include`/`exclude` globs), and that guarantee is unconditional.
523
-
524
- Making a package-shipped contract discoverable is an opt-in mechanism (see [`VERSIONING.md`](VERSIONING.md) and [ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md)):
525
-
526
- ```ts
527
- // consuming app's build script
528
- await generateEnvArtifacts({
529
- packages: ["@acme/payments-sdk"], // explicit allowlist -- never implicit
530
- manifest: { location: "src/env.manifest.ts" },
531
- })
532
- ```
178
+ What the runtime refuses to do, and what enforces each refusal:
533
179
 
534
- The publishing package takes on two obligations:
180
+ | The runtime does not | Enforced by | Limit |
181
+ | ------------------------------ | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
182
+ | Touch the filesystem | A lint ban on `node:fs` in `src/` outside the CLI, and the `AmbientCapabilities` tarball scan | The scan is textual |
183
+ | Read `process.env` | The `AmbientCapabilities` scan and the browser-bundle test | `globalThis["process"]` would evade both |
184
+ | Open a network connection | The `ipc/no-network` lint rule on env-cap's own `src/` | Source lint only; the bundled TypeScript compiler is not covered |
185
+ | Show values when logged | `test/runtime/create.test.ts`: `console.log`, `String()`, `JSON.stringify`, templates | Spreading a contract or calling `Object.entries()` reads every value |
186
+ | Put values in errors | `test/runtime/validate.test.ts` | Your own validator or processor message is passed through verbatim |
187
+ | Fetch, store or rotate secrets | No such code exists; `documentEnv()` fields are documentation only | Not a check; read the source |
535
188
 
536
- 1. Declare `"envCap": { "schema": "./src/env.schema.ts" }` in its own `package.json`, pointing at its real, uncompiled `.ts` source (ship that file via `"files": ["dist", "src/env.schema.ts"]` alongside the compiled `dist/` used at runtime).
189
+ Logged, a contract prints a marker instead of its values:
537
190
 
538
- 2. Re-export the `createEnv()`-produced contract under the same name from its main entry point, so:
539
-
540
- ```ts
541
- import { paypalEnv } from "@acme/paypal-addon"
542
- ```
543
-
544
- resolves to the same contract discovered during build-time analysis.
545
-
546
- Resolution never calls `readdir` on `node_modules` — it reads exactly one `package.json` per allow-listed package to find the declared field, then exactly one declared file, validated (path, extension, symlink target, size) before it is parsed.
547
-
548
- See `SECURITY.md`'s "Avoids unnecessary traversal of dependency directories" section for the exact bounds.
549
-
550
- ### Documenting a variable a package already explains
551
-
552
- A variable can be declared in the package's contract and again in the application that consumes it. The application
553
- does not repeat the explanation: it names the variable with only what is its own, and every field it leaves unset is
554
- filled from the package's declaration.
555
-
556
- ```ts
557
- const credentials = { PAYPAL_CLIENT_SECRET: { default: "", validator: () => true } }
558
- export const credentialsEnv = createEnv(credentials, { name: "credentials" })
559
-
560
- documentEnv(credentials, {
561
- variables: { PAYPAL_CLIENT_SECRET: { expiresAt: "2027-01-01", owner: "payments" } },
562
- })
563
- ```
564
-
565
- Both declarations then report the package's `description`, `sensitivity` and `refreshInstructions` together with the
566
- application's `expiresAt` and `owner`. A field the application sets itself is never replaced, and a field both set to
567
- different values is reported as `DUPLICATE_VARIABLE_DOCUMENTATION`. Two of the application's own contracts never fill
568
- each other (a service that can run on either of two databases documents each one's variable for itself); a field
569
- both set differently is still reported. See
570
- [ADR 0050](specs/decisions/0050-a-variable-declared-twice-is-documented-once.md).
571
-
572
- ## TypeScript path aliases (paths/baseUrl)
573
-
574
- If your project organizes its own source with a `tsconfig.json` path alias (`"@/lib/env"`, `"~/schema/env"`, ...), `env-cap` resolves it automatically — no configuration required:
575
-
576
- ```ts
577
- // tsconfig.json
578
- { "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }
579
- ```
580
-
581
- ```ts
582
- // src/consumer.ts
583
- import { paymentsEnv } from "@/features/payments/env.schema.js"
584
- paymentsEnv.STRIPE_KEY
585
- ```
586
-
587
- Without this, a contract only ever imported through an alias would be misreported as `abandoned` in the Dependency & Ownership Report, or its `documentEnv()` call left unlinked — the same class of false positive [ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md)'s ownership engine exists to avoid.
588
-
589
- See [`test/integration/positive/enterprise/tsconfig-aliases`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/tsconfig-aliases) for a complete, runnable example, and [`test/integration/positive/enterprise/tsconfig-aliases-consumer`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/tsconfig-aliases-consumer) for the same producer/consumer pairing [Reusable packages](#reusable-packages) uses — proving this composes correctly with cross-package discovery (ADR 0014) in one real install (see [`examples/`](examples/) for the three flagship, human-facing examples, and [`test/integration/`](https://github.com/MaverickCER/env-cap/tree/main/test/integration) for every other runnable scenario).
590
-
591
- Unlike [Reusable packages](#reusable-packages) above, this is on by default (see [`VERSIONING.md`](VERSIONING.md) and [ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md)): a project's own `tsconfig.json` never crosses a trust/versioning boundary the way an installed package does, so there's no safety reason to require opt-in. `env-cap` auto-detects `tsconfig.json` at `root`, exactly (no upward directory search, unlike bare `tsc`). Pass `tsconfig: "<path>"` to point at a different file (useful in monorepos where the relevant config isn't at `root`), or `tsconfig: false` to disable alias resolution entirely:
592
-
593
- ```ts
594
- await generateEnvArtifacts({
595
- tsconfig: "tsconfig.build.json", // or `false` to disable
596
- manifest: { location: "src/env.manifest.ts" },
597
- })
598
- ```
599
-
600
- The actual `paths`/`baseUrl` matching is delegated entirely to the TypeScript compiler (`ts.resolveModuleName()`, the same function `tsc`/`tsserver` themselves use), never resolves into `node_modules` (that boundary stays exclusively [ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md)'s), and only ever resolves to a real `.ts`/`.tsx` file.
601
-
602
- ## Architecture
603
-
604
- ### Runtime and build-time are intentionally separate
605
-
606
- `env-cap` separates application execution from project-wide analysis.
607
-
608
- ```text
609
- Environment contract
610
- |
611
- |
612
- +----+----+
613
- | |
614
- Runtime Build-time
615
- | |
616
- createEnv AST analysis
617
- | |
618
- validateEnv generate artifacts
619
- |
620
- Typed access
191
+ ```txt
192
+ EnvContract("payments") { 1 variable(s) }
621
193
  ```
622
194
 
623
- Runtime:
195
+ The full model, including what stays your responsibility, is in [SECURITY.md](SECURITY.md).
624
196
 
625
- - validates configuration
626
- - exposes typed values
627
- - contains no filesystem access
628
- - does not discover files dynamically
197
+ ### Troubleshooting
629
198
 
630
- Build-time:
199
+ env-cap defines these error classes. A contract from the other module format throws a `TypeError` ([dual-package hazard](SECURITY.md#dual-package-hazard)), and a processor called outside `validateEnv()` throws a plain `Error`.
631
200
 
632
- - discovers contracts
633
- - generates documentation
634
- - creates manifests and operational visibility artifacts
201
+ | Error | Thrown by | Common cause | Fix |
202
+ | --------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
203
+ | `EnvNotReadyError` | Reading `someEnv.KEY` | The contract was read before `validateEnv()` finished, or its context was not active | Await `validateEnv()` at startup, before application code reads values |
204
+ | `EnvValidationError` | `validateEnv()` | A processor or validator rejected one or more variables | Read `error.failures`: one entry per variable, with names and your message |
205
+ | `EnvManifestGenerationError` | `generateEnvManifest()` | Conflicting explicit processor types for one variable, or `location` outside `root` | Read `error.issues`; fix the definitions or the output path |
206
+ | `EnvDocumentationGenerationError` | `generateDocumentation()` | `location` or `envExample.location` outside `root` | Correct the output path |
207
+ | `EnvUsageAnalysisError` | `generateUsageReport()` | `report.location` outside `root` | Correct the output path |
208
+ | `EnvProjectGenerationError` | `generateEnvArtifacts()` | Any of the above, collected across the requested passes, or an exclusive-group violation | Fix the underlying error; every failure is listed in one result |
635
209
 
636
- This separation keeps application startup deterministic while allowing development and platform workflows to understand the complete configuration surface.
210
+ Documentation and ownership findings never throw. They are reported as findings in the evidence file, and fail a run only under a `--strict*` flag.
637
211
 
638
- A project can begin with a centralized environment contract and adopt capability-owned contracts where ownership boundaries provide value. The runtime model remains the same: contracts define validated access, while build-time tooling provides application-wide visibility.
212
+ **A schema's variable is missing from the manifest.** Discovery reads an inline object literal or a resolvable `const`. A spread or a factory produces a parse warning; read `result.parseWarnings` or the CLI output ([ADR 0002](specs/decisions/0002-static-analysis-never-execution.md)).
639
213
 
640
- For the reasoning behind capability-owned configuration — code ownership, reusable packages, and platform visibility without runtime centralization — see [Why capability ownership?](https://maverickcer.github.io/env-cap/#why-context) on the website, and [specs/architecture.md](specs/architecture.md) for the full technical treatment.
641
-
642
- ## Migration
214
+ **A contract imported through a path alias shows as abandoned.** Check that `tsconfig.json` sits at `root` and declares `paths` or `baseUrl`. Otherwise, point `tsconfig` at the right file. Discovery does not search upward ([path aliases](#typescript-path-aliases-pathsbaseurl)).
643
215
 
644
- `env-cap` is designed for incremental adoption.
216
+ **A listed package's contract is not discovered.** Look for a `(package) <name>` entry in `result.parseWarnings`. The package must declare `envCap.schema` pointing at a `.ts` or `.tsx` file inside itself ([reusable packages](#reusable-packages)).
645
217
 
646
- Keep your existing tools and validation approach. Introduce contracts where they provide value, then move toward stronger ownership boundaries as your application grows.
218
+ **A second `validateEnv()` call returned the first result.** That is the cache ([step 3](#3-validate-once-during-startup)). Call `resetEnvCache()` between scenarios.
647
219
 
648
- ### From dotenv
220
+ **Discovery fails with a "sanity limit" error.** `discoverSchemaFiles` refuses to return more files than `MAX_DISCOVERED_SCHEMA_FILES`. The usual cause is a `root` or `include` far broader than intended, such as an unset `root` falling back to a large working directory. Narrow `root`, `include` or `exclude`.
649
221
 
650
- Continue loading variables with dotenv.
222
+ ## Application developers: helpers
651
223
 
652
- Add validated contracts on top:
224
+ **What it solves:** small, composable processors and validators for when a validation library is more than a variable needs. This snippet is illustrative; [`examples/application/src/env.ts`](https://github.com/MaverickCER/env-cap/blob/main/examples/application/src/env.ts) uses `processors` and `validators` in CI.
653
225
 
654
226
  ```ts
655
227
  import { createEnv } from "@maverickcer/env-cap"
228
+ import { processors, validators } from "@maverickcer/env-cap/helpers"
656
229
 
657
- export const env = createEnv({
658
- DATABASE_URL: {
659
- validator(value: string) {
660
- return value.startsWith("postgres://") || "Expected a PostgreSQL connection string."
230
+ export const databaseEnv = createEnv(
231
+ {
232
+ DATABASE_URL: { processor: processors.toURL(), validator: validators.required() },
233
+ PORT: {
234
+ default: 5432,
235
+ processor: processors.toNumber(),
236
+ validator: validators.range(1, 65535),
661
237
  },
662
238
  },
663
- })
239
+ { name: "database" },
240
+ )
664
241
  ```
665
242
 
666
- No loader replacement is required.
667
-
668
- ### From process.env
243
+ - **The `Buffer` caveat:** `processors.base64()` returns a Node `Buffer`. Use it only where `Buffer` exists, or decode with your own processor. Every other helper uses Web globals only (`test/runtime/browser-bundle.test.ts`).
244
+ - **Cost:** `./helpers` stays under 4 KB gzip, enforced by the `Size` check. Unused helpers are dropped by esbuild (`test/helpers/tree-shaking.test.ts`); other bundlers are not tested.
245
+ - **Messages:** a processor that receives `undefined` or `null` names the type, not the value (`test/helpers/processors.test.ts`).
246
+ - **Optional:** keep Zod, envalid or your own functions if you have them. Any function returning `true` or a message works as a validator.
669
247
 
670
- Replace scattered access:
248
+ The full list is in the [API reference](https://maverickcer.github.io/env-cap/api/) and [src/helpers/index.ts](https://github.com/MaverickCER/env-cap/blob/main/src/helpers/index.ts).
671
249
 
672
- ```ts
673
- process.env.STRIPE_KEY
674
- ```
675
-
676
- with validated contract access:
250
+ ## Platform engineers: generating artifacts
677
251
 
678
- ```ts
679
- env.STRIPE_KEY
680
- ```
252
+ **What it solves:** generated manifests, documentation that cannot go stale, and drift that fails a pull request instead of reaching production.
681
253
 
682
- As ownership boundaries become useful, contracts can move closer to the capabilities that consume them:
254
+ The build entry discovers every `env.schema.ts`, parses it, and writes the artifacts you ask for. It needs a filesystem from its caller; on Node, pass `nodeBuildFileSystem`. This is the script `env-cap init` scaffolds, pinned by `test/cli/init.test.ts`:
683
255
 
684
256
  ```ts
685
- paymentsEnv.STRIPE_KEY
686
- ```
687
-
688
- ### From Zod, envalid, or t3-env
689
-
690
- Keep your existing validation logic.
691
-
692
- `env-cap` organizes configuration ownership, lifecycle visibility, and application-wide validation boundaries; it does not replace specialized validation libraries.
257
+ import { generateEnvArtifacts } from "@maverickcer/env-cap/build"
258
+ import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"
259
+ import path from "node:path"
260
+ import { fileURLToPath } from "node:url"
693
261
 
694
- Existing validators can be integrated directly:
262
+ const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
695
263
 
696
- ```ts
697
- validator(value) {
698
- return existingValidator(value) || "Invalid value";
699
- }
264
+ const result = await generateEnvArtifacts({
265
+ fs: nodeBuildFileSystem,
266
+ root,
267
+ manifest: { location: "src/generated/env.manifest.ts" },
268
+ docs: {
269
+ location: "docs/ENVIRONMENT.md",
270
+ envExample: { location: ".env.example", onExisting: "keep-sibling" },
271
+ },
272
+ usage: { report: { location: "docs/ENV-OWNERSHIP.md" } },
273
+ })
700
274
  ```
701
275
 
702
- No large rewrite is required.
703
-
704
- See [`specs/migrations/`](specs/migrations/) for the full, tool-specific guides this section summarizes.
705
-
706
- ## Security model
276
+ What the build step promises, and where it stops:
707
277
 
708
- `env-cap` is intentionally limited in scope.
278
+ | Promise | Test | Limit |
279
+ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
280
+ | Schema files are parsed, never imported or run | `test/build/parse.test.ts` (a throwing top-level statement never runs) | Lint does not ban `import()` or `vm` in `src/build`; reviewers check that |
281
+ | Only literal values are resolved; anything dynamic is reported as unresolved | `test/build/parse.test.ts`, `test/build/literal-eval.test.ts` | None found |
282
+ | An output path that is absolute outside `root`, or climbs out with `..`, fails before writing | `test/build/manifest-generate.test.ts`, `documentation-generate.test.ts` | The check is lexical; a symlinked directory inside `root` can lead outside |
283
+ | An existing `.env.example` is never overwritten by default | `test/build/env-example.test.ts` | `onExisting: "overwrite"` opts out |
284
+ | Discovery never enters `node_modules` or `.git` | `test/build/discover.test.ts` | None found |
709
285
 
710
- The runtime:
286
+ Every artifact separates **declared** facts from **proven** ones. Declared facts come from `documentEnv()`: owner, sensitivity, expiry. env-cap checks they are present, never that they are true. Proven facts come from the syntax tree: which variables are consumed, and the dependency graph. [`specs/generated-artifacts.md`](specs/generated-artifacts.md) lists each artifact and the models it reads.
711
287
 
712
- - does not store secrets
713
- - does not fetch secrets
714
- - does not transmit telemetry
715
- - does not execute lifecycle commands
716
- - does not log secret values
717
- - does not include documentation metadata in runtime contracts
288
+ ### Change tracking via the evidence file
718
289
 
719
- Runtime contracts protect against accidental exposure:
290
+ Pass `evidence` to also write the full Evidence Model, with a change report against the previous file:
720
291
 
721
292
  ```ts
722
- console.log(paymentsEnv)
723
- ```
724
-
725
- outputs:
726
-
727
- ```txt
728
- EnvContract("payments") { 1 variable(s) }
729
- ```
730
-
731
- not:
293
+ const result = await generateEnvArtifacts({
294
+ fs: nodeBuildFileSystem,
295
+ root,
296
+ manifest: { location: "src/generated/env.manifest.ts" },
297
+ evidence: { location: "docs/env.evidence.json" },
298
+ })
732
299
 
733
- ```txt
734
- {
735
- STRIPE_KEY: "sk_live_..."
736
- }
300
+ result.evidence.change.manifest.addedVariables
301
+ result.evidence.change.manifest.updatedVariables
302
+ result.evidence.change.manifest.removedVariables
737
303
  ```
738
304
 
739
- Explicit access remains required:
305
+ Writing it also writes `docs/env.evidence.json.fingerprint`, a content hash `getEvidenceModel()` uses to skip a rebuild when nothing changed.
740
306
 
741
- ```ts
742
- paymentsEnv.STRIPE_KEY
743
- ```
307
+ Commit both files, as you commit the manifest. The diff then means "since the last commit on this branch", which a reviewer can read ([ADR 0038](specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md)).
744
308
 
745
- Secret storage, rotation, and infrastructure management remain responsibilities of dedicated systems.
309
+ 1. A diff is expected when a `documentEnv()` field or a contract's `active`, `category` or `exclusiveGroup` changes.
310
+ 2. Every run with `--evidence` rewrites both files; there is no separate update step.
311
+ 3. A diff worth a second look is one nobody meant to make, such as an `updatedVariables` entry in an unrelated change.
746
312
 
747
- Full threat model, and what stays an application responsibility: [`SECURITY.md`](SECURITY.md). Decision-maker-level summary (bundle size, supply chain, LTS stance): [`ADOPTION.md`](ADOPTION.md).
313
+ Two active contracts that document the same variable differently produce a `DUPLICATE_VARIABLE_DOCUMENTATION` warning, which only `--strict` turns into an error.
748
314
 
749
- ## Troubleshooting
315
+ ### Reusable packages
750
316
 
751
- Every error `env-cap` throws belongs to one of these classes. When debugging a CI failure or a startup crash, start by checking which one was received.
317
+ A package can ship its own contract, and a consuming application can discover it. Discovery is opt-in, by exact package name:
752
318
 
753
- | Error | Thrown by | Common cause | Fix |
754
- | --------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
755
- | `EnvNotReadyError` | Reading `someEnv.KEY` | A contract was accessed before `validateEnv()` completed validation | Call `await validateEnv({ manifest, values })` during startup before application code accesses validated configuration |
756
- | `EnvValidationError` | `validateEnv()` | One or more variables failed their processor or validator | Read `error.failures` — one entry per variable, each naming the contract, variable, and developer-supplied message. It never contains raw or processed values (see [Security model](#security-model)) |
757
- | `EnvManifestGenerationError` | `generateEnvManifest()` | A provable contract conflict (for example, two contracts define incompatible processor return types for the same variable name), or `location` resolves outside `root` | Read `error.issues`; resolve the conflicting definitions or correct the output path |
758
- | `EnvDocumentationGenerationError` | `generateDocumentation()` | `location`/`envExample.location` resolves outside `root` (undocumented contracts/variables never throw — see below) | Correct the output path |
759
- | `EnvUsageAnalysisError` | `generateUsageReport()` | `report.location` resolves outside `root` (unused/unowned findings never throw — see below) | Correct the output path |
760
- | `EnvProjectGenerationError` | `generateEnvArtifacts()` | Any of the above errors aggregated across requested generation steps (manifest/docs/usage), or a provable manifest-pass compatibility/exclusive-group issue | Apply the fix for the underlying error. `generateEnvArtifacts()` combines failures into one result instead of failing independently per generation step |
761
-
762
- **Documentation completeness and dependency ownership never throw.** An undocumented contract/variable
763
- or an unconsumed owned dependency is a heuristic signal, not a provable defect the way a manifest
764
- compatibility conflict is — both have real, common false-positive causes (a webhook handler in another
765
- repo, a shell script reading the variable, a package outside the `packages` allowlist). They're
766
- reported as `Finding`s (`documentation`/`ownership` families) on the persisted evidence artifact
767
- instead; gate CI on them yourself by reading `--evidence`'s `finding` field if you want that
768
- enforced. See [ADR 0038](specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md).
319
+ ```ts
320
+ await generateEnvArtifacts({
321
+ fs: nodeBuildFileSystem,
322
+ packages: ["@acme/payments-sdk"],
323
+ manifest: { location: "src/env.manifest.ts" },
324
+ })
325
+ ```
769
326
 
770
- **"My schema file's variable isn't showing up in the generated manifest/docs."**
327
+ The publishing package does two things:
771
328
 
772
- Discovery only understands statically analyzable patterns — an inline object literal or a directly resolvable local/imported `const`.
329
+ 1. Declare `"envCap": { "schema": "./src/env.schema.ts" }` in its `package.json`, and ship that `.ts` file in `files`.
330
+ 2. Re-export the `createEnv()` contract under the same name from its main entry.
773
331
 
774
- A dynamically constructed schema (`createEnv(buildSchema())`) or a spread (`createEnv({ ...shared })`) may produce a parse warning instead of silently guessing.
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 does not yet block a merge.
775
333
 
776
- Check `result.parseWarnings` or the CLI's non-JSON output for the specific reason (see [ADR 0002](specs/decisions/0002-static-analysis-never-execution.md)).
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)).
777
335
 
778
- **"A contract imported through a `tsconfig.json` path alias shows up as abandoned / a `documentEnv()` call through an alias is unresolved."**
336
+ ### TypeScript path aliases (paths/baseUrl)
779
337
 
780
- Confirm `tsconfig.json` is actually at `root` (auto-detection doesn't search upward) and declares `paths`/`baseUrl`, or that an explicit `tsconfig` option points at the right file. Confirm `tsconfig` wasn't set to `false`.
338
+ A contract imported through an alias such as `@/features/payments/env.schema.js` is resolved with no configuration. Without it, that contract would be reported as abandoned.
781
339
 
782
- See [ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md) and [TypeScript path aliases](#typescript-path-aliases-pathsbaseurl) above.
340
+ - `tsconfig.json` is read from `root` exactly; there is no upward search.
341
+ - Pass `tsconfig: "tsconfig.build.json"` to use another file, or `tsconfig: false` to turn resolution off.
342
+ - Matching uses TypeScript's own `ts.resolveModuleName()`. A result inside `node_modules` is discarded, so only `packages` can reach installed code ([ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md)).
783
343
 
784
- **"A package's contract isn't discoverable even though I listed it in `packages`."**
344
+ ### Requirements
785
345
 
786
- Check `result.parseWarnings` for a `"(package) <name>"`-prefixed entry.
346
+ | Need | Detail |
347
+ | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
348
+ | Node.js | `>=22`. CI tests 22 and 24; 26 runs as an informational job |
349
+ | 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`) |
350
+ | TypeScript versions in CI | The newest 5.x, 6.x and 7.x, in a job that does not yet block a merge; the `^5.0.0` floor is not tested |
351
+ | `moduleResolution` | `node16`, `nodenext` or `bundler`, checked by the `TypeResolution` check; `node10` cannot resolve subpath exports |
352
+ | `./eslint-plugin` | Also needs `eslint` and `@typescript-eslint/utils`; versions in [ADOPTION's dependency table](ADOPTION.md#security--threat-model) |
787
353
 
788
- The allow-listed package must declare a valid `envCap.schema` field pointing to real `.ts`/`.tsx` source inside its own directory (see [Reusable packages](#reusable-packages)).
354
+ 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.
789
355
 
790
- **"I called `validateEnv()` again with different `values` and got the same result as last time."**
356
+ ### Package managers
791
357
 
792
- `validateEnv()` caches its first outcome for the life of the process (see [Validate once during startup](#3-validate-once-during-startup)). Call `resetEnvCache()` before re-validating — normal for a test suite or a script exercising multiple scenarios, not something a running application should need.
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. That job does not yet block a merge. Yarn Plug'n'Play and non-hoisted pnpm are unsupported.
793
359
 
794
360
  ## CLI
795
361
 
796
- Generate the manifest and the persisted evidence artifact directly from the command line:
362
+ **What it solves:** the same artifacts and drift check in any CI system, from one command.
797
363
 
798
- ```bash
799
- npx env-cap \
800
- --location src/generated/env.manifest.ts \
801
- --evidence docs/env.evidence.json \
802
- --strict
364
+ ```sh
365
+ npx env-cap --location src/generated/env.manifest.ts --evidence docs/env.evidence.json --strict
803
366
  ```
804
367
 
805
- The CLI is designed for development workflows, CI pipelines, and platform automation.
806
-
807
- The CLI's own surface is deliberately narrow -- see [ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md):
808
- only outputs with a real runtime consumer (the manifest) or that are inherent
809
- to the tool's own evidence/reporting contract (`--evidence`/`--json`/`--check`)
810
- get a flag. The rich Markdown docs catalog, the dependency & ownership
811
- report, and a reconciled `.env.example` have no such consumer -- nothing
812
- imports them the way application code imports the generated manifest -- so
813
- generating them is a few lines of application code instead, calling
814
- `@maverickcer/env-cap/build`'s exported `generateDocumentation()`/`generateUsageReport()`
815
- directly:
368
+ The CLI writes only the manifest and the evidence file ([ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md)). The documentation catalog, the ownership report and `.env.example` come from your own script calling `@maverickcer/env-cap/build`. This one is from [`examples/application/scripts/generate-docs/run.ts`](https://github.com/MaverickCER/env-cap/blob/main/examples/application/scripts/generate-docs/run.ts):
816
369
 
817
370
  ```ts
818
371
  import { generateDocumentation, generateUsageReport } from "@maverickcer/env-cap/build"
819
372
  import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"
820
373
 
821
- await generateDocumentation({
374
+ const docs = await generateDocumentation({
822
375
  fs: nodeBuildFileSystem,
376
+ root,
377
+ include,
823
378
  location: "docs/ENVIRONMENT.md",
824
- // Never overwrites a file that already exists at `envExample.location` by
825
- // default -- it writes a timestamped sibling instead, for you to
826
- // diff/merge by hand. Pass `onExisting: "overwrite"` to replace it
827
- // directly, or `"skip"` to write nothing at all when one is already
828
- // present -- see `EnvExampleOnExisting`.
829
379
  envExample: { location: ".env.example", onExisting: "overwrite" },
830
380
  })
831
381
 
832
- await generateUsageReport({
382
+ const usage = await generateUsageReport({
833
383
  fs: nodeBuildFileSystem,
834
- report: { location: "docs/ENV-OWNERSHIP.md" },
384
+ root,
385
+ include,
386
+ report: { location: "docs/OWNERSHIP.md" },
835
387
  })
836
388
  ```
837
389
 
838
- `checkEnvArtifacts()` is the same function `--check` calls internally, and
839
- takes the same `docs`/`usage` options -- see any of this repo's own
840
- `examples/*/scripts/generate-docs/` directories for a complete, wired-up
841
- `run.ts`/`check.ts` pair to copy from.
842
-
843
- Common uses include:
844
-
845
- - generating environment manifests
846
- - generating the persisted evidence artifact for reporting/CI
847
- - enforcing configuration ownership rules
848
- - detecting undocumented or stale configuration changes
849
- - producing machine-readable reports for automation
390
+ `checkEnvArtifacts()` is the drift check `--check` uses, with the same `docs` and `usage` options. Each example's `scripts/generate-docs/check.ts` shows it wired up.
850
391
 
851
392
  ### Options
852
393
 
853
- At least one of `--location` or `--evidence` is required. Run `npx env-cap --help` for the same list.
854
-
855
- | Flag | Meaning |
856
- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
857
- | `--root <path>` | Directory that globs resolve from (default: the current directory). |
858
- | `--location <path>` | Output path for the generated manifest. |
859
- | `--include <glob>` | Schema-discovery glob. Repeatable. Default: `**/env.schema.ts`. |
860
- | `--exclude <glob>` | Glob to exclude from discovery. Repeatable. |
861
- | `--package <name>` | Installed package to also discover a schema from, through its `envCap.schema` `package.json` field. Repeatable. |
862
- | `--tsconfig <path>` | `tsconfig.json` (relative to root) whose `paths` and `baseUrl` resolve aliased imports during static analysis. Default: the `tsconfig.json` found at the root. |
863
- | `--no-tsconfig` | Turn path-alias resolution off entirely. |
864
- | `--evidence <path>` | Also write the persisted evidence artifact and its `.fingerprint` sidecar, for example `docs/env.evidence.json`. |
865
- | `--strict` | Escalate every warning-severity finding to a hard error: compatibility, documentation and ownership. Nothing is written when it fires. Info findings never escalate. |
866
- | `--strict-docs` | Escalate only documentation warnings (undocumented, stale or expiring entries, unresolvable `documentEnv()` links), independent of `--strict`. |
867
- | `--strict-ownership` | Escalate only ownership warnings (abandoned contracts, unresolved consumers, unconsumed owned variables, indeterminate ownership), independent of `--strict`. |
868
- | `--json` | Emit a machine-readable report instead of formatted text (see below). |
869
- | `--check` | Verify generated artifacts are up to date without writing anything. Exits `1` if any is stale or missing. |
870
- | `--help`, `-h` | Show the help text. |
394
+ At least one of `--location` or `--evidence` is required. `npx env-cap --help` prints the same list, and `test/docs-cli-flags.test.ts` fails if a flag has no row here.
395
+
396
+ | Flag | Meaning |
397
+ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
398
+ | `--root <path>` | Directory that globs resolve from (default: the current directory). |
399
+ | `--location <path>` | Output path for the generated manifest. |
400
+ | `--include <glob>` | Schema-discovery glob. Repeatable. Default: `**/env.schema.ts`. |
401
+ | `--exclude <glob>` | Glob to exclude from discovery. Repeatable. |
402
+ | `--package <name>` | Installed package to also discover a schema from, through its `envCap.schema` field. Repeatable. |
403
+ | `--tsconfig <path>` | `tsconfig.json` (relative to root) whose `paths` and `baseUrl` resolve aliased imports. Default: `tsconfig.json` at the root. |
404
+ | `--no-tsconfig` | Turn path-alias resolution off. |
405
+ | `--evidence <path>` | Also write the evidence file and its `.fingerprint` sidecar, for example `docs/env.evidence.json`. |
406
+ | `--strict` | Escalate every warning to an error: compatibility, documentation and ownership. Nothing is written when one fires. |
407
+ | `--strict-docs` | Escalate only documentation warnings: undocumented or stale entries, expiring or expired entries, and unresolvable `documentEnv()` links. |
408
+ | `--strict-ownership` | Escalate only ownership warnings: abandoned contracts, unresolved consumers, unconsumed owned variables, indeterminate ownership, stale or missing `dynamicAccess` citations. |
409
+ | `--json` | Print a machine-readable report instead of text. |
410
+ | `--check` | Write nothing; exit `1` if any generated artifact is stale or missing. |
411
+ | `--help`, `-h` | Show the help text. |
412
+
413
+ The CLI exits `0` on success. It exits `1` on any error, a warning escalated by `--strict*`, or a bad argument.
414
+
415
+ Info findings never escalate. Without a `--strict*` flag, documentation and ownership findings never fail a run. Exclusive-group violations and conflicting explicit processor types always fail (`test/cli/main.test.ts`, `test/build/exclusive-group.test.ts`).
871
416
 
872
417
  ### `--json`
873
418
 
874
- Add `--json` to emit a machine-readable report instead of formatted terminal output.
875
-
876
- The output contains the same generated artifact information returned by `generateEnvArtifacts()` wrapped in a stable JSON envelope:
877
-
878
- ```bash
879
- npx env-cap \
880
- --location src/generated/env.manifest.ts \
881
- --evidence docs/env.evidence.json \
882
- --json
883
- ```
884
-
885
- Example:
419
+ `--json` prints a versioned report instead of text. It changes the format only; the exit code is the same. An abbreviated example:
886
420
 
887
421
  ```jsonc
888
422
  {
@@ -890,77 +424,55 @@ Example:
890
424
  "kind": "env-cap-report",
891
425
  "toolVersion": "<installed env-cap version>",
892
426
  "ok": true,
893
- "manifest": {
894
- "outputPath": "...",
895
- "contracts": [/* discovered contracts */],
896
- },
897
- // "evidence" appears when --evidence is passed. "docs"/"usage" no longer
898
- // appear from the CLI at all (ADR 0046) -- call `generateDocumentation()`/
899
- // `generateUsageReport()` directly for that shape.
427
+ "manifest": { "outputPath": "...", "contracts": [] },
428
+ // "evidence" appears when --evidence is passed.
900
429
  }
901
430
  ```
902
431
 
903
- The full field-by-field shape -- including `docs.catalog` entries, `manifest`, and
904
- `usage` -- is defined by the [published JSON Schema](#published-json-schema) below
905
- rather than repeated here.
906
-
907
- `--json` changes output formatting only. Exit-code behavior remains unchanged.
908
-
909
- New fields may be added without a `schemaVersion` change. Consumers should ignore properties they do not recognize.
910
-
911
- See [ADR 0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md).
432
+ New fields may appear without a `schemaVersion` change, so ignore properties you do not recognize ([ADR 0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md)).
912
433
 
913
434
  #### Published JSON Schema
914
435
 
915
- A real, published JSON Schema for the `--json` envelope lives at
916
- [`schemas/env-cap-report.schema.json`](schemas/env-cap-report.schema.json), also
917
- resolvable as `@maverickcer/env-cap/schema` -- for external, non-TypeScript tooling
918
- (a Go service, a Python dashboard, a generic CI linter) to validate or codegen
919
- against without hand-transcribing the shape above.
436
+ The report's schema is [`schemas/env-cap-report.schema.json`](schemas/env-cap-report.schema.json), importable as `@maverickcer/env-cap/schema`. It is generated from `src/cli/json.ts`, and the `Schema` check fails if the committed file differs ([ADR 0019](specs/decisions/0019-published-json-schema-generated-from-types.md)).
920
437
 
921
- It's generated directly from `src/cli/json.ts`'s own types (never hand-authored), so
922
- the two can't silently drift apart, and it evolves under the same additive-only rule
923
- already established for `--json` itself: a new optional field is never a breaking
924
- schema change; a changed or removed field is.
925
-
926
- See [ADR 0019](specs/decisions/0019-published-json-schema-generated-from-types.md).
438
+ - Real success, failure and `--check` payloads validate against it (`test/build/json-schema.test.ts`).
439
+ - The committed evidence files of two examples validate against its `EvidenceModel` definition, in the same test file.
440
+ - A changed or removed field is meant to bump `schemaVersion`. No check enforces that yet; the `SurfaceContract` check enforces the changeset level.
927
441
 
928
442
  ### `--check`
929
443
 
930
- Add `--check` to verify generated artifacts are current without modifying files.
931
-
932
- This is useful as a CI drift check when a schema changes but generated artifacts were not updated:
444
+ `--check` recomputes every requested artifact in memory and compares it with the committed file. It never writes ([ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
933
445
 
934
- ```bash
935
- npx env-cap \
936
- --location src/generated/env.manifest.ts \
937
- --evidence docs/env.evidence.json \
938
- --check
446
+ ```sh
447
+ npx env-cap --location src/generated/env.manifest.ts --evidence docs/env.evidence.json --check
939
448
  ```
940
449
 
941
- The command exits:
450
+ | Exit code | Meaning | Line of output |
451
+ | --------- | ------------------------------- | ----------------------------------------- |
452
+ | `0` | Every artifact matches | `All generated artifacts are up to date.` |
453
+ | `1` | An artifact is stale or missing | `<n> artifact(s) are stale or missing.` |
942
454
 
943
- - `0` when generated artifacts match the expected output
944
- - `1` when artifacts are missing or stale
455
+ With `--json`, the report carries a `checkResult` field: `ok` is the verdict and `stale` names each stale artifact (`test/build/check-artifacts.test.ts`).
945
456
 
946
- `--check` never writes to or modifies committed files, even when drift is detected.
457
+ ### Using the CLI outside GitHub Actions
947
458
 
948
- With `--json`, the response includes an additive `checkResult` field containing the comparison result.
459
+ GitLab, Jenkins or Buildkite get the same gate from the CLI alone.
949
460
 
950
- See [ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md).
461
+ 1. Install the package as a devDependency and run:
951
462
 
952
- ## GitHub Action
463
+ ```sh
464
+ npx env-cap --location src/generated/env.manifest.ts --evidence docs/env.evidence.json --check --json > env-cap.json
465
+ ```
953
466
 
954
- The first-party GitHub Action runs `env-cap --json` and integrates configuration analysis into pull requests and scheduled maintenance workflows.
467
+ 2. Fail the job on the exit code: `0` when every artifact is current, `1` when one is stale or missing or the run failed.
468
+ 3. Read `checkResult` in `env-cap.json` for the verdict. For per-finding severity, file and line, read `finding.findings` in the evidence file.
469
+ 4. For a SARIF upload, pass the persisted Finding Model to `buildSarifLog` from `@maverickcer/env-cap/build` ([evidence](#reviewers-evidence)).
955
470
 
956
- It provides:
471
+ The CLI reads no `GITHUB_` variable today. No check enforces that, so read it as a description of the current code.
957
472
 
958
- - machine-readable configuration reports
959
- - inline pull request annotations
960
- - sticky summary comments
961
- - scheduled rotation monitoring
473
+ ## GitHub Action
962
474
 
963
- Example:
475
+ **What it solves:** drift and findings show up on the pull request, as annotations and one summary comment.
964
476
 
965
477
  ```yaml
966
478
  # .github/workflows/env-cap.yml
@@ -976,67 +488,48 @@ permissions:
976
488
  jobs:
977
489
  report:
978
490
  runs-on: ubuntu-latest
979
-
980
491
  steps:
981
492
  - uses: actions/checkout@v4
982
-
493
+ - run: npm ci # the Action runs the env-cap your project installs
983
494
  - uses: maverickcer/env-cap@v0
984
495
  with:
985
496
  args: "--location src/generated/env.manifest.ts --evidence docs/env.evidence.json"
986
497
  ```
987
498
 
988
- The action runs the project's own installed `env-cap` (`devDependencies`) and never an unpinned
989
- `latest`: with no local install it needs `with: version: "<x.y.z>"` and otherwise fails with an
990
- explanation. Inputs reach the CLI through environment variables, not shell text, so a PR-controlled
991
- value forwarded into `args` cannot become a command.
992
-
993
- What this action reports (data-cap's sibling action reports the same sections minus the rotation
994
- alert): inline `::warning`/`::error` annotations, one sticky pull-request comment per `report-key`,
995
- and -- env-cap only, on runs with no pull request -- a GitHub issue for expiring or expired
996
- variables (`rotation-alert`, needs `issues: write`), closed again once nothing is expiring.
997
-
998
- `args` only reaches the CLI, so it can only drive `--location`/`--evidence`/
999
- `--strict`-family flags (ADR 0046) -- the persisted evidence artifact this
1000
- produces is what the Action's own PR annotations/summary comment/rotation
1001
- alerts read from (Finding Model, ADR 0038), regardless of whether your repo
1002
- also generates `docs/ENVIRONMENT.md`/`docs/ENV-OWNERSHIP.md` as a separate step (the scaffolded default is `ENV-OWNERSHIP.md` so it never collides with a sibling package's ownership report).
1003
-
1004
- | Input | Default | Purpose |
1005
- | ------------------- | --------------------- | ----------------------------------------------------------------------------------------------------- |
1006
- | `args` | _(required)_ | Arguments passed to `env-cap --json`, such as `--location`, `--evidence`, and strict validation flags |
1007
- | `working-directory` | `.` | Directory where `env-cap` executes |
1008
- | `version` | _(latest)_ | Version to execute through `npx` when `env-cap` is not installed locally |
1009
- | `comment` | `true` | Creates or updates a sticky pull request summary comment |
1010
- | `annotations` | `true` | Emits GitHub workflow annotations for detected issues |
1011
- | `rotation-alert` | `true` | Enables scheduled expiration reporting outside pull requests |
1012
- | `report-key` | _(working-directory)_ | Identifies this report when multiple workflows run against the same pull request |
1013
- | `github-token` | `${{ github.token }}` | Token used for the `gh` CLI calls that post/update PR comments and rotation-alert issues |
1014
-
1015
- The Action does not create its own policy layer. Pass/fail behavior always follows the CLI exit code and whatever `--strict`/`--strict-docs`/`--strict-ownership` combination this invocation's own `args` input passes (ADR 0044 — see [Troubleshooting](#troubleshooting)). A finding family with no matching `--strict*` flag never fails the run on its own; read it from `--evidence`'s output and gate on it in your own workflow step if you want that enforced.
499
+ How the Action behaves, and what tests it:
1016
500
 
1017
- ### Monorepos
501
+ 1. It runs the env-cap your project installs. It looks for `node_modules/.bin/env-cap` inside `working-directory`; in a hoisted monorepo, set `version` or run from the root. With none found, it needs a `version` input and exits `2` without one (`test/scripts/github-action-run-cli.test.ts`).
502
+ 2. A `version` must be a plain version or a dist-tag. `latest` is a dist-tag and is accepted, so pin a version instead.
503
+ 3. Inputs reach the CLI as environment variables, never as shell text. `args` is split into words, so a forwarded value can add CLI flags.
504
+ 4. Its pass or fail is the CLI's exit code. It adds no policy of its own; a finding family fails only under its `--strict*` flag in `args`.
505
+ 5. Annotations and the summary comment are computed from the CLI report and the evidence file. Pass `--evidence` to get documentation, ownership and expiry reporting.
1018
506
 
1019
- For monorepos running multiple `env-cap` checks in parallel, provide a unique `report-key` for each invocation.
507
+ 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.
1020
508
 
1021
- This prevents separate jobs from overwriting each other's pull request comments.
509
+ | Input | Default | Purpose |
510
+ | ------------------- | ----------------------- | ---------------------------------------------------------------------------------------- |
511
+ | `args` | _(required)_ | Arguments passed to `env-cap --json`, such as `--location`, `--evidence` and `--strict*` |
512
+ | `working-directory` | `.` | Directory where `env-cap` runs |
513
+ | `version` | _(none; required then)_ | Version to run through `npx` when env-cap is not installed; pin one rather than `latest` |
514
+ | `comment` | `true` | Create or update one sticky summary comment on the pull request |
515
+ | `annotations` | `true` | Emit inline workflow annotations |
516
+ | `rotation-alert` | `true` | On runs with no pull request, report expiring variables in an issue |
517
+ | `report-key` | _(working-directory)_ | Identifies this report when several jobs comment on one pull request |
518
+ | `github-token` | `${{ github.token }}` | Token for the `gh` calls that post comments and issues |
1022
519
 
1023
- For teams that want a single combined report across multiple packages, upload each job's `--json` output as an artifact and aggregate the results in a final workflow step.
520
+ ### Monorepos
1024
521
 
1025
- ### Reusable packages and external contracts
522
+ Give each parallel invocation its own `report-key`, so jobs do not overwrite each other's comments. For one combined report, upload each job's `--json` output and merge them in a final step.
1026
523
 
1027
- Contracts discovered from explicitly included packages are reported through the same annotations and summary surfaces as local contracts.
524
+ The Action looks for `node_modules/.bin/env-cap` inside `working-directory`; in a hoisted monorepo, set `version` or run from the root.
1028
525
 
1029
- Because `node_modules` is not part of a pull request diff, findings originating from installed packages cannot render as inline changed-file annotations. The sticky summary comment remains the complete reporting surface.
526
+ ### Reusable packages and external contracts
1030
527
 
1031
- See [Reusable packages](#reusable-packages) for the package discovery model.
528
+ Contracts discovered through `packages` appear in the same annotations and comment. Their files sit in `node_modules`, outside the diff, so their findings appear only in the summary comment.
1032
529
 
1033
530
  ### Scheduled rotation alerts
1034
531
 
1035
- The same Action can run independently of pull requests to monitor configuration lifecycle metadata.
1036
-
1037
- This is useful for detecting variables that are approaching expiration or have exceeded their documented rotation window.
1038
-
1039
- Example:
532
+ The same Action can run on a schedule and report expiring variables in an issue:
1040
533
 
1041
534
  ```yaml
1042
535
  # .github/workflows/env-cap-rotation.yml
@@ -1054,161 +547,189 @@ permissions:
1054
547
  jobs:
1055
548
  check-rotation:
1056
549
  runs-on: ubuntu-latest
1057
-
1058
550
  steps:
1059
551
  - uses: actions/checkout@v4
1060
-
552
+ - run: npm ci
1061
553
  - uses: maverickcer/env-cap@v0
1062
554
  with:
1063
555
  args: "--location src/generated/env.manifest.ts --evidence docs/env.evidence.json"
1064
556
  ```
1065
557
 
1066
- The Action reads the rotation-alert list from the persisted evidence artifact's Lifecycle Model (`result.evidence.lifecycle.expiring`), so `--evidence` is required here — `--docs`/`--expiring-within-days` are not CLI flags (see ADR 0046); the expiring-soon window itself is always the library's 30-day default when driven through the CLI this way.
558
+ 1. The list comes from the evidence file's Lifecycle Model, so `--evidence` is required.
559
+ 2. The window is the library's default (`DEFAULT_EXPIRING_WITHIN_DAYS`); the CLI has no flag to change it.
560
+ 3. With no pull request, the Action opens or updates an issue listing expiring or expired variables.
561
+ 4. When nothing is expiring, it decides to close that issue. The decision is unit-tested; the `gh` call is not run in CI.
1067
562
 
1068
- When running without a pull request context, the Action can create or update a GitHub issue containing expiring or expired configuration entries.
563
+ Set `rotation-alert: "false"` to turn issues off ([ADR 0018](specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md)).
1069
564
 
1070
- Once all reported variables are resolved, the issue is automatically closed.
565
+ ## Reviewers: evidence
1071
566
 
1072
- Set `rotation-alert: "false"` to disable issue-based rotation reporting.
567
+ **What it solves:** an inventory of every variable, its owner and its expiry, with findings you can trace to a file and line. The outputs support a review, nothing more.
1073
568
 
1074
- See [ADR 0018](specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md).
569
+ The evidence file is a serialized `EvidenceModel` with these members:
1075
570
 
1076
- ## ESLint plugin
571
+ | Member | What it holds |
572
+ | --------------- | -------------------------------------------------------------------------------------------------------------- |
573
+ | `schemaVersion` | The evidence format's version |
574
+ | `provenance` | When it was generated, by which env-cap version, at which commit |
575
+ | `contract` | Every contract and variable, with declared documentation |
576
+ | `dependency` | Which code consumes which variable, computed from the syntax tree; dynamic access is reported as indeterminate |
577
+ | `ownership` | Owners, abandoned contracts and unconsumed owned variables |
578
+ | `lifecycle` | Expiry, rotation fields and the computed `rotationStatus` |
579
+ | `finding` | Every finding, with family, severity and position where one is known |
580
+ | `change` | What changed since the previous evidence file |
581
+
582
+ `rotationStatus` is a judgement over declared dates and periods. It never states that a rotation happened or that a control is met. Its values are `compliant`, `overdue`, `expired` and `undeclared`. `compliant` means only that the declared dates fall within the declared period; 1.0 renames it `withinPolicy`.
583
+
584
+ ### Findings and SARIF
1077
585
 
1078
- `@maverickcer/env-cap/eslint-plugin` provides a `no-raw-process-env` rule (and its filesystem analogue `no-node-fs`, below) that helps enforce environment ownership boundaries.
586
+ `buildSarifLog` from `@maverickcer/env-cap/build` turns the Finding Model into SARIF 2.1.0. Its output validates against the official OASIS schema, with and without positions (`test/build/sarif.test.ts`). It is a library export; the CLI does not write SARIF.
1079
587
 
1080
- It flags direct `process.env` access outside approved contract definitions, making configuration ownership enforceable through tooling rather than relying only on team conventions.
588
+ ### Projections
1081
589
 
1082
- ```bash
1083
- npm install -D eslint
590
+ `defineEvidenceProjection()` from `@maverickcer/env-cap/evidence` turns the model into any shape you need. It also records which model paths each output field read (`test/evidence/define-projection.test.ts`). This one is trimmed from [`inventory.mjs`](https://github.com/MaverickCER/env-cap/blob/main/test/integration/positive/enterprise/evidence-projections/projections/inventory.mjs):
591
+
592
+ ```ts
593
+ import { defineEvidenceProjection } from "@maverickcer/env-cap/evidence"
594
+
595
+ export const inventoryProjection = defineEvidenceProjection({
596
+ inventory: (evidence) =>
597
+ evidence.contract.contracts.map((contract) => ({
598
+ contractName: contract.contractName,
599
+ variables: contract.variables.map((variable) => variable.key),
600
+ })),
601
+ })
1084
602
  ```
1085
603
 
604
+ - `./evidence` imports no Node module and runs under Web globals only (`test/runtime/browser-bundle.test.ts`).
605
+ - It stays under 3 KB gzip, enforced by the `Size` check.
606
+ - `./evidence` and the `EvidenceModel` shape are Stable, and the `ApiContract` check diffs them. Before 1.0, a breaking change needs only a minor release.
607
+
608
+ [`examples/enterprise-platform`](https://github.com/MaverickCER/env-cap/tree/main/examples/enterprise-platform) builds a configuration-governance report this way.
609
+
610
+ ## Build-script authors: the Node adapter
611
+
612
+ **What it solves:** `./build` never acquires a filesystem on its own, so your script hands it one.
613
+
614
+ ```ts
615
+ import { generateEnvArtifacts } from "@maverickcer/env-cap/build"
616
+ import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"
617
+ ```
618
+
619
+ `./node` re-exports the CLI's `node:fs` adapter; only `src/cli` imports `node:fs`. `./node` does not read `process.env`. The `AmbientCapabilities` check enforces both. A non-Node runtime passes its own `BuildFileSystem` instead ([ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
620
+
621
+ ## ESLint plugin
622
+
623
+ **What it solves:** direct `process.env` reads outside your contracts become lint errors, so ownership is enforced by tooling.
624
+
1086
625
  ```js
1087
626
  // eslint.config.js
1088
-
1089
627
  import envCapPlugin from "@maverickcer/env-cap/eslint-plugin"
1090
628
 
1091
629
  export default [
1092
630
  {
1093
631
  files: ["**/*.ts"],
1094
- plugins: {
1095
- "env-cap": envCapPlugin,
1096
- },
1097
- rules: {
1098
- "env-cap/no-raw-process-env": "error",
1099
- },
632
+ plugins: { "env-cap": envCapPlugin },
633
+ rules: { "env-cap/no-raw-process-env": "error" },
1100
634
  },
1101
635
  ]
1102
636
  ```
1103
637
 
1104
- By default, `env.schema.ts` and `env.schema.tsx` files are exempt because their purpose is to define the environment contract consumed by `createEnv()`.
638
+ The plugin needs `eslint` and `@typescript-eslint/utils`; [ADOPTION's dependency table](ADOPTION.md#security--threat-model) lists the ranges. Its tests run on ESLint 10 only; the declared ESLint 8.57 and 9 support is untested.
1105
639
 
1106
- Other files must access validated contracts instead of reading environment variables directly.
640
+ ### `no-raw-process-env`
1107
641
 
1108
- For example:
642
+ The rule reports `process.env` outside `env.schema.ts` and `env.schema.tsx` files (`test/eslint-plugin/no-raw-process-env.test.ts`). Nothing else is exempt unless you list it:
1109
643
 
1110
- ```ts
1111
- process.env.STRIPE_KEY
644
+ ```js
645
+ rules: {
646
+ "env-cap/no-raw-process-env": ["error", { allow: ["scripts/bootstrap-secrets.ts"] }],
647
+ }
1112
648
  ```
1113
649
 
1114
- becomes:
650
+ A one-off exception can use `// eslint-disable-next-line env-cap/no-raw-process-env` ([ADR 0017](specs/decisions/0017-eslint-plugin-entry-point.md)).
1115
651
 
1116
- ```ts
1117
- paymentsEnv.STRIPE_KEY
1118
- ```
1119
-
1120
- The rule does not prevent legitimate infrastructure or build-time code from accessing raw environment variables.
652
+ ### `no-node-fs`
1121
653
 
1122
- For approved exceptions, provide an explicit allow list:
654
+ The rule reports `import`, `require` and `import()` of `fs`, `node:fs` and their `/promises` subpaths (`test/eslint-plugin/no-node-fs.test.ts`). Nothing is exempt unless you list it:
1123
655
 
1124
656
  ```js
1125
657
  rules: {
1126
- "env-cap/no-raw-process-env": [
1127
- "error",
1128
- {
1129
- allow: ["scripts/bootstrap-secrets.ts"],
1130
- },
1131
- ],
658
+ "env-cap/no-node-fs": ["error", { allow: ["src/cli/**", "scripts/**"] }],
1132
659
  }
1133
660
  ```
1134
661
 
1135
- One-off exceptions can also use the standard ESLint disable comment:
662
+ It applies the rule env-cap follows itself: a library accepts a filesystem from its caller ([ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
1136
663
 
1137
- ```ts
1138
- // eslint-disable-next-line env-cap/no-raw-process-env
1139
- process.env.BOOTSTRAP_TOKEN
1140
- ```
664
+ ## Architecture
1141
665
 
1142
- The goal is not to eliminate every direct environment read. The goal is to make ownership boundaries intentional and reviewable.
666
+ ### Runtime and build-time are intentionally separate
1143
667
 
1144
- See [ADR 0017](specs/decisions/0017-eslint-plugin-entry-point.md).
668
+ The runtime and the build tooling share one contract file and nothing else.
1145
669
 
1146
- ### `no-node-fs`
670
+ | Path | Entry points | What it does | Where it runs |
671
+ | ---------- | -------------------------------- | -------------------------------------------------------------------- | ---------------------------- |
672
+ | Runtime | `.`, `./helpers`, `./evidence` | Validates values, exposes typed access, projects evidence | Your application, at startup |
673
+ | Build-time | `./build`, CLI, `./node`, Action | Discovers contracts, analyzes source, writes manifests and documents | Development and CI only |
1147
674
 
1148
- The plugin also ships `no-node-fs`, the filesystem analogue of `no-raw-process-env`. It flags any `import`, `require`, or dynamic `import()` of `node:fs` (or `fs`, and their `/promises` subpaths) so a module accepts a filesystem capability from its caller instead of acquiring one implicitly — the discipline `env-cap`'s own `./build` surface follows (see [ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
675
+ A run goes through four steps, in order:
1149
676
 
1150
- ```js
1151
- rules: {
1152
- "env-cap/no-node-fs": [
1153
- "error",
1154
- {
1155
- // globs for the executable entry points that legitimately construct
1156
- // the concrete node:fs adapter -- nothing is exempt by default.
1157
- allow: ["src/cli/**", "scripts/**"],
1158
- },
1159
- ],
1160
- }
1161
- ```
677
+ 1. Each capability declares a contract with `createEnv()` and `documentEnv()`.
678
+ 2. The build step parses every contract file and writes the manifest, documents and evidence.
679
+ 3. The application imports the manifest and calls `validateEnv()` once at startup.
680
+ 4. Code reads typed values through the contract that owns them.
681
+
682
+ A project can start with one central contract and split it later; the runtime model stays the same. [specs/architecture.md](specs/architecture.md) has the full treatment.
683
+
684
+ ### Runtime support matrix
1162
685
 
1163
- Nothing is exempt unless you list it: the rule never guesses at what counts as an executable capability boundary. A consuming project that runs `@maverickcer/env-cap/build` from its own script imports the ready-made adapter from `@maverickcer/env-cap/node` (`{ nodeBuildFileSystem }`) rather than reaching for `node:fs` itself.
686
+ | Environment | `.` (runtime) | `./helpers` | `./evidence` | `./build`, CLI, `./node`, `./eslint-plugin` |
687
+ | ---------------------------------- | ---------------- | ------------------ | ---------------- | ------------------------------------------- |
688
+ | Node.js 22 and 24 (ESM and CJS) | Tested, blocking | Tested, blocking | Tested, blocking | Tested, blocking ⁴ |
689
+ | Web-globals bundle ¹ | Tested, blocking | Tested ², blocking | Tested, blocking | Not applicable |
690
+ | Bun and Deno | Executed in CI ³ | Executed in CI ³ | Executed in CI ³ | Not tested |
691
+ | Real browsers, edge and serverless | Not tested | Not tested | Not tested | Not applicable |
1164
692
 
1165
- Common questions about dotenv/Zod overlap, centralized configuration, AST analysis, incremental adoption, and ownership models are answered in the [FAQ](https://maverickcer.github.io/env-cap/#faq).
693
+ ¹ Bundled with esbuild for the browser and run in a `node:vm` context with no `process`, `Buffer`, `require` or timers (`test/runtime/browser-bundle.test.ts`).
1166
694
 
1167
- ## Performance characteristics
695
+ ² Except `processors.base64()`, which returns a Node `Buffer`.
1168
696
 
1169
- env-cap is designed to add predictable configuration validation without introducing
1170
- runtime complexity into every environment variable access.
697
+ ³ `bun-version: latest` and Deno `v2.x`, in a job that does not yet block a merge.
1171
698
 
1172
- Runtime behavior:
699
+ ⁴ `./eslint-plugin`: unit tests block; its ESM and CJS import from the tarball runs only in the non-blocking `package-managers` job.
1173
700
 
1174
- - Environment initialization: O(N), where N is the number of defined variables.
1175
- - Initial validation: O(N), where N is the number of variables being validated.
1176
- - Variable lookup after initialization: O(1).
1177
- - Repeated validation after the initial pass: O(1) through cached validation state.
701
+ 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
+
703
+ ## Migration
1178
704
 
1179
- This means applications pay validation and setup costs once during initialization,
1180
- rather than repeatedly processing configuration during normal execution.
705
+ Adopt env-cap one contract at a time, and keep what you have:
1181
706
 
1182
- For comparison, conventional configuration patterns typically perform one of two
1183
- operations:
707
+ | Coming from | What changes |
708
+ | -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
709
+ | `dotenv` | Keep loading with it; add a contract over the variables it loads |
710
+ | Raw `process.env` | Replace `process.env.STRIPE_KEY` with `env.STRIPE_KEY`, then move contracts next to their features |
711
+ | Zod, envalid, t3-env | Keep your schemas; call them from a validator: `validator: (value) => schema.safeParse(value).success \|\| "Invalid value"` |
1184
712
 
1185
- 1. Build a configuration object and access properties:
1186
- - Object construction: O(N)
1187
- - Property lookup: O(1)
713
+ [`specs/migrations/`](specs/migrations/) has a guide per tool, each with a section on when to keep what you have.
1188
714
 
1189
- 2. Build a configuration object with inline processing/validation:
1190
- - Object construction: O(N)
1191
- - Processing cost: O(N)
1192
- - Validation cost: O(N)
715
+ ## Performance
1193
716
 
1194
- env-cap follows the second model's safety benefits while separating processing,
1195
- validation, and access so repeated application usage remains constant-time.
717
+ Validation runs once, at startup. After it, reading a value is a property lookup on the frozen record of validated values.
1196
718
 
1197
- See the [performance documentation](./benchmarks/README.md) for benchmark methodology
1198
- and regression tracking.
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. That job does not yet block a merge, and 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.
1199
720
 
1200
721
  ## Documentation index
1201
722
 
1202
- | Doc | For |
1203
- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
1204
- | This Guide + the [docs site](https://maverickcer.github.io/env-cap/) | Using `env-cap` in an application |
1205
- | [API reference](https://maverickcer.github.io/env-cap/api/) | Every exported symbol, generated from the types |
1206
- | [`specs/architecture.md`](specs/architecture.md) + [`specs/decisions/`](specs/decisions/) | Why the package is shaped the way it is (ADRs) |
1207
- | [`specs/migrations/`](specs/migrations/) | Adopting `env-cap` alongside dotenv / Zod / envalid / t3-env |
1208
- | [`ADOPTION.md`](ADOPTION.md) | Decision-maker summary: security, size, LTS |
1209
- | [`SECURITY.md`](SECURITY.md) | Full threat model and application responsibilities |
1210
- | [`VERSIONING.md`](VERSIONING.md) | What semver covers; Stable / Experimental / Private tiers |
1211
- | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Making a change |
1212
- | [`CODE_REVIEW.md`](CODE_REVIEW.md) | What a reviewer checks before merging |
1213
- | [`RELEASING.md`](RELEASING.md) | Maintainer release process |
1214
- | [`SUPPORT.md`](SUPPORT.md) | Where to ask questions and file bugs |
723
+ | Doc | For |
724
+ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
725
+ | This guide and the [docs site](https://maverickcer.github.io/env-cap/) | Using env-cap |
726
+ | [API reference](https://maverickcer.github.io/env-cap/api/) | Every exported symbol, generated from source |
727
+ | [`specs/architecture.md`](specs/architecture.md) and [`specs/decisions/`](specs/decisions/) | Why the package is shaped this way |
728
+ | [`specs/migrations/`](specs/migrations/) | Adopting env-cap beside dotenv, Zod, envalid or t3-env |
729
+ | [`ADOPTION.md`](ADOPTION.md) | What adopting costs, needs and refuses to do |
730
+ | [`SECURITY.md`](SECURITY.md) | What is enforced, where, and what is not |
731
+ | [`VERSIONING.md`](VERSIONING.md) | What semver covers; the tier of each entry point |
732
+ | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Making a change |
733
+ | [`CODE_REVIEW.md`](CODE_REVIEW.md) | What a reviewer checks before merging |
734
+ | [`RELEASING.md`](RELEASING.md) | The release process |
735
+ | [`SUPPORT.md`](SUPPORT.md) | Where to ask questions and file bugs |