@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,222 @@
1
+ import type { DiscoveredSchemaVariable, DiscoveredVariableEvidence, ParseWarning } from "./parse.js";
2
+ import type { EnvGovernanceFields } from "./governance-fields.js";
3
+ import type { ImportResolutionContext } from "./resolution/resolve-import.js";
4
+ import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
5
+ import type { SourcePosition } from "./source-position.js";
6
+ /** One schema variable, merged with its linked `documentEnv()` documentation (if any). */
7
+ /**
8
+ * One schema variable merged with its linked `documentEnv()` documentation. Its
9
+ * governance fields (`owner` .. `metadata`) are `EnvGovernanceFields`:
10
+ * each an individual-variable override of the contract's own value, from the
11
+ * linked `documentEnv()` call's matching `variables` entry, or `undefined`.
12
+ */
13
+ export interface DiscoveredVariable extends DiscoveredSchemaVariable, EnvGovernanceFields {
14
+ /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
15
+ readonly description: string | undefined;
16
+ /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
17
+ readonly refreshInstructions: string | undefined;
18
+ /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
19
+ readonly authenticatorType: string | undefined;
20
+ /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
21
+ readonly rotationPeriod: string | undefined;
22
+ /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
23
+ readonly lastRotatedAt: string | undefined;
24
+ /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
25
+ readonly rotationTriggerEvents: readonly string[] | undefined;
26
+ /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
27
+ readonly setupInstructions: string | undefined;
28
+ /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
29
+ readonly required: boolean | undefined;
30
+ /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
31
+ readonly deprecated: boolean | undefined;
32
+ /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
33
+ readonly deprecatedReason: string | undefined;
34
+ /** From the linked `documentEnv()` call's matching `variables` entry, if any. */
35
+ readonly removeBy: string | undefined;
36
+ /** From the linked `documentEnv()` call's matching `variables` entry, if any. The previous variable name this one renames, if this declaration is the result of a rename. */
37
+ readonly renamedFrom: string | undefined;
38
+ /** The linked `documentEnv()` entry's `evidence` sub-object: the re-verified-every-run half of this variable's documentation, deliberately not flattened in alongside the declared-only fields above. See {@link runtime.VariableEvidenceDocs} and ADR 0037. */
39
+ readonly evidence: DiscoveredVariableEvidence | undefined;
40
+ /** Whether this specific key had a matching entry in the linked `documentEnv()` call, if any. */
41
+ readonly documented: boolean;
42
+ }
43
+ /** One `createEnv()` contract, merged with its linked `documentEnv()` documentation (if any). Its governance fields (`owner` .. `metadata`) are `EnvGovernanceFields`: contract-level defaults that individual variables may override. */
44
+ export interface DiscoveredContract extends EnvGovernanceFields {
45
+ /** Absolute path of the file declaring the `createEnv()` call. */
46
+ readonly file: string;
47
+ /** The binding name the `createEnv()` result is exported as. */
48
+ readonly exportName: string;
49
+ /** Resolved display name: linked `documentEnv()`'s `name`, else `createEnv()`'s own `name` option, else `exportName`. */
50
+ readonly contractName: string;
51
+ /** From the linked `documentEnv()`'s `active` option. Defaults to `true` when omitted or undocumented. */
52
+ readonly active: boolean;
53
+ /** From the linked `documentEnv()` call, if any. */
54
+ readonly category: string | undefined;
55
+ /** From the linked `documentEnv()` call, if any: see {@link runtime.ContractDocs.exclusiveGroup}. */
56
+ readonly exclusiveGroup: string | undefined;
57
+ /** From the linked `documentEnv()` call, if any. */
58
+ readonly deprecated: boolean | undefined;
59
+ /** From the linked `documentEnv()` call, if any. */
60
+ readonly deprecatedReason: string | undefined;
61
+ /** Every variable declared in the schema, merged with its linked documentation. */
62
+ readonly variables: readonly DiscoveredVariable[];
63
+ /** Whether *any* `documentEnv()` call is linked to this contract at all. */
64
+ readonly documented: boolean;
65
+ /** Set when this contract was discovered via an allow-listed package's
66
+ * declared schema entry point rather than local discovery. It is the bare
67
+ * package name `renderManifest()` imports from. A relative path to the
68
+ * (analysis-only) resolved file would be wrong. See ADR 0014. */
69
+ readonly packageOrigin: PackageOrigin | undefined;
70
+ /** Where this contract's `createEnv(...)` call is declared. Always present: every discovered contract has one, by definition. See ADR 0036. */
71
+ readonly declaration: SourcePosition;
72
+ /** Where this contract's `documentEnv(...)` call is declared, if one exists. Undefined for a contract that's never been documented. See ADR 0036. */
73
+ readonly documentation: SourcePosition | undefined;
74
+ }
75
+ /** A `documentEnv()` call that could not be statically linked back to a `createEnv()` schema. */
76
+ export interface UnresolvedLink {
77
+ /** Absolute path of the file containing the unlinkable call. */
78
+ readonly file: string;
79
+ /** Human-readable explanation of why the link couldn't be resolved. */
80
+ readonly reason: string;
81
+ }
82
+ /** The full result of {@link linkFiles}: every linked contract, plus every category of thing that didn't link cleanly. */
83
+ export interface LinkResult {
84
+ /** Every `createEnv()` contract found, merged with its documentation. */
85
+ readonly contracts: readonly DiscoveredContract[];
86
+ /** Parse-time warnings collected across every analyzed file. */
87
+ readonly warnings: readonly ParseWarning[];
88
+ /** `documentEnv()` calls that couldn't be statically linked to a schema. */
89
+ readonly unresolvedLinks: readonly UnresolvedLink[];
90
+ /** Contracts with no linked `documentEnv()` call at all. */
91
+ readonly undocumentedContracts: readonly {
92
+ /** Absolute path of the file declaring the contract. */
93
+ readonly file: string;
94
+ /** The contract's exported binding name. */
95
+ readonly exportName: string;
96
+ }[];
97
+ /** Schema variables with no matching entry in their contract's linked documentation. */
98
+ readonly undocumentedVariables: readonly {
99
+ /** Absolute path of the file declaring the contract. */
100
+ readonly file: string;
101
+ /** The contract's exported binding name. */
102
+ readonly exportName: string;
103
+ /** The undocumented environment variable name. */
104
+ readonly key: string;
105
+ }[];
106
+ /** Documented variable entries with no matching schema variable (the schema key was removed or renamed). */
107
+ readonly staleDocEntries: readonly {
108
+ /** Absolute path of the file declaring the contract. */
109
+ readonly file: string;
110
+ /** The contract's exported binding name. */
111
+ readonly exportName: string;
112
+ /** The stale documented variable name. */
113
+ readonly key: string;
114
+ }[];
115
+ }
116
+ /**
117
+ * Parses every discovered file, then resolves and links `createEnv`/
118
+ * `documentEnv` calls into the merged, docs-enriched contract shape. The
119
+ * rest of the generator consumes that shape (`compatibility.ts`,
120
+ * `exclusive-group.ts`, `manifest.ts`, `docs.ts`, `env-example.ts`).
121
+ *
122
+ * @remarks
123
+ * Cross-file linking is deliberately narrow (see `resolveImportSpecifier`).
124
+ * A `documentEnv()` call's schema reference resolves to one of three things.
125
+ * The first is a `const` in its own file. The second is a directly-imported
126
+ * named export of another file's `const`. The third is an allow-listed
127
+ * package's declared schema entry point (ADR 0014). Anything else becomes an `unresolvedLinks` entry, not a throw
128
+ * or a guess. Examples: a re-export barrel, a namespace import, an unlisted
129
+ * bare package specifier. Every other static-analysis boundary in this codebase
130
+ * does the same.
131
+ *
132
+ * `packageOrigins` (from `resolveAllowlistedPackages()`) tags any discovered
133
+ * contract whose `file` matches a package-resolved path with that package's
134
+ * origin. It is purely a lookup. `discoveredFiles` must already include
135
+ * those files (the caller merges them in via `mergeLocalAndPackageFiles()`).
136
+ *
137
+ * @param context - See `ImportResolutionContext`; drives how a resolved import specifier maps back to a file on disk.
138
+ */
139
+ export declare function linkFiles(discoveredFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, packageOrigins?: ReadonlyMap<string, PackageOrigin>): Promise<LinkResult>;
140
+ /** Root-relative projection of a {@link DiscoveredContract}, as returned by {@link generateEnvManifest}/{@link generateDocumentation}. */
141
+ export interface DiscoveredContractSummary {
142
+ /** Root-relative, POSIX-separated file path. */
143
+ readonly file: string;
144
+ /** The binding name the `createEnv()` result is exported as. */
145
+ readonly exportName: string;
146
+ /** Resolved display name (see {@link DiscoveredContract.contractName}). */
147
+ readonly contractName: string;
148
+ /** Number of variables declared in this contract's schema. */
149
+ readonly variableCount: number;
150
+ /** Whether this contract was included in the generated manifest (`active` defaults to true). */
151
+ readonly active: boolean;
152
+ /** Whether a `documentEnv()` call is linked to this contract. */
153
+ readonly documented: boolean;
154
+ }
155
+ /**
156
+ * Projects a {@link DiscoveredContract} (absolute `file`) into the root-relative
157
+ * summary shape returned by {@link generateEnvManifest}/{@link generateDocumentation}.
158
+ *
159
+ * @remarks
160
+ * Pulled out here, rather than duplicated in both, since it's a pure
161
+ * projection with no manifest- or docs-specific behavior.
162
+ */
163
+ export declare function summarizeContract(contract: DiscoveredContract, root: string): DiscoveredContractSummary;
164
+ /**
165
+ * A variable's owner, falling back to its contract's default when the
166
+ * variable itself doesn't set one.
167
+ *
168
+ * @remarks
169
+ * The one place this resolution rule should live: see ADR 0028. Every
170
+ * caller that needs "who owns this variable" must go through this, not
171
+ * `variable.owner` or `contract.owner` alone. Those callers are the docs
172
+ * Catalog, ownership matrix and security review, and the usage report's
173
+ * variable-level ownership findings (ADR 0028). One rule means two call
174
+ * sites can never disagree about who owns a variable.
175
+ *
176
+ * Structurally typed (not pinned to `DiscoveredContract`/`DiscoveredVariable`).
177
+ * So the same rule also serves `ContractModelContract`/`ContractModelVariable`
178
+ * (`contract-model.ts`). Both shapes carry the same field, and this rule must
179
+ * never have two independent implementations.
180
+ */
181
+ export declare function effectiveOwner(contract: {
182
+ readonly owner: string | undefined;
183
+ }, variable: {
184
+ readonly owner: string | undefined;
185
+ }): string | undefined;
186
+ /** A variable's sensitivity, falling back to its contract's default: see {@link effectiveOwner}. */
187
+ export declare function effectiveSensitivity(contract: {
188
+ readonly sensitivity: string | undefined;
189
+ }, variable: {
190
+ readonly sensitivity: string | undefined;
191
+ }): string | undefined;
192
+ /** A variable's purpose, falling back to its contract's default: see {@link effectiveOwner}. */
193
+ export declare function effectivePurpose(contract: {
194
+ readonly purpose: string | undefined;
195
+ }, variable: {
196
+ readonly purpose: string | undefined;
197
+ }): string | undefined;
198
+ /** A variable's legal basis, falling back to its contract's default: see {@link effectiveOwner}. */
199
+ export declare function effectiveLegalBasis(contract: {
200
+ readonly legalBasis: string | undefined;
201
+ }, variable: {
202
+ readonly legalBasis: string | undefined;
203
+ }): string | undefined;
204
+ /** A variable's retention policy, falling back to its contract's default: see {@link effectiveOwner}. */
205
+ export declare function effectiveRetention(contract: {
206
+ readonly retention: string | undefined;
207
+ }, variable: {
208
+ readonly retention: string | undefined;
209
+ }): string | undefined;
210
+ /** A variable's data residency, falling back to its contract's default: see {@link effectiveOwner}. */
211
+ export declare function effectiveDataResidency(contract: {
212
+ readonly dataResidency: string | readonly string[] | undefined;
213
+ }, variable: {
214
+ readonly dataResidency: string | readonly string[] | undefined;
215
+ }): string | readonly string[] | undefined;
216
+ /** A variable's audit-required assertion, falling back to its contract's default: see {@link effectiveOwner}. */
217
+ export declare function effectiveAuditRequired(contract: {
218
+ readonly auditRequired: boolean | undefined;
219
+ }, variable: {
220
+ readonly auditRequired: boolean | undefined;
221
+ }): boolean | undefined;
222
+ //# sourceMappingURL=link.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../../src/build/link.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,24 @@
1
+ import type TS from "@typescript/typescript6";
2
+ /**
3
+ * The result of a literal evaluation: either a real JS value, or `{ ok: false }` when the AST
4
+ * expression wasn't a literal (or contained a non-literal element/property).
5
+ */
6
+ export type LiteralEvalResult = {
7
+ ok: true;
8
+ value: unknown;
9
+ } | {
10
+ ok: false;
11
+ value?: undefined;
12
+ };
13
+ /**
14
+ * Structurally evaluates a *literal* AST expression (strings, numbers, booleans, null, arrays,
15
+ * and object literals of the same) into a real JS value: without ever executing code.
16
+ *
17
+ * @remarks
18
+ * Anything that isn't a literal (identifiers, calls, imports, template expressions with
19
+ * interpolation) resolves to `{ ok: false }` rather than being guessed at.
20
+ */
21
+ export declare function evaluateLiteral(node: TS.Expression): LiteralEvalResult;
22
+ /** Reads a property name statically (identifier, string literal, or numeric literal): a computed key (e.g. `[expr]`) resolves to `undefined` rather than being guessed at. */
23
+ export declare function getStaticPropertyName(name: TS.PropertyName): string | undefined;
24
+ //# sourceMappingURL=literal-eval.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"literal-eval.d.ts","sourceRoot":"","sources":["../../../src/build/literal-eval.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhC;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,CAAA;AAE/F;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,GAAG,iBAAiB,CA4CtE;AAED,8KAA8K;AAC9K,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,GAAG,MAAM,GAAG,SAAS,CAK/E"}
@@ -0,0 +1,48 @@
1
+ import type { DiscoveredContract } from "./link.js";
2
+ /**
3
+ * Supplies expiration metadata from a live source (a secrets manager, an
4
+ * internal inventory API, ...) as a post-discovery override: the one
5
+ * sanctioned escape hatch from static-only `expiresAt`.
6
+ *
7
+ * @remarks
8
+ * Invoked exactly once per generation run, from the orchestration layer, after AST discovery/
9
+ * linking completes and before documentation is rendered. Never invoked
10
+ * during AST parsing or runtime validation: see ADR 0012 for why a
11
+ * function embedded in a schema file itself was rejected instead.
12
+ */
13
+ export type LiveExpirationDates = (variableNames: readonly string[]) => Promise<Readonly<Record<string, string>>>;
14
+ /**
15
+ * Every unique variable key across every linked contract's `variables`.
16
+ * Contract-level `expiresAt` is out of scope for override: the callback is
17
+ * keyed by variable name, not contract name.
18
+ */
19
+ export declare function collectVariableNames(contracts: readonly DiscoveredContract[]): string[];
20
+ /**
21
+ * Applies `overrides` onto a fresh copy of `contracts`. Every contract and
22
+ * every variable (and their nested `metadata`/`extra` records) is rebuilt
23
+ * into a new object, never the original reference. The returned structure
24
+ * therefore shares no mutable object identity with `contracts` at any depth.
25
+ *
26
+ * @remarks
27
+ * A key absent from `overrides`, or present but not a `parseIsoDate`-parseable
28
+ * ISO-8601 string, leaves that variable's static `expiresAt` untouched:
29
+ * same "warn/skip, never guess" policy the rest of the generator uses for
30
+ * malformed data. Contract-level `expiresAt` is never touched; only
31
+ * variable-level `expiresAt` is in scope for override.
32
+ */
33
+ export declare function applyLiveExpirationOverrides(contracts: readonly DiscoveredContract[], overrides: Readonly<Record<string, string>>): readonly DiscoveredContract[];
34
+ /**
35
+ * Orchestration entry point: the only place `liveExpirationDates` is ever invoked.
36
+ *
37
+ * @remarks
38
+ * No-ops (returns the exact same array reference, zero invocations)
39
+ * when `liveExpirationDates` is undefined, which is what guarantees "omitted ->
40
+ * behavior unchanged." Otherwise it collects the unique discovered variable
41
+ * names, invokes the callback exactly once and applies the result. It
42
+ * deep-freezes the returned structure so no mutation of it can reach
43
+ * `contracts` or anything else downstream. `contracts` is used elsewhere too,
44
+ * e.g. by the manifest and usage passes in the same
45
+ * {@link generateEnvArtifacts} run.
46
+ */
47
+ export declare function resolveLiveExpirationDates(contracts: readonly DiscoveredContract[], liveExpirationDates: LiveExpirationDates | undefined): Promise<readonly DiscoveredContract[]>;
48
+ //# sourceMappingURL=live-expirations.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"live-expirations.d.ts","sourceRoot":"","sources":["../../../src/build/live-expirations.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,aAAa,EAAE,SAAS,MAAM,EAAE,KAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;AAE9C;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,EAAE,CAMvF;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC1C,SAAS,kBAAkB,EAAE,CAM/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,mBAAmB,EAAE,mBAAmB,GAAG,SAAS,GACnD,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAIxC"}
@@ -0,0 +1,31 @@
1
+ import type { DiscoveredContract } from "./link.js";
2
+ /**
3
+ * Every validation context declared by any variable in an *active* contract
4
+ * in `contracts` (a variable belonging to a contract documented `active:
5
+ * false` never contributes: same exclusion the `manifest` array itself
6
+ * already applies), sorted and deduplicated. What {@link renderManifest}
7
+ * surfaces as the generated `activeContexts` export. Exported for reuse by
8
+ * anything that needs the same computation (currently just `renderManifest`
9
+ * itself).
10
+ */
11
+ export declare function discoverValidationContexts(contracts: readonly DiscoveredContract[]): readonly string[];
12
+ /**
13
+ * Renders the deterministic manifest source: sorted imports (aliased on name
14
+ * collision) plus a `contracts` array, in the exact banner format schema
15
+ * authors will recognize as generated. No timestamps, no randomness: same
16
+ * input files always produce byte-identical output.
17
+ *
18
+ * @remarks
19
+ * When at least one discovered variable declares a `context` (ADR 0022),
20
+ * this also emits `activeContexts`: every validation context found across
21
+ * `contracts`, as a plain array. Its name matches {@link runtime.validateEnvOptions}'s
22
+ * own `activeContexts` field, so application code can import it alongside
23
+ * `manifest` and pass it straight through: `validateEnv({ manifest, values, activeContexts })`.
24
+ * It's every context this manifest has, meant as a starting point to narrow
25
+ * per process/deployment, not a pre-scoped default: see the README's
26
+ * "Validation contexts" section. Omitted entirely (not even an empty array)
27
+ * when no variable declares a `context` at all, so generated output for
28
+ * projects that don't use this feature is untouched.
29
+ */
30
+ export declare function renderManifest(contracts: readonly DiscoveredContract[], outputFile: string): string;
31
+ //# sourceMappingURL=manifest.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/build/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,SAAS,MAAM,EAAE,CASnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,UAAU,EAAE,MAAM,GACjB,MAAM,CAiER"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * `map.get(key)` after iterating `map`'s own `.keys()` is always defined.
3
+ * This makes that invariant an explicit, named operation instead of a bare
4
+ * `!` non-null assertion at each call site. A future bug that violates it
5
+ * gets a real error, not a silent `undefined`.
6
+ */
7
+ export declare function mustGet<K, V>(map: ReadonlyMap<K, V>, key: K): V;
8
+ //# sourceMappingURL=map-utils.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"map-utils.d.ts","sourceRoot":"","sources":["../../../src/build/map-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAK/D"}
@@ -0,0 +1,36 @@
1
+ import type { DiscoveredContract, DiscoveredVariable } from "./link.js";
2
+ /**
3
+ * Every documentation field of a variable that a second declaration of it can supply. `metadata` is merged key by
4
+ * key rather than as one value, so it is handled on its own below. `evidence` is not one of them. Its citations
5
+ * point at the declaring contract's own code and are re-verified there every run (ADR 0037). So they stay with the
6
+ * contract that wrote them, and are never copied to, or compared with, another declaration.
7
+ */
8
+ export declare const VALUE_FIELDS: readonly ["description", "owner", "sensitivity", "expiresAt", "refreshInstructions", "authenticatorType", "rotationPeriod", "lastRotatedAt", "rotationTriggerEvents", "setupInstructions", "required", "deprecated", "deprecatedReason", "removeBy", "renamedFrom", "purpose", "legalBasis", "retention", "dataResidency", "auditRequired"];
9
+ /**
10
+ * Fills what one declaration of a variable leaves unset from the other declarations of the same variable.
11
+ *
12
+ * @remarks
13
+ * A variable can be declared in more than one contract. A package that ships its own contract (see
14
+ * {@link ../README} "Reusable packages") and the application that consumes it both name the same environment
15
+ * variable, because the process has one flat namespace. Writing the explanation twice is how the two drift, so the
16
+ * declaration that carries it can be the one place it is written, and the other adds only what is its own (the
17
+ * application's own `expiresAt`, say).
18
+ *
19
+ * Every field a declaration leaves unset is taken from another declaration that sets it, as long as one of the two
20
+ * is a package's contract. When several set it, a package's contract wins over the application's own, and the
21
+ * first package's wins over a later one's. The application's own contracts fill a gap only when all of them that set
22
+ * it agree. Two of the application's own contracts never fill each other: they are siblings, often alternatives,
23
+ * and each documents the variable for itself. A field a declaration sets itself is never replaced. So two
24
+ * declarations that set the same field differently still differ afterwards, and the compatibility check can say so. `metadata` is merged key by key under
25
+ * the same rule. Pure: the contracts passed in are not changed.
26
+ */
27
+ export declare function mergeSharedDocumentation(contracts: readonly DiscoveredContract[]): readonly DiscoveredContract[];
28
+ /**
29
+ * The fields (and `metadata.<key>`s) {@link mergeSharedDocumentation} filled into `variable` from another declaration
30
+ * of it. The compatibility check skips them: a value a declaration was given is not one it wrote, so it cannot
31
+ * disagree with anyone.
32
+ * @param variable - a variable as the merge returned it; any other has been given nothing.
33
+ * @returns the given field names.
34
+ */
35
+ export declare function donatedTo(variable: DiscoveredVariable): ReadonlySet<string>;
36
+ //# sourceMappingURL=merge-documentation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"merge-documentation.d.ts","sourceRoot":"","sources":["../../../src/build/merge-documentation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEvE;;;;;GAKG;AACH,eAAO,MAAM,YAAY,6UAqBiC,CAAA;AAQ1D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GACvC,SAAS,kBAAkB,EAAE,CA6B/B;AA8DD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,kBAAkB,GAAG,WAAW,CAAC,MAAM,CAAC,CAE3E"}
@@ -0,0 +1,58 @@
1
+ import type { ContractRef } from "./evidence-reference.js";
2
+ import type { DiscoveredContract } from "./link.js";
3
+ /**
4
+ * The third of env-cap's seven canonical fact models (ADR 0024): every
5
+ * contract and variable's effective owner, plus first-class
6
+ * `unownedContracts`/`unownedVariables` arrays. See ADR 0028.
7
+ *
8
+ * @remarks
9
+ * `docs.ts`'s security review holds "unowned" only as a count
10
+ * (`noOwnerCount`); this model itemizes it as data. It uses the same
11
+ * `effectiveOwner()` rule (variable overrides contract) as `docs.ts` and
12
+ * `usage-report.ts`'s ownership findings (ADR 0028). So this model can never
13
+ * disagree with either of them about who owns a variable.
14
+ */
15
+ /** Bump only when a reader could misinterpret the new shape: same discipline every other canonical model's `schemaVersion` follows. */
16
+ export declare const OWNERSHIP_MODEL_SCHEMA_VERSION = 1;
17
+ /**
18
+ * One variable's effective owner (its own, falling back to the contract's).
19
+ *
20
+ * @see {@link ContractModelVariable}: this same declared variable's canonical starting point.
21
+ */
22
+ export interface OwnershipModelVariable {
23
+ readonly key: string;
24
+ /** The variable's own `owner`, falling back to the contract's: see `effectiveOwner()`. */
25
+ readonly owner: string | undefined;
26
+ }
27
+ /** One contract's own default owner plus every variable's effective owner. See {@link OwnershipModelVariable} for the per-variable shape. */
28
+ export interface OwnershipModelContract {
29
+ /** Root-relative, POSIX-separated: matches `ContractModelContract.file`. */
30
+ readonly file: string;
31
+ readonly exportName: string;
32
+ readonly contractName: string;
33
+ /** The contract's own default owner: not "effective" the way a variable's is, since there's no level above a contract to fall back to. */
34
+ readonly owner: string | undefined;
35
+ readonly variables: readonly OwnershipModelVariable[];
36
+ }
37
+ /** One contract, referenced by identity only: see {@link ContractRef} for why no `contractName` is carried here. Resolve one from `ContractModel` when a renderer needs display text. */
38
+ export type OwnershipModelContractRef = ContractRef;
39
+ /** One variable, referenced by its owning contract's identity plus its own key: see {@link ContractRef}. */
40
+ export interface OwnershipModelVariableRef extends ContractRef {
41
+ readonly key: string;
42
+ }
43
+ /** The versioned, JSON-serializable root of the Ownership Model: see this module's own doc comment for the full picture. */
44
+ export interface OwnershipModel {
45
+ readonly schemaVersion: typeof OWNERSHIP_MODEL_SCHEMA_VERSION;
46
+ readonly contracts: readonly OwnershipModelContract[];
47
+ /** Every contract with no `owner` set at all. */
48
+ readonly unownedContracts: readonly OwnershipModelContractRef[];
49
+ /** Every variable whose effective owner (its own, falling back to the contract's) is still `undefined`. */
50
+ readonly unownedVariables: readonly OwnershipModelVariableRef[];
51
+ }
52
+ /**
53
+ * Projects every discovered contract (active or not, same scope as
54
+ * `renderSecurityReview()`'s `noOwnerCount` this model itemizes) into the
55
+ * Ownership Model's versioned, JSON-serializable shape.
56
+ */
57
+ export declare function buildOwnershipModel(contracts: readonly DiscoveredContract[], root: string): OwnershipModel;
58
+ //# sourceMappingURL=ownership-model.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ownership-model.d.ts","sourceRoot":"","sources":["../../../src/build/ownership-model.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAEnD;;;;;;;;;;;GAWG;AAEH,uIAAuI;AACvI,eAAO,MAAM,8BAA8B,IAAI,CAAA;AAE/C;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAED,6IAA6I;AAC7I,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,0IAA0I;IAC1I,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACtD;AAED,yLAAyL;AACzL,MAAM,MAAM,yBAAyB,GAAG,WAAW,CAAA;AAEnD,4GAA4G;AAC5G,MAAM,WAAW,yBAA0B,SAAQ,WAAW;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,4HAA4H;AAC5H,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,aAAa,EAAE,OAAO,8BAA8B,CAAA;IAC7D,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;IACrD,iDAAiD;IACjD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAC/D,2GAA2G;IAC3G,QAAQ,CAAC,gBAAgB,EAAE,SAAS,yBAAyB,EAAE,CAAA;CAChE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,IAAI,EAAE,MAAM,GACX,cAAc,CAmChB"}