@maverickcer/env-cap 0.7.4 → 0.7.5

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.
Files changed (235) hide show
  1. package/ADOPTION.md +106 -124
  2. package/AGENTS.md +14 -13
  3. package/CHANGELOG.md +15 -0
  4. package/CODE_REVIEW.md +69 -173
  5. package/CONTRIBUTING.md +57 -74
  6. package/GUIDE.md +393 -872
  7. package/README.md +81 -76
  8. package/RELEASING.md +17 -15
  9. package/SECURITY.md +76 -227
  10. package/SUPPORT.md +21 -45
  11. package/VERSIONING.md +68 -105
  12. package/benchmarks/READING-BENCHMARKS.md +13 -7
  13. package/benchmarks/WRITING-BENCHMARKS.md +1 -1
  14. package/dist/.dts/_ipc/build-fs.d.ts +9 -14
  15. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  16. package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
  17. package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
  19. package/dist/.dts/_ipc/glob.d.ts +6 -6
  20. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
  21. package/dist/.dts/build/lifecycle-model.d.ts +8 -3
  22. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  23. package/dist/.dts/build/sarif.d.ts.map +1 -1
  24. package/dist/.dts/helpers/index.d.ts +1 -1
  25. package/dist/.dts/runtime/create.d.ts +3 -0
  26. package/dist/.dts/runtime/create.d.ts.map +1 -1
  27. package/dist/.dts/runtime/document.d.ts +7 -4
  28. package/dist/.dts/runtime/document.d.ts.map +1 -1
  29. package/dist/.dts/runtime/index.d.ts +11 -10
  30. package/dist/.dts/runtime/index.d.ts.map +1 -1
  31. package/dist/.dts/runtime/types.d.ts +16 -0
  32. package/dist/.dts/runtime/types.d.ts.map +1 -1
  33. package/dist/.dts/runtime/validate.d.ts +14 -1
  34. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  35. package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
  36. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
  37. package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
  38. package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
  39. package/dist/.dts7/_ipc/display-path.d.ts +27 -0
  40. package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
  41. package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
  42. package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
  43. package/dist/.dts7/_ipc/glob.d.ts +22 -0
  44. package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
  45. package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
  46. package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
  47. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  48. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  49. package/dist/.dts7/_ipc/typescript.d.ts +20 -0
  50. package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
  51. package/dist/.dts7/build/assemble-project.d.ts +47 -0
  52. package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
  53. package/dist/.dts7/build/change-model.d.ts +63 -0
  54. package/dist/.dts7/build/change-model.d.ts.map +1 -0
  55. package/dist/.dts7/build/check-artifacts.d.ts +48 -0
  56. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
  57. package/dist/.dts7/build/citation-verification.d.ts +62 -0
  58. package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
  59. package/dist/.dts7/build/compatibility.d.ts +83 -0
  60. package/dist/.dts7/build/compatibility.d.ts.map +1 -0
  61. package/dist/.dts7/build/compiler-api.d.ts +12 -0
  62. package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
  63. package/dist/.dts7/build/contract-model.d.ts +93 -0
  64. package/dist/.dts7/build/contract-model.d.ts.map +1 -0
  65. package/dist/.dts7/build/deep-equal.d.ts +9 -0
  66. package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
  67. package/dist/.dts7/build/deep-freeze.d.ts +20 -0
  68. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
  69. package/dist/.dts7/build/dependency-graph.d.ts +170 -0
  70. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
  71. package/dist/.dts7/build/dependency-model.d.ts +81 -0
  72. package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
  73. package/dist/.dts7/build/discover.d.ts +41 -0
  74. package/dist/.dts7/build/discover.d.ts.map +1 -0
  75. package/dist/.dts7/build/display-path.d.ts +6 -0
  76. package/dist/.dts7/build/display-path.d.ts.map +1 -0
  77. package/dist/.dts7/build/docs.d.ts +176 -0
  78. package/dist/.dts7/build/docs.d.ts.map +1 -0
  79. package/dist/.dts7/build/env-example.d.ts +85 -0
  80. package/dist/.dts7/build/env-example.d.ts.map +1 -0
  81. package/dist/.dts7/build/errors.d.ts +78 -0
  82. package/dist/.dts7/build/errors.d.ts.map +1 -0
  83. package/dist/.dts7/build/evidence-cache.d.ts +74 -0
  84. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
  85. package/dist/.dts7/build/evidence-model.d.ts +50 -0
  86. package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
  87. package/dist/.dts7/build/evidence-reference.d.ts +67 -0
  88. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
  89. package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
  90. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
  91. package/dist/.dts7/build/exclusive-group.d.ts +19 -0
  92. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
  93. package/dist/.dts7/build/finding-model.d.ts +80 -0
  94. package/dist/.dts7/build/finding-model.d.ts.map +1 -0
  95. package/dist/.dts7/build/generate-documentation.d.ts +176 -0
  96. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
  97. package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
  98. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
  99. package/dist/.dts7/build/generate-evidence.d.ts +77 -0
  100. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
  101. package/dist/.dts7/build/generate-manifest.d.ts +101 -0
  102. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
  103. package/dist/.dts7/build/generate-usage.d.ts +95 -0
  104. package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
  105. package/dist/.dts7/build/generated-banner.d.ts +43 -0
  106. package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
  107. package/dist/.dts7/build/glob.d.ts +6 -0
  108. package/dist/.dts7/build/glob.d.ts.map +1 -0
  109. package/dist/.dts7/build/governance-fields.d.ts +34 -0
  110. package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
  111. package/dist/.dts7/build/humanize-key.d.ts +14 -0
  112. package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
  113. package/dist/.dts7/build/index.d.ts +105 -0
  114. package/dist/.dts7/build/index.d.ts.map +1 -0
  115. package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
  116. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
  117. package/dist/.dts7/build/link.d.ts +223 -0
  118. package/dist/.dts7/build/link.d.ts.map +1 -0
  119. package/dist/.dts7/build/literal-eval.d.ts +24 -0
  120. package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
  121. package/dist/.dts7/build/live-expirations.d.ts +47 -0
  122. package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
  123. package/dist/.dts7/build/manifest.d.ts +31 -0
  124. package/dist/.dts7/build/manifest.d.ts.map +1 -0
  125. package/dist/.dts7/build/map-utils.d.ts +8 -0
  126. package/dist/.dts7/build/map-utils.d.ts.map +1 -0
  127. package/dist/.dts7/build/merge-documentation.d.ts +35 -0
  128. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
  129. package/dist/.dts7/build/ownership-model.d.ts +59 -0
  130. package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
  131. package/dist/.dts7/build/parse.d.ts +207 -0
  132. package/dist/.dts7/build/parse.d.ts.map +1 -0
  133. package/dist/.dts7/build/reference-projections.d.ts +170 -0
  134. package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
  135. package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
  136. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
  137. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
  138. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
  139. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
  140. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
  141. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
  142. package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
  143. package/dist/.dts7/build/sarif.d.ts +66 -0
  144. package/dist/.dts7/build/sarif.d.ts.map +1 -0
  145. package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
  146. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
  147. package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
  148. package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
  149. package/dist/.dts7/build/source-position.d.ts +69 -0
  150. package/dist/.dts7/build/source-position.d.ts.map +1 -0
  151. package/dist/.dts7/build/tool-version.d.ts +8 -0
  152. package/dist/.dts7/build/tool-version.d.ts.map +1 -0
  153. package/dist/.dts7/build/types.d.ts +7 -0
  154. package/dist/.dts7/build/types.d.ts.map +1 -0
  155. package/dist/.dts7/build/typescript.d.ts +6 -0
  156. package/dist/.dts7/build/typescript.d.ts.map +1 -0
  157. package/dist/.dts7/build/usage-report.d.ts +124 -0
  158. package/dist/.dts7/build/usage-report.d.ts.map +1 -0
  159. package/dist/.dts7/cli/filesystem.d.ts +7 -0
  160. package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
  161. package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
  162. package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
  163. package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
  164. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
  165. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
  166. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
  167. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
  168. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
  169. package/dist/.dts7/evidence/define-projection.d.ts +52 -0
  170. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
  171. package/dist/.dts7/evidence/index.d.ts +23 -0
  172. package/dist/.dts7/evidence/index.d.ts.map +1 -0
  173. package/dist/.dts7/helpers/index.d.ts +135 -0
  174. package/dist/.dts7/helpers/index.d.ts.map +1 -0
  175. package/dist/.dts7/helpers/processors.d.ts +32 -0
  176. package/dist/.dts7/helpers/processors.d.ts.map +1 -0
  177. package/dist/.dts7/helpers/validators.d.ts +68 -0
  178. package/dist/.dts7/helpers/validators.d.ts.map +1 -0
  179. package/dist/.dts7/node/index.d.ts +2 -0
  180. package/dist/.dts7/node/index.d.ts.map +1 -0
  181. package/dist/.dts7/runtime/cache.d.ts +17 -0
  182. package/dist/.dts7/runtime/cache.d.ts.map +1 -0
  183. package/dist/.dts7/runtime/create.d.ts +23 -0
  184. package/dist/.dts7/runtime/create.d.ts.map +1 -0
  185. package/dist/.dts7/runtime/document.d.ts +223 -0
  186. package/dist/.dts7/runtime/document.d.ts.map +1 -0
  187. package/dist/.dts7/runtime/errors.d.ts +55 -0
  188. package/dist/.dts7/runtime/errors.d.ts.map +1 -0
  189. package/dist/.dts7/runtime/index.d.ts +25 -0
  190. package/dist/.dts7/runtime/index.d.ts.map +1 -0
  191. package/dist/.dts7/runtime/registry.d.ts +12 -0
  192. package/dist/.dts7/runtime/registry.d.ts.map +1 -0
  193. package/dist/.dts7/runtime/reset.d.ts +8 -0
  194. package/dist/.dts7/runtime/reset.d.ts.map +1 -0
  195. package/dist/.dts7/runtime/types.d.ts +191 -0
  196. package/dist/.dts7/runtime/types.d.ts.map +1 -0
  197. package/dist/.dts7/runtime/validate.d.ts +27 -0
  198. package/dist/.dts7/runtime/validate.d.ts.map +1 -0
  199. package/dist/{build-6XFHJFQK.js → build-DNAYWD2B.js} +8 -5
  200. package/dist/build-DNAYWD2B.js.map +1 -0
  201. package/dist/build.cjs +7 -4
  202. package/dist/build.cjs.map +1 -1
  203. package/dist/build.js +7 -4
  204. package/dist/build.js.map +1 -1
  205. package/dist/build.ts7.d.cts +1 -0
  206. package/dist/build.ts7.d.ts +1 -0
  207. package/dist/{chunk-RL5KFVUT.js → chunk-HAGMVMN5.js} +2 -2
  208. package/dist/cli/index.js +3 -3
  209. package/dist/eslint-plugin/index.cjs.map +1 -1
  210. package/dist/eslint-plugin/index.js.map +1 -1
  211. package/dist/eslint-plugin/index.ts7.d.cts +1 -0
  212. package/dist/eslint-plugin/index.ts7.d.ts +1 -0
  213. package/dist/evidence.ts7.d.cts +1 -0
  214. package/dist/evidence.ts7.d.ts +1 -0
  215. package/dist/helpers.ts7.d.cts +1 -0
  216. package/dist/helpers.ts7.d.ts +1 -0
  217. package/dist/index.cjs.map +1 -1
  218. package/dist/index.js.map +1 -1
  219. package/dist/index.ts7.d.cts +1 -0
  220. package/dist/index.ts7.d.ts +1 -0
  221. package/dist/node.ts7.d.cts +1 -0
  222. package/dist/node.ts7.d.ts +1 -0
  223. package/examples/README.md +46 -80
  224. package/package.json +27 -4
  225. package/schemas/env-cap-report.schema.json +1 -1
  226. package/skills/env-cap/SKILL.md +1 -1
  227. package/skills/env-cap/references/api.md +1 -1
  228. package/specs/architecture.md +2 -2
  229. package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
  230. package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
  231. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
  232. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
  233. package/specs/generated-artifacts.md +14 -2
  234. package/dist/build-6XFHJFQK.js.map +0 -1
  235. /package/dist/{chunk-RL5KFVUT.js.map → chunk-HAGMVMN5.js.map} +0 -0
