@maverickcer/env-cap 0.7.4 → 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 (353) hide show
  1. package/ADOPTION.md +106 -124
  2. package/AGENTS.md +94 -128
  3. package/CHANGELOG.md +42 -0
  4. package/CODE_REVIEW.md +69 -173
  5. package/CONTRIBUTING.md +57 -74
  6. package/GUIDE.md +405 -866
  7. package/README.md +112 -89
  8. package/RELEASING.md +81 -65
  9. package/SECURITY.md +76 -227
  10. package/SUPPORT.md +21 -45
  11. package/VERSIONING.md +69 -105
  12. package/benchmarks/READING-BENCHMARKS.md +103 -81
  13. package/benchmarks/README.md +12 -9
  14. package/benchmarks/WRITING-BENCHMARKS.md +90 -80
  15. package/benchmarks/performance-buildtime/BENCHMARKS.md +20 -20
  16. package/benchmarks/performance-runtime/BENCHMARKS.md +107 -107
  17. package/dist/.dts/_ipc/build-fs.d.ts +12 -17
  18. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  19. package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
  20. package/dist/.dts/_ipc/display-path.d.ts +1 -1
  21. package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
  22. package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
  23. package/dist/.dts/_ipc/glob.d.ts +9 -8
  24. package/dist/.dts/_ipc/glob.d.ts.map +1 -1
  25. package/dist/.dts/_ipc/no-node-fs.d.ts +2 -2
  26. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
  27. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  28. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  29. package/dist/.dts/_ipc/typescript.d.ts +4 -4
  30. package/dist/.dts/build/assemble-project.d.ts +14 -15
  31. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  32. package/dist/.dts/build/change-model.d.ts +14 -14
  33. package/dist/.dts/build/change-model.d.ts.map +1 -1
  34. package/dist/.dts/build/check-artifacts.d.ts +4 -4
  35. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  36. package/dist/.dts/build/citation-verification.d.ts +13 -14
  37. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  38. package/dist/.dts/build/compatibility.d.ts +24 -24
  39. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  40. package/dist/.dts/build/contract-model.d.ts +10 -10
  41. package/dist/.dts/build/contract-model.d.ts.map +1 -1
  42. package/dist/.dts/build/deep-equal.d.ts +2 -2
  43. package/dist/.dts/build/deep-freeze.d.ts +2 -2
  44. package/dist/.dts/build/dependency-graph.d.ts +48 -55
  45. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  46. package/dist/.dts/build/dependency-model.d.ts +18 -18
  47. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  48. package/dist/.dts/build/discover.d.ts +11 -11
  49. package/dist/.dts/build/discover.d.ts.map +1 -1
  50. package/dist/.dts/build/docs.d.ts +34 -38
  51. package/dist/.dts/build/docs.d.ts.map +1 -1
  52. package/dist/.dts/build/env-example.d.ts +13 -13
  53. package/dist/.dts/build/env-example.d.ts.map +1 -1
  54. package/dist/.dts/build/errors.d.ts +8 -8
  55. package/dist/.dts/build/evidence-cache.d.ts +23 -23
  56. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  57. package/dist/.dts/build/evidence-model.d.ts +3 -3
  58. package/dist/.dts/build/evidence-reference.d.ts +15 -15
  59. package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
  60. package/dist/.dts/build/evidence-snapshot.d.ts +47 -53
  61. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  62. package/dist/.dts/build/exclusive-group.d.ts +4 -4
  63. package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
  64. package/dist/.dts/build/finding-model.d.ts +12 -12
  65. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  66. package/dist/.dts/build/generate-documentation.d.ts +19 -19
  67. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  68. package/dist/.dts/build/generate-env-artifacts.d.ts +43 -43
  69. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  70. package/dist/.dts/build/generate-evidence.d.ts +19 -19
  71. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  72. package/dist/.dts/build/generate-manifest.d.ts +11 -12
  73. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  74. package/dist/.dts/build/generate-usage.d.ts +23 -24
  75. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  76. package/dist/.dts/build/generated-banner.d.ts +5 -5
  77. package/dist/.dts/build/governance-fields.d.ts +7 -7
  78. package/dist/.dts/build/humanize-key.d.ts +1 -1
  79. package/dist/.dts/build/humanize-key.d.ts.map +1 -1
  80. package/dist/.dts/build/index.d.ts +20 -36
  81. package/dist/.dts/build/index.d.ts.map +1 -1
  82. package/dist/.dts/build/lifecycle-model.d.ts +90 -83
  83. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  84. package/dist/.dts/build/link.d.ts +38 -39
  85. package/dist/.dts/build/link.d.ts.map +1 -1
  86. package/dist/.dts/build/literal-eval.d.ts +2 -2
  87. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  88. package/dist/.dts/build/live-expirations.d.ts +14 -13
  89. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  90. package/dist/.dts/build/manifest.d.ts +6 -6
  91. package/dist/.dts/build/map-utils.d.ts +4 -4
  92. package/dist/.dts/build/merge-documentation.d.ts +9 -8
  93. package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
  94. package/dist/.dts/build/ownership-model.d.ts +14 -15
  95. package/dist/.dts/build/ownership-model.d.ts.map +1 -1
  96. package/dist/.dts/build/parse.d.ts +20 -21
  97. package/dist/.dts/build/parse.d.ts.map +1 -1
  98. package/dist/.dts/build/reference-projections.d.ts +36 -38
  99. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  100. package/dist/.dts/build/resolution/resolve-import.d.ts +18 -14
  101. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  102. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +26 -26
  103. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  104. package/dist/.dts/build/resolution/resolve-within-root.d.ts +9 -9
  105. package/dist/.dts/build/sarif.d.ts +5 -5
  106. package/dist/.dts/build/sarif.d.ts.map +1 -1
  107. package/dist/.dts/build/scan-dependencies.d.ts +17 -16
  108. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  109. package/dist/.dts/build/sort-by-identity.d.ts +1 -1
  110. package/dist/.dts/build/source-position.d.ts +13 -13
  111. package/dist/.dts/build/tool-version.d.ts +1 -1
  112. package/dist/.dts/build/usage-report.d.ts +19 -19
  113. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  114. package/dist/.dts/eslint-plugin/index.d.ts +16 -5
  115. package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
  116. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
  117. package/dist/.dts/evidence/define-projection.d.ts +15 -16
  118. package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
  119. package/dist/.dts/evidence/index.d.ts +11 -15
  120. package/dist/.dts/evidence/index.d.ts.map +1 -1
  121. package/dist/.dts/helpers/index.d.ts +15 -18
  122. package/dist/.dts/helpers/index.d.ts.map +1 -1
  123. package/dist/.dts/helpers/validators.d.ts +2 -2
  124. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  125. package/dist/.dts/node/index.d.ts +19 -0
  126. package/dist/.dts/node/index.d.ts.map +1 -1
  127. package/dist/.dts/runtime/create.d.ts +6 -3
  128. package/dist/.dts/runtime/create.d.ts.map +1 -1
  129. package/dist/.dts/runtime/document.d.ts +91 -97
  130. package/dist/.dts/runtime/document.d.ts.map +1 -1
  131. package/dist/.dts/runtime/errors.d.ts +5 -5
  132. package/dist/.dts/runtime/index.d.ts +11 -10
  133. package/dist/.dts/runtime/index.d.ts.map +1 -1
  134. package/dist/.dts/runtime/reset.d.ts +1 -1
  135. package/dist/.dts/runtime/types.d.ts +39 -24
  136. package/dist/.dts/runtime/types.d.ts.map +1 -1
  137. package/dist/.dts/runtime/validate.d.ts +15 -2
  138. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  139. package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
  140. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
  141. package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
  142. package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
  143. package/dist/.dts7/_ipc/display-path.d.ts +27 -0
  144. package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
  145. package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
  146. package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
  147. package/dist/.dts7/_ipc/glob.d.ts +23 -0
  148. package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
  149. package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
  150. package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
  151. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  152. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  153. package/dist/.dts7/_ipc/typescript.d.ts +20 -0
  154. package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
  155. package/dist/.dts7/build/assemble-project.d.ts +46 -0
  156. package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
  157. package/dist/.dts7/build/change-model.d.ts +63 -0
  158. package/dist/.dts7/build/change-model.d.ts.map +1 -0
  159. package/dist/.dts7/build/check-artifacts.d.ts +48 -0
  160. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
  161. package/dist/.dts7/build/citation-verification.d.ts +61 -0
  162. package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
  163. package/dist/.dts7/build/compatibility.d.ts +83 -0
  164. package/dist/.dts7/build/compatibility.d.ts.map +1 -0
  165. package/dist/.dts7/build/compiler-api.d.ts +12 -0
  166. package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
  167. package/dist/.dts7/build/contract-model.d.ts +93 -0
  168. package/dist/.dts7/build/contract-model.d.ts.map +1 -0
  169. package/dist/.dts7/build/deep-equal.d.ts +9 -0
  170. package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
  171. package/dist/.dts7/build/deep-freeze.d.ts +20 -0
  172. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
  173. package/dist/.dts7/build/dependency-graph.d.ts +163 -0
  174. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
  175. package/dist/.dts7/build/dependency-model.d.ts +81 -0
  176. package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
  177. package/dist/.dts7/build/discover.d.ts +41 -0
  178. package/dist/.dts7/build/discover.d.ts.map +1 -0
  179. package/dist/.dts7/build/display-path.d.ts +6 -0
  180. package/dist/.dts7/build/display-path.d.ts.map +1 -0
  181. package/dist/.dts7/build/docs.d.ts +172 -0
  182. package/dist/.dts7/build/docs.d.ts.map +1 -0
  183. package/dist/.dts7/build/env-example.d.ts +85 -0
  184. package/dist/.dts7/build/env-example.d.ts.map +1 -0
  185. package/dist/.dts7/build/errors.d.ts +78 -0
  186. package/dist/.dts7/build/errors.d.ts.map +1 -0
  187. package/dist/.dts7/build/evidence-cache.d.ts +74 -0
  188. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
  189. package/dist/.dts7/build/evidence-model.d.ts +50 -0
  190. package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
  191. package/dist/.dts7/build/evidence-reference.d.ts +67 -0
  192. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
  193. package/dist/.dts7/build/evidence-snapshot.d.ts +142 -0
  194. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
  195. package/dist/.dts7/build/exclusive-group.d.ts +19 -0
  196. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
  197. package/dist/.dts7/build/finding-model.d.ts +80 -0
  198. package/dist/.dts7/build/finding-model.d.ts.map +1 -0
  199. package/dist/.dts7/build/generate-documentation.d.ts +176 -0
  200. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
  201. package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
  202. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
  203. package/dist/.dts7/build/generate-evidence.d.ts +77 -0
  204. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
  205. package/dist/.dts7/build/generate-manifest.d.ts +100 -0
  206. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
  207. package/dist/.dts7/build/generate-usage.d.ts +94 -0
  208. package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
  209. package/dist/.dts7/build/generated-banner.d.ts +43 -0
  210. package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
  211. package/dist/.dts7/build/glob.d.ts +6 -0
  212. package/dist/.dts7/build/glob.d.ts.map +1 -0
  213. package/dist/.dts7/build/governance-fields.d.ts +34 -0
  214. package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
  215. package/dist/.dts7/build/humanize-key.d.ts +14 -0
  216. package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
  217. package/dist/.dts7/build/index.d.ts +89 -0
  218. package/dist/.dts7/build/index.d.ts.map +1 -0
  219. package/dist/.dts7/build/lifecycle-model.d.ts +181 -0
  220. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
  221. package/dist/.dts7/build/link.d.ts +222 -0
  222. package/dist/.dts7/build/link.d.ts.map +1 -0
  223. package/dist/.dts7/build/literal-eval.d.ts +24 -0
  224. package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
  225. package/dist/.dts7/build/live-expirations.d.ts +48 -0
  226. package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
  227. package/dist/.dts7/build/manifest.d.ts +31 -0
  228. package/dist/.dts7/build/manifest.d.ts.map +1 -0
  229. package/dist/.dts7/build/map-utils.d.ts +8 -0
  230. package/dist/.dts7/build/map-utils.d.ts.map +1 -0
  231. package/dist/.dts7/build/merge-documentation.d.ts +36 -0
  232. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
  233. package/dist/.dts7/build/ownership-model.d.ts +58 -0
  234. package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
  235. package/dist/.dts7/build/parse.d.ts +206 -0
  236. package/dist/.dts7/build/parse.d.ts.map +1 -0
  237. package/dist/.dts7/build/reference-projections.d.ts +168 -0
  238. package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
  239. package/dist/.dts7/build/resolution/resolve-import.d.ts +62 -0
  240. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
  241. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
  242. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
  243. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
  244. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
  245. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
  246. package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
  247. package/dist/.dts7/build/sarif.d.ts +66 -0
  248. package/dist/.dts7/build/sarif.d.ts.map +1 -0
  249. package/dist/.dts7/build/scan-dependencies.d.ts +71 -0
  250. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
  251. package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
  252. package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
  253. package/dist/.dts7/build/source-position.d.ts +69 -0
  254. package/dist/.dts7/build/source-position.d.ts.map +1 -0
  255. package/dist/.dts7/build/tool-version.d.ts +8 -0
  256. package/dist/.dts7/build/tool-version.d.ts.map +1 -0
  257. package/dist/.dts7/build/types.d.ts +7 -0
  258. package/dist/.dts7/build/types.d.ts.map +1 -0
  259. package/dist/.dts7/build/typescript.d.ts +6 -0
  260. package/dist/.dts7/build/typescript.d.ts.map +1 -0
  261. package/dist/.dts7/build/usage-report.d.ts +124 -0
  262. package/dist/.dts7/build/usage-report.d.ts.map +1 -0
  263. package/dist/.dts7/cli/filesystem.d.ts +7 -0
  264. package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
  265. package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
  266. package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
  267. package/dist/.dts7/eslint-plugin/index.d.ts +38 -0
  268. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
  269. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
  270. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
  271. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
  272. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
  273. package/dist/.dts7/evidence/define-projection.d.ts +51 -0
  274. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
  275. package/dist/.dts7/evidence/index.d.ts +19 -0
  276. package/dist/.dts7/evidence/index.d.ts.map +1 -0
  277. package/dist/.dts7/helpers/index.d.ts +132 -0
  278. package/dist/.dts7/helpers/index.d.ts.map +1 -0
  279. package/dist/.dts7/helpers/processors.d.ts +32 -0
  280. package/dist/.dts7/helpers/processors.d.ts.map +1 -0
  281. package/dist/.dts7/helpers/validators.d.ts +68 -0
  282. package/dist/.dts7/helpers/validators.d.ts.map +1 -0
  283. package/dist/.dts7/node/index.d.ts +21 -0
  284. package/dist/.dts7/node/index.d.ts.map +1 -0
  285. package/dist/.dts7/runtime/cache.d.ts +17 -0
  286. package/dist/.dts7/runtime/cache.d.ts.map +1 -0
  287. package/dist/.dts7/runtime/create.d.ts +23 -0
  288. package/dist/.dts7/runtime/create.d.ts.map +1 -0
  289. package/dist/.dts7/runtime/document.d.ts +214 -0
  290. package/dist/.dts7/runtime/document.d.ts.map +1 -0
  291. package/dist/.dts7/runtime/errors.d.ts +55 -0
  292. package/dist/.dts7/runtime/errors.d.ts.map +1 -0
  293. package/dist/.dts7/runtime/index.d.ts +25 -0
  294. package/dist/.dts7/runtime/index.d.ts.map +1 -0
  295. package/dist/.dts7/runtime/registry.d.ts +12 -0
  296. package/dist/.dts7/runtime/registry.d.ts.map +1 -0
  297. package/dist/.dts7/runtime/reset.d.ts +8 -0
  298. package/dist/.dts7/runtime/reset.d.ts.map +1 -0
  299. package/dist/.dts7/runtime/types.d.ts +190 -0
  300. package/dist/.dts7/runtime/types.d.ts.map +1 -0
  301. package/dist/.dts7/runtime/validate.d.ts +27 -0
  302. package/dist/.dts7/runtime/validate.d.ts.map +1 -0
  303. package/dist/{build-6XFHJFQK.js → build-UEENZEUX.js} +43 -42
  304. package/dist/build-UEENZEUX.js.map +1 -0
  305. package/dist/build.cjs +42 -41
  306. package/dist/build.cjs.map +1 -1
  307. package/dist/build.js +42 -41
  308. package/dist/build.js.map +1 -1
  309. package/dist/build.ts7.d.cts +1 -0
  310. package/dist/build.ts7.d.ts +1 -0
  311. package/dist/{chunk-RL5KFVUT.js → chunk-TBL3O7IG.js} +2 -2
  312. package/dist/cli/index.js +29 -28
  313. package/dist/cli/index.js.map +1 -1
  314. package/dist/eslint-plugin/index.cjs.map +1 -1
  315. package/dist/eslint-plugin/index.js.map +1 -1
  316. package/dist/eslint-plugin/index.ts7.d.cts +1 -0
  317. package/dist/eslint-plugin/index.ts7.d.ts +1 -0
  318. package/dist/evidence.cjs +1 -1
  319. package/dist/evidence.cjs.map +1 -1
  320. package/dist/evidence.js +1 -1
  321. package/dist/evidence.js.map +1 -1
  322. package/dist/evidence.ts7.d.cts +1 -0
  323. package/dist/evidence.ts7.d.ts +1 -0
  324. package/dist/helpers.cjs +4 -4
  325. package/dist/helpers.cjs.map +1 -1
  326. package/dist/helpers.js +4 -4
  327. package/dist/helpers.js.map +1 -1
  328. package/dist/helpers.ts7.d.cts +1 -0
  329. package/dist/helpers.ts7.d.ts +1 -0
  330. package/dist/index.cjs.map +1 -1
  331. package/dist/index.js.map +1 -1
  332. package/dist/index.ts7.d.cts +1 -0
  333. package/dist/index.ts7.d.ts +1 -0
  334. package/dist/node.ts7.d.cts +1 -0
  335. package/dist/node.ts7.d.ts +1 -0
  336. package/examples/README.md +46 -80
  337. package/package.json +43 -12
  338. package/schemas/contract-model.schema.json +7 -7
  339. package/schemas/env-cap-report.schema.json +88 -88
  340. package/skills/env-cap/SKILL.md +12 -13
  341. package/skills/env-cap/references/api.md +1 -1
  342. package/specs/architecture.md +147 -122
  343. package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
  344. package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
  345. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
  346. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
  347. package/specs/generated-artifacts.md +91 -71
  348. package/specs/migrations/README.md +6 -6
  349. package/specs/migrations/from-centralized-schema.md +1 -1
  350. package/specs/migrations/from-t3-env.md +9 -9
  351. package/PROMPT.md +0 -89
  352. package/dist/build-6XFHJFQK.js.map +0 -1
  353. /package/dist/{chunk-RL5KFVUT.js.map → chunk-TBL3O7IG.js.map} +0 -0
