@maverickcer/env-cap 0.7.4 → 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 (235) hide show
  1. package/ADOPTION.md +106 -124
  2. package/AGENTS.md +14 -13
  3. package/CHANGELOG.md +15 -0
  4. package/CODE_REVIEW.md +69 -173
  5. package/CONTRIBUTING.md +57 -74
  6. package/GUIDE.md +393 -872
  7. package/README.md +81 -76
  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.map +1 -1
  21. package/dist/.dts/build/lifecycle-model.d.ts +8 -3
  22. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  23. package/dist/.dts/build/sarif.d.ts.map +1 -1
  24. package/dist/.dts/helpers/index.d.ts +1 -1
  25. package/dist/.dts/runtime/create.d.ts +3 -0
  26. package/dist/.dts/runtime/create.d.ts.map +1 -1
  27. package/dist/.dts/runtime/document.d.ts +7 -4
  28. package/dist/.dts/runtime/document.d.ts.map +1 -1
  29. package/dist/.dts/runtime/index.d.ts +11 -10
  30. package/dist/.dts/runtime/index.d.ts.map +1 -1
  31. package/dist/.dts/runtime/types.d.ts +16 -0
  32. package/dist/.dts/runtime/types.d.ts.map +1 -1
  33. package/dist/.dts/runtime/validate.d.ts +14 -1
  34. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  35. package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
  36. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
  37. package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
  38. package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
  39. package/dist/.dts7/_ipc/display-path.d.ts +27 -0
  40. package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
  41. package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
  42. package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
  43. package/dist/.dts7/_ipc/glob.d.ts +22 -0
  44. package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
  45. package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
  46. package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
  47. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  48. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  49. package/dist/.dts7/_ipc/typescript.d.ts +20 -0
  50. package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
  51. package/dist/.dts7/build/assemble-project.d.ts +47 -0
  52. package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
  53. package/dist/.dts7/build/change-model.d.ts +63 -0
  54. package/dist/.dts7/build/change-model.d.ts.map +1 -0
  55. package/dist/.dts7/build/check-artifacts.d.ts +48 -0
  56. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
  57. package/dist/.dts7/build/citation-verification.d.ts +62 -0
  58. package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
  59. package/dist/.dts7/build/compatibility.d.ts +83 -0
  60. package/dist/.dts7/build/compatibility.d.ts.map +1 -0
  61. package/dist/.dts7/build/compiler-api.d.ts +12 -0
  62. package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
  63. package/dist/.dts7/build/contract-model.d.ts +93 -0
  64. package/dist/.dts7/build/contract-model.d.ts.map +1 -0
  65. package/dist/.dts7/build/deep-equal.d.ts +9 -0
  66. package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
  67. package/dist/.dts7/build/deep-freeze.d.ts +20 -0
  68. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
  69. package/dist/.dts7/build/dependency-graph.d.ts +170 -0
  70. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
  71. package/dist/.dts7/build/dependency-model.d.ts +81 -0
  72. package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
  73. package/dist/.dts7/build/discover.d.ts +41 -0
  74. package/dist/.dts7/build/discover.d.ts.map +1 -0
  75. package/dist/.dts7/build/display-path.d.ts +6 -0
  76. package/dist/.dts7/build/display-path.d.ts.map +1 -0
  77. package/dist/.dts7/build/docs.d.ts +176 -0
  78. package/dist/.dts7/build/docs.d.ts.map +1 -0
  79. package/dist/.dts7/build/env-example.d.ts +85 -0
  80. package/dist/.dts7/build/env-example.d.ts.map +1 -0
  81. package/dist/.dts7/build/errors.d.ts +78 -0
  82. package/dist/.dts7/build/errors.d.ts.map +1 -0
  83. package/dist/.dts7/build/evidence-cache.d.ts +74 -0
  84. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
  85. package/dist/.dts7/build/evidence-model.d.ts +50 -0
  86. package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
  87. package/dist/.dts7/build/evidence-reference.d.ts +67 -0
  88. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
  89. package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
  90. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
  91. package/dist/.dts7/build/exclusive-group.d.ts +19 -0
  92. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
  93. package/dist/.dts7/build/finding-model.d.ts +80 -0
  94. package/dist/.dts7/build/finding-model.d.ts.map +1 -0
  95. package/dist/.dts7/build/generate-documentation.d.ts +176 -0
  96. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
  97. package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
  98. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
  99. package/dist/.dts7/build/generate-evidence.d.ts +77 -0
  100. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
  101. package/dist/.dts7/build/generate-manifest.d.ts +101 -0
  102. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
  103. package/dist/.dts7/build/generate-usage.d.ts +95 -0
  104. package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
  105. package/dist/.dts7/build/generated-banner.d.ts +43 -0
  106. package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
  107. package/dist/.dts7/build/glob.d.ts +6 -0
  108. package/dist/.dts7/build/glob.d.ts.map +1 -0
  109. package/dist/.dts7/build/governance-fields.d.ts +34 -0
  110. package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
  111. package/dist/.dts7/build/humanize-key.d.ts +14 -0
  112. package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
  113. package/dist/.dts7/build/index.d.ts +105 -0
  114. package/dist/.dts7/build/index.d.ts.map +1 -0
  115. package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
  116. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
  117. package/dist/.dts7/build/link.d.ts +223 -0
  118. package/dist/.dts7/build/link.d.ts.map +1 -0
  119. package/dist/.dts7/build/literal-eval.d.ts +24 -0
  120. package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
  121. package/dist/.dts7/build/live-expirations.d.ts +47 -0
  122. package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
  123. package/dist/.dts7/build/manifest.d.ts +31 -0
  124. package/dist/.dts7/build/manifest.d.ts.map +1 -0
  125. package/dist/.dts7/build/map-utils.d.ts +8 -0
  126. package/dist/.dts7/build/map-utils.d.ts.map +1 -0
  127. package/dist/.dts7/build/merge-documentation.d.ts +35 -0
  128. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
  129. package/dist/.dts7/build/ownership-model.d.ts +59 -0
  130. package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
  131. package/dist/.dts7/build/parse.d.ts +207 -0
  132. package/dist/.dts7/build/parse.d.ts.map +1 -0
  133. package/dist/.dts7/build/reference-projections.d.ts +170 -0
  134. package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
  135. package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
  136. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
  137. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
  138. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
  139. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
  140. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
  141. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
  142. package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
  143. package/dist/.dts7/build/sarif.d.ts +66 -0
  144. package/dist/.dts7/build/sarif.d.ts.map +1 -0
  145. package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
  146. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
  147. package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
  148. package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
  149. package/dist/.dts7/build/source-position.d.ts +69 -0
  150. package/dist/.dts7/build/source-position.d.ts.map +1 -0
  151. package/dist/.dts7/build/tool-version.d.ts +8 -0
  152. package/dist/.dts7/build/tool-version.d.ts.map +1 -0
  153. package/dist/.dts7/build/types.d.ts +7 -0
  154. package/dist/.dts7/build/types.d.ts.map +1 -0
  155. package/dist/.dts7/build/typescript.d.ts +6 -0
  156. package/dist/.dts7/build/typescript.d.ts.map +1 -0
  157. package/dist/.dts7/build/usage-report.d.ts +124 -0
  158. package/dist/.dts7/build/usage-report.d.ts.map +1 -0
  159. package/dist/.dts7/cli/filesystem.d.ts +7 -0
  160. package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
  161. package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
  162. package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
  163. package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
  164. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
  165. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
  166. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
  167. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
  168. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
  169. package/dist/.dts7/evidence/define-projection.d.ts +52 -0
  170. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
  171. package/dist/.dts7/evidence/index.d.ts +23 -0
  172. package/dist/.dts7/evidence/index.d.ts.map +1 -0
  173. package/dist/.dts7/helpers/index.d.ts +135 -0
  174. package/dist/.dts7/helpers/index.d.ts.map +1 -0
  175. package/dist/.dts7/helpers/processors.d.ts +32 -0
  176. package/dist/.dts7/helpers/processors.d.ts.map +1 -0
  177. package/dist/.dts7/helpers/validators.d.ts +68 -0
  178. package/dist/.dts7/helpers/validators.d.ts.map +1 -0
  179. package/dist/.dts7/node/index.d.ts +2 -0
  180. package/dist/.dts7/node/index.d.ts.map +1 -0
  181. package/dist/.dts7/runtime/cache.d.ts +17 -0
  182. package/dist/.dts7/runtime/cache.d.ts.map +1 -0
  183. package/dist/.dts7/runtime/create.d.ts +23 -0
  184. package/dist/.dts7/runtime/create.d.ts.map +1 -0
  185. package/dist/.dts7/runtime/document.d.ts +223 -0
  186. package/dist/.dts7/runtime/document.d.ts.map +1 -0
  187. package/dist/.dts7/runtime/errors.d.ts +55 -0
  188. package/dist/.dts7/runtime/errors.d.ts.map +1 -0
  189. package/dist/.dts7/runtime/index.d.ts +25 -0
  190. package/dist/.dts7/runtime/index.d.ts.map +1 -0
  191. package/dist/.dts7/runtime/registry.d.ts +12 -0
  192. package/dist/.dts7/runtime/registry.d.ts.map +1 -0
  193. package/dist/.dts7/runtime/reset.d.ts +8 -0
  194. package/dist/.dts7/runtime/reset.d.ts.map +1 -0
  195. package/dist/.dts7/runtime/types.d.ts +191 -0
  196. package/dist/.dts7/runtime/types.d.ts.map +1 -0
  197. package/dist/.dts7/runtime/validate.d.ts +27 -0
  198. package/dist/.dts7/runtime/validate.d.ts.map +1 -0
  199. package/dist/{build-6XFHJFQK.js → build-DNAYWD2B.js} +8 -5
  200. package/dist/build-DNAYWD2B.js.map +1 -0
  201. package/dist/build.cjs +7 -4
  202. package/dist/build.cjs.map +1 -1
  203. package/dist/build.js +7 -4
  204. package/dist/build.js.map +1 -1
  205. package/dist/build.ts7.d.cts +1 -0
  206. package/dist/build.ts7.d.ts +1 -0
  207. package/dist/{chunk-RL5KFVUT.js → chunk-HAGMVMN5.js} +2 -2
  208. package/dist/cli/index.js +3 -3
  209. package/dist/eslint-plugin/index.cjs.map +1 -1
  210. package/dist/eslint-plugin/index.js.map +1 -1
  211. package/dist/eslint-plugin/index.ts7.d.cts +1 -0
  212. package/dist/eslint-plugin/index.ts7.d.ts +1 -0
  213. package/dist/evidence.ts7.d.cts +1 -0
  214. package/dist/evidence.ts7.d.ts +1 -0
  215. package/dist/helpers.ts7.d.cts +1 -0
  216. package/dist/helpers.ts7.d.ts +1 -0
  217. package/dist/index.cjs.map +1 -1
  218. package/dist/index.js.map +1 -1
  219. package/dist/index.ts7.d.cts +1 -0
  220. package/dist/index.ts7.d.ts +1 -0
  221. package/dist/node.ts7.d.cts +1 -0
  222. package/dist/node.ts7.d.ts +1 -0
  223. package/examples/README.md +46 -80
  224. package/package.json +27 -4
  225. package/schemas/env-cap-report.schema.json +1 -1
  226. package/skills/env-cap/SKILL.md +1 -1
  227. package/skills/env-cap/references/api.md +1 -1
  228. package/specs/architecture.md +2 -2
  229. package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
  230. package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
  231. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
  232. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
  233. package/specs/generated-artifacts.md +14 -2
  234. package/dist/build-6XFHJFQK.js.map +0 -1
  235. /package/dist/{chunk-RL5KFVUT.js.map → chunk-HAGMVMN5.js.map} +0 -0
