@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
@@ -0,0 +1,25 @@
1
+ /**
2
+ * The env-cap runtime entry point: declare contracts, validate them once at startup, and read
3
+ * typed values through the contract that owns them.
4
+ *
5
+ * It imports no Node module and reads no Node global; it takes values only from the `values`
6
+ * you pass to `validateEnv()`. `test/runtime/browser-bundle.test.ts` checks the built bundle for
7
+ * Node imports, `process.` and `Buffer.`, but a third-party import would pass unnoticed.
8
+ * Discovery and manifest generation live in `@maverickcer/env-cap/build`, never here.
9
+ *
10
+ * `documentEnv` is exported here, not from `./build`, because it is called inline in the same
11
+ * schema file as `createEnv`, which may end up in any bundle. It must be as cheap to import as
12
+ * `createEnv` (see `document.ts`).
13
+ *
14
+ * @packageDocumentation
15
+ */
16
+ export type { CreateEnvOptions, DefaultValue, EnvContract, EnvDefinition, EnvSchema, InferEnvValue, Processor, RawEnv, validateEnvOptions, validateEnvResult, Validator, } from "./types.js";
17
+ export { createEnv } from "./create.js";
18
+ export { documentEnv } from "./document.js";
19
+ export type { ContractDocs, VariableDocs, VariableEvidenceDocs } from "./document.js";
20
+ export { EnvNotReadyError, EnvValidationError } from "./errors.js";
21
+ export type { VariableFailure } from "./errors.js";
22
+ export { isEnvContract } from "./registry.js";
23
+ export { resetEnvCache } from "./reset.js";
24
+ export { validateEnv } from "./validate.js";
25
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACT,MAAM,EACN,kBAAkB,EAClB,iBAAiB,EACjB,SAAS,GACV,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA"}
@@ -0,0 +1,12 @@
1
+ import type { ContractInternals } from "./types.js";
2
+ /** Associates a contract object with its internal identity/schema. Called once, by `createEnv`. */
3
+ export declare function registerContract(contract: object, internals: ContractInternals): void;
4
+ /**
5
+ * Looks up a contract's internal identity/schema.
6
+ *
7
+ * @throws {TypeError} If `contract` wasn't returned by `createEnv` (and so was never registered).
8
+ */
9
+ export declare function getContractInternals(contract: object): ContractInternals;
10
+ /** Type guard: `true` when `value` was created by `createEnv` (i.e. is a registered contract). */
11
+ export declare function isEnvContract(value: unknown): value is object;
12
+ //# sourceMappingURL=registry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/runtime/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAUnD,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAErF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CASxE;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAK7D"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Clears cached validation state. Intended for tests and dev tooling (e.g.
3
+ * `beforeEach(() => resetEnvCache())` in a test suite that re-validates with
4
+ * different fixture values per test): production applications validate
5
+ * once at startup and should not normally call this.
6
+ */
7
+ export declare function resetEnvCache(): void;
8
+ //# sourceMappingURL=reset.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"reset.d.ts","sourceRoot":"","sources":["../../../src/runtime/reset.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}
@@ -0,0 +1,190 @@
1
+ /**
2
+ * Core contract types for env-cap.
3
+ *
4
+ * These types are intentionally minimal: an `EnvDefinition` describes how to
5
+ * turn one raw environment value into one typed, validated application
6
+ * value. There is no `optional`/`required` flag anywhere in this file:
7
+ * requiredness is just a validator that rejects `undefined`/empty values.
8
+ *
9
+ * Documentation fields (description, owner, expiresAt, category, ...) live
10
+ * entirely in {@link documentEnv} (see `document.ts`), not here: this file is
11
+ * the runtime's whole vocabulary, and every field in it is read by
12
+ * `validate.ts`/`create.ts`/`errors.ts` at runtime. If a field is only ever
13
+ * read by the generator, it belongs in `document.ts`, not here. `context` is
14
+ * the one exception. 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.
18
+ */
19
+ /** The raw, unprocessed source of environment values (e.g. `process.env`, a resolved secrets bag). */
20
+ export type RawEnv = Readonly<Record<string, unknown>>;
21
+ /** Processes a raw value into a typed, ready-to-use application value. Must not read any other key. */
22
+ export type Processor<T> = (value: unknown) => T;
23
+ /**
24
+ * Validates an already-processed value; return `true` when valid, or a human-readable error
25
+ * string when invalid.
26
+ *
27
+ * @remarks
28
+ * Receives the full raw env for conditional validation (e.g. "required only if X").
29
+ */
30
+ export type Validator<T> = (value: T, rawEnv: RawEnv) => true | string;
31
+ /**
32
+ * A default may be a literal value, or a zero-arg thunk evaluated lazily when the raw value is
33
+ * undefined.
34
+ *
35
+ * @remarks
36
+ * The union is redundant at the type level (`unknown` alone already accepts a
37
+ * function). It's kept because this type is public API: collapsing it to bare `unknown`
38
+ * would erase the one thing a reader of the generated `.d.ts` needs to learn here.
39
+ */
40
+ export type DefaultValue = unknown | (() => unknown);
41
+ /** Configuration for one schema entry: how to default, process, and validate a single raw environment value. */
42
+ export interface EnvDefinition<T> {
43
+ /** Literal fallback or lazy thunk used when the raw value is `undefined`. */
44
+ default?: DefaultValue;
45
+ /** Converts the raw (or defaulted) value to `T`; passed through unprocessed when omitted. */
46
+ processor?: Processor<T>;
47
+ /** Rejects an invalid processed value; return `true` to accept it. */
48
+ validator?: Validator<T>;
49
+ /**
50
+ * The validation context this variable belongs to (e.g. `"server"`,
51
+ * `"production"`, `"worker"`): entirely application-defined; env-cap
52
+ * never interprets, detects, or infers this string. Omitted (the
53
+ * default) means the variable participates in every {@link validateEnv}
54
+ * run regardless of `activeContexts`. A variable belongs to at most one
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
58
+ * design deliberately avoids.
59
+ *
60
+ * @remarks
61
+ * Validation contexts are a participation filter only: not
62
+ * authentication, authorization, or a bundling/security boundary. See
63
+ * ADR 0022's Formal Invariants.
64
+ */
65
+ context?: string;
66
+ }
67
+ /**
68
+ * A schema is a map of variable name -> definition.
69
+ *
70
+ * @remarks
71
+ * `EnvDefinition<any>` is used only as the generic *bound* here (never surfaced to consumers):
72
+ * TypeScript infers a precise, per-key literal type for `S` from the object passed to
73
+ * {@link createEnv}, so the resolved contract type (see {@link InferEnvValue}) stays fully
74
+ * strict. This is the same variance workaround used by schema libraries like zod/trpc for
75
+ * heterogeneous generic maps.
76
+ */
77
+ export type EnvSchema = Record<string, EnvDefinition<any>>;
78
+ type UnwrapDefault<D> = D extends {
79
+ default: infer Def;
80
+ } ? Def extends () => infer R ? R : Def : never;
81
+ /**
82
+ * Resolves the application-facing type for one schema entry: processor return type, else the
83
+ * default's type, else `string` (the shape raw process.env values naturally arrive in).
84
+ *
85
+ * @remarks
86
+ * Same documented generic-bound variance workaround as {@link EnvSchema} above:
87
+ * `any` here is never surfaced to a consumer's inferred type.
88
+ */
89
+ export type InferEnvValue<D extends EnvDefinition<any>> = D extends {
90
+ /** Narrows to the processor's return type when one is present. */
91
+ processor: Processor<infer P>;
92
+ } ? P : [UnwrapDefault<D>] extends [never] ? string : UnwrapDefault<D>;
93
+ /** The internal, non-enumerable identity + metadata attached to every contract created by `createEnv`. */
94
+ export interface ContractInternals<S extends EnvSchema = EnvSchema> {
95
+ readonly id: symbol;
96
+ readonly name: string;
97
+ readonly source: string | undefined;
98
+ readonly schema: S;
99
+ }
100
+ /**
101
+ * The object returned by {@link createEnv}. Each key is a lazily-resolved getter backed by the
102
+ * runtime cache: there is no global env object, only per-feature contracts like this one.
103
+ *
104
+ * @remarks
105
+ * `toString()` is intersected in (rather than left to the ambient `Object.prototype`
106
+ * declaration) because `create.ts` genuinely overrides it to return a redacted
107
+ * `EnvContract("name")` representation, never resolved values: see ADR 0006. Declaring
108
+ * it here means the type accurately describes what calling `String(contract)` returns.
109
+ */
110
+ export type EnvContract<S extends EnvSchema> = {
111
+ readonly [K in keyof S]: InferEnvValue<S[K]>;
112
+ } & {
113
+ /** Returns the redacted `EnvContract("name")` representation, never resolved values: see ADR 0006. */
114
+ toString(): string;
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
+ */
124
+ export interface validateEnvOptions {
125
+ /** The raw source of environment values, e.g. `process.env` or a resolved secrets bag. */
126
+ values: RawEnv;
127
+ /**
128
+ * Every contract to validate: typically the `contracts` array imported
129
+ * from a generated manifest (see {@link build.generateEnvManifest}). Pass all of them
130
+ * in one call: {@link validateEnv} only ever initializes once per process, so
131
+ * a second call returns the first call's cached result without
132
+ * re-running anything, even if it passes a different manifest.
133
+ */
134
+ manifest: readonly EnvContract<any>[];
135
+ /**
136
+ * The validation contexts active for this run (e.g. `["server",
137
+ * "production"]`): entirely application-defined; env-cap never
138
+ * detects or infers these, the caller always computes and passes them
139
+ * explicitly. A variable whose `context` isn't in this list is skipped
140
+ * entirely (no default/processor/validator runs for it, and it stays in
141
+ * its not-ready state, exactly as if this run had never happened for
142
+ * it): see ADR 0022. A variable with no `context` always participates,
143
+ * regardless of what's passed here. Omitted (the default) behaves as an
144
+ * empty list: only variables with no `context` participate.
145
+ *
146
+ * @remarks
147
+ * Not part of the validation cache's identity: {@link validateEnv}
148
+ * remains one-shot per process whatever this option holds. A
149
+ * second call does not re-evaluate `activeContexts`; it returns the
150
+ * first call's result outright. Different active contexts belong to
151
+ * different processes (e.g. a server process and a browser bundle),
152
+ * never to two calls within the same one.
153
+ */
154
+ activeContexts?: readonly string[];
155
+ }
156
+ /** Aggregate counts from a completed {@link validateEnv} run. */
157
+ export interface validateEnvResult {
158
+ /** Number of contracts in the manifest that were validated. */
159
+ readonly contractCount: number;
160
+ /** Total number of variables validated across all contracts. */
161
+ readonly variableCount: number;
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
+ */
171
+ export interface CreateEnvOptions {
172
+ /**
173
+ * A short, stable label for this contract (e.g. "payments", "database").
174
+ * Used in error messages. Defaults to an auto-generated anonymous label if
175
+ * omitted: providing one is strongly recommended for readable validation
176
+ * errors.
177
+ */
178
+ name?: string;
179
+ /**
180
+ * Pass `import.meta.url` here so validation errors point at the file that
181
+ * declared the failing variable (e.g. "features/payments/env.schema.ts")
182
+ * instead of just the short `name` label. There is no portable way for
183
+ * `createEnv` to discover its caller's module URL on its own: this is
184
+ * always correct and never goes stale, since it's supplied by the JS
185
+ * engine rather than hand-typed.
186
+ */
187
+ source?: string;
188
+ }
189
+ export {};
190
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/runtime/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,sGAAsG;AACtG,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAEtD,uGAAuG;AACvG,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAA;AAEhD;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAAA;AAEtE;;;;;;;;GAQG;AAEH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAA;AAEpD,gHAAgH;AAChH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACxB,sEAAsE;IACtE,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACxB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;GASG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAA;AAE1D,KAAK,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,GAAG,CAAA;CAAE,GACpD,GAAG,SAAS,MAAM,MAAM,CAAC,GACvB,CAAC,GACD,GAAG,GACL,KAAK,CAAA;AAET;;;;;;;GAOG;AAEH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS;IAClE,kEAAkE;IAClE,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAA;CAC9B,GACG,CAAC,GACD,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAChC,MAAM,GACN,aAAa,CAAC,CAAC,CAAC,CAAA;AAEtB,0GAA0G;AAC1G,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAChE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,SAAS,IAAI;IAC7C,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7C,GAAG;IACF,sGAAsG;IACtG,QAAQ,IAAI,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAA;IACd;;;;;;OAMG;IAEH,QAAQ,EAAE,SAAS,WAAW,CAAC,GAAG,CAAC,EAAE,CAAA;IACrC;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB"}
@@ -0,0 +1,27 @@
1
+ import type { validateEnvOptions, validateEnvResult } from "./types.js";
2
+ /**
3
+ * Validates every variable in every contract in `options.manifest` against
4
+ * `options.values`, then caches the results.
5
+ *
6
+ * @remarks
7
+ * Idempotent: the first successful (or failed) call is authoritative for the life of the
8
+ * process; later calls return (or re-throw) that same outcome without re-running any
9
+ * processor or validator. Concurrent in-flight calls share one underlying run. Call
10
+ * `resetEnvCache()` to validate again, for example between test scenarios.
11
+ *
12
+ * The record of validated values is frozen, but only one level deep: an object, array or `URL`
13
+ * a processor returns stays mutable. A failure message carries variable and contract names and
14
+ * the message your processor or validator produced, never the value itself.
15
+ *
16
+ * @example
17
+ * ```ts
18
+ * import { validateEnv } from "@maverickcer/env-cap"
19
+ * import { manifest } from "./generated/env.manifest"
20
+ *
21
+ * await validateEnv({ manifest, values: process.env })
22
+ * ```
23
+ *
24
+ * @throws {EnvValidationError} If any variable fails processing or validation.
25
+ */
26
+ export declare function validateEnv(options: validateEnvOptions): Promise<validateEnvResult>;
27
+ //# sourceMappingURL=validate.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/runtime/validate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEvE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0BzF"}
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  readToolVersion
4
- } from "./chunk-RL5KFVUT.js";
4
+ } from "./chunk-TBL3O7IG.js";
5
5
 
