@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.
Files changed (137) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +449 -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 +35 -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/index.d.ts +3 -3
  45. package/dist/.dts/build/link.d.ts.map +1 -1
  46. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  47. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  48. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
  49. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  50. package/dist/.dts/build/types.d.ts +4 -53
  51. package/dist/.dts/build/types.d.ts.map +1 -1
  52. package/dist/.dts/build/typescript.d.ts +3 -17
  53. package/dist/.dts/build/typescript.d.ts.map +1 -1
  54. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  55. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  56. package/dist/.dts/eslint-plugin/index.d.ts +1 -1
  57. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  58. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  59. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  60. package/dist/{build-H4KFV44Z.js → build-F3RQS7VE.js} +218 -63
  61. package/dist/build-F3RQS7VE.js.map +1 -0
  62. package/dist/build.cjs +257 -102
  63. package/dist/build.cjs.map +1 -1
  64. package/dist/build.js +256 -101
  65. package/dist/build.js.map +1 -1
  66. package/dist/{chunk-7GVPOHDU.js → chunk-QKIQ3LZP.js} +2 -2
  67. package/dist/cli/index.js +36 -29
  68. package/dist/cli/index.js.map +1 -1
  69. package/dist/eslint-plugin/index.cjs +95 -54
  70. package/dist/eslint-plugin/index.cjs.map +1 -1
  71. package/dist/eslint-plugin/index.js +94 -53
  72. package/dist/eslint-plugin/index.js.map +1 -1
  73. package/examples/README.md +95 -0
  74. package/package.json +53 -19
  75. package/skills/env-cap/SKILL.md +91 -0
  76. package/skills/env-cap/references/api.md +220 -0
  77. package/specs/architecture.md +634 -0
  78. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  79. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  80. package/specs/decisions/0003-no-global-env-object.md +172 -0
  81. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  82. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  83. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  84. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  85. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  86. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  87. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  88. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  89. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  90. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  91. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  92. package/specs/decisions/0015-security-backport-window.md +60 -0
  93. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  94. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  95. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  96. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  97. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  98. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  99. package/specs/decisions/0022-validation-contexts.md +267 -0
  100. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  101. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  102. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  103. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  104. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  105. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  106. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  107. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  108. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  109. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  110. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  111. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  112. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  113. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  114. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  115. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  116. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  117. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  118. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  119. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  120. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  121. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  122. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  123. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  124. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  125. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  126. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  127. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  128. package/specs/generated-artifacts.md +104 -0
  129. package/specs/migrations/README.md +30 -0
  130. package/specs/migrations/from-centralized-schema.md +503 -0
  131. package/specs/migrations/from-dotenv.md +352 -0
  132. package/specs/migrations/from-envalid.md +482 -0
  133. package/specs/migrations/from-process-env.md +398 -0
  134. package/specs/migrations/from-t3-env.md +416 -0
  135. package/specs/migrations/from-zod.md +303 -0
  136. package/dist/build-H4KFV44Z.js.map +0 -1
  137. /package/dist/{chunk-7GVPOHDU.js.map → chunk-QKIQ3LZP.js.map} +0 -0
