@maverickcer/env-cap 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (195) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +279 -0
  3. package/dist/.dts/build/assemble-project.d.ts +47 -0
  4. package/dist/.dts/build/assemble-project.d.ts.map +1 -0
  5. package/dist/.dts/build/change-model.d.ts +62 -0
  6. package/dist/.dts/build/change-model.d.ts.map +1 -0
  7. package/dist/.dts/build/check-artifacts.d.ts +48 -0
  8. package/dist/.dts/build/check-artifacts.d.ts.map +1 -0
  9. package/dist/.dts/build/citation-verification.d.ts +62 -0
  10. package/dist/.dts/build/citation-verification.d.ts.map +1 -0
  11. package/dist/.dts/build/compatibility.d.ts +76 -0
  12. package/dist/.dts/build/compatibility.d.ts.map +1 -0
  13. package/dist/.dts/build/contract-model.d.ts +92 -0
  14. package/dist/.dts/build/contract-model.d.ts.map +1 -0
  15. package/dist/.dts/build/deep-equal.d.ts +9 -0
  16. package/dist/.dts/build/deep-equal.d.ts.map +1 -0
  17. package/dist/.dts/build/deep-freeze.d.ts +20 -0
  18. package/dist/.dts/build/deep-freeze.d.ts.map +1 -0
  19. package/dist/.dts/build/dependency-graph.d.ts +168 -0
  20. package/dist/.dts/build/dependency-graph.d.ts.map +1 -0
  21. package/dist/.dts/build/dependency-model.d.ts +79 -0
  22. package/dist/.dts/build/dependency-model.d.ts.map +1 -0
  23. package/dist/.dts/build/discover.d.ts +25 -0
  24. package/dist/.dts/build/discover.d.ts.map +1 -0
  25. package/dist/.dts/build/display-path.d.ts +24 -0
  26. package/dist/.dts/build/display-path.d.ts.map +1 -0
  27. package/dist/.dts/build/docs.d.ts +176 -0
  28. package/dist/.dts/build/docs.d.ts.map +1 -0
  29. package/dist/.dts/build/env-example.d.ts +85 -0
  30. package/dist/.dts/build/env-example.d.ts.map +1 -0
  31. package/dist/.dts/build/errors.d.ts +78 -0
  32. package/dist/.dts/build/errors.d.ts.map +1 -0
  33. package/dist/.dts/build/evidence-cache.d.ts +74 -0
  34. package/dist/.dts/build/evidence-cache.d.ts.map +1 -0
  35. package/dist/.dts/build/evidence-model.d.ts +50 -0
  36. package/dist/.dts/build/evidence-model.d.ts.map +1 -0
  37. package/dist/.dts/build/evidence-reference.d.ts +67 -0
  38. package/dist/.dts/build/evidence-reference.d.ts.map +1 -0
  39. package/dist/.dts/build/evidence-snapshot.d.ts +123 -0
  40. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -0
  41. package/dist/.dts/build/exclusive-group.d.ts +19 -0
  42. package/dist/.dts/build/exclusive-group.d.ts.map +1 -0
  43. package/dist/.dts/build/finding-model.d.ts +79 -0
  44. package/dist/.dts/build/finding-model.d.ts.map +1 -0
  45. package/dist/.dts/build/generate-documentation.d.ts +176 -0
  46. package/dist/.dts/build/generate-documentation.d.ts.map +1 -0
  47. package/dist/.dts/build/generate-env-artifacts.d.ts +176 -0
  48. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -0
  49. package/dist/.dts/build/generate-evidence.d.ts +77 -0
  50. package/dist/.dts/build/generate-evidence.d.ts.map +1 -0
  51. package/dist/.dts/build/generate-manifest.d.ts +101 -0
  52. package/dist/.dts/build/generate-manifest.d.ts.map +1 -0
  53. package/dist/.dts/build/generate-usage.d.ts +95 -0
  54. package/dist/.dts/build/generate-usage.d.ts.map +1 -0
  55. package/dist/.dts/build/generated-banner.d.ts +52 -0
  56. package/dist/.dts/build/generated-banner.d.ts.map +1 -0
  57. package/dist/.dts/build/glob.d.ts +18 -0
  58. package/dist/.dts/build/glob.d.ts.map +1 -0
  59. package/dist/.dts/build/governance-fields.d.ts +34 -0
  60. package/dist/.dts/build/governance-fields.d.ts.map +1 -0
  61. package/dist/.dts/build/humanize-key.d.ts +14 -0
  62. package/dist/.dts/build/humanize-key.d.ts.map +1 -0
  63. package/dist/.dts/build/index.d.ts +107 -0
  64. package/dist/.dts/build/index.d.ts.map +1 -0
  65. package/dist/.dts/build/lifecycle-model.d.ts +64 -0
  66. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -0
  67. package/dist/.dts/build/link.d.ts +215 -0
  68. package/dist/.dts/build/link.d.ts.map +1 -0
  69. package/dist/.dts/build/literal-eval.d.ts +23 -0
  70. package/dist/.dts/build/literal-eval.d.ts.map +1 -0
  71. package/dist/.dts/build/live-expirations.d.ts +47 -0
  72. package/dist/.dts/build/live-expirations.d.ts.map +1 -0
  73. package/dist/.dts/build/manifest-snapshot.d.ts +229 -0
  74. package/dist/.dts/build/manifest-snapshot.d.ts.map +1 -0
  75. package/dist/.dts/build/manifest.d.ts +31 -0
  76. package/dist/.dts/build/manifest.d.ts.map +1 -0
  77. package/dist/.dts/build/map-utils.d.ts +8 -0
  78. package/dist/.dts/build/map-utils.d.ts.map +1 -0
  79. package/dist/.dts/build/ownership-model.d.ts +57 -0
  80. package/dist/.dts/build/ownership-model.d.ts.map +1 -0
  81. package/dist/.dts/build/parse.d.ts +199 -0
  82. package/dist/.dts/build/parse.d.ts.map +1 -0
  83. package/dist/.dts/build/reference-projections.d.ts +156 -0
  84. package/dist/.dts/build/reference-projections.d.ts.map +1 -0
  85. package/dist/.dts/build/resolution/resolve-import.d.ts +53 -0
  86. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -0
  87. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +83 -0
  88. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -0
  89. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +101 -0
  90. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
  91. package/dist/.dts/build/resolution/resolve-within-root.d.ts +35 -0
  92. package/dist/.dts/build/resolution/resolve-within-root.d.ts.map +1 -0
  93. package/dist/.dts/build/resolve-import.d.ts +50 -0
  94. package/dist/.dts/build/resolve-import.d.ts.map +1 -0
  95. package/dist/.dts/build/resolve-package-schema.d.ts +99 -0
  96. package/dist/.dts/build/resolve-package-schema.d.ts.map +1 -0
  97. package/dist/.dts/build/resolve-tsconfig-paths.d.ts +100 -0
  98. package/dist/.dts/build/resolve-tsconfig-paths.d.ts.map +1 -0
  99. package/dist/.dts/build/resolve-within-root.d.ts +35 -0
  100. package/dist/.dts/build/resolve-within-root.d.ts.map +1 -0
  101. package/dist/.dts/build/sarif.d.ts +66 -0
  102. package/dist/.dts/build/sarif.d.ts.map +1 -0
  103. package/dist/.dts/build/scan-dependencies.d.ts +47 -0
  104. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -0
  105. package/dist/.dts/build/sort-by-identity.d.ts +14 -0
  106. package/dist/.dts/build/sort-by-identity.d.ts.map +1 -0
  107. package/dist/.dts/build/source-position.d.ts +69 -0
  108. package/dist/.dts/build/source-position.d.ts.map +1 -0
  109. package/dist/.dts/build/tool-version.d.ts +8 -0
  110. package/dist/.dts/build/tool-version.d.ts.map +1 -0
  111. package/dist/.dts/build/types.d.ts +53 -0
  112. package/dist/.dts/build/types.d.ts.map +1 -0
  113. package/dist/.dts/build/usage-report.d.ts +124 -0
  114. package/dist/.dts/build/usage-report.d.ts.map +1 -0
  115. package/dist/.dts/cli/filesystem.d.ts +3 -0
  116. package/dist/.dts/cli/filesystem.d.ts.map +1 -0
  117. package/dist/.dts/eslint-plugin/glob.d.ts +18 -0
  118. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -0
  119. package/dist/.dts/eslint-plugin/index.d.ts +27 -0
  120. package/dist/.dts/eslint-plugin/index.d.ts.map +1 -0
  121. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +25 -0
  122. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -0
  123. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +23 -0
  124. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
  125. package/dist/.dts/evidence/define-projection.d.ts +51 -0
  126. package/dist/.dts/evidence/define-projection.d.ts.map +1 -0
  127. package/dist/.dts/evidence/index.d.ts +23 -0
  128. package/dist/.dts/evidence/index.d.ts.map +1 -0
  129. package/dist/.dts/helpers/index.d.ts +135 -0
  130. package/dist/.dts/helpers/index.d.ts.map +1 -0
  131. package/dist/.dts/helpers/processors.d.ts +32 -0
  132. package/dist/.dts/helpers/processors.d.ts.map +1 -0
  133. package/dist/.dts/helpers/validators.d.ts +68 -0
  134. package/dist/.dts/helpers/validators.d.ts.map +1 -0
  135. package/dist/.dts/node/index.d.ts +2 -0
  136. package/dist/.dts/node/index.d.ts.map +1 -0
  137. package/dist/.dts/runtime/cache.d.ts +20 -0
  138. package/dist/.dts/runtime/cache.d.ts.map +1 -0
  139. package/dist/.dts/runtime/create.d.ts +20 -0
  140. package/dist/.dts/runtime/create.d.ts.map +1 -0
  141. package/dist/.dts/runtime/document.d.ts +181 -0
  142. package/dist/.dts/runtime/document.d.ts.map +1 -0
  143. package/dist/.dts/runtime/errors.d.ts +55 -0
  144. package/dist/.dts/runtime/errors.d.ts.map +1 -0
  145. package/dist/.dts/runtime/index.d.ts +24 -0
  146. package/dist/.dts/runtime/index.d.ts.map +1 -0
  147. package/dist/.dts/runtime/registry.d.ts +12 -0
  148. package/dist/.dts/runtime/registry.d.ts.map +1 -0
  149. package/dist/.dts/runtime/reset.d.ts +8 -0
  150. package/dist/.dts/runtime/reset.d.ts.map +1 -0
  151. package/dist/.dts/runtime/types.d.ts +175 -0
  152. package/dist/.dts/runtime/types.d.ts.map +1 -0
  153. package/dist/.dts/runtime/validate.d.ts +14 -0
  154. package/dist/.dts/runtime/validate.d.ts.map +1 -0
  155. package/dist/build.cjs +83 -0
  156. package/dist/build.cjs.map +1 -0
  157. package/dist/build.d.cts +1 -0
  158. package/dist/build.d.ts +1 -0
  159. package/dist/build.js +19 -0
  160. package/dist/build.js.map +1 -0
  161. package/dist/cli/index.js +134 -0
  162. package/dist/cli/index.js.map +1 -0
  163. package/dist/eslint-plugin/index.cjs +12 -0
  164. package/dist/eslint-plugin/index.cjs.map +1 -0
  165. package/dist/eslint-plugin/index.d.cts +1 -0
  166. package/dist/eslint-plugin/index.d.ts +1 -0
  167. package/dist/eslint-plugin/index.js +5 -0
  168. package/dist/eslint-plugin/index.js.map +1 -0
  169. package/dist/evidence.cjs +7 -0
  170. package/dist/evidence.cjs.map +1 -0
  171. package/dist/evidence.d.cts +1 -0
  172. package/dist/evidence.d.ts +1 -0
  173. package/dist/evidence.js +5 -0
  174. package/dist/evidence.js.map +1 -0
  175. package/dist/helpers.cjs +8 -0
  176. package/dist/helpers.cjs.map +1 -0
  177. package/dist/helpers.d.cts +1 -0
  178. package/dist/helpers.d.ts +1 -0
  179. package/dist/helpers.js +5 -0
  180. package/dist/helpers.js.map +1 -0
  181. package/dist/index.cjs +15 -0
  182. package/dist/index.cjs.map +1 -0
  183. package/dist/index.d.cts +1 -0
  184. package/dist/index.d.ts +1 -0
  185. package/dist/index.js +7 -0
  186. package/dist/index.js.map +1 -0
  187. package/dist/node.cjs +13 -0
  188. package/dist/node.cjs.map +1 -0
  189. package/dist/node.d.cts +1 -0
  190. package/dist/node.d.ts +1 -0
  191. package/dist/node.js +7 -0
  192. package/dist/node.js.map +1 -0
  193. package/package.json +183 -0
  194. package/schemas/contract-model.schema.json +321 -0
  195. package/schemas/env-cap-report.schema.json +2369 -0
