@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,100 @@
|
|
|
1
|
+
# 0019: The published `--json` schema is generated from `src/cli/json.ts`'s types, never hand-authored
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented in `scripts/generate-json-schema.mjs`, committed at
|
|
6
|
+
`schemas/env-cap-report.schema.json`, published via the `./schema` subpath
|
|
7
|
+
export.
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
`--json`'s envelope is already committed to being semver-stable (ADR 0013)
|
|
12
|
+
and documented via prose plus one worked example in the README, backed
|
|
13
|
+
internally by the `JsonSuccessPayload`/`JsonErrorPayload` types in
|
|
14
|
+
`src/cli/json.ts`. None of that helps an external, non-TypeScript tool -- a
|
|
15
|
+
Go service, a Python dashboard, a generic CI linter -- validate or codegen
|
|
16
|
+
against real `--json` output without hand-transcribing the README's one
|
|
17
|
+
example. A real, standalone JSON Schema artifact closes that gap, but only
|
|
18
|
+
if it can't silently drift from the actual emitted shape -- a hand-authored
|
|
19
|
+
schema is itself a second place the envelope's shape has to be kept in sync
|
|
20
|
+
by hand, exactly the kind of duplication `report.d.mts` (ADR 0013 decision 7) already accepts as a narrow, one-off exception for a single internal
|
|
21
|
+
test-support file, not a pattern to repeat for a schema external parties
|
|
22
|
+
will build real tooling against.
|
|
23
|
+
|
|
24
|
+
## Decision
|
|
25
|
+
|
|
26
|
+
- **Generated from types, not hand-authored.** `scripts/generate-json-schema.mjs`
|
|
27
|
+
uses `ts-json-schema-generator` (a devDependency, not shipped at runtime)
|
|
28
|
+
to compile `src/cli/json.ts`'s exported `JsonReportPayload` type --
|
|
29
|
+
`JsonSuccessPayload | JsonErrorPayload`, the complete envelope shape --
|
|
30
|
+
directly into `schemas/env-cap-report.schema.json`. `report.d.mts`'s
|
|
31
|
+
hand-kept-in-sync exception is accepted there specifically because it's
|
|
32
|
+
one internal file with one maintainer's own test suite as the only
|
|
33
|
+
consumer; a schema published for arbitrary external tooling to build
|
|
34
|
+
against does not get the same latitude.
|
|
35
|
+
- **Two tests, not one**, because they prove different things:
|
|
36
|
+
- **Freshness** (`test/build/json-schema.test.ts`): regenerates the
|
|
37
|
+
schema in-memory and compares it byte-for-byte against the committed
|
|
38
|
+
file, failing if they differ. This proves the committed file matches
|
|
39
|
+
what the generator _currently_ produces -- the same "generated but
|
|
40
|
+
committed, diffable" discipline the example projects already use for
|
|
41
|
+
their own generated manifests/docs.
|
|
42
|
+
- **Correctness**: using `ajv` (a devDependency) against real `--json`
|
|
43
|
+
output from actually running the built CLI (a success case, a failure
|
|
44
|
+
case, and a `--check` run producing a `checkResult`-bearing payload),
|
|
45
|
+
asserting each validates cleanly against the committed schema.
|
|
46
|
+
Freshness alone only proves "the schema matches what the generator
|
|
47
|
+
currently produces" -- it says nothing about whether the schema is
|
|
48
|
+
_correct_ against real, running output, which is the property external
|
|
49
|
+
tooling actually depends on. A generator bug that produces a
|
|
50
|
+
self-consistent but wrong schema would pass the freshness test and fail
|
|
51
|
+
this one.
|
|
52
|
+
- **Ships in the published npm tarball, with its own subpath export.**
|
|
53
|
+
`schemas/` is added to `package.json`'s `files` array, and
|
|
54
|
+
`@maverickcer/env-cap/schema` maps directly to the JSON file -- the same
|
|
55
|
+
pattern already used for `"./package.json": "./package.json"` -- so a
|
|
56
|
+
consumer can resolve it via Node's own module resolution rather than
|
|
57
|
+
reconstructing a path into `node_modules`.
|
|
58
|
+
- **Evolves under the same additive-only rules as `--json` itself.** A new
|
|
59
|
+
optional field appearing in the schema is never a breaking change; a
|
|
60
|
+
changed or removed field is, exactly mirroring ADR 0013's policy for the
|
|
61
|
+
envelope the schema describes. `VERSIONING.md`'s Stable tier gains an
|
|
62
|
+
explicit line for this.
|
|
63
|
+
|
|
64
|
+
## Consequences
|
|
65
|
+
|
|
66
|
+
- `npm run schema` regenerates the file — a developer runs it locally after
|
|
67
|
+
changing `src/cli/json.ts`'s types and commits the result, the same as any
|
|
68
|
+
other generated-and-committed artifact this project produces. No CI step
|
|
69
|
+
re-runs the script itself; a stale commit is still caught, via the
|
|
70
|
+
freshness test (`test/build/json-schema.test.ts`), which regenerates the
|
|
71
|
+
schema in-memory during the normal test run and byte-compares it against
|
|
72
|
+
the committed file — the same way a stale generated manifest would fail in
|
|
73
|
+
any project using this tool on itself.
|
|
74
|
+
- External tooling gets exactly one artifact to point at
|
|
75
|
+
(`@maverickcer/env-cap/schema` or `schemas/env-cap-report.schema.json` in
|
|
76
|
+
the repo) instead of reverse-engineering the README's prose example.
|
|
77
|
+
- `ts-json-schema-generator` and `ajv` are devDependencies only -- neither
|
|
78
|
+
ships in the published package or is required at runtime by anything
|
|
79
|
+
except the schema-generation/test scripts themselves.
|
|
80
|
+
|
|
81
|
+
## Alternatives considered
|
|
82
|
+
|
|
83
|
+
- **Hand-author the schema once and keep it in sync manually.** Rejected --
|
|
84
|
+
this is precisely the failure mode a generated schema exists to prevent;
|
|
85
|
+
a manually-maintained schema silently drifting from the real envelope
|
|
86
|
+
would be worse than not publishing one at all, since it would carry false
|
|
87
|
+
authority.
|
|
88
|
+
- **Freshness test only, skip the correctness test.** Rejected -- freshness
|
|
89
|
+
alone can't catch a generator bug that produces a schema internally
|
|
90
|
+
consistent with itself but wrong against what the CLI actually emits
|
|
91
|
+
(e.g. a misconfigured `expose`/`jsDoc` option silently dropping a real
|
|
92
|
+
field). Running the real, built CLI and validating its actual output is
|
|
93
|
+
the only way to catch that class of bug.
|
|
94
|
+
- **`typescript-json-schema` instead of `ts-json-schema-generator`.**
|
|
95
|
+
Both are actively maintained and comparably popular; `ts-json-schema-generator`
|
|
96
|
+
was chosen as the plan's leading candidate and confirmed still actively
|
|
97
|
+
maintained (multiple releases within the last month) at implementation
|
|
98
|
+
time. Either would satisfy this decision's actual requirement (generated,
|
|
99
|
+
not hand-authored); this is a tooling choice, not a load-bearing part of
|
|
100
|
+
the decision itself.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# 0020: Declaration maps are emitted by a separate `tsc` pass, not tsup's own `dts` pipeline
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented in `tsconfig.build.json`, `scripts/emit-dts-shims.mjs`,
|
|
6
|
+
and `package.json`'s `build` script (`tsup && tsc -p tsconfig.build.json &&
|
|
7
|
+
node scripts/emit-dts-shims.mjs`).
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
Sourcemaps (`sourcemap: true`) were straightforward to enable across all
|
|
12
|
+
five `tsup.config.ts` targets. Declaration maps (`.d.ts.map`, letting an
|
|
13
|
+
editor's "Go to Definition" on an imported type land in real `.ts` source
|
|
14
|
+
instead of the bundled `.d.ts`) were expected to be equally simple: tsup's
|
|
15
|
+
`dts` option accepts a `compilerOptions` object, and passing
|
|
16
|
+
`{ declarationMap: true }` there looked like the natural way to enable them.
|
|
17
|
+
|
|
18
|
+
It doesn't work. Reading the installed `tsup@8.5.1`'s bundled dts pipeline
|
|
19
|
+
(`rollup-plugin-dts`, used whenever `dts: true` or `dts: {...}` is set)
|
|
20
|
+
showed two things: first, `dts.compilerOptions` is only honored by tsup's
|
|
21
|
+
separate, opt-in `experimentalDts` pipeline -- not the default one this
|
|
22
|
+
project uses. Second, and more fundamentally, `rollup-plugin-dts`'s own
|
|
23
|
+
`DEFAULT_OPTIONS` hardcodes `declarationMap: false` internally, so even
|
|
24
|
+
routing the option correctly wouldn't have produced a working map: the
|
|
25
|
+
bundling step that merges multiple source files' declarations into one
|
|
26
|
+
`dist/index.d.ts` per entry point has no path to emit a coherent merged map
|
|
27
|
+
at all. Building it and inspecting `dist/index.d.ts.map` confirmed this
|
|
28
|
+
directly -- no file was produced.
|
|
29
|
+
|
|
30
|
+
## Decision
|
|
31
|
+
|
|
32
|
+
Declaration files and their maps are emitted by a genuinely separate `tsc`
|
|
33
|
+
invocation, not tsup at all:
|
|
34
|
+
|
|
35
|
+
1. All five `tsup.config.ts` targets set `dts: false`. tsup only produces
|
|
36
|
+
the bundled `.js`/`.cjs` output (plus sourcemaps) for each entry point.
|
|
37
|
+
2. A new `tsconfig.build.json` (extending the project's own `tsconfig.json`)
|
|
38
|
+
runs `tsc --declaration --declarationMap --emitDeclarationOnly` against
|
|
39
|
+
`src/` (excluding `test/` and `src/cli/**`, which ships no public types),
|
|
40
|
+
emitting one real per-file `.d.ts`/`.d.ts.map` pair per source file into
|
|
41
|
+
`dist/.dts/`, mirroring `src/`'s own directory structure. Plain `tsc`
|
|
42
|
+
reliably produces correct per-file maps -- it's specifically
|
|
43
|
+
`rollup-plugin-dts`'s _bundling_ step that can't, not TypeScript's
|
|
44
|
+
declaration emit itself.
|
|
45
|
+
3. Since `tsc` (unlike `rollup-plugin-dts`) has no bundling step, and
|
|
46
|
+
`package.json#exports` pins each entry point to a single filename (e.g.
|
|
47
|
+
`dist/index.d.ts`), a new `scripts/emit-dts-shims.mjs` writes a one-line
|
|
48
|
+
re-export shim for each public entry point's `.d.ts`/`.d.cts`
|
|
49
|
+
(`export * from "./.dts/<target>/index.js";`), pointing package.json's
|
|
50
|
+
declared type location at the real per-file declarations underneath.
|
|
51
|
+
4. `package.json`'s `build` script becomes `tsup && tsc -p
|
|
52
|
+
tsconfig.build.json && node scripts/emit-dts-shims.mjs` -- three steps,
|
|
53
|
+
run in that order, every time.
|
|
54
|
+
|
|
55
|
+
Verified end-to-end, not just at the file-existence level: an installed
|
|
56
|
+
tarball (`npm pack`, installed into a scratch project) resolves a real,
|
|
57
|
+
non-`any` type through the shim -- a deliberately wrong `Processor`
|
|
58
|
+
signature in a scratch consumer produced a genuine `tsc` type error against
|
|
59
|
+
the shipped declarations, proving the shim isn't silently degrading to
|
|
60
|
+
`any`.
|
|
61
|
+
|
|
62
|
+
## Consequences
|
|
63
|
+
|
|
64
|
+
- The build has three sequential steps instead of one. A contributor
|
|
65
|
+
changing `tsup.config.ts`'s `dts`/`sourcemap` settings needs to
|
|
66
|
+
understand why `dts: false` appears on every target and where the real
|
|
67
|
+
declarations actually come from -- this ADR, plus the inline comments on
|
|
68
|
+
`tsup.config.ts`'s `dts: false` lines and at the top of
|
|
69
|
+
`scripts/emit-dts-shims.mjs`, are that record.
|
|
70
|
+
- `dist/.dts/` ships inside the published npm tarball (`files` includes the
|
|
71
|
+
whole `dist` directory) -- it's not optional scaffolding, the four shim
|
|
72
|
+
files depend on it existing at the paths they reference.
|
|
73
|
+
- If `src/eslint-plugin/` (or any future `dts`-bearing entry point) is
|
|
74
|
+
added, both `scripts/emit-dts-shims.mjs`'s `ENTRIES` list and
|
|
75
|
+
`tsconfig.build.json`'s `include`/`exclude` need the new entry point
|
|
76
|
+
accounted for -- `tsconfig.build.json`'s `include: ["src"]` already covers
|
|
77
|
+
a new directory under `src/` by default; only an entry point that should
|
|
78
|
+
be _excluded_ (like `src/cli/`, which ships no declarations at all) needs
|
|
79
|
+
an explicit exclude added.
|
|
80
|
+
- If a future `tsup`/`rollup-plugin-dts` release adds real declaration-map
|
|
81
|
+
support to the bundling pipeline, this three-step build can collapse back
|
|
82
|
+
to tsup's native `dts: true` -- nothing about this decision assumes the
|
|
83
|
+
gap is permanent, only that it exists today.
|
|
84
|
+
|
|
85
|
+
## Alternatives considered
|
|
86
|
+
|
|
87
|
+
- **`dts: { compilerOptions: { declarationMap: true } }` as originally
|
|
88
|
+
planned.** Rejected after verification -- doesn't work, for the two
|
|
89
|
+
reasons in Context above (wrong pipeline, and that pipeline's own
|
|
90
|
+
hardcoded default even if it were reached).
|
|
91
|
+
- **tsup's `experimentalDts` option**, which does read `compilerOptions`.
|
|
92
|
+
Not pursued -- it's explicitly experimental in tsup itself, uses a
|
|
93
|
+
different (per-file, not bundled) output shape that would itself require
|
|
94
|
+
the same shim-file treatment to fit `package.json#exports`' one-file-per-
|
|
95
|
+
entry-point pins, and swapping one experimental dependency behavior for
|
|
96
|
+
another doesn't remove the actual complexity, just relocates it.
|
|
97
|
+
- **Give up on declaration maps entirely.** Rejected -- "Go to Definition"
|
|
98
|
+
landing in real source instead of a bundled `.d.ts` is a real editor-
|
|
99
|
+
experience improvement or long-time maintainers and external contributors
|
|
100
|
+
alike, and the separate-`tsc`-pass approach achieves it without giving up
|
|
101
|
+
tsup's bundling for the actual JS output.
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# 0021: The manifest change report is a persisted, committed JSON sidecar snapshot
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented in `src/build/manifest-snapshot.ts`, wired into
|
|
6
|
+
`src/build/generate-manifest.ts` (`generateEnvManifest()`) and
|
|
7
|
+
`src/build/generate-env-artifacts.ts` (`generateEnvArtifacts()`). The
|
|
8
|
+
duplicate-documentation warning it depends on is implemented in
|
|
9
|
+
`src/build/compatibility.ts` (`detectCompatibilityIssues()`).
|
|
10
|
+
|
|
11
|
+
## Context
|
|
12
|
+
|
|
13
|
+
`generateEnvManifest()` has never had any memory of a previous run. `docs.ts`
|
|
14
|
+
already solves an adjacent problem for the Markdown docs artifact -- it
|
|
15
|
+
re-reads its own previously-written file before overwriting it, and diffs the
|
|
16
|
+
``### `KEY` `` headings it finds against the current run to report an
|
|
17
|
+
added/removed/commented key summary (`computeChangeSummary()`,
|
|
18
|
+
`renderHeader()`). The manifest has nothing equivalent to read back: its `.ts` output is deliberately metadata-free by design -- sorted imports plus a `contracts` array, "no timestamps, no randomness" per `manifest.ts`'s own
|
|
19
|
+
docstring. There is no `description`/`owner`/`expiresAt`/etc. in it at all,
|
|
20
|
+
so there is nothing in a previously-generated `manifest.ts` for a later run
|
|
21
|
+
to parse back out.
|
|
22
|
+
|
|
23
|
+
The ask was to teach `generateEnvManifest()` to report `documentEnv()`
|
|
24
|
+
metadata that was added, removed, or changed since the last run, and to
|
|
25
|
+
specifically call out two related but distinct situations: (a) two _active_
|
|
26
|
+
contracts declaring the same variable with divergent documented metadata
|
|
27
|
+
right now, in the same run, and (b) a single variable's documented metadata
|
|
28
|
+
having drifted since the last time this ran. These need different mechanisms.
|
|
29
|
+
(a) is a same-run comparison with no history involved -- it's the same shape
|
|
30
|
+
of problem `detectCompatibilityIssues()` already solves for processor/
|
|
31
|
+
validator source (0005), just applied to documentation fields instead of
|
|
32
|
+
code. (b) genuinely needs persisted state across runs, which nothing in this
|
|
33
|
+
codebase had before this change.
|
|
34
|
+
|
|
35
|
+
## Decision
|
|
36
|
+
|
|
37
|
+
**A new sidecar file, not a change to `manifest.ts` itself.** Every
|
|
38
|
+
`generateEnvManifest()` (and, via `generate-env-artifacts.ts`, every
|
|
39
|
+
`generateEnvArtifacts()` call with a `manifest` pass) writes
|
|
40
|
+
`<manifest-location>.snapshot.json` alongside the manifest -- e.g.
|
|
41
|
+
`src/generated/env.manifest.ts` gets a sibling
|
|
42
|
+
`src/generated/env.manifest.snapshot.json`. It's a deterministic JSON
|
|
43
|
+
projection of exactly the documented-metadata fields already on
|
|
44
|
+
`DiscoveredContract`/`DiscoveredVariable` (contract-level `contractName`/
|
|
45
|
+
`active`/`category`/`exclusiveGroup`/`owner`/`expiresAt`/`metadata`,
|
|
46
|
+
variable-level `description`/`owner`/`expiresAt`/`refreshInstructions`/
|
|
47
|
+
`required`/`extra`/`documented`), sorted by file/exportName/key so
|
|
48
|
+
`JSON.stringify` output is stable and diffs cleanly. Nothing schema- or
|
|
49
|
+
processor-shaped is in it -- that distinction is exactly why `manifest.ts`
|
|
50
|
+
itself couldn't be reused for this.
|
|
51
|
+
|
|
52
|
+
**Committed, not ephemeral.** The snapshot is meant to be committed to git
|
|
53
|
+
right next to the manifest it describes, the same way the manifest itself
|
|
54
|
+
already is. "Since last execution" means "since the last commit on this
|
|
55
|
+
branch" -- reviewable in a PR diff, and consistent in CI (a fresh checkout
|
|
56
|
+
sees exactly what the last commit left behind) in a way a gitignored,
|
|
57
|
+
per-machine cache directory could never be. A local-cache design was
|
|
58
|
+
considered and rejected specifically because CI's "since last execution"
|
|
59
|
+
would otherwise mean nothing at all on a fresh checkout.
|
|
60
|
+
|
|
61
|
+
**Scoped to active contracts only**, matching `renderManifest()`'s own scope.
|
|
62
|
+
A contract flipping from `active: true` to `active: false` disappears from
|
|
63
|
+
`manifest.ts` itself; it disappears from this snapshot for the same reason,
|
|
64
|
+
and shows up as `removedContracts`/`removedVariables` in the next diff.
|
|
65
|
+
|
|
66
|
+
**`schemaVersion`, with the same bump discipline `src/cli/json.ts`'s
|
|
67
|
+
`JSON_SCHEMA_VERSION` already documents** (ADR 0019's sibling policy, not a
|
|
68
|
+
new one): bump only when a reader could misinterpret the new shape, never for
|
|
69
|
+
an ordinary additive field. Reading a snapshot distinguishes four cases, not
|
|
70
|
+
two -- `"missing"` (no snapshot yet: the normal, silent first-run state),
|
|
71
|
+
`"invalid-json"` (unparseable), `"unsupported-version"` (parses fine, but a
|
|
72
|
+
`schemaVersion` this build doesn't recognize), and `"ok"`. The first is
|
|
73
|
+
silent; the middle two are **surfaced as a `ParseWarning`**, reusing the
|
|
74
|
+
existing warning channel every generator result already carries (rather than
|
|
75
|
+
inventing a new field), specifically so a corrupted or foreign-version
|
|
76
|
+
snapshot never masquerades as "nothing has ever been documented before" --
|
|
77
|
+
that would otherwise render as a confusing wall of "everything just got
|
|
78
|
+
added" with no visible explanation for why history was lost.
|
|
79
|
+
|
|
80
|
+
**Field-level diffs, not just field-name lists.** `ManifestChangeReport`'s
|
|
81
|
+
`updatedContracts`/`updatedVariables` entries carry
|
|
82
|
+
`{ field, previous, current }` per differing field (including
|
|
83
|
+
`metadata.<key>`/`extra.<key>` for record fields), not merely the names of
|
|
84
|
+
what changed. The values are already known at diff time; making a CLI
|
|
85
|
+
formatter, a JSON consumer, or a future GitHub Action annotation re-derive
|
|
86
|
+
them from somewhere else would be pure friction for no benefit.
|
|
87
|
+
|
|
88
|
+
**Duplicate-key documentation divergence is a `CompatibilityIssue`
|
|
89
|
+
extension, not a new mechanism.** Two _active_ contracts documenting the same
|
|
90
|
+
variable key with different `description`/`owner`/`expiresAt`/
|
|
91
|
+
`refreshInstructions`/`required`/`extra` is a same-run, no-history comparison
|
|
92
|
+
-- `detectCompatibilityIssues()` already runs this exact kind of pairwise
|
|
93
|
+
per-key comparison for processor/validator source (0005), so this is a third
|
|
94
|
+
comparison added to that same loop, not a parallel system. It is always
|
|
95
|
+
`severity: "warning"`, never `"error"` (see "Alternatives considered" for why
|
|
96
|
+
this isn't treated like ADR 0009's exclusive-group violations), and
|
|
97
|
+
participates in the existing `onIncompatibility` warn/throw gate unchanged.
|
|
98
|
+
It's also the first check to set the new, optional `CompatibilityIssue.code`
|
|
99
|
+
field (`"duplicate-variable-documentation"`) -- a stable, machine-readable
|
|
100
|
+
identifier deliberately added to the type as opt-in rather than backfilled
|
|
101
|
+
onto the three checks that predate it, so CI filtering, doc-linking, or an
|
|
102
|
+
IDE integration has something to key on without this change also being a
|
|
103
|
+
silent behavior change for every existing warning.
|
|
104
|
+
|
|
105
|
+
**`--check` is untouched.** `computeArtifacts()` (shared by the write path
|
|
106
|
+
and by `checkEnvArtifacts()`, ADR 0011) computes the snapshot diff as a
|
|
107
|
+
read-only step -- it was already doing read-only discovery/linking work
|
|
108
|
+
`checkEnvArtifacts()` needed anyway, so the diff comes along for free. But
|
|
109
|
+
`checkEnvArtifacts()` itself never surfaces it and never writes the new
|
|
110
|
+
snapshot file: ADR 0016's "nothing is ever written at all" guarantee for
|
|
111
|
+
`--check` stays exactly as absolute as it already was, and
|
|
112
|
+
`CheckEnvArtifactsResult`'s shape gains no new field from this change.
|
|
113
|
+
|
|
114
|
+
**Only `ManifestChangeReport` (and the small ref/update/field-change types
|
|
115
|
+
its entries are built from) are exported from `src/build/index.ts`.** The
|
|
116
|
+
snapshot build/read/write/diff functions in `manifest-snapshot.ts`, and the
|
|
117
|
+
on-disk `ManifestSnapshot`/`ManifestSnapshotContract`/`ManifestSnapshotVariable`
|
|
118
|
+
shapes, all stay internal. This mirrors ADR 0010's precedent for the
|
|
119
|
+
dependency-ownership engine: a primitive earns Experimental-public status
|
|
120
|
+
through a real external caller pushing on it, not by default just because it
|
|
121
|
+
was convenient to write as an exported function.
|
|
122
|
+
|
|
123
|
+
## Consequences
|
|
124
|
+
|
|
125
|
+
- A PR that changes `documentEnv()` metadata now shows that change twice: once
|
|
126
|
+
as prose in the regenerated docs artifact (if a docs pass is requested),
|
|
127
|
+
and once as a structured, field-level diff in the committed snapshot JSON
|
|
128
|
+
-- a reviewer can see exactly which fields moved without reading the whole
|
|
129
|
+
generated Markdown file.
|
|
130
|
+
- The very first `generateEnvManifest()` run against any given `location`
|
|
131
|
+
(or the first run after cloning a repo that hasn't committed a snapshot
|
|
132
|
+
yet) reports every discovered variable as `added*`. This is expected, not
|
|
133
|
+
a bug -- the same "first run has no `previousContent`" shape `docs.ts`'s
|
|
134
|
+
own change summary has always had.
|
|
135
|
+
- One more generated-and-committed file to review per manifest, alongside
|
|
136
|
+
`manifest.ts` itself. This is mitigated by it being fully automatic (every
|
|
137
|
+
`generate:env`/CI run regenerates it, there is no separate manual step --
|
|
138
|
+
see the snapshot's own explanatory section in the package README) and by
|
|
139
|
+
the field-level diff making the review itself fast rather than requiring a
|
|
140
|
+
reader to reconstruct what changed from two full JSON blobs.
|
|
141
|
+
- A hand-edited or foreign-tool-written snapshot degrades gracefully to a
|
|
142
|
+
visible warning plus a fresh-start diff, never a crash and never a silent,
|
|
143
|
+
unexplained loss of history.
|
|
144
|
+
|
|
145
|
+
## Alternatives considered
|
|
146
|
+
|
|
147
|
+
- **Embed the metadata directly into `manifest.ts`.** Rejected. That file's
|
|
148
|
+
entire contract, documented in its own file header, is "no timestamps, no
|
|
149
|
+
randomness -- same input files always produce byte-identical output" and
|
|
150
|
+
nothing beyond imports plus a `contracts` array. Adding diffable metadata
|
|
151
|
+
there would mean either breaking that contract or parsing TypeScript
|
|
152
|
+
(rather than JSON) back out on the next run to recover prior state, for no
|
|
153
|
+
benefit over a dedicated, purpose-built sidecar.
|
|
154
|
+
- **An ephemeral, gitignored cache instead of a committed file.** Rejected --
|
|
155
|
+
"since last execution" would mean "since last time this exact machine ran
|
|
156
|
+
it," which is meaningless in CI (a fresh checkout every run has no local
|
|
157
|
+
history) and gives a PR reviewer nothing to look at. The whole value of the
|
|
158
|
+
feature is the structured diff being visible in review, the same way the
|
|
159
|
+
manifest and docs artifacts already are.
|
|
160
|
+
- **Reuse `docs.ts`'s existing `previousContent` mechanism (read back the
|
|
161
|
+
Markdown docs file) instead of a dedicated snapshot.** Rejected --
|
|
162
|
+
`generateEnvManifest()` is fully usable standalone, with no docs pass ever
|
|
163
|
+
requested. Making the manifest's own change-tracking depend on whether a
|
|
164
|
+
docs artifact happens to exist elsewhere would make the feature's
|
|
165
|
+
availability accidental rather than a property of `generateEnvManifest()`
|
|
166
|
+
itself.
|
|
167
|
+
- **Escalate duplicate-variable-documentation divergence to `severity:
|
|
168
|
+
"error"`, unconditionally, the way ADR 0009 treats exclusive-group
|
|
169
|
+
violations.** Rejected. ADR 0009's reasoning is that `exclusiveGroup` is an
|
|
170
|
+
explicit, author-declared constraint with no legitimate "maybe" reading --
|
|
171
|
+
two contracts either share the string or they don't. Two contracts
|
|
172
|
+
documenting the same variable name differently has no such property: it is
|
|
173
|
+
never provably wrong via static analysis, exactly like the pre-existing
|
|
174
|
+
differently-shaped-processor-source and differently-shaped-validator-source
|
|
175
|
+
checks it sits alongside. Warning-tier, gated by the existing
|
|
176
|
+
`onIncompatibility` option, is the correct precedent to follow here, not
|
|
177
|
+
the exclusive-group one.
|
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
# 0022: Generic validation contexts
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted.
|
|
6
|
+
|
|
7
|
+
## Context
|
|
8
|
+
|
|
9
|
+
ADR 0004 rejected a `runtime: "server"|"client"` option on `createEnv()`,
|
|
10
|
+
and rejected separate `/client`/`/server` packages, because a variable's
|
|
11
|
+
classification as server-only or client-safe doesn't change how it's
|
|
12
|
+
processed or validated -- and because the real boundary that keeps
|
|
13
|
+
server-only source out of a browser bundle is the application's module
|
|
14
|
+
graph (separate discovery -> separate generated manifests), not something
|
|
15
|
+
a runtime flag could enforce anyway.
|
|
16
|
+
|
|
17
|
+
That decision holds. But real usage since then has surfaced a narrower,
|
|
18
|
+
legitimate need it didn't address: a single validation run sometimes needs
|
|
19
|
+
to activate or deactivate variables by some caller-defined facet --
|
|
20
|
+
"which deployment target," "which environment tier," "which entry point"
|
|
21
|
+
-- without necessarily forking into multiple manifests for it. Examples:
|
|
22
|
+
|
|
23
|
+
- One manifest shared by a Node server and its browser bundle, where each
|
|
24
|
+
process should only validate (and be able to read) the variables that
|
|
25
|
+
apply to it.
|
|
26
|
+
- A single manifest validated with different `activeContexts` in
|
|
27
|
+
development vs. production, to require a variable only where it
|
|
28
|
+
actually matters.
|
|
29
|
+
- A backend that also runs a worker/edge entry point from the same
|
|
30
|
+
codebase, where a handful of variables are entry-point-specific.
|
|
31
|
+
|
|
32
|
+
This ADR adds **validation contexts** to close that gap, while explicitly
|
|
33
|
+
not reopening what ADR 0004 already settled.
|
|
34
|
+
|
|
35
|
+
## Decision
|
|
36
|
+
|
|
37
|
+
A schema entry may declare a validation context:
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
DATABASE_URL: {
|
|
41
|
+
context: "server",
|
|
42
|
+
validator: validators.required(),
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
`validateEnv()` accepts the validation contexts active for this run:
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
await validateEnv({
|
|
50
|
+
manifest,
|
|
51
|
+
values: process.env,
|
|
52
|
+
activeContexts: ["server", "production"],
|
|
53
|
+
})
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**Matching rule:** a variable without a `context` participates in every
|
|
57
|
+
run. A variable with a `context` participates only when `activeContexts`
|
|
58
|
+
contains that exact string. Omitted `activeContexts` behaves as empty --
|
|
59
|
+
this isn't a special case, it's the general rule applied uniformly (an
|
|
60
|
+
empty set contains no string, so only context-less variables match),
|
|
61
|
+
which is exactly why every existing schema (none of which set `context`)
|
|
62
|
+
behaves identically before and after this feature exists.
|
|
63
|
+
|
|
64
|
+
**Skip means skip the entire pipeline.** A variable that doesn't match
|
|
65
|
+
never runs its `default`/`processor`/`validator`, is never counted as
|
|
66
|
+
validated, and is never written into the validated result -- it stays in
|
|
67
|
+
its not-ready state exactly as if this run had never happened for it.
|
|
68
|
+
Reading it throws `EnvNotReadyError`, the same error (and the same code
|
|
69
|
+
path) as reading any variable before `validateEnv()` has run. Getting this
|
|
70
|
+
right required a small, real bug fix alongside the new field: contract
|
|
71
|
+
readiness was tracked per _contract_, not per _variable_ (`create.ts`'s
|
|
72
|
+
getter only checked whether the whole contract had been validated, then
|
|
73
|
+
read the key from its cached values unconditionally). A context-skipped
|
|
74
|
+
variable is simply absent as an own property of that cached object, so the
|
|
75
|
+
getter now checks key presence, not just contract presence.
|
|
76
|
+
|
|
77
|
+
### Why `context` is first-class schema vocabulary, not documentation metadata
|
|
78
|
+
|
|
79
|
+
`EnvDefinition` is deliberately minimal (`default`/`processor`/`validator`
|
|
80
|
+
-- see ADR 0001, ADR 0007), and everything that doesn't change runtime
|
|
81
|
+
behavior lives in `documentEnv()` instead. `context` belongs with the
|
|
82
|
+
former, not the latter, for the same reason `default`/`processor`/
|
|
83
|
+
`validator` do: `validate.ts` reads it directly to decide whether the rest
|
|
84
|
+
of the pipeline runs at all. That build tooling can _also_ read it for
|
|
85
|
+
generated docs is incidental -- true of `hasDefault`/`hasProcessor`/
|
|
86
|
+
`hasValidator` today too -- not the justification.
|
|
87
|
+
|
|
88
|
+
### Why declarative metadata, not a callback
|
|
89
|
+
|
|
90
|
+
An alternative shape would let a variable decide participation itself,
|
|
91
|
+
e.g. `shouldInclude: (activeContexts) => boolean`. Rejected: ADR 0002
|
|
92
|
+
requires schemas to be statically analyzable without executing them: a
|
|
93
|
+
callback can't be evaluated by the AST parser, so build tooling could
|
|
94
|
+
never surface which context a variable belongs to in generated docs or
|
|
95
|
+
`.env.example` -- exactly the kind of unanalyzable schema entry ADR 0002
|
|
96
|
+
already treats as a parse-time warning, not a supported pattern.
|
|
97
|
+
|
|
98
|
+
### Why a single string, not an array, on the variable side
|
|
99
|
+
|
|
100
|
+
`context?: string`, not `context?: string[]`. A variable belongs to at
|
|
101
|
+
most one validation context. An array would require defining AND/OR
|
|
102
|
+
semantics for a variable that lists more than one -- and either answer
|
|
103
|
+
adds a second axis of complexity for a feature whose whole value is being
|
|
104
|
+
simple enough to reason about at a glance. If a real case ever needs one
|
|
105
|
+
variable to participate in more than one context, that should be solved
|
|
106
|
+
by an explicit new mechanism (a second field, or splitting into two
|
|
107
|
+
schema entries) -- never by loosening this field to `string | string[]`,
|
|
108
|
+
which would silently reintroduce the exact ambiguity this decision avoids.
|
|
109
|
+
|
|
110
|
+
### Why `activeContexts` is a plural array on `validateEnv()`
|
|
111
|
+
|
|
112
|
+
Unlike a variable, one validation run can have several simultaneously-true
|
|
113
|
+
facets -- `["server", "production"]` is both "which deployment target" and
|
|
114
|
+
"which environment tier" at once. The option is named `activeContexts`,
|
|
115
|
+
not `contexts`, specifically because "contexts" alone is ambiguous between
|
|
116
|
+
"declared" and "currently active"; the option is unambiguously the latter.
|
|
117
|
+
|
|
118
|
+
### Why omitted-context variables always participate
|
|
119
|
+
|
|
120
|
+
This is what makes the feature backward compatible without a migration or
|
|
121
|
+
an opt-in flag: every schema written before this feature exists has no
|
|
122
|
+
`context` fields, so under the matching rule above, every variable in it
|
|
123
|
+
keeps matching via the `context === undefined` branch regardless of what
|
|
124
|
+
(or whether) `activeContexts` is passed. No existing caller needs to
|
|
125
|
+
change anything.
|
|
126
|
+
|
|
127
|
+
## Formal invariants
|
|
128
|
+
|
|
129
|
+
These are the contract this feature makes, written down so future changes
|
|
130
|
+
don't erode it without a new ADR. (Also stated in
|
|
131
|
+
[`specs/architecture.md`](../architecture.md#validation-context-invariants),
|
|
132
|
+
which is the canonical copy -- repeated here for the record.)
|
|
133
|
+
|
|
134
|
+
1. **Matching** is exact-string only: no prefix matching, wildcards,
|
|
135
|
+
hierarchy, or inheritance.
|
|
136
|
+
2. **Not runtime detection.** env-cap never infers `activeContexts` from
|
|
137
|
+
any ambient signal. The application always computes and passes it.
|
|
138
|
+
3. **Not cache identity.** `validateEnv()` stays one-shot per process;
|
|
139
|
+
`activeContexts` isn't part of what makes a second call a no-op, and
|
|
140
|
+
there is no per-context cache dimension.
|
|
141
|
+
4. **Not a type-level concept.** `context` never alters `EnvContract`'s
|
|
142
|
+
TypeScript shape or any inferred type. Every schema key remains a
|
|
143
|
+
property of `EnvContract<S>` regardless of context; an out-of-context
|
|
144
|
+
read is a runtime throw, not a compile-time error.
|
|
145
|
+
5. **Not authorization.** A validation context is not an authentication,
|
|
146
|
+
authorization, or access-control mechanism -- it does not restrict
|
|
147
|
+
_who_ can read a value, only whether a given `validateEnv()` run
|
|
148
|
+
processes it at all.
|
|
149
|
+
6. **Not a bundling/security boundary.** Separate discovery/manifests (ADR 0004) remain the actual mechanism for keeping server-only source out of
|
|
150
|
+
client-bound code. `activeContexts` filtering happens after the schema
|
|
151
|
+
-- including any literal `default` value -- is already wherever it's
|
|
152
|
+
going to be. Putting both `context: "server"` and `context: "client"`
|
|
153
|
+
variables in one schema feeding one manifest that a client bundle
|
|
154
|
+
imports does not stop the server-context variable's definition from
|
|
155
|
+
shipping to the browser.
|
|
156
|
+
|
|
157
|
+
## Consequences
|
|
158
|
+
|
|
159
|
+
- **Generated docs and `.env.example` surface `context`**, extracted the
|
|
160
|
+
same statically-analyzed way as `hasDefault`/`hasProcessor`/
|
|
161
|
+
`hasValidator` (never executed -- a non-literal `context` warns and is
|
|
162
|
+
ignored, same as every other unanalyzable field). Rendered as
|
|
163
|
+
"Validation context," not the bare "Context," and paired with the
|
|
164
|
+
non-boundary/non-authorization caveat wherever it's shown, so a
|
|
165
|
+
generated artifact never reads as more of a guarantee than it is.
|
|
166
|
+
- **The generated manifest file also exports `activeContexts`** -- every
|
|
167
|
+
validation context declared by any variable in an _active_ contract
|
|
168
|
+
(`discoverValidationContexts()`, `src/build/manifest.ts`), sorted and
|
|
169
|
+
deduplicated, named to match `validateEnvOptions.activeContexts` itself
|
|
170
|
+
so application code can pass it straight through:
|
|
171
|
+
`validateEnv({ manifest, values, activeContexts })`. It's every context
|
|
172
|
+
the manifest has, meant as a starting point to narrow per process --
|
|
173
|
+
importing it unmodified into every process defeats the point of scoping
|
|
174
|
+
contexts per deployment target in the first place (see the README's
|
|
175
|
+
"Validation contexts" section). Emitted only when at least one variable
|
|
176
|
+
actually declares a `context`, immediately after the imports (`// all
|
|
177
|
+
currently active validation contexts`), so a project that doesn't use
|
|
178
|
+
this feature gets byte-identical manifest output to before this ADR.
|
|
179
|
+
This was originally scoped as _not_ touching the manifest at all (an
|
|
180
|
+
earlier draft of this ADR said so); seeing the feature in real use made
|
|
181
|
+
clear that hand-typing the discovered context list at every
|
|
182
|
+
`validateEnv()` call site was the actual remaining friction, so this was
|
|
183
|
+
added as an explicit, later revision -- see "Alternatives considered"
|
|
184
|
+
for the scaffolded-`validateEnv()`-call approach that was tried first
|
|
185
|
+
and rejected.
|
|
186
|
+
- **A validation run's participation detail isn't exposed as data.**
|
|
187
|
+
`validateEnvResult` still reports only `contractCount`/`variableCount`
|
|
188
|
+
(a skipped variable isn't counted in the latter). Future diagnostics
|
|
189
|
+
could expose which variables were skipped and why (`{ skippedVariables,
|
|
190
|
+
activeContexts }`) without changing validation semantics -- not
|
|
191
|
+
implemented here, to keep this change purely additive and minimal; see
|
|
192
|
+
Alternatives.
|
|
193
|
+
- **Empty-string `context` is treated as absent, at the build layer.** A
|
|
194
|
+
literal `context: ""` almost certainly signals a mistake, not an
|
|
195
|
+
intentional empty context; the static analyzer warns and drops it
|
|
196
|
+
(same "warn, don't guess" policy as every other field). The runtime
|
|
197
|
+
itself does not add a check for this -- an empty string flowing through
|
|
198
|
+
at runtime just never matches anything in practice, which is harmless,
|
|
199
|
+
and adding runtime input-shape validation for a schema field has no
|
|
200
|
+
precedent elsewhere in this codebase (the runtime trusts
|
|
201
|
+
`default`/`processor`/`validator`'s shape too) and would cost bytes
|
|
202
|
+
against the ADR 0008 gzip budget for a case the build-time warning
|
|
203
|
+
already catches for anyone running the generator.
|
|
204
|
+
|
|
205
|
+
## Alternatives considered
|
|
206
|
+
|
|
207
|
+
- **`context: string[]` on the variable.** Rejected -- see "Why a single
|
|
208
|
+
string, not an array" above.
|
|
209
|
+
- **A built-in `"shared"` sentinel value.** Rejected -- redundant with
|
|
210
|
+
`context: undefined`, and it would imply env-cap has an opinion about
|
|
211
|
+
what "shared" means, which contradicts the whole premise of contexts
|
|
212
|
+
being entirely application-defined.
|
|
213
|
+
- **Hierarchical or wildcard contexts** (e.g. `"server.production"`
|
|
214
|
+
matching an active `"server"`). Rejected -- the point of this feature is
|
|
215
|
+
staying generic; a hierarchy would require env-cap to understand context
|
|
216
|
+
semantics it has no business understanding. See Formal Invariant 1.
|
|
217
|
+
- **A callback (`shouldInclude`/`when`) instead of a declarative field.**
|
|
218
|
+
Rejected -- breaks static analyzability (ADR 0002); see above.
|
|
219
|
+
- **Automatic context detection** (inspecting `window`, `NODE_ENV`, a
|
|
220
|
+
bundler `define`, etc.). Rejected for the same reasons ADR 0004 already
|
|
221
|
+
rejected automatic client/server detection: framework-dependent,
|
|
222
|
+
unreliable across deployment targets, and it would put detection logic
|
|
223
|
+
in the smallest, most security-sensitive part of the package. See
|
|
224
|
+
Formal Invariant 2.
|
|
225
|
+
- **Using `context` for access control** (e.g. `context: "admin"` implying
|
|
226
|
+
only "admin" code paths may read a variable). Rejected outright --
|
|
227
|
+
contexts govern validation participation, never access. See Formal
|
|
228
|
+
Invariant 5. Anyone with code access to a contract in an active context
|
|
229
|
+
can read it, same as any other variable.
|
|
230
|
+
- **A scaffolded `validateEnv()` call written directly into the generated
|
|
231
|
+
manifest file, preserved verbatim across regenerations.** Considered (and
|
|
232
|
+
briefly drafted) as the mechanism for surfacing discovered contexts to
|
|
233
|
+
application code: on first generation, write a trailing `await
|
|
234
|
+
validateEnv({ manifest, values: process.env, activeContexts: [...] })`
|
|
235
|
+
call the developer could hand-edit; on regeneration, parse the existing
|
|
236
|
+
file and leave everything below the imports untouched so those edits
|
|
237
|
+
survive. Rejected for two concrete reasons: (1) `renderManifest()` is a
|
|
238
|
+
pure function of `(contracts, outputFile)`, called both to write the
|
|
239
|
+
real file and, in `--check` mode (`check-artifacts.ts`), to compute
|
|
240
|
+
"what a fresh run would produce" for a byte-for-byte drift comparison --
|
|
241
|
+
a preserved region breaks that comparison without new machinery to know
|
|
242
|
+
which part is exempt. (2) The preserved/regenerated boundary was
|
|
243
|
+
ambiguous in a way that mattered: if `export const manifest = [...]`
|
|
244
|
+
itself fell on the preserved side, adding or removing an `env.schema.ts`
|
|
245
|
+
file would stop automatically updating the manifest array, breaking the
|
|
246
|
+
tool's core auto-discovery guarantee. The `activeContexts` export
|
|
247
|
+
actually shipped avoids both problems -- it's plain, always-fresh,
|
|
248
|
+
fully-regenerated data, exactly like `manifest` itself, with no
|
|
249
|
+
user-owned region to parse or preserve.
|
|
250
|
+
- **A `runtime: "server" | "client"` option on `createEnv()`.** This is
|
|
251
|
+
the alternative ADR 0004 already rejected, not a new one -- noted here
|
|
252
|
+
only to be explicit about the difference: that alternative was a closed
|
|
253
|
+
enum implying a bundling boundary the runtime can't actually enforce.
|
|
254
|
+
`context` is an open, user-supplied string that only gates validation
|
|
255
|
+
participation and makes no claim about bundling at all (see Formal
|
|
256
|
+
Invariant 6).
|
|
257
|
+
|
|
258
|
+
## Relationship to ADR 0004
|
|
259
|
+
|
|
260
|
+
ADR 0004's decision -- no `/client`/`/server` package split, separate
|
|
261
|
+
discovery/manifests as the real module boundary -- is unchanged by this
|
|
262
|
+
ADR and remains the mechanism for keeping server-only source out of
|
|
263
|
+
client-bound code. Validation contexts are a complementary, orthogonal
|
|
264
|
+
feature: useful _within_ a manifest that's already scoped to one
|
|
265
|
+
deployment target but has more than one simultaneously-relevant facet (an
|
|
266
|
+
environment tier, a secondary entry point), not a substitute for scoping
|
|
267
|
+
that manifest correctly in the first place.
|