@maverickcer/env-cap 0.7.4 → 0.7.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (353) hide show
  1. package/ADOPTION.md +106 -124
  2. package/AGENTS.md +94 -128
  3. package/CHANGELOG.md +42 -0
  4. package/CODE_REVIEW.md +69 -173
  5. package/CONTRIBUTING.md +57 -74
  6. package/GUIDE.md +405 -866
  7. package/README.md +112 -89
  8. package/RELEASING.md +81 -65
  9. package/SECURITY.md +76 -227
  10. package/SUPPORT.md +21 -45
  11. package/VERSIONING.md +69 -105
  12. package/benchmarks/READING-BENCHMARKS.md +103 -81
  13. package/benchmarks/README.md +12 -9
  14. package/benchmarks/WRITING-BENCHMARKS.md +90 -80
  15. package/benchmarks/performance-buildtime/BENCHMARKS.md +20 -20
  16. package/benchmarks/performance-runtime/BENCHMARKS.md +107 -107
  17. package/dist/.dts/_ipc/build-fs.d.ts +12 -17
  18. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  19. package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
  20. package/dist/.dts/_ipc/display-path.d.ts +1 -1
  21. package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
  22. package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
  23. package/dist/.dts/_ipc/glob.d.ts +9 -8
  24. package/dist/.dts/_ipc/glob.d.ts.map +1 -1
  25. package/dist/.dts/_ipc/no-node-fs.d.ts +2 -2
  26. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
  27. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  28. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  29. package/dist/.dts/_ipc/typescript.d.ts +4 -4
  30. package/dist/.dts/build/assemble-project.d.ts +14 -15
  31. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  32. package/dist/.dts/build/change-model.d.ts +14 -14
  33. package/dist/.dts/build/change-model.d.ts.map +1 -1
  34. package/dist/.dts/build/check-artifacts.d.ts +4 -4
  35. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  36. package/dist/.dts/build/citation-verification.d.ts +13 -14
  37. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  38. package/dist/.dts/build/compatibility.d.ts +24 -24
  39. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  40. package/dist/.dts/build/contract-model.d.ts +10 -10
  41. package/dist/.dts/build/contract-model.d.ts.map +1 -1
  42. package/dist/.dts/build/deep-equal.d.ts +2 -2
  43. package/dist/.dts/build/deep-freeze.d.ts +2 -2
  44. package/dist/.dts/build/dependency-graph.d.ts +48 -55
  45. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  46. package/dist/.dts/build/dependency-model.d.ts +18 -18
  47. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  48. package/dist/.dts/build/discover.d.ts +11 -11
  49. package/dist/.dts/build/discover.d.ts.map +1 -1
  50. package/dist/.dts/build/docs.d.ts +34 -38
  51. package/dist/.dts/build/docs.d.ts.map +1 -1
  52. package/dist/.dts/build/env-example.d.ts +13 -13
  53. package/dist/.dts/build/env-example.d.ts.map +1 -1
  54. package/dist/.dts/build/errors.d.ts +8 -8
  55. package/dist/.dts/build/evidence-cache.d.ts +23 -23
  56. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  57. package/dist/.dts/build/evidence-model.d.ts +3 -3
  58. package/dist/.dts/build/evidence-reference.d.ts +15 -15
  59. package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
  60. package/dist/.dts/build/evidence-snapshot.d.ts +47 -53
  61. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  62. package/dist/.dts/build/exclusive-group.d.ts +4 -4
  63. package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
  64. package/dist/.dts/build/finding-model.d.ts +12 -12
  65. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  66. package/dist/.dts/build/generate-documentation.d.ts +19 -19
  67. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  68. package/dist/.dts/build/generate-env-artifacts.d.ts +43 -43
  69. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  70. package/dist/.dts/build/generate-evidence.d.ts +19 -19
  71. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  72. package/dist/.dts/build/generate-manifest.d.ts +11 -12
  73. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  74. package/dist/.dts/build/generate-usage.d.ts +23 -24
  75. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  76. package/dist/.dts/build/generated-banner.d.ts +5 -5
  77. package/dist/.dts/build/governance-fields.d.ts +7 -7
  78. package/dist/.dts/build/humanize-key.d.ts +1 -1
  79. package/dist/.dts/build/humanize-key.d.ts.map +1 -1
  80. package/dist/.dts/build/index.d.ts +20 -36
  81. package/dist/.dts/build/index.d.ts.map +1 -1
  82. package/dist/.dts/build/lifecycle-model.d.ts +90 -83
  83. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  84. package/dist/.dts/build/link.d.ts +38 -39
  85. package/dist/.dts/build/link.d.ts.map +1 -1
  86. package/dist/.dts/build/literal-eval.d.ts +2 -2
  87. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  88. package/dist/.dts/build/live-expirations.d.ts +14 -13
  89. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  90. package/dist/.dts/build/manifest.d.ts +6 -6
  91. package/dist/.dts/build/map-utils.d.ts +4 -4
  92. package/dist/.dts/build/merge-documentation.d.ts +9 -8
  93. package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
  94. package/dist/.dts/build/ownership-model.d.ts +14 -15
  95. package/dist/.dts/build/ownership-model.d.ts.map +1 -1
  96. package/dist/.dts/build/parse.d.ts +20 -21
  97. package/dist/.dts/build/parse.d.ts.map +1 -1
  98. package/dist/.dts/build/reference-projections.d.ts +36 -38
  99. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  100. package/dist/.dts/build/resolution/resolve-import.d.ts +18 -14
  101. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  102. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +26 -26
  103. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  104. package/dist/.dts/build/resolution/resolve-within-root.d.ts +9 -9
  105. package/dist/.dts/build/sarif.d.ts +5 -5
  106. package/dist/.dts/build/sarif.d.ts.map +1 -1
  107. package/dist/.dts/build/scan-dependencies.d.ts +17 -16
  108. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  109. package/dist/.dts/build/sort-by-identity.d.ts +1 -1
  110. package/dist/.dts/build/source-position.d.ts +13 -13
  111. package/dist/.dts/build/tool-version.d.ts +1 -1
  112. package/dist/.dts/build/usage-report.d.ts +19 -19
  113. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  114. package/dist/.dts/eslint-plugin/index.d.ts +16 -5
  115. package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
  116. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
  117. package/dist/.dts/evidence/define-projection.d.ts +15 -16
  118. package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
  119. package/dist/.dts/evidence/index.d.ts +11 -15
  120. package/dist/.dts/evidence/index.d.ts.map +1 -1
  121. package/dist/.dts/helpers/index.d.ts +15 -18
  122. package/dist/.dts/helpers/index.d.ts.map +1 -1
  123. package/dist/.dts/helpers/validators.d.ts +2 -2
  124. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  125. package/dist/.dts/node/index.d.ts +19 -0
  126. package/dist/.dts/node/index.d.ts.map +1 -1
  127. package/dist/.dts/runtime/create.d.ts +6 -3
  128. package/dist/.dts/runtime/create.d.ts.map +1 -1
  129. package/dist/.dts/runtime/document.d.ts +91 -97
  130. package/dist/.dts/runtime/document.d.ts.map +1 -1
  131. package/dist/.dts/runtime/errors.d.ts +5 -5
  132. package/dist/.dts/runtime/index.d.ts +11 -10
  133. package/dist/.dts/runtime/index.d.ts.map +1 -1
  134. package/dist/.dts/runtime/reset.d.ts +1 -1
  135. package/dist/.dts/runtime/types.d.ts +39 -24
  136. package/dist/.dts/runtime/types.d.ts.map +1 -1
  137. package/dist/.dts/runtime/validate.d.ts +15 -2
  138. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  139. package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
  140. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
  141. package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
  142. package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
  143. package/dist/.dts7/_ipc/display-path.d.ts +27 -0
  144. package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
  145. package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
  146. package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
  147. package/dist/.dts7/_ipc/glob.d.ts +23 -0
  148. package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
  149. package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
  150. package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
  151. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  152. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  153. package/dist/.dts7/_ipc/typescript.d.ts +20 -0
  154. package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
  155. package/dist/.dts7/build/assemble-project.d.ts +46 -0
  156. package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
  157. package/dist/.dts7/build/change-model.d.ts +63 -0
  158. package/dist/.dts7/build/change-model.d.ts.map +1 -0
  159. package/dist/.dts7/build/check-artifacts.d.ts +48 -0
  160. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
  161. package/dist/.dts7/build/citation-verification.d.ts +61 -0
  162. package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
  163. package/dist/.dts7/build/compatibility.d.ts +83 -0
  164. package/dist/.dts7/build/compatibility.d.ts.map +1 -0
  165. package/dist/.dts7/build/compiler-api.d.ts +12 -0
  166. package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
  167. package/dist/.dts7/build/contract-model.d.ts +93 -0
  168. package/dist/.dts7/build/contract-model.d.ts.map +1 -0
  169. package/dist/.dts7/build/deep-equal.d.ts +9 -0
  170. package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
  171. package/dist/.dts7/build/deep-freeze.d.ts +20 -0
  172. package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
  173. package/dist/.dts7/build/dependency-graph.d.ts +163 -0
  174. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
  175. package/dist/.dts7/build/dependency-model.d.ts +81 -0
  176. package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
  177. package/dist/.dts7/build/discover.d.ts +41 -0
  178. package/dist/.dts7/build/discover.d.ts.map +1 -0
  179. package/dist/.dts7/build/display-path.d.ts +6 -0
  180. package/dist/.dts7/build/display-path.d.ts.map +1 -0
  181. package/dist/.dts7/build/docs.d.ts +172 -0
  182. package/dist/.dts7/build/docs.d.ts.map +1 -0
  183. package/dist/.dts7/build/env-example.d.ts +85 -0
  184. package/dist/.dts7/build/env-example.d.ts.map +1 -0
  185. package/dist/.dts7/build/errors.d.ts +78 -0
  186. package/dist/.dts7/build/errors.d.ts.map +1 -0
  187. package/dist/.dts7/build/evidence-cache.d.ts +74 -0
  188. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
  189. package/dist/.dts7/build/evidence-model.d.ts +50 -0
  190. package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
  191. package/dist/.dts7/build/evidence-reference.d.ts +67 -0
  192. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
  193. package/dist/.dts7/build/evidence-snapshot.d.ts +142 -0
  194. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
  195. package/dist/.dts7/build/exclusive-group.d.ts +19 -0
  196. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
  197. package/dist/.dts7/build/finding-model.d.ts +80 -0
  198. package/dist/.dts7/build/finding-model.d.ts.map +1 -0
  199. package/dist/.dts7/build/generate-documentation.d.ts +176 -0
  200. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
  201. package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
  202. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
  203. package/dist/.dts7/build/generate-evidence.d.ts +77 -0
  204. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
  205. package/dist/.dts7/build/generate-manifest.d.ts +100 -0
  206. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
  207. package/dist/.dts7/build/generate-usage.d.ts +94 -0
  208. package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
  209. package/dist/.dts7/build/generated-banner.d.ts +43 -0
  210. package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
  211. package/dist/.dts7/build/glob.d.ts +6 -0
  212. package/dist/.dts7/build/glob.d.ts.map +1 -0
  213. package/dist/.dts7/build/governance-fields.d.ts +34 -0
  214. package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
  215. package/dist/.dts7/build/humanize-key.d.ts +14 -0
  216. package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
  217. package/dist/.dts7/build/index.d.ts +89 -0
  218. package/dist/.dts7/build/index.d.ts.map +1 -0
  219. package/dist/.dts7/build/lifecycle-model.d.ts +181 -0
  220. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
  221. package/dist/.dts7/build/link.d.ts +222 -0
  222. package/dist/.dts7/build/link.d.ts.map +1 -0
  223. package/dist/.dts7/build/literal-eval.d.ts +24 -0
  224. package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
  225. package/dist/.dts7/build/live-expirations.d.ts +48 -0
  226. package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
  227. package/dist/.dts7/build/manifest.d.ts +31 -0
  228. package/dist/.dts7/build/manifest.d.ts.map +1 -0
  229. package/dist/.dts7/build/map-utils.d.ts +8 -0
  230. package/dist/.dts7/build/map-utils.d.ts.map +1 -0
  231. package/dist/.dts7/build/merge-documentation.d.ts +36 -0
  232. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
  233. package/dist/.dts7/build/ownership-model.d.ts +58 -0
  234. package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
  235. package/dist/.dts7/build/parse.d.ts +206 -0
  236. package/dist/.dts7/build/parse.d.ts.map +1 -0
  237. package/dist/.dts7/build/reference-projections.d.ts +168 -0
  238. package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
  239. package/dist/.dts7/build/resolution/resolve-import.d.ts +62 -0
  240. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
  241. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
  242. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
  243. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
  244. package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
  245. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
  246. package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
  247. package/dist/.dts7/build/sarif.d.ts +66 -0
  248. package/dist/.dts7/build/sarif.d.ts.map +1 -0
  249. package/dist/.dts7/build/scan-dependencies.d.ts +71 -0
  250. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
  251. package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
  252. package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
  253. package/dist/.dts7/build/source-position.d.ts +69 -0
  254. package/dist/.dts7/build/source-position.d.ts.map +1 -0
  255. package/dist/.dts7/build/tool-version.d.ts +8 -0
  256. package/dist/.dts7/build/tool-version.d.ts.map +1 -0
  257. package/dist/.dts7/build/types.d.ts +7 -0
  258. package/dist/.dts7/build/types.d.ts.map +1 -0
  259. package/dist/.dts7/build/typescript.d.ts +6 -0
  260. package/dist/.dts7/build/typescript.d.ts.map +1 -0
  261. package/dist/.dts7/build/usage-report.d.ts +124 -0
  262. package/dist/.dts7/build/usage-report.d.ts.map +1 -0
  263. package/dist/.dts7/cli/filesystem.d.ts +7 -0
  264. package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
  265. package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
  266. package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
  267. package/dist/.dts7/eslint-plugin/index.d.ts +38 -0
  268. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
  269. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
  270. package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
  271. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
  272. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
  273. package/dist/.dts7/evidence/define-projection.d.ts +51 -0
  274. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
  275. package/dist/.dts7/evidence/index.d.ts +19 -0
  276. package/dist/.dts7/evidence/index.d.ts.map +1 -0
  277. package/dist/.dts7/helpers/index.d.ts +132 -0
  278. package/dist/.dts7/helpers/index.d.ts.map +1 -0
  279. package/dist/.dts7/helpers/processors.d.ts +32 -0
  280. package/dist/.dts7/helpers/processors.d.ts.map +1 -0
  281. package/dist/.dts7/helpers/validators.d.ts +68 -0
  282. package/dist/.dts7/helpers/validators.d.ts.map +1 -0
  283. package/dist/.dts7/node/index.d.ts +21 -0
  284. package/dist/.dts7/node/index.d.ts.map +1 -0
  285. package/dist/.dts7/runtime/cache.d.ts +17 -0
  286. package/dist/.dts7/runtime/cache.d.ts.map +1 -0
  287. package/dist/.dts7/runtime/create.d.ts +23 -0
  288. package/dist/.dts7/runtime/create.d.ts.map +1 -0
  289. package/dist/.dts7/runtime/document.d.ts +214 -0
  290. package/dist/.dts7/runtime/document.d.ts.map +1 -0
  291. package/dist/.dts7/runtime/errors.d.ts +55 -0
  292. package/dist/.dts7/runtime/errors.d.ts.map +1 -0
  293. package/dist/.dts7/runtime/index.d.ts +25 -0
  294. package/dist/.dts7/runtime/index.d.ts.map +1 -0
  295. package/dist/.dts7/runtime/registry.d.ts +12 -0
  296. package/dist/.dts7/runtime/registry.d.ts.map +1 -0
  297. package/dist/.dts7/runtime/reset.d.ts +8 -0
  298. package/dist/.dts7/runtime/reset.d.ts.map +1 -0
  299. package/dist/.dts7/runtime/types.d.ts +190 -0
  300. package/dist/.dts7/runtime/types.d.ts.map +1 -0
  301. package/dist/.dts7/runtime/validate.d.ts +27 -0
  302. package/dist/.dts7/runtime/validate.d.ts.map +1 -0
  303. package/dist/{build-6XFHJFQK.js → build-UEENZEUX.js} +43 -42
  304. package/dist/build-UEENZEUX.js.map +1 -0
  305. package/dist/build.cjs +42 -41
  306. package/dist/build.cjs.map +1 -1
  307. package/dist/build.js +42 -41
  308. package/dist/build.js.map +1 -1
  309. package/dist/build.ts7.d.cts +1 -0
  310. package/dist/build.ts7.d.ts +1 -0
  311. package/dist/{chunk-RL5KFVUT.js → chunk-TBL3O7IG.js} +2 -2
  312. package/dist/cli/index.js +29 -28
  313. package/dist/cli/index.js.map +1 -1
  314. package/dist/eslint-plugin/index.cjs.map +1 -1
  315. package/dist/eslint-plugin/index.js.map +1 -1
  316. package/dist/eslint-plugin/index.ts7.d.cts +1 -0
  317. package/dist/eslint-plugin/index.ts7.d.ts +1 -0
  318. package/dist/evidence.cjs +1 -1
  319. package/dist/evidence.cjs.map +1 -1
  320. package/dist/evidence.js +1 -1
  321. package/dist/evidence.js.map +1 -1
  322. package/dist/evidence.ts7.d.cts +1 -0
  323. package/dist/evidence.ts7.d.ts +1 -0
  324. package/dist/helpers.cjs +4 -4
  325. package/dist/helpers.cjs.map +1 -1
  326. package/dist/helpers.js +4 -4
  327. package/dist/helpers.js.map +1 -1
  328. package/dist/helpers.ts7.d.cts +1 -0
  329. package/dist/helpers.ts7.d.ts +1 -0
  330. package/dist/index.cjs.map +1 -1
  331. package/dist/index.js.map +1 -1
  332. package/dist/index.ts7.d.cts +1 -0
  333. package/dist/index.ts7.d.ts +1 -0
  334. package/dist/node.ts7.d.cts +1 -0
  335. package/dist/node.ts7.d.ts +1 -0
  336. package/examples/README.md +46 -80
  337. package/package.json +43 -12
  338. package/schemas/contract-model.schema.json +7 -7
  339. package/schemas/env-cap-report.schema.json +88 -88
  340. package/skills/env-cap/SKILL.md +12 -13
  341. package/skills/env-cap/references/api.md +1 -1
  342. package/specs/architecture.md +147 -122
  343. package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
  344. package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
  345. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
  346. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
  347. package/specs/generated-artifacts.md +91 -71
  348. package/specs/migrations/README.md +6 -6
  349. package/specs/migrations/from-centralized-schema.md +1 -1
  350. package/specs/migrations/from-t3-env.md +9 -9
  351. package/PROMPT.md +0 -89
  352. package/dist/build-6XFHJFQK.js.map +0 -1
  353. /package/dist/{chunk-RL5KFVUT.js.map → chunk-TBL3O7IG.js.map} +0 -0
