@maverickcer/env-cap 0.6.0 → 0.7.0

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 (136) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +438 -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 +34 -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/link.d.ts.map +1 -1
  45. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  46. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  47. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
  48. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  49. package/dist/.dts/build/types.d.ts +4 -53
  50. package/dist/.dts/build/types.d.ts.map +1 -1
  51. package/dist/.dts/build/typescript.d.ts +3 -17
  52. package/dist/.dts/build/typescript.d.ts.map +1 -1
  53. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  54. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  55. package/dist/.dts/eslint-plugin/index.d.ts +1 -1
  56. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  57. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  58. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  59. package/dist/{build-H4KFV44Z.js → build-WKDIAWF7.js} +198 -60
  60. package/dist/build-WKDIAWF7.js.map +1 -0
  61. package/dist/build.cjs +194 -56
  62. package/dist/build.cjs.map +1 -1
  63. package/dist/build.js +194 -56
  64. package/dist/build.js.map +1 -1
  65. package/dist/{chunk-7GVPOHDU.js → chunk-KEGYUHBU.js} +2 -2
  66. package/dist/cli/index.js +36 -29
  67. package/dist/cli/index.js.map +1 -1
  68. package/dist/eslint-plugin/index.cjs +84 -54
  69. package/dist/eslint-plugin/index.cjs.map +1 -1
  70. package/dist/eslint-plugin/index.js +83 -53
  71. package/dist/eslint-plugin/index.js.map +1 -1
  72. package/examples/README.md +95 -0
  73. package/package.json +48 -14
  74. package/skills/env-cap/SKILL.md +91 -0
  75. package/skills/env-cap/references/api.md +220 -0
  76. package/specs/architecture.md +634 -0
  77. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  78. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  79. package/specs/decisions/0003-no-global-env-object.md +172 -0
  80. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  81. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  82. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  83. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  84. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  85. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  86. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  87. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  88. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  89. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  90. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  91. package/specs/decisions/0015-security-backport-window.md +60 -0
  92. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  93. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  94. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  95. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  96. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  97. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  98. package/specs/decisions/0022-validation-contexts.md +267 -0
  99. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  100. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  101. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  102. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  103. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  104. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  105. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  106. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  107. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  108. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  109. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  110. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  111. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  112. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  113. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  114. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  115. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  116. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  117. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  118. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  119. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  120. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  121. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  122. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  123. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  124. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  125. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  126. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  127. package/specs/generated-artifacts.md +104 -0
  128. package/specs/migrations/README.md +30 -0
  129. package/specs/migrations/from-centralized-schema.md +503 -0
  130. package/specs/migrations/from-dotenv.md +352 -0
  131. package/specs/migrations/from-envalid.md +482 -0
  132. package/specs/migrations/from-process-env.md +398 -0
  133. package/specs/migrations/from-t3-env.md +416 -0
  134. package/specs/migrations/from-zod.md +303 -0
  135. package/dist/build-H4KFV44Z.js.map +0 -1
  136. /package/dist/{chunk-7GVPOHDU.js.map → chunk-KEGYUHBU.js.map} +0 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,438 @@
