@maverickcer/env-cap 0.6.0 → 0.7.1

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 (137) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +449 -0
  4. package/CODE_OF_CONDUCT.md +124 -0
  5. package/CODE_REVIEW.md +200 -0
  6. package/CONTRIBUTING.md +131 -0
  7. package/GUIDE.md +1214 -0
  8. package/PROMPT.md +89 -0
  9. package/README.md +92 -200
  10. package/RELEASING.md +160 -0
  11. package/SECURITY.md +270 -0
  12. package/SUPPORT.md +76 -0
  13. package/VERSIONING.md +118 -0
  14. package/benchmarks/READING-BENCHMARKS.md +197 -0
  15. package/benchmarks/README.md +126 -0
  16. package/benchmarks/WRITING-BENCHMARKS.md +252 -0
  17. package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
  18. package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
  19. package/dist/.dts/_ipc/build-fs.d.ts +53 -0
  20. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
  21. package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
  22. package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
  23. package/dist/.dts/_ipc/display-path.d.ts +27 -0
  24. package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
  25. package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
  26. package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
  27. package/dist/.dts/_ipc/glob.d.ts +22 -0
  28. package/dist/.dts/_ipc/glob.d.ts.map +1 -0
  29. package/dist/.dts/_ipc/no-node-fs.d.ts +35 -0
  30. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
  31. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  32. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  33. package/dist/.dts/_ipc/typescript.d.ts +20 -0
  34. package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
  35. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  36. package/dist/.dts/build/compiler-api.d.ts +3 -6
  37. package/dist/.dts/build/compiler-api.d.ts.map +1 -1
  38. package/dist/.dts/build/display-path.d.ts +3 -21
  39. package/dist/.dts/build/display-path.d.ts.map +1 -1
  40. package/dist/.dts/build/generated-banner.d.ts +21 -42
  41. package/dist/.dts/build/generated-banner.d.ts.map +1 -1
  42. package/dist/.dts/build/glob.d.ts +3 -15
  43. package/dist/.dts/build/glob.d.ts.map +1 -1
  44. package/dist/.dts/build/index.d.ts +3 -3
  45. package/dist/.dts/build/link.d.ts.map +1 -1
  46. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  47. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  48. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
  49. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  50. package/dist/.dts/build/types.d.ts +4 -53
  51. package/dist/.dts/build/types.d.ts.map +1 -1
  52. package/dist/.dts/build/typescript.d.ts +3 -17
  53. package/dist/.dts/build/typescript.d.ts.map +1 -1
  54. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  55. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  56. package/dist/.dts/eslint-plugin/index.d.ts +1 -1
  57. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  58. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  59. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  60. package/dist/{build-H4KFV44Z.js → build-F3RQS7VE.js} +218 -63
  61. package/dist/build-F3RQS7VE.js.map +1 -0
  62. package/dist/build.cjs +257 -102
  63. package/dist/build.cjs.map +1 -1
  64. package/dist/build.js +256 -101
  65. package/dist/build.js.map +1 -1
  66. package/dist/{chunk-7GVPOHDU.js → chunk-QKIQ3LZP.js} +2 -2
  67. package/dist/cli/index.js +36 -29
  68. package/dist/cli/index.js.map +1 -1
  69. package/dist/eslint-plugin/index.cjs +95 -54
  70. package/dist/eslint-plugin/index.cjs.map +1 -1
  71. package/dist/eslint-plugin/index.js +94 -53
  72. package/dist/eslint-plugin/index.js.map +1 -1
  73. package/examples/README.md +95 -0
  74. package/package.json +53 -19
  75. package/skills/env-cap/SKILL.md +91 -0
  76. package/skills/env-cap/references/api.md +220 -0
  77. package/specs/architecture.md +634 -0
  78. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  79. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  80. package/specs/decisions/0003-no-global-env-object.md +172 -0
  81. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  82. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  83. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  84. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  85. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  86. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  87. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  88. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  89. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  90. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  91. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  92. package/specs/decisions/0015-security-backport-window.md +60 -0
  93. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  94. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  95. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  96. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  97. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  98. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  99. package/specs/decisions/0022-validation-contexts.md +267 -0
  100. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  101. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  102. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  103. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  104. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  105. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  106. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  107. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  108. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  109. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  110. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  111. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  112. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  113. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  114. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  115. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  116. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  117. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  118. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  119. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  120. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  121. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  122. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  123. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  124. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  125. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  126. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  127. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  128. package/specs/generated-artifacts.md +104 -0
  129. package/specs/migrations/README.md +30 -0
  130. package/specs/migrations/from-centralized-schema.md +503 -0
  131. package/specs/migrations/from-dotenv.md +352 -0
  132. package/specs/migrations/from-envalid.md +482 -0
  133. package/specs/migrations/from-process-env.md +398 -0
  134. package/specs/migrations/from-t3-env.md +416 -0
  135. package/specs/migrations/from-zod.md +303 -0
  136. package/dist/build-H4KFV44Z.js.map +0 -1
  137. /package/dist/{chunk-7GVPOHDU.js.map → chunk-QKIQ3LZP.js.map} +0 -0
package/CODE_REVIEW.md ADDED
@@ -0,0 +1,200 @@
1
+ # Reviewing changes to env-cap
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.
8
+
9
+ ## 1. Review standard
10
+
11
+ A change is ready to merge when all of the following hold:
12
+
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).
24
+
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."
28
+
29
+ ## 2. Package invariants
30
+
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.
101
+
102
+ ## 4. Generated-artifact review
103
+
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.
119
+
120
+ ## 5. Security and capability-boundary review
121
+
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.
140
+
141
+ ## 6. AI-authored change review
142
+
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.
173
+
174
+ ## 7. Required verification
175
+
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.
187
+
188
+ ## 8. Approval checklist
189
+
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
198
+ - [ ] No new runtime dependency; any new dev dependency justified
199
+ - [ ] Coverage not lowered; mutation score not regressed
200
+ - [ ] An ADR added if a structural boundary moved
@@ -0,0 +1,131 @@
1
+ # Contributing to env-cap
2
+
3
+ ## Development setup
4
+
5
+ ```bash
6
+ git clone https://github.com/maverickcer/env-cap.git
7
+ cd env-cap
8
+ npm install
9
+ ```
10
+
11
+ There is one local pre-flight gate that mirrors CI exactly:
12
+
13
+ ```bash
14
+ npm run verify # typecheck && build && test && size
15
+ ```
16
+
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/`).
21
+
22
+ ### Working with `examples/`
23
+
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:
30
+
31
+ ```bash
32
+ npm run examples:update-golden
33
+ ```
34
+
35
+ ## Making a change
36
+
37
+ 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.
55
+
56
+ ## Adding an Architecture Decision Record (ADR)
57
+
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:
61
+
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.
68
+
69
+ A one-line bug fix or an internal refactor with no observable behavior change
70
+ does not need one.
71
+
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).
76
+
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
+
80
+ ```markdown
81
+ # NNNN: <short, decision-stated-as-a-sentence title>
82
+
83
+ ## Status
84
+
85
+ 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
+
89
+ ## Context
90
+
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.
94
+
95
+ ## Decision
96
+
97
+ What was actually decided, stated concretely enough that a future reader
98
+ could verify the codebase still matches it.
99
+
100
+ ## Consequences
101
+
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.
105
+
106
+ ## Alternatives considered
107
+
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.
111
+ ```
112
+
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.
116
+
117
+ ## Release process (maintainers)
118
+
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.
124
+
125
+ ## Versioning and stability
126
+
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.