@maverickcer/env-cap 0.6.0 → 0.7.1
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 +449 -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 +35 -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/index.d.ts +3 -3
- 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-F3RQS7VE.js} +218 -63
- package/dist/build-F3RQS7VE.js.map +1 -0
- package/dist/build.cjs +257 -102
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +256 -101
- package/dist/build.js.map +1 -1
- package/dist/{chunk-7GVPOHDU.js → chunk-QKIQ3LZP.js} +2 -2
- package/dist/cli/index.js +36 -29
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +95 -54
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +94 -53
- package/dist/eslint-plugin/index.js.map +1 -1
- package/examples/README.md +95 -0
- package/package.json +53 -19
- 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-QKIQ3LZP.js.map} +0 -0
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# 0028: Ownership Model shares one `effectiveOwner()` rule, fixing a pre-existing divergence
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. `effectiveOwner()` relocated from `docs.ts` (private) to
|
|
6
|
+
`link.ts` (exported). Implemented in `src/build/ownership-model.ts`
|
|
7
|
+
(`buildOwnershipModel()`, `OwnershipModel`), exported from
|
|
8
|
+
`@maverickcer/env-cap/build`. `src/build/generate-usage.ts` now uses the
|
|
9
|
+
shared function for `unconsumedOwnedVariables`' `owner` field.
|
|
10
|
+
|
|
11
|
+
## Context
|
|
12
|
+
|
|
13
|
+
ADR 0024 flagged that Ownership Model's "unowned" signal previously existed
|
|
14
|
+
only as a count (`noOwnerCount`) inside `docs.ts`'s `renderSecurityReview()`
|
|
15
|
+
prose, computed via that file's own private `effectiveOwner()` (variable's
|
|
16
|
+
own `owner`, falling back to the contract's). Investigating that gap
|
|
17
|
+
surfaced a real, separate bug: `generate-usage.ts`'s `computeUsage()`
|
|
18
|
+
resolves ownership for its findings using only `contract.owner`, via a
|
|
19
|
+
locally-built `ownerByIdentity` map that never looks at a variable's own
|
|
20
|
+
`owner` override at all. For a contract-level finding (`dependencyOwnership`,
|
|
21
|
+
`abandonedContracts`) that's correct -- there's no specific variable in
|
|
22
|
+
play. But `UnconsumedOwnedVariableFinding` _does_ name a specific variable
|
|
23
|
+
(`key`), and its `owner` field was silently using the contract-only value --
|
|
24
|
+
meaning `docs.ts`'s Catalog/ownership matrix and `usage-report.ts`'s
|
|
25
|
+
Dependency & Ownership Report could disagree about who owns the same
|
|
26
|
+
variable whenever a `documentEnv()` call set a per-variable `owner`
|
|
27
|
+
override with no contract-level default.
|
|
28
|
+
|
|
29
|
+
## Decision
|
|
30
|
+
|
|
31
|
+
**Fix the bug and build the model on the corrected, shared rule in the same
|
|
32
|
+
change**, rather than building a new model on top of a known-divergent
|
|
33
|
+
foundation:
|
|
34
|
+
|
|
35
|
+
- **`effectiveOwner()` moves to `link.ts`, exported.** Co-located with
|
|
36
|
+
`DiscoveredContract`/`DiscoveredVariable`, the types it operates over,
|
|
37
|
+
instead of living private inside the one renderer that happened to need
|
|
38
|
+
it first. `docs.ts` now imports it instead of defining its own copy.
|
|
39
|
+
- **`generate-usage.ts` gains a second lookup, `effectiveOwnerFor()`,
|
|
40
|
+
used only for `unconsumedOwnedVariables`.** The existing contract-only
|
|
41
|
+
`ownerFor()` stays exactly as it was for the three genuinely
|
|
42
|
+
contract-level fields (`dependencyOwnership.owner`,
|
|
43
|
+
`abandonedContracts.owner`) -- those have no variable to consider an
|
|
44
|
+
override for, so using the contract's own `owner` there was never wrong.
|
|
45
|
+
Only the one finding type that names a specific variable needed the fix.
|
|
46
|
+
- **`OwnershipModel` computes every variable's owner through the same
|
|
47
|
+
shared `effectiveOwner()`, and itemizes `unownedContracts`/
|
|
48
|
+
`unownedVariables` as real arrays**, matching the array-of-refs shape
|
|
49
|
+
`abandonedContracts`/`unconsumedOwnedVariables` already established in
|
|
50
|
+
`usage-report.ts` -- not a new shape invented for this model.
|
|
51
|
+
- **Scoped to every discovered contract, active or not** -- the same scope
|
|
52
|
+
`renderSecurityReview()`'s `noOwnerCount` already had (it counts over
|
|
53
|
+
`for (const contract of contracts)` with no `active` filter). This model
|
|
54
|
+
formalizes that existing scope rather than narrowing it.
|
|
55
|
+
|
|
56
|
+
## Consequences
|
|
57
|
+
|
|
58
|
+
- `docs.ts` and `usage-report.ts` can no longer disagree about who owns a
|
|
59
|
+
variable -- both read through the one function.
|
|
60
|
+
- This is, narrowly, a bug fix bundled with new scope: the changeset for
|
|
61
|
+
this change ships as two entries -- a `patch` for the
|
|
62
|
+
`unconsumedOwnedVariables` owner-resolution fix, a `minor` for the new
|
|
63
|
+
`OwnershipModel` type -- so the changelog doesn't conflate "this was
|
|
64
|
+
wrong before" with "this is new."
|
|
65
|
+
- `OwnershipModelContract.owner` is deliberately _not_ run through
|
|
66
|
+
`effectiveOwner()` (there's no level above a contract to fall back to) --
|
|
67
|
+
only `OwnershipModelVariable.owner` is "effective" in that sense. A
|
|
68
|
+
reader shouldn't assume the same word means the same computation at both
|
|
69
|
+
levels without checking; the field-level doc comments say so explicitly.
|
|
70
|
+
|
|
71
|
+
## Alternatives considered
|
|
72
|
+
|
|
73
|
+
- **Ship `OwnershipModel` first, fix the `generate-usage.ts` bug in a
|
|
74
|
+
separate, later change.** Rejected -- building a new canonical model on
|
|
75
|
+
top of a foundation already known to produce two different answers for
|
|
76
|
+
the same question would just give the bug a second, model-shaped place
|
|
77
|
+
to hide, rather than actually resolving ADR 0024's stated goal of "a fact
|
|
78
|
+
gets computed once."
|
|
79
|
+
- **Leave `ownerFor()` (contract-only) as the single lookup, and make
|
|
80
|
+
`effectiveOwnerFor()` the _only_ one, used everywhere in
|
|
81
|
+
`generate-usage.ts`.** Rejected -- `dependencyOwnership`/
|
|
82
|
+
`abandonedContracts` are genuinely contract-level facts; running them
|
|
83
|
+
through variable-aware resolution would be meaningless (there's no
|
|
84
|
+
variable) and would obscure that these three fields answer a different
|
|
85
|
+
question than `unconsumedOwnedVariables.owner` does.
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# 0029: Lifecycle Model adds deprecation/rename fields, promotes ExpiringEntry
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. `deprecated`/`deprecatedReason`/`removeBy`/`renamedFrom` added to
|
|
6
|
+
`VariableDocs` (`deprecated`/`deprecatedReason` also on `ContractDocs`),
|
|
7
|
+
threaded through `parse.ts` -> `link.ts` -> `manifest-snapshot.ts`.
|
|
8
|
+
Implemented in `src/build/lifecycle-model.ts` (`buildLifecycleModel()`,
|
|
9
|
+
`LifecycleModel`), exported from `@maverickcer/env-cap/build`.
|
|
10
|
+
|
|
11
|
+
## Context
|
|
12
|
+
|
|
13
|
+
ADR 0024 named two gaps in the Lifecycle Model: no `deprecated`/`removeBy`
|
|
14
|
+
field at all (only contract-level `active: boolean`, which means "on/off,"
|
|
15
|
+
not "being phased out"), and no `renamedFrom` -- so a variable rename shows
|
|
16
|
+
up in `ManifestChangeReport` as an unrelated `removedVariables` +
|
|
17
|
+
`addedVariables` pair instead of a single correlated change. Zero grep hits
|
|
18
|
+
existed anywhere in the codebase for any of these four fields before this
|
|
19
|
+
change.
|
|
20
|
+
|
|
21
|
+
## Decision
|
|
22
|
+
|
|
23
|
+
**Add the four fields exactly like every other `documentEnv()` field
|
|
24
|
+
already flows** -- `runtime/document.ts` -> `build/parse.ts`
|
|
25
|
+
(`DiscoveredVariableDocs`/`DiscoveredContractDocs`) -> `build/link.ts`
|
|
26
|
+
(`DiscoveredVariable`/`DiscoveredContract`) -> `build/manifest-snapshot.ts`
|
|
27
|
+
(`ManifestSnapshotVariable`/`ManifestSnapshotContract`, including
|
|
28
|
+
field-level diffing), the same path ADR 0024's Contract Model phase
|
|
29
|
+
established for `classification`. No new mechanism, no special case.
|
|
30
|
+
|
|
31
|
+
- **`deprecated`/`deprecatedReason` exist at both variable and contract
|
|
32
|
+
level; `removeBy`/`renamedFrom` exist only at variable level.** A
|
|
33
|
+
variable rename is a variable-level fact by nature. A contract-level
|
|
34
|
+
"removeBy"/"renamedFrom" wasn't asked for by the audit and has no clear
|
|
35
|
+
meaning (a contract doesn't have a single name to rename `from`) --
|
|
36
|
+
adding it now would be speculative scope, not a real gap being closed.
|
|
37
|
+
- **`deprecated` is deliberately independent of `expiresAt` and of
|
|
38
|
+
contract-level `active`.** `expiresAt` is a rotation/sunset _date_;
|
|
39
|
+
`deprecated` is a phase-out _signal_ with no required date attached (a
|
|
40
|
+
variable can be deprecated with no `removeBy` set yet). `active` is an
|
|
41
|
+
on/off switch for whether a contract participates in the manifest at all
|
|
42
|
+
-- orthogonal to whether it's being phased out. All three stay
|
|
43
|
+
independently settable, matching how `expiresAt` and `active` already
|
|
44
|
+
coexist without one implying the other.
|
|
45
|
+
- **`LifecycleModel` promotes the already-good `ExpiringEntry`/
|
|
46
|
+
`computeExpiringEntries()` precedent** (real, exported, already reused
|
|
47
|
+
across `renderDocs()` and `generate-documentation.ts`) into a canonical,
|
|
48
|
+
versioned shape (`expiring` field, unchanged), and adds a new
|
|
49
|
+
`contracts` array carrying every lifecycle-relevant fact
|
|
50
|
+
(`expiresAt`, `refreshInstructions`, `deprecated`, `deprecatedReason`,
|
|
51
|
+
`removeBy`, `renamedFrom`) per contract/variable.
|
|
52
|
+
- **`LifecycleModel.contracts` only includes a contract when it, or at
|
|
53
|
+
least one of its variables, actually sets a lifecycle field** -- the same
|
|
54
|
+
"only what's relevant" scope `renderLifecycleReport()`'s existing row
|
|
55
|
+
filter already uses (`expiresAt || owner || refreshInstructions`, minus
|
|
56
|
+
`owner`, which belongs to the Ownership Model, not this one). A contract
|
|
57
|
+
with no lifecycle data at all contributes nothing to this model, same as
|
|
58
|
+
it contributes no row to the rendered report today.
|
|
59
|
+
- **`renamedFrom` is authored, not inferred.** Consistent with ADR 0010's
|
|
60
|
+
"provable, not heuristic" ethos: no Levenshtein/similarity matching is
|
|
61
|
+
attempted anywhere to _guess_ a rename from a remove+add pair.
|
|
62
|
+
`diffManifestSnapshots()` reading `renamedFrom` to actually correlate a
|
|
63
|
+
rename is Change Model B's job (a later phase), gated on this field
|
|
64
|
+
existing first.
|
|
65
|
+
|
|
66
|
+
## Consequences
|
|
67
|
+
|
|
68
|
+
- `ManifestChangeReport`'s `updatedVariables` now includes `renamedFrom` in
|
|
69
|
+
its field-level diff whenever it changes, same as any other field --
|
|
70
|
+
itself not yet a rename _correlation_, just a diffable fact, until Change
|
|
71
|
+
Model B lands.
|
|
72
|
+
- A deprecation workflow (flag a variable, give a reason, set a removal
|
|
73
|
+
date) is now representable in `documentEnv()` without overloading
|
|
74
|
+
`expiresAt` (a rotation concept) or `active` (an on/off switch) to mean
|
|
75
|
+
something they were never designed to mean.
|
|
76
|
+
- `LifecycleModelContract`/`LifecycleModelVariable` deliberately omit
|
|
77
|
+
`owner` -- a consumer wanting both lifecycle and ownership facts for the
|
|
78
|
+
same contract joins `LifecycleModel` with `OwnershipModel` by identity
|
|
79
|
+
(`file`+`exportName`), rather than this model duplicating a field that
|
|
80
|
+
model already owns.
|
|
81
|
+
|
|
82
|
+
## Alternatives considered
|
|
83
|
+
|
|
84
|
+
- **Overload `expiresAt` to also mean "deprecated."** Rejected -- a
|
|
85
|
+
variable can be deprecated with no known removal date yet (the whole
|
|
86
|
+
reason `removeBy` is optional and separate), and a variable can have a
|
|
87
|
+
rotation `expiresAt` with no deprecation intent at all (a secret that
|
|
88
|
+
just needs periodic rotation, not phase-out). Conflating the two would
|
|
89
|
+
make either concept unrepresentable without the other.
|
|
90
|
+
- **Attempt heuristic rename detection** (matching a removed key to an
|
|
91
|
+
added key by similarity/edit-distance) instead of an authored
|
|
92
|
+
`renamedFrom` field. Rejected -- exactly the kind of guess ADR 0010's
|
|
93
|
+
"provable, not heuristic" principle already rules out elsewhere in this
|
|
94
|
+
codebase; a false-positive rename correlation would be actively
|
|
95
|
+
misleading in a change report.
|
|
96
|
+
- **Add `removeBy`/`renamedFrom` at the contract level too, for
|
|
97
|
+
symmetry.** Rejected as speculative -- neither has a clear meaning at
|
|
98
|
+
contract granularity, and nothing in the original audit asked for it.
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# 0030: Change Model wraps the existing manifest change report
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented in `src/build/change-model.ts` (`buildChangeModel()`,
|
|
6
|
+
`ChangeModel`), exported from `@maverickcer/env-cap/build`. Rename
|
|
7
|
+
correlation (`RenamedVariable`, `renamedVariables`) landed as a second
|
|
8
|
+
phase on top of this same file once ADR 0029's `renamedFrom` field existed
|
|
9
|
+
to correlate from.
|
|
10
|
+
|
|
11
|
+
## Context
|
|
12
|
+
|
|
13
|
+
ADR 0024 named Change Model as the sixth of the seven canonical models,
|
|
14
|
+
already fact-shaped and exported as `ManifestChangeReport` (ADR 0021), but
|
|
15
|
+
with no versioned, model-namespaced identity of its own -- it's just a field
|
|
16
|
+
(`result.manifest.changes`) on `GenerateEnvManifestResult`, not a value a
|
|
17
|
+
consumer can hand to `defineEvidenceProjection()`-style code alongside the
|
|
18
|
+
other six models.
|
|
19
|
+
|
|
20
|
+
## Decision
|
|
21
|
+
|
|
22
|
+
**A thin wrapper, computing nothing new.** `ChangeModel` is
|
|
23
|
+
`{ schemaVersion, manifest: ManifestChangeReport }`; `buildChangeModel()`
|
|
24
|
+
takes an already-computed `ManifestChangeReport` and wraps it. Concretely:
|
|
25
|
+
|
|
26
|
+
- **`ManifestChangeReport` and its ref/update/field-change types stay
|
|
27
|
+
exactly as they are, exported from where they already are.** Nothing
|
|
28
|
+
about `generateEnvManifest()`'s consumer surface changes. This mirrors
|
|
29
|
+
ADR 0024's additive-wrapper convention exactly: a canonical model is a
|
|
30
|
+
new file that maps or aggregates existing pieces, never an in-place
|
|
31
|
+
rewrite.
|
|
32
|
+
- **No rename correlation in the base shape.** `renamedFrom` (ADR 0029)
|
|
33
|
+
exists on `DiscoveredVariable`/`ManifestSnapshotVariable` as a diffable
|
|
34
|
+
field, but `diffManifestSnapshots()` itself doesn't read it -- correlation
|
|
35
|
+
landed as a second, later phase (Change Model B, below), gated on this
|
|
36
|
+
base shape existing first so the two changes land as independently
|
|
37
|
+
reviewable, independently revertable steps.
|
|
38
|
+
|
|
39
|
+
**Change Model B: rename correlation lives in `change-model.ts`, not
|
|
40
|
+
`manifest-snapshot.ts`.** `buildChangeModel()` gained two more parameters
|
|
41
|
+
(`currentContracts: readonly DiscoveredContract[]`, `root: string`) and a
|
|
42
|
+
new `renamedVariables: readonly RenamedVariable[]` field on `ChangeModel`:
|
|
43
|
+
|
|
44
|
+
- **`ManifestChangeReport`/`diffManifestSnapshots()` stay untouched**,
|
|
45
|
+
exactly as this ADR's original decision required. Correlation happens by
|
|
46
|
+
cross-referencing the _current_ contracts' `renamedFrom` declarations
|
|
47
|
+
against the _already-computed_ `manifest.addedVariables`/
|
|
48
|
+
`removedVariables` -- a second pass over data that already exists, not a
|
|
49
|
+
change to how the diff itself is computed. `ManifestVariableRef` gains no
|
|
50
|
+
new field; `renamedFrom` isn't in that ref shape and doesn't need to be.
|
|
51
|
+
- **A rename is only ever correlated within the same contract**
|
|
52
|
+
(`contractIdentity` must match on both halves) -- a variable moving
|
|
53
|
+
between two different contracts' schemas is a different kind of change,
|
|
54
|
+
not a rename, and correlating across contracts would risk a false match
|
|
55
|
+
on a coincidentally-reused key name.
|
|
56
|
+
- **A `renamedFrom` that doesn't resolve to a real `removedVariables`
|
|
57
|
+
entry correlates nothing.** No error, no warning -- the variable simply
|
|
58
|
+
keeps showing as an ordinary addition in `manifest.addedVariables`,
|
|
59
|
+
same "provable, not heuristic" fallback-to-silence ADR 0010 already
|
|
60
|
+
established for barrel re-exports.
|
|
61
|
+
- **`renamedVariables` is additive, not a filter.** `manifest.addedVariables`/
|
|
62
|
+
`removedVariables` still list a correlated rename's two halves
|
|
63
|
+
separately -- a consumer wanting a deduplicated view filters them out
|
|
64
|
+
using `renamedVariables` itself, rather than this model silently
|
|
65
|
+
removing entries from the untouched legacy report.
|
|
66
|
+
- **No `renamedContracts`.** Lifecycle Model deliberately has no
|
|
67
|
+
contract-level `renamedFrom` (ADR 0029's own alternatives-considered
|
|
68
|
+
section) -- there is no field to correlate a contract-level rename from,
|
|
69
|
+
so no such array is added here either.
|
|
70
|
+
|
|
71
|
+
## Consequences
|
|
72
|
+
|
|
73
|
+
- `ChangeModel` becomes the sixth model Evidence Model assembles against,
|
|
74
|
+
alongside Contract/Dependency/Ownership/Lifecycle/Finding.
|
|
75
|
+
- `buildChangeModel()`'s signature grew from `(manifest)` to
|
|
76
|
+
`(manifest, currentContracts, root)` between these two phases, both
|
|
77
|
+
landing before any published release included the first shape -- an
|
|
78
|
+
Experimental-tier signature change with no real external caller to
|
|
79
|
+
break, per `VERSIONING.md`.
|
|
80
|
+
- A rename shows up in `ChangeModel.renamedVariables` as
|
|
81
|
+
`{ previousKey, currentKey, ... }` the moment a `documentEnv()` edit sets
|
|
82
|
+
`renamedFrom`, with no manual bookkeeping beyond authoring that one field.
|
|
83
|
+
|
|
84
|
+
## Alternatives considered
|
|
85
|
+
|
|
86
|
+
- **Land rename correlation in the same phase.** Rejected -- bundling "give
|
|
87
|
+
Change Model its own identity" with "teach the diff to correlate renames"
|
|
88
|
+
would make this phase's diff meaningfully harder to review and revert
|
|
89
|
+
independently, for no benefit; the two are separable concerns that happen
|
|
90
|
+
to touch the same file.
|
|
91
|
+
- **Fold `ChangeModel` directly into `ManifestChangeReport`** (add a
|
|
92
|
+
`schemaVersion` field to the existing type) rather than a wrapping type.
|
|
93
|
+
Rejected -- `ManifestChangeReport` is real, in-use public surface
|
|
94
|
+
(`result.manifest.changes`); adding an unrelated `schemaVersion` field to
|
|
95
|
+
it conflates "the diff" with "the model-namespaced fact wrapper," and
|
|
96
|
+
would need every existing consumer destructuring that type to account for
|
|
97
|
+
a field with no bearing on the diff itself.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# 0031: A 5th public entry point (`./evidence`) for Evidence Model projections
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented in `src/evidence/`, exported as
|
|
6
|
+
`@maverickcer/env-cap/evidence`.
|
|
7
|
+
|
|
8
|
+
## Context
|
|
9
|
+
|
|
10
|
+
ADR 0024 established seven canonical fact models, the last of which --
|
|
11
|
+
Evidence -- assembles the other six into one immutable snapshot and exists
|
|
12
|
+
specifically to be projected into whatever shape a downstream consumer
|
|
13
|
+
needs (a Markdown report, a compliance export, a dashboard's JSON feed),
|
|
14
|
+
rather than env-cap hand-rolling each of those shapes itself. That
|
|
15
|
+
projection mechanism, `defineEvidenceProjection()`, has a different runtime
|
|
16
|
+
profile than everything `@maverickcer/env-cap/build` exports: assembling an
|
|
17
|
+
`EvidenceModel` requires `node:fs` and the TypeScript compiler API (Node-only,
|
|
18
|
+
dev/CI tooling, per ADR 0002 and `specs/architecture.md`), but _running a
|
|
19
|
+
projection over an already-assembled model_ does not -- a projection is a
|
|
20
|
+
pure function of a plain, JSON-serializable object, no different in kind
|
|
21
|
+
from `createEnv()`/`validateEnv()`'s own isomorphic contract. A dashboard
|
|
22
|
+
backend, an edge function, or a CI step that only has a previously-generated
|
|
23
|
+
`EvidenceModel` JSON file on disk (or over the wire) should be able to run a
|
|
24
|
+
projection against it without pulling in `typescript` or `node:fs` at all.
|
|
25
|
+
|
|
26
|
+
## Decision
|
|
27
|
+
|
|
28
|
+
- **A 5th entry point, not a `./build` export.** `defineEvidenceProjection()`
|
|
29
|
+
ships as `@maverickcer/env-cap/evidence`, isomorphic like `runtime` and
|
|
30
|
+
`helpers` (`platform: "neutral"`, `target: "es2020"` in `tsup.config.ts`),
|
|
31
|
+
rather than living inside `@maverickcer/env-cap/build` alongside the
|
|
32
|
+
Node-only model builders. Bundling it with `build` would mean any consumer
|
|
33
|
+
running a projection in a browser or edge function pulls in the TypeScript
|
|
34
|
+
compiler API transitively, defeating the isomorphism this module exists to
|
|
35
|
+
provide.
|
|
36
|
+
- **`EvidenceModel` is imported as a type only.** `src/evidence/` needs to
|
|
37
|
+
name the shape it projects over, but never constructs one -- that's
|
|
38
|
+
`generateEvidenceModel()`'s job (`@maverickcer/env-cap/build`, a later
|
|
39
|
+
phase). `src/evidence/define-projection.ts` imports `EvidenceModel` from
|
|
40
|
+
`src/build/evidence-model.ts` with `import type` only, erased entirely at
|
|
41
|
+
compile time under `verbatimModuleSyntax` -- a second, deliberate instance
|
|
42
|
+
of the one cross-folder pattern `helpers`→`runtime` already established
|
|
43
|
+
(see `specs/architecture.md`), not an exception carved out for this
|
|
44
|
+
feature alone.
|
|
45
|
+
- **No default export.** Unlike the eslint-plugin entry point (ADR 0017),
|
|
46
|
+
`src/evidence/index.ts` has only named exports, so it needs none of the
|
|
47
|
+
CJS-interop postprocessing `internal-package-contract tool cjs-interop`
|
|
48
|
+
exists for -- esbuild's ordinary CJS output already resolves
|
|
49
|
+
`require("@maverickcer/env-cap/evidence").defineEvidenceProjection`
|
|
50
|
+
correctly.
|
|
51
|
+
- **Experimental tier.** Like `packages` (ADR 0014) and `./build`'s
|
|
52
|
+
lower-level primitives, `./evidence` ships Experimental rather than
|
|
53
|
+
Stable -- see `VERSIONING.md`. The provenance mechanism (ADR 0032) is new
|
|
54
|
+
enough that real projection authorship is likely to reveal a better shape
|
|
55
|
+
before it's ready to commit to for good.
|
|
56
|
+
|
|
57
|
+
## Consequences
|
|
58
|
+
|
|
59
|
+
- `tsup.config.ts`, `scripts/emit-dts-shims.mjs`, `ci/size-budgets.mjs`
|
|
60
|
+
(a 3KB gzip budget, matching `runtime`; `helpers` has 4KB), `typedoc.json`,
|
|
61
|
+
`package.json#exports`, `AGENTS.md`, and `VERSIONING.md` each gained an
|
|
62
|
+
`evidence` entry, mirroring every other place ADR 0017 already touched for
|
|
63
|
+
`eslint-plugin`.
|
|
64
|
+
- `specs/architecture.md`'s "entry points" section and diagram describe five
|
|
65
|
+
directories instead of four, with a second type-only cross-folder edge
|
|
66
|
+
(`evidence` → `build`) alongside `helpers` → `runtime`.
|
|
67
|
+
- A consumer who only ever calls env-cap's build-time generators never pays
|
|
68
|
+
for `./evidence`'s existence -- it's a separate bundle, untouched unless
|
|
69
|
+
imported.
|
|
70
|
+
|
|
71
|
+
## Alternatives considered
|
|
72
|
+
|
|
73
|
+
- **Export `defineEvidenceProjection()` from `@maverickcer/env-cap/build`
|
|
74
|
+
alongside the six model builders.** Rejected -- would make every consumer
|
|
75
|
+
of a projection also a transitive consumer of the TypeScript compiler API
|
|
76
|
+
and `node:fs`, breaking the "run anywhere a persisted snapshot travels"
|
|
77
|
+
goal this mechanism exists to serve, and would put `./build`'s tight
|
|
78
|
+
`999KB` (effectively unbudgeted, dev/CI-only) size profile in tension with
|
|
79
|
+
`./evidence`'s deliberately tiny one.
|
|
80
|
+
- **Export it from the package root (`.`, alongside `createEnv`/
|
|
81
|
+
`validateEnv`).** Rejected -- the root entry point's whole identity is a
|
|
82
|
+
fixed, tiny (3KB gzip) runtime surface (ADR 0008); adding a second,
|
|
83
|
+
independently-growing feature there risks that budget for a capability
|
|
84
|
+
most runtime consumers never use, the same reasoning that kept `helpers`
|
|
85
|
+
and `eslint-plugin` as their own entry points rather than root additions.
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# 0032: Evidence projection provenance via a non-frozen Proxy tracking membrane, not `Object.freeze()`
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented in `src/evidence/define-projection.ts`.
|
|
6
|
+
|
|
7
|
+
## Context
|
|
8
|
+
|
|
9
|
+
The original audit's sketch for `defineEvidenceProjection()` proposed
|
|
10
|
+
wrapping the (already `deepFreeze()`-d, per ADR 0012's precedent)
|
|
11
|
+
`EvidenceModel` in a tracking `Proxy` before handing it to a projector,
|
|
12
|
+
recording every field path actually read, and attaching those paths as
|
|
13
|
+
automatic provenance -- so a consumer never has to hand-maintain "which
|
|
14
|
+
evidence produced this output" bookkeeping themselves.
|
|
15
|
+
|
|
16
|
+
A design spike (tracked separately, not merged) tested this directly and
|
|
17
|
+
found a real incompatibility the original sketch didn't anticipate:
|
|
18
|
+
`Object.freeze()` makes every one of an object's own properties
|
|
19
|
+
non-configurable (and non-writable, for data properties). Per the ECMAScript
|
|
20
|
+
spec, a `Proxy`'s `get` trap on a non-configurable, non-writable data
|
|
21
|
+
property is _required_ to return the exact (`===`) value the target holds --
|
|
22
|
+
it cannot substitute a wrapping proxy for a nested object. Concretely: once
|
|
23
|
+
`EvidenceModel` is frozen (at any level), wrapping it in a wider Proxy and
|
|
24
|
+
returning a _different_ proxy for a nested property read throws
|
|
25
|
+
`TypeError: 'get' on proxy: property '...' is a read-only and
|
|
26
|
+
non-configurable data property on the proxy target but the proxy did not
|
|
27
|
+
return its actual value` on the very first nested access. Freezing even
|
|
28
|
+
just the top level was enough to break wrapping of that level's own
|
|
29
|
+
properties in reproduction.
|
|
30
|
+
|
|
31
|
+
## Decision
|
|
32
|
+
|
|
33
|
+
- **The tracking membrane never wraps a frozen object.** Each call into a
|
|
34
|
+
projector's field function first takes a `structuredClone()` of the
|
|
35
|
+
caller's `EvidenceModel` -- a fresh, unfrozen, fully disconnected copy --
|
|
36
|
+
and wraps _that_ in the Proxy membrane. The caller's own (possibly
|
|
37
|
+
`deepFreeze()`-d) `EvidenceModel` is never touched.
|
|
38
|
+
- **Immutability is enforced by the membrane's own traps, not by freezing
|
|
39
|
+
the target.** `set`, `deleteProperty`, `defineProperty`, and
|
|
40
|
+
`setPrototypeOf` all throw a `TypeError` unconditionally. This gives the
|
|
41
|
+
same practical guarantee (a projector cannot mutate the evidence it reads)
|
|
42
|
+
without relying on `Object.freeze()`, which is what made deep read-tracking
|
|
43
|
+
impossible in the first place.
|
|
44
|
+
- **Every `get` is a two-fold operation: return the real value, and record
|
|
45
|
+
the path.** For each property key that is a string (not a `Symbol`, which
|
|
46
|
+
covers well-known protocol hooks like `Symbol.iterator` and is left to pass
|
|
47
|
+
through unrecorded) other than an array's own `"length"` (recorded paths
|
|
48
|
+
are meant to name _evidence fields_, and `.length` reads are pervasive
|
|
49
|
+
incidental noise from iteration, not a field a consumer meaningfully
|
|
50
|
+
"read"), the dotted path from the model root is added to a `Set`, and the
|
|
51
|
+
result -- if itself an object -- is recursively wrapped (memoized in a
|
|
52
|
+
`WeakMap` keyed by the already-cloned object, so repeated reads of the same
|
|
53
|
+
nested object return the same proxy instance rather than constructing a
|
|
54
|
+
new one each time). This design was verified against plain nested reads,
|
|
55
|
+
`.map()`/array iteration (including `for...of`'s internal `Symbol.iterator`
|
|
56
|
+
call, which correctly re-enters the membrane per element), destructuring,
|
|
57
|
+
and spread -- all correctly attribute reads to their real field paths.
|
|
58
|
+
- **`generateEvidenceModel()`'s own output stays genuinely frozen.**
|
|
59
|
+
`deepFreeze()` (ADR from Phase 12's genericization) is still the right
|
|
60
|
+
tool for the `EvidenceModel` a caller receives _outside_ a projection --
|
|
61
|
+
direct property access on that object throws on mutation exactly as every
|
|
62
|
+
other canonical model does. Freezing and the tracking membrane are simply
|
|
63
|
+
never applied to the same object graph at the same time.
|
|
64
|
+
- **Recorded sources are flat `EvidenceModel` field-path strings today, not
|
|
65
|
+
`EvidenceReference`s.** Turning a path like
|
|
66
|
+
`"contract.contracts.0.variables.0.key"` into the structured
|
|
67
|
+
`EvidenceReference` shape (`{model: "contract", exportName: "...",
|
|
68
|
+
variable: "..."}`, `src/build/evidence-reference.ts`, ADR 0026) requires
|
|
69
|
+
_model-aware_ interpretation -- knowing that index `0` into `.contracts`
|
|
70
|
+
means "keyed by that contract's `exportName`," and index `0` into
|
|
71
|
+
`.variables` means "keyed by `key`" -- which a generic path-string reader
|
|
72
|
+
cannot derive on its own without hardcoding each model's array-shape
|
|
73
|
+
semantics into the tracking membrane itself. That per-model resolution is
|
|
74
|
+
real, additional design work, deliberately deferred rather than rushed
|
|
75
|
+
into this phase; see `VERSIONING.md`'s Experimental-tier note for
|
|
76
|
+
`./evidence`.
|
|
77
|
+
- **Purity beyond read-only-ness is documented, not enforced.** Nothing stops
|
|
78
|
+
a projector from calling `fetch()` or `console.log`-ing a secret from
|
|
79
|
+
within its function body -- there is no runtime mechanism in JavaScript
|
|
80
|
+
that can prevent arbitrary side effects inside a plain function. A
|
|
81
|
+
projector is documented (`EvidenceProjector`'s own JSDoc) as required to be
|
|
82
|
+
a pure function of its `evidence` argument; only the read-only half of
|
|
83
|
+
that contract is actually enforced.
|
|
84
|
+
|
|
85
|
+
## Consequences
|
|
86
|
+
|
|
87
|
+
- `defineEvidenceProjection()`'s `project()` path clones `EvidenceModel` once
|
|
88
|
+
per output field (a fresh membrane per field, so each output key's
|
|
89
|
+
`sources` list reflects only that field's own reads). For a typical
|
|
90
|
+
projection (a handful of output fields over a config-sized model), this is
|
|
91
|
+
cheap; it would need reconsidering if a projection schema ever grew large
|
|
92
|
+
enough, or `EvidenceModel` itself large enough, for repeated
|
|
93
|
+
`structuredClone()` calls to matter.
|
|
94
|
+
- `structuredClone()` is a runtime dependency of `./evidence` -- available as
|
|
95
|
+
a global in Node ≥17, all evergreen browsers, and every edge runtime this
|
|
96
|
+
package already targets; no polyfill or additional dependency required.
|
|
97
|
+
- A future phase can add per-model index-path → `EvidenceReference`
|
|
98
|
+
resolvers (one small, targeted function per of the six sub-models, per the
|
|
99
|
+
spike's recommendation) as a purely additive enhancement to
|
|
100
|
+
`EvidenceProjectionResult.sources`, without changing
|
|
101
|
+
`defineEvidenceProjection()`'s call signature.
|
|
102
|
+
|
|
103
|
+
## Alternatives considered
|
|
104
|
+
|
|
105
|
+
- **Ship the original sketch as-is (freeze first, then wrap).** Rejected --
|
|
106
|
+
throws a `TypeError` on the first nested property read, as confirmed by
|
|
107
|
+
direct reproduction; not a viable implementation of the original design at
|
|
108
|
+
all, not just a suboptimal one.
|
|
109
|
+
- **Explicit, caller-supplied `sources` instead of automatic tracking.** The
|
|
110
|
+
documented fallback if the design spike hadn't panned out. Rejected once
|
|
111
|
+
the spike confirmed the membrane-based approach works cleanly -- automatic
|
|
112
|
+
provenance is strictly more useful than asking every projection author to
|
|
113
|
+
hand-maintain a parallel `sources` array that can silently drift from what
|
|
114
|
+
their projector actually reads.
|
|
115
|
+
- **Build the full model-aware `EvidenceReference` resolution now, instead of
|
|
116
|
+
flat path strings.** Rejected for this phase -- real, separate design work
|
|
117
|
+
(six model-specific index-path interpreters) that the spike explicitly
|
|
118
|
+
flagged as non-trivial; shipping flat path strings first lets real
|
|
119
|
+
projection usage inform what the resolved shape should look like, the same
|
|
120
|
+
Experimental-tier reasoning `VERSIONING.md` already applies elsewhere.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# 0033: The ten first-party reference projections live in `examples/`, not `src/`
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented starting with `examples/evidence-projections/`. **Superseded in part by
|
|
6
|
+
ADR 0034**: the three-tier `examples/` restructuring relocated this package to
|
|
7
|
+
`test/integration/positive/enterprise/evidence-projections/` as a behavioral fixture rather than a
|
|
8
|
+
human-facing example — the reasoning below (no privileged internal path, reuses the flagship
|
|
9
|
+
schema, golden-fixture regression protection) is unchanged and still governs it; only its
|
|
10
|
+
directory and presentation to readers changed.
|
|
11
|
+
|
|
12
|
+
## Context
|
|
13
|
+
|
|
14
|
+
ADR 0024's plan calls for ten first-party reference projections (`.env.example`, Environment
|
|
15
|
+
Configuration Reference, Configuration Inventory, and so on) built through
|
|
16
|
+
`defineEvidenceProjection()` (`@maverickcer/env-cap/evidence`, ADR 0031) with "no privileged
|
|
17
|
+
internal path" — the same public API a real consumer would use. Each one, in practice, needs
|
|
18
|
+
both halves of that API: `generateEvidenceModel()` (Node-only, `@maverickcer/env-cap/build`) to
|
|
19
|
+
assemble an `EvidenceModel`, and `defineEvidenceProjection()` (isomorphic,
|
|
20
|
+
`@maverickcer/env-cap/evidence`) to project it. `src/evidence/` currently has exactly one
|
|
21
|
+
sanctioned cross-folder edge — a type-only import of `EvidenceModel` from `src/build/`, erased at
|
|
22
|
+
compile time (ADR 0031) — and no edge at all onto any of `src/build/`'s actual renderer
|
|
23
|
+
_functions_ (`renderEnvExample`, `renderDocs`, etc.), which several of these projections need to
|
|
24
|
+
call directly to stay "thin wrappers" rather than reimplemented rendering logic.
|
|
25
|
+
|
|
26
|
+
## Decision
|
|
27
|
+
|
|
28
|
+
- **The reference projections live in `examples/evidence-projections/`, a new example package
|
|
29
|
+
structured like every other directory in `examples/`** — its own `package.json` depending on
|
|
30
|
+
`env-cap` via `file:../..`, importing `@maverickcer/env-cap/build` and
|
|
31
|
+
`@maverickcer/env-cap/evidence` exactly as an external consumer's own project would. Nothing
|
|
32
|
+
inside it reaches into `src/**/*.ts` or an unexported build internal.
|
|
33
|
+
- **This is the literal, strongest form of "no privileged internal path."** A file living inside
|
|
34
|
+
`src/build/` importing from `src/evidence/` (or vice versa) would still be _inside the
|
|
35
|
+
package_, with the option of reaching past the public surface even if it chose not to.
|
|
36
|
+
A file in `examples/evidence-projections/`, installing the package the same way a real
|
|
37
|
+
consumer does, structurally cannot.
|
|
38
|
+
- **`src/`'s five-folder, zero-(or type-only-)cross-dependency invariant is left completely
|
|
39
|
+
untouched.** No new ADR-sanctioned edge was needed on either `src/build/` or `src/evidence/` —
|
|
40
|
+
the tension that raised this question in the first place (a projection needing both a
|
|
41
|
+
Node-only renderer and the isomorphic projection mechanism) is resolved by placing the
|
|
42
|
+
_consumer_ of both outside `src/` entirely, not by adding a new edge between them.
|
|
43
|
+
`src/evidence/`'s one type-only edge onto `src/build/evidence-model.ts` is unaffected.
|
|
44
|
+
- **Reuses `examples/basic-node`'s exact schema.** Each projection's output can be verified
|
|
45
|
+
byte-identical to what the existing, already-tested `generateEnvArtifacts()` path produces on
|
|
46
|
+
the exact same input — the strongest form of regression protection available, and proof that a
|
|
47
|
+
projection is a _reshape_, not a second, independently-drifting rendering implementation.
|
|
48
|
+
- **Wired into the same infrastructure every other example uses**: `.github/workflows/ci.yml`'s
|
|
49
|
+
`examples` job, `test/examples/evidence-projections.test.ts`, `examples/README.md`'s ordered
|
|
50
|
+
list, and `scripts/update-example-goldens.mjs`'s `EXAMPLES` map — no special-cased tooling.
|
|
51
|
+
|
|
52
|
+
## Consequences
|
|
53
|
+
|
|
54
|
+
- A consumer cannot `import` env-cap's reference projections as ready-made functions from the
|
|
55
|
+
published package — only copy the pattern, the same way every other `examples/` directory is
|
|
56
|
+
a pattern to copy, not an importable module. This was an explicit, accepted tradeoff (see
|
|
57
|
+
Alternatives below), not an oversight.
|
|
58
|
+
- Each reference projection needs its own small reshape from a canonical fact model's shape
|
|
59
|
+
(e.g. `ContractModelContract`) into whatever shape the renderer it wraps already expects (e.g.
|
|
60
|
+
`DiscoveredContract`) — genuine, if mechanical, adapter code, not a zero-cost pass-through.
|
|
61
|
+
Fields the target renderer doesn't use (e.g. `renderEnvExample()` never reads
|
|
62
|
+
`deprecated`/`deprecatedReason`) are stubbed `undefined` rather than sourced from a
|
|
63
|
+
cross-referenced model, to keep each projection's own scope narrow.
|
|
64
|
+
- `examples/evidence-projections/`'s own `expected/` golden fixtures follow the exact same
|
|
65
|
+
regression-fixture convention documented in `examples/README.md` — regenerated only via
|
|
66
|
+
`npm run examples:update-golden`, never silently.
|
|
67
|
+
|
|
68
|
+
## Alternatives considered
|
|
69
|
+
|
|
70
|
+
- **Inside `src/build/`, importing `defineEvidenceProjection` from `src/evidence/`.** Rejected —
|
|
71
|
+
would require a new ADR sanctioning a second, _value-level_ cross-folder edge (unlike the
|
|
72
|
+
existing type-only ones), and would mean `src/build/` could no longer move to its own
|
|
73
|
+
repository without `src/evidence/` coming along, a real cost for a set of files whose whole
|
|
74
|
+
point is demonstrating the _public_, cross-package-boundary API, not needing privileged access.
|
|
75
|
+
- **A 6th public entry point exporting the ten projections as ready-made functions** (e.g.
|
|
76
|
+
`env-cap/projections`). Rejected for this round — would commit env-cap to
|
|
77
|
+
versioning and supporting ten specific output shapes as Stable-track API surface before any
|
|
78
|
+
real external usage has validated they're the right shapes (the same reasoning `VERSIONING.md`
|
|
79
|
+
already applies to `packages` and `./evidence` itself). Revisiting this once real projection
|
|
80
|
+
authorship (env-cap's own and consumers') has had a feedback cycle is explicitly left open,
|
|
81
|
+
not foreclosed.
|