@maverickcer/env-cap 0.7.5 → 0.7.6

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