@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,85 @@
|
|
|
1
|
+
# 0034: `examples/` restructured into three audience-shaped flagships; every other scenario moves to `test/integration/`
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented.
|
|
6
|
+
|
|
7
|
+
## Context
|
|
8
|
+
|
|
9
|
+
`examples/` grew to fourteen flat, feature-demo directories, each proving one distinct
|
|
10
|
+
capability (the packaged CLI binary, cross-package discovery, tsconfig path-alias resolution, the
|
|
11
|
+
`liveExpirationDates` callback, per-variable validation contexts, deliberately-broken negative
|
|
12
|
+
cases, and more). Useful as regression coverage, but as a _reading list_ for someone new to
|
|
13
|
+
`env-cap`, fourteen peer directories with no ordering signal beyond a numbered list asked a reader
|
|
14
|
+
to sift through all of them to find the one shape that matched their own situation.
|
|
15
|
+
|
|
16
|
+
Examples are for humans exploring a library for the first time. Integration fixtures are for
|
|
17
|
+
correctness — a scenario worth regression-testing is not automatically a scenario worth reading
|
|
18
|
+
through as an adoption sample. Those had been conflated into one directory.
|
|
19
|
+
|
|
20
|
+
## Decision
|
|
21
|
+
|
|
22
|
+
- **`examples/` holds exactly three flagships**, each answering a different question, in reading
|
|
23
|
+
order: [`application/`](https://github.com/MaverickCER/env-cap/tree/main/examples/application) ("how does this make my code better?",
|
|
24
|
+
evolved in place from the old `basic-node/`), [`team-service/`](https://github.com/MaverickCER/env-cap/tree/main/examples/team-service)
|
|
25
|
+
("how does this help my team?", evolved from `composable-boilerplates/` with real
|
|
26
|
+
multi-team ownership and a `classification`-tagged secret added, not a plain rename — see
|
|
27
|
+
below), and `enterprise-platform/` ("how does this help my organization?", a new build).
|
|
28
|
+
- **`team-service` is not a rename.** `composable-boilerplates`' actual content —
|
|
29
|
+
`exclusiveGroup`/`active: false` schema-composition mechanics — never centered on ownership,
|
|
30
|
+
classification, or a `--check` CI gate, which is what the "engineering team" tier needs to
|
|
31
|
+
demonstrate. A fourth capability (`auth`, owned by `security-team` rather than the database/orm
|
|
32
|
+
capabilities' `data-platform-team`, carrying a `classification: "secret"` variable) and a
|
|
33
|
+
`verify:env` script using `--check` (ADR 0016) were added so the generated ownership matrix and
|
|
34
|
+
security review have genuine, multi-team content, and the CI-gate pattern is actually
|
|
35
|
+
demonstrated, not just described.
|
|
36
|
+
- **The other twelve scenarios physically relocate to `test/integration/`**, not just get
|
|
37
|
+
re-narrated in documentation — `positive/{basic,team,enterprise}/` and
|
|
38
|
+
`negative/{invalid-config,exclusive-violation}/`, matching whether each proves a working path or
|
|
39
|
+
a deliberately broken one. Each fixture keeps its exact internal shape (own `package.json`, own
|
|
40
|
+
`generate:env`/`typecheck` scripts, own `expected/` golden fixtures) — only its directory, the
|
|
41
|
+
resulting `file:` dependency depth (`file:../..` at two directories deep becomes
|
|
42
|
+
`file:../../../../..` at five), and human-facing narrative (no top-level README, no listing in
|
|
43
|
+
`examples/README.md`) change. **Zero coverage loss** — every scenario the fourteen originally
|
|
44
|
+
proved is still exercised in CI exactly as before.
|
|
45
|
+
- **Test infrastructure is shared, not forked.** `test/examples/support.ts` (the shared
|
|
46
|
+
`isInstalled`/`runScript`/`runStart`/`compareGoldenArtifacts` helpers) moves to
|
|
47
|
+
`test/support/example-runner.ts`, with every helper's implicit `examplesRoot` replaced by an
|
|
48
|
+
explicit directory argument each caller resolves itself — `test/examples/` and
|
|
49
|
+
`test/integration/{positive,negative}/` both consume the one module. _Amended: the flagship
|
|
50
|
+
tests were never moved. They remain in `test/examples/` (`application.test.ts`,
|
|
51
|
+
`enterprise-platform.test.ts`, `support.ts`), and only the twelve relocated fixtures live under
|
|
52
|
+
`test/integration/{positive,negative}/`; there is no `test/integration/flagships/`._
|
|
53
|
+
- **`.github/workflows/ci.yml`'s single `examples` job splits into two**: `examples` (the three
|
|
54
|
+
flagships) and `integration-fixtures` (the twelve relocated fixtures), each installing and
|
|
55
|
+
typechecking only what it's responsible for, each running its own `vitest run` scope
|
|
56
|
+
(`test/examples/` vs. `test/integration/positive/ test/integration/negative/`).
|
|
57
|
+
|
|
58
|
+
## Consequences
|
|
59
|
+
|
|
60
|
+
- A reader following `examples/README.md` sees three directories with a clear "read in this
|
|
61
|
+
order" signal, not fourteen with none.
|
|
62
|
+
- A behavior-specific regression (e.g. "does `--tsconfig` resolution still work") is found under
|
|
63
|
+
`test/integration/positive/enterprise/tsconfig-aliases/`, not by guessing which of fourteen
|
|
64
|
+
example READMEs happens to mention it.
|
|
65
|
+
- `scripts/update-example-goldens.mjs`'s single `EXAMPLES` map splits into a `FLAGSHIPS` map
|
|
66
|
+
(rooted at `examples/<name>`) and a `FIXTURES` map (rooted at each fixture's own
|
|
67
|
+
`test/integration/...` path) — the update mechanism itself (regenerate, copy into `expected/`)
|
|
68
|
+
is unchanged.
|
|
69
|
+
- A packed-tarball producer/consumer pair (`paypal-addon`/`paypal-consumer`,
|
|
70
|
+
`tsconfig-aliases`/`tsconfig-aliases-consumer`) still resolves correctly after relocation only
|
|
71
|
+
once each side's `node_modules` is freshly installed — a stale `node_modules` carried over from
|
|
72
|
+
before a directory move retains a symlink pointing at the old, now-wrong relative depth. This is
|
|
73
|
+
expected (any fresh CI checkout always installs clean) and was verified by hand during this
|
|
74
|
+
migration, not assumed from the path arithmetic alone.
|
|
75
|
+
|
|
76
|
+
## Alternatives considered
|
|
77
|
+
|
|
78
|
+
- **Leave all fourteen in `examples/`, just reorder/re-tier the README's list.** Rejected — the
|
|
79
|
+
actual complaint was volume and undifferentiated presentation, not ordering; a reader still has
|
|
80
|
+
to open and discard eleven directories that aren't relevant to their situation.
|
|
81
|
+
- **Drop the twelve relocated scenarios' coverage entirely**, keeping only the three flagships'
|
|
82
|
+
own tests. Rejected outright — each of the twelve proves something a flagship's own content
|
|
83
|
+
doesn't (the packaged CLI binary, cross-package discovery, tsconfig aliases, live external
|
|
84
|
+
metadata, validation contexts, both negative cases), and dropping any of them is a real
|
|
85
|
+
regression-coverage loss, not a documentation simplification.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# 0035: `documentEnv()` metadata generalized to any value, plus five new named compliance-adjacent fields
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented.
|
|
6
|
+
|
|
7
|
+
## Context
|
|
8
|
+
|
|
9
|
+
`ContractDocs.metadata` (`src/runtime/document.ts`) was already a named, typed field —
|
|
10
|
+
`Record<string, string>` — but only at contract level. `VariableDocs` had no `metadata` field at
|
|
11
|
+
all; instead it carried an open index signature, `[key: string]: string | boolean | undefined`,
|
|
12
|
+
so any unrecognized top-level key on a variable's docs got silently swept into an internal `extra`
|
|
13
|
+
bag by `src/build/parse.ts`'s `extractVariableDocsMap()` — and only if its value happened to be a
|
|
14
|
+
string. A non-string, non-boolean value on an unrecognized key (an object, a number, an array) was
|
|
15
|
+
silently dropped at parse time with no warning at all.
|
|
16
|
+
|
|
17
|
+
Separately, building a genuine "prove sensitive data was handled responsibly" report (the
|
|
18
|
+
motivating use case for `enterprise-platform`, the third flagship — ADR 0034) needs facts a free-form
|
|
19
|
+
string bag can't reliably provide: a projection can't safely assert "this variable has no stated
|
|
20
|
+
purpose" if `purpose` might be spelled `purpose`, `reason`, or `why` inconsistently across a
|
|
21
|
+
codebase's `metadata` bags.
|
|
22
|
+
|
|
23
|
+
## Decision
|
|
24
|
+
|
|
25
|
+
- **`VariableDocs.metadata?: Record<string, unknown>` replaces the open index signature.**
|
|
26
|
+
`ContractDocs.metadata` widens in place from `Record<string, string>` to
|
|
27
|
+
`Record<string, unknown>`. Both accept any primitive or object value per key, recursively —
|
|
28
|
+
`evaluateLiteral()` (`src/build/literal-eval.ts`) already evaluates arbitrary nested
|
|
29
|
+
object/array/primitive literals with no code execution, so this needed no new AST capability,
|
|
30
|
+
only a validation-loosening change: `parse.ts`'s `isStringRecord()` becomes `isRecord()`,
|
|
31
|
+
accepting any value shape, reused at both levels.
|
|
32
|
+
- **The old variable-level catch-all is gone, not renamed.** A previous draft of this change
|
|
33
|
+
considered renaming the internal `extra` bag to `metadata` and keeping its "sweep any
|
|
34
|
+
unrecognized string-valued key" behavior. Rejected: that would make `metadata` behave
|
|
35
|
+
differently at the two levels (contract-level `metadata` has always been an explicit,
|
|
36
|
+
deliberately-set field; a renamed `extra` would still be an implicit catch-all). `metadata` is
|
|
37
|
+
now explicit and symmetric at both levels — a value must be nested under a literal `metadata:
|
|
38
|
+
{...}` key to be captured; an arbitrary sibling key on a `VariableDocs` object literal is no
|
|
39
|
+
longer collected by anything.
|
|
40
|
+
- **Five new named fields, on both `VariableDocs` and `ContractDocs`**, following the exact
|
|
41
|
+
`owner`/`classification`/`expiresAt` variable-overrides-contract pattern:
|
|
42
|
+
`purpose?: string`, `legalBasis?: string`, `retentionPolicy?: string`,
|
|
43
|
+
`dataResidency?: string | string[]`, `auditRequired?: boolean`. Deliberately
|
|
44
|
+
**framework-agnostic** — no GDPR/HIPAA/SOC2 vocabulary in the field names themselves (a specific
|
|
45
|
+
citation like `metadata: { gdprArticle: "Art. 32" }` belongs in the now-widened `metadata` bag
|
|
46
|
+
instead), matching ADR 0024's "env-cap doesn't decide what compliance means" stance.
|
|
47
|
+
- **`retentionPolicy` is deliberately not given `expiresAt`'s computed semantics.** `expiresAt` is
|
|
48
|
+
an actual temporal constraint env-cap already parses and computes "days remaining" against;
|
|
49
|
+
`retentionPolicy` is a policy description ("delete after 90 days") env-cap never parses or
|
|
50
|
+
evaluates. Both are exposed side by side in the Lifecycle Model as independent facts.
|
|
51
|
+
- **No new core `FindingCode`s.** A rule like "`classification: pii` without a `purpose` is a
|
|
52
|
+
finding" encodes a policy decision env-cap has no basis to assert on its own — only the
|
|
53
|
+
organization using it does. That responsibility belongs in the _consumer's_ evidence projection
|
|
54
|
+
(see `enterprise-platform`'s `configuration-governance.ts`), reading these five facts, not in
|
|
55
|
+
`src/build/finding-model.ts`.
|
|
56
|
+
|
|
57
|
+
## Consequences
|
|
58
|
+
|
|
59
|
+
- Any `VariableDocs` object literal relying on the old open index signature for an arbitrary
|
|
60
|
+
top-level field (e.g. `{ FOO_VAR: { runbook: "https://..." } }`) must move it under
|
|
61
|
+
`metadata: {...}` (e.g. `{ FOO_VAR: { metadata: { runbook: "https://..." } } }`) — a real,
|
|
62
|
+
intentional breaking change, acceptable pre-1.0.
|
|
63
|
+
- `DiscoveredVariableDocs.extra: Readonly<Record<string, string>>` (always present, possibly
|
|
64
|
+
empty) becomes `metadata: Readonly<Record<string, unknown>> | undefined` (present only when
|
|
65
|
+
actually set) — every downstream consumer (`link.ts`, `manifest-snapshot.ts`,
|
|
66
|
+
`contract-model.ts`, `compatibility.ts`, `docs.ts`, `env-example.ts`) threads the rename and the
|
|
67
|
+
now-optional shape.
|
|
68
|
+
- `compatibility.ts`'s `"extra.<key>"` divergence label becomes `"metadata.<key>"`, and its
|
|
69
|
+
divergence check needs a real deep-equal instead of `!==`, since two structurally-identical
|
|
70
|
+
`metadata` objects are never referentially equal.
|
|
71
|
+
- Non-string `metadata` values need `JSON.stringify()` wherever `docs.ts`/`env-example.ts` render
|
|
72
|
+
them as `` `- ${key}: ${value}` `` — a bare template-literal interpolation of an object value
|
|
73
|
+
would print `[object Object]`.
|
|
74
|
+
|
|
75
|
+
## Alternatives considered
|
|
76
|
+
|
|
77
|
+
- **Minimal: widen `metadata` only, no new named fields.** Rejected as the sole change —
|
|
78
|
+
`purpose`/`legalBasis` would have no dedicated, reliably-spelled key any projection could read
|
|
79
|
+
with a type guarantee, meaningfully weaker for the legal-defense use case `enterprise-platform`
|
|
80
|
+
exists to demonstrate.
|
|
81
|
+
- **Maximal: the five fields above plus `dataSubjectRights`, `thirdPartyRecipients`,
|
|
82
|
+
`crossBorderTransfer`, `consentRequired`.** Rejected for this round — goes further than
|
|
83
|
+
`enterprise-platform` strictly needs to prove the pattern, with no concrete driving use case the
|
|
84
|
+
way `purpose`/`legalBasis` have one. A specific field from this list can be added later if
|
|
85
|
+
actually needed.
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# 0036: Exact source-position evidence — `SourcePosition`, three declaration positions, retained dynamic-access sites, and named scan surfaces
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented (Part 2a only — developer-declared dynamic-access citations and
|
|
6
|
+
acknowledgment freshness are a separate, not-yet-implemented follow-on, tracked as Part 2b).
|
|
7
|
+
|
|
8
|
+
## Context
|
|
9
|
+
|
|
10
|
+
Every fact env-cap derived pointed at a _file_, never a _place within it_. `scanFileForDependencies()`
|
|
11
|
+
(`src/build/scan-dependencies.ts`) already walked the real TypeScript AST and already computed a
|
|
12
|
+
line number for every access site, but discarded the column (`.character`) it had already computed
|
|
13
|
+
alongside it. `dependency-graph.ts`'s per-variable `lines: readonly number[]` aggregated line
|
|
14
|
+
numbers across every consuming file with no way to tell which file a given line came from once a
|
|
15
|
+
variable was read from more than one place. Dynamic (computed) property access collapsed into a
|
|
16
|
+
single `hasDynamicAccess: boolean` per contract — the specific sites that set it were computed and
|
|
17
|
+
then discarded, never retained. A contract's `createEnv()` call, its optional `documentEnv()` call,
|
|
18
|
+
and each variable's own schema property are three different declarations with three different real
|
|
19
|
+
answers to "where is this"; nothing distinguished them. `EvidenceReference` had no position field
|
|
20
|
+
at all. The usage-scan surface `buildDependencyGraph()` walked was narrower than what a report
|
|
21
|
+
implied: `packages` (ADR 0014) resolved each allow-listed package's schema file for cross-package
|
|
22
|
+
contract _discovery_, but never added that package's own source into the _usage-scan_ surface — so
|
|
23
|
+
"unconsumed" only ever meant "no consumer found in this project's own root," a materially narrower
|
|
24
|
+
claim than what the rendered prose suggested.
|
|
25
|
+
|
|
26
|
+
Closing all of this turned out to be mostly wiring already-computed positions through to the public
|
|
27
|
+
model, not new AST capability — the same kind of move ADR 0027 already made once for member-access
|
|
28
|
+
line numbers.
|
|
29
|
+
|
|
30
|
+
## Decision
|
|
31
|
+
|
|
32
|
+
- **One reusable `SourcePosition` type**, in a new `src/build/source-position.ts`:
|
|
33
|
+
`{ file: string; line: number; column: number }`, both 1-indexed. A `positionOf(sourceFile, node)`
|
|
34
|
+
helper computes `{ line, column }` from any AST node; every caller combines it with the file it's
|
|
35
|
+
already scanning. Every `AccessSite` variant (`scan-dependencies.ts`) gained `column`.
|
|
36
|
+
`VariableAccessInfo.lines: readonly number[]` became `positions: readonly SourcePosition[]` — each
|
|
37
|
+
entry now carries its own `file`, closing the "which file did this line come from" gap, not just
|
|
38
|
+
adding a column to the old file-less shape.
|
|
39
|
+
- **Dynamic-access sites are a retained list, not a boolean.** `dynamicAccessSites: SourcePosition[]`
|
|
40
|
+
is appended to at every computed-property-access site `dependency-graph.ts` observes.
|
|
41
|
+
`hasDynamicAccess` stays, now simply `dynamicAccessSites.length > 0` — existing boolean consumers
|
|
42
|
+
are unaffected. `DEPENDENCY_MODEL_SCHEMA_VERSION` bumped 1 → 2. `IndeterminateOwnershipFinding`
|
|
43
|
+
gained the same `dynamicAccessSites`, and its generated prose now cites exact `file:line:column`
|
|
44
|
+
sites instead of naming only the contract.
|
|
45
|
+
- **Three distinct declaration positions, never collapsed into one.** `DiscoveredContract` gained
|
|
46
|
+
`declaration: SourcePosition` (the `createEnv()` call, always present) and
|
|
47
|
+
`documentation: SourcePosition | undefined` (the `documentEnv()` call, if one exists — a
|
|
48
|
+
genuinely different location, and "not yet documented" is a real, distinct state from "documented
|
|
49
|
+
right here"). Each variable's own `DiscoveredSchemaVariable`/`DiscoveredVariable` gained its own
|
|
50
|
+
`declaration: SourcePosition`, sourced from its schema-object property, distinct from either
|
|
51
|
+
contract-level position. `ContractModel`/`ManifestSnapshot`-downstream consumers thread all three
|
|
52
|
+
through under these exact names — never `position`/`declarationLine` standing in for all of them —
|
|
53
|
+
so a future contributor can't accidentally re-merge them without the type itself pushing back.
|
|
54
|
+
- **Usage-scan surface extended to allow-listed `packages`, with an explicit, bounded root.** Each
|
|
55
|
+
package's own resolved `packageDir` (already available from `resolveAllowlistedPackages()`, ADR 0014) is walked with the exact same `discoverSchemaFiles()` + `SCAN_INCLUDE`/`DEFAULT_EXCLUDE`
|
|
56
|
+
policy the local root scan already relies on — never a bespoke, unbounded directory walk. Every
|
|
57
|
+
surface actually scanned is named: `DependencyModel.scannedSurfaces: readonly { label: string;
|
|
58
|
+
root: string }[]`, always at least one entry (`{ label: "application", root: "." }`) even with no
|
|
59
|
+
`packages` configured. Every usage-derived conclusion (`unconsumedOwnedVariables`, `indeterminate`)
|
|
60
|
+
is attributable to a named entry in this list; rendered prose (`usage-report.ts`) says exactly
|
|
61
|
+
"Searched: application; package:\<name\>." rather than a vaguer "the application."
|
|
62
|
+
- **`EvidenceReference` gains an optional-by-value, always-present-by-shape `position` field.**
|
|
63
|
+
`ContractEvidenceReference` and `OwnershipEvidenceReference` both gained
|
|
64
|
+
`readonly position: SourcePosition | undefined` — present on every reference, `undefined` where no
|
|
65
|
+
single position is more relevant than another (e.g. `indeterminate-ownership`, which has multiple
|
|
66
|
+
candidate sites — see `IndeterminateOwnershipFinding.dynamicAccessSites` for the full list
|
|
67
|
+
instead). `Finding.location`'s ten construction sites in `finding-model.ts` all set this field
|
|
68
|
+
explicitly (never omit it — the field's own type requires the key to be present even when its
|
|
69
|
+
value is `undefined`), but none of them populate a real position yet: none of
|
|
70
|
+
`finding-model.ts`'s current inputs (`CompatibilityIssue`, `DocumentationFindings`'s sub-types,
|
|
71
|
+
`usage-report.ts`'s finding types) carry a `SourcePosition` themselves. That's real,
|
|
72
|
+
separate, not-yet-started follow-up work — threading `declaration`/`documentation` through each of
|
|
73
|
+
those intermediate finding types — not something faked here. `position: undefined` is an honest
|
|
74
|
+
value, not a placeholder.
|
|
75
|
+
|
|
76
|
+
## Consequences
|
|
77
|
+
|
|
78
|
+
- `DependencyModelVariable.lines: readonly number[]` is gone; `positions: readonly SourcePosition[]`
|
|
79
|
+
replaces it. `DEPENDENCY_MODEL_SCHEMA_VERSION` 1 → 2. Every consumer of the old shape (tests,
|
|
80
|
+
reference projections in `evidence-projections`) needed updating.
|
|
81
|
+
- `ContractModelContract`/`ContractModelVariable` gained `declaration`/`documentation` fields;
|
|
82
|
+
`CONTRACT_MODEL_SCHEMA_VERSION` 1 → 2.
|
|
83
|
+
- `scanFileForDependencies()`'s public `AccessSite` shape gained `column` on every variant — a
|
|
84
|
+
strictly additive field, but every hand-written fixture asserting an exact `AccessSite` array
|
|
85
|
+
needed its expected column added.
|
|
86
|
+
- A reference-projection helper (`test/integration/positive/enterprise/evidence-projections/
|
|
87
|
+
projections/lib/to-discovered-contracts.mjs`) reconstructs a `DiscoveredContract[]`-compatible
|
|
88
|
+
shape from Contract Model by hand; it's a plain `.mjs` file with no compile-time enforcement
|
|
89
|
+
against the real `DiscoveredContract` type, so it can silently drift when that type gains fields.
|
|
90
|
+
This ADR's implementation found it still reading the pre-ADR-0035 `variable.extra` (renamed to
|
|
91
|
+
`metadata`) and missing all five of ADR 0035's new fields — fixed as part of this pass, not a new
|
|
92
|
+
gap this ADR introduces, but worth naming since nothing currently prevents it from recurring.
|
|
93
|
+
- Several example/fixture schemas (`examples/application/src/env.ts` and four fixtures under
|
|
94
|
+
`test/integration/`) still declared bare `setup`/`documentation` keys directly on a `VariableDocs`
|
|
95
|
+
object literal — valid under the pre-ADR-0035 open index signature, but a hard `TS2353` excess-
|
|
96
|
+
property error under ADR 0035's closed `VariableDocs` shape. This had gone unnoticed because
|
|
97
|
+
`generate:env` (a plain AST scan, not a `tsc` check) doesn't fail on it, and each fixture's own
|
|
98
|
+
`npm run typecheck` is a separate, per-directory command never exercised by the root project's own
|
|
99
|
+
`npm run verify`. Fixed by moving each into `metadata: { setup: ..., documentation: ... }`. Flagged
|
|
100
|
+
here because it's the second time in this same implementation pass that a real regression only
|
|
101
|
+
surfaced by explicitly running every fixture's own `typecheck`/test suite rather than trusting the
|
|
102
|
+
root project's green `npm run verify` alone — worth remembering for any future breaking change to
|
|
103
|
+
a type example/fixture source actually authors against.
|
|
104
|
+
- `Finding.location.position` exists on every `Finding` today but is always `undefined` in practice
|
|
105
|
+
— real population is Part 2a's one deliberately deferred item, left for whenever a consumer
|
|
106
|
+
actually needs it (the `enterprise-platform` configuration-governance projection, Part 3, is the
|
|
107
|
+
first candidate).
|
|
108
|
+
|
|
109
|
+
## Alternatives considered
|
|
110
|
+
|
|
111
|
+
- **One shared declaration position instead of three.** Rejected — collapses "where is this
|
|
112
|
+
variable declared," "where is this contract declared," and "where is this contract documented"
|
|
113
|
+
into one answer, losing exactly the distinction a citation-heavy report most needs.
|
|
114
|
+
- **A naive recursive walk of each allow-listed package's entire directory for usage-scanning.**
|
|
115
|
+
Rejected — a package root routinely contains `node_modules/`, build output, fixtures; walking all
|
|
116
|
+
of it would be both slow and wrong. Reusing the existing `discoverSchemaFiles()` +
|
|
117
|
+
`SCAN_INCLUDE`/`DEFAULT_EXCLUDE` policy against each package's own resolved root was already
|
|
118
|
+
available and already exercised by the local-root scan.
|
|
119
|
+
- **Populating `Finding.location.position` in this same pass by inventing placeholder positions
|
|
120
|
+
(e.g. the contract's `declaration` for every finding regardless of what the finding is actually
|
|
121
|
+
about).** Rejected — a position that doesn't actually correspond to what the finding describes is
|
|
122
|
+
worse than no position at all; `undefined` is honest, a wrong guess is not.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# 0037: Developer-declared dynamic-access citations, kept fully separate from `VariableAccessStatus`, with committed-baseline acknowledgment freshness
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented. **Amended**: the two `FindingCode`s this ADR introduced were renamed from
|
|
6
|
+
`"dynamic-access-citation-stale"`/`"dynamic-access-citation-missing"` to
|
|
7
|
+
`"stale-dynamic-access-citation"`/`"missing-dynamic-access-citation"` to match the adjective-first
|
|
8
|
+
word order every other `FindingCode` uses (`FINDING_MODEL_SCHEMA_VERSION` bumped to 2). Every
|
|
9
|
+
occurrence of the old names below is historical — read as the renamed values.
|
|
10
|
+
|
|
11
|
+
## Context
|
|
12
|
+
|
|
13
|
+
ADR 0036 made "dynamic (computed) property access was observed" a first-class, position-cited fact
|
|
14
|
+
(`dynamicAccessSites`), but left no way for a developer to explain _away_ a false "unconsumed"/
|
|
15
|
+
"indeterminate" signal when the real access genuinely happens somewhere env-cap's static AST walk
|
|
16
|
+
can't see at all — a separate shell script, a Docker entrypoint, a sibling service in another
|
|
17
|
+
repository, a config loader that string-builds a key with no traceable import relationship to the
|
|
18
|
+
contract. Without an escape hatch, every such variable permanently reads as unused or uncertain, no
|
|
19
|
+
matter how correct the deployment actually is.
|
|
20
|
+
|
|
21
|
+
The obvious naive fix — a developer-supplied `dynamicAccess` hint that upgrades `VariableAccessStatus`
|
|
22
|
+
directly to `"used"` — was considered and rejected during design review: that would make env-cap
|
|
23
|
+
_claim it observed_ something it never actually saw, collapsing two epistemically different kinds of
|
|
24
|
+
evidence (an AST walk's own finding vs. a developer's unverified claim) into one signal a report
|
|
25
|
+
reader could no longer tell apart.
|
|
26
|
+
|
|
27
|
+
## Decision
|
|
28
|
+
|
|
29
|
+
- **`VariableDocs.dynamicAccess?: readonly string[]`** (new) — each entry a
|
|
30
|
+
`"<relative-path>:<line>:<column>"` citation. Parsed via a new, shared `parsePositionCitation()`
|
|
31
|
+
(`source-position.ts`), reused everywhere a citation needs turning back into a `SourcePosition`.
|
|
32
|
+
Malformed entries (wrong shape, non-positive line/column) are dropped individually with a
|
|
33
|
+
`ParseWarning`, never a hard failure — matches every other statically-unresolvable-field policy in
|
|
34
|
+
`parse.ts`.
|
|
35
|
+
- **`VariableAccessStatus` is untouched — still exactly `"used" | "unconsumed" | "indeterminate"`,
|
|
36
|
+
purely AST-derived.** A citation is modeled as a wholly separate, independent fact:
|
|
37
|
+
`DependencyModelVariable.dynamicAccessAssertions: readonly DynamicAccessAssertion[]`, each entry a
|
|
38
|
+
`SourcePosition` plus its own `acknowledgment: "fresh" | "stale" | "missing"`. The raw `status` and
|
|
39
|
+
any assertions are always both present on the same object — nothing ever overwrites the other. A
|
|
40
|
+
citation is called an **acknowledgment**, not "verification": content-hash matching only proves the
|
|
41
|
+
developer re-confirmed the citation against a specific version of the cited file, never that the
|
|
42
|
+
citation is semantically correct (env-cap was never built to parse shell scripts, Dockerfiles, or
|
|
43
|
+
YAML).
|
|
44
|
+
- **Freshness is a committed-baseline comparison, re-derived every run, mirroring the existing
|
|
45
|
+
`renamedFrom`/`expiresAt` "committed snapshot, diffed on next run" pattern.**
|
|
46
|
+
`ManifestSnapshotVariable.dynamicAccessSnapshots` stores a SHA-256 hex digest of each cited file's
|
|
47
|
+
full content at the moment `generate:env` last ran and confirmed the file existed —
|
|
48
|
+
`MANIFEST_SNAPSHOT_SCHEMA_VERSION` was **not** bumped for this (purely additive), so every reader
|
|
49
|
+
must treat the field as possibly absent, not just possibly empty (see Consequences).
|
|
50
|
+
`computeDynamicAccessAcknowledgments()` (`manifest-snapshot.ts`) re-checks, every run: does the
|
|
51
|
+
cited file exist right now (never trusted from either snapshot -- always a fresh, live check)? If
|
|
52
|
+
not, `"missing"`. If it exists, does its current hash match the previous snapshot's stored digest
|
|
53
|
+
for that exact citation? Match, or no previous baseline at all (a brand-new citation, nothing to
|
|
54
|
+
contradict it yet) → `"fresh"`. Mismatch → `"stale"`.
|
|
55
|
+
- **Only a `"fresh"` assertion suppresses a finding.** `deriveOwnershipFindings()`
|
|
56
|
+
(`dependency-graph.ts`) skips `unconsumedOwned`/`indeterminate` entirely for a variable with at
|
|
57
|
+
least one fresh assertion — but never silently drops it: it's reported instead in a new `asserted`
|
|
58
|
+
category (`AssertedOwnershipFinding`/`AssertedDynamicAccessFinding`), carrying `wouldBeStatus`
|
|
59
|
+
(what `status` would have produced) side by side with the assertion, rendered in
|
|
60
|
+
`OWNERSHIP.md` as its own `## Asserted (developer-acknowledged dynamic access)` section — the
|
|
61
|
+
report always shows what was actually observed, never lets a developer's claim quietly replace it.
|
|
62
|
+
- **A stale or missing citation becomes a real, actionable `Finding`.** Two new `FindingCode`s,
|
|
63
|
+
`"stale-dynamic-access-citation"`/`"missing-dynamic-access-citation"` (`family: "ownership"`,
|
|
64
|
+
`severity: "warning"`), computed by `findDynamicAccessCitationProblems()` and adapted by
|
|
65
|
+
`finding-model.ts` — the one ownership-family finding with a genuinely meaningful `location.position`
|
|
66
|
+
(every other ownership finding leaves it `undefined`, per ADR 0036's still-deferred position
|
|
67
|
+
threading), since the citation's own position _is_ exactly what the finding is about. This is what
|
|
68
|
+
actually prevents a citation from permanently laundering a variable out of scrutiny: once its
|
|
69
|
+
baseline goes stale, the suppression stops applying on the very next run.
|
|
70
|
+
|
|
71
|
+
## Consequences
|
|
72
|
+
|
|
73
|
+
- `ManifestSnapshotVariable.dynamicAccessSnapshots` is typed `readonly (...)[] | undefined`, not a
|
|
74
|
+
bare array, specifically because it's additive-without-a-version-bump — a real snapshot committed
|
|
75
|
+
before this field existed parses as `"ok"` (not `"unsupported-version"`) while genuinely lacking the
|
|
76
|
+
key. `computeDynamicAccessAcknowledgments()` defaults to `[]` at every read site; caught via a real
|
|
77
|
+
fixture (`test/integration/positive/enterprise/tsconfig-aliases`) throwing
|
|
78
|
+
`TypeError: variable.dynamicAccessSnapshots is not iterable` against its own real, pre-existing
|
|
79
|
+
committed snapshot before this defensive read was added — not a hypothetical.
|
|
80
|
+
- `buildManifestSnapshot()` becomes `async` (hashing cited files is I/O) and gains a required
|
|
81
|
+
`readFile` parameter; `computeManifestChanges()` likewise gains a required `readFile` parameter.
|
|
82
|
+
Every production call site (`generate-manifest.ts`, `generate-evidence.ts`,
|
|
83
|
+
`generate-env-artifacts.ts`) already had a `readFile`/`readFileCached` in scope, so this was a
|
|
84
|
+
mechanical threading change, not new plumbing.
|
|
85
|
+
- `buildDependencyGraph()`/`buildDependencyModel()`/`computeUsage()` each gain an optional final
|
|
86
|
+
`dynamicAccessAcknowledgments` parameter. When the manifest pass isn't also requested (no
|
|
87
|
+
`computeManifestChanges()` call happened), this is simply omitted — every `dynamicAccessAssertions`
|
|
88
|
+
reads back as `[]` for that run, a real, honestly-scoped limitation: acknowledgment freshness needs
|
|
89
|
+
the manifest snapshot's committed baseline to mean anything, so it's only as available as that pass
|
|
90
|
+
is.
|
|
91
|
+
- Implementing this surfaced a real, pre-existing gap unrelated to this ADR: `generate-env-artifacts.ts`'s
|
|
92
|
+
`computeArtifacts()` (the orchestrator behind `generateEnvArtifacts()`, the CLI's default
|
|
93
|
+
`generate:env` path) was still calling a bare `discoverSchemaFiles()` for its usage scan instead of
|
|
94
|
+
ADR 0036's `computeScanSurface()` — meaning the most common path never actually scanned allow-listed
|
|
95
|
+
`packages` sources for usage, only `generateUsageReport()`/`generateEvidenceModel()` did. Fixed as
|
|
96
|
+
part of this pass (it needed the same `computeScanSurface()` call site touched to thread
|
|
97
|
+
`dynamicAccessAcknowledgments` through anyway), not a new gap this ADR introduces.
|
|
98
|
+
- `OwnershipFindings`/`RenderUsageReportOptions` both gain a mandatory `asserted` field — every
|
|
99
|
+
existing hand-written fixture constructing either shape needed a `asserted: []` (or real content)
|
|
100
|
+
added.
|
|
101
|
+
|
|
102
|
+
## Alternatives considered
|
|
103
|
+
|
|
104
|
+
- **Upgrading `VariableAccessStatus` to a 4th value (e.g. `"asserted-dynamic"`) when a citation
|
|
105
|
+
exists.** Rejected during design review — conflates "env-cap observed this" with "a developer
|
|
106
|
+
claimed this," the exact distinction this whole feature exists to preserve. A consumer reading
|
|
107
|
+
`status` alone must always get a purely AST-derived answer.
|
|
108
|
+
- **Calling citation-hash matching "verification."** Rejected — a matching hash proves the developer
|
|
109
|
+
re-confirmed the citation against an unchanged file, nothing about whether the citation is
|
|
110
|
+
semantically correct. "Acknowledgment" is the honest word.
|
|
111
|
+
- **Trusting a citation forever, with no freshness check.** Rejected — a citation that's never
|
|
112
|
+
re-validated could let a variable launder itself out of "unused" scrutiny indefinitely, even after
|
|
113
|
+
the cited file (and the access it once documented) is deleted or rewritten. Re-deriving freshness
|
|
114
|
+
every run, against a committed baseline, closes that permanently.
|