6
6
  // src/build/evidence-snapshot.ts
7
7
  import path3 from "path";
@@ -393,7 +393,7 @@ async function discoverSchemaFiles(options) {
393
393
  const included = await discoverFiles(options);
394
394
  if (included.length > MAX_DISCOVERED_SCHEMA_FILES) {
395
395
  throw new Error(
396
- `discoverSchemaFiles: found ${String(included.length)} files matching "include" under ${options.root} -- more than the ${String(MAX_DISCOVERED_SCHEMA_FILES)}-file sanity limit. This almost always means "root" (or "include"/"exclude") resolved more broadly than intended -- e.g. an omitted "root" falling back to an unexpectedly large process.cwd() -- rather than a real project genuinely declaring this many contracts. Narrow "root"/"include"/"exclude" to the intended project boundary.`
396
+ `discoverSchemaFiles: found ${String(included.length)} files matching "include" under ${options.root}, more than the ${String(MAX_DISCOVERED_SCHEMA_FILES)}-file sanity limit. This usually means "root" (or "include"/"exclude") resolved more broadly than intended, for example an omitted "root" falling back to a large process.cwd(). Narrow "root"/"include"/"exclude" to the intended project boundary.`
397
397
  );
398
398
  }
399
399
  return included;
@@ -672,7 +672,7 @@ function extractSchemaVariable(key, definition, filePath, contextLabel, warnings
672
672
  } else {
673
673
  warnings.push({
674
674
  file: filePath,
675
- message: evaluated.ok && evaluated.value === "" ? `"context" for "${key}" in "${contextLabel}" is an empty string; ignoring it -- validation contexts must be non-empty.` : `"context" for "${key}" in "${contextLabel}" is not a statically-resolvable string literal; ignoring it.`
675
+ message: evaluated.ok && evaluated.value === "" ? `"context" for "${key}" in "${contextLabel}" is an empty string; ignoring it. Validation contexts must be non-empty.` : `"context" for "${key}" in "${contextLabel}" is not a statically-resolvable string literal; ignoring it.`
676
676
  });
677
677
  }
678
678
  }
