@maverickcer/env-cap 0.7.3 → 0.7.5

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 (238) hide show
  1. package/ADOPTION.md +106 -124
  2. package/AGENTS.md +14 -13
  3. package/CHANGELOG.md +23 -0
  4. package/CODE_REVIEW.md +69 -173
  5. package/CONTRIBUTING.md +57 -74
  6. package/GUIDE.md +393 -872
  7. package/README.md +82 -77
  8. package/RELEASING.md +17 -15
  9. package/SECURITY.md +76 -227
  10. package/SUPPORT.md +21 -45
  11. package/VERSIONING.md +68 -105
  12. package/benchmarks/READING-BENCHMARKS.md +13 -7
  13. package/benchmarks/WRITING-BENCHMARKS.md +1 -1
  14. package/dist/.dts/_ipc/build-fs.d.ts +9 -14
  15. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  16. package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
  17. package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
  19. package/dist/.dts/_ipc/glob.d.ts +6 -6
  20. package/dist/.dts/_ipc/no-node-fs.d.ts +0 -14
  21. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
  22. package/dist/.dts/build/lifecycle-model.d.ts +8 -3
  23. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  24. package/dist/.dts/build/sarif.d.ts.map +1 -1
  25. package/dist/.dts/helpers/index.d.ts +1 -1
  26. package/dist/.dts/runtime/create.d.ts +3 -0
  27. package/dist/.dts/runtime/create.d.ts.map +1 -1
  28. package/dist/.dts/runtime/document.d.ts +7 -4
  29. package/dist/.dts/runtime/document.d.ts.map +1 -1
  30. package/dist/.dts/runtime/index.d.ts +11 -10
  31. package/dist/.dts/runtime/index.d.ts.map +1 -1
  32. package/dist/.dts/runtime/types.d.ts +16 -0
  33. package/dist/.dts/runtime/types.d.ts.map +1 -1
  34. package/dist/.dts/runtime/validate.d.ts +14 -1
  35. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  36. package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
  37. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
  38. package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
  39. package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
  40. package/dist/.dts7/_ipc/display-path.d.ts +27 -0
  41. package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
  42. package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
  43. package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
  44. package/dist/.dts7/_ipc/glob.d.ts +22 -0
  45. package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
  46. package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
  47. package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
  48. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  49. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  50. package/dist/.dts7/_ipc/typescript.d.ts +20 -0
  51. package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
  52. package/dist/.dts7/build/assemble-project.d.ts +47 -0
  53. package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
  54. package/dist/.dts7/build/change-model.d.ts +63 -0
  55. package/dist/.dts7/build/change-model.d.ts.map +1 -0
  56. package/dist/.dts7/build/check-artifacts.d.ts +48 -0
  57. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
  58. package/dist/.dts7/build/citation-verification.d.ts +62 -0
  59. package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
  60. package/dist/.dts7/build/compatibility.d.ts +83 -0
  61. package/dist/.dts7/build/compatibility.d.ts.map +1 -0
  62. package/dist/.dts7/build/compiler-api.d.ts +12 -0
  63. package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
  64. package/dist/.dts7/build/contract-model.d.ts +93 -0
  65. package/dist/.dts7/build/contract-model.d.ts.map +1 -0
  66. package/dist/.dts7/build/deep-equal.d.ts +9 -0
  67. package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
  68. package/dist/.dts7/build/deep-freeze.d.ts +20 -0
  69. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
  70. package/dist/.dts7/build/dependency-graph.d.ts +170 -0
  71. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
  72. package/dist/.dts7/build/dependency-model.d.ts +81 -0
  73. package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
  74. package/dist/.dts7/build/discover.d.ts +41 -0
  75. package/dist/.dts7/build/discover.d.ts.map +1 -0
  76. package/dist/.dts7/build/display-path.d.ts +6 -0
  77. package/dist/.dts7/build/display-path.d.ts.map +1 -0
  78. package/dist/.dts7/build/docs.d.ts +176 -0
  79. package/dist/.dts7/build/docs.d.ts.map +1 -0
  80. package/dist/.dts7/build/env-example.d.ts +85 -0
  81. package/dist/.dts7/build/env-example.d.ts.map +1 -0
  82. package/dist/.dts7/build/errors.d.ts +78 -0
  83. package/dist/.dts7/build/errors.d.ts.map +1 -0
  84. package/dist/.dts7/build/evidence-cache.d.ts +74 -0
  85. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
  86. package/dist/.dts7/build/evidence-model.d.ts +50 -0
  87. package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
  88. package/dist/.dts7/build/evidence-reference.d.ts +67 -0
  89. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
  90. package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
  91. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
  92. package/dist/.dts7/build/exclusive-group.d.ts +19 -0
  93. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
  94. package/dist/.dts7/build/finding-model.d.ts +80 -0
  95. package/dist/.dts7/build/finding-model.d.ts.map +1 -0
  96. package/dist/.dts7/build/generate-documentation.d.ts +176 -0
  97. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
  98. package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
  99. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
  100. package/dist/.dts7/build/generate-evidence.d.ts +77 -0
  101. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
  102. package/dist/.dts7/build/generate-manifest.d.ts +101 -0
  103. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
  104. package/dist/.dts7/build/generate-usage.d.ts +95 -0
  105. package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
  106. package/dist/.dts7/build/generated-banner.d.ts +43 -0
  107. package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
  108. package/dist/.dts7/build/glob.d.ts +6 -0
  109. package/dist/.dts7/build/glob.d.ts.map +1 -0
  110. package/dist/.dts7/build/governance-fields.d.ts +34 -0
  111. package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
  112. package/dist/.dts7/build/humanize-key.d.ts +14 -0
  113. package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
  114. package/dist/.dts7/build/index.d.ts +105 -0
  115. package/dist/.dts7/build/index.d.ts.map +1 -0
  116. package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
  117. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
  118. package/dist/.dts7/build/link.d.ts +223 -0
  119. package/dist/.dts7/build/link.d.ts.map +1 -0
  120. package/dist/.dts7/build/literal-eval.d.ts +24 -0
  121. package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
  122. package/dist/.dts7/build/live-expirations.d.ts +47 -0
  123. package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
  124. package/dist/.dts7/build/manifest.d.ts +31 -0
  125. package/dist/.dts7/build/manifest.d.ts.map +1 -0
  126. package/dist/.dts7/build/map-utils.d.ts +8 -0
  127. package/dist/.dts7/build/map-utils.d.ts.map +1 -0
  128. package/dist/.dts7/build/merge-documentation.d.ts +35 -0
  129. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
  130. package/dist/.dts7/build/ownership-model.d.ts +59 -0
  131. package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
  132. package/dist/.dts7/build/parse.d.ts +207 -0
  133. package/dist/.dts7/build/parse.d.ts.map +1 -0
  134. package/dist/.dts7/build/reference-projections.d.ts +170 -0
  135. package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
  136. package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
  137. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
  138. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
  139. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
  140. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
  141. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
  142. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
  143. package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
  144. package/dist/.dts7/build/sarif.d.ts +66 -0
  145. package/dist/.dts7/build/sarif.d.ts.map +1 -0
  146. package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
  147. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
  148. package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
  149. package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
  150. package/dist/.dts7/build/source-position.d.ts +69 -0
  151. package/dist/.dts7/build/source-position.d.ts.map +1 -0
  152. package/dist/.dts7/build/tool-version.d.ts +8 -0
  153. package/dist/.dts7/build/tool-version.d.ts.map +1 -0
  154. package/dist/.dts7/build/types.d.ts +7 -0
  155. package/dist/.dts7/build/types.d.ts.map +1 -0
  156. package/dist/.dts7/build/typescript.d.ts +6 -0
  157. package/dist/.dts7/build/typescript.d.ts.map +1 -0
  158. package/dist/.dts7/build/usage-report.d.ts +124 -0
  159. package/dist/.dts7/build/usage-report.d.ts.map +1 -0
  160. package/dist/.dts7/cli/filesystem.d.ts +7 -0
  161. package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
  162. package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
  163. package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
  164. package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
  165. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
  166. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
  167. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
  168. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
  169. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
  170. package/dist/.dts7/evidence/define-projection.d.ts +52 -0
  171. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
  172. package/dist/.dts7/evidence/index.d.ts +23 -0
  173. package/dist/.dts7/evidence/index.d.ts.map +1 -0
  174. package/dist/.dts7/helpers/index.d.ts +135 -0
  175. package/dist/.dts7/helpers/index.d.ts.map +1 -0
  176. package/dist/.dts7/helpers/processors.d.ts +32 -0
  177. package/dist/.dts7/helpers/processors.d.ts.map +1 -0
  178. package/dist/.dts7/helpers/validators.d.ts +68 -0
  179. package/dist/.dts7/helpers/validators.d.ts.map +1 -0
  180. package/dist/.dts7/node/index.d.ts +2 -0
  181. package/dist/.dts7/node/index.d.ts.map +1 -0
  182. package/dist/.dts7/runtime/cache.d.ts +17 -0
  183. package/dist/.dts7/runtime/cache.d.ts.map +1 -0
  184. package/dist/.dts7/runtime/create.d.ts +23 -0
  185. package/dist/.dts7/runtime/create.d.ts.map +1 -0
  186. package/dist/.dts7/runtime/document.d.ts +223 -0
  187. package/dist/.dts7/runtime/document.d.ts.map +1 -0
  188. package/dist/.dts7/runtime/errors.d.ts +55 -0
  189. package/dist/.dts7/runtime/errors.d.ts.map +1 -0
  190. package/dist/.dts7/runtime/index.d.ts +25 -0
  191. package/dist/.dts7/runtime/index.d.ts.map +1 -0
  192. package/dist/.dts7/runtime/registry.d.ts +12 -0
  193. package/dist/.dts7/runtime/registry.d.ts.map +1 -0
  194. package/dist/.dts7/runtime/reset.d.ts +8 -0
  195. package/dist/.dts7/runtime/reset.d.ts.map +1 -0
  196. package/dist/.dts7/runtime/types.d.ts +191 -0
  197. package/dist/.dts7/runtime/types.d.ts.map +1 -0
  198. package/dist/.dts7/runtime/validate.d.ts +27 -0
  199. package/dist/.dts7/runtime/validate.d.ts.map +1 -0
  200. package/dist/{build-LFHPVDQL.js → build-DNAYWD2B.js} +8 -5
  201. package/dist/build-DNAYWD2B.js.map +1 -0
  202. package/dist/build.cjs +7 -4
  203. package/dist/build.cjs.map +1 -1
  204. package/dist/build.js +7 -4
  205. package/dist/build.js.map +1 -1
  206. package/dist/build.ts7.d.cts +1 -0
  207. package/dist/build.ts7.d.ts +1 -0
  208. package/dist/{chunk-ZW3BLAPD.js → chunk-HAGMVMN5.js} +2 -2
  209. package/dist/cli/index.js +3 -3
  210. package/dist/eslint-plugin/index.cjs +8 -5
  211. package/dist/eslint-plugin/index.cjs.map +1 -1
  212. package/dist/eslint-plugin/index.js +8 -5
  213. package/dist/eslint-plugin/index.js.map +1 -1
  214. package/dist/eslint-plugin/index.ts7.d.cts +1 -0
  215. package/dist/eslint-plugin/index.ts7.d.ts +1 -0
  216. package/dist/evidence.ts7.d.cts +1 -0
  217. package/dist/evidence.ts7.d.ts +1 -0
  218. package/dist/helpers.ts7.d.cts +1 -0
  219. package/dist/helpers.ts7.d.ts +1 -0
  220. package/dist/index.cjs.map +1 -1
  221. package/dist/index.js.map +1 -1
  222. package/dist/index.ts7.d.cts +1 -0
  223. package/dist/index.ts7.d.ts +1 -0
  224. package/dist/node.ts7.d.cts +1 -0
  225. package/dist/node.ts7.d.ts +1 -0
  226. package/examples/README.md +46 -80
  227. package/package.json +37 -6
  228. package/schemas/env-cap-report.schema.json +1 -1
  229. package/skills/env-cap/SKILL.md +1 -1
  230. package/skills/env-cap/references/api.md +1 -1
  231. package/specs/architecture.md +2 -2
  232. package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
  233. package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
  234. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
  235. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
  236. package/specs/generated-artifacts.md +14 -2
  237. package/dist/build-LFHPVDQL.js.map +0 -1
  238. /package/dist/{chunk-ZW3BLAPD.js.map → chunk-HAGMVMN5.js.map} +0 -0
