@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
@@ -0,0 +1,206 @@
1
+ # 0014: Cross-Package Schema Discovery via an Explicit Package Allowlist
2
+
3
+ ## Status
4
+
5
+ Proposed / **Experimental** (see [`VERSIONING.md`](../../VERSIONING.md)).
6
+ Implemented in:
7
+
8
+ - `src/build/resolve-package-schema.ts`
9
+ - `src/build/resolve-import.ts` (`resolveImportSpecifier`)
10
+ - `src/build/link.ts` (`DiscoveredContract.packageOrigin`)
11
+ - `src/build/dependency-graph.ts`
12
+ - `src/build/manifest.ts`
13
+
14
+ The `packages` option, the `PackageOrigin` type it attaches to discovered
15
+ contracts, and the `"envCap": { "schema": "<path>" }` package.json convention
16
+ are all Experimental: they may still change shape in a minor release without
17
+ that being a semver violation. This is genuinely first-of-its-kind surface
18
+ for the project -- a new cross-trust-boundary resolution mechanism with real
19
+ edge cases (upward `package.json` walks, symlink/realpath handling,
20
+ package-manager-specific layouts) that benefits from real-world feedback
21
+ before being locked to the same strict stability guarantee the rest of the
22
+ public build API carries. This does **not** license casual churn: a
23
+ publishing package that adopts the convention starts building real
24
+ automation around it from day one, so the Experimental label buys room to
25
+ refine based on genuine feedback, not permission to change it for its own
26
+ sake.
27
+
28
+ ## Context
29
+
30
+ `generateEnvManifest()`/`generateEnvArtifacts()` could not, until this
31
+ decision, see a schema that exists only inside an installed package's
32
+ `node_modules` copy. Two independent boundaries blocked it:
33
+
34
+ 1. `discoverSchemaFiles()` (`discover.ts`) unconditionally prunes
35
+ `node_modules` during its directory walk -- `ALWAYS_SKIP_DIR_NAMES`,
36
+ applied regardless of `include`/`exclude`.
37
+ 2. `resolveRelativeImport()` (`resolve-import.ts`) unconditionally returns
38
+ `undefined` for bare/package specifiers -- only `./`- and `../`-prefixed
39
+ specifiers ever resolve.
40
+
41
+ `test/integration/positive/enterprise/paypal-consumer`'s README documented this honestly as "a real
42
+ discovery boundary, not glossed over," worked around only by pointing `root`
43
+ at a shared parent directory of monorepo-sibling source folders -- a
44
+ technique that provides no help for a genuinely separately-published npm
45
+ package with no sibling source visible outside its own `node_modules` copy.
46
+
47
+ A large organization with many internal, separately-published packages
48
+ (`@acme/payments-sdk`, `@acme/auth-sdk`, ...) -- no monorepo, no shared
49
+ source tree -- had no way to consolidate env-var contracts across package
50
+ boundaries at all. The threat model for extending discovery across a package
51
+ boundary is different from local discovery: a package crosses a real trust
52
+ and versioning boundary (a transitive artifact someone else publishes and
53
+ updates independently), even though ADR 0002's "never execute" invariant is
54
+ not weakened by anything in this decision -- only _which files get fed into_
55
+ the existing AST-only pipeline changes.
56
+
57
+ ## Decision
58
+
59
+ 1. **A publishing package opts itself in** by declaring a dedicated
60
+ `"envCap": { "schema": "<path>" }` field in its own `package.json`,
61
+ pointing at its own real, uncompiled `.ts`/`.tsx` schema source file --
62
+ not a compiled or bundled entry point. Compiled/bundled output risks
63
+ identifier renaming (bundlers rename local variables to avoid
64
+ collisions), CJS/ESM shape mismatches (`parse.ts` only recognizes ESM
65
+ `import`/`export const` syntax), and minification (which renames every
66
+ local identifier by design) -- any of which would silently break
67
+ `isCallToName`'s `createEnv`/`documentEnv` identifier matching. The
68
+ package ships that one file via a narrow `files` addition (e.g.
69
+ `"files": ["dist", "src/env.schema.ts"]`), not its whole `src/` tree. This
70
+ field's value is part of the package's public contract, not an internal
71
+ implementation detail -- once any consumer's build depends on discovering
72
+ it, moving or renaming the declared file is effectively a breaking change
73
+ for that package, the same as moving a file referenced by `exports`
74
+ would be, independent of whether `env-cap` itself treats the surface as
75
+ Experimental.
76
+
77
+ 2. **A consuming project opts itself in** by passing an explicit
78
+ `packages: readonly string[]` allowlist to `generateEnvManifest`/
79
+ `generateDocumentation`/`generateUsageReport`/`generateEnvArtifacts`
80
+ (and the CLI's repeatable `--package <name>` flag). No package is ever
81
+ considered unless named exactly in this array. There is no auto-scan of
82
+ installed dependencies for the `envCap` field.
83
+
84
+ 3. **Resolution never walks `node_modules`.** An allow-listed name resolves
85
+ entirely through Node's own package-resolution machinery
86
+ (`createRequire(...).resolve(...)`), bounded to a handful of `fs` calls
87
+ per package regardless of `node_modules` size, and correct across
88
+ npm/pnpm/yarn installs uniformly since none are special-cased. When a
89
+ package's `exports` map omits `"./package.json"`, resolution falls back
90
+ to locating the main entry and walking upward through ancestor
91
+ directories -- but that walk cannot stop at the _nearest_ `package.json`,
92
+ since dual CJS/ESM packages commonly ship decoy marker files (e.g.
93
+ `dist/cjs/package.json` containing only `{"type":"commonjs"}`, no `name`
94
+ field) at intermediate directory levels. The walk continues until a
95
+ `package.json`'s own `name` field actually matches the target package.
96
+
97
+ 4. **The resolved file must pass layered validation before it is ever
98
+ parsed**: a lexical boundary check on the declared path string (it must
99
+ not escape the package directory), a `.ts`/`.tsx` extension check, a
100
+ **realpath-based containment check** (resolving both the target file and
101
+ the package directory via `fs.realpath` and verifying the real target is
102
+ still contained within the real package root -- necessary because
103
+ `packageDir` itself is frequently a symlink under real-world installs,
104
+ e.g. pnpm's content-addressable store, so a purely lexical check on
105
+ either side of the comparison can be wrong), and a fixed size cap
106
+ (`MAX_PACKAGE_SCHEMA_FILE_BYTES`, 1 MiB) checked via `fs.stat` before any
107
+ content is read into memory. A symlink is not rejected on sight -- the
108
+ realpath containment check is the actual authority, so a symlink
109
+ resolving _within_ the package directory is harmless and allowed; only a
110
+ real target outside it is rejected. Any failure at any step
111
+ (`PackageResolutionFailureCode`: `PACKAGE_NOT_FOUND`,
112
+ `MALFORMED_PACKAGE_JSON`, `FIELD_MISSING`, `INVALID_EXTENSION`,
113
+ `OUTSIDE_PACKAGE`, `FILE_TOO_LARGE`) becomes exactly one `ParseWarning`
114
+ per package, never a throw, never a guess -- the package's contract is
115
+ simply absent from the result, exactly as an unresolvable local reference
116
+ already behaves today.
117
+
118
+ 5. **`resolveRelativeImport()`'s bare-specifier no-op is preserved
119
+ unmodified.** A new composed entry point, `resolveImportSpecifier()`, is
120
+ what `link.ts` and `dependency-graph.ts` actually call: it tries the
121
+ relative resolver first and falls back to package resolution only for
122
+ specifiers matching an allow-listed name. Wiring this into
123
+ `dependency-graph.ts` (not just `link.ts`) is load-bearing, not optional:
124
+ without it, a cross-package contract's consumer
125
+ (`import { x } from "@acme/pkg"`) could never resolve, and the contract
126
+ would be misreported as `abandoned` by `generateUsageReport()`.
127
+
128
+ 6. **Local and package-resolved files are merged and deduplicated by
129
+ realpath**, not lexical path, before being handed to `linkFiles()` --
130
+ package-resolved files are already realpath-canonicalized, but local
131
+ `discoverSchemaFiles()` hits may themselves traverse a symlink (a
132
+ symlinked `root`, or an included path reached through one). A lexical-
133
+ only dedup would miss the same physical file reached through two
134
+ different symlinked routes and silently double-count it into two
135
+ identical contracts.
136
+
137
+ 7. **Generated manifests import a package-resolved contract by bare package
138
+ name**, not a relative path to the (analysis-only) resolved file --
139
+ `DiscoveredContract.packageOrigin` carries this. A relative path into
140
+ `node_modules` would point at raw `.ts` source most consumer build
141
+ configs don't compile, and wouldn't be a valid runtime import path
142
+ anyway. This requires a publishing package to re-export its contract
143
+ under the _same_ export name its schema file uses, from its own main
144
+ entry point -- a violation fails loudly (a real compile/runtime error for
145
+ the consumer), so this obligation is not separately verified here.
146
+
147
+ **This decision does not weaken or amend ADR 0002 in any way.** No file
148
+ resolved through `packages` is ever imported, required, or executed -- a
149
+ package-resolved file is fed into the exact same `parseSchemaFile()`/
150
+ AST-only pipeline as a locally-discovered file, indistinguishable from it
151
+ after resolution. Package discovery only changes _which files are found_,
152
+ never _what happens to a found file_. `discoverSchemaFiles()`'s existing
153
+ `node_modules`-pruning walk is untouched by this decision; the two
154
+ mechanisms never overlap -- the general walk never calls into package
155
+ resolution, and package resolution never calls `readdir`.
156
+
157
+ ## Consequences
158
+
159
+ - A schema that exists only in an installed package's `node_modules` copy is
160
+ now discoverable, but only for packages a project's own build
161
+ configuration explicitly names -- the allowlist is authored by the same
162
+ person who already has arbitrary code execution rights over that build
163
+ configuration, so it is a convenience/scoping mechanism, not a new
164
+ privilege boundary.
165
+ - `discoverSchemaFiles()`'s existing performance guarantee (never scans
166
+ `node_modules`) is unmodified -- the two code paths structurally never
167
+ overlap.
168
+ - A package crossing this boundary takes on two concrete, documented
169
+ obligations: ship its schema source file (a narrow `files` addition, not
170
+ its whole `src/`), and re-export each contract under its schema file's
171
+ export name from its own main entry point.
172
+ - Being Experimental, the `packages` convention may still be refined (e.g.
173
+ the exact package.json field name or shape) based on real adoption
174
+ feedback before this ADR's Status is promoted to Accepted.
175
+
176
+ ## Alternatives considered
177
+
178
+ - **Auto-scan every installed dependency's `package.json` for an `envCap`
179
+ field, no allowlist.** Rejected. It would silently expand the trust
180
+ boundary to every transitive dependency that happens to declare the
181
+ field, including ones a team never audited for this purpose, and would
182
+ reintroduce exactly the "walk potentially huge `node_modules`"
183
+ performance/DoS surface `discoverSchemaFiles()`'s hardcoded skip exists to
184
+ avoid, just moved into a different function.
185
+ - **Reuse the `exports` map with a well-known subpath (e.g.
186
+ `"./env-schema"`) instead of a dedicated field.** Rejected. It would force
187
+ the declared entry point to be a real, runtime-importable module,
188
+ reopening the CJS/ESM/bundling/minification risks in Decision 1, and
189
+ risks becoming a de facto second public API with expectations `env-cap`
190
+ doesn't control. Adding an `exports` map at all is also a breaking
191
+ encapsulation change for a package that doesn't already have one.
192
+ - **Follow a package's internal re-export chain to verify the main-entry
193
+ re-export obligation.** Rejected as scope creep -- it would mean parsing a
194
+ second package-owned file per package, expanding the trust surface for a
195
+ case that already fails loudly (a real compile/runtime error) rather than
196
+ silently.
197
+ - **Accept compiled `.js` output as a valid `envCap.schema` target.**
198
+ Rejected for now, given the CJS/ESM/bundling/minification risks in
199
+ Decision 1. Revisiting this is possible in a future version if a clean
200
+ mitigation is found, but nothing in the current requirements demands it.
201
+ - **A dedicated `onPackageResolutionFailure: "warn" | "throw"` escalation
202
+ option.** Considered, not added -- no real use case has asked for a way to
203
+ hard-fail CI specifically on a package-resolution failure as distinct from
204
+ every other warning-tier finding. If one surfaces, this is the natural
205
+ future extension point, following the same "no knob nobody's asked for
206
+ yet" precedent as ADR 0009.
@@ -0,0 +1,60 @@
1
+ # 0015: Post-1.0 security fixes are backported one major version back, for a minimum of six months
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `SECURITY.md`'s "Supported versions" section.
6
+
7
+ ## Context
8
+
9
+ `SECURITY.md`'s "Supported versions" section previously said only that
10
+ security fixes target the latest published `0.x` version and that "there is
11
+ currently no separate long-term-support branch or extended security-support
12
+ policy" -- true today, but silent on what happens once the project reaches
13
+ `1.0`, when a major-version bump starts meaning something different (a real
14
+ breaking-change boundary, not `0.x`'s "any minor may break Stable APIs" per
15
+ `VERSIONING.md`). `ADOPTION.md`'s "Versioning, stability, and long-term
16
+ support" section named this directly as "the honest gap" for an organization
17
+ evaluating adoption at scale, with no forward answer -- only a description of
18
+ what's missing today.
19
+
20
+ ## Decision
21
+
22
+ Starting at the first `1.0` release, security fixes will be backported to
23
+ the latest minor release of the previous major version for a minimum of six
24
+ months after a new major version ships. That minimum window may be extended
25
+ at the maintainer's discretion, but once a minimum end date has been stated
26
+ for a given major version's backport window, it will never be shortened
27
+ retroactively. Before `1.0`, the existing "latest `0.x` only" policy
28
+ continues unchanged -- this decision does not attempt to backdate a
29
+ commitment onto pre-1.0 releases.
30
+
31
+ ## Consequences
32
+
33
+ - An organization evaluating `env-cap` for a hard LTS/backport requirement
34
+ now has a concrete, dated answer for the _post-1.0_ state, distinct from
35
+ today's real, current gap -- `ADOPTION.md` is updated to state both
36
+ halves rather than only the gap.
37
+ - This is a forward commitment, not a proven track record. `ADOPTION.md`
38
+ must continue to say so explicitly.
39
+ - A future major-version release's changelog/release notes must state the
40
+ backport window's end date explicitly, since the "never shortened once
41
+ stated" guarantee only has teeth if the stated date is written down
42
+ somewhere a consumer can point back to.
43
+
44
+ ## Alternatives considered
45
+
46
+ - **No forward commitment at all.** Rejected -- `ADOPTION.md` already
47
+ surfaces this as "the honest gap" to every evaluator; leaving it
48
+ permanently unanswered costs real adoptions for a project where the
49
+ actual future behavior is knowable and cheap to commit to now.
50
+ - **A shorter (e.g. 90-day) or open-ended/indefinite window.** Rejected.
51
+ Six months balances real migration planning time against not being an
52
+ indefinite burden for a solo-maintained project; open-ended was rejected
53
+ because an unbounded promise from a single maintainer isn't a credible
54
+ commitment.
55
+ - **A commitment that can be shortened later if maintenance burden proves
56
+ unsustainable.** Rejected -- a window a consumer can't rely on staying put
57
+ isn't meaningfully different from no commitment; "extendable, never
58
+ shortened once stated" lets the maintainer add slack without ever pulling
59
+ support out from under an application that planned around the original
60
+ date.
@@ -0,0 +1,113 @@
1
+ # 0016: `--check` computes fully before ever touching disk, and never partially writes
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/build/check-artifacts.ts` (`checkEnvArtifacts()`),
6
+ wired into the CLI via `--check` in `src/cli/index.ts`.
7
+
8
+ ## Context
9
+
10
+ `generateEnvArtifacts()` already gives two atomicity guarantees (ADR 0011):
11
+ every requested pass's blocking findings are checked, across all passes,
12
+ before any pass writes anything, but once writes begin, they are not
13
+ transactional. A CI "drift guard" -- verify that a schema change was
14
+ actually followed by regenerating the committed manifest/docs/`.env.example`/
15
+ ownership report, without writing anything, so a stale artifact fails the
16
+ build instead of silently drifting out of sync -- needs a stronger,
17
+ simpler guarantee than either of those: **nothing is ever written at all**,
18
+ regardless of what's found. A read-then-maybe-write design (compute, then
19
+ overwrite the target files, then diff old vs. new via git) was considered
20
+ and rejected: it would leave a working tree dirty after a failed CI check
21
+ (annoying for a local dry run) and, more importantly, would defeat the
22
+ entire point of a drift guard the moment anyone rebinds `--check` to also
23
+ regenerate "just to be safe."
24
+
25
+ `generateEnvArtifacts()`'s existing pipeline already separates "compute the
26
+ artifact's content" from "write it to disk" for all three generators
27
+ (`renderManifest()`, `renderDocs()`, `renderUsageReport()` are pure
28
+ functions of already-computed data). `--check` reuses that same compute
29
+ step via a new exported `computeArtifacts()` (extracted from
30
+ `generateEnvArtifacts()` in `src/build/generate-env-artifacts.ts`) and a new,
31
+ comparison-only module, `src/build/check-artifacts.ts`, rather than
32
+ special-casing "don't actually write" flags through the existing write path.
33
+
34
+ ## Decision
35
+
36
+ - **`checkEnvArtifacts()` never calls any of the four write functions**
37
+ (`writeManifest`, `writeDocumentation`/`writeEnvExample`, `writeUsageReport`).
38
+ It only reads the currently-committed target files (via `fs.readFile`,
39
+ exactly as a normal run already does for docs/env-example reconciliation)
40
+ to compare against freshly rendered content -- render-and-compare, never
41
+ render-and-overwrite.
42
+ - **Compute fully before comparing anything.** `computeArtifacts()` runs
43
+ discovery, linking, and every requested pass's pure compute step exactly
44
+ once, and throws `EnvProjectGenerationError` on the same blocking findings
45
+ a real run would throw on (an escaping output path, or a `--strict`-family
46
+ finding) -- `--check` reports drift, it does not paper over a run that
47
+ would otherwise fail outright.
48
+ - **Each artifact gets its own `ok`/`stale`/`missing` finding**, not one
49
+ aggregate boolean -- `missing` (target doesn't exist yet) and `stale`
50
+ (exists but differs from what a real run would produce) are distinguished
51
+ because they suggest different next steps for whoever reads the CI output.
52
+ - **Docs' one non-deterministic line (`_Generated <timestamp>_`) is
53
+ normalized before comparison.** Byte-for-byte equality would otherwise
54
+ report every check as stale purely because real time moved between the
55
+ last real generation and the check, which is not drift.
56
+ - **`.env.example` staleness is judged by `computeReconciliation()`'s
57
+ three-list diff, not string equality.** `writeEnvExample()` never
58
+ overwrites an existing file (a variable-count-only diff, by design), so
59
+ "stale" for this one artifact means "genuine reconciliation drift"
60
+ (missing/extra/stale variables), not "the file's bytes differ from a
61
+ hypothetical fresh render" -- a human-added comment in an otherwise
62
+ reconciled `.env.example` must not be flagged.
63
+
64
+ ## Consequences
65
+
66
+ - `--check`'s exit code (`0`/`1`) is driven entirely by its own
67
+ `CheckEnvArtifactsResult.ok`, independent of `--json`'s top-level `ok`
68
+ field (which keeps meaning "did generation complete without throwing").
69
+ `--json`'s envelope gains an additive `checkResult: { ok, stale }` field
70
+ (see ADR 0013's additive-field policy) rather than overloading the
71
+ existing `ok`.
72
+ - **`--check` requires `renderDocs()` to be a fixed point under self-feeding**:
73
+ regenerating with a file's own current content as `previousContent` must
74
+ reproduce that file byte-for-byte (modulo only the normalized
75
+ `_Generated ...` line), since that's exactly what `checkEnvArtifacts()`
76
+ does -- it always treats whatever is currently on disk as `previousContent`
77
+ for the comparison render. This was violated for a project's very first
78
+ `--check` immediately after its very first real generation: a true first
79
+ write has no `previousContent` at all, and `renderDocs()` used to omit the
80
+ "Changes since last report" section entirely in that case, while a
81
+ same-content second render (real or checked) legitimately includes it --
82
+ so the first-ever `--check` always reported `docs` as stale, for a reason
83
+ unrelated to any real schema drift. Fixed in `computeChangeSummary()`
84
+ (`src/build/docs.ts`): a missing `previousContent` is now treated as "no
85
+ changes" (the section is always rendered, "No changes." on a true first
86
+ run too) rather than "no summary at all" -- see that function's docstring
87
+ for the full reasoning. `--check` itself required no change; the fix
88
+ belongs entirely in `renderDocs()`, since the self-feeding fixed-point
89
+ property it depends on is a general correctness requirement of that
90
+ function, not something specific to `--check`'s own logic.
91
+ - `computeArtifacts()` is `Private` tier (VERSIONING.md) -- exported from
92
+ `generate-env-artifacts.ts` so `check-artifacts.ts` can import it, but not
93
+ re-exported from `./index.ts`. Only `checkEnvArtifacts()` and its result
94
+ types are public.
95
+
96
+ ## Alternatives considered
97
+
98
+ - **A `--dry-run` flag on the existing write functions**, threading a
99
+ boolean through `writeManifest()`/`writeDocumentation()`/`writeUsageReport()`
100
+ to skip the actual `fs.writeFile` call. Rejected -- it would still need a
101
+ parallel comparison step to be useful (skipping the write alone doesn't
102
+ tell you _whether_ the skipped write would have changed anything), so it
103
+ buys nothing over a dedicated compare-only module, while spreading
104
+ "don't actually write" conditionals through code whose entire job today
105
+ is writing.
106
+ - **Regenerate into a temp location and `diff` against the real target.**
107
+ Rejected as unnecessary I/O and directory bookkeeping -- every artifact's
108
+ render step already produces an in-memory string; comparing that string
109
+ against the target file's current content directly needs no intermediate
110
+ file at all.
111
+ - **One aggregate boolean instead of a per-artifact finding list.** Rejected
112
+ -- "something is stale" is far less actionable in a CI log than "docs is
113
+ stale, manifest is fine, `.env.example` is missing entirely."
@@ -0,0 +1,113 @@
1
+ # 0017: A 4th public entry point (`./eslint-plugin`) for a capability-owned-access lint rule
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/eslint-plugin/`, exported as
6
+ `@maverickcer/env-cap/eslint-plugin`.
7
+
8
+ ## Context
9
+
10
+ Nothing in `env-cap`'s runtime or build-time API stops application code from
11
+ reading `process.env` directly, bypassing a capability's `createEnv()`
12
+ contract entirely -- the whole ownership/visibility story this package tells
13
+ (ADR 0003, ADR 0010) is opt-in by convention, not enforced. A lint rule that
14
+ flags a raw `process.env` access outside a capability's own `env.schema.ts`
15
+ closes that gap, but a first draft of this idea risked breaking a real,
16
+ legitimate pattern: a build-time resolver that needs a raw bootstrap
17
+ credential (e.g. `VAULT_TOKEN`) to authenticate to a secrets vault, before
18
+ any `env-cap` contract exists to go through -- there is no capability to
19
+ "own" a variable whose entire purpose is bootstrapping the system that will
20
+ eventually manage every other variable. `test/integration/positive/enterprise/aws-secrets-manager`'s
21
+ `live-expirations.ts` demonstrates the general shape of this pattern
22
+ already (Node-only, build-time orchestration code with a materially
23
+ different trust boundary than application runtime code, per ADR 0012),
24
+ though that specific file authenticates via the AWS SDK's own implicit
25
+ credential chain rather than reading `process.env` directly itself.
26
+
27
+ ## Decision
28
+
29
+ Ship the rule as `@maverickcer/env-cap/eslint-plugin`, a new subpath export
30
+ on the existing package, rather than a standalone
31
+ `@maverickcer/eslint-plugin-env-cap` package. Concretely:
32
+
33
+ - **A 4th entry point, not a new package.** Ties the rule's version to the
34
+ exact contract shape it enforces -- a breaking change to `createEnv()`'s
35
+ API and a breaking change to the rule that understands it ship together,
36
+ under the same semver number, instead of needing a second release
37
+ pipeline, `CODEOWNERS` entry, and cross-repo version-compatibility matrix
38
+ for what is, in practice, always used together with the runtime package.
39
+ - **Zero `allow` entries by default.** The rule ships maximally strict out
40
+ of the box (beyond the built-in `env.schema.ts` exemption below) --
41
+ `env-cap` never guesses at what a given project considers legitimate
42
+ bootstrap code. A consuming project must explicitly populate `allow` with
43
+ its own glob patterns to permit anything else.
44
+ - **`env.schema.ts`/`.tsx` exempted by default, and nothing else.** A
45
+ schema file's entire job is declaring the raw shape `createEnv()`
46
+ contracts wrap -- flagging `process.env` access inside the one place
47
+ that's supposed to define the contract would make the rule fight its own
48
+ purpose. No other file gets a free pass.
49
+ - **The vault/bootstrap-credential trust-boundary as `allow`'s canonical
50
+ justification.** The `RuleOptions.allow` option, and the rule's own error
51
+ message, point at this exact scenario -- a resolver that must read a raw
52
+ credential from `process.env` to authenticate to a secrets manager before
53
+ any contract exists to go through -- as the worked example for when
54
+ `allow` is the correct escape hatch, not a workaround.
55
+
56
+ ## Consequences
57
+
58
+ - A consuming project adopts the rule via
59
+ `import envCapPlugin from "@maverickcer/env-cap/eslint-plugin"` in its own
60
+ flat config, with no second package to install or version-match.
61
+ - `eslint`/`typescript` are optional peer dependencies (`peerDependenciesMeta`)
62
+ so a consumer who never touches `./eslint-plugin` is never nagged about
63
+ either. `@typescript-eslint/utils`/`@typescript-eslint/types` are ordinary,
64
+ bundled devDependencies of `env-cap` itself -- the published package still
65
+ carries zero runtime dependencies.
66
+ - `@typescript-eslint/utils`'s main entry re-exports `ts-eslint` wrapper
67
+ classes (`FlatESLint`/`ESLint`) that do a runtime `require("eslint")`; that
68
+ breaks when bundled into this package's ESM output (no real `require` to
69
+ call). The rule imports narrowly from `@typescript-eslint/utils/eslint-utils`
70
+ (`RuleCreator`) and `@typescript-eslint/types` (`AST_NODE_TYPES`) instead
71
+ of the main entry, avoiding that code path entirely -- and, as a side
72
+ effect, keeping the bundled output over 15x smaller (roughly 28 KB vs.
73
+ 494 KB gzipped-uncompressed) than importing the whole package would.
74
+ - `globToRegExp()` (the `allow` option's matching engine) is the same
75
+ algorithm `src/build/discover.ts` uses for its own `include`/`exclude`
76
+ walk, but deliberately duplicated as `src/eslint-plugin/glob.ts` rather
77
+ than imported from a shared internal module -- each `src/` subfolder maps
78
+ to a public entry point (`.`/`./build`/`./helpers`/`./eslint-plugin`) with
79
+ zero source-level import reaching outside it, so any one of them can move
80
+ to its own repo/package with no cross-folder dependency to untangle first.
81
+ A one-off matching-behavior fix has to land in both copies, a small,
82
+ known cost against that guarantee (see `test/build/glob.test.ts` and
83
+ `test/eslint-plugin/glob.test.ts`, which assert identical behavior from
84
+ each copy).
85
+
86
+ ## Alternatives considered
87
+
88
+ - **A standalone `@maverickcer/eslint-plugin-env-cap` package.** Rejected --
89
+ the common, expected naming convention for an ESLint plugin, but it buys
90
+ nothing here that a subpath export doesn't already provide, at the cost
91
+ of a second release pipeline, a second `CODEOWNERS` surface, and a
92
+ version-compatibility matrix between two packages that are, in every
93
+ realistic case, adopted together.
94
+ - **Default-permissive `allow` (e.g. matching common bootstrap-script
95
+ directory conventions like `scripts/**`).** Rejected -- guessing at what
96
+ counts as trusted bootstrap code on a project's behalf is exactly the kind
97
+ of silent, magic behavior this package avoids elsewhere (ADR 0002, ADR
98
+ 0005). A project that needs the escape hatch states so explicitly.
99
+ - **A shared internal `src/shared/glob.ts` module for `globToRegExp()`,
100
+ imported by both `src/build` and `src/eslint-plugin`.** This was the
101
+ original implementation, and it worked -- one algorithm, one place to fix
102
+ a matching bug. Rejected in favor of per-folder duplication once each
103
+ `src/` subfolder's independent splittability became a hard requirement:
104
+ a module living outside every public entry point but imported by two of
105
+ them is exactly the kind of cross-folder dependency that requirement
106
+ rules out, since neither `build` nor `eslint-plugin` could move to its
107
+ own repo without first deciding where `shared/` goes. Two 40-line copies
108
+ cost less than that ambiguity.
109
+ - **Exempt any file matching `**/*.config.ts` or similar build-tooling
110
+ conventions, not just `env.schema.ts`.** Rejected -- too broad a default
111
+ exemption undermines the rule's entire purpose; a project's own build
112
+ scripts are exactly the kind of file this rule should flag unless the
113
+ project explicitly opts that specific file into `allow`.
@@ -0,0 +1,104 @@
1
+ # 0018: The GitHub Action opens/auto-closes a rotation-alert issue when a run has no PR to comment on
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `scripts/github-action/report.mjs`
6
+ (`buildRotationAlert()`, `upsertRotationIssue()`, `closeRotationIssueIfOpen()`)
7
+ and `action.yml`'s `rotation-alert` input.
8
+
9
+ ## Context
10
+
11
+ `documentEnv()`'s `expiresAt`/`rotationCadence`/`refreshInstructions` fields
12
+ and the generated docs' "Lifecycle report" already give a project real,
13
+ checkable rotation metadata (ADR 0006-adjacent territory). The Action
14
+ (`action.yml`) already turns a `--json` report into inline PR annotations
15
+ and a sticky PR comment -- but both delivery mechanisms require a PR to
16
+ attach to. `main()`'s existing gate
17
+ (`GITHUB_EVENT_NAME === "pull_request" && prNumber`) means a run triggered
18
+ by `schedule`, `workflow_dispatch`, or a plain `push` produces annotations
19
+ that only appear in a workflow run log nobody opens, and a job summary that
20
+ populates a run page nobody visits. On a repository nobody has touched in
21
+ months -- exactly the case where a variable is most likely to quietly
22
+ expire unnoticed -- there was no alert path at all.
23
+
24
+ Every piece this needs already exists and is already tested:
25
+ `doc.expiringSoon` (from `--expiring-within-days`), `collectDocumentationFindings()`'s
26
+ existing error/warning split on `daysRemaining < 0`, and
27
+ `renderMarkdownSummary()`'s "Expiring / expired secrets" table. This is
28
+ additive glue over working infrastructure, not new plumbing.
29
+
30
+ ## Decision
31
+
32
+ - **GitHub Issues, not a workflow failure or a third-party integration.**
33
+ An issue is persistent (survives past the single workflow run that created
34
+ it), triggers GitHub's own email notification to repository watchers, and
35
+ works identically whether the repository is actively developed or
36
+ dormant. A failed scheduled workflow was rejected: `process.exitCode`
37
+ already carries a different meaning for this CLI/Action, and a "red X" on
38
+ a scheduled workflow is easy for GitHub's own UI to bury or for a
39
+ maintainer to mute after the first false alarm. A third-party
40
+ notification integration (Slack webhook, email API) was rejected as a
41
+ new, undeclared dependency that breaks the Action's dependency-free
42
+ design (`ci/size-budgets.mjs`'s header comment states this convention
43
+ for the CLI/build tooling; the Action follows the same principle by only
44
+ ever calling the preinstalled `gh` CLI).
45
+ - **Gated on "no PR available to comment on," not a `schedule`-specific
46
+ event-name check.** `main()`'s existing branch already distinguishes "is
47
+ there a PR to comment on" from every other case; the rotation-alert path
48
+ is simply the `else` of that same condition. This is strictly more
49
+ general than checking `GITHUB_EVENT_NAME === "schedule"` -- it also
50
+ covers a plain `push`-triggered run with no associated PR (e.g. a direct
51
+ push to `main`), which a schedule-specific check would miss.
52
+ - **Auto-close once nothing is left to report**, rather than leaving a
53
+ stale alert open indefinitely. `buildRotationAlert()` returns
54
+ `{ action: "close" }` whenever `expiringSoon` is empty; `main()` maps that
55
+ straight to `closeRotationIssueIfOpen()`, which also leaves a closing
56
+ comment explaining why, so the issue's own timeline stays legible.
57
+ - **Upsert by marker comment, not by title.** `` `<!-- env-cap-rotation-alert:${reportKey} -->` ``
58
+ mirrors `upsertComment()`'s existing PR-comment pattern exactly --
59
+ `listOpenRotationIssues()` finds the one open issue (if any) carrying that
60
+ marker in its body and PATCHes it, rather than risking a duplicate issue
61
+ each run or matching on a title string a maintainer might reasonably edit.
62
+ - **No default label on the created issue.** Requiring a label to already
63
+ exist in every consuming repository (or relying on the API's
64
+ auto-create-label behavior) is an avoidable fragility for a first
65
+ version. An optional `label` input is a natural, backward-compatible
66
+ future addition once real usage shows it's wanted -- not something to
67
+ guess at now.
68
+
69
+ ## Consequences
70
+
71
+ - A repository that adds the scheduled workflow example from the README
72
+ gets a real alert path even if nobody opens the Actions tab for months --
73
+ the email GitHub sends to issue watchers when the issue opens is the
74
+ actual notification mechanism, not the workflow run itself.
75
+ - `rotation-alert: "true"` is the default, but the calling workflow must
76
+ still grant `issues: write` in its own `permissions:` block for the
77
+ `gh api` calls to succeed; the README's copy-pasteable example workflow
78
+ states this explicitly.
79
+ - `listOpenRotationIssues()`/`upsertRotationIssue()`/`closeRotationIssueIfOpen()`
80
+ stay unexported and untested by the unit suite, consistent with
81
+ `upsertComment()`/`listComments()` today -- all four call the `gh` CLI
82
+ directly, which isn't economically unit-testable without a real GitHub
83
+ API or heavy process-mocking. `buildRotationAlert()` is the pure,
84
+ unit-tested boundary; the `gh`-invoking functions are exercised manually
85
+ against a real test repository (see the verification checklist).
86
+ - Running this on every push to `main` (not just scheduled runs) is
87
+ harmless by construction: the marker-based upsert never creates a
88
+ duplicate issue, and closing an already-closed alert is a no-op via
89
+ `listOpenRotationIssues()`'s empty result.
90
+
91
+ ## Alternatives considered
92
+
93
+ - **Fail the workflow (non-zero exit) instead of opening an issue.**
94
+ Rejected -- conflates "the Action found something to report" with "the
95
+ Action itself malfunctioned," and a failed scheduled workflow has no
96
+ persistent, human-visible artifact the way an issue does.
97
+ - **A Slack/email integration.** Rejected -- a new external dependency
98
+ (webhook URL, API credentials) the Action would need to manage, breaking
99
+ the dependency-free design every other part of this tool follows.
100
+ - **Event-name allowlist (`schedule`, `workflow_dispatch`) instead of
101
+ "no PR available."** Rejected as needlessly narrower for no benefit --
102
+ it would miss a plain `push` run with no PR, and the actual constraint
103
+ driving this feature ("nothing to comment on") is exactly what the
104
+ broader check already expresses.