@maverickcer/env-cap 0.6.0 → 0.7.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 (136) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +438 -0
  4. package/CODE_OF_CONDUCT.md +124 -0
  5. package/CODE_REVIEW.md +200 -0
  6. package/CONTRIBUTING.md +131 -0
  7. package/GUIDE.md +1214 -0
  8. package/PROMPT.md +89 -0
  9. package/README.md +92 -200
  10. package/RELEASING.md +160 -0
  11. package/SECURITY.md +270 -0
  12. package/SUPPORT.md +76 -0
  13. package/VERSIONING.md +118 -0
  14. package/benchmarks/READING-BENCHMARKS.md +197 -0
  15. package/benchmarks/README.md +126 -0
  16. package/benchmarks/WRITING-BENCHMARKS.md +252 -0
  17. package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
  18. package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
  19. package/dist/.dts/_ipc/build-fs.d.ts +53 -0
  20. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
  21. package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
  22. package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
  23. package/dist/.dts/_ipc/display-path.d.ts +27 -0
  24. package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
  25. package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
  26. package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
  27. package/dist/.dts/_ipc/glob.d.ts +22 -0
  28. package/dist/.dts/_ipc/glob.d.ts.map +1 -0
  29. package/dist/.dts/_ipc/no-node-fs.d.ts +34 -0
  30. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
  31. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  32. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  33. package/dist/.dts/_ipc/typescript.d.ts +20 -0
  34. package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
  35. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  36. package/dist/.dts/build/compiler-api.d.ts +3 -6
  37. package/dist/.dts/build/compiler-api.d.ts.map +1 -1
  38. package/dist/.dts/build/display-path.d.ts +3 -21
  39. package/dist/.dts/build/display-path.d.ts.map +1 -1
  40. package/dist/.dts/build/generated-banner.d.ts +21 -42
  41. package/dist/.dts/build/generated-banner.d.ts.map +1 -1
  42. package/dist/.dts/build/glob.d.ts +3 -15
  43. package/dist/.dts/build/glob.d.ts.map +1 -1
  44. package/dist/.dts/build/link.d.ts.map +1 -1
  45. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  46. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  47. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
  48. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  49. package/dist/.dts/build/types.d.ts +4 -53
  50. package/dist/.dts/build/types.d.ts.map +1 -1
  51. package/dist/.dts/build/typescript.d.ts +3 -17
  52. package/dist/.dts/build/typescript.d.ts.map +1 -1
  53. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  54. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  55. package/dist/.dts/eslint-plugin/index.d.ts +1 -1
  56. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  57. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  58. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  59. package/dist/{build-H4KFV44Z.js → build-WKDIAWF7.js} +198 -60
  60. package/dist/build-WKDIAWF7.js.map +1 -0
  61. package/dist/build.cjs +194 -56
  62. package/dist/build.cjs.map +1 -1
  63. package/dist/build.js +194 -56
  64. package/dist/build.js.map +1 -1
  65. package/dist/{chunk-7GVPOHDU.js → chunk-KEGYUHBU.js} +2 -2
  66. package/dist/cli/index.js +36 -29
  67. package/dist/cli/index.js.map +1 -1
  68. package/dist/eslint-plugin/index.cjs +84 -54
  69. package/dist/eslint-plugin/index.cjs.map +1 -1
  70. package/dist/eslint-plugin/index.js +83 -53
  71. package/dist/eslint-plugin/index.js.map +1 -1
  72. package/examples/README.md +95 -0
  73. package/package.json +48 -14
  74. package/skills/env-cap/SKILL.md +91 -0
  75. package/skills/env-cap/references/api.md +220 -0
  76. package/specs/architecture.md +634 -0
  77. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  78. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  79. package/specs/decisions/0003-no-global-env-object.md +172 -0
  80. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  81. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  82. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  83. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  84. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  85. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  86. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  87. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  88. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  89. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  90. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  91. package/specs/decisions/0015-security-backport-window.md +60 -0
  92. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  93. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  94. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  95. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  96. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  97. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  98. package/specs/decisions/0022-validation-contexts.md +267 -0
  99. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  100. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  101. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  102. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  103. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  104. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  105. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  106. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  107. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  108. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  109. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  110. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  111. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  112. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  113. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  114. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  115. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  116. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  117. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  118. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  119. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  120. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  121. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  122. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  123. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  124. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  125. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  126. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  127. package/specs/generated-artifacts.md +104 -0
  128. package/specs/migrations/README.md +30 -0
  129. package/specs/migrations/from-centralized-schema.md +503 -0
  130. package/specs/migrations/from-dotenv.md +352 -0
  131. package/specs/migrations/from-envalid.md +482 -0
  132. package/specs/migrations/from-process-env.md +398 -0
  133. package/specs/migrations/from-t3-env.md +416 -0
  134. package/specs/migrations/from-zod.md +303 -0
  135. package/dist/build-H4KFV44Z.js.map +0 -1
  136. /package/dist/{chunk-7GVPOHDU.js.map → chunk-KEGYUHBU.js.map} +0 -0
