@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,85 @@
1
+ # 0028: Ownership Model shares one `effectiveOwner()` rule, fixing a pre-existing divergence
2
+
3
+ ## Status
4
+
5
+ Accepted. `effectiveOwner()` relocated from `docs.ts` (private) to
6
+ `link.ts` (exported). Implemented in `src/build/ownership-model.ts`
7
+ (`buildOwnershipModel()`, `OwnershipModel`), exported from
8
+ `@maverickcer/env-cap/build`. `src/build/generate-usage.ts` now uses the
9
+ shared function for `unconsumedOwnedVariables`' `owner` field.
10
+
11
+ ## Context
12
+
13
+ ADR 0024 flagged that Ownership Model's "unowned" signal previously existed
14
+ only as a count (`noOwnerCount`) inside `docs.ts`'s `renderSecurityReview()`
15
+ prose, computed via that file's own private `effectiveOwner()` (variable's
16
+ own `owner`, falling back to the contract's). Investigating that gap
17
+ surfaced a real, separate bug: `generate-usage.ts`'s `computeUsage()`
18
+ resolves ownership for its findings using only `contract.owner`, via a
19
+ locally-built `ownerByIdentity` map that never looks at a variable's own
20
+ `owner` override at all. For a contract-level finding (`dependencyOwnership`,
21
+ `abandonedContracts`) that's correct -- there's no specific variable in
22
+ play. But `UnconsumedOwnedVariableFinding` _does_ name a specific variable
23
+ (`key`), and its `owner` field was silently using the contract-only value --
24
+ meaning `docs.ts`'s Catalog/ownership matrix and `usage-report.ts`'s
25
+ Dependency & Ownership Report could disagree about who owns the same
26
+ variable whenever a `documentEnv()` call set a per-variable `owner`
27
+ override with no contract-level default.
28
+
29
+ ## Decision
30
+
31
+ **Fix the bug and build the model on the corrected, shared rule in the same
32
+ change**, rather than building a new model on top of a known-divergent
33
+ foundation:
34
+
35
+ - **`effectiveOwner()` moves to `link.ts`, exported.** Co-located with
36
+ `DiscoveredContract`/`DiscoveredVariable`, the types it operates over,
37
+ instead of living private inside the one renderer that happened to need
38
+ it first. `docs.ts` now imports it instead of defining its own copy.
39
+ - **`generate-usage.ts` gains a second lookup, `effectiveOwnerFor()`,
40
+ used only for `unconsumedOwnedVariables`.** The existing contract-only
41
+ `ownerFor()` stays exactly as it was for the three genuinely
42
+ contract-level fields (`dependencyOwnership.owner`,
43
+ `abandonedContracts.owner`) -- those have no variable to consider an
44
+ override for, so using the contract's own `owner` there was never wrong.
45
+ Only the one finding type that names a specific variable needed the fix.
46
+ - **`OwnershipModel` computes every variable's owner through the same
47
+ shared `effectiveOwner()`, and itemizes `unownedContracts`/
48
+ `unownedVariables` as real arrays**, matching the array-of-refs shape
49
+ `abandonedContracts`/`unconsumedOwnedVariables` already established in
50
+ `usage-report.ts` -- not a new shape invented for this model.
51
+ - **Scoped to every discovered contract, active or not** -- the same scope
52
+ `renderSecurityReview()`'s `noOwnerCount` already had (it counts over
53
+ `for (const contract of contracts)` with no `active` filter). This model
54
+ formalizes that existing scope rather than narrowing it.
55
+
56
+ ## Consequences
57
+
58
+ - `docs.ts` and `usage-report.ts` can no longer disagree about who owns a
59
+ variable -- both read through the one function.
60
+ - This is, narrowly, a bug fix bundled with new scope: the changeset for
61
+ this change ships as two entries -- a `patch` for the
62
+ `unconsumedOwnedVariables` owner-resolution fix, a `minor` for the new
63
+ `OwnershipModel` type -- so the changelog doesn't conflate "this was
64
+ wrong before" with "this is new."
65
+ - `OwnershipModelContract.owner` is deliberately _not_ run through
66
+ `effectiveOwner()` (there's no level above a contract to fall back to) --
67
+ only `OwnershipModelVariable.owner` is "effective" in that sense. A
68
+ reader shouldn't assume the same word means the same computation at both
69
+ levels without checking; the field-level doc comments say so explicitly.
70
+
71
+ ## Alternatives considered
72
+
73
+ - **Ship `OwnershipModel` first, fix the `generate-usage.ts` bug in a
74
+ separate, later change.** Rejected -- building a new canonical model on
75
+ top of a foundation already known to produce two different answers for
76
+ the same question would just give the bug a second, model-shaped place
77
+ to hide, rather than actually resolving ADR 0024's stated goal of "a fact
78
+ gets computed once."
79
+ - **Leave `ownerFor()` (contract-only) as the single lookup, and make
80
+ `effectiveOwnerFor()` the _only_ one, used everywhere in
81
+ `generate-usage.ts`.** Rejected -- `dependencyOwnership`/
82
+ `abandonedContracts` are genuinely contract-level facts; running them
83
+ through variable-aware resolution would be meaningless (there's no
84
+ variable) and would obscure that these three fields answer a different
85
+ question than `unconsumedOwnedVariables.owner` does.
@@ -0,0 +1,98 @@
1
+ # 0029: Lifecycle Model adds deprecation/rename fields, promotes ExpiringEntry
2
+
3
+ ## Status
4
+
5
+ Accepted. `deprecated`/`deprecatedReason`/`removeBy`/`renamedFrom` added to
6
+ `VariableDocs` (`deprecated`/`deprecatedReason` also on `ContractDocs`),
7
+ threaded through `parse.ts` -> `link.ts` -> `manifest-snapshot.ts`.
8
+ Implemented in `src/build/lifecycle-model.ts` (`buildLifecycleModel()`,
9
+ `LifecycleModel`), exported from `@maverickcer/env-cap/build`.
10
+
11
+ ## Context
12
+
13
+ ADR 0024 named two gaps in the Lifecycle Model: no `deprecated`/`removeBy`
14
+ field at all (only contract-level `active: boolean`, which means "on/off,"
15
+ not "being phased out"), and no `renamedFrom` -- so a variable rename shows
16
+ up in `ManifestChangeReport` as an unrelated `removedVariables` +
17
+ `addedVariables` pair instead of a single correlated change. Zero grep hits
18
+ existed anywhere in the codebase for any of these four fields before this
19
+ change.
20
+
21
+ ## Decision
22
+
23
+ **Add the four fields exactly like every other `documentEnv()` field
24
+ already flows** -- `runtime/document.ts` -> `build/parse.ts`
25
+ (`DiscoveredVariableDocs`/`DiscoveredContractDocs`) -> `build/link.ts`
26
+ (`DiscoveredVariable`/`DiscoveredContract`) -> `build/manifest-snapshot.ts`
27
+ (`ManifestSnapshotVariable`/`ManifestSnapshotContract`, including
28
+ field-level diffing), the same path ADR 0024's Contract Model phase
29
+ established for `classification`. No new mechanism, no special case.
30
+
31
+ - **`deprecated`/`deprecatedReason` exist at both variable and contract
32
+ level; `removeBy`/`renamedFrom` exist only at variable level.** A
33
+ variable rename is a variable-level fact by nature. A contract-level
34
+ "removeBy"/"renamedFrom" wasn't asked for by the audit and has no clear
35
+ meaning (a contract doesn't have a single name to rename `from`) --
36
+ adding it now would be speculative scope, not a real gap being closed.
37
+ - **`deprecated` is deliberately independent of `expiresAt` and of
38
+ contract-level `active`.** `expiresAt` is a rotation/sunset _date_;
39
+ `deprecated` is a phase-out _signal_ with no required date attached (a
40
+ variable can be deprecated with no `removeBy` set yet). `active` is an
41
+ on/off switch for whether a contract participates in the manifest at all
42
+ -- orthogonal to whether it's being phased out. All three stay
43
+ independently settable, matching how `expiresAt` and `active` already
44
+ coexist without one implying the other.
45
+ - **`LifecycleModel` promotes the already-good `ExpiringEntry`/
46
+ `computeExpiringEntries()` precedent** (real, exported, already reused
47
+ across `renderDocs()` and `generate-documentation.ts`) into a canonical,
48
+ versioned shape (`expiring` field, unchanged), and adds a new
49
+ `contracts` array carrying every lifecycle-relevant fact
50
+ (`expiresAt`, `refreshInstructions`, `deprecated`, `deprecatedReason`,
51
+ `removeBy`, `renamedFrom`) per contract/variable.
52
+ - **`LifecycleModel.contracts` only includes a contract when it, or at
53
+ least one of its variables, actually sets a lifecycle field** -- the same
54
+ "only what's relevant" scope `renderLifecycleReport()`'s existing row
55
+ filter already uses (`expiresAt || owner || refreshInstructions`, minus
56
+ `owner`, which belongs to the Ownership Model, not this one). A contract
57
+ with no lifecycle data at all contributes nothing to this model, same as
58
+ it contributes no row to the rendered report today.
59
+ - **`renamedFrom` is authored, not inferred.** Consistent with ADR 0010's
60
+ "provable, not heuristic" ethos: no Levenshtein/similarity matching is
61
+ attempted anywhere to _guess_ a rename from a remove+add pair.
62
+ `diffManifestSnapshots()` reading `renamedFrom` to actually correlate a
63
+ rename is Change Model B's job (a later phase), gated on this field
64
+ existing first.
65
+
66
+ ## Consequences
67
+
68
+ - `ManifestChangeReport`'s `updatedVariables` now includes `renamedFrom` in
69
+ its field-level diff whenever it changes, same as any other field --
70
+ itself not yet a rename _correlation_, just a diffable fact, until Change
71
+ Model B lands.
72
+ - A deprecation workflow (flag a variable, give a reason, set a removal
73
+ date) is now representable in `documentEnv()` without overloading
74
+ `expiresAt` (a rotation concept) or `active` (an on/off switch) to mean
75
+ something they were never designed to mean.
76
+ - `LifecycleModelContract`/`LifecycleModelVariable` deliberately omit
77
+ `owner` -- a consumer wanting both lifecycle and ownership facts for the
78
+ same contract joins `LifecycleModel` with `OwnershipModel` by identity
79
+ (`file`+`exportName`), rather than this model duplicating a field that
80
+ model already owns.
81
+
82
+ ## Alternatives considered
83
+
84
+ - **Overload `expiresAt` to also mean "deprecated."** Rejected -- a
85
+ variable can be deprecated with no known removal date yet (the whole
86
+ reason `removeBy` is optional and separate), and a variable can have a
87
+ rotation `expiresAt` with no deprecation intent at all (a secret that
88
+ just needs periodic rotation, not phase-out). Conflating the two would
89
+ make either concept unrepresentable without the other.
90
+ - **Attempt heuristic rename detection** (matching a removed key to an
91
+ added key by similarity/edit-distance) instead of an authored
92
+ `renamedFrom` field. Rejected -- exactly the kind of guess ADR 0010's
93
+ "provable, not heuristic" principle already rules out elsewhere in this
94
+ codebase; a false-positive rename correlation would be actively
95
+ misleading in a change report.
96
+ - **Add `removeBy`/`renamedFrom` at the contract level too, for
97
+ symmetry.** Rejected as speculative -- neither has a clear meaning at
98
+ contract granularity, and nothing in the original audit asked for it.
@@ -0,0 +1,97 @@
1
+ # 0030: Change Model wraps the existing manifest change report
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/build/change-model.ts` (`buildChangeModel()`,
6
+ `ChangeModel`), exported from `@maverickcer/env-cap/build`. Rename
7
+ correlation (`RenamedVariable`, `renamedVariables`) landed as a second
8
+ phase on top of this same file once ADR 0029's `renamedFrom` field existed
9
+ to correlate from.
10
+
11
+ ## Context
12
+
13
+ ADR 0024 named Change Model as the sixth of the seven canonical models,
14
+ already fact-shaped and exported as `ManifestChangeReport` (ADR 0021), but
15
+ with no versioned, model-namespaced identity of its own -- it's just a field
16
+ (`result.manifest.changes`) on `GenerateEnvManifestResult`, not a value a
17
+ consumer can hand to `defineEvidenceProjection()`-style code alongside the
18
+ other six models.
19
+
20
+ ## Decision
21
+
22
+ **A thin wrapper, computing nothing new.** `ChangeModel` is
23
+ `{ schemaVersion, manifest: ManifestChangeReport }`; `buildChangeModel()`
24
+ takes an already-computed `ManifestChangeReport` and wraps it. Concretely:
25
+
26
+ - **`ManifestChangeReport` and its ref/update/field-change types stay
27
+ exactly as they are, exported from where they already are.** Nothing
28
+ about `generateEnvManifest()`'s consumer surface changes. This mirrors
29
+ ADR 0024's additive-wrapper convention exactly: a canonical model is a
30
+ new file that maps or aggregates existing pieces, never an in-place
31
+ rewrite.
32
+ - **No rename correlation in the base shape.** `renamedFrom` (ADR 0029)
33
+ exists on `DiscoveredVariable`/`ManifestSnapshotVariable` as a diffable
34
+ field, but `diffManifestSnapshots()` itself doesn't read it -- correlation
35
+ landed as a second, later phase (Change Model B, below), gated on this
36
+ base shape existing first so the two changes land as independently
37
+ reviewable, independently revertable steps.
38
+
39
+ **Change Model B: rename correlation lives in `change-model.ts`, not
40
+ `manifest-snapshot.ts`.** `buildChangeModel()` gained two more parameters
41
+ (`currentContracts: readonly DiscoveredContract[]`, `root: string`) and a
42
+ new `renamedVariables: readonly RenamedVariable[]` field on `ChangeModel`:
43
+
44
+ - **`ManifestChangeReport`/`diffManifestSnapshots()` stay untouched**,
45
+ exactly as this ADR's original decision required. Correlation happens by
46
+ cross-referencing the _current_ contracts' `renamedFrom` declarations
47
+ against the _already-computed_ `manifest.addedVariables`/
48
+ `removedVariables` -- a second pass over data that already exists, not a
49
+ change to how the diff itself is computed. `ManifestVariableRef` gains no
50
+ new field; `renamedFrom` isn't in that ref shape and doesn't need to be.
51
+ - **A rename is only ever correlated within the same contract**
52
+ (`contractIdentity` must match on both halves) -- a variable moving
53
+ between two different contracts' schemas is a different kind of change,
54
+ not a rename, and correlating across contracts would risk a false match
55
+ on a coincidentally-reused key name.
56
+ - **A `renamedFrom` that doesn't resolve to a real `removedVariables`
57
+ entry correlates nothing.** No error, no warning -- the variable simply
58
+ keeps showing as an ordinary addition in `manifest.addedVariables`,
59
+ same "provable, not heuristic" fallback-to-silence ADR 0010 already
60
+ established for barrel re-exports.
61
+ - **`renamedVariables` is additive, not a filter.** `manifest.addedVariables`/
62
+ `removedVariables` still list a correlated rename's two halves
63
+ separately -- a consumer wanting a deduplicated view filters them out
64
+ using `renamedVariables` itself, rather than this model silently
65
+ removing entries from the untouched legacy report.
66
+ - **No `renamedContracts`.** Lifecycle Model deliberately has no
67
+ contract-level `renamedFrom` (ADR 0029's own alternatives-considered
68
+ section) -- there is no field to correlate a contract-level rename from,
69
+ so no such array is added here either.
70
+
71
+ ## Consequences
72
+
73
+ - `ChangeModel` becomes the sixth model Evidence Model assembles against,
74
+ alongside Contract/Dependency/Ownership/Lifecycle/Finding.
75
+ - `buildChangeModel()`'s signature grew from `(manifest)` to
76
+ `(manifest, currentContracts, root)` between these two phases, both
77
+ landing before any published release included the first shape -- an
78
+ Experimental-tier signature change with no real external caller to
79
+ break, per `VERSIONING.md`.
80
+ - A rename shows up in `ChangeModel.renamedVariables` as
81
+ `{ previousKey, currentKey, ... }` the moment a `documentEnv()` edit sets
82
+ `renamedFrom`, with no manual bookkeeping beyond authoring that one field.
83
+
84
+ ## Alternatives considered
85
+
86
+ - **Land rename correlation in the same phase.** Rejected -- bundling "give
87
+ Change Model its own identity" with "teach the diff to correlate renames"
88
+ would make this phase's diff meaningfully harder to review and revert
89
+ independently, for no benefit; the two are separable concerns that happen
90
+ to touch the same file.
91
+ - **Fold `ChangeModel` directly into `ManifestChangeReport`** (add a
92
+ `schemaVersion` field to the existing type) rather than a wrapping type.
93
+ Rejected -- `ManifestChangeReport` is real, in-use public surface
94
+ (`result.manifest.changes`); adding an unrelated `schemaVersion` field to
95
+ it conflates "the diff" with "the model-namespaced fact wrapper," and
96
+ would need every existing consumer destructuring that type to account for
97
+ a field with no bearing on the diff itself.
@@ -0,0 +1,85 @@
1
+ # 0031: A 5th public entry point (`./evidence`) for Evidence Model projections
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/evidence/`, exported as
6
+ `@maverickcer/env-cap/evidence`.
7
+
8
+ ## Context
9
+
10
+ ADR 0024 established seven canonical fact models, the last of which --
11
+ Evidence -- assembles the other six into one immutable snapshot and exists
12
+ specifically to be projected into whatever shape a downstream consumer
13
+ needs (a Markdown report, a compliance export, a dashboard's JSON feed),
14
+ rather than env-cap hand-rolling each of those shapes itself. That
15
+ projection mechanism, `defineEvidenceProjection()`, has a different runtime
16
+ profile than everything `@maverickcer/env-cap/build` exports: assembling an
17
+ `EvidenceModel` requires `node:fs` and the TypeScript compiler API (Node-only,
18
+ dev/CI tooling, per ADR 0002 and `specs/architecture.md`), but _running a
19
+ projection over an already-assembled model_ does not -- a projection is a
20
+ pure function of a plain, JSON-serializable object, no different in kind
21
+ from `createEnv()`/`validateEnv()`'s own isomorphic contract. A dashboard
22
+ backend, an edge function, or a CI step that only has a previously-generated
23
+ `EvidenceModel` JSON file on disk (or over the wire) should be able to run a
24
+ projection against it without pulling in `typescript` or `node:fs` at all.
25
+
26
+ ## Decision
27
+
28
+ - **A 5th entry point, not a `./build` export.** `defineEvidenceProjection()`
29
+ ships as `@maverickcer/env-cap/evidence`, isomorphic like `runtime` and
30
+ `helpers` (`platform: "neutral"`, `target: "es2020"` in `tsup.config.ts`),
31
+ rather than living inside `@maverickcer/env-cap/build` alongside the
32
+ Node-only model builders. Bundling it with `build` would mean any consumer
33
+ running a projection in a browser or edge function pulls in the TypeScript
34
+ compiler API transitively, defeating the isomorphism this module exists to
35
+ provide.
36
+ - **`EvidenceModel` is imported as a type only.** `src/evidence/` needs to
37
+ name the shape it projects over, but never constructs one -- that's
38
+ `generateEvidenceModel()`'s job (`@maverickcer/env-cap/build`, a later
39
+ phase). `src/evidence/define-projection.ts` imports `EvidenceModel` from
40
+ `src/build/evidence-model.ts` with `import type` only, erased entirely at
41
+ compile time under `verbatimModuleSyntax` -- a second, deliberate instance
42
+ of the one cross-folder pattern `helpers`→`runtime` already established
43
+ (see `specs/architecture.md`), not an exception carved out for this
44
+ feature alone.
45
+ - **No default export.** Unlike the eslint-plugin entry point (ADR 0017),
46
+ `src/evidence/index.ts` has only named exports, so it needs none of the
47
+ CJS-interop postprocessing `internal-package-contract tool cjs-interop`
48
+ exists for -- esbuild's ordinary CJS output already resolves
49
+ `require("@maverickcer/env-cap/evidence").defineEvidenceProjection`
50
+ correctly.
51
+ - **Experimental tier.** Like `packages` (ADR 0014) and `./build`'s
52
+ lower-level primitives, `./evidence` ships Experimental rather than
53
+ Stable -- see `VERSIONING.md`. The provenance mechanism (ADR 0032) is new
54
+ enough that real projection authorship is likely to reveal a better shape
55
+ before it's ready to commit to for good.
56
+
57
+ ## Consequences
58
+
59
+ - `tsup.config.ts`, `scripts/emit-dts-shims.mjs`, `ci/size-budgets.mjs`
60
+ (a 3KB gzip budget, matching `runtime`; `helpers` has 4KB), `typedoc.json`,
61
+ `package.json#exports`, `AGENTS.md`, and `VERSIONING.md` each gained an
62
+ `evidence` entry, mirroring every other place ADR 0017 already touched for
63
+ `eslint-plugin`.
64
+ - `specs/architecture.md`'s "entry points" section and diagram describe five
65
+ directories instead of four, with a second type-only cross-folder edge
66
+ (`evidence` → `build`) alongside `helpers` → `runtime`.
67
+ - A consumer who only ever calls env-cap's build-time generators never pays
68
+ for `./evidence`'s existence -- it's a separate bundle, untouched unless
69
+ imported.
70
+
71
+ ## Alternatives considered
72
+
73
+ - **Export `defineEvidenceProjection()` from `@maverickcer/env-cap/build`
74
+ alongside the six model builders.** Rejected -- would make every consumer
75
+ of a projection also a transitive consumer of the TypeScript compiler API
76
+ and `node:fs`, breaking the "run anywhere a persisted snapshot travels"
77
+ goal this mechanism exists to serve, and would put `./build`'s tight
78
+ `999KB` (effectively unbudgeted, dev/CI-only) size profile in tension with
79
+ `./evidence`'s deliberately tiny one.
80
+ - **Export it from the package root (`.`, alongside `createEnv`/
81
+ `validateEnv`).** Rejected -- the root entry point's whole identity is a
82
+ fixed, tiny (3KB gzip) runtime surface (ADR 0008); adding a second,
83
+ independently-growing feature there risks that budget for a capability
84
+ most runtime consumers never use, the same reasoning that kept `helpers`
85
+ and `eslint-plugin` as their own entry points rather than root additions.
@@ -0,0 +1,120 @@
1
+ # 0032: Evidence projection provenance via a non-frozen Proxy tracking membrane, not `Object.freeze()`
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/evidence/define-projection.ts`.
6
+
7
+ ## Context
8
+
9
+ The original audit's sketch for `defineEvidenceProjection()` proposed
10
+ wrapping the (already `deepFreeze()`-d, per ADR 0012's precedent)
11
+ `EvidenceModel` in a tracking `Proxy` before handing it to a projector,
12
+ recording every field path actually read, and attaching those paths as
13
+ automatic provenance -- so a consumer never has to hand-maintain "which
14
+ evidence produced this output" bookkeeping themselves.
15
+
16
+ A design spike (tracked separately, not merged) tested this directly and
17
+ found a real incompatibility the original sketch didn't anticipate:
18
+ `Object.freeze()` makes every one of an object's own properties
19
+ non-configurable (and non-writable, for data properties). Per the ECMAScript
20
+ spec, a `Proxy`'s `get` trap on a non-configurable, non-writable data
21
+ property is _required_ to return the exact (`===`) value the target holds --
22
+ it cannot substitute a wrapping proxy for a nested object. Concretely: once
23
+ `EvidenceModel` is frozen (at any level), wrapping it in a wider Proxy and
24
+ returning a _different_ proxy for a nested property read throws
25
+ `TypeError: 'get' on proxy: property '...' is a read-only and
26
+ non-configurable data property on the proxy target but the proxy did not
27
+ return its actual value` on the very first nested access. Freezing even
28
+ just the top level was enough to break wrapping of that level's own
29
+ properties in reproduction.
30
+
31
+ ## Decision
32
+
33
+ - **The tracking membrane never wraps a frozen object.** Each call into a
34
+ projector's field function first takes a `structuredClone()` of the
35
+ caller's `EvidenceModel` -- a fresh, unfrozen, fully disconnected copy --
36
+ and wraps _that_ in the Proxy membrane. The caller's own (possibly
37
+ `deepFreeze()`-d) `EvidenceModel` is never touched.
38
+ - **Immutability is enforced by the membrane's own traps, not by freezing
39
+ the target.** `set`, `deleteProperty`, `defineProperty`, and
40
+ `setPrototypeOf` all throw a `TypeError` unconditionally. This gives the
41
+ same practical guarantee (a projector cannot mutate the evidence it reads)
42
+ without relying on `Object.freeze()`, which is what made deep read-tracking
43
+ impossible in the first place.
44
+ - **Every `get` is a two-fold operation: return the real value, and record
45
+ the path.** For each property key that is a string (not a `Symbol`, which
46
+ covers well-known protocol hooks like `Symbol.iterator` and is left to pass
47
+ through unrecorded) other than an array's own `"length"` (recorded paths
48
+ are meant to name _evidence fields_, and `.length` reads are pervasive
49
+ incidental noise from iteration, not a field a consumer meaningfully
50
+ "read"), the dotted path from the model root is added to a `Set`, and the
51
+ result -- if itself an object -- is recursively wrapped (memoized in a
52
+ `WeakMap` keyed by the already-cloned object, so repeated reads of the same
53
+ nested object return the same proxy instance rather than constructing a
54
+ new one each time). This design was verified against plain nested reads,
55
+ `.map()`/array iteration (including `for...of`'s internal `Symbol.iterator`
56
+ call, which correctly re-enters the membrane per element), destructuring,
57
+ and spread -- all correctly attribute reads to their real field paths.
58
+ - **`generateEvidenceModel()`'s own output stays genuinely frozen.**
59
+ `deepFreeze()` (ADR from Phase 12's genericization) is still the right
60
+ tool for the `EvidenceModel` a caller receives _outside_ a projection --
61
+ direct property access on that object throws on mutation exactly as every
62
+ other canonical model does. Freezing and the tracking membrane are simply
63
+ never applied to the same object graph at the same time.
64
+ - **Recorded sources are flat `EvidenceModel` field-path strings today, not
65
+ `EvidenceReference`s.** Turning a path like
66
+ `"contract.contracts.0.variables.0.key"` into the structured
67
+ `EvidenceReference` shape (`{model: "contract", exportName: "...",
68
+ variable: "..."}`, `src/build/evidence-reference.ts`, ADR 0026) requires
69
+ _model-aware_ interpretation -- knowing that index `0` into `.contracts`
70
+ means "keyed by that contract's `exportName`," and index `0` into
71
+ `.variables` means "keyed by `key`" -- which a generic path-string reader
72
+ cannot derive on its own without hardcoding each model's array-shape
73
+ semantics into the tracking membrane itself. That per-model resolution is
74
+ real, additional design work, deliberately deferred rather than rushed
75
+ into this phase; see `VERSIONING.md`'s Experimental-tier note for
76
+ `./evidence`.
77
+ - **Purity beyond read-only-ness is documented, not enforced.** Nothing stops
78
+ a projector from calling `fetch()` or `console.log`-ing a secret from
79
+ within its function body -- there is no runtime mechanism in JavaScript
80
+ that can prevent arbitrary side effects inside a plain function. A
81
+ projector is documented (`EvidenceProjector`'s own JSDoc) as required to be
82
+ a pure function of its `evidence` argument; only the read-only half of
83
+ that contract is actually enforced.
84
+
85
+ ## Consequences
86
+
87
+ - `defineEvidenceProjection()`'s `project()` path clones `EvidenceModel` once
88
+ per output field (a fresh membrane per field, so each output key's
89
+ `sources` list reflects only that field's own reads). For a typical
90
+ projection (a handful of output fields over a config-sized model), this is
91
+ cheap; it would need reconsidering if a projection schema ever grew large
92
+ enough, or `EvidenceModel` itself large enough, for repeated
93
+ `structuredClone()` calls to matter.
94
+ - `structuredClone()` is a runtime dependency of `./evidence` -- available as
95
+ a global in Node ≥17, all evergreen browsers, and every edge runtime this
96
+ package already targets; no polyfill or additional dependency required.
97
+ - A future phase can add per-model index-path → `EvidenceReference`
98
+ resolvers (one small, targeted function per of the six sub-models, per the
99
+ spike's recommendation) as a purely additive enhancement to
100
+ `EvidenceProjectionResult.sources`, without changing
101
+ `defineEvidenceProjection()`'s call signature.
102
+
103
+ ## Alternatives considered
104
+
105
+ - **Ship the original sketch as-is (freeze first, then wrap).** Rejected --
106
+ throws a `TypeError` on the first nested property read, as confirmed by
107
+ direct reproduction; not a viable implementation of the original design at
108
+ all, not just a suboptimal one.
109
+ - **Explicit, caller-supplied `sources` instead of automatic tracking.** The
110
+ documented fallback if the design spike hadn't panned out. Rejected once
111
+ the spike confirmed the membrane-based approach works cleanly -- automatic
112
+ provenance is strictly more useful than asking every projection author to
113
+ hand-maintain a parallel `sources` array that can silently drift from what
114
+ their projector actually reads.
115
+ - **Build the full model-aware `EvidenceReference` resolution now, instead of
116
+ flat path strings.** Rejected for this phase -- real, separate design work
117
+ (six model-specific index-path interpreters) that the spike explicitly
118
+ flagged as non-trivial; shipping flat path strings first lets real
119
+ projection usage inform what the resolved shape should look like, the same
120
+ Experimental-tier reasoning `VERSIONING.md` already applies elsewhere.
@@ -0,0 +1,81 @@
1
+ # 0033: The ten first-party reference projections live in `examples/`, not `src/`
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented starting with `examples/evidence-projections/`. **Superseded in part by
6
+ ADR 0034**: the three-tier `examples/` restructuring relocated this package to
7
+ `test/integration/positive/enterprise/evidence-projections/` as a behavioral fixture rather than a
8
+ human-facing example — the reasoning below (no privileged internal path, reuses the flagship
9
+ schema, golden-fixture regression protection) is unchanged and still governs it; only its
10
+ directory and presentation to readers changed.
11
+
12
+ ## Context
13
+
14
+ ADR 0024's plan calls for ten first-party reference projections (`.env.example`, Environment
15
+ Configuration Reference, Configuration Inventory, and so on) built through
16
+ `defineEvidenceProjection()` (`@maverickcer/env-cap/evidence`, ADR 0031) with "no privileged
17
+ internal path" — the same public API a real consumer would use. Each one, in practice, needs
18
+ both halves of that API: `generateEvidenceModel()` (Node-only, `@maverickcer/env-cap/build`) to
19
+ assemble an `EvidenceModel`, and `defineEvidenceProjection()` (isomorphic,
20
+ `@maverickcer/env-cap/evidence`) to project it. `src/evidence/` currently has exactly one
21
+ sanctioned cross-folder edge — a type-only import of `EvidenceModel` from `src/build/`, erased at
22
+ compile time (ADR 0031) — and no edge at all onto any of `src/build/`'s actual renderer
23
+ _functions_ (`renderEnvExample`, `renderDocs`, etc.), which several of these projections need to
24
+ call directly to stay "thin wrappers" rather than reimplemented rendering logic.
25
+
26
+ ## Decision
27
+
28
+ - **The reference projections live in `examples/evidence-projections/`, a new example package
29
+ structured like every other directory in `examples/`** — its own `package.json` depending on
30
+ `env-cap` via `file:../..`, importing `@maverickcer/env-cap/build` and
31
+ `@maverickcer/env-cap/evidence` exactly as an external consumer's own project would. Nothing
32
+ inside it reaches into `src/**/*.ts` or an unexported build internal.
33
+ - **This is the literal, strongest form of "no privileged internal path."** A file living inside
34
+ `src/build/` importing from `src/evidence/` (or vice versa) would still be _inside the
35
+ package_, with the option of reaching past the public surface even if it chose not to.
36
+ A file in `examples/evidence-projections/`, installing the package the same way a real
37
+ consumer does, structurally cannot.
38
+ - **`src/`'s five-folder, zero-(or type-only-)cross-dependency invariant is left completely
39
+ untouched.** No new ADR-sanctioned edge was needed on either `src/build/` or `src/evidence/` —
40
+ the tension that raised this question in the first place (a projection needing both a
41
+ Node-only renderer and the isomorphic projection mechanism) is resolved by placing the
42
+ _consumer_ of both outside `src/` entirely, not by adding a new edge between them.
43
+ `src/evidence/`'s one type-only edge onto `src/build/evidence-model.ts` is unaffected.
44
+ - **Reuses `examples/basic-node`'s exact schema.** Each projection's output can be verified
45
+ byte-identical to what the existing, already-tested `generateEnvArtifacts()` path produces on
46
+ the exact same input — the strongest form of regression protection available, and proof that a
47
+ projection is a _reshape_, not a second, independently-drifting rendering implementation.
48
+ - **Wired into the same infrastructure every other example uses**: `.github/workflows/ci.yml`'s
49
+ `examples` job, `test/examples/evidence-projections.test.ts`, `examples/README.md`'s ordered
50
+ list, and `scripts/update-example-goldens.mjs`'s `EXAMPLES` map — no special-cased tooling.
51
+
52
+ ## Consequences
53
+
54
+ - A consumer cannot `import` env-cap's reference projections as ready-made functions from the
55
+ published package — only copy the pattern, the same way every other `examples/` directory is
56
+ a pattern to copy, not an importable module. This was an explicit, accepted tradeoff (see
57
+ Alternatives below), not an oversight.
58
+ - Each reference projection needs its own small reshape from a canonical fact model's shape
59
+ (e.g. `ContractModelContract`) into whatever shape the renderer it wraps already expects (e.g.
60
+ `DiscoveredContract`) — genuine, if mechanical, adapter code, not a zero-cost pass-through.
61
+ Fields the target renderer doesn't use (e.g. `renderEnvExample()` never reads
62
+ `deprecated`/`deprecatedReason`) are stubbed `undefined` rather than sourced from a
63
+ cross-referenced model, to keep each projection's own scope narrow.
64
+ - `examples/evidence-projections/`'s own `expected/` golden fixtures follow the exact same
65
+ regression-fixture convention documented in `examples/README.md` — regenerated only via
66
+ `npm run examples:update-golden`, never silently.
67
+
68
+ ## Alternatives considered
69
+
70
+ - **Inside `src/build/`, importing `defineEvidenceProjection` from `src/evidence/`.** Rejected —
71
+ would require a new ADR sanctioning a second, _value-level_ cross-folder edge (unlike the
72
+ existing type-only ones), and would mean `src/build/` could no longer move to its own
73
+ repository without `src/evidence/` coming along, a real cost for a set of files whose whole
74
+ point is demonstrating the _public_, cross-package-boundary API, not needing privileged access.
75
+ - **A 6th public entry point exporting the ten projections as ready-made functions** (e.g.
76
+ `env-cap/projections`). Rejected for this round — would commit env-cap to
77
+ versioning and supporting ten specific output shapes as Stable-track API surface before any
78
+ real external usage has validated they're the right shapes (the same reasoning `VERSIONING.md`
79
+ already applies to `packages` and `./evidence` itself). Revisiting this once real projection
80
+ authorship (env-cap's own and consumers') has had a feedback cycle is explicitly left open,
81
+ not foreclosed.