@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
|
@@ -2,7 +2,7 @@ import type { DiscoveredContract } from "./link.js";
|
|
|
2
2
|
/**
|
|
3
3
|
* Every stable `code` a check in this file (or `exclusive-group.ts`) can
|
|
4
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
|
|
5
|
+
* `code` has a closed list to switch over, rather than an arbitrary string:
|
|
6
6
|
* see ADR 0024/0026. `exclusive-group.ts`'s check does not (yet) set one; see
|
|
7
7
|
* that file's own comment for why.
|
|
8
8
|
*/
|
|
@@ -15,11 +15,11 @@ export interface CompatibilityIssue {
|
|
|
15
15
|
readonly variable: string;
|
|
16
16
|
/**
|
|
17
17
|
* Every file declaring a conflicting definition. A pairwise comparison
|
|
18
|
-
* (compatibility.ts, exclusive-group.ts) always produces exactly two
|
|
18
|
+
* (compatibility.ts, exclusive-group.ts) always produces exactly two. A
|
|
19
19
|
* finding escalated from another family (generate-env-artifacts.ts's
|
|
20
20
|
* `escalatedFindings()`, via `findingFiles()`) can produce zero, one, or
|
|
21
|
-
* two, depending on
|
|
22
|
-
*
|
|
21
|
+
* two, depending on the location information that finding carries. So
|
|
22
|
+
* the arity varies, and this is not a tuple.
|
|
23
23
|
*/
|
|
24
24
|
readonly files: readonly string[];
|
|
25
25
|
/** Human-readable explanation of the conflict. */
|
|
@@ -27,41 +27,41 @@ export interface CompatibilityIssue {
|
|
|
27
27
|
/**
|
|
28
28
|
* Stable, machine-readable identifier for CI filtering / doc-linking /
|
|
29
29
|
* GitHub Action annotations / IDE integration. `undefined` only for checks
|
|
30
|
-
* that don't
|
|
31
|
-
*
|
|
30
|
+
* that don't set one yet. {@link CompatibilityIssueCode} lists every value
|
|
31
|
+
* a check in this file can produce.
|
|
32
32
|
*/
|
|
33
33
|
readonly code?: CompatibilityIssueCode;
|
|
34
34
|
}
|
|
35
35
|
/**
|
|
36
36
|
* Flags cases where two contracts declare the same variable name but appear to
|
|
37
|
-
* disagree about its shape
|
|
37
|
+
* disagree about its shape. A human can then confirm they're still meant to be "the same" var.
|
|
38
38
|
*
|
|
39
39
|
* @remarks
|
|
40
|
-
* Duplicate variable names across contracts are not a merge problem
|
|
41
|
-
* contract
|
|
42
|
-
*
|
|
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
43
|
*
|
|
44
44
|
* Only one thing is treated as *provable* without executing code: two
|
|
45
45
|
* processors with explicit, differing `: T` return type annotations. That is
|
|
46
46
|
* a hard error. Everything else (differing processor/validator source text
|
|
47
|
-
* with no annotation, or none at all) is a warning
|
|
48
|
-
* semantic non-equivalence
|
|
49
|
-
*
|
|
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
50
|
*/
|
|
51
51
|
export declare function detectCompatibilityIssues(contracts: readonly DiscoveredContract[]): CompatibilityIssue[];
|
|
52
52
|
/**
|
|
53
53
|
* Flags *differently-named* variables in different contracts that share an
|
|
54
|
-
* identical type shape
|
|
55
|
-
*
|
|
56
|
-
*
|
|
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
57
|
*
|
|
58
58
|
* @remarks
|
|
59
59
|
* Always `severity: "info"`, and never escalated to blocking by any flag,
|
|
60
|
-
* including `--strict
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
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
65
|
*
|
|
66
66
|
* Scope, deliberately narrow on every axis:
|
|
67
67
|
* - **Different keys only.** Same-key collisions across contracts are
|
|
@@ -72,11 +72,11 @@ export declare function detectCompatibilityIssues(contracts: readonly Discovered
|
|
|
72
72
|
* - **Active contracts only.** An inactive contract is wired into nothing,
|
|
73
73
|
* so an overlap with it is not a live duplication.
|
|
74
74
|
* - **No exclusive-grouped contracts.** Members of an exclusive group are
|
|
75
|
-
* interchangeable alternatives by explicit authorial declaration
|
|
75
|
+
* interchangeable alternatives by explicit authorial declaration:
|
|
76
76
|
* matching shapes there are the *point*, not a smell.
|
|
77
77
|
* - **Pairwise, never transitive.** Three mutually-matching variables emit
|
|
78
|
-
* three independent findings (A-B, A-C, B-C), never one merged "cluster"
|
|
79
|
-
*
|
|
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
80
|
* would imply a transitive relationship this check never established.
|
|
81
81
|
*/
|
|
82
82
|
export declare function detectDuplicateVariableShapes(contracts: readonly DiscoveredContract[]): CompatibilityIssue[];
|
|
@@ -1 +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,
|
|
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"}
|
|
@@ -4,7 +4,7 @@ import type { DiscoveredVariableEvidence } from "./parse.js";
|
|
|
4
4
|
import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
|
|
5
5
|
import type { SourcePosition } from "./source-position.js";
|
|
6
6
|
/**
|
|
7
|
-
* The first of env-cap's seven canonical fact models (ADR 0024)
|
|
7
|
+
* The first of env-cap's seven canonical fact models (ADR 0024): a
|
|
8
8
|
* versioned, JSON-serializable projection of every declared environment
|
|
9
9
|
* variable's structural and documentation contract. See ADR 0025.
|
|
10
10
|
*
|
|
@@ -15,21 +15,21 @@ import type { SourcePosition } from "./source-position.js";
|
|
|
15
15
|
* matching `renderManifest()`'s own scope (ADR 0021). This model includes
|
|
16
16
|
* every discovered contract regardless of `active`, plus the AST-derived
|
|
17
17
|
* schema facts (`hasDefault`/`hasProcessor`/etc.) the change report
|
|
18
|
-
* deliberately excludes
|
|
18
|
+
* deliberately excludes: both are load-bearing for downstream
|
|
19
19
|
* Finding/Evidence Model work.
|
|
20
20
|
*/
|
|
21
21
|
/** Bump only when a reader could misinterpret the new shape (a field changes
|
|
22
|
-
* type/meaning, or is removed)
|
|
22
|
+
* type/meaning, or is removed): NOT for every additive field. Same
|
|
23
23
|
* discipline `evidence-model.ts`'s `EVIDENCE_MODEL_SCHEMA_VERSION` and
|
|
24
24
|
* `src/cli/json.ts`'s `JSON_SCHEMA_VERSION` already document. */
|
|
25
25
|
export declare const CONTRACT_MODEL_SCHEMA_VERSION = 3;
|
|
26
26
|
/**
|
|
27
27
|
* One variable's full statically-discoverable contract: schema-shaped facts plus linked documentation.
|
|
28
28
|
*
|
|
29
|
-
* @see {@link DependencyModelVariable}
|
|
30
|
-
* @see {@link OwnershipModelVariable}
|
|
31
|
-
* @see {@link LifecycleModelVariable}
|
|
32
|
-
* @see `CatalogVariable` (`docs.ts`)
|
|
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
33
|
* docs catalog/JSON. Plain reference, not `{@link}`: `CatalogVariable` is intentionally not part
|
|
34
34
|
* of the public surface (see `typedoc.json`'s `intentionallyNotExported`).
|
|
35
35
|
*/
|
|
@@ -53,14 +53,14 @@ export interface ContractModelVariable extends EnvGovernanceFields {
|
|
|
53
53
|
readonly setupInstructions: string | undefined;
|
|
54
54
|
readonly required: boolean | undefined;
|
|
55
55
|
readonly documented: boolean;
|
|
56
|
-
/** The `evidence` sub-object from this variable's linked documentation
|
|
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
57
|
readonly evidence: DiscoveredVariableEvidence | undefined;
|
|
58
58
|
/** Where this variable's own schema property is declared. See ADR 0036. */
|
|
59
59
|
readonly declaration: SourcePosition;
|
|
60
60
|
}
|
|
61
61
|
/** One `createEnv()` contract's full statically-discoverable contract, active or not. */
|
|
62
62
|
export interface ContractModelContract extends EnvGovernanceFields {
|
|
63
|
-
/** Root-relative, POSIX-separated
|
|
63
|
+
/** Root-relative, POSIX-separated: matches `DiscoveredContractSummary.file`. */
|
|
64
64
|
readonly file: string;
|
|
65
65
|
readonly exportName: string;
|
|
66
66
|
readonly contractName: string;
|
|
@@ -75,7 +75,7 @@ export interface ContractModelContract extends EnvGovernanceFields {
|
|
|
75
75
|
/** Where this contract's `documentEnv(...)` call is declared, if one exists. See ADR 0036. */
|
|
76
76
|
readonly documentation: SourcePosition | undefined;
|
|
77
77
|
}
|
|
78
|
-
/** The versioned, JSON-serializable root of the Contract Model
|
|
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
79
|
export interface ContractModel {
|
|
80
80
|
readonly schemaVersion: typeof CONTRACT_MODEL_SCHEMA_VERSION;
|
|
81
81
|
readonly contracts: readonly ContractModelContract[];
|
|
@@ -1 +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,
|
|
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"}
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Structural equality for JSON-safe values
|
|
2
|
+
* Structural equality for JSON-safe values: `documentEnv()`'s `metadata` can hold an
|
|
3
3
|
* object/array (ADR 0035), so two independently-declared-but-identical values are never `===`.
|
|
4
4
|
* Values compared here are always JSON-safe (string/number/boolean/null/array/object,
|
|
5
|
-
* recursively
|
|
5
|
+
* recursively: see `literal-eval.ts`), so this doesn't need to handle cycles, `Date`, `Map`, or
|
|
6
6
|
* anything else `evaluateLiteral()` can never produce.
|
|
7
7
|
*/
|
|
8
8
|
export declare function deepEqual(a: unknown, b: unknown): boolean;
|
|
@@ -9,8 +9,8 @@
|
|
|
9
9
|
* utility, so Evidence Model's own immutability guarantee (a later phase)
|
|
10
10
|
* can reuse it instead of duplicating the recursion.
|
|
11
11
|
*
|
|
12
|
-
* Only recurses into arrays and plain objects (`{}` or `Object.create(null)`)
|
|
13
|
-
*
|
|
12
|
+
* Only recurses into arrays and plain objects (`{}` or `Object.create(null)`):
|
|
13
|
+
* a `Map`, `Set`, or class instance is frozen at its own top level but not
|
|
14
14
|
* walked further. This codebase's fact models are plain JSON-serializable
|
|
15
15
|
* data, never class instances, so this is deliberately narrow rather than a
|
|
16
16
|
* general-purpose deep-freeze library. A `WeakSet` guards against infinite
|
|
@@ -4,66 +4,61 @@ import type { DiscoveredContract } from "./link.js";
|
|
|
4
4
|
import type { ParseWarning } from "./parse.js";
|
|
5
5
|
import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
|
|
6
6
|
/**
|
|
7
|
-
* What env-cap's static scan could prove about one variable's consumption
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
* (`"indeterminate"`).
|
|
7
|
+
* What env-cap's static scan could prove about one variable's consumption.
|
|
8
|
+
* It was member-accessed somewhere (`"used"`), or never accessed within the
|
|
9
|
+
* scanned surfaces (`"unconsumed"`). Or a computed (dynamic) property access
|
|
10
|
+
* on the owning contract makes the answer unprovable (`"indeterminate"`).
|
|
12
11
|
*
|
|
13
12
|
* @remarks
|
|
14
|
-
* Deliberately narrower than `data-cap`'s equivalent
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
* names the key statically (`"used"`) or it doesn't (`"indeterminate"`)
|
|
21
|
-
*
|
|
22
|
-
* consumed is ambiguous.
|
|
23
|
-
*
|
|
24
|
-
* "provable, not heuristic" rule. Developer-declared `dynamicAccess`
|
|
13
|
+
* Deliberately narrower than `data-cap`'s equivalent. That one splits the
|
|
14
|
+
* unprovable case further (an unresolved *consumer* vs. an indeterminate
|
|
15
|
+
* *field*). That split exists because a data-cap capability exposes many
|
|
16
|
+
* fields at once. It has a real "we resolved the consumer, but can't tell
|
|
17
|
+
* which field it touched" state to name. In env-cap, the consumption model
|
|
18
|
+
* is one value per key. A contract member access either
|
|
19
|
+
* names the key statically (`"used"`) or it doesn't (`"indeterminate"`).
|
|
20
|
+
* There is no intermediate case where the consumer is known but the thing
|
|
21
|
+
* consumed is ambiguous. A fourth state here would borrow vocabulary from a
|
|
22
|
+
* model env-cap doesn't have: see ADR 0010's "provable, not heuristic" rule. Developer-declared `dynamicAccess`
|
|
25
23
|
* citations stay a wholly separate fact and are never folded into this
|
|
26
24
|
* status (ADR 0037).
|
|
27
25
|
*/
|
|
28
26
|
export type VariableAccessStatus = "used" | "unconsumed" | "indeterminate";
|
|
29
27
|
/**
|
|
30
28
|
* Every reason `deriveOwnershipFindings` can cite for an `indeterminate`
|
|
31
|
-
* variable, cited on the {@link EscapeSite} the scanner actually observed
|
|
32
|
-
* `EscapeReason`
|
|
33
|
-
* follow
|
|
34
|
-
* mentioned bare (passed as an argument, spread, assigned elsewhere, ...)
|
|
35
|
-
* a real, provable read of the contract
|
|
36
|
-
* can't attribute to any specific key.
|
|
29
|
+
* variable, cited on the {@link EscapeSite} the scanner actually observed.
|
|
30
|
+
* `EscapeReason` covers destructuring/aliasing shapes the scanner declines to
|
|
31
|
+
* follow (see ADR 0039). `"reference"` covers a tracked import/alias
|
|
32
|
+
* mentioned bare (passed as an argument, spread, assigned elsewhere, ...).
|
|
33
|
+
* That is a real, provable read of the contract, but this single-file walk
|
|
34
|
+
* can't attribute it to any specific key.
|
|
37
35
|
*/
|
|
38
36
|
type EscapeVia = EscapeReason | "reference";
|
|
39
|
-
/** One position where a tracked contract's value escaped this scanner's local dataflow analysis
|
|
37
|
+
/** One position where a tracked contract's value escaped this scanner's local dataflow analysis: see {@link EscapeVia}. */
|
|
40
38
|
interface EscapeSite extends SourcePosition {
|
|
41
39
|
readonly via: EscapeVia;
|
|
42
40
|
}
|
|
43
41
|
interface VariableAccessInfo {
|
|
44
42
|
readonly status: VariableAccessStatus;
|
|
45
|
-
/** Internal only, never exposed publicly
|
|
46
|
-
* this status
|
|
47
|
-
*
|
|
48
|
-
* by hand. */
|
|
43
|
+
/** Internal only, never exposed publicly: which AST evidence produced
|
|
44
|
+
* this status. A "why does env-cap think this is unconsumed" bug report
|
|
45
|
+
* is then debuggable without re-deriving the AST walk by hand. */
|
|
49
46
|
readonly evidence: "member-access" | "dynamic-access" | "escape" | "no-access";
|
|
50
47
|
/** Every position where a member access was observed for this variable,
|
|
51
|
-
* aggregated across every consuming file
|
|
52
|
-
* `status === "used"`.
|
|
53
|
-
* `
|
|
54
|
-
*
|
|
55
|
-
*
|
|
56
|
-
* line numbers) so `dependency-model.ts` can publish it. */
|
|
48
|
+
* aggregated across every consuming file: empty unless
|
|
49
|
+
* `status === "used"`. Taken from `scan-dependencies.ts`'s `AccessSite`
|
|
50
|
+
* so `dependency-model.ts` can publish it: the line since ADR 0027, the
|
|
51
|
+
* full position since ADR 0036. There is one entry per file, not a flat,
|
|
52
|
+
* file-less list of line numbers. */
|
|
57
53
|
readonly positions: readonly SourcePosition[];
|
|
58
|
-
/** Every developer-declared `dynamicAccess` citation's current freshness for this variable
|
|
54
|
+
/** Every developer-declared `dynamicAccess` citation's current freshness for this variable: a wholly separate, independent fact from `status`/`evidence` above, never folded into them. Empty unless the linked `documentEnv()` call declared at least one citation for this key. See ADR 0037. */
|
|
59
55
|
readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
|
|
60
56
|
}
|
|
61
|
-
/** One named surface `buildDependencyGraph()`'s scan actually covered
|
|
57
|
+
/** One named surface `buildDependencyGraph()`'s scan actually covered: the
|
|
62
58
|
* application's own root, plus one entry per allow-listed `packages` (ADR
|
|
63
|
-
* 0014) name whose source was also scanned. See ADR 0036
|
|
64
|
-
* "no consumer found" is only
|
|
65
|
-
*
|
|
66
|
-
* implying an unbounded guarantee it can't back up. */
|
|
59
|
+
* 0014) name whose source was also scanned. See ADR 0036. A claim like
|
|
60
|
+
* "no consumer found" is only as strong as what was searched. This lets a
|
|
61
|
+
* renderer say so explicitly, not imply an unbounded guarantee. */
|
|
67
62
|
export interface ScannedSurface {
|
|
68
63
|
/** `"application"` for the local project root, `"package:<name>"` for an allow-listed package's own source. */
|
|
69
64
|
readonly label: string;
|
|
@@ -78,7 +73,7 @@ interface ContractDependencySummary {
|
|
|
78
73
|
readonly hasDynamicAccess: boolean;
|
|
79
74
|
/** Every declared key is always present. */
|
|
80
75
|
readonly variables: ReadonlyMap<string, VariableAccessInfo>;
|
|
81
|
-
/** Every file coupled to this contract
|
|
76
|
+
/** Every file coupled to this contract: contract-level "who depends on
|
|
82
77
|
* this," not proof any specific variable was read. See the
|
|
83
78
|
* consumer-vs-variable-access semantics note in `deriveOwnershipFindings`. */
|
|
84
79
|
readonly consumingFiles: readonly string[];
|
|
@@ -87,13 +82,11 @@ interface ContractDependencySummary {
|
|
|
87
82
|
* re-export. */
|
|
88
83
|
readonly ambiguousBarrelFiles: readonly string[];
|
|
89
84
|
/** Every computed (dynamic) property-access site observed anywhere on
|
|
90
|
-
* this contract
|
|
91
|
-
*
|
|
92
|
-
* exactly where the uncertainty comes from instead of just asserting it
|
|
93
|
-
* exists. */
|
|
85
|
+
* this contract (ADR 0036). `hasDynamicAccess` only says that one exists.
|
|
86
|
+
* This list lets a finding cite where the uncertainty comes from. */
|
|
94
87
|
readonly dynamicAccessSites: readonly SourcePosition[];
|
|
95
88
|
/** Every position where the contract's value flowed somewhere this
|
|
96
|
-
* scanner's local dataflow analysis can't follow
|
|
89
|
+
* scanner's local dataflow analysis can't follow: see {@link
|
|
97
90
|
* EscapeVia} and ADR 0039. Like `dynamicAccessSites`, this widens every
|
|
98
91
|
* not-otherwise-accessed variable on the SAME contract to
|
|
99
92
|
* `indeterminate`, never `unconsumed`. */
|
|
@@ -102,7 +95,7 @@ interface ContractDependencySummary {
|
|
|
102
95
|
export interface DependencyGraph {
|
|
103
96
|
readonly contracts: readonly ContractDependencySummary[];
|
|
104
97
|
readonly warnings: readonly ParseWarning[];
|
|
105
|
-
/** Every surface actually scanned for usage
|
|
98
|
+
/** Every surface actually scanned for usage: see {@link ScannedSurface}. Always has at least one entry (the application root). */
|
|
106
99
|
readonly scannedSurfaces: readonly ScannedSurface[];
|
|
107
100
|
}
|
|
108
101
|
/** Sorts two positions by file, then line. @internal Exported for direct unit coverage. */
|
|
@@ -122,12 +115,12 @@ interface UnconsumedOwnedVariableOwnershipFinding extends AbandonedOwnershipFind
|
|
|
122
115
|
interface IndeterminateAccessOwnershipFinding extends AbandonedOwnershipFinding {
|
|
123
116
|
readonly key: string;
|
|
124
117
|
readonly reason: string;
|
|
125
|
-
/** Every AST-observed dynamic-access site on this contract
|
|
118
|
+
/** Every AST-observed dynamic-access site on this contract: see ADR 0036. */
|
|
126
119
|
readonly dynamicAccessSites: readonly SourcePosition[];
|
|
127
|
-
/** Every AST-observed escape site on this contract
|
|
120
|
+
/** Every AST-observed escape site on this contract: see {@link EscapeVia} and ADR 0039. */
|
|
128
121
|
readonly escapeSites: readonly EscapeSite[];
|
|
129
122
|
}
|
|
130
|
-
/** A variable that would otherwise be `unconsumedOwned`/`indeterminate`, but has at least one `"fresh"` developer-declared `dynamicAccess` assertion
|
|
123
|
+
/** A variable that would otherwise be `unconsumedOwned`/`indeterminate`, but has at least one `"fresh"` developer-declared `dynamicAccess` assertion: the "asserted" category (ADR 0037). Never silently dropped: the raw `wouldBeStatus` is always shown alongside the assertion, per Design 7's "never let a claim overwrite an observation" rule. */
|
|
131
124
|
interface AssertedOwnershipFinding extends AbandonedOwnershipFinding {
|
|
132
125
|
readonly key: string;
|
|
133
126
|
readonly wouldBeStatus: "unconsumed" | "indeterminate";
|
|
@@ -144,23 +137,23 @@ export interface OwnershipFindings {
|
|
|
144
137
|
* Derives ownership findings from the graph. This is where the epistemic
|
|
145
138
|
* rules that matter most live:
|
|
146
139
|
* - A contract never imported anywhere, with no ambiguous barrel path
|
|
147
|
-
* either, is `abandoned
|
|
140
|
+
* either, is `abandoned`; a feature's schema outliving the feature.
|
|
148
141
|
* - A contract never *directly* imported, but reachable only through an
|
|
149
|
-
* unresolved barrel re-export, is `unresolvedConsumers
|
|
142
|
+
* unresolved barrel re-export, is `unresolvedConsumers`: never
|
|
150
143
|
* `abandoned`. Claiming "abandoned" here would be a false positive with
|
|
151
144
|
* real consequences.
|
|
152
145
|
* - A variable with no member access anywhere, on a contract with no
|
|
153
|
-
* dynamic access anywhere, is `unconsumedOwned
|
|
154
|
-
* this repository,
|
|
146
|
+
* dynamic access anywhere, is `unconsumedOwned`. That means "no consumer
|
|
147
|
+
* found in this repository", not "provably dead". The scanned surfaces are named
|
|
155
148
|
* explicitly in the reason, per ADR 0036, so the claim is exactly as
|
|
156
149
|
* strong as what was actually searched.
|
|
157
150
|
* - A variable with no member access, but dynamic access observed
|
|
158
|
-
* *somewhere* on that contract, is `indeterminate
|
|
151
|
+
* *somewhere* on that contract, is `indeterminate`: never
|
|
159
152
|
* `unconsumedOwned`. Uncertainty is never promoted to certainty in either
|
|
160
153
|
* direction. Every candidate dynamic-access site is cited by name.
|
|
161
154
|
* - A variable with at least one `"fresh"` {@link DynamicAccessAssertion}
|
|
162
155
|
* (ADR 0037) gets neither `unconsumedOwned` nor `indeterminate`, regardless
|
|
163
|
-
* of `status
|
|
156
|
+
* of `status`: a developer has re-acknowledged the access exists. The
|
|
164
157
|
* Dependency Model itself still keeps `status` and the assertion side by
|
|
165
158
|
* side, unedited; only *this* finding-suppression decision reads them
|
|
166
159
|
* together.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../../../src/build/dependency-graph.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAc,YAAY,EAAkB,MAAM,wBAAwB,CAAA;AAEtF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAG7E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAElF
|
|
1
|
+
{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../../../src/build/dependency-graph.ts"],"names":[],"mappings":"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"}
|
|
@@ -5,77 +5,77 @@ import type { ParseWarning } from "./parse.js";
|
|
|
5
5
|
import type { ImportResolutionContext } from "./resolution/resolve-import.js";
|
|
6
6
|
import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
|
|
7
7
|
/**
|
|
8
|
-
* The second of env-cap's seven canonical fact models (ADR 0024)
|
|
8
|
+
* The second of env-cap's seven canonical fact models (ADR 0024): a
|
|
9
9
|
* versioned, JSON-serializable projection of the dependency-ownership
|
|
10
10
|
* engine's graph. See ADR 0027 and ADR 0036.
|
|
11
11
|
*
|
|
12
12
|
* @remarks
|
|
13
13
|
* `dependency-graph.ts`'s scanning/graph-building internals stay Private,
|
|
14
|
-
* unchanged, per ADR 0010
|
|
14
|
+
* unchanged, per ADR 0010: this is a fact-shaped *result* built on top of
|
|
15
15
|
* them, not a relaxation of that boundary. Graph-format rendering (DOT,
|
|
16
|
-
* Mermaid, a `{nodes, edges}` JSON export) is deliberately not here
|
|
16
|
+
* Mermaid, a `{nodes, edges}` JSON export) is deliberately not here:
|
|
17
17
|
* that's presentation over this model's data, not the model itself.
|
|
18
18
|
*/
|
|
19
|
-
/** Bump only when a reader could misinterpret the new shape
|
|
19
|
+
/** Bump only when a reader could misinterpret the new shape: same discipline every other canonical model's `schemaVersion` follows. */
|
|
20
20
|
export declare const DEPENDENCY_MODEL_SCHEMA_VERSION = 2;
|
|
21
21
|
/**
|
|
22
22
|
* One variable's access status within a contract, plus every position it was found
|
|
23
23
|
* member-accessed at, aggregated across every consuming file.
|
|
24
24
|
*
|
|
25
|
-
* @see {@link ContractModelVariable}
|
|
25
|
+
* @see {@link ContractModelVariable}: this same declared variable's canonical starting point.
|
|
26
26
|
*/
|
|
27
27
|
export interface DependencyModelVariable {
|
|
28
28
|
readonly key: string;
|
|
29
29
|
readonly status: VariableAccessStatus;
|
|
30
|
-
/** Empty unless `status === "used"`.
|
|
30
|
+
/** Empty unless `status === "used"`. Each entry is a full position with its file (ADR 0027, ADR 0036). */
|
|
31
31
|
readonly positions: readonly SourcePosition[];
|
|
32
|
-
/** Every developer-declared `dynamicAccess` citation's current freshness for this variable
|
|
32
|
+
/** Every developer-declared `dynamicAccess` citation's current freshness for this variable: a wholly separate, independent fact from `status` above, never folded into it. Empty when no citation was declared, or when no manifest snapshot baseline was available to check against (the manifest pass wasn't also requested). See ADR 0037. */
|
|
33
33
|
readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
|
|
34
34
|
}
|
|
35
35
|
/** One contract's dependency-ownership facts: which variables were accessed, which files consume it, and every dynamic/ambiguous access site found. See {@link DependencyModelVariable} for the per-variable breakdown. */
|
|
36
36
|
export interface DependencyModelContract {
|
|
37
|
-
/** Root-relative, POSIX-separated
|
|
37
|
+
/** Root-relative, POSIX-separated: matches `ContractModelContract.file`. */
|
|
38
38
|
readonly file: string;
|
|
39
39
|
readonly exportName: string;
|
|
40
40
|
readonly contractName: string;
|
|
41
41
|
readonly imported: boolean;
|
|
42
42
|
readonly hasDynamicAccess: boolean;
|
|
43
43
|
readonly variables: readonly DependencyModelVariable[];
|
|
44
|
-
/** Every file coupled to this contract
|
|
44
|
+
/** Every file coupled to this contract: contract-level "who depends on this," not proof any specific variable was read. */
|
|
45
45
|
readonly consumingFiles: readonly string[];
|
|
46
46
|
/** Files whose import of this contract's name couldn't be verified because it resolved through a file containing an unresolved wildcard re-export. */
|
|
47
47
|
readonly ambiguousBarrelFiles: readonly string[];
|
|
48
|
-
/** Every computed (dynamic) property-access site observed anywhere on this contract
|
|
48
|
+
/** Every computed (dynamic) property-access site observed anywhere on this contract: see ADR 0036. */
|
|
49
49
|
readonly dynamicAccessSites: readonly SourcePosition[];
|
|
50
50
|
}
|
|
51
|
-
/** One contract, as referenced from the inverse (`consumers`) index
|
|
51
|
+
/** One contract, as referenced from the inverse (`consumers`) index: see {@link ContractRef} for why no `contractName` is carried here. */
|
|
52
52
|
export type DependencyModelContractRef = ContractRef;
|
|
53
|
-
/** One consuming file, and every contract it depends on
|
|
53
|
+
/** One consuming file, and every contract it depends on: the inverse of `DependencyModelContract.consumingFiles`. */
|
|
54
54
|
export interface DependencyModelConsumer {
|
|
55
55
|
/** Root-relative, POSIX-separated. */
|
|
56
56
|
readonly file: string;
|
|
57
57
|
readonly contracts: readonly DependencyModelContractRef[];
|
|
58
58
|
}
|
|
59
|
-
/** The versioned, JSON-serializable root of the Dependency Model
|
|
59
|
+
/** The versioned, JSON-serializable root of the Dependency Model: see this module's own doc comment for the full picture. */
|
|
60
60
|
export interface DependencyModel {
|
|
61
61
|
readonly schemaVersion: typeof DEPENDENCY_MODEL_SCHEMA_VERSION;
|
|
62
62
|
readonly contracts: readonly DependencyModelContract[];
|
|
63
|
-
/** Inverse of `contracts[].consumingFiles
|
|
63
|
+
/** Inverse of `contracts[].consumingFiles`: one entry per file that consumes at least one contract, listing which contracts it reads. */
|
|
64
64
|
readonly consumers: readonly DependencyModelConsumer[];
|
|
65
65
|
readonly warnings: readonly ParseWarning[];
|
|
66
|
-
/** Every surface actually scanned for usage
|
|
66
|
+
/** Every surface actually scanned for usage: see ADR 0036. Always has at least one entry (the application root). */
|
|
67
67
|
readonly scannedSurfaces: readonly ScannedSurface[];
|
|
68
68
|
}
|
|
69
69
|
/**
|
|
70
70
|
* Runs the dependency-ownership engine (`buildDependencyGraph()`, Private)
|
|
71
71
|
* and projects its result into the Dependency Model's versioned,
|
|
72
|
-
* JSON-serializable shape
|
|
72
|
+
* JSON-serializable shape: including the inverse file-\>contracts index
|
|
73
73
|
* neither `dependency-graph.ts` nor `usage-report.ts` exposes today.
|
|
74
74
|
*
|
|
75
75
|
* @param scannedSurfaces - See `buildDependencyGraph()`'s own parameter of
|
|
76
|
-
* the same name
|
|
76
|
+
* the same name: passed straight through to the published model.
|
|
77
77
|
* @param dynamicAccessAcknowledgments - See `buildDependencyGraph()`'s own
|
|
78
|
-
* parameter of the same name (ADR 0037)
|
|
78
|
+
* parameter of the same name (ADR 0037): passed straight through.
|
|
79
79
|
*/
|
|
80
80
|
export declare function buildDependencyModel(contracts: readonly DiscoveredContract[], scanFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, root: string, scannedSurfaces?: readonly ScannedSurface[], dynamicAccessAcknowledgments?: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): Promise<DependencyModel>;
|
|
81
81
|
//# sourceMappingURL=dependency-model.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"dependency-model.d.ts","sourceRoot":"","sources":["../../../src/build/dependency-model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAElF;;;;;;;;;;;GAWG;AAEH,
|
|
1
|
+
{"version":3,"file":"dependency-model.d.ts","sourceRoot":"","sources":["../../../src/build/dependency-model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAElF;;;;;;;;;;;GAWG;AAEH,uIAAuI;AACvI,eAAO,MAAM,+BAA+B,IAAI,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;IACrC,0GAA0G;IAC1G,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAA;IAC7C,iVAAiV;IACjV,QAAQ,CAAC,uBAAuB,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACpE;AAED,2NAA2N;AAC3N,MAAM,WAAW,uBAAuB;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD,2HAA2H;IAC3H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,sJAAsJ;IACtJ,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAA;IAChD,sGAAsG;IACtG,QAAQ,CAAC,kBAAkB,EAAE,SAAS,cAAc,EAAE,CAAA;CACvD;AAED,2IAA2I;AAC3I,MAAM,MAAM,0BAA0B,GAAG,WAAW,CAAA;AAEpD,qHAAqH;AACrH,MAAM,WAAW,uBAAuB;IACtC,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,SAAS,0BAA0B,EAAE,CAAA;CAC1D;AAED,6HAA6H;AAC7H,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,+BAA+B,CAAA;IAC9D,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD,yIAAyI;IACzI,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;IAC1C,oHAAoH;IACpH,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAA;CACpD;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC/C,OAAO,EAAE,uBAAuB,EAChC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,EAC3C,4BAA4B,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,GACpF,OAAO,CAAC,eAAe,CAAC,CAoE1B"}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { BuildFileSystem } from "./types.js";
|
|
2
2
|
/** Options for {@link discoverSchemaFiles}. */
|
|
3
3
|
export interface DiscoverOptions {
|
|
4
|
-
/** The filesystem capability
|
|
4
|
+
/** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
|
|
5
5
|
readonly fs: BuildFileSystem;
|
|
6
6
|
/** Absolute path to search under. */
|
|
7
7
|
readonly root: string;
|
|
@@ -13,29 +13,29 @@ export interface DiscoverOptions {
|
|
|
13
13
|
/**
|
|
14
14
|
* Finds every file matching `include`/`exclude` under `root`, returned as
|
|
15
15
|
* absolute paths in deterministic (alphabetically sorted) order. No count
|
|
16
|
-
* limit
|
|
16
|
+
* limit: the usage scan walks every TypeScript source file, which a large
|
|
17
17
|
* project legitimately has thousands of; {@link discoverSchemaFiles} adds the
|
|
18
18
|
* schema-specific sanity limit on top.
|
|
19
19
|
*
|
|
20
20
|
* @remarks
|
|
21
|
-
* No external glob dependency
|
|
21
|
+
* No external glob dependency. Directories are pruned *during* the walk
|
|
22
22
|
* (both a hardcoded node_modules/.git skip and the caller's `exclude`
|
|
23
|
-
* patterns),
|
|
24
|
-
*
|
|
25
|
-
*
|
|
23
|
+
* patterns), not walked in full and filtered afterward. Walking an entire
|
|
24
|
+
* node_modules tree just to discard it is not acceptable for a tool meant to
|
|
25
|
+
* run against real projects.
|
|
26
26
|
*/
|
|
27
27
|
export declare function discoverFiles(options: DiscoverOptions): Promise<string[]>;
|
|
28
28
|
/**
|
|
29
29
|
* Finds every schema file matching `include`/`exclude` under `root`, returned
|
|
30
|
-
* as absolute paths in deterministic (alphabetically sorted) order
|
|
30
|
+
* as absolute paths in deterministic (alphabetically sorted) order: the
|
|
31
31
|
* same walk as `discoverFiles`, plus a sanity limit on the count.
|
|
32
32
|
*
|
|
33
33
|
* @remarks
|
|
34
|
-
* No external glob dependency
|
|
34
|
+
* No external glob dependency. Directories are pruned *during* the walk
|
|
35
35
|
* (both a hardcoded node_modules/.git skip and the caller's `exclude`
|
|
36
|
-
* patterns),
|
|
37
|
-
*
|
|
38
|
-
*
|
|
36
|
+
* patterns), not walked in full and filtered afterward. Walking an entire
|
|
37
|
+
* node_modules tree just to discard it is not acceptable for a tool meant to
|
|
38
|
+
* run against real projects.
|
|
39
39
|
*/
|
|
40
40
|
export declare function discoverSchemaFiles(options: DiscoverOptions): Promise<string[]>;
|
|
41
41
|
//# sourceMappingURL=discover.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/build/discover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B
|
|
1
|
+
{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/build/discover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAgBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAa/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBrF"}
|