@maverickcer/env-cap 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +449 -0
  4. package/CODE_OF_CONDUCT.md +124 -0
  5. package/CODE_REVIEW.md +200 -0
  6. package/CONTRIBUTING.md +131 -0
  7. package/GUIDE.md +1214 -0
  8. package/PROMPT.md +89 -0
  9. package/README.md +92 -200
  10. package/RELEASING.md +160 -0
  11. package/SECURITY.md +270 -0
  12. package/SUPPORT.md +76 -0
  13. package/VERSIONING.md +118 -0
  14. package/benchmarks/READING-BENCHMARKS.md +197 -0
  15. package/benchmarks/README.md +126 -0
  16. package/benchmarks/WRITING-BENCHMARKS.md +252 -0
  17. package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
  18. package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
  19. package/dist/.dts/_ipc/build-fs.d.ts +53 -0
  20. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
  21. package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
  22. package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
  23. package/dist/.dts/_ipc/display-path.d.ts +27 -0
  24. package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
  25. package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
  26. package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
  27. package/dist/.dts/_ipc/glob.d.ts +22 -0
  28. package/dist/.dts/_ipc/glob.d.ts.map +1 -0
  29. package/dist/.dts/_ipc/no-node-fs.d.ts +35 -0
  30. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
  31. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  32. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  33. package/dist/.dts/_ipc/typescript.d.ts +20 -0
  34. package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
  35. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  36. package/dist/.dts/build/compiler-api.d.ts +3 -6
  37. package/dist/.dts/build/compiler-api.d.ts.map +1 -1
  38. package/dist/.dts/build/display-path.d.ts +3 -21
  39. package/dist/.dts/build/display-path.d.ts.map +1 -1
  40. package/dist/.dts/build/generated-banner.d.ts +21 -42
  41. package/dist/.dts/build/generated-banner.d.ts.map +1 -1
  42. package/dist/.dts/build/glob.d.ts +3 -15
  43. package/dist/.dts/build/glob.d.ts.map +1 -1
  44. package/dist/.dts/build/index.d.ts +3 -3
  45. package/dist/.dts/build/link.d.ts.map +1 -1
  46. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  47. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  48. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
  49. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  50. package/dist/.dts/build/types.d.ts +4 -53
  51. package/dist/.dts/build/types.d.ts.map +1 -1
  52. package/dist/.dts/build/typescript.d.ts +3 -17
  53. package/dist/.dts/build/typescript.d.ts.map +1 -1
  54. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  55. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  56. package/dist/.dts/eslint-plugin/index.d.ts +1 -1
  57. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  58. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  59. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  60. package/dist/{build-H4KFV44Z.js → build-F3RQS7VE.js} +218 -63
  61. package/dist/build-F3RQS7VE.js.map +1 -0
  62. package/dist/build.cjs +257 -102
  63. package/dist/build.cjs.map +1 -1
  64. package/dist/build.js +256 -101
  65. package/dist/build.js.map +1 -1
  66. package/dist/{chunk-7GVPOHDU.js → chunk-QKIQ3LZP.js} +2 -2
  67. package/dist/cli/index.js +36 -29
  68. package/dist/cli/index.js.map +1 -1
  69. package/dist/eslint-plugin/index.cjs +95 -54
  70. package/dist/eslint-plugin/index.cjs.map +1 -1
  71. package/dist/eslint-plugin/index.js +94 -53
  72. package/dist/eslint-plugin/index.js.map +1 -1
  73. package/examples/README.md +95 -0
  74. package/package.json +53 -19
  75. package/skills/env-cap/SKILL.md +91 -0
  76. package/skills/env-cap/references/api.md +220 -0
  77. package/specs/architecture.md +634 -0
  78. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  79. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  80. package/specs/decisions/0003-no-global-env-object.md +172 -0
  81. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  82. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  83. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  84. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  85. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  86. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  87. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  88. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  89. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  90. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  91. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  92. package/specs/decisions/0015-security-backport-window.md +60 -0
  93. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  94. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  95. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  96. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  97. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  98. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  99. package/specs/decisions/0022-validation-contexts.md +267 -0
  100. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  101. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  102. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  103. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  104. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  105. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  106. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  107. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  108. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  109. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  110. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  111. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  112. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  113. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  114. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  115. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  116. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  117. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  118. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  119. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  120. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  121. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  122. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  123. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  124. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  125. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  126. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  127. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  128. package/specs/generated-artifacts.md +104 -0
  129. package/specs/migrations/README.md +30 -0
  130. package/specs/migrations/from-centralized-schema.md +503 -0
  131. package/specs/migrations/from-dotenv.md +352 -0
  132. package/specs/migrations/from-envalid.md +482 -0
  133. package/specs/migrations/from-process-env.md +398 -0
  134. package/specs/migrations/from-t3-env.md +416 -0
  135. package/specs/migrations/from-zod.md +303 -0
  136. package/dist/build-H4KFV44Z.js.map +0 -1
  137. /package/dist/{chunk-7GVPOHDU.js.map → chunk-QKIQ3LZP.js.map} +0 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,449 @@
