@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,244 @@
|
|
|
1
|
+
# 0038: A real, always-computed `EvidenceModel` backs `generate`/`check`/docs; `ManifestSnapshot` retires; docs/ownership never throw
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented.
|
|
6
|
+
|
|
7
|
+
## Context
|
|
8
|
+
|
|
9
|
+
`EvidenceModel`/`generateEvidenceModel()` (ADR 0031) existed, fully tested, schema-published — but
|
|
10
|
+
`computeArtifacts()`, the function `generateEnvArtifacts()`/`checkEnvArtifacts()`/the CLI's default
|
|
11
|
+
path all ultimately depend on, never actually built one. Every real consumer that wanted evidence,
|
|
12
|
+
including this repo's own `enterprise-platform` example, had to either hand-roll a duplicate
|
|
13
|
+
discovery pipeline or call `generateEvidenceModel()` as a second, fully independent
|
|
14
|
+
discover-and-link pass. `generate-evidence.ts` used to say this duplication out loud: "a real,
|
|
15
|
+
accepted cost." A sibling project (`data-cap`) hit and fixed the identical bug: an evidence model
|
|
16
|
+
that existed but was never wired into the artifact path everything else depends on. This ADR mirrors
|
|
17
|
+
that fix directly rather than inventing new snapshot machinery.
|
|
18
|
+
|
|
19
|
+
Two smaller, longstanding gaps rode along with the fix once the model became load-bearing:
|
|
20
|
+
|
|
21
|
+
- **`env.manifest.snapshot.json`** (ADR 0021) mechanically derived its path from the manifest's own
|
|
22
|
+
location (`src/generated/env.manifest.ts` → `src/generated/env.manifest.snapshot.json`), implying
|
|
23
|
+
it belonged to the same artifact family as the manifest. It doesn't. `env.manifest.ts` is a
|
|
24
|
+
**runtime build artifact** — real TypeScript, imported and executed by the running application. A
|
|
25
|
+
change-history/citation-baseline file is a **CI/reporting artifact** — read by `--check`, by CI
|
|
26
|
+
tooling, by humans; never a build input to the application itself, and tying its path to the
|
|
27
|
+
manifest's meant a project with no `.ts` manifest at all had no way to get one.
|
|
28
|
+
- `generateDocumentation()`/`generateUsageReport()` each had a throw-on-issue escape hatch
|
|
29
|
+
(`onUndocumented`, `onOwnershipIssue`, the CLI's `--strict-docs`/`--strict-ownership`) for
|
|
30
|
+
categories of finding — undocumented variables, unconsumed owned dependencies — that are not
|
|
31
|
+
provable defects the way ADR 0009's exclusive-group/compatibility errors are. Both are heuristic
|
|
32
|
+
signals with real, common false-positive causes (a webhook handler in another repo; a shell script
|
|
33
|
+
reading the variable; a package outside the `packages` allowlist), yet a throw treated them as hard
|
|
34
|
+
failures.
|
|
35
|
+
|
|
36
|
+
## Decision
|
|
37
|
+
|
|
38
|
+
### `computeArtifacts()` always builds the real `EvidenceModel`
|
|
39
|
+
|
|
40
|
+
- The six canonical fact models (Contract/Dependency/Ownership/Lifecycle/Finding/Change →
|
|
41
|
+
`EvidenceModel`) are composed on **every** `computeArtifacts()` call, unconditionally
|
|
42
|
+
(`generate-env-artifacts.ts`), reusing the exact same builders `generateEvidenceModel()` calls —
|
|
43
|
+
not a second implementation of the same assembly. `GenerateEnvArtifactsResult.evidence:
|
|
44
|
+
EvidenceModel` is therefore always populated, regardless of whether `--evidence`/`options.evidence`
|
|
45
|
+
was requested. Free to compute (the same discovery/link pass every other requested output already
|
|
46
|
+
paid for, via the shared `assembleProject()`), always real, never conditionally scoped.
|
|
47
|
+
- **New `--evidence <path>` CLI flag / `evidence?: { location: string } | false` option** on
|
|
48
|
+
`GenerateEnvArtifactsOptions`, resolved via `resolveWithinRoot()` exactly like every other output
|
|
49
|
+
location — independent of, and unconstrained by, `manifest.location`. Requesting it needs no other
|
|
50
|
+
pass: `generateEnvArtifacts({ root, evidence: { location: "docs/env.evidence.json" } })` alone
|
|
51
|
+
succeeds and writes exactly that one file (plus its `.fingerprint` sidecar, below).
|
|
52
|
+
- **Default location convention is `docs/`, never `src/`** — the same reasoning that already put
|
|
53
|
+
`ENVIRONMENT.md`/`OWNERSHIP.md` there: this is generated-but-non-runtime content, not a build
|
|
54
|
+
input. Every example commits `docs/env.evidence.json`.
|
|
55
|
+
- **Optional, always** — nothing writes it unless `evidence.location`/`--evidence <path>` is
|
|
56
|
+
explicitly passed. Not an automatic side effect of requesting a manifest, unlike the old sidecar.
|
|
57
|
+
- `--check` gets evidence support through the **existing generic plumbing**, not a new mechanism:
|
|
58
|
+
`ArtifactCheckFinding["artifact"]`'s union gained `"evidence"`, and `checkEnvArtifacts()` re-renders
|
|
59
|
+
the evidence JSON in-memory and diffs it against disk via the same `compareTextArtifact()`/
|
|
60
|
+
`readIfExists()` path manifest/docs/usage already used (`check-artifacts.ts`).
|
|
61
|
+
|
|
62
|
+
### The provenance/timestamp trap, and the parallel `change`-field trap
|
|
63
|
+
|
|
64
|
+
`EvidenceModel.provenance.generatedAt` is a live timestamp. Persisting it into `docs/env.evidence.json`
|
|
65
|
+
and then having `--check` re-render-and-diff the same way as every other artifact would fail on
|
|
66
|
+
_every single run_, even with zero real changes — the file can never be "up to date" against itself,
|
|
67
|
+
since a fresh render's timestamp can never equal a past write's. `normalizeEvidenceSnapshotForComparison()`
|
|
68
|
+
(`evidence-snapshot.ts`) blanks `provenance.generatedAt` before any comparison — used by
|
|
69
|
+
`check-artifacts.ts`'s `normalizeEvidenceJsonForComparison()`, by every example's golden-file
|
|
70
|
+
comparison (`test/support/example-runner.ts`), and by the `--json` envelope's embedded `evidence`
|
|
71
|
+
field (`normalizeExampleJsonOutput()`) — one normalization rule, applied at every place a persisted
|
|
72
|
+
or embedded copy gets compared, not three separately-maintained ones.
|
|
73
|
+
|
|
74
|
+
A second, less obvious instance of the same trap surfaced during implementation: `evidence.change`
|
|
75
|
+
describes "what's different from whatever snapshot was on disk the moment this run computed it." By
|
|
76
|
+
construction, a `--check` run's own re-derivation of `change` is **not reproducible** against the
|
|
77
|
+
file it's verifying — by the time `--check` recomputes, the file just written _is_ the new baseline,
|
|
78
|
+
so the diff naturally comes back different from (emptier than) what got persisted. This isn't drift;
|
|
79
|
+
it's what `change` means. `normalizeEvidenceSnapshotForComparison()` blanks `change.manifest` and
|
|
80
|
+
`change.renamedVariables` to a constant empty value for exactly the same reason it blanks
|
|
81
|
+
`generatedAt` — caught by a real test (`--check` run twice in a row with no source edits must report
|
|
82
|
+
clean both times), not by inspection.
|
|
83
|
+
|
|
84
|
+
### `env.manifest.snapshot.json` retires; one evidence file replaces it
|
|
85
|
+
|
|
86
|
+
`src/build/manifest-snapshot.ts` is deleted. Its two real jobs both retarget to
|
|
87
|
+
`docs/env.evidence.json` (or wherever `evidence.location`/a caller's `previousSnapshotLocation`
|
|
88
|
+
points), fully decoupled from wherever — or whether — a `.ts` manifest is even being generated:
|
|
89
|
+
|
|
90
|
+
- **Field-level change diffing** — `diffContracts()` (`evidence-snapshot.ts`), a **generic structural
|
|
91
|
+
differ**, not a hand-maintained field-by-field comparison. It walks every own key of a
|
|
92
|
+
`ManifestContractRef`/`ManifestVariableRef` pair via `genericFieldChanges()`, skip-listing identity
|
|
93
|
+
fields (`file`, `exportName`, `key`) rather than special-casing every content field by name — a new
|
|
94
|
+
field on either shape is diffed automatically, with no matching update required in the differ
|
|
95
|
+
itself. `metadata` is special-cased to recurse per-key (`recordFieldChanges()`) rather than being
|
|
96
|
+
diffed as one opaque blob, so `metadata.<key>`-level change entries survive.
|
|
97
|
+
- **Dynamic-access citation content-hash baselines** (ADR 0037) —
|
|
98
|
+
`computeDynamicAccessAcknowledgments()`/`findDynamicAccessCitationProblems()` now read
|
|
99
|
+
`contentHash` off `EvidenceModel.dependency`'s own `DynamicAccessAssertion` (a field added directly
|
|
100
|
+
to that type, not a parallel shape) instead of a separate `ManifestSnapshotVariable.dynamicAccessSnapshots`
|
|
101
|
+
array.
|
|
102
|
+
|
|
103
|
+
One committed file, two consumers (`--check` staleness, and cross-run citation-freshness comparison),
|
|
104
|
+
not two files, and not tied to the manifest's own path. Whether a project commits
|
|
105
|
+
`docs/env.evidence.json` is that project's call — a missing file reads as the normal first-run state
|
|
106
|
+
everywhere this is read, never an error.
|
|
107
|
+
|
|
108
|
+
### The fingerprint cache (`getEvidenceModel()`), mirroring `data-cap`'s fix
|
|
109
|
+
|
|
110
|
+
A full `generateEvidenceModel()` call pays for schema parsing, cross-file linking, the
|
|
111
|
+
dependency-graph AST scan, and all six model builds — expensive to pay on every single report/
|
|
112
|
+
projection script invocation. `evidence-cache.ts` adds:
|
|
113
|
+
|
|
114
|
+
- **`computeSourceFingerprint()`** — a SHA-256 over the raw bytes of every schema file and every
|
|
115
|
+
usage-scan-surface file (`**/*.ts`/`**/*.tsx`, the same broad surface ADR 0036's dynamic-access
|
|
116
|
+
scan already uses), plus env-cap's own installed version. Zero AST work; still pays for the
|
|
117
|
+
discovery/glob walk itself (fingerprinting has to know which files matter), but skips everything
|
|
118
|
+
after it. Deterministic — file paths are deduplicated and sorted before hashing.
|
|
119
|
+
- **`getEvidenceModel()`** — trusts the committed evidence artifact only when its paired
|
|
120
|
+
`.fingerprint` sidecar matches a freshly-computed `computeSourceFingerprint()`; never on file
|
|
121
|
+
presence alone, never on a timestamp (a checkout, a rebase, or a `touch` can all bump mtime with no
|
|
122
|
+
real content change). On any mismatch — stale fingerprint, missing/corrupt evidence file, no
|
|
123
|
+
sidecar at all — falls back to a real `generateEvidenceModel()` call. Never hard-fails, never
|
|
124
|
+
serves data that might be stale.
|
|
125
|
+
- **Never self-heals, never writes.** A cache miss inside `getEvidenceModel()` does not refresh the
|
|
126
|
+
committed artifact or its fingerprint — only the explicit write path
|
|
127
|
+
(`generateEnvArtifacts()`'s `evidence` option, which calls `writeEvidenceSnapshot()` +
|
|
128
|
+
`writeEvidenceFingerprint()` together, always in that order so the two files never describe
|
|
129
|
+
different moments) does that. Two independent callers hitting the same stale cache both recompute
|
|
130
|
+
independently; neither's recompute updates what the other reads.
|
|
131
|
+
|
|
132
|
+
**A consequence worth naming explicitly, not a bug**: because the fingerprint's scan surface is
|
|
133
|
+
`**/*.ts`/`**/*.tsx` across the whole project, editing _any_ TypeScript file in a project — including
|
|
134
|
+
a test file with no relationship to a schema or a consumer — invalidates the cache and changes the
|
|
135
|
+
fingerprint. This is the intended breadth (the same surface ADR 0036/0037's citation machinery needs
|
|
136
|
+
to stay honest about what was actually scanned), not something to narrow for convenience.
|
|
137
|
+
|
|
138
|
+
A real test bug caught this design's own edge, mirroring `data-cap`'s account of the same mistake:
|
|
139
|
+
`configuration-governance.test.ts`'s provenance test asserts a **freshly-generated** `generatedAt` is
|
|
140
|
+
`>=` a timestamp captured immediately before the call. Calling the _cache-aware_ `getEvidenceModel()`
|
|
141
|
+
there is wrong on its face — the whole point of that function is to skip generation (and thus skip
|
|
142
|
+
stamping a new `generatedAt`) when nothing changed, so asserting freshness through it is
|
|
143
|
+
self-contradicting, not merely flaky. Fixed by having that one test call `generateEvidenceModel()`
|
|
144
|
+
directly; every other test in the same file, which only wants correct _content_, keeps using
|
|
145
|
+
`getEvidenceModel()` for the cache's real benefit.
|
|
146
|
+
|
|
147
|
+
### `ENVIRONMENT.md`/`OWNERSHIP.md` never throw; findings replace the escape hatch
|
|
148
|
+
|
|
149
|
+
- `onUndocumented`/`blocking` (`generate-documentation.ts`) and `onOwnershipIssue`/`blocking`
|
|
150
|
+
(`generate-usage.ts`) are removed outright — pre-1.0, not deprecated-and-kept. So are the CLI's
|
|
151
|
+
`--strict-docs`/`--strict-ownership` flags. `--strict` (manifest exclusive-group/compatibility —
|
|
152
|
+
ADR 0009's genuinely provable error category) is untouched; it is the one pass that still blocks.
|
|
153
|
+
- Documentation completeness and ownership hygiene are visible `Finding`s (`documentation`/
|
|
154
|
+
`ownership` families) a team can gate on in its own CI step, reading `Finding[]` off the evidence
|
|
155
|
+
artifact — never something env-cap enforces via a thrown error. `computeDocumentation()`/
|
|
156
|
+
`computeUsage()` now have exactly one throw-severity-free shape of result each, computed
|
|
157
|
+
unconditionally regardless of whether the corresponding pass was itself requested (Finding Model,
|
|
158
|
+
now part of the always-built `EvidenceModel`, needs both either way).
|
|
159
|
+
|
|
160
|
+
### `renderDocs()` migrates to `ContractModel`; the hand-synced adapter drops
|
|
161
|
+
|
|
162
|
+
`docs.ts`'s `renderDocs()`/`renderCatalog()`/`renderDependencyGraph()` take `ContractModelContract`/
|
|
163
|
+
`ContractModelVariable` directly instead of `DiscoveredContract[]`, and drop the `root` param (a
|
|
164
|
+
`ContractModelContract.file` is already root-relative, POSIX-separated — no `relativeTo()` helper
|
|
165
|
+
needed at render time). This removes the need for `to-discovered-contracts.mjs`, a hand-synced,
|
|
166
|
+
untyped adapter the `enterprise-platform` example's `config-reference.mjs` projection used to
|
|
167
|
+
maintain solely to satisfy `renderDocs()`'s old signature — already flagged as a drift risk in ADR
|
|
168
|
+
0036's Consequences. `config-reference.mjs` now calls `renderDocs(evidence.contract.contracts, ...)`
|
|
169
|
+
directly. `generate-documentation.ts`/`check-artifacts.ts` build a `ContractModelContract[]` once
|
|
170
|
+
(`computeDocumentation()`'s `contractModelContracts` field) and pass it to both the real write path
|
|
171
|
+
and the `--check` comparison, rather than each computing it separately.
|
|
172
|
+
|
|
173
|
+
`ContractModelVariable` gained a new field, `dynamicAccess: readonly string[] | undefined`, populated
|
|
174
|
+
in `buildContractModel()` — purely additive, no schema-version bump. `effectiveOwner()`/
|
|
175
|
+
`effectivePurpose()`/`effectiveLegalBasis()`/`effectiveRetentionPolicy()`/`effectiveDataResidency()`/
|
|
176
|
+
`effectiveAuditRequired()` (`link.ts`) were genericized to structural parameter types so one
|
|
177
|
+
implementation serves both `DiscoveredContract`/`DiscoveredVariable` and `ContractModelContract`/
|
|
178
|
+
`ContractModelVariable` shapes without duplicating the field-fallback logic. `computeExpiringEntries()`
|
|
179
|
+
deliberately was **not** migrated the same way — it stays on a new, narrower structural type
|
|
180
|
+
(`ExpiryBearingContract`, satisfied by both shapes) rather than `ContractModel`, specifically to avoid
|
|
181
|
+
silently changing the Stable-tier `DocumentationFindings.expiringSoon[].file` from absolute to
|
|
182
|
+
relative. Nothing in `docs.ts`'s own render path calls this function; migrating it would have been an
|
|
183
|
+
unforced breaking change to an unrelated public field.
|
|
184
|
+
|
|
185
|
+
### Confidence signal: the caveat gets specific, and a citation-freshness column replaces a collapsed label
|
|
186
|
+
|
|
187
|
+
`OWNERSHIP.md`'s "unconsumed owned dependencies" caveat expanded from a bare "not proof of dead code"
|
|
188
|
+
to name the concrete cases: a separate out-of-repo service or webhook handler; non-TypeScript
|
|
189
|
+
consumers (a shell script, a Dockerfile, a Terraform/Kubernetes manifest); or a package whose usage
|
|
190
|
+
lives outside this project's own `packages` allowlist (ADR 0014).
|
|
191
|
+
|
|
192
|
+
Rather than collapsing confidence into a `high`/`low` label, `UnconsumedOwnedVariableFinding`/
|
|
193
|
+
`IndeterminateOwnershipFinding` gained `staleOrMissingCitations: readonly DynamicAccessCitationProblem[]`
|
|
194
|
+
(`usage-report.ts`), joined from `findDynamicAccessCitationProblems()`'s existing output on the
|
|
195
|
+
variable-identity key ADR 0037 already produces. Rendered as its own report column
|
|
196
|
+
(`formatStaleOrMissingCitations()`): blank is the strongest "looks genuinely unused" signal — no
|
|
197
|
+
developer has ever claimed dynamic access here. A non-blank cell names the exact stale/missing
|
|
198
|
+
citation(s) — a developer specifically claimed dynamic access once and that claim can no longer be
|
|
199
|
+
verified — the report shows the receipt directly rather than asking a reader to trust a label.
|
|
200
|
+
|
|
201
|
+
## Consequences
|
|
202
|
+
|
|
203
|
+
- **Breaking (deliberate, pre-1.0, per VERSIONING.md)**: `GenerateEnvManifestResult.changes` no
|
|
204
|
+
longer exists — `generateEnvManifest()` itself no longer tracks change history at all; that moved
|
|
205
|
+
entirely to the persisted evidence artifact. Any script computing "what changed" from a bare
|
|
206
|
+
manifest call (e.g. `split-generators`'s fixture, which calls the standalone generators separately
|
|
207
|
+
rather than through `generateEnvArtifacts()`) must call `generateEvidenceModel()`/`getEvidenceModel()`
|
|
208
|
+
itself and read `evidence.change.manifest`.
|
|
209
|
+
- `src/build/manifest-snapshot.ts` is deleted; `ManifestChangeReport`/`ManifestContractRef`/etc. types
|
|
210
|
+
live on, retargeted, in `evidence-snapshot.ts`.
|
|
211
|
+
- `--strict-docs`/`--strict-ownership` are gone from the CLI; a project relying on either for CI
|
|
212
|
+
gating needs to switch to reading `Finding[]` off `--evidence`'s output in its own step.
|
|
213
|
+
- `RenderDocsOptions.undocumentedContracts`/`undocumentedVariables` (and the equivalent
|
|
214
|
+
`check-artifacts.ts` comparison) need root-relative `file` values now, matching `ContractModelContract`'s
|
|
215
|
+
convention — `generate-documentation.ts` exports `relativizeRef()` for exactly this conversion,
|
|
216
|
+
applied at both the real write path and the drift-check path.
|
|
217
|
+
- A test asserting no file under `src/runtime/` (or the isomorphic `src/evidence/`) imports evidence-
|
|
218
|
+
snapshot/cache machinery would be a reasonable follow-up to make the "never executed at runtime"
|
|
219
|
+
invariant self-verifying rather than convention-only; not added in this pass.
|
|
220
|
+
- Every flagship (`application/`, `team-service/`, `enterprise-platform/`) and every integration
|
|
221
|
+
fixture's `expected/` golden now includes `docs/env.evidence.json` + `.fingerprint`, regenerated via
|
|
222
|
+
`scripts/update-example-goldens.mjs`. Because the fingerprint's scan surface is project-wide
|
|
223
|
+
(`**/*.ts`/`**/*.tsx`), editing _any_ `.ts` file inside an example directory — including its own test
|
|
224
|
+
files — changes that example's fingerprint and requires re-running the golden-regeneration script,
|
|
225
|
+
even when the edit has nothing to do with schemas or evidence content.
|
|
226
|
+
|
|
227
|
+
## Alternatives considered
|
|
228
|
+
|
|
229
|
+
- **Keep deriving the snapshot's path from `manifest.location`.** Rejected — ties a CI/reporting
|
|
230
|
+
artifact's existence to whether a project happens to also generate a runtime `.ts` manifest, which
|
|
231
|
+
is an unrelated decision. A project with only `--docs`/`--ownership`, no `.ts` manifest at all,
|
|
232
|
+
should still be able to get evidence.
|
|
233
|
+
- **Compare `--check`'s embedded/persisted `generatedAt` and `change` by re-deriving and accepting the
|
|
234
|
+
mismatch as real drift.** Rejected — this would make `--check` permanently unable to report "up to
|
|
235
|
+
date" for the one artifact whose entire point is proving CI can trust it; caught by a real repeated-
|
|
236
|
+
`--check` test, not merely reasoned about.
|
|
237
|
+
- **Upgrade `unconsumedOwnedVariables`/`indeterminate` findings to a collapsed `confidence: "high" |
|
|
238
|
+
"low"` label.** Rejected — collapses an inspectable fact (which exact citations exist, and whether
|
|
239
|
+
each is fresh) into a label a reader has to trust rather than verify, the same objection ADR 0036/
|
|
240
|
+
0037 already raised against less-specific evidence shapes elsewhere in this codebase.
|
|
241
|
+
- **Migrate `computeExpiringEntries()` to `ContractModelContract` alongside everything else in
|
|
242
|
+
`docs.ts`.** Rejected — no caller inside `docs.ts`'s own render path needs it on that type, and doing
|
|
243
|
+
so would have silently flipped `DocumentationFindings.expiringSoon[].file` (Stable tier) from
|
|
244
|
+
absolute to relative for no benefit.
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# 0039: The Usage Scanner Follows Object-Destructuring and One-Level `const` Aliasing, and Nothing Else
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented in `src/build/scan-dependencies.ts` and
|
|
6
|
+
`src/build/dependency-graph.ts`, orchestrated by `generateUsageReport()`
|
|
7
|
+
(`src/build/generate-usage.ts`). Extends ADR 0010 (the engine's fixed scope)
|
|
8
|
+
and ADR 0036 (position-cited findings); does not change ADR 0037
|
|
9
|
+
(developer-declared `dynamicAccess` citations stay a wholly separate fact).
|
|
10
|
+
|
|
11
|
+
## Context
|
|
12
|
+
|
|
13
|
+
Before this decision, `scanFileForDependencies()` recognized exactly three
|
|
14
|
+
consumption shapes on a tracked contract binding `paymentsEnv`:
|
|
15
|
+
|
|
16
|
+
- `paymentsEnv.STRIPE_KEY` / `paymentsEnv["STRIPE_KEY"]` -> a `member` access
|
|
17
|
+
("STRIPE_KEY is read").
|
|
18
|
+
- `paymentsEnv[expr]` (non-literal key) -> a `dynamic` access (the contract
|
|
19
|
+
has a computed access; every not-otherwise-read key on it becomes
|
|
20
|
+
`indeterminate`).
|
|
21
|
+
- Any other mention of the bare identifier -> a `reference` (contract-level
|
|
22
|
+
coupling only -- it counted toward "this file is a consumer" but was
|
|
23
|
+
discarded for per-variable status).
|
|
24
|
+
|
|
25
|
+
The `reference` bucket silently swallowed two very different situations:
|
|
26
|
+
|
|
27
|
+
1. **Genuinely ambiguous reads this pass can't attribute to a key**:
|
|
28
|
+
`initialize(paymentsEnv)`, `{ ...paymentsEnv }`, `return paymentsEnv`.
|
|
29
|
+
2. **Reads that a slightly smarter single-file pass CAN attribute**:
|
|
30
|
+
`const { STRIPE_KEY } = paymentsEnv` binds STRIPE_KEY by name; `const e =
|
|
31
|
+
paymentsEnv; e.STRIPE_KEY` reads it through a trivial local alias.
|
|
32
|
+
|
|
33
|
+
For (2), every declared key of a destructured or aliased contract reported as
|
|
34
|
+
`UNCONSUMED_OWNED_VARIABLE` -- a **false claim of certainty**: env-cap said
|
|
35
|
+
"no consumer found in this repository" when a consumer was right there in the
|
|
36
|
+
same file, just not written as `contract.KEY`. Teams that destructure their
|
|
37
|
+
contracts (a common style) got a uniformly wrong usage report.
|
|
38
|
+
|
|
39
|
+
The naive fix -- "trace data flow properly" -- means a `ts.Program` + type
|
|
40
|
+
checker, which ADR 0002 and ADR 0010 deliberately avoid: the scanner is a
|
|
41
|
+
fast, per-file `ts.createSourceFile()` parse with no semantic binding, and
|
|
42
|
+
keeping it that way is what makes it viable on a large monorepo and what
|
|
43
|
+
keeps its findings _provable_ rather than heuristic.
|
|
44
|
+
|
|
45
|
+
## Decision
|
|
46
|
+
|
|
47
|
+
The scanner follows exactly two additional, purely-syntactic, single-file
|
|
48
|
+
shapes, and treats everything it cannot follow as an explicit `escape`
|
|
49
|
+
(never as silence, and never as a guess):
|
|
50
|
+
|
|
51
|
+
### 1. Object-destructuring from a bare tracked import
|
|
52
|
+
|
|
53
|
+
`const { X, Y: y, ["Z"]: z } = paymentsEnv` records a `member` access for
|
|
54
|
+
each statically-knowable key (`X`, `Y`, `Z`), keyed by the **property name**,
|
|
55
|
+
never the local binding name. Per binding element:
|
|
56
|
+
|
|
57
|
+
- A computed key that is **not** a string literal (`{ [k]: v }`, `{ [f()]: v
|
|
58
|
+
}`, `{ 5: v }`) -> `escape` (`via: "computed-key"`). The key expression is
|
|
59
|
+
still walked for nested tracked references.
|
|
60
|
+
- A **nested** binding pattern (`{ Y: { Z } }`) -> `escape` (`via:
|
|
61
|
+
"nested-pattern"`) for that element only. Sibling plain keys still record
|
|
62
|
+
their `member` access.
|
|
63
|
+
- A **rest** element (`{ ...rest }`) -> `escape` (`via: "rest"`).
|
|
64
|
+
|
|
65
|
+
The fast path only fires when the destructuring source is a **bare
|
|
66
|
+
identifier** that is a tracked import. `const { x } = paymentsEnv.getThing()`
|
|
67
|
+
falls through to the ordinary walk (which records the `.getThing` member
|
|
68
|
+
access), unchanged.
|
|
69
|
+
|
|
70
|
+
### 2. One level of file-unique `const` aliasing
|
|
71
|
+
|
|
72
|
+
`const e = paymentsEnv` registers `e` as **another local name for the same
|
|
73
|
+
import binding**, so the ordinary walk then treats `e.X`, `e["X"]`, `e[expr]`
|
|
74
|
+
and a bare `e` exactly as it treats `paymentsEnv.X` etc. -- zero further
|
|
75
|
+
special-casing, and `dependency-graph.ts`'s existing import-resolution pass
|
|
76
|
+
merges `e`'s accesses into the same contract automatically.
|
|
77
|
+
|
|
78
|
+
An alias is tracked **only if** its name is:
|
|
79
|
+
|
|
80
|
+
- declared with `const`, initialized to a bare identifier that is itself a
|
|
81
|
+
**tracked import** (never another alias -- one level, no chains); and
|
|
82
|
+
- **file-unique**: introduced exactly once anywhere in the file, as counted
|
|
83
|
+
by every binding-introducing position (a `var`/`let`/`const` declarator, a
|
|
84
|
+
destructuring binding element, a function/arrow parameter, a `catch`
|
|
85
|
+
binding, a named function/class); and
|
|
86
|
+
- **never assigned to** afterward: not the left side of `=` or any compound
|
|
87
|
+
assignment (`^=` is the top of `SyntaxKind`'s assignment-token range), not
|
|
88
|
+
the operand of `++`/`--`, not a keyword-less `for (e of …)` / `for (e in …)`
|
|
89
|
+
loop variable.
|
|
90
|
+
|
|
91
|
+
A candidate whose base **is** a real tracked import but that fails the
|
|
92
|
+
uniqueness/never-assigned check is reported as an `escape` (`via:
|
|
93
|
+
"reassignment"`) against that import at the declaration site -- `const e =
|
|
94
|
+
paymentsEnv` is a real read of the contract even when this pass declines to
|
|
95
|
+
follow `e`. A `const b = a` chained onto a resolved alias `a` is deliberately
|
|
96
|
+
**not** followed: `a` is recorded as a bare reference for that read, since
|
|
97
|
+
`b` is never tracked.
|
|
98
|
+
|
|
99
|
+
This pass is **not scope-aware** -- matching every other check in
|
|
100
|
+
`scan-dependencies.ts`. A name shadowed in a nested function still counts as
|
|
101
|
+
a second declaration and disqualifies the alias. This is conservative in the
|
|
102
|
+
safe direction: the worst outcome is a real alias going untracked and its
|
|
103
|
+
keys degrading to `indeterminate`, never a false `used`.
|
|
104
|
+
|
|
105
|
+
### 3. `deriveOwnershipFindings` widens on any escape, and a proven access always wins
|
|
106
|
+
|
|
107
|
+
`dependency-graph.ts` records every `escape` site (and every remaining bare
|
|
108
|
+
`reference`) at the **contract** level (`escapeSites`), alongside the
|
|
109
|
+
existing `dynamicAccessSites`. A variable's status is then:
|
|
110
|
+
|
|
111
|
+
- `used` -- at least one `member` access anywhere. **Unconditional**: a
|
|
112
|
+
proven member access wins even when the same contract also has escapes.
|
|
113
|
+
- `indeterminate` -- no member access, but the contract has a dynamic access
|
|
114
|
+
**or** an escape somewhere. `evidence` is `"dynamic-access"` or
|
|
115
|
+
`"escape"`; the finding's `reason` cites every site (with its `via`),
|
|
116
|
+
named per ADR 0036.
|
|
117
|
+
- `unconsumed` -- imported, and no member access, no dynamic access, **no
|
|
118
|
+
escape** anywhere. This now provably means "we resolved the import, saw
|
|
119
|
+
every use of it, and none named this key."
|
|
120
|
+
|
|
121
|
+
`VariableAccessStatus` stays exactly three-valued (`used | unconsumed |
|
|
122
|
+
indeterminate`) -- `escape` is a sub-reason within `indeterminate`, not a new
|
|
123
|
+
status, so ADR 0010's "no fourth state borrowed from a model env-cap doesn't
|
|
124
|
+
have" rule is untouched.
|
|
125
|
+
|
|
126
|
+
## Consequences
|
|
127
|
+
|
|
128
|
+
- A bare `initialize(paymentsEnv)` / `{ ...paymentsEnv }` / `return
|
|
129
|
+
paymentsEnv` now yields `indeterminate` for every not-otherwise-read key,
|
|
130
|
+
where it previously (wrongly) yielded `unconsumed`. Three env-cap test
|
|
131
|
+
fixtures that relied on the old behavior to construct an "unconsumed" case
|
|
132
|
+
were changed to import-without-referencing instead (the genuine
|
|
133
|
+
never-consumed shape).
|
|
134
|
+
- `documentEnv`'s `dynamicAccess` citation (ADR 0037) remains the escape
|
|
135
|
+
hatch for a read env-cap's own AST walk genuinely cannot see -- a shell
|
|
136
|
+
script, a Docker entrypoint, a sibling service. In-repo destructuring and
|
|
137
|
+
aliasing no longer need one.
|
|
138
|
+
|
|
139
|
+
## Alternatives considered
|
|
140
|
+
|
|
141
|
+
- **A `ts.Program` + type checker to follow aliases/destructuring/cross-file
|
|
142
|
+
properly.** Rejected -- contradicts ADR 0002/0010's fast, per-file,
|
|
143
|
+
semantics-free design; seconds-to-minutes on a large monorepo; and the
|
|
144
|
+
checker can still be defeated (`any`, dynamic access), so it trades a large
|
|
145
|
+
cost for a still-incomplete result. The bounded syntactic rule here catches
|
|
146
|
+
the overwhelmingly common real shapes and is honest (`indeterminate`) about
|
|
147
|
+
the rest.
|
|
148
|
+
- **Downgrade `unconsumed` -> `indeterminate` for any bare reference, and add
|
|
149
|
+
no dataflow at all.** Rejected -- removes the false positives but adds no
|
|
150
|
+
real signal; a destructured contract would report every key as "we're not
|
|
151
|
+
sure" forever.
|
|
152
|
+
- **Track alias chains (`const b = a; b.X`).** Rejected -- no natural
|
|
153
|
+
stopping point (`c = b; d = c; …`), the same unbounded-resolution concern
|
|
154
|
+
ADR 0010 rejects for barrel chains. One level covers the real cases; deeper
|
|
155
|
+
chains degrade safely to `indeterminate`.
|
|
156
|
+
- **Full lexical-scope analysis for alias validity** (so a shadowed name in a
|
|
157
|
+
nested function doesn't disqualify the outer alias). Rejected as
|
|
158
|
+
disproportionate -- the file-unique-`const` rule needs no scope engine and
|
|
159
|
+
cannot produce a false `used`; an un-followed real alias just becomes
|
|
160
|
+
`indeterminate`, the safe direction.
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# 0040: Library Surfaces Do Not Acquire `node:fs` -- the Caller Supplies the Filesystem Capability
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented: `src/build/types.ts` (`BuildFileSystem`), threaded through
|
|
6
|
+
every `src/build/**` module and every public options object in
|
|
7
|
+
`src/build/index.ts`; `src/cli/filesystem.ts` (the concrete adapter), re-exported
|
|
8
|
+
as the public `@maverickcer/env-cap/node` entry (`src/node/index.ts`) for a
|
|
9
|
+
consumer's own build script; `src/build/tool-version.ts` + `src/cli/json.ts`
|
|
10
|
+
(version via build-time constant, not a self-read); `src/eslint-plugin/no-node-fs.ts`
|
|
11
|
+
and `no-restricted-imports` in `eslint.config.js`; the `AmbientCapabilities` check.
|
|
12
|
+
|
|
13
|
+
**Amended.** The `BuildFileSystem`, `BuildDirent` and `BuildStats` types and the `no-node-fs` lint rule are now
|
|
14
|
+
carried as managed copies of internal-package-contract's canonical sources (`src/_ipc/build-fs.ts`,
|
|
15
|
+
`src/_ipc/no-node-fs.ts`), re-exported from `src/build/types.ts` and wrapped in `src/eslint-plugin/no-node-fs.ts`.
|
|
16
|
+
The decision itself, that library surfaces never acquire `node:fs`, is unchanged.
|
|
17
|
+
|
|
18
|
+
## Context
|
|
19
|
+
|
|
20
|
+
`repo-contract`'s ADR-0011 removed `child_process`/`process.env` access from
|
|
21
|
+
its own published code after socket.dev flagged "Shell access" and
|
|
22
|
+
"Environment variable access" against its `dist/`. The fix: `spawn`/`env`
|
|
23
|
+
became **required** fields on `RepoContractConfig`, supplied by the consumer
|
|
24
|
+
and threaded internally as one capability object; enforced by a script that
|
|
25
|
+
greps a real `npm pack` tarball.
|
|
26
|
+
|
|
27
|
+
The durable principle: **library code should not implicitly acquire powerful
|
|
28
|
+
ambient capabilities that callers did not explicitly provide.** socket.dev's
|
|
29
|
+
flagging is the concrete trigger and supporting evidence, and a better
|
|
30
|
+
socket.dev score plus less consumer security-review burden is the practical
|
|
31
|
+
payoff -- but the principle stands on its own even if socket.dev's detection
|
|
32
|
+
model changes.
|
|
33
|
+
|
|
34
|
+
Audit of env-cap:
|
|
35
|
+
|
|
36
|
+
- The **runtime** surfaces -- `.` and `./helpers` -- already have zero
|
|
37
|
+
`process.env`, `fs`, network, `child_process`, or `os` access. Nothing to
|
|
38
|
+
do; this already matches ADR-0011's target.
|
|
39
|
+
- The gap: env-cap also ships `./build` and a CLI `bin`, both in the
|
|
40
|
+
published `dist/`. `src/build/*.ts` imported `node:fs`/`node:fs/promises`
|
|
41
|
+
throughout. A socket.dev scan flags the whole package with "Filesystem
|
|
42
|
+
access" regardless of which subpath a consumer imports.
|
|
43
|
+
|
|
44
|
+
## Decision
|
|
45
|
+
|
|
46
|
+
### The invariant
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
Library entrypoints (., ./helpers, ./build, ./evidence)
|
|
50
|
+
→ MUST NOT acquire node:fs -- the capability is always supplied by the caller
|
|
51
|
+
|
|
52
|
+
Executable-context entries (bin, ./eslint-plugin, ./node)
|
|
53
|
+
→ MAY acquire node:fs -- they are the capability boundary:
|
|
54
|
+
bin constructs the concrete adapter and runs it; ./node ships that
|
|
55
|
+
same adapter as a value for a consumer's own Node build script;
|
|
56
|
+
./eslint-plugin runs inside ESLint's own Node process
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
"Ambient-fs-free" means specifically: **`./build` does not acquire filesystem
|
|
60
|
+
capabilities from Node globals/modules itself.** It still performs real
|
|
61
|
+
filesystem operations -- it just never `import`s `node:fs` to do so; the
|
|
62
|
+
capability is always handed in.
|
|
63
|
+
|
|
64
|
+
The CLI is _permitted_ (not "necessarily has to") retain `node:fs` because it
|
|
65
|
+
is the executable consumer: it constructs the concrete `BuildFileSystem`
|
|
66
|
+
adapter, does its own self-bootstrapping (`process.argv[1]` through a
|
|
67
|
+
symlink), and is never imported by a consumer who only depends on `.`/
|
|
68
|
+
`./helpers`/`./build`. `repo-contract` ships no `bin` at all, so full
|
|
69
|
+
package-level zero-fs parity isn't reachable through injection alone; this is
|
|
70
|
+
the one accepted, standard exception (an executable consumer owns the
|
|
71
|
+
capability required to execute its filesystem-oriented behavior). The
|
|
72
|
+
`./eslint-plugin` entry is exempt for the same reason -- it runs inside
|
|
73
|
+
ESLint's Node process, and its bundled `@typescript-eslint/utils` references
|
|
74
|
+
`node:fs`.
|
|
75
|
+
|
|
76
|
+
### The injection interface
|
|
77
|
+
|
|
78
|
+
`BuildFileSystem` (`src/build/types.ts`) -- modeled structurally on
|
|
79
|
+
`node:fs/promises` so a thin adapter is a drop-in value, but with **minimal
|
|
80
|
+
structural types** (`BuildDirent`/`BuildStats`) rather than Node's `Dirent`/
|
|
81
|
+
`Stats`: the capability boundary shouldn't leak Node's type surface just
|
|
82
|
+
because the concrete adapter is Node-backed. Only the six operations
|
|
83
|
+
`src/build/**` actually calls are present (`readFile`, `writeFile`, `mkdir`,
|
|
84
|
+
`readdir`, `stat`, `realpath`).
|
|
85
|
+
|
|
86
|
+
**Not shared with `data-cap`.** The two packages are
|
|
87
|
+
independent products with no runtime coupling; a shared types package to
|
|
88
|
+
dedupe six signatures would add real cross-package coupling for negligible
|
|
89
|
+
benefit. data-cap gets its own, structurally-identical interface.
|
|
90
|
+
|
|
91
|
+
Every public options object in `build/index.ts` carries a **required** `fs:
|
|
92
|
+
BuildFileSystem`. Internal positional helpers take it as a parameter, or via
|
|
93
|
+
`ImportResolutionContext` where a context object already exists.
|
|
94
|
+
|
|
95
|
+
**The Node adapter ships as `@maverickcer/env-cap/node`.** `repo-contract`'s
|
|
96
|
+
consumers pass an existing npm package (`crossSpawn`, `process.env`); there is
|
|
97
|
+
no equivalent off-the-shelf `node:fs/promises` → `BuildFileSystem` value, so
|
|
98
|
+
env-cap ships one -- `nodeBuildFileSystem`, the same object the CLI uses -- from
|
|
99
|
+
a dedicated executable-context entry. `./node` bundles `node:fs/promises`; the
|
|
100
|
+
tarball guard exempts its resolved target exactly as it does `bin` and
|
|
101
|
+
`./eslint-plugin`. `./build` stays clean: a consumer's build script does
|
|
102
|
+
`import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"` and passes it
|
|
103
|
+
as `fs`. A non-Node consumer supplies their own `BuildFileSystem` and never
|
|
104
|
+
imports `./node`.
|
|
105
|
+
|
|
106
|
+
### Version self-read (a distinct concern)
|
|
107
|
+
|
|
108
|
+
`tool-version.ts` and `cli/json.ts` synchronously read the package's _own_
|
|
109
|
+
`package.json` at import time for a version string -- self-introspection, no
|
|
110
|
+
meaningful "consumer" to inject from. Replaced with a build-time constant:
|
|
111
|
+
`tsup.config.ts` reads `package.json` once (build tooling, never shipped) and
|
|
112
|
+
`define`s `__PACKAGE_VERSION__`; `readToolVersion()` returns it, and
|
|
113
|
+
`cli/json.ts` reuses `readToolVersion()` rather than duplicating the logic.
|
|
114
|
+
vitest's config `define`s the same constant so tests run against `src/`
|
|
115
|
+
unchanged.
|
|
116
|
+
|
|
117
|
+
**Build-time filesystem access is not the same thing as published runtime
|
|
118
|
+
filesystem access** -- `tsup.config.ts` reading `package.json` to compute a
|
|
119
|
+
constant never ships in `dist/`, so it adds nothing to the package's own
|
|
120
|
+
flagged capabilities.
|
|
121
|
+
|
|
122
|
+
### Enforcement
|
|
123
|
+
|
|
124
|
+
- **Source-level** (fast feedback): `no-restricted-imports` in
|
|
125
|
+
`eslint.config.js` forbids `fs`/`node:fs`/`fs/promises`/`node:fs/promises`
|
|
126
|
+
under `src/**` except `src/cli/**`. The published `env-cap/
|
|
127
|
+
eslint-plugin` also ships `no-node-fs` for a consumer to enforce the same
|
|
128
|
+
discipline on its own code.
|
|
129
|
+
- **Tarball-level** (release-blocking backstop): the `AmbientCapabilities` check
|
|
130
|
+
runs `npm pack --ignore-scripts`, extracts it, and greps every `.js`/
|
|
131
|
+
`.cjs`/`.mjs` file **inside the extracted package root** for the forbidden
|
|
132
|
+
specifier set, excluding only the resolved `bin`, `./eslint-plugin`, and
|
|
133
|
+
`./node` targets (and their `.map`s) -- derived from `package.json`, not a
|
|
134
|
+
hardcoded glob. Wired into `precommit`/`verify`/`prepublishOnly`.
|
|
135
|
+
|
|
136
|
+
## Alternatives considered
|
|
137
|
+
|
|
138
|
+
- **A shared `BuildFileSystem` package across env-cap and data-cap.**
|
|
139
|
+
Rejected -- adds cross-package coupling against this project's
|
|
140
|
+
minimal-dependency stance; two independently-versioned interfaces stay
|
|
141
|
+
simpler.
|
|
142
|
+
- **Read/write interface segregation** (`ReadFileSystem`/`WriteFileSystem`
|
|
143
|
+
so a check-only path requires just a reader). A legitimate idea, but adds a
|
|
144
|
+
second interface pair to thread everywhere for a benefit that only bites at
|
|
145
|
+
the check-vs-generate boundary. Revisit if `checkEnvArtifacts` ever needs
|
|
146
|
+
a type-level guarantee it can't write.
|
|
147
|
+
- **Splitting the CLI into its own npm package** for literal package-level
|
|
148
|
+
zero-fs parity. A possible future escalation, not undertaken now.
|
|
149
|
+
- **Re-engineering module resolution** to avoid `createRequire().resolve()`
|
|
150
|
+
(used in `resolve-package-schema.ts`) on the guess that socket.dev might
|
|
151
|
+
flag it under some "module resolution" category. No confirmed evidence
|
|
152
|
+
that's a real, distinct capability class -- a post-scan check item, not a
|
|
153
|
+
design change.
|
|
154
|
+
- **`Date.now()`/`setTimeout()` ambient reads** in true runtime code
|
|
155
|
+
(`future()`/`past()` validators). Out of scope -- a determinism concern,
|
|
156
|
+
not a socket-flagged capability.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# 0041: Dual-package hazard (duplicate module instantiation across import paths) is a checked, documented risk class
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Checked by `test/runtime/dual-package-hazard.test.ts`; documented
|
|
6
|
+
in [`SECURITY.md`](../../SECURITY.md#dual-package-hazard).
|
|
7
|
+
|
|
8
|
+
## Context
|
|
9
|
+
|
|
10
|
+
The runtime keeps identity-sensitive state in module scope:
|
|
11
|
+
|
|
12
|
+
- `src/runtime/registry.ts` — a private `WeakMap<object, ContractInternals>`
|
|
13
|
+
that is the only association between a contract object returned by
|
|
14
|
+
`createEnv()` and its schema. `validateEnv()`, `resetEnvCache()`, and
|
|
15
|
+
`isEnvContract()` all consult it.
|
|
16
|
+
- `src/runtime/cache.ts` — the module-level validation cache (`state`,
|
|
17
|
+
`contractValues`, `contractErrors`).
|
|
18
|
+
|
|
19
|
+
Both are correct and necessary within one loaded module instance. They
|
|
20
|
+
become a hazard the moment a consumer's dependency tree resolves
|
|
21
|
+
`env-cap` through two different specifiers — an ESM importer
|
|
22
|
+
and a CJS `require()`r of the same logical package, or a re-exporting
|
|
23
|
+
intermediate package. Node loads two entirely separate module instances in
|
|
24
|
+
that case, each with its own registry `WeakMap` and its own cache. No npm
|
|
25
|
+
package that ships both an ESM and a CJS build can prevent this; it is a
|
|
26
|
+
property of how Node's two module systems resolve independently.
|
|
27
|
+
|
|
28
|
+
## Decision
|
|
29
|
+
|
|
30
|
+
Since the hazard cannot be prevented, it is made a checked, documented risk
|
|
31
|
+
class instead of a silent unknown. `test/runtime/dual-package-hazard.test.ts`
|
|
32
|
+
loads the built `dist/index.js` (ESM) and `dist/index.cjs` (CJS) as two
|
|
33
|
+
genuinely separate module instances and pins the exact, understood
|
|
34
|
+
consequence:
|
|
35
|
+
|
|
36
|
+
- the same resolution path always yields the same registry/cache (no hazard
|
|
37
|
+
within one module graph);
|
|
38
|
+
- different resolution paths load different instances (the hazard itself,
|
|
39
|
+
confirmed rather than assumed);
|
|
40
|
+
- and — the important part — the failure mode is **fail-fast, not silent**:
|
|
41
|
+
a contract created by the ESM instance's `createEnv()` and handed to the
|
|
42
|
+
CJS instance's `validateEnv()`/`resetEnvCache()` throws a `TypeError`
|
|
43
|
+
("this value was not created by createEnv()"), and `isEnvContract()`
|
|
44
|
+
returns `false`. It never validates against the wrong schema or reads a
|
|
45
|
+
stale cache silently.
|
|
46
|
+
|
|
47
|
+
[`SECURITY.md`](../../SECURITY.md#dual-package-hazard) states this plainly
|
|
48
|
+
for evaluators planning a mixed-module-system deployment.
|
|
49
|
+
|
|
50
|
+
## Consequences
|
|
51
|
+
|
|
52
|
+
- An application evaluating this package for a mixed ESM/CJS environment
|
|
53
|
+
has an honest, tested answer rather than an unverified claim.
|
|
54
|
+
- The `TypeError` thrown by `getContractInternals()` is load-bearing for
|
|
55
|
+
this guarantee — a future change that made it return a default or
|
|
56
|
+
`undefined` instead of throwing would turn the fail-fast behavior into
|
|
57
|
+
silent misvalidation. The test pins the throw.
|
|
58
|
+
- The test requires `npm run build` to have produced `dist/index.{js,cjs}`;
|
|
59
|
+
it `skipIf`s gracefully otherwise, matching the cross-runtime tests'
|
|
60
|
+
convention.
|
|
61
|
+
|
|
62
|
+
## Alternatives considered
|
|
63
|
+
|
|
64
|
+
- **Preventing the hazard via a `globalThis`-keyed registry stable across
|
|
65
|
+
realms.** Rejected — adds real complexity and a new hazard class (global
|
|
66
|
+
namespace collision, version-mismatch handling) to solve a problem that,
|
|
67
|
+
once understood, already fails loudly and safely.
|
|
68
|
+
- **Ignoring it, undocumented.** Rejected — an unstated, unverified risk is
|
|
69
|
+
strictly worse for an evaluator than a stated, tested one, even though
|
|
70
|
+
the underlying limitation is identical either way.
|
|
71
|
+
- **Matching `data-cap`'s framing verbatim.** data-cap's
|
|
72
|
+
hazard (ADR 0041 there) degrades _silently_ (its `defaultCoordinator`
|
|
73
|
+
singleton just stops sharing work). env-cap's degrades _loudly_ (a
|
|
74
|
+
`TypeError`). The risk class is the same; the documented consequence is
|
|
75
|
+
deliberately package-specific.
|