@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
|
@@ -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.
|