@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,83 @@
1
+ import type { ParseWarning } from "../parse.js";
2
+ import type { BuildFileSystem } from "../types.js";
3
+ /** 1 MiB. New hardening specific to this trust tier -- a package crosses a
4
+ * real versioning/trust boundary that locally-discovered source doesn't,
5
+ * so this caps the cost of parsing an oversized or adversarial file before
6
+ * any of its content is even read into memory. See ADR 0014. */
7
+ export declare const MAX_PACKAGE_SCHEMA_FILE_BYTES = 1048576;
8
+ type PackageResolutionFailureCode = "PACKAGE_NOT_FOUND" | "MALFORMED_PACKAGE_JSON" | "FIELD_MISSING" | "INVALID_EXTENSION" | "OUTSIDE_PACKAGE" | "FILE_TOO_LARGE";
9
+ /** Both the authored and resolved forms are kept -- diagnostics benefit from
10
+ * showing exactly what a package author wrote versus what it resolved to. */
11
+ export interface PackageOrigin {
12
+ /** The allow-listed package name that declared this schema. */
13
+ readonly packageName: string;
14
+ /** The `"envCap.schema"` value exactly as the package author wrote it. */
15
+ readonly declaredField: string;
16
+ /** Absolute, realpath-canonicalized path to the resolved schema file. */
17
+ readonly resolvedFile: string;
18
+ /** Absolute, realpath-canonicalized path to the package's own directory. */
19
+ readonly packageDir: string;
20
+ }
21
+ export type PackageSchemaResolutionResult = {
22
+ readonly ok: true;
23
+ readonly origin: PackageOrigin;
24
+ } | {
25
+ readonly ok: false;
26
+ readonly code: PackageResolutionFailureCode;
27
+ readonly reason: string;
28
+ };
29
+ /**
30
+ * Resolves one allow-listed package name. Memoized in a caller-owned
31
+ * `cache` (one per `generate*()` invocation, shared with linking/dependency-
32
+ * graph resolution) so a name referenced from multiple places -- multiple
33
+ * scanned files bare-importing the same package, or a duplicate entry in
34
+ * `packages` -- is only ever resolved once. The cache is populated with the
35
+ * in-flight promise before it settles, so concurrent callers await the same
36
+ * resolution rather than racing duplicate work.
37
+ */
38
+ export declare function resolvePackageSchemaFile(packageName: string, root: string, cache: Map<string, Promise<PackageSchemaResolutionResult>>, fs: BuildFileSystem): Promise<PackageSchemaResolutionResult>;
39
+ interface ResolvedPackageFile {
40
+ readonly packageName: string;
41
+ readonly file: string;
42
+ }
43
+ export interface ResolvePackagesResult {
44
+ readonly files: readonly ResolvedPackageFile[];
45
+ /** Keyed by resolved file path, for `DiscoveredContract.packageOrigin` lookups downstream. */
46
+ readonly origins: ReadonlyMap<string, PackageOrigin>;
47
+ readonly warnings: readonly ParseWarning[];
48
+ }
49
+ /**
50
+ * Resolves every allow-listed package name. Input is deduplicated first, so
51
+ * a duplicate entry in `packages` (accidental or defensive) produces exactly
52
+ * one resolution attempt and, on failure, exactly one warning -- never two.
53
+ * Never throws: every failure becomes one `ParseWarning`, consistent with
54
+ * every other static-analysis boundary in this codebase.
55
+ */
56
+ export declare function resolveAllowlistedPackages(packages: readonly string[] | undefined, root: string, cache: Map<string, Promise<PackageSchemaResolutionResult>>, fs: BuildFileSystem): Promise<ResolvePackagesResult>;
57
+ /**
58
+ * Combines local schema-discovery hits with package-resolved files into one
59
+ * deduplicated list, keyed by realpath rather than lexical absolute path --
60
+ * package-resolved files are already realpath-canonicalized (see
61
+ * `resolveUncached` above), but local `discoverSchemaFiles()` hits are plain
62
+ * `readdir`-derived absolute paths that may themselves traverse a symlink (a
63
+ * symlinked `root`, or an included path reached through one). Deduplicating
64
+ * on the lexical path alone would miss the case where the same physical file
65
+ * is reached twice through two different symlinked routes -- one via local
66
+ * glob discovery, one via package resolution -- and silently double-count it
67
+ * into two identical contracts, including the more mundane case of a package
68
+ * that's both locally glob-reachable (e.g. during a monorepo migration) and
69
+ * explicitly allow-listed. On a collision, the local path string identity
70
+ * wins (the package-resolved duplicate is dropped).
71
+ */
72
+ export declare function mergeLocalAndPackageFiles(localFiles: readonly string[], packageFiles: readonly string[], fs: BuildFileSystem): Promise<string[]>;
73
+ /**
74
+ * Bare-specifier-to-allowlist matching, used by `resolve-import.ts`'s
75
+ * `resolveImportSpecifier()` as its package-resolution fallback. Only ever
76
+ * attempts resolution for a specifier that is (or is a subpath of) an
77
+ * allow-listed package name -- any other bare specifier is not this
78
+ * mechanism's concern and returns `undefined` immediately, identical to
79
+ * `resolveRelativeImport()`'s existing bare-specifier no-op.
80
+ */
81
+ export declare function resolvePackageImport(specifier: string, allowedPackages: readonly string[], root: string, cache: Map<string, Promise<PackageSchemaResolutionResult>>, fs: BuildFileSystem): Promise<string | undefined>;
82
+ export {};
83
+ //# sourceMappingURL=resolve-package-schema.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolve-package-schema.d.ts","sourceRoot":"","sources":["../../../../src/build/resolution/resolve-package-schema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAuBlD;;;iEAGiE;AACjE,eAAO,MAAM,6BAA6B,UAAY,CAAA;AAItD,KAAK,4BAA4B,GAC7B,mBAAmB,GACnB,wBAAwB,GACxB,eAAe,GACf,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,CAAA;AAEpB;8EAC8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,MAAM,6BAA6B,GACrC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAoOhG;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,EAC1D,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,6BAA6B,CAAC,CAcxC;AAED,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAA;IAC9C,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;CAC3C;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACvC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,EAC1D,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,qBAAqB,CAAC,CAgChC;AAED;;;;;;;;;;;;;;GAcG;AASH,wBAAsB,yBAAyB,CAC7C,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBnB;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,SAAS,MAAM,EAAE,EAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,6BAA6B,CAAC,CAAC,EAC1D,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA0B7B"}
@@ -0,0 +1,18 @@
1
+ import type { LoadTsconfigPathsResult } from "../../_ipc/resolve-tsconfig-paths.js";
2
+ import type { BuildFileSystem } from "../types.js";
3
+ /**
4
+ * TypeScript path-alias resolution. The behavior lives in `../../_ipc/resolve-tsconfig-paths.ts`, a managed copy of
5
+ * internal-package-contract's `runtime/resolve-tsconfig-paths.ts`; this binds the one package-specific input, the
6
+ * name used when no usable compiler resolved.
7
+ */
8
+ export { createAliasResolutionCache, resolveAliasImport, } from "../../_ipc/resolve-tsconfig-paths.js";
9
+ export type { AliasResolutionCache, LoadTsconfigPathsResult, TsconfigPathsResolution, } from "../../_ipc/resolve-tsconfig-paths.js";
10
+ /**
11
+ * Loads and parses a `tsconfig.json` for alias resolution, once per run.
12
+ * @param root - The project root; a missing default `tsconfig.json` there is silent.
13
+ * @param tsconfigOption - `false` disables alias resolution, a path overrides the default file.
14
+ * @param fs - The filesystem capability.
15
+ * @returns The resolution and at most one warning.
16
+ */
17
+ export declare function loadTsconfigPaths(root: string, tsconfigOption: string | false | undefined, fs: BuildFileSystem): Promise<LoadTsconfigPathsResult>;
18
+ //# sourceMappingURL=resolve-tsconfig-paths.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolve-tsconfig-paths.d.ts","sourceRoot":"","sources":["../../../../src/build/resolution/resolve-tsconfig-paths.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD;;;;GAIG;AACH,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,sCAAsC,CAAA;AAC7C,YAAY,EACV,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,sCAAsC,CAAA;AAE7C;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,EAC1C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,uBAAuB,CAAC,CAElC"}
@@ -0,0 +1,35 @@
1
+ import type { CompatibilityIssue } from "../compatibility.js";
2
+ export type ResolveWithinRootResult = {
3
+ readonly ok: true;
4
+ readonly resolved: string;
5
+ } | {
6
+ readonly ok: false;
7
+ readonly issue: CompatibilityIssue;
8
+ };
9
+ /**
10
+ * Plain lexical bounds-check: is `targetPath` inside `baseDir`? Shared by
11
+ * `resolveWithinRoot()` below (output paths, checked lexically since they
12
+ * usually don't exist on disk yet) and `resolve-package-schema.ts` (which
13
+ * additionally re-checks this against `fs.realpath`-resolved paths, since a
14
+ * package-declared schema path both exists on disk and crosses a real trust
15
+ * boundary -- see ADR 0014). Boundary-agnostic on purpose: neither caller's
16
+ * notion of "root" is baked in here.
17
+ */
18
+ export declare function isWithinDirectory(baseDir: string, targetPath: string): boolean;
19
+ /**
20
+ * Resolves `location` against `root` and checks the result doesn't escape it
21
+ * (e.g. `location: "../../malicious.ts"`, or an absolute path on another
22
+ * branch of the filesystem entirely). Discovery (`include`/`exclude`) is
23
+ * already safe by construction -- it only ever walks *down* from `root` via
24
+ * `readdir`, so a pattern can't make it read outside `root`. Output
25
+ * locations have no such structural guarantee, since `path.resolve` happily
26
+ * walks back out via `..` segments, so this is a plain lexical bounds-check
27
+ * (not a symlink-aware `realpath` check -- these are *output* paths that
28
+ * usually don't exist yet).
29
+ *
30
+ * Never throws itself -- returns a `CompatibilityIssue`-shaped finding on
31
+ * escape so each generator function (`generateEnvManifest`, `generateDocumentation`,
32
+ * `generateUsageReport`, `generateEnvArtifacts`) can wrap it in its own error type.
33
+ */
34
+ export declare function resolveWithinRoot(root: string, location: string, optionName: string, functionName: string): ResolveWithinRootResult;
35
+ //# sourceMappingURL=resolve-within-root.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolve-within-root.d.ts","sourceRoot":"","sources":["../../../../src/build/resolution/resolve-within-root.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAE7D,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAAA;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAG9E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,GACnB,uBAAuB,CAgBzB"}
@@ -0,0 +1,66 @@
1
+ /**
2
+ * SARIF export -- an adapter over Finding Model, not a new fact source.
3
+ * Produces a minimal, spec-conformant SARIF 2.1.0 log
4
+ * (https://docs.oasis-open.org/sarif/sarif/v2.1.0/) so env-cap's findings can
5
+ * be consumed by any SARIF-aware tool (GitHub code scanning, most CI security
6
+ * dashboards) without a bespoke integration.
7
+ *
8
+ * Pure and synchronous: every input is already computed by the time this
9
+ * runs, so this never re-derives a finding, never reads the filesystem, and
10
+ * never decides what is or isn't a problem -- it only re-shapes what
11
+ * `buildFindingModel()` already concluded.
12
+ */
13
+ import type { FindingModel } from "./finding-model.js";
14
+ /** SARIF's `level` enum -- see the SARIF 2.1.0 spec, section 3.27.10. */
15
+ type SarifLevel = "none" | "note" | "warning" | "error";
16
+ interface SarifLocation {
17
+ readonly physicalLocation: {
18
+ readonly artifactLocation: {
19
+ readonly uri: string;
20
+ };
21
+ readonly region?: {
22
+ readonly startLine: number;
23
+ readonly startColumn: number;
24
+ };
25
+ };
26
+ }
27
+ interface SarifResult {
28
+ readonly ruleId: string;
29
+ readonly level: SarifLevel;
30
+ readonly message: {
31
+ readonly text: string;
32
+ };
33
+ readonly locations?: readonly SarifLocation[];
34
+ }
35
+ /** A minimal SARIF 2.1.0 log -- only the properties this adapter actually populates, not the full spec surface. */
36
+ export interface SarifLog {
37
+ readonly $schema: string;
38
+ readonly version: "2.1.0";
39
+ readonly runs: readonly {
40
+ readonly tool: {
41
+ readonly driver: {
42
+ readonly name: string;
43
+ readonly informationUri: string;
44
+ readonly version: string;
45
+ readonly rules: readonly {
46
+ readonly id: string;
47
+ }[];
48
+ };
49
+ };
50
+ readonly results: readonly SarifResult[];
51
+ }[];
52
+ }
53
+ /**
54
+ * Projects Finding Model into a SARIF 2.1.0 log.
55
+ *
56
+ * @remarks
57
+ * `rules` lists every distinct `FindingCode` actually present in this run,
58
+ * sorted -- not the full `FindingCode` union. A SARIF consumer treats the
59
+ * rules array as "what this tool reported", and advertising rules that
60
+ * produced no result makes a clean run look like it has unexplained silent
61
+ * rules. `results` preserves Finding Model's own order, which a caller wanting
62
+ * a different one sorts themselves.
63
+ */
64
+ export declare function buildSarifLog(findingModel: FindingModel): SarifLog;
65
+ export {};
66
+ //# sourceMappingURL=sarif.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sarif.d.ts","sourceRoot":"","sources":["../../../src/build/sarif.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAW,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAI/D,yEAAyE;AACzE,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAA;AAOvD,UAAU,aAAa;IACrB,QAAQ,CAAC,gBAAgB,EAAE;QACzB,QAAQ,CAAC,gBAAgB,EAAE;YAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;QACnD,QAAQ,CAAC,MAAM,CAAC,EAAE;YAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAA;KAC/E,CAAA;CACF;AAuCD,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,aAAa,EAAE,CAAA;CAC9C;AAED,mHAAmH;AACnH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS;QACtB,QAAQ,CAAC,IAAI,EAAE;YACb,QAAQ,CAAC,MAAM,EAAE;gBACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBACrB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;gBAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBACxB,QAAQ,CAAC,KAAK,EAAE,SAAS;oBAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;iBAAE,EAAE,CAAA;aACnD,CAAA;SACF,CAAA;QACD,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;KACzC,EAAE,CAAA;CACJ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,YAAY,GAAG,QAAQ,CAgClE"}
@@ -0,0 +1,70 @@
1
+ import type TS from "@typescript/typescript6";
2
+ import type { ImportBinding } from "./parse.js";
3
+ /**
4
+ * Why a tracked binding's value flowed somewhere this single-file, syntactic
5
+ * walk cannot follow -- see ADR 0039. Each reason names the exact construct
6
+ * so a downstream "cannot determine whether X is read" message can cite it,
7
+ * rather than a single opaque "escape" label.
8
+ */
9
+ export type EscapeReason =
10
+ /** `const { ...rest } = contract` -- a rest element captures every remaining key at once. */
11
+ "rest"
12
+ /** `const { X: { Y } } = contract` -- the bound value itself gets destructured again, one level too deep for this pass. */
13
+ | "nested-pattern"
14
+ /** `const { [expr]: v } = contract` where `expr` isn't a string literal -- the bound key can't be read without evaluating `expr`. */
15
+ | "computed-key"
16
+ /** `const e = contract` where `e` isn't file-unique/never-assigned (see `resolveAliasTargets`) -- the read is real, but this pass declines to follow `e` any further. */
17
+ | "reassignment";
18
+ /** One observed use of a tracked contract binding in a consumer file -- see ADR 0039. Consumed by `dependency-graph.ts`. */
19
+ export type AccessSite = {
20
+ readonly kind: "member";
21
+ readonly member: string;
22
+ readonly line: number;
23
+ readonly column: number;
24
+ } | {
25
+ readonly kind: "dynamic";
26
+ readonly line: number;
27
+ readonly column: number;
28
+ } | {
29
+ readonly kind: "reference";
30
+ readonly line: number;
31
+ readonly column: number;
32
+ } | {
33
+ readonly kind: "escape";
34
+ readonly via: EscapeReason;
35
+ readonly line: number;
36
+ readonly column: number;
37
+ };
38
+ export interface FileScanResult {
39
+ readonly file: string;
40
+ readonly imports: ReadonlyMap<string, ImportBinding>;
41
+ readonly accessesByLocalName: ReadonlyMap<string, readonly AccessSite[]>;
42
+ /** True if this file contains a bare `export * from "..."` -- used only to
43
+ * flag ambiguous barrel forwarding elsewhere as "unresolved", never to
44
+ * follow it (see ADR 0010's scope boundary). */
45
+ readonly hasWildcardReExport: boolean;
46
+ }
47
+ /** One `const <name> = <identifier>` declaration -- a candidate one-level alias of `<identifier>`, before file-uniqueness/never-assigned checks (see `resolveAliasTargets`). */
48
+ interface AliasCandidate {
49
+ readonly aliasName: string;
50
+ readonly baseName: string;
51
+ readonly declaration: TS.VariableDeclaration;
52
+ }
53
+ /**
54
+ * One whole-file pass collecting the three facts `resolveAliasTargets` needs:
55
+ * how many times each name is introduced as *any* kind of binding (a same
56
+ * name declared twice anywhere -- including inside a nested scope, since
57
+ * this pass is deliberately not scope-aware, matching every other check in
58
+ * this file -- disqualifies it as a trackable alias), which names are ever
59
+ * assigned to after their declaration, and every plain `const <name> =
60
+ * <identifier>` declaration as a raw candidate.
61
+ */
62
+ /** @internal Exported for direct unit coverage. */
63
+ export declare function collectDeclarationFacts(sourceFile: TS.SourceFile): {
64
+ readonly declarationCounts: ReadonlyMap<string, number>;
65
+ readonly assignedNames: ReadonlySet<string>;
66
+ readonly constAliasCandidates: readonly AliasCandidate[];
67
+ };
68
+ export declare function scanFileForDependencies(filePath: string, sourceText: string): FileScanResult;
69
+ export {};
70
+ //# sourceMappingURL=scan-dependencies.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"scan-dependencies.d.ts","sourceRoot":"","sources":["../../../src/build/scan-dependencies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAGhC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG/C;;;;;GAKG;AACH,MAAM,MAAM,YAAY;AACtB,6FAA6F;AAC3F,MAAM;AACR,2HAA2H;GACzH,gBAAgB;AAClB,qIAAqI;GACnI,cAAc;AAChB,yKAAyK;GACvK,cAAc,CAAA;AAElB,4HAA4H;AAC5H,MAAM,MAAM,UAAU,GAClB;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9E;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAA;AAEL,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpD,QAAQ,CAAC,mBAAmB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC,CAAA;IACxE;;qDAEiD;IACjD,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAA;CACtC;AAYD,gLAAgL;AAChL,UAAU,cAAc;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC,mBAAmB,CAAA;CAC7C;AAuGD;;;;;;;;GAQG;AACH,mDAAmD;AACnD,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,GAAG;IAClE,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvD,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC3C,QAAQ,CAAC,oBAAoB,EAAE,SAAS,cAAc,EAAE,CAAA;CACzD,CAiBA;AA2ED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAmK5F"}
@@ -0,0 +1,14 @@
1
+ /**
2
+ * The canonical ordering every fact model's contract list is sorted by: `file`
3
+ * (root-relative, POSIX) then `exportName`. One definition so `JSON.stringify`
4
+ * output is stable and diffs cleanly across Contract / Ownership / Lifecycle /
5
+ * Dependency Models. Internal -- not re-exported from the public `.` barrel.
6
+ */
7
+ export declare function byContractIdentity(a: {
8
+ readonly file: string;
9
+ readonly exportName: string;
10
+ }, b: {
11
+ readonly file: string;
12
+ readonly exportName: string;
13
+ }): number;
14
+ //# sourceMappingURL=sort-by-identity.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sort-by-identity.d.ts","sourceRoot":"","sources":["../../../src/build/sort-by-identity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EACzD,CAAC,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxD,MAAM,CAER"}
@@ -0,0 +1,69 @@
1
+ import type ts from "@typescript/typescript6";
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.VariableEvidenceDocs.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.VariableEvidenceDocs.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,7 @@
1
+ /**
2
+ * The filesystem capability `./build` requires from its caller, and the two small structural types it returns.
3
+ * Defined once in `../_ipc/build-fs.ts`, a managed copy of internal-package-contract's `runtime/build-fs.ts`, and
4
+ * re-exported here so the public `build` entry keeps exporting them. See ADR 0040.
5
+ */
6
+ export type { BuildDirent, BuildFileSystem, BuildStats } from "../_ipc/build-fs.js";
7
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/build/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA"}
@@ -0,0 +1,6 @@
1
+ /**
2
+ * The TypeScript compiler the build-time scanner parses with. The behavior lives in `../_ipc/typescript.ts`, a
3
+ * managed copy of internal-package-contract's `runtime/typescript.ts`.
4
+ */
5
+ export { ts } from "../_ipc/typescript.js";
6
+ //# sourceMappingURL=typescript.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["../../../src/build/typescript.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,EAAE,EAAE,MAAM,uBAAuB,CAAA"}
@@ -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,7 @@
1
+ import type { BuildFileSystem } from "../build/types.js";
2
+ /**
3
+ * The Node-backed `BuildFileSystem`: the filesystem capability the build-time generators require.
4
+ * @public
5
+ */
6
+ export declare const nodeBuildFileSystem: BuildFileSystem;
7
+ //# 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;AAiDjF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,eAO9B,CAAA"}
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Matching of the plugin's `allow` options against the file a rule is checking. The behavior lives in
3
+ * `../_ipc/glob.ts`, a managed copy of internal-package-contract's `runtime/glob.ts`: a pattern written relative to
4
+ * the working directory (`src/cli/**`) matches the absolute path ESLint passes, on Windows too.
5
+ */
6
+ export { matchesAllowList } from "../_ipc/glob.js";
7
+ //# 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;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}
@@ -0,0 +1,27 @@
1
+ import { noNodeFs } from "./no-node-fs.js";
2
+ import { noRawProcessEnv } from "./no-raw-process-env.js";
3
+ /**
4
+ * `@maverickcer/env-cap/eslint-plugin` -- a flat-config-shaped plugin object
5
+ * ({ rules: { ... } }), consumed as:
6
+ *
7
+ * import envCapPlugin from "@maverickcer/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("../_ipc/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"}