@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.
- package/ADOPTION.md +144 -0
- package/AGENTS.md +146 -0
- package/CHANGELOG.md +438 -0
- package/CODE_OF_CONDUCT.md +124 -0
- package/CODE_REVIEW.md +200 -0
- package/CONTRIBUTING.md +131 -0
- package/GUIDE.md +1214 -0
- package/PROMPT.md +89 -0
- package/README.md +92 -200
- package/RELEASING.md +160 -0
- package/SECURITY.md +270 -0
- package/SUPPORT.md +76 -0
- package/VERSIONING.md +118 -0
- package/benchmarks/READING-BENCHMARKS.md +197 -0
- package/benchmarks/README.md +126 -0
- package/benchmarks/WRITING-BENCHMARKS.md +252 -0
- package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
- package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
- package/dist/.dts/_ipc/build-fs.d.ts +53 -0
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts/_ipc/display-path.d.ts +27 -0
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts/_ipc/glob.d.ts +22 -0
- package/dist/.dts/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts +34 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts/_ipc/typescript.d.ts +20 -0
- package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts/build/compatibility.d.ts.map +1 -1
- package/dist/.dts/build/compiler-api.d.ts +3 -6
- package/dist/.dts/build/compiler-api.d.ts.map +1 -1
- package/dist/.dts/build/display-path.d.ts +3 -21
- package/dist/.dts/build/display-path.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +21 -42
- package/dist/.dts/build/generated-banner.d.ts.map +1 -1
- package/dist/.dts/build/glob.d.ts +3 -15
- package/dist/.dts/build/glob.d.ts.map +1 -1
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/merge-documentation.d.ts +35 -0
- package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/build/types.d.ts +4 -53
- package/dist/.dts/build/types.d.ts.map +1 -1
- package/dist/.dts/build/typescript.d.ts +3 -17
- package/dist/.dts/build/typescript.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
- package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/index.d.ts +1 -1
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
- package/dist/{build-H4KFV44Z.js → build-WKDIAWF7.js} +198 -60
- package/dist/build-WKDIAWF7.js.map +1 -0
- package/dist/build.cjs +194 -56
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +194 -56
- package/dist/build.js.map +1 -1
- package/dist/{chunk-7GVPOHDU.js → chunk-KEGYUHBU.js} +2 -2
- package/dist/cli/index.js +36 -29
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +84 -54
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +83 -53
- package/dist/eslint-plugin/index.js.map +1 -1
- package/examples/README.md +95 -0
- package/package.json +48 -14
- package/skills/env-cap/SKILL.md +91 -0
- package/skills/env-cap/references/api.md +220 -0
- package/specs/architecture.md +634 -0
- package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
- package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
- package/specs/decisions/0003-no-global-env-object.md +172 -0
- package/specs/decisions/0004-no-client-server-package-split.md +116 -0
- package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
- package/specs/decisions/0006-self-redacting-contracts.md +124 -0
- package/specs/decisions/0007-processor-not-transformer.md +109 -0
- package/specs/decisions/0008-gzip-size-budget.md +173 -0
- package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
- package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
- package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
- package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
- package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
- package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
- package/specs/decisions/0015-security-backport-window.md +60 -0
- package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
- package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
- package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
- package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
- package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
- package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
- package/specs/decisions/0022-validation-contexts.md +267 -0
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
- package/specs/decisions/0024-fact-model-architecture.md +144 -0
- package/specs/decisions/0025-contract-model-json-projection.md +105 -0
- package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
- package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
- package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
- package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
- package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
- package/specs/decisions/0031-evidence-entry-point.md +85 -0
- package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
- package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
- package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
- package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
- package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
- package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
- package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
- package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
- package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
- package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
- package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
- package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
- package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
- package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
- package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
- package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
- package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
- package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
- package/specs/generated-artifacts.md +104 -0
- package/specs/migrations/README.md +30 -0
- package/specs/migrations/from-centralized-schema.md +503 -0
- package/specs/migrations/from-dotenv.md +352 -0
- package/specs/migrations/from-envalid.md +482 -0
- package/specs/migrations/from-process-env.md +398 -0
- package/specs/migrations/from-t3-env.md +416 -0
- package/specs/migrations/from-zod.md +303 -0
- package/dist/build-H4KFV44Z.js.map +0 -1
- /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.
|