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