@maverickcer/env-cap 0.5.3 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (359) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +438 -0
  4. package/CODE_OF_CONDUCT.md +124 -0
  5. package/CODE_REVIEW.md +200 -0
  6. package/CONTRIBUTING.md +131 -0
  7. package/GUIDE.md +1214 -0
  8. package/PROMPT.md +89 -0
  9. package/README.md +97 -199
  10. package/RELEASING.md +160 -0
  11. package/SECURITY.md +270 -0
  12. package/SUPPORT.md +76 -0
  13. package/VERSIONING.md +118 -0
  14. package/benchmarks/READING-BENCHMARKS.md +197 -0
  15. package/benchmarks/README.md +126 -0
  16. package/benchmarks/WRITING-BENCHMARKS.md +252 -0
  17. package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
  18. package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
  19. package/dist/.dts/_ipc/build-fs.d.ts +53 -0
  20. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
  21. package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
  22. package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
  23. package/dist/.dts/_ipc/display-path.d.ts +27 -0
  24. package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
  25. package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
  26. package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
  27. package/dist/.dts/_ipc/glob.d.ts +22 -0
  28. package/dist/.dts/_ipc/glob.d.ts.map +1 -0
  29. package/dist/.dts/_ipc/no-node-fs.d.ts +34 -0
  30. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
  31. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  32. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  33. package/dist/.dts/_ipc/typescript.d.ts +20 -0
  34. package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
  35. package/dist/.dts/build/assemble-project.d.ts +1 -1
  36. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  37. package/dist/.dts/build/change-model.d.ts.map +1 -1
  38. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  39. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  40. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  41. package/dist/.dts/build/compiler-api.d.ts +12 -0
  42. package/dist/.dts/build/compiler-api.d.ts.map +1 -0
  43. package/dist/.dts/build/dependency-graph.d.ts +3 -1
  44. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  45. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  46. package/dist/.dts/build/discover.d.ts.map +1 -1
  47. package/dist/.dts/build/display-path.d.ts +3 -21
  48. package/dist/.dts/build/display-path.d.ts.map +1 -1
  49. package/dist/.dts/build/docs.d.ts +1 -1
  50. package/dist/.dts/build/docs.d.ts.map +1 -1
  51. package/dist/.dts/build/env-example.d.ts.map +1 -1
  52. package/dist/.dts/build/evidence-cache.d.ts +1 -1
  53. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  54. package/dist/.dts/build/evidence-model.d.ts +2 -2
  55. package/dist/.dts/build/evidence-snapshot.d.ts +25 -0
  56. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  57. package/dist/.dts/build/finding-model.d.ts +1 -1
  58. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  59. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  60. package/dist/.dts/build/generate-env-artifacts.d.ts +23 -8
  61. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  62. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  63. package/dist/.dts/build/generate-manifest.d.ts +1 -1
  64. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  65. package/dist/.dts/build/generate-usage.d.ts +3 -3
  66. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  67. package/dist/.dts/build/generated-banner.d.ts +29 -38
  68. package/dist/.dts/build/generated-banner.d.ts.map +1 -1
  69. package/dist/.dts/build/glob.d.ts +3 -15
  70. package/dist/.dts/build/glob.d.ts.map +1 -1
  71. package/dist/.dts/build/index.d.ts +2 -2
  72. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  73. package/dist/.dts/build/link.d.ts.map +1 -1
  74. package/dist/.dts/build/literal-eval.d.ts +4 -3
  75. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  76. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  77. package/dist/.dts/build/manifest.d.ts.map +1 -1
  78. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  79. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  80. package/dist/.dts/build/parse.d.ts +12 -12
  81. package/dist/.dts/build/parse.d.ts.map +1 -1
  82. package/dist/.dts/build/reference-projections.d.ts +17 -3
  83. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  84. package/dist/.dts/build/resolution/resolve-import.d.ts +5 -0
  85. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  86. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +1 -1
  87. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  88. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -94
  89. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  90. package/dist/.dts/build/sarif.d.ts.map +1 -1
  91. package/dist/.dts/build/scan-dependencies.d.ts +23 -0
  92. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  93. package/dist/.dts/build/types.d.ts +4 -53
  94. package/dist/.dts/build/types.d.ts.map +1 -1
  95. package/dist/.dts/build/typescript.d.ts +6 -0
  96. package/dist/.dts/build/typescript.d.ts.map +1 -0
  97. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  98. package/dist/.dts/cli/filesystem.d.ts +4 -0
  99. package/dist/.dts/cli/filesystem.d.ts.map +1 -1
  100. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  101. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  102. package/dist/.dts/eslint-plugin/index.d.ts +3 -3
  103. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  104. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  105. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  106. package/dist/.dts/evidence/index.d.ts +2 -2
  107. package/dist/.dts/helpers/index.d.ts +2 -2
  108. package/dist/.dts/helpers/processors.d.ts.map +1 -1
  109. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  110. package/dist/.dts/runtime/cache.d.ts +0 -3
  111. package/dist/.dts/runtime/cache.d.ts.map +1 -1
  112. package/dist/.dts/runtime/create.d.ts.map +1 -1
  113. package/dist/.dts/runtime/document.d.ts.map +1 -1
  114. package/dist/.dts/runtime/index.d.ts +2 -2
  115. package/dist/.dts/runtime/registry.d.ts.map +1 -1
  116. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  117. package/dist/{build-U326PI5A.js → build-WKDIAWF7.js} +685 -645
  118. package/dist/build-WKDIAWF7.js.map +1 -0
  119. package/dist/build.cjs +698 -651
  120. package/dist/build.cjs.map +1 -1
  121. package/dist/build.js +695 -649
  122. package/dist/build.js.map +1 -1
  123. package/dist/{chunk-BSTLSR2R.js → chunk-KEGYUHBU.js} +2 -2
  124. package/dist/chunk-KEGYUHBU.js.map +1 -0
  125. package/dist/cli/index.js +64 -63
  126. package/dist/cli/index.js.map +1 -1
  127. package/dist/eslint-plugin/index.cjs +95 -626
  128. package/dist/eslint-plugin/index.cjs.map +1 -1
  129. package/dist/eslint-plugin/index.js +94 -625
  130. package/dist/eslint-plugin/index.js.map +1 -1
  131. package/dist/evidence.cjs.map +1 -1
  132. package/dist/evidence.js.map +1 -1
  133. package/dist/helpers.cjs +4 -9
  134. package/dist/helpers.cjs.map +1 -1
  135. package/dist/helpers.js +4 -9
  136. package/dist/helpers.js.map +1 -1
  137. package/dist/index.cjs +11 -25
  138. package/dist/index.cjs.map +1 -1
  139. package/dist/index.js +11 -25
  140. package/dist/index.js.map +1 -1
  141. package/dist/node.cjs +10 -8
  142. package/dist/node.cjs.map +1 -1
  143. package/dist/node.js +10 -8
  144. package/dist/node.js.map +1 -1
  145. package/examples/README.md +95 -0
  146. package/node_modules/@typescript/old/LICENSE.txt +55 -0
  147. package/node_modules/@typescript/old/README.md +50 -0
  148. package/node_modules/@typescript/old/SECURITY.md +39 -0
  149. package/node_modules/@typescript/old/ThirdPartyNoticeText.txt +193 -0
  150. package/node_modules/@typescript/old/bin/tsc +2 -0
  151. package/node_modules/@typescript/old/bin/tsserver +2 -0
  152. package/node_modules/@typescript/old/lib/_tsc.js +134465 -0
  153. package/node_modules/@typescript/old/lib/_tsserver.js +659 -0
  154. package/node_modules/@typescript/old/lib/_typingsInstaller.js +222 -0
  155. package/node_modules/@typescript/old/lib/cs/diagnosticMessages.generated.json +2129 -0
  156. package/node_modules/@typescript/old/lib/de/diagnosticMessages.generated.json +2125 -0
  157. package/node_modules/@typescript/old/lib/es/diagnosticMessages.generated.json +2129 -0
  158. package/node_modules/@typescript/old/lib/fr/diagnosticMessages.generated.json +2129 -0
  159. package/node_modules/@typescript/old/lib/it/diagnosticMessages.generated.json +2125 -0
  160. package/node_modules/@typescript/old/lib/ja/diagnosticMessages.generated.json +2129 -0
  161. package/node_modules/@typescript/old/lib/ko/diagnosticMessages.generated.json +2129 -0
  162. package/node_modules/@typescript/old/lib/lib.d.ts +20 -0
  163. package/node_modules/@typescript/old/lib/lib.decorators.d.ts +382 -0
  164. package/node_modules/@typescript/old/lib/lib.decorators.legacy.d.ts +20 -0
  165. package/node_modules/@typescript/old/lib/lib.dom.asynciterable.d.ts +18 -0
  166. package/node_modules/@typescript/old/lib/lib.dom.d.ts +45125 -0
  167. package/node_modules/@typescript/old/lib/lib.dom.iterable.d.ts +18 -0
  168. package/node_modules/@typescript/old/lib/lib.es2015.collection.d.ts +150 -0
  169. package/node_modules/@typescript/old/lib/lib.es2015.core.d.ts +595 -0
  170. package/node_modules/@typescript/old/lib/lib.es2015.d.ts +26 -0
  171. package/node_modules/@typescript/old/lib/lib.es2015.generator.d.ts +75 -0
  172. package/node_modules/@typescript/old/lib/lib.es2015.iterable.d.ts +603 -0
  173. package/node_modules/@typescript/old/lib/lib.es2015.promise.d.ts +79 -0
  174. package/node_modules/@typescript/old/lib/lib.es2015.proxy.d.ts +126 -0
  175. package/node_modules/@typescript/old/lib/lib.es2015.reflect.d.ts +142 -0
  176. package/node_modules/@typescript/old/lib/lib.es2015.symbol.d.ts +44 -0
  177. package/node_modules/@typescript/old/lib/lib.es2015.symbol.wellknown.d.ts +324 -0
  178. package/node_modules/@typescript/old/lib/lib.es2016.array.include.d.ts +114 -0
  179. package/node_modules/@typescript/old/lib/lib.es2016.d.ts +19 -0
  180. package/node_modules/@typescript/old/lib/lib.es2016.full.d.ts +21 -0
  181. package/node_modules/@typescript/old/lib/lib.es2016.intl.d.ts +29 -0
  182. package/node_modules/@typescript/old/lib/lib.es2017.arraybuffer.d.ts +19 -0
  183. package/node_modules/@typescript/old/lib/lib.es2017.d.ts +24 -0
  184. package/node_modules/@typescript/old/lib/lib.es2017.date.d.ts +29 -0
  185. package/node_modules/@typescript/old/lib/lib.es2017.full.d.ts +21 -0
  186. package/node_modules/@typescript/old/lib/lib.es2017.intl.d.ts +42 -0
  187. package/node_modules/@typescript/old/lib/lib.es2017.object.d.ts +47 -0
  188. package/node_modules/@typescript/old/lib/lib.es2017.sharedmemory.d.ts +133 -0
  189. package/node_modules/@typescript/old/lib/lib.es2017.string.d.ts +43 -0
  190. package/node_modules/@typescript/old/lib/lib.es2017.typedarrays.d.ts +51 -0
  191. package/node_modules/@typescript/old/lib/lib.es2018.asyncgenerator.d.ts +75 -0
  192. package/node_modules/@typescript/old/lib/lib.es2018.asynciterable.d.ts +51 -0
  193. package/node_modules/@typescript/old/lib/lib.es2018.d.ts +22 -0
  194. package/node_modules/@typescript/old/lib/lib.es2018.full.d.ts +22 -0
  195. package/node_modules/@typescript/old/lib/lib.es2018.intl.d.ts +81 -0
  196. package/node_modules/@typescript/old/lib/lib.es2018.promise.d.ts +28 -0
  197. package/node_modules/@typescript/old/lib/lib.es2018.regexp.d.ts +35 -0
  198. package/node_modules/@typescript/old/lib/lib.es2019.array.d.ts +77 -0
  199. package/node_modules/@typescript/old/lib/lib.es2019.d.ts +22 -0
  200. package/node_modules/@typescript/old/lib/lib.es2019.full.d.ts +22 -0
  201. package/node_modules/@typescript/old/lib/lib.es2019.intl.d.ts +21 -0
  202. package/node_modules/@typescript/old/lib/lib.es2019.object.d.ts +31 -0
  203. package/node_modules/@typescript/old/lib/lib.es2019.string.d.ts +35 -0
  204. package/node_modules/@typescript/old/lib/lib.es2019.symbol.d.ts +22 -0
  205. package/node_modules/@typescript/old/lib/lib.es2020.bigint.d.ts +763 -0
  206. package/node_modules/@typescript/old/lib/lib.es2020.d.ts +25 -0
  207. package/node_modules/@typescript/old/lib/lib.es2020.date.d.ts +40 -0
  208. package/node_modules/@typescript/old/lib/lib.es2020.full.d.ts +22 -0
  209. package/node_modules/@typescript/old/lib/lib.es2020.intl.d.ts +472 -0
  210. package/node_modules/@typescript/old/lib/lib.es2020.number.d.ts +26 -0
  211. package/node_modules/@typescript/old/lib/lib.es2020.promise.d.ts +45 -0
  212. package/node_modules/@typescript/old/lib/lib.es2020.sharedmemory.d.ts +97 -0
  213. package/node_modules/@typescript/old/lib/lib.es2020.string.d.ts +42 -0
  214. package/node_modules/@typescript/old/lib/lib.es2020.symbol.wellknown.d.ts +39 -0
  215. package/node_modules/@typescript/old/lib/lib.es2021.d.ts +21 -0
  216. package/node_modules/@typescript/old/lib/lib.es2021.full.d.ts +22 -0
  217. package/node_modules/@typescript/old/lib/lib.es2021.intl.d.ts +164 -0
  218. package/node_modules/@typescript/old/lib/lib.es2021.promise.d.ts +46 -0
  219. package/node_modules/@typescript/old/lib/lib.es2021.string.d.ts +31 -0
  220. package/node_modules/@typescript/old/lib/lib.es2021.weakref.d.ts +76 -0
  221. package/node_modules/@typescript/old/lib/lib.es2022.array.d.ts +119 -0
  222. package/node_modules/@typescript/old/lib/lib.es2022.d.ts +23 -0
  223. package/node_modules/@typescript/old/lib/lib.es2022.error.d.ts +73 -0
  224. package/node_modules/@typescript/old/lib/lib.es2022.full.d.ts +22 -0
  225. package/node_modules/@typescript/old/lib/lib.es2022.intl.d.ts +143 -0
  226. package/node_modules/@typescript/old/lib/lib.es2022.object.d.ts +24 -0
  227. package/node_modules/@typescript/old/lib/lib.es2022.regexp.d.ts +37 -0
  228. package/node_modules/@typescript/old/lib/lib.es2022.string.d.ts +23 -0
  229. package/node_modules/@typescript/old/lib/lib.es2023.array.d.ts +922 -0
  230. package/node_modules/@typescript/old/lib/lib.es2023.collection.d.ts +19 -0
  231. package/node_modules/@typescript/old/lib/lib.es2023.d.ts +20 -0
  232. package/node_modules/@typescript/old/lib/lib.es2023.full.d.ts +22 -0
  233. package/node_modules/@typescript/old/lib/lib.es2023.intl.d.ts +62 -0
  234. package/node_modules/@typescript/old/lib/lib.es2024.arraybuffer.d.ts +63 -0
  235. package/node_modules/@typescript/old/lib/lib.es2024.collection.d.ts +27 -0
  236. package/node_modules/@typescript/old/lib/lib.es2024.d.ts +24 -0
  237. package/node_modules/@typescript/old/lib/lib.es2024.full.d.ts +22 -0
  238. package/node_modules/@typescript/old/lib/lib.es2024.object.d.ts +27 -0
  239. package/node_modules/@typescript/old/lib/lib.es2024.promise.d.ts +33 -0
  240. package/node_modules/@typescript/old/lib/lib.es2024.regexp.d.ts +23 -0
  241. package/node_modules/@typescript/old/lib/lib.es2024.sharedmemory.d.ts +66 -0
  242. package/node_modules/@typescript/old/lib/lib.es2024.string.d.ts +27 -0
  243. package/node_modules/@typescript/old/lib/lib.es2025.collection.d.ts +94 -0
  244. package/node_modules/@typescript/old/lib/lib.es2025.d.ts +23 -0
  245. package/node_modules/@typescript/old/lib/lib.es2025.float16.d.ts +443 -0
  246. package/node_modules/@typescript/old/lib/lib.es2025.full.d.ts +22 -0
  247. package/node_modules/@typescript/old/lib/lib.es2025.intl.d.ts +200 -0
  248. package/node_modules/@typescript/old/lib/lib.es2025.iterator.d.ts +146 -0
  249. package/node_modules/@typescript/old/lib/lib.es2025.promise.d.ts +32 -0
  250. package/node_modules/@typescript/old/lib/lib.es2025.regexp.d.ts +30 -0
  251. package/node_modules/@typescript/old/lib/lib.es5.d.ts +4599 -0
  252. package/node_modules/@typescript/old/lib/lib.es6.d.ts +21 -0
  253. package/node_modules/@typescript/old/lib/lib.esnext.array.d.ts +33 -0
  254. package/node_modules/@typescript/old/lib/lib.esnext.collection.d.ts +47 -0
  255. package/node_modules/@typescript/old/lib/lib.esnext.d.ts +27 -0
  256. package/node_modules/@typescript/old/lib/lib.esnext.date.d.ts +21 -0
  257. package/node_modules/@typescript/old/lib/lib.esnext.decorators.d.ts +26 -0
  258. package/node_modules/@typescript/old/lib/lib.esnext.disposable.d.ts +191 -0
  259. package/node_modules/@typescript/old/lib/lib.esnext.error.d.ts +22 -0
  260. package/node_modules/@typescript/old/lib/lib.esnext.full.d.ts +22 -0
  261. package/node_modules/@typescript/old/lib/lib.esnext.intl.d.ts +107 -0
  262. package/node_modules/@typescript/old/lib/lib.esnext.sharedmemory.d.ts +23 -0
  263. package/node_modules/@typescript/old/lib/lib.esnext.temporal.d.ts +485 -0
  264. package/node_modules/@typescript/old/lib/lib.esnext.typedarrays.d.ts +90 -0
  265. package/node_modules/@typescript/old/lib/lib.scripthost.d.ts +320 -0
  266. package/node_modules/@typescript/old/lib/lib.webworker.asynciterable.d.ts +18 -0
  267. package/node_modules/@typescript/old/lib/lib.webworker.d.ts +15606 -0
  268. package/node_modules/@typescript/old/lib/lib.webworker.importscripts.d.ts +21 -0
  269. package/node_modules/@typescript/old/lib/lib.webworker.iterable.d.ts +18 -0
  270. package/node_modules/@typescript/old/lib/pl/diagnosticMessages.generated.json +2129 -0
  271. package/node_modules/@typescript/old/lib/pt-br/diagnosticMessages.generated.json +2129 -0
  272. package/node_modules/@typescript/old/lib/ru/diagnosticMessages.generated.json +2125 -0
  273. package/node_modules/@typescript/old/lib/tr/diagnosticMessages.generated.json +2129 -0
  274. package/node_modules/@typescript/old/lib/tsc.js +8 -0
  275. package/node_modules/@typescript/old/lib/tsserver.js +8 -0
  276. package/node_modules/@typescript/old/lib/tsserverlibrary.d.ts +17 -0
  277. package/node_modules/@typescript/old/lib/tsserverlibrary.js +21 -0
  278. package/node_modules/@typescript/old/lib/typesMap.json +497 -0
  279. package/node_modules/@typescript/old/lib/typescript.d.ts +11448 -0
  280. package/node_modules/@typescript/old/lib/typescript.js +201039 -0
  281. package/node_modules/@typescript/old/lib/typingsInstaller.js +8 -0
  282. package/node_modules/@typescript/old/lib/watchGuard.js +53 -0
  283. package/node_modules/@typescript/old/lib/zh-cn/diagnosticMessages.generated.json +2129 -0
  284. package/node_modules/@typescript/old/lib/zh-tw/diagnosticMessages.generated.json +2125 -0
  285. package/node_modules/@typescript/old/package.json +118 -0
  286. package/node_modules/@typescript/typescript6/LICENSE.txt +55 -0
  287. package/node_modules/@typescript/typescript6/README.md +9 -0
  288. package/node_modules/@typescript/typescript6/bin/tsc6 +2 -0
  289. package/node_modules/@typescript/typescript6/lib/tsc.js +1 -0
  290. package/node_modules/@typescript/typescript6/lib/tsserverlibrary.d.ts +2 -0
  291. package/node_modules/@typescript/typescript6/lib/tsserverlibrary.js +1 -0
  292. package/node_modules/@typescript/typescript6/lib/typescript.d.ts +2 -0
  293. package/node_modules/@typescript/typescript6/lib/typescript.js +1 -0
  294. package/node_modules/@typescript/typescript6/package.json +39 -0
  295. package/package.json +74 -22
  296. package/schemas/env-cap-report.schema.json +1 -1
  297. package/skills/env-cap/SKILL.md +91 -0
  298. package/skills/env-cap/references/api.md +220 -0
  299. package/specs/architecture.md +634 -0
  300. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  301. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  302. package/specs/decisions/0003-no-global-env-object.md +172 -0
  303. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  304. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  305. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  306. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  307. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  308. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  309. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  310. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  311. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  312. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  313. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  314. package/specs/decisions/0015-security-backport-window.md +60 -0
  315. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  316. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  317. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  318. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  319. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  320. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  321. package/specs/decisions/0022-validation-contexts.md +267 -0
  322. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  323. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  324. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  325. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  326. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  327. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  328. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  329. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  330. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  331. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  332. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  333. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  334. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  335. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  336. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  337. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  338. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  339. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  340. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  341. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  342. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  343. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  344. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  345. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  346. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  347. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  348. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  349. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  350. package/specs/generated-artifacts.md +104 -0
  351. package/specs/migrations/README.md +30 -0
  352. package/specs/migrations/from-centralized-schema.md +503 -0
  353. package/specs/migrations/from-dotenv.md +352 -0
  354. package/specs/migrations/from-envalid.md +482 -0
  355. package/specs/migrations/from-process-env.md +398 -0
  356. package/specs/migrations/from-t3-env.md +416 -0
  357. package/specs/migrations/from-zod.md +303 -0
  358. package/dist/build-U326PI5A.js.map +0 -1
  359. package/dist/chunk-BSTLSR2R.js.map +0 -1
