@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,176 @@
1
+ import type { ContractModelContract } from "./contract-model.js";
2
+ import type { CatalogContract, ExpiringEntry } from "./docs.js";
3
+ import type { EnvExampleOnExisting, EnvExampleResult } from "./env-example.js";
4
+ import type { DiscoveredContract, DiscoveredContractSummary, LinkResult } from "./link.js";
5
+ import type { LiveExpirationDates } from "./live-expirations.js";
6
+ import type { ParseWarning } from "./parse.js";
7
+ import type { BuildFileSystem } from "./types.js";
8
+ /** Options for {@link generateDocumentation}. */
9
+ export interface GenerateDocumentationOptions {
10
+ /** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
11
+ fs: BuildFileSystem;
12
+ /** Project root schema discovery is relative to. Defaults to `process.cwd()`. */
13
+ root?: string | undefined;
14
+ /** Output path for the Markdown docs artifact, relative to `root`. */
15
+ location: string;
16
+ /** Glob patterns for files to scan. Defaults to `defaultInclude()`. */
17
+ include?: string[] | undefined;
18
+ /** Glob patterns for files/directories to prune. Defaults to `defaultExclude()`. */
19
+ exclude?: string[] | undefined;
20
+ /** See `GenerateEnvManifestOptions.packages`; see ADR 0014. */
21
+ packages?: readonly string[] | undefined;
22
+ /** See `GenerateEnvManifestOptions.tsconfig`; see ADR 0023. */
23
+ tsconfig?: string | false | undefined;
24
+ /** How many days out counts as "expiring soon". Defaults to 30. */
25
+ expiringWithinDays?: number | undefined;
26
+ /**
27
+ * Also emit a `.env.example`-style file, relative to `root`. `onExisting`
28
+ * controls what happens when a file already exists there: defaults to
29
+ * `"keep-sibling"` (never overwrites; see `EnvExampleOnExisting` and
30
+ * `EnvExampleResult`).
31
+ */
32
+ envExample?: {
33
+ /** Output path for the `.env.example`-style file, relative to `root`. */
34
+ location: string;
35
+ /** What to do when a file already exists at `location`. Defaults to `"keep-sibling"`. */
36
+ onExisting?: EnvExampleOnExisting | undefined;
37
+ } | undefined;
38
+ /**
39
+ * Supplies expiration metadata from a live source as a post-discovery
40
+ * override, invoked exactly once with every discovered variable name after
41
+ * linking completes and before rendering. See `live-expirations.ts` and
42
+ * ADR 0012. Omitted: behavior is unchanged from a purely static `expiresAt`.
43
+ */
44
+ liveExpirationDates?: LiveExpirationDates | undefined;
45
+ }
46
+ /** Everything {@link generateDocumentation} found that isn't fully documented or up to date: never blocks generation; a team that wants to gate CI on this reads `Finding[]` (the "documentation" family) from the persisted evidence artifact and decides for itself. See ADR 0038. */
47
+ export interface DocumentationFindings {
48
+ /** Contracts with no linked `documentEnv()` call at all. */
49
+ readonly undocumentedContracts: readonly {
50
+ /** Absolute path of the file declaring the contract. */
51
+ readonly file: string;
52
+ /** The contract's exported binding name. */
53
+ readonly exportName: string;
54
+ }[];
55
+ /** Schema variables with no matching entry in their contract's linked documentation. */
56
+ readonly undocumentedVariables: readonly {
57
+ /** Absolute path of the file declaring the contract. */
58
+ readonly file: string;
59
+ /** The contract's exported binding name. */
60
+ readonly exportName: string;
61
+ /** The undocumented environment variable name. */
62
+ readonly key: string;
63
+ }[];
64
+ /** Documented variable entries with no matching schema variable (the schema key was removed or renamed). */
65
+ readonly staleDocEntries: readonly {
66
+ /** Absolute path of the file declaring the contract. */
67
+ readonly file: string;
68
+ /** The contract's exported binding name. */
69
+ readonly exportName: string;
70
+ /** The stale documented variable name. */
71
+ readonly key: string;
72
+ }[];
73
+ /** Variables whose `expiresAt` falls within the configured window. */
74
+ readonly expiringSoon: readonly ExpiringEntry[];
75
+ /** Contract- or variable-level `sensitivity` values outside {@link STANDARD_SENSITIVITY_LEVELS}. Advisory only: the declared level is always honored verbatim; this exists purely so vocabulary drift across a repo stays visible. */
76
+ readonly nonstandardSensitivityLevels: readonly NonstandardSensitivityEntry[];
77
+ /** `documentEnv()` calls that couldn't be statically linked to a schema. */
78
+ readonly unresolvedLinks: readonly {
79
+ /** Absolute path of the file containing the unlinkable call. */
80
+ readonly file: string;
81
+ /** Human-readable explanation of why the link couldn't be resolved. */
82
+ readonly reason: string;
83
+ }[];
84
+ }
85
+ /** The result of a completed {@link generateDocumentation} run. */
86
+ export interface GenerateDocumentationResult {
87
+ /** Absolute path the Markdown docs artifact was written to. */
88
+ readonly docsPath: string;
89
+ /** Set only when `options.envExample` was passed. */
90
+ readonly envExample: EnvExampleResult | undefined;
91
+ /** Root-relative summary of every discovered contract, active or not. */
92
+ readonly contracts: readonly DiscoveredContractSummary[];
93
+ /** Same descriptive content as the generated Markdown Catalog, reshaped for
94
+ * programmatic consumers: see `buildCatalog()` in `docs.ts`. */
95
+ readonly catalog: readonly CatalogContract[];
96
+ /** Parse-time warnings collected across every analyzed file (including allow-listed package resolution). */
97
+ readonly parseWarnings: readonly ParseWarning[];
98
+ /** Everything found that isn't fully documented or up to date. */
99
+ readonly documentation: DocumentationFindings;
100
+ }
101
+ /** Default value for {@link GenerateDocumentationOptions.expiringWithinDays}. */
102
+ export declare const DEFAULT_EXPIRING_WITHIN_DAYS = 30;
103
+ /**
104
+ * The sensitivity vocabulary env-cap's own docs, examples, and `.env.example`
105
+ * comments are written around. Purely advisory: `sensitivity` is an open
106
+ * `string` (see {@link runtime.VariableDocs.sensitivity}), any value is
107
+ * honored verbatim, and nothing here ever drops or rewrites a declared level.
108
+ * A level outside this set only produces a non-blocking
109
+ * `NONSTANDARD_SENSITIVITY_LEVEL` finding. A team that deliberately runs its
110
+ * own vocabulary sees one advisory line rather than silent data loss. A team
111
+ * that meant to write `"secret"` and typo'd `"secrets"` finds out.
112
+ */
113
+ export declare const STANDARD_SENSITIVITY_LEVELS: ReadonlySet<string>;
114
+ /** One contract- or variable-level `sensitivity` declaring a level outside {@link STANDARD_SENSITIVITY_LEVELS}. */
115
+ export interface NonstandardSensitivityEntry {
116
+ /** Absolute path of the file declaring the contract. */
117
+ readonly file: string;
118
+ /** The contract's exported binding name. */
119
+ readonly exportName: string;
120
+ /** `undefined` for a contract-level `sensitivity`, set for a per-variable one. */
121
+ readonly key: string | undefined;
122
+ /** The declared level, exactly as written. */
123
+ readonly sensitivity: string;
124
+ }
125
+ /**
126
+ * Every contract- or variable-level `sensitivity` outside the standard set,
127
+ * in declaration order (contract first, then its own variables by key).
128
+ *
129
+ * @remarks
130
+ * A variable's *own* declared level only: never the contract-inherited one
131
+ * `effectiveSensitivity()` would resolve to. Reporting the inherited value
132
+ * would fire this same finding once per variable on a contract that already
133
+ * produced its own contract-level entry, turning one real vocabulary
134
+ * question into N duplicates of it.
135
+ */
136
+ export declare function findNonstandardSensitivityLevels(contracts: readonly DiscoveredContract[]): NonstandardSensitivityEntry[];
137
+ export interface DocumentationComputation {
138
+ readonly contractSummaries: readonly DiscoveredContractSummary[];
139
+ readonly catalog: readonly CatalogContract[];
140
+ readonly documentation: DocumentationFindings;
141
+ /** `ContractModel`'s own projection of the same contracts, built once here and reused by `writeDocumentation()`: the shape `renderDocs()` itself takes (ADR 0038). */
142
+ readonly contractModelContracts: readonly ContractModelContract[];
143
+ }
144
+ /** Root-relative, POSIX-separated: `RenderDocsOptions`'s own convention, matching `ContractModel`'s `file`. Exported so `check-artifacts.ts`'s drift check can convert the same `documentation.undocumentedContracts`/`undocumentedVariables` fields for its own `renderDocs()` call, identically. Delegates to `displayPath()` so this can never disagree with the `ContractModel` `file` values it's matched against by identity. */
145
+ export declare function relativizeRef<T extends {
146
+ file: string;
147
+ }>(root: string, ref: T): T;
148
+ /**
149
+ * Pure: no I/O. Computes undocumented/stale/expiring findings against an
150
+ * already-discovered contract graph (active and inactive alike: docs
151
+ * document everything, unlike the manifest). Never blocks: see
152
+ * `DocumentationFindings`'s own doc comment. Shared by the standalone
153
+ * `generateDocumentation()` and `generate-env-artifacts.ts` (which also
154
+ * reuses this same call for Finding Model's documentation-family findings,
155
+ * ADR 0038: one computation, not two).
156
+ */
157
+ export declare function computeDocumentation(root: string, linkResult: LinkResult, expiringWithinDays: number, generatedAt: Date): DocumentationComputation;
158
+ /** Writes the docs artifact and, if requested, the `.env.example` file. Callers must have already confirmed both output paths are safe and nothing is blocking. */
159
+ export declare function writeDocumentation(docsPath: string, envExamplePath: string | undefined, root: string, contracts: readonly DiscoveredContract[], contractModelContracts: readonly ContractModelContract[], documentation: DocumentationFindings, expiringWithinDays: number, generatedAt: Date, fs: BuildFileSystem, envExampleOnExisting?: EnvExampleOnExisting): Promise<{
160
+ envExample: EnvExampleResult | undefined;
161
+ }>;
162
+ /**
163
+ * Build-time only. Discovers and links `env.schema.ts` files (same static
164
+ * analysis as {@link generateEnvManifest}) and writes the rich Markdown
165
+ * "Catalog": every variable, its description, default, processor/validator
166
+ * flags, owner, and expiry. Application developers use it as the single
167
+ * onboarding reference for what configuration a feature needs and how to set
168
+ * it up. Optionally also writes a reconciling `.env.example`.
169
+ *
170
+ * @remarks
171
+ * Documents every discovered contract, active or not, unlike {@link generateEnvManifest}.
172
+ *
173
+ * @throws {EnvDocumentationGenerationError} If `location`/`envExample.location` escape `root`.
174
+ */
175
+ export declare function generateDocumentation(options: GenerateDocumentationOptions): Promise<GenerateDocumentationResult>;
176
+ //# sourceMappingURL=generate-documentation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"generate-documentation.d.ts","sourceRoot":"","sources":["../../../src/build/generate-documentation.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,191 @@
1
+ import type { CompatibilityIssue } from "./compatibility.js";
2
+ import type { EvidenceModel } from "./evidence-model.js";
3
+ import type { Finding, FindingFamily } from "./finding-model.js";
4
+ import type { DocumentationComputation, GenerateDocumentationOptions, GenerateDocumentationResult } from "./generate-documentation.js";
5
+ import type { GenerateEnvManifestOptions, GenerateEnvManifestResult, ManifestComputation } from "./generate-manifest.js";
6
+ import type { GenerateUsageReportOptions, GenerateUsageReportResult, UsageComputation } from "./generate-usage.js";
7
+ import type { DiscoveredContract } from "./link.js";
8
+ import type { LiveExpirationDates } from "./live-expirations.js";
9
+ import type { ParseWarning } from "./parse.js";
10
+ import type { BuildFileSystem } from "./types.js";
11
+ /** Options for {@link generateEnvArtifacts}. */
12
+ export interface GenerateEnvArtifactsOptions {
13
+ /** The filesystem capability, shared across every requested pass: `./build` never imports `node:fs` (ADR 0040). */
14
+ fs: BuildFileSystem;
15
+ /** Directory glob patterns are resolved against, shared across every requested pass. Defaults to `process.cwd()`. */
16
+ root?: string | undefined;
17
+ /** Shared schema-discovery glob for the contract graph. Defaults to `["**\/env.schema.ts"]`. */
18
+ include?: string[] | undefined;
19
+ /** Glob patterns to exclude, shared across every requested pass. Defaults to node_modules/dist/.git. */
20
+ exclude?: string[] | undefined;
21
+ /** See `GenerateEnvManifestOptions.packages`; shared across every requested pass. See ADR 0014. */
22
+ packages?: readonly string[] | undefined;
23
+ /** See `GenerateEnvManifestOptions.tsconfig`; shared across every requested pass. See ADR 0023. */
24
+ tsconfig?: string | false | undefined;
25
+ /** Manifest pass options, or `false` to skip it entirely. */
26
+ manifest?: Omit<GenerateEnvManifestOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig"> | false | undefined;
27
+ /** Docs pass options, or `false` to skip it entirely. */
28
+ docs?: Omit<GenerateDocumentationOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig" | "liveExpirationDates"> | false | undefined;
29
+ /** Usage-report pass options, or `false` to skip it entirely. */
30
+ usage?: Omit<GenerateUsageReportOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig"> | false | undefined;
31
+ /**
32
+ * Where to write the persisted evidence artifact (the full, literal
33
+ * `EvidenceModel`, plus a paired `.fingerprint` sidecar: see
34
+ * `evidence-cache.ts`), e.g. `docs/env.evidence.json`, relative to `root`.
35
+ * Independent of `manifest.location`: requesting this needs no other
36
+ * pass, and generating a manifest never requires it. `EvidenceModel`
37
+ * itself is always computed (ADR 0038, "free to compute, always real") and
38
+ * always returned as `result.evidence`. This option controls only whether
39
+ * it's also written to disk. Omitted: nothing is written, and
40
+ * `result.evidence` is still populated.
41
+ */
42
+ evidence?: {
43
+ location: string;
44
+ } | false | undefined;
45
+ /**
46
+ * Escalates every warning-severity `"documentation"`-family finding
47
+ * (undocumented contracts/variables, stale doc entries, expiring/expired
48
+ * entries, unresolvable `documentEnv()` links) into a blocking error. A
49
+ * run with any of them then writes nothing and throws. Defaults to
50
+ * `"warn"`: per ADR 0038, documentation gaps never block by default.
51
+ *
52
+ * @remarks
53
+ * Scoped deliberately narrowly, unlike `manifest.onIncompatibility`, which
54
+ * gates only the compatibility family. `"info"`-severity findings are never
55
+ * escalated by either: see `Finding.severity`.
56
+ */
57
+ onUndocumented?: "warn" | "throw" | undefined;
58
+ /**
59
+ * Escalates every warning-severity `"ownership"`-family finding (abandoned
60
+ * contracts, unresolved consumers, unconsumed owned variables,
61
+ * indeterminate ownership, stale/missing `dynamicAccess` citations) into a
62
+ * blocking error. Defaults to `"warn"`: see {@link onUndocumented}.
63
+ */
64
+ onOwnershipIssue?: "warn" | "throw" | undefined;
65
+ /**
66
+ * Supplies expiration metadata from a live source (a secrets manager, an
67
+ * internal inventory API, ...) as a post-discovery override applied only to
68
+ * the docs pass. Invoked at most once, only when a `docs` pass is actually
69
+ * requested, with every discovered variable name across all passes' shared
70
+ * contract graph. See `live-expirations.ts` and ADR 0012. Omitted: behavior
71
+ * is unchanged from a purely static `expiresAt`.
72
+ */
73
+ liveExpirationDates?: LiveExpirationDates | undefined;
74
+ }
75
+ /** The result of a completed {@link generateEnvArtifacts} run. */
76
+ export interface GenerateEnvArtifactsResult {
77
+ /** Set only when `options.manifest` wasn't `false`. */
78
+ readonly manifest: GenerateEnvManifestResult | undefined;
79
+ /** Set only when `options.docs` wasn't `false`. */
80
+ readonly docs: GenerateDocumentationResult | undefined;
81
+ /** Set only when `options.usage` wasn't `false`. */
82
+ readonly usage: GenerateUsageReportResult | undefined;
83
+ /** Always populated, regardless of `options.evidence`: see that option's own doc comment. */
84
+ readonly evidence: EvidenceModel;
85
+ }
86
+ /**
87
+ * Every intermediate value both the write path (`generateEnvArtifacts()`
88
+ * below) and the drift-check path (`checkEnvArtifacts()` in
89
+ * `check-artifacts.ts`) need, computed exactly once. Internal/Private tier
90
+ * per `VERSIONING.md`: not re-exported from `./index.ts`.
91
+ */
92
+ export interface ComputeArtifactsResult {
93
+ readonly root: string;
94
+ /** Set only when a manifest pass was requested. */
95
+ readonly manifest: {
96
+ readonly options: Omit<GenerateEnvManifestOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig">;
97
+ readonly outputPath: string;
98
+ readonly computed: ManifestComputation;
99
+ } | undefined;
100
+ /** Set only when a docs pass was requested; `envExamplePath` only when it also asked for an example file. */
101
+ readonly docs: {
102
+ readonly options: Omit<GenerateDocumentationOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig" | "liveExpirationDates">;
103
+ readonly path: string;
104
+ readonly envExamplePath: string | undefined;
105
+ } | undefined;
106
+ /** Always computed: Finding Model needs it regardless of whether a `docs` pass was itself requested. See ADR 0038. */
107
+ readonly docsComputed: DocumentationComputation;
108
+ readonly docsContracts: readonly DiscoveredContract[];
109
+ /** Set only when a usage pass was requested; `reportPath` only when it also asked for a report file. */
110
+ readonly usage: {
111
+ readonly options: Omit<GenerateUsageReportOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig">;
112
+ readonly reportPath: string | undefined;
113
+ } | undefined;
114
+ /** Always computed: Finding Model needs it regardless of whether a `usage` pass was itself requested. See ADR 0038. */
115
+ readonly usageComputed: UsageComputation;
116
+ readonly evidencePath: string | undefined;
117
+ readonly evidence: EvidenceModel;
118
+ readonly blocking: readonly CompatibilityIssue[];
119
+ readonly packageWarnings: readonly ParseWarning[];
120
+ readonly linkWarnings: readonly ParseWarning[];
121
+ /** Single timestamp shared by every pass' own time-sensitive computation (`expiringSoon`, `EvidenceModel.provenance.generatedAt`), so all of them agree on exactly the same instant. */
122
+ readonly generatedAt: Date;
123
+ }
124
+ /**
125
+ * Adapts every warning-severity finding of one family into the
126
+ * `CompatibilityIssue` shape `blocking`/`EnvProjectGenerationError` speak.
127
+ * So `--strict-docs`/`--strict-ownership` fail through the same path as
128
+ * `--strict`, with no second failure mode.
129
+ *
130
+ * @remarks
131
+ * `"info"` findings are filtered out unconditionally and can never be
132
+ * escalated by any flag: they're observations, not gaps (see
133
+ * `Finding.severity`). `"error"` findings are excluded too. They already
134
+ * block on their own, via the manifest pass. Re-adding them here would
135
+ * report the same violation twice in one error message. `code` is left unset:
136
+ * `CompatibilityIssueCode` is that check family's own closed vocabulary,
137
+ * and a `FindingCode` from another family is not a member of it.
138
+ */
139
+ /** @internal Exported for direct unit coverage: reached through `generateEnvArtifacts()`'s `--strict-docs`/`--strict-ownership` flags in production, but its filter/mapping logic isn't independently observable through that path alone (every mutant on it still needs a real `computeArtifacts()` call, discovery included, to reach it). */
140
+ export declare function escalatedFindings(findings: readonly Finding[], family: FindingFamily): CompatibilityIssue[];
141
+ /** The variable a finding is about, or a `"(contract) <name>"` label when it's contract-level: matching `CompatibilityIssue.variable`'s own documented convention.
142
+ * @internal Exported for direct unit coverage: see {@link escalatedFindings}'s own doc comment for why. */
143
+ export declare function findingSubject(finding: Finding): string;
144
+ /** Every file a finding names, as `CompatibilityIssue.files`: empty when its location carries none (an ownership finding about a variable, which names no single file).
145
+ * @internal Exported for direct unit coverage: see {@link escalatedFindings}'s own doc comment for why. */
146
+ export declare function findingFiles(finding: Finding): string[];
147
+ /**
148
+ * A pass's options, or `undefined` when the pass is not requested: `false` skips a pass entirely,
149
+ * exactly as omitting it does.
150
+ * @internal Exported for direct unit coverage.
151
+ */
152
+ export declare function requestedPass<T extends object>(option: T | false | undefined): T | undefined;
153
+ /**
154
+ * Runs schema discovery, linking, and every requested pass's pure `compute*()`
155
+ * step: but never writes anything to disk. Throws `EnvProjectGenerationError`
156
+ * immediately if any requested output location escapes `root`, the same
157
+ * fail-fast-before-any-work guarantee `generateEnvArtifacts()` gives.
158
+ * Otherwise returns every intermediate value without checking `blocking`
159
+ * findings. Each caller (the write path below, and `--check`'s
160
+ * `checkEnvArtifacts()`) decides when to throw on those.
161
+ *
162
+ * @remarks
163
+ * The six canonical fact models (Contract/Dependency/Ownership/Lifecycle/
164
+ * Finding/Change -> `EvidenceModel`) are composed on every call,
165
+ * unconditionally. They reuse the builders `generateEvidenceModel()` calls,
166
+ * so there is no second implementation of the same assembly. See ADR 0038.
167
+ */
168
+ export declare function computeArtifacts(options: GenerateEnvArtifactsOptions): Promise<ComputeArtifactsResult>;
169
+ /**
170
+ * Orchestrates {@link generateEnvManifest}/{@link generateDocumentation}/
171
+ * {@link generateUsageReport}, plus the persisted evidence artifact. It
172
+ * composes their shared private compute/write pipeline directly. Schema
173
+ * discovery+linking runs exactly once, however many outputs are requested.
174
+ * It is an orchestrator, not a new analysis engine (see ADR 0011).
175
+ *
176
+ * @remarks
177
+ * Two distinct atomicity guarantees, not one:
178
+ * - **Compute atomicity (guaranteed)**: every requested pass's blocking
179
+ * findings are checked, across all passes, before any pass writes
180
+ * anything.
181
+ * - **Write atomicity (NOT guaranteed, and not attempted)**: once writes
182
+ * begin, each `fs.writeFile` is independent. A real I/O failure partway
183
+ * through (disk full, permissions changed mid-run) can leave some
184
+ * artifacts on disk and not others. Transactional (temp-file + rename)
185
+ * writes across all three artifacts are not used. They would be
186
+ * disproportionate machinery for a rare failure mode: see ADR 0011.
187
+ *
188
+ * @throws {EnvProjectGenerationError} If any requested output location escapes `root`, or if any requested pass reports a blocking finding.
189
+ */
190
+ export declare function generateEnvArtifacts(options: GenerateEnvArtifactsOptions): Promise<GenerateEnvArtifactsResult>;
191
+ //# sourceMappingURL=generate-env-artifacts.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"generate-env-artifacts.d.ts","sourceRoot":"","sources":["../../../src/build/generate-env-artifacts.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,77 @@
1
+ import type { EvidenceModel } from "./evidence-model.js";
2
+ import type { LiveExpirationDates } from "./live-expirations.js";
3
+ import type { BuildFileSystem } from "./types.js";
4
+ /** Options for {@link generateEvidenceModel}. */
5
+ export interface GenerateEvidenceModelOptions {
6
+ /** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
7
+ fs: BuildFileSystem;
8
+ /** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
9
+ root?: string | undefined;
10
+ /** Schema-discovery glob for the contract graph. Defaults to `["**\/env.schema.ts"]`. */
11
+ include?: string[] | undefined;
12
+ /** Glob patterns to exclude, shared across every pass. Defaults to node_modules/dist/.git. */
13
+ exclude?: string[] | undefined;
14
+ /** See `GenerateEnvManifestOptions.packages`. See ADR 0014. */
15
+ packages?: readonly string[] | undefined;
16
+ /** See `GenerateEnvManifestOptions.tsconfig`. See ADR 0023. */
17
+ tsconfig?: string | false | undefined;
18
+ /**
19
+ * Where a previously-persisted evidence artifact lives, relative to
20
+ * `root`: read (never written) as the baseline Change Model diffs
21
+ * against and dynamic-access citation freshness (ADR 0037) compares
22
+ * content hashes to. Independent of any `.ts` manifest a project may or
23
+ * may not also generate: there is no derivation from a manifest's own
24
+ * location. Omitted: treated as the normal first-run state (everything
25
+ * reads as added, no citation-freshness baseline to compare against),
26
+ * never an error.
27
+ */
28
+ previousSnapshotLocation?: string | undefined;
29
+ /** Feeds Lifecycle Model's `expiring` list. Defaults to 30. */
30
+ expiringWithinDays?: number | undefined;
31
+ /**
32
+ * Supplies expiration metadata from a live source as a post-discovery
33
+ * override, applied to Lifecycle Model's (and Finding Model's
34
+ * `expiring-soon` findings') data only: Contract Model still reflects the
35
+ * schema's own static `expiresAt`. See `live-expirations.ts` and ADR 0012.
36
+ */
37
+ liveExpirationDates?: LiveExpirationDates | undefined;
38
+ /**
39
+ * Resolves the commit SHA to stamp onto `EvidenceModel.provenance.commit`.
40
+ * Invoked at most once, after discovery/linking completes. env-cap never
41
+ * shells out to `git` itself: see ADR 0012's callback precedent. Omitted:
42
+ * `commit` is `undefined`.
43
+ */
44
+ commit?: (() => Promise<string | undefined>) | undefined;
45
+ }
46
+ /**
47
+ * Node-only assembly orchestrator (ADR 0024, ADR 0031). It runs schema
48
+ * discovery and linking once (via `assembleProject()`, shared with
49
+ * `computeArtifacts()`). It then builds all seven canonical fact models by
50
+ * calling each model's own public builder directly. This function adds no
51
+ * derivation logic of its own, only sequencing and the shared
52
+ * discovery/linking every builder needs. The result is `deepFreeze()`-d
53
+ * before being returned.
54
+ *
55
+ * @remarks
56
+ * Deliberately never throws on a data-quality finding (a compatibility
57
+ * issue, an undocumented variable, an abandoned contract, ...): every one
58
+ * of those becomes a `Finding` in the returned model's `finding` field
59
+ * instead. This differs from `generateEnvManifest()`, which throws by
60
+ * default, because that is a "should I write this artifact" gate. Evidence
61
+ * Model assembly is a read-only snapshot. Its purpose is to represent such
62
+ * issues as data for a consumer's own projection to act on (see ADR 0024's
63
+ * mission statement). It still throws
64
+ * `EnvProjectGenerationError` for a genuine configuration error:
65
+ * `previousSnapshotLocation` escaping `root`.
66
+ *
67
+ * The dependency-graph scan underlying Dependency Model (via
68
+ * `buildDependencyModel()`) and the one underlying Finding Model's
69
+ * ownership-related findings (via `computeUsage()`) each run their own,
70
+ * independent pass over the repository. That cost is accepted: each half's
71
+ * already-tested public building block is called directly, rather than a
72
+ * second copy of either's logic being hand-derived here. Both are Node-only,
73
+ * dev/CI-time-only work (never a runtime hot path), so the redundant I/O is
74
+ * an honest tradeoff, not an oversight.
75
+ */
76
+ export declare function generateEvidenceModel(options: GenerateEvidenceModelOptions): Promise<EvidenceModel>;
77
+ //# sourceMappingURL=generate-evidence.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"generate-evidence.d.ts","sourceRoot":"","sources":["../../../src/build/generate-evidence.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAYxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,+EAA+E;IAC/E,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAA;IACrD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,aAAa,CAAC,CAyHxB"}
@@ -0,0 +1,100 @@
1
+ import type { BuildFileSystem } from "./types.js";
2
+ import type { CompatibilityIssue } from "./compatibility.js";
3
+ import { type DiscoveredContract, type DiscoveredContractSummary, type LinkResult } from "./link.js";
4
+ import type { ParseWarning } from "./parse.js";
5
+ /** Options for {@link generateEnvManifest}. */
6
+ export interface GenerateEnvManifestOptions {
7
+ /** The filesystem capability: `./build` never imports `node:fs` (ADR 0040). */
8
+ fs: BuildFileSystem;
9
+ /** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
10
+ root?: string | undefined;
11
+ /** Output path for the generated manifest, relative to `root` (e.g. "src/generated/env.manifest.ts"). */
12
+ location: string;
13
+ /** Glob patterns for schema files. Defaults to `["**\/env.schema.ts"]`. */
14
+ include?: string[] | undefined;
15
+ /** Glob patterns to exclude. Defaults to node_modules/dist/.git. */
16
+ exclude?: string[] | undefined;
17
+ /**
18
+ * Explicit allowlist of installed
19
+ * package names whose declared `"envCap": { "schema": "<path>" }` entry
20
+ * point should also be discovered, so a contract that ships as its own
21
+ * separately-published package (no monorepo required) can be included in
22
+ * the manifest. Opt-in only: a package is never considered unless its
23
+ * exact name appears here. See ADR 0014.
24
+ */
25
+ packages?: readonly string[] | undefined;
26
+ /**
27
+ * Path to a tsconfig.json (relative to `root`)
28
+ * whose `compilerOptions.paths`/`baseUrl` resolve aliased import specifiers (e.g.
29
+ * `"@/lib/env.schema.js"`) encountered during static analysis, so a contract or consumer
30
+ * reached only through an alias isn't misreported as abandoned/unresolved. Defaults to
31
+ * `"tsconfig.json"` at `root`: on automatically, no opt-in required, since (unlike
32
+ * `packages`) this never crosses a trust/versioning boundary: every resolved file is
33
+ * already local, already-trusted project source. Pass `false` to disable entirely. See
34
+ * ADR 0023.
35
+ */
36
+ tsconfig?: string | false | undefined;
37
+ /**
38
+ * "warn" (default): only provable incompatibilities (conflicting explicit processor
39
+ * return type annotations) block generation; everything else is reported as a warning.
40
+ * "throw": warnings are escalated to hard errors too, for stricter CI gates.
41
+ */
42
+ onIncompatibility?: "warn" | "throw" | undefined;
43
+ }
44
+ /** The result of a completed {@link generateEnvManifest} run. */
45
+ export interface GenerateEnvManifestResult {
46
+ /** Absolute path the manifest file was written to. */
47
+ readonly outputPath: string;
48
+ /** Root-relative summary of every discovered contract, active or not. */
49
+ readonly contracts: readonly DiscoveredContractSummary[];
50
+ /** Non-blocking compatibility/exclusive-group issues (severity `"warning"`). */
51
+ readonly warnings: readonly CompatibilityIssue[];
52
+ /** Parse-time warnings collected across every analyzed file (including allow-listed package resolution). */
53
+ readonly parseWarnings: readonly ParseWarning[];
54
+ }
55
+ /**
56
+ * Default value for {@link GenerateEnvManifestOptions.include}. A function
57
+ * (not a bare module-level `const`) so every call gets its own fresh array.
58
+ * A shared literal used from many files (`evidence-cache.ts`,
59
+ * `generate-documentation.ts`, `generate-evidence.ts`,
60
+ * `generate-env-artifacts.ts`, `generate-usage.ts`) attracts covered-static
61
+ * mutants under Stryker's `coverageAnalysis: perTest` + `ignoreStatic: true`.
62
+ * A mutant on module-load code that a test still references is run anyway
63
+ * and falsely reported "Survived".
64
+ */
65
+ export declare function defaultInclude(): string[];
66
+ /** Default value for {@link GenerateEnvManifestOptions.exclude}. Same reasoning as {@link defaultInclude}. */
67
+ export declare function defaultExclude(): string[];
68
+ export interface ManifestComputation {
69
+ readonly activeContracts: readonly DiscoveredContract[];
70
+ readonly contractSummaries: readonly DiscoveredContractSummary[];
71
+ readonly warnings: readonly CompatibilityIssue[];
72
+ readonly blocking: readonly CompatibilityIssue[];
73
+ }
74
+ /**
75
+ * Pure: no I/O. Runs compatibility (0005) and exclusive-group (0009,
76
+ * always-error, never gated by `onIncompatibility`) checks against an
77
+ * already-discovered contract graph and applies the `onIncompatibility` gate.
78
+ * Shared by the standalone `generateEnvManifest()` (which discovers its own
79
+ * graph) and `generate-env-artifacts.ts` (which discovers once and reuses it across
80
+ * manifest/docs/usage): see ADR 0011.
81
+ */
82
+ export declare function computeManifest(root: string, linkResult: LinkResult, onIncompatibility: "warn" | "throw" | undefined): ManifestComputation;
83
+ /** Writes the manifest file. Callers must have already confirmed `outputPath` is safe and nothing is blocking. */
84
+ export declare function writeManifest(outputPath: string, activeContracts: readonly DiscoveredContract[], fs: BuildFileSystem): Promise<void>;
85
+ /**
86
+ * Build-time only. Discovers `env.schema.ts` files, statically analyzes them
87
+ * (never executes them) to link `createEnv()`/`documentEnv()` calls, checks
88
+ * for provable incompatibilities between duplicate variable declarations,
89
+ * and writes a deterministic manifest file that re-exports every discovered
90
+ * active contract.
91
+ *
92
+ * @remarks
93
+ * Never call this at application startup or import it from
94
+ * runtime code: wire it into an npm script, a bundler plugin, or a CI
95
+ * step instead.
96
+ *
97
+ * @throws {EnvManifestGenerationError} If `location` escapes `root`, or if a blocking compatibility/exclusive-group issue is found.
98
+ */
99
+ export declare function generateEnvManifest(options: GenerateEnvManifestOptions): Promise<GenerateEnvManifestResult>;
100
+ //# sourceMappingURL=generate-manifest.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"generate-manifest.d.ts","sourceRoot":"","sources":["../../../src/build/generate-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAG5D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EAChB,MAAM,WAAW,CAAA;AAElB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yGAAyG;IACzG,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CACjD;AAED,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACxD,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,4GAA4G;IAC5G,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;CAChD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AACD,8GAA8G;AAC9G,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAczC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,eAAe,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACvD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAChE,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,iBAAiB,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAC9C,mBAAmB,CAwBrB;AAED,kHAAkH;AAClH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAoCpC"}