@maverickcer/env-cap 0.7.6 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (184) hide show
  1. package/ADOPTION.md +4 -4
  2. package/AGENTS.md +2 -3
  3. package/CHANGELOG.md +36 -0
  4. package/CODE_REVIEW.md +1 -1
  5. package/CONTRIBUTING.md +1 -1
  6. package/GUIDE.md +12 -12
  7. package/README.md +11 -12
  8. package/VERSIONING.md +2 -1
  9. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +3 -4
  10. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  11. package/dist/.dts/build/assemble-project.d.ts +3 -3
  12. package/dist/.dts/build/change-model.d.ts +9 -11
  13. package/dist/.dts/build/change-model.d.ts.map +1 -1
  14. package/dist/.dts/build/check-artifacts.d.ts +5 -6
  15. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  16. package/dist/.dts/build/citation-verification.d.ts +6 -7
  17. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  18. package/dist/.dts/build/contract-model.d.ts +7 -8
  19. package/dist/.dts/build/contract-model.d.ts.map +1 -1
  20. package/dist/.dts/build/deep-equal.d.ts +3 -3
  21. package/dist/.dts/build/deep-freeze.d.ts +5 -7
  22. package/dist/.dts/build/deep-freeze.d.ts.map +1 -1
  23. package/dist/.dts/build/dependency-model.d.ts +2 -2
  24. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  25. package/dist/.dts/build/discover.d.ts +6 -6
  26. package/dist/.dts/build/discover.d.ts.map +1 -1
  27. package/dist/.dts/build/env-example.d.ts +6 -7
  28. package/dist/.dts/build/env-example.d.ts.map +1 -1
  29. package/dist/.dts/build/errors.d.ts +4 -4
  30. package/dist/.dts/build/evidence-cache.d.ts +12 -14
  31. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  32. package/dist/.dts/build/evidence-model.d.ts +6 -7
  33. package/dist/.dts/build/evidence-model.d.ts.map +1 -1
  34. package/dist/.dts/build/evidence-reference.d.ts +6 -6
  35. package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
  36. package/dist/.dts/build/exclusive-group.d.ts +3 -3
  37. package/dist/.dts/build/finding-model.d.ts +12 -13
  38. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  39. package/dist/.dts/build/generate-documentation.d.ts +6 -7
  40. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  41. package/dist/.dts/build/generate-evidence.d.ts +13 -15
  42. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  43. package/dist/.dts/build/generate-manifest.d.ts +14 -16
  44. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  45. package/dist/.dts/build/generated-banner.d.ts +3 -3
  46. package/dist/.dts/build/governance-fields.d.ts +3 -3
  47. package/dist/.dts/build/humanize-key.d.ts +3 -3
  48. package/dist/.dts/build/lifecycle-model.d.ts +3 -3
  49. package/dist/.dts/build/literal-eval.d.ts +2 -2
  50. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  51. package/dist/.dts/build/live-expirations.d.ts +9 -9
  52. package/dist/.dts/build/manifest.d.ts +7 -8
  53. package/dist/.dts/build/manifest.d.ts.map +1 -1
  54. package/dist/.dts/build/merge-documentation.d.ts +4 -5
  55. package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
  56. package/dist/.dts/build/resolution/resolve-import.d.ts +8 -9
  57. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  58. package/dist/.dts/build/resolution/resolve-within-root.d.ts +4 -4
  59. package/dist/.dts/build/sarif.d.ts +9 -11
  60. package/dist/.dts/build/sarif.d.ts.map +1 -1
  61. package/dist/.dts/build/source-position.d.ts +14 -17
  62. package/dist/.dts/build/source-position.d.ts.map +1 -1
  63. package/dist/.dts/build/usage-report.d.ts +16 -17
  64. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  65. package/dist/.dts/cli/filesystem.d.ts.map +1 -1
  66. package/dist/.dts/eslint-plugin/glob.d.ts +2 -2
  67. package/dist/.dts/eslint-plugin/index.d.ts +2 -1
  68. package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
  69. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +5 -5
  70. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
  71. package/dist/.dts/evidence/define-projection.d.ts +6 -6
  72. package/dist/.dts/runtime/create.d.ts +2 -3
  73. package/dist/.dts/runtime/create.d.ts.map +1 -1
  74. package/dist/.dts/runtime/errors.d.ts +7 -8
  75. package/dist/.dts/runtime/errors.d.ts.map +1 -1
  76. package/dist/.dts/runtime/index.d.ts +2 -2
  77. package/dist/.dts/runtime/types.d.ts +18 -20
  78. package/dist/.dts/runtime/types.d.ts.map +1 -1
  79. package/dist/.dts/runtime/validate.d.ts +2 -2
  80. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  81. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +3 -4
  82. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  83. package/dist/.dts7/build/assemble-project.d.ts +3 -3
  84. package/dist/.dts7/build/change-model.d.ts +9 -11
  85. package/dist/.dts7/build/change-model.d.ts.map +1 -1
  86. package/dist/.dts7/build/check-artifacts.d.ts +5 -6
  87. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -1
  88. package/dist/.dts7/build/citation-verification.d.ts +6 -7
  89. package/dist/.dts7/build/citation-verification.d.ts.map +1 -1
  90. package/dist/.dts7/build/contract-model.d.ts +7 -8
  91. package/dist/.dts7/build/contract-model.d.ts.map +1 -1
  92. package/dist/.dts7/build/deep-equal.d.ts +3 -3
  93. package/dist/.dts7/build/deep-freeze.d.ts +5 -7
  94. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -1
  95. package/dist/.dts7/build/dependency-model.d.ts +2 -2
  96. package/dist/.dts7/build/dependency-model.d.ts.map +1 -1
  97. package/dist/.dts7/build/discover.d.ts +6 -6
  98. package/dist/.dts7/build/discover.d.ts.map +1 -1
  99. package/dist/.dts7/build/env-example.d.ts +6 -7
  100. package/dist/.dts7/build/env-example.d.ts.map +1 -1
  101. package/dist/.dts7/build/errors.d.ts +4 -4
  102. package/dist/.dts7/build/evidence-cache.d.ts +12 -14
  103. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -1
  104. package/dist/.dts7/build/evidence-model.d.ts +6 -7
  105. package/dist/.dts7/build/evidence-model.d.ts.map +1 -1
  106. package/dist/.dts7/build/evidence-reference.d.ts +6 -6
  107. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -1
  108. package/dist/.dts7/build/exclusive-group.d.ts +3 -3
  109. package/dist/.dts7/build/finding-model.d.ts +12 -13
  110. package/dist/.dts7/build/finding-model.d.ts.map +1 -1
  111. package/dist/.dts7/build/generate-documentation.d.ts +6 -7
  112. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -1
  113. package/dist/.dts7/build/generate-evidence.d.ts +13 -15
  114. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -1
  115. package/dist/.dts7/build/generate-manifest.d.ts +14 -16
  116. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -1
  117. package/dist/.dts7/build/generated-banner.d.ts +3 -3
  118. package/dist/.dts7/build/governance-fields.d.ts +3 -3
  119. package/dist/.dts7/build/humanize-key.d.ts +3 -3
  120. package/dist/.dts7/build/lifecycle-model.d.ts +3 -3
  121. package/dist/.dts7/build/literal-eval.d.ts +2 -2
  122. package/dist/.dts7/build/literal-eval.d.ts.map +1 -1
  123. package/dist/.dts7/build/live-expirations.d.ts +9 -9
  124. package/dist/.dts7/build/manifest.d.ts +7 -8
  125. package/dist/.dts7/build/manifest.d.ts.map +1 -1
  126. package/dist/.dts7/build/merge-documentation.d.ts +4 -5
  127. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -1
  128. package/dist/.dts7/build/resolution/resolve-import.d.ts +8 -9
  129. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -1
  130. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +4 -4
  131. package/dist/.dts7/build/sarif.d.ts +9 -11
  132. package/dist/.dts7/build/sarif.d.ts.map +1 -1
  133. package/dist/.dts7/build/source-position.d.ts +14 -17
  134. package/dist/.dts7/build/source-position.d.ts.map +1 -1
  135. package/dist/.dts7/build/usage-report.d.ts +16 -17
  136. package/dist/.dts7/build/usage-report.d.ts.map +1 -1
  137. package/dist/.dts7/cli/filesystem.d.ts.map +1 -1
  138. package/dist/.dts7/eslint-plugin/glob.d.ts +2 -2
  139. package/dist/.dts7/eslint-plugin/index.d.ts +2 -1
  140. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -1
  141. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +5 -5
  142. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +4 -4
  143. package/dist/.dts7/evidence/define-projection.d.ts +6 -6
  144. package/dist/.dts7/runtime/create.d.ts +2 -3
  145. package/dist/.dts7/runtime/create.d.ts.map +1 -1
  146. package/dist/.dts7/runtime/errors.d.ts +7 -8
  147. package/dist/.dts7/runtime/errors.d.ts.map +1 -1
  148. package/dist/.dts7/runtime/index.d.ts +2 -2
  149. package/dist/.dts7/runtime/types.d.ts +18 -20
  150. package/dist/.dts7/runtime/types.d.ts.map +1 -1
  151. package/dist/.dts7/runtime/validate.d.ts +2 -2
  152. package/dist/.dts7/runtime/validate.d.ts.map +1 -1
  153. package/dist/{build-UEENZEUX.js → build-Z76NCC65.js} +7 -10
  154. package/dist/build-Z76NCC65.js.map +1 -0
  155. package/dist/build.cjs +6 -9
  156. package/dist/build.cjs.map +1 -1
  157. package/dist/build.js +6 -9
  158. package/dist/build.js.map +1 -1
  159. package/dist/{chunk-TBL3O7IG.js → chunk-JRCMG4FQ.js} +2 -2
  160. package/dist/cli/index.js +3 -3
  161. package/dist/cli/index.js.map +1 -1
  162. package/dist/eslint-plugin/index.cjs.map +1 -1
  163. package/dist/eslint-plugin/index.js.map +1 -1
  164. package/dist/evidence.cjs.map +1 -1
  165. package/dist/evidence.js.map +1 -1
  166. package/dist/index.cjs.map +1 -1
  167. package/dist/index.js.map +1 -1
  168. package/dist/node.cjs.map +1 -1
  169. package/dist/node.js.map +1 -1
  170. package/package.json +8 -7
  171. package/schemas/env-cap-report.schema.json +11 -11
  172. package/skills/env-cap/SKILL.md +1 -1
  173. package/skills/env-cap/references/api.md +1 -1
  174. package/specs/architecture.md +6 -6
  175. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +9 -0
  176. package/specs/migrations/README.md +9 -9
  177. package/specs/migrations/from-centralized-schema.md +28 -28
  178. package/specs/migrations/from-dotenv.md +11 -11
  179. package/specs/migrations/from-envalid.md +16 -16
  180. package/specs/migrations/from-process-env.md +19 -19
  181. package/specs/migrations/from-t3-env.md +24 -24
  182. package/specs/migrations/from-zod.md +21 -21
  183. package/dist/build-UEENZEUX.js.map +0 -1
  184. /package/dist/{chunk-TBL3O7IG.js.map → chunk-JRCMG4FQ.js.map} +0 -0
