@maverickcer/env-cap 0.7.3 → 0.7.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (238) hide show
  1. package/ADOPTION.md +106 -124
  2. package/AGENTS.md +14 -13
  3. package/CHANGELOG.md +23 -0
  4. package/CODE_REVIEW.md +69 -173
  5. package/CONTRIBUTING.md +57 -74
  6. package/GUIDE.md +393 -872
  7. package/README.md +82 -77
  8. package/RELEASING.md +17 -15
  9. package/SECURITY.md +76 -227
  10. package/SUPPORT.md +21 -45
  11. package/VERSIONING.md +68 -105
  12. package/benchmarks/READING-BENCHMARKS.md +13 -7
  13. package/benchmarks/WRITING-BENCHMARKS.md +1 -1
  14. package/dist/.dts/_ipc/build-fs.d.ts +9 -14
  15. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  16. package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
  17. package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
  19. package/dist/.dts/_ipc/glob.d.ts +6 -6
  20. package/dist/.dts/_ipc/no-node-fs.d.ts +0 -14
  21. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
  22. package/dist/.dts/build/lifecycle-model.d.ts +8 -3
  23. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  24. package/dist/.dts/build/sarif.d.ts.map +1 -1
  25. package/dist/.dts/helpers/index.d.ts +1 -1
  26. package/dist/.dts/runtime/create.d.ts +3 -0
  27. package/dist/.dts/runtime/create.d.ts.map +1 -1
  28. package/dist/.dts/runtime/document.d.ts +7 -4
  29. package/dist/.dts/runtime/document.d.ts.map +1 -1
  30. package/dist/.dts/runtime/index.d.ts +11 -10
  31. package/dist/.dts/runtime/index.d.ts.map +1 -1
  32. package/dist/.dts/runtime/types.d.ts +16 -0
  33. package/dist/.dts/runtime/types.d.ts.map +1 -1
  34. package/dist/.dts/runtime/validate.d.ts +14 -1
  35. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  36. package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
  37. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
  38. package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
  39. package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
  40. package/dist/.dts7/_ipc/display-path.d.ts +27 -0
  41. package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
  42. package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
  43. package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
  44. package/dist/.dts7/_ipc/glob.d.ts +22 -0
  45. package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
  46. package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
  47. package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
  48. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  49. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  50. package/dist/.dts7/_ipc/typescript.d.ts +20 -0
  51. package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
  52. package/dist/.dts7/build/assemble-project.d.ts +47 -0
  53. package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
  54. package/dist/.dts7/build/change-model.d.ts +63 -0
  55. package/dist/.dts7/build/change-model.d.ts.map +1 -0
  56. package/dist/.dts7/build/check-artifacts.d.ts +48 -0
  57. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
  58. package/dist/.dts7/build/citation-verification.d.ts +62 -0
  59. package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
  60. package/dist/.dts7/build/compatibility.d.ts +83 -0
  61. package/dist/.dts7/build/compatibility.d.ts.map +1 -0
  62. package/dist/.dts7/build/compiler-api.d.ts +12 -0
  63. package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
  64. package/dist/.dts7/build/contract-model.d.ts +93 -0
  65. package/dist/.dts7/build/contract-model.d.ts.map +1 -0
  66. package/dist/.dts7/build/deep-equal.d.ts +9 -0
  67. package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
  68. package/dist/.dts7/build/deep-freeze.d.ts +20 -0
  69. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
  70. package/dist/.dts7/build/dependency-graph.d.ts +170 -0
  71. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
  72. package/dist/.dts7/build/dependency-model.d.ts +81 -0
  73. package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
  74. package/dist/.dts7/build/discover.d.ts +41 -0
  75. package/dist/.dts7/build/discover.d.ts.map +1 -0
  76. package/dist/.dts7/build/display-path.d.ts +6 -0
  77. package/dist/.dts7/build/display-path.d.ts.map +1 -0
  78. package/dist/.dts7/build/docs.d.ts +176 -0
  79. package/dist/.dts7/build/docs.d.ts.map +1 -0
  80. package/dist/.dts7/build/env-example.d.ts +85 -0
  81. package/dist/.dts7/build/env-example.d.ts.map +1 -0
  82. package/dist/.dts7/build/errors.d.ts +78 -0
  83. package/dist/.dts7/build/errors.d.ts.map +1 -0
  84. package/dist/.dts7/build/evidence-cache.d.ts +74 -0
  85. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
  86. package/dist/.dts7/build/evidence-model.d.ts +50 -0
  87. package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
  88. package/dist/.dts7/build/evidence-reference.d.ts +67 -0
  89. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
  90. package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
  91. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
  92. package/dist/.dts7/build/exclusive-group.d.ts +19 -0
  93. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
  94. package/dist/.dts7/build/finding-model.d.ts +80 -0
  95. package/dist/.dts7/build/finding-model.d.ts.map +1 -0
  96. package/dist/.dts7/build/generate-documentation.d.ts +176 -0
  97. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
  98. package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
  99. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
  100. package/dist/.dts7/build/generate-evidence.d.ts +77 -0
  101. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
  102. package/dist/.dts7/build/generate-manifest.d.ts +101 -0
  103. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
  104. package/dist/.dts7/build/generate-usage.d.ts +95 -0
  105. package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
  106. package/dist/.dts7/build/generated-banner.d.ts +43 -0
  107. package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
  108. package/dist/.dts7/build/glob.d.ts +6 -0
  109. package/dist/.dts7/build/glob.d.ts.map +1 -0
  110. package/dist/.dts7/build/governance-fields.d.ts +34 -0
  111. package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
  112. package/dist/.dts7/build/humanize-key.d.ts +14 -0
  113. package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
  114. package/dist/.dts7/build/index.d.ts +105 -0
  115. package/dist/.dts7/build/index.d.ts.map +1 -0
  116. package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
  117. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
  118. package/dist/.dts7/build/link.d.ts +223 -0
  119. package/dist/.dts7/build/link.d.ts.map +1 -0
  120. package/dist/.dts7/build/literal-eval.d.ts +24 -0
  121. package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
  122. package/dist/.dts7/build/live-expirations.d.ts +47 -0
  123. package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
  124. package/dist/.dts7/build/manifest.d.ts +31 -0
  125. package/dist/.dts7/build/manifest.d.ts.map +1 -0
  126. package/dist/.dts7/build/map-utils.d.ts +8 -0
  127. package/dist/.dts7/build/map-utils.d.ts.map +1 -0
  128. package/dist/.dts7/build/merge-documentation.d.ts +35 -0
  129. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
  130. package/dist/.dts7/build/ownership-model.d.ts +59 -0
  131. package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
  132. package/dist/.dts7/build/parse.d.ts +207 -0
  133. package/dist/.dts7/build/parse.d.ts.map +1 -0
  134. package/dist/.dts7/build/reference-projections.d.ts +170 -0
  135. package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
  136. package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
  137. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
  138. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
  139. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
  140. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
  141. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
  142. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
  143. package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
  144. package/dist/.dts7/build/sarif.d.ts +66 -0
  145. package/dist/.dts7/build/sarif.d.ts.map +1 -0
  146. package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
  147. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
  148. package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
  149. package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
  150. package/dist/.dts7/build/source-position.d.ts +69 -0
  151. package/dist/.dts7/build/source-position.d.ts.map +1 -0
  152. package/dist/.dts7/build/tool-version.d.ts +8 -0
  153. package/dist/.dts7/build/tool-version.d.ts.map +1 -0
  154. package/dist/.dts7/build/types.d.ts +7 -0
  155. package/dist/.dts7/build/types.d.ts.map +1 -0
  156. package/dist/.dts7/build/typescript.d.ts +6 -0
  157. package/dist/.dts7/build/typescript.d.ts.map +1 -0
  158. package/dist/.dts7/build/usage-report.d.ts +124 -0
  159. package/dist/.dts7/build/usage-report.d.ts.map +1 -0
  160. package/dist/.dts7/cli/filesystem.d.ts +7 -0
  161. package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
  162. package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
  163. package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
  164. package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
  165. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
  166. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
  167. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
  168. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
  169. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
  170. package/dist/.dts7/evidence/define-projection.d.ts +52 -0
  171. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
  172. package/dist/.dts7/evidence/index.d.ts +23 -0
  173. package/dist/.dts7/evidence/index.d.ts.map +1 -0
  174. package/dist/.dts7/helpers/index.d.ts +135 -0
  175. package/dist/.dts7/helpers/index.d.ts.map +1 -0
  176. package/dist/.dts7/helpers/processors.d.ts +32 -0
  177. package/dist/.dts7/helpers/processors.d.ts.map +1 -0
  178. package/dist/.dts7/helpers/validators.d.ts +68 -0
  179. package/dist/.dts7/helpers/validators.d.ts.map +1 -0
  180. package/dist/.dts7/node/index.d.ts +2 -0
  181. package/dist/.dts7/node/index.d.ts.map +1 -0
  182. package/dist/.dts7/runtime/cache.d.ts +17 -0
  183. package/dist/.dts7/runtime/cache.d.ts.map +1 -0
  184. package/dist/.dts7/runtime/create.d.ts +23 -0
  185. package/dist/.dts7/runtime/create.d.ts.map +1 -0
  186. package/dist/.dts7/runtime/document.d.ts +223 -0
  187. package/dist/.dts7/runtime/document.d.ts.map +1 -0
  188. package/dist/.dts7/runtime/errors.d.ts +55 -0
  189. package/dist/.dts7/runtime/errors.d.ts.map +1 -0
  190. package/dist/.dts7/runtime/index.d.ts +25 -0
  191. package/dist/.dts7/runtime/index.d.ts.map +1 -0
  192. package/dist/.dts7/runtime/registry.d.ts +12 -0
  193. package/dist/.dts7/runtime/registry.d.ts.map +1 -0
  194. package/dist/.dts7/runtime/reset.d.ts +8 -0
  195. package/dist/.dts7/runtime/reset.d.ts.map +1 -0
  196. package/dist/.dts7/runtime/types.d.ts +191 -0
  197. package/dist/.dts7/runtime/types.d.ts.map +1 -0
  198. package/dist/.dts7/runtime/validate.d.ts +27 -0
  199. package/dist/.dts7/runtime/validate.d.ts.map +1 -0
  200. package/dist/{build-LFHPVDQL.js → build-DNAYWD2B.js} +8 -5
  201. package/dist/build-DNAYWD2B.js.map +1 -0
  202. package/dist/build.cjs +7 -4
  203. package/dist/build.cjs.map +1 -1
  204. package/dist/build.js +7 -4
  205. package/dist/build.js.map +1 -1
  206. package/dist/build.ts7.d.cts +1 -0
  207. package/dist/build.ts7.d.ts +1 -0
  208. package/dist/{chunk-ZW3BLAPD.js → chunk-HAGMVMN5.js} +2 -2
  209. package/dist/cli/index.js +3 -3
  210. package/dist/eslint-plugin/index.cjs +8 -5
  211. package/dist/eslint-plugin/index.cjs.map +1 -1
  212. package/dist/eslint-plugin/index.js +8 -5
  213. package/dist/eslint-plugin/index.js.map +1 -1
  214. package/dist/eslint-plugin/index.ts7.d.cts +1 -0
  215. package/dist/eslint-plugin/index.ts7.d.ts +1 -0
  216. package/dist/evidence.ts7.d.cts +1 -0
  217. package/dist/evidence.ts7.d.ts +1 -0
  218. package/dist/helpers.ts7.d.cts +1 -0
  219. package/dist/helpers.ts7.d.ts +1 -0
  220. package/dist/index.cjs.map +1 -1
  221. package/dist/index.js.map +1 -1
  222. package/dist/index.ts7.d.cts +1 -0
  223. package/dist/index.ts7.d.ts +1 -0
  224. package/dist/node.ts7.d.cts +1 -0
  225. package/dist/node.ts7.d.ts +1 -0
  226. package/examples/README.md +46 -80
  227. package/package.json +37 -6
  228. package/schemas/env-cap-report.schema.json +1 -1
  229. package/skills/env-cap/SKILL.md +1 -1
  230. package/skills/env-cap/references/api.md +1 -1
  231. package/specs/architecture.md +2 -2
  232. package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
  233. package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
  234. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
  235. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
  236. package/specs/generated-artifacts.md +14 -2
  237. package/dist/build-LFHPVDQL.js.map +0 -1
  238. /package/dist/{chunk-ZW3BLAPD.js.map → chunk-HAGMVMN5.js.map} +0 -0
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACT,MAAM,EACN,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,GACV,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACT,MAAM,EACN,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,GACV,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}
@@ -114,6 +114,14 @@ export type EnvContract<S extends EnvSchema> = {
114
114
  /** Returns the redacted `EnvContract("name")` representation, never resolved values -- see ADR 0006. */
115
115
  toString(): string;
116
116
  };
