@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,20 @@
1
+ /**
2
+ * Recursively freezes `value` and everything reachable from it (array
3
+ * elements, plain-object property values), so a mutation anywhere in the
4
+ * structure throws instead of silently succeeding.
5
+ *
6
+ * @remarks
7
+ * Generalized from `live-expirations.ts`'s former `DiscoveredContract[]`-
8
+ * hardcoded `deepFreezeContracts()` (see ADR 0012) into a truly generic
9
+ * utility, so Evidence Model's own immutability guarantee (a later phase)
10
+ * can reuse it instead of duplicating the recursion.
11
+ *
12
+ * Only recurses into arrays and plain objects (`{}` or `Object.create(null)`):
13
+ * a `Map`, `Set`, or class instance is frozen at its own top level but not
14
+ * walked further. This codebase's fact models are plain JSON-serializable
15
+ * data, never class instances, so this is deliberately narrow rather than a
16
+ * general-purpose deep-freeze library. A `WeakSet` guards against infinite
17
+ * recursion if a cyclic reference is ever passed in.
18
+ */
19
+ export declare function deepFreeze<T>(value: T): T;
20
+ //# sourceMappingURL=deep-freeze.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"deep-freeze.d.ts","sourceRoot":"","sources":["../../../src/build/deep-freeze.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAEzC"}
@@ -0,0 +1,163 @@
1
+ import type { EscapeReason } from "./scan-dependencies.js";
2
+ import type { ImportResolutionContext } from "./resolution/resolve-import.js";
3
+ import type { DiscoveredContract } from "./link.js";
4
+ import type { ParseWarning } from "./parse.js";
5
+ import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
6
+ /**
7
+ * What env-cap's static scan could prove about one variable's consumption.
8
+ * It was member-accessed somewhere (`"used"`), or never accessed within the
9
+ * scanned surfaces (`"unconsumed"`). Or a computed (dynamic) property access
10
+ * on the owning contract makes the answer unprovable (`"indeterminate"`).
11
+ *
12
+ * @remarks
13
+ * Deliberately narrower than `data-cap`'s equivalent. That one splits the
14
+ * unprovable case further (an unresolved *consumer* vs. an indeterminate
15
+ * *field*). That split exists because a data-cap capability exposes many
16
+ * fields at once. It has a real "we resolved the consumer, but can't tell
17
+ * which field it touched" state to name. In env-cap, the consumption model
18
+ * is one value per key. A contract member access either
19
+ * names the key statically (`"used"`) or it doesn't (`"indeterminate"`).
20
+ * There is no intermediate case where the consumer is known but the thing
21
+ * consumed is ambiguous. A fourth state here would borrow vocabulary from a
22
+ * model env-cap doesn't have: see ADR 0010's "provable, not heuristic" rule. Developer-declared `dynamicAccess`
23
+ * citations stay a wholly separate fact and are never folded into this
24
+ * status (ADR 0037).
25
+ */
26
+ export type VariableAccessStatus = "used" | "unconsumed" | "indeterminate";
27
+ /**
28
+ * Every reason `deriveOwnershipFindings` can cite for an `indeterminate`
29
+ * variable, cited on the {@link EscapeSite} the scanner actually observed.
30
+ * `EscapeReason` covers destructuring/aliasing shapes the scanner declines to
31
+ * follow (see ADR 0039). `"reference"` covers a tracked import/alias
32
+ * mentioned bare (passed as an argument, spread, assigned elsewhere, ...).
33
+ * That is a real, provable read of the contract, but this single-file walk
34
+ * can't attribute it to any specific key.
35
+ */
36
+ type EscapeVia = EscapeReason | "reference";
37
+ /** One position where a tracked contract's value escaped this scanner's local dataflow analysis: see {@link EscapeVia}. */
38
+ interface EscapeSite extends SourcePosition {
39
+ readonly via: EscapeVia;
40
+ }
41
+ interface VariableAccessInfo {
42
+ readonly status: VariableAccessStatus;
43
+ /** Internal only, never exposed publicly: which AST evidence produced
44
+ * this status. A "why does env-cap think this is unconsumed" bug report
45
+ * is then debuggable without re-deriving the AST walk by hand. */
46
+ readonly evidence: "member-access" | "dynamic-access" | "escape" | "no-access";
47
+ /** Every position where a member access was observed for this variable,
48
+ * aggregated across every consuming file: empty unless
49
+ * `status === "used"`. Taken from `scan-dependencies.ts`'s `AccessSite`
50
+ * so `dependency-model.ts` can publish it: the line since ADR 0027, the
51
+ * full position since ADR 0036. There is one entry per file, not a flat,
52
+ * file-less list of line numbers. */
53
+ readonly positions: readonly SourcePosition[];
54
+ /** Every developer-declared `dynamicAccess` citation's current freshness for this variable: a wholly separate, independent fact from `status`/`evidence` above, never folded into them. Empty unless the linked `documentEnv()` call declared at least one citation for this key. See ADR 0037. */
55
+ readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
56
+ }
57
+ /** One named surface `buildDependencyGraph()`'s scan actually covered: the
58
+ * application's own root, plus one entry per allow-listed `packages` (ADR
59
+ * 0014) name whose source was also scanned. See ADR 0036. A claim like
60
+ * "no consumer found" is only as strong as what was searched. This lets a
61
+ * renderer say so explicitly, not imply an unbounded guarantee. */
62
+ export interface ScannedSurface {
63
+ /** `"application"` for the local project root, `"package:<name>"` for an allow-listed package's own source. */
64
+ readonly label: string;
65
+ /** Root-relative, POSIX-separated. */
66
+ readonly root: string;
67
+ }
68
+ interface ContractDependencySummary {
69
+ readonly file: string;
70
+ readonly exportName: string;
71
+ readonly contractName: string;
72
+ readonly imported: boolean;
73
+ readonly hasDynamicAccess: boolean;
74
+ /** Every declared key is always present. */
75
+ readonly variables: ReadonlyMap<string, VariableAccessInfo>;
76
+ /** Every file coupled to this contract: contract-level "who depends on
77
+ * this," not proof any specific variable was read. See the
78
+ * consumer-vs-variable-access semantics note in `deriveOwnershipFindings`. */
79
+ readonly consumingFiles: readonly string[];
80
+ /** Files whose import of this contract's name couldn't be verified
81
+ * because it resolved through a file containing an unresolved wildcard
82
+ * re-export. */
83
+ readonly ambiguousBarrelFiles: readonly string[];
84
+ /** Every computed (dynamic) property-access site observed anywhere on
85
+ * this contract (ADR 0036). `hasDynamicAccess` only says that one exists.
86
+ * This list lets a finding cite where the uncertainty comes from. */
87
+ readonly dynamicAccessSites: readonly SourcePosition[];
88
+ /** Every position where the contract's value flowed somewhere this
89
+ * scanner's local dataflow analysis can't follow: see {@link
90
+ * EscapeVia} and ADR 0039. Like `dynamicAccessSites`, this widens every
91
+ * not-otherwise-accessed variable on the SAME contract to
92
+ * `indeterminate`, never `unconsumed`. */
93
+ readonly escapeSites: readonly EscapeSite[];
94
+ }
95
+ export interface DependencyGraph {
96
+ readonly contracts: readonly ContractDependencySummary[];
97
+ readonly warnings: readonly ParseWarning[];
98
+ /** Every surface actually scanned for usage: see {@link ScannedSurface}. Always has at least one entry (the application root). */
99
+ readonly scannedSurfaces: readonly ScannedSurface[];
100
+ }
101
+ /** Sorts two positions by file, then line. @internal Exported for direct unit coverage. */
102
+ export declare function byPosition(a: SourcePosition, b: SourcePosition): number;
103
+ export declare function buildDependencyGraph(contracts: readonly DiscoveredContract[], scanFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, scannedSurfaces?: readonly ScannedSurface[], dynamicAccessAcknowledgments?: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): Promise<DependencyGraph>;
104
+ interface AbandonedOwnershipFinding {
105
+ readonly file: string;
106
+ readonly exportName: string;
107
+ readonly contractName: string;
108
+ }
109
+ interface UnresolvedConsumerOwnershipFinding extends AbandonedOwnershipFinding {
110
+ readonly reason: string;
111
+ }
112
+ interface UnconsumedOwnedVariableOwnershipFinding extends AbandonedOwnershipFinding {
113
+ readonly key: string;
114
+ }
115
+ interface IndeterminateAccessOwnershipFinding extends AbandonedOwnershipFinding {
116
+ readonly key: string;
117
+ readonly reason: string;
118
+ /** Every AST-observed dynamic-access site on this contract: see ADR 0036. */
119
+ readonly dynamicAccessSites: readonly SourcePosition[];
120
+ /** Every AST-observed escape site on this contract: see {@link EscapeVia} and ADR 0039. */
121
+ readonly escapeSites: readonly EscapeSite[];
122
+ }
123
+ /** A variable that would otherwise be `unconsumedOwned`/`indeterminate`, but has at least one `"fresh"` developer-declared `dynamicAccess` assertion: the "asserted" category (ADR 0037). Never silently dropped: the raw `wouldBeStatus` is always shown alongside the assertion, per Design 7's "never let a claim overwrite an observation" rule. */
124
+ interface AssertedOwnershipFinding extends AbandonedOwnershipFinding {
125
+ readonly key: string;
126
+ readonly wouldBeStatus: "unconsumed" | "indeterminate";
127
+ readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
128
+ }
129
+ export interface OwnershipFindings {
130
+ readonly abandoned: readonly AbandonedOwnershipFinding[];
131
+ readonly unresolvedConsumers: readonly UnresolvedConsumerOwnershipFinding[];
132
+ readonly unconsumedOwned: readonly UnconsumedOwnedVariableOwnershipFinding[];
133
+ readonly indeterminate: readonly IndeterminateAccessOwnershipFinding[];
134
+ readonly asserted: readonly AssertedOwnershipFinding[];
135
+ }
136
+ /**
137
+ * Derives ownership findings from the graph. This is where the epistemic
138
+ * rules that matter most live:
139
+ * - A contract never imported anywhere, with no ambiguous barrel path
140
+ * either, is `abandoned`; a feature's schema outliving the feature.
141
+ * - A contract never *directly* imported, but reachable only through an
142
+ * unresolved barrel re-export, is `unresolvedConsumers`: never
143
+ * `abandoned`. Claiming "abandoned" here would be a false positive with
144
+ * real consequences.
145
+ * - A variable with no member access anywhere, on a contract with no
146
+ * dynamic access anywhere, is `unconsumedOwned`. That means "no consumer
147
+ * found in this repository", not "provably dead". The scanned surfaces are named
148
+ * explicitly in the reason, per ADR 0036, so the claim is exactly as
149
+ * strong as what was actually searched.
150
+ * - A variable with no member access, but dynamic access observed
151
+ * *somewhere* on that contract, is `indeterminate`: never
152
+ * `unconsumedOwned`. Uncertainty is never promoted to certainty in either
153
+ * direction. Every candidate dynamic-access site is cited by name.
154
+ * - A variable with at least one `"fresh"` {@link DynamicAccessAssertion}
155
+ * (ADR 0037) gets neither `unconsumedOwned` nor `indeterminate`, regardless
156
+ * of `status`: a developer has re-acknowledged the access exists. The
157
+ * Dependency Model itself still keeps `status` and the assertion side by
158
+ * side, unedited; only *this* finding-suppression decision reads them
159
+ * together.
160
+ */
161
+ export declare function deriveOwnershipFindings(graph: DependencyGraph): OwnershipFindings;
162
+ export {};
163
+ //# sourceMappingURL=dependency-graph.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../../../src/build/dependency-graph.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,81 @@
1
+ import type { ContractRef } from "./evidence-reference.js";
2
+ import type { ScannedSurface, VariableAccessStatus } from "./dependency-graph.js";
3
+ import type { DiscoveredContract } from "./link.js";
4
+ import type { ParseWarning } from "./parse.js";
5
+ import type { ImportResolutionContext } from "./resolution/resolve-import.js";
6
+ import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
7
+ /**
8
+ * The second of env-cap's seven canonical fact models (ADR 0024): a
9
+ * versioned, JSON-serializable projection of the dependency-ownership
10
+ * engine's graph. See ADR 0027 and ADR 0036.
11
+ *
12
+ * @remarks
13
+ * `dependency-graph.ts`'s scanning/graph-building internals stay Private,
14
+ * unchanged, per ADR 0010: this is a fact-shaped *result* built on top of
15
+ * them, not a relaxation of that boundary. Graph-format rendering (DOT,
16
+ * Mermaid, a `{nodes, edges}` JSON export) is deliberately not here:
17
+ * that's presentation over this model's data, not the model itself.
18
+ */
19
+ /** Bump only when a reader could misinterpret the new shape: same discipline every other canonical model's `schemaVersion` follows. */
20
+ export declare const DEPENDENCY_MODEL_SCHEMA_VERSION = 2;
21
+ /**
22
+ * One variable's access status within a contract, plus every position it was found
23
+ * member-accessed at, aggregated across every consuming file.
24
+ *
25
+ * @see {@link ContractModelVariable}: this same declared variable's canonical starting point.
26
+ */
27
+ export interface DependencyModelVariable {
28
+ readonly key: string;
29
+ readonly status: VariableAccessStatus;
30
+ /** Empty unless `status === "used"`. Each entry is a full position with its file (ADR 0027, ADR 0036). */
31
+ readonly positions: readonly SourcePosition[];
32
+ /** Every developer-declared `dynamicAccess` citation's current freshness for this variable: a wholly separate, independent fact from `status` above, never folded into it. Empty when no citation was declared, or when no manifest snapshot baseline was available to check against (the manifest pass wasn't also requested). See ADR 0037. */
33
+ readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
34
+ }
35
+ /** One contract's dependency-ownership facts: which variables were accessed, which files consume it, and every dynamic/ambiguous access site found. See {@link DependencyModelVariable} for the per-variable breakdown. */
36
+ export interface DependencyModelContract {
37
+ /** Root-relative, POSIX-separated: matches `ContractModelContract.file`. */
38
+ readonly file: string;
39
+ readonly exportName: string;
40
+ readonly contractName: string;
41
+ readonly imported: boolean;
42
+ readonly hasDynamicAccess: boolean;
43
+ readonly variables: readonly DependencyModelVariable[];
44
+ /** Every file coupled to this contract: contract-level "who depends on this," not proof any specific variable was read. */
45
+ readonly consumingFiles: readonly string[];
46
+ /** Files whose import of this contract's name couldn't be verified because it resolved through a file containing an unresolved wildcard re-export. */
47
+ readonly ambiguousBarrelFiles: readonly string[];
48
+ /** Every computed (dynamic) property-access site observed anywhere on this contract: see ADR 0036. */
49
+ readonly dynamicAccessSites: readonly SourcePosition[];
50
+ }
51
+ /** One contract, as referenced from the inverse (`consumers`) index: see {@link ContractRef} for why no `contractName` is carried here. */
52
+ export type DependencyModelContractRef = ContractRef;
53
+ /** One consuming file, and every contract it depends on: the inverse of `DependencyModelContract.consumingFiles`. */
54
+ export interface DependencyModelConsumer {
55
+ /** Root-relative, POSIX-separated. */
56
+ readonly file: string;
57
+ readonly contracts: readonly DependencyModelContractRef[];
58
+ }
59
+ /** The versioned, JSON-serializable root of the Dependency Model: see this module's own doc comment for the full picture. */
60
+ export interface DependencyModel {
61
+ readonly schemaVersion: typeof DEPENDENCY_MODEL_SCHEMA_VERSION;
62
+ readonly contracts: readonly DependencyModelContract[];
63
+ /** Inverse of `contracts[].consumingFiles`: one entry per file that consumes at least one contract, listing which contracts it reads. */
64
+ readonly consumers: readonly DependencyModelConsumer[];
65
+ readonly warnings: readonly ParseWarning[];
66
+ /** Every surface actually scanned for usage: see ADR 0036. Always has at least one entry (the application root). */
67
+ readonly scannedSurfaces: readonly ScannedSurface[];
68
+ }
69
+ /**
70
+ * Runs the dependency-ownership engine (`buildDependencyGraph()`, Private)
71
+ * and projects its result into the Dependency Model's versioned,
72
+ * JSON-serializable shape: including the inverse file-\>contracts index
73
+ * neither `dependency-graph.ts` nor `usage-report.ts` exposes today.
74
+ *
75
+ * @param scannedSurfaces - See `buildDependencyGraph()`'s own parameter of
76
+ * the same name: passed straight through to the published model.
77
+ * @param dynamicAccessAcknowledgments - See `buildDependencyGraph()`'s own
78
+ * parameter of the same name (ADR 0037): passed straight through.
79
+ */
80
+ export declare function buildDependencyModel(contracts: readonly DiscoveredContract[], scanFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, root: string, scannedSurfaces?: readonly ScannedSurface[], dynamicAccessAcknowledgments?: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): Promise<DependencyModel>;
81
+ //# sourceMappingURL=dependency-model.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dependency-model.d.ts","sourceRoot":"","sources":["../../../src/build/dependency-model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAElF;;;;;;;;;;;GAWG;AAEH,uIAAuI;AACvI,eAAO,MAAM,+BAA+B,IAAI,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;IACrC,0GAA0G;IAC1G,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAA;IAC7C,iVAAiV;IACjV,QAAQ,CAAC,uBAAuB,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACpE;AAED,2NAA2N;AAC3N,MAAM,WAAW,uBAAuB;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD,2HAA2H;IAC3H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,sJAAsJ;IACtJ,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAA;IAChD,sGAAsG;IACtG,QAAQ,CAAC,kBAAkB,EAAE,SAAS,cAAc,EAAE,CAAA;CACvD;AAED,2IAA2I;AAC3I,MAAM,MAAM,0BAA0B,GAAG,WAAW,CAAA;AAEpD,qHAAqH;AACrH,MAAM,WAAW,uBAAuB;IACtC,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,SAAS,0BAA0B,EAAE,CAAA;CAC1D;AAED,6HAA6H;AAC7H,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,+BAA+B,CAAA;IAC9D,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD,yIAAyI;IACzI,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACtD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;IAC1C,oHAAoH;IACpH,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAA;CACpD;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC/C,OAAO,EAAE,uBAAuB,EAChC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,EAC3C,4BAA4B,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,GACpF,OAAO,CAAC,eAAe,CAAC,CAoE1B"}
@@ -0,0 +1,41 @@
1
+ import type { BuildFileSystem } from "./types.js";
2
+ /** Options for {@link discoverSchemaFiles}. */
3
+ export interface DiscoverOptions {
4
+ /** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
5
+ readonly fs: BuildFileSystem;
6
+ /** Absolute path to search under. */
7
+ readonly root: string;
8
+ /** Glob patterns (relative to `root`) a file must match at least one of to be included. */
9
+ readonly include: readonly string[];
10
+ /** Glob patterns (relative to `root`) that prune a file or directory regardless of `include`. */
11
+ readonly exclude: readonly string[];
12
+ }
13
+ /**
14
+ * Finds every file matching `include`/`exclude` under `root`, returned as
15
+ * absolute paths in deterministic (alphabetically sorted) order. No count
16
+ * limit: the usage scan walks every TypeScript source file, which a large
17
+ * project legitimately has thousands of; {@link discoverSchemaFiles} adds the
18
+ * schema-specific sanity limit on top.
19
+ *
20
+ * @remarks
21
+ * No external glob dependency. Directories are pruned *during* the walk
22
+ * (both a hardcoded node_modules/.git skip and the caller's `exclude`
23
+ * patterns), not walked in full and filtered afterward. Walking an entire
24
+ * node_modules tree just to discard it is not acceptable for a tool meant to
25
+ * run against real projects.
26
+ */
27
+ export declare function discoverFiles(options: DiscoverOptions): Promise<string[]>;
28
+ /**
29
+ * Finds every schema file matching `include`/`exclude` under `root`, returned
30
+ * as absolute paths in deterministic (alphabetically sorted) order: the
31
+ * same walk as `discoverFiles`, plus a sanity limit on the count.
32
+ *
33
+ * @remarks
34
+ * No external glob dependency. Directories are pruned *during* the walk
35
+ * (both a hardcoded node_modules/.git skip and the caller's `exclude`
36
+ * patterns), not walked in full and filtered afterward. Walking an entire
37
+ * node_modules tree just to discard it is not acceptable for a tool meant to
38
+ * run against real projects.
39
+ */
40
+ export declare function discoverSchemaFiles(options: DiscoverOptions): Promise<string[]>;
41
+ //# sourceMappingURL=discover.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/build/discover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAgBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAa/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBrF"}
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Root-relative paths for published artifacts, bound to env-cap. The behavior lives in
3
+ * `../_ipc/display-path.ts`, a managed copy of internal-package-contract's `runtime/display-path.ts`.
4
+ */
5
+ export { displayPath } from "../_ipc/display-path.js";
6
+ //# sourceMappingURL=display-path.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"display-path.d.ts","sourceRoot":"","sources":["../../../src/build/display-path.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA"}
@@ -0,0 +1,172 @@
1
+ import type { ContractModelContract } from "./contract-model.js";
2
+ import { type EnvGovernanceFields } from "./governance-fields.js";
3
+ import type { DiscoveredVariableEvidence } from "./parse.js";
4
+ /** Identifies a contract with no linked `documentEnv()` call at all. Whether `file` is absolute or relative depends on the field using this type. `DocumentationFindings.undocumentedContracts` is absolute. `RenderDocsOptions.undocumentedContracts` must be root-relative, matching the `ContractModel`-shaped `contracts` it's compared against. */
5
+ export interface UndocumentedContractRef {
6
+ readonly file: string;
7
+ /** The contract's exported binding name. */
8
+ readonly exportName: string;
9
+ }
10
+ /** Identifies a schema variable with no matching entry in its contract's linked documentation. See {@link UndocumentedContractRef}'s own note on `file`. */
11
+ export interface UndocumentedVariableRef {
12
+ readonly file: string;
13
+ /** The contract's exported binding name. */
14
+ readonly exportName: string;
15
+ /** The undocumented environment variable name. */
16
+ readonly key: string;
17
+ }
18
+ /** One contract- or variable-level `expiresAt` falling within the configured "expiring soon" window. */
19
+ export interface ExpiringEntry {
20
+ /** Absolute path of the file declaring the contract. */
21
+ readonly file: string;
22
+ /** The contract's exported binding name. */
23
+ readonly exportName: string;
24
+ /** `undefined` for a contract-level `expiresAt`, set for a per-variable one. */
25
+ readonly key: string | undefined;
26
+ /** The raw ISO date string, unparsed. */
27
+ readonly expiresAt: string;
28
+ /** Days from `now` until expiry; negative when already expired. */
29
+ readonly daysRemaining: number;
30
+ }
31
+ /** Options for {@link renderDocs}. */
32
+ export interface RenderDocsOptions {
33
+ /** How many days out counts as "expiring soon" in the lifecycle report and security review. */
34
+ readonly expiringWithinDays: number;
35
+ /** Contracts with no linked `documentEnv()` call at all. `file` must be root-relative, POSIX-separated: matching `contracts`' own `ContractModel` convention, since this is matched against it by identity. */
36
+ readonly undocumentedContracts: readonly UndocumentedContractRef[];
37
+ /** Schema variables with no matching entry in their contract's linked documentation. Only how many there are is rendered (the security-review counter), so `file` is not matched against anything. */
38
+ readonly undocumentedVariables: readonly UndocumentedVariableRef[];
39
+ /** Timestamp rendered into the header and used for expiry/days-remaining math. */
40
+ readonly generatedAt: Date;
41
+ /** Content already at `docs.location`, if any: used only for the "changes since last report" summary. */
42
+ readonly previousContent: string | undefined;
43
+ }
44
+ /**
45
+ * Parses `expiresAt` as a real date.
46
+ *
47
+ * @remarks
48
+ * Malformed strings are silently ignored (return `undefined`) rather than throwing: same
49
+ * "warn/skip, never guess" policy as the rest of the generator. Exported so `live-expirations.ts`
50
+ * can validate live override values against the exact same rule used for static `expiresAt`.
51
+ */
52
+ export declare function parseIsoDate(value: string): Date | undefined;
53
+ /** The minimal shape {@link computeExpiringEntries} needs. It is structural, not pinned to `DiscoveredContract`, so one rule serves both kinds of contract. Those are `LinkResult`'s absolute-path contracts (`generate-documentation.ts`'s `documentation.expiringSoon`, Stable tier) and `ContractModel`'s root-relative ones. */
54
+ interface ExpiryBearingContract {
55
+ readonly file: string;
56
+ readonly exportName: string;
57
+ readonly expiresAt: string | undefined;
58
+ readonly variables: readonly {
59
+ readonly key: string;
60
+ readonly expiresAt: string | undefined;
61
+ }[];
62
+ }
63
+ /**
64
+ * Computes every contract- or variable-level `expiresAt` within `expiringWithinDays` of `now`, sorted soonest-first.
65
+ */
66
+ export declare function computeExpiringEntries(contracts: readonly ExpiryBearingContract[], expiringWithinDays: number, now: Date): ExpiringEntry[];
67
+ /**
68
+ * Same data `renderCatalog()` renders to Markdown for one variable, reshaped for JSON/
69
+ * programmatic consumers instead of prose.
70
+ *
71
+ * @see `ContractModelVariable` (`contract-model.ts`): this same declared variable's canonical
72
+ * starting point. Plain reference, not `{@link}`: this type is intentionally not part of the
73
+ * public surface (see `typedoc.json`'s `intentionallyNotExported`).
74
+ */
75
+ interface CatalogVariable extends EnvGovernanceFields {
76
+ readonly description: string | undefined;
77
+ readonly refreshInstructions: string | undefined;
78
+ readonly setupInstructions: string | undefined;
79
+ readonly required: boolean | undefined;
80
+ readonly hasDefault: boolean;
81
+ readonly hasProcessor: boolean;
82
+ readonly processorReturnType: string | undefined;
83
+ readonly hasValidator: boolean;
84
+ readonly documented: boolean;
85
+ /** The variable's declared validation context, if any: see ADR 0022. Participation data, not documentation: describes when `validateEnv()` processes this variable, not who may access it or what a bundler includes. */
86
+ readonly context: string | undefined;
87
+ /** The `evidence` sub-object from this variable's linked documentation: re-verified every run, unlike every declared-only field above. See ADR 0037. */
88
+ readonly evidence: DiscoveredVariableEvidence | undefined;
89
+ }
90
+ export interface CatalogContract extends EnvGovernanceFields {
91
+ readonly file: string;
92
+ readonly exportName: string;
93
+ readonly contractName: string;
94
+ readonly active: boolean;
95
+ readonly documented: boolean;
96
+ readonly category: string | undefined;
97
+ readonly exclusiveGroup: string | undefined;
98
+ /** Keyed by variable name: unique within one contract (a schema
99
+ * object-literal property name), unlike `contractName` at the top level. */
100
+ readonly variables: Readonly<Record<string, CatalogVariable>>;
101
+ }
102
+ /**
103
+ * Same data `renderCatalog()` renders to Markdown, reshaped for JSON/
104
+ * programmatic consumers instead of prose. See `GenerateDocumentationResult.catalog`.
105
+ */
106
+ export declare function buildCatalog(contracts: readonly ContractModelContract[]): CatalogContract[];
107
+ /** Every variable key that appeared as a catalog heading in a previously-generated docs file. Exported for testing. */
108
+ export declare function extractPreviouslyDocumentedKeys(previousContent: string): Set<string>;
109
+ /**
110
+ * Every variable key that was documented under an *active* contract in a
111
+ * previously-generated docs file. It walks the `- Active: yes/no` marker
112
+ * `renderCatalog` always emits right after each `## <contract>` heading. So a
113
+ * key already inactive last time is excluded (a permanently-dormant contract,
114
+ * e.g. behind an unused feature flag). It is excluded even though it still
115
+ * appears as a `### \`KEY\`` heading. Exported for testing.
116
+ */
117
+ export declare function extractPreviouslyActiveKeys(previousContent: string): Set<string>;
118
+ /** Every number the security review reports, as structured data instead of only rendered Markdown text. */
119
+ export interface SecurityReviewCounters {
120
+ readonly totalContracts: number;
121
+ readonly totalVariableDeclarations: number;
122
+ readonly activeVariableDeclarations: number;
123
+ readonly uniqueVariableNames: number;
124
+ readonly expiresAtSetCount: number;
125
+ readonly expiredCount: number;
126
+ readonly expiringSoonCount: number;
127
+ readonly requiredCount: number;
128
+ readonly refreshInstructionsCount: number;
129
+ readonly noOwnerCount: number;
130
+ readonly duplicateVariableNameCount: number;
131
+ readonly undocumentedContractCount: number;
132
+ readonly undocumentedVariableCount: number;
133
+ }
134
+ /**
135
+ * Computes every number `renderSecurityReview()` reports, as real data.
136
+ *
137
+ * @remarks
138
+ * An exported type backs these numbers. So consumers other than the
139
+ * rendered Markdown can read them as data: the `--json` envelope, a CI gate,
140
+ * a future Finding Model adapter.
141
+ */
142
+ export declare function computeSecurityReviewCounters(contracts: readonly ContractModelContract[], expiringWithinDays: number, now: Date, undocumentedContractCount: number, undocumentedVariableCount: number): SecurityReviewCounters;
143
+ /**
144
+ * Renders the full docs artifact. It opens with a header, change summary and
145
+ * table of contents. Then come the catalog, ownership matrix (if used),
146
+ * dependency graph, lifecycle report and security review.
147
+ *
148
+ * @remarks
149
+ * Documents everything discovered, active or not, same scope as the catalog always
150
+ * had. Fully regenerated every run: unlike `.env.example`, nothing here is
151
+ * meant to be hand-edited, so there's no "never overwrite" behavior.
152
+ *
153
+ * `contracts` is `ContractModel`'s own shape, so `file` is already
154
+ * root-relative and POSIX-separated (ADR 0038). There is no separate `root`
155
+ * parameter to resolve against.
156
+ */
157
+ export declare function renderDocs(contracts: readonly ContractModelContract[], options: RenderDocsOptions): string;
158
+ /**
159
+ * Normalizes every wall-clock-relative substring `renderDocs()` can produce,
160
+ * so two renders of the *same* input on different days compare equal. That
161
+ * covers the `_Generated ..._` timestamp line, the lifecycle report's
162
+ * `(**Xd remaining**)`/`(**expired Xd ago**)` annotations, and the security
163
+ * review's "Already expired"/"Expiring within N days" counts.
164
+ * `check-artifacts.ts`'s drift comparison and the examples golden-file test
165
+ * harness (`test/support/example-runner.ts`) both need all of it. A contract
166
+ * with a near-term `expiresAt` renders day-relative text. Without this,
167
+ * `--check` (or a golden-file comparison) would report false drift only
168
+ * because real time passed between generation and comparison.
169
+ */
170
+ export declare function normalizeDocsForComparison(content: string): string;
171
+ export {};
172
+ //# sourceMappingURL=docs.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/build/docs.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,85 @@
1
+ import type { DiscoveredContract } from "./link.js";
2
+ import type { BuildFileSystem } from "./types.js";
3
+ /**
4
+ * Controls what happens when a `.env.example` already exists at the target
5
+ * location. `"keep-sibling"` (default): never touch the existing file;
6
+ * write a timestamped sibling instead, for the developer to diff/merge
7
+ * manually. `"overwrite"`: replace the existing file with freshly rendered
8
+ * content directly. `"skip"`: write nothing at all.
9
+ */
10
+ export type EnvExampleOnExisting = "keep-sibling" | "overwrite" | "skip";
11
+ /** The result of a completed {@link writeEnvExample} call. */
12
+ export interface EnvExampleResult {
13
+ /**
14
+ * Where the example file actually got written. `undefined` only when
15
+ * `onExisting: "skip"` left an existing file untouched and nothing was
16
+ * written.
17
+ */
18
+ readonly writtenPath: string | undefined;
19
+ /**
20
+ * Set when a file already existed at the requested location and was left
21
+ * untouched: with the default `"keep-sibling"`, `writtenPath` is a fresh
22
+ * timestamped sibling instead; with `"skip"`, this is the only outcome and
23
+ * `writtenPath` is `undefined`. Always `undefined` with `"overwrite"`.
24
+ */
25
+ readonly skippedExistingPath: string | undefined;
26
+ /** Variable names (live or already commented-out) in an existing example file that no discovered contract declares anymore. */
27
+ readonly staleVariables: readonly string[];
28
+ /** Variables live in an existing example file whose feature is no longer active, and that no other active feature still needs: safe to comment out. */
29
+ readonly variablesToComment: readonly string[];
30
+ /** Variables the current (active) configuration requires that aren't yet a live entry in an existing example file. */
31
+ readonly variablesToAdd: readonly string[];
32
+ }
33
+ /** The result of {@link computeReconciliation}: an existing `.env.example` diffed against the current configuration. */
34
+ export interface Reconciliation {
35
+ /** Variable names (live or already commented-out) in an existing example file that no discovered contract declares anymore. */
36
+ readonly staleVariables: readonly string[];
37
+ /** Variables live in an existing example file whose feature is no longer active, and that no other active feature still needs: safe to comment out. */
38
+ readonly variablesToComment: readonly string[];
39
+ /** Variables the current (active) configuration requires that aren't yet a live entry in an existing example file. */
40
+ readonly variablesToAdd: readonly string[];
41
+ }
42
+ /**
43
+ * Renders a deterministic `.env.example`-style file scoped to the *current*
44
+ * configuration. It lists every unique variable the active contracts
45
+ * require, one live entry per key, alphabetically. A key declared by more
46
+ * than one active contract renders once live; the rest are commented out
47
+ * with a pointer. Variables unique to disabled contracts follow, commented
48
+ * out for visibility. A key already required by an active contract is not
49
+ * unique and never repeated there. `reconciliationHeader`, when non-empty, is
50
+ * spliced in right after the banner (see `computeReconciliation`).
51
+ */
52
+ export declare function renderEnvExample(contracts: readonly DiscoveredContract[], reconciliationHeader?: readonly string[]): string;
53
+ /** Parses `KEY=value` lines out of an existing `.env`-style file, ignoring comments and blank lines. */
54
+ export declare function extractDeclaredVariables(source: string): string[];
55
+ /** Parses `# KEY=value` lines out of an existing `.env`-style file: variables it already knows about but has turned off. */
56
+ export declare function extractCommentedVariables(source: string): string[];
57
+ /**
58
+ * Diffs an existing `.env.example` against the current configuration into
59
+ * three actionable sets. Pure and filesystem-independent: `writeEnvExample`
60
+ * is the only caller that reads the file itself.
61
+ */
62
+ export declare function computeReconciliation(contracts: readonly DiscoveredContract[], existingContent: string): Reconciliation;
63
+ /**
64
+ * Writes a rendered `.env.example` to `location`. Behavior when a file
65
+ * already exists there is governed by `options.onExisting` (default
66
+ * `"keep-sibling"`, see `EnvExampleOnExisting`):
67
+ * - `"keep-sibling"`: the existing file is left alone; freshly generated
68
+ * content is written to a timestamped sibling instead
69
+ * (`<location>.<epoch-ms>`), prefixed with a reconciliation header
70
+ * comparing it against the existing file (omitted when there's nothing
71
+ * to report).
72
+ * - `"overwrite"`: the existing file is replaced directly with freshly
73
+ * rendered content; no reconciliation header (the changes it would
74
+ * describe are already applied).
75
+ * - `"skip"`: nothing is written.
76
+ * When no file exists yet at `location`, all three modes behave the same:
77
+ * write fresh content, nothing to reconcile against. `staleVariables`/
78
+ * `variablesToComment`/`variablesToAdd` are always computed and returned
79
+ * when a prior file existed, even under `"overwrite"`/`"skip"`, as a
80
+ * diagnostic: independent of whether anything was actually written.
81
+ */
82
+ export declare function writeEnvExample(contracts: readonly DiscoveredContract[], location: string, fs: BuildFileSystem, options?: {
83
+ onExisting?: EnvExampleOnExisting;
84
+ }): Promise<EnvExampleResult>;
85
+ //# sourceMappingURL=env-example.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"env-example.d.ts","sourceRoot":"","sources":["../../../src/build/env-example.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGjD;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,WAAW,GAAG,MAAM,CAAA;AAExE,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,+HAA+H;IAC/H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,uJAAuJ;IACvJ,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAED,wHAAwH;AACxH,MAAM,WAAW,cAAc;IAC7B,+HAA+H;IAC/H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,uJAAuJ;IACvJ,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAuED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,oBAAoB,GAAE,SAAS,MAAM,EAAO,GAC3C,MAAM,CAiDR;AAED,wGAAwG;AACxG,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAQjE;AAED,4HAA4H;AAC5H,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAQlE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,eAAe,EAAE,MAAM,GACtB,cAAc,CAkBhB;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,eAAe,EACnB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,oBAAoB,CAAA;CAAO,GAClD,OAAO,CAAC,gBAAgB,CAAC,CA6D3B"}