package/dist/build.cjs CHANGED
@@ -2,19 +2,20 @@
2
2
 
3
3
  var path6 = require('path');
4
4
  var crypto = require('crypto');
5
- var ts4 = require('typescript');
6
5
  var module$1 = require('module');
7
6
 
8
7
  function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
9
8
 
10
9
  var path6__default = /*#__PURE__*/_interopDefault(path6);
11
10
  var crypto__default = /*#__PURE__*/_interopDefault(crypto);
12
- var ts4__default = /*#__PURE__*/_interopDefault(ts4);
13
11
 
14
- // src/build/evidence-snapshot.ts
15
- function displayPath(root, absolutePath) {
16
- const relative = path6__default.default.relative(root, absolutePath);
17
- if (relative.startsWith("..") || path6__default.default.isAbsolute(relative)) return absolutePath;
12
+ // node_modules/tsup/assets/cjs_shims.js
13
+ var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
14
+ var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
15
+ function displayPath(root, filePath) {
16
+ if (!path6__default.default.isAbsolute(filePath)) return filePath.split(path6__default.default.sep).join("/");
17
+ const relative = path6__default.default.relative(root, filePath);
18
+ if (relative.startsWith("..") || path6__default.default.isAbsolute(relative)) return filePath;
18
19
  return relative.split(path6__default.default.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,
@@ -366,30 +341,21 @@ async function computeEvidenceChanges(root, snapshotPath, activeContracts, curre
366
341
  };
367
342
  }
368
343
 
369
- // src/build/glob.ts
344
+ // src/_ipc/glob.ts
370
345
  function globToRegExp(pattern) {
371
346
  let out = "";
372
- let passes = 0;
373
- const maxPasses = pattern.length * 2 + 4;
374
- for (let i = 0; i < pattern.length; i++) {
375
- passes++;
376
- if (passes > maxPasses) {
377
- throw new Error(
378
- // Stryker disable next-line StringLiteral
379
- `globToRegExp: exceeded ${String(maxPasses)} iterations parsing pattern ${JSON.stringify(pattern)} -- this should never happen for any real pattern and indicates an internal parsing bug.`
380
- );
381
- }
382
- const char = pattern[i];
383
- if (char === void 0) continue;
347
+ let resume = 0;
348
+ for (const [i, char] of pattern.split("").entries()) {
349
+ if (i < resume) continue;
384
350
  if (char === "*" && pattern[i + 1] === "*") {
385
351
  const precededBySlashOrStart = i === 0 || pattern[i - 1] === "/";
386
352
  const followedBySlash = pattern[i + 2] === "/";
387
353
  if (precededBySlashOrStart && followedBySlash) {
388
354
  out += "(?:.*/)?";
389
- i += 2;
355
+ resume = i + 3;
390
356
  } else {
391
357
  out += ".*";
392
- i += 1;
358
+ resume = i + 2;
393
359
  }
394
360
  } else if (char === "*") {
395
361
  out += "[^/]*";
@@ -420,7 +386,7 @@ async function discoverSchemaFiles(options) {
420
386
  `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.`
421
387
  );
422
388
  }
423
- return included.map((file) => path6__default.default.normalize(file)).sort((a, b) => a < b ? -1 : 1);
389
+ return included.map((file) => path6__default.default.normalize(file)).sort();
424
390
  }
425
391
  async function walkDirectory(directory, root, exclude, fs) {
426
392
  const entries = await fs.readdir(directory, { withFileTypes: true });
@@ -446,18 +412,57 @@ function toPosixRelative(root, target) {
446
412
  function matchesAnyPattern(filePath, patterns) {
447
413
  return patterns.some((pattern) => globToRegExp(pattern).test(filePath));
448
414
  }
415
+ function hasClassicApi(candidate) {
416
+ return typeof candidate?.createSourceFile === "function";
417
+ }
418
+ function isModuleNotFound(error, id) {
419
+ const { code, message } = error ?? {};
420
+ if (code !== "MODULE_NOT_FOUND" && code !== "ERR_MODULE_NOT_FOUND") return false;
421
+ return typeof message === "string" && (message.startsWith(`Cannot find module '${id}'`) || message.startsWith(`Cannot find package '${id}'`));
422
+ }
423
+ function tryLoad(load, id) {
424
+ try {
425
+ return load(id);
426
+ } catch (error) {
427
+ if (isModuleNotFound(error, id)) return void 0;
428
+ throw error;
429
+ }
430
+ }
431
+ function pickCompiler(load) {
432
+ const consumer = tryLoad(load, "typescript");
433
+ if (hasClassicApi(consumer)) return consumer;
434
+ const bundled = tryLoad(load, "@typescript/typescript6");
435
+ if (hasClassicApi(bundled)) return bundled;
436
+ return consumer ?? {};
437
+ }
438
+ var ts = pickCompiler(module$1.createRequire(importMetaUrl));
439
+
440
+ // src/_ipc/compiler-api.ts
441
+ function assertCompilerApi(product, compiler) {
442
+ if (typeof compiler.createSourceFile === "function") return;
443
+ throw new Error(
444
+ `${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'.`
445
+ );
446
+ }
447
+
448
+ // src/build/compiler-api.ts
449
+ function assertCompilerApi2(compiler) {
450
+ assertCompilerApi("env-cap", compiler);
451
+ }
452
+
453
+ // src/build/literal-eval.ts
449
454
  function evaluateLiteral(node) {
450
- if (ts4__default.default.isStringLiteralLike(node)) return { ok: true, value: node.text };
451
- if (ts4__default.default.isNumericLiteral(node)) return { ok: true, value: Number(node.text) };
452
- if (node.kind === ts4__default.default.SyntaxKind.TrueKeyword) return { ok: true, value: true };
453
- if (node.kind === ts4__default.default.SyntaxKind.FalseKeyword) return { ok: true, value: false };
454
- if (node.kind === ts4__default.default.SyntaxKind.NullKeyword) return { ok: true, value: null };
455
- if (ts4__default.default.isParenthesizedExpression(node)) return evaluateLiteral(node.expression);
456
- if (ts4__default.default.isPrefixUnaryExpression(node) && node.operator === ts4__default.default.SyntaxKind.MinusToken) {
455
+ if (ts.isStringLiteralLike(node)) return { ok: true, value: node.text };
456
+ if (ts.isNumericLiteral(node)) return { ok: true, value: Number(node.text) };
457
+ if (node.kind === ts.SyntaxKind.TrueKeyword) return { ok: true, value: true };
458
+ if (node.kind === ts.SyntaxKind.FalseKeyword) return { ok: true, value: false };
459
+ if (node.kind === ts.SyntaxKind.NullKeyword) return { ok: true, value: null };
460
+ if (ts.isParenthesizedExpression(node)) return evaluateLiteral(node.expression);
461
+ if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken) {
457
462
  const operand = evaluateLiteral(node.operand);
458
463
  return operand.ok && typeof operand.value === "number" ? { ok: true, value: -operand.value } : { ok: false };
459
464
  }
460
- if (ts4__default.default.isArrayLiteralExpression(node)) {
465
+ if (ts.isArrayLiteralExpression(node)) {
461
466
  const values = [];
462
467
  for (const element of node.elements) {
463
468
  const result = evaluateLiteral(element);
@@ -466,10 +471,10 @@ function evaluateLiteral(node) {
466
471
  }
467
472
  return { ok: true, value: values };
468
473
  }
469
- if (ts4__default.default.isObjectLiteralExpression(node)) {
474
+ if (ts.isObjectLiteralExpression(node)) {
470
475
  const record = {};
471
476
  for (const prop of node.properties) {
472
- if (!ts4__default.default.isPropertyAssignment(prop)) return { ok: false };
477
+ if (!ts.isPropertyAssignment(prop)) return { ok: false };
473
478
  const key = getStaticPropertyName(prop.name);
474
479
  if (key === void 0) return { ok: false };
475
480
  const result = evaluateLiteral(prop.initializer);
@@ -481,20 +486,21 @@ function evaluateLiteral(node) {
481
486
  return { ok: false };
482
487
  }
483
488
  function getStaticPropertyName(name) {
484
- if (ts4__default.default.isIdentifier(name)) return name.text;
485
- if (ts4__default.default.isStringLiteralLike(name)) return name.text;
486
- if (ts4__default.default.isNumericLiteral(name)) return name.text;
489
+ if (ts.isIdentifier(name)) return name.text;
490
+ if (ts.isStringLiteralLike(name)) return name.text;
491
+ if (ts.isNumericLiteral(name)) return name.text;
487
492
  return void 0;
488
493
  }
489
494
 
490
495
  // src/build/parse.ts
491
496
  function parseSchemaFile(filePath, sourceText) {
492
- const sourceFile = ts4__default.default.createSourceFile(
497
+ assertCompilerApi2(ts);
498
+ const sourceFile = ts.createSourceFile(
493
499
  filePath,
494
500
  sourceText,
495
- ts4__default.default.ScriptTarget.Latest,
501
+ ts.ScriptTarget.Latest,
496
502
  true,
497
- ts4__default.default.ScriptKind.TS
503
+ ts.ScriptKind.TS
498
504
  );
499
505
  const warnings = [];
500
506
  const localConsts = /* @__PURE__ */ new Map();
@@ -503,21 +509,21 @@ function parseSchemaFile(filePath, sourceText) {
503
509
  const createEnvCalls = [];
504
510
  const documentEnvCalls = [];
505
511
  for (const statement of sourceFile.statements) {
506
- if (ts4__default.default.isImportDeclaration(statement)) {
512
+ if (ts.isImportDeclaration(statement)) {
507
513
  collectImportBindings(statement, imports);
508
514
  continue;
509
515
  }
510
- if (!ts4__default.default.isVariableStatement(statement)) continue;
511
- const isExported = statement.modifiers?.some((m) => m.kind === ts4__default.default.SyntaxKind.ExportKeyword) ?? false;
516
+ if (!ts.isVariableStatement(statement)) continue;
517
+ const isExported = statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
512
518
  for (const decl of statement.declarationList.declarations) {
513
- if (!ts4__default.default.isIdentifier(decl.name) || !decl.initializer) continue;
519
+ if (!ts.isIdentifier(decl.name) || !decl.initializer) continue;
514
520
  const bindingName = decl.name.text;
515
- if (ts4__default.default.isObjectLiteralExpression(decl.initializer)) {
521
+ if (ts.isObjectLiteralExpression(decl.initializer)) {
516
522
  localConsts.set(bindingName, decl.initializer);
517
523
  if (isExported) exportedConstNames.add(bindingName);
518
524
  continue;
519
525
  }
520
- if (ts4__default.default.isCallExpression(decl.initializer)) {
526
+ if (ts.isCallExpression(decl.initializer)) {
521
527
  if (isCallToName(decl.initializer, "createEnv")) {
522
528
  if (!isExported) {
523
529
  warnings.push({
@@ -545,9 +551,9 @@ function parseSchemaFile(filePath, sourceText) {
545
551
  }
546
552
  }
547
553
  for (const statement of sourceFile.statements) {
548
- if (!ts4__default.default.isExpressionStatement(statement)) continue;
554
+ if (!ts.isExpressionStatement(statement)) continue;
549
555
  const expr = statement.expression;
550
- if (!ts4__default.default.isCallExpression(expr) || !isCallToName(expr, "documentEnv")) continue;
556
+ if (!ts.isCallExpression(expr) || !isCallToName(expr, "documentEnv")) continue;
551
557
  const [schemaArg, docsArg] = expr.arguments;
552
558
  documentEnvCalls.push({ schemaRef: resolveSchemaRef(schemaArg), docsArg, node: expr });
553
559
  }
@@ -564,15 +570,15 @@ function parseSchemaFile(filePath, sourceText) {
564
570
  }
565
571
  function resolveSchemaRef(node) {
566
572
  if (!node) return { kind: "unresolvable" };
567
- if (ts4__default.default.isObjectLiteralExpression(node)) return { kind: "literal", node };
568
- if (ts4__default.default.isIdentifier(node)) return { kind: "identifier", name: node.text };
573
+ if (ts.isObjectLiteralExpression(node)) return { kind: "literal", node };
574
+ if (ts.isIdentifier(node)) return { kind: "identifier", name: node.text };
569
575
  return { kind: "unresolvable" };
570
576
  }
571
577
  function collectImportBindings(statement, imports) {
572
- if (!ts4__default.default.isStringLiteralLike(statement.moduleSpecifier)) return;
578
+ if (!ts.isStringLiteralLike(statement.moduleSpecifier)) return;
573
579
  const specifier = statement.moduleSpecifier.text;
574
580
  const namedBindings = statement.importClause?.namedBindings;
575
- if (!namedBindings || !ts4__default.default.isNamedImports(namedBindings)) return;
581
+ if (!namedBindings || !ts.isNamedImports(namedBindings)) return;
576
582
  for (const element of namedBindings.elements) {
577
583
  const localName = element.name.text;
578
584
  const importedName = element.propertyName?.text ?? localName;
@@ -581,8 +587,8 @@ function collectImportBindings(statement, imports) {
581
587
  }
582
588
  function isCallToName(call, name) {
583
589
  const expr = call.expression;
584
- if (ts4__default.default.isIdentifier(expr)) return expr.text === name;
585
- if (ts4__default.default.isPropertyAccessExpression(expr)) return expr.name.text === name;
590
+ if (ts.isIdentifier(expr)) return expr.text === name;
591
+ if (ts.isPropertyAccessExpression(expr)) return expr.name.text === name;
586
592
  return false;
587
593
  }
588
594
  function isValidEnvKey(key) {
@@ -591,7 +597,7 @@ function isValidEnvKey(key) {
591
597
  function extractSchemaVariables(schemaLiteral, filePath, contextLabel, warnings, sourceFile) {
592
598
  const variables = [];
593
599
  for (const prop of schemaLiteral.properties) {
594
- if (!ts4__default.default.isPropertyAssignment(prop)) {
600
+ if (!ts.isPropertyAssignment(prop)) {
595
601
  warnings.push({
596
602
  file: filePath,
597
603
  message: `Skipped a non-static schema entry in "${contextLabel}" (spread or computed key are not statically analyzable).`
@@ -607,7 +613,7 @@ function extractSchemaVariables(schemaLiteral, filePath, contextLabel, warnings,
607
613
  });
608
614
  continue;
609
615
  }
610
- if (!ts4__default.default.isObjectLiteralExpression(prop.initializer)) {
616
+ if (!ts.isObjectLiteralExpression(prop.initializer)) {
611
617
  warnings.push({
612
618
  file: filePath,
613
619
  message: `Definition for "${key}" in "${contextLabel}" is not an inline object literal; skipping static analysis for this variable.`
@@ -631,7 +637,7 @@ function extractSchemaVariable(key, definition, filePath, contextLabel, warnings
631
637
  let validatorSource;
632
638
  let context;
633
639
  for (const prop of definition.properties) {
634
- if (!ts4__default.default.isPropertyAssignment(prop)) continue;
640
+ if (!ts.isPropertyAssignment(prop)) continue;
635
641
  const name = getStaticPropertyName(prop.name);
636
642
  if (name === "default") {
637
643
  hasDefault = true;
@@ -669,13 +675,13 @@ function extractSchemaVariable(key, definition, filePath, contextLabel, warnings
669
675
  };
670
676
  }
671
677
  function extractReturnType(node) {
672
- if ((ts4__default.default.isArrowFunction(node) || ts4__default.default.isFunctionExpression(node)) && node.type) {
673
- return node.type.getText().replace(/\s+/g, "");
678
+ if ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.type) {
679
+ return node.type.getText().replace(/\s/g, "");
674
680
  }
675
681
  return void 0;
676
682
  }
677
683
  function normalizeSource(text) {
678
- return text.replace(/\s+/g, " ").trim();
684
+ return text.replace(/\s+/g, " ");
679
685
  }
680
686
  function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
681
687
  let name;
@@ -694,7 +700,7 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
694
700
  let auditRequired;
695
701
  let metadata;
696
702
  const variables = /* @__PURE__ */ new Map();
697
- if (!docsArg || !ts4__default.default.isObjectLiteralExpression(docsArg)) {
703
+ if (!docsArg || !ts.isObjectLiteralExpression(docsArg)) {
698
704
  if (docsArg) {
699
705
  warnings.push({
700
706
  file: filePath,
@@ -721,7 +727,7 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
721
727
  };
722
728
  }
723
729
  for (const prop of docsArg.properties) {
724
- if (!ts4__default.default.isPropertyAssignment(prop)) continue;
730
+ if (!ts.isPropertyAssignment(prop)) continue;
725
731
  const propName = getStaticPropertyName(prop.name);
726
732
  if (propName === "name") {
727
733
  const evaluated = evaluateLiteral(prop.initializer);
@@ -825,7 +831,7 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
825
831
  });
826
832
  }
827
833
  } else if (propName === "variables") {
828
- if (ts4__default.default.isObjectLiteralExpression(prop.initializer)) {
834
+ if (ts.isObjectLiteralExpression(prop.initializer)) {
829
835
  extractVariableDocsMap(prop.initializer, filePath, contextLabel, warnings, variables);
830
836
  } else {
831
837
  warnings.push({
@@ -856,10 +862,10 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
856
862
  }
857
863
  function extractVariableDocsMap(variablesLiteral, filePath, contextLabel, warnings, out) {
858
864
  for (const prop of variablesLiteral.properties) {
859
- if (!ts4__default.default.isPropertyAssignment(prop)) continue;
865
+ if (!ts.isPropertyAssignment(prop)) continue;
860
866
  const key = getStaticPropertyName(prop.name);
861
867
  if (key === void 0) continue;
862
- if (!ts4__default.default.isObjectLiteralExpression(prop.initializer)) {
868
+ if (!ts.isObjectLiteralExpression(prop.initializer)) {
863
869
  warnings.push({
864
870
  file: filePath,
865
871
  message: `documentEnv() variable docs for "${key}" in "${contextLabel}" is not an inline object literal; skipped.`
@@ -889,11 +895,9 @@ function extractVariableDocsMap(variablesLiteral, filePath, contextLabel, warnin
889
895
  let metadata;
890
896
  let evidence;
891
897
  for (const field of prop.initializer.properties) {
892
- if (!ts4__default.default.isPropertyAssignment(field)) continue;
898
+ if (!ts.isPropertyAssignment(field)) continue;
893
899
  const fieldName = getStaticPropertyName(field.name);
894
- if (fieldName === void 0) continue;
895
900
  const evaluated = evaluateLiteral(field.initializer);
896
- if (!evaluated.ok) continue;
897
901
  if (fieldName === "description" && typeof evaluated.value === "string")
898
902
  description = evaluated.value;
899
903
  else if (fieldName === "owner" && typeof evaluated.value === "string") owner = evaluated.value;
@@ -989,9 +993,9 @@ function extractDynamicAccessCitations(value, filePath, key, contextLabel, warni
989
993
  return citations;
990
994
  }
991
995
  function extractCreateEnvOptionsName(optionsArg) {
992
- if (!optionsArg || !ts4__default.default.isObjectLiteralExpression(optionsArg)) return void 0;
996
+ if (!optionsArg || !ts.isObjectLiteralExpression(optionsArg)) return void 0;
993
997
  for (const prop of optionsArg.properties) {
994
- if (!ts4__default.default.isPropertyAssignment(prop)) continue;
998
+ if (!ts.isPropertyAssignment(prop)) continue;
995
999
  if (getStaticPropertyName(prop.name) !== "name") continue;
996
1000
  const evaluated = evaluateLiteral(prop.initializer);
997
1001
  if (evaluated.ok && typeof evaluated.value === "string") return evaluated.value;
@@ -1016,6 +1020,93 @@ function mustGet(map, key) {
1016
1020
  throw new Error(`Internal error: expected key "${String(key)}" to be present in map.`);
1017
1021
  return value;
1018
1022
  }
1023
+
1024
+ // src/build/merge-documentation.ts
1025
+ var VALUE_FIELDS = [
1026
+ "description",
1027
+ "owner",
1028
+ "sensitivity",
1029
+ "expiresAt",
1030
+ "refreshInstructions",
1031
+ "authenticatorType",
1032
+ "rotationPeriod",
1033
+ "lastRotatedAt",
1034
+ "rotationTriggerEvents",
1035
+ "setupInstructions",
1036
+ "required",
1037
+ "deprecated",
1038
+ "deprecatedReason",
1039
+ "removeBy",
1040
+ "renamedFrom",
1041
+ "purpose",
1042
+ "legalBasis",
1043
+ "retention",
1044
+ "dataResidency",
1045
+ "auditRequired"
1046
+ ];
1047
+ function mergeSharedDocumentation(contracts) {
1048
+ const declarationsByKey = /* @__PURE__ */ new Map();
1049
+ for (const contract of contracts) {
1050
+ for (const variable of contract.variables) {
1051
+ const declarations = declarationsByKey.get(variable.key);
1052
+ if (declarations === void 0) declarationsByKey.set(variable.key, [{ contract, variable }]);
1053
+ else declarations.push({ contract, variable });
1054
+ }
1055
+ }
1056
+ return contracts.map((contract) => ({
1057
+ ...contract,
1058
+ variables: contract.variables.map((variable) => {
1059
+ const fromPackages = [];
1060
+ const fromApplication = [];
1061
+ for (const declaration of mustGet(declarationsByKey, variable.key)) {
1062
+ if (declaration.variable === variable) continue;
1063
+ const fromPackage = declaration.contract.packageOrigin !== void 0;
1064
+ if (!fromPackage && contract.packageOrigin === void 0) continue;
1065
+ (fromPackage ? fromPackages : fromApplication).push(declaration);
1066
+ }
1067
+ return fromPackages.length + fromApplication.length === 0 ? variable : filled(variable, fromPackages, fromApplication);
1068
+ })
1069
+ }));
1070
+ }
1071
+ function donated(read, fromPackages, fromApplication) {
1072
+ const fromPackage = fromPackages.find(({ variable }) => read(variable) !== void 0);
1073
+ if (fromPackage !== void 0) return read(fromPackage.variable);
1074
+ const values = fromApplication.map(({ variable }) => read(variable)).filter((v) => v !== void 0);
1075
+ return values.every((value) => deepEqual(value, values[0])) ? values[0] : void 0;
1076
+ }
1077
+ function filled(variable, fromPackages, fromApplication) {
1078
+ const donors = [...fromPackages, ...fromApplication];
1079
+ const merged = { ...variable };
1080
+ for (const field of VALUE_FIELDS) {
1081
+ if (variable[field] !== void 0) continue;
1082
+ merged[field] = donated((other) => other[field], fromPackages, fromApplication);
1083
+ }
1084
+ const metadata = {};
1085
+ for (const key of new Set(
1086
+ donors.flatMap(({ variable: other }) => Object.keys(other.metadata ?? {}))
1087
+ )) {
1088
+ const value = donated((other) => other.metadata?.[key], fromPackages, fromApplication);
1089
+ if (value !== void 0) metadata[key] = value;
1090
+ }
1091
+ Object.assign(metadata, variable.metadata);
1092
+ const result = {
1093
+ ...merged,
1094
+ metadata: Object.keys(metadata).length === 0 ? variable.metadata : metadata,
1095
+ documented: variable.documented || donors.some(({ variable: other }) => other.documented)
1096
+ };
1097
+ DONATED.set(
1098
+ result,
1099
+ /* @__PURE__ */ new Set([
1100
+ ...VALUE_FIELDS.filter((field) => result[field] !== variable[field]),
1101
+ ...Object.keys(metadata).filter((key) => metadata[key] !== variable.metadata?.[key]).map((key) => `metadata.${key}`)
1102
+ ])
1103
+ );
1104
+ return result;
1105
+ }
1106
+ var DONATED = /* @__PURE__ */ new WeakMap();
1107
+ function donatedTo(variable) {
1108
+ return DONATED.get(variable) ?? /* @__PURE__ */ new Set();
1109
+ }
1019
1110
  function isWithinDirectory(baseDir, targetPath) {
1020
1111
  const relative = path6__default.default.relative(baseDir, targetPath);
1021
1112
  return relative !== ".." && !relative.startsWith(`..${path6__default.default.sep}`) && !path6__default.default.isAbsolute(relative);
@@ -1226,13 +1317,15 @@ async function mergeLocalAndPackageFiles(localFiles, packageFiles, fs) {
1226
1317
  }
1227
1318
  async function resolvePackageImport(specifier, allowedPackages, root, cache, fs) {
1228
1319
  const matched = allowedPackages.find(
1229
- // Stryker disable next-line ConditionalExpression
1230
1320
  (pkg) => specifier === pkg || specifier.startsWith(`${pkg}/`)
1231
1321
  );
1232
1322
  if (!matched) return void 0;
1233
1323
  const result = await resolvePackageSchemaFile(matched, root, cache, fs);
1234
1324
  return result.ok ? result.origin.resolvedFile : void 0;
1235
1325
  }
1326
+ function pathMappingOptions(options) {
1327
+ return options;
1328
+ }
1236
1329
  function createAliasResolutionCache() {
1237
1330
  return { resolutions: /* @__PURE__ */ new Map() };
1238
1331
  }
@@ -1243,7 +1336,10 @@ async function fileExists(filePath, fs) {
1243
1336
  }
1244
1337
  return false;
1245
1338
  }
1246
- async function loadTsconfigPaths(root, tsconfigOption, fs) {
1339
+ function typescriptPath(file, separator) {
1340
+ return file.split(separator).join("/");
1341
+ }
1342
+ async function loadTsconfigPaths(product, root, tsconfigOption, fs) {
1247
1343
  if (tsconfigOption === false) return { resolution: void 0, warning: void 0 };
1248
1344
  const isExplicit = tsconfigOption !== void 0;
1249
1345
  const configFile = path6__default.default.resolve(root, tsconfigOption ?? "tsconfig.json");
@@ -1257,9 +1353,13 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1257
1353
  }
1258
1354
  };
1259
1355
  }
1260
- const readResult = ts4__default.default.readConfigFile(configFile, (p) => ts4__default.default.sys.readFile(p));
1356
+ assertCompilerApi(product, ts);
1357
+ const readResult = ts.readConfigFile(
1358
+ typescriptPath(configFile, path6__default.default.sep),
1359
+ (p) => ts.sys.readFile(p)
1360
+ );
1261
1361
  if (readResult.error) {
1262
- const detail = ts4__default.default.flattenDiagnosticMessageText(readResult.error.messageText, "\n");
1362
+ const detail = ts.flattenDiagnosticMessageText(readResult.error.messageText, ts.sys.newLine);
1263
1363
  return {
1264
1364
  resolution: void 0,
1265
1365
  warning: {
@@ -1268,8 +1368,8 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1268
1368
  }
1269
1369
  };
1270
1370
  }
1271
- const parsed = ts4__default.default.parseJsonConfigFileContent(readResult.config, ts4__default.default.sys, path6__default.default.dirname(configFile));
1272
- const { paths, baseUrl } = parsed.options;
1371
+ const parsed = ts.parseJsonConfigFileContent(readResult.config, ts.sys, path6__default.default.dirname(configFile));
1372
+ const { paths, baseUrl } = pathMappingOptions(parsed.options);
1273
1373
  const hasPaths = paths !== void 0 && Object.keys(paths).length > 0;
1274
1374
  if (!hasPaths && baseUrl === void 0) {
1275
1375
  return { resolution: void 0, warning: void 0 };
@@ -1279,7 +1379,7 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1279
1379
  function resolveAliasImport(specifier, importingFile, resolution, cache) {
1280
1380
  const cacheKey = `${importingFile}\0${specifier}`;
1281
1381
  if (cache.resolutions.has(cacheKey)) return cache.resolutions.get(cacheKey);
1282
- const result = ts4__default.default.resolveModuleName(specifier, importingFile, resolution.compilerOptions, ts4__default.default.sys);
1382
+ const result = ts.resolveModuleName(specifier, importingFile, resolution.compilerOptions, ts.sys);
1283
1383
  const resolvedFileName = result.resolvedModule?.resolvedFileName;
1284
1384
  let resolved;
1285
1385
  if (resolvedFileName) {
@@ -1292,6 +1392,11 @@ function resolveAliasImport(specifier, importingFile, resolution, cache) {
1292
1392
  return resolved;
1293
1393
  }
1294
1394
 
1395
+ // src/build/resolution/resolve-tsconfig-paths.ts
1396
+ function loadTsconfigPaths2(root, tsconfigOption, fs) {
1397
+ return loadTsconfigPaths("env-cap", root, tsconfigOption, fs);
1398
+ }
1399
+
1295
1400
  // src/build/resolution/resolve-import.ts
1296
1401
  async function resolveRelativeImport(importingFile, specifier, fs) {
1297
1402
  if (!specifier.startsWith("./") && !specifier.startsWith("../")) return void 0;
@@ -1307,13 +1412,11 @@ async function resolveRelativeImport(importingFile, specifier, fs) {
1307
1412
  }
1308
1413
  return void 0;
1309
1414
  }
1310
- async function fileExists2(filePath, fs) {
1311
- try {
1312
- const stat = await fs.stat(filePath);
1313
- return stat.isFile();
1314
- } catch {
1315
- return false;
1316
- }
1415
+ function fileExists2(filePath, fs) {
1416
+ return fs.stat(filePath).then(
1417
+ (stat) => stat.isFile(),
1418
+ () => false
1419
+ );
1317
1420
  }
1318
1421
  async function resolveImportSpecifier(importingFile, specifier, context) {
1319
1422
  const relative = await resolveRelativeImport(importingFile, specifier, context.fs);
@@ -1352,24 +1455,29 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1352
1455
  const warnings = [];
1353
1456
  const unresolvedLinks = [];
1354
1457
  async function resolveSchema(ref, inFile, contextLabel) {
1355
- if (ref.kind === "unresolvable") return void 0;
1356
1458
  const inFileAnalysis = mustGet(analysisCache, inFile);
1357
- if (ref.kind === "literal") {
1358
- return {
1359
- identity: `${inFile}#<inline:${ref.node.pos}>`,
1360
- variables: extractSchemaVariables(
1361
- ref.node,
1362
- inFile,
1363
- contextLabel,
1364
- warnings,
1365
- inFileAnalysis.sourceFile
1366
- )
1367
- };
1459
+ switch (ref.kind) {
1460
+ case "literal":
1461
+ return {
1462
+ identity: `${inFile}#<inline:${ref.node.pos}>`,
1463
+ variables: extractSchemaVariables(
1464
+ ref.node,
1465
+ inFile,
1466
+ contextLabel,
1467
+ warnings,
1468
+ inFileAnalysis.sourceFile
1469
+ )
1470
+ };
1471
+ case "identifier":
1472
+ return resolveNamedSchema(ref.name, inFile, inFileAnalysis, contextLabel);
1368
1473
  }
1369
- const local = inFileAnalysis.localConsts.get(ref.name);
1474
+ return void 0;
1475
+ }
1476
+ async function resolveNamedSchema(name, inFile, inFileAnalysis, contextLabel) {
1477
+ const local = inFileAnalysis.localConsts.get(name);
1370
1478
  if (local) {
1371
1479
  return {
1372
- identity: `${inFile}#${ref.name}`,
1480
+ identity: `${inFile}#${name}`,
1373
1481
  variables: extractSchemaVariables(
1374
1482
  local,
1375
1483
  inFile,
@@ -1379,7 +1487,7 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1379
1487
  )
1380
1488
  };
1381
1489
  }
1382
- const imported = inFileAnalysis.imports.get(ref.name);
1490
+ const imported = inFileAnalysis.imports.get(name);
1383
1491
  if (!imported) return void 0;
1384
1492
  const targetFile = await resolveImportSpecifier(inFile, imported.specifier, context);
1385
1493
  if (!targetFile) return void 0;
@@ -1447,7 +1555,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1447
1555
  }
1448
1556
  const contracts = [];
1449
1557
  const undocumentedContracts = [];
1450
- const undocumentedVariables = [];
1451
1558
  const staleDocEntries = [];
1452
1559
  for (const entry of createEnvEntries) {
1453
1560
  const linked = documentEnvByIdentity.get(entry.identity);
@@ -1457,10 +1564,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1457
1564
  }
1458
1565
  const schemaKeys = new Set(entry.variables.map((v) => v.key));
1459
1566
  const docsVariables = docs?.variables ?? /* @__PURE__ */ new Map();
1460
- for (const key of schemaKeys) {
1461
- if (!docsVariables.has(key))
1462
- undocumentedVariables.push({ file: entry.file, exportName: entry.exportName, key });
1463
- }
1464
1567
  for (const key of docsVariables.keys()) {
1465
1568
  if (!schemaKeys.has(key))
1466
1569
  staleDocEntries.push({ file: entry.file, exportName: entry.exportName, key });
@@ -1522,12 +1625,17 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1522
1625
  for (const analysis of analysisCache.values()) {
1523
1626
  warnings.push(...analysis.warnings);
1524
1627
  }
1628
+ const merged = mergeSharedDocumentation(contracts);
1525
1629
  return {
1526
- contracts,
1630
+ contracts: merged,
1527
1631
  warnings,
1528
1632
  unresolvedLinks,
1633
+ // Judged after the merge: a variable a package's contract documents is documented for the application that
1634
+ // declares it again.
1635
+ undocumentedVariables: merged.flatMap(
1636
+ ({ file, exportName, variables }) => variables.filter(({ documented }) => !documented).map(({ key }) => ({ file, exportName, key }))
1637
+ ),
1529
1638
  undocumentedContracts,
1530
- undocumentedVariables,
1531
1639
  staleDocEntries
1532
1640
  };
1533
1641
  }
@@ -1565,7 +1673,7 @@ function effectiveAuditRequired(contract, variable) {
1565
1673
 
1566
1674
  // src/build/assemble-project.ts
1567
1675
  async function assembleProject(options) {
1568
- const { fs, root, include, exclude, packages, tsconfig } = options;
1676
+ const { fs, root, include, exclude, packages = [], tsconfig } = options;
1569
1677
  const fileCache = /* @__PURE__ */ new Map();
1570
1678
  const readFileCached = (filePath) => {
1571
1679
  let cached = fileCache.get(filePath);
@@ -1587,7 +1695,7 @@ async function assembleProject(options) {
1587
1695
  packageFiles.map((f) => f.file),
1588
1696
  fs
1589
1697
  );
1590
- const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths(
1698
+ const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths2(
1591
1699
  root,
1592
1700
  tsconfig,
1593
1701
  fs
@@ -1622,7 +1730,6 @@ function buildChangeModel(manifest, currentContracts, root) {
1622
1730
  const relativeFile = displayPath(root, contract.file);
1623
1731
  const cIdentity = contractIdentity2(relativeFile, contract.exportName);
1624
1732
  for (const variable of contract.variables) {
1625
- if (!variable.renamedFrom) continue;
1626
1733
  const addedRef = findByContractAndKey(
1627
1734
  manifest.addedVariables,
1628
1735
  relativeFile,
@@ -1653,24 +1760,20 @@ function buildChangeModel(manifest, currentContracts, root) {
1653
1760
  }
1654
1761
 
1655
1762
  // src/build/compatibility.ts
1656
- var DOCUMENTATION_COMPARISON_FIELDS = [
1657
- "description",
1658
- "owner",
1659
- "sensitivity",
1660
- "expiresAt",
1661
- "refreshInstructions",
1662
- "setupInstructions",
1663
- "required"
1664
- ];
1665
1763
  function documentationDivergences(a, b) {
1666
1764
  const divergences = [];
1667
- for (const field of DOCUMENTATION_COMPARISON_FIELDS) {
1668
- if (a[field] !== b[field]) divergences.push(field);
1765
+ const given = /* @__PURE__ */ new Set([...donatedTo(a), ...donatedTo(b)]);
1766
+ for (const field of VALUE_FIELDS) {
1767
+ if (!given.has(field) && a[field] !== void 0 && b[field] !== void 0 && !deepEqual(a[field], b[field])) {
1768
+ divergences.push(field);
1769
+ }
1669
1770
  }
1670
1771
  const aMetadata = a.metadata ?? {};
1671
1772
  const bMetadata = b.metadata ?? {};
1672
- for (const key of /* @__PURE__ */ new Set([...Object.keys(aMetadata), ...Object.keys(bMetadata)])) {
1673
- if (!deepEqual(aMetadata[key], bMetadata[key])) divergences.push(`metadata.${key}`);
1773
+ for (const key of Object.keys(aMetadata)) {
1774
+ if (!given.has(`metadata.${key}`) && key in bMetadata && !deepEqual(aMetadata[key], bMetadata[key])) {
1775
+ divergences.push(`metadata.${key}`);
1776
+ }
1674
1777
  }
1675
1778
  return divergences;
1676
1779
  }
@@ -1717,17 +1820,15 @@ function detectCompatibilityIssues(contracts) {
1717
1820
  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.`
1718
1821
  });
1719
1822
  }
1720
- if (a.variable.documented && b.variable.documented) {
1721
- const divergences = documentationDivergences(a.variable, b.variable);
1722
- if (divergences.length > 0) {
1723
- issues.push({
1724
- severity: "warning",
1725
- variable: key,
1726
- files: [a.file, b.file],
1727
- code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1728
- 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.`
1729
- });
1730
- }
1823
+ const divergences = documentationDivergences(a.variable, b.variable);
1824
+ if (divergences.length > 0) {
1825
+ issues.push({
1826
+ severity: "warning",
1827
+ variable: key,
1828
+ files: [a.file, b.file],
1829
+ code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1830
+ 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.`
1831
+ });
1731
1832
  }
1732
1833
  }
1733
1834
  }
@@ -1748,8 +1849,7 @@ function variableShape(variable) {
1748
1849
  };
1749
1850
  }
1750
1851
  function shapesMatch(a, b) {
1751
- if (a.valueType === "unknown" || b.valueType === "unknown") return false;
1752
- return a.valueType === b.valueType && a.hasProcessor === b.hasProcessor && a.hasValidator === b.hasValidator;
1852
+ return a.valueType !== "unknown" && a.valueType === b.valueType && a.hasProcessor === b.hasProcessor && a.hasValidator === b.hasValidator;
1753
1853
  }
1754
1854
  function detectDuplicateVariableShapes(contracts) {
1755
1855
  const candidates = contracts.filter((c) => c.active && !c.exclusiveGroup);
@@ -1888,60 +1988,55 @@ function isPlainObject(value) {
1888
1988
  const proto = Object.getPrototypeOf(value);
1889
1989
  return proto === Object.prototype || proto === null;
1890
1990
  }
1991
+
1992
+ // src/build/scan-dependencies.ts
1891
1993
  function unwrapParens(node) {
1892
1994
  let current = node;
1893
- while (ts4__default.default.isParenthesizedExpression(current)) current = current.expression;
1995
+ while (ts.isParenthesizedExpression(current)) current = current.expression;
1894
1996
  return current;
1895
1997
  }
1896
1998
  function staticElementKey(node) {
1897
- return ts4__default.default.isStringLiteralLike(node) ? node.text : void 0;
1999
+ return ts.isStringLiteralLike(node) ? node.text : void 0;
1898
2000
  }
1899
2001
  function forEachBindingName(name, record) {
1900
- if (ts4__default.default.isIdentifier(name)) {
2002
+ if (ts.isIdentifier(name)) {
1901
2003
  record(name.text);
1902
2004
  return;
1903
2005
  }
1904
2006
  for (const element of name.elements) {
1905
- if (ts4__default.default.isOmittedExpression(element)) continue;
2007
+ if (ts.isOmittedExpression(element)) continue;
1906
2008
  forEachBindingName(element.name, record);
1907
2009
  }
1908
2010
  }
1909
2011
  function isAssignmentToken(token) {
1910
- return token >= ts4__default.default.SyntaxKind.FirstAssignment && token <= ts4__default.default.SyntaxKind.LastAssignment;
2012
+ return token >= ts.SyntaxKind.FirstAssignment && token <= ts.SyntaxKind.LastAssignment;
1911
2013
  }
1912
2014
  function recordIfIdentifierTarget(expression, assignedNames) {
1913
2015
  const target = unwrapParens(expression);
1914
- if (ts4__default.default.isIdentifier(target)) assignedNames.add(target.text);
2016
+ if (ts.isIdentifier(target)) assignedNames.add(target.text);
1915
2017
  }
1916
2018
  function recordAssignmentTargets(node, assignedNames) {
1917
- if (ts4__default.default.isBinaryExpression(node) && isAssignmentToken(node.operatorToken.kind)) {
2019
+ if (ts.isBinaryExpression(node) && isAssignmentToken(node.operatorToken.kind)) {
1918
2020
  recordIfIdentifierTarget(node.left, assignedNames);
1919
2021
  return;
1920
2022
  }
1921
- if (
1922
- // Widening this to `true` is behaviorally equivalent, not a real gap:
1923
- // only a prefix/postfix unary node carries an `.operator` at all, so on
1924
- // any other node the two `=== PlusPlus/MinusMinus` checks below both
1925
- // read `undefined` and fail. Hand-verified: mutating this compound to
1926
- // `if (true)` and running the real suite passes unchanged.
1927
- // Stryker disable next-line ConditionalExpression
1928
- (ts4__default.default.isPrefixUnaryExpression(node) || ts4__default.default.isPostfixUnaryExpression(node)) && (node.operator === ts4__default.default.SyntaxKind.PlusPlusToken || node.operator === ts4__default.default.SyntaxKind.MinusMinusToken)
1929
- ) {
1930
- recordIfIdentifierTarget(node.operand, assignedNames);
2023
+ const { operator, operand } = node;
2024
+ if (operator === ts.SyntaxKind.PlusPlusToken || operator === ts.SyntaxKind.MinusMinusToken) {
2025
+ recordIfIdentifierTarget(operand, assignedNames);
1931
2026
  return;
1932
2027
  }
1933
- if ((ts4__default.default.isForOfStatement(node) || ts4__default.default.isForInStatement(node)) && !ts4__default.default.isVariableDeclarationList(node.initializer)) {
2028
+ if ((ts.isForOfStatement(node) || ts.isForInStatement(node)) && !ts.isVariableDeclarationList(node.initializer)) {
1934
2029
  recordIfIdentifierTarget(node.initializer, assignedNames);
1935
2030
  }
1936
2031
  }
1937
2032
  function recordDeclarationIntroduction(node, countDeclaration, constAliasCandidates) {
1938
- if (ts4__default.default.isVariableDeclaration(node) || ts4__default.default.isParameter(node)) {
2033
+ if (ts.isVariableDeclaration(node) || ts.isParameter(node)) {
1939
2034
  forEachBindingName(node.name, countDeclaration);
1940
- if (!ts4__default.default.isVariableDeclaration(node) || !ts4__default.default.isIdentifier(node.name)) return;
2035
+ if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name)) return;
1941
2036
  if (node.initializer === void 0) return;
1942
2037
  const initializer = unwrapParens(node.initializer);
1943
- const isConst = (ts4__default.default.getCombinedNodeFlags(node) & ts4__default.default.NodeFlags.Const) !== 0;
1944
- if (isConst && ts4__default.default.isIdentifier(initializer)) {
2038
+ const isConst = (ts.getCombinedNodeFlags(node) & ts.NodeFlags.Const) !== 0;
2039
+ if (isConst && ts.isIdentifier(initializer)) {
1945
2040
  constAliasCandidates.push({
1946
2041
  aliasName: node.name.text,
1947
2042
  baseName: initializer.text,
@@ -1950,7 +2045,7 @@ function recordDeclarationIntroduction(node, countDeclaration, constAliasCandida
1950
2045
  }
1951
2046
  return;
1952
2047
  }
1953
- if ((ts4__default.default.isFunctionDeclaration(node) || ts4__default.default.isClassDeclaration(node)) && node.name) {
2048
+ if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) {
1954
2049
  countDeclaration(node.name.text);
1955
2050
  }
1956
2051
  }
@@ -1964,9 +2059,9 @@ function collectDeclarationFacts(sourceFile) {
1964
2059
  function walk(node) {
1965
2060
  recordDeclarationIntroduction(node, countDeclaration, constAliasCandidates);
1966
2061
  recordAssignmentTargets(node, assignedNames);
1967
- ts4__default.default.forEachChild(node, walk);
2062
+ ts.forEachChild(node, walk);
1968
2063
  }
1969
- ts4__default.default.forEachChild(sourceFile, walk);
2064
+ ts.forEachChild(sourceFile, walk);
1970
2065
  return { declarationCounts, assignedNames, constAliasCandidates };
1971
2066
  }
1972
2067
  function resolveAliasTargets(candidates, declarationCounts, assignedNames, imports) {
@@ -1991,21 +2086,22 @@ function bindingElementKey(element) {
1991
2086
  if (element.propertyName === void 0) {
1992
2087
  return element.name.text;
1993
2088
  }
1994
- if (ts4__default.default.isIdentifier(element.propertyName) || ts4__default.default.isStringLiteral(element.propertyName)) {
2089
+ if (ts.isIdentifier(element.propertyName) || ts.isStringLiteral(element.propertyName)) {
1995
2090
  return element.propertyName.text;
1996
2091
  }
1997
- if (ts4__default.default.isComputedPropertyName(element.propertyName)) {
2092
+ if (ts.isComputedPropertyName(element.propertyName)) {
1998
2093
  const inner = element.propertyName.expression;
1999
- return ts4__default.default.isStringLiteralLike(inner) ? inner.text : inner;
2094
+ return ts.isStringLiteralLike(inner) ? inner.text : inner;
2000
2095
  }
2001
2096
  return element.propertyName;
2002
2097
  }
2003
2098
  function scanFileForDependencies(filePath, sourceText) {
2004
- const scriptKind = filePath.endsWith(".tsx") ? ts4__default.default.ScriptKind.TSX : ts4__default.default.ScriptKind.TS;
2005
- const sourceFile = ts4__default.default.createSourceFile(
2099
+ assertCompilerApi2(ts);
2100
+ const scriptKind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
2101
+ const sourceFile = ts.createSourceFile(
2006
2102
  filePath,
2007
2103
  sourceText,
2008
- ts4__default.default.ScriptTarget.Latest,
2104
+ ts.ScriptTarget.Latest,
2009
2105
  // Load-bearing, unlike before: `ts.getCombinedNodeFlags()` (used to tell
2010
2106
  // a `const` declaration apart from `let`/`var` when resolving alias
2011
2107
  // candidates) walks parent pointers internally. Flipping this to `false`
@@ -2017,9 +2113,9 @@ function scanFileForDependencies(filePath, sourceText) {
2017
2113
  const imports = /* @__PURE__ */ new Map();
2018
2114
  let hasWildcardReExport = false;
2019
2115
  for (const statement of sourceFile.statements) {
2020
- if (ts4__default.default.isImportDeclaration(statement)) {
2116
+ if (ts.isImportDeclaration(statement)) {
2021
2117
  collectImportBindings(statement, imports);
2022
- } else if (ts4__default.default.isExportDeclaration(statement) && !statement.exportClause && statement.moduleSpecifier) {
2118
+ } else if (ts.isExportDeclaration(statement) && !statement.exportClause && statement.moduleSpecifier) {
2023
2119
  hasWildcardReExport = true;
2024
2120
  }
2025
2121
  }
@@ -2050,7 +2146,7 @@ function scanFileForDependencies(filePath, sourceText) {
2050
2146
  for (const element of pattern.elements) {
2051
2147
  if (element.dotDotDotToken) {
2052
2148
  record(localName, { kind: "escape", via: "rest", ...positionOf(sourceFile, element) });
2053
- } else if (!ts4__default.default.isIdentifier(element.name)) {
2149
+ } else if (!ts.isIdentifier(element.name)) {
2054
2150
  record(localName, {
2055
2151
  kind: "escape",
2056
2152
  via: "nested-pattern",
@@ -2066,17 +2162,17 @@ function scanFileForDependencies(filePath, sourceText) {
2066
2162
  via: "computed-key",
2067
2163
  ...positionOf(sourceFile, element)
2068
2164
  });
2069
- ts4__default.default.forEachChild(key, visit);
2165
+ ts.forEachChild(key, visit);
2070
2166
  }
2071
2167
  }
2072
- if (element.initializer) ts4__default.default.forEachChild(element.initializer, visit);
2168
+ ts.forEachChild(element.initializer, visit);
2073
2169
  }
2074
2170
  }
2075
2171
  function tryRecordPropertyOrElementAccess(node) {
2076
- const isProperty = ts4__default.default.isPropertyAccessExpression(node);
2077
- if (!isProperty && !ts4__default.default.isElementAccessExpression(node)) return false;
2172
+ const isProperty = ts.isPropertyAccessExpression(node);
2173
+ if (!isProperty && !ts.isElementAccessExpression(node)) return false;
2078
2174
  const base = unwrapParens(node.expression);
2079
- if (!ts4__default.default.isIdentifier(base) || !imports.has(base.text)) return false;
2175
+ if (!ts.isIdentifier(base) || !imports.has(base.text)) return false;
2080
2176
  if (isProperty) {
2081
2177
  record(base.text, { kind: "member", member: node.name.text, ...positionOf(sourceFile, node) });
2082
2178
  return true;
@@ -2086,49 +2182,92 @@ function scanFileForDependencies(filePath, sourceText) {
2086
2182
  base.text,
2087
2183
  key !== void 0 ? { kind: "member", member: key, ...positionOf(sourceFile, node) } : { kind: "dynamic", ...positionOf(sourceFile, node) }
2088
2184
  );
2089
- ts4__default.default.forEachChild(node.argumentExpression, visit);
2185
+ ts.forEachChild(node.argumentExpression, visit);
2090
2186
  return true;
2091
2187
  }
2092
2188
  function visit(node) {
2093
- if (ts4__default.default.isImportDeclaration(node) || ts4__default.default.isExportDeclaration(node) || ts4__default.default.isVariableDeclaration(node) && handledDeclarations.has(node)) {
2189
+ if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node) || ts.isVariableDeclaration(node) && handledDeclarations.has(node)) {
2094
2190
  return;
2095
2191
  }
2096
- if (ts4__default.default.isVariableDeclaration(node) && ts4__default.default.isObjectBindingPattern(node.name) && node.initializer) {
2192
+ if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer) {
2097
2193
  const base = unwrapParens(node.initializer);
2098
- if (ts4__default.default.isIdentifier(base) && imports.has(base.text)) {
2194
+ if (ts.isIdentifier(base) && imports.has(base.text)) {
2099
2195
  recordObjectBindingAccesses(node.name, base.text);
2100
2196
  return;
2101
2197
  }
2102
2198
  }
2103
2199
  if (tryRecordPropertyOrElementAccess(node)) return;
2104
- if (ts4__default.default.isIdentifier(node) && imports.has(node.text)) {
2200
+ if (ts.isIdentifier(node) && imports.has(node.text)) {
2105
2201
  record(node.text, { kind: "reference", ...positionOf(sourceFile, node) });
2106
2202
  return;
2107
2203
  }
2108
- ts4__default.default.forEachChild(node, visit);
2204
+ ts.forEachChild(node, visit);
2109
2205
  }
2110
- ts4__default.default.forEachChild(sourceFile, visit);
2206
+ ts.forEachChild(sourceFile, visit);
2111
2207
  return { file: filePath, imports, accessesByLocalName: accesses, hasWildcardReExport };
2112
2208
  }
2113
2209
 
2210
+ // src/_ipc/generated-banner.ts
2211
+ function marker() {
2212
+ return "GENERATED FILE -- do not edit by hand";
2213
+ }
2214
+ function createGeneratedBanner(describe) {
2215
+ return {
2216
+ reportRegenerateHint: () => describe().reportRegenerateHint,
2217
+ generatedBanner: (format = "ts", regenerate = `Run \`${describe().cliCommand}\` to regenerate.`) => {
2218
+ const text = `${marker()}. ${regenerate}`;
2219
+ return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2220
+ },
2221
+ // Not a bare `startsWith`: a shebang, a `"use strict"` pragma or a license header pushes a real marker
2222
+ // off line one, and a stricter check would read a genuinely generated file as hand-written, which a
2223
+ // dependency scan would take as "a real consumer imports this" and so permanently mask an abandoned
2224
+ // contract. The first 20 non-empty lines clear every realistic preamble without scanning a whole file.
2225
+ // A line counts only when the marker opens a comment, as `generatedBanner` writes it, so code or prose that
2226
+ // merely quotes the marker is not mistaken for a generated file.
2227
+ isGeneratedFile: (content) => {
2228
+ let seen = 0;
2229
+ for (const [line] of content.matchAll(/[^\n]*/g)) {
2230
+ const text = line.trimStart();
2231
+ if (text === "") continue;
2232
+ if (text.startsWith(`// ${marker()}`) || text.startsWith(`<!-- ${marker()}`)) return true;
2233
+ seen += 1;
2234
+ if (seen === 20) break;
2235
+ }
2236
+ return false;
2237
+ },
2238
+ 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.",
2239
+ evidenceProjectionNote: (evidencePath) => {
2240
+ const { product, guideUrl } = describe();
2241
+ const concept = `Projected from ${product}'s Evidence Model (${guideUrl}), the same source every other generated artifact draws from.`;
2242
+ return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2243
+ }
2244
+ };
2245
+ }
2246
+
2114
2247
  // src/build/generated-banner.ts
2115
- function generatedFileMarker() {
2116
- return "GENERATED FILE";
2248
+ function envCap() {
2249
+ return {
2250
+ product: "env-cap",
2251
+ guideUrl: "https://github.com/MaverickCER/env-cap/blob/main/GUIDE.md",
2252
+ cliCommand: "npx env-cap",
2253
+ reportRegenerateHint: "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`."
2254
+ };
2117
2255
  }
2118
- function generatedBanner(format = "ts") {
2119
- const text = `${generatedFileMarker()} -- do not edit by hand. Run \`npx env-cap\` to regenerate.`;
2120
- return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2256
+ var banner = createGeneratedBanner(envCap);
2257
+ function reportRegenerateHint() {
2258
+ return banner.reportRegenerateHint();
2259
+ }
2260
+ function generatedBanner(format, regenerate) {
2261
+ return banner.generatedBanner(format, regenerate);
2121
2262
  }
2122
2263
  function isGeneratedFile(content) {
2123
- const nonEmptyLines = content.split("\n").filter((line) => line.trim().length > 0);
2124
- return nonEmptyLines.slice(0, 20).some((line) => line.includes(generatedFileMarker()));
2264
+ return banner.isGeneratedFile(content);
2125
2265
  }
2126
2266
  function evidenceDisclaimer() {
2127
- 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.";
2267
+ return banner.evidenceDisclaimer();
2128
2268
  }
2129
2269
  function evidenceProjectionNote(evidencePath) {
2130
- const concept = "Projected from env-cap's Evidence Model (ADR 0031/0038), the same source every other generated artifact draws from.";
2131
- return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2270
+ return banner.evidenceProjectionNote(evidencePath);
2132
2271
  }
2133
2272
 
2134
2273
  // src/build/dependency-graph.ts
@@ -2238,8 +2377,7 @@ async function buildDependencyGraph(contracts, scanFiles, readFile, context, sca
2238
2377
  for (const scan of scanResults) {
2239
2378
  for (const [localName, binding] of scan.imports) {
2240
2379
  const resolvedFile = await resolveImportSpecifier(scan.file, binding.specifier, context);
2241
- if (!resolvedFile) continue;
2242
- const building = byIdentity2.get(`${resolvedFile}#${binding.importedName}`);
2380
+ const building = byIdentity2.get(`${String(resolvedFile)}#${binding.importedName}`);
2243
2381
  if (!building) continue;
2244
2382
  building.imported = true;
2245
2383
  building.consumingFiles.add(scan.file);
@@ -2249,8 +2387,7 @@ async function buildDependencyGraph(contracts, scanFiles, readFile, context, sca
2249
2387
  for (const scan of scanResults) {
2250
2388
  for (const [, binding] of scan.imports) {
2251
2389
  const resolvedFile = await resolveImportSpecifier(scan.file, binding.specifier, context);
2252
- if (!resolvedFile) continue;
2253
- const targetScan = scanByFile.get(resolvedFile);
2390
+ const targetScan = scanByFile.get(String(resolvedFile));
2254
2391
  if (!targetScan?.hasWildcardReExport) continue;
2255
2392
  for (const building of byIdentity2.values()) {
2256
2393
  if (building.imported) continue;
@@ -2353,20 +2490,9 @@ async function buildDependencyModel(contracts, scanFiles, readFile, context, roo
2353
2490
  positions: info.positions.map((p) => relativizePosition2(root, p)),
2354
2491
  dynamicAccessAssertions: info.dynamicAccessAssertions
2355
2492
  })).sort((a, b) => a.key.localeCompare(b.key)),
2356
- // `.sort()` here (and the whole `.map(...).sort()` chain as one
2357
- // `MethodExpression` unit) is a defensive no-op, not a real gap:
2358
- // dependency-graph.ts's own `consumingFiles` is already
2359
- // `[...building.consumingFiles].sort()` before this projection ever
2360
- // sees it (see that file's own comment). Hand-verified: dropping this
2361
- // `.sort()` and running the real suite passes unchanged -- confirmed
2362
- // again 2026-09-18 against CI's own diagnostic mutation report, which
2363
- // flagged this exact `MethodExpression` mutant as Survived.
2364
- // Stryker disable next-line MethodExpression
2493
+ // Sorted after mapping to display paths: a file outside `root` (a package surface) shows as
2494
+ // `../...`, which can order differently from its absolute path.
2365
2495
  consumingFiles: [...contract.consumingFiles].map((f) => displayPath(root, f)).sort(),
2366
- // Same reasoning as `consumingFiles` just above -- the whole
2367
- // `.map(...).sort()` chain is a coarser-grained `MethodExpression`
2368
- // mutant target than the next-line one on `.sort()` alone just below.
2369
- // Stryker disable next-line MethodExpression
2370
2496
  ambiguousBarrelFiles: [...contract.ambiguousBarrelFiles].map((f) => displayPath(root, f)).sort(),
2371
2497
  dynamicAccessSites: contract.dynamicAccessSites.map((p) => relativizePosition2(root, p))
2372
2498
  }));
@@ -2520,30 +2646,11 @@ function renderManifest(contracts, outputFile) {
2520
2646
  for (const contract of sorted) {
2521
2647
  let localName = contract.exportName;
2522
2648
  if (usedNames.has(localName)) {
2523
- const maxSuffix = sorted.length + 16;
2524
- let found;
2525
- let passes = 0;
2526
- for (let suffix = 1; suffix <= maxSuffix; suffix++) {
2527
- passes++;
2528
- if (passes > maxSuffix) {
2529
- throw new Error(
2530
- // Stryker disable next-line StringLiteral
2531
- `renderManifest: exceeded ${String(maxSuffix)} attempts choosing a unique local import name for "${contract.exportName}" -- this should never happen and indicates an internal naming bug.`
2532
- );
2533
- }
2534
- const candidate = `${contract.exportName}_${suffix}`;
2535
- if (!usedNames.has(candidate)) {
2536
- found = candidate;
2537
- break;
2538
- }
2539
- }
2540
- if (found === void 0) {
2541
- throw new Error(
2542
- // Stryker disable next-line StringLiteral
2543
- `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.`
2544
- );
2545
- }
2546
- localName = found;
2649
+ const candidates = Array.from(
2650
+ { length: usedNames.size + 1 },
2651
+ (_, index) => `${contract.exportName}_${index + 1}`
2652
+ );
2653
+ localName = String(candidates.find((candidate) => !usedNames.has(candidate)));
2547
2654
  }
2548
2655
  usedNames.add(localName);
2549
2656
  referenceNames.push(localName);
@@ -2592,10 +2699,8 @@ function defaultExclude() {
2592
2699
  // inspect `exclude` directly, and as defense if that hardcoding ever
2593
2700
  // changes) -- hand-verified: emptying both and running the full
2594
2701
  // `vitest run` leaves all 1243 tests passing.
2595
- // Stryker disable next-line StringLiteral
2596
2702
  "**/node_modules/**",
2597
2703
  "**/dist/**",
2598
- // Stryker disable next-line StringLiteral
2599
2704
  "**/.git/**"
2600
2705
  ];
2601
2706
  }
@@ -2625,8 +2730,6 @@ async function generateEnvManifest(options) {
2625
2730
  const root = path6__default.default.resolve(options.root ?? process.cwd());
2626
2731
  const include = options.include ?? defaultInclude();
2627
2732
  const exclude = options.exclude ?? defaultExclude();
2628
- const packages = options.packages ?? [];
2629
- const onIncompatibility = options.onIncompatibility ?? "warn";
2630
2733
  const locationResult = resolveWithinRoot(
2631
2734
  root,
2632
2735
  options.location,
@@ -2640,10 +2743,10 @@ async function generateEnvManifest(options) {
2640
2743
  root,
2641
2744
  include,
2642
2745
  exclude,
2643
- packages,
2746
+ packages: options.packages,
2644
2747
  tsconfig: options.tsconfig
2645
2748
  });
2646
- const computed = computeManifest(root, linkResult, onIncompatibility);
2749
+ const computed = computeManifest(root, linkResult, options.onIncompatibility);
2647
2750
  if (computed.blocking.length > 0) throw new EnvManifestGenerationError(computed.blocking);
2648
2751
  await writeManifest(outputPath, computed.activeContracts, options.fs);
2649
2752
  return {
@@ -2783,7 +2886,7 @@ function renderParseWarnings(warnings) {
2783
2886
  }
2784
2887
  function renderUsageReport(computed) {
2785
2888
  const lines = [
2786
- generatedBanner("markdown"),
2889
+ generatedBanner("markdown", reportRegenerateHint()),
2787
2890
  "",
2788
2891
  `> ${evidenceDisclaimer()}`,
2789
2892
  "",
@@ -2791,7 +2894,7 @@ function renderUsageReport(computed) {
2791
2894
  "",
2792
2895
  "# Dependency & Ownership Report",
2793
2896
  "",
2794
- "_Produced by `env-cap --ownership`._",
2897
+ "_Produced by `generateUsageReport()` from `@maverickcer/env-cap/build`._",
2795
2898
  "",
2796
2899
  "Which feature owns each variable, which features consume that contract, and what the blast radius is if it changes.",
2797
2900
  "",
@@ -2803,7 +2906,7 @@ function renderUsageReport(computed) {
2803
2906
  ...renderAsserted(computed.asserted),
2804
2907
  ...renderParseWarnings(computed.parseWarnings)
2805
2908
  ];
2806
- return lines.join("\n").replace(/\n{3,}/g, "\n\n");
2909
+ return lines.join("\n");
2807
2910
  }
2808
2911
 
2809
2912
  // src/build/generate-usage.ts
@@ -2834,7 +2937,7 @@ async function computeScanSurface(root, exclude, origins, fs) {
2834
2937
  }
2835
2938
  return { scanFiles, scannedSurfaces };
2836
2939
  }
2837
- async function computeUsage(root, contracts, scanFiles, readFile, context, parseWarnings, scannedSurfaces, dynamicAccessAcknowledgments) {
2940
+ async function computeUsage(root, contracts, scanFiles, readFile, context, scannedSurfaces, dynamicAccessAcknowledgments) {
2838
2941
  const graph = await buildDependencyGraph(
2839
2942
  contracts,
2840
2943
  scanFiles,
@@ -2847,13 +2950,9 @@ async function computeUsage(root, contracts, scanFiles, readFile, context, parse
2847
2950
  const contractByIdentity = /* @__PURE__ */ new Map();
2848
2951
  for (const contract of contracts)
2849
2952
  contractByIdentity.set(`${contract.file}#${contract.exportName}`, contract);
2850
- const ownerFor = (file, exportName) => (
2851
- // Stryker disable next-line OptionalChaining
2852
- contractByIdentity.get(`${file}#${exportName}`)?.owner
2853
- );
2953
+ const ownerFor = (file, exportName) => mustGet(contractByIdentity, `${file}#${exportName}`).owner;
2854
2954
  const effectiveOwnerFor = (file, exportName, key) => {
2855
- const contract = contractByIdentity.get(`${file}#${exportName}`);
2856
- if (!contract) return void 0;
2955
+ const contract = mustGet(contractByIdentity, `${file}#${exportName}`);
2857
2956
  const variable = contract.variables.find((v) => v.key === key);
2858
2957
  return variable ? effectiveOwner(contract, variable) : contract.owner;
2859
2958
  };
@@ -2879,19 +2978,16 @@ async function computeUsage(root, contracts, scanFiles, readFile, context, parse
2879
2978
  const staleOrMissingCitationsFor = (contractName, file, exportName, key) => {
2880
2979
  const relativeFile = displayPath(root, file);
2881
2980
  const identity = dynamicAccessVariableIdentity(relativeFile, exportName, key);
2882
- const problems = [];
2883
- for (const a of dynamicAccessAcknowledgments?.get(identity) ?? []) {
2884
- if (a.acknowledgment === "fresh") continue;
2885
- problems.push({
2981
+ return (dynamicAccessAcknowledgments?.get(identity) ?? []).map(
2982
+ (a) => ({
2886
2983
  contractName,
2887
2984
  file: relativeFile,
2888
2985
  exportName,
2889
2986
  key,
2890
2987
  position: { file: a.file, line: a.line, column: a.column },
2891
2988
  acknowledgment: a.acknowledgment
2892
- });
2893
- }
2894
- return problems;
2989
+ })
2990
+ );
2895
2991
  };
2896
2992
  const unconsumedOwnedVariables = findings.unconsumedOwned.map(
2897
2993
  (f) => ({
@@ -2936,7 +3032,6 @@ async function computeUsage(root, contracts, scanFiles, readFile, context, parse
2936
3032
  unconsumedOwnedVariables,
2937
3033
  indeterminate,
2938
3034
  asserted,
2939
- parseWarnings,
2940
3035
  scannedSurfaces: graph.scannedSurfaces
2941
3036
  }
2942
3037
  };
@@ -2950,24 +3045,23 @@ async function generateUsageReport(options) {
2950
3045
  const root = path6__default.default.resolve(options.root ?? process.cwd());
2951
3046
  const include = options.include ?? defaultInclude();
2952
3047
  const exclude = options.exclude ?? defaultExclude();
2953
- const packages = options.packages ?? [];
2954
3048
  let reportPath;
2955
3049
  if (options.report) {
2956
- const result = resolveWithinRoot(
3050
+ const result2 = resolveWithinRoot(
2957
3051
  root,
2958
3052
  options.report.location,
2959
3053
  "report.location",
2960
3054
  "generateUsageReport"
2961
3055
  );
2962
- if (!result.ok) throw new EnvUsageAnalysisError([result.issue]);
2963
- reportPath = result.resolved;
3056
+ if (!result2.ok) throw new EnvUsageAnalysisError([result2.issue]);
3057
+ reportPath = result2.resolved;
2964
3058
  }
2965
3059
  const { readFileCached, linkResult, context, origins, packageWarnings, tsconfigWarnings } = await assembleProject({
2966
3060
  fs: options.fs,
2967
3061
  root,
2968
3062
  include,
2969
3063
  exclude,
2970
- packages,
3064
+ packages: options.packages,
2971
3065
  tsconfig: options.tsconfig
2972
3066
  });
2973
3067
  const { scanFiles, scannedSurfaces } = await computeScanSurface(
@@ -2982,11 +3076,14 @@ async function generateUsageReport(options) {
2982
3076
  scanFiles,
2983
3077
  readFileCached,
2984
3078
  context,
2985
- [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings],
2986
3079
  scannedSurfaces
2987
3080
  );
2988
- if (reportPath) await writeUsageReport(reportPath, computed.result, options.fs);
2989
- return { reportPath, ...computed.result };
3081
+ const result = {
3082
+ ...computed.result,
3083
+ parseWarnings: [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings]
3084
+ };
3085
+ if (reportPath) await writeUsageReport(reportPath, result, options.fs);
3086
+ return { reportPath, ...result };
2990
3087
  }
2991
3088
 
2992
3089
  // src/build/finding-model.ts
@@ -3300,107 +3397,132 @@ function groupVariablesByOwner(contracts, ownerOf) {
3300
3397
  }
3301
3398
  return byOwner;
3302
3399
  }
3303
- var configurationReference = defineEvidenceProjection({
3304
- // Stryker disable next-line ArrowFunction
3305
- disclaimer: () => evidenceDisclaimer(),
3306
- entries: (evidence) => {
3307
- const entries = [];
3308
- for (const contract of evidence.contract.contracts) {
3309
- for (const variable of contract.variables) {
3310
- entries.push({
3311
- file: contract.file,
3312
- exportName: contract.exportName,
3313
- contractName: contract.contractName,
3314
- key: variable.key,
3315
- description: variable.description,
3316
- owner: variable.owner ?? contract.owner,
3317
- sensitivity: variable.sensitivity ?? contract.sensitivity,
3318
- required: variable.required,
3319
- hasDefault: variable.hasDefault,
3320
- hasProcessor: variable.hasProcessor,
3321
- hasValidator: variable.hasValidator,
3322
- expiresAt: variable.expiresAt,
3323
- active: contract.active
3324
- });
3400
+ function configurationReference(evidence) {
3401
+ return projectConfigurationReference(evidence).value;
3402
+ }
3403
+ configurationReference.project = projectConfigurationReference;
3404
+ function projectConfigurationReference(evidence) {
3405
+ return defineEvidenceProjection(configurationReferenceSchema()).project(evidence);
3406
+ }
3407
+ function configurationReferenceSchema() {
3408
+ return {
3409
+ disclaimer: evidenceDisclaimer,
3410
+ entries: (evidence) => {
3411
+ const entries = [];
3412
+ for (const contract of evidence.contract.contracts) {
3413
+ for (const variable of contract.variables) {
3414
+ entries.push({
3415
+ file: contract.file,
3416
+ exportName: contract.exportName,
3417
+ contractName: contract.contractName,
3418
+ key: variable.key,
3419
+ description: variable.description,
3420
+ owner: variable.owner ?? contract.owner,
3421
+ sensitivity: variable.sensitivity ?? contract.sensitivity,
3422
+ required: variable.required,
3423
+ hasDefault: variable.hasDefault,
3424
+ hasProcessor: variable.hasProcessor,
3425
+ hasValidator: variable.hasValidator,
3426
+ expiresAt: variable.expiresAt,
3427
+ active: contract.active
3428
+ });
3429
+ }
3325
3430
  }
3431
+ return entries.sort(byContractThenKey);
3326
3432
  }
3327
- return entries.sort(byContractThenKey);
3328
- }
3329
- });
3330
- var ownershipSummary = defineEvidenceProjection({
3331
- // Stryker disable next-line ArrowFunction
3332
- disclaimer: () => evidenceDisclaimer(),
3333
- owners: (evidence) => {
3334
- const contracts = contractIndex(evidence.contract.contracts);
3335
- const nameOf = (file, exportName) => contracts.get(`${file}#${exportName}`)?.contractName ?? exportName;
3336
- const variablesByOwner = groupVariablesByOwner(
3337
- evidence.ownership.contracts,
3338
- (_contract, variable) => variable.owner
3339
- );
3340
- const contractsByOwner = /* @__PURE__ */ new Map();
3341
- for (const contract of evidence.ownership.contracts) {
3342
- if (contract.owner === void 0) continue;
3343
- const list = contractsByOwner.get(contract.owner) ?? [];
3344
- list.push(nameOf(contract.file, contract.exportName));
3345
- contractsByOwner.set(contract.owner, list);
3433
+ };
3434
+ }
3435
+ function ownershipSummary(evidence) {
3436
+ return projectOwnershipSummary(evidence).value;
3437
+ }
3438
+ ownershipSummary.project = projectOwnershipSummary;
3439
+ function projectOwnershipSummary(evidence) {
3440
+ return defineEvidenceProjection(ownershipSummarySchema()).project(evidence);
3441
+ }
3442
+ function ownershipSummarySchema() {
3443
+ return {
3444
+ disclaimer: evidenceDisclaimer,
3445
+ owners: (evidence) => {
3446
+ const contracts = contractIndex(evidence.contract.contracts);
3447
+ const nameOf = (file, exportName) => contracts.get(`${file}#${exportName}`)?.contractName ?? exportName;
3448
+ const variablesByOwner = groupVariablesByOwner(
3449
+ evidence.ownership.contracts,
3450
+ (_contract, variable) => variable.owner
3451
+ );
3452
+ const contractsByOwner = /* @__PURE__ */ new Map();
3453
+ for (const contract of evidence.ownership.contracts) {
3454
+ if (contract.owner === void 0) continue;
3455
+ const list = contractsByOwner.get(contract.owner) ?? [];
3456
+ list.push(nameOf(contract.file, contract.exportName));
3457
+ contractsByOwner.set(contract.owner, list);
3458
+ }
3459
+ const owners = /* @__PURE__ */ new Set([...variablesByOwner.keys(), ...contractsByOwner.keys()]);
3460
+ return [...owners].sort().map((owner) => ({
3461
+ owner,
3462
+ variables: (variablesByOwner.get(owner) ?? []).map(
3463
+ ({ contract, variable }) => `${nameOf(contract.file, contract.exportName)}.${variable.key}`
3464
+ ).sort(),
3465
+ contracts: (contractsByOwner.get(owner) ?? []).sort()
3466
+ }));
3467
+ },
3468
+ unowned: (evidence) => {
3469
+ const contracts = contractIndex(evidence.contract.contracts);
3470
+ return evidence.ownership.unownedVariables.map((ref) => {
3471
+ const contractName = contracts.get(`${ref.file}#${ref.exportName}`)?.contractName ?? ref.exportName;
3472
+ return `${contractName}.${ref.key}`;
3473
+ }).sort();
3346
3474
  }
3347
- const owners = /* @__PURE__ */ new Set([...variablesByOwner.keys(), ...contractsByOwner.keys()]);
3348
- return [...owners].sort().map((owner) => ({
3349
- owner,
3350
- variables: (variablesByOwner.get(owner) ?? []).map(
3351
- ({ contract, variable }) => `${nameOf(contract.file, contract.exportName)}.${variable.key}`
3352
- ).sort(),
3353
- contracts: (contractsByOwner.get(owner) ?? []).sort()
3354
- }));
3355
- },
3356
- unowned: (evidence) => {
3357
- const contracts = contractIndex(evidence.contract.contracts);
3358
- return evidence.ownership.unownedVariables.map((ref) => {
3359
- const contractName = contracts.get(`${ref.file}#${ref.exportName}`)?.contractName ?? ref.exportName;
3360
- return `${contractName}.${ref.key}`;
3361
- }).sort();
3362
- }
3363
- });
3364
- var expiringSoonReport = defineEvidenceProjection({
3365
- // Stryker disable next-line ArrowFunction
3366
- disclaimer: () => evidenceDisclaimer(),
3367
- entries: (evidence) => {
3368
- const contracts = contractIndex(evidence.contract.contracts);
3369
- const ownerByVariable = /* @__PURE__ */ new Map();
3370
- for (const contract of evidence.ownership.contracts)
3371
- for (const variable of contract.variables)
3372
- ownerByVariable.set(
3373
- `${contract.file}#${contract.exportName}#${variable.key}`,
3374
- variable.owner
3375
- );
3376
- return evidence.lifecycle.expiring.map((entry) => {
3377
- const contract = contracts.get(`${entry.file}#${entry.exportName}`);
3378
- const variable = entry.key === void 0 ? void 0 : contract?.variables.find((v) => v.key === entry.key);
3379
- return {
3380
- file: entry.file,
3381
- exportName: entry.exportName,
3382
- contractName: contract?.contractName ?? entry.exportName,
3383
- key: entry.key,
3384
- expiresAt: entry.expiresAt,
3385
- daysRemaining: entry.daysRemaining,
3386
- expired: entry.daysRemaining < 0,
3387
- refreshInstructions: variable?.refreshInstructions,
3388
- owner: entry.key === void 0 ? contract?.owner : ownerByVariable.get(`${entry.file}#${entry.exportName}#${entry.key}`) ?? contract?.owner
3389
- };
3390
- });
3391
- },
3392
- // Same static covered-mutant false-Survivor as the `disclaimer` arrows
3393
- // above -- hand-verified killed (mutating this whole arrow to `() =>
3394
- // undefined` fails the "expiredCount" assertions in every test above).
3395
- // Stryker disable next-line ArrowFunction
3396
- expiredCount: (evidence) => evidence.lifecycle.expiring.filter((e) => e.daysRemaining < 0).length
3397
- });
3475
+ };
3476
+ }
3477
+ function expiringSoonReport(evidence) {
3478
+ return projectExpiringSoonReport(evidence).value;
3479
+ }
3480
+ expiringSoonReport.project = projectExpiringSoonReport;
3481
+ function projectExpiringSoonReport(evidence) {
3482
+ return defineEvidenceProjection(expiringSoonReportSchema()).project(evidence);
3483
+ }
3484
+ function expiringSoonReportSchema() {
3485
+ return {
3486
+ disclaimer: evidenceDisclaimer,
3487
+ entries: (evidence) => {
3488
+ const contracts = contractIndex(evidence.contract.contracts);
3489
+ const ownerByVariable = /* @__PURE__ */ new Map();
3490
+ for (const contract of evidence.ownership.contracts)
3491
+ for (const variable of contract.variables)
3492
+ ownerByVariable.set(
3493
+ `${contract.file}#${contract.exportName}#${variable.key}`,
3494
+ variable.owner
3495
+ );
3496
+ return evidence.lifecycle.expiring.map((entry) => {
3497
+ const contract = contracts.get(`${entry.file}#${entry.exportName}`);
3498
+ const variable = contract?.variables.find((v) => v.key === entry.key);
3499
+ return {
3500
+ file: entry.file,
3501
+ exportName: entry.exportName,
3502
+ contractName: contract?.contractName ?? entry.exportName,
3503
+ key: entry.key,
3504
+ expiresAt: entry.expiresAt,
3505
+ daysRemaining: entry.daysRemaining,
3506
+ expired: entry.daysRemaining < 0,
3507
+ refreshInstructions: variable?.refreshInstructions,
3508
+ owner: entry.key === void 0 ? contract?.owner : ownerByVariable.get(`${entry.file}#${entry.exportName}#${entry.key}`) ?? contract?.owner
3509
+ };
3510
+ });
3511
+ },
3512
+ expiredCount: (evidence) => evidence.lifecycle.expiring.filter((e) => e.daysRemaining < 0).length
3513
+ };
3514
+ }
3398
3515
 
3399
3516
  // src/build/docs.ts
3400
3517
  function parseIsoDate(value) {
3401
3518
  const date = new Date(value);
3402
3519
  return Number.isNaN(date.getTime()) ? void 0 : date;
3403
3520
  }
3521
+ function parseExpiry(expiresAt) {
3522
+ const raw = String(expiresAt);
3523
+ const date = parseIsoDate(raw);
3524
+ return date && { raw, date };
3525
+ }
3404
3526
  var MS_PER_DAY = 864e5;
3405
3527
  function daysRemainingFrom(date, now) {
3406
3528
  return Math.ceil((date.getTime() - now.getTime()) / MS_PER_DAY);
@@ -3408,32 +3530,29 @@ function daysRemainingFrom(date, now) {
3408
3530
  function computeExpiringEntries(contracts, expiringWithinDays, now) {
3409
3531
  const entries = [];
3410
3532
  for (const contract of contracts) {
3411
- if (contract.expiresAt) {
3412
- const date = parseIsoDate(contract.expiresAt);
3413
- if (date) {
3414
- const daysRemaining = daysRemainingFrom(date, now);
3415
- if (daysRemaining <= expiringWithinDays) {
3416
- entries.push({
3417
- file: contract.file,
3418
- exportName: contract.exportName,
3419
- key: void 0,
3420
- expiresAt: contract.expiresAt,
3421
- daysRemaining
3422
- });
3423
- }
3533
+ const contractExpiry = parseExpiry(contract.expiresAt);
3534
+ if (contractExpiry) {
3535
+ const daysRemaining = daysRemainingFrom(contractExpiry.date, now);
3536
+ if (daysRemaining <= expiringWithinDays) {
3537
+ entries.push({
3538
+ file: contract.file,
3539
+ exportName: contract.exportName,
3540
+ key: void 0,
3541
+ expiresAt: contractExpiry.raw,
3542
+ daysRemaining
3543
+ });
3424
3544
  }
3425
3545
  }
3426
3546
  for (const variable of contract.variables) {
3427
- if (!variable.expiresAt) continue;
3428
- const date = parseIsoDate(variable.expiresAt);
3429
- if (!date) continue;
3430
- const daysRemaining = daysRemainingFrom(date, now);
3547
+ const expiry = parseExpiry(variable.expiresAt);
3548
+ if (!expiry) continue;
3549
+ const daysRemaining = daysRemainingFrom(expiry.date, now);
3431
3550
  if (daysRemaining <= expiringWithinDays) {
3432
3551
  entries.push({
3433
3552
  file: contract.file,
3434
3553
  exportName: contract.exportName,
3435
3554
  key: variable.key,
3436
- expiresAt: variable.expiresAt,
3555
+ expiresAt: expiry.raw,
3437
3556
  daysRemaining
3438
3557
  });
3439
3558
  }
@@ -3484,7 +3603,7 @@ function buildCatalog(contracts) {
3484
3603
  function extractPreviouslyDocumentedKeys(previousContent) {
3485
3604
  const keys = /* @__PURE__ */ new Set();
3486
3605
  for (const match of previousContent.matchAll(/^### `([A-Za-z_][A-Za-z0-9_]*)`$/gm)) {
3487
- if (match[1]) keys.add(match[1]);
3606
+ keys.add(String(match[1]));
3488
3607
  }
3489
3608
  return keys;
3490
3609
  }
@@ -3524,7 +3643,7 @@ function computeChangeSummary(contracts, previousContent) {
3524
3643
  };
3525
3644
  }
3526
3645
  function slugify(text) {
3527
- return text.toLowerCase().replace(/[^a-z0-9_]+/g, "-").replace(/^-+|-+$/g, "") || "section";
3646
+ return text.toLowerCase().replace(/[^a-z0-9_]+/g, "-").replace(/^-|-$/g, "") || "section";
3528
3647
  }
3529
3648
  var AnchorRegistry = class {
3530
3649
  constructor() {
@@ -3541,16 +3660,24 @@ var AnchorRegistry = class {
3541
3660
  this.assigned.set(target, anchor);
3542
3661
  return anchor;
3543
3662
  }
3663
+ /** The anchor an earlier {@link anchorFor} call assigned to `target`; throws if there was none. */
3664
+ anchorOf(target) {
3665
+ return mustGet(this.assigned, target);
3666
+ }
3544
3667
  };
3545
3668
  function mdLink(text, anchor) {
3546
3669
  return `[${text}](#${anchor})`;
3547
3670
  }
3671
+ function sortedByKey(items) {
3672
+ const byKey = new Map(items.map((item) => [item.key, item]));
3673
+ return [...byKey.keys()].sort().map((key) => mustGet(byKey, key));
3674
+ }
3548
3675
  function sortedContracts(contracts) {
3549
3676
  return [...contracts].sort((a, b) => a.contractName.localeCompare(b.contractName));
3550
3677
  }
3551
3678
  function renderHeader(contracts, options, anchors, hasOwnership, hasDuplicates, hasLifecycle) {
3552
3679
  const lines = [
3553
- generatedBanner("markdown"),
3680
+ generatedBanner("markdown", reportRegenerateHint()),
3554
3681
  "",
3555
3682
  `> ${evidenceDisclaimer()}`,
3556
3683
  "",
@@ -3558,7 +3685,7 @@ function renderHeader(contracts, options, anchors, hasOwnership, hasDuplicates,
3558
3685
  "",
3559
3686
  "# Environment Variables",
3560
3687
  "",
3561
- "_Produced by `env-cap --docs`._",
3688
+ "_Produced by `generateDocumentation()` from `@maverickcer/env-cap/build`._",
3562
3689
  "",
3563
3690
  `_Generated ${options.generatedAt.toISOString()}_`,
3564
3691
  ""
@@ -3601,7 +3728,7 @@ function renderCatalog(contracts, anchors, undocumented) {
3601
3728
  );
3602
3729
  }
3603
3730
  for (const contract of sortedContracts(contracts)) {
3604
- lines.push(`<a id="${anchors.anchorFor(contract, `contract-${contract.contractName}`)}"></a>`);
3731
+ lines.push(`<a id="${anchors.anchorOf(contract)}"></a>`);
3605
3732
  lines.push(`## ${contract.contractName}`, "", `Source: \`${contract.file}\``);
3606
3733
  if (undocumentedByIdentity.has(`${contract.file}#${contract.exportName}`)) {
3607
3734
  lines.push("", "> \u26A0\uFE0F **Undocumented.** No `documentEnv()` call is linked to this contract.");
@@ -3626,10 +3753,8 @@ function renderCatalog(contracts, anchors, undocumented) {
3626
3753
  }
3627
3754
  }
3628
3755
  lines.push("");
3629
- for (const variable of [...contract.variables].sort((a, b) => a.key < b.key ? -1 : 1)) {
3630
- lines.push(
3631
- `<a id="${anchors.anchorFor(variable, `${contract.contractName}-${variable.key}`)}"></a>`
3632
- );
3756
+ for (const variable of sortedByKey(contract.variables)) {
3757
+ lines.push(`<a id="${anchors.anchorOf(variable)}"></a>`);
3633
3758
  lines.push(`### \`${variable.key}\``, "");
3634
3759
  if (variable.description) lines.push(variable.description, "");
3635
3760
  if (!variable.documented) lines.push("> \u26A0\uFE0F **Undocumented.**", "");
@@ -3742,18 +3867,17 @@ function renderLifecycleReport(contracts, anchors, expiringWithinDays, now) {
3742
3867
  const owner = effectiveOwner(contract, variable);
3743
3868
  if (variable.expiresAt === void 0 && owner === void 0 && variable.refreshInstructions === void 0)
3744
3869
  continue;
3745
- const expiresAt = variable.expiresAt;
3746
- const expiry = expiresAt ? parseIsoDate(expiresAt) : void 0;
3747
- let expiresCell = expiresAt ?? "--";
3748
- if (expiry && expiresAt) {
3749
- const daysRemaining = daysRemainingFrom(expiry, now);
3870
+ const expiry = parseExpiry(variable.expiresAt);
3871
+ let expiresCell = variable.expiresAt ?? "--";
3872
+ if (expiry) {
3873
+ const daysRemaining = daysRemainingFrom(expiry.date, now);
3750
3874
  if (daysRemaining < 0)
3751
- expiresCell = `${expiresAt} (**expired ${Math.abs(daysRemaining)}d ago**)`;
3875
+ expiresCell = `${expiry.raw} (**expired ${Math.abs(daysRemaining)}d ago**)`;
3752
3876
  else if (daysRemaining <= expiringWithinDays)
3753
- expiresCell = `${expiresAt} (**${daysRemaining}d remaining**)`;
3877
+ expiresCell = `${expiry.raw} (**${daysRemaining}d remaining**)`;
3754
3878
  }
3755
3879
  rows.push(
3756
- `| ${mdLink(`\`${variable.key}\``, anchors.anchorFor(variable, `${contract.contractName}-${variable.key}`))} | ${owner ?? "--"} | ${expiresCell} | ${variable.refreshInstructions ?? "--"} |`
3880
+ `| ${mdLink(`\`${variable.key}\``, anchors.anchorOf(variable))} | ${owner ?? "--"} | ${expiresCell} | ${variable.refreshInstructions ?? "--"} |`
3757
3881
  );
3758
3882
  }
3759
3883
  }
@@ -3869,7 +3993,14 @@ function renderDocs(contracts, options) {
3869
3993
  );
3870
3994
  const catalog = renderCatalog(sorted, anchors, options.undocumentedContracts);
3871
3995
  const security = renderSecurityReview(sorted, options, options.generatedAt);
3872
- return [...header, ...catalog, ...ownership, ...dependencyLines, ...lifecycleLines, ...security].join("\n").replace(/\n{3,}/g, "\n\n");
3996
+ return [
3997
+ ...header,
3998
+ ...catalog,
3999
+ ...ownership,
4000
+ ...dependencyLines,
4001
+ ...lifecycleLines,
4002
+ ...security
4003
+ ].join("\n");
3873
4004
  }
3874
4005
  function normalizeDocsForComparison(content) {
3875
4006
  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");
@@ -3908,9 +4039,9 @@ function groupByKey(contracts) {
3908
4039
  const byKey = /* @__PURE__ */ new Map();
3909
4040
  for (const contract of contracts) {
3910
4041
  for (const variable of contract.variables) {
3911
- const list = byKey.get(variable.key) ?? [];
3912
- list.push({ contract, variable });
3913
- byKey.set(variable.key, list);
4042
+ const existing = byKey.get(variable.key);
4043
+ if (existing === void 0) byKey.set(variable.key, [{ contract, variable }]);
4044
+ else existing.push({ contract, variable });
3914
4045
  }
3915
4046
  }
3916
4047
  return byKey;
@@ -3918,7 +4049,6 @@ function groupByKey(contracts) {
3918
4049
  function renderEnvExample(contracts, reconciliationHeader = []) {
3919
4050
  const sorted = [...contracts].sort((a, b) => a.file.localeCompare(b.file));
3920
4051
  const active = sorted.filter((c) => c.active);
3921
- const inactive = sorted.filter((c) => !c.active);
3922
4052
  const lines = [
3923
4053
  "# AUTO-GENERATED EXAMPLE FILE.",
3924
4054
  "# Copy to .env and fill in real values. Do not commit .env."
@@ -3930,12 +4060,11 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
3930
4060
  "# still written to this file regardless of its context."
3931
4061
  );
3932
4062
  }
3933
- if (reconciliationHeader.length > 0) lines.push(...reconciliationHeader);
4063
+ lines.push(...reconciliationHeader);
3934
4064
  lines.push("");
3935
4065
  const activeByKey = groupByKey(active);
3936
4066
  for (const key of [...activeByKey.keys()].sort()) {
3937
4067
  const [first, ...rest] = mustGet(activeByKey, key);
3938
- if (first === void 0) continue;
3939
4068
  lines.push(...renderVariableLines(first.variable));
3940
4069
  for (const dup of rest) {
3941
4070
  lines.push(
@@ -3946,11 +4075,10 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
3946
4075
  );
3947
4076
  }
3948
4077
  }
3949
- const inactiveByKey = groupByKey(inactive);
4078
+ const inactiveByKey = groupByKey(sorted);
3950
4079
  for (const key of [...inactiveByKey.keys()].sort()) {
3951
4080
  if (activeByKey.has(key)) continue;
3952
4081
  const [first] = mustGet(inactiveByKey, key);
3953
- if (first === void 0) continue;
3954
4082
  lines.push(
3955
4083
  ...renderVariableLines(first.variable, {
3956
4084
  commented: true,
@@ -3958,13 +4086,12 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
3958
4086
  })
3959
4087
  );
3960
4088
  }
3961
- return lines.join("\n").replace(/\n+$/, "\n");
4089
+ return lines.join("\n");
3962
4090
  }
3963
4091
  function extractDeclaredVariables(source) {
3964
4092
  const names = [];
3965
4093
  for (const line of source.split("\n")) {
3966
4094
  const trimmed = line.trim();
3967
- if (!trimmed || trimmed.startsWith("#")) continue;
3968
4095
  const match = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(trimmed);
3969
4096
  if (match?.[1]) names.push(match[1]);
3970
4097
  }
@@ -3974,9 +4101,7 @@ function extractCommentedVariables(source) {
3974
4101
  const names = [];
3975
4102
  for (const line of source.split("\n")) {
3976
4103
  const trimmed = line.trim();
3977
- if (!trimmed.startsWith("#")) continue;
3978
- const withoutHash = trimmed.replace(/^#+\s*/, "");
3979
- const match = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(withoutHash);
4104
+ const match = /^#+\s*([A-Za-z_][A-Za-z0-9_]*)=/.exec(trimmed);
3980
4105
  if (match?.[1]) names.push(match[1]);
3981
4106
  }
3982
4107
  return names;
@@ -4058,7 +4183,7 @@ function collectVariableNames(contracts) {
4058
4183
  }
4059
4184
  function overrideVariable(variable, overrides) {
4060
4185
  const override = overrides[variable.key];
4061
- const date = override === void 0 ? void 0 : parseIsoDate(override);
4186
+ const date = parseIsoDate(String(override));
4062
4187
  return {
4063
4188
  ...variable,
4064
4189
  expiresAt: date ? override : variable.expiresAt,
@@ -4080,16 +4205,14 @@ async function resolveLiveExpirationDates(contracts, liveExpirationDates) {
4080
4205
 
4081
4206
  // src/build/generate-documentation.ts
4082
4207
  var DEFAULT_EXPIRING_WITHIN_DAYS = 30;
4083
- var STANDARD_SENSITIVITY_LEVELS = /* @__PURE__ */ new Set([
4084
- "secret",
4085
- "credential",
4086
- "pii",
4087
- "config"
4088
- ]);
4208
+ function standardSensitivityLevels() {
4209
+ return ["secret", "credential", "pii", "config"];
4210
+ }
4211
+ var STANDARD_SENSITIVITY_LEVELS = new Set(standardSensitivityLevels());
4089
4212
  function findNonstandardSensitivityLevels(contracts) {
4090
4213
  const entries = [];
4091
4214
  for (const contract of contracts) {
4092
- if (contract.sensitivity !== void 0 && !STANDARD_SENSITIVITY_LEVELS.has(contract.sensitivity))
4215
+ if (contract.sensitivity !== void 0 && !standardSensitivityLevels().includes(contract.sensitivity))
4093
4216
  entries.push({
4094
4217
  file: contract.file,
4095
4218
  exportName: contract.exportName,
@@ -4098,7 +4221,7 @@ function findNonstandardSensitivityLevels(contracts) {
4098
4221
  });
4099
4222
  for (const variable of [...contract.variables].sort((a, b) => a.key.localeCompare(b.key))) {
4100
4223
  if (variable.sensitivity === void 0) continue;
4101
- if (STANDARD_SENSITIVITY_LEVELS.has(variable.sensitivity)) continue;
4224
+ if (standardSensitivityLevels().includes(variable.sensitivity)) continue;
4102
4225
  entries.push({
4103
4226
  file: contract.file,
4104
4227
  exportName: contract.exportName,
@@ -4139,36 +4262,20 @@ async function writeDocumentation(docsPath, envExamplePath, root, contracts, con
4139
4262
  undocumentedContracts: documentation.undocumentedContracts.map(
4140
4263
  (ref) => relativizeRef(root, ref)
4141
4264
  ),
4142
- // `RenderDocsOptions.undocumentedVariables` is consumed by `renderDocs()`
4143
- // ONLY via `.length` (the security-review counter) -- never by content
4144
- // or identity, unlike its `undocumentedContracts` sibling above (matched
4145
- // by identity against the catalog for the "Undocumented." marker).
4146
- // `.map()` always preserves length regardless of what each element
4147
- // transforms to, so this specific `relativizeRef()` call's own output is
4148
- // unobservable through this call site. Hand-verified: mapping every
4149
- // entry to `undefined` instead and running the full `vitest run` leaves
4150
- // all tests passing.
4151
- // Stryker disable next-line ArrowFunction
4152
- undocumentedVariables: documentation.undocumentedVariables.map(
4153
- (ref) => relativizeRef(root, ref)
4154
- ),
4265
+ undocumentedVariables: documentation.undocumentedVariables,
4155
4266
  generatedAt,
4156
4267
  previousContent
4157
4268
  });
4158
4269
  await fs.mkdir(path6__default.default.dirname(docsPath), { recursive: true });
4159
4270
  await fs.writeFile(docsPath, docsSource, "utf8");
4160
4271
  const envExample = envExamplePath ? (
4161
- // exactOptionalPropertyTypes: omit the key rather than set it to
4162
- // `undefined` when the caller didn't supply one. writeEnvExample
4163
- // itself does `options.onExisting ?? "keep-sibling"`, so passing
4164
- // `onExisting: undefined` explicitly (what always-spreading here
4165
- // would do) is behaviorally identical to omitting the key.
4166
- // Hand-verified: forcing this guard to `true` and running the real
4167
- // suite passes unchanged.
4168
- await writeEnvExample(contracts, envExamplePath, fs, {
4169
- // Stryker disable next-line ConditionalExpression
4170
- ...envExampleOnExisting === void 0 ? {} : { onExisting: envExampleOnExisting }
4171
- })
4272
+ // `exactOptionalPropertyTypes` rejects an explicit `undefined`, so the key is omitted when unset.
4273
+ await writeEnvExample(
4274
+ contracts,
4275
+ envExamplePath,
4276
+ fs,
4277
+ envExampleOnExisting && { onExisting: envExampleOnExisting }
4278
+ )
4172
4279
  ) : void 0;
4173
4280
  return { envExample };
4174
4281
  }
@@ -4176,7 +4283,6 @@ async function generateDocumentation(options) {
4176
4283
  const root = path6__default.default.resolve(options.root ?? process.cwd());
4177
4284
  const include = options.include ?? defaultInclude();
4178
4285
  const exclude = options.exclude ?? defaultExclude();
4179
- const packages = options.packages ?? [];
4180
4286
  const expiringWithinDays = options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS;
4181
4287
  const docsLocationResult = resolveWithinRoot(
4182
4288
  root,
@@ -4202,7 +4308,7 @@ async function generateDocumentation(options) {
4202
4308
  root,
4203
4309
  include,
4204
4310
  exclude,
4205
- packages,
4311
+ packages: options.packages,
4206
4312
  tsconfig: options.tsconfig
4207
4313
  });
4208
4314
  const docsContracts = await resolveLiveExpirationDates(
@@ -4256,7 +4362,7 @@ function parseRotationPeriodDays(value) {
4256
4362
  if (plain) {
4257
4363
  const amount = Number(plain[1]);
4258
4364
  if (amount > 0) {
4259
- const unit = (plain[2] ?? "").toLowerCase();
4365
+ const unit = String(plain[2]).toLowerCase();
4260
4366
  switch (unit) {
4261
4367
  case "day":
4262
4368
  case "days":
@@ -4289,18 +4395,14 @@ function parseRotationPeriodDays(value) {
4289
4395
  }
4290
4396
  function computeRotationStatus(variable, now) {
4291
4397
  if (!hasRotationData(variable)) return "undeclared";
4292
- if (variable.expiresAt !== void 0) {
4293
- const expiry = parseIsoDate(variable.expiresAt);
4294
- if (expiry !== void 0 && expiry.getTime() < now.getTime()) return "expired";
4295
- }
4398
+ const expiry = parseIsoDate(String(variable.expiresAt));
4399
+ if (expiry !== void 0 && expiry.getTime() < now.getTime()) return "expired";
4296
4400
  if (variable.rotationPeriod !== void 0) {
4297
- if (variable.lastRotatedAt !== void 0) {
4298
- const lastRotated = parseIsoDate(variable.lastRotatedAt);
4299
- const periodDays = parseRotationPeriodDays(variable.rotationPeriod);
4300
- if (lastRotated !== void 0 && lastRotated.getTime() <= now.getTime() && periodDays !== void 0) {
4301
- const dueDate = lastRotated.getTime() + periodDays * MS_PER_DAY2;
4302
- return dueDate < now.getTime() ? "overdue" : "compliant";
4303
- }
4401
+ const lastRotated = parseIsoDate(String(variable.lastRotatedAt));
4402
+ const periodDays = parseRotationPeriodDays(variable.rotationPeriod);
4403
+ if (lastRotated !== void 0 && lastRotated.getTime() <= now.getTime() && periodDays !== void 0) {
4404
+ const dueDate = lastRotated.getTime() + periodDays * MS_PER_DAY2;
4405
+ return dueDate < now.getTime() ? "overdue" : "compliant";
4304
4406
  }
4305
4407
  return "overdue";
4306
4408
  }
@@ -4382,7 +4484,7 @@ function buildOwnershipModel(contracts, root) {
4382
4484
 
4383
4485
  // src/build/tool-version.ts
4384
4486
  function readToolVersion() {
4385
- return "0.5.3";
4487
+ return "0.7.0";
4386
4488
  }
4387
4489
 
4388
4490
  // src/build/generate-evidence.ts
@@ -4390,7 +4492,6 @@ async function generateEvidenceModel(options) {
4390
4492
  const root = path6__default.default.resolve(options.root ?? process.cwd());
4391
4493
  const include = options.include ?? defaultInclude();
4392
4494
  const exclude = options.exclude ?? defaultExclude();
4393
- const packages = options.packages ?? [];
4394
4495
  const expiringWithinDays = options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS;
4395
4496
  let snapshotPath;
4396
4497
  if (options.previousSnapshotLocation !== void 0) {
@@ -4408,10 +4509,10 @@ async function generateEvidenceModel(options) {
4408
4509
  root,
4409
4510
  include,
4410
4511
  exclude,
4411
- packages,
4512
+ packages: options.packages,
4412
4513
  tsconfig: options.tsconfig
4413
4514
  });
4414
- const { readFileCached, linkResult, context, origins, packageWarnings, tsconfigWarnings } = assembled;
4515
+ const { readFileCached, linkResult, context, origins } = assembled;
4415
4516
  const generatedAt = /* @__PURE__ */ new Date();
4416
4517
  const activeContracts = linkResult.contracts.filter((c) => c.active);
4417
4518
  const lifecycleContracts = options.liveExpirationDates ? await resolveLiveExpirationDates(linkResult.contracts, options.liveExpirationDates) : linkResult.contracts;
@@ -4465,8 +4566,6 @@ async function generateEvidenceModel(options) {
4465
4566
  scanFiles,
4466
4567
  readFileCached,
4467
4568
  context,
4468
- // Stryker disable next-line ArrayDeclaration
4469
- [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings],
4470
4569
  scannedSurfaces,
4471
4570
  evidenceChanges?.dynamicAccessAcknowledgments
4472
4571
  );
@@ -4479,12 +4578,7 @@ async function generateEvidenceModel(options) {
4479
4578
  unresolvedConsumers: usageComputed.result.unresolvedConsumers,
4480
4579
  unconsumedOwnedVariables: usageComputed.result.unconsumedOwnedVariables,
4481
4580
  indeterminateOwnership: usageComputed.result.indeterminate,
4482
- // `buildFindingModel` (finding-model.ts) has its own `?? []` fallback
4483
- // on this exact same field, so even an `undefined` that slipped past
4484
- // this one (e.g. `??`-vs-`&&` on `evidenceChanges?.…`) is caught there
4485
- // identically -- belt-and-suspenders, not independently observable.
4486
- // Stryker disable next-line LogicalOperator
4487
- dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems ?? []
4581
+ dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems
4488
4582
  });
4489
4583
  const commit = options.commit ? await options.commit() : void 0;
4490
4584
  return deepFreeze({
@@ -4540,7 +4634,6 @@ async function getEvidenceModel(options) {
4540
4634
  const root = path6__default.default.resolve(options.root ?? process.cwd());
4541
4635
  const include = options.include ?? defaultInclude();
4542
4636
  const exclude = options.exclude ?? defaultExclude();
4543
- const packages = options.packages ?? [];
4544
4637
  const evidencePath = path6__default.default.resolve(root, options.location);
4545
4638
  const fingerprintPath = fingerprintPathFor(evidencePath);
4546
4639
  const recompute = async (missReason) => ({
@@ -4555,7 +4648,7 @@ async function getEvidenceModel(options) {
4555
4648
  root,
4556
4649
  include,
4557
4650
  exclude,
4558
- packages
4651
+ packages: options.packages
4559
4652
  });
4560
4653
  } catch (error) {
4561
4654
  return recompute(
@@ -4603,91 +4696,61 @@ function findingFiles(finding) {
4603
4696
  if (location.model === "change") return [location.path];
4604
4697
  return location.file === void 0 ? [] : [location.file];
4605
4698
  }
4699
+ function requestedPass(option) {
4700
+ return option === false ? void 0 : option;
4701
+ }
4606
4702
  async function computeArtifacts(options) {
4607
4703
  const root = path6__default.default.resolve(options.root ?? process.cwd());
4608
4704
  const include = options.include ?? defaultInclude();
4609
4705
  const exclude = options.exclude ?? defaultExclude();
4610
- const packages = options.packages ?? [];
4611
- const manifestOptions = options.manifest === false ? void 0 : options.manifest;
4612
- const docsOptions = options.docs === false ? void 0 : options.docs;
4613
- const usageOptions = options.usage === false ? void 0 : options.usage;
4614
- const evidenceOptions = options.evidence === false ? void 0 : options.evidence;
4706
+ const manifestOptions = requestedPass(options.manifest);
4707
+ const docsOptions = requestedPass(options.docs);
4708
+ const usageOptions = requestedPass(options.usage);
4709
+ const evidenceOptions = requestedPass(options.evidence);
4615
4710
  const pathIssues = [];
4616
- let manifestOutputPath;
4617
- if (manifestOptions) {
4618
- const result = resolveWithinRoot(
4619
- root,
4620
- manifestOptions.location,
4621
- "manifest.location",
4622
- "generateEnvArtifacts"
4623
- );
4624
- if (result.ok) manifestOutputPath = result.resolved;
4625
- else pathIssues.push(result.issue);
4626
- }
4627
- let docsPath;
4628
- let envExamplePath;
4629
- if (docsOptions) {
4630
- const result = resolveWithinRoot(
4631
- root,
4632
- docsOptions.location,
4633
- "docs.location",
4634
- "generateEnvArtifacts"
4635
- );
4636
- if (result.ok) docsPath = result.resolved;
4637
- else pathIssues.push(result.issue);
4638
- if (docsOptions.envExample) {
4639
- const exampleResult = resolveWithinRoot(
4640
- root,
4641
- docsOptions.envExample.location,
4642
- "docs.envExample.location",
4643
- "generateEnvArtifacts"
4644
- );
4645
- if (exampleResult.ok) envExamplePath = exampleResult.resolved;
4646
- else pathIssues.push(exampleResult.issue);
4647
- }
4648
- }
4649
- let usageReportPath;
4650
- if (usageOptions?.report) {
4651
- const result = resolveWithinRoot(
4652
- root,
4653
- usageOptions.report.location,
4654
- "usage.report.location",
4655
- "generateEnvArtifacts"
4656
- );
4657
- if (result.ok) usageReportPath = result.resolved;
4658
- else pathIssues.push(result.issue);
4659
- }
4660
- let evidencePath;
4661
- if (evidenceOptions) {
4662
- const result = resolveWithinRoot(
4663
- root,
4664
- evidenceOptions.location,
4665
- "evidence.location",
4666
- "generateEnvArtifacts"
4667
- );
4668
- if (result.ok) evidencePath = result.resolved;
4669
- else pathIssues.push(result.issue);
4670
- }
4711
+ const resolveOutput = (location, label) => {
4712
+ const result = resolveWithinRoot(root, location, label, "generateEnvArtifacts");
4713
+ if (result.ok) return result.resolved;
4714
+ pathIssues.push(result.issue);
4715
+ return location;
4716
+ };
4717
+ const manifestTarget = manifestOptions && {
4718
+ options: manifestOptions,
4719
+ outputPath: resolveOutput(manifestOptions.location, "manifest.location")
4720
+ };
4721
+ const docsTarget = docsOptions && {
4722
+ options: docsOptions,
4723
+ path: resolveOutput(docsOptions.location, "docs.location"),
4724
+ envExamplePath: docsOptions.envExample ? resolveOutput(docsOptions.envExample.location, "docs.envExample.location") : void 0
4725
+ };
4726
+ const usageTarget = usageOptions && {
4727
+ options: usageOptions,
4728
+ reportPath: usageOptions.report ? resolveOutput(usageOptions.report.location, "usage.report.location") : void 0
4729
+ };
4730
+ const evidencePath = evidenceOptions ? resolveOutput(evidenceOptions.location, "evidence.location") : void 0;
4671
4731
  if (pathIssues.length > 0) throw new EnvProjectGenerationError(pathIssues);
4672
4732
  const { readFileCached, linkResult, context, origins, packageWarnings, tsconfigWarnings } = await assembleProject({
4673
4733
  fs: options.fs,
4674
4734
  root,
4675
4735
  include,
4676
4736
  exclude,
4677
- packages,
4737
+ packages: options.packages,
4678
4738
  tsconfig: options.tsconfig
4679
4739
  });
4680
4740
  const generatedAt = /* @__PURE__ */ new Date();
4681
4741
  const activeContracts = linkResult.contracts.filter((c) => c.active);
4682
4742
  const liveExpirationContracts = options.liveExpirationDates ? await resolveLiveExpirationDates(linkResult.contracts, options.liveExpirationDates) : linkResult.contracts;
4683
- const docsContracts = docsOptions ? liveExpirationContracts : linkResult.contracts;
4743
+ const docsContracts = docsTarget ? liveExpirationContracts : linkResult.contracts;
4684
4744
  const blocking = [];
4685
- const manifestComputed = manifestOptions ? computeManifest(root, linkResult, manifestOptions.onIncompatibility ?? "warn") : void 0;
4686
- if (manifestComputed) blocking.push(...manifestComputed.blocking);
4745
+ const manifest = manifestTarget && {
4746
+ ...manifestTarget,
4747
+ computed: computeManifest(root, linkResult, manifestTarget.options.onIncompatibility)
4748
+ };
4749
+ if (manifest) blocking.push(...manifest.computed.blocking);
4687
4750
  const docsComputed = computeDocumentation(
4688
4751
  root,
4689
4752
  { ...linkResult, contracts: liveExpirationContracts },
4690
- docsOptions?.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4753
+ docsTarget?.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4691
4754
  generatedAt
4692
4755
  );
4693
4756
  const { scanFiles, scannedSurfaces } = await computeScanSurface(
@@ -4711,14 +4774,13 @@ async function computeArtifacts(options) {
4711
4774
  scanFiles,
4712
4775
  readFileCached,
4713
4776
  context,
4714
- [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings],
4715
4777
  scannedSurfaces,
4716
4778
  evidenceChanges?.dynamicAccessAcknowledgments
4717
4779
  );
4718
4780
  const ownership = buildOwnershipModel(linkResult.contracts, root);
4719
4781
  const lifecycle = buildLifecycleModel(
4720
4782
  liveExpirationContracts,
4721
- docsOptions?.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4783
+ docsTarget?.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4722
4784
  generatedAt,
4723
4785
  root
4724
4786
  );
@@ -4755,7 +4817,7 @@ async function computeArtifacts(options) {
4755
4817
  unresolvedConsumers: usageComputed.result.unresolvedConsumers,
4756
4818
  unconsumedOwnedVariables: usageComputed.result.unconsumedOwnedVariables,
4757
4819
  indeterminateOwnership: usageComputed.result.indeterminate,
4758
- dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems ?? []
4820
+ dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems
4759
4821
  });
4760
4822
  if (options.onUndocumented === "throw")
4761
4823
  blocking.push(...escalatedFindings(finding.findings, "documentation"));
@@ -4777,16 +4839,11 @@ async function computeArtifacts(options) {
4777
4839
  });
4778
4840
  return {
4779
4841
  root,
4780
- manifestOptions,
4781
- manifestOutputPath,
4782
- manifestComputed,
4783
- docsOptions,
4784
- docsPath,
4785
- envExamplePath,
4842
+ manifest,
4843
+ docs: docsTarget,
4786
4844
  docsComputed,
4787
4845
  docsContracts,
4788
- usageOptions,
4789
- usageReportPath,
4846
+ usage: usageTarget,
4790
4847
  usageComputed,
4791
4848
  evidencePath,
4792
4849
  evidence,
@@ -4799,16 +4856,11 @@ async function computeArtifacts(options) {
4799
4856
  async function generateEnvArtifacts(options) {
4800
4857
  const computed = await computeArtifacts(options);
4801
4858
  const {
4802
- manifestOptions,
4803
- manifestOutputPath,
4804
- manifestComputed,
4805
- docsOptions,
4806
- docsPath,
4807
- envExamplePath,
4859
+ manifest,
4860
+ docs,
4808
4861
  docsComputed,
4809
4862
  docsContracts,
4810
- usageOptions,
4811
- usageReportPath,
4863
+ usage,
4812
4864
  usageComputed,
4813
4865
  evidencePath,
4814
4866
  evidence,
@@ -4819,43 +4871,47 @@ async function generateEnvArtifacts(options) {
4819
4871
  generatedAt
4820
4872
  } = computed;
4821
4873
  if (blocking.length > 0) throw new EnvProjectGenerationError(blocking);
4874
+ const parseWarnings = [...packageWarnings, ...linkWarnings];
4822
4875
  let manifestResult;
4823
- if (manifestOptions && manifestComputed && manifestOutputPath) {
4824
- await writeManifest(manifestOutputPath, manifestComputed.activeContracts, options.fs);
4876
+ if (manifest) {
4877
+ await writeManifest(manifest.outputPath, manifest.computed.activeContracts, options.fs);
4825
4878
  manifestResult = {
4826
- outputPath: manifestOutputPath,
4827
- contracts: manifestComputed.contractSummaries,
4828
- warnings: manifestComputed.warnings,
4829
- parseWarnings: [...packageWarnings, ...linkWarnings]
4879
+ outputPath: manifest.outputPath,
4880
+ contracts: manifest.computed.contractSummaries,
4881
+ warnings: manifest.computed.warnings,
4882
+ parseWarnings
4830
4883
  };
4831
4884
  }
4832
4885
  let docsResult;
4833
- if (docsOptions && docsPath) {
4886
+ if (docs) {
4834
4887
  const { envExample } = await writeDocumentation(
4835
- docsPath,
4836
- envExamplePath,
4888
+ docs.path,
4889
+ docs.envExamplePath,
4837
4890
  root,
4838
4891
  docsContracts,
4839
4892
  docsComputed.contractModelContracts,
4840
4893
  docsComputed.documentation,
4841
- docsOptions.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4894
+ docs.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4842
4895
  generatedAt,
4843
4896
  options.fs,
4844
- docsOptions.envExample?.onExisting
4897
+ docs.options.envExample?.onExisting
4845
4898
  );
4846
4899
  docsResult = {
4847
- docsPath,
4900
+ docsPath: docs.path,
4848
4901
  envExample,
4849
4902
  contracts: docsComputed.contractSummaries,
4850
4903
  catalog: docsComputed.catalog,
4851
- parseWarnings: [...packageWarnings, ...linkWarnings],
4904
+ parseWarnings,
4852
4905
  documentation: docsComputed.documentation
4853
4906
  };
4854
4907
  }
4855
4908
  let usageResult;
4856
- if (usageOptions) {
4857
- if (usageReportPath) await writeUsageReport(usageReportPath, usageComputed.result, options.fs);
4858
- usageResult = { reportPath: usageReportPath, ...usageComputed.result };
4909
+ if (usage) {
4910
+ const usageReport = { ...usageComputed.result, parseWarnings };
4911
+ if (usage.reportPath !== void 0) {
4912
+ await writeUsageReport(usage.reportPath, usageReport, options.fs);
4913
+ }
4914
+ usageResult = { reportPath: usage.reportPath, ...usageReport };
4859
4915
  }
4860
4916
  if (evidencePath) {
4861
4917
  await writeEvidenceSnapshot(evidencePath, evidence, options.fs);
@@ -4864,7 +4920,7 @@ async function generateEnvArtifacts(options) {
4864
4920
  root,
4865
4921
  include: options.include ?? defaultInclude(),
4866
4922
  exclude: options.exclude ?? defaultExclude(),
4867
- packages: options.packages ?? []
4923
+ packages: options.packages
4868
4924
  });
4869
4925
  await writeEvidenceFingerprint(evidencePath, fingerprint, options.fs);
4870
4926
  }
@@ -4872,12 +4928,8 @@ async function generateEnvArtifacts(options) {
4872
4928
  }
4873
4929
 
4874
4930
  // src/build/check-artifacts.ts
4875
- async function readIfExists(filePath, fs) {
4876
- try {
4877
- return await fs.readFile(filePath, "utf8");
4878
- } catch {
4879
- return void 0;
4880
- }
4931
+ function readIfExists(filePath, fs) {
4932
+ return fs.readFile(filePath, "utf8").catch(() => void 0);
4881
4933
  }
4882
4934
  function normalizeEvidenceJsonForComparison(text) {
4883
4935
  try {
@@ -4903,46 +4955,38 @@ async function checkEnvArtifacts(options) {
4903
4955
  const c = await computeArtifacts(options);
4904
4956
  if (c.blocking.length > 0) throw new EnvProjectGenerationError(c.blocking);
4905
4957
  const findings = [];
4906
- if (c.manifestOptions && c.manifestComputed && c.manifestOutputPath) {
4907
- const expected = renderManifest(c.manifestComputed.activeContracts, c.manifestOutputPath);
4908
- findings.push(await compareTextArtifact("manifest", c.manifestOutputPath, expected, options.fs));
4958
+ if (c.manifest) {
4959
+ const expected = renderManifest(c.manifest.computed.activeContracts, c.manifest.outputPath);
4960
+ findings.push(
4961
+ await compareTextArtifact("manifest", c.manifest.outputPath, expected, options.fs)
4962
+ );
4909
4963
  }
4910
- if (c.docsOptions && c.docsPath) {
4911
- const previousContent = await readIfExists(c.docsPath, options.fs);
4964
+ if (c.docs) {
4965
+ const previousContent = await readIfExists(c.docs.path, options.fs);
4912
4966
  const expected = renderDocs(c.docsComputed.contractModelContracts, {
4913
- expiringWithinDays: c.docsOptions.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4967
+ expiringWithinDays: c.docs.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4914
4968
  undocumentedContracts: c.docsComputed.documentation.undocumentedContracts.map(
4915
4969
  (ref) => relativizeRef(c.root, ref)
4916
4970
  ),
4917
- // `RenderDocsOptions.undocumentedVariables` is consumed by `renderDocs()`
4918
- // ONLY via `.length` (the security-review counter), never by content
4919
- // or identity -- same equivalence already established for
4920
- // `generate-documentation.ts`'s identical call site. Hand-verified:
4921
- // mapping every entry to `undefined` instead and running the full
4922
- // `vitest run` leaves every test passing.
4923
- // Stryker disable ArrowFunction
4924
- undocumentedVariables: c.docsComputed.documentation.undocumentedVariables.map(
4925
- (ref) => relativizeRef(c.root, ref)
4926
- ),
4927
- // Stryker restore ArrowFunction
4971
+ undocumentedVariables: c.docsComputed.documentation.undocumentedVariables,
4928
4972
  generatedAt: c.generatedAt,
4929
4973
  previousContent
4930
4974
  });
4931
4975
  findings.push(
4932
4976
  await compareTextArtifact(
4933
4977
  "docs",
4934
- c.docsPath,
4978
+ c.docs.path,
4935
4979
  expected,
4936
4980
  options.fs,
4937
4981
  normalizeDocsForComparison
4938
4982
  )
4939
4983
  );
4940
- if (c.docsOptions.envExample && c.envExamplePath) {
4941
- const existing = await readIfExists(c.envExamplePath, options.fs);
4984
+ if (c.docs.envExamplePath !== void 0) {
4985
+ const existing = await readIfExists(c.docs.envExamplePath, options.fs);
4942
4986
  if (existing === void 0) {
4943
4987
  findings.push({
4944
4988
  artifact: "envExample",
4945
- path: c.envExamplePath,
4989
+ path: c.docs.envExamplePath,
4946
4990
  status: "missing",
4947
4991
  detail: "not yet generated"
4948
4992
  });
@@ -4954,7 +4998,7 @@ async function checkEnvArtifacts(options) {
4954
4998
  const driftCount = staleVariables.length + variablesToComment.length + variablesToAdd.length;
4955
4999
  findings.push({
4956
5000
  artifact: "envExample",
4957
- path: c.envExamplePath,
5001
+ path: c.docs.envExamplePath,
4958
5002
  status: driftCount > 0 ? "stale" : "ok",
4959
5003
  // exactOptionalPropertyTypes: omit the key entirely rather than
4960
5004
  // set it to `undefined` -- `detail` is absent when there's
@@ -4966,9 +5010,12 @@ async function checkEnvArtifacts(options) {
4966
5010
  }
4967
5011
  }
4968
5012
  }
4969
- if (c.usageOptions && c.usageReportPath) {
4970
- const expected = renderUsageReport(c.usageComputed.result);
4971
- findings.push(await compareTextArtifact("usage", c.usageReportPath, expected, options.fs));
5013
+ if (c.usage?.reportPath !== void 0) {
5014
+ const expected = renderUsageReport({
5015
+ ...c.usageComputed.result,
5016
+ parseWarnings: [...c.packageWarnings, ...c.linkWarnings]
5017
+ });
5018
+ findings.push(await compareTextArtifact("usage", c.usage.reportPath, expected, options.fs));
4972
5019
  }
4973
5020
  if (c.evidencePath) {
4974
5021
  const expected = JSON.stringify(c.evidence, null, 2);
@@ -4993,7 +5040,7 @@ function sarifLocations(finding) {
4993
5040
  const location = finding.location;
4994
5041
  const uri = location.model === "change" ? location.path : location.file;
4995
5042
  if (uri === void 0) return void 0;
4996
- const position = location.model === "change" ? void 0 : location.position;
5043
+ const { position } = location;
4997
5044
  return [
4998
5045
  {
4999
5046
  physicalLocation: {