@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,95 @@
1
+ # 0042: `env-cap init` is a filesystem-only scaffolder, never a project configurator
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented: `src/cli/init.ts` (`runInitCommand`), dispatched from
6
+ `src/cli/index.ts`'s `main()` on `init` as the first positional token;
7
+ covered by `test/cli/init.test.ts` and `test/cli/main.test.ts`.
8
+
9
+ ## Context
10
+
11
+ The CLI (`src/cli/index.ts`) was a single flat flag-parser — `--location`,
12
+ `--docs`, `--check`, `--json`, etc. — with no subcommand concept. A new
13
+ adopter's first step ("write an `env.schema.ts`, then generate the
14
+ manifest") was entirely manual, described only in the README.
15
+
16
+ `repo-contract` added an `init` subcommand for the same reason (its ADR
17
+ 0004, 2026-09-09 amendment). env-cap should offer the same low-friction
18
+ entry point, but env-cap's own invariants constrain what `init` may do:
19
+ static analysis only, never execution (ADR 0002); library surfaces do not
20
+ acquire ambient capabilities the caller didn't grant (ADR 0040).
21
+
22
+ ## Decision
23
+
24
+ ### Grammar
25
+
26
+ `init` as the **first positional token** routes to the scaffolder; every
27
+ existing flag-based invocation is untouched (no flag is reinterpreted as a
28
+ subcommand, `--help` alone still prints the generator help). `env-cap init`
29
+ takes no arguments except `--help`.
30
+
31
+ ### `init` scaffolds, it does not configure
32
+
33
+ `init` writes exactly two new files:
34
+
35
+ - `<src>/env.schema.ts` — a starter capability contract (`createEnv` +
36
+ `documentEnv`, one placeholder variable). `src/` if that directory
37
+ already exists, project root otherwise.
38
+ - `scripts/generate-env.mjs` — a runnable artifact generator calling
39
+ `generateEnvArtifacts()` with the `@maverickcer/env-cap/node`
40
+ filesystem adapter.
41
+
42
+ It is **filesystem-only and non-executing**: no subprocess, no
43
+ package-manager call, no `package.json` mutation, no artifact
44
+ regeneration, no ambient-environment read, no network. It reads the
45
+ consumer's `package.json` only to confirm it's a project and to choose
46
+ `src/` vs. root. Writes use exclusive-create (`{ flag: "wx" }`) — an
47
+ existing file is reported as skipped, never overwritten — with parent
48
+ directories created first. Any preflight failure (no `package.json`,
49
+ malformed `package.json`, a scaffold target blocked by a wrong-typed
50
+ entry) means zero writes.
51
+
52
+ Unlike `repo-contract`'s `init`, env-cap's does **not** patch a
53
+ `package.json` script. `repo-contract`'s `npm run contract` has to exist
54
+ because its git hooks call it; env-cap's CLI already works standalone via
55
+ `npx env-cap`, so there is nothing to wire. Anything the documented
56
+ workflow still needs — running the generator, wiring `validateEnv()` into
57
+ startup — is printed as a `Next:` step, never performed.
58
+
59
+ ### Tier
60
+
61
+ Experimental (VERSIONING.md). The scaffold's exact file set and template
62
+ contents may change in a minor/patch release; what it has already written
63
+ into a consumer's repo is theirs and unaffected.
64
+
65
+ ## Consequences
66
+
67
+ - A new adopter runs `npx env-cap init`, gets a discoverable contract and a
68
+ generator, and expands from there — the README's manual walkthrough
69
+ becomes the "understand what init did" reference, not the required first
70
+ path.
71
+ - `src/cli/init.ts` uses `node:fs` directly. That's consistent with ADR
72
+ 0040's carve-out (`src/cli/**` is executable-context source) and the
73
+ file is bundled into the `bin` target, so the `AmbientCapabilities` check's
74
+ tarball scan exempts it exactly as it does `src/cli/index.ts`.
75
+ - The scaffolded templates are plain string constants in `init.ts`. If the
76
+ public `createEnv`/`documentEnv`/`generateEnvArtifacts` API changes
77
+ shape, the templates need updating too — a test that actually type-checks
78
+ or runs the scaffolded output would catch drift, and is a reasonable
79
+ future addition.
80
+
81
+ ## Alternatives considered
82
+
83
+ - **Patch `package.json` to add a `generate:env` script**, like
84
+ repo-contract. Rejected — env-cap's CLI is directly runnable via `npx`,
85
+ so the script is a convenience the adopter can add in five seconds, and
86
+ mutating `package.json` widens `init`'s blast radius for no real gain.
87
+ - **Scaffold only the schema file, no generator script.** Considered — the
88
+ CLI alone (`npx env-cap --location ...`) covers generation. Kept the
89
+ generator script anyway: it documents the full option set (docs,
90
+ ownership, `.env.example`) in a form the adopter edits, which a bare CLI
91
+ invocation in `Next:` output doesn't.
92
+ - **An interactive prompt flow** (pick a directory, name the capability).
93
+ Rejected — `init` must be safely runnable inside a CI step or a
94
+ higher-level generator; non-interactive and deterministic is the
95
+ constraint.
@@ -0,0 +1,71 @@
1
+ # 0043: env-cap's path-alias resolver is relocated into `src/build/resolution/` and duplicated, not extracted to a shared package
2
+
3
+ ## Status
4
+
5
+ Accepted. Filed in both `env-cap` and `data-cap`. Implemented in env-cap by
6
+ relocating `resolve-import.ts`, `resolve-tsconfig-paths.ts`,
7
+ `resolve-package-schema.ts`, `resolve-within-root.ts` (and their tests)
8
+ into `src/build/resolution/`, with zero change to `@maverickcer/env-cap/
9
+ build`'s public export surface, verified via `npm run verify` and a
10
+ git-stash export-list diff before/after; implemented in data-cap by
11
+ copying that folder verbatim as the seed for `src/build/resolution/`.
12
+
13
+ **Amended (internal-package-contract managed copies).** The decision to avoid a shared _runtime
14
+ dependency_ stands: neither package imports a shared package at runtime. What changed is that code known to
15
+ be identical is no longer maintained twice. internal-package-contract owns the canonical source of the
16
+ path-alias resolver (`resolve-tsconfig-paths`), the build filesystem types, the TypeScript loader and its
17
+ error, `glob`, `displayPath` and the generated-file banner, and each package carries a byte-identical copy in
18
+ `src/_ipc/`, kept current by `internal-package-contract sync` and checked by the `ManagedFiles` check. The
19
+ package's own `src/build/**` files are thin wrappers that bind the package's name. The other resolution
20
+ modules (`resolve-import`, `resolve-within-root`, `resolve-package-schema`) stay independent, because their
21
+ result shapes differ between the two packages.
22
+
23
+ ## Context
24
+
25
+ data-cap's build tooling needs exactly the same specifier-resolution
26
+ primitives env-cap's already has — relative-import resolution, tsconfig
27
+ path-alias resolution (ADR 0032), cross-package schema resolution — and
28
+ the underlying logic is already specifier-target-agnostic (it resolves _a
29
+ specifier_ to _a file_; it has no opinion about what kind of schema lives
30
+ at that file). Two live options existed: extract a shared package both
31
+ repos depend on, or duplicate the logic into data-cap directly.
32
+
33
+ ## Decision
34
+
35
+ The logic is duplicated, not extracted into a shared package. As a
36
+ prerequisite, env-cap's own `src/build/resolve-*.ts` files were first
37
+ relocated (an internal reorg only — same public exports, same behavior,
38
+ same tests just re-pathed) into their own `src/build/resolution/`
39
+ subfolder, to make the boundary of what would be copied explicit and
40
+ self-contained. That folder was then copied verbatim into `data-cap/src/
41
+ build/resolution/` as data-cap's own starting point; data-cap's build
42
+ tooling adapts only the call sites (what gets linked), never the
43
+ resolution primitives themselves.
44
+
45
+ ## Consequences
46
+
47
+ - Each package's `resolution/` folder can evolve independently once
48
+ copied — a data-cap-specific fix or optimization never risks an
49
+ unintended behavior change in env-cap, and vice versa.
50
+ - Neither package takes on a third, shared-package dependency (with its
51
+ own versioning, release, and compatibility surface) for logic that,
52
+ while duplicated, is small enough (a handful of files) that the
53
+ duplication cost is genuinely lower than a shared package's overhead.
54
+ - The relocation-first step means both repos now describe this logic's
55
+ boundary identically (`src/build/resolution/`), so a future contributor
56
+ moving between the two codebases finds it in the same place either way.
57
+
58
+ ## Alternatives considered
59
+
60
+ - **Extracting a shared internal package** (e.g.
61
+ `@maverickcer/module-resolution`) both repos depend on. Rejected —
62
+ explicitly, by the user's own scoping decision: "the logic is fairly
63
+ straightforward although it is split across many files and this isn't a
64
+ large enough issue for there to be a generic widely used module resolver
65
+ package." A shared package's release/versioning overhead wasn't judged
66
+ worth it for logic this contained.
67
+ - **Leaving env-cap's resolver in `src/build/` unrelocated, copying files
68
+ from scattered locations.** Rejected — the relocation makes the
69
+ copied boundary explicit and self-contained for both the copy itself and
70
+ any future re-sync, rather than requiring a contributor to re-derive
71
+ "which files, exactly" every time.
@@ -0,0 +1,88 @@
1
+ # 0044: Bare `--strict` escalates every warning family, not just manifest compatibility
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/cli/index.ts` (`artifactOptions`,
6
+ `groupEscalates`); covered by `test/cli/index.test.ts`. Breaking change to
7
+ `--strict`'s own behavior, not to any exported type shape.
8
+
9
+ ## Context
10
+
11
+ Before this decision, `--strict` escalated only the manifest pass's
12
+ compatibility findings (ADR 0009's provable exclusive-group/compatibility
13
+ errors) to a hard error; documentation and ownership warnings needed their
14
+ own separate `--strict-docs`/`--strict-ownership` flags to escalate at all
15
+ — `--strict` alone left them at `warn`. This was a deliberate, documented
16
+ scoping (GUIDE.md/`--help` both said so explicitly), not an oversight.
17
+
18
+ A cross-package parity audit ahead of either package's `1.0` release
19
+ compared the two siblings'
20
+ identically-named `--strict`/`--strict-docs`/`--strict-ownership` flags and
21
+ found they mean different things: data-cap's bare `--strict` already
22
+ escalates every pass (docs, ownership, and its own flow-family findings)
23
+ via an OR across `--strict`/the group-specific flag
24
+ (`src/build/generate-data-artifacts.ts`'s `groupEscalates`). Same flag
25
+ name, same lineage, materially different scope — a CI script written
26
+ against one tool's `--strict` and copied to the other silently gets
27
+ different enforcement. Worse, "strict" without qualification naturally
28
+ reads as "maximum strictness"; a user who ran bare `--strict` in CI
29
+ expecting full escalation and got only the compatibility family was
30
+ carrying a false sense of safety about documentation/ownership drift —
31
+ exactly the class of problem an audit tool exists to prevent, not
32
+ reproduce in its own flag semantics.
33
+
34
+ ## Decision
35
+
36
+ Bare `--strict` now escalates all three provable-error families at once —
37
+ compatibility, documentation, and ownership — equivalent to passing
38
+ `--strict --strict-docs --strict-ownership` together. `--strict-docs`/
39
+ `--strict-ownership` are unchanged: still independently settable, still
40
+ escalate their own family alone when passed without bare `--strict`.
41
+
42
+ Mechanically: `parseArgs` keeps `strict`/`strictDocs`/`strictOwnership` as
43
+ three independent booleans (unchanged — `--strict` still never sets the
44
+ other two flags itself). The OR happens once, at read time, in
45
+ `artifactOptions`'s new `groupEscalates(strict, specificFlag)` helper —
46
+ `onUndocumented`/`onOwnershipIssue` both now read
47
+ `groupEscalates(args.strict, args.strictDocs/args.strictOwnership) ?
48
+ "throw" : "warn"`, matching data-cap's own `groupEscalates`
49
+ (`src/build/generate-data-artifacts.ts`) exactly in name and shape.
50
+
51
+ ## Consequences
52
+
53
+ - **Breaking.** Any CI pipeline currently running bare `--strict` alone,
54
+ relying on it _not_ escalating documentation/ownership warnings, will
55
+ start failing on pre-existing warnings in those families the next time
56
+ it runs. This is a real, deliberate behavior change, not a bug fix wearing
57
+ a disguise — anyone affected needs to either fix the newly-escalated
58
+ findings or drop back to `--strict-docs`/`--strict-ownership` individually
59
+ (or neither) to keep today's narrower gate.
60
+ - `--strict`'s and data-cap's `--strict`'s meaning are now the same shape
61
+ (an all-families shorthand, with independent per-family flags underneath)
62
+ for anyone using both tools.
63
+ - `GUIDE.md`, `ADOPTION.md`, and `--help`'s own `--strict` description are
64
+ updated to describe the new scope; the GitHub Action's own pass/fail
65
+ section is updated too, since it previously singled out compatibility as
66
+ "the one provable, manifest-pass error category."
67
+
68
+ ## Alternatives considered
69
+
70
+ - **Narrow data-cap's `--strict` to match env-cap's old scope instead.**
71
+ Rejected — data-cap's broader "escalate everything" semantics matches
72
+ what "strict" naturally reads as, and narrowing an already-shipped
73
+ strictness flag is the more dangerous direction: an existing data-cap CI
74
+ gate relying on `--strict` catching docs/ownership drift would silently
75
+ lose that coverage. Widening env-cap's `--strict` is the safer kind of
76
+ breaking change for a strictness flag — previously-passing CI newly
77
+ failing on a real, pre-existing problem it should have caught, never the
78
+ reverse.
79
+ - **Leave the divergence undocumented as an intentional design
80
+ difference.** Rejected — there was no actual domain reason for env-cap's
81
+ narrower scope; it was just how the flag grew one family at a time before
82
+ `--strict-docs`/`--strict-ownership` existed, never revisited once they
83
+ did.
84
+ - **A fourth, explicit `--strict-all` flag, leaving bare `--strict` as
85
+ compatibility-only.** Rejected — adds a flag name to remember for no
86
+ real benefit over just widening `--strict` itself, and still leaves the
87
+ cross-package naming mismatch (data-cap has no `--strict-all`) unresolved
88
+ for the "familiar experience switching tools" goal this change exists for.
@@ -0,0 +1,103 @@
1
+ # 0045: Promote every remaining Experimental surface to Stable
2
+
3
+ ## Status
4
+
5
+ Accepted. Moves the entire Experimental-tier bullet list in `VERSIONING.md`
6
+ into Stable, leaving the Experimental section empty. Removes every
7
+ `**Experimental**`/`Experimental, see ADR NNNN` doc-comment and CLI
8
+ help-text marker for the promoted surfaces across `src/build/generate-manifest.ts`,
9
+ `generate-documentation.ts`, `generate-evidence.ts`, `generate-usage.ts`,
10
+ `generate-env-artifacts.ts`, `index.ts`, `resolution/resolve-tsconfig-paths.ts`,
11
+ `resolution/resolve-package-schema.ts`, and `src/cli/index.ts`'s help text;
12
+ updates the corresponding prose in `README.md`, `GUIDE.md`, `SECURITY.md`,
13
+ and `ADOPTION.md`.
14
+
15
+ ## Context
16
+
17
+ `VERSIONING.md`'s own Experimental-tier definition states the graduation
18
+ criterion directly: "Once a feature has been through at least one real
19
+ feedback cycle without a need to break it... it becomes Stable." Applying
20
+ that criterion to each currently-Experimental surface:
21
+
22
+ - **`packages`/`tsconfig` options** (ADR 0014/ADR 0023): the first surfaces
23
+ to ship this way, in real use the longest, with no reported need to
24
+ change either option's shape.
25
+ - **The lower-level `./build` primitives** (`discoverSchemaFiles`,
26
+ `linkFiles`, `parseSchemaFile`, `renderManifest`, `renderDocs`,
27
+ `detectCompatibilityIssues`, `detectExclusiveGroupIssues`): justified for
28
+ real external use (custom CI scripts, bundler plugins) since their
29
+ introduction, with no reported need to change their signatures.
30
+ - **`generateEvidenceModel`/`getEvidenceModel`/`computeSourceFingerprint`/
31
+ `renderUsageReport`**: each has shipped with its current contract since
32
+ introduction; `generateEvidenceModel`'s "every finding becomes a
33
+ `Finding`, never a throw" behavior is explicitly its permanent, intended
34
+ shape (see ADR 0031), not a temporary gap this promotion needed to close.
35
+ - **The `init` CLI subcommand** (ADR 0042): its scaffolded file set and
36
+ template contents have not needed to change since introduction.
37
+ - **`@maverickcer/env-cap/evidence`** (`defineEvidenceProjection`, `EvidenceModel`) and
38
+ **the persisted evidence artifact** format: see the caveat below --
39
+ promoted along with everything else per this decision's scope, but with a
40
+ real, named exception to the "no reported need to change" pattern the
41
+ other promotions share.
42
+
43
+ This package is laser-focused on one core benefit -- environment-variable
44
+ contracts that are documented, owned, and validated by construction -- and
45
+ every mechanism that ships as part of it is meant to be depended on with
46
+ confidence, not held at arm's length behind a tier that exists for genuine
47
+ uncertainty that no longer applies.
48
+
49
+ ## Decision
50
+
51
+ Promote all of it to Stable in one pass. The Experimental tier itself stays
52
+ defined in `VERSIONING.md` -- it remains the right mechanism for a
53
+ genuinely new, unproven future surface -- it is just empty right now,
54
+ honestly, rather than holding onto a designation that no longer describes
55
+ something true for these APIs.
56
+
57
+ **Named caveat, not silently dropped:** `VERSIONING.md`'s prior text for
58
+ `@maverickcer/env-cap/evidence` said real projection authorship "is likely to surface a
59
+ better shape for `EvidenceProjectionResult.sources` in particular
60
+ (currently flat `EvidenceModel` field-path strings, not yet resolved into
61
+ structured `EvidenceReference`s -- see ADR 0032's Consequences)." That is a
62
+ specific, acknowledged, _unresolved_ design question about the current
63
+ shape being probably wrong in one particular spot -- not merely "hasn't had
64
+ time to prove itself yet," which is the graduation story every other
65
+ surface in this ADR has. Promoting it anyway is a deliberate choice to
66
+ apply one consistent policy fleet-wide rather than carve out an exception,
67
+ made with that specific risk stated plainly here rather than folded
68
+ silently into a blanket "everything's fine now" promotion. A future
69
+ `sources` shape change, if `EvidenceReference` resolution is added, is a
70
+ real Stable-tier breaking change from this point forward -- not the
71
+ minor-may-break allowance an Experimental surface would still have had.
72
+
73
+ ## Consequences
74
+
75
+ - A breaking change to any promoted surface now requires a major version
76
+ bump (once `env-cap` reaches 1.0 -- see `VERSIONING.md`'s Pre-1.0 status
77
+ section; before that, the existing minor-may-break-Stable allowance still
78
+ applies, same as every other Stable surface).
79
+ - No runtime behavior changes anywhere in this ADR -- documentation and
80
+ compatibility-promise change only, verified by the full test suite
81
+ passing unchanged.
82
+ - `EvidenceProjectionResult.sources`'s field-path-string shape is now a
83
+ Stable commitment despite the open design question above -- see the
84
+ caveat. If that question resolves toward structured `EvidenceReference`s
85
+ later, it ships as a major (or, pre-1.0, an explicitly-flagged breaking
86
+ minor per existing convention), not a quiet Experimental-tier adjustment.
87
+
88
+ ## Alternatives considered
89
+
90
+ - **Promote everything except `@maverickcer/env-cap/evidence`/the evidence artifact
91
+ format, leaving those two Experimental until the `sources` question
92
+ resolves.** This is the technically more conservative option, and was
93
+ seriously considered given the caveat above is a real, specific,
94
+ unresolved concern rather than a generic "needs more time." Not taken for
95
+ this pass because the fleet-wide decision this ADR implements is to carry
96
+ no Experimental-tier surface at all; the caveat is recorded here precisely
97
+ so this tradeoff is visible and reversible (a future ADR can re-introduce
98
+ an Experimental designation for `sources` specifically if the shape
99
+ question surfaces a real need to break it before 1.0).
100
+ - **Promote piecemeal, one ADR-reviewed feedback cycle at a time.**
101
+ Rejected for the surfaces with no open design question -- they already
102
+ independently satisfy the graduation criterion, so gating them on
103
+ separate future ADRs would just delay an already-justified decision.
@@ -0,0 +1,177 @@
1
+ # 0046: The CLI surface is restricted to flags with a verified real consumer
2
+
3
+ ## Status
4
+
5
+ Accepted. Removes `--docs`, `--ownership`, `--env-example`, and
6
+ `--env-example-on-existing` from `src/cli/index.ts` (`ParsedArgs`,
7
+ `VALUE_FLAGS`, `helpText()`, the "at least one of ..." guard, and every
8
+ CLI-only rendering path that only existed to format their output --
9
+ `printDocsSummary()`, `printUsageSummary()`, and the corresponding terms in
10
+ `runGenerateMode()`'s warning-count banner). `--expiring-within-days` is
11
+ removed too, as a direct structural consequence (see Context). Covered by
12
+ `test/cli/index.test.ts` and `test/cli/main.test.ts`.
13
+
14
+ `computeDocumentation`/`writeDocumentation`/`computeUsage`/`writeUsageReport`
15
+ (`src/build/generate-documentation.ts`, `src/build/generate-usage.ts`), and
16
+ the higher-level orchestrators `generateDocumentation`/`generateUsageReport`/
17
+ `generateEnvArtifacts`/`checkEnvArtifacts` that compose them, are **not**
18
+ changed by this decision and remain fully exported from `@maverickcer/env-cap/build`,
19
+ Stable per ADR 0045. Nothing about the library surface shrank -- only what
20
+ the packaged CLI binary can trigger by itself.
21
+
22
+ ## Context
23
+
24
+ `env-cap`'s CLI (`src/cli/index.ts`) grew flags for every artifact the
25
+ library could produce, on the assumption that "the library can generate it"
26
+ and "the CLI should have a flag for it" were the same decision. They aren't.
27
+ Auditing the CLI's actual flag set against what each flag's output is
28
+ _for_ found two different categories, previously flattened into one:
29
+
30
+ - **Flags whose output something else in a real project actually reads.**
31
+ `--location` writes the generated manifest `.ts` file that application
32
+ code `import`s and passes to `validateEnv()` (see
33
+ `examples/team-service/src/startup.ts`, `examples/nextjs-app`'s
34
+ `src/env.ts`) -- a real, provable runtime dependency. `--evidence` writes
35
+ the persisted `EvidenceModel` artifact that is itself this package's
36
+ reporting contract (ADR 0038: "always computed, always real" -- Finding
37
+ Model, evidence projections, and CI drift-guards all key off this one
38
+ file). `--json`/`--check` are inherent to the tool's own contract, not
39
+ outputs of a particular pass (ADR 0013, ADR 0016).
40
+ - **Flags whose output nothing in a real project reads at runtime, or
41
+ checks programmatically, at all.** `--docs` (the rich Markdown catalog)
42
+ and `--ownership` (the dependency & ownership report) are purely
43
+ human-facing documentation. Auditing every example in this repo
44
+ (`examples/application`, `examples/team-service`, `examples/nextjs-app`,
45
+ `examples/enterprise-platform`) found no `import` of `docs/ENVIRONMENT.md`
46
+ or `docs/OWNERSHIP.md` anywhere, and no test asserting on their content
47
+ except as committed, golden, human-readable output. `--env-example` turned
48
+ out to be structurally _part of_ the docs pass, not independent of it --
49
+ `writeDocumentation()`'s signature requires a `docsPath: string` (not
50
+ optional) to write an `.env.example` at all, and the CLI's own pre-existing
51
+ help text already said as much ("`--env-example <path>` ... only
52
+ meaningful alongside `--docs`"). Once `--docs` is gone, `--env-example`
53
+ has no remaining CLI path to reach `writeDocumentation()` through, so it
54
+ was removed alongside it rather than left as a flag that silently does
55
+ nothing. `--expiring-within-days` has the same structural problem one
56
+ level up: `GenerateEnvArtifactsOptions.docs.expiringWithinDays` is the
57
+ only place that value is threaded through
58
+ (`computeArtifacts()`'s `docsOptions?.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS`),
59
+ so it too had no remaining CLI path once `--docs` no longer exists to
60
+ carry it.
61
+
62
+ This distinction matters for a stronger reason than tidiness: every CLI flag
63
+ is a compatibility surface someone can build a CI pipeline against (ADR
64
+ 0044's own `--strict` audit made exactly this point about flag semantics
65
+ drifting from what a reasonable user expects). A flag whose only job is
66
+ "write a file nothing else reads" earns its place by being _useful_, not by
67
+ being _possible_ -- and it was already possible without the flag: every
68
+ generator function it called was, and remains, a plain exported function
69
+ from `@maverickcer/env-cap/build`. Keeping `--docs`/`--ownership` in the CLI while their
70
+ only real consumers turned out to be humans reading committed Markdown, not
71
+ other code or a CI drift check with independent value, meant the CLI's
72
+ surface area didn't reflect what the tool's flags were actually _for_.
73
+
74
+ A secondary, mechanical reason forced the same conclusion from a different
75
+ angle: once `--docs`/`--ownership` are removed from `ParsedArgs`,
76
+ `artifactOptions()` can never again set `GenerateEnvArtifactsOptions.docs`/
77
+ `.usage` from a real CLI invocation, which makes `result.docs`/`result.usage`
78
+ permanently `undefined` on every real `runGenerateMode()` call. Under this
79
+ repo's zero-tolerance Mutation gate (`npm run contract`), the CLI's own
80
+ `printDocsSummary()`/`printUsageSummary()` functions and their
81
+ `if (result.docs)`/`if (result.usage)` call sites would then be
82
+ permanently unreachable dead code -- no real CLI-level test could construct
83
+ a state where the removed flag's summary-printing branch is taken. Rather
84
+ than leave dead branches a mutation-testing gate would rightly flag,
85
+ they were removed along with the flags that used to reach them.
86
+
87
+ ## Decision
88
+
89
+ The `env-cap` CLI's flag set is restricted to flags with a verified real
90
+ runtime consumer (`--location`), or that are inherent to the tool's own
91
+ evidence/reporting contract (`--evidence`, `--json`, `--check`), plus the
92
+ flags that scope/configure those (`--root`, `--include`, `--exclude`,
93
+ `--package`, `--tsconfig`/`--no-tsconfig`, `--strict`/`--strict-docs`/
94
+ `--strict-ownership`, `--help`). `--strict-docs`/`--strict-ownership`
95
+ survive this cut even though they're documentation/ownership-scoped,
96
+ because they don't write a docs/ownership _artifact_ at all -- they
97
+ escalate Finding Model's always-computed documentation/ownership warnings
98
+ (ADR 0038) into a blocking error on the manifest/evidence write path,
99
+ independent of whether a docs/ownership file is ever produced (confirmed by
100
+ existing behavior: bare `--strict --location` already escalated
101
+ documentation/ownership findings before this change, per ADR 0044).
102
+
103
+ Flags with no verified runtime consumer -- `--docs`, `--ownership`,
104
+ `--env-example`, `--env-example-on-existing`, `--expiring-within-days` --
105
+ move to application-level code: a project that wants
106
+ `docs/ENVIRONMENT.md`/`docs/OWNERSHIP.md`/`.env.example` now calls
107
+ `generateDocumentation()`/`generateUsageReport()` (or the lower-level
108
+ `computeDocumentation`/`writeDocumentation`/`computeUsage`/
109
+ `writeUsageReport`, or `checkEnvArtifacts()` for a `--check`-equivalent
110
+ drift guard) directly from `@maverickcer/env-cap/build` in its own build script, exactly
111
+ as it would for any other custom reporting need this package doesn't build
112
+ in (see ADR 0010's precedent: engine internals stay private until a
113
+ primitive earns public status through real external use; these four
114
+ orchestrators already have that status, per ADR 0045). Every example this
115
+ repo ships that used the removed flags (`examples/application`,
116
+ `examples/team-service`, `examples/nextjs-app`) now carries a
117
+ `scripts/generate-docs/{run.ts,check.ts}` pair doing exactly this --
118
+ `examples/enterprise-platform` already had an equivalent hand-written
119
+ script (`scripts/generate-manifest.mjs`) calling `generateEnvArtifacts()`
120
+ directly with `docs`/`usage` options, predating this decision, which only
121
+ needed its `check` script updated the same way (a new
122
+ `scripts/check-artifacts.mjs`, calling the now-CLI-unreachable
123
+ `checkEnvArtifacts()` directly).
124
+
125
+ ## Consequences
126
+
127
+ - **Breaking, but pre-1.0 minor per this repo's convention.** Any script
128
+ invoking `env-cap --docs ...`/`--ownership ...`/`--env-example ...`/
129
+ `--env-example-on-existing ...`/`--expiring-within-days ...` now fails
130
+ with `Unknown argument: --docs` (etc.) instead of generating output. The
131
+ fix is mechanical: call the equivalent `@maverickcer/env-cap/build` function directly
132
+ from a small script, following the pattern in any of this repo's own
133
+ `examples/*/scripts/generate-docs/` directories.
134
+ - `generateEnvArtifacts()`'s own `docs`/`usage` options (`GenerateEnvArtifactsOptions`)
135
+ are completely unaffected -- they remain a fully supported part of that
136
+ Stable, exported orchestrator's public contract for any caller that
137
+ supplies them directly (not through the CLI). The CLI itself simply never
138
+ populates them anymore.
139
+ - The CLI's `--json` envelope (`JsonRequestedPasses.docs`/`.usage`) keeps
140
+ both fields, unchanged in shape -- `requestedPasses()` now always reports
141
+ them `false` from the CLI, since neither pass can be requested through it
142
+ anymore, but the envelope's schema itself (and `JSON_SCHEMA_VERSION`)
143
+ didn't need to change, since no field was removed or reinterpreted.
144
+ - `docs/ENVIRONMENT.md`'s/`docs/OWNERSHIP.md`'s generated byline named the removed CLI flags
145
+ (``_Produced by `env-cap --docs`._``/``_Produced by `env-cap --ownership`._``), which was
146
+ inaccurate for every example generating these through application code. That was left for a
147
+ focused follow-up, because both renderers are shared by every consumer of
148
+ `@maverickcer/env-cap/build` and correcting the byline is a golden-fixture-wide change. _Amended:
149
+ the follow-up is done. The shared renderers now state the build function that produced the
150
+ file (`generateDocumentation()` in `src/build/docs.ts`, `generateUsageReport()` in
151
+ `src/build/usage-report.ts`), and neither renders a CLI flag._
152
+
153
+ ## Alternatives considered
154
+
155
+ - **Keep `--docs`/`--ownership` in the CLI regardless of runtime
156
+ consumption, since "more flags" costs nothing on its own.** Rejected --
157
+ it costs exactly what this ADR's Context section describes: dead,
158
+ mutation-flagged branches in the CLI's own rendering code once nothing
159
+ can reach them, and a CLI surface that no longer reflects a verified
160
+ reason to exist for each flag, which is the actual audit this change
161
+ applies.
162
+ - **Keep `--env-example`/`--expiring-within-days` independently reachable
163
+ by restructuring `writeDocumentation()`/`computeArtifacts()` so they no
164
+ longer require the docs pass.** Rejected for this pass -- both are
165
+ genuinely, structurally nested under the docs pass in the current library
166
+ design (`writeDocumentation()`'s `docsPath` parameter is not optional;
167
+ `expiringWithinDays` lives only on `GenerateEnvArtifactsOptions.docs`),
168
+ and restructuring either is a library-shape change with its own blast
169
+ radius across every existing caller -- out of scope for a CLI-surface
170
+ change that was explicitly scoped to keep the library "fully available,
171
+ unchanged."
172
+ - **Cite ADR 0001 (runtime/`documentEnv` separation) as this decision's
173
+ direct precedent.** Considered, since both decisions draw a line between
174
+ "runtime-relevant" and "documentation-only" concerns. Not treated as a
175
+ full precedent, since ADR 0001 is about the _authoring_ API
176
+ (`createEnv`/`documentEnv`), not the CLI's own flag surface -- referenced
177
+ here as related reasoning, not superseded or extended.
@@ -0,0 +1,30 @@
1
+ # 0047: Supported toolchain is Node 22+ and TypeScript 5 or 6
2
+
3
+ ## Status
4
+
5
+ Accepted. The TypeScript 7 paragraph is superseded by
6
+ [ADR 0049](0049-typescript-7-scanner-uses-a-bundled-typescript-6.md).
7
+
8
+ ## Context
9
+
10
+ Node 20 reached end-of-life on 2026-04-30, so advertising it would commit the package to a runtime
11
+ nobody patches. Separately, the build-time scanner (`src/build/parse.ts`, `scan-dependencies.ts`)
12
+ uses TypeScript's classic compiler API (`createSourceFile`). TypeScript 6 still has it; TypeScript 7
13
+ moved the syntax-tree API to `typescript/unstable/*`, and the optional peer `^5.0.0` also made
14
+ `npm i typescript@latest @maverickcer/env-cap` fail with `ERESOLVE`.
15
+
16
+ ## Decision
17
+
18
+ - `engines.node` is `>=22.0.0`; `@types/node` is `^22`; bundles for Node target `node22`; CI tests 22
19
+ and 24 (26 non-blocking).
20
+ - The optional `typescript` peer is `^5.0.0 || ^6.0.0`.
21
+ - TypeScript 7 is unsupported for the build step. Migrating to `typescript/unstable/*` is deferred
22
+ until that API is stable. `assertCompilerApi` makes the scanner fail with a message that names
23
+ the installed version and the workaround (install `typescript@6` for the build step) rather than
24
+ `ts.createSourceFile is not a function`.
25
+ - The runtime entry points never import TypeScript and are unaffected.
26
+
27
+ ## Consequences
28
+
29
+ Dropping Node 20 is a breaking change, released as a pre-1.0 minor. `VERSIONING.md` lists the
30
+ toolchain as Stable.
@@ -0,0 +1,25 @@
1
+ # 0048: The ESLint plugin does not vendor `@typescript-eslint/utils`
2
+
3
+ ## Status
4
+
5
+ Accepted. Supersedes the "bundle it" note in `tsup.config.ts` and package.json's old devDependency comment.
6
+
7
+ ## Context
8
+
9
+ `./eslint-plugin` used to inline `@typescript-eslint/utils` and `@typescript-eslint/types` into its
10
+ bundle. A consumer's `npm audit`, Dependabot and Socket then could not see those packages (an
11
+ advisory never reaches users), their versions were frozen at build time, and the vendored text was
12
+ most of what supply-chain scanners flagged in the published tarball. `./eslint-plugin` is a public
13
+ subpath, so changing it after 1.0.0 would be a breaking change.
14
+
15
+ ## Decision
16
+
17
+ Keep the subpath. Declare `@typescript-eslint/utils` as an optional peer (`^8.0.0`), mark it
18
+ external in the bundle, and import `AST_NODE_TYPES` from it instead of from `@typescript-eslint/types`
19
+ (a dependency of utils). Anyone linting TypeScript with ESLint already has it through
20
+ `typescript-eslint`.
21
+
22
+ ## Consequences
23
+
24
+ A project that uses `./eslint-plugin` must have `@typescript-eslint/utils` installed. The packed
25
+ `dist/eslint-plugin/*` shrinks by about 400 KB per format.