@@ -1 +1 @@
1
- {"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../../src/runtime/document.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../../src/runtime/document.ts"],"names":[],"mappings":"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"}
@@ -2,10 +2,10 @@
2
2
  * Every error type here is constructed only from: the variable name, the
3
3
  * declaring contract's name, the failure kind, and a message string that the
4
4
  * *developer's own* processor/validator produced. Raw or processed environment
5
- * values are never read into an error -- see the Security section in the README.
5
+ * values are never read into an error: see the Security section in the README.
6
6
  *
7
7
  * Documentation (description, owner, etc.) never appears here, even when a
8
- * {@link documentEnv} call exists for this variable -- `documentEnv` is
8
+ * {@link documentEnv} call exists for this variable: `documentEnv` is
9
9
  * build-time-only and its data is never retained anywhere {@link validateEnv}
10
10
  * could read it back out. This is a deliberate consequence of keeping the
11
11
  * runtime minimal, not an oversight.
@@ -25,11 +25,11 @@ export interface VariableFailure {
25
25
  }
26
26
  /**
27
27
  * Thrown by {@link validateEnv} when one or more variables fail processing or
28
- * validation. Aggregates every failure across every contract in the batch --
28
+ * validation. Aggregates every failure across every contract in the batch:
29
29
  * the caller sees the whole picture in one error, not one-at-a-time.
30
30
  *
31
31
  * @remarks
32
- * `code` is a stable, Stable-tier discriminant for programmatic handling --
32
+ * `code` is a stable, Stable-tier discriminant for programmatic handling:
33
33
  * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
34
34
  */
