@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,134 @@
|
|
|
1
|
+
import type TS from "@typescript/typescript6";
|
|
2
|
+
import type { BuildFileSystem } from "./build-fs.js";
|
|
3
|
+
/**
|
|
4
|
+
* TypeScript path-alias resolution.
|
|
5
|
+
*
|
|
6
|
+
* Resolves a bare import specifier (`"@/lib/env.schema.js"`) against a project's own
|
|
7
|
+
* `tsconfig.json` `compilerOptions.paths`/`baseUrl`, so a schema or consumer reached only
|
|
8
|
+
* through an alias isn't misreported by `link.ts`/`dependency-graph.ts` as unresolved or
|
|
9
|
+
* abandoned. Unlike a package-schema resolver, this never crosses a
|
|
10
|
+
* trust/versioning boundary (every resolved file is already local, already-trusted
|
|
11
|
+
* project source), so it is on by default (auto-detecting `root/tsconfig.json`) rather
|
|
12
|
+
* than requiring an explicit allowlist.
|
|
13
|
+
*
|
|
14
|
+
* The actual `paths`/`baseUrl` matching algorithm (longest-prefix matching, `*` wildcard
|
|
15
|
+
* substitution, multiple fallback targets, `extends`-chain merging, JSONC parsing) is
|
|
16
|
+
* delegated entirely to the TypeScript compiler via `ts.resolveModuleName()` and
|
|
17
|
+
* `ts.parseJsonConfigFileContent()` (the same functions `tsc`/`tsserver` themselves use)
|
|
18
|
+
* rather than reimplemented here. This module's own logic is limited to loading the config,
|
|
19
|
+
* caching resolutions, and enforcing the `node_modules` safety boundary below.
|
|
20
|
+
*/
|
|
21
|
+
/**
|
|
22
|
+
* The `paths`/`baseUrl` view of parsed compiler options.
|
|
23
|
+
*
|
|
24
|
+
* TypeScript 6 marks `baseUrl` deprecated in its own typings. A project's tsconfig can still set it and
|
|
25
|
+
* TypeScript still honours it, so path resolution has to keep reading it to resolve the way the project's own
|
|
26
|
+
* compiler does. Reading it through this view, which does not carry that deprecation, states that on purpose.
|
|
27
|
+
* @internal
|
|
28
|
+
*/
|
|
29
|
+
export interface PathMappingOptions {
|
|
30
|
+
readonly paths?: TS.MapLike<string[]>;
|
|
31
|
+
readonly baseUrl?: string;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* @param options - Parsed compiler options.
|
|
35
|
+
* @returns The same options, typed as the `paths`/`baseUrl` view.
|
|
36
|
+
* @internal
|
|
37
|
+
*/
|
|
38
|
+
export declare function pathMappingOptions(options: TS.CompilerOptions): PathMappingOptions;
|
|
39
|
+
/** Parsed `tsconfig.json` `paths`/`baseUrl` configuration, immutable for the life of one generate*() run. See {@link loadTsconfigPaths}. */
|
|
40
|
+
export interface TsconfigPathsResolution {
|
|
41
|
+
/** The subset of `compilerOptions` `ts.resolveModuleName()` needs: at minimum `paths` and/or `baseUrl`. */
|
|
42
|
+
readonly compilerOptions: TS.CompilerOptions;
|
|
43
|
+
/** Absolute path of the tsconfig.json this was loaded from, for diagnostics. */
|
|
44
|
+
readonly configFile: string;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Opaque memoization for {@link resolveAliasImport}, created once per generate*() run via
|
|
48
|
+
* {@link createAliasResolutionCache} and threaded through `ImportResolutionContext`. Kept
|
|
49
|
+
* distinct from `TsconfigPathsResolution` (immutable config) so the cache's internal
|
|
50
|
+
* representation stays free to change without touching that type's shape.
|
|
51
|
+
*/
|
|
52
|
+
export interface AliasResolutionCache {
|
|
53
|
+
/**
|
|
54
|
+
* Keyed by `` `${importingFile}\0${specifier}` ``, not by `specifier` alone. With one
|
|
55
|
+
* fixed `compilerOptions` object and no project-reference support, `paths`-pattern
|
|
56
|
+
* substitution itself doesn't depend on the importing file, but `ts.resolveModuleName()`'s
|
|
57
|
+
* fallback behavior when `paths` doesn't match a real file (classic-mode ancestor search,
|
|
58
|
+
* extension-preference edge cases) legitimately can. A `Map`, not a network call, so
|
|
59
|
+
* keying defensively by both costs nothing.
|
|
60
|
+
*/
|
|
61
|
+
readonly resolutions: Map<string, string | undefined>;
|
|
62
|
+
}
|
|
63
|
+
/** Creates a fresh, empty {@link AliasResolutionCache} for one generate*()/computeArtifacts() run. */
|
|
64
|
+
export declare function createAliasResolutionCache(): AliasResolutionCache;
|
|
65
|
+
/** A problem with the tsconfig that is reported rather than thrown. Structurally the same as each package's own warning type. */
|
|
66
|
+
export interface TsconfigWarning {
|
|
67
|
+
/** Absolute path of the tsconfig the warning applies to. */
|
|
68
|
+
readonly file: string;
|
|
69
|
+
/** Human-readable explanation of what was skipped and why. */
|
|
70
|
+
readonly message: string;
|
|
71
|
+
}
|
|
72
|
+
export interface LoadTsconfigPathsResult {
|
|
73
|
+
readonly resolution: TsconfigPathsResolution | undefined;
|
|
74
|
+
readonly warning: TsconfigWarning | undefined;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* The compiler's own functions take a path written with `/` and assert it when they report a problem in the file, so
|
|
78
|
+
* a path with the platform's separator (a backslash on Windows) is written with `/` for them.
|
|
79
|
+
* @param file - an absolute path as the platform writes it.
|
|
80
|
+
* @param separator - the platform's path separator.
|
|
81
|
+
* @returns the same path written with `/`.
|
|
82
|
+
*/
|
|
83
|
+
export declare function typescriptPath(file: string, separator: string): string;
|
|
84
|
+
/**
|
|
85
|
+
* Loads and parses a `tsconfig.json` for alias resolution. Called exactly once per
|
|
86
|
+
* `generate*()`/`computeArtifacts()` invocation, at the same point
|
|
87
|
+
* `resolveAllowlistedPackages()` is already called once, so at most one tsconfig-related
|
|
88
|
+
* warning is ever produced per run, never once per file scanned.
|
|
89
|
+
*
|
|
90
|
+
* @param product - The consuming package's name, used in the message when no usable compiler resolved.
|
|
91
|
+
* @remarks
|
|
92
|
+
* `tsconfigOption === false` disables alias resolution entirely.
|
|
93
|
+
* `tsconfigOption === undefined` (the default) looks for `root/tsconfig.json` exactly:
|
|
94
|
+
* deliberately not `ts.findConfigFile()`'s upward directory walk, since every other
|
|
95
|
+
* root-relative mechanism in this codebase (schema discovery, `packages` resolution)
|
|
96
|
+
* treats `root` as a hard boundary. A missing default tsconfig is silent (most projects
|
|
97
|
+
* don't use aliases); a missing *explicit* `tsconfigOption` is a real misconfiguration and
|
|
98
|
+
* warns. `jsconfig.json` is intentionally not auto-detected: pass `tsconfig:
|
|
99
|
+
* "jsconfig.json"` explicitly if needed; this loader only cares about the file's JSON
|
|
100
|
+
* shape, not its name.
|
|
101
|
+
*
|
|
102
|
+
* The gate for building a resolution is "`paths` non-empty OR `baseUrl` set", not `paths`
|
|
103
|
+
* alone. A `baseUrl`-only tsconfig (no `paths` at all) still makes TypeScript resolve
|
|
104
|
+
* bare specifiers relative to `baseUrl`. `ts.resolveModuleName()` already handles that
|
|
105
|
+
* once `compilerOptions.baseUrl` is passed through.
|
|
106
|
+
*/
|
|
107
|
+
export declare function loadTsconfigPaths(product: string, root: string, tsconfigOption: string | false | undefined, fs: BuildFileSystem): Promise<LoadTsconfigPathsResult>;
|
|
108
|
+
/**
|
|
109
|
+
* Resolves one bare import specifier against a project's `tsconfig.json` `paths`/`baseUrl`,
|
|
110
|
+
* or returns `undefined` if it doesn't resolve through this mechanism.
|
|
111
|
+
*
|
|
112
|
+
* @remarks
|
|
113
|
+
* Necessarily synchronous: `ts.resolveModuleName()` has no async form, matching how
|
|
114
|
+
* `tsc`/`tsserver` themselves always call it. `ts.sys` is used directly as the resolution
|
|
115
|
+
* host (an existing Node-backed singleton the `typescript` package exports; nothing to
|
|
116
|
+
* construct).
|
|
117
|
+
*
|
|
118
|
+
* Two safety/scope filters apply to any candidate `ts.resolveModuleName()` returns,
|
|
119
|
+
* independent of its own internal fallback behavior:
|
|
120
|
+
* - **Never resolves into `node_modules`.** `ts.resolveModuleName()` can, in principle,
|
|
121
|
+
* fall through to classic Node resolution and land inside `node_modules`. Any resolved
|
|
122
|
+
* path containing a `node_modules` path segment (checked after `path.normalize()`, so
|
|
123
|
+
* mixed separators can't slip past it on Windows) is discarded here. Bare package
|
|
124
|
+
* specifiers continue to be handled exclusively by `resolvePackageImport()`:
|
|
125
|
+
* this mechanism never overlaps with that trust boundary.
|
|
126
|
+
* - **`.ts`/`.tsx` only.** Matches `resolveRelativeImport()`'s own existing candidate set
|
|
127
|
+
* and `resolve-package-schema.ts`'s `SCHEMA_FILE_EXTENSIONS`: this codebase's static-
|
|
128
|
+
* analysis pipeline is `.ts`/`.tsx` only today. A resolved non-`.ts`/`.tsx` file is a
|
|
129
|
+
* real risk, not just a gap: feeding it straight into `ts.createSourceFile()` wouldn't
|
|
130
|
+
* error, it would silently parse garbage: exactly the "guess" this codebase's
|
|
131
|
+
* warn-don't-guess philosophy exists to avoid.
|
|
132
|
+
*/
|
|
133
|
+
export declare function resolveAliasImport(specifier: string, importingFile: string, resolution: TsconfigPathsResolution, cache: AliasResolutionCache): string | undefined;
|
|
134
|
+
//# sourceMappingURL=resolve-tsconfig-paths.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"resolve-tsconfig-paths.d.ts","sourceRoot":"","sources":["../../../src/_ipc/resolve-tsconfig-paths.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,EAAE,CAAC,eAAe,GAAG,kBAAkB,CAElF;AAED,4IAA4I;AAC5I,MAAM,WAAW,uBAAuB;IACtC,2GAA2G;IAC3G,QAAQ,CAAC,eAAe,EAAE,EAAE,CAAC,eAAe,CAAA;IAC5C,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CACtD;AAED,sGAAsG;AACtG,wBAAgB,0BAA0B,IAAI,oBAAoB,CAEjE;AAYD,iIAAiI;AACjI,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,uBAAuB,GAAG,SAAS,CAAA;IACxD,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,CAAA;CAC9C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,EAC1C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,uBAAuB,CAAC,CAuElC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,uBAAuB,EACnC,KAAK,EAAE,oBAAoB,GAC1B,MAAM,GAAG,SAAS,CAiBpB"}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type TS from "@typescript/typescript6";
|
|
2
|
+
/** The compiler namespace the build-time scanner is written against. */
|
|
3
|
+
export type TypeScript = typeof TS;
|
|
4
|
+
/**
|
|
5
|
+
* Picks the compiler the scanner parses with: the consumer's `typescript` when it exposes the
|
|
6
|
+
* classic compiler API (TypeScript 5 and 6), otherwise the bundled `@typescript/typescript6`. That is
|
|
7
|
+
* Microsoft's side-by-side TypeScript 6 package, a dependency of the package, so the scanner keeps working
|
|
8
|
+
* for a consumer whose own `typescript` is 7+ (which ships no programmatic API). Chosen by capability, never by version,
|
|
9
|
+
* so a future `typescript` that regains the API is used as-is.
|
|
10
|
+
*
|
|
11
|
+
* When neither has the API (the bundled dependency was stripped from an install), it returns the
|
|
12
|
+
* consumer's module anyway so `assertCompilerApi` (called at every scanner entry point) fails
|
|
13
|
+
* with its readable message instead of a bare "is not a function".
|
|
14
|
+
* @param load - How a module id is resolved (a parameter so a test can hand in stand-ins).
|
|
15
|
+
* @throws Whatever `load` throws for a reason other than the module not being installed.
|
|
16
|
+
*/
|
|
17
|
+
export declare function pickCompiler(load: (id: string) => unknown): TypeScript;
|
|
18
|
+
/** The compiler every scanner module parses with. Resolved once, synchronously, at import. */
|
|
19
|
+
export declare const ts: TypeScript;
|
|
20
|
+
//# sourceMappingURL=typescript.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["../../../src/_ipc/typescript.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhC,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,OAAO,EAAE,CAAA;AAqClC;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GAAG,UAAU,CAMtE;AAED,8FAA8F;AAC9F,eAAO,MAAM,EAAE,EAAE,UAAyD,CAAA"}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { LinkResult } from "./link.js";
|
|
2
|
+
import type { ParseWarning } from "./parse.js";
|
|
3
|
+
import type { BuildFileSystem } from "./types.js";
|
|
4
|
+
import type { ImportResolutionContext } from "./resolution/resolve-import.js";
|
|
5
|
+
import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
|
|
6
|
+
/** Options for {@link assembleProject}. */
|
|
7
|
+
export interface AssembleProjectOptions {
|
|
8
|
+
/** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
|
|
9
|
+
readonly fs: BuildFileSystem;
|
|
10
|
+
readonly root: string;
|
|
11
|
+
readonly include: readonly string[];
|
|
12
|
+
readonly exclude: readonly string[];
|
|
13
|
+
readonly packages?: readonly string[] | undefined;
|
|
14
|
+
readonly tsconfig: string | false | undefined;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Everything downstream model-building and artifact-rendering needs from one
|
|
18
|
+
* discovery+link pass. It holds the linked contract graph and the
|
|
19
|
+
* import-resolution context. Every later resolution call
|
|
20
|
+
* (`computeScanSurface()`, `buildDependencyModel()`, ...) must reuse that
|
|
21
|
+
* context to agree with `linkResult`. It also holds a shared file-read cache,
|
|
22
|
+
* so a file matched by more than one later pass' glob is read from disk once
|
|
23
|
+
* (e.g. a schema file also matched by the usage pass' broader `SCAN_INCLUDE`).
|
|
24
|
+
*/
|
|
25
|
+
export interface AssembledProject {
|
|
26
|
+
readonly root: string;
|
|
27
|
+
readonly readFileCached: (filePath: string) => Promise<string>;
|
|
28
|
+
readonly linkResult: LinkResult;
|
|
29
|
+
readonly context: ImportResolutionContext;
|
|
30
|
+
/** Keyed by resolved file path: see `resolveAllowlistedPackages()`. */
|
|
31
|
+
readonly origins: ReadonlyMap<string, PackageOrigin>;
|
|
32
|
+
readonly packageWarnings: readonly ParseWarning[];
|
|
33
|
+
readonly tsconfigWarnings: readonly ParseWarning[];
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* The one shared discovery+link pass every orchestrator needs: local +
|
|
37
|
+
* allow-listed-package schema discovery, tsconfig path-alias resolution, and
|
|
38
|
+
* cross-file linking, exactly once. `computeArtifacts()`
|
|
39
|
+
* (`generate-env-artifacts.ts`) and `generateEvidenceModel()`
|
|
40
|
+
* (`generate-evidence.ts`) both call it, so the two orchestrators can never
|
|
41
|
+
* drift into scanning the same source tree twice. This is ADR 0011's "shared
|
|
42
|
+
* discovery, computed once" principle for manifest/docs/usage, extended to
|
|
43
|
+
* evidence assembly.
|
|
44
|
+
*/
|
|
45
|
+
export declare function assembleProject(options: AssembleProjectOptions): Promise<AssembledProject>;
|
|
46
|
+
//# sourceMappingURL=assemble-project.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"assemble-project.d.ts","sourceRoot":"","sources":["../../../src/build/assemble-project.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAK7E,OAAO,KAAK,EACV,aAAa,EAEd,MAAM,wCAAwC,CAAA;AAM/C,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;CAC9C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC9D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAA;IACzC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpD,QAAQ,CAAC,eAAe,EAAE,SAAS,YAAY,EAAE,CAAA;IACjD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,YAAY,EAAE,CAAA;CACnD;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2ChG"}
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import type { DiscoveredContract } from "./link.js";
|
|
2
|
+
import type { ManifestChangeReport } from "./evidence-snapshot.js";
|
|
3
|
+
/**
|
|
4
|
+
* The sixth of env-cap's seven canonical fact models (ADR 0024): what
|
|
5
|
+
* changed since the last persisted evidence snapshot (ADR 0038, which
|
|
6
|
+
* replaces the manifest-scoped snapshot of ADR 0021). See ADR 0030 (base shape) and ADR
|
|
7
|
+
* 0029 (the `renamedFrom` field this file's rename correlation is gated
|
|
8
|
+
* on).
|
|
9
|
+
*
|
|
10
|
+
* @remarks
|
|
11
|
+
* Wraps `ManifestChangeReport` (`evidence-snapshot.ts`) rather than
|
|
12
|
+
* replacing it: this model exists to give the change report a versioned,
|
|
13
|
+
* model-namespaced shape Evidence Model can assemble against, alongside the
|
|
14
|
+
* other six models. Empty (no adds/removes/updates) whenever no previous
|
|
15
|
+
* evidence snapshot location was configured for this run: there is
|
|
16
|
+
* nothing to diff against, which is a genuinely different state from a
|
|
17
|
+
* first-ever run *with* tracking configured (where everything reads as
|
|
18
|
+
* added).
|
|
19
|
+
*/
|
|
20
|
+
/** Bump only when a reader could misinterpret the new shape: same discipline every other canonical model's `schemaVersion` follows. */
|
|
21
|
+
export declare const CHANGE_MODEL_SCHEMA_VERSION = 1;
|
|
22
|
+
/** One `addedVariables`/`removedVariables` pair in `manifest`, correlated into a single rename via the current declaration's `renamedFrom` field (ADR 0029). */
|
|
23
|
+
export interface RenamedVariable {
|
|
24
|
+
/** The owning contract's identity (`${file}#${exportName}`): a rename never crosses contracts. */
|
|
25
|
+
readonly contractIdentity: string;
|
|
26
|
+
readonly file: string;
|
|
27
|
+
readonly exportName: string;
|
|
28
|
+
readonly contractName: string;
|
|
29
|
+
/** The variable's key before the rename: matches a `manifest.removedVariables` entry. */
|
|
30
|
+
readonly previousKey: string;
|
|
31
|
+
/** The variable's key after the rename: matches a `manifest.addedVariables` entry. */
|
|
32
|
+
readonly currentKey: string;
|
|
33
|
+
}
|
|
34
|
+
/** The versioned, JSON-serializable root of the Change Model: what changed since the last persisted evidence snapshot. See this module's own doc comment for the full picture. */
|
|
35
|
+
export interface ChangeModel {
|
|
36
|
+
readonly schemaVersion: typeof CHANGE_MODEL_SCHEMA_VERSION;
|
|
37
|
+
/** The existing manifest change report, unmodified: see ADR 0021. `addedVariables`/`removedVariables` still list a correlated rename's two halves separately; `renamedVariables` below is an additive, separately-computed view, not a filter over this field. */
|
|
38
|
+
readonly manifest: ManifestChangeReport;
|
|
39
|
+
/**
|
|
40
|
+
* Every `addedVariables`/`removedVariables` pair this run's currently
|
|
41
|
+
* declared `renamedFrom` values correlate into a single rename, sorted by
|
|
42
|
+
* contract identity then current key.
|
|
43
|
+
*
|
|
44
|
+
* @remarks
|
|
45
|
+
* Only ever populated from an *authored* `renamedFrom`: never guessed
|
|
46
|
+
* from name similarity (ADR 0010's "provable, not heuristic" ethos).
|
|
47
|
+
* Variable-level only: Lifecycle Model deliberately has no contract-level
|
|
48
|
+
* `renamedFrom` (ADR 0029), so there is no `renamedContracts`; a
|
|
49
|
+
* contract-level rename has no field to correlate from.
|
|
50
|
+
*/
|
|
51
|
+
readonly renamedVariables: readonly RenamedVariable[];
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Wraps an already-computed `ManifestChangeReport` (e.g.
|
|
55
|
+
* `generateEnvArtifacts()`'s internal `evidenceChanges.report`) in the Change Model's versioned
|
|
56
|
+
* shape, and correlates renames using the current run's `renamedFrom`
|
|
57
|
+
* declarations. `currentContracts` should be the same contracts the
|
|
58
|
+
* manifest was generated from (active contracts only, matching
|
|
59
|
+
* `renderManifest()`'s own scope: same as every other input to this
|
|
60
|
+
* report family).
|
|
61
|
+
*/
|
|
62
|
+
export declare function buildChangeModel(manifest: ManifestChangeReport, currentContracts: readonly DiscoveredContract[], root: string): ChangeModel;
|
|
63
|
+
//# sourceMappingURL=change-model.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"change-model.d.ts","sourceRoot":"","sources":["../../../src/build/change-model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAuB,MAAM,wBAAwB,CAAA;AAEvF;;;;;;;;;;;;;;;;GAgBG;AAEH,uIAAuI;AACvI,eAAO,MAAM,2BAA2B,IAAI,CAAA;AAE5C,gKAAgK;AAChK,MAAM,WAAW,eAAe;IAC9B,kGAAkG;IAClG,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,kLAAkL;AAClL,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAA;IAC1D,kQAAkQ;IAClQ,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAA;IACvC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAA;CACtD;AAqBD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,oBAAoB,EAC9B,gBAAgB,EAAE,SAAS,kBAAkB,EAAE,EAC/C,IAAI,EAAE,MAAM,GACX,WAAW,CAqCb"}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import type { GenerateEnvArtifactsOptions } from "./generate-env-artifacts.js";
|
|
2
|
+
/**
|
|
3
|
+
* `--check` / drift-guard support: computes every requested artifact exactly
|
|
4
|
+
* as a real run would, but never writes to any of the four real target
|
|
5
|
+
* paths. See ADR 0016.
|
|
6
|
+
*/
|
|
7
|
+
/** One artifact's drift status, as found by {@link checkEnvArtifacts}. */
|
|
8
|
+
export interface ArtifactCheckFinding {
|
|
9
|
+
/** Which generated artifact this finding is about. */
|
|
10
|
+
readonly artifact: "manifest" | "docs" | "envExample" | "usage" | "evidence";
|
|
11
|
+
/** Absolute path the artifact would be written to. */
|
|
12
|
+
readonly path: string;
|
|
13
|
+
/** `"missing"` if the file doesn't exist yet, `"stale"` if it exists but differs from what a real run would produce. */
|
|
14
|
+
readonly status: "ok" | "stale" | "missing";
|
|
15
|
+
/** Human-readable detail, set for `"stale"`/`"missing"` findings. */
|
|
16
|
+
readonly detail?: string;
|
|
17
|
+
}
|
|
18
|
+
/** The result of a completed {@link checkEnvArtifacts} run. */
|
|
19
|
+
export interface CheckEnvArtifactsResult {
|
|
20
|
+
/** `true` iff every requested artifact is `"ok"`. */
|
|
21
|
+
readonly ok: boolean;
|
|
22
|
+
/** One entry per requested artifact. */
|
|
23
|
+
readonly findings: readonly ArtifactCheckFinding[];
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Parses `text` as an `EvidenceModel` and re-serializes it with
|
|
27
|
+
* `provenance.generatedAt` normalized out (see `normalizeEvidenceSnapshotForComparison()`):
|
|
28
|
+
* so `--check` never reports drift solely because a fresh render's
|
|
29
|
+
* timestamp differs from the committed file's. A parse failure returns
|
|
30
|
+
* `text` unchanged, so a corrupted on-disk file simply fails to match
|
|
31
|
+
* `expected`'s normalized form (reported as `"stale"`), rather than
|
|
32
|
+
* crashing `--check` itself.
|
|
33
|
+
*/
|
|
34
|
+
/** @internal Exported for direct unit coverage: reached through `checkEnvArtifacts()`'s `--evidence` pass in production, but the exact "returns text unchanged, not undefined/thrown" catch behavior isn't independently observable through that public path (any malformed `actual` already reads as "stale" against a well-formed `expected`, regardless of the catch's exact return value). */
|
|
35
|
+
export declare function normalizeEvidenceJsonForComparison(text: string): string;
|
|
36
|
+
/**
|
|
37
|
+
* Verifies every requested artifact (`manifest`/`docs`/`envExample`/`usage`)
|
|
38
|
+
* matches what a real {@link generateEnvArtifacts} run would produce, without
|
|
39
|
+
* writing anything.
|
|
40
|
+
*
|
|
41
|
+
* @remarks
|
|
42
|
+
* `--check` reports drift, it doesn't paper over a run that would otherwise fail:
|
|
43
|
+
* see `@throws` below.
|
|
44
|
+
*
|
|
45
|
+
* @throws {EnvProjectGenerationError} On the same blocking findings a real run would throw on.
|
|
46
|
+
*/
|
|
47
|
+
export declare function checkEnvArtifacts(options: GenerateEnvArtifactsOptions): Promise<CheckEnvArtifactsResult>;
|
|
48
|
+
//# sourceMappingURL=check-artifacts.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"check-artifacts.d.ts","sourceRoot":"","sources":["../../../src/build/check-artifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAA;AAU9E;;;;GAIG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,UAAU,CAAA;IAC5E,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wHAAwH;IACxH,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAA;IAC3C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,uBAAuB;IACtC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAA;CACnD;AAOD;;;;;;;;GAQG;AACH,kYAAkY;AAClY,wBAAgB,kCAAkC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvE;AAqBD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,uBAAuB,CAAC,CAwFlC"}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Re-verifies developer-declared `dynamicAccess` citations every run: never
|
|
3
|
+
* trusted forever (ADR 0037). Two independent steps, kept as two separate
|
|
4
|
+
* functions rather than one, since they answer two different questions and
|
|
5
|
+
* the second is a pure read over the first's result:
|
|
6
|
+
*
|
|
7
|
+
* - `buildCitationSnapshots` (this run, I/O): for every currently-declared
|
|
8
|
+
* citation, resolves the cited file and computes a whole-file SHA-256, then
|
|
9
|
+
* compares it against the *previous* evidence snapshot's recorded hash to
|
|
10
|
+
* label the citation `"fresh"` / `"stale"` / `"missing"`. Existence is
|
|
11
|
+
* always re-checked live, never trusted from either snapshot. A citation
|
|
12
|
+
* with no previous baseline (the first time it's ever been seen) is
|
|
13
|
+
* `"fresh"`: there is nothing to contradict it yet. Never throws on a
|
|
14
|
+
* missing file; that citation is simply labeled `"missing"`.
|
|
15
|
+
* - `verifyDynamicAccessCitations` (pure): flattens that result down to just
|
|
16
|
+
* the citations that need a human's attention; every `"stale"`/`"missing"`
|
|
17
|
+
* assertion, enriched with the owning contract's display name. These are the
|
|
18
|
+
* direct input to `finding-model.ts`'s `STALE_DYNAMIC_ACCESS_CITATION` /
|
|
19
|
+
* `MISSING_DYNAMIC_ACCESS_CITATION` findings.
|
|
20
|
+
*
|
|
21
|
+
* Deliberately separate from `evidence-snapshot.ts`'s own `diffContracts()`,
|
|
22
|
+
* which stays synchronous and pure: these are the only filesystem-touching,
|
|
23
|
+
* citation-specific part of the evidence-snapshot lifecycle. A citation is
|
|
24
|
+
* always a developer's *re-acknowledgment* that access happens, never a claim
|
|
25
|
+
* env-cap itself observed anything: nothing here ever folds into the
|
|
26
|
+
* AST-derived `VariableAccessStatus`.
|
|
27
|
+
*/
|
|
28
|
+
import type { EvidenceModel } from "./evidence-model.js";
|
|
29
|
+
import type { DiscoveredContract } from "./link.js";
|
|
30
|
+
import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
|
|
31
|
+
/** Stable key {@link buildCitationSnapshots} and `dependency-graph.ts`'s consumer of it agree on: `file` must be root-relative, POSIX-separated on both sides for a lookup to ever hit. */
|
|
32
|
+
export declare function dynamicAccessVariableIdentity(file: string, exportName: string, key: string): string;
|
|
33
|
+
/**
|
|
34
|
+
* Re-checks every current `dynamicAccess` citation against the previous
|
|
35
|
+
* evidence snapshot's committed `contentHash` baseline. Existence is always
|
|
36
|
+
* re-checked live (never trusted from either snapshot). Content drift is
|
|
37
|
+
* only detectable when a previous baseline exists. A citation with no
|
|
38
|
+
* previous baseline (the first time it's seen) is reported `"fresh"`,
|
|
39
|
+
* because nothing contradicts it yet. See ADR 0037.
|
|
40
|
+
*/
|
|
41
|
+
export declare function buildCitationSnapshots(activeContracts: readonly DiscoveredContract[], previous: EvidenceModel | undefined, root: string, readFile: (filePath: string) => Promise<string>): Promise<ReadonlyMap<string, readonly DynamicAccessAssertion[]>>;
|
|
42
|
+
/** One `dynamicAccess` citation env-cap can no longer vouch for: the direct input to `finding-model.ts`'s `"STALE_DYNAMIC_ACCESS_CITATION"`/`"MISSING_DYNAMIC_ACCESS_CITATION"` findings. See ADR 0037. */
|
|
43
|
+
export interface DynamicAccessCitationProblem {
|
|
44
|
+
readonly contractName: string;
|
|
45
|
+
/** Root-relative, POSIX-separated. */
|
|
46
|
+
readonly file: string;
|
|
47
|
+
readonly exportName: string;
|
|
48
|
+
/** The variable whose `dynamicAccess` citation this is. */
|
|
49
|
+
readonly key: string;
|
|
50
|
+
/** Where the citation points: not the variable's own declaration. */
|
|
51
|
+
readonly position: SourcePosition;
|
|
52
|
+
readonly acknowledgment: "stale" | "missing";
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Flattens {@link buildCitationSnapshots}' result down to just the citations
|
|
56
|
+
* that need attention: every `"stale"`/`"missing"` assertion, enriched with
|
|
57
|
+
* the owning contract's display name. `"fresh"` assertions are silently
|
|
58
|
+
* omitted: nothing to report about a citation that's still trustworthy.
|
|
59
|
+
*/
|
|
60
|
+
export declare function verifyDynamicAccessCitations(activeContracts: readonly DiscoveredContract[], root: string, acknowledgments: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): readonly DynamicAccessCitationProblem[];
|
|
61
|
+
//# sourceMappingURL=citation-verification.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"citation-verification.d.ts","sourceRoot":"","sources":["../../../src/build/citation-verification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAOlF,2LAA2L;AAC3L,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GACV,MAAM,CAER;AAyBD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC9C,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,CAAC,CAmCjE;AAED,2MAA2M;AAC3M,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,SAAS,CAAA;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,GACtE,SAAS,4BAA4B,EAAE,CA4BzC"}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import type { DiscoveredContract } from "./link.js";
|
|
2
|
+
/**
|
|
3
|
+
* Every stable `code` a check in this file (or `exclusive-group.ts`) can
|
|
4
|
+
* emit. Documented as an enumerated union so a consumer filtering/linking on
|
|
5
|
+
* `code` has a closed list to switch over, rather than an arbitrary string:
|
|
6
|
+
* see ADR 0024/0026. `exclusive-group.ts`'s check does not (yet) set one; see
|
|
7
|
+
* that file's own comment for why.
|
|
8
|
+
*/
|
|
9
|
+
export type CompatibilityIssueCode = "PROCESSOR_RETURN_TYPE_CONFLICT" | "PROCESSOR_SOURCE_CONFLICT" | "VALIDATOR_SOURCE_CONFLICT" | "DUPLICATE_VARIABLE_DOCUMENTATION" | "DUPLICATE_VARIABLE_SHAPE_ACROSS_CONTRACTS";
|
|
10
|
+
/** One compatibility problem found between two or more declarations of the same variable, or an exclusive-group violation. */
|
|
11
|
+
export interface CompatibilityIssue {
|
|
12
|
+
/** `"error"` blocks generation regardless of `onIncompatibility`; `"warning"` blocks only when `onIncompatibility: "throw"`; `"info"` never blocks, under any flag. */
|
|
13
|
+
readonly severity: "error" | "warning" | "info";
|
|
14
|
+
/** The environment variable name, or `"(contract) <name>"` for a contract-level (e.g. exclusive-group) issue. */
|
|
15
|
+
readonly variable: string;
|
|
16
|
+
/**
|
|
17
|
+
* Every file declaring a conflicting definition. A pairwise comparison
|
|
18
|
+
* (compatibility.ts, exclusive-group.ts) always produces exactly two. A
|
|
19
|
+
* finding escalated from another family (generate-env-artifacts.ts's
|
|
20
|
+
* `escalatedFindings()`, via `findingFiles()`) can produce zero, one, or
|
|
21
|
+
* two, depending on the location information that finding carries. So
|
|
22
|
+
* the arity varies, and this is not a tuple.
|
|
23
|
+
*/
|
|
24
|
+
readonly files: readonly string[];
|
|
25
|
+
/** Human-readable explanation of the conflict. */
|
|
26
|
+
readonly reason: string;
|
|
27
|
+
/**
|
|
28
|
+
* Stable, machine-readable identifier for CI filtering / doc-linking /
|
|
29
|
+
* GitHub Action annotations / IDE integration. `undefined` only for checks
|
|
30
|
+
* that don't set one yet. {@link CompatibilityIssueCode} lists every value
|
|
31
|
+
* a check in this file can produce.
|
|
32
|
+
*/
|
|
33
|
+
readonly code?: CompatibilityIssueCode;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Flags cases where two contracts declare the same variable name but appear to
|
|
37
|
+
* disagree about its shape. A human can then confirm they're still meant to be "the same" var.
|
|
38
|
+
*
|
|
39
|
+
* @remarks
|
|
40
|
+
* Duplicate variable names across contracts are not a merge problem. Each
|
|
41
|
+
* contract processes its own copy of the raw value; there is no runtime
|
|
42
|
+
* merge at all. This is purely a build-time lint.
|
|
43
|
+
*
|
|
44
|
+
* Only one thing is treated as *provable* without executing code: two
|
|
45
|
+
* processors with explicit, differing `: T` return type annotations. That is
|
|
46
|
+
* a hard error. Everything else (differing processor/validator source text
|
|
47
|
+
* with no annotation, or none at all) is a warning. Static analysis alone
|
|
48
|
+
* cannot prove semantic non-equivalence. And the library never executes
|
|
49
|
+
* schema code to check further (see literal-eval.ts).
|
|
50
|
+
*/
|
|
51
|
+
export declare function detectCompatibilityIssues(contracts: readonly DiscoveredContract[]): CompatibilityIssue[];
|
|
52
|
+
/**
|
|
53
|
+
* Flags *differently-named* variables in different contracts that share an
|
|
54
|
+
* identical type shape. It is a soft signal that two features may model the
|
|
55
|
+
* same configuration value under two names. That is worth a human glance
|
|
56
|
+
* before they drift apart.
|
|
57
|
+
*
|
|
58
|
+
* @remarks
|
|
59
|
+
* Always `severity: "info"`, and never escalated to blocking by any flag,
|
|
60
|
+
* including `--strict`. An identical shape is common and often correct. Two
|
|
61
|
+
* unrelated features can both take a `number` timeout with a validator, and
|
|
62
|
+
* that is not a defect. This is an observation for a reader, not a rule. A
|
|
63
|
+
* blockable version would be noise a team has to suppress, not a signal
|
|
64
|
+
* they can scan.
|
|
65
|
+
*
|
|
66
|
+
* Scope, deliberately narrow on every axis:
|
|
67
|
+
* - **Different keys only.** Same-key collisions across contracts are
|
|
68
|
+
* `detectCompatibilityIssues()`'s own, entirely separate concern above;
|
|
69
|
+
* reporting them here too would double-report one problem under two codes.
|
|
70
|
+
* - **Different contracts only.** Two same-shaped variables inside one
|
|
71
|
+
* contract are that contract's own deliberate design.
|
|
72
|
+
* - **Active contracts only.** An inactive contract is wired into nothing,
|
|
73
|
+
* so an overlap with it is not a live duplication.
|
|
74
|
+
* - **No exclusive-grouped contracts.** Members of an exclusive group are
|
|
75
|
+
* interchangeable alternatives by explicit authorial declaration:
|
|
76
|
+
* matching shapes there are the *point*, not a smell.
|
|
77
|
+
* - **Pairwise, never transitive.** Three mutually-matching variables emit
|
|
78
|
+
* three independent findings (A-B, A-C, B-C), never one merged "cluster".
|
|
79
|
+
* Each pair is its own question a reader answers on its own. A cluster
|
|
80
|
+
* would imply a transitive relationship this check never established.
|
|
81
|
+
*/
|
|
82
|
+
export declare function detectDuplicateVariableShapes(contracts: readonly DiscoveredContract[]): CompatibilityIssue[];
|
|
83
|
+
//# sourceMappingURL=compatibility.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../../../src/build/compatibility.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AAGvE;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAC9B,gCAAgC,GAChC,2BAA2B,GAC3B,2BAA2B,GAC3B,kCAAkC,GAClC,2CAA2C,CAAA;AAE/C,8HAA8H;AAC9H,MAAM,WAAW,kBAAkB;IACjC,uKAAuK;IACvK,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;IAC/C,iHAAiH;IACjH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,sBAAsB,CAAA;CACvC;AAkCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,kBAAkB,EAAE,CA+FtB;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,kBAAkB,EAAE,CAqDtB"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fails with a readable message when the resolved compiler lacks the classic API the scanner needs. The wording
|
|
3
|
+
* lives in `../_ipc/compiler-api.ts`, a managed copy of internal-package-contract's `runtime/compiler-api.ts`;
|
|
4
|
+
* this binds it to env-cap.
|
|
5
|
+
* @param compiler - The resolved compiler module (a parameter so a test can hand in a stand-in).
|
|
6
|
+
* @throws Error naming the installed version and how to restore the bundled compiler.
|
|
7
|
+
*/
|
|
8
|
+
export declare function assertCompilerApi(compiler: {
|
|
9
|
+
readonly createSourceFile?: unknown;
|
|
10
|
+
readonly version?: string;
|
|
11
|
+
}): void;
|
|
12
|
+
//# sourceMappingURL=compiler-api.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"compiler-api.d.ts","sourceRoot":"","sources":["../../../src/build/compiler-api.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE;IAC1C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B,GAAG,IAAI,CAEP"}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import { type EnvGovernanceFields } from "./governance-fields.js";
|
|
2
|
+
import type { DiscoveredContract } from "./link.js";
|
|
3
|
+
import type { DiscoveredVariableEvidence } from "./parse.js";
|
|
4
|
+
import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
|
|
5
|
+
import type { SourcePosition } from "./source-position.js";
|
|
6
|
+
/**
|
|
7
|
+
* The first of env-cap's seven canonical fact models (ADR 0024): a
|
|
8
|
+
* versioned, JSON-serializable projection of every declared environment
|
|
9
|
+
* variable's structural and documentation contract. See ADR 0025.
|
|
10
|
+
*
|
|
11
|
+
* @remarks
|
|
12
|
+
* Deliberately broader than the persisted evidence snapshot's
|
|
13
|
+
* (`evidence-snapshot.ts`) `ManifestChangeReport` scope: that diff is scoped
|
|
14
|
+
* to *active* contracts and *only* the `documentEnv()`-sourced fields,
|
|
15
|
+
* matching `renderManifest()`'s own scope (ADR 0021). This model includes
|
|
16
|
+
* every discovered contract regardless of `active`, plus the AST-derived
|
|
17
|
+
* schema facts (`hasDefault`/`hasProcessor`/etc.) the change report
|
|
18
|
+
* deliberately excludes: both are load-bearing for downstream
|
|
19
|
+
* Finding/Evidence Model work.
|
|
20
|
+
*/
|
|
21
|
+
/** Bump only when a reader could misinterpret the new shape (a field changes
|
|
22
|
+
* type/meaning, or is removed): NOT for every additive field. Same
|
|
23
|
+
* discipline `evidence-model.ts`'s `EVIDENCE_MODEL_SCHEMA_VERSION` and
|
|
24
|
+
* `src/cli/json.ts`'s `JSON_SCHEMA_VERSION` already document. */
|
|
25
|
+
export declare const CONTRACT_MODEL_SCHEMA_VERSION = 3;
|
|
26
|
+
/**
|
|
27
|
+
* One variable's full statically-discoverable contract: schema-shaped facts plus linked documentation.
|
|
28
|
+
*
|
|
29
|
+
* @see {@link DependencyModelVariable}: this same declared variable's access status.
|
|
30
|
+
* @see {@link OwnershipModelVariable}: this same declared variable's effective owner.
|
|
31
|
+
* @see {@link LifecycleModelVariable}: this same declared variable's lifecycle data.
|
|
32
|
+
* @see `CatalogVariable` (`docs.ts`): this same declared variable, reshaped for the generated
|
|
33
|
+
* docs catalog/JSON. Plain reference, not `{@link}`: `CatalogVariable` is intentionally not part
|
|
34
|
+
* of the public surface (see `typedoc.json`'s `intentionallyNotExported`).
|
|
35
|
+
*/
|
|
36
|
+
export interface ContractModelVariable extends EnvGovernanceFields {
|
|
37
|
+
readonly key: string;
|
|
38
|
+
readonly hasDefault: boolean;
|
|
39
|
+
readonly defaultValue: {
|
|
40
|
+
readonly ok: true;
|
|
41
|
+
readonly value: unknown;
|
|
42
|
+
} | {
|
|
43
|
+
readonly ok: false;
|
|
44
|
+
} | undefined;
|
|
45
|
+
readonly hasProcessor: boolean;
|
|
46
|
+
readonly processorSource: string | undefined;
|
|
47
|
+
readonly processorReturnType: string | undefined;
|
|
48
|
+
readonly hasValidator: boolean;
|
|
49
|
+
readonly validatorSource: string | undefined;
|
|
50
|
+
readonly context: string | undefined;
|
|
51
|
+
readonly description: string | undefined;
|
|
52
|
+
readonly refreshInstructions: string | undefined;
|
|
53
|
+
readonly setupInstructions: string | undefined;
|
|
54
|
+
readonly required: boolean | undefined;
|
|
55
|
+
readonly documented: boolean;
|
|
56
|
+
/** The `evidence` sub-object from this variable's linked documentation: re-verified every run, unlike every declared-only field above. See {@link runtime.VariableEvidenceDocs} and ADR 0037. */
|
|
57
|
+
readonly evidence: DiscoveredVariableEvidence | undefined;
|
|
58
|
+
/** Where this variable's own schema property is declared. See ADR 0036. */
|
|
59
|
+
readonly declaration: SourcePosition;
|
|
60
|
+
}
|
|
61
|
+
/** One `createEnv()` contract's full statically-discoverable contract, active or not. */
|
|
62
|
+
export interface ContractModelContract extends EnvGovernanceFields {
|
|
63
|
+
/** Root-relative, POSIX-separated: matches `DiscoveredContractSummary.file`. */
|
|
64
|
+
readonly file: string;
|
|
65
|
+
readonly exportName: string;
|
|
66
|
+
readonly contractName: string;
|
|
67
|
+
readonly active: boolean;
|
|
68
|
+
readonly category: string | undefined;
|
|
69
|
+
readonly exclusiveGroup: string | undefined;
|
|
70
|
+
readonly variables: readonly ContractModelVariable[];
|
|
71
|
+
readonly documented: boolean;
|
|
72
|
+
readonly packageOrigin: PackageOrigin | undefined;
|
|
73
|
+
/** Where this contract's `createEnv(...)` call is declared. Always present. See ADR 0036. */
|
|
74
|
+
readonly declaration: SourcePosition;
|
|
75
|
+
/** Where this contract's `documentEnv(...)` call is declared, if one exists. See ADR 0036. */
|
|
76
|
+
readonly documentation: SourcePosition | undefined;
|
|
77
|
+
}
|
|
78
|
+
/** The versioned, JSON-serializable root of the Contract Model: every discovered `createEnv()` contract (active or not), each with its own full statically-discoverable shape. See {@link ContractModelContract}. */
|
|
79
|
+
export interface ContractModel {
|
|
80
|
+
readonly schemaVersion: typeof CONTRACT_MODEL_SCHEMA_VERSION;
|
|
81
|
+
readonly contracts: readonly ContractModelContract[];
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Projects every discovered contract (active or not) into the Contract
|
|
85
|
+
* Model's versioned, JSON-serializable shape.
|
|
86
|
+
*
|
|
87
|
+
* @remarks
|
|
88
|
+
* Sorted deterministically (by file, then exportName, then variable key), so
|
|
89
|
+
* `JSON.stringify` output is stable and diffs cleanly wherever this is
|
|
90
|
+
* persisted.
|
|
91
|
+
*/
|
|
92
|
+
export declare function buildContractModel(contracts: readonly DiscoveredContract[], root: string): ContractModel;
|
|
93
|
+
//# sourceMappingURL=contract-model.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"contract-model.d.ts","sourceRoot":"","sources":["../../../src/build/contract-model.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AACrF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAmB1D;;;;;;;;;;;;;;GAcG;AAEH;;;kEAGkE;AAClE,eAAO,MAAM,6BAA6B,IAAI,CAAA;AAE9C;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,YAAY,EACnB;QAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG;QAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;KAAE,GAAG,SAAS,CAAA;IACrF,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9C,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,iMAAiM;IACjM,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,GAAG,SAAS,CAAA;IACzD,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAA;CACrC;AAED,yFAAyF;AACzF,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAA;IACpD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,SAAS,CAAA;IACjD,6FAA6F;IAC7F,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAA;IACpC,8FAA8F;IAC9F,QAAQ,CAAC,aAAa,EAAE,cAAc,GAAG,SAAS,CAAA;CACnD;AAED,qNAAqN;AACrN,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,6BAA6B,CAAA;IAC5D,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAA;CACrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,IAAI,EAAE,MAAM,GACX,aAAa,CAmDf"}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Structural equality for JSON-safe values: `documentEnv()`'s `metadata` can hold an
|
|
3
|
+
* object/array (ADR 0035), so two independently-declared-but-identical values are never `===`.
|
|
4
|
+
* Values compared here are always JSON-safe (string/number/boolean/null/array/object,
|
|
5
|
+
* recursively: see `literal-eval.ts`), so this doesn't need to handle cycles, `Date`, `Map`, or
|
|
6
|
+
* anything else `evaluateLiteral()` can never produce.
|
|
7
|
+
*/
|
|
8
|
+
export declare function deepEqual(a: unknown, b: unknown): boolean;
|
|
9
|
+
//# sourceMappingURL=deep-equal.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"deep-equal.d.ts","sourceRoot":"","sources":["../../../src/build/deep-equal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAezD"}
|