@maverickcer/env-cap 0.5.3 → 0.7.0

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 (359) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +438 -0
  4. package/CODE_OF_CONDUCT.md +124 -0
  5. package/CODE_REVIEW.md +200 -0
  6. package/CONTRIBUTING.md +131 -0
  7. package/GUIDE.md +1214 -0
  8. package/PROMPT.md +89 -0
  9. package/README.md +97 -199
  10. package/RELEASING.md +160 -0
  11. package/SECURITY.md +270 -0
  12. package/SUPPORT.md +76 -0
  13. package/VERSIONING.md +118 -0
  14. package/benchmarks/READING-BENCHMARKS.md +197 -0
  15. package/benchmarks/README.md +126 -0
  16. package/benchmarks/WRITING-BENCHMARKS.md +252 -0
  17. package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
  18. package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
  19. package/dist/.dts/_ipc/build-fs.d.ts +53 -0
  20. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
  21. package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
  22. package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
  23. package/dist/.dts/_ipc/display-path.d.ts +27 -0
  24. package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
  25. package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
  26. package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
  27. package/dist/.dts/_ipc/glob.d.ts +22 -0
  28. package/dist/.dts/_ipc/glob.d.ts.map +1 -0
  29. package/dist/.dts/_ipc/no-node-fs.d.ts +34 -0
  30. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
  31. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  32. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  33. package/dist/.dts/_ipc/typescript.d.ts +20 -0
  34. package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
  35. package/dist/.dts/build/assemble-project.d.ts +1 -1
  36. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  37. package/dist/.dts/build/change-model.d.ts.map +1 -1
  38. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  39. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  40. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  41. package/dist/.dts/build/compiler-api.d.ts +12 -0
  42. package/dist/.dts/build/compiler-api.d.ts.map +1 -0
  43. package/dist/.dts/build/dependency-graph.d.ts +3 -1
  44. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  45. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  46. package/dist/.dts/build/discover.d.ts.map +1 -1
  47. package/dist/.dts/build/display-path.d.ts +3 -21
  48. package/dist/.dts/build/display-path.d.ts.map +1 -1
  49. package/dist/.dts/build/docs.d.ts +1 -1
  50. package/dist/.dts/build/docs.d.ts.map +1 -1
  51. package/dist/.dts/build/env-example.d.ts.map +1 -1
  52. package/dist/.dts/build/evidence-cache.d.ts +1 -1
  53. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  54. package/dist/.dts/build/evidence-model.d.ts +2 -2
  55. package/dist/.dts/build/evidence-snapshot.d.ts +25 -0
  56. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  57. package/dist/.dts/build/finding-model.d.ts +1 -1
  58. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  59. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  60. package/dist/.dts/build/generate-env-artifacts.d.ts +23 -8
  61. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  62. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  63. package/dist/.dts/build/generate-manifest.d.ts +1 -1
  64. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  65. package/dist/.dts/build/generate-usage.d.ts +3 -3
  66. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  67. package/dist/.dts/build/generated-banner.d.ts +29 -38
  68. package/dist/.dts/build/generated-banner.d.ts.map +1 -1
  69. package/dist/.dts/build/glob.d.ts +3 -15
  70. package/dist/.dts/build/glob.d.ts.map +1 -1
  71. package/dist/.dts/build/index.d.ts +2 -2
  72. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  73. package/dist/.dts/build/link.d.ts.map +1 -1
  74. package/dist/.dts/build/literal-eval.d.ts +4 -3
  75. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  76. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  77. package/dist/.dts/build/manifest.d.ts.map +1 -1
  78. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  79. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  80. package/dist/.dts/build/parse.d.ts +12 -12
  81. package/dist/.dts/build/parse.d.ts.map +1 -1
  82. package/dist/.dts/build/reference-projections.d.ts +17 -3
  83. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  84. package/dist/.dts/build/resolution/resolve-import.d.ts +5 -0
  85. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  86. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +1 -1
  87. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  88. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -94
  89. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  90. package/dist/.dts/build/sarif.d.ts.map +1 -1
  91. package/dist/.dts/build/scan-dependencies.d.ts +23 -0
  92. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  93. package/dist/.dts/build/types.d.ts +4 -53
  94. package/dist/.dts/build/types.d.ts.map +1 -1
  95. package/dist/.dts/build/typescript.d.ts +6 -0
  96. package/dist/.dts/build/typescript.d.ts.map +1 -0
  97. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  98. package/dist/.dts/cli/filesystem.d.ts +4 -0
  99. package/dist/.dts/cli/filesystem.d.ts.map +1 -1
  100. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  101. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  102. package/dist/.dts/eslint-plugin/index.d.ts +3 -3
  103. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  104. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  105. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  106. package/dist/.dts/evidence/index.d.ts +2 -2
  107. package/dist/.dts/helpers/index.d.ts +2 -2
  108. package/dist/.dts/helpers/processors.d.ts.map +1 -1
  109. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  110. package/dist/.dts/runtime/cache.d.ts +0 -3
  111. package/dist/.dts/runtime/cache.d.ts.map +1 -1
  112. package/dist/.dts/runtime/create.d.ts.map +1 -1
  113. package/dist/.dts/runtime/document.d.ts.map +1 -1
  114. package/dist/.dts/runtime/index.d.ts +2 -2
  115. package/dist/.dts/runtime/registry.d.ts.map +1 -1
  116. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  117. package/dist/{build-U326PI5A.js → build-WKDIAWF7.js} +685 -645
  118. package/dist/build-WKDIAWF7.js.map +1 -0
  119. package/dist/build.cjs +698 -651
  120. package/dist/build.cjs.map +1 -1
  121. package/dist/build.js +695 -649
  122. package/dist/build.js.map +1 -1
  123. package/dist/{chunk-BSTLSR2R.js → chunk-KEGYUHBU.js} +2 -2
  124. package/dist/chunk-KEGYUHBU.js.map +1 -0
  125. package/dist/cli/index.js +64 -63
  126. package/dist/cli/index.js.map +1 -1
  127. package/dist/eslint-plugin/index.cjs +95 -626
  128. package/dist/eslint-plugin/index.cjs.map +1 -1
  129. package/dist/eslint-plugin/index.js +94 -625
  130. package/dist/eslint-plugin/index.js.map +1 -1
  131. package/dist/evidence.cjs.map +1 -1
  132. package/dist/evidence.js.map +1 -1
  133. package/dist/helpers.cjs +4 -9
  134. package/dist/helpers.cjs.map +1 -1
  135. package/dist/helpers.js +4 -9
  136. package/dist/helpers.js.map +1 -1
  137. package/dist/index.cjs +11 -25
  138. package/dist/index.cjs.map +1 -1
  139. package/dist/index.js +11 -25
  140. package/dist/index.js.map +1 -1
  141. package/dist/node.cjs +10 -8
  142. package/dist/node.cjs.map +1 -1
  143. package/dist/node.js +10 -8
  144. package/dist/node.js.map +1 -1
  145. package/examples/README.md +95 -0
  146. package/node_modules/@typescript/old/LICENSE.txt +55 -0
  147. package/node_modules/@typescript/old/README.md +50 -0
  148. package/node_modules/@typescript/old/SECURITY.md +39 -0
  149. package/node_modules/@typescript/old/ThirdPartyNoticeText.txt +193 -0
  150. package/node_modules/@typescript/old/bin/tsc +2 -0
  151. package/node_modules/@typescript/old/bin/tsserver +2 -0
  152. package/node_modules/@typescript/old/lib/_tsc.js +134465 -0
  153. package/node_modules/@typescript/old/lib/_tsserver.js +659 -0
  154. package/node_modules/@typescript/old/lib/_typingsInstaller.js +222 -0
  155. package/node_modules/@typescript/old/lib/cs/diagnosticMessages.generated.json +2129 -0
  156. package/node_modules/@typescript/old/lib/de/diagnosticMessages.generated.json +2125 -0
  157. package/node_modules/@typescript/old/lib/es/diagnosticMessages.generated.json +2129 -0
  158. package/node_modules/@typescript/old/lib/fr/diagnosticMessages.generated.json +2129 -0
  159. package/node_modules/@typescript/old/lib/it/diagnosticMessages.generated.json +2125 -0
  160. package/node_modules/@typescript/old/lib/ja/diagnosticMessages.generated.json +2129 -0
  161. package/node_modules/@typescript/old/lib/ko/diagnosticMessages.generated.json +2129 -0
  162. package/node_modules/@typescript/old/lib/lib.d.ts +20 -0
  163. package/node_modules/@typescript/old/lib/lib.decorators.d.ts +382 -0
  164. package/node_modules/@typescript/old/lib/lib.decorators.legacy.d.ts +20 -0
  165. package/node_modules/@typescript/old/lib/lib.dom.asynciterable.d.ts +18 -0
  166. package/node_modules/@typescript/old/lib/lib.dom.d.ts +45125 -0
  167. package/node_modules/@typescript/old/lib/lib.dom.iterable.d.ts +18 -0
  168. package/node_modules/@typescript/old/lib/lib.es2015.collection.d.ts +150 -0
  169. package/node_modules/@typescript/old/lib/lib.es2015.core.d.ts +595 -0
  170. package/node_modules/@typescript/old/lib/lib.es2015.d.ts +26 -0
  171. package/node_modules/@typescript/old/lib/lib.es2015.generator.d.ts +75 -0
  172. package/node_modules/@typescript/old/lib/lib.es2015.iterable.d.ts +603 -0
  173. package/node_modules/@typescript/old/lib/lib.es2015.promise.d.ts +79 -0
  174. package/node_modules/@typescript/old/lib/lib.es2015.proxy.d.ts +126 -0
  175. package/node_modules/@typescript/old/lib/lib.es2015.reflect.d.ts +142 -0
  176. package/node_modules/@typescript/old/lib/lib.es2015.symbol.d.ts +44 -0
  177. package/node_modules/@typescript/old/lib/lib.es2015.symbol.wellknown.d.ts +324 -0
  178. package/node_modules/@typescript/old/lib/lib.es2016.array.include.d.ts +114 -0
  179. package/node_modules/@typescript/old/lib/lib.es2016.d.ts +19 -0
  180. package/node_modules/@typescript/old/lib/lib.es2016.full.d.ts +21 -0
  181. package/node_modules/@typescript/old/lib/lib.es2016.intl.d.ts +29 -0
  182. package/node_modules/@typescript/old/lib/lib.es2017.arraybuffer.d.ts +19 -0
  183. package/node_modules/@typescript/old/lib/lib.es2017.d.ts +24 -0
  184. package/node_modules/@typescript/old/lib/lib.es2017.date.d.ts +29 -0
  185. package/node_modules/@typescript/old/lib/lib.es2017.full.d.ts +21 -0
  186. package/node_modules/@typescript/old/lib/lib.es2017.intl.d.ts +42 -0
  187. package/node_modules/@typescript/old/lib/lib.es2017.object.d.ts +47 -0
  188. package/node_modules/@typescript/old/lib/lib.es2017.sharedmemory.d.ts +133 -0
  189. package/node_modules/@typescript/old/lib/lib.es2017.string.d.ts +43 -0
  190. package/node_modules/@typescript/old/lib/lib.es2017.typedarrays.d.ts +51 -0
  191. package/node_modules/@typescript/old/lib/lib.es2018.asyncgenerator.d.ts +75 -0
  192. package/node_modules/@typescript/old/lib/lib.es2018.asynciterable.d.ts +51 -0
  193. package/node_modules/@typescript/old/lib/lib.es2018.d.ts +22 -0
  194. package/node_modules/@typescript/old/lib/lib.es2018.full.d.ts +22 -0
  195. package/node_modules/@typescript/old/lib/lib.es2018.intl.d.ts +81 -0
  196. package/node_modules/@typescript/old/lib/lib.es2018.promise.d.ts +28 -0
  197. package/node_modules/@typescript/old/lib/lib.es2018.regexp.d.ts +35 -0
  198. package/node_modules/@typescript/old/lib/lib.es2019.array.d.ts +77 -0
  199. package/node_modules/@typescript/old/lib/lib.es2019.d.ts +22 -0
  200. package/node_modules/@typescript/old/lib/lib.es2019.full.d.ts +22 -0
  201. package/node_modules/@typescript/old/lib/lib.es2019.intl.d.ts +21 -0
  202. package/node_modules/@typescript/old/lib/lib.es2019.object.d.ts +31 -0
  203. package/node_modules/@typescript/old/lib/lib.es2019.string.d.ts +35 -0
  204. package/node_modules/@typescript/old/lib/lib.es2019.symbol.d.ts +22 -0
  205. package/node_modules/@typescript/old/lib/lib.es2020.bigint.d.ts +763 -0
  206. package/node_modules/@typescript/old/lib/lib.es2020.d.ts +25 -0
  207. package/node_modules/@typescript/old/lib/lib.es2020.date.d.ts +40 -0
  208. package/node_modules/@typescript/old/lib/lib.es2020.full.d.ts +22 -0
  209. package/node_modules/@typescript/old/lib/lib.es2020.intl.d.ts +472 -0
  210. package/node_modules/@typescript/old/lib/lib.es2020.number.d.ts +26 -0
  211. package/node_modules/@typescript/old/lib/lib.es2020.promise.d.ts +45 -0
  212. package/node_modules/@typescript/old/lib/lib.es2020.sharedmemory.d.ts +97 -0
  213. package/node_modules/@typescript/old/lib/lib.es2020.string.d.ts +42 -0
  214. package/node_modules/@typescript/old/lib/lib.es2020.symbol.wellknown.d.ts +39 -0
  215. package/node_modules/@typescript/old/lib/lib.es2021.d.ts +21 -0
  216. package/node_modules/@typescript/old/lib/lib.es2021.full.d.ts +22 -0
  217. package/node_modules/@typescript/old/lib/lib.es2021.intl.d.ts +164 -0
  218. package/node_modules/@typescript/old/lib/lib.es2021.promise.d.ts +46 -0
  219. package/node_modules/@typescript/old/lib/lib.es2021.string.d.ts +31 -0
  220. package/node_modules/@typescript/old/lib/lib.es2021.weakref.d.ts +76 -0
  221. package/node_modules/@typescript/old/lib/lib.es2022.array.d.ts +119 -0
  222. package/node_modules/@typescript/old/lib/lib.es2022.d.ts +23 -0
  223. package/node_modules/@typescript/old/lib/lib.es2022.error.d.ts +73 -0
  224. package/node_modules/@typescript/old/lib/lib.es2022.full.d.ts +22 -0
  225. package/node_modules/@typescript/old/lib/lib.es2022.intl.d.ts +143 -0
  226. package/node_modules/@typescript/old/lib/lib.es2022.object.d.ts +24 -0
  227. package/node_modules/@typescript/old/lib/lib.es2022.regexp.d.ts +37 -0
  228. package/node_modules/@typescript/old/lib/lib.es2022.string.d.ts +23 -0
  229. package/node_modules/@typescript/old/lib/lib.es2023.array.d.ts +922 -0
  230. package/node_modules/@typescript/old/lib/lib.es2023.collection.d.ts +19 -0
  231. package/node_modules/@typescript/old/lib/lib.es2023.d.ts +20 -0
  232. package/node_modules/@typescript/old/lib/lib.es2023.full.d.ts +22 -0
  233. package/node_modules/@typescript/old/lib/lib.es2023.intl.d.ts +62 -0
  234. package/node_modules/@typescript/old/lib/lib.es2024.arraybuffer.d.ts +63 -0
  235. package/node_modules/@typescript/old/lib/lib.es2024.collection.d.ts +27 -0
  236. package/node_modules/@typescript/old/lib/lib.es2024.d.ts +24 -0
  237. package/node_modules/@typescript/old/lib/lib.es2024.full.d.ts +22 -0
  238. package/node_modules/@typescript/old/lib/lib.es2024.object.d.ts +27 -0
  239. package/node_modules/@typescript/old/lib/lib.es2024.promise.d.ts +33 -0
  240. package/node_modules/@typescript/old/lib/lib.es2024.regexp.d.ts +23 -0
  241. package/node_modules/@typescript/old/lib/lib.es2024.sharedmemory.d.ts +66 -0
  242. package/node_modules/@typescript/old/lib/lib.es2024.string.d.ts +27 -0
  243. package/node_modules/@typescript/old/lib/lib.es2025.collection.d.ts +94 -0
  244. package/node_modules/@typescript/old/lib/lib.es2025.d.ts +23 -0
  245. package/node_modules/@typescript/old/lib/lib.es2025.float16.d.ts +443 -0
  246. package/node_modules/@typescript/old/lib/lib.es2025.full.d.ts +22 -0
  247. package/node_modules/@typescript/old/lib/lib.es2025.intl.d.ts +200 -0
  248. package/node_modules/@typescript/old/lib/lib.es2025.iterator.d.ts +146 -0
  249. package/node_modules/@typescript/old/lib/lib.es2025.promise.d.ts +32 -0
  250. package/node_modules/@typescript/old/lib/lib.es2025.regexp.d.ts +30 -0
  251. package/node_modules/@typescript/old/lib/lib.es5.d.ts +4599 -0
  252. package/node_modules/@typescript/old/lib/lib.es6.d.ts +21 -0
  253. package/node_modules/@typescript/old/lib/lib.esnext.array.d.ts +33 -0
  254. package/node_modules/@typescript/old/lib/lib.esnext.collection.d.ts +47 -0
  255. package/node_modules/@typescript/old/lib/lib.esnext.d.ts +27 -0
  256. package/node_modules/@typescript/old/lib/lib.esnext.date.d.ts +21 -0
  257. package/node_modules/@typescript/old/lib/lib.esnext.decorators.d.ts +26 -0
  258. package/node_modules/@typescript/old/lib/lib.esnext.disposable.d.ts +191 -0
  259. package/node_modules/@typescript/old/lib/lib.esnext.error.d.ts +22 -0
  260. package/node_modules/@typescript/old/lib/lib.esnext.full.d.ts +22 -0
  261. package/node_modules/@typescript/old/lib/lib.esnext.intl.d.ts +107 -0
  262. package/node_modules/@typescript/old/lib/lib.esnext.sharedmemory.d.ts +23 -0
  263. package/node_modules/@typescript/old/lib/lib.esnext.temporal.d.ts +485 -0
  264. package/node_modules/@typescript/old/lib/lib.esnext.typedarrays.d.ts +90 -0
  265. package/node_modules/@typescript/old/lib/lib.scripthost.d.ts +320 -0
  266. package/node_modules/@typescript/old/lib/lib.webworker.asynciterable.d.ts +18 -0
  267. package/node_modules/@typescript/old/lib/lib.webworker.d.ts +15606 -0
  268. package/node_modules/@typescript/old/lib/lib.webworker.importscripts.d.ts +21 -0
  269. package/node_modules/@typescript/old/lib/lib.webworker.iterable.d.ts +18 -0
  270. package/node_modules/@typescript/old/lib/pl/diagnosticMessages.generated.json +2129 -0
  271. package/node_modules/@typescript/old/lib/pt-br/diagnosticMessages.generated.json +2129 -0
  272. package/node_modules/@typescript/old/lib/ru/diagnosticMessages.generated.json +2125 -0
  273. package/node_modules/@typescript/old/lib/tr/diagnosticMessages.generated.json +2129 -0
  274. package/node_modules/@typescript/old/lib/tsc.js +8 -0
  275. package/node_modules/@typescript/old/lib/tsserver.js +8 -0
  276. package/node_modules/@typescript/old/lib/tsserverlibrary.d.ts +17 -0
  277. package/node_modules/@typescript/old/lib/tsserverlibrary.js +21 -0
  278. package/node_modules/@typescript/old/lib/typesMap.json +497 -0
  279. package/node_modules/@typescript/old/lib/typescript.d.ts +11448 -0
  280. package/node_modules/@typescript/old/lib/typescript.js +201039 -0
  281. package/node_modules/@typescript/old/lib/typingsInstaller.js +8 -0
  282. package/node_modules/@typescript/old/lib/watchGuard.js +53 -0
  283. package/node_modules/@typescript/old/lib/zh-cn/diagnosticMessages.generated.json +2129 -0
  284. package/node_modules/@typescript/old/lib/zh-tw/diagnosticMessages.generated.json +2125 -0
  285. package/node_modules/@typescript/old/package.json +118 -0
  286. package/node_modules/@typescript/typescript6/LICENSE.txt +55 -0
  287. package/node_modules/@typescript/typescript6/README.md +9 -0
  288. package/node_modules/@typescript/typescript6/bin/tsc6 +2 -0
  289. package/node_modules/@typescript/typescript6/lib/tsc.js +1 -0
  290. package/node_modules/@typescript/typescript6/lib/tsserverlibrary.d.ts +2 -0
  291. package/node_modules/@typescript/typescript6/lib/tsserverlibrary.js +1 -0
  292. package/node_modules/@typescript/typescript6/lib/typescript.d.ts +2 -0
  293. package/node_modules/@typescript/typescript6/lib/typescript.js +1 -0
  294. package/node_modules/@typescript/typescript6/package.json +39 -0
  295. package/package.json +74 -22
  296. package/schemas/env-cap-report.schema.json +1 -1
  297. package/skills/env-cap/SKILL.md +91 -0
  298. package/skills/env-cap/references/api.md +220 -0
  299. package/specs/architecture.md +634 -0
  300. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  301. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  302. package/specs/decisions/0003-no-global-env-object.md +172 -0
  303. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  304. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  305. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  306. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  307. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  308. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  309. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  310. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  311. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  312. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  313. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  314. package/specs/decisions/0015-security-backport-window.md +60 -0
  315. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  316. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  317. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  318. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  319. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  320. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  321. package/specs/decisions/0022-validation-contexts.md +267 -0
  322. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  323. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  324. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  325. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  326. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  327. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  328. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  329. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  330. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  331. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  332. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  333. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  334. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  335. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  336. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  337. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  338. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  339. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  340. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  341. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  342. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  343. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  344. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  345. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  346. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  347. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  348. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  349. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  350. package/specs/generated-artifacts.md +104 -0
  351. package/specs/migrations/README.md +30 -0
  352. package/specs/migrations/from-centralized-schema.md +503 -0
  353. package/specs/migrations/from-dotenv.md +352 -0
  354. package/specs/migrations/from-envalid.md +482 -0
  355. package/specs/migrations/from-process-env.md +398 -0
  356. package/specs/migrations/from-t3-env.md +416 -0
  357. package/specs/migrations/from-zod.md +303 -0
  358. package/dist/build-U326PI5A.js.map +0 -1
  359. package/dist/chunk-BSTLSR2R.js.map +0 -1
