@maverickcer/env-cap 0.7.4 → 0.7.6
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 +106 -124
- package/AGENTS.md +94 -128
- package/CHANGELOG.md +42 -0
- package/CODE_REVIEW.md +69 -173
- package/CONTRIBUTING.md +57 -74
- package/GUIDE.md +405 -866
- package/README.md +112 -89
- package/RELEASING.md +81 -65
- package/SECURITY.md +76 -227
- package/SUPPORT.md +21 -45
- package/VERSIONING.md +69 -105
- package/benchmarks/READING-BENCHMARKS.md +103 -81
- package/benchmarks/README.md +12 -9
- package/benchmarks/WRITING-BENCHMARKS.md +90 -80
- package/benchmarks/performance-buildtime/BENCHMARKS.md +20 -20
- package/benchmarks/performance-runtime/BENCHMARKS.md +107 -107
- package/dist/.dts/_ipc/build-fs.d.ts +12 -17
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
- package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
- package/dist/.dts/_ipc/display-path.d.ts +1 -1
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
- package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
- package/dist/.dts/_ipc/glob.d.ts +9 -8
- package/dist/.dts/_ipc/glob.d.ts.map +1 -1
- package/dist/.dts/_ipc/no-node-fs.d.ts +2 -2
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +16 -16
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/_ipc/typescript.d.ts +4 -4
- package/dist/.dts/build/assemble-project.d.ts +14 -15
- package/dist/.dts/build/assemble-project.d.ts.map +1 -1
- package/dist/.dts/build/change-model.d.ts +14 -14
- package/dist/.dts/build/change-model.d.ts.map +1 -1
- package/dist/.dts/build/check-artifacts.d.ts +4 -4
- package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
- package/dist/.dts/build/citation-verification.d.ts +13 -14
- package/dist/.dts/build/citation-verification.d.ts.map +1 -1
- package/dist/.dts/build/compatibility.d.ts +24 -24
- package/dist/.dts/build/compatibility.d.ts.map +1 -1
- package/dist/.dts/build/contract-model.d.ts +10 -10
- package/dist/.dts/build/contract-model.d.ts.map +1 -1
- package/dist/.dts/build/deep-equal.d.ts +2 -2
- package/dist/.dts/build/deep-freeze.d.ts +2 -2
- package/dist/.dts/build/dependency-graph.d.ts +48 -55
- package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
- package/dist/.dts/build/dependency-model.d.ts +18 -18
- package/dist/.dts/build/dependency-model.d.ts.map +1 -1
- package/dist/.dts/build/discover.d.ts +11 -11
- package/dist/.dts/build/discover.d.ts.map +1 -1
- package/dist/.dts/build/docs.d.ts +34 -38
- package/dist/.dts/build/docs.d.ts.map +1 -1
- package/dist/.dts/build/env-example.d.ts +13 -13
- package/dist/.dts/build/env-example.d.ts.map +1 -1
- package/dist/.dts/build/errors.d.ts +8 -8
- package/dist/.dts/build/evidence-cache.d.ts +23 -23
- package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
- package/dist/.dts/build/evidence-model.d.ts +3 -3
- package/dist/.dts/build/evidence-reference.d.ts +15 -15
- package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
- package/dist/.dts/build/evidence-snapshot.d.ts +47 -53
- package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
- package/dist/.dts/build/exclusive-group.d.ts +4 -4
- package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
- package/dist/.dts/build/finding-model.d.ts +12 -12
- package/dist/.dts/build/finding-model.d.ts.map +1 -1
- package/dist/.dts/build/generate-documentation.d.ts +19 -19
- package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
- package/dist/.dts/build/generate-env-artifacts.d.ts +43 -43
- package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
- package/dist/.dts/build/generate-evidence.d.ts +19 -19
- package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
- package/dist/.dts/build/generate-manifest.d.ts +11 -12
- package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
- package/dist/.dts/build/generate-usage.d.ts +23 -24
- package/dist/.dts/build/generate-usage.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +5 -5
- package/dist/.dts/build/governance-fields.d.ts +7 -7
- package/dist/.dts/build/humanize-key.d.ts +1 -1
- package/dist/.dts/build/humanize-key.d.ts.map +1 -1
- package/dist/.dts/build/index.d.ts +20 -36
- package/dist/.dts/build/index.d.ts.map +1 -1
- package/dist/.dts/build/lifecycle-model.d.ts +90 -83
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts/build/link.d.ts +38 -39
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/literal-eval.d.ts +2 -2
- package/dist/.dts/build/literal-eval.d.ts.map +1 -1
- package/dist/.dts/build/live-expirations.d.ts +14 -13
- package/dist/.dts/build/live-expirations.d.ts.map +1 -1
- package/dist/.dts/build/manifest.d.ts +6 -6
- package/dist/.dts/build/map-utils.d.ts +4 -4
- package/dist/.dts/build/merge-documentation.d.ts +9 -8
- package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
- package/dist/.dts/build/ownership-model.d.ts +14 -15
- package/dist/.dts/build/ownership-model.d.ts.map +1 -1
- package/dist/.dts/build/parse.d.ts +20 -21
- package/dist/.dts/build/parse.d.ts.map +1 -1
- package/dist/.dts/build/reference-projections.d.ts +36 -38
- package/dist/.dts/build/reference-projections.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-import.d.ts +18 -14
- package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-package-schema.d.ts +26 -26
- package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
- package/dist/.dts/build/resolution/resolve-within-root.d.ts +9 -9
- package/dist/.dts/build/sarif.d.ts +5 -5
- package/dist/.dts/build/sarif.d.ts.map +1 -1
- package/dist/.dts/build/scan-dependencies.d.ts +17 -16
- package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
- package/dist/.dts/build/sort-by-identity.d.ts +1 -1
- package/dist/.dts/build/source-position.d.ts +13 -13
- package/dist/.dts/build/tool-version.d.ts +1 -1
- package/dist/.dts/build/usage-report.d.ts +19 -19
- package/dist/.dts/build/usage-report.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/index.d.ts +16 -5
- package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
- package/dist/.dts/evidence/define-projection.d.ts +15 -16
- package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
- package/dist/.dts/evidence/index.d.ts +11 -15
- package/dist/.dts/evidence/index.d.ts.map +1 -1
- package/dist/.dts/helpers/index.d.ts +15 -18
- package/dist/.dts/helpers/index.d.ts.map +1 -1
- package/dist/.dts/helpers/validators.d.ts +2 -2
- package/dist/.dts/helpers/validators.d.ts.map +1 -1
- package/dist/.dts/node/index.d.ts +19 -0
- package/dist/.dts/node/index.d.ts.map +1 -1
- package/dist/.dts/runtime/create.d.ts +6 -3
- package/dist/.dts/runtime/create.d.ts.map +1 -1
- package/dist/.dts/runtime/document.d.ts +91 -97
- package/dist/.dts/runtime/document.d.ts.map +1 -1
- package/dist/.dts/runtime/errors.d.ts +5 -5
- package/dist/.dts/runtime/index.d.ts +11 -10
- package/dist/.dts/runtime/index.d.ts.map +1 -1
- package/dist/.dts/runtime/reset.d.ts +1 -1
- package/dist/.dts/runtime/types.d.ts +39 -24
- package/dist/.dts/runtime/types.d.ts.map +1 -1
- package/dist/.dts/runtime/validate.d.ts +15 -2
- package/dist/.dts/runtime/validate.d.ts.map +1 -1
- package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
- package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/_ipc/display-path.d.ts +27 -0
- package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/_ipc/glob.d.ts +23 -0
- package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/_ipc/typescript.d.ts +20 -0
- package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/assemble-project.d.ts +46 -0
- package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
- package/dist/.dts7/build/change-model.d.ts +63 -0
- package/dist/.dts7/build/change-model.d.ts.map +1 -0
- package/dist/.dts7/build/check-artifacts.d.ts +48 -0
- package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/citation-verification.d.ts +61 -0
- package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
- package/dist/.dts7/build/compatibility.d.ts +83 -0
- package/dist/.dts7/build/compatibility.d.ts.map +1 -0
- package/dist/.dts7/build/compiler-api.d.ts +12 -0
- package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/build/contract-model.d.ts +93 -0
- package/dist/.dts7/build/contract-model.d.ts.map +1 -0
- package/dist/.dts7/build/deep-equal.d.ts +9 -0
- package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
- package/dist/.dts7/build/deep-freeze.d.ts +20 -0
- package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-graph.d.ts +163 -0
- package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-model.d.ts +81 -0
- package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
- package/dist/.dts7/build/discover.d.ts +41 -0
- package/dist/.dts7/build/discover.d.ts.map +1 -0
- package/dist/.dts7/build/display-path.d.ts +6 -0
- package/dist/.dts7/build/display-path.d.ts.map +1 -0
- package/dist/.dts7/build/docs.d.ts +172 -0
- package/dist/.dts7/build/docs.d.ts.map +1 -0
- package/dist/.dts7/build/env-example.d.ts +85 -0
- package/dist/.dts7/build/env-example.d.ts.map +1 -0
- package/dist/.dts7/build/errors.d.ts +78 -0
- package/dist/.dts7/build/errors.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-cache.d.ts +74 -0
- package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-model.d.ts +50 -0
- package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-reference.d.ts +67 -0
- package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts +142 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
- package/dist/.dts7/build/exclusive-group.d.ts +19 -0
- package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
- package/dist/.dts7/build/finding-model.d.ts +80 -0
- package/dist/.dts7/build/finding-model.d.ts.map +1 -0
- package/dist/.dts7/build/generate-documentation.d.ts +176 -0
- package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/generate-evidence.d.ts +77 -0
- package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
- package/dist/.dts7/build/generate-manifest.d.ts +100 -0
- package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
- package/dist/.dts7/build/generate-usage.d.ts +94 -0
- package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
- package/dist/.dts7/build/generated-banner.d.ts +43 -0
- package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/build/glob.d.ts +6 -0
- package/dist/.dts7/build/glob.d.ts.map +1 -0
- package/dist/.dts7/build/governance-fields.d.ts +34 -0
- package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
- package/dist/.dts7/build/humanize-key.d.ts +14 -0
- package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
- package/dist/.dts7/build/index.d.ts +89 -0
- package/dist/.dts7/build/index.d.ts.map +1 -0
- package/dist/.dts7/build/lifecycle-model.d.ts +181 -0
- package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
- package/dist/.dts7/build/link.d.ts +222 -0
- package/dist/.dts7/build/link.d.ts.map +1 -0
- package/dist/.dts7/build/literal-eval.d.ts +24 -0
- package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
- package/dist/.dts7/build/live-expirations.d.ts +48 -0
- package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
- package/dist/.dts7/build/manifest.d.ts +31 -0
- package/dist/.dts7/build/manifest.d.ts.map +1 -0
- package/dist/.dts7/build/map-utils.d.ts +8 -0
- package/dist/.dts7/build/map-utils.d.ts.map +1 -0
- package/dist/.dts7/build/merge-documentation.d.ts +36 -0
- package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/ownership-model.d.ts +58 -0
- package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
- package/dist/.dts7/build/parse.d.ts +206 -0
- package/dist/.dts7/build/parse.d.ts.map +1 -0
- package/dist/.dts7/build/reference-projections.d.ts +168 -0
- package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts +62 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
- package/dist/.dts7/build/sarif.d.ts +66 -0
- package/dist/.dts7/build/sarif.d.ts.map +1 -0
- package/dist/.dts7/build/scan-dependencies.d.ts +71 -0
- package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
- package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
- package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
- package/dist/.dts7/build/source-position.d.ts +69 -0
- package/dist/.dts7/build/source-position.d.ts.map +1 -0
- package/dist/.dts7/build/tool-version.d.ts +8 -0
- package/dist/.dts7/build/tool-version.d.ts.map +1 -0
- package/dist/.dts7/build/types.d.ts +7 -0
- package/dist/.dts7/build/types.d.ts.map +1 -0
- package/dist/.dts7/build/typescript.d.ts +6 -0
- package/dist/.dts7/build/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/usage-report.d.ts +124 -0
- package/dist/.dts7/build/usage-report.d.ts.map +1 -0
- package/dist/.dts7/cli/filesystem.d.ts +7 -0
- package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/index.d.ts +38 -0
- package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
- package/dist/.dts7/evidence/define-projection.d.ts +51 -0
- package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
- package/dist/.dts7/evidence/index.d.ts +19 -0
- package/dist/.dts7/evidence/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/index.d.ts +132 -0
- package/dist/.dts7/helpers/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/processors.d.ts +32 -0
- package/dist/.dts7/helpers/processors.d.ts.map +1 -0
- package/dist/.dts7/helpers/validators.d.ts +68 -0
- package/dist/.dts7/helpers/validators.d.ts.map +1 -0
- package/dist/.dts7/node/index.d.ts +21 -0
- package/dist/.dts7/node/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/cache.d.ts +17 -0
- package/dist/.dts7/runtime/cache.d.ts.map +1 -0
- package/dist/.dts7/runtime/create.d.ts +23 -0
- package/dist/.dts7/runtime/create.d.ts.map +1 -0
- package/dist/.dts7/runtime/document.d.ts +214 -0
- package/dist/.dts7/runtime/document.d.ts.map +1 -0
- package/dist/.dts7/runtime/errors.d.ts +55 -0
- package/dist/.dts7/runtime/errors.d.ts.map +1 -0
- package/dist/.dts7/runtime/index.d.ts +25 -0
- package/dist/.dts7/runtime/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/registry.d.ts +12 -0
- package/dist/.dts7/runtime/registry.d.ts.map +1 -0
- package/dist/.dts7/runtime/reset.d.ts +8 -0
- package/dist/.dts7/runtime/reset.d.ts.map +1 -0
- package/dist/.dts7/runtime/types.d.ts +190 -0
- package/dist/.dts7/runtime/types.d.ts.map +1 -0
- package/dist/.dts7/runtime/validate.d.ts +27 -0
- package/dist/.dts7/runtime/validate.d.ts.map +1 -0
- package/dist/{build-6XFHJFQK.js → build-UEENZEUX.js} +43 -42
- package/dist/build-UEENZEUX.js.map +1 -0
- package/dist/build.cjs +42 -41
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +42 -41
- package/dist/build.js.map +1 -1
- package/dist/build.ts7.d.cts +1 -0
- package/dist/build.ts7.d.ts +1 -0
- package/dist/{chunk-RL5KFVUT.js → chunk-TBL3O7IG.js} +2 -2
- package/dist/cli/index.js +29 -28
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js.map +1 -1
- package/dist/eslint-plugin/index.ts7.d.cts +1 -0
- package/dist/eslint-plugin/index.ts7.d.ts +1 -0
- package/dist/evidence.cjs +1 -1
- package/dist/evidence.cjs.map +1 -1
- package/dist/evidence.js +1 -1
- package/dist/evidence.js.map +1 -1
- package/dist/evidence.ts7.d.cts +1 -0
- package/dist/evidence.ts7.d.ts +1 -0
- package/dist/helpers.cjs +4 -4
- package/dist/helpers.cjs.map +1 -1
- package/dist/helpers.js +4 -4
- package/dist/helpers.js.map +1 -1
- package/dist/helpers.ts7.d.cts +1 -0
- package/dist/helpers.ts7.d.ts +1 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/index.ts7.d.cts +1 -0
- package/dist/index.ts7.d.ts +1 -0
- package/dist/node.ts7.d.cts +1 -0
- package/dist/node.ts7.d.ts +1 -0
- package/examples/README.md +46 -80
- package/package.json +43 -12
- package/schemas/contract-model.schema.json +7 -7
- package/schemas/env-cap-report.schema.json +88 -88
- package/skills/env-cap/SKILL.md +12 -13
- package/skills/env-cap/references/api.md +1 -1
- package/specs/architecture.md +147 -122
- package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
- package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
- package/specs/generated-artifacts.md +91 -71
- package/specs/migrations/README.md +6 -6
- package/specs/migrations/from-centralized-schema.md +1 -1
- package/specs/migrations/from-t3-env.md +9 -9
- package/PROMPT.md +0 -89
- package/dist/build-6XFHJFQK.js.map +0 -1
- /package/dist/{chunk-RL5KFVUT.js.map → chunk-TBL3O7IG.js.map} +0 -0
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The env-cap runtime entry point: declare contracts, validate them once at startup, and read
|
|
3
|
+
* typed values through the contract that owns them.
|
|
4
|
+
*
|
|
5
|
+
* It imports no Node module and reads no Node global; it takes values only from the `values`
|
|
6
|
+
* you pass to `validateEnv()`. `test/runtime/browser-bundle.test.ts` checks the built bundle for
|
|
7
|
+
* Node imports, `process.` and `Buffer.`, but a third-party import would pass unnoticed.
|
|
8
|
+
* Discovery and manifest generation live in `@maverickcer/env-cap/build`, never here.
|
|
9
|
+
*
|
|
10
|
+
* `documentEnv` is exported here, not from `./build`, because it is called inline in the same
|
|
11
|
+
* schema file as `createEnv`, which may end up in any bundle. It must be as cheap to import as
|
|
12
|
+
* `createEnv` (see `document.ts`).
|
|
13
|
+
*
|
|
14
|
+
* @packageDocumentation
|
|
15
|
+
*/
|
|
16
|
+
export type { CreateEnvOptions, DefaultValue, EnvContract, EnvDefinition, EnvSchema, InferEnvValue, Processor, RawEnv, validateEnvOptions, validateEnvResult, Validator, } from "./types.js";
|
|
17
|
+
export { createEnv } from "./create.js";
|
|
18
|
+
export { documentEnv } from "./document.js";
|
|
19
|
+
export type { ContractDocs, VariableDocs, VariableEvidenceDocs } from "./document.js";
|
|
20
|
+
export { EnvNotReadyError, EnvValidationError } from "./errors.js";
|
|
21
|
+
export type { VariableFailure } from "./errors.js";
|
|
22
|
+
export { isEnvContract } from "./registry.js";
|
|
23
|
+
export { resetEnvCache } from "./reset.js";
|
|
24
|
+
export { validateEnv } from "./validate.js";
|
|
25
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACT,MAAM,EACN,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,GACV,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { ContractInternals } from "./types.js";
|
|
2
|
+
/** Associates a contract object with its internal identity/schema. Called once, by `createEnv`. */
|
|
3
|
+
export declare function registerContract(contract: object, internals: ContractInternals): void;
|
|
4
|
+
/**
|
|
5
|
+
* Looks up a contract's internal identity/schema.
|
|
6
|
+
*
|
|
7
|
+
* @throws {TypeError} If `contract` wasn't returned by `createEnv` (and so was never registered).
|
|
8
|
+
*/
|
|
9
|
+
export declare function getContractInternals(contract: object): ContractInternals;
|
|
10
|
+
/** Type guard: `true` when `value` was created by `createEnv` (i.e. is a registered contract). */
|
|
11
|
+
export declare function isEnvContract(value: unknown): value is object;
|
|
12
|
+
//# sourceMappingURL=registry.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/runtime/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAUnD,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAErF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CASxE;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAK7D"}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Clears cached validation state. Intended for tests and dev tooling (e.g.
|
|
3
|
+
* `beforeEach(() => resetEnvCache())` in a test suite that re-validates with
|
|
4
|
+
* different fixture values per test): production applications validate
|
|
5
|
+
* once at startup and should not normally call this.
|
|
6
|
+
*/
|
|
7
|
+
export declare function resetEnvCache(): void;
|
|
8
|
+
//# sourceMappingURL=reset.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"reset.d.ts","sourceRoot":"","sources":["../../../src/runtime/reset.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Core contract types for env-cap.
|
|
3
|
+
*
|
|
4
|
+
* These types are intentionally minimal: an `EnvDefinition` describes how to
|
|
5
|
+
* turn one raw environment value into one typed, validated application
|
|
6
|
+
* value. There is no `optional`/`required` flag anywhere in this file:
|
|
7
|
+
* requiredness is just a validator that rejects `undefined`/empty values.
|
|
8
|
+
*
|
|
9
|
+
* Documentation fields (description, owner, expiresAt, category, ...) live
|
|
10
|
+
* entirely in {@link documentEnv} (see `document.ts`), not here: this file is
|
|
11
|
+
* the runtime's whole vocabulary, and every field in it is read by
|
|
12
|
+
* `validate.ts`/`create.ts`/`errors.ts` at runtime. If a field is only ever
|
|
13
|
+
* read by the generator, it belongs in `document.ts`, not here. `context` is
|
|
14
|
+
* the one exception. The build package also reads it for documentation
|
|
15
|
+
* display (see ADR 0022). It belongs here rather than in `documentEnv()`
|
|
16
|
+
* because `validate.ts` reads it too, to decide pipeline participation: the
|
|
17
|
+
* same bar `default`/`processor`/`validator` already clear.
|
|
18
|
+
*/
|
|
19
|
+
/** The raw, unprocessed source of environment values (e.g. `process.env`, a resolved secrets bag). */
|
|
20
|
+
export type RawEnv = Readonly<Record<string, unknown>>;
|
|
21
|
+
/** Processes a raw value into a typed, ready-to-use application value. Must not read any other key. */
|
|
22
|
+
export type Processor<T> = (value: unknown) => T;
|
|
23
|
+
/**
|
|
24
|
+
* Validates an already-processed value; return `true` when valid, or a human-readable error
|
|
25
|
+
* string when invalid.
|
|
26
|
+
*
|
|
27
|
+
* @remarks
|
|
28
|
+
* Receives the full raw env for conditional validation (e.g. "required only if X").
|
|
29
|
+
*/
|
|
30
|
+
export type Validator<T> = (value: T, rawEnv: RawEnv) => true | string;
|
|
31
|
+
/**
|
|
32
|
+
* A default may be a literal value, or a zero-arg thunk evaluated lazily when the raw value is
|
|
33
|
+
* undefined.
|
|
34
|
+
*
|
|
35
|
+
* @remarks
|
|
36
|
+
* The union is redundant at the type level (`unknown` alone already accepts a
|
|
37
|
+
* function). It's kept because this type is public API: collapsing it to bare `unknown`
|
|
38
|
+
* would erase the one thing a reader of the generated `.d.ts` needs to learn here.
|
|
39
|
+
*/
|
|
40
|
+
export type DefaultValue = unknown | (() => unknown);
|
|
41
|
+
/** Configuration for one schema entry: how to default, process, and validate a single raw environment value. */
|
|
42
|
+
export interface EnvDefinition<T> {
|
|
43
|
+
/** Literal fallback or lazy thunk used when the raw value is `undefined`. */
|
|
44
|
+
default?: DefaultValue;
|
|
45
|
+
/** Converts the raw (or defaulted) value to `T`; passed through unprocessed when omitted. */
|
|
46
|
+
processor?: Processor<T>;
|
|
47
|
+
/** Rejects an invalid processed value; return `true` to accept it. */
|
|
48
|
+
validator?: Validator<T>;
|
|
49
|
+
/**
|
|
50
|
+
* The validation context this variable belongs to (e.g. `"server"`,
|
|
51
|
+
* `"production"`, `"worker"`): entirely application-defined; env-cap
|
|
52
|
+
* never interprets, detects, or infers this string. Omitted (the
|
|
53
|
+
* default) means the variable participates in every {@link validateEnv}
|
|
54
|
+
* run regardless of `activeContexts`. A variable belongs to at most one
|
|
55
|
+
* validation context: see ADR 0022 for why this is a single `string`
|
|
56
|
+
* and not `string[]`. Do not widen it to an array to let one variable
|
|
57
|
+
* join multiple contexts. That reintroduces the AND/OR ambiguity this
|
|
58
|
+
* design deliberately avoids.
|
|
59
|
+
*
|
|
60
|
+
* @remarks
|
|
61
|
+
* Validation contexts are a participation filter only: not
|
|
62
|
+
* authentication, authorization, or a bundling/security boundary. See
|
|
63
|
+
* ADR 0022's Formal Invariants.
|
|
64
|
+
*/
|
|
65
|
+
context?: string;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* A schema is a map of variable name -> definition.
|
|
69
|
+
*
|
|
70
|
+
* @remarks
|
|
71
|
+
* `EnvDefinition<any>` is used only as the generic *bound* here (never surfaced to consumers):
|
|
72
|
+
* TypeScript infers a precise, per-key literal type for `S` from the object passed to
|
|
73
|
+
* {@link createEnv}, so the resolved contract type (see {@link InferEnvValue}) stays fully
|
|
74
|
+
* strict. This is the same variance workaround used by schema libraries like zod/trpc for
|
|
75
|
+
* heterogeneous generic maps.
|
|
76
|
+
*/
|
|
77
|
+
export type EnvSchema = Record<string, EnvDefinition<any>>;
|
|
78
|
+
type UnwrapDefault<D> = D extends {
|
|
79
|
+
default: infer Def;
|
|
80
|
+
} ? Def extends () => infer R ? R : Def : never;
|
|
81
|
+
/**
|
|
82
|
+
* Resolves the application-facing type for one schema entry: processor return type, else the
|
|
83
|
+
* default's type, else `string` (the shape raw process.env values naturally arrive in).
|
|
84
|
+
*
|
|
85
|
+
* @remarks
|
|
86
|
+
* Same documented generic-bound variance workaround as {@link EnvSchema} above:
|
|
87
|
+
* `any` here is never surfaced to a consumer's inferred type.
|
|
88
|
+
*/
|
|
89
|
+
export type InferEnvValue<D extends EnvDefinition<any>> = D extends {
|
|
90
|
+
/** Narrows to the processor's return type when one is present. */
|
|
91
|
+
processor: Processor<infer P>;
|
|
92
|
+
} ? P : [UnwrapDefault<D>] extends [never] ? string : UnwrapDefault<D>;
|
|
93
|
+
/** The internal, non-enumerable identity + metadata attached to every contract created by `createEnv`. */
|
|
94
|
+
export interface ContractInternals<S extends EnvSchema = EnvSchema> {
|
|
95
|
+
readonly id: symbol;
|
|
96
|
+
readonly name: string;
|
|
97
|
+
readonly source: string | undefined;
|
|
98
|
+
readonly schema: S;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* The object returned by {@link createEnv}. Each key is a lazily-resolved getter backed by the
|
|
102
|
+
* runtime cache: there is no global env object, only per-feature contracts like this one.
|
|
103
|
+
*
|
|
104
|
+
* @remarks
|
|
105
|
+
* `toString()` is intersected in (rather than left to the ambient `Object.prototype`
|
|
106
|
+
* declaration) because `create.ts` genuinely overrides it to return a redacted
|
|
107
|
+
* `EnvContract("name")` representation, never resolved values: see ADR 0006. Declaring
|
|
108
|
+
* it here means the type accurately describes what calling `String(contract)` returns.
|
|
109
|
+
*/
|
|
110
|
+
export type EnvContract<S extends EnvSchema> = {
|
|
111
|
+
readonly [K in keyof S]: InferEnvValue<S[K]>;
|
|
112
|
+
} & {
|
|
113
|
+
/** Returns the redacted `EnvContract("name")` representation, never resolved values: see ADR 0006. */
|
|
114
|
+
toString(): string;
|
|
115
|
+
};
|
|
116
|
+
/**
|
|
117
|
+
* What {@link validateEnv} validates: the generated manifest, the raw values, and the active
|
|
118
|
+
* validation contexts.
|
|
119
|
+
*
|
|
120
|
+
* @remarks
|
|
121
|
+
* Only the first call in a process is used; later calls return its outcome, whatever options
|
|
122
|
+
* they pass. Call `resetEnvCache()` between runs in a test.
|
|
123
|
+
*/
|
|
124
|
+
export interface validateEnvOptions {
|
|
125
|
+
/** The raw source of environment values, e.g. `process.env` or a resolved secrets bag. */
|
|
126
|
+
values: RawEnv;
|
|
127
|
+
/**
|
|
128
|
+
* Every contract to validate: typically the `contracts` array imported
|
|
129
|
+
* from a generated manifest (see {@link build.generateEnvManifest}). Pass all of them
|
|
130
|
+
* in one call: {@link validateEnv} only ever initializes once per process, so
|
|
131
|
+
* a second call returns the first call's cached result without
|
|
132
|
+
* re-running anything, even if it passes a different manifest.
|
|
133
|
+
*/
|
|
134
|
+
manifest: readonly EnvContract<any>[];
|
|
135
|
+
/**
|
|
136
|
+
* The validation contexts active for this run (e.g. `["server",
|
|
137
|
+
* "production"]`): entirely application-defined; env-cap never
|
|
138
|
+
* detects or infers these, the caller always computes and passes them
|
|
139
|
+
* explicitly. A variable whose `context` isn't in this list is skipped
|
|
140
|
+
* entirely (no default/processor/validator runs for it, and it stays in
|
|
141
|
+
* its not-ready state, exactly as if this run had never happened for
|
|
142
|
+
* it): see ADR 0022. A variable with no `context` always participates,
|
|
143
|
+
* regardless of what's passed here. Omitted (the default) behaves as an
|
|
144
|
+
* empty list: only variables with no `context` participate.
|
|
145
|
+
*
|
|
146
|
+
* @remarks
|
|
147
|
+
* Not part of the validation cache's identity: {@link validateEnv}
|
|
148
|
+
* remains one-shot per process whatever this option holds. A
|
|
149
|
+
* second call does not re-evaluate `activeContexts`; it returns the
|
|
150
|
+
* first call's result outright. Different active contexts belong to
|
|
151
|
+
* different processes (e.g. a server process and a browser bundle),
|
|
152
|
+
* never to two calls within the same one.
|
|
153
|
+
*/
|
|
154
|
+
activeContexts?: readonly string[];
|
|
155
|
+
}
|
|
156
|
+
/** Aggregate counts from a completed {@link validateEnv} run. */
|
|
157
|
+
export interface validateEnvResult {
|
|
158
|
+
/** Number of contracts in the manifest that were validated. */
|
|
159
|
+
readonly contractCount: number;
|
|
160
|
+
/** Total number of variables validated across all contracts. */
|
|
161
|
+
readonly variableCount: number;
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* Options for {@link createEnv}: a display name for error messages and where the contract was
|
|
165
|
+
* declared.
|
|
166
|
+
*
|
|
167
|
+
* @remarks
|
|
168
|
+
* Purely for identification. Owners, descriptions and other documentation belong in
|
|
169
|
+
* `documentEnv()`.
|
|
170
|
+
*/
|
|
171
|
+
export interface CreateEnvOptions {
|
|
172
|
+
/**
|
|
173
|
+
* A short, stable label for this contract (e.g. "payments", "database").
|
|
174
|
+
* Used in error messages. Defaults to an auto-generated anonymous label if
|
|
175
|
+
* omitted: providing one is strongly recommended for readable validation
|
|
176
|
+
* errors.
|
|
177
|
+
*/
|
|
178
|
+
name?: string;
|
|
179
|
+
/**
|
|
180
|
+
* Pass `import.meta.url` here so validation errors point at the file that
|
|
181
|
+
* declared the failing variable (e.g. "features/payments/env.schema.ts")
|
|
182
|
+
* instead of just the short `name` label. There is no portable way for
|
|
183
|
+
* `createEnv` to discover its caller's module URL on its own: this is
|
|
184
|
+
* always correct and never goes stale, since it's supplied by the JS
|
|
185
|
+
* engine rather than hand-typed.
|
|
186
|
+
*/
|
|
187
|
+
source?: string;
|
|
188
|
+
}
|
|
189
|
+
export {};
|
|
190
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/runtime/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,sGAAsG;AACtG,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAEtD,uGAAuG;AACvG,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAA;AAEhD;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAA;AAEtE;;;;;;;;GAQG;AAEH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAA;AAEpD,gHAAgH;AAChH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACxB,sEAAsE;IACtE,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACxB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;GASG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAA;AAE1D,KAAK,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,GAAG,CAAA;CAAE,GACpD,GAAG,SAAS,MAAM,MAAM,CAAC,GACvB,CAAC,GACD,GAAG,GACL,KAAK,CAAA;AAET;;;;;;;GAOG;AAEH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS;IAClE,kEAAkE;IAClE,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAA;CAC9B,GACG,CAAC,GACD,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAChC,MAAM,GACN,aAAa,CAAC,CAAC,CAAC,CAAA;AAEtB,0GAA0G;AAC1G,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAChE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,SAAS,IAAI;IAC7C,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7C,GAAG;IACF,sGAAsG;IACtG,QAAQ,IAAI,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IAEH,QAAQ,EAAE,SAAS,WAAW,CAAC,GAAG,CAAC,EAAE,CAAA;IACrC;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB"}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import type { validateEnvOptions, validateEnvResult } from "./types.js";
|
|
2
|
+
/**
|
|
3
|
+
* Validates every variable in every contract in `options.manifest` against
|
|
4
|
+
* `options.values`, then caches the results.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Idempotent: the first successful (or failed) call is authoritative for the life of the
|
|
8
|
+
* process; later calls return (or re-throw) that same outcome without re-running any
|
|
9
|
+
* processor or validator. Concurrent in-flight calls share one underlying run. Call
|
|
10
|
+
* `resetEnvCache()` to validate again, for example between test scenarios.
|
|
11
|
+
*
|
|
12
|
+
* The record of validated values is frozen, but only one level deep: an object, array or `URL`
|
|
13
|
+
* a processor returns stays mutable. A failure message carries variable and contract names and
|
|
14
|
+
* the message your processor or validator produced, never the value itself.
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```ts
|
|
18
|
+
* import { validateEnv } from "@maverickcer/env-cap"
|
|
19
|
+
* import { manifest } from "./generated/env.manifest"
|
|
20
|
+
*
|
|
21
|
+
* await validateEnv({ manifest, values: process.env })
|
|
22
|
+
* ```
|
|
23
|
+
*
|
|
24
|
+
* @throws {EnvValidationError} If any variable fails processing or validation.
|
|
25
|
+
*/
|
|
26
|
+
export declare function validateEnv(options: validateEnvOptions): Promise<validateEnvResult>;
|
|
27
|
+
//# sourceMappingURL=validate.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/runtime/validate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEvE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0BzF"}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import {
|
|
3
3
|
readToolVersion
|
|
4
|
-
} from "./chunk-
|
|
4
|
+
} from "./chunk-TBL3O7IG.js";
|
|
5
5
|
|
|
6
6
|
// src/build/evidence-snapshot.ts
|
|
7
7
|
import path3 from "path";
|
|
@@ -393,7 +393,7 @@ async function discoverSchemaFiles(options) {
|
|
|
393
393
|
const included = await discoverFiles(options);
|
|
394
394
|
if (included.length > MAX_DISCOVERED_SCHEMA_FILES) {
|
|
395
395
|
throw new Error(
|
|
396
|
-
`discoverSchemaFiles: found ${String(included.length)} files matching "include" under ${options.root}
|
|
396
|
+
`discoverSchemaFiles: found ${String(included.length)} files matching "include" under ${options.root}, more than the ${String(MAX_DISCOVERED_SCHEMA_FILES)}-file sanity limit. This usually means "root" (or "include"/"exclude") resolved more broadly than intended, for example an omitted "root" falling back to a large process.cwd(). Narrow "root"/"include"/"exclude" to the intended project boundary.`
|
|
397
397
|
);
|
|
398
398
|
}
|
|
399
399
|
return included;
|
|
@@ -672,7 +672,7 @@ function extractSchemaVariable(key, definition, filePath, contextLabel, warnings
|
|
|
672
672
|
} else {
|
|
673
673
|
warnings.push({
|
|
674
674
|
file: filePath,
|
|
675
|
-
message: evaluated.ok && evaluated.value === "" ? `"context" for "${key}" in "${contextLabel}" is an empty string; ignoring it
|
|
675
|
+
message: evaluated.ok && evaluated.value === "" ? `"context" for "${key}" in "${contextLabel}" is an empty string; ignoring it. Validation contexts must be non-empty.` : `"context" for "${key}" in "${contextLabel}" is not a statically-resolvable string literal; ignoring it.`
|
|
676
676
|
});
|
|
677
677
|
}
|
|
678
678
|
}
|
|
@@ -1146,7 +1146,7 @@ function resolveWithinRoot(root, location, optionName, functionName) {
|
|
|
1146
1146
|
severity: "error",
|
|
1147
1147
|
variable: optionName,
|
|
1148
1148
|
files: [location],
|
|
1149
|
-
reason: `"${optionName}" ("${location}") resolves to "${resolved}", which is outside "root" ("${root}"). ${functionName}() refuses to write outside root
|
|
1149
|
+
reason: `"${optionName}" ("${location}") resolves to "${resolved}", which is outside "root" ("${root}"). ${functionName}() refuses to write outside root. Use a path nested under root instead.`
|
|
1150
1150
|
}
|
|
1151
1151
|
};
|
|
1152
1152
|
}
|
|
@@ -1195,7 +1195,7 @@ async function resolveUncached(packageName, root, fs) {
|
|
|
1195
1195
|
return {
|
|
1196
1196
|
ok: false,
|
|
1197
1197
|
code: "PACKAGE_NOT_FOUND",
|
|
1198
|
-
reason: `Package "${packageName}" listed in "packages" could not be resolved from "${root}"
|
|
1198
|
+
reason: `Package "${packageName}" listed in "packages" could not be resolved from "${root}". Is it installed?`
|
|
1199
1199
|
};
|
|
1200
1200
|
}
|
|
1201
1201
|
const { packageJsonPath, packageDir } = located;
|
|
@@ -1793,7 +1793,7 @@ function buildChangeModel(manifest, currentContracts, root) {
|
|
|
1793
1793
|
file: addedRef.file,
|
|
1794
1794
|
exportName: addedRef.exportName,
|
|
1795
1795
|
// Resolved from the contract this rename was declared on, not carried
|
|
1796
|
-
// on the ref
|
|
1796
|
+
// on the ref: see `ContractRef` (`evidence-reference.ts`).
|
|
1797
1797
|
contractName: contract.contractName,
|
|
1798
1798
|
previousKey: removedRef.key,
|
|
1799
1799
|
currentKey: addedRef.key
|
|
@@ -1853,7 +1853,7 @@ function detectCompatibilityIssues(contracts) {
|
|
|
1853
1853
|
variable: key,
|
|
1854
1854
|
files: [a.file, b.file],
|
|
1855
1855
|
code: "PROCESSOR_SOURCE_CONFLICT",
|
|
1856
|
-
reason: `"${a.contractName}" and "${b.contractName}" both declare a processor for this variable with different implementations. Return types could not be statically verified
|
|
1856
|
+
reason: `"${a.contractName}" and "${b.contractName}" both declare a processor for this variable with different implementations. Return types could not be statically verified. Add explicit return type annotations, or confirm they produce equivalent output.`
|
|
1857
1857
|
});
|
|
1858
1858
|
}
|
|
1859
1859
|
if (a.variable.hasValidator && b.variable.hasValidator && a.variable.validatorSource !== b.variable.validatorSource) {
|
|
@@ -1862,7 +1862,7 @@ function detectCompatibilityIssues(contracts) {
|
|
|
1862
1862
|
variable: key,
|
|
1863
1863
|
files: [a.file, b.file],
|
|
1864
1864
|
code: "VALIDATOR_SOURCE_CONFLICT",
|
|
1865
|
-
reason: `"${a.contractName}" and "${b.contractName}" both declare a validator for this variable with different implementations. Validator logic cannot be statically compared
|
|
1865
|
+
reason: `"${a.contractName}" and "${b.contractName}" both declare a validator for this variable with different implementations. Validator logic cannot be statically compared. Confirm they enforce compatible rules.`
|
|
1866
1866
|
});
|
|
1867
1867
|
}
|
|
1868
1868
|
const divergences = documentationDivergences(a.variable, b.variable);
|
|
@@ -1923,7 +1923,7 @@ function detectDuplicateVariableShapes(contracts) {
|
|
|
1923
1923
|
variable: `${a.key} / ${b.key}`,
|
|
1924
1924
|
files: [a.file, b.file],
|
|
1925
1925
|
code: "DUPLICATE_VARIABLE_SHAPE_ACROSS_CONTRACTS",
|
|
1926
|
-
reason: `"${a.key}" (${a.contractName}) and "${b.key}" (${b.contractName}) declare an identical shape (type ${a.shape.valueType}, processor: ${a.shape.hasProcessor ? "yes" : "no"}, validator: ${a.shape.hasValidator ? "yes" : "no"}). Informational only
|
|
1926
|
+
reason: `"${a.key}" (${a.contractName}) and "${b.key}" (${b.contractName}) declare an identical shape (type ${a.shape.valueType}, processor: ${a.shape.hasProcessor ? "yes" : "no"}, validator: ${a.shape.hasValidator ? "yes" : "no"}). Informational only: they may be the same underlying value modelled twice, or two unrelated values that happen to look alike. Nothing is required.`
|
|
1927
1927
|
});
|
|
1928
1928
|
}
|
|
1929
1929
|
}
|
|
@@ -2147,11 +2147,9 @@ function scanFileForDependencies(filePath, sourceText) {
|
|
|
2147
2147
|
filePath,
|
|
2148
2148
|
sourceText,
|
|
2149
2149
|
ts.ScriptTarget.Latest,
|
|
2150
|
-
// Load-bearing
|
|
2151
|
-
// a `const` declaration
|
|
2152
|
-
// candidates
|
|
2153
|
-
// now breaks const-detection silently rather than merely being an
|
|
2154
|
-
// unobserved no-op -- do not remove parent-pointer tracking here.
|
|
2150
|
+
// Load-bearing: `ts.getCombinedNodeFlags()` walks parent pointers. It
|
|
2151
|
+
// tells a `const` declaration from `let`/`var` when resolving alias
|
|
2152
|
+
// candidates. Setting this to `false` breaks const-detection silently.
|
|
2155
2153
|
true,
|
|
2156
2154
|
scriptKind
|
|
2157
2155
|
);
|
|
@@ -2264,8 +2262,8 @@ function createGeneratedBanner(describe) {
|
|
|
2264
2262
|
return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
|
|
2265
2263
|
},
|
|
2266
2264
|
// Not a bare `startsWith`: a shebang, a `"use strict"` pragma or a license header pushes a real marker
|
|
2267
|
-
// off line one
|
|
2268
|
-
//
|
|
2265
|
+
// off line one. A stricter check would read a genuinely generated file as hand-written. A dependency
|
|
2266
|
+
// scan would take that as "a real consumer imports this", and so permanently mask an abandoned
|
|
2269
2267
|
// contract. The first 20 non-empty lines clear every realistic preamble without scanning a whole file.
|
|
2270
2268
|
// A line counts only when the marker opens a comment, as `generatedBanner` writes it, so code or prose that
|
|
2271
2269
|
// merely quotes the marker is not mistaken for a generated file.
|
|
@@ -2473,7 +2471,7 @@ function deriveOwnershipFindings(graph) {
|
|
|
2473
2471
|
if (contract.ambiguousBarrelFiles.length > 0) {
|
|
2474
2472
|
unresolvedConsumers.push({
|
|
2475
2473
|
...identity,
|
|
2476
|
-
reason: `Not directly imported anywhere, but ${contract.ambiguousBarrelFiles.length} file(s) import "${contract.exportName}" through a specifier that resolves to a file containing an unresolved "export * from" re-export
|
|
2474
|
+
reason: `Not directly imported anywhere, but ${contract.ambiguousBarrelFiles.length} file(s) import "${contract.exportName}" through a specifier that resolves to a file containing an unresolved "export * from" re-export, so whether this contract is forwarded by it cannot be determined. Files: ${contract.ambiguousBarrelFiles.join(", ")}.`
|
|
2477
2475
|
});
|
|
2478
2476
|
} else {
|
|
2479
2477
|
abandoned.push(identity);
|
|
@@ -2495,7 +2493,7 @@ function deriveOwnershipFindings(graph) {
|
|
|
2495
2493
|
if (info.status === "unconsumed") {
|
|
2496
2494
|
unconsumedOwned.push({ ...identity, key });
|
|
2497
2495
|
} else if (info.status === "indeterminate") {
|
|
2498
|
-
const reason = info.evidence === "dynamic-access" ? `Dynamic (computed) property access was observed on "${contract.exportName}"
|
|
2496
|
+
const reason = info.evidence === "dynamic-access" ? `Dynamic (computed) property access was observed on "${contract.exportName}", so whether "${key}" is read cannot be determined. Searched: ${surfaces}. Dynamic access observed at: ${formatSites(contract.dynamicAccessSites)}.` : `Contract "${contract.exportName}" is used in a way this scanner's local dataflow analysis cannot follow (a rest binding, nested destructuring, a computed key, an ambiguous alias, or the contract passed/referenced directly), so whether "${key}" is read cannot be determined. Searched: ${surfaces}. Escaped at: ${formatEscapeSites(contract.escapeSites)}.`;
|
|
2499
2497
|
indeterminate.push({
|
|
2500
2498
|
...identity,
|
|
2501
2499
|
key,
|
|
@@ -2672,7 +2670,7 @@ function detectExclusiveGroupIssues(contracts) {
|
|
|
2672
2670
|
severity: "error",
|
|
2673
2671
|
variable: `Exclusive group "${group}"`,
|
|
2674
2672
|
files: [a.file, b.file],
|
|
2675
|
-
reason: `"${a.contractName}" and "${b.contractName}" are both active and both declare exclusiveGroup "${group}"
|
|
2673
|
+
reason: `"${a.contractName}" and "${b.contractName}" are both active and both declare exclusiveGroup "${group}". Only one active contract per exclusive group is allowed. Set active: false on whichever one isn't in use.`
|
|
2676
2674
|
});
|
|
2677
2675
|
}
|
|
2678
2676
|
}
|
|
@@ -2748,11 +2746,11 @@ function defaultExclude() {
|
|
|
2748
2746
|
return [
|
|
2749
2747
|
// `discoverSchemaFiles()`'s own walk (`discover.ts`) hardcodes skipping
|
|
2750
2748
|
// a directory literally named "node_modules" or ".git" via its own
|
|
2751
|
-
// `isAlwaysSkippedDirName()` check, regardless of `exclude
|
|
2749
|
+
// `isAlwaysSkippedDirName()` check, regardless of `exclude`: it never
|
|
2752
2750
|
// even descends into either to test a glob pattern against it. These
|
|
2753
2751
|
// two entries are provably redundant (kept for readers/tooling that
|
|
2754
2752
|
// inspect `exclude` directly, and as defense if that hardcoding ever
|
|
2755
|
-
// changes)
|
|
2753
|
+
// changes). Hand-verified: emptying both and running the full
|
|
2756
2754
|
// `vitest run` leaves all 1243 tests passing.
|
|
2757
2755
|
"**/node_modules/**",
|
|
2758
2756
|
"**/dist/**",
|
|
@@ -2843,7 +2841,7 @@ function renderAbandoned(findings) {
|
|
|
2843
2841
|
const lines = [
|
|
2844
2842
|
"## Abandoned ownership",
|
|
2845
2843
|
"",
|
|
2846
|
-
"Contracts never imported anywhere in the scanned repository
|
|
2844
|
+
"Contracts never imported anywhere in the scanned repository: a feature's schema outliving the feature.",
|
|
2847
2845
|
"",
|
|
2848
2846
|
"| Contract | Owner | File |",
|
|
2849
2847
|
"|---|---|---|"
|
|
@@ -2858,7 +2856,7 @@ function renderUnresolvedConsumers(findings) {
|
|
|
2858
2856
|
const lines = [
|
|
2859
2857
|
"## Unresolved consumers (barrel re-exports)",
|
|
2860
2858
|
"",
|
|
2861
|
-
"Contracts reachable only through an unresolved `export * from` barrel re-export
|
|
2859
|
+
"Contracts reachable only through an unresolved `export * from` barrel re-export. They cannot be proven abandoned or consumed. Advisory only; never fails a build.",
|
|
2862
2860
|
""
|
|
2863
2861
|
];
|
|
2864
2862
|
for (const f of sortedByContractName(findings))
|
|
@@ -2880,7 +2878,7 @@ function renderUnconsumedOwned(findings, scannedSurfaces) {
|
|
|
2880
2878
|
"",
|
|
2881
2879
|
`Searched: ${surfaces}.`,
|
|
2882
2880
|
"",
|
|
2883
|
-
'A blank Stale/missing citations cell is the strongest "looks
|
|
2881
|
+
'A blank Stale/missing citations cell is the strongest "looks unused" signal: no developer has ever claimed otherwise. A non-blank cell means someone specifically claimed dynamic access here via `dynamicAccess`, and that claim can no longer be verified (ADR 0037). Check with them before deleting.',
|
|
2884
2882
|
"",
|
|
2885
2883
|
"| Variable | Contract | Owner | Stale/missing citations |",
|
|
2886
2884
|
"|---|---|---|---|"
|
|
@@ -2897,7 +2895,7 @@ function renderIndeterminate(findings) {
|
|
|
2897
2895
|
const lines = [
|
|
2898
2896
|
"## Indeterminate (dynamic access)",
|
|
2899
2897
|
"",
|
|
2900
|
-
"Dynamic (computed) property access was observed
|
|
2898
|
+
"Dynamic (computed) property access was observed, so usage cannot be determined statically. Never guessed at.",
|
|
2901
2899
|
"",
|
|
2902
2900
|
"| Variable | Contract | Reason | Stale/missing citations |",
|
|
2903
2901
|
"|---|---|---|---|"
|
|
@@ -2918,7 +2916,7 @@ function renderAsserted(findings) {
|
|
|
2918
2916
|
const lines = [
|
|
2919
2917
|
"## Asserted (developer-acknowledged dynamic access)",
|
|
2920
2918
|
"",
|
|
2921
|
-
"Variables env-cap's own scan would otherwise flag as unconsumed or indeterminate, but a developer has cited exactly where the dynamic access happens via `dynamicAccess`. The raw static status is shown alongside the citation, never hidden behind it
|
|
2919
|
+
"Variables env-cap's own scan would otherwise flag as unconsumed or indeterminate, but a developer has cited exactly where the dynamic access happens via `dynamicAccess`. The raw static status is shown alongside the citation, never hidden behind it. A citation is a re-acknowledgment, not proof.",
|
|
2922
2920
|
"",
|
|
2923
2921
|
"| Variable | Contract | Static status | Developer assertion |",
|
|
2924
2922
|
"|---|---|---|---|"
|
|
@@ -3255,7 +3253,7 @@ function buildFindingModel(input) {
|
|
|
3255
3253
|
severity: "info",
|
|
3256
3254
|
code: "NONSTANDARD_SENSITIVITY_LEVEL",
|
|
3257
3255
|
family: "documentation",
|
|
3258
|
-
message: `"${n.key ?? n.exportName}" declares sensitivity "${n.sensitivity}", which isn't one of the standard levels (secret/credential/pii/config)
|
|
3256
|
+
message: `"${n.key ?? n.exportName}" declares sensitivity "${n.sensitivity}", which isn't one of the standard levels (secret/credential/pii/config). It is still honored verbatim, only flagged for vocabulary drift.`,
|
|
3259
3257
|
location: {
|
|
3260
3258
|
model: "contract",
|
|
3261
3259
|
file: displayPath(root, n.file),
|
|
@@ -3339,7 +3337,7 @@ function buildFindingModel(input) {
|
|
|
3339
3337
|
contractName: i.contractName,
|
|
3340
3338
|
file: void 0,
|
|
3341
3339
|
variable: i.key,
|
|
3342
|
-
// Multiple candidate sites, never one representative pointer
|
|
3340
|
+
// Multiple candidate sites, never one representative pointer: see
|
|
3343
3341
|
// `IndeterminateOwnershipFinding.dynamicAccessSites` for the full list.
|
|
3344
3342
|
position: NO_POSITION
|
|
3345
3343
|
}
|
|
@@ -3356,12 +3354,12 @@ function buildFindingModel(input) {
|
|
|
3356
3354
|
model: "ownership",
|
|
3357
3355
|
contractName: p.contractName,
|
|
3358
3356
|
// p.file (DynamicAccessCitationProblem.file) is already
|
|
3359
|
-
// root-relative
|
|
3360
|
-
// absolute path
|
|
3357
|
+
// root-relative (unlike every other .file above, not a raw
|
|
3358
|
+
// absolute path) so no displayPath() conversion here.
|
|
3361
3359
|
file: p.file,
|
|
3362
3360
|
variable: p.key,
|
|
3363
3361
|
// The one ownership-family finding with a genuinely meaningful
|
|
3364
|
-
// position
|
|
3362
|
+
// position: exactly where the (now-stale/missing) citation points.
|
|
3365
3363
|
position: p.position
|
|
3366
3364
|
}
|
|
3367
3365
|
});
|
|
@@ -3401,7 +3399,7 @@ function defineEvidenceProjection(schema) {
|
|
|
3401
3399
|
}
|
|
3402
3400
|
function readOnlyMembraneError() {
|
|
3403
3401
|
return new TypeError(
|
|
3404
|
-
"EvidenceModel is read-only inside a projector
|
|
3402
|
+
"EvidenceModel is read-only inside a projector. A projection must be a pure function of its evidence argument. See ADR 0032."
|
|
3405
3403
|
);
|
|
3406
3404
|
}
|
|
3407
3405
|
function createTrackingProxy(evidence) {
|
|
@@ -4137,7 +4135,7 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
|
|
|
4137
4135
|
lines.push(
|
|
4138
4136
|
...renderVariableLines(dup.variable, {
|
|
4139
4137
|
commented: true,
|
|
4140
|
-
note: `Also declared by "${dup.contract.contractName}"
|
|
4138
|
+
note: `Also declared by "${dup.contract.contractName}". See "${first.contract.contractName}" above.`
|
|
4141
4139
|
})
|
|
4142
4140
|
);
|
|
4143
4141
|
}
|
|
@@ -4149,7 +4147,7 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
|
|
|
4149
4147
|
lines.push(
|
|
4150
4148
|
...renderVariableLines(first.variable, {
|
|
4151
4149
|
commented: true,
|
|
4152
|
-
note: `Disabled
|
|
4150
|
+
note: `Disabled: feature "${first.contract.contractName}" is not active.`
|
|
4153
4151
|
})
|
|
4154
4152
|
);
|
|
4155
4153
|
}
|
|
@@ -5063,7 +5061,7 @@ async function checkEnvArtifacts(options) {
|
|
|
5063
5061
|
path: c.docs.envExamplePath,
|
|
5064
5062
|
status: driftCount > 0 ? "stale" : "ok",
|
|
5065
5063
|
// exactOptionalPropertyTypes: omit the key entirely rather than
|
|
5066
|
-
// set it to `undefined
|
|
5064
|
+
// set it to `undefined`; `detail` is absent when there's
|
|
5067
5065
|
// nothing to report, not present-but-empty.
|
|
5068
5066
|
...driftCount > 0 ? {
|
|
5069
5067
|
detail: `${staleVariables.length} stale, ${variablesToComment.length} to comment, ${variablesToAdd.length} to add`
|
|
@@ -5098,15 +5096,18 @@ async function checkEnvArtifacts(options) {
|
|
|
5098
5096
|
function sarifLevel(severity) {
|
|
5099
5097
|
return severity === "info" ? "note" : severity;
|
|
5100
5098
|
}
|
|
5099
|
+
function uriReference(file) {
|
|
5100
|
+
return encodeURI(file).replace(/#/g, "%23").replace(/\?/g, "%3F");
|
|
5101
|
+
}
|
|
5101
5102
|
function sarifLocations(finding) {
|
|
5102
5103
|
const location = finding.location;
|
|
5103
|
-
const uri = location.model === "change" ? location.path : location.file;
|
|
5104
|
-
if (uri === void 0) return void 0;
|
|
5105
5104
|
const { position } = location;
|
|
5105
|
+
const file = position?.file ?? (location.model === "change" ? location.path : location.file);
|
|
5106
|
+
if (file === void 0) return void 0;
|
|
5106
5107
|
return [
|
|
5107
5108
|
{
|
|
5108
5109
|
physicalLocation: {
|
|
5109
|
-
artifactLocation: { uri },
|
|
5110
|
+
artifactLocation: { uri: uriReference(file) },
|
|
5110
5111
|
...position === void 0 ? {} : { region: { startLine: position.line, startColumn: position.column } }
|
|
5111
5112
|
}
|
|
5112
5113
|
}
|
|
@@ -5127,9 +5128,9 @@ function buildSarifLog(findingModel) {
|
|
|
5127
5128
|
rules: ruleIds.map((id) => ({ id }))
|
|
5128
5129
|
}
|
|
5129
5130
|
},
|
|
5130
|
-
//
|
|
5131
|
-
//
|
|
5132
|
-
//
|
|
5131
|
+
// Under `exactOptionalPropertyTypes` the key must be absent, never
|
|
5132
|
+
// `undefined`. So `locations` is spread in only when
|
|
5133
|
+
// `sarifLocations()` has one.
|
|
5133
5134
|
results: findingModel.findings.map((finding) => {
|
|
5134
5135
|
const locations = sarifLocations(finding);
|
|
5135
5136
|
return {
|
|
@@ -5205,4 +5206,4 @@ export {
|
|
|
5205
5206
|
resolveRelativeImport,
|
|
5206
5207
|
writeEnvExample
|
|
5207
5208
|
};
|
|
5208
|
-
//# sourceMappingURL=build-
|
|
5209
|
+
//# sourceMappingURL=build-UEENZEUX.js.map
|