@maverickcer/env-cap 0.7.5 → 0.7.6

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 (278) hide show
  1. package/ADOPTION.md +12 -12
  2. package/AGENTS.md +85 -120
  3. package/CHANGELOG.md +27 -0
  4. package/CODE_REVIEW.md +5 -5
  5. package/CONTRIBUTING.md +5 -5
  6. package/GUIDE.md +42 -24
  7. package/README.md +52 -34
  8. package/RELEASING.md +78 -64
  9. package/SECURITY.md +15 -15
  10. package/VERSIONING.md +16 -15
  11. package/benchmarks/READING-BENCHMARKS.md +101 -85
  12. package/benchmarks/README.md +12 -9
  13. package/benchmarks/WRITING-BENCHMARKS.md +89 -79
  14. package/benchmarks/performance-buildtime/BENCHMARKS.md +20 -20
  15. package/benchmarks/performance-runtime/BENCHMARKS.md +107 -107
  16. package/dist/.dts/_ipc/build-fs.d.ts +3 -3
  17. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/display-path.d.ts +1 -1
  19. package/dist/.dts/_ipc/glob.d.ts +3 -2
  20. package/dist/.dts/_ipc/glob.d.ts.map +1 -1
  21. package/dist/.dts/_ipc/no-node-fs.d.ts +2 -2
  22. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  23. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  24. package/dist/.dts/_ipc/typescript.d.ts +4 -4
  25. package/dist/.dts/build/assemble-project.d.ts +14 -15
  26. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  27. package/dist/.dts/build/change-model.d.ts +14 -14
  28. package/dist/.dts/build/change-model.d.ts.map +1 -1
  29. package/dist/.dts/build/check-artifacts.d.ts +4 -4
  30. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  31. package/dist/.dts/build/citation-verification.d.ts +13 -14
  32. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  33. package/dist/.dts/build/compatibility.d.ts +24 -24
  34. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  35. package/dist/.dts/build/contract-model.d.ts +10 -10
  36. package/dist/.dts/build/contract-model.d.ts.map +1 -1
  37. package/dist/.dts/build/deep-equal.d.ts +2 -2
  38. package/dist/.dts/build/deep-freeze.d.ts +2 -2
  39. package/dist/.dts/build/dependency-graph.d.ts +48 -55
  40. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  41. package/dist/.dts/build/dependency-model.d.ts +18 -18
  42. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  43. package/dist/.dts/build/discover.d.ts +11 -11
  44. package/dist/.dts/build/discover.d.ts.map +1 -1
  45. package/dist/.dts/build/docs.d.ts +34 -38
  46. package/dist/.dts/build/docs.d.ts.map +1 -1
  47. package/dist/.dts/build/env-example.d.ts +13 -13
  48. package/dist/.dts/build/env-example.d.ts.map +1 -1
  49. package/dist/.dts/build/errors.d.ts +8 -8
  50. package/dist/.dts/build/evidence-cache.d.ts +23 -23
  51. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  52. package/dist/.dts/build/evidence-model.d.ts +3 -3
  53. package/dist/.dts/build/evidence-reference.d.ts +15 -15
  54. package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
  55. package/dist/.dts/build/evidence-snapshot.d.ts +47 -53
  56. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  57. package/dist/.dts/build/exclusive-group.d.ts +4 -4
  58. package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
  59. package/dist/.dts/build/finding-model.d.ts +12 -12
  60. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  61. package/dist/.dts/build/generate-documentation.d.ts +19 -19
  62. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  63. package/dist/.dts/build/generate-env-artifacts.d.ts +43 -43
  64. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  65. package/dist/.dts/build/generate-evidence.d.ts +19 -19
  66. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  67. package/dist/.dts/build/generate-manifest.d.ts +11 -12
  68. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  69. package/dist/.dts/build/generate-usage.d.ts +23 -24
  70. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  71. package/dist/.dts/build/generated-banner.d.ts +5 -5
  72. package/dist/.dts/build/governance-fields.d.ts +7 -7
  73. package/dist/.dts/build/humanize-key.d.ts +1 -1
  74. package/dist/.dts/build/humanize-key.d.ts.map +1 -1
  75. package/dist/.dts/build/index.d.ts +20 -36
  76. package/dist/.dts/build/index.d.ts.map +1 -1
  77. package/dist/.dts/build/lifecycle-model.d.ts +87 -85
  78. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  79. package/dist/.dts/build/link.d.ts +38 -39
  80. package/dist/.dts/build/link.d.ts.map +1 -1
  81. package/dist/.dts/build/literal-eval.d.ts +2 -2
  82. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  83. package/dist/.dts/build/live-expirations.d.ts +14 -13
  84. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  85. package/dist/.dts/build/manifest.d.ts +6 -6
  86. package/dist/.dts/build/map-utils.d.ts +4 -4
  87. package/dist/.dts/build/merge-documentation.d.ts +9 -8
  88. package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
  89. package/dist/.dts/build/ownership-model.d.ts +14 -15
  90. package/dist/.dts/build/ownership-model.d.ts.map +1 -1
  91. package/dist/.dts/build/parse.d.ts +20 -21
  92. package/dist/.dts/build/parse.d.ts.map +1 -1
  93. package/dist/.dts/build/reference-projections.d.ts +36 -38
  94. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  95. package/dist/.dts/build/resolution/resolve-import.d.ts +18 -14
  96. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  97. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +26 -26
  98. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  99. package/dist/.dts/build/resolution/resolve-within-root.d.ts +9 -9
  100. package/dist/.dts/build/sarif.d.ts +5 -5
  101. package/dist/.dts/build/sarif.d.ts.map +1 -1
  102. package/dist/.dts/build/scan-dependencies.d.ts +17 -16
  103. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  104. package/dist/.dts/build/sort-by-identity.d.ts +1 -1
  105. package/dist/.dts/build/source-position.d.ts +13 -13
  106. package/dist/.dts/build/tool-version.d.ts +1 -1
  107. package/dist/.dts/build/usage-report.d.ts +19 -19
  108. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  109. package/dist/.dts/eslint-plugin/index.d.ts +16 -5
  110. package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
  111. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
  112. package/dist/.dts/evidence/define-projection.d.ts +15 -16
  113. package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
  114. package/dist/.dts/evidence/index.d.ts +11 -15
  115. package/dist/.dts/evidence/index.d.ts.map +1 -1
  116. package/dist/.dts/helpers/index.d.ts +15 -18
  117. package/dist/.dts/helpers/index.d.ts.map +1 -1
  118. package/dist/.dts/helpers/validators.d.ts +2 -2
  119. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  120. package/dist/.dts/node/index.d.ts +19 -0
  121. package/dist/.dts/node/index.d.ts.map +1 -1
  122. package/dist/.dts/runtime/create.d.ts +3 -3
  123. package/dist/.dts/runtime/document.d.ts +90 -99
  124. package/dist/.dts/runtime/document.d.ts.map +1 -1
  125. package/dist/.dts/runtime/errors.d.ts +5 -5
  126. package/dist/.dts/runtime/reset.d.ts +1 -1
  127. package/dist/.dts/runtime/types.d.ts +23 -24
  128. package/dist/.dts/runtime/types.d.ts.map +1 -1
  129. package/dist/.dts/runtime/validate.d.ts +1 -1
  130. package/dist/.dts7/_ipc/build-fs.d.ts +3 -3
  131. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -1
  132. package/dist/.dts7/_ipc/display-path.d.ts +1 -1
  133. package/dist/.dts7/_ipc/glob.d.ts +3 -2
  134. package/dist/.dts7/_ipc/glob.d.ts.map +1 -1
  135. package/dist/.dts7/_ipc/no-node-fs.d.ts +2 -2
  136. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  137. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  138. package/dist/.dts7/_ipc/typescript.d.ts +4 -4
  139. package/dist/.dts7/build/assemble-project.d.ts +14 -15
  140. package/dist/.dts7/build/assemble-project.d.ts.map +1 -1
  141. package/dist/.dts7/build/change-model.d.ts +14 -14
  142. package/dist/.dts7/build/change-model.d.ts.map +1 -1
  143. package/dist/.dts7/build/check-artifacts.d.ts +4 -4
  144. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -1
  145. package/dist/.dts7/build/citation-verification.d.ts +13 -14
  146. package/dist/.dts7/build/citation-verification.d.ts.map +1 -1
  147. package/dist/.dts7/build/compatibility.d.ts +24 -24
  148. package/dist/.dts7/build/compatibility.d.ts.map +1 -1
  149. package/dist/.dts7/build/contract-model.d.ts +10 -10
  150. package/dist/.dts7/build/contract-model.d.ts.map +1 -1
  151. package/dist/.dts7/build/deep-equal.d.ts +2 -2
  152. package/dist/.dts7/build/deep-freeze.d.ts +2 -2
  153. package/dist/.dts7/build/dependency-graph.d.ts +48 -55
  154. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -1
  155. package/dist/.dts7/build/dependency-model.d.ts +18 -18
  156. package/dist/.dts7/build/dependency-model.d.ts.map +1 -1
  157. package/dist/.dts7/build/discover.d.ts +11 -11
  158. package/dist/.dts7/build/discover.d.ts.map +1 -1
  159. package/dist/.dts7/build/docs.d.ts +34 -38
  160. package/dist/.dts7/build/docs.d.ts.map +1 -1
  161. package/dist/.dts7/build/env-example.d.ts +13 -13
  162. package/dist/.dts7/build/env-example.d.ts.map +1 -1
  163. package/dist/.dts7/build/errors.d.ts +8 -8
  164. package/dist/.dts7/build/evidence-cache.d.ts +23 -23
  165. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -1
  166. package/dist/.dts7/build/evidence-model.d.ts +3 -3
  167. package/dist/.dts7/build/evidence-reference.d.ts +15 -15
  168. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -1
  169. package/dist/.dts7/build/evidence-snapshot.d.ts +47 -53
  170. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -1
  171. package/dist/.dts7/build/exclusive-group.d.ts +4 -4
  172. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -1
  173. package/dist/.dts7/build/finding-model.d.ts +12 -12
  174. package/dist/.dts7/build/finding-model.d.ts.map +1 -1
  175. package/dist/.dts7/build/generate-documentation.d.ts +19 -19
  176. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -1
  177. package/dist/.dts7/build/generate-env-artifacts.d.ts +43 -43
  178. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -1
  179. package/dist/.dts7/build/generate-evidence.d.ts +19 -19
  180. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -1
  181. package/dist/.dts7/build/generate-manifest.d.ts +11 -12
  182. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -1
  183. package/dist/.dts7/build/generate-usage.d.ts +23 -24
  184. package/dist/.dts7/build/generate-usage.d.ts.map +1 -1
  185. package/dist/.dts7/build/generated-banner.d.ts +5 -5
  186. package/dist/.dts7/build/governance-fields.d.ts +7 -7
  187. package/dist/.dts7/build/humanize-key.d.ts +1 -1
  188. package/dist/.dts7/build/humanize-key.d.ts.map +1 -1
  189. package/dist/.dts7/build/index.d.ts +20 -36
  190. package/dist/.dts7/build/index.d.ts.map +1 -1
  191. package/dist/.dts7/build/lifecycle-model.d.ts +87 -85
  192. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -1
  193. package/dist/.dts7/build/link.d.ts +38 -39
  194. package/dist/.dts7/build/link.d.ts.map +1 -1
  195. package/dist/.dts7/build/literal-eval.d.ts +2 -2
  196. package/dist/.dts7/build/literal-eval.d.ts.map +1 -1
  197. package/dist/.dts7/build/live-expirations.d.ts +14 -13
  198. package/dist/.dts7/build/live-expirations.d.ts.map +1 -1
  199. package/dist/.dts7/build/manifest.d.ts +6 -6
  200. package/dist/.dts7/build/map-utils.d.ts +4 -4
  201. package/dist/.dts7/build/merge-documentation.d.ts +9 -8
  202. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -1
  203. package/dist/.dts7/build/ownership-model.d.ts +14 -15
  204. package/dist/.dts7/build/ownership-model.d.ts.map +1 -1
  205. package/dist/.dts7/build/parse.d.ts +20 -21
  206. package/dist/.dts7/build/parse.d.ts.map +1 -1
  207. package/dist/.dts7/build/reference-projections.d.ts +36 -38
  208. package/dist/.dts7/build/reference-projections.d.ts.map +1 -1
  209. package/dist/.dts7/build/resolution/resolve-import.d.ts +18 -14
  210. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -1
  211. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +26 -26
  212. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -1
  213. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +9 -9
  214. package/dist/.dts7/build/sarif.d.ts +5 -5
  215. package/dist/.dts7/build/sarif.d.ts.map +1 -1
  216. package/dist/.dts7/build/scan-dependencies.d.ts +17 -16
  217. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -1
  218. package/dist/.dts7/build/sort-by-identity.d.ts +1 -1
  219. package/dist/.dts7/build/source-position.d.ts +13 -13
  220. package/dist/.dts7/build/tool-version.d.ts +1 -1
  221. package/dist/.dts7/build/usage-report.d.ts +19 -19
  222. package/dist/.dts7/build/usage-report.d.ts.map +1 -1
  223. package/dist/.dts7/eslint-plugin/index.d.ts +16 -5
  224. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -1
  225. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +4 -4
  226. package/dist/.dts7/evidence/define-projection.d.ts +15 -16
  227. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -1
  228. package/dist/.dts7/evidence/index.d.ts +11 -15
  229. package/dist/.dts7/evidence/index.d.ts.map +1 -1
  230. package/dist/.dts7/helpers/index.d.ts +15 -18
  231. package/dist/.dts7/helpers/index.d.ts.map +1 -1
  232. package/dist/.dts7/helpers/validators.d.ts +2 -2
  233. package/dist/.dts7/helpers/validators.d.ts.map +1 -1
  234. package/dist/.dts7/node/index.d.ts +19 -0
  235. package/dist/.dts7/node/index.d.ts.map +1 -1
  236. package/dist/.dts7/runtime/create.d.ts +3 -3
  237. package/dist/.dts7/runtime/document.d.ts +90 -99
  238. package/dist/.dts7/runtime/document.d.ts.map +1 -1
  239. package/dist/.dts7/runtime/errors.d.ts +5 -5
  240. package/dist/.dts7/runtime/reset.d.ts +1 -1
  241. package/dist/.dts7/runtime/types.d.ts +23 -24
  242. package/dist/.dts7/runtime/types.d.ts.map +1 -1
  243. package/dist/.dts7/runtime/validate.d.ts +1 -1
  244. package/dist/{build-DNAYWD2B.js → build-UEENZEUX.js} +37 -39
  245. package/dist/build-UEENZEUX.js.map +1 -0
  246. package/dist/build.cjs +36 -38
  247. package/dist/build.cjs.map +1 -1
  248. package/dist/build.js +36 -38
  249. package/dist/build.js.map +1 -1
  250. package/dist/{chunk-HAGMVMN5.js → chunk-TBL3O7IG.js} +2 -2
  251. package/dist/cli/index.js +29 -28
  252. package/dist/cli/index.js.map +1 -1
  253. package/dist/eslint-plugin/index.cjs.map +1 -1
  254. package/dist/eslint-plugin/index.js.map +1 -1
  255. package/dist/evidence.cjs +1 -1
  256. package/dist/evidence.cjs.map +1 -1
  257. package/dist/evidence.js +1 -1
  258. package/dist/evidence.js.map +1 -1
  259. package/dist/helpers.cjs +4 -4
  260. package/dist/helpers.cjs.map +1 -1
  261. package/dist/helpers.js +4 -4
  262. package/dist/helpers.js.map +1 -1
  263. package/dist/index.cjs.map +1 -1
  264. package/dist/index.js.map +1 -1
  265. package/examples/README.md +1 -1
  266. package/package.json +18 -10
  267. package/schemas/contract-model.schema.json +7 -7
  268. package/schemas/env-cap-report.schema.json +88 -88
  269. package/skills/env-cap/SKILL.md +12 -13
  270. package/skills/env-cap/references/api.md +1 -1
  271. package/specs/architecture.md +145 -120
  272. package/specs/generated-artifacts.md +78 -70
  273. package/specs/migrations/README.md +6 -6
  274. package/specs/migrations/from-centralized-schema.md +1 -1
  275. package/specs/migrations/from-t3-env.md +9 -9
  276. package/PROMPT.md +0 -89
  277. package/dist/build-DNAYWD2B.js.map +0 -1
  278. /package/dist/{chunk-HAGMVMN5.js.map → chunk-TBL3O7IG.js.map} +0 -0