@@ -0,0 +1,87 @@
1
+ # 0049: With TypeScript 7 installed, the build-time scanner uses a bundled TypeScript 6
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/build/typescript.ts`. Supersedes the TypeScript 7 paragraph of
6
+ [ADR 0047](0047-supported-toolchain-node-22-and-typescript-5-6.md).
7
+
8
+ ## Context
9
+
10
+ The build-time scanner (`src/build/parse.ts`, `scan-dependencies.ts`, `literal-eval.ts`,
11
+ `resolution/resolve-tsconfig-paths.ts`) is written against TypeScript's classic compiler API
12
+ (`createSourceFile`, the `is*` guards, `SyntaxKind`). TypeScript 7.0 is a native rewrite that ships
13
+ no programmatic API: its `typescript` entry exports only `version` and `versionMajorMinor`. TypeScript
14
+ 7.1 will ship a new, different API. 7.0's `typescript/unstable/*` subpaths exist but are explicitly
15
+ unstable and are replaced in 7.1, so building on them would mean migrating twice.
16
+
17
+ ADR 0047 made TypeScript 7 unsupported for the build step. That left a developer on `typescript@7`
18
+ choosing between an `ERESOLVE` at install (the old peer range) and, after widening it, a scanner that
19
+ refuses to run until they rework their `package.json`.
20
+
21
+ Microsoft publishes `@typescript/typescript6`, a ~10 KB package whose only job is to expose
22
+ TypeScript 6 (`typescript@^6`, installed under the alias `@typescript/old`) as a normal, stable module.
23
+
24
+ ## Decision
25
+
26
+ - The optional `typescript` peer is `^5.0.0 || ^6.0.0 || ^7.0.0`.
27
+ - `@typescript/typescript6` (`^6.0.2`) is a dependency **and a `bundleDependencies` entry, together with
28
+ its `@typescript/old` payload**: it ships inside this package's tarball, nested under the package's own
29
+ `node_modules/`. It is the first runtime dependency of this package.
30
+ - It belongs to the build entry alone. `internal-package-contract tool compiler-isolation` walks the static import
31
+ graph of every built entry point and fails the build if the runtime, helpers, evidence, node or ESLint
32
+ plugin entry can reach the bundled compiler or the loader's `node:module`, or any entry except the
33
+ ESLint plugin (which runs inside the consumer's own ESLint process) can reach `typescript` itself -- and
34
+ fails if the build entry cannot, so the check cannot pass vacuously. A bundler following a client import
35
+ never reaches the compiler's bytes.
36
+ - `src/build/typescript.ts` resolves the compiler synchronously, once, **by capability, never by
37
+ version**: the consumer's `typescript` if it exposes `createSourceFile` (TypeScript 5 and 6 -- exactly
38
+ today's behavior), otherwise the bundled TypeScript 6. When neither works (the dependency was
39
+ stripped from an install) it returns what it found so `assertCompilerApi` fails at the scanner entry
40
+ with a readable message, before any generator writes a file.
41
+ - Scanner modules import `ts` from that loader and `import type TS from "typescript"` for type
42
+ positions, so the public declarations are unchanged for TypeScript 5 and 6 consumers.
43
+ - `scripts/typescript-compat.mjs` (CI job `typescript-compat`) packs the tarball and, for a root
44
+ `typescript` of 5, 6 and 7, runs the scanner from both the ESM and CJS entries and type-checks a
45
+ consumer.
46
+
47
+ ## Consequences
48
+
49
+ - A developer on TypeScript 7 installs env-cap and runs `./build` with no extra configuration; `tsc`
50
+ stays TypeScript 7.
51
+ - Every install of this package now carries ~26 MB unpacked (~5 MB packed) for the bundled compiler. It
52
+ is nested, so a TypeScript 6 consumer does not save it by deduplication. The runtime, helpers, evidence
53
+ and node entry points never load it, and the isolation check keeps it that way.
54
+ - Bundling is what keeps the consumer's `tsc` theirs. As an ordinary dependency, `@typescript/old`'s `tsc`
55
+ bin is hoisted and linked into `node_modules/.bin`, so installing this package turned every consumer's
56
+ `npx tsc` into TypeScript 6.0.3 -- TypeScript 5 users moved up a major and TypeScript 7 users lost the
57
+ native compiler. A nested, bundled copy is never linked. `scripts/typescript-compat.mjs` asserts that
58
+ `node_modules/.bin/tsc` is still the root compiler after install.
59
+ - Bundled code is invisible to `npm audit`, Dependabot and Socket's per-dependency view -- the reason
60
+ [ADR 0048](0048-eslint-plugin-does-not-vendor-typescript-eslint.md) refuses to vendor
61
+ `@typescript-eslint/utils`. It is accepted here because the bundle is Microsoft's published TypeScript 6
62
+ pinned by `^6.0.2`, is only reachable from the build entry, and exists to be removed once TypeScript 7.1's
63
+ API replaces it. A new TypeScript 6 patch needs a release of this package to reach consumers.
64
+ - On TypeScript 7, the scanner parses with TypeScript 6. TypeScript 7.0 is designed to match 6.0's
65
+ behavior, and the scanner fixtures are run under a 7 root in CI.
66
+ - The `./build` and `./evidence` declarations still name TypeScript AST types from `typescript`.
67
+ TypeScript 7's package exports none, so a consumer on 7 needs `skipLibCheck` for those two entry
68
+ points (the AST-typed parameters then degrade to `any`). The runtime, helpers and node entry points
69
+ type-check strictly. Typing them from the bundled package instead would break TypeScript 5/6
70
+ consumers who pass their own nodes into these Stable primitives, because two copies of
71
+ `SyntaxKind` are distinct enums.
72
+
73
+ ## Alternatives considered
74
+
75
+ - **Build on `typescript/unstable/*`.** Rejected: unstable by name, and replaced by a different API
76
+ in 7.1.
77
+ - **A plain (hoisted) dependency.** Rejected after it was built and measured: the `tsc` bin collision
78
+ above.
79
+ - **Require the consumer to alias `typescript` to `@typescript/typescript6`.** Rejected: it is the
80
+ config the package is meant to spare them -- the alias replaces their `tsc` with `tsc6`, so keeping
81
+ TypeScript 7's `tsc` needs a second alias (`@typescript/native`).
82
+ - **Always use the bundled compiler.** Rejected for now: it would make the `typescript` peer
83
+ meaningless and change which parser TypeScript 5/6 consumers' scans run under.
84
+ - **An optional peer on `@typescript/typescript6`.** Rejected: a TypeScript 7 consumer running
85
+ `./build` would have to know to install it.
86
+ - **Wait for 7.1.** Not rejected -- the 7.1 API replaces the bundled fallback when it is stable, and
87
+ the dependency can then be dropped without a breaking change.
@@ -0,0 +1,55 @@
1
+ # 0050: A variable declared in more than one contract is documented once
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/build/merge-documentation.ts`, applied at the end of `linkFiles` in
6
+ `src/build/link.ts`, and in `documentationDivergences` in `src/build/compatibility.ts`. Refines
7
+ [ADR 0005](0005-warn-not-throw-by-default.md)'s duplicate-documentation warning and builds on
8
+ [ADR 0014](0014-cross-package-schema-discovery.md).
9
+
10
+ ## Context
11
+
12
+ The process has one flat environment, so two contracts can name the same variable: a reusable package that ships
13
+ its own contract (ADR 0014), and the application that consumes it. Each declaration is processed independently, so
14
+ this is not a conflict in itself. It did make the documentation awkward: the package explains the variable, and the
15
+ application, to record something that is only true of the application (the date its own copy of a token expires, who
16
+ owns it there), had to repeat the whole explanation. Two copies of an explanation drift, and the duplicate
17
+ documentation warning fired on any field that differed, including a field only one declaration set.
18
+
19
+ ## Decision
20
+
21
+ - Documentation for the same variable is merged between a package's contract and any other contract when the
22
+ contracts are linked. Every field a declaration leaves unset is filled from a declaration of the same variable that
23
+ sets it, where one of the two comes from an allow-listed package. `metadata` is merged key by key under the same
24
+ rule.
25
+ - Two of the application's own contracts never fill each other. They are siblings, often alternatives (a service that
26
+ can run on either of two databases), and each documents the variable for itself; borrowing an owner or an expiry
27
+ from the other would describe a credential the contract does not use.
28
+ - A field a declaration sets itself is never replaced.
29
+ - When several declarations set a field, the one from a package found first wins; the application's own contracts
30
+ fill a package's gaps only when no package sets the field, and only when every one of them that sets it agrees
31
+ (two alternatives that disagree give the package neither value). Metadata follows the same rule key by key.
32
+ - A variable counts as documented when it, or a declaration it can be filled from, is.
33
+ - `DUPLICATE_VARIABLE_DOCUMENTATION` is reported only for a field both declarations set, to different values. A field
34
+ only one of them sets is not a disagreement.
35
+
36
+ ## Consequences
37
+
38
+ - An application documents a variable a package already explains by naming it again with only what is its own, for
39
+ example `{ expiresAt: "2027-01-01" }`. The explanation stays in one place and cannot drift from the package's.
40
+ - Both declarations then show the merged documentation in every output, so a reader sees the same thing wherever
41
+ they look, except for a field the two set differently, which each keeps as its own; the catalog still lists the
42
+ variable under each contract that declares it.
43
+ - Two declarations that set a field differently still differ afterwards and are still reported, so a deliberate
44
+ override is visible rather than silently resolved.
45
+ - The processor and validator comparisons are unchanged: declarations that carry different implementations are
46
+ still reported, since a merge cannot make them agree.
47
+ - Reversible: removing the merge step restores the previous behaviour, apart from the comparison change.
48
+
49
+ ## Alternatives considered
50
+
51
+ - **Let the application's declaration win.** It would hide that a package's explanation was overridden, and an
52
+ application would silently shadow a security note.
53
+ - **A separate "overlay" API for an application's additions.** A second way to say the same thing, for something the
54
+ existing `documentEnv()` entry already expresses.
55
+ - **Keep reporting any difference.** It keeps the copy-everything habit that makes the copies drift.
@@ -0,0 +1,104 @@
1
+ # Generated artifacts: what `env-cap` produces, and what it deliberately doesn't
2
+
3
+ This is the canonical place — for a human or an AI agent working in this
4
+ repository or a consuming project — to check before assuming `env-cap`
5
+ generates something it doesn't. Every artifact below is produced by
6
+ `generateEnvArtifacts()` (or, for the manifest/evidence outputs only, the
7
+ `env-cap` CLI, its thin wrapper for those two — see [ADR
8
+ 0046](decisions/0046-cli-restricted-to-runtime-and-evidence-output.md): the
9
+ documentation catalog, `.env.example`, and the ownership report have no CLI
10
+ flag at all, only a direct `generateDocumentation()`/`generateUsageReport()`
11
+ call); nothing here is generated by a separate, independently-derived
12
+ pipeline. Concretely:
13
+ `computeArtifacts` (the function both `generateEnvArtifacts` and
14
+ `checkArtifacts` share) runs one `assembleProject()` parse/link pass, then
15
+ builds all seven canonical fact models (ADR 0024) from that single result —
16
+ every artifact in this file is a projection of that same run's models, not a
17
+ second, independently-assembled source. `--evidence <path>` writes the
18
+ composed Evidence Model to disk directly, as JSON, for a project that wants
19
+ the canonical artifact itself rather than only its Markdown projections.
20
+
21
+ **Every artifact in this table is evidence that can _support_ a review
22
+ process — a security review, a privacy review, a platform audit — never a
23
+ compliance claim.** Static analysis of one repository cannot, by itself,
24
+ establish compliance with any external standard. Every rendered artifact
25
+ that carries this claim opens with the same disclaimer
26
+ (`evidenceDisclaimer()` in `generated-banner.ts`, byte-identical to
27
+ data-cap's own):
28
+
29
+ > Machine-generated engineering artifact assembled from statically-provable
30
+ > code facts and author-declared documentation. It can support a security,
31
+ > privacy, or compliance review. It does not itself establish compliance
32
+ > with any standard.
33
+
34
+ ## Declared vs. proven vs. evidence
35
+
36
+ Every fact in every generated artifact is one of exactly three kinds, and a
37
+ rendering function may never blend them or imply one is another:
38
+
39
+ - **Declared** — metadata the author wrote via `documentEnv()`'s
40
+ `VariableDocs`/`ContractDocs`: `description`, `owner`, `sensitivity`,
41
+ `expiresAt`, `refreshInstructions`, `setupInstructions`, `required`,
42
+ `deprecated`/`deprecatedReason`/`removeBy`, `renamedFrom`, `purpose`,
43
+ `legalBasis`, `retention`, `dataResidency`, `auditRequired`, `metadata`.
44
+ Presence is checked; correctness, adequacy, and enforcement are never
45
+ claimed. A report may say a variable's retention policy is _"documented,"_
46
+ never that it is _"sufficient"_ or _"enforced."_
47
+ - **Proven** — facts derived by AST analysis of the actual source: whether a
48
+ declared variable is actually read anywhere in the scanned surface
49
+ (`UNCONSUMED_OWNED_VARIABLE`), which files import/reference a given
50
+ contract (Dependency Model), and every exclusive-group/compatibility
51
+ conflict between contracts (`FindingCode`'s compatibility family). These
52
+ are statically provable from the code that exists today, in this
53
+ repository, at analysis time.
54
+ - **A third case, named explicitly because it's neither** —
55
+ `VariableDocs.evidence.dynamicAccess` (ADR 0053-equivalent citation
56
+ mechanism, mirroring data-cap's identical design) is declared, like every
57
+ other governance field, but unlike every other one it's re-verified every
58
+ run against a persisted content hash of the cited file
59
+ (`MISSING_DYNAMIC_ACCESS_CITATION`/`STALE_DYNAMIC_ACCESS_CITATION`). A
60
+ passing check establishes only that the citation is currently _supported
61
+ by its own citation/integrity state_ — the cited file exists and hasn't
62
+ visibly changed since the developer wrote it — never that the described
63
+ access has been proven to happen there. No rendering of this field ever
64
+ uses "verified" or "proven" language for this reason.
65
+
66
+ ## Built in this release
67
+
68
+ | Artifact | Generator | What it answers |
69
+ | -------------------------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
70
+ | **Manifest** (`--location`) | `generateEnvManifest` (Contract Model) | A single, deterministic `.ts` file re-exporting every _active_ contract — a projection of the Contract Model, not a second source of truth. `runtime/validate.ts` validates real `process.env` values against exactly this manifest. |
71
+ | **Documentation catalog** (`generateDocumentation()` — no CLI flag, ADR 0046) | `generateDocumentation` | Per-contract variables: `description` ("why"), `owner`/`sensitivity`/`purpose`/`legalBasis`/`retention`/`dataResidency` (labeled declared, not verified), plus a live "expiring soon or already expired" section sourced from the Lifecycle Model. |
72
+ | **`.env.example`** (`generateDocumentation()`'s `envExample` option — no CLI flag, ADR 0046) | `generateDocumentation` | One line per active variable, generated from the same declared metadata the documentation catalog renders — never hand-maintained, never a second copy of the schema to drift from the real one. |
73
+ | **Dependency & Ownership report** (`generateUsageReport()` — no CLI flag, ADR 0046) | `generateUsage` (Dependency + Ownership Model) | The owner → variables matrix, plus a real, in-repo, AST-proven consumer graph: which files actually read which variable — never guessed at. `UNCONSUMED_OWNED_VARIABLE`/`ABANDONED_CONTRACT` are warnings; `UNRESOLVED_CONSUMER`/`INDETERMINATE_OWNERSHIP` stay info, escalated only by `--strict-ownership`. |
74
+ | **Evidence Model** (`--evidence`, ADR 0038) | `generateEvidenceModel` | The composed `EvidenceModel` (ADR 0024's seventh model) as JSON, plus a paired `.fingerprint` sidecar — Contract/Dependency/Ownership/Finding/Lifecycle/Change models, whichever were computed this run. Always composed in-memory even without this flag; the flag only controls whether it's additionally written to disk. |
75
+ | **JSON report** (`--json`) | CLI (`src/cli/json.ts`) | The full result — every finding, every generator's output, and the composed Evidence Model — as one versioned envelope (`@maverickcer/env-cap/schema`), for a CI step or another tool to consume without parsing human-readable text. |
76
+ | **Drift check** (`--check`) | `checkArtifacts` | Recomputes every requested artifact and diffs it against disk — writes nothing, exits non-zero if anything is stale or missing. Its exit code reflects staleness only, independent of `--strict*` finding severity. |
77
+ | **SARIF log** | `buildSarifLog` (library export) | A SARIF 2.1.0 adapter over the Finding Model, for a security-tooling pipeline that already ingests SARIF. Not CLI-wired — an ordinary consumer of the public Finding Model type, called directly by whichever project needs it (the same boundary Phase 4/5's own generator scripts sit behind). |
78
+
79
+ ## Canonical fact models (ADR 0024)
80
+
81
+ Seven canonical, versioned, JSON-serializable models — the machine-readable
82
+ surface every rendered artifact above is a projection of, and what
83
+ `defineEvidenceProjection()` consumers (below) read instead of re-deriving
84
+ facts from raw source.
85
+
86
+ | Model | Builder | What it answers |
87
+ | ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
88
+ | Contract Model | `buildContractModel` | Every discovered contract (active or not) and its variables — the schema shape itself, projected and sorted deterministically. |
89
+ | Dependency Model | `buildDependencyModel` | Every proven consumer relationship, indexed by contract/variable and by consuming file — the fact the ownership report projects, computed once. |
90
+ | Ownership Model | `buildOwnershipModel` | Every contract and variable's effective owner, plus first-class `unownedContracts`/`unownedVariables` arrays. |
91
+ | Finding Model | `buildFindingModel` | Every rule violation and derived risk signal, unified behind one shape with a stable `code` and a structured `EvidenceReference` — the input the SARIF adapter and Evidence Model compose from. |
92
+ | Lifecycle Model | `buildLifecycleModel` | Every contract and variable's lifecycle data: expiry, deprecation, rename correlation. |
93
+ | Change Model | `buildChangeModel` | What changed since the last persisted evidence snapshot — the manifest diff, keyed for a "changes since last report" section. |
94
+ | Evidence Model | `generateEvidenceModel` | The composition of the other six into one artifact — what every reference projection below reads. Two of the seven are separately published as JSON Schema (`@maverickcer/env-cap/schema`, `@maverickcer/env-cap/schema/contract-model`); the rest are TypeScript-typed only, not yet independently schema'd. |
95
+
96
+ A first wave of reference projections ships alongside the models themselves
97
+ — `configurationReference`, `ownershipSummary`, and `expiringSoonReport`
98
+ (all built through `defineEvidenceProjection()`), plus `buildSarifLog` (a
99
+ SARIF 2.1.0 adapter over Finding Model). Every one of these is an ordinary
100
+ consumer of the public model types above — none has a privileged internal
101
+ path a downstream tool couldn't also use. Phase 5's open-standard
102
+ alignment-evidence generator (see `specs/decisions/`, once written) is
103
+ architecturally no different: another `defineEvidenceProjection()` consumer,
104
+ not a bespoke script bypassing this model.
@@ -0,0 +1,30 @@
1
+ # Migrating to env-cap
2
+
3
+ `env-cap` is not a replacement for environment validation libraries.
4
+
5
+ If your application already uses Zod, envalid, t3-env, Joi, or another validation system, those tools solve an important problem: ensuring environment values are valid.
6
+
7
+ `env-cap` solves a different problem: ensuring environment configuration has clear ownership, discoverability, and lifecycle visibility as applications grow.
8
+
9
+ Migration does not require replacing your validation approach immediately. The recommended path is to move configuration ownership into capability boundaries first, then adopt the runtime validation features that best fit your application.
10
+
11
+ ## Guides
12
+
13
+ - [From `dotenv`](from-dotenv.md) -- keep `dotenv` loading values, add capability-owned contracts on top.
14
+ - [From raw `process.env`](from-process-env.md) -- replace scattered `process.env.X` access with owned, validated contracts.
15
+ - [From a centralized environment schema](from-centralized-schema.md) -- split a single `env.ts`/`env.schema.ts` file into capability-owned schemas.
16
+ - [From Zod](from-zod.md) -- keep Zod for validation, move ownership to capabilities.
17
+ - [From envalid](from-envalid.md) -- keep envalid's validators, move ownership to capabilities.
18
+ - [From t3-env](from-t3-env.md) -- keep t3-env's client/server split conceptually, replace the centralized object with capability-owned contracts.
19
+
20
+ ## Migration strategy
21
+
22
+ Migrate incrementally:
23
+
24
+ 1. Identify capability boundaries.
25
+ 2. Move environment requirements next to the capability that uses them.
26
+ 3. Replace direct `process.env` access with capability-owned contracts.
27
+ 4. Generate project-wide configuration artifacts through build tooling.
28
+ 5. Remove the centralized schema when no longer needed.
29
+
30
+ The goal is not fewer environment variables. The goal is clearer ownership.