@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,100 @@
1
+ # 0019: The published `--json` schema is generated from `src/cli/json.ts`'s types, never hand-authored
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `scripts/generate-json-schema.mjs`, committed at
6
+ `schemas/env-cap-report.schema.json`, published via the `./schema` subpath
7
+ export.
8
+
9
+ ## Context
10
+
11
+ `--json`'s envelope is already committed to being semver-stable (ADR 0013)
12
+ and documented via prose plus one worked example in the README, backed
13
+ internally by the `JsonSuccessPayload`/`JsonErrorPayload` types in
14
+ `src/cli/json.ts`. None of that helps an external, non-TypeScript tool -- a
15
+ Go service, a Python dashboard, a generic CI linter -- validate or codegen
16
+ against real `--json` output without hand-transcribing the README's one
17
+ example. A real, standalone JSON Schema artifact closes that gap, but only
18
+ if it can't silently drift from the actual emitted shape -- a hand-authored
19
+ schema is itself a second place the envelope's shape has to be kept in sync
20
+ by hand, exactly the kind of duplication `report.d.mts` (ADR 0013 decision 7) already accepts as a narrow, one-off exception for a single internal
21
+ test-support file, not a pattern to repeat for a schema external parties
22
+ will build real tooling against.
23
+
24
+ ## Decision
25
+
26
+ - **Generated from types, not hand-authored.** `scripts/generate-json-schema.mjs`
27
+ uses `ts-json-schema-generator` (a devDependency, not shipped at runtime)
28
+ to compile `src/cli/json.ts`'s exported `JsonReportPayload` type --
29
+ `JsonSuccessPayload | JsonErrorPayload`, the complete envelope shape --
30
+ directly into `schemas/env-cap-report.schema.json`. `report.d.mts`'s
31
+ hand-kept-in-sync exception is accepted there specifically because it's
32
+ one internal file with one maintainer's own test suite as the only
33
+ consumer; a schema published for arbitrary external tooling to build
34
+ against does not get the same latitude.
35
+ - **Two tests, not one**, because they prove different things:
36
+ - **Freshness** (`test/build/json-schema.test.ts`): regenerates the
37
+ schema in-memory and compares it byte-for-byte against the committed
38
+ file, failing if they differ. This proves the committed file matches
39
+ what the generator _currently_ produces -- the same "generated but
40
+ committed, diffable" discipline the example projects already use for
41
+ their own generated manifests/docs.
42
+ - **Correctness**: using `ajv` (a devDependency) against real `--json`
43
+ output from actually running the built CLI (a success case, a failure
44
+ case, and a `--check` run producing a `checkResult`-bearing payload),
45
+ asserting each validates cleanly against the committed schema.
46
+ Freshness alone only proves "the schema matches what the generator
47
+ currently produces" -- it says nothing about whether the schema is
48
+ _correct_ against real, running output, which is the property external
49
+ tooling actually depends on. A generator bug that produces a
50
+ self-consistent but wrong schema would pass the freshness test and fail
51
+ this one.
52
+ - **Ships in the published npm tarball, with its own subpath export.**
53
+ `schemas/` is added to `package.json`'s `files` array, and
54
+ `@maverickcer/env-cap/schema` maps directly to the JSON file -- the same
55
+ pattern already used for `"./package.json": "./package.json"` -- so a
56
+ consumer can resolve it via Node's own module resolution rather than
57
+ reconstructing a path into `node_modules`.
58
+ - **Evolves under the same additive-only rules as `--json` itself.** A new
59
+ optional field appearing in the schema is never a breaking change; a
60
+ changed or removed field is, exactly mirroring ADR 0013's policy for the
61
+ envelope the schema describes. `VERSIONING.md`'s Stable tier gains an
62
+ explicit line for this.
63
+
64
+ ## Consequences
65
+
66
+ - `npm run schema` regenerates the file — a developer runs it locally after
67
+ changing `src/cli/json.ts`'s types and commits the result, the same as any
68
+ other generated-and-committed artifact this project produces. No CI step
69
+ re-runs the script itself; a stale commit is still caught, via the
70
+ freshness test (`test/build/json-schema.test.ts`), which regenerates the
71
+ schema in-memory during the normal test run and byte-compares it against
72
+ the committed file — the same way a stale generated manifest would fail in
73
+ any project using this tool on itself.
74
+ - External tooling gets exactly one artifact to point at
75
+ (`@maverickcer/env-cap/schema` or `schemas/env-cap-report.schema.json` in
76
+ the repo) instead of reverse-engineering the README's prose example.
77
+ - `ts-json-schema-generator` and `ajv` are devDependencies only -- neither
78
+ ships in the published package or is required at runtime by anything
79
+ except the schema-generation/test scripts themselves.
80
+
81
+ ## Alternatives considered
82
+
83
+ - **Hand-author the schema once and keep it in sync manually.** Rejected --
84
+ this is precisely the failure mode a generated schema exists to prevent;
85
+ a manually-maintained schema silently drifting from the real envelope
86
+ would be worse than not publishing one at all, since it would carry false
87
+ authority.
88
+ - **Freshness test only, skip the correctness test.** Rejected -- freshness
89
+ alone can't catch a generator bug that produces a schema internally
90
+ consistent with itself but wrong against what the CLI actually emits
91
+ (e.g. a misconfigured `expose`/`jsDoc` option silently dropping a real
92
+ field). Running the real, built CLI and validating its actual output is
93
+ the only way to catch that class of bug.
94
+ - **`typescript-json-schema` instead of `ts-json-schema-generator`.**
95
+ Both are actively maintained and comparably popular; `ts-json-schema-generator`
96
+ was chosen as the plan's leading candidate and confirmed still actively
97
+ maintained (multiple releases within the last month) at implementation
98
+ time. Either would satisfy this decision's actual requirement (generated,
99
+ not hand-authored); this is a tooling choice, not a load-bearing part of
100
+ the decision itself.
@@ -0,0 +1,101 @@
1
+ # 0020: Declaration maps are emitted by a separate `tsc` pass, not tsup's own `dts` pipeline
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `tsconfig.build.json`, `scripts/emit-dts-shims.mjs`,
6
+ and `package.json`'s `build` script (`tsup && tsc -p tsconfig.build.json &&
7
+ node scripts/emit-dts-shims.mjs`).
8
+
9
+ ## Context
10
+
11
+ Sourcemaps (`sourcemap: true`) were straightforward to enable across all
12
+ five `tsup.config.ts` targets. Declaration maps (`.d.ts.map`, letting an
13
+ editor's "Go to Definition" on an imported type land in real `.ts` source
14
+ instead of the bundled `.d.ts`) were expected to be equally simple: tsup's
15
+ `dts` option accepts a `compilerOptions` object, and passing
16
+ `{ declarationMap: true }` there looked like the natural way to enable them.
17
+
18
+ It doesn't work. Reading the installed `tsup@8.5.1`'s bundled dts pipeline
19
+ (`rollup-plugin-dts`, used whenever `dts: true` or `dts: {...}` is set)
20
+ showed two things: first, `dts.compilerOptions` is only honored by tsup's
21
+ separate, opt-in `experimentalDts` pipeline -- not the default one this
22
+ project uses. Second, and more fundamentally, `rollup-plugin-dts`'s own
23
+ `DEFAULT_OPTIONS` hardcodes `declarationMap: false` internally, so even
24
+ routing the option correctly wouldn't have produced a working map: the
25
+ bundling step that merges multiple source files' declarations into one
26
+ `dist/index.d.ts` per entry point has no path to emit a coherent merged map
27
+ at all. Building it and inspecting `dist/index.d.ts.map` confirmed this
28
+ directly -- no file was produced.
29
+
30
+ ## Decision
31
+
32
+ Declaration files and their maps are emitted by a genuinely separate `tsc`
33
+ invocation, not tsup at all:
34
+
35
+ 1. All five `tsup.config.ts` targets set `dts: false`. tsup only produces
36
+ the bundled `.js`/`.cjs` output (plus sourcemaps) for each entry point.
37
+ 2. A new `tsconfig.build.json` (extending the project's own `tsconfig.json`)
38
+ runs `tsc --declaration --declarationMap --emitDeclarationOnly` against
39
+ `src/` (excluding `test/` and `src/cli/**`, which ships no public types),
40
+ emitting one real per-file `.d.ts`/`.d.ts.map` pair per source file into
41
+ `dist/.dts/`, mirroring `src/`'s own directory structure. Plain `tsc`
42
+ reliably produces correct per-file maps -- it's specifically
43
+ `rollup-plugin-dts`'s _bundling_ step that can't, not TypeScript's
44
+ declaration emit itself.
45
+ 3. Since `tsc` (unlike `rollup-plugin-dts`) has no bundling step, and
46
+ `package.json#exports` pins each entry point to a single filename (e.g.
47
+ `dist/index.d.ts`), a new `scripts/emit-dts-shims.mjs` writes a one-line
48
+ re-export shim for each public entry point's `.d.ts`/`.d.cts`
49
+ (`export * from "./.dts/<target>/index.js";`), pointing package.json's
50
+ declared type location at the real per-file declarations underneath.
51
+ 4. `package.json`'s `build` script becomes `tsup && tsc -p
52
+ tsconfig.build.json && node scripts/emit-dts-shims.mjs` -- three steps,
53
+ run in that order, every time.
54
+
55
+ Verified end-to-end, not just at the file-existence level: an installed
56
+ tarball (`npm pack`, installed into a scratch project) resolves a real,
57
+ non-`any` type through the shim -- a deliberately wrong `Processor`
58
+ signature in a scratch consumer produced a genuine `tsc` type error against
59
+ the shipped declarations, proving the shim isn't silently degrading to
60
+ `any`.
61
+
62
+ ## Consequences
63
+
64
+ - The build has three sequential steps instead of one. A contributor
65
+ changing `tsup.config.ts`'s `dts`/`sourcemap` settings needs to
66
+ understand why `dts: false` appears on every target and where the real
67
+ declarations actually come from -- this ADR, plus the inline comments on
68
+ `tsup.config.ts`'s `dts: false` lines and at the top of
69
+ `scripts/emit-dts-shims.mjs`, are that record.
70
+ - `dist/.dts/` ships inside the published npm tarball (`files` includes the
71
+ whole `dist` directory) -- it's not optional scaffolding, the four shim
72
+ files depend on it existing at the paths they reference.
73
+ - If `src/eslint-plugin/` (or any future `dts`-bearing entry point) is
74
+ added, both `scripts/emit-dts-shims.mjs`'s `ENTRIES` list and
75
+ `tsconfig.build.json`'s `include`/`exclude` need the new entry point
76
+ accounted for -- `tsconfig.build.json`'s `include: ["src"]` already covers
77
+ a new directory under `src/` by default; only an entry point that should
78
+ be _excluded_ (like `src/cli/`, which ships no declarations at all) needs
79
+ an explicit exclude added.
80
+ - If a future `tsup`/`rollup-plugin-dts` release adds real declaration-map
81
+ support to the bundling pipeline, this three-step build can collapse back
82
+ to tsup's native `dts: true` -- nothing about this decision assumes the
83
+ gap is permanent, only that it exists today.
84
+
85
+ ## Alternatives considered
86
+
87
+ - **`dts: { compilerOptions: { declarationMap: true } }` as originally
88
+ planned.** Rejected after verification -- doesn't work, for the two
89
+ reasons in Context above (wrong pipeline, and that pipeline's own
90
+ hardcoded default even if it were reached).
91
+ - **tsup's `experimentalDts` option**, which does read `compilerOptions`.
92
+ Not pursued -- it's explicitly experimental in tsup itself, uses a
93
+ different (per-file, not bundled) output shape that would itself require
94
+ the same shim-file treatment to fit `package.json#exports`' one-file-per-
95
+ entry-point pins, and swapping one experimental dependency behavior for
96
+ another doesn't remove the actual complexity, just relocates it.
97
+ - **Give up on declaration maps entirely.** Rejected -- "Go to Definition"
98
+ landing in real source instead of a bundled `.d.ts` is a real editor-
99
+ experience improvement or long-time maintainers and external contributors
100
+ alike, and the separate-`tsc`-pass approach achieves it without giving up
101
+ tsup's bundling for the actual JS output.
@@ -0,0 +1,177 @@
1
+ # 0021: The manifest change report is a persisted, committed JSON sidecar snapshot
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/build/manifest-snapshot.ts`, wired into
6
+ `src/build/generate-manifest.ts` (`generateEnvManifest()`) and
7
+ `src/build/generate-env-artifacts.ts` (`generateEnvArtifacts()`). The
8
+ duplicate-documentation warning it depends on is implemented in
9
+ `src/build/compatibility.ts` (`detectCompatibilityIssues()`).
10
+
11
+ ## Context
12
+
13
+ `generateEnvManifest()` has never had any memory of a previous run. `docs.ts`
14
+ already solves an adjacent problem for the Markdown docs artifact -- it
15
+ re-reads its own previously-written file before overwriting it, and diffs the
16
+ ``### `KEY` `` headings it finds against the current run to report an
17
+ added/removed/commented key summary (`computeChangeSummary()`,
18
+ `renderHeader()`). The manifest has nothing equivalent to read back: its `.ts` output is deliberately metadata-free by design -- sorted imports plus a `contracts` array, "no timestamps, no randomness" per `manifest.ts`'s own
19
+ docstring. There is no `description`/`owner`/`expiresAt`/etc. in it at all,
20
+ so there is nothing in a previously-generated `manifest.ts` for a later run
21
+ to parse back out.
22
+
23
+ The ask was to teach `generateEnvManifest()` to report `documentEnv()`
24
+ metadata that was added, removed, or changed since the last run, and to
25
+ specifically call out two related but distinct situations: (a) two _active_
26
+ contracts declaring the same variable with divergent documented metadata
27
+ right now, in the same run, and (b) a single variable's documented metadata
28
+ having drifted since the last time this ran. These need different mechanisms.
29
+ (a) is a same-run comparison with no history involved -- it's the same shape
30
+ of problem `detectCompatibilityIssues()` already solves for processor/
31
+ validator source (0005), just applied to documentation fields instead of
32
+ code. (b) genuinely needs persisted state across runs, which nothing in this
33
+ codebase had before this change.
34
+
35
+ ## Decision
36
+
37
+ **A new sidecar file, not a change to `manifest.ts` itself.** Every
38
+ `generateEnvManifest()` (and, via `generate-env-artifacts.ts`, every
39
+ `generateEnvArtifacts()` call with a `manifest` pass) writes
40
+ `<manifest-location>.snapshot.json` alongside the manifest -- e.g.
41
+ `src/generated/env.manifest.ts` gets a sibling
42
+ `src/generated/env.manifest.snapshot.json`. It's a deterministic JSON
43
+ projection of exactly the documented-metadata fields already on
44
+ `DiscoveredContract`/`DiscoveredVariable` (contract-level `contractName`/
45
+ `active`/`category`/`exclusiveGroup`/`owner`/`expiresAt`/`metadata`,
46
+ variable-level `description`/`owner`/`expiresAt`/`refreshInstructions`/
47
+ `required`/`extra`/`documented`), sorted by file/exportName/key so
48
+ `JSON.stringify` output is stable and diffs cleanly. Nothing schema- or
49
+ processor-shaped is in it -- that distinction is exactly why `manifest.ts`
50
+ itself couldn't be reused for this.
51
+
52
+ **Committed, not ephemeral.** The snapshot is meant to be committed to git
53
+ right next to the manifest it describes, the same way the manifest itself
54
+ already is. "Since last execution" means "since the last commit on this
55
+ branch" -- reviewable in a PR diff, and consistent in CI (a fresh checkout
56
+ sees exactly what the last commit left behind) in a way a gitignored,
57
+ per-machine cache directory could never be. A local-cache design was
58
+ considered and rejected specifically because CI's "since last execution"
59
+ would otherwise mean nothing at all on a fresh checkout.
60
+
61
+ **Scoped to active contracts only**, matching `renderManifest()`'s own scope.
62
+ A contract flipping from `active: true` to `active: false` disappears from
63
+ `manifest.ts` itself; it disappears from this snapshot for the same reason,
64
+ and shows up as `removedContracts`/`removedVariables` in the next diff.
65
+
66
+ **`schemaVersion`, with the same bump discipline `src/cli/json.ts`'s
67
+ `JSON_SCHEMA_VERSION` already documents** (ADR 0019's sibling policy, not a
68
+ new one): bump only when a reader could misinterpret the new shape, never for
69
+ an ordinary additive field. Reading a snapshot distinguishes four cases, not
70
+ two -- `"missing"` (no snapshot yet: the normal, silent first-run state),
71
+ `"invalid-json"` (unparseable), `"unsupported-version"` (parses fine, but a
72
+ `schemaVersion` this build doesn't recognize), and `"ok"`. The first is
73
+ silent; the middle two are **surfaced as a `ParseWarning`**, reusing the
74
+ existing warning channel every generator result already carries (rather than
75
+ inventing a new field), specifically so a corrupted or foreign-version
76
+ snapshot never masquerades as "nothing has ever been documented before" --
77
+ that would otherwise render as a confusing wall of "everything just got
78
+ added" with no visible explanation for why history was lost.
79
+
80
+ **Field-level diffs, not just field-name lists.** `ManifestChangeReport`'s
81
+ `updatedContracts`/`updatedVariables` entries carry
82
+ `{ field, previous, current }` per differing field (including
83
+ `metadata.<key>`/`extra.<key>` for record fields), not merely the names of
84
+ what changed. The values are already known at diff time; making a CLI
85
+ formatter, a JSON consumer, or a future GitHub Action annotation re-derive
86
+ them from somewhere else would be pure friction for no benefit.
87
+
88
+ **Duplicate-key documentation divergence is a `CompatibilityIssue`
89
+ extension, not a new mechanism.** Two _active_ contracts documenting the same
90
+ variable key with different `description`/`owner`/`expiresAt`/
91
+ `refreshInstructions`/`required`/`extra` is a same-run, no-history comparison
92
+ -- `detectCompatibilityIssues()` already runs this exact kind of pairwise
93
+ per-key comparison for processor/validator source (0005), so this is a third
94
+ comparison added to that same loop, not a parallel system. It is always
95
+ `severity: "warning"`, never `"error"` (see "Alternatives considered" for why
96
+ this isn't treated like ADR 0009's exclusive-group violations), and
97
+ participates in the existing `onIncompatibility` warn/throw gate unchanged.
98
+ It's also the first check to set the new, optional `CompatibilityIssue.code`
99
+ field (`"duplicate-variable-documentation"`) -- a stable, machine-readable
100
+ identifier deliberately added to the type as opt-in rather than backfilled
101
+ onto the three checks that predate it, so CI filtering, doc-linking, or an
102
+ IDE integration has something to key on without this change also being a
103
+ silent behavior change for every existing warning.
104
+
105
+ **`--check` is untouched.** `computeArtifacts()` (shared by the write path
106
+ and by `checkEnvArtifacts()`, ADR 0011) computes the snapshot diff as a
107
+ read-only step -- it was already doing read-only discovery/linking work
108
+ `checkEnvArtifacts()` needed anyway, so the diff comes along for free. But
109
+ `checkEnvArtifacts()` itself never surfaces it and never writes the new
110
+ snapshot file: ADR 0016's "nothing is ever written at all" guarantee for
111
+ `--check` stays exactly as absolute as it already was, and
112
+ `CheckEnvArtifactsResult`'s shape gains no new field from this change.
113
+
114
+ **Only `ManifestChangeReport` (and the small ref/update/field-change types
115
+ its entries are built from) are exported from `src/build/index.ts`.** The
116
+ snapshot build/read/write/diff functions in `manifest-snapshot.ts`, and the
117
+ on-disk `ManifestSnapshot`/`ManifestSnapshotContract`/`ManifestSnapshotVariable`
118
+ shapes, all stay internal. This mirrors ADR 0010's precedent for the
119
+ dependency-ownership engine: a primitive earns Experimental-public status
120
+ through a real external caller pushing on it, not by default just because it
121
+ was convenient to write as an exported function.
122
+
123
+ ## Consequences
124
+
125
+ - A PR that changes `documentEnv()` metadata now shows that change twice: once
126
+ as prose in the regenerated docs artifact (if a docs pass is requested),
127
+ and once as a structured, field-level diff in the committed snapshot JSON
128
+ -- a reviewer can see exactly which fields moved without reading the whole
129
+ generated Markdown file.
130
+ - The very first `generateEnvManifest()` run against any given `location`
131
+ (or the first run after cloning a repo that hasn't committed a snapshot
132
+ yet) reports every discovered variable as `added*`. This is expected, not
133
+ a bug -- the same "first run has no `previousContent`" shape `docs.ts`'s
134
+ own change summary has always had.
135
+ - One more generated-and-committed file to review per manifest, alongside
136
+ `manifest.ts` itself. This is mitigated by it being fully automatic (every
137
+ `generate:env`/CI run regenerates it, there is no separate manual step --
138
+ see the snapshot's own explanatory section in the package README) and by
139
+ the field-level diff making the review itself fast rather than requiring a
140
+ reader to reconstruct what changed from two full JSON blobs.
141
+ - A hand-edited or foreign-tool-written snapshot degrades gracefully to a
142
+ visible warning plus a fresh-start diff, never a crash and never a silent,
143
+ unexplained loss of history.
144
+
145
+ ## Alternatives considered
146
+
147
+ - **Embed the metadata directly into `manifest.ts`.** Rejected. That file's
148
+ entire contract, documented in its own file header, is "no timestamps, no
149
+ randomness -- same input files always produce byte-identical output" and
150
+ nothing beyond imports plus a `contracts` array. Adding diffable metadata
151
+ there would mean either breaking that contract or parsing TypeScript
152
+ (rather than JSON) back out on the next run to recover prior state, for no
153
+ benefit over a dedicated, purpose-built sidecar.
154
+ - **An ephemeral, gitignored cache instead of a committed file.** Rejected --
155
+ "since last execution" would mean "since last time this exact machine ran
156
+ it," which is meaningless in CI (a fresh checkout every run has no local
157
+ history) and gives a PR reviewer nothing to look at. The whole value of the
158
+ feature is the structured diff being visible in review, the same way the
159
+ manifest and docs artifacts already are.
160
+ - **Reuse `docs.ts`'s existing `previousContent` mechanism (read back the
161
+ Markdown docs file) instead of a dedicated snapshot.** Rejected --
162
+ `generateEnvManifest()` is fully usable standalone, with no docs pass ever
163
+ requested. Making the manifest's own change-tracking depend on whether a
164
+ docs artifact happens to exist elsewhere would make the feature's
165
+ availability accidental rather than a property of `generateEnvManifest()`
166
+ itself.
167
+ - **Escalate duplicate-variable-documentation divergence to `severity:
168
+ "error"`, unconditionally, the way ADR 0009 treats exclusive-group
169
+ violations.** Rejected. ADR 0009's reasoning is that `exclusiveGroup` is an
170
+ explicit, author-declared constraint with no legitimate "maybe" reading --
171
+ two contracts either share the string or they don't. Two contracts
172
+ documenting the same variable name differently has no such property: it is
173
+ never provably wrong via static analysis, exactly like the pre-existing
174
+ differently-shaped-processor-source and differently-shaped-validator-source
175
+ checks it sits alongside. Warning-tier, gated by the existing
176
+ `onIncompatibility` option, is the correct precedent to follow here, not
177
+ the exclusive-group one.
@@ -0,0 +1,267 @@
1
+ # 0022: Generic validation contexts
2
+
3
+ ## Status
4
+
5
+ Accepted.
6
+
7
+ ## Context
8
+
9
+ ADR 0004 rejected a `runtime: "server"|"client"` option on `createEnv()`,
10
+ and rejected separate `/client`/`/server` packages, because a variable's
11
+ classification as server-only or client-safe doesn't change how it's
12
+ processed or validated -- and because the real boundary that keeps
13
+ server-only source out of a browser bundle is the application's module
14
+ graph (separate discovery -> separate generated manifests), not something
15
+ a runtime flag could enforce anyway.
16
+
17
+ That decision holds. But real usage since then has surfaced a narrower,
18
+ legitimate need it didn't address: a single validation run sometimes needs
19
+ to activate or deactivate variables by some caller-defined facet --
20
+ "which deployment target," "which environment tier," "which entry point"
21
+ -- without necessarily forking into multiple manifests for it. Examples:
22
+
23
+ - One manifest shared by a Node server and its browser bundle, where each
24
+ process should only validate (and be able to read) the variables that
25
+ apply to it.
26
+ - A single manifest validated with different `activeContexts` in
27
+ development vs. production, to require a variable only where it
28
+ actually matters.
29
+ - A backend that also runs a worker/edge entry point from the same
30
+ codebase, where a handful of variables are entry-point-specific.
31
+
32
+ This ADR adds **validation contexts** to close that gap, while explicitly
33
+ not reopening what ADR 0004 already settled.
34
+
35
+ ## Decision
36
+
37
+ A schema entry may declare a validation context:
38
+
39
+ ```ts
40
+ DATABASE_URL: {
41
+ context: "server",
42
+ validator: validators.required(),
43
+ }
44
+ ```
45
+
46
+ `validateEnv()` accepts the validation contexts active for this run:
47
+
48
+ ```ts
49
+ await validateEnv({
50
+ manifest,
51
+ values: process.env,
52
+ activeContexts: ["server", "production"],
53
+ })
54
+ ```
55
+
56
+ **Matching rule:** a variable without a `context` participates in every
57
+ run. A variable with a `context` participates only when `activeContexts`
58
+ contains that exact string. Omitted `activeContexts` behaves as empty --
59
+ this isn't a special case, it's the general rule applied uniformly (an
60
+ empty set contains no string, so only context-less variables match),
61
+ which is exactly why every existing schema (none of which set `context`)
62
+ behaves identically before and after this feature exists.
63
+
64
+ **Skip means skip the entire pipeline.** A variable that doesn't match
65
+ never runs its `default`/`processor`/`validator`, is never counted as
66
+ validated, and is never written into the validated result -- it stays in
67
+ its not-ready state exactly as if this run had never happened for it.
68
+ Reading it throws `EnvNotReadyError`, the same error (and the same code
69
+ path) as reading any variable before `validateEnv()` has run. Getting this
70
+ right required a small, real bug fix alongside the new field: contract
71
+ readiness was tracked per _contract_, not per _variable_ (`create.ts`'s
72
+ getter only checked whether the whole contract had been validated, then
73
+ read the key from its cached values unconditionally). A context-skipped
74
+ variable is simply absent as an own property of that cached object, so the
75
+ getter now checks key presence, not just contract presence.
76
+
77
+ ### Why `context` is first-class schema vocabulary, not documentation metadata
78
+
79
+ `EnvDefinition` is deliberately minimal (`default`/`processor`/`validator`
80
+ -- see ADR 0001, ADR 0007), and everything that doesn't change runtime
81
+ behavior lives in `documentEnv()` instead. `context` belongs with the
82
+ former, not the latter, for the same reason `default`/`processor`/
83
+ `validator` do: `validate.ts` reads it directly to decide whether the rest
84
+ of the pipeline runs at all. That build tooling can _also_ read it for
85
+ generated docs is incidental -- true of `hasDefault`/`hasProcessor`/
86
+ `hasValidator` today too -- not the justification.
87
+
88
+ ### Why declarative metadata, not a callback
89
+
90
+ An alternative shape would let a variable decide participation itself,
91
+ e.g. `shouldInclude: (activeContexts) => boolean`. Rejected: ADR 0002
92
+ requires schemas to be statically analyzable without executing them: a
93
+ callback can't be evaluated by the AST parser, so build tooling could
94
+ never surface which context a variable belongs to in generated docs or
95
+ `.env.example` -- exactly the kind of unanalyzable schema entry ADR 0002
96
+ already treats as a parse-time warning, not a supported pattern.
97
+
98
+ ### Why a single string, not an array, on the variable side
99
+
100
+ `context?: string`, not `context?: string[]`. A variable belongs to at
101
+ most one validation context. An array would require defining AND/OR
102
+ semantics for a variable that lists more than one -- and either answer
103
+ adds a second axis of complexity for a feature whose whole value is being
104
+ simple enough to reason about at a glance. If a real case ever needs one
105
+ variable to participate in more than one context, that should be solved
106
+ by an explicit new mechanism (a second field, or splitting into two
107
+ schema entries) -- never by loosening this field to `string | string[]`,
108
+ which would silently reintroduce the exact ambiguity this decision avoids.
109
+
110
+ ### Why `activeContexts` is a plural array on `validateEnv()`
111
+
112
+ Unlike a variable, one validation run can have several simultaneously-true
113
+ facets -- `["server", "production"]` is both "which deployment target" and
114
+ "which environment tier" at once. The option is named `activeContexts`,
115
+ not `contexts`, specifically because "contexts" alone is ambiguous between
116
+ "declared" and "currently active"; the option is unambiguously the latter.
117
+
118
+ ### Why omitted-context variables always participate
119
+
120
+ This is what makes the feature backward compatible without a migration or
121
+ an opt-in flag: every schema written before this feature exists has no
122
+ `context` fields, so under the matching rule above, every variable in it
123
+ keeps matching via the `context === undefined` branch regardless of what
124
+ (or whether) `activeContexts` is passed. No existing caller needs to
125
+ change anything.
126
+
127
+ ## Formal invariants
128
+
129
+ These are the contract this feature makes, written down so future changes
130
+ don't erode it without a new ADR. (Also stated in
131
+ [`specs/architecture.md`](../architecture.md#validation-context-invariants),
132
+ which is the canonical copy -- repeated here for the record.)
133
+
134
+ 1. **Matching** is exact-string only: no prefix matching, wildcards,
135
+ hierarchy, or inheritance.
136
+ 2. **Not runtime detection.** env-cap never infers `activeContexts` from
137
+ any ambient signal. The application always computes and passes it.
138
+ 3. **Not cache identity.** `validateEnv()` stays one-shot per process;
139
+ `activeContexts` isn't part of what makes a second call a no-op, and
140
+ there is no per-context cache dimension.
141
+ 4. **Not a type-level concept.** `context` never alters `EnvContract`'s
142
+ TypeScript shape or any inferred type. Every schema key remains a
143
+ property of `EnvContract<S>` regardless of context; an out-of-context
144
+ read is a runtime throw, not a compile-time error.
145
+ 5. **Not authorization.** A validation context is not an authentication,
146
+ authorization, or access-control mechanism -- it does not restrict
147
+ _who_ can read a value, only whether a given `validateEnv()` run
148
+ processes it at all.
149
+ 6. **Not a bundling/security boundary.** Separate discovery/manifests (ADR 0004) remain the actual mechanism for keeping server-only source out of
150
+ client-bound code. `activeContexts` filtering happens after the schema
151
+ -- including any literal `default` value -- is already wherever it's
152
+ going to be. Putting both `context: "server"` and `context: "client"`
153
+ variables in one schema feeding one manifest that a client bundle
154
+ imports does not stop the server-context variable's definition from
155
+ shipping to the browser.
156
+
157
+ ## Consequences
158
+
159
+ - **Generated docs and `.env.example` surface `context`**, extracted the
160
+ same statically-analyzed way as `hasDefault`/`hasProcessor`/
161
+ `hasValidator` (never executed -- a non-literal `context` warns and is
162
+ ignored, same as every other unanalyzable field). Rendered as
163
+ "Validation context," not the bare "Context," and paired with the
164
+ non-boundary/non-authorization caveat wherever it's shown, so a
165
+ generated artifact never reads as more of a guarantee than it is.
166
+ - **The generated manifest file also exports `activeContexts`** -- every
167
+ validation context declared by any variable in an _active_ contract
168
+ (`discoverValidationContexts()`, `src/build/manifest.ts`), sorted and
169
+ deduplicated, named to match `validateEnvOptions.activeContexts` itself
170
+ so application code can pass it straight through:
171
+ `validateEnv({ manifest, values, activeContexts })`. It's every context
172
+ the manifest has, meant as a starting point to narrow per process --
173
+ importing it unmodified into every process defeats the point of scoping
174
+ contexts per deployment target in the first place (see the README's
175
+ "Validation contexts" section). Emitted only when at least one variable
176
+ actually declares a `context`, immediately after the imports (`// all
177
+ currently active validation contexts`), so a project that doesn't use
178
+ this feature gets byte-identical manifest output to before this ADR.
179
+ This was originally scoped as _not_ touching the manifest at all (an
180
+ earlier draft of this ADR said so); seeing the feature in real use made
181
+ clear that hand-typing the discovered context list at every
182
+ `validateEnv()` call site was the actual remaining friction, so this was
183
+ added as an explicit, later revision -- see "Alternatives considered"
184
+ for the scaffolded-`validateEnv()`-call approach that was tried first
185
+ and rejected.
186
+ - **A validation run's participation detail isn't exposed as data.**
187
+ `validateEnvResult` still reports only `contractCount`/`variableCount`
188
+ (a skipped variable isn't counted in the latter). Future diagnostics
189
+ could expose which variables were skipped and why (`{ skippedVariables,
190
+ activeContexts }`) without changing validation semantics -- not
191
+ implemented here, to keep this change purely additive and minimal; see
192
+ Alternatives.
193
+ - **Empty-string `context` is treated as absent, at the build layer.** A
194
+ literal `context: ""` almost certainly signals a mistake, not an
195
+ intentional empty context; the static analyzer warns and drops it
196
+ (same "warn, don't guess" policy as every other field). The runtime
197
+ itself does not add a check for this -- an empty string flowing through
198
+ at runtime just never matches anything in practice, which is harmless,
199
+ and adding runtime input-shape validation for a schema field has no
200
+ precedent elsewhere in this codebase (the runtime trusts
201
+ `default`/`processor`/`validator`'s shape too) and would cost bytes
202
+ against the ADR 0008 gzip budget for a case the build-time warning
203
+ already catches for anyone running the generator.
204
+
205
+ ## Alternatives considered
206
+
207
+ - **`context: string[]` on the variable.** Rejected -- see "Why a single
208
+ string, not an array" above.
209
+ - **A built-in `"shared"` sentinel value.** Rejected -- redundant with
210
+ `context: undefined`, and it would imply env-cap has an opinion about
211
+ what "shared" means, which contradicts the whole premise of contexts
212
+ being entirely application-defined.
213
+ - **Hierarchical or wildcard contexts** (e.g. `"server.production"`
214
+ matching an active `"server"`). Rejected -- the point of this feature is
215
+ staying generic; a hierarchy would require env-cap to understand context
216
+ semantics it has no business understanding. See Formal Invariant 1.
217
+ - **A callback (`shouldInclude`/`when`) instead of a declarative field.**
218
+ Rejected -- breaks static analyzability (ADR 0002); see above.
219
+ - **Automatic context detection** (inspecting `window`, `NODE_ENV`, a
220
+ bundler `define`, etc.). Rejected for the same reasons ADR 0004 already
221
+ rejected automatic client/server detection: framework-dependent,
222
+ unreliable across deployment targets, and it would put detection logic
223
+ in the smallest, most security-sensitive part of the package. See
224
+ Formal Invariant 2.
225
+ - **Using `context` for access control** (e.g. `context: "admin"` implying
226
+ only "admin" code paths may read a variable). Rejected outright --
227
+ contexts govern validation participation, never access. See Formal
228
+ Invariant 5. Anyone with code access to a contract in an active context
229
+ can read it, same as any other variable.
230
+ - **A scaffolded `validateEnv()` call written directly into the generated
231
+ manifest file, preserved verbatim across regenerations.** Considered (and
232
+ briefly drafted) as the mechanism for surfacing discovered contexts to
233
+ application code: on first generation, write a trailing `await
234
+ validateEnv({ manifest, values: process.env, activeContexts: [...] })`
235
+ call the developer could hand-edit; on regeneration, parse the existing
236
+ file and leave everything below the imports untouched so those edits
237
+ survive. Rejected for two concrete reasons: (1) `renderManifest()` is a
238
+ pure function of `(contracts, outputFile)`, called both to write the
239
+ real file and, in `--check` mode (`check-artifacts.ts`), to compute
240
+ "what a fresh run would produce" for a byte-for-byte drift comparison --
241
+ a preserved region breaks that comparison without new machinery to know
242
+ which part is exempt. (2) The preserved/regenerated boundary was
243
+ ambiguous in a way that mattered: if `export const manifest = [...]`
244
+ itself fell on the preserved side, adding or removing an `env.schema.ts`
245
+ file would stop automatically updating the manifest array, breaking the
246
+ tool's core auto-discovery guarantee. The `activeContexts` export
247
+ actually shipped avoids both problems -- it's plain, always-fresh,
248
+ fully-regenerated data, exactly like `manifest` itself, with no
249
+ user-owned region to parse or preserve.
250
+ - **A `runtime: "server" | "client"` option on `createEnv()`.** This is
251
+ the alternative ADR 0004 already rejected, not a new one -- noted here
252
+ only to be explicit about the difference: that alternative was a closed
253
+ enum implying a bundling boundary the runtime can't actually enforce.
254
+ `context` is an open, user-supplied string that only gates validation
255
+ participation and makes no claim about bundling at all (see Formal
256
+ Invariant 6).
257
+
258
+ ## Relationship to ADR 0004
259
+
260
+ ADR 0004's decision -- no `/client`/`/server` package split, separate
261
+ discovery/manifests as the real module boundary -- is unchanged by this
262
+ ADR and remains the mechanism for keeping server-only source out of
263
+ client-bound code. Validation contexts are a complementary, orthogonal
264
+ feature: useful _within_ a manifest that's already scoped to one
265
+ deployment target but has more than one simultaneously-relevant facet (an
266
+ environment tier, a secondary entry point), not a substitute for scoping
267
+ that manifest correctly in the first place.