@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,398 @@
1
+ # Migrating from direct `process.env` usage
2
+
3
+ Many applications begin by reading environment variables directly from Node's built-in environment object:
4
+
5
+ ```ts
6
+ const databaseUrl = process.env.DATABASE_URL
7
+ const stripeKey = process.env.STRIPE_SECRET_KEY
8
+ ```
9
+
10
+ This approach is flexible and requires no additional tooling. However, as applications grow, direct `process.env` access creates several challenges:
11
+
12
+ - Environment requirements are scattered throughout the codebase.
13
+ - Validation logic is repeated across capabilities.
14
+ - It is difficult to identify which part of the application owns a variable.
15
+ - Removing unused configuration requires manually searching for references.
16
+ - Platform teams lack a reliable inventory of application configuration.
17
+
18
+ `env-cap` does not replace `process.env`. It creates an ownership and validation layer around it.
19
+
20
+ The relationship is:
21
+
22
+ ```text
23
+ process.env
24
+ |
25
+ v
26
+ env-cap validation
27
+ |
28
+ v
29
+ capability-owned environment contract
30
+ |
31
+ v
32
+ application code
33
+ ```
34
+
35
+ ## Migration goals
36
+
37
+ The recommended migration path is incremental:
38
+
39
+ 1. Find existing environment variable usage.
40
+ 2. Group variables by the capability that consumes them.
41
+ 3. Create capability-owned environment contracts.
42
+ 4. Replace direct `process.env` reads with validated access.
43
+ 5. Generate project-wide configuration artifacts through build tooling.
44
+
45
+ The goal is not to centralize configuration. The goal is to make ownership explicit.
46
+
47
+ ## Before: direct process.env access
48
+
49
+ A typical application:
50
+
51
+ ```ts
52
+ // payments/stripe.ts
53
+
54
+ const stripeKey = process.env.STRIPE_SECRET_KEY
55
+
56
+ if (!stripeKey) {
57
+ throw new Error("Missing Stripe key")
58
+ }
59
+
60
+ initializeStripe(stripeKey)
61
+ ```
62
+
63
+ Another module:
64
+
65
+ ```ts
66
+ // database/connection.ts
67
+
68
+ const databaseUrl = process.env.DATABASE_URL
69
+
70
+ connect(databaseUrl)
71
+ ```
72
+
73
+ The application works, but configuration ownership is implicit.
74
+
75
+ The environment variables exist globally:
76
+
77
+ ```text
78
+ process.env
79
+
80
+ ├── STRIPE_SECRET_KEY
81
+ ├── DATABASE_URL
82
+ ├── REDIS_URL
83
+ ├── SMTP_PASSWORD
84
+ └── INTERNAL_API_KEY
85
+ ```
86
+
87
+ Any file can access any value.
88
+
89
+ ## After: capability-owned environment contracts
90
+
91
+ Move configuration definitions next to the capability that uses them.
92
+
93
+ Example:
94
+
95
+ ```ts
96
+ // features/payments/env.schema.ts
97
+
98
+ import { createEnv, documentEnv } from "@maverickcer/env-cap"
99
+
100
+ const paymentsSchema = {
101
+ STRIPE_SECRET_KEY: {
102
+ validator(value: string) {
103
+ return value.startsWith("sk_") || 'Expected a key starting with "sk_".'
104
+ },
105
+ },
106
+ }
107
+
108
+ export const paymentsEnv = createEnv(paymentsSchema, {
109
+ name: "payments",
110
+ })
111
+
112
+ documentEnv(paymentsSchema, {
113
+ owner: "payments-team",
114
+ variables: {
115
+ STRIPE_SECRET_KEY: {
116
+ description: "Stripe API credential used for payment processing",
117
+ },
118
+ },
119
+ })
120
+ ```
121
+
122
+ The capability now owns its requirement:
123
+
124
+ ```ts
125
+ import { paymentsEnv } from "./env.schema"
126
+
127
+ initializeStripe(paymentsEnv.STRIPE_SECRET_KEY)
128
+ ```
129
+
130
+ The dependency becomes explicit.
131
+
132
+ A payments module depends on payment configuration instead of depending on an application-wide environment object.
133
+
134
+ ## Migrating existing variables
135
+
136
+ ### Step 1: Find environment usage
137
+
138
+ Search the application:
139
+
140
+ ```ts
141
+ process.env
142
+ ```
143
+
144
+ Create an inventory:
145
+
146
+ ```text
147
+ STRIPE_SECRET_KEY
148
+ used by:
149
+ - features/payments
150
+ - scripts/refund-job
151
+
152
+ DATABASE_URL
153
+ used by:
154
+ - database module
155
+ - migrations
156
+ ```
157
+
158
+ Do not move variables based only on their names. Move them based on the code that consumes them.
159
+
160
+ ## Step 2: Create capability schemas
161
+
162
+ Create schemas alongside existing modules:
163
+
164
+ ```text
165
+ src/
166
+
167
+ ├── features/
168
+ │ ├── payments/
169
+ │ │ └── env.schema.ts
170
+ │ │
171
+ │ ├── notifications/
172
+ │ │ └── env.schema.ts
173
+ │ │
174
+ │ └── reporting/
175
+ │ └── env.schema.ts
176
+ ```
177
+
178
+ Each schema defines only the variables required by that capability.
179
+
180
+ ## Step 3: Replace direct reads
181
+
182
+ Before:
183
+
184
+ ```ts
185
+ const apiKey = process.env.STRIPE_SECRET_KEY
186
+ ```
187
+
188
+ After:
189
+
190
+ ```ts
191
+ const apiKey = paymentsEnv.STRIPE_SECRET_KEY
192
+ ```
193
+
194
+ The application no longer receives an unknown value. It receives a value that has passed the capability's validation rules.
195
+
196
+ ## Step 4: Add startup validation
197
+
198
+ Generate a manifest:
199
+
200
+ ```ts
201
+ await generateEnvManifest({
202
+ location: "src/generated/env.manifest.ts",
203
+ })
204
+ ```
205
+
206
+ Validate once during startup:
207
+
208
+ ```ts
209
+ import { validateEnv } from "@maverickcer/env-cap"
210
+ import { manifest } from "./generated/env.manifest"
211
+
212
+ await validateEnv({
213
+ manifest,
214
+ values: process.env,
215
+ })
216
+ ```
217
+
218
+ After validation:
219
+
220
+ ```ts
221
+ paymentsEnv.STRIPE_SECRET_KEY
222
+ ```
223
+
224
+ returns the processed value.
225
+
226
+ Before validation completes:
227
+
228
+ ```ts
229
+ paymentsEnv.STRIPE_SECRET_KEY
230
+ ```
231
+
232
+ throws an `EnvNotReadyError`.
233
+
234
+ ## Handling existing validation logic
235
+
236
+ Many applications already have inline validation:
237
+
238
+ ```ts
239
+ const port = Number(process.env.PORT)
240
+
241
+ if (Number.isNaN(port)) {
242
+ throw new Error("Invalid PORT")
243
+ }
244
+ ```
245
+
246
+ Move that logic into the contract:
247
+
248
+ ```ts
249
+ const serverSchema = {
250
+ PORT: {
251
+ processor(value: string) {
252
+ return Number(value)
253
+ },
254
+ validator(value: number) {
255
+ return (Number.isInteger(value) && value > 0) || "Expected a positive integer."
256
+ },
257
+ },
258
+ }
259
+ ```
260
+
261
+ The validation remains near the code that understands the variable's purpose.
262
+
263
+ ## Handling shared environment variables
264
+
265
+ A common concern during migration is:
266
+
267
+ > "What if multiple capabilities use the same environment variable?"
268
+
269
+ The answer depends on whether the variable represents the same concept.
270
+
271
+ If multiple capabilities truly share the same configuration meaning:
272
+
273
+ ```env
274
+ LOG_LEVEL=info
275
+ ```
276
+
277
+ multiple contracts may reference it:
278
+
279
+ ```ts
280
+ loggingEnv.LOG_LEVEL
281
+ apiEnv.LOG_LEVEL
282
+ ```
283
+
284
+ If capabilities process the same raw value differently, each capability can define its own contract:
285
+
286
+ ```env
287
+ CACHE_TIMEOUT=60000
288
+ ```
289
+
290
+ One capability may need:
291
+
292
+ ```ts
293
+ cacheEnv.CACHE_TIMEOUT
294
+ // number
295
+ ```
296
+
297
+ while another may need:
298
+
299
+ ```ts
300
+ monitoringEnv.CACHE_TIMEOUT
301
+ // string for reporting
302
+ ```
303
+
304
+ A centralized object would have to choose one global interpretation. Feature-owned contracts keep processing decisions local.
305
+
306
+ ## Coexisting with existing environment files
307
+
308
+ `env-cap` does not require changing how environments are provided.
309
+
310
+ Existing systems continue to work:
311
+
312
+ ```text
313
+ Docker
314
+ |
315
+ Kubernetes
316
+ |
317
+ Cloud provider secrets
318
+ |
319
+ CI/CD variables
320
+ |
321
+ process.env
322
+ |
323
+ env-cap
324
+ ```
325
+
326
+ The package validates and organizes values after they enter the application process.
327
+
328
+ ## Removing the old environment object
329
+
330
+ After migration:
331
+
332
+ Before:
333
+
334
+ ```text
335
+ src/
336
+
337
+ ├── env.ts
338
+ │ ├── DATABASE_URL
339
+ │ ├── STRIPE_SECRET_KEY
340
+ │ └── REDIS_URL
341
+ ```
342
+
343
+ After:
344
+
345
+ ```text
346
+ src/
347
+
348
+ ├── database/
349
+ │ └── env.schema.ts
350
+ │
351
+ ├── payments/
352
+ │ └── env.schema.ts
353
+ │
354
+ └── cache/
355
+ └── env.schema.ts
356
+ ```
357
+
358
+ The environment requirements move with the capabilities that own them.
359
+
360
+ ## When direct process.env usage may be enough
361
+
362
+ Direct `process.env` access can be appropriate when:
363
+
364
+ - the application is small
365
+ - there are few environment variables
366
+ - configuration ownership is obvious
367
+ - validation requirements are minimal
368
+
369
+ `env-cap` is intended for applications where configuration management becomes a coordination problem between developers and platform teams.
370
+
371
+ ## Summary
372
+
373
+ Migrating from `process.env` changes configuration from an implicit global dependency into an explicit capability dependency.
374
+
375
+ Before:
376
+
377
+ ```text
378
+ capability
379
+ |
380
+ v
381
+ process.env.SOME_VARIABLE
382
+ ```
383
+
384
+ After:
385
+
386
+ ```text
387
+ capability
388
+ |
389
+ v
390
+ capabilityEnv.SOME_VARIABLE
391
+ |
392
+ v
393
+ validated configuration contract
394
+ ```
395
+
396
+ `process.env` remains the source of configuration values.
397
+
398
+ `env-cap` provides the structure needed to safely manage those values as applications and teams scale.