@maverickcer/env-cap 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ADOPTION.md +144 -0
- package/AGENTS.md +146 -0
- package/CHANGELOG.md +438 -0
- package/CODE_OF_CONDUCT.md +124 -0
- package/CODE_REVIEW.md +200 -0
- package/CONTRIBUTING.md +131 -0
- package/GUIDE.md +1214 -0
- package/PROMPT.md +89 -0
- package/README.md +92 -200
- package/RELEASING.md +160 -0
- package/SECURITY.md +270 -0
- package/SUPPORT.md +76 -0
- package/VERSIONING.md +118 -0
- package/benchmarks/READING-BENCHMARKS.md +197 -0
- package/benchmarks/README.md +126 -0
- package/benchmarks/WRITING-BENCHMARKS.md +252 -0
- package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
- package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
- package/dist/.dts/_ipc/build-fs.d.ts +53 -0
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts/_ipc/display-path.d.ts +27 -0
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts/_ipc/glob.d.ts +22 -0
- package/dist/.dts/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts +34 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts/_ipc/typescript.d.ts +20 -0
- package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts/build/compatibility.d.ts.map +1 -1
- package/dist/.dts/build/compiler-api.d.ts +3 -6
- package/dist/.dts/build/compiler-api.d.ts.map +1 -1
- package/dist/.dts/build/display-path.d.ts +3 -21
- package/dist/.dts/build/display-path.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +21 -42
- package/dist/.dts/build/generated-banner.d.ts.map +1 -1
- package/dist/.dts/build/glob.d.ts +3 -15
- package/dist/.dts/build/glob.d.ts.map +1 -1
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/merge-documentation.d.ts +35 -0
- package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/build/types.d.ts +4 -53
- package/dist/.dts/build/types.d.ts.map +1 -1
- package/dist/.dts/build/typescript.d.ts +3 -17
- package/dist/.dts/build/typescript.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
- package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/index.d.ts +1 -1
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
- package/dist/{build-H4KFV44Z.js → build-WKDIAWF7.js} +198 -60
- package/dist/build-WKDIAWF7.js.map +1 -0
- package/dist/build.cjs +194 -56
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +194 -56
- package/dist/build.js.map +1 -1
- package/dist/{chunk-7GVPOHDU.js → chunk-KEGYUHBU.js} +2 -2
- package/dist/cli/index.js +36 -29
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +84 -54
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +83 -53
- package/dist/eslint-plugin/index.js.map +1 -1
- package/examples/README.md +95 -0
- package/package.json +48 -14
- package/skills/env-cap/SKILL.md +91 -0
- package/skills/env-cap/references/api.md +220 -0
- package/specs/architecture.md +634 -0
- package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
- package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
- package/specs/decisions/0003-no-global-env-object.md +172 -0
- package/specs/decisions/0004-no-client-server-package-split.md +116 -0
- package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
- package/specs/decisions/0006-self-redacting-contracts.md +124 -0
- package/specs/decisions/0007-processor-not-transformer.md +109 -0
- package/specs/decisions/0008-gzip-size-budget.md +173 -0
- package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
- package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
- package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
- package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
- package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
- package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
- package/specs/decisions/0015-security-backport-window.md +60 -0
- package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
- package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
- package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
- package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
- package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
- package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
- package/specs/decisions/0022-validation-contexts.md +267 -0
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
- package/specs/decisions/0024-fact-model-architecture.md +144 -0
- package/specs/decisions/0025-contract-model-json-projection.md +105 -0
- package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
- package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
- package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
- package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
- package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
- package/specs/decisions/0031-evidence-entry-point.md +85 -0
- package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
- package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
- package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
- package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
- package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
- package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
- package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
- package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
- package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
- package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
- package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
- package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
- package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
- package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
- package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
- package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
- package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
- package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
- package/specs/generated-artifacts.md +104 -0
- package/specs/migrations/README.md +30 -0
- package/specs/migrations/from-centralized-schema.md +503 -0
- package/specs/migrations/from-dotenv.md +352 -0
- package/specs/migrations/from-envalid.md +482 -0
- package/specs/migrations/from-process-env.md +398 -0
- package/specs/migrations/from-t3-env.md +416 -0
- package/specs/migrations/from-zod.md +303 -0
- package/dist/build-H4KFV44Z.js.map +0 -1
- /package/dist/{chunk-7GVPOHDU.js.map → chunk-KEGYUHBU.js.map} +0 -0
|
@@ -0,0 +1,634 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
Canonical current-state description of how `env-cap` is built and what guarantees its architecture
|
|
4
|
+
provides. [`decisions/`](decisions/) holds the reasoning trail (the ADRs); this document is the
|
|
5
|
+
destination those decisions arrived at, not the argument for them. For the product overview and
|
|
6
|
+
integration guidance, see [README.md](../README.md) and [GUIDE.md](../GUIDE.md).
|
|
7
|
+
|
|
8
|
+
- [Purpose](#purpose)
|
|
9
|
+
- [Core invariants](#core-invariants)
|
|
10
|
+
- [The entry points](#the-entry-points)
|
|
11
|
+
- [`runtime/` — define, validate, cache, and expose environment values](#runtime--define-validate-cache-and-expose-environment-values)
|
|
12
|
+
- [`build/` — discover, analyze, link, and generate artifacts](#build--discover-analyze-link-and-generate-artifacts)
|
|
13
|
+
- [`helpers/` — optional processors and validators](#helpers--optional-processors-and-validators)
|
|
14
|
+
- [Documentation is parallel to runtime, not part of runtime state](#documentation-is-parallel-to-runtime-not-part-of-runtime-state)
|
|
15
|
+
- [Data flow](#data-flow)
|
|
16
|
+
- [Module layout](#module-layout)
|
|
17
|
+
- [Architectural decisions](#architectural-decisions)
|
|
18
|
+
|
|
19
|
+
## Purpose
|
|
20
|
+
|
|
21
|
+
`env-cap` treats an application's environment configuration as a set of capability-owned contracts,
|
|
22
|
+
not as loose strings read off `process.env`. It does not perform secret storage, rotation, or
|
|
23
|
+
retrieval itself: a capability declares the environment variables it depends on (`createEnv()`) and,
|
|
24
|
+
optionally, the documentation metadata that describes them (`documentEnv()`); `env-cap` validates
|
|
25
|
+
those declarations against real values at startup, and separately, at build time, discovers every
|
|
26
|
+
declared contract across a project to produce manifests, documentation, ownership reports, and a
|
|
27
|
+
canonical Evidence Model.
|
|
28
|
+
|
|
29
|
+
The architecture keeps two concerns from collapsing into one:
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
runtime -> validated, typed access to configuration a capability already declared owning
|
|
33
|
+
build-time -> project-wide discovery, documentation, and ownership visibility
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
The runtime never discovers anything; it only validates what a generated manifest already told it to
|
|
37
|
+
expect. Build-time tooling never runs at startup; it only ever runs as an explicit CI/npm-script step.
|
|
38
|
+
Neither one substitutes for the other, and a consumer can use either independently — validation with no
|
|
39
|
+
generated artifacts at all (a hand-written manifest works), or discovery/documentation with no runtime
|
|
40
|
+
validation (a project that only wants the ownership report).
|
|
41
|
+
|
|
42
|
+
## Core invariants
|
|
43
|
+
|
|
44
|
+
These are the guarantees the rest of the design exists to uphold. Each links to the section that
|
|
45
|
+
describes its mechanics.
|
|
46
|
+
|
|
47
|
+
### Runtime and build-time are strictly separate
|
|
48
|
+
|
|
49
|
+
The runtime (`.`, `./helpers`) has zero npm dependencies, never touches the filesystem, never
|
|
50
|
+
discovers files, and never imports Node-specific APIs. `./build` is Node-only developer tooling,
|
|
51
|
+
never meant to reach a browser bundle — bundle-size and tree-shaking tests fail if runtime consumers
|
|
52
|
+
accidentally receive build tooling or unrelated helper code. See
|
|
53
|
+
[`runtime/`](#runtime--define-validate-cache-and-expose-environment-values) and
|
|
54
|
+
[`build/`](#build--discover-analyze-link-and-generate-artifacts) below, and
|
|
55
|
+
[ADR 0004](decisions/0004-no-client-server-package-split.md).
|
|
56
|
+
|
|
57
|
+
### The build tool never imports or executes a schema file
|
|
58
|
+
|
|
59
|
+
Discovery is AST analysis only (`build/parse.ts`, the TypeScript compiler API) — a schema file's
|
|
60
|
+
`createEnv()`/`documentEnv()` calls are read as syntax, never imported or run. This preserves the
|
|
61
|
+
safety boundary required for CI environments and large monorepos: a malicious or merely broken schema
|
|
62
|
+
file can't execute code just by being discovered. See
|
|
63
|
+
[`build/`](#build--discover-analyze-link-and-generate-artifacts) and
|
|
64
|
+
[ADR 0002](decisions/0002-static-analysis-never-execution.md).
|
|
65
|
+
|
|
66
|
+
### `./build` does not acquire filesystem access implicitly
|
|
67
|
+
|
|
68
|
+
`./build` never imports `node:fs` itself — every public options object requires a caller-supplied
|
|
69
|
+
`BuildFileSystem` capability. The `env-cap` CLI (`src/cli/`) is the executable boundary that
|
|
70
|
+
constructs the real `node:fs/promises` adapter and hands it in; a consumer running the generators
|
|
71
|
+
from their own Node script imports that same adapter from `@maverickcer/env-cap/node`. This is the
|
|
72
|
+
same discipline `repo-contract`'s ADR-0011 established for `spawn`/`env`: a library surface should
|
|
73
|
+
not implicitly acquire a powerful ambient capability a caller did not explicitly provide. See
|
|
74
|
+
[ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md).
|
|
75
|
+
|
|
76
|
+
### Documentation is inert at runtime
|
|
77
|
+
|
|
78
|
+
`documentEnv()` is a source-level marker the build system discovers through AST analysis — it stores
|
|
79
|
+
nothing in memory and adds no fields to a runtime contract. `createEnv()`'s runtime contracts and
|
|
80
|
+
`documentEnv()`'s documentation metadata are separate concerns that happen to share a source file, not
|
|
81
|
+
one pipeline. See
|
|
82
|
+
[Documentation is parallel to runtime, not part of runtime state](#documentation-is-parallel-to-runtime-not-part-of-runtime-state).
|
|
83
|
+
|
|
84
|
+
### Runtime contracts are self-redacting
|
|
85
|
+
|
|
86
|
+
A contract's own `toString`/`console.log`/JSON representation never exposes resolved values —
|
|
87
|
+
`console.log(paymentsEnv)` prints `EnvContract("payments") { 1 variable(s) }`, never the underlying
|
|
88
|
+
secret. Explicit property access (`paymentsEnv.STRIPE_KEY`) remains required to read a value. See
|
|
89
|
+
[ADR 0006](decisions/0006-self-redacting-contracts.md) and [SECURITY.md](../SECURITY.md).
|
|
90
|
+
|
|
91
|
+
### Validation contexts gate participation, nothing else
|
|
92
|
+
|
|
93
|
+
A variable with no `context` participates in every run; a variable with a `context` participates only
|
|
94
|
+
when `activeContexts` contains that exact string — no prefix matching, no inference from ambient
|
|
95
|
+
signals, no effect on `EnvContract`'s TypeScript shape, and no authorization/bundling meaning. See
|
|
96
|
+
[Validation context invariants](#validation-context-invariants) below and
|
|
97
|
+
[ADR 0022](decisions/0022-validation-contexts.md).
|
|
98
|
+
|
|
99
|
+
### Manifest compatibility is the one blocking category
|
|
100
|
+
|
|
101
|
+
Of the three finding categories a generation run can produce — manifest compatibility/exclusive-group
|
|
102
|
+
issues, documentation completeness, and dependency ownership — only the first ever blocks
|
|
103
|
+
(`EnvProjectGenerationError`, nothing written). Documentation and ownership issues are heuristic
|
|
104
|
+
signals with real, common false-positive causes; they're recorded as `Finding`s on the persisted
|
|
105
|
+
Evidence Model instead, for a consumer to gate on explicitly if they want that enforced. See
|
|
106
|
+
[Data flow](#data-flow) and [ADR 0038](decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md).
|
|
107
|
+
|
|
108
|
+
### The Evidence Model is always computed, independent of what's requested
|
|
109
|
+
|
|
110
|
+
`computeArtifacts()` always builds the full `EvidenceModel` — the manifest/docs/ownership/`--evidence`
|
|
111
|
+
flags only control which artifacts are additionally _written to disk_, never whether the underlying
|
|
112
|
+
model is computed. See [Data flow](#data-flow) and
|
|
113
|
+
[ADR 0038](decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md).
|
|
114
|
+
|
|
115
|
+
## The entry points
|
|
116
|
+
|
|
117
|
+
`package.json` `exports` is the authoritative list (this section is the map of what each one is for, and TypeDoc generates the reference for each).
|
|
118
|
+
|
|
119
|
+
```text
|
|
120
|
+
|
|
121
|
+
src/
|
|
122
|
+
├── runtime/ @maverickcer/env-cap (runtime library)
|
|
123
|
+
├── build/ @maverickcer/env-cap/build (Node-only build tooling)
|
|
124
|
+
├── helpers/ @maverickcer/env-cap/helpers (optional utilities)
|
|
125
|
+
├── evidence/ @maverickcer/env-cap/evidence (Evidence Model projections)
|
|
126
|
+
├── node/ @maverickcer/env-cap/node (the Node-backed BuildFileSystem adapter)
|
|
127
|
+
└── eslint-plugin/ @maverickcer/env-cap/eslint-plugin (capability-owned-access lint rules)
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Each directory corresponds to a separate package export with its own build
|
|
132
|
+
output (configured in `tsup.config.ts`). Importing one entry point does not
|
|
133
|
+
include the implementation of the others.
|
|
134
|
+
|
|
135
|
+
`build`, `eslint-plugin`, and `runtime` contain their own implementation with
|
|
136
|
+
zero cross-folder dependency, including internal utilities.
|
|
137
|
+
`globToRegExp()`, for example, is needed by both `build/discover.ts` and
|
|
138
|
+
`eslint-plugin/no-raw-process-env.ts`; rather than living in a shared
|
|
139
|
+
internal module both would depend on, each directory owns its own copy
|
|
140
|
+
(`build/glob.ts`, `eslint-plugin/glob.ts` -- see ADR 0017's "Alternatives
|
|
141
|
+
considered"). `helpers` and `evidence` each have exactly one cross-folder
|
|
142
|
+
import, and both are structural, not incidental. `helpers`' `processors.ts`/
|
|
143
|
+
`validators.ts` import `Processor`/`Validator` as types (erased at compile
|
|
144
|
+
time) from `runtime/index.ts`, because a helper's whole job is producing a
|
|
145
|
+
value that type-checks as the exact shape `createEnv()` expects -- that
|
|
146
|
+
contract can't be expressed without referencing runtime's own type.
|
|
147
|
+
`evidence/define-projection.ts` imports `EvidenceModel` as a type (also
|
|
148
|
+
erased at compile time) from `build/evidence-model.ts`, for the same reason:
|
|
149
|
+
a projector's whole job is a function _of_ that shape, which can't be named
|
|
150
|
+
without referencing it -- see ADR 0031. Neither edge is an oversight: it's
|
|
151
|
+
what lets any of these five directories move to its own repository
|
|
152
|
+
independent of the others, with `helpers`/`evidence` simply gaining
|
|
153
|
+
`env-cap`/`env-cap-build` as an ordinary
|
|
154
|
+
dependency the way any package depending on another package's published
|
|
155
|
+
types would.
|
|
156
|
+
|
|
157
|
+
`src/cli/` (the `env-cap` bin, not a `package.json#exports` subpath) has the
|
|
158
|
+
same kind of real, intentional dependency on `build` -- it imports
|
|
159
|
+
`@maverickcer/env-cap/build`'s public surface (`src/build/index.ts`)
|
|
160
|
+
directly, never an internal `build/*.ts` file, since generating artifacts
|
|
161
|
+
from the command line requires the same engine `./build` exports. It is also
|
|
162
|
+
the one place `node:fs` is acquired to build the concrete `BuildFileSystem`
|
|
163
|
+
adapter `./build` requires (see [ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
|
|
164
|
+
A split-out `cli` package would simply declare `env-cap-build`
|
|
165
|
+
as a normal npm dependency.
|
|
166
|
+
|
|
167
|
+
This separation is enforced through automated checks. The tree-shaking tests
|
|
168
|
+
and bundle-size checks fail if runtime consumers accidentally receive build
|
|
169
|
+
tooling or unrelated helper code, and the `AmbientCapabilities` check
|
|
170
|
+
fails if a published library entrypoint's packed output reaches for
|
|
171
|
+
`node:fs` outside the CLI/`./node`/`./eslint-plugin` exceptions.
|
|
172
|
+
|
|
173
|
+
```mermaid
|
|
174
|
+
flowchart TB
|
|
175
|
+
subgraph RUNTIME["package root - runtime (isomorphic)<br/>zero npm dependencies, no fs, no Node APIs"]
|
|
176
|
+
CREATE["createEnv()"]
|
|
177
|
+
DOCFN["documentEnv()<br/>(inert at runtime - a marker only)"]
|
|
178
|
+
VALIDATE["validateEnv()"]
|
|
179
|
+
REG["registry (WeakMap) + cache"]
|
|
180
|
+
end
|
|
181
|
+
|
|
182
|
+
subgraph HELPERS["./helpers - optional"]
|
|
183
|
+
PROC["processors.*"]
|
|
184
|
+
VALID["validators.*"]
|
|
185
|
+
end
|
|
186
|
+
|
|
187
|
+
subgraph BUILD["./build - Node-only, dev/CI tooling<br/>never imports node:fs (ADR 0040)"]
|
|
188
|
+
DISCOVER["discoverSchemaFiles()"]
|
|
189
|
+
PARSE["parseSchemaFile()<br/>TS compiler API - parses AST,<br/>never imports/executes the file"]
|
|
190
|
+
LINK["linkFiles()"]
|
|
191
|
+
CHECKS["detectCompatibilityIssues()<br/>detectExclusiveGroupIssues()"]
|
|
192
|
+
GEN["generateEnvManifest / Documentation /<br/>UsageReport / EnvArtifacts"]
|
|
193
|
+
CHECKMODE["checkEnvArtifacts() - the --check flag"]
|
|
194
|
+
DISCOVER --> PARSE --> LINK --> CHECKS --> GEN
|
|
195
|
+
GEN -.->|"same discovery + link,<br/>compare instead of write"| CHECKMODE
|
|
196
|
+
end
|
|
197
|
+
|
|
198
|
+
subgraph EVIDENCE["./evidence - isomorphic, optional"]
|
|
199
|
+
DEFPROJ["defineEvidenceProjection()"]
|
|
200
|
+
end
|
|
201
|
+
|
|
202
|
+
subgraph ESLINT["./eslint-plugin"]
|
|
203
|
+
RULE["no-raw-process-env / no-node-fs rules"]
|
|
204
|
+
end
|
|
205
|
+
|
|
206
|
+
subgraph CLIBIN["env-cap bin - src/cli/<br/>constructs the real node:fs adapter"]
|
|
207
|
+
MAIN["parseArgs() / main()"]
|
|
208
|
+
end
|
|
209
|
+
|
|
210
|
+
HELPERS -->|"type-only import:<br/>Processor / Validator"| RUNTIME
|
|
211
|
+
EVIDENCE -->|"type-only import:<br/>EvidenceModel"| BUILD
|
|
212
|
+
CLIBIN -->|"imports build's public<br/>src/build/index.ts +<br/>supplies BuildFileSystem"| BUILD
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
`build`, `eslint-plugin`, and `runtime` have no edges between them above
|
|
216
|
+
because none exist: each owns its own copy of shared internals (e.g.
|
|
217
|
+
`glob.ts`) rather than importing from another entry point. `helpers`' and
|
|
218
|
+
`evidence`'s single edges are both type-only and erased at compile time.
|
|
219
|
+
This is what the tree-shaking and bundle-size tests in the previous
|
|
220
|
+
paragraph actually verify.
|
|
221
|
+
|
|
222
|
+
## `runtime/` — define, validate, cache, and expose environment values
|
|
223
|
+
|
|
224
|
+
The runtime package contains only the functionality required while an
|
|
225
|
+
application is running.
|
|
226
|
+
|
|
227
|
+
Its core concepts are limited to:
|
|
228
|
+
|
|
229
|
+
- `default`
|
|
230
|
+
- `processor`
|
|
231
|
+
- `validator`
|
|
232
|
+
- `context` (a variable's validation context, see below and ADR 0022)
|
|
233
|
+
|
|
234
|
+
These are the only pieces of information required to transform raw
|
|
235
|
+
environment values into validated application configuration.
|
|
236
|
+
|
|
237
|
+
`createEnv()` (`runtime/create.ts`) creates a feature-owned environment
|
|
238
|
+
contract. `validateEnv()` (`runtime/validate.ts`) executes every registered
|
|
239
|
+
contract's processing pipeline against the provided environment values and
|
|
240
|
+
caches successful results through `runtime/cache.ts`. Before running that
|
|
241
|
+
pipeline for a given variable, it first checks whether the variable's
|
|
242
|
+
`context` (if any) is in the run's `activeContexts` -- a variable that
|
|
243
|
+
doesn't match is skipped entirely (no default/processor/validator runs) and
|
|
244
|
+
stays in its not-ready state, exactly as if this run had never happened for
|
|
245
|
+
it.
|
|
246
|
+
|
|
247
|
+
### Validation context invariants
|
|
248
|
+
|
|
249
|
+
A **validation context** is an application-defined string a variable may
|
|
250
|
+
declare (`context`) and a validation run may activate (`activeContexts`).
|
|
251
|
+
env-cap never interprets, detects, or infers these strings itself -- the
|
|
252
|
+
application always computes and passes `activeContexts` explicitly. The
|
|
253
|
+
following invariants are load-bearing; none should be relaxed without a new
|
|
254
|
+
ADR (see [ADR 0022](decisions/0022-validation-contexts.md)):
|
|
255
|
+
|
|
256
|
+
1. **Matching.** A variable without a `context` participates in every
|
|
257
|
+
validation run. A variable with a `context` participates only when
|
|
258
|
+
`activeContexts` contains that exact string. No prefix matching, no
|
|
259
|
+
wildcards, no hierarchy, no inheritance.
|
|
260
|
+
2. **Not runtime detection.** env-cap never infers, detects, or defaults
|
|
261
|
+
`activeContexts` from any ambient signal (`window`, `NODE_ENV`, a
|
|
262
|
+
bundler `define`, etc.). The application always computes and passes it
|
|
263
|
+
explicitly.
|
|
264
|
+
3. **Not cache identity.** `validateEnv()` stays one-shot per process: a
|
|
265
|
+
second call while already `"ready"` returns the first call's result
|
|
266
|
+
outright, without inspecting the second call's `activeContexts`. There
|
|
267
|
+
is no per-context cache dimension.
|
|
268
|
+
4. **Not a type-level concept.** Validation contexts affect participation
|
|
269
|
+
at `validateEnv()` time only -- they do not alter `EnvContract`'s
|
|
270
|
+
TypeScript shape, `InferEnvValue`, or any generated type. Every schema
|
|
271
|
+
key remains a property of `EnvContract<S>` regardless of `context`; an
|
|
272
|
+
out-of-context key throws `EnvNotReadyError` at access time, exactly
|
|
273
|
+
like any value read before `validateEnv()` has run.
|
|
274
|
+
5. **Not authorization.** Validation contexts are not an authentication,
|
|
275
|
+
authorization, or access-control mechanism. They determine validation
|
|
276
|
+
participation only, never who may read a resolved value.
|
|
277
|
+
6. **Not a bundling/security boundary.** Separate discovery/manifests (ADR 0004) remain the real mechanism for keeping server-only source out of
|
|
278
|
+
client-bound code. `activeContexts` filtering happens after the schema
|
|
279
|
+
is already wherever it's going to be -- it does not remove a variable's
|
|
280
|
+
definition (or its `default` value) from a bundle that imports it.
|
|
281
|
+
|
|
282
|
+
`runtime/registry.ts` maintains the internal relationship between created
|
|
283
|
+
contracts and their schemas using a private `WeakMap`. This keeps internal
|
|
284
|
+
implementation details inaccessible to application code while allowing the
|
|
285
|
+
runtime to resolve values safely.
|
|
286
|
+
|
|
287
|
+
`runtime/errors.ts` defines the runtime error types used for validation
|
|
288
|
+
failures and invalid access states.
|
|
289
|
+
|
|
290
|
+
The runtime package intentionally:
|
|
291
|
+
|
|
292
|
+
- does not access the filesystem
|
|
293
|
+
- does not parse source code
|
|
294
|
+
- does not depend on Node-specific APIs
|
|
295
|
+
- has zero runtime npm dependencies
|
|
296
|
+
|
|
297
|
+
This keeps the runtime small, portable, and safe to include in browser,
|
|
298
|
+
edge, serverless, and Node environments.
|
|
299
|
+
|
|
300
|
+
## `build/` — discover, analyze, link, and generate artifacts
|
|
301
|
+
|
|
302
|
+
The build package contains developer tooling only. It exists to analyze a
|
|
303
|
+
project's environment schemas and generate artifacts; it is not part of an
|
|
304
|
+
application's runtime execution path.
|
|
305
|
+
|
|
306
|
+
The build pipeline is responsible for:
|
|
307
|
+
|
|
308
|
+
- discovering schema files (`build/discover.ts`)
|
|
309
|
+
- parsing TypeScript source into AST representations (`build/parse.ts`)
|
|
310
|
+
- evaluating safe literal expressions (`build/literal-eval.ts`)
|
|
311
|
+
- linking `createEnv()` and `documentEnv()` calls (`build/link.ts`)
|
|
312
|
+
- detecting compatibility concerns (`build/compatibility.ts`,
|
|
313
|
+
`build/exclusive-group.ts`)
|
|
314
|
+
- scanning source files for variable access and deriving ownership findings
|
|
315
|
+
(`build/scan-dependencies.ts`, `build/dependency-graph.ts`) -- a
|
|
316
|
+
purely-syntactic, per-file walk that follows `contract.KEY` member access,
|
|
317
|
+
object-destructuring, and one level of file-unique `const` aliasing, and
|
|
318
|
+
records every shape it can't follow (a rest/nested/computed-key binding, a
|
|
319
|
+
reassigned alias, the contract passed around as a value) as an explicit
|
|
320
|
+
`escape` that widens a variable to `indeterminate`, never a false
|
|
321
|
+
`unconsumed` (see ADR 0039)
|
|
322
|
+
- resolving live expiration overrides for documentation (`build/live-expirations.ts`)
|
|
323
|
+
- generating output artifacts (`build/manifest.ts`, `build/docs.ts`,
|
|
324
|
+
`build/env-example.ts`, `build/usage-report.ts`)
|
|
325
|
+
|
|
326
|
+
`generateEnvManifest()` (`build/generate-manifest.ts`),
|
|
327
|
+
`generateDocumentation()` (`build/generate-documentation.ts`), and
|
|
328
|
+
`generateUsageReport()` (`build/generate-usage.ts`) each coordinate one of
|
|
329
|
+
these passes and are responsible for writing their own generated files.
|
|
330
|
+
`generateEnvArtifacts()` (`build/generate-env-artifacts.ts`) composes all
|
|
331
|
+
three into a single call sharing one discovery pass and one combined
|
|
332
|
+
blocking-failure check.
|
|
333
|
+
|
|
334
|
+
The build package never imports or executes application schema files. It
|
|
335
|
+
analyzes source structure instead of running user code. This preserves the
|
|
336
|
+
safety boundary required for CI environments and large monorepos.
|
|
337
|
+
|
|
338
|
+
See
|
|
339
|
+
[`decisions/0002-static-analysis-never-execution.md`](decisions/0002-static-analysis-never-execution.md)
|
|
340
|
+
for the reasoning behind AST analysis instead of dynamic imports.
|
|
341
|
+
|
|
342
|
+
Every public options object in `build/index.ts` also carries a required
|
|
343
|
+
`fs: BuildFileSystem` field -- `./build` itself never imports `node:fs`; see
|
|
344
|
+
[ADR 0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md) and the
|
|
345
|
+
[Core invariants](#core-invariants) above.
|
|
346
|
+
|
|
347
|
+
## `helpers/` — optional processors and validators
|
|
348
|
+
|
|
349
|
+
The helpers package provides reusable implementations of the
|
|
350
|
+
`Processor` and `Validator` function types defined by
|
|
351
|
+
`runtime/types.ts`.
|
|
352
|
+
|
|
353
|
+
Examples include common transformations and validation patterns that most
|
|
354
|
+
applications would otherwise need to implement manually.
|
|
355
|
+
|
|
356
|
+
The runtime package has no dependency on helpers. They are convenience
|
|
357
|
+
utilities, not part of the environment-contract execution model.
|
|
358
|
+
|
|
359
|
+
`processors` and `validators` are separate exports so applications can
|
|
360
|
+
include only the category they use.
|
|
361
|
+
|
|
362
|
+
## Documentation is parallel to runtime, not part of runtime state
|
|
363
|
+
|
|
364
|
+
The most important architectural separation is the distinction between
|
|
365
|
+
runtime configuration and human-facing documentation.
|
|
366
|
+
|
|
367
|
+
`createEnv()` defines the information required to process and validate
|
|
368
|
+
environment values.
|
|
369
|
+
|
|
370
|
+
`documentEnv()` defines information intended for developers, operators, and
|
|
371
|
+
generated artifacts, such as:
|
|
372
|
+
|
|
373
|
+
- descriptions
|
|
374
|
+
- ownership information
|
|
375
|
+
- lifecycle details
|
|
376
|
+
- expiration dates
|
|
377
|
+
- operational guidance
|
|
378
|
+
|
|
379
|
+
`documentEnv()` is intentionally inert at runtime. It exists as a source-level
|
|
380
|
+
marker that the build system can discover through AST analysis. It does not
|
|
381
|
+
store documentation data in memory or add documentation fields to runtime
|
|
382
|
+
contracts.
|
|
383
|
+
|
|
384
|
+
The relationship is therefore not a runtime pipeline:
|
|
385
|
+
|
|
386
|
+
```mermaid
|
|
387
|
+
flowchart TB
|
|
388
|
+
SCHEMA["env.schema.ts"]
|
|
389
|
+
|
|
390
|
+
SCHEMA --> CREATECALL["createEnv(schema)"]
|
|
391
|
+
CREATECALL --> CONTRACT["runtime contract"]
|
|
392
|
+
CONTRACT --> VALIDATECALL["validateEnv()"]
|
|
393
|
+
VALIDATECALL --> VALUES["validated in-memory values"]
|
|
394
|
+
|
|
395
|
+
SCHEMA --> DOCCALL["documentEnv(schema, docs)"]
|
|
396
|
+
DOCCALL --> BUILDANALYSIS["build-time AST analysis only"]
|
|
397
|
+
BUILDANALYSIS --> ARTIFACTS["manifest / documentation / example artifacts"]
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
The same schema file can contain both calls, but they serve different
|
|
401
|
+
consumers:
|
|
402
|
+
|
|
403
|
+
- application runtime consumes `createEnv()`
|
|
404
|
+
- build tooling consumes `documentEnv()`
|
|
405
|
+
|
|
406
|
+
## Data flow
|
|
407
|
+
|
|
408
|
+
```mermaid
|
|
409
|
+
flowchart TB
|
|
410
|
+
subgraph AUTHOR["1 - Author time (capability owner)"]
|
|
411
|
+
SCHEMA["features/payments/env.schema.ts<br/>createEnv(schema) + documentEnv(schema, docs)"]
|
|
412
|
+
end
|
|
413
|
+
|
|
414
|
+
subgraph BUILDTIME["2 - Build time - shared compute pipeline<br/>(explicit CLI / npm script / CI step, never automatic at startup)"]
|
|
415
|
+
DISCOVER["discoverSchemaFiles()<br/>glob scan, + optional --package allowlist,<br/>+ optional tsconfig path-alias resolution"]
|
|
416
|
+
PARSE["parseSchemaFile()<br/>TypeScript AST - static analysis,<br/>schema file is never imported/executed"]
|
|
417
|
+
LINK["linkFiles()<br/>pairs createEnv()/documentEnv() calls<br/>into DiscoveredContract objects"]
|
|
418
|
+
CHECKS{"detectCompatibilityIssues()<br/>detectExclusiveGroupIssues()<br/>blocking finding?"}
|
|
419
|
+
THROW["EnvProjectGenerationError<br/>nothing written, either mode"]
|
|
420
|
+
|
|
421
|
+
DISCOVER --> PARSE --> LINK --> CHECKS
|
|
422
|
+
CHECKS -- yes --> THROW
|
|
423
|
+
end
|
|
424
|
+
|
|
425
|
+
SCHEMA -.->|explicit run| DISCOVER
|
|
426
|
+
|
|
427
|
+
subgraph WRITE["2a - generateEnvArtifacts() (default: write)"]
|
|
428
|
+
MANIFEST["env.manifest.ts<br/>renderManifest()"]
|
|
429
|
+
DOCS["ENVIRONMENT.md<br/>renderDocs(), never blocks<br/>(findings, not throws - ADR 0038)"]
|
|
430
|
+
EXAMPLE[".env.example<br/>renderEnvExample(), reconciled<br/>against the existing file"]
|
|
431
|
+
OWNERSHIP["OWNERSHIP.md<br/>broader source scan -><br/>dependency graph -> ownership findings,<br/>never blocks (ADR 0038)"]
|
|
432
|
+
EVIDENCE["docs/env.evidence.json<br/>+ .fingerprint sidecar<br/>full EvidenceModel, always computed,<br/>independent of manifest.location - ADR 0038"]
|
|
433
|
+
end
|
|
434
|
+
|
|
435
|
+
subgraph CHECKPATH["2b - checkEnvArtifacts() (--check: compare, never write)"]
|
|
436
|
+
COMPARE["recompute every requested artifact,<br/>diff against what's already on disk<br/>(generatedAt/change normalized out<br/>for the evidence artifact - ADR 0038)"]
|
|
437
|
+
end
|
|
438
|
+
|
|
439
|
+
CHECKS -- "no, writing" --> MANIFEST & DOCS & EXAMPLE & OWNERSHIP & EVIDENCE
|
|
440
|
+
CHECKS -- "no, check mode" --> COMPARE
|
|
441
|
+
|
|
442
|
+
subgraph CI["3 - CI enforcement"]
|
|
443
|
+
GHACTION["GitHub Action (action.yml)<br/>env-cap --json -> PR annotations +<br/>sticky summary comment"]
|
|
444
|
+
ROTATION["rotation-alert GitHub issue<br/>on scheduled/non-PR runs -<br/>opens/auto-closes on expiringSoon"]
|
|
445
|
+
GHACTION --> ROTATION
|
|
446
|
+
end
|
|
447
|
+
|
|
448
|
+
COMPARE -->|exit 1 on drift| GHACTION
|
|
449
|
+
|
|
450
|
+
subgraph STARTUP["4 - Process startup"]
|
|
451
|
+
IMPORT["application imports<br/>the generated manifest"]
|
|
452
|
+
VALIDATECALL["validateEnv({ manifest,<br/>values: process.env, activeContexts })"]
|
|
453
|
+
PERVAR["per variable: context match?<br/>-> default -> processor -> validator<br/>-> freeze into cache"]
|
|
454
|
+
ERR["EnvValidationError<br/>aggregated failures"]
|
|
455
|
+
CACHED["cached validated result<br/>(one-shot per process)"]
|
|
456
|
+
|
|
457
|
+
IMPORT --> VALIDATECALL --> PERVAR
|
|
458
|
+
PERVAR -- "any invalid" --> ERR
|
|
459
|
+
PERVAR -- "all valid" --> CACHED
|
|
460
|
+
end
|
|
461
|
+
|
|
462
|
+
MANIFEST --> IMPORT
|
|
463
|
+
|
|
464
|
+
subgraph RUNTIME_ACCESS["5 - Runtime access"]
|
|
465
|
+
ACCESS["feature code imports the<br/>contract it owns:<br/>paymentsEnv.STRIPE_KEY"]
|
|
466
|
+
NOTREADY["EnvNotReadyError<br/>if read before validateEnv() resolves"]
|
|
467
|
+
end
|
|
468
|
+
|
|
469
|
+
CACHED --> ACCESS
|
|
470
|
+
ACCESS -. "read before ready" .-> NOTREADY
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
`generateEnvArtifacts()` and `checkEnvArtifacts()` share one
|
|
474
|
+
`computeArtifacts()` pass (discovery, parsing, linking, and blocking-finding
|
|
475
|
+
checks) and only diverge at the last step: write, or compare-and-report (see
|
|
476
|
+
[ADR 0011](decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md)
|
|
477
|
+
and [ADR 0016](decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
|
|
478
|
+
Manifest, docs, `.env.example`, the ownership report, and the persisted
|
|
479
|
+
evidence artifact are each optional per `generateEnvArtifacts()`/
|
|
480
|
+
`checkEnvArtifacts()` call (`manifest`/`docs`/`usage`/`evidence` options) and
|
|
481
|
+
only appear above when requested. The `env-cap` CLI only exposes
|
|
482
|
+
`--location`/`--evidence` of those four -- docs/`.env.example`/the ownership
|
|
483
|
+
report have no CLI flag at all (ADR 0046: no verified runtime consumer, so
|
|
484
|
+
generating them is application code calling `generateDocumentation()`/
|
|
485
|
+
`generateUsageReport()` directly, not a CLI concern) -- except the
|
|
486
|
+
`EvidenceModel` backing the persisted evidence artifact, which
|
|
487
|
+
`computeArtifacts()` always builds regardless of whether `evidence`/
|
|
488
|
+
`--evidence` was requested; that option only controls whether it's also
|
|
489
|
+
written to disk (ADR 0038).
|
|
490
|
+
Manifest compatibility/exclusive-group issues are the one category that still
|
|
491
|
+
blocks (`CHECKS`, ADR 0009) — a documentation or ownership issue never does;
|
|
492
|
+
both are surfaced as `Finding`s on the evidence artifact instead, for a team
|
|
493
|
+
to gate on in its own CI step if it wants that enforced. The GitHub Action wraps whichever mode a workflow invokes
|
|
494
|
+
`env-cap --json` with.
|
|
495
|
+
|
|
496
|
+
### 1. Author time
|
|
497
|
+
|
|
498
|
+
A feature owner creates an environment schema:
|
|
499
|
+
|
|
500
|
+
```text
|
|
501
|
+
|
|
502
|
+
features/payments/env.schema.ts
|
|
503
|
+
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
The file defines:
|
|
507
|
+
|
|
508
|
+
- the feature's environment variables
|
|
509
|
+
- processing rules
|
|
510
|
+
- validation rules
|
|
511
|
+
- optional documentation metadata
|
|
512
|
+
|
|
513
|
+
Importing the file creates the contract object but does not resolve
|
|
514
|
+
environment values.
|
|
515
|
+
|
|
516
|
+
### 2. Build time
|
|
517
|
+
|
|
518
|
+
`generateEnvManifest()` runs as an explicit development or CI step.
|
|
519
|
+
|
|
520
|
+
It:
|
|
521
|
+
|
|
522
|
+
1. discovers schema files
|
|
523
|
+
2. parses their ASTs
|
|
524
|
+
3. links `createEnv()` and `documentEnv()` calls
|
|
525
|
+
4. checks for detectable issues
|
|
526
|
+
5. generates requested artifacts
|
|
527
|
+
|
|
528
|
+
Possible outputs include:
|
|
529
|
+
|
|
530
|
+
- environment manifests
|
|
531
|
+
- documentation artifacts
|
|
532
|
+
- `.env.example` files
|
|
533
|
+
|
|
534
|
+
This process never runs automatically during application startup.
|
|
535
|
+
|
|
536
|
+
### 3. Process startup
|
|
537
|
+
|
|
538
|
+
The application imports the generated manifest and calls:
|
|
539
|
+
|
|
540
|
+
```ts
|
|
541
|
+
validateEnv({ manifest, values: process.env })
|
|
542
|
+
```
|
|
543
|
+
|
|
544
|
+
Validation happens once for the process lifetime.
|
|
545
|
+
|
|
546
|
+
Each contract, per variable:
|
|
547
|
+
|
|
548
|
+
1. checks whether the variable's `context` matches this run's
|
|
549
|
+
`activeContexts` -- if not, skips every remaining step entirely and
|
|
550
|
+
moves to the next variable (see "Validation context invariants" above)
|
|
551
|
+
2. reads its raw value
|
|
552
|
+
3. applies its default
|
|
553
|
+
4. runs its processor
|
|
554
|
+
5. runs its validator
|
|
555
|
+
6. stores the frozen validated result
|
|
556
|
+
|
|
557
|
+
```mermaid
|
|
558
|
+
flowchart LR
|
|
559
|
+
START(["for each variable<br/>in the contract"]) --> CTX{"has a context,<br/>and it's not in<br/>activeContexts?"}
|
|
560
|
+
CTX -- "yes - skip" --> SKIP["stays not-ready,<br/>as if this run<br/>never happened"]
|
|
561
|
+
CTX -- "no - participates" --> RAW["read raw value"]
|
|
562
|
+
RAW --> DEFAULT["apply default"]
|
|
563
|
+
DEFAULT --> PROC["run processor"]
|
|
564
|
+
PROC --> VALID["run validator"]
|
|
565
|
+
VALID --> FREEZE["store frozen<br/>validated result"]
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
Failures are aggregated into `EnvValidationError` rather than stopping at
|
|
569
|
+
the first invalid variable.
|
|
570
|
+
|
|
571
|
+
### 4. Runtime access
|
|
572
|
+
|
|
573
|
+
Feature code imports the contract it owns:
|
|
574
|
+
|
|
575
|
+
```ts
|
|
576
|
+
paymentsEnv.STRIPE_KEY
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
There is no global environment object.
|
|
580
|
+
|
|
581
|
+
Accessing a value before validation completes throws `EnvNotReadyError`.
|
|
582
|
+
Successful access returns the validated value for that specific feature
|
|
583
|
+
contract.
|
|
584
|
+
|
|
585
|
+
## Module layout
|
|
586
|
+
|
|
587
|
+
The `src/` tree mirrors the entry points described above:
|
|
588
|
+
`runtime/`, `build/` (and `build/resolution/`), `helpers/`, `evidence/`,
|
|
589
|
+
`eslint-plugin/`, plus `cli/` (the `env-cap` bin) and `node/` (the
|
|
590
|
+
`@maverickcer/env-cap/node` executable-context entry that ships the CLI's
|
|
591
|
+
concrete `BuildFileSystem` adapter as a value for a consumer's own build
|
|
592
|
+
script). See [The entry points](#the-entry-points) for the
|
|
593
|
+
dependency rules between them.
|
|
594
|
+
|
|
595
|
+
## Architectural decisions
|
|
596
|
+
|
|
597
|
+
| Boundary | ADR |
|
|
598
|
+
| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
|
599
|
+
| One `createEnv` vs `createEnv` + `defineEnv` | [0001](decisions/0001-runtime-documentation-separation.md) |
|
|
600
|
+
| Parsing instead of importing schema files | [0002](decisions/0002-static-analysis-never-execution.md) |
|
|
601
|
+
| Per-feature contracts instead of global `env` | [0003](decisions/0003-no-global-env-object.md) |
|
|
602
|
+
| No `/client` or `/server` package split | [0004](decisions/0004-no-client-server-package-split.md) |
|
|
603
|
+
| Warn by default instead of throwing | [0005](decisions/0005-warn-not-throw-by-default.md) |
|
|
604
|
+
| Self-redacting contracts | [0006](decisions/0006-self-redacting-contracts.md) |
|
|
605
|
+
| `processor` terminology instead of `transformer` | [0007](decisions/0007-processor-not-transformer.md) |
|
|
606
|
+
| Fixed gzip size budget on runtime/helpers | [0008](decisions/0008-gzip-size-budget.md) |
|
|
607
|
+
| Exclusive-group violations always error | [0009](decisions/0009-exclusive-groups-are-always-errors.md) |
|
|
608
|
+
| Dependency-ownership engine's fixed scope, internals not public | [0010](decisions/0010-dependency-ownership-engine-scope-boundary.md) |
|
|
609
|
+
| Shared discovery, compute-atomic but not write-atomic `generateEnvArtifacts()` | [0011](decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md) |
|
|
610
|
+
| Live expiration overrides via callback, not AST | [0012](decisions/0012-live-expiration-overrides-not-ast-functions.md) |
|
|
611
|
+
| `--json` CLI output is a versioned mirror | [0013](decisions/0013-json-output-is-a-versioned-mirror.md) |
|
|
612
|
+
| Cross-package schema discovery via explicit allowlist (Experimental) | [0014](decisions/0014-cross-package-schema-discovery.md) |
|
|
613
|
+
| Post-1.0 security-fix backport window (one major back, ≥6 months, never shortened once stated) | [0015](decisions/0015-security-backport-window.md) |
|
|
614
|
+
| `--check` computes fully before comparing, and never partially writes | [0016](decisions/0016-check-mode-compute-before-compare-never-partial-write.md) |
|
|
615
|
+
| A 4th public entry point (`./eslint-plugin`) for a capability-owned-access lint rule | [0017](decisions/0017-eslint-plugin-entry-point.md) |
|
|
616
|
+
| Rotation-alert GitHub issue on non-PR Action runs (opens/auto-closes based on expiringSoon) | [0018](decisions/0018-rotation-alert-issue-on-non-pr-runs.md) |
|
|
617
|
+
| The published `--json` schema is generated from types, never hand-authored | [0019](decisions/0019-published-json-schema-generated-from-types.md) |
|
|
618
|
+
| Declaration maps emitted by a separate `tsc` pass, not tsup's own `dts` pipeline | [0020](decisions/0020-declaration-maps-via-separate-tsc-pass.md) |
|
|
619
|
+
| The manifest change report is a persisted, committed JSON sidecar snapshot | [0021](decisions/0021-manifest-change-report-persisted-snapshot.md) |
|
|
620
|
+
| Generic, declarative validation contexts (`context`/`activeContexts`) | [0022](decisions/0022-validation-contexts.md) |
|
|
621
|
+
| TypeScript path-alias resolution, on by default (Experimental) | [0023](decisions/0023-tsconfig-path-alias-resolution.md) |
|
|
622
|
+
| Seven canonical fact models (Contract/Dependency/Ownership/Lifecycle/Finding/Change/Evidence), not thirty-five reports | [0024](decisions/0024-fact-model-architecture.md) |
|
|
623
|
+
| Contract Model is a new, versioned JSON projection, published alongside the manifest | [0025](decisions/0025-contract-model-json-projection.md) |
|
|
624
|
+
| Finding Model unifies four independently-shaped finding families | [0026](decisions/0026-finding-model-unifies-four-families.md) |
|
|
625
|
+
| Dependency Model publishes a fact-shaped result, not the scanning engine | [0027](decisions/0027-dependency-model-fact-shape-not-engine-access.md) |
|
|
626
|
+
| Ownership Model shares one effectiveOwner() rule, fixing a pre-existing divergence | [0028](decisions/0028-ownership-model-shared-effective-owner.md) |
|
|
627
|
+
| Lifecycle Model adds deprecation/rename fields, promotes ExpiringEntry | [0029](decisions/0029-lifecycle-model-deprecation-rename-fields.md) |
|
|
628
|
+
| Change Model wraps the existing manifest change report | [0030](decisions/0030-change-model-wraps-manifest-change-report.md) |
|
|
629
|
+
| A 5th public entry point (`./evidence`) for Evidence Model projections | [0031](decisions/0031-evidence-entry-point.md) |
|
|
630
|
+
| Evidence projection provenance via a non-frozen Proxy tracking membrane, not `Object.freeze()` | [0032](decisions/0032-evidence-projection-provenance-mechanism.md) |
|
|
631
|
+
| The ten first-party reference projections live in examples/, not src/ | [0033](decisions/0033-reference-projections-live-in-examples.md) |
|
|
632
|
+
| `computeArtifacts()` always builds a real `EvidenceModel`; `ManifestSnapshot` retires; docs/ownership never throw | [0038](decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md) |
|
|
633
|
+
| Usage scanner follows object-destructuring + one-level `const` aliasing; every other shape is an explicit `escape` | [0039](decisions/0039-scanner-local-dataflow-boundary.md) |
|
|
634
|
+
| Library surfaces (`./build`) never import `node:fs`; a caller supplies a `BuildFileSystem` | [0040](decisions/0040-library-surfaces-do-not-acquire-node-fs.md) |
|