@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
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,47 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.7.6
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- aa38823: Documentation, help text and message wording only. No flag, export, exit code, error code or behaviour changed.
|
|
8
|
+
|
|
9
|
+
- Sentences that said a CI job "does not yet block a merge" now name the job and say that the `required` check depends on it. That is because the branch ruleset requires `required`.
|
|
10
|
+
- A failed benchmark job now fails `contract` as well, so it can no longer pass a merge by skipping the other gate jobs.
|
|
11
|
+
- VERSIONING says which exit codes the surface baseline covers (`--help` of the CLI and of `init`) and which a test pins instead.
|
|
12
|
+
- `env-cap --help` lists the exit codes (`0` and `1` and when each applies), so the surface baseline records them. The codes themselves did not change.
|
|
13
|
+
- SECURITY no longer says that no release has run on the current release workflow.
|
|
14
|
+
- The `rotationStatus` value `"compliant"` keeps its name; its TSDoc no longer promises a rename at 1.0, only that a rename would need a major release.
|
|
15
|
+
- `env-cap init --help` rewords one sentence about next steps; the surface baseline is refreshed to match.
|
|
16
|
+
- README's entry-point table is now generated from `package.json` and `docs/surface.json`.
|
|
17
|
+
- Messages and generated text no longer use `--` as a dash: error and warning messages, the `.env.example` notes (`Disabled: feature ...`, `Also declared by ... See ...`), the ownership report's section text, the `init` output and starter template, and the published JSON Schema descriptions. Only the wording changed; codes, keys, file names and the `GENERATED FILE -- do not edit by hand` banner are unchanged.
|
|
18
|
+
- A new test fails when a published JSON Schema removes, retypes or makes optional a field while its `schemaVersion` stays the same.
|
|
19
|
+
- SECURITY says the release requires both `contract` and `required`.
|
|
20
|
+
- The package description, keywords, README opening, landing page and agent skill now say in one sentence what env-cap is, what it reports, what it works alongside and what it does not do.
|
|
21
|
+
- `env-cap --help` opens with what the CLI writes ("the manifest your app passes to `validateEnv()`, an evidence file, or both") and calls the `--evidence` output the evidence file. The flags and exit codes are unchanged.
|
|
22
|
+
- Each entry point (`./build`, `./helpers`, `./node`, `./evidence`, `./eslint-plugin`) now has a module overview in the API reference.
|
|
23
|
+
- A test fails when a document's list of CI-tested Node versions differs from the `verify` matrix in ci.yml.
|
|
24
|
+
- The npm description, README, landing page and agent skill open with one pitch: each feature declares its variables and their format, and your app validates them at startup and reports how to rotate them before they expire. A test fails when the four copies differ.
|
|
25
|
+
- The README's first screen shows the startup error the `init` starter contract throws for a bad value. A test runs `validateEnv()` on that contract and fails when the excerpt differs.
|
|
26
|
+
- `PROMPT.md` is removed from the package; the agent skill and `AGENTS.md` carry its rules.
|
|
27
|
+
- The `ManifestChangeReport` description in the published JSON Schema no longer points at source code the reader cannot see.
|
|
28
|
+
- A new test runs the README quick start (`env-cap init`, then the scaffolded `scripts/generate-env.mjs`) against the built package, so the README and landing page no longer say CI skips it.
|
|
29
|
+
|
|
30
|
+
## 0.7.5
|
|
31
|
+
|
|
32
|
+
### Patch Changes
|
|
33
|
+
|
|
34
|
+
- 72cb72c: Documentation now describes the TypeScript 6 compiler as the package's one npm dependency, bundled inside the tarball and used only by the build entry, and says that installing your own TypeScript is optional. The rotation-log example quotes NIST SP 800-53 IA-5(f) verbatim and no longer calls itself a compliance artifact, and the enterprise example no longer describes its report as useful in litigation.
|
|
35
|
+
|
|
36
|
+
What installing the package adds is now generated into ADOPTION.md from `package.json` (`internal-package-contract generate`, reasons in `docs/surface.json`), and the standard-format documents it generates are a generated table in `specs/generated-artifacts.md` that cites the test checking each format. SARIF output is now validated in tests against the official OASIS 2.1.0 schema (a managed copy from internal-package-contract), and a finding with a position points at the cited file, percent-encoded.
|
|
37
|
+
- 72cb72c: Gates widened: the helpers and evidence entry points are executed under Bun and Deno in CI (not only the runtime); the TypeScript compat job parses all 23 committed schema fixtures under TypeScript 5, 6 and 7 roots and requires byte-identical results; the ambient-capability tarball scan also rejects `process.env` outside the CLI and the ESLint plugin; the `node:fs` import ban in `src/` is live again (two flat-config blocks had let the later one replace it); a `required` CI check stands for every job the ruleset could not name, and `contract` fails instead of skipping when `verify` or `lint` fails; `npm run setup` installs the shared git hooks.
|
|
38
|
+
|
|
39
|
+
Documentation now matches the gates behind it: coverage is described as fixed floors raised in review (not a self-moving ratchet); the compiler is described as bundled, about 24 MB; SECURITY names all six entry points in its no-network statement; VERSIONING's Private tier covers every entry point; the Action's `version` input is documented as required when env-cap is not installed, and the workflow examples install the package first; ADRs 0014 and 0023 carry their real status; `rotationStatus` is documented as a policy-window judgement, never a compliance statement, with the 1.0 rename announced. The Action's step summary is capped below GitHub's size limit.
|
|
40
|
+
|
|
41
|
+
TypeScript 7 consumers no longer need `skipLibCheck`: the build emits a second declaration tree (`dist/.dts7`) whose compiler-API types come from the bundled TypeScript 6, served only to TypeScript 7 through `types@>=7` export conditions; TypeScript 5 and 6 keep the declarations typed from their own `typescript`. The compat job type-checks every entry point but `./eslint-plugin` (typed through its `@typescript-eslint/utils` peer) with full library checking under all three and asserts which declaration set answered.
|
|
42
|
+
|
|
43
|
+
Every document is rewritten for its reader, with each promise naming the check behind it and the limit of that check in the same sentence: README as the map (an entry-point table and the output of `examples/application` as CI runs it), GUIDE by audience with one story per entry point, ADOPTION as the decision document (what it costs, needs and refuses to do), SECURITY as the reviewer's tables (mechanism, where it blocks, limit), VERSIONING with the real tier table, CONTRIBUTING and CODE_REVIEW to the real jobs and the hand-merged release pull request, and every example README with its command, exit code and the output line to look for. Claims the gates did not hold were narrowed or removed; a docs test now pins the size budgets, coverage floors and the dependency count the prose quotes.
|
|
44
|
+
|
|
3
45
|
## 0.7.4
|
|
4
46
|
|
|
5
47
|
### Patch Changes
|
package/CODE_REVIEW.md
CHANGED
|
@@ -1,200 +1,96 @@
|
|
|
1
1
|
# Reviewing changes to env-cap
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
answers one question: **what makes a change to this package safe to merge?**
|
|
5
|
-
It is not a second contributor guide and not a style checklist — CI already
|
|
6
|
-
enforces formatting, lint, types, coverage, and mutation score. This
|
|
7
|
-
document covers the judgement calls CI can't make.
|
|
3
|
+
A change is safe to merge when CI is green, no invariant below has moved, and every surface change is declared. CI checks formatting, lint, types, coverage and mutation; this list covers the rest. [`CONTRIBUTING.md`](CONTRIBUTING.md) is the author's side.
|
|
8
4
|
|
|
9
5
|
## 1. Review standard
|
|
10
6
|
|
|
11
|
-
A change is ready to merge when all of
|
|
7
|
+
A change is ready to merge when all of these hold:
|
|
12
8
|
|
|
13
|
-
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
- Every invariant in §2 that the change touches
|
|
18
|
-
|
|
19
|
-
- Any
|
|
20
|
-
|
|
21
|
-
- Any generated artifact in the diff (§4) has been reviewed as output, not
|
|
22
|
-
skimmed.
|
|
23
|
-
- The change doesn't weaken a capability boundary (§5).
|
|
9
|
+
- The `contract`, `lint` and `required` checks are green; the branch ruleset requires all three.
|
|
10
|
+
- `required` waits for every gate job in ci.yml: `verify`, `lint`, `contract`, `cross-runtime` (the Bun and Deno suite), `examples`, `integration-fixtures`, `typescript-5`, `typescript-compat`, `package-managers` and `benchmark-pr`.
|
|
11
|
+
- Three jobs are outside `required`. `verify-current` tries the newest Node and is informational. `badges` and `deploy` run only after a push to `main`.
|
|
12
|
+
- A `benchmark-pr` failure also fails `contract` in its first step, so it cannot pass as a skip.
|
|
13
|
+
- Every invariant in §2 that the change touches still holds, checked in the code, not the description.
|
|
14
|
+
- Any public-surface change (§3) is intended, explained, and carries the right changeset.
|
|
15
|
+
- Any generated artifact in the diff (§4) has been read as output.
|
|
16
|
+
- No capability boundary is weakened (§5).
|
|
24
17
|
|
|
25
|
-
When a change
|
|
26
|
-
that keeps an invariant intact beats a complete one that bends it "just for
|
|
27
|
-
now."
|
|
18
|
+
When a change cannot meet this bar in one pull request, split it.
|
|
28
19
|
|
|
29
20
|
## 2. Package invariants
|
|
30
21
|
|
|
31
|
-
These are
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
- **
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
- **
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
fires, nothing is written
|
|
54
|
-
([ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
|
|
55
|
-
- **Capability ownership — no global env object**
|
|
56
|
-
([ADR 0003](specs/decisions/0003-no-global-env-object.md)). Reject any
|
|
57
|
-
merged/global wrapper over multiple contracts.
|
|
58
|
-
- **Contracts self-redact; errors never carry values**
|
|
59
|
-
([ADR 0006](specs/decisions/0006-self-redacting-contracts.md)). Read
|
|
60
|
-
every new/changed error message, log line, and fixture: a raw or
|
|
61
|
-
processed env value must never appear. This is the single highest-value
|
|
62
|
-
thing to check by eye.
|
|
63
|
-
- **`--check` computes before it compares and never partially writes**
|
|
64
|
-
([ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
|
|
65
|
-
|
|
66
|
-
If a change genuinely needs to move one of these boundaries, it needs its
|
|
67
|
-
own ADR first (see [`CONTRIBUTING.md`](CONTRIBUTING.md#adding-an-architecture-decision-record-adr)),
|
|
68
|
-
not a reviewer waving it through.
|
|
69
|
-
|
|
70
|
-
## 3. Public API / stability review
|
|
71
|
-
|
|
72
|
-
[`VERSIONING.md`](VERSIONING.md) defines three tiers. Before approving:
|
|
73
|
-
|
|
74
|
-
- **Stable** (public runtime APIs, the four documented `generate*()` build
|
|
75
|
-
orchestrators, every `env-cap --help` flag, `--json` output, the
|
|
76
|
-
published JSON Schema, the generated manifest shape, the ESLint plugin's
|
|
77
|
-
rule names/options). A breaking change here needs a `major` changeset and
|
|
78
|
-
an explicit "yes, we're doing this" in the PR. An _additive_ change
|
|
79
|
-
(new optional flag, new optional option field, new export) is `minor` —
|
|
80
|
-
confirm it's genuinely additive and doesn't change a default.
|
|
81
|
-
- **`--json` and the JSON Schema** are versioned by their own
|
|
82
|
-
`schemaVersion` ([ADR 0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md),
|
|
83
|
-
[ADR 0019](specs/decisions/0019-published-json-schema-generated-from-types.md)).
|
|
84
|
-
Additive field: no bump. Changed/removed field: `schemaVersion` bump +
|
|
85
|
-
`major`. The schema is generated from the types (`npm run schema`) —
|
|
86
|
-
confirm the committed `schemas/*.json` in the diff matches.
|
|
87
|
-
- **Experimental** (the `packages` option, the lower-level `./build`
|
|
88
|
-
primitives, `./evidence`, `generateEvidenceModel` and friends). May
|
|
89
|
-
change shape in a `minor`/`patch` — but the change should still be
|
|
90
|
-
deliberate, and the ADR's Status line should reflect reality.
|
|
91
|
-
- **Private** (anything not re-exported, all AST-traversal internals, the
|
|
92
|
-
dependency-ownership engine internals per
|
|
93
|
-
[ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md)).
|
|
94
|
-
No bump, but check the change didn't leak an internal into a public
|
|
95
|
-
entry point.
|
|
96
|
-
|
|
97
|
-
Check `package.json#exports` in the diff: the allowed set is exactly `.`,
|
|
98
|
-
`./build`, `./node`, `./helpers`, `./evidence`, `./eslint-plugin`,
|
|
99
|
-
`./schema`, `./schema/*`, `./package.json`. A new entry is a public-surface
|
|
100
|
-
decision.
|
|
22
|
+
These are listed in [`AGENTS.md`](AGENTS.md) ("Non-negotiable invariants") and pinned by ADRs. Check that the change does not erode one, even indirectly:
|
|
23
|
+
|
|
24
|
+
- **Schemas are never executed** ([ADR 0002](specs/decisions/0002-static-analysis-never-execution.md)). Reject any change that adds `import()`, `require()`, `eval`, `new Function`, `vm`, a worker or a subprocess to the analysis path. Lint bans `eval` and `new Function`; the rest is yours to catch. An unresolvable value must surface as a finding, never a guess.
|
|
25
|
+
- **The runtime stays isomorphic and within budget** ([ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md), [ADR 0008](specs/decisions/0008-gzip-size-budget.md)). `src/runtime` and `src/helpers` must not import `node:*` or add a dependency. The browser-bundle test catches a Node import; nothing catches a third-party import.
|
|
26
|
+
- **Only `src/cli` may import `node:fs`.** ESLint enforces it in `src/`. `src/build` uses `node:path` and `typescript` and takes its filesystem from the caller. No runtime entry may reach `src/build`; `compiler-isolation` checks that.
|
|
27
|
+
- **Warn, do not throw, by default** ([ADR 0005](specs/decisions/0005-warn-not-throw-by-default.md)). New data-quality findings are warnings. Escalation happens only behind a `--strict*` flag or an `on*: "throw"` option, and nothing is written when it fires ([ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
|
|
28
|
+
- **No global env object** ([ADR 0003](specs/decisions/0003-no-global-env-object.md)). Reject any wrapper that merges contracts.
|
|
29
|
+
- **Errors never carry values** ([ADR 0006](specs/decisions/0006-self-redacting-contracts.md)). Read every new or changed error message, log line and fixture for a raw or processed value. This is the most valuable thing to check by eye.
|
|
30
|
+
- **`--check` computes before it compares and never writes** ([ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md)).
|
|
31
|
+
|
|
32
|
+
Moving one of these boundaries needs its own ADR first ([CONTRIBUTING.md](CONTRIBUTING.md#adding-an-architecture-decision-record-adr)).
|
|
33
|
+
|
|
34
|
+
## 3. Public API and stability review
|
|
35
|
+
|
|
36
|
+
[`VERSIONING.md`](VERSIONING.md) lists every entry point and its tier. Every entry point is Stable today; nothing ships Experimental ([ADR 0045](specs/decisions/0045-promote-experimental-surfaces-to-stable.md)).
|
|
37
|
+
|
|
38
|
+
- **Stable.** A breaking change needs a `major` changeset from 1.0, or a `minor` before 1.0, and an explicit decision in the pull request. In a hand-written changeset, an additive change is `minor`; confirm it does not change a default. `ApiContract` and `SurfaceContract` fail when the declared level is too low.
|
|
39
|
+
- **`--json` and the JSON Schema.** An additive field needs no `schemaVersion` bump. A changed or removed field needs a `schemaVersion` bump and a breaking changeset ([ADR 0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md), [ADR 0019](specs/decisions/0019-published-json-schema-generated-from-types.md)). No check ties the shape change to the bump, so check it here.
|
|
40
|
+
- **The schema is generated** from the types by `npm run schema`. The `Schema` check fails if the committed file differs.
|
|
41
|
+
- **Private.** Anything not re-exported, the AST-traversal internals, and the dependency-ownership engine ([ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md)). No bump, but check nothing internal leaked into an entry point.
|
|
42
|
+
|
|
43
|
+
Check `package.json#exports` in the diff. The allowed set is `.`, `./build`, `./node`, `./helpers`, `./evidence`, `./eslint-plugin`, `./schema`, `./schema/*` and `./package.json`. A new entry is a public-surface decision and needs a row in `docs/surface.json`.
|
|
101
44
|
|
|
102
45
|
## 4. Generated-artifact review
|
|
103
46
|
|
|
104
|
-
env-cap
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
-
|
|
109
|
-
|
|
110
|
-
description is not a substitute for looking at what changed in them.
|
|
111
|
-
- Confirm the artifact was regenerated by the tool, not hand-edited — files
|
|
112
|
-
marked `AUTO-GENERATED FILE. DO NOT EDIT.` must only change via their
|
|
113
|
-
generator.
|
|
114
|
-
- If an example's `expected/` tree changed, the source `env.schema.ts` /
|
|
115
|
-
`documentEnv()` change that caused it must be in the same PR and must
|
|
116
|
-
explain the delta.
|
|
117
|
-
- If `schemas/*.json` changed without a corresponding types change, that's
|
|
118
|
-
a red flag — the schema is generated from the types.
|
|
47
|
+
env-cap commits its own generated files: `schemas/*.json`, `docs/api-report/`, the flagship examples' `docs/` and manifests, and the integration fixtures' `expected/` trees. When one appears in a diff:
|
|
48
|
+
|
|
49
|
+
- **Read it as output.** A schema or golden diff is the observable behaviour change. "Regenerated goldens" in a description does not replace reading them.
|
|
50
|
+
- Confirm a generator wrote it. A file marked as generated changes only through its generator.
|
|
51
|
+
- If an example's generated `docs/` changed, the schema or `documentEnv()` change that caused it must be in the same pull request.
|
|
52
|
+
- If `schemas/*.json` changed without a matching type change, that is a red flag.
|
|
119
53
|
|
|
120
54
|
## 5. Security and capability-boundary review
|
|
121
55
|
|
|
122
|
-
- The static-analysis
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
- the `AmbientCapabilities` check enforces that runtime/helpers acquire no ambient
|
|
128
|
-
filesystem capability; `src/build` receives its filesystem explicitly
|
|
129
|
-
from the CLI ([ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
|
|
130
|
-
A change that reaches for `node:fs` directly inside a library surface
|
|
131
|
-
breaks this — reject it.
|
|
132
|
-
- Dependency scanning stays within the bounds described in
|
|
133
|
-
[`SECURITY.md`](SECURITY.md) — no unbounded traversal of `node_modules`.
|
|
134
|
-
- Validation `context` is a participation filter, **not** a security or
|
|
135
|
-
bundling boundary ([ADR 0022](specs/decisions/0022-validation-contexts.md),
|
|
136
|
-
[ADR 0004](specs/decisions/0004-no-client-server-package-split.md)). Reject
|
|
137
|
-
any change or doc that implies otherwise.
|
|
138
|
-
- New dependency (runtime _or_ dev): scrutinize. The runtime tier allows
|
|
139
|
-
zero; a dev dependency needs a real justification in the PR.
|
|
56
|
+
- The static-analysis rule (§2) is a security boundary. env-cap runs on untrusted repository content: schema files, `tsconfig.json`, package metadata. Anything that could run that content, or read outside the declared roots, is a vulnerability.
|
|
57
|
+
- The `AmbientCapabilities` check allows `fs` only in the CLI, `./node` and the ESLint plugin. A library surface that reaches for `node:fs` breaks this; reject it.
|
|
58
|
+
- Dependency scanning stays within the bounds in [`SECURITY.md`](SECURITY.md#build-time-security-model).
|
|
59
|
+
- A validation `context` is a participation filter, not a security or bundling boundary ([ADR 0022](specs/decisions/0022-validation-contexts.md), [ADR 0004](specs/decisions/0004-no-client-server-package-split.md)). Reject a change or a document that implies otherwise.
|
|
60
|
+
- A new dependency, runtime or dev, needs scrutiny. The runtime entries allow none; a dev dependency needs a reason in the pull request.
|
|
140
61
|
|
|
141
62
|
## 6. AI-authored change review
|
|
142
63
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
- **
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
`--flag` that looks reasonable but expands the Stable surface without a
|
|
154
|
-
decision. Cross-check `package.json#exports` and the `--help` text in the
|
|
155
|
-
diff against [`VERSIONING.md`](VERSIONING.md) §Stable and
|
|
156
|
-
[`AGENTS.md`](AGENTS.md) invariant 4.
|
|
157
|
-
- **Documentation fields in the wrong call.** `description`/`owner`/
|
|
158
|
-
`expiresAt` placed inside `createEnv()` instead of `documentEnv()` —
|
|
159
|
-
[`AGENTS.md`](AGENTS.md) invariant 3.
|
|
160
|
-
- **Framework accretion.** A manager/registry/provider wrapper around
|
|
161
|
-
`validateEnv()` — [`AGENTS.md`](AGENTS.md) "Avoid".
|
|
162
|
-
- **Tests that assert the bug.** A regenerated golden or a new test that
|
|
163
|
-
simply encodes whatever the code now does. Confirm the _expected_ value
|
|
164
|
-
is correct independently, not just internally consistent.
|
|
165
|
-
- **Mutation-score gaming.** A test added only to kill a mutant, asserting
|
|
166
|
-
nothing meaningful. The mutation gate is a floor, not the goal — a test
|
|
167
|
-
must assert real behavior.
|
|
168
|
-
|
|
169
|
-
[`AGENTS.md`](AGENTS.md), [`PROMPT.md`](PROMPT.md), and
|
|
170
|
-
[`skills/env-cap/SKILL.md`](skills/env-cap/SKILL.md) are the invariant set
|
|
171
|
-
an assistant was (or should have been) working against — a reviewer can use
|
|
172
|
-
the same list.
|
|
64
|
+
A pull request written with an AI assistant gets the same scrutiny. Its common failure modes are specific:
|
|
65
|
+
|
|
66
|
+
- **Silent invariant drift:** a fallback that executes a schema, a value embedded in an error to be "helpful", or `node:fs` in a helper. Check every new `catch`, fallback and error string against §2.
|
|
67
|
+
- **Plausible API additions:** a new export or flag that widens the Stable surface without a decision. Compare `package.json#exports` and `--help` in the diff with [`VERSIONING.md`](VERSIONING.md).
|
|
68
|
+
- **Documentation fields in the wrong call:** `description`, `owner` or `expiresAt` inside `createEnv()` instead of `documentEnv()`.
|
|
69
|
+
- **Framework accretion:** a manager, registry or provider around `validateEnv()`.
|
|
70
|
+
- **Tests that assert the bug:** a regenerated golden or a test that encodes whatever the code now does. Confirm the expected value independently.
|
|
71
|
+
- **Mutation gaming:** a test that kills a mutant but asserts nothing meaningful.
|
|
72
|
+
|
|
73
|
+
[`AGENTS.md`](AGENTS.md) and [`skills/env-cap/SKILL.md`](skills/env-cap/SKILL.md) are the rules an assistant works against; use the same list.
|
|
173
74
|
|
|
174
75
|
## 7. Required verification
|
|
175
76
|
|
|
176
|
-
- `npm run verify` green locally or in CI.
|
|
177
|
-
-
|
|
178
|
-
|
|
179
|
-
-
|
|
180
|
-
|
|
181
|
-
- `npm run
|
|
182
|
-
- The example `expected/` goldens regenerated (`npm run examples:update-golden`)
|
|
183
|
-
and reviewed if generated output changed.
|
|
184
|
-
- The committed Markdown API report regenerated (`npm run docs:api:report`)
|
|
185
|
-
and committed if any public export changed — CI's `docs:api:report:check`
|
|
186
|
-
fails otherwise. The report diff _is_ the API-surface diff; read it.
|
|
77
|
+
- `npm run verify` green, locally or in CI.
|
|
78
|
+
- Coverage floors in `vitest.config.ts` not lowered without a stated reason.
|
|
79
|
+
- Mutation: the `contract` job fails on any surviving, timed-out or uncovered mutant. New logic needs tests that assert behaviour.
|
|
80
|
+
- `npm run size` if `src/runtime`, `src/helpers` or `src/evidence` changed.
|
|
81
|
+
- Integration-fixture goldens regenerated with `npm run examples:update-golden`, and read, if generated output changed.
|
|
82
|
+
- The API report regenerated with `npm run docs:api:report` if a public export or its TSDoc changed. The `ApiDocsReport` check fails otherwise. The report diff is the API diff; read it.
|
|
187
83
|
|
|
188
84
|
## 8. Approval checklist
|
|
189
85
|
|
|
190
|
-
- [ ]
|
|
191
|
-
- [ ] Every touched invariant in §2 re-checked against the
|
|
192
|
-
- [ ] No raw
|
|
193
|
-
- [ ] Public-surface changes
|
|
194
|
-
- [ ] `package.json#exports` unchanged, or the new entry is a
|
|
195
|
-
- [ ] `--json`
|
|
196
|
-
- [ ] Generated artifacts in the diff
|
|
197
|
-
- [ ] `docs/api-report/` regenerated
|
|
86
|
+
- [ ] `contract` and `lint` green, and every other CI job green
|
|
87
|
+
- [ ] Every touched invariant in §2 re-checked against the code
|
|
88
|
+
- [ ] No raw or processed value in any error, log or fixture
|
|
89
|
+
- [ ] Public-surface changes intended, with the right changeset
|
|
90
|
+
- [ ] `package.json#exports` unchanged, or the new entry is a decision
|
|
91
|
+
- [ ] `--json` and JSON Schema changes carry the right `schemaVersion` treatment
|
|
92
|
+
- [ ] Generated artifacts in the diff read as output
|
|
93
|
+
- [ ] `docs/api-report/` regenerated if a public export changed
|
|
198
94
|
- [ ] No new runtime dependency; any new dev dependency justified
|
|
199
|
-
- [ ] Coverage not lowered;
|
|
95
|
+
- [ ] Coverage floors not lowered without a reason; no surviving mutants
|
|
200
96
|
- [ ] An ADR added if a structural boundary moved
|
package/CONTRIBUTING.md
CHANGED
|
@@ -1,32 +1,52 @@
|
|
|
1
1
|
# Contributing to env-cap
|
|
2
2
|
|
|
3
|
+
A change needs a branch, tests, a changeset and green `contract`, `lint` and `required` checks. The steps below go from clone to merge; [CODE_REVIEW.md](CODE_REVIEW.md) covers the reviewer's side.
|
|
4
|
+
|
|
3
5
|
## Development setup
|
|
4
6
|
|
|
5
7
|
```bash
|
|
6
8
|
git clone https://github.com/maverickcer/env-cap.git
|
|
7
9
|
cd env-cap
|
|
8
|
-
npm install
|
|
10
|
+
npm run setup # install, build, regenerate the schema, and install the git hooks
|
|
9
11
|
```
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
`npm run setup` installs the optional shared git hooks (`internal-package-contract install-hooks`):
|
|
14
|
+
|
|
15
|
+
| Hook | What it runs |
|
|
16
|
+
| ---------- | --------------------------------------------------------- |
|
|
17
|
+
| pre-commit | The contract checks the staged change can reach |
|
|
18
|
+
| pre-push | Most of the contract, without Coverage, Crap and Mutation |
|
|
19
|
+
| commit-msg | The Conventional Commits format check |
|
|
20
|
+
|
|
21
|
+
The hooks are a convenience and can be bypassed. CI is the gate.
|
|
22
|
+
|
|
23
|
+
## Local checks
|
|
24
|
+
|
|
25
|
+
`npm run verify` runs what CI's `verify` and `lint` jobs run, plus the schema and README-example checks:
|
|
12
26
|
|
|
13
27
|
```bash
|
|
14
|
-
npm run verify # typecheck
|
|
28
|
+
npm run verify # typecheck, lint, format, build, schema, coverage, size, ambient, isolation, API-report and README-example checks
|
|
15
29
|
```
|
|
16
30
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
31
|
+
The `contract` job runs `npm run contract` on top of it. Run single steps when you need them:
|
|
32
|
+
|
|
33
|
+
| Command | What it does |
|
|
34
|
+
| ------------------------- | -------------------------------------------------------------- |
|
|
35
|
+
| `npm run typecheck` | Type-check the repository |
|
|
36
|
+
| `npm run build` | Build `dist/` |
|
|
37
|
+
| `npm test` | Run the tests once; `npm run test:watch` keeps them running |
|
|
38
|
+
| `npm run test:coverage` | Run the tests with the coverage floors from `vitest.config.ts` |
|
|
39
|
+
| `npm run lint` | Run ESLint |
|
|
40
|
+
| `npm run size` | Check the gzip budgets in `ci/size-budgets.mjs` |
|
|
41
|
+
| `npm run docs:api` | Generate the TypeDoc site into `docs/api/` |
|
|
42
|
+
| `npm run docs:api:report` | Regenerate the Markdown API report in `docs/api-report/` |
|
|
43
|
+
| `npm run contract` | Run the whole contract; add `-- --checks A,B` for named checks |
|
|
21
44
|
|
|
22
45
|
### Working with `examples/`
|
|
23
46
|
|
|
24
|
-
Each example under [`examples/`](examples/) is its own npm project
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
change intentionally alters generated output (manifest/docs/`.env.example`/ownership-report
|
|
28
|
-
formatting, ordering, or serialization), regenerate every example's goldens and review the
|
|
29
|
-
diff before committing:
|
|
47
|
+
Each example under [`examples/`](examples/) is its own npm project; run `npm install` inside it. None of the examples keeps an `expected/` tree of env-cap output. `enterprise-platform/expected/output.json` is that example's own smoke-test fixture. Their committed `docs/`, `.env.example` and `src/generated/env.manifest.ts` are the golden output, and each example's `check` script compares them with a fresh run ([examples/README.md](examples/README.md#golden-regression-testing)).
|
|
48
|
+
|
|
49
|
+
The integration fixtures under `test/integration/` keep `expected/` directories. When your change alters generated output on purpose, regenerate everything and read the diff:
|
|
30
50
|
|
|
31
51
|
```bash
|
|
32
52
|
npm run examples:update-golden
|
|
@@ -35,97 +55,60 @@ npm run examples:update-golden
|
|
|
35
55
|
## Making a change
|
|
36
56
|
|
|
37
57
|
1. Branch from `main`.
|
|
38
|
-
2. Make your change. If it touches a
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
4. Run `npx changeset` and describe your change from the consumer's
|
|
47
|
-
perspective (not "what I changed in the code", but "what changes for
|
|
48
|
-
someone who installs this package"). Pick `patch`/`minor`/`major`
|
|
49
|
-
according to [`VERSIONING.md`](VERSIONING.md)'s stable/experimental/private
|
|
50
|
-
split — a change to something documented as Experimental is never
|
|
51
|
-
`major`, even if it's breaking, since Experimental surfaces are explicitly
|
|
52
|
-
exempted from the stability guarantee until they're promoted to stable.
|
|
53
|
-
5. Open a pull request. CI runs `npm run verify`, `npm run lint`, coverage
|
|
54
|
-
thresholds, and the Bun/Deno cross-runtime conformance suite.
|
|
58
|
+
2. Make your change. If it touches a surface in [`VERSIONING.md`](VERSIONING.md)'s Stable tier, decide whether it is breaking, additive or a fix.
|
|
59
|
+
3. Add or update tests. `npm run test:coverage` fails below the floors in `vitest.config.ts`. Floors are raised in review when coverage improves. Lowering one is a reviewed change, never a silent one.
|
|
60
|
+
4. Run `npx changeset` and describe what changes for someone who installs the package. Pick `patch`, `minor` or `major` by [`VERSIONING.md`](VERSIONING.md). If you add none, the release workflow generates one from `feat`, `fix`, `perf` and `revert` commit messages; other types release nothing.
|
|
61
|
+
5. Open a pull request. A merge needs the `contract`, `lint` and `required` checks; `contract` fails when `verify` or `lint` fails.
|
|
62
|
+
|
|
63
|
+
The `required` check also waits for `cross-runtime` (Bun and Deno), `examples`, `integration-fixtures`, `typescript-5`, `typescript-compat` and `package-managers`, so a red one blocks a merge.
|
|
64
|
+
|
|
65
|
+
A `benchmark-pr` failure skips `lint` and `verify`. `contract` and `required` still run and fail on it, so it blocks a merge too.
|
|
55
66
|
|
|
56
67
|
## Adding an Architecture Decision Record (ADR)
|
|
57
68
|
|
|
58
|
-
`specs/decisions/` records
|
|
59
|
-
just what it does today — `specs/architecture.md` is the current-state
|
|
60
|
-
summary; ADRs are the reasoning trail. Add one when a change:
|
|
69
|
+
`specs/decisions/` records why the project is shaped the way it is. `specs/architecture.md` summarizes the current state. Add an ADR when a change:
|
|
61
70
|
|
|
62
|
-
- introduces a
|
|
63
|
-
|
|
64
|
-
-
|
|
65
|
-
reintroduce without knowing it was already considered and rejected, or
|
|
66
|
-
- changes the boundary of what the runtime/build/helpers packages are
|
|
67
|
-
responsible for.
|
|
71
|
+
- introduces a constraint or promise an application could rely on, such as "warn, not throw, by default";
|
|
72
|
+
- closes off an approach a future contributor might reintroduce without knowing it was rejected; or
|
|
73
|
+
- moves the boundary of what the runtime, build or helpers entry points are responsible for.
|
|
68
74
|
|
|
69
|
-
A one-line
|
|
70
|
-
does not need one.
|
|
75
|
+
A one-line fix or an internal refactor with no observable change needs no ADR.
|
|
71
76
|
|
|
72
|
-
**Numbering
|
|
73
|
-
current highest number — gaps are possible if a numbered decision was
|
|
74
|
-
retroactively backfilled out of order; don't reuse a number even if a file
|
|
75
|
-
for it doesn't exist yet).
|
|
77
|
+
**Numbering:** run `npx internal-package-contract new` for the next unused number and the sections. Never reuse a number, even if its file is missing.
|
|
76
78
|
|
|
77
|
-
**Structure**,
|
|
78
|
-
or `0009-exclusive-groups-are-always-errors.md` for full examples):
|
|
79
|
+
**Structure**, from the existing ADRs (see `0002-static-analysis-never-execution.md` or `0009-exclusive-groups-are-always-errors.md`):
|
|
79
80
|
|
|
80
81
|
```markdown
|
|
81
|
-
# NNNN: <short
|
|
82
|
+
# NNNN: <short title that states the decision>
|
|
82
83
|
|
|
83
84
|
## Status
|
|
84
85
|
|
|
85
86
|
Accepted. Implemented in `path/to/file.ts`.
|
|
86
|
-
<!-- or: Proposed / Experimental, if the decision ships behind an explicit
|
|
87
|
-
Experimental label per VERSIONING.md -->
|
|
88
87
|
|
|
89
88
|
## Context
|
|
90
89
|
|
|
91
|
-
What problem existed, what constraints applied, and what would happen
|
|
92
|
-
|
|
93
|
-
problem.
|
|
90
|
+
What problem existed, what constraints applied, and what would happen without this decision.
|
|
91
|
+
Name specific files and functions.
|
|
94
92
|
|
|
95
93
|
## Decision
|
|
96
94
|
|
|
97
|
-
What was
|
|
98
|
-
could verify the codebase still matches it.
|
|
95
|
+
What was decided, concretely enough that a reader could check the code still matches it.
|
|
99
96
|
|
|
100
97
|
## Consequences
|
|
101
98
|
|
|
102
|
-
What this makes possible, what it
|
|
103
|
-
future contributor should know about before "fixing" what looks like a
|
|
104
|
-
limitation.
|
|
99
|
+
What this makes possible, what it rules out, and any trade-off a future contributor should know.
|
|
105
100
|
|
|
106
101
|
## Alternatives considered
|
|
107
102
|
|
|
108
|
-
Each rejected alternative, and the
|
|
109
|
-
"more complex," but what concrete problem the complexity would or wouldn't
|
|
110
|
-
have solved.
|
|
103
|
+
Each rejected alternative, and the concrete reason it was rejected.
|
|
111
104
|
```
|
|
112
105
|
|
|
113
|
-
|
|
114
|
-
it documents a structural boundary, not just a narrower implementation
|
|
115
|
-
choice.
|
|
106
|
+
Add the new ADR to `specs/architecture.md`'s decision table if it records a structural boundary.
|
|
116
107
|
|
|
117
108
|
## Release process (maintainers)
|
|
118
109
|
|
|
119
|
-
Releases
|
|
120
|
-
whole process — the normal flow, first-time trusted-publisher setup, and
|
|
121
|
-
how to recover a failed or wrong publish — lives in
|
|
122
|
-
[`RELEASING.md`](RELEASING.md). Contributors don't run any of it; a change
|
|
123
|
-
ships by merging a PR that carries a changeset.
|
|
110
|
+
Releases use Changesets and npm OIDC trusted publishing. They are automated after a person merges the release pull request. [`RELEASING.md`](RELEASING.md) covers the normal flow, first-time setup and recovery. Contributors run none of it. A change ships when its pull request merges and the next release pull request merges after it.
|
|
124
111
|
|
|
125
112
|
## Versioning and stability
|
|
126
113
|
|
|
127
|
-
|
|
128
|
-
versioning, what's Experimental, and what's a private implementation detail
|
|
129
|
-
that can change without notice. When in doubt about whether your change is
|
|
130
|
-
breaking, ask in the pull request rather than guessing at the changeset bump
|
|
131
|
-
type — an incorrect bump type is harder to fix after release than before.
|
|
114
|
+
[`VERSIONING.md`](VERSIONING.md) lists what semver covers, tier by tier. If you are unsure whether a change is breaking, ask in the pull request. A wrong bump type is harder to fix after a release than before.
|