@maverickcer/env-cap 0.7.3 → 0.7.5

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 (238) hide show
  1. package/ADOPTION.md +106 -124
  2. package/AGENTS.md +14 -13
  3. package/CHANGELOG.md +23 -0
  4. package/CODE_REVIEW.md +69 -173
  5. package/CONTRIBUTING.md +57 -74
  6. package/GUIDE.md +393 -872
  7. package/README.md +82 -77
  8. package/RELEASING.md +17 -15
  9. package/SECURITY.md +76 -227
  10. package/SUPPORT.md +21 -45
  11. package/VERSIONING.md +68 -105
  12. package/benchmarks/READING-BENCHMARKS.md +13 -7
  13. package/benchmarks/WRITING-BENCHMARKS.md +1 -1
  14. package/dist/.dts/_ipc/build-fs.d.ts +9 -14
  15. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  16. package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
  17. package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
  19. package/dist/.dts/_ipc/glob.d.ts +6 -6
  20. package/dist/.dts/_ipc/no-node-fs.d.ts +0 -14
  21. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
  22. package/dist/.dts/build/lifecycle-model.d.ts +8 -3
  23. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  24. package/dist/.dts/build/sarif.d.ts.map +1 -1
  25. package/dist/.dts/helpers/index.d.ts +1 -1
  26. package/dist/.dts/runtime/create.d.ts +3 -0
  27. package/dist/.dts/runtime/create.d.ts.map +1 -1
  28. package/dist/.dts/runtime/document.d.ts +7 -4
  29. package/dist/.dts/runtime/document.d.ts.map +1 -1
  30. package/dist/.dts/runtime/index.d.ts +11 -10
  31. package/dist/.dts/runtime/index.d.ts.map +1 -1
  32. package/dist/.dts/runtime/types.d.ts +16 -0
  33. package/dist/.dts/runtime/types.d.ts.map +1 -1
  34. package/dist/.dts/runtime/validate.d.ts +14 -1
  35. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  36. package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
  37. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
  38. package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
  39. package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
  40. package/dist/.dts7/_ipc/display-path.d.ts +27 -0
  41. package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
  42. package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
  43. package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
  44. package/dist/.dts7/_ipc/glob.d.ts +22 -0
  45. package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
  46. package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
  47. package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
  48. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  49. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  50. package/dist/.dts7/_ipc/typescript.d.ts +20 -0
  51. package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
  52. package/dist/.dts7/build/assemble-project.d.ts +47 -0
  53. package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
  54. package/dist/.dts7/build/change-model.d.ts +63 -0
  55. package/dist/.dts7/build/change-model.d.ts.map +1 -0
  56. package/dist/.dts7/build/check-artifacts.d.ts +48 -0
  57. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
  58. package/dist/.dts7/build/citation-verification.d.ts +62 -0
  59. package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
  60. package/dist/.dts7/build/compatibility.d.ts +83 -0
  61. package/dist/.dts7/build/compatibility.d.ts.map +1 -0
  62. package/dist/.dts7/build/compiler-api.d.ts +12 -0
  63. package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
  64. package/dist/.dts7/build/contract-model.d.ts +93 -0
  65. package/dist/.dts7/build/contract-model.d.ts.map +1 -0
  66. package/dist/.dts7/build/deep-equal.d.ts +9 -0
  67. package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
  68. package/dist/.dts7/build/deep-freeze.d.ts +20 -0
  69. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
  70. package/dist/.dts7/build/dependency-graph.d.ts +170 -0
  71. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
  72. package/dist/.dts7/build/dependency-model.d.ts +81 -0
  73. package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
  74. package/dist/.dts7/build/discover.d.ts +41 -0
  75. package/dist/.dts7/build/discover.d.ts.map +1 -0
  76. package/dist/.dts7/build/display-path.d.ts +6 -0
  77. package/dist/.dts7/build/display-path.d.ts.map +1 -0
  78. package/dist/.dts7/build/docs.d.ts +176 -0
  79. package/dist/.dts7/build/docs.d.ts.map +1 -0
  80. package/dist/.dts7/build/env-example.d.ts +85 -0
  81. package/dist/.dts7/build/env-example.d.ts.map +1 -0
  82. package/dist/.dts7/build/errors.d.ts +78 -0
  83. package/dist/.dts7/build/errors.d.ts.map +1 -0
  84. package/dist/.dts7/build/evidence-cache.d.ts +74 -0
  85. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
  86. package/dist/.dts7/build/evidence-model.d.ts +50 -0
  87. package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
  88. package/dist/.dts7/build/evidence-reference.d.ts +67 -0
  89. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
  90. package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
  91. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
  92. package/dist/.dts7/build/exclusive-group.d.ts +19 -0
  93. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
  94. package/dist/.dts7/build/finding-model.d.ts +80 -0
  95. package/dist/.dts7/build/finding-model.d.ts.map +1 -0
  96. package/dist/.dts7/build/generate-documentation.d.ts +176 -0
  97. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
  98. package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
  99. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
  100. package/dist/.dts7/build/generate-evidence.d.ts +77 -0
  101. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
  102. package/dist/.dts7/build/generate-manifest.d.ts +101 -0
  103. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
  104. package/dist/.dts7/build/generate-usage.d.ts +95 -0
  105. package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
  106. package/dist/.dts7/build/generated-banner.d.ts +43 -0
  107. package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
  108. package/dist/.dts7/build/glob.d.ts +6 -0
  109. package/dist/.dts7/build/glob.d.ts.map +1 -0
  110. package/dist/.dts7/build/governance-fields.d.ts +34 -0
  111. package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
  112. package/dist/.dts7/build/humanize-key.d.ts +14 -0
  113. package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
  114. package/dist/.dts7/build/index.d.ts +105 -0
  115. package/dist/.dts7/build/index.d.ts.map +1 -0
  116. package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
  117. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
  118. package/dist/.dts7/build/link.d.ts +223 -0
  119. package/dist/.dts7/build/link.d.ts.map +1 -0
  120. package/dist/.dts7/build/literal-eval.d.ts +24 -0
  121. package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
  122. package/dist/.dts7/build/live-expirations.d.ts +47 -0
  123. package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
  124. package/dist/.dts7/build/manifest.d.ts +31 -0
  125. package/dist/.dts7/build/manifest.d.ts.map +1 -0
  126. package/dist/.dts7/build/map-utils.d.ts +8 -0
  127. package/dist/.dts7/build/map-utils.d.ts.map +1 -0
  128. package/dist/.dts7/build/merge-documentation.d.ts +35 -0
  129. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
  130. package/dist/.dts7/build/ownership-model.d.ts +59 -0
  131. package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
  132. package/dist/.dts7/build/parse.d.ts +207 -0
  133. package/dist/.dts7/build/parse.d.ts.map +1 -0
  134. package/dist/.dts7/build/reference-projections.d.ts +170 -0
  135. package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
  136. package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
  137. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
  138. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
  139. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
  140. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
  141. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
  142. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
  143. package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
  144. package/dist/.dts7/build/sarif.d.ts +66 -0
  145. package/dist/.dts7/build/sarif.d.ts.map +1 -0
  146. package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
  147. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
  148. package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
  149. package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
  150. package/dist/.dts7/build/source-position.d.ts +69 -0
  151. package/dist/.dts7/build/source-position.d.ts.map +1 -0
  152. package/dist/.dts7/build/tool-version.d.ts +8 -0
  153. package/dist/.dts7/build/tool-version.d.ts.map +1 -0
  154. package/dist/.dts7/build/types.d.ts +7 -0
  155. package/dist/.dts7/build/types.d.ts.map +1 -0
  156. package/dist/.dts7/build/typescript.d.ts +6 -0
  157. package/dist/.dts7/build/typescript.d.ts.map +1 -0
  158. package/dist/.dts7/build/usage-report.d.ts +124 -0
  159. package/dist/.dts7/build/usage-report.d.ts.map +1 -0
  160. package/dist/.dts7/cli/filesystem.d.ts +7 -0
  161. package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
  162. package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
  163. package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
  164. package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
  165. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
  166. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
  167. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
  168. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
  169. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
  170. package/dist/.dts7/evidence/define-projection.d.ts +52 -0
  171. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
  172. package/dist/.dts7/evidence/index.d.ts +23 -0
  173. package/dist/.dts7/evidence/index.d.ts.map +1 -0
  174. package/dist/.dts7/helpers/index.d.ts +135 -0
  175. package/dist/.dts7/helpers/index.d.ts.map +1 -0
  176. package/dist/.dts7/helpers/processors.d.ts +32 -0
  177. package/dist/.dts7/helpers/processors.d.ts.map +1 -0
  178. package/dist/.dts7/helpers/validators.d.ts +68 -0
  179. package/dist/.dts7/helpers/validators.d.ts.map +1 -0
  180. package/dist/.dts7/node/index.d.ts +2 -0
  181. package/dist/.dts7/node/index.d.ts.map +1 -0
  182. package/dist/.dts7/runtime/cache.d.ts +17 -0
  183. package/dist/.dts7/runtime/cache.d.ts.map +1 -0
  184. package/dist/.dts7/runtime/create.d.ts +23 -0
  185. package/dist/.dts7/runtime/create.d.ts.map +1 -0
  186. package/dist/.dts7/runtime/document.d.ts +223 -0
  187. package/dist/.dts7/runtime/document.d.ts.map +1 -0
  188. package/dist/.dts7/runtime/errors.d.ts +55 -0
  189. package/dist/.dts7/runtime/errors.d.ts.map +1 -0
  190. package/dist/.dts7/runtime/index.d.ts +25 -0
  191. package/dist/.dts7/runtime/index.d.ts.map +1 -0
  192. package/dist/.dts7/runtime/registry.d.ts +12 -0
  193. package/dist/.dts7/runtime/registry.d.ts.map +1 -0
  194. package/dist/.dts7/runtime/reset.d.ts +8 -0
  195. package/dist/.dts7/runtime/reset.d.ts.map +1 -0
  196. package/dist/.dts7/runtime/types.d.ts +191 -0
  197. package/dist/.dts7/runtime/types.d.ts.map +1 -0
  198. package/dist/.dts7/runtime/validate.d.ts +27 -0
  199. package/dist/.dts7/runtime/validate.d.ts.map +1 -0
  200. package/dist/{build-LFHPVDQL.js → build-DNAYWD2B.js} +8 -5
  201. package/dist/build-DNAYWD2B.js.map +1 -0
  202. package/dist/build.cjs +7 -4
  203. package/dist/build.cjs.map +1 -1
  204. package/dist/build.js +7 -4
  205. package/dist/build.js.map +1 -1
  206. package/dist/build.ts7.d.cts +1 -0
  207. package/dist/build.ts7.d.ts +1 -0
  208. package/dist/{chunk-ZW3BLAPD.js → chunk-HAGMVMN5.js} +2 -2
  209. package/dist/cli/index.js +3 -3
  210. package/dist/eslint-plugin/index.cjs +8 -5
  211. package/dist/eslint-plugin/index.cjs.map +1 -1
  212. package/dist/eslint-plugin/index.js +8 -5
  213. package/dist/eslint-plugin/index.js.map +1 -1
  214. package/dist/eslint-plugin/index.ts7.d.cts +1 -0
  215. package/dist/eslint-plugin/index.ts7.d.ts +1 -0
  216. package/dist/evidence.ts7.d.cts +1 -0
  217. package/dist/evidence.ts7.d.ts +1 -0
  218. package/dist/helpers.ts7.d.cts +1 -0
  219. package/dist/helpers.ts7.d.ts +1 -0
  220. package/dist/index.cjs.map +1 -1
  221. package/dist/index.js.map +1 -1
  222. package/dist/index.ts7.d.cts +1 -0
  223. package/dist/index.ts7.d.ts +1 -0
  224. package/dist/node.ts7.d.cts +1 -0
  225. package/dist/node.ts7.d.ts +1 -0
  226. package/examples/README.md +46 -80
  227. package/package.json +37 -6
  228. package/schemas/env-cap-report.schema.json +1 -1
  229. package/skills/env-cap/SKILL.md +1 -1
  230. package/skills/env-cap/references/api.md +1 -1
  231. package/specs/architecture.md +2 -2
  232. package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
  233. package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
  234. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
  235. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
  236. package/specs/generated-artifacts.md +14 -2
  237. package/dist/build-LFHPVDQL.js.map +0 -1
  238. /package/dist/{chunk-ZW3BLAPD.js.map → chunk-HAGMVMN5.js.map} +0 -0