@@ -0,0 +1,223 @@
1
+ import type { EnvSchema } from "./types.js";
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.
10
+ */
11
+ export interface VariableEvidenceDocs {
12
+ /**
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
16
+ * `"<relative-path>:<line>:<column>"` citation.
17
+ *
18
+ * @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.
25
+ */
26
+ dynamicAccess?: readonly string[];
27
+ }
28
+ /**
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.
33
+ */
34
+ export interface VariableDocs {
35
+ /** Human-readable explanation of what this variable is and what it controls. */
36
+ description?: string;
37
+ /** Who owns this variable (a team, a handle, whatever your org uses). Overrides the contract's own `owner` for this key. */
38
+ owner?: string;
39
+ /**
40
+ * How sensitive this variable's value is. Overrides the contract's own `sensitivity` for this
41
+ * key.
42
+ *
43
+ * @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
46
+ * still reports a `NONSTANDARD_SENSITIVITY_LEVEL` finding (severity `info`, never blocking) for
47
+ * anything outside `secret`/`credential`/`pii`/`config`, so vocabulary drift stays visible
48
+ * without being enforced.
49
+ */
50
+ 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.). */
52
+ expiresAt?: string;
53
+ /** How to get a new value before/when it expires (e.g. "Rotate in the Stripe dashboard, then redeploy."). */
54
+ refreshInstructions?: string;
55
+ /**
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-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).
60
+ *
61
+ * @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.
65
+ */
66
+ authenticatorType?: string;
67
+ /**
68
+ * 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
70
+ * 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.
77
+ */
78
+ rotationPeriod?: string;
79
+ /**
80
+ * ISO date string -- the last time this variable's value was actually rotated. Paired with
81
+ * {@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.
85
+ */
86
+ lastRotatedAt?: string;
87
+ /**
88
+ * 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.
96
+ */
97
+ rotationTriggerEvents?: readonly string[];
98
+ /**
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.
105
+ */
106
+ setupInstructions?: string;
107
+ /** Documentation-level assertion that this variable must be set. Independent of how (or whether) a validator actually enforces it. */
108
+ required?: boolean;
109
+ /** Marks this variable as being phased out. Independent of `expiresAt` (a rotation/sunset date) and of the contract-level `active` switch (on/off, not a phase-out signal). */
110
+ deprecated?: boolean;
111
+ /** Why this variable is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
112
+ deprecatedReason?: string;
113
+ /** ISO date string -- by when a deprecated variable must be removed. Only meaningful alongside `deprecated: true`. */
114
+ removeBy?: string;
115
+ /** 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
+ 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. */
118
+ 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. */
120
+ 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. */
122
+ retention?: string;
123
+ /** 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
+ dataResidency?: string | string[];
125
+ /** Documentation-level assertion that this variable's handling must be auditable. Overrides the contract's own `auditRequired` for this key. */
126
+ auditRequired?: boolean;
127
+ /**
128
+ * Developer-supplied evidence assertions for this variable -- verified over
129
+ * time, unlike every other field above, which is declared and never
130
+ * verified. Kept structurally separate for exactly that reason; see
131
+ * {@link VariableEvidenceDocs}.
132
+ */
133
+ evidence?: VariableEvidenceDocs;
134
+ /**
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.
138
+ */
139
+ metadata?: Record<string, unknown>;
140
+ }
141
+ /**
142
+ * Contract-level documentation, plus everything {@link documentEnv}'s options used to carry that
143
+ * only the generator ever read.
144
+ *
145
+ * @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.
151
+ */
152
+ export interface ContractDocs<S extends EnvSchema = EnvSchema> {
153
+ /** 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
+ name?: string;
155
+ /** Groups this contract under a heading in the generated docs' feature catalog. */
156
+ 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. */
158
+ 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`. */
160
+ active?: boolean;
161
+ /** Default owner for every variable in this contract that doesn't set its own `owner`. */
162
+ 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`. */
164
+ sensitivity?: string;
165
+ /** Whole-contract/feature sunset date, ISO date string. */
166
+ expiresAt?: string;
167
+ /** Marks this whole contract/feature as being phased out. Independent of `active` (on/off, not a phase-out signal). */
168
+ deprecated?: boolean;
169
+ /** Why this contract is deprecated, and/or what to use instead. Only meaningful alongside `deprecated: true`. */
170
+ deprecatedReason?: string;
171
+ /** Default reason this contract's variables' values are collected/used -- see {@link VariableDocs.purpose}. */
172
+ purpose?: string;
173
+ /** Default legal basis for this contract's variables -- see {@link VariableDocs.legalBasis}. */
174
+ legalBasis?: string;
175
+ /** Default retention policy for this contract's variables -- see {@link VariableDocs.retention}. */
176
+ retention?: string;
177
+ /** Default data residency for this contract's variables -- see {@link VariableDocs.dataResidency}. */
178
+ dataResidency?: string | string[];
179
+ /** Default audit-required assertion for this contract's variables -- see {@link VariableDocs.auditRequired}. */
180
+ auditRequired?: boolean;
181
+ /** Arbitrary contract-level documentation (e.g. `runbook`), rendered alongside this feature -- see {@link VariableDocs.metadata}. */
182
+ metadata?: Record<string, unknown>;
183
+ /**
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.
190
+ */
191
+ variables?: {
192
+ readonly [K in keyof S]?: VariableDocs;
193
+ };
194
+ }
195
+ /**
196
+ * Documents a schema for the generator: explains values, assigns ownership,
197
+ * 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.
203
+ *
204
+ * @remarks
205
+ * A no-op at runtime by design -- nothing passed here is retained anywhere,
206
+ * and this can never throw, no matter how malformed `schema`/`docs` are.
207
+ * Calling it is entirely optional: {@link createEnv} works identically whether or
208
+ * 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.
215
+ *
216
+ * `S` is inferred from `schema`, never written out by hand -- pass the
217
+ * 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.
221
+ */
222
+ export declare function documentEnv<S extends EnvSchema>(schema: S, docs: ContractDocs<S>): void;
223
+ //# sourceMappingURL=document.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../../src/runtime/document.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Every error type here is constructed only from: the variable name, the
3
+ * declaring contract's name, the failure kind, and a message string that the
4
+ * *developer's own* processor/validator produced. Raw or processed environment
5
+ * values are never read into an error -- see the Security section in the README.
6
+ *
7
+ * Documentation (description, owner, etc.) never appears here, even when a
8
+ * {@link documentEnv} call exists for this variable -- `documentEnv` is
9
+ * build-time-only and its data is never retained anywhere {@link validateEnv}
10
+ * could read it back out. This is a deliberate consequence of keeping the
11
+ * runtime minimal, not an oversight.
12
+ */
13
+ /** One variable's processing or validation failure, as recorded by {@link validateEnv}. */
14
+ export interface VariableFailure {
15
+ /** The schema key that failed. */
16
+ readonly variable: string;
17
+ /** The declaring contract's `name` (see {@link CreateEnvOptions}). */
18
+ readonly contractName: string;
19
+ /** `import.meta.url` (or similar) passed to `createEnv`'s `source` option, if any. Falls back to `contractName` when absent. */
20
+ readonly source: string | undefined;
21
+ /** Which stage produced the failure. */
22
+ readonly kind: "processor" | "validator";
23
+ /** The error message from the developer's own processor/validator, or the thrown error's message. */
24
+ readonly message: string;
25
+ }
26
+ /**
27
+ * Thrown by {@link validateEnv} when one or more variables fail processing or
28
+ * validation. Aggregates every failure across every contract in the batch --
29
+ * the caller sees the whole picture in one error, not one-at-a-time.
30
+ *
31
+ * @remarks
32
+ * `code` is a stable, Stable-tier discriminant for programmatic handling --
33
+ * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
34
+ */
35
+ export declare class EnvValidationError extends Error {
36
+ /** Stable discriminant for programmatic handling; always `"ENV_VALIDATION_FAILED"`. */
37
+ readonly code = "ENV_VALIDATION_FAILED";
38
+ /** Every variable failure across every contract in the batch. */
39
+ readonly failures: readonly VariableFailure[];
40
+ constructor(failures: readonly VariableFailure[]);
41
+ }
42
+ /**
43
+ * Thrown when a contract's value is accessed via property access before
44
+ * {@link validateEnv} has completed successfully for it.
45
+ *
46
+ * @remarks
47
+ * `code` is a stable, Stable-tier discriminant for programmatic handling --
48
+ * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
49
+ */
50
+ export declare class EnvNotReadyError extends Error {
51
+ /** Stable discriminant for programmatic handling; always `"ENV_NOT_READY"`. */
52
+ readonly code = "ENV_NOT_READY";
53
+ constructor(contractName: string, key: string);
54
+ }
55
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/runtime/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,gIAAgI;IAChI,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAAA;IACxC,qGAAqG;IACrG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAwBD;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,uFAAuF;IACvF,QAAQ,CAAC,IAAI,2BAA0B;IACvC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;gBAEjC,QAAQ,EAAE,SAAS,eAAe,EAAE;CAMjD;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,mBAAkB;gBAEnB,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAS9C"}
@@ -0,0 +1,25 @@
1
+ /**
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.
4
+ *
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.
9
+ *
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
15
+ */
16
+ export type { CreateEnvOptions, DefaultValue, EnvContract, EnvDefinition, EnvSchema, InferEnvValue, Processor, RawEnv, validateEnvOptions, validateEnvResult, Validator, } from "./types.js";
17
+ export { createEnv } from "./create.js";
18
+ export { documentEnv } from "./document.js";
19
+ export type { ContractDocs, VariableDocs, VariableEvidenceDocs } from "./document.js";
20
+ export { EnvNotReadyError, EnvValidationError } from "./errors.js";
21
+ export type { VariableFailure } from "./errors.js";
22
+ export { isEnvContract } from "./registry.js";
23
+ export { resetEnvCache } from "./reset.js";
24
+ export { validateEnv } from "./validate.js";
25
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACT,MAAM,EACN,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,GACV,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}
@@ -0,0 +1,12 @@
1
+ import type { ContractInternals } from "./types.js";
2
+ /** Associates a contract object with its internal identity/schema. Called once, by `createEnv`. */
3
+ export declare function registerContract(contract: object, internals: ContractInternals): void;
4
+ /**
5
+ * Looks up a contract's internal identity/schema.
6
+ *
7
+ * @throws {TypeError} If `contract` wasn't returned by `createEnv` (and so was never registered).
8
+ */
9
+ export declare function getContractInternals(contract: object): ContractInternals;
10
+ /** Type guard: `true` when `value` was created by `createEnv` (i.e. is a registered contract). */
11
+ export declare function isEnvContract(value: unknown): value is object;
12
+ //# sourceMappingURL=registry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/runtime/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAUnD,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAErF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CASxE;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAK7D"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Clears cached validation state. Intended for tests and dev tooling (e.g.
3
+ * `beforeEach(() => resetEnvCache())` in a test suite that re-validates with
4
+ * different fixture values per test) -- production applications validate
5
+ * once at startup and should not normally call this.
6
+ */
7
+ export declare function resetEnvCache(): void;
8
+ //# sourceMappingURL=reset.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"reset.d.ts","sourceRoot":"","sources":["../../../src/runtime/reset.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}
@@ -0,0 +1,191 @@
1
+ /**
2
+ * Core contract types for env-cap.
3
+ *
4
+ * These types are intentionally minimal: an `EnvDefinition` describes how to
5
+ * turn one raw environment value into one typed, validated application
6
+ * value. There is no `optional`/`required` flag anywhere in this file --
7
+ * requiredness is just a validator that rejects `undefined`/empty values.
8
+ *
9
+ * Documentation fields (description, owner, expiresAt, category, ...) live
10
+ * entirely in {@link documentEnv} (see `document.ts`), not here -- this file is
11
+ * the runtime's whole vocabulary, and every field in it is read by
12
+ * `validate.ts`/`create.ts`/`errors.ts` at runtime. If a field is only ever
13
+ * read by the generator, it belongs in `document.ts`, not here. `context` is
14
+ * the one exception worth calling out: it's also read by the build package
15
+ * for documentation display (see ADR 0022), but it belongs here rather than
16
+ * in `documentEnv()` because `validate.ts` reads it too, to decide pipeline
17
+ * participation -- the same bar `default`/`processor`/`validator` already
18
+ * clear.
19
+ */
20
+ /** The raw, unprocessed source of environment values (e.g. `process.env`, a resolved secrets bag). */
21
+ export type RawEnv = Readonly<Record<string, unknown>>;
22
+ /** Processes a raw value into a typed, ready-to-use application value. Must not read any other key. */
23
+ export type Processor<T> = (value: unknown) => T;
24
+ /**
25
+ * Validates an already-processed value; return `true` when valid, or a human-readable error
26
+ * string when invalid.
27
+ *
28
+ * @remarks
29
+ * Receives the full raw env for conditional validation (e.g. "required only if X").
30
+ */
31
+ export type Validator<T> = (value: T, rawEnv: RawEnv) => true | string;
32
+ /**
33
+ * A default may be a literal value, or a zero-arg thunk evaluated lazily when the raw value is
34
+ * undefined.
35
+ *
36
+ * @remarks
37
+ * The union is redundant at the type level (`unknown` alone already accepts a
38
+ * function) -- it's kept because this type is public API, and collapsing it to bare `unknown`
39
+ * would erase the one thing a reader of the generated `.d.ts` needs to learn here.
40
+ */
41
+ export type DefaultValue = unknown | (() => unknown);
42
+ /** Configuration for one schema entry: how to default, process, and validate a single raw environment value. */
43
+ export interface EnvDefinition<T> {
44
+ /** Literal fallback or lazy thunk used when the raw value is `undefined`. */
45
+ default?: DefaultValue;
46
+ /** Converts the raw (or defaulted) value to `T`; passed through unprocessed when omitted. */
47
+ processor?: Processor<T>;
48
+ /** Rejects an invalid processed value; return `true` to accept it. */
49
+ validator?: Validator<T>;
50
+ /**
51
+ * The validation context this variable belongs to (e.g. `"server"`,
52
+ * `"production"`, `"worker"`) -- entirely application-defined; env-cap
53
+ * never interprets, detects, or infers this string. Omitted (the
54
+ * default) means the variable participates in every {@link validateEnv}
55
+ * run regardless of `activeContexts`. A variable belongs to at most one
56
+ * validation context -- see ADR 0022 for why this is a single `string`
57
+ * and not `string[]`; do not widen it to an array to let one variable
58
+ * join multiple contexts, that reintroduces the AND/OR ambiguity this
59
+ * design deliberately avoids.
60
+ *
61
+ * @remarks
62
+ * Validation contexts are a participation filter only -- not
63
+ * authentication, authorization, or a bundling/security boundary. See
64
+ * ADR 0022's Formal Invariants.
65
+ */
66
+ context?: string;
67
+ }
68
+ /**
69
+ * A schema is a map of variable name -> definition.
70
+ *
71
+ * @remarks
72
+ * `EnvDefinition<any>` is used only as the generic *bound* here (never surfaced to consumers):
73
+ * TypeScript infers a precise, per-key literal type for `S` from the object passed to
74
+ * {@link createEnv}, so the resolved contract type (see {@link InferEnvValue}) stays fully
75
+ * strict. This is the same variance workaround used by schema libraries like zod/trpc for
76
+ * heterogeneous generic maps.
77
+ */
78
+ export type EnvSchema = Record<string, EnvDefinition<any>>;
79
+ type UnwrapDefault<D> = D extends {
80
+ default: infer Def;
81
+ } ? Def extends () => infer R ? R : Def : never;
82
+ /**
83
+ * Resolves the application-facing type for one schema entry: processor return type, else the
84
+ * default's type, else `string` (the shape raw process.env values naturally arrive in).
85
+ *
86
+ * @remarks
87
+ * Same documented generic-bound variance workaround as {@link EnvSchema} above --
88
+ * `any` here is never surfaced to a consumer's inferred type.
89
+ */
90
+ export type InferEnvValue<D extends EnvDefinition<any>> = D extends {
91
+ /** Narrows to the processor's return type when one is present. */
92
+ processor: Processor<infer P>;
93
+ } ? P : [UnwrapDefault<D>] extends [never] ? string : UnwrapDefault<D>;
94
+ /** The internal, non-enumerable identity + metadata attached to every contract created by `createEnv`. */
95
+ export interface ContractInternals<S extends EnvSchema = EnvSchema> {
96
+ readonly id: symbol;
97
+ readonly name: string;
98
+ readonly source: string | undefined;
99
+ readonly schema: S;
100
+ }
101
+ /**
102
+ * The object returned by {@link createEnv}. Each key is a lazily-resolved getter backed by the
103
+ * runtime cache -- there is no global env object, only per-feature contracts like this one.
104
+ *
105
+ * @remarks
106
+ * `toString()` is intersected in (rather than left to the ambient `Object.prototype`
107
+ * declaration) because `create.ts` genuinely overrides it to return a redacted
108
+ * `EnvContract("name")` representation, never resolved values -- see ADR 0006. Declaring
109
+ * it here means the type accurately describes what calling `String(contract)` returns.
110
+ */
111
+ export type EnvContract<S extends EnvSchema> = {
112
+ readonly [K in keyof S]: InferEnvValue<S[K]>;
113
+ } & {
114
+ /** Returns the redacted `EnvContract("name")` representation, never resolved values -- see ADR 0006. */
115
+ toString(): string;
116
+ };
117
+ /**
118
+ * What {@link validateEnv} validates: the generated manifest, the raw values, and the active
119
+ * validation contexts.
120
+ *
121
+ * @remarks
122
+ * Only the first call in a process is used; later calls return its outcome, whatever options
123
+ * they pass. Call `resetEnvCache()` between runs in a test.
124
+ */
125
+ export interface validateEnvOptions {
126
+ /** The raw source of environment values, e.g. `process.env` or a resolved secrets bag. */
127
+ values: RawEnv;
128
+ /**
129
+ * Every contract to validate -- typically the `contracts` array imported
130
+ * from a generated manifest (see {@link build.generateEnvManifest}). Pass all of them
131
+ * in one call: {@link validateEnv} only ever initializes once per process, so
132
+ * a second call returns the first call's cached result without
133
+ * re-running anything, even if it passes a different manifest.
134
+ */
135
+ manifest: readonly EnvContract<any>[];
136
+ /**
137
+ * The validation contexts active for this run (e.g. `["server",
138
+ * "production"]`) -- entirely application-defined; env-cap never
139
+ * detects or infers these, the caller always computes and passes them
140
+ * explicitly. A variable whose `context` isn't in this list is skipped
141
+ * entirely (no default/processor/validator runs for it, and it stays in
142
+ * its not-ready state, exactly as if this run had never happened for
143
+ * it) -- see ADR 0022. A variable with no `context` always participates,
144
+ * regardless of what's passed here. Omitted (the default) behaves as an
145
+ * empty list: only variables with no `context` participate.
146
+ *
147
+ * @remarks
148
+ * Not part of the validation cache's identity -- {@link validateEnv}
149
+ * remains one-shot per process exactly as before this option existed. A
150
+ * second call does not re-evaluate `activeContexts`; it returns the
151
+ * first call's result outright. Different active contexts belong to
152
+ * different processes (e.g. a server process and a browser bundle),
153
+ * never to two calls within the same one.
154
+ */
155
+ activeContexts?: readonly string[];
156
+ }
157
+ /** Aggregate counts from a completed {@link validateEnv} run. */
158
+ export interface validateEnvResult {
159
+ /** Number of contracts in the manifest that were validated. */
160
+ readonly contractCount: number;
161
+ /** Total number of variables validated across all contracts. */
162
+ readonly variableCount: number;
163
+ }
164
+ /**
165
+ * Options for {@link createEnv}: a display name for error messages and where the contract was
166
+ * declared.
167
+ *
168
+ * @remarks
169
+ * Purely for identification. Owners, descriptions and other documentation belong in
170
+ * `documentEnv()`.
171
+ */
172
+ export interface CreateEnvOptions {
173
+ /**
174
+ * A short, stable label for this contract (e.g. "payments", "database").
175
+ * Used in error messages. Defaults to an auto-generated anonymous label if
176
+ * omitted -- providing one is strongly recommended for readable validation
177
+ * errors.
178
+ */
179
+ name?: string;
180
+ /**
181
+ * Pass `import.meta.url` here so validation errors point at the file that
182
+ * declared the failing variable (e.g. "features/payments/env.schema.ts")
183
+ * instead of just the short `name` label. There is no portable way for
184
+ * `createEnv` to discover its caller's module URL on its own -- this is
185
+ * always correct and never goes stale, since it's supplied by the JS
186
+ * engine rather than hand-typed.
187
+ */
188
+ source?: string;
189
+ }
190
+ export {};
191
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/runtime/types.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,27 @@
1
+ import type { validateEnvOptions, validateEnvResult } from "./types.js";
2
+ /**
3
+ * Validates every variable in every contract in `options.manifest` against
4
+ * `options.values`, then caches the results.
5
+ *
6
+ * @remarks
7
+ * Idempotent: the first successful (or failed) call is authoritative for the life of the
8
+ * process -- later calls return (or re-throw) that same outcome without re-running any
9
+ * processor or validator. Concurrent in-flight calls share one underlying run. Call
10
+ * `resetEnvCache()` to validate again, for example between test scenarios.
11
+ *
12
+ * The record of validated values is frozen, but only one level deep: an object, array or `URL`
13
+ * a processor returns stays mutable. A failure message carries variable and contract names and
14
+ * the message your processor or validator produced, never the value itself.
15
+ *
16
+ * @example
17
+ * ```ts
18
+ * import { validateEnv } from "@maverickcer/env-cap"
19
+ * import { manifest } from "./generated/env.manifest"
20
+ *
21
+ * await validateEnv({ manifest, values: process.env })
22
+ * ```
23
+ *
24
+ * @throws {EnvValidationError} If any variable fails processing or validation.
25
+ */
26
+ export declare function validateEnv(options: validateEnvOptions): Promise<validateEnvResult>;
27
+ //# sourceMappingURL=validate.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/runtime/validate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEvE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0BzF"}
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  readToolVersion
4
- } from "./chunk-RL5KFVUT.js";
4
+ } from "./chunk-HAGMVMN5.js";
5
5
 
