@maverickcer/env-cap 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (136) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +438 -0
  4. package/CODE_OF_CONDUCT.md +124 -0
  5. package/CODE_REVIEW.md +200 -0
  6. package/CONTRIBUTING.md +131 -0
  7. package/GUIDE.md +1214 -0
  8. package/PROMPT.md +89 -0
  9. package/README.md +92 -200
  10. package/RELEASING.md +160 -0
  11. package/SECURITY.md +270 -0
  12. package/SUPPORT.md +76 -0
  13. package/VERSIONING.md +118 -0
  14. package/benchmarks/READING-BENCHMARKS.md +197 -0
  15. package/benchmarks/README.md +126 -0
  16. package/benchmarks/WRITING-BENCHMARKS.md +252 -0
  17. package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
  18. package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
  19. package/dist/.dts/_ipc/build-fs.d.ts +53 -0
  20. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
  21. package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
  22. package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
  23. package/dist/.dts/_ipc/display-path.d.ts +27 -0
  24. package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
  25. package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
  26. package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
  27. package/dist/.dts/_ipc/glob.d.ts +22 -0
  28. package/dist/.dts/_ipc/glob.d.ts.map +1 -0
  29. package/dist/.dts/_ipc/no-node-fs.d.ts +34 -0
  30. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
  31. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  32. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  33. package/dist/.dts/_ipc/typescript.d.ts +20 -0
  34. package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
  35. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  36. package/dist/.dts/build/compiler-api.d.ts +3 -6
  37. package/dist/.dts/build/compiler-api.d.ts.map +1 -1
  38. package/dist/.dts/build/display-path.d.ts +3 -21
  39. package/dist/.dts/build/display-path.d.ts.map +1 -1
  40. package/dist/.dts/build/generated-banner.d.ts +21 -42
  41. package/dist/.dts/build/generated-banner.d.ts.map +1 -1
  42. package/dist/.dts/build/glob.d.ts +3 -15
  43. package/dist/.dts/build/glob.d.ts.map +1 -1
  44. package/dist/.dts/build/link.d.ts.map +1 -1
  45. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  46. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  47. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
  48. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  49. package/dist/.dts/build/types.d.ts +4 -53
  50. package/dist/.dts/build/types.d.ts.map +1 -1
  51. package/dist/.dts/build/typescript.d.ts +3 -17
  52. package/dist/.dts/build/typescript.d.ts.map +1 -1
  53. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  54. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  55. package/dist/.dts/eslint-plugin/index.d.ts +1 -1
  56. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  57. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  58. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  59. package/dist/{build-H4KFV44Z.js → build-WKDIAWF7.js} +198 -60
  60. package/dist/build-WKDIAWF7.js.map +1 -0
  61. package/dist/build.cjs +194 -56
  62. package/dist/build.cjs.map +1 -1
  63. package/dist/build.js +194 -56
  64. package/dist/build.js.map +1 -1
  65. package/dist/{chunk-7GVPOHDU.js → chunk-KEGYUHBU.js} +2 -2
  66. package/dist/cli/index.js +36 -29
  67. package/dist/cli/index.js.map +1 -1
  68. package/dist/eslint-plugin/index.cjs +84 -54
  69. package/dist/eslint-plugin/index.cjs.map +1 -1
  70. package/dist/eslint-plugin/index.js +83 -53
  71. package/dist/eslint-plugin/index.js.map +1 -1
  72. package/examples/README.md +95 -0
  73. package/package.json +48 -14
  74. package/skills/env-cap/SKILL.md +91 -0
  75. package/skills/env-cap/references/api.md +220 -0
  76. package/specs/architecture.md +634 -0
  77. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  78. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  79. package/specs/decisions/0003-no-global-env-object.md +172 -0
  80. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  81. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  82. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  83. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  84. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  85. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  86. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  87. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  88. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  89. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  90. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  91. package/specs/decisions/0015-security-backport-window.md +60 -0
  92. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  93. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  94. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  95. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  96. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  97. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  98. package/specs/decisions/0022-validation-contexts.md +267 -0
  99. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  100. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  101. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  102. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  103. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  104. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  105. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  106. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  107. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  108. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  109. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  110. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  111. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  112. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  113. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  114. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  115. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  116. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  117. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  118. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  119. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  120. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  121. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  122. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  123. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  124. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  125. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  126. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  127. package/specs/generated-artifacts.md +104 -0
  128. package/specs/migrations/README.md +30 -0
  129. package/specs/migrations/from-centralized-schema.md +503 -0
  130. package/specs/migrations/from-dotenv.md +352 -0
  131. package/specs/migrations/from-envalid.md +482 -0
  132. package/specs/migrations/from-process-env.md +398 -0
  133. package/specs/migrations/from-t3-env.md +416 -0
  134. package/specs/migrations/from-zod.md +303 -0
  135. package/dist/build-H4KFV44Z.js.map +0 -1
  136. /package/dist/{chunk-7GVPOHDU.js.map → chunk-KEGYUHBU.js.map} +0 -0