1
+ # Changelog
2
+
3
+ ## 0.7.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 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.
8
+
9
+ ### Patch Changes
10
+
11
+ - 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.
12
+ - fix(site): readable inline code in the hero; record the brief link that goes live on deploy
13
+ - fix(security): commit the Socket registry in the form the check writes it
14
+ - fix(security): record the Socket alerts that only appear once a version is published
15
+ - feat(ci): publish the mutation badge and the OpenSSF Scorecard result
16
+ - fix(security): give every v2 Socket record an explicit expires
17
+ - 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.
18
+
19
+ ## 0.6.0
20
+
21
+ ### Minor Changes
22
+
23
+ - 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.
24
+
25
+ - 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`.
26
+ - 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.
27
+ - If the bundled compiler is stripped from an install, the scanner fails before writing anything, with a message that shows the alias to install.
28
+ - CI now installs the packed tarball beside TypeScript 5, 6 and 7 and runs the scanner from both the ESM and CJS entry points.
29
+
30
+ - 931e0d6: Audit fixes ahead of 1.0.
31
+
32
+ - 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).
33
+ - 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.
34
+ - Breaking (pre-1.0 minor): `init` scaffolds `docs/ENV-OWNERSHIP.md` so it can no longer collide with data-cap's `docs/OWNERSHIP.md`.
35
+ - 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.
36
+ - 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`.
37
+ - Source maps no longer embed `sourcesContent` (about 60% of the unpacked package).
38
+ - 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.
39
+ - Landing page: keyboard-focusable code blocks, a high-contrast theme toggle, forced-colors support.
40
+ - 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.
41
+
42
+ ### Patch Changes
43
+
44
+ - fix: do not mistake a broken typescript install for an absent one
45
+ - fix: run the compiler guard only when a tsconfig file exists
46
+ - fix(build): support TypeScript 6 and test both TypeScript lines (#55)
47
+ - fix(build): keep the sort after path mapping, the fingerprint fallback and the private-field check
48
+ - 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.
49
+
50
+ ## 0.5.3
51
+
52
+ ### Patch Changes
53
+
54
+ - 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.
55
+
56
+ ## 0.5.2
57
+
58
+ ### Patch Changes
59
+
60
+ - 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.
61
+
62
+ ## 0.5.1
63
+
64
+ ### Patch Changes
65
+
66
+ - chore(socket): drop the record for the minified-file alert that no longer applies
67
+ - 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.
68
+
69
+ ## 0.5.0
70
+
71
+ ### Minor Changes
72
+
73
+ - feat: sync internal-package-contract version automatically; centralize typedoc config (#24)
74
+ - feat(benchmark): extend coverage to helpers/evidence, add benchmarks nav link
75
+ - e84fa82: Migrates the benchmark pipeline onto internal-package-contract's shared
76
+ benchmark engine (PR #22): `scripts/append-benchmark-history.mjs` and
77
+ `scripts/render-benchmark-summary.mjs` are removed in favor of
78
+ internal-package-contract's own `append-history.mjs`/`render-summary.mjs`,
79
+ called from a new reusable `benchmark-pr` workflow
80
+ (`internal-package-contract/.github/workflows/benchmark-pr.yml`) that
81
+ replaces this repo's own inline job steps. Committed benchmark history moves
82
+ from `docs/benchmark-history/` to `benchmark/history/` (matching data-cap's
83
+ own convention) and gains a v2 schema that carries each tier's full `inputs`
84
+ alongside `medianMs`. The `deploy` job now also publishes a generated
85
+ `docs/benchmarks/index.html` history chart page, built fresh from
86
+ `render-page.mjs` on every deploy, never committed.
87
+
88
+ This is internal tooling only -- no change to any published runtime or
89
+ build-time API.
90
+
91
+ - 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).
92
+
93
+ 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).
94
+
95
+ 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.
96
+
97
+ - 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`.
98
+
99
+ 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.
100
+
101
+ - 5f4ca0f: Removes the `examples/nextjs-app` ISO 10007/ISO-IEC 27001 open-standard
102
+ alignment report generator (`scripts/open-config-alignment/`, the
103
+ `docs:alignment` script, and the two generated `docs/ISO-*.md` reports).
104
+ The generation logic behind these ISO-branded reports was never verified
105
+ against the real, licensed ISO standard text, creating real copyright/
106
+ mislabeling exposure -- this is a pure deletion, not a design change, and
107
+ no replacement generator is added in its place.
108
+
109
+ ### Patch Changes
110
+
111
+ - fix: stop relying on chmod for the evidence-cache unreadable-file test
112
+ - docs: regenerate api-report/build.md for the rotation-log schema additions
113
+ - fix: regenerate paypal-consumer's stale lockfile pin and golden fixtures
114
+ - chore(benchmarks): refresh results.json
115
+ - fix: stop golden fixtures hardcoding a calendar date that eventually expires
116
+ - chore(benchmarks): refresh results.json
117
+ - fix: regenerate tsconfig-aliases-consumer's stale lockfile pin
118
+ - chore(benchmarks): refresh results.json
119
+ - chore(benchmarks): refresh results.json
120
+ - chore(benchmarks): refresh results.json
121
+ - chore(benchmarks): refresh results.json
122
+ - chore(benchmarks): refresh results.json
123
+ - chore(benchmarks): refresh results.json
124
+ - chore: commit the first-ever api-contract baseline
125
+ - ci: run benchmarks before contract/lint, in one workflow, to stop the re-approval loop
126
+ - chore(benchmarks): refresh results.json
127
+ - chore(benchmarks): refresh results.json
128
+ - fix(size): recalibrate the helpers budget to unminified output
129
+ - chore(benchmarks): refresh results.json
130
+ - chore(benchmarks): refresh results.json
131
+ - fix(test): close mutation-coverage gap on the --evidence-only text output path
132
+ - chore: except a Stryker false-positive survivor in resolve-tsconfig-paths.ts
133
+ - chore(benchmarks): refresh results.json
134
+ - chore(benchmarks): refresh results.json
135
+ - chore(benchmarks): refresh results.json (132477d) (#22)
136
+ - chore(benchmarks): refresh results.json
137
+ - chore(benchmarks): refresh results.json
138
+ - chore(benchmarks): refresh results.json
139
+ - chore(benchmarks): refresh results.json
140
+ - fix: real CI for bot-authored branches; benchmark results land in the PR itself (#23)
141
+ - fix(scripts): update check-readme-example-fresh.mjs to the two-step docs flow
142
+ - 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.
143
+
144
+ ## 0.4.0
145
+
146
+ ### Minor Changes
147
+
148
+ - 69ff088: Exports `VariableEvidenceDocs` (previously an unexported internal
149
+ interface) from the package root, alongside the existing `ContractDocs`/
150
+ `VariableDocs` type exports.
151
+ - ab1f435: Wires `internal-package-contract`'s governance in for real (CI now runs the
152
+ full contract as a blocking gate, mutation testing ratcheted to zero
153
+ survived/no-coverage/timeout), adds ISO 10007 and ISO/IEC 27001
154
+ open-standard alignment reports, and adds a Next.js example demonstrating
155
+ the client/server environment boundary.
156
+ - 69ff088: Promotes every remaining Experimental-tier surface to Stable (ADR 0045):
157
+ the `packages`/`tsconfig` generator options, `env-cap/build`'s lower-level
158
+ discovery/linking primitives, `generateEvidenceModel`/`getEvidenceModel`/
159
+ `computeSourceFingerprint`/`renderUsageReport`, the `init` CLI subcommand,
160
+ `env-cap/evidence`, and the persisted evidence artifact format. No behavior
161
+ change -- this is a compatibility commitment change only. The Experimental
162
+ tier remains defined in `VERSIONING.md` for future genuinely-new surfaces;
163
+ nothing currently ships under it.
164
+
165
+ **Named caveat** (see ADR 0045): `env-cap/evidence`'s `EvidenceProjectionResult.sources`
166
+ had a specific, previously-documented open design question about its shape
167
+ (flat field-path strings vs. structured `EvidenceReference`s) that is not
168
+ yet resolved. It is promoted along with everything else for one consistent
169
+ fleet-wide policy, but a future shape change there is now a real Stable-tier
170
+ breaking change, not a minor-may-break Experimental adjustment.
171
+
172
+ - 69ff088: **Breaking, pre-1.0 (any Stable API may change in a minor per VERSIONING.md):**
173
+ bare `--strict` now escalates every warning family (compatibility, documentation,
174
+ ownership) to a hard error, not just manifest compatibility (ADR 0044). This
175
+ matches `data-cap`'s own `--strict`, which already escalates
176
+ every pass. `--strict-docs`/`--strict-ownership` are unchanged and still work
177
+ independently. A CI script relying on bare `--strict` _not_ escalating
178
+ documentation/ownership warnings needs to switch to the scoped flags (or fix
179
+ the newly-escalated findings).
180
+
181
+ ### Patch Changes
182
+
183
+ - 69ff088: Fixes the bundled GitHub Action (`action.yml`) referencing the unscoped
184
+ package name `env-cap`, which does not exist on the public npm registry --
185
+ only the published `@maverickcer/env-cap` does. Any workflow using this
186
+ Action via `npx --yes` (its documented fetch path) 404'd. Also clarifies
187
+ the `args` input's description to mention `--evidence`.
188
+ - 69ff088: Fixes `env-cap init` and `env-cap --help` throwing
189
+ `ERR_MODULE_NOT_FOUND: Cannot find package 'typescript'` on a fresh install
190
+ with no `typescript` present. `typescript` is an optional peer dependency
191
+ (only required for build-time manifest generation), but a static top-level
192
+ import of `../build/index.js` was evaluated eagerly for every CLI
193
+ invocation, including the two commands that never touch it. `../build/index.js`
194
+ is now loaded with a dynamic `import()` inside `runCheckMode`/`runGenerateMode`
195
+ only.
196
+
197
+ ## 0.3.1
198
+
199
+ ### Patch Changes
200
+
201
+ - 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).
202
+
203
+ Also pins `tar` to `^7.5.22` (a critical hardlink/symlink-traversal CVE, non-breaking fix).
204
+
205
+ ## 0.3.0
206
+
207
+ ### Minor Changes
208
+
209
+ - 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.
210
+
211
+ ### Patch Changes
212
+
213
+ - 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"`.
214
+
215
+ ## 0.2.0
216
+
217
+ ### Minor Changes
218
+
219
+ - 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).
220
+ - 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).
221
+ - 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.
222
+ - Rename `documentEnv()`'s `ContractDocs.name` field to `displayName`. `name` collided with
223
+ `createEnv()`'s unrelated `CreateEnvOptions.name` (a runtime error-message label) -- same word,
224
+ different meaning, on the same conceptual contract. `ContractDocs.name` is removed, not deprecated
225
+ or aliased, because the collision is the reason for this change and aliasing would leave it
226
+ half-fixed.
227
+
228
+ This is a **breaking change to a Stable-tier TypeScript API** (`documentEnv`'s `ContractDocs`
229
+ parameter -- `documentEnv` itself is listed under VERSIONING.md's Stable tier). It ships as a
230
+ `minor` release only because `env-cap` is pre-1.0 and VERSIONING.md's major-bump requirement is
231
+ explicitly scoped to "once the package reaches 1.0" -- `minor` here does not mean non-breaking.
232
+ `documentEnv()` is a no-op at runtime (ADR 0001), so the only real-world impact is a TypeScript
233
+ compile error at an existing `{ name: ... }` call site, never a behavior change. Migration: rename
234
+ `name` to `displayName` in any `documentEnv()` call that sets it.
235
+
236
+ - 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.
237
+ - 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).
238
+ - 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.
239
+ - 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.
240
+ - `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).
241
+ - 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.
242
+ - Finish wiring `classification` through the pipeline, matching the treatment its sibling
243
+ documentation fields (`owner`, `purpose`, `legalBasis`, `retentionPolicy`, `dataResidency`,
244
+ `auditRequired`) already get: a new `effectiveClassification()` helper (`env-cap/build`,
245
+ internal like its siblings other than `effectiveOwner()`) resolves a variable's own classification,
246
+ falling back to its contract's; the effective value now renders as a `- Classification:` line in
247
+ generated docs and appears on `CatalogContract`/`CatalogVariable`'s JSON shape (a purely additive
248
+ field); and two documented declarations of the same variable that disagree on `classification` now
249
+ produce a `duplicate-variable-documentation` compatibility warning, the same as an `owner`/
250
+ `description` mismatch already does -- this can surface a _new_ warning for a project whose
251
+ contracts already silently disagree on classification, worth checking before enabling
252
+ `onIncompatibility: "throw"`.
253
+ - 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).
254
+ - 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()`).
255
+ - 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.
256
+ - Rename two `FindingCode` values to match the adjective-first word order every other code in the
257
+ union uses: `"dynamic-access-citation-missing"` -> `"missing-dynamic-access-citation"`, and
258
+ `"dynamic-access-citation-stale"` -> `"stale-dynamic-access-citation"`. `FINDING_MODEL_SCHEMA_VERSION`
259
+ bumped from 1 to 2. This is a rename, not an additive union member -- the old strings are no
260
+ longer produced anywhere. `FindingModel`/`EvidenceModel` are Experimental (VERSIONING.md), so this
261
+ ships without a major bump; a consumer matching on these exact `code` strings (in a projection, CI
262
+ filter, or dashboard) needs to update them.
263
+ - 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).
264
+ - 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.
265
+ - Add "Joined Variable View" as an eleventh first-party reference projection, alongside the original
266
+ ten from ADR 0024, in `test/integration/positive/enterprise/evidence-projections/`
267
+ (`projections/joined-variables.mjs`). One row per declared variable, joining Contract Model,
268
+ Dependency Model, and Lifecycle Model by `${file}#${exportName}#${key}` identity, with a fixed and
269
+ documented field list -- a working, copyable example of the cross-model join every one of the
270
+ other ten projections performs its own version of, for a `defineEvidenceProjection()` author to
271
+ start from instead of re-deriving it. Shipped as an example, not a package export -- see ADR
272
+ 0033's "Alternatives considered" on why a public entry point exporting ready-made projections was
273
+ rejected; this doesn't reopen that decision.
274
+ - 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).
275
+ - 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)).
276
+
277
+ 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.
278
+
279
+ - 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.
280
+ - 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).
281
+ - 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`.
282
+
283
+ 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.
284
+
285
+ - 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).
286
+ - 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`).
287
+ - 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.
288
+ - 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.
289
+ - 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).
290
+
291
+ ### Patch Changes
292
+
293
+ - 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.
294
+ - Generated docs (`renderDocs()`/`--docs`) and the dependency & ownership report
295
+ (`renderUsageReport()`/`--ownership`) now each print a one-line "Produced by `env-cap --docs`"/
296
+ "Produced by `env-cap --ownership`" note under their heading, so the generated file itself names
297
+ the CLI flag that produced it. Purely additive Markdown; no shape change, no CLI/API change.
298
+ - 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).
299
+ - 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.
300
+ - 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.
301
+ - 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.
302
+ - 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.
303
+ - 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.
304
+
305
+ All notable changes to this project will be documented in this file.
306
+
307
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
308
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
309
+ once it reaches 1.0. Before 1.0, minor versions may include breaking changes.
310
+
311
+ ## [0.1.0] - 2026-08-02
312
+
313
+ Carried over from the legacy hand-kept `[Unreleased]` block that sat above this release:
314
+
315
+ - Build: **Experimental** TypeScript path-alias resolution -- a new `tsconfig`
316
+ option (and CLI `--tsconfig <path>` / `--no-tsconfig`) on `generateEnvManifest()`/
317
+ `generateDocumentation()`/`generateUsageReport()`/`generateEnvArtifacts()` resolves
318
+ import specifiers written as `tsconfig.json` path aliases (`"@/lib/env"`) during
319
+ static analysis, so a contract or `documentEnv()` call reached only through an alias
320
+ isn't misreported as abandoned/unresolved in the manifest, docs, or Dependency &
321
+ Ownership Report. Unlike `packages` (ADR 0014), this is on by default -- `tsconfig.json`
322
+ at `root` is auto-detected, matching `tsc`'s own behavior, since a project's own
323
+ tsconfig never crosses the trust/versioning boundary an installed package does. See
324
+ [ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md) and
325
+ [`VERSIONING.md`](VERSIONING.md) for the Experimental-surface policy this ships under.
326
+ `examples/tsconfig-aliases` demonstrates it end to end, including the ownership-report
327
+ false positive it fixes; `examples/tsconfig-aliases-consumer` additionally installs it as
328
+ a real package (a real packed tarball, same shape as `examples/paypal-consumer`) to prove
329
+ this composes correctly with cross-package discovery (ADR 0014) in one run.
330
+
331
+ Initial release.
332
+
333
+ - Runtime: `createEnv()` / `validateEnv()` / `documentEnv()` -- capability-owned,
334
+ lazily-resolved environment contracts with no global env object.
335
+ - Build: `generateEnvManifest()` / `generateDocumentation()` / `generateUsageReport()` /
336
+ `generateEnvArtifacts()` -- static AST discovery and artifact generation, never
337
+ importing or executing schema files.
338
+ - Helpers: `@maverickcer/env-cap/helpers` -- optional, tree-shakeable
339
+ processor/validator convenience functions.
340
+ - CLI: `npx env-cap` for CI/release-pipeline artifact generation.
341
+ - CLI: a published JSON Schema for `--json` output (`schemas/env-cap-report.schema.json`,
342
+ also exported as `@maverickcer/env-cap/schema`) for external, non-TypeScript
343
+ tooling to validate or codegen against -- generated directly from
344
+ `src/cli/json.ts`'s types, never hand-authored, so the two can't silently
345
+ drift apart. See [ADR 0019](specs/decisions/0019-published-json-schema-generated-from-types.md).
346
+ - GitHub Action: a new `rotation-alert` input (default `true`) opens/updates a
347
+ GitHub issue -- and auto-closes it once resolved -- when a run has no PR to
348
+ comment on (a `schedule`/`workflow_dispatch`/plain-`push` trigger) and finds
349
+ an expiring or expired variable, so a dormant repository still gets a real,
350
+ emailed alert. See [ADR 0018](specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md).
351
+ - ESLint: new `@maverickcer/env-cap/eslint-plugin` subpath export, a
352
+ `no-raw-process-env` rule that flags direct `process.env` access outside a
353
+ capability's own `env.schema.ts`, with an `allow` glob-list escape hatch for
354
+ legitimate build-time bootstrap code (e.g. a resolver reading a raw
355
+ `VAULT_TOKEN` to authenticate to a secrets manager before any contract
356
+ exists to go through). See [ADR 0017](specs/decisions/0017-eslint-plugin-entry-point.md).
357
+ - CLI: new `--check` flag verifies every requested artifact (manifest/docs/
358
+ `.env.example`/ownership report) is up to date without writing anything --
359
+ a CI drift guard for a schema change that forgot a local regeneration.
360
+ `--json`'s envelope gains an additive `checkResult: { ok, stale }` field.
361
+ See [ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md).
362
+ - CLI: a leading `⚠ N unresolved/dropped-schema warning(s) found` banner
363
+ prints before the rest of a non-JSON run's output whenever a schema
364
+ couldn't be statically resolved -- purely additive visibility, no change
365
+ to exit-code semantics.
366
+ - Docs: SECURITY.md commits to a concrete post-1.0 security-backport policy (latest
367
+ minor of the previous major, minimum six months after a new major ships, extendable
368
+ but never shortened once stated) -- see
369
+ [ADR 0015](specs/decisions/0015-security-backport-window.md).
370
+ - Build: `GenerateDocumentationResult.catalog` -- the full per-variable documentation
371
+ content (description, owner, `expiresAt`, `extra` metadata, ...) alongside the
372
+ existing `contracts` summary, keyed by variable name within each contract.
373
+ - CLI: `--json` flag emits a versioned, machine-readable report (`{ schemaVersion,
374
+ kind, toolVersion, ok, ... }`) instead of formatted text, for CI checks, PR
375
+ annotations, and dashboards. Exit-code semantics are unchanged.
376
+ - GitHub Action: a first-party, dependency-free composite Action (`action.yml`) runs
377
+ the CLI with `--json` and turns the result into inline PR annotations and a sticky
378
+ summary comment.
379
+ - Build: **Experimental** cross-package schema discovery -- a new `packages`
380
+ option (and CLI `--package <name>`, repeatable) on `generateEnvManifest()`/
381
+ `generateDocumentation()`/`generateUsageReport()`/`generateEnvArtifacts()` lets a
382
+ project discover a schema that ships inside a separately-published, installed
383
+ package via an explicit allowlist, never an implicit scan of `node_modules`. See
384
+ [ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md) and
385
+ [`VERSIONING.md`](VERSIONING.md) for the Experimental-surface policy this ships
386
+ under. `examples/paypal-addon`/`examples/paypal-consumer` now demonstrate it
387
+ against a real packed tarball, not a monorepo-sibling workaround.
388
+ - Docs: `GenerateUsageReportResult` gains `parseWarnings`, surfacing schema-discovery
389
+ and package-resolution warnings from the `--ownership`/usage pass, matching the
390
+ other two generators (purely additive; no `schemaVersion` bump per ADR 0013).
391
+ - New `VERSIONING.md` codifying the stable/Experimental/private semver scope, and
392
+ `ADOPTION.md` synthesizing the security model, versioning stance, and migration
393
+ cost for technical decision-makers.
394
+ - README: runtime support matrix, a Troubleshooting section keyed by exported error
395
+ class, and a "Reusable packages" section documenting cross-package discovery.
396
+ - Specs: backfilled [ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md)
397
+ (dependency-ownership engine's scope boundary) and
398
+ [ADR 0011](specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md)
399
+ (shared discovery, compute-atomic but not write-atomic `generateEnvArtifacts()`),
400
+ both already-implemented decisions that were referenced by number but never
401
+ written down until now.
402
+ - Governance: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1),
403
+ `CODEOWNERS`, and tailored issue/PR templates.
404
+ - CI: GitHub Actions pinned to commit SHAs; Node matrix refreshed to currently
405
+ maintained LTS lines (`18.x`/`22.x`/`24.x` required, `26.x` Current as a
406
+ non-blocking signal) while `engines.node` stays `>=18.0.0`, unchanged, since
407
+ nothing in the code requires newer; a new cross-runtime job runs the same
408
+ conformance suite under Bun and Deno's own native test runners, not just
409
+ Node/vitest; an `examples` job installs and typechecks/runs all seven
410
+ reference examples against the real, just-built package.
411
+ - Adopted `@typescript-eslint`'s `strict-type-checked` + `stylistic-type-checked`
412
+ ESLint configuration (`npm run lint`, its own step in CI) with
413
+ every finding fixed or explicitly, narrowly justified -- including two real bugs
414
+ this caught: an untyped `new Map()` fallback that silently widened a chain of
415
+ values to `any`, and `EnvContract`'s type not declaring the `toString()` override
416
+ `create.ts` actually implements.
417
+ - `vitest.config.ts` now enforces coverage thresholds (lines/branches/functions/
418
+ statements) in CI, not just locally informational reporting.
419
+ - Runtime/build error classes (`EnvValidationError`, `EnvNotReadyError`,
420
+ `EnvManifestGenerationError`, `EnvDocumentationGenerationError`,
421
+ `EnvUsageAnalysisError`, `EnvProjectGenerationError`) gain a stable, Stable-tier
422
+ `code` field for programmatic handling that doesn't depend on `.name`/`instanceof`.
423
+ - Release: adopted [Changesets](https://github.com/changesets/changesets) plus a
424
+ new `release.yml` workflow publishing via npm's OIDC trusted publishing -- no
425
+ `NPM_TOKEN` secret, provenance-attested by default. See `CONTRIBUTING.md`'s
426
+ release-process section for the one-time, human-only npmjs.com setup step this
427
+ requires.
428
+ - Website: dark mode (follows `prefers-color-scheme`, overridable via a new header
429
+ toggle, persisted); a dependency-free `Cmd+K`/`Ctrl+K` search over the page's own
430
+ sections and FAQ entries; an `aria-live` announcement for the copy-button
431
+ confirmation; a fixed borderline (~4.55:1) muted-text contrast token to ~7.2-7.6:1;
432
+ named links to specific ADRs from the Security and Adoption sections instead of a
433
+ generic repository link; `sitemap.xml` plus a `Sitemap:` line in `robots.txt`;
434
+ a Getting Started mention of the ESLint plugin and `--json`/`--check`; removed
435
+ several leftover, never-referenced CSS classes (`.card`, `.callout--warning`,
436
+ `.callout--success`, `.comparison-table .is-positive`).
437
+
438
+ [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