@@ -0,0 +1,182 @@
1
+ # 0023: TypeScript Path-Alias Resolution, On By Default
2
+
3
+ ## Status
4
+
5
+ Proposed / **Experimental** (see [`VERSIONING.md`](../../VERSIONING.md)). Implemented in:
6
+
7
+ - `src/build/resolve-tsconfig-paths.ts`
8
+ - `src/build/resolve-import.ts` (`resolveImportSpecifier`, `ImportResolutionContext`)
9
+ - `src/build/generate-manifest.ts`, `generate-documentation.ts`, `generate-usage.ts`,
10
+ `generate-env-artifacts.ts` (the `tsconfig` option)
11
+ - `src/cli/index.ts` (`--tsconfig`/`--no-tsconfig`)
12
+
13
+ The `tsconfig` option and the resolution behavior it controls are Experimental: they may
14
+ still change shape in a minor release without that being a semver violation, following the
15
+ same policy `packages` (ADR 0014) shipped under.
16
+
17
+ ## Context
18
+
19
+ Every cross-file link this project computes -- `link.ts`'s `createEnv()`/`documentEnv()`
20
+ linking, and `dependency-graph.ts`'s usage/ownership scan -- funnels through one
21
+ resolution chokepoint, `resolveImportSpecifier()`. Until this decision, it recognized only
22
+ two specifier shapes: relative (`./foo`, `../foo`, via `resolveRelativeImport()`), and a
23
+ bare specifier matching an explicit `packages` allowlist (ADR 0014, via
24
+ `resolvePackageImport()`). Any other bare specifier -- critically, a **TypeScript path
25
+ alias** (`"@/lib/env"`, `"~/schema/env"`), configured via a project's own `tsconfig.json`
26
+ `compilerOptions.paths`/`baseUrl` and extremely common in real-world TypeScript
27
+ projects -- fell through both and returned `undefined`. `resolveRelativeImport()`'s own
28
+ doc comment said as much: a bare specifier is treated as "couldn't statically link," and
29
+ the caller warns rather than guesses.
30
+
31
+ The concrete cost: a `documentEnv()` call whose schema reference is imported via an alias
32
+ became an `unresolvedLinks` entry instead of a linked contract. A `createEnv()` contract
33
+ only ever consumed through an alias import was misreported as `abandoned` -- never
34
+ imported anywhere -- by `deriveOwnershipFindings()`, or produced a false-positive
35
+ `unconsumedOwnedVariables` finding. Both are exactly the class of wrong finding ADR 0010's
36
+ ownership engine exists to never produce, and for any project organizing its own source
37
+ with aliases (a majority of real-world TypeScript codebases), the Dependency & Ownership
38
+ Report -- this project's core "who owns this, who depends on it" answer -- was
39
+ systematically inaccurate.
40
+
41
+ ## Decision
42
+
43
+ 1. **On by default, unlike `packages`.** `generateEnvManifest`/`generateDocumentation`/
44
+ `generateUsageReport`/`generateEnvArtifacts` (and the CLI) auto-detect
45
+ `root/tsconfig.json` and use its `paths`/`baseUrl` for alias resolution with no
46
+ configuration required. This deliberately diverges from ADR 0014's opt-in posture: a
47
+ package crosses a real trust/versioning boundary into another package's `node_modules`
48
+ copy, but a project's own `tsconfig.json` only ever points at files already inside the
49
+ same, already-trusted local project -- there is no new boundary being crossed, so
50
+ opt-in would only mean silently wrong reports for every project that doesn't know to
51
+ ask for correctness. An explicit `tsconfig` option overrides the path (for monorepos
52
+ where the relevant config isn't at `root`), and `tsconfig: false` disables the
53
+ mechanism entirely (a CLI `--tsconfig <path>`/`--no-tsconfig` pair mirrors this).
54
+
55
+ 2. **Exactly `root/tsconfig.json`, never an upward directory walk.** Auto-detection does
56
+ _not_ use `ts.findConfigFile()` (which walks parent directories looking for the nearest
57
+ config) -- every other root-relative mechanism in this codebase (schema discovery,
58
+ `packages` resolution) treats `root` as a hard boundary, never searching above it. This
59
+ also matches `tsc -p <root>`'s behavior (an explicit project directory) rather than bare
60
+ `tsc`'s cwd-upward-walk default, which is the more apt comparison here since `root` is
61
+ always an explicit, caller-supplied directory, never an implicit cwd. Walking upward
62
+ could silently pick up an unrelated ancestor tsconfig in a monorepo.
63
+
64
+ 3. **The alias-matching algorithm is delegated entirely to the TypeScript compiler.**
65
+ `ts.readConfigFile()` + `ts.parseJsonConfigFileContent()` load the config (handling
66
+ JSONC and `extends`-chain merging for free -- neither exists anywhere else in this
67
+ codebase), and `ts.resolveModuleName()` -- the same function `tsc`/`tsserver` themselves
68
+ call -- does the actual longest-prefix `paths` matching, `*` wildcard substitution,
69
+ multiple-fallback-target resolution, and `baseUrl` fallback. This avoids reimplementing
70
+ a solved algorithm with new bug surface; the net-new code in
71
+ `resolve-tsconfig-paths.ts` is limited to loading config, caching, and enforcing the
72
+ safety boundary below. `ts.sys` is used directly as the resolution host (an existing
73
+ Node-backed singleton). This call is necessarily synchronous -- `ts.resolveModuleName()`
74
+ has no async form.
75
+
76
+ 4. **The gate for building a resolution is "`paths` non-empty OR `baseUrl` set,"
77
+ not `paths` alone.** A `baseUrl`-only tsconfig (no `paths` at all) still makes
78
+ TypeScript resolve bare specifiers relative to `baseUrl` (e.g. `import "./src/env/schema"`), and `ts.resolveModuleName()` already handles that once
79
+ `compilerOptions.baseUrl` is passed through -- gating on `paths` alone would silently
80
+ drop this real, common case.
81
+
82
+ 5. **Never resolves into `node_modules`.** `ts.resolveModuleName()` can, in principle, fall
83
+ through to classic Node resolution and land inside `node_modules`. Any resolved path
84
+ containing a `node_modules` path segment (checked after `path.normalize()`, so mixed
85
+ separators can't slip past it on Windows) is discarded. Bare package specifiers continue
86
+ to be handled exclusively by `resolvePackageImport()` (ADR 0014) -- this mechanism never
87
+ overlaps with that trust boundary, and this codebase's cross-package discovery keeps its
88
+ existing explicit-allowlist requirement unchanged.
89
+
90
+ 6. **`.ts`/`.tsx` only, matching `resolveRelativeImport()`'s and
91
+ `resolve-package-schema.ts`'s existing scope.** A resolved non-`.ts`/`.tsx` file is
92
+ discarded, not merely deprioritized. This is not a new restriction unique to aliases --
93
+ every static-analysis entry point in this codebase is `.ts`/`.tsx`-only today -- and it
94
+ is a real safety property, not just a scope boundary: feeding a resolved `.json` or
95
+ other non-source file straight into `ts.createSourceFile()` wouldn't error, it would
96
+ silently parse garbage, which is exactly the "guess" this codebase's warn-don't-guess
97
+ philosophy exists to avoid.
98
+
99
+ 7. **`resolveImportSpecifier()`'s resolution order is relative → alias → package.** Alias
100
+ resolution runs before package resolution because it resolves the consuming project's
101
+ own local source (already-trusted, no versioning boundary) -- the same precedence
102
+ relative resolution already has over package resolution. Wiring this into
103
+ `dependency-graph.ts` (not just `link.ts`) is load-bearing, not optional, for the same
104
+ reason ADR 0014 called out for `packages`: without it, a contract's consumer reached
105
+ only through an alias could never resolve, and the contract would be misreported as
106
+ `abandoned`.
107
+
108
+ 8. **Failures become one `ParseWarning`, never a throw.** `loadTsconfigPaths()` is called
109
+ exactly once per `generate*()`/`computeArtifacts()` invocation -- the same point
110
+ `resolveAllowlistedPackages()` is already called once -- so at most one tsconfig-related
111
+ warning is ever produced per run, never once per file scanned. A missing _default_
112
+ `tsconfig.json` is silent (most projects don't use aliases, and this must not be noisy);
113
+ a missing _explicit_ `tsconfig` path, or malformed JSON, is a real misconfiguration and
114
+ warns.
115
+
116
+ ### Explicit scope boundaries
117
+
118
+ - **Project references are not followed.** `env-cap` analyzes one configured project root
119
+ at a time, with one fixed `compilerOptions` object regardless of which file is importing.
120
+ Traversing referenced projects would require resolving and merging multiple
121
+ `compilerOptions` sets and would materially expand analysis scope -- it deserves its own
122
+ ADR if ever pursued, not a silent extension of this one.
123
+ - **`jsconfig.json` is not auto-detected.** `env-cap` analyzes TypeScript projects today; a
124
+ `jsconfig.json`-based (JS + `checkJs`) project is a distinct, unhandled case elsewhere in
125
+ this codebase too. A project can still opt in today via an explicit
126
+ `tsconfig: "jsconfig.json"` override -- the loader only cares about the file's JSON
127
+ shape, not its name -- and native auto-detection of `jsconfig.json` alongside
128
+ `tsconfig.json` could be added later without an API change.
129
+ - **This does not reopen ADR 0010's or ADR 0014's boundaries.** Alias resolution only
130
+ changes how a specifier already reachable from the consuming project's own scanned
131
+ source resolves -- it does not walk an allow-listed package's own `node_modules` copy to
132
+ verify what that package's internal source consumes, and it does not recurse into that
133
+ package's own dependencies. That remains explicitly out of scope; see ADR 0014's own
134
+ "Alternatives considered" (which already rejected following a package's internal
135
+ re-export chain as scope creep) and ADR 0010's "never reaches `node_modules`" boundary
136
+ for the dependency-ownership engine.
137
+
138
+ ## Consequences
139
+
140
+ - A project organizing its own source with `tsconfig.json` path aliases now gets an
141
+ accurate Dependency & Ownership Report, manifest, and docs Catalog with zero
142
+ configuration -- the common case just works, matching `tsc`'s own behavior.
143
+ - `env-cap` gains its first resolution mechanism that is on by default rather than
144
+ explicitly opted into, a deliberate departure from ADR 0014's precedent, justified by the
145
+ different trust posture (no new boundary crossed) documented in Decision 1 above.
146
+ - A monorepo whose relevant `tsconfig.json` isn't at `root` needs an explicit `tsconfig`
147
+ override to benefit; without one, alias imports in that project silently continue to
148
+ behave as before this decision (an `unresolvedLinks`/`abandoned` finding), not
149
+ differently -- there is no regression, only a missed opportunity until configured.
150
+ - The `typescript` package (already a peer dependency, used elsewhere in this codebase only
151
+ for AST walking) is now also used for its config-loading and module-resolution APIs, a
152
+ new but well-precedented use of an existing dependency.
153
+
154
+ ## Alternatives considered
155
+
156
+ - **Hand-rolled longest-prefix `paths` matcher.** Rejected -- reimplements an algorithm
157
+ TypeScript itself already gets right (wildcard substitution, multiple fallback targets,
158
+ `extends` merging), with strictly more bug surface and no offsetting benefit.
159
+ - **`ts.findConfigFile()`'s upward directory walk**, matching bare `tsc`'s default
160
+ behavior. Rejected -- breaks with `root`'s existing hard-boundary role everywhere else in
161
+ this codebase (schema discovery, `packages` resolution) and could silently pick up an
162
+ unrelated ancestor tsconfig in a monorepo. `tsc -p <root>`'s explicit-directory behavior
163
+ is the closer analog anyway, since `root` is always caller-supplied, never an implicit
164
+ cwd.
165
+ - **Opt-in only, mirroring `packages` (ADR 0014).** Rejected -- `packages`' opt-in
166
+ requirement exists because it crosses a real trust/versioning boundary into another
167
+ package's `node_modules` copy; a project's own `tsconfig.json` paths never cross that
168
+ boundary, so opt-in would only cost every unconfigured project a wrong report for no
169
+ corresponding safety benefit.
170
+ - **Traversing into an allow-listed package's own `node_modules` copy to verify its
171
+ internal consumption of its own declared schema, recursively into its own
172
+ dependencies.** Rejected as out of scope for this decision -- it would reopen ADR 0010's
173
+ "never reaches `node_modules`" boundary and reverse the alternative ADR 0014 already
174
+ rejected ("follow a package's internal re-export chain... rejected as scope creep").
175
+ Recursing into nested dependencies would multiply that trust-surface expansion further.
176
+ If ever pursued, it is a materially larger, separate feature deserving its own ADR and
177
+ its own security review.
178
+ - **Widening resolution past `.ts`/`.tsx` (e.g. `.mts`/`.cts`/`.js`) specifically for the
179
+ alias path.** Rejected -- would introduce a new asymmetry against `resolveRelativeImport()`'s
180
+ and `resolve-package-schema.ts`'s existing `.ts`/`.tsx`-only scope. Widening the whole
181
+ codebase's static-analysis scope to more extensions is a legitimate future enhancement,
182
+ but it isn't specific to aliases and belongs in its own change.
@@ -0,0 +1,144 @@
1
+ # 0024: Seven canonical fact models, not thirty-five reports
2
+
3
+ ## Status
4
+
5
+ Accepted. This ADR establishes the architecture and shared conventions that
6
+ ADRs 0025 through 0032 (and the implementation phases between them) apply
7
+ incrementally, one additive change at a time. It documents no code of its
8
+ own.
9
+
10
+ ## Context
11
+
12
+ A readiness review of 35 requested report types for env-cap (Configuration
13
+ Ownership Report, Secret Exposure Report, SARIF Security Findings Report,
14
+ and so on) found that most of them are different renderings of a small,
15
+ repeated set of underlying facts, not 35 independent analyses. The clearest
16
+ existing symptom is already in this codebase: `docs.ts`'s
17
+ `renderSecurityReview()` computes counters like `noOwnerCount`,
18
+ `duplicateKeyCount`, and `expiredCount` as plain `let`s inside one function,
19
+ and those numbers become Markdown text and nothing else -- no exported type
20
+ backs them, so no downstream consumer (the `--json` envelope, a CI gate, a
21
+ future SARIF renderer) can ever see them as data. A second, independent
22
+ symptom of the same root cause: `usage-report.ts`'s ownership findings and
23
+ `docs.ts`'s `effectiveOwner()` resolve "who owns this variable" two
24
+ different ways (one checks only the contract-level `owner`, the other
25
+ correctly falls back variable-then-contract) -- because ownership resolution
26
+ was written twice, once per report, instead of once as a fact.
27
+
28
+ The review also found a specific, named gap blocking an entire cluster of
29
+ requested reports: no field anywhere in env-cap's vocabulary (`EnvDefinition`,
30
+ `VariableDocs`, `ContractDocs`) distinguishes a secret from an ordinary
31
+ config value. Every report about exposure, secret rotation hygiene, or
32
+ security findings has no data to work from until that's fixed at the source.
33
+
34
+ Building the 35 (or a trimmed 19) requested reports one at a time, as
35
+ independent renderers or as incremental fields bolted onto existing report
36
+ functions, repeats this exact pattern at larger scale: more places
37
+ recomputing the same facts, more chances for two of them to quietly
38
+ disagree, as `usage-report.ts` and `docs.ts` already do today.
39
+
40
+ ## Decision
41
+
42
+ **Seven canonical, versioned, JSON-serializable fact models become the real
43
+ API surface: Contract, Dependency, Ownership, Lifecycle, Finding, Change,
44
+ Evidence.** Every report is a projection over one or more of these models,
45
+ built through a single public projection function
46
+ (`defineEvidenceProjection()`, ADR 0031), never a second, independently
47
+ computed source of truth. Facts belong in a model; judgment (what counts as
48
+ risky, what satisfies a compliance control) belongs in a projection,
49
+ never inside a model itself -- this is why Risk Report, Compliance Evidence
50
+ Report, and Environment/Executive Assurance Report are cut on principle, not
51
+ deferred: each requires an opinion env-cap has no basis to supply. The
52
+ mission this architecture serves: env-cap doesn't decide what compliance
53
+ means; it produces verifiable evidence from the configuration architecture,
54
+ and provides the machinery to transform that evidence into whatever
55
+ downstream standard a consumer requires.
56
+
57
+ Conventions every model-adding phase follows, so they don't get re-decided
58
+ per phase:
59
+
60
+ - **New model types are additive wrappers, never in-place rewrites.**
61
+ `DiscoveredContract`, `ManifestChangeReport`, `CompatibilityIssue`,
62
+ `OwnershipDependencyEntry`, and every other existing exported type stay
63
+ exactly as they are. Each canonical model is a new file that maps or
64
+ aggregates the existing pieces into a versioned shape. This is what keeps
65
+ every phase of this build-out additive-only, needing no major-version
66
+ discussion despite the scale of the overall change.
67
+ - **`schemaVersion` discipline, one constant per model.** Bumped only when a
68
+ reader could misinterpret the new shape -- the same rule
69
+ `MANIFEST_SNAPSHOT_SCHEMA_VERSION` (ADR 0021) and `JSON_SCHEMA_VERSION`
70
+ (ADR 0013) already document. A purely additive field never requires a
71
+ bump.
72
+ - **Provenance is caller-supplied, never ambient-detected.** Evidence
73
+ Model's commit-SHA/timestamp stamping (ADR 0031, ADR 0032) takes an
74
+ optional callback the same shape as ADR 0012's `LiveExpirationDates` --
75
+ env-cap never shells out to `git` itself, and an omitted callback means
76
+ omitted fields, never a guess. This mirrors the project's existing
77
+ invariant that nothing is ever inferred from an ambient signal (see the
78
+ validation-context rule in ADR 0022).
79
+ - **The published JSON Schema generator generalizes to one target per
80
+ model**, rather than staying hardcoded to the single `--json` envelope
81
+ type it covers today (ADR 0019). Each model phase adds one entry to that
82
+ generator's target list and one freshness+correctness test pair, instead
83
+ of inventing its own schema-publishing mechanism.
84
+ - **The ten first-party reference projections are ordinary
85
+ `defineEvidenceProjection()` calls, with no privileged internal path.** If
86
+ a reference projection needs something the public projection API can't
87
+ express, that's proof the API is incomplete, not license to give
88
+ first-party code special access the public surface lacks -- the same
89
+ discipline `specs/architecture.md` already applies to `src/cli/` importing
90
+ only `build`'s public surface, never an internal file.
91
+
92
+ Sequencing: Contract Model ships first, since it's the closest of the seven
93
+ to already existing and because Finding Model's secret-specific facts are
94
+ blocked on its one missing field (`classification`). Finding Model ships
95
+ second because it's the most scattered of the seven today and is referenced,
96
+ directly or via Evidence Model, by most of what follows. Dependency,
97
+ Ownership, Lifecycle, and Change Model have no shape dependency on each
98
+ other and may ship in any order once Finding Model exists. Evidence Model
99
+ ships last, since it's defined as the composition of the other six -- built
100
+ before they're real would just produce an evidence artifact full of holes.
101
+
102
+ ## Consequences
103
+
104
+ - The package's public surface grows by roughly seven new Experimental-tier
105
+ types and one new public entry point (`./evidence`, ADR 0031) over the
106
+ course of this build-out, none of it replacing anything existing.
107
+ - `usage-report.ts`'s owner-resolution divergence from `docs.ts`'s
108
+ `effectiveOwner()` gets fixed as part of Ownership Model landing (a real
109
+ bug fix, bundled with -- not hidden inside -- that model's new type), since
110
+ the whole point of a canonical model is that a fact gets computed once.
111
+ - The ten reference projections replace the originally-requested 35/19
112
+ report list; several of the originally-requested reports turn out to be
113
+ the same projection viewed two ways (e.g. Configuration Consumer Report is
114
+ Configuration Dependency Report, inverted) and are folded in as filters
115
+ rather than shipped as separate artifacts.
116
+ - This is sized closer to the package's original build-out than to a
117
+ consistency pass. It lands as a long sequence of independently-mergeable,
118
+ independently-`npm run verify`-clean phases rather than one release, each
119
+ with its own changeset, so the scale of the overall change never forces a
120
+ single high-risk merge.
121
+
122
+ ## Alternatives considered
123
+
124
+ - **Ship the 35 (or 19) requested reports as independent renderers, one at
125
+ a time.** Rejected -- this is the exact pattern already producing
126
+ divergent bugs in this codebase (`usage-report.ts` vs. `docs.ts`'s owner
127
+ resolution) and would multiply, not fix, that risk at 35x the scale.
128
+ - **Add fields to existing report functions incrementally, without a
129
+ unifying model layer.** Rejected as indistinguishable in the long run
130
+ from the previous option -- `renderSecurityReview()` growing a 12th, 13th,
131
+ 14th inline counter is the same anti-pattern that motivated this ADR in
132
+ the first place, just deferred rather than fixed.
133
+ - **Ship opinionated compliance/risk/executive-assurance reports directly,
134
+ since the underlying facts already exist.** Rejected -- a risk weighting,
135
+ a named compliance framework's control language, and an executive
136
+ headline number are each an opinion env-cap has no basis to assert on a
137
+ consumer's behalf. The projection mechanism exists precisely so a
138
+ consumer can build these correctly, for their own policy, without
139
+ env-cap guessing.
140
+ - **Land this as one large release once everything is ready.** Rejected --
141
+ given the acknowledged size of this change, a single merge would be
142
+ effectively unreviewable and would leave the package in a broken
143
+ intermediate state for the duration of the work. Additive, independently
144
+ verifiable phases were chosen specifically to avoid that.
@@ -0,0 +1,105 @@
1
+ # 0025: The Contract Model is a new, versioned JSON projection, published alongside the manifest
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/build/contract-model.ts`, exported as
6
+ `buildContractModel()`/`ContractModel` from `@maverickcer/env-cap/build`. Its
7
+ JSON Schema is generated into `schemas/contract-model.schema.json` and
8
+ published at `@maverickcer/env-cap/schema/contract-model` (`scripts/generate-json-schema.mjs`,
9
+ generalized from ADR 0019's single-target script).
10
+
11
+ ## Context
12
+
13
+ ADR 0024 named the Contract Model as the closest of the seven canonical fact
14
+ models to already existing: `DiscoveredContract`/`DiscoveredVariable`
15
+ (`src/build/link.ts`) are already fact-shaped and exported. What's missing is
16
+ a JSON-serializable, versioned publication of that data -- today the only
17
+ generated artifact close to it is `env.manifest.ts` (`renderManifest()`),
18
+ which is deliberately metadata-free TS source (no `description`/`owner`/
19
+ AST facts, "no timestamps, no randomness," per its own docstring), and the
20
+ manifest change-report's sidecar snapshot (`manifest-snapshot.ts`), which is
21
+ JSON but deliberately scoped to _active_ contracts and _only_ the
22
+ `documentEnv()`-sourced fields (ADR 0021: "nothing schema- or processor-shaped
23
+ is in it"). Neither is a suitable Contract Model publication: a consumer
24
+ building a projection over "every declared variable's full contract" (its
25
+ processor/validator presence, its statically-resolved default, its
26
+ declaring contract's active status) has no single artifact to read.
27
+
28
+ ## Decision
29
+
30
+ **A new file, `src/build/contract-model.ts`, exporting `ContractModel`/
31
+ `ContractModelContract`/`ContractModelVariable` and `buildContractModel()`.**
32
+ Concretely:
33
+
34
+ - **A superset, not a replacement.** `ContractModel` carries every field
35
+ `DiscoveredContract`/`DiscoveredVariable` already have -- both the
36
+ `documentEnv()`-sourced fields the manifest snapshot already captures
37
+ (`description`, `owner`, `classification`, `expiresAt`,
38
+ `refreshInstructions`, `required`, `extra`) and the AST-derived schema
39
+ facts it deliberately excludes (`hasDefault`/`defaultValue`/`hasProcessor`/
40
+ `processorSource`/`processorReturnType`/`hasValidator`/`validatorSource`/
41
+ `context`). Both are load-bearing for what this model unblocks: Finding
42
+ Model needs `classification` for anything secret-specific, and a
43
+ completeness/inventory projection needs to know whether a variable has a
44
+ processor at all.
45
+ - **Every discovered contract, active or not.** Unlike the manifest
46
+ snapshot (scoped to active contracts, matching `renderManifest()`'s own
47
+ scope), `ContractModel` includes inactive contracts too, with `active:
48
+ boolean` carried through -- a report answering "what's declared, and is it
49
+ currently active" needs both states visible, not just the active half.
50
+ - **`schemaVersion`, same bump discipline as every other snapshot in this
51
+ codebase.** `CONTRACT_MODEL_SCHEMA_VERSION`, bumped only when a reader
52
+ could misinterpret the new shape, mirroring `MANIFEST_SNAPSHOT_SCHEMA_VERSION`
53
+ (ADR 0021) and `JSON_SCHEMA_VERSION` (ADR 0013).
54
+ - **Deterministic ordering.** Sorted by file, then exportName, then variable
55
+ key -- the same discipline `buildManifestSnapshot()` already follows, so
56
+ wherever this model is persisted, `JSON.stringify` output is stable and
57
+ diffs cleanly.
58
+ - **The JSON Schema generator generalizes to a `TARGETS` list, one entry per
59
+ published schema, rather than staying hardcoded to the single `--json`
60
+ envelope type ADR 0019 introduced it for.** Each target's own freshness
61
+ test (mirroring `test/build/json-schema.test.ts`) still fails the build if
62
+ its committed schema drifts from what `ts-json-schema-generator` would
63
+ produce fresh -- this generalization changes nothing about that guarantee,
64
+ it just lets a second (and future third, fourth, ...) type opt into it
65
+ without a second hand-copied script.
66
+ - **Published at `@maverickcer/env-cap/schema/contract-model`, via a new
67
+ wildcard `./schema/*` export**, alongside the existing bare `./schema`
68
+ (kept, unchanged, for the original `--json` envelope schema). A new fact
69
+ model's schema needs zero further `package.json` edits going forward --
70
+ it's picked up by the wildcard the moment its file lands in `schemas/`.
71
+
72
+ ## Consequences
73
+
74
+ - A consumer wanting the full declared-contract surface (for a custom
75
+ inventory report, a policy check, or feeding `defineEvidenceProjection()`
76
+ once it exists) has one artifact to read instead of reconstructing it by
77
+ combining the manifest snapshot with `linkFiles()`'s raw output themselves.
78
+ - `env.manifest.ts` and `manifest-snapshot.ts`'s `ManifestSnapshot` are
79
+ unchanged and keep their existing, narrower scopes -- this is additive,
80
+ not a consolidation. A project already depending on the snapshot's
81
+ active-only, metadata-only shape sees no behavior change.
82
+ - Two schema files now ship in `schemas/` (`env-cap-report.schema.json`,
83
+ `contract-model.schema.json`), both generated by the same script, both
84
+ covered by their own freshness + correctness tests.
85
+
86
+ ## Alternatives considered
87
+
88
+ - **Widen `ManifestSnapshot` itself to include AST facts and inactive
89
+ contracts, instead of a new type.** Rejected -- `ManifestSnapshot`'s scope
90
+ is deliberately narrow and already load-bearing for the manifest
91
+ change-report's diffing semantics (ADR 0021's "matches `renderManifest()`'s
92
+ own scope" reasoning). Widening it would change what "since last commit"
93
+ means for existing consumers of `ManifestChangeReport`, an unrelated
94
+ breaking change bundled into unrelated new scope.
95
+ - **Add a `--json`-only Contract Model, folded into the existing envelope
96
+ schema rather than published separately.** Rejected -- the whole point of
97
+ publishing a model-specific schema is that a consumer validating just a
98
+ `ContractModel` payload (e.g. from a future persisted Evidence Model slice)
99
+ shouldn't need to reference or strip away the unrelated `--json` envelope
100
+ fields (`docs`, `usage`, `checkResult`) that have nothing to do with the
101
+ Contract Model itself.
102
+ - **Keep the JSON Schema generator single-target and hand-copy it for each
103
+ new model.** Rejected -- this is exactly the "35 independently-maintained
104
+ analyses of the same underlying facts" anti-pattern ADR 0024 exists to
105
+ avoid, just at the tooling layer instead of the report layer.
@@ -0,0 +1,109 @@
1
+ # 0026: Finding Model unifies four independently-shaped finding families
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/build/finding-model.ts` (`buildFindingModel()`,
6
+ `Finding`, `FindingModel`) and `src/build/evidence-reference.ts`
7
+ (`EvidenceReference`), exported from `@maverickcer/env-cap/build`.
8
+
9
+ ## Context
10
+
11
+ ADR 0024 named Finding Model as the most scattered of the seven canonical
12
+ models. Four independently-shaped finding families exist in the public
13
+ surface today, with no shared base type: `CompatibilityIssue`
14
+ (`compatibility.ts`/`exclusive-group.ts` -- the only one with `severity`),
15
+ `ArtifactCheckFinding` (`check-artifacts.ts` -- a three-value `status`
16
+ instead of `severity`), `DocumentationFindings` (`generate-documentation.ts`
17
+ -- a container of five arrays, not itself a finding), and the four ownership
18
+ findings in `usage-report.ts` (`AbandonedContractFinding`,
19
+ `UnresolvedConsumerFinding`, `UnconsumedOwnedVariableFinding`,
20
+ `IndeterminateOwnershipFinding`). Only `CompatibilityIssue` has any
21
+ machine-readable identifier at all (`code`, optional, and as of ADR 0024's
22
+ Phase 4 work populated on every check in `compatibility.ts` -- but still
23
+ never set by `detectExclusiveGroupIssues()`). A consumer wanting "every
24
+ problem this run found" today has to know about, and separately merge,
25
+ four unrelated shapes.
26
+
27
+ ## Decision
28
+
29
+ **A new adapter, not a replacement.** `buildFindingModel()` maps the four
30
+ existing families into one canonical `Finding[]`/`FindingModel` shape.
31
+ Every existing exported type (`CompatibilityIssue`, `ArtifactCheckFinding`,
32
+ `DocumentationFindings`, the four ownership finding types) stays exactly as
33
+ it is -- this is purely additive, per ADR 0024's additive-wrapper
34
+ convention.
35
+
36
+ - **`code` is required on `Finding`, unlike the optional `CompatibilityIssue.code`
37
+ it's adapted from.** Verified this is safe: `CompatibilityIssue` and the
38
+ lower-level discovery/linking primitives are Experimental tier, not
39
+ Stable, per `VERSIONING.md` -- and the package is pre-1.0, where even the
40
+ Stable tier may change. Making `code` required on the _new_ canonical
41
+ type costs nothing against the _existing_ type, which is untouched. Every
42
+ source that doesn't naturally carry a code gets one synthesized here:
43
+ `detectExclusiveGroupIssues()`'s issues (never set one, by design -- ADR 0009) become `"exclusive-group-violation"`; `ArtifactCheckFinding`'s
44
+ `status` becomes `"artifact-stale"`/`"artifact-missing"`; each
45
+ `DocumentationFindings` array and each ownership finding type gets its own
46
+ code (`"undocumented-contract"`, `"abandoned-contract"`, etc.).
47
+ - **`location: EvidenceReference` is structured, never a formatted string.**
48
+ The exact hazard `CompatibilityIssue.code` itself once was (an
49
+ inconsistently-populated optional string) is avoided from the start here.
50
+ `EvidenceReference` is a discriminated union keyed by `model`, carrying
51
+ only as much identity as the source finding actually has -- `"contract"`
52
+ (file/exportName/variable, all optional, for `CompatibilityIssue`/
53
+ `DocumentationFindings`), `"ownership"` (contractName always present,
54
+ file/variable optional -- `usage-report.ts`'s finding types don't
55
+ consistently carry `file`+`exportName` together the way `DiscoveredContract`
56
+ does), and `"change"` (a generated artifact's `path`, for
57
+ `ArtifactCheckFinding` -- which isn't about a declared contract or
58
+ variable at all).
59
+ - **`EvidenceReference` ships with only the three `model` variants something
60
+ in this codebase actually needs today, not a speculative six-model union.**
61
+ The original audit sketched `EvidenceReference` as covering all seven
62
+ models; building `"dependency"`/`"lifecycle"`/`"finding"`/`"evidence"`
63
+ variants now, with no real finding or projector to populate them, would be
64
+ exactly the kind of premature generality this codebase avoids elsewhere.
65
+ The type is a plain discriminated union -- trivially extended with a new
66
+ variant once Phase 7+ (Dependency/Lifecycle Model) or Phase 13
67
+ (`defineEvidenceProjection()`'s auto-provenance tracking) has a real
68
+ consumer for one.
69
+ - **`family` is a coarser, four-value discriminant alongside `code`** --
70
+ `"compatibility"` | `"drift"` | `"documentation"` | `"ownership"` -- for a
71
+ consumer that wants "every documentation gap" without enumerating every
72
+ individual code.
73
+ - **`buildFindingModel()`'s input is a flat object of independently-optional
74
+ arrays/containers**, mirroring how `GenerateEnvArtifactsResult`'s own
75
+ `manifest`/`docs`/`usage` fields are each independently optional -- a
76
+ caller passes whatever it actually has (e.g. only `compatibilityIssues` if
77
+ it never ran a docs or usage pass).
78
+
79
+ ## Consequences
80
+
81
+ - A consumer building a unified findings view (cluster 3.3 in the original
82
+ report audit) can call `buildFindingModel()` once instead of merging four
83
+ shapes by hand.
84
+ - `EvidenceReference`'s `"ownership"` variant is keyed by `contractName`
85
+ rather than `file`+`exportName` together, unlike `"contract"` -- a
86
+ deliberate asymmetry reflecting what `usage-report.ts`'s finding types
87
+ actually carry, not an oversight to reconcile later.
88
+ - `ArtifactCheckFinding`'s `"ok"` entries never become a `Finding` --
89
+ `buildFindingModel()` only adapts what's actually wrong, consistent with
90
+ every other source family (an absence of a finding already means "nothing
91
+ to report" everywhere else in this model).
92
+
93
+ ## Alternatives considered
94
+
95
+ - **Make `EvidenceReference` a formatted string** (e.g.
96
+ `"contract:payments-team#STRIPE_KEY"`), mirroring how
97
+ `CompatibilityIssue.code` started as an ad hoc string. Rejected --
98
+ explicitly the anti-pattern ADR 0024 and this ADR both exist to move away
99
+ from; a consumer would need to parse it back apart to do anything
100
+ structured with it.
101
+ - **Retrofit `code` onto `CompatibilityIssue` as required**, instead of
102
+ leaving it optional and building a separate, required-`code` `Finding`
103
+ type. Rejected -- `CompatibilityIssue` is real, in-use public surface;
104
+ changing an existing optional field to required is exactly the kind of
105
+ gratuitous churn ADR 0024's additive-only discipline exists to avoid, even
106
+ though the tier technically allows it.
107
+ - **Build all seven `EvidenceReference` model variants now**, anticipating
108
+ Dependency/Ownership/Lifecycle/Change Model's eventual finding types.
109
+ Rejected as premature -- see Decision above.
@@ -0,0 +1,98 @@
1
+ # 0027: Dependency Model publishes a fact-shaped result, not the scanning engine
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/build/dependency-model.ts`
6
+ (`buildDependencyModel()`, `DependencyModel`), exported from
7
+ `@maverickcer/env-cap/build`. `src/build/dependency-graph.ts`'s
8
+ `buildDependencyGraph()`, `scan-dependencies.ts`'s
9
+ `scanFileForDependencies()`, and every other engine internal stay
10
+ unexported, unchanged from ADR 0010.
11
+
12
+ ## Context
13
+
14
+ ADR 0010 drew a boundary around the dependency-ownership engine
15
+ (`scan-dependencies.ts`, `dependency-graph.ts`): its scanning/graph-building
16
+ internals are not exported from `@maverickcer/env-cap/build`, only the ownership-framed
17
+ result `generateUsageReport()` maps them into. That ADR's stated reason was
18
+ that no real external use case had justified exporting the raw graph, and
19
+ that env-cap "answers ownership/visibility questions... it doesn't ship a
20
+ general-purpose static-analysis toolkit."
21
+
22
+ ADR 0024 names Dependency Model as one of the seven canonical facts models,
23
+ with two gaps the audit identified: no consumer-indexed view (file -> which
24
+ contracts it reads; only the inverse, contract -> consuming files, exists
25
+ today), and per-access-site line numbers that `scan-dependencies.ts`'s
26
+ `AccessSite.line` already computes but `dependency-graph.ts` discards before
27
+ even its own internal `VariableAccessInfo` type retains them.
28
+
29
+ ## Decision
30
+
31
+ **Publish a new, fact-shaped `DependencyModel` built on top of the existing
32
+ engine, without exporting the engine itself.** `buildDependencyModel()`
33
+ takes the same inputs `buildDependencyGraph()` already does, calls it
34
+ internally, and projects the result into a versioned, JSON-serializable
35
+ shape:
36
+
37
+ - **This does not relax ADR 0010's boundary.** That ADR's actual constraint
38
+ is on the _engine's implementation internals_ -- `scan-dependencies.ts`'s
39
+ AST-walking vocabulary, `dependency-graph.ts`'s two-pass
40
+ building/resolution logic -- staying unexported so nothing outside this
41
+ package depends on their exact shape. A _derived fact_, computed by that
42
+ engine and published in a stable, versioned form, is a different thing
43
+ entirely -- the same relationship `ManifestChangeReport` already has to
44
+ `manifest-snapshot.ts`'s internal diffing functions (ADR 0021), or
45
+ `OwnershipDependencyEntry` has to this same engine, already exported
46
+ today via `usage-report.ts`.
47
+ - **Line numbers are threaded through `VariableAccessInfo` first**, since
48
+ that internal type is where `scan-dependencies.ts`'s `AccessSite.line`
49
+ was being discarded (the two-pass resolution only ever recorded a boolean
50
+ "was this member accessed," never where). Aggregated across every
51
+ consuming file per variable, not attributed per-file -- a full per-file
52
+ breakdown is real added scope this fact didn't need to unblock right now,
53
+ and can be added later without a breaking change if a real consumer asks
54
+ for it.
55
+ - **The inverse `consumers` index is computed once, inside
56
+ `buildDependencyModel()`**, by inverting `contracts[].consumingFiles` --
57
+ not by re-scanning, and not exposed as a second entry point.
58
+ - **Graph-format rendering (DOT, Mermaid, a raw `{nodes, edges}` JSON) is
59
+ explicitly not part of this model.** That's presentation over
60
+ `DependencyModel`'s data, which belongs in a projection (the
61
+ "Configuration Dependency" reference projection, once
62
+ `defineEvidenceProjection()` exists), not baked into the fact model
63
+ itself -- the same fact-vs-projection split ADR 0024 draws everywhere
64
+ else.
65
+
66
+ ## Consequences
67
+
68
+ - `DependencyModel.contracts[].variables[].lines` gives a consumer (or a
69
+ future SARIF/annotation renderer) a real line to point at, where today
70
+ only "used"/"unconsumed"/"indeterminate" exists.
71
+ - A consumer asking "what does this file actually depend on" no longer has
72
+ to invert `OwnershipDependencyEntry[]`'s `consumers: string[]` by hand --
73
+ `DependencyModel.consumers` already is that index.
74
+ - `dependency-graph.ts`/`scan-dependencies.ts` remain exactly as
75
+ unexported and free to change shape as ADR 0010 already established --
76
+ this decision adds a consumer of their _output_, not a new contract on
77
+ their _internals_.
78
+
79
+ ## Alternatives considered
80
+
81
+ - **Export `buildDependencyGraph()`/`scanFileForDependencies()` directly,
82
+ now that a real use case (this fact model) exists.** Rejected -- ADR
83
+ 0010's "no real external use case" reasoning was never the _only_
84
+ argument against exporting the engine; the graph's internal shape
85
+ (`BuildingContract`, two-pass mutation state) is genuinely an
86
+ implementation detail that should stay free to change without a semver
87
+ concern, even once something real is built on its _output_.
88
+ - **Attribute line numbers per consuming file**, not aggregated across all
89
+ of them. Rejected for this phase as more scope than the identified gap
90
+ needed -- the audit's ask was "line numbers exist somewhere reachable,"
91
+ not "know which file each one came from." Revisit if a real projection
92
+ needs the finer grain.
93
+ - **Build the graph-export renderer (DOT/Mermaid/JSON) now, alongside the
94
+ model.** Rejected -- see Decision above; this is projection work, and
95
+ building it ahead of `defineEvidenceProjection()` would either mean a
96
+ privileged non-projection code path (against ADR 0024's "no privileged
97
+ path" rule) or premature commitment to a renderer shape before the
98
+ projection API exists to house it properly.