@@ -1146,7 +1146,7 @@ function resolveWithinRoot(root, location, optionName, functionName) {
1146
1146
  severity: "error",
1147
1147
  variable: optionName,
1148
1148
  files: [location],
1149
- reason: `"${optionName}" ("${location}") resolves to "${resolved}", which is outside "root" ("${root}"). ${functionName}() refuses to write outside root -- use a path nested under root instead.`
1149
+ reason: `"${optionName}" ("${location}") resolves to "${resolved}", which is outside "root" ("${root}"). ${functionName}() refuses to write outside root. Use a path nested under root instead.`
1150
1150
  }
1151
1151
  };
1152
1152
  }
@@ -1195,7 +1195,7 @@ async function resolveUncached(packageName, root, fs) {
1195
1195
  return {
1196
1196
  ok: false,
1197
1197
  code: "PACKAGE_NOT_FOUND",
1198
- reason: `Package "${packageName}" listed in "packages" could not be resolved from "${root}" -- is it installed?`
1198
+ reason: `Package "${packageName}" listed in "packages" could not be resolved from "${root}". Is it installed?`
1199
1199
  };
1200
1200
  }
1201
1201
  const { packageJsonPath, packageDir } = located;
@@ -1793,7 +1793,7 @@ function buildChangeModel(manifest, currentContracts, root) {
1793
1793
  file: addedRef.file,
1794
1794
  exportName: addedRef.exportName,
1795
1795
  // Resolved from the contract this rename was declared on, not carried
1796
- // on the ref -- see `ContractRef` (`evidence-reference.ts`).
1796
+ // on the ref: see `ContractRef` (`evidence-reference.ts`).
1797
1797
  contractName: contract.contractName,
1798
1798
  previousKey: removedRef.key,
1799
1799
  currentKey: addedRef.key
@@ -1853,7 +1853,7 @@ function detectCompatibilityIssues(contracts) {
1853
1853
  variable: key,
1854
1854
  files: [a.file, b.file],
1855
1855
  code: "PROCESSOR_SOURCE_CONFLICT",
1856
- reason: `"${a.contractName}" and "${b.contractName}" both declare a processor for this variable with different implementations. Return types could not be statically verified -- add explicit return type annotations, or confirm they produce equivalent output.`
1856
+ reason: `"${a.contractName}" and "${b.contractName}" both declare a processor for this variable with different implementations. Return types could not be statically verified. Add explicit return type annotations, or confirm they produce equivalent output.`
1857
1857
  });
