@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,482 @@
1
+ # Migrating from envalid
2
+
3
+ This guide explains how to migrate an application using
4
+ [`envalid`](https://github.com/af/envalid) to `env-cap`.
5
+
6
+ The migration is not a replacement of validation capabilities. `envalid` and
7
+ `env-cap` solve different problems:
8
+
9
+ - `envalid` focuses on validating environment variables and producing a typed
10
+ configuration object.
11
+ - `env-cap` focuses on configuration ownership, lifecycle visibility,
12
+ modular architecture, and runtime access boundaries.
13
+
14
+ `env-cap` can use the same validation approach you already have today,
15
+ including custom validators and processors. The primary change is moving
16
+ from a centralized configuration object to capability-owned environment
17
+ contracts.
18
+
19
+ ## Before: centralized environment validation
20
+
21
+ A typical `envalid` setup looks like:
22
+
23
+ ```ts
24
+ import { cleanEnv, str, num } from "envalid"
25
+
26
+ export const env = cleanEnv(process.env, {
27
+ DATABASE_URL: str(),
28
+ PORT: num(),
29
+ STRIPE_SECRET_KEY: str(),
30
+ })
31
+ ```
32
+
33
+ Application code accesses everything through one shared object:
34
+
35
+ ```ts
36
+ env.DATABASE_URL
37
+ env.PORT
38
+ env.STRIPE_SECRET_KEY
39
+ ```
40
+
41
+ This works well for small applications. As applications grow, the environment
42
+ configuration becomes a shared ownership boundary:
43
+
44
+ ```text
45
+ src/
46
+ ├── env.ts
47
+ ├── payments/
48
+ ├── database/
49
+ ├── reports/
50
+ └── notifications/
51
+ ```
52
+
53
+ Every capability that requires configuration modifies the same file.
54
+
55
+ Common consequences:
56
+
57
+ - configuration ownership becomes unclear
58
+ - unrelated capabilities modify the same schema
59
+ - removing capabilities requires cleaning up centralized variables
60
+ - platform teams need separate tooling to understand ownership
61
+
62
+ ## After: capability-owned contracts
63
+
64
+ With `env-cap`, move configuration ownership into the capability that uses
65
+ it.
66
+
67
+ Example:
68
+
69
+ ```text
70
+ src/
71
+ ├── database/
72
+ │ └── env.schema.ts
73
+ ├── payments/
74
+ │ └── env.schema.ts
75
+ └── reports/
76
+ └── env.schema.ts
77
+ ```
78
+
79
+ The database capability owns database configuration:
80
+
81
+ ```ts
82
+ // database/env.schema.ts
83
+
84
+ import { createEnv } from "@maverickcer/env-cap"
85
+
86
+ const databaseSchema = {
87
+ DATABASE_URL: {
88
+ validator(value: string) {
89
+ return value.startsWith("postgres://") || 'Expected a value starting with "postgres://".'
90
+ },
91
+ },
92
+ }
93
+
94
+ export const databaseEnv = createEnv(databaseSchema, {
95
+ name: "database",
96
+ })
97
+ ```
98
+
99
+ The payments capability owns payment configuration:
100
+
101
+ ```ts
102
+ // payments/env.schema.ts
103
+
104
+ import { createEnv } from "@maverickcer/env-cap"
105
+
106
+ const paymentsSchema = {
107
+ STRIPE_SECRET_KEY: {
108
+ validator(value: string) {
109
+ return value.startsWith("sk_") || 'Expected a value starting with "sk_".'
110
+ },
111
+ },
112
+ }
113
+
114
+ export const paymentsEnv = createEnv(paymentsSchema, {
115
+ name: "payments",
116
+ })
117
+ ```
118
+
119
+ Application code imports configuration from the capability that owns it:
120
+
121
+ ```ts
122
+ import { databaseEnv } from "./database/env.schema"
123
+
124
+ databaseEnv.DATABASE_URL
125
+ ```
126
+
127
+ There is no global:
128
+
129
+ ```ts
130
+ env.DATABASE_URL
131
+ ```
132
+
133
+ The import relationship becomes the ownership relationship.
134
+
135
+ ---
136
+
137
+ ## Migration strategy
138
+
139
+ The migration can happen incrementally.
140
+
141
+ You do not need to convert every environment variable at once.
142
+
143
+ ### Step 1: Keep your existing environment loading
144
+
145
+ `env-cap` does not replace dotenv, deployment secrets, or your existing
146
+ environment provider.
147
+
148
+ Continue loading values however your application currently does:
149
+
150
+ ```ts
151
+ dotenv.config()
152
+ ```
153
+
154
+ or:
155
+
156
+ ```ts
157
+ process.env
158
+ ```
159
+
160
+ The package only validates and exposes configuration.
161
+
162
+ ---
163
+
164
+ ### Step 2: Identify capability ownership
165
+
166
+ Start by grouping existing variables by the code that consumes them.
167
+
168
+ Example existing configuration:
169
+
170
+ ```ts
171
+ DATABASE_URL
172
+ PORT
173
+ STRIPE_SECRET_KEY
174
+ REDIS_URL
175
+ SMTP_HOST
176
+ ```
177
+
178
+ Move toward:
179
+
180
+ ```text
181
+ database/
182
+ DATABASE_URL
183
+
184
+ server/
185
+ PORT
186
+
187
+ payments/
188
+ STRIPE_SECRET_KEY
189
+
190
+ cache/
191
+ REDIS_URL
192
+
193
+ email/
194
+ SMTP_HOST
195
+ ```
196
+
197
+ The goal is not fewer environment variables.
198
+
199
+ The goal is clear ownership.
200
+
201
+ ---
202
+
203
+ ### Step 3: Convert validators
204
+
205
+ Most `envalid` validators map directly to `env-cap` processors and
206
+ validators.
207
+
208
+ #### String validation
209
+
210
+ Before:
211
+
212
+ ```ts
213
+ import { str } from "envalid"
214
+
215
+ STRIPE_SECRET_KEY: str()
216
+ ```
217
+
218
+ After:
219
+
220
+ ```ts
221
+ STRIPE_SECRET_KEY: {
222
+ validator(value: string) {
223
+ return value.length > 0 || "This variable is required.";
224
+ },
225
+ }
226
+ ```
227
+
228
+ ---
229
+
230
+ #### Number conversion
231
+
232
+ Before:
233
+
234
+ ```ts
235
+ import { num } from "envalid"
236
+
237
+ PORT: num()
238
+ ```
239
+
240
+ After:
241
+
242
+ ```ts
243
+ PORT: {
244
+ processor(value: string) {
245
+ return Number(value);
246
+ },
247
+ validator(value: number) {
248
+ return Number.isInteger(value) || "Expected an integer.";
249
+ },
250
+ }
251
+ ```
252
+
253
+ The important distinction is that transformation and validation are explicit.
254
+
255
+ The runtime contract defines how the capability consumes the value.
256
+
257
+ ---
258
+
259
+ #### Default values
260
+
261
+ Before:
262
+
263
+ ```ts
264
+ PORT: num({
265
+ default: 3000,
266
+ })
267
+ ```
268
+
269
+ After:
270
+
271
+ ```ts
272
+ PORT: {
273
+ default: 3000,
274
+ processor(value: string) {
275
+ return Number(value);
276
+ },
277
+ }
278
+ ```
279
+
280
+ ---
281
+
282
+ ### Step 4: Add documentation metadata
283
+
284
+ `envalid` validates configuration, but it does not create an ownership model.
285
+
286
+ Add operational metadata separately:
287
+
288
+ ```ts
289
+ import { documentEnv } from "@maverickcer/env-cap"
290
+
291
+ documentEnv(databaseSchema, {
292
+ owner: "platform",
293
+ variables: {
294
+ DATABASE_URL: {
295
+ description: "Primary PostgreSQL connection string",
296
+ expiresAt: "2027-01-01T00:00:00Z",
297
+ },
298
+ },
299
+ })
300
+ ```
301
+
302
+ This enables generated documentation without adding metadata to runtime
303
+ configuration.
304
+
305
+ ---
306
+
307
+ ### Step 5: Replace centralized imports gradually
308
+
309
+ Before:
310
+
311
+ ```ts
312
+ import { env } from "./env"
313
+
314
+ export function createPayment() {
315
+ return stripe(env.STRIPE_SECRET_KEY)
316
+ }
317
+ ```
318
+
319
+ After:
320
+
321
+ ```ts
322
+ import { paymentsEnv } from "./payments/env.schema"
323
+
324
+ export function createPayment() {
325
+ return stripe(paymentsEnv.STRIPE_SECRET_KEY)
326
+ }
327
+ ```
328
+
329
+ Continue migrating capability by capability until the centralized environment object
330
+ is no longer needed.
331
+
332
+ ---
333
+
334
+ ## Differences from envalid
335
+
336
+ ### Environment validation
337
+
338
+ Both packages support:
339
+
340
+ - required variables
341
+ - defaults
342
+ - transformations
343
+ - custom validation
344
+ - startup validation
345
+
346
+ The difference is the ownership model.
347
+
348
+ `envalid` answers:
349
+
350
+ > "Are all environment variables valid?"
351
+
352
+ `env-cap` answers:
353
+
354
+ > "Which capability owns this configuration, how is it validated, and how is it
355
+ > operated over time?"
356
+
357
+ ---
358
+
359
+ ### Multiple consumers with different requirements
360
+
361
+ A centralized environment object often requires choosing one representation:
362
+
363
+ ```ts
364
+ env.TIMEOUT
365
+ ```
366
+
367
+ Should `TIMEOUT` be:
368
+
369
+ ```ts
370
+ string
371
+ ```
372
+
373
+ or:
374
+
375
+ ```ts
376
+ number
377
+ ```
378
+
379
+ Different consumers may have different needs.
380
+
381
+ Example:
382
+
383
+ ```ts
384
+ // HTTP client configuration
385
+ timeout: "5000"
386
+ ```
387
+
388
+ A library integration may require a string because it serializes directly into
389
+ headers or configuration.
390
+
391
+ Another capability may require:
392
+
393
+ ```ts
394
+ timeout: 5000
395
+ ```
396
+
397
+ for arithmetic:
398
+
399
+ ```ts
400
+ timeout + retryDelay
401
+ ```
402
+
403
+ The environment value is the same. The consumer requirement is different.
404
+
405
+ `env-cap` allows each owning capability to define its own processing boundary:
406
+
407
+ ```ts
408
+ apiClientEnv.TIMEOUT
409
+ // string
410
+
411
+ jobRunnerEnv.TIMEOUT
412
+ // number
413
+ ```
414
+
415
+ The build system can identify these situations for review without assuming
416
+ that one interpretation is universally correct.
417
+
418
+ ---
419
+
420
+ ## What stays the same
421
+
422
+ Migrating from envalid does not require changing:
423
+
424
+ - deployment secrets
425
+ - Docker configuration
426
+ - CI environment variables
427
+ - hosting provider configuration
428
+ - secret managers
429
+ - `.env` loading
430
+
431
+ The same environment values continue entering the application.
432
+
433
+ The change is where configuration ownership and validation logic live.
434
+
435
+ ---
436
+
437
+ ## When not to migrate
438
+
439
+ `envalid` may be the better choice when:
440
+
441
+ - the application is small
442
+ - one team owns all configuration
443
+ - a centralized config object is desirable
444
+ - operational documentation is managed elsewhere
445
+
446
+ `env-cap` is designed for applications where configuration ownership
447
+ becomes a scaling concern:
448
+
449
+ - large applications
450
+ - multiple teams
451
+ - monorepos
452
+ - platform engineering workflows
453
+ - long-lived services
454
+ - environments with operational lifecycle requirements
455
+
456
+ ---
457
+
458
+ ## Related approaches
459
+
460
+ `env-cap` is designed as a modular complement to validation libraries, not
461
+ as a replacement for every environment solution.
462
+
463
+ Similar centralized approaches include:
464
+
465
+ - `envalid`
466
+ - `t3-env`
467
+ - `zod`-based environment wrappers
468
+ - `dotenv` + custom configuration objects
469
+
470
+ These tools solve environment parsing and validation.
471
+
472
+ `env-cap` adds the organizational layer:
473
+
474
+ - capability ownership
475
+ - static discovery
476
+ - generated documentation
477
+ - lifecycle visibility
478
+ - configuration dependency mapping
479
+
480
+ The validation library answers whether a value is valid.
481
+
482
+ The contract system answers who owns that value and how it is maintained.