1
+ # Changelog
2
+
3
+ ## 0.7.1
4
+
5
+ ### Patch Changes
6
+
7
+ - fix(examples): move enterprise-platform to vite 8 for TanStack Start
8
+ - 69fda85: - Built with tsup 9, with this month's other development-tool updates; the API-contract check confirms the published API is unchanged.
9
+ - `prepare` honours `npm pack --ignore-scripts` itself. npm 10 (Node 22) still runs `prepare` there, which rebuilt `dist/` from scratch and emptied it under anything reading it at the time, such as this repository's tree-shaking tests.
10
+ - The release's `version` step regenerates the agent skill and landing page, so a release no longer needs a follow-up commit for them.
11
+ - The API pages write `VERSIONING.md` as a file name instead of a link to a nonexistent `http://VERSIONING.md` host.
12
+ - SARIF logs point `$schema` at OASIS's published SARIF 2.1.0 schema; the previous address had stopped resolving (404).
13
+
14
+ ## 0.7.0
15
+
16
+ ### Minor Changes
17
+
18
+ - 8997705: A variable declared in more than one contract is documented once: every field a declaration leaves unset is filled from a declaration of the same variable when one of the two comes from a package's contract, in either direction: the application's declaration takes the package's explanation, and the package's declaration shows the application's own `expiresAt` or `owner` when the application's contracts that set it agree (alternatives that disagree, such as two databases, give it neither). Two of the application's own contracts never fill each other. An application can therefore add only its own `expiresAt` or `owner` to a variable a package already explains. `DUPLICATE_VARIABLE_DOCUMENTATION` is now reported only for a field both declarations set differently.
19
+
20
+ ### Patch Changes
21
+
22
+ - 8997705: fix(eslint-plugin): an `allow` pattern written relative to the working directory, such as `scripts/**`, now matches the absolute path ESLint passes a rule (on Windows too), in `no-raw-process-env` and `no-node-fs`; a `**/`-prefixed pattern matched before and still does. `no-node-fs` also reports `node:fs` reached through a re-export or TypeScript's `import x = require()`. Each rule's documentation link now opens the guide's ESLint plugin section; the README anchor it pointed at did not exist.
23
+ - fix(site): readable inline code in the hero; record the brief link that goes live on deploy
24
+ - fix(security): commit the Socket registry in the form the check writes it
25
+ - fix(security): record the Socket alerts that only appear once a version is published
26
+ - feat(ci): publish the mutation badge and the OpenSSF Scorecard result
27
+ - fix(security): give every v2 Socket record an explicit expires
28
+ - 8997705: `env-cap --help` is shorter and shows examples, with the options grouped by what they are for and no decision-record numbers. Shared build-tooling code (glob, path display, tsconfig path resolution, the generated-file banner, the no-node-fs rule) is now carried as managed copies of the standard's, so a fix lands once. The `/build` types change only in compatible ways: optional options also accept `undefined`, and `configurationReference`, `expiringSoonReport` and `ownershipSummary` also expose the `project` step they are built from.
29
+
30
+ ## 0.6.0
31
+
32
+ ### Minor Changes
33
+
34
+ - b3fd866: TypeScript 7 is supported. `npm i typescript@7 @maverickcer/env-cap` no longer fails with `ERESOLVE` (the optional `typescript` peer is now `^5 || ^6 || ^7`), and the `./build` scanner works under a TypeScript 7 root with no configuration: TypeScript 7 ships no programmatic compiler API, so the scanner uses your `typescript` when it has one (5 and 6, unchanged) and otherwise a bundled `@typescript/typescript6` (ADR 0049). Your `tsc` stays TypeScript 7.
35
+
36
+ - The compiler is bundled inside the package (`bundleDependencies`, about 5 MB packed / 26 MB installed) and used only by the build entry; the runtime, helpers, evidence and node entry points can never reach it (checked in CI by `verify:compiler-isolation`). Bundling also keeps your own `tsc` yours: installing the package does not change `node_modules/.bin/tsc`.
37
+ - With TypeScript 7, the `./build` and `./evidence` declarations name AST types TypeScript 7 does not export, so those two entry points need `skipLibCheck`; the runtime, helpers and node entry points type-check strictly. TypeScript 5 and 6 are unaffected.
38
+ - If the bundled compiler is stripped from an install, the scanner fails before writing anything, with a message that shows the alias to install.
39
+ - CI now installs the packed tarball beside TypeScript 5, 6 and 7 and runs the scanner from both the ESM and CJS entry points.
40
+
41
+ - 931e0d6: Audit fixes ahead of 1.0.
42
+
43
+ - Breaking (pre-1.0 minor): Node.js `>=22` (Node 20 is end-of-life) and an optional `typescript` peer of `^5 || ^6`, so `npm i typescript@6 @maverickcer/env-cap` no longer fails with `ERESOLVE`. With TypeScript 7 the build step now says so instead of failing with `ts.createSourceFile is not a function` (ADR 0047).
44
+ - Breaking (pre-1.0 minor): `@maverickcer/env-cap/eslint-plugin` no longer vendors `@typescript-eslint/utils`; it is an optional peer (ADR 0048). The entry shrinks from ~400 KB to ~7 KB per format.
45
+ - Breaking (pre-1.0 minor): `init` scaffolds `docs/ENV-OWNERSHIP.md` so it can no longer collide with data-cap's `docs/OWNERSHIP.md`.
46
+ - Generated Markdown reports now tell the reader how they are really produced and regenerated (the script that calls `generateDocumentation()` / `generateUsageReport()`), not `npx env-cap --docs`; internal ADR numbers are gone from them.
47
+ - The composite GitHub Action passes every input through environment variables, uses the project's own install, and requires `version` otherwise instead of running an unpinned `latest`.
48
+ - Source maps no longer embed `sourcesContent` (about 60% of the unpacked package).
49
+ - Every documented import now uses the published `@maverickcer/env-cap` name; `./node` is documented as Stable and in the API reference; `--help` links are absolute URLs.
50
+ - Landing page: keyboard-focusable code blocks, a high-contrast theme toggle, forced-colors support.
51
+ - Every `Stryker disable` now says why, 79 mutation exception records are gone, and mutation runs the full suite; `init` scaffolds an https check with `URL` instead of a string prefix.
52
+
53
+ ### Patch Changes
54
+
55
+ - fix: do not mistake a broken typescript install for an absent one
56
+ - fix: run the compiler guard only when a tsconfig file exists
57
+ - fix(build): support TypeScript 6 and test both TypeScript lines (#55)
58
+ - fix(build): keep the sort after path mapping, the fingerprint fallback and the private-field check
59
+ - 3d743bc: With a `tsconfig.json` present and no usable compiler (the bundled TypeScript 6 stripped from an install), the build step now says so instead of failing with a raw "is not a function": the compiler check runs before the tsconfig is read. `tsconfig: false` is unchanged.
60
+
61
+ ## 0.5.3
62
+
63
+ ### Patch Changes
64
+
65
+ - 542534b: Resolve the repository's open Dependabot alerts: update `js-yaml`, `brace-expansion`, `markdown-it`, `qs` and `fast-uri`; override `adm-zip` (reached only through `github-actionlint`) to 0.6.1; and bump `next`, `vitest` and `@sentry/node` in the example projects. Replace the cross-repository sync trigger with a daily pull and re-pin internal-package-contract to its 0.8 release.
66
+
67
+ ## 0.5.2
68
+
69
+ ### Patch Changes
70
+
71
+ - 46e4e0c: Remove npm and Socket-score caches from the CI workflows (CodeQL `actions/cache-poisoning`: a workflow that runs pull-request code could poison a cache the release build later restores), git-ignore the local code-scanning exception registry, and re-pin internal-package-contract to its 0.7.0 release.
72
+
73
+ ## 0.5.1
74
+
75
+ ### Patch Changes
76
+
77
+ - chore(socket): drop the record for the minified-file alert that no longer applies
78
+ - 9a1f69f: Re-pin internal-package-contract to its 0.6.0 release, which scans Socket last and caches the score so the quota is spent once per version.
79
+
80
+ ## 0.5.0
81
+
82
+ ### Minor Changes
83
+
84
+ - feat: sync internal-package-contract version automatically; centralize typedoc config (#24)
85
+ - feat(benchmark): extend coverage to helpers/evidence, add benchmarks nav link
86
+ - e84fa82: Migrates the benchmark pipeline onto internal-package-contract's shared
87
+ benchmark engine (PR #22): `scripts/append-benchmark-history.mjs` and
88
+ `scripts/render-benchmark-summary.mjs` are removed in favor of
89
+ internal-package-contract's own `append-history.mjs`/`render-summary.mjs`,
90
+ called from a new reusable `benchmark-pr` workflow
91
+ (`internal-package-contract/.github/workflows/benchmark-pr.yml`) that
92
+ replaces this repo's own inline job steps. Committed benchmark history moves
93
+ from `docs/benchmark-history/` to `benchmark/history/` (matching data-cap's
94
+ own convention) and gains a v2 schema that carries each tier's full `inputs`
95
+ alongside `medianMs`. The `deploy` job now also publishes a generated
96
+ `docs/benchmarks/index.html` history chart page, built fresh from
97
+ `render-page.mjs` on every deploy, never committed.
98
+
99
+ This is internal tooling only -- no change to any published runtime or
100
+ build-time API.
101
+
102
+ - 08df0e4: **Breaking (pre-1.0 minor -- see VERSIONING.md's Stable pre-1.0 allowance):** removes `--docs`, `--ownership`, `--env-example`, and `--env-example-on-existing` (and, as a direct structural consequence, `--expiring-within-days`) from the `env-cap` CLI. Every remaining CLI flag either has a verified real runtime consumer (`--location`) or is inherent to the tool's own evidence/reporting contract (`--evidence`, `--json`, `--check`, `--strict`/`--strict-docs`/`--strict-ownership`) -- see [ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md).
103
+
104
+ The underlying generator functions are **not removed and are not breaking**: `generateDocumentation`, `generateUsageReport`, `computeDocumentation`, `writeDocumentation`, `computeUsage`, `writeUsageReport`, `generateEnvArtifacts` (including its own `docs`/`usage` options), and `checkEnvArtifacts` all remain fully exported from `env-cap/build`, unchanged. A project that used `--docs`/`--ownership`/`--env-example` now calls these directly from a small build script instead of a CLI flag -- see any of this repo's own `examples/*/scripts/generate-docs/{run.ts,check.ts}` for a complete, copyable pattern (generation and its `--check`-equivalent drift guard).
105
+
106
+ Also fixes a real bug this surfaced and migrates the first-party GitHub Action in the same change: `env-cap`'s Action (`scripts/github-action/report.mjs`) used to read `result.docs`/`result.usage` from the CLI's `--json` output for PR annotations, the summary comment, and rotation-alert issues (ADR 0018) -- since the CLI can no longer populate either field, that reporting would otherwise have gone silently empty for the documentation/ownership/expiring-secret sections regardless of `args`. `report.mjs` now reads `result.evidence` (Finding/Lifecycle/Contract/Ownership/Dependency Model, ADR 0038) instead, which requires `--evidence` in the Action's `args` for full reporting (manifest-only findings still work without it) -- see `action.yml`'s updated `args` description. Covered by a new end-to-end test (`test/scripts/github-action-report.test.ts`) that runs the real CLI entry point, not just a hand-built fixture object, which is what let the original gap through undetected.
107
+
108
+ - acfdc58: Adds four new per-variable schema fields (`authenticatorType`, `rotationPeriod`, `lastRotatedAt`, `rotationTriggerEvents`) to `documentEnv()`'s `variables` shape, alongside the existing `expiresAt`/`refreshInstructions` lifecycle fields -- purely additive, no existing field's behavior changes. `env-cap/build`'s Lifecycle Model (`buildLifecycleModel()`) now threads these through and computes a `rotationStatus` (`compliant`/`overdue`/`expired`/`undeclared`) per variable that declares at least one of them, grounded in NIST SP 800-53 Rev. 5 **IA-5** (Authenticator Management)'s two-trigger rotation model (a time-based `rotationPeriod` and event-based `rotationTriggerEvents`) -- see `src/build/lifecycle-model.ts`'s `computeRotationStatus()` doc comment for the full interpretive judgment call on how a pre-existing `expiresAt` and the new `rotationPeriod`/`lastRotatedAt` pair combine. `LIFECYCLE_MODEL_SCHEMA_VERSION` bumps from 2 to 3 for the new fields, and `computeRotationStatus`/`parseRotationPeriodDays`/`RotationComplianceStatus` are newly exported from `env-cap/build`.
109
+
110
+ Also adds a new example generator, `examples/application/scripts/rotation-log/` (peer to `scripts/generate-docs/`, wired into that example's `docs:reports` npm script), demonstrating a real NIST IA-5 secrets-rotation compliance document (`docs/SECRETS-ROTATION-LOG.md`) built from `env-cap`'s own evidence artifact -- application-level code calling exported `env-cap/build` functions, the same pattern `generate-docs/` established; no new CLI flags. See that directory's own README for the architecture (`types.ts`/`build-model.ts`/`render.ts`/`print-lines.ts`/`run.ts`) and why there's no single official NIST-prescribed template for this document.
111
+
112
+ - 5f4ca0f: Removes the `examples/nextjs-app` ISO 10007/ISO-IEC 27001 open-standard
113
+ alignment report generator (`scripts/open-config-alignment/`, the
114
+ `docs:alignment` script, and the two generated `docs/ISO-*.md` reports).
115
+ The generation logic behind these ISO-branded reports was never verified
116
+ against the real, licensed ISO standard text, creating real copyright/
117
+ mislabeling exposure -- this is a pure deletion, not a design change, and
118
+ no replacement generator is added in its place.
119
+
120
+ ### Patch Changes
121
+
122
+ - fix: stop relying on chmod for the evidence-cache unreadable-file test
123
+ - docs: regenerate api-report/build.md for the rotation-log schema additions
124
+ - fix: regenerate paypal-consumer's stale lockfile pin and golden fixtures
125
+ - chore(benchmarks): refresh results.json
126
+ - fix: stop golden fixtures hardcoding a calendar date that eventually expires
127
+ - chore(benchmarks): refresh results.json
128
+ - fix: regenerate tsconfig-aliases-consumer's stale lockfile pin
129
+ - chore(benchmarks): refresh results.json
130
+ - chore(benchmarks): refresh results.json
131
+ - chore(benchmarks): refresh results.json
132
+ - chore(benchmarks): refresh results.json
133
+ - chore(benchmarks): refresh results.json
134
+ - chore(benchmarks): refresh results.json
135
+ - chore: commit the first-ever api-contract baseline
136
+ - ci: run benchmarks before contract/lint, in one workflow, to stop the re-approval loop
137
+ - chore(benchmarks): refresh results.json
138
+ - chore(benchmarks): refresh results.json
139
+ - fix(size): recalibrate the helpers budget to unminified output
140
+ - chore(benchmarks): refresh results.json
141
+ - chore(benchmarks): refresh results.json
142
+ - fix(test): close mutation-coverage gap on the --evidence-only text output path
143
+ - chore: except a Stryker false-positive survivor in resolve-tsconfig-paths.ts
144
+ - chore(benchmarks): refresh results.json
145
+ - chore(benchmarks): refresh results.json
146
+ - chore(benchmarks): refresh results.json (132477d) (#22)
147
+ - chore(benchmarks): refresh results.json
148
+ - chore(benchmarks): refresh results.json
149
+ - chore(benchmarks): refresh results.json
150
+ - chore(benchmarks): refresh results.json
151
+ - fix: real CI for bot-authored branches; benchmark results land in the PR itself (#23)
152
+ - fix(scripts): update check-readme-example-fresh.mjs to the two-step docs flow
153
+ - 549a694: Stop minifying the published build, move the benchmarks onto internal-package-contract's shared benchmark kit (documented suites, cost-first `BENCHMARKS.md`, `benchmarks/README.md`), and record the shipped URLs and Socket alerts as fully written exceptions.
154
+
155
+ ## 0.4.0
156
+
157
+ ### Minor Changes
158
+
159
+ - 69ff088: Exports `VariableEvidenceDocs` (previously an unexported internal
160
+ interface) from the package root, alongside the existing `ContractDocs`/
161
+ `VariableDocs` type exports.
162
+ - ab1f435: Wires `internal-package-contract`'s governance in for real (CI now runs the
163
+ full contract as a blocking gate, mutation testing ratcheted to zero
164
+ survived/no-coverage/timeout), adds ISO 10007 and ISO/IEC 27001
165
+ open-standard alignment reports, and adds a Next.js example demonstrating
166
+ the client/server environment boundary.
167
+ - 69ff088: Promotes every remaining Experimental-tier surface to Stable (ADR 0045):
168
+ the `packages`/`tsconfig` generator options, `env-cap/build`'s lower-level
169
+ discovery/linking primitives, `generateEvidenceModel`/`getEvidenceModel`/
170
+ `computeSourceFingerprint`/`renderUsageReport`, the `init` CLI subcommand,
171
+ `env-cap/evidence`, and the persisted evidence artifact format. No behavior
172
+ change -- this is a compatibility commitment change only. The Experimental
173
+ tier remains defined in `VERSIONING.md` for future genuinely-new surfaces;
174
+ nothing currently ships under it.
175
+
176
+ **Named caveat** (see ADR 0045): `env-cap/evidence`'s `EvidenceProjectionResult.sources`
177
+ had a specific, previously-documented open design question about its shape
178
+ (flat field-path strings vs. structured `EvidenceReference`s) that is not
179
+ yet resolved. It is promoted along with everything else for one consistent
180
+ fleet-wide policy, but a future shape change there is now a real Stable-tier
181
+ breaking change, not a minor-may-break Experimental adjustment.
182
+
183
+ - 69ff088: **Breaking, pre-1.0 (any Stable API may change in a minor per VERSIONING.md):**
184
+ bare `--strict` now escalates every warning family (compatibility, documentation,
185
+ ownership) to a hard error, not just manifest compatibility (ADR 0044). This
186
+ matches `data-cap`'s own `--strict`, which already escalates
187
+ every pass. `--strict-docs`/`--strict-ownership` are unchanged and still work
188
+ independently. A CI script relying on bare `--strict` _not_ escalating
189
+ documentation/ownership warnings needs to switch to the scoped flags (or fix
190
+ the newly-escalated findings).
191
+
192
+ ### Patch Changes
193
+
194
+ - 69ff088: Fixes the bundled GitHub Action (`action.yml`) referencing the unscoped
195
+ package name `env-cap`, which does not exist on the public npm registry --
196
+ only the published `@maverickcer/env-cap` does. Any workflow using this
197
+ Action via `npx --yes` (its documented fetch path) 404'd. Also clarifies
198
+ the `args` input's description to mention `--evidence`.
199
+ - 69ff088: Fixes `env-cap init` and `env-cap --help` throwing
200
+ `ERR_MODULE_NOT_FOUND: Cannot find package 'typescript'` on a fresh install
201
+ with no `typescript` present. `typescript` is an optional peer dependency
202
+ (only required for build-time manifest generation), but a static top-level
203
+ import of `../build/index.js` was evaluated eagerly for every CLI
204
+ invocation, including the two commands that never touch it. `../build/index.js`
205
+ is now loaded with a dynamic `import()` inside `runCheckMode`/`runGenerateMode`
206
+ only.
207
+
208
+ ## 0.3.1
209
+
210
+ ### Patch Changes
211
+
212
+ - 9059cfa: `overrides` now aliases `puppeteer` -> `puppeteer-core` wherever `pa11y` resolves it -- zero bundled browser, zero Chromium-download postinstall script. A Socket.dev "Install scripts" finding directly hurts this package's own supply-chain score, so this had to go regardless of `pa11y`/`puppeteer` staying real, hard dependencies (no extra install step for anyone).
213
+
214
+ Also pins `tar` to `^7.5.22` (a critical hardlink/symlink-traversal CVE, non-breaking fix).
215
+
216
+ ## 0.3.0
217
+
218
+ ### Minor Changes
219
+
220
+ - Bump to unblock publishing -- 0.2.0 was already published manually to bootstrap npm OIDC trusted publishing (see RELEASING.md), so the registry already holds that exact version and content hash. No functional change beyond the previous release.
221
+
222
+ ### Patch Changes
223
+
224
+ - 61f387c: Publish as the scoped package `@maverickcer/env-cap` instead of `env-cap` -- npm rejected the unscoped name as "too similar to existing packages" (`env-cmd`, `env-var`). The `env-cap` CLI binary name, `npx env-cap` invocation, and all subpath exports (`/build`, `/node`, `/helpers`, `/evidence`, `/eslint-plugin`, `/schema`) are unchanged; only the install/import specifier changes, e.g. `npm install @maverickcer/env-cap` and `import { createEnv } from "@maverickcer/env-cap"`.
225
+
226
+ ## 0.2.0
227
+
228
+ ### Minor Changes
229
+
230
+ - a388405: `buildChangeModel()` now correlates a renamed variable's `addedVariables`/`removedVariables` pair (matched via the current declaration's `renamedFrom`, ADR 0029) into a new `ChangeModel.renamedVariables` array, and takes two new parameters -- `currentContracts` and `root` -- to do so. `ManifestChangeReport` itself is unchanged; `renamedVariables` is additive, not a filter over the existing `addedVariables`/`removedVariables`. See [ADR 0030](specs/decisions/0030-change-model-wraps-manifest-change-report.md).
231
+ - 93635c0: Add the Change Model: `buildChangeModel()`/`ChangeModel` wrap the existing `ManifestChangeReport` (unchanged) in a versioned, model-namespaced shape, giving it the same standing as env-cap's other canonical fact models. See [ADR 0030](specs/decisions/0030-change-model-wraps-manifest-change-report.md).
232
+ - c5d9f3a: `detectCompatibilityIssues()` now sets a stable `code` (`"processor-return-type-conflict"` | `"processor-source-conflict"` | `"validator-source-conflict"`) on every check it runs, matching the `"duplicate-variable-documentation"` code the duplicate-documentation check already set. `CompatibilityIssue.code` is now typed as the new exported `CompatibilityIssueCode` union instead of a bare `string`. First step of the Finding Model work described in [ADR 0024](specs/decisions/0024-fact-model-architecture.md) -- every check now has a stable identifier to key CI filtering, doc-linking, or a future SARIF `ruleId` on.
233
+ - Rename `documentEnv()`'s `ContractDocs.name` field to `displayName`. `name` collided with
234
+ `createEnv()`'s unrelated `CreateEnvOptions.name` (a runtime error-message label) -- same word,
235
+ different meaning, on the same conceptual contract. `ContractDocs.name` is removed, not deprecated
236
+ or aliased, because the collision is the reason for this change and aliasing would leave it
237
+ half-fixed.
238
+
239
+ This is a **breaking change to a Stable-tier TypeScript API** (`documentEnv`'s `ContractDocs`
240
+ parameter -- `documentEnv` itself is listed under VERSIONING.md's Stable tier). It ships as a
241
+ `minor` release only because `env-cap` is pre-1.0 and VERSIONING.md's major-bump requirement is
242
+ explicitly scoped to "once the package reaches 1.0" -- `minor` here does not mean non-breaking.
243
+ `documentEnv()` is a no-op at runtime (ADR 0001), so the only real-world impact is a TypeScript
244
+ compile error at an existing `{ name: ... }` call site, never a behavior change. Migration: rename
245
+ `name` to `displayName` in any `documentEnv()` call that sets it.
246
+
247
+ - cff9afd: Add an optional `classification` field to `documentEnv()`'s contract- and variable-level docs (`"secret" | "credential" | "pii" | "config"`), mirroring `owner`'s default-plus-per-variable-override pattern. Statically discovered like every other documentation field -- threaded through `DiscoveredVariable`/`DiscoveredContract` (`env-cap/build`) and the committed manifest change-report snapshot, including field-level diffing when a variable's classification changes between runs. This is the first step of the Contract Model work described in [ADR 0024](specs/decisions/0024-fact-model-architecture.md) -- the one field the whole exposure/secret-hygiene report cluster was previously blocked on.
248
+ - 60ca77f: Add the Contract Model: a new, versioned, JSON-serializable projection of every declared environment-variable contract, active or not, including both `documentEnv()` metadata and the AST-derived schema facts (`hasDefault`/`hasProcessor`/`hasValidator`/etc.) that the manifest change-report snapshot deliberately excludes. Exported as `buildContractModel()`/`ContractModel` from `env-cap/build`; its JSON Schema is published at the new `env-cap/schema/contract-model` subpath (a `./schema/*` wildcard export now covers any future per-model schema too, alongside the unchanged `./schema`). See [ADR 0025](specs/decisions/0025-contract-model-json-projection.md).
249
+ - cbcbc0d: Add the Dependency Model: `buildDependencyModel()`/`DependencyModel` publish a versioned, JSON-serializable fact-shaped result over the dependency-ownership engine, including an inverse `consumers` index (file -> which contracts it reads, the inverse of the existing contract -> consuming-files view) and per-access-site line numbers that were previously computed but discarded before reaching any type. `dependency-graph.ts`/`scan-dependencies.ts`'s scanning internals stay unexported, unchanged, per [ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md) -- see [ADR 0027](specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md) for why publishing this fact doesn't relax that boundary.
250
+ - Add five new named `documentEnv()` fields, at both contract and variable level: `purpose`, `legalBasis`, `retentionPolicy`, `dataResidency` (`string | string[]`), and `auditRequired` (`boolean`) -- variable-level values override the contract's own, following the existing `owner`/`classification`/`expiresAt` pattern, via new `effectivePurpose()`/`effectiveLegalBasis()`/`effectiveRetentionPolicy()`/`effectiveDataResidency()`/`effectiveAuditRequired()` exports from `env-cap/build`. Deliberately framework-agnostic (no GDPR/HIPAA/SOC2 vocabulary in the field names) -- a framework-specific citation belongs in the widened `metadata` bag instead. `retentionPolicy` is a descriptive policy statement, never parsed or computed, deliberately independent of `expiresAt`'s actual temporal constraint. Threaded through the Contract Model, Manifest Snapshot, Lifecycle Model, generated docs, and `.env.example`. See ADR 0035.
251
+ - `documentEnv()` and `ContractDocs` are now generic over the exact schema type passed to `createEnv()`/`documentEnv()`. `docs.variables`' keys are checked against the schema's own keys at compile time -- documenting a variable that was renamed, removed, or simply mistyped is now a type error at the `documentEnv()` call site itself, instead of a silently-accepted key the generator only reports as "stale" after the fact. Passing the schema object literal (or a `const`-inferred reference to it) gives the strongest inference; explicitly widening `schema` to the bare `EnvSchema` type falls back to the previous behavior (any string key accepted).
252
+ - Add developer-declared dynamic-access citations: a new `dynamicAccess?: readonly string[]` field on `documentEnv()`'s per-variable docs, each entry a `"path:line:column"` citation of where a variable is actually read outside what env-cap's static AST scan can see (a shell script, a Docker entrypoint, a sibling service). `VariableAccessStatus` stays exactly 3-valued and purely AST-derived -- a citation is modeled as a wholly separate, independent `dynamicAccessAssertions` fact on `DependencyModelVariable`, each with its own re-derived-every-run `"fresh" | "stale" | "missing"` acknowledgment (a SHA-256 content-hash comparison against a committed baseline in the manifest snapshot, mirroring the existing `renamedFrom`/`expiresAt` pattern). Only a fresh assertion suppresses the corresponding `unconsumed-owned-variable`/`indeterminate-ownership` finding -- and never silently: the variable is instead reported in a new `asserted` category (rendered as "## Asserted (developer-acknowledged dynamic access)" in the Dependency & Ownership Report), always showing the raw AST-derived status alongside the citation. A citation that goes stale or missing raises a new `Finding` (`dynamic-access-citation-stale`/`dynamic-access-citation-missing`) on the very next run. See ADR 0037.
253
+ - Finish wiring `classification` through the pipeline, matching the treatment its sibling
254
+ documentation fields (`owner`, `purpose`, `legalBasis`, `retentionPolicy`, `dataResidency`,
255
+ `auditRequired`) already get: a new `effectiveClassification()` helper (`env-cap/build`,
256
+ internal like its siblings other than `effectiveOwner()`) resolves a variable's own classification,
257
+ falling back to its contract's; the effective value now renders as a `- Classification:` line in
258
+ generated docs and appears on `CatalogContract`/`CatalogVariable`'s JSON shape (a purely additive
259
+ field); and two documented declarations of the same variable that disagree on `classification` now
260
+ produce a `duplicate-variable-documentation` compatibility warning, the same as an `owner`/
261
+ `description` mismatch already does -- this can surface a _new_ warning for a project whose
262
+ contracts already silently disagree on classification, worth checking before enabling
263
+ `onIncompatibility: "throw"`.
264
+ - fc96fa2: Add an `onExisting` option to `.env.example` generation (`envExample.onExisting` on `generateDocumentation()`/`generateEnvArtifacts()`, `--env-example-on-existing` on the CLI): `"keep-sibling"` (default, unchanged behavior — never overwrites, writes a timestamped sibling instead), `"overwrite"` (replace the existing file directly), or `"skip"` (write nothing when a file already exists).
265
+ - c81d1e4: Adds a 5th public entry point, `env-cap/evidence` (Experimental), exporting `defineEvidenceProjection()` -- a pure, isomorphic transform from the immutable `EvidenceModel` (ADR 0024) to any consumer-defined output shape. Every projector's `EvidenceModel` argument is wrapped in a read-only tracking Proxy that throws on any mutation attempt and automatically records which field paths were read, surfaced via the projection's `.project(evidence)` method alongside the computed value. See ADR 0031 (the new entry point) and ADR 0032 (the provenance mechanism, including why it clones rather than relying on `Object.freeze()`).
266
+ - Export `SourcePosition`, `DynamicAccessAssertion`, and `ScannedSurface` from `env-cap/build` -- these shapes were already referenced by public fields (`ContractModelContract.declaration`/`.documentation`, `ContractModelVariable.declaration`, `DependencyModelContract.dynamicAccessSites`, `DependencyModelVariable.positions`/`.dynamicAccessAssertions`, `DependencyModel.scannedSurfaces`) since ADR 0036/ADR 0037, but the types themselves were never nameable by a consumer writing their own projection or tooling against those fields.
267
+ - Rename two `FindingCode` values to match the adjective-first word order every other code in the
268
+ union uses: `"dynamic-access-citation-missing"` -> `"missing-dynamic-access-citation"`, and
269
+ `"dynamic-access-citation-stale"` -> `"stale-dynamic-access-citation"`. `FINDING_MODEL_SCHEMA_VERSION`
270
+ bumped from 1 to 2. This is a rename, not an additive union member -- the old strings are no
271
+ longer produced anywhere. `FindingModel`/`EvidenceModel` are Experimental (VERSIONING.md), so this
272
+ ships without a major bump; a consumer matching on these exact `code` strings (in a projection, CI
273
+ filter, or dashboard) needs to update them.
274
+ - beea60a: Add the Finding Model: `buildFindingModel()`/`Finding`/`FindingModel` unify `CompatibilityIssue`, `ArtifactCheckFinding`, `DocumentationFindings`, and the four `usage-report.ts` ownership findings into one shape with a required, stable `code`, a coarse `family` discriminant, and a structured `location: EvidenceReference` pointer instead of a formatted string. All four existing finding types are unchanged -- this is purely additive. Also adds the new `EvidenceReference` type (`ContractEvidenceReference` | `OwnershipEvidenceReference` | `ChangeEvidenceReference`), the structured-location vocabulary the Finding Model and, later, `defineEvidenceProjection()` build on. See [ADR 0026](specs/decisions/0026-finding-model-unifies-four-families.md).
275
+ - dadba33: Adds `generateEvidenceModel()` (`env-cap/build`, Experimental) -- the assembly orchestrator that runs schema discovery and linking once, then builds all seven canonical fact models (Contract, Dependency, Ownership, Lifecycle, Finding, Change, Evidence) by calling each model's own public builder directly, `deepFreeze()`s the result, and stamps provenance (a fresh `generatedAt`, env-cap's own `toolVersion`, and an optional caller-supplied `commit`). Unlike `generateEnvManifest()`/`generateDocumentation()`/`generateUsageReport()`/`generateEnvArtifacts()`, it never throws on a data-quality finding -- every compatibility issue, undocumented variable, abandoned contract, and similar shows up as a `Finding` in the returned model instead, by design.
276
+ - Add "Joined Variable View" as an eleventh first-party reference projection, alongside the original
277
+ ten from ADR 0024, in `test/integration/positive/enterprise/evidence-projections/`
278
+ (`projections/joined-variables.mjs`). One row per declared variable, joining Contract Model,
279
+ Dependency Model, and Lifecycle Model by `${file}#${exportName}#${key}` identity, with a fixed and
280
+ documented field list -- a working, copyable example of the cross-model join every one of the
281
+ other ten projections performs its own version of, for a `defineEvidenceProjection()` author to
282
+ start from instead of re-deriving it. Shipped as an example, not a package export -- see ADR
283
+ 0033's "Alternatives considered" on why a public entry point exporting ready-made projections was
284
+ rejected; this doesn't reopen that decision.
285
+ - 13cb26e: Add `deprecated`/`deprecatedReason`/`removeBy`/`renamedFrom` to `documentEnv()`'s per-variable docs (`deprecated`/`deprecatedReason` also at the contract level), threaded through the same static-analysis path every other documentation field follows -- `DiscoveredContract`/`DiscoveredVariable`, and the committed manifest change-report snapshot with field-level diffing. Add the Lifecycle Model: `buildLifecycleModel()`/`LifecycleModel` promote the existing `ExpiringEntry`/`computeExpiringEntries()` into a canonical, versioned shape (`expiring`), plus a new `contracts` array carrying every lifecycle-relevant fact for contracts/variables that set at least one. See [ADR 0029](specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md).
286
+ - fc96fa2: `generateEnvManifest()`/`generateEnvArtifacts()` now track `documentEnv()` metadata changes across runs: a new `changes` field on the manifest result (also in `--json`/CLI output) reports contracts and variables added, removed, or updated since the last run, with field-level before/after values. Backed by a new committed sidecar snapshot file next to the manifest (`<location>.snapshot.json` — see [ADR 0021](specs/decisions/0021-manifest-change-report-persisted-snapshot.md)).
287
+
288
+ Also adds a new `duplicate-variable-documentation` warning: two active contracts documenting the same variable key with different `description`/`owner`/`expiresAt`/`refreshInstructions`/`required`/`extra` now produce a warning (never a hard error) naming exactly which fields diverge, alongside the existing processor/validator compatibility checks. `CompatibilityIssue` gains an optional `code` field, populated for this new check.
289
+
290
+ - 72fc1a8: Add an `optional()` validator to `env-cap/helpers`: passes automatically when the value is `undefined`, otherwise delegates to the wrapped validator. Useful for validating optional environment variables (e.g. `validators.optional(validators.url())`) without hand-writing the `undefined` check.
291
+ - 772d743: Add the Ownership Model: `buildOwnershipModel()`/`OwnershipModel` publish every contract and variable's effective owner, plus first-class `unownedContracts`/`unownedVariables` arrays -- previously only a count (`noOwnerCount`) inside `docs.ts`'s rendered security-review text. Also exports `effectiveOwner()` (relocated from `docs.ts` to `link.ts`) as reusable public surface. See [ADR 0028](specs/decisions/0028-ownership-model-shared-effective-owner.md).
292
+ - 7b585f9: Remove the `notDefault()` and `notOneOf()` validators from `env-cap/helpers` -- rarely used, and part of bringing `dist/helpers.js` back under its 3072-byte gzip budget (see [ADR 0008](specs/decisions/0008-gzip-size-budget.md)). Equivalent behavior is still directly expressible with existing validators: `validators.not(validators.oneOf([...]))` covers both `notDefault` and `notOneOf`.
293
+
294
+ Every built entry point (`dist/index.js`, `dist/helpers.js`, `dist/build.js`, `dist/cli/index.js`, `dist/eslint-plugin/index.js`) also no longer ships source comments -- esbuild's unminified default otherwise preserved every JSDoc comment verbatim, which was pure dead weight against the gzip budget (declarations, and the IDE hover they drive, come from a separate `tsc` pass, never from these `.js` files). No identifiers are mangled and no syntax is rewritten, so a debugger stepping into `dist/*.js` still reads like the source.
295
+
296
+ - 7237e13: Extracts `renderDocs()`'s security-review counters (total/active variables, expired/expiring-soon counts, unowned/duplicate-name counts, undocumented counts) into a new exported `computeSecurityReviewCounters()`/`SecurityReviewCounters` from `env-cap/build`, instead of only ever becoming rendered Markdown text. The rendered "Security review" section is unchanged, byte-for-byte. Also dedupes the days-remaining arithmetic that was previously implemented three times (`computeExpiringEntries`, the lifecycle report, and the security review) into one shared internal helper. Part of the Finding Model groundwork described in [ADR 0024](specs/decisions/0024-fact-model-architecture.md).
297
+ - Add `setupInstructions` to `VariableDocs`/`ContractDocs` (`documentEnv()`) -- "how to get a value the first time" (provisioning, requesting access, generating a secret), distinct from the existing `refreshInstructions` ("how to rotate it once you have one"). Threaded through the Contract Model, manifest snapshots, generated `ENVIRONMENT.md` (its own `- Setup instructions:` line, before `Refresh instructions`), and generated `.env.example` (a `# Setup:` comment, before `Expires At`).
298
+ - Add exact source-position evidence throughout the build pipeline, exported as a new `SourcePosition` type from `env-cap/build`. `ContractModelContract` gains `declaration` (its `createEnv()` call, always present) and `documentation` (its `documentEnv()` call, when one exists) -- two distinct positions, never collapsed into one. `ContractModelVariable` gains its own `declaration` (the variable's schema property). `DependencyModelContract` gains `dynamicAccessSites: readonly SourcePosition[]`, retaining every computed (dynamic) property-access site observed, not just a `hasDynamicAccess` boolean. `DependencyModel` gains `scannedSurfaces: readonly { label: string; root: string }[]`, naming every surface actually scanned for usage -- the application root plus one entry per allow-listed `packages` (ADR 0014) source -- so "no consumer found" claims are never stronger than what was actually searched. `EvidenceReference`'s contract/ownership variants gain an optional `position: SourcePosition | undefined` field for future findings to point at an exact location. `CONTRACT_MODEL_SCHEMA_VERSION` bumped 1 -> 2. See ADR 0036.
299
+ - 7c84ad4: Add Experimental TypeScript path-alias resolution. A new `tsconfig` option (and CLI `--tsconfig <path>` / `--no-tsconfig`) on `generateEnvManifest()`/`generateDocumentation()`/`generateUsageReport()`/`generateEnvArtifacts()` resolves import specifiers written as `tsconfig.json` path aliases (e.g. `"@/lib/env.schema.js"`) during static analysis, so a contract or `documentEnv()` call reached only through an alias isn't misreported as abandoned, unresolved, or undocumented. Unlike cross-package discovery's `packages` option (ADR 0014), this is on by default -- `tsconfig.json` at `root` is auto-detected automatically, matching `tsc`'s own behavior, since a project's own tsconfig never crosses the trust/versioning boundary an installed package does. Pass an explicit path for a monorepo whose relevant config isn't at `root`, or `false` to disable entirely. The actual `paths`/`baseUrl` matching is delegated to the TypeScript compiler itself and never resolves into `node_modules` -- that boundary remains exclusively `packages`'. See [ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md) and `examples/tsconfig-aliases` for a runnable demonstration -- `examples/tsconfig-aliases-consumer` additionally proves this composes correctly with cross-package discovery (ADR 0014) in one real install.
300
+ - 7b585f9: Add generic, framework-agnostic validation contexts. A schema entry may declare a `context` (e.g. `"server"`, `"production"`, `"worker"` -- entirely application-defined, never interpreted by env-cap), and `validateEnv()` accepts the `activeContexts` active for a run. A variable with no `context` always participates; a variable with a `context` participates only when `activeContexts` includes it, otherwise it's skipped entirely (no default/processor/validator runs, and it stays in its not-ready state). Existing schemas that never set `context` are unaffected. Generated docs and `.env.example` surface a variable's validation context alongside a caveat that it's a participation filter only, not a bundling/security boundary or an authorization mechanism. When at least one variable declares a `context`, the generated manifest also exports `activeContexts` -- every context found across its (active) contracts -- so application code can pass it straight to `validateEnv()` without hand-typing the list. See [ADR 0022](specs/decisions/0022-validation-contexts.md).
301
+
302
+ ### Patch Changes
303
+
304
+ - 37de92f: Genericizes `live-expirations.ts`'s private, `DiscoveredContract[]`-hardcoded `deepFreezeContracts()` into a new, exported `deepFreeze<T>(value: T): T` (`env-cap/build`). No behavior change for `resolveLiveExpirationDates()`, which now calls the generic version internally.
305
+ - Generated docs (`renderDocs()`/`--docs`) and the dependency & ownership report
306
+ (`renderUsageReport()`/`--ownership`) now each print a one-line "Produced by `env-cap --docs`"/
307
+ "Produced by `env-cap --ownership`" note under their heading, so the generated file itself names
308
+ the CLI flag that produced it. Purely additive Markdown; no shape change, no CLI/API change.
309
+ - fc96fa2: Fix `--check` (and `checkEnvArtifacts()`) always reporting the `docs` artifact as stale on the very first check immediately following a project's very first-ever documentation generation, with no real drift involved. `renderDocs()`'s "Changes since last report" section now renders "No changes." on a true first run too, instead of being omitted — the omission broke the fixed-point property `--check`'s comparison depends on (regenerating using a file's own content as `previousContent` must reproduce that file exactly). See [ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md).
310
+ - d57c854: Fixes `LifecycleModel.expiring[].file` to be root-relative and POSIX-separated, matching `LifecycleModelContract.file` and every other canonical model's file convention -- it previously leaked an absolute, machine-specific filesystem path (`buildLifecycleModel()` called `computeExpiringEntries()` without relativizing its result, unlike the rest of the model). `ExpiringEntry`'s own doc comment (an absolute path) still applies to `computeExpiringEntries()`'s other direct consumers (e.g. `DocumentationFindings.expiringSoon`), which are unaffected.
311
+ - Generalize `documentEnv()`'s `metadata` from a contract-only, string-valued field into a symmetric `Record<string, unknown>` field available at both contract and variable level, accepting any primitive or object value per key. `VariableDocs`'s previous open index signature (which silently swept unrecognized string-valued keys into an internal `extra` bag, and silently dropped anything else) is removed -- a value must now be nested under a literal `metadata: {...}` key to be captured. See ADR 0035.
312
+ - 772d743: Fix `generateUsageReport()`'s `unconsumedOwnedVariables[].owner` ignoring a variable-level `owner` override when the contract has none set. It previously resolved ownership using only the contract's default `owner`, so a `documentEnv()` call setting `variables: { KEY: { owner: "..." } }` with no contract-level `owner` produced `owner: undefined` for that finding, disagreeing with the docs Catalog and ownership matrix (which already applied the variable-then-contract fallback correctly). `dependencyOwnership`/`abandonedContracts` are unaffected -- those are genuinely contract-level facts with no variable to override.
313
+ - 44fc5a0: Relocate the import-resolution modules (`resolve-import.ts`, `resolve-tsconfig-paths.ts`, `resolve-package-schema.ts`, `resolve-within-root.ts`) into a new `src/build/resolution/` subfolder, consolidating the `resolveImportSpecifier()` chokepoint (relative → alias → package resolution, ADR 0023/ADR 0014) into one cohesive location. Internal reorganization only -- `env-cap/build`'s public export names, types, and behavior are unchanged; verified byte-identical before/after. Prompted by `data-cap` needing the same resolver design; see that package's `src/build/resolution/` for the ported copy.
314
+ - Replace `DependencyModelVariable.lines: readonly number[]` (and the underlying `AccessSite`/`VariableAccessInfo` shapes) with `positions: readonly SourcePosition[]`, a `{ file, line, column }` per access site instead of a bare, file-less line number -- closes a gap where a variable read from more than one file had no way to tell which file a given line number came from. `DEPENDENCY_MODEL_SCHEMA_VERSION` bumped 1 -> 2. See ADR 0036.
315
+
316
+ All notable changes to this project will be documented in this file.
317
+
318
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
319
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
320
+ once it reaches 1.0. Before 1.0, minor versions may include breaking changes.
321
+
322
+ ## [0.1.0] - 2026-08-02
323
+
324
+ Carried over from the legacy hand-kept `[Unreleased]` block that sat above this release:
325
+
326
+ - Build: **Experimental** TypeScript path-alias resolution -- a new `tsconfig`
327
+ option (and CLI `--tsconfig <path>` / `--no-tsconfig`) on `generateEnvManifest()`/
328
+ `generateDocumentation()`/`generateUsageReport()`/`generateEnvArtifacts()` resolves
329
+ import specifiers written as `tsconfig.json` path aliases (`"@/lib/env"`) during
330
+ static analysis, so a contract or `documentEnv()` call reached only through an alias
331
+ isn't misreported as abandoned/unresolved in the manifest, docs, or Dependency &
332
+ Ownership Report. Unlike `packages` (ADR 0014), this is on by default -- `tsconfig.json`
333
+ at `root` is auto-detected, matching `tsc`'s own behavior, since a project's own
334
+ tsconfig never crosses the trust/versioning boundary an installed package does. See
335
+ [ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md) and
336
+ [`VERSIONING.md`](VERSIONING.md) for the Experimental-surface policy this ships under.
337
+ `examples/tsconfig-aliases` demonstrates it end to end, including the ownership-report
338
+ false positive it fixes; `examples/tsconfig-aliases-consumer` additionally installs it as
339
+ a real package (a real packed tarball, same shape as `examples/paypal-consumer`) to prove
340
+ this composes correctly with cross-package discovery (ADR 0014) in one run.
341
+
342
+ Initial release.
343
+
344
+ - Runtime: `createEnv()` / `validateEnv()` / `documentEnv()` -- capability-owned,
345
+ lazily-resolved environment contracts with no global env object.
346
+ - Build: `generateEnvManifest()` / `generateDocumentation()` / `generateUsageReport()` /
347
+ `generateEnvArtifacts()` -- static AST discovery and artifact generation, never
348
+ importing or executing schema files.
349
+ - Helpers: `@maverickcer/env-cap/helpers` -- optional, tree-shakeable
350
+ processor/validator convenience functions.
351
+ - CLI: `npx env-cap` for CI/release-pipeline artifact generation.
352
+ - CLI: a published JSON Schema for `--json` output (`schemas/env-cap-report.schema.json`,
353
+ also exported as `@maverickcer/env-cap/schema`) for external, non-TypeScript
354
+ tooling to validate or codegen against -- generated directly from
355
+ `src/cli/json.ts`'s types, never hand-authored, so the two can't silently
356
+ drift apart. See [ADR 0019](specs/decisions/0019-published-json-schema-generated-from-types.md).
357
+ - GitHub Action: a new `rotation-alert` input (default `true`) opens/updates a
358
+ GitHub issue -- and auto-closes it once resolved -- when a run has no PR to
359
+ comment on (a `schedule`/`workflow_dispatch`/plain-`push` trigger) and finds
360
+ an expiring or expired variable, so a dormant repository still gets a real,
361
+ emailed alert. See [ADR 0018](specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md).
362
+ - ESLint: new `@maverickcer/env-cap/eslint-plugin` subpath export, a
363
+ `no-raw-process-env` rule that flags direct `process.env` access outside a
364
+ capability's own `env.schema.ts`, with an `allow` glob-list escape hatch for
365
+ legitimate build-time bootstrap code (e.g. a resolver reading a raw
366
+ `VAULT_TOKEN` to authenticate to a secrets manager before any contract
367
+ exists to go through). See [ADR 0017](specs/decisions/0017-eslint-plugin-entry-point.md).
368
+ - CLI: new `--check` flag verifies every requested artifact (manifest/docs/
369
+ `.env.example`/ownership report) is up to date without writing anything --
370
+ a CI drift guard for a schema change that forgot a local regeneration.
371
+ `--json`'s envelope gains an additive `checkResult: { ok, stale }` field.
372
+ See [ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md).
373
+ - CLI: a leading `⚠ N unresolved/dropped-schema warning(s) found` banner
374
+ prints before the rest of a non-JSON run's output whenever a schema
375
+ couldn't be statically resolved -- purely additive visibility, no change
376
+ to exit-code semantics.
377
+ - Docs: SECURITY.md commits to a concrete post-1.0 security-backport policy (latest
378
+ minor of the previous major, minimum six months after a new major ships, extendable
379
+ but never shortened once stated) -- see
380
+ [ADR 0015](specs/decisions/0015-security-backport-window.md).
381
+ - Build: `GenerateDocumentationResult.catalog` -- the full per-variable documentation
382
+ content (description, owner, `expiresAt`, `extra` metadata, ...) alongside the
383
+ existing `contracts` summary, keyed by variable name within each contract.
384
+ - CLI: `--json` flag emits a versioned, machine-readable report (`{ schemaVersion,
385
+ kind, toolVersion, ok, ... }`) instead of formatted text, for CI checks, PR
386
+ annotations, and dashboards. Exit-code semantics are unchanged.
387
+ - GitHub Action: a first-party, dependency-free composite Action (`action.yml`) runs
388
+ the CLI with `--json` and turns the result into inline PR annotations and a sticky
389
+ summary comment.
390
+ - Build: **Experimental** cross-package schema discovery -- a new `packages`
391
+ option (and CLI `--package <name>`, repeatable) on `generateEnvManifest()`/
392
+ `generateDocumentation()`/`generateUsageReport()`/`generateEnvArtifacts()` lets a
393
+ project discover a schema that ships inside a separately-published, installed
394
+ package via an explicit allowlist, never an implicit scan of `node_modules`. See
395
+ [ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md) and
396
+ [`VERSIONING.md`](VERSIONING.md) for the Experimental-surface policy this ships
397
+ under. `examples/paypal-addon`/`examples/paypal-consumer` now demonstrate it
398
+ against a real packed tarball, not a monorepo-sibling workaround.
399
+ - Docs: `GenerateUsageReportResult` gains `parseWarnings`, surfacing schema-discovery
400
+ and package-resolution warnings from the `--ownership`/usage pass, matching the
401
+ other two generators (purely additive; no `schemaVersion` bump per ADR 0013).
402
+ - New `VERSIONING.md` codifying the stable/Experimental/private semver scope, and
403
+ `ADOPTION.md` synthesizing the security model, versioning stance, and migration
404
+ cost for technical decision-makers.
405
+ - README: runtime support matrix, a Troubleshooting section keyed by exported error
406
+ class, and a "Reusable packages" section documenting cross-package discovery.
407
+ - Specs: backfilled [ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md)
408
+ (dependency-ownership engine's scope boundary) and
409
+ [ADR 0011](specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md)
410
+ (shared discovery, compute-atomic but not write-atomic `generateEnvArtifacts()`),
411
+ both already-implemented decisions that were referenced by number but never
412
+ written down until now.
413
+ - Governance: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1),
414
+ `CODEOWNERS`, and tailored issue/PR templates.
415
+ - CI: GitHub Actions pinned to commit SHAs; Node matrix refreshed to currently
416
+ maintained LTS lines (`18.x`/`22.x`/`24.x` required, `26.x` Current as a
417
+ non-blocking signal) while `engines.node` stays `>=18.0.0`, unchanged, since
418
+ nothing in the code requires newer; a new cross-runtime job runs the same
419
+ conformance suite under Bun and Deno's own native test runners, not just
420
+ Node/vitest; an `examples` job installs and typechecks/runs all seven
421
+ reference examples against the real, just-built package.
422
+ - Adopted `@typescript-eslint`'s `strict-type-checked` + `stylistic-type-checked`
423
+ ESLint configuration (`npm run lint`, its own step in CI) with
424
+ every finding fixed or explicitly, narrowly justified -- including two real bugs
425
+ this caught: an untyped `new Map()` fallback that silently widened a chain of
426
+ values to `any`, and `EnvContract`'s type not declaring the `toString()` override
427
+ `create.ts` actually implements.
428
+ - `vitest.config.ts` now enforces coverage thresholds (lines/branches/functions/
429
+ statements) in CI, not just locally informational reporting.
430
+ - Runtime/build error classes (`EnvValidationError`, `EnvNotReadyError`,
431
+ `EnvManifestGenerationError`, `EnvDocumentationGenerationError`,
432
+ `EnvUsageAnalysisError`, `EnvProjectGenerationError`) gain a stable, Stable-tier
433
+ `code` field for programmatic handling that doesn't depend on `.name`/`instanceof`.
434
+ - Release: adopted [Changesets](https://github.com/changesets/changesets) plus a
435
+ new `release.yml` workflow publishing via npm's OIDC trusted publishing -- no
436
+ `NPM_TOKEN` secret, provenance-attested by default. See `CONTRIBUTING.md`'s
437
+ release-process section for the one-time, human-only npmjs.com setup step this
438
+ requires.
439
+ - Website: dark mode (follows `prefers-color-scheme`, overridable via a new header
440
+ toggle, persisted); a dependency-free `Cmd+K`/`Ctrl+K` search over the page's own
441
+ sections and FAQ entries; an `aria-live` announcement for the copy-button
442
+ confirmation; a fixed borderline (~4.55:1) muted-text contrast token to ~7.2-7.6:1;
443
+ named links to specific ADRs from the Security and Adoption sections instead of a
444
+ generic repository link; `sitemap.xml` plus a `Sitemap:` line in `robots.txt`;
445
+ a Getting Started mention of the ESLint plugin and `--json`/`--check`; removed
446
+ several leftover, never-referenced CSS classes (`.card`, `.callout--warning`,
447
+ `.callout--success`, `.comparison-table .is-positive`).
448
+
449
+ [0.1.0]: https://github.com/maverickcer/env-cap/releases/tag/v0.1.0
@@ -0,0 +1,124 @@
1
+ <!-- Managed by internal-package-contract. Do not edit this file: change template/package/CODE_OF_CONDUCT.md in the standard and run `internal-package-contract sync`. -->
2
+
3
+ # Contributor Covenant Code of Conduct
4
+
5
+ ## Our Pledge
6
+
7
+ We as members, contributors, and leaders pledge to make participation in our
8
+ community a harassment-free experience for everyone, regardless of age, body
9
+ size, visible or invisible disability, ethnicity, sex characteristics, gender
10
+ identity and expression, level of experience, education, socio-economic
11
+ status, nationality, personal appearance, race, caste, color, religion, or
12
+ sexual identity and orientation.
13
+
14
+ We pledge to act and interact in ways that contribute to an open, welcoming,
15
+ diverse, inclusive, and healthy community.
16
+
17
+ ## Our Standards
18
+
19
+ Examples of behavior that contributes to a positive environment for our
20
+ community include:
21
+
22
+ - Demonstrating empathy and kindness toward other people
23
+ - Being respectful of differing opinions, viewpoints, and experiences
24
+ - Giving and gracefully accepting constructive feedback
25
+ - Accepting responsibility and apologizing to those affected by our mistakes,
26
+ and learning from the experience
27
+ - Focusing on what is best not just for us as individuals, but for the
28
+ overall community
29
+
30
+ Examples of unacceptable behavior include:
31
+
32
+ - The use of sexualized language or imagery, and sexual attention or advances
33
+ of any kind
34
+ - Trolling, insulting or derogatory comments, and personal or political
35
+ attacks
36
+ - Public or private harassment
37
+ - Publishing others' private information, such as a physical or email
38
+ address, without their explicit permission
39
+ - Other conduct which could reasonably be considered inappropriate in a
40
+ professional setting
41
+
42
+ ## Enforcement Responsibilities
43
+
44
+ Community leaders are responsible for clarifying and enforcing our standards
45
+ of acceptable behavior and will take appropriate and fair corrective action
46
+ in response to any behavior that they deem inappropriate, threatening,
47
+ offensive, or harmful.
48
+
49
+ Community leaders have the right and responsibility to remove, edit, or
50
+ reject comments, commits, code, wiki edits, issues, and other contributions
51
+ that are not aligned to this Code of Conduct, and will communicate reasons
52
+ for moderation decisions when appropriate.
53
+
54
+ ## Scope
55
+
56
+ This Code of Conduct applies within all community spaces, and also applies
57
+ when an individual is officially representing the community in public
58
+ spaces.
59
+
60
+ ## Enforcement
61
+
62
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be
63
+ reported to the community leaders responsible for enforcement through a
64
+ [GitHub security advisory](https://github.com/maverickcer/env-cap/security/advisories/new)
65
+ or the contact information provided on the npm package page. All complaints
66
+ will be reviewed and investigated promptly and fairly.
67
+
68
+ All community leaders are obligated to respect the privacy and security of
69
+ the reporter of any incident.
70
+
71
+ ## Enforcement Guidelines
72
+
73
+ Community leaders will follow these Community Impact Guidelines in
74
+ determining the consequences for any action they deem in violation of this
75
+ Code of Conduct:
76
+
77
+ ### 1. Correction
78
+
79
+ **Community Impact**: Use of inappropriate language or other behavior deemed
80
+ unprofessional or unwelcome in the community.
81
+
82
+ **Consequence**: A private, written warning from community leaders, providing
83
+ clarity around the nature of the violation and an explanation of why the
84
+ behavior was inappropriate. A public apology may be requested.
85
+
86
+ ### 2. Warning
87
+
88
+ **Community Impact**: A violation through a single incident or series of
89
+ actions.
90
+
91
+ **Consequence**: A warning with consequences for continued behavior. No
92
+ interaction with the people involved for a specified period of time. This
93
+ includes avoiding interactions in community spaces as well as external
94
+ channels. Violating these terms may lead to a temporary or permanent ban.
95
+
96
+ ### 3. Temporary Ban
97
+
98
+ **Community Impact**: A serious violation of community standards, including
99
+ sustained inappropriate behavior.
100
+
101
+ **Consequence**: A temporary ban from any sort of interaction or public
102
+ communication with the community for a specified period of time.
103
+
104
+ ### 4. Permanent Ban
105
+
106
+ **Community Impact**: Demonstrating a pattern of violation of community
107
+ standards, including sustained inappropriate behavior, harassment of an
108
+ individual, or aggression toward or disparagement of classes of individuals.
109
+
110
+ **Consequence**: A permanent ban from any sort of public interaction within
111
+ the community.
112
+
113
+ ## Attribution
114
+
115
+ This Code of Conduct is adapted from the [Contributor Covenant][homepage],
116
+ version 2.1, available at
117
+ [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
118
+
119
+ Community Impact Guidelines were inspired by
120
+ [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
121
+
122
+ [homepage]: https://www.contributor-covenant.org
123
+ [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
124
+ [Mozilla CoC]: https://github.com/mozilla/diversity