@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,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Recursively freezes `value` and everything reachable from it (array
|
|
3
|
+
* elements, plain-object property values), so a mutation anywhere in the
|
|
4
|
+
* structure throws instead of silently succeeding.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Generalized from `live-expirations.ts`'s former `DiscoveredContract[]`-
|
|
8
|
+
* hardcoded `deepFreezeContracts()` (see ADR 0012) into a truly generic
|
|
9
|
+
* utility, so Evidence Model's own immutability guarantee (a later phase)
|
|
10
|
+
* can reuse it instead of duplicating the recursion.
|
|
11
|
+
*
|
|
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
|
+
* walked further. This codebase's fact models are plain JSON-serializable
|
|
15
|
+
* data, never class instances, so this is deliberately narrow rather than a
|
|
16
|
+
* general-purpose deep-freeze library. A `WeakSet` guards against infinite
|
|
17
|
+
* recursion if a cyclic reference is ever passed in.
|
|
18
|
+
*/
|
|
19
|
+
export declare function deepFreeze<T>(value: T): T;
|
|
20
|
+
//# sourceMappingURL=deep-freeze.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"deep-freeze.d.ts","sourceRoot":"","sources":["../../../src/build/deep-freeze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEzC"}
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
import type { EscapeReason } from "./scan-dependencies.js";
|
|
2
|
+
import type { ImportResolutionContext } from "./resolution/resolve-import.js";
|
|
3
|
+
import type { DiscoveredContract } from "./link.js";
|
|
4
|
+
import type { ParseWarning } from "./parse.js";
|
|
5
|
+
import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
|
|
6
|
+
/**
|
|
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"`).
|
|
11
|
+
*
|
|
12
|
+
* @remarks
|
|
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`
|
|
23
|
+
* citations stay a wholly separate fact and are never folded into this
|
|
24
|
+
* status (ADR 0037).
|
|
25
|
+
*/
|
|
26
|
+
export type VariableAccessStatus = "used" | "unconsumed" | "indeterminate";
|
|
27
|
+
/**
|
|
28
|
+
* Every reason `deriveOwnershipFindings` can cite for an `indeterminate`
|
|
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.
|
|
35
|
+
*/
|
|
36
|
+
type EscapeVia = EscapeReason | "reference";
|
|
37
|
+
/** One position where a tracked contract's value escaped this scanner's local dataflow analysis: see {@link EscapeVia}. */
|
|
38
|
+
interface EscapeSite extends SourcePosition {
|
|
39
|
+
readonly via: EscapeVia;
|
|
40
|
+
}
|
|
41
|
+
interface VariableAccessInfo {
|
|
42
|
+
readonly status: VariableAccessStatus;
|
|
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. */
|
|
46
|
+
readonly evidence: "member-access" | "dynamic-access" | "escape" | "no-access";
|
|
47
|
+
/** Every position where a member access was observed for this variable,
|
|
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. */
|
|
53
|
+
readonly positions: readonly SourcePosition[];
|
|
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. */
|
|
55
|
+
readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
|
|
56
|
+
}
|
|
57
|
+
/** One named surface `buildDependencyGraph()`'s scan actually covered: the
|
|
58
|
+
* application's own root, plus one entry per allow-listed `packages` (ADR
|
|
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. */
|
|
62
|
+
export interface ScannedSurface {
|
|
63
|
+
/** `"application"` for the local project root, `"package:<name>"` for an allow-listed package's own source. */
|
|
64
|
+
readonly label: string;
|
|
65
|
+
/** Root-relative, POSIX-separated. */
|
|
66
|
+
readonly root: string;
|
|
67
|
+
}
|
|
68
|
+
interface ContractDependencySummary {
|
|
69
|
+
readonly file: string;
|
|
70
|
+
readonly exportName: string;
|
|
71
|
+
readonly contractName: string;
|
|
72
|
+
readonly imported: boolean;
|
|
73
|
+
readonly hasDynamicAccess: boolean;
|
|
74
|
+
/** Every declared key is always present. */
|
|
75
|
+
readonly variables: ReadonlyMap<string, VariableAccessInfo>;
|
|
76
|
+
/** Every file coupled to this contract: contract-level "who depends on
|
|
77
|
+
* this," not proof any specific variable was read. See the
|
|
78
|
+
* consumer-vs-variable-access semantics note in `deriveOwnershipFindings`. */
|
|
79
|
+
readonly consumingFiles: readonly string[];
|
|
80
|
+
/** Files whose import of this contract's name couldn't be verified
|
|
81
|
+
* because it resolved through a file containing an unresolved wildcard
|
|
82
|
+
* re-export. */
|
|
83
|
+
readonly ambiguousBarrelFiles: readonly string[];
|
|
84
|
+
/** Every computed (dynamic) property-access site observed anywhere on
|
|
85
|
+
* this contract (ADR 0036). `hasDynamicAccess` only says that one exists.
|
|
86
|
+
* This list lets a finding cite where the uncertainty comes from. */
|
|
87
|
+
readonly dynamicAccessSites: readonly SourcePosition[];
|
|
88
|
+
/** Every position where the contract's value flowed somewhere this
|
|
89
|
+
* scanner's local dataflow analysis can't follow: see {@link
|
|
90
|
+
* EscapeVia} and ADR 0039. Like `dynamicAccessSites`, this widens every
|
|
91
|
+
* not-otherwise-accessed variable on the SAME contract to
|
|
92
|
+
* `indeterminate`, never `unconsumed`. */
|
|
93
|
+
readonly escapeSites: readonly EscapeSite[];
|
|
94
|
+
}
|
|
95
|
+
export interface DependencyGraph {
|
|
96
|
+
readonly contracts: readonly ContractDependencySummary[];
|
|
97
|
+
readonly warnings: readonly ParseWarning[];
|
|
98
|
+
/** Every surface actually scanned for usage: see {@link ScannedSurface}. Always has at least one entry (the application root). */
|
|
99
|
+
readonly scannedSurfaces: readonly ScannedSurface[];
|
|
100
|
+
}
|
|
101
|
+
/** Sorts two positions by file, then line. @internal Exported for direct unit coverage. */
|
|
102
|
+
export declare function byPosition(a: SourcePosition, b: SourcePosition): number;
|
|
103
|
+
export declare function buildDependencyGraph(contracts: readonly DiscoveredContract[], scanFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, scannedSurfaces?: readonly ScannedSurface[], dynamicAccessAcknowledgments?: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): Promise<DependencyGraph>;
|
|
104
|
+
interface AbandonedOwnershipFinding {
|
|
105
|
+
readonly file: string;
|
|
106
|
+
readonly exportName: string;
|
|
107
|
+
readonly contractName: string;
|
|
108
|
+
}
|
|
109
|
+
interface UnresolvedConsumerOwnershipFinding extends AbandonedOwnershipFinding {
|
|
110
|
+
readonly reason: string;
|
|
111
|
+
}
|
|
112
|
+
interface UnconsumedOwnedVariableOwnershipFinding extends AbandonedOwnershipFinding {
|
|
113
|
+
readonly key: string;
|
|
114
|
+
}
|
|
115
|
+
interface IndeterminateAccessOwnershipFinding extends AbandonedOwnershipFinding {
|
|
116
|
+
readonly key: string;
|
|
117
|
+
readonly reason: string;
|
|
118
|
+
/** Every AST-observed dynamic-access site on this contract: see ADR 0036. */
|
|
119
|
+
readonly dynamicAccessSites: readonly SourcePosition[];
|
|
120
|
+
/** Every AST-observed escape site on this contract: see {@link EscapeVia} and ADR 0039. */
|
|
121
|
+
readonly escapeSites: readonly EscapeSite[];
|
|
122
|
+
}
|
|
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. */
|
|
124
|
+
interface AssertedOwnershipFinding extends AbandonedOwnershipFinding {
|
|
125
|
+
readonly key: string;
|
|
126
|
+
readonly wouldBeStatus: "unconsumed" | "indeterminate";
|
|
127
|
+
readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
|
|
128
|
+
}
|
|
129
|
+
export interface OwnershipFindings {
|
|
130
|
+
readonly abandoned: readonly AbandonedOwnershipFinding[];
|
|
131
|
+
readonly unresolvedConsumers: readonly UnresolvedConsumerOwnershipFinding[];
|
|
132
|
+
readonly unconsumedOwned: readonly UnconsumedOwnedVariableOwnershipFinding[];
|
|
133
|
+
readonly indeterminate: readonly IndeterminateAccessOwnershipFinding[];
|
|
134
|
+
readonly asserted: readonly AssertedOwnershipFinding[];
|
|
135
|
+
}
|
|
136
|
+
/**
|
|
137
|
+
* Derives ownership findings from the graph. This is where the epistemic
|
|
138
|
+
* rules that matter most live:
|
|
139
|
+
* - A contract never imported anywhere, with no ambiguous barrel path
|
|
140
|
+
* either, is `abandoned`; a feature's schema outliving the feature.
|
|
141
|
+
* - A contract never *directly* imported, but reachable only through an
|
|
142
|
+
* unresolved barrel re-export, is `unresolvedConsumers`: never
|
|
143
|
+
* `abandoned`. Claiming "abandoned" here would be a false positive with
|
|
144
|
+
* real consequences.
|
|
145
|
+
* - A variable with no member access anywhere, on a contract with no
|
|
146
|
+
* dynamic access anywhere, is `unconsumedOwned`. That means "no consumer
|
|
147
|
+
* found in this repository", not "provably dead". The scanned surfaces are named
|
|
148
|
+
* explicitly in the reason, per ADR 0036, so the claim is exactly as
|
|
149
|
+
* strong as what was actually searched.
|
|
150
|
+
* - A variable with no member access, but dynamic access observed
|
|
151
|
+
* *somewhere* on that contract, is `indeterminate`: never
|
|
152
|
+
* `unconsumedOwned`. Uncertainty is never promoted to certainty in either
|
|
153
|
+
* direction. Every candidate dynamic-access site is cited by name.
|
|
154
|
+
* - A variable with at least one `"fresh"` {@link DynamicAccessAssertion}
|
|
155
|
+
* (ADR 0037) gets neither `unconsumedOwned` nor `indeterminate`, regardless
|
|
156
|
+
* of `status`: a developer has re-acknowledged the access exists. The
|
|
157
|
+
* Dependency Model itself still keeps `status` and the assertion side by
|
|
158
|
+
* side, unedited; only *this* finding-suppression decision reads them
|
|
159
|
+
* together.
|
|
160
|
+
*/
|
|
161
|
+
export declare function deriveOwnershipFindings(graph: DependencyGraph): OwnershipFindings;
|
|
162
|
+
export {};
|
|
163
|
+
//# sourceMappingURL=dependency-graph.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../../../src/build/dependency-graph.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
import type { ContractRef } from "./evidence-reference.js";
|
|
2
|
+
import type { ScannedSurface, VariableAccessStatus } from "./dependency-graph.js";
|
|
3
|
+
import type { DiscoveredContract } from "./link.js";
|
|
4
|
+
import type { ParseWarning } from "./parse.js";
|
|
5
|
+
import type { ImportResolutionContext } from "./resolution/resolve-import.js";
|
|
6
|
+
import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
|
|
7
|
+
/**
|
|
8
|
+
* The second of env-cap's seven canonical fact models (ADR 0024): a
|
|
9
|
+
* versioned, JSON-serializable projection of the dependency-ownership
|
|
10
|
+
* engine's graph. See ADR 0027 and ADR 0036.
|
|
11
|
+
*
|
|
12
|
+
* @remarks
|
|
13
|
+
* `dependency-graph.ts`'s scanning/graph-building internals stay Private,
|
|
14
|
+
* unchanged, per ADR 0010: this is a fact-shaped *result* built on top of
|
|
15
|
+
* them, not a relaxation of that boundary. Graph-format rendering (DOT,
|
|
16
|
+
* Mermaid, a `{nodes, edges}` JSON export) is deliberately not here:
|
|
17
|
+
* that's presentation over this model's data, not the model itself.
|
|
18
|
+
*/
|
|
19
|
+
/** Bump only when a reader could misinterpret the new shape: same discipline every other canonical model's `schemaVersion` follows. */
|
|
20
|
+
export declare const DEPENDENCY_MODEL_SCHEMA_VERSION = 2;
|
|
21
|
+
/**
|
|
22
|
+
* One variable's access status within a contract, plus every position it was found
|
|
23
|
+
* member-accessed at, aggregated across every consuming file.
|
|
24
|
+
*
|
|
25
|
+
* @see {@link ContractModelVariable}: this same declared variable's canonical starting point.
|
|
26
|
+
*/
|
|
27
|
+
export interface DependencyModelVariable {
|
|
28
|
+
readonly key: string;
|
|
29
|
+
readonly status: VariableAccessStatus;
|
|
30
|
+
/** Empty unless `status === "used"`. Each entry is a full position with its file (ADR 0027, ADR 0036). */
|
|
31
|
+
readonly positions: readonly SourcePosition[];
|
|
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
|
+
readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
|
|
34
|
+
}
|
|
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
|
+
export interface DependencyModelContract {
|
|
37
|
+
/** Root-relative, POSIX-separated: matches `ContractModelContract.file`. */
|
|
38
|
+
readonly file: string;
|
|
39
|
+
readonly exportName: string;
|
|
40
|
+
readonly contractName: string;
|
|
41
|
+
readonly imported: boolean;
|
|
42
|
+
readonly hasDynamicAccess: boolean;
|
|
43
|
+
readonly variables: readonly DependencyModelVariable[];
|
|
44
|
+
/** Every file coupled to this contract: contract-level "who depends on this," not proof any specific variable was read. */
|
|
45
|
+
readonly consumingFiles: readonly string[];
|
|
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
|
+
readonly ambiguousBarrelFiles: readonly string[];
|
|
48
|
+
/** Every computed (dynamic) property-access site observed anywhere on this contract: see ADR 0036. */
|
|
49
|
+
readonly dynamicAccessSites: readonly SourcePosition[];
|
|
50
|
+
}
|
|
51
|
+
/** One contract, as referenced from the inverse (`consumers`) index: see {@link ContractRef} for why no `contractName` is carried here. */
|
|
52
|
+
export type DependencyModelContractRef = ContractRef;
|
|
53
|
+
/** One consuming file, and every contract it depends on: the inverse of `DependencyModelContract.consumingFiles`. */
|
|
54
|
+
export interface DependencyModelConsumer {
|
|
55
|
+
/** Root-relative, POSIX-separated. */
|
|
56
|
+
readonly file: string;
|
|
57
|
+
readonly contracts: readonly DependencyModelContractRef[];
|
|
58
|
+
}
|
|
59
|
+
/** The versioned, JSON-serializable root of the Dependency Model: see this module's own doc comment for the full picture. */
|
|
60
|
+
export interface DependencyModel {
|
|
61
|
+
readonly schemaVersion: typeof DEPENDENCY_MODEL_SCHEMA_VERSION;
|
|
62
|
+
readonly contracts: readonly DependencyModelContract[];
|
|
63
|
+
/** Inverse of `contracts[].consumingFiles`: one entry per file that consumes at least one contract, listing which contracts it reads. */
|
|
64
|
+
readonly consumers: readonly DependencyModelConsumer[];
|
|
65
|
+
readonly warnings: readonly ParseWarning[];
|
|
66
|
+
/** Every surface actually scanned for usage: see ADR 0036. Always has at least one entry (the application root). */
|
|
67
|
+
readonly scannedSurfaces: readonly ScannedSurface[];
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Runs the dependency-ownership engine (`buildDependencyGraph()`, Private)
|
|
71
|
+
* and projects its result into the Dependency Model's versioned,
|
|
72
|
+
* JSON-serializable shape: including the inverse file-\>contracts index
|
|
73
|
+
* neither `dependency-graph.ts` nor `usage-report.ts` exposes today.
|
|
74
|
+
*
|
|
75
|
+
* @param scannedSurfaces - See `buildDependencyGraph()`'s own parameter of
|
|
76
|
+
* the same name: passed straight through to the published model.
|
|
77
|
+
* @param dynamicAccessAcknowledgments - See `buildDependencyGraph()`'s own
|
|
78
|
+
* parameter of the same name (ADR 0037): passed straight through.
|
|
79
|
+
*/
|
|
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
|
+
//# sourceMappingURL=dependency-model.d.ts.map
|
|
@@ -0,0 +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,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"}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { BuildFileSystem } from "./types.js";
|
|
2
|
+
/** Options for {@link discoverSchemaFiles}. */
|
|
3
|
+
export interface DiscoverOptions {
|
|
4
|
+
/** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
|
|
5
|
+
readonly fs: BuildFileSystem;
|
|
6
|
+
/** Absolute path to search under. */
|
|
7
|
+
readonly root: string;
|
|
8
|
+
/** Glob patterns (relative to `root`) a file must match at least one of to be included. */
|
|
9
|
+
readonly include: readonly string[];
|
|
10
|
+
/** Glob patterns (relative to `root`) that prune a file or directory regardless of `include`. */
|
|
11
|
+
readonly exclude: readonly string[];
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Finds every file matching `include`/`exclude` under `root`, returned as
|
|
15
|
+
* absolute paths in deterministic (alphabetically sorted) order. No count
|
|
16
|
+
* limit: the usage scan walks every TypeScript source file, which a large
|
|
17
|
+
* project legitimately has thousands of; {@link discoverSchemaFiles} adds the
|
|
18
|
+
* schema-specific sanity limit on top.
|
|
19
|
+
*
|
|
20
|
+
* @remarks
|
|
21
|
+
* No external glob dependency. Directories are pruned *during* the walk
|
|
22
|
+
* (both a hardcoded node_modules/.git skip and the caller's `exclude`
|
|
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
|
+
*/
|
|
27
|
+
export declare function discoverFiles(options: DiscoverOptions): Promise<string[]>;
|
|
28
|
+
/**
|
|
29
|
+
* Finds every schema file matching `include`/`exclude` under `root`, returned
|
|
30
|
+
* as absolute paths in deterministic (alphabetically sorted) order: the
|
|
31
|
+
* same walk as `discoverFiles`, plus a sanity limit on the count.
|
|
32
|
+
*
|
|
33
|
+
* @remarks
|
|
34
|
+
* No external glob dependency. Directories are pruned *during* the walk
|
|
35
|
+
* (both a hardcoded node_modules/.git skip and the caller's `exclude`
|
|
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
|
+
*/
|
|
40
|
+
export declare function discoverSchemaFiles(options: DiscoverOptions): Promise<string[]>;
|
|
41
|
+
//# sourceMappingURL=discover.d.ts.map
|
|
@@ -0,0 +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,+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"}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Root-relative paths for published artifacts, bound to env-cap. The behavior lives in
|
|
3
|
+
* `../_ipc/display-path.ts`, a managed copy of internal-package-contract's `runtime/display-path.ts`.
|
|
4
|
+
*/
|
|
5
|
+
export { displayPath } from "../_ipc/display-path.js";
|
|
6
|
+
//# sourceMappingURL=display-path.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"display-path.d.ts","sourceRoot":"","sources":["../../../src/build/display-path.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA"}
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
import type { ContractModelContract } from "./contract-model.js";
|
|
2
|
+
import { type EnvGovernanceFields } from "./governance-fields.js";
|
|
3
|
+
import type { DiscoveredVariableEvidence } from "./parse.js";
|
|
4
|
+
/** Identifies a contract with no linked `documentEnv()` call at all. Whether `file` is absolute or relative depends on the field using this type. `DocumentationFindings.undocumentedContracts` is absolute. `RenderDocsOptions.undocumentedContracts` must be root-relative, matching the `ContractModel`-shaped `contracts` it's compared against. */
|
|
5
|
+
export interface UndocumentedContractRef {
|
|
6
|
+
readonly file: string;
|
|
7
|
+
/** The contract's exported binding name. */
|
|
8
|
+
readonly exportName: string;
|
|
9
|
+
}
|
|
10
|
+
/** Identifies a schema variable with no matching entry in its contract's linked documentation. See {@link UndocumentedContractRef}'s own note on `file`. */
|
|
11
|
+
export interface UndocumentedVariableRef {
|
|
12
|
+
readonly file: string;
|
|
13
|
+
/** The contract's exported binding name. */
|
|
14
|
+
readonly exportName: string;
|
|
15
|
+
/** The undocumented environment variable name. */
|
|
16
|
+
readonly key: string;
|
|
17
|
+
}
|
|
18
|
+
/** One contract- or variable-level `expiresAt` falling within the configured "expiring soon" window. */
|
|
19
|
+
export interface ExpiringEntry {
|
|
20
|
+
/** Absolute path of the file declaring the contract. */
|
|
21
|
+
readonly file: string;
|
|
22
|
+
/** The contract's exported binding name. */
|
|
23
|
+
readonly exportName: string;
|
|
24
|
+
/** `undefined` for a contract-level `expiresAt`, set for a per-variable one. */
|
|
25
|
+
readonly key: string | undefined;
|
|
26
|
+
/** The raw ISO date string, unparsed. */
|
|
27
|
+
readonly expiresAt: string;
|
|
28
|
+
/** Days from `now` until expiry; negative when already expired. */
|
|
29
|
+
readonly daysRemaining: number;
|
|
30
|
+
}
|
|
31
|
+
/** Options for {@link renderDocs}. */
|
|
32
|
+
export interface RenderDocsOptions {
|
|
33
|
+
/** How many days out counts as "expiring soon" in the lifecycle report and security review. */
|
|
34
|
+
readonly expiringWithinDays: number;
|
|
35
|
+
/** Contracts with no linked `documentEnv()` call at all. `file` must be root-relative, POSIX-separated: matching `contracts`' own `ContractModel` convention, since this is matched against it by identity. */
|
|
36
|
+
readonly undocumentedContracts: readonly UndocumentedContractRef[];
|
|
37
|
+
/** Schema variables with no matching entry in their contract's linked documentation. Only how many there are is rendered (the security-review counter), so `file` is not matched against anything. */
|
|
38
|
+
readonly undocumentedVariables: readonly UndocumentedVariableRef[];
|
|
39
|
+
/** Timestamp rendered into the header and used for expiry/days-remaining math. */
|
|
40
|
+
readonly generatedAt: Date;
|
|
41
|
+
/** Content already at `docs.location`, if any: used only for the "changes since last report" summary. */
|
|
42
|
+
readonly previousContent: string | undefined;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Parses `expiresAt` as a real date.
|
|
46
|
+
*
|
|
47
|
+
* @remarks
|
|
48
|
+
* Malformed strings are silently ignored (return `undefined`) rather than throwing: same
|
|
49
|
+
* "warn/skip, never guess" policy as the rest of the generator. Exported so `live-expirations.ts`
|
|
50
|
+
* can validate live override values against the exact same rule used for static `expiresAt`.
|
|
51
|
+
*/
|
|
52
|
+
export declare function parseIsoDate(value: string): Date | undefined;
|
|
53
|
+
/** The minimal shape {@link computeExpiringEntries} needs. It is structural, not pinned to `DiscoveredContract`, so one rule serves both kinds of contract. Those are `LinkResult`'s absolute-path contracts (`generate-documentation.ts`'s `documentation.expiringSoon`, Stable tier) and `ContractModel`'s root-relative ones. */
|
|
54
|
+
interface ExpiryBearingContract {
|
|
55
|
+
readonly file: string;
|
|
56
|
+
readonly exportName: string;
|
|
57
|
+
readonly expiresAt: string | undefined;
|
|
58
|
+
readonly variables: readonly {
|
|
59
|
+
readonly key: string;
|
|
60
|
+
readonly expiresAt: string | undefined;
|
|
61
|
+
}[];
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Computes every contract- or variable-level `expiresAt` within `expiringWithinDays` of `now`, sorted soonest-first.
|
|
65
|
+
*/
|
|
66
|
+
export declare function computeExpiringEntries(contracts: readonly ExpiryBearingContract[], expiringWithinDays: number, now: Date): ExpiringEntry[];
|
|
67
|
+
/**
|
|
68
|
+
* Same data `renderCatalog()` renders to Markdown for one variable, reshaped for JSON/
|
|
69
|
+
* programmatic consumers instead of prose.
|
|
70
|
+
*
|
|
71
|
+
* @see `ContractModelVariable` (`contract-model.ts`): this same declared variable's canonical
|
|
72
|
+
* starting point. Plain reference, not `{@link}`: this type is intentionally not part of the
|
|
73
|
+
* public surface (see `typedoc.json`'s `intentionallyNotExported`).
|
|
74
|
+
*/
|
|
75
|
+
interface CatalogVariable extends EnvGovernanceFields {
|
|
76
|
+
readonly description: string | undefined;
|
|
77
|
+
readonly refreshInstructions: string | undefined;
|
|
78
|
+
readonly setupInstructions: string | undefined;
|
|
79
|
+
readonly required: boolean | undefined;
|
|
80
|
+
readonly hasDefault: boolean;
|
|
81
|
+
readonly hasProcessor: boolean;
|
|
82
|
+
readonly processorReturnType: string | undefined;
|
|
83
|
+
readonly hasValidator: boolean;
|
|
84
|
+
readonly documented: boolean;
|
|
85
|
+
/** The variable's declared validation context, if any: see ADR 0022. Participation data, not documentation: describes when `validateEnv()` processes this variable, not who may access it or what a bundler includes. */
|
|
86
|
+
readonly context: string | undefined;
|
|
87
|
+
/** The `evidence` sub-object from this variable's linked documentation: re-verified every run, unlike every declared-only field above. See ADR 0037. */
|
|
88
|
+
readonly evidence: DiscoveredVariableEvidence | undefined;
|
|
89
|
+
}
|
|
90
|
+
export interface CatalogContract extends EnvGovernanceFields {
|
|
91
|
+
readonly file: string;
|
|
92
|
+
readonly exportName: string;
|
|
93
|
+
readonly contractName: string;
|
|
94
|
+
readonly active: boolean;
|
|
95
|
+
readonly documented: boolean;
|
|
96
|
+
readonly category: string | undefined;
|
|
97
|
+
readonly exclusiveGroup: string | undefined;
|
|
98
|
+
/** Keyed by variable name: unique within one contract (a schema
|
|
99
|
+
* object-literal property name), unlike `contractName` at the top level. */
|
|
100
|
+
readonly variables: Readonly<Record<string, CatalogVariable>>;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Same data `renderCatalog()` renders to Markdown, reshaped for JSON/
|
|
104
|
+
* programmatic consumers instead of prose. See `GenerateDocumentationResult.catalog`.
|
|
105
|
+
*/
|
|
106
|
+
export declare function buildCatalog(contracts: readonly ContractModelContract[]): CatalogContract[];
|
|
107
|
+
/** Every variable key that appeared as a catalog heading in a previously-generated docs file. Exported for testing. */
|
|
108
|
+
export declare function extractPreviouslyDocumentedKeys(previousContent: string): Set<string>;
|
|
109
|
+
/**
|
|
110
|
+
* Every variable key that was documented under an *active* contract in a
|
|
111
|
+
* previously-generated docs file. It walks the `- Active: yes/no` marker
|
|
112
|
+
* `renderCatalog` always emits right after each `## <contract>` heading. So a
|
|
113
|
+
* key already inactive last time is excluded (a permanently-dormant contract,
|
|
114
|
+
* e.g. behind an unused feature flag). It is excluded even though it still
|
|
115
|
+
* appears as a `### \`KEY\`` heading. Exported for testing.
|
|
116
|
+
*/
|
|
117
|
+
export declare function extractPreviouslyActiveKeys(previousContent: string): Set<string>;
|
|
118
|
+
/** Every number the security review reports, as structured data instead of only rendered Markdown text. */
|
|
119
|
+
export interface SecurityReviewCounters {
|
|
120
|
+
readonly totalContracts: number;
|
|
121
|
+
readonly totalVariableDeclarations: number;
|
|
122
|
+
readonly activeVariableDeclarations: number;
|
|
123
|
+
readonly uniqueVariableNames: number;
|
|
124
|
+
readonly expiresAtSetCount: number;
|
|
125
|
+
readonly expiredCount: number;
|
|
126
|
+
readonly expiringSoonCount: number;
|
|
127
|
+
readonly requiredCount: number;
|
|
128
|
+
readonly refreshInstructionsCount: number;
|
|
129
|
+
readonly noOwnerCount: number;
|
|
130
|
+
readonly duplicateVariableNameCount: number;
|
|
131
|
+
readonly undocumentedContractCount: number;
|
|
132
|
+
readonly undocumentedVariableCount: number;
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Computes every number `renderSecurityReview()` reports, as real data.
|
|
136
|
+
*
|
|
137
|
+
* @remarks
|
|
138
|
+
* An exported type backs these numbers. So consumers other than the
|
|
139
|
+
* rendered Markdown can read them as data: the `--json` envelope, a CI gate,
|
|
140
|
+
* a future Finding Model adapter.
|
|
141
|
+
*/
|
|
142
|
+
export declare function computeSecurityReviewCounters(contracts: readonly ContractModelContract[], expiringWithinDays: number, now: Date, undocumentedContractCount: number, undocumentedVariableCount: number): SecurityReviewCounters;
|
|
143
|
+
/**
|
|
144
|
+
* Renders the full docs artifact. It opens with a header, change summary and
|
|
145
|
+
* table of contents. Then come the catalog, ownership matrix (if used),
|
|
146
|
+
* dependency graph, lifecycle report and security review.
|
|
147
|
+
*
|
|
148
|
+
* @remarks
|
|
149
|
+
* Documents everything discovered, active or not, same scope as the catalog always
|
|
150
|
+
* had. Fully regenerated every run: unlike `.env.example`, nothing here is
|
|
151
|
+
* meant to be hand-edited, so there's no "never overwrite" behavior.
|
|
152
|
+
*
|
|
153
|
+
* `contracts` is `ContractModel`'s own shape, so `file` is already
|
|
154
|
+
* root-relative and POSIX-separated (ADR 0038). There is no separate `root`
|
|
155
|
+
* parameter to resolve against.
|
|
156
|
+
*/
|
|
157
|
+
export declare function renderDocs(contracts: readonly ContractModelContract[], options: RenderDocsOptions): string;
|
|
158
|
+
/**
|
|
159
|
+
* Normalizes every wall-clock-relative substring `renderDocs()` can produce,
|
|
160
|
+
* so two renders of the *same* input on different days compare equal. That
|
|
161
|
+
* covers the `_Generated ..._` timestamp line, the lifecycle report's
|
|
162
|
+
* `(**Xd remaining**)`/`(**expired Xd ago**)` annotations, and the security
|
|
163
|
+
* review's "Already expired"/"Expiring within N days" counts.
|
|
164
|
+
* `check-artifacts.ts`'s drift comparison and the examples golden-file test
|
|
165
|
+
* harness (`test/support/example-runner.ts`) both need all of it. A contract
|
|
166
|
+
* with a near-term `expiresAt` renders day-relative text. Without this,
|
|
167
|
+
* `--check` (or a golden-file comparison) would report false drift only
|
|
168
|
+
* because real time passed between generation and comparison.
|
|
169
|
+
*/
|
|
170
|
+
export declare function normalizeDocsForComparison(content: string): string;
|
|
171
|
+
export {};
|
|
172
|
+
//# sourceMappingURL=docs.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/build/docs.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import type { DiscoveredContract } from "./link.js";
|
|
2
|
+
import type { BuildFileSystem } from "./types.js";
|
|
3
|
+
/**
|
|
4
|
+
* Controls what happens when a `.env.example` already exists at the target
|
|
5
|
+
* location. `"keep-sibling"` (default): never touch the existing file;
|
|
6
|
+
* write a timestamped sibling instead, for the developer to diff/merge
|
|
7
|
+
* manually. `"overwrite"`: replace the existing file with freshly rendered
|
|
8
|
+
* content directly. `"skip"`: write nothing at all.
|
|
9
|
+
*/
|
|
10
|
+
export type EnvExampleOnExisting = "keep-sibling" | "overwrite" | "skip";
|
|
11
|
+
/** The result of a completed {@link writeEnvExample} call. */
|
|
12
|
+
export interface EnvExampleResult {
|
|
13
|
+
/**
|
|
14
|
+
* Where the example file actually got written. `undefined` only when
|
|
15
|
+
* `onExisting: "skip"` left an existing file untouched and nothing was
|
|
16
|
+
* written.
|
|
17
|
+
*/
|
|
18
|
+
readonly writtenPath: string | undefined;
|
|
19
|
+
/**
|
|
20
|
+
* Set when a file already existed at the requested location and was left
|
|
21
|
+
* untouched: with the default `"keep-sibling"`, `writtenPath` is a fresh
|
|
22
|
+
* timestamped sibling instead; with `"skip"`, this is the only outcome and
|
|
23
|
+
* `writtenPath` is `undefined`. Always `undefined` with `"overwrite"`.
|
|
24
|
+
*/
|
|
25
|
+
readonly skippedExistingPath: string | undefined;
|
|
26
|
+
/** Variable names (live or already commented-out) in an existing example file that no discovered contract declares anymore. */
|
|
27
|
+
readonly staleVariables: readonly string[];
|
|
28
|
+
/** Variables live in an existing example file whose feature is no longer active, and that no other active feature still needs: safe to comment out. */
|
|
29
|
+
readonly variablesToComment: readonly string[];
|
|
30
|
+
/** Variables the current (active) configuration requires that aren't yet a live entry in an existing example file. */
|
|
31
|
+
readonly variablesToAdd: readonly string[];
|
|
32
|
+
}
|
|
33
|
+
/** The result of {@link computeReconciliation}: an existing `.env.example` diffed against the current configuration. */
|
|
34
|
+
export interface Reconciliation {
|
|
35
|
+
/** Variable names (live or already commented-out) in an existing example file that no discovered contract declares anymore. */
|
|
36
|
+
readonly staleVariables: readonly string[];
|
|
37
|
+
/** Variables live in an existing example file whose feature is no longer active, and that no other active feature still needs: safe to comment out. */
|
|
38
|
+
readonly variablesToComment: readonly string[];
|
|
39
|
+
/** Variables the current (active) configuration requires that aren't yet a live entry in an existing example file. */
|
|
40
|
+
readonly variablesToAdd: readonly string[];
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Renders a deterministic `.env.example`-style file scoped to the *current*
|
|
44
|
+
* configuration. It lists every unique variable the active contracts
|
|
45
|
+
* require, one live entry per key, alphabetically. A key declared by more
|
|
46
|
+
* than one active contract renders once live; the rest are commented out
|
|
47
|
+
* with a pointer. Variables unique to disabled contracts follow, commented
|
|
48
|
+
* out for visibility. A key already required by an active contract is not
|
|
49
|
+
* unique and never repeated there. `reconciliationHeader`, when non-empty, is
|
|
50
|
+
* spliced in right after the banner (see `computeReconciliation`).
|
|
51
|
+
*/
|
|
52
|
+
export declare function renderEnvExample(contracts: readonly DiscoveredContract[], reconciliationHeader?: readonly string[]): string;
|
|
53
|
+
/** Parses `KEY=value` lines out of an existing `.env`-style file, ignoring comments and blank lines. */
|
|
54
|
+
export declare function extractDeclaredVariables(source: string): string[];
|
|
55
|
+
/** Parses `# KEY=value` lines out of an existing `.env`-style file: variables it already knows about but has turned off. */
|
|
56
|
+
export declare function extractCommentedVariables(source: string): string[];
|
|
57
|
+
/**
|
|
58
|
+
* Diffs an existing `.env.example` against the current configuration into
|
|
59
|
+
* three actionable sets. Pure and filesystem-independent: `writeEnvExample`
|
|
60
|
+
* is the only caller that reads the file itself.
|
|
61
|
+
*/
|
|
62
|
+
export declare function computeReconciliation(contracts: readonly DiscoveredContract[], existingContent: string): Reconciliation;
|
|
63
|
+
/**
|
|
64
|
+
* Writes a rendered `.env.example` to `location`. Behavior when a file
|
|
65
|
+
* already exists there is governed by `options.onExisting` (default
|
|
66
|
+
* `"keep-sibling"`, see `EnvExampleOnExisting`):
|
|
67
|
+
* - `"keep-sibling"`: the existing file is left alone; freshly generated
|
|
68
|
+
* content is written to a timestamped sibling instead
|
|
69
|
+
* (`<location>.<epoch-ms>`), prefixed with a reconciliation header
|
|
70
|
+
* comparing it against the existing file (omitted when there's nothing
|
|
71
|
+
* to report).
|
|
72
|
+
* - `"overwrite"`: the existing file is replaced directly with freshly
|
|
73
|
+
* rendered content; no reconciliation header (the changes it would
|
|
74
|
+
* describe are already applied).
|
|
75
|
+
* - `"skip"`: nothing is written.
|
|
76
|
+
* When no file exists yet at `location`, all three modes behave the same:
|
|
77
|
+
* write fresh content, nothing to reconcile against. `staleVariables`/
|
|
78
|
+
* `variablesToComment`/`variablesToAdd` are always computed and returned
|
|
79
|
+
* when a prior file existed, even under `"overwrite"`/`"skip"`, as a
|
|
80
|
+
* diagnostic: independent of whether anything was actually written.
|
|
81
|
+
*/
|
|
82
|
+
export declare function writeEnvExample(contracts: readonly DiscoveredContract[], location: string, fs: BuildFileSystem, options?: {
|
|
83
|
+
onExisting?: EnvExampleOnExisting;
|
|
84
|
+
}): Promise<EnvExampleResult>;
|
|
85
|
+
//# sourceMappingURL=env-example.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"env-example.d.ts","sourceRoot":"","sources":["../../../src/build/env-example.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGjD;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,WAAW,GAAG,MAAM,CAAA;AAExE,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,+HAA+H;IAC/H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,uJAAuJ;IACvJ,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAED,wHAAwH;AACxH,MAAM,WAAW,cAAc;IAC7B,+HAA+H;IAC/H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,uJAAuJ;IACvJ,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAuED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,oBAAoB,GAAE,SAAS,MAAM,EAAO,GAC3C,MAAM,CAiDR;AAED,wGAAwG;AACxG,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAQjE;AAED,4HAA4H;AAC5H,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAQlE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,eAAe,EAAE,MAAM,GACtB,cAAc,CAkBhB;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,eAAe,EACnB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,oBAAoB,CAAA;CAAO,GAClD,OAAO,CAAC,gBAAgB,CAAC,CA6D3B"}
|