@maverickcer/env-cap 0.7.5 → 0.7.6

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 (278) hide show
  1. package/ADOPTION.md +12 -12
  2. package/AGENTS.md +85 -120
  3. package/CHANGELOG.md +27 -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-UEENZEUX.js} +37 -39
  245. package/dist/build-UEENZEUX.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-TBL3O7IG.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 +18 -10
  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/generated-artifacts.md +78 -70
  273. package/specs/migrations/README.md +6 -6
  274. package/specs/migrations/from-centralized-schema.md +1 -1
  275. package/specs/migrations/from-t3-env.md +9 -9
  276. package/PROMPT.md +0 -89
  277. package/dist/build-DNAYWD2B.js.map +0 -1
  278. /package/dist/{chunk-HAGMVMN5.js.map → chunk-TBL3O7IG.js.map} +0 -0
@@ -10,7 +10,7 @@ import type { ParseWarning } from "./parse.js";
10
10
  import type { BuildFileSystem } from "./types.js";
11
11
  /** Options for {@link generateEnvArtifacts}. */
12
12
  export interface GenerateEnvArtifactsOptions {
13
- /** The filesystem capability, shared across every requested pass -- `./build` never imports `node:fs` (ADR 0040). */
13
+ /** The filesystem capability, shared across every requested pass: `./build` never imports `node:fs` (ADR 0040). */
14
14
  fs: BuildFileSystem;
15
15
  /** Directory glob patterns are resolved against, shared across every requested pass. Defaults to `process.cwd()`. */
16
16
  root?: string | undefined;
@@ -30,14 +30,14 @@ export interface GenerateEnvArtifactsOptions {
30
30
  usage?: Omit<GenerateUsageReportOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig"> | false | undefined;
31
31
  /**
32
32
  * Where to write the persisted evidence artifact (the full, literal
33
- * `EvidenceModel`, plus a paired `.fingerprint` sidecar -- see
33
+ * `EvidenceModel`, plus a paired `.fingerprint` sidecar: see
34
34
  * `evidence-cache.ts`), e.g. `docs/env.evidence.json`, relative to `root`.
35
- * Independent of `manifest.location` -- requesting this needs no other
35
+ * Independent of `manifest.location`: requesting this needs no other
36
36
  * pass, and generating a manifest never requires it. `EvidenceModel`
37
- * itself is always computed regardless of this option (ADR 0038, "free to
38
- * compute, always real") and always returned as `result.evidence`; this
39
- * option controls only whether it's also written to disk. Omitted:
40
- * nothing is written, `result.evidence` is still populated.
37
+ * itself is always computed (ADR 0038, "free to compute, always real") and
38
+ * always returned as `result.evidence`. This option controls only whether
39
+ * it's also written to disk. Omitted: nothing is written, and
40
+ * `result.evidence` is still populated.
41
41
  */
42
42
  evidence?: {
43
43
  location: string;
@@ -45,21 +45,21 @@ export interface GenerateEnvArtifactsOptions {
45
45
  /**
46
46
  * Escalates every warning-severity `"documentation"`-family finding
47
47
  * (undocumented contracts/variables, stale doc entries, expiring/expired
48
- * entries, unresolvable `documentEnv()` links) into a blocking error, so a
49
- * run with any of them writes nothing and throws. Defaults to `"warn"` --
50
- * ADR 0038's stance, unchanged: documentation gaps never block by default.
48
+ * entries, unresolvable `documentEnv()` links) into a blocking error. A
49
+ * run with any of them then writes nothing and throws. Defaults to
50
+ * `"warn"`: per ADR 0038, documentation gaps never block by default.
51
51
  *
52
52
  * @remarks
53
53
  * Scoped deliberately narrowly, unlike `manifest.onIncompatibility`, which
54
54
  * gates only the compatibility family. `"info"`-severity findings are never
55
- * escalated by either -- see `Finding.severity`.
55
+ * escalated by either: see `Finding.severity`.
56
56
  */
57
57
  onUndocumented?: "warn" | "throw" | undefined;
58
58
  /**
59
59
  * Escalates every warning-severity `"ownership"`-family finding (abandoned
60
60
  * contracts, unresolved consumers, unconsumed owned variables,
61
61
  * indeterminate ownership, stale/missing `dynamicAccess` citations) into a
62
- * blocking error. Defaults to `"warn"` -- see {@link onUndocumented}.
62
+ * blocking error. Defaults to `"warn"`: see {@link onUndocumented}.
63
63
  */
64
64
  onOwnershipIssue?: "warn" | "throw" | undefined;
65
65
  /**
@@ -80,14 +80,14 @@ export interface GenerateEnvArtifactsResult {
80
80
  readonly docs: GenerateDocumentationResult | undefined;
81
81
  /** Set only when `options.usage` wasn't `false`. */
82
82
  readonly usage: GenerateUsageReportResult | undefined;
83
- /** Always populated, regardless of `options.evidence` -- see that option's own doc comment. */
83
+ /** Always populated, regardless of `options.evidence`: see that option's own doc comment. */
84
84
  readonly evidence: EvidenceModel;
85
85
  }
86
86
  /**
87
87
  * Every intermediate value both the write path (`generateEnvArtifacts()`
88
88
  * below) and the drift-check path (`checkEnvArtifacts()` in
89
89
  * `check-artifacts.ts`) need, computed exactly once. Internal/Private tier
90
- * per `VERSIONING.md` -- not re-exported from `./index.ts`.
90
+ * per `VERSIONING.md`: not re-exported from `./index.ts`.
91
91
  */
92
92
  export interface ComputeArtifactsResult {
93
93
  readonly root: string;
@@ -103,7 +103,7 @@ export interface ComputeArtifactsResult {
103
103
  readonly path: string;
104
104
  readonly envExamplePath: string | undefined;
105
105
  } | undefined;
106
- /** Always computed -- Finding Model needs it regardless of whether a `docs` pass was itself requested. See ADR 0038. */
106
+ /** Always computed: Finding Model needs it regardless of whether a `docs` pass was itself requested. See ADR 0038. */
107
107
  readonly docsComputed: DocumentationComputation;
108
108
  readonly docsContracts: readonly DiscoveredContract[];
109
109
  /** Set only when a usage pass was requested; `reportPath` only when it also asked for a report file. */
@@ -111,7 +111,7 @@ export interface ComputeArtifactsResult {
111
111
  readonly options: Omit<GenerateUsageReportOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig">;
112
112
  readonly reportPath: string | undefined;
113
113
  } | undefined;
114
- /** Always computed -- Finding Model needs it regardless of whether a `usage` pass was itself requested. See ADR 0038. */
114
+ /** Always computed: Finding Model needs it regardless of whether a `usage` pass was itself requested. See ADR 0038. */
115
115
  readonly usageComputed: UsageComputation;
116
116
  readonly evidencePath: string | undefined;
117
117
  readonly evidence: EvidenceModel;
@@ -123,26 +123,26 @@ export interface ComputeArtifactsResult {
123
123
  }
124
124
  /**
125
125
  * Adapts every warning-severity finding of one family into the
126
- * `CompatibilityIssue` shape `blocking`/`EnvProjectGenerationError` speak, so
127
- * `--strict-docs`/`--strict-ownership` fail through exactly the same path
128
- * `--strict` already does rather than inventing a second failure mode.
126
+ * `CompatibilityIssue` shape `blocking`/`EnvProjectGenerationError` speak.
127
+ * So `--strict-docs`/`--strict-ownership` fail through the same path as
128
+ * `--strict`, with no second failure mode.
129
129
  *
130
130
  * @remarks
131
131
  * `"info"` findings are filtered out unconditionally and can never be
132
- * escalated by any flag -- they're observations, not gaps (see
133
- * `Finding.severity`). `"error"` findings are excluded too: those already
134
- * block on their own, via the manifest pass, and re-adding them here would
135
- * report the same violation twice in one error message. `code` is left unset
136
- * -- `CompatibilityIssueCode` is that check family's own closed vocabulary,
132
+ * escalated by any flag: they're observations, not gaps (see
133
+ * `Finding.severity`). `"error"` findings are excluded too. They already
134
+ * block on their own, via the manifest pass. Re-adding them here would
135
+ * report the same violation twice in one error message. `code` is left unset:
136
+ * `CompatibilityIssueCode` is that check family's own closed vocabulary,
137
137
  * and a `FindingCode` from another family is not a member of it.
138
138
  */
139
- /** @internal Exported for direct unit coverage -- reached through `generateEnvArtifacts()`'s `--strict-docs`/`--strict-ownership` flags in production, but its filter/mapping logic isn't independently observable through that path alone (every mutant on it still needs a real `computeArtifacts()` call, discovery included, to reach it). */
139
+ /** @internal Exported for direct unit coverage: reached through `generateEnvArtifacts()`'s `--strict-docs`/`--strict-ownership` flags in production, but its filter/mapping logic isn't independently observable through that path alone (every mutant on it still needs a real `computeArtifacts()` call, discovery included, to reach it). */
140
140
  export declare function escalatedFindings(findings: readonly Finding[], family: FindingFamily): CompatibilityIssue[];
141
- /** The variable a finding is about, or a `"(contract) <name>"` label when it's contract-level -- matching `CompatibilityIssue.variable`'s own documented convention.
142
- * @internal Exported for direct unit coverage -- see {@link escalatedFindings}'s own doc comment for why. */
141
+ /** The variable a finding is about, or a `"(contract) <name>"` label when it's contract-level: matching `CompatibilityIssue.variable`'s own documented convention.
142
+ * @internal Exported for direct unit coverage: see {@link escalatedFindings}'s own doc comment for why. */
143
143
  export declare function findingSubject(finding: Finding): string;
144
- /** Every file a finding names, as `CompatibilityIssue.files` -- empty when its location carries none (an ownership finding about a variable, which names no single file).
145
- * @internal Exported for direct unit coverage -- see {@link escalatedFindings}'s own doc comment for why. */
144
+ /** Every file a finding names, as `CompatibilityIssue.files`: empty when its location carries none (an ownership finding about a variable, which names no single file).
145
+ * @internal Exported for direct unit coverage: see {@link escalatedFindings}'s own doc comment for why. */
146
146
  export declare function findingFiles(finding: Finding): string[];
147
147
  /**
148
148
  * A pass's options, or `undefined` when the pass is not requested: `false` skips a pass entirely,
@@ -152,26 +152,26 @@ export declare function findingFiles(finding: Finding): string[];
152
152
  export declare function requestedPass<T extends object>(option: T | false | undefined): T | undefined;
153
153
  /**
154
154
  * Runs schema discovery, linking, and every requested pass's pure `compute*()`
155
- * step -- but never writes anything to disk. Throws `EnvProjectGenerationError`
156
- * immediately if any requested output location escapes `root` (same
157
- * fail-fast-before-any-work guarantee `generateEnvArtifacts()` has always
158
- * given); otherwise returns every intermediate value without itself checking
159
- * `blocking` findings, so callers (the write path below, and `--check`'s
160
- * `checkEnvArtifacts()`) each decide when to throw on those.
155
+ * step: but never writes anything to disk. Throws `EnvProjectGenerationError`
156
+ * immediately if any requested output location escapes `root`, the same
157
+ * fail-fast-before-any-work guarantee `generateEnvArtifacts()` gives.
158
+ * Otherwise returns every intermediate value without checking `blocking`
159
+ * findings. Each caller (the write path below, and `--check`'s
160
+ * `checkEnvArtifacts()`) decides when to throw on those.
161
161
  *
162
162
  * @remarks
163
163
  * The six canonical fact models (Contract/Dependency/Ownership/Lifecycle/
164
164
  * Finding/Change -> `EvidenceModel`) are composed on every call,
165
- * unconditionally, reusing the exact same builders `generateEvidenceModel()`
166
- * calls -- not a second implementation of the same assembly. See ADR 0038.
165
+ * unconditionally. They reuse the builders `generateEvidenceModel()` calls,
166
+ * so there is no second implementation of the same assembly. See ADR 0038.
167
167
  */
168
168
  export declare function computeArtifacts(options: GenerateEnvArtifactsOptions): Promise<ComputeArtifactsResult>;
169
169
  /**
170
170
  * Orchestrates {@link generateEnvManifest}/{@link generateDocumentation}/
171
- * {@link generateUsageReport}, plus the persisted evidence artifact, by
172
- * composing their shared private compute/write pipeline directly, running
173
- * schema discovery+linking exactly once regardless of how many outputs are
174
- * requested -- an orchestrator, not a new analysis engine (see ADR 0011).
171
+ * {@link generateUsageReport}, plus the persisted evidence artifact. It
172
+ * composes their shared private compute/write pipeline directly. Schema
173
+ * discovery+linking runs exactly once, however many outputs are requested.
174
+ * It is an orchestrator, not a new analysis engine (see ADR 0011).
175
175
  *
176
176
  * @remarks
177
177
  * Two distinct atomicity guarantees, not one:
@@ -182,8 +182,8 @@ export declare function computeArtifacts(options: GenerateEnvArtifactsOptions):
182
182
  * begin, each `fs.writeFile` is independent. A real I/O failure partway
183
183
  * through (disk full, permissions changed mid-run) can leave some
184
184
  * artifacts on disk and not others. Transactional (temp-file + rename)
185
- * writes across all three artifacts were considered and rejected as
186
- * disproportionate machinery for a rare failure mode -- see ADR 0011.
185
+ * writes across all three artifacts are not used. They would be
186
+ * disproportionate machinery for a rare failure mode: see ADR 0011.
187
187
  *
188
188
  * @throws {EnvProjectGenerationError} If any requested output location escapes `root`, or if any requested pass reports a blocking finding.
189
189
  */
@@ -1 +1 @@
1
- {"version":3,"file":"generate-env-artifacts.d.ts","sourceRoot":"","sources":["../../../src/build/generate-env-artifacts.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"generate-env-artifacts.d.ts","sourceRoot":"","sources":["../../../src/build/generate-env-artifacts.ts"],"names":[],"mappings":"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"}
@@ -3,7 +3,7 @@ import type { LiveExpirationDates } from "./live-expirations.js";
3
3
  import type { BuildFileSystem } from "./types.js";
4
4
  /** Options for {@link generateEvidenceModel}. */
5
5
  export interface GenerateEvidenceModelOptions {
6
- /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
6
+ /** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
7
7
  fs: BuildFileSystem;
8
8
  /** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
9
9
  root?: string | undefined;
@@ -17,10 +17,10 @@ export interface GenerateEvidenceModelOptions {
17
17
  tsconfig?: string | false | undefined;
18
18
  /**
19
19
  * Where a previously-persisted evidence artifact lives, relative to
20
- * `root` -- read (never written) as the baseline Change Model diffs
20
+ * `root`: read (never written) as the baseline Change Model diffs
21
21
  * against and dynamic-access citation freshness (ADR 0037) compares
22
22
  * content hashes to. Independent of any `.ts` manifest a project may or
23
- * may not also generate -- there is no derivation from a manifest's own
23
+ * may not also generate: there is no derivation from a manifest's own
24
24
  * location. Omitted: treated as the normal first-run state (everything
25
25
  * reads as added, no citation-freshness baseline to compare against),
26
26
  * never an error.
@@ -31,45 +31,45 @@ export interface GenerateEvidenceModelOptions {
31
31
  /**
32
32
  * Supplies expiration metadata from a live source as a post-discovery
33
33
  * override, applied to Lifecycle Model's (and Finding Model's
34
- * `expiring-soon` findings') data only -- Contract Model still reflects the
34
+ * `expiring-soon` findings') data only: Contract Model still reflects the
35
35
  * schema's own static `expiresAt`. See `live-expirations.ts` and ADR 0012.
36
36
  */
37
37
  liveExpirationDates?: LiveExpirationDates | undefined;
38
38
  /**
39
39
  * Resolves the commit SHA to stamp onto `EvidenceModel.provenance.commit`.
40
40
  * Invoked at most once, after discovery/linking completes. env-cap never
41
- * shells out to `git` itself -- see ADR 0012's callback precedent. Omitted:
41
+ * shells out to `git` itself: see ADR 0012's callback precedent. Omitted:
42
42
  * `commit` is `undefined`.
43
43
  */
44
44
  commit?: (() => Promise<string | undefined>) | undefined;
45
45
  }
46
46
  /**
47
- * Node-only assembly orchestrator (ADR 0024, ADR 0031): runs schema
47
+ * Node-only assembly orchestrator (ADR 0024, ADR 0031). It runs schema
48
48
  * discovery and linking once (via `assembleProject()`, shared with
49
- * `computeArtifacts()`), then builds all seven canonical fact models by
50
- * calling each model's own public builder directly -- this function
51
- * introduces no derivation logic of its own, only sequencing and the shared
49
+ * `computeArtifacts()`). It then builds all seven canonical fact models by
50
+ * calling each model's own public builder directly. This function adds no
51
+ * derivation logic of its own, only sequencing and the shared
52
52
  * discovery/linking every builder needs. The result is `deepFreeze()`-d
53
53
  * before being returned.
54
54
  *
55
55
  * @remarks
56
56
  * Deliberately never throws on a data-quality finding (a compatibility
57
- * issue, an undocumented variable, an abandoned contract, ...) -- every one
57
+ * issue, an undocumented variable, an abandoned contract, ...): every one
58
58
  * of those becomes a `Finding` in the returned model's `finding` field
59
- * instead. This is a real difference from `generateEnvManifest()`, which
60
- * throws by default: that's a "should I write this artifact" gate, while
61
- * Evidence Model assembly is a read-only snapshot whose entire purpose is
62
- * representing such issues as data for a consumer's own projection to act
63
- * on (see ADR 0024's mission statement). It still throws
64
- * `EnvProjectGenerationError` for a genuine configuration error --
59
+ * instead. This differs from `generateEnvManifest()`, which throws by
60
+ * default, because that is a "should I write this artifact" gate. Evidence
61
+ * Model assembly is a read-only snapshot. Its purpose is to represent such
62
+ * issues as data for a consumer's own projection to act on (see ADR 0024's
63
+ * mission statement). It still throws
64
+ * `EnvProjectGenerationError` for a genuine configuration error:
65
65
  * `previousSnapshotLocation` escaping `root`.
66
66
  *
67
67
  * The dependency-graph scan underlying Dependency Model (via
68
68
  * `buildDependencyModel()`) and the one underlying Finding Model's
69
69
  * ownership-related findings (via `computeUsage()`) each run their own,
70
- * independent pass over the repository -- a real, accepted cost of calling
71
- * each half's already-tested public building block directly rather than
72
- * hand-deriving a second copy of either's logic here. Both are Node-only,
70
+ * independent pass over the repository. That cost is accepted: each half's
71
+ * already-tested public building block is called directly, rather than a
72
+ * second copy of either's logic being hand-derived here. Both are Node-only,
73
73
  * dev/CI-time-only work (never a runtime hot path), so the redundant I/O is
74
74
  * an honest tradeoff, not an oversight.
75
75
  */
@@ -1 +1 @@
1
- {"version":3,"file":"generate-evidence.d.ts","sourceRoot":"","sources":["../../../src/build/generate-evidence.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAYxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,iFAAiF;IACjF,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAA;IACrD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,aAAa,CAAC,CAyHxB"}
1
+ {"version":3,"file":"generate-evidence.d.ts","sourceRoot":"","sources":["../../../src/build/generate-evidence.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAYxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,+EAA+E;IAC/E,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAA;IACrD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,aAAa,CAAC,CAyHxB"}
@@ -4,7 +4,7 @@ import { type DiscoveredContract, type DiscoveredContractSummary, type LinkResul
4
4
  import type { ParseWarning } from "./parse.js";
5
5
  /** Options for {@link generateEnvManifest}. */
6
6
  export interface GenerateEnvManifestOptions {
7
- /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
7
+ /** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
8
8
  fs: BuildFileSystem;
9
9
  /** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
10
10
  root?: string | undefined;
@@ -28,7 +28,7 @@ export interface GenerateEnvManifestOptions {
28
28
  * whose `compilerOptions.paths`/`baseUrl` resolve aliased import specifiers (e.g.
29
29
  * `"@/lib/env.schema.js"`) encountered during static analysis, so a contract or consumer
30
30
  * reached only through an alias isn't misreported as abandoned/unresolved. Defaults to
31
- * `"tsconfig.json"` at `root` -- on automatically, no opt-in required, since (unlike
31
+ * `"tsconfig.json"` at `root`: on automatically, no opt-in required, since (unlike
32
32
  * `packages`) this never crosses a trust/versioning boundary: every resolved file is
33
33
  * already local, already-trusted project source. Pass `false` to disable entirely. See
34
34
  * ADR 0023.
@@ -54,14 +54,13 @@ export interface GenerateEnvManifestResult {
54
54
  }
55
55
  /**
56
56
  * Default value for {@link GenerateEnvManifestOptions.include}. A function
57
- * (not a bare module-level `const`) so every call gets its own fresh array
58
- * -- a shared literal used from many files (`evidence-cache.ts`,
57
+ * (not a bare module-level `const`) so every call gets its own fresh array.
58
+ * A shared literal used from many files (`evidence-cache.ts`,
59
59
  * `generate-documentation.ts`, `generate-evidence.ts`,
60
- * `generate-env-artifacts.ts`, `generate-usage.ts`) is a covered-static
61
- * mutant magnet under Stryker's `coverageAnalysis: perTest` +
62
- * `ignoreStatic: true` (a mutant on module-load code that's still referenced
63
- * by a test is run anyway and falsely reported "Survived") -- see this
64
- * drive's memory for the fully-documented limitation.
60
+ * `generate-env-artifacts.ts`, `generate-usage.ts`) attracts covered-static
61
+ * mutants under Stryker's `coverageAnalysis: perTest` + `ignoreStatic: true`.
62
+ * A mutant on module-load code that a test still references is run anyway
63
+ * and falsely reported "Survived".
65
64
  */
66
65
  export declare function defaultInclude(): string[];
67
66
  /** Default value for {@link GenerateEnvManifestOptions.exclude}. Same reasoning as {@link defaultInclude}. */
@@ -73,12 +72,12 @@ export interface ManifestComputation {
73
72
  readonly blocking: readonly CompatibilityIssue[];
74
73
  }
75
74
  /**
76
- * Pure -- no I/O. Runs compatibility (0005) and exclusive-group (0009,
75
+ * Pure: no I/O. Runs compatibility (0005) and exclusive-group (0009,
77
76
  * always-error, never gated by `onIncompatibility`) checks against an
78
77
  * already-discovered contract graph and applies the `onIncompatibility` gate.
79
78
  * Shared by the standalone `generateEnvManifest()` (which discovers its own
80
79
  * graph) and `generate-env-artifacts.ts` (which discovers once and reuses it across
81
- * manifest/docs/usage) -- see ADR 0011.
80
+ * manifest/docs/usage): see ADR 0011.
82
81
  */
83
82
  export declare function computeManifest(root: string, linkResult: LinkResult, onIncompatibility: "warn" | "throw" | undefined): ManifestComputation;
84
83
  /** Writes the manifest file. Callers must have already confirmed `outputPath` is safe and nothing is blocking. */
@@ -92,7 +91,7 @@ export declare function writeManifest(outputPath: string, activeContracts: reado
92
91
  *
93
92
  * @remarks
94
93
  * Never call this at application startup or import it from
95
- * runtime code -- wire it into an npm script, a bundler plugin, or a CI
94
+ * runtime code: wire it into an npm script, a bundler plugin, or a CI
96
95
  * step instead.
97
96
  *
98
97
  * @throws {EnvManifestGenerationError} If `location` escapes `root`, or if a blocking compatibility/exclusive-group issue is found.
@@ -1 +1 @@
1
- {"version":3,"file":"generate-manifest.d.ts","sourceRoot":"","sources":["../../../src/build/generate-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAG5D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EAChB,MAAM,WAAW,CAAA;AAElB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,iFAAiF;IACjF,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yGAAyG;IACzG,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CACjD;AAED,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACxD,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,4GAA4G;IAC5G,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;CAChD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AACD,8GAA8G;AAC9G,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAczC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,eAAe,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACvD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAChE,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,iBAAiB,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAC9C,mBAAmB,CAwBrB;AAED,kHAAkH;AAClH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAoCpC"}
1
+ {"version":3,"file":"generate-manifest.d.ts","sourceRoot":"","sources":["../../../src/build/generate-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAG5D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EAChB,MAAM,WAAW,CAAA;AAElB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yGAAyG;IACzG,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CACjD;AAED,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACxD,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,4GAA4G;IAC5G,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;CAChD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AACD,8GAA8G;AAC9G,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAczC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,eAAe,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACvD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAChE,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,iBAAiB,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAC9C,mBAAmB,CAwBrB;AAED,kHAAkH;AAClH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAoCpC"}
@@ -8,12 +8,12 @@ import { type RenderUsageReportOptions } from "./usage-report.js";
8
8
  /**
9
9
  * Computes the full usage-scan surface: the local project root, plus (ADR
10
10
  * 0036) each allow-listed `packages` (ADR 0014) name whose schema was
11
- * successfully resolved -- reusing `origins`' already-resolved
12
- * `packageDir` (from `resolveAllowlistedPackages()`, already computed by
13
- * the caller for contract discovery, not re-resolved here) as a bounded
14
- * scan root, walked with the exact same `discoverFiles()` +
15
- * `SCAN_INCLUDE`/`defaultExclude()` policy the local root already uses --
16
- * never a naive, unbounded walk of the package's whole directory. Shared by
11
+ * successfully resolved. Each such package's `packageDir` becomes a bounded
12
+ * scan root. It is reused from `origins` (computed by
13
+ * `resolveAllowlistedPackages()` for contract discovery), not re-resolved
14
+ * here. That root is walked with the same `discoverFiles()` +
15
+ * `SCAN_INCLUDE`/`defaultExclude()` policy as the local root, never as a
16
+ * naive, unbounded walk of the package's whole directory. Shared by
17
17
  * `generateUsageReport()` and `generateEvidenceModel()` so both agree on
18
18
  * exactly the same scanned surface.
19
19
  */
@@ -23,11 +23,11 @@ export declare function computeScanSurface(root: string, exclude: readonly strin
23
23
  }>;
24
24
  /** Options for {@link generateUsageReport}. */
25
25
  export interface GenerateUsageReportOptions {
26
- /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
26
+ /** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
27
27
  fs: BuildFileSystem;
28
28
  /** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
29
29
  root?: string | undefined;
30
- /** Schema-discovery glob, for the contract graph -- self-sufficient like the other two generator functions. */
30
+ /** Schema-discovery glob, for the contract graph: self-sufficient like the other two generator functions. */
31
31
  include?: string[] | undefined;
32
32
  /** Glob patterns to exclude, for both schema discovery and the usage scan. Defaults to node_modules/dist/.git. */
33
33
  exclude?: string[] | undefined;
@@ -45,10 +45,10 @@ export interface GenerateUsageReportOptions {
45
45
  * Public result of {@link generateUsageReport}.
46
46
  *
47
47
  * @remarks
48
- * Composed from the building-block types `usage-report.ts` (the renderer) owns, the same way
49
- * `GenerateDocumentationResult` composes from `docs.ts`'s `CatalogContract` --
50
- * keeps the renderer importable without its orchestrator (see
51
- * `RenderUsageReportOptions`'s own doc comment).
48
+ * Composed from the building-block types `usage-report.ts` (the renderer) owns. That mirrors how
49
+ * `GenerateDocumentationResult` composes from `docs.ts`'s `CatalogContract`. It keeps the
50
+ * renderer importable without its orchestrator (see `RenderUsageReportOptions`'s own doc
51
+ * comment).
52
52
  */
53
53
  export interface GenerateUsageReportResult extends RenderUsageReportOptions {
54
54
  /** Absolute path the report was written to, or `undefined` if `options.report` wasn't passed. */
@@ -61,32 +61,31 @@ export interface UsageComputation {
61
61
  }
62
62
  /**
63
63
  * Builds the dependency graph and maps it into the public, ownership-framed
64
- * result. Never blocks -- see `RenderUsageReportOptions`'s finding fields'
65
- * own doc comments; a team that wants to gate CI on an ownership issue reads
66
- * `Finding[]` (the "ownership" family) from the persisted evidence artifact
67
- * and decides for itself. See ADR 0038.
64
+ * result. Never blocks: see the doc comments on `RenderUsageReportOptions`'s
65
+ * finding fields. A team that wants to gate CI on an ownership issue reads
66
+ * `Finding[]` (the "ownership" family) from the persisted evidence artifact.
67
+ * It then decides for itself. See ADR 0038.
68
68
  *
69
69
  * @remarks
70
70
  * This mapping is the actual API boundary: internal AST vocabulary
71
71
  * ("member accessed", "dynamic") becomes ownership vocabulary ("who owns
72
72
  * it", "who consumes it", "abandoned", "unresolved"). The result is a
73
- * renderer-agnostic domain model -- the same computed data a future JSON or
74
- * SARIF exporter would consume, not something coupled to the Markdown
75
- * renderer.
73
+ * renderer-agnostic domain model. A future JSON or SARIF exporter would
74
+ * consume the same data; it is not coupled to the Markdown renderer.
76
75
  */
77
76
  export declare function computeUsage(root: string, contracts: readonly DiscoveredContract[], scanFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, scannedSurfaces?: readonly ScannedSurface[], dynamicAccessAcknowledgments?: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): Promise<UsageComputation>;
78
77
  /** Writes the Dependency & Ownership Report. Callers must have already confirmed `reportPath` is safe and nothing is blocking. */
79
78
  export declare function writeUsageReport(reportPath: string, computed: Omit<GenerateUsageReportResult, "reportPath">, fs: BuildFileSystem): Promise<void>;
80
79
  /**
81
80
  * Build-time only. Answers who owns each contract, which features depend on
82
- * it, and what the blast radius is if it changes -- the mirror image of
83
- * {@link generateEnvManifest}'s "safer migrations" story: a schema that was never
84
- * wired up, or was abandoned mid-removal, shows up here instead of sitting
85
- * unnoticed.
81
+ * it, and what the blast radius is if it changes. It is the mirror image of
82
+ * {@link generateEnvManifest}'s "safer migrations" story. A schema that was
83
+ * never wired up, or was abandoned mid-removal, shows up here instead of
84
+ * sitting unnoticed.
86
85
  *
87
86
  * @remarks
88
87
  * This is an additional, separate artifact, not a replacement for
89
- * {@link generateDocumentation}'s Catalog -- the two serve different audiences
88
+ * {@link generateDocumentation}'s Catalog: the two serve different audiences
90
89
  * (see ADR 0010).
91
90
  *
92
91
  * @throws {EnvUsageAnalysisError} If `report.location` escapes `root`.
@@ -1 +1 @@
1
- {"version":3,"file":"generate-usage.d.ts","sourceRoot":"","sources":["../../../src/build/generate-usage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAS5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAE3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAClE,OAAO,EAML,KAAK,wBAAwB,EAG9B,MAAM,mBAAmB,CAAA;AAE1B;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,EAC3C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,EAAE,cAAc,EAAE,CAAA;CAAE,CAAC,CAmCrE;AAED,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,iFAAiF;IACjF,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,kHAAkH;IAClH,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC,mIAAmI;IACnI,MAAM,CAAC,EACH;QACE,sDAAsD;QACtD,QAAQ,EAAE,MAAM,CAAA;KACjB,GACD,SAAS,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IACzE,iGAAiG;IACjG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,qIAAqI;IACrI,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,wBAAwB,EAAE,eAAe,CAAC,CAAA;CACjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC/C,OAAO,EAAE,uBAAuB,EAChC,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,EAC3C,4BAA4B,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,GACpF,OAAO,CAAC,gBAAgB,CAAC,CAsI3B;AAED,kIAAkI;AAClI,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,IAAI,CAAC,yBAAyB,EAAE,YAAY,CAAC,EACvD,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAkDpC"}
1
+ {"version":3,"file":"generate-usage.d.ts","sourceRoot":"","sources":["../../../src/build/generate-usage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAS5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAE3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAClE,OAAO,EAML,KAAK,wBAAwB,EAG9B,MAAM,mBAAmB,CAAA;AAE1B;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,EAC3C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,EAAE,cAAc,EAAE,CAAA;CAAE,CAAC,CAmCrE;AAED,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,6GAA6G;IAC7G,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,kHAAkH;IAClH,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC,mIAAmI;IACnI,MAAM,CAAC,EACH;QACE,sDAAsD;QACtD,QAAQ,EAAE,MAAM,CAAA;KACjB,GACD,SAAS,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IACzE,iGAAiG;IACjG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,qIAAqI;IACrI,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,wBAAwB,EAAE,eAAe,CAAC,CAAA;CACjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC/C,OAAO,EAAE,uBAAuB,EAChC,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,EAC3C,4BAA4B,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,GACpF,OAAO,CAAC,gBAAgB,CAAC,CAsI3B;AAED,kIAAkI;AAClI,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,IAAI,CAAC,yBAAyB,EAAE,YAAY,CAAC,EACvD,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAkDpC"}
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Regeneration instruction for a report the CLI does not write (ADR 0046) -- it is produced by the project's own
2
+ * Regeneration instruction for a report the CLI does not write (ADR 0046): it is produced by the project's own
3
3
  * script calling the `@maverickcer/env-cap/build` generators, so naming `npx env-cap` there would send a reader to a command that
4
4
  * cannot regenerate it.
5
5
  * @returns The instruction, as a sentence.
@@ -16,10 +16,10 @@ export declare function generatedBanner(format?: "ts" | "markdown", regenerate?:
16
16
  * Whether `content` carries a {@link generatedBanner}-produced marker, in either format.
17
17
  *
18
18
  * @remarks
19
- * Deliberately not a bare `content.startsWith(generatedBanner(...))`: a shebang, a `"use strict"` pragma, or a
20
- * license header pushes a real banner off line one, and a stricter check would then read a genuinely
21
- * generated file as hand-written, which the dependency scan would take as "a real consumer imports this" and
22
- * so permanently mask an abandoned one. The marker is looked for across the first 20 non-empty lines instead,
19
+ * Deliberately not a bare `content.startsWith(generatedBanner(...))`. A shebang, a `"use strict"` pragma, or a
20
+ * license header pushes a real banner off line one. A stricter check would then read a generated file as
21
+ * hand-written. The dependency scan would take that as "a real consumer imports this" and so permanently mask an
22
+ * abandoned contract. The marker is looked for across the first 20 non-empty lines instead,
23
23
  * which clears every realistic preamble without scanning a whole file.
24
24
  * @param content - A file's text.
25
25
  * @returns `true` when the file is generated.
@@ -1,17 +1,17 @@
1
1
  /**
2
2
  * The declared governance-metadata field set every pipeline-stage contract and
3
- * variable type carries -- `owner` through `metadata`. The field names and types
4
- * are identical at every stage (parse -> link -> contract-model -> docs); only
5
- * the surrounding context differs (a `parse`-stage value is "statically resolved
6
- * from a string literal, or `undefined`"; a `link`/`contract-model`-stage value
7
- * is "from the linked `documentEnv()` call, or `undefined`"). This is the single
3
+ * variable type carries: `owner` through `metadata`. The field names and types
4
+ * are identical at every stage (parse -> link -> contract-model -> docs). Only
5
+ * the surrounding context differs. A `parse`-stage value is "statically resolved
6
+ * from a string literal, or `undefined`". A `link`/`contract-model`-stage value
7
+ * is "from the linked `documentEnv()` call, or `undefined`". This is the single
8
8
  * source of truth for the shape; each stage interface `extends` it.
9
9
  *
10
10
  * `metadata` is the open bag for keys `env-cap` has no named concept for (ADR
11
11
  * 0037); `dataResidency`/`auditRequired`/`legalBasis`/`purpose`/`retention` are
12
12
  * presence-only governance facts, never verified.
13
13
  *
14
- * Internal -- not re-exported from the public `.` barrel.
14
+ * Internal: not re-exported from the public `.` barrel.
15
15
  */
16
16
  export interface EnvGovernanceFields {
17
17
  readonly owner: string | undefined;
@@ -26,7 +26,7 @@ export interface EnvGovernanceFields {
26
26
  }
27
27
  /**
28
28
  * Copies exactly the `EnvGovernanceFields` out of a value that carries
29
- * them -- for projecting one pipeline stage's contract/variable into the next
29
+ * them: for projecting one pipeline stage's contract/variable into the next
30
30
  * (`link` -> `contract-model` -> `docs` catalog, ...) without re-listing all
31
31
  * nine fields at every hop.
32
32
  */
@@ -5,7 +5,7 @@
5
5
  */
6
6
  export declare function humanizeKey(key: string): string;
7
7
  /**
8
- * Formats a `metadata`/`dataResidency` value for display in generated docs/examples -- a string
8
+ * Formats a `metadata`/`dataResidency` value for display in generated docs/examples: a string
9
9
  * renders as-is; anything else (ADR 0035 widened `metadata` to any value) renders as its JSON
10
10
  * text, so an object/array value never prints `[object Object]`. Shared by `docs.ts` and
11
11
  * `env-example.ts`, same rationale as {@link humanizeKey}.
@@ -1 +1 @@
1
- {"version":3,"file":"humanize-key.d.ts","sourceRoot":"","sources":["../../../src/build/humanize-key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ/C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE1D"}
1
+ {"version":3,"file":"humanize-key.d.ts","sourceRoot":"","sources":["../../../src/build/humanize-key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO/C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE1D"}