@@ -0,0 +1,197 @@
1
+ # 0001: Separate `createEnv` (runtime) from `documentEnv` (build-time, inert)
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/runtime/create.ts`, `src/runtime/document.ts`,
6
+ and `src/runtime/types.ts`.
7
+
8
+ ## Design evolution
9
+
10
+ The first implementation combined runtime validation and documentation metadata
11
+ into a single environment definition.
12
+
13
+ The approach was initially attractive because it provided a single source of
14
+ truth:
15
+
16
+ ```ts
17
+ defineEnv({
18
+ DATABASE_URL: {
19
+ processor,
20
+ validator,
21
+ description,
22
+ owner,
23
+ expiresAt,
24
+ },
25
+ })
26
+ ```
27
+
28
+ During implementation, this design exposed several constraints:
29
+
30
+ - Runtime consumers and build tooling had different information requirements.
31
+ - Documentation fields could grow independently from validation requirements.
32
+ - Rich metadata increased the risk of accidentally shipping non-runtime data
33
+ into client bundles.
34
+ - Runtime validation should remain deterministic and independent from
35
+ operational tooling.
36
+
37
+ The design was changed before stabilization by separating runtime execution
38
+ from documentation analysis.
39
+
40
+ This decision reflects an intentional tradeoff: the API became slightly more
41
+ verbose in exchange for a smaller runtime boundary, clearer security
42
+ properties, and better long-term maintainability.
43
+
44
+ ## Context
45
+
46
+ An environment-contract system has two fundamentally different categories of
47
+ information for each variable:
48
+
49
+ 1. **Runtime behavior** — how a value is processed and validated. This
50
+ includes defaults, processors, and validators. This information must be
51
+ available to `validateEnv()` during application startup across every
52
+ supported runtime environment (server, edge, browser, tests).
53
+
54
+ 2. **Operational documentation** — how a human understands and maintains the
55
+ variable. This includes descriptions, ownership, expiration dates, refresh
56
+ guidance, runbooks, and related operational context. This information is
57
+ useful for generated documentation and maintenance workflows, but it has no
58
+ role in resolving the runtime value.
59
+
60
+ The initial API design combined both concerns:
61
+
62
+ ```ts
63
+ defineEnv({
64
+ DATABASE_URL: {
65
+ processor,
66
+ validator,
67
+ description,
68
+ owner,
69
+ expiresAt,
70
+ refreshInstructions,
71
+ },
72
+ })
73
+ ```
74
+
75
+ While convenient, this couples runtime behavior to documentation concerns.
76
+ Documentation naturally grows over time and may contain large amounts of
77
+ human-oriented context, while runtime initialization should remain minimal,
78
+ predictable, and safe to execute in every environment.
79
+
80
+ ## Decision
81
+
82
+ Separate runtime creation from build-time documentation using two operations
83
+ against the same schema definition:
84
+
85
+ ```ts
86
+ export const databaseEnv = createEnv(databaseSchema, {
87
+ name: "database",
88
+ })
89
+
90
+ documentEnv(databaseSchema, {
91
+ owner: "platform",
92
+ variables: {
93
+ DATABASE_URL: {
94
+ description: "...",
95
+ },
96
+ },
97
+ })
98
+ ```
99
+
100
+ `createEnv()` accepts only runtime-relevant schema information. Its
101
+ `EnvDefinition` type intentionally excludes fields that exist exclusively for
102
+ documentation.
103
+
104
+ `documentEnv()` is intentionally inert at runtime. It does not register
105
+ values, mutate global state, or retain documentation data. Its implementation
106
+ exists so build tooling can statically discover documentation metadata through
107
+ AST parsing while allowing developers to keep documentation associated with
108
+ the schema it describes.
109
+
110
+ The build system links `documentEnv()` data back to the corresponding
111
+ `createEnv()` schema during generation. The runtime never needs to know that
112
+ documentation exists.
113
+
114
+ ## Consequences
115
+
116
+ - **Runtime remains small and stable.** Documentation can grow with project
117
+ needs without increasing runtime memory usage, validation cost, or bundle
118
+ size. The runtime package remains focused only on resolving and validating
119
+ environment variables.
120
+
121
+ - **Runtime errors intentionally do not include documentation metadata.**
122
+ Validation failures cannot include descriptions, owners, or operational
123
+ guidance because that information is not available to the runtime layer.
124
+ Generated documentation artifacts are the appropriate place for human
125
+ context, while runtime errors should remain focused on validation state and
126
+ failure details.
127
+
128
+ - **Documentation can still enter a client bundle if developers import it
129
+ incorrectly.** Separating `createEnv()` and `documentEnv()` does not
130
+ prevent bundlers from including literal documentation data passed into a
131
+ function call. If a schema file containing `documentEnv()` is imported into
132
+ a browser bundle, those literals may be included because bundlers cannot
133
+ generally remove arguments passed into executed functions.
134
+
135
+ This is an application-boundary concern rather than a runtime design flaw.
136
+ Documentation fields should be treated as potentially public and should not
137
+ contain secrets, credentials, internal-only security details, or information
138
+ that should not be exposed to clients.
139
+
140
+ - **Documentation coverage is convention-based rather than mandatory.**
141
+ `createEnv()` can exist without a matching `documentEnv()` call. The build
142
+ tooling treats missing documentation as a discoverable issue rather than a
143
+ runtime failure. This preserves flexibility while still allowing teams to
144
+ enforce documentation standards through generated reports and CI checks.
145
+
146
+ - **Schema ownership remains capability-local.** Developers can keep runtime
147
+ configuration and operational knowledge near the capability that owns it without
148
+ forcing a centralized environment file. The build layer can aggregate this
149
+ information for reporting without introducing runtime coupling.
150
+
151
+ ## Future reconsiderations before 1.0
152
+
153
+ This decision intentionally prioritizes runtime simplicity and build-time
154
+ analysis. Before a 1.0 release, several areas should continue to be evaluated:
155
+
156
+ - **Whether the two-call API provides sufficient ergonomics.**
157
+ Keeping runtime and documentation separate improves boundaries, but requiring
158
+ two declarations may create friction. Future versions may explore syntax
159
+ improvements without merging the responsibilities back together. See the
160
+ README's ["Status"](../../README.md#status) section for this package's
161
+ general pre-1.0 stability posture.
162
+
163
+ - **Whether documentation completeness should remain opt-in.**
164
+ The current model allows teams to adopt documentation gradually. Enterprise
165
+ environments may prefer stricter defaults where undocumented variables fail
166
+ builds.
167
+
168
+ - **Whether generated artifacts need additional operational workflows.**
169
+ The current design reports lifecycle information but intentionally does not
170
+ manage rotation, secret retrieval, or infrastructure operations. Those
171
+ capabilities may belong in separate tooling rather than expanding the
172
+ runtime package.
173
+
174
+ - **Whether the runtime API is stable enough for a major release.**
175
+ The current separation creates a strong boundary, but usage across different
176
+ deployment environments may reveal additional runtime requirements that
177
+ should be addressed before committing to a 1.x compatibility guarantee.
178
+
179
+ ## Alternatives considered
180
+
181
+ - **A single API containing runtime and documentation fields.**
182
+
183
+ Rejected: this couples the runtime API, memory model, and type surface to
184
+ documentation complexity. It also creates unnecessary opportunities for
185
+ documentation data to become part of runtime errors, logs, telemetry, or
186
+ client bundles.
187
+
188
+ - **Documentation stored in separate files with no schema relationship.**
189
+
190
+ Rejected: an unlinked documentation system cannot reliably determine whether
191
+ documentation matches the current schema. The build system would lose the
192
+ ability to identify issues such as undocumented variables, stale
193
+ documentation entries, or mismatched variable references.
194
+
195
+ Keeping `documentEnv()` structurally connected to the schema allows the
196
+ generator to validate documentation completeness while maintaining a strict
197
+ separation between runtime execution and build-time analysis.
@@ -0,0 +1,233 @@
1
+ # 0002: Build Tooling Parses Schema Files as AST; It Never Imports or Executes Them
2
+
3
+ ## Status
4
+
5
+ Accepted.
6
+
7
+ Implemented in:
8
+
9
+ - `src/build/discover.ts`
10
+ - `src/build/parse.ts`
11
+ - `src/build/literal-eval.ts`
12
+ - `src/build/link.ts`
13
+
14
+ ## Context
15
+
16
+ `generateEnvManifest()` needs to understand the environment contracts defined throughout an application. For each discovered schema, the build process needs to determine:
17
+
18
+ - declared environment variable names
19
+ - available processors and validators
20
+ - static schema configuration such as defaults
21
+ - relationships between `createEnv()` definitions and `documentEnv()` metadata
22
+
23
+ The most straightforward approach would be to import each discovered schema file and inspect the exported objects.
24
+
25
+ For `env-cap`, that approach is intentionally avoided.
26
+
27
+ Importing discovered files creates two problems:
28
+
29
+ ### 1. Discovery would become code execution
30
+
31
+ A build tool that scans a filesystem and imports every matching schema file would execute arbitrary application code during generation.
32
+
33
+ This is undesirable for a tool commonly used in:
34
+
35
+ - CI pipelines
36
+ - monorepos
37
+ - automated documentation generation
38
+ - deployment workflows
39
+
40
+ The generator should analyze application structure, not execute application behavior.
41
+
42
+ ### 2. Runtime evaluation does not provide additional correctness
43
+
44
+ Environment values are not resolved during generation.
45
+
46
+ Processors and validators operate later when the application calls:
47
+
48
+ ```ts
49
+ validateEnv({ manifest, values })
50
+ ```
51
+
52
+ against actual environment values.
53
+
54
+ At build time, there is no meaningful resolved output from executing a processor because the real input does not exist yet.
55
+
56
+ The build tool needs to understand the declared contract, not execute the runtime contract.
57
+
58
+ ## Decision
59
+
60
+ Schema files are analyzed using the TypeScript compiler API as an abstract syntax tree (AST).
61
+
62
+ The build system uses:
63
+
64
+ ```ts
65
+ ts.createSourceFile()
66
+ ```
67
+
68
+ for parsing.
69
+
70
+ It never uses:
71
+
72
+ - `import()`
73
+ - `require()`
74
+ - `eval()`
75
+ - transpilation followed by execution
76
+
77
+ Only statically analyzable expressions are evaluated.
78
+
79
+ `evaluateLiteral()` in `src/build/literal-eval.ts` resolves safe literal values:
80
+
81
+ Supported:
82
+
83
+ - string literals
84
+ - numeric literals
85
+ - boolean literals
86
+ - `null`
87
+ - unary negative numeric values
88
+ - arrays containing supported literals
89
+ - objects containing supported literals
90
+
91
+ Unsupported expressions are not guessed.
92
+
93
+ Examples that remain unresolved:
94
+
95
+ ```ts
96
+ process.env.DEFAULT_VALUE
97
+ ```
98
+
99
+ ```ts
100
+ createDefault()
101
+ ```
102
+
103
+ ```ts
104
+ ;`${prefix}_VALUE`
105
+ ```
106
+
107
+ ```ts
108
+ {
109
+ ...sharedConfig
110
+ }
111
+ ```
112
+
113
+ These resolve as unknown and are reported through parse warnings or unresolved links.
114
+
115
+ The same safety principle applies to file discovery and output generation:
116
+
117
+ - `discoverSchemaFiles()` prunes excluded directories such as `node_modules` and `.git` during traversal instead of scanning and filtering afterward.
118
+ - Generated output paths are validated with `resolveWithinRoot()` before writing to prevent configured locations from escaping the intended project root.
119
+
120
+ ## Consequences
121
+
122
+ ### Some valid JavaScript patterns are intentionally not discoverable
123
+
124
+ Schemas that are dynamically constructed cannot always be analyzed.
125
+
126
+ Examples:
127
+
128
+ ```ts
129
+ createEnv(buildSchema())
130
+ ```
131
+
132
+ ```ts
133
+ createEnv({
134
+ ...sharedVariables,
135
+ })
136
+ ```
137
+
138
+ ```ts
139
+ export { paymentsEnv } from "./shared"
140
+ ```
141
+
142
+ These may produce unresolved entries or warnings instead of complete contract information.
143
+
144
+ This is an intentional limitation.
145
+
146
+ The generator prioritizes predictable analysis over attempting to execute arbitrary application logic.
147
+
148
+ ### Conflict analysis is conservative
149
+
150
+ Because the build tool does not execute processors or validators, it cannot determine every possible runtime behavior.
151
+
152
+ It can identify conflicts that are statically provable.
153
+
154
+ For example:
155
+
156
+ ```ts
157
+ (value): string
158
+ ```
159
+
160
+ versus:
161
+
162
+ ```ts
163
+ (value): boolean
164
+ ```
165
+
166
+ for the same variable can be identified as incompatible.
167
+
168
+ However, two functions with unknown runtime behavior are treated as requiring developer review rather than being incorrectly classified.
169
+
170
+ This follows the principle:
171
+
172
+ > Prove what can be proven. Report uncertainty instead of inventing certainty.
173
+
174
+ ### The build tool can safely analyze unfamiliar codebases
175
+
176
+ `generateEnvManifest()` can run against large repositories without executing discovered schema files.
177
+
178
+ This prevents a schema file from becoming an unexpected execution path during documentation or contract generation.
179
+
180
+ The build system analyzes source structure; it does not run application code.
181
+
182
+ ### TypeScript is isolated to build tooling
183
+
184
+ AST analysis requires a TypeScript parser.
185
+
186
+ This is why `typescript` is associated only with the build functionality rather than the runtime package.
187
+
188
+ Runtime consumers do not need:
189
+
190
+ - TypeScript compiler APIs
191
+ - filesystem access
192
+ - source parsing
193
+ - code generation
194
+
195
+ The runtime remains dependency-free and environment agnostic.
196
+
197
+ ## Alternatives Considered
198
+
199
+ ### Import every discovered schema file
200
+
201
+ Rejected.
202
+
203
+ Although this provides direct access to exported objects, it introduces unnecessary code execution risk.
204
+
205
+ It also does not solve the full documentation problem because `documentEnv()` metadata is intentionally separate from runtime contracts.
206
+
207
+ A runtime import would still require an additional mechanism to discover and associate documentation metadata.
208
+
209
+ ### Regex-based source scanning
210
+
211
+ Rejected.
212
+
213
+ Regex parsing is insufficient for understanding TypeScript semantics.
214
+
215
+ A real AST provides:
216
+
217
+ - reliable syntax analysis
218
+ - import relationship resolution
219
+ - TypeScript type information
220
+ - structural distinction between known and unknown values
221
+
222
+ It also enables more accurate cross-file linking between `createEnv()` and `documentEnv()` definitions.
223
+
224
+ ## Summary
225
+
226
+ The build system intentionally behaves like a compiler analysis tool, not a runtime loader.
227
+
228
+ `env-cap` separates:
229
+
230
+ - **build time:** understand application structure safely
231
+ - **runtime:** validate and provide environment values
232
+
233
+ This keeps generation deterministic, avoids arbitrary code execution, and preserves the small runtime footprint that is central to the package design.
@@ -0,0 +1,172 @@
1
+ # 0003: No Global `env` Object — Only Capability-Owned Contracts
2
+
3
+ ## Status
4
+
5
+ Accepted.
6
+
7
+ Implemented in `src/runtime/create.ts` and reflected throughout the documentation. Capabilities expose their own environment contracts, such as `paymentsEnv.STRIPE_KEY`, rather than accessing variables through a global namespace such as `env.payments.STRIPE_KEY`.
8
+
9
+ ## Context
10
+
11
+ Many environment-validation libraries create a single global environment object:
12
+
13
+ ```ts
14
+ env.DATABASE_URL
15
+ env.STRIPE_KEY
16
+ ```
17
+
18
+ All variables are declared within one shared schema, often in one central file. While this approach is simple initially, it creates ownership and scalability problems as an application grows.
19
+
20
+ A centralized schema becomes a shared modification point that every capability must update when adding configuration. This creates several issues:
21
+
22
+ - **Capability development becomes coupled to unrelated code.** Adding a new capability requires modifying a file owned by another area of the application, increasing merge conflicts and creating unnecessary coordination.
23
+ - **Capability removal becomes incomplete.** Removing a capability requires someone to identify and delete all associated variables from a shared schema. Unused configuration can remain indefinitely because ownership is unclear.
24
+ - **Configuration ownership becomes ambiguous.** A global object does not communicate which capability owns, validates, or depends on a variable.
25
+
26
+ `env-cap` treats environment configuration as part of capability ownership rather than application-wide shared state.
27
+
28
+ ## Decision
29
+
30
+ `createEnv()` creates an environment contract scoped to the schema that defines it.
31
+
32
+ A capability owns its environment schema and exports the resulting contract from the same module:
33
+
34
+ ```ts
35
+ // features/payments/env.schema.ts
36
+
37
+ export const paymentsEnv = createEnv({
38
+ STRIPE_KEY: {
39
+ processor: processors.string(),
40
+ validator: validators.required(),
41
+ },
42
+ })
43
+ ```
44
+
45
+ Application code accesses configuration through the capability contract that owns it:
46
+
47
+ ```ts
48
+ paymentsEnv.STRIPE_KEY
49
+ ```
50
+
51
+ The package intentionally does not provide a mechanism for merging multiple contracts into a single global environment object.
52
+
53
+ The only systems that operate across multiple contracts are build-time or lifecycle systems:
54
+
55
+ - `generateEnvManifest()` can discover and describe contracts.
56
+ - `validateEnv()` can initialize validation across contracts.
57
+
58
+ Neither exposes a flattened runtime value object. `validateEnv()` returns execution metadata (`validateEnvResult`), not the resolved environment values.
59
+
60
+ ## Consequences
61
+
62
+ ### Capability ownership remains explicit
63
+
64
+ Two capabilities may define the same environment variable name without creating runtime collisions:
65
+
66
+ ```ts
67
+ postgresEnv.DATABASE_URL
68
+ mongoEnv.DATABASE_URL
69
+ ```
70
+
71
+ Each contract applies its own processor and validator rules to the raw environment value.
72
+
73
+ There is no merge operation where conflicting definitions must be resolved.
74
+
75
+ Potential overlaps are treated as an architectural concern and can be surfaced through build-time analysis such as `detectCompatibilityIssues()`, allowing developers to decide whether the duplication is intentional.
76
+
77
+ ### Accidental cross-capability coupling is reduced
78
+
79
+ A developer cannot access another capability's configuration through a global namespace:
80
+
81
+ ```ts
82
+ env.someOtherCapabilityVariable
83
+ ```
84
+
85
+ Access requires importing the contract that owns the variable:
86
+
87
+ ```ts
88
+ import { paymentsEnv } from "./payments/env.schema"
89
+
90
+ paymentsEnv.STRIPE_KEY
91
+ ```
92
+
93
+ This creates a structural relationship between a capability and its configuration instead of relying on naming conventions.
94
+
95
+ ### Runtime does not maintain a centralized configuration inventory
96
+
97
+ There is intentionally no runtime object containing every environment variable in the application.
98
+
99
+ This is a deliberate tradeoff.
100
+
101
+ A global inventory is useful for:
102
+
103
+ - documentation
104
+ - auditing
105
+ - dependency analysis
106
+ - lifecycle reporting
107
+
108
+ Those concerns belong to build-time tooling, where `env-cap` can generate artifacts without forcing runtime code to carry application-wide metadata.
109
+
110
+ The generated contract and documentation systems provide visibility without reintroducing a centralized runtime dependency.
111
+
112
+ ### Contracts remain globally accessible only through normal module semantics
113
+
114
+ A capability contract can be imported throughout an application:
115
+
116
+ ```ts
117
+ import { paymentsEnv } from "./payments/env.schema"
118
+ ```
119
+
120
+ Multiple imports reference the same module instance through the JavaScript module system.
121
+
122
+ This provides consistent runtime behavior without requiring a package-managed singleton registry. The package does not own global state; the application module system provides the appropriate sharing behavior.
123
+
124
+ ## Alternatives Considered
125
+
126
+ ### Global namespaced registry
127
+
128
+ Example:
129
+
130
+ ```ts
131
+ env.payments.STRIPE_KEY
132
+ ```
133
+
134
+ Rejected.
135
+
136
+ A global registry recreates the same ownership problem at another level. Every capability must now register itself into shared mutable state, introducing additional concerns:
137
+
138
+ - Who owns namespace naming?
139
+ - How are collisions handled?
140
+ - What happens when two capabilities expose the same name?
141
+ - When is the registry considered complete?
142
+ - Does initialization order affect behavior?
143
+
144
+ Additionally, automatic registration requires every capability module to be imported before the registry is complete, creating hidden dependency requirements.
145
+
146
+ ### Automatic discovery that builds a global runtime object
147
+
148
+ Rejected.
149
+
150
+ Discovery is a build-time concern, not a runtime execution concern.
151
+
152
+ Automatically scanning files and creating runtime state would:
153
+
154
+ - introduce filesystem/build assumptions
155
+ - create implicit side effects
156
+ - make application startup behavior harder to reason about
157
+ - blur the boundary between development tooling and runtime code
158
+
159
+ `env-cap` uses explicit build-time discovery to generate artifacts while keeping runtime behavior deterministic and framework-independent.
160
+
161
+ ## Summary
162
+
163
+ `env-cap` treats environment configuration as capability-owned infrastructure rather than a global application resource.
164
+
165
+ The runtime model intentionally favors:
166
+
167
+ - explicit ownership over convenience access
168
+ - composition over centralization
169
+ - build-time visibility over runtime metadata
170
+ - deterministic imports over implicit discovery
171
+
172
+ The result is a configuration system that scales with capability boundaries instead of creating a larger shared dependency as the application grows.