35
35
  export declare class EnvValidationError extends Error {
@@ -44,7 +44,7 @@ export declare class EnvValidationError extends Error {
44
44
  * {@link validateEnv} has completed successfully for it.
45
45
  *
46
46
  * @remarks
47
- * `code` is a stable, Stable-tier discriminant for programmatic handling --
47
+ * `code` is a stable, Stable-tier discriminant for programmatic handling:
48
48
  * prefer it over `.name`/`instanceof` when a message-independent switch is needed.
49
49
  */
50
50
  export declare class EnvNotReadyError extends Error {
@@ -1,16 +1,17 @@
1
1
  /**
2
- * env-cap runtime entry point.
2
+ * The env-cap runtime entry point: declare contracts, validate them once at startup, and read
3
+ * typed values through the contract that owns them.
3
4
  *
4
- * Zero dependencies, isomorphic (no `fs`, no `process` other than the values
5
- * the developer passes in). Handles processing, validation, caching, and
6
- * typed access only -- discovery and manifest generation live in
7
- * `@maverickcer/env-cap/build` and are never imported from here.
5
+ * It imports no Node module and reads no Node global; it takes values only from the `values`
6
+ * you pass to `validateEnv()`. `test/runtime/browser-bundle.test.ts` checks the built bundle for
7
+ * Node imports, `process.` and `Buffer.`, but a third-party import would pass unnoticed.
8
+ * Discovery and manifest generation live in `@maverickcer/env-cap/build`, never here.
8
9
  *
9
- * `documentEnv` is exported from here, not `@maverickcer/env-cap/build`, even though
10
- * it exists purely for documentation: it's meant to be called inline in the
11
- * same schema file as `createEnv`, which is ordinary runtime code that may
12
- * end up in any bundle (including a browser one). It must be exactly as
13
- * cheap and safe to import as `createEnv` -- see `document.ts`.
10
+ * `documentEnv` is exported here, not from `./build`, because it is called inline in the same
11
+ * schema file as `createEnv`, which may end up in any bundle. It must be as cheap to import as
12
+ * `createEnv` (see `document.ts`).
13
+ *
14
+ * @packageDocumentation
14
15
  */
15
16
  export type { CreateEnvOptions, DefaultValue, EnvContract, EnvDefinition, EnvSchema, InferEnvValue, Processor, RawEnv, validateEnvOptions, validateEnvResult, Validator, } from "./types.js";
16
17
  export { createEnv } from "./create.js";
@@ -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"}
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Clears cached validation state. Intended for tests and dev tooling (e.g.
3
3
  * `beforeEach(() => resetEnvCache())` in a test suite that re-validates with
4
- * different fixture values per test) -- production applications validate
4
+ * different fixture values per test): production applications validate
5
5
  * once at startup and should not normally call this.
6
6
  */
7
7
  export declare function resetEnvCache(): void;
@@ -3,19 +3,18 @@
3
3
  *
4
4
  * These types are intentionally minimal: an `EnvDefinition` describes how to
5
5
  * turn one raw environment value into one typed, validated application
6
- * value. There is no `optional`/`required` flag anywhere in this file --
6
+ * value. There is no `optional`/`required` flag anywhere in this file:
7
7
  * requiredness is just a validator that rejects `undefined`/empty values.
8
8
  *
9
9
  * Documentation fields (description, owner, expiresAt, category, ...) live
10
- * entirely in {@link documentEnv} (see `document.ts`), not here -- this file is
10
+ * entirely in {@link documentEnv} (see `document.ts`), not here: this file is
11
11
  * the runtime's whole vocabulary, and every field in it is read by
12
12
  * `validate.ts`/`create.ts`/`errors.ts` at runtime. If a field is only ever
13
13
  * read by the generator, it belongs in `document.ts`, not here. `context` is
14
- * the one exception worth calling out: it's also read by the build package
15
- * for documentation display (see ADR 0022), but it belongs here rather than
16
- * in `documentEnv()` because `validate.ts` reads it too, to decide pipeline
17
- * participation -- the same bar `default`/`processor`/`validator` already
18
- * clear.
14
+ * the one exception. The build package also reads it for documentation
15
+ * display (see ADR 0022). It belongs here rather than in `documentEnv()`
16
+ * because `validate.ts` reads it too, to decide pipeline participation: the
17
+ * same bar `default`/`processor`/`validator` already clear.
19
18
  */
20
19
  /** The raw, unprocessed source of environment values (e.g. `process.env`, a resolved secrets bag). */
21
20
  export type RawEnv = Readonly<Record<string, unknown>>;
@@ -35,7 +34,7 @@ export type Validator<T> = (value: T, rawEnv: RawEnv) => true | string;
35
34
  *
36
35
  * @remarks
37
36
  * The union is redundant at the type level (`unknown` alone already accepts a
38
- * function) -- it's kept because this type is public API, and collapsing it to bare `unknown`
37
+ * function). It's kept because this type is public API: collapsing it to bare `unknown`
39
38
  * would erase the one thing a reader of the generated `.d.ts` needs to learn here.
40
39
  */
41
40
  export type DefaultValue = unknown | (() => unknown);
@@ -49,17 +48,17 @@ export interface EnvDefinition<T> {
49
48
  validator?: Validator<T>;
50
49
  /**
51
50
  * The validation context this variable belongs to (e.g. `"server"`,
52
- * `"production"`, `"worker"`) -- entirely application-defined; env-cap
51
+ * `"production"`, `"worker"`): entirely application-defined; env-cap
53
52
  * never interprets, detects, or infers this string. Omitted (the
54
53
  * default) means the variable participates in every {@link validateEnv}
55
54
  * run regardless of `activeContexts`. A variable belongs to at most one
56
- * validation context -- see ADR 0022 for why this is a single `string`
57
- * and not `string[]`; do not widen it to an array to let one variable
58
- * join multiple contexts, that reintroduces the AND/OR ambiguity this
55
+ * validation context: see ADR 0022 for why this is a single `string`
56
+ * and not `string[]`. Do not widen it to an array to let one variable
57
+ * join multiple contexts. That reintroduces the AND/OR ambiguity this
59
58
  * design deliberately avoids.
60
59
  *
61
60
  * @remarks
62
- * Validation contexts are a participation filter only -- not
61
+ * Validation contexts are a participation filter only: not
63
62
  * authentication, authorization, or a bundling/security boundary. See
64
63
  * ADR 0022's Formal Invariants.
65
64
  */
@@ -84,7 +83,7 @@ type UnwrapDefault<D> = D extends {
84
83
  * default's type, else `string` (the shape raw process.env values naturally arrive in).
85
84
  *
86
85
  * @remarks
87
- * Same documented generic-bound variance workaround as {@link EnvSchema} above --
86
+ * Same documented generic-bound variance workaround as {@link EnvSchema} above:
88
87
  * `any` here is never surfaced to a consumer's inferred type.
89
88
  */
90
89
  export type InferEnvValue<D extends EnvDefinition<any>> = D extends {
@@ -100,25 +99,33 @@ export interface ContractInternals<S extends EnvSchema = EnvSchema> {
100
99
  }
101
100
  /**
102
101
  * The object returned by {@link createEnv}. Each key is a lazily-resolved getter backed by the
103
- * runtime cache -- there is no global env object, only per-feature contracts like this one.
102
+ * runtime cache: there is no global env object, only per-feature contracts like this one.
104
103
  *
105
104
  * @remarks
106
105
  * `toString()` is intersected in (rather than left to the ambient `Object.prototype`
107
106
  * declaration) because `create.ts` genuinely overrides it to return a redacted
108
- * `EnvContract("name")` representation, never resolved values -- see ADR 0006. Declaring
107
+ * `EnvContract("name")` representation, never resolved values: see ADR 0006. Declaring
109
108
  * it here means the type accurately describes what calling `String(contract)` returns.
110
109
  */
111
110
  export type EnvContract<S extends EnvSchema> = {
112
111
  readonly [K in keyof S]: InferEnvValue<S[K]>;
113
112
  } & {
114
- /** Returns the redacted `EnvContract("name")` representation, never resolved values -- see ADR 0006. */
113
+ /** Returns the redacted `EnvContract("name")` representation, never resolved values: see ADR 0006. */
115
114
  toString(): string;
116
115
  };
116
+ /**
117
+ * What {@link validateEnv} validates: the generated manifest, the raw values, and the active
118
+ * validation contexts.
119
+ *
120
+ * @remarks
121
+ * Only the first call in a process is used; later calls return its outcome, whatever options
122
+ * they pass. Call `resetEnvCache()` between runs in a test.
123
+ */
117
124
  export interface validateEnvOptions {
118
125
  /** The raw source of environment values, e.g. `process.env` or a resolved secrets bag. */
119
126
  values: RawEnv;
120
127
  /**
121
- * Every contract to validate -- typically the `contracts` array imported
128
+ * Every contract to validate: typically the `contracts` array imported
122
129
  * from a generated manifest (see {@link build.generateEnvManifest}). Pass all of them
123
130
  * in one call: {@link validateEnv} only ever initializes once per process, so
124
131
  * a second call returns the first call's cached result without
@@ -127,18 +134,18 @@ export interface validateEnvOptions {
127
134
  manifest: readonly EnvContract<any>[];
128
135
  /**
129
136
  * The validation contexts active for this run (e.g. `["server",
130
- * "production"]`) -- entirely application-defined; env-cap never
137
+ * "production"]`): entirely application-defined; env-cap never
131
138
  * detects or infers these, the caller always computes and passes them
132
139
  * explicitly. A variable whose `context` isn't in this list is skipped
133
140
  * entirely (no default/processor/validator runs for it, and it stays in
134
141
  * its not-ready state, exactly as if this run had never happened for
135
- * it) -- see ADR 0022. A variable with no `context` always participates,
142
+ * it): see ADR 0022. A variable with no `context` always participates,
136
143
  * regardless of what's passed here. Omitted (the default) behaves as an
137
144
  * empty list: only variables with no `context` participate.
138
145
  *
139
146
  * @remarks
140
- * Not part of the validation cache's identity -- {@link validateEnv}
141
- * remains one-shot per process exactly as before this option existed. A
147
+ * Not part of the validation cache's identity: {@link validateEnv}
148
+ * remains one-shot per process whatever this option holds. A
142
149
  * second call does not re-evaluate `activeContexts`; it returns the
143
150
  * first call's result outright. Different active contexts belong to
144
151
  * different processes (e.g. a server process and a browser bundle),
@@ -153,11 +160,19 @@ export interface validateEnvResult {
153
160
  /** Total number of variables validated across all contracts. */
154
161
  readonly variableCount: number;
155
162
  }
163
+ /**
164
+ * Options for {@link createEnv}: a display name for error messages and where the contract was
165
+ * declared.
166
+ *
167
+ * @remarks
168
+ * Purely for identification. Owners, descriptions and other documentation belong in
169
+ * `documentEnv()`.
170
+ */
156
171
  export interface CreateEnvOptions {
157
172
  /**
158
173
  * A short, stable label for this contract (e.g. "payments", "database").
159
174
  * Used in error messages. Defaults to an auto-generated anonymous label if
160
- * omitted -- providing one is strongly recommended for readable validation
175
+ * omitted: providing one is strongly recommended for readable validation
161
176
  * errors.
162
177
  */
163
178
  name?: string;
@@ -165,7 +180,7 @@ export interface CreateEnvOptions {
165
180
  * Pass `import.meta.url` here so validation errors point at the file that
166
181
  * declared the failing variable (e.g. "features/payments/env.schema.ts")
167
182
  * instead of just the short `name` label. There is no portable way for
168
- * `createEnv` to discover its caller's module URL on its own -- this is
183
+ * `createEnv` to discover its caller's module URL on its own: this is
169
184
  * always correct and never goes stale, since it's supplied by the JS
170
185
  * engine rather than hand-typed.
171
186
  */
@@ -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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"}
@@ -5,8 +5,21 @@ import type { validateEnvOptions, validateEnvResult } from "./types.js";
5
5
  *
6
6
  * @remarks
7
7
  * Idempotent: the first successful (or failed) call is authoritative for the life of the
8
- * process -- later calls return (or re-throw) that same outcome without re-running any
9
- * processor or validator. Concurrent in-flight calls share one underlying run.
8
+ * process; later calls return (or re-throw) that same outcome without re-running any
9
+ * processor or validator. Concurrent in-flight calls share one underlying run. Call
10
+ * `resetEnvCache()` to validate again, for example between test scenarios.
11
+ *
12
+ * The record of validated values is frozen, but only one level deep: an object, array or `URL`
13
+ * a processor returns stays mutable. A failure message carries variable and contract names and
14
+ * the message your processor or validator produced, never the value itself.
15
+ *
16
+ * @example
17
+ * ```ts
18
+ * import { validateEnv } from "@maverickcer/env-cap"
19
+ * import { manifest } from "./generated/env.manifest"
20
+ *
21
+ * await validateEnv({ manifest, values: process.env })
22
+ * ```
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,oHAAoH;AACpH,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,+GAA+G;AAC/G,MAAM,WAAW,UAAU;IACzB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;IAC9B,oFAAoF;IACpF,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,23 @@
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. When the file is inside `cwd`, it is also tested against the path from there, written with `/` on
15
+ * every platform.
16
+ * (`split`/`join`, not `replaceAll`: a package that carries this copy may compile for ES2020.)
17
+ * @param patterns - the rule's `allow` globs.
18
+ * @param filename - the file as ESLint names it (`context.filename`).
19
+ * @param cwd - ESLint's working directory (`context.cwd`).
20
+ * @returns true when any pattern matches either name.
21
+ */
22
+ export declare function matchesAllowList(patterns: readonly string[], filename: string, cwd: string): boolean;
23
+ //# 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;;;;;;;;;;GAUG;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"}