@maverickcer/env-cap 0.5.3 → 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.
- package/ADOPTION.md +144 -0
- package/AGENTS.md +146 -0
- package/CHANGELOG.md +438 -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 +97 -199
- 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 +34 -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/assemble-project.d.ts +1 -1
- package/dist/.dts/build/assemble-project.d.ts.map +1 -1
- package/dist/.dts/build/change-model.d.ts.map +1 -1
- package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
- package/dist/.dts/build/citation-verification.d.ts.map +1 -1
- package/dist/.dts/build/compatibility.d.ts.map +1 -1
- package/dist/.dts/build/compiler-api.d.ts +12 -0
- package/dist/.dts/build/compiler-api.d.ts.map +1 -0
- package/dist/.dts/build/dependency-graph.d.ts +3 -1
- package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
- package/dist/.dts/build/dependency-model.d.ts.map +1 -1
- package/dist/.dts/build/discover.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/docs.d.ts +1 -1
- package/dist/.dts/build/docs.d.ts.map +1 -1
- package/dist/.dts/build/env-example.d.ts.map +1 -1
- package/dist/.dts/build/evidence-cache.d.ts +1 -1
- package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
- package/dist/.dts/build/evidence-model.d.ts +2 -2
- package/dist/.dts/build/evidence-snapshot.d.ts +25 -0
- package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
- package/dist/.dts/build/finding-model.d.ts +1 -1
- package/dist/.dts/build/finding-model.d.ts.map +1 -1
- package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
- package/dist/.dts/build/generate-env-artifacts.d.ts +23 -8
- package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
- package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
- package/dist/.dts/build/generate-manifest.d.ts +1 -1
- package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
- package/dist/.dts/build/generate-usage.d.ts +3 -3
- package/dist/.dts/build/generate-usage.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +29 -38
- 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 +2 -2
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/literal-eval.d.ts +4 -3
- package/dist/.dts/build/literal-eval.d.ts.map +1 -1
- package/dist/.dts/build/live-expirations.d.ts.map +1 -1
- package/dist/.dts/build/manifest.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/parse.d.ts +12 -12
- package/dist/.dts/build/parse.d.ts.map +1 -1
- package/dist/.dts/build/reference-projections.d.ts +17 -3
- package/dist/.dts/build/reference-projections.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-import.d.ts +5 -0
- package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-package-schema.d.ts +1 -1
- package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -94
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/build/sarif.d.ts.map +1 -1
- package/dist/.dts/build/scan-dependencies.d.ts +23 -0
- package/dist/.dts/build/scan-dependencies.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 +6 -0
- package/dist/.dts/build/typescript.d.ts.map +1 -0
- package/dist/.dts/build/usage-report.d.ts.map +1 -1
- package/dist/.dts/cli/filesystem.d.ts +4 -0
- package/dist/.dts/cli/filesystem.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 +3 -3
- 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/.dts/evidence/index.d.ts +2 -2
- package/dist/.dts/helpers/index.d.ts +2 -2
- package/dist/.dts/helpers/processors.d.ts.map +1 -1
- package/dist/.dts/helpers/validators.d.ts.map +1 -1
- package/dist/.dts/runtime/cache.d.ts +0 -3
- package/dist/.dts/runtime/cache.d.ts.map +1 -1
- package/dist/.dts/runtime/create.d.ts.map +1 -1
- package/dist/.dts/runtime/document.d.ts.map +1 -1
- package/dist/.dts/runtime/index.d.ts +2 -2
- package/dist/.dts/runtime/registry.d.ts.map +1 -1
- package/dist/.dts/runtime/validate.d.ts.map +1 -1
- package/dist/{build-U326PI5A.js → build-WKDIAWF7.js} +685 -645
- package/dist/build-WKDIAWF7.js.map +1 -0
- package/dist/build.cjs +698 -651
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +695 -649
- package/dist/build.js.map +1 -1
- package/dist/{chunk-BSTLSR2R.js → chunk-KEGYUHBU.js} +2 -2
- package/dist/chunk-KEGYUHBU.js.map +1 -0
- package/dist/cli/index.js +64 -63
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +95 -626
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +94 -625
- package/dist/eslint-plugin/index.js.map +1 -1
- package/dist/evidence.cjs.map +1 -1
- package/dist/evidence.js.map +1 -1
- package/dist/helpers.cjs +4 -9
- package/dist/helpers.cjs.map +1 -1
- package/dist/helpers.js +4 -9
- package/dist/helpers.js.map +1 -1
- package/dist/index.cjs +11 -25
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +11 -25
- package/dist/index.js.map +1 -1
- package/dist/node.cjs +10 -8
- package/dist/node.cjs.map +1 -1
- package/dist/node.js +10 -8
- package/dist/node.js.map +1 -1
- package/examples/README.md +95 -0
- package/node_modules/@typescript/old/LICENSE.txt +55 -0
- package/node_modules/@typescript/old/README.md +50 -0
- package/node_modules/@typescript/old/SECURITY.md +39 -0
- package/node_modules/@typescript/old/ThirdPartyNoticeText.txt +193 -0
- package/node_modules/@typescript/old/bin/tsc +2 -0
- package/node_modules/@typescript/old/bin/tsserver +2 -0
- package/node_modules/@typescript/old/lib/_tsc.js +134465 -0
- package/node_modules/@typescript/old/lib/_tsserver.js +659 -0
- package/node_modules/@typescript/old/lib/_typingsInstaller.js +222 -0
- package/node_modules/@typescript/old/lib/cs/diagnosticMessages.generated.json +2129 -0
- package/node_modules/@typescript/old/lib/de/diagnosticMessages.generated.json +2125 -0
- package/node_modules/@typescript/old/lib/es/diagnosticMessages.generated.json +2129 -0
- package/node_modules/@typescript/old/lib/fr/diagnosticMessages.generated.json +2129 -0
- package/node_modules/@typescript/old/lib/it/diagnosticMessages.generated.json +2125 -0
- package/node_modules/@typescript/old/lib/ja/diagnosticMessages.generated.json +2129 -0
- package/node_modules/@typescript/old/lib/ko/diagnosticMessages.generated.json +2129 -0
- package/node_modules/@typescript/old/lib/lib.d.ts +20 -0
- package/node_modules/@typescript/old/lib/lib.decorators.d.ts +382 -0
- package/node_modules/@typescript/old/lib/lib.decorators.legacy.d.ts +20 -0
- package/node_modules/@typescript/old/lib/lib.dom.asynciterable.d.ts +18 -0
- package/node_modules/@typescript/old/lib/lib.dom.d.ts +45125 -0
- package/node_modules/@typescript/old/lib/lib.dom.iterable.d.ts +18 -0
- package/node_modules/@typescript/old/lib/lib.es2015.collection.d.ts +150 -0
- package/node_modules/@typescript/old/lib/lib.es2015.core.d.ts +595 -0
- package/node_modules/@typescript/old/lib/lib.es2015.d.ts +26 -0
- package/node_modules/@typescript/old/lib/lib.es2015.generator.d.ts +75 -0
- package/node_modules/@typescript/old/lib/lib.es2015.iterable.d.ts +603 -0
- package/node_modules/@typescript/old/lib/lib.es2015.promise.d.ts +79 -0
- package/node_modules/@typescript/old/lib/lib.es2015.proxy.d.ts +126 -0
- package/node_modules/@typescript/old/lib/lib.es2015.reflect.d.ts +142 -0
- package/node_modules/@typescript/old/lib/lib.es2015.symbol.d.ts +44 -0
- package/node_modules/@typescript/old/lib/lib.es2015.symbol.wellknown.d.ts +324 -0
- package/node_modules/@typescript/old/lib/lib.es2016.array.include.d.ts +114 -0
- package/node_modules/@typescript/old/lib/lib.es2016.d.ts +19 -0
- package/node_modules/@typescript/old/lib/lib.es2016.full.d.ts +21 -0
- package/node_modules/@typescript/old/lib/lib.es2016.intl.d.ts +29 -0
- package/node_modules/@typescript/old/lib/lib.es2017.arraybuffer.d.ts +19 -0
- package/node_modules/@typescript/old/lib/lib.es2017.d.ts +24 -0
- package/node_modules/@typescript/old/lib/lib.es2017.date.d.ts +29 -0
- package/node_modules/@typescript/old/lib/lib.es2017.full.d.ts +21 -0
- package/node_modules/@typescript/old/lib/lib.es2017.intl.d.ts +42 -0
- package/node_modules/@typescript/old/lib/lib.es2017.object.d.ts +47 -0
- package/node_modules/@typescript/old/lib/lib.es2017.sharedmemory.d.ts +133 -0
- package/node_modules/@typescript/old/lib/lib.es2017.string.d.ts +43 -0
- package/node_modules/@typescript/old/lib/lib.es2017.typedarrays.d.ts +51 -0
- package/node_modules/@typescript/old/lib/lib.es2018.asyncgenerator.d.ts +75 -0
- package/node_modules/@typescript/old/lib/lib.es2018.asynciterable.d.ts +51 -0
- package/node_modules/@typescript/old/lib/lib.es2018.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.es2018.full.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.es2018.intl.d.ts +81 -0
- package/node_modules/@typescript/old/lib/lib.es2018.promise.d.ts +28 -0
- package/node_modules/@typescript/old/lib/lib.es2018.regexp.d.ts +35 -0
- package/node_modules/@typescript/old/lib/lib.es2019.array.d.ts +77 -0
- package/node_modules/@typescript/old/lib/lib.es2019.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.es2019.full.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.es2019.intl.d.ts +21 -0
- package/node_modules/@typescript/old/lib/lib.es2019.object.d.ts +31 -0
- package/node_modules/@typescript/old/lib/lib.es2019.string.d.ts +35 -0
- package/node_modules/@typescript/old/lib/lib.es2019.symbol.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.es2020.bigint.d.ts +763 -0
- package/node_modules/@typescript/old/lib/lib.es2020.d.ts +25 -0
- package/node_modules/@typescript/old/lib/lib.es2020.date.d.ts +40 -0
- package/node_modules/@typescript/old/lib/lib.es2020.full.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.es2020.intl.d.ts +472 -0
- package/node_modules/@typescript/old/lib/lib.es2020.number.d.ts +26 -0
- package/node_modules/@typescript/old/lib/lib.es2020.promise.d.ts +45 -0
- package/node_modules/@typescript/old/lib/lib.es2020.sharedmemory.d.ts +97 -0
- package/node_modules/@typescript/old/lib/lib.es2020.string.d.ts +42 -0
- package/node_modules/@typescript/old/lib/lib.es2020.symbol.wellknown.d.ts +39 -0
- package/node_modules/@typescript/old/lib/lib.es2021.d.ts +21 -0
- package/node_modules/@typescript/old/lib/lib.es2021.full.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.es2021.intl.d.ts +164 -0
- package/node_modules/@typescript/old/lib/lib.es2021.promise.d.ts +46 -0
- package/node_modules/@typescript/old/lib/lib.es2021.string.d.ts +31 -0
- package/node_modules/@typescript/old/lib/lib.es2021.weakref.d.ts +76 -0
- package/node_modules/@typescript/old/lib/lib.es2022.array.d.ts +119 -0
- package/node_modules/@typescript/old/lib/lib.es2022.d.ts +23 -0
- package/node_modules/@typescript/old/lib/lib.es2022.error.d.ts +73 -0
- package/node_modules/@typescript/old/lib/lib.es2022.full.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.es2022.intl.d.ts +143 -0
- package/node_modules/@typescript/old/lib/lib.es2022.object.d.ts +24 -0
- package/node_modules/@typescript/old/lib/lib.es2022.regexp.d.ts +37 -0
- package/node_modules/@typescript/old/lib/lib.es2022.string.d.ts +23 -0
- package/node_modules/@typescript/old/lib/lib.es2023.array.d.ts +922 -0
- package/node_modules/@typescript/old/lib/lib.es2023.collection.d.ts +19 -0
- package/node_modules/@typescript/old/lib/lib.es2023.d.ts +20 -0
- package/node_modules/@typescript/old/lib/lib.es2023.full.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.es2023.intl.d.ts +62 -0
- package/node_modules/@typescript/old/lib/lib.es2024.arraybuffer.d.ts +63 -0
- package/node_modules/@typescript/old/lib/lib.es2024.collection.d.ts +27 -0
- package/node_modules/@typescript/old/lib/lib.es2024.d.ts +24 -0
- package/node_modules/@typescript/old/lib/lib.es2024.full.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.es2024.object.d.ts +27 -0
- package/node_modules/@typescript/old/lib/lib.es2024.promise.d.ts +33 -0
- package/node_modules/@typescript/old/lib/lib.es2024.regexp.d.ts +23 -0
- package/node_modules/@typescript/old/lib/lib.es2024.sharedmemory.d.ts +66 -0
- package/node_modules/@typescript/old/lib/lib.es2024.string.d.ts +27 -0
- package/node_modules/@typescript/old/lib/lib.es2025.collection.d.ts +94 -0
- package/node_modules/@typescript/old/lib/lib.es2025.d.ts +23 -0
- package/node_modules/@typescript/old/lib/lib.es2025.float16.d.ts +443 -0
- package/node_modules/@typescript/old/lib/lib.es2025.full.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.es2025.intl.d.ts +200 -0
- package/node_modules/@typescript/old/lib/lib.es2025.iterator.d.ts +146 -0
- package/node_modules/@typescript/old/lib/lib.es2025.promise.d.ts +32 -0
- package/node_modules/@typescript/old/lib/lib.es2025.regexp.d.ts +30 -0
- package/node_modules/@typescript/old/lib/lib.es5.d.ts +4599 -0
- package/node_modules/@typescript/old/lib/lib.es6.d.ts +21 -0
- package/node_modules/@typescript/old/lib/lib.esnext.array.d.ts +33 -0
- package/node_modules/@typescript/old/lib/lib.esnext.collection.d.ts +47 -0
- package/node_modules/@typescript/old/lib/lib.esnext.d.ts +27 -0
- package/node_modules/@typescript/old/lib/lib.esnext.date.d.ts +21 -0
- package/node_modules/@typescript/old/lib/lib.esnext.decorators.d.ts +26 -0
- package/node_modules/@typescript/old/lib/lib.esnext.disposable.d.ts +191 -0
- package/node_modules/@typescript/old/lib/lib.esnext.error.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.esnext.full.d.ts +22 -0
- package/node_modules/@typescript/old/lib/lib.esnext.intl.d.ts +107 -0
- package/node_modules/@typescript/old/lib/lib.esnext.sharedmemory.d.ts +23 -0
- package/node_modules/@typescript/old/lib/lib.esnext.temporal.d.ts +485 -0
- package/node_modules/@typescript/old/lib/lib.esnext.typedarrays.d.ts +90 -0
- package/node_modules/@typescript/old/lib/lib.scripthost.d.ts +320 -0
- package/node_modules/@typescript/old/lib/lib.webworker.asynciterable.d.ts +18 -0
- package/node_modules/@typescript/old/lib/lib.webworker.d.ts +15606 -0
- package/node_modules/@typescript/old/lib/lib.webworker.importscripts.d.ts +21 -0
- package/node_modules/@typescript/old/lib/lib.webworker.iterable.d.ts +18 -0
- package/node_modules/@typescript/old/lib/pl/diagnosticMessages.generated.json +2129 -0
- package/node_modules/@typescript/old/lib/pt-br/diagnosticMessages.generated.json +2129 -0
- package/node_modules/@typescript/old/lib/ru/diagnosticMessages.generated.json +2125 -0
- package/node_modules/@typescript/old/lib/tr/diagnosticMessages.generated.json +2129 -0
- package/node_modules/@typescript/old/lib/tsc.js +8 -0
- package/node_modules/@typescript/old/lib/tsserver.js +8 -0
- package/node_modules/@typescript/old/lib/tsserverlibrary.d.ts +17 -0
- package/node_modules/@typescript/old/lib/tsserverlibrary.js +21 -0
- package/node_modules/@typescript/old/lib/typesMap.json +497 -0
- package/node_modules/@typescript/old/lib/typescript.d.ts +11448 -0
- package/node_modules/@typescript/old/lib/typescript.js +201039 -0
- package/node_modules/@typescript/old/lib/typingsInstaller.js +8 -0
- package/node_modules/@typescript/old/lib/watchGuard.js +53 -0
- package/node_modules/@typescript/old/lib/zh-cn/diagnosticMessages.generated.json +2129 -0
- package/node_modules/@typescript/old/lib/zh-tw/diagnosticMessages.generated.json +2125 -0
- package/node_modules/@typescript/old/package.json +118 -0
- package/node_modules/@typescript/typescript6/LICENSE.txt +55 -0
- package/node_modules/@typescript/typescript6/README.md +9 -0
- package/node_modules/@typescript/typescript6/bin/tsc6 +2 -0
- package/node_modules/@typescript/typescript6/lib/tsc.js +1 -0
- package/node_modules/@typescript/typescript6/lib/tsserverlibrary.d.ts +2 -0
- package/node_modules/@typescript/typescript6/lib/tsserverlibrary.js +1 -0
- package/node_modules/@typescript/typescript6/lib/typescript.d.ts +2 -0
- package/node_modules/@typescript/typescript6/lib/typescript.js +1 -0
- package/node_modules/@typescript/typescript6/package.json +39 -0
- package/package.json +74 -22
- package/schemas/env-cap-report.schema.json +1 -1
- 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-U326PI5A.js.map +0 -1
- package/dist/chunk-BSTLSR2R.js.map +0 -1
|
@@ -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.
|