@maverickcer/env-cap 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (136) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +438 -0
  4. package/CODE_OF_CONDUCT.md +124 -0
  5. package/CODE_REVIEW.md +200 -0
  6. package/CONTRIBUTING.md +131 -0
  7. package/GUIDE.md +1214 -0
  8. package/PROMPT.md +89 -0
  9. package/README.md +92 -200
  10. package/RELEASING.md +160 -0
  11. package/SECURITY.md +270 -0
  12. package/SUPPORT.md +76 -0
  13. package/VERSIONING.md +118 -0
  14. package/benchmarks/READING-BENCHMARKS.md +197 -0
  15. package/benchmarks/README.md +126 -0
  16. package/benchmarks/WRITING-BENCHMARKS.md +252 -0
  17. package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
  18. package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
  19. package/dist/.dts/_ipc/build-fs.d.ts +53 -0
  20. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
  21. package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
  22. package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
  23. package/dist/.dts/_ipc/display-path.d.ts +27 -0
  24. package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
  25. package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
  26. package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
  27. package/dist/.dts/_ipc/glob.d.ts +22 -0
  28. package/dist/.dts/_ipc/glob.d.ts.map +1 -0
  29. package/dist/.dts/_ipc/no-node-fs.d.ts +34 -0
  30. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
  31. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  32. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  33. package/dist/.dts/_ipc/typescript.d.ts +20 -0
  34. package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
  35. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  36. package/dist/.dts/build/compiler-api.d.ts +3 -6
  37. package/dist/.dts/build/compiler-api.d.ts.map +1 -1
  38. package/dist/.dts/build/display-path.d.ts +3 -21
  39. package/dist/.dts/build/display-path.d.ts.map +1 -1
  40. package/dist/.dts/build/generated-banner.d.ts +21 -42
  41. package/dist/.dts/build/generated-banner.d.ts.map +1 -1
  42. package/dist/.dts/build/glob.d.ts +3 -15
  43. package/dist/.dts/build/glob.d.ts.map +1 -1
  44. package/dist/.dts/build/link.d.ts.map +1 -1
  45. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  46. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  47. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
  48. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  49. package/dist/.dts/build/types.d.ts +4 -53
  50. package/dist/.dts/build/types.d.ts.map +1 -1
  51. package/dist/.dts/build/typescript.d.ts +3 -17
  52. package/dist/.dts/build/typescript.d.ts.map +1 -1
  53. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  54. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  55. package/dist/.dts/eslint-plugin/index.d.ts +1 -1
  56. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  57. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  58. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  59. package/dist/{build-H4KFV44Z.js → build-WKDIAWF7.js} +198 -60
  60. package/dist/build-WKDIAWF7.js.map +1 -0
  61. package/dist/build.cjs +194 -56
  62. package/dist/build.cjs.map +1 -1
  63. package/dist/build.js +194 -56
  64. package/dist/build.js.map +1 -1
  65. package/dist/{chunk-7GVPOHDU.js → chunk-KEGYUHBU.js} +2 -2
  66. package/dist/cli/index.js +36 -29
  67. package/dist/cli/index.js.map +1 -1
  68. package/dist/eslint-plugin/index.cjs +84 -54
  69. package/dist/eslint-plugin/index.cjs.map +1 -1
  70. package/dist/eslint-plugin/index.js +83 -53
  71. package/dist/eslint-plugin/index.js.map +1 -1
  72. package/examples/README.md +95 -0
  73. package/package.json +48 -14
  74. package/skills/env-cap/SKILL.md +91 -0
  75. package/skills/env-cap/references/api.md +220 -0
  76. package/specs/architecture.md +634 -0
  77. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  78. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  79. package/specs/decisions/0003-no-global-env-object.md +172 -0
  80. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  81. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  82. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  83. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  84. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  85. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  86. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  87. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  88. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  89. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  90. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  91. package/specs/decisions/0015-security-backport-window.md +60 -0
  92. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  93. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  94. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  95. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  96. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  97. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  98. package/specs/decisions/0022-validation-contexts.md +267 -0
  99. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  100. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  101. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  102. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  103. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  104. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  105. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  106. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  107. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  108. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  109. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  110. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  111. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  112. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  113. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  114. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  115. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  116. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  117. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  118. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  119. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  120. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  121. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  122. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  123. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  124. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  125. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  126. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  127. package/specs/generated-artifacts.md +104 -0
  128. package/specs/migrations/README.md +30 -0
  129. package/specs/migrations/from-centralized-schema.md +503 -0
  130. package/specs/migrations/from-dotenv.md +352 -0
  131. package/specs/migrations/from-envalid.md +482 -0
  132. package/specs/migrations/from-process-env.md +398 -0
  133. package/specs/migrations/from-t3-env.md +416 -0
  134. package/specs/migrations/from-zod.md +303 -0
  135. package/dist/build-H4KFV44Z.js.map +0 -1
  136. /package/dist/{chunk-7GVPOHDU.js.map → chunk-KEGYUHBU.js.map} +0 -0
@@ -0,0 +1,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.