package/CODE_REVIEW.md CHANGED
@@ -1,200 +1,96 @@
1
1
  # Reviewing changes to env-cap
2
2
 
3
- The reviewer-side companion to [`CONTRIBUTING.md`](CONTRIBUTING.md). It
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 the following hold:
7
+ A change is ready to merge when all of these hold:
12
8
 
13
- - CI is green — `npm run verify` (typecheck, lint, format, build, schema
14
- generation, coverage thresholds, `npm run size`, the `AmbientCapabilities` check,
15
- the API-report drift check) plus the Bun/Deno cross-runtime conformance
16
- suite.
17
- - Every invariant in §2 that the change touches is still true, and the
18
- reviewer has checked the specific code, not just trusted the description.
19
- - Any public-surface change (§3) is intentional, justified in the PR, and
20
- carries the right changeset bump type.
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` and `lint` checks are green; the branch ruleset requires both.
10
+ - Every other CI job is green too. They are the Bun and Deno suite, the examples, the integration fixtures, `typescript-5`, `typescript-compat` and the package-manager smoke test.
11
+ - The `required` check waits for those jobs, but the ruleset does not yet require `required`, so a reviewer must look.
12
+ - `benchmark-pr` is green. A failure there skips `lint`, `verify` and `contract`, which GitHub then counts as passing; check it by hand.
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 can't meet this bar in one PR, split it — a partial 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 enumerated in [`AGENTS.md`](AGENTS.md) ("Non-negotiable
32
- invariants") and pinned by ADRs. A reviewer's job is to confirm the change
33
- doesn't erode one, even indirectly:
34
-
35
- - **Static analysis only — schemas are never executed**
36
- ([ADR 0002](specs/decisions/0002-static-analysis-never-execution.md)).
37
- `src/build` parses `env.schema.ts` as TypeScript AST. Reject any change
38
- that adds `import()`, `require()`, `eval`, `new Function`, `vm`, a
39
- worker, or a subprocess to the analysis path. A value that can't be
40
- resolved from a literal must surface as a `Finding`/warning, never a
41
- guess or a fallback execution.
42
- - **Runtime stays isomorphic, zero-dependency, and within budget**
43
- ([ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md),
44
- [ADR 0008](specs/decisions/0008-gzip-size-budget.md)). `src/runtime` and
45
- `src/helpers` must not import `node:*`, must not add a dependency, and
46
- must stay under the `npm run size` gzip budget. `src/build` is the only
47
- place `node:fs`/`node:path`/`typescript` may appear, and it must never be
48
- reachable from a runtime entry point.
49
- - **Warn, don't throw, by default**
50
- ([ADR 0005](specs/decisions/0005-warn-not-throw-by-default.md)). New
51
- data-quality findings are warnings. Escalation to an error happens only
52
- behind an explicit `--strict*` flag / `on*: "throw"` option, and when it
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 both produces generated artifacts and commits its own
105
- (`schemas/*.json`, example `expected/` golden trees, `docs/api-report/`).
106
- When any of these appear in a diff:
107
-
108
- - **Review the artifact as output.** A golden or schema diff is the
109
- observable behavior change — read it. "Regenerated goldens" in a PR
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 guarantee (§2, ADR 0002) is a security boundary:
123
- env-cap runs against untrusted repo content (schema files, `tsconfig`,
124
- installed package metadata). Anything that could execute that content, or
125
- read/traverse outside the declared discovery roots, is a vulnerability,
126
- not a bug.
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
- Treat a PR written with an AI assistant as needing the _same_ scrutiny as
144
- any other — but the common failure modes are specific and checkable
145
- against documented invariants:
146
-
147
- - **Silent invariant drift.** An assistant "helpfully" adds a fallback that
148
- executes a schema when static resolution fails (violates ADR 0002), or
149
- embeds the offending value in an error message to be "more helpful"
150
- (violates ADR 0006), or reaches for `node:fs` in a helper. Check every
151
- new `catch`, fallback, and error-message string against §2.
152
- - **Plausible-looking API additions.** A new exported symbol or a new
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), [`PROMPT.md`](PROMPT.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
- - `npm run test:coverage` — coverage is ratchet-up-only; a threshold is
178
- raised when coverage improves, never lowered to accommodate a drop.
179
- - Mutation score (Stryker) must not regress. New logic needs tests that
180
- actually kill mutants by asserting behavior.
181
- - `npm run size` if `src/runtime` or `src/helpers` changed.
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
- - [ ] CI green (`verify` + cross-runtime conformance)
191
- - [ ] Every touched invariant in §2 re-checked against the actual code
192
- - [ ] No raw/processed env value in any error, log, or fixture
193
- - [ ] Public-surface changes are intentional + correct changeset bump
194
- - [ ] `package.json#exports` unchanged, or the new entry is a deliberate decision
195
- - [ ] `--json` / JSON Schema changes carry the right `schemaVersion` treatment
196
- - [ ] Generated artifacts in the diff reviewed as output, not skimmed
197
- - [ ] `docs/api-report/` regenerated + committed if any public export changed
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; mutation score not regressed
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` and `lint` 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
- There is one local pre-flight gate that mirrors CI exactly:
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 && build && test && size
28
+ npm run verify # typecheck, lint, format, build, schema, coverage, size, ambient, isolation, API-report and README-example checks
15
29
  ```
16
30
 
17
- Run it before opening a pull request. Individual steps are also available on
18
- their own: `npm run typecheck`, `npm run build`, `npm test` / `npm run
19
- test:watch`, `npm run test:coverage`, `npm run lint`, `npm run size`,
20
- `npm run docs:api` (generates the TypeDoc API reference into `api-docs/`).
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 (`npm install` inside it
25
- separately) and carries a committed `expected/` directory of golden regression fixtures --
26
- see [`examples/README.md`](examples/README.md#golden-regression-testing). If your
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 documented, user-facing behavior
39
- (anything covered by [`VERSIONING.md`](VERSIONING.md)'s "stable" tier),
40
- check whether it's breaking, additive, or a fix — this determines the
41
- changeset bump type in step 4.
42
- 3. Add or update tests. `npm run test:coverage` must not drop coverage below
43
- the thresholds in `vitest.config.ts` — the policy is ratchet-up-only:
44
- thresholds are raised when coverage improves, never lowered to
45
- accommodate a drop.
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` and `lint` checks; `contract` fails when `verify` or `lint` fails.
62
+
63
+ CI also runs the Bun and Deno suite, the examples, the integration fixtures, `typescript-5`, `typescript-compat` and the package-manager smoke test. The `required` check waits for all of them. The branch ruleset does not yet require `required`, so those jobs do not yet block a merge. Treat a red one as blocking anyway.
64
+
65
+ `benchmark-pr` needs the same care. A failure there skips `lint`, `verify` and `contract`, which GitHub then counts as passing; check it by hand.
55
66
 
56
67
  ## Adding an Architecture Decision Record (ADR)
57
68
 
58
- `specs/decisions/` records _why_ the project is shaped the way it is, not
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 new constraint or guarantee an application could come to rely
63
- on (e.g. "warn, not throw, by default"),
64
- - closes off an alternative approach a future contributor might otherwise
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 guarantee 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 bug fix or an internal refactor with no observable behavior change
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**: take the next unused integer (check `specs/decisions/` for the
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**, drawn from the existing ADRs (see `0002-static-analysis-never-execution.md`
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, decision-stated-as-a-sentence title>
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 absent
92
- this decision. Reference specific files/functions, not just the abstract
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 actually decided, stated concretely enough that a future reader
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 forecloses, and any non-obvious tradeoff a
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 specific reason it was rejected — not just
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
- Cross-reference the new ADR from `specs/architecture.md`'s decision table if
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 are fully automated (Changesets + npm OIDC trusted publishing). The
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
- See [`VERSIONING.md`](VERSIONING.md) for what's covered by semantic
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.