@maverickcer/env-cap 0.5.3 → 0.7.0

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 (359) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +438 -0
  4. package/CODE_OF_CONDUCT.md +124 -0
  5. package/CODE_REVIEW.md +200 -0
  6. package/CONTRIBUTING.md +131 -0
  7. package/GUIDE.md +1214 -0
  8. package/PROMPT.md +89 -0
  9. package/README.md +97 -199
  10. package/RELEASING.md +160 -0
  11. package/SECURITY.md +270 -0
  12. package/SUPPORT.md +76 -0
  13. package/VERSIONING.md +118 -0
  14. package/benchmarks/READING-BENCHMARKS.md +197 -0
  15. package/benchmarks/README.md +126 -0
  16. package/benchmarks/WRITING-BENCHMARKS.md +252 -0
  17. package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
  18. package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
  19. package/dist/.dts/_ipc/build-fs.d.ts +53 -0
  20. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
  21. package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
  22. package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
  23. package/dist/.dts/_ipc/display-path.d.ts +27 -0
  24. package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
  25. package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
  26. package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
  27. package/dist/.dts/_ipc/glob.d.ts +22 -0
  28. package/dist/.dts/_ipc/glob.d.ts.map +1 -0
  29. package/dist/.dts/_ipc/no-node-fs.d.ts +34 -0
  30. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
  31. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  32. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  33. package/dist/.dts/_ipc/typescript.d.ts +20 -0
  34. package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
  35. package/dist/.dts/build/assemble-project.d.ts +1 -1
  36. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  37. package/dist/.dts/build/change-model.d.ts.map +1 -1
  38. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  39. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  40. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  41. package/dist/.dts/build/compiler-api.d.ts +12 -0
  42. package/dist/.dts/build/compiler-api.d.ts.map +1 -0
  43. package/dist/.dts/build/dependency-graph.d.ts +3 -1
  44. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  45. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  46. package/dist/.dts/build/discover.d.ts.map +1 -1
  47. package/dist/.dts/build/display-path.d.ts +3 -21
  48. package/dist/.dts/build/display-path.d.ts.map +1 -1
  49. package/dist/.dts/build/docs.d.ts +1 -1
  50. package/dist/.dts/build/docs.d.ts.map +1 -1
  51. package/dist/.dts/build/env-example.d.ts.map +1 -1
  52. package/dist/.dts/build/evidence-cache.d.ts +1 -1
  53. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  54. package/dist/.dts/build/evidence-model.d.ts +2 -2
  55. package/dist/.dts/build/evidence-snapshot.d.ts +25 -0
  56. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  57. package/dist/.dts/build/finding-model.d.ts +1 -1
  58. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  59. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  60. package/dist/.dts/build/generate-env-artifacts.d.ts +23 -8
  61. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  62. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  63. package/dist/.dts/build/generate-manifest.d.ts +1 -1
  64. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  65. package/dist/.dts/build/generate-usage.d.ts +3 -3
  66. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  67. package/dist/.dts/build/generated-banner.d.ts +29 -38
  68. package/dist/.dts/build/generated-banner.d.ts.map +1 -1
  69. package/dist/.dts/build/glob.d.ts +3 -15
  70. package/dist/.dts/build/glob.d.ts.map +1 -1
  71. package/dist/.dts/build/index.d.ts +2 -2
  72. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  73. package/dist/.dts/build/link.d.ts.map +1 -1
  74. package/dist/.dts/build/literal-eval.d.ts +4 -3
  75. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  76. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  77. package/dist/.dts/build/manifest.d.ts.map +1 -1
  78. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  79. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  80. package/dist/.dts/build/parse.d.ts +12 -12
  81. package/dist/.dts/build/parse.d.ts.map +1 -1
  82. package/dist/.dts/build/reference-projections.d.ts +17 -3
  83. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  84. package/dist/.dts/build/resolution/resolve-import.d.ts +5 -0
  85. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  86. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +1 -1
  87. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  88. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -94
  89. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  90. package/dist/.dts/build/sarif.d.ts.map +1 -1
  91. package/dist/.dts/build/scan-dependencies.d.ts +23 -0
  92. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  93. package/dist/.dts/build/types.d.ts +4 -53
  94. package/dist/.dts/build/types.d.ts.map +1 -1
  95. package/dist/.dts/build/typescript.d.ts +6 -0
  96. package/dist/.dts/build/typescript.d.ts.map +1 -0
  97. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  98. package/dist/.dts/cli/filesystem.d.ts +4 -0
  99. package/dist/.dts/cli/filesystem.d.ts.map +1 -1
  100. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  101. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  102. package/dist/.dts/eslint-plugin/index.d.ts +3 -3
  103. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  104. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  105. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  106. package/dist/.dts/evidence/index.d.ts +2 -2
  107. package/dist/.dts/helpers/index.d.ts +2 -2
  108. package/dist/.dts/helpers/processors.d.ts.map +1 -1
  109. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  110. package/dist/.dts/runtime/cache.d.ts +0 -3
  111. package/dist/.dts/runtime/cache.d.ts.map +1 -1
  112. package/dist/.dts/runtime/create.d.ts.map +1 -1
  113. package/dist/.dts/runtime/document.d.ts.map +1 -1
  114. package/dist/.dts/runtime/index.d.ts +2 -2
  115. package/dist/.dts/runtime/registry.d.ts.map +1 -1
  116. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  117. package/dist/{build-U326PI5A.js → build-WKDIAWF7.js} +685 -645
  118. package/dist/build-WKDIAWF7.js.map +1 -0
  119. package/dist/build.cjs +698 -651
  120. package/dist/build.cjs.map +1 -1
  121. package/dist/build.js +695 -649
  122. package/dist/build.js.map +1 -1
  123. package/dist/{chunk-BSTLSR2R.js → chunk-KEGYUHBU.js} +2 -2
  124. package/dist/chunk-KEGYUHBU.js.map +1 -0
  125. package/dist/cli/index.js +64 -63
  126. package/dist/cli/index.js.map +1 -1
  127. package/dist/eslint-plugin/index.cjs +95 -626
  128. package/dist/eslint-plugin/index.cjs.map +1 -1
  129. package/dist/eslint-plugin/index.js +94 -625
  130. package/dist/eslint-plugin/index.js.map +1 -1
  131. package/dist/evidence.cjs.map +1 -1
  132. package/dist/evidence.js.map +1 -1
  133. package/dist/helpers.cjs +4 -9
  134. package/dist/helpers.cjs.map +1 -1
  135. package/dist/helpers.js +4 -9
  136. package/dist/helpers.js.map +1 -1
  137. package/dist/index.cjs +11 -25
  138. package/dist/index.cjs.map +1 -1
  139. package/dist/index.js +11 -25
  140. package/dist/index.js.map +1 -1
  141. package/dist/node.cjs +10 -8
  142. package/dist/node.cjs.map +1 -1
  143. package/dist/node.js +10 -8
  144. package/dist/node.js.map +1 -1
  145. package/examples/README.md +95 -0
  146. package/node_modules/@typescript/old/LICENSE.txt +55 -0
  147. package/node_modules/@typescript/old/README.md +50 -0
  148. package/node_modules/@typescript/old/SECURITY.md +39 -0
  149. package/node_modules/@typescript/old/ThirdPartyNoticeText.txt +193 -0
  150. package/node_modules/@typescript/old/bin/tsc +2 -0
  151. package/node_modules/@typescript/old/bin/tsserver +2 -0
  152. package/node_modules/@typescript/old/lib/_tsc.js +134465 -0
  153. package/node_modules/@typescript/old/lib/_tsserver.js +659 -0
  154. package/node_modules/@typescript/old/lib/_typingsInstaller.js +222 -0
  155. package/node_modules/@typescript/old/lib/cs/diagnosticMessages.generated.json +2129 -0
  156. package/node_modules/@typescript/old/lib/de/diagnosticMessages.generated.json +2125 -0
  157. package/node_modules/@typescript/old/lib/es/diagnosticMessages.generated.json +2129 -0
  158. package/node_modules/@typescript/old/lib/fr/diagnosticMessages.generated.json +2129 -0
  159. package/node_modules/@typescript/old/lib/it/diagnosticMessages.generated.json +2125 -0
  160. package/node_modules/@typescript/old/lib/ja/diagnosticMessages.generated.json +2129 -0
  161. package/node_modules/@typescript/old/lib/ko/diagnosticMessages.generated.json +2129 -0
  162. package/node_modules/@typescript/old/lib/lib.d.ts +20 -0
  163. package/node_modules/@typescript/old/lib/lib.decorators.d.ts +382 -0
  164. package/node_modules/@typescript/old/lib/lib.decorators.legacy.d.ts +20 -0
  165. package/node_modules/@typescript/old/lib/lib.dom.asynciterable.d.ts +18 -0
  166. package/node_modules/@typescript/old/lib/lib.dom.d.ts +45125 -0
  167. package/node_modules/@typescript/old/lib/lib.dom.iterable.d.ts +18 -0
  168. package/node_modules/@typescript/old/lib/lib.es2015.collection.d.ts +150 -0
  169. package/node_modules/@typescript/old/lib/lib.es2015.core.d.ts +595 -0
  170. package/node_modules/@typescript/old/lib/lib.es2015.d.ts +26 -0
  171. package/node_modules/@typescript/old/lib/lib.es2015.generator.d.ts +75 -0
  172. package/node_modules/@typescript/old/lib/lib.es2015.iterable.d.ts +603 -0
  173. package/node_modules/@typescript/old/lib/lib.es2015.promise.d.ts +79 -0
  174. package/node_modules/@typescript/old/lib/lib.es2015.proxy.d.ts +126 -0
  175. package/node_modules/@typescript/old/lib/lib.es2015.reflect.d.ts +142 -0
  176. package/node_modules/@typescript/old/lib/lib.es2015.symbol.d.ts +44 -0
  177. package/node_modules/@typescript/old/lib/lib.es2015.symbol.wellknown.d.ts +324 -0
  178. package/node_modules/@typescript/old/lib/lib.es2016.array.include.d.ts +114 -0
  179. package/node_modules/@typescript/old/lib/lib.es2016.d.ts +19 -0
  180. package/node_modules/@typescript/old/lib/lib.es2016.full.d.ts +21 -0
  181. package/node_modules/@typescript/old/lib/lib.es2016.intl.d.ts +29 -0
  182. package/node_modules/@typescript/old/lib/lib.es2017.arraybuffer.d.ts +19 -0
  183. package/node_modules/@typescript/old/lib/lib.es2017.d.ts +24 -0
  184. package/node_modules/@typescript/old/lib/lib.es2017.date.d.ts +29 -0
  185. package/node_modules/@typescript/old/lib/lib.es2017.full.d.ts +21 -0
  186. package/node_modules/@typescript/old/lib/lib.es2017.intl.d.ts +42 -0
  187. package/node_modules/@typescript/old/lib/lib.es2017.object.d.ts +47 -0
  188. package/node_modules/@typescript/old/lib/lib.es2017.sharedmemory.d.ts +133 -0
  189. package/node_modules/@typescript/old/lib/lib.es2017.string.d.ts +43 -0
  190. package/node_modules/@typescript/old/lib/lib.es2017.typedarrays.d.ts +51 -0
  191. package/node_modules/@typescript/old/lib/lib.es2018.asyncgenerator.d.ts +75 -0
  192. package/node_modules/@typescript/old/lib/lib.es2018.asynciterable.d.ts +51 -0
  193. package/node_modules/@typescript/old/lib/lib.es2018.d.ts +22 -0
  194. package/node_modules/@typescript/old/lib/lib.es2018.full.d.ts +22 -0
  195. package/node_modules/@typescript/old/lib/lib.es2018.intl.d.ts +81 -0
  196. package/node_modules/@typescript/old/lib/lib.es2018.promise.d.ts +28 -0
  197. package/node_modules/@typescript/old/lib/lib.es2018.regexp.d.ts +35 -0
  198. package/node_modules/@typescript/old/lib/lib.es2019.array.d.ts +77 -0
  199. package/node_modules/@typescript/old/lib/lib.es2019.d.ts +22 -0
  200. package/node_modules/@typescript/old/lib/lib.es2019.full.d.ts +22 -0
  201. package/node_modules/@typescript/old/lib/lib.es2019.intl.d.ts +21 -0
  202. package/node_modules/@typescript/old/lib/lib.es2019.object.d.ts +31 -0
  203. package/node_modules/@typescript/old/lib/lib.es2019.string.d.ts +35 -0
  204. package/node_modules/@typescript/old/lib/lib.es2019.symbol.d.ts +22 -0
  205. package/node_modules/@typescript/old/lib/lib.es2020.bigint.d.ts +763 -0
  206. package/node_modules/@typescript/old/lib/lib.es2020.d.ts +25 -0
  207. package/node_modules/@typescript/old/lib/lib.es2020.date.d.ts +40 -0
  208. package/node_modules/@typescript/old/lib/lib.es2020.full.d.ts +22 -0
  209. package/node_modules/@typescript/old/lib/lib.es2020.intl.d.ts +472 -0
  210. package/node_modules/@typescript/old/lib/lib.es2020.number.d.ts +26 -0
  211. package/node_modules/@typescript/old/lib/lib.es2020.promise.d.ts +45 -0
  212. package/node_modules/@typescript/old/lib/lib.es2020.sharedmemory.d.ts +97 -0
  213. package/node_modules/@typescript/old/lib/lib.es2020.string.d.ts +42 -0
  214. package/node_modules/@typescript/old/lib/lib.es2020.symbol.wellknown.d.ts +39 -0
  215. package/node_modules/@typescript/old/lib/lib.es2021.d.ts +21 -0
  216. package/node_modules/@typescript/old/lib/lib.es2021.full.d.ts +22 -0
  217. package/node_modules/@typescript/old/lib/lib.es2021.intl.d.ts +164 -0
  218. package/node_modules/@typescript/old/lib/lib.es2021.promise.d.ts +46 -0
  219. package/node_modules/@typescript/old/lib/lib.es2021.string.d.ts +31 -0
  220. package/node_modules/@typescript/old/lib/lib.es2021.weakref.d.ts +76 -0
  221. package/node_modules/@typescript/old/lib/lib.es2022.array.d.ts +119 -0
  222. package/node_modules/@typescript/old/lib/lib.es2022.d.ts +23 -0
  223. package/node_modules/@typescript/old/lib/lib.es2022.error.d.ts +73 -0
  224. package/node_modules/@typescript/old/lib/lib.es2022.full.d.ts +22 -0
  225. package/node_modules/@typescript/old/lib/lib.es2022.intl.d.ts +143 -0
  226. package/node_modules/@typescript/old/lib/lib.es2022.object.d.ts +24 -0
  227. package/node_modules/@typescript/old/lib/lib.es2022.regexp.d.ts +37 -0
  228. package/node_modules/@typescript/old/lib/lib.es2022.string.d.ts +23 -0
  229. package/node_modules/@typescript/old/lib/lib.es2023.array.d.ts +922 -0
  230. package/node_modules/@typescript/old/lib/lib.es2023.collection.d.ts +19 -0
  231. package/node_modules/@typescript/old/lib/lib.es2023.d.ts +20 -0
  232. package/node_modules/@typescript/old/lib/lib.es2023.full.d.ts +22 -0
  233. package/node_modules/@typescript/old/lib/lib.es2023.intl.d.ts +62 -0
  234. package/node_modules/@typescript/old/lib/lib.es2024.arraybuffer.d.ts +63 -0
  235. package/node_modules/@typescript/old/lib/lib.es2024.collection.d.ts +27 -0
  236. package/node_modules/@typescript/old/lib/lib.es2024.d.ts +24 -0
  237. package/node_modules/@typescript/old/lib/lib.es2024.full.d.ts +22 -0
  238. package/node_modules/@typescript/old/lib/lib.es2024.object.d.ts +27 -0
  239. package/node_modules/@typescript/old/lib/lib.es2024.promise.d.ts +33 -0
  240. package/node_modules/@typescript/old/lib/lib.es2024.regexp.d.ts +23 -0
  241. package/node_modules/@typescript/old/lib/lib.es2024.sharedmemory.d.ts +66 -0
  242. package/node_modules/@typescript/old/lib/lib.es2024.string.d.ts +27 -0
  243. package/node_modules/@typescript/old/lib/lib.es2025.collection.d.ts +94 -0
  244. package/node_modules/@typescript/old/lib/lib.es2025.d.ts +23 -0
  245. package/node_modules/@typescript/old/lib/lib.es2025.float16.d.ts +443 -0
  246. package/node_modules/@typescript/old/lib/lib.es2025.full.d.ts +22 -0
  247. package/node_modules/@typescript/old/lib/lib.es2025.intl.d.ts +200 -0
  248. package/node_modules/@typescript/old/lib/lib.es2025.iterator.d.ts +146 -0
  249. package/node_modules/@typescript/old/lib/lib.es2025.promise.d.ts +32 -0
  250. package/node_modules/@typescript/old/lib/lib.es2025.regexp.d.ts +30 -0
  251. package/node_modules/@typescript/old/lib/lib.es5.d.ts +4599 -0
  252. package/node_modules/@typescript/old/lib/lib.es6.d.ts +21 -0
  253. package/node_modules/@typescript/old/lib/lib.esnext.array.d.ts +33 -0
  254. package/node_modules/@typescript/old/lib/lib.esnext.collection.d.ts +47 -0
  255. package/node_modules/@typescript/old/lib/lib.esnext.d.ts +27 -0
  256. package/node_modules/@typescript/old/lib/lib.esnext.date.d.ts +21 -0
  257. package/node_modules/@typescript/old/lib/lib.esnext.decorators.d.ts +26 -0
  258. package/node_modules/@typescript/old/lib/lib.esnext.disposable.d.ts +191 -0
  259. package/node_modules/@typescript/old/lib/lib.esnext.error.d.ts +22 -0
  260. package/node_modules/@typescript/old/lib/lib.esnext.full.d.ts +22 -0
  261. package/node_modules/@typescript/old/lib/lib.esnext.intl.d.ts +107 -0
  262. package/node_modules/@typescript/old/lib/lib.esnext.sharedmemory.d.ts +23 -0
  263. package/node_modules/@typescript/old/lib/lib.esnext.temporal.d.ts +485 -0
  264. package/node_modules/@typescript/old/lib/lib.esnext.typedarrays.d.ts +90 -0
  265. package/node_modules/@typescript/old/lib/lib.scripthost.d.ts +320 -0
  266. package/node_modules/@typescript/old/lib/lib.webworker.asynciterable.d.ts +18 -0
  267. package/node_modules/@typescript/old/lib/lib.webworker.d.ts +15606 -0
  268. package/node_modules/@typescript/old/lib/lib.webworker.importscripts.d.ts +21 -0
  269. package/node_modules/@typescript/old/lib/lib.webworker.iterable.d.ts +18 -0
  270. package/node_modules/@typescript/old/lib/pl/diagnosticMessages.generated.json +2129 -0
  271. package/node_modules/@typescript/old/lib/pt-br/diagnosticMessages.generated.json +2129 -0
  272. package/node_modules/@typescript/old/lib/ru/diagnosticMessages.generated.json +2125 -0
  273. package/node_modules/@typescript/old/lib/tr/diagnosticMessages.generated.json +2129 -0
  274. package/node_modules/@typescript/old/lib/tsc.js +8 -0
  275. package/node_modules/@typescript/old/lib/tsserver.js +8 -0
  276. package/node_modules/@typescript/old/lib/tsserverlibrary.d.ts +17 -0
  277. package/node_modules/@typescript/old/lib/tsserverlibrary.js +21 -0
  278. package/node_modules/@typescript/old/lib/typesMap.json +497 -0
  279. package/node_modules/@typescript/old/lib/typescript.d.ts +11448 -0
  280. package/node_modules/@typescript/old/lib/typescript.js +201039 -0
  281. package/node_modules/@typescript/old/lib/typingsInstaller.js +8 -0
  282. package/node_modules/@typescript/old/lib/watchGuard.js +53 -0
  283. package/node_modules/@typescript/old/lib/zh-cn/diagnosticMessages.generated.json +2129 -0
  284. package/node_modules/@typescript/old/lib/zh-tw/diagnosticMessages.generated.json +2125 -0
  285. package/node_modules/@typescript/old/package.json +118 -0
  286. package/node_modules/@typescript/typescript6/LICENSE.txt +55 -0
  287. package/node_modules/@typescript/typescript6/README.md +9 -0
  288. package/node_modules/@typescript/typescript6/bin/tsc6 +2 -0
  289. package/node_modules/@typescript/typescript6/lib/tsc.js +1 -0
  290. package/node_modules/@typescript/typescript6/lib/tsserverlibrary.d.ts +2 -0
  291. package/node_modules/@typescript/typescript6/lib/tsserverlibrary.js +1 -0
  292. package/node_modules/@typescript/typescript6/lib/typescript.d.ts +2 -0
  293. package/node_modules/@typescript/typescript6/lib/typescript.js +1 -0
  294. package/node_modules/@typescript/typescript6/package.json +39 -0
  295. package/package.json +74 -22
  296. package/schemas/env-cap-report.schema.json +1 -1
  297. package/skills/env-cap/SKILL.md +91 -0
  298. package/skills/env-cap/references/api.md +220 -0
  299. package/specs/architecture.md +634 -0
  300. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  301. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  302. package/specs/decisions/0003-no-global-env-object.md +172 -0
  303. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  304. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  305. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  306. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  307. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  308. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  309. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  310. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  311. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  312. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  313. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  314. package/specs/decisions/0015-security-backport-window.md +60 -0
  315. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  316. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  317. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  318. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  319. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  320. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  321. package/specs/decisions/0022-validation-contexts.md +267 -0
  322. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  323. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  324. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  325. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  326. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  327. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  328. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  329. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  330. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  331. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  332. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  333. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  334. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  335. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  336. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  337. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  338. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  339. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  340. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  341. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  342. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  343. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  344. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  345. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  346. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  347. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  348. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  349. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  350. package/specs/generated-artifacts.md +104 -0
  351. package/specs/migrations/README.md +30 -0
  352. package/specs/migrations/from-centralized-schema.md +503 -0
  353. package/specs/migrations/from-dotenv.md +352 -0
  354. package/specs/migrations/from-envalid.md +482 -0
  355. package/specs/migrations/from-process-env.md +398 -0
  356. package/specs/migrations/from-t3-env.md +416 -0
  357. package/specs/migrations/from-zod.md +303 -0
  358. package/dist/build-U326PI5A.js.map +0 -1
  359. package/dist/chunk-BSTLSR2R.js.map +0 -1
