@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
package/dist/build.js CHANGED
@@ -1,12 +1,12 @@
1
1
  import path6 from 'path';
2
2
  import crypto from 'crypto';
3
- import ts4 from 'typescript';
4
3
  import { createRequire } from 'module';
5
4
 
6
5
  // src/build/evidence-snapshot.ts
7
- function displayPath(root, absolutePath) {
8
- const relative = path6.relative(root, absolutePath);
9
- if (relative.startsWith("..") || path6.isAbsolute(relative)) return absolutePath;
6
+ function displayPath(root, filePath) {
7
+ if (!path6.isAbsolute(filePath)) return filePath.split(path6.sep).join("/");
8
+ const relative = path6.relative(root, filePath);
9
+ if (relative.startsWith("..") || path6.isAbsolute(relative)) return filePath;
10
10
  return relative.split(path6.sep).join("/");
11
11
  }
12
12
 
@@ -37,7 +37,6 @@ function previousContentHashes(previous) {
37
37
  for (const contract of previous?.dependency.contracts ?? []) {
38
38
  for (const variable of contract.variables) {
39
39
  for (const assertion of variable.dynamicAccessAssertions) {
40
- if (assertion.contentHash === void 0) continue;
41
40
  const identity = dynamicAccessVariableIdentity(
42
41
  contract.file,
43
42
  contract.exportName,
@@ -58,8 +57,8 @@ async function buildCitationSnapshots(activeContracts, previous, root, readFile)
58
57
  for (const contract of activeContracts) {
59
58
  const file = displayPath(root, contract.file);
60
59
  for (const variable of contract.variables) {
61
- const citations = variable.evidence?.dynamicAccess ?? [];
62
- if (citations.length === 0) continue;
60
+ const citations = variable.evidence?.dynamicAccess;
61
+ if (citations === void 0) continue;
63
62
  const identity = dynamicAccessVariableIdentity(file, contract.exportName, variable.key);
64
63
  const assertions = [];
65
64
  for (const citation of citations) {
@@ -137,9 +136,7 @@ function toVariableRef(contract, variable) {
137
136
  return { file: contract.file, exportName: contract.exportName, key: variable.key };
138
137
  }
139
138
  function toComparable(value) {
140
- if (value === void 0) return void 0;
141
- if (typeof value === "string") return value;
142
- return JSON.stringify(value);
139
+ return typeof value === "string" ? value : JSON.stringify(value);
143
140
  }
144
141
  function genericFieldChanges(previous, current, skipKeys) {
145
142
  const keys = /* @__PURE__ */ new Set([...Object.keys(previous), ...Object.keys(current)]);
@@ -182,17 +179,7 @@ function recordFieldChanges(previous, current) {
182
179
  return changes;
183
180
  }
184
181
  function byIdentity(a, b) {
185
- return a.file.localeCompare(b.file) || a.exportName.localeCompare(b.exportName) || // The `?? ""` fallbacks themselves are unreachable through any real
186
- // array this function ever sorts: a `ManifestContractRef` never carries
187
- // a `key` at all, but its own array can never hold two entries sharing
188
- // both file+exportName (contracts are unique by that pair) so the key
189
- // term is never reached for them either way; a `ManifestVariableRef`'s
190
- // `key` is always a real, non-empty string, never `undefined`. Hand-
191
- // verified: mutating both fallbacks to a distinguishing sentinel and
192
- // running the real suite (this file plus
193
- // check-artifacts.test.ts/generate-evidence.test.ts) passes unchanged.
194
- // Stryker disable next-line StringLiteral
195
- (a.key ?? "").localeCompare(b.key ?? "");
182
+ return a.file.localeCompare(b.file) || a.exportName.localeCompare(b.exportName) || String(a.key).localeCompare(String(b.key));
196
183
  }
197
184
  function diffContracts(previous, current) {
198
185
  const previousContracts = new Map((previous ?? []).map((c) => [contractIdentity(c), c]));
@@ -211,25 +198,12 @@ function diffContracts(previous, current) {
211
198
  const changes = genericFieldChanges(
212
199
  previousContract,
213
200
  currentContract,
214
- /* @__PURE__ */ new Set([
215
- // "file"/"exportName" can never actually differ here: both
216
- // contracts of a matched pair share the same Map key
217
- // (`contractIdentity()`), itself derived from file+exportName, so
218
- // they're always structurally equal for two contracts matched
219
- // into one updatedContracts entry. Hand-verified equivalent via
220
- // direct mutation + a real suite run.
221
- // Stryker disable next-line StringLiteral
222
- "file",
223
- // Stryker disable next-line StringLiteral
224
- "exportName",
225
- // Genuinely skipped AND real-tested -- see "does not report the
226
- // whole variables array as a changed field" below.
227
- "variables"
228
- ])
201
+ // `file` and `exportName` cannot differ for a matched pair (they make up its identity).
202
+ /* @__PURE__ */ new Set(["variables"])
229
203
  );
230
204
  if (changes.length > 0) updatedContracts.push({ ...toContractRef(currentContract), changes });
231
205
  }
232
- const previousVariables = new Map((previousContract?.variables ?? []).map((v) => [v.key, v]));
206
+ const previousVariables = new Map(previousContract?.variables.map((v) => [v.key, v]));
233
207
  const currentVariables = new Map(currentContract.variables.map((v) => [v.key, v]));
234
208
  for (const [key, currentVariable] of currentVariables) {
235
209
  const previousVariable = previousVariables.get(key);
@@ -240,16 +214,14 @@ function diffContracts(previous, current) {
240
214
  const changes = genericFieldChanges(
241
215
  previousVariable,
242
216
  currentVariable,
243
- /* @__PURE__ */ new Set(["key"])
217
+ /* @__PURE__ */ new Set()
244
218
  );
245
219
  if (changes.length > 0)
246
220
  updatedVariables.push({ ...toVariableRef(currentContract, currentVariable), changes });
247
221
  }
248
- if (previousContract) {
249
- for (const [key, previousVariable] of previousVariables) {
250
- if (!currentVariables.has(key))
251
- removedVariables.push(toVariableRef(previousContract, previousVariable));
252
- }
222
+ for (const [key, previousVariable] of previousVariables) {
223
+ if (!currentVariables.has(key))
224
+ removedVariables.push(toVariableRef(currentContract, previousVariable));
253
225
  }
254
226
  }
255
227
  for (const [identity, previousContract] of previousContracts) {
@@ -293,7 +265,6 @@ async function writeEvidenceSnapshot(snapshotPath, snapshot, fs) {
293
265
  await fs.writeFile(snapshotPath, `${JSON.stringify(snapshot, null, 2)}
294
266
  `, "utf8");
295
267
  }
296
- var EXPIRY_DAY_COUNT = /\b\d+ day\(s\)/g;
297
268
  function normalizeEvidenceSnapshotForComparison(snapshot) {
298
269
  return {
299
270
  ...snapshot,
@@ -317,7 +288,7 @@ function normalizeEvidenceSnapshotForComparison(snapshot) {
317
288
  finding: {
318
289
  ...snapshot.finding,
319
290
  findings: snapshot.finding.findings.map(
320
- (f) => f.code === "EXPIRED" || f.code === "EXPIRING_SOON" ? { ...f, message: f.message.replace(EXPIRY_DAY_COUNT, "N day(s)") } : f
291
+ (f) => f.code === "EXPIRED" || f.code === "EXPIRING_SOON" ? { ...f, message: f.message.replace(/\b\d+ day\(s\)/g, "N day(s)") } : f
321
292
  )
322
293
  }
323
294
  };
@@ -326,19 +297,22 @@ async function computeEvidenceChanges(root, snapshotPath, activeContracts, curre
326
297
  const read = await readEvidenceSnapshot(snapshotPath, fs);
327
298
  let previous;
328
299
  let readWarning;
329
- if (read.status === "invalid-json") {
330
- readWarning = {
331
- file: snapshotPath,
332
- message: `Evidence snapshot could not be parsed as JSON (${read.detail}); treating this run as if no previous snapshot existed.`
333
- };
334
- } else if (read.status === "unsupported-version") {
335
- readWarning = {
336
- file: snapshotPath,
337
- message: `Evidence snapshot has schemaVersion ${JSON.stringify(read.foundVersion)}, which this version of env-cap does not understand (expected ${EVIDENCE_MODEL_SCHEMA_VERSION}); treating this run as if no previous snapshot existed.`
338
- };
339
- }
340
- if (read.status === "ok") {
341
- previous = read.snapshot;
300
+ switch (read.status) {
301
+ case "ok":
302
+ previous = read.snapshot;
303
+ break;
304
+ case "invalid-json":
305
+ readWarning = {
306
+ file: snapshotPath,
307
+ message: `Evidence snapshot could not be parsed as JSON (${read.detail}); treating this run as if no previous snapshot existed.`
308
+ };
309
+ break;
310
+ case "unsupported-version":
311
+ readWarning = {
312
+ file: snapshotPath,
313
+ message: `Evidence snapshot has schemaVersion ${JSON.stringify(read.foundVersion)}, which this version of env-cap does not understand (expected ${EVIDENCE_MODEL_SCHEMA_VERSION}); treating this run as if no previous snapshot existed.`
314
+ };
315
+ break;
342
316
  }
343
317
  const dynamicAccessAcknowledgments = await buildCitationSnapshots(
344
318
  activeContracts,
@@ -358,30 +332,21 @@ async function computeEvidenceChanges(root, snapshotPath, activeContracts, curre
358
332
  };
359
333
  }
360
334
 
361
- // src/build/glob.ts
335
+ // src/_ipc/glob.ts
362
336
  function globToRegExp(pattern) {
363
337
  let out = "";
364
- let passes = 0;
365
- const maxPasses = pattern.length * 2 + 4;
366
- for (let i = 0; i < pattern.length; i++) {
367
- passes++;
368
- if (passes > maxPasses) {
369
- throw new Error(
370
- // Stryker disable next-line StringLiteral
371
- `globToRegExp: exceeded ${String(maxPasses)} iterations parsing pattern ${JSON.stringify(pattern)} -- this should never happen for any real pattern and indicates an internal parsing bug.`
372
- );
373
- }
374
- const char = pattern[i];
375
- if (char === void 0) continue;
338
+ let resume = 0;
339
+ for (const [i, char] of pattern.split("").entries()) {
340
+ if (i < resume) continue;
376
341
  if (char === "*" && pattern[i + 1] === "*") {
377
342
  const precededBySlashOrStart = i === 0 || pattern[i - 1] === "/";
378
343
  const followedBySlash = pattern[i + 2] === "/";
379
344
  if (precededBySlashOrStart && followedBySlash) {
380
345
  out += "(?:.*/)?";
381
- i += 2;
346
+ resume = i + 3;
382
347
  } else {
383
348
  out += ".*";
384
- i += 1;
349
+ resume = i + 2;
385
350
  }
386
351
  } else if (char === "*") {
387
352
  out += "[^/]*";
@@ -412,7 +377,7 @@ async function discoverSchemaFiles(options) {
412
377
  `discoverSchemaFiles: found ${String(included.length)} files matching "include" under ${options.root} -- more than the ${String(MAX_DISCOVERED_SCHEMA_FILES)}-file sanity limit. This almost always means "root" (or "include"/"exclude") resolved more broadly than intended -- e.g. an omitted "root" falling back to an unexpectedly large process.cwd() -- rather than a real project genuinely declaring this many contracts. Narrow "root"/"include"/"exclude" to the intended project boundary.`
413
378
  );
414
379
  }
415
- return included.map((file) => path6.normalize(file)).sort((a, b) => a < b ? -1 : 1);
380
+ return included.map((file) => path6.normalize(file)).sort();
416
381
  }
417
382
  async function walkDirectory(directory, root, exclude, fs) {
418
383
  const entries = await fs.readdir(directory, { withFileTypes: true });
@@ -438,18 +403,57 @@ function toPosixRelative(root, target) {
438
403
  function matchesAnyPattern(filePath, patterns) {
439
404
  return patterns.some((pattern) => globToRegExp(pattern).test(filePath));
440
405
  }
406
+ function hasClassicApi(candidate) {
407
+ return typeof candidate?.createSourceFile === "function";
408
+ }
409
+ function isModuleNotFound(error, id) {
410
+ const { code, message } = error ?? {};
411
+ if (code !== "MODULE_NOT_FOUND" && code !== "ERR_MODULE_NOT_FOUND") return false;
412
+ return typeof message === "string" && (message.startsWith(`Cannot find module '${id}'`) || message.startsWith(`Cannot find package '${id}'`));
413
+ }
414
+ function tryLoad(load, id) {
415
+ try {
416
+ return load(id);
417
+ } catch (error) {
418
+ if (isModuleNotFound(error, id)) return void 0;
419
+ throw error;
420
+ }
421
+ }
422
+ function pickCompiler(load) {
423
+ const consumer = tryLoad(load, "typescript");
424
+ if (hasClassicApi(consumer)) return consumer;
425
+ const bundled = tryLoad(load, "@typescript/typescript6");
426
+ if (hasClassicApi(bundled)) return bundled;
427
+ return consumer ?? {};
428
+ }
429
+ var ts = pickCompiler(createRequire(import.meta.url));
430
+
431
+ // src/_ipc/compiler-api.ts
432
+ function assertCompilerApi(product, compiler) {
433
+ if (typeof compiler.createSourceFile === "function") return;
434
+ throw new Error(
435
+ `${product}'s build-time scanner needs TypeScript's classic compiler API (typescript ^5 || ^6), but the installed typescript${compiler.version === void 0 ? "" : ` ${compiler.version}`} does not expose it and the bundled @typescript/typescript6 could not be loaded. Reinstall ${product} with its dependencies, or provide a TypeScript 6 compiler: npm install --save-dev typescript@npm:@typescript/typescript6 (this swaps your \`tsc\` for \`tsc6\`; to keep TypeScript 7's \`tsc\`, also add @typescript/native@npm:typescript@^7). See VERSIONING.md, 'Supported toolchain'.`
436
+ );
437
+ }
438
+
439
+ // src/build/compiler-api.ts
440
+ function assertCompilerApi2(compiler) {
441
+ assertCompilerApi("env-cap", compiler);
442
+ }
443
+
444
+ // src/build/literal-eval.ts
441
445
  function evaluateLiteral(node) {
442
- if (ts4.isStringLiteralLike(node)) return { ok: true, value: node.text };
443
- if (ts4.isNumericLiteral(node)) return { ok: true, value: Number(node.text) };
444
- if (node.kind === ts4.SyntaxKind.TrueKeyword) return { ok: true, value: true };
445
- if (node.kind === ts4.SyntaxKind.FalseKeyword) return { ok: true, value: false };
446
- if (node.kind === ts4.SyntaxKind.NullKeyword) return { ok: true, value: null };
447
- if (ts4.isParenthesizedExpression(node)) return evaluateLiteral(node.expression);
448
- if (ts4.isPrefixUnaryExpression(node) && node.operator === ts4.SyntaxKind.MinusToken) {
446
+ if (ts.isStringLiteralLike(node)) return { ok: true, value: node.text };
447
+ if (ts.isNumericLiteral(node)) return { ok: true, value: Number(node.text) };
448
+ if (node.kind === ts.SyntaxKind.TrueKeyword) return { ok: true, value: true };
449
+ if (node.kind === ts.SyntaxKind.FalseKeyword) return { ok: true, value: false };
450
+ if (node.kind === ts.SyntaxKind.NullKeyword) return { ok: true, value: null };
451
+ if (ts.isParenthesizedExpression(node)) return evaluateLiteral(node.expression);
452
+ if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken) {
449
453
  const operand = evaluateLiteral(node.operand);
450
454
  return operand.ok && typeof operand.value === "number" ? { ok: true, value: -operand.value } : { ok: false };
451
455
  }
452
- if (ts4.isArrayLiteralExpression(node)) {
456
+ if (ts.isArrayLiteralExpression(node)) {
453
457
  const values = [];
454
458
  for (const element of node.elements) {
455
459
  const result = evaluateLiteral(element);
@@ -458,10 +462,10 @@ function evaluateLiteral(node) {
458
462
  }
459
463
  return { ok: true, value: values };
460
464
  }
461
- if (ts4.isObjectLiteralExpression(node)) {
465
+ if (ts.isObjectLiteralExpression(node)) {
462
466
  const record = {};
463
467
  for (const prop of node.properties) {
464
- if (!ts4.isPropertyAssignment(prop)) return { ok: false };
468
+ if (!ts.isPropertyAssignment(prop)) return { ok: false };
465
469
  const key = getStaticPropertyName(prop.name);
466
470
  if (key === void 0) return { ok: false };
467
471
  const result = evaluateLiteral(prop.initializer);
@@ -473,20 +477,21 @@ function evaluateLiteral(node) {
473
477
  return { ok: false };
474
478
  }
475
479
  function getStaticPropertyName(name) {
476
- if (ts4.isIdentifier(name)) return name.text;
477
- if (ts4.isStringLiteralLike(name)) return name.text;
478
- if (ts4.isNumericLiteral(name)) return name.text;
480
+ if (ts.isIdentifier(name)) return name.text;
481
+ if (ts.isStringLiteralLike(name)) return name.text;
482
+ if (ts.isNumericLiteral(name)) return name.text;
479
483
  return void 0;
480
484
  }
481
485
 
482
486
  // src/build/parse.ts
483
487
  function parseSchemaFile(filePath, sourceText) {
484
- const sourceFile = ts4.createSourceFile(
488
+ assertCompilerApi2(ts);
489
+ const sourceFile = ts.createSourceFile(
485
490
  filePath,
486
491
  sourceText,
487
- ts4.ScriptTarget.Latest,
492
+ ts.ScriptTarget.Latest,
488
493
  true,
489
- ts4.ScriptKind.TS
494
+ ts.ScriptKind.TS
490
495
  );
491
496
  const warnings = [];
492
497
  const localConsts = /* @__PURE__ */ new Map();
@@ -495,21 +500,21 @@ function parseSchemaFile(filePath, sourceText) {
495
500
  const createEnvCalls = [];
496
501
  const documentEnvCalls = [];
497
502
  for (const statement of sourceFile.statements) {
498
- if (ts4.isImportDeclaration(statement)) {
503
+ if (ts.isImportDeclaration(statement)) {
499
504
  collectImportBindings(statement, imports);
500
505
  continue;
501
506
  }
502
- if (!ts4.isVariableStatement(statement)) continue;
503
- const isExported = statement.modifiers?.some((m) => m.kind === ts4.SyntaxKind.ExportKeyword) ?? false;
507
+ if (!ts.isVariableStatement(statement)) continue;
508
+ const isExported = statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
504
509
  for (const decl of statement.declarationList.declarations) {
505
- if (!ts4.isIdentifier(decl.name) || !decl.initializer) continue;
510
+ if (!ts.isIdentifier(decl.name) || !decl.initializer) continue;
506
511
  const bindingName = decl.name.text;
507
- if (ts4.isObjectLiteralExpression(decl.initializer)) {
512
+ if (ts.isObjectLiteralExpression(decl.initializer)) {
508
513
  localConsts.set(bindingName, decl.initializer);
509
514
  if (isExported) exportedConstNames.add(bindingName);
510
515
  continue;
511
516
  }
512
- if (ts4.isCallExpression(decl.initializer)) {
517
+ if (ts.isCallExpression(decl.initializer)) {
513
518
  if (isCallToName(decl.initializer, "createEnv")) {
514
519
  if (!isExported) {
515
520
  warnings.push({
@@ -537,9 +542,9 @@ function parseSchemaFile(filePath, sourceText) {
537
542
  }
538
543
  }
539
544
  for (const statement of sourceFile.statements) {
540
- if (!ts4.isExpressionStatement(statement)) continue;
545
+ if (!ts.isExpressionStatement(statement)) continue;
541
546
  const expr = statement.expression;
542
- if (!ts4.isCallExpression(expr) || !isCallToName(expr, "documentEnv")) continue;
547
+ if (!ts.isCallExpression(expr) || !isCallToName(expr, "documentEnv")) continue;
543
548
  const [schemaArg, docsArg] = expr.arguments;
544
549
  documentEnvCalls.push({ schemaRef: resolveSchemaRef(schemaArg), docsArg, node: expr });
545
550
  }
@@ -556,15 +561,15 @@ function parseSchemaFile(filePath, sourceText) {
556
561
  }
557
562
  function resolveSchemaRef(node) {
558
563
  if (!node) return { kind: "unresolvable" };
559
- if (ts4.isObjectLiteralExpression(node)) return { kind: "literal", node };
560
- if (ts4.isIdentifier(node)) return { kind: "identifier", name: node.text };
564
+ if (ts.isObjectLiteralExpression(node)) return { kind: "literal", node };
565
+ if (ts.isIdentifier(node)) return { kind: "identifier", name: node.text };
561
566
  return { kind: "unresolvable" };
562
567
  }
563
568
  function collectImportBindings(statement, imports) {
564
- if (!ts4.isStringLiteralLike(statement.moduleSpecifier)) return;
569
+ if (!ts.isStringLiteralLike(statement.moduleSpecifier)) return;
565
570
  const specifier = statement.moduleSpecifier.text;
566
571
  const namedBindings = statement.importClause?.namedBindings;
567
- if (!namedBindings || !ts4.isNamedImports(namedBindings)) return;
572
+ if (!namedBindings || !ts.isNamedImports(namedBindings)) return;
568
573
  for (const element of namedBindings.elements) {
569
574
  const localName = element.name.text;
570
575
  const importedName = element.propertyName?.text ?? localName;
@@ -573,8 +578,8 @@ function collectImportBindings(statement, imports) {
573
578
  }
574
579
  function isCallToName(call, name) {
575
580
  const expr = call.expression;
576
- if (ts4.isIdentifier(expr)) return expr.text === name;
577
- if (ts4.isPropertyAccessExpression(expr)) return expr.name.text === name;
581
+ if (ts.isIdentifier(expr)) return expr.text === name;
582
+ if (ts.isPropertyAccessExpression(expr)) return expr.name.text === name;
578
583
  return false;
579
584
  }
580
585
  function isValidEnvKey(key) {
@@ -583,7 +588,7 @@ function isValidEnvKey(key) {
583
588
  function extractSchemaVariables(schemaLiteral, filePath, contextLabel, warnings, sourceFile) {
584
589
  const variables = [];
585
590
  for (const prop of schemaLiteral.properties) {
586
- if (!ts4.isPropertyAssignment(prop)) {
591
+ if (!ts.isPropertyAssignment(prop)) {
587
592
  warnings.push({
588
593
  file: filePath,
589
594
  message: `Skipped a non-static schema entry in "${contextLabel}" (spread or computed key are not statically analyzable).`
@@ -599,7 +604,7 @@ function extractSchemaVariables(schemaLiteral, filePath, contextLabel, warnings,
599
604
  });
600
605
  continue;
601
606
  }
602
- if (!ts4.isObjectLiteralExpression(prop.initializer)) {
607
+ if (!ts.isObjectLiteralExpression(prop.initializer)) {
603
608
  warnings.push({
604
609
  file: filePath,
605
610
  message: `Definition for "${key}" in "${contextLabel}" is not an inline object literal; skipping static analysis for this variable.`
@@ -623,7 +628,7 @@ function extractSchemaVariable(key, definition, filePath, contextLabel, warnings
623
628
  let validatorSource;
624
629
  let context;
625
630
  for (const prop of definition.properties) {
626
- if (!ts4.isPropertyAssignment(prop)) continue;
631
+ if (!ts.isPropertyAssignment(prop)) continue;
627
632
  const name = getStaticPropertyName(prop.name);
628
633
  if (name === "default") {
629
634
  hasDefault = true;
@@ -661,13 +666,13 @@ function extractSchemaVariable(key, definition, filePath, contextLabel, warnings
661
666
  };
662
667
  }
663
668
  function extractReturnType(node) {
664
- if ((ts4.isArrowFunction(node) || ts4.isFunctionExpression(node)) && node.type) {
665
- return node.type.getText().replace(/\s+/g, "");
669
+ if ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.type) {
670
+ return node.type.getText().replace(/\s/g, "");
666
671
  }
667
672
  return void 0;
668
673
  }
669
674
  function normalizeSource(text) {
670
- return text.replace(/\s+/g, " ").trim();
675
+ return text.replace(/\s+/g, " ");
671
676
  }
672
677
  function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
673
678
  let name;
@@ -686,7 +691,7 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
686
691
  let auditRequired;
687
692
  let metadata;
688
693
  const variables = /* @__PURE__ */ new Map();
689
- if (!docsArg || !ts4.isObjectLiteralExpression(docsArg)) {
694
+ if (!docsArg || !ts.isObjectLiteralExpression(docsArg)) {
690
695
  if (docsArg) {
691
696
  warnings.push({
692
697
  file: filePath,
@@ -713,7 +718,7 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
713
718
  };
714
719
  }
715
720
  for (const prop of docsArg.properties) {
716
- if (!ts4.isPropertyAssignment(prop)) continue;
721
+ if (!ts.isPropertyAssignment(prop)) continue;
717
722
  const propName = getStaticPropertyName(prop.name);
718
723
  if (propName === "name") {
719
724
  const evaluated = evaluateLiteral(prop.initializer);
@@ -817,7 +822,7 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
817
822
  });
818
823
  }
819
824
  } else if (propName === "variables") {
820
- if (ts4.isObjectLiteralExpression(prop.initializer)) {
825
+ if (ts.isObjectLiteralExpression(prop.initializer)) {
821
826
  extractVariableDocsMap(prop.initializer, filePath, contextLabel, warnings, variables);
822
827
  } else {
823
828
  warnings.push({
@@ -848,10 +853,10 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
848
853
  }
849
854
  function extractVariableDocsMap(variablesLiteral, filePath, contextLabel, warnings, out) {
850
855
  for (const prop of variablesLiteral.properties) {
851
- if (!ts4.isPropertyAssignment(prop)) continue;
856
+ if (!ts.isPropertyAssignment(prop)) continue;
852
857
  const key = getStaticPropertyName(prop.name);
853
858
  if (key === void 0) continue;
854
- if (!ts4.isObjectLiteralExpression(prop.initializer)) {
859
+ if (!ts.isObjectLiteralExpression(prop.initializer)) {
855
860
  warnings.push({
856
861
  file: filePath,
857
862
  message: `documentEnv() variable docs for "${key}" in "${contextLabel}" is not an inline object literal; skipped.`
@@ -881,11 +886,9 @@ function extractVariableDocsMap(variablesLiteral, filePath, contextLabel, warnin
881
886
  let metadata;
882
887
  let evidence;
883
888
  for (const field of prop.initializer.properties) {
884
- if (!ts4.isPropertyAssignment(field)) continue;
889
+ if (!ts.isPropertyAssignment(field)) continue;
885
890
  const fieldName = getStaticPropertyName(field.name);
886
- if (fieldName === void 0) continue;
887
891
  const evaluated = evaluateLiteral(field.initializer);
888
- if (!evaluated.ok) continue;
889
892
  if (fieldName === "description" && typeof evaluated.value === "string")
890
893
  description = evaluated.value;
891
894
  else if (fieldName === "owner" && typeof evaluated.value === "string") owner = evaluated.value;
@@ -981,9 +984,9 @@ function extractDynamicAccessCitations(value, filePath, key, contextLabel, warni
981
984
  return citations;
982
985
  }
983
986
  function extractCreateEnvOptionsName(optionsArg) {
984
- if (!optionsArg || !ts4.isObjectLiteralExpression(optionsArg)) return void 0;
987
+ if (!optionsArg || !ts.isObjectLiteralExpression(optionsArg)) return void 0;
985
988
  for (const prop of optionsArg.properties) {
986
- if (!ts4.isPropertyAssignment(prop)) continue;
989
+ if (!ts.isPropertyAssignment(prop)) continue;
987
990
  if (getStaticPropertyName(prop.name) !== "name") continue;
988
991
  const evaluated = evaluateLiteral(prop.initializer);
989
992
  if (evaluated.ok && typeof evaluated.value === "string") return evaluated.value;
@@ -1008,6 +1011,93 @@ function mustGet(map, key) {
1008
1011
  throw new Error(`Internal error: expected key "${String(key)}" to be present in map.`);
1009
1012
  return value;
1010
1013
  }
1014
+
1015
+ // src/build/merge-documentation.ts
1016
+ var VALUE_FIELDS = [
1017
+ "description",
1018
+ "owner",
1019
+ "sensitivity",
1020
+ "expiresAt",
1021
+ "refreshInstructions",
1022
+ "authenticatorType",
1023
+ "rotationPeriod",
1024
+ "lastRotatedAt",
1025
+ "rotationTriggerEvents",
1026
+ "setupInstructions",
1027
+ "required",
1028
+ "deprecated",
1029
+ "deprecatedReason",
1030
+ "removeBy",
1031
+ "renamedFrom",
1032
+ "purpose",
1033
+ "legalBasis",
1034
+ "retention",
1035
+ "dataResidency",
1036
+ "auditRequired"
1037
+ ];
1038
+ function mergeSharedDocumentation(contracts) {
1039
+ const declarationsByKey = /* @__PURE__ */ new Map();
1040
+ for (const contract of contracts) {
1041
+ for (const variable of contract.variables) {
1042
+ const declarations = declarationsByKey.get(variable.key);
1043
+ if (declarations === void 0) declarationsByKey.set(variable.key, [{ contract, variable }]);
1044
+ else declarations.push({ contract, variable });
1045
+ }
1046
+ }
1047
+ return contracts.map((contract) => ({
1048
+ ...contract,
1049
+ variables: contract.variables.map((variable) => {
1050
+ const fromPackages = [];
1051
+ const fromApplication = [];
1052
+ for (const declaration of mustGet(declarationsByKey, variable.key)) {
1053
+ if (declaration.variable === variable) continue;
1054
+ const fromPackage = declaration.contract.packageOrigin !== void 0;
1055
+ if (!fromPackage && contract.packageOrigin === void 0) continue;
1056
+ (fromPackage ? fromPackages : fromApplication).push(declaration);
1057
+ }
1058
+ return fromPackages.length + fromApplication.length === 0 ? variable : filled(variable, fromPackages, fromApplication);
1059
+ })
1060
+ }));
1061
+ }
1062
+ function donated(read, fromPackages, fromApplication) {
1063
+ const fromPackage = fromPackages.find(({ variable }) => read(variable) !== void 0);
1064
+ if (fromPackage !== void 0) return read(fromPackage.variable);
1065
+ const values = fromApplication.map(({ variable }) => read(variable)).filter((v) => v !== void 0);
1066
+ return values.every((value) => deepEqual(value, values[0])) ? values[0] : void 0;
1067
+ }
1068
+ function filled(variable, fromPackages, fromApplication) {
1069
+ const donors = [...fromPackages, ...fromApplication];
1070
+ const merged = { ...variable };
1071
+ for (const field of VALUE_FIELDS) {
1072
+ if (variable[field] !== void 0) continue;
1073
+ merged[field] = donated((other) => other[field], fromPackages, fromApplication);
1074
+ }
1075
+ const metadata = {};
1076
+ for (const key of new Set(
1077
+ donors.flatMap(({ variable: other }) => Object.keys(other.metadata ?? {}))
1078
+ )) {
1079
+ const value = donated((other) => other.metadata?.[key], fromPackages, fromApplication);
1080
+ if (value !== void 0) metadata[key] = value;
1081
+ }
1082
+ Object.assign(metadata, variable.metadata);
1083
+ const result = {
1084
+ ...merged,
1085
+ metadata: Object.keys(metadata).length === 0 ? variable.metadata : metadata,
1086
+ documented: variable.documented || donors.some(({ variable: other }) => other.documented)
1087
+ };
1088
+ DONATED.set(
1089
+ result,
1090
+ /* @__PURE__ */ new Set([
1091
+ ...VALUE_FIELDS.filter((field) => result[field] !== variable[field]),
1092
+ ...Object.keys(metadata).filter((key) => metadata[key] !== variable.metadata?.[key]).map((key) => `metadata.${key}`)
1093
+ ])
1094
+ );
1095
+ return result;
1096
+ }
1097
+ var DONATED = /* @__PURE__ */ new WeakMap();
1098
+ function donatedTo(variable) {
1099
+ return DONATED.get(variable) ?? /* @__PURE__ */ new Set();
1100
+ }
1011
1101
  function isWithinDirectory(baseDir, targetPath) {
1012
1102
  const relative = path6.relative(baseDir, targetPath);
1013
1103
  return relative !== ".." && !relative.startsWith(`..${path6.sep}`) && !path6.isAbsolute(relative);
@@ -1218,13 +1308,15 @@ async function mergeLocalAndPackageFiles(localFiles, packageFiles, fs) {
1218
1308
  }
1219
1309
  async function resolvePackageImport(specifier, allowedPackages, root, cache, fs) {
1220
1310
  const matched = allowedPackages.find(
1221
- // Stryker disable next-line ConditionalExpression
1222
1311
  (pkg) => specifier === pkg || specifier.startsWith(`${pkg}/`)
1223
1312
  );
1224
1313
  if (!matched) return void 0;
1225
1314
  const result = await resolvePackageSchemaFile(matched, root, cache, fs);
1226
1315
  return result.ok ? result.origin.resolvedFile : void 0;
1227
1316
  }
1317
+ function pathMappingOptions(options) {
1318
+ return options;
1319
+ }
1228
1320
  function createAliasResolutionCache() {
1229
1321
  return { resolutions: /* @__PURE__ */ new Map() };
1230
1322
  }
@@ -1235,7 +1327,10 @@ async function fileExists(filePath, fs) {
1235
1327
  }
1236
1328
  return false;
1237
1329
  }
1238
- async function loadTsconfigPaths(root, tsconfigOption, fs) {
1330
+ function typescriptPath(file, separator) {
1331
+ return file.split(separator).join("/");
1332
+ }
1333
+ async function loadTsconfigPaths(product, root, tsconfigOption, fs) {
1239
1334
  if (tsconfigOption === false) return { resolution: void 0, warning: void 0 };
1240
1335
  const isExplicit = tsconfigOption !== void 0;
1241
1336
  const configFile = path6.resolve(root, tsconfigOption ?? "tsconfig.json");
@@ -1249,9 +1344,13 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1249
1344
  }
1250
1345
  };
1251
1346
  }
1252
- const readResult = ts4.readConfigFile(configFile, (p) => ts4.sys.readFile(p));
1347
+ assertCompilerApi(product, ts);
1348
+ const readResult = ts.readConfigFile(
1349
+ typescriptPath(configFile, path6.sep),
1350
+ (p) => ts.sys.readFile(p)
1351
+ );
1253
1352
  if (readResult.error) {
1254
- const detail = ts4.flattenDiagnosticMessageText(readResult.error.messageText, "\n");
1353
+ const detail = ts.flattenDiagnosticMessageText(readResult.error.messageText, ts.sys.newLine);
1255
1354
  return {
1256
1355
  resolution: void 0,
1257
1356
  warning: {
@@ -1260,8 +1359,8 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1260
1359
  }
1261
1360
  };
1262
1361
  }
1263
- const parsed = ts4.parseJsonConfigFileContent(readResult.config, ts4.sys, path6.dirname(configFile));
1264
- const { paths, baseUrl } = parsed.options;
1362
+ const parsed = ts.parseJsonConfigFileContent(readResult.config, ts.sys, path6.dirname(configFile));
1363
+ const { paths, baseUrl } = pathMappingOptions(parsed.options);
1265
1364
  const hasPaths = paths !== void 0 && Object.keys(paths).length > 0;
1266
1365
  if (!hasPaths && baseUrl === void 0) {
1267
1366
  return { resolution: void 0, warning: void 0 };
@@ -1271,7 +1370,7 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1271
1370
  function resolveAliasImport(specifier, importingFile, resolution, cache) {
1272
1371
  const cacheKey = `${importingFile}\0${specifier}`;
1273
1372
  if (cache.resolutions.has(cacheKey)) return cache.resolutions.get(cacheKey);
1274
- const result = ts4.resolveModuleName(specifier, importingFile, resolution.compilerOptions, ts4.sys);
1373
+ const result = ts.resolveModuleName(specifier, importingFile, resolution.compilerOptions, ts.sys);
1275
1374
  const resolvedFileName = result.resolvedModule?.resolvedFileName;
1276
1375
  let resolved;
1277
1376
  if (resolvedFileName) {
@@ -1284,6 +1383,11 @@ function resolveAliasImport(specifier, importingFile, resolution, cache) {
1284
1383
  return resolved;
1285
1384
  }
1286
1385
 
1386
+ // src/build/resolution/resolve-tsconfig-paths.ts
1387
+ function loadTsconfigPaths2(root, tsconfigOption, fs) {
1388
+ return loadTsconfigPaths("env-cap", root, tsconfigOption, fs);
1389
+ }
1390
+
1287
1391
  // src/build/resolution/resolve-import.ts
1288
1392
  async function resolveRelativeImport(importingFile, specifier, fs) {
1289
1393
  if (!specifier.startsWith("./") && !specifier.startsWith("../")) return void 0;
@@ -1299,13 +1403,11 @@ async function resolveRelativeImport(importingFile, specifier, fs) {
1299
1403
  }
1300
1404
  return void 0;
1301
1405
  }
1302
- async function fileExists2(filePath, fs) {
1303
- try {
1304
- const stat = await fs.stat(filePath);
1305
- return stat.isFile();
1306
- } catch {
1307
- return false;
1308
- }
1406
+ function fileExists2(filePath, fs) {
1407
+ return fs.stat(filePath).then(
1408
+ (stat) => stat.isFile(),
1409
+ () => false
1410
+ );
1309
1411
  }
1310
1412
  async function resolveImportSpecifier(importingFile, specifier, context) {
1311
1413
  const relative = await resolveRelativeImport(importingFile, specifier, context.fs);
@@ -1344,24 +1446,29 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1344
1446
  const warnings = [];
1345
1447
  const unresolvedLinks = [];
1346
1448
  async function resolveSchema(ref, inFile, contextLabel) {
1347
- if (ref.kind === "unresolvable") return void 0;
1348
1449
  const inFileAnalysis = mustGet(analysisCache, inFile);
1349
- if (ref.kind === "literal") {
1350
- return {
1351
- identity: `${inFile}#<inline:${ref.node.pos}>`,
1352
- variables: extractSchemaVariables(
1353
- ref.node,
1354
- inFile,
1355
- contextLabel,
1356
- warnings,
1357
- inFileAnalysis.sourceFile
1358
- )
1359
- };
1450
+ switch (ref.kind) {
1451
+ case "literal":
1452
+ return {
1453
+ identity: `${inFile}#<inline:${ref.node.pos}>`,
1454
+ variables: extractSchemaVariables(
1455
+ ref.node,
1456
+ inFile,
1457
+ contextLabel,
1458
+ warnings,
1459
+ inFileAnalysis.sourceFile
1460
+ )
1461
+ };
1462
+ case "identifier":
1463
+ return resolveNamedSchema(ref.name, inFile, inFileAnalysis, contextLabel);
1360
1464
  }
1361
- const local = inFileAnalysis.localConsts.get(ref.name);
1465
+ return void 0;
1466
+ }
1467
+ async function resolveNamedSchema(name, inFile, inFileAnalysis, contextLabel) {
1468
+ const local = inFileAnalysis.localConsts.get(name);
1362
1469
  if (local) {
1363
1470
  return {
1364
- identity: `${inFile}#${ref.name}`,
1471
+ identity: `${inFile}#${name}`,
1365
1472
  variables: extractSchemaVariables(
1366
1473
  local,
1367
1474
  inFile,
@@ -1371,7 +1478,7 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1371
1478
  )
1372
1479
  };
1373
1480
  }
1374
- const imported = inFileAnalysis.imports.get(ref.name);
1481
+ const imported = inFileAnalysis.imports.get(name);
1375
1482
  if (!imported) return void 0;
1376
1483
  const targetFile = await resolveImportSpecifier(inFile, imported.specifier, context);
1377
1484
  if (!targetFile) return void 0;
@@ -1439,7 +1546,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1439
1546
  }
1440
1547
  const contracts = [];
1441
1548
  const undocumentedContracts = [];
1442
- const undocumentedVariables = [];
1443
1549
  const staleDocEntries = [];
1444
1550
  for (const entry of createEnvEntries) {
1445
1551
  const linked = documentEnvByIdentity.get(entry.identity);
@@ -1449,10 +1555,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1449
1555
  }
1450
1556
  const schemaKeys = new Set(entry.variables.map((v) => v.key));
1451
1557
  const docsVariables = docs?.variables ?? /* @__PURE__ */ new Map();
1452
- for (const key of schemaKeys) {
1453
- if (!docsVariables.has(key))
1454
- undocumentedVariables.push({ file: entry.file, exportName: entry.exportName, key });
1455
- }
1456
1558
  for (const key of docsVariables.keys()) {
1457
1559
  if (!schemaKeys.has(key))
1458
1560
  staleDocEntries.push({ file: entry.file, exportName: entry.exportName, key });
@@ -1514,12 +1616,17 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1514
1616
  for (const analysis of analysisCache.values()) {
1515
1617
  warnings.push(...analysis.warnings);
1516
1618
  }
1619
+ const merged = mergeSharedDocumentation(contracts);
1517
1620
  return {
1518
- contracts,
1621
+ contracts: merged,
1519
1622
  warnings,
1520
1623
  unresolvedLinks,
1624
+ // Judged after the merge: a variable a package's contract documents is documented for the application that
1625
+ // declares it again.
1626
+ undocumentedVariables: merged.flatMap(
1627
+ ({ file, exportName, variables }) => variables.filter(({ documented }) => !documented).map(({ key }) => ({ file, exportName, key }))
1628
+ ),
1521
1629
  undocumentedContracts,
1522
- undocumentedVariables,
1523
1630
  staleDocEntries
1524
1631
  };
1525
1632
  }
@@ -1557,7 +1664,7 @@ function effectiveAuditRequired(contract, variable) {
1557
1664
 
1558
1665
  // src/build/assemble-project.ts
1559
1666
  async function assembleProject(options) {
1560
- const { fs, root, include, exclude, packages, tsconfig } = options;
1667
+ const { fs, root, include, exclude, packages = [], tsconfig } = options;
1561
1668
  const fileCache = /* @__PURE__ */ new Map();
1562
1669
  const readFileCached = (filePath) => {
1563
1670
  let cached = fileCache.get(filePath);
@@ -1579,7 +1686,7 @@ async function assembleProject(options) {
1579
1686
  packageFiles.map((f) => f.file),
1580
1687
  fs
1581
1688
  );
1582
- const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths(
1689
+ const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths2(
1583
1690
  root,
1584
1691
  tsconfig,
1585
1692
  fs
@@ -1614,7 +1721,6 @@ function buildChangeModel(manifest, currentContracts, root) {
1614
1721
  const relativeFile = displayPath(root, contract.file);
1615
1722
  const cIdentity = contractIdentity2(relativeFile, contract.exportName);
1616
1723
  for (const variable of contract.variables) {
1617
- if (!variable.renamedFrom) continue;
1618
1724
  const addedRef = findByContractAndKey(
1619
1725
  manifest.addedVariables,
1620
1726
  relativeFile,
@@ -1645,24 +1751,20 @@ function buildChangeModel(manifest, currentContracts, root) {
1645
1751
  }
1646
1752
 
1647
1753
  // src/build/compatibility.ts
1648
- var DOCUMENTATION_COMPARISON_FIELDS = [
1649
- "description",
1650
- "owner",
1651
- "sensitivity",
1652
- "expiresAt",
1653
- "refreshInstructions",
1654
- "setupInstructions",
1655
- "required"
1656
- ];
1657
1754
  function documentationDivergences(a, b) {
1658
1755
  const divergences = [];
1659
- for (const field of DOCUMENTATION_COMPARISON_FIELDS) {
1660
- if (a[field] !== b[field]) divergences.push(field);
1756
+ const given = /* @__PURE__ */ new Set([...donatedTo(a), ...donatedTo(b)]);
1757
+ for (const field of VALUE_FIELDS) {
1758
+ if (!given.has(field) && a[field] !== void 0 && b[field] !== void 0 && !deepEqual(a[field], b[field])) {
1759
+ divergences.push(field);
1760
+ }
1661
1761
  }
1662
1762
  const aMetadata = a.metadata ?? {};
1663
1763
  const bMetadata = b.metadata ?? {};
1664
- for (const key of /* @__PURE__ */ new Set([...Object.keys(aMetadata), ...Object.keys(bMetadata)])) {
1665
- if (!deepEqual(aMetadata[key], bMetadata[key])) divergences.push(`metadata.${key}`);
1764
+ for (const key of Object.keys(aMetadata)) {
1765
+ if (!given.has(`metadata.${key}`) && key in bMetadata && !deepEqual(aMetadata[key], bMetadata[key])) {
1766
+ divergences.push(`metadata.${key}`);
1767
+ }
1666
1768
  }
1667
1769
  return divergences;
1668
1770
  }
@@ -1709,17 +1811,15 @@ function detectCompatibilityIssues(contracts) {
1709
1811
  reason: `"${a.contractName}" and "${b.contractName}" both declare a validator for this variable with different implementations. Validator logic cannot be statically compared -- confirm they enforce compatible rules.`
1710
1812
  });
1711
1813
  }
1712
- if (a.variable.documented && b.variable.documented) {
1713
- const divergences = documentationDivergences(a.variable, b.variable);
1714
- if (divergences.length > 0) {
1715
- issues.push({
1716
- severity: "warning",
1717
- variable: key,
1718
- files: [a.file, b.file],
1719
- code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1720
- reason: `"${a.contractName}" and "${b.contractName}" both document this variable, but disagree on: ${divergences.join(", ")}. Confirm they're still meant to be the same variable and align the documentation, or document them separately if they're not.`
1721
- });
1722
- }
1814
+ const divergences = documentationDivergences(a.variable, b.variable);
1815
+ if (divergences.length > 0) {
1816
+ issues.push({
1817
+ severity: "warning",
1818
+ variable: key,
1819
+ files: [a.file, b.file],
1820
+ code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1821
+ reason: `"${a.contractName}" and "${b.contractName}" both document this variable, but disagree on: ${divergences.join(", ")}. Confirm they're still meant to be the same variable and align the documentation, or document them separately if they're not.`
1822
+ });
1723
1823
  }
1724
1824
  }
1725
1825
  }
@@ -1740,8 +1840,7 @@ function variableShape(variable) {
1740
1840
  };
1741
1841
  }
1742
1842
  function shapesMatch(a, b) {
1743
- if (a.valueType === "unknown" || b.valueType === "unknown") return false;
1744
- return a.valueType === b.valueType && a.hasProcessor === b.hasProcessor && a.hasValidator === b.hasValidator;
1843
+ return a.valueType !== "unknown" && a.valueType === b.valueType && a.hasProcessor === b.hasProcessor && a.hasValidator === b.hasValidator;
1745
1844
  }
1746
1845
  function detectDuplicateVariableShapes(contracts) {
1747
1846
  const candidates = contracts.filter((c) => c.active && !c.exclusiveGroup);
@@ -1880,60 +1979,55 @@ function isPlainObject(value) {
1880
1979
  const proto = Object.getPrototypeOf(value);
1881
1980
  return proto === Object.prototype || proto === null;
1882
1981
  }
1982
+
1983
+ // src/build/scan-dependencies.ts
1883
1984
  function unwrapParens(node) {
1884
1985
  let current = node;
1885
- while (ts4.isParenthesizedExpression(current)) current = current.expression;
1986
+ while (ts.isParenthesizedExpression(current)) current = current.expression;
1886
1987
  return current;
1887
1988
  }
1888
1989
  function staticElementKey(node) {
1889
- return ts4.isStringLiteralLike(node) ? node.text : void 0;
1990
+ return ts.isStringLiteralLike(node) ? node.text : void 0;
1890
1991
  }
1891
1992
  function forEachBindingName(name, record) {
1892
- if (ts4.isIdentifier(name)) {
1993
+ if (ts.isIdentifier(name)) {
1893
1994
  record(name.text);
1894
1995
  return;
1895
1996
  }
1896
1997
  for (const element of name.elements) {
1897
- if (ts4.isOmittedExpression(element)) continue;
1998
+ if (ts.isOmittedExpression(element)) continue;
1898
1999
  forEachBindingName(element.name, record);
1899
2000
  }
1900
2001
  }
1901
2002
  function isAssignmentToken(token) {
1902
- return token >= ts4.SyntaxKind.FirstAssignment && token <= ts4.SyntaxKind.LastAssignment;
2003
+ return token >= ts.SyntaxKind.FirstAssignment && token <= ts.SyntaxKind.LastAssignment;
1903
2004
  }
1904
2005
  function recordIfIdentifierTarget(expression, assignedNames) {
1905
2006
  const target = unwrapParens(expression);
1906
- if (ts4.isIdentifier(target)) assignedNames.add(target.text);
2007
+ if (ts.isIdentifier(target)) assignedNames.add(target.text);
1907
2008
  }
1908
2009
  function recordAssignmentTargets(node, assignedNames) {
1909
- if (ts4.isBinaryExpression(node) && isAssignmentToken(node.operatorToken.kind)) {
2010
+ if (ts.isBinaryExpression(node) && isAssignmentToken(node.operatorToken.kind)) {
1910
2011
  recordIfIdentifierTarget(node.left, assignedNames);
1911
2012
  return;
1912
2013
  }
1913
- if (
1914
- // Widening this to `true` is behaviorally equivalent, not a real gap:
1915
- // only a prefix/postfix unary node carries an `.operator` at all, so on
1916
- // any other node the two `=== PlusPlus/MinusMinus` checks below both
1917
- // read `undefined` and fail. Hand-verified: mutating this compound to
1918
- // `if (true)` and running the real suite passes unchanged.
1919
- // Stryker disable next-line ConditionalExpression
1920
- (ts4.isPrefixUnaryExpression(node) || ts4.isPostfixUnaryExpression(node)) && (node.operator === ts4.SyntaxKind.PlusPlusToken || node.operator === ts4.SyntaxKind.MinusMinusToken)
1921
- ) {
1922
- recordIfIdentifierTarget(node.operand, assignedNames);
2014
+ const { operator, operand } = node;
2015
+ if (operator === ts.SyntaxKind.PlusPlusToken || operator === ts.SyntaxKind.MinusMinusToken) {
2016
+ recordIfIdentifierTarget(operand, assignedNames);
1923
2017
  return;
1924
2018
  }
1925
- if ((ts4.isForOfStatement(node) || ts4.isForInStatement(node)) && !ts4.isVariableDeclarationList(node.initializer)) {
2019
+ if ((ts.isForOfStatement(node) || ts.isForInStatement(node)) && !ts.isVariableDeclarationList(node.initializer)) {
1926
2020
  recordIfIdentifierTarget(node.initializer, assignedNames);
1927
2021
  }
1928
2022
  }
1929
2023
  function recordDeclarationIntroduction(node, countDeclaration, constAliasCandidates) {
1930
- if (ts4.isVariableDeclaration(node) || ts4.isParameter(node)) {
2024
+ if (ts.isVariableDeclaration(node) || ts.isParameter(node)) {
1931
2025
  forEachBindingName(node.name, countDeclaration);
1932
- if (!ts4.isVariableDeclaration(node) || !ts4.isIdentifier(node.name)) return;
2026
+ if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name)) return;
1933
2027
  if (node.initializer === void 0) return;
1934
2028
  const initializer = unwrapParens(node.initializer);
1935
- const isConst = (ts4.getCombinedNodeFlags(node) & ts4.NodeFlags.Const) !== 0;
1936
- if (isConst && ts4.isIdentifier(initializer)) {
2029
+ const isConst = (ts.getCombinedNodeFlags(node) & ts.NodeFlags.Const) !== 0;
2030
+ if (isConst && ts.isIdentifier(initializer)) {
1937
2031
  constAliasCandidates.push({
1938
2032
  aliasName: node.name.text,
1939
2033
  baseName: initializer.text,
@@ -1942,7 +2036,7 @@ function recordDeclarationIntroduction(node, countDeclaration, constAliasCandida
1942
2036
  }
1943
2037
  return;
1944
2038
  }
1945
- if ((ts4.isFunctionDeclaration(node) || ts4.isClassDeclaration(node)) && node.name) {
2039
+ if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) {
1946
2040
  countDeclaration(node.name.text);
1947
2041
  }
1948
2042
  }
@@ -1956,9 +2050,9 @@ function collectDeclarationFacts(sourceFile) {
1956
2050
  function walk(node) {
1957
2051
  recordDeclarationIntroduction(node, countDeclaration, constAliasCandidates);
1958
2052
  recordAssignmentTargets(node, assignedNames);
1959
- ts4.forEachChild(node, walk);
2053
+ ts.forEachChild(node, walk);
1960
2054
  }
1961
- ts4.forEachChild(sourceFile, walk);
2055
+ ts.forEachChild(sourceFile, walk);
1962
2056
  return { declarationCounts, assignedNames, constAliasCandidates };
1963
2057
  }
1964
2058
  function resolveAliasTargets(candidates, declarationCounts, assignedNames, imports) {
@@ -1983,21 +2077,22 @@ function bindingElementKey(element) {
1983
2077
  if (element.propertyName === void 0) {
1984
2078
  return element.name.text;
1985
2079
  }
1986
- if (ts4.isIdentifier(element.propertyName) || ts4.isStringLiteral(element.propertyName)) {
2080
+ if (ts.isIdentifier(element.propertyName) || ts.isStringLiteral(element.propertyName)) {
1987
2081
  return element.propertyName.text;
1988
2082
  }
1989
- if (ts4.isComputedPropertyName(element.propertyName)) {
2083
+ if (ts.isComputedPropertyName(element.propertyName)) {
1990
2084
  const inner = element.propertyName.expression;
1991
- return ts4.isStringLiteralLike(inner) ? inner.text : inner;
2085
+ return ts.isStringLiteralLike(inner) ? inner.text : inner;
1992
2086
  }
1993
2087
  return element.propertyName;
1994
2088
  }
1995
2089
  function scanFileForDependencies(filePath, sourceText) {
1996
- const scriptKind = filePath.endsWith(".tsx") ? ts4.ScriptKind.TSX : ts4.ScriptKind.TS;
1997
- const sourceFile = ts4.createSourceFile(
2090
+ assertCompilerApi2(ts);
2091
+ const scriptKind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
2092
+ const sourceFile = ts.createSourceFile(
1998
2093
  filePath,
1999
2094
  sourceText,
2000
- ts4.ScriptTarget.Latest,
2095
+ ts.ScriptTarget.Latest,
2001
2096
  // Load-bearing, unlike before: `ts.getCombinedNodeFlags()` (used to tell
2002
2097
  // a `const` declaration apart from `let`/`var` when resolving alias
2003
2098
  // candidates) walks parent pointers internally. Flipping this to `false`
@@ -2009,9 +2104,9 @@ function scanFileForDependencies(filePath, sourceText) {
2009
2104
  const imports = /* @__PURE__ */ new Map();
2010
2105
  let hasWildcardReExport = false;
2011
2106
  for (const statement of sourceFile.statements) {
2012
- if (ts4.isImportDeclaration(statement)) {
2107
+ if (ts.isImportDeclaration(statement)) {
2013
2108
  collectImportBindings(statement, imports);
2014
- } else if (ts4.isExportDeclaration(statement) && !statement.exportClause && statement.moduleSpecifier) {
2109
+ } else if (ts.isExportDeclaration(statement) && !statement.exportClause && statement.moduleSpecifier) {
2015
2110
  hasWildcardReExport = true;
2016
2111
  }
2017
2112
  }
@@ -2042,7 +2137,7 @@ function scanFileForDependencies(filePath, sourceText) {
2042
2137
  for (const element of pattern.elements) {
2043
2138
  if (element.dotDotDotToken) {
2044
2139
  record(localName, { kind: "escape", via: "rest", ...positionOf(sourceFile, element) });
2045
- } else if (!ts4.isIdentifier(element.name)) {
2140
+ } else if (!ts.isIdentifier(element.name)) {
2046
2141
  record(localName, {
2047
2142
  kind: "escape",
2048
2143
  via: "nested-pattern",
@@ -2058,17 +2153,17 @@ function scanFileForDependencies(filePath, sourceText) {
2058
2153
  via: "computed-key",
2059
2154
  ...positionOf(sourceFile, element)
2060
2155
  });
2061
- ts4.forEachChild(key, visit);
2156
+ ts.forEachChild(key, visit);
2062
2157
  }
2063
2158
  }
2064
- if (element.initializer) ts4.forEachChild(element.initializer, visit);
2159
+ ts.forEachChild(element.initializer, visit);
2065
2160
  }
2066
2161
  }
2067
2162
  function tryRecordPropertyOrElementAccess(node) {
2068
- const isProperty = ts4.isPropertyAccessExpression(node);
2069
- if (!isProperty && !ts4.isElementAccessExpression(node)) return false;
2163
+ const isProperty = ts.isPropertyAccessExpression(node);
2164
+ if (!isProperty && !ts.isElementAccessExpression(node)) return false;
2070
2165
  const base = unwrapParens(node.expression);
2071
- if (!ts4.isIdentifier(base) || !imports.has(base.text)) return false;
2166
+ if (!ts.isIdentifier(base) || !imports.has(base.text)) return false;
2072
2167
  if (isProperty) {
2073
2168
  record(base.text, { kind: "member", member: node.name.text, ...positionOf(sourceFile, node) });
2074
2169
  return true;
@@ -2078,49 +2173,92 @@ function scanFileForDependencies(filePath, sourceText) {
2078
2173
  base.text,
2079
2174
  key !== void 0 ? { kind: "member", member: key, ...positionOf(sourceFile, node) } : { kind: "dynamic", ...positionOf(sourceFile, node) }
2080
2175
  );
2081
- ts4.forEachChild(node.argumentExpression, visit);
2176
+ ts.forEachChild(node.argumentExpression, visit);
2082
2177
  return true;
2083
2178
  }
2084
2179
  function visit(node) {
2085
- if (ts4.isImportDeclaration(node) || ts4.isExportDeclaration(node) || ts4.isVariableDeclaration(node) && handledDeclarations.has(node)) {
2180
+ if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node) || ts.isVariableDeclaration(node) && handledDeclarations.has(node)) {
2086
2181
  return;
2087
2182
  }
2088
- if (ts4.isVariableDeclaration(node) && ts4.isObjectBindingPattern(node.name) && node.initializer) {
2183
+ if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer) {
2089
2184
  const base = unwrapParens(node.initializer);
2090
- if (ts4.isIdentifier(base) && imports.has(base.text)) {
2185
+ if (ts.isIdentifier(base) && imports.has(base.text)) {
2091
2186
  recordObjectBindingAccesses(node.name, base.text);
2092
2187
  return;
2093
2188
  }
2094
2189
  }
2095
2190
  if (tryRecordPropertyOrElementAccess(node)) return;
2096
- if (ts4.isIdentifier(node) && imports.has(node.text)) {
2191
+ if (ts.isIdentifier(node) && imports.has(node.text)) {
2097
2192
  record(node.text, { kind: "reference", ...positionOf(sourceFile, node) });
2098
2193
  return;
2099
2194
  }
2100
- ts4.forEachChild(node, visit);
2195
+ ts.forEachChild(node, visit);
2101
2196
  }
2102
- ts4.forEachChild(sourceFile, visit);
2197
+ ts.forEachChild(sourceFile, visit);
2103
2198
  return { file: filePath, imports, accessesByLocalName: accesses, hasWildcardReExport };
2104
2199
  }
2105
2200
 
2201
+ // src/_ipc/generated-banner.ts
2202
+ function marker() {
2203
+ return "GENERATED FILE -- do not edit by hand";
2204
+ }
2205
+ function createGeneratedBanner(describe) {
2206
+ return {
2207
+ reportRegenerateHint: () => describe().reportRegenerateHint,
2208
+ generatedBanner: (format = "ts", regenerate = `Run \`${describe().cliCommand}\` to regenerate.`) => {
2209
+ const text = `${marker()}. ${regenerate}`;
2210
+ return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2211
+ },
2212
+ // Not a bare `startsWith`: a shebang, a `"use strict"` pragma or a license header pushes a real marker
2213
+ // off line one, and a stricter check would read a genuinely generated file as hand-written, which a
2214
+ // dependency scan would take as "a real consumer imports this" and so permanently mask an abandoned
2215
+ // contract. The first 20 non-empty lines clear every realistic preamble without scanning a whole file.
2216
+ // A line counts only when the marker opens a comment, as `generatedBanner` writes it, so code or prose that
2217
+ // merely quotes the marker is not mistaken for a generated file.
2218
+ isGeneratedFile: (content) => {
2219
+ let seen = 0;
2220
+ for (const [line] of content.matchAll(/[^\n]*/g)) {
2221
+ const text = line.trimStart();
2222
+ if (text === "") continue;
2223
+ if (text.startsWith(`// ${marker()}`) || text.startsWith(`<!-- ${marker()}`)) return true;
2224
+ seen += 1;
2225
+ if (seen === 20) break;
2226
+ }
2227
+ return false;
2228
+ },
2229
+ evidenceDisclaimer: () => "Machine-generated engineering artifact assembled from statically-provable code facts and author-declared documentation. It can support a security, privacy, or compliance review. It does not itself establish compliance with any standard.",
2230
+ evidenceProjectionNote: (evidencePath) => {
2231
+ const { product, guideUrl } = describe();
2232
+ const concept = `Projected from ${product}'s Evidence Model (${guideUrl}), the same source every other generated artifact draws from.`;
2233
+ return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2234
+ }
2235
+ };
2236
+ }
2237
+
2106
2238
  // src/build/generated-banner.ts
2107
- function generatedFileMarker() {
2108
- return "GENERATED FILE";
2239
+ function envCap() {
2240
+ return {
2241
+ product: "env-cap",
2242
+ guideUrl: "https://github.com/MaverickCER/env-cap/blob/main/GUIDE.md",
2243
+ cliCommand: "npx env-cap",
2244
+ reportRegenerateHint: "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`."
2245
+ };
2109
2246
  }
2110
- function generatedBanner(format = "ts") {
2111
- const text = `${generatedFileMarker()} -- do not edit by hand. Run \`npx env-cap\` to regenerate.`;
2112
- return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2247
+ var banner = createGeneratedBanner(envCap);
2248
+ function reportRegenerateHint() {
2249
+ return banner.reportRegenerateHint();
2250
+ }
2251
+ function generatedBanner(format, regenerate) {
2252
+ return banner.generatedBanner(format, regenerate);
2113
2253
  }
2114
2254
  function isGeneratedFile(content) {
2115
- const nonEmptyLines = content.split("\n").filter((line) => line.trim().length > 0);
2116
- return nonEmptyLines.slice(0, 20).some((line) => line.includes(generatedFileMarker()));
2255
+ return banner.isGeneratedFile(content);
2117
2256
  }
2118
2257
  function evidenceDisclaimer() {
2119
- return "Machine-generated engineering artifact assembled from statically-provable code facts and author-declared documentation. It can support a security, privacy, or compliance review. It does not itself establish compliance with any standard.";
2258
+ return banner.evidenceDisclaimer();
2120
2259
  }
2121
2260
  function evidenceProjectionNote(evidencePath) {
2122
- const concept = "Projected from env-cap's Evidence Model (ADR 0031/0038), the same source every other generated artifact draws from.";
2123
- return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2261
+ return banner.evidenceProjectionNote(evidencePath);
2124
2262
  }
2125
2263
 
2126
2264
  // src/build/dependency-graph.ts
@@ -2230,8 +2368,7 @@ async function buildDependencyGraph(contracts, scanFiles, readFile, context, sca
2230
2368
  for (const scan of scanResults) {
2231
2369
  for (const [localName, binding] of scan.imports) {
2232
2370
  const resolvedFile = await resolveImportSpecifier(scan.file, binding.specifier, context);
2233
- if (!resolvedFile) continue;
2234
- const building = byIdentity2.get(`${resolvedFile}#${binding.importedName}`);
2371
+ const building = byIdentity2.get(`${String(resolvedFile)}#${binding.importedName}`);
2235
2372
  if (!building) continue;
2236
2373
  building.imported = true;
2237
2374
  building.consumingFiles.add(scan.file);
@@ -2241,8 +2378,7 @@ async function buildDependencyGraph(contracts, scanFiles, readFile, context, sca
2241
2378
  for (const scan of scanResults) {
2242
2379
  for (const [, binding] of scan.imports) {
2243
2380
  const resolvedFile = await resolveImportSpecifier(scan.file, binding.specifier, context);
2244
- if (!resolvedFile) continue;
2245
- const targetScan = scanByFile.get(resolvedFile);
2381
+ const targetScan = scanByFile.get(String(resolvedFile));
2246
2382
  if (!targetScan?.hasWildcardReExport) continue;
2247
2383
  for (const building of byIdentity2.values()) {
2248
2384
  if (building.imported) continue;
@@ -2345,20 +2481,9 @@ async function buildDependencyModel(contracts, scanFiles, readFile, context, roo
2345
2481
  positions: info.positions.map((p) => relativizePosition2(root, p)),
2346
2482
  dynamicAccessAssertions: info.dynamicAccessAssertions
2347
2483
  })).sort((a, b) => a.key.localeCompare(b.key)),
2348
- // `.sort()` here (and the whole `.map(...).sort()` chain as one
2349
- // `MethodExpression` unit) is a defensive no-op, not a real gap:
2350
- // dependency-graph.ts's own `consumingFiles` is already
2351
- // `[...building.consumingFiles].sort()` before this projection ever
2352
- // sees it (see that file's own comment). Hand-verified: dropping this
2353
- // `.sort()` and running the real suite passes unchanged -- confirmed
2354
- // again 2026-09-18 against CI's own diagnostic mutation report, which
2355
- // flagged this exact `MethodExpression` mutant as Survived.
2356
- // Stryker disable next-line MethodExpression
2484
+ // Sorted after mapping to display paths: a file outside `root` (a package surface) shows as
2485
+ // `../...`, which can order differently from its absolute path.
2357
2486
  consumingFiles: [...contract.consumingFiles].map((f) => displayPath(root, f)).sort(),
2358
- // Same reasoning as `consumingFiles` just above -- the whole
2359
- // `.map(...).sort()` chain is a coarser-grained `MethodExpression`
2360
- // mutant target than the next-line one on `.sort()` alone just below.
2361
- // Stryker disable next-line MethodExpression
2362
2487
  ambiguousBarrelFiles: [...contract.ambiguousBarrelFiles].map((f) => displayPath(root, f)).sort(),
2363
2488
  dynamicAccessSites: contract.dynamicAccessSites.map((p) => relativizePosition2(root, p))
2364
2489
  }));
@@ -2512,30 +2637,11 @@ function renderManifest(contracts, outputFile) {
2512
2637
  for (const contract of sorted) {
2513
2638
  let localName = contract.exportName;
2514
2639
  if (usedNames.has(localName)) {
2515
- const maxSuffix = sorted.length + 16;
2516
- let found;
2517
- let passes = 0;
2518
- for (let suffix = 1; suffix <= maxSuffix; suffix++) {
2519
- passes++;
2520
- if (passes > maxSuffix) {
2521
- throw new Error(
2522
- // Stryker disable next-line StringLiteral
2523
- `renderManifest: exceeded ${String(maxSuffix)} attempts choosing a unique local import name for "${contract.exportName}" -- this should never happen and indicates an internal naming bug.`
2524
- );
2525
- }
2526
- const candidate = `${contract.exportName}_${suffix}`;
2527
- if (!usedNames.has(candidate)) {
2528
- found = candidate;
2529
- break;
2530
- }
2531
- }
2532
- if (found === void 0) {
2533
- throw new Error(
2534
- // Stryker disable next-line StringLiteral
2535
- `renderManifest: could not find a unique local import name for "${contract.exportName}" within ${String(maxSuffix)} attempts -- this should never happen and indicates an internal naming bug.`
2536
- );
2537
- }
2538
- localName = found;
2640
+ const candidates = Array.from(
2641
+ { length: usedNames.size + 1 },
2642
+ (_, index) => `${contract.exportName}_${index + 1}`
2643
+ );
2644
+ localName = String(candidates.find((candidate) => !usedNames.has(candidate)));
2539
2645
  }
2540
2646
  usedNames.add(localName);
2541
2647
  referenceNames.push(localName);
@@ -2584,10 +2690,8 @@ function defaultExclude() {
2584
2690
  // inspect `exclude` directly, and as defense if that hardcoding ever
2585
2691
  // changes) -- hand-verified: emptying both and running the full
2586
2692
  // `vitest run` leaves all 1243 tests passing.
2587
- // Stryker disable next-line StringLiteral
2588
2693
  "**/node_modules/**",
2589
2694
  "**/dist/**",
2590
- // Stryker disable next-line StringLiteral
2591
2695
  "**/.git/**"
2592
2696
  ];
2593
2697
  }
@@ -2617,8 +2721,6 @@ async function generateEnvManifest(options) {
2617
2721
  const root = path6.resolve(options.root ?? process.cwd());
2618
2722
  const include = options.include ?? defaultInclude();
2619
2723
  const exclude = options.exclude ?? defaultExclude();
2620
- const packages = options.packages ?? [];
2621
- const onIncompatibility = options.onIncompatibility ?? "warn";
2622
2724
  const locationResult = resolveWithinRoot(
2623
2725
  root,
2624
2726
  options.location,
@@ -2632,10 +2734,10 @@ async function generateEnvManifest(options) {
2632
2734
  root,
2633
2735
  include,
2634
2736
  exclude,
2635
- packages,
2737
+ packages: options.packages,
2636
2738
  tsconfig: options.tsconfig
2637
2739
  });
2638
- const computed = computeManifest(root, linkResult, onIncompatibility);
2740
+ const computed = computeManifest(root, linkResult, options.onIncompatibility);
2639
2741
  if (computed.blocking.length > 0) throw new EnvManifestGenerationError(computed.blocking);
2640
2742
  await writeManifest(outputPath, computed.activeContracts, options.fs);
2641
2743
  return {
@@ -2775,7 +2877,7 @@ function renderParseWarnings(warnings) {
2775
2877
  }
2776
2878
  function renderUsageReport(computed) {
2777
2879
  const lines = [
2778
- generatedBanner("markdown"),
2880
+ generatedBanner("markdown", reportRegenerateHint()),
2779
2881
  "",
2780
2882
  `> ${evidenceDisclaimer()}`,
2781
2883
  "",
@@ -2783,7 +2885,7 @@ function renderUsageReport(computed) {
2783
2885
  "",
2784
2886
  "# Dependency & Ownership Report",
2785
2887
  "",
2786
- "_Produced by `env-cap --ownership`._",
2888
+ "_Produced by `generateUsageReport()` from `@maverickcer/env-cap/build`._",
2787
2889
  "",
2788
2890
  "Which feature owns each variable, which features consume that contract, and what the blast radius is if it changes.",
2789
2891
  "",
@@ -2795,7 +2897,7 @@ function renderUsageReport(computed) {
2795
2897
  ...renderAsserted(computed.asserted),
2796
2898
  ...renderParseWarnings(computed.parseWarnings)
2797
2899
  ];
2798
- return lines.join("\n").replace(/\n{3,}/g, "\n\n");
2900
+ return lines.join("\n");
2799
2901
  }
2800
2902
 
2801
2903
  // src/build/generate-usage.ts
@@ -2826,7 +2928,7 @@ async function computeScanSurface(root, exclude, origins, fs) {
2826
2928
  }
2827
2929
  return { scanFiles, scannedSurfaces };
2828
2930
  }
2829
- async function computeUsage(root, contracts, scanFiles, readFile, context, parseWarnings, scannedSurfaces, dynamicAccessAcknowledgments) {
2931
+ async function computeUsage(root, contracts, scanFiles, readFile, context, scannedSurfaces, dynamicAccessAcknowledgments) {
2830
2932
  const graph = await buildDependencyGraph(
2831
2933
  contracts,
2832
2934
  scanFiles,
@@ -2839,13 +2941,9 @@ async function computeUsage(root, contracts, scanFiles, readFile, context, parse
2839
2941
  const contractByIdentity = /* @__PURE__ */ new Map();
2840
2942
  for (const contract of contracts)
2841
2943
  contractByIdentity.set(`${contract.file}#${contract.exportName}`, contract);
2842
- const ownerFor = (file, exportName) => (
2843
- // Stryker disable next-line OptionalChaining
2844
- contractByIdentity.get(`${file}#${exportName}`)?.owner
2845
- );
2944
+ const ownerFor = (file, exportName) => mustGet(contractByIdentity, `${file}#${exportName}`).owner;
2846
2945
  const effectiveOwnerFor = (file, exportName, key) => {
2847
- const contract = contractByIdentity.get(`${file}#${exportName}`);
2848
- if (!contract) return void 0;
2946
+ const contract = mustGet(contractByIdentity, `${file}#${exportName}`);
2849
2947
  const variable = contract.variables.find((v) => v.key === key);
2850
2948
  return variable ? effectiveOwner(contract, variable) : contract.owner;
2851
2949
  };
@@ -2871,19 +2969,16 @@ async function computeUsage(root, contracts, scanFiles, readFile, context, parse
2871
2969
  const staleOrMissingCitationsFor = (contractName, file, exportName, key) => {
2872
2970
  const relativeFile = displayPath(root, file);
2873
2971
  const identity = dynamicAccessVariableIdentity(relativeFile, exportName, key);
2874
- const problems = [];
2875
- for (const a of dynamicAccessAcknowledgments?.get(identity) ?? []) {
2876
- if (a.acknowledgment === "fresh") continue;
2877
- problems.push({
2972
+ return (dynamicAccessAcknowledgments?.get(identity) ?? []).map(
2973
+ (a) => ({
2878
2974
  contractName,
2879
2975
  file: relativeFile,
2880
2976
  exportName,
2881
2977
  key,
2882
2978
  position: { file: a.file, line: a.line, column: a.column },
2883
2979
  acknowledgment: a.acknowledgment
2884
- });
2885
- }
2886
- return problems;
2980
+ })
2981
+ );
2887
2982
  };
2888
2983
  const unconsumedOwnedVariables = findings.unconsumedOwned.map(
2889
2984
  (f) => ({
@@ -2928,7 +3023,6 @@ async function computeUsage(root, contracts, scanFiles, readFile, context, parse
2928
3023
  unconsumedOwnedVariables,
2929
3024
  indeterminate,
2930
3025
  asserted,
2931
- parseWarnings,
2932
3026
  scannedSurfaces: graph.scannedSurfaces
2933
3027
  }
2934
3028
  };
@@ -2942,24 +3036,23 @@ async function generateUsageReport(options) {
2942
3036
  const root = path6.resolve(options.root ?? process.cwd());
2943
3037
  const include = options.include ?? defaultInclude();
2944
3038
  const exclude = options.exclude ?? defaultExclude();
2945
- const packages = options.packages ?? [];
2946
3039
  let reportPath;
2947
3040
  if (options.report) {
2948
- const result = resolveWithinRoot(
3041
+ const result2 = resolveWithinRoot(
2949
3042
  root,
2950
3043
  options.report.location,
2951
3044
  "report.location",
2952
3045
  "generateUsageReport"
2953
3046
  );
2954
- if (!result.ok) throw new EnvUsageAnalysisError([result.issue]);
2955
- reportPath = result.resolved;
3047
+ if (!result2.ok) throw new EnvUsageAnalysisError([result2.issue]);
3048
+ reportPath = result2.resolved;
2956
3049
  }
2957
3050
  const { readFileCached, linkResult, context, origins, packageWarnings, tsconfigWarnings } = await assembleProject({
2958
3051
  fs: options.fs,
2959
3052
  root,
2960
3053
  include,
2961
3054
  exclude,
2962
- packages,
3055
+ packages: options.packages,
2963
3056
  tsconfig: options.tsconfig
2964
3057
  });
2965
3058
  const { scanFiles, scannedSurfaces } = await computeScanSurface(
@@ -2974,11 +3067,14 @@ async function generateUsageReport(options) {
2974
3067
  scanFiles,
2975
3068
  readFileCached,
2976
3069
  context,
2977
- [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings],
2978
3070
  scannedSurfaces
2979
3071
  );
2980
- if (reportPath) await writeUsageReport(reportPath, computed.result, options.fs);
2981
- return { reportPath, ...computed.result };
3072
+ const result = {
3073
+ ...computed.result,
3074
+ parseWarnings: [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings]
3075
+ };
3076
+ if (reportPath) await writeUsageReport(reportPath, result, options.fs);
3077
+ return { reportPath, ...result };
2982
3078
  }
2983
3079
 
2984
3080
  // src/build/finding-model.ts
@@ -3292,107 +3388,132 @@ function groupVariablesByOwner(contracts, ownerOf) {
3292
3388
  }
3293
3389
  return byOwner;
3294
3390
  }
3295
- var configurationReference = defineEvidenceProjection({
3296
- // Stryker disable next-line ArrowFunction
3297
- disclaimer: () => evidenceDisclaimer(),
3298
- entries: (evidence) => {
3299
- const entries = [];
3300
- for (const contract of evidence.contract.contracts) {
3301
- for (const variable of contract.variables) {
3302
- entries.push({
3303
- file: contract.file,
3304
- exportName: contract.exportName,
3305
- contractName: contract.contractName,
3306
- key: variable.key,
3307
- description: variable.description,
3308
- owner: variable.owner ?? contract.owner,
3309
- sensitivity: variable.sensitivity ?? contract.sensitivity,
3310
- required: variable.required,
3311
- hasDefault: variable.hasDefault,
3312
- hasProcessor: variable.hasProcessor,
3313
- hasValidator: variable.hasValidator,
3314
- expiresAt: variable.expiresAt,
3315
- active: contract.active
3316
- });
3391
+ function configurationReference(evidence) {
3392
+ return projectConfigurationReference(evidence).value;
3393
+ }
3394
+ configurationReference.project = projectConfigurationReference;
3395
+ function projectConfigurationReference(evidence) {
3396
+ return defineEvidenceProjection(configurationReferenceSchema()).project(evidence);
3397
+ }
3398
+ function configurationReferenceSchema() {
3399
+ return {
3400
+ disclaimer: evidenceDisclaimer,
3401
+ entries: (evidence) => {
3402
+ const entries = [];
3403
+ for (const contract of evidence.contract.contracts) {
3404
+ for (const variable of contract.variables) {
3405
+ entries.push({
3406
+ file: contract.file,
3407
+ exportName: contract.exportName,
3408
+ contractName: contract.contractName,
3409
+ key: variable.key,
3410
+ description: variable.description,
3411
+ owner: variable.owner ?? contract.owner,
3412
+ sensitivity: variable.sensitivity ?? contract.sensitivity,
3413
+ required: variable.required,
3414
+ hasDefault: variable.hasDefault,
3415
+ hasProcessor: variable.hasProcessor,
3416
+ hasValidator: variable.hasValidator,
3417
+ expiresAt: variable.expiresAt,
3418
+ active: contract.active
3419
+ });
3420
+ }
3317
3421
  }
3422
+ return entries.sort(byContractThenKey);
3318
3423
  }
3319
- return entries.sort(byContractThenKey);
3320
- }
3321
- });
3322
- var ownershipSummary = defineEvidenceProjection({
3323
- // Stryker disable next-line ArrowFunction
3324
- disclaimer: () => evidenceDisclaimer(),
3325
- owners: (evidence) => {
3326
- const contracts = contractIndex(evidence.contract.contracts);
3327
- const nameOf = (file, exportName) => contracts.get(`${file}#${exportName}`)?.contractName ?? exportName;
3328
- const variablesByOwner = groupVariablesByOwner(
3329
- evidence.ownership.contracts,
3330
- (_contract, variable) => variable.owner
3331
- );
3332
- const contractsByOwner = /* @__PURE__ */ new Map();
3333
- for (const contract of evidence.ownership.contracts) {
3334
- if (contract.owner === void 0) continue;
3335
- const list = contractsByOwner.get(contract.owner) ?? [];
3336
- list.push(nameOf(contract.file, contract.exportName));
3337
- contractsByOwner.set(contract.owner, list);
3424
+ };
3425
+ }
3426
+ function ownershipSummary(evidence) {
3427
+ return projectOwnershipSummary(evidence).value;
3428
+ }
3429
+ ownershipSummary.project = projectOwnershipSummary;
3430
+ function projectOwnershipSummary(evidence) {
3431
+ return defineEvidenceProjection(ownershipSummarySchema()).project(evidence);
3432
+ }
3433
+ function ownershipSummarySchema() {
3434
+ return {
3435
+ disclaimer: evidenceDisclaimer,
3436
+ owners: (evidence) => {
3437
+ const contracts = contractIndex(evidence.contract.contracts);
3438
+ const nameOf = (file, exportName) => contracts.get(`${file}#${exportName}`)?.contractName ?? exportName;
3439
+ const variablesByOwner = groupVariablesByOwner(
3440
+ evidence.ownership.contracts,
3441
+ (_contract, variable) => variable.owner
3442
+ );
3443
+ const contractsByOwner = /* @__PURE__ */ new Map();
3444
+ for (const contract of evidence.ownership.contracts) {
3445
+ if (contract.owner === void 0) continue;
3446
+ const list = contractsByOwner.get(contract.owner) ?? [];
3447
+ list.push(nameOf(contract.file, contract.exportName));
3448
+ contractsByOwner.set(contract.owner, list);
3449
+ }
3450
+ const owners = /* @__PURE__ */ new Set([...variablesByOwner.keys(), ...contractsByOwner.keys()]);
3451
+ return [...owners].sort().map((owner) => ({
3452
+ owner,
3453
+ variables: (variablesByOwner.get(owner) ?? []).map(
3454
+ ({ contract, variable }) => `${nameOf(contract.file, contract.exportName)}.${variable.key}`
3455
+ ).sort(),
3456
+ contracts: (contractsByOwner.get(owner) ?? []).sort()
3457
+ }));
3458
+ },
3459
+ unowned: (evidence) => {
3460
+ const contracts = contractIndex(evidence.contract.contracts);
3461
+ return evidence.ownership.unownedVariables.map((ref) => {
3462
+ const contractName = contracts.get(`${ref.file}#${ref.exportName}`)?.contractName ?? ref.exportName;
3463
+ return `${contractName}.${ref.key}`;
3464
+ }).sort();
3338
3465
  }
3339
- const owners = /* @__PURE__ */ new Set([...variablesByOwner.keys(), ...contractsByOwner.keys()]);
3340
- return [...owners].sort().map((owner) => ({
3341
- owner,
3342
- variables: (variablesByOwner.get(owner) ?? []).map(
3343
- ({ contract, variable }) => `${nameOf(contract.file, contract.exportName)}.${variable.key}`
3344
- ).sort(),
3345
- contracts: (contractsByOwner.get(owner) ?? []).sort()
3346
- }));
3347
- },
3348
- unowned: (evidence) => {
3349
- const contracts = contractIndex(evidence.contract.contracts);
3350
- return evidence.ownership.unownedVariables.map((ref) => {
3351
- const contractName = contracts.get(`${ref.file}#${ref.exportName}`)?.contractName ?? ref.exportName;
3352
- return `${contractName}.${ref.key}`;
3353
- }).sort();
3354
- }
3355
- });
3356
- var expiringSoonReport = defineEvidenceProjection({
3357
- // Stryker disable next-line ArrowFunction
3358
- disclaimer: () => evidenceDisclaimer(),
3359
- entries: (evidence) => {
3360
- const contracts = contractIndex(evidence.contract.contracts);
3361
- const ownerByVariable = /* @__PURE__ */ new Map();
3362
- for (const contract of evidence.ownership.contracts)
3363
- for (const variable of contract.variables)
3364
- ownerByVariable.set(
3365
- `${contract.file}#${contract.exportName}#${variable.key}`,
3366
- variable.owner
3367
- );
3368
- return evidence.lifecycle.expiring.map((entry) => {
3369
- const contract = contracts.get(`${entry.file}#${entry.exportName}`);
3370
- const variable = entry.key === void 0 ? void 0 : contract?.variables.find((v) => v.key === entry.key);
3371
- return {
3372
- file: entry.file,
3373
- exportName: entry.exportName,
3374
- contractName: contract?.contractName ?? entry.exportName,
3375
- key: entry.key,
3376
- expiresAt: entry.expiresAt,
3377
- daysRemaining: entry.daysRemaining,
3378
- expired: entry.daysRemaining < 0,
3379
- refreshInstructions: variable?.refreshInstructions,
3380
- owner: entry.key === void 0 ? contract?.owner : ownerByVariable.get(`${entry.file}#${entry.exportName}#${entry.key}`) ?? contract?.owner
3381
- };
3382
- });
3383
- },
3384
- // Same static covered-mutant false-Survivor as the `disclaimer` arrows
3385
- // above -- hand-verified killed (mutating this whole arrow to `() =>
3386
- // undefined` fails the "expiredCount" assertions in every test above).
3387
- // Stryker disable next-line ArrowFunction
3388
- expiredCount: (evidence) => evidence.lifecycle.expiring.filter((e) => e.daysRemaining < 0).length
3389
- });
3466
+ };
3467
+ }
3468
+ function expiringSoonReport(evidence) {
3469
+ return projectExpiringSoonReport(evidence).value;
3470
+ }
3471
+ expiringSoonReport.project = projectExpiringSoonReport;
3472
+ function projectExpiringSoonReport(evidence) {
3473
+ return defineEvidenceProjection(expiringSoonReportSchema()).project(evidence);
3474
+ }
3475
+ function expiringSoonReportSchema() {
3476
+ return {
3477
+ disclaimer: evidenceDisclaimer,
3478
+ entries: (evidence) => {
3479
+ const contracts = contractIndex(evidence.contract.contracts);
3480
+ const ownerByVariable = /* @__PURE__ */ new Map();
3481
+ for (const contract of evidence.ownership.contracts)
3482
+ for (const variable of contract.variables)
3483
+ ownerByVariable.set(
3484
+ `${contract.file}#${contract.exportName}#${variable.key}`,
3485
+ variable.owner
3486
+ );
3487
+ return evidence.lifecycle.expiring.map((entry) => {
3488
+ const contract = contracts.get(`${entry.file}#${entry.exportName}`);
3489
+ const variable = contract?.variables.find((v) => v.key === entry.key);
3490
+ return {
3491
+ file: entry.file,
3492
+ exportName: entry.exportName,
3493
+ contractName: contract?.contractName ?? entry.exportName,
3494
+ key: entry.key,
3495
+ expiresAt: entry.expiresAt,
3496
+ daysRemaining: entry.daysRemaining,
3497
+ expired: entry.daysRemaining < 0,
3498
+ refreshInstructions: variable?.refreshInstructions,
3499
+ owner: entry.key === void 0 ? contract?.owner : ownerByVariable.get(`${entry.file}#${entry.exportName}#${entry.key}`) ?? contract?.owner
3500
+ };
3501
+ });
3502
+ },
3503
+ expiredCount: (evidence) => evidence.lifecycle.expiring.filter((e) => e.daysRemaining < 0).length
3504
+ };
3505
+ }
3390
3506
 
3391
3507
  // src/build/docs.ts
3392
3508
  function parseIsoDate(value) {
3393
3509
  const date = new Date(value);
3394
3510
  return Number.isNaN(date.getTime()) ? void 0 : date;
3395
3511
  }
3512
+ function parseExpiry(expiresAt) {
3513
+ const raw = String(expiresAt);
3514
+ const date = parseIsoDate(raw);
3515
+ return date && { raw, date };
3516
+ }
3396
3517
  var MS_PER_DAY = 864e5;
3397
3518
  function daysRemainingFrom(date, now) {
3398
3519
  return Math.ceil((date.getTime() - now.getTime()) / MS_PER_DAY);
@@ -3400,32 +3521,29 @@ function daysRemainingFrom(date, now) {
3400
3521
  function computeExpiringEntries(contracts, expiringWithinDays, now) {
3401
3522
  const entries = [];
3402
3523
  for (const contract of contracts) {
3403
- if (contract.expiresAt) {
3404
- const date = parseIsoDate(contract.expiresAt);
3405
- if (date) {
3406
- const daysRemaining = daysRemainingFrom(date, now);
3407
- if (daysRemaining <= expiringWithinDays) {
3408
- entries.push({
3409
- file: contract.file,
3410
- exportName: contract.exportName,
3411
- key: void 0,
3412
- expiresAt: contract.expiresAt,
3413
- daysRemaining
3414
- });
3415
- }
3524
+ const contractExpiry = parseExpiry(contract.expiresAt);
3525
+ if (contractExpiry) {
3526
+ const daysRemaining = daysRemainingFrom(contractExpiry.date, now);
3527
+ if (daysRemaining <= expiringWithinDays) {
3528
+ entries.push({
3529
+ file: contract.file,
3530
+ exportName: contract.exportName,
3531
+ key: void 0,
3532
+ expiresAt: contractExpiry.raw,
3533
+ daysRemaining
3534
+ });
3416
3535
  }
3417
3536
  }
3418
3537
  for (const variable of contract.variables) {
3419
- if (!variable.expiresAt) continue;
3420
- const date = parseIsoDate(variable.expiresAt);
3421
- if (!date) continue;
3422
- const daysRemaining = daysRemainingFrom(date, now);
3538
+ const expiry = parseExpiry(variable.expiresAt);
3539
+ if (!expiry) continue;
3540
+ const daysRemaining = daysRemainingFrom(expiry.date, now);
3423
3541
  if (daysRemaining <= expiringWithinDays) {
3424
3542
  entries.push({
3425
3543
  file: contract.file,
3426
3544
  exportName: contract.exportName,
3427
3545
  key: variable.key,
3428
- expiresAt: variable.expiresAt,
3546
+ expiresAt: expiry.raw,
3429
3547
  daysRemaining
3430
3548
  });
3431
3549
  }
@@ -3476,7 +3594,7 @@ function buildCatalog(contracts) {
3476
3594
  function extractPreviouslyDocumentedKeys(previousContent) {
3477
3595
  const keys = /* @__PURE__ */ new Set();
3478
3596
  for (const match of previousContent.matchAll(/^### `([A-Za-z_][A-Za-z0-9_]*)`$/gm)) {
3479
- if (match[1]) keys.add(match[1]);
3597
+ keys.add(String(match[1]));
3480
3598
  }
3481
3599
  return keys;
3482
3600
  }
@@ -3516,7 +3634,7 @@ function computeChangeSummary(contracts, previousContent) {
3516
3634
  };
3517
3635
  }
3518
3636
  function slugify(text) {
3519
- return text.toLowerCase().replace(/[^a-z0-9_]+/g, "-").replace(/^-+|-+$/g, "") || "section";
3637
+ return text.toLowerCase().replace(/[^a-z0-9_]+/g, "-").replace(/^-|-$/g, "") || "section";
3520
3638
  }
3521
3639
  var AnchorRegistry = class {
3522
3640
  constructor() {
@@ -3533,16 +3651,24 @@ var AnchorRegistry = class {
3533
3651
  this.assigned.set(target, anchor);
3534
3652
  return anchor;
3535
3653
  }
3654
+ /** The anchor an earlier {@link anchorFor} call assigned to `target`; throws if there was none. */
3655
+ anchorOf(target) {
3656
+ return mustGet(this.assigned, target);
3657
+ }
3536
3658
  };
3537
3659
  function mdLink(text, anchor) {
3538
3660
  return `[${text}](#${anchor})`;
3539
3661
  }
3662
+ function sortedByKey(items) {
3663
+ const byKey = new Map(items.map((item) => [item.key, item]));
3664
+ return [...byKey.keys()].sort().map((key) => mustGet(byKey, key));
3665
+ }
3540
3666
  function sortedContracts(contracts) {
3541
3667
  return [...contracts].sort((a, b) => a.contractName.localeCompare(b.contractName));
3542
3668
  }
3543
3669
  function renderHeader(contracts, options, anchors, hasOwnership, hasDuplicates, hasLifecycle) {
3544
3670
  const lines = [
3545
- generatedBanner("markdown"),
3671
+ generatedBanner("markdown", reportRegenerateHint()),
3546
3672
  "",
3547
3673
  `> ${evidenceDisclaimer()}`,
3548
3674
  "",
@@ -3550,7 +3676,7 @@ function renderHeader(contracts, options, anchors, hasOwnership, hasDuplicates,
3550
3676
  "",
3551
3677
  "# Environment Variables",
3552
3678
  "",
3553
- "_Produced by `env-cap --docs`._",
3679
+ "_Produced by `generateDocumentation()` from `@maverickcer/env-cap/build`._",
3554
3680
  "",
3555
3681
  `_Generated ${options.generatedAt.toISOString()}_`,
3556
3682
  ""
@@ -3593,7 +3719,7 @@ function renderCatalog(contracts, anchors, undocumented) {
3593
3719
  );
3594
3720
  }
3595
3721
  for (const contract of sortedContracts(contracts)) {
3596
- lines.push(`<a id="${anchors.anchorFor(contract, `contract-${contract.contractName}`)}"></a>`);
3722
+ lines.push(`<a id="${anchors.anchorOf(contract)}"></a>`);
3597
3723
  lines.push(`## ${contract.contractName}`, "", `Source: \`${contract.file}\``);
3598
3724
  if (undocumentedByIdentity.has(`${contract.file}#${contract.exportName}`)) {
3599
3725
  lines.push("", "> \u26A0\uFE0F **Undocumented.** No `documentEnv()` call is linked to this contract.");
@@ -3618,10 +3744,8 @@ function renderCatalog(contracts, anchors, undocumented) {
3618
3744
  }
3619
3745
  }
3620
3746
  lines.push("");
3621
- for (const variable of [...contract.variables].sort((a, b) => a.key < b.key ? -1 : 1)) {
3622
- lines.push(
3623
- `<a id="${anchors.anchorFor(variable, `${contract.contractName}-${variable.key}`)}"></a>`
3624
- );
3747
+ for (const variable of sortedByKey(contract.variables)) {
3748
+ lines.push(`<a id="${anchors.anchorOf(variable)}"></a>`);
3625
3749
  lines.push(`### \`${variable.key}\``, "");
3626
3750
  if (variable.description) lines.push(variable.description, "");
3627
3751
  if (!variable.documented) lines.push("> \u26A0\uFE0F **Undocumented.**", "");
@@ -3734,18 +3858,17 @@ function renderLifecycleReport(contracts, anchors, expiringWithinDays, now) {
3734
3858
  const owner = effectiveOwner(contract, variable);
3735
3859
  if (variable.expiresAt === void 0 && owner === void 0 && variable.refreshInstructions === void 0)
3736
3860
  continue;
3737
- const expiresAt = variable.expiresAt;
3738
- const expiry = expiresAt ? parseIsoDate(expiresAt) : void 0;
3739
- let expiresCell = expiresAt ?? "--";
3740
- if (expiry && expiresAt) {
3741
- const daysRemaining = daysRemainingFrom(expiry, now);
3861
+ const expiry = parseExpiry(variable.expiresAt);
3862
+ let expiresCell = variable.expiresAt ?? "--";
3863
+ if (expiry) {
3864
+ const daysRemaining = daysRemainingFrom(expiry.date, now);
3742
3865
  if (daysRemaining < 0)
3743
- expiresCell = `${expiresAt} (**expired ${Math.abs(daysRemaining)}d ago**)`;
3866
+ expiresCell = `${expiry.raw} (**expired ${Math.abs(daysRemaining)}d ago**)`;
3744
3867
  else if (daysRemaining <= expiringWithinDays)
3745
- expiresCell = `${expiresAt} (**${daysRemaining}d remaining**)`;
3868
+ expiresCell = `${expiry.raw} (**${daysRemaining}d remaining**)`;
3746
3869
  }
3747
3870
  rows.push(
3748
- `| ${mdLink(`\`${variable.key}\``, anchors.anchorFor(variable, `${contract.contractName}-${variable.key}`))} | ${owner ?? "--"} | ${expiresCell} | ${variable.refreshInstructions ?? "--"} |`
3871
+ `| ${mdLink(`\`${variable.key}\``, anchors.anchorOf(variable))} | ${owner ?? "--"} | ${expiresCell} | ${variable.refreshInstructions ?? "--"} |`
3749
3872
  );
3750
3873
  }
3751
3874
  }
@@ -3861,7 +3984,14 @@ function renderDocs(contracts, options) {
3861
3984
  );
3862
3985
  const catalog = renderCatalog(sorted, anchors, options.undocumentedContracts);
3863
3986
  const security = renderSecurityReview(sorted, options, options.generatedAt);
3864
- return [...header, ...catalog, ...ownership, ...dependencyLines, ...lifecycleLines, ...security].join("\n").replace(/\n{3,}/g, "\n\n");
3987
+ return [
3988
+ ...header,
3989
+ ...catalog,
3990
+ ...ownership,
3991
+ ...dependencyLines,
3992
+ ...lifecycleLines,
3993
+ ...security
3994
+ ].join("\n");
3865
3995
  }
3866
3996
  function normalizeDocsForComparison(content) {
3867
3997
  return content.replace(/^_Generated .+_$/m, "_Generated <normalized-for-comparison>_").replace(/\(\*\*\d+d remaining\*\*\)/g, "(**Nd remaining**)").replace(/\(\*\*expired \d+d ago\*\*\)/g, "(**expired Nd ago**)").replace(/^(- Already expired:) \d+$/gm, "$1 N").replace(/^(- Expiring within \d+ days:) \d+$/gm, "$1 N");
@@ -3900,9 +4030,9 @@ function groupByKey(contracts) {
3900
4030
  const byKey = /* @__PURE__ */ new Map();
3901
4031
  for (const contract of contracts) {
3902
4032
  for (const variable of contract.variables) {
3903
- const list = byKey.get(variable.key) ?? [];
3904
- list.push({ contract, variable });
3905
- byKey.set(variable.key, list);
4033
+ const existing = byKey.get(variable.key);
4034
+ if (existing === void 0) byKey.set(variable.key, [{ contract, variable }]);
4035
+ else existing.push({ contract, variable });
3906
4036
  }
3907
4037
  }
3908
4038
  return byKey;
@@ -3910,7 +4040,6 @@ function groupByKey(contracts) {
3910
4040
  function renderEnvExample(contracts, reconciliationHeader = []) {
3911
4041
  const sorted = [...contracts].sort((a, b) => a.file.localeCompare(b.file));
3912
4042
  const active = sorted.filter((c) => c.active);
3913
- const inactive = sorted.filter((c) => !c.active);
3914
4043
  const lines = [
3915
4044
  "# AUTO-GENERATED EXAMPLE FILE.",
3916
4045
  "# Copy to .env and fill in real values. Do not commit .env."
@@ -3922,12 +4051,11 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
3922
4051
  "# still written to this file regardless of its context."
3923
4052
  );
3924
4053
  }
3925
- if (reconciliationHeader.length > 0) lines.push(...reconciliationHeader);
4054
+ lines.push(...reconciliationHeader);
3926
4055
  lines.push("");
3927
4056
  const activeByKey = groupByKey(active);
3928
4057
  for (const key of [...activeByKey.keys()].sort()) {
3929
4058
  const [first, ...rest] = mustGet(activeByKey, key);
3930
- if (first === void 0) continue;
3931
4059
  lines.push(...renderVariableLines(first.variable));
3932
4060
  for (const dup of rest) {
3933
4061
  lines.push(
@@ -3938,11 +4066,10 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
3938
4066
  );
3939
4067
  }
3940
4068
  }
3941
- const inactiveByKey = groupByKey(inactive);
4069
+ const inactiveByKey = groupByKey(sorted);
3942
4070
  for (const key of [...inactiveByKey.keys()].sort()) {
3943
4071
  if (activeByKey.has(key)) continue;
3944
4072
  const [first] = mustGet(inactiveByKey, key);
3945
- if (first === void 0) continue;
3946
4073
  lines.push(
3947
4074
  ...renderVariableLines(first.variable, {
3948
4075
  commented: true,
@@ -3950,13 +4077,12 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
3950
4077
  })
3951
4078
  );
3952
4079
  }
3953
- return lines.join("\n").replace(/\n+$/, "\n");
4080
+ return lines.join("\n");
3954
4081
  }
3955
4082
  function extractDeclaredVariables(source) {
3956
4083
  const names = [];
3957
4084
  for (const line of source.split("\n")) {
3958
4085
  const trimmed = line.trim();
3959
- if (!trimmed || trimmed.startsWith("#")) continue;
3960
4086
  const match = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(trimmed);
3961
4087
  if (match?.[1]) names.push(match[1]);
3962
4088
  }
@@ -3966,9 +4092,7 @@ function extractCommentedVariables(source) {
3966
4092
  const names = [];
3967
4093
  for (const line of source.split("\n")) {
3968
4094
  const trimmed = line.trim();
3969
- if (!trimmed.startsWith("#")) continue;
3970
- const withoutHash = trimmed.replace(/^#+\s*/, "");
3971
- const match = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(withoutHash);
4095
+ const match = /^#+\s*([A-Za-z_][A-Za-z0-9_]*)=/.exec(trimmed);
3972
4096
  if (match?.[1]) names.push(match[1]);
3973
4097
  }
3974
4098
  return names;
@@ -4050,7 +4174,7 @@ function collectVariableNames(contracts) {
4050
4174
  }
4051
4175
  function overrideVariable(variable, overrides) {
4052
4176
  const override = overrides[variable.key];
4053
- const date = override === void 0 ? void 0 : parseIsoDate(override);
4177
+ const date = parseIsoDate(String(override));
4054
4178
  return {
4055
4179
  ...variable,
4056
4180
  expiresAt: date ? override : variable.expiresAt,
@@ -4072,16 +4196,14 @@ async function resolveLiveExpirationDates(contracts, liveExpirationDates) {
4072
4196
 
4073
4197
  // src/build/generate-documentation.ts
4074
4198
  var DEFAULT_EXPIRING_WITHIN_DAYS = 30;
4075
- var STANDARD_SENSITIVITY_LEVELS = /* @__PURE__ */ new Set([
4076
- "secret",
4077
- "credential",
4078
- "pii",
4079
- "config"
4080
- ]);
4199
+ function standardSensitivityLevels() {
4200
+ return ["secret", "credential", "pii", "config"];
4201
+ }
4202
+ var STANDARD_SENSITIVITY_LEVELS = new Set(standardSensitivityLevels());
4081
4203
  function findNonstandardSensitivityLevels(contracts) {
4082
4204
  const entries = [];
4083
4205
  for (const contract of contracts) {
4084
- if (contract.sensitivity !== void 0 && !STANDARD_SENSITIVITY_LEVELS.has(contract.sensitivity))
4206
+ if (contract.sensitivity !== void 0 && !standardSensitivityLevels().includes(contract.sensitivity))
4085
4207
  entries.push({
4086
4208
  file: contract.file,
4087
4209
  exportName: contract.exportName,
@@ -4090,7 +4212,7 @@ function findNonstandardSensitivityLevels(contracts) {
4090
4212
  });
4091
4213
  for (const variable of [...contract.variables].sort((a, b) => a.key.localeCompare(b.key))) {
4092
4214
  if (variable.sensitivity === void 0) continue;
4093
- if (STANDARD_SENSITIVITY_LEVELS.has(variable.sensitivity)) continue;
4215
+ if (standardSensitivityLevels().includes(variable.sensitivity)) continue;
4094
4216
  entries.push({
4095
4217
  file: contract.file,
4096
4218
  exportName: contract.exportName,
@@ -4131,36 +4253,20 @@ async function writeDocumentation(docsPath, envExamplePath, root, contracts, con
4131
4253
  undocumentedContracts: documentation.undocumentedContracts.map(
4132
4254
  (ref) => relativizeRef(root, ref)
4133
4255
  ),
4134
- // `RenderDocsOptions.undocumentedVariables` is consumed by `renderDocs()`
4135
- // ONLY via `.length` (the security-review counter) -- never by content
4136
- // or identity, unlike its `undocumentedContracts` sibling above (matched
4137
- // by identity against the catalog for the "Undocumented." marker).
4138
- // `.map()` always preserves length regardless of what each element
4139
- // transforms to, so this specific `relativizeRef()` call's own output is
4140
- // unobservable through this call site. Hand-verified: mapping every
4141
- // entry to `undefined` instead and running the full `vitest run` leaves
4142
- // all tests passing.
4143
- // Stryker disable next-line ArrowFunction
4144
- undocumentedVariables: documentation.undocumentedVariables.map(
4145
- (ref) => relativizeRef(root, ref)
4146
- ),
4256
+ undocumentedVariables: documentation.undocumentedVariables,
4147
4257
  generatedAt,
4148
4258
  previousContent
4149
4259
  });
4150
4260
  await fs.mkdir(path6.dirname(docsPath), { recursive: true });
4151
4261
  await fs.writeFile(docsPath, docsSource, "utf8");
4152
4262
  const envExample = envExamplePath ? (
4153
- // exactOptionalPropertyTypes: omit the key rather than set it to
4154
- // `undefined` when the caller didn't supply one. writeEnvExample
4155
- // itself does `options.onExisting ?? "keep-sibling"`, so passing
4156
- // `onExisting: undefined` explicitly (what always-spreading here
4157
- // would do) is behaviorally identical to omitting the key.
4158
- // Hand-verified: forcing this guard to `true` and running the real
4159
- // suite passes unchanged.
4160
- await writeEnvExample(contracts, envExamplePath, fs, {
4161
- // Stryker disable next-line ConditionalExpression
4162
- ...envExampleOnExisting === void 0 ? {} : { onExisting: envExampleOnExisting }
4163
- })
4263
+ // `exactOptionalPropertyTypes` rejects an explicit `undefined`, so the key is omitted when unset.
4264
+ await writeEnvExample(
4265
+ contracts,
4266
+ envExamplePath,
4267
+ fs,
4268
+ envExampleOnExisting && { onExisting: envExampleOnExisting }
4269
+ )
4164
4270
  ) : void 0;
4165
4271
  return { envExample };
4166
4272
  }
@@ -4168,7 +4274,6 @@ async function generateDocumentation(options) {
4168
4274
  const root = path6.resolve(options.root ?? process.cwd());
4169
4275
  const include = options.include ?? defaultInclude();
4170
4276
  const exclude = options.exclude ?? defaultExclude();
4171
- const packages = options.packages ?? [];
4172
4277
  const expiringWithinDays = options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS;
4173
4278
  const docsLocationResult = resolveWithinRoot(
4174
4279
  root,
@@ -4194,7 +4299,7 @@ async function generateDocumentation(options) {
4194
4299
  root,
4195
4300
  include,
4196
4301
  exclude,
4197
- packages,
4302
+ packages: options.packages,
4198
4303
  tsconfig: options.tsconfig
4199
4304
  });
4200
4305
  const docsContracts = await resolveLiveExpirationDates(
@@ -4248,7 +4353,7 @@ function parseRotationPeriodDays(value) {
4248
4353
  if (plain) {
4249
4354
  const amount = Number(plain[1]);
4250
4355
  if (amount > 0) {
4251
- const unit = (plain[2] ?? "").toLowerCase();
4356
+ const unit = String(plain[2]).toLowerCase();
4252
4357
  switch (unit) {
4253
4358
  case "day":
4254
4359
  case "days":
@@ -4281,18 +4386,14 @@ function parseRotationPeriodDays(value) {
4281
4386
  }
4282
4387
  function computeRotationStatus(variable, now) {
4283
4388
  if (!hasRotationData(variable)) return "undeclared";
4284
- if (variable.expiresAt !== void 0) {
4285
- const expiry = parseIsoDate(variable.expiresAt);
4286
- if (expiry !== void 0 && expiry.getTime() < now.getTime()) return "expired";
4287
- }
4389
+ const expiry = parseIsoDate(String(variable.expiresAt));
4390
+ if (expiry !== void 0 && expiry.getTime() < now.getTime()) return "expired";
4288
4391
  if (variable.rotationPeriod !== void 0) {
4289
- if (variable.lastRotatedAt !== void 0) {
4290
- const lastRotated = parseIsoDate(variable.lastRotatedAt);
4291
- const periodDays = parseRotationPeriodDays(variable.rotationPeriod);
4292
- if (lastRotated !== void 0 && lastRotated.getTime() <= now.getTime() && periodDays !== void 0) {
4293
- const dueDate = lastRotated.getTime() + periodDays * MS_PER_DAY2;
4294
- return dueDate < now.getTime() ? "overdue" : "compliant";
4295
- }
4392
+ const lastRotated = parseIsoDate(String(variable.lastRotatedAt));
4393
+ const periodDays = parseRotationPeriodDays(variable.rotationPeriod);
4394
+ if (lastRotated !== void 0 && lastRotated.getTime() <= now.getTime() && periodDays !== void 0) {
4395
+ const dueDate = lastRotated.getTime() + periodDays * MS_PER_DAY2;
4396
+ return dueDate < now.getTime() ? "overdue" : "compliant";
4296
4397
  }
4297
4398
  return "overdue";
4298
4399
  }
@@ -4374,7 +4475,7 @@ function buildOwnershipModel(contracts, root) {
4374
4475
 
4375
4476
  // src/build/tool-version.ts
4376
4477
  function readToolVersion() {
4377
- return "0.5.3";
4478
+ return "0.7.0";
4378
4479
  }
4379
4480
 
4380
4481
  // src/build/generate-evidence.ts
@@ -4382,7 +4483,6 @@ async function generateEvidenceModel(options) {
4382
4483
  const root = path6.resolve(options.root ?? process.cwd());
4383
4484
  const include = options.include ?? defaultInclude();
4384
4485
  const exclude = options.exclude ?? defaultExclude();
4385
- const packages = options.packages ?? [];
4386
4486
  const expiringWithinDays = options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS;
4387
4487
  let snapshotPath;
4388
4488
  if (options.previousSnapshotLocation !== void 0) {
@@ -4400,10 +4500,10 @@ async function generateEvidenceModel(options) {
4400
4500
  root,
4401
4501
  include,
4402
4502
  exclude,
4403
- packages,
4503
+ packages: options.packages,
4404
4504
  tsconfig: options.tsconfig
4405
4505
  });
4406
- const { readFileCached, linkResult, context, origins, packageWarnings, tsconfigWarnings } = assembled;
4506
+ const { readFileCached, linkResult, context, origins } = assembled;
4407
4507
  const generatedAt = /* @__PURE__ */ new Date();
4408
4508
  const activeContracts = linkResult.contracts.filter((c) => c.active);
4409
4509
  const lifecycleContracts = options.liveExpirationDates ? await resolveLiveExpirationDates(linkResult.contracts, options.liveExpirationDates) : linkResult.contracts;
@@ -4457,8 +4557,6 @@ async function generateEvidenceModel(options) {
4457
4557
  scanFiles,
4458
4558
  readFileCached,
4459
4559
  context,
4460
- // Stryker disable next-line ArrayDeclaration
4461
- [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings],
4462
4560
  scannedSurfaces,
4463
4561
  evidenceChanges?.dynamicAccessAcknowledgments
4464
4562
  );
@@ -4471,12 +4569,7 @@ async function generateEvidenceModel(options) {
4471
4569
  unresolvedConsumers: usageComputed.result.unresolvedConsumers,
4472
4570
  unconsumedOwnedVariables: usageComputed.result.unconsumedOwnedVariables,
4473
4571
  indeterminateOwnership: usageComputed.result.indeterminate,
4474
- // `buildFindingModel` (finding-model.ts) has its own `?? []` fallback
4475
- // on this exact same field, so even an `undefined` that slipped past
4476
- // this one (e.g. `??`-vs-`&&` on `evidenceChanges?.…`) is caught there
4477
- // identically -- belt-and-suspenders, not independently observable.
4478
- // Stryker disable next-line LogicalOperator
4479
- dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems ?? []
4572
+ dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems
4480
4573
  });
4481
4574
  const commit = options.commit ? await options.commit() : void 0;
4482
4575
  return deepFreeze({
@@ -4532,7 +4625,6 @@ async function getEvidenceModel(options) {
4532
4625
  const root = path6.resolve(options.root ?? process.cwd());
4533
4626
  const include = options.include ?? defaultInclude();
4534
4627
  const exclude = options.exclude ?? defaultExclude();
4535
- const packages = options.packages ?? [];
4536
4628
  const evidencePath = path6.resolve(root, options.location);
4537
4629
  const fingerprintPath = fingerprintPathFor(evidencePath);
4538
4630
  const recompute = async (missReason) => ({
@@ -4547,7 +4639,7 @@ async function getEvidenceModel(options) {
4547
4639
  root,
4548
4640
  include,
4549
4641
  exclude,
4550
- packages
4642
+ packages: options.packages
4551
4643
  });
4552
4644
  } catch (error) {
4553
4645
  return recompute(
@@ -4595,91 +4687,61 @@ function findingFiles(finding) {
4595
4687
  if (location.model === "change") return [location.path];
4596
4688
  return location.file === void 0 ? [] : [location.file];
4597
4689
  }
4690
+ function requestedPass(option) {
4691
+ return option === false ? void 0 : option;
4692
+ }
4598
4693
  async function computeArtifacts(options) {
4599
4694
  const root = path6.resolve(options.root ?? process.cwd());
4600
4695
  const include = options.include ?? defaultInclude();
4601
4696
  const exclude = options.exclude ?? defaultExclude();
4602
- const packages = options.packages ?? [];
4603
- const manifestOptions = options.manifest === false ? void 0 : options.manifest;
4604
- const docsOptions = options.docs === false ? void 0 : options.docs;
4605
- const usageOptions = options.usage === false ? void 0 : options.usage;
4606
- const evidenceOptions = options.evidence === false ? void 0 : options.evidence;
4697
+ const manifestOptions = requestedPass(options.manifest);
4698
+ const docsOptions = requestedPass(options.docs);
4699
+ const usageOptions = requestedPass(options.usage);
4700
+ const evidenceOptions = requestedPass(options.evidence);
4607
4701
  const pathIssues = [];
4608
- let manifestOutputPath;
4609
- if (manifestOptions) {
4610
- const result = resolveWithinRoot(
4611
- root,
4612
- manifestOptions.location,
4613
- "manifest.location",
4614
- "generateEnvArtifacts"
4615
- );
4616
- if (result.ok) manifestOutputPath = result.resolved;
4617
- else pathIssues.push(result.issue);
4618
- }
4619
- let docsPath;
4620
- let envExamplePath;
4621
- if (docsOptions) {
4622
- const result = resolveWithinRoot(
4623
- root,
4624
- docsOptions.location,
4625
- "docs.location",
4626
- "generateEnvArtifacts"
4627
- );
4628
- if (result.ok) docsPath = result.resolved;
4629
- else pathIssues.push(result.issue);
4630
- if (docsOptions.envExample) {
4631
- const exampleResult = resolveWithinRoot(
4632
- root,
4633
- docsOptions.envExample.location,
4634
- "docs.envExample.location",
4635
- "generateEnvArtifacts"
4636
- );
4637
- if (exampleResult.ok) envExamplePath = exampleResult.resolved;
4638
- else pathIssues.push(exampleResult.issue);
4639
- }
4640
- }
4641
- let usageReportPath;
4642
- if (usageOptions?.report) {
4643
- const result = resolveWithinRoot(
4644
- root,
4645
- usageOptions.report.location,
4646
- "usage.report.location",
4647
- "generateEnvArtifacts"
4648
- );
4649
- if (result.ok) usageReportPath = result.resolved;
4650
- else pathIssues.push(result.issue);
4651
- }
4652
- let evidencePath;
4653
- if (evidenceOptions) {
4654
- const result = resolveWithinRoot(
4655
- root,
4656
- evidenceOptions.location,
4657
- "evidence.location",
4658
- "generateEnvArtifacts"
4659
- );
4660
- if (result.ok) evidencePath = result.resolved;
4661
- else pathIssues.push(result.issue);
4662
- }
4702
+ const resolveOutput = (location, label) => {
4703
+ const result = resolveWithinRoot(root, location, label, "generateEnvArtifacts");
4704
+ if (result.ok) return result.resolved;
4705
+ pathIssues.push(result.issue);
4706
+ return location;
4707
+ };
4708
+ const manifestTarget = manifestOptions && {
4709
+ options: manifestOptions,
4710
+ outputPath: resolveOutput(manifestOptions.location, "manifest.location")
4711
+ };
4712
+ const docsTarget = docsOptions && {
4713
+ options: docsOptions,
4714
+ path: resolveOutput(docsOptions.location, "docs.location"),
4715
+ envExamplePath: docsOptions.envExample ? resolveOutput(docsOptions.envExample.location, "docs.envExample.location") : void 0
4716
+ };
4717
+ const usageTarget = usageOptions && {
4718
+ options: usageOptions,
4719
+ reportPath: usageOptions.report ? resolveOutput(usageOptions.report.location, "usage.report.location") : void 0
4720
+ };
4721
+ const evidencePath = evidenceOptions ? resolveOutput(evidenceOptions.location, "evidence.location") : void 0;
4663
4722
  if (pathIssues.length > 0) throw new EnvProjectGenerationError(pathIssues);
4664
4723
  const { readFileCached, linkResult, context, origins, packageWarnings, tsconfigWarnings } = await assembleProject({
4665
4724
  fs: options.fs,
4666
4725
  root,
4667
4726
  include,
4668
4727
  exclude,
4669
- packages,
4728
+ packages: options.packages,
4670
4729
  tsconfig: options.tsconfig
4671
4730
  });
4672
4731
  const generatedAt = /* @__PURE__ */ new Date();
4673
4732
  const activeContracts = linkResult.contracts.filter((c) => c.active);
4674
4733
  const liveExpirationContracts = options.liveExpirationDates ? await resolveLiveExpirationDates(linkResult.contracts, options.liveExpirationDates) : linkResult.contracts;
4675
- const docsContracts = docsOptions ? liveExpirationContracts : linkResult.contracts;
4734
+ const docsContracts = docsTarget ? liveExpirationContracts : linkResult.contracts;
4676
4735
  const blocking = [];
4677
- const manifestComputed = manifestOptions ? computeManifest(root, linkResult, manifestOptions.onIncompatibility ?? "warn") : void 0;
4678
- if (manifestComputed) blocking.push(...manifestComputed.blocking);
4736
+ const manifest = manifestTarget && {
4737
+ ...manifestTarget,
4738
+ computed: computeManifest(root, linkResult, manifestTarget.options.onIncompatibility)
4739
+ };
4740
+ if (manifest) blocking.push(...manifest.computed.blocking);
4679
4741
  const docsComputed = computeDocumentation(
4680
4742
  root,
4681
4743
  { ...linkResult, contracts: liveExpirationContracts },
4682
- docsOptions?.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4744
+ docsTarget?.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4683
4745
  generatedAt
4684
4746
  );
4685
4747
  const { scanFiles, scannedSurfaces } = await computeScanSurface(
@@ -4703,14 +4765,13 @@ async function computeArtifacts(options) {
4703
4765
  scanFiles,
4704
4766
  readFileCached,
4705
4767
  context,
4706
- [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings],
4707
4768
  scannedSurfaces,
4708
4769
  evidenceChanges?.dynamicAccessAcknowledgments
4709
4770
  );
4710
4771
  const ownership = buildOwnershipModel(linkResult.contracts, root);
4711
4772
  const lifecycle = buildLifecycleModel(
4712
4773
  liveExpirationContracts,
4713
- docsOptions?.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4774
+ docsTarget?.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4714
4775
  generatedAt,
4715
4776
  root
4716
4777
  );
@@ -4747,7 +4808,7 @@ async function computeArtifacts(options) {
4747
4808
  unresolvedConsumers: usageComputed.result.unresolvedConsumers,
4748
4809
  unconsumedOwnedVariables: usageComputed.result.unconsumedOwnedVariables,
4749
4810
  indeterminateOwnership: usageComputed.result.indeterminate,
4750
- dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems ?? []
4811
+ dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems
4751
4812
  });
4752
4813
  if (options.onUndocumented === "throw")
4753
4814
  blocking.push(...escalatedFindings(finding.findings, "documentation"));
@@ -4769,16 +4830,11 @@ async function computeArtifacts(options) {
4769
4830
  });
4770
4831
  return {
4771
4832
  root,
4772
- manifestOptions,
4773
- manifestOutputPath,
4774
- manifestComputed,
4775
- docsOptions,
4776
- docsPath,
4777
- envExamplePath,
4833
+ manifest,
4834
+ docs: docsTarget,
4778
4835
  docsComputed,
4779
4836
  docsContracts,
4780
- usageOptions,
4781
- usageReportPath,
4837
+ usage: usageTarget,
4782
4838
  usageComputed,
4783
4839
  evidencePath,
4784
4840
  evidence,
@@ -4791,16 +4847,11 @@ async function computeArtifacts(options) {
4791
4847
  async function generateEnvArtifacts(options) {
4792
4848
  const computed = await computeArtifacts(options);
4793
4849
  const {
4794
- manifestOptions,
4795
- manifestOutputPath,
4796
- manifestComputed,
4797
- docsOptions,
4798
- docsPath,
4799
- envExamplePath,
4850
+ manifest,
4851
+ docs,
4800
4852
  docsComputed,
4801
4853
  docsContracts,
4802
- usageOptions,
4803
- usageReportPath,
4854
+ usage,
4804
4855
  usageComputed,
4805
4856
  evidencePath,
4806
4857
  evidence,
@@ -4811,43 +4862,47 @@ async function generateEnvArtifacts(options) {
4811
4862
  generatedAt
4812
4863
  } = computed;
4813
4864
  if (blocking.length > 0) throw new EnvProjectGenerationError(blocking);
4865
+ const parseWarnings = [...packageWarnings, ...linkWarnings];
4814
4866
  let manifestResult;
4815
- if (manifestOptions && manifestComputed && manifestOutputPath) {
4816
- await writeManifest(manifestOutputPath, manifestComputed.activeContracts, options.fs);
4867
+ if (manifest) {
4868
+ await writeManifest(manifest.outputPath, manifest.computed.activeContracts, options.fs);
4817
4869
  manifestResult = {
4818
- outputPath: manifestOutputPath,
4819
- contracts: manifestComputed.contractSummaries,
4820
- warnings: manifestComputed.warnings,
4821
- parseWarnings: [...packageWarnings, ...linkWarnings]
4870
+ outputPath: manifest.outputPath,
4871
+ contracts: manifest.computed.contractSummaries,
4872
+ warnings: manifest.computed.warnings,
4873
+ parseWarnings
4822
4874
  };
4823
4875
  }
4824
4876
  let docsResult;
4825
- if (docsOptions && docsPath) {
4877
+ if (docs) {
4826
4878
  const { envExample } = await writeDocumentation(
4827
- docsPath,
4828
- envExamplePath,
4879
+ docs.path,
4880
+ docs.envExamplePath,
4829
4881
  root,
4830
4882
  docsContracts,
4831
4883
  docsComputed.contractModelContracts,
4832
4884
  docsComputed.documentation,
4833
- docsOptions.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4885
+ docs.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4834
4886
  generatedAt,
4835
4887
  options.fs,
4836
- docsOptions.envExample?.onExisting
4888
+ docs.options.envExample?.onExisting
4837
4889
  );
4838
4890
  docsResult = {
4839
- docsPath,
4891
+ docsPath: docs.path,
4840
4892
  envExample,
4841
4893
  contracts: docsComputed.contractSummaries,
4842
4894
  catalog: docsComputed.catalog,
4843
- parseWarnings: [...packageWarnings, ...linkWarnings],
4895
+ parseWarnings,
4844
4896
  documentation: docsComputed.documentation
4845
4897
  };
4846
4898
  }
4847
4899
  let usageResult;
4848
- if (usageOptions) {
4849
- if (usageReportPath) await writeUsageReport(usageReportPath, usageComputed.result, options.fs);
4850
- usageResult = { reportPath: usageReportPath, ...usageComputed.result };
4900
+ if (usage) {
4901
+ const usageReport = { ...usageComputed.result, parseWarnings };
4902
+ if (usage.reportPath !== void 0) {
4903
+ await writeUsageReport(usage.reportPath, usageReport, options.fs);
4904
+ }
4905
+ usageResult = { reportPath: usage.reportPath, ...usageReport };
4851
4906
  }
4852
4907
  if (evidencePath) {
4853
4908
  await writeEvidenceSnapshot(evidencePath, evidence, options.fs);
@@ -4856,7 +4911,7 @@ async function generateEnvArtifacts(options) {
4856
4911
  root,
4857
4912
  include: options.include ?? defaultInclude(),
4858
4913
  exclude: options.exclude ?? defaultExclude(),
4859
- packages: options.packages ?? []
4914
+ packages: options.packages
4860
4915
  });
4861
4916
  await writeEvidenceFingerprint(evidencePath, fingerprint, options.fs);
4862
4917
  }
@@ -4864,12 +4919,8 @@ async function generateEnvArtifacts(options) {
4864
4919
  }
4865
4920
 
4866
4921
  // src/build/check-artifacts.ts
4867
- async function readIfExists(filePath, fs) {
4868
- try {
4869
- return await fs.readFile(filePath, "utf8");
4870
- } catch {
4871
- return void 0;
4872
- }
4922
+ function readIfExists(filePath, fs) {
4923
+ return fs.readFile(filePath, "utf8").catch(() => void 0);
4873
4924
  }
4874
4925
  function normalizeEvidenceJsonForComparison(text) {
4875
4926
  try {
@@ -4895,46 +4946,38 @@ async function checkEnvArtifacts(options) {
4895
4946
  const c = await computeArtifacts(options);
4896
4947
  if (c.blocking.length > 0) throw new EnvProjectGenerationError(c.blocking);
4897
4948
  const findings = [];
4898
- if (c.manifestOptions && c.manifestComputed && c.manifestOutputPath) {
4899
- const expected = renderManifest(c.manifestComputed.activeContracts, c.manifestOutputPath);
4900
- findings.push(await compareTextArtifact("manifest", c.manifestOutputPath, expected, options.fs));
4949
+ if (c.manifest) {
4950
+ const expected = renderManifest(c.manifest.computed.activeContracts, c.manifest.outputPath);
4951
+ findings.push(
4952
+ await compareTextArtifact("manifest", c.manifest.outputPath, expected, options.fs)
4953
+ );
4901
4954
  }
4902
- if (c.docsOptions && c.docsPath) {
4903
- const previousContent = await readIfExists(c.docsPath, options.fs);
4955
+ if (c.docs) {
4956
+ const previousContent = await readIfExists(c.docs.path, options.fs);
4904
4957
  const expected = renderDocs(c.docsComputed.contractModelContracts, {
4905
- expiringWithinDays: c.docsOptions.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4958
+ expiringWithinDays: c.docs.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4906
4959
  undocumentedContracts: c.docsComputed.documentation.undocumentedContracts.map(
4907
4960
  (ref) => relativizeRef(c.root, ref)
4908
4961
  ),
4909
- // `RenderDocsOptions.undocumentedVariables` is consumed by `renderDocs()`
4910
- // ONLY via `.length` (the security-review counter), never by content
4911
- // or identity -- same equivalence already established for
4912
- // `generate-documentation.ts`'s identical call site. Hand-verified:
4913
- // mapping every entry to `undefined` instead and running the full
4914
- // `vitest run` leaves every test passing.
4915
- // Stryker disable ArrowFunction
4916
- undocumentedVariables: c.docsComputed.documentation.undocumentedVariables.map(
4917
- (ref) => relativizeRef(c.root, ref)
4918
- ),
4919
- // Stryker restore ArrowFunction
4962
+ undocumentedVariables: c.docsComputed.documentation.undocumentedVariables,
4920
4963
  generatedAt: c.generatedAt,
4921
4964
  previousContent
4922
4965
  });
4923
4966
  findings.push(
4924
4967
  await compareTextArtifact(
4925
4968
  "docs",
4926
- c.docsPath,
4969
+ c.docs.path,
4927
4970
  expected,
4928
4971
  options.fs,
4929
4972
  normalizeDocsForComparison
4930
4973
  )
4931
4974
  );
4932
- if (c.docsOptions.envExample && c.envExamplePath) {
4933
- const existing = await readIfExists(c.envExamplePath, options.fs);
4975
+ if (c.docs.envExamplePath !== void 0) {
4976
+ const existing = await readIfExists(c.docs.envExamplePath, options.fs);
4934
4977
  if (existing === void 0) {
4935
4978
  findings.push({
4936
4979
  artifact: "envExample",
4937
- path: c.envExamplePath,
4980
+ path: c.docs.envExamplePath,
4938
4981
  status: "missing",
4939
4982
  detail: "not yet generated"
4940
4983
  });
@@ -4946,7 +4989,7 @@ async function checkEnvArtifacts(options) {
4946
4989
  const driftCount = staleVariables.length + variablesToComment.length + variablesToAdd.length;
4947
4990
  findings.push({
4948
4991
  artifact: "envExample",
4949
- path: c.envExamplePath,
4992
+ path: c.docs.envExamplePath,
4950
4993
  status: driftCount > 0 ? "stale" : "ok",
4951
4994
  // exactOptionalPropertyTypes: omit the key entirely rather than
4952
4995
  // set it to `undefined` -- `detail` is absent when there's
@@ -4958,9 +5001,12 @@ async function checkEnvArtifacts(options) {
4958
5001
  }
4959
5002
  }
4960
5003
  }
4961
- if (c.usageOptions && c.usageReportPath) {
4962
- const expected = renderUsageReport(c.usageComputed.result);
4963
- findings.push(await compareTextArtifact("usage", c.usageReportPath, expected, options.fs));
5004
+ if (c.usage?.reportPath !== void 0) {
5005
+ const expected = renderUsageReport({
5006
+ ...c.usageComputed.result,
5007
+ parseWarnings: [...c.packageWarnings, ...c.linkWarnings]
5008
+ });
5009
+ findings.push(await compareTextArtifact("usage", c.usage.reportPath, expected, options.fs));
4964
5010
  }
4965
5011
  if (c.evidencePath) {
4966
5012
  const expected = JSON.stringify(c.evidence, null, 2);
@@ -4985,7 +5031,7 @@ function sarifLocations(finding) {
4985
5031
  const location = finding.location;
4986
5032
  const uri = location.model === "change" ? location.path : location.file;
4987
5033
  if (uri === void 0) return void 0;
4988
- const position = location.model === "change" ? void 0 : location.position;
5034
+ const { position } = location;
4989
5035
  return [
4990
5036
  {
4991
5037
  physicalLocation: {