@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.
- package/ADOPTION.md +144 -0
- package/AGENTS.md +146 -0
- package/CHANGELOG.md +449 -0
- package/CODE_OF_CONDUCT.md +124 -0
- package/CODE_REVIEW.md +200 -0
- package/CONTRIBUTING.md +131 -0
- package/GUIDE.md +1214 -0
- package/PROMPT.md +89 -0
- package/README.md +92 -200
- package/RELEASING.md +160 -0
- package/SECURITY.md +270 -0
- package/SUPPORT.md +76 -0
- package/VERSIONING.md +118 -0
- package/benchmarks/READING-BENCHMARKS.md +197 -0
- package/benchmarks/README.md +126 -0
- package/benchmarks/WRITING-BENCHMARKS.md +252 -0
- package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
- package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
- package/dist/.dts/_ipc/build-fs.d.ts +53 -0
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts/_ipc/display-path.d.ts +27 -0
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts/_ipc/glob.d.ts +22 -0
- package/dist/.dts/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts +35 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts/_ipc/typescript.d.ts +20 -0
- package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts/build/compatibility.d.ts.map +1 -1
- package/dist/.dts/build/compiler-api.d.ts +3 -6
- package/dist/.dts/build/compiler-api.d.ts.map +1 -1
- package/dist/.dts/build/display-path.d.ts +3 -21
- package/dist/.dts/build/display-path.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +21 -42
- package/dist/.dts/build/generated-banner.d.ts.map +1 -1
- package/dist/.dts/build/glob.d.ts +3 -15
- package/dist/.dts/build/glob.d.ts.map +1 -1
- package/dist/.dts/build/index.d.ts +3 -3
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/merge-documentation.d.ts +35 -0
- package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/build/types.d.ts +4 -53
- package/dist/.dts/build/types.d.ts.map +1 -1
- package/dist/.dts/build/typescript.d.ts +3 -17
- package/dist/.dts/build/typescript.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
- package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/index.d.ts +1 -1
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
- package/dist/{build-H4KFV44Z.js → build-F3RQS7VE.js} +218 -63
- package/dist/build-F3RQS7VE.js.map +1 -0
- package/dist/build.cjs +257 -102
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +256 -101
- package/dist/build.js.map +1 -1
- package/dist/{chunk-7GVPOHDU.js → chunk-QKIQ3LZP.js} +2 -2
- package/dist/cli/index.js +36 -29
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +95 -54
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +94 -53
- package/dist/eslint-plugin/index.js.map +1 -1
- package/examples/README.md +95 -0
- package/package.json +53 -19
- package/skills/env-cap/SKILL.md +91 -0
- package/skills/env-cap/references/api.md +220 -0
- package/specs/architecture.md +634 -0
- package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
- package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
- package/specs/decisions/0003-no-global-env-object.md +172 -0
- package/specs/decisions/0004-no-client-server-package-split.md +116 -0
- package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
- package/specs/decisions/0006-self-redacting-contracts.md +124 -0
- package/specs/decisions/0007-processor-not-transformer.md +109 -0
- package/specs/decisions/0008-gzip-size-budget.md +173 -0
- package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
- package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
- package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
- package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
- package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
- package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
- package/specs/decisions/0015-security-backport-window.md +60 -0
- package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
- package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
- package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
- package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
- package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
- package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
- package/specs/decisions/0022-validation-contexts.md +267 -0
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
- package/specs/decisions/0024-fact-model-architecture.md +144 -0
- package/specs/decisions/0025-contract-model-json-projection.md +105 -0
- package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
- package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
- package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
- package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
- package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
- package/specs/decisions/0031-evidence-entry-point.md +85 -0
- package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
- package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
- package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
- package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
- package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
- package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
- package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
- package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
- package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
- package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
- package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
- package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
- package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
- package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
- package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
- package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
- package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
- package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
- package/specs/generated-artifacts.md +104 -0
- package/specs/migrations/README.md +30 -0
- package/specs/migrations/from-centralized-schema.md +503 -0
- package/specs/migrations/from-dotenv.md +352 -0
- package/specs/migrations/from-envalid.md +482 -0
- package/specs/migrations/from-process-env.md +398 -0
- package/specs/migrations/from-t3-env.md +416 -0
- package/specs/migrations/from-zod.md +303 -0
- package/dist/build-H4KFV44Z.js.map +0 -1
- /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
|
package/CONTRIBUTING.md
ADDED
|
@@ -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.
|