@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,31 @@
1
+ import type { DiscoveredContract } from "./link.js";
2
+ /**
3
+ * Every validation context declared by any variable in an *active* contract
4
+ * in `contracts` (a variable belonging to a contract documented `active:
5
+ * false` never contributes -- same exclusion the `manifest` array itself
6
+ * already applies), sorted and deduplicated. What {@link renderManifest}
7
+ * surfaces as the generated `activeContexts` export. Exported for reuse by
8
+ * anything that needs the same computation (currently just `renderManifest`
9
+ * itself).
10
+ */
11
+ export declare function discoverValidationContexts(contracts: readonly DiscoveredContract[]): readonly string[];
12
+ /**
13
+ * Renders the deterministic manifest source: sorted imports (aliased on name
14
+ * collision) plus a `contracts` array, in the exact banner format schema
15
+ * authors will recognize as generated. No timestamps, no randomness -- same
16
+ * input files always produce byte-identical output.
17
+ *
18
+ * @remarks
19
+ * When at least one discovered variable declares a `context` (ADR 0022),
20
+ * this also emits `activeContexts` -- every validation context found across
21
+ * `contracts`, as a plain array named to match {@link runtime.validateEnvOptions}'s
22
+ * own `activeContexts` field -- so application code can import it alongside
23
+ * `manifest` and pass it straight through: `validateEnv({ manifest, values, activeContexts })`.
24
+ * It's every context this manifest has, meant as a starting point to narrow
25
+ * per process/deployment, not a pre-scoped default -- see the README's
26
+ * "Validation contexts" section. Omitted entirely (not even an empty array)
27
+ * when no variable declares a `context` at all, so generated output for
28
+ * projects that don't use this feature is untouched.
29
+ */
30
+ export declare function renderManifest(contracts: readonly DiscoveredContract[], outputFile: string): string;
31
+ //# sourceMappingURL=manifest.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/build/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,SAAS,MAAM,EAAE,CASnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,UAAU,EAAE,MAAM,GACjB,MAAM,CAiER"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * `map.get(key)` after iterating `map`'s own `.keys()` is always defined --
3
+ * this makes that invariant an explicit, named operation instead of a bare
4
+ * `!` non-null assertion at each call site, with a real error (not a
5
+ * silent `undefined`) if it's ever violated by a future bug.
6
+ */
7
+ export declare function mustGet<K, V>(map: ReadonlyMap<K, V>, key: K): V;
8
+ //# sourceMappingURL=map-utils.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"map-utils.d.ts","sourceRoot":"","sources":["../../../src/build/map-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAK/D"}
@@ -0,0 +1,35 @@
1
+ import type { DiscoveredContract, DiscoveredVariable } from "./link.js";
2
+ /**
3
+ * Every documentation field of a variable that a second declaration of it can supply. `metadata` is merged key by
4
+ * key rather than as one value, so it is handled on its own below. `evidence` is not one of them: its citations
5
+ * point at the declaring contract's own code and are re-verified there every run (ADR 0037), so they stay with the
6
+ * contract that wrote them and are never copied to, or compared with, another declaration.
7
+ */
8
+ export declare const VALUE_FIELDS: readonly ["description", "owner", "sensitivity", "expiresAt", "refreshInstructions", "authenticatorType", "rotationPeriod", "lastRotatedAt", "rotationTriggerEvents", "setupInstructions", "required", "deprecated", "deprecatedReason", "removeBy", "renamedFrom", "purpose", "legalBasis", "retention", "dataResidency", "auditRequired"];
9
+ /**
10
+ * Fills what one declaration of a variable leaves unset from the other declarations of the same variable.
11
+ *
12
+ * @remarks
13
+ * A variable can be declared in more than one contract: a package that ships its own contract (see
14
+ * {@link ../README} "Reusable packages") and the application that consumes it both name the same environment
15
+ * variable, because the process has one flat namespace. Writing the explanation twice is how the two drift, so the
16
+ * declaration that carries it can be the one place it is written, and the other adds only what is its own (the
17
+ * application's own `expiresAt`, say).
18
+ *
19
+ * Every field a declaration leaves unset is taken from another declaration that sets it, as long as one of the two
20
+ * is a package's contract; when several do, the one from a package's contract wins over the application's own, the
21
+ * first package's over a later one's, and the application's own fill a gap only when all of them that set it agree. Two of the application's own contracts never fill each
22
+ * other: they are siblings, often alternatives, and each documents the variable for itself. A field a declaration sets itself is never replaced, so two declarations that set the same field
23
+ * differently still differ afterwards, and the compatibility check can say so. `metadata` is merged key by key under
24
+ * the same rule. Pure: the contracts passed in are not changed.
25
+ */
26
+ export declare function mergeSharedDocumentation(contracts: readonly DiscoveredContract[]): readonly DiscoveredContract[];
27
+ /**
28
+ * The fields (and `metadata.<key>`s) {@link mergeSharedDocumentation} filled into `variable` from another declaration
29
+ * of it. The compatibility check skips them: a value a declaration was given is not one it wrote, so it cannot
30
+ * disagree with anyone.
31
+ * @param variable - a variable as the merge returned it; any other has been given nothing.
32
+ * @returns the given field names.
33
+ */
34
+ export declare function donatedTo(variable: DiscoveredVariable): ReadonlySet<string>;
35
+ //# sourceMappingURL=merge-documentation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"merge-documentation.d.ts","sourceRoot":"","sources":["../../../src/build/merge-documentation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEvE;;;;;GAKG;AACH,eAAO,MAAM,YAAY,6UAqBiC,CAAA;AAQ1D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,SAAS,kBAAkB,EAAE,CA6B/B;AA8DD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,kBAAkB,GAAG,WAAW,CAAC,MAAM,CAAC,CAE3E"}
@@ -0,0 +1,59 @@
1
+ import type { ContractRef } from "./evidence-reference.js";
2
+ import type { DiscoveredContract } from "./link.js";
3
+ /**
4
+ * The third of env-cap's seven canonical fact models (ADR 0024) -- every
5
+ * contract and variable's effective owner, plus first-class
6
+ * `unownedContracts`/`unownedVariables` arrays. See ADR 0028.
7
+ *
8
+ * @remarks
9
+ * "Unowned" previously existed only as a count (`noOwnerCount`) inside
10
+ * `docs.ts`'s `renderSecurityReview()` -- itemized here as real data for the
11
+ * first time, computed via the same `effectiveOwner()` (variable overrides
12
+ * contract) that ADR 0028 also fixed `usage-report.ts`'s ownership findings
13
+ * to use, so this model can never disagree with either of them about who
14
+ * owns a variable.
15
+ */
16
+ /** Bump only when a reader could misinterpret the new shape -- same discipline every other canonical model's `schemaVersion` follows. */
17
+ export declare const OWNERSHIP_MODEL_SCHEMA_VERSION = 1;
18
+ /**
19
+ * One variable's effective owner (its own, falling back to the contract's).
20
+ *
21
+ * @see {@link ContractModelVariable} -- this same declared variable's canonical starting point.
22
+ */
23
+ export interface OwnershipModelVariable {
24
+ readonly key: string;
25
+ /** The variable's own `owner`, falling back to the contract's -- see `effectiveOwner()`. */
26
+ readonly owner: string | undefined;
27
+ }
28
+ /** One contract's own default owner plus every variable's effective owner. See {@link OwnershipModelVariable} for the per-variable shape. */
29
+ export interface OwnershipModelContract {
30
+ /** Root-relative, POSIX-separated -- matches `ContractModelContract.file`. */
31
+ readonly file: string;
32
+ readonly exportName: string;
33
+ readonly contractName: string;
34
+ /** The contract's own default owner -- not "effective" the way a variable's is, since there's no level above a contract to fall back to. */
35
+ readonly owner: string | undefined;
36
+ readonly variables: readonly OwnershipModelVariable[];
37
+ }
38
+ /** One contract, referenced by identity only -- see {@link ContractRef} for why no `contractName` is carried here. Resolve one from `ContractModel` when a renderer needs display text. */
39
+ export type OwnershipModelContractRef = ContractRef;
40
+ /** One variable, referenced by its owning contract's identity plus its own key -- see {@link ContractRef}. */
41
+ export interface OwnershipModelVariableRef extends ContractRef {
42
+ readonly key: string;
43
+ }
44
+ /** The versioned, JSON-serializable root of the Ownership Model -- see this module's own doc comment for the full picture. */
45
+ export interface OwnershipModel {
46
+ readonly schemaVersion: typeof OWNERSHIP_MODEL_SCHEMA_VERSION;
47
+ readonly contracts: readonly OwnershipModelContract[];
48
+ /** Every contract with no `owner` set at all. */
49
+ readonly unownedContracts: readonly OwnershipModelContractRef[];
50
+ /** Every variable whose effective owner (its own, falling back to the contract's) is still `undefined`. */
51
+ readonly unownedVariables: readonly OwnershipModelVariableRef[];
52
+ }
53
+ /**
54
+ * Projects every discovered contract (active or not, same scope as
55
+ * `renderSecurityReview()`'s `noOwnerCount` this model itemizes) into the
56
+ * Ownership Model's versioned, JSON-serializable shape.
57
+ */
58
+ export declare function buildOwnershipModel(contracts: readonly DiscoveredContract[], root: string): OwnershipModel;
59
+ //# sourceMappingURL=ownership-model.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ownership-model.d.ts","sourceRoot":"","sources":["../../../src/build/ownership-model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD;;;;;;;;;;;;GAYG;AAEH,yIAAyI;AACzI,eAAO,MAAM,8BAA8B,IAAI,CAAA;AAE/C;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAED,6IAA6I;AAC7I,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,4IAA4I;IAC5I,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACtD;AAED,2LAA2L;AAC3L,MAAM,MAAM,yBAAyB,GAAG,WAAW,CAAA;AAEnD,8GAA8G;AAC9G,MAAM,WAAW,yBAA0B,SAAQ,WAAW;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,8HAA8H;AAC9H,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,aAAa,EAAE,OAAO,8BAA8B,CAAA;IAC7D,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;IACrD,iDAAiD;IACjD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAC/D,2GAA2G;IAC3G,QAAQ,CAAC,gBAAgB,EAAE,SAAS,yBAAyB,EAAE,CAAA;CAChE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,IAAI,EAAE,MAAM,GACX,cAAc,CAmChB"}
@@ -0,0 +1,207 @@
1
+ import type TS from "@typescript/typescript6";
2
+ import type { EnvGovernanceFields } from "./governance-fields.js";
3
+ import type { SourcePosition } from "./source-position.js";
4
+ /** A recoverable issue found while statically parsing or linking one schema file -- never fatal, always surfaced to the caller as data. */
5
+ export interface ParseWarning {
6
+ /** Absolute path of the file the warning applies to. */
7
+ readonly file: string;
8
+ /** Human-readable explanation of what was skipped and why. */
9
+ readonly message: string;
10
+ }
11
+ /**
12
+ * How a `createEnv`/`documentEnv` call's first argument resolves, before any
13
+ * cross-file linking is attempted (that's `link.ts`'s job, not this file's --
14
+ * this module only ever looks at one file's own AST).
15
+ */
16
+ export type SchemaRef = {
17
+ /** Discriminant: the schema argument is an inline object literal. */
18
+ readonly kind: "literal";
19
+ /** The object literal AST node itself. */
20
+ readonly node: TS.ObjectLiteralExpression;
21
+ } | {
22
+ /** Discriminant: the schema argument is a bare identifier referencing a local `const`. */
23
+ readonly kind: "identifier";
24
+ /** The referenced identifier's name, not yet resolved to a declaration. */
25
+ readonly name: string;
26
+ } | {
27
+ /** Discriminant: the schema argument isn't statically resolvable (not a literal or identifier). */
28
+ readonly kind: "unresolvable";
29
+ };
30
+ /** One `createEnv(...)` call site, as found by {@link parseSchemaFile}, before cross-file linking. */
31
+ interface RawCreateEnvCall {
32
+ /** The binding name the call result is assigned to (must be exported to be usable -- see {@link parseSchemaFile}). */
33
+ readonly exportName: string;
34
+ /** How the first (schema) argument resolves within this file. */
35
+ readonly schemaRef: SchemaRef;
36
+ /** The second (options) argument expression, if the call passes one. */
37
+ readonly optionsArg: TS.Expression | undefined;
38
+ /** The full call expression AST node. */
39
+ readonly node: TS.CallExpression;
40
+ }
41
+ /** One `documentEnv(...)` call site, as found by {@link parseSchemaFile}, before cross-file linking. */
42
+ interface RawDocumentEnvCall {
43
+ /** How the first (schema) argument resolves within this file. */
44
+ readonly schemaRef: SchemaRef;
45
+ /** The second (docs) argument expression, if the call passes one. */
46
+ readonly docsArg: TS.Expression | undefined;
47
+ /** The full call expression AST node. */
48
+ readonly node: TS.CallExpression;
49
+ }
50
+ /** One named import binding, tracked only for relative specifiers (see {@link FileParseResult.imports}). */
51
+ export interface ImportBinding {
52
+ /** The raw module specifier as written in the import (e.g. `"./payments.schema.js"`). */
53
+ readonly specifier: string;
54
+ /** The name as exported by the source module -- accounts for `import { real as local }`. */
55
+ readonly importedName: string;
56
+ }
57
+ /** The raw, single-file facts extracted by {@link parseSchemaFile}. */
58
+ export interface FileParseResult {
59
+ /** Absolute path of the parsed file. */
60
+ readonly file: string;
61
+ /** The TypeScript AST for this file, reused by callers that need to inspect it further. */
62
+ readonly sourceFile: TS.SourceFile;
63
+ /** Top-level `const NAME = {...}` object-literal declarations, whether exported or not. */
64
+ readonly localConsts: ReadonlyMap<string, TS.ObjectLiteralExpression>;
65
+ /** Names of top-level `const` declarations that are exported (a subset of {@link localConsts}'s keys, plus non-object-literal exports). */
66
+ readonly exportedConstNames: ReadonlySet<string>;
67
+ /** Local binding name -> where it came from. Only named imports of a relative specifier are tracked (namespace/default/bare-package imports are irrelevant to schema linking). */
68
+ readonly imports: ReadonlyMap<string, ImportBinding>;
69
+ /** Every `createEnv(...)` call site found at the top level of this file. */
70
+ readonly createEnvCalls: readonly RawCreateEnvCall[];
71
+ /** Every `documentEnv(...)` call site found at the top level of this file. */
72
+ readonly documentEnvCalls: readonly RawDocumentEnvCall[];
73
+ /** Recoverable issues found while parsing this file. */
74
+ readonly warnings: readonly ParseWarning[];
75
+ }
76
+ /**
77
+ * Structurally parses one file's AST for everything the generator needs:
78
+ * `createEnv(...)`/`documentEnv(...)` call sites, the local `const`
79
+ * declarations and imports needed to resolve an identifier passed to either
80
+ * of them.
81
+ *
82
+ * @remarks
83
+ * Never type-checks or executes the file -- see `link.ts` for how
84
+ * these raw facts get resolved into actual schema/docs data, including
85
+ * across files.
86
+ */
87
+ export declare function parseSchemaFile(filePath: string, sourceText: string): FileParseResult;
88
+ /**
89
+ * Collects named import bindings from one `import` statement into `imports`, keyed by local name.
90
+ *
91
+ * @remarks
92
+ * Exported for reuse by `scan-dependencies.ts`, which needs the same
93
+ * alias-aware named-import tracking this file already does for schema
94
+ * linking, just applied to arbitrary application source instead of schema
95
+ * files.
96
+ *
97
+ * @param imports - Mutated in place; a binding re-collected under the same local name overwrites the previous entry.
98
+ */
99
+ export declare function collectImportBindings(statement: TS.ImportDeclaration, imports: Map<string, ImportBinding>): void;
100
+ /** One schema entry's statically-discoverable shape -- presence facts, never evaluated/executed values. */
101
+ export interface DiscoveredSchemaVariable {
102
+ /** The environment variable name (the schema's object key). */
103
+ readonly key: string;
104
+ /** Whether the entry declares a `default`. */
105
+ readonly hasDefault: boolean;
106
+ /** The default's statically-evaluated literal value, if `hasDefault` and it was a literal we could evaluate -- `{ ok: false }` when present but not statically resolvable, `undefined` when absent. */
107
+ readonly defaultValue: {
108
+ /** Always `true` in this branch. */
109
+ ok: true;
110
+ /** The evaluated literal value. */
111
+ value: unknown;
112
+ } | {
113
+ /** Always `false` in this branch: present but not statically resolvable. */
114
+ ok: false;
115
+ } | undefined;
116
+ /** Whether the entry declares a `processor`. */
117
+ readonly hasProcessor: boolean;
118
+ /** The processor function's source text, normalized to single-line, if `hasProcessor`. */
119
+ readonly processorSource: string | undefined;
120
+ /** Only present when the processor has an explicit `: T` return type annotation -- the one thing we treat as provable. */
121
+ readonly processorReturnType: string | undefined;
122
+ /** Whether the entry declares a `validator`. */
123
+ readonly hasValidator: boolean;
124
+ /** The validator function's source text, normalized to single-line, if `hasValidator`. */
125
+ readonly validatorSource: string | undefined;
126
+ /** The variable's statically-resolved `context`, if set to a non-empty string literal (see ADR 0022). `undefined` when absent, non-literal, or empty. */
127
+ readonly context: string | undefined;
128
+ /** Where this variable's own schema property (e.g. `SESSION_SECRET: z.string()`) is declared -- distinct from the *contract's* `declaration`/`documentation` (`link.ts`); every variable has exactly one of these, always. See ADR 0036. */
129
+ readonly declaration: SourcePosition;
130
+ }
131
+ /**
132
+ * Extracts one schema object literal's variables (processor/validator/default presence); never
133
+ * evaluates or executes the schema.
134
+ *
135
+ * @param contextLabel - Used only to build human-readable warning messages (e.g. the contract's export name).
136
+ * @param warnings - Mutated in place: one entry is pushed per skipped (non-static, invalid-key, or non-literal) property.
137
+ */
138
+ export declare function extractSchemaVariables(schemaLiteral: TS.ObjectLiteralExpression, filePath: string, contextLabel: string, warnings: ParseWarning[], sourceFile: TS.SourceFile): DiscoveredSchemaVariable[];
139
+ /** One variable's statically-extracted `documentEnv()` documentation, as declared in that call's `variables` entry for this key -- governance fields (`owner` .. `metadata`) are `EnvGovernanceFields`, resolved from static literals. */
140
+ export interface DiscoveredVariableDocs extends EnvGovernanceFields {
141
+ /** The environment variable name this documentation applies to. */
142
+ readonly key: string;
143
+ /** Statically-resolved `description`, if set to a string literal. */
144
+ readonly description: string | undefined;
145
+ /** Statically-resolved `refreshInstructions`, if set to a string literal. */
146
+ readonly refreshInstructions: string | undefined;
147
+ /** Statically-resolved `authenticatorType`, if set to a string literal. */
148
+ readonly authenticatorType: string | undefined;
149
+ /** Statically-resolved `rotationPeriod`, if set to a string literal. */
150
+ readonly rotationPeriod: string | undefined;
151
+ /** Statically-resolved `lastRotatedAt`, if set to a string literal. */
152
+ readonly lastRotatedAt: string | undefined;
153
+ /** Statically-resolved `rotationTriggerEvents`, if set to an array of string literals. */
154
+ readonly rotationTriggerEvents: readonly string[] | undefined;
155
+ /** Statically-resolved `setupInstructions`, if set to a string literal. */
156
+ readonly setupInstructions: string | undefined;
157
+ /** Statically-resolved `required`, if set to a boolean literal. */
158
+ readonly required: boolean | undefined;
159
+ /** Statically-resolved `deprecated`, if set to a boolean literal. */
160
+ readonly deprecated: boolean | undefined;
161
+ /** Statically-resolved `deprecatedReason`, if set to a string literal. */
162
+ readonly deprecatedReason: string | undefined;
163
+ /** Statically-resolved `removeBy`, if set to a string literal. */
164
+ readonly removeBy: string | undefined;
165
+ /** Statically-resolved `renamedFrom`, if set to a string literal. */
166
+ readonly renamedFrom: string | undefined;
167
+ /** Statically-extracted `evidence` sub-object -- the re-verified-every-run half of a variable's documentation, kept structurally apart from the declared-only fields above. `undefined` when the declaration has no `evidence` key at all. See {@link runtime.VariableEvidenceDocs} and ADR 0037. */
168
+ readonly evidence: DiscoveredVariableEvidence | undefined;
169
+ }
170
+ /** The statically-extracted contents of one variable's `evidence` sub-object. See {@link runtime.VariableEvidenceDocs}. */
171
+ export interface DiscoveredVariableEvidence {
172
+ /** Well-formed `"path:line:column"` entries from `evidence.dynamicAccess`, if set to an array of string literals -- a malformed entry warns and is dropped, never included here. See ADR 0037. */
173
+ readonly dynamicAccess: readonly string[] | undefined;
174
+ }
175
+ /** A contract's statically-extracted `documentEnv()` documentation. */
176
+ /** The `documentEnv()` contract-level documentation, resolved from static literals at the parse stage. Its governance fields (`owner` .. `metadata`) are `EnvGovernanceFields`. */
177
+ export interface DiscoveredContractDocs extends EnvGovernanceFields {
178
+ /** Statically-resolved `name`, if set to a string literal. */
179
+ readonly name: string | undefined;
180
+ /** Statically-resolved `category`, if set to a string literal. */
181
+ readonly category: string | undefined;
182
+ /** Statically-resolved `exclusiveGroup`, if set to a string literal. */
183
+ readonly exclusiveGroup: string | undefined;
184
+ /** Defaults to `true` when the call's `active` field is absent or not statically resolvable. */
185
+ readonly active: boolean;
186
+ /** Statically-resolved `deprecated`, if set to a boolean literal. */
187
+ readonly deprecated: boolean | undefined;
188
+ /** Statically-resolved `deprecatedReason`, if set to a string literal. */
189
+ readonly deprecatedReason: string | undefined;
190
+ /** Per-variable documentation, keyed by variable name. */
191
+ readonly variables: ReadonlyMap<string, DiscoveredVariableDocs>;
192
+ }
193
+ /**
194
+ * Reads a `documentEnv()` call's second argument (the {@link runtime.ContractDocs} shape).
195
+ *
196
+ * @remarks
197
+ * Anything not a statically-resolvable literal warns and is skipped (falls back to
198
+ * "not set") rather than guessed at, same policy as schema-entry parsing.
199
+ *
200
+ * @param contextLabel - Used only to build human-readable warning messages.
201
+ * @param warnings - Mutated in place: one entry is pushed per unresolvable field.
202
+ */
203
+ export declare function extractContractDocs(docsArg: TS.Expression | undefined, filePath: string, contextLabel: string, warnings: ParseWarning[]): DiscoveredContractDocs;
204
+ /** Reads `createEnv`'s second argument (the {@link runtime.CreateEnvOptions} shape) for just `name`, if it's a statically-resolvable string literal. Used only for the docs fallback chain (`documentEnv`'s `name` wins if set); `source` is runtime-only and never read here. */
205
+ export declare function extractCreateEnvOptionsName(optionsArg: TS.Expression | undefined): string | undefined;
206
+ export {};
207
+ //# sourceMappingURL=parse.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../src/build/parse.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,170 @@
1
+ /**
2
+ * env-cap's own built-in reference projections, declared through the exact
3
+ * same public `defineEvidenceProjection()` a consumer would use (ADR
4
+ * 0031/0032) -- no privileged internal path, no second way of reading the
5
+ * Evidence Model.
6
+ *
7
+ * This is deliberate dogfooding, not a convenience layer: `renderDocs()`'s
8
+ * Catalog/ownership/lifecycle sections and `renderUsageReport()`'s ownership
9
+ * table now source their underlying data through these projections, so the
10
+ * extensibility API is exercised by env-cap's own generated output on every
11
+ * single run. If a projector here can't express something, that's a real gap
12
+ * in the public API -- discovered by env-cap itself rather than by a consumer
13
+ * reporting it.
14
+ *
15
+ * Every projection is pure and derives *only* from `EvidenceModel`. None
16
+ * reads the filesystem, and none reaches back into `DiscoveredContract` --
17
+ * that would defeat the point, since a consumer only ever has the model.
18
+ */
19
+ import type { EvidenceProjectionResult } from "../evidence/define-projection.js";
20
+ import type { EvidenceModel } from "./evidence-model.js";
21
+ /** One variable, flattened across Contract/Ownership/Lifecycle Model into the row a Configuration Reference renders. */
22
+ export interface ConfigurationReferenceEntry {
23
+ /** Root-relative, POSIX-separated path of the declaring contract. */
24
+ readonly file: string;
25
+ readonly exportName: string;
26
+ /** The declaring contract's display name, resolved from Contract Model -- the one model that owns it. */
27
+ readonly contractName: string;
28
+ readonly key: string;
29
+ readonly description: string | undefined;
30
+ /** Effective owner: the variable's own, falling back to its contract's. */
31
+ readonly owner: string | undefined;
32
+ /** Effective sensitivity: the variable's own, falling back to its contract's. Any string; see {@link runtime.VariableDocs.sensitivity}. */
33
+ readonly sensitivity: string | undefined;
34
+ readonly required: boolean | undefined;
35
+ readonly hasDefault: boolean;
36
+ readonly hasProcessor: boolean;
37
+ readonly hasValidator: boolean;
38
+ readonly expiresAt: string | undefined;
39
+ /** Whether the declaring contract is active. Inactive contracts are included -- the reference documents everything discovered, same scope the Catalog always had. */
40
+ readonly active: boolean;
41
+ }
42
+ /** The Configuration Reference projection's output shape. */
43
+ export interface ConfigurationReference extends Record<string, unknown> {
44
+ /** The standing "declared, not verified" notice -- see `evidenceDisclaimer()`. Carried in the data, not only in a renderer, so a consumer projecting this to their own format can't accidentally drop it. */
45
+ readonly disclaimer: string;
46
+ /** Every declared variable across every discovered contract, sorted by contract file, then export name, then key. */
47
+ readonly entries: readonly ConfigurationReferenceEntry[];
48
+ }
49
+ /** The minimal shape {@link groupVariablesByOwner} needs -- structural, not pinned to one model, so the exact same grouping serves `OwnershipModel`'s already-resolved owners and `ContractModel`'s raw ones alike. */
50
+ export interface OwnerBearingContract {
51
+ readonly owner: string | undefined;
52
+ readonly variables: readonly unknown[];
53
+ }
54
+ /** The element type of an {@link OwnerBearingContract}'s own `variables`, so callers never have to name it a second time. */
55
+ type VariableOf<C> = C extends {
56
+ readonly variables: readonly (infer V)[];
57
+ } ? V : never;
58
+ /**
59
+ * Groups every variable under its effective owner (its own, falling back to
60
+ * its contract's), preserving input order within each owner.
61
+ *
62
+ * @remarks
63
+ * The single implementation of "who owns what, rolled up per owner", shared
64
+ * by the {@link ownershipSummary} projection and `docs.ts`'s own rendered
65
+ * ownership matrix. Kept as one function precisely so env-cap's generated
66
+ * Markdown and the projection a consumer reads can never disagree about the
67
+ * grouping -- the same reason `effectiveOwner()` is the single resolution
68
+ * rule (ADR 0028). Variables with no effective owner are omitted entirely
69
+ * rather than bucketed under a synthetic `"unowned"` key, which would read
70
+ * as a real team name; callers that need them ask for them separately.
71
+ *
72
+ * `ownerOf` is supplied by the caller so a model whose owners are already
73
+ * resolved (`OwnershipModel`) and one whose aren't (`ContractModel`) both
74
+ * work without this function guessing which it was handed.
75
+ */
76
+ export declare function groupVariablesByOwner<C extends OwnerBearingContract>(contracts: readonly C[], ownerOf: (contract: C, variable: VariableOf<C>) => string | undefined): ReadonlyMap<string, readonly {
77
+ contract: C;
78
+ variable: VariableOf<C>;
79
+ }[]>;
80
+ /**
81
+ * Configuration Reference: every declared variable, with its effective owner
82
+ * and sensitivity already resolved, in one flat, sorted list.
83
+ *
84
+ * @remarks
85
+ * Resolution (variable's own value falling back to its contract's) happens
86
+ * here rather than being left to each consumer, so two readers of this
87
+ * projection can never disagree about who owns a variable -- the same reason
88
+ * `effectiveOwner()` exists on the generator side (ADR 0028).
89
+ */
90
+ export declare function configurationReference(evidence: EvidenceModel): ConfigurationReference;
91
+ export declare namespace configurationReference {
92
+ var project: typeof projectConfigurationReference;
93
+ }
94
+ declare function projectConfigurationReference(evidence: EvidenceModel): EvidenceProjectionResult<ConfigurationReference>;
95
+ /** One owner and everything attributed to them. */
96
+ export interface OwnershipSummaryEntry {
97
+ /** The owner string exactly as declared. */
98
+ readonly owner: string;
99
+ /** Every variable this owner is the effective owner of, as `${contractName}.${key}`, sorted. */
100
+ readonly variables: readonly string[];
101
+ /** Every contract declaring this owner as its contract-level default, by display name, sorted. */
102
+ readonly contracts: readonly string[];
103
+ }
104
+ /** The Ownership summary projection's output shape. */
105
+ export interface OwnershipSummary extends Record<string, unknown> {
106
+ /** See {@link ConfigurationReference.disclaimer}. */
107
+ readonly disclaimer: string;
108
+ /** One entry per distinct owner, sorted by owner. */
109
+ readonly owners: readonly OwnershipSummaryEntry[];
110
+ /** Every variable with no effective owner at all, as `${contractName}.${key}`, sorted. Named separately rather than bucketed under a synthetic `"unowned"` owner, so "nobody owns this" can never be mistaken for a real team name. */
111
+ readonly unowned: readonly string[];
112
+ }
113
+ /**
114
+ * Ownership summary: the inverse of Ownership Model's per-contract view --
115
+ * who owns what, rolled up per owner, plus an explicit unowned list.
116
+ */
117
+ export declare function ownershipSummary(evidence: EvidenceModel): OwnershipSummary;
118
+ export declare namespace ownershipSummary {
119
+ var project: typeof projectOwnershipSummary;
120
+ }
121
+ declare function projectOwnershipSummary(evidence: EvidenceModel): EvidenceProjectionResult<OwnershipSummary>;
122
+ /** One contract- or variable-level `expiresAt` inside the configured window. */
123
+ export interface ExpiringSoonEntry {
124
+ /** Root-relative, POSIX-separated path of the declaring contract. */
125
+ readonly file: string;
126
+ readonly exportName: string;
127
+ /** The declaring contract's display name, resolved from Contract Model. */
128
+ readonly contractName: string;
129
+ /** `undefined` for a contract-level expiry, set for a per-variable one. */
130
+ readonly key: string | undefined;
131
+ /** The raw ISO date string, exactly as declared -- never reformatted. */
132
+ readonly expiresAt: string;
133
+ /** Days remaining as of the run that produced this evidence; negative when already expired. */
134
+ readonly daysRemaining: number;
135
+ /** `true` when `daysRemaining` is negative -- the deadline has already passed. */
136
+ readonly expired: boolean;
137
+ /** How to obtain a replacement value, if the declaration says. */
138
+ readonly refreshInstructions: string | undefined;
139
+ /** Effective owner, so a reader knows who to chase without a second lookup. */
140
+ readonly owner: string | undefined;
141
+ }
142
+ /** The Expiring-Soon projection's output shape. */
143
+ export interface ExpiringSoonReport extends Record<string, unknown> {
144
+ /** See {@link ConfigurationReference.disclaimer}. */
145
+ readonly disclaimer: string;
146
+ /** Every entry inside the window, soonest-first (already-expired entries lead, most-overdue first). */
147
+ readonly entries: readonly ExpiringSoonEntry[];
148
+ /** How many of `entries` are already past their `expiresAt`. */
149
+ readonly expiredCount: number;
150
+ }
151
+ /**
152
+ * Expiring-Soon report: Lifecycle Model's `expiring` view, joined with
153
+ * ownership and refresh instructions so a reader can act on a row without
154
+ * cross-referencing three other models by hand.
155
+ *
156
+ * @remarks
157
+ * The window itself was applied upstream, when Lifecycle Model was built --
158
+ * this projection deliberately does not re-filter by a date of its own.
159
+ * Recomputing "soon" here would make the projection's answer depend on when
160
+ * it happened to be *read* rather than when the evidence was *generated*,
161
+ * which is exactly the reproducibility property the Evidence Model exists to
162
+ * preserve.
163
+ */
164
+ export declare function expiringSoonReport(evidence: EvidenceModel): ExpiringSoonReport;
165
+ export declare namespace expiringSoonReport {
166
+ var project: typeof projectExpiringSoonReport;
167
+ }
168
+ declare function projectExpiringSoonReport(evidence: EvidenceModel): EvidenceProjectionResult<ExpiringSoonReport>;
169
+ export {};
170
+ //# sourceMappingURL=reference-projections.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"reference-projections.d.ts","sourceRoot":"","sources":["../../../src/build/reference-projections.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,58 @@
1
+ import type { BuildFileSystem } from "../types.js";
2
+ import { type PackageSchemaResolutionResult } from "./resolve-package-schema.js";
3
+ import { type AliasResolutionCache, type TsconfigPathsResolution } from "./resolve-tsconfig-paths.js";
4
+ /**
5
+ * Resolves a relative import specifier (as written in source: `"./schema.js"`,
6
+ * matching this codebase's own convention of `.js`-suffixed relative imports
7
+ * pointing at `.ts` source files) to an absolute file path, relative to the
8
+ * file that contains the import.
9
+ *
10
+ * @remarks
11
+ * Deliberately narrow: only handles a direct relative specifier resolving to
12
+ * a real `.ts`/`.tsx` file on disk. Bare/package specifiers, namespace
13
+ * imports, and anything requiring real module resolution (re-export chains,
14
+ * `exports` map lookups, etc.) return `undefined` -- the caller treats that
15
+ * as "couldn't statically link" and warns rather than guesses, the same
16
+ * philosophy `evaluateLiteral` already uses for non-literal expressions.
17
+ *
18
+ * @returns The resolved absolute path, or `undefined` when the specifier isn't relative or doesn't resolve to a real file.
19
+ */
20
+ export declare function resolveRelativeImport(importingFile: string, specifier: string, fs: BuildFileSystem): Promise<string | undefined>;
21
+ /**
22
+ * Whether `filePath` is a regular file; a path that cannot be stat'd is simply not one.
23
+ * @internal Exported for direct unit coverage.
24
+ */
25
+ export declare function fileExists(filePath: string, fs: BuildFileSystem): Promise<boolean>;
26
+ /** Shared inputs threaded through every call to {@link resolveImportSpecifier} for one discovery/link run. */
27
+ export interface ImportResolutionContext {
28
+ /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
29
+ readonly fs: BuildFileSystem;
30
+ /** Absolute path of the project root, used to resolve package specifiers. */
31
+ readonly root: string;
32
+ /** Explicit allowlist -- see ADR 0014. Empty/omitted means package resolution never fires, identical to today's behavior. */
33
+ readonly packages: readonly string[];
34
+ /** Memoizes package resolution per specifier across the whole run -- see `resolvePackageImport`'s own doc comment for why. */
35
+ readonly cache: Map<string, Promise<PackageSchemaResolutionResult>>;
36
+ /** Parsed `tsconfig.json` `paths`/`baseUrl`, or `undefined` when alias resolution found nothing to do or was disabled -- see ADR 0023. */
37
+ readonly tsconfigPaths: TsconfigPathsResolution | undefined;
38
+ /** Memoizes alias resolution across the whole run -- see `resolveAliasImport`'s own doc comment for why. Always allocated, even when `tsconfigPaths` is `undefined`, mirroring `cache` above. */
39
+ readonly aliasCache: AliasResolutionCache;
40
+ }
41
+ /**
42
+ * The one specifier-resolution entry point `link.ts` and `dependency-graph.ts`
43
+ * call, instead of each duplicating a
44
+ * `(await resolveRelativeImport(...)) ?? resolveAliasImport(...) ?? (await resolvePackageImport(...))`
45
+ * chain at every call site.
46
+ *
47
+ * @remarks
48
+ * Purely a composition point -- no new resolution logic lives here. Tries, in order: the
49
+ * relative resolver (cheap, no `fs.stat` beyond the local filesystem check it already
50
+ * does); tsconfig path-alias resolution (ADR 0023, on by default) for a bare specifier
51
+ * matching the project's own `tsconfig.json` `paths`/`baseUrl`; then package resolution
52
+ * (ADR 0014) for a bare specifier matching an allow-listed package name. Alias resolution
53
+ * runs before package resolution because it resolves the consuming project's own local
54
+ * source (already-trusted, no versioning boundary), the same precedence relative
55
+ * resolution already has over package resolution.
56
+ */
57
+ export declare function resolveImportSpecifier(importingFile: string, specifier: string, context: ImportResolutionContext): Promise<string | undefined>;
58
+ //# sourceMappingURL=resolve-import.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolve-import.d.ts","sourceRoot":"","sources":["../../../../src/build/resolution/resolve-import.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC7B,MAAM,6BAA6B,CAAA;AAEpC;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAKlF;AAED,8GAA8G;AAC9G,MAAM,WAAW,uBAAuB;IACtC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6HAA6H;IAC7H,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,8HAA8H;IAC9H,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,CAAA;IACnE,0IAA0I;IAC1I,QAAQ,CAAC,aAAa,EAAE,uBAAuB,GAAG,SAAS,CAAA;IAC3D,iMAAiM;IACjM,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,sBAAsB,CAC1C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B"}