@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,78 @@
|
|
|
1
|
+
import type { CompatibilityIssue } from "./compatibility.js";
|
|
2
|
+
/**
|
|
3
|
+
* Thrown by {@link generateEnvManifest} on a blocking compatibility/exclusive-group
|
|
4
|
+
* finding, or an output path escaping `root`.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Nothing is written when this throws: generation fails atomically, same as
|
|
8
|
+
* {@link runtime.validateEnv} fails atomically at runtime.
|
|
9
|
+
*
|
|
10
|
+
* `code` is a stable, Stable-tier discriminant for programmatic handling:
|
|
11
|
+
* prefer it over `.name`/`instanceof` when a message-independent switch is needed.
|
|
12
|
+
*/
|
|
13
|
+
export declare class EnvManifestGenerationError extends Error {
|
|
14
|
+
/** Stable discriminant for programmatic handling; always `"ENV_MANIFEST_GENERATION_FAILED"`. */
|
|
15
|
+
readonly code = "ENV_MANIFEST_GENERATION_FAILED";
|
|
16
|
+
/** Every blocking finding, aggregated. */
|
|
17
|
+
readonly issues: readonly CompatibilityIssue[];
|
|
18
|
+
constructor(issues: readonly CompatibilityIssue[]);
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Thrown by {@link generateDocumentation} on a blocking undocumented-contract/
|
|
22
|
+
* variable finding (when `onUndocumented: "throw"`), or an output path
|
|
23
|
+
* (`location`/`envExample.location`) escaping `root`. Nothing is written
|
|
24
|
+
* when this throws.
|
|
25
|
+
*
|
|
26
|
+
* @remarks
|
|
27
|
+
* `code` is a stable, Stable-tier discriminant for programmatic handling:
|
|
28
|
+
* prefer it over `.name`/`instanceof` when a message-independent switch is needed.
|
|
29
|
+
*/
|
|
30
|
+
export declare class EnvDocumentationGenerationError extends Error {
|
|
31
|
+
/** Stable discriminant for programmatic handling; always `"ENV_DOCUMENTATION_GENERATION_FAILED"`. */
|
|
32
|
+
readonly code = "ENV_DOCUMENTATION_GENERATION_FAILED";
|
|
33
|
+
/** Every blocking finding, aggregated. */
|
|
34
|
+
readonly issues: readonly CompatibilityIssue[];
|
|
35
|
+
constructor(issues: readonly CompatibilityIssue[]);
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Thrown by {@link generateUsageReport} on a blocking abandoned-contract/
|
|
39
|
+
* unconsumed-owned-variable finding (when `onOwnershipIssue: "throw"`), or an
|
|
40
|
+
* output path (`report.location`) escaping `root`.
|
|
41
|
+
*
|
|
42
|
+
* @remarks
|
|
43
|
+
* Never thrown for `unresolvedConsumers` or `indeterminate` findings: both are "we don't
|
|
44
|
+
* know" states, and uncertainty is never promoted to a failure.
|
|
45
|
+
*
|
|
46
|
+
* `code` is a stable, Stable-tier discriminant for programmatic handling:
|
|
47
|
+
* prefer it over `.name`/`instanceof` when a message-independent switch is needed.
|
|
48
|
+
*/
|
|
49
|
+
export declare class EnvUsageAnalysisError extends Error {
|
|
50
|
+
/** Stable discriminant for programmatic handling; always `"ENV_USAGE_ANALYSIS_FAILED"`. */
|
|
51
|
+
readonly code = "ENV_USAGE_ANALYSIS_FAILED";
|
|
52
|
+
/** Every blocking finding, aggregated. */
|
|
53
|
+
readonly issues: readonly CompatibilityIssue[];
|
|
54
|
+
constructor(issues: readonly CompatibilityIssue[]);
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Thrown by {@link generateEnvArtifacts} when any requested pass (manifest/docs/usage)
|
|
58
|
+
* reports a blocking finding, aggregated across all requested passes into
|
|
59
|
+
* one error.
|
|
60
|
+
*
|
|
61
|
+
* @remarks
|
|
62
|
+
* Nothing from any pass is written when this throws: see
|
|
63
|
+
* `generate-env-artifacts.ts`'s compute-atomic guarantee (ADR 0011). Write-phase failures
|
|
64
|
+
* (a real I/O error after all computes already passed) are NOT wrapped in
|
|
65
|
+
* this type: they propagate as whatever `fs.writeFile` itself throws,
|
|
66
|
+
* since by that point some artifacts may already be on disk.
|
|
67
|
+
*
|
|
68
|
+
* `code` is a stable, Stable-tier discriminant for programmatic handling:
|
|
69
|
+
* prefer it over `.name`/`instanceof` when a message-independent switch is needed.
|
|
70
|
+
*/
|
|
71
|
+
export declare class EnvProjectGenerationError extends Error {
|
|
72
|
+
/** Stable discriminant for programmatic handling; always `"ENV_PROJECT_GENERATION_FAILED"`. */
|
|
73
|
+
readonly code = "ENV_PROJECT_GENERATION_FAILED";
|
|
74
|
+
/** Every blocking finding, aggregated across all requested passes. */
|
|
75
|
+
readonly issues: readonly CompatibilityIssue[];
|
|
76
|
+
constructor(issues: readonly CompatibilityIssue[]);
|
|
77
|
+
}
|
|
78
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/build/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAmB5D;;;;;;;;;;GAUG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,gGAAgG;IAChG,QAAQ,CAAC,IAAI,oCAAmC;IAChD,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;gBAElC,MAAM,EAAE,SAAS,kBAAkB,EAAE;CAelD;AAED;;;;;;;;;GASG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,qGAAqG;IACrG,QAAQ,CAAC,IAAI,yCAAwC;IACrD,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;gBAElC,MAAM,EAAE,SAAS,kBAAkB,EAAE;CAelD;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,+BAA8B;IAC3C,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;gBAElC,MAAM,EAAE,SAAS,kBAAkB,EAAE;CAWlD;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,mCAAkC;IAC/C,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;gBAElC,MAAM,EAAE,SAAS,kBAAkB,EAAE;CAQlD"}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import type { EvidenceModel } from "./evidence-model.js";
|
|
2
|
+
import type { GenerateEvidenceModelOptions } from "./generate-evidence.js";
|
|
3
|
+
import type { BuildFileSystem } from "./types.js";
|
|
4
|
+
/**
|
|
5
|
+
* A fast, honest read path for the persisted evidence artifact. It serves a
|
|
6
|
+
* report/projection script, a CI step, or any consumer that wants the
|
|
7
|
+
* current `EvidenceModel` without silently-stale data. Such a consumer
|
|
8
|
+
* avoids a full `generateEvidenceModel()` recompute on every invocation
|
|
9
|
+
* (schema parsing, cross-file linking, the dependency-graph AST scan, all six
|
|
10
|
+
* model builds). The mechanism: a cheap content fingerprint,
|
|
11
|
+
* computed from raw file bytes with zero AST work, lets a caller cheaply
|
|
12
|
+
* prove "nothing relevant to evidence generation has changed since this file
|
|
13
|
+
* was last written" before trusting it.
|
|
14
|
+
*/
|
|
15
|
+
/** Options for {@link computeSourceFingerprint}. */
|
|
16
|
+
export interface ComputeSourceFingerprintOptions {
|
|
17
|
+
/** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
|
|
18
|
+
readonly fs: BuildFileSystem;
|
|
19
|
+
readonly root: string;
|
|
20
|
+
readonly include: readonly string[];
|
|
21
|
+
readonly exclude: readonly string[];
|
|
22
|
+
readonly packages?: readonly string[] | undefined;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* SHA-256 over the raw bytes of every schema file and every usage-scan-
|
|
26
|
+
* surface file (the same file sets `assembleProject()`/`computeScanSurface()`
|
|
27
|
+
* touch), plus env-cap's own installed version: zero AST parsing or
|
|
28
|
+
* linking. Still requires the discovery/glob walk itself (fingerprinting has
|
|
29
|
+
* to know which files matter), but skips everything after it. Deterministic:
|
|
30
|
+
* file paths are deduplicated and sorted before hashing, so the result never
|
|
31
|
+
* depends on filesystem enumeration order.
|
|
32
|
+
*
|
|
33
|
+
* @remarks
|
|
34
|
+
* Not a timestamp, and never compared as one. A fresh mtime doesn't prove
|
|
35
|
+
* content is unchanged (a checkout, a rebase, or a touch can all bump it
|
|
36
|
+
* with no real edit). Content is the only thing that invalidates a cached
|
|
37
|
+
* evidence artifact.
|
|
38
|
+
*/
|
|
39
|
+
export declare function computeSourceFingerprint(options: ComputeSourceFingerprintOptions): Promise<string>;
|
|
40
|
+
/** Writes `fingerprint`'s paired sidecar for `evidencePath`: call immediately after writing the evidence artifact itself, so the two files always describe the same moment in the source tree's history. */
|
|
41
|
+
export declare function writeEvidenceFingerprint(evidencePath: string, fingerprint: string, fs: BuildFileSystem): Promise<void>;
|
|
42
|
+
/** Options for {@link getEvidenceModel}: every `generateEvidenceModel()` option, plus where the cached artifact lives. */
|
|
43
|
+
export interface GetEvidenceModelOptions extends GenerateEvidenceModelOptions {
|
|
44
|
+
/** Where the cached evidence artifact (and its `.fingerprint` sidecar) live, e.g. `docs/env.evidence.json`, relative to `root`. Required: there is no honest default env-cap could guess at for where a project keeps this. */
|
|
45
|
+
readonly location: string;
|
|
46
|
+
}
|
|
47
|
+
/** The result of {@link getEvidenceModel}. */
|
|
48
|
+
export interface GetEvidenceModelResult {
|
|
49
|
+
readonly evidence: EvidenceModel;
|
|
50
|
+
/** `"hit"`: the committed evidence artifact's fingerprint matched current source; read from disk, no recompute. `"miss"`: a real `generateEvidenceModel()` call ran. */
|
|
51
|
+
readonly source: "hit" | "miss";
|
|
52
|
+
/** Set only when `source === "miss"`: why the cache wasn't trusted, for a caller that wants to log it. */
|
|
53
|
+
readonly missReason: string | undefined;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Trusts the committed evidence artifact at `options.location` only when its
|
|
57
|
+
* paired `.fingerprint` sidecar matches a freshly (cheaply) computed
|
|
58
|
+
* {@link computeSourceFingerprint}: never on file presence alone, never on
|
|
59
|
+
* a timestamp. On any mismatch (stale fingerprint, missing/corrupt evidence
|
|
60
|
+
* file, no fingerprint sidecar at all), falls back to a real
|
|
61
|
+
* `generateEvidenceModel()` call: never hard-fails, never silently serves
|
|
62
|
+
* data that might be stale.
|
|
63
|
+
*
|
|
64
|
+
* @remarks
|
|
65
|
+
* Never writes anything. A cache miss here does not self-heal the cache.
|
|
66
|
+
* Only an explicit write (`generateEnvArtifacts()`'s `evidence` option)
|
|
67
|
+
* refreshes the committed artifact and its fingerprint together. That keeps
|
|
68
|
+
* "when was this last regenerated" under explicit control, never an implicit
|
|
69
|
+
* side effect of a read. Two independent callers hitting the same
|
|
70
|
+
* stale cache both recompute independently; neither one's recompute updates
|
|
71
|
+
* the file the other reads.
|
|
72
|
+
*/
|
|
73
|
+
export declare function getEvidenceModel(options: GetEvidenceModelOptions): Promise<GetEvidenceModelResult>;
|
|
74
|
+
//# sourceMappingURL=evidence-cache.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"evidence-cache.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-cache.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAKxD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAA;AAO1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;GAUG;AAEH,oDAAoD;AACpD,MAAM,WAAW,+BAA+B;IAC9C,+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;CAClD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,MAAM,CAAC,CA4CjB;AAMD,4MAA4M;AAC5M,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,0HAA0H;AAC1H,MAAM,WAAW,uBAAwB,SAAQ,4BAA4B;IAC3E,+NAA+N;IAC/N,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,wKAAwK;IACxK,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAA;IAC/B,0GAA0G;IAC1G,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAuDjC"}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import type { ChangeModel } from "./change-model.js";
|
|
2
|
+
import type { ContractModel } from "./contract-model.js";
|
|
3
|
+
import type { DependencyModel } from "./dependency-model.js";
|
|
4
|
+
import type { FindingModel } from "./finding-model.js";
|
|
5
|
+
import type { LifecycleModel } from "./lifecycle-model.js";
|
|
6
|
+
import type { OwnershipModel } from "./ownership-model.js";
|
|
7
|
+
/**
|
|
8
|
+
* Bump only when a reader could misinterpret the new shape of `EvidenceModel`
|
|
9
|
+
* itself (not any one sub-model's own `<MODEL>_SCHEMA_VERSION`, which is
|
|
10
|
+
* versioned independently): same rule every other canonical model follows.
|
|
11
|
+
*/
|
|
12
|
+
export declare const EVIDENCE_MODEL_SCHEMA_VERSION = 1;
|
|
13
|
+
/**
|
|
14
|
+
* Who/when/what produced a given `EvidenceModel` instance. Caller-supplied,
|
|
15
|
+
* never ambient-detected: `generateEvidenceModel()` never shells out to
|
|
16
|
+
* `git` itself, mirroring ADR 0012's live-expiration-callback precedent.
|
|
17
|
+
*/
|
|
18
|
+
export interface EvidenceProvenance {
|
|
19
|
+
readonly generatedAt: string;
|
|
20
|
+
readonly toolVersion: string;
|
|
21
|
+
readonly commit: string | undefined;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* The seventh canonical fact model (ADR 0024): the assembled union of the
|
|
25
|
+
* other six, plus provenance, the immutable input every
|
|
26
|
+
* `defineEvidenceProjection()` projector runs over (`@maverickcer/env-cap/evidence`,
|
|
27
|
+
* ADR 0031).
|
|
28
|
+
*
|
|
29
|
+
* @remarks
|
|
30
|
+
* This type is the one intentional exception to `src/build/`'s zero-
|
|
31
|
+
* cross-folder-import rule: `src/evidence/` imports it with `import type`
|
|
32
|
+
* only (fully erased at compile time under `verbatimModuleSyntax`), the same
|
|
33
|
+
* shape as `helpers`' single sanctioned edge onto `runtime`; see
|
|
34
|
+
* `specs/architecture.md`. `src/evidence/` never imports a *value* from
|
|
35
|
+
* here, only this shape, so it stays isomorphic and Node-free. An actual
|
|
36
|
+
* `EvidenceModel` instance is produced by {@link generateEvidenceModel}
|
|
37
|
+
* (`@maverickcer/env-cap/build`, Node-only), which runs discovery once,
|
|
38
|
+
* builds all six sub-models, and `deepFreeze()`s the result.
|
|
39
|
+
*/
|
|
40
|
+
export interface EvidenceModel {
|
|
41
|
+
readonly schemaVersion: typeof EVIDENCE_MODEL_SCHEMA_VERSION;
|
|
42
|
+
readonly provenance: EvidenceProvenance;
|
|
43
|
+
readonly contract: ContractModel;
|
|
44
|
+
readonly dependency: DependencyModel;
|
|
45
|
+
readonly ownership: OwnershipModel;
|
|
46
|
+
readonly lifecycle: LifecycleModel;
|
|
47
|
+
readonly finding: FindingModel;
|
|
48
|
+
readonly change: ChangeModel;
|
|
49
|
+
}
|
|
50
|
+
//# sourceMappingURL=evidence-model.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"evidence-model.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAA;AAE9C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,6BAA6B,CAAA;IAC5D,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAA;IACvC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;IACpC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B"}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import type { SourcePosition } from "./source-position.js";
|
|
2
|
+
/**
|
|
3
|
+
* A structured pointer back to where a `Finding` (or, later, any other
|
|
4
|
+
* model's derived fact) came from: never a formatted string. See ADR 0024
|
|
5
|
+
* and ADR 0026.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* Deliberately only as many `model` variants as something in this codebase
|
|
9
|
+
* actually needs to reference today (`"contract"`, `"ownership"`,
|
|
10
|
+
* `"change"`). This is an additive, growable union, not a speculative
|
|
11
|
+
* six-model union built ahead of a real consumer. Another model (e.g. the
|
|
12
|
+
* Dependency or Lifecycle Model) adds its own variant only once a finding
|
|
13
|
+
* or projector needs to point at it.
|
|
14
|
+
*/
|
|
15
|
+
export type EvidenceReference = ContractEvidenceReference | OwnershipEvidenceReference | ChangeEvidenceReference;
|
|
16
|
+
/**
|
|
17
|
+
* The one shape every model in this package uses to point at a declared
|
|
18
|
+
* contract: the file it's declared in, and the binding it's exported as.
|
|
19
|
+
* Nothing else: see ADR 0039.
|
|
20
|
+
*
|
|
21
|
+
* @remarks
|
|
22
|
+
* Deliberately *not* carrying `contractName`. A display name is a rendering
|
|
23
|
+
* concern. A renderer that needs prose resolves it on demand from
|
|
24
|
+
* `ContractModel`, the one model that owns it. A copy on every reference
|
|
25
|
+
* would go stale independently, since the name can change under a
|
|
26
|
+
* `documentEnv()` edit. Deliberately not carrying a
|
|
27
|
+
* pre-formatted `identity` string either: `${file}#${exportName}` is
|
|
28
|
+
* trivially derivable, and a stored copy is one more thing that can disagree
|
|
29
|
+
* with the two fields it was built from. Code that genuinely needs a map key
|
|
30
|
+
* builds that string locally, at the point of use.
|
|
31
|
+
*/
|
|
32
|
+
export interface ContractRef {
|
|
33
|
+
/** Root-relative, POSIX-separated path of the file declaring the contract: see `displayPath()`. */
|
|
34
|
+
readonly file: string;
|
|
35
|
+
/** The binding name the `createEnv()` result is exported as. */
|
|
36
|
+
readonly exportName: string;
|
|
37
|
+
}
|
|
38
|
+
/** Points at a declared contract and, optionally, one of its variables: the shape every `CompatibilityIssue`/documentation finding can be resolved to. Unlike {@link ContractRef}, both identity fields are optional here: a finding can legitimately know only the file (an unresolvable `documentEnv()` link) or neither. */
|
|
39
|
+
export interface ContractEvidenceReference {
|
|
40
|
+
readonly model: "contract";
|
|
41
|
+
/** Root-relative, POSIX-separated path of the file declaring the contract, when known: see `displayPath()`. */
|
|
42
|
+
readonly file: string | undefined;
|
|
43
|
+
/** The contract's exported binding name, when known. */
|
|
44
|
+
readonly exportName: string | undefined;
|
|
45
|
+
/** The environment variable name, when the finding is variable-level rather than contract-level. */
|
|
46
|
+
readonly variable: string | undefined;
|
|
47
|
+
/** Exact file:line:column this finding is about; the contract's `createEnv()` declaration, its `documentEnv()` declaration, or the specific variable's own declaration, whichever is most relevant to the finding. `undefined` only when no single position is more relevant than another (e.g. an `indeterminate-ownership` finding, which can have multiple candidate sites: see `IndeterminateOwnershipFinding.dynamicAccessSites` for the full list instead). See ADR 0036. */
|
|
48
|
+
readonly position: SourcePosition | undefined;
|
|
49
|
+
}
|
|
50
|
+
/** Points at a contract by name for an ownership/usage finding: `usage-report.ts`'s finding types don't consistently carry `file`/`exportName` together, only `contractName`. */
|
|
51
|
+
export interface OwnershipEvidenceReference {
|
|
52
|
+
readonly model: "ownership";
|
|
53
|
+
readonly contractName: string;
|
|
54
|
+
/** Root-relative path of the file declaring the contract, when the source finding carries one. */
|
|
55
|
+
readonly file: string | undefined;
|
|
56
|
+
/** The environment variable name, when the finding is variable-level rather than contract-level. */
|
|
57
|
+
readonly variable: string | undefined;
|
|
58
|
+
/** See {@link ContractEvidenceReference.position}. */
|
|
59
|
+
readonly position: SourcePosition | undefined;
|
|
60
|
+
}
|
|
61
|
+
/** Points at a generated artifact's path: what `checkEnvArtifacts()`'s drift findings are about, not a declared contract or variable at all. */
|
|
62
|
+
export interface ChangeEvidenceReference {
|
|
63
|
+
readonly model: "change";
|
|
64
|
+
/** Absolute path of the generated artifact. */
|
|
65
|
+
readonly path: string;
|
|
66
|
+
}
|
|
67
|
+
//# sourceMappingURL=evidence-reference.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"evidence-reference.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-reference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GAC3B,yBAAyB,GAAG,0BAA0B,GAAG,uBAAuB,CAAA;AAElF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,WAAW;IAC1B,mGAAmG;IACnG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,+TAA+T;AAC/T,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,+GAA+G;IAC/G,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,mdAAmd;IACnd,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CAC9C;AAED,iLAAiL;AACjL,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CAC9C;AAED,gJAAgJ;AAChJ,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB"}
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
import type { DynamicAccessCitationProblem } from "./citation-verification.js";
|
|
2
|
+
import type { ContractRef } from "./evidence-reference.js";
|
|
3
|
+
import type { ContractModelContract } from "./contract-model.js";
|
|
4
|
+
import type { EvidenceModel } from "./evidence-model.js";
|
|
5
|
+
import type { DiscoveredContract } from "./link.js";
|
|
6
|
+
import type { ParseWarning } from "./parse.js";
|
|
7
|
+
import type { DynamicAccessAssertion } from "./source-position.js";
|
|
8
|
+
import type { BuildFileSystem } from "./types.js";
|
|
9
|
+
/**
|
|
10
|
+
* The persisted evidence artifact and everything that reads/diffs it.
|
|
11
|
+
*
|
|
12
|
+
* Not a sibling of `env.manifest.ts`. `env.manifest.ts` is a *runtime build
|
|
13
|
+
* artifact*: real TypeScript, imported and executed by the running
|
|
14
|
+
* application. This module's own artifact is a *CI/reporting artifact*: the
|
|
15
|
+
* literal `EvidenceModel` a caller gets back from `generateEvidenceModel()`,
|
|
16
|
+
* serialized to disk. Only `--check`, CI tooling and a project's own
|
|
17
|
+
* reporting/projection code read it. Nothing under `src/runtime/` imports it,
|
|
18
|
+
* and it is never a build input to the application itself. Its location is never derived from a
|
|
19
|
+
* manifest's own output path; there is no `<manifest>.snapshot.json` sidecar. A caller supplies
|
|
20
|
+
* it directly, whether or not a `.ts` manifest is being generated at all.
|
|
21
|
+
*
|
|
22
|
+
* Two jobs, one file. (a) It is the baseline `diffContracts()` compares the
|
|
23
|
+
* current run's `ContractModel` against to produce `ManifestChangeReport`.
|
|
24
|
+
* (b) It is the committed content-hash baseline `buildCitationSnapshots()`
|
|
25
|
+
* (`citation-verification.ts`) uses to tell a "fresh" developer
|
|
26
|
+
* dynamic-access citation from a "stale" one (ADR 0037).
|
|
27
|
+
* A project chooses whether to commit this file or regenerate it every CI
|
|
28
|
+
* run. A missing file is always the normal first-run state, never an error.
|
|
29
|
+
*/
|
|
30
|
+
/** One field's before/after value in a {@link ManifestContractUpdate} or {@link ManifestVariableUpdate}. */
|
|
31
|
+
export interface ManifestFieldChange {
|
|
32
|
+
/** The changed field's name. */
|
|
33
|
+
readonly field: string;
|
|
34
|
+
/** The value from the previous snapshot, or `undefined` if the field was unset. */
|
|
35
|
+
readonly previous: string | undefined;
|
|
36
|
+
/** The value in the current run, or `undefined` if the field is now unset. */
|
|
37
|
+
readonly current: string | undefined;
|
|
38
|
+
}
|
|
39
|
+
/** Identifies one contract for {@link ManifestChangeReport} purposes: see {@link ContractRef} for why neither a `contractName` nor a pre-formatted `identity` is carried here. */
|
|
40
|
+
export type ManifestContractRef = ContractRef;
|
|
41
|
+
/** Identifies one variable for {@link ManifestChangeReport} purposes: its owning contract's identity plus its own key. See {@link ContractRef}. */
|
|
42
|
+
export interface ManifestVariableRef extends ContractRef {
|
|
43
|
+
/** The environment variable name. */
|
|
44
|
+
readonly key: string;
|
|
45
|
+
}
|
|
46
|
+
/** A contract present in both snapshots, with at least one changed field. */
|
|
47
|
+
export interface ManifestContractUpdate extends ManifestContractRef {
|
|
48
|
+
/** Every field that changed between the previous and current snapshot. */
|
|
49
|
+
readonly changes: readonly ManifestFieldChange[];
|
|
50
|
+
}
|
|
51
|
+
/** A variable present in both snapshots, with at least one changed field. */
|
|
52
|
+
export interface ManifestVariableUpdate extends ManifestVariableRef {
|
|
53
|
+
/** Every field that changed between the previous and current snapshot. */
|
|
54
|
+
readonly changes: readonly ManifestFieldChange[];
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* The result of diffing two `ContractModel.contracts` arrays: see
|
|
58
|
+
* `diffContracts()`. Comprehensive by construction. Every own field of
|
|
59
|
+
* `ContractModelContract`/`ContractModelVariable` participates: schema facts
|
|
60
|
+
* (`hasDefault`/`processorSource`/`validatorSource`/...) and documented
|
|
61
|
+
* metadata. Every discovered contract is covered, not only active ones.
|
|
62
|
+
* `diffContracts()` compares every field generically, so a new Contract Model
|
|
63
|
+
* field is diffed without an edit here.
|
|
64
|
+
*/
|
|
65
|
+
export interface ManifestChangeReport {
|
|
66
|
+
/** Contracts present now but not in the previous snapshot. */
|
|
67
|
+
readonly addedContracts: readonly ManifestContractRef[];
|
|
68
|
+
/** Contracts present in the previous snapshot but not now. */
|
|
69
|
+
readonly removedContracts: readonly ManifestContractRef[];
|
|
70
|
+
/** Variables present now but not in the previous snapshot. */
|
|
71
|
+
readonly addedVariables: readonly ManifestVariableRef[];
|
|
72
|
+
/** Variables present in the previous snapshot but not now. */
|
|
73
|
+
readonly removedVariables: readonly ManifestVariableRef[];
|
|
74
|
+
/** Contracts present in both snapshots with at least one changed field. */
|
|
75
|
+
readonly updatedContracts: readonly ManifestContractUpdate[];
|
|
76
|
+
/** Variables present in both snapshots with at least one changed field. */
|
|
77
|
+
readonly updatedVariables: readonly ManifestVariableUpdate[];
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Pure. `previous === undefined` (no snapshot last time, for any reason:
|
|
81
|
+
* see `EvidenceSnapshotReadResult`) reports everything in `current` as
|
|
82
|
+
* added, nothing as removed/updated.
|
|
83
|
+
*/
|
|
84
|
+
export declare function diffContracts(previous: readonly ContractModelContract[] | undefined, current: readonly ContractModelContract[]): ManifestChangeReport;
|
|
85
|
+
/** Distinguishes *why* there's no usable previous snapshot, rather than collapsing every case into a bare `undefined`. A missing file is the normal, silent, expected first-run/never-configured case. An unparseable file or a `schemaVersion` this build doesn't recognize are both real, diagnosable problems. */
|
|
86
|
+
export type EvidenceSnapshotReadResult = {
|
|
87
|
+
readonly status: "missing";
|
|
88
|
+
} | {
|
|
89
|
+
readonly status: "invalid-json";
|
|
90
|
+
readonly detail: string;
|
|
91
|
+
} | {
|
|
92
|
+
readonly status: "unsupported-version";
|
|
93
|
+
readonly foundVersion: unknown;
|
|
94
|
+
} | {
|
|
95
|
+
readonly status: "ok";
|
|
96
|
+
readonly snapshot: EvidenceModel;
|
|
97
|
+
};
|
|
98
|
+
export declare function readEvidenceSnapshot(snapshotPath: string, fs: BuildFileSystem): Promise<EvidenceSnapshotReadResult>;
|
|
99
|
+
export declare function writeEvidenceSnapshot(snapshotPath: string, snapshot: EvidenceModel, fs: BuildFileSystem): Promise<void>;
|
|
100
|
+
/**
|
|
101
|
+
* `snapshot`, with two fields normalized to a constant: the comparison
|
|
102
|
+
* basis `--check` uses:
|
|
103
|
+
*
|
|
104
|
+
* - `provenance.generatedAt` is a live timestamp stamped fresh on every real
|
|
105
|
+
* `generate` run. The two renders' timestamps can never match. So a
|
|
106
|
+
* byte-for-byte comparison with a copy rendered for `--check` would report
|
|
107
|
+
* drift every time, even with zero real changes. `toolVersion`/`commit`
|
|
108
|
+
* stay compared as-is. Both are stable provenance across a `--check` run
|
|
109
|
+
* and the `generate` run it verifies; neither varies on its own.
|
|
110
|
+
* - `change` describes "what's different from whatever snapshot was on disk
|
|
111
|
+
* the moment this run computed it". A second computation cannot reproduce
|
|
112
|
+
* it. By the time `--check` re-derives it, the file just written *is* the
|
|
113
|
+
* new baseline, so the diff comes back empty against itself. This isn't
|
|
114
|
+
* drift; it's `change`'s own definition. So `--check` doesn't re-verify it,
|
|
115
|
+
* the same treatment as `generatedAt`.
|
|
116
|
+
* - every `now`-relative expiry countdown is the same class as `generatedAt`.
|
|
117
|
+
* That covers `lifecycle.expiring[].daysRemaining` and the day-count inside
|
|
118
|
+
* an `EXPIRED`/`EXPIRING_SOON` finding message. A static `expiresAt`
|
|
119
|
+
* produces a different number every day. So a committed artifact would go
|
|
120
|
+
* "stale" with zero real edits. These are normalized to a constant, so
|
|
121
|
+
* `--check` (and the golden tests) verify the substance, not the calendar.
|
|
122
|
+
* The raw `expiresAt` strings stay compared.
|
|
123
|
+
*/
|
|
124
|
+
export declare function normalizeEvidenceSnapshotForComparison(snapshot: EvidenceModel): EvidenceModel;
|
|
125
|
+
/** Everything reading a previous evidence snapshot and diffing the current run against it produces, in one call. Never writes anything itself: writing the fresh snapshot stays a separate, explicit step on the real write path. */
|
|
126
|
+
export interface EvidenceChangesComputation {
|
|
127
|
+
readonly report: ManifestChangeReport;
|
|
128
|
+
/** Set only when the previous snapshot existed but was unusable (corrupt JSON or an unrecognized `schemaVersion`). Never set for the ordinary "no snapshot yet" first-run case. */
|
|
129
|
+
readonly readWarning: ParseWarning | undefined;
|
|
130
|
+
readonly dynamicAccessAcknowledgments: ReadonlyMap<string, readonly DynamicAccessAssertion[]>;
|
|
131
|
+
readonly dynamicAccessCitationProblems: readonly DynamicAccessCitationProblem[];
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* The one I/O-performing helper every caller wanting change/citation-freshness
|
|
135
|
+
* data shares. It reads the previous evidence snapshot (if `snapshotPath` is
|
|
136
|
+
* given and a file exists there). It diffs the current run's `ContractModel`
|
|
137
|
+
* against it, and re-checks every current `dynamicAccess` citation's
|
|
138
|
+
* freshness. `snapshotPath` is always caller-supplied, never derived from a
|
|
139
|
+
* manifest's own output path.
|
|
140
|
+
*/
|
|
141
|
+
export declare function computeEvidenceChanges(root: string, snapshotPath: string, activeContracts: readonly DiscoveredContract[], currentContracts: readonly ContractModelContract[], readFile: (filePath: string) => Promise<string>, fs: BuildFileSystem): Promise<EvidenceChangesComputation>;
|
|
142
|
+
//# sourceMappingURL=evidence-snapshot.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"evidence-snapshot.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-snapshot.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { CompatibilityIssue } from "./compatibility.js";
|
|
2
|
+
import type { DiscoveredContract } from "./link.js";
|
|
3
|
+
/**
|
|
4
|
+
* Detects two *active* contracts declaring the same `exclusiveGroup`:
|
|
5
|
+
* e.g. two interchangeable database backends both left enabled at once.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* Unlike `detectCompatibilityIssues`, this is never a heuristic warning: an
|
|
9
|
+
* author explicitly declared these contracts mutually exclusive, so any
|
|
10
|
+
* violation is always a hard error, regardless of `onIncompatibility`. See
|
|
11
|
+
* ADR 0009 for why this doesn't follow 0005's warn-by-default policy.
|
|
12
|
+
*
|
|
13
|
+
* Inactive contracts are ignored entirely here (filtered internally, not by
|
|
14
|
+
* the caller), so this stays correct when called directly via the `/build`
|
|
15
|
+
* export. An inactive contract can share a group with an active one with no
|
|
16
|
+
* conflict, since it was never wired into anything.
|
|
17
|
+
*/
|
|
18
|
+
export declare function detectExclusiveGroupIssues(contracts: readonly DiscoveredContract[]): CompatibilityIssue[];
|
|
19
|
+
//# sourceMappingURL=exclusive-group.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"exclusive-group.d.ts","sourceRoot":"","sources":["../../../src/build/exclusive-group.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,kBAAkB,EAAE,CA8BtB"}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import type { ArtifactCheckFinding } from "./check-artifacts.js";
|
|
2
|
+
import type { CompatibilityIssue, CompatibilityIssueCode } from "./compatibility.js";
|
|
3
|
+
import type { EvidenceReference } from "./evidence-reference.js";
|
|
4
|
+
import type { DocumentationFindings } from "./generate-documentation.js";
|
|
5
|
+
import type { DynamicAccessCitationProblem } from "./citation-verification.js";
|
|
6
|
+
import type { AbandonedContractFinding, IndeterminateOwnershipFinding, UnconsumedOwnedVariableFinding, UnresolvedConsumerFinding } from "./usage-report.js";
|
|
7
|
+
/**
|
|
8
|
+
* The fourth of env-cap's seven canonical fact models (ADR 0024): every
|
|
9
|
+
* rule violation and derived risk signal, unified behind one shape, with a
|
|
10
|
+
* stable `code` and a structured {@link EvidenceReference} instead of four
|
|
11
|
+
* independently-shaped finding families. See ADR 0026.
|
|
12
|
+
*/
|
|
13
|
+
/** Every stable `code` a {@link Finding} can carry. A superset of {@link CompatibilityIssueCode} plus one code per non-compatibility source family this model adapts. */
|
|
14
|
+
export type FindingCode = CompatibilityIssueCode | "EXCLUSIVE_GROUP_VIOLATION" | "ARTIFACT_STALE" | "ARTIFACT_MISSING" | "UNDOCUMENTED_CONTRACT" | "UNDOCUMENTED_VARIABLE" | "STALE_DOC_ENTRY" | "EXPIRED" | "EXPIRING_SOON" | "UNRESOLVED_DOCUMENTENV_LINK" | "ABANDONED_CONTRACT" | "UNRESOLVED_CONSUMER" | "UNCONSUMED_OWNED_VARIABLE" | "INDETERMINATE_OWNERSHIP" | "MISSING_DYNAMIC_ACCESS_CITATION" | "STALE_DYNAMIC_ACCESS_CITATION" | "NONSTANDARD_SENSITIVITY_LEVEL";
|
|
15
|
+
/** Which source check produced a {@link Finding}: coarser than `code`, for a consumer that only wants to filter by kind (e.g. "show me every documentation gap") without enumerating every individual code. */
|
|
16
|
+
export type FindingFamily = "compatibility" | "drift" | "documentation" | "ownership";
|
|
17
|
+
/** One rule violation or derived signal, in the Finding Model's canonical shape. */
|
|
18
|
+
export interface Finding {
|
|
19
|
+
/**
|
|
20
|
+
* `"error"` for a provable, always-blocking violation (e.g. an
|
|
21
|
+
* exclusive-group conflict); `"warning"` for everything gated by
|
|
22
|
+
* `onIncompatibility`/`onUndocumented`/`onOwnershipIssue`'s default "warn"
|
|
23
|
+
* behavior; `"info"` for an observation that is never actionable enough to
|
|
24
|
+
* block anything, even under `--strict`: see `INFO_ONLY_CODES` in
|
|
25
|
+
* `generate-env-artifacts.ts`.
|
|
26
|
+
*/
|
|
27
|
+
readonly severity: "error" | "warning" | "info";
|
|
28
|
+
/** Stable, machine-readable identifier: always set, unlike {@link CompatibilityIssue.code} which stays optional on that narrower, pre-existing type. */
|
|
29
|
+
readonly code: FindingCode;
|
|
30
|
+
/** Which source check produced this finding. */
|
|
31
|
+
readonly family: FindingFamily;
|
|
32
|
+
/** Human-readable explanation, reusing the source finding's own prose where one exists. */
|
|
33
|
+
readonly message: string;
|
|
34
|
+
/** Structured pointer back to what this finding is about. */
|
|
35
|
+
readonly location: EvidenceReference;
|
|
36
|
+
}
|
|
37
|
+
/** Bump only when a reader could misinterpret the new shape: same discipline every other canonical model's `schemaVersion` follows. */
|
|
38
|
+
export declare const FINDING_MODEL_SCHEMA_VERSION = 3;
|
|
39
|
+
/** The versioned, JSON-serializable root of the Finding Model: every rule violation and derived risk signal from this run, unified behind {@link Finding}'s one shape. See this module's own doc comment for the full picture. */
|
|
40
|
+
export interface FindingModel {
|
|
41
|
+
readonly schemaVersion: typeof FINDING_MODEL_SCHEMA_VERSION;
|
|
42
|
+
readonly findings: readonly Finding[];
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Every source a {@link buildFindingModel} call can adapt, all optional:
|
|
46
|
+
* a caller passes whichever of `generateEnvArtifacts()`'s `manifest`/`docs`/
|
|
47
|
+
* `usage` results it actually requested, exactly like that result's own
|
|
48
|
+
* top-level fields are each independently optional.
|
|
49
|
+
*/
|
|
50
|
+
export interface BuildFindingModelInput {
|
|
51
|
+
/** Every `EvidenceReference.file` below is rendered relative to this, matching every other rendered path in this package's output: see `displayPath()`. */
|
|
52
|
+
readonly root: string;
|
|
53
|
+
/** From `detectCompatibilityIssues()`. */
|
|
54
|
+
readonly compatibilityIssues?: readonly CompatibilityIssue[];
|
|
55
|
+
/** From `detectExclusiveGroupIssues()`: kept separate from `compatibilityIssues` since it never sets its own `code` yet (ADR 0009), so this adapter synthesizes `"EXCLUSIVE_GROUP_VIOLATION"` for every entry. */
|
|
56
|
+
readonly exclusiveGroupIssues?: readonly CompatibilityIssue[];
|
|
57
|
+
/** From `checkEnvArtifacts()`'s result. Only `"stale"`/`"missing"` findings become a `Finding`: `"ok"` means nothing to report. */
|
|
58
|
+
readonly artifactCheckFindings?: readonly ArtifactCheckFinding[];
|
|
59
|
+
/** From `generateDocumentation()`'s result. */
|
|
60
|
+
readonly documentation?: DocumentationFindings;
|
|
61
|
+
/** From `generateUsageReport()`'s result. */
|
|
62
|
+
readonly abandonedContracts?: readonly AbandonedContractFinding[];
|
|
63
|
+
/** From `generateUsageReport()`'s result. */
|
|
64
|
+
readonly unresolvedConsumers?: readonly UnresolvedConsumerFinding[];
|
|
65
|
+
/** From `generateUsageReport()`'s result. */
|
|
66
|
+
readonly unconsumedOwnedVariables?: readonly UnconsumedOwnedVariableFinding[];
|
|
67
|
+
/** From `generateUsageReport()`'s result. */
|
|
68
|
+
readonly indeterminateOwnership?: readonly IndeterminateOwnershipFinding[];
|
|
69
|
+
/** From `computeManifestChanges()`'s result: every `dynamicAccess` citation that's gone `"stale"` or `"missing"` since it was last acknowledged. See ADR 0037. */
|
|
70
|
+
readonly dynamicAccessCitationProblems?: readonly DynamicAccessCitationProblem[] | undefined;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Adapts every existing finding family into the Finding Model's unified
|
|
74
|
+
* shape: an adapter over data that already exists, not a new source of
|
|
75
|
+
* truth. Order of the returned array mirrors the order sources are given
|
|
76
|
+
* above; a consumer wanting a specific order (by severity, by file, ...)
|
|
77
|
+
* sorts it themselves.
|
|
78
|
+
*/
|
|
79
|
+
export declare function buildFindingModel(input: BuildFindingModelInput): FindingModel;
|
|
80
|
+
//# sourceMappingURL=finding-model.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"finding-model.d.ts","sourceRoot":"","sources":["../../../src/build/finding-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAEpF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAA;AACxE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,4BAA4B,CAAA;AAC9E,OAAO,KAAK,EACV,wBAAwB,EACxB,6BAA6B,EAC7B,8BAA8B,EAC9B,yBAAyB,EAC1B,MAAM,mBAAmB,CAAA;AAE1B;;;;;GAKG;AAEH,yKAAyK;AACzK,MAAM,MAAM,WAAW,GACnB,sBAAsB,GACtB,2BAA2B,GAC3B,gBAAgB,GAChB,kBAAkB,GAClB,uBAAuB,GACvB,uBAAuB,GACvB,iBAAiB,GACjB,SAAS,GACT,eAAe,GACf,6BAA6B,GAC7B,oBAAoB,GACpB,qBAAqB,GACrB,2BAA2B,GAC3B,yBAAyB,GACzB,iCAAiC,GACjC,+BAA+B,GAC/B,+BAA+B,CAAA;AAEnC,+MAA+M;AAC/M,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,OAAO,GAAG,eAAe,GAAG,WAAW,CAAA;AAErF,oFAAoF;AACpF,MAAM,WAAW,OAAO;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;IAC/C,wJAAwJ;IACxJ,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;CACrC;AAED,uIAAuI;AACvI,eAAO,MAAM,4BAA4B,IAAI,CAAA;AAE7C,kOAAkO;AAClO,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,4BAA4B,CAAA;IAC3D,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,2JAA2J;IAC3J,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC5D,kNAAkN;IAClN,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC7D,mIAAmI;IACnI,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;IAChE,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,qBAAqB,CAAA;IAC9C,6CAA6C;IAC7C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAA;IACjE,6CAA6C;IAC7C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACnE,6CAA6C;IAC7C,QAAQ,CAAC,wBAAwB,CAAC,EAAE,SAAS,8BAA8B,EAAE,CAAA;IAC7E,6CAA6C;IAC7C,QAAQ,CAAC,sBAAsB,CAAC,EAAE,SAAS,6BAA6B,EAAE,CAAA;IAC1E,kKAAkK;IAClK,QAAQ,CAAC,6BAA6B,CAAC,EAAE,SAAS,4BAA4B,EAAE,GAAG,SAAS,CAAA;CAC7F;AAoCD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,YAAY,CAwN7E"}
|