@@ -0,0 +1,69 @@
1
+ import type ts from "typescript";
2
+ /**
3
+ * A precise pointer into a source file -- the shared shape every exact-position fact in the
4
+ * build pipeline (declaration sites, usage sites, dynamic-access sites) uses, so a consumer never
5
+ * has to reconcile three ad hoc `{ file; line; column }` shapes that happen to mean the same
6
+ * thing. See ADR 0036.
7
+ */
8
+ export interface SourcePosition {
9
+ /** Root-relative, POSIX-separated. */
10
+ readonly file: string;
11
+ /** 1-indexed line number. */
12
+ readonly line: number;
13
+ /** 1-indexed column number. */
14
+ readonly column: number;
15
+ }
16
+ /**
17
+ * `node`'s starting line/column within `sourceFile`, both 1-indexed -- TypeScript's own
18
+ * `getLineAndCharacterOfPosition()` returns 0-indexed values for both. Callers combine this with
19
+ * the file path they already have in scope to build a full {@link SourcePosition}; this returns
20
+ * only the two numbers so it's usable identically whether the caller's `file` is already
21
+ * root-relative or still absolute.
22
+ */
23
+ export declare function positionOf(sourceFile: ts.SourceFile, node: ts.Node): {
24
+ line: number;
25
+ column: number;
26
+ };
27
+ /**
28
+ * Parses a developer-supplied `"<relative-path>:<line>:<column>"` citation
29
+ * (a {@link runtime.VariableDocs.dynamicAccess} entry) into a
30
+ * {@link SourcePosition}. Splits on the *last* two colons so a path
31
+ * containing colons of its own (rare, but not impossible) still parses --
32
+ * only the trailing `:<line>:<column>` is treated as position syntax.
33
+ * Returns `undefined` for anything that isn't exactly that shape (missing
34
+ * segments, a non-positive-integer line/column, an empty path) -- callers
35
+ * treat that as a malformed citation, never a thrown error. See ADR 0037.
36
+ */
37
+ export declare function parsePositionCitation(citation: string): SourcePosition | undefined;
38
+ /**
39
+ * One developer-declared {@link runtime.VariableDocs.dynamicAccess} citation's
40
+ * current acknowledgment state -- a claim, never an observation. Kept fully
41
+ * separate from `VariableAccessStatus` (which stays exactly 3-valued and
42
+ * purely AST-derived) so a developer's assertion can never make env-cap
43
+ * claim it observed something it didn't. See
44
+ * `evidence-snapshot.ts`'s `computeDynamicAccessAcknowledgments()` (where
45
+ * this is computed) and ADR 0037.
46
+ */
47
+ export interface DynamicAccessAssertion extends SourcePosition {
48
+ /**
49
+ * `"fresh"` -- the cited file currently exists and either matches the
50
+ * committed baseline hash or has no baseline yet (a brand-new citation,
51
+ * nothing to contradict it yet). `"stale"` -- the cited file exists but its
52
+ * content has changed since the committed baseline. `"missing"` -- the
53
+ * cited file no longer exists at all. Re-derived from scratch every run;
54
+ * never cached across runs.
55
+ */
56
+ readonly acknowledgment: "fresh" | "stale" | "missing";
57
+ /**
58
+ * SHA-256 hex digest of the cited file's content *as observed this run* --
59
+ * `undefined` iff `acknowledgment === "missing"` (nothing to hash). This is
60
+ * the one field that makes freshness checking possible without a
61
+ * snapshot-only shadow type: the live `EvidenceModel.dependency` a caller
62
+ * gets back and the persisted evidence snapshot a later run reads back as
63
+ * its baseline are the exact same shape -- this run's `contentHash` becomes
64
+ * next run's comparison target directly. See `evidence-snapshot.ts` and
65
+ * ADR 0037.
66
+ */
67
+ readonly contentHash: string | undefined;
68
+ }
69
+ //# sourceMappingURL=source-position.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"source-position.d.ts","sourceRoot":"","sources":["../../../src/build/source-position.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,IAAI,EAAE,EAAE,CAAC,IAAI,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAGlC;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAQlF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAA;IACtD;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;CACzC"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * env-cap's own installed version -- stamped onto
3
+ * `EvidenceModel.provenance.toolVersion` and mixed into
4
+ * `computeSourceFingerprint()`. `./build` never reads its own manifest from
5
+ * disk (ADR 0040).
6
+ */
7
+ export declare function readToolVersion(): string;
8
+ //# sourceMappingURL=tool-version.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tool-version.d.ts","sourceRoot":"","sources":["../../../src/build/tool-version.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC"}
@@ -0,0 +1,53 @@
1
+ /**
2
+ * The filesystem capability `env-cap/build` requires from its caller.
3
+ *
4
+ * `./build` is a **library surface**: it must not acquire filesystem access
5
+ * implicitly (no `node:fs` import anywhere under `src/` outside `src/cli/`).
6
+ * Every public options object in `build/index.ts` carries a required `fs`
7
+ * field of this type, and the caller supplies a concrete adapter -- the
8
+ * `env-cap` CLI builds one over `node:fs/promises` (`src/cli/filesystem.ts`);
9
+ * a test builds either that same real adapter or an in-memory fake. See ADR
10
+ * 0040.
11
+ *
12
+ * "Ambient-fs-free" means specifically: `./build` never reaches for
13
+ * `node:fs` itself. It still performs real filesystem operations -- the
14
+ * capability is always handed in.
15
+ *
16
+ * The shape is modeled on `node:fs/promises`'s own signatures so a thin
17
+ * adapter is a drop-in value, but uses minimal structural types
18
+ * ({@link BuildDirent}/{@link BuildStats}) rather than Node's `Dirent`/
19
+ * `Stats` -- the capability boundary shouldn't leak Node's type surface just
20
+ * because the concrete adapter happens to be Node-backed. Only the
21
+ * operations `src/build/**` actually calls are here.
22
+ */
23
+ export interface BuildFileSystem {
24
+ /** Read a UTF-8 text file. Rejects if the path doesn't exist or isn't readable. */
25
+ readonly readFile: (path: string, encoding: "utf8") => Promise<string>;
26
+ /** Write a UTF-8 text file, creating or truncating it. The parent directory must already exist. */
27
+ readonly writeFile: (path: string, data: string, encoding: "utf8") => Promise<void>;
28
+ /** Create a directory and every missing parent. A no-op if it already exists. */
29
+ readonly mkdir: (path: string, options: {
30
+ readonly recursive: true;
31
+ }) => Promise<void>;
32
+ /** List a directory's entries with their file-type info. */
33
+ readonly readdir: (path: string, options: {
34
+ readonly withFileTypes: true;
35
+ }) => Promise<readonly BuildDirent[]>;
36
+ /** Stat a path (following symlinks). Rejects if the path doesn't exist. */
37
+ readonly stat: (path: string) => Promise<BuildStats>;
38
+ /** Resolve a path to its canonical, symlink-free absolute form. */
39
+ readonly realpath: (path: string) => Promise<string>;
40
+ }
41
+ /** One directory entry from {@link BuildFileSystem.readdir} -- the subset of Node's `Dirent` `src/build/**` reads. */
42
+ export interface BuildDirent {
43
+ readonly name: string;
44
+ readonly isDirectory: () => boolean;
45
+ readonly isFile: () => boolean;
46
+ }
47
+ /** A path's stat info from {@link BuildFileSystem.stat} -- the subset of Node's `Stats` `src/build/**` reads. */
48
+ export interface BuildStats {
49
+ readonly isFile: () => boolean;
50
+ /** Size in bytes -- read by the package-schema resolver to enforce a size ceiling. */
51
+ readonly size: number;
52
+ }
53
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/build/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACtE,mGAAmG;IACnG,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnF,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACtF,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAA;KAAE,KACtC,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IACpD,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CACrD;AAED,sHAAsH;AACtH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;CAC/B;AAED,iHAAiH;AACjH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB"}
@@ -0,0 +1,124 @@
1
+ import type { ScannedSurface } from "./dependency-graph.js";
2
+ import type { DynamicAccessCitationProblem } from "./citation-verification.js";
3
+ import type { ParseWarning } from "./parse.js";
4
+ import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
5
+ /** One contract's dependency-ownership summary: who owns it, and who depends on it. */
6
+ export interface OwnershipDependencyEntry {
7
+ /** Resolved display name (see {@link DiscoveredContract.contractName}). */
8
+ readonly contractName: string;
9
+ /** Root-relative path of the file declaring the contract. */
10
+ readonly file: string;
11
+ /** Contract-level default owner, if set. */
12
+ readonly owner: string | undefined;
13
+ /** Number of variables declared in this contract's schema. */
14
+ readonly variableCount: number;
15
+ /** Files coupled to this contract (imported it, referenced it, or read a
16
+ * member from it) -- contract-level "who depends on this," NOT proof any
17
+ * specific variable was read. Blast radius if this contract changes is
18
+ * `consumers.length`, computed by callers/renderers on demand rather than
19
+ * stored redundantly here. */
20
+ readonly consumers: readonly string[];
21
+ }
22
+ /** A contract never imported anywhere in the scanned repository. */
23
+ export interface AbandonedContractFinding {
24
+ /** Resolved display name (see {@link DiscoveredContract.contractName}). */
25
+ readonly contractName: string;
26
+ /** Root-relative path of the file declaring the contract. */
27
+ readonly file: string;
28
+ /** Contract-level default owner, if set. */
29
+ readonly owner: string | undefined;
30
+ }
31
+ /** A contract reachable only through an unresolved barrel re-export -- can't be proven abandoned or consumed. */
32
+ export interface UnresolvedConsumerFinding {
33
+ /** Resolved display name (see {@link DiscoveredContract.contractName}). */
34
+ readonly contractName: string;
35
+ /** Root-relative path of the file declaring the contract. */
36
+ readonly file: string;
37
+ /** Human-readable explanation of why usage couldn't be resolved. */
38
+ readonly reason: string;
39
+ }
40
+ /** An owned variable with no consumer found in the scanned repository. */
41
+ export interface UnconsumedOwnedVariableFinding {
42
+ /** Resolved display name (see {@link DiscoveredContract.contractName}). */
43
+ readonly contractName: string;
44
+ /** The owning contract's default owner, if set. */
45
+ readonly owner: string | undefined;
46
+ /** The unconsumed environment variable name. */
47
+ readonly key: string;
48
+ /**
49
+ * Every `dynamicAccess` citation for this variable that's currently
50
+ * `"stale"` or `"missing"` (empty when none exist -- see ADR 0037).
51
+ * Empty is the *strongest* "looks genuinely unused" signal: no developer
52
+ * has ever claimed otherwise. A non-empty list means someone specifically
53
+ * claimed dynamic access here once and that claim can no longer be
54
+ * verified -- worth a human check before deleting, not a stronger reason
55
+ * to trust "unconsumed." Exposed as the raw citations, not a collapsed
56
+ * `high`/`low` label, matching this codebase's "show the receipt" pattern
57
+ * (ADR 0036/0037) -- a reader can judge confidence from the actual
58
+ * evidence rather than trusting a derived summary. See ADR 0038.
59
+ */
60
+ readonly staleOrMissingCitations: readonly DynamicAccessCitationProblem[];
61
+ }
62
+ /** A variable accessed only via dynamic (computed) property access -- usage cannot be determined statically. */
63
+ export interface IndeterminateOwnershipFinding {
64
+ /** Resolved display name (see {@link DiscoveredContract.contractName}). */
65
+ readonly contractName: string;
66
+ /** The environment variable name. */
67
+ readonly key: string;
68
+ /** Human-readable explanation of why usage couldn't be determined. */
69
+ readonly reason: string;
70
+ /** Every AST-observed dynamic-access site backing `reason`, structured -- see ADR 0036. */
71
+ readonly dynamicAccessSites: readonly SourcePosition[];
72
+ /** See {@link UnconsumedOwnedVariableFinding.staleOrMissingCitations}. */
73
+ readonly staleOrMissingCitations: readonly DynamicAccessCitationProblem[];
74
+ }
75
+ /** A variable that would otherwise be reported `unconsumedOwnedVariables`/`indeterminate`, but has at least one `"fresh"` developer-declared `dynamicAccess` citation -- the raw static status is always shown alongside the assertion, never replaced by it. See ADR 0037. */
76
+ export interface AssertedDynamicAccessFinding {
77
+ /** Resolved display name (see {@link DiscoveredContract.contractName}). */
78
+ readonly contractName: string;
79
+ /** The environment variable name. */
80
+ readonly key: string;
81
+ /** What this variable's status would be without the fresh assertion. */
82
+ readonly wouldBeStatus: "unconsumed" | "indeterminate";
83
+ /** Every citation covering this variable, each with its own current freshness. */
84
+ readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
85
+ }
86
+ /** Everything {@link renderUsageReport} needs to render the Dependency &
87
+ * Ownership Report -- deliberately independent of (not derived from)
88
+ * `GenerateUsageReportResult` in `generate-usage.js`, the same way
89
+ * `RenderDocsOptions` in `docs.ts` doesn't derive from
90
+ * `GenerateDocumentationResult`. `generate-usage.ts` composes its own
91
+ * public result type from these building blocks instead, keeping this
92
+ * renderer module importable without its orchestrator. */
93
+ export interface RenderUsageReportOptions {
94
+ /** Every contract's ownership/dependency summary. */
95
+ readonly dependencyOwnership: readonly OwnershipDependencyEntry[];
96
+ /** Contracts never imported anywhere in the scanned repository. */
97
+ readonly abandonedContracts: readonly AbandonedContractFinding[];
98
+ /** Advisory only, never gates `onOwnershipIssue` -- a contract only
99
+ * reaches here when an ambiguous barrel re-export makes "abandoned" or
100
+ * "consumed" both unprovable. */
101
+ readonly unresolvedConsumers: readonly UnresolvedConsumerFinding[];
102
+ /** Owned variables with no consumer found in the scanned repository. */
103
+ readonly unconsumedOwnedVariables: readonly UnconsumedOwnedVariableFinding[];
104
+ /** Variables accessed only via dynamic (computed) property access. */
105
+ readonly indeterminate: readonly IndeterminateOwnershipFinding[];
106
+ /** Variables a developer has re-acknowledged via `dynamicAccess`, freshly -- see ADR 0037. */
107
+ readonly asserted: readonly AssertedDynamicAccessFinding[];
108
+ /** Schema-discovery parse warnings plus, since ADR 0014, any `packages`
109
+ * resolution failures -- surfaced here too (not just from
110
+ * `generateEnvManifest`/`generateDocumentation`) so a team relying only
111
+ * on `--ownership` output still learns when a cross-package contract
112
+ * failed to resolve. */
113
+ readonly parseWarnings: readonly ParseWarning[];
114
+ /** Every surface actually scanned for usage -- see ADR 0036. Named explicitly next to `unconsumedOwnedVariables` so "no consumer found" is never read as a stronger claim than what was actually searched. */
115
+ readonly scannedSurfaces: readonly ScannedSurface[];
116
+ }
117
+ /**
118
+ * Renders the Dependency & Ownership Report: who owns each variable, which
119
+ * features consume each contract, and what the blast radius is if it
120
+ * changes -- structured around exactly those three questions, never generic
121
+ * "dead code"/"unused symbol" language.
122
+ */
123
+ export declare function renderUsageReport(computed: RenderUsageReportOptions): string;
124
+ //# sourceMappingURL=usage-report.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"usage-report.d.ts","sourceRoot":"","sources":["../../../src/build/usage-report.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,3 @@
1
+ import type { BuildFileSystem } from "../build/types.js";
2
+ export declare const nodeBuildFileSystem: BuildFileSystem;
3
+ //# sourceMappingURL=filesystem.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../../src/cli/filesystem.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,eAAe,EAAc,MAAM,mBAAmB,CAAA;AAwDjF,eAAO,MAAM,mBAAmB,EAAE,eAOjC,CAAA"}
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Converts one glob pattern to a RegExp. Handles `**` as "any number of path
3
+ * segments, including zero" (so `**\/node_modules/**` matches a root-level
4
+ * `node_modules`, and `**\/env.schema.ts` matches a root-level file, not just
5
+ * nested ones) -- a plain `**` -> `.*` substitution gets both of those wrong.
6
+ *
7
+ * Used by no-raw-process-env.ts's `allow` option.
8
+ *
9
+ * Deliberately duplicated (not shared) with
10
+ * src/build/glob.ts, which needs the exact same matching behavior for its
11
+ * own schema-discovery walk -- keeps this eslint-plugin-only module free of
12
+ * any import reaching outside src/eslint-plugin, so `src/eslint-plugin`
13
+ * stays independently splittable into its own package with zero
14
+ * source-level cross-folder dependency. Not re-exported from `./index.js` --
15
+ * Private tier per VERSIONING.md.
16
+ */
17
+ export declare function globToRegExp(pattern: string): RegExp;
18
+ //# sourceMappingURL=glob.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../../src/eslint-plugin/glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAyBpD"}
@@ -0,0 +1,27 @@
1
+ import { noNodeFs } from "./no-node-fs.js";
2
+ import { noRawProcessEnv } from "./no-raw-process-env.js";
3
+ /**
4
+ * `env-cap/eslint-plugin` -- a flat-config-shaped plugin object
5
+ * ({ rules: { ... } }), consumed as:
6
+ *
7
+ * import envCapPlugin from "env-cap/eslint-plugin";
8
+ * export default [{ plugins: { "env-cap": envCapPlugin }, rules: { "env-cap/no-raw-process-env": "error" } }];
9
+ *
10
+ * A 4th public entry point alongside `.`, `./build`, `./helpers` -- see ADR 0017.
11
+ */
12
+ declare const plugin: {
13
+ /** Every rule this plugin ships, keyed by its flat-config rule name. */
14
+ rules: {
15
+ /** See {@link noRawProcessEnv}. */
16
+ "no-raw-process-env": import("@typescript-eslint/utils/ts-eslint").RuleModule<"noRawProcessEnv", [import("./no-raw-process-env.js").RuleOptions], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
17
+ name: string;
18
+ };
19
+ /** See {@link noNodeFs}. */
20
+ "no-node-fs": import("@typescript-eslint/utils/ts-eslint").RuleModule<"noNodeFs", [import("./no-node-fs.js").RuleOptions], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
21
+ name: string;
22
+ };
23
+ };
24
+ };
25
+ export default plugin;
26
+ export { noNodeFs, noRawProcessEnv };
27
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/eslint-plugin/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAEzD;;;;;;;;GAQG;AACH,QAAA,MAAM,MAAM;IACV,wEAAwE;;QAEtE,mCAAmC;;;;QAEnC,4BAA4B;;;;;CAG/B,CAAA;AACD,eAAe,MAAM,CAAA;AACrB,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAA"}
@@ -0,0 +1,25 @@
1
+ export interface RuleOptions {
2
+ /** Glob-array of files this rule doesn't apply to -- a project's own
3
+ * executable entry points (a CLI, a script) that legitimately construct
4
+ * the concrete filesystem adapter. Empty by default -- populate it
5
+ * explicitly; the rule never guesses at what counts as an executable
6
+ * capability boundary. */
7
+ allow?: string[];
8
+ }
9
+ /**
10
+ * Flags any `import`/`require`/dynamic `import()` of `node:fs` in library
11
+ * code, so a library surface acquires its filesystem capability from the
12
+ * caller instead of reaching for `node:fs` itself (the same discipline
13
+ * `repo-contract`'s ADR-0011 established for `child_process`/`process.env`).
14
+ * See ADR 0040.
15
+ *
16
+ * @remarks
17
+ * Nothing is exempt by default. env-cap's own config allows `src/cli/**`
18
+ * (the executable capability boundary that builds the `node:fs/promises`
19
+ * adapter); a consuming project sets its own `allow` for its own entry
20
+ * points.
21
+ */
22
+ export declare const noNodeFs: import("@typescript-eslint/utils/ts-eslint").RuleModule<"noNodeFs", [RuleOptions], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
23
+ name: string;
24
+ };
25
+ //# sourceMappingURL=no-node-fs.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"no-node-fs.d.ts","sourceRoot":"","sources":["../../../src/eslint-plugin/no-node-fs.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,WAAW;IAC1B;;;;+BAI2B;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AAmBD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ;;CAsEnB,CAAA"}
@@ -0,0 +1,23 @@
1
+ export interface RuleOptions {
2
+ /** Glob-array of files this rule doesn't apply to, beyond the built-in
3
+ * env.schema.ts allowance below -- for a consuming project's own
4
+ * Node-only, build-time bootstrap code (see the README section this
5
+ * rule ships with for the canonical worked example: a live-expiration
6
+ * resolver authenticating to a secrets manager). Empty by default --
7
+ * MUST be populated explicitly by the consuming project; env-cap never
8
+ * guesses at what counts as "trusted bootstrap code." */
9
+ allow?: string[];
10
+ }
11
+ /**
12
+ * Flags any direct `process.env.X`/`process.env["X"]` read in application code, so environment
13
+ * access always goes through a capability's own `createEnv()` contract instead.
14
+ *
15
+ * @remarks
16
+ * `env.schema.ts`/`env.schema.tsx` files are always exempt (that's where `createEnv()` itself
17
+ * reads `process.env`); the rule's `allow` option extends that exemption to a consuming
18
+ * project's own trusted bootstrap code.
19
+ */
20
+ export declare const noRawProcessEnv: import("@typescript-eslint/utils/ts-eslint").RuleModule<"noRawProcessEnv", [RuleOptions], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
21
+ name: string;
22
+ };
23
+ //# sourceMappingURL=no-raw-process-env.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"no-raw-process-env.d.ts","sourceRoot":"","sources":["../../../src/eslint-plugin/no-raw-process-env.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,WAAW;IAC1B;;;;;;8DAM0D;IAC1D,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;CA8D1B,CAAA"}
@@ -0,0 +1,51 @@
1
+ import type { EvidenceModel } from "../build/evidence-model.js";
2
+ /**
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
5
+ * `defineEvidenceProjection()` wraps it in enforces that at runtime, see
6
+ * `createTrackingProxy()` below -- and must not perform I/O; env-cap can
7
+ * enforce the read-only half of purity but not the "no side effects" half.
8
+ */
9
+ export type EvidenceProjector<T> = (evidence: EvidenceModel) => T;
10
+ /** One independent, pure projector function per key of the projection's output shape `T`. */
11
+ export type EvidenceProjectionSchema<T extends Record<string, unknown>> = {
12
+ readonly [K in keyof T]: EvidenceProjector<T[K]>;
13
+ };
14
+ /** `project()`'s return shape: the computed output, plus which `EvidenceModel` field paths fed each output key. */
15
+ export interface EvidenceProjectionResult<T extends Record<string, unknown>> {
16
+ readonly value: T;
17
+ readonly sources: Readonly<Record<keyof T, readonly string[]>>;
18
+ }
19
+ /**
20
+ * The function `defineEvidenceProjection()` returns. Callable directly for
21
+ * the common case (`projection(evidence)` -> `T`); `.project()` returns the
22
+ * same value alongside automatic provenance -- see ADR 0032.
23
+ */
24
+ export interface EvidenceProjection<T extends Record<string, unknown>> {
25
+ (evidence: EvidenceModel): T;
26
+ project(evidence: EvidenceModel): EvidenceProjectionResult<T>;
27
+ }
28
+ /**
29
+ * Declares a projection: a named, pure transform from the immutable
30
+ * `EvidenceModel` to any consumer-defined output shape, built entirely from
31
+ * `schema`'s independent per-field projector functions -- see ADR 0031/0032.
32
+ *
33
+ * env-cap's own reference projections (`.env.example`, Environment
34
+ * Configuration Reference, Configuration Ownership, etc.) are built through
35
+ * this exact function, with no privileged internal path -- a consumer's own
36
+ * projection is a first-class citizen, not a lesser one.
37
+ */
38
+ export declare function defineEvidenceProjection<T extends Record<string, unknown>>(schema: EvidenceProjectionSchema<T>): EvidenceProjection<T>;
39
+ /**
40
+ * The error every membrane write-trap below throws. A function, not a
41
+ * module-level `const` -- a `const` string's mutants are evaluated once at
42
+ * module load and can't be attributed to a covering test under Stryker's
43
+ * `perTest` coverage analysis (a documented false-Survivor, not a real
44
+ * gap); exported so a test can pin the exact message directly, the same way
45
+ * every membrane trap's own `.toThrow(...)` can't (a `TypeError` from a
46
+ * Proxy invariant violation is thrown either way a trap's body is mutated,
47
+ * so `.toThrow(TypeError)` alone doesn't distinguish "our message" from
48
+ * "the engine's own invariant-violation message").
49
+ */
50
+ export declare function readOnlyMembraneError(): TypeError;
51
+ //# sourceMappingURL=define-projection.d.ts.map
@@ -0,0 +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,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"}
@@ -0,0 +1,23 @@
1
+ /**
2
+ * env-cap Evidence Model entry point (`env-cap/evidence`).
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()`, `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).
11
+ *
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.
19
+ */
20
+ export type { EvidenceModel, EvidenceProvenance } from "../build/evidence-model.js";
21
+ export { defineEvidenceProjection } from "./define-projection.js";
22
+ export type { EvidenceProjection, EvidenceProjectionResult, EvidenceProjectionSchema, EvidenceProjector, } from "./define-projection.js";
23
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,135 @@
1
+ /**
2
+ * Optional convenience helpers for common processor/validator patterns.
3
+ * Entirely separate from the core runtime -- `defineEnv`/`validateEnv` have
4
+ * no knowledge of this module and work identically without it.
5
+ *
6
+ * Usage: `processors.toNumber()`, `validators.range(1, 65535)`.
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
+ * "env-cap/helpers"` alone drops `validators` entirely.
17
+ */
18
+ import { base64, parseJSON, split, toArray, toBigInt, toBoolean, toDate, toInteger, toLowerCase, toNumber, toRegExp, toString, toURL, toUpperCase, trim } from "./processors.js";
19
+ 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";
20
+ /**
21
+ * Convenience {@link runtime.Processor} implementations for common coercion
22
+ * patterns (e.g. `processors.toNumber()`).
23
+ *
24
+ * @remarks
25
+ * Naming matches `@maverickcer/data-cap`'s `helpers.processors` -- but these
26
+ * throw with a formatted `Error` message on invalid input, where data-cap's
27
+ * silently return `undefined`. Do not assume the same failure mode when
28
+ * moving between packages.
29
+ */
30
+ export declare const processors: {
31
+ /** Decodes a base64 string into a `Buffer`. */
32
+ base64: typeof base64;
33
+ /** Parses a JSON string; passes non-string values through unchanged. */
34
+ parseJSON: typeof parseJSON;
35
+ /** Splits a string on `separator` into a trimmed string array; returns `[]` for non-string input. */
36
+ split: typeof split;
37
+ /** Splits a delimited string (or passes through an array) into items, running each through `processors` in order. */
38
+ toArray: typeof toArray;
39
+ /** Coerces a value to a `bigint`. */
40
+ toBigInt: typeof toBigInt;
41
+ /** Coerces common boolean-like strings (`true`/`1`/`yes`/`on`, and their opposites) into a real boolean. */
42
+ toBoolean: typeof toBoolean;
43
+ /** Parses a value into a `Date`. */
44
+ toDate: typeof toDate;
45
+ /** Coerces a value to a number and requires it to be an integer. */
46
+ toInteger: typeof toInteger;
47
+ /** Lowercases a string (coercing nullish values to `""` first). */
48
+ toLowerCase: typeof toLowerCase;
49
+ /** Coerces a value to a number, rejecting empty/whitespace-only strings instead of silently resolving to `0`. */
50
+ toNumber: typeof toNumber;
51
+ /** Compiles a value into a `RegExp`. */
52
+ toRegExp: typeof toRegExp;
53
+ /** Coerces a value to a string, treating nullish values as `""`. */
54
+ toString: typeof toString;
55
+ /** Parses a value into a `URL`, treating nullish values as `""` first. */
56
+ toURL: typeof toURL;
57
+ /** Uppercases a string (coercing nullish values to `""` first). */
58
+ toUpperCase: typeof toUpperCase;
59
+ /** Trims surrounding whitespace from a string (coercing nullish values to `""` first). */
60
+ trim: typeof trim;
61
+ };
62
+ /** Convenience {@link runtime.Validator} implementations for common validation patterns (e.g. `validators.range(1, 65535)`). */
63
+ export declare const validators: {
64
+ /** Passes when the date value is strictly after `date`. */
65
+ after: typeof after;
66
+ /** Passes only when every wrapped validator passes; returns the first failing message. */
67
+ all: typeof all;
68
+ /** Passes when at least one wrapped validator passes. */
69
+ any: typeof any;
70
+ /** Passes when the date value is strictly before `date`. */
71
+ before: typeof before;
72
+ /** Identity wrapper for a hand-written `Validator<T>` -- no behavior change, just a fluent entry point alongside the other helpers. */
73
+ custom: typeof custom;
74
+ /** Passes for a plausibly-shaped email address (`local@domain`). */
75
+ email: typeof email;
76
+ /** Passes when the string ends with `suffix`. */
77
+ endsWith: typeof endsWith;
78
+ /** Alias for `oneOf` -- passes when the value is one of the `allowed` values. */
79
+ enum: typeof oneOf;
80
+ /** Passes when the number is finite (rejects `Infinity`/`-Infinity`/`NaN`). */
81
+ finite: typeof finite;
82
+ /** Passes when the date is strictly after the current time. */
83
+ future: typeof future;
84
+ /** Passes when the string contains `text` as a substring. */
85
+ includes: typeof includes;
86
+ /** Passes when the number is an integer. */
87
+ integer: typeof integerValidator;
88
+ /** Passes when the string's length is exactly `expected`. */
89
+ length: typeof length;
90
+ /** Passes when the string matches `pattern`; `message` overrides the default failure text. */
91
+ matches: typeof matches;
92
+ /** Passes when the number is less than or equal to `maximum`. */
93
+ max: typeof max;
94
+ /** Passes when the array has at most `maximum` items. */
95
+ maxItems: typeof maxItems;
96
+ /** Passes when the string's length is at most `length`. */
97
+ maxLength: typeof maxLength;
98
+ /** Passes when the number is greater than or equal to `minimum`. */
99
+ min: typeof min;
100
+ /** Passes when the array has at least `minimum` items. */
101
+ minItems: typeof minItems;
102
+ /** Passes when the string's length is at least `length`. */
103
+ minLength: typeof minLength;
104
+ /** Passes when the number is strictly negative. */
105
+ negative: typeof negative;
106
+ /** Inverts a validator: passes when the wrapped validator fails, and vice versa. */
107
+ not: typeof not;
108
+ /** Passes when the value is one of the `allowed` values. */
109
+ oneOf: typeof oneOf;
110
+ /** Passes when the value is undefined, otherwise delegates to the provided validator. */
111
+ optional: typeof optional;
112
+ /** Passes when the date is strictly before the current time. */
113
+ past: typeof past;
114
+ /** Passes when the number is strictly positive. */
115
+ positive: typeof positive;
116
+ /** Passes when the number is within `[minimum, maximum]` inclusive. */
117
+ range: typeof range;
118
+ /** Runs the wrapped validator but replaces its failure message with `message`. */
119
+ refine: typeof refine;
120
+ /** Alias for `matches` -- passes when the string matches `pattern`. */
121
+ regex: typeof matches;
122
+ /** Passes when the value is defined and, unless `allowEmptyString` is set, non-empty. */
123
+ required: typeof required;
124
+ /** Passes when the number is a safe integer (`Number.isSafeInteger`). */
125
+ safeInteger: typeof safeInteger;
126
+ /** Passes when every item in the array is unique. */
127
+ unique: typeof unique;
128
+ /** Passes when the string is a valid absolute URL. */
129
+ url: typeof urlValidator;
130
+ /** Passes when the string is a valid UUID of one of the given `versions` (default: any of 1-8). */
131
+ uuid: typeof uuid;
132
+ /** Shorthand for `uuid([version])` -- passes only for that exact UUID version. */
133
+ uuidVersion: typeof uuidVersion;
134
+ };
135
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +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"}