@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,244 @@
1
+ # 0038: A real, always-computed `EvidenceModel` backs `generate`/`check`/docs; `ManifestSnapshot` retires; docs/ownership never throw
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented.
6
+
7
+ ## Context
8
+
9
+ `EvidenceModel`/`generateEvidenceModel()` (ADR 0031) existed, fully tested, schema-published — but
10
+ `computeArtifacts()`, the function `generateEnvArtifacts()`/`checkEnvArtifacts()`/the CLI's default
11
+ path all ultimately depend on, never actually built one. Every real consumer that wanted evidence,
12
+ including this repo's own `enterprise-platform` example, had to either hand-roll a duplicate
13
+ discovery pipeline or call `generateEvidenceModel()` as a second, fully independent
14
+ discover-and-link pass. `generate-evidence.ts` used to say this duplication out loud: "a real,
15
+ accepted cost." A sibling project (`data-cap`) hit and fixed the identical bug: an evidence model
16
+ that existed but was never wired into the artifact path everything else depends on. This ADR mirrors
17
+ that fix directly rather than inventing new snapshot machinery.
18
+
19
+ Two smaller, longstanding gaps rode along with the fix once the model became load-bearing:
20
+
21
+ - **`env.manifest.snapshot.json`** (ADR 0021) mechanically derived its path from the manifest's own
22
+ location (`src/generated/env.manifest.ts` → `src/generated/env.manifest.snapshot.json`), implying
23
+ it belonged to the same artifact family as the manifest. It doesn't. `env.manifest.ts` is a
24
+ **runtime build artifact** — real TypeScript, imported and executed by the running application. A
25
+ change-history/citation-baseline file is a **CI/reporting artifact** — read by `--check`, by CI
26
+ tooling, by humans; never a build input to the application itself, and tying its path to the
27
+ manifest's meant a project with no `.ts` manifest at all had no way to get one.
28
+ - `generateDocumentation()`/`generateUsageReport()` each had a throw-on-issue escape hatch
29
+ (`onUndocumented`, `onOwnershipIssue`, the CLI's `--strict-docs`/`--strict-ownership`) for
30
+ categories of finding — undocumented variables, unconsumed owned dependencies — that are not
31
+ provable defects the way ADR 0009's exclusive-group/compatibility errors are. Both are heuristic
32
+ signals with real, common false-positive causes (a webhook handler in another repo; a shell script
33
+ reading the variable; a package outside the `packages` allowlist), yet a throw treated them as hard
34
+ failures.
35
+
36
+ ## Decision
37
+
38
+ ### `computeArtifacts()` always builds the real `EvidenceModel`
39
+
40
+ - The six canonical fact models (Contract/Dependency/Ownership/Lifecycle/Finding/Change →
41
+ `EvidenceModel`) are composed on **every** `computeArtifacts()` call, unconditionally
42
+ (`generate-env-artifacts.ts`), reusing the exact same builders `generateEvidenceModel()` calls —
43
+ not a second implementation of the same assembly. `GenerateEnvArtifactsResult.evidence:
44
+ EvidenceModel` is therefore always populated, regardless of whether `--evidence`/`options.evidence`
45
+ was requested. Free to compute (the same discovery/link pass every other requested output already
46
+ paid for, via the shared `assembleProject()`), always real, never conditionally scoped.
47
+ - **New `--evidence <path>` CLI flag / `evidence?: { location: string } | false` option** on
48
+ `GenerateEnvArtifactsOptions`, resolved via `resolveWithinRoot()` exactly like every other output
49
+ location — independent of, and unconstrained by, `manifest.location`. Requesting it needs no other
50
+ pass: `generateEnvArtifacts({ root, evidence: { location: "docs/env.evidence.json" } })` alone
51
+ succeeds and writes exactly that one file (plus its `.fingerprint` sidecar, below).
52
+ - **Default location convention is `docs/`, never `src/`** — the same reasoning that already put
53
+ `ENVIRONMENT.md`/`OWNERSHIP.md` there: this is generated-but-non-runtime content, not a build
54
+ input. Every example commits `docs/env.evidence.json`.
55
+ - **Optional, always** — nothing writes it unless `evidence.location`/`--evidence <path>` is
56
+ explicitly passed. Not an automatic side effect of requesting a manifest, unlike the old sidecar.
57
+ - `--check` gets evidence support through the **existing generic plumbing**, not a new mechanism:
58
+ `ArtifactCheckFinding["artifact"]`'s union gained `"evidence"`, and `checkEnvArtifacts()` re-renders
59
+ the evidence JSON in-memory and diffs it against disk via the same `compareTextArtifact()`/
60
+ `readIfExists()` path manifest/docs/usage already used (`check-artifacts.ts`).
61
+
62
+ ### The provenance/timestamp trap, and the parallel `change`-field trap
63
+
64
+ `EvidenceModel.provenance.generatedAt` is a live timestamp. Persisting it into `docs/env.evidence.json`
65
+ and then having `--check` re-render-and-diff the same way as every other artifact would fail on
66
+ _every single run_, even with zero real changes — the file can never be "up to date" against itself,
67
+ since a fresh render's timestamp can never equal a past write's. `normalizeEvidenceSnapshotForComparison()`
68
+ (`evidence-snapshot.ts`) blanks `provenance.generatedAt` before any comparison — used by
69
+ `check-artifacts.ts`'s `normalizeEvidenceJsonForComparison()`, by every example's golden-file
70
+ comparison (`test/support/example-runner.ts`), and by the `--json` envelope's embedded `evidence`
71
+ field (`normalizeExampleJsonOutput()`) — one normalization rule, applied at every place a persisted
72
+ or embedded copy gets compared, not three separately-maintained ones.
73
+
74
+ A second, less obvious instance of the same trap surfaced during implementation: `evidence.change`
75
+ describes "what's different from whatever snapshot was on disk the moment this run computed it." By
76
+ construction, a `--check` run's own re-derivation of `change` is **not reproducible** against the
77
+ file it's verifying — by the time `--check` recomputes, the file just written _is_ the new baseline,
78
+ so the diff naturally comes back different from (emptier than) what got persisted. This isn't drift;
79
+ it's what `change` means. `normalizeEvidenceSnapshotForComparison()` blanks `change.manifest` and
80
+ `change.renamedVariables` to a constant empty value for exactly the same reason it blanks
81
+ `generatedAt` — caught by a real test (`--check` run twice in a row with no source edits must report
82
+ clean both times), not by inspection.
83
+
84
+ ### `env.manifest.snapshot.json` retires; one evidence file replaces it
85
+
86
+ `src/build/manifest-snapshot.ts` is deleted. Its two real jobs both retarget to
87
+ `docs/env.evidence.json` (or wherever `evidence.location`/a caller's `previousSnapshotLocation`
88
+ points), fully decoupled from wherever — or whether — a `.ts` manifest is even being generated:
89
+
90
+ - **Field-level change diffing** — `diffContracts()` (`evidence-snapshot.ts`), a **generic structural
91
+ differ**, not a hand-maintained field-by-field comparison. It walks every own key of a
92
+ `ManifestContractRef`/`ManifestVariableRef` pair via `genericFieldChanges()`, skip-listing identity
93
+ fields (`file`, `exportName`, `key`) rather than special-casing every content field by name — a new
94
+ field on either shape is diffed automatically, with no matching update required in the differ
95
+ itself. `metadata` is special-cased to recurse per-key (`recordFieldChanges()`) rather than being
96
+ diffed as one opaque blob, so `metadata.<key>`-level change entries survive.
97
+ - **Dynamic-access citation content-hash baselines** (ADR 0037) —
98
+ `computeDynamicAccessAcknowledgments()`/`findDynamicAccessCitationProblems()` now read
99
+ `contentHash` off `EvidenceModel.dependency`'s own `DynamicAccessAssertion` (a field added directly
100
+ to that type, not a parallel shape) instead of a separate `ManifestSnapshotVariable.dynamicAccessSnapshots`
101
+ array.
102
+
103
+ One committed file, two consumers (`--check` staleness, and cross-run citation-freshness comparison),
104
+ not two files, and not tied to the manifest's own path. Whether a project commits
105
+ `docs/env.evidence.json` is that project's call — a missing file reads as the normal first-run state
106
+ everywhere this is read, never an error.
107
+
108
+ ### The fingerprint cache (`getEvidenceModel()`), mirroring `data-cap`'s fix
109
+
110
+ A full `generateEvidenceModel()` call pays for schema parsing, cross-file linking, the
111
+ dependency-graph AST scan, and all six model builds — expensive to pay on every single report/
112
+ projection script invocation. `evidence-cache.ts` adds:
113
+
114
+ - **`computeSourceFingerprint()`** — a SHA-256 over the raw bytes of every schema file and every
115
+ usage-scan-surface file (`**/*.ts`/`**/*.tsx`, the same broad surface ADR 0036's dynamic-access
116
+ scan already uses), plus env-cap's own installed version. Zero AST work; still pays for the
117
+ discovery/glob walk itself (fingerprinting has to know which files matter), but skips everything
118
+ after it. Deterministic — file paths are deduplicated and sorted before hashing.
119
+ - **`getEvidenceModel()`** — trusts the committed evidence artifact only when its paired
120
+ `.fingerprint` sidecar matches a freshly-computed `computeSourceFingerprint()`; never on file
121
+ presence alone, never on a timestamp (a checkout, a rebase, or a `touch` can all bump mtime with no
122
+ real content change). On any mismatch — stale fingerprint, missing/corrupt evidence file, no
123
+ sidecar at all — falls back to a real `generateEvidenceModel()` call. Never hard-fails, never
124
+ serves data that might be stale.
125
+ - **Never self-heals, never writes.** A cache miss inside `getEvidenceModel()` does not refresh the
126
+ committed artifact or its fingerprint — only the explicit write path
127
+ (`generateEnvArtifacts()`'s `evidence` option, which calls `writeEvidenceSnapshot()` +
128
+ `writeEvidenceFingerprint()` together, always in that order so the two files never describe
129
+ different moments) does that. Two independent callers hitting the same stale cache both recompute
130
+ independently; neither's recompute updates what the other reads.
131
+
132
+ **A consequence worth naming explicitly, not a bug**: because the fingerprint's scan surface is
133
+ `**/*.ts`/`**/*.tsx` across the whole project, editing _any_ TypeScript file in a project — including
134
+ a test file with no relationship to a schema or a consumer — invalidates the cache and changes the
135
+ fingerprint. This is the intended breadth (the same surface ADR 0036/0037's citation machinery needs
136
+ to stay honest about what was actually scanned), not something to narrow for convenience.
137
+
138
+ A real test bug caught this design's own edge, mirroring `data-cap`'s account of the same mistake:
139
+ `configuration-governance.test.ts`'s provenance test asserts a **freshly-generated** `generatedAt` is
140
+ `>=` a timestamp captured immediately before the call. Calling the _cache-aware_ `getEvidenceModel()`
141
+ there is wrong on its face — the whole point of that function is to skip generation (and thus skip
142
+ stamping a new `generatedAt`) when nothing changed, so asserting freshness through it is
143
+ self-contradicting, not merely flaky. Fixed by having that one test call `generateEvidenceModel()`
144
+ directly; every other test in the same file, which only wants correct _content_, keeps using
145
+ `getEvidenceModel()` for the cache's real benefit.
146
+
147
+ ### `ENVIRONMENT.md`/`OWNERSHIP.md` never throw; findings replace the escape hatch
148
+
149
+ - `onUndocumented`/`blocking` (`generate-documentation.ts`) and `onOwnershipIssue`/`blocking`
150
+ (`generate-usage.ts`) are removed outright — pre-1.0, not deprecated-and-kept. So are the CLI's
151
+ `--strict-docs`/`--strict-ownership` flags. `--strict` (manifest exclusive-group/compatibility —
152
+ ADR 0009's genuinely provable error category) is untouched; it is the one pass that still blocks.
153
+ - Documentation completeness and ownership hygiene are visible `Finding`s (`documentation`/
154
+ `ownership` families) a team can gate on in its own CI step, reading `Finding[]` off the evidence
155
+ artifact — never something env-cap enforces via a thrown error. `computeDocumentation()`/
156
+ `computeUsage()` now have exactly one throw-severity-free shape of result each, computed
157
+ unconditionally regardless of whether the corresponding pass was itself requested (Finding Model,
158
+ now part of the always-built `EvidenceModel`, needs both either way).
159
+
160
+ ### `renderDocs()` migrates to `ContractModel`; the hand-synced adapter drops
161
+
162
+ `docs.ts`'s `renderDocs()`/`renderCatalog()`/`renderDependencyGraph()` take `ContractModelContract`/
163
+ `ContractModelVariable` directly instead of `DiscoveredContract[]`, and drop the `root` param (a
164
+ `ContractModelContract.file` is already root-relative, POSIX-separated — no `relativeTo()` helper
165
+ needed at render time). This removes the need for `to-discovered-contracts.mjs`, a hand-synced,
166
+ untyped adapter the `enterprise-platform` example's `config-reference.mjs` projection used to
167
+ maintain solely to satisfy `renderDocs()`'s old signature — already flagged as a drift risk in ADR
168
+ 0036's Consequences. `config-reference.mjs` now calls `renderDocs(evidence.contract.contracts, ...)`
169
+ directly. `generate-documentation.ts`/`check-artifacts.ts` build a `ContractModelContract[]` once
170
+ (`computeDocumentation()`'s `contractModelContracts` field) and pass it to both the real write path
171
+ and the `--check` comparison, rather than each computing it separately.
172
+
173
+ `ContractModelVariable` gained a new field, `dynamicAccess: readonly string[] | undefined`, populated
174
+ in `buildContractModel()` — purely additive, no schema-version bump. `effectiveOwner()`/
175
+ `effectivePurpose()`/`effectiveLegalBasis()`/`effectiveRetentionPolicy()`/`effectiveDataResidency()`/
176
+ `effectiveAuditRequired()` (`link.ts`) were genericized to structural parameter types so one
177
+ implementation serves both `DiscoveredContract`/`DiscoveredVariable` and `ContractModelContract`/
178
+ `ContractModelVariable` shapes without duplicating the field-fallback logic. `computeExpiringEntries()`
179
+ deliberately was **not** migrated the same way — it stays on a new, narrower structural type
180
+ (`ExpiryBearingContract`, satisfied by both shapes) rather than `ContractModel`, specifically to avoid
181
+ silently changing the Stable-tier `DocumentationFindings.expiringSoon[].file` from absolute to
182
+ relative. Nothing in `docs.ts`'s own render path calls this function; migrating it would have been an
183
+ unforced breaking change to an unrelated public field.
184
+
185
+ ### Confidence signal: the caveat gets specific, and a citation-freshness column replaces a collapsed label
186
+
187
+ `OWNERSHIP.md`'s "unconsumed owned dependencies" caveat expanded from a bare "not proof of dead code"
188
+ to name the concrete cases: a separate out-of-repo service or webhook handler; non-TypeScript
189
+ consumers (a shell script, a Dockerfile, a Terraform/Kubernetes manifest); or a package whose usage
190
+ lives outside this project's own `packages` allowlist (ADR 0014).
191
+
192
+ Rather than collapsing confidence into a `high`/`low` label, `UnconsumedOwnedVariableFinding`/
193
+ `IndeterminateOwnershipFinding` gained `staleOrMissingCitations: readonly DynamicAccessCitationProblem[]`
194
+ (`usage-report.ts`), joined from `findDynamicAccessCitationProblems()`'s existing output on the
195
+ variable-identity key ADR 0037 already produces. Rendered as its own report column
196
+ (`formatStaleOrMissingCitations()`): blank is the strongest "looks genuinely unused" signal — no
197
+ developer has ever claimed dynamic access here. A non-blank cell names the exact stale/missing
198
+ citation(s) — a developer specifically claimed dynamic access once and that claim can no longer be
199
+ verified — the report shows the receipt directly rather than asking a reader to trust a label.
200
+
201
+ ## Consequences
202
+
203
+ - **Breaking (deliberate, pre-1.0, per VERSIONING.md)**: `GenerateEnvManifestResult.changes` no
204
+ longer exists — `generateEnvManifest()` itself no longer tracks change history at all; that moved
205
+ entirely to the persisted evidence artifact. Any script computing "what changed" from a bare
206
+ manifest call (e.g. `split-generators`'s fixture, which calls the standalone generators separately
207
+ rather than through `generateEnvArtifacts()`) must call `generateEvidenceModel()`/`getEvidenceModel()`
208
+ itself and read `evidence.change.manifest`.
209
+ - `src/build/manifest-snapshot.ts` is deleted; `ManifestChangeReport`/`ManifestContractRef`/etc. types
210
+ live on, retargeted, in `evidence-snapshot.ts`.
211
+ - `--strict-docs`/`--strict-ownership` are gone from the CLI; a project relying on either for CI
212
+ gating needs to switch to reading `Finding[]` off `--evidence`'s output in its own step.
213
+ - `RenderDocsOptions.undocumentedContracts`/`undocumentedVariables` (and the equivalent
214
+ `check-artifacts.ts` comparison) need root-relative `file` values now, matching `ContractModelContract`'s
215
+ convention — `generate-documentation.ts` exports `relativizeRef()` for exactly this conversion,
216
+ applied at both the real write path and the drift-check path.
217
+ - A test asserting no file under `src/runtime/` (or the isomorphic `src/evidence/`) imports evidence-
218
+ snapshot/cache machinery would be a reasonable follow-up to make the "never executed at runtime"
219
+ invariant self-verifying rather than convention-only; not added in this pass.
220
+ - Every flagship (`application/`, `team-service/`, `enterprise-platform/`) and every integration
221
+ fixture's `expected/` golden now includes `docs/env.evidence.json` + `.fingerprint`, regenerated via
222
+ `scripts/update-example-goldens.mjs`. Because the fingerprint's scan surface is project-wide
223
+ (`**/*.ts`/`**/*.tsx`), editing _any_ `.ts` file inside an example directory — including its own test
224
+ files — changes that example's fingerprint and requires re-running the golden-regeneration script,
225
+ even when the edit has nothing to do with schemas or evidence content.
226
+
227
+ ## Alternatives considered
228
+
229
+ - **Keep deriving the snapshot's path from `manifest.location`.** Rejected — ties a CI/reporting
230
+ artifact's existence to whether a project happens to also generate a runtime `.ts` manifest, which
231
+ is an unrelated decision. A project with only `--docs`/`--ownership`, no `.ts` manifest at all,
232
+ should still be able to get evidence.
233
+ - **Compare `--check`'s embedded/persisted `generatedAt` and `change` by re-deriving and accepting the
234
+ mismatch as real drift.** Rejected — this would make `--check` permanently unable to report "up to
235
+ date" for the one artifact whose entire point is proving CI can trust it; caught by a real repeated-
236
+ `--check` test, not merely reasoned about.
237
+ - **Upgrade `unconsumedOwnedVariables`/`indeterminate` findings to a collapsed `confidence: "high" |
238
+ "low"` label.** Rejected — collapses an inspectable fact (which exact citations exist, and whether
239
+ each is fresh) into a label a reader has to trust rather than verify, the same objection ADR 0036/
240
+ 0037 already raised against less-specific evidence shapes elsewhere in this codebase.
241
+ - **Migrate `computeExpiringEntries()` to `ContractModelContract` alongside everything else in
242
+ `docs.ts`.** Rejected — no caller inside `docs.ts`'s own render path needs it on that type, and doing
243
+ so would have silently flipped `DocumentationFindings.expiringSoon[].file` (Stable tier) from
244
+ absolute to relative for no benefit.
@@ -0,0 +1,160 @@
1
+ # 0039: The Usage Scanner Follows Object-Destructuring and One-Level `const` Aliasing, and Nothing Else
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/build/scan-dependencies.ts` and
6
+ `src/build/dependency-graph.ts`, orchestrated by `generateUsageReport()`
7
+ (`src/build/generate-usage.ts`). Extends ADR 0010 (the engine's fixed scope)
8
+ and ADR 0036 (position-cited findings); does not change ADR 0037
9
+ (developer-declared `dynamicAccess` citations stay a wholly separate fact).
10
+
11
+ ## Context
12
+
13
+ Before this decision, `scanFileForDependencies()` recognized exactly three
14
+ consumption shapes on a tracked contract binding `paymentsEnv`:
15
+
16
+ - `paymentsEnv.STRIPE_KEY` / `paymentsEnv["STRIPE_KEY"]` -> a `member` access
17
+ ("STRIPE_KEY is read").
18
+ - `paymentsEnv[expr]` (non-literal key) -> a `dynamic` access (the contract
19
+ has a computed access; every not-otherwise-read key on it becomes
20
+ `indeterminate`).
21
+ - Any other mention of the bare identifier -> a `reference` (contract-level
22
+ coupling only -- it counted toward "this file is a consumer" but was
23
+ discarded for per-variable status).
24
+
25
+ The `reference` bucket silently swallowed two very different situations:
26
+
27
+ 1. **Genuinely ambiguous reads this pass can't attribute to a key**:
28
+ `initialize(paymentsEnv)`, `{ ...paymentsEnv }`, `return paymentsEnv`.
29
+ 2. **Reads that a slightly smarter single-file pass CAN attribute**:
30
+ `const { STRIPE_KEY } = paymentsEnv` binds STRIPE_KEY by name; `const e =
31
+ paymentsEnv; e.STRIPE_KEY` reads it through a trivial local alias.
32
+
33
+ For (2), every declared key of a destructured or aliased contract reported as
34
+ `UNCONSUMED_OWNED_VARIABLE` -- a **false claim of certainty**: env-cap said
35
+ "no consumer found in this repository" when a consumer was right there in the
36
+ same file, just not written as `contract.KEY`. Teams that destructure their
37
+ contracts (a common style) got a uniformly wrong usage report.
38
+
39
+ The naive fix -- "trace data flow properly" -- means a `ts.Program` + type
40
+ checker, which ADR 0002 and ADR 0010 deliberately avoid: the scanner is a
41
+ fast, per-file `ts.createSourceFile()` parse with no semantic binding, and
42
+ keeping it that way is what makes it viable on a large monorepo and what
43
+ keeps its findings _provable_ rather than heuristic.
44
+
45
+ ## Decision
46
+
47
+ The scanner follows exactly two additional, purely-syntactic, single-file
48
+ shapes, and treats everything it cannot follow as an explicit `escape`
49
+ (never as silence, and never as a guess):
50
+
51
+ ### 1. Object-destructuring from a bare tracked import
52
+
53
+ `const { X, Y: y, ["Z"]: z } = paymentsEnv` records a `member` access for
54
+ each statically-knowable key (`X`, `Y`, `Z`), keyed by the **property name**,
55
+ never the local binding name. Per binding element:
56
+
57
+ - A computed key that is **not** a string literal (`{ [k]: v }`, `{ [f()]: v
58
+ }`, `{ 5: v }`) -> `escape` (`via: "computed-key"`). The key expression is
59
+ still walked for nested tracked references.
60
+ - A **nested** binding pattern (`{ Y: { Z } }`) -> `escape` (`via:
61
+ "nested-pattern"`) for that element only. Sibling plain keys still record
62
+ their `member` access.
63
+ - A **rest** element (`{ ...rest }`) -> `escape` (`via: "rest"`).
64
+
65
+ The fast path only fires when the destructuring source is a **bare
66
+ identifier** that is a tracked import. `const { x } = paymentsEnv.getThing()`
67
+ falls through to the ordinary walk (which records the `.getThing` member
68
+ access), unchanged.
69
+
70
+ ### 2. One level of file-unique `const` aliasing
71
+
72
+ `const e = paymentsEnv` registers `e` as **another local name for the same
73
+ import binding**, so the ordinary walk then treats `e.X`, `e["X"]`, `e[expr]`
74
+ and a bare `e` exactly as it treats `paymentsEnv.X` etc. -- zero further
75
+ special-casing, and `dependency-graph.ts`'s existing import-resolution pass
76
+ merges `e`'s accesses into the same contract automatically.
77
+
78
+ An alias is tracked **only if** its name is:
79
+
80
+ - declared with `const`, initialized to a bare identifier that is itself a
81
+ **tracked import** (never another alias -- one level, no chains); and
82
+ - **file-unique**: introduced exactly once anywhere in the file, as counted
83
+ by every binding-introducing position (a `var`/`let`/`const` declarator, a
84
+ destructuring binding element, a function/arrow parameter, a `catch`
85
+ binding, a named function/class); and
86
+ - **never assigned to** afterward: not the left side of `=` or any compound
87
+ assignment (`^=` is the top of `SyntaxKind`'s assignment-token range), not
88
+ the operand of `++`/`--`, not a keyword-less `for (e of …)` / `for (e in …)`
89
+ loop variable.
90
+
91
+ A candidate whose base **is** a real tracked import but that fails the
92
+ uniqueness/never-assigned check is reported as an `escape` (`via:
93
+ "reassignment"`) against that import at the declaration site -- `const e =
94
+ paymentsEnv` is a real read of the contract even when this pass declines to
95
+ follow `e`. A `const b = a` chained onto a resolved alias `a` is deliberately
96
+ **not** followed: `a` is recorded as a bare reference for that read, since
97
+ `b` is never tracked.
98
+
99
+ This pass is **not scope-aware** -- matching every other check in
100
+ `scan-dependencies.ts`. A name shadowed in a nested function still counts as
101
+ a second declaration and disqualifies the alias. This is conservative in the
102
+ safe direction: the worst outcome is a real alias going untracked and its
103
+ keys degrading to `indeterminate`, never a false `used`.
104
+
105
+ ### 3. `deriveOwnershipFindings` widens on any escape, and a proven access always wins
106
+
107
+ `dependency-graph.ts` records every `escape` site (and every remaining bare
108
+ `reference`) at the **contract** level (`escapeSites`), alongside the
109
+ existing `dynamicAccessSites`. A variable's status is then:
110
+
111
+ - `used` -- at least one `member` access anywhere. **Unconditional**: a
112
+ proven member access wins even when the same contract also has escapes.
113
+ - `indeterminate` -- no member access, but the contract has a dynamic access
114
+ **or** an escape somewhere. `evidence` is `"dynamic-access"` or
115
+ `"escape"`; the finding's `reason` cites every site (with its `via`),
116
+ named per ADR 0036.
117
+ - `unconsumed` -- imported, and no member access, no dynamic access, **no
118
+ escape** anywhere. This now provably means "we resolved the import, saw
119
+ every use of it, and none named this key."
120
+
121
+ `VariableAccessStatus` stays exactly three-valued (`used | unconsumed |
122
+ indeterminate`) -- `escape` is a sub-reason within `indeterminate`, not a new
123
+ status, so ADR 0010's "no fourth state borrowed from a model env-cap doesn't
124
+ have" rule is untouched.
125
+
126
+ ## Consequences
127
+
128
+ - A bare `initialize(paymentsEnv)` / `{ ...paymentsEnv }` / `return
129
+ paymentsEnv` now yields `indeterminate` for every not-otherwise-read key,
130
+ where it previously (wrongly) yielded `unconsumed`. Three env-cap test
131
+ fixtures that relied on the old behavior to construct an "unconsumed" case
132
+ were changed to import-without-referencing instead (the genuine
133
+ never-consumed shape).
134
+ - `documentEnv`'s `dynamicAccess` citation (ADR 0037) remains the escape
135
+ hatch for a read env-cap's own AST walk genuinely cannot see -- a shell
136
+ script, a Docker entrypoint, a sibling service. In-repo destructuring and
137
+ aliasing no longer need one.
138
+
139
+ ## Alternatives considered
140
+
141
+ - **A `ts.Program` + type checker to follow aliases/destructuring/cross-file
142
+ properly.** Rejected -- contradicts ADR 0002/0010's fast, per-file,
143
+ semantics-free design; seconds-to-minutes on a large monorepo; and the
144
+ checker can still be defeated (`any`, dynamic access), so it trades a large
145
+ cost for a still-incomplete result. The bounded syntactic rule here catches
146
+ the overwhelmingly common real shapes and is honest (`indeterminate`) about
147
+ the rest.
148
+ - **Downgrade `unconsumed` -> `indeterminate` for any bare reference, and add
149
+ no dataflow at all.** Rejected -- removes the false positives but adds no
150
+ real signal; a destructured contract would report every key as "we're not
151
+ sure" forever.
152
+ - **Track alias chains (`const b = a; b.X`).** Rejected -- no natural
153
+ stopping point (`c = b; d = c; …`), the same unbounded-resolution concern
154
+ ADR 0010 rejects for barrel chains. One level covers the real cases; deeper
155
+ chains degrade safely to `indeterminate`.
156
+ - **Full lexical-scope analysis for alias validity** (so a shadowed name in a
157
+ nested function doesn't disqualify the outer alias). Rejected as
158
+ disproportionate -- the file-unique-`const` rule needs no scope engine and
159
+ cannot produce a false `used`; an un-followed real alias just becomes
160
+ `indeterminate`, the safe direction.
@@ -0,0 +1,156 @@
1
+ # 0040: Library Surfaces Do Not Acquire `node:fs` -- the Caller Supplies the Filesystem Capability
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented: `src/build/types.ts` (`BuildFileSystem`), threaded through
6
+ every `src/build/**` module and every public options object in
7
+ `src/build/index.ts`; `src/cli/filesystem.ts` (the concrete adapter), re-exported
8
+ as the public `@maverickcer/env-cap/node` entry (`src/node/index.ts`) for a
9
+ consumer's own build script; `src/build/tool-version.ts` + `src/cli/json.ts`
10
+ (version via build-time constant, not a self-read); `src/eslint-plugin/no-node-fs.ts`
11
+ and `no-restricted-imports` in `eslint.config.js`; the `AmbientCapabilities` check.
12
+
13
+ **Amended.** The `BuildFileSystem`, `BuildDirent` and `BuildStats` types and the `no-node-fs` lint rule are now
14
+ carried as managed copies of internal-package-contract's canonical sources (`src/_ipc/build-fs.ts`,
15
+ `src/_ipc/no-node-fs.ts`), re-exported from `src/build/types.ts` and wrapped in `src/eslint-plugin/no-node-fs.ts`.
16
+ The decision itself, that library surfaces never acquire `node:fs`, is unchanged.
17
+
18
+ ## Context
19
+
20
+ `repo-contract`'s ADR-0011 removed `child_process`/`process.env` access from
21
+ its own published code after socket.dev flagged "Shell access" and
22
+ "Environment variable access" against its `dist/`. The fix: `spawn`/`env`
23
+ became **required** fields on `RepoContractConfig`, supplied by the consumer
24
+ and threaded internally as one capability object; enforced by a script that
25
+ greps a real `npm pack` tarball.
26
+
27
+ The durable principle: **library code should not implicitly acquire powerful
28
+ ambient capabilities that callers did not explicitly provide.** socket.dev's
29
+ flagging is the concrete trigger and supporting evidence, and a better
30
+ socket.dev score plus less consumer security-review burden is the practical
31
+ payoff -- but the principle stands on its own even if socket.dev's detection
32
+ model changes.
33
+
34
+ Audit of env-cap:
35
+
36
+ - The **runtime** surfaces -- `.` and `./helpers` -- already have zero
37
+ `process.env`, `fs`, network, `child_process`, or `os` access. Nothing to
38
+ do; this already matches ADR-0011's target.
39
+ - The gap: env-cap also ships `./build` and a CLI `bin`, both in the
40
+ published `dist/`. `src/build/*.ts` imported `node:fs`/`node:fs/promises`
41
+ throughout. A socket.dev scan flags the whole package with "Filesystem
42
+ access" regardless of which subpath a consumer imports.
43
+
44
+ ## Decision
45
+
46
+ ### The invariant
47
+
48
+ ```text
49
+ Library entrypoints (., ./helpers, ./build, ./evidence)
50
+ → MUST NOT acquire node:fs -- the capability is always supplied by the caller
51
+
52
+ Executable-context entries (bin, ./eslint-plugin, ./node)
53
+ → MAY acquire node:fs -- they are the capability boundary:
54
+ bin constructs the concrete adapter and runs it; ./node ships that
55
+ same adapter as a value for a consumer's own Node build script;
56
+ ./eslint-plugin runs inside ESLint's own Node process
57
+ ```
58
+
59
+ "Ambient-fs-free" means specifically: **`./build` does not acquire filesystem
60
+ capabilities from Node globals/modules itself.** It still performs real
61
+ filesystem operations -- it just never `import`s `node:fs` to do so; the
62
+ capability is always handed in.
63
+
64
+ The CLI is _permitted_ (not "necessarily has to") retain `node:fs` because it
65
+ is the executable consumer: it constructs the concrete `BuildFileSystem`
66
+ adapter, does its own self-bootstrapping (`process.argv[1]` through a
67
+ symlink), and is never imported by a consumer who only depends on `.`/
68
+ `./helpers`/`./build`. `repo-contract` ships no `bin` at all, so full
69
+ package-level zero-fs parity isn't reachable through injection alone; this is
70
+ the one accepted, standard exception (an executable consumer owns the
71
+ capability required to execute its filesystem-oriented behavior). The
72
+ `./eslint-plugin` entry is exempt for the same reason -- it runs inside
73
+ ESLint's Node process, and its bundled `@typescript-eslint/utils` references
74
+ `node:fs`.
75
+
76
+ ### The injection interface
77
+
78
+ `BuildFileSystem` (`src/build/types.ts`) -- modeled structurally on
79
+ `node:fs/promises` so a thin adapter is a drop-in value, but with **minimal
80
+ structural types** (`BuildDirent`/`BuildStats`) rather than Node's `Dirent`/
81
+ `Stats`: the capability boundary shouldn't leak Node's type surface just
82
+ because the concrete adapter is Node-backed. Only the six operations
83
+ `src/build/**` actually calls are present (`readFile`, `writeFile`, `mkdir`,
84
+ `readdir`, `stat`, `realpath`).
85
+
86
+ **Not shared with `data-cap`.** The two packages are
87
+ independent products with no runtime coupling; a shared types package to
88
+ dedupe six signatures would add real cross-package coupling for negligible
89
+ benefit. data-cap gets its own, structurally-identical interface.
90
+
91
+ Every public options object in `build/index.ts` carries a **required** `fs:
92
+ BuildFileSystem`. Internal positional helpers take it as a parameter, or via
93
+ `ImportResolutionContext` where a context object already exists.
94
+
95
+ **The Node adapter ships as `@maverickcer/env-cap/node`.** `repo-contract`'s
96
+ consumers pass an existing npm package (`crossSpawn`, `process.env`); there is
97
+ no equivalent off-the-shelf `node:fs/promises` → `BuildFileSystem` value, so
98
+ env-cap ships one -- `nodeBuildFileSystem`, the same object the CLI uses -- from
99
+ a dedicated executable-context entry. `./node` bundles `node:fs/promises`; the
100
+ tarball guard exempts its resolved target exactly as it does `bin` and
101
+ `./eslint-plugin`. `./build` stays clean: a consumer's build script does
102
+ `import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"` and passes it
103
+ as `fs`. A non-Node consumer supplies their own `BuildFileSystem` and never
104
+ imports `./node`.
105
+
106
+ ### Version self-read (a distinct concern)
107
+
108
+ `tool-version.ts` and `cli/json.ts` synchronously read the package's _own_
109
+ `package.json` at import time for a version string -- self-introspection, no
110
+ meaningful "consumer" to inject from. Replaced with a build-time constant:
111
+ `tsup.config.ts` reads `package.json` once (build tooling, never shipped) and
112
+ `define`s `__PACKAGE_VERSION__`; `readToolVersion()` returns it, and
113
+ `cli/json.ts` reuses `readToolVersion()` rather than duplicating the logic.
114
+ vitest's config `define`s the same constant so tests run against `src/`
115
+ unchanged.
116
+
117
+ **Build-time filesystem access is not the same thing as published runtime
118
+ filesystem access** -- `tsup.config.ts` reading `package.json` to compute a
119
+ constant never ships in `dist/`, so it adds nothing to the package's own
120
+ flagged capabilities.
121
+
122
+ ### Enforcement
123
+
124
+ - **Source-level** (fast feedback): `no-restricted-imports` in
125
+ `eslint.config.js` forbids `fs`/`node:fs`/`fs/promises`/`node:fs/promises`
126
+ under `src/**` except `src/cli/**`. The published `env-cap/
127
+ eslint-plugin` also ships `no-node-fs` for a consumer to enforce the same
128
+ discipline on its own code.
129
+ - **Tarball-level** (release-blocking backstop): the `AmbientCapabilities` check
130
+ runs `npm pack --ignore-scripts`, extracts it, and greps every `.js`/
131
+ `.cjs`/`.mjs` file **inside the extracted package root** for the forbidden
132
+ specifier set, excluding only the resolved `bin`, `./eslint-plugin`, and
133
+ `./node` targets (and their `.map`s) -- derived from `package.json`, not a
134
+ hardcoded glob. Wired into `precommit`/`verify`/`prepublishOnly`.
135
+
136
+ ## Alternatives considered
137
+
138
+ - **A shared `BuildFileSystem` package across env-cap and data-cap.**
139
+ Rejected -- adds cross-package coupling against this project's
140
+ minimal-dependency stance; two independently-versioned interfaces stay
141
+ simpler.
142
+ - **Read/write interface segregation** (`ReadFileSystem`/`WriteFileSystem`
143
+ so a check-only path requires just a reader). A legitimate idea, but adds a
144
+ second interface pair to thread everywhere for a benefit that only bites at
145
+ the check-vs-generate boundary. Revisit if `checkEnvArtifacts` ever needs
146
+ a type-level guarantee it can't write.
147
+ - **Splitting the CLI into its own npm package** for literal package-level
148
+ zero-fs parity. A possible future escalation, not undertaken now.
149
+ - **Re-engineering module resolution** to avoid `createRequire().resolve()`
150
+ (used in `resolve-package-schema.ts`) on the guess that socket.dev might
151
+ flag it under some "module resolution" category. No confirmed evidence
152
+ that's a real, distinct capability class -- a post-scan check item, not a
153
+ design change.
154
+ - **`Date.now()`/`setTimeout()` ambient reads** in true runtime code
155
+ (`future()`/`past()` validators). Out of scope -- a determinism concern,
156
+ not a socket-flagged capability.
@@ -0,0 +1,75 @@
1
+ # 0041: Dual-package hazard (duplicate module instantiation across import paths) is a checked, documented risk class
2
+
3
+ ## Status
4
+
5
+ Accepted. Checked by `test/runtime/dual-package-hazard.test.ts`; documented
6
+ in [`SECURITY.md`](../../SECURITY.md#dual-package-hazard).
7
+
8
+ ## Context
9
+
10
+ The runtime keeps identity-sensitive state in module scope:
11
+
12
+ - `src/runtime/registry.ts` — a private `WeakMap<object, ContractInternals>`
13
+ that is the only association between a contract object returned by
14
+ `createEnv()` and its schema. `validateEnv()`, `resetEnvCache()`, and
15
+ `isEnvContract()` all consult it.
16
+ - `src/runtime/cache.ts` — the module-level validation cache (`state`,
17
+ `contractValues`, `contractErrors`).
18
+
19
+ Both are correct and necessary within one loaded module instance. They
20
+ become a hazard the moment a consumer's dependency tree resolves
21
+ `env-cap` through two different specifiers — an ESM importer
22
+ and a CJS `require()`r of the same logical package, or a re-exporting
23
+ intermediate package. Node loads two entirely separate module instances in
24
+ that case, each with its own registry `WeakMap` and its own cache. No npm
25
+ package that ships both an ESM and a CJS build can prevent this; it is a
26
+ property of how Node's two module systems resolve independently.
27
+
28
+ ## Decision
29
+
30
+ Since the hazard cannot be prevented, it is made a checked, documented risk
31
+ class instead of a silent unknown. `test/runtime/dual-package-hazard.test.ts`
32
+ loads the built `dist/index.js` (ESM) and `dist/index.cjs` (CJS) as two
33
+ genuinely separate module instances and pins the exact, understood
34
+ consequence:
35
+
36
+ - the same resolution path always yields the same registry/cache (no hazard
37
+ within one module graph);
38
+ - different resolution paths load different instances (the hazard itself,
39
+ confirmed rather than assumed);
40
+ - and — the important part — the failure mode is **fail-fast, not silent**:
41
+ a contract created by the ESM instance's `createEnv()` and handed to the
42
+ CJS instance's `validateEnv()`/`resetEnvCache()` throws a `TypeError`
43
+ ("this value was not created by createEnv()"), and `isEnvContract()`
44
+ returns `false`. It never validates against the wrong schema or reads a
45
+ stale cache silently.
46
+
47
+ [`SECURITY.md`](../../SECURITY.md#dual-package-hazard) states this plainly
48
+ for evaluators planning a mixed-module-system deployment.
49
+
50
+ ## Consequences
51
+
52
+ - An application evaluating this package for a mixed ESM/CJS environment
53
+ has an honest, tested answer rather than an unverified claim.
54
+ - The `TypeError` thrown by `getContractInternals()` is load-bearing for
55
+ this guarantee — a future change that made it return a default or
56
+ `undefined` instead of throwing would turn the fail-fast behavior into
57
+ silent misvalidation. The test pins the throw.
58
+ - The test requires `npm run build` to have produced `dist/index.{js,cjs}`;
59
+ it `skipIf`s gracefully otherwise, matching the cross-runtime tests'
60
+ convention.
61
+
62
+ ## Alternatives considered
63
+
64
+ - **Preventing the hazard via a `globalThis`-keyed registry stable across
65
+ realms.** Rejected — adds real complexity and a new hazard class (global
66
+ namespace collision, version-mismatch handling) to solve a problem that,
67
+ once understood, already fails loudly and safely.
68
+ - **Ignoring it, undocumented.** Rejected — an unstated, unverified risk is
69
+ strictly worse for an evaluator than a stated, tested one, even though
70
+ the underlying limitation is identical either way.
71
+ - **Matching `data-cap`'s framing verbatim.** data-cap's
72
+ hazard (ADR 0041 there) degrades _silently_ (its `defaultCoordinator`
73
+ singleton just stops sharing work). env-cap's degrades _loudly_ (a
74
+ `TypeError`). The risk class is the same; the documented consequence is
75
+ deliberately package-specific.