@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,503 @@
1
+ # Migrating from a Centralized Environment Schema
2
+
3
+ This guide explains how to migrate from a centralized environment configuration model into capability-owned environment contracts.
4
+
5
+ Examples of centralized schemas include:
6
+
7
+ ```text
8
+ src/config/env.ts
9
+ src/env/schema.ts
10
+ src/config/environment.ts
11
+ src/config/settings.ts
12
+ ```
13
+
14
+ where one file defines every environment variable used by the application:
15
+
16
+ ```ts
17
+ export const env = createConfig({
18
+ DATABASE_URL: ...,
19
+ STRIPE_SECRET_KEY: ...,
20
+ REDIS_URL: ...,
21
+ API_TIMEOUT: ...,
22
+ });
23
+ ```
24
+
25
+ Centralized schemas are a reasonable starting point. They provide a clear location for configuration and make small applications easy to understand.
26
+
27
+ As applications grow, however, the centralized file becomes a shared ownership boundary:
28
+
29
+ - Every capability change modifies the same file.
30
+ - Teams become dependent on whoever owns the schema.
31
+ - Removing capabilities requires finding unused configuration manually.
32
+ - Configuration ownership becomes separated from capability ownership.
33
+ - Merge conflicts increase as the application grows.
34
+
35
+ `env-cap` does not replace your validation system. It changes where environment ownership lives.
36
+
37
+ You can continue using Zod, Valibot, Joi, custom validators, or simple functions inside capability contracts.
38
+
39
+ The migration goal is:
40
+
41
+ ```text
42
+ centralized configuration
43
+ |
44
+ v
45
+ capability-owned contracts
46
+ |
47
+ v
48
+ generated project-wide visibility
49
+ ```
50
+
51
+ The runtime becomes modular while build tooling provides the centralized view when needed.
52
+
53
+ ---
54
+
55
+ ## Before migration
56
+
57
+ A centralized schema commonly looks like:
58
+
59
+ ```ts
60
+ // env.ts
61
+
62
+ export const env = {
63
+ DATABASE_URL: process.env.DATABASE_URL,
64
+ STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
65
+ REDIS_URL: process.env.REDIS_URL,
66
+ }
67
+ ```
68
+
69
+ or:
70
+
71
+ ```ts
72
+ // env.schema.ts
73
+
74
+ export const env = createConfig({
75
+ DATABASE_URL: z.string().url(),
76
+ STRIPE_SECRET_KEY: z.string(),
77
+ REDIS_URL: z.string(),
78
+ })
79
+ ```
80
+
81
+ Every capability imports the same object:
82
+
83
+ ```ts
84
+ import { env } from "./env"
85
+
86
+ await connectDatabase(env.DATABASE_URL)
87
+
88
+ stripe.configure(env.STRIPE_SECRET_KEY)
89
+
90
+ redis.connect(env.REDIS_URL)
91
+ ```
92
+
93
+ The problem is not the validation.
94
+
95
+ The problem is ownership.
96
+
97
+ The database capability owns `DATABASE_URL`, but the database configuration lives somewhere else.
98
+
99
+ ---
100
+
101
+ ## Migration strategy
102
+
103
+ Migrate one capability at a time.
104
+
105
+ Do not move every variable into `env-cap` immediately.
106
+
107
+ A gradual migration works best:
108
+
109
+ ```text
110
+ Before:
111
+
112
+ src/
113
+ ├── env.ts
114
+ ├── payments/
115
+ ├── database/
116
+ └── reports/
117
+
118
+
119
+ After:
120
+
121
+ src/
122
+ ├── env.ts (remaining legacy variables)
123
+ ├── payments/
124
+ │ └── env.schema.ts
125
+ ├── database/
126
+ │ └── env.schema.ts
127
+ └── reports/
128
+ └── env.schema.ts
129
+ ```
130
+
131
+ The application can temporarily support both approaches.
132
+
133
+ ---
134
+
135
+ ## Step 1: Identify ownership
136
+
137
+ For each variable, determine which capability requires it.
138
+
139
+ Example centralized schema:
140
+
141
+ ```ts
142
+ {
143
+ DATABASE_URL,
144
+ STRIPE_SECRET_KEY,
145
+ REPORT_TIMEOUT,
146
+ CACHE_TTL,
147
+ }
148
+ ```
149
+
150
+ Move ownership:
151
+
152
+ | Variable | New owner |
153
+ | ----------------- | --------- |
154
+ | DATABASE_URL | database |
155
+ | STRIPE_SECRET_KEY | payments |
156
+ | REPORT_TIMEOUT | reports |
157
+ | CACHE_TTL | cache |
158
+
159
+ Ownership should follow usage, not technical category.
160
+
161
+ A variable is not "database configuration" because it contains `DATABASE`.
162
+
163
+ It belongs to the capability that defines how it is consumed.
164
+
165
+ ---
166
+
167
+ ## Step 2: Create capability schemas
168
+
169
+ Create a schema next to the capability.
170
+
171
+ Example:
172
+
173
+ ```text
174
+ features/
175
+ └── payments/
176
+ ├── env.schema.ts
177
+ └── stripe.ts
178
+ ```
179
+
180
+ Move the relevant variable:
181
+
182
+ ```ts
183
+ import { createEnv, documentEnv } from "@maverickcer/env-cap"
184
+
185
+ const paymentsSchema = {
186
+ STRIPE_SECRET_KEY: {
187
+ validator(value: string) {
188
+ return value.startsWith("sk_") || 'Expected a value starting with "sk_".'
189
+ },
190
+ },
191
+ }
192
+
193
+ export const paymentsEnv = createEnv(paymentsSchema, {
194
+ name: "payments",
195
+ })
196
+
197
+ documentEnv(paymentsSchema, {
198
+ owner: "payments-team",
199
+ })
200
+ ```
201
+
202
+ The capability now owns its configuration.
203
+
204
+ ---
205
+
206
+ ## Step 3: Replace global imports
207
+
208
+ Before:
209
+
210
+ ```ts
211
+ import { env } from "../env"
212
+
213
+ stripe.configure(env.STRIPE_SECRET_KEY)
214
+ ```
215
+
216
+ After:
217
+
218
+ ```ts
219
+ import { paymentsEnv } from "./env.schema"
220
+
221
+ stripe.configure(paymentsEnv.STRIPE_SECRET_KEY)
222
+ ```
223
+
224
+ The dependency becomes explicit:
225
+
226
+ ```text
227
+ payment code
228
+ |
229
+ v
230
+ paymentsEnv
231
+ |
232
+ v
233
+ payments schema
234
+ ```
235
+
236
+ The capability no longer depends on a global configuration object.
237
+
238
+ ---
239
+
240
+ ## Step 4: Preserve existing validators
241
+
242
+ `env-cap` does not require replacing your validation library.
243
+
244
+ Existing logic can be moved directly.
245
+
246
+ ### Zod example
247
+
248
+ Before:
249
+
250
+ ```ts
251
+ export const env = z
252
+ .object({
253
+ STRIPE_SECRET_KEY: z.string().startsWith("sk_"),
254
+ })
255
+ .parse(process.env)
256
+ ```
257
+
258
+ After:
259
+
260
+ ```ts
261
+ import { z } from "zod"
262
+
263
+ const stripeKey = z.string().startsWith("sk_")
264
+
265
+ const paymentsSchema = {
266
+ STRIPE_SECRET_KEY: {
267
+ validator(value: string) {
268
+ return stripeKey.safeParse(value).success || 'Expected a value starting with "sk_".'
269
+ },
270
+ },
271
+ }
272
+ ```
273
+
274
+ The validation implementation is still yours.
275
+
276
+ `env-cap` provides:
277
+
278
+ - ownership boundaries
279
+ - lifecycle metadata
280
+ - static discovery
281
+ - generated artifacts
282
+ - runtime access patterns
283
+
284
+ It is not intended to replace schema validation libraries.
285
+
286
+ ---
287
+
288
+ ## Step 5: Generate project visibility
289
+
290
+ A centralized schema gave visibility because everything existed in one file.
291
+
292
+ Replace that visibility with generated artifacts.
293
+
294
+ Example:
295
+
296
+ ```ts
297
+ await generateEnvManifest({
298
+ location: "src/generated/env.manifest.ts",
299
+ })
300
+ ```
301
+
302
+ This allows tooling to answer:
303
+
304
+ - Which variables exist?
305
+ - Which capability owns them?
306
+ - Which variables are undocumented?
307
+ - Which variables are expiring?
308
+ - Which variables have possible conflicts?
309
+
310
+ The runtime stays modular.
311
+
312
+ The platform view remains centralized.
313
+
314
+ ---
315
+
316
+ ## Handling shared variables
317
+
318
+ A common migration concern is:
319
+
320
+ > "What happens if multiple capabilities use the same environment variable?"
321
+
322
+ The answer depends on whether the value has the same meaning.
323
+
324
+ If multiple capabilities consume the same value with identical requirements, create a shared ownership module:
325
+
326
+ ```text
327
+ features/
328
+ └── database/
329
+ └── env.schema.ts
330
+ ```
331
+
332
+ Other capabilities import the database contract:
333
+
334
+ ```ts
335
+ import { databaseEnv } from "../database/env.schema"
336
+
337
+ databaseEnv.DATABASE_URL
338
+ ```
339
+
340
+ If different capabilities interpret the same raw value differently, keep those interpretations local.
341
+
342
+ Example:
343
+
344
+ ```ts
345
+ // metrics capability
346
+ REPORT_INTERVAL_MS -> number
347
+
348
+ // logging capability
349
+ REPORT_INTERVAL_MS -> string identifier
350
+ ```
351
+
352
+ Both consume the same underlying environment value, but their application requirements differ.
353
+
354
+ A centralized schema must choose one global representation.
355
+
356
+ Capability contracts allow each consumer to define its own validated view.
357
+
358
+ ---
359
+
360
+ ## Removing the centralized schema
361
+
362
+ After migration:
363
+
364
+ ```text
365
+ src/
366
+ ├── env.ts remove
367
+ ├── payments/
368
+ │ └── env.schema.ts
369
+ ├── database/
370
+ │ └── env.schema.ts
371
+ └── reports/
372
+ └── env.schema.ts
373
+ ```
374
+
375
+ Remove:
376
+
377
+ - global exports
378
+ - centralized validation calls
379
+ - unused configuration helpers
380
+
381
+ The generated contract becomes the project-wide configuration inventory.
382
+
383
+ The application runtime no longer depends on a global environment object.
384
+
385
+ ---
386
+
387
+ ## Common migration mistakes
388
+
389
+ ### Moving variables by technical category
390
+
391
+ Avoid:
392
+
393
+ ```text
394
+ config/
395
+ ├── database.env.ts
396
+ ├── payments.env.ts
397
+ └── cache.env.ts
398
+ ```
399
+
400
+ These recreate centralized ownership.
401
+
402
+ Prefer:
403
+
404
+ ```text
405
+ features/
406
+ ├── checkout/
407
+ │ └── env.schema.ts
408
+ ├── reporting/
409
+ │ └── env.schema.ts
410
+ └── notifications/
411
+ └── env.schema.ts
412
+ ```
413
+
414
+ Configuration should follow capability ownership.
415
+
416
+ ---
417
+
418
+ ### Creating a new global wrapper
419
+
420
+ Avoid recreating:
421
+
422
+ ```ts
423
+ export const env = {
424
+ payments: paymentsEnv,
425
+ database: databaseEnv,
426
+ }
427
+ ```
428
+
429
+ This recreates the same coupling:
430
+
431
+ ```ts
432
+ env.payments.STRIPE_SECRET_KEY
433
+ ```
434
+
435
+ The capability import itself should define the dependency.
436
+
437
+ ---
438
+
439
+ ### Migrating documentation separately
440
+
441
+ Avoid creating:
442
+
443
+ ```text
444
+ docs/
445
+ └── environment.md
446
+ ```
447
+
448
+ as the only source of configuration information.
449
+
450
+ Documentation becomes stale when it is disconnected from code.
451
+
452
+ Use:
453
+
454
+ ```ts
455
+ documentEnv(schema, {
456
+ owner: "payments-team",
457
+ })
458
+ ```
459
+
460
+ so tooling can verify documentation coverage.
461
+
462
+ ---
463
+
464
+ ## When not to migrate
465
+
466
+ `env-cap` may not provide significant value for:
467
+
468
+ - small applications with few variables
469
+ - single-team projects with no ownership boundaries
470
+ - applications where all configuration truly belongs to one module
471
+
472
+ A centralized schema is not inherently wrong.
473
+
474
+ The value appears when configuration ownership becomes difficult to maintain.
475
+
476
+ ---
477
+
478
+ ## Migration complete
479
+
480
+ After migration:
481
+
482
+ | Responsibility | Location |
483
+ | ------------------ | ------------------- |
484
+ | Variable ownership | Capability schema |
485
+ | Validation logic | Capability schema |
486
+ | Runtime access | Capability contract |
487
+ | Documentation | `documentEnv()` |
488
+ | Project visibility | Generated artifacts |
489
+ | Platform reporting | Build tooling |
490
+
491
+ The application moves from:
492
+
493
+ ```text
494
+ one configuration object shared everywhere
495
+ ```
496
+
497
+ to:
498
+
499
+ ```text
500
+ many owned contracts with a generated system view
501
+ ```
502
+
503
+ without requiring a rewrite of existing validation logic.