@@ -0,0 +1,116 @@
1
+ # 0004: No `env-cap/client` or `/server` package
2
+
3
+ ## Status
4
+
5
+ Accepted. Reflected in `package.json`'s `exports` map (only `.`, `./build`,
6
+ and `./helpers`) and documented in the README's ["Runtime and build-time are
7
+ intentionally separate"](../../GUIDE.md#runtime-and-build-time-are-intentionally-separate)
8
+ section.
9
+
10
+ ## Context
11
+
12
+ Many environment-management libraries provide separate `/client` and
13
+ `/server` entry points to reduce the risk of exposing server-only
14
+ configuration to browser bundles. These packages typically enforce the
15
+ distinction by creating separate APIs or schema types that prevent server
16
+ variables from being referenced in client code.
17
+
18
+ `env-cap` needs to support the same goal: allowing applications to
19
+ maintain clear boundaries between server-only configuration and
20
+ client-safe configuration without introducing unnecessary runtime
21
+ complexity.
22
+
23
+ ## Decision
24
+
25
+ `env-cap` does not provide separate `/client` or `/server` subpath
26
+ exports.
27
+
28
+ The runtime API (`createEnv` and `validateEnv`) is intentionally identical
29
+ for all environments. A variable's classification as server-only or
30
+ client-safe does not change how it is processed, validated, or accessed at
31
+ runtime. There is no different runtime behavior that would justify separate
32
+ packages.
33
+
34
+ The separation happens at build time through generated contract. Projects
35
+ should generate separate contract for separate execution environments using
36
+ disjoint discovery rules:
37
+
38
+ ```js
39
+ await generateEnvManifest({
40
+ location: "src/generated/server.contract.ts",
41
+ include: ["server/**/env.schema.ts"],
42
+ })
43
+
44
+ await generateEnvManifest({
45
+ location: "src/generated/client.contract.ts",
46
+ include: ["web/**/env.schema.ts"],
47
+ })
48
+ ```
49
+
50
+ The application architecture is responsible for ensuring that
51
+ server-generated contract are only imported by server-side code and
52
+ client-generated contract are only imported by browser-bound code. This
53
+ follows the same dependency-boundary rules used throughout an application:
54
+ server-only modules should not be imported into client code.
55
+
56
+ ## Consequences
57
+
58
+ - **The package does not pretend to provide enforcement it cannot guarantee.**
59
+ Separate `/client` and `/server` packages would not fully prevent
60
+ accidental exposure. A developer could still misconfigure discovery
61
+ patterns or import a server contract directly into client code. The actual
62
+ security boundary remains the application's module graph and build
63
+ configuration.
64
+
65
+ - **The public API remains smaller and more accurate.**
66
+ Separate entry points would suggest different runtime capabilities or
67
+ behaviors that do not exist. Maintaining two nearly identical APIs would
68
+ add maintenance cost while providing little additional protection.
69
+
70
+ - **Environment separation remains explicit and project-owned.**
71
+ Different applications have different definitions of what is client-safe,
72
+ server-only, internal, or public. `env-cap` does not impose a
73
+ universal classification system. Teams define those boundaries through
74
+ their schema organization, generated contract, and documentation.
75
+
76
+ - **Build-time metadata remains separate from runtime behavior.**
77
+ Whether a variable is categorized as server-only or client-safe is a
78
+ build and deployment concern, not something the runtime needs to process.
79
+ This keeps the runtime contract minimal and avoids carrying metadata that
80
+ has no effect during validation.
81
+
82
+ ## Alternatives considered
83
+
84
+ - **Parallel `/client` and `/server` packages with identical APIs.**
85
+ Rejected. This would imply a runtime distinction that does not exist,
86
+ double the public API surface, and require every future runtime change to
87
+ be maintained across multiple entry points. It would also not prevent
88
+ incorrect imports or incorrectly generated contract.
89
+
90
+ - **A `runtime: "server" | "client"` option on `createEnv`.**
91
+ Rejected. This would add classification data to the runtime schema even
92
+ though the runtime does not use it. It would blur the boundary between
93
+ runtime configuration processing and build-time concerns. Environment
94
+ classification belongs with build tooling and documentation, not the
95
+ runtime contract itself.
96
+
97
+ - **Automatic detection of client/server usage at runtime.**
98
+ Rejected. Runtime detection would be framework-dependent, unreliable
99
+ across different deployment targets, and would introduce complexity into
100
+ the smallest and most security-sensitive part of the package. The package
101
+ should remain environment-agnostic and allow the application's build
102
+ system to define the correct boundary.
103
+
104
+ ## Update (see ADR 0022)
105
+
106
+ [ADR 0022](0022-validation-contexts.md) later added a generic
107
+ `context`/`activeContexts` mechanism to `createEnv()`/`validateEnv()`.
108
+ This is _not_ the `runtime: "server" | "client"` option rejected above:
109
+ that alternative was a closed, client/server-specific enum that implied a
110
+ bundling boundary the runtime can't actually enforce. `context` is an
111
+ open, application-defined string (never interpreted by env-cap, never
112
+ limited to client/server) that only gates whether `validateEnv()`
113
+ processes a variable in a given run -- it makes no claim about, and is not
114
+ a substitute for, the module-boundary decision made above. Separate
115
+ discovery/manifests remain the only real mechanism for keeping
116
+ server-only source out of client-bound code.
@@ -0,0 +1,93 @@
1
+ # 0005: Manifest generation warns by default; throwing is opt-in
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/build/generate-manifest.ts`
6
+ (`onIncompatibility`) and `src/build/generate-documentation.ts`
7
+ (`onUndocumented`), both defaulting to `"warn"`.
8
+
9
+ ## Context
10
+
11
+ `generateEnvManifest()` performs static analysis rather than executing
12
+ application code (see 0002). Because of this, some findings can be detected
13
+ with certainty while others represent potential issues that require human
14
+ judgment.
15
+
16
+ Two categories intentionally fall into the second group:
17
+
18
+ - **Duplicate variable incompatibility.**
19
+ The build tool cannot execute processors or validators to determine their
20
+ runtime behavior. It can only prove that two contracts are incompatible
21
+ when both provide explicit, conflicting return-type annotations for the
22
+ same variable name. Different implementations without annotations, or
23
+ implementations that happen to produce different values at runtime, cannot
24
+ be proven incompatible through static analysis alone.
25
+
26
+ - **Undocumented contracts or variables.**
27
+ A `createEnv()` call without a matching `documentEnv()` call, or a variable
28
+ that exists in the schema but not in documentation, indicates incomplete
29
+ documentation coverage. However, documentation is intentionally optional
30
+ (see 0001), so the absence of documentation is not inherently a runtime
31
+ correctness failure.
32
+
33
+ ## Decision
34
+
35
+ `onIncompatibility` and `onUndocumented` both default to `"warn"`.
36
+
37
+ When a warning-level finding is detected, it is included in the generation
38
+ result, surfaced through the CLI, and included in generated reporting output,
39
+ but contract generation continues and the output file is written.
40
+
41
+ Only findings that can be proven to be invalid are treated as generation
42
+ failures by default. For example, two contracts declaring the same variable
43
+ with explicitly incompatible return-type annotations are a confirmed
44
+ conflict and block generation.
45
+
46
+ Teams that want stricter enforcement can set either option to `"throw"`.
47
+ This converts that category of finding into an `EnvManifestGenerationError`,
48
+ allowing projects to enforce stricter CI requirements as their adoption
49
+ matures.
50
+
51
+ ## Consequences
52
+
53
+ - **Projects can adopt `env-cap` incrementally.**
54
+ A team does not need complete documentation coverage or immediate
55
+ resolution of every potential duplicate-variable concern before generating
56
+ its first contract. Documentation and stricter validation policies can be
57
+ introduced over time through CLI flags such as `--strict` and
58
+ `--strict-docs`, or through equivalent options passed directly to
59
+ `generateEnvManifest()`.
60
+
61
+ - **Warnings require an intentional review process.**
62
+ Because warnings do not fail generation by default, a project that only
63
+ checks command exit codes could allow important findings to remain
64
+ unresolved. The CLI surfaces warnings directly, and generated
65
+ documentation artifacts provide additional visibility, but teams should
66
+ decide how warnings are reviewed within their development workflow.
67
+
68
+ - **Strict enforcement does not require different analysis logic.**
69
+ Teams can move from permissive adoption to strict CI enforcement without
70
+ changing schemas or rewriting configuration. The same static analysis runs
71
+ in both modes; the only difference is whether a detected condition is
72
+ informational or fatal.
73
+
74
+ - **The package avoids pretending static analysis knows more than it does.**
75
+ A warning represents uncertainty that requires human evaluation. Throwing
76
+ for cases that cannot be proven would encourage developers to work around
77
+ the tool rather than trust its results.
78
+
79
+ ## Alternatives considered
80
+
81
+ - **Throw by default.**
82
+ Rejected. This would require every project to achieve complete
83
+ documentation coverage and resolve every potential duplicate-variable
84
+ concern before the first successful contract generation. That conflicts
85
+ with the design goal that documentation is optional and can be adopted
86
+ incrementally.
87
+
88
+ - **Only report provable incompatibilities and ignore uncertain cases.**
89
+ Rejected. Remaining silent about possible issues removes valuable context
90
+ from developers and prevents teams from improving their configuration
91
+ quality over time. The package follows a consistent policy: detect what can
92
+ be proven, warn about what requires review, and avoid making assumptions
93
+ about runtime behavior.
@@ -0,0 +1,124 @@
1
+ # 0006: Contracts redact themselves; only explicit per-key access reveals a value
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/runtime/create.ts`.
6
+
7
+ ## Context
8
+
9
+ A common way secrets reach logs or monitoring systems is through accidental
10
+ object serialization rather than intentional exposure. Examples include
11
+ debugging statements such as `console.log(config)` or serializing request
12
+ context objects that happen to contain resolved environment values.
13
+
14
+ A traditional environment library often returns a plain object containing
15
+ resolved values:
16
+
17
+ ```ts
18
+ {
19
+ STRIPE_KEY: "sk_live_...",
20
+ DATABASE_URL: "postgres://..."
21
+ }
22
+ ```
23
+
24
+ This creates an unsafe default because the easiest way to inspect the object
25
+ is also the easiest way to expose every secret it contains. Reading one
26
+ specific variable and dumping the entire configuration object require the
27
+ same action.
28
+
29
+ ## Decision
30
+
31
+ The object returned by `createEnv()` is intentionally not a plain value
32
+ object. It is a protected contract object that exposes values only through
33
+ explicit property access.
34
+
35
+ The returned object overrides:
36
+
37
+ - `Symbol.for("nodejs.util.inspect.custom")`
38
+ - `toString()`
39
+ - `toJSON()`
40
+
41
+ Each returns a redacted representation containing only contract metadata:
42
+
43
+ ```text
44
+ EnvContract("payments") { 3 variable(s) }
45
+ ```
46
+
47
+ The underlying environment values are never included.
48
+
49
+ As a result:
50
+
51
+ - `console.log(paymentsEnv)` is safe.
52
+ - `util.inspect(paymentsEnv)` is safe.
53
+ - `` `${paymentsEnv}` `` is safe.
54
+ - `JSON.stringify(paymentsEnv)` is safe.
55
+
56
+ Explicit access to a known variable remains unchanged:
57
+
58
+ ```ts
59
+ paymentsEnv.STRIPE_KEY
60
+ ```
61
+
62
+ returns the validated, processed value required by application code.
63
+
64
+ The contract object is also frozen with `Object.freeze()` to prevent runtime
65
+ mutation of the redaction methods or replacement of the protected behavior.
66
+
67
+ ## Consequences
68
+
69
+ - **The safe path becomes easier than the unsafe path.**
70
+ Accidentally dumping an entire environment contract no longer exposes every
71
+ variable. Retrieving a secret requires an intentional property access to a
72
+ specific key rather than a generic object serialization.
73
+
74
+ - **Protection ends once a value is extracted.**
75
+ This design protects the contract object itself, not arbitrary values after
76
+ application code retrieves them.
77
+
78
+ For example:
79
+
80
+ ```ts
81
+ console.log({ key: paymentsEnv.STRIPE_KEY })
82
+ ```
83
+
84
+ intentionally creates a new object containing the secret. The package
85
+ cannot prevent application code from re-exposing values after extraction.
86
+
87
+ - **Processors and validators remain responsible for their own error
88
+ handling.**
89
+ If custom processing code includes sensitive values in thrown errors, such
90
+ as:
91
+
92
+ ```ts
93
+ throw new Error(`Invalid value: ${value}`)
94
+ ```
95
+
96
+ that information may appear in validation failures. The contract
97
+ redaction boundary cannot protect values that custom code has already
98
+ placed into an error message.
99
+
100
+ - **The design intentionally avoids turning environment access into a secret
101
+ management system.**
102
+ There is no `.reveal()`, `.unwrap()`, access auditing, or permission layer.
103
+ The goal is narrowly defined: prevent the most common accidental exposure
104
+ pattern while preserving normal developer ergonomics.
105
+
106
+ - **Per-variable access remains intentionally simple.**
107
+ Developers should not need additional ceremony for the normal case of
108
+ reading a required configuration value. Security is improved at the object
109
+ boundary without making legitimate access cumbersome.
110
+
111
+ ## Alternatives considered
112
+
113
+ - **A `Proxy`-based lazy contract with an explicit `.reveal()` or
114
+ `.unwrap()` method.**
115
+ Rejected. This adds API complexity and introduces a second access model
116
+ without meaningfully improving the primary protection target. The main
117
+ risk is accidental whole-object serialization, which the existing
118
+ inspection overrides already address.
119
+
120
+ - **Return a normal object and rely on documentation to prevent leaks.**
121
+ Rejected. A warning in documentation does not change the default behavior
122
+ of serialization. Since this package exists specifically around handling
123
+ sensitive configuration values, the safer default should be enforced by
124
+ the object design itself rather than developer discipline alone.
@@ -0,0 +1,109 @@
1
+ # 0007: Rename `transformer`/`Transformer` to `processor`/`Processor`
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `src/runtime/types.ts`, `src/runtime/validate.ts`,
6
+ `src/runtime/errors.ts`, `src/build/parse.ts`, `src/build/compatibility.ts`,
7
+ `src/build/docs.ts`, and `src/helpers/processors.ts`, and reflected
8
+ throughout the documentation and examples.
9
+
10
+ ## Context
11
+
12
+ The schema field responsible for turning a raw environment value into a
13
+ typed application value was originally named `transformer`, backed by a
14
+ `Transformer<T>` type (`(value: unknown) => T`). This mirrored the
15
+ terminology used by comparable environment-validation libraries, where the
16
+ job is described as reshaping a value from one type into another (e.g.
17
+ string to number).
18
+
19
+ In practice, this field is expected to do more than reshape a value's type.
20
+ It is the one place where a raw value should be turned into its final,
21
+ directly-usable form -- parsing a connection string into a `URL`, decoding a
22
+ token into its claims, resolving a reference into the actual secret,
23
+ splitting a delimited string into an array -- so that every consumer of the
24
+ resulting contract can use the value as-is, without re-deriving the same
25
+ result on every read. "Transform" describes a shape change; it does not
26
+ communicate that the output is meant to be the value's _final_ form,
27
+ computed once.
28
+
29
+ This mismatch was already visible inside the codebase itself:
30
+ `src/helpers/processors.ts` and its exported `processors` namespace
31
+ (`processors.url()`, `processors.number()`, ...) were named for the
32
+ finished-value contract from the start, and `helpers/index.ts`'s own
33
+ comments already described "processor/validator patterns." Only the
34
+ underlying schema field (`transformer:`) and its type (`Transformer<T>`)
35
+ had not caught up, so a developer writing `processor: processors.url()` --
36
+ correct under this decision -- previously had to write `transformer:
37
+ processors.url()`, bridging a naming gap between the helper they imported
38
+ and the field they assigned it to.
39
+
40
+ ## Decision
41
+
42
+ Rename the runtime vocabulary end to end:
43
+
44
+ - `Transformer<T>` (`src/runtime/types.ts`) → `Processor<T>`
45
+ - `EnvDefinition.transformer` → `EnvDefinition.processor`
46
+ - `VariableFailure.kind: "transformer"` → `"processor"`, and its formatted
47
+ heading, `"Transformer failed:"` → `"Processor failed:"`
48
+ - Build-time static-analysis fields (`src/build/parse.ts`): `hasTransformer`
49
+ → `hasProcessor`, `transformerSource` → `processorSource`,
50
+ `transformerReturnType` → `processorReturnType`
51
+ - The generated docs catalog line, `- Transformer: yes/no` → `- Processor:
52
+ yes/no`, and compatibility messages (`src/build/compatibility.ts`), e.g.
53
+ `"Processor return types are declared incompatible..."`
54
+ - All prose referencing the concept across `specs/architecture.md`, the
55
+ other ADRs, `README.md`, `SECURITY.md`, and the `examples/` schema files
56
+
57
+ The function signature is unchanged (`(value: unknown) => T`); this is a
58
+ vocabulary change, not a behavioral one. It exists to make the schema field
59
+ match the intent it was always meant to carry: produce a value that's ready
60
+ to use directly, computed once, rather than a value that merely has a
61
+ different shape than its input.
62
+
63
+ ## Consequences
64
+
65
+ - **This is a breaking API change.** Every existing `env.schema.ts` using
66
+ `transformer:` must rename that key to `processor:` before upgrading. The
67
+ value assigned to it (a plain `(value: unknown) => T` function, or a call
68
+ like `processors.url()`) does not need to change -- only the key name.
69
+
70
+ - **Naming is now consistent end to end.** The helper namespace
71
+ (`processors.url()`), the schema field (`processor:`), the runtime type
72
+ (`Processor<T>`), thrown error headings (`"Processor failed:"`), and
73
+ generated documentation (`- Processor: yes`) all describe the same
74
+ concept with the same word. A developer no longer has to translate
75
+ between "processor" (what they import) and "transformer" (what they
76
+ assign it to).
77
+
78
+ - **The name now sets the right expectation for schema authors.** A
79
+ `processor` reads as "produce the value this contract should expose,"
80
+ encouraging authors to do complete, one-time preparation (parsing,
81
+ decoding, resolving) in that function rather than a narrow coercion that
82
+ downstream code still has to finish preparing on every read. It also fits
83
+ naturally with per-capability ownership ([0003](0003-no-global-env-object.md)):
84
+ two capabilities can process the same raw variable into two different final
85
+ forms, each already finished, with no shared coercion step to agree on.
86
+
87
+ - **No change to `EnvDefinition`'s minimal vocabulary.** This rename does
88
+ not add, remove, or restructure fields -- `default`, `processor`, and
89
+ `validator` remain the whole runtime vocabulary described in
90
+ [0001](0001-runtime-documentation-separation.md).
91
+
92
+ ## Alternatives considered
93
+
94
+ - **Keep `transformer`, and only address the helpers naming.** Rejected:
95
+ the helpers module and its `processors` export were already named this
96
+ way; the mismatch this decision fixes is that the _schema field_ never
97
+ caught up, not the reverse.
98
+
99
+ - **Support both `transformer` and `processor` as accepted aliases.**
100
+ Rejected. `EnvDefinition`'s whole design principle is a minimal, explicit
101
+ vocabulary (see [0001](0001-runtime-documentation-separation.md)). A
102
+ synonym field would double the surface `validateEnv()` and the
103
+ build-time parser (`src/build/parse.ts`) both need to recognize,
104
+ indefinitely, for no runtime benefit.
105
+
106
+ - **Deprecate `transformer` and migrate over a transition window.**
107
+ Rejected. The package is pre-1.0 (`0.1.0`) with no external consumers
108
+ depending on the existing field name yet, so a direct rename is simpler
109
+ and cheaper than introducing, and later removing, a deprecation shim.
@@ -0,0 +1,173 @@
1
+ # 0008: A fixed gzip budget on the runtime and helpers entry points
2
+
3
+ ## Status
4
+
5
+ Accepted. Implemented in `ci/size-budgets.mjs`, run via `npm run size` and
6
+ wired into `prepublishOnly`, so it is enforced at publish time rather than
7
+ being an optional CI check a maintainer can ignore.
8
+
9
+ ## Amendment
10
+
11
+ The helpers budget is now **4096 bytes (4KB)**; the runtime's stays at 3KB. The budget was calibrated on
12
+ minified output, and the standard now forbids minified output (internal-package-contract's `NoMinify`
13
+ check), under which the same helpers gzip to about 3.2KB. This was a one-time recalibration to the new
14
+ baseline, recorded in `ci/size-budgets.mjs`, and not a loosening for growth. Where this record says both
15
+ entry points share the 3KB ceiling, read it as the original decision.
16
+
17
+ ## Context
18
+
19
+ `env-cap` makes a specific claim in its own architecture: the runtime
20
+ stays "small and stable" while documentation, discovery, and reporting live
21
+ in build-time tooling that never ships to an application (0001). That claim
22
+ only holds because of a second decision — there is no `/client` or `/server`
23
+ split (0004). One runtime implementation, exported from the package root,
24
+ is what every consumer imports, including code that ends up in a browser
25
+ bundle. There is no smaller, trimmed-down client package to fall back on if
26
+ the shared runtime grows. Whatever size `dist/index.js` and `dist/helpers.js`
27
+ are, that is the size every browser-bound feature pays.
28
+
29
+ Left unchecked, that size is just a sentence in a README. Runtime code
30
+ accretes for reasonable-sounding reasons — a clearer error message, an extra
31
+ option field, a convenience helper — and none of those changes look like
32
+ "bloat" in the PR that introduces them. Without an automated check, the only
33
+ way to notice the runtime had grown would be to manually gzip the build
34
+ output and compare it to a number nobody had written down, which is to say:
35
+ nobody would notice until a consumer complained about bundle size, by which
36
+ point the growth would already be load-bearing and hard to revert.
37
+
38
+ `ci/size-budgets.mjs` exists to make "the runtime stays small" a build
39
+ failure instead of a promise. The remaining question this decision addresses
40
+ is what the number should be, and specifically why it's 3KB gzipped rather
41
+ than something looser (5KB) or stricter (1KB).
42
+
43
+ ## Decision
44
+
45
+ `ci/size-budgets.mjs` gzips `dist/index.js` (the `.` entry point —
46
+ `createEnv`, `validateEnv`, error types, contract redaction) and
47
+ `dist/helpers.js` (the `./helpers` entry point — `processors`, `validators`)
48
+ and fails the build if either exceeds **3072 bytes (3KB) gzipped**. At the
49
+ time of writing, actual usage is 2081B (68% of budget) for the runtime and
50
+ 1030B (34% of budget) for helpers — both comfortably under, neither close to
51
+ the edge by accident.
52
+
53
+ `dist/build.js` and `dist/cli/index.js` are deliberately **not** budgeted.
54
+ They are Node-only, dev-time-only tooling (0002) — `build.js` alone is
55
+ ~53KB raw, almost an order of magnitude over the runtime's entire gzip
56
+ budget, because it embeds TypeScript-compiler-scale AST parsing that has no
57
+ reason to be small. That's fine, because it never runs inside an application
58
+ bundle; the tree-shaking and browser-platform-bundle tests are what
59
+ guarantee it stays isolated from `index.js`/`helpers.js`, not the size
60
+ budget. The size budget's job is narrower and more specific: bound exactly
61
+ the two artifacts that cross the boundary described in 0001 and 0004, and
62
+ nothing else.
63
+
64
+ ### Why not 1KB
65
+
66
+ A 1KB ceiling isn't stricter in any useful sense — it's already broken by
67
+ functionality the architecture is explicitly committed to, not by bloat.
68
+ The runtime's 2081B includes per-key lazy getters, `EnvNotReadyError`,
69
+ aggregated `EnvValidationError` (0005 requires collecting _every_ failure
70
+ rather than throwing on the first, which costs more code than a fail-fast
71
+ check would), and the `Symbol.for("nodejs.util.inspect.custom")` /
72
+ `toString()` / `toJSON()` overrides that make `console.log(contract)` safe
73
+ by default (0006). None of that is incidental — each piece is the direct
74
+ implementation of a numbered decision. Fitting inside 1KB would mean cutting
75
+ one of them to satisfy the budget, which is backwards: the budget is
76
+ supposed to protect the architecture, not force a rewrite of it. A ceiling
77
+ the intended design can't pass under normal operation isn't a guardrail,
78
+ it's noise a team learns to route around — either by routinely waiving it or
79
+ by quietly stripping the features that made the number fail in the first
80
+ place.
81
+
82
+ ### Why not 5KB
83
+
84
+ 5KB is loose enough to stop working as a forcing function. Measured against
85
+ today's actual size, a 5KB ceiling would leave roughly 4KB — about
86
+ two-thirds of the entire budget — as slack the check would never flag: room
87
+ enough to vendor a small validation dependency, inline logic that belongs in
88
+ `helpers` instead of the runtime core, or let the redaction/error-handling
89
+ code duplicate itself across a couple of code paths, all without the build
90
+ ever turning red. `env-cap`'s pitch is explicitly "no unnecessary
91
+ runtime complexity" (README) — the budget's entire job is to catch that kind
92
+ of drift automatically, before a maintainer has to notice it by hand in a
93
+ bundle analyzer. Note also that this was never primarily about shaving
94
+ load time in absolute terms: 3–5KB gzipped is negligible next to a typical
95
+ application bundle (hundreds of KB to several MB). The budget is a proxy for
96
+ "did the runtime's shape change," not a user-facing performance target — and
97
+ a looser number quietly stops measuring that, even while technically still
98
+ "passing."
99
+
100
+ ### Why 3KB
101
+
102
+ 3KB sits meaningfully above current usage — enough headroom (roughly 1KB
103
+ above the runtime's actual 2081B, about half again its current size) that
104
+ ordinary maintenance doesn't force a budget renegotiation on every PR. A new
105
+ processor, a clearer error message, an extra `CreateEnvOptions` field can
106
+ land without anyone touching `check-size.mjs`. But the amount of growth that
107
+ would exhaust that headroom — roughly 50% growth in a module whose entire
108
+ job is to stay minimal — is bigger than any single feature the runtime is
109
+ expected to gain at once. Hitting the ceiling is meant to prompt a question
110
+ ("does this belong in the runtime, or in `helpers`/`build`/`documentEnv()`
111
+ metadata?"), not a reflex to raise the number.
112
+
113
+ The same 3KB ceiling is applied to both entry points rather than tuning two
114
+ separate numbers per module. That's intentional, not laziness: `helpers`
115
+ (processors/validators) is optional sugar most contracts don't even import,
116
+ so it earns no larger allowance than the runtime core every contract
117
+ depends on. One number, applied uniformly, also keeps the check itself
118
+ trivial to read and hard to quietly special-case.
119
+
120
+ ## Consequences
121
+
122
+ - **"The runtime stays small" has teeth.** `npm run size` — and by
123
+ extension `prepublishOnly` — fails the build the moment either entry
124
+ point crosses 3072 bytes gzipped, turning the Consequences section of
125
+ 0001 from a claim into an enforced property of every published release.
126
+
127
+ - **The check is self-explanatory.** `ci/size-budgets.mjs` prints the
128
+ measured gzip size against the fixed budget for both entry points, so a
129
+ contributor who trips it sees exactly how much they added and against
130
+ what limit, without needing to consult this document to understand what
131
+ "too big" means.
132
+
133
+ - **The number is calibrated to the implementation, not to an external
134
+ performance target.** 3KB was not derived from a Core Web Vitals
135
+ threshold or a competitive benchmark against other environment-validation
136
+ libraries; it was set relative to what the intended architecture actually
137
+ costs today, plus deliberate headroom. If the runtime's legitimate,
138
+ necessary scope grows substantially, the budget will need a conscious
139
+ revision — that's an accepted cost, preferable to a budget that's either
140
+ unenforceable (1KB) or too loose to catch drift (5KB).
141
+
142
+ - **Genuinely necessary growth can still hit the ceiling.** A contributor
143
+ adding a real, justified few hundred bytes may need to trim elsewhere or
144
+ open a follow-up decision to raise the budget rather than merging past it
145
+ silently. That friction is the point, not a flaw to design around.
146
+
147
+ ## Alternatives considered
148
+
149
+ - **No automated budget; rely on code review to notice growth.**
150
+ Rejected. Growth by a hundred bytes at a time across many reasonable-
151
+ looking PRs is exactly what review reliably misses. Nothing would catch a
152
+ single large accidental addition (an inlined dependency, a duplicated
153
+ utility) until a consumer noticed the bundle size themselves.
154
+
155
+ - **One shared budget across all four `dist` outputs
156
+ (`index.js`, `helpers.js`, `build.js`, `cli/index.js`).**
157
+ Rejected. This conflates dev-time-only Node tooling — which already
158
+ depends on TypeScript-compiler-scale machinery per 0002 — with the two
159
+ artifacts that actually ship to applications. A shared number would
160
+ either force the CLI to be unrealistically small or let the runtime hide
161
+ its growth inside a much larger combined ceiling.
162
+
163
+ - **A raw-byte budget instead of gzip.**
164
+ Rejected. Gzip (or an equivalent) is what actually crosses the network
165
+ for essentially every real consumer — bundlers and CDNs compress by
166
+ default — so it's the more accurate proxy for real-world cost, and it's
167
+ the unit comparable packages conventionally report their size in.
168
+
169
+ - **A budget expressed as a percentage of a typical application bundle.**
170
+ Rejected. That number depends on the size of a consuming application's
171
+ own bundle, which `env-cap` has no visibility into and no control
172
+ over. An absolute gzip ceiling is the only kind of budget the package
173
+ itself can actually own and enforce.