1858
1858
  }
1859
1859
  if (a.variable.hasValidator && b.variable.hasValidator && a.variable.validatorSource !== b.variable.validatorSource) {
@@ -1862,7 +1862,7 @@ function detectCompatibilityIssues(contracts) {
1862
1862
  variable: key,
1863
1863
  files: [a.file, b.file],
1864
1864
  code: "VALIDATOR_SOURCE_CONFLICT",
1865
- reason: `"${a.contractName}" and "${b.contractName}" both declare a validator for this variable with different implementations. Validator logic cannot be statically compared -- confirm they enforce compatible rules.`
1865
+ reason: `"${a.contractName}" and "${b.contractName}" both declare a validator for this variable with different implementations. Validator logic cannot be statically compared. Confirm they enforce compatible rules.`
1866
1866
  });
1867
1867
  }
1868
1868
  const divergences = documentationDivergences(a.variable, b.variable);
@@ -1923,7 +1923,7 @@ function detectDuplicateVariableShapes(contracts) {
1923
1923
  variable: `${a.key} / ${b.key}`,
1924
1924
  files: [a.file, b.file],
1925
1925
  code: "DUPLICATE_VARIABLE_SHAPE_ACROSS_CONTRACTS",
1926
- reason: `"${a.key}" (${a.contractName}) and "${b.key}" (${b.contractName}) declare an identical shape (type ${a.shape.valueType}, processor: ${a.shape.hasProcessor ? "yes" : "no"}, validator: ${a.shape.hasValidator ? "yes" : "no"}). Informational only -- they may be the same underlying value modelled twice, or two unrelated values that happen to look alike. Nothing is required.`
1926
+ reason: `"${a.key}" (${a.contractName}) and "${b.key}" (${b.contractName}) declare an identical shape (type ${a.shape.valueType}, processor: ${a.shape.hasProcessor ? "yes" : "no"}, validator: ${a.shape.hasValidator ? "yes" : "no"}). Informational only: they may be the same underlying value modelled twice, or two unrelated values that happen to look alike. Nothing is required.`
1927
1927
  });