package/VERSIONING.md CHANGED
@@ -1,118 +1,81 @@
1
1
  # Versioning and API stability
2
2
 
3
- `env-cap` follows [Semantic Versioning](https://semver.org/). This document
4
- defines what that promise actually covers, since "semver" alone doesn't say
5
- which surface it applies to. Three tiers exist:
6
-
7
- ## Stable
8
-
9
- Covered by semver. A breaking change to any of the following requires a
10
- major version bump (once the package reaches 1.0 -- see
11
- [Pre-1.0 status](#pre-10-status) below):
12
-
13
- - **Public runtime APIs**: `createEnv`, `validateEnv`, `documentEnv`,
14
- `resetEnvCache`, `isEnvContract`, and the exported error classes
15
- (`EnvValidationError`, `EnvNotReadyError`) from the package root.
16
- - **Documented build APIs**: `generateEnvManifest`, `generateDocumentation`,
17
- `generateUsageReport`, `generateEnvArtifacts` and their documented
18
- options, from `@maverickcer/env-cap/build`.
19
- - **`@maverickcer/env-cap/node`** (`nodeBuildFileSystem`): the only sanctioned way to give
20
- `./build` a filesystem, and required by every generator script `init` scaffolds.
21
- - **CLI flags**: every flag listed in `env-cap --help`, and the CLI's exit codes.
22
- - **`--json` output**: versioned independently via its own `schemaVersion`
23
- field -- see [ADR 0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md).
24
- A purely additive field never requires a `schemaVersion` bump; a changed
25
- or removed field does.
26
- - **The published JSON Schema** (`schemas/env-cap-report.schema.json`, the
27
- `@maverickcer/env-cap/schema` export), kept in lockstep with `--json`'s
28
- documented shape and generated directly from it -- see
29
- [ADR 0019](specs/decisions/0019-published-json-schema-generated-from-types.md).
30
- Follows the same additive-only rule as `--json` itself.
31
- - **The generated manifest schema**: the shape of the file
32
- `generateEnvManifest()`/`generateEnvArtifacts()` writes.
33
- - **Documented configuration conventions**: for example, the `envCap.schema`
34
- package.json field (see [ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md)).
35
- - **The ESLint plugin**: `@maverickcer/env-cap/eslint-plugin`'s exported rule
36
- name(s), each rule's `RuleOptions` shape, and the default `env.schema.ts`/
37
- `.tsx` allowlist -- see [ADR 0017](specs/decisions/0017-eslint-plugin-entry-point.md).
38
- - **The `packages` option** (cross-package schema discovery, ADR 0014) and
39
- **`tsconfig` option** (TypeScript path-alias resolution, ADR 0023) on every
40
- generator.
41
- - **`@maverickcer/env-cap/build`'s lower-level discovery/linking primitives** --
42
- everything `./build` exports beyond the four generator orchestrators,
43
- e.g. `discoverSchemaFiles`, `linkFiles`, `parseSchemaFile`, `renderManifest`,
44
- `renderDocs`, `detectCompatibilityIssues`, `detectExclusiveGroupIssues`,
45
- `generateEvidenceModel`, `getEvidenceModel`/`computeSourceFingerprint`,
46
- `renderUsageReport`, and their accompanying types.
47
- - **`@maverickcer/env-cap/evidence`** (`defineEvidenceProjection`, and the `EvidenceModel`
48
- shape it projects over) -- see [ADR 0031](specs/decisions/0031-evidence-entry-point.md)
49
- and [ADR 0032](specs/decisions/0032-evidence-projection-provenance-mechanism.md).
50
- - **The persisted evidence artifact** (`docs/env.evidence.json` or wherever a
51
- project's `evidence.location`/`--evidence <path>` points) -- a direct,
52
- literal serialization of `EvidenceModel`.
53
- - **The `init` CLI subcommand**'s scaffolded file set and template contents
54
- -- see [ADR 0042](specs/decisions/0042-init-cli-subcommand-scaffolds-only.md).
55
- - **The composite GitHub Action** (`action.yml`): its input and output names and meanings, and
56
- the PR comment's sections. The major tag it is used through (`uses: MaverickCER/env-cap@v0`
57
- while the package is 0.x, `@v1` from 1.0.0) moves only within a major version.
58
- - **Supported toolchain**: Node.js `>=22`, `moduleResolution` `node16`/`nodenext`/`bundler` (not the legacy
59
- `node10`, which cannot resolve subpath exports), and the TypeScript versions named in the
60
- `typescript` peer range (`^5 || ^6 || ^7`). The build-time scanner needs TypeScript's classic
61
- compiler API, which TypeScript 7 does not ship, so it uses the consumer's `typescript` when that has
62
- the API and otherwise the bundled `@typescript/typescript6` dependency -- no configuration, and `tsc`
63
- stays TypeScript 7 ([ADR 0049](specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md)).
64
- Under TypeScript 7 the `./build` and `./evidence` declarations need `skipLibCheck`; the runtime,
65
- helpers and node entry points type-check strictly.
66
-
67
- All promoted from Experimental per [ADR 0045](specs/decisions/0045-promote-experimental-surfaces-to-stable.md)
68
- -- see that ADR for why each one had already cleared this tier's own
69
- graduation criterion (below).
3
+ Every entry point is Stable, and two baseline checks enforce the release level a change needs. Before 1.0, a breaking change needs only a minor release. `env-cap` follows [Semantic Versioning](https://semver.org/).
4
+
5
+ ## Tiers
6
+
7
+ | Tier | What a release may do | Enforced by |
8
+ | ------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
9
+ | Stable | A breaking change needs a major release from 1.0 (a minor before 1.0) | `ApiContract` and `SurfaceContract` diff against committed baselines and require a matching changeset |
10
+ | Experimental | May change shape in any release, including a patch | Labelled in this document, the option's TSDoc and its ADR. Nothing ships Experimental today |
11
+ | Private | May change at any time without notice | Not exported from `package.json#exports`; no check needed |
12
+
13
+ ## Every entry point and its tier
14
+
15
+ Generated from `package.json#exports` and `docs/surface.json` by `internal-package-contract generate`; the `GeneratedRegions` check fails if it is stale.
16
+
17
+ <!-- ipc:begin entry-points -->
18
+
19
+ | Export | Source | Environment | Tier | Purpose |
20
+ | ------------------------------------ | -------------------- | ------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
21
+ | `@maverickcer/env-cap` | `src/runtime/` | No Node module or Node global | Stable | `createEnv`, `documentEnv`, `validateEnv`, `resetEnvCache`, `isEnvContract` and the error types |
22
+ | `@maverickcer/env-cap/build` | `src/build/` | Node only, in development and CI | Stable | Discovery, AST analysis and artifact generation. The four `generate*()` orchestrators and the lower-level primitives are Stable (ADR 0045, `VERSIONING.md`). |
23
+ | `@maverickcer/env-cap/helpers` | `src/helpers/` | No Node module; `processors.base64()` returns a Node `Buffer` | Stable | `processors` and `validators` |
24
+ | `@maverickcer/env-cap/node` | `src/node/` | Node only, in development and CI | Stable | `nodeBuildFileSystem`, the `BuildFileSystem` adapter a build script hands to `./build` |
25
+ | `@maverickcer/env-cap/evidence` | `src/evidence/` | No Node module or Node global | Stable | `defineEvidenceProjection`, pure transforms over the Evidence Model (Stable, see `VERSIONING.md`) |
26
+ | `@maverickcer/env-cap/eslint-plugin` | `src/eslint-plugin/` | Node only, inside the project's ESLint | Stable | The `no-raw-process-env` and `no-node-fs` lint rules |
27
+ | `@maverickcer/env-cap/schema` | `schemas/` | Static JSON | Stable | The JSON Schema for `env-cap --json` output (`env-cap-report.schema.json`) and the model schemas under `./schema/*` |
28
+
29
+ <!-- ipc:end entry-points -->
30
+
31
+ ## What the Stable tier covers
32
+
33
+ | Surface | Checked by | Limit |
34
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
35
+ | Runtime APIs: `createEnv`, `validateEnv`, `documentEnv`, `resetEnvCache`, `isEnvContract`, the error classes | `ApiContract` (runtime baseline) | Signatures, not behaviour; tests cover behaviour |
36
+ | The four `generate*()` functions, their options, and the lower-level `./build` primitives such as `discoverSchemaFiles`, `parseSchemaFile`, `generateEvidenceModel` and `getEvidenceModel` | `ApiContract` (build baseline) | The dependency-ownership engine's internals are Private ([ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md)) |
37
+ | `@maverickcer/env-cap/helpers`, `/evidence`, `/node` and `/eslint-plugin` exports, including rule names, options and the default allow list | `ApiContract` (one baseline per entry) | None found |
38
+ | CLI flags in `env-cap --help`, and the exit codes | `SurfaceContract` | None found |
39
+ | The `--json` report and the published JSON Schema (`@maverickcer/env-cap/schema`) | `SurfaceContract` diffs the schema; the `Schema` check fails if it is not regenerated from `src/cli/json.ts` | A changed or removed field is meant to bump `schemaVersion`. No check ties a shape change to that bump yet |
40
+ | The persisted evidence file, a serialization of `EvidenceModel` | `ApiContract` (evidence baseline) for the type | The committed evidence of two examples validates against the schema; a freshly written file is not checked |
41
+ | The generated manifest's shape | Tests in `test/build/manifest.test.ts` | No baseline diff |
42
+ | The `envCap.schema` field in a package's `package.json`, and the `packages` and `tsconfig` options | Tests in `test/build/resolution/` | No baseline diff for the field |
43
+ | The files and templates `env-cap init` writes | `test/cli/init.test.ts` pins the exact templates | None found |
44
+ | The GitHub Action's input names and defaults | `SurfaceContract` | Input descriptions and the summary comment's sections are not baselined |
45
+ | The supported toolchain: Node.js `>=22` and `moduleResolution` `node16`, `nodenext` or `bundler` | `EngineMatrix` (Node 22 and 24) and `TypeResolution` | Node 26 runs as an informational job |
46
+ | TypeScript 5, 6 and 7 for type-checking every entry point except `./eslint-plugin`, under `strict` and full library checking | `scripts/typescript-compat.mjs` in CI | CI installs the newest 5.x, 6.x and 7.x only, and that job does not yet block a merge |
47
+
48
+ The Action is used through a major tag: `uses: maverickcer/env-cap@v0` while the package is `0.x`, `@v1` from 1.0.0. That tag moves only within a major version.
49
+
50
+ The scanner needs TypeScript's classic compiler API, which TypeScript 7 does not ship. It uses your `typescript` when that has the API, and the bundled TypeScript 6 otherwise. Your `tsc` stays TypeScript 7 ([ADR 0049](specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md)).
51
+
52
+ Everything above was promoted from Experimental in [ADR 0045](specs/decisions/0045-promote-experimental-surfaces-to-stable.md).
70
53
 
71
54
  ## Experimental
72
55
 
73
- Explicitly labeled as such, in the README, the relevant option's own JSDoc,
74
- and the ADR that introduces it. An Experimental surface may change shape --
75
- including in a breaking way -- in a minor or patch release, without that
76
- being a semver violation. This is not a loophole for casual churn: a feature
77
- ships Experimental because it is genuinely new enough that real-world
78
- feedback is likely to reveal a better shape, not because we're unwilling to
79
- commit to _something_. Once a feature has been through at least one real
80
- feedback cycle without a need to break it, its ADR's Status moves from
81
- Proposed/Experimental to Accepted, and it becomes Stable.
56
+ A surface ships Experimental when it is new enough that real use may show a better shape. It is labelled here, in the option's TSDoc, and in the ADR that introduces it. After one feedback cycle without a break, its ADR moves to Accepted and it becomes Stable.
82
57
 
83
- Nothing currently ships Experimental -- see [ADR 0045](specs/decisions/0045-promote-experimental-surfaces-to-stable.md)
84
- for the most recent round of promotions. A future feature genuinely new
85
- enough to warrant it will be added here, explicitly, with its own ADR.
58
+ Nothing ships Experimental today.
86
59
 
87
60
  ## Private
88
61
 
89
- Never covered by semver, may change at any time without notice:
62
+ Never covered by semver:
90
63
 
91
- - Internal modules and functions not re-exported from `.`, `./build`, or
92
- `./helpers`.
93
- - Parsing/AST-traversal implementation details (e.g. exactly how
94
- `src/build/parse.ts` walks a source file).
95
- - The dependency-ownership engine's internals (`scan-dependencies.ts`,
96
- `dependency-graph.ts`) -- see [ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md).
97
- - Any behavior not documented in the README, a JSDoc comment on a public
98
- export, or an ADR.
64
+ - Modules and functions not re-exported from an entry point in `package.json#exports`.
65
+ - How `src/build/parse.ts` walks a source file.
66
+ - The dependency-ownership engine (`scan-dependencies.ts`, `dependency-graph.ts`).
67
+ - Behaviour not documented in the README, the Guide, a TSDoc comment on a public export, or an ADR.
99
68
 
100
69
  ## Pre-1.0 status
101
70
 
102
- `env-cap` has not yet reached a `1.0` release. Per [Keep a
103
- Changelog](https://keepachangelog.com/en/1.1.0/)/semver convention, **minor
104
- versions may include breaking changes to the Stable tier before 1.0** --
105
- this document defines _scope_ (what would eventually be covered), not a
106
- promise that it is already fully locked in at `0.x`.
107
-
108
- How a `0.x` bump is chosen: the shared release tooling from
109
- `internal-package-contract` deflates one level below 1.0.0 -- a breaking change
110
- releases a minor, a feature a patch, and the API-contract gate requires only a
111
- minor for a breaking API diff -- so **nothing automated can publish `1.0.0`**.
112
- Crossing to 1.0.0 takes a human-authored `major` changeset, and that release
113
- pull request is not auto-merged. The Experimental and Private tiers behave the
114
- same before and after 1.0: Experimental surfaces may change at any version;
115
- Private internals always may.
116
-
117
- See [`SECURITY.md`](SECURITY.md#supported-versions) for the related, and
118
- separate, question of which versions receive security fixes.
71
+ `env-cap` has not reached 1.0. Before 1.0, **a minor release may include a breaking change to the Stable tier.** This document defines the scope the 1.0 promise will cover.
72
+
73
+ How a `0.x` release level is chosen:
74
+
75
+ 1. For changesets it generates from commit messages, the release tooling lowers each level by one below 1.0: a breaking commit releases a minor, a `feat` commit a patch. A hand-written changeset is released at the level it names.
76
+ 2. The `ApiContract` check requires only a minor for a breaking API diff.
77
+ 3. Commit-generated bumps stop below 1.0.0. Crossing it takes a hand-written `major` changeset, and the workflow only posts a notice when its release pull request is opened. A person merges every release pull request.
78
+
79
+ Experimental and Private tiers behave the same before and after 1.0.
80
+
81
+ [`SECURITY.md`](SECURITY.md#supported-versions) covers the separate question of which versions get security fixes.
@@ -2,8 +2,8 @@
2
2
 
3
3
  This guide is for the person **reading** `BENCHMARKS.md`: a platform engineer deciding whether to run
4
4
  this package, a CTO estimating what it adds to the infrastructure bill, or a maintainer checking a
5
- change. It explains why the benchmarks exist, how to read each number, and -- just as important --
6
- what you must **not** do with them.
5
+ change. It explains why the benchmarks exist, how to read each number, and, as important, what you
6
+ must **not** do with them.
7
7
 
8
8
  Its companion, [WRITING-BENCHMARKS.md](WRITING-BENCHMARKS.md), explains how benchmarks are written and
9
9
  documented.
@@ -42,7 +42,7 @@ you what you are paying for them, in time and in money, and how the bill grows w
42
42
  | Column | Meaning |
43
43
  | --------------- | ------------------------------------------------------------------------------------------------------------------------ |
44
44
  | size (`n`) | The workload size for that row. The unit (record, call, file...) is stated at the top of the section. |
45
- | Median | The middle sample. Robust against the occasional slow outlier; the number to quote. |
45
+ | Median | The middle sample. Unmoved by the occasional slow outlier; the number to quote. |
46
46
  | p95 | 95% of samples were this fast or faster. The gap between median and p95 is the variability you should plan for. |
47
47
  | CPU (median) | CPU time actually spent. Can exceed wall time slightly because of background compilation and garbage collection threads. |
48
48
  | Heap Δ | Memory the operation left allocated (can be negative when garbage was collected during the sample). |
@@ -101,7 +101,7 @@ one moment.** It is not a property of the package.
101
101
  timings by 10-40%.
102
102
  - Do **not** compare one package's numbers with another package's. The workloads differ; the
103
103
  comparison means nothing.
104
- - Do **not** treat any single number as a promise. It is not a guarantee, a service-level agreement or
104
+ - Do **not** treat any single number as a promise. It is not a commitment, a service-level agreement or
105
105
  a competitive claim.
106
106
 
107
107
  What the numbers **are** good for:
@@ -109,7 +109,7 @@ What the numbers **are** good for:
109
109
  - **Change over time on comparable hardware.** The same suite on the same kind of machine before and
110
110
  after a change shows whether the change made the package slower. Look for movement larger than the
111
111
  run-to-run noise.
112
- - **Shape, not just level.** A change in growth class (O(n) becoming O(n²)) is a much bigger signal
112
+ - **Shape, not only level.** A change in growth class (O(n) becoming O(n²)) is a much bigger signal
113
113
  than a 15% shift in a timing, and it is far less sensitive to the machine than a time is, because it
114
114
  is a ratio between sizes on the same run. It still assumes the same sizes, workload and runtime.
115
115
  - **Relative cost between functions.** Which function dominates the overhead is usually the same on
@@ -172,9 +172,15 @@ not the speed of the machine: the measured class against the documented big-O (a
172
172
  fails, unless `.repo-contract/exceptions/benchmark-complexity.json` records a person's acceptance of it).
173
173
  The third is a ratio: the package's overhead _relative to its own baseline_, measured in the same run,
174
174
  growing past an allowance (50% for millisecond-scale work, 70% for microsecond-scale work, which is
175
- noisier) against both the last run on main and the last release. A function whose big-O could not be
175
+ noisier). The baseline and the package are sampled interleaved, so the overhead is a per-pair
176
+ difference with a 95% confidence interval; a growth that sits inside the intervals of the two runs
177
+ compared is reported as a note, never a failure. What the gate judges is main measured on the same
178
+ runner in the same job; the committed results of main and of the last release are judged only when
179
+ they came from the same CPU model, since for fast work the ratio also depends on how much of a bare
180
+ baseline is process start-up. A function whose big-O could not be
176
181
  determined (too few sizes, or no difference between them) is a **warning**: nothing is known to be wrong, but
177
- nothing is checked. Raw time against another run is shown, never judged.
182
+ nothing is checked. Raw time against another run is shown, never judged. A failed gate fails the benchmark
183
+ job; whether a red job blocks the merge is decided by the repository's ruleset, not by the gate.
178
184
 
179
185
  After a merge, a job measures the merge commit and records it -- the results file and a history entry
180
186
  naming the commit, pull request and version -- through its own small pull request. Each entry also keeps
@@ -36,7 +36,7 @@ a function whose cost nobody can see.
36
36
  - **Cold start**, if the package does work at import or startup (module evaluation, building
37
37
  registries, reading configuration). Cold start is paid by every process, every deploy and every
38
38
  serverless invocation that scales from zero.
39
- - **Memory**, not just time: what the operation allocates and retains. The report records the heap
39
+ - **Memory**, as well as time: what the operation allocates and retains. The report records the heap
40
40
  delta of every sample.
41
41
  - **Every variable that could change the cost.** This is the part that is easy to skip and the part
42
42
  that matters most. Walk through each of these for every function and decide, explicitly, whether it
@@ -1,21 +1,16 @@
1
1
  /**
2
- * The filesystem capability a package's `./build` entry requires from its caller.
2
+ * The filesystem a package's `./build` entry is handed by its caller.
3
3
  *
4
- * `./build` is a **library surface**: it must not acquire filesystem access
5
- * implicitly (no `node:fs` import outside the package's CLI). Every public options object carries a required
6
- * `fs` field of this type, and the caller supplies a concrete adapter: the CLI builds one over
7
- * `node:fs/promises`; a test builds either that same adapter or an in-memory fake.
4
+ * `./build` is a library surface, so it never imports `node:fs` itself (the `no-node-fs` rule enforces that).
5
+ * Every public options object carries a required `fs` of this type. The CLI builds one over `node:fs/promises`;
6
+ * a test hands in the same adapter or an in-memory fake. Real filesystem work still happens; the capability is
7
+ * handed in rather than acquired.
8
8
  *
9
- * "Ambient-fs-free" means specifically: `./build` never reaches for
10
- * `node:fs` itself. It still performs real filesystem operations -- the
11
- * capability is always handed in.
9
+ * The signatures mirror `node:fs/promises`, so a thin adapter is a drop-in value. The entry and stat types are
10
+ * structural ({@link BuildDirent}, {@link BuildStats}) rather than Node's own, so the boundary does not leak
11
+ * Node's types. Only the operations the build code calls are declared.
12
12
  *
13
- * The shape is modeled on `node:fs/promises`'s own signatures so a thin
14
- * adapter is a drop-in value, but uses minimal structural types
15
- * ({@link BuildDirent}/{@link BuildStats}) rather than Node's `Dirent`/
16
- * `Stats` -- the capability boundary shouldn't leak Node's type surface just
17
- * because the concrete adapter happens to be Node-backed. Only the
18
- * operations the build code actually calls are here.
13
+ * This file is the canonical source; a package carries a managed copy (`src/_ipc/build-fs.ts`, see `sync`).
19
14
  */
20
15
  export interface BuildFileSystem {
21
16
  /** Read a UTF-8 text file. Rejects if the path doesn't exist or isn't readable. */
@@ -1 +1 @@
1
- {"version":3,"file":"build-fs.d.ts","sourceRoot":"","sources":["../../../src/_ipc/build-fs.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACtE,mGAAmG;IACnG,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnF,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACtF,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAA;KAAE,KACtC,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IACpD,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CACrD;AAED,sHAAsH;AACtH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAA;IACnC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;CAC/B;AAED,iHAAiH;AACjH,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB"}
1
+ {"version":3,"file":"build-fs.d.ts","sourceRoot":"","sources":["../../../src/_ipc/build-fs.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACtE,mGAAmG;IACnG,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnF,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACtF,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAA;KAAE,KACtC,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IACpD,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CACrD;AAED,sHAAsH;AACtH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAA;IACnC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;CAC/B;AAED,iHAAiH;AACjH,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB"}
@@ -1,11 +1,11 @@
1
1
  /**
2
- * Fails with a readable message when neither the installed `typescript` nor the bundled
3
- * `@typescript/typescript6` exposes the classic compiler API (`createSourceFile`) the build-time scanner is
4
- * written against. TypeScript 7 ships no programmatic API, so a package normally falls back to the bundled
5
- * TypeScript 6 (see `typescript.ts`); this only fires when that dependency was stripped from the install, where
6
- * a raw call would die with "ts.createSourceFile is not a function".
2
+ * Fails with a readable message when no loaded compiler exposes the classic API (`createSourceFile`) the
3
+ * build-time scanner is written against. TypeScript 7 ships no programmatic API, so a package falls back to the
4
+ * bundled `@typescript/typescript6` (see `typescript.ts`). This fires only when that dependency was stripped from
5
+ * the install; a raw call would otherwise die with "ts.createSourceFile is not a function".
7
6
  *
8
- * This file is the canonical source; a package carries a managed copy (see `sync`) and binds its own name.
7
+ * This file is the canonical source; a package carries a managed copy (`src/_ipc/compiler-api.ts`, see `sync`)
8
+ * and binds its own name.
9
9
  * @param product - The package's name, as users install it, for the message.
10
10
  * @param compiler - The resolved compiler module (a parameter so a test can hand in a stand-in).
11
11
  * @throws Error naming the installed version and how to restore the bundled compiler.
@@ -1 +1 @@
1
- {"version":3,"file":"display-path.d.ts","sourceRoot":"","sources":["../../../src/_ipc/display-path.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOlE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvE"}
1
+ {"version":3,"file":"display-path.d.ts","sourceRoot":"","sources":["../../../src/_ipc/display-path.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOlE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvE"}
@@ -1,14 +1,14 @@
1
1
  /**
2
- * The marker every generated file starts with, and the two standing notices every governance-adjacent
3
- * artifact carries, written once for every MaverickCER package that generates files.
2
+ * The marker every generated file starts with, and the two standing notices a generated artifact carries,
3
+ * written once for every package that generates files.
4
4
  *
5
- * This file is the canonical source. A package that uses it holds a managed copy (see `sync`), so it
6
- * needs no dependency on this repository at runtime. It is deliberately self-contained: no imports, no
7
- * Node APIs, no environment access, so it is safe in any bundle.
5
+ * This file is the canonical source; a package carries a managed copy (`src/_ipc/generated-banner.ts`, see
6
+ * `sync`), so it needs no dependency on this repository at runtime. It has no imports, no Node APIs and no
7
+ * environment access, so it is safe in any bundle.
8
8
  *
9
- * One marker means one place decides what "generated" looks like: the code that writes the marker and the
10
- * code that reads it (to refuse to overwrite a hand-written file, or to ignore a file that only imports a
11
- * generated one) can never drift apart.
9
+ * One marker means one place decides what "generated" looks like. The code that writes it and the code that
10
+ * reads it (to refuse to overwrite a hand-written file, or to ignore a file that only imports a generated one)
11
+ * cannot drift apart.
12
12
  */
13
13
  /** What differs between packages; everything else is shared. */
14
14
  export interface GeneratedBannerOptions {
@@ -1,11 +1,11 @@
1
1
  /**
2
- * Converts one glob pattern to a `RegExp`. Handles `**` as "any number of path segments, including zero", so
3
- * `**\/node_modules/**` matches a root-level `node_modules` and `**\/x.ts` matches a root-level file, not
4
- * just nested ones; a plain `**` to `.*` substitution gets both wrong.
2
+ * Converts one glob pattern to a `RegExp`. `**` means any number of path segments, including zero, so
3
+ * `**\/node_modules/**` matches a root-level `node_modules` and `**\/x.ts` a root-level file. A plain `**` to
4
+ * `.*` substitution gets both wrong.
5
5
  *
6
- * One implementation for every package: build-time discovery and ESLint options need exactly the same matching,
7
- * and four hand-kept copies (two designs) had already accumulated. This file is the canonical source; a
8
- * package carries a managed copy (see `sync`).
6
+ * One implementation for every package: build-time discovery and ESLint options need the same matching, and
7
+ * hand-kept copies had already diverged. This file is the canonical source; a package carries a managed copy
8
+ * (`src/_ipc/glob.ts`, see `sync`).
9
9
  */
10
10
  export declare function globToRegExp(pattern: string): RegExp;
11
11
  /**
@@ -15,20 +15,6 @@ export interface RuleOptions {
15
15
  * capability boundary. */
16
16
  allow?: string[];
17
17
  }
18
- /**
19
- * Flags any `import`, re-export (`export ... from`, `export * from`), `require`, `process.getBuiltinModule`,
20
- * TypeScript `import x = require()` or dynamic `import()` of `node:fs` (a string or a `${}`-free template) in
21
- * library code, so a library surface acquires its filesystem capability from the
22
- * caller instead of reaching for `node:fs` itself (the same discipline
23
- * `repo-contract`'s ADR-0011 established for `child_process`/`process.env`).
24
- * The wording passed in names the package's own documentation and decision record.
25
- *
26
- * @remarks
27
- * Nothing is exempt by default. A package's own config allows its CLI folder, for example `src/cli/**`
28
- * (the executable capability boundary that builds the `node:fs/promises`
29
- * adapter); a consuming project sets its own `allow` for its own entry
30
- * points.
31
- */
32
18
  export declare function createNoNodeFs(wording: NoNodeFsWording): import("@typescript-eslint/utils/ts-eslint").RuleModule<"noNodeFs", [RuleOptions], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
33
19
  name: string;
34
20
  };
@@ -1 +1 @@
1
- {"version":3,"file":"no-node-fs.d.ts","sourceRoot":"","sources":["../../../src/_ipc/no-node-fs.ts"],"names":[],"mappings":"AAQA,6GAA6G;AAC7G,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;IAC9C,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,kHAAkH;IAClH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;+BAI2B;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AAsCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe;;EAqEtD"}
1
+ {"version":3,"file":"no-node-fs.d.ts","sourceRoot":"","sources":["../../../src/_ipc/no-node-fs.ts"],"names":[],"mappings":"AAYA,6GAA6G;AAC7G,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;IAC9C,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,kHAAkH;IAClH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;+BAI2B;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AA6DD,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe;;EAsEtD"}
@@ -18,13 +18,18 @@ import type { DiscoveredContract } from "./link.js";
18
18
  /** Bump only when a reader could misinterpret the new shape -- same discipline every other canonical model's `schemaVersion` follows. */
19
19
  export declare const LIFECYCLE_MODEL_SCHEMA_VERSION = 3;
20
20
  /**
21
- * One variable's computed NIST SP 800-53 IA-5 rotation-compliance status --
21
+ * One variable's computed NIST SP 800-53 IA-5 rotation status (a policy-window judgement) --
22
22
  * see `computeRotationStatus()` for exactly how it's derived. Always present
23
23
  * on a `LifecycleModelVariable` (never `undefined`) since a variable with
24
24
  * literally nothing lifecycle-relevant set never reaches this model at all
25
25
  * (`hasLifecycleData()` below) -- `"undeclared"` is itself the honest value
26
26
  * for "reached this model for some other lifecycle reason (e.g. `deprecated`)
27
27
  * but declares none of the four rotation-specific fields."
28
+ *
29
+ * This is a policy-window judgement from the declared metadata ("within the declared
30
+ * rotation period"), never a statement that any control is met or that a rotation
31
+ * happened; env-cap never checks a declaration against reality. The 1.0 release
32
+ * renames the value `"compliant"` to `"withinPolicy"` for that reason.
28
33
  */
29
34
  export type RotationComplianceStatus = "compliant" | "overdue" | "expired" | "undeclared";
30
35
  /**
@@ -101,7 +106,7 @@ export interface LifecycleModel {
101
106
  * fit either grammar still has it stored and rendered verbatim everywhere else, it just can't feed
102
107
  * a computed due date, and `computeRotationStatus()` fails closed (`"overdue"`) rather than
103
108
  * guessing at one. Month/year are calendar approximations (30/365 days) -- acceptable for a
104
- * rotation-compliance signal, not precise enough for anything billing/calendar-accurate.
109
+ * rotation-window signal, not precise enough for anything billing/calendar-accurate.
105
110
  *
106
111
  * A computed total of zero days (e.g. "0 days", "P0D", "P0Y0M0D" -- the digit grammar can't
107
112
  * produce a *negative* total, but zero is reachable) is treated the same as an unparseable
@@ -120,7 +125,7 @@ export interface LifecycleModel {
120
125
  */
121
126
  export declare function parseRotationPeriodDays(value: string): number | undefined;
122
127
  /**
123
- * Computes one variable's NIST SP 800-53 IA-5 rotation-compliance status from its lifecycle facts,
128
+ * Computes one variable's NIST SP 800-53 IA-5 rotation status (a policy-window judgement) from its lifecycle facts,
124
129
  * relative to `now`.
125
130
  *
126
131
  * @remarks
@@ -1 +1 @@
1
- {"version":3,"file":"lifecycle-model.d.ts","sourceRoot":"","sources":["../../../src/build/lifecycle-model.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"lifecycle-model.d.ts","sourceRoot":"","sources":["../../../src/build/lifecycle-model.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AAEvE;;;;;;;;;;;;;;GAcG;AAEH,yIAAyI;AACzI,eAAO,MAAM,8BAA8B,IAAI,CAAA;AAE/C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,wBAAwB,GAAG,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,YAAY,CAAA;AAEzF;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,8HAA8H;IAC9H,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,sMAAsM;IACtM,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,0DAA0D;IAC1D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9C,uDAAuD;IACvD,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C,sDAAsD;IACtD,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1C,8DAA8D;IAC9D,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IAC7D,kGAAkG;IAClG,QAAQ,CAAC,cAAc,EAAE,wBAAwB,CAAA;CAClD;AAED,6KAA6K;AAC7K,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,UAAU,EAAE,OAAO,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,iUAAiU;IACjU,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACtD;AAED,8HAA8H;AAC9H,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,aAAa,EAAE,OAAO,8BAA8B,CAAA;IAC7D,wHAAwH;IACxH,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;IACrD;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAA;CAC5C;AAoCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA8CzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE;IACR,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9C,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1C,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;CAC9D,EACD,GAAG,EAAE,IAAI,GACR,wBAAwB,CA2B1B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,kBAAkB,EAAE,MAAM,EAC1B,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,MAAM,GACX,cAAc,CAoDhB"}
@@ -1 +1 @@
1
- {"version":3,"file":"sarif.d.ts","sourceRoot":"","sources":["../../../src/build/sarif.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAW,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAI/D,yEAAyE;AACzE,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;AAOvD,UAAU,aAAa;IACrB,QAAQ,CAAC,gBAAgB,EAAE;QACzB,QAAQ,CAAC,gBAAgB,EAAE;YAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;QACnD,QAAQ,CAAC,MAAM,CAAC,EAAE;YAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAA;KAC/E,CAAA;CACF;AAgCD,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;CAC9C;AAED,mHAAmH;AACnH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS;QACtB,QAAQ,CAAC,IAAI,EAAE;YACb,QAAQ,CAAC,MAAM,EAAE;gBACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBACrB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;gBAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBACxB,QAAQ,CAAC,KAAK,EAAE,SAAS;oBAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;iBAAE,EAAE,CAAA;aACnD,CAAA;SACF,CAAA;QACD,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;KACzC,EAAE,CAAA;CACJ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,YAAY,GAAG,QAAQ,CAgClE"}
1
+ {"version":3,"file":"sarif.d.ts","sourceRoot":"","sources":["../../../src/build/sarif.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAW,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAI/D,yEAAyE;AACzE,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;AAOvD,UAAU,aAAa;IACrB,QAAQ,CAAC,gBAAgB,EAAE;QACzB,QAAQ,CAAC,gBAAgB,EAAE;YAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;QACnD,QAAQ,CAAC,MAAM,CAAC,EAAE;YAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAA;KAC/E,CAAA;CACF;AAuCD,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;CAC9C;AAED,mHAAmH;AACnH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS;QACtB,QAAQ,CAAC,IAAI,EAAE;YACb,QAAQ,CAAC,MAAM,EAAE;gBACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBACrB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;gBAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBACxB,QAAQ,CAAC,KAAK,EAAE,SAAS;oBAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;iBAAE,EAAE,CAAA;aACnD,CAAA;SACF,CAAA;QACD,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;KACzC,EAAE,CAAA;CACJ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,YAAY,GAAG,QAAQ,CAgClE"}
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Optional convenience helpers for common processor/validator patterns.
3
- * Entirely separate from the core runtime -- `defineEnv`/`validateEnv` have
3
+ * Entirely separate from the core runtime -- `createEnv`/`validateEnv` have
4
4
  * no knowledge of this module and work identically without it.
5
5
  *
6
6
  * Usage: `processors.toNumber()`, `validators.range(1, 65535)`.
@@ -15,6 +15,9 @@ import type { CreateEnvOptions, EnvContract, EnvSchema } from "./types.js";
15
15
  * global env object, only per-feature contracts like `paymentsEnv.STRIPE_KEY`. Accessing a
16
16
  * key throws until {@link validateEnv} has run successfully for the runtime this contract
17
17
  * was passed to.
18
+ *
19
+ * The contract redacts itself under `console.log`, `String()`, `JSON.stringify` and template
20
+ * interpolation. Spreading it or calling `Object.entries()` on it reads every value, so do not.
18
21
  */
19
22
  export declare function createEnv<S extends EnvSchema>(schema: S, options?: CreateEnvOptions): EnvContract<S>;
20
23
  //# sourceMappingURL=create.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/runtime/create.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAqB,gBAAgB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAI7F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,SAAS,EAC3C,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,gBAAqB,GAC7B,WAAW,CAAC,CAAC,CAAC,CA4ChB"}
1
+ {"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/runtime/create.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAqB,gBAAgB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAI7F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,SAAS,EAC3C,MAAM,EAAE,CAAC,EACT,OAAO,GAAE,gBAAqB,GAC7B,WAAW,CAAC,CAAC,CAAC,CA4ChB"}
@@ -54,7 +54,7 @@ export interface VariableDocs {
54
54
  refreshInstructions?: string;
55
55
  /**
56
56
  * The kind of authenticator/secret this variable holds (e.g. "api-key", "oauth-client-secret",
57
- * "database-password", "tls-certificate") -- feeds the NIST SP 800-53 IA-5 rotation-compliance
57
+ * "database-password", "tls-certificate") -- feeds the NIST SP 800-53 IA-5 rotation-status
58
58
  * report's "authenticator type" column (IA-5's main statement requires an organization-defined
59
59
  * rotation period "by authenticator type," so this is what a generator groups/labels by).
60
60
  *
@@ -70,12 +70,15 @@ export interface VariableDocs {
70
70
  * type (the time-based half of IA-5's two-trigger rotation model). Paired with
71
71
  * {@link lastRotatedAt} so a generator can compute whether rotation is actually current, rather
72
72
  * than only recording that a period was declared; see `lifecycle-model.ts`'s
73
- * `computeRotationStatus()` for exactly how the two combine with {@link expiresAt}.
73
+ * `computeRotationStatus()` for exactly how the two combine with {@link expiresAt}. What comes
74
+ * out is a policy-window judgement over declared metadata ("within the declared period"), never
75
+ * a statement that a rotation happened or that a control is met: env-cap reads declarations, it
76
+ * does not check them against the secret store.
74
77
  */
75
78
  rotationPeriod?: string;
76
79
  /**
77
80
  * ISO date string -- the last time this variable's value was actually rotated. Paired with
78
- * {@link rotationPeriod} to compute rotation compliance. Independent of {@link expiresAt}, which
81
+ * {@link rotationPeriod} to compute whether rotation is within the declared period. Independent of {@link expiresAt}, which
79
82
  * states when the *current* value stops being valid, not when it was last changed -- a value can
80
83
  * be freshly rotated and still have a near-term `expiresAt` (a short-lived token), or long overdue
81
84
  * for rotation while its `expiresAt` (if any) is still comfortably in the future.
@@ -88,7 +91,7 @@ export interface VariableDocs {
88
91
  * rather than replacing it: this is a list a generator can render as its own column,
89
92
  * `refreshInstructions` stays prose ("how to actually rotate it"). Presence-only -- env-cap has
90
93
  * no way to observe whether a listed event actually occurred, so declaring this never by itself
91
- * changes a computed rotation-compliance status (see `lifecycle-model.ts`); it only makes the
94
+ * changes a computed rotation status (see `lifecycle-model.ts`); it only makes the
92
95
  * event-based trigger's existence visible in generated output.
93
96
  */
94
97
  rotationTriggerEvents?: readonly string[];
@@ -1 +1 @@
1
- {"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../../src/runtime/document.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../../src/runtime/document.ts"],"names":[],"mappings":"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"}
@@ -1,16 +1,17 @@
1
1
  /**
2
- * env-cap runtime entry point.
2
+ * The env-cap runtime entry point: declare contracts, validate them once at startup, and read
3
+ * typed values through the contract that owns them.
3
4
  *
4
- * Zero dependencies, isomorphic (no `fs`, no `process` other than the values
5
- * the developer passes in). Handles processing, validation, caching, and
6
- * typed access only -- discovery and manifest generation live in
7
- * `@maverickcer/env-cap/build` and are never imported from here.
5
+ * It imports no Node module and reads no Node global; it takes values only from the `values`
6
+ * you pass to `validateEnv()`. `test/runtime/browser-bundle.test.ts` checks the built bundle for
7
+ * Node imports, `process.` and `Buffer.`, but a third-party import would pass unnoticed.
8
+ * Discovery and manifest generation live in `@maverickcer/env-cap/build`, never here.
8
9
  *
9
- * `documentEnv` is exported from here, not `@maverickcer/env-cap/build`, even though
10
- * it exists purely for documentation: it's meant to be called inline in the
11
- * same schema file as `createEnv`, which is ordinary runtime code that may
12
- * end up in any bundle (including a browser one). It must be exactly as
13
- * cheap and safe to import as `createEnv` -- see `document.ts`.
10
+ * `documentEnv` is exported here, not from `./build`, because it is called inline in the same
11
+ * schema file as `createEnv`, which may end up in any bundle. It must be as cheap to import as
12
+ * `createEnv` (see `document.ts`).
13
+ *
14
+ * @packageDocumentation
14
15
  */
15
16
  export type { CreateEnvOptions, DefaultValue, EnvContract, EnvDefinition, EnvSchema, InferEnvValue, Processor, RawEnv, validateEnvOptions, validateEnvResult, Validator, } from "./types.js";
16
17
  export { createEnv } from "./create.js";