@maverickcer/env-cap 0.7.5 → 0.7.7

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 (279) hide show
  1. package/ADOPTION.md +12 -12
  2. package/AGENTS.md +85 -120
  3. package/CHANGELOG.md +36 -0
  4. package/CODE_REVIEW.md +5 -5
  5. package/CONTRIBUTING.md +5 -5
  6. package/GUIDE.md +42 -24
  7. package/README.md +52 -34
  8. package/RELEASING.md +78 -64
  9. package/SECURITY.md +15 -15
  10. package/VERSIONING.md +16 -15
  11. package/benchmarks/READING-BENCHMARKS.md +101 -85
  12. package/benchmarks/README.md +12 -9
  13. package/benchmarks/WRITING-BENCHMARKS.md +89 -79
  14. package/benchmarks/performance-buildtime/BENCHMARKS.md +20 -20
  15. package/benchmarks/performance-runtime/BENCHMARKS.md +107 -107
  16. package/dist/.dts/_ipc/build-fs.d.ts +3 -3
  17. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/display-path.d.ts +1 -1
  19. package/dist/.dts/_ipc/glob.d.ts +3 -2
  20. package/dist/.dts/_ipc/glob.d.ts.map +1 -1
  21. package/dist/.dts/_ipc/no-node-fs.d.ts +2 -2
  22. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  23. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  24. package/dist/.dts/_ipc/typescript.d.ts +4 -4
  25. package/dist/.dts/build/assemble-project.d.ts +14 -15
  26. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  27. package/dist/.dts/build/change-model.d.ts +14 -14
  28. package/dist/.dts/build/change-model.d.ts.map +1 -1
  29. package/dist/.dts/build/check-artifacts.d.ts +4 -4
  30. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  31. package/dist/.dts/build/citation-verification.d.ts +13 -14
  32. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  33. package/dist/.dts/build/compatibility.d.ts +24 -24
  34. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  35. package/dist/.dts/build/contract-model.d.ts +10 -10
  36. package/dist/.dts/build/contract-model.d.ts.map +1 -1
  37. package/dist/.dts/build/deep-equal.d.ts +2 -2
  38. package/dist/.dts/build/deep-freeze.d.ts +2 -2
  39. package/dist/.dts/build/dependency-graph.d.ts +48 -55
  40. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  41. package/dist/.dts/build/dependency-model.d.ts +18 -18
  42. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  43. package/dist/.dts/build/discover.d.ts +11 -11
  44. package/dist/.dts/build/discover.d.ts.map +1 -1
  45. package/dist/.dts/build/docs.d.ts +34 -38
  46. package/dist/.dts/build/docs.d.ts.map +1 -1
  47. package/dist/.dts/build/env-example.d.ts +13 -13
  48. package/dist/.dts/build/env-example.d.ts.map +1 -1
  49. package/dist/.dts/build/errors.d.ts +8 -8
  50. package/dist/.dts/build/evidence-cache.d.ts +23 -23
  51. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  52. package/dist/.dts/build/evidence-model.d.ts +3 -3
  53. package/dist/.dts/build/evidence-reference.d.ts +15 -15
  54. package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
  55. package/dist/.dts/build/evidence-snapshot.d.ts +47 -53
  56. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  57. package/dist/.dts/build/exclusive-group.d.ts +4 -4
  58. package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
  59. package/dist/.dts/build/finding-model.d.ts +12 -12
  60. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  61. package/dist/.dts/build/generate-documentation.d.ts +19 -19
  62. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  63. package/dist/.dts/build/generate-env-artifacts.d.ts +43 -43
  64. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  65. package/dist/.dts/build/generate-evidence.d.ts +19 -19
  66. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  67. package/dist/.dts/build/generate-manifest.d.ts +11 -12
  68. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  69. package/dist/.dts/build/generate-usage.d.ts +23 -24
  70. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  71. package/dist/.dts/build/generated-banner.d.ts +5 -5
  72. package/dist/.dts/build/governance-fields.d.ts +7 -7
  73. package/dist/.dts/build/humanize-key.d.ts +1 -1
  74. package/dist/.dts/build/humanize-key.d.ts.map +1 -1
  75. package/dist/.dts/build/index.d.ts +20 -36
  76. package/dist/.dts/build/index.d.ts.map +1 -1
  77. package/dist/.dts/build/lifecycle-model.d.ts +87 -85
  78. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  79. package/dist/.dts/build/link.d.ts +38 -39
  80. package/dist/.dts/build/link.d.ts.map +1 -1
  81. package/dist/.dts/build/literal-eval.d.ts +2 -2
  82. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  83. package/dist/.dts/build/live-expirations.d.ts +14 -13
  84. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  85. package/dist/.dts/build/manifest.d.ts +6 -6
  86. package/dist/.dts/build/map-utils.d.ts +4 -4
  87. package/dist/.dts/build/merge-documentation.d.ts +9 -8
  88. package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
  89. package/dist/.dts/build/ownership-model.d.ts +14 -15
  90. package/dist/.dts/build/ownership-model.d.ts.map +1 -1
  91. package/dist/.dts/build/parse.d.ts +20 -21
  92. package/dist/.dts/build/parse.d.ts.map +1 -1
  93. package/dist/.dts/build/reference-projections.d.ts +36 -38
  94. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  95. package/dist/.dts/build/resolution/resolve-import.d.ts +18 -14
  96. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  97. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +26 -26
  98. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  99. package/dist/.dts/build/resolution/resolve-within-root.d.ts +9 -9
  100. package/dist/.dts/build/sarif.d.ts +5 -5
  101. package/dist/.dts/build/sarif.d.ts.map +1 -1
  102. package/dist/.dts/build/scan-dependencies.d.ts +17 -16
  103. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  104. package/dist/.dts/build/sort-by-identity.d.ts +1 -1
  105. package/dist/.dts/build/source-position.d.ts +13 -13
  106. package/dist/.dts/build/tool-version.d.ts +1 -1
  107. package/dist/.dts/build/usage-report.d.ts +19 -19
  108. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  109. package/dist/.dts/eslint-plugin/index.d.ts +16 -5
  110. package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
  111. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
  112. package/dist/.dts/evidence/define-projection.d.ts +15 -16
  113. package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
  114. package/dist/.dts/evidence/index.d.ts +11 -15
  115. package/dist/.dts/evidence/index.d.ts.map +1 -1
  116. package/dist/.dts/helpers/index.d.ts +15 -18
  117. package/dist/.dts/helpers/index.d.ts.map +1 -1
  118. package/dist/.dts/helpers/validators.d.ts +2 -2
  119. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  120. package/dist/.dts/node/index.d.ts +19 -0
  121. package/dist/.dts/node/index.d.ts.map +1 -1
  122. package/dist/.dts/runtime/create.d.ts +3 -3
  123. package/dist/.dts/runtime/document.d.ts +90 -99
  124. package/dist/.dts/runtime/document.d.ts.map +1 -1
  125. package/dist/.dts/runtime/errors.d.ts +5 -5
  126. package/dist/.dts/runtime/reset.d.ts +1 -1
  127. package/dist/.dts/runtime/types.d.ts +23 -24
  128. package/dist/.dts/runtime/types.d.ts.map +1 -1
  129. package/dist/.dts/runtime/validate.d.ts +1 -1
  130. package/dist/.dts7/_ipc/build-fs.d.ts +3 -3
  131. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -1
  132. package/dist/.dts7/_ipc/display-path.d.ts +1 -1
  133. package/dist/.dts7/_ipc/glob.d.ts +3 -2
  134. package/dist/.dts7/_ipc/glob.d.ts.map +1 -1
  135. package/dist/.dts7/_ipc/no-node-fs.d.ts +2 -2
  136. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  137. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  138. package/dist/.dts7/_ipc/typescript.d.ts +4 -4
  139. package/dist/.dts7/build/assemble-project.d.ts +14 -15
  140. package/dist/.dts7/build/assemble-project.d.ts.map +1 -1
  141. package/dist/.dts7/build/change-model.d.ts +14 -14
  142. package/dist/.dts7/build/change-model.d.ts.map +1 -1
  143. package/dist/.dts7/build/check-artifacts.d.ts +4 -4
  144. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -1
  145. package/dist/.dts7/build/citation-verification.d.ts +13 -14
  146. package/dist/.dts7/build/citation-verification.d.ts.map +1 -1
  147. package/dist/.dts7/build/compatibility.d.ts +24 -24
  148. package/dist/.dts7/build/compatibility.d.ts.map +1 -1
  149. package/dist/.dts7/build/contract-model.d.ts +10 -10
  150. package/dist/.dts7/build/contract-model.d.ts.map +1 -1
  151. package/dist/.dts7/build/deep-equal.d.ts +2 -2
  152. package/dist/.dts7/build/deep-freeze.d.ts +2 -2
  153. package/dist/.dts7/build/dependency-graph.d.ts +48 -55
  154. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -1
  155. package/dist/.dts7/build/dependency-model.d.ts +18 -18
  156. package/dist/.dts7/build/dependency-model.d.ts.map +1 -1
  157. package/dist/.dts7/build/discover.d.ts +11 -11
  158. package/dist/.dts7/build/discover.d.ts.map +1 -1
  159. package/dist/.dts7/build/docs.d.ts +34 -38
  160. package/dist/.dts7/build/docs.d.ts.map +1 -1
  161. package/dist/.dts7/build/env-example.d.ts +13 -13
  162. package/dist/.dts7/build/env-example.d.ts.map +1 -1
  163. package/dist/.dts7/build/errors.d.ts +8 -8
  164. package/dist/.dts7/build/evidence-cache.d.ts +23 -23
  165. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -1
  166. package/dist/.dts7/build/evidence-model.d.ts +3 -3
  167. package/dist/.dts7/build/evidence-reference.d.ts +15 -15
  168. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -1
  169. package/dist/.dts7/build/evidence-snapshot.d.ts +47 -53
  170. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -1
  171. package/dist/.dts7/build/exclusive-group.d.ts +4 -4
  172. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -1
  173. package/dist/.dts7/build/finding-model.d.ts +12 -12
  174. package/dist/.dts7/build/finding-model.d.ts.map +1 -1
  175. package/dist/.dts7/build/generate-documentation.d.ts +19 -19
  176. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -1
  177. package/dist/.dts7/build/generate-env-artifacts.d.ts +43 -43
  178. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -1
  179. package/dist/.dts7/build/generate-evidence.d.ts +19 -19
  180. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -1
  181. package/dist/.dts7/build/generate-manifest.d.ts +11 -12
  182. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -1
  183. package/dist/.dts7/build/generate-usage.d.ts +23 -24
  184. package/dist/.dts7/build/generate-usage.d.ts.map +1 -1
  185. package/dist/.dts7/build/generated-banner.d.ts +5 -5
  186. package/dist/.dts7/build/governance-fields.d.ts +7 -7
  187. package/dist/.dts7/build/humanize-key.d.ts +1 -1
  188. package/dist/.dts7/build/humanize-key.d.ts.map +1 -1
  189. package/dist/.dts7/build/index.d.ts +20 -36
  190. package/dist/.dts7/build/index.d.ts.map +1 -1
  191. package/dist/.dts7/build/lifecycle-model.d.ts +87 -85
  192. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -1
  193. package/dist/.dts7/build/link.d.ts +38 -39
  194. package/dist/.dts7/build/link.d.ts.map +1 -1
  195. package/dist/.dts7/build/literal-eval.d.ts +2 -2
  196. package/dist/.dts7/build/literal-eval.d.ts.map +1 -1
  197. package/dist/.dts7/build/live-expirations.d.ts +14 -13
  198. package/dist/.dts7/build/live-expirations.d.ts.map +1 -1
  199. package/dist/.dts7/build/manifest.d.ts +6 -6
  200. package/dist/.dts7/build/map-utils.d.ts +4 -4
  201. package/dist/.dts7/build/merge-documentation.d.ts +9 -8
  202. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -1
  203. package/dist/.dts7/build/ownership-model.d.ts +14 -15
  204. package/dist/.dts7/build/ownership-model.d.ts.map +1 -1
  205. package/dist/.dts7/build/parse.d.ts +20 -21
  206. package/dist/.dts7/build/parse.d.ts.map +1 -1
  207. package/dist/.dts7/build/reference-projections.d.ts +36 -38
  208. package/dist/.dts7/build/reference-projections.d.ts.map +1 -1
  209. package/dist/.dts7/build/resolution/resolve-import.d.ts +18 -14
  210. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -1
  211. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +26 -26
  212. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -1
  213. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +9 -9
  214. package/dist/.dts7/build/sarif.d.ts +5 -5
  215. package/dist/.dts7/build/sarif.d.ts.map +1 -1
  216. package/dist/.dts7/build/scan-dependencies.d.ts +17 -16
  217. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -1
  218. package/dist/.dts7/build/sort-by-identity.d.ts +1 -1
  219. package/dist/.dts7/build/source-position.d.ts +13 -13
  220. package/dist/.dts7/build/tool-version.d.ts +1 -1
  221. package/dist/.dts7/build/usage-report.d.ts +19 -19
  222. package/dist/.dts7/build/usage-report.d.ts.map +1 -1
  223. package/dist/.dts7/eslint-plugin/index.d.ts +16 -5
  224. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -1
  225. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +4 -4
  226. package/dist/.dts7/evidence/define-projection.d.ts +15 -16
  227. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -1
  228. package/dist/.dts7/evidence/index.d.ts +11 -15
  229. package/dist/.dts7/evidence/index.d.ts.map +1 -1
  230. package/dist/.dts7/helpers/index.d.ts +15 -18
  231. package/dist/.dts7/helpers/index.d.ts.map +1 -1
  232. package/dist/.dts7/helpers/validators.d.ts +2 -2
  233. package/dist/.dts7/helpers/validators.d.ts.map +1 -1
  234. package/dist/.dts7/node/index.d.ts +19 -0
  235. package/dist/.dts7/node/index.d.ts.map +1 -1
  236. package/dist/.dts7/runtime/create.d.ts +3 -3
  237. package/dist/.dts7/runtime/document.d.ts +90 -99
  238. package/dist/.dts7/runtime/document.d.ts.map +1 -1
  239. package/dist/.dts7/runtime/errors.d.ts +5 -5
  240. package/dist/.dts7/runtime/reset.d.ts +1 -1
  241. package/dist/.dts7/runtime/types.d.ts +23 -24
  242. package/dist/.dts7/runtime/types.d.ts.map +1 -1
  243. package/dist/.dts7/runtime/validate.d.ts +1 -1
  244. package/dist/{build-DNAYWD2B.js → build-33O5SDTC.js} +37 -39
  245. package/dist/build-33O5SDTC.js.map +1 -0
  246. package/dist/build.cjs +36 -38
  247. package/dist/build.cjs.map +1 -1
  248. package/dist/build.js +36 -38
  249. package/dist/build.js.map +1 -1
  250. package/dist/{chunk-HAGMVMN5.js → chunk-4D67AQFY.js} +2 -2
  251. package/dist/cli/index.js +29 -28
  252. package/dist/cli/index.js.map +1 -1
  253. package/dist/eslint-plugin/index.cjs.map +1 -1
  254. package/dist/eslint-plugin/index.js.map +1 -1
  255. package/dist/evidence.cjs +1 -1
  256. package/dist/evidence.cjs.map +1 -1
  257. package/dist/evidence.js +1 -1
  258. package/dist/evidence.js.map +1 -1
  259. package/dist/helpers.cjs +4 -4
  260. package/dist/helpers.cjs.map +1 -1
  261. package/dist/helpers.js +4 -4
  262. package/dist/helpers.js.map +1 -1
  263. package/dist/index.cjs.map +1 -1
  264. package/dist/index.js.map +1 -1
  265. package/examples/README.md +1 -1
  266. package/package.json +20 -13
  267. package/schemas/contract-model.schema.json +7 -7
  268. package/schemas/env-cap-report.schema.json +88 -88
  269. package/skills/env-cap/SKILL.md +12 -13
  270. package/skills/env-cap/references/api.md +1 -1
  271. package/specs/architecture.md +145 -120
  272. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +9 -0
  273. package/specs/generated-artifacts.md +78 -70
  274. package/specs/migrations/README.md +6 -6
  275. package/specs/migrations/from-centralized-schema.md +1 -1
  276. package/specs/migrations/from-t3-env.md +9 -9
  277. package/PROMPT.md +0 -89
  278. package/dist/build-DNAYWD2B.js.map +0 -1
  279. /package/dist/{chunk-HAGMVMN5.js.map → chunk-4D67AQFY.js.map} +0 -0