1928
1928
  }
1929
1929
  }
@@ -2147,11 +2147,9 @@ function scanFileForDependencies(filePath, sourceText) {
2147
2147
  filePath,
2148
2148
  sourceText,
2149
2149
  ts.ScriptTarget.Latest,
2150
- // Load-bearing, unlike before: `ts.getCombinedNodeFlags()` (used to tell
2151
- // a `const` declaration apart from `let`/`var` when resolving alias
2152
- // candidates) walks parent pointers internally. Flipping this to `false`
2153
- // now breaks const-detection silently rather than merely being an
2154
- // unobserved no-op -- do not remove parent-pointer tracking here.
2150
+ // Load-bearing: `ts.getCombinedNodeFlags()` walks parent pointers. It
2151
+ // tells a `const` declaration from `let`/`var` when resolving alias
2152
+ // candidates. Setting this to `false` breaks const-detection silently.
2155
2153
  true,
2156
2154
  scriptKind
2157
2155
  );
@@ -2264,8 +2262,8 @@ function createGeneratedBanner(describe) {
2264
2262
  return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2265
2263
  },
2266
2264
  // Not a bare `startsWith`: a shebang, a `"use strict"` pragma or a license header pushes a real marker
2267
- // off line one, and a stricter check would read a genuinely generated file as hand-written, which a
2268
- // dependency scan would take as "a real consumer imports this" and so permanently mask an abandoned
2265
+ // off line one. A stricter check would read a genuinely generated file as hand-written. A dependency
2266
+ // scan would take that as "a real consumer imports this", and so permanently mask an abandoned
2269
2267
  // contract. The first 20 non-empty lines clear every realistic preamble without scanning a whole file.
2270
2268
  // A line counts only when the marker opens a comment, as `generatedBanner` writes it, so code or prose that
2271
2269
  // merely quotes the marker is not mistaken for a generated file.