@@ -0,0 +1,634 @@
1
+ # Architecture
2
+
3
+ Canonical current-state description of how `env-cap` is built and what guarantees its architecture
4
+ provides. [`decisions/`](decisions/) holds the reasoning trail (the ADRs); this document is the
5
+ destination those decisions arrived at, not the argument for them. For the product overview and
6
+ integration guidance, see [README.md](../README.md) and [GUIDE.md](../GUIDE.md).
7
+
8
+ - [Purpose](#purpose)
9
+ - [Core invariants](#core-invariants)
10
+ - [The entry points](#the-entry-points)
11
+ - [`runtime/` — define, validate, cache, and expose environment values](#runtime--define-validate-cache-and-expose-environment-values)
12
+ - [`build/` — discover, analyze, link, and generate artifacts](#build--discover-analyze-link-and-generate-artifacts)
13
+ - [`helpers/` — optional processors and validators](#helpers--optional-processors-and-validators)
14
+ - [Documentation is parallel to runtime, not part of runtime state](#documentation-is-parallel-to-runtime-not-part-of-runtime-state)
15
+ - [Data flow](#data-flow)
16
+ - [Module layout](#module-layout)
17
+ - [Architectural decisions](#architectural-decisions)
18
+
19
+ ## Purpose
20
+
21
+ `env-cap` treats an application's environment configuration as a set of capability-owned contracts,
22
+ not as loose strings read off `process.env`. It does not perform secret storage, rotation, or
23
+ retrieval itself: a capability declares the environment variables it depends on (`createEnv()`) and,
24
+ optionally, the documentation metadata that describes them (`documentEnv()`); `env-cap` validates
25
+ those declarations against real values at startup, and separately, at build time, discovers every
26
+ declared contract across a project to produce manifests, documentation, ownership reports, and a
27
+ canonical Evidence Model.
28
+
29
+ The architecture keeps two concerns from collapsing into one:
30
+
31
+ ```text
32
+ runtime -> validated, typed access to configuration a capability already declared owning
33
+ build-time -> project-wide discovery, documentation, and ownership visibility
34
+ ```
35
+
36
+ The runtime never discovers anything; it only validates what a generated manifest already told it to
37
+ expect. Build-time tooling never runs at startup; it only ever runs as an explicit CI/npm-script step.
38
+ Neither one substitutes for the other, and a consumer can use either independently — validation with no
39
+ generated artifacts at all (a hand-written manifest works), or discovery/documentation with no runtime
40
+ validation (a project that only wants the ownership report).
41
+
42
+ ## Core invariants
43
+
44
+ These are the guarantees the rest of the design exists to uphold. Each links to the section that
45
+ describes its mechanics.
46
+
47
+ ### Runtime and build-time are strictly separate
48
+
49
+ The runtime (`.`, `./helpers`) has zero npm dependencies, never touches the filesystem, never
50
+ discovers files, and never imports Node-specific APIs. `./build` is Node-only developer tooling,
51
+ never meant to reach a browser bundle — bundle-size and tree-shaking tests fail if runtime consumers
52
+ accidentally receive build tooling or unrelated helper code. See
53
+ [`runtime/`](#runtime--define-validate-cache-and-expose-environment-values) and
54
+ [`build/`](#build--discover-analyze-link-and-generate-artifacts) below, and
55
+ [ADR 0004](decisions/0004-no-client-server-package-split.md).
56
+
57
+ ### The build tool never imports or executes a schema file
58
+
59
+ Discovery is AST analysis only (`build/parse.ts`, the TypeScript compiler API) — a schema file's
60
+ `createEnv()`/`documentEnv()` calls are read as syntax, never imported or run. This preserves the
61
+ safety boundary required for CI environments and large monorepos: a malicious or merely broken schema
62
+ file can't execute code just by being discovered. See
63
+ [`build/`](#build--discover-analyze-link-and-generate-artifacts) and
64
+ [ADR 0002](decisions/0002-static-analysis-never-execution.md).
65
+
66
+ ### `./build` does not acquire filesystem access implicitly
67
+
68
+ `./build` never imports `node:fs` itself — every public options object requires a caller-supplied
69
+ `BuildFileSystem` capability. The `env-cap` CLI (`src/cli/`) is the executable boundary that
70
+ constructs the real `node:fs/promises` adapter and hands it in; a consumer running the generators
71
+ from their own Node script imports that same adapter from `@maverickcer/env-cap/node`. This is the
72
+ same discipline `repo-contract`'s ADR-0011 established for `spawn`/`env`: a library surface should
73
+ not implicitly acquire a powerful ambient capability a caller did not explicitly provide. See
74
+ [ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md).
75
+
76
+ ### Documentation is inert at runtime
77
+
78
+ `documentEnv()` is a source-level marker the build system discovers through AST analysis — it stores
79
+ nothing in memory and adds no fields to a runtime contract. `createEnv()`'s runtime contracts and
80
+ `documentEnv()`'s documentation metadata are separate concerns that happen to share a source file, not
81
+ one pipeline. See
82
+ [Documentation is parallel to runtime, not part of runtime state](#documentation-is-parallel-to-runtime-not-part-of-runtime-state).
83
+
84
+ ### Runtime contracts are self-redacting
85
+
86
+ A contract's own `toString`/`console.log`/JSON representation never exposes resolved values —
87
+ `console.log(paymentsEnv)` prints `EnvContract("payments") { 1 variable(s) }`, never the underlying
88
+ secret. Explicit property access (`paymentsEnv.STRIPE_KEY`) remains required to read a value. See
89
+ [ADR 0006](decisions/0006-self-redacting-contracts.md) and [SECURITY.md](../SECURITY.md).
90
+
91
+ ### Validation contexts gate participation, nothing else
92
+
93
+ A variable with no `context` participates in every run; a variable with a `context` participates only
94
+ when `activeContexts` contains that exact string — no prefix matching, no inference from ambient
95
+ signals, no effect on `EnvContract`'s TypeScript shape, and no authorization/bundling meaning. See
96
+ [Validation context invariants](#validation-context-invariants) below and
97
+ [ADR 0022](decisions/0022-validation-contexts.md).
98
+
99
+ ### Manifest compatibility is the one blocking category
100
+
101
+ Of the three finding categories a generation run can produce — manifest compatibility/exclusive-group
102
+ issues, documentation completeness, and dependency ownership — only the first ever blocks
103
+ (`EnvProjectGenerationError`, nothing written). Documentation and ownership issues are heuristic
104
+ signals with real, common false-positive causes; they're recorded as `Finding`s on the persisted
105
+ Evidence Model instead, for a consumer to gate on explicitly if they want that enforced. See
106
+ [Data flow](#data-flow) and [ADR 0038](decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md).
107
+
108
+ ### The Evidence Model is always computed, independent of what's requested
109
+
110
+ `computeArtifacts()` always builds the full `EvidenceModel` — the manifest/docs/ownership/`--evidence`
111
+ flags only control which artifacts are additionally _written to disk_, never whether the underlying
112
+ model is computed. See [Data flow](#data-flow) and
113
+ [ADR 0038](decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md).
114
+
115
+ ## The entry points
116
+
117
+ `package.json` `exports` is the authoritative list (this section is the map of what each one is for, and TypeDoc generates the reference for each).
118
+
119
+ ```text
120
+
121
+ src/
122
+ ├── runtime/ @maverickcer/env-cap (runtime library)
123
+ ├── build/ @maverickcer/env-cap/build (Node-only build tooling)
124
+ ├── helpers/ @maverickcer/env-cap/helpers (optional utilities)
125
+ ├── evidence/ @maverickcer/env-cap/evidence (Evidence Model projections)
126
+ ├── node/ @maverickcer/env-cap/node (the Node-backed BuildFileSystem adapter)
127
+ └── eslint-plugin/ @maverickcer/env-cap/eslint-plugin (capability-owned-access lint rules)
128
+
129
+ ```
130
+
131
+ Each directory corresponds to a separate package export with its own build
132
+ output (configured in `tsup.config.ts`). Importing one entry point does not
133
+ include the implementation of the others.
134
+
135
+ `build`, `eslint-plugin`, and `runtime` contain their own implementation with
136
+ zero cross-folder dependency, including internal utilities.
137
+ `globToRegExp()`, for example, is needed by both `build/discover.ts` and
138
+ `eslint-plugin/no-raw-process-env.ts`; rather than living in a shared
139
+ internal module both would depend on, each directory owns its own copy
140
+ (`build/glob.ts`, `eslint-plugin/glob.ts` -- see ADR 0017's "Alternatives
141
+ considered"). `helpers` and `evidence` each have exactly one cross-folder
142
+ import, and both are structural, not incidental. `helpers`' `processors.ts`/
143
+ `validators.ts` import `Processor`/`Validator` as types (erased at compile
144
+ time) from `runtime/index.ts`, because a helper's whole job is producing a
145
+ value that type-checks as the exact shape `createEnv()` expects -- that
146
+ contract can't be expressed without referencing runtime's own type.
147
+ `evidence/define-projection.ts` imports `EvidenceModel` as a type (also
148
+ erased at compile time) from `build/evidence-model.ts`, for the same reason:
149
+ a projector's whole job is a function _of_ that shape, which can't be named
150
+ without referencing it -- see ADR 0031. Neither edge is an oversight: it's
151
+ what lets any of these five directories move to its own repository
152
+ independent of the others, with `helpers`/`evidence` simply gaining
153
+ `env-cap`/`env-cap-build` as an ordinary
154
+ dependency the way any package depending on another package's published
155
+ types would.
156
+
157
+ `src/cli/` (the `env-cap` bin, not a `package.json#exports` subpath) has the
158
+ same kind of real, intentional dependency on `build` -- it imports
159
+ `@maverickcer/env-cap/build`'s public surface (`src/build/index.ts`)
160
+ directly, never an internal `build/*.ts` file, since generating artifacts
161
+ from the command line requires the same engine `./build` exports. It is also
162
+ the one place `node:fs` is acquired to build the concrete `BuildFileSystem`
163
+ adapter `./build` requires (see [ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
164
+ A split-out `cli` package would simply declare `env-cap-build`
165
+ as a normal npm dependency.
166
+
167
+ This separation is enforced through automated checks. The tree-shaking tests
168
+ and bundle-size checks fail if runtime consumers accidentally receive build
169
+ tooling or unrelated helper code, and the `AmbientCapabilities` check
170
+ fails if a published library entrypoint's packed output reaches for
171
+ `node:fs` outside the CLI/`./node`/`./eslint-plugin` exceptions.
172
+
173
+ ```mermaid
174
+ flowchart TB
175
+ subgraph RUNTIME["package root - runtime (isomorphic)<br/>zero npm dependencies, no fs, no Node APIs"]
176
+ CREATE["createEnv()"]
177
+ DOCFN["documentEnv()<br/>(inert at runtime - a marker only)"]
178
+ VALIDATE["validateEnv()"]
179
+ REG["registry (WeakMap) + cache"]
180
+ end
181
+
182
+ subgraph HELPERS["./helpers - optional"]
183
+ PROC["processors.*"]
184
+ VALID["validators.*"]
185
+ end
186
+
187
+ subgraph BUILD["./build - Node-only, dev/CI tooling<br/>never imports node:fs (ADR 0040)"]
188
+ DISCOVER["discoverSchemaFiles()"]
189
+ PARSE["parseSchemaFile()<br/>TS compiler API - parses AST,<br/>never imports/executes the file"]
190
+ LINK["linkFiles()"]
191
+ CHECKS["detectCompatibilityIssues()<br/>detectExclusiveGroupIssues()"]
192
+ GEN["generateEnvManifest / Documentation /<br/>UsageReport / EnvArtifacts"]
193
+ CHECKMODE["checkEnvArtifacts() - the --check flag"]
194
+ DISCOVER --> PARSE --> LINK --> CHECKS --> GEN
195
+ GEN -.->|"same discovery + link,<br/>compare instead of write"| CHECKMODE
196
+ end
197
+
198
+ subgraph EVIDENCE["./evidence - isomorphic, optional"]
199
+ DEFPROJ["defineEvidenceProjection()"]
200
+ end
201
+
202
+ subgraph ESLINT["./eslint-plugin"]
203
+ RULE["no-raw-process-env / no-node-fs rules"]
204
+ end
205
+
206
+ subgraph CLIBIN["env-cap bin - src/cli/<br/>constructs the real node:fs adapter"]
207
+ MAIN["parseArgs() / main()"]
208
+ end
209
+
210
+ HELPERS -->|"type-only import:<br/>Processor / Validator"| RUNTIME
211
+ EVIDENCE -->|"type-only import:<br/>EvidenceModel"| BUILD
212
+ CLIBIN -->|"imports build's public<br/>src/build/index.ts +<br/>supplies BuildFileSystem"| BUILD
213
+ ```
214
+
215
+ `build`, `eslint-plugin`, and `runtime` have no edges between them above
216
+ because none exist: each owns its own copy of shared internals (e.g.
217
+ `glob.ts`) rather than importing from another entry point. `helpers`' and
218
+ `evidence`'s single edges are both type-only and erased at compile time.
219
+ This is what the tree-shaking and bundle-size tests in the previous
220
+ paragraph actually verify.
221
+
222
+ ## `runtime/` — define, validate, cache, and expose environment values
223
+
224
+ The runtime package contains only the functionality required while an
225
+ application is running.
226
+
227
+ Its core concepts are limited to:
228
+
229
+ - `default`
230
+ - `processor`
231
+ - `validator`
232
+ - `context` (a variable's validation context, see below and ADR 0022)
233
+
234
+ These are the only pieces of information required to transform raw
235
+ environment values into validated application configuration.
236
+
237
+ `createEnv()` (`runtime/create.ts`) creates a feature-owned environment
238
+ contract. `validateEnv()` (`runtime/validate.ts`) executes every registered
239
+ contract's processing pipeline against the provided environment values and
240
+ caches successful results through `runtime/cache.ts`. Before running that
241
+ pipeline for a given variable, it first checks whether the variable's
242
+ `context` (if any) is in the run's `activeContexts` -- a variable that
243
+ doesn't match is skipped entirely (no default/processor/validator runs) and
244
+ stays in its not-ready state, exactly as if this run had never happened for
245
+ it.
246
+
247
+ ### Validation context invariants
248
+
249
+ A **validation context** is an application-defined string a variable may
250
+ declare (`context`) and a validation run may activate (`activeContexts`).
251
+ env-cap never interprets, detects, or infers these strings itself -- the
252
+ application always computes and passes `activeContexts` explicitly. The
253
+ following invariants are load-bearing; none should be relaxed without a new
254
+ ADR (see [ADR 0022](decisions/0022-validation-contexts.md)):
255
+
256
+ 1. **Matching.** A variable without a `context` participates in every
257
+ validation run. A variable with a `context` participates only when
258
+ `activeContexts` contains that exact string. No prefix matching, no
259
+ wildcards, no hierarchy, no inheritance.
260
+ 2. **Not runtime detection.** env-cap never infers, detects, or defaults
261
+ `activeContexts` from any ambient signal (`window`, `NODE_ENV`, a
262
+ bundler `define`, etc.). The application always computes and passes it
263
+ explicitly.
264
+ 3. **Not cache identity.** `validateEnv()` stays one-shot per process: a
265
+ second call while already `"ready"` returns the first call's result
266
+ outright, without inspecting the second call's `activeContexts`. There
267
+ is no per-context cache dimension.
268
+ 4. **Not a type-level concept.** Validation contexts affect participation
269
+ at `validateEnv()` time only -- they do not alter `EnvContract`'s
270
+ TypeScript shape, `InferEnvValue`, or any generated type. Every schema
271
+ key remains a property of `EnvContract<S>` regardless of `context`; an
272
+ out-of-context key throws `EnvNotReadyError` at access time, exactly
273
+ like any value read before `validateEnv()` has run.
274
+ 5. **Not authorization.** Validation contexts are not an authentication,
275
+ authorization, or access-control mechanism. They determine validation
276
+ participation only, never who may read a resolved value.
277
+ 6. **Not a bundling/security boundary.** Separate discovery/manifests (ADR 0004) remain the real mechanism for keeping server-only source out of
278
+ client-bound code. `activeContexts` filtering happens after the schema
279
+ is already wherever it's going to be -- it does not remove a variable's
280
+ definition (or its `default` value) from a bundle that imports it.
281
+
282
+ `runtime/registry.ts` maintains the internal relationship between created
283
+ contracts and their schemas using a private `WeakMap`. This keeps internal
284
+ implementation details inaccessible to application code while allowing the
285
+ runtime to resolve values safely.
286
+
287
+ `runtime/errors.ts` defines the runtime error types used for validation
288
+ failures and invalid access states.
289
+
290
+ The runtime package intentionally:
291
+
292
+ - does not access the filesystem
293
+ - does not parse source code
294
+ - does not depend on Node-specific APIs
295
+ - has zero runtime npm dependencies
296
+
297
+ This keeps the runtime small, portable, and safe to include in browser,
298
+ edge, serverless, and Node environments.
299
+
300
+ ## `build/` — discover, analyze, link, and generate artifacts
301
+
302
+ The build package contains developer tooling only. It exists to analyze a
303
+ project's environment schemas and generate artifacts; it is not part of an
304
+ application's runtime execution path.
305
+
306
+ The build pipeline is responsible for:
307
+
308
+ - discovering schema files (`build/discover.ts`)
309
+ - parsing TypeScript source into AST representations (`build/parse.ts`)
310
+ - evaluating safe literal expressions (`build/literal-eval.ts`)
311
+ - linking `createEnv()` and `documentEnv()` calls (`build/link.ts`)
312
+ - detecting compatibility concerns (`build/compatibility.ts`,
313
+ `build/exclusive-group.ts`)
314
+ - scanning source files for variable access and deriving ownership findings
315
+ (`build/scan-dependencies.ts`, `build/dependency-graph.ts`) -- a
316
+ purely-syntactic, per-file walk that follows `contract.KEY` member access,
317
+ object-destructuring, and one level of file-unique `const` aliasing, and
318
+ records every shape it can't follow (a rest/nested/computed-key binding, a
319
+ reassigned alias, the contract passed around as a value) as an explicit
320
+ `escape` that widens a variable to `indeterminate`, never a false
321
+ `unconsumed` (see ADR 0039)
322
+ - resolving live expiration overrides for documentation (`build/live-expirations.ts`)
323
+ - generating output artifacts (`build/manifest.ts`, `build/docs.ts`,
324
+ `build/env-example.ts`, `build/usage-report.ts`)
325
+
326
+ `generateEnvManifest()` (`build/generate-manifest.ts`),
327
+ `generateDocumentation()` (`build/generate-documentation.ts`), and
328
+ `generateUsageReport()` (`build/generate-usage.ts`) each coordinate one of
329
+ these passes and are responsible for writing their own generated files.
330
+ `generateEnvArtifacts()` (`build/generate-env-artifacts.ts`) composes all
331
+ three into a single call sharing one discovery pass and one combined
332
+ blocking-failure check.
333
+
334
+ The build package never imports or executes application schema files. It
335
+ analyzes source structure instead of running user code. This preserves the
336
+ safety boundary required for CI environments and large monorepos.
337
+
338
+ See
339
+ [`decisions/0002-static-analysis-never-execution.md`](decisions/0002-static-analysis-never-execution.md)
340
+ for the reasoning behind AST analysis instead of dynamic imports.
341
+
342
+ Every public options object in `build/index.ts` also carries a required
343
+ `fs: BuildFileSystem` field -- `./build` itself never imports `node:fs`; see
344
+ [ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md) and the
345
+ [Core invariants](#core-invariants) above.
346
+
347
+ ## `helpers/` — optional processors and validators
348
+
349
+ The helpers package provides reusable implementations of the
350
+ `Processor` and `Validator` function types defined by
351
+ `runtime/types.ts`.
352
+
353
+ Examples include common transformations and validation patterns that most
354
+ applications would otherwise need to implement manually.
355
+
356
+ The runtime package has no dependency on helpers. They are convenience
357
+ utilities, not part of the environment-contract execution model.
358
+
359
+ `processors` and `validators` are separate exports so applications can
360
+ include only the category they use.
361
+
362
+ ## Documentation is parallel to runtime, not part of runtime state
363
+
364
+ The most important architectural separation is the distinction between
365
+ runtime configuration and human-facing documentation.
366
+
367
+ `createEnv()` defines the information required to process and validate
368
+ environment values.
369
+
370
+ `documentEnv()` defines information intended for developers, operators, and
371
+ generated artifacts, such as:
372
+
373
+ - descriptions
374
+ - ownership information
375
+ - lifecycle details
376
+ - expiration dates
377
+ - operational guidance
378
+
379
+ `documentEnv()` is intentionally inert at runtime. It exists as a source-level
380
+ marker that the build system can discover through AST analysis. It does not
381
+ store documentation data in memory or add documentation fields to runtime
382
+ contracts.
383
+
384
+ The relationship is therefore not a runtime pipeline:
385
+
386
+ ```mermaid
387
+ flowchart TB
388
+ SCHEMA["env.schema.ts"]
389
+
390
+ SCHEMA --> CREATECALL["createEnv(schema)"]
391
+ CREATECALL --> CONTRACT["runtime contract"]
392
+ CONTRACT --> VALIDATECALL["validateEnv()"]
393
+ VALIDATECALL --> VALUES["validated in-memory values"]
394
+
395
+ SCHEMA --> DOCCALL["documentEnv(schema, docs)"]
396
+ DOCCALL --> BUILDANALYSIS["build-time AST analysis only"]
397
+ BUILDANALYSIS --> ARTIFACTS["manifest / documentation / example artifacts"]
398
+ ```
399
+
400
+ The same schema file can contain both calls, but they serve different
401
+ consumers:
402
+
403
+ - application runtime consumes `createEnv()`
404
+ - build tooling consumes `documentEnv()`
405
+
406
+ ## Data flow
407
+
408
+ ```mermaid
409
+ flowchart TB
410
+ subgraph AUTHOR["1 - Author time (capability owner)"]
411
+ SCHEMA["features/payments/env.schema.ts<br/>createEnv(schema) + documentEnv(schema, docs)"]
412
+ end
413
+
414
+ subgraph BUILDTIME["2 - Build time - shared compute pipeline<br/>(explicit CLI / npm script / CI step, never automatic at startup)"]
415
+ DISCOVER["discoverSchemaFiles()<br/>glob scan, + optional --package allowlist,<br/>+ optional tsconfig path-alias resolution"]
416
+ PARSE["parseSchemaFile()<br/>TypeScript AST - static analysis,<br/>schema file is never imported/executed"]
417
+ LINK["linkFiles()<br/>pairs createEnv()/documentEnv() calls<br/>into DiscoveredContract objects"]
418
+ CHECKS{"detectCompatibilityIssues()<br/>detectExclusiveGroupIssues()<br/>blocking finding?"}
419
+ THROW["EnvProjectGenerationError<br/>nothing written, either mode"]
420
+
421
+ DISCOVER --> PARSE --> LINK --> CHECKS
422
+ CHECKS -- yes --> THROW
423
+ end
424
+
425
+ SCHEMA -.->|explicit run| DISCOVER
426
+
427
+ subgraph WRITE["2a - generateEnvArtifacts() (default: write)"]
428
+ MANIFEST["env.manifest.ts<br/>renderManifest()"]
429
+ DOCS["ENVIRONMENT.md<br/>renderDocs(), never blocks<br/>(findings, not throws - ADR 0038)"]
430
+ EXAMPLE[".env.example<br/>renderEnvExample(), reconciled<br/>against the existing file"]
431
+ OWNERSHIP["OWNERSHIP.md<br/>broader source scan -><br/>dependency graph -> ownership findings,<br/>never blocks (ADR 0038)"]
432
+ EVIDENCE["docs/env.evidence.json<br/>+ .fingerprint sidecar<br/>full EvidenceModel, always computed,<br/>independent of manifest.location - ADR 0038"]
433
+ end
434
+
435
+ subgraph CHECKPATH["2b - checkEnvArtifacts() (--check: compare, never write)"]
436
+ COMPARE["recompute every requested artifact,<br/>diff against what's already on disk<br/>(generatedAt/change normalized out<br/>for the evidence artifact - ADR 0038)"]
437
+ end
438
+
439
+ CHECKS -- "no, writing" --> MANIFEST & DOCS & EXAMPLE & OWNERSHIP & EVIDENCE
440
+ CHECKS -- "no, check mode" --> COMPARE
441
+
442
+ subgraph CI["3 - CI enforcement"]
443
+ GHACTION["GitHub Action (action.yml)<br/>env-cap --json -> PR annotations +<br/>sticky summary comment"]
444
+ ROTATION["rotation-alert GitHub issue<br/>on scheduled/non-PR runs -<br/>opens/auto-closes on expiringSoon"]
445
+ GHACTION --> ROTATION
446
+ end
447
+
448
+ COMPARE -->|exit 1 on drift| GHACTION
449
+
450
+ subgraph STARTUP["4 - Process startup"]
451
+ IMPORT["application imports<br/>the generated manifest"]
452
+ VALIDATECALL["validateEnv({ manifest,<br/>values: process.env, activeContexts })"]
453
+ PERVAR["per variable: context match?<br/>-> default -> processor -> validator<br/>-> freeze into cache"]
454
+ ERR["EnvValidationError<br/>aggregated failures"]
455
+ CACHED["cached validated result<br/>(one-shot per process)"]
456
+
457
+ IMPORT --> VALIDATECALL --> PERVAR
458
+ PERVAR -- "any invalid" --> ERR
459
+ PERVAR -- "all valid" --> CACHED
460
+ end
461
+
462
+ MANIFEST --> IMPORT
463
+
464
+ subgraph RUNTIME_ACCESS["5 - Runtime access"]
465
+ ACCESS["feature code imports the<br/>contract it owns:<br/>paymentsEnv.STRIPE_KEY"]
466
+ NOTREADY["EnvNotReadyError<br/>if read before validateEnv() resolves"]
467
+ end
468
+
469
+ CACHED --> ACCESS
470
+ ACCESS -. "read before ready" .-> NOTREADY
471
+ ```
472
+
473
+ `generateEnvArtifacts()` and `checkEnvArtifacts()` share one
474
+ `computeArtifacts()` pass (discovery, parsing, linking, and blocking-finding
475
+ checks) and only diverge at the last step: write, or compare-and-report (see
476
+ [ADR 0011](decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md)
477
+ and [ADR 0016](decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
478
+ Manifest, docs, `.env.example`, the ownership report, and the persisted
479
+ evidence artifact are each optional per `generateEnvArtifacts()`/
480
+ `checkEnvArtifacts()` call (`manifest`/`docs`/`usage`/`evidence` options) and
481
+ only appear above when requested. The `env-cap` CLI only exposes
482
+ `--location`/`--evidence` of those four -- docs/`.env.example`/the ownership
483
+ report have no CLI flag at all (ADR 0046: no verified runtime consumer, so
484
+ generating them is application code calling `generateDocumentation()`/
485
+ `generateUsageReport()` directly, not a CLI concern) -- except the
486
+ `EvidenceModel` backing the persisted evidence artifact, which
487
+ `computeArtifacts()` always builds regardless of whether `evidence`/
488
+ `--evidence` was requested; that option only controls whether it's also
489
+ written to disk (ADR 0038).
490
+ Manifest compatibility/exclusive-group issues are the one category that still
491
+ blocks (`CHECKS`, ADR 0009) — a documentation or ownership issue never does;
492
+ both are surfaced as `Finding`s on the evidence artifact instead, for a team
493
+ to gate on in its own CI step if it wants that enforced. The GitHub Action wraps whichever mode a workflow invokes
494
+ `env-cap --json` with.
495
+
496
+ ### 1. Author time
497
+
498
+ A feature owner creates an environment schema:
499
+
500
+ ```text
501
+
502
+ features/payments/env.schema.ts
503
+
504
+ ```
505
+
506
+ The file defines:
507
+
508
+ - the feature's environment variables
509
+ - processing rules
510
+ - validation rules
511
+ - optional documentation metadata
512
+
513
+ Importing the file creates the contract object but does not resolve
514
+ environment values.
515
+
516
+ ### 2. Build time
517
+
518
+ `generateEnvManifest()` runs as an explicit development or CI step.
519
+
520
+ It:
521
+
522
+ 1. discovers schema files
523
+ 2. parses their ASTs
524
+ 3. links `createEnv()` and `documentEnv()` calls
525
+ 4. checks for detectable issues
526
+ 5. generates requested artifacts
527
+
528
+ Possible outputs include:
529
+
530
+ - environment manifests
531
+ - documentation artifacts
532
+ - `.env.example` files
533
+
534
+ This process never runs automatically during application startup.
535
+
536
+ ### 3. Process startup
537
+
538
+ The application imports the generated manifest and calls:
539
+
540
+ ```ts
541
+ validateEnv({ manifest, values: process.env })
542
+ ```
543
+
544
+ Validation happens once for the process lifetime.
545
+
546
+ Each contract, per variable:
547
+
548
+ 1. checks whether the variable's `context` matches this run's
549
+ `activeContexts` -- if not, skips every remaining step entirely and
550
+ moves to the next variable (see "Validation context invariants" above)
551
+ 2. reads its raw value
552
+ 3. applies its default
553
+ 4. runs its processor
554
+ 5. runs its validator
555
+ 6. stores the frozen validated result
556
+
557
+ ```mermaid
558
+ flowchart LR
559
+ START(["for each variable<br/>in the contract"]) --> CTX{"has a context,<br/>and it's not in<br/>activeContexts?"}
560
+ CTX -- "yes - skip" --> SKIP["stays not-ready,<br/>as if this run<br/>never happened"]
561
+ CTX -- "no - participates" --> RAW["read raw value"]
562
+ RAW --> DEFAULT["apply default"]
563
+ DEFAULT --> PROC["run processor"]
564
+ PROC --> VALID["run validator"]
565
+ VALID --> FREEZE["store frozen<br/>validated result"]
566
+ ```
567
+
568
+ Failures are aggregated into `EnvValidationError` rather than stopping at
569
+ the first invalid variable.
570
+
571
+ ### 4. Runtime access
572
+
573
+ Feature code imports the contract it owns:
574
+
575
+ ```ts
576
+ paymentsEnv.STRIPE_KEY
577
+ ```
578
+
579
+ There is no global environment object.
580
+
581
+ Accessing a value before validation completes throws `EnvNotReadyError`.
582
+ Successful access returns the validated value for that specific feature
583
+ contract.
584
+
585
+ ## Module layout
586
+
587
+ The `src/` tree mirrors the entry points described above:
588
+ `runtime/`, `build/` (and `build/resolution/`), `helpers/`, `evidence/`,
589
+ `eslint-plugin/`, plus `cli/` (the `env-cap` bin) and `node/` (the
590
+ `@maverickcer/env-cap/node` executable-context entry that ships the CLI's
591
+ concrete `BuildFileSystem` adapter as a value for a consumer's own build
592
+ script). See [The entry points](#the-entry-points) for the
593
+ dependency rules between them.
594
+
595
+ ## Architectural decisions
596
+
597
+ | Boundary | ADR |
598
+ | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
599
+ | One `createEnv` vs `createEnv` + `defineEnv` | [0001](decisions/0001-runtime-documentation-separation.md) |
600
+ | Parsing instead of importing schema files | [0002](decisions/0002-static-analysis-never-execution.md) |
601
+ | Per-feature contracts instead of global `env` | [0003](decisions/0003-no-global-env-object.md) |
602
+ | No `/client` or `/server` package split | [0004](decisions/0004-no-client-server-package-split.md) |
603
+ | Warn by default instead of throwing | [0005](decisions/0005-warn-not-throw-by-default.md) |
604
+ | Self-redacting contracts | [0006](decisions/0006-self-redacting-contracts.md) |
605
+ | `processor` terminology instead of `transformer` | [0007](decisions/0007-processor-not-transformer.md) |
606
+ | Fixed gzip size budget on runtime/helpers | [0008](decisions/0008-gzip-size-budget.md) |
607
+ | Exclusive-group violations always error | [0009](decisions/0009-exclusive-groups-are-always-errors.md) |
608
+ | Dependency-ownership engine's fixed scope, internals not public | [0010](decisions/0010-dependency-ownership-engine-scope-boundary.md) |
609
+ | Shared discovery, compute-atomic but not write-atomic `generateEnvArtifacts()` | [0011](decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md) |
610
+ | Live expiration overrides via callback, not AST | [0012](decisions/0012-live-expiration-overrides-not-ast-functions.md) |
611
+ | `--json` CLI output is a versioned mirror | [0013](decisions/0013-json-output-is-a-versioned-mirror.md) |
612
+ | Cross-package schema discovery via explicit allowlist (Experimental) | [0014](decisions/0014-cross-package-schema-discovery.md) |
613
+ | Post-1.0 security-fix backport window (one major back, ≥6 months, never shortened once stated) | [0015](decisions/0015-security-backport-window.md) |
614
+ | `--check` computes fully before comparing, and never partially writes | [0016](decisions/0016-check-mode-compute-before-compare-never-partial-write.md) |
615
+ | A 4th public entry point (`./eslint-plugin`) for a capability-owned-access lint rule | [0017](decisions/0017-eslint-plugin-entry-point.md) |
616
+ | Rotation-alert GitHub issue on non-PR Action runs (opens/auto-closes based on expiringSoon) | [0018](decisions/0018-rotation-alert-issue-on-non-pr-runs.md) |
617
+ | The published `--json` schema is generated from types, never hand-authored | [0019](decisions/0019-published-json-schema-generated-from-types.md) |
618
+ | Declaration maps emitted by a separate `tsc` pass, not tsup's own `dts` pipeline | [0020](decisions/0020-declaration-maps-via-separate-tsc-pass.md) |
619
+ | The manifest change report is a persisted, committed JSON sidecar snapshot | [0021](decisions/0021-manifest-change-report-persisted-snapshot.md) |
620
+ | Generic, declarative validation contexts (`context`/`activeContexts`) | [0022](decisions/0022-validation-contexts.md) |
621
+ | TypeScript path-alias resolution, on by default (Experimental) | [0023](decisions/0023-tsconfig-path-alias-resolution.md) |
622
+ | Seven canonical fact models (Contract/Dependency/Ownership/Lifecycle/Finding/Change/Evidence), not thirty-five reports | [0024](decisions/0024-fact-model-architecture.md) |
623
+ | Contract Model is a new, versioned JSON projection, published alongside the manifest | [0025](decisions/0025-contract-model-json-projection.md) |
624
+ | Finding Model unifies four independently-shaped finding families | [0026](decisions/0026-finding-model-unifies-four-families.md) |
625
+ | Dependency Model publishes a fact-shaped result, not the scanning engine | [0027](decisions/0027-dependency-model-fact-shape-not-engine-access.md) |
626
+ | Ownership Model shares one effectiveOwner() rule, fixing a pre-existing divergence | [0028](decisions/0028-ownership-model-shared-effective-owner.md) |
627
+ | Lifecycle Model adds deprecation/rename fields, promotes ExpiringEntry | [0029](decisions/0029-lifecycle-model-deprecation-rename-fields.md) |
628
+ | Change Model wraps the existing manifest change report | [0030](decisions/0030-change-model-wraps-manifest-change-report.md) |
629
+ | A 5th public entry point (`./evidence`) for Evidence Model projections | [0031](decisions/0031-evidence-entry-point.md) |
630
+ | Evidence projection provenance via a non-frozen Proxy tracking membrane, not `Object.freeze()` | [0032](decisions/0032-evidence-projection-provenance-mechanism.md) |
631
+ | The ten first-party reference projections live in examples/, not src/ | [0033](decisions/0033-reference-projections-live-in-examples.md) |
632
+ | `computeArtifacts()` always builds a real `EvidenceModel`; `ManifestSnapshot` retires; docs/ownership never throw | [0038](decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md) |
633
+ | Usage scanner follows object-destructuring + one-level `const` aliasing; every other shape is an explicit `escape` | [0039](decisions/0039-scanner-local-dataflow-boundary.md) |
634
+ | Library surfaces (`./build`) never import `node:fs`; a caller supplies a `BuildFileSystem` | [0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md) |