@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,95 @@
|
|
|
1
|
+
# 0042: `env-cap init` is a filesystem-only scaffolder, never a project configurator
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented: `src/cli/init.ts` (`runInitCommand`), dispatched from
|
|
6
|
+
`src/cli/index.ts`'s `main()` on `init` as the first positional token;
|
|
7
|
+
covered by `test/cli/init.test.ts` and `test/cli/main.test.ts`.
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
The CLI (`src/cli/index.ts`) was a single flat flag-parser — `--location`,
|
|
12
|
+
`--docs`, `--check`, `--json`, etc. — with no subcommand concept. A new
|
|
13
|
+
adopter's first step ("write an `env.schema.ts`, then generate the
|
|
14
|
+
manifest") was entirely manual, described only in the README.
|
|
15
|
+
|
|
16
|
+
`repo-contract` added an `init` subcommand for the same reason (its ADR
|
|
17
|
+
0004, 2026-09-09 amendment). env-cap should offer the same low-friction
|
|
18
|
+
entry point, but env-cap's own invariants constrain what `init` may do:
|
|
19
|
+
static analysis only, never execution (ADR 0002); library surfaces do not
|
|
20
|
+
acquire ambient capabilities the caller didn't grant (ADR 0040).
|
|
21
|
+
|
|
22
|
+
## Decision
|
|
23
|
+
|
|
24
|
+
### Grammar
|
|
25
|
+
|
|
26
|
+
`init` as the **first positional token** routes to the scaffolder; every
|
|
27
|
+
existing flag-based invocation is untouched (no flag is reinterpreted as a
|
|
28
|
+
subcommand, `--help` alone still prints the generator help). `env-cap init`
|
|
29
|
+
takes no arguments except `--help`.
|
|
30
|
+
|
|
31
|
+
### `init` scaffolds, it does not configure
|
|
32
|
+
|
|
33
|
+
`init` writes exactly two new files:
|
|
34
|
+
|
|
35
|
+
- `<src>/env.schema.ts` — a starter capability contract (`createEnv` +
|
|
36
|
+
`documentEnv`, one placeholder variable). `src/` if that directory
|
|
37
|
+
already exists, project root otherwise.
|
|
38
|
+
- `scripts/generate-env.mjs` — a runnable artifact generator calling
|
|
39
|
+
`generateEnvArtifacts()` with the `@maverickcer/env-cap/node`
|
|
40
|
+
filesystem adapter.
|
|
41
|
+
|
|
42
|
+
It is **filesystem-only and non-executing**: no subprocess, no
|
|
43
|
+
package-manager call, no `package.json` mutation, no artifact
|
|
44
|
+
regeneration, no ambient-environment read, no network. It reads the
|
|
45
|
+
consumer's `package.json` only to confirm it's a project and to choose
|
|
46
|
+
`src/` vs. root. Writes use exclusive-create (`{ flag: "wx" }`) — an
|
|
47
|
+
existing file is reported as skipped, never overwritten — with parent
|
|
48
|
+
directories created first. Any preflight failure (no `package.json`,
|
|
49
|
+
malformed `package.json`, a scaffold target blocked by a wrong-typed
|
|
50
|
+
entry) means zero writes.
|
|
51
|
+
|
|
52
|
+
Unlike `repo-contract`'s `init`, env-cap's does **not** patch a
|
|
53
|
+
`package.json` script. `repo-contract`'s `npm run contract` has to exist
|
|
54
|
+
because its git hooks call it; env-cap's CLI already works standalone via
|
|
55
|
+
`npx env-cap`, so there is nothing to wire. Anything the documented
|
|
56
|
+
workflow still needs — running the generator, wiring `validateEnv()` into
|
|
57
|
+
startup — is printed as a `Next:` step, never performed.
|
|
58
|
+
|
|
59
|
+
### Tier
|
|
60
|
+
|
|
61
|
+
Experimental (VERSIONING.md). The scaffold's exact file set and template
|
|
62
|
+
contents may change in a minor/patch release; what it has already written
|
|
63
|
+
into a consumer's repo is theirs and unaffected.
|
|
64
|
+
|
|
65
|
+
## Consequences
|
|
66
|
+
|
|
67
|
+
- A new adopter runs `npx env-cap init`, gets a discoverable contract and a
|
|
68
|
+
generator, and expands from there — the README's manual walkthrough
|
|
69
|
+
becomes the "understand what init did" reference, not the required first
|
|
70
|
+
path.
|
|
71
|
+
- `src/cli/init.ts` uses `node:fs` directly. That's consistent with ADR
|
|
72
|
+
0040's carve-out (`src/cli/**` is executable-context source) and the
|
|
73
|
+
file is bundled into the `bin` target, so the `AmbientCapabilities` check's
|
|
74
|
+
tarball scan exempts it exactly as it does `src/cli/index.ts`.
|
|
75
|
+
- The scaffolded templates are plain string constants in `init.ts`. If the
|
|
76
|
+
public `createEnv`/`documentEnv`/`generateEnvArtifacts` API changes
|
|
77
|
+
shape, the templates need updating too — a test that actually type-checks
|
|
78
|
+
or runs the scaffolded output would catch drift, and is a reasonable
|
|
79
|
+
future addition.
|
|
80
|
+
|
|
81
|
+
## Alternatives considered
|
|
82
|
+
|
|
83
|
+
- **Patch `package.json` to add a `generate:env` script**, like
|
|
84
|
+
repo-contract. Rejected — env-cap's CLI is directly runnable via `npx`,
|
|
85
|
+
so the script is a convenience the adopter can add in five seconds, and
|
|
86
|
+
mutating `package.json` widens `init`'s blast radius for no real gain.
|
|
87
|
+
- **Scaffold only the schema file, no generator script.** Considered — the
|
|
88
|
+
CLI alone (`npx env-cap --location ...`) covers generation. Kept the
|
|
89
|
+
generator script anyway: it documents the full option set (docs,
|
|
90
|
+
ownership, `.env.example`) in a form the adopter edits, which a bare CLI
|
|
91
|
+
invocation in `Next:` output doesn't.
|
|
92
|
+
- **An interactive prompt flow** (pick a directory, name the capability).
|
|
93
|
+
Rejected — `init` must be safely runnable inside a CI step or a
|
|
94
|
+
higher-level generator; non-interactive and deterministic is the
|
|
95
|
+
constraint.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# 0043: env-cap's path-alias resolver is relocated into `src/build/resolution/` and duplicated, not extracted to a shared package
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Filed in both `env-cap` and `data-cap`. Implemented in env-cap by
|
|
6
|
+
relocating `resolve-import.ts`, `resolve-tsconfig-paths.ts`,
|
|
7
|
+
`resolve-package-schema.ts`, `resolve-within-root.ts` (and their tests)
|
|
8
|
+
into `src/build/resolution/`, with zero change to `@maverickcer/env-cap/
|
|
9
|
+
build`'s public export surface, verified via `npm run verify` and a
|
|
10
|
+
git-stash export-list diff before/after; implemented in data-cap by
|
|
11
|
+
copying that folder verbatim as the seed for `src/build/resolution/`.
|
|
12
|
+
|
|
13
|
+
**Amended (internal-package-contract managed copies).** The decision to avoid a shared _runtime
|
|
14
|
+
dependency_ stands: neither package imports a shared package at runtime. What changed is that code known to
|
|
15
|
+
be identical is no longer maintained twice. internal-package-contract owns the canonical source of the
|
|
16
|
+
path-alias resolver (`resolve-tsconfig-paths`), the build filesystem types, the TypeScript loader and its
|
|
17
|
+
error, `glob`, `displayPath` and the generated-file banner, and each package carries a byte-identical copy in
|
|
18
|
+
`src/_ipc/`, kept current by `internal-package-contract sync` and checked by the `ManagedFiles` check. The
|
|
19
|
+
package's own `src/build/**` files are thin wrappers that bind the package's name. The other resolution
|
|
20
|
+
modules (`resolve-import`, `resolve-within-root`, `resolve-package-schema`) stay independent, because their
|
|
21
|
+
result shapes differ between the two packages.
|
|
22
|
+
|
|
23
|
+
## Context
|
|
24
|
+
|
|
25
|
+
data-cap's build tooling needs exactly the same specifier-resolution
|
|
26
|
+
primitives env-cap's already has — relative-import resolution, tsconfig
|
|
27
|
+
path-alias resolution (ADR 0032), cross-package schema resolution — and
|
|
28
|
+
the underlying logic is already specifier-target-agnostic (it resolves _a
|
|
29
|
+
specifier_ to _a file_; it has no opinion about what kind of schema lives
|
|
30
|
+
at that file). Two live options existed: extract a shared package both
|
|
31
|
+
repos depend on, or duplicate the logic into data-cap directly.
|
|
32
|
+
|
|
33
|
+
## Decision
|
|
34
|
+
|
|
35
|
+
The logic is duplicated, not extracted into a shared package. As a
|
|
36
|
+
prerequisite, env-cap's own `src/build/resolve-*.ts` files were first
|
|
37
|
+
relocated (an internal reorg only — same public exports, same behavior,
|
|
38
|
+
same tests just re-pathed) into their own `src/build/resolution/`
|
|
39
|
+
subfolder, to make the boundary of what would be copied explicit and
|
|
40
|
+
self-contained. That folder was then copied verbatim into `data-cap/src/
|
|
41
|
+
build/resolution/` as data-cap's own starting point; data-cap's build
|
|
42
|
+
tooling adapts only the call sites (what gets linked), never the
|
|
43
|
+
resolution primitives themselves.
|
|
44
|
+
|
|
45
|
+
## Consequences
|
|
46
|
+
|
|
47
|
+
- Each package's `resolution/` folder can evolve independently once
|
|
48
|
+
copied — a data-cap-specific fix or optimization never risks an
|
|
49
|
+
unintended behavior change in env-cap, and vice versa.
|
|
50
|
+
- Neither package takes on a third, shared-package dependency (with its
|
|
51
|
+
own versioning, release, and compatibility surface) for logic that,
|
|
52
|
+
while duplicated, is small enough (a handful of files) that the
|
|
53
|
+
duplication cost is genuinely lower than a shared package's overhead.
|
|
54
|
+
- The relocation-first step means both repos now describe this logic's
|
|
55
|
+
boundary identically (`src/build/resolution/`), so a future contributor
|
|
56
|
+
moving between the two codebases finds it in the same place either way.
|
|
57
|
+
|
|
58
|
+
## Alternatives considered
|
|
59
|
+
|
|
60
|
+
- **Extracting a shared internal package** (e.g.
|
|
61
|
+
`@maverickcer/module-resolution`) both repos depend on. Rejected —
|
|
62
|
+
explicitly, by the user's own scoping decision: "the logic is fairly
|
|
63
|
+
straightforward although it is split across many files and this isn't a
|
|
64
|
+
large enough issue for there to be a generic widely used module resolver
|
|
65
|
+
package." A shared package's release/versioning overhead wasn't judged
|
|
66
|
+
worth it for logic this contained.
|
|
67
|
+
- **Leaving env-cap's resolver in `src/build/` unrelocated, copying files
|
|
68
|
+
from scattered locations.** Rejected — the relocation makes the
|
|
69
|
+
copied boundary explicit and self-contained for both the copy itself and
|
|
70
|
+
any future re-sync, rather than requiring a contributor to re-derive
|
|
71
|
+
"which files, exactly" every time.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# 0044: Bare `--strict` escalates every warning family, not just manifest compatibility
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Implemented in `src/cli/index.ts` (`artifactOptions`,
|
|
6
|
+
`groupEscalates`); covered by `test/cli/index.test.ts`. Breaking change to
|
|
7
|
+
`--strict`'s own behavior, not to any exported type shape.
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
Before this decision, `--strict` escalated only the manifest pass's
|
|
12
|
+
compatibility findings (ADR 0009's provable exclusive-group/compatibility
|
|
13
|
+
errors) to a hard error; documentation and ownership warnings needed their
|
|
14
|
+
own separate `--strict-docs`/`--strict-ownership` flags to escalate at all
|
|
15
|
+
— `--strict` alone left them at `warn`. This was a deliberate, documented
|
|
16
|
+
scoping (GUIDE.md/`--help` both said so explicitly), not an oversight.
|
|
17
|
+
|
|
18
|
+
A cross-package parity audit ahead of either package's `1.0` release
|
|
19
|
+
compared the two siblings'
|
|
20
|
+
identically-named `--strict`/`--strict-docs`/`--strict-ownership` flags and
|
|
21
|
+
found they mean different things: data-cap's bare `--strict` already
|
|
22
|
+
escalates every pass (docs, ownership, and its own flow-family findings)
|
|
23
|
+
via an OR across `--strict`/the group-specific flag
|
|
24
|
+
(`src/build/generate-data-artifacts.ts`'s `groupEscalates`). Same flag
|
|
25
|
+
name, same lineage, materially different scope — a CI script written
|
|
26
|
+
against one tool's `--strict` and copied to the other silently gets
|
|
27
|
+
different enforcement. Worse, "strict" without qualification naturally
|
|
28
|
+
reads as "maximum strictness"; a user who ran bare `--strict` in CI
|
|
29
|
+
expecting full escalation and got only the compatibility family was
|
|
30
|
+
carrying a false sense of safety about documentation/ownership drift —
|
|
31
|
+
exactly the class of problem an audit tool exists to prevent, not
|
|
32
|
+
reproduce in its own flag semantics.
|
|
33
|
+
|
|
34
|
+
## Decision
|
|
35
|
+
|
|
36
|
+
Bare `--strict` now escalates all three provable-error families at once —
|
|
37
|
+
compatibility, documentation, and ownership — equivalent to passing
|
|
38
|
+
`--strict --strict-docs --strict-ownership` together. `--strict-docs`/
|
|
39
|
+
`--strict-ownership` are unchanged: still independently settable, still
|
|
40
|
+
escalate their own family alone when passed without bare `--strict`.
|
|
41
|
+
|
|
42
|
+
Mechanically: `parseArgs` keeps `strict`/`strictDocs`/`strictOwnership` as
|
|
43
|
+
three independent booleans (unchanged — `--strict` still never sets the
|
|
44
|
+
other two flags itself). The OR happens once, at read time, in
|
|
45
|
+
`artifactOptions`'s new `groupEscalates(strict, specificFlag)` helper —
|
|
46
|
+
`onUndocumented`/`onOwnershipIssue` both now read
|
|
47
|
+
`groupEscalates(args.strict, args.strictDocs/args.strictOwnership) ?
|
|
48
|
+
"throw" : "warn"`, matching data-cap's own `groupEscalates`
|
|
49
|
+
(`src/build/generate-data-artifacts.ts`) exactly in name and shape.
|
|
50
|
+
|
|
51
|
+
## Consequences
|
|
52
|
+
|
|
53
|
+
- **Breaking.** Any CI pipeline currently running bare `--strict` alone,
|
|
54
|
+
relying on it _not_ escalating documentation/ownership warnings, will
|
|
55
|
+
start failing on pre-existing warnings in those families the next time
|
|
56
|
+
it runs. This is a real, deliberate behavior change, not a bug fix wearing
|
|
57
|
+
a disguise — anyone affected needs to either fix the newly-escalated
|
|
58
|
+
findings or drop back to `--strict-docs`/`--strict-ownership` individually
|
|
59
|
+
(or neither) to keep today's narrower gate.
|
|
60
|
+
- `--strict`'s and data-cap's `--strict`'s meaning are now the same shape
|
|
61
|
+
(an all-families shorthand, with independent per-family flags underneath)
|
|
62
|
+
for anyone using both tools.
|
|
63
|
+
- `GUIDE.md`, `ADOPTION.md`, and `--help`'s own `--strict` description are
|
|
64
|
+
updated to describe the new scope; the GitHub Action's own pass/fail
|
|
65
|
+
section is updated too, since it previously singled out compatibility as
|
|
66
|
+
"the one provable, manifest-pass error category."
|
|
67
|
+
|
|
68
|
+
## Alternatives considered
|
|
69
|
+
|
|
70
|
+
- **Narrow data-cap's `--strict` to match env-cap's old scope instead.**
|
|
71
|
+
Rejected — data-cap's broader "escalate everything" semantics matches
|
|
72
|
+
what "strict" naturally reads as, and narrowing an already-shipped
|
|
73
|
+
strictness flag is the more dangerous direction: an existing data-cap CI
|
|
74
|
+
gate relying on `--strict` catching docs/ownership drift would silently
|
|
75
|
+
lose that coverage. Widening env-cap's `--strict` is the safer kind of
|
|
76
|
+
breaking change for a strictness flag — previously-passing CI newly
|
|
77
|
+
failing on a real, pre-existing problem it should have caught, never the
|
|
78
|
+
reverse.
|
|
79
|
+
- **Leave the divergence undocumented as an intentional design
|
|
80
|
+
difference.** Rejected — there was no actual domain reason for env-cap's
|
|
81
|
+
narrower scope; it was just how the flag grew one family at a time before
|
|
82
|
+
`--strict-docs`/`--strict-ownership` existed, never revisited once they
|
|
83
|
+
did.
|
|
84
|
+
- **A fourth, explicit `--strict-all` flag, leaving bare `--strict` as
|
|
85
|
+
compatibility-only.** Rejected — adds a flag name to remember for no
|
|
86
|
+
real benefit over just widening `--strict` itself, and still leaves the
|
|
87
|
+
cross-package naming mismatch (data-cap has no `--strict-all`) unresolved
|
|
88
|
+
for the "familiar experience switching tools" goal this change exists for.
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# 0045: Promote every remaining Experimental surface to Stable
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Moves the entire Experimental-tier bullet list in `VERSIONING.md`
|
|
6
|
+
into Stable, leaving the Experimental section empty. Removes every
|
|
7
|
+
`**Experimental**`/`Experimental, see ADR NNNN` doc-comment and CLI
|
|
8
|
+
help-text marker for the promoted surfaces across `src/build/generate-manifest.ts`,
|
|
9
|
+
`generate-documentation.ts`, `generate-evidence.ts`, `generate-usage.ts`,
|
|
10
|
+
`generate-env-artifacts.ts`, `index.ts`, `resolution/resolve-tsconfig-paths.ts`,
|
|
11
|
+
`resolution/resolve-package-schema.ts`, and `src/cli/index.ts`'s help text;
|
|
12
|
+
updates the corresponding prose in `README.md`, `GUIDE.md`, `SECURITY.md`,
|
|
13
|
+
and `ADOPTION.md`.
|
|
14
|
+
|
|
15
|
+
## Context
|
|
16
|
+
|
|
17
|
+
`VERSIONING.md`'s own Experimental-tier definition states the graduation
|
|
18
|
+
criterion directly: "Once a feature has been through at least one real
|
|
19
|
+
feedback cycle without a need to break it... it becomes Stable." Applying
|
|
20
|
+
that criterion to each currently-Experimental surface:
|
|
21
|
+
|
|
22
|
+
- **`packages`/`tsconfig` options** (ADR 0014/ADR 0023): the first surfaces
|
|
23
|
+
to ship this way, in real use the longest, with no reported need to
|
|
24
|
+
change either option's shape.
|
|
25
|
+
- **The lower-level `./build` primitives** (`discoverSchemaFiles`,
|
|
26
|
+
`linkFiles`, `parseSchemaFile`, `renderManifest`, `renderDocs`,
|
|
27
|
+
`detectCompatibilityIssues`, `detectExclusiveGroupIssues`): justified for
|
|
28
|
+
real external use (custom CI scripts, bundler plugins) since their
|
|
29
|
+
introduction, with no reported need to change their signatures.
|
|
30
|
+
- **`generateEvidenceModel`/`getEvidenceModel`/`computeSourceFingerprint`/
|
|
31
|
+
`renderUsageReport`**: each has shipped with its current contract since
|
|
32
|
+
introduction; `generateEvidenceModel`'s "every finding becomes a
|
|
33
|
+
`Finding`, never a throw" behavior is explicitly its permanent, intended
|
|
34
|
+
shape (see ADR 0031), not a temporary gap this promotion needed to close.
|
|
35
|
+
- **The `init` CLI subcommand** (ADR 0042): its scaffolded file set and
|
|
36
|
+
template contents have not needed to change since introduction.
|
|
37
|
+
- **`@maverickcer/env-cap/evidence`** (`defineEvidenceProjection`, `EvidenceModel`) and
|
|
38
|
+
**the persisted evidence artifact** format: see the caveat below --
|
|
39
|
+
promoted along with everything else per this decision's scope, but with a
|
|
40
|
+
real, named exception to the "no reported need to change" pattern the
|
|
41
|
+
other promotions share.
|
|
42
|
+
|
|
43
|
+
This package is laser-focused on one core benefit -- environment-variable
|
|
44
|
+
contracts that are documented, owned, and validated by construction -- and
|
|
45
|
+
every mechanism that ships as part of it is meant to be depended on with
|
|
46
|
+
confidence, not held at arm's length behind a tier that exists for genuine
|
|
47
|
+
uncertainty that no longer applies.
|
|
48
|
+
|
|
49
|
+
## Decision
|
|
50
|
+
|
|
51
|
+
Promote all of it to Stable in one pass. The Experimental tier itself stays
|
|
52
|
+
defined in `VERSIONING.md` -- it remains the right mechanism for a
|
|
53
|
+
genuinely new, unproven future surface -- it is just empty right now,
|
|
54
|
+
honestly, rather than holding onto a designation that no longer describes
|
|
55
|
+
something true for these APIs.
|
|
56
|
+
|
|
57
|
+
**Named caveat, not silently dropped:** `VERSIONING.md`'s prior text for
|
|
58
|
+
`@maverickcer/env-cap/evidence` said real projection authorship "is likely to surface a
|
|
59
|
+
better shape for `EvidenceProjectionResult.sources` in particular
|
|
60
|
+
(currently flat `EvidenceModel` field-path strings, not yet resolved into
|
|
61
|
+
structured `EvidenceReference`s -- see ADR 0032's Consequences)." That is a
|
|
62
|
+
specific, acknowledged, _unresolved_ design question about the current
|
|
63
|
+
shape being probably wrong in one particular spot -- not merely "hasn't had
|
|
64
|
+
time to prove itself yet," which is the graduation story every other
|
|
65
|
+
surface in this ADR has. Promoting it anyway is a deliberate choice to
|
|
66
|
+
apply one consistent policy fleet-wide rather than carve out an exception,
|
|
67
|
+
made with that specific risk stated plainly here rather than folded
|
|
68
|
+
silently into a blanket "everything's fine now" promotion. A future
|
|
69
|
+
`sources` shape change, if `EvidenceReference` resolution is added, is a
|
|
70
|
+
real Stable-tier breaking change from this point forward -- not the
|
|
71
|
+
minor-may-break allowance an Experimental surface would still have had.
|
|
72
|
+
|
|
73
|
+
## Consequences
|
|
74
|
+
|
|
75
|
+
- A breaking change to any promoted surface now requires a major version
|
|
76
|
+
bump (once `env-cap` reaches 1.0 -- see `VERSIONING.md`'s Pre-1.0 status
|
|
77
|
+
section; before that, the existing minor-may-break-Stable allowance still
|
|
78
|
+
applies, same as every other Stable surface).
|
|
79
|
+
- No runtime behavior changes anywhere in this ADR -- documentation and
|
|
80
|
+
compatibility-promise change only, verified by the full test suite
|
|
81
|
+
passing unchanged.
|
|
82
|
+
- `EvidenceProjectionResult.sources`'s field-path-string shape is now a
|
|
83
|
+
Stable commitment despite the open design question above -- see the
|
|
84
|
+
caveat. If that question resolves toward structured `EvidenceReference`s
|
|
85
|
+
later, it ships as a major (or, pre-1.0, an explicitly-flagged breaking
|
|
86
|
+
minor per existing convention), not a quiet Experimental-tier adjustment.
|
|
87
|
+
|
|
88
|
+
## Alternatives considered
|
|
89
|
+
|
|
90
|
+
- **Promote everything except `@maverickcer/env-cap/evidence`/the evidence artifact
|
|
91
|
+
format, leaving those two Experimental until the `sources` question
|
|
92
|
+
resolves.** This is the technically more conservative option, and was
|
|
93
|
+
seriously considered given the caveat above is a real, specific,
|
|
94
|
+
unresolved concern rather than a generic "needs more time." Not taken for
|
|
95
|
+
this pass because the fleet-wide decision this ADR implements is to carry
|
|
96
|
+
no Experimental-tier surface at all; the caveat is recorded here precisely
|
|
97
|
+
so this tradeoff is visible and reversible (a future ADR can re-introduce
|
|
98
|
+
an Experimental designation for `sources` specifically if the shape
|
|
99
|
+
question surfaces a real need to break it before 1.0).
|
|
100
|
+
- **Promote piecemeal, one ADR-reviewed feedback cycle at a time.**
|
|
101
|
+
Rejected for the surfaces with no open design question -- they already
|
|
102
|
+
independently satisfy the graduation criterion, so gating them on
|
|
103
|
+
separate future ADRs would just delay an already-justified decision.
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
# 0046: The CLI surface is restricted to flags with a verified real consumer
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Removes `--docs`, `--ownership`, `--env-example`, and
|
|
6
|
+
`--env-example-on-existing` from `src/cli/index.ts` (`ParsedArgs`,
|
|
7
|
+
`VALUE_FLAGS`, `helpText()`, the "at least one of ..." guard, and every
|
|
8
|
+
CLI-only rendering path that only existed to format their output --
|
|
9
|
+
`printDocsSummary()`, `printUsageSummary()`, and the corresponding terms in
|
|
10
|
+
`runGenerateMode()`'s warning-count banner). `--expiring-within-days` is
|
|
11
|
+
removed too, as a direct structural consequence (see Context). Covered by
|
|
12
|
+
`test/cli/index.test.ts` and `test/cli/main.test.ts`.
|
|
13
|
+
|
|
14
|
+
`computeDocumentation`/`writeDocumentation`/`computeUsage`/`writeUsageReport`
|
|
15
|
+
(`src/build/generate-documentation.ts`, `src/build/generate-usage.ts`), and
|
|
16
|
+
the higher-level orchestrators `generateDocumentation`/`generateUsageReport`/
|
|
17
|
+
`generateEnvArtifacts`/`checkEnvArtifacts` that compose them, are **not**
|
|
18
|
+
changed by this decision and remain fully exported from `@maverickcer/env-cap/build`,
|
|
19
|
+
Stable per ADR 0045. Nothing about the library surface shrank -- only what
|
|
20
|
+
the packaged CLI binary can trigger by itself.
|
|
21
|
+
|
|
22
|
+
## Context
|
|
23
|
+
|
|
24
|
+
`env-cap`'s CLI (`src/cli/index.ts`) grew flags for every artifact the
|
|
25
|
+
library could produce, on the assumption that "the library can generate it"
|
|
26
|
+
and "the CLI should have a flag for it" were the same decision. They aren't.
|
|
27
|
+
Auditing the CLI's actual flag set against what each flag's output is
|
|
28
|
+
_for_ found two different categories, previously flattened into one:
|
|
29
|
+
|
|
30
|
+
- **Flags whose output something else in a real project actually reads.**
|
|
31
|
+
`--location` writes the generated manifest `.ts` file that application
|
|
32
|
+
code `import`s and passes to `validateEnv()` (see
|
|
33
|
+
`examples/team-service/src/startup.ts`, `examples/nextjs-app`'s
|
|
34
|
+
`src/env.ts`) -- a real, provable runtime dependency. `--evidence` writes
|
|
35
|
+
the persisted `EvidenceModel` artifact that is itself this package's
|
|
36
|
+
reporting contract (ADR 0038: "always computed, always real" -- Finding
|
|
37
|
+
Model, evidence projections, and CI drift-guards all key off this one
|
|
38
|
+
file). `--json`/`--check` are inherent to the tool's own contract, not
|
|
39
|
+
outputs of a particular pass (ADR 0013, ADR 0016).
|
|
40
|
+
- **Flags whose output nothing in a real project reads at runtime, or
|
|
41
|
+
checks programmatically, at all.** `--docs` (the rich Markdown catalog)
|
|
42
|
+
and `--ownership` (the dependency & ownership report) are purely
|
|
43
|
+
human-facing documentation. Auditing every example in this repo
|
|
44
|
+
(`examples/application`, `examples/team-service`, `examples/nextjs-app`,
|
|
45
|
+
`examples/enterprise-platform`) found no `import` of `docs/ENVIRONMENT.md`
|
|
46
|
+
or `docs/OWNERSHIP.md` anywhere, and no test asserting on their content
|
|
47
|
+
except as committed, golden, human-readable output. `--env-example` turned
|
|
48
|
+
out to be structurally _part of_ the docs pass, not independent of it --
|
|
49
|
+
`writeDocumentation()`'s signature requires a `docsPath: string` (not
|
|
50
|
+
optional) to write an `.env.example` at all, and the CLI's own pre-existing
|
|
51
|
+
help text already said as much ("`--env-example <path>` ... only
|
|
52
|
+
meaningful alongside `--docs`"). Once `--docs` is gone, `--env-example`
|
|
53
|
+
has no remaining CLI path to reach `writeDocumentation()` through, so it
|
|
54
|
+
was removed alongside it rather than left as a flag that silently does
|
|
55
|
+
nothing. `--expiring-within-days` has the same structural problem one
|
|
56
|
+
level up: `GenerateEnvArtifactsOptions.docs.expiringWithinDays` is the
|
|
57
|
+
only place that value is threaded through
|
|
58
|
+
(`computeArtifacts()`'s `docsOptions?.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS`),
|
|
59
|
+
so it too had no remaining CLI path once `--docs` no longer exists to
|
|
60
|
+
carry it.
|
|
61
|
+
|
|
62
|
+
This distinction matters for a stronger reason than tidiness: every CLI flag
|
|
63
|
+
is a compatibility surface someone can build a CI pipeline against (ADR
|
|
64
|
+
0044's own `--strict` audit made exactly this point about flag semantics
|
|
65
|
+
drifting from what a reasonable user expects). A flag whose only job is
|
|
66
|
+
"write a file nothing else reads" earns its place by being _useful_, not by
|
|
67
|
+
being _possible_ -- and it was already possible without the flag: every
|
|
68
|
+
generator function it called was, and remains, a plain exported function
|
|
69
|
+
from `@maverickcer/env-cap/build`. Keeping `--docs`/`--ownership` in the CLI while their
|
|
70
|
+
only real consumers turned out to be humans reading committed Markdown, not
|
|
71
|
+
other code or a CI drift check with independent value, meant the CLI's
|
|
72
|
+
surface area didn't reflect what the tool's flags were actually _for_.
|
|
73
|
+
|
|
74
|
+
A secondary, mechanical reason forced the same conclusion from a different
|
|
75
|
+
angle: once `--docs`/`--ownership` are removed from `ParsedArgs`,
|
|
76
|
+
`artifactOptions()` can never again set `GenerateEnvArtifactsOptions.docs`/
|
|
77
|
+
`.usage` from a real CLI invocation, which makes `result.docs`/`result.usage`
|
|
78
|
+
permanently `undefined` on every real `runGenerateMode()` call. Under this
|
|
79
|
+
repo's zero-tolerance Mutation gate (`npm run contract`), the CLI's own
|
|
80
|
+
`printDocsSummary()`/`printUsageSummary()` functions and their
|
|
81
|
+
`if (result.docs)`/`if (result.usage)` call sites would then be
|
|
82
|
+
permanently unreachable dead code -- no real CLI-level test could construct
|
|
83
|
+
a state where the removed flag's summary-printing branch is taken. Rather
|
|
84
|
+
than leave dead branches a mutation-testing gate would rightly flag,
|
|
85
|
+
they were removed along with the flags that used to reach them.
|
|
86
|
+
|
|
87
|
+
## Decision
|
|
88
|
+
|
|
89
|
+
The `env-cap` CLI's flag set is restricted to flags with a verified real
|
|
90
|
+
runtime consumer (`--location`), or that are inherent to the tool's own
|
|
91
|
+
evidence/reporting contract (`--evidence`, `--json`, `--check`), plus the
|
|
92
|
+
flags that scope/configure those (`--root`, `--include`, `--exclude`,
|
|
93
|
+
`--package`, `--tsconfig`/`--no-tsconfig`, `--strict`/`--strict-docs`/
|
|
94
|
+
`--strict-ownership`, `--help`). `--strict-docs`/`--strict-ownership`
|
|
95
|
+
survive this cut even though they're documentation/ownership-scoped,
|
|
96
|
+
because they don't write a docs/ownership _artifact_ at all -- they
|
|
97
|
+
escalate Finding Model's always-computed documentation/ownership warnings
|
|
98
|
+
(ADR 0038) into a blocking error on the manifest/evidence write path,
|
|
99
|
+
independent of whether a docs/ownership file is ever produced (confirmed by
|
|
100
|
+
existing behavior: bare `--strict --location` already escalated
|
|
101
|
+
documentation/ownership findings before this change, per ADR 0044).
|
|
102
|
+
|
|
103
|
+
Flags with no verified runtime consumer -- `--docs`, `--ownership`,
|
|
104
|
+
`--env-example`, `--env-example-on-existing`, `--expiring-within-days` --
|
|
105
|
+
move to application-level code: a project that wants
|
|
106
|
+
`docs/ENVIRONMENT.md`/`docs/OWNERSHIP.md`/`.env.example` now calls
|
|
107
|
+
`generateDocumentation()`/`generateUsageReport()` (or the lower-level
|
|
108
|
+
`computeDocumentation`/`writeDocumentation`/`computeUsage`/
|
|
109
|
+
`writeUsageReport`, or `checkEnvArtifacts()` for a `--check`-equivalent
|
|
110
|
+
drift guard) directly from `@maverickcer/env-cap/build` in its own build script, exactly
|
|
111
|
+
as it would for any other custom reporting need this package doesn't build
|
|
112
|
+
in (see ADR 0010's precedent: engine internals stay private until a
|
|
113
|
+
primitive earns public status through real external use; these four
|
|
114
|
+
orchestrators already have that status, per ADR 0045). Every example this
|
|
115
|
+
repo ships that used the removed flags (`examples/application`,
|
|
116
|
+
`examples/team-service`, `examples/nextjs-app`) now carries a
|
|
117
|
+
`scripts/generate-docs/{run.ts,check.ts}` pair doing exactly this --
|
|
118
|
+
`examples/enterprise-platform` already had an equivalent hand-written
|
|
119
|
+
script (`scripts/generate-manifest.mjs`) calling `generateEnvArtifacts()`
|
|
120
|
+
directly with `docs`/`usage` options, predating this decision, which only
|
|
121
|
+
needed its `check` script updated the same way (a new
|
|
122
|
+
`scripts/check-artifacts.mjs`, calling the now-CLI-unreachable
|
|
123
|
+
`checkEnvArtifacts()` directly).
|
|
124
|
+
|
|
125
|
+
## Consequences
|
|
126
|
+
|
|
127
|
+
- **Breaking, but pre-1.0 minor per this repo's convention.** Any script
|
|
128
|
+
invoking `env-cap --docs ...`/`--ownership ...`/`--env-example ...`/
|
|
129
|
+
`--env-example-on-existing ...`/`--expiring-within-days ...` now fails
|
|
130
|
+
with `Unknown argument: --docs` (etc.) instead of generating output. The
|
|
131
|
+
fix is mechanical: call the equivalent `@maverickcer/env-cap/build` function directly
|
|
132
|
+
from a small script, following the pattern in any of this repo's own
|
|
133
|
+
`examples/*/scripts/generate-docs/` directories.
|
|
134
|
+
- `generateEnvArtifacts()`'s own `docs`/`usage` options (`GenerateEnvArtifactsOptions`)
|
|
135
|
+
are completely unaffected -- they remain a fully supported part of that
|
|
136
|
+
Stable, exported orchestrator's public contract for any caller that
|
|
137
|
+
supplies them directly (not through the CLI). The CLI itself simply never
|
|
138
|
+
populates them anymore.
|
|
139
|
+
- The CLI's `--json` envelope (`JsonRequestedPasses.docs`/`.usage`) keeps
|
|
140
|
+
both fields, unchanged in shape -- `requestedPasses()` now always reports
|
|
141
|
+
them `false` from the CLI, since neither pass can be requested through it
|
|
142
|
+
anymore, but the envelope's schema itself (and `JSON_SCHEMA_VERSION`)
|
|
143
|
+
didn't need to change, since no field was removed or reinterpreted.
|
|
144
|
+
- `docs/ENVIRONMENT.md`'s/`docs/OWNERSHIP.md`'s generated byline named the removed CLI flags
|
|
145
|
+
(``_Produced by `env-cap --docs`._``/``_Produced by `env-cap --ownership`._``), which was
|
|
146
|
+
inaccurate for every example generating these through application code. That was left for a
|
|
147
|
+
focused follow-up, because both renderers are shared by every consumer of
|
|
148
|
+
`@maverickcer/env-cap/build` and correcting the byline is a golden-fixture-wide change. _Amended:
|
|
149
|
+
the follow-up is done. The shared renderers now state the build function that produced the
|
|
150
|
+
file (`generateDocumentation()` in `src/build/docs.ts`, `generateUsageReport()` in
|
|
151
|
+
`src/build/usage-report.ts`), and neither renders a CLI flag._
|
|
152
|
+
|
|
153
|
+
## Alternatives considered
|
|
154
|
+
|
|
155
|
+
- **Keep `--docs`/`--ownership` in the CLI regardless of runtime
|
|
156
|
+
consumption, since "more flags" costs nothing on its own.** Rejected --
|
|
157
|
+
it costs exactly what this ADR's Context section describes: dead,
|
|
158
|
+
mutation-flagged branches in the CLI's own rendering code once nothing
|
|
159
|
+
can reach them, and a CLI surface that no longer reflects a verified
|
|
160
|
+
reason to exist for each flag, which is the actual audit this change
|
|
161
|
+
applies.
|
|
162
|
+
- **Keep `--env-example`/`--expiring-within-days` independently reachable
|
|
163
|
+
by restructuring `writeDocumentation()`/`computeArtifacts()` so they no
|
|
164
|
+
longer require the docs pass.** Rejected for this pass -- both are
|
|
165
|
+
genuinely, structurally nested under the docs pass in the current library
|
|
166
|
+
design (`writeDocumentation()`'s `docsPath` parameter is not optional;
|
|
167
|
+
`expiringWithinDays` lives only on `GenerateEnvArtifactsOptions.docs`),
|
|
168
|
+
and restructuring either is a library-shape change with its own blast
|
|
169
|
+
radius across every existing caller -- out of scope for a CLI-surface
|
|
170
|
+
change that was explicitly scoped to keep the library "fully available,
|
|
171
|
+
unchanged."
|
|
172
|
+
- **Cite ADR 0001 (runtime/`documentEnv` separation) as this decision's
|
|
173
|
+
direct precedent.** Considered, since both decisions draw a line between
|
|
174
|
+
"runtime-relevant" and "documentation-only" concerns. Not treated as a
|
|
175
|
+
full precedent, since ADR 0001 is about the _authoring_ API
|
|
176
|
+
(`createEnv`/`documentEnv`), not the CLI's own flag surface -- referenced
|
|
177
|
+
here as related reasoning, not superseded or extended.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# 0047: Supported toolchain is Node 22+ and TypeScript 5 or 6
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. The TypeScript 7 paragraph is superseded by
|
|
6
|
+
[ADR 0049](0049-typescript-7-scanner-uses-a-bundled-typescript-6.md).
|
|
7
|
+
|
|
8
|
+
## Context
|
|
9
|
+
|
|
10
|
+
Node 20 reached end-of-life on 2026-04-30, so advertising it would commit the package to a runtime
|
|
11
|
+
nobody patches. Separately, the build-time scanner (`src/build/parse.ts`, `scan-dependencies.ts`)
|
|
12
|
+
uses TypeScript's classic compiler API (`createSourceFile`). TypeScript 6 still has it; TypeScript 7
|
|
13
|
+
moved the syntax-tree API to `typescript/unstable/*`, and the optional peer `^5.0.0` also made
|
|
14
|
+
`npm i typescript@latest @maverickcer/env-cap` fail with `ERESOLVE`.
|
|
15
|
+
|
|
16
|
+
## Decision
|
|
17
|
+
|
|
18
|
+
- `engines.node` is `>=22.0.0`; `@types/node` is `^22`; bundles for Node target `node22`; CI tests 22
|
|
19
|
+
and 24 (26 non-blocking).
|
|
20
|
+
- The optional `typescript` peer is `^5.0.0 || ^6.0.0`.
|
|
21
|
+
- TypeScript 7 is unsupported for the build step. Migrating to `typescript/unstable/*` is deferred
|
|
22
|
+
until that API is stable. `assertCompilerApi` makes the scanner fail with a message that names
|
|
23
|
+
the installed version and the workaround (install `typescript@6` for the build step) rather than
|
|
24
|
+
`ts.createSourceFile is not a function`.
|
|
25
|
+
- The runtime entry points never import TypeScript and are unaffected.
|
|
26
|
+
|
|
27
|
+
## Consequences
|
|
28
|
+
|
|
29
|
+
Dropping Node 20 is a breaking change, released as a pre-1.0 minor. `VERSIONING.md` lists the
|
|
30
|
+
toolchain as Stable.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# 0048: The ESLint plugin does not vendor `@typescript-eslint/utils`
|
|
2
|
+
|
|
3
|
+
## Status
|
|
4
|
+
|
|
5
|
+
Accepted. Supersedes the "bundle it" note in `tsup.config.ts` and package.json's old devDependency comment.
|
|
6
|
+
|
|
7
|
+
## Context
|
|
8
|
+
|
|
9
|
+
`./eslint-plugin` used to inline `@typescript-eslint/utils` and `@typescript-eslint/types` into its
|
|
10
|
+
bundle. A consumer's `npm audit`, Dependabot and Socket then could not see those packages (an
|
|
11
|
+
advisory never reaches users), their versions were frozen at build time, and the vendored text was
|
|
12
|
+
most of what supply-chain scanners flagged in the published tarball. `./eslint-plugin` is a public
|
|
13
|
+
subpath, so changing it after 1.0.0 would be a breaking change.
|
|
14
|
+
|
|
15
|
+
## Decision
|
|
16
|
+
|
|
17
|
+
Keep the subpath. Declare `@typescript-eslint/utils` as an optional peer (`^8.0.0`), mark it
|
|
18
|
+
external in the bundle, and import `AST_NODE_TYPES` from it instead of from `@typescript-eslint/types`
|
|
19
|
+
(a dependency of utils). Anyone linting TypeScript with ESLint already has it through
|
|
20
|
+
`typescript-eslint`.
|
|
21
|
+
|
|
22
|
+
## Consequences
|
|
23
|
+
|
|
24
|
+
A project that uses `./eslint-plugin` must have `@typescript-eslint/utils` installed. The packed
|
|
25
|
+
`dist/eslint-plugin/*` shrinks by about 400 KB per format.
|