@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
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  readToolVersion
4
- } from "./chunk-BSTLSR2R.js";
4
+ } from "./chunk-KEGYUHBU.js";
5
5
 
6
6
  // src/build/evidence-snapshot.ts
7
7
  import path3 from "path";
@@ -10,11 +10,12 @@ import path3 from "path";
10
10
  import crypto from "crypto";
11
11
  import path2 from "path";
12
12
 
13
- // src/build/display-path.ts
13
+ // src/_ipc/display-path.ts
14
14
  import path from "path";
15
- function displayPath(root, absolutePath) {
16
- const relative = path.relative(root, absolutePath);
17
- if (relative.startsWith("..") || path.isAbsolute(relative)) return absolutePath;
15
+ function displayPath(root, filePath) {
16
+ if (!path.isAbsolute(filePath)) return filePath.split(path.sep).join("/");
17
+ const relative = path.relative(root, filePath);
18
+ if (relative.startsWith("..") || path.isAbsolute(relative)) return filePath;
18
19
  return relative.split(path.sep).join("/");
19
20
  }
20
21
 
@@ -45,7 +46,6 @@ function previousContentHashes(previous) {
45
46
  for (const contract of previous?.dependency.contracts ?? []) {
46
47
  for (const variable of contract.variables) {
47
48
  for (const assertion of variable.dynamicAccessAssertions) {
48
- if (assertion.contentHash === void 0) continue;
49
49
  const identity = dynamicAccessVariableIdentity(
50
50
  contract.file,
51
51
  contract.exportName,
@@ -66,8 +66,8 @@ async function buildCitationSnapshots(activeContracts, previous, root, readFile)
66
66
  for (const contract of activeContracts) {
67
67
  const file = displayPath(root, contract.file);
68
68
  for (const variable of contract.variables) {
69
- const citations = variable.evidence?.dynamicAccess ?? [];
70
- if (citations.length === 0) continue;
69
+ const citations = variable.evidence?.dynamicAccess;
70
+ if (citations === void 0) continue;
71
71
  const identity = dynamicAccessVariableIdentity(file, contract.exportName, variable.key);
72
72
  const assertions = [];
73
73
  for (const citation of citations) {
@@ -145,9 +145,7 @@ function toVariableRef(contract, variable) {
145
145
  return { file: contract.file, exportName: contract.exportName, key: variable.key };
146
146
  }
147
147
  function toComparable(value) {
148
- if (value === void 0) return void 0;
149
- if (typeof value === "string") return value;
150
- return JSON.stringify(value);
148
+ return typeof value === "string" ? value : JSON.stringify(value);
151
149
  }
152
150
  function genericFieldChanges(previous, current, skipKeys) {
153
151
  const keys = /* @__PURE__ */ new Set([...Object.keys(previous), ...Object.keys(current)]);
@@ -190,17 +188,7 @@ function recordFieldChanges(previous, current) {
190
188
  return changes;
191
189
  }
192
190
  function byIdentity(a, b) {
193
- return a.file.localeCompare(b.file) || a.exportName.localeCompare(b.exportName) || // The `?? ""` fallbacks themselves are unreachable through any real
194
- // array this function ever sorts: a `ManifestContractRef` never carries
195
- // a `key` at all, but its own array can never hold two entries sharing
196
- // both file+exportName (contracts are unique by that pair) so the key
197
- // term is never reached for them either way; a `ManifestVariableRef`'s
198
- // `key` is always a real, non-empty string, never `undefined`. Hand-
199
- // verified: mutating both fallbacks to a distinguishing sentinel and
200
- // running the real suite (this file plus
201
- // check-artifacts.test.ts/generate-evidence.test.ts) passes unchanged.
202
- // Stryker disable next-line StringLiteral
203
- (a.key ?? "").localeCompare(b.key ?? "");
191
+ return a.file.localeCompare(b.file) || a.exportName.localeCompare(b.exportName) || String(a.key).localeCompare(String(b.key));
204
192
  }
205
193
  function diffContracts(previous, current) {
206
194
  const previousContracts = new Map((previous ?? []).map((c) => [contractIdentity(c), c]));
@@ -219,25 +207,12 @@ function diffContracts(previous, current) {
219
207
  const changes = genericFieldChanges(
220
208
  previousContract,
221
209
  currentContract,
222
- /* @__PURE__ */ new Set([
223
- // "file"/"exportName" can never actually differ here: both
224
- // contracts of a matched pair share the same Map key
225
- // (`contractIdentity()`), itself derived from file+exportName, so
226
- // they're always structurally equal for two contracts matched
227
- // into one updatedContracts entry. Hand-verified equivalent via
228
- // direct mutation + a real suite run.
229
- // Stryker disable next-line StringLiteral
230
- "file",
231
- // Stryker disable next-line StringLiteral
232
- "exportName",
233
- // Genuinely skipped AND real-tested -- see "does not report the
234
- // whole variables array as a changed field" below.
235
- "variables"
236
- ])
210
+ // `file` and `exportName` cannot differ for a matched pair (they make up its identity).
211
+ /* @__PURE__ */ new Set(["variables"])
237
212
  );
238
213
  if (changes.length > 0) updatedContracts.push({ ...toContractRef(currentContract), changes });
239
214
  }
240
- const previousVariables = new Map((previousContract?.variables ?? []).map((v) => [v.key, v]));
215
+ const previousVariables = new Map(previousContract?.variables.map((v) => [v.key, v]));
241
216
  const currentVariables = new Map(currentContract.variables.map((v) => [v.key, v]));
242
217
  for (const [key, currentVariable] of currentVariables) {
243
218
  const previousVariable = previousVariables.get(key);
@@ -248,16 +223,14 @@ function diffContracts(previous, current) {
248
223
  const changes = genericFieldChanges(
249
224
  previousVariable,
250
225
  currentVariable,
251
- /* @__PURE__ */ new Set(["key"])
226
+ /* @__PURE__ */ new Set()
252
227
  );
253
228
  if (changes.length > 0)
254
229
  updatedVariables.push({ ...toVariableRef(currentContract, currentVariable), changes });
255
230
  }
256
- if (previousContract) {
257
- for (const [key, previousVariable] of previousVariables) {
258
- if (!currentVariables.has(key))
259
- removedVariables.push(toVariableRef(previousContract, previousVariable));
260
- }
231
+ for (const [key, previousVariable] of previousVariables) {
232
+ if (!currentVariables.has(key))
233
+ removedVariables.push(toVariableRef(currentContract, previousVariable));
261
234
  }
262
235
  }
263
236
  for (const [identity, previousContract] of previousContracts) {
@@ -301,7 +274,6 @@ async function writeEvidenceSnapshot(snapshotPath, snapshot, fs) {
301
274
  await fs.writeFile(snapshotPath, `${JSON.stringify(snapshot, null, 2)}
302
275
  `, "utf8");
303
276
  }
304
- var EXPIRY_DAY_COUNT = /\b\d+ day\(s\)/g;
305
277
  function normalizeEvidenceSnapshotForComparison(snapshot) {
306
278
  return {
307
279
  ...snapshot,
@@ -325,7 +297,7 @@ function normalizeEvidenceSnapshotForComparison(snapshot) {
325
297
  finding: {
326
298
  ...snapshot.finding,
327
299
  findings: snapshot.finding.findings.map(
328
- (f) => f.code === "EXPIRED" || f.code === "EXPIRING_SOON" ? { ...f, message: f.message.replace(EXPIRY_DAY_COUNT, "N day(s)") } : f
300
+ (f) => f.code === "EXPIRED" || f.code === "EXPIRING_SOON" ? { ...f, message: f.message.replace(/\b\d+ day\(s\)/g, "N day(s)") } : f
329
301
  )
330
302
  }
331
303
  };
@@ -334,19 +306,22 @@ async function computeEvidenceChanges(root, snapshotPath, activeContracts, curre
334
306
  const read = await readEvidenceSnapshot(snapshotPath, fs);
335
307
  let previous;
336
308
  let readWarning;
337
- if (read.status === "invalid-json") {
338
- readWarning = {
339
- file: snapshotPath,
340
- message: `Evidence snapshot could not be parsed as JSON (${read.detail}); treating this run as if no previous snapshot existed.`
341
- };
342
- } else if (read.status === "unsupported-version") {
343
- readWarning = {
344
- file: snapshotPath,
345
- 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.`
346
- };
347
- }
348
- if (read.status === "ok") {
349
- previous = read.snapshot;
309
+ switch (read.status) {
310
+ case "ok":
311
+ previous = read.snapshot;
312
+ break;
313
+ case "invalid-json":
314
+ readWarning = {
315
+ file: snapshotPath,
316
+ message: `Evidence snapshot could not be parsed as JSON (${read.detail}); treating this run as if no previous snapshot existed.`
317
+ };
318
+ break;
319
+ case "unsupported-version":
320
+ readWarning = {
321
+ file: snapshotPath,
322
+ 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.`
323
+ };
324
+ break;
350
325
  }
351
326
  const dynamicAccessAcknowledgments = await buildCitationSnapshots(
352
327
  activeContracts,
@@ -372,30 +347,21 @@ import path17 from "path";
372
347
  // src/build/discover.ts
373
348
  import path4 from "path";
374
349
 
375
- // src/build/glob.ts
350
+ // src/_ipc/glob.ts
376
351
  function globToRegExp(pattern) {
377
352
  let out = "";
378
- let passes = 0;
379
- const maxPasses = pattern.length * 2 + 4;
380
- for (let i = 0; i < pattern.length; i++) {
381
- passes++;
382
- if (passes > maxPasses) {
383
- throw new Error(
384
- // Stryker disable next-line StringLiteral
385
- `globToRegExp: exceeded ${String(maxPasses)} iterations parsing pattern ${JSON.stringify(pattern)} -- this should never happen for any real pattern and indicates an internal parsing bug.`
386
- );
387
- }
388
- const char = pattern[i];
389
- if (char === void 0) continue;
353
+ let resume = 0;
354
+ for (const [i, char] of pattern.split("").entries()) {
355
+ if (i < resume) continue;
390
356
  if (char === "*" && pattern[i + 1] === "*") {
391
357
  const precededBySlashOrStart = i === 0 || pattern[i - 1] === "/";
392
358
  const followedBySlash = pattern[i + 2] === "/";
393
359
  if (precededBySlashOrStart && followedBySlash) {
394
360
  out += "(?:.*/)?";
395
- i += 2;
361
+ resume = i + 3;
396
362
  } else {
397
363
  out += ".*";
398
- i += 1;
364
+ resume = i + 2;
399
365
  }
400
366
  } else if (char === "*") {
401
367
  out += "[^/]*";
@@ -426,7 +392,7 @@ async function discoverSchemaFiles(options) {
426
392
  `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.`
427
393
  );
428
394
  }
429
- return included.map((file) => path4.normalize(file)).sort((a, b) => a < b ? -1 : 1);
395
+ return included.map((file) => path4.normalize(file)).sort();
430
396
  }
431
397
  async function walkDirectory(directory, root, exclude, fs) {
432
398
  const entries = await fs.readdir(directory, { withFileTypes: true });
@@ -456,11 +422,47 @@ function matchesAnyPattern(filePath, patterns) {
456
422
  // src/build/link.ts
457
423
  import path9 from "path";
458
424
 
459
- // src/build/parse.ts
460
- import ts2 from "typescript";
425
+ // src/_ipc/typescript.ts
426
+ import { createRequire } from "module";
427
+ function hasClassicApi(candidate) {
428
+ return typeof candidate?.createSourceFile === "function";
429
+ }
430
+ function isModuleNotFound(error, id) {
431
+ const { code, message } = error ?? {};
432
+ if (code !== "MODULE_NOT_FOUND" && code !== "ERR_MODULE_NOT_FOUND") return false;
433
+ return typeof message === "string" && (message.startsWith(`Cannot find module '${id}'`) || message.startsWith(`Cannot find package '${id}'`));
434
+ }
435
+ function tryLoad(load, id) {
436
+ try {
437
+ return load(id);
438
+ } catch (error) {
439
+ if (isModuleNotFound(error, id)) return void 0;
440
+ throw error;
441
+ }
442
+ }
443
+ function pickCompiler(load) {
444
+ const consumer = tryLoad(load, "typescript");
445
+ if (hasClassicApi(consumer)) return consumer;
446
+ const bundled = tryLoad(load, "@typescript/typescript6");
447
+ if (hasClassicApi(bundled)) return bundled;
448
+ return consumer ?? {};
449
+ }
450
+ var ts = pickCompiler(createRequire(import.meta.url));
451
+
452
+ // src/_ipc/compiler-api.ts
453
+ function assertCompilerApi(product, compiler) {
454
+ if (typeof compiler.createSourceFile === "function") return;
455
+ throw new Error(
456
+ `${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'.`
457
+ );
458
+ }
459
+
460
+ // src/build/compiler-api.ts
461
+ function assertCompilerApi2(compiler) {
462
+ assertCompilerApi("env-cap", compiler);
463
+ }
461
464
 
462
465
  // src/build/literal-eval.ts
463
- import ts from "typescript";
464
466
  function evaluateLiteral(node) {
465
467
  if (ts.isStringLiteralLike(node)) return { ok: true, value: node.text };
466
468
  if (ts.isNumericLiteral(node)) return { ok: true, value: Number(node.text) };
@@ -504,12 +506,13 @@ function getStaticPropertyName(name) {
504
506
 
505
507
  // src/build/parse.ts
506
508
  function parseSchemaFile(filePath, sourceText) {
507
- const sourceFile = ts2.createSourceFile(
509
+ assertCompilerApi2(ts);
510
+ const sourceFile = ts.createSourceFile(
508
511
  filePath,
509
512
  sourceText,
510
- ts2.ScriptTarget.Latest,
513
+ ts.ScriptTarget.Latest,
511
514
  true,
512
- ts2.ScriptKind.TS
515
+ ts.ScriptKind.TS
513
516
  );
514
517
  const warnings = [];
515
518
  const localConsts = /* @__PURE__ */ new Map();
@@ -518,21 +521,21 @@ function parseSchemaFile(filePath, sourceText) {
518
521
  const createEnvCalls = [];
519
522
  const documentEnvCalls = [];
520
523
  for (const statement of sourceFile.statements) {
521
- if (ts2.isImportDeclaration(statement)) {
524
+ if (ts.isImportDeclaration(statement)) {
522
525
  collectImportBindings(statement, imports);
523
526
  continue;
524
527
  }
525
- if (!ts2.isVariableStatement(statement)) continue;
526
- const isExported = statement.modifiers?.some((m) => m.kind === ts2.SyntaxKind.ExportKeyword) ?? false;
528
+ if (!ts.isVariableStatement(statement)) continue;
529
+ const isExported = statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
527
530
  for (const decl of statement.declarationList.declarations) {
528
- if (!ts2.isIdentifier(decl.name) || !decl.initializer) continue;
531
+ if (!ts.isIdentifier(decl.name) || !decl.initializer) continue;
529
532
  const bindingName = decl.name.text;
530
- if (ts2.isObjectLiteralExpression(decl.initializer)) {
533
+ if (ts.isObjectLiteralExpression(decl.initializer)) {
531
534
  localConsts.set(bindingName, decl.initializer);
532
535
  if (isExported) exportedConstNames.add(bindingName);
533
536
  continue;
534
537
  }
535
- if (ts2.isCallExpression(decl.initializer)) {
538
+ if (ts.isCallExpression(decl.initializer)) {
536
539
  if (isCallToName(decl.initializer, "createEnv")) {
537
540
  if (!isExported) {
538
541
  warnings.push({
@@ -560,9 +563,9 @@ function parseSchemaFile(filePath, sourceText) {
560
563
  }
561
564
  }
562
565
  for (const statement of sourceFile.statements) {
563
- if (!ts2.isExpressionStatement(statement)) continue;
566
+ if (!ts.isExpressionStatement(statement)) continue;
564
567
  const expr = statement.expression;
565
- if (!ts2.isCallExpression(expr) || !isCallToName(expr, "documentEnv")) continue;
568
+ if (!ts.isCallExpression(expr) || !isCallToName(expr, "documentEnv")) continue;
566
569
  const [schemaArg, docsArg] = expr.arguments;
567
570
  documentEnvCalls.push({ schemaRef: resolveSchemaRef(schemaArg), docsArg, node: expr });
568
571
  }
@@ -579,15 +582,15 @@ function parseSchemaFile(filePath, sourceText) {
579
582
  }
580
583
  function resolveSchemaRef(node) {
581
584
  if (!node) return { kind: "unresolvable" };
582
- if (ts2.isObjectLiteralExpression(node)) return { kind: "literal", node };
583
- if (ts2.isIdentifier(node)) return { kind: "identifier", name: node.text };
585
+ if (ts.isObjectLiteralExpression(node)) return { kind: "literal", node };
586
+ if (ts.isIdentifier(node)) return { kind: "identifier", name: node.text };
584
587
  return { kind: "unresolvable" };
585
588
  }
586
589
  function collectImportBindings(statement, imports) {
587
- if (!ts2.isStringLiteralLike(statement.moduleSpecifier)) return;
590
+ if (!ts.isStringLiteralLike(statement.moduleSpecifier)) return;
588
591
  const specifier = statement.moduleSpecifier.text;
589
592
  const namedBindings = statement.importClause?.namedBindings;
590
- if (!namedBindings || !ts2.isNamedImports(namedBindings)) return;
593
+ if (!namedBindings || !ts.isNamedImports(namedBindings)) return;
591
594
  for (const element of namedBindings.elements) {
592
595
  const localName = element.name.text;
593
596
  const importedName = element.propertyName?.text ?? localName;
@@ -596,8 +599,8 @@ function collectImportBindings(statement, imports) {
596
599
  }
597
600
  function isCallToName(call, name) {
598
601
  const expr = call.expression;
599
- if (ts2.isIdentifier(expr)) return expr.text === name;
600
- if (ts2.isPropertyAccessExpression(expr)) return expr.name.text === name;
602
+ if (ts.isIdentifier(expr)) return expr.text === name;
603
+ if (ts.isPropertyAccessExpression(expr)) return expr.name.text === name;
601
604
  return false;
602
605
  }
603
606
  function isValidEnvKey(key) {
@@ -606,7 +609,7 @@ function isValidEnvKey(key) {
606
609
  function extractSchemaVariables(schemaLiteral, filePath, contextLabel, warnings, sourceFile) {
607
610
  const variables = [];
608
611
  for (const prop of schemaLiteral.properties) {
609
- if (!ts2.isPropertyAssignment(prop)) {
612
+ if (!ts.isPropertyAssignment(prop)) {
610
613
  warnings.push({
611
614
  file: filePath,
612
615
  message: `Skipped a non-static schema entry in "${contextLabel}" (spread or computed key are not statically analyzable).`
@@ -622,7 +625,7 @@ function extractSchemaVariables(schemaLiteral, filePath, contextLabel, warnings,
622
625
  });
623
626
  continue;
624
627
  }
625
- if (!ts2.isObjectLiteralExpression(prop.initializer)) {
628
+ if (!ts.isObjectLiteralExpression(prop.initializer)) {
626
629
  warnings.push({
627
630
  file: filePath,
628
631
  message: `Definition for "${key}" in "${contextLabel}" is not an inline object literal; skipping static analysis for this variable.`
@@ -646,7 +649,7 @@ function extractSchemaVariable(key, definition, filePath, contextLabel, warnings
646
649
  let validatorSource;
647
650
  let context;
648
651
  for (const prop of definition.properties) {
649
- if (!ts2.isPropertyAssignment(prop)) continue;
652
+ if (!ts.isPropertyAssignment(prop)) continue;
650
653
  const name = getStaticPropertyName(prop.name);
651
654
  if (name === "default") {
652
655
  hasDefault = true;
@@ -684,13 +687,13 @@ function extractSchemaVariable(key, definition, filePath, contextLabel, warnings
684
687
  };
685
688
  }
686
689
  function extractReturnType(node) {
687
- if ((ts2.isArrowFunction(node) || ts2.isFunctionExpression(node)) && node.type) {
688
- return node.type.getText().replace(/\s+/g, "");
690
+ if ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.type) {
691
+ return node.type.getText().replace(/\s/g, "");
689
692
  }
690
693
  return void 0;
691
694
  }
692
695
  function normalizeSource(text) {
693
- return text.replace(/\s+/g, " ").trim();
696
+ return text.replace(/\s+/g, " ");
694
697
  }
695
698
  function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
696
699
  let name;
@@ -709,7 +712,7 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
709
712
  let auditRequired;
710
713
  let metadata;
711
714
  const variables = /* @__PURE__ */ new Map();
712
- if (!docsArg || !ts2.isObjectLiteralExpression(docsArg)) {
715
+ if (!docsArg || !ts.isObjectLiteralExpression(docsArg)) {
713
716
  if (docsArg) {
714
717
  warnings.push({
715
718
  file: filePath,
@@ -736,7 +739,7 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
736
739
  };
737
740
  }
738
741
  for (const prop of docsArg.properties) {
739
- if (!ts2.isPropertyAssignment(prop)) continue;
742
+ if (!ts.isPropertyAssignment(prop)) continue;
740
743
  const propName = getStaticPropertyName(prop.name);
741
744
  if (propName === "name") {
742
745
  const evaluated = evaluateLiteral(prop.initializer);
@@ -840,7 +843,7 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
840
843
  });
841
844
  }
842
845
  } else if (propName === "variables") {
843
- if (ts2.isObjectLiteralExpression(prop.initializer)) {
846
+ if (ts.isObjectLiteralExpression(prop.initializer)) {
844
847
  extractVariableDocsMap(prop.initializer, filePath, contextLabel, warnings, variables);
845
848
  } else {
846
849
  warnings.push({
@@ -871,10 +874,10 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
871
874
  }
872
875
  function extractVariableDocsMap(variablesLiteral, filePath, contextLabel, warnings, out) {
873
876
  for (const prop of variablesLiteral.properties) {
874
- if (!ts2.isPropertyAssignment(prop)) continue;
877
+ if (!ts.isPropertyAssignment(prop)) continue;
875
878
  const key = getStaticPropertyName(prop.name);
876
879
  if (key === void 0) continue;
877
- if (!ts2.isObjectLiteralExpression(prop.initializer)) {
880
+ if (!ts.isObjectLiteralExpression(prop.initializer)) {
878
881
  warnings.push({
879
882
  file: filePath,
880
883
  message: `documentEnv() variable docs for "${key}" in "${contextLabel}" is not an inline object literal; skipped.`
@@ -904,11 +907,9 @@ function extractVariableDocsMap(variablesLiteral, filePath, contextLabel, warnin
904
907
  let metadata;
905
908
  let evidence;
906
909
  for (const field of prop.initializer.properties) {
907
- if (!ts2.isPropertyAssignment(field)) continue;
910
+ if (!ts.isPropertyAssignment(field)) continue;
908
911
  const fieldName = getStaticPropertyName(field.name);
909
- if (fieldName === void 0) continue;
910
912
  const evaluated = evaluateLiteral(field.initializer);
911
- if (!evaluated.ok) continue;
912
913
  if (fieldName === "description" && typeof evaluated.value === "string")
913
914
  description = evaluated.value;
914
915
  else if (fieldName === "owner" && typeof evaluated.value === "string") owner = evaluated.value;
@@ -1004,9 +1005,9 @@ function extractDynamicAccessCitations(value, filePath, key, contextLabel, warni
1004
1005
  return citations;
1005
1006
  }
1006
1007
  function extractCreateEnvOptionsName(optionsArg) {
1007
- if (!optionsArg || !ts2.isObjectLiteralExpression(optionsArg)) return void 0;
1008
+ if (!optionsArg || !ts.isObjectLiteralExpression(optionsArg)) return void 0;
1008
1009
  for (const prop of optionsArg.properties) {
1009
- if (!ts2.isPropertyAssignment(prop)) continue;
1010
+ if (!ts.isPropertyAssignment(prop)) continue;
1010
1011
  if (getStaticPropertyName(prop.name) !== "name") continue;
1011
1012
  const evaluated = evaluateLiteral(prop.initializer);
1012
1013
  if (evaluated.ok && typeof evaluated.value === "string") return evaluated.value;
@@ -1032,11 +1033,98 @@ function mustGet(map, key) {
1032
1033
  return value;
1033
1034
  }
1034
1035
 
1036
+ // src/build/merge-documentation.ts
1037
+ var VALUE_FIELDS = [
1038
+ "description",
1039
+ "owner",
1040
+ "sensitivity",
1041
+ "expiresAt",
1042
+ "refreshInstructions",
1043
+ "authenticatorType",
1044
+ "rotationPeriod",
1045
+ "lastRotatedAt",
1046
+ "rotationTriggerEvents",
1047
+ "setupInstructions",
1048
+ "required",
1049
+ "deprecated",
1050
+ "deprecatedReason",
1051
+ "removeBy",
1052
+ "renamedFrom",
1053
+ "purpose",
1054
+ "legalBasis",
1055
+ "retention",
1056
+ "dataResidency",
1057
+ "auditRequired"
1058
+ ];
1059
+ function mergeSharedDocumentation(contracts) {
1060
+ const declarationsByKey = /* @__PURE__ */ new Map();
1061
+ for (const contract of contracts) {
1062
+ for (const variable of contract.variables) {
1063
+ const declarations = declarationsByKey.get(variable.key);
1064
+ if (declarations === void 0) declarationsByKey.set(variable.key, [{ contract, variable }]);
1065
+ else declarations.push({ contract, variable });
1066
+ }
1067
+ }
1068
+ return contracts.map((contract) => ({
1069
+ ...contract,
1070
+ variables: contract.variables.map((variable) => {
1071
+ const fromPackages = [];
1072
+ const fromApplication = [];
1073
+ for (const declaration of mustGet(declarationsByKey, variable.key)) {
1074
+ if (declaration.variable === variable) continue;
1075
+ const fromPackage = declaration.contract.packageOrigin !== void 0;
1076
+ if (!fromPackage && contract.packageOrigin === void 0) continue;
1077
+ (fromPackage ? fromPackages : fromApplication).push(declaration);
1078
+ }
1079
+ return fromPackages.length + fromApplication.length === 0 ? variable : filled(variable, fromPackages, fromApplication);
1080
+ })
1081
+ }));
1082
+ }
1083
+ function donated(read, fromPackages, fromApplication) {
1084
+ const fromPackage = fromPackages.find(({ variable }) => read(variable) !== void 0);
1085
+ if (fromPackage !== void 0) return read(fromPackage.variable);
1086
+ const values = fromApplication.map(({ variable }) => read(variable)).filter((v) => v !== void 0);
1087
+ return values.every((value) => deepEqual(value, values[0])) ? values[0] : void 0;
1088
+ }
1089
+ function filled(variable, fromPackages, fromApplication) {
1090
+ const donors = [...fromPackages, ...fromApplication];
1091
+ const merged = { ...variable };
1092
+ for (const field of VALUE_FIELDS) {
1093
+ if (variable[field] !== void 0) continue;
1094
+ merged[field] = donated((other) => other[field], fromPackages, fromApplication);
1095
+ }
1096
+ const metadata = {};
1097
+ for (const key of new Set(
1098
+ donors.flatMap(({ variable: other }) => Object.keys(other.metadata ?? {}))
1099
+ )) {
1100
+ const value = donated((other) => other.metadata?.[key], fromPackages, fromApplication);
1101
+ if (value !== void 0) metadata[key] = value;
1102
+ }
1103
+ Object.assign(metadata, variable.metadata);
1104
+ const result = {
1105
+ ...merged,
1106
+ metadata: Object.keys(metadata).length === 0 ? variable.metadata : metadata,
1107
+ documented: variable.documented || donors.some(({ variable: other }) => other.documented)
1108
+ };
1109
+ DONATED.set(
1110
+ result,
1111
+ /* @__PURE__ */ new Set([
1112
+ ...VALUE_FIELDS.filter((field) => result[field] !== variable[field]),
1113
+ ...Object.keys(metadata).filter((key) => metadata[key] !== variable.metadata?.[key]).map((key) => `metadata.${key}`)
1114
+ ])
1115
+ );
1116
+ return result;
1117
+ }
1118
+ var DONATED = /* @__PURE__ */ new WeakMap();
1119
+ function donatedTo(variable) {
1120
+ return DONATED.get(variable) ?? /* @__PURE__ */ new Set();
1121
+ }
1122
+
1035
1123
  // src/build/resolution/resolve-import.ts
1036
1124
  import path8 from "path";
1037
1125
 
1038
1126
  // src/build/resolution/resolve-package-schema.ts
1039
- import { createRequire } from "module";
1127
+ import { createRequire as createRequire2 } from "module";
1040
1128
  import path6 from "path";
1041
1129
 
1042
1130
  // src/build/resolution/resolve-within-root.ts
@@ -1069,7 +1157,7 @@ function isRecord2(value) {
1069
1157
  return typeof value === "object" && value !== null;
1070
1158
  }
1071
1159
  async function locatePackageManifest(packageName, root, fs) {
1072
- const req = createRequire(path6.join(root, "package.json"));
1160
+ const req = createRequire2(path6.join(root, "package.json"));
1073
1161
  try {
1074
1162
  const packageJsonPath = req.resolve(`${packageName}/package.json`);
1075
1163
  return { packageJsonPath, packageDir: path6.dirname(packageJsonPath) };
@@ -1251,7 +1339,6 @@ async function mergeLocalAndPackageFiles(localFiles, packageFiles, fs) {
1251
1339
  }
1252
1340
  async function resolvePackageImport(specifier, allowedPackages, root, cache, fs) {
1253
1341
  const matched = allowedPackages.find(
1254
- // Stryker disable next-line ConditionalExpression
1255
1342
  (pkg) => specifier === pkg || specifier.startsWith(`${pkg}/`)
1256
1343
  );
1257
1344
  if (!matched) return void 0;
@@ -1259,9 +1346,11 @@ async function resolvePackageImport(specifier, allowedPackages, root, cache, fs)
1259
1346
  return result.ok ? result.origin.resolvedFile : void 0;
1260
1347
  }
1261
1348
 
1262
- // src/build/resolution/resolve-tsconfig-paths.ts
1349
+ // src/_ipc/resolve-tsconfig-paths.ts
1263
1350
  import path7 from "path";
1264
- import ts3 from "typescript";
1351
+ function pathMappingOptions(options) {
1352
+ return options;
1353
+ }
1265
1354
  function createAliasResolutionCache() {
1266
1355
  return { resolutions: /* @__PURE__ */ new Map() };
1267
1356
  }
@@ -1272,7 +1361,10 @@ async function fileExists(filePath, fs) {
1272
1361
  }
1273
1362
  return false;
1274
1363
  }
1275
- async function loadTsconfigPaths(root, tsconfigOption, fs) {
1364
+ function typescriptPath(file, separator) {
1365
+ return file.split(separator).join("/");
1366
+ }
1367
+ async function loadTsconfigPaths(product, root, tsconfigOption, fs) {
1276
1368
  if (tsconfigOption === false) return { resolution: void 0, warning: void 0 };
1277
1369
  const isExplicit = tsconfigOption !== void 0;
1278
1370
  const configFile = path7.resolve(root, tsconfigOption ?? "tsconfig.json");
@@ -1286,9 +1378,13 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1286
1378
  }
1287
1379
  };
1288
1380
  }
1289
- const readResult = ts3.readConfigFile(configFile, (p) => ts3.sys.readFile(p));
1381
+ assertCompilerApi(product, ts);
1382
+ const readResult = ts.readConfigFile(
1383
+ typescriptPath(configFile, path7.sep),
1384
+ (p) => ts.sys.readFile(p)
1385
+ );
1290
1386
  if (readResult.error) {
1291
- const detail = ts3.flattenDiagnosticMessageText(readResult.error.messageText, "\n");
1387
+ const detail = ts.flattenDiagnosticMessageText(readResult.error.messageText, ts.sys.newLine);
1292
1388
  return {
1293
1389
  resolution: void 0,
1294
1390
  warning: {
@@ -1297,8 +1393,8 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1297
1393
  }
1298
1394
  };
1299
1395
  }
1300
- const parsed = ts3.parseJsonConfigFileContent(readResult.config, ts3.sys, path7.dirname(configFile));
1301
- const { paths, baseUrl } = parsed.options;
1396
+ const parsed = ts.parseJsonConfigFileContent(readResult.config, ts.sys, path7.dirname(configFile));
1397
+ const { paths, baseUrl } = pathMappingOptions(parsed.options);
1302
1398
  const hasPaths = paths !== void 0 && Object.keys(paths).length > 0;
1303
1399
  if (!hasPaths && baseUrl === void 0) {
1304
1400
  return { resolution: void 0, warning: void 0 };
@@ -1308,7 +1404,7 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1308
1404
  function resolveAliasImport(specifier, importingFile, resolution, cache) {
1309
1405
  const cacheKey = `${importingFile}\0${specifier}`;
1310
1406
  if (cache.resolutions.has(cacheKey)) return cache.resolutions.get(cacheKey);
1311
- const result = ts3.resolveModuleName(specifier, importingFile, resolution.compilerOptions, ts3.sys);
1407
+ const result = ts.resolveModuleName(specifier, importingFile, resolution.compilerOptions, ts.sys);
1312
1408
  const resolvedFileName = result.resolvedModule?.resolvedFileName;
1313
1409
  let resolved;
1314
1410
  if (resolvedFileName) {
@@ -1321,6 +1417,11 @@ function resolveAliasImport(specifier, importingFile, resolution, cache) {
1321
1417
  return resolved;
1322
1418
  }
1323
1419
 
1420
+ // src/build/resolution/resolve-tsconfig-paths.ts
1421
+ function loadTsconfigPaths2(root, tsconfigOption, fs) {
1422
+ return loadTsconfigPaths("env-cap", root, tsconfigOption, fs);
1423
+ }
1424
+
1324
1425
  // src/build/resolution/resolve-import.ts
1325
1426
  async function resolveRelativeImport(importingFile, specifier, fs) {
1326
1427
  if (!specifier.startsWith("./") && !specifier.startsWith("../")) return void 0;
@@ -1336,13 +1437,11 @@ async function resolveRelativeImport(importingFile, specifier, fs) {
1336
1437
  }
1337
1438
  return void 0;
1338
1439
  }
1339
- async function fileExists2(filePath, fs) {
1340
- try {
1341
- const stat = await fs.stat(filePath);
1342
- return stat.isFile();
1343
- } catch {
1344
- return false;
1345
- }
1440
+ function fileExists2(filePath, fs) {
1441
+ return fs.stat(filePath).then(
1442
+ (stat) => stat.isFile(),
1443
+ () => false
1444
+ );
1346
1445
  }
1347
1446
  async function resolveImportSpecifier(importingFile, specifier, context) {
1348
1447
  const relative = await resolveRelativeImport(importingFile, specifier, context.fs);
@@ -1381,24 +1480,29 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1381
1480
  const warnings = [];
1382
1481
  const unresolvedLinks = [];
1383
1482
  async function resolveSchema(ref, inFile, contextLabel) {
1384
- if (ref.kind === "unresolvable") return void 0;
1385
1483
  const inFileAnalysis = mustGet(analysisCache, inFile);
1386
- if (ref.kind === "literal") {
1387
- return {
1388
- identity: `${inFile}#<inline:${ref.node.pos}>`,
1389
- variables: extractSchemaVariables(
1390
- ref.node,
1391
- inFile,
1392
- contextLabel,
1393
- warnings,
1394
- inFileAnalysis.sourceFile
1395
- )
1396
- };
1484
+ switch (ref.kind) {
1485
+ case "literal":
1486
+ return {
1487
+ identity: `${inFile}#<inline:${ref.node.pos}>`,
1488
+ variables: extractSchemaVariables(
1489
+ ref.node,
1490
+ inFile,
1491
+ contextLabel,
1492
+ warnings,
1493
+ inFileAnalysis.sourceFile
1494
+ )
1495
+ };
1496
+ case "identifier":
1497
+ return resolveNamedSchema(ref.name, inFile, inFileAnalysis, contextLabel);
1397
1498
  }
1398
- const local = inFileAnalysis.localConsts.get(ref.name);
1499
+ return void 0;
1500
+ }
1501
+ async function resolveNamedSchema(name, inFile, inFileAnalysis, contextLabel) {
1502
+ const local = inFileAnalysis.localConsts.get(name);
1399
1503
  if (local) {
1400
1504
  return {
1401
- identity: `${inFile}#${ref.name}`,
1505
+ identity: `${inFile}#${name}`,
1402
1506
  variables: extractSchemaVariables(
1403
1507
  local,
1404
1508
  inFile,
@@ -1408,7 +1512,7 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1408
1512
  )
1409
1513
  };
1410
1514
  }
1411
- const imported = inFileAnalysis.imports.get(ref.name);
1515
+ const imported = inFileAnalysis.imports.get(name);
1412
1516
  if (!imported) return void 0;
1413
1517
  const targetFile = await resolveImportSpecifier(inFile, imported.specifier, context);
1414
1518
  if (!targetFile) return void 0;
@@ -1476,7 +1580,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1476
1580
  }
1477
1581
  const contracts = [];
1478
1582
  const undocumentedContracts = [];
1479
- const undocumentedVariables = [];
1480
1583
  const staleDocEntries = [];
1481
1584
  for (const entry of createEnvEntries) {
1482
1585
  const linked = documentEnvByIdentity.get(entry.identity);
@@ -1486,10 +1589,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1486
1589
  }
1487
1590
  const schemaKeys = new Set(entry.variables.map((v) => v.key));
1488
1591
  const docsVariables = docs?.variables ?? /* @__PURE__ */ new Map();
1489
- for (const key of schemaKeys) {
1490
- if (!docsVariables.has(key))
1491
- undocumentedVariables.push({ file: entry.file, exportName: entry.exportName, key });
1492
- }
1493
1592
  for (const key of docsVariables.keys()) {
1494
1593
  if (!schemaKeys.has(key))
1495
1594
  staleDocEntries.push({ file: entry.file, exportName: entry.exportName, key });
@@ -1551,12 +1650,17 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1551
1650
  for (const analysis of analysisCache.values()) {
1552
1651
  warnings.push(...analysis.warnings);
1553
1652
  }
1653
+ const merged = mergeSharedDocumentation(contracts);
1554
1654
  return {
1555
- contracts,
1655
+ contracts: merged,
1556
1656
  warnings,
1557
1657
  unresolvedLinks,
1658
+ // Judged after the merge: a variable a package's contract documents is documented for the application that
1659
+ // declares it again.
1660
+ undocumentedVariables: merged.flatMap(
1661
+ ({ file, exportName, variables }) => variables.filter(({ documented }) => !documented).map(({ key }) => ({ file, exportName, key }))
1662
+ ),
1558
1663
  undocumentedContracts,
1559
- undocumentedVariables,
1560
1664
  staleDocEntries
1561
1665
  };
1562
1666
  }
@@ -1594,7 +1698,7 @@ function effectiveAuditRequired(contract, variable) {
1594
1698
 
1595
1699
  // src/build/assemble-project.ts
1596
1700
  async function assembleProject(options) {
1597
- const { fs, root, include, exclude, packages, tsconfig } = options;
1701
+ const { fs, root, include, exclude, packages = [], tsconfig } = options;
1598
1702
  const fileCache = /* @__PURE__ */ new Map();
1599
1703
  const readFileCached = (filePath) => {
1600
1704
  let cached = fileCache.get(filePath);
@@ -1616,7 +1720,7 @@ async function assembleProject(options) {
1616
1720
  packageFiles.map((f) => f.file),
1617
1721
  fs
1618
1722
  );
1619
- const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths(
1723
+ const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths2(
1620
1724
  root,
1621
1725
  tsconfig,
1622
1726
  fs
@@ -1651,7 +1755,6 @@ function buildChangeModel(manifest, currentContracts, root) {
1651
1755
  const relativeFile = displayPath(root, contract.file);
1652
1756
  const cIdentity = contractIdentity2(relativeFile, contract.exportName);
1653
1757
  for (const variable of contract.variables) {
1654
- if (!variable.renamedFrom) continue;
1655
1758
  const addedRef = findByContractAndKey(
1656
1759
  manifest.addedVariables,
1657
1760
  relativeFile,
@@ -1682,24 +1785,20 @@ function buildChangeModel(manifest, currentContracts, root) {
1682
1785
  }
1683
1786
 
1684
1787
  // src/build/compatibility.ts
1685
- var DOCUMENTATION_COMPARISON_FIELDS = [
1686
- "description",
1687
- "owner",
1688
- "sensitivity",
1689
- "expiresAt",
1690
- "refreshInstructions",
1691
- "setupInstructions",
1692
- "required"
1693
- ];
1694
1788
  function documentationDivergences(a, b) {
1695
1789
  const divergences = [];
1696
- for (const field of DOCUMENTATION_COMPARISON_FIELDS) {
1697
- if (a[field] !== b[field]) divergences.push(field);
1790
+ const given = /* @__PURE__ */ new Set([...donatedTo(a), ...donatedTo(b)]);
1791
+ for (const field of VALUE_FIELDS) {
1792
+ if (!given.has(field) && a[field] !== void 0 && b[field] !== void 0 && !deepEqual(a[field], b[field])) {
1793
+ divergences.push(field);
1794
+ }
1698
1795
  }
1699
1796
  const aMetadata = a.metadata ?? {};
1700
1797
  const bMetadata = b.metadata ?? {};
1701
- for (const key of /* @__PURE__ */ new Set([...Object.keys(aMetadata), ...Object.keys(bMetadata)])) {
1702
- if (!deepEqual(aMetadata[key], bMetadata[key])) divergences.push(`metadata.${key}`);
1798
+ for (const key of Object.keys(aMetadata)) {
1799
+ if (!given.has(`metadata.${key}`) && key in bMetadata && !deepEqual(aMetadata[key], bMetadata[key])) {
1800
+ divergences.push(`metadata.${key}`);
1801
+ }
1703
1802
  }
1704
1803
  return divergences;
1705
1804
  }
@@ -1746,17 +1845,15 @@ function detectCompatibilityIssues(contracts) {
1746
1845
  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.`
1747
1846
  });
1748
1847
  }
1749
- if (a.variable.documented && b.variable.documented) {
1750
- const divergences = documentationDivergences(a.variable, b.variable);
1751
- if (divergences.length > 0) {
1752
- issues.push({
1753
- severity: "warning",
1754
- variable: key,
1755
- files: [a.file, b.file],
1756
- code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1757
- 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.`
1758
- });
1759
- }
1848
+ const divergences = documentationDivergences(a.variable, b.variable);
1849
+ if (divergences.length > 0) {
1850
+ issues.push({
1851
+ severity: "warning",
1852
+ variable: key,
1853
+ files: [a.file, b.file],
1854
+ code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1855
+ 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.`
1856
+ });
1760
1857
  }
1761
1858
  }
1762
1859
  }
@@ -1777,8 +1874,7 @@ function variableShape(variable) {
1777
1874
  };
1778
1875
  }
1779
1876
  function shapesMatch(a, b) {
1780
- if (a.valueType === "unknown" || b.valueType === "unknown") return false;
1781
- return a.valueType === b.valueType && a.hasProcessor === b.hasProcessor && a.hasValidator === b.hasValidator;
1877
+ return a.valueType !== "unknown" && a.valueType === b.valueType && a.hasProcessor === b.hasProcessor && a.hasValidator === b.hasValidator;
1782
1878
  }
1783
1879
  function detectDuplicateVariableShapes(contracts) {
1784
1880
  const candidates = contracts.filter((c) => c.active && !c.exclusiveGroup);
@@ -1919,61 +2015,53 @@ function isPlainObject(value) {
1919
2015
  }
1920
2016
 
1921
2017
  // src/build/scan-dependencies.ts
1922
- import ts4 from "typescript";
1923
2018
  function unwrapParens(node) {
1924
2019
  let current = node;
1925
- while (ts4.isParenthesizedExpression(current)) current = current.expression;
2020
+ while (ts.isParenthesizedExpression(current)) current = current.expression;
1926
2021
  return current;
1927
2022
  }
1928
2023
  function staticElementKey(node) {
1929
- return ts4.isStringLiteralLike(node) ? node.text : void 0;
2024
+ return ts.isStringLiteralLike(node) ? node.text : void 0;
1930
2025
  }
1931
2026
  function forEachBindingName(name, record) {
1932
- if (ts4.isIdentifier(name)) {
2027
+ if (ts.isIdentifier(name)) {
1933
2028
  record(name.text);
1934
2029
  return;
1935
2030
  }
1936
2031
  for (const element of name.elements) {
1937
- if (ts4.isOmittedExpression(element)) continue;
2032
+ if (ts.isOmittedExpression(element)) continue;
1938
2033
  forEachBindingName(element.name, record);
1939
2034
  }
1940
2035
  }
1941
2036
  function isAssignmentToken(token) {
1942
- return token >= ts4.SyntaxKind.FirstAssignment && token <= ts4.SyntaxKind.LastAssignment;
2037
+ return token >= ts.SyntaxKind.FirstAssignment && token <= ts.SyntaxKind.LastAssignment;
1943
2038
  }
1944
2039
  function recordIfIdentifierTarget(expression, assignedNames) {
1945
2040
  const target = unwrapParens(expression);
1946
- if (ts4.isIdentifier(target)) assignedNames.add(target.text);
2041
+ if (ts.isIdentifier(target)) assignedNames.add(target.text);
1947
2042
  }
1948
2043
  function recordAssignmentTargets(node, assignedNames) {
1949
- if (ts4.isBinaryExpression(node) && isAssignmentToken(node.operatorToken.kind)) {
2044
+ if (ts.isBinaryExpression(node) && isAssignmentToken(node.operatorToken.kind)) {
1950
2045
  recordIfIdentifierTarget(node.left, assignedNames);
1951
2046
  return;
1952
2047
  }
1953
- if (
1954
- // Widening this to `true` is behaviorally equivalent, not a real gap:
1955
- // only a prefix/postfix unary node carries an `.operator` at all, so on
1956
- // any other node the two `=== PlusPlus/MinusMinus` checks below both
1957
- // read `undefined` and fail. Hand-verified: mutating this compound to
1958
- // `if (true)` and running the real suite passes unchanged.
1959
- // Stryker disable next-line ConditionalExpression
1960
- (ts4.isPrefixUnaryExpression(node) || ts4.isPostfixUnaryExpression(node)) && (node.operator === ts4.SyntaxKind.PlusPlusToken || node.operator === ts4.SyntaxKind.MinusMinusToken)
1961
- ) {
1962
- recordIfIdentifierTarget(node.operand, assignedNames);
2048
+ const { operator, operand } = node;
2049
+ if (operator === ts.SyntaxKind.PlusPlusToken || operator === ts.SyntaxKind.MinusMinusToken) {
2050
+ recordIfIdentifierTarget(operand, assignedNames);
1963
2051
  return;
1964
2052
  }
1965
- if ((ts4.isForOfStatement(node) || ts4.isForInStatement(node)) && !ts4.isVariableDeclarationList(node.initializer)) {
2053
+ if ((ts.isForOfStatement(node) || ts.isForInStatement(node)) && !ts.isVariableDeclarationList(node.initializer)) {
1966
2054
  recordIfIdentifierTarget(node.initializer, assignedNames);
1967
2055
  }
1968
2056
  }
1969
2057
  function recordDeclarationIntroduction(node, countDeclaration, constAliasCandidates) {
1970
- if (ts4.isVariableDeclaration(node) || ts4.isParameter(node)) {
2058
+ if (ts.isVariableDeclaration(node) || ts.isParameter(node)) {
1971
2059
  forEachBindingName(node.name, countDeclaration);
1972
- if (!ts4.isVariableDeclaration(node) || !ts4.isIdentifier(node.name)) return;
2060
+ if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name)) return;
1973
2061
  if (node.initializer === void 0) return;
1974
2062
  const initializer = unwrapParens(node.initializer);
1975
- const isConst = (ts4.getCombinedNodeFlags(node) & ts4.NodeFlags.Const) !== 0;
1976
- if (isConst && ts4.isIdentifier(initializer)) {
2063
+ const isConst = (ts.getCombinedNodeFlags(node) & ts.NodeFlags.Const) !== 0;
2064
+ if (isConst && ts.isIdentifier(initializer)) {
1977
2065
  constAliasCandidates.push({
1978
2066
  aliasName: node.name.text,
1979
2067
  baseName: initializer.text,
@@ -1982,7 +2070,7 @@ function recordDeclarationIntroduction(node, countDeclaration, constAliasCandida
1982
2070
  }
1983
2071
  return;
1984
2072
  }
1985
- if ((ts4.isFunctionDeclaration(node) || ts4.isClassDeclaration(node)) && node.name) {
2073
+ if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) {
1986
2074
  countDeclaration(node.name.text);
1987
2075
  }
1988
2076
  }
@@ -1996,9 +2084,9 @@ function collectDeclarationFacts(sourceFile) {
1996
2084
  function walk(node) {
1997
2085
  recordDeclarationIntroduction(node, countDeclaration, constAliasCandidates);
1998
2086
  recordAssignmentTargets(node, assignedNames);
1999
- ts4.forEachChild(node, walk);
2087
+ ts.forEachChild(node, walk);
2000
2088
  }
2001
- ts4.forEachChild(sourceFile, walk);
2089
+ ts.forEachChild(sourceFile, walk);
2002
2090
  return { declarationCounts, assignedNames, constAliasCandidates };
2003
2091
  }
2004
2092
  function resolveAliasTargets(candidates, declarationCounts, assignedNames, imports) {
@@ -2023,21 +2111,22 @@ function bindingElementKey(element) {
2023
2111
  if (element.propertyName === void 0) {
2024
2112
  return element.name.text;
2025
2113
  }
2026
- if (ts4.isIdentifier(element.propertyName) || ts4.isStringLiteral(element.propertyName)) {
2114
+ if (ts.isIdentifier(element.propertyName) || ts.isStringLiteral(element.propertyName)) {
2027
2115
  return element.propertyName.text;
2028
2116
  }
2029
- if (ts4.isComputedPropertyName(element.propertyName)) {
2117
+ if (ts.isComputedPropertyName(element.propertyName)) {
2030
2118
  const inner = element.propertyName.expression;
2031
- return ts4.isStringLiteralLike(inner) ? inner.text : inner;
2119
+ return ts.isStringLiteralLike(inner) ? inner.text : inner;
2032
2120
  }
2033
2121
  return element.propertyName;
2034
2122
  }
2035
2123
  function scanFileForDependencies(filePath, sourceText) {
2036
- const scriptKind = filePath.endsWith(".tsx") ? ts4.ScriptKind.TSX : ts4.ScriptKind.TS;
2037
- const sourceFile = ts4.createSourceFile(
2124
+ assertCompilerApi2(ts);
2125
+ const scriptKind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
2126
+ const sourceFile = ts.createSourceFile(
2038
2127
  filePath,
2039
2128
  sourceText,
2040
- ts4.ScriptTarget.Latest,
2129
+ ts.ScriptTarget.Latest,
2041
2130
  // Load-bearing, unlike before: `ts.getCombinedNodeFlags()` (used to tell
2042
2131
  // a `const` declaration apart from `let`/`var` when resolving alias
2043
2132
  // candidates) walks parent pointers internally. Flipping this to `false`
@@ -2049,9 +2138,9 @@ function scanFileForDependencies(filePath, sourceText) {
2049
2138
  const imports = /* @__PURE__ */ new Map();
2050
2139
  let hasWildcardReExport = false;
2051
2140
  for (const statement of sourceFile.statements) {
2052
- if (ts4.isImportDeclaration(statement)) {
2141
+ if (ts.isImportDeclaration(statement)) {
2053
2142
  collectImportBindings(statement, imports);
2054
- } else if (ts4.isExportDeclaration(statement) && !statement.exportClause && statement.moduleSpecifier) {
2143
+ } else if (ts.isExportDeclaration(statement) && !statement.exportClause && statement.moduleSpecifier) {
2055
2144
  hasWildcardReExport = true;
2056
2145
  }
2057
2146
  }
@@ -2082,7 +2171,7 @@ function scanFileForDependencies(filePath, sourceText) {
2082
2171
  for (const element of pattern.elements) {
2083
2172
  if (element.dotDotDotToken) {
2084
2173
  record(localName, { kind: "escape", via: "rest", ...positionOf(sourceFile, element) });
2085
- } else if (!ts4.isIdentifier(element.name)) {
2174
+ } else if (!ts.isIdentifier(element.name)) {
2086
2175
  record(localName, {
2087
2176
  kind: "escape",
2088
2177
  via: "nested-pattern",
@@ -2098,17 +2187,17 @@ function scanFileForDependencies(filePath, sourceText) {
2098
2187
  via: "computed-key",
2099
2188
  ...positionOf(sourceFile, element)
2100
2189
  });
2101
- ts4.forEachChild(key, visit);
2190
+ ts.forEachChild(key, visit);
2102
2191
  }
2103
2192
  }
2104
- if (element.initializer) ts4.forEachChild(element.initializer, visit);
2193
+ ts.forEachChild(element.initializer, visit);
2105
2194
  }
2106
2195
  }
2107
2196
  function tryRecordPropertyOrElementAccess(node) {
2108
- const isProperty = ts4.isPropertyAccessExpression(node);
2109
- if (!isProperty && !ts4.isElementAccessExpression(node)) return false;
2197
+ const isProperty = ts.isPropertyAccessExpression(node);
2198
+ if (!isProperty && !ts.isElementAccessExpression(node)) return false;
2110
2199
  const base = unwrapParens(node.expression);
2111
- if (!ts4.isIdentifier(base) || !imports.has(base.text)) return false;
2200
+ if (!ts.isIdentifier(base) || !imports.has(base.text)) return false;
2112
2201
  if (isProperty) {
2113
2202
  record(base.text, { kind: "member", member: node.name.text, ...positionOf(sourceFile, node) });
2114
2203
  return true;
@@ -2118,49 +2207,92 @@ function scanFileForDependencies(filePath, sourceText) {
2118
2207
  base.text,
2119
2208
  key !== void 0 ? { kind: "member", member: key, ...positionOf(sourceFile, node) } : { kind: "dynamic", ...positionOf(sourceFile, node) }
2120
2209
  );
2121
- ts4.forEachChild(node.argumentExpression, visit);
2210
+ ts.forEachChild(node.argumentExpression, visit);
2122
2211
  return true;
2123
2212
  }
2124
2213
  function visit(node) {
2125
- if (ts4.isImportDeclaration(node) || ts4.isExportDeclaration(node) || ts4.isVariableDeclaration(node) && handledDeclarations.has(node)) {
2214
+ if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node) || ts.isVariableDeclaration(node) && handledDeclarations.has(node)) {
2126
2215
  return;
2127
2216
  }
2128
- if (ts4.isVariableDeclaration(node) && ts4.isObjectBindingPattern(node.name) && node.initializer) {
2217
+ if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer) {
2129
2218
  const base = unwrapParens(node.initializer);
2130
- if (ts4.isIdentifier(base) && imports.has(base.text)) {
2219
+ if (ts.isIdentifier(base) && imports.has(base.text)) {
2131
2220
  recordObjectBindingAccesses(node.name, base.text);
2132
2221
  return;
2133
2222
  }
2134
2223
  }
2135
2224
  if (tryRecordPropertyOrElementAccess(node)) return;
2136
- if (ts4.isIdentifier(node) && imports.has(node.text)) {
2225
+ if (ts.isIdentifier(node) && imports.has(node.text)) {
2137
2226
  record(node.text, { kind: "reference", ...positionOf(sourceFile, node) });
2138
2227
  return;
2139
2228
  }
2140
- ts4.forEachChild(node, visit);
2229
+ ts.forEachChild(node, visit);
2141
2230
  }
2142
- ts4.forEachChild(sourceFile, visit);
2231
+ ts.forEachChild(sourceFile, visit);
2143
2232
  return { file: filePath, imports, accessesByLocalName: accesses, hasWildcardReExport };
2144
2233
  }
2145
2234
 
2235
+ // src/_ipc/generated-banner.ts
2236
+ function marker() {
2237
+ return "GENERATED FILE -- do not edit by hand";
2238
+ }
2239
+ function createGeneratedBanner(describe) {
2240
+ return {
2241
+ reportRegenerateHint: () => describe().reportRegenerateHint,
2242
+ generatedBanner: (format = "ts", regenerate = `Run \`${describe().cliCommand}\` to regenerate.`) => {
2243
+ const text = `${marker()}. ${regenerate}`;
2244
+ return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2245
+ },
2246
+ // Not a bare `startsWith`: a shebang, a `"use strict"` pragma or a license header pushes a real marker
2247
+ // off line one, and a stricter check would read a genuinely generated file as hand-written, which a
2248
+ // dependency scan would take as "a real consumer imports this" and so permanently mask an abandoned
2249
+ // contract. The first 20 non-empty lines clear every realistic preamble without scanning a whole file.
2250
+ // A line counts only when the marker opens a comment, as `generatedBanner` writes it, so code or prose that
2251
+ // merely quotes the marker is not mistaken for a generated file.
2252
+ isGeneratedFile: (content) => {
2253
+ let seen = 0;
2254
+ for (const [line] of content.matchAll(/[^\n]*/g)) {
2255
+ const text = line.trimStart();
2256
+ if (text === "") continue;
2257
+ if (text.startsWith(`// ${marker()}`) || text.startsWith(`<!-- ${marker()}`)) return true;
2258
+ seen += 1;
2259
+ if (seen === 20) break;
2260
+ }
2261
+ return false;
2262
+ },
2263
+ 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.",
2264
+ evidenceProjectionNote: (evidencePath) => {
2265
+ const { product, guideUrl } = describe();
2266
+ const concept = `Projected from ${product}'s Evidence Model (${guideUrl}), the same source every other generated artifact draws from.`;
2267
+ return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2268
+ }
2269
+ };
2270
+ }
2271
+
2146
2272
  // src/build/generated-banner.ts
2147
- function generatedFileMarker() {
2148
- return "GENERATED FILE";
2273
+ function envCap() {
2274
+ return {
2275
+ product: "env-cap",
2276
+ guideUrl: "https://github.com/MaverickCER/env-cap/blob/main/GUIDE.md",
2277
+ cliCommand: "npx env-cap",
2278
+ reportRegenerateHint: "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`."
2279
+ };
2280
+ }
2281
+ var banner = createGeneratedBanner(envCap);
2282
+ function reportRegenerateHint() {
2283
+ return banner.reportRegenerateHint();
2149
2284
  }
2150
- function generatedBanner(format = "ts") {
2151
- const text = `${generatedFileMarker()} -- do not edit by hand. Run \`npx env-cap\` to regenerate.`;
2152
- return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2285
+ function generatedBanner(format, regenerate) {
2286
+ return banner.generatedBanner(format, regenerate);
2153
2287
  }
2154
2288
  function isGeneratedFile(content) {
2155
- const nonEmptyLines = content.split("\n").filter((line) => line.trim().length > 0);
2156
- return nonEmptyLines.slice(0, 20).some((line) => line.includes(generatedFileMarker()));
2289
+ return banner.isGeneratedFile(content);
2157
2290
  }
2158
2291
  function evidenceDisclaimer() {
2159
- 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.";
2292
+ return banner.evidenceDisclaimer();
2160
2293
  }
2161
2294
  function evidenceProjectionNote(evidencePath) {
2162
- const concept = "Projected from env-cap's Evidence Model (ADR 0031/0038), the same source every other generated artifact draws from.";
2163
- return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2295
+ return banner.evidenceProjectionNote(evidencePath);
2164
2296
  }
2165
2297
 
2166
2298
  // src/build/dependency-graph.ts
@@ -2270,8 +2402,7 @@ async function buildDependencyGraph(contracts, scanFiles, readFile, context, sca
2270
2402
  for (const scan of scanResults) {
2271
2403
  for (const [localName, binding] of scan.imports) {
2272
2404
  const resolvedFile = await resolveImportSpecifier(scan.file, binding.specifier, context);
2273
- if (!resolvedFile) continue;
2274
- const building = byIdentity2.get(`${resolvedFile}#${binding.importedName}`);
2405
+ const building = byIdentity2.get(`${String(resolvedFile)}#${binding.importedName}`);
2275
2406
  if (!building) continue;
2276
2407
  building.imported = true;
2277
2408
  building.consumingFiles.add(scan.file);
@@ -2281,8 +2412,7 @@ async function buildDependencyGraph(contracts, scanFiles, readFile, context, sca
2281
2412
  for (const scan of scanResults) {
2282
2413
  for (const [, binding] of scan.imports) {
2283
2414
  const resolvedFile = await resolveImportSpecifier(scan.file, binding.specifier, context);
2284
- if (!resolvedFile) continue;
2285
- const targetScan = scanByFile.get(resolvedFile);
2415
+ const targetScan = scanByFile.get(String(resolvedFile));
2286
2416
  if (!targetScan?.hasWildcardReExport) continue;
2287
2417
  for (const building of byIdentity2.values()) {
2288
2418
  if (building.imported) continue;
@@ -2385,20 +2515,9 @@ async function buildDependencyModel(contracts, scanFiles, readFile, context, roo
2385
2515
  positions: info.positions.map((p) => relativizePosition2(root, p)),
2386
2516
  dynamicAccessAssertions: info.dynamicAccessAssertions
2387
2517
  })).sort((a, b) => a.key.localeCompare(b.key)),
2388
- // `.sort()` here (and the whole `.map(...).sort()` chain as one
2389
- // `MethodExpression` unit) is a defensive no-op, not a real gap:
2390
- // dependency-graph.ts's own `consumingFiles` is already
2391
- // `[...building.consumingFiles].sort()` before this projection ever
2392
- // sees it (see that file's own comment). Hand-verified: dropping this
2393
- // `.sort()` and running the real suite passes unchanged -- confirmed
2394
- // again 2026-09-18 against CI's own diagnostic mutation report, which
2395
- // flagged this exact `MethodExpression` mutant as Survived.
2396
- // Stryker disable next-line MethodExpression
2518
+ // Sorted after mapping to display paths: a file outside `root` (a package surface) shows as
2519
+ // `../...`, which can order differently from its absolute path.
2397
2520
  consumingFiles: [...contract.consumingFiles].map((f) => displayPath(root, f)).sort(),
2398
- // Same reasoning as `consumingFiles` just above -- the whole
2399
- // `.map(...).sort()` chain is a coarser-grained `MethodExpression`
2400
- // mutant target than the next-line one on `.sort()` alone just below.
2401
- // Stryker disable next-line MethodExpression
2402
2521
  ambiguousBarrelFiles: [...contract.ambiguousBarrelFiles].map((f) => displayPath(root, f)).sort(),
2403
2522
  dynamicAccessSites: contract.dynamicAccessSites.map((p) => relativizePosition2(root, p))
2404
2523
  }));
@@ -2562,30 +2681,11 @@ function renderManifest(contracts, outputFile) {
2562
2681
  for (const contract of sorted) {
2563
2682
  let localName = contract.exportName;
2564
2683
  if (usedNames.has(localName)) {
2565
- const maxSuffix = sorted.length + 16;
2566
- let found;
2567
- let passes = 0;
2568
- for (let suffix = 1; suffix <= maxSuffix; suffix++) {
2569
- passes++;
2570
- if (passes > maxSuffix) {
2571
- throw new Error(
2572
- // Stryker disable next-line StringLiteral
2573
- `renderManifest: exceeded ${String(maxSuffix)} attempts choosing a unique local import name for "${contract.exportName}" -- this should never happen and indicates an internal naming bug.`
2574
- );
2575
- }
2576
- const candidate = `${contract.exportName}_${suffix}`;
2577
- if (!usedNames.has(candidate)) {
2578
- found = candidate;
2579
- break;
2580
- }
2581
- }
2582
- if (found === void 0) {
2583
- throw new Error(
2584
- // Stryker disable next-line StringLiteral
2585
- `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.`
2586
- );
2587
- }
2588
- localName = found;
2684
+ const candidates = Array.from(
2685
+ { length: usedNames.size + 1 },
2686
+ (_, index) => `${contract.exportName}_${index + 1}`
2687
+ );
2688
+ localName = String(candidates.find((candidate) => !usedNames.has(candidate)));
2589
2689
  }
2590
2690
  usedNames.add(localName);
2591
2691
  referenceNames.push(localName);
@@ -2634,10 +2734,8 @@ function defaultExclude() {
2634
2734
  // inspect `exclude` directly, and as defense if that hardcoding ever
2635
2735
  // changes) -- hand-verified: emptying both and running the full
2636
2736
  // `vitest run` leaves all 1243 tests passing.
2637
- // Stryker disable next-line StringLiteral
2638
2737
  "**/node_modules/**",
2639
2738
  "**/dist/**",
2640
- // Stryker disable next-line StringLiteral
2641
2739
  "**/.git/**"
2642
2740
  ];
2643
2741
  }
@@ -2667,8 +2765,6 @@ async function generateEnvManifest(options) {
2667
2765
  const root = path11.resolve(options.root ?? process.cwd());
2668
2766
  const include = options.include ?? defaultInclude();
2669
2767
  const exclude = options.exclude ?? defaultExclude();
2670
- const packages = options.packages ?? [];
2671
- const onIncompatibility = options.onIncompatibility ?? "warn";
2672
2768
  const locationResult = resolveWithinRoot(
2673
2769
  root,
2674
2770
  options.location,
@@ -2682,10 +2778,10 @@ async function generateEnvManifest(options) {
2682
2778
  root,
2683
2779
  include,
2684
2780
  exclude,
2685
- packages,
2781
+ packages: options.packages,
2686
2782
  tsconfig: options.tsconfig
2687
2783
  });
2688
- const computed = computeManifest(root, linkResult, onIncompatibility);
2784
+ const computed = computeManifest(root, linkResult, options.onIncompatibility);
2689
2785
  if (computed.blocking.length > 0) throw new EnvManifestGenerationError(computed.blocking);
2690
2786
  await writeManifest(outputPath, computed.activeContracts, options.fs);
2691
2787
  return {
@@ -2828,7 +2924,7 @@ function renderParseWarnings(warnings) {
2828
2924
  }
2829
2925
  function renderUsageReport(computed) {
2830
2926
  const lines = [
2831
- generatedBanner("markdown"),
2927
+ generatedBanner("markdown", reportRegenerateHint()),
2832
2928
  "",
2833
2929
  `> ${evidenceDisclaimer()}`,
2834
2930
  "",
@@ -2836,7 +2932,7 @@ function renderUsageReport(computed) {
2836
2932
  "",
2837
2933
  "# Dependency & Ownership Report",
2838
2934
  "",
2839
- "_Produced by `env-cap --ownership`._",
2935
+ "_Produced by `generateUsageReport()` from `@maverickcer/env-cap/build`._",
2840
2936
  "",
2841
2937
  "Which feature owns each variable, which features consume that contract, and what the blast radius is if it changes.",
2842
2938
  "",
@@ -2848,7 +2944,7 @@ function renderUsageReport(computed) {
2848
2944
  ...renderAsserted(computed.asserted),
2849
2945
  ...renderParseWarnings(computed.parseWarnings)
2850
2946
  ];
2851
- return lines.join("\n").replace(/\n{3,}/g, "\n\n");
2947
+ return lines.join("\n");
2852
2948
  }
2853
2949
 
2854
2950
  // src/build/generate-usage.ts
@@ -2879,7 +2975,7 @@ async function computeScanSurface(root, exclude, origins, fs) {
2879
2975
  }
2880
2976
  return { scanFiles, scannedSurfaces };
2881
2977
  }
2882
- async function computeUsage(root, contracts, scanFiles, readFile, context, parseWarnings, scannedSurfaces, dynamicAccessAcknowledgments) {
2978
+ async function computeUsage(root, contracts, scanFiles, readFile, context, scannedSurfaces, dynamicAccessAcknowledgments) {
2883
2979
  const graph = await buildDependencyGraph(
2884
2980
  contracts,
2885
2981
  scanFiles,
@@ -2892,13 +2988,9 @@ async function computeUsage(root, contracts, scanFiles, readFile, context, parse
2892
2988
  const contractByIdentity = /* @__PURE__ */ new Map();
2893
2989
  for (const contract of contracts)
2894
2990
  contractByIdentity.set(`${contract.file}#${contract.exportName}`, contract);
2895
- const ownerFor = (file, exportName) => (
2896
- // Stryker disable next-line OptionalChaining
2897
- contractByIdentity.get(`${file}#${exportName}`)?.owner
2898
- );
2991
+ const ownerFor = (file, exportName) => mustGet(contractByIdentity, `${file}#${exportName}`).owner;
2899
2992
  const effectiveOwnerFor = (file, exportName, key) => {
2900
- const contract = contractByIdentity.get(`${file}#${exportName}`);
2901
- if (!contract) return void 0;
2993
+ const contract = mustGet(contractByIdentity, `${file}#${exportName}`);
2902
2994
  const variable = contract.variables.find((v) => v.key === key);
2903
2995
  return variable ? effectiveOwner(contract, variable) : contract.owner;
2904
2996
  };
@@ -2924,19 +3016,16 @@ async function computeUsage(root, contracts, scanFiles, readFile, context, parse
2924
3016
  const staleOrMissingCitationsFor = (contractName, file, exportName, key) => {
2925
3017
  const relativeFile = displayPath(root, file);
2926
3018
  const identity = dynamicAccessVariableIdentity(relativeFile, exportName, key);
2927
- const problems = [];
2928
- for (const a of dynamicAccessAcknowledgments?.get(identity) ?? []) {
2929
- if (a.acknowledgment === "fresh") continue;
2930
- problems.push({
3019
+ return (dynamicAccessAcknowledgments?.get(identity) ?? []).map(
3020
+ (a) => ({
2931
3021
  contractName,
2932
3022
  file: relativeFile,
2933
3023
  exportName,
2934
3024
  key,
2935
3025
  position: { file: a.file, line: a.line, column: a.column },
2936
3026
  acknowledgment: a.acknowledgment
2937
- });
2938
- }
2939
- return problems;
3027
+ })
3028
+ );
2940
3029
  };
2941
3030
  const unconsumedOwnedVariables = findings.unconsumedOwned.map(
2942
3031
  (f) => ({
@@ -2981,7 +3070,6 @@ async function computeUsage(root, contracts, scanFiles, readFile, context, parse
2981
3070
  unconsumedOwnedVariables,
2982
3071
  indeterminate,
2983
3072
  asserted,
2984
- parseWarnings,
2985
3073
  scannedSurfaces: graph.scannedSurfaces
2986
3074
  }
2987
3075
  };
@@ -2995,24 +3083,23 @@ async function generateUsageReport(options) {
2995
3083
  const root = path12.resolve(options.root ?? process.cwd());
2996
3084
  const include = options.include ?? defaultInclude();
2997
3085
  const exclude = options.exclude ?? defaultExclude();
2998
- const packages = options.packages ?? [];
2999
3086
  let reportPath;
3000
3087
  if (options.report) {
3001
- const result = resolveWithinRoot(
3088
+ const result2 = resolveWithinRoot(
3002
3089
  root,
3003
3090
  options.report.location,
3004
3091
  "report.location",
3005
3092
  "generateUsageReport"
3006
3093
  );
3007
- if (!result.ok) throw new EnvUsageAnalysisError([result.issue]);
3008
- reportPath = result.resolved;
3094
+ if (!result2.ok) throw new EnvUsageAnalysisError([result2.issue]);
3095
+ reportPath = result2.resolved;
3009
3096
  }
3010
3097
  const { readFileCached, linkResult, context, origins, packageWarnings, tsconfigWarnings } = await assembleProject({
3011
3098
  fs: options.fs,
3012
3099
  root,
3013
3100
  include,
3014
3101
  exclude,
3015
- packages,
3102
+ packages: options.packages,
3016
3103
  tsconfig: options.tsconfig
3017
3104
  });
3018
3105
  const { scanFiles, scannedSurfaces } = await computeScanSurface(
@@ -3027,11 +3114,14 @@ async function generateUsageReport(options) {
3027
3114
  scanFiles,
3028
3115
  readFileCached,
3029
3116
  context,
3030
- [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings],
3031
3117
  scannedSurfaces
3032
3118
  );
3033
- if (reportPath) await writeUsageReport(reportPath, computed.result, options.fs);
3034
- return { reportPath, ...computed.result };
3119
+ const result = {
3120
+ ...computed.result,
3121
+ parseWarnings: [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings]
3122
+ };
3123
+ if (reportPath) await writeUsageReport(reportPath, result, options.fs);
3124
+ return { reportPath, ...result };
3035
3125
  }
3036
3126
 
3037
3127
  // src/build/generate-evidence.ts
@@ -3351,107 +3441,132 @@ function groupVariablesByOwner(contracts, ownerOf) {
3351
3441
  }
3352
3442
  return byOwner;
3353
3443
  }
3354
- var configurationReference = defineEvidenceProjection({
3355
- // Stryker disable next-line ArrowFunction
3356
- disclaimer: () => evidenceDisclaimer(),
3357
- entries: (evidence) => {
3358
- const entries = [];
3359
- for (const contract of evidence.contract.contracts) {
3360
- for (const variable of contract.variables) {
3361
- entries.push({
3362
- file: contract.file,
3363
- exportName: contract.exportName,
3364
- contractName: contract.contractName,
3365
- key: variable.key,
3366
- description: variable.description,
3367
- owner: variable.owner ?? contract.owner,
3368
- sensitivity: variable.sensitivity ?? contract.sensitivity,
3369
- required: variable.required,
3370
- hasDefault: variable.hasDefault,
3371
- hasProcessor: variable.hasProcessor,
3372
- hasValidator: variable.hasValidator,
3373
- expiresAt: variable.expiresAt,
3374
- active: contract.active
3375
- });
3444
+ function configurationReference(evidence) {
3445
+ return projectConfigurationReference(evidence).value;
3446
+ }
3447
+ configurationReference.project = projectConfigurationReference;
3448
+ function projectConfigurationReference(evidence) {
3449
+ return defineEvidenceProjection(configurationReferenceSchema()).project(evidence);
3450
+ }
3451
+ function configurationReferenceSchema() {
3452
+ return {
3453
+ disclaimer: evidenceDisclaimer,
3454
+ entries: (evidence) => {
3455
+ const entries = [];
3456
+ for (const contract of evidence.contract.contracts) {
3457
+ for (const variable of contract.variables) {
3458
+ entries.push({
3459
+ file: contract.file,
3460
+ exportName: contract.exportName,
3461
+ contractName: contract.contractName,
3462
+ key: variable.key,
3463
+ description: variable.description,
3464
+ owner: variable.owner ?? contract.owner,
3465
+ sensitivity: variable.sensitivity ?? contract.sensitivity,
3466
+ required: variable.required,
3467
+ hasDefault: variable.hasDefault,
3468
+ hasProcessor: variable.hasProcessor,
3469
+ hasValidator: variable.hasValidator,
3470
+ expiresAt: variable.expiresAt,
3471
+ active: contract.active
3472
+ });
3473
+ }
3376
3474
  }
3475
+ return entries.sort(byContractThenKey);
3377
3476
  }
3378
- return entries.sort(byContractThenKey);
3379
- }
3380
- });
3381
- var ownershipSummary = defineEvidenceProjection({
3382
- // Stryker disable next-line ArrowFunction
3383
- disclaimer: () => evidenceDisclaimer(),
3384
- owners: (evidence) => {
3385
- const contracts = contractIndex(evidence.contract.contracts);
3386
- const nameOf = (file, exportName) => contracts.get(`${file}#${exportName}`)?.contractName ?? exportName;
3387
- const variablesByOwner = groupVariablesByOwner(
3388
- evidence.ownership.contracts,
3389
- (_contract, variable) => variable.owner
3390
- );
3391
- const contractsByOwner = /* @__PURE__ */ new Map();
3392
- for (const contract of evidence.ownership.contracts) {
3393
- if (contract.owner === void 0) continue;
3394
- const list = contractsByOwner.get(contract.owner) ?? [];
3395
- list.push(nameOf(contract.file, contract.exportName));
3396
- contractsByOwner.set(contract.owner, list);
3477
+ };
3478
+ }
3479
+ function ownershipSummary(evidence) {
3480
+ return projectOwnershipSummary(evidence).value;
3481
+ }
3482
+ ownershipSummary.project = projectOwnershipSummary;
3483
+ function projectOwnershipSummary(evidence) {
3484
+ return defineEvidenceProjection(ownershipSummarySchema()).project(evidence);
3485
+ }
3486
+ function ownershipSummarySchema() {
3487
+ return {
3488
+ disclaimer: evidenceDisclaimer,
3489
+ owners: (evidence) => {
3490
+ const contracts = contractIndex(evidence.contract.contracts);
3491
+ const nameOf = (file, exportName) => contracts.get(`${file}#${exportName}`)?.contractName ?? exportName;
3492
+ const variablesByOwner = groupVariablesByOwner(
3493
+ evidence.ownership.contracts,
3494
+ (_contract, variable) => variable.owner
3495
+ );
3496
+ const contractsByOwner = /* @__PURE__ */ new Map();
3497
+ for (const contract of evidence.ownership.contracts) {
3498
+ if (contract.owner === void 0) continue;
3499
+ const list = contractsByOwner.get(contract.owner) ?? [];
3500
+ list.push(nameOf(contract.file, contract.exportName));
3501
+ contractsByOwner.set(contract.owner, list);
3502
+ }
3503
+ const owners = /* @__PURE__ */ new Set([...variablesByOwner.keys(), ...contractsByOwner.keys()]);
3504
+ return [...owners].sort().map((owner) => ({
3505
+ owner,
3506
+ variables: (variablesByOwner.get(owner) ?? []).map(
3507
+ ({ contract, variable }) => `${nameOf(contract.file, contract.exportName)}.${variable.key}`
3508
+ ).sort(),
3509
+ contracts: (contractsByOwner.get(owner) ?? []).sort()
3510
+ }));
3511
+ },
3512
+ unowned: (evidence) => {
3513
+ const contracts = contractIndex(evidence.contract.contracts);
3514
+ return evidence.ownership.unownedVariables.map((ref) => {
3515
+ const contractName = contracts.get(`${ref.file}#${ref.exportName}`)?.contractName ?? ref.exportName;
3516
+ return `${contractName}.${ref.key}`;
3517
+ }).sort();
3397
3518
  }
3398
- const owners = /* @__PURE__ */ new Set([...variablesByOwner.keys(), ...contractsByOwner.keys()]);
3399
- return [...owners].sort().map((owner) => ({
3400
- owner,
3401
- variables: (variablesByOwner.get(owner) ?? []).map(
3402
- ({ contract, variable }) => `${nameOf(contract.file, contract.exportName)}.${variable.key}`
3403
- ).sort(),
3404
- contracts: (contractsByOwner.get(owner) ?? []).sort()
3405
- }));
3406
- },
3407
- unowned: (evidence) => {
3408
- const contracts = contractIndex(evidence.contract.contracts);
3409
- return evidence.ownership.unownedVariables.map((ref) => {
3410
- const contractName = contracts.get(`${ref.file}#${ref.exportName}`)?.contractName ?? ref.exportName;
3411
- return `${contractName}.${ref.key}`;
3412
- }).sort();
3413
- }
3414
- });
3415
- var expiringSoonReport = defineEvidenceProjection({
3416
- // Stryker disable next-line ArrowFunction
3417
- disclaimer: () => evidenceDisclaimer(),
3418
- entries: (evidence) => {
3419
- const contracts = contractIndex(evidence.contract.contracts);
3420
- const ownerByVariable = /* @__PURE__ */ new Map();
3421
- for (const contract of evidence.ownership.contracts)
3422
- for (const variable of contract.variables)
3423
- ownerByVariable.set(
3424
- `${contract.file}#${contract.exportName}#${variable.key}`,
3425
- variable.owner
3426
- );
3427
- return evidence.lifecycle.expiring.map((entry) => {
3428
- const contract = contracts.get(`${entry.file}#${entry.exportName}`);
3429
- const variable = entry.key === void 0 ? void 0 : contract?.variables.find((v) => v.key === entry.key);
3430
- return {
3431
- file: entry.file,
3432
- exportName: entry.exportName,
3433
- contractName: contract?.contractName ?? entry.exportName,
3434
- key: entry.key,
3435
- expiresAt: entry.expiresAt,
3436
- daysRemaining: entry.daysRemaining,
3437
- expired: entry.daysRemaining < 0,
3438
- refreshInstructions: variable?.refreshInstructions,
3439
- owner: entry.key === void 0 ? contract?.owner : ownerByVariable.get(`${entry.file}#${entry.exportName}#${entry.key}`) ?? contract?.owner
3440
- };
3441
- });
3442
- },
3443
- // Same static covered-mutant false-Survivor as the `disclaimer` arrows
3444
- // above -- hand-verified killed (mutating this whole arrow to `() =>
3445
- // undefined` fails the "expiredCount" assertions in every test above).
3446
- // Stryker disable next-line ArrowFunction
3447
- expiredCount: (evidence) => evidence.lifecycle.expiring.filter((e) => e.daysRemaining < 0).length
3448
- });
3519
+ };
3520
+ }
3521
+ function expiringSoonReport(evidence) {
3522
+ return projectExpiringSoonReport(evidence).value;
3523
+ }
3524
+ expiringSoonReport.project = projectExpiringSoonReport;
3525
+ function projectExpiringSoonReport(evidence) {
3526
+ return defineEvidenceProjection(expiringSoonReportSchema()).project(evidence);
3527
+ }
3528
+ function expiringSoonReportSchema() {
3529
+ return {
3530
+ disclaimer: evidenceDisclaimer,
3531
+ entries: (evidence) => {
3532
+ const contracts = contractIndex(evidence.contract.contracts);
3533
+ const ownerByVariable = /* @__PURE__ */ new Map();
3534
+ for (const contract of evidence.ownership.contracts)
3535
+ for (const variable of contract.variables)
3536
+ ownerByVariable.set(
3537
+ `${contract.file}#${contract.exportName}#${variable.key}`,
3538
+ variable.owner
3539
+ );
3540
+ return evidence.lifecycle.expiring.map((entry) => {
3541
+ const contract = contracts.get(`${entry.file}#${entry.exportName}`);
3542
+ const variable = contract?.variables.find((v) => v.key === entry.key);
3543
+ return {
3544
+ file: entry.file,
3545
+ exportName: entry.exportName,
3546
+ contractName: contract?.contractName ?? entry.exportName,
3547
+ key: entry.key,
3548
+ expiresAt: entry.expiresAt,
3549
+ daysRemaining: entry.daysRemaining,
3550
+ expired: entry.daysRemaining < 0,
3551
+ refreshInstructions: variable?.refreshInstructions,
3552
+ owner: entry.key === void 0 ? contract?.owner : ownerByVariable.get(`${entry.file}#${entry.exportName}#${entry.key}`) ?? contract?.owner
3553
+ };
3554
+ });
3555
+ },
3556
+ expiredCount: (evidence) => evidence.lifecycle.expiring.filter((e) => e.daysRemaining < 0).length
3557
+ };
3558
+ }
3449
3559
 
3450
3560
  // src/build/docs.ts
3451
3561
  function parseIsoDate(value) {
3452
3562
  const date = new Date(value);
3453
3563
  return Number.isNaN(date.getTime()) ? void 0 : date;
3454
3564
  }
3565
+ function parseExpiry(expiresAt) {
3566
+ const raw = String(expiresAt);
3567
+ const date = parseIsoDate(raw);
3568
+ return date && { raw, date };
3569
+ }
3455
3570
  var MS_PER_DAY = 864e5;
3456
3571
  function daysRemainingFrom(date, now) {
3457
3572
  return Math.ceil((date.getTime() - now.getTime()) / MS_PER_DAY);
@@ -3459,32 +3574,29 @@ function daysRemainingFrom(date, now) {
3459
3574
  function computeExpiringEntries(contracts, expiringWithinDays, now) {
3460
3575
  const entries = [];
3461
3576
  for (const contract of contracts) {
3462
- if (contract.expiresAt) {
3463
- const date = parseIsoDate(contract.expiresAt);
3464
- if (date) {
3465
- const daysRemaining = daysRemainingFrom(date, now);
3466
- if (daysRemaining <= expiringWithinDays) {
3467
- entries.push({
3468
- file: contract.file,
3469
- exportName: contract.exportName,
3470
- key: void 0,
3471
- expiresAt: contract.expiresAt,
3472
- daysRemaining
3473
- });
3474
- }
3577
+ const contractExpiry = parseExpiry(contract.expiresAt);
3578
+ if (contractExpiry) {
3579
+ const daysRemaining = daysRemainingFrom(contractExpiry.date, now);
3580
+ if (daysRemaining <= expiringWithinDays) {
3581
+ entries.push({
3582
+ file: contract.file,
3583
+ exportName: contract.exportName,
3584
+ key: void 0,
3585
+ expiresAt: contractExpiry.raw,
3586
+ daysRemaining
3587
+ });
3475
3588
  }
3476
3589
  }
3477
3590
  for (const variable of contract.variables) {
3478
- if (!variable.expiresAt) continue;
3479
- const date = parseIsoDate(variable.expiresAt);
3480
- if (!date) continue;
3481
- const daysRemaining = daysRemainingFrom(date, now);
3591
+ const expiry = parseExpiry(variable.expiresAt);
3592
+ if (!expiry) continue;
3593
+ const daysRemaining = daysRemainingFrom(expiry.date, now);
3482
3594
  if (daysRemaining <= expiringWithinDays) {
3483
3595
  entries.push({
3484
3596
  file: contract.file,
3485
3597
  exportName: contract.exportName,
3486
3598
  key: variable.key,
3487
- expiresAt: variable.expiresAt,
3599
+ expiresAt: expiry.raw,
3488
3600
  daysRemaining
3489
3601
  });
3490
3602
  }
@@ -3535,7 +3647,7 @@ function buildCatalog(contracts) {
3535
3647
  function extractPreviouslyDocumentedKeys(previousContent) {
3536
3648
  const keys = /* @__PURE__ */ new Set();
3537
3649
  for (const match of previousContent.matchAll(/^### `([A-Za-z_][A-Za-z0-9_]*)`$/gm)) {
3538
- if (match[1]) keys.add(match[1]);
3650
+ keys.add(String(match[1]));
3539
3651
  }
3540
3652
  return keys;
3541
3653
  }
@@ -3575,7 +3687,7 @@ function computeChangeSummary(contracts, previousContent) {
3575
3687
  };
3576
3688
  }
3577
3689
  function slugify(text) {
3578
- return text.toLowerCase().replace(/[^a-z0-9_]+/g, "-").replace(/^-+|-+$/g, "") || "section";
3690
+ return text.toLowerCase().replace(/[^a-z0-9_]+/g, "-").replace(/^-|-$/g, "") || "section";
3579
3691
  }
3580
3692
  var AnchorRegistry = class {
3581
3693
  constructor() {
@@ -3592,16 +3704,24 @@ var AnchorRegistry = class {
3592
3704
  this.assigned.set(target, anchor);
3593
3705
  return anchor;
3594
3706
  }
3707
+ /** The anchor an earlier {@link anchorFor} call assigned to `target`; throws if there was none. */
3708
+ anchorOf(target) {
3709
+ return mustGet(this.assigned, target);
3710
+ }
3595
3711
  };
3596
3712
  function mdLink(text, anchor) {
3597
3713
  return `[${text}](#${anchor})`;
3598
3714
  }
3715
+ function sortedByKey(items) {
3716
+ const byKey = new Map(items.map((item) => [item.key, item]));
3717
+ return [...byKey.keys()].sort().map((key) => mustGet(byKey, key));
3718
+ }
3599
3719
  function sortedContracts(contracts) {
3600
3720
  return [...contracts].sort((a, b) => a.contractName.localeCompare(b.contractName));
3601
3721
  }
3602
3722
  function renderHeader(contracts, options, anchors, hasOwnership, hasDuplicates, hasLifecycle) {
3603
3723
  const lines = [
3604
- generatedBanner("markdown"),
3724
+ generatedBanner("markdown", reportRegenerateHint()),
3605
3725
  "",
3606
3726
  `> ${evidenceDisclaimer()}`,
3607
3727
  "",
@@ -3609,7 +3729,7 @@ function renderHeader(contracts, options, anchors, hasOwnership, hasDuplicates,
3609
3729
  "",
3610
3730
  "# Environment Variables",
3611
3731
  "",
3612
- "_Produced by `env-cap --docs`._",
3732
+ "_Produced by `generateDocumentation()` from `@maverickcer/env-cap/build`._",
3613
3733
  "",
3614
3734
  `_Generated ${options.generatedAt.toISOString()}_`,
3615
3735
  ""
@@ -3652,7 +3772,7 @@ function renderCatalog(contracts, anchors, undocumented) {
3652
3772
  );
3653
3773
  }
3654
3774
  for (const contract of sortedContracts(contracts)) {
3655
- lines.push(`<a id="${anchors.anchorFor(contract, `contract-${contract.contractName}`)}"></a>`);
3775
+ lines.push(`<a id="${anchors.anchorOf(contract)}"></a>`);
3656
3776
  lines.push(`## ${contract.contractName}`, "", `Source: \`${contract.file}\``);
3657
3777
  if (undocumentedByIdentity.has(`${contract.file}#${contract.exportName}`)) {
3658
3778
  lines.push("", "> \u26A0\uFE0F **Undocumented.** No `documentEnv()` call is linked to this contract.");
@@ -3677,10 +3797,8 @@ function renderCatalog(contracts, anchors, undocumented) {
3677
3797
  }
3678
3798
  }
3679
3799
  lines.push("");
3680
- for (const variable of [...contract.variables].sort((a, b) => a.key < b.key ? -1 : 1)) {
3681
- lines.push(
3682
- `<a id="${anchors.anchorFor(variable, `${contract.contractName}-${variable.key}`)}"></a>`
3683
- );
3800
+ for (const variable of sortedByKey(contract.variables)) {
3801
+ lines.push(`<a id="${anchors.anchorOf(variable)}"></a>`);
3684
3802
  lines.push(`### \`${variable.key}\``, "");
3685
3803
  if (variable.description) lines.push(variable.description, "");
3686
3804
  if (!variable.documented) lines.push("> \u26A0\uFE0F **Undocumented.**", "");
@@ -3793,18 +3911,17 @@ function renderLifecycleReport(contracts, anchors, expiringWithinDays, now) {
3793
3911
  const owner = effectiveOwner(contract, variable);
3794
3912
  if (variable.expiresAt === void 0 && owner === void 0 && variable.refreshInstructions === void 0)
3795
3913
  continue;
3796
- const expiresAt = variable.expiresAt;
3797
- const expiry = expiresAt ? parseIsoDate(expiresAt) : void 0;
3798
- let expiresCell = expiresAt ?? "--";
3799
- if (expiry && expiresAt) {
3800
- const daysRemaining = daysRemainingFrom(expiry, now);
3914
+ const expiry = parseExpiry(variable.expiresAt);
3915
+ let expiresCell = variable.expiresAt ?? "--";
3916
+ if (expiry) {
3917
+ const daysRemaining = daysRemainingFrom(expiry.date, now);
3801
3918
  if (daysRemaining < 0)
3802
- expiresCell = `${expiresAt} (**expired ${Math.abs(daysRemaining)}d ago**)`;
3919
+ expiresCell = `${expiry.raw} (**expired ${Math.abs(daysRemaining)}d ago**)`;
3803
3920
  else if (daysRemaining <= expiringWithinDays)
3804
- expiresCell = `${expiresAt} (**${daysRemaining}d remaining**)`;
3921
+ expiresCell = `${expiry.raw} (**${daysRemaining}d remaining**)`;
3805
3922
  }
3806
3923
  rows.push(
3807
- `| ${mdLink(`\`${variable.key}\``, anchors.anchorFor(variable, `${contract.contractName}-${variable.key}`))} | ${owner ?? "--"} | ${expiresCell} | ${variable.refreshInstructions ?? "--"} |`
3924
+ `| ${mdLink(`\`${variable.key}\``, anchors.anchorOf(variable))} | ${owner ?? "--"} | ${expiresCell} | ${variable.refreshInstructions ?? "--"} |`
3808
3925
  );
3809
3926
  }
3810
3927
  }
@@ -3920,7 +4037,14 @@ function renderDocs(contracts, options) {
3920
4037
  );
3921
4038
  const catalog = renderCatalog(sorted, anchors, options.undocumentedContracts);
3922
4039
  const security = renderSecurityReview(sorted, options, options.generatedAt);
3923
- return [...header, ...catalog, ...ownership, ...dependencyLines, ...lifecycleLines, ...security].join("\n").replace(/\n{3,}/g, "\n\n");
4040
+ return [
4041
+ ...header,
4042
+ ...catalog,
4043
+ ...ownership,
4044
+ ...dependencyLines,
4045
+ ...lifecycleLines,
4046
+ ...security
4047
+ ].join("\n");
3924
4048
  }
3925
4049
  function normalizeDocsForComparison(content) {
3926
4050
  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");
@@ -3962,9 +4086,9 @@ function groupByKey(contracts) {
3962
4086
  const byKey = /* @__PURE__ */ new Map();
3963
4087
  for (const contract of contracts) {
3964
4088
  for (const variable of contract.variables) {
3965
- const list = byKey.get(variable.key) ?? [];
3966
- list.push({ contract, variable });
3967
- byKey.set(variable.key, list);
4089
+ const existing = byKey.get(variable.key);
4090
+ if (existing === void 0) byKey.set(variable.key, [{ contract, variable }]);
4091
+ else existing.push({ contract, variable });
3968
4092
  }
3969
4093
  }
3970
4094
  return byKey;
@@ -3972,7 +4096,6 @@ function groupByKey(contracts) {
3972
4096
  function renderEnvExample(contracts, reconciliationHeader = []) {
3973
4097
  const sorted = [...contracts].sort((a, b) => a.file.localeCompare(b.file));
3974
4098
  const active = sorted.filter((c) => c.active);
3975
- const inactive = sorted.filter((c) => !c.active);
3976
4099
  const lines = [
3977
4100
  "# AUTO-GENERATED EXAMPLE FILE.",
3978
4101
  "# Copy to .env and fill in real values. Do not commit .env."
@@ -3984,12 +4107,11 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
3984
4107
  "# still written to this file regardless of its context."
3985
4108
  );
3986
4109
  }
3987
- if (reconciliationHeader.length > 0) lines.push(...reconciliationHeader);
4110
+ lines.push(...reconciliationHeader);
3988
4111
  lines.push("");
3989
4112
  const activeByKey = groupByKey(active);
3990
4113
  for (const key of [...activeByKey.keys()].sort()) {
3991
4114
  const [first, ...rest] = mustGet(activeByKey, key);
3992
- if (first === void 0) continue;
3993
4115
  lines.push(...renderVariableLines(first.variable));
3994
4116
  for (const dup of rest) {
3995
4117
  lines.push(
@@ -4000,11 +4122,10 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
4000
4122
  );
4001
4123
  }
4002
4124
  }
4003
- const inactiveByKey = groupByKey(inactive);
4125
+ const inactiveByKey = groupByKey(sorted);
4004
4126
  for (const key of [...inactiveByKey.keys()].sort()) {
4005
4127
  if (activeByKey.has(key)) continue;
4006
4128
  const [first] = mustGet(inactiveByKey, key);
4007
- if (first === void 0) continue;
4008
4129
  lines.push(
4009
4130
  ...renderVariableLines(first.variable, {
4010
4131
  commented: true,
@@ -4012,13 +4133,12 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
4012
4133
  })
4013
4134
  );
4014
4135
  }
4015
- return lines.join("\n").replace(/\n+$/, "\n");
4136
+ return lines.join("\n");
4016
4137
  }
4017
4138
  function extractDeclaredVariables(source) {
4018
4139
  const names = [];
4019
4140
  for (const line of source.split("\n")) {
4020
4141
  const trimmed = line.trim();
4021
- if (!trimmed || trimmed.startsWith("#")) continue;
4022
4142
  const match = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(trimmed);
4023
4143
  if (match?.[1]) names.push(match[1]);
4024
4144
  }
@@ -4028,9 +4148,7 @@ function extractCommentedVariables(source) {
4028
4148
  const names = [];
4029
4149
  for (const line of source.split("\n")) {
4030
4150
  const trimmed = line.trim();
4031
- if (!trimmed.startsWith("#")) continue;
4032
- const withoutHash = trimmed.replace(/^#+\s*/, "");
4033
- const match = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(withoutHash);
4151
+ const match = /^#+\s*([A-Za-z_][A-Za-z0-9_]*)=/.exec(trimmed);
4034
4152
  if (match?.[1]) names.push(match[1]);
4035
4153
  }
4036
4154
  return names;
@@ -4112,7 +4230,7 @@ function collectVariableNames(contracts) {
4112
4230
  }
4113
4231
  function overrideVariable(variable, overrides) {
4114
4232
  const override = overrides[variable.key];
4115
- const date = override === void 0 ? void 0 : parseIsoDate(override);
4233
+ const date = parseIsoDate(String(override));
4116
4234
  return {
4117
4235
  ...variable,
4118
4236
  expiresAt: date ? override : variable.expiresAt,
@@ -4134,16 +4252,14 @@ async function resolveLiveExpirationDates(contracts, liveExpirationDates) {
4134
4252
 
4135
4253
  // src/build/generate-documentation.ts
4136
4254
  var DEFAULT_EXPIRING_WITHIN_DAYS = 30;
4137
- var STANDARD_SENSITIVITY_LEVELS = /* @__PURE__ */ new Set([
4138
- "secret",
4139
- "credential",
4140
- "pii",
4141
- "config"
4142
- ]);
4255
+ function standardSensitivityLevels() {
4256
+ return ["secret", "credential", "pii", "config"];
4257
+ }
4258
+ var STANDARD_SENSITIVITY_LEVELS = new Set(standardSensitivityLevels());
4143
4259
  function findNonstandardSensitivityLevels(contracts) {
4144
4260
  const entries = [];
4145
4261
  for (const contract of contracts) {
4146
- if (contract.sensitivity !== void 0 && !STANDARD_SENSITIVITY_LEVELS.has(contract.sensitivity))
4262
+ if (contract.sensitivity !== void 0 && !standardSensitivityLevels().includes(contract.sensitivity))
4147
4263
  entries.push({
4148
4264
  file: contract.file,
4149
4265
  exportName: contract.exportName,
@@ -4152,7 +4268,7 @@ function findNonstandardSensitivityLevels(contracts) {
4152
4268
  });
4153
4269
  for (const variable of [...contract.variables].sort((a, b) => a.key.localeCompare(b.key))) {
4154
4270
  if (variable.sensitivity === void 0) continue;
4155
- if (STANDARD_SENSITIVITY_LEVELS.has(variable.sensitivity)) continue;
4271
+ if (standardSensitivityLevels().includes(variable.sensitivity)) continue;
4156
4272
  entries.push({
4157
4273
  file: contract.file,
4158
4274
  exportName: contract.exportName,
@@ -4193,36 +4309,20 @@ async function writeDocumentation(docsPath, envExamplePath, root, contracts, con
4193
4309
  undocumentedContracts: documentation.undocumentedContracts.map(
4194
4310
  (ref) => relativizeRef(root, ref)
4195
4311
  ),
4196
- // `RenderDocsOptions.undocumentedVariables` is consumed by `renderDocs()`
4197
- // ONLY via `.length` (the security-review counter) -- never by content
4198
- // or identity, unlike its `undocumentedContracts` sibling above (matched
4199
- // by identity against the catalog for the "Undocumented." marker).
4200
- // `.map()` always preserves length regardless of what each element
4201
- // transforms to, so this specific `relativizeRef()` call's own output is
4202
- // unobservable through this call site. Hand-verified: mapping every
4203
- // entry to `undefined` instead and running the full `vitest run` leaves
4204
- // all tests passing.
4205
- // Stryker disable next-line ArrowFunction
4206
- undocumentedVariables: documentation.undocumentedVariables.map(
4207
- (ref) => relativizeRef(root, ref)
4208
- ),
4312
+ undocumentedVariables: documentation.undocumentedVariables,
4209
4313
  generatedAt,
4210
4314
  previousContent
4211
4315
  });
4212
4316
  await fs.mkdir(path14.dirname(docsPath), { recursive: true });
4213
4317
  await fs.writeFile(docsPath, docsSource, "utf8");
4214
4318
  const envExample = envExamplePath ? (
4215
- // exactOptionalPropertyTypes: omit the key rather than set it to
4216
- // `undefined` when the caller didn't supply one. writeEnvExample
4217
- // itself does `options.onExisting ?? "keep-sibling"`, so passing
4218
- // `onExisting: undefined` explicitly (what always-spreading here
4219
- // would do) is behaviorally identical to omitting the key.
4220
- // Hand-verified: forcing this guard to `true` and running the real
4221
- // suite passes unchanged.
4222
- await writeEnvExample(contracts, envExamplePath, fs, {
4223
- // Stryker disable next-line ConditionalExpression
4224
- ...envExampleOnExisting === void 0 ? {} : { onExisting: envExampleOnExisting }
4225
- })
4319
+ // `exactOptionalPropertyTypes` rejects an explicit `undefined`, so the key is omitted when unset.
4320
+ await writeEnvExample(
4321
+ contracts,
4322
+ envExamplePath,
4323
+ fs,
4324
+ envExampleOnExisting && { onExisting: envExampleOnExisting }
4325
+ )
4226
4326
  ) : void 0;
4227
4327
  return { envExample };
4228
4328
  }
@@ -4230,7 +4330,6 @@ async function generateDocumentation(options) {
4230
4330
  const root = path14.resolve(options.root ?? process.cwd());
4231
4331
  const include = options.include ?? defaultInclude();
4232
4332
  const exclude = options.exclude ?? defaultExclude();
4233
- const packages = options.packages ?? [];
4234
4333
  const expiringWithinDays = options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS;
4235
4334
  const docsLocationResult = resolveWithinRoot(
4236
4335
  root,
@@ -4256,7 +4355,7 @@ async function generateDocumentation(options) {
4256
4355
  root,
4257
4356
  include,
4258
4357
  exclude,
4259
- packages,
4358
+ packages: options.packages,
4260
4359
  tsconfig: options.tsconfig
4261
4360
  });
4262
4361
  const docsContracts = await resolveLiveExpirationDates(
@@ -4310,7 +4409,7 @@ function parseRotationPeriodDays(value) {
4310
4409
  if (plain) {
4311
4410
  const amount = Number(plain[1]);
4312
4411
  if (amount > 0) {
4313
- const unit = (plain[2] ?? "").toLowerCase();
4412
+ const unit = String(plain[2]).toLowerCase();
4314
4413
  switch (unit) {
4315
4414
  case "day":
4316
4415
  case "days":
@@ -4343,18 +4442,14 @@ function parseRotationPeriodDays(value) {
4343
4442
  }
4344
4443
  function computeRotationStatus(variable, now) {
4345
4444
  if (!hasRotationData(variable)) return "undeclared";
4346
- if (variable.expiresAt !== void 0) {
4347
- const expiry = parseIsoDate(variable.expiresAt);
4348
- if (expiry !== void 0 && expiry.getTime() < now.getTime()) return "expired";
4349
- }
4445
+ const expiry = parseIsoDate(String(variable.expiresAt));
4446
+ if (expiry !== void 0 && expiry.getTime() < now.getTime()) return "expired";
4350
4447
  if (variable.rotationPeriod !== void 0) {
4351
- if (variable.lastRotatedAt !== void 0) {
4352
- const lastRotated = parseIsoDate(variable.lastRotatedAt);
4353
- const periodDays = parseRotationPeriodDays(variable.rotationPeriod);
4354
- if (lastRotated !== void 0 && lastRotated.getTime() <= now.getTime() && periodDays !== void 0) {
4355
- const dueDate = lastRotated.getTime() + periodDays * MS_PER_DAY2;
4356
- return dueDate < now.getTime() ? "overdue" : "compliant";
4357
- }
4448
+ const lastRotated = parseIsoDate(String(variable.lastRotatedAt));
4449
+ const periodDays = parseRotationPeriodDays(variable.rotationPeriod);
4450
+ if (lastRotated !== void 0 && lastRotated.getTime() <= now.getTime() && periodDays !== void 0) {
4451
+ const dueDate = lastRotated.getTime() + periodDays * MS_PER_DAY2;
4452
+ return dueDate < now.getTime() ? "overdue" : "compliant";
4358
4453
  }
4359
4454
  return "overdue";
4360
4455
  }
@@ -4439,7 +4534,6 @@ async function generateEvidenceModel(options) {
4439
4534
  const root = path15.resolve(options.root ?? process.cwd());
4440
4535
  const include = options.include ?? defaultInclude();
4441
4536
  const exclude = options.exclude ?? defaultExclude();
4442
- const packages = options.packages ?? [];
4443
4537
  const expiringWithinDays = options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS;
4444
4538
  let snapshotPath;
4445
4539
  if (options.previousSnapshotLocation !== void 0) {
@@ -4457,10 +4551,10 @@ async function generateEvidenceModel(options) {
4457
4551
  root,
4458
4552
  include,
4459
4553
  exclude,
4460
- packages,
4554
+ packages: options.packages,
4461
4555
  tsconfig: options.tsconfig
4462
4556
  });
4463
- const { readFileCached, linkResult, context, origins, packageWarnings, tsconfigWarnings } = assembled;
4557
+ const { readFileCached, linkResult, context, origins } = assembled;
4464
4558
  const generatedAt = /* @__PURE__ */ new Date();
4465
4559
  const activeContracts = linkResult.contracts.filter((c) => c.active);
4466
4560
  const lifecycleContracts = options.liveExpirationDates ? await resolveLiveExpirationDates(linkResult.contracts, options.liveExpirationDates) : linkResult.contracts;
@@ -4514,8 +4608,6 @@ async function generateEvidenceModel(options) {
4514
4608
  scanFiles,
4515
4609
  readFileCached,
4516
4610
  context,
4517
- // Stryker disable next-line ArrayDeclaration
4518
- [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings],
4519
4611
  scannedSurfaces,
4520
4612
  evidenceChanges?.dynamicAccessAcknowledgments
4521
4613
  );
@@ -4528,12 +4620,7 @@ async function generateEvidenceModel(options) {
4528
4620
  unresolvedConsumers: usageComputed.result.unresolvedConsumers,
4529
4621
  unconsumedOwnedVariables: usageComputed.result.unconsumedOwnedVariables,
4530
4622
  indeterminateOwnership: usageComputed.result.indeterminate,
4531
- // `buildFindingModel` (finding-model.ts) has its own `?? []` fallback
4532
- // on this exact same field, so even an `undefined` that slipped past
4533
- // this one (e.g. `??`-vs-`&&` on `evidenceChanges?.…`) is caught there
4534
- // identically -- belt-and-suspenders, not independently observable.
4535
- // Stryker disable next-line LogicalOperator
4536
- dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems ?? []
4623
+ dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems
4537
4624
  });
4538
4625
  const commit = options.commit ? await options.commit() : void 0;
4539
4626
  return deepFreeze({
@@ -4589,7 +4676,6 @@ async function getEvidenceModel(options) {
4589
4676
  const root = path16.resolve(options.root ?? process.cwd());
4590
4677
  const include = options.include ?? defaultInclude();
4591
4678
  const exclude = options.exclude ?? defaultExclude();
4592
- const packages = options.packages ?? [];
4593
4679
  const evidencePath = path16.resolve(root, options.location);
4594
4680
  const fingerprintPath = fingerprintPathFor(evidencePath);
4595
4681
  const recompute = async (missReason) => ({
@@ -4604,7 +4690,7 @@ async function getEvidenceModel(options) {
4604
4690
  root,
4605
4691
  include,
4606
4692
  exclude,
4607
- packages
4693
+ packages: options.packages
4608
4694
  });
4609
4695
  } catch (error) {
4610
4696
  return recompute(
@@ -4652,91 +4738,61 @@ function findingFiles(finding) {
4652
4738
  if (location.model === "change") return [location.path];
4653
4739
  return location.file === void 0 ? [] : [location.file];
4654
4740
  }
4741
+ function requestedPass(option) {
4742
+ return option === false ? void 0 : option;
4743
+ }
4655
4744
  async function computeArtifacts(options) {
4656
4745
  const root = path17.resolve(options.root ?? process.cwd());
4657
4746
  const include = options.include ?? defaultInclude();
4658
4747
  const exclude = options.exclude ?? defaultExclude();
4659
- const packages = options.packages ?? [];
4660
- const manifestOptions = options.manifest === false ? void 0 : options.manifest;
4661
- const docsOptions = options.docs === false ? void 0 : options.docs;
4662
- const usageOptions = options.usage === false ? void 0 : options.usage;
4663
- const evidenceOptions = options.evidence === false ? void 0 : options.evidence;
4748
+ const manifestOptions = requestedPass(options.manifest);
4749
+ const docsOptions = requestedPass(options.docs);
4750
+ const usageOptions = requestedPass(options.usage);
4751
+ const evidenceOptions = requestedPass(options.evidence);
4664
4752
  const pathIssues = [];
4665
- let manifestOutputPath;
4666
- if (manifestOptions) {
4667
- const result = resolveWithinRoot(
4668
- root,
4669
- manifestOptions.location,
4670
- "manifest.location",
4671
- "generateEnvArtifacts"
4672
- );
4673
- if (result.ok) manifestOutputPath = result.resolved;
4674
- else pathIssues.push(result.issue);
4675
- }
4676
- let docsPath;
4677
- let envExamplePath;
4678
- if (docsOptions) {
4679
- const result = resolveWithinRoot(
4680
- root,
4681
- docsOptions.location,
4682
- "docs.location",
4683
- "generateEnvArtifacts"
4684
- );
4685
- if (result.ok) docsPath = result.resolved;
4686
- else pathIssues.push(result.issue);
4687
- if (docsOptions.envExample) {
4688
- const exampleResult = resolveWithinRoot(
4689
- root,
4690
- docsOptions.envExample.location,
4691
- "docs.envExample.location",
4692
- "generateEnvArtifacts"
4693
- );
4694
- if (exampleResult.ok) envExamplePath = exampleResult.resolved;
4695
- else pathIssues.push(exampleResult.issue);
4696
- }
4697
- }
4698
- let usageReportPath;
4699
- if (usageOptions?.report) {
4700
- const result = resolveWithinRoot(
4701
- root,
4702
- usageOptions.report.location,
4703
- "usage.report.location",
4704
- "generateEnvArtifacts"
4705
- );
4706
- if (result.ok) usageReportPath = result.resolved;
4707
- else pathIssues.push(result.issue);
4708
- }
4709
- let evidencePath;
4710
- if (evidenceOptions) {
4711
- const result = resolveWithinRoot(
4712
- root,
4713
- evidenceOptions.location,
4714
- "evidence.location",
4715
- "generateEnvArtifacts"
4716
- );
4717
- if (result.ok) evidencePath = result.resolved;
4718
- else pathIssues.push(result.issue);
4719
- }
4753
+ const resolveOutput = (location, label) => {
4754
+ const result = resolveWithinRoot(root, location, label, "generateEnvArtifacts");
4755
+ if (result.ok) return result.resolved;
4756
+ pathIssues.push(result.issue);
4757
+ return location;
4758
+ };
4759
+ const manifestTarget = manifestOptions && {
4760
+ options: manifestOptions,
4761
+ outputPath: resolveOutput(manifestOptions.location, "manifest.location")
4762
+ };
4763
+ const docsTarget = docsOptions && {
4764
+ options: docsOptions,
4765
+ path: resolveOutput(docsOptions.location, "docs.location"),
4766
+ envExamplePath: docsOptions.envExample ? resolveOutput(docsOptions.envExample.location, "docs.envExample.location") : void 0
4767
+ };
4768
+ const usageTarget = usageOptions && {
4769
+ options: usageOptions,
4770
+ reportPath: usageOptions.report ? resolveOutput(usageOptions.report.location, "usage.report.location") : void 0
4771
+ };
4772
+ const evidencePath = evidenceOptions ? resolveOutput(evidenceOptions.location, "evidence.location") : void 0;
4720
4773
  if (pathIssues.length > 0) throw new EnvProjectGenerationError(pathIssues);
4721
4774
  const { readFileCached, linkResult, context, origins, packageWarnings, tsconfigWarnings } = await assembleProject({
4722
4775
  fs: options.fs,
4723
4776
  root,
4724
4777
  include,
4725
4778
  exclude,
4726
- packages,
4779
+ packages: options.packages,
4727
4780
  tsconfig: options.tsconfig
4728
4781
  });
4729
4782
  const generatedAt = /* @__PURE__ */ new Date();
4730
4783
  const activeContracts = linkResult.contracts.filter((c) => c.active);
4731
4784
  const liveExpirationContracts = options.liveExpirationDates ? await resolveLiveExpirationDates(linkResult.contracts, options.liveExpirationDates) : linkResult.contracts;
4732
- const docsContracts = docsOptions ? liveExpirationContracts : linkResult.contracts;
4785
+ const docsContracts = docsTarget ? liveExpirationContracts : linkResult.contracts;
4733
4786
  const blocking = [];
4734
- const manifestComputed = manifestOptions ? computeManifest(root, linkResult, manifestOptions.onIncompatibility ?? "warn") : void 0;
4735
- if (manifestComputed) blocking.push(...manifestComputed.blocking);
4787
+ const manifest = manifestTarget && {
4788
+ ...manifestTarget,
4789
+ computed: computeManifest(root, linkResult, manifestTarget.options.onIncompatibility)
4790
+ };
4791
+ if (manifest) blocking.push(...manifest.computed.blocking);
4736
4792
  const docsComputed = computeDocumentation(
4737
4793
  root,
4738
4794
  { ...linkResult, contracts: liveExpirationContracts },
4739
- docsOptions?.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4795
+ docsTarget?.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4740
4796
  generatedAt
4741
4797
  );
4742
4798
  const { scanFiles, scannedSurfaces } = await computeScanSurface(
@@ -4760,14 +4816,13 @@ async function computeArtifacts(options) {
4760
4816
  scanFiles,
4761
4817
  readFileCached,
4762
4818
  context,
4763
- [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings],
4764
4819
  scannedSurfaces,
4765
4820
  evidenceChanges?.dynamicAccessAcknowledgments
4766
4821
  );
4767
4822
  const ownership = buildOwnershipModel(linkResult.contracts, root);
4768
4823
  const lifecycle = buildLifecycleModel(
4769
4824
  liveExpirationContracts,
4770
- docsOptions?.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4825
+ docsTarget?.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4771
4826
  generatedAt,
4772
4827
  root
4773
4828
  );
@@ -4804,7 +4859,7 @@ async function computeArtifacts(options) {
4804
4859
  unresolvedConsumers: usageComputed.result.unresolvedConsumers,
4805
4860
  unconsumedOwnedVariables: usageComputed.result.unconsumedOwnedVariables,
4806
4861
  indeterminateOwnership: usageComputed.result.indeterminate,
4807
- dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems ?? []
4862
+ dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems
4808
4863
  });
4809
4864
  if (options.onUndocumented === "throw")
4810
4865
  blocking.push(...escalatedFindings(finding.findings, "documentation"));
@@ -4826,16 +4881,11 @@ async function computeArtifacts(options) {
4826
4881
  });
4827
4882
  return {
4828
4883
  root,
4829
- manifestOptions,
4830
- manifestOutputPath,
4831
- manifestComputed,
4832
- docsOptions,
4833
- docsPath,
4834
- envExamplePath,
4884
+ manifest,
4885
+ docs: docsTarget,
4835
4886
  docsComputed,
4836
4887
  docsContracts,
4837
- usageOptions,
4838
- usageReportPath,
4888
+ usage: usageTarget,
4839
4889
  usageComputed,
4840
4890
  evidencePath,
4841
4891
  evidence,
@@ -4848,16 +4898,11 @@ async function computeArtifacts(options) {
4848
4898
  async function generateEnvArtifacts(options) {
4849
4899
  const computed = await computeArtifacts(options);
4850
4900
  const {
4851
- manifestOptions,
4852
- manifestOutputPath,
4853
- manifestComputed,
4854
- docsOptions,
4855
- docsPath,
4856
- envExamplePath,
4901
+ manifest,
4902
+ docs,
4857
4903
  docsComputed,
4858
4904
  docsContracts,
4859
- usageOptions,
4860
- usageReportPath,
4905
+ usage,
4861
4906
  usageComputed,
4862
4907
  evidencePath,
4863
4908
  evidence,
@@ -4868,43 +4913,47 @@ async function generateEnvArtifacts(options) {
4868
4913
  generatedAt
4869
4914
  } = computed;
4870
4915
  if (blocking.length > 0) throw new EnvProjectGenerationError(blocking);
4916
+ const parseWarnings = [...packageWarnings, ...linkWarnings];
4871
4917
  let manifestResult;
4872
- if (manifestOptions && manifestComputed && manifestOutputPath) {
4873
- await writeManifest(manifestOutputPath, manifestComputed.activeContracts, options.fs);
4918
+ if (manifest) {
4919
+ await writeManifest(manifest.outputPath, manifest.computed.activeContracts, options.fs);
4874
4920
  manifestResult = {
4875
- outputPath: manifestOutputPath,
4876
- contracts: manifestComputed.contractSummaries,
4877
- warnings: manifestComputed.warnings,
4878
- parseWarnings: [...packageWarnings, ...linkWarnings]
4921
+ outputPath: manifest.outputPath,
4922
+ contracts: manifest.computed.contractSummaries,
4923
+ warnings: manifest.computed.warnings,
4924
+ parseWarnings
4879
4925
  };
4880
4926
  }
4881
4927
  let docsResult;
4882
- if (docsOptions && docsPath) {
4928
+ if (docs) {
4883
4929
  const { envExample } = await writeDocumentation(
4884
- docsPath,
4885
- envExamplePath,
4930
+ docs.path,
4931
+ docs.envExamplePath,
4886
4932
  root,
4887
4933
  docsContracts,
4888
4934
  docsComputed.contractModelContracts,
4889
4935
  docsComputed.documentation,
4890
- docsOptions.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4936
+ docs.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4891
4937
  generatedAt,
4892
4938
  options.fs,
4893
- docsOptions.envExample?.onExisting
4939
+ docs.options.envExample?.onExisting
4894
4940
  );
4895
4941
  docsResult = {
4896
- docsPath,
4942
+ docsPath: docs.path,
4897
4943
  envExample,
4898
4944
  contracts: docsComputed.contractSummaries,
4899
4945
  catalog: docsComputed.catalog,
4900
- parseWarnings: [...packageWarnings, ...linkWarnings],
4946
+ parseWarnings,
4901
4947
  documentation: docsComputed.documentation
4902
4948
  };
4903
4949
  }
4904
4950
  let usageResult;
4905
- if (usageOptions) {
4906
- if (usageReportPath) await writeUsageReport(usageReportPath, usageComputed.result, options.fs);
4907
- usageResult = { reportPath: usageReportPath, ...usageComputed.result };
4951
+ if (usage) {
4952
+ const usageReport = { ...usageComputed.result, parseWarnings };
4953
+ if (usage.reportPath !== void 0) {
4954
+ await writeUsageReport(usage.reportPath, usageReport, options.fs);
4955
+ }
4956
+ usageResult = { reportPath: usage.reportPath, ...usageReport };
4908
4957
  }
4909
4958
  if (evidencePath) {
4910
4959
  await writeEvidenceSnapshot(evidencePath, evidence, options.fs);
@@ -4913,7 +4962,7 @@ async function generateEnvArtifacts(options) {
4913
4962
  root,
4914
4963
  include: options.include ?? defaultInclude(),
4915
4964
  exclude: options.exclude ?? defaultExclude(),
4916
- packages: options.packages ?? []
4965
+ packages: options.packages
4917
4966
  });
4918
4967
  await writeEvidenceFingerprint(evidencePath, fingerprint, options.fs);
4919
4968
  }
@@ -4921,12 +4970,8 @@ async function generateEnvArtifacts(options) {
4921
4970
  }
4922
4971
 
4923
4972
  // src/build/check-artifacts.ts
4924
- async function readIfExists(filePath, fs) {
4925
- try {
4926
- return await fs.readFile(filePath, "utf8");
4927
- } catch {
4928
- return void 0;
4929
- }
4973
+ function readIfExists(filePath, fs) {
4974
+ return fs.readFile(filePath, "utf8").catch(() => void 0);
4930
4975
  }
4931
4976
  function normalizeEvidenceJsonForComparison(text) {
4932
4977
  try {
@@ -4952,46 +4997,38 @@ async function checkEnvArtifacts(options) {
4952
4997
  const c = await computeArtifacts(options);
4953
4998
  if (c.blocking.length > 0) throw new EnvProjectGenerationError(c.blocking);
4954
4999
  const findings = [];
4955
- if (c.manifestOptions && c.manifestComputed && c.manifestOutputPath) {
4956
- const expected = renderManifest(c.manifestComputed.activeContracts, c.manifestOutputPath);
4957
- findings.push(await compareTextArtifact("manifest", c.manifestOutputPath, expected, options.fs));
5000
+ if (c.manifest) {
5001
+ const expected = renderManifest(c.manifest.computed.activeContracts, c.manifest.outputPath);
5002
+ findings.push(
5003
+ await compareTextArtifact("manifest", c.manifest.outputPath, expected, options.fs)
5004
+ );
4958
5005
  }
4959
- if (c.docsOptions && c.docsPath) {
4960
- const previousContent = await readIfExists(c.docsPath, options.fs);
5006
+ if (c.docs) {
5007
+ const previousContent = await readIfExists(c.docs.path, options.fs);
4961
5008
  const expected = renderDocs(c.docsComputed.contractModelContracts, {
4962
- expiringWithinDays: c.docsOptions.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
5009
+ expiringWithinDays: c.docs.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4963
5010
  undocumentedContracts: c.docsComputed.documentation.undocumentedContracts.map(
4964
5011
  (ref) => relativizeRef(c.root, ref)
4965
5012
  ),
4966
- // `RenderDocsOptions.undocumentedVariables` is consumed by `renderDocs()`
4967
- // ONLY via `.length` (the security-review counter), never by content
4968
- // or identity -- same equivalence already established for
4969
- // `generate-documentation.ts`'s identical call site. Hand-verified:
4970
- // mapping every entry to `undefined` instead and running the full
4971
- // `vitest run` leaves every test passing.
4972
- // Stryker disable ArrowFunction
4973
- undocumentedVariables: c.docsComputed.documentation.undocumentedVariables.map(
4974
- (ref) => relativizeRef(c.root, ref)
4975
- ),
4976
- // Stryker restore ArrowFunction
5013
+ undocumentedVariables: c.docsComputed.documentation.undocumentedVariables,
4977
5014
  generatedAt: c.generatedAt,
4978
5015
  previousContent
4979
5016
  });
4980
5017
  findings.push(
4981
5018
  await compareTextArtifact(
4982
5019
  "docs",
4983
- c.docsPath,
5020
+ c.docs.path,
4984
5021
  expected,
4985
5022
  options.fs,
4986
5023
  normalizeDocsForComparison
4987
5024
  )
4988
5025
  );
4989
- if (c.docsOptions.envExample && c.envExamplePath) {
4990
- const existing = await readIfExists(c.envExamplePath, options.fs);
5026
+ if (c.docs.envExamplePath !== void 0) {
5027
+ const existing = await readIfExists(c.docs.envExamplePath, options.fs);
4991
5028
  if (existing === void 0) {
4992
5029
  findings.push({
4993
5030
  artifact: "envExample",
4994
- path: c.envExamplePath,
5031
+ path: c.docs.envExamplePath,
4995
5032
  status: "missing",
4996
5033
  detail: "not yet generated"
4997
5034
  });
@@ -5003,7 +5040,7 @@ async function checkEnvArtifacts(options) {
5003
5040
  const driftCount = staleVariables.length + variablesToComment.length + variablesToAdd.length;
5004
5041
  findings.push({
5005
5042
  artifact: "envExample",
5006
- path: c.envExamplePath,
5043
+ path: c.docs.envExamplePath,
5007
5044
  status: driftCount > 0 ? "stale" : "ok",
5008
5045
  // exactOptionalPropertyTypes: omit the key entirely rather than
5009
5046
  // set it to `undefined` -- `detail` is absent when there's
@@ -5015,9 +5052,12 @@ async function checkEnvArtifacts(options) {
5015
5052
  }
5016
5053
  }
5017
5054
  }
5018
- if (c.usageOptions && c.usageReportPath) {
5019
- const expected = renderUsageReport(c.usageComputed.result);
5020
- findings.push(await compareTextArtifact("usage", c.usageReportPath, expected, options.fs));
5055
+ if (c.usage?.reportPath !== void 0) {
5056
+ const expected = renderUsageReport({
5057
+ ...c.usageComputed.result,
5058
+ parseWarnings: [...c.packageWarnings, ...c.linkWarnings]
5059
+ });
5060
+ findings.push(await compareTextArtifact("usage", c.usage.reportPath, expected, options.fs));
5021
5061
  }
5022
5062
  if (c.evidencePath) {
5023
5063
  const expected = JSON.stringify(c.evidence, null, 2);
@@ -5042,7 +5082,7 @@ function sarifLocations(finding) {
5042
5082
  const location = finding.location;
5043
5083
  const uri = location.model === "change" ? location.path : location.file;
5044
5084
  if (uri === void 0) return void 0;
5045
- const position = location.model === "change" ? void 0 : location.position;
5085
+ const { position } = location;
5046
5086
  return [
5047
5087
  {
5048
5088
  physicalLocation: {
@@ -5145,4 +5185,4 @@ export {
5145
5185
  resolveRelativeImport,
5146
5186
  writeEnvExample
5147
5187
  };
5148
- //# sourceMappingURL=build-U326PI5A.js.map
5188
+ //# sourceMappingURL=build-WKDIAWF7.js.map