6
6
  // src/build/evidence-snapshot.ts
7
7
  import path3 from "path";
@@ -5098,15 +5098,18 @@ async function checkEnvArtifacts(options) {
5098
5098
  function sarifLevel(severity) {
5099
5099
  return severity === "info" ? "note" : severity;
5100
5100
  }
5101
+ function uriReference(file) {
5102
+ return encodeURI(file).replace(/#/g, "%23").replace(/\?/g, "%3F");
5103
+ }
5101
5104
  function sarifLocations(finding) {
5102
5105
  const location = finding.location;
5103
- const uri = location.model === "change" ? location.path : location.file;
5104
- if (uri === void 0) return void 0;
5105
5106
  const { position } = location;
5107
+ const file = position?.file ?? (location.model === "change" ? location.path : location.file);
5108
+ if (file === void 0) return void 0;
5106
5109
  return [
5107
5110
  {
5108
5111
  physicalLocation: {
5109
- artifactLocation: { uri },
5112
+ artifactLocation: { uri: uriReference(file) },
5110
5113
  ...position === void 0 ? {} : { region: { startLine: position.line, startColumn: position.column } }
5111
5114
  }
5112
5115
  }
@@ -5205,4 +5208,4 @@ export {
5205
5208
  resolveRelativeImport,
5206
5209
  writeEnvExample
5207
5210
  };
5208
- //# sourceMappingURL=build-6XFHJFQK.js.map
5211
+ //# sourceMappingURL=build-DNAYWD2B.js.map