@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
@@ -0,0 +1,132 @@
1
+ /**
2
+ * Optional processors and validators for common cases (`@maverickcer/env-cap/helpers`), such as
3
+ * `processors.toNumber()` and `validators.range(1, 65535)`.
4
+ *
5
+ * A contract works the same without them: `createEnv` and `validateEnv` never import this module. Any
6
+ * function with the `Processor<T>` or `Validator<T>` shape plugs in the same way.
7
+ *
8
+ * The two objects are plain literals of named imports, not `export * as processors`. A bundler lowers
9
+ * `export * as` into a namespace helper call it cannot prove free of side effects. That call blocks
10
+ * tree-shaking in a consumer's own bundler, so importing `processors` alone would still ship
11
+ * `validators`. With plain literals, importing `processors` alone drops `validators` entirely.
12
+ *
13
+ * @packageDocumentation
14
+ */
15
+ import { base64, parseJSON, split, toArray, toBigInt, toBoolean, toDate, toInteger, toLowerCase, toNumber, toRegExp, toString, toURL, toUpperCase, trim } from "./processors.js";
16
+ import { after, all, any, before, custom, email, endsWith, finite, future, includes, integer as integerValidator, length, matches, max, maxItems, maxLength, min, minItems, minLength, negative, not, oneOf, optional, past, positive, range, refine, required, safeInteger, unique, url as urlValidator, uuid, uuidVersion } from "./validators.js";
17
+ /**
18
+ * Convenience {@link runtime.Processor} implementations for common coercion
19
+ * patterns (e.g. `processors.toNumber()`).
20
+ *
21
+ * @remarks
22
+ * Naming matches `data-cap`'s `helpers.processors`: but these
23
+ * throw with a formatted `Error` message on invalid input, where data-cap's
24
+ * silently return `undefined`. Do not assume the same failure mode when
25
+ * moving between packages.
26
+ */
27
+ export declare const processors: {
28
+ /** Decodes a base64 string into a `Buffer`. */
29
+ base64: typeof base64;
30
+ /** Parses a JSON string; passes non-string values through unchanged. */
31
+ parseJSON: typeof parseJSON;
32
+ /** Splits a string on `separator` into a trimmed string array; returns `[]` for non-string input. */
33
+ split: typeof split;
34
+ /** Splits a delimited string (or passes through an array) into items, running each through `processors` in order. */
35
+ toArray: typeof toArray;
36
+ /** Coerces a value to a `bigint`. */
37
+ toBigInt: typeof toBigInt;
38
+ /** Coerces common boolean-like strings (`true`/`1`/`yes`/`on`, and their opposites) into a real boolean. */
39
+ toBoolean: typeof toBoolean;
40
+ /** Parses a value into a `Date`. */
41
+ toDate: typeof toDate;
42
+ /** Coerces a value to a number and requires it to be an integer. */
43
+ toInteger: typeof toInteger;
44
+ /** Lowercases a string (coercing nullish values to `""` first). */
45
+ toLowerCase: typeof toLowerCase;
46
+ /** Coerces a value to a number, rejecting empty/whitespace-only strings instead of silently resolving to `0`. */
47
+ toNumber: typeof toNumber;
48
+ /** Compiles a value into a `RegExp`. */
49
+ toRegExp: typeof toRegExp;
50
+ /** Coerces a value to a string, treating nullish values as `""`. */
51
+ toString: typeof toString;
52
+ /** Parses a value into a `URL`, treating nullish values as `""` first. */
53
+ toURL: typeof toURL;
54
+ /** Uppercases a string (coercing nullish values to `""` first). */
55
+ toUpperCase: typeof toUpperCase;
56
+ /** Trims surrounding whitespace from a string (coercing nullish values to `""` first). */
57
+ trim: typeof trim;
58
+ };
59
+ /** Convenience {@link runtime.Validator} implementations for common validation patterns (e.g. `validators.range(1, 65535)`). */
60
+ export declare const validators: {
61
+ /** Passes when the date value is strictly after `date`. */
62
+ after: typeof after;
63
+ /** Passes only when every wrapped validator passes; returns the first failing message. */
64
+ all: typeof all;
65
+ /** Passes when at least one wrapped validator passes. */
66
+ any: typeof any;
67
+ /** Passes when the date value is strictly before `date`. */
68
+ before: typeof before;
69
+ /** Identity wrapper for a hand-written `Validator<T>`: no behavior change, just a fluent entry point alongside the other helpers. */
70
+ custom: typeof custom;
71
+ /** Passes for a plausibly-shaped email address (`local@domain`). */
72
+ email: typeof email;
73
+ /** Passes when the string ends with `suffix`. */
74
+ endsWith: typeof endsWith;
75
+ /** Alias for `oneOf`: passes when the value is one of the `allowed` values. */
76
+ enum: typeof oneOf;
77
+ /** Passes when the number is finite (rejects `Infinity`/`-Infinity`/`NaN`). */
78
+ finite: typeof finite;
79
+ /** Passes when the date is strictly after the current time. */
80
+ future: typeof future;
81
+ /** Passes when the string contains `text` as a substring. */
82
+ includes: typeof includes;
83
+ /** Passes when the number is an integer. */
84
+ integer: typeof integerValidator;
85
+ /** Passes when the string's length is exactly `expected`. */
86
+ length: typeof length;
87
+ /** Passes when the string matches `pattern`; `message` overrides the default failure text. */
88
+ matches: typeof matches;
89
+ /** Passes when the number is less than or equal to `maximum`. */
90
+ max: typeof max;
91
+ /** Passes when the array has at most `maximum` items. */
92
+ maxItems: typeof maxItems;
93
+ /** Passes when the string's length is at most `length`. */
94
+ maxLength: typeof maxLength;
95
+ /** Passes when the number is greater than or equal to `minimum`. */
96
+ min: typeof min;
97
+ /** Passes when the array has at least `minimum` items. */
98
+ minItems: typeof minItems;
99
+ /** Passes when the string's length is at least `length`. */
100
+ minLength: typeof minLength;
101
+ /** Passes when the number is strictly negative. */
102
+ negative: typeof negative;
103
+ /** Inverts a validator: passes when the wrapped validator fails, and vice versa. */
104
+ not: typeof not;
105
+ /** Passes when the value is one of the `allowed` values. */
106
+ oneOf: typeof oneOf;
107
+ /** Passes when the value is undefined, otherwise delegates to the provided validator. */
108
+ optional: typeof optional;
109
+ /** Passes when the date is strictly before the current time. */
110
+ past: typeof past;
111
+ /** Passes when the number is strictly positive. */
112
+ positive: typeof positive;
113
+ /** Passes when the number is within `[minimum, maximum]` inclusive. */
114
+ range: typeof range;
115
+ /** Runs the wrapped validator but replaces its failure message with `message`. */
116
+ refine: typeof refine;
117
+ /** Alias for `matches`: passes when the string matches `pattern`. */
118
+ regex: typeof matches;
119
+ /** Passes when the value is defined and, unless `allowEmptyString` is set, non-empty. */
120
+ required: typeof required;
121
+ /** Passes when the number is a safe integer (`Number.isSafeInteger`). */
122
+ safeInteger: typeof safeInteger;
123
+ /** Passes when every item in the array is unique. */
124
+ unique: typeof unique;
125
+ /** Passes when the string is a valid absolute URL. */
126
+ url: typeof urlValidator;
127
+ /** Passes when the string is a valid UUID of one of the given `versions` (default: any of 1-8). */
128
+ uuid: typeof uuid;
129
+ /** Shorthand for `uuid([version])`: passes only for that exact UUID version. */
130
+ uuidVersion: typeof uuidVersion;
131
+ };
132
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,EACP,QAAQ,EACR,SAAS,EACT,MAAM,EACN,SAAS,EACT,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,WAAW,EACX,IAAI,EACL,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,EACL,GAAG,EACH,GAAG,EACH,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,OAAO,IAAI,gBAAgB,EAC3B,MAAM,EACN,OAAO,EACP,GAAG,EACH,QAAQ,EACR,SAAS,EACT,GAAG,EACH,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,GAAG,EACH,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,MAAM,EACN,QAAQ,EACR,WAAW,EACX,MAAM,EACN,GAAG,IAAI,YAAY,EACnB,IAAI,EACJ,WAAW,EACZ,MAAM,iBAAiB,CAAA;AAExB;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;IACrB,+CAA+C;;IAE/C,wEAAwE;;IAExE,qGAAqG;;IAErG,qHAAqH;;IAErH,qCAAqC;;IAErC,4GAA4G;;IAE5G,oCAAoC;;IAEpC,oEAAoE;;IAEpE,mEAAmE;;IAEnE,iHAAiH;;IAEjH,wCAAwC;;IAExC,oEAAoE;;IAEpE,0EAA0E;;IAE1E,mEAAmE;;IAEnE,0FAA0F;;CAE3F,CAAA;AACD,gIAAgI;AAChI,eAAO,MAAM,UAAU;IACrB,2DAA2D;;IAE3D,0FAA0F;;IAE1F,yDAAyD;;IAEzD,4DAA4D;;IAE5D,qIAAqI;;IAErI,oEAAoE;;IAEpE,iDAAiD;;IAEjD,+EAA+E;;IAE/E,+EAA+E;;IAE/E,+DAA+D;;IAE/D,6DAA6D;;IAE7D,4CAA4C;;IAE5C,6DAA6D;;IAE7D,8FAA8F;;IAE9F,iEAAiE;;IAEjE,yDAAyD;;IAEzD,2DAA2D;;IAE3D,oEAAoE;;IAEpE,0DAA0D;;IAE1D,4DAA4D;;IAE5D,mDAAmD;;IAEnD,oFAAoF;;IAEpF,4DAA4D;;IAE5D,yFAAyF;;IAEzF,gEAAgE;;IAEhE,mDAAmD;;IAEnD,uEAAuE;;IAEvE,kFAAkF;;IAElF,qEAAqE;;IAErE,yFAAyF;;IAEzF,yEAAyE;;IAEzE,qDAAqD;;IAErD,sDAAsD;;IAEtD,mGAAmG;;IAEnG,gFAAgF;;CAEjF,CAAA"}
@@ -0,0 +1,32 @@
1
+ import type { Processor } from "../runtime/index.js";
2
+ /** Splits a delimited string (or passes through an array) into items, running each through `processors` in order. */
3
+ export declare function toArray<T>(separator?: string | RegExp, processors?: Processor<unknown>[]): Processor<T[]>;
4
+ /** Decodes a base64 string into a `Buffer`. */
5
+ export declare function base64(): Processor<Buffer>;
6
+ /** Coerces a value to a `bigint`. */
7
+ export declare function toBigInt(): Processor<bigint>;
8
+ /** Coerces common boolean-like strings (`true`/`1`/`yes`/`on`, and their opposites) into a real boolean. */
9
+ export declare function toBoolean(): Processor<boolean>;
10
+ /** Parses a value into a `Date`. */
11
+ export declare function toDate(): Processor<Date>;
12
+ /** Coerces a value to a number and requires it to be an integer. */
13
+ export declare function toInteger(): Processor<number>;
14
+ /** Parses a JSON string; passes non-string values through unchanged. */
15
+ export declare function parseJSON<T = unknown>(): Processor<T>;
16
+ /** Lowercases a string (coercing nullish values to `""` first). */
17
+ export declare function toLowerCase(): Processor<string>;
18
+ /** Coerces a value to a number, rejecting empty/whitespace-only strings instead of silently resolving to `0`. */
19
+ export declare function toNumber(): Processor<number>;
20
+ /** Compiles a value into a `RegExp`. */
21
+ export declare function toRegExp(): Processor<RegExp>;
22
+ /** Splits a string on `separator` into a trimmed string array; returns `[]` for non-string input. */
23
+ export declare function split(separator?: string): Processor<string[]>;
24
+ /** Coerces a value to a string, treating nullish values as `""`. */
25
+ export declare function toString(): Processor<string>;
26
+ /** Trims surrounding whitespace from a string (coercing nullish values to `""` first). */
27
+ export declare function trim(): Processor<string>;
28
+ /** Uppercases a string (coercing nullish values to `""` first). */
29
+ export declare function toUpperCase(): Processor<string>;
30
+ /** Parses a value into a `URL`, treating nullish values as `""` first. */
31
+ export declare function toURL(): Processor<URL>;
32
+ //# sourceMappingURL=processors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"processors.d.ts","sourceRoot":"","sources":["../../../src/helpers/processors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAepD,qHAAqH;AACrH,wBAAgB,OAAO,CAAC,CAAC,EACvB,SAAS,GAAE,MAAM,GAAG,MAAY,EAChC,UAAU,GAAE,SAAS,CAAC,OAAO,CAAC,EAAO,GACpC,SAAS,CAAC,CAAC,EAAE,CAAC,CAYhB;AAED,+CAA+C;AAC/C,wBAAgB,MAAM,IAAI,SAAS,CAAC,MAAM,CAAC,CAQ1C;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAQ5C;AAED,4GAA4G;AAC5G,wBAAgB,SAAS,IAAI,SAAS,CAAC,OAAO,CAAC,CAS9C;AAED,oCAAoC;AACpC,wBAAgB,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,CAUxC;AAED,oEAAoE;AACpE,wBAAgB,SAAS,IAAI,SAAS,CAAC,MAAM,CAAC,CAU7C;AAED,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAcrD;AAED,mEAAmE;AACnE,wBAAgB,WAAW,IAAI,SAAS,CAAC,MAAM,CAAC,CAE/C;AAED,iHAAiH;AACjH,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAc5C;AAED,wCAAwC;AACxC,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAQ5C;AAED,qGAAqG;AACrG,wBAAgB,KAAK,CAAC,SAAS,SAAM,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAM1D;AAED,oEAAoE;AACpE,wBAAgB,QAAQ,IAAI,SAAS,CAAC,MAAM,CAAC,CAK5C;AAED,0FAA0F;AAC1F,wBAAgB,IAAI,IAAI,SAAS,CAAC,MAAM,CAAC,CAExC;AAED,mEAAmE;AACnE,wBAAgB,WAAW,IAAI,SAAS,CAAC,MAAM,CAAC,CAE/C;AAED,0EAA0E;AAC1E,wBAAgB,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,CAStC"}
@@ -0,0 +1,68 @@
1
+ import type { Validator } from "../runtime/index.js";
2
+ /** Passes when the date value is strictly after `date`. */
3
+ export declare function after(date: Date): Validator<Date>;
4
+ /** Passes only when every wrapped validator passes; returns the first failing message. */
5
+ export declare function all<T>(...validators: Validator<T>[]): Validator<T>;
6
+ /** Passes when at least one wrapped validator passes. */
7
+ export declare function any<T>(...validators: Validator<T>[]): Validator<T>;
8
+ /** Passes when the date value is strictly before `date`. */
9
+ export declare function before(date: Date): Validator<Date>;
10
+ /** Identity wrapper for a hand-written `Validator<T>`: no behavior change, just a fluent entry point alongside the other helpers. */
11
+ export declare function custom<T>(validator: Validator<T>): Validator<T>;
12
+ /** Passes for a plausibly-shaped email address (`local@domain`). */
13
+ export declare function email(): Validator<string>;
14
+ /** Passes when the string ends with `suffix`. */
15
+ export declare function endsWith(suffix: string): Validator<string>;
16
+ /** Passes when the number is finite (rejects `Infinity`/`-Infinity`/`NaN`). */
17
+ export declare function finite(): Validator<number>;
18
+ /** Passes when the date is strictly after the current time. */
19
+ export declare function future(): Validator<Date>;
20
+ /** Passes when the string contains `text` as a substring. */
21
+ export declare function includes(text: string): Validator<string>;
22
+ /** Passes when the number is an integer. */
23
+ export declare function integer(): Validator<number>;
24
+ /** Passes when the string's length is exactly `expected`. */
25
+ export declare function length(expected: number): Validator<string>;
26
+ /** Passes when the string matches `pattern`; `message` overrides the default failure text. */
27
+ export declare function matches(pattern: RegExp, message?: string): Validator<string>;
28
+ /** Passes when the number is less than or equal to `maximum`. */
29
+ export declare function max(maximum: number): Validator<number>;
30
+ /** Passes when the array has at most `maximum` items. */
31
+ export declare function maxItems<T>(maximum: number): Validator<T[]>;
32
+ /** Passes when the string's length is at most `length`. */
33
+ export declare function maxLength(length: number): Validator<string>;
34
+ /** Passes when the number is greater than or equal to `minimum`. */
35
+ export declare function min(minimum: number): Validator<number>;
36
+ /** Passes when the array has at least `minimum` items. */
37
+ export declare function minItems<T>(minimum: number): Validator<T[]>;
38
+ /** Passes when the string's length is at least `length`. */
39
+ export declare function minLength(length: number): Validator<string>;
40
+ /** Passes when the number is strictly negative. */
41
+ export declare function negative(): Validator<number>;
42
+ /** Inverts a validator: passes when the wrapped validator fails, and vice versa. */
43
+ export declare function not<T>(validator: Validator<T>): Validator<T>;
44
+ /** Passes when the value is one of the `allowed` values. */
45
+ export declare function oneOf<T>(allowed: readonly T[]): Validator<T>;
46
+ /** Passes when the value is undefined, otherwise delegates to the provided validator. */
47
+ export declare function optional<T>(validator: Validator<T>): Validator<T | undefined>;
48
+ /** Passes when the date is strictly before the current time. */
49
+ export declare function past(): Validator<Date>;
50
+ /** Passes when the number is strictly positive. */
51
+ export declare function positive(): Validator<number>;
52
+ /** Passes when the number is within `[minimum, maximum]` inclusive. */
53
+ export declare function range(minimum: number, maximum: number): Validator<number>;
54
+ /** Runs the wrapped validator but replaces its failure message with `message`. */
55
+ export declare function refine<T>(validator: Validator<T>, message: string): Validator<T>;
56
+ /** Passes when the value is defined and, unless `allowEmptyString` is set, non-empty. */
57
+ export declare function required(allowEmptyString?: boolean): Validator<unknown>;
58
+ /** Passes when the number is a safe integer (`Number.isSafeInteger`). */
59
+ export declare function safeInteger(): Validator<number>;
60
+ /** Passes when every item in the array is unique. */
61
+ export declare function unique<T>(): Validator<T[]>;
62
+ /** Passes when the string is a valid absolute URL. */
63
+ export declare function url(): Validator<string>;
64
+ /** Passes when the string is a valid UUID of one of the given `versions` (default: any of 1-8). */
65
+ export declare function uuid(versions?: readonly number[]): Validator<string>;
66
+ /** Shorthand for `uuid([version])`: passes only for that exact UUID version. */
67
+ export declare function uuidVersion(number: number): Validator<string>;
68
+ //# sourceMappingURL=validators.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/helpers/validators.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,21 @@
1
+ /**
2
+ * The Node file system adapter for the build entry (`@maverickcer/env-cap/node`).
3
+ *
4
+ * `@maverickcer/env-cap/build` never imports `node:fs` (ADR 0040), so every generator takes the file
5
+ * system as a required `fs` option. A Node build script passes `nodeBuildFileSystem`:
6
+ *
7
+ * ```ts
8
+ * import { generateEnvArtifacts } from "@maverickcer/env-cap/build"
9
+ * import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"
10
+ *
11
+ * await generateEnvArtifacts({ fs: nodeBuildFileSystem, root, manifest: { ... } })
12
+ * ```
13
+ *
14
+ * Like `bin` and `./eslint-plugin`, this entry runs only in Node, and it is the one place the build
15
+ * path loads `node:fs/promises`. In another runtime, implement the `BuildFileSystem` type that
16
+ * `./build` exports instead.
17
+ *
18
+ * @packageDocumentation
19
+ */
20
+ export { nodeBuildFileSystem } from "../cli/filesystem.js";
21
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA"}
@@ -0,0 +1,17 @@
1
+ import type { EnvValidationError } from "./errors.js";
2
+ import type { validateEnvResult } from "./types.js";
3
+ export interface CacheState {
4
+ /** ids of every contract validated as part of this initialization, so resetEnvCache() can clean up precisely. */
5
+ contractIds: Set<symbol>;
6
+ result?: validateEnvResult;
7
+ error?: EnvValidationError;
8
+ inFlight?: Promise<validateEnvResult>;
9
+ }
10
+ export declare function getState(): CacheState;
11
+ export declare function getContractValues(id: symbol): Readonly<Record<string, unknown>> | undefined;
12
+ export declare function setContractValues(id: symbol, values: Readonly<Record<string, unknown>>): void;
13
+ export declare function getContractError(id: symbol): EnvValidationError | undefined;
14
+ export declare function setContractError(id: symbol, error: EnvValidationError): void;
15
+ /** Clears cached state: the global status plus every contract validated as part of it. */
16
+ export declare function resetCache(): void;
17
+ //# sourceMappingURL=cache.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/runtime/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD,MAAM,WAAW,UAAU;IACzB,iHAAiH;IACjH,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACxB,MAAM,CAAC,EAAE,iBAAiB,CAAA;IAC1B,KAAK,CAAC,EAAE,kBAAkB,CAAA;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;CACtC;AAqBD,wBAAgB,QAAQ,IAAI,UAAU,CAErC;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAE3F;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAE7F;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAE3E;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAE5E;AAED,0FAA0F;AAC1F,wBAAgB,UAAU,IAAI,IAAI,CAMjC"}
@@ -0,0 +1,23 @@
1
+ import type { CreateEnvOptions, EnvContract, EnvSchema } from "./types.js";
2
+ /**
3
+ * Declares a feature's environment contract. Colocate this call with the
4
+ * feature that consumes the variables (e.g. `features/payments/env.schema.ts`).
5
+ *
6
+ * @remarks
7
+ * `createEnv` is runtime-only: `processor`/`validator`/`default` are the
8
+ * whole vocabulary, because they're the only fields {@link validateEnv} actually
9
+ * reads. Documentation (description, ownership, lifecycle, category, and
10
+ * everything else that only exists to generate docs) lives in a separate
11
+ * {@link documentEnv} call (see `document.ts`), which is entirely optional and
12
+ * never required for this to work.
13
+ *
14
+ * @returns An {@link EnvContract} exposing one read-only getter per key: there is no
15
+ * global env object, only per-feature contracts like `paymentsEnv.STRIPE_KEY`. Accessing a
16
+ * key throws until {@link validateEnv} has run successfully for the runtime this contract
17
+ * was passed to.
18
+ *
19
+ * The contract redacts itself under `console.log`, `String()`, `JSON.stringify` and template
20
+ * interpolation. Spreading it or calling `Object.entries()` on it reads every value, so do not.
21
+ */
22
+ export declare function createEnv<S extends EnvSchema>(schema: S, options?: CreateEnvOptions): EnvContract<S>;
23
+ //# sourceMappingURL=create.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/runtime/create.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAqB,gBAAgB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAI7F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,SAAS,EAC3C,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,gBAAqB,GAC7B,WAAW,CAAC,CAAC,CAAC,CA4ChB"}
@@ -0,0 +1,214 @@
1
+ import type { EnvSchema } from "./types.js";
2
+ /**
3
+ * Developer-supplied evidence assertions for one variable. They differ in kind from every field on
4
+ * {@link VariableDocs}, which are declared and never verified. `dynamicAccess` is re-checked against
5
+ * reality on every run (fresh / stale / missing). It lives apart, in `VariableDocs.evidence`, not
6
+ * beside `description`, `owner` and the rest. So the shape itself shows the different status, not
7
+ * only a doc comment. See ADR 0037.
8
+ */
9
+ export interface VariableEvidenceDocs {
10
+ /**
11
+ * Citation(s) of where this variable is read dynamically, somewhere env-cap's static AST scan
12
+ * can't see (a shell script, a Docker entrypoint, a sibling service). Each entry is a
13
+ * `"<relative-path>:<line>:<column>"` citation.
14
+ *
15
+ * @remarks
16
+ * A developer's re-acknowledgment that access happens, never a claim that env-cap observed
17
+ * anything. It is tracked as its own fact and never folded into the AST-derived
18
+ * `VariableAccessStatus`. It is re-verified every run. A citation whose file is gone, or whose
19
+ * content has visibly changed since it was acknowledged, is flagged rather than trusted forever.
20
+ */
21
+ dynamicAccess?: readonly string[];
22
+ }
23
+ /**
24
+ * Per-variable documentation. Every field is optional and unconstrained on purpose. With no
25
+ * required shape, documenting a variable never fights the type checker. A field the generator
26
+ * doesn't know yet is accepted, not rejected.
27
+ */
28
+ export interface VariableDocs {
29
+ /** Human-readable explanation of what this variable is and what it controls. */
30
+ description?: string;
31
+ /** Who owns this variable (a team, a handle, whatever your org uses). Overrides the contract's own `owner` for this key. */
32
+ owner?: string;
33
+ /**
34
+ * How sensitive this variable's value is. Overrides the contract's own `sensitivity` for this
35
+ * key.
36
+ *
37
+ * @remarks
38
+ * Deliberately an open `string`, not a closed union. An org's sensitivity vocabulary is its own,
39
+ * and a level env-cap doesn't recognize is always honored, never dropped. The generator
40
+ * still reports a `NONSTANDARD_SENSITIVITY_LEVEL` finding (severity `info`, never blocking) for
41
+ * anything outside `secret`/`credential`/`pii`/`config`, so vocabulary drift stays visible
42
+ * without being enforced.
43
+ */
44
+ sensitivity?: string;
45
+ /** ISO date string (e.g. "2026-06-01"): when this variable's current value stops being valid (a key rotation deadline, a sunset date, etc.). */
46
+ expiresAt?: string;
47
+ /** How to get a new value before/when it expires (e.g. "Rotate in the Stripe dashboard, then redeploy."). */
48
+ refreshInstructions?: string;
49
+ /**
50
+ * The kind of authenticator/secret this variable holds (e.g. "api-key", "oauth-client-secret",
51
+ * "database-password", "tls-certificate"). It feeds the "authenticator type" column of the NIST
52
+ * SP 800-53 IA-5 rotation-status report. IA-5 requires an organization-defined rotation period
53
+ * "by authenticator type," so a generator groups and labels by this field.
54
+ *
55
+ * @remarks
56
+ * Deliberately an open `string`, not a closed union, like {@link sensitivity}. An org's
57
+ * authenticator taxonomy is its own, and IA-5 itself names no fixed set of types.
58
+ */
59
+ authenticatorType?: string;
60
+ /**
61
+ * How often this variable's value must be rotated, in organization-defined terms (e.g. "90
62
+ * days", "P90D", "6 months"). This is IA-5's "organization-defined time period" per authenticator
63
+ * type (the time-based half of IA-5's two-trigger rotation model). Paired with
64
+ * {@link lastRotatedAt}, it lets a generator compute whether rotation is current. Without it, a
65
+ * generator could only record that a period was declared. `lifecycle-model.ts`'s
66
+ * `computeRotationStatus()` shows how the two combine with {@link expiresAt}. The result is a
67
+ * policy-window judgement over declared metadata ("within the declared period"). It never states
68
+ * that a rotation happened or that a control is met. env-cap reads declarations; it does not
69
+ * check them against the secret store.
70
+ */
71
+ rotationPeriod?: string;
72
+ /**
73
+ * ISO date string: the last time this variable's value was actually rotated. Paired with
74
+ * {@link rotationPeriod} to compute whether rotation is within the declared period. Independent of {@link expiresAt}, which
75
+ * states when the *current* value stops being valid, not when it was last changed. A value can
76
+ * be freshly rotated and still have a near-term `expiresAt` (a short-lived token). It can also be
77
+ * long overdue for rotation while its `expiresAt` (if any) is still comfortably in the future.
78
+ */
79
+ lastRotatedAt?: string;
80
+ /**
81
+ * IA-5's event-based rotation triggers that apply to this variable (e.g. "suspected compromise",
82
+ * "personnel change", "system update"): the event-based half of IA-5's two-trigger rotation
83
+ * model. It sits beside the free-text {@link refreshInstructions} and does not replace it. This
84
+ * is a list a generator can render as its own column; `refreshInstructions` stays prose ("how to
85
+ * actually rotate it"). It is presence-only: env-cap cannot observe whether a listed event
86
+ * occurred. So declaring it never changes a computed rotation status by itself (see
87
+ * `lifecycle-model.ts`). It only makes the event-based trigger visible in generated output.
88
+ */
89
+ rotationTriggerEvents?: readonly string[];
90
+ /**
91
+ * Explicit, actionable instructions for obtaining this variable's value the *first* time.
92
+ * `refreshInstructions` is "how to rotate it once you already have one"; this is "how to get
93
+ * one at all" (e.g. "Create a restricted API key in the Stripe dashboard under Developers ->
94
+ * API keys, scoped to read/write Charges."). It is a named field so it renders as its own
95
+ * labeled line in generated docs. A `metadata.setup`-style convention would get no dedicated
96
+ * rendering or type checking.
97
+ */
98
+ setupInstructions?: string;
99
+ /** Documentation-level assertion that this variable must be set. Independent of how (or whether) a validator actually enforces it. */
100
+ required?: boolean;
101
+ /** Marks this variable as being phased out. Independent of `expiresAt` (a rotation/sunset date) and of the contract-level `active` switch (on/off, not a phase-out signal). */
102
+ deprecated?: boolean;
103
+ /** Why this variable is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
104
+ deprecatedReason?: string;
105
+ /** ISO date string: by when a deprecated variable must be removed. Only meaningful alongside `deprecated: true`. */
106
+ removeBy?: string;
107
+ /** The previous environment variable name this one replaces, if this declaration is the result of a rename. Lets the Change Model correlate a remove+add pair into a single rename entry instead of two unrelated changes. */
108
+ renamedFrom?: string;
109
+ /** Why this variable's value is collected/used: a framework-agnostic fact (pairs with `legalBasis`; a specific citation like a GDPR article belongs in `metadata` instead). Overrides the contract's own `purpose` for this key. */
110
+ purpose?: string;
111
+ /** The legal basis this variable's collection/use relies on: framework-agnostic (e.g. "user consent," "contractual necessity"), never a specific statute name. Overrides the contract's own `legalBasis` for this key. */
112
+ legalBasis?: string;
113
+ /** Descriptive retention policy (e.g. "delete after 90 days"). A policy statement, not a computed value: unlike `expiresAt`, nothing parses or evaluates this. Overrides the contract's own `retention` for this key. */
114
+ retention?: string;
115
+ /** Where this variable's value is/must be stored (a region, or a permitted set of regions). Overrides the contract's own `dataResidency` for this key. */
116
+ dataResidency?: string | string[];
117
+ /** Documentation-level assertion that this variable's handling must be auditable. Overrides the contract's own `auditRequired` for this key. */
118
+ auditRequired?: boolean;
119
+ /**
120
+ * Developer-supplied evidence assertions for this variable: verified over
121
+ * time, unlike every other field above, which is declared and never
122
+ * verified. Kept structurally separate for exactly that reason; see
123
+ * {@link VariableEvidenceDocs}.
124
+ */
125
+ evidence?: VariableEvidenceDocs;
126
+ /**
127
+ * Structured, unsupported-key documentation: any primitive or object value, for anything that
128
+ * doesn't warrant its own named field. A key that has a named field above belongs in that field,
129
+ * not here.
130
+ */
131
+ metadata?: Record<string, unknown>;
132
+ }
133
+ /**
134
+ * Contract-level documentation. Only the generator reads these fields; validation never does.
135
+ *
136
+ * @remarks
137
+ * Generic over `S`, the exact schema type {@link documentEnv} infers from its `schema` argument.
138
+ * That makes `variables` below a closed, checked map, not an open `Record<string, VariableDocs>`
139
+ * any string would satisfy. A typo'd or renamed key is a compile error, not a silent no-op. `S`
140
+ * defaults to the widest possible schema. So this type is still nameable on its own (e.g. in a
141
+ * helper function's parameter type) without narrowing to one specific contract.
142
+ */
143
+ export interface ContractDocs<S extends EnvSchema = EnvSchema> {
144
+ /** Overrides the auto-generated label used in generated docs. Purely cosmetic. Wins over `createEnv()`'s own `name` option, which in turn wins over the exported binding name. */
145
+ name?: string;
146
+ /** Groups this contract under a heading in the generated docs' feature catalog. */
147
+ category?: string;
148
+ /** The generator throws if two *active* contracts declare the same `exclusiveGroup`: use it to mark interchangeable features (e.g. two database backends) as mutually exclusive. */
149
+ exclusiveGroup?: string;
150
+ /** When `false`, this contract is excluded from the generated manifest, docs' required section, and exclusiveGroup checks: it still appears, marked disabled, in the feature catalog. Defaults to `true`. */
151
+ active?: boolean;
152
+ /** Default owner for every variable in this contract that doesn't set its own `owner`. */
153
+ owner?: string;
154
+ /** Default sensitivity for every variable in this contract that doesn't set its own `sensitivity`: see {@link VariableDocs.sensitivity} for why this is an open `string`. */
155
+ sensitivity?: string;
156
+ /** Whole-contract/feature sunset date, ISO date string. */
157
+ expiresAt?: string;
158
+ /** Marks this whole contract/feature as being phased out. Independent of `active` (on/off, not a phase-out signal). */
159
+ deprecated?: boolean;
160
+ /** Why this contract is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
161
+ deprecatedReason?: string;
162
+ /** Default reason this contract's variables' values are collected/used: see {@link VariableDocs.purpose}. */
163
+ purpose?: string;
164
+ /** Default legal basis for this contract's variables: see {@link VariableDocs.legalBasis}. */
165
+ legalBasis?: string;
166
+ /** Default retention policy for this contract's variables: see {@link VariableDocs.retention}. */
167
+ retention?: string;
168
+ /** Default data residency for this contract's variables: see {@link VariableDocs.dataResidency}. */
169
+ dataResidency?: string | string[];
170
+ /** Default audit-required assertion for this contract's variables: see {@link VariableDocs.auditRequired}. */
171
+ auditRequired?: boolean;
172
+ /** Arbitrary contract-level documentation (e.g. `runbook`), rendered alongside this feature: see {@link VariableDocs.metadata}. */
173
+ metadata?: Record<string, unknown>;
174
+ /**
175
+ * Per-variable documentation, keyed by variable name. Keys are checked against `S`'s own keys
176
+ * at compile time. Documenting a variable that was renamed or removed from `schema` (or a plain
177
+ * typo) is therefore a type error here. The generator never has to report it as "stale" after
178
+ * the fact. A schema key absent from `variables` entirely is
179
+ * still valid (not every variable needs documentation). The generator reports it as
180
+ * undocumented.
181
+ */
182
+ variables?: {
183
+ readonly [K in keyof S]?: VariableDocs;
184
+ };
185
+ }
186
+ /**
187
+ * Documents a schema for the generator: explains values, assigns ownership,
188
+ * and describes lifecycle, feeding the generated docs artifact and
189
+ * `.env.example`. Pass it the *same* schema object given to {@link createEnv}.
190
+ * The generator then statically links the two and verifies every variable is
191
+ * documented. TypeScript also checks `docs.variables`' keys against
192
+ * `schema`'s own keys, so the same object identity serves both the
193
+ * generator's static link and the type checker.
194
+ *
195
+ * @remarks
196
+ * A no-op at runtime by design: nothing passed here is retained anywhere,
197
+ * and this can never throw, no matter how malformed `schema`/`docs` are.
198
+ * Calling it is entirely optional: {@link createEnv} works identically whether or
199
+ * not a matching `documentEnv` call exists. The real "is everything
200
+ * documented?" check runs entirely inside {@link build.generateEnvManifest}'s
201
+ * static analysis. So does every artifact this data drives: the docs
202
+ * artifact's ownership matrix, dependency graph, lifecycle report and
203
+ * security review, and `.env.example`'s comments. At runtime this function
204
+ * only exists as a safe marker the AST parser can find, and gives you
205
+ * type-checked argument shapes while writing it.
206
+ *
207
+ * `S` is inferred from `schema`, never written out by hand. Pass the
208
+ * schema object literal (or a `const`-inferred reference to it) directly for
209
+ * the strongest inference. An explicitly-widened `schema: EnvSchema`
210
+ * annotation loses the per-key literal type, so `docs.variables` then
211
+ * accepts any string key.
212
+ */
213
+ export declare function documentEnv<S extends EnvSchema>(schema: S, docs: ContractDocs<S>): void;
214
+ //# sourceMappingURL=document.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../../src/runtime/document.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Every error type here is constructed only from: the variable name, the
3
+ * declaring contract's name, the failure kind, and a message string that the
4
+ * *developer's own* processor/validator produced. Raw or processed environment
5
+ * values are never read into an error: see the Security section in the README.
6
+ *
7
+ * Documentation (description, owner, etc.) never appears here, even when a
8
+ * {@link documentEnv} call exists for this variable: `documentEnv` is
9
+ * build-time-only and its data is never retained anywhere {@link validateEnv}
10
+ * could read it back out. This is a deliberate consequence of keeping the
11
+ * runtime minimal, not an oversight.
12
+ */
13
+ /** One variable's processing or validation failure, as recorded by {@link validateEnv}. */
14
+ export interface VariableFailure {
15
+ /** The schema key that failed. */
16
+ readonly variable: string;
17
+ /** The declaring contract's `name` (see {@link CreateEnvOptions}). */
18
+ readonly contractName: string;
19
+ /** `import.meta.url` (or similar) passed to `createEnv`'s `source` option, if any. Falls back to `contractName` when absent. */
20
+ readonly source: string | undefined;
21
+ /** Which stage produced the failure. */
22
+ readonly kind: "processor" | "validator";
23
+ /** The error message from the developer's own processor/validator, or the thrown error's message. */
24
+ readonly message: string;
25
+ }
26
+ /**
27
+ * Thrown by {@link validateEnv} when one or more variables fail processing or
28
+ * validation. Aggregates every failure across every contract in the batch:
29
+ * the caller sees the whole picture in one error, not one-at-a-time.
30
+ *
31
+ * @remarks
32
+ * `code` is a stable, Stable-tier discriminant for programmatic handling:
33
+ * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
34
+ */
35
+ export declare class EnvValidationError extends Error {
36
+ /** Stable discriminant for programmatic handling; always `"ENV_VALIDATION_FAILED"`. */
37
+ readonly code = "ENV_VALIDATION_FAILED";
38
+ /** Every variable failure across every contract in the batch. */
39
+ readonly failures: readonly VariableFailure[];
40
+ constructor(failures: readonly VariableFailure[]);
41
+ }
42
+ /**
43
+ * Thrown when a contract's value is accessed via property access before
44
+ * {@link validateEnv} has completed successfully for it.
45
+ *
46
+ * @remarks
47
+ * `code` is a stable, Stable-tier discriminant for programmatic handling:
48
+ * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
49
+ */
50
+ export declare class EnvNotReadyError extends Error {
51
+ /** Stable discriminant for programmatic handling; always `"ENV_NOT_READY"`. */
52
+ readonly code = "ENV_NOT_READY";
53
+ constructor(contractName: string, key: string);
54
+ }
55
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,gIAAgI;IAChI,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAAA;IACxC,qGAAqG;IACrG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAwBD;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,uFAAuF;IACvF,QAAQ,CAAC,IAAI,2BAA0B;IACvC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;gBAEjC,QAAQ,EAAE,SAAS,eAAe,EAAE;CAMjD;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,mBAAkB;gBAEnB,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAS9C"}