@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,116 @@
|
|
|
1
|
+
# 0004: No `env-cap/client` or `/server` package
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Reflected in `package.json`'s `exports` map (only `.`, `./build`,
|
|
6
|
+
and `./helpers`) and documented in the README's ["Runtime and build-time are
|
|
7
|
+
intentionally separate"](../../GUIDE.md#runtime-and-build-time-are-intentionally-separate)
|
|
8
|
+
section.
|
|
9
|
+
|
|
10
|
+
## Context
|
|
11
|
+
|
|
12
|
+
Many environment-management libraries provide separate `/client` and
|
|
13
|
+
`/server` entry points to reduce the risk of exposing server-only
|
|
14
|
+
configuration to browser bundles. These packages typically enforce the
|
|
15
|
+
distinction by creating separate APIs or schema types that prevent server
|
|
16
|
+
variables from being referenced in client code.
|
|
17
|
+
|
|
18
|
+
`env-cap` needs to support the same goal: allowing applications to
|
|
19
|
+
maintain clear boundaries between server-only configuration and
|
|
20
|
+
client-safe configuration without introducing unnecessary runtime
|
|
21
|
+
complexity.
|
|
22
|
+
|
|
23
|
+
## Decision
|
|
24
|
+
|
|
25
|
+
`env-cap` does not provide separate `/client` or `/server` subpath
|
|
26
|
+
exports.
|
|
27
|
+
|
|
28
|
+
The runtime API (`createEnv` and `validateEnv`) is intentionally identical
|
|
29
|
+
for all environments. A variable's classification as server-only or
|
|
30
|
+
client-safe does not change how it is processed, validated, or accessed at
|
|
31
|
+
runtime. There is no different runtime behavior that would justify separate
|
|
32
|
+
packages.
|
|
33
|
+
|
|
34
|
+
The separation happens at build time through generated contract. Projects
|
|
35
|
+
should generate separate contract for separate execution environments using
|
|
36
|
+
disjoint discovery rules:
|
|
37
|
+
|
|
38
|
+
```js
|
|
39
|
+
await generateEnvManifest({
|
|
40
|
+
location: "src/generated/server.contract.ts",
|
|
41
|
+
include: ["server/**/env.schema.ts"],
|
|
42
|
+
})
|
|
43
|
+
|
|
44
|
+
await generateEnvManifest({
|
|
45
|
+
location: "src/generated/client.contract.ts",
|
|
46
|
+
include: ["web/**/env.schema.ts"],
|
|
47
|
+
})
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The application architecture is responsible for ensuring that
|
|
51
|
+
server-generated contract are only imported by server-side code and
|
|
52
|
+
client-generated contract are only imported by browser-bound code. This
|
|
53
|
+
follows the same dependency-boundary rules used throughout an application:
|
|
54
|
+
server-only modules should not be imported into client code.
|
|
55
|
+
|
|
56
|
+
## Consequences
|
|
57
|
+
|
|
58
|
+
- **The package does not pretend to provide enforcement it cannot guarantee.**
|
|
59
|
+
Separate `/client` and `/server` packages would not fully prevent
|
|
60
|
+
accidental exposure. A developer could still misconfigure discovery
|
|
61
|
+
patterns or import a server contract directly into client code. The actual
|
|
62
|
+
security boundary remains the application's module graph and build
|
|
63
|
+
configuration.
|
|
64
|
+
|
|
65
|
+
- **The public API remains smaller and more accurate.**
|
|
66
|
+
Separate entry points would suggest different runtime capabilities or
|
|
67
|
+
behaviors that do not exist. Maintaining two nearly identical APIs would
|
|
68
|
+
add maintenance cost while providing little additional protection.
|
|
69
|
+
|
|
70
|
+
- **Environment separation remains explicit and project-owned.**
|
|
71
|
+
Different applications have different definitions of what is client-safe,
|
|
72
|
+
server-only, internal, or public. `env-cap` does not impose a
|
|
73
|
+
universal classification system. Teams define those boundaries through
|
|
74
|
+
their schema organization, generated contract, and documentation.
|
|
75
|
+
|
|
76
|
+
- **Build-time metadata remains separate from runtime behavior.**
|
|
77
|
+
Whether a variable is categorized as server-only or client-safe is a
|
|
78
|
+
build and deployment concern, not something the runtime needs to process.
|
|
79
|
+
This keeps the runtime contract minimal and avoids carrying metadata that
|
|
80
|
+
has no effect during validation.
|
|
81
|
+
|
|
82
|
+
## Alternatives considered
|
|
83
|
+
|
|
84
|
+
- **Parallel `/client` and `/server` packages with identical APIs.**
|
|
85
|
+
Rejected. This would imply a runtime distinction that does not exist,
|
|
86
|
+
double the public API surface, and require every future runtime change to
|
|
87
|
+
be maintained across multiple entry points. It would also not prevent
|
|
88
|
+
incorrect imports or incorrectly generated contract.
|
|
89
|
+
|
|
90
|
+
- **A `runtime: "server" | "client"` option on `createEnv`.**
|
|
91
|
+
Rejected. This would add classification data to the runtime schema even
|
|
92
|
+
though the runtime does not use it. It would blur the boundary between
|
|
93
|
+
runtime configuration processing and build-time concerns. Environment
|
|
94
|
+
classification belongs with build tooling and documentation, not the
|
|
95
|
+
runtime contract itself.
|
|
96
|
+
|
|
97
|
+
- **Automatic detection of client/server usage at runtime.**
|
|
98
|
+
Rejected. Runtime detection would be framework-dependent, unreliable
|
|
99
|
+
across different deployment targets, and would introduce complexity into
|
|
100
|
+
the smallest and most security-sensitive part of the package. The package
|
|
101
|
+
should remain environment-agnostic and allow the application's build
|
|
102
|
+
system to define the correct boundary.
|
|
103
|
+
|
|
104
|
+
## Update (see ADR 0022)
|
|
105
|
+
|
|
106
|
+
[ADR 0022](0022-validation-contexts.md) later added a generic
|
|
107
|
+
`context`/`activeContexts` mechanism to `createEnv()`/`validateEnv()`.
|
|
108
|
+
This is _not_ the `runtime: "server" | "client"` option rejected above:
|
|
109
|
+
that alternative was a closed, client/server-specific enum that implied a
|
|
110
|
+
bundling boundary the runtime can't actually enforce. `context` is an
|
|
111
|
+
open, application-defined string (never interpreted by env-cap, never
|
|
112
|
+
limited to client/server) that only gates whether `validateEnv()`
|
|
113
|
+
processes a variable in a given run -- it makes no claim about, and is not
|
|
114
|
+
a substitute for, the module-boundary decision made above. Separate
|
|
115
|
+
discovery/manifests remain the only real mechanism for keeping
|
|
116
|
+
server-only source out of client-bound code.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# 0005: Manifest generation warns by default; throwing is opt-in
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented in `src/build/generate-manifest.ts`
|
|
6
|
+
(`onIncompatibility`) and `src/build/generate-documentation.ts`
|
|
7
|
+
(`onUndocumented`), both defaulting to `"warn"`.
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
`generateEnvManifest()` performs static analysis rather than executing
|
|
12
|
+
application code (see 0002). Because of this, some findings can be detected
|
|
13
|
+
with certainty while others represent potential issues that require human
|
|
14
|
+
judgment.
|
|
15
|
+
|
|
16
|
+
Two categories intentionally fall into the second group:
|
|
17
|
+
|
|
18
|
+
- **Duplicate variable incompatibility.**
|
|
19
|
+
The build tool cannot execute processors or validators to determine their
|
|
20
|
+
runtime behavior. It can only prove that two contracts are incompatible
|
|
21
|
+
when both provide explicit, conflicting return-type annotations for the
|
|
22
|
+
same variable name. Different implementations without annotations, or
|
|
23
|
+
implementations that happen to produce different values at runtime, cannot
|
|
24
|
+
be proven incompatible through static analysis alone.
|
|
25
|
+
|
|
26
|
+
- **Undocumented contracts or variables.**
|
|
27
|
+
A `createEnv()` call without a matching `documentEnv()` call, or a variable
|
|
28
|
+
that exists in the schema but not in documentation, indicates incomplete
|
|
29
|
+
documentation coverage. However, documentation is intentionally optional
|
|
30
|
+
(see 0001), so the absence of documentation is not inherently a runtime
|
|
31
|
+
correctness failure.
|
|
32
|
+
|
|
33
|
+
## Decision
|
|
34
|
+
|
|
35
|
+
`onIncompatibility` and `onUndocumented` both default to `"warn"`.
|
|
36
|
+
|
|
37
|
+
When a warning-level finding is detected, it is included in the generation
|
|
38
|
+
result, surfaced through the CLI, and included in generated reporting output,
|
|
39
|
+
but contract generation continues and the output file is written.
|
|
40
|
+
|
|
41
|
+
Only findings that can be proven to be invalid are treated as generation
|
|
42
|
+
failures by default. For example, two contracts declaring the same variable
|
|
43
|
+
with explicitly incompatible return-type annotations are a confirmed
|
|
44
|
+
conflict and block generation.
|
|
45
|
+
|
|
46
|
+
Teams that want stricter enforcement can set either option to `"throw"`.
|
|
47
|
+
This converts that category of finding into an `EnvManifestGenerationError`,
|
|
48
|
+
allowing projects to enforce stricter CI requirements as their adoption
|
|
49
|
+
matures.
|
|
50
|
+
|
|
51
|
+
## Consequences
|
|
52
|
+
|
|
53
|
+
- **Projects can adopt `env-cap` incrementally.**
|
|
54
|
+
A team does not need complete documentation coverage or immediate
|
|
55
|
+
resolution of every potential duplicate-variable concern before generating
|
|
56
|
+
its first contract. Documentation and stricter validation policies can be
|
|
57
|
+
introduced over time through CLI flags such as `--strict` and
|
|
58
|
+
`--strict-docs`, or through equivalent options passed directly to
|
|
59
|
+
`generateEnvManifest()`.
|
|
60
|
+
|
|
61
|
+
- **Warnings require an intentional review process.**
|
|
62
|
+
Because warnings do not fail generation by default, a project that only
|
|
63
|
+
checks command exit codes could allow important findings to remain
|
|
64
|
+
unresolved. The CLI surfaces warnings directly, and generated
|
|
65
|
+
documentation artifacts provide additional visibility, but teams should
|
|
66
|
+
decide how warnings are reviewed within their development workflow.
|
|
67
|
+
|
|
68
|
+
- **Strict enforcement does not require different analysis logic.**
|
|
69
|
+
Teams can move from permissive adoption to strict CI enforcement without
|
|
70
|
+
changing schemas or rewriting configuration. The same static analysis runs
|
|
71
|
+
in both modes; the only difference is whether a detected condition is
|
|
72
|
+
informational or fatal.
|
|
73
|
+
|
|
74
|
+
- **The package avoids pretending static analysis knows more than it does.**
|
|
75
|
+
A warning represents uncertainty that requires human evaluation. Throwing
|
|
76
|
+
for cases that cannot be proven would encourage developers to work around
|
|
77
|
+
the tool rather than trust its results.
|
|
78
|
+
|
|
79
|
+
## Alternatives considered
|
|
80
|
+
|
|
81
|
+
- **Throw by default.**
|
|
82
|
+
Rejected. This would require every project to achieve complete
|
|
83
|
+
documentation coverage and resolve every potential duplicate-variable
|
|
84
|
+
concern before the first successful contract generation. That conflicts
|
|
85
|
+
with the design goal that documentation is optional and can be adopted
|
|
86
|
+
incrementally.
|
|
87
|
+
|
|
88
|
+
- **Only report provable incompatibilities and ignore uncertain cases.**
|
|
89
|
+
Rejected. Remaining silent about possible issues removes valuable context
|
|
90
|
+
from developers and prevents teams from improving their configuration
|
|
91
|
+
quality over time. The package follows a consistent policy: detect what can
|
|
92
|
+
be proven, warn about what requires review, and avoid making assumptions
|
|
93
|
+
about runtime behavior.
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# 0006: Contracts redact themselves; only explicit per-key access reveals a value
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented in `src/runtime/create.ts`.
|
|
6
|
+
|
|
7
|
+
## Context
|
|
8
|
+
|
|
9
|
+
A common way secrets reach logs or monitoring systems is through accidental
|
|
10
|
+
object serialization rather than intentional exposure. Examples include
|
|
11
|
+
debugging statements such as `console.log(config)` or serializing request
|
|
12
|
+
context objects that happen to contain resolved environment values.
|
|
13
|
+
|
|
14
|
+
A traditional environment library often returns a plain object containing
|
|
15
|
+
resolved values:
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
{
|
|
19
|
+
STRIPE_KEY: "sk_live_...",
|
|
20
|
+
DATABASE_URL: "postgres://..."
|
|
21
|
+
}
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
This creates an unsafe default because the easiest way to inspect the object
|
|
25
|
+
is also the easiest way to expose every secret it contains. Reading one
|
|
26
|
+
specific variable and dumping the entire configuration object require the
|
|
27
|
+
same action.
|
|
28
|
+
|
|
29
|
+
## Decision
|
|
30
|
+
|
|
31
|
+
The object returned by `createEnv()` is intentionally not a plain value
|
|
32
|
+
object. It is a protected contract object that exposes values only through
|
|
33
|
+
explicit property access.
|
|
34
|
+
|
|
35
|
+
The returned object overrides:
|
|
36
|
+
|
|
37
|
+
- `Symbol.for("nodejs.util.inspect.custom")`
|
|
38
|
+
- `toString()`
|
|
39
|
+
- `toJSON()`
|
|
40
|
+
|
|
41
|
+
Each returns a redacted representation containing only contract metadata:
|
|
42
|
+
|
|
43
|
+
```text
|
|
44
|
+
EnvContract("payments") { 3 variable(s) }
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The underlying environment values are never included.
|
|
48
|
+
|
|
49
|
+
As a result:
|
|
50
|
+
|
|
51
|
+
- `console.log(paymentsEnv)` is safe.
|
|
52
|
+
- `util.inspect(paymentsEnv)` is safe.
|
|
53
|
+
- `` `${paymentsEnv}` `` is safe.
|
|
54
|
+
- `JSON.stringify(paymentsEnv)` is safe.
|
|
55
|
+
|
|
56
|
+
Explicit access to a known variable remains unchanged:
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
paymentsEnv.STRIPE_KEY
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
returns the validated, processed value required by application code.
|
|
63
|
+
|
|
64
|
+
The contract object is also frozen with `Object.freeze()` to prevent runtime
|
|
65
|
+
mutation of the redaction methods or replacement of the protected behavior.
|
|
66
|
+
|
|
67
|
+
## Consequences
|
|
68
|
+
|
|
69
|
+
- **The safe path becomes easier than the unsafe path.**
|
|
70
|
+
Accidentally dumping an entire environment contract no longer exposes every
|
|
71
|
+
variable. Retrieving a secret requires an intentional property access to a
|
|
72
|
+
specific key rather than a generic object serialization.
|
|
73
|
+
|
|
74
|
+
- **Protection ends once a value is extracted.**
|
|
75
|
+
This design protects the contract object itself, not arbitrary values after
|
|
76
|
+
application code retrieves them.
|
|
77
|
+
|
|
78
|
+
For example:
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
console.log({ key: paymentsEnv.STRIPE_KEY })
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
intentionally creates a new object containing the secret. The package
|
|
85
|
+
cannot prevent application code from re-exposing values after extraction.
|
|
86
|
+
|
|
87
|
+
- **Processors and validators remain responsible for their own error
|
|
88
|
+
handling.**
|
|
89
|
+
If custom processing code includes sensitive values in thrown errors, such
|
|
90
|
+
as:
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
throw new Error(`Invalid value: ${value}`)
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
that information may appear in validation failures. The contract
|
|
97
|
+
redaction boundary cannot protect values that custom code has already
|
|
98
|
+
placed into an error message.
|
|
99
|
+
|
|
100
|
+
- **The design intentionally avoids turning environment access into a secret
|
|
101
|
+
management system.**
|
|
102
|
+
There is no `.reveal()`, `.unwrap()`, access auditing, or permission layer.
|
|
103
|
+
The goal is narrowly defined: prevent the most common accidental exposure
|
|
104
|
+
pattern while preserving normal developer ergonomics.
|
|
105
|
+
|
|
106
|
+
- **Per-variable access remains intentionally simple.**
|
|
107
|
+
Developers should not need additional ceremony for the normal case of
|
|
108
|
+
reading a required configuration value. Security is improved at the object
|
|
109
|
+
boundary without making legitimate access cumbersome.
|
|
110
|
+
|
|
111
|
+
## Alternatives considered
|
|
112
|
+
|
|
113
|
+
- **A `Proxy`-based lazy contract with an explicit `.reveal()` or
|
|
114
|
+
`.unwrap()` method.**
|
|
115
|
+
Rejected. This adds API complexity and introduces a second access model
|
|
116
|
+
without meaningfully improving the primary protection target. The main
|
|
117
|
+
risk is accidental whole-object serialization, which the existing
|
|
118
|
+
inspection overrides already address.
|
|
119
|
+
|
|
120
|
+
- **Return a normal object and rely on documentation to prevent leaks.**
|
|
121
|
+
Rejected. A warning in documentation does not change the default behavior
|
|
122
|
+
of serialization. Since this package exists specifically around handling
|
|
123
|
+
sensitive configuration values, the safer default should be enforced by
|
|
124
|
+
the object design itself rather than developer discipline alone.
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# 0007: Rename `transformer`/`Transformer` to `processor`/`Processor`
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented in `src/runtime/types.ts`, `src/runtime/validate.ts`,
|
|
6
|
+
`src/runtime/errors.ts`, `src/build/parse.ts`, `src/build/compatibility.ts`,
|
|
7
|
+
`src/build/docs.ts`, and `src/helpers/processors.ts`, and reflected
|
|
8
|
+
throughout the documentation and examples.
|
|
9
|
+
|
|
10
|
+
## Context
|
|
11
|
+
|
|
12
|
+
The schema field responsible for turning a raw environment value into a
|
|
13
|
+
typed application value was originally named `transformer`, backed by a
|
|
14
|
+
`Transformer<T>` type (`(value: unknown) => T`). This mirrored the
|
|
15
|
+
terminology used by comparable environment-validation libraries, where the
|
|
16
|
+
job is described as reshaping a value from one type into another (e.g.
|
|
17
|
+
string to number).
|
|
18
|
+
|
|
19
|
+
In practice, this field is expected to do more than reshape a value's type.
|
|
20
|
+
It is the one place where a raw value should be turned into its final,
|
|
21
|
+
directly-usable form -- parsing a connection string into a `URL`, decoding a
|
|
22
|
+
token into its claims, resolving a reference into the actual secret,
|
|
23
|
+
splitting a delimited string into an array -- so that every consumer of the
|
|
24
|
+
resulting contract can use the value as-is, without re-deriving the same
|
|
25
|
+
result on every read. "Transform" describes a shape change; it does not
|
|
26
|
+
communicate that the output is meant to be the value's _final_ form,
|
|
27
|
+
computed once.
|
|
28
|
+
|
|
29
|
+
This mismatch was already visible inside the codebase itself:
|
|
30
|
+
`src/helpers/processors.ts` and its exported `processors` namespace
|
|
31
|
+
(`processors.url()`, `processors.number()`, ...) were named for the
|
|
32
|
+
finished-value contract from the start, and `helpers/index.ts`'s own
|
|
33
|
+
comments already described "processor/validator patterns." Only the
|
|
34
|
+
underlying schema field (`transformer:`) and its type (`Transformer<T>`)
|
|
35
|
+
had not caught up, so a developer writing `processor: processors.url()` --
|
|
36
|
+
correct under this decision -- previously had to write `transformer:
|
|
37
|
+
processors.url()`, bridging a naming gap between the helper they imported
|
|
38
|
+
and the field they assigned it to.
|
|
39
|
+
|
|
40
|
+
## Decision
|
|
41
|
+
|
|
42
|
+
Rename the runtime vocabulary end to end:
|
|
43
|
+
|
|
44
|
+
- `Transformer<T>` (`src/runtime/types.ts`) → `Processor<T>`
|
|
45
|
+
- `EnvDefinition.transformer` → `EnvDefinition.processor`
|
|
46
|
+
- `VariableFailure.kind: "transformer"` → `"processor"`, and its formatted
|
|
47
|
+
heading, `"Transformer failed:"` → `"Processor failed:"`
|
|
48
|
+
- Build-time static-analysis fields (`src/build/parse.ts`): `hasTransformer`
|
|
49
|
+
→ `hasProcessor`, `transformerSource` → `processorSource`,
|
|
50
|
+
`transformerReturnType` → `processorReturnType`
|
|
51
|
+
- The generated docs catalog line, `- Transformer: yes/no` → `- Processor:
|
|
52
|
+
yes/no`, and compatibility messages (`src/build/compatibility.ts`), e.g.
|
|
53
|
+
`"Processor return types are declared incompatible..."`
|
|
54
|
+
- All prose referencing the concept across `specs/architecture.md`, the
|
|
55
|
+
other ADRs, `README.md`, `SECURITY.md`, and the `examples/` schema files
|
|
56
|
+
|
|
57
|
+
The function signature is unchanged (`(value: unknown) => T`); this is a
|
|
58
|
+
vocabulary change, not a behavioral one. It exists to make the schema field
|
|
59
|
+
match the intent it was always meant to carry: produce a value that's ready
|
|
60
|
+
to use directly, computed once, rather than a value that merely has a
|
|
61
|
+
different shape than its input.
|
|
62
|
+
|
|
63
|
+
## Consequences
|
|
64
|
+
|
|
65
|
+
- **This is a breaking API change.** Every existing `env.schema.ts` using
|
|
66
|
+
`transformer:` must rename that key to `processor:` before upgrading. The
|
|
67
|
+
value assigned to it (a plain `(value: unknown) => T` function, or a call
|
|
68
|
+
like `processors.url()`) does not need to change -- only the key name.
|
|
69
|
+
|
|
70
|
+
- **Naming is now consistent end to end.** The helper namespace
|
|
71
|
+
(`processors.url()`), the schema field (`processor:`), the runtime type
|
|
72
|
+
(`Processor<T>`), thrown error headings (`"Processor failed:"`), and
|
|
73
|
+
generated documentation (`- Processor: yes`) all describe the same
|
|
74
|
+
concept with the same word. A developer no longer has to translate
|
|
75
|
+
between "processor" (what they import) and "transformer" (what they
|
|
76
|
+
assign it to).
|
|
77
|
+
|
|
78
|
+
- **The name now sets the right expectation for schema authors.** A
|
|
79
|
+
`processor` reads as "produce the value this contract should expose,"
|
|
80
|
+
encouraging authors to do complete, one-time preparation (parsing,
|
|
81
|
+
decoding, resolving) in that function rather than a narrow coercion that
|
|
82
|
+
downstream code still has to finish preparing on every read. It also fits
|
|
83
|
+
naturally with per-capability ownership ([0003](0003-no-global-env-object.md)):
|
|
84
|
+
two capabilities can process the same raw variable into two different final
|
|
85
|
+
forms, each already finished, with no shared coercion step to agree on.
|
|
86
|
+
|
|
87
|
+
- **No change to `EnvDefinition`'s minimal vocabulary.** This rename does
|
|
88
|
+
not add, remove, or restructure fields -- `default`, `processor`, and
|
|
89
|
+
`validator` remain the whole runtime vocabulary described in
|
|
90
|
+
[0001](0001-runtime-documentation-separation.md).
|
|
91
|
+
|
|
92
|
+
## Alternatives considered
|
|
93
|
+
|
|
94
|
+
- **Keep `transformer`, and only address the helpers naming.** Rejected:
|
|
95
|
+
the helpers module and its `processors` export were already named this
|
|
96
|
+
way; the mismatch this decision fixes is that the _schema field_ never
|
|
97
|
+
caught up, not the reverse.
|
|
98
|
+
|
|
99
|
+
- **Support both `transformer` and `processor` as accepted aliases.**
|
|
100
|
+
Rejected. `EnvDefinition`'s whole design principle is a minimal, explicit
|
|
101
|
+
vocabulary (see [0001](0001-runtime-documentation-separation.md)). A
|
|
102
|
+
synonym field would double the surface `validateEnv()` and the
|
|
103
|
+
build-time parser (`src/build/parse.ts`) both need to recognize,
|
|
104
|
+
indefinitely, for no runtime benefit.
|
|
105
|
+
|
|
106
|
+
- **Deprecate `transformer` and migrate over a transition window.**
|
|
107
|
+
Rejected. The package is pre-1.0 (`0.1.0`) with no external consumers
|
|
108
|
+
depending on the existing field name yet, so a direct rename is simpler
|
|
109
|
+
and cheaper than introducing, and later removing, a deprecation shim.
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# 0008: A fixed gzip budget on the runtime and helpers entry points
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented in `ci/size-budgets.mjs`, run via `npm run size` and
|
|
6
|
+
wired into `prepublishOnly`, so it is enforced at publish time rather than
|
|
7
|
+
being an optional CI check a maintainer can ignore.
|
|
8
|
+
|
|
9
|
+
## Amendment
|
|
10
|
+
|
|
11
|
+
The helpers budget is now **4096 bytes (4KB)**; the runtime's stays at 3KB. The budget was calibrated on
|
|
12
|
+
minified output, and the standard now forbids minified output (internal-package-contract's `NoMinify`
|
|
13
|
+
check), under which the same helpers gzip to about 3.2KB. This was a one-time recalibration to the new
|
|
14
|
+
baseline, recorded in `ci/size-budgets.mjs`, and not a loosening for growth. Where this record says both
|
|
15
|
+
entry points share the 3KB ceiling, read it as the original decision.
|
|
16
|
+
|
|
17
|
+
## Context
|
|
18
|
+
|
|
19
|
+
`env-cap` makes a specific claim in its own architecture: the runtime
|
|
20
|
+
stays "small and stable" while documentation, discovery, and reporting live
|
|
21
|
+
in build-time tooling that never ships to an application (0001). That claim
|
|
22
|
+
only holds because of a second decision — there is no `/client` or `/server`
|
|
23
|
+
split (0004). One runtime implementation, exported from the package root,
|
|
24
|
+
is what every consumer imports, including code that ends up in a browser
|
|
25
|
+
bundle. There is no smaller, trimmed-down client package to fall back on if
|
|
26
|
+
the shared runtime grows. Whatever size `dist/index.js` and `dist/helpers.js`
|
|
27
|
+
are, that is the size every browser-bound feature pays.
|
|
28
|
+
|
|
29
|
+
Left unchecked, that size is just a sentence in a README. Runtime code
|
|
30
|
+
accretes for reasonable-sounding reasons — a clearer error message, an extra
|
|
31
|
+
option field, a convenience helper — and none of those changes look like
|
|
32
|
+
"bloat" in the PR that introduces them. Without an automated check, the only
|
|
33
|
+
way to notice the runtime had grown would be to manually gzip the build
|
|
34
|
+
output and compare it to a number nobody had written down, which is to say:
|
|
35
|
+
nobody would notice until a consumer complained about bundle size, by which
|
|
36
|
+
point the growth would already be load-bearing and hard to revert.
|
|
37
|
+
|
|
38
|
+
`ci/size-budgets.mjs` exists to make "the runtime stays small" a build
|
|
39
|
+
failure instead of a promise. The remaining question this decision addresses
|
|
40
|
+
is what the number should be, and specifically why it's 3KB gzipped rather
|
|
41
|
+
than something looser (5KB) or stricter (1KB).
|
|
42
|
+
|
|
43
|
+
## Decision
|
|
44
|
+
|
|
45
|
+
`ci/size-budgets.mjs` gzips `dist/index.js` (the `.` entry point —
|
|
46
|
+
`createEnv`, `validateEnv`, error types, contract redaction) and
|
|
47
|
+
`dist/helpers.js` (the `./helpers` entry point — `processors`, `validators`)
|
|
48
|
+
and fails the build if either exceeds **3072 bytes (3KB) gzipped**. At the
|
|
49
|
+
time of writing, actual usage is 2081B (68% of budget) for the runtime and
|
|
50
|
+
1030B (34% of budget) for helpers — both comfortably under, neither close to
|
|
51
|
+
the edge by accident.
|
|
52
|
+
|
|
53
|
+
`dist/build.js` and `dist/cli/index.js` are deliberately **not** budgeted.
|
|
54
|
+
They are Node-only, dev-time-only tooling (0002) — `build.js` alone is
|
|
55
|
+
~53KB raw, almost an order of magnitude over the runtime's entire gzip
|
|
56
|
+
budget, because it embeds TypeScript-compiler-scale AST parsing that has no
|
|
57
|
+
reason to be small. That's fine, because it never runs inside an application
|
|
58
|
+
bundle; the tree-shaking and browser-platform-bundle tests are what
|
|
59
|
+
guarantee it stays isolated from `index.js`/`helpers.js`, not the size
|
|
60
|
+
budget. The size budget's job is narrower and more specific: bound exactly
|
|
61
|
+
the two artifacts that cross the boundary described in 0001 and 0004, and
|
|
62
|
+
nothing else.
|
|
63
|
+
|
|
64
|
+
### Why not 1KB
|
|
65
|
+
|
|
66
|
+
A 1KB ceiling isn't stricter in any useful sense — it's already broken by
|
|
67
|
+
functionality the architecture is explicitly committed to, not by bloat.
|
|
68
|
+
The runtime's 2081B includes per-key lazy getters, `EnvNotReadyError`,
|
|
69
|
+
aggregated `EnvValidationError` (0005 requires collecting _every_ failure
|
|
70
|
+
rather than throwing on the first, which costs more code than a fail-fast
|
|
71
|
+
check would), and the `Symbol.for("nodejs.util.inspect.custom")` /
|
|
72
|
+
`toString()` / `toJSON()` overrides that make `console.log(contract)` safe
|
|
73
|
+
by default (0006). None of that is incidental — each piece is the direct
|
|
74
|
+
implementation of a numbered decision. Fitting inside 1KB would mean cutting
|
|
75
|
+
one of them to satisfy the budget, which is backwards: the budget is
|
|
76
|
+
supposed to protect the architecture, not force a rewrite of it. A ceiling
|
|
77
|
+
the intended design can't pass under normal operation isn't a guardrail,
|
|
78
|
+
it's noise a team learns to route around — either by routinely waiving it or
|
|
79
|
+
by quietly stripping the features that made the number fail in the first
|
|
80
|
+
place.
|
|
81
|
+
|
|
82
|
+
### Why not 5KB
|
|
83
|
+
|
|
84
|
+
5KB is loose enough to stop working as a forcing function. Measured against
|
|
85
|
+
today's actual size, a 5KB ceiling would leave roughly 4KB — about
|
|
86
|
+
two-thirds of the entire budget — as slack the check would never flag: room
|
|
87
|
+
enough to vendor a small validation dependency, inline logic that belongs in
|
|
88
|
+
`helpers` instead of the runtime core, or let the redaction/error-handling
|
|
89
|
+
code duplicate itself across a couple of code paths, all without the build
|
|
90
|
+
ever turning red. `env-cap`'s pitch is explicitly "no unnecessary
|
|
91
|
+
runtime complexity" (README) — the budget's entire job is to catch that kind
|
|
92
|
+
of drift automatically, before a maintainer has to notice it by hand in a
|
|
93
|
+
bundle analyzer. Note also that this was never primarily about shaving
|
|
94
|
+
load time in absolute terms: 3–5KB gzipped is negligible next to a typical
|
|
95
|
+
application bundle (hundreds of KB to several MB). The budget is a proxy for
|
|
96
|
+
"did the runtime's shape change," not a user-facing performance target — and
|
|
97
|
+
a looser number quietly stops measuring that, even while technically still
|
|
98
|
+
"passing."
|
|
99
|
+
|
|
100
|
+
### Why 3KB
|
|
101
|
+
|
|
102
|
+
3KB sits meaningfully above current usage — enough headroom (roughly 1KB
|
|
103
|
+
above the runtime's actual 2081B, about half again its current size) that
|
|
104
|
+
ordinary maintenance doesn't force a budget renegotiation on every PR. A new
|
|
105
|
+
processor, a clearer error message, an extra `CreateEnvOptions` field can
|
|
106
|
+
land without anyone touching `check-size.mjs`. But the amount of growth that
|
|
107
|
+
would exhaust that headroom — roughly 50% growth in a module whose entire
|
|
108
|
+
job is to stay minimal — is bigger than any single feature the runtime is
|
|
109
|
+
expected to gain at once. Hitting the ceiling is meant to prompt a question
|
|
110
|
+
("does this belong in the runtime, or in `helpers`/`build`/`documentEnv()`
|
|
111
|
+
metadata?"), not a reflex to raise the number.
|
|
112
|
+
|
|
113
|
+
The same 3KB ceiling is applied to both entry points rather than tuning two
|
|
114
|
+
separate numbers per module. That's intentional, not laziness: `helpers`
|
|
115
|
+
(processors/validators) is optional sugar most contracts don't even import,
|
|
116
|
+
so it earns no larger allowance than the runtime core every contract
|
|
117
|
+
depends on. One number, applied uniformly, also keeps the check itself
|
|
118
|
+
trivial to read and hard to quietly special-case.
|
|
119
|
+
|
|
120
|
+
## Consequences
|
|
121
|
+
|
|
122
|
+
- **"The runtime stays small" has teeth.** `npm run size` — and by
|
|
123
|
+
extension `prepublishOnly` — fails the build the moment either entry
|
|
124
|
+
point crosses 3072 bytes gzipped, turning the Consequences section of
|
|
125
|
+
0001 from a claim into an enforced property of every published release.
|
|
126
|
+
|
|
127
|
+
- **The check is self-explanatory.** `ci/size-budgets.mjs` prints the
|
|
128
|
+
measured gzip size against the fixed budget for both entry points, so a
|
|
129
|
+
contributor who trips it sees exactly how much they added and against
|
|
130
|
+
what limit, without needing to consult this document to understand what
|
|
131
|
+
"too big" means.
|
|
132
|
+
|
|
133
|
+
- **The number is calibrated to the implementation, not to an external
|
|
134
|
+
performance target.** 3KB was not derived from a Core Web Vitals
|
|
135
|
+
threshold or a competitive benchmark against other environment-validation
|
|
136
|
+
libraries; it was set relative to what the intended architecture actually
|
|
137
|
+
costs today, plus deliberate headroom. If the runtime's legitimate,
|
|
138
|
+
necessary scope grows substantially, the budget will need a conscious
|
|
139
|
+
revision — that's an accepted cost, preferable to a budget that's either
|
|
140
|
+
unenforceable (1KB) or too loose to catch drift (5KB).
|
|
141
|
+
|
|
142
|
+
- **Genuinely necessary growth can still hit the ceiling.** A contributor
|
|
143
|
+
adding a real, justified few hundred bytes may need to trim elsewhere or
|
|
144
|
+
open a follow-up decision to raise the budget rather than merging past it
|
|
145
|
+
silently. That friction is the point, not a flaw to design around.
|
|
146
|
+
|
|
147
|
+
## Alternatives considered
|
|
148
|
+
|
|
149
|
+
- **No automated budget; rely on code review to notice growth.**
|
|
150
|
+
Rejected. Growth by a hundred bytes at a time across many reasonable-
|
|
151
|
+
looking PRs is exactly what review reliably misses. Nothing would catch a
|
|
152
|
+
single large accidental addition (an inlined dependency, a duplicated
|
|
153
|
+
utility) until a consumer noticed the bundle size themselves.
|
|
154
|
+
|
|
155
|
+
- **One shared budget across all four `dist` outputs
|
|
156
|
+
(`index.js`, `helpers.js`, `build.js`, `cli/index.js`).**
|
|
157
|
+
Rejected. This conflates dev-time-only Node tooling — which already
|
|
158
|
+
depends on TypeScript-compiler-scale machinery per 0002 — with the two
|
|
159
|
+
artifacts that actually ship to applications. A shared number would
|
|
160
|
+
either force the CLI to be unrealistically small or let the runtime hide
|
|
161
|
+
its growth inside a much larger combined ceiling.
|
|
162
|
+
|
|
163
|
+
- **A raw-byte budget instead of gzip.**
|
|
164
|
+
Rejected. Gzip (or an equivalent) is what actually crosses the network
|
|
165
|
+
for essentially every real consumer — bundlers and CDNs compress by
|
|
166
|
+
default — so it's the more accurate proxy for real-world cost, and it's
|
|
167
|
+
the unit comparable packages conventionally report their size in.
|
|
168
|
+
|
|
169
|
+
- **A budget expressed as a percentage of a typical application bundle.**
|
|
170
|
+
Rejected. That number depends on the size of a consuming application's
|
|
171
|
+
own bundle, which `env-cap` has no visibility into and no control
|
|
172
|
+
over. An absolute gzip ceiling is the only kind of budget the package
|
|
173
|
+
itself can actually own and enforce.
|