@@ -2473,7 +2471,7 @@ function deriveOwnershipFindings(graph) {
2473
2471
  if (contract.ambiguousBarrelFiles.length > 0) {
2474
2472
  unresolvedConsumers.push({
2475
2473
  ...identity,
2476
- reason: `Not directly imported anywhere, but ${contract.ambiguousBarrelFiles.length} file(s) import "${contract.exportName}" through a specifier that resolves to a file containing an unresolved "export * from" re-export -- cannot determine whether this contract is forwarded by it. Files: ${contract.ambiguousBarrelFiles.join(", ")}.`
2474
+ reason: `Not directly imported anywhere, but ${contract.ambiguousBarrelFiles.length} file(s) import "${contract.exportName}" through a specifier that resolves to a file containing an unresolved "export * from" re-export, so whether this contract is forwarded by it cannot be determined. Files: ${contract.ambiguousBarrelFiles.join(", ")}.`
2477
2475
  });
2478
2476
  } else {
2479
2477
  abandoned.push(identity);
@@ -2495,7 +2493,7 @@ function deriveOwnershipFindings(graph) {
2495
2493
  if (info.status === "unconsumed") {
2496
2494
  unconsumedOwned.push({ ...identity, key });
2497
2495
  } else if (info.status === "indeterminate") {
2498
- const reason = info.evidence === "dynamic-access" ? `Dynamic (computed) property access was observed on "${contract.exportName}" -- cannot determine whether "${key}" is read. Searched: ${surfaces}. Dynamic access observed at: ${formatSites(contract.dynamicAccessSites)}.` : `Contract "${contract.exportName}" is used in a way this scanner's local dataflow analysis cannot follow (a rest binding, nested destructuring, a computed key, an ambiguous alias, or the contract passed/referenced directly) -- cannot determine whether "${key}" is read. Searched: ${surfaces}. Escaped at: ${formatEscapeSites(contract.escapeSites)}.`;
2496
+ const reason = info.evidence === "dynamic-access" ? `Dynamic (computed) property access was observed on "${contract.exportName}", so whether "${key}" is read cannot be determined. Searched: ${surfaces}. Dynamic access observed at: ${formatSites(contract.dynamicAccessSites)}.` : `Contract "${contract.exportName}" is used in a way this scanner's local dataflow analysis cannot follow (a rest binding, nested destructuring, a computed key, an ambiguous alias, or the contract passed/referenced directly), so whether "${key}" is read cannot be determined. Searched: ${surfaces}. Escaped at: ${formatEscapeSites(contract.escapeSites)}.`;
2499
2497
  indeterminate.push({
2500
2498
  ...identity,
2501
2499
  key,
@@ -2672,7 +2670,7 @@ function detectExclusiveGroupIssues(contracts) {
2672
2670
  severity: "error",
2673
2671
  variable: `Exclusive group "${group}"`,
2674
2672
  files: [a.file, b.file],
2675
- reason: `"${a.contractName}" and "${b.contractName}" are both active and both declare exclusiveGroup "${group}" -- only one active contract per exclusive group is allowed. Set active: false on whichever one isn't in use.`
2673
+ reason: `"${a.contractName}" and "${b.contractName}" are both active and both declare exclusiveGroup "${group}". Only one active contract per exclusive group is allowed. Set active: false on whichever one isn't in use.`
2676
2674
  });
2677
2675
  }
2678
2676
  }
@@ -2748,11 +2746,11 @@ function defaultExclude() {
2748
2746
  return [
2749
2747
  // `discoverSchemaFiles()`'s own walk (`discover.ts`) hardcodes skipping
2750
2748
  // a directory literally named "node_modules" or ".git" via its own
2751
- // `isAlwaysSkippedDirName()` check, regardless of `exclude` -- it never
2749
+ // `isAlwaysSkippedDirName()` check, regardless of `exclude`: it never
2752
2750
  // even descends into either to test a glob pattern against it. These
2753
2751
  // two entries are provably redundant (kept for readers/tooling that
2754
2752
  // inspect `exclude` directly, and as defense if that hardcoding ever
2755
- // changes) -- hand-verified: emptying both and running the full
2753
+ // changes). Hand-verified: emptying both and running the full
2756
2754
  // `vitest run` leaves all 1243 tests passing.
2757
2755
  "**/node_modules/**",
2758
2756
  "**/dist/**",
@@ -2843,7 +2841,7 @@ function renderAbandoned(findings) {
2843
2841
  const lines = [
2844
2842
  "## Abandoned ownership",
2845
2843
  "",
2846
- "Contracts never imported anywhere in the scanned repository -- a feature's schema outliving the feature.",
2844
+ "Contracts never imported anywhere in the scanned repository: a feature's schema outliving the feature.",
2847
2845
  "",
2848
2846
  "| Contract | Owner | File |",
2849
2847
  "|---|---|---|"
@@ -2858,7 +2856,7 @@ function renderUnresolvedConsumers(findings) {
2858
2856
  const lines = [
2859
2857
  "## Unresolved consumers (barrel re-exports)",
2860
2858
  "",
2861
- "Contracts reachable only through an unresolved `export * from` barrel re-export -- cannot be proven abandoned or consumed. Advisory only; never fails a build.",
2859
+ "Contracts reachable only through an unresolved `export * from` barrel re-export. They cannot be proven abandoned or consumed. Advisory only; never fails a build.",
2862
2860
  ""
2863
2861
  ];
2864
2862
  for (const f of sortedByContractName(findings))
@@ -2880,7 +2878,7 @@ function renderUnconsumedOwned(findings, scannedSurfaces) {
2880
2878
  "",
2881
2879
  `Searched: ${surfaces}.`,
2882
2880
  "",
2883
- 'A blank Stale/missing citations cell is the strongest "looks genuinely unused" signal -- no developer has ever claimed otherwise. A non-blank cell means someone specifically claimed dynamic access here via `dynamicAccess`, and that claim can no longer be verified (ADR 0037) -- check with them before deleting.',
2881
+ 'A blank Stale/missing citations cell is the strongest "looks unused" signal: no developer has ever claimed otherwise. A non-blank cell means someone specifically claimed dynamic access here via `dynamicAccess`, and that claim can no longer be verified (ADR 0037). Check with them before deleting.',
2884
2882
  "",
2885
2883
  "| Variable | Contract | Owner | Stale/missing citations |",
2886
2884
  "|---|---|---|---|"
@@ -2897,7 +2895,7 @@ function renderIndeterminate(findings) {
2897
2895
  const lines = [
2898
2896
  "## Indeterminate (dynamic access)",
2899
2897
  "",
2900
- "Dynamic (computed) property access was observed -- usage cannot be determined statically. Never guessed at.",
2898
+ "Dynamic (computed) property access was observed, so usage cannot be determined statically. Never guessed at.",
2901
2899
  "",
2902
2900
  "| Variable | Contract | Reason | Stale/missing citations |",
2903
2901
  "|---|---|---|---|"
@@ -2918,7 +2916,7 @@ function renderAsserted(findings) {
2918
2916
  const lines = [
2919
2917
  "## Asserted (developer-acknowledged dynamic access)",
2920
2918
  "",
2921
- "Variables env-cap's own scan would otherwise flag as unconsumed or indeterminate, but a developer has cited exactly where the dynamic access happens via `dynamicAccess`. The raw static status is shown alongside the citation, never hidden behind it -- a citation is a re-acknowledgment, not proof.",
2919
+ "Variables env-cap's own scan would otherwise flag as unconsumed or indeterminate, but a developer has cited exactly where the dynamic access happens via `dynamicAccess`. The raw static status is shown alongside the citation, never hidden behind it. A citation is a re-acknowledgment, not proof.",
2922
2920
  "",
2923
2921
  "| Variable | Contract | Static status | Developer assertion |",
2924
2922
  "|---|---|---|---|"
@@ -3255,7 +3253,7 @@ function buildFindingModel(input) {
3255
3253
  severity: "info",
3256
3254
  code: "NONSTANDARD_SENSITIVITY_LEVEL",
3257
3255
  family: "documentation",
3258
- message: `"${n.key ?? n.exportName}" declares sensitivity "${n.sensitivity}", which isn't one of the standard levels (secret/credential/pii/config) -- still honored verbatim, just flagged for vocabulary drift.`,
3256
+ message: `"${n.key ?? n.exportName}" declares sensitivity "${n.sensitivity}", which isn't one of the standard levels (secret/credential/pii/config). It is still honored verbatim, only flagged for vocabulary drift.`,
3259
3257
  location: {
3260
3258
  model: "contract",
3261
3259
  file: displayPath(root, n.file),
@@ -3339,7 +3337,7 @@ function buildFindingModel(input) {
3339
3337
  contractName: i.contractName,
3340
3338
  file: void 0,
3341
3339
  variable: i.key,
3342
- // Multiple candidate sites, never one representative pointer -- see
3340
+ // Multiple candidate sites, never one representative pointer: see
3343
3341
  // `IndeterminateOwnershipFinding.dynamicAccessSites` for the full list.
3344
3342
  position: NO_POSITION
3345
3343
  }
@@ -3356,12 +3354,12 @@ function buildFindingModel(input) {
3356
3354
  model: "ownership",
3357
3355
  contractName: p.contractName,
3358
3356
  // p.file (DynamicAccessCitationProblem.file) is already
3359
- // root-relative -- unlike every other .file above, not a raw
3360
- // absolute path -- so no displayPath() conversion here.
3357
+ // root-relative (unlike every other .file above, not a raw
3358
+ // absolute path) so no displayPath() conversion here.
3361
3359
  file: p.file,
3362
3360
  variable: p.key,
3363
3361
  // The one ownership-family finding with a genuinely meaningful
3364
- // position -- exactly where the (now-stale/missing) citation points.
3362
+ // position: exactly where the (now-stale/missing) citation points.
3365
3363
  position: p.position
3366
3364
  }
3367
3365
  });
@@ -3401,7 +3399,7 @@ function defineEvidenceProjection(schema) {
3401
3399
  }
3402
3400
  function readOnlyMembraneError() {
3403
3401
  return new TypeError(
3404
- "EvidenceModel is read-only inside a projector -- a projection must be a pure function of its evidence argument. See ADR 0032."
3402
+ "EvidenceModel is read-only inside a projector. A projection must be a pure function of its evidence argument. See ADR 0032."
3405
3403
  );
3406
3404
  }
3407
3405
  function createTrackingProxy(evidence) {
@@ -4137,7 +4135,7 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
4137
4135
  lines.push(
4138
4136
  ...renderVariableLines(dup.variable, {
4139
4137
  commented: true,
4140
- note: `Also declared by "${dup.contract.contractName}" -- see "${first.contract.contractName}" above.`
4138
+ note: `Also declared by "${dup.contract.contractName}". See "${first.contract.contractName}" above.`
4141
4139
  })
4142
4140
  );
4143
4141
  }
@@ -4149,7 +4147,7 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
4149
4147
  lines.push(
4150
4148
  ...renderVariableLines(first.variable, {
4151
4149
  commented: true,
4152
- note: `Disabled -- feature "${first.contract.contractName}" is not active.`
4150
+ note: `Disabled: feature "${first.contract.contractName}" is not active.`
4153
4151
  })
4154
4152
  );
4155
4153
  }
@@ -5063,7 +5061,7 @@ async function checkEnvArtifacts(options) {
5063
5061
  path: c.docs.envExamplePath,
5064
5062
  status: driftCount > 0 ? "stale" : "ok",
5065
5063
  // exactOptionalPropertyTypes: omit the key entirely rather than
5066
- // set it to `undefined` -- `detail` is absent when there's
5064
+ // set it to `undefined`; `detail` is absent when there's
5067
5065
  // nothing to report, not present-but-empty.
5068
5066
  ...driftCount > 0 ? {
5069
5067
  detail: `${staleVariables.length} stale, ${variablesToComment.length} to comment, ${variablesToAdd.length} to add`
@@ -5098,15 +5096,18 @@ async function checkEnvArtifacts(options) {
5098
5096
  function sarifLevel(severity) {
5099
5097
  return severity === "info" ? "note" : severity;
5100
5098
  }
5099
+ function uriReference(file) {
5100
+ return encodeURI(file).replace(/#/g, "%23").replace(/\?/g, "%3F");
5101
+ }
5101
5102
  function sarifLocations(finding) {
5102
5103
  const location = finding.location;
5103
- const uri = location.model === "change" ? location.path : location.file;
5104
- if (uri === void 0) return void 0;
5105
5104
  const { position } = location;
5105
+ const file = position?.file ?? (location.model === "change" ? location.path : location.file);
5106
+ if (file === void 0) return void 0;
5106
5107
  return [
5107
5108
  {
5108
5109
  physicalLocation: {
5109
- artifactLocation: { uri },
5110
+ artifactLocation: { uri: uriReference(file) },
5110
5111
  ...position === void 0 ? {} : { region: { startLine: position.line, startColumn: position.column } }
5111
5112
  }
5112
5113
  }
@@ -5127,9 +5128,9 @@ function buildSarifLog(findingModel) {
5127
5128
  rules: ruleIds.map((id) => ({ id }))
5128
5129
  }
5129
5130
  },
5130
- // exactOptionalPropertyTypes: spread `locations` in only when
5131
- // sarifLocations() actually has one, rather than ever setting the
5132
- // key to `undefined` explicitly.
5131
+ // Under `exactOptionalPropertyTypes` the key must be absent, never
5132
+ // `undefined`. So `locations` is spread in only when
5133
+ // `sarifLocations()` has one.
5133
5134
  results: findingModel.findings.map((finding) => {
5134
5135
  const locations = sarifLocations(finding);
5135
5136
  return {
@@ -5205,4 +5206,4 @@ export {
5205
5206
  resolveRelativeImport,
5206
5207
  writeEnvExample
5207
5208
  };
5208
- //# sourceMappingURL=build-6XFHJFQK.js.map
5209
+ //# sourceMappingURL=build-UEENZEUX.js.map