package/README.md CHANGED
@@ -10,81 +10,102 @@
10
10
  [![Node](https://img.shields.io/node/v/%40maverickcer%2Fenv-cap)](https://www.npmjs.com/package/@maverickcer/env-cap)
11
11
  [![License](https://img.shields.io/npm/l/%40maverickcer%2Fenv-cap)](LICENSE)
12
12
 
13
- **Define who owns your environment variables, why they exist, and where they are used.**
13
+ **Each feature declares the environment variables it needs and their format. Your app validates them all in one place at startup, fails fast on a bad value, and reports how they should be rotated before they expire.**
14
14
 
15
- `env-cap` turns environment configuration into capability-owned contracts you can version, review, validate, document, and query. It keeps `dotenv`, Zod, envalid, t3-env, your secret manager, and plain `process.env` exactly where they are, and adds the layer they do not provide: ownership, lifecycle, and project-wide evidence about whether declared configuration is actually consumed.
15
+ `env-cap` is a TypeScript library. A feature is a folder or an installable package in your code; the docs also call it a capability. It declares its variables in a **contract**: how to parse and check each value, who owns it and, for a secret, when it expires.
16
16
 
17
- [Why](#why-it-exists) · [See it run](#see-it-run) · [Install](#install-and-verify) · [Fit](#fit-and-capabilities) · [Limits](#limits-and-when-not-to-use-it) · [Security](#security-and-supply-chain) · [Maturity](#maturity-versioning-and-support) · [Docs](#documentation)
17
+ A build step lists every contract in the **manifest**, a generated file your app passes to `validateEnv()` at startup. A bad value throws an error that names the variable, never its value.
18
18
 
19
- ## Why it exists
19
+ **Rotation** replaces a secret before its expiry date, following the steps its contract gives. It applies to each variable whose `documentEnv()` entry declares both, for example `STRIPE_KEY: { expiresAt: "2026-09-01", refreshInstructions: "Rotate in the Stripe dashboard, then redeploy." }`. The build step writes environment docs that print those steps beside each date. They flag a variable that has expired or expires within 30 days, the default window. It also writes the **ownership report**: each contract's owner and the variables nothing reads.
20
+
21
+ It works alongside `dotenv`, Zod and your secret manager. It does not load `.env` files, store secrets or replace your validator.
22
+
23
+ **Try it:** run `npm install @maverickcer/env-cap`, then `npx env-cap init`. It writes a starter contract and a script that writes the manifest, the environment docs (`docs/ENVIRONMENT.md`) and the ownership report. A CI test runs both steps in an empty project ([Install and verify](#install-and-verify)). Once `validateEnv()` runs at startup, an `http://` value for the starter's `EXAMPLE_API_URL` stops the app with:
24
+
25
+ ```text
26
+ Environment validation failed.
20
27
 
21
- **Benefit:** every environment variable has an owner, a reason to exist, and a lifecycle you can query, so a rotation deadline or an orphaned secret is found by a report instead of an outage.
28
+ 1 configuration error found:
22
29
 
23
- **Problem:** a configuration value can be perfectly valid and still be a problem. A secret manager stores a credential securely and a validator confirms its shape, but neither says why the variable exists, which capability depends on it, who owns it, when it should be rotated or retired, or whether anything still consumes it. That knowledge drifts into wikis, Slack threads, and memory, until the application accepts a variable that nobody owns, nobody uses, or nobody remembers to retire.
30
+ EXAMPLE_API_URL
31
+ ---------------
32
+ Validation failed:
33
+ Expected an https URL.
34
+ ```
35
+
36
+ ## Why it exists
24
37
 
25
- **Who it is for:** platform and staff engineers responsible for configuration across teams or packages, and teams whose environment has outgrown a single `.env` convention.
38
+ **The problem:** a variable can be well-formed and still be a problem. A validator checks its shape and a secret manager stores it. Neither says who owns it, what depends on it, when it must rotate, or whether anything still reads it.
26
39
 
27
- **Why it matters:** an undetected expiry or an unowned secret is a security and availability risk that no validator can see, because the value itself is well-formed.
40
+ **What changes:** the answers live in the code next to each variable. An expiring secret shows up in the environment docs with the steps to rotate it, and a variable nothing reads shows up in the ownership report.
41
+
42
+ **Who it is for:** application developers who have shipped an undefined variable to production, and platform engineers who own configuration across teams.
28
43
 
29
44
  ## How it differs
30
45
 
31
- | Tool | What it solves | What remains unanswered |
32
- | ---------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
33
- | `dotenv` | Loads values from a `.env` file | Who owns the value, why it exists, whether it is still used, when it expires |
34
- | Zod / envalid / t3-env | Validates value shape and types | Whether the variable is still needed, who owns it, or what capability depends on it |
35
- | Secret manager | Stores and manages secrets | Which capability in the codebase actually consumes the secret |
36
- | `env-cap` | Defines ownership, lifecycle, and consumption contracts | Does not replace loading, secret storage, or application-specific validation |
46
+ | Tool | What it solves | What remains unanswered |
47
+ | ---------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
48
+ | `dotenv` | Loads values from a `.env` file | Who owns the value, why it exists, whether it is still used, when it expires |
49
+ | Zod / envalid / t3-env | Validates value shape and types | Whether the variable is still needed, who owns it, or what code depends on it |
50
+ | Secret manager | Stores and manages secrets | Which code actually reads the secret |
51
+ | `env-cap` | Validates each feature's variables at startup; reports expiry dates, rotation steps, owners and readers | Does not replace loading, secret storage, or application-specific validation |
37
52
 
38
- `env-cap` is additive: use it with your existing validator or processor, or with its lightweight helpers when a validation library is unnecessary. [Migration guides](specs/migrations/README.md) cover `dotenv`, Zod, envalid, and t3-env, including cases where switching is not worth it.
53
+ Keep your existing validator: any function that returns `true` or a message plugs into a contract. [Migration guides](specs/migrations/README.md) cover `dotenv`, Zod, envalid and t3-env, including when to stay put.
39
54
 
40
55
  ## What it does
41
56
 
42
- A capability declares the environment it owns next to the validation it already needs. A build-time pass reads those declarations and your source, and writes a project-wide manifest, documentation, an ownership report, and an evidence artifact. At runtime the application validates its environment against that manifest and reads typed, capability-scoped values.
57
+ Application developers write contracts with `@maverickcer/env-cap` and `./helpers`. Platform engineers who own CI use `./build`, the `env-cap` CLI and the GitHub Action. These write the manifest, the environment docs, the ownership report and the **evidence file**, a JSON record of owners, expiry dates and readers. `--check` fails when any of them is stale. Reviewers build their own views of the evidence file with `./evidence`. The [Guide](GUIDE.md) tells each reader's story in full. The table below is generated from `package.json#exports` and `docs/surface.json`; the `GeneratedRegions` check fails if it is stale.
43
58
 
44
- ```text
45
- declare → generate → validate → consume
46
- ```
59
+ <!-- ipc:begin entry-points -->
47
60
 
48
- ### See it run
61
+ | Export | Source | Environment | Tier | Purpose |
62
+ | ------------------------------------ | -------------------- | ------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
63
+ | `@maverickcer/env-cap` | `src/runtime/` | No Node module or Node global | Stable | `createEnv`, `documentEnv`, `validateEnv`, `resetEnvCache`, `isEnvContract` and the error types |
64
+ | `@maverickcer/env-cap/build` | `src/build/` | Node only, in development and CI | Stable | Discovery, AST analysis and artifact generation. The four `generate*()` orchestrators and the lower-level primitives are Stable (ADR 0045, `VERSIONING.md`). |
65
+ | `@maverickcer/env-cap/helpers` | `src/helpers/` | No Node module; `processors.base64()` returns a Node `Buffer` | Stable | `processors` and `validators` |
66
+ | `@maverickcer/env-cap/node` | `src/node/` | Node only, in development and CI | Stable | `nodeBuildFileSystem`, the `BuildFileSystem` adapter a build script hands to `./build` |
67
+ | `@maverickcer/env-cap/evidence` | `src/evidence/` | No Node module or Node global | Stable | `defineEvidenceProjection`, pure transforms over the Evidence Model (Stable, see `VERSIONING.md`) |
68
+ | `@maverickcer/env-cap/eslint-plugin` | `src/eslint-plugin/` | Node only, inside the project's ESLint | Stable | The `no-raw-process-env` and `no-node-fs` lint rules |
69
+ | `@maverickcer/env-cap/schema` | `schemas/` | Static JSON | Stable | The JSON Schema for `env-cap --json` output (`env-cap-report.schema.json`) and the model schemas under `./schema/*` |
49
70
 
50
- **Every environment variable has an owner, a reason to exist, and a lifecycle you can query.**
71
+ <!-- ipc:end entry-points -->
51
72
 
52
- A capability declares the environment it owns alongside the validation already needed at runtime:
73
+ ### See it run
53
74
 
54
- ```ts
55
- // features/payments/env.schema.ts
75
+ A contract declares the variables it owns next to their validation. This excerpt is from [`examples/application/src/env.ts`](https://github.com/MaverickCER/env-cap/blob/main/examples/application/src/env.ts), the file CI runs:
56
76
 
57
- import { createEnv, documentEnv } from "@maverickcer/env-cap"
77
+ ```ts
78
+ // examples/application/src/env.ts (excerpt: other variables and fields omitted)
79
+ import { createEnv, documentEnv, type RawEnv } from "@maverickcer/env-cap"
80
+ import { processors } from "@maverickcer/env-cap/helpers"
58
81
 
59
- const paymentsSchema = {
82
+ const schema = {
83
+ DATABASE_URL: { processor: processors.toURL() },
60
84
  STRIPE_KEY: {
61
- validator: (value: string) => value.startsWith("sk_") || 'Expected a key starting with "sk_".',
85
+ processor: (value: unknown): string => String(value ?? ""),
86
+ validator: (value: string, rawEnv: RawEnv) => {
87
+ if (rawEnv["PAYMENT_PROVIDER"] !== "stripe") return true
88
+ return value.length > 0 || "Stripe key is required when PAYMENT_PROVIDER=stripe."
89
+ },
62
90
  },
63
91
  }
64
92
 
65
- export const paymentsEnv = createEnv(paymentsSchema, { name: "payments" })
93
+ export const env = createEnv(schema, { name: "app", source: import.meta.url })
66
94
 
67
- documentEnv(paymentsSchema, {
68
- owner: "payments-team",
95
+ documentEnv(schema, {
96
+ owner: "platform-team",
69
97
  variables: {
98
+ DATABASE_URL: { description: "Postgres connection string.", required: true },
70
99
  STRIPE_KEY: {
71
- description: "Stripe secret key used to create charges and process refunds.",
72
- owner: "payments-team",
73
- expiresAt: "2027-01-01",
74
- sensitivity: "secret",
100
+ description: "Stripe secret key used to authenticate server-side API calls.",
101
+ required: true,
102
+ expiresAt: "2026-09-01",
75
103
  },
76
104
  },
77
105
  })
78
106
  ```
79
107
 
80
- Generate, then validate: the build-time analysis writes the manifest your code imports
81
- (`./generated/env.manifest`) and the evidence artifact, with one command (`npx env-cap init` scaffolds
82
- the same thing as a script, `scripts/generate-env.mjs`). The manifest and the
83
- persisted evidence artifact -- the two outputs a real project actually reads
84
- at runtime/in CI (see [ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md))
85
- -- come from the CLI itself; the human-facing docs/ownership report come
86
- from a small script calling `@maverickcer/env-cap/build` directly (see
87
- `examples/application/scripts/generate-docs`):
108
+ The CLI writes the manifest your code imports and the evidence file ([ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md)). A short script calls `@maverickcer/env-cap/build` for the human-facing docs and ownership report:
88
109
 
89
110
  ```text
90
111
  $ npx env-cap --include src/env.ts --location src/generated/env.manifest.ts --evidence docs/env.evidence.json
@@ -103,95 +124,97 @@ $ npx tsx scripts/generate-docs/run.ts
103
124
  - STRIPE_KEY in app
104
125
  ```
105
126
 
106
- This is real output from [`examples/application`](https://github.com/MaverickCER/env-cap/tree/main/examples/application)'s own `npm run docs` and `npm run docs:reports` scripts, not a mockup. The age (`Nd`) is counted from the day you run it, so it is shown as `N` here instead of a number that would rot.
107
-
108
- The important part is what the analysis can establish: `STRIPE_KEY` has an ownership and expiration record, its declared expiration has passed, and `DATABASE_URL` and `STRIPE_KEY` are declared as owned but are not consumed by the analyzed application. Those are facts about the application's configuration and dependencies, not merely the result of a value validator.
127
+ This is output from [`examples/application`](https://github.com/MaverickCER/env-cap/tree/main/examples/application) (`npm run docs:reports`). `N` stands for the days since 2026-09-01, counted on the day you run it. The report states facts a validator cannot see. `STRIPE_KEY` is declared to expire on 2026-09-01, and that date has passed. `DATABASE_URL` and `STRIPE_KEY` are declared in the `app` contract, but the analysis found no code that reads them.
109
128
 
110
129
  ### Evidence it works
111
130
 
112
- - **Real fixtures:** the output above comes from a runnable example that is also a regression test, and two more stages (a [team service](https://github.com/MaverickCER/env-cap/tree/main/examples/team-service) and an [enterprise platform](https://github.com/MaverickCER/env-cap/tree/main/examples/enterprise-platform)) show the model at scale.
113
- - **Enforced in CI:** coverage is a ratchet that may only move up, mutation score is a gate ([CODE_REVIEW.md](CODE_REVIEW.md)), and the README's own demo is re-run and compared on every change.
114
- - **Runtime-tested:** the runtime and helpers are verified against real Node, Bun, and Deno in CI, not assumed isomorphic.
115
- - **Hard size budget:** the runtime entry point stays under 3 KB gzip and the helpers under 4 KB, enforced before publish ([ADR 0008](specs/decisions/0008-gzip-size-budget.md)).
116
- - **Verifiable release:** published with npm OIDC provenance and no long-lived token ([SECURITY.md](SECURITY.md#supply-chain-posture)).
131
+ - **Real output:** CI's `examples` job re-runs the block above and compares its expiry and unconsumed lists with this README (`npm run verify:readme-example`). `required` waits for `examples`, so a failure blocks a merge.
132
+ - **Coverage floors:** 90% branches, 100% functions, 95% lines and statements, enforced by the `contract` job (`vitest.config.ts`). A pull request can lower a floor; reviewers treat that as a reviewed change.
133
+ - **Mutation testing:** the `contract` job fails on any surviving, timed-out or uncovered Stryker mutant in `src/`. Managed copies under `src/_ipc/`, `scripts/`, and mutants silenced by a disable comment are not counted.
134
+ - **Runtimes:** the runtime, helpers and evidence entries run on Node 22 and 24 in blocking jobs. They also run under Bun, Deno and a Web-globals VM. `required` waits for the Bun and Deno job (`cross-runtime`).
135
+ - **Size budgets:** 3 KB gzip for the runtime, 4 KB for helpers and 3 KB for evidence, enforced by the `Size` check ([ADR 0008](specs/decisions/0008-gzip-size-budget.md)). The budget measures the entry file, not your bundle.
117
136
 
118
137
  ## Install and verify
119
138
 
120
- **Prerequisites:** Node.js `>=22`. TypeScript 5, 6, or 7 is needed only for the build-time generator (the runtime works in plain JavaScript); the [runtime and TypeScript requirements](GUIDE.md#runtime-support-matrix) are in the Guide.
139
+ **Prerequisites:** Node.js `>=22`. Your own TypeScript is optional. The generator uses it when it is version 5 or 6, and otherwise the bundled TypeScript 6 compiler. CI tests the newest 5.x only; the 5.0 floor is untested. The runtime works in plain JavaScript ([requirements](GUIDE.md#requirements)).
121
140
 
122
141
  ```sh
123
142
  npm install @maverickcer/env-cap
124
- npx env-cap init # scaffolds env.schema.ts and scripts/generate-env.mjs
125
- npm install --save-dev typescript # the generator parses your schema with it
143
+ npx env-cap init # writes env.schema.ts and scripts/generate-env.mjs
126
144
  node scripts/generate-env.mjs
127
145
  ```
128
146
 
129
- **Using an AI agent?** Give it [the skill](https://raw.githubusercontent.com/MaverickCER/env-cap/main/skills/env-cap/SKILL.md): a short manual written from this package's own exports, with the rules a type signature cannot say.
147
+ `init` writes two files and skips any file that already exists. Without a valid `package.json` it exits `1` and writes nothing. `test/cli/init.test.ts` pins these rules and the templates. **Verify it works:** the script prints `Discovered 1 contract(s).` and exits `0`. `test/cli/quick-start.test.ts` runs `init` and the script against the built package and checks that line and each generated file. Report an issue if that line differs.
130
148
 
131
- `init` never overwrites existing files and never edits `package.json`. **Verify it works:** the generator prints `Discovered 1 contract(s).` and writes the manifest, `docs/ENVIRONMENT.md`, and an ownership report. Then validate once at startup and read values through the contract:
149
+ Then validate once at startup and read values through the contract. `init` writes `env.schema.ts` into `src/` when that folder exists, otherwise into the project root; adjust the import path to match:
132
150
 
133
151
  ```ts
134
152
  import { validateEnv } from "@maverickcer/env-cap"
135
153
  import { manifest } from "./generated/env.manifest"
136
- import { paymentsEnv } from "./features/payments/env.schema"
154
+ import { exampleEnv } from "./env.schema"
137
155
 
138
156
  await validateEnv({ manifest, values: process.env })
139
- paymentsEnv.STRIPE_KEY
157
+ exampleEnv.EXAMPLE_API_URL
140
158
  ```
141
159
 
142
- The smallest contract is one `createEnv` call with a validator per variable ([Core workflow](GUIDE.md#core-workflow) has the complete generate and validate cycle).
143
-
144
160
  ## Fit and capabilities
145
161
 
146
- **Use cases:** find expired or unowned secrets before they page someone; document every variable from the code instead of a wiki; let each team own the variables its feature needs; give CI bots and coding agents concrete facts (`payments owns STRIPE_KEY`, `STRIPE_KEY is declared but unconsumed`) instead of "configuration check failed".
162
+ **Use cases:** find expired or unowned secrets before they page someone. Generate variable documentation from the code instead of a wiki. Let each team own the variables its feature needs. Give CI bots facts such as "`STRIPE_KEY` is declared but unconsumed".
163
+
164
+ **What you get:**
147
165
 
148
- **Core capabilities:**
166
+ - Per-feature contracts with validators, owners, sensitivity and expiry dates ([contracts](GUIDE.md#capability-owned-contracts)).
167
+ - A manifest, environment docs, `.env.example` and an ownership report, from static analysis that never imports your schema files.
168
+ - A persisted evidence file, a CLI, a [GitHub Action](GUIDE.md#github-action), scheduled rotation reports and an [ESLint plugin](GUIDE.md#eslint-plugin).
169
+ - One central schema or one contract per feature or package; the manifest stays project-wide either way.
149
170
 
150
- - Capability-scoped contracts with validators, ownership, sensitivity, and expiry ([model](GUIDE.md#capability-owned-contracts)).
151
- - A project-wide manifest, environment docs, `.env.example`, and an ownership and unconsumed-variable report, generated by static analysis that never executes your schema files.
152
- - A persisted evidence artifact for change tracking, a CLI, a [GitHub Action](GUIDE.md#github-action), scheduled rotation alerts, and an [ESLint plugin](GUIDE.md#eslint-plugin).
153
- - Adoption from one centralized schema to per-feature and per-package contracts; the manifest stays project-wide however the schema is organized.
171
+ **How it works:** the runtime and the build tooling are separate entry points. The runtime has no filesystem access, which lint and a tarball scan enforce. The build pass runs only in development and CI ([Architecture](GUIDE.md#runtime-and-build-time-are-intentionally-separate)).
154
172
 
155
- **How it works:** the runtime and the build tooling are separate on purpose. Runtime validation needs no dependencies and no filesystem; the build pass analyzes your source and runs only in development and CI ([Architecture](specs/architecture.md)).
173
+ **Runtimes:** Node.js 22 and 24 are tested. Bun, Deno and a browser-style bundle run in CI for the runtime, helpers and evidence entries. Edge runtimes are not tested ([support matrix](GUIDE.md#runtime-support-matrix)).
156
174
 
157
- **Integration:** it works beside the validator and secret manager you already use, so nothing is replaced. **Runtimes:** Node.js 22+, browser bundles, edge runtimes, Bun, and Deno for the runtime; the build entry is Node-only ([support matrix](GUIDE.md#runtime-support-matrix)). **Configuration and extension:** plug any `Validator<T>` or `Processor<T>` function into a contract, share contracts from a reusable package, and resolve TypeScript path aliases ([Guide](GUIDE.md)).
175
+ **Package managers:** npm is supported. pnpm, Yarn 1 and Yarn Berry are tested only for installing the tarball and importing every entry ([details](GUIDE.md#package-managers)).
158
176
 
159
177
  ## Limits and when not to use it
160
178
 
161
- - **Skip it when** the application is small, one team owns every configuration decision, there are only a few stable variables, ownership is already obvious, or you do not need project-wide evidence about usage. A validation library or `dotenv` may be all you need.
162
- - **Trade-offs:** it adds a build step and a declaration per variable, and its reports are only as accurate as those declarations. It cannot see variables read from outside the code it analyzes.
163
- - **Install weight:** the build entry bundles a TypeScript 6 compiler (about 24 MB unpacked) used only in development and CI; the runtime never reaches it, which CI verifies ([Adoption guide](ADOPTION.md#bundle-size-and-performance)).
164
- - **Automation:** agents and bots can consume the same manifests and evidence, but a structured finding does not guarantee a correct fix; the automation owns its retry and validation loop. See the [AI integration prompt](PROMPT.md).
179
+ - **Skip it when** one team owns every variable, there are few of them, and ownership is obvious. A validator or `dotenv` may be all you need.
180
+ - **Trade-offs:** it adds a build step and a declaration per variable. Its reports are only as accurate as those declarations, and it cannot see variables read outside the analyzed code.
181
+ - **Install weight:** the one dependency is a TypeScript 6 compiler bundled in the tarball. Only the build entry loads it, and a CI step fails if a runtime entry can reach it ([Adoption guide](ADOPTION.md#bundle-size-and-performance)).
182
+ - **Dynamic schemas:** 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.
183
+ - **Automation:** bots can read the same manifest and evidence. A structured finding does not make a fix correct, so review a bot's change as you would a person's.
165
184
 
166
185
  ## Security and supply chain
167
186
 
168
- - **Guarantees:** the runtime never persists, retrieves, rotates, or logs secrets, and contracts redact themselves when logged or serialized ([runtime security model](SECURITY.md#runtime-security-model)).
169
- - **Trust boundaries:** the build tool parses schema files as ASTs and never imports or executes them, but it does not sandbox the rest of your build, and a validator you write can still log ([build-time model](SECURITY.md#build-time-security-model), [your responsibilities](SECURITY.md#application-responsibilities)).
170
- - **Dependencies and licence:** zero runtime dependencies in the runtime and helpers entry points; the build entry bundles one compiler. MIT licensed.
171
- - **Release integrity:** npm OIDC trusted publishing with provenance ([supply-chain posture](SECURITY.md#supply-chain-posture)). Report a vulnerability through [SECURITY.md](SECURITY.md#reporting-a-vulnerability).
187
+ - **Runtime:** it has no filesystem access and reads only the `values` you pass. Lint and the tarball scan enforce the first; the tarball scan and a browser-bundle test the second. Both scans are textual. Contracts redact themselves when logged or serialized, but spreading a contract reads every value ([runtime model](SECURITY.md#runtime-security-model)).
188
+ - **Errors:** validation errors carry variable and contract names and your own messages, never values (tested). A validator message that embeds the value is passed through.
189
+ - **Build:** schema files are parsed as syntax trees and never imported or run (tested). It does not sandbox the rest of your build ([build-time model](SECURITY.md#build-time-security-model)).
190
+ - **Dependencies:** what installing the package adds is generated from `package.json` into the [Adoption guide](ADOPTION.md#security--threat-model). MIT licensed.
191
+ - **Release integrity:** releases publish from CI over npm OIDC with a provenance attestation, and the repository stores no npm token. A manual last-resort publish carries no attestation ([supply chain](SECURITY.md#supply-chain-posture)).
192
+ - **Report a vulnerability** privately: [SECURITY.md](SECURITY.md#reporting-a-vulnerability).
172
193
 
173
194
  ## Maturity, versioning and support
174
195
 
175
- Pre-1.0 (see the npm badge for the current version). Per [VERSIONING.md](VERSIONING.md), a minor release may include a breaking change to the Stable tier before 1.0, so pin accordingly. Security fixes target the latest published `0.x` only; there is no backport branch until 1.0 ([Adoption guide](ADOPTION.md#versioning-stability-and-long-term-support)).
196
+ Pre-1.0; the npm badge shows the current version. Before 1.0, a minor release may break the Stable tier, so pin a version ([VERSIONING.md](VERSIONING.md)). Security fixes target the latest `0.x` only, with no backport branch before 1.0.
176
197
 
177
- - **Upgrade and migrate:** read the [CHANGELOG](CHANGELOG.md) on every minor; [migration guides](specs/migrations/README.md) cover adoption from other tools.
178
- - **Release history:** [CHANGELOG](CHANGELOG.md) and [GitHub releases](https://github.com/MaverickCER/env-cap/releases); the process is in [RELEASING.md](RELEASING.md).
198
+ - **Upgrade:** read the [CHANGELOG](CHANGELOG.md) on every minor; [migration guides](specs/migrations/README.md) cover adoption from other tools.
199
+ - **Releases:** [GitHub releases](https://github.com/MaverickCER/env-cap/releases); a person merges every release pull request ([RELEASING.md](RELEASING.md)).
179
200
  - **Bugs and requests:** [open an issue](https://github.com/MaverickCER/env-cap/issues); see [SUPPORT.md](SUPPORT.md).
180
- - **Troubleshooting:** the [Guide's troubleshooting section](GUIDE.md#troubleshooting).
201
+ - **Troubleshooting:** the [Guide's troubleshooting table](GUIDE.md#troubleshooting).
181
202
 
182
203
  ## Documentation
183
204
 
184
- - **[Guide](GUIDE.md)**: the complete generate and validate workflow, validation contexts, reusable packages, path aliases, CLI, GitHub Action, ESLint plugin, and performance.
185
- - **[Adoption guide](ADOPTION.md)**: the decision-maker summary of security, bundle size, and versioning.
186
- - **[API reference](https://maverickcer.github.io/env-cap/api/)**: every exported symbol, generated from source.
187
- - **[Architecture](specs/architecture.md)** and **[ADRs](https://github.com/MaverickCER/env-cap/tree/main/specs/decisions)**: why it is designed this way.
188
- - **[Examples](https://github.com/MaverickCER/env-cap/tree/main/examples)**: runnable application, team-service, and enterprise-platform examples.
189
- - **Part of the MaverickCER toolkit:** `@maverickcer/env-cap` governs configuration and `data-cap` governs application data; `repo-contract` and `internal-package-contract` are how they are verified ([toolkit overview](https://github.com/MaverickCER/internal-package-contract/blob/main/TOOLKIT.md)).
205
+ - **[Guide](GUIDE.md):** one story per entry point and reader, the CLI options, the GitHub Action and the ESLint plugin.
206
+ - **[Adoption guide](ADOPTION.md):** what adopting costs, what it needs, and what it refuses to do.
207
+ - **[Security](SECURITY.md):** the reviewer's model of what is enforced, where, and what is not.
208
+ - **[API reference](https://maverickcer.github.io/env-cap/api/):** every exported symbol, generated from source.
209
+ - **[Agent skill](https://raw.githubusercontent.com/MaverickCER/env-cap/main/skills/env-cap/SKILL.md):** a short manual for an AI agent, generated from `docs/skill.json` and the exports; [AGENTS.md](AGENTS.md) adds the rules for this repository.
210
+ - **[Architecture](specs/architecture.md)** and **[ADRs](https://github.com/MaverickCER/env-cap/tree/main/specs/decisions):** why it is designed this way.
211
+ - **[Examples](https://github.com/MaverickCER/env-cap/tree/main/examples):** runnable application, team-service, enterprise-platform and Next.js examples.
212
+ - **Toolkit:** `data-cap` governs application data; `repo-contract` and `internal-package-contract` verify both ([toolkit overview](https://github.com/MaverickCER/internal-package-contract/blob/main/TOOLKIT.md)).
190
213
 
191
214
  ## Next steps
192
215
 
193
- - **Evaluate:** read the [Adoption guide](ADOPTION.md), then try env-cap against one real schema.
194
- - **Integrate:** follow the [Guide](GUIDE.md#core-workflow) and the [examples](https://github.com/MaverickCER/env-cap/tree/main/examples).
195
- - **Verify:** inspect the [security model](SECURITY.md#runtime-security-model) and the [architecture](specs/architecture.md).
216
+ - **Evaluate:** read the [Adoption guide](ADOPTION.md), then try env-cap on one real schema.
217
+ - **Integrate:** follow the [Guide](GUIDE.md#core-workflow) and run an [example](https://github.com/MaverickCER/env-cap/tree/main/examples).
218
+ - **Verify:** check the [security model](SECURITY.md#runtime-security-model) against the tests it names.
196
219
 
197
- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) covers setup, the change workflow, ADRs and changesets; [CODE_REVIEW.md](CODE_REVIEW.md) covers review. License: MIT, see [LICENSE](LICENSE).
220
+ Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) covers setup and changesets; [CODE_REVIEW.md](CODE_REVIEW.md) covers review. License: MIT, see [LICENSE](LICENSE).
package/RELEASING.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # Releasing @maverickcer/env-cap
4
4
 
5
- Maintainer-facing. Contributors don't run any of this: a normal change is just a pull request, and its
5
+ Maintainer-facing. Contributors run none of this: a normal change is a pull request, and its
6
6
  changeset is generated if it has none (see [`CONTRIBUTING.md`](CONTRIBUTING.md#making-a-change)).
7
7
  For what semver actually covers, see [`VERSIONING.md`](VERSIONING.md).
8
8
 
@@ -11,33 +11,42 @@ For what semver actually covers, see [`VERSIONING.md`](VERSIONING.md).
11
11
  Releases are driven by [Changesets](https://github.com/changesets/changesets) and npm's
12
12
  [OIDC trusted publishing](https://docs.npmjs.com/trusted-publishers), through
13
13
  [`.github/workflows/release.yml`](https://github.com/MaverickCER/env-cap/blob/main/.github/workflows/release.yml),
14
- which calls a shared, pinned workflow. **No `NPM_TOKEN` secret exists in this repository** and none is
15
- needed: npm verifies the workflow's OIDC identity against a one-time trusted-publisher registration on
16
- npmjs.com (see [First-time setup](#first-time-setup)). A person merges the release pull request; nothing
17
- publishes without that.
14
+ which calls a shared, pinned workflow. A person merges the release pull request.
15
+
16
+ **No `NPM_TOKEN` secret exists in this repository**, and none is needed. The workflow's OIDC identity is
17
+ verified by npm against a one-time trusted-publisher registration on npmjs.com (see
18
+ [First-time setup](#first-time-setup)).
19
+
20
+ The one other path is recovery. A version on `main` that is not on npm is built and published without a pull
21
+ request (see "Recovering from a failed release").
18
22
 
19
23
  The loop:
20
24
 
21
25
  1. A pull request that changes user-facing behavior carries a changeset in `.changeset/` (Markdown,
22
26
  `patch`/`minor`/`major` plus a consumer-facing description). When it does not, one is generated on `main`
23
- from the commit messages (`feat`, `fix`, `perf`, `revert` or a breaking marker; a `Changeset: <bump>`
24
- trailer overrides). Below 1.0.0 a generated bump never exceeds minor, so 1.0.0 is reached only by a
27
+ from the commit messages: `feat`, `fix`, `perf`, `revert` or a breaking marker. A `Changeset: <bump>`
28
+ trailer overrides. Below 1.0.0 a generated bump never exceeds minor, so 1.0.0 is reached only by a
25
29
  deliberate `major` changeset.
26
30
  2. On each push to `main`, the workflow opens or updates a pull request titled **"chore: version packages"**
27
- from the branch **`changeset-release/main`** and dispatches CI on it. That pull request consumes the
28
- changeset files, bumps `package.json`'s `version` and rewrites `CHANGELOG.md`. Review it and merge it
29
- yourself; it is never merged automatically.
30
- 3. Merging it runs the workflow again. A **build** job, which holds no publishing credentials, runs
31
- `npm run verify` when the package defines it, packs the tarball, installs that tarball into an empty
32
- project and imports every entry point it declares. Only if all of that passes does the **publish** job
33
- run, and only from the default branch. It publishes exactly the tarball the build job made, over OIDC with
34
- a provenance attestation.
35
- 4. After publishing, the workflow tags the release `v<major>.<minor>.<patch>` on the merged commit,
36
- force-updates the floating major tag (`v0` while the package is 0.x, `v1` from 1.0.0), and asks npm what
37
- it now serves: the version must be there and must carry the provenance attestation, or the run goes red.
38
- The floating tag tracks the composite Action's interface (`action.yml` inputs and outputs), so
39
- `uses: maverickcer/env-cap@v0` keeps pointing at the latest compatible build until `action.yml` itself
40
- has a breaking change.
31
+ from the branch **`changeset-release/main`**. It dispatches CI on that pull request. The pull request
32
+ consumes the changeset files, bumps `package.json`'s `version` and rewrites `CHANGELOG.md`. Review it and
33
+ merge it yourself; it is never merged automatically.
34
+ 3. Merging it runs the workflow again. A **build** job, which holds no publishing credentials:
35
+ - runs `npm run verify` when the package defines it;
36
+ - requires that a CI run on a commit with exactly this tree finished its `contract` job with success, and
37
+ its `required` job too where that run has one;
38
+ - checks that no scaffold prompt is unanswered;
39
+ - packs the tarball, installs that tarball into an empty project and imports every entry point it declares.
40
+
41
+ Only if all of that passes does the **publish** job run, and only from the default branch. It publishes
42
+ exactly the tarball the build job made, over OIDC with a provenance attestation.
43
+
44
+ 4. After publishing, the workflow tags the release `v<major>.<minor>.<patch>` on the merged commit. It
45
+ force-updates the floating major tag (`v0` while the package is 0.x, `v1` from 1.0.0). Then it asks npm
46
+ what it now serves. The version must be there and must carry the provenance attestation, or the run goes
47
+ red. The floating tag tracks the composite Action's interface (`action.yml` inputs and outputs).
48
+ `uses: maverickcer/env-cap@v0` therefore keeps pointing at the latest compatible build until
49
+ `action.yml` itself has a breaking change.
41
50
 
42
51
  `CHANGELOG.md` is generated; never hand-edit it. Fix a wrong entry by correcting the offending changeset
43
52
  before the version pull request is merged, or with a follow-up changeset after.
@@ -52,26 +61,23 @@ access, so it can't be done from a PR.
52
61
  GitHub Actions:
53
62
  - Organization or user: `maverickcer`
54
63
  - Repository: `env-cap`
55
- - Workflow filename: `release.yml` (exactly — just the filename, not a
56
- path; a mismatch here is the most common cause of the OIDC flow failing
57
- with a misleading `E404`)
64
+ - Workflow filename: `release.yml`. Enter exactly the filename alone, not a path. A mismatch here is the
65
+ most common cause of the OIDC flow failing with a misleading `E404`.
58
66
  - Environment: leave blank unless `release.yml` is later scoped to a
59
67
  GitHub Environment
60
- 2. That's the whole trust relationship — `release.yml`'s `id-token: write`
68
+ 2. That is the whole trust relationship: `release.yml`'s `id-token: write`
61
69
  permission plus this registration. There is no token to copy anywhere.
62
70
 
63
- Until the package exists on npm, its settings page doesn't either. For the
64
- **first ever publish**, register the trusted publisher immediately after the
65
- first `npm publish` (a one-time manual `npm publish --access public` from a
66
- maintainer machine, from a clean `npm run verify` tree), then let every
67
- subsequent release go through `release.yml`. Alternatively, publish an empty
68
- `0.0.0` placeholder manually first, register the trusted publisher, then let
69
- the first real version pull request publish `0.1.0` over OIDC.
71
+ Until the package exists on npm, its settings page doesn't either. For the **first ever publish**, make a
72
+ one-time manual `npm publish --access public` from a maintainer machine, from a clean `npm run verify` tree.
73
+ Register the trusted publisher immediately after that first `npm publish`. Then let every subsequent release
74
+ go through `release.yml`. Alternatively, publish an empty `0.0.0` placeholder manually first, register the
75
+ trusted publisher, then let the first real version pull request publish `0.1.0` over OIDC.
70
76
 
71
77
  ## Recovering from a failed release
72
78
 
73
- Identify which state you're in first — the recovery differs and the wrong
74
- one can double-publish or lose a version.
79
+ Identify which state you're in first. The recovery differs, and the wrong one can double-publish or lose a
80
+ version.
75
81
 
76
82
  ### A. The version pull request is open, nothing published yet
77
83
 
@@ -83,30 +89,39 @@ Nothing is on npm; nothing to undo.
83
89
  ### B. The version pull request is merged, but the release failed
84
90
 
85
91
  `main` now has the version bump and changelog commit, but npm does not have the version. This is the common
86
- failure (OIDC misconfiguration, a failing `npm run verify` or packed-consumer check in the build job, a
87
- registry blip).
92
+ failure. Its causes include:
93
+
94
+ - OIDC misconfiguration;
95
+ - a failing `npm run verify`;
96
+ - no CI run on the tree that passed `contract` and, where the run has it, `required`;
97
+ - a failing packed-consumer check in the build job;
98
+ - a registry blip.
99
+
100
+ To recover:
88
101
 
89
102
  1. Confirm npm really doesn't have it: `npm view @maverickcer/env-cap versions --json`, and check the bumped version is
90
103
  absent.
91
104
  2. Find the cause (see [Common failures](#common-failure-causes)).
92
105
  3. If it was transient or a configuration problem outside the repository (a registry blip, the
93
- trusted-publisher registration), fix that and re-run the failed `release.yml` run from the Actions tab
106
+ trusted-publisher registration), fix that. Then re-run the failed `release.yml` run from the Actions tab
94
107
  ("Re-run failed jobs"). A re-run uses the same commit.
95
108
  4. If the cause is in the code, a re-run cannot help: it would build the same commit again. Fix it in a normal
96
- pull request to `main`. What happens next depends on the commit type. A `fix`, `feat`, `perf` or `revert`
97
- commit gets a changeset generated for it, so the workflow opens a new version pull request instead of
98
- publishing the stuck version; merging that publishes the next version, and the stuck version number is
99
- simply skipped. A commit type that releases nothing (`chore`, `ci`, `docs`) leaves no changeset, so the
100
- workflow sees that the current `package.json` version isn't on npm and builds and publishes that version.
101
- 5. Publishing by hand is the last resort, and it publishes without the provenance attestation that the
102
- workflow adds. If you must, publish that exact version from a clean tree
103
- (`git checkout main && npm ci && npm run verify && npm publish --access public`), then confirm the next push
109
+ pull request to `main`. What happens next depends on the commit type.
110
+ - A `fix`, `feat`, `perf` or `revert` commit gets a changeset generated for it. The workflow then opens a
111
+ new version pull request instead of publishing the stuck version. Merging that publishes the next
112
+ version, and the stuck version number is skipped.
113
+ - A commit type that releases nothing (`chore`, `ci`, `docs`) leaves no changeset. The workflow then sees
114
+ that the current `package.json` version isn't on npm, and builds and publishes that version.
115
+ 5. Publishing by hand is the last resort. It skips the build job's proof that CI passed `contract` (and
116
+ `required`) on this tree, and it publishes without the provenance attestation that the workflow adds.
117
+ Check the CI run on that commit yourself first. If you must, publish that exact version from a clean tree
118
+ (`git checkout main && npm ci && npm run verify && npm publish --access public`). Then confirm the next push
104
119
  to `main` produces no spurious version pull request.
105
120
 
106
121
  ### C. Published to npm, but a later workflow step failed
107
122
 
108
- e.g. the publish succeeded but the floating major tag (`v0` or `v1`) roll failed. The release itself
109
- is done and correct. Just fix the trailing step manually:
123
+ For example, the publish succeeded but the floating major tag (`v0` or `v1`) roll failed. The release itself
124
+ is done and correct. Fix the trailing step by hand:
110
125
 
111
126
  ```bash
112
127
  git checkout main && git pull
@@ -114,47 +129,48 @@ git tag -f v0 && git push origin v0 --force # while the package is 0.x
114
129
  git tag -f v1 && git push origin v1 --force # from 1.0.0
115
130
  ```
116
131
 
117
- Do **not** re-run the whole workflow — `changeset publish` is idempotent and
118
- will no-op on the already-published version, but re-running risks masking
119
- whatever the real trailing failure was.
132
+ Fix it by hand rather than re-running the workflow. A re-run publishes nothing and runs none of the later
133
+ steps: the build job finds the version already on npm and stops there.
120
134
 
121
135
  ### D. Wrong version published
122
136
 
123
- npm publishes are effectively permanent (`npm unpublish` is allowed only
124
- within 72 hours and only if nothing depends on it, and the version number
125
- can never be reused). Don't try to unpublish a normal mistake. Instead:
137
+ npm publishes are effectively permanent. `npm unpublish` is allowed only within 72 hours and only if nothing
138
+ depends on it, and the version number can never be reused. Don't try to unpublish a normal mistake. Instead:
126
139
 
127
140
  - Wrong contents, right version number: publish a patch (`x.y.z+1`) with a
128
- changeset that fixes it, and `npm deprecate @maverickcer/env-cap@x.y.z
129
- "Broken publish — use x.y.z+1"`.
141
+ changeset that fixes it, and `npm deprecate @maverickcer/env-cap@x.y.z "Broken publish; use x.y.z+1"`.
130
142
  - Accidental major/minor bump: it stays. Continue from the new baseline; a
131
143
  version number is cheap, a rewritten history is not.
132
144
 
133
145
  ### E. First release, package not yet on npm
134
146
 
135
- See [First-time setup](#first-time-setup) — the trusted-publisher
136
- registration cannot exist before the package does, so the first publish is
137
- the one manual step. Every release after that is automated.
147
+ See [First-time setup](#first-time-setup). The trusted-publisher registration cannot exist before the
148
+ package does, so the first publish is the one manual step. Every release after that is automated.
138
149
 
139
150
  ## Common failure causes
140
151
 
141
152
  - **`E404` on publish with OIDC**: the trusted-publisher registration's
142
153
  workflow filename doesn't exactly match `release.yml`, or the
143
154
  org/user/repo fields are wrong.
144
- - **The build job's verify or packed-consumer step fails**: the version pull request merged with a red
145
- `main`, or the tarball does not contain what `exports` promises. Fix `main` first, then recover per case B.
155
+ - **The build job's verify, contract-run or packed-consumer step fails**: one of these happened.
156
+ - The version pull request merged with a red `main`.
157
+ - No CI run on that tree passed `contract` and, where the run has it, `required`.
158
+ - The tarball does not contain what `exports` promises.
159
+
160
+ Fix `main` first, then recover per case B.
161
+
146
162
  - **The final "Verify what npm now serves" step fails**: npm did not return the version or its provenance
147
163
  attestation. Nothing is unpublished by the failure; look at the registry before doing anything else.
148
- - **A version pull request appears when you didn't expect one**: there's a stray changeset file in `.changeset/` on `main`. If it's
149
- spurious, delete it in a normal PR.
164
+ - **A version pull request appears when you didn't expect one**: there's a stray changeset file in
165
+ `.changeset/` on `main`. If it's spurious, delete it in a normal PR.
150
166
  - **Two version pull requests**: an older one wasn't closed when `main` moved. Close the stale one; the
151
167
  workflow only maintains the newest.
152
168
 
153
169
  ## Related
154
170
 
155
- - [`VERSIONING.md`](VERSIONING.md) — what each bump type means, and which
171
+ - [`VERSIONING.md`](VERSIONING.md): what each bump type means, and which
156
172
  surface semver actually covers.
157
- - [`CONTRIBUTING.md`](CONTRIBUTING.md) — the contributor-side workflow
173
+ - [`CONTRIBUTING.md`](CONTRIBUTING.md): the contributor-side workflow
158
174
  (branch, changeset, PR).
159
- - [`SECURITY.md`](SECURITY.md#supported-versions) — which versions get
175
+ - [`SECURITY.md`](SECURITY.md#supported-versions): which versions get
160
176
  security fixes.