@@ -0,0 +1,191 @@
1
+ import type { CompatibilityIssue } from "./compatibility.js";
2
+ import type { EvidenceModel } from "./evidence-model.js";
3
+ import type { Finding, FindingFamily } from "./finding-model.js";
4
+ import type { DocumentationComputation, GenerateDocumentationOptions, GenerateDocumentationResult } from "./generate-documentation.js";
5
+ import type { GenerateEnvManifestOptions, GenerateEnvManifestResult, ManifestComputation } from "./generate-manifest.js";
6
+ import type { GenerateUsageReportOptions, GenerateUsageReportResult, UsageComputation } from "./generate-usage.js";
7
+ import type { DiscoveredContract } from "./link.js";
8
+ import type { LiveExpirationDates } from "./live-expirations.js";
9
+ import type { ParseWarning } from "./parse.js";
10
+ import type { BuildFileSystem } from "./types.js";
11
+ /** Options for {@link generateEnvArtifacts}. */
12
+ export interface GenerateEnvArtifactsOptions {
13
+ /** The filesystem capability, shared across every requested pass -- `./build` never imports `node:fs` (ADR 0040). */
14
+ fs: BuildFileSystem;
15
+ /** Directory glob patterns are resolved against, shared across every requested pass. Defaults to `process.cwd()`. */
16
+ root?: string | undefined;
17
+ /** Shared schema-discovery glob for the contract graph. Defaults to `["**\/env.schema.ts"]`. */
18
+ include?: string[] | undefined;
19
+ /** Glob patterns to exclude, shared across every requested pass. Defaults to node_modules/dist/.git. */
20
+ exclude?: string[] | undefined;
21
+ /** See `GenerateEnvManifestOptions.packages`; shared across every requested pass. See ADR 0014. */
22
+ packages?: readonly string[] | undefined;
23
+ /** See `GenerateEnvManifestOptions.tsconfig`; shared across every requested pass. See ADR 0023. */
24
+ tsconfig?: string | false | undefined;
25
+ /** Manifest pass options, or `false` to skip it entirely. */
26
+ manifest?: Omit<GenerateEnvManifestOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig"> | false | undefined;
27
+ /** Docs pass options, or `false` to skip it entirely. */
28
+ docs?: Omit<GenerateDocumentationOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig" | "liveExpirationDates"> | false | undefined;
29
+ /** Usage-report pass options, or `false` to skip it entirely. */
30
+ usage?: Omit<GenerateUsageReportOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig"> | false | undefined;
31
+ /**
32
+ * Where to write the persisted evidence artifact (the full, literal
33
+ * `EvidenceModel`, plus a paired `.fingerprint` sidecar -- see
34
+ * `evidence-cache.ts`), e.g. `docs/env.evidence.json`, relative to `root`.
35
+ * Independent of `manifest.location` -- requesting this needs no other
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.
41
+ */
42
+ evidence?: {
43
+ location: string;
44
+ } | false | undefined;
45
+ /**
46
+ * Escalates every warning-severity `"documentation"`-family finding
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.
51
+ *
52
+ * @remarks
53
+ * Scoped deliberately narrowly, unlike `manifest.onIncompatibility`, which
54
+ * gates only the compatibility family. `"info"`-severity findings are never
55
+ * escalated by either -- see `Finding.severity`.
56
+ */
57
+ onUndocumented?: "warn" | "throw" | undefined;
58
+ /**
59
+ * Escalates every warning-severity `"ownership"`-family finding (abandoned
60
+ * contracts, unresolved consumers, unconsumed owned variables,
61
+ * indeterminate ownership, stale/missing `dynamicAccess` citations) into a
62
+ * blocking error. Defaults to `"warn"` -- see {@link onUndocumented}.
63
+ */
64
+ onOwnershipIssue?: "warn" | "throw" | undefined;
65
+ /**
66
+ * Supplies expiration metadata from a live source (a secrets manager, an
67
+ * internal inventory API, ...) as a post-discovery override applied only to
68
+ * the docs pass. Invoked at most once, only when a `docs` pass is actually
69
+ * requested, with every discovered variable name across all passes' shared
70
+ * contract graph. See `live-expirations.ts` and ADR 0012. Omitted: behavior
71
+ * is unchanged from a purely static `expiresAt`.
72
+ */
73
+ liveExpirationDates?: LiveExpirationDates | undefined;
74
+ }
75
+ /** The result of a completed {@link generateEnvArtifacts} run. */
76
+ export interface GenerateEnvArtifactsResult {
77
+ /** Set only when `options.manifest` wasn't `false`. */
78
+ readonly manifest: GenerateEnvManifestResult | undefined;
79
+ /** Set only when `options.docs` wasn't `false`. */
80
+ readonly docs: GenerateDocumentationResult | undefined;
81
+ /** Set only when `options.usage` wasn't `false`. */
82
+ readonly usage: GenerateUsageReportResult | undefined;
83
+ /** Always populated, regardless of `options.evidence` -- see that option's own doc comment. */
84
+ readonly evidence: EvidenceModel;
85
+ }
86
+ /**
87
+ * Every intermediate value both the write path (`generateEnvArtifacts()`
88
+ * below) and the drift-check path (`checkEnvArtifacts()` in
89
+ * `check-artifacts.ts`) need, computed exactly once. Internal/Private tier
90
+ * per `VERSIONING.md` -- not re-exported from `./index.ts`.
91
+ */
92
+ export interface ComputeArtifactsResult {
93
+ readonly root: string;
94
+ /** Set only when a manifest pass was requested. */
95
+ readonly manifest: {
96
+ readonly options: Omit<GenerateEnvManifestOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig">;
97
+ readonly outputPath: string;
98
+ readonly computed: ManifestComputation;
99
+ } | undefined;
100
+ /** Set only when a docs pass was requested; `envExamplePath` only when it also asked for an example file. */
101
+ readonly docs: {
102
+ readonly options: Omit<GenerateDocumentationOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig" | "liveExpirationDates">;
103
+ readonly path: string;
104
+ readonly envExamplePath: string | undefined;
105
+ } | undefined;
106
+ /** Always computed -- Finding Model needs it regardless of whether a `docs` pass was itself requested. See ADR 0038. */
107
+ readonly docsComputed: DocumentationComputation;
108
+ readonly docsContracts: readonly DiscoveredContract[];
109
+ /** Set only when a usage pass was requested; `reportPath` only when it also asked for a report file. */
110
+ readonly usage: {
111
+ readonly options: Omit<GenerateUsageReportOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig">;
112
+ readonly reportPath: string | undefined;
113
+ } | undefined;
114
+ /** Always computed -- Finding Model needs it regardless of whether a `usage` pass was itself requested. See ADR 0038. */
115
+ readonly usageComputed: UsageComputation;
116
+ readonly evidencePath: string | undefined;
117
+ readonly evidence: EvidenceModel;
118
+ readonly blocking: readonly CompatibilityIssue[];
119
+ readonly packageWarnings: readonly ParseWarning[];
120
+ readonly linkWarnings: readonly ParseWarning[];
121
+ /** Single timestamp shared by every pass' own time-sensitive computation (`expiringSoon`, `EvidenceModel.provenance.generatedAt`), so all of them agree on exactly the same instant. */
122
+ readonly generatedAt: Date;
123
+ }
124
+ /**
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.
129
+ *
130
+ * @remarks
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,
137
+ * and a `FindingCode` from another family is not a member of it.
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). */
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. */
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. */
146
+ export declare function findingFiles(finding: Finding): string[];
147
+ /**
148
+ * A pass's options, or `undefined` when the pass is not requested: `false` skips a pass entirely,
149
+ * exactly as omitting it does.
150
+ * @internal Exported for direct unit coverage.
151
+ */
152
+ export declare function requestedPass<T extends object>(option: T | false | undefined): T | undefined;
153
+ /**
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.
161
+ *
162
+ * @remarks
163
+ * The six canonical fact models (Contract/Dependency/Ownership/Lifecycle/
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.
167
+ */
168
+ export declare function computeArtifacts(options: GenerateEnvArtifactsOptions): Promise<ComputeArtifactsResult>;
169
+ /**
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).
175
+ *
176
+ * @remarks
177
+ * Two distinct atomicity guarantees, not one:
178
+ * - **Compute atomicity (guaranteed)**: every requested pass's blocking
179
+ * findings are checked, across all passes, before any pass writes
180
+ * anything.
181
+ * - **Write atomicity (NOT guaranteed, and not attempted)**: once writes
182
+ * begin, each `fs.writeFile` is independent. A real I/O failure partway
183
+ * through (disk full, permissions changed mid-run) can leave some
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.
187
+ *
188
+ * @throws {EnvProjectGenerationError} If any requested output location escapes `root`, or if any requested pass reports a blocking finding.
189
+ */
190
+ export declare function generateEnvArtifacts(options: GenerateEnvArtifactsOptions): Promise<GenerateEnvArtifactsResult>;
191
+ //# sourceMappingURL=generate-env-artifacts.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"generate-env-artifacts.d.ts","sourceRoot":"","sources":["../../../src/build/generate-env-artifacts.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,77 @@
1
+ import type { EvidenceModel } from "./evidence-model.js";
2
+ import type { LiveExpirationDates } from "./live-expirations.js";
3
+ import type { BuildFileSystem } from "./types.js";
4
+ /** Options for {@link generateEvidenceModel}. */
5
+ export interface GenerateEvidenceModelOptions {
6
+ /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
7
+ fs: BuildFileSystem;
8
+ /** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
9
+ root?: string | undefined;
10
+ /** Schema-discovery glob for the contract graph. Defaults to `["**\/env.schema.ts"]`. */
11
+ include?: string[] | undefined;
12
+ /** Glob patterns to exclude, shared across every pass. Defaults to node_modules/dist/.git. */
13
+ exclude?: string[] | undefined;
14
+ /** See `GenerateEnvManifestOptions.packages`. See ADR 0014. */
15
+ packages?: readonly string[] | undefined;
16
+ /** See `GenerateEnvManifestOptions.tsconfig`. See ADR 0023. */
17
+ tsconfig?: string | false | undefined;
18
+ /**
19
+ * Where a previously-persisted evidence artifact lives, relative to
20
+ * `root` -- read (never written) as the baseline Change Model diffs
21
+ * against and dynamic-access citation freshness (ADR 0037) compares
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
24
+ * location. Omitted: treated as the normal first-run state (everything
25
+ * reads as added, no citation-freshness baseline to compare against),
26
+ * never an error.
27
+ */
28
+ previousSnapshotLocation?: string | undefined;
29
+ /** Feeds Lifecycle Model's `expiring` list. Defaults to 30. */
30
+ expiringWithinDays?: number | undefined;
31
+ /**
32
+ * Supplies expiration metadata from a live source as a post-discovery
33
+ * override, applied to Lifecycle Model's (and Finding Model's
34
+ * `expiring-soon` findings') data only -- Contract Model still reflects the
35
+ * schema's own static `expiresAt`. See `live-expirations.ts` and ADR 0012.
36
+ */
37
+ liveExpirationDates?: LiveExpirationDates | undefined;
38
+ /**
39
+ * Resolves the commit SHA to stamp onto `EvidenceModel.provenance.commit`.
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:
42
+ * `commit` is `undefined`.
43
+ */
44
+ commit?: (() => Promise<string | undefined>) | undefined;
45
+ }
46
+ /**
47
+ * Node-only assembly orchestrator (ADR 0024, ADR 0031): runs schema
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
52
+ * discovery/linking every builder needs. The result is `deepFreeze()`-d
53
+ * before being returned.
54
+ *
55
+ * @remarks
56
+ * Deliberately never throws on a data-quality finding (a compatibility
57
+ * issue, an undocumented variable, an abandoned contract, ...) -- every one
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 --
65
+ * `previousSnapshotLocation` escaping `root`.
66
+ *
67
+ * The dependency-graph scan underlying Dependency Model (via
68
+ * `buildDependencyModel()`) and the one underlying Finding Model's
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,
73
+ * dev/CI-time-only work (never a runtime hot path), so the redundant I/O is
74
+ * an honest tradeoff, not an oversight.
75
+ */
76
+ export declare function generateEvidenceModel(options: GenerateEvidenceModelOptions): Promise<EvidenceModel>;
77
+ //# sourceMappingURL=generate-evidence.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,101 @@
1
+ import type { BuildFileSystem } from "./types.js";
2
+ import type { CompatibilityIssue } from "./compatibility.js";
3
+ import { type DiscoveredContract, type DiscoveredContractSummary, type LinkResult } from "./link.js";
4
+ import type { ParseWarning } from "./parse.js";
5
+ /** Options for {@link generateEnvManifest}. */
6
+ export interface GenerateEnvManifestOptions {
7
+ /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
8
+ fs: BuildFileSystem;
9
+ /** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
10
+ root?: string | undefined;
11
+ /** Output path for the generated manifest, relative to `root` (e.g. "src/generated/env.manifest.ts"). */
12
+ location: string;
13
+ /** Glob patterns for schema files. Defaults to `["**\/env.schema.ts"]`. */
14
+ include?: string[] | undefined;
15
+ /** Glob patterns to exclude. Defaults to node_modules/dist/.git. */
16
+ exclude?: string[] | undefined;
17
+ /**
18
+ * Explicit allowlist of installed
19
+ * package names whose declared `"envCap": { "schema": "<path>" }` entry
20
+ * point should also be discovered, so a contract that ships as its own
21
+ * separately-published package (no monorepo required) can be included in
22
+ * the manifest. Opt-in only: a package is never considered unless its
23
+ * exact name appears here. See ADR 0014.
24
+ */
25
+ packages?: readonly string[] | undefined;
26
+ /**
27
+ * Path to a tsconfig.json (relative to `root`)
28
+ * whose `compilerOptions.paths`/`baseUrl` resolve aliased import specifiers (e.g.
29
+ * `"@/lib/env.schema.js"`) encountered during static analysis, so a contract or consumer
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
32
+ * `packages`) this never crosses a trust/versioning boundary: every resolved file is
33
+ * already local, already-trusted project source. Pass `false` to disable entirely. See
34
+ * ADR 0023.
35
+ */
36
+ tsconfig?: string | false | undefined;
37
+ /**
38
+ * "warn" (default): only provable incompatibilities (conflicting explicit processor
39
+ * return type annotations) block generation; everything else is reported as a warning.
40
+ * "throw": warnings are escalated to hard errors too, for stricter CI gates.
41
+ */
42
+ onIncompatibility?: "warn" | "throw" | undefined;
43
+ }
44
+ /** The result of a completed {@link generateEnvManifest} run. */
45
+ export interface GenerateEnvManifestResult {
46
+ /** Absolute path the manifest file was written to. */
47
+ readonly outputPath: string;
48
+ /** Root-relative summary of every discovered contract, active or not. */
49
+ readonly contracts: readonly DiscoveredContractSummary[];
50
+ /** Non-blocking compatibility/exclusive-group issues (severity `"warning"`). */
51
+ readonly warnings: readonly CompatibilityIssue[];
52
+ /** Parse-time warnings collected across every analyzed file (including allow-listed package resolution). */
53
+ readonly parseWarnings: readonly ParseWarning[];
54
+ }
55
+ /**
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`,
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.
65
+ */
66
+ export declare function defaultInclude(): string[];
67
+ /** Default value for {@link GenerateEnvManifestOptions.exclude}. Same reasoning as {@link defaultInclude}. */
68
+ export declare function defaultExclude(): string[];
69
+ export interface ManifestComputation {
70
+ readonly activeContracts: readonly DiscoveredContract[];
71
+ readonly contractSummaries: readonly DiscoveredContractSummary[];
72
+ readonly warnings: readonly CompatibilityIssue[];
73
+ readonly blocking: readonly CompatibilityIssue[];
74
+ }
75
+ /**
76
+ * Pure -- no I/O. Runs compatibility (0005) and exclusive-group (0009,
77
+ * always-error, never gated by `onIncompatibility`) checks against an
78
+ * already-discovered contract graph and applies the `onIncompatibility` gate.
79
+ * Shared by the standalone `generateEnvManifest()` (which discovers its own
80
+ * graph) and `generate-env-artifacts.ts` (which discovers once and reuses it across
81
+ * manifest/docs/usage) -- see ADR 0011.
82
+ */
83
+ export declare function computeManifest(root: string, linkResult: LinkResult, onIncompatibility: "warn" | "throw" | undefined): ManifestComputation;
84
+ /** Writes the manifest file. Callers must have already confirmed `outputPath` is safe and nothing is blocking. */
85
+ export declare function writeManifest(outputPath: string, activeContracts: readonly DiscoveredContract[], fs: BuildFileSystem): Promise<void>;
86
+ /**
87
+ * Build-time only. Discovers `env.schema.ts` files, statically analyzes them
88
+ * (never executes them) to link `createEnv()`/`documentEnv()` calls, checks
89
+ * for provable incompatibilities between duplicate variable declarations,
90
+ * and writes a deterministic manifest file that re-exports every discovered
91
+ * active contract.
92
+ *
93
+ * @remarks
94
+ * 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
96
+ * step instead.
97
+ *
98
+ * @throws {EnvManifestGenerationError} If `location` escapes `root`, or if a blocking compatibility/exclusive-group issue is found.
99
+ */
100
+ export declare function generateEnvManifest(options: GenerateEnvManifestOptions): Promise<GenerateEnvManifestResult>;
101
+ //# sourceMappingURL=generate-manifest.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,95 @@
1
+ import type { BuildFileSystem } from "./types.js";
2
+ import type { DependencyGraph, ScannedSurface } from "./dependency-graph.js";
3
+ import type { DiscoveredContract } from "./link.js";
4
+ import type { ImportResolutionContext } from "./resolution/resolve-import.js";
5
+ import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
6
+ import type { DynamicAccessAssertion } from "./source-position.js";
7
+ import { type RenderUsageReportOptions } from "./usage-report.js";
8
+ /**
9
+ * Computes the full usage-scan surface: the local project root, plus (ADR
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
17
+ * `generateUsageReport()` and `generateEvidenceModel()` so both agree on
18
+ * exactly the same scanned surface.
19
+ */
20
+ export declare function computeScanSurface(root: string, exclude: readonly string[], origins: ReadonlyMap<string, PackageOrigin>, fs: BuildFileSystem): Promise<{
21
+ scanFiles: string[];
22
+ scannedSurfaces: ScannedSurface[];
23
+ }>;
24
+ /** Options for {@link generateUsageReport}. */
25
+ export interface GenerateUsageReportOptions {
26
+ /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
27
+ fs: BuildFileSystem;
28
+ /** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
29
+ root?: string | undefined;
30
+ /** Schema-discovery glob, for the contract graph -- self-sufficient like the other two generator functions. */
31
+ include?: string[] | undefined;
32
+ /** Glob patterns to exclude, for both schema discovery and the usage scan. Defaults to node_modules/dist/.git. */
33
+ exclude?: string[] | undefined;
34
+ /** See `GenerateEnvManifestOptions.packages`; see ADR 0014. */
35
+ packages?: readonly string[] | undefined;
36
+ /** See `GenerateEnvManifestOptions.tsconfig`; see ADR 0023. */
37
+ tsconfig?: string | false | undefined;
38
+ /** Also write the rendered Markdown report to this path, relative to `root`. Omitted: the report is only returned, not written. */
39
+ report?: {
40
+ /** Output path for the report, relative to `root`. */
41
+ location: string;
42
+ } | undefined;
43
+ }
44
+ /**
45
+ * Public result of {@link generateUsageReport}.
46
+ *
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).
52
+ */
53
+ export interface GenerateUsageReportResult extends RenderUsageReportOptions {
54
+ /** Absolute path the report was written to, or `undefined` if `options.report` wasn't passed. */
55
+ readonly reportPath: string | undefined;
56
+ }
57
+ export interface UsageComputation {
58
+ readonly graph: DependencyGraph;
59
+ /** Everything the report renders except `parseWarnings`, which the caller owns (it comes from discovery, not from this analysis). */
60
+ readonly result: Omit<RenderUsageReportOptions, "parseWarnings">;
61
+ }
62
+ /**
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.
68
+ *
69
+ * @remarks
70
+ * This mapping is the actual API boundary: internal AST vocabulary
71
+ * ("member accessed", "dynamic") becomes ownership vocabulary ("who owns
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.
76
+ */
77
+ 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
+ /** Writes the Dependency & Ownership Report. Callers must have already confirmed `reportPath` is safe and nothing is blocking. */
79
+ export declare function writeUsageReport(reportPath: string, computed: Omit<GenerateUsageReportResult, "reportPath">, fs: BuildFileSystem): Promise<void>;
80
+ /**
81
+ * 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.
86
+ *
87
+ * @remarks
88
+ * This is an additional, separate artifact, not a replacement for
89
+ * {@link generateDocumentation}'s Catalog -- the two serve different audiences
90
+ * (see ADR 0010).
91
+ *
92
+ * @throws {EnvUsageAnalysisError} If `report.location` escapes `root`.
93
+ */
94
+ export declare function generateUsageReport(options: GenerateUsageReportOptions): Promise<GenerateUsageReportResult>;
95
+ //# sourceMappingURL=generate-usage.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Regeneration instruction for a report the CLI does not write (ADR 0046) -- it is produced by the project's own
3
+ * script calling the `@maverickcer/env-cap/build` generators, so naming `npx env-cap` there would send a reader to a command that
4
+ * cannot regenerate it.
5
+ * @returns The instruction, as a sentence.
6
+ */
7
+ export declare function reportRegenerateHint(): string;
8
+ /**
9
+ * Renders the "do not edit by hand" marker in the given comment syntax.
10
+ * @param format - Comment syntax to render in.
11
+ * @param regenerate - How to regenerate; defaults to the CLI, which writes the manifest.
12
+ * @returns The comment line.
13
+ */
14
+ export declare function generatedBanner(format?: "ts" | "markdown", regenerate?: string): string;
15
+ /**
16
+ * Whether `content` carries a {@link generatedBanner}-produced marker, in either format.
17
+ *
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,
23
+ * which clears every realistic preamble without scanning a whole file.
24
+ * @param content - A file's text.
25
+ * @returns `true` when the file is generated.
26
+ */
27
+ export declare function isGeneratedFile(content: string): boolean;
28
+ /**
29
+ * Short disclaimer stamped into every artifact that renders sensitivity, ownership or expiry claims. Never omit
30
+ * it from an artifact that renders such metadata: it is what keeps "documented" from being misread as
31
+ * "verified" or "compliant". Every fact in those artifacts is either a statically-provable code fact or an
32
+ * author's own declaration; env-cap never validates a declaration against reality.
33
+ * @returns The disclaimer.
34
+ */
35
+ export declare function evidenceDisclaimer(): string;
36
+ /**
37
+ * States, by concept, that an artifact is a projection of env-cap's Evidence Model, and by path when one is known.
38
+ * It never hardcodes a path, because the evidence file only exists on a run that passed `--evidence`.
39
+ * @param evidencePath - The path the evidence was also written to, when this run wrote it.
40
+ * @returns The note.
41
+ */
42
+ export declare function evidenceProjectionNote(evidencePath?: string): string;
43
+ //# sourceMappingURL=generated-banner.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"generated-banner.d.ts","sourceRoot":"","sources":["../../../src/build/generated-banner.ts"],"names":[],"mappings":"AAwBA;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpE"}
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Glob-to-RegExp conversion for discovery. The behavior lives in `../_ipc/glob.ts`, a managed copy of
3
+ * internal-package-contract's `runtime/glob.ts`. Not re-exported from `./index.js`: Private tier per `VERSIONING.md`.
4
+ */
5
+ export { globToRegExp } from "../_ipc/glob.js";
6
+ //# sourceMappingURL=glob.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../../src/build/glob.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA"}
@@ -0,0 +1,34 @@
1
+ /**
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
8
+ * source of truth for the shape; each stage interface `extends` it.
9
+ *
10
+ * `metadata` is the open bag for keys `env-cap` has no named concept for (ADR
11
+ * 0037); `dataResidency`/`auditRequired`/`legalBasis`/`purpose`/`retention` are
12
+ * presence-only governance facts, never verified.
13
+ *
14
+ * Internal -- not re-exported from the public `.` barrel.
15
+ */
16
+ export interface EnvGovernanceFields {
17
+ readonly owner: string | undefined;
18
+ readonly sensitivity: string | undefined;
19
+ readonly expiresAt: string | undefined;
20
+ readonly purpose: string | undefined;
21
+ readonly legalBasis: string | undefined;
22
+ readonly retention: string | undefined;
23
+ readonly dataResidency: string | readonly string[] | undefined;
24
+ readonly auditRequired: boolean | undefined;
25
+ readonly metadata: Readonly<Record<string, unknown>> | undefined;
26
+ }
27
+ /**
28
+ * Copies exactly the `EnvGovernanceFields` out of a value that carries
29
+ * them -- for projecting one pipeline stage's contract/variable into the next
30
+ * (`link` -> `contract-model` -> `docs` catalog, ...) without re-listing all
31
+ * nine fields at every hop.
32
+ */
33
+ export declare function governanceFieldsOf(source: EnvGovernanceFields): EnvGovernanceFields;
34
+ //# sourceMappingURL=governance-fields.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"governance-fields.d.ts","sourceRoot":"","sources":["../../../src/build/governance-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9D,QAAQ,CAAC,aAAa,EAAE,OAAO,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAA;CACjE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAYnF"}
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Formats a metadata key for display in generated docs/examples:
3
+ * "lastRotation" -> "Last Rotation". Shared by `docs.ts` and `env-example.ts`
4
+ * so both generated artifacts label metadata the same way.
5
+ */
6
+ export declare function humanizeKey(key: string): string;
7
+ /**
8
+ * Formats a `metadata`/`dataResidency` value for display in generated docs/examples -- a string
9
+ * renders as-is; anything else (ADR 0035 widened `metadata` to any value) renders as its JSON
10
+ * text, so an object/array value never prints `[object Object]`. Shared by `docs.ts` and
11
+ * `env-example.ts`, same rationale as {@link humanizeKey}.
12
+ */
13
+ export declare function renderMetadataValue(value: unknown): string;
14
+ //# sourceMappingURL=humanize-key.d.ts.map
@@ -0,0 +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"}