117
+ /**
118
+ * What {@link validateEnv} validates: the generated manifest, the raw values, and the active
119
+ * validation contexts.
120
+ *
121
+ * @remarks
122
+ * Only the first call in a process is used; later calls return its outcome, whatever options
123
+ * they pass. Call `resetEnvCache()` between runs in a test.
124
+ */
117
125
  export interface validateEnvOptions {
118
126
  /** The raw source of environment values, e.g. `process.env` or a resolved secrets bag. */
119
127
  values: RawEnv;
@@ -153,6 +161,14 @@ export interface validateEnvResult {
153
161
  /** Total number of variables validated across all contracts. */
154
162
  readonly variableCount: number;
155
163
  }
164
+ /**
165
+ * Options for {@link createEnv}: a display name for error messages and where the contract was
166
+ * declared.
167
+ *
168
+ * @remarks
169
+ * Purely for identification. Owners, descriptions and other documentation belong in
170
+ * `documentEnv()`.
171
+ */
156
172
  export interface CreateEnvOptions {
157
173
  /**
158
174
  * A short, stable label for this contract (e.g. "payments", "database").
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/runtime/types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/runtime/types.ts"],"names":[],"mappings":"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"}
@@ -6,7 +6,20 @@ import type { validateEnvOptions, validateEnvResult } from "./types.js";
6
6
  * @remarks
7
7
  * Idempotent: the first successful (or failed) call is authoritative for the life of the
8
8
  * process -- later calls return (or re-throw) that same outcome without re-running any
9
- * processor or validator. Concurrent in-flight calls share one underlying run.
9
+ * processor or validator. Concurrent in-flight calls share one underlying run. Call
10
+ * `resetEnvCache()` to validate again, for example between test scenarios.
11
+ *
12
+ * The record of validated values is frozen, but only one level deep: an object, array or `URL`
13
+ * a processor returns stays mutable. A failure message carries variable and contract names and
14
+ * the message your processor or validator produced, never the value itself.
15
+ *
16
+ * @example
17
+ * ```ts
18
+ * import { validateEnv } from "@maverickcer/env-cap"
19
+ * import { manifest } from "./generated/env.manifest"
20
+ *
21
+ * await validateEnv({ manifest, values: process.env })
22
+ * ```
10
23
  *
11
24
  * @throws {EnvValidationError} If any variable fails processing or validation.
12
25
  */
@@ -1 +1 @@
1
- {"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/runtime/validate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEvE;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0BzF"}
1
+ {"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/runtime/validate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEvE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0BzF"}
@@ -0,0 +1,48 @@
1
+ /**
2
+ * The filesystem a package's `./build` entry is handed by its caller.
3
+ *
4
+ * `./build` is a library surface, so it never imports `node:fs` itself (the `no-node-fs` rule enforces that).
5
+ * Every public options object carries a required `fs` of this type. The CLI builds one over `node:fs/promises`;
6
+ * a test hands in the same adapter or an in-memory fake. Real filesystem work still happens; the capability is
7
+ * handed in rather than acquired.
8
+ *
9
+ * The signatures mirror `node:fs/promises`, so a thin adapter is a drop-in value. The entry and stat types are
10
+ * structural ({@link BuildDirent}, {@link BuildStats}) rather than Node's own, so the boundary does not leak
11
+ * Node's types. Only the operations the build code calls are declared.
12
+ *
13
+ * This file is the canonical source; a package carries a managed copy (`src/_ipc/build-fs.ts`, see `sync`).
14
+ */
15
+ export interface BuildFileSystem {
16
+ /** Read a UTF-8 text file. Rejects if the path doesn't exist or isn't readable. */
17
+ readonly readFile: (path: string, encoding: "utf8") => Promise<string>;
18
+ /** Write a UTF-8 text file, creating or truncating it. The parent directory must already exist. */
19
+ readonly writeFile: (path: string, data: string, encoding: "utf8") => Promise<void>;
20
+ /** Create a directory and every missing parent. A no-op if it already exists. */
21
+ readonly mkdir: (path: string, options: {
22
+ readonly recursive: true;
23
+ }) => Promise<void>;
24
+ /** List a directory's entries with their file-type info. */
25
+ readonly readdir: (path: string, options: {
26
+ readonly withFileTypes: true;
27
+ }) => Promise<readonly BuildDirent[]>;
28
+ /** Stat a path (following symlinks). Rejects if the path doesn't exist. */
29
+ readonly stat: (path: string) => Promise<BuildStats>;
30
+ /** Resolve a path to its canonical, symlink-free absolute form. */
31
+ readonly realpath: (path: string) => Promise<string>;
32
+ }
33
+ /** One directory entry from {@link BuildFileSystem.readdir} -- the subset of Node's `Dirent` the build code reads. */
34
+ export interface BuildDirent {
35
+ readonly name: string;
36
+ /** Same contract as Node's `Dirent.isDirectory()`. */
37
+ readonly isDirectory: () => boolean;
38
+ /** Same contract as Node's `Dirent.isFile()`. */
39
+ readonly isFile: () => boolean;
40
+ }
41
+ /** A path's stat info from {@link BuildFileSystem.stat} -- the subset of Node's `Stats` the build code reads. */
42
+ export interface BuildStats {
43
+ /** Same contract as Node's `Stats.isFile()`. */
44
+ readonly isFile: () => boolean;
45
+ /** Size in bytes -- read by the package-schema resolver to enforce a size ceiling. */
46
+ readonly size: number;
47
+ }
48
+ //# sourceMappingURL=build-fs.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"build-fs.d.ts","sourceRoot":"","sources":["../../../src/_ipc/build-fs.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACtE,mGAAmG;IACnG,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnF,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACtF,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAA;KAAE,KACtC,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IACpD,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CACrD;AAED,sHAAsH;AACtH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAA;IACnC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;CAC/B;AAED,iHAAiH;AACjH,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB"}
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Fails with a readable message when no loaded compiler exposes the classic API (`createSourceFile`) the
3
+ * build-time scanner is written against. TypeScript 7 ships no programmatic API, so a package falls back to the
4
+ * bundled `@typescript/typescript6` (see `typescript.ts`). This fires only when that dependency was stripped from
5
+ * the install; a raw call would otherwise die with "ts.createSourceFile is not a function".
6
+ *
7
+ * This file is the canonical source; a package carries a managed copy (`src/_ipc/compiler-api.ts`, see `sync`)
8
+ * and binds its own name.
9
+ * @param product - The package's name, as users install it, for the message.
10
+ * @param compiler - The resolved compiler module (a parameter so a test can hand in a stand-in).
11
+ * @throws Error naming the installed version and how to restore the bundled compiler.
12
+ */
13
+ export declare function assertCompilerApi(product: string, compiler: {
14
+ readonly createSourceFile?: unknown;
15
+ readonly version?: string;
16
+ }): void;
17
+ //# sourceMappingURL=compiler-api.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"compiler-api.d.ts","sourceRoot":"","sources":["../../../src/_ipc/compiler-api.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE;IAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3E,IAAI,CAWN"}
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Renders `filePath` relative to `root`, POSIX-separated whatever the platform.
3
+ *
4
+ * Two deliberate non-conversions:
5
+ *
6
+ * - An already-relative `filePath` is returned as given (POSIX-normalized). That makes the function
7
+ * idempotent, which matters because a model's `file` is relativized once and then passed through render
8
+ * helpers that call this again. Resolving a relative path against `process.cwd()` first, which is what
9
+ * `path.relative` does on its own, silently gives a wrong answer whenever the working directory is not `root`.
10
+ * - An absolute path that would need to climb outside `root` is returned unchanged, never rewritten into a
11
+ * `../` escape: a file discovered in another package legitimately lives outside `root`, and its absolute path
12
+ * is the only unambiguous thing to say about it.
13
+ * @param root - The directory paths are published relative to.
14
+ * @param filePath - An absolute path, or one already relative to `root`.
15
+ * @returns The path to publish.
16
+ */
17
+ export declare function displayPath(root: string, filePath: string): string;
18
+ /**
19
+ * The inverse of {@link displayPath}: turns a published `file` back into a real, absolute path for filesystem
20
+ * or import work. `path.resolve` rather than `path.join`, because `displayPath` leaves an out-of-root absolute
21
+ * path unchanged and `resolve` returns such a path untouched, where `join` would produce `root + absolute`.
22
+ * @param root - The directory paths are published relative to.
23
+ * @param filePath - A published path.
24
+ * @returns The absolute path.
25
+ */
26
+ export declare function absolutePathFrom(root: string, filePath: string): string;
27
+ //# sourceMappingURL=display-path.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"display-path.d.ts","sourceRoot":"","sources":["../../../src/_ipc/display-path.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOlE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEvE"}
@@ -0,0 +1,58 @@
1
+ /**
2
+ * The marker every generated file starts with, and the two standing notices a generated artifact carries,
3
+ * written once for every package that generates files.
4
+ *
5
+ * This file is the canonical source; a package carries a managed copy (`src/_ipc/generated-banner.ts`, see
6
+ * `sync`), so it needs no dependency on this repository at runtime. It has no imports, no Node APIs and no
7
+ * environment access, so it is safe in any bundle.
8
+ *
9
+ * One marker means one place decides what "generated" looks like. The code that writes it and the code that
10
+ * reads it (to refuse to overwrite a hand-written file, or to ignore a file that only imports a generated one)
11
+ * cannot drift apart.
12
+ */
13
+ /** What differs between packages; everything else is shared. */
14
+ export interface GeneratedBannerOptions {
15
+ /** The package's short name, as its documentation names it, for example `env-cap`. */
16
+ readonly product: string;
17
+ /** The page that describes the package's Evidence Model. */
18
+ readonly guideUrl: string;
19
+ /** The command that regenerates what the CLI writes, for example `npx env-cap`. */
20
+ readonly cliCommand: string;
21
+ /** How to regenerate a report the CLI does not write (it is produced by the project's own script). */
22
+ readonly reportRegenerateHint: string;
23
+ }
24
+ /** The functions a package's generated-file code uses. */
25
+ export interface GeneratedBanner {
26
+ /** @returns how to regenerate a report the CLI does not write. */
27
+ readonly reportRegenerateHint: () => string;
28
+ /**
29
+ * Renders the "do not edit by hand" marker in the given comment syntax.
30
+ * @param format - Comment syntax to render in.
31
+ * @param regenerate - How to regenerate; defaults to the CLI, which writes the manifest.
32
+ * @returns The comment line.
33
+ */
34
+ readonly generatedBanner: (format?: "ts" | "markdown", regenerate?: string) => string;
35
+ /**
36
+ * Whether `content` carries a marker, as the opening of a `//` or `<!--` comment, within its first 20 non-empty lines.
37
+ * @param content - A file's text.
38
+ * @returns `true` when the file is generated.
39
+ */
40
+ readonly isGeneratedFile: (content: string) => boolean;
41
+ /** @returns the short disclaimer stamped into every artifact that renders sensitivity, ownership or expiry claims. */
42
+ readonly evidenceDisclaimer: () => string;
43
+ /**
44
+ * States that an artifact is a projection of the Evidence Model, by concept, and by path when one is known.
45
+ * @param evidencePath - The path the evidence was also written to, when this run wrote it.
46
+ * @returns The note.
47
+ */
48
+ readonly evidenceProjectionNote: (evidencePath?: string) => string;
49
+ }
50
+ /**
51
+ * @param describe - Returns what differs for this package. A function, not an object, for the same reason
52
+ * as the marker: an object literal written at module level is evaluated once at load, so mutation
53
+ * testing cannot attribute its values to the tests that pin them; a function's literals are evaluated
54
+ * per call.
55
+ * @returns the package's generated-file functions.
56
+ */
57
+ export declare function createGeneratedBanner(describe: () => GeneratedBannerOptions): GeneratedBanner;
58
+ //# sourceMappingURL=generated-banner.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"generated-banner.d.ts","sourceRoot":"","sources":["../../../src/_ipc/generated-banner.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,gEAAgE;AAChE,MAAM,WAAW,sBAAsB;IACrC,sFAAsF;IACtF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,sGAAsG;IACtG,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;CACtC;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,oBAAoB,EAAE,MAAM,MAAM,CAAA;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;IACrF;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAA;IACtD,sHAAsH;IACtH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,MAAM,CAAA;IACzC;;;;OAIG;IACH,QAAQ,CAAC,sBAAsB,EAAE,CAAC,YAAY,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;CACnE;AAWD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,sBAAsB,GAAG,eAAe,CA8C7F"}
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Converts one glob pattern to a `RegExp`. `**` means any number of path segments, including zero, so
3
+ * `**\/node_modules/**` matches a root-level `node_modules` and `**\/x.ts` a root-level file. A plain `**` to
4
+ * `.*` substitution gets both wrong.
5
+ *
6
+ * One implementation for every package: build-time discovery and ESLint options need the same matching, and
7
+ * hand-kept copies had already diverged. This file is the canonical source; a package carries a managed copy
8
+ * (`src/_ipc/glob.ts`, see `sync`).
9
+ */
10
+ export declare function globToRegExp(pattern: string): RegExp;
11
+ /**
12
+ * Whether a lint rule's `allow` list covers a file. ESLint gives a rule the file's absolute path, while a config
13
+ * writes its patterns relative to the working directory (`src/cli/**`), so each pattern is tested against the path
14
+ * as given and, when the file is inside `cwd`, against the path from there, written with `/` on every platform.
15
+ * (`split`/`join`, not `replaceAll`: a package that carries this copy may compile for ES2020.)
16
+ * @param patterns - the rule's `allow` globs.
17
+ * @param filename - the file as ESLint names it (`context.filename`).
18
+ * @param cwd - ESLint's working directory (`context.cwd`).
19
+ * @returns true when any pattern matches either name.
20
+ */
21
+ export declare function matchesAllowList(patterns: readonly string[], filename: string, cwd: string): boolean;
22
+ //# sourceMappingURL=glob.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../../src/_ipc/glob.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA4BpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAeT"}
@@ -0,0 +1,21 @@
1
+ /** What differs between the packages that carry the rule: where its documentation lives and what to read. */
2
+ export interface NoNodeFsWording {
3
+ /** @returns the documentation URL for a rule of this plugin. */
4
+ readonly docsUrl: (ruleName: string) => string;
5
+ /** What the message cites for the reasoning, for example `ADR 0040`. */
6
+ readonly adr: string;
7
+ /** Where the message says the allow-list escape hatch is described, for example `the README's ESLint section`. */
8
+ readonly guide: string;
9
+ }
10
+ export interface RuleOptions {
11
+ /** Glob-array of files this rule doesn't apply to -- a project's own
12
+ * executable entry points (a CLI, a script) that legitimately construct
13
+ * the concrete filesystem adapter. Empty by default -- populate it
14
+ * explicitly; the rule never guesses at what counts as an executable
15
+ * capability boundary. */
16
+ allow?: string[];
17
+ }
18
+ export declare function createNoNodeFs(wording: NoNodeFsWording): import("@typescript-eslint/utils/ts-eslint").RuleModule<"noNodeFs", [RuleOptions], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
19
+ name: string;
20
+ };
21
+ //# sourceMappingURL=no-node-fs.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"no-node-fs.d.ts","sourceRoot":"","sources":["../../../src/_ipc/no-node-fs.ts"],"names":[],"mappings":"AAYA,6GAA6G;AAC7G,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;IAC9C,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,kHAAkH;IAClH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;+BAI2B;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AA6DD,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe;;EAsEtD"}
@@ -0,0 +1,134 @@
1
+ import type TS from "@typescript/typescript6";
2
+ import type { BuildFileSystem } from "./build-fs.js";
3
+ /**
4
+ * TypeScript path-alias resolution.
5
+ *
6
+ * Resolves a bare import specifier (`"@/lib/env.schema.js"`) against a project's own
7
+ * `tsconfig.json` `compilerOptions.paths`/`baseUrl`, so a schema or consumer reached only
8
+ * through an alias isn't misreported by `link.ts`/`dependency-graph.ts` as unresolved or
9
+ * abandoned. Unlike a package-schema resolver, this never crosses a
10
+ * trust/versioning boundary -- every resolved file is already local, already-trusted
11
+ * project source -- so it is on by default (auto-detecting `root/tsconfig.json`) rather
12
+ * than requiring an explicit allowlist.
13
+ *
14
+ * The actual `paths`/`baseUrl` matching algorithm (longest-prefix matching, `*` wildcard
15
+ * substitution, multiple fallback targets, `extends`-chain merging, JSONC parsing) is
16
+ * delegated entirely to the TypeScript compiler via `ts.resolveModuleName()` and
17
+ * `ts.parseJsonConfigFileContent()` -- the same functions `tsc`/`tsserver` themselves use --
18
+ * rather than reimplemented here. This module's own logic is limited to loading the config,
19
+ * caching resolutions, and enforcing the `node_modules` safety boundary below.
20
+ */
21
+ /**
22
+ * The `paths`/`baseUrl` view of parsed compiler options.
23
+ *
24
+ * TypeScript 6 marks `baseUrl` deprecated in its own typings. A project's tsconfig can still set it and
25
+ * TypeScript still honours it, so path resolution has to keep reading it to resolve the way the project's own
26
+ * compiler does. Reading it through this view, which does not carry that deprecation, states that on purpose.
27
+ * @internal
28
+ */
29
+ export interface PathMappingOptions {
30
+ readonly paths?: TS.MapLike<string[]>;
31
+ readonly baseUrl?: string;
32
+ }
33
+ /**
34
+ * @param options - Parsed compiler options.
35
+ * @returns The same options, typed as the `paths`/`baseUrl` view.
36
+ * @internal
37
+ */
38
+ export declare function pathMappingOptions(options: TS.CompilerOptions): PathMappingOptions;
39
+ /** Parsed `tsconfig.json` `paths`/`baseUrl` configuration, immutable for the life of one generate*() run. See {@link loadTsconfigPaths}. */
40
+ export interface TsconfigPathsResolution {
41
+ /** The subset of `compilerOptions` `ts.resolveModuleName()` needs -- at minimum `paths` and/or `baseUrl`. */
42
+ readonly compilerOptions: TS.CompilerOptions;
43
+ /** Absolute path of the tsconfig.json this was loaded from, for diagnostics. */
44
+ readonly configFile: string;
45
+ }
46
+ /**
47
+ * Opaque memoization for {@link resolveAliasImport}, created once per generate*() run via
48
+ * {@link createAliasResolutionCache} and threaded through `ImportResolutionContext`. Kept
49
+ * distinct from `TsconfigPathsResolution` (immutable config) so the cache's internal
50
+ * representation stays free to change without touching that type's shape.
51
+ */
52
+ export interface AliasResolutionCache {
53
+ /**
54
+ * Keyed by `` `${importingFile}\0${specifier}` ``, not by `specifier` alone. With one
55
+ * fixed `compilerOptions` object and no project-reference support, `paths`-pattern
56
+ * substitution itself doesn't depend on the importing file -- but `ts.resolveModuleName()`'s
57
+ * fallback behavior when `paths` doesn't match a real file (classic-mode ancestor search,
58
+ * extension-preference edge cases) legitimately can. A `Map`, not a network call, so
59
+ * keying defensively by both costs nothing.
60
+ */
61
+ readonly resolutions: Map<string, string | undefined>;
62
+ }
63
+ /** Creates a fresh, empty {@link AliasResolutionCache} for one generate*()/computeArtifacts() run. */
64
+ export declare function createAliasResolutionCache(): AliasResolutionCache;
65
+ /** A problem with the tsconfig that is reported rather than thrown. Structurally the same as each package's own warning type. */
66
+ export interface TsconfigWarning {
67
+ /** Absolute path of the tsconfig the warning applies to. */
68
+ readonly file: string;
69
+ /** Human-readable explanation of what was skipped and why. */
70
+ readonly message: string;
71
+ }
72
+ export interface LoadTsconfigPathsResult {
73
+ readonly resolution: TsconfigPathsResolution | undefined;
74
+ readonly warning: TsconfigWarning | undefined;
75
+ }
76
+ /**
77
+ * The compiler's own functions take a path written with `/` and assert it when they report a problem in the file, so
78
+ * a path with the platform's separator (a backslash on Windows) is written with `/` for them.
79
+ * @param file - an absolute path as the platform writes it.
80
+ * @param separator - the platform's path separator.
81
+ * @returns the same path written with `/`.
82
+ */
83
+ export declare function typescriptPath(file: string, separator: string): string;
84
+ /**
85
+ * Loads and parses a `tsconfig.json` for alias resolution. Called exactly once per
86
+ * `generate*()`/`computeArtifacts()` invocation, at the same point
87
+ * `resolveAllowlistedPackages()` is already called once -- so at most one tsconfig-related
88
+ * warning is ever produced per run, never once per file scanned.
89
+ *
90
+ * @param product - The consuming package's name, used in the message when no usable compiler resolved.
91
+ * @remarks
92
+ * `tsconfigOption === false` disables alias resolution entirely.
93
+ * `tsconfigOption === undefined` (the default) looks for `root/tsconfig.json` exactly --
94
+ * deliberately not `ts.findConfigFile()`'s upward directory walk, since every other
95
+ * root-relative mechanism in this codebase (schema discovery, `packages` resolution)
96
+ * treats `root` as a hard boundary. A missing default tsconfig is silent (most projects
97
+ * don't use aliases); a missing *explicit* `tsconfigOption` is a real misconfiguration and
98
+ * warns. `jsconfig.json` is intentionally not auto-detected -- pass `tsconfig:
99
+ * "jsconfig.json"` explicitly if needed; this loader only cares about the file's JSON
100
+ * shape, not its name.
101
+ *
102
+ * The gate for building a resolution is "`paths` non-empty OR `baseUrl` set", not `paths`
103
+ * alone -- a `baseUrl`-only tsconfig (no `paths` at all) still makes TypeScript resolve
104
+ * bare specifiers relative to `baseUrl`, and `ts.resolveModuleName()` already handles that
105
+ * once `compilerOptions.baseUrl` is passed through.
106
+ */
107
+ export declare function loadTsconfigPaths(product: string, root: string, tsconfigOption: string | false | undefined, fs: BuildFileSystem): Promise<LoadTsconfigPathsResult>;
108
+ /**
109
+ * Resolves one bare import specifier against a project's `tsconfig.json` `paths`/`baseUrl`,
110
+ * or returns `undefined` if it doesn't resolve through this mechanism.
111
+ *
112
+ * @remarks
113
+ * Necessarily synchronous -- `ts.resolveModuleName()` has no async form, matching how
114
+ * `tsc`/`tsserver` themselves always call it. `ts.sys` is used directly as the resolution
115
+ * host (an existing Node-backed singleton the `typescript` package exports; nothing to
116
+ * construct).
117
+ *
118
+ * Two safety/scope filters apply to any candidate `ts.resolveModuleName()` returns,
119
+ * independent of its own internal fallback behavior:
120
+ * - **Never resolves into `node_modules`.** `ts.resolveModuleName()` can, in principle,
121
+ * fall through to classic Node resolution and land inside `node_modules`; any resolved
122
+ * path containing a `node_modules` path segment (checked after `path.normalize()`, so
123
+ * mixed separators can't slip past it on Windows) is discarded here. Bare package
124
+ * specifiers continue to be handled exclusively by `resolvePackageImport()`
125
+ * -- this mechanism never overlaps with that trust boundary.
126
+ * - **`.ts`/`.tsx` only.** Matches `resolveRelativeImport()`'s own existing candidate set
127
+ * and `resolve-package-schema.ts`'s `SCHEMA_FILE_EXTENSIONS` -- this codebase's static-
128
+ * analysis pipeline is `.ts`/`.tsx` only today. A resolved non-`.ts`/`.tsx` file is a
129
+ * real risk, not just a gap: feeding it straight into `ts.createSourceFile()` wouldn't
130
+ * error, it would silently parse garbage -- exactly the "guess" this codebase's
131
+ * warn-don't-guess philosophy exists to avoid.
132
+ */
133
+ export declare function resolveAliasImport(specifier: string, importingFile: string, resolution: TsconfigPathsResolution, cache: AliasResolutionCache): string | undefined;
134
+ //# sourceMappingURL=resolve-tsconfig-paths.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolve-tsconfig-paths.d.ts","sourceRoot":"","sources":["../../../src/_ipc/resolve-tsconfig-paths.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,EAAE,CAAC,eAAe,GAAG,kBAAkB,CAElF;AAED,4IAA4I;AAC5I,MAAM,WAAW,uBAAuB;IACtC,6GAA6G;IAC7G,QAAQ,CAAC,eAAe,EAAE,EAAE,CAAC,eAAe,CAAA;IAC5C,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CACtD;AAED,sGAAsG;AACtG,wBAAgB,0BAA0B,IAAI,oBAAoB,CAEjE;AAYD,iIAAiI;AACjI,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,uBAAuB,GAAG,SAAS,CAAA;IACxD,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,CAAA;CAC9C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,EAC1C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,uBAAuB,CAAC,CAuElC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,uBAAuB,EACnC,KAAK,EAAE,oBAAoB,GAC1B,MAAM,GAAG,SAAS,CAiBpB"}
@@ -0,0 +1,20 @@
1
+ import type TS from "@typescript/typescript6";
2
+ /** The compiler namespace the build-time scanner is written against. */
3
+ export type TypeScript = typeof TS;
4
+ /**
5
+ * Picks the compiler the scanner parses with: the consumer's `typescript` when it exposes the
6
+ * classic compiler API (TypeScript 5 and 6), otherwise the bundled `@typescript/typescript6` --
7
+ * Microsoft's side-by-side TypeScript 6 package, a dependency of the package so the scanner keeps working
8
+ * for a consumer whose own `typescript` is 7+, which ships no programmatic API. Chosen by capability, never by version,
9
+ * so a future `typescript` that regains the API is used as-is.
10
+ *
11
+ * When neither has the API (the bundled dependency was stripped from an install), it returns the
12
+ * consumer's module anyway so `assertCompilerApi` -- called at every scanner entry point -- fails
13
+ * with its readable message instead of a bare "is not a function".
14
+ * @param load - How a module id is resolved (a parameter so a test can hand in stand-ins).
15
+ * @throws Whatever `load` throws for a reason other than the module not being installed.
16
+ */
17
+ export declare function pickCompiler(load: (id: string) => unknown): TypeScript;
18
+ /** The compiler every scanner module parses with. Resolved once, synchronously, at import. */
19
+ export declare const ts: TypeScript;
20
+ //# sourceMappingURL=typescript.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"typescript.d.ts","sourceRoot":"","sources":["../../../src/_ipc/typescript.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhC,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,OAAO,EAAE,CAAA;AAqClC;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GAAG,UAAU,CAMtE;AAED,8FAA8F;AAC9F,eAAO,MAAM,EAAE,EAAE,UAAyD,CAAA"}
@@ -0,0 +1,47 @@
1
+ import type { LinkResult } from "./link.js";
2
+ import type { ParseWarning } from "./parse.js";
3
+ import type { BuildFileSystem } from "./types.js";
4
+ import type { ImportResolutionContext } from "./resolution/resolve-import.js";
5
+ import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
6
+ /** Options for {@link assembleProject}. */
7
+ export interface AssembleProjectOptions {
8
+ /** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
9
+ readonly fs: BuildFileSystem;
10
+ readonly root: string;
11
+ readonly include: readonly string[];
12
+ readonly exclude: readonly string[];
13
+ readonly packages?: readonly string[] | undefined;
14
+ readonly tsconfig: string | false | undefined;
15
+ }
16
+ /**
17
+ * Everything downstream model-building and artifact-rendering needs from one
18
+ * discovery+link pass: the linked contract graph, the import-resolution
19
+ * context every later resolution call (`computeScanSurface()`,
20
+ * `buildDependencyModel()`, ...) must reuse to agree with `linkResult`, and a
21
+ * shared file-read cache so a file matched by more than one later pass'
22
+ * glob (e.g. a schema file also matched by the usage pass' broader
23
+ * `SCAN_INCLUDE`) is only ever read from disk once.
24
+ */
25
+ export interface AssembledProject {
26
+ readonly root: string;
27
+ readonly readFileCached: (filePath: string) => Promise<string>;
28
+ readonly linkResult: LinkResult;
29
+ readonly context: ImportResolutionContext;
30
+ /** Keyed by resolved file path -- see `resolveAllowlistedPackages()`. */
31
+ readonly origins: ReadonlyMap<string, PackageOrigin>;
32
+ readonly packageWarnings: readonly ParseWarning[];
33
+ readonly tsconfigWarnings: readonly ParseWarning[];
34
+ }
35
+ /**
36
+ * The one shared discovery+link pass every orchestrator needs -- local +
37
+ * allow-listed-package schema discovery, tsconfig path-alias resolution, and
38
+ * cross-file linking, exactly once. Extracted from what `computeArtifacts()`
39
+ * (`generate-env-artifacts.ts`) and `generateEvidenceModel()`
40
+ * (`generate-evidence.ts`) each used to run independently, so the two
41
+ * orchestrators can never silently drift into scanning the same source tree
42
+ * twice -- the same "shared discovery, computed once" principle ADR 0011
43
+ * already established for manifest/docs/usage, now shared with evidence
44
+ * assembly too.
45
+ */
46
+ export declare function assembleProject(options: AssembleProjectOptions): Promise<AssembledProject>;
47
+ //# sourceMappingURL=assemble-project.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"assemble-project.d.ts","sourceRoot":"","sources":["../../../src/build/assemble-project.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAK7E,OAAO,KAAK,EACV,aAAa,EAEd,MAAM,wCAAwC,CAAA;AAM/C,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,iFAAiF;IACjF,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;CAC9C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC9D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAA;IACzC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpD,QAAQ,CAAC,eAAe,EAAE,SAAS,YAAY,EAAE,CAAA;IACjD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,YAAY,EAAE,CAAA;CACnD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2ChG"}
@@ -0,0 +1,63 @@
1
+ import type { DiscoveredContract } from "./link.js";
2
+ import type { ManifestChangeReport } from "./evidence-snapshot.js";
3
+ /**
4
+ * The sixth of env-cap's seven canonical fact models (ADR 0024) -- what
5
+ * changed since the last persisted evidence snapshot (ADR 0038; previously
6
+ * a manifest-scoped snapshot, ADR 0021). See ADR 0030 (base shape) and ADR
7
+ * 0029 (the `renamedFrom` field this file's rename correlation is gated
8
+ * on).
9
+ *
10
+ * @remarks
11
+ * Wraps `ManifestChangeReport` (`evidence-snapshot.ts`) rather than
12
+ * replacing it -- this model exists to give the change report a versioned,
13
+ * model-namespaced shape Evidence Model can assemble against, alongside the
14
+ * other six models. Empty (no adds/removes/updates) whenever no previous
15
+ * evidence snapshot location was configured for this run -- there is
16
+ * nothing to diff against, which is a genuinely different state from a
17
+ * first-ever run *with* tracking configured (where everything reads as
18
+ * added).
19
+ */
20
+ /** Bump only when a reader could misinterpret the new shape -- same discipline every other canonical model's `schemaVersion` follows. */
21
+ export declare const CHANGE_MODEL_SCHEMA_VERSION = 1;
22
+ /** One `addedVariables`/`removedVariables` pair in `manifest`, correlated into a single rename via the current declaration's `renamedFrom` field (ADR 0029). */
23
+ export interface RenamedVariable {
24
+ /** The owning contract's identity (`${file}#${exportName}`) -- a rename never crosses contracts. */
25
+ readonly contractIdentity: string;
26
+ readonly file: string;
27
+ readonly exportName: string;
28
+ readonly contractName: string;
29
+ /** The variable's key before the rename -- matches a `manifest.removedVariables` entry. */
30
+ readonly previousKey: string;
31
+ /** The variable's key after the rename -- matches a `manifest.addedVariables` entry. */
32
+ readonly currentKey: string;
33
+ }
34
+ /** The versioned, JSON-serializable root of the Change Model -- what changed since the last persisted evidence snapshot. See this module's own doc comment for the full picture. */
35
+ export interface ChangeModel {
36
+ readonly schemaVersion: typeof CHANGE_MODEL_SCHEMA_VERSION;
37
+ /** The existing manifest change report, unmodified -- see ADR 0021. `addedVariables`/`removedVariables` still list a correlated rename's two halves separately; `renamedVariables` below is an additive, separately-computed view, not a filter over this field. */
38
+ readonly manifest: ManifestChangeReport;
39
+ /**
40
+ * Every `addedVariables`/`removedVariables` pair this run's currently
41
+ * declared `renamedFrom` values correlate into a single rename, sorted by
42
+ * contract identity then current key.
43
+ *
44
+ * @remarks
45
+ * Only ever populated from an *authored* `renamedFrom` -- never guessed
46
+ * from name similarity (ADR 0010's "provable, not heuristic" ethos).
47
+ * Variable-level only: Lifecycle Model deliberately has no contract-level
48
+ * `renamedFrom` (ADR 0029), so there is no `renamedContracts` -- a
49
+ * contract-level rename has no field to correlate from.
50
+ */
51
+ readonly renamedVariables: readonly RenamedVariable[];
52
+ }
53
+ /**
54
+ * Wraps an already-computed `ManifestChangeReport` (e.g.
55
+ * `generateEnvArtifacts()`'s internal `evidenceChanges.report`) in the Change Model's versioned
56
+ * shape, and correlates renames using the current run's `renamedFrom`
57
+ * declarations. `currentContracts` should be the same contracts the
58
+ * manifest was generated from (active contracts only, matching
59
+ * `renderManifest()`'s own scope -- same as every other input to this
60
+ * report family).
61
+ */
62
+ export declare function buildChangeModel(manifest: ManifestChangeReport, currentContracts: readonly DiscoveredContract[], root: string): ChangeModel;
63
+ //# sourceMappingURL=change-model.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"change-model.d.ts","sourceRoot":"","sources":["../../../src/build/change-model.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAuB,MAAM,wBAAwB,CAAA;AAEvF;;;;;;;;;;;;;;;;GAgBG;AAEH,yIAAyI;AACzI,eAAO,MAAM,2BAA2B,IAAI,CAAA;AAE5C,gKAAgK;AAChK,MAAM,WAAW,eAAe;IAC9B,oGAAoG;IACpG,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,oLAAoL;AACpL,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAA;IAC1D,oQAAoQ;IACpQ,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAA;IACvC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAA;CACtD;AAqBD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,oBAAoB,EAC9B,gBAAgB,EAAE,SAAS,kBAAkB,EAAE,EAC/C,IAAI,EAAE,MAAM,GACX,WAAW,CAqCb"}