@@ -16,10 +16,10 @@ export interface GenerateEvidenceModelOptions {
16
16
  /** See `GenerateEnvManifestOptions.tsconfig`. See ADR 0023. */
17
17
  tsconfig?: string | false | undefined;
18
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
19
+ * Where a previously persisted evidence artifact lives, relative to
20
+ * `root`. It is read, never written. Change Model diffs against it, and
21
+ * dynamic-access citation freshness (ADR 0037) compares content hashes
22
+ * with it. Independent of any `.ts` manifest a project may or
23
23
  * may not also generate: there is no derivation from a manifest's own
24
24
  * location. Omitted: treated as the normal first-run state (everything
25
25
  * reads as added, no citation-freshness baseline to compare against),
@@ -30,9 +30,9 @@ export interface GenerateEvidenceModelOptions {
30
30
  expiringWithinDays?: number | undefined;
31
31
  /**
32
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.
33
+ * override. It applies only to Lifecycle Model and Finding Model's
34
+ * `expiring-soon` findings. Contract Model still reflects the schema's
35
+ * static `expiresAt`. See `live-expirations.ts` and ADR 0012.
36
36
  */
37
37
  liveExpirationDates?: LiveExpirationDates | undefined;
38
38
  /**
@@ -53,10 +53,9 @@ export interface GenerateEvidenceModelOptions {
53
53
  * before being returned.
54
54
  *
55
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 differs from `generateEnvManifest()`, which throws by
56
+ * Never throws on a data-quality finding, such as a compatibility issue,
57
+ * an undocumented variable or an abandoned contract. Each becomes a
58
+ * `Finding` in the returned model's `finding` field instead. This differs from `generateEnvManifest()`, which throws by
60
59
  * default, because that is a "should I write this artifact" gate. Evidence
61
60
  * Model assembly is a read-only snapshot. Its purpose is to represent such
62
61
  * issues as data for a consumer's own projection to act on (see ADR 0024's
@@ -64,10 +63,9 @@ export interface GenerateEvidenceModelOptions {
64
63
  * `EnvProjectGenerationError` for a genuine configuration error:
65
64
  * `previousSnapshotLocation` escaping `root`.
66
65
  *
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. That cost is accepted: each half's
66
+ * Dependency Model (via `buildDependencyModel()`) and Finding Model's
67
+ * ownership findings (via `computeUsage()`) each run a dependency-graph scan.
68
+ * The two scans are separate passes over the repository. That cost is accepted: each half's
71
69
  * already-tested public building block is called directly, rather than a
72
70
  * second copy of either's logic being hand-derived here. Both are Node-only,
73
71
  * dev/CI-time-only work (never a runtime hot path), so the redundant I/O is
@@ -1 +1 @@
1
- {"version":3,"file":"generate-evidence.d.ts","sourceRoot":"","sources":["../../../src/build/generate-evidence.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAYxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,+EAA+E;IAC/E,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAA;IACrD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,aAAa,CAAC,CAyHxB"}
1
+ {"version":3,"file":"generate-evidence.d.ts","sourceRoot":"","sources":["../../../src/build/generate-evidence.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAYxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,+EAA+E;IAC/E,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAA;IACrD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,aAAa,CAAC,CAyHxB"}
@@ -15,11 +15,10 @@ export interface GenerateEnvManifestOptions {
15
15
  /** Glob patterns to exclude. Defaults to node_modules/dist/.git. */
16
16
  exclude?: string[] | undefined;
17
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
18
+ * Explicit allowlist of installed package names whose declared
19
+ * `"envCap": { "schema": "<path>" }` entry point is also discovered. It lets
20
+ * the manifest include a contract published as a separate package, with no
21
+ * monorepo required. Opt-in only: a package is never considered unless its
23
22
  * exact name appears here. See ADR 0014.
24
23
  */
25
24
  packages?: readonly string[] | undefined;
@@ -28,9 +27,9 @@ export interface GenerateEnvManifestOptions {
28
27
  * whose `compilerOptions.paths`/`baseUrl` resolve aliased import specifiers (e.g.
29
28
  * `"@/lib/env.schema.js"`) encountered during static analysis, so a contract or consumer
30
29
  * 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
30
+ * `"tsconfig.json"` at `root`, so it is on with no opt-in. Unlike `packages`, it never
31
+ * crosses a trust or versioning boundary: every resolved file is local, trusted project
32
+ * source. Pass `false` to disable entirely. See
34
33
  * ADR 0023.
35
34
  */
36
35
  tsconfig?: string | false | undefined;
@@ -83,16 +82,15 @@ export declare function computeManifest(root: string, linkResult: LinkResult, on
83
82
  /** Writes the manifest file. Callers must have already confirmed `outputPath` is safe and nothing is blocking. */
84
83
  export declare function writeManifest(outputPath: string, activeContracts: readonly DiscoveredContract[], fs: BuildFileSystem): Promise<void>;
85
84
  /**
86
- * Build-time only. Discovers `env.schema.ts` files, statically analyzes them
87
- * (never executes them) to link `createEnv()`/`documentEnv()` calls, checks
88
- * for provable incompatibilities between duplicate variable declarations,
89
- * and writes a deterministic manifest file that re-exports every discovered
90
- * active contract.
85
+ * Build-time only. Discovers `env.schema.ts` files and analyzes them
86
+ * statically, never executing them, to link `createEnv()`/`documentEnv()`
87
+ * calls. It checks duplicate variable declarations for provable
88
+ * incompatibilities. Then it writes a deterministic manifest file that
89
+ * re-exports every discovered active contract.
91
90
  *
92
91
  * @remarks
93
- * Never call this at application startup or import it from
94
- * runtime code: wire it into an npm script, a bundler plugin, or a CI
95
- * step instead.
92
+ * Run it from an npm script, a bundler plugin or a CI step. Application
93
+ * startup and runtime code never call or import it.
96
94
  *
97
95
  * @throws {EnvManifestGenerationError} If `location` escapes `root`, or if a blocking compatibility/exclusive-group issue is found.
98
96
  */
@@ -1 +1 @@
1
- {"version":3,"file":"generate-manifest.d.ts","sourceRoot":"","sources":["../../../src/build/generate-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAG5D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EAChB,MAAM,WAAW,CAAA;AAElB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yGAAyG;IACzG,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CACjD;AAED,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACxD,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,4GAA4G;IAC5G,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;CAChD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AACD,8GAA8G;AAC9G,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAczC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,eAAe,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACvD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAChE,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,iBAAiB,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAC9C,mBAAmB,CAwBrB;AAED,kHAAkH;AAClH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAoCpC"}
1
+ {"version":3,"file":"generate-manifest.d.ts","sourceRoot":"","sources":["../../../src/build/generate-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAG5D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EAChB,MAAM,WAAW,CAAA;AAElB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yGAAyG;IACzG,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CACjD;AAED,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACxD,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,4GAA4G;IAC5G,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;CAChD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AACD,8GAA8G;AAC9G,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAWzC;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;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAoCpC"}
@@ -1,7 +1,7 @@
1
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.
2
+ * Regeneration instruction for a report the CLI does not write (ADR 0046). The project's script produces it
3
+ * with the `@maverickcer/env-cap/build` generators. Naming `npx env-cap` would send a reader to a command
4
+ * that cannot regenerate it.
5
5
  * @returns The instruction, as a sentence.
6
6
  */
7
7
  export declare function reportRegenerateHint(): string;
@@ -26,9 +26,9 @@ export interface EnvGovernanceFields {
26
26
  }
27
27
  /**
28
28
  * Copies exactly the `EnvGovernanceFields` out of a value that carries
29
- * them: for projecting one pipeline stage's contract/variable into the next
30
- * (`link` -> `contract-model` -> `docs` catalog, ...) without re-listing all
31
- * nine fields at every hop.
29
+ * them. Each pipeline stage (`link` -> `contract-model` -> `docs` catalog,
30
+ * ...) projects its contract or variable into the next without re-listing
31
+ * all nine fields.
32
32
  */
33
33
  export declare function governanceFieldsOf(source: EnvGovernanceFields): EnvGovernanceFields;
34
34
  //# sourceMappingURL=governance-fields.d.ts.map
@@ -5,9 +5,9 @@
5
5
  */
6
6
  export declare function humanizeKey(key: string): string;
7
7
  /**
8
- * Formats a `metadata`/`dataResidency` value for display in generated docs/examples: a string
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
8
+ * Formats a `metadata`/`dataResidency` value for display in generated docs/examples. A string
9
+ * renders as-is. Anything else renders as its JSON text, since ADR 0035 widened `metadata` to
10
+ * any value. So an object or array never prints `[object Object]`. Shared by `docs.ts` and
11
11
  * `env-example.ts`, same rationale as {@link humanizeKey}.
12
12
  */
13
13
  export declare function renderMetadataValue(value: unknown): string;
@@ -158,9 +158,9 @@ export declare function parseRotationPeriodDays(value: string): number | undefin
158
158
  * `lastRotatedAt` and/or `rotationTriggerEvents`), with no `rotationPeriod` and no past-due
159
159
  * `expiresAt`. Nothing states a time-based obligation this variable could be failing to meet.
160
160
  *
161
- * `rotationTriggerEvents` (the event-based trigger) deliberately never changes the returned status
162
- * by itself. env-cap cannot observe whether a listed event (a suspected compromise, a personnel
163
- * change, ...) actually occurred. Treating its mere presence as either compliant or overdue would
161
+ * `rotationTriggerEvents` (the event-based trigger) never changes the returned status by itself.
162
+ * Nothing in env-cap can observe whether a listed event occurred, such as a suspected compromise or
163
+ * a personnel change. Treating its mere presence as either compliant or overdue would
164
164
  * fabricate a signal. It's presence-only evidence that the event-based half of IA-5's
165
165
  * two-trigger model was at least *declared*. A generator should still surface it, but never fold
166
166
  * it into this computed status.
@@ -11,8 +11,8 @@ export type LiteralEvalResult = {
11
11
  value?: undefined;
12
12
  };
13
13
  /**
14
- * Structurally evaluates a *literal* AST expression (strings, numbers, booleans, null, arrays,
15
- * and object literals of the same) into a real JS value: without ever executing code.
14
+ * Structurally evaluates a *literal* AST expression into a real JS value, without executing code.
15
+ * Literals are strings, numbers, booleans, null, and arrays and object literals of those.
16
16
  *
17
17
  * @remarks
18
18
  * Anything that isn't a literal (identifiers, calls, imports, template expressions with
@@ -1 +1 @@
1
- {"version":3,"file":"literal-eval.d.ts","sourceRoot":"","sources":["../../../src/build/literal-eval.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhC;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,CAAA;AAE/F;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,GAAG,iBAAiB,CA4CtE;AAED,8KAA8K;AAC9K,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,GAAG,MAAM,GAAG,SAAS,CAK/E"}
1
+ {"version":3,"file":"literal-eval.d.ts","sourceRoot":"","sources":["../../../src/build/literal-eval.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhC;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,CAAA;AAE/F;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,GAAG,iBAAiB,CA2CtE;AAED,8KAA8K;AAC9K,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,GAAG,MAAM,GAAG,SAAS,CAK/E"}
@@ -1,8 +1,8 @@
1
1
  import type { DiscoveredContract } from "./link.js";
2
2
  /**
3
- * Supplies expiration metadata from a live source (a secrets manager, an
4
- * internal inventory API, ...) as a post-discovery override: the one
5
- * sanctioned escape hatch from static-only `expiresAt`.
3
+ * Supplies expiration metadata from a live source, such as a secrets manager
4
+ * or an inventory API, as a post-discovery override. It is the one sanctioned
5
+ * escape hatch from static-only `expiresAt`.
6
6
  *
7
7
  * @remarks
8
8
  * Invoked exactly once per generation run, from the orchestration layer, after AST discovery/
@@ -25,9 +25,9 @@ export declare function collectVariableNames(contracts: readonly DiscoveredContr
25
25
  *
26
26
  * @remarks
27
27
  * A key absent from `overrides`, or present but not a `parseIsoDate`-parseable
28
- * ISO-8601 string, leaves that variable's static `expiresAt` untouched:
29
- * same "warn/skip, never guess" policy the rest of the generator uses for
30
- * malformed data. Contract-level `expiresAt` is never touched; only
28
+ * ISO-8601 string, leaves that variable's static `expiresAt` untouched. The
29
+ * rest of the generator treats malformed data the same way: warn or skip,
30
+ * never guess. Contract-level `expiresAt` is never touched; only
31
31
  * variable-level `expiresAt` is in scope for override.
32
32
  */
33
33
  export declare function applyLiveExpirationOverrides(contracts: readonly DiscoveredContract[], overrides: Readonly<Record<string, string>>): readonly DiscoveredContract[];
@@ -35,9 +35,9 @@ export declare function applyLiveExpirationOverrides(contracts: readonly Discove
35
35
  * Orchestration entry point: the only place `liveExpirationDates` is ever invoked.
36
36
  *
37
37
  * @remarks
38
- * No-ops (returns the exact same array reference, zero invocations)
39
- * when `liveExpirationDates` is undefined, which is what guarantees "omitted ->
40
- * behavior unchanged." Otherwise it collects the unique discovered variable
38
+ * When `liveExpirationDates` is undefined it does nothing: it returns the same
39
+ * array reference and invokes nothing. That keeps behavior unchanged when the
40
+ * option is omitted. Otherwise it collects the unique discovered variable
41
41
  * names, invokes the callback exactly once and applies the result. It
42
42
  * deep-freezes the returned structure so no mutation of it can reach
43
43
  * `contracts` or anything else downstream. `contracts` is used elsewhere too,
@@ -1,9 +1,8 @@
1
1
  import type { DiscoveredContract } from "./link.js";
2
2
  /**
3
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}
4
+ * in `contracts`, sorted and deduplicated. A contract documented
5
+ * `active: false` never contributes, as in the `manifest` array. What {@link renderManifest}
7
6
  * surfaces as the generated `activeContexts` export. Exported for reuse by
8
7
  * anything that needs the same computation (currently just `renderManifest`
9
8
  * itself).
@@ -11,8 +10,8 @@ import type { DiscoveredContract } from "./link.js";
11
10
  export declare function discoverValidationContexts(contracts: readonly DiscoveredContract[]): readonly string[];
12
11
  /**
13
12
  * 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
13
+ * collision) plus a `contracts` array. The banner marks the file as generated
14
+ * for schema authors. No timestamps, no randomness: same
16
15
  * input files always produce byte-identical output.
17
16
  *
18
17
  * @remarks
@@ -23,9 +22,9 @@ export declare function discoverValidationContexts(contracts: readonly Discovere
23
22
  * `manifest` and pass it straight through: `validateEnv({ manifest, values, activeContexts })`.
24
23
  * It's every context this manifest has, meant as a starting point to narrow
25
24
  * 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.
25
+ * "Validation contexts" section. It is omitted, not even an empty array, when
26
+ * no variable declares a `context`. So projects that don't use contexts get
27
+ * unchanged output.
29
28
  */
30
29
  export declare function renderManifest(contracts: readonly DiscoveredContract[], outputFile: string): string;
31
30
  //# sourceMappingURL=manifest.d.ts.map
@@ -1 +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"}
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;;;;;;;GAOG;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"}
@@ -10,11 +10,10 @@ export declare const VALUE_FIELDS: readonly ["description", "owner", "sensitivit
10
10
  * Fills what one declaration of a variable leaves unset from the other declarations of the same variable.
11
11
  *
12
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).
13
+ * A variable can be declared in more than one contract. A package that ships a contract (see {@link ../README}
14
+ * "Reusable packages") and the application that consumes it can name the same environment variable. The process
15
+ * has one flat namespace. Writing the explanation twice is how the two drift. So one declaration carries it, and
16
+ * the other adds only its own fields (the application's `expiresAt`, say).
18
17
  *
19
18
  * Every field a declaration leaves unset is taken from another declaration that sets it, as long as one of the two
20
19
  * is a package's contract. When several set it, a package's contract wins over the application's own, and the
@@ -1 +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;;;;;;;;;;;;;;;;;GAiBG;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"}
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"}
@@ -2,18 +2,17 @@ import type { BuildFileSystem } from "../types.js";
2
2
  import { type PackageSchemaResolutionResult } from "./resolve-package-schema.js";
3
3
  import { type AliasResolutionCache, type TsconfigPathsResolution } from "./resolve-tsconfig-paths.js";
4
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.
5
+ * Resolves a relative import specifier, as written in source (`"./schema.js"`),
6
+ * to an absolute file path. It resolves against the file that contains the
7
+ * import. A `.js` suffix points at the `.ts` source file, as in this codebase.
9
8
  *
10
9
  * @remarks
11
10
  * 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.
11
+ * a real `.ts`/`.tsx` file on disk. Anything else returns `undefined`: bare
12
+ * or package specifiers, namespace imports, and anything that needs real
13
+ * module resolution (re-export chains, `exports` map lookups). The caller
14
+ * reads that as "couldn't statically link" and warns rather than guesses.
15
+ * `evaluateLiteral` treats non-literal expressions the same way.
17
16
  *
18
17
  * @returns The resolved absolute path, or `undefined` when the specifier isn't relative or doesn't resolve to a real file.
19
18
  */
@@ -1 +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,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2HAA2H;IAC3H,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,4HAA4H;IAC5H,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,CAAA;IACnE,wIAAwI;IACxI,QAAQ,CAAC,aAAa,EAAE,uBAAuB,GAAG,SAAS,CAAA;IAC3D,+LAA+L;IAC/L,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAC1C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B"}
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;;;;;;;;;;;;;;GAcG;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,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2HAA2H;IAC3H,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,4HAA4H;IAC5H,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,CAAA;IACnE,wIAAwI;IACxI,QAAQ,CAAC,aAAa,EAAE,uBAAuB,GAAG,SAAS,CAAA;IAC3D,+LAA+L;IAC/L,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAC1C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B"}
@@ -22,10 +22,10 @@ export declare function isWithinDirectory(baseDir: string, targetPath: string):
22
22
  * branch of the filesystem entirely). Discovery (`include`/`exclude`) is
23
23
  * already safe by construction: it only ever walks *down* from `root` via
24
24
  * `readdir`, so a pattern can't make it read outside `root`. Output
25
- * locations have no such structural guarantee, since `path.resolve` happily
26
- * walks back out via `..` segments, so this is a plain lexical bounds-check
27
- * (not a symlink-aware `realpath` check: these are *output* paths that
28
- * usually don't exist yet).
25
+ * locations have no such guarantee, since `path.resolve` walks back out
26
+ * through `..` segments. So this is a lexical bounds-check. It is not a
27
+ * symlink-aware `realpath` check, because *output* paths usually don't
28
+ * exist yet.
29
29
  *
30
30
  * Never throws itself: returns a `CompatibilityIssue`-shaped finding on
31
31
  * escape so each generator function (`generateEnvManifest`, `generateDocumentation`,
@@ -1,14 +1,13 @@
1
1
  /**
2
2
  * SARIF export: an adapter over Finding Model, not a new fact source.
3
3
  * Produces a minimal, spec-conformant SARIF 2.1.0 log
4
- * (https://docs.oasis-open.org/sarif/sarif/v2.1.0/) so env-cap's findings can
5
- * be consumed by any SARIF-aware tool (GitHub code scanning, most CI security
6
- * dashboards) without a bespoke integration.
4
+ * (https://docs.oasis-open.org/sarif/sarif/v2.1.0/). Any SARIF-aware tool can
5
+ * then read env-cap's findings, such as GitHub code scanning or a CI security
6
+ * dashboard.
7
7
  *
8
- * Pure and synchronous: every input is already computed by the time this
9
- * runs, so this never re-derives a finding, never reads the filesystem, and
10
- * never decides what is or isn't a problem; it only re-shapes what
11
- * `buildFindingModel()` already concluded.
8
+ * Pure and synchronous: every input is computed before this runs. It never
9
+ * re-derives a finding, reads the filesystem or decides what is a problem.
10
+ * It only re-shapes what `buildFindingModel()` concluded.
12
11
  */
13
12
  import type { FindingModel } from "./finding-model.js";
14
13
  /** SARIF's `level` enum: see the SARIF 2.1.0 spec, section 3.27.10. */
@@ -55,10 +54,9 @@ export interface SarifLog {
55
54
  *
56
55
  * @remarks
57
56
  * `rules` lists every distinct `FindingCode` actually present in this run,
58
- * sorted: not the full `FindingCode` union. A SARIF consumer treats the
59
- * rules array as "what this tool reported", and advertising rules that
60
- * produced no result makes a clean run look like it has unexplained silent
61
- * rules. `results` preserves Finding Model's own order, which a caller wanting
57
+ * sorted: not the full `FindingCode` union. A SARIF consumer reads the rules
58
+ * array as "what this tool reported". Rules with no result would make a clean
59
+ * run look like it has unexplained silent rules. `results` preserves Finding Model's own order, which a caller wanting
62
60
  * a different one sorts themselves.
63
61
  */
64
62
  export declare function buildSarifLog(findingModel: FindingModel): SarifLog;
@@ -1 +1 @@
1
- {"version":3,"file":"sarif.d.ts","sourceRoot":"","sources":["../../../src/build/sarif.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAW,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAI/D,uEAAuE;AACvE,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;AAOvD,UAAU,aAAa;IACrB,QAAQ,CAAC,gBAAgB,EAAE;QACzB,QAAQ,CAAC,gBAAgB,EAAE;YAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;QACnD,QAAQ,CAAC,MAAM,CAAC,EAAE;YAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAA;KAC/E,CAAA;CACF;AAsCD,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;CAC9C;AAED,iHAAiH;AACjH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS;QACtB,QAAQ,CAAC,IAAI,EAAE;YACb,QAAQ,CAAC,MAAM,EAAE;gBACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBACrB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;gBAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBACxB,QAAQ,CAAC,KAAK,EAAE,SAAS;oBAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;iBAAE,EAAE,CAAA;aACnD,CAAA;SACF,CAAA;QACD,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;KACzC,EAAE,CAAA;CACJ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,YAAY,GAAG,QAAQ,CAgClE"}
1
+ {"version":3,"file":"sarif.d.ts","sourceRoot":"","sources":["../../../src/build/sarif.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAW,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAI/D,uEAAuE;AACvE,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;AAOvD,UAAU,aAAa;IACrB,QAAQ,CAAC,gBAAgB,EAAE;QACzB,QAAQ,CAAC,gBAAgB,EAAE;YAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;QACnD,QAAQ,CAAC,MAAM,CAAC,EAAE;YAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAA;KAC/E,CAAA;CACF;AAsCD,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;CAC9C;AAED,iHAAiH;AACjH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS;QACtB,QAAQ,CAAC,IAAI,EAAE;YACb,QAAQ,CAAC,MAAM,EAAE;gBACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBACrB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;gBAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBACxB,QAAQ,CAAC,KAAK,EAAE,SAAS;oBAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;iBAAE,EAAE,CAAA;aACnD,CAAA;SACF,CAAA;QACD,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;KACzC,EAAE,CAAA;CACJ;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,YAAY,GAAG,QAAQ,CAgClE"}
@@ -15,10 +15,9 @@ export interface SourcePosition {
15
15
  }
16
16
  /**
17
17
  * `node`'s starting line/column within `sourceFile`, both 1-indexed: TypeScript's own
18
- * `getLineAndCharacterOfPosition()` returns 0-indexed values for both. Callers combine this with
19
- * the file path they already have in scope to build a full {@link SourcePosition}; this returns
20
- * only the two numbers so it's usable identically whether the caller's `file` is already
21
- * root-relative or still absolute.
18
+ * `getLineAndCharacterOfPosition()` returns 0-indexed values for both. Callers add the file path
19
+ * they have in scope to build a full {@link SourcePosition}. Returning only the two numbers keeps
20
+ * it usable whether that path is root-relative or absolute.
22
21
  */
23
22
  export declare function positionOf(sourceFile: ts.SourceFile, node: ts.Node): {
24
23
  line: number;
@@ -27,28 +26,26 @@ export declare function positionOf(sourceFile: ts.SourceFile, node: ts.Node): {
27
26
  /**
28
27
  * Parses a developer-supplied `"<relative-path>:<line>:<column>"` citation
29
28
  * (a {@link runtime.VariableEvidenceDocs.dynamicAccess} entry) into a
30
- * {@link SourcePosition}. Splits on the *last* two colons so a path
31
- * containing colons of its own (rare, but not impossible) still parses:
32
- * only the trailing `:<line>:<column>` is treated as position syntax.
33
- * Returns `undefined` for anything that isn't exactly that shape (missing
34
- * segments, a non-positive-integer line/column, an empty path): callers
35
- * treat that as a malformed citation, never a thrown error. See ADR 0037.
29
+ * {@link SourcePosition}. Splits on the *last* two colons, so a path that
30
+ * contains colons still parses. Only the trailing `:<line>:<column>` is
31
+ * position syntax. Returns `undefined` for any other shape: missing segments,
32
+ * a line or column that is not a positive integer, or an empty path. Callers
33
+ * treat that as a malformed citation, not a thrown error. See ADR 0037.
36
34
  */
37
35
  export declare function parsePositionCitation(citation: string): SourcePosition | undefined;
38
36
  /**
39
37
  * One developer-declared {@link runtime.VariableEvidenceDocs.dynamicAccess} citation's
40
- * current acknowledgment state: a claim, never an observation. Kept fully
41
- * separate from `VariableAccessStatus` (which stays exactly 3-valued and
42
- * purely AST-derived) so a developer's assertion can never make env-cap
43
- * claim it observed something it didn't. See
38
+ * current acknowledgment state: a claim, never an observation. It stays
39
+ * separate from `VariableAccessStatus`, which is 3-valued and AST-derived only.
40
+ * So a developer's assertion can never make env-cap claim an observation it
41
+ * did not make. See
44
42
  * `evidence-snapshot.ts`'s `computeDynamicAccessAcknowledgments()` (where
45
43
  * this is computed) and ADR 0037.
46
44
  */
47
45
  export interface DynamicAccessAssertion extends SourcePosition {
48
46
  /**
49
- * `"fresh"`: the cited file currently exists and either matches the
50
- * committed baseline hash or has no baseline yet (a brand-new citation,
51
- * nothing to contradict it yet). `"stale"`: the cited file exists but its
47
+ * `"fresh"`: the cited file exists and matches the committed baseline
48
+ * hash, or has no baseline yet (a new citation). `"stale"`: the cited file exists but its
52
49
  * content has changed since the committed baseline. `"missing"`: the
53
50
  * cited file no longer exists at all. Re-derived from scratch every run;
54
51
  * never cached across runs.
@@ -1 +1 @@
1
- {"version":3,"file":"source-position.d.ts","sourceRoot":"","sources":["../../../src/build/source-position.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,IAAI,EAAE,EAAE,CAAC,IAAI,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAGlC;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAQlF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAA;IACtD;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;CACzC"}
1
+ {"version":3,"file":"source-position.d.ts","sourceRoot":"","sources":["../../../src/build/source-position.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,IAAI,EAAE,EAAE,CAAC,IAAI,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAGlC;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAQlF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAA;IACtD;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;CACzC"}
@@ -12,9 +12,9 @@ export interface OwnershipDependencyEntry {
12
12
  readonly owner: string | undefined;
13
13
  /** Number of variables declared in this contract's schema. */
14
14
  readonly variableCount: number;
15
- /** Files coupled to this contract (imported it, referenced it, or read a
16
- * member from it): contract-level "who depends on this," NOT proof any
17
- * specific variable was read. Blast radius if this contract changes is
15
+ /** Files coupled to this contract: they import it, reference it, or read a
16
+ * member from it. This answers "who depends on this" per contract; it does
17
+ * not prove any variable was read. Blast radius if this contract changes is
18
18
  * `consumers.length`, computed by callers/renderers on demand rather than
19
19
  * stored redundantly here. */
20
20
  readonly consumers: readonly string[];
@@ -52,7 +52,7 @@ export interface UnconsumedOwnedVariableFinding {
52
52
  * claimed otherwise. A non-empty list means someone specifically claimed
53
53
  * dynamic access here once, and that claim can no longer be verified. That
54
54
  * is worth a human check before deleting, not a stronger reason to trust
55
- * "unconsumed." The list holds the raw citations, not a collapsed
55
+ * "unconsumed". The list holds the raw citations, not a collapsed
56
56
  * `high`/`low` label, matching this codebase's "show the receipt" pattern
57
57
  * (ADR 0036/0037). A reader can judge confidence from the actual evidence
58
58
  * rather than trusting a derived summary. See ADR 0038.
@@ -72,7 +72,7 @@ export interface IndeterminateOwnershipFinding {
72
72
  /** See {@link UnconsumedOwnedVariableFinding.staleOrMissingCitations}. */
73
73
  readonly staleOrMissingCitations: readonly DynamicAccessCitationProblem[];
74
74
  }
75
- /** A variable that would otherwise be reported `unconsumedOwnedVariables`/`indeterminate`, but has at least one `"fresh"` developer-declared `dynamicAccess` citation: the raw static status is always shown alongside the assertion, never replaced by it. See ADR 0037. */
75
+ /** A variable that would otherwise be reported `unconsumedOwnedVariables`/`indeterminate` but has at least one `"fresh"` developer-declared `dynamicAccess` citation. The raw static status is shown beside the assertion, never replaced by it. See ADR 0037. */
76
76
  export interface AssertedDynamicAccessFinding {
77
77
  /** Resolved display name (see {@link DiscoveredContract.contractName}). */
78
78
  readonly contractName: string;
@@ -84,10 +84,9 @@ export interface AssertedDynamicAccessFinding {
84
84
  readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
85
85
  }
86
86
  /** Everything {@link renderUsageReport} needs to render the Dependency &
87
- * Ownership Report: deliberately independent of (not derived from)
88
- * `GenerateUsageReportResult` in `generate-usage.js`, the same way
89
- * `RenderDocsOptions` in `docs.ts` doesn't derive from
90
- * `GenerateDocumentationResult`. `generate-usage.ts` composes its own
87
+ * Ownership Report. It is not derived from `GenerateUsageReportResult` in
88
+ * `generate-usage.js`, as `RenderDocsOptions` in `docs.ts` is not derived
89
+ * from `GenerateDocumentationResult`. `generate-usage.ts` composes its own
91
90
  * public result type from these building blocks instead, keeping this
92
91
  * renderer module importable without its orchestrator. */
93
92
  export interface RenderUsageReportOptions {
@@ -105,20 +104,20 @@ export interface RenderUsageReportOptions {
105
104
  readonly indeterminate: readonly IndeterminateOwnershipFinding[];
106
105
  /** Variables a developer has re-acknowledged via `dynamicAccess`, freshly: see ADR 0037. */
107
106
  readonly asserted: readonly AssertedDynamicAccessFinding[];
108
- /** Schema-discovery parse warnings plus, since ADR 0014, any `packages`
109
- * resolution failures: surfaced here too (not just from
110
- * `generateEnvManifest`/`generateDocumentation`) so a team relying only
111
- * on `--ownership` output still learns when a cross-package contract
112
- * failed to resolve. */
107
+ /** Schema-discovery parse warnings plus any `packages` resolution failures
108
+ * (ADR 0014). They appear here as well as in
109
+ * `generateEnvManifest`/`generateDocumentation`, so a team that reads only
110
+ * this report still learns when a cross-package contract failed to
111
+ * resolve. */
113
112
  readonly parseWarnings: readonly ParseWarning[];
114
113
  /** Every surface actually scanned for usage: see ADR 0036. Named explicitly next to `unconsumedOwnedVariables` so "no consumer found" is never read as a stronger claim than what was actually searched. */
115
114
  readonly scannedSurfaces: readonly ScannedSurface[];
116
115
  }
117
116
  /**
118
117
  * Renders the Dependency & Ownership Report: who owns each variable, which
119
- * features consume each contract, and what the blast radius is if it
120
- * changes; structured around exactly those three questions, never generic
121
- * "dead code"/"unused symbol" language.
118
+ * features consume each contract, and the blast radius of a change. It
119
+ * answers those three questions, never in generic "dead code" or "unused
120
+ * symbol" terms.
122
121
  */
123
122
  export declare function renderUsageReport(computed: RenderUsageReportOptions): string;
124
123
  //# sourceMappingURL=usage-report.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"usage-report.d.ts","sourceRoot":"","sources":["../../../src/build/usage-report.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"usage-report.d.ts","sourceRoot":"","sources":["../../../src/build/usage-report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAA;AAO9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAElF,uFAAuF;AACvF,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B;;;;mCAI+B;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CACtC;AAED,oEAAoE;AACpE,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AACD,+GAA+G;AAC/G,MAAM,WAAW,yBAAyB;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AACD,0EAA0E;AAC1E,MAAM,WAAW,8BAA8B;IAC7C,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,uBAAuB,EAAE,SAAS,4BAA4B,EAAE,CAAA;CAC1E;AACD,8GAA8G;AAC9G,MAAM,WAAW,6BAA6B;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,yFAAyF;IACzF,QAAQ,CAAC,kBAAkB,EAAE,SAAS,cAAc,EAAE,CAAA;IACtD,0EAA0E;IAC1E,QAAQ,CAAC,uBAAuB,EAAE,SAAS,4BAA4B,EAAE,CAAA;CAC1E;AACD,kQAAkQ;AAClQ,MAAM,WAAW,4BAA4B;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,wEAAwE;IACxE,QAAQ,CAAC,aAAa,EAAE,YAAY,GAAG,eAAe,CAAA;IACtD,kFAAkF;IAClF,QAAQ,CAAC,uBAAuB,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACpE;AAED;;;;;2DAK2D;AAC3D,MAAM,WAAW,wBAAwB;IACvC,qDAAqD;IACrD,QAAQ,CAAC,mBAAmB,EAAE,SAAS,wBAAwB,EAAE,CAAA;IACjE,mEAAmE;IACnE,QAAQ,CAAC,kBAAkB,EAAE,SAAS,wBAAwB,EAAE,CAAA;IAChE;;sCAEkC;IAClC,QAAQ,CAAC,mBAAmB,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAClE,wEAAwE;IACxE,QAAQ,CAAC,wBAAwB,EAAE,SAAS,8BAA8B,EAAE,CAAA;IAC5E,sEAAsE;IACtE,QAAQ,CAAC,aAAa,EAAE,SAAS,6BAA6B,EAAE,CAAA;IAChE,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,EAAE,SAAS,4BAA4B,EAAE,CAAA;IAC1D;;;;mBAIe;IACf,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/C,4MAA4M;IAC5M,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAA;CACpD;AAsJD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,MAAM,CAuB5E"}
@@ -1 +1 @@
1
- {"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../../src/cli/filesystem.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,eAAe,EAAc,MAAM,mBAAmB,CAAA;AAiDjF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAO9B,CAAA"}
1
+ {"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../../src/cli/filesystem.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,eAAe,EAAc,MAAM,mBAAmB,CAAA;AAgDjF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAO9B,CAAA"}
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Matching of the plugin's `allow` options against the file a rule is checking. The behavior lives in
3
- * `../_ipc/glob.ts`, a managed copy of internal-package-contract's `runtime/glob.ts`: a pattern written relative to
4
- * the working directory (`src/cli/**`) matches the absolute path ESLint passes, on Windows too.
3
+ * `../_ipc/glob.ts`, a managed copy of `runtime/glob.ts` from internal-package-contract. A pattern written
4
+ * relative to the working directory (`src/cli/**`) matches the absolute path ESLint passes, on Windows too.
5
5
  */
6
6
  export { matchesAllowList } from "../_ipc/glob.js";
7
7
  //# sourceMappingURL=glob.d.ts.map
@@ -3,7 +3,8 @@
3
3
  *
4
4
  * `no-raw-process-env` flags direct `process.env` reads outside `env.schema.ts` files. `no-node-fs` flags
5
5
  * `node:fs` imports in library code, which should take its file system from the caller. The plugin runs
6
- * inside the project's own ESLint; CI runs the rules on ESLint 10 only.
6
+ * inside the project's ESLint. The `eslint-compat` CI job tests it on the lowest and newest release of each
7
+ * ESLint major in the peer range.
7
8
  *
8
9
  * @packageDocumentation
9
10
  */