@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,206 @@
|
|
|
1
|
+
import type TS from "@typescript/typescript6";
|
|
2
|
+
import type { EnvGovernanceFields } from "./governance-fields.js";
|
|
3
|
+
import type { SourcePosition } from "./source-position.js";
|
|
4
|
+
/** A recoverable issue found while statically parsing or linking one schema file: never fatal, always surfaced to the caller as data. */
|
|
5
|
+
export interface ParseWarning {
|
|
6
|
+
/** Absolute path of the file the warning applies to. */
|
|
7
|
+
readonly file: string;
|
|
8
|
+
/** Human-readable explanation of what was skipped and why. */
|
|
9
|
+
readonly message: string;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* How a `createEnv`/`documentEnv` call's first argument resolves, before any
|
|
13
|
+
* cross-file linking is attempted. Linking is `link.ts`'s job; this module
|
|
14
|
+
* only ever looks at one file's own AST.
|
|
15
|
+
*/
|
|
16
|
+
export type SchemaRef = {
|
|
17
|
+
/** Discriminant: the schema argument is an inline object literal. */
|
|
18
|
+
readonly kind: "literal";
|
|
19
|
+
/** The object literal AST node itself. */
|
|
20
|
+
readonly node: TS.ObjectLiteralExpression;
|
|
21
|
+
} | {
|
|
22
|
+
/** Discriminant: the schema argument is a bare identifier referencing a local `const`. */
|
|
23
|
+
readonly kind: "identifier";
|
|
24
|
+
/** The referenced identifier's name, not yet resolved to a declaration. */
|
|
25
|
+
readonly name: string;
|
|
26
|
+
} | {
|
|
27
|
+
/** Discriminant: the schema argument isn't statically resolvable (not a literal or identifier). */
|
|
28
|
+
readonly kind: "unresolvable";
|
|
29
|
+
};
|
|
30
|
+
/** One `createEnv(...)` call site, as found by {@link parseSchemaFile}, before cross-file linking. */
|
|
31
|
+
interface RawCreateEnvCall {
|
|
32
|
+
/** The binding name the call result is assigned to (must be exported to be usable: see {@link parseSchemaFile}). */
|
|
33
|
+
readonly exportName: string;
|
|
34
|
+
/** How the first (schema) argument resolves within this file. */
|
|
35
|
+
readonly schemaRef: SchemaRef;
|
|
36
|
+
/** The second (options) argument expression, if the call passes one. */
|
|
37
|
+
readonly optionsArg: TS.Expression | undefined;
|
|
38
|
+
/** The full call expression AST node. */
|
|
39
|
+
readonly node: TS.CallExpression;
|
|
40
|
+
}
|
|
41
|
+
/** One `documentEnv(...)` call site, as found by {@link parseSchemaFile}, before cross-file linking. */
|
|
42
|
+
interface RawDocumentEnvCall {
|
|
43
|
+
/** How the first (schema) argument resolves within this file. */
|
|
44
|
+
readonly schemaRef: SchemaRef;
|
|
45
|
+
/** The second (docs) argument expression, if the call passes one. */
|
|
46
|
+
readonly docsArg: TS.Expression | undefined;
|
|
47
|
+
/** The full call expression AST node. */
|
|
48
|
+
readonly node: TS.CallExpression;
|
|
49
|
+
}
|
|
50
|
+
/** One named import binding, tracked only for relative specifiers (see {@link FileParseResult.imports}). */
|
|
51
|
+
export interface ImportBinding {
|
|
52
|
+
/** The raw module specifier as written in the import (e.g. `"./payments.schema.js"`). */
|
|
53
|
+
readonly specifier: string;
|
|
54
|
+
/** The name as exported by the source module: accounts for `import { real as local }`. */
|
|
55
|
+
readonly importedName: string;
|
|
56
|
+
}
|
|
57
|
+
/** The raw, single-file facts extracted by {@link parseSchemaFile}. */
|
|
58
|
+
export interface FileParseResult {
|
|
59
|
+
/** Absolute path of the parsed file. */
|
|
60
|
+
readonly file: string;
|
|
61
|
+
/** The TypeScript AST for this file, reused by callers that need to inspect it further. */
|
|
62
|
+
readonly sourceFile: TS.SourceFile;
|
|
63
|
+
/** Top-level `const NAME = {...}` object-literal declarations, whether exported or not. */
|
|
64
|
+
readonly localConsts: ReadonlyMap<string, TS.ObjectLiteralExpression>;
|
|
65
|
+
/** Names of top-level `const` declarations that are exported (a subset of {@link localConsts}'s keys, plus non-object-literal exports). */
|
|
66
|
+
readonly exportedConstNames: ReadonlySet<string>;
|
|
67
|
+
/** Local binding name -> where it came from. Only named imports of a relative specifier are tracked (namespace/default/bare-package imports are irrelevant to schema linking). */
|
|
68
|
+
readonly imports: ReadonlyMap<string, ImportBinding>;
|
|
69
|
+
/** Every `createEnv(...)` call site found at the top level of this file. */
|
|
70
|
+
readonly createEnvCalls: readonly RawCreateEnvCall[];
|
|
71
|
+
/** Every `documentEnv(...)` call site found at the top level of this file. */
|
|
72
|
+
readonly documentEnvCalls: readonly RawDocumentEnvCall[];
|
|
73
|
+
/** Recoverable issues found while parsing this file. */
|
|
74
|
+
readonly warnings: readonly ParseWarning[];
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Structurally parses one file's AST for everything the generator needs. That
|
|
78
|
+
* is the `createEnv(...)`/`documentEnv(...)` call sites, plus the local
|
|
79
|
+
* `const` declarations and imports that resolve an identifier passed to
|
|
80
|
+
* either.
|
|
81
|
+
*
|
|
82
|
+
* @remarks
|
|
83
|
+
* Never type-checks or executes the file: see `link.ts` for how
|
|
84
|
+
* these raw facts get resolved into actual schema/docs data, including
|
|
85
|
+
* across files.
|
|
86
|
+
*/
|
|
87
|
+
export declare function parseSchemaFile(filePath: string, sourceText: string): FileParseResult;
|
|
88
|
+
/**
|
|
89
|
+
* Collects named import bindings from one `import` statement into `imports`, keyed by local name.
|
|
90
|
+
*
|
|
91
|
+
* @remarks
|
|
92
|
+
* Exported for reuse by `scan-dependencies.ts`. It needs the same
|
|
93
|
+
* alias-aware named-import tracking this file does for schema linking. It
|
|
94
|
+
* applies it to arbitrary application source instead of schema files.
|
|
95
|
+
*
|
|
96
|
+
* @param imports - Mutated in place; a binding re-collected under the same local name overwrites the previous entry.
|
|
97
|
+
*/
|
|
98
|
+
export declare function collectImportBindings(statement: TS.ImportDeclaration, imports: Map<string, ImportBinding>): void;
|
|
99
|
+
/** One schema entry's statically-discoverable shape: presence facts, never evaluated/executed values. */
|
|
100
|
+
export interface DiscoveredSchemaVariable {
|
|
101
|
+
/** The environment variable name (the schema's object key). */
|
|
102
|
+
readonly key: string;
|
|
103
|
+
/** Whether the entry declares a `default`. */
|
|
104
|
+
readonly hasDefault: boolean;
|
|
105
|
+
/** The default's statically-evaluated literal value, if `hasDefault` and it was a literal we could evaluate: `{ ok: false }` when present but not statically resolvable, `undefined` when absent. */
|
|
106
|
+
readonly defaultValue: {
|
|
107
|
+
/** Always `true` in this branch. */
|
|
108
|
+
ok: true;
|
|
109
|
+
/** The evaluated literal value. */
|
|
110
|
+
value: unknown;
|
|
111
|
+
} | {
|
|
112
|
+
/** Always `false` in this branch: present but not statically resolvable. */
|
|
113
|
+
ok: false;
|
|
114
|
+
} | undefined;
|
|
115
|
+
/** Whether the entry declares a `processor`. */
|
|
116
|
+
readonly hasProcessor: boolean;
|
|
117
|
+
/** The processor function's source text, normalized to single-line, if `hasProcessor`. */
|
|
118
|
+
readonly processorSource: string | undefined;
|
|
119
|
+
/** Only present when the processor has an explicit `: T` return type annotation: the one thing we treat as provable. */
|
|
120
|
+
readonly processorReturnType: string | undefined;
|
|
121
|
+
/** Whether the entry declares a `validator`. */
|
|
122
|
+
readonly hasValidator: boolean;
|
|
123
|
+
/** The validator function's source text, normalized to single-line, if `hasValidator`. */
|
|
124
|
+
readonly validatorSource: string | undefined;
|
|
125
|
+
/** The variable's statically-resolved `context`, if set to a non-empty string literal (see ADR 0022). `undefined` when absent, non-literal, or empty. */
|
|
126
|
+
readonly context: string | undefined;
|
|
127
|
+
/** Where this variable's own schema property (e.g. `SESSION_SECRET: z.string()`) is declared: distinct from the *contract's* `declaration`/`documentation` (`link.ts`); every variable has exactly one of these, always. See ADR 0036. */
|
|
128
|
+
readonly declaration: SourcePosition;
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* Extracts one schema object literal's variables (processor/validator/default presence); never
|
|
132
|
+
* evaluates or executes the schema.
|
|
133
|
+
*
|
|
134
|
+
* @param contextLabel - Used only to build human-readable warning messages (e.g. the contract's export name).
|
|
135
|
+
* @param warnings - Mutated in place: one entry is pushed per skipped (non-static, invalid-key, or non-literal) property.
|
|
136
|
+
*/
|
|
137
|
+
export declare function extractSchemaVariables(schemaLiteral: TS.ObjectLiteralExpression, filePath: string, contextLabel: string, warnings: ParseWarning[], sourceFile: TS.SourceFile): DiscoveredSchemaVariable[];
|
|
138
|
+
/** One variable's statically-extracted `documentEnv()` documentation, as declared in that call's `variables` entry for this key: governance fields (`owner` .. `metadata`) are `EnvGovernanceFields`, resolved from static literals. */
|
|
139
|
+
export interface DiscoveredVariableDocs extends EnvGovernanceFields {
|
|
140
|
+
/** The environment variable name this documentation applies to. */
|
|
141
|
+
readonly key: string;
|
|
142
|
+
/** Statically-resolved `description`, if set to a string literal. */
|
|
143
|
+
readonly description: string | undefined;
|
|
144
|
+
/** Statically-resolved `refreshInstructions`, if set to a string literal. */
|
|
145
|
+
readonly refreshInstructions: string | undefined;
|
|
146
|
+
/** Statically-resolved `authenticatorType`, if set to a string literal. */
|
|
147
|
+
readonly authenticatorType: string | undefined;
|
|
148
|
+
/** Statically-resolved `rotationPeriod`, if set to a string literal. */
|
|
149
|
+
readonly rotationPeriod: string | undefined;
|
|
150
|
+
/** Statically-resolved `lastRotatedAt`, if set to a string literal. */
|
|
151
|
+
readonly lastRotatedAt: string | undefined;
|
|
152
|
+
/** Statically-resolved `rotationTriggerEvents`, if set to an array of string literals. */
|
|
153
|
+
readonly rotationTriggerEvents: readonly string[] | undefined;
|
|
154
|
+
/** Statically-resolved `setupInstructions`, if set to a string literal. */
|
|
155
|
+
readonly setupInstructions: string | undefined;
|
|
156
|
+
/** Statically-resolved `required`, if set to a boolean literal. */
|
|
157
|
+
readonly required: boolean | undefined;
|
|
158
|
+
/** Statically-resolved `deprecated`, if set to a boolean literal. */
|
|
159
|
+
readonly deprecated: boolean | undefined;
|
|
160
|
+
/** Statically-resolved `deprecatedReason`, if set to a string literal. */
|
|
161
|
+
readonly deprecatedReason: string | undefined;
|
|
162
|
+
/** Statically-resolved `removeBy`, if set to a string literal. */
|
|
163
|
+
readonly removeBy: string | undefined;
|
|
164
|
+
/** Statically-resolved `renamedFrom`, if set to a string literal. */
|
|
165
|
+
readonly renamedFrom: string | undefined;
|
|
166
|
+
/** Statically-extracted `evidence` sub-object: the re-verified-every-run half of a variable's documentation, kept structurally apart from the declared-only fields above. `undefined` when the declaration has no `evidence` key at all. See {@link runtime.VariableEvidenceDocs} and ADR 0037. */
|
|
167
|
+
readonly evidence: DiscoveredVariableEvidence | undefined;
|
|
168
|
+
}
|
|
169
|
+
/** The statically-extracted contents of one variable's `evidence` sub-object. See {@link runtime.VariableEvidenceDocs}. */
|
|
170
|
+
export interface DiscoveredVariableEvidence {
|
|
171
|
+
/** Well-formed `"path:line:column"` entries from `evidence.dynamicAccess`, if set to an array of string literals: a malformed entry warns and is dropped, never included here. See ADR 0037. */
|
|
172
|
+
readonly dynamicAccess: readonly string[] | undefined;
|
|
173
|
+
}
|
|
174
|
+
/** A contract's statically-extracted `documentEnv()` documentation. */
|
|
175
|
+
/** The `documentEnv()` contract-level documentation, resolved from static literals at the parse stage. Its governance fields (`owner` .. `metadata`) are `EnvGovernanceFields`. */
|
|
176
|
+
export interface DiscoveredContractDocs extends EnvGovernanceFields {
|
|
177
|
+
/** Statically-resolved `name`, if set to a string literal. */
|
|
178
|
+
readonly name: string | undefined;
|
|
179
|
+
/** Statically-resolved `category`, if set to a string literal. */
|
|
180
|
+
readonly category: string | undefined;
|
|
181
|
+
/** Statically-resolved `exclusiveGroup`, if set to a string literal. */
|
|
182
|
+
readonly exclusiveGroup: string | undefined;
|
|
183
|
+
/** Defaults to `true` when the call's `active` field is absent or not statically resolvable. */
|
|
184
|
+
readonly active: boolean;
|
|
185
|
+
/** Statically-resolved `deprecated`, if set to a boolean literal. */
|
|
186
|
+
readonly deprecated: boolean | undefined;
|
|
187
|
+
/** Statically-resolved `deprecatedReason`, if set to a string literal. */
|
|
188
|
+
readonly deprecatedReason: string | undefined;
|
|
189
|
+
/** Per-variable documentation, keyed by variable name. */
|
|
190
|
+
readonly variables: ReadonlyMap<string, DiscoveredVariableDocs>;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* Reads a `documentEnv()` call's second argument (the {@link runtime.ContractDocs} shape).
|
|
194
|
+
*
|
|
195
|
+
* @remarks
|
|
196
|
+
* Anything not a statically-resolvable literal warns and is skipped (falls back to
|
|
197
|
+
* "not set") rather than guessed at, same policy as schema-entry parsing.
|
|
198
|
+
*
|
|
199
|
+
* @param contextLabel - Used only to build human-readable warning messages.
|
|
200
|
+
* @param warnings - Mutated in place: one entry is pushed per unresolvable field.
|
|
201
|
+
*/
|
|
202
|
+
export declare function extractContractDocs(docsArg: TS.Expression | undefined, filePath: string, contextLabel: string, warnings: ParseWarning[]): DiscoveredContractDocs;
|
|
203
|
+
/** Reads `createEnv`'s second argument (the {@link runtime.CreateEnvOptions} shape) for just `name`, if it's a statically-resolvable string literal. Used only for the docs fallback chain (`documentEnv`'s `name` wins if set); `source` is runtime-only and never read here. */
|
|
204
|
+
export declare function extractCreateEnvOptionsName(optionsArg: TS.Expression | undefined): string | undefined;
|
|
205
|
+
export {};
|
|
206
|
+
//# sourceMappingURL=parse.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../src/build/parse.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* env-cap's own built-in reference projections. They are declared through
|
|
3
|
+
* the same public `defineEvidenceProjection()` a consumer would use (ADR
|
|
4
|
+
* 0031/0032). There is no privileged internal path, and no second way of
|
|
5
|
+
* reading the Evidence Model.
|
|
6
|
+
*
|
|
7
|
+
* This is deliberate dogfooding, not a convenience layer. `renderDocs()`'s
|
|
8
|
+
* Catalog/ownership/lifecycle sections and `renderUsageReport()`'s ownership
|
|
9
|
+
* table source their data through these projections. So env-cap's own
|
|
10
|
+
* generated output exercises the extensibility API on every run. If a
|
|
11
|
+
* projector here can't express something, that's a real gap in the public
|
|
12
|
+
* API. It shows up in env-cap's own output, before a consumer has to report it.
|
|
13
|
+
*
|
|
14
|
+
* Every projection is pure and derives *only* from `EvidenceModel`. None
|
|
15
|
+
* reads the filesystem, and none reaches back into `DiscoveredContract`:
|
|
16
|
+
* that would defeat the point, since a consumer only ever has the model.
|
|
17
|
+
*/
|
|
18
|
+
import type { EvidenceProjectionResult } from "../evidence/define-projection.js";
|
|
19
|
+
import type { EvidenceModel } from "./evidence-model.js";
|
|
20
|
+
/** One variable, flattened across Contract/Ownership/Lifecycle Model into the row a Configuration Reference renders. */
|
|
21
|
+
export interface ConfigurationReferenceEntry {
|
|
22
|
+
/** Root-relative, POSIX-separated path of the declaring contract. */
|
|
23
|
+
readonly file: string;
|
|
24
|
+
readonly exportName: string;
|
|
25
|
+
/** The declaring contract's display name, resolved from Contract Model: the one model that owns it. */
|
|
26
|
+
readonly contractName: string;
|
|
27
|
+
readonly key: string;
|
|
28
|
+
readonly description: string | undefined;
|
|
29
|
+
/** Effective owner: the variable's own, falling back to its contract's. */
|
|
30
|
+
readonly owner: string | undefined;
|
|
31
|
+
/** Effective sensitivity: the variable's own, falling back to its contract's. Any string; see {@link runtime.VariableDocs.sensitivity}. */
|
|
32
|
+
readonly sensitivity: string | undefined;
|
|
33
|
+
readonly required: boolean | undefined;
|
|
34
|
+
readonly hasDefault: boolean;
|
|
35
|
+
readonly hasProcessor: boolean;
|
|
36
|
+
readonly hasValidator: boolean;
|
|
37
|
+
readonly expiresAt: string | undefined;
|
|
38
|
+
/** Whether the declaring contract is active. Inactive contracts are included: the reference documents everything discovered, same scope the Catalog always had. */
|
|
39
|
+
readonly active: boolean;
|
|
40
|
+
}
|
|
41
|
+
/** The Configuration Reference projection's output shape. */
|
|
42
|
+
export interface ConfigurationReference extends Record<string, unknown> {
|
|
43
|
+
/** The standing "declared, not verified" notice: see `evidenceDisclaimer()`. Carried in the data, not only in a renderer, so a consumer projecting this to their own format can't accidentally drop it. */
|
|
44
|
+
readonly disclaimer: string;
|
|
45
|
+
/** Every declared variable across every discovered contract, sorted by contract file, then export name, then key. */
|
|
46
|
+
readonly entries: readonly ConfigurationReferenceEntry[];
|
|
47
|
+
}
|
|
48
|
+
/** The minimal shape {@link groupVariablesByOwner} needs. It is structural, not pinned to one model. So one grouping serves `OwnershipModel`'s already-resolved owners and `ContractModel`'s raw ones alike. */
|
|
49
|
+
export interface OwnerBearingContract {
|
|
50
|
+
readonly owner: string | undefined;
|
|
51
|
+
readonly variables: readonly unknown[];
|
|
52
|
+
}
|
|
53
|
+
/** The element type of an {@link OwnerBearingContract}'s own `variables`, so callers never have to name it a second time. */
|
|
54
|
+
type VariableOf<C> = C extends {
|
|
55
|
+
readonly variables: readonly (infer V)[];
|
|
56
|
+
} ? V : never;
|
|
57
|
+
/**
|
|
58
|
+
* Groups every variable under its effective owner (its own, falling back to
|
|
59
|
+
* its contract's), preserving input order within each owner.
|
|
60
|
+
*
|
|
61
|
+
* @remarks
|
|
62
|
+
* The single implementation of "who owns what, rolled up per owner". The
|
|
63
|
+
* {@link ownershipSummary} projection and `docs.ts`'s rendered ownership
|
|
64
|
+
* matrix share it. One function means env-cap's generated Markdown and the
|
|
65
|
+
* projection a consumer reads can never disagree about the grouping. That is
|
|
66
|
+
* also why `effectiveOwner()` is the single resolution rule (ADR 0028).
|
|
67
|
+
* Variables with no effective owner are omitted entirely. A synthetic
|
|
68
|
+
* `"unowned"` bucket would read as a real team name. Callers that need them
|
|
69
|
+
* ask for them separately.
|
|
70
|
+
*
|
|
71
|
+
* The caller supplies `ownerOf`. So a model whose owners are already
|
|
72
|
+
* resolved (`OwnershipModel`) and one whose aren't (`ContractModel`) both
|
|
73
|
+
* work, without this function guessing which it was handed.
|
|
74
|
+
*/
|
|
75
|
+
export declare function groupVariablesByOwner<C extends OwnerBearingContract>(contracts: readonly C[], ownerOf: (contract: C, variable: VariableOf<C>) => string | undefined): ReadonlyMap<string, readonly {
|
|
76
|
+
contract: C;
|
|
77
|
+
variable: VariableOf<C>;
|
|
78
|
+
}[]>;
|
|
79
|
+
/**
|
|
80
|
+
* Configuration Reference: every declared variable, with its effective owner
|
|
81
|
+
* and sensitivity already resolved, in one flat, sorted list.
|
|
82
|
+
*
|
|
83
|
+
* @remarks
|
|
84
|
+
* Resolution (variable's own value falling back to its contract's) happens
|
|
85
|
+
* here rather than being left to each consumer. So two readers of this
|
|
86
|
+
* projection can never disagree about who owns a variable. That is the same
|
|
87
|
+
* reason `effectiveOwner()` exists on the generator side (ADR 0028).
|
|
88
|
+
*/
|
|
89
|
+
export declare function configurationReference(evidence: EvidenceModel): ConfigurationReference;
|
|
90
|
+
export declare namespace configurationReference {
|
|
91
|
+
var project: typeof projectConfigurationReference;
|
|
92
|
+
}
|
|
93
|
+
declare function projectConfigurationReference(evidence: EvidenceModel): EvidenceProjectionResult<ConfigurationReference>;
|
|
94
|
+
/** One owner and everything attributed to them. */
|
|
95
|
+
export interface OwnershipSummaryEntry {
|
|
96
|
+
/** The owner string exactly as declared. */
|
|
97
|
+
readonly owner: string;
|
|
98
|
+
/** Every variable this owner is the effective owner of, as `${contractName}.${key}`, sorted. */
|
|
99
|
+
readonly variables: readonly string[];
|
|
100
|
+
/** Every contract declaring this owner as its contract-level default, by display name, sorted. */
|
|
101
|
+
readonly contracts: readonly string[];
|
|
102
|
+
}
|
|
103
|
+
/** The Ownership summary projection's output shape. */
|
|
104
|
+
export interface OwnershipSummary extends Record<string, unknown> {
|
|
105
|
+
/** See {@link ConfigurationReference.disclaimer}. */
|
|
106
|
+
readonly disclaimer: string;
|
|
107
|
+
/** One entry per distinct owner, sorted by owner. */
|
|
108
|
+
readonly owners: readonly OwnershipSummaryEntry[];
|
|
109
|
+
/** Every variable with no effective owner at all, as `${contractName}.${key}`, sorted. Named separately rather than bucketed under a synthetic `"unowned"` owner, so "nobody owns this" can never be mistaken for a real team name. */
|
|
110
|
+
readonly unowned: readonly string[];
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Ownership summary: the inverse of Ownership Model's per-contract view;
|
|
114
|
+
* who owns what, rolled up per owner, plus an explicit unowned list.
|
|
115
|
+
*/
|
|
116
|
+
export declare function ownershipSummary(evidence: EvidenceModel): OwnershipSummary;
|
|
117
|
+
export declare namespace ownershipSummary {
|
|
118
|
+
var project: typeof projectOwnershipSummary;
|
|
119
|
+
}
|
|
120
|
+
declare function projectOwnershipSummary(evidence: EvidenceModel): EvidenceProjectionResult<OwnershipSummary>;
|
|
121
|
+
/** One contract- or variable-level `expiresAt` inside the configured window. */
|
|
122
|
+
export interface ExpiringSoonEntry {
|
|
123
|
+
/** Root-relative, POSIX-separated path of the declaring contract. */
|
|
124
|
+
readonly file: string;
|
|
125
|
+
readonly exportName: string;
|
|
126
|
+
/** The declaring contract's display name, resolved from Contract Model. */
|
|
127
|
+
readonly contractName: string;
|
|
128
|
+
/** `undefined` for a contract-level expiry, set for a per-variable one. */
|
|
129
|
+
readonly key: string | undefined;
|
|
130
|
+
/** The raw ISO date string, exactly as declared: never reformatted. */
|
|
131
|
+
readonly expiresAt: string;
|
|
132
|
+
/** Days remaining as of the run that produced this evidence; negative when already expired. */
|
|
133
|
+
readonly daysRemaining: number;
|
|
134
|
+
/** `true` when `daysRemaining` is negative: the deadline has already passed. */
|
|
135
|
+
readonly expired: boolean;
|
|
136
|
+
/** How to obtain a replacement value, if the declaration says. */
|
|
137
|
+
readonly refreshInstructions: string | undefined;
|
|
138
|
+
/** Effective owner, so a reader knows who to chase without a second lookup. */
|
|
139
|
+
readonly owner: string | undefined;
|
|
140
|
+
}
|
|
141
|
+
/** The Expiring-Soon projection's output shape. */
|
|
142
|
+
export interface ExpiringSoonReport extends Record<string, unknown> {
|
|
143
|
+
/** See {@link ConfigurationReference.disclaimer}. */
|
|
144
|
+
readonly disclaimer: string;
|
|
145
|
+
/** Every entry inside the window, soonest-first (already-expired entries lead, most-overdue first). */
|
|
146
|
+
readonly entries: readonly ExpiringSoonEntry[];
|
|
147
|
+
/** How many of `entries` are already past their `expiresAt`. */
|
|
148
|
+
readonly expiredCount: number;
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* Expiring-Soon report: Lifecycle Model's `expiring` view, joined with
|
|
152
|
+
* ownership and refresh instructions. A reader can act on a row without
|
|
153
|
+
* cross-referencing three other models by hand.
|
|
154
|
+
*
|
|
155
|
+
* @remarks
|
|
156
|
+
* The window itself was applied upstream, when Lifecycle Model was built.
|
|
157
|
+
* This projection deliberately does not re-filter by a date of its own.
|
|
158
|
+
* Recomputing "soon" here would tie the answer to when it was *read*, not
|
|
159
|
+
* when the evidence was *generated*. The Evidence Model exists to preserve
|
|
160
|
+
* exactly that reproducibility.
|
|
161
|
+
*/
|
|
162
|
+
export declare function expiringSoonReport(evidence: EvidenceModel): ExpiringSoonReport;
|
|
163
|
+
export declare namespace expiringSoonReport {
|
|
164
|
+
var project: typeof projectExpiringSoonReport;
|
|
165
|
+
}
|
|
166
|
+
declare function projectExpiringSoonReport(evidence: EvidenceModel): EvidenceProjectionResult<ExpiringSoonReport>;
|
|
167
|
+
export {};
|
|
168
|
+
//# sourceMappingURL=reference-projections.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"reference-projections.d.ts","sourceRoot":"","sources":["../../../src/build/reference-projections.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import type { BuildFileSystem } from "../types.js";
|
|
2
|
+
import { type PackageSchemaResolutionResult } from "./resolve-package-schema.js";
|
|
3
|
+
import { type AliasResolutionCache, type TsconfigPathsResolution } from "./resolve-tsconfig-paths.js";
|
|
4
|
+
/**
|
|
5
|
+
* Resolves a relative import specifier (as written in source: `"./schema.js"`,
|
|
6
|
+
* matching this codebase's own convention of `.js`-suffixed relative imports
|
|
7
|
+
* pointing at `.ts` source files) to an absolute file path, relative to the
|
|
8
|
+
* file that contains the import.
|
|
9
|
+
*
|
|
10
|
+
* @remarks
|
|
11
|
+
* Deliberately narrow: only handles a direct relative specifier resolving to
|
|
12
|
+
* a real `.ts`/`.tsx` file on disk. Bare/package specifiers, namespace
|
|
13
|
+
* imports, and anything requiring real module resolution (re-export chains,
|
|
14
|
+
* `exports` map lookups, etc.) return `undefined`: the caller treats that
|
|
15
|
+
* as "couldn't statically link" and warns rather than guesses, the same
|
|
16
|
+
* philosophy `evaluateLiteral` already uses for non-literal expressions.
|
|
17
|
+
*
|
|
18
|
+
* @returns The resolved absolute path, or `undefined` when the specifier isn't relative or doesn't resolve to a real file.
|
|
19
|
+
*/
|
|
20
|
+
export declare function resolveRelativeImport(importingFile: string, specifier: string, fs: BuildFileSystem): Promise<string | undefined>;
|
|
21
|
+
/**
|
|
22
|
+
* Whether `filePath` is a regular file; a path that cannot be stat'd is simply not one.
|
|
23
|
+
* @internal Exported for direct unit coverage.
|
|
24
|
+
*/
|
|
25
|
+
export declare function fileExists(filePath: string, fs: BuildFileSystem): Promise<boolean>;
|
|
26
|
+
/** Shared inputs threaded through every call to {@link resolveImportSpecifier} for one discovery/link run. */
|
|
27
|
+
export interface ImportResolutionContext {
|
|
28
|
+
/** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
|
|
29
|
+
readonly fs: BuildFileSystem;
|
|
30
|
+
/** Absolute path of the project root, used to resolve package specifiers. */
|
|
31
|
+
readonly root: string;
|
|
32
|
+
/** Explicit allowlist: see ADR 0014. Empty/omitted means package resolution never fires, identical to today's behavior. */
|
|
33
|
+
readonly packages: readonly string[];
|
|
34
|
+
/** Memoizes package resolution per specifier across the whole run: see `resolvePackageImport`'s own doc comment for why. */
|
|
35
|
+
readonly cache: Map<string, Promise<PackageSchemaResolutionResult>>;
|
|
36
|
+
/** Parsed `tsconfig.json` `paths`/`baseUrl`, or `undefined` when alias resolution found nothing to do or was disabled: see ADR 0023. */
|
|
37
|
+
readonly tsconfigPaths: TsconfigPathsResolution | undefined;
|
|
38
|
+
/** Memoizes alias resolution across the whole run: see `resolveAliasImport`'s own doc comment for why. Always allocated, even when `tsconfigPaths` is `undefined`, mirroring `cache` above. */
|
|
39
|
+
readonly aliasCache: AliasResolutionCache;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* The one specifier-resolution entry point `link.ts` and `dependency-graph.ts`
|
|
43
|
+
* call, instead of each duplicating a
|
|
44
|
+
* `(await resolveRelativeImport(...)) ?? resolveAliasImport(...) ?? (await resolvePackageImport(...))`
|
|
45
|
+
* chain at every call site.
|
|
46
|
+
*
|
|
47
|
+
* @remarks
|
|
48
|
+
* Purely a composition point: no new resolution logic lives here. It tries, in order:
|
|
49
|
+
*
|
|
50
|
+
* 1. The relative resolver (cheap, no `fs.stat` beyond the local filesystem check it
|
|
51
|
+
* already does).
|
|
52
|
+
* 2. tsconfig path-alias resolution (ADR 0023, on by default), for a bare specifier
|
|
53
|
+
* matching the project's own `tsconfig.json` `paths`/`baseUrl`.
|
|
54
|
+
* 3. Package resolution (ADR 0014), for a bare specifier matching an allow-listed
|
|
55
|
+
* package name.
|
|
56
|
+
*
|
|
57
|
+
* Alias resolution runs before package resolution because it resolves the consuming
|
|
58
|
+
* project's own local source (already-trusted, no versioning boundary). Relative
|
|
59
|
+
* resolution has the same precedence over package resolution.
|
|
60
|
+
*/
|
|
61
|
+
export declare function resolveImportSpecifier(importingFile: string, specifier: string, context: ImportResolutionContext): Promise<string | undefined>;
|
|
62
|
+
//# sourceMappingURL=resolve-import.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"resolve-import.d.ts","sourceRoot":"","sources":["../../../../src/build/resolution/resolve-import.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAEL,KAAK,6BAA6B,EACnC,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC7B,MAAM,6BAA6B,CAAA;AAEpC;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAKlF;AAED,8GAA8G;AAC9G,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2HAA2H;IAC3H,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,4HAA4H;IAC5H,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,CAAA;IACnE,wIAAwI;IACxI,QAAQ,CAAC,aAAa,EAAE,uBAAuB,GAAG,SAAS,CAAA;IAC3D,+LAA+L;IAC/L,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAA;CAC1C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAC1C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B"}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import type { ParseWarning } from "../parse.js";
|
|
2
|
+
import type { BuildFileSystem } from "../types.js";
|
|
3
|
+
/** 1 MiB. Hardening specific to this trust tier. A package crosses a real
|
|
4
|
+
* versioning/trust boundary that locally-discovered source doesn't. So this
|
|
5
|
+
* caps the cost of an oversized or adversarial file before any of its
|
|
6
|
+
* content is read into memory. See ADR 0014. */
|
|
7
|
+
export declare const MAX_PACKAGE_SCHEMA_FILE_BYTES = 1048576;
|
|
8
|
+
type PackageResolutionFailureCode = "PACKAGE_NOT_FOUND" | "MALFORMED_PACKAGE_JSON" | "FIELD_MISSING" | "INVALID_EXTENSION" | "OUTSIDE_PACKAGE" | "FILE_TOO_LARGE";
|
|
9
|
+
/** Both the authored and resolved forms are kept: diagnostics benefit from
|
|
10
|
+
* showing exactly what a package author wrote versus what it resolved to. */
|
|
11
|
+
export interface PackageOrigin {
|
|
12
|
+
/** The allow-listed package name that declared this schema. */
|
|
13
|
+
readonly packageName: string;
|
|
14
|
+
/** The `"envCap.schema"` value exactly as the package author wrote it. */
|
|
15
|
+
readonly declaredField: string;
|
|
16
|
+
/** Absolute, realpath-canonicalized path to the resolved schema file. */
|
|
17
|
+
readonly resolvedFile: string;
|
|
18
|
+
/** Absolute, realpath-canonicalized path to the package's own directory. */
|
|
19
|
+
readonly packageDir: string;
|
|
20
|
+
}
|
|
21
|
+
export type PackageSchemaResolutionResult = {
|
|
22
|
+
readonly ok: true;
|
|
23
|
+
readonly origin: PackageOrigin;
|
|
24
|
+
} | {
|
|
25
|
+
readonly ok: false;
|
|
26
|
+
readonly code: PackageResolutionFailureCode;
|
|
27
|
+
readonly reason: string;
|
|
28
|
+
};
|
|
29
|
+
/**
|
|
30
|
+
* Resolves one allow-listed package name. Memoized in a caller-owned
|
|
31
|
+
* `cache`: one per `generate*()` invocation, shared with linking/dependency-
|
|
32
|
+
* graph resolution. So a name referenced from multiple places is resolved
|
|
33
|
+
* only once (e.g. several scanned files bare-import the same package, or
|
|
34
|
+
* `packages` has a duplicate entry). The cache holds the in-flight promise
|
|
35
|
+
* before it settles. So concurrent callers await the same resolution rather
|
|
36
|
+
* than racing duplicate work.
|
|
37
|
+
*/
|
|
38
|
+
export declare function resolvePackageSchemaFile(packageName: string, root: string, cache: Map<string, Promise<PackageSchemaResolutionResult>>, fs: BuildFileSystem): Promise<PackageSchemaResolutionResult>;
|
|
39
|
+
interface ResolvedPackageFile {
|
|
40
|
+
readonly packageName: string;
|
|
41
|
+
readonly file: string;
|
|
42
|
+
}
|
|
43
|
+
export interface ResolvePackagesResult {
|
|
44
|
+
readonly files: readonly ResolvedPackageFile[];
|
|
45
|
+
/** Keyed by resolved file path, for `DiscoveredContract.packageOrigin` lookups downstream. */
|
|
46
|
+
readonly origins: ReadonlyMap<string, PackageOrigin>;
|
|
47
|
+
readonly warnings: readonly ParseWarning[];
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Resolves every allow-listed package name. Input is deduplicated first. So
|
|
51
|
+
* a duplicate entry in `packages` (accidental or defensive) produces one
|
|
52
|
+
* resolution attempt and, on failure, one warning: never two.
|
|
53
|
+
* Never throws: every failure becomes one `ParseWarning`, consistent with
|
|
54
|
+
* every other static-analysis boundary in this codebase.
|
|
55
|
+
*/
|
|
56
|
+
export declare function resolveAllowlistedPackages(packages: readonly string[] | undefined, root: string, cache: Map<string, Promise<PackageSchemaResolutionResult>>, fs: BuildFileSystem): Promise<ResolvePackagesResult>;
|
|
57
|
+
/**
|
|
58
|
+
* Combines local schema-discovery hits with package-resolved files into one
|
|
59
|
+
* deduplicated list, keyed by realpath rather than lexical absolute path.
|
|
60
|
+
* Package-resolved files are already realpath-canonicalized (see
|
|
61
|
+
* `resolveUncached` above). Local `discoverSchemaFiles()` hits are plain
|
|
62
|
+
* `readdir`-derived absolute paths that may themselves traverse a symlink (a
|
|
63
|
+
* symlinked `root`, or an included path reached through one).
|
|
64
|
+
*
|
|
65
|
+
* Deduplicating on the lexical path alone would miss one physical file
|
|
66
|
+
* reached by two symlinked routes: local glob discovery and package
|
|
67
|
+
* resolution. That file would be silently
|
|
68
|
+
* double-counted into two identical contracts. A common case: a package
|
|
69
|
+
* that's both locally glob-reachable (e.g. during a monorepo migration) and
|
|
70
|
+
* explicitly allow-listed. On a collision, the local path string identity
|
|
71
|
+
* wins (the package-resolved duplicate is dropped).
|
|
72
|
+
*/
|
|
73
|
+
export declare function mergeLocalAndPackageFiles(localFiles: readonly string[], packageFiles: readonly string[], fs: BuildFileSystem): Promise<string[]>;
|
|
74
|
+
/**
|
|
75
|
+
* Bare-specifier-to-allowlist matching, used by `resolve-import.ts`'s
|
|
76
|
+
* `resolveImportSpecifier()` as its package-resolution fallback. It only
|
|
77
|
+
* attempts resolution for a specifier that is (or is a subpath of) an
|
|
78
|
+
* allow-listed package name. Any other bare specifier returns `undefined`
|
|
79
|
+
* immediately, like `resolveRelativeImport()`'s bare-specifier no-op.
|
|
80
|
+
*/
|
|
81
|
+
export declare function resolvePackageImport(specifier: string, allowedPackages: readonly string[], root: string, cache: Map<string, Promise<PackageSchemaResolutionResult>>, fs: BuildFileSystem): Promise<string | undefined>;
|
|
82
|
+
export {};
|
|
83
|
+
//# sourceMappingURL=resolve-package-schema.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"resolve-package-schema.d.ts","sourceRoot":"","sources":["../../../../src/build/resolution/resolve-package-schema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAsBlD;;;iDAGiD;AACjD,eAAO,MAAM,6BAA6B,UAAY,CAAA;AAItD,KAAK,4BAA4B,GAC7B,mBAAmB,GACnB,wBAAwB,GACxB,eAAe,GACf,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,CAAA;AAEpB;8EAC8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,MAAM,6BAA6B,GACrC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAwNhG;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,EAC1D,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,6BAA6B,CAAC,CAYxC;AAED,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAA;IAC9C,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;CAC3C;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACvC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,EAC1D,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,qBAAqB,CAAC,CA2BhC;AAED;;;;;;;;;;;;;;;GAeG;AAKH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBnB;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,SAAS,MAAM,EAAE,EAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,EAC1D,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B"}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { LoadTsconfigPathsResult } from "../../_ipc/resolve-tsconfig-paths.js";
|
|
2
|
+
import type { BuildFileSystem } from "../types.js";
|
|
3
|
+
/**
|
|
4
|
+
* TypeScript path-alias resolution. The behavior lives in `../../_ipc/resolve-tsconfig-paths.ts`, a managed copy of
|
|
5
|
+
* internal-package-contract's `runtime/resolve-tsconfig-paths.ts`; this binds the one package-specific input, the
|
|
6
|
+
* name used when no usable compiler resolved.
|
|
7
|
+
*/
|
|
8
|
+
export { createAliasResolutionCache, resolveAliasImport, } from "../../_ipc/resolve-tsconfig-paths.js";
|
|
9
|
+
export type { AliasResolutionCache, LoadTsconfigPathsResult, TsconfigPathsResolution, } from "../../_ipc/resolve-tsconfig-paths.js";
|
|
10
|
+
/**
|
|
11
|
+
* Loads and parses a `tsconfig.json` for alias resolution, once per run.
|
|
12
|
+
* @param root - The project root; a missing default `tsconfig.json` there is silent.
|
|
13
|
+
* @param tsconfigOption - `false` disables alias resolution, a path overrides the default file.
|
|
14
|
+
* @param fs - The filesystem capability.
|
|
15
|
+
* @returns The resolution and at most one warning.
|
|
16
|
+
*/
|
|
17
|
+
export declare function loadTsconfigPaths(root: string, tsconfigOption: string | false | undefined, fs: BuildFileSystem): Promise<LoadTsconfigPathsResult>;
|
|
18
|
+
//# sourceMappingURL=resolve-tsconfig-paths.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"resolve-tsconfig-paths.d.ts","sourceRoot":"","sources":["../../../../src/build/resolution/resolve-tsconfig-paths.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD;;;;GAIG;AACH,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,sCAAsC,CAAA;AAC7C,YAAY,EACV,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,sCAAsC,CAAA;AAE7C;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,EAC1C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,uBAAuB,CAAC,CAElC"}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import type { CompatibilityIssue } from "../compatibility.js";
|
|
2
|
+
export type ResolveWithinRootResult = {
|
|
3
|
+
readonly ok: true;
|
|
4
|
+
readonly resolved: string;
|
|
5
|
+
} | {
|
|
6
|
+
readonly ok: false;
|
|
7
|
+
readonly issue: CompatibilityIssue;
|
|
8
|
+
};
|
|
9
|
+
/**
|
|
10
|
+
* Plain lexical bounds-check: is `targetPath` inside `baseDir`? Two callers
|
|
11
|
+
* share it. `resolveWithinRoot()` below checks output paths lexically, since
|
|
12
|
+
* they usually don't exist on disk yet. `resolve-package-schema.ts` also
|
|
13
|
+
* re-checks against `fs.realpath`-resolved paths, since a package-declared
|
|
14
|
+
* schema path both exists on disk and crosses a real trust boundary (see
|
|
15
|
+
* ADR 0014). Boundary-agnostic on purpose: neither caller's
|
|
16
|
+
* notion of "root" is baked in here.
|
|
17
|
+
*/
|
|
18
|
+
export declare function isWithinDirectory(baseDir: string, targetPath: string): boolean;
|
|
19
|
+
/**
|
|
20
|
+
* Resolves `location` against `root` and checks the result doesn't escape it
|
|
21
|
+
* (e.g. `location: "../../malicious.ts"`, or an absolute path on another
|
|
22
|
+
* branch of the filesystem entirely). Discovery (`include`/`exclude`) is
|
|
23
|
+
* already safe by construction: it only ever walks *down* from `root` via
|
|
24
|
+
* `readdir`, so a pattern can't make it read outside `root`. Output
|
|
25
|
+
* locations have no such structural guarantee, since `path.resolve` happily
|
|
26
|
+
* walks back out via `..` segments, so this is a plain lexical bounds-check
|
|
27
|
+
* (not a symlink-aware `realpath` check: these are *output* paths that
|
|
28
|
+
* usually don't exist yet).
|
|
29
|
+
*
|
|
30
|
+
* Never throws itself: returns a `CompatibilityIssue`-shaped finding on
|
|
31
|
+
* escape so each generator function (`generateEnvManifest`, `generateDocumentation`,
|
|
32
|
+
* `generateUsageReport`, `generateEnvArtifacts`) can wrap it in its own error type.
|
|
33
|
+
*/
|
|
34
|
+
export declare function resolveWithinRoot(root: string, location: string, optionName: string, functionName: string): ResolveWithinRootResult;
|
|
35
|
+
//# sourceMappingURL=resolve-within-root.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"resolve-within-root.d.ts","sourceRoot":"","sources":["../../../../src/build/resolution/resolve-within-root.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAE7D,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAAA;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAG9E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,uBAAuB,CAgBzB"}
|