@maverickcer/env-cap 0.5.3 → 0.6.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 (256) hide show
  1. package/README.md +11 -5
  2. package/dist/.dts/build/assemble-project.d.ts +1 -1
  3. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  4. package/dist/.dts/build/change-model.d.ts.map +1 -1
  5. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  6. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  7. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  8. package/dist/.dts/build/compiler-api.d.ts +15 -0
  9. package/dist/.dts/build/compiler-api.d.ts.map +1 -0
  10. package/dist/.dts/build/dependency-graph.d.ts +3 -1
  11. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  12. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  13. package/dist/.dts/build/discover.d.ts.map +1 -1
  14. package/dist/.dts/build/docs.d.ts +1 -1
  15. package/dist/.dts/build/docs.d.ts.map +1 -1
  16. package/dist/.dts/build/env-example.d.ts.map +1 -1
  17. package/dist/.dts/build/evidence-cache.d.ts +1 -1
  18. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  19. package/dist/.dts/build/evidence-model.d.ts +2 -2
  20. package/dist/.dts/build/evidence-snapshot.d.ts +25 -0
  21. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  22. package/dist/.dts/build/finding-model.d.ts +1 -1
  23. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  24. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  25. package/dist/.dts/build/generate-env-artifacts.d.ts +23 -8
  26. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  27. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  28. package/dist/.dts/build/generate-manifest.d.ts +1 -1
  29. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  30. package/dist/.dts/build/generate-usage.d.ts +3 -3
  31. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  32. package/dist/.dts/build/generated-banner.d.ts +15 -3
  33. package/dist/.dts/build/generated-banner.d.ts.map +1 -1
  34. package/dist/.dts/build/glob.d.ts.map +1 -1
  35. package/dist/.dts/build/index.d.ts +2 -2
  36. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  37. package/dist/.dts/build/link.d.ts.map +1 -1
  38. package/dist/.dts/build/literal-eval.d.ts +4 -3
  39. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  40. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  41. package/dist/.dts/build/manifest.d.ts.map +1 -1
  42. package/dist/.dts/build/parse.d.ts +12 -12
  43. package/dist/.dts/build/parse.d.ts.map +1 -1
  44. package/dist/.dts/build/reference-projections.d.ts +17 -3
  45. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  46. package/dist/.dts/build/resolution/resolve-import.d.ts +5 -0
  47. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  48. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +1 -1
  49. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  50. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +20 -2
  51. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  52. package/dist/.dts/build/sarif.d.ts.map +1 -1
  53. package/dist/.dts/build/scan-dependencies.d.ts +23 -0
  54. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  55. package/dist/.dts/build/types.d.ts +1 -1
  56. package/dist/.dts/build/typescript.d.ts +20 -0
  57. package/dist/.dts/build/typescript.d.ts.map +1 -0
  58. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  59. package/dist/.dts/cli/filesystem.d.ts +4 -0
  60. package/dist/.dts/cli/filesystem.d.ts.map +1 -1
  61. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  62. package/dist/.dts/eslint-plugin/index.d.ts +2 -2
  63. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  64. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  65. package/dist/.dts/evidence/index.d.ts +2 -2
  66. package/dist/.dts/helpers/index.d.ts +2 -2
  67. package/dist/.dts/helpers/processors.d.ts.map +1 -1
  68. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  69. package/dist/.dts/runtime/cache.d.ts +0 -3
  70. package/dist/.dts/runtime/cache.d.ts.map +1 -1
  71. package/dist/.dts/runtime/create.d.ts.map +1 -1
  72. package/dist/.dts/runtime/document.d.ts.map +1 -1
  73. package/dist/.dts/runtime/index.d.ts +2 -2
  74. package/dist/.dts/runtime/registry.d.ts.map +1 -1
  75. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  76. package/dist/{build-U326PI5A.js → build-H4KFV44Z.js} +501 -599
  77. package/dist/build-H4KFV44Z.js.map +1 -0
  78. package/dist/build.cjs +516 -607
  79. package/dist/build.cjs.map +1 -1
  80. package/dist/build.js +513 -605
  81. package/dist/build.js.map +1 -1
  82. package/dist/{chunk-BSTLSR2R.js → chunk-7GVPOHDU.js} +2 -2
  83. package/dist/chunk-7GVPOHDU.js.map +1 -0
  84. package/dist/cli/index.js +35 -41
  85. package/dist/cli/index.js.map +1 -1
  86. package/dist/eslint-plugin/index.cjs +15 -576
  87. package/dist/eslint-plugin/index.cjs.map +1 -1
  88. package/dist/eslint-plugin/index.js +15 -576
  89. package/dist/eslint-plugin/index.js.map +1 -1
  90. package/dist/evidence.cjs.map +1 -1
  91. package/dist/evidence.js.map +1 -1
  92. package/dist/helpers.cjs +4 -9
  93. package/dist/helpers.cjs.map +1 -1
  94. package/dist/helpers.js +4 -9
  95. package/dist/helpers.js.map +1 -1
  96. package/dist/index.cjs +11 -25
  97. package/dist/index.cjs.map +1 -1
  98. package/dist/index.js +11 -25
  99. package/dist/index.js.map +1 -1
  100. package/dist/node.cjs +10 -8
  101. package/dist/node.cjs.map +1 -1
  102. package/dist/node.js +10 -8
  103. package/dist/node.js.map +1 -1
  104. package/node_modules/@typescript/old/LICENSE.txt +55 -0
  105. package/node_modules/@typescript/old/README.md +50 -0
  106. package/node_modules/@typescript/old/SECURITY.md +39 -0
  107. package/node_modules/@typescript/old/ThirdPartyNoticeText.txt +193 -0
  108. package/node_modules/@typescript/old/bin/tsc +2 -0
  109. package/node_modules/@typescript/old/bin/tsserver +2 -0
  110. package/node_modules/@typescript/old/lib/_tsc.js +134465 -0
  111. package/node_modules/@typescript/old/lib/_tsserver.js +659 -0
  112. package/node_modules/@typescript/old/lib/_typingsInstaller.js +222 -0
  113. package/node_modules/@typescript/old/lib/cs/diagnosticMessages.generated.json +2129 -0
  114. package/node_modules/@typescript/old/lib/de/diagnosticMessages.generated.json +2125 -0
  115. package/node_modules/@typescript/old/lib/es/diagnosticMessages.generated.json +2129 -0
  116. package/node_modules/@typescript/old/lib/fr/diagnosticMessages.generated.json +2129 -0
  117. package/node_modules/@typescript/old/lib/it/diagnosticMessages.generated.json +2125 -0
  118. package/node_modules/@typescript/old/lib/ja/diagnosticMessages.generated.json +2129 -0
  119. package/node_modules/@typescript/old/lib/ko/diagnosticMessages.generated.json +2129 -0
  120. package/node_modules/@typescript/old/lib/lib.d.ts +20 -0
  121. package/node_modules/@typescript/old/lib/lib.decorators.d.ts +382 -0
  122. package/node_modules/@typescript/old/lib/lib.decorators.legacy.d.ts +20 -0
  123. package/node_modules/@typescript/old/lib/lib.dom.asynciterable.d.ts +18 -0
  124. package/node_modules/@typescript/old/lib/lib.dom.d.ts +45125 -0
  125. package/node_modules/@typescript/old/lib/lib.dom.iterable.d.ts +18 -0
  126. package/node_modules/@typescript/old/lib/lib.es2015.collection.d.ts +150 -0
  127. package/node_modules/@typescript/old/lib/lib.es2015.core.d.ts +595 -0
  128. package/node_modules/@typescript/old/lib/lib.es2015.d.ts +26 -0
  129. package/node_modules/@typescript/old/lib/lib.es2015.generator.d.ts +75 -0
  130. package/node_modules/@typescript/old/lib/lib.es2015.iterable.d.ts +603 -0
  131. package/node_modules/@typescript/old/lib/lib.es2015.promise.d.ts +79 -0
  132. package/node_modules/@typescript/old/lib/lib.es2015.proxy.d.ts +126 -0
  133. package/node_modules/@typescript/old/lib/lib.es2015.reflect.d.ts +142 -0
  134. package/node_modules/@typescript/old/lib/lib.es2015.symbol.d.ts +44 -0
  135. package/node_modules/@typescript/old/lib/lib.es2015.symbol.wellknown.d.ts +324 -0
  136. package/node_modules/@typescript/old/lib/lib.es2016.array.include.d.ts +114 -0
  137. package/node_modules/@typescript/old/lib/lib.es2016.d.ts +19 -0
  138. package/node_modules/@typescript/old/lib/lib.es2016.full.d.ts +21 -0
  139. package/node_modules/@typescript/old/lib/lib.es2016.intl.d.ts +29 -0
  140. package/node_modules/@typescript/old/lib/lib.es2017.arraybuffer.d.ts +19 -0
  141. package/node_modules/@typescript/old/lib/lib.es2017.d.ts +24 -0
  142. package/node_modules/@typescript/old/lib/lib.es2017.date.d.ts +29 -0
  143. package/node_modules/@typescript/old/lib/lib.es2017.full.d.ts +21 -0
  144. package/node_modules/@typescript/old/lib/lib.es2017.intl.d.ts +42 -0
  145. package/node_modules/@typescript/old/lib/lib.es2017.object.d.ts +47 -0
  146. package/node_modules/@typescript/old/lib/lib.es2017.sharedmemory.d.ts +133 -0
  147. package/node_modules/@typescript/old/lib/lib.es2017.string.d.ts +43 -0
  148. package/node_modules/@typescript/old/lib/lib.es2017.typedarrays.d.ts +51 -0
  149. package/node_modules/@typescript/old/lib/lib.es2018.asyncgenerator.d.ts +75 -0
  150. package/node_modules/@typescript/old/lib/lib.es2018.asynciterable.d.ts +51 -0
  151. package/node_modules/@typescript/old/lib/lib.es2018.d.ts +22 -0
  152. package/node_modules/@typescript/old/lib/lib.es2018.full.d.ts +22 -0
  153. package/node_modules/@typescript/old/lib/lib.es2018.intl.d.ts +81 -0
  154. package/node_modules/@typescript/old/lib/lib.es2018.promise.d.ts +28 -0
  155. package/node_modules/@typescript/old/lib/lib.es2018.regexp.d.ts +35 -0
  156. package/node_modules/@typescript/old/lib/lib.es2019.array.d.ts +77 -0
  157. package/node_modules/@typescript/old/lib/lib.es2019.d.ts +22 -0
  158. package/node_modules/@typescript/old/lib/lib.es2019.full.d.ts +22 -0
  159. package/node_modules/@typescript/old/lib/lib.es2019.intl.d.ts +21 -0
  160. package/node_modules/@typescript/old/lib/lib.es2019.object.d.ts +31 -0
  161. package/node_modules/@typescript/old/lib/lib.es2019.string.d.ts +35 -0
  162. package/node_modules/@typescript/old/lib/lib.es2019.symbol.d.ts +22 -0
  163. package/node_modules/@typescript/old/lib/lib.es2020.bigint.d.ts +763 -0
  164. package/node_modules/@typescript/old/lib/lib.es2020.d.ts +25 -0
  165. package/node_modules/@typescript/old/lib/lib.es2020.date.d.ts +40 -0
  166. package/node_modules/@typescript/old/lib/lib.es2020.full.d.ts +22 -0
  167. package/node_modules/@typescript/old/lib/lib.es2020.intl.d.ts +472 -0
  168. package/node_modules/@typescript/old/lib/lib.es2020.number.d.ts +26 -0
  169. package/node_modules/@typescript/old/lib/lib.es2020.promise.d.ts +45 -0
  170. package/node_modules/@typescript/old/lib/lib.es2020.sharedmemory.d.ts +97 -0
  171. package/node_modules/@typescript/old/lib/lib.es2020.string.d.ts +42 -0
  172. package/node_modules/@typescript/old/lib/lib.es2020.symbol.wellknown.d.ts +39 -0
  173. package/node_modules/@typescript/old/lib/lib.es2021.d.ts +21 -0
  174. package/node_modules/@typescript/old/lib/lib.es2021.full.d.ts +22 -0
  175. package/node_modules/@typescript/old/lib/lib.es2021.intl.d.ts +164 -0
  176. package/node_modules/@typescript/old/lib/lib.es2021.promise.d.ts +46 -0
  177. package/node_modules/@typescript/old/lib/lib.es2021.string.d.ts +31 -0
  178. package/node_modules/@typescript/old/lib/lib.es2021.weakref.d.ts +76 -0
  179. package/node_modules/@typescript/old/lib/lib.es2022.array.d.ts +119 -0
  180. package/node_modules/@typescript/old/lib/lib.es2022.d.ts +23 -0
  181. package/node_modules/@typescript/old/lib/lib.es2022.error.d.ts +73 -0
  182. package/node_modules/@typescript/old/lib/lib.es2022.full.d.ts +22 -0
  183. package/node_modules/@typescript/old/lib/lib.es2022.intl.d.ts +143 -0
  184. package/node_modules/@typescript/old/lib/lib.es2022.object.d.ts +24 -0
  185. package/node_modules/@typescript/old/lib/lib.es2022.regexp.d.ts +37 -0
  186. package/node_modules/@typescript/old/lib/lib.es2022.string.d.ts +23 -0
  187. package/node_modules/@typescript/old/lib/lib.es2023.array.d.ts +922 -0
  188. package/node_modules/@typescript/old/lib/lib.es2023.collection.d.ts +19 -0
  189. package/node_modules/@typescript/old/lib/lib.es2023.d.ts +20 -0
  190. package/node_modules/@typescript/old/lib/lib.es2023.full.d.ts +22 -0
  191. package/node_modules/@typescript/old/lib/lib.es2023.intl.d.ts +62 -0
  192. package/node_modules/@typescript/old/lib/lib.es2024.arraybuffer.d.ts +63 -0
  193. package/node_modules/@typescript/old/lib/lib.es2024.collection.d.ts +27 -0
  194. package/node_modules/@typescript/old/lib/lib.es2024.d.ts +24 -0
  195. package/node_modules/@typescript/old/lib/lib.es2024.full.d.ts +22 -0
  196. package/node_modules/@typescript/old/lib/lib.es2024.object.d.ts +27 -0
  197. package/node_modules/@typescript/old/lib/lib.es2024.promise.d.ts +33 -0
  198. package/node_modules/@typescript/old/lib/lib.es2024.regexp.d.ts +23 -0
  199. package/node_modules/@typescript/old/lib/lib.es2024.sharedmemory.d.ts +66 -0
  200. package/node_modules/@typescript/old/lib/lib.es2024.string.d.ts +27 -0
  201. package/node_modules/@typescript/old/lib/lib.es2025.collection.d.ts +94 -0
  202. package/node_modules/@typescript/old/lib/lib.es2025.d.ts +23 -0
  203. package/node_modules/@typescript/old/lib/lib.es2025.float16.d.ts +443 -0
  204. package/node_modules/@typescript/old/lib/lib.es2025.full.d.ts +22 -0
  205. package/node_modules/@typescript/old/lib/lib.es2025.intl.d.ts +200 -0
  206. package/node_modules/@typescript/old/lib/lib.es2025.iterator.d.ts +146 -0
  207. package/node_modules/@typescript/old/lib/lib.es2025.promise.d.ts +32 -0
  208. package/node_modules/@typescript/old/lib/lib.es2025.regexp.d.ts +30 -0
  209. package/node_modules/@typescript/old/lib/lib.es5.d.ts +4599 -0
  210. package/node_modules/@typescript/old/lib/lib.es6.d.ts +21 -0
  211. package/node_modules/@typescript/old/lib/lib.esnext.array.d.ts +33 -0
  212. package/node_modules/@typescript/old/lib/lib.esnext.collection.d.ts +47 -0
  213. package/node_modules/@typescript/old/lib/lib.esnext.d.ts +27 -0
  214. package/node_modules/@typescript/old/lib/lib.esnext.date.d.ts +21 -0
  215. package/node_modules/@typescript/old/lib/lib.esnext.decorators.d.ts +26 -0
  216. package/node_modules/@typescript/old/lib/lib.esnext.disposable.d.ts +191 -0
  217. package/node_modules/@typescript/old/lib/lib.esnext.error.d.ts +22 -0
  218. package/node_modules/@typescript/old/lib/lib.esnext.full.d.ts +22 -0
  219. package/node_modules/@typescript/old/lib/lib.esnext.intl.d.ts +107 -0
  220. package/node_modules/@typescript/old/lib/lib.esnext.sharedmemory.d.ts +23 -0
  221. package/node_modules/@typescript/old/lib/lib.esnext.temporal.d.ts +485 -0
  222. package/node_modules/@typescript/old/lib/lib.esnext.typedarrays.d.ts +90 -0
  223. package/node_modules/@typescript/old/lib/lib.scripthost.d.ts +320 -0
  224. package/node_modules/@typescript/old/lib/lib.webworker.asynciterable.d.ts +18 -0
  225. package/node_modules/@typescript/old/lib/lib.webworker.d.ts +15606 -0
  226. package/node_modules/@typescript/old/lib/lib.webworker.importscripts.d.ts +21 -0
  227. package/node_modules/@typescript/old/lib/lib.webworker.iterable.d.ts +18 -0
  228. package/node_modules/@typescript/old/lib/pl/diagnosticMessages.generated.json +2129 -0
  229. package/node_modules/@typescript/old/lib/pt-br/diagnosticMessages.generated.json +2129 -0
  230. package/node_modules/@typescript/old/lib/ru/diagnosticMessages.generated.json +2125 -0
  231. package/node_modules/@typescript/old/lib/tr/diagnosticMessages.generated.json +2129 -0
  232. package/node_modules/@typescript/old/lib/tsc.js +8 -0
  233. package/node_modules/@typescript/old/lib/tsserver.js +8 -0
  234. package/node_modules/@typescript/old/lib/tsserverlibrary.d.ts +17 -0
  235. package/node_modules/@typescript/old/lib/tsserverlibrary.js +21 -0
  236. package/node_modules/@typescript/old/lib/typesMap.json +497 -0
  237. package/node_modules/@typescript/old/lib/typescript.d.ts +11448 -0
  238. package/node_modules/@typescript/old/lib/typescript.js +201039 -0
  239. package/node_modules/@typescript/old/lib/typingsInstaller.js +8 -0
  240. package/node_modules/@typescript/old/lib/watchGuard.js +53 -0
  241. package/node_modules/@typescript/old/lib/zh-cn/diagnosticMessages.generated.json +2129 -0
  242. package/node_modules/@typescript/old/lib/zh-tw/diagnosticMessages.generated.json +2125 -0
  243. package/node_modules/@typescript/old/package.json +118 -0
  244. package/node_modules/@typescript/typescript6/LICENSE.txt +55 -0
  245. package/node_modules/@typescript/typescript6/README.md +9 -0
  246. package/node_modules/@typescript/typescript6/bin/tsc6 +2 -0
  247. package/node_modules/@typescript/typescript6/lib/tsc.js +1 -0
  248. package/node_modules/@typescript/typescript6/lib/tsserverlibrary.d.ts +2 -0
  249. package/node_modules/@typescript/typescript6/lib/tsserverlibrary.js +1 -0
  250. package/node_modules/@typescript/typescript6/lib/typescript.d.ts +2 -0
  251. package/node_modules/@typescript/typescript6/lib/typescript.js +1 -0
  252. package/node_modules/@typescript/typescript6/package.json +39 -0
  253. package/package.json +32 -14
  254. package/schemas/env-cap-report.schema.json +1 -1
  255. package/dist/build-U326PI5A.js.map +0 -1
  256. package/dist/chunk-BSTLSR2R.js.map +0 -1