@@ -1,7 +1,7 @@
1
1
  import type { BuildFileSystem } from "./types.js";
2
2
  /** Options for {@link discoverSchemaFiles}. */
3
3
  export interface DiscoverOptions {
4
- /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
4
+ /** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
5
5
  readonly fs: BuildFileSystem;
6
6
  /** Absolute path to search under. */
7
7
  readonly root: string;
@@ -13,29 +13,29 @@ export interface DiscoverOptions {
13
13
  /**
14
14
  * Finds every file matching `include`/`exclude` under `root`, returned as
15
15
  * absolute paths in deterministic (alphabetically sorted) order. No count
16
- * limit -- the usage scan walks every TypeScript source file, which a large
16
+ * limit: the usage scan walks every TypeScript source file, which a large
17
17
  * project legitimately has thousands of; {@link discoverSchemaFiles} adds the
18
18
  * schema-specific sanity limit on top.
19
19
  *
20
20
  * @remarks
21
- * No external glob dependency: directories are pruned *during* the walk
21
+ * No external glob dependency. Directories are pruned *during* the walk
22
22
  * (both a hardcoded node_modules/.git skip and the caller's `exclude`
23
- * patterns), rather than walked in full and filtered afterward -- walking an
24
- * entire node_modules tree just to discard it is not acceptable for a tool
25
- * meant to run against real projects.
23
+ * patterns), not walked in full and filtered afterward. Walking an entire
24
+ * node_modules tree just to discard it is not acceptable for a tool meant to
25
+ * run against real projects.
26
26
  */
27
27
  export declare function discoverFiles(options: DiscoverOptions): Promise<string[]>;
28
28
  /**
29
29
  * Finds every schema file matching `include`/`exclude` under `root`, returned
30
- * as absolute paths in deterministic (alphabetically sorted) order -- the
30
+ * as absolute paths in deterministic (alphabetically sorted) order: the
31
31
  * same walk as `discoverFiles`, plus a sanity limit on the count.
32
32
  *
33
33
  * @remarks
34
- * No external glob dependency: directories are pruned *during* the walk
34
+ * No external glob dependency. Directories are pruned *during* the walk
35
35
  * (both a hardcoded node_modules/.git skip and the caller's `exclude`
36
- * patterns), rather than walked in full and filtered afterward -- walking an
37
- * entire node_modules tree just to discard it is not acceptable for a tool
38
- * meant to run against real projects.
36
+ * patterns), not walked in full and filtered afterward. Walking an entire
37
+ * node_modules tree just to discard it is not acceptable for a tool meant to
38
+ * run against real projects.
39
39
  */
40
40
  export declare function discoverSchemaFiles(options: DiscoverOptions): Promise<string[]>;
41
41
  //# sourceMappingURL=discover.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/build/discover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAkBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAa/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBrF"}
1
+ {"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/build/discover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAgBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAa/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBrF"}
@@ -1,7 +1,7 @@
1
1
  import type { ContractModelContract } from "./contract-model.js";
2
2
  import { type EnvGovernanceFields } from "./governance-fields.js";
3
3
  import type { DiscoveredVariableEvidence } from "./parse.js";
4
- /** Identifies a contract with no linked `documentEnv()` call at all. `file`'s absolute-vs-relative convention depends on where a given instance comes from -- see the specific field using this type (`DocumentationFindings.undocumentedContracts` is absolute; `RenderDocsOptions.undocumentedContracts` must be root-relative, matching the `ContractModel`-shaped `contracts` it's compared against). */
4
+ /** Identifies a contract with no linked `documentEnv()` call at all. Whether `file` is absolute or relative depends on the field using this type. `DocumentationFindings.undocumentedContracts` is absolute. `RenderDocsOptions.undocumentedContracts` must be root-relative, matching the `ContractModel`-shaped `contracts` it's compared against. */
5
5
  export interface UndocumentedContractRef {
6
6
  readonly file: string;
7
7
  /** The contract's exported binding name. */
@@ -32,25 +32,25 @@ export interface ExpiringEntry {
32
32
  export interface RenderDocsOptions {
33
33
  /** How many days out counts as "expiring soon" in the lifecycle report and security review. */
34
34
  readonly expiringWithinDays: number;
35
- /** Contracts with no linked `documentEnv()` call at all. `file` must be root-relative, POSIX-separated -- matching `contracts`' own `ContractModel` convention, since this is matched against it by identity. */
35
+ /** Contracts with no linked `documentEnv()` call at all. `file` must be root-relative, POSIX-separated: matching `contracts`' own `ContractModel` convention, since this is matched against it by identity. */
36
36
  readonly undocumentedContracts: readonly UndocumentedContractRef[];
37
37
  /** Schema variables with no matching entry in their contract's linked documentation. Only how many there are is rendered (the security-review counter), so `file` is not matched against anything. */
38
38
  readonly undocumentedVariables: readonly UndocumentedVariableRef[];
39
39
  /** Timestamp rendered into the header and used for expiry/days-remaining math. */
40
40
  readonly generatedAt: Date;
41
- /** Content already at `docs.location`, if any -- used only for the "changes since last report" summary. */
41
+ /** Content already at `docs.location`, if any: used only for the "changes since last report" summary. */
42
42
  readonly previousContent: string | undefined;
43
43
  }
44
44
  /**
45
45
  * Parses `expiresAt` as a real date.
46
46
  *
47
47
  * @remarks
48
- * Malformed strings are silently ignored (return `undefined`) rather than throwing -- same
48
+ * Malformed strings are silently ignored (return `undefined`) rather than throwing: same
49
49
  * "warn/skip, never guess" policy as the rest of the generator. Exported so `live-expirations.ts`
50
50
  * can validate live override values against the exact same rule used for static `expiresAt`.
51
51
  */
52
52
  export declare function parseIsoDate(value: string): Date | undefined;
53
- /** The minimal shape {@link computeExpiringEntries} needs -- structural, not pinned to `DiscoveredContract`, so the exact same rule serves both `LinkResult`'s absolute-path contracts (`generate-documentation.ts`'s `documentation.expiringSoon`, Stable tier) and `ContractModel`'s root-relative ones, whichever a caller already has on hand. */
53
+ /** The minimal shape {@link computeExpiringEntries} needs. It is structural, not pinned to `DiscoveredContract`, so one rule serves both kinds of contract. Those are `LinkResult`'s absolute-path contracts (`generate-documentation.ts`'s `documentation.expiringSoon`, Stable tier) and `ContractModel`'s root-relative ones. */
54
54
  interface ExpiryBearingContract {
55
55
  readonly file: string;
56
56
  readonly exportName: string;
@@ -68,7 +68,7 @@ export declare function computeExpiringEntries(contracts: readonly ExpiryBearing
68
68
  * Same data `renderCatalog()` renders to Markdown for one variable, reshaped for JSON/
69
69
  * programmatic consumers instead of prose.
70
70
  *
71
- * @see `ContractModelVariable` (`contract-model.ts`) -- this same declared variable's canonical
71
+ * @see `ContractModelVariable` (`contract-model.ts`): this same declared variable's canonical
72
72
  * starting point. Plain reference, not `{@link}`: this type is intentionally not part of the
73
73
  * public surface (see `typedoc.json`'s `intentionallyNotExported`).
74
74
  */
@@ -82,9 +82,9 @@ interface CatalogVariable extends EnvGovernanceFields {
82
82
  readonly processorReturnType: string | undefined;
83
83
  readonly hasValidator: boolean;
84
84
  readonly documented: boolean;
85
- /** The variable's declared validation context, if any -- see ADR 0022. Participation data, not documentation: describes when `validateEnv()` processes this variable, not who may access it or what a bundler includes. */
85
+ /** The variable's declared validation context, if any: see ADR 0022. Participation data, not documentation: describes when `validateEnv()` processes this variable, not who may access it or what a bundler includes. */
86
86
  readonly context: string | undefined;
87
- /** The `evidence` sub-object from this variable's linked documentation -- re-verified every run, unlike every declared-only field above. See ADR 0037. */
87
+ /** The `evidence` sub-object from this variable's linked documentation: re-verified every run, unlike every declared-only field above. See ADR 0037. */
88
88
  readonly evidence: DiscoveredVariableEvidence | undefined;
89
89
  }
90
90
  export interface CatalogContract extends EnvGovernanceFields {
@@ -95,7 +95,7 @@ export interface CatalogContract extends EnvGovernanceFields {
95
95
  readonly documented: boolean;
96
96
  readonly category: string | undefined;
97
97
  readonly exclusiveGroup: string | undefined;
98
- /** Keyed by variable name -- unique within one contract (a schema
98
+ /** Keyed by variable name: unique within one contract (a schema
99
99
  * object-literal property name), unlike `contractName` at the top level. */
100
100
  readonly variables: Readonly<Record<string, CatalogVariable>>;
101
101
  }
@@ -108,11 +108,11 @@ export declare function buildCatalog(contracts: readonly ContractModelContract[]
108
108
  export declare function extractPreviouslyDocumentedKeys(previousContent: string): Set<string>;
109
109
  /**
110
110
  * Every variable key that was documented under an *active* contract in a
111
- * previously-generated docs file -- walks the same `- Active: yes/no`
112
- * marker `renderCatalog` always emits immediately after each `## <contract>`
113
- * heading, so a key already inactive last time (a permanently-dormant
114
- * contract, e.g. behind an unused feature flag) is excluded even though it
115
- * still appears as a `### \`KEY\`` heading. Exported for testing.
111
+ * previously-generated docs file. It walks the `- Active: yes/no` marker
112
+ * `renderCatalog` always emits right after each `## <contract>` heading. So a
113
+ * key already inactive last time is excluded (a permanently-dormant contract,
114
+ * e.g. behind an unused feature flag). It is excluded even though it still
115
+ * appears as a `### \`KEY\`` heading. Exported for testing.
116
116
  */
117
117
  export declare function extractPreviouslyActiveKeys(previousContent: string): Set<string>;
118
118
  /** Every number the security review reports, as structured data instead of only rendered Markdown text. */
@@ -135,41 +135,37 @@ export interface SecurityReviewCounters {
135
135
  * Computes every number `renderSecurityReview()` reports, as real data.
136
136
  *
137
137
  * @remarks
138
- * Previously this arithmetic lived entirely inside the renderer as closure
139
- * locals that only ever became interpolated Markdown text -- no exported
140
- * type backed any of it, so nothing downstream (the `--json` envelope, a CI
141
- * gate, a future Finding Model adapter) could consume it as data. Extracted
142
- * so it can be reused wherever these facts are needed, not just prose.
138
+ * An exported type backs these numbers. So consumers other than the
139
+ * rendered Markdown can read them as data: the `--json` envelope, a CI gate,
140
+ * a future Finding Model adapter.
143
141
  */
144
142
  export declare function computeSecurityReviewCounters(contracts: readonly ContractModelContract[], expiringWithinDays: number, now: Date, undocumentedContractCount: number, undocumentedVariableCount: number): SecurityReviewCounters;
145
143
  /**
146
- * Renders the full docs artifact: header + change summary + table of
147
- * contents, then the comprehensive catalog, ownership matrix (if used),
148
- * dependency graph, lifecycle report, and a security review.
144
+ * Renders the full docs artifact. It opens with a header, change summary and
145
+ * table of contents. Then come the catalog, ownership matrix (if used),
146
+ * dependency graph, lifecycle report and security review.
149
147
  *
150
148
  * @remarks
151
149
  * Documents everything discovered, active or not, same scope as the catalog always
152
- * had. Fully regenerated every run -- unlike `.env.example`, nothing here is
150
+ * had. Fully regenerated every run: unlike `.env.example`, nothing here is
153
151
  * meant to be hand-edited, so there's no "never overwrite" behavior.
154
152
  *
155
- * `contracts` is `ContractModel`'s own shape (`file` root-relative and
156
- * POSIX-separated already, per that model's convention) -- there is no
157
- * separate `root` parameter to resolve against, unlike this function's
158
- * pre-ADR-0038 signature.
153
+ * `contracts` is `ContractModel`'s own shape, so `file` is already
154
+ * root-relative and POSIX-separated (ADR 0038). There is no separate `root`
155
+ * parameter to resolve against.
159
156
  */
160
157
  export declare function renderDocs(contracts: readonly ContractModelContract[], options: RenderDocsOptions): string;
161
158
  /**
162
- * Normalizes every wall-clock-relative substring `renderDocs()` can produce
163
- * -- not just the single `_Generated ..._` timestamp line, but also the
164
- * lifecycle report's `(**Xd remaining**)`/`(**expired Xd ago**)` annotations
165
- * and the security review's "Already expired"/"Expiring within N days"
166
- * counts -- so two renders of the *same* input, taken on different days,
167
- * compare equal. `check-artifacts.ts`'s drift comparison and the examples
168
- * golden-file test harness (`test/support/example-runner.ts`) both need
169
- * exactly this, not just the timestamp line alone: any contract with a near-term
170
- * `expiresAt` renders day-relative text that would otherwise make `--check`
171
- * (or a golden-file comparison) report false drift purely because real time
172
- * passed between generation and comparison.
159
+ * Normalizes every wall-clock-relative substring `renderDocs()` can produce,
160
+ * so two renders of the *same* input on different days compare equal. That
161
+ * covers the `_Generated ..._` timestamp line, the lifecycle report's
162
+ * `(**Xd remaining**)`/`(**expired Xd ago**)` annotations, and the security
163
+ * review's "Already expired"/"Expiring within N days" counts.
164
+ * `check-artifacts.ts`'s drift comparison and the examples golden-file test
165
+ * harness (`test/support/example-runner.ts`) both need all of it. A contract
166
+ * with a near-term `expiresAt` renders day-relative text. Without this,
167
+ * `--check` (or a golden-file comparison) would report false drift only
168
+ * because real time passed between generation and comparison.
173
169
  */
174
170
  export declare function normalizeDocsForComparison(content: string): string;
175
171
  export {};
@@ -1 +1 @@
1
- {"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/build/docs.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/build/docs.ts"],"names":[],"mappings":"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"}
@@ -2,7 +2,7 @@ import type { DiscoveredContract } from "./link.js";
2
2
  import type { BuildFileSystem } from "./types.js";
3
3
  /**
4
4
  * Controls what happens when a `.env.example` already exists at the target
5
- * location. `"keep-sibling"` (default): never touch the existing file --
5
+ * location. `"keep-sibling"` (default): never touch the existing file;
6
6
  * write a timestamped sibling instead, for the developer to diff/merge
7
7
  * manually. `"overwrite"`: replace the existing file with freshly rendered
8
8
  * content directly. `"skip"`: write nothing at all.
@@ -25,7 +25,7 @@ export interface EnvExampleResult {
25
25
  readonly skippedExistingPath: string | undefined;
26
26
  /** Variable names (live or already commented-out) in an existing example file that no discovered contract declares anymore. */
27
27
  readonly staleVariables: readonly string[];
28
- /** Variables live in an existing example file whose feature is no longer active, and that no other active feature still needs -- safe to comment out. */
28
+ /** Variables live in an existing example file whose feature is no longer active, and that no other active feature still needs: safe to comment out. */
29
29
  readonly variablesToComment: readonly string[];
30
30
  /** Variables the current (active) configuration requires that aren't yet a live entry in an existing example file. */
31
31
  readonly variablesToAdd: readonly string[];
@@ -34,29 +34,29 @@ export interface EnvExampleResult {
34
34
  export interface Reconciliation {
35
35
  /** Variable names (live or already commented-out) in an existing example file that no discovered contract declares anymore. */
36
36
  readonly staleVariables: readonly string[];
37
- /** Variables live in an existing example file whose feature is no longer active, and that no other active feature still needs -- safe to comment out. */
37
+ /** Variables live in an existing example file whose feature is no longer active, and that no other active feature still needs: safe to comment out. */
38
38
  readonly variablesToComment: readonly string[];
39
39
  /** Variables the current (active) configuration requires that aren't yet a live entry in an existing example file. */
40
40
  readonly variablesToAdd: readonly string[];
41
41
  }
42
42
  /**
43
43
  * Renders a deterministic `.env.example`-style file scoped to the *current*
44
- * configuration: every unique variable the active contracts require (one
45
- * live entry per key, alphabetical; a key declared by more than one active
46
- * contract renders once live and the rest commented-out with a pointer),
47
- * followed by variables unique to disabled contracts (commented-out, for
48
- * visibility -- a key already required by an active contract is not unique
49
- * and never repeated here). `reconciliationHeader`, when non-empty, is
44
+ * configuration. It lists every unique variable the active contracts
45
+ * require, one live entry per key, alphabetically. A key declared by more
46
+ * than one active contract renders once live; the rest are commented out
47
+ * with a pointer. Variables unique to disabled contracts follow, commented
48
+ * out for visibility. A key already required by an active contract is not
49
+ * unique and never repeated there. `reconciliationHeader`, when non-empty, is
50
50
  * spliced in right after the banner (see `computeReconciliation`).
51
51
  */
52
52
  export declare function renderEnvExample(contracts: readonly DiscoveredContract[], reconciliationHeader?: readonly string[]): string;
53
53
  /** Parses `KEY=value` lines out of an existing `.env`-style file, ignoring comments and blank lines. */
54
54
  export declare function extractDeclaredVariables(source: string): string[];
55
- /** Parses `# KEY=value` lines out of an existing `.env`-style file -- variables it already knows about but has turned off. */
55
+ /** Parses `# KEY=value` lines out of an existing `.env`-style file: variables it already knows about but has turned off. */
56
56
  export declare function extractCommentedVariables(source: string): string[];
57
57
  /**
58
58
  * Diffs an existing `.env.example` against the current configuration into
59
- * three actionable sets. Pure and filesystem-independent -- `writeEnvExample`
59
+ * three actionable sets. Pure and filesystem-independent: `writeEnvExample`
60
60
  * is the only caller that reads the file itself.
61
61
  */
62
62
  export declare function computeReconciliation(contracts: readonly DiscoveredContract[], existingContent: string): Reconciliation;
@@ -70,14 +70,14 @@ export declare function computeReconciliation(contracts: readonly DiscoveredCont
70
70
  * comparing it against the existing file (omitted when there's nothing
71
71
  * to report).
72
72
  * - `"overwrite"`: the existing file is replaced directly with freshly
73
- * rendered content -- no reconciliation header (the changes it would
73
+ * rendered content; no reconciliation header (the changes it would
74
74
  * describe are already applied).
75
75
  * - `"skip"`: nothing is written.
76
76
  * When no file exists yet at `location`, all three modes behave the same:
77
77
  * write fresh content, nothing to reconcile against. `staleVariables`/
78
78
  * `variablesToComment`/`variablesToAdd` are always computed and returned
79
79
  * when a prior file existed, even under `"overwrite"`/`"skip"`, as a
80
- * diagnostic -- independent of whether anything was actually written.
80
+ * diagnostic: independent of whether anything was actually written.
81
81
  */
82
82
  export declare function writeEnvExample(contracts: readonly DiscoveredContract[], location: string, fs: BuildFileSystem, options?: {
83
83
  onExisting?: EnvExampleOnExisting;
@@ -1 +1 @@
1
- {"version":3,"file":"env-example.d.ts","sourceRoot":"","sources":["../../../src/build/env-example.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGjD;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,WAAW,GAAG,MAAM,CAAA;AAExE,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,+HAA+H;IAC/H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,yJAAyJ;IACzJ,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAED,wHAAwH;AACxH,MAAM,WAAW,cAAc;IAC7B,+HAA+H;IAC/H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,yJAAyJ;IACzJ,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAuED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,oBAAoB,GAAE,SAAS,MAAM,EAAO,GAC3C,MAAM,CAiDR;AAED,wGAAwG;AACxG,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAQjE;AAED,8HAA8H;AAC9H,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAQlE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,eAAe,EAAE,MAAM,GACtB,cAAc,CAkBhB;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,eAAe,EACnB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,oBAAoB,CAAA;CAAO,GAClD,OAAO,CAAC,gBAAgB,CAAC,CA6D3B"}
1
+ {"version":3,"file":"env-example.d.ts","sourceRoot":"","sources":["../../../src/build/env-example.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGjD;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,WAAW,GAAG,MAAM,CAAA;AAExE,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,+HAA+H;IAC/H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,uJAAuJ;IACvJ,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAED,wHAAwH;AACxH,MAAM,WAAW,cAAc;IAC7B,+HAA+H;IAC/H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,uJAAuJ;IACvJ,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAuED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,oBAAoB,GAAE,SAAS,MAAM,EAAO,GAC3C,MAAM,CAiDR;AAED,wGAAwG;AACxG,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAQjE;AAED,4HAA4H;AAC5H,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAQlE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,eAAe,EAAE,MAAM,GACtB,cAAc,CAkBhB;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,eAAe,EACnB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,oBAAoB,CAAA;CAAO,GAClD,OAAO,CAAC,gBAAgB,CAAC,CA6D3B"}
@@ -4,10 +4,10 @@ import type { CompatibilityIssue } from "./compatibility.js";
4
4
  * finding, or an output path escaping `root`.
5
5
  *
6
6
  * @remarks
7
- * Nothing is written when this throws -- generation fails atomically, same as
7
+ * Nothing is written when this throws: generation fails atomically, same as
8
8
  * {@link runtime.validateEnv} fails atomically at runtime.
9
9
  *
10
- * `code` is a stable, Stable-tier discriminant for programmatic handling --
10
+ * `code` is a stable, Stable-tier discriminant for programmatic handling:
11
11
  * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
12
12
  */
13
13
  export declare class EnvManifestGenerationError extends Error {
@@ -24,7 +24,7 @@ export declare class EnvManifestGenerationError extends Error {
24
24
  * when this throws.
25
25
  *
26
26
  * @remarks
27
- * `code` is a stable, Stable-tier discriminant for programmatic handling --
27
+ * `code` is a stable, Stable-tier discriminant for programmatic handling:
28
28
  * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
29
29
  */
30
30
  export declare class EnvDocumentationGenerationError extends Error {
@@ -40,10 +40,10 @@ export declare class EnvDocumentationGenerationError extends Error {
40
40
  * output path (`report.location`) escaping `root`.
41
41
  *
42
42
  * @remarks
43
- * Never thrown for `unresolvedConsumers` or `indeterminate` findings -- both are "we don't
43
+ * Never thrown for `unresolvedConsumers` or `indeterminate` findings: both are "we don't
44
44
  * know" states, and uncertainty is never promoted to a failure.
45
45
  *
46
- * `code` is a stable, Stable-tier discriminant for programmatic handling --
46
+ * `code` is a stable, Stable-tier discriminant for programmatic handling:
47
47
  * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
48
48
  */
49
49
  export declare class EnvUsageAnalysisError extends Error {
@@ -59,13 +59,13 @@ export declare class EnvUsageAnalysisError extends Error {
59
59
  * one error.
60
60
  *
61
61
  * @remarks
62
- * Nothing from any pass is written when this throws -- see
62
+ * Nothing from any pass is written when this throws: see
63
63
  * `generate-env-artifacts.ts`'s compute-atomic guarantee (ADR 0011). Write-phase failures
64
64
  * (a real I/O error after all computes already passed) are NOT wrapped in
65
- * this type -- they propagate as whatever `fs.writeFile` itself throws,
65
+ * this type: they propagate as whatever `fs.writeFile` itself throws,
66
66
  * since by that point some artifacts may already be on disk.
67
67
  *
68
- * `code` is a stable, Stable-tier discriminant for programmatic handling --
68
+ * `code` is a stable, Stable-tier discriminant for programmatic handling:
69
69
  * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
70
70
  */
71
71
  export declare class EnvProjectGenerationError extends Error {
@@ -2,19 +2,19 @@ import type { EvidenceModel } from "./evidence-model.js";
2
2
  import type { GenerateEvidenceModelOptions } from "./generate-evidence.js";
3
3
  import type { BuildFileSystem } from "./types.js";
4
4
  /**
5
- * A fast, honest read path for the persisted evidence artifact -- for a
6
- * report/projection script, a CI step, or any consumer that just wants the
7
- * current `EvidenceModel` without paying a full `generateEvidenceModel()`
8
- * recompute (schema parsing, cross-file linking, the dependency-graph AST
9
- * scan, all six model builds) on every single invocation, and without ever
10
- * risking silently-stale data. The mechanism: a cheap content fingerprint,
5
+ * A fast, honest read path for the persisted evidence artifact. It serves a
6
+ * report/projection script, a CI step, or any consumer that wants the
7
+ * current `EvidenceModel` without silently-stale data. Such a consumer
8
+ * avoids a full `generateEvidenceModel()` recompute on every invocation
9
+ * (schema parsing, cross-file linking, the dependency-graph AST scan, all six
10
+ * model builds). The mechanism: a cheap content fingerprint,
11
11
  * computed from raw file bytes with zero AST work, lets a caller cheaply
12
12
  * prove "nothing relevant to evidence generation has changed since this file
13
13
  * was last written" before trusting it.
14
14
  */
15
15
  /** Options for {@link computeSourceFingerprint}. */
16
16
  export interface ComputeSourceFingerprintOptions {
17
- /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
17
+ /** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
18
18
  readonly fs: BuildFileSystem;
19
19
  readonly root: string;
20
20
  readonly include: readonly string[];
@@ -24,49 +24,49 @@ export interface ComputeSourceFingerprintOptions {
24
24
  /**
25
25
  * SHA-256 over the raw bytes of every schema file and every usage-scan-
26
26
  * surface file (the same file sets `assembleProject()`/`computeScanSurface()`
27
- * touch), plus env-cap's own installed version -- zero AST parsing or
27
+ * touch), plus env-cap's own installed version: zero AST parsing or
28
28
  * linking. Still requires the discovery/glob walk itself (fingerprinting has
29
29
  * to know which files matter), but skips everything after it. Deterministic:
30
30
  * file paths are deduplicated and sorted before hashing, so the result never
31
31
  * depends on filesystem enumeration order.
32
32
  *
33
33
  * @remarks
34
- * Not a timestamp, and never compared as one -- a fresh mtime doesn't prove
34
+ * Not a timestamp, and never compared as one. A fresh mtime doesn't prove
35
35
  * content is unchanged (a checkout, a rebase, or a touch can all bump it
36
- * with no real edit), and content is the only thing that actually
37
- * invalidates a cached evidence artifact.
36
+ * with no real edit). Content is the only thing that invalidates a cached
37
+ * evidence artifact.
38
38
  */
39
39
  export declare function computeSourceFingerprint(options: ComputeSourceFingerprintOptions): Promise<string>;
40
- /** Writes `fingerprint`'s paired sidecar for `evidencePath` -- call immediately after writing the evidence artifact itself, so the two files always describe the same moment in the source tree's history. */
40
+ /** Writes `fingerprint`'s paired sidecar for `evidencePath`: call immediately after writing the evidence artifact itself, so the two files always describe the same moment in the source tree's history. */
41
41
  export declare function writeEvidenceFingerprint(evidencePath: string, fingerprint: string, fs: BuildFileSystem): Promise<void>;
42
- /** Options for {@link getEvidenceModel} -- every `generateEvidenceModel()` option, plus where the cached artifact lives. */
42
+ /** Options for {@link getEvidenceModel}: every `generateEvidenceModel()` option, plus where the cached artifact lives. */
43
43
  export interface GetEvidenceModelOptions extends GenerateEvidenceModelOptions {
44
- /** Where the cached evidence artifact (and its `.fingerprint` sidecar) live, e.g. `docs/env.evidence.json`, relative to `root`. Required -- there is no honest default env-cap could guess at for where a project keeps this. */
44
+ /** Where the cached evidence artifact (and its `.fingerprint` sidecar) live, e.g. `docs/env.evidence.json`, relative to `root`. Required: there is no honest default env-cap could guess at for where a project keeps this. */
45
45
  readonly location: string;
46
46
  }
47
47
  /** The result of {@link getEvidenceModel}. */
48
48
  export interface GetEvidenceModelResult {
49
49
  readonly evidence: EvidenceModel;
50
- /** `"hit"` -- the committed evidence artifact's fingerprint matched current source; read from disk, no recompute. `"miss"` -- a real `generateEvidenceModel()` call ran. */
50
+ /** `"hit"`: the committed evidence artifact's fingerprint matched current source; read from disk, no recompute. `"miss"`: a real `generateEvidenceModel()` call ran. */
51
51
  readonly source: "hit" | "miss";
52
- /** Set only when `source === "miss"` -- why the cache wasn't trusted, for a caller that wants to log it. */
52
+ /** Set only when `source === "miss"`: why the cache wasn't trusted, for a caller that wants to log it. */
53
53
  readonly missReason: string | undefined;
54
54
  }
55
55
  /**
56
56
  * Trusts the committed evidence artifact at `options.location` only when its
57
57
  * paired `.fingerprint` sidecar matches a freshly (cheaply) computed
58
- * {@link computeSourceFingerprint} -- never on file presence alone, never on
58
+ * {@link computeSourceFingerprint}: never on file presence alone, never on
59
59
  * a timestamp. On any mismatch (stale fingerprint, missing/corrupt evidence
60
60
  * file, no fingerprint sidecar at all), falls back to a real
61
- * `generateEvidenceModel()` call -- never hard-fails, never silently serves
61
+ * `generateEvidenceModel()` call: never hard-fails, never silently serves
62
62
  * data that might be stale.
63
63
  *
64
64
  * @remarks
65
- * Never writes anything. A cache miss here does not self-heal the cache --
66
- * only an explicit write (`generateEnvArtifacts()`'s `evidence` option)
67
- * refreshes the committed artifact and its fingerprint together, so "when
68
- * was this last regenerated" stays under explicit control, never an
69
- * implicit side effect of a read. Two independent callers hitting the same
65
+ * Never writes anything. A cache miss here does not self-heal the cache.
66
+ * Only an explicit write (`generateEnvArtifacts()`'s `evidence` option)
67
+ * refreshes the committed artifact and its fingerprint together. That keeps
68
+ * "when was this last regenerated" under explicit control, never an implicit
69
+ * side effect of a read. Two independent callers hitting the same
70
70
  * stale cache both recompute independently; neither one's recompute updates
71
71
  * the file the other reads.
72
72
  */
@@ -1 +1 @@
1
- {"version":3,"file":"evidence-cache.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-cache.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAKxD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAA;AAO1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;GAUG;AAEH,oDAAoD;AACpD,MAAM,WAAW,+BAA+B;IAC9C,iFAAiF;IACjF,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;CAClD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAMD,8MAA8M;AAC9M,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,4HAA4H;AAC5H,MAAM,WAAW,uBAAwB,SAAQ,4BAA4B;IAC3E,iOAAiO;IACjO,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,4KAA4K;IAC5K,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAA;IAC/B,4GAA4G;IAC5G,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAuDjC"}
1
+ {"version":3,"file":"evidence-cache.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-cache.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAKxD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAA;AAO1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;GAUG;AAEH,oDAAoD;AACpD,MAAM,WAAW,+BAA+B;IAC9C,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;CAClD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,MAAM,CAAC,CA4CjB;AAMD,4MAA4M;AAC5M,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,0HAA0H;AAC1H,MAAM,WAAW,uBAAwB,SAAQ,4BAA4B;IAC3E,+NAA+N;IAC/N,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,wKAAwK;IACxK,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAA;IAC/B,0GAA0G;IAC1G,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAuDjC"}
@@ -7,12 +7,12 @@ import type { OwnershipModel } from "./ownership-model.js";
7
7
  /**
8
8
  * Bump only when a reader could misinterpret the new shape of `EvidenceModel`
9
9
  * itself (not any one sub-model's own `<MODEL>_SCHEMA_VERSION`, which is
10
- * versioned independently) -- same rule every other canonical model follows.
10
+ * versioned independently): same rule every other canonical model follows.
11
11
  */
12
12
  export declare const EVIDENCE_MODEL_SCHEMA_VERSION = 1;
13
13
  /**
14
14
  * Who/when/what produced a given `EvidenceModel` instance. Caller-supplied,
15
- * never ambient-detected -- `generateEvidenceModel()` never shells out to
15
+ * never ambient-detected: `generateEvidenceModel()` never shells out to
16
16
  * `git` itself, mirroring ADR 0012's live-expiration-callback precedent.
17
17
  */
18
18
  export interface EvidenceProvenance {
@@ -30,7 +30,7 @@ export interface EvidenceProvenance {
30
30
  * This type is the one intentional exception to `src/build/`'s zero-
31
31
  * cross-folder-import rule: `src/evidence/` imports it with `import type`
32
32
  * only (fully erased at compile time under `verbatimModuleSyntax`), the same
33
- * shape as `helpers`' single sanctioned edge onto `runtime` -- see
33
+ * shape as `helpers`' single sanctioned edge onto `runtime`; see
34
34
  * `specs/architecture.md`. `src/evidence/` never imports a *value* from
35
35
  * here, only this shape, so it stays isomorphic and Node-free. An actual
36
36
  * `EvidenceModel` instance is produced by {@link generateEvidenceModel}
@@ -1,53 +1,53 @@
1
1
  import type { SourcePosition } from "./source-position.js";
2
2
  /**
3
3
  * A structured pointer back to where a `Finding` (or, later, any other
4
- * model's derived fact) came from -- never a formatted string. See ADR 0024
4
+ * model's derived fact) came from: never a formatted string. See ADR 0024
5
5
  * and ADR 0026.
6
6
  *
7
7
  * @remarks
8
8
  * Deliberately only as many `model` variants as something in this codebase
9
9
  * actually needs to reference today (`"contract"`, `"ownership"`,
10
10
  * `"change"`). This is an additive, growable union, not a speculative
11
- * six-model union built ahead of a real consumer -- a later phase (e.g. the
11
+ * six-model union built ahead of a real consumer. Another model (e.g. the
12
12
  * Dependency or Lifecycle Model) adds its own variant only once a finding
13
- * or projector genuinely needs to point at it.
13
+ * or projector needs to point at it.
14
14
  */
15
15
  export type EvidenceReference = ContractEvidenceReference | OwnershipEvidenceReference | ChangeEvidenceReference;
16
16
  /**
17
17
  * The one shape every model in this package uses to point at a declared
18
18
  * contract: the file it's declared in, and the binding it's exported as.
19
- * Nothing else -- see ADR 0039.
19
+ * Nothing else: see ADR 0039.
20
20
  *
21
21
  * @remarks
22
22
  * Deliberately *not* carrying `contractName`. A display name is a rendering
23
- * concern, resolved on demand from `ContractModel` (the one model that owns
24
- * it) by whichever renderer actually needs prose; duplicating it onto every
25
- * reference made it a second, independently-stale copy of a fact that can
26
- * change under a `documentEnv()` edit. Deliberately not carrying a
27
- * pre-formatted `identity` string either -- `${file}#${exportName}` is
23
+ * concern. A renderer that needs prose resolves it on demand from
24
+ * `ContractModel`, the one model that owns it. A copy on every reference
25
+ * would go stale independently, since the name can change under a
26
+ * `documentEnv()` edit. Deliberately not carrying a
27
+ * pre-formatted `identity` string either: `${file}#${exportName}` is
28
28
  * trivially derivable, and a stored copy is one more thing that can disagree
29
29
  * with the two fields it was built from. Code that genuinely needs a map key
30
30
  * builds that string locally, at the point of use.
31
31
  */
32
32
  export interface ContractRef {
33
- /** Root-relative, POSIX-separated path of the file declaring the contract -- see `displayPath()`. */
33
+ /** Root-relative, POSIX-separated path of the file declaring the contract: see `displayPath()`. */
34
34
  readonly file: string;
35
35
  /** The binding name the `createEnv()` result is exported as. */
36
36
  readonly exportName: string;
37
37
  }
38
- /** Points at a declared contract and, optionally, one of its variables -- the shape every `CompatibilityIssue`/documentation finding can be resolved to. Unlike {@link ContractRef}, both identity fields are optional here: a finding can legitimately know only the file (an unresolvable `documentEnv()` link) or neither. */
38
+ /** Points at a declared contract and, optionally, one of its variables: the shape every `CompatibilityIssue`/documentation finding can be resolved to. Unlike {@link ContractRef}, both identity fields are optional here: a finding can legitimately know only the file (an unresolvable `documentEnv()` link) or neither. */
39
39
  export interface ContractEvidenceReference {
40
40
  readonly model: "contract";
41
- /** Root-relative, POSIX-separated path of the file declaring the contract, when known -- see `displayPath()`. */
41
+ /** Root-relative, POSIX-separated path of the file declaring the contract, when known: see `displayPath()`. */
42
42
  readonly file: string | undefined;
43
43
  /** The contract's exported binding name, when known. */
44
44
  readonly exportName: string | undefined;
45
45
  /** The environment variable name, when the finding is variable-level rather than contract-level. */
46
46
  readonly variable: string | undefined;
47
- /** Exact file:line:column this finding is about -- the contract's `createEnv()` declaration, its `documentEnv()` declaration, or the specific variable's own declaration, whichever is most relevant to the finding. `undefined` only when no single position is more relevant than another (e.g. an `indeterminate-ownership` finding, which can have multiple candidate sites -- see `IndeterminateOwnershipFinding.dynamicAccessSites` for the full list instead). See ADR 0036. */
47
+ /** Exact file:line:column this finding is about; the contract's `createEnv()` declaration, its `documentEnv()` declaration, or the specific variable's own declaration, whichever is most relevant to the finding. `undefined` only when no single position is more relevant than another (e.g. an `indeterminate-ownership` finding, which can have multiple candidate sites: see `IndeterminateOwnershipFinding.dynamicAccessSites` for the full list instead). See ADR 0036. */
48
48
  readonly position: SourcePosition | undefined;
49
49
  }
50
- /** Points at a contract by name for an ownership/usage finding -- `usage-report.ts`'s finding types don't consistently carry `file`/`exportName` together, only `contractName`. */
50
+ /** Points at a contract by name for an ownership/usage finding: `usage-report.ts`'s finding types don't consistently carry `file`/`exportName` together, only `contractName`. */
51
51
  export interface OwnershipEvidenceReference {
52
52
  readonly model: "ownership";
53
53
  readonly contractName: string;
@@ -58,7 +58,7 @@ export interface OwnershipEvidenceReference {
58
58
  /** See {@link ContractEvidenceReference.position}. */
59
59
  readonly position: SourcePosition | undefined;
60
60
  }
61
- /** Points at a generated artifact's path -- what `checkEnvArtifacts()`'s drift findings are about, not a declared contract or variable at all. */
61
+ /** Points at a generated artifact's path: what `checkEnvArtifacts()`'s drift findings are about, not a declared contract or variable at all. */
62
62
  export interface ChangeEvidenceReference {
63
63
  readonly model: "change";
64
64
  /** Absolute path of the generated artifact. */
@@ -1 +1 @@
1
- {"version":3,"file":"evidence-reference.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-reference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GAC3B,yBAAyB,GAAG,0BAA0B,GAAG,uBAAuB,CAAA;AAElF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,WAAW;IAC1B,qGAAqG;IACrG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,iUAAiU;AACjU,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,iHAAiH;IACjH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,udAAud;IACvd,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CAC9C;AAED,mLAAmL;AACnL,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CAC9C;AAED,kJAAkJ;AAClJ,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB"}
1
+ {"version":3,"file":"evidence-reference.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-reference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GAC3B,yBAAyB,GAAG,0BAA0B,GAAG,uBAAuB,CAAA;AAElF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,WAAW;IAC1B,mGAAmG;IACnG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,+TAA+T;AAC/T,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,+GAA+G;IAC/G,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,mdAAmd;IACnd,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CAC9C;AAED,iLAAiL;AACjL,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CAC9C;AAED,gJAAgJ;AAChJ,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB"}