@@ -1,9 +1,9 @@
1
1
  import type { EvidenceModel } from "../build/evidence-model.js";
2
2
  /**
3
3
  * A pure function from the full Evidence Model to one field of a
4
- * projection's output shape. Must not mutate `evidence` -- the membrane
4
+ * projection's output shape. Must not mutate `evidence` (the membrane
5
5
  * `defineEvidenceProjection()` wraps it in enforces that at runtime, see
6
- * `createTrackingProxy()` below -- and must not perform I/O; env-cap can
6
+ * `createTrackingProxy()` below) and must not perform I/O; env-cap can
7
7
  * enforce the read-only half of purity but not the "no side effects" half.
8
8
  */
9
9
  export type EvidenceProjector<T> = (evidence: EvidenceModel) => T;
@@ -19,34 +19,33 @@ export interface EvidenceProjectionResult<T extends Record<string, unknown>> {
19
19
  /**
20
20
  * The function `defineEvidenceProjection()` returns. Callable directly for
21
21
  * the common case (`projection(evidence)` -> `T`); `.project()` returns the
22
- * same value alongside automatic provenance -- see ADR 0032.
22
+ * same value alongside automatic provenance: see ADR 0032.
23
23
  */
24
24
  export interface EvidenceProjection<T extends Record<string, unknown>> {
25
25
  (evidence: EvidenceModel): T;
26
- /** Same computation as calling the projection directly, plus which `EvidenceModel` field paths fed each output key -- see {@link EvidenceProjectionResult}. */
26
+ /** Same computation as calling the projection directly, plus which `EvidenceModel` field paths fed each output key: see {@link EvidenceProjectionResult}. */
27
27
  project(evidence: EvidenceModel): EvidenceProjectionResult<T>;
28
28
  }
29
29
  /**
30
30
  * Declares a projection: a named, pure transform from the immutable
31
31
  * `EvidenceModel` to any consumer-defined output shape, built entirely from
32
- * `schema`'s independent per-field projector functions -- see ADR 0031/0032.
32
+ * `schema`'s independent per-field projector functions; see ADR 0031/0032.
33
33
  *
34
- * env-cap's own reference projections (`.env.example`, Environment
34
+ * The reference projections env-cap ships (`.env.example`, Environment
35
35
  * Configuration Reference, Configuration Ownership, etc.) are built through
36
- * this exact function, with no privileged internal path -- a consumer's own
36
+ * this exact function, with no privileged internal path. A consumer's own
37
37
  * projection is a first-class citizen, not a lesser one.
38
38
  */
39
39
  export declare function defineEvidenceProjection<T extends Record<string, unknown>>(schema: EvidenceProjectionSchema<T>): EvidenceProjection<T>;
40
40
  /**
41
- * The error every membrane write-trap below throws. A function, not a
42
- * module-level `const` -- a `const` string's mutants are evaluated once at
43
- * module load and can't be attributed to a covering test under Stryker's
44
- * `perTest` coverage analysis (a documented false-Survivor, not a real
45
- * gap); exported so a test can pin the exact message directly, the same way
46
- * every membrane trap's own `.toThrow(...)` can't (a `TypeError` from a
47
- * Proxy invariant violation is thrown either way a trap's body is mutated,
48
- * so `.toThrow(TypeError)` alone doesn't distinguish "our message" from
49
- * "the engine's own invariant-violation message").
41
+ * The error every membrane write-trap below throws.
42
+ *
43
+ * @remarks
44
+ * It is a function, not a module-level `const`, because Stryker's `perTest`
45
+ * coverage cannot attribute a module-load string to the test that covers it.
46
+ * It is exported so a test can pin the exact message. A trap's
47
+ * `.toThrow(TypeError)` cannot: a mutated trap body still throws the engine's
48
+ * own Proxy invariant `TypeError`.
50
49
  */
51
50
  export declare function readOnlyMembraneError(): TypeError;
52
51
  //# sourceMappingURL=define-projection.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"define-projection.d.ts","sourceRoot":"","sources":["../../../src/evidence/define-projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAE/D;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,KAAK,CAAC,CAAA;AAEjE,6FAA6F;AAC7F,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACxE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACjD,CAAA;AAED,mHAAmH;AACnH,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;IACjB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;CAC/D;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACnE,CAAC,QAAQ,EAAE,aAAa,GAAG,CAAC,CAAA;IAC5B,+JAA+J;IAC/J,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,wBAAwB,CAAC,CAAC,CAAC,CAAA;CAC9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxE,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAClC,kBAAkB,CAAC,CAAC,CAAC,CAkBvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,IAAI,SAAS,CAIjD"}
1
+ {"version":3,"file":"define-projection.d.ts","sourceRoot":"","sources":["../../../src/evidence/define-projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAE/D;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,KAAK,CAAC,CAAA;AAEjE,6FAA6F;AAC7F,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACxE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACjD,CAAA;AAED,mHAAmH;AACnH,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;IACjB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;CAC/D;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACnE,CAAC,QAAQ,EAAE,aAAa,GAAG,CAAC,CAAA;IAC5B,6JAA6J;IAC7J,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,wBAAwB,CAAC,CAAC,CAAC,CAAA;CAC9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxE,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAClC,kBAAkB,CAAC,CAAC,CAAC,CAkBvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,IAAI,SAAS,CAIjD"}
@@ -1,21 +1,17 @@
1
1
  /**
2
- * env-cap Evidence Model entry point (`@maverickcer/env-cap/evidence`).
2
+ * Build your own views of the evidence file (`@maverickcer/env-cap/evidence`).
3
3
  *
4
- * `defineEvidenceProjection()` is the extensibility mechanism the seven
5
- * canonical fact models (ADR 0024) exist to serve. A projection is a named,
6
- * pure transform from the immutable `EvidenceModel` -- assembled at build
7
- * time by `generateEvidenceModel()`, `@maverickcer/env-cap/build` -- to any
8
- * consumer-defined output shape, with automatic read-only enforcement and
9
- * field-level provenance. See ADR 0031 (why a 5th entry point) and ADR 0032
10
- * (the Proxy-based mechanism itself).
4
+ * `defineEvidenceProjection()` declares a pure transform from an `EvidenceModel` to a shape you define:
5
+ * a dashboard row, an inventory table or a CI comment. The projectors read the model
6
+ * through a read-only membrane, and `.project()` also returns which model fields fed each output field
7
+ * (ADR 0032). ADR 0031 explains why this is its own entry point.
11
8
  *
12
- * This module is deliberately isomorphic: no `node:fs`, no `typescript`, no
13
- * knowledge of how an `EvidenceModel` gets built -- it only imports that
14
- * shape as a type (erased at compile time, mirroring `helpers`' one
15
- * sanctioned cross-folder edge onto `runtime` -- see
16
- * `specs/architecture.md`). A dashboard backend, an edge function, or a CI
17
- * step can run a projection over a previously-generated,
18
- * JSON-deserialized `EvidenceModel` with zero Node dependency.
9
+ * `generateEvidenceModel()` in `@maverickcer/env-cap/build` assembles the model at build time. This
10
+ * module imports no Node module and no TypeScript compiler, and takes the `EvidenceModel` shape as a
11
+ * type only. So a projection can run over a JSON-parsed evidence file outside Node; CI runs this
12
+ * entry under Bun, Deno and a Web-globals bundle.
13
+ *
14
+ * @packageDocumentation
19
15
  */
20
16
  export type { EvidenceModel, EvidenceProvenance } from "../build/evidence-model.js";
21
17
  export { defineEvidenceProjection } from "./define-projection.js";
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/evidence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACnF,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AACjE,YAAY,EACV,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,wBAAwB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/evidence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACnF,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AACjE,YAAY,EACV,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,wBAAwB,CAAA"}
@@ -1,19 +1,16 @@
1
1
  /**
2
- * Optional convenience helpers for common processor/validator patterns.
3
- * Entirely separate from the core runtime -- `createEnv`/`validateEnv` have
4
- * no knowledge of this module and work identically without it.
2
+ * Optional processors and validators for common cases (`@maverickcer/env-cap/helpers`), such as
3
+ * `processors.toNumber()` and `validators.range(1, 65535)`.
5
4
  *
6
- * Usage: `processors.toNumber()`, `validators.range(1, 65535)`.
5
+ * A contract works the same without them: `createEnv` and `validateEnv` never import this module. Any
6
+ * function with the `Processor<T>` or `Validator<T>` shape plugs in the same way.
7
7
  *
8
- * Deliberately built from explicit named imports assembled into plain object
9
- * literals, not `export * as processors from "./processors.js"`. A bundler
10
- * (tsup/esbuild) lowers that `export * as` form into a namespace-construction
11
- * helper call it can't prove side-effect-free, which defeats tree-shaking in
12
- * a *second*, downstream bundling pass (a consumer's own bundler bundling
13
- * this already-bundled package): importing only `processors` would still
14
- * ship all of `validators`' code. A plain object literal of already-imported
15
- * bindings has no such call in the way, so `import { processors } from
16
- * "@maverickcer/env-cap/helpers"` alone drops `validators` entirely.
8
+ * The two objects are plain literals of named imports, not `export * as processors`. A bundler lowers
9
+ * `export * as` into a namespace helper call it cannot prove free of side effects. That call blocks
10
+ * tree-shaking in a consumer's own bundler, so importing `processors` alone would still ship
11
+ * `validators`. With plain literals, importing `processors` alone drops `validators` entirely.
12
+ *
13
+ * @packageDocumentation
17
14
  */
18
15
  import { base64, parseJSON, split, toArray, toBigInt, toBoolean, toDate, toInteger, toLowerCase, toNumber, toRegExp, toString, toURL, toUpperCase, trim } from "./processors.js";
19
16
  import { after, all, any, before, custom, email, endsWith, finite, future, includes, integer as integerValidator, length, matches, max, maxItems, maxLength, min, minItems, minLength, negative, not, oneOf, optional, past, positive, range, refine, required, safeInteger, unique, url as urlValidator, uuid, uuidVersion } from "./validators.js";
@@ -22,7 +19,7 @@ import { after, all, any, before, custom, email, endsWith, finite, future, inclu
22
19
  * patterns (e.g. `processors.toNumber()`).
23
20
  *
24
21
  * @remarks
25
- * Naming matches `data-cap`'s `helpers.processors` -- but these
22
+ * Naming matches `data-cap`'s `helpers.processors`: but these
26
23
  * throw with a formatted `Error` message on invalid input, where data-cap's
27
24
  * silently return `undefined`. Do not assume the same failure mode when
28
25
  * moving between packages.
@@ -69,13 +66,13 @@ export declare const validators: {
69
66
  any: typeof any;
70
67
  /** Passes when the date value is strictly before `date`. */
71
68
  before: typeof before;
72
- /** Identity wrapper for a hand-written `Validator<T>` -- no behavior change, just a fluent entry point alongside the other helpers. */
69
+ /** Identity wrapper for a hand-written `Validator<T>`: no behavior change, just a fluent entry point alongside the other helpers. */
73
70
  custom: typeof custom;
74
71
  /** Passes for a plausibly-shaped email address (`local@domain`). */
75
72
  email: typeof email;
76
73
  /** Passes when the string ends with `suffix`. */
77
74
  endsWith: typeof endsWith;
78
- /** Alias for `oneOf` -- passes when the value is one of the `allowed` values. */
75
+ /** Alias for `oneOf`: passes when the value is one of the `allowed` values. */
79
76
  enum: typeof oneOf;
80
77
  /** Passes when the number is finite (rejects `Infinity`/`-Infinity`/`NaN`). */
81
78
  finite: typeof finite;
@@ -117,7 +114,7 @@ export declare const validators: {
117
114
  range: typeof range;
118
115
  /** Runs the wrapped validator but replaces its failure message with `message`. */
119
116
  refine: typeof refine;
120
- /** Alias for `matches` -- passes when the string matches `pattern`. */
117
+ /** Alias for `matches`: passes when the string matches `pattern`. */
121
118
  regex: typeof matches;
122
119
  /** Passes when the value is defined and, unless `allowEmptyString` is set, non-empty. */
123
120
  required: typeof required;
@@ -129,7 +126,7 @@ export declare const validators: {
129
126
  url: typeof urlValidator;
130
127
  /** Passes when the string is a valid UUID of one of the given `versions` (default: any of 1-8). */
131
128
  uuid: typeof uuid;
132
- /** Shorthand for `uuid([version])` -- passes only for that exact UUID version. */
129
+ /** Shorthand for `uuid([version])`: passes only for that exact UUID version. */
133
130
  uuidVersion: typeof uuidVersion;
134
131
  };
135
132
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EACL,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,EACP,QAAQ,EACR,SAAS,EACT,MAAM,EACN,SAAS,EACT,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,WAAW,EACX,IAAI,EACL,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,EACL,GAAG,EACH,GAAG,EACH,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,OAAO,IAAI,gBAAgB,EAC3B,MAAM,EACN,OAAO,EACP,GAAG,EACH,QAAQ,EACR,SAAS,EACT,GAAG,EACH,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,GAAG,EACH,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,MAAM,EACN,QAAQ,EACR,WAAW,EACX,MAAM,EACN,GAAG,IAAI,YAAY,EACnB,IAAI,EACJ,WAAW,EACZ,MAAM,iBAAiB,CAAA;AAExB;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;IACrB,+CAA+C;;IAE/C,wEAAwE;;IAExE,qGAAqG;;IAErG,qHAAqH;;IAErH,qCAAqC;;IAErC,4GAA4G;;IAE5G,oCAAoC;;IAEpC,oEAAoE;;IAEpE,mEAAmE;;IAEnE,iHAAiH;;IAEjH,wCAAwC;;IAExC,oEAAoE;;IAEpE,0EAA0E;;IAE1E,mEAAmE;;IAEnE,0FAA0F;;CAE3F,CAAA;AACD,gIAAgI;AAChI,eAAO,MAAM,UAAU;IACrB,2DAA2D;;IAE3D,0FAA0F;;IAE1F,yDAAyD;;IAEzD,4DAA4D;;IAE5D,uIAAuI;;IAEvI,oEAAoE;;IAEpE,iDAAiD;;IAEjD,iFAAiF;;IAEjF,+EAA+E;;IAE/E,+DAA+D;;IAE/D,6DAA6D;;IAE7D,4CAA4C;;IAE5C,6DAA6D;;IAE7D,8FAA8F;;IAE9F,iEAAiE;;IAEjE,yDAAyD;;IAEzD,2DAA2D;;IAE3D,oEAAoE;;IAEpE,0DAA0D;;IAE1D,4DAA4D;;IAE5D,mDAAmD;;IAEnD,oFAAoF;;IAEpF,4DAA4D;;IAE5D,yFAAyF;;IAEzF,gEAAgE;;IAEhE,mDAAmD;;IAEnD,uEAAuE;;IAEvE,kFAAkF;;IAElF,uEAAuE;;IAEvE,yFAAyF;;IAEzF,yEAAyE;;IAEzE,qDAAqD;;IAErD,sDAAsD;;IAEtD,mGAAmG;;IAEnG,kFAAkF;;CAEnF,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,EACP,QAAQ,EACR,SAAS,EACT,MAAM,EACN,SAAS,EACT,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,WAAW,EACX,IAAI,EACL,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,EACL,GAAG,EACH,GAAG,EACH,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,OAAO,IAAI,gBAAgB,EAC3B,MAAM,EACN,OAAO,EACP,GAAG,EACH,QAAQ,EACR,SAAS,EACT,GAAG,EACH,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,GAAG,EACH,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,MAAM,EACN,QAAQ,EACR,WAAW,EACX,MAAM,EACN,GAAG,IAAI,YAAY,EACnB,IAAI,EACJ,WAAW,EACZ,MAAM,iBAAiB,CAAA;AAExB;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;IACrB,+CAA+C;;IAE/C,wEAAwE;;IAExE,qGAAqG;;IAErG,qHAAqH;;IAErH,qCAAqC;;IAErC,4GAA4G;;IAE5G,oCAAoC;;IAEpC,oEAAoE;;IAEpE,mEAAmE;;IAEnE,iHAAiH;;IAEjH,wCAAwC;;IAExC,oEAAoE;;IAEpE,0EAA0E;;IAE1E,mEAAmE;;IAEnE,0FAA0F;;CAE3F,CAAA;AACD,gIAAgI;AAChI,eAAO,MAAM,UAAU;IACrB,2DAA2D;;IAE3D,0FAA0F;;IAE1F,yDAAyD;;IAEzD,4DAA4D;;IAE5D,qIAAqI;;IAErI,oEAAoE;;IAEpE,iDAAiD;;IAEjD,+EAA+E;;IAE/E,+EAA+E;;IAE/E,+DAA+D;;IAE/D,6DAA6D;;IAE7D,4CAA4C;;IAE5C,6DAA6D;;IAE7D,8FAA8F;;IAE9F,iEAAiE;;IAEjE,yDAAyD;;IAEzD,2DAA2D;;IAE3D,oEAAoE;;IAEpE,0DAA0D;;IAE1D,4DAA4D;;IAE5D,mDAAmD;;IAEnD,oFAAoF;;IAEpF,4DAA4D;;IAE5D,yFAAyF;;IAEzF,gEAAgE;;IAEhE,mDAAmD;;IAEnD,uEAAuE;;IAEvE,kFAAkF;;IAElF,qEAAqE;;IAErE,yFAAyF;;IAEzF,yEAAyE;;IAEzE,qDAAqD;;IAErD,sDAAsD;;IAEtD,mGAAmG;;IAEnG,gFAAgF;;CAEjF,CAAA"}
@@ -7,7 +7,7 @@ export declare function all<T>(...validators: Validator<T>[]): Validator<T>;
7
7
  export declare function any<T>(...validators: Validator<T>[]): Validator<T>;
8
8
  /** Passes when the date value is strictly before `date`. */
9
9
  export declare function before(date: Date): Validator<Date>;
10
- /** Identity wrapper for a hand-written `Validator<T>` -- no behavior change, just a fluent entry point alongside the other helpers. */
10
+ /** Identity wrapper for a hand-written `Validator<T>`: no behavior change, just a fluent entry point alongside the other helpers. */
11
11
  export declare function custom<T>(validator: Validator<T>): Validator<T>;
12
12
  /** Passes for a plausibly-shaped email address (`local@domain`). */
13
13
  export declare function email(): Validator<string>;
@@ -63,6 +63,6 @@ export declare function unique<T>(): Validator<T[]>;
63
63
  export declare function url(): Validator<string>;
64
64
  /** Passes when the string is a valid UUID of one of the given `versions` (default: any of 1-8). */
65
65
  export declare function uuid(versions?: readonly number[]): Validator<string>;
66
- /** Shorthand for `uuid([version])` -- passes only for that exact UUID version. */
66
+ /** Shorthand for `uuid([version])`: passes only for that exact UUID version. */
67
67
  export declare function uuidVersion(number: number): Validator<string>;
68
68
  //# sourceMappingURL=validators.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/helpers/validators.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../../src/helpers/validators.ts"],"names":[],"mappings":"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"}
@@ -1,2 +1,21 @@
1
+ /**
2
+ * The Node file system adapter for the build entry (`@maverickcer/env-cap/node`).
3
+ *
4
+ * `@maverickcer/env-cap/build` never imports `node:fs` (ADR 0040), so every generator takes the file
5
+ * system as a required `fs` option. A Node build script passes `nodeBuildFileSystem`:
6
+ *
7
+ * ```ts
8
+ * import { generateEnvArtifacts } from "@maverickcer/env-cap/build"
9
+ * import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"
10
+ *
11
+ * await generateEnvArtifacts({ fs: nodeBuildFileSystem, root, manifest: { ... } })
12
+ * ```
13
+ *
14
+ * Like `bin` and `./eslint-plugin`, this entry runs only in Node, and it is the one place the build
15
+ * path loads `node:fs/promises`. In another runtime, implement the `BuildFileSystem` type that
16
+ * `./build` exports instead.
17
+ *
18
+ * @packageDocumentation
19
+ */
1
20
  export { nodeBuildFileSystem } from "../cli/filesystem.js";
2
21
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/node/index.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA"}
@@ -6,12 +6,12 @@ import type { CreateEnvOptions, EnvContract, EnvSchema } from "./types.js";
6
6
  * @remarks
7
7
  * `createEnv` is runtime-only: `processor`/`validator`/`default` are the
8
8
  * whole vocabulary, because they're the only fields {@link validateEnv} actually
9
- * reads. Documentation -- description, ownership, lifecycle, category, and
10
- * everything else that only exists to generate docs -- lives in a separate
9
+ * reads. Documentation (description, ownership, lifecycle, category, and
10
+ * everything else that only exists to generate docs) lives in a separate
11
11
  * {@link documentEnv} call (see `document.ts`), which is entirely optional and
12
12
  * never required for this to work.
13
13
  *
14
- * @returns An {@link EnvContract} exposing one read-only getter per key -- there is no
14
+ * @returns An {@link EnvContract} exposing one read-only getter per key: there is no
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.
@@ -1,35 +1,29 @@
1
1
  import type { EnvSchema } from "./types.js";
2
2
  /**
3
- * Developer-supplied evidence assertions for one variable -- categorically
4
- * different from every field on {@link VariableDocs}: those are
5
- * declared-and-never-verified, while `dynamicAccess` is re-checked against
6
- * reality on every run (fresh / stale / missing). Kept structurally separate,
7
- * in `VariableDocs.evidence` rather than folded in alongside `description`/
8
- * `owner`/..., specifically so that different epistemic status is visible in
9
- * the shape itself and not only in a doc comment. See ADR 0037.
3
+ * Developer-supplied evidence assertions for one variable. They differ in kind from every field on
4
+ * {@link VariableDocs}, which are declared and never verified. `dynamicAccess` is re-checked against
5
+ * reality on every run (fresh / stale / missing). It lives apart, in `VariableDocs.evidence`, not
6
+ * beside `description`, `owner` and the rest. So the shape itself shows the different status, not
7
+ * only a doc comment. See ADR 0037.
10
8
  */
11
9
  export interface VariableEvidenceDocs {
12
10
  /**
13
- * Citation(s) of where this variable is actually read dynamically --
14
- * somewhere env-cap's own static AST scan can't see (a shell script, a
15
- * Docker entrypoint, a sibling service). Each entry is a
11
+ * Citation(s) of where this variable is read dynamically, somewhere env-cap's static AST scan
12
+ * can't see (a shell script, a Docker entrypoint, a sibling service). Each entry is a
16
13
  * `"<relative-path>:<line>:<column>"` citation.
17
14
  *
18
15
  * @remarks
19
- * A developer's re-acknowledgment that access happens, never a claim
20
- * env-cap itself observed anything -- tracked as its own independent fact
21
- * and never folded into the AST-derived `VariableAccessStatus`. Re-verified
22
- * every run: a citation whose file no longer exists, or whose content has
23
- * visibly changed since it was last acknowledged, is flagged rather than
24
- * trusted forever.
16
+ * A developer's re-acknowledgment that access happens, never a claim that env-cap observed
17
+ * anything. It is tracked as its own fact and never folded into the AST-derived
18
+ * `VariableAccessStatus`. It is re-verified every run. A citation whose file is gone, or whose
19
+ * content has visibly changed since it was acknowledged, is flagged rather than trusted forever.
25
20
  */
26
21
  dynamicAccess?: readonly string[];
27
22
  }
28
23
  /**
29
- * Per-variable documentation. Every field is optional and unconstrained on
30
- * purpose -- there is no required shape, so documenting a variable never
31
- * fights the type checker, and you can add a field the generator doesn't
32
- * know about yet without it being rejected.
24
+ * Per-variable documentation. Every field is optional and unconstrained on purpose. With no
25
+ * required shape, documenting a variable never fights the type checker. A field the generator
26
+ * doesn't know yet is accepted, not rejected.
33
27
  */
34
28
  export interface VariableDocs {
35
29
  /** Human-readable explanation of what this variable is and what it controls. */
@@ -41,67 +35,65 @@ export interface VariableDocs {
41
35
  * key.
42
36
  *
43
37
  * @remarks
44
- * Deliberately an open `string`, not a closed union: an org's own sensitivity vocabulary is its
45
- * own, and a level env-cap doesn't recognize is always honored, never dropped. The generator
38
+ * Deliberately an open `string`, not a closed union. An org's sensitivity vocabulary is its own,
39
+ * and a level env-cap doesn't recognize is always honored, never dropped. The generator
46
40
  * still reports a `NONSTANDARD_SENSITIVITY_LEVEL` finding (severity `info`, never blocking) for
47
41
  * anything outside `secret`/`credential`/`pii`/`config`, so vocabulary drift stays visible
48
42
  * without being enforced.
49
43
  */
50
44
  sensitivity?: string;
51
- /** ISO date string (e.g. "2026-06-01") -- when this variable's current value stops being valid (a key rotation deadline, a sunset date, etc.). */
45
+ /** ISO date string (e.g. "2026-06-01"): when this variable's current value stops being valid (a key rotation deadline, a sunset date, etc.). */
52
46
  expiresAt?: string;
53
47
  /** How to get a new value before/when it expires (e.g. "Rotate in the Stripe dashboard, then redeploy."). */
54
48
  refreshInstructions?: string;
55
49
  /**
56
50
  * 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-status
58
- * report's "authenticator type" column (IA-5's main statement requires an organization-defined
59
- * rotation period "by authenticator type," so this is what a generator groups/labels by).
51
+ * "database-password", "tls-certificate"). It feeds the "authenticator type" column of the NIST
52
+ * SP 800-53 IA-5 rotation-status report. IA-5 requires an organization-defined rotation period
53
+ * "by authenticator type," so a generator groups and labels by this field.
60
54
  *
61
55
  * @remarks
62
- * Deliberately an open `string`, not a closed union -- same "open vocabulary" pattern as
63
- * {@link sensitivity}: an org's own authenticator taxonomy is its own, and IA-5 itself never
64
- * names a fixed set of types either.
56
+ * Deliberately an open `string`, not a closed union, like {@link sensitivity}. An org's
57
+ * authenticator taxonomy is its own, and IA-5 itself names no fixed set of types.
65
58
  */
66
59
  authenticatorType?: string;
67
60
  /**
68
61
  * How often this variable's value must be rotated, in organization-defined terms (e.g. "90
69
- * days", "P90D", "6 months") -- IA-5's own "organization-defined time period" per authenticator
62
+ * days", "P90D", "6 months"). This is IA-5's "organization-defined time period" per authenticator
70
63
  * type (the time-based half of IA-5's two-trigger rotation model). Paired with
71
- * {@link lastRotatedAt} so a generator can compute whether rotation is actually current, rather
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}. 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.
64
+ * {@link lastRotatedAt}, it lets a generator compute whether rotation is current. Without it, a
65
+ * generator could only record that a period was declared. `lifecycle-model.ts`'s
66
+ * `computeRotationStatus()` shows how the two combine with {@link expiresAt}. The result is a
67
+ * policy-window judgement over declared metadata ("within the declared period"). It never states
68
+ * that a rotation happened or that a control is met. env-cap reads declarations; it does not
69
+ * check them against the secret store.
77
70
  */
78
71
  rotationPeriod?: string;
79
72
  /**
80
- * ISO date string -- the last time this variable's value was actually rotated. Paired with
73
+ * ISO date string: the last time this variable's value was actually rotated. Paired with
81
74
  * {@link rotationPeriod} to compute whether rotation is within the declared period. Independent of {@link expiresAt}, which
82
- * states when the *current* value stops being valid, not when it was last changed -- a value can
83
- * be freshly rotated and still have a near-term `expiresAt` (a short-lived token), or long overdue
84
- * for rotation while its `expiresAt` (if any) is still comfortably in the future.
75
+ * states when the *current* value stops being valid, not when it was last changed. A value can
76
+ * be freshly rotated and still have a near-term `expiresAt` (a short-lived token). It can also be
77
+ * long overdue for rotation while its `expiresAt` (if any) is still comfortably in the future.
85
78
  */
86
79
  lastRotatedAt?: string;
87
80
  /**
88
81
  * IA-5's event-based rotation triggers that apply to this variable (e.g. "suspected compromise",
89
- * "personnel change", "system update") -- the event-based half of IA-5's two-trigger rotation
90
- * model. Structured and additive alongside the existing free-text {@link refreshInstructions}
91
- * rather than replacing it: this is a list a generator can render as its own column,
92
- * `refreshInstructions` stays prose ("how to actually rotate it"). Presence-only -- env-cap has
93
- * no way to observe whether a listed event actually occurred, so declaring this never by itself
94
- * changes a computed rotation status (see `lifecycle-model.ts`); it only makes the
95
- * event-based trigger's existence visible in generated output.
82
+ * "personnel change", "system update"): the event-based half of IA-5's two-trigger rotation
83
+ * model. It sits beside the free-text {@link refreshInstructions} and does not replace it. This
84
+ * is a list a generator can render as its own column; `refreshInstructions` stays prose ("how to
85
+ * actually rotate it"). It is presence-only: env-cap cannot observe whether a listed event
86
+ * occurred. So declaring it never changes a computed rotation status by itself (see
87
+ * `lifecycle-model.ts`). It only makes the event-based trigger visible in generated output.
96
88
  */
97
89
  rotationTriggerEvents?: readonly string[];
98
90
  /**
99
- * Explicit, actionable instructions for obtaining this variable's value the *first* time --
100
- * where `refreshInstructions` is "how to rotate it once you already have one," this is "how to
101
- * get one at all" (e.g. "Create a restricted API key in the Stripe dashboard under Developers ->
102
- * API keys, scoped to read/write Charges."). A named field specifically so this can render as
103
- * its own labeled line in generated docs, rather than requiring a `metadata.setup`-style
104
- * convention with no dedicated rendering or type checking.
91
+ * Explicit, actionable instructions for obtaining this variable's value the *first* time.
92
+ * `refreshInstructions` is "how to rotate it once you already have one"; this is "how to get
93
+ * one at all" (e.g. "Create a restricted API key in the Stripe dashboard under Developers ->
94
+ * API keys, scoped to read/write Charges."). It is a named field so it renders as its own
95
+ * labeled line in generated docs. A `metadata.setup`-style convention would get no dedicated
96
+ * rendering or type checking.
105
97
  */
106
98
  setupInstructions?: string;
107
99
  /** Documentation-level assertion that this variable must be set. Independent of how (or whether) a validator actually enforces it. */
@@ -110,57 +102,56 @@ export interface VariableDocs {
110
102
  deprecated?: boolean;
111
103
  /** Why this variable is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
112
104
  deprecatedReason?: string;
113
- /** ISO date string -- by when a deprecated variable must be removed. Only meaningful alongside `deprecated: true`. */
105
+ /** ISO date string: by when a deprecated variable must be removed. Only meaningful alongside `deprecated: true`. */
114
106
  removeBy?: string;
115
107
  /** The previous environment variable name this one replaces, if this declaration is the result of a rename. Lets the Change Model correlate a remove+add pair into a single rename entry instead of two unrelated changes. */
116
108
  renamedFrom?: string;
117
- /** Why this variable's value is collected/used -- a framework-agnostic fact (pairs with `legalBasis`; a specific citation like a GDPR article belongs in `metadata` instead). Overrides the contract's own `purpose` for this key. */
109
+ /** Why this variable's value is collected/used: a framework-agnostic fact (pairs with `legalBasis`; a specific citation like a GDPR article belongs in `metadata` instead). Overrides the contract's own `purpose` for this key. */
118
110
  purpose?: string;
119
- /** The legal basis this variable's collection/use relies on -- framework-agnostic (e.g. "user consent," "contractual necessity"), never a specific statute name. Overrides the contract's own `legalBasis` for this key. */
111
+ /** The legal basis this variable's collection/use relies on: framework-agnostic (e.g. "user consent," "contractual necessity"), never a specific statute name. Overrides the contract's own `legalBasis` for this key. */
120
112
  legalBasis?: string;
121
- /** Descriptive retention policy (e.g. "delete after 90 days"). A policy statement, not a computed value -- unlike `expiresAt`, nothing parses or evaluates this. Overrides the contract's own `retention` for this key. */
113
+ /** Descriptive retention policy (e.g. "delete after 90 days"). A policy statement, not a computed value: unlike `expiresAt`, nothing parses or evaluates this. Overrides the contract's own `retention` for this key. */
122
114
  retention?: string;
123
115
  /** Where this variable's value is/must be stored (a region, or a permitted set of regions). Overrides the contract's own `dataResidency` for this key. */
124
116
  dataResidency?: string | string[];
125
117
  /** Documentation-level assertion that this variable's handling must be auditable. Overrides the contract's own `auditRequired` for this key. */
126
118
  auditRequired?: boolean;
127
119
  /**
128
- * Developer-supplied evidence assertions for this variable -- verified over
120
+ * Developer-supplied evidence assertions for this variable: verified over
129
121
  * time, unlike every other field above, which is declared and never
130
122
  * verified. Kept structurally separate for exactly that reason; see
131
123
  * {@link VariableEvidenceDocs}.
132
124
  */
133
125
  evidence?: VariableEvidenceDocs;
134
126
  /**
135
- * Structured, unsupported-key documentation -- any primitive or object value, for anything that
136
- * doesn't warrant its own named field. A previously-supported top-level key belongs in a named
137
- * field above instead of here once one exists for it.
127
+ * Structured, unsupported-key documentation: any primitive or object value, for anything that
128
+ * doesn't warrant its own named field. A key that has a named field above belongs in that field,
129
+ * not here.
138
130
  */
139
131
  metadata?: Record<string, unknown>;
140
132
  }
141
133
  /**
142
- * Contract-level documentation, plus everything {@link documentEnv}'s options used to carry that
143
- * only the generator ever read.
134
+ * Contract-level documentation. Only the generator reads these fields; validation never does.
144
135
  *
145
136
  * @remarks
146
- * Generic over `S`, the exact schema type {@link documentEnv} infers from its `schema` argument --
147
- * this is what makes `variables` below a closed, checked map (a typo'd or renamed key is a
148
- * compile error, not a silent no-op) rather than an open `Record<string, VariableDocs>` any string
149
- * would satisfy. `S` defaults to the widest possible schema so this type is still nameable on its
150
- * own (e.g. in a helper function's own parameter type) without narrowing to one specific contract.
137
+ * Generic over `S`, the exact schema type {@link documentEnv} infers from its `schema` argument.
138
+ * That makes `variables` below a closed, checked map, not an open `Record<string, VariableDocs>`
139
+ * any string would satisfy. A typo'd or renamed key is a compile error, not a silent no-op. `S`
140
+ * defaults to the widest possible schema. So this type is still nameable on its own (e.g. in a
141
+ * helper function's parameter type) without narrowing to one specific contract.
151
142
  */
152
143
  export interface ContractDocs<S extends EnvSchema = EnvSchema> {
153
144
  /** Overrides the auto-generated label used in generated docs. Purely cosmetic. Wins over `createEnv()`'s own `name` option, which in turn wins over the exported binding name. */
154
145
  name?: string;
155
146
  /** Groups this contract under a heading in the generated docs' feature catalog. */
156
147
  category?: string;
157
- /** The generator throws if two *active* contracts declare the same `exclusiveGroup` -- use it to mark interchangeable features (e.g. two database backends) as mutually exclusive. */
148
+ /** The generator throws if two *active* contracts declare the same `exclusiveGroup`: use it to mark interchangeable features (e.g. two database backends) as mutually exclusive. */
158
149
  exclusiveGroup?: string;
159
- /** When `false`, this contract is excluded from the generated manifest, docs' required section, and exclusiveGroup checks -- it still appears, marked disabled, in the feature catalog. Defaults to `true`. */
150
+ /** When `false`, this contract is excluded from the generated manifest, docs' required section, and exclusiveGroup checks: it still appears, marked disabled, in the feature catalog. Defaults to `true`. */
160
151
  active?: boolean;
161
152
  /** Default owner for every variable in this contract that doesn't set its own `owner`. */
162
153
  owner?: string;
163
- /** Default sensitivity for every variable in this contract that doesn't set its own `sensitivity` -- see {@link VariableDocs.sensitivity} for why this is an open `string`. */
154
+ /** Default sensitivity for every variable in this contract that doesn't set its own `sensitivity`: see {@link VariableDocs.sensitivity} for why this is an open `string`. */
164
155
  sensitivity?: string;
165
156
  /** Whole-contract/feature sunset date, ISO date string. */
166
157
  expiresAt?: string;
@@ -168,25 +159,25 @@ export interface ContractDocs<S extends EnvSchema = EnvSchema> {
168
159
  deprecated?: boolean;
169
160
  /** Why this contract is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
170
161
  deprecatedReason?: string;
171
- /** Default reason this contract's variables' values are collected/used -- see {@link VariableDocs.purpose}. */
162
+ /** Default reason this contract's variables' values are collected/used: see {@link VariableDocs.purpose}. */
172
163
  purpose?: string;
173
- /** Default legal basis for this contract's variables -- see {@link VariableDocs.legalBasis}. */
164
+ /** Default legal basis for this contract's variables: see {@link VariableDocs.legalBasis}. */
174
165
  legalBasis?: string;
175
- /** Default retention policy for this contract's variables -- see {@link VariableDocs.retention}. */
166
+ /** Default retention policy for this contract's variables: see {@link VariableDocs.retention}. */
176
167
  retention?: string;
177
- /** Default data residency for this contract's variables -- see {@link VariableDocs.dataResidency}. */
168
+ /** Default data residency for this contract's variables: see {@link VariableDocs.dataResidency}. */
178
169
  dataResidency?: string | string[];
179
- /** Default audit-required assertion for this contract's variables -- see {@link VariableDocs.auditRequired}. */
170
+ /** Default audit-required assertion for this contract's variables: see {@link VariableDocs.auditRequired}. */
180
171
  auditRequired?: boolean;
181
- /** Arbitrary contract-level documentation (e.g. `runbook`), rendered alongside this feature -- see {@link VariableDocs.metadata}. */
172
+ /** Arbitrary contract-level documentation (e.g. `runbook`), rendered alongside this feature: see {@link VariableDocs.metadata}. */
182
173
  metadata?: Record<string, unknown>;
183
174
  /**
184
- * Per-variable documentation, keyed by variable name -- keys are checked against `S`'s own keys
185
- * at compile time, so documenting a variable that was renamed or removed from `schema` (or a
186
- * plain typo) is a type error here, not a silently-ignored entry the generator would otherwise
187
- * have to report as "stale" after the fact. A schema key absent from `variables` entirely is
188
- * still valid (not every variable needs documentation) and is reported as undocumented by the
189
- * generator, exactly as before.
175
+ * Per-variable documentation, keyed by variable name. Keys are checked against `S`'s own keys
176
+ * at compile time. Documenting a variable that was renamed or removed from `schema` (or a plain
177
+ * typo) is therefore a type error here. The generator never has to report it as "stale" after
178
+ * the fact. A schema key absent from `variables` entirely is
179
+ * still valid (not every variable needs documentation). The generator reports it as
180
+ * undocumented.
190
181
  */
191
182
  variables?: {
192
183
  readonly [K in keyof S]?: VariableDocs;
@@ -195,29 +186,29 @@ export interface ContractDocs<S extends EnvSchema = EnvSchema> {
195
186
  /**
196
187
  * Documents a schema for the generator: explains values, assigns ownership,
197
188
  * and describes lifecycle, feeding the generated docs artifact and
198
- * `.env.example`. Pass it the *same* schema object given to {@link createEnv}, so
199
- * the generator can statically link the two and verify every variable is
200
- * documented -- and so TypeScript can check `docs.variables`' keys against
201
- * `schema`'s own keys, the same object identity doing double duty for both
202
- * the generator's static link and the type checker's.
189
+ * `.env.example`. Pass it the *same* schema object given to {@link createEnv}.
190
+ * The generator then statically links the two and verifies every variable is
191
+ * documented. TypeScript also checks `docs.variables`' keys against
192
+ * `schema`'s own keys, so the same object identity serves both the
193
+ * generator's static link and the type checker.
203
194
  *
204
195
  * @remarks
205
- * A no-op at runtime by design -- nothing passed here is retained anywhere,
196
+ * A no-op at runtime by design: nothing passed here is retained anywhere,
206
197
  * and this can never throw, no matter how malformed `schema`/`docs` are.
207
198
  * Calling it is entirely optional: {@link createEnv} works identically whether or
208
199
  * not a matching `documentEnv` call exists. The real "is everything
209
- * documented?" check, and every artifact this data drives (the docs
210
- * artifact's ownership matrix, dependency graph, lifecycle report, and
211
- * security review; `.env.example`'s comments), runs entirely inside
212
- * {@link build.generateEnvManifest}'s static analysis -- this function's only job at
213
- * runtime is to exist as a safe, harmless marker the AST parser can find,
214
- * and to give you type-checked argument shapes while writing it.
200
+ * documented?" check runs entirely inside {@link build.generateEnvManifest}'s
201
+ * static analysis. So does every artifact this data drives: the docs
202
+ * artifact's ownership matrix, dependency graph, lifecycle report and
203
+ * security review, and `.env.example`'s comments. At runtime this function
204
+ * only exists as a safe marker the AST parser can find, and gives you
205
+ * type-checked argument shapes while writing it.
215
206
  *
216
- * `S` is inferred from `schema`, never written out by hand -- pass the
207
+ * `S` is inferred from `schema`, never written out by hand. Pass the
217
208
  * schema object literal (or a `const`-inferred reference to it) directly for
218
- * the strongest inference; an explicitly-widened `schema: EnvSchema`
219
- * annotation loses the per-key literal type and falls back to accepting any
220
- * string key in `docs.variables`, same as before this generic existed.
209
+ * the strongest inference. An explicitly-widened `schema: EnvSchema`
210
+ * annotation loses the per-key literal type, so `docs.variables` then
211
+ * accepts any string key.
221
212
  */
222
213
  export declare function documentEnv<S extends EnvSchema>(schema: S, docs: ContractDocs<S>): void;
223
214
  //# sourceMappingURL=document.d.ts.map