package/dist/build.js CHANGED
@@ -1,6 +1,5 @@
1
1
  import path6 from 'path';
2
2
  import crypto from 'crypto';
3
- import ts4 from 'typescript';
4
3
  import { createRequire } from 'module';
5
4
 
6
5
  // src/build/evidence-snapshot.ts
@@ -37,7 +36,6 @@ function previousContentHashes(previous) {
37
36
  for (const contract of previous?.dependency.contracts ?? []) {
38
37
  for (const variable of contract.variables) {
39
38
  for (const assertion of variable.dynamicAccessAssertions) {
40
- if (assertion.contentHash === void 0) continue;
41
39
  const identity = dynamicAccessVariableIdentity(
42
40
  contract.file,
43
41
  contract.exportName,
@@ -58,8 +56,8 @@ async function buildCitationSnapshots(activeContracts, previous, root, readFile)
58
56
  for (const contract of activeContracts) {
59
57
  const file = displayPath(root, contract.file);
60
58
  for (const variable of contract.variables) {
61
- const citations = variable.evidence?.dynamicAccess ?? [];
62
- if (citations.length === 0) continue;
59
+ const citations = variable.evidence?.dynamicAccess;
60
+ if (citations === void 0) continue;
63
61
  const identity = dynamicAccessVariableIdentity(file, contract.exportName, variable.key);
64
62
  const assertions = [];
65
63
  for (const citation of citations) {
@@ -137,9 +135,7 @@ function toVariableRef(contract, variable) {
137
135
  return { file: contract.file, exportName: contract.exportName, key: variable.key };
138
136
  }
139
137
  function toComparable(value) {
140
- if (value === void 0) return void 0;
141
- if (typeof value === "string") return value;
142
- return JSON.stringify(value);
138
+ return typeof value === "string" ? value : JSON.stringify(value);
143
139
  }
144
140
  function genericFieldChanges(previous, current, skipKeys) {
145
141
  const keys = /* @__PURE__ */ new Set([...Object.keys(previous), ...Object.keys(current)]);
@@ -182,17 +178,7 @@ function recordFieldChanges(previous, current) {
182
178
  return changes;
183
179
  }
184
180
  function byIdentity(a, b) {
185
- return a.file.localeCompare(b.file) || a.exportName.localeCompare(b.exportName) || // The `?? ""` fallbacks themselves are unreachable through any real
186
- // array this function ever sorts: a `ManifestContractRef` never carries
187
- // a `key` at all, but its own array can never hold two entries sharing
188
- // both file+exportName (contracts are unique by that pair) so the key
189
- // term is never reached for them either way; a `ManifestVariableRef`'s
190
- // `key` is always a real, non-empty string, never `undefined`. Hand-
191
- // verified: mutating both fallbacks to a distinguishing sentinel and
192
- // running the real suite (this file plus
193
- // check-artifacts.test.ts/generate-evidence.test.ts) passes unchanged.
194
- // Stryker disable next-line StringLiteral
195
- (a.key ?? "").localeCompare(b.key ?? "");
181
+ return a.file.localeCompare(b.file) || a.exportName.localeCompare(b.exportName) || String(a.key).localeCompare(String(b.key));
196
182
  }
197
183
  function diffContracts(previous, current) {
198
184
  const previousContracts = new Map((previous ?? []).map((c) => [contractIdentity(c), c]));
@@ -211,25 +197,12 @@ function diffContracts(previous, current) {
211
197
  const changes = genericFieldChanges(
212
198
  previousContract,
213
199
  currentContract,
214
- /* @__PURE__ */ new Set([
215
- // "file"/"exportName" can never actually differ here: both
216
- // contracts of a matched pair share the same Map key
217
- // (`contractIdentity()`), itself derived from file+exportName, so
218
- // they're always structurally equal for two contracts matched
219
- // into one updatedContracts entry. Hand-verified equivalent via
220
- // direct mutation + a real suite run.
221
- // Stryker disable next-line StringLiteral
222
- "file",
223
- // Stryker disable next-line StringLiteral
224
- "exportName",
225
- // Genuinely skipped AND real-tested -- see "does not report the
226
- // whole variables array as a changed field" below.
227
- "variables"
228
- ])
200
+ // `file` and `exportName` cannot differ for a matched pair (they make up its identity).
201
+ /* @__PURE__ */ new Set(["variables"])
229
202
  );
230
203
  if (changes.length > 0) updatedContracts.push({ ...toContractRef(currentContract), changes });
231
204
  }
232
- const previousVariables = new Map((previousContract?.variables ?? []).map((v) => [v.key, v]));
205
+ const previousVariables = new Map(previousContract?.variables.map((v) => [v.key, v]));
233
206
  const currentVariables = new Map(currentContract.variables.map((v) => [v.key, v]));
234
207
  for (const [key, currentVariable] of currentVariables) {
235
208
  const previousVariable = previousVariables.get(key);
@@ -240,16 +213,14 @@ function diffContracts(previous, current) {
240
213
  const changes = genericFieldChanges(
241
214
  previousVariable,
242
215
  currentVariable,
243
- /* @__PURE__ */ new Set(["key"])
216
+ /* @__PURE__ */ new Set()
244
217
  );
245
218
  if (changes.length > 0)
246
219
  updatedVariables.push({ ...toVariableRef(currentContract, currentVariable), changes });
247
220
  }
248
- if (previousContract) {
249
- for (const [key, previousVariable] of previousVariables) {
250
- if (!currentVariables.has(key))
251
- removedVariables.push(toVariableRef(previousContract, previousVariable));
252
- }
221
+ for (const [key, previousVariable] of previousVariables) {
222
+ if (!currentVariables.has(key))
223
+ removedVariables.push(toVariableRef(currentContract, previousVariable));
253
224
  }
254
225
  }
255
226
  for (const [identity, previousContract] of previousContracts) {
@@ -293,7 +264,6 @@ async function writeEvidenceSnapshot(snapshotPath, snapshot, fs) {
293
264
  await fs.writeFile(snapshotPath, `${JSON.stringify(snapshot, null, 2)}
294
265
  `, "utf8");
295
266
  }
296
- var EXPIRY_DAY_COUNT = /\b\d+ day\(s\)/g;
297
267
  function normalizeEvidenceSnapshotForComparison(snapshot) {
298
268
  return {
299
269
  ...snapshot,
@@ -317,7 +287,7 @@ function normalizeEvidenceSnapshotForComparison(snapshot) {
317
287
  finding: {
318
288
  ...snapshot.finding,
319
289
  findings: snapshot.finding.findings.map(
320
- (f) => f.code === "EXPIRED" || f.code === "EXPIRING_SOON" ? { ...f, message: f.message.replace(EXPIRY_DAY_COUNT, "N day(s)") } : f
290
+ (f) => f.code === "EXPIRED" || f.code === "EXPIRING_SOON" ? { ...f, message: f.message.replace(/\b\d+ day\(s\)/g, "N day(s)") } : f
321
291
  )
322
292
  }
323
293
  };
@@ -326,19 +296,22 @@ async function computeEvidenceChanges(root, snapshotPath, activeContracts, curre
326
296
  const read = await readEvidenceSnapshot(snapshotPath, fs);
327
297
  let previous;
328
298
  let readWarning;
329
- if (read.status === "invalid-json") {
330
- readWarning = {
331
- file: snapshotPath,
332
- message: `Evidence snapshot could not be parsed as JSON (${read.detail}); treating this run as if no previous snapshot existed.`
333
- };
334
- } else if (read.status === "unsupported-version") {
335
- readWarning = {
336
- file: snapshotPath,
337
- message: `Evidence snapshot has schemaVersion ${JSON.stringify(read.foundVersion)}, which this version of env-cap does not understand (expected ${EVIDENCE_MODEL_SCHEMA_VERSION}); treating this run as if no previous snapshot existed.`
338
- };
339
- }
340
- if (read.status === "ok") {
341
- previous = read.snapshot;
299
+ switch (read.status) {
300
+ case "ok":
301
+ previous = read.snapshot;
302
+ break;
303
+ case "invalid-json":
304
+ readWarning = {
305
+ file: snapshotPath,
306
+ message: `Evidence snapshot could not be parsed as JSON (${read.detail}); treating this run as if no previous snapshot existed.`
307
+ };
308
+ break;
309
+ case "unsupported-version":
310
+ readWarning = {
311
+ file: snapshotPath,
312
+ 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.`
313
+ };
314
+ break;
342
315
  }
343
316
  const dynamicAccessAcknowledgments = await buildCitationSnapshots(
344
317
  activeContracts,
@@ -361,27 +334,18 @@ async function computeEvidenceChanges(root, snapshotPath, activeContracts, curre
361
334
  // src/build/glob.ts
362
335
  function globToRegExp(pattern) {
363
336
  let out = "";
364
- let passes = 0;
365
- const maxPasses = pattern.length * 2 + 4;
366
- for (let i = 0; i < pattern.length; i++) {
367
- passes++;
368
- if (passes > maxPasses) {
369
- throw new Error(
370
- // Stryker disable next-line StringLiteral
371
- `globToRegExp: exceeded ${String(maxPasses)} iterations parsing pattern ${JSON.stringify(pattern)} -- this should never happen for any real pattern and indicates an internal parsing bug.`
372
- );
373
- }
374
- const char = pattern[i];
375
- if (char === void 0) continue;
337
+ let resume = 0;
338
+ for (const [i, char] of pattern.split("").entries()) {
339
+ if (i < resume) continue;
376
340
  if (char === "*" && pattern[i + 1] === "*") {
377
341
  const precededBySlashOrStart = i === 0 || pattern[i - 1] === "/";
378
342
  const followedBySlash = pattern[i + 2] === "/";
379
343
  if (precededBySlashOrStart && followedBySlash) {
380
344
  out += "(?:.*/)?";
381
- i += 2;
345
+ resume = i + 3;
382
346
  } else {
383
347
  out += ".*";
384
- i += 1;
348
+ resume = i + 2;
385
349
  }
386
350
  } else if (char === "*") {
387
351
  out += "[^/]*";
@@ -412,7 +376,7 @@ async function discoverSchemaFiles(options) {
412
376
  `discoverSchemaFiles: found ${String(included.length)} files matching "include" under ${options.root} -- more than the ${String(MAX_DISCOVERED_SCHEMA_FILES)}-file sanity limit. This almost always means "root" (or "include"/"exclude") resolved more broadly than intended -- e.g. an omitted "root" falling back to an unexpectedly large process.cwd() -- rather than a real project genuinely declaring this many contracts. Narrow "root"/"include"/"exclude" to the intended project boundary.`
413
377
  );
414
378
  }
415
- return included.map((file) => path6.normalize(file)).sort((a, b) => a < b ? -1 : 1);
379
+ return included.map((file) => path6.normalize(file)).sort();
416
380
  }
417
381
  async function walkDirectory(directory, root, exclude, fs) {
418
382
  const entries = await fs.readdir(directory, { withFileTypes: true });
@@ -438,18 +402,52 @@ function toPosixRelative(root, target) {
438
402
  function matchesAnyPattern(filePath, patterns) {
439
403
  return patterns.some((pattern) => globToRegExp(pattern).test(filePath));
440
404
  }
405
+ function hasClassicApi(candidate) {
406
+ return typeof candidate?.createSourceFile === "function";
407
+ }
408
+ function isModuleNotFound(error, id) {
409
+ const { code, message } = error ?? {};
410
+ if (code !== "MODULE_NOT_FOUND" && code !== "ERR_MODULE_NOT_FOUND") return false;
411
+ return typeof message === "string" && (message.startsWith(`Cannot find module '${id}'`) || message.startsWith(`Cannot find package '${id}'`));
412
+ }
413
+ function tryLoad(load, id) {
414
+ try {
415
+ return load(id);
416
+ } catch (error) {
417
+ if (isModuleNotFound(error, id)) return void 0;
418
+ throw error;
419
+ }
420
+ }
421
+ function pickCompiler(load) {
422
+ const consumer = tryLoad(load, "typescript");
423
+ if (hasClassicApi(consumer)) return consumer;
424
+ const bundled = tryLoad(load, "@typescript/typescript6");
425
+ if (hasClassicApi(bundled)) return bundled;
426
+ return consumer ?? {};
427
+ }
428
+ var ts = pickCompiler(createRequire(import.meta.url));
429
+
430
+ // src/build/compiler-api.ts
431
+ function assertCompilerApi(compiler) {
432
+ if (typeof compiler.createSourceFile === "function") return;
433
+ throw new Error(
434
+ `env-cap'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 env-cap 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'.`
435
+ );
436
+ }
437
+
438
+ // src/build/literal-eval.ts
441
439
  function evaluateLiteral(node) {
442
- if (ts4.isStringLiteralLike(node)) return { ok: true, value: node.text };
443
- if (ts4.isNumericLiteral(node)) return { ok: true, value: Number(node.text) };
444
- if (node.kind === ts4.SyntaxKind.TrueKeyword) return { ok: true, value: true };
445
- if (node.kind === ts4.SyntaxKind.FalseKeyword) return { ok: true, value: false };
446
- if (node.kind === ts4.SyntaxKind.NullKeyword) return { ok: true, value: null };
447
- if (ts4.isParenthesizedExpression(node)) return evaluateLiteral(node.expression);
448
- if (ts4.isPrefixUnaryExpression(node) && node.operator === ts4.SyntaxKind.MinusToken) {
440
+ if (ts.isStringLiteralLike(node)) return { ok: true, value: node.text };
441
+ if (ts.isNumericLiteral(node)) return { ok: true, value: Number(node.text) };
442
+ if (node.kind === ts.SyntaxKind.TrueKeyword) return { ok: true, value: true };
443
+ if (node.kind === ts.SyntaxKind.FalseKeyword) return { ok: true, value: false };
444
+ if (node.kind === ts.SyntaxKind.NullKeyword) return { ok: true, value: null };
445
+ if (ts.isParenthesizedExpression(node)) return evaluateLiteral(node.expression);
446
+ if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken) {
449
447
  const operand = evaluateLiteral(node.operand);
450
448
  return operand.ok && typeof operand.value === "number" ? { ok: true, value: -operand.value } : { ok: false };
451
449
  }
452
- if (ts4.isArrayLiteralExpression(node)) {
450
+ if (ts.isArrayLiteralExpression(node)) {
453
451
  const values = [];
454
452
  for (const element of node.elements) {
455
453
  const result = evaluateLiteral(element);
@@ -458,10 +456,10 @@ function evaluateLiteral(node) {
458
456
  }
459
457
  return { ok: true, value: values };
460
458
  }
461
- if (ts4.isObjectLiteralExpression(node)) {
459
+ if (ts.isObjectLiteralExpression(node)) {
462
460
  const record = {};
463
461
  for (const prop of node.properties) {
464
- if (!ts4.isPropertyAssignment(prop)) return { ok: false };
462
+ if (!ts.isPropertyAssignment(prop)) return { ok: false };
465
463
  const key = getStaticPropertyName(prop.name);
466
464
  if (key === void 0) return { ok: false };
467
465
  const result = evaluateLiteral(prop.initializer);
@@ -473,20 +471,21 @@ function evaluateLiteral(node) {
473
471
  return { ok: false };
474
472
  }
475
473
  function getStaticPropertyName(name) {
476
- if (ts4.isIdentifier(name)) return name.text;
477
- if (ts4.isStringLiteralLike(name)) return name.text;
478
- if (ts4.isNumericLiteral(name)) return name.text;
474
+ if (ts.isIdentifier(name)) return name.text;
475
+ if (ts.isStringLiteralLike(name)) return name.text;
476
+ if (ts.isNumericLiteral(name)) return name.text;
479
477
  return void 0;
480
478
  }
481
479
 
482
480
  // src/build/parse.ts
483
481
  function parseSchemaFile(filePath, sourceText) {
484
- const sourceFile = ts4.createSourceFile(
482
+ assertCompilerApi(ts);
483
+ const sourceFile = ts.createSourceFile(
485
484
  filePath,
486
485
  sourceText,
487
- ts4.ScriptTarget.Latest,
486
+ ts.ScriptTarget.Latest,
488
487
  true,
489
- ts4.ScriptKind.TS
488
+ ts.ScriptKind.TS
490
489
  );
491
490
  const warnings = [];
492
491
  const localConsts = /* @__PURE__ */ new Map();
@@ -495,21 +494,21 @@ function parseSchemaFile(filePath, sourceText) {
495
494
  const createEnvCalls = [];
496
495
  const documentEnvCalls = [];
497
496
  for (const statement of sourceFile.statements) {
498
- if (ts4.isImportDeclaration(statement)) {
497
+ if (ts.isImportDeclaration(statement)) {
499
498
  collectImportBindings(statement, imports);
500
499
  continue;
501
500
  }
502
- if (!ts4.isVariableStatement(statement)) continue;
503
- const isExported = statement.modifiers?.some((m) => m.kind === ts4.SyntaxKind.ExportKeyword) ?? false;
501
+ if (!ts.isVariableStatement(statement)) continue;
502
+ const isExported = statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
504
503
  for (const decl of statement.declarationList.declarations) {
505
- if (!ts4.isIdentifier(decl.name) || !decl.initializer) continue;
504
+ if (!ts.isIdentifier(decl.name) || !decl.initializer) continue;
506
505
  const bindingName = decl.name.text;
507
- if (ts4.isObjectLiteralExpression(decl.initializer)) {
506
+ if (ts.isObjectLiteralExpression(decl.initializer)) {
508
507
  localConsts.set(bindingName, decl.initializer);
509
508
  if (isExported) exportedConstNames.add(bindingName);
510
509
  continue;
511
510
  }
512
- if (ts4.isCallExpression(decl.initializer)) {
511
+ if (ts.isCallExpression(decl.initializer)) {
513
512
  if (isCallToName(decl.initializer, "createEnv")) {
514
513
  if (!isExported) {
515
514
  warnings.push({
@@ -537,9 +536,9 @@ function parseSchemaFile(filePath, sourceText) {
537
536
  }
538
537
  }
539
538
  for (const statement of sourceFile.statements) {
540
- if (!ts4.isExpressionStatement(statement)) continue;
539
+ if (!ts.isExpressionStatement(statement)) continue;
541
540
  const expr = statement.expression;
542
- if (!ts4.isCallExpression(expr) || !isCallToName(expr, "documentEnv")) continue;
541
+ if (!ts.isCallExpression(expr) || !isCallToName(expr, "documentEnv")) continue;
543
542
  const [schemaArg, docsArg] = expr.arguments;
544
543
  documentEnvCalls.push({ schemaRef: resolveSchemaRef(schemaArg), docsArg, node: expr });
545
544
  }
@@ -556,15 +555,15 @@ function parseSchemaFile(filePath, sourceText) {
556
555
  }
557
556
  function resolveSchemaRef(node) {
558
557
  if (!node) return { kind: "unresolvable" };
559
- if (ts4.isObjectLiteralExpression(node)) return { kind: "literal", node };
560
- if (ts4.isIdentifier(node)) return { kind: "identifier", name: node.text };
558
+ if (ts.isObjectLiteralExpression(node)) return { kind: "literal", node };
559
+ if (ts.isIdentifier(node)) return { kind: "identifier", name: node.text };
561
560
  return { kind: "unresolvable" };
562
561
  }
563
562
  function collectImportBindings(statement, imports) {
564
- if (!ts4.isStringLiteralLike(statement.moduleSpecifier)) return;
563
+ if (!ts.isStringLiteralLike(statement.moduleSpecifier)) return;
565
564
  const specifier = statement.moduleSpecifier.text;
566
565
  const namedBindings = statement.importClause?.namedBindings;
567
- if (!namedBindings || !ts4.isNamedImports(namedBindings)) return;
566
+ if (!namedBindings || !ts.isNamedImports(namedBindings)) return;
568
567
  for (const element of namedBindings.elements) {
569
568
  const localName = element.name.text;
570
569
  const importedName = element.propertyName?.text ?? localName;
@@ -573,8 +572,8 @@ function collectImportBindings(statement, imports) {
573
572
  }
574
573
  function isCallToName(call, name) {
575
574
  const expr = call.expression;
576
- if (ts4.isIdentifier(expr)) return expr.text === name;
577
- if (ts4.isPropertyAccessExpression(expr)) return expr.name.text === name;
575
+ if (ts.isIdentifier(expr)) return expr.text === name;
576
+ if (ts.isPropertyAccessExpression(expr)) return expr.name.text === name;
578
577
  return false;
579
578
  }
580
579
  function isValidEnvKey(key) {
@@ -583,7 +582,7 @@ function isValidEnvKey(key) {
583
582
  function extractSchemaVariables(schemaLiteral, filePath, contextLabel, warnings, sourceFile) {
584
583
  const variables = [];
585
584
  for (const prop of schemaLiteral.properties) {
586
- if (!ts4.isPropertyAssignment(prop)) {
585
+ if (!ts.isPropertyAssignment(prop)) {
587
586
  warnings.push({
588
587
  file: filePath,
589
588
  message: `Skipped a non-static schema entry in "${contextLabel}" (spread or computed key are not statically analyzable).`
@@ -599,7 +598,7 @@ function extractSchemaVariables(schemaLiteral, filePath, contextLabel, warnings,
599
598
  });
600
599
  continue;
601
600
  }
602
- if (!ts4.isObjectLiteralExpression(prop.initializer)) {
601
+ if (!ts.isObjectLiteralExpression(prop.initializer)) {
603
602
  warnings.push({
604
603
  file: filePath,
605
604
  message: `Definition for "${key}" in "${contextLabel}" is not an inline object literal; skipping static analysis for this variable.`
@@ -623,7 +622,7 @@ function extractSchemaVariable(key, definition, filePath, contextLabel, warnings
623
622
  let validatorSource;
624
623
  let context;
625
624
  for (const prop of definition.properties) {
626
- if (!ts4.isPropertyAssignment(prop)) continue;
625
+ if (!ts.isPropertyAssignment(prop)) continue;
627
626
  const name = getStaticPropertyName(prop.name);
628
627
  if (name === "default") {
629
628
  hasDefault = true;
@@ -661,13 +660,13 @@ function extractSchemaVariable(key, definition, filePath, contextLabel, warnings
661
660
  };
662
661
  }
663
662
  function extractReturnType(node) {
664
- if ((ts4.isArrowFunction(node) || ts4.isFunctionExpression(node)) && node.type) {
665
- return node.type.getText().replace(/\s+/g, "");
663
+ if ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.type) {
664
+ return node.type.getText().replace(/\s/g, "");
666
665
  }
667
666
  return void 0;
668
667
  }
669
668
  function normalizeSource(text) {
670
- return text.replace(/\s+/g, " ").trim();
669
+ return text.replace(/\s+/g, " ");
671
670
  }
672
671
  function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
673
672
  let name;
@@ -686,7 +685,7 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
686
685
  let auditRequired;
687
686
  let metadata;
688
687
  const variables = /* @__PURE__ */ new Map();
689
- if (!docsArg || !ts4.isObjectLiteralExpression(docsArg)) {
688
+ if (!docsArg || !ts.isObjectLiteralExpression(docsArg)) {
690
689
  if (docsArg) {
691
690
  warnings.push({
692
691
  file: filePath,
@@ -713,7 +712,7 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
713
712
  };
714
713
  }
715
714
  for (const prop of docsArg.properties) {
716
- if (!ts4.isPropertyAssignment(prop)) continue;
715
+ if (!ts.isPropertyAssignment(prop)) continue;
717
716
  const propName = getStaticPropertyName(prop.name);
718
717
  if (propName === "name") {
719
718
  const evaluated = evaluateLiteral(prop.initializer);
@@ -817,7 +816,7 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
817
816
  });
818
817
  }
819
818
  } else if (propName === "variables") {
820
- if (ts4.isObjectLiteralExpression(prop.initializer)) {
819
+ if (ts.isObjectLiteralExpression(prop.initializer)) {
821
820
  extractVariableDocsMap(prop.initializer, filePath, contextLabel, warnings, variables);
822
821
  } else {
823
822
  warnings.push({
@@ -848,10 +847,10 @@ function extractContractDocs(docsArg, filePath, contextLabel, warnings) {
848
847
  }
849
848
  function extractVariableDocsMap(variablesLiteral, filePath, contextLabel, warnings, out) {
850
849
  for (const prop of variablesLiteral.properties) {
851
- if (!ts4.isPropertyAssignment(prop)) continue;
850
+ if (!ts.isPropertyAssignment(prop)) continue;
852
851
  const key = getStaticPropertyName(prop.name);
853
852
  if (key === void 0) continue;
854
- if (!ts4.isObjectLiteralExpression(prop.initializer)) {
853
+ if (!ts.isObjectLiteralExpression(prop.initializer)) {
855
854
  warnings.push({
856
855
  file: filePath,
857
856
  message: `documentEnv() variable docs for "${key}" in "${contextLabel}" is not an inline object literal; skipped.`
@@ -881,11 +880,9 @@ function extractVariableDocsMap(variablesLiteral, filePath, contextLabel, warnin
881
880
  let metadata;
882
881
  let evidence;
883
882
  for (const field of prop.initializer.properties) {
884
- if (!ts4.isPropertyAssignment(field)) continue;
883
+ if (!ts.isPropertyAssignment(field)) continue;
885
884
  const fieldName = getStaticPropertyName(field.name);
886
- if (fieldName === void 0) continue;
887
885
  const evaluated = evaluateLiteral(field.initializer);
888
- if (!evaluated.ok) continue;
889
886
  if (fieldName === "description" && typeof evaluated.value === "string")
890
887
  description = evaluated.value;
891
888
  else if (fieldName === "owner" && typeof evaluated.value === "string") owner = evaluated.value;
@@ -981,9 +978,9 @@ function extractDynamicAccessCitations(value, filePath, key, contextLabel, warni
981
978
  return citations;
982
979
  }
983
980
  function extractCreateEnvOptionsName(optionsArg) {
984
- if (!optionsArg || !ts4.isObjectLiteralExpression(optionsArg)) return void 0;
981
+ if (!optionsArg || !ts.isObjectLiteralExpression(optionsArg)) return void 0;
985
982
  for (const prop of optionsArg.properties) {
986
- if (!ts4.isPropertyAssignment(prop)) continue;
983
+ if (!ts.isPropertyAssignment(prop)) continue;
987
984
  if (getStaticPropertyName(prop.name) !== "name") continue;
988
985
  const evaluated = evaluateLiteral(prop.initializer);
989
986
  if (evaluated.ok && typeof evaluated.value === "string") return evaluated.value;
@@ -1218,13 +1215,15 @@ async function mergeLocalAndPackageFiles(localFiles, packageFiles, fs) {
1218
1215
  }
1219
1216
  async function resolvePackageImport(specifier, allowedPackages, root, cache, fs) {
1220
1217
  const matched = allowedPackages.find(
1221
- // Stryker disable next-line ConditionalExpression
1222
1218
  (pkg) => specifier === pkg || specifier.startsWith(`${pkg}/`)
1223
1219
  );
1224
1220
  if (!matched) return void 0;
1225
1221
  const result = await resolvePackageSchemaFile(matched, root, cache, fs);
1226
1222
  return result.ok ? result.origin.resolvedFile : void 0;
1227
1223
  }
1224
+ function pathMappingOptions(options) {
1225
+ return options;
1226
+ }
1228
1227
  function createAliasResolutionCache() {
1229
1228
  return { resolutions: /* @__PURE__ */ new Map() };
1230
1229
  }
@@ -1249,9 +1248,10 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1249
1248
  }
1250
1249
  };
1251
1250
  }
1252
- const readResult = ts4.readConfigFile(configFile, (p) => ts4.sys.readFile(p));
1251
+ assertCompilerApi(ts);
1252
+ const readResult = ts.readConfigFile(configFile, (p) => ts.sys.readFile(p));
1253
1253
  if (readResult.error) {
1254
- const detail = ts4.flattenDiagnosticMessageText(readResult.error.messageText, "\n");
1254
+ const detail = ts.flattenDiagnosticMessageText(readResult.error.messageText, ts.sys.newLine);
1255
1255
  return {
1256
1256
  resolution: void 0,
1257
1257
  warning: {
@@ -1260,8 +1260,8 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1260
1260
  }
1261
1261
  };
1262
1262
  }
1263
- const parsed = ts4.parseJsonConfigFileContent(readResult.config, ts4.sys, path6.dirname(configFile));
1264
- const { paths, baseUrl } = parsed.options;
1263
+ const parsed = ts.parseJsonConfigFileContent(readResult.config, ts.sys, path6.dirname(configFile));
1264
+ const { paths, baseUrl } = pathMappingOptions(parsed.options);
1265
1265
  const hasPaths = paths !== void 0 && Object.keys(paths).length > 0;
1266
1266
  if (!hasPaths && baseUrl === void 0) {
1267
1267
  return { resolution: void 0, warning: void 0 };
@@ -1271,7 +1271,7 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1271
1271
  function resolveAliasImport(specifier, importingFile, resolution, cache) {
1272
1272
  const cacheKey = `${importingFile}\0${specifier}`;
1273
1273
  if (cache.resolutions.has(cacheKey)) return cache.resolutions.get(cacheKey);
1274
- const result = ts4.resolveModuleName(specifier, importingFile, resolution.compilerOptions, ts4.sys);
1274
+ const result = ts.resolveModuleName(specifier, importingFile, resolution.compilerOptions, ts.sys);
1275
1275
  const resolvedFileName = result.resolvedModule?.resolvedFileName;
1276
1276
  let resolved;
1277
1277
  if (resolvedFileName) {
@@ -1299,13 +1299,11 @@ async function resolveRelativeImport(importingFile, specifier, fs) {
1299
1299
  }
1300
1300
  return void 0;
1301
1301
  }
1302
- async function fileExists2(filePath, fs) {
1303
- try {
1304
- const stat = await fs.stat(filePath);
1305
- return stat.isFile();
1306
- } catch {
1307
- return false;
1308
- }
1302
+ function fileExists2(filePath, fs) {
1303
+ return fs.stat(filePath).then(
1304
+ (stat) => stat.isFile(),
1305
+ () => false
1306
+ );
1309
1307
  }
1310
1308
  async function resolveImportSpecifier(importingFile, specifier, context) {
1311
1309
  const relative = await resolveRelativeImport(importingFile, specifier, context.fs);
@@ -1344,24 +1342,29 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1344
1342
  const warnings = [];
1345
1343
  const unresolvedLinks = [];
1346
1344
  async function resolveSchema(ref, inFile, contextLabel) {
1347
- if (ref.kind === "unresolvable") return void 0;
1348
1345
  const inFileAnalysis = mustGet(analysisCache, inFile);
1349
- if (ref.kind === "literal") {
1350
- return {
1351
- identity: `${inFile}#<inline:${ref.node.pos}>`,
1352
- variables: extractSchemaVariables(
1353
- ref.node,
1354
- inFile,
1355
- contextLabel,
1356
- warnings,
1357
- inFileAnalysis.sourceFile
1358
- )
1359
- };
1346
+ switch (ref.kind) {
1347
+ case "literal":
1348
+ return {
1349
+ identity: `${inFile}#<inline:${ref.node.pos}>`,
1350
+ variables: extractSchemaVariables(
1351
+ ref.node,
1352
+ inFile,
1353
+ contextLabel,
1354
+ warnings,
1355
+ inFileAnalysis.sourceFile
1356
+ )
1357
+ };
1358
+ case "identifier":
1359
+ return resolveNamedSchema(ref.name, inFile, inFileAnalysis, contextLabel);
1360
1360
  }
1361
- const local = inFileAnalysis.localConsts.get(ref.name);
1361
+ return void 0;
1362
+ }
1363
+ async function resolveNamedSchema(name, inFile, inFileAnalysis, contextLabel) {
1364
+ const local = inFileAnalysis.localConsts.get(name);
1362
1365
  if (local) {
1363
1366
  return {
1364
- identity: `${inFile}#${ref.name}`,
1367
+ identity: `${inFile}#${name}`,
1365
1368
  variables: extractSchemaVariables(
1366
1369
  local,
1367
1370
  inFile,
@@ -1371,7 +1374,7 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1371
1374
  )
1372
1375
  };
1373
1376
  }
1374
- const imported = inFileAnalysis.imports.get(ref.name);
1377
+ const imported = inFileAnalysis.imports.get(name);
1375
1378
  if (!imported) return void 0;
1376
1379
  const targetFile = await resolveImportSpecifier(inFile, imported.specifier, context);
1377
1380
  if (!targetFile) return void 0;
@@ -1557,7 +1560,7 @@ function effectiveAuditRequired(contract, variable) {
1557
1560
 
1558
1561
  // src/build/assemble-project.ts
1559
1562
  async function assembleProject(options) {
1560
- const { fs, root, include, exclude, packages, tsconfig } = options;
1563
+ const { fs, root, include, exclude, packages = [], tsconfig } = options;
1561
1564
  const fileCache = /* @__PURE__ */ new Map();
1562
1565
  const readFileCached = (filePath) => {
1563
1566
  let cached = fileCache.get(filePath);
@@ -1614,7 +1617,6 @@ function buildChangeModel(manifest, currentContracts, root) {
1614
1617
  const relativeFile = displayPath(root, contract.file);
1615
1618
  const cIdentity = contractIdentity2(relativeFile, contract.exportName);
1616
1619
  for (const variable of contract.variables) {
1617
- if (!variable.renamedFrom) continue;
1618
1620
  const addedRef = findByContractAndKey(
1619
1621
  manifest.addedVariables,
1620
1622
  relativeFile,
@@ -1740,8 +1742,7 @@ function variableShape(variable) {
1740
1742
  };
1741
1743
  }
1742
1744
  function shapesMatch(a, b) {
1743
- if (a.valueType === "unknown" || b.valueType === "unknown") return false;
1744
- return a.valueType === b.valueType && a.hasProcessor === b.hasProcessor && a.hasValidator === b.hasValidator;
1745
+ return a.valueType !== "unknown" && a.valueType === b.valueType && a.hasProcessor === b.hasProcessor && a.hasValidator === b.hasValidator;
1745
1746
  }
1746
1747
  function detectDuplicateVariableShapes(contracts) {
1747
1748
  const candidates = contracts.filter((c) => c.active && !c.exclusiveGroup);
@@ -1880,60 +1881,55 @@ function isPlainObject(value) {
1880
1881
  const proto = Object.getPrototypeOf(value);
1881
1882
  return proto === Object.prototype || proto === null;
1882
1883
  }
1884
+
1885
+ // src/build/scan-dependencies.ts
1883
1886
  function unwrapParens(node) {
1884
1887
  let current = node;
1885
- while (ts4.isParenthesizedExpression(current)) current = current.expression;
1888
+ while (ts.isParenthesizedExpression(current)) current = current.expression;
1886
1889
  return current;
1887
1890
  }
1888
1891
  function staticElementKey(node) {
1889
- return ts4.isStringLiteralLike(node) ? node.text : void 0;
1892
+ return ts.isStringLiteralLike(node) ? node.text : void 0;
1890
1893
  }
1891
1894
  function forEachBindingName(name, record) {
1892
- if (ts4.isIdentifier(name)) {
1895
+ if (ts.isIdentifier(name)) {
1893
1896
  record(name.text);
1894
1897
  return;
1895
1898
  }
1896
1899
  for (const element of name.elements) {
1897
- if (ts4.isOmittedExpression(element)) continue;
1900
+ if (ts.isOmittedExpression(element)) continue;
1898
1901
  forEachBindingName(element.name, record);
1899
1902
  }
1900
1903
  }
1901
1904
  function isAssignmentToken(token) {
1902
- return token >= ts4.SyntaxKind.FirstAssignment && token <= ts4.SyntaxKind.LastAssignment;
1905
+ return token >= ts.SyntaxKind.FirstAssignment && token <= ts.SyntaxKind.LastAssignment;
1903
1906
  }
1904
1907
  function recordIfIdentifierTarget(expression, assignedNames) {
1905
1908
  const target = unwrapParens(expression);
1906
- if (ts4.isIdentifier(target)) assignedNames.add(target.text);
1909
+ if (ts.isIdentifier(target)) assignedNames.add(target.text);
1907
1910
  }
1908
1911
  function recordAssignmentTargets(node, assignedNames) {
1909
- if (ts4.isBinaryExpression(node) && isAssignmentToken(node.operatorToken.kind)) {
1912
+ if (ts.isBinaryExpression(node) && isAssignmentToken(node.operatorToken.kind)) {
1910
1913
  recordIfIdentifierTarget(node.left, assignedNames);
1911
1914
  return;
1912
1915
  }
1913
- if (
1914
- // Widening this to `true` is behaviorally equivalent, not a real gap:
1915
- // only a prefix/postfix unary node carries an `.operator` at all, so on
1916
- // any other node the two `=== PlusPlus/MinusMinus` checks below both
1917
- // read `undefined` and fail. Hand-verified: mutating this compound to
1918
- // `if (true)` and running the real suite passes unchanged.
1919
- // Stryker disable next-line ConditionalExpression
1920
- (ts4.isPrefixUnaryExpression(node) || ts4.isPostfixUnaryExpression(node)) && (node.operator === ts4.SyntaxKind.PlusPlusToken || node.operator === ts4.SyntaxKind.MinusMinusToken)
1921
- ) {
1922
- recordIfIdentifierTarget(node.operand, assignedNames);
1916
+ const { operator, operand } = node;
1917
+ if (operator === ts.SyntaxKind.PlusPlusToken || operator === ts.SyntaxKind.MinusMinusToken) {
1918
+ recordIfIdentifierTarget(operand, assignedNames);
1923
1919
  return;
1924
1920
  }
1925
- if ((ts4.isForOfStatement(node) || ts4.isForInStatement(node)) && !ts4.isVariableDeclarationList(node.initializer)) {
1921
+ if ((ts.isForOfStatement(node) || ts.isForInStatement(node)) && !ts.isVariableDeclarationList(node.initializer)) {
1926
1922
  recordIfIdentifierTarget(node.initializer, assignedNames);
1927
1923
  }
1928
1924
  }
1929
1925
  function recordDeclarationIntroduction(node, countDeclaration, constAliasCandidates) {
1930
- if (ts4.isVariableDeclaration(node) || ts4.isParameter(node)) {
1926
+ if (ts.isVariableDeclaration(node) || ts.isParameter(node)) {
1931
1927
  forEachBindingName(node.name, countDeclaration);
1932
- if (!ts4.isVariableDeclaration(node) || !ts4.isIdentifier(node.name)) return;
1928
+ if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name)) return;
1933
1929
  if (node.initializer === void 0) return;
1934
1930
  const initializer = unwrapParens(node.initializer);
1935
- const isConst = (ts4.getCombinedNodeFlags(node) & ts4.NodeFlags.Const) !== 0;
1936
- if (isConst && ts4.isIdentifier(initializer)) {
1931
+ const isConst = (ts.getCombinedNodeFlags(node) & ts.NodeFlags.Const) !== 0;
1932
+ if (isConst && ts.isIdentifier(initializer)) {
1937
1933
  constAliasCandidates.push({
1938
1934
  aliasName: node.name.text,
1939
1935
  baseName: initializer.text,
@@ -1942,7 +1938,7 @@ function recordDeclarationIntroduction(node, countDeclaration, constAliasCandida
1942
1938
  }
1943
1939
  return;
1944
1940
  }
1945
- if ((ts4.isFunctionDeclaration(node) || ts4.isClassDeclaration(node)) && node.name) {
1941
+ if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) {
1946
1942
  countDeclaration(node.name.text);
1947
1943
  }
1948
1944
  }
@@ -1956,9 +1952,9 @@ function collectDeclarationFacts(sourceFile) {
1956
1952
  function walk(node) {
1957
1953
  recordDeclarationIntroduction(node, countDeclaration, constAliasCandidates);
1958
1954
  recordAssignmentTargets(node, assignedNames);
1959
- ts4.forEachChild(node, walk);
1955
+ ts.forEachChild(node, walk);
1960
1956
  }
1961
- ts4.forEachChild(sourceFile, walk);
1957
+ ts.forEachChild(sourceFile, walk);
1962
1958
  return { declarationCounts, assignedNames, constAliasCandidates };
1963
1959
  }
1964
1960
  function resolveAliasTargets(candidates, declarationCounts, assignedNames, imports) {
@@ -1983,21 +1979,22 @@ function bindingElementKey(element) {
1983
1979
  if (element.propertyName === void 0) {
1984
1980
  return element.name.text;
1985
1981
  }
1986
- if (ts4.isIdentifier(element.propertyName) || ts4.isStringLiteral(element.propertyName)) {
1982
+ if (ts.isIdentifier(element.propertyName) || ts.isStringLiteral(element.propertyName)) {
1987
1983
  return element.propertyName.text;
1988
1984
  }
1989
- if (ts4.isComputedPropertyName(element.propertyName)) {
1985
+ if (ts.isComputedPropertyName(element.propertyName)) {
1990
1986
  const inner = element.propertyName.expression;
1991
- return ts4.isStringLiteralLike(inner) ? inner.text : inner;
1987
+ return ts.isStringLiteralLike(inner) ? inner.text : inner;
1992
1988
  }
1993
1989
  return element.propertyName;
1994
1990
  }
1995
1991
  function scanFileForDependencies(filePath, sourceText) {
1996
- const scriptKind = filePath.endsWith(".tsx") ? ts4.ScriptKind.TSX : ts4.ScriptKind.TS;
1997
- const sourceFile = ts4.createSourceFile(
1992
+ assertCompilerApi(ts);
1993
+ const scriptKind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
1994
+ const sourceFile = ts.createSourceFile(
1998
1995
  filePath,
1999
1996
  sourceText,
2000
- ts4.ScriptTarget.Latest,
1997
+ ts.ScriptTarget.Latest,
2001
1998
  // Load-bearing, unlike before: `ts.getCombinedNodeFlags()` (used to tell
2002
1999
  // a `const` declaration apart from `let`/`var` when resolving alias
2003
2000
  // candidates) walks parent pointers internally. Flipping this to `false`
@@ -2009,9 +2006,9 @@ function scanFileForDependencies(filePath, sourceText) {
2009
2006
  const imports = /* @__PURE__ */ new Map();
2010
2007
  let hasWildcardReExport = false;
2011
2008
  for (const statement of sourceFile.statements) {
2012
- if (ts4.isImportDeclaration(statement)) {
2009
+ if (ts.isImportDeclaration(statement)) {
2013
2010
  collectImportBindings(statement, imports);
2014
- } else if (ts4.isExportDeclaration(statement) && !statement.exportClause && statement.moduleSpecifier) {
2011
+ } else if (ts.isExportDeclaration(statement) && !statement.exportClause && statement.moduleSpecifier) {
2015
2012
  hasWildcardReExport = true;
2016
2013
  }
2017
2014
  }
@@ -2042,7 +2039,7 @@ function scanFileForDependencies(filePath, sourceText) {
2042
2039
  for (const element of pattern.elements) {
2043
2040
  if (element.dotDotDotToken) {
2044
2041
  record(localName, { kind: "escape", via: "rest", ...positionOf(sourceFile, element) });
2045
- } else if (!ts4.isIdentifier(element.name)) {
2042
+ } else if (!ts.isIdentifier(element.name)) {
2046
2043
  record(localName, {
2047
2044
  kind: "escape",
2048
2045
  via: "nested-pattern",
@@ -2058,17 +2055,17 @@ function scanFileForDependencies(filePath, sourceText) {
2058
2055
  via: "computed-key",
2059
2056
  ...positionOf(sourceFile, element)
2060
2057
  });
2061
- ts4.forEachChild(key, visit);
2058
+ ts.forEachChild(key, visit);
2062
2059
  }
2063
2060
  }
2064
- if (element.initializer) ts4.forEachChild(element.initializer, visit);
2061
+ ts.forEachChild(element.initializer, visit);
2065
2062
  }
2066
2063
  }
2067
2064
  function tryRecordPropertyOrElementAccess(node) {
2068
- const isProperty = ts4.isPropertyAccessExpression(node);
2069
- if (!isProperty && !ts4.isElementAccessExpression(node)) return false;
2065
+ const isProperty = ts.isPropertyAccessExpression(node);
2066
+ if (!isProperty && !ts.isElementAccessExpression(node)) return false;
2070
2067
  const base = unwrapParens(node.expression);
2071
- if (!ts4.isIdentifier(base) || !imports.has(base.text)) return false;
2068
+ if (!ts.isIdentifier(base) || !imports.has(base.text)) return false;
2072
2069
  if (isProperty) {
2073
2070
  record(base.text, { kind: "member", member: node.name.text, ...positionOf(sourceFile, node) });
2074
2071
  return true;
@@ -2078,28 +2075,28 @@ function scanFileForDependencies(filePath, sourceText) {
2078
2075
  base.text,
2079
2076
  key !== void 0 ? { kind: "member", member: key, ...positionOf(sourceFile, node) } : { kind: "dynamic", ...positionOf(sourceFile, node) }
2080
2077
  );
2081
- ts4.forEachChild(node.argumentExpression, visit);
2078
+ ts.forEachChild(node.argumentExpression, visit);
2082
2079
  return true;
2083
2080
  }
2084
2081
  function visit(node) {
2085
- if (ts4.isImportDeclaration(node) || ts4.isExportDeclaration(node) || ts4.isVariableDeclaration(node) && handledDeclarations.has(node)) {
2082
+ if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node) || ts.isVariableDeclaration(node) && handledDeclarations.has(node)) {
2086
2083
  return;
2087
2084
  }
2088
- if (ts4.isVariableDeclaration(node) && ts4.isObjectBindingPattern(node.name) && node.initializer) {
2085
+ if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer) {
2089
2086
  const base = unwrapParens(node.initializer);
2090
- if (ts4.isIdentifier(base) && imports.has(base.text)) {
2087
+ if (ts.isIdentifier(base) && imports.has(base.text)) {
2091
2088
  recordObjectBindingAccesses(node.name, base.text);
2092
2089
  return;
2093
2090
  }
2094
2091
  }
2095
2092
  if (tryRecordPropertyOrElementAccess(node)) return;
2096
- if (ts4.isIdentifier(node) && imports.has(node.text)) {
2093
+ if (ts.isIdentifier(node) && imports.has(node.text)) {
2097
2094
  record(node.text, { kind: "reference", ...positionOf(sourceFile, node) });
2098
2095
  return;
2099
2096
  }
2100
- ts4.forEachChild(node, visit);
2097
+ ts.forEachChild(node, visit);
2101
2098
  }
2102
- ts4.forEachChild(sourceFile, visit);
2099
+ ts.forEachChild(sourceFile, visit);
2103
2100
  return { file: filePath, imports, accessesByLocalName: accesses, hasWildcardReExport };
2104
2101
  }
2105
2102
 
@@ -2107,8 +2104,11 @@ function scanFileForDependencies(filePath, sourceText) {
2107
2104
  function generatedFileMarker() {
2108
2105
  return "GENERATED FILE";
2109
2106
  }
2110
- function generatedBanner(format = "ts") {
2111
- const text = `${generatedFileMarker()} -- do not edit by hand. Run \`npx env-cap\` to regenerate.`;
2107
+ function reportRegenerateHint() {
2108
+ return "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`.";
2109
+ }
2110
+ function generatedBanner(format = "ts", regenerate = "Run `npx env-cap` to regenerate.") {
2111
+ const text = `${generatedFileMarker()} -- do not edit by hand. ${regenerate}`;
2112
2112
  return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2113
2113
  }
2114
2114
  function isGeneratedFile(content) {
@@ -2119,7 +2119,7 @@ function evidenceDisclaimer() {
2119
2119
  return "Machine-generated engineering artifact assembled from statically-provable code facts and author-declared documentation. It can support a security, privacy, or compliance review. It does not itself establish compliance with any standard.";
2120
2120
  }
2121
2121
  function evidenceProjectionNote(evidencePath) {
2122
- const concept = "Projected from env-cap's Evidence Model (ADR 0031/0038), the same source every other generated artifact draws from.";
2122
+ const concept = "Projected from env-cap's Evidence Model (https://github.com/MaverickCER/env-cap/blob/main/GUIDE.md), the same source every other generated artifact draws from.";
2123
2123
  return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2124
2124
  }
2125
2125
 
@@ -2230,8 +2230,7 @@ async function buildDependencyGraph(contracts, scanFiles, readFile, context, sca
2230
2230
  for (const scan of scanResults) {
2231
2231
  for (const [localName, binding] of scan.imports) {
2232
2232
  const resolvedFile = await resolveImportSpecifier(scan.file, binding.specifier, context);
2233
- if (!resolvedFile) continue;
2234
- const building = byIdentity2.get(`${resolvedFile}#${binding.importedName}`);
2233
+ const building = byIdentity2.get(`${String(resolvedFile)}#${binding.importedName}`);
2235
2234
  if (!building) continue;
2236
2235
  building.imported = true;
2237
2236
  building.consumingFiles.add(scan.file);
@@ -2241,8 +2240,7 @@ async function buildDependencyGraph(contracts, scanFiles, readFile, context, sca
2241
2240
  for (const scan of scanResults) {
2242
2241
  for (const [, binding] of scan.imports) {
2243
2242
  const resolvedFile = await resolveImportSpecifier(scan.file, binding.specifier, context);
2244
- if (!resolvedFile) continue;
2245
- const targetScan = scanByFile.get(resolvedFile);
2243
+ const targetScan = scanByFile.get(String(resolvedFile));
2246
2244
  if (!targetScan?.hasWildcardReExport) continue;
2247
2245
  for (const building of byIdentity2.values()) {
2248
2246
  if (building.imported) continue;
@@ -2345,20 +2343,9 @@ async function buildDependencyModel(contracts, scanFiles, readFile, context, roo
2345
2343
  positions: info.positions.map((p) => relativizePosition2(root, p)),
2346
2344
  dynamicAccessAssertions: info.dynamicAccessAssertions
2347
2345
  })).sort((a, b) => a.key.localeCompare(b.key)),
2348
- // `.sort()` here (and the whole `.map(...).sort()` chain as one
2349
- // `MethodExpression` unit) is a defensive no-op, not a real gap:
2350
- // dependency-graph.ts's own `consumingFiles` is already
2351
- // `[...building.consumingFiles].sort()` before this projection ever
2352
- // sees it (see that file's own comment). Hand-verified: dropping this
2353
- // `.sort()` and running the real suite passes unchanged -- confirmed
2354
- // again 2026-09-18 against CI's own diagnostic mutation report, which
2355
- // flagged this exact `MethodExpression` mutant as Survived.
2356
- // Stryker disable next-line MethodExpression
2346
+ // Sorted after mapping to display paths: a file outside `root` (a package surface) shows as
2347
+ // `../...`, which can order differently from its absolute path.
2357
2348
  consumingFiles: [...contract.consumingFiles].map((f) => displayPath(root, f)).sort(),
2358
- // Same reasoning as `consumingFiles` just above -- the whole
2359
- // `.map(...).sort()` chain is a coarser-grained `MethodExpression`
2360
- // mutant target than the next-line one on `.sort()` alone just below.
2361
- // Stryker disable next-line MethodExpression
2362
2349
  ambiguousBarrelFiles: [...contract.ambiguousBarrelFiles].map((f) => displayPath(root, f)).sort(),
2363
2350
  dynamicAccessSites: contract.dynamicAccessSites.map((p) => relativizePosition2(root, p))
2364
2351
  }));
@@ -2512,30 +2499,11 @@ function renderManifest(contracts, outputFile) {
2512
2499
  for (const contract of sorted) {
2513
2500
  let localName = contract.exportName;
2514
2501
  if (usedNames.has(localName)) {
2515
- const maxSuffix = sorted.length + 16;
2516
- let found;
2517
- let passes = 0;
2518
- for (let suffix = 1; suffix <= maxSuffix; suffix++) {
2519
- passes++;
2520
- if (passes > maxSuffix) {
2521
- throw new Error(
2522
- // Stryker disable next-line StringLiteral
2523
- `renderManifest: exceeded ${String(maxSuffix)} attempts choosing a unique local import name for "${contract.exportName}" -- this should never happen and indicates an internal naming bug.`
2524
- );
2525
- }
2526
- const candidate = `${contract.exportName}_${suffix}`;
2527
- if (!usedNames.has(candidate)) {
2528
- found = candidate;
2529
- break;
2530
- }
2531
- }
2532
- if (found === void 0) {
2533
- throw new Error(
2534
- // Stryker disable next-line StringLiteral
2535
- `renderManifest: could not find a unique local import name for "${contract.exportName}" within ${String(maxSuffix)} attempts -- this should never happen and indicates an internal naming bug.`
2536
- );
2537
- }
2538
- localName = found;
2502
+ const candidates = Array.from(
2503
+ { length: usedNames.size + 1 },
2504
+ (_, index) => `${contract.exportName}_${index + 1}`
2505
+ );
2506
+ localName = String(candidates.find((candidate) => !usedNames.has(candidate)));
2539
2507
  }
2540
2508
  usedNames.add(localName);
2541
2509
  referenceNames.push(localName);
@@ -2584,10 +2552,8 @@ function defaultExclude() {
2584
2552
  // inspect `exclude` directly, and as defense if that hardcoding ever
2585
2553
  // changes) -- hand-verified: emptying both and running the full
2586
2554
  // `vitest run` leaves all 1243 tests passing.
2587
- // Stryker disable next-line StringLiteral
2588
2555
  "**/node_modules/**",
2589
2556
  "**/dist/**",
2590
- // Stryker disable next-line StringLiteral
2591
2557
  "**/.git/**"
2592
2558
  ];
2593
2559
  }
@@ -2617,8 +2583,6 @@ async function generateEnvManifest(options) {
2617
2583
  const root = path6.resolve(options.root ?? process.cwd());
2618
2584
  const include = options.include ?? defaultInclude();
2619
2585
  const exclude = options.exclude ?? defaultExclude();
2620
- const packages = options.packages ?? [];
2621
- const onIncompatibility = options.onIncompatibility ?? "warn";
2622
2586
  const locationResult = resolveWithinRoot(
2623
2587
  root,
2624
2588
  options.location,
@@ -2632,10 +2596,10 @@ async function generateEnvManifest(options) {
2632
2596
  root,
2633
2597
  include,
2634
2598
  exclude,
2635
- packages,
2599
+ packages: options.packages,
2636
2600
  tsconfig: options.tsconfig
2637
2601
  });
2638
- const computed = computeManifest(root, linkResult, onIncompatibility);
2602
+ const computed = computeManifest(root, linkResult, options.onIncompatibility);
2639
2603
  if (computed.blocking.length > 0) throw new EnvManifestGenerationError(computed.blocking);
2640
2604
  await writeManifest(outputPath, computed.activeContracts, options.fs);
2641
2605
  return {
@@ -2775,7 +2739,7 @@ function renderParseWarnings(warnings) {
2775
2739
  }
2776
2740
  function renderUsageReport(computed) {
2777
2741
  const lines = [
2778
- generatedBanner("markdown"),
2742
+ generatedBanner("markdown", reportRegenerateHint()),
2779
2743
  "",
2780
2744
  `> ${evidenceDisclaimer()}`,
2781
2745
  "",
@@ -2783,7 +2747,7 @@ function renderUsageReport(computed) {
2783
2747
  "",
2784
2748
  "# Dependency & Ownership Report",
2785
2749
  "",
2786
- "_Produced by `env-cap --ownership`._",
2750
+ "_Produced by `generateUsageReport()` from `@maverickcer/env-cap/build`._",
2787
2751
  "",
2788
2752
  "Which feature owns each variable, which features consume that contract, and what the blast radius is if it changes.",
2789
2753
  "",
@@ -2795,7 +2759,7 @@ function renderUsageReport(computed) {
2795
2759
  ...renderAsserted(computed.asserted),
2796
2760
  ...renderParseWarnings(computed.parseWarnings)
2797
2761
  ];
2798
- return lines.join("\n").replace(/\n{3,}/g, "\n\n");
2762
+ return lines.join("\n");
2799
2763
  }
2800
2764
 
2801
2765
  // src/build/generate-usage.ts
@@ -2826,7 +2790,7 @@ async function computeScanSurface(root, exclude, origins, fs) {
2826
2790
  }
2827
2791
  return { scanFiles, scannedSurfaces };
2828
2792
  }
2829
- async function computeUsage(root, contracts, scanFiles, readFile, context, parseWarnings, scannedSurfaces, dynamicAccessAcknowledgments) {
2793
+ async function computeUsage(root, contracts, scanFiles, readFile, context, scannedSurfaces, dynamicAccessAcknowledgments) {
2830
2794
  const graph = await buildDependencyGraph(
2831
2795
  contracts,
2832
2796
  scanFiles,
@@ -2839,13 +2803,9 @@ async function computeUsage(root, contracts, scanFiles, readFile, context, parse
2839
2803
  const contractByIdentity = /* @__PURE__ */ new Map();
2840
2804
  for (const contract of contracts)
2841
2805
  contractByIdentity.set(`${contract.file}#${contract.exportName}`, contract);
2842
- const ownerFor = (file, exportName) => (
2843
- // Stryker disable next-line OptionalChaining
2844
- contractByIdentity.get(`${file}#${exportName}`)?.owner
2845
- );
2806
+ const ownerFor = (file, exportName) => mustGet(contractByIdentity, `${file}#${exportName}`).owner;
2846
2807
  const effectiveOwnerFor = (file, exportName, key) => {
2847
- const contract = contractByIdentity.get(`${file}#${exportName}`);
2848
- if (!contract) return void 0;
2808
+ const contract = mustGet(contractByIdentity, `${file}#${exportName}`);
2849
2809
  const variable = contract.variables.find((v) => v.key === key);
2850
2810
  return variable ? effectiveOwner(contract, variable) : contract.owner;
2851
2811
  };
@@ -2871,19 +2831,16 @@ async function computeUsage(root, contracts, scanFiles, readFile, context, parse
2871
2831
  const staleOrMissingCitationsFor = (contractName, file, exportName, key) => {
2872
2832
  const relativeFile = displayPath(root, file);
2873
2833
  const identity = dynamicAccessVariableIdentity(relativeFile, exportName, key);
2874
- const problems = [];
2875
- for (const a of dynamicAccessAcknowledgments?.get(identity) ?? []) {
2876
- if (a.acknowledgment === "fresh") continue;
2877
- problems.push({
2834
+ return (dynamicAccessAcknowledgments?.get(identity) ?? []).map(
2835
+ (a) => ({
2878
2836
  contractName,
2879
2837
  file: relativeFile,
2880
2838
  exportName,
2881
2839
  key,
2882
2840
  position: { file: a.file, line: a.line, column: a.column },
2883
2841
  acknowledgment: a.acknowledgment
2884
- });
2885
- }
2886
- return problems;
2842
+ })
2843
+ );
2887
2844
  };
2888
2845
  const unconsumedOwnedVariables = findings.unconsumedOwned.map(
2889
2846
  (f) => ({
@@ -2928,7 +2885,6 @@ async function computeUsage(root, contracts, scanFiles, readFile, context, parse
2928
2885
  unconsumedOwnedVariables,
2929
2886
  indeterminate,
2930
2887
  asserted,
2931
- parseWarnings,
2932
2888
  scannedSurfaces: graph.scannedSurfaces
2933
2889
  }
2934
2890
  };
@@ -2942,24 +2898,23 @@ async function generateUsageReport(options) {
2942
2898
  const root = path6.resolve(options.root ?? process.cwd());
2943
2899
  const include = options.include ?? defaultInclude();
2944
2900
  const exclude = options.exclude ?? defaultExclude();
2945
- const packages = options.packages ?? [];
2946
2901
  let reportPath;
2947
2902
  if (options.report) {
2948
- const result = resolveWithinRoot(
2903
+ const result2 = resolveWithinRoot(
2949
2904
  root,
2950
2905
  options.report.location,
2951
2906
  "report.location",
2952
2907
  "generateUsageReport"
2953
2908
  );
2954
- if (!result.ok) throw new EnvUsageAnalysisError([result.issue]);
2955
- reportPath = result.resolved;
2909
+ if (!result2.ok) throw new EnvUsageAnalysisError([result2.issue]);
2910
+ reportPath = result2.resolved;
2956
2911
  }
2957
2912
  const { readFileCached, linkResult, context, origins, packageWarnings, tsconfigWarnings } = await assembleProject({
2958
2913
  fs: options.fs,
2959
2914
  root,
2960
2915
  include,
2961
2916
  exclude,
2962
- packages,
2917
+ packages: options.packages,
2963
2918
  tsconfig: options.tsconfig
2964
2919
  });
2965
2920
  const { scanFiles, scannedSurfaces } = await computeScanSurface(
@@ -2974,11 +2929,14 @@ async function generateUsageReport(options) {
2974
2929
  scanFiles,
2975
2930
  readFileCached,
2976
2931
  context,
2977
- [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings],
2978
2932
  scannedSurfaces
2979
2933
  );
2980
- if (reportPath) await writeUsageReport(reportPath, computed.result, options.fs);
2981
- return { reportPath, ...computed.result };
2934
+ const result = {
2935
+ ...computed.result,
2936
+ parseWarnings: [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings]
2937
+ };
2938
+ if (reportPath) await writeUsageReport(reportPath, result, options.fs);
2939
+ return { reportPath, ...result };
2982
2940
  }
2983
2941
 
2984
2942
  // src/build/finding-model.ts
@@ -3292,107 +3250,132 @@ function groupVariablesByOwner(contracts, ownerOf) {
3292
3250
  }
3293
3251
  return byOwner;
3294
3252
  }
3295
- var configurationReference = defineEvidenceProjection({
3296
- // Stryker disable next-line ArrowFunction
3297
- disclaimer: () => evidenceDisclaimer(),
3298
- entries: (evidence) => {
3299
- const entries = [];
3300
- for (const contract of evidence.contract.contracts) {
3301
- for (const variable of contract.variables) {
3302
- entries.push({
3303
- file: contract.file,
3304
- exportName: contract.exportName,
3305
- contractName: contract.contractName,
3306
- key: variable.key,
3307
- description: variable.description,
3308
- owner: variable.owner ?? contract.owner,
3309
- sensitivity: variable.sensitivity ?? contract.sensitivity,
3310
- required: variable.required,
3311
- hasDefault: variable.hasDefault,
3312
- hasProcessor: variable.hasProcessor,
3313
- hasValidator: variable.hasValidator,
3314
- expiresAt: variable.expiresAt,
3315
- active: contract.active
3316
- });
3253
+ function configurationReference(evidence) {
3254
+ return projectConfigurationReference(evidence).value;
3255
+ }
3256
+ configurationReference.project = projectConfigurationReference;
3257
+ function projectConfigurationReference(evidence) {
3258
+ return defineEvidenceProjection(configurationReferenceSchema()).project(evidence);
3259
+ }
3260
+ function configurationReferenceSchema() {
3261
+ return {
3262
+ disclaimer: evidenceDisclaimer,
3263
+ entries: (evidence) => {
3264
+ const entries = [];
3265
+ for (const contract of evidence.contract.contracts) {
3266
+ for (const variable of contract.variables) {
3267
+ entries.push({
3268
+ file: contract.file,
3269
+ exportName: contract.exportName,
3270
+ contractName: contract.contractName,
3271
+ key: variable.key,
3272
+ description: variable.description,
3273
+ owner: variable.owner ?? contract.owner,
3274
+ sensitivity: variable.sensitivity ?? contract.sensitivity,
3275
+ required: variable.required,
3276
+ hasDefault: variable.hasDefault,
3277
+ hasProcessor: variable.hasProcessor,
3278
+ hasValidator: variable.hasValidator,
3279
+ expiresAt: variable.expiresAt,
3280
+ active: contract.active
3281
+ });
3282
+ }
3317
3283
  }
3284
+ return entries.sort(byContractThenKey);
3318
3285
  }
3319
- return entries.sort(byContractThenKey);
3320
- }
3321
- });
3322
- var ownershipSummary = defineEvidenceProjection({
3323
- // Stryker disable next-line ArrowFunction
3324
- disclaimer: () => evidenceDisclaimer(),
3325
- owners: (evidence) => {
3326
- const contracts = contractIndex(evidence.contract.contracts);
3327
- const nameOf = (file, exportName) => contracts.get(`${file}#${exportName}`)?.contractName ?? exportName;
3328
- const variablesByOwner = groupVariablesByOwner(
3329
- evidence.ownership.contracts,
3330
- (_contract, variable) => variable.owner
3331
- );
3332
- const contractsByOwner = /* @__PURE__ */ new Map();
3333
- for (const contract of evidence.ownership.contracts) {
3334
- if (contract.owner === void 0) continue;
3335
- const list = contractsByOwner.get(contract.owner) ?? [];
3336
- list.push(nameOf(contract.file, contract.exportName));
3337
- contractsByOwner.set(contract.owner, list);
3286
+ };
3287
+ }
3288
+ function ownershipSummary(evidence) {
3289
+ return projectOwnershipSummary(evidence).value;
3290
+ }
3291
+ ownershipSummary.project = projectOwnershipSummary;
3292
+ function projectOwnershipSummary(evidence) {
3293
+ return defineEvidenceProjection(ownershipSummarySchema()).project(evidence);
3294
+ }
3295
+ function ownershipSummarySchema() {
3296
+ return {
3297
+ disclaimer: evidenceDisclaimer,
3298
+ owners: (evidence) => {
3299
+ const contracts = contractIndex(evidence.contract.contracts);
3300
+ const nameOf = (file, exportName) => contracts.get(`${file}#${exportName}`)?.contractName ?? exportName;
3301
+ const variablesByOwner = groupVariablesByOwner(
3302
+ evidence.ownership.contracts,
3303
+ (_contract, variable) => variable.owner
3304
+ );
3305
+ const contractsByOwner = /* @__PURE__ */ new Map();
3306
+ for (const contract of evidence.ownership.contracts) {
3307
+ if (contract.owner === void 0) continue;
3308
+ const list = contractsByOwner.get(contract.owner) ?? [];
3309
+ list.push(nameOf(contract.file, contract.exportName));
3310
+ contractsByOwner.set(contract.owner, list);
3311
+ }
3312
+ const owners = /* @__PURE__ */ new Set([...variablesByOwner.keys(), ...contractsByOwner.keys()]);
3313
+ return [...owners].sort().map((owner) => ({
3314
+ owner,
3315
+ variables: (variablesByOwner.get(owner) ?? []).map(
3316
+ ({ contract, variable }) => `${nameOf(contract.file, contract.exportName)}.${variable.key}`
3317
+ ).sort(),
3318
+ contracts: (contractsByOwner.get(owner) ?? []).sort()
3319
+ }));
3320
+ },
3321
+ unowned: (evidence) => {
3322
+ const contracts = contractIndex(evidence.contract.contracts);
3323
+ return evidence.ownership.unownedVariables.map((ref) => {
3324
+ const contractName = contracts.get(`${ref.file}#${ref.exportName}`)?.contractName ?? ref.exportName;
3325
+ return `${contractName}.${ref.key}`;
3326
+ }).sort();
3338
3327
  }
3339
- const owners = /* @__PURE__ */ new Set([...variablesByOwner.keys(), ...contractsByOwner.keys()]);
3340
- return [...owners].sort().map((owner) => ({
3341
- owner,
3342
- variables: (variablesByOwner.get(owner) ?? []).map(
3343
- ({ contract, variable }) => `${nameOf(contract.file, contract.exportName)}.${variable.key}`
3344
- ).sort(),
3345
- contracts: (contractsByOwner.get(owner) ?? []).sort()
3346
- }));
3347
- },
3348
- unowned: (evidence) => {
3349
- const contracts = contractIndex(evidence.contract.contracts);
3350
- return evidence.ownership.unownedVariables.map((ref) => {
3351
- const contractName = contracts.get(`${ref.file}#${ref.exportName}`)?.contractName ?? ref.exportName;
3352
- return `${contractName}.${ref.key}`;
3353
- }).sort();
3354
- }
3355
- });
3356
- var expiringSoonReport = defineEvidenceProjection({
3357
- // Stryker disable next-line ArrowFunction
3358
- disclaimer: () => evidenceDisclaimer(),
3359
- entries: (evidence) => {
3360
- const contracts = contractIndex(evidence.contract.contracts);
3361
- const ownerByVariable = /* @__PURE__ */ new Map();
3362
- for (const contract of evidence.ownership.contracts)
3363
- for (const variable of contract.variables)
3364
- ownerByVariable.set(
3365
- `${contract.file}#${contract.exportName}#${variable.key}`,
3366
- variable.owner
3367
- );
3368
- return evidence.lifecycle.expiring.map((entry) => {
3369
- const contract = contracts.get(`${entry.file}#${entry.exportName}`);
3370
- const variable = entry.key === void 0 ? void 0 : contract?.variables.find((v) => v.key === entry.key);
3371
- return {
3372
- file: entry.file,
3373
- exportName: entry.exportName,
3374
- contractName: contract?.contractName ?? entry.exportName,
3375
- key: entry.key,
3376
- expiresAt: entry.expiresAt,
3377
- daysRemaining: entry.daysRemaining,
3378
- expired: entry.daysRemaining < 0,
3379
- refreshInstructions: variable?.refreshInstructions,
3380
- owner: entry.key === void 0 ? contract?.owner : ownerByVariable.get(`${entry.file}#${entry.exportName}#${entry.key}`) ?? contract?.owner
3381
- };
3382
- });
3383
- },
3384
- // Same static covered-mutant false-Survivor as the `disclaimer` arrows
3385
- // above -- hand-verified killed (mutating this whole arrow to `() =>
3386
- // undefined` fails the "expiredCount" assertions in every test above).
3387
- // Stryker disable next-line ArrowFunction
3388
- expiredCount: (evidence) => evidence.lifecycle.expiring.filter((e) => e.daysRemaining < 0).length
3389
- });
3328
+ };
3329
+ }
3330
+ function expiringSoonReport(evidence) {
3331
+ return projectExpiringSoonReport(evidence).value;
3332
+ }
3333
+ expiringSoonReport.project = projectExpiringSoonReport;
3334
+ function projectExpiringSoonReport(evidence) {
3335
+ return defineEvidenceProjection(expiringSoonReportSchema()).project(evidence);
3336
+ }
3337
+ function expiringSoonReportSchema() {
3338
+ return {
3339
+ disclaimer: evidenceDisclaimer,
3340
+ entries: (evidence) => {
3341
+ const contracts = contractIndex(evidence.contract.contracts);
3342
+ const ownerByVariable = /* @__PURE__ */ new Map();
3343
+ for (const contract of evidence.ownership.contracts)
3344
+ for (const variable of contract.variables)
3345
+ ownerByVariable.set(
3346
+ `${contract.file}#${contract.exportName}#${variable.key}`,
3347
+ variable.owner
3348
+ );
3349
+ return evidence.lifecycle.expiring.map((entry) => {
3350
+ const contract = contracts.get(`${entry.file}#${entry.exportName}`);
3351
+ const variable = contract?.variables.find((v) => v.key === entry.key);
3352
+ return {
3353
+ file: entry.file,
3354
+ exportName: entry.exportName,
3355
+ contractName: contract?.contractName ?? entry.exportName,
3356
+ key: entry.key,
3357
+ expiresAt: entry.expiresAt,
3358
+ daysRemaining: entry.daysRemaining,
3359
+ expired: entry.daysRemaining < 0,
3360
+ refreshInstructions: variable?.refreshInstructions,
3361
+ owner: entry.key === void 0 ? contract?.owner : ownerByVariable.get(`${entry.file}#${entry.exportName}#${entry.key}`) ?? contract?.owner
3362
+ };
3363
+ });
3364
+ },
3365
+ expiredCount: (evidence) => evidence.lifecycle.expiring.filter((e) => e.daysRemaining < 0).length
3366
+ };
3367
+ }
3390
3368
 
3391
3369
  // src/build/docs.ts
3392
3370
  function parseIsoDate(value) {
3393
3371
  const date = new Date(value);
3394
3372
  return Number.isNaN(date.getTime()) ? void 0 : date;
3395
3373
  }
3374
+ function parseExpiry(expiresAt) {
3375
+ const raw = String(expiresAt);
3376
+ const date = parseIsoDate(raw);
3377
+ return date && { raw, date };
3378
+ }
3396
3379
  var MS_PER_DAY = 864e5;
3397
3380
  function daysRemainingFrom(date, now) {
3398
3381
  return Math.ceil((date.getTime() - now.getTime()) / MS_PER_DAY);
@@ -3400,32 +3383,29 @@ function daysRemainingFrom(date, now) {
3400
3383
  function computeExpiringEntries(contracts, expiringWithinDays, now) {
3401
3384
  const entries = [];
3402
3385
  for (const contract of contracts) {
3403
- if (contract.expiresAt) {
3404
- const date = parseIsoDate(contract.expiresAt);
3405
- if (date) {
3406
- const daysRemaining = daysRemainingFrom(date, now);
3407
- if (daysRemaining <= expiringWithinDays) {
3408
- entries.push({
3409
- file: contract.file,
3410
- exportName: contract.exportName,
3411
- key: void 0,
3412
- expiresAt: contract.expiresAt,
3413
- daysRemaining
3414
- });
3415
- }
3386
+ const contractExpiry = parseExpiry(contract.expiresAt);
3387
+ if (contractExpiry) {
3388
+ const daysRemaining = daysRemainingFrom(contractExpiry.date, now);
3389
+ if (daysRemaining <= expiringWithinDays) {
3390
+ entries.push({
3391
+ file: contract.file,
3392
+ exportName: contract.exportName,
3393
+ key: void 0,
3394
+ expiresAt: contractExpiry.raw,
3395
+ daysRemaining
3396
+ });
3416
3397
  }
3417
3398
  }
3418
3399
  for (const variable of contract.variables) {
3419
- if (!variable.expiresAt) continue;
3420
- const date = parseIsoDate(variable.expiresAt);
3421
- if (!date) continue;
3422
- const daysRemaining = daysRemainingFrom(date, now);
3400
+ const expiry = parseExpiry(variable.expiresAt);
3401
+ if (!expiry) continue;
3402
+ const daysRemaining = daysRemainingFrom(expiry.date, now);
3423
3403
  if (daysRemaining <= expiringWithinDays) {
3424
3404
  entries.push({
3425
3405
  file: contract.file,
3426
3406
  exportName: contract.exportName,
3427
3407
  key: variable.key,
3428
- expiresAt: variable.expiresAt,
3408
+ expiresAt: expiry.raw,
3429
3409
  daysRemaining
3430
3410
  });
3431
3411
  }
@@ -3476,7 +3456,7 @@ function buildCatalog(contracts) {
3476
3456
  function extractPreviouslyDocumentedKeys(previousContent) {
3477
3457
  const keys = /* @__PURE__ */ new Set();
3478
3458
  for (const match of previousContent.matchAll(/^### `([A-Za-z_][A-Za-z0-9_]*)`$/gm)) {
3479
- if (match[1]) keys.add(match[1]);
3459
+ keys.add(String(match[1]));
3480
3460
  }
3481
3461
  return keys;
3482
3462
  }
@@ -3516,7 +3496,7 @@ function computeChangeSummary(contracts, previousContent) {
3516
3496
  };
3517
3497
  }
3518
3498
  function slugify(text) {
3519
- return text.toLowerCase().replace(/[^a-z0-9_]+/g, "-").replace(/^-+|-+$/g, "") || "section";
3499
+ return text.toLowerCase().replace(/[^a-z0-9_]+/g, "-").replace(/^-|-$/g, "") || "section";
3520
3500
  }
3521
3501
  var AnchorRegistry = class {
3522
3502
  constructor() {
@@ -3533,16 +3513,24 @@ var AnchorRegistry = class {
3533
3513
  this.assigned.set(target, anchor);
3534
3514
  return anchor;
3535
3515
  }
3516
+ /** The anchor an earlier {@link anchorFor} call assigned to `target`; throws if there was none. */
3517
+ anchorOf(target) {
3518
+ return mustGet(this.assigned, target);
3519
+ }
3536
3520
  };
3537
3521
  function mdLink(text, anchor) {
3538
3522
  return `[${text}](#${anchor})`;
3539
3523
  }
3524
+ function sortedByKey(items) {
3525
+ const byKey = new Map(items.map((item) => [item.key, item]));
3526
+ return [...byKey.keys()].sort().map((key) => mustGet(byKey, key));
3527
+ }
3540
3528
  function sortedContracts(contracts) {
3541
3529
  return [...contracts].sort((a, b) => a.contractName.localeCompare(b.contractName));
3542
3530
  }
3543
3531
  function renderHeader(contracts, options, anchors, hasOwnership, hasDuplicates, hasLifecycle) {
3544
3532
  const lines = [
3545
- generatedBanner("markdown"),
3533
+ generatedBanner("markdown", reportRegenerateHint()),
3546
3534
  "",
3547
3535
  `> ${evidenceDisclaimer()}`,
3548
3536
  "",
@@ -3550,7 +3538,7 @@ function renderHeader(contracts, options, anchors, hasOwnership, hasDuplicates,
3550
3538
  "",
3551
3539
  "# Environment Variables",
3552
3540
  "",
3553
- "_Produced by `env-cap --docs`._",
3541
+ "_Produced by `generateDocumentation()` from `@maverickcer/env-cap/build`._",
3554
3542
  "",
3555
3543
  `_Generated ${options.generatedAt.toISOString()}_`,
3556
3544
  ""
@@ -3593,7 +3581,7 @@ function renderCatalog(contracts, anchors, undocumented) {
3593
3581
  );
3594
3582
  }
3595
3583
  for (const contract of sortedContracts(contracts)) {
3596
- lines.push(`<a id="${anchors.anchorFor(contract, `contract-${contract.contractName}`)}"></a>`);
3584
+ lines.push(`<a id="${anchors.anchorOf(contract)}"></a>`);
3597
3585
  lines.push(`## ${contract.contractName}`, "", `Source: \`${contract.file}\``);
3598
3586
  if (undocumentedByIdentity.has(`${contract.file}#${contract.exportName}`)) {
3599
3587
  lines.push("", "> \u26A0\uFE0F **Undocumented.** No `documentEnv()` call is linked to this contract.");
@@ -3618,10 +3606,8 @@ function renderCatalog(contracts, anchors, undocumented) {
3618
3606
  }
3619
3607
  }
3620
3608
  lines.push("");
3621
- for (const variable of [...contract.variables].sort((a, b) => a.key < b.key ? -1 : 1)) {
3622
- lines.push(
3623
- `<a id="${anchors.anchorFor(variable, `${contract.contractName}-${variable.key}`)}"></a>`
3624
- );
3609
+ for (const variable of sortedByKey(contract.variables)) {
3610
+ lines.push(`<a id="${anchors.anchorOf(variable)}"></a>`);
3625
3611
  lines.push(`### \`${variable.key}\``, "");
3626
3612
  if (variable.description) lines.push(variable.description, "");
3627
3613
  if (!variable.documented) lines.push("> \u26A0\uFE0F **Undocumented.**", "");
@@ -3734,18 +3720,17 @@ function renderLifecycleReport(contracts, anchors, expiringWithinDays, now) {
3734
3720
  const owner = effectiveOwner(contract, variable);
3735
3721
  if (variable.expiresAt === void 0 && owner === void 0 && variable.refreshInstructions === void 0)
3736
3722
  continue;
3737
- const expiresAt = variable.expiresAt;
3738
- const expiry = expiresAt ? parseIsoDate(expiresAt) : void 0;
3739
- let expiresCell = expiresAt ?? "--";
3740
- if (expiry && expiresAt) {
3741
- const daysRemaining = daysRemainingFrom(expiry, now);
3723
+ const expiry = parseExpiry(variable.expiresAt);
3724
+ let expiresCell = variable.expiresAt ?? "--";
3725
+ if (expiry) {
3726
+ const daysRemaining = daysRemainingFrom(expiry.date, now);
3742
3727
  if (daysRemaining < 0)
3743
- expiresCell = `${expiresAt} (**expired ${Math.abs(daysRemaining)}d ago**)`;
3728
+ expiresCell = `${expiry.raw} (**expired ${Math.abs(daysRemaining)}d ago**)`;
3744
3729
  else if (daysRemaining <= expiringWithinDays)
3745
- expiresCell = `${expiresAt} (**${daysRemaining}d remaining**)`;
3730
+ expiresCell = `${expiry.raw} (**${daysRemaining}d remaining**)`;
3746
3731
  }
3747
3732
  rows.push(
3748
- `| ${mdLink(`\`${variable.key}\``, anchors.anchorFor(variable, `${contract.contractName}-${variable.key}`))} | ${owner ?? "--"} | ${expiresCell} | ${variable.refreshInstructions ?? "--"} |`
3733
+ `| ${mdLink(`\`${variable.key}\``, anchors.anchorOf(variable))} | ${owner ?? "--"} | ${expiresCell} | ${variable.refreshInstructions ?? "--"} |`
3749
3734
  );
3750
3735
  }
3751
3736
  }
@@ -3861,7 +3846,14 @@ function renderDocs(contracts, options) {
3861
3846
  );
3862
3847
  const catalog = renderCatalog(sorted, anchors, options.undocumentedContracts);
3863
3848
  const security = renderSecurityReview(sorted, options, options.generatedAt);
3864
- return [...header, ...catalog, ...ownership, ...dependencyLines, ...lifecycleLines, ...security].join("\n").replace(/\n{3,}/g, "\n\n");
3849
+ return [
3850
+ ...header,
3851
+ ...catalog,
3852
+ ...ownership,
3853
+ ...dependencyLines,
3854
+ ...lifecycleLines,
3855
+ ...security
3856
+ ].join("\n");
3865
3857
  }
3866
3858
  function normalizeDocsForComparison(content) {
3867
3859
  return content.replace(/^_Generated .+_$/m, "_Generated <normalized-for-comparison>_").replace(/\(\*\*\d+d remaining\*\*\)/g, "(**Nd remaining**)").replace(/\(\*\*expired \d+d ago\*\*\)/g, "(**expired Nd ago**)").replace(/^(- Already expired:) \d+$/gm, "$1 N").replace(/^(- Expiring within \d+ days:) \d+$/gm, "$1 N");
@@ -3900,9 +3892,9 @@ function groupByKey(contracts) {
3900
3892
  const byKey = /* @__PURE__ */ new Map();
3901
3893
  for (const contract of contracts) {
3902
3894
  for (const variable of contract.variables) {
3903
- const list = byKey.get(variable.key) ?? [];
3904
- list.push({ contract, variable });
3905
- byKey.set(variable.key, list);
3895
+ const existing = byKey.get(variable.key);
3896
+ if (existing === void 0) byKey.set(variable.key, [{ contract, variable }]);
3897
+ else existing.push({ contract, variable });
3906
3898
  }
3907
3899
  }
3908
3900
  return byKey;
@@ -3910,7 +3902,6 @@ function groupByKey(contracts) {
3910
3902
  function renderEnvExample(contracts, reconciliationHeader = []) {
3911
3903
  const sorted = [...contracts].sort((a, b) => a.file.localeCompare(b.file));
3912
3904
  const active = sorted.filter((c) => c.active);
3913
- const inactive = sorted.filter((c) => !c.active);
3914
3905
  const lines = [
3915
3906
  "# AUTO-GENERATED EXAMPLE FILE.",
3916
3907
  "# Copy to .env and fill in real values. Do not commit .env."
@@ -3922,12 +3913,11 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
3922
3913
  "# still written to this file regardless of its context."
3923
3914
  );
3924
3915
  }
3925
- if (reconciliationHeader.length > 0) lines.push(...reconciliationHeader);
3916
+ lines.push(...reconciliationHeader);
3926
3917
  lines.push("");
3927
3918
  const activeByKey = groupByKey(active);
3928
3919
  for (const key of [...activeByKey.keys()].sort()) {
3929
3920
  const [first, ...rest] = mustGet(activeByKey, key);
3930
- if (first === void 0) continue;
3931
3921
  lines.push(...renderVariableLines(first.variable));
3932
3922
  for (const dup of rest) {
3933
3923
  lines.push(
@@ -3938,11 +3928,10 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
3938
3928
  );
3939
3929
  }
3940
3930
  }
3941
- const inactiveByKey = groupByKey(inactive);
3931
+ const inactiveByKey = groupByKey(sorted);
3942
3932
  for (const key of [...inactiveByKey.keys()].sort()) {
3943
3933
  if (activeByKey.has(key)) continue;
3944
3934
  const [first] = mustGet(inactiveByKey, key);
3945
- if (first === void 0) continue;
3946
3935
  lines.push(
3947
3936
  ...renderVariableLines(first.variable, {
3948
3937
  commented: true,
@@ -3950,13 +3939,12 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
3950
3939
  })
3951
3940
  );
3952
3941
  }
3953
- return lines.join("\n").replace(/\n+$/, "\n");
3942
+ return lines.join("\n");
3954
3943
  }
3955
3944
  function extractDeclaredVariables(source) {
3956
3945
  const names = [];
3957
3946
  for (const line of source.split("\n")) {
3958
3947
  const trimmed = line.trim();
3959
- if (!trimmed || trimmed.startsWith("#")) continue;
3960
3948
  const match = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(trimmed);
3961
3949
  if (match?.[1]) names.push(match[1]);
3962
3950
  }
@@ -3966,9 +3954,7 @@ function extractCommentedVariables(source) {
3966
3954
  const names = [];
3967
3955
  for (const line of source.split("\n")) {
3968
3956
  const trimmed = line.trim();
3969
- if (!trimmed.startsWith("#")) continue;
3970
- const withoutHash = trimmed.replace(/^#+\s*/, "");
3971
- const match = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(withoutHash);
3957
+ const match = /^#+\s*([A-Za-z_][A-Za-z0-9_]*)=/.exec(trimmed);
3972
3958
  if (match?.[1]) names.push(match[1]);
3973
3959
  }
3974
3960
  return names;
@@ -4050,7 +4036,7 @@ function collectVariableNames(contracts) {
4050
4036
  }
4051
4037
  function overrideVariable(variable, overrides) {
4052
4038
  const override = overrides[variable.key];
4053
- const date = override === void 0 ? void 0 : parseIsoDate(override);
4039
+ const date = parseIsoDate(String(override));
4054
4040
  return {
4055
4041
  ...variable,
4056
4042
  expiresAt: date ? override : variable.expiresAt,
@@ -4072,16 +4058,14 @@ async function resolveLiveExpirationDates(contracts, liveExpirationDates) {
4072
4058
 
4073
4059
  // src/build/generate-documentation.ts
4074
4060
  var DEFAULT_EXPIRING_WITHIN_DAYS = 30;
4075
- var STANDARD_SENSITIVITY_LEVELS = /* @__PURE__ */ new Set([
4076
- "secret",
4077
- "credential",
4078
- "pii",
4079
- "config"
4080
- ]);
4061
+ function standardSensitivityLevels() {
4062
+ return ["secret", "credential", "pii", "config"];
4063
+ }
4064
+ var STANDARD_SENSITIVITY_LEVELS = new Set(standardSensitivityLevels());
4081
4065
  function findNonstandardSensitivityLevels(contracts) {
4082
4066
  const entries = [];
4083
4067
  for (const contract of contracts) {
4084
- if (contract.sensitivity !== void 0 && !STANDARD_SENSITIVITY_LEVELS.has(contract.sensitivity))
4068
+ if (contract.sensitivity !== void 0 && !standardSensitivityLevels().includes(contract.sensitivity))
4085
4069
  entries.push({
4086
4070
  file: contract.file,
4087
4071
  exportName: contract.exportName,
@@ -4090,7 +4074,7 @@ function findNonstandardSensitivityLevels(contracts) {
4090
4074
  });
4091
4075
  for (const variable of [...contract.variables].sort((a, b) => a.key.localeCompare(b.key))) {
4092
4076
  if (variable.sensitivity === void 0) continue;
4093
- if (STANDARD_SENSITIVITY_LEVELS.has(variable.sensitivity)) continue;
4077
+ if (standardSensitivityLevels().includes(variable.sensitivity)) continue;
4094
4078
  entries.push({
4095
4079
  file: contract.file,
4096
4080
  exportName: contract.exportName,
@@ -4131,36 +4115,20 @@ async function writeDocumentation(docsPath, envExamplePath, root, contracts, con
4131
4115
  undocumentedContracts: documentation.undocumentedContracts.map(
4132
4116
  (ref) => relativizeRef(root, ref)
4133
4117
  ),
4134
- // `RenderDocsOptions.undocumentedVariables` is consumed by `renderDocs()`
4135
- // ONLY via `.length` (the security-review counter) -- never by content
4136
- // or identity, unlike its `undocumentedContracts` sibling above (matched
4137
- // by identity against the catalog for the "Undocumented." marker).
4138
- // `.map()` always preserves length regardless of what each element
4139
- // transforms to, so this specific `relativizeRef()` call's own output is
4140
- // unobservable through this call site. Hand-verified: mapping every
4141
- // entry to `undefined` instead and running the full `vitest run` leaves
4142
- // all tests passing.
4143
- // Stryker disable next-line ArrowFunction
4144
- undocumentedVariables: documentation.undocumentedVariables.map(
4145
- (ref) => relativizeRef(root, ref)
4146
- ),
4118
+ undocumentedVariables: documentation.undocumentedVariables,
4147
4119
  generatedAt,
4148
4120
  previousContent
4149
4121
  });
4150
4122
  await fs.mkdir(path6.dirname(docsPath), { recursive: true });
4151
4123
  await fs.writeFile(docsPath, docsSource, "utf8");
4152
4124
  const envExample = envExamplePath ? (
4153
- // exactOptionalPropertyTypes: omit the key rather than set it to
4154
- // `undefined` when the caller didn't supply one. writeEnvExample
4155
- // itself does `options.onExisting ?? "keep-sibling"`, so passing
4156
- // `onExisting: undefined` explicitly (what always-spreading here
4157
- // would do) is behaviorally identical to omitting the key.
4158
- // Hand-verified: forcing this guard to `true` and running the real
4159
- // suite passes unchanged.
4160
- await writeEnvExample(contracts, envExamplePath, fs, {
4161
- // Stryker disable next-line ConditionalExpression
4162
- ...envExampleOnExisting === void 0 ? {} : { onExisting: envExampleOnExisting }
4163
- })
4125
+ // `exactOptionalPropertyTypes` rejects an explicit `undefined`, so the key is omitted when unset.
4126
+ await writeEnvExample(
4127
+ contracts,
4128
+ envExamplePath,
4129
+ fs,
4130
+ envExampleOnExisting && { onExisting: envExampleOnExisting }
4131
+ )
4164
4132
  ) : void 0;
4165
4133
  return { envExample };
4166
4134
  }
@@ -4168,7 +4136,6 @@ async function generateDocumentation(options) {
4168
4136
  const root = path6.resolve(options.root ?? process.cwd());
4169
4137
  const include = options.include ?? defaultInclude();
4170
4138
  const exclude = options.exclude ?? defaultExclude();
4171
- const packages = options.packages ?? [];
4172
4139
  const expiringWithinDays = options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS;
4173
4140
  const docsLocationResult = resolveWithinRoot(
4174
4141
  root,
@@ -4194,7 +4161,7 @@ async function generateDocumentation(options) {
4194
4161
  root,
4195
4162
  include,
4196
4163
  exclude,
4197
- packages,
4164
+ packages: options.packages,
4198
4165
  tsconfig: options.tsconfig
4199
4166
  });
4200
4167
  const docsContracts = await resolveLiveExpirationDates(
@@ -4248,7 +4215,7 @@ function parseRotationPeriodDays(value) {
4248
4215
  if (plain) {
4249
4216
  const amount = Number(plain[1]);
4250
4217
  if (amount > 0) {
4251
- const unit = (plain[2] ?? "").toLowerCase();
4218
+ const unit = String(plain[2]).toLowerCase();
4252
4219
  switch (unit) {
4253
4220
  case "day":
4254
4221
  case "days":
@@ -4281,18 +4248,14 @@ function parseRotationPeriodDays(value) {
4281
4248
  }
4282
4249
  function computeRotationStatus(variable, now) {
4283
4250
  if (!hasRotationData(variable)) return "undeclared";
4284
- if (variable.expiresAt !== void 0) {
4285
- const expiry = parseIsoDate(variable.expiresAt);
4286
- if (expiry !== void 0 && expiry.getTime() < now.getTime()) return "expired";
4287
- }
4251
+ const expiry = parseIsoDate(String(variable.expiresAt));
4252
+ if (expiry !== void 0 && expiry.getTime() < now.getTime()) return "expired";
4288
4253
  if (variable.rotationPeriod !== void 0) {
4289
- if (variable.lastRotatedAt !== void 0) {
4290
- const lastRotated = parseIsoDate(variable.lastRotatedAt);
4291
- const periodDays = parseRotationPeriodDays(variable.rotationPeriod);
4292
- if (lastRotated !== void 0 && lastRotated.getTime() <= now.getTime() && periodDays !== void 0) {
4293
- const dueDate = lastRotated.getTime() + periodDays * MS_PER_DAY2;
4294
- return dueDate < now.getTime() ? "overdue" : "compliant";
4295
- }
4254
+ const lastRotated = parseIsoDate(String(variable.lastRotatedAt));
4255
+ const periodDays = parseRotationPeriodDays(variable.rotationPeriod);
4256
+ if (lastRotated !== void 0 && lastRotated.getTime() <= now.getTime() && periodDays !== void 0) {
4257
+ const dueDate = lastRotated.getTime() + periodDays * MS_PER_DAY2;
4258
+ return dueDate < now.getTime() ? "overdue" : "compliant";
4296
4259
  }
4297
4260
  return "overdue";
4298
4261
  }
@@ -4374,7 +4337,7 @@ function buildOwnershipModel(contracts, root) {
4374
4337
 
4375
4338
  // src/build/tool-version.ts
4376
4339
  function readToolVersion() {
4377
- return "0.5.3";
4340
+ return "0.6.0";
4378
4341
  }
4379
4342
 
4380
4343
  // src/build/generate-evidence.ts
@@ -4382,7 +4345,6 @@ async function generateEvidenceModel(options) {
4382
4345
  const root = path6.resolve(options.root ?? process.cwd());
4383
4346
  const include = options.include ?? defaultInclude();
4384
4347
  const exclude = options.exclude ?? defaultExclude();
4385
- const packages = options.packages ?? [];
4386
4348
  const expiringWithinDays = options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS;
4387
4349
  let snapshotPath;
4388
4350
  if (options.previousSnapshotLocation !== void 0) {
@@ -4400,10 +4362,10 @@ async function generateEvidenceModel(options) {
4400
4362
  root,
4401
4363
  include,
4402
4364
  exclude,
4403
- packages,
4365
+ packages: options.packages,
4404
4366
  tsconfig: options.tsconfig
4405
4367
  });
4406
- const { readFileCached, linkResult, context, origins, packageWarnings, tsconfigWarnings } = assembled;
4368
+ const { readFileCached, linkResult, context, origins } = assembled;
4407
4369
  const generatedAt = /* @__PURE__ */ new Date();
4408
4370
  const activeContracts = linkResult.contracts.filter((c) => c.active);
4409
4371
  const lifecycleContracts = options.liveExpirationDates ? await resolveLiveExpirationDates(linkResult.contracts, options.liveExpirationDates) : linkResult.contracts;
@@ -4457,8 +4419,6 @@ async function generateEvidenceModel(options) {
4457
4419
  scanFiles,
4458
4420
  readFileCached,
4459
4421
  context,
4460
- // Stryker disable next-line ArrayDeclaration
4461
- [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings],
4462
4422
  scannedSurfaces,
4463
4423
  evidenceChanges?.dynamicAccessAcknowledgments
4464
4424
  );
@@ -4471,12 +4431,7 @@ async function generateEvidenceModel(options) {
4471
4431
  unresolvedConsumers: usageComputed.result.unresolvedConsumers,
4472
4432
  unconsumedOwnedVariables: usageComputed.result.unconsumedOwnedVariables,
4473
4433
  indeterminateOwnership: usageComputed.result.indeterminate,
4474
- // `buildFindingModel` (finding-model.ts) has its own `?? []` fallback
4475
- // on this exact same field, so even an `undefined` that slipped past
4476
- // this one (e.g. `??`-vs-`&&` on `evidenceChanges?.…`) is caught there
4477
- // identically -- belt-and-suspenders, not independently observable.
4478
- // Stryker disable next-line LogicalOperator
4479
- dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems ?? []
4434
+ dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems
4480
4435
  });
4481
4436
  const commit = options.commit ? await options.commit() : void 0;
4482
4437
  return deepFreeze({
@@ -4532,7 +4487,6 @@ async function getEvidenceModel(options) {
4532
4487
  const root = path6.resolve(options.root ?? process.cwd());
4533
4488
  const include = options.include ?? defaultInclude();
4534
4489
  const exclude = options.exclude ?? defaultExclude();
4535
- const packages = options.packages ?? [];
4536
4490
  const evidencePath = path6.resolve(root, options.location);
4537
4491
  const fingerprintPath = fingerprintPathFor(evidencePath);
4538
4492
  const recompute = async (missReason) => ({
@@ -4547,7 +4501,7 @@ async function getEvidenceModel(options) {
4547
4501
  root,
4548
4502
  include,
4549
4503
  exclude,
4550
- packages
4504
+ packages: options.packages
4551
4505
  });
4552
4506
  } catch (error) {
4553
4507
  return recompute(
@@ -4595,91 +4549,61 @@ function findingFiles(finding) {
4595
4549
  if (location.model === "change") return [location.path];
4596
4550
  return location.file === void 0 ? [] : [location.file];
4597
4551
  }
4552
+ function requestedPass(option) {
4553
+ return option === false ? void 0 : option;
4554
+ }
4598
4555
  async function computeArtifacts(options) {
4599
4556
  const root = path6.resolve(options.root ?? process.cwd());
4600
4557
  const include = options.include ?? defaultInclude();
4601
4558
  const exclude = options.exclude ?? defaultExclude();
4602
- const packages = options.packages ?? [];
4603
- const manifestOptions = options.manifest === false ? void 0 : options.manifest;
4604
- const docsOptions = options.docs === false ? void 0 : options.docs;
4605
- const usageOptions = options.usage === false ? void 0 : options.usage;
4606
- const evidenceOptions = options.evidence === false ? void 0 : options.evidence;
4559
+ const manifestOptions = requestedPass(options.manifest);
4560
+ const docsOptions = requestedPass(options.docs);
4561
+ const usageOptions = requestedPass(options.usage);
4562
+ const evidenceOptions = requestedPass(options.evidence);
4607
4563
  const pathIssues = [];
4608
- let manifestOutputPath;
4609
- if (manifestOptions) {
4610
- const result = resolveWithinRoot(
4611
- root,
4612
- manifestOptions.location,
4613
- "manifest.location",
4614
- "generateEnvArtifacts"
4615
- );
4616
- if (result.ok) manifestOutputPath = result.resolved;
4617
- else pathIssues.push(result.issue);
4618
- }
4619
- let docsPath;
4620
- let envExamplePath;
4621
- if (docsOptions) {
4622
- const result = resolveWithinRoot(
4623
- root,
4624
- docsOptions.location,
4625
- "docs.location",
4626
- "generateEnvArtifacts"
4627
- );
4628
- if (result.ok) docsPath = result.resolved;
4629
- else pathIssues.push(result.issue);
4630
- if (docsOptions.envExample) {
4631
- const exampleResult = resolveWithinRoot(
4632
- root,
4633
- docsOptions.envExample.location,
4634
- "docs.envExample.location",
4635
- "generateEnvArtifacts"
4636
- );
4637
- if (exampleResult.ok) envExamplePath = exampleResult.resolved;
4638
- else pathIssues.push(exampleResult.issue);
4639
- }
4640
- }
4641
- let usageReportPath;
4642
- if (usageOptions?.report) {
4643
- const result = resolveWithinRoot(
4644
- root,
4645
- usageOptions.report.location,
4646
- "usage.report.location",
4647
- "generateEnvArtifacts"
4648
- );
4649
- if (result.ok) usageReportPath = result.resolved;
4650
- else pathIssues.push(result.issue);
4651
- }
4652
- let evidencePath;
4653
- if (evidenceOptions) {
4654
- const result = resolveWithinRoot(
4655
- root,
4656
- evidenceOptions.location,
4657
- "evidence.location",
4658
- "generateEnvArtifacts"
4659
- );
4660
- if (result.ok) evidencePath = result.resolved;
4661
- else pathIssues.push(result.issue);
4662
- }
4564
+ const resolveOutput = (location, label) => {
4565
+ const result = resolveWithinRoot(root, location, label, "generateEnvArtifacts");
4566
+ if (result.ok) return result.resolved;
4567
+ pathIssues.push(result.issue);
4568
+ return location;
4569
+ };
4570
+ const manifestTarget = manifestOptions && {
4571
+ options: manifestOptions,
4572
+ outputPath: resolveOutput(manifestOptions.location, "manifest.location")
4573
+ };
4574
+ const docsTarget = docsOptions && {
4575
+ options: docsOptions,
4576
+ path: resolveOutput(docsOptions.location, "docs.location"),
4577
+ envExamplePath: docsOptions.envExample ? resolveOutput(docsOptions.envExample.location, "docs.envExample.location") : void 0
4578
+ };
4579
+ const usageTarget = usageOptions && {
4580
+ options: usageOptions,
4581
+ reportPath: usageOptions.report ? resolveOutput(usageOptions.report.location, "usage.report.location") : void 0
4582
+ };
4583
+ const evidencePath = evidenceOptions ? resolveOutput(evidenceOptions.location, "evidence.location") : void 0;
4663
4584
  if (pathIssues.length > 0) throw new EnvProjectGenerationError(pathIssues);
4664
4585
  const { readFileCached, linkResult, context, origins, packageWarnings, tsconfigWarnings } = await assembleProject({
4665
4586
  fs: options.fs,
4666
4587
  root,
4667
4588
  include,
4668
4589
  exclude,
4669
- packages,
4590
+ packages: options.packages,
4670
4591
  tsconfig: options.tsconfig
4671
4592
  });
4672
4593
  const generatedAt = /* @__PURE__ */ new Date();
4673
4594
  const activeContracts = linkResult.contracts.filter((c) => c.active);
4674
4595
  const liveExpirationContracts = options.liveExpirationDates ? await resolveLiveExpirationDates(linkResult.contracts, options.liveExpirationDates) : linkResult.contracts;
4675
- const docsContracts = docsOptions ? liveExpirationContracts : linkResult.contracts;
4596
+ const docsContracts = docsTarget ? liveExpirationContracts : linkResult.contracts;
4676
4597
  const blocking = [];
4677
- const manifestComputed = manifestOptions ? computeManifest(root, linkResult, manifestOptions.onIncompatibility ?? "warn") : void 0;
4678
- if (manifestComputed) blocking.push(...manifestComputed.blocking);
4598
+ const manifest = manifestTarget && {
4599
+ ...manifestTarget,
4600
+ computed: computeManifest(root, linkResult, manifestTarget.options.onIncompatibility)
4601
+ };
4602
+ if (manifest) blocking.push(...manifest.computed.blocking);
4679
4603
  const docsComputed = computeDocumentation(
4680
4604
  root,
4681
4605
  { ...linkResult, contracts: liveExpirationContracts },
4682
- docsOptions?.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4606
+ docsTarget?.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4683
4607
  generatedAt
4684
4608
  );
4685
4609
  const { scanFiles, scannedSurfaces } = await computeScanSurface(
@@ -4703,14 +4627,13 @@ async function computeArtifacts(options) {
4703
4627
  scanFiles,
4704
4628
  readFileCached,
4705
4629
  context,
4706
- [...packageWarnings, ...tsconfigWarnings, ...linkResult.warnings],
4707
4630
  scannedSurfaces,
4708
4631
  evidenceChanges?.dynamicAccessAcknowledgments
4709
4632
  );
4710
4633
  const ownership = buildOwnershipModel(linkResult.contracts, root);
4711
4634
  const lifecycle = buildLifecycleModel(
4712
4635
  liveExpirationContracts,
4713
- docsOptions?.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4636
+ docsTarget?.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4714
4637
  generatedAt,
4715
4638
  root
4716
4639
  );
@@ -4747,7 +4670,7 @@ async function computeArtifacts(options) {
4747
4670
  unresolvedConsumers: usageComputed.result.unresolvedConsumers,
4748
4671
  unconsumedOwnedVariables: usageComputed.result.unconsumedOwnedVariables,
4749
4672
  indeterminateOwnership: usageComputed.result.indeterminate,
4750
- dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems ?? []
4673
+ dynamicAccessCitationProblems: evidenceChanges?.dynamicAccessCitationProblems
4751
4674
  });
4752
4675
  if (options.onUndocumented === "throw")
4753
4676
  blocking.push(...escalatedFindings(finding.findings, "documentation"));
@@ -4769,16 +4692,11 @@ async function computeArtifacts(options) {
4769
4692
  });
4770
4693
  return {
4771
4694
  root,
4772
- manifestOptions,
4773
- manifestOutputPath,
4774
- manifestComputed,
4775
- docsOptions,
4776
- docsPath,
4777
- envExamplePath,
4695
+ manifest,
4696
+ docs: docsTarget,
4778
4697
  docsComputed,
4779
4698
  docsContracts,
4780
- usageOptions,
4781
- usageReportPath,
4699
+ usage: usageTarget,
4782
4700
  usageComputed,
4783
4701
  evidencePath,
4784
4702
  evidence,
@@ -4791,16 +4709,11 @@ async function computeArtifacts(options) {
4791
4709
  async function generateEnvArtifacts(options) {
4792
4710
  const computed = await computeArtifacts(options);
4793
4711
  const {
4794
- manifestOptions,
4795
- manifestOutputPath,
4796
- manifestComputed,
4797
- docsOptions,
4798
- docsPath,
4799
- envExamplePath,
4712
+ manifest,
4713
+ docs,
4800
4714
  docsComputed,
4801
4715
  docsContracts,
4802
- usageOptions,
4803
- usageReportPath,
4716
+ usage,
4804
4717
  usageComputed,
4805
4718
  evidencePath,
4806
4719
  evidence,
@@ -4811,43 +4724,47 @@ async function generateEnvArtifacts(options) {
4811
4724
  generatedAt
4812
4725
  } = computed;
4813
4726
  if (blocking.length > 0) throw new EnvProjectGenerationError(blocking);
4727
+ const parseWarnings = [...packageWarnings, ...linkWarnings];
4814
4728
  let manifestResult;
4815
- if (manifestOptions && manifestComputed && manifestOutputPath) {
4816
- await writeManifest(manifestOutputPath, manifestComputed.activeContracts, options.fs);
4729
+ if (manifest) {
4730
+ await writeManifest(manifest.outputPath, manifest.computed.activeContracts, options.fs);
4817
4731
  manifestResult = {
4818
- outputPath: manifestOutputPath,
4819
- contracts: manifestComputed.contractSummaries,
4820
- warnings: manifestComputed.warnings,
4821
- parseWarnings: [...packageWarnings, ...linkWarnings]
4732
+ outputPath: manifest.outputPath,
4733
+ contracts: manifest.computed.contractSummaries,
4734
+ warnings: manifest.computed.warnings,
4735
+ parseWarnings
4822
4736
  };
4823
4737
  }
4824
4738
  let docsResult;
4825
- if (docsOptions && docsPath) {
4739
+ if (docs) {
4826
4740
  const { envExample } = await writeDocumentation(
4827
- docsPath,
4828
- envExamplePath,
4741
+ docs.path,
4742
+ docs.envExamplePath,
4829
4743
  root,
4830
4744
  docsContracts,
4831
4745
  docsComputed.contractModelContracts,
4832
4746
  docsComputed.documentation,
4833
- docsOptions.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4747
+ docs.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4834
4748
  generatedAt,
4835
4749
  options.fs,
4836
- docsOptions.envExample?.onExisting
4750
+ docs.options.envExample?.onExisting
4837
4751
  );
4838
4752
  docsResult = {
4839
- docsPath,
4753
+ docsPath: docs.path,
4840
4754
  envExample,
4841
4755
  contracts: docsComputed.contractSummaries,
4842
4756
  catalog: docsComputed.catalog,
4843
- parseWarnings: [...packageWarnings, ...linkWarnings],
4757
+ parseWarnings,
4844
4758
  documentation: docsComputed.documentation
4845
4759
  };
4846
4760
  }
4847
4761
  let usageResult;
4848
- if (usageOptions) {
4849
- if (usageReportPath) await writeUsageReport(usageReportPath, usageComputed.result, options.fs);
4850
- usageResult = { reportPath: usageReportPath, ...usageComputed.result };
4762
+ if (usage) {
4763
+ const usageReport = { ...usageComputed.result, parseWarnings };
4764
+ if (usage.reportPath !== void 0) {
4765
+ await writeUsageReport(usage.reportPath, usageReport, options.fs);
4766
+ }
4767
+ usageResult = { reportPath: usage.reportPath, ...usageReport };
4851
4768
  }
4852
4769
  if (evidencePath) {
4853
4770
  await writeEvidenceSnapshot(evidencePath, evidence, options.fs);
@@ -4856,7 +4773,7 @@ async function generateEnvArtifacts(options) {
4856
4773
  root,
4857
4774
  include: options.include ?? defaultInclude(),
4858
4775
  exclude: options.exclude ?? defaultExclude(),
4859
- packages: options.packages ?? []
4776
+ packages: options.packages
4860
4777
  });
4861
4778
  await writeEvidenceFingerprint(evidencePath, fingerprint, options.fs);
4862
4779
  }
@@ -4864,12 +4781,8 @@ async function generateEnvArtifacts(options) {
4864
4781
  }
4865
4782
 
4866
4783
  // src/build/check-artifacts.ts
4867
- async function readIfExists(filePath, fs) {
4868
- try {
4869
- return await fs.readFile(filePath, "utf8");
4870
- } catch {
4871
- return void 0;
4872
- }
4784
+ function readIfExists(filePath, fs) {
4785
+ return fs.readFile(filePath, "utf8").catch(() => void 0);
4873
4786
  }
4874
4787
  function normalizeEvidenceJsonForComparison(text) {
4875
4788
  try {
@@ -4895,46 +4808,38 @@ async function checkEnvArtifacts(options) {
4895
4808
  const c = await computeArtifacts(options);
4896
4809
  if (c.blocking.length > 0) throw new EnvProjectGenerationError(c.blocking);
4897
4810
  const findings = [];
4898
- if (c.manifestOptions && c.manifestComputed && c.manifestOutputPath) {
4899
- const expected = renderManifest(c.manifestComputed.activeContracts, c.manifestOutputPath);
4900
- findings.push(await compareTextArtifact("manifest", c.manifestOutputPath, expected, options.fs));
4811
+ if (c.manifest) {
4812
+ const expected = renderManifest(c.manifest.computed.activeContracts, c.manifest.outputPath);
4813
+ findings.push(
4814
+ await compareTextArtifact("manifest", c.manifest.outputPath, expected, options.fs)
4815
+ );
4901
4816
  }
4902
- if (c.docsOptions && c.docsPath) {
4903
- const previousContent = await readIfExists(c.docsPath, options.fs);
4817
+ if (c.docs) {
4818
+ const previousContent = await readIfExists(c.docs.path, options.fs);
4904
4819
  const expected = renderDocs(c.docsComputed.contractModelContracts, {
4905
- expiringWithinDays: c.docsOptions.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4820
+ expiringWithinDays: c.docs.options.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS,
4906
4821
  undocumentedContracts: c.docsComputed.documentation.undocumentedContracts.map(
4907
4822
  (ref) => relativizeRef(c.root, ref)
4908
4823
  ),
4909
- // `RenderDocsOptions.undocumentedVariables` is consumed by `renderDocs()`
4910
- // ONLY via `.length` (the security-review counter), never by content
4911
- // or identity -- same equivalence already established for
4912
- // `generate-documentation.ts`'s identical call site. Hand-verified:
4913
- // mapping every entry to `undefined` instead and running the full
4914
- // `vitest run` leaves every test passing.
4915
- // Stryker disable ArrowFunction
4916
- undocumentedVariables: c.docsComputed.documentation.undocumentedVariables.map(
4917
- (ref) => relativizeRef(c.root, ref)
4918
- ),
4919
- // Stryker restore ArrowFunction
4824
+ undocumentedVariables: c.docsComputed.documentation.undocumentedVariables,
4920
4825
  generatedAt: c.generatedAt,
4921
4826
  previousContent
4922
4827
  });
4923
4828
  findings.push(
4924
4829
  await compareTextArtifact(
4925
4830
  "docs",
4926
- c.docsPath,
4831
+ c.docs.path,
4927
4832
  expected,
4928
4833
  options.fs,
4929
4834
  normalizeDocsForComparison
4930
4835
  )
4931
4836
  );
4932
- if (c.docsOptions.envExample && c.envExamplePath) {
4933
- const existing = await readIfExists(c.envExamplePath, options.fs);
4837
+ if (c.docs.envExamplePath !== void 0) {
4838
+ const existing = await readIfExists(c.docs.envExamplePath, options.fs);
4934
4839
  if (existing === void 0) {
4935
4840
  findings.push({
4936
4841
  artifact: "envExample",
4937
- path: c.envExamplePath,
4842
+ path: c.docs.envExamplePath,
4938
4843
  status: "missing",
4939
4844
  detail: "not yet generated"
4940
4845
  });
@@ -4946,7 +4851,7 @@ async function checkEnvArtifacts(options) {
4946
4851
  const driftCount = staleVariables.length + variablesToComment.length + variablesToAdd.length;
4947
4852
  findings.push({
4948
4853
  artifact: "envExample",
4949
- path: c.envExamplePath,
4854
+ path: c.docs.envExamplePath,
4950
4855
  status: driftCount > 0 ? "stale" : "ok",
4951
4856
  // exactOptionalPropertyTypes: omit the key entirely rather than
4952
4857
  // set it to `undefined` -- `detail` is absent when there's
@@ -4958,9 +4863,12 @@ async function checkEnvArtifacts(options) {
4958
4863
  }
4959
4864
  }
4960
4865
  }
4961
- if (c.usageOptions && c.usageReportPath) {
4962
- const expected = renderUsageReport(c.usageComputed.result);
4963
- findings.push(await compareTextArtifact("usage", c.usageReportPath, expected, options.fs));
4866
+ if (c.usage?.reportPath !== void 0) {
4867
+ const expected = renderUsageReport({
4868
+ ...c.usageComputed.result,
4869
+ parseWarnings: [...c.packageWarnings, ...c.linkWarnings]
4870
+ });
4871
+ findings.push(await compareTextArtifact("usage", c.usage.reportPath, expected, options.fs));
4964
4872
  }
4965
4873
  if (c.evidencePath) {
4966
4874
  const expected = JSON.stringify(c.evidence, null, 2);
@@ -4985,7 +4893,7 @@ function sarifLocations(finding) {
4985
4893
  const location = finding.location;
4986
4894
  const uri = location.model === "change" ? location.path : location.file;
4987
4895
  if (uri === void 0) return void 0;
4988
- const position = location.model === "change" ? void 0 : location.position;
4896
+ const { position } = location;
4989
4897
  return [
4990
4898
  {
4991
4899
  physicalLocation: {