@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
package/GUIDE.md ADDED
@@ -0,0 +1,1214 @@
1
+ # env-cap Guide
2
+
3
+ The reference manual: capability-owned contracts in depth, the full generate/validate workflow, validation contexts, reusable packages, tsconfig path aliases, runtime/build-time architecture, migration notes, the security model, troubleshooting, the CLI, the GitHub Action, the ESLint plugin, and performance characteristics.
4
+
5
+ For the pitch, quick start, and adoption reasoning, see [README.md](README.md). For why the package is built the way it is, see [specs/architecture.md](specs/architecture.md) and the [ADRs](specs/decisions/).
6
+
7
+ - [Documented example](#documented-example)
8
+ - [Capability-owned contracts](#capability-owned-contracts)
9
+ - [Helpers](#helpers)
10
+ - [Core workflow](#core-workflow)
11
+ - [Runtime support matrix](#runtime-support-matrix)
12
+ - [Validation contexts](#validation-contexts)
13
+ - [Reusable packages](#reusable-packages)
14
+ - [TypeScript path aliases (paths/baseUrl)](#typescript-path-aliases-pathsbaseurl)
15
+ - [Architecture](#architecture)
16
+ - [Migration](#migration)
17
+ - [Security model](#security-model)
18
+ - [Troubleshooting](#troubleshooting)
19
+ - [CLI](#cli)
20
+ - [GitHub Action](#github-action)
21
+ - [ESLint plugin](#eslint-plugin)
22
+ - [Performance characteristics](#performance-characteristics)
23
+
24
+ ## Documented example
25
+
26
+ Most applications start with a centralized environment configuration model:
27
+
28
+ ```ts
29
+ // src/env.ts
30
+
31
+ import { createEnv } from "@maverickcer/env-cap"
32
+
33
+ const schema = {
34
+ DATABASE_URL: {
35
+ validator(value: string) {
36
+ return value.startsWith("postgres://") || "Expected a PostgreSQL connection string."
37
+ },
38
+ },
39
+
40
+ STRIPE_KEY: {
41
+ validator(value: string) {
42
+ return value.startsWith("sk_") || 'Expected a Stripe secret key starting with "sk_".'
43
+ },
44
+ },
45
+
46
+ SENDGRID_API_KEY: {
47
+ validator(value: string) {
48
+ return value.startsWith("SG.") || "Expected a SendGrid API key."
49
+ },
50
+ },
51
+ }
52
+
53
+ export const env = createEnv(schema)
54
+ ```
55
+
56
+ This approach works well while one application owns all configuration decisions.
57
+
58
+ As applications grow, the challenge becomes understanding the relationship between configuration and the capabilities that depend on it:
59
+
60
+ - Which feature requires `STRIPE_KEY`?
61
+ - Can this variable be removed when a feature is removed?
62
+ - Who owns its rotation?
63
+ - Which service depends on this secret?
64
+ - Is this configuration still required?
65
+
66
+ `env-cap` can move those contracts closer to the capabilities that consume them, while still generating a complete application-wide view when teams need operational visibility.
67
+
68
+ ## Capability-owned contracts
69
+
70
+ Each capability defines its own environment requirements while the application can still generate a complete project-wide view.
71
+
72
+ ```ts
73
+ // features/payments/env.schema.ts
74
+
75
+ import { createEnv, documentEnv } from "@maverickcer/env-cap"
76
+
77
+ const paymentsSchema = {
78
+ STRIPE_KEY: {
79
+ validator(value: string) {
80
+ return value.startsWith("sk_") || 'Expected a Stripe secret key starting with "sk_".'
81
+ },
82
+ },
83
+ }
84
+
85
+ export const paymentsEnv = createEnv(paymentsSchema, {
86
+ name: "payments",
87
+ })
88
+
89
+ documentEnv(paymentsSchema, {
90
+ category: "Payments",
91
+ owner: "payments-team",
92
+ metadata: {
93
+ service: "Payment Processing API",
94
+ criticality: "Production-critical",
95
+ },
96
+ variables: {
97
+ STRIPE_KEY: {
98
+ description:
99
+ "Stripe secret API key used by the payment service to create charges and process refunds.",
100
+ owner: "payments-team",
101
+ expiresAt: "2027-01-01",
102
+ refreshInstructions: "Rotate in AWS Secrets Manager, then redeploy. Rotate every 90 days.",
103
+ sensitivity: "secret",
104
+ metadata: {
105
+ storageProvider: "AWS Secrets Manager",
106
+ accessPolicy: "Restricted to payment service runtime credentials.",
107
+ validationReason:
108
+ "Ensures the payment service cannot start with missing or malformed Stripe credentials.",
109
+ },
110
+ },
111
+ },
112
+ })
113
+ ```
114
+
115
+ The application still receives one validated startup boundary:
116
+
117
+ ```ts
118
+ await validateEnv({
119
+ manifest,
120
+ values: process.env,
121
+ })
122
+ ```
123
+
124
+ But ownership follows usage:
125
+
126
+ ```ts
127
+ paymentsEnv.STRIPE_KEY
128
+ ```
129
+
130
+ The capability that owns the dependency owns access to it. There is no global configuration object requiring every capability to access configuration through a centralized namespace:
131
+
132
+ ```ts
133
+ env.payments.STRIPE_KEY
134
+ ```
135
+
136
+ Instead, each capability exposes only the configuration it owns.
137
+
138
+ At application startup, `validateEnv()` provides fail-fast verification across the complete application when paired with a generated manifest:
139
+
140
+ ```ts
141
+ import { validateEnv } from "@maverickcer/env-cap"
142
+ import { manifest } from "./generated/env.manifest"
143
+
144
+ await validateEnv({
145
+ manifest,
146
+ values: process.env,
147
+ })
148
+ ```
149
+
150
+ The generated manifest provides a complete project-wide view without requiring runtime centralization. `validateEnv()` discovers every registered capability contract, validates required environment dependencies before the application serves traffic, and aggregates failures into a single validation error.
151
+
152
+ This allows teams to maintain local ownership while preserving operational visibility:
153
+
154
+ - Missing variables are detected before the application serves traffic.
155
+ - Invalid values across multiple capabilities are reported together instead of failing one at a time.
156
+ - Each capability retains ownership of its validation rules.
157
+ - Operations teams maintain visibility into application-wide configuration requirements.
158
+
159
+ Runtime access remains capability-scoped, while validation remains application-wide.
160
+
161
+ ## Helpers
162
+
163
+ `@maverickcer/env-cap/helpers` provides optional convenience functions for common processor and validator patterns.
164
+
165
+ Helpers are intentionally not the core `env-cap` workflow. They are provided for smaller applications, prototypes, and straightforward configuration requirements where a lightweight convenience API is useful.
166
+
167
+ Already using Zod, envalid, or another validation library? Keep it and integrate it directly with env-cap contracts — helpers exist for when a lighter API is enough, not as a reason to switch.
168
+
169
+ ```ts
170
+ import { createEnv } from "@maverickcer/env-cap"
171
+ import { processors, validators } from "@maverickcer/env-cap/helpers"
172
+
173
+ export const databaseEnv = createEnv(
174
+ {
175
+ DATABASE_URL: {
176
+ processor: processors.toURL(),
177
+ validator: validators.required(),
178
+ },
179
+
180
+ PORT: {
181
+ default: 5432,
182
+ processor: processors.toNumber(),
183
+ validator: validators.range(1, 65535),
184
+ },
185
+ },
186
+ {
187
+ name: "database",
188
+ },
189
+ )
190
+ ```
191
+
192
+ Available helpers include common processors and validators with composition utilities. They can be
193
+ found at [src/helpers/index.ts](https://github.com/MaverickCER/env-cap/blob/main/src/helpers/index.ts)
194
+
195
+ When possible, prefer validation rules that communicate domain intent directly alongside the capability contract. These may be custom `Processor<T>` and `Validator<T>` functions or existing validators from your application's validation stack.
196
+
197
+ ```ts
198
+ validator(value: string) {
199
+ return value.startsWith("sk_") ||
200
+ 'Expected a Stripe secret key starting with "sk_".';
201
+ }
202
+ ```
203
+
204
+ A named validation rule explains why the dependency exists and gives future maintainers context that a generic helper cannot always provide.
205
+
206
+ The helper package is optional and has no impact on the core runtime when unused. When all runtime features are included, the runtime entry point remains within its 3 KB gzip budget and `./helpers` within its 4 KB one. `createEnv()` and `validateEnv()` remain the core APIs and provide the foundation for capability-owned configuration, while helpers provide convenient building blocks for common processor and validator patterns.
207
+
208
+ ## Core workflow
209
+
210
+ ### 1. Define your environment contract
211
+
212
+ `env-cap` works with both centralized configuration and capability-owned contracts.
213
+
214
+ For existing applications, start by wrapping your current environment requirements:
215
+
216
+ ```ts
217
+ import { createEnv } from "@maverickcer/env-cap"
218
+
219
+ export const env = createEnv(
220
+ {
221
+ DATABASE_URL: {
222
+ validator(value: string) {
223
+ return value.startsWith("postgres://") || "Expected a PostgreSQL connection string."
224
+ },
225
+ },
226
+ PORT: {
227
+ default: 3000,
228
+ processor(value: string) {
229
+ return Number(value)
230
+ },
231
+ },
232
+ },
233
+ {
234
+ name: "application",
235
+ },
236
+ )
237
+ ```
238
+
239
+ As applications grow, contracts can move closer to the capabilities that consume them:
240
+
241
+ ```text
242
+ src/
243
+ ├── features/
244
+ │ ├── payments/
245
+ │ │ └── env.schema.ts
246
+ │ ├── database/
247
+ │ │ └── env.schema.ts
248
+ │ └── notifications/
249
+ │ └── env.schema.ts
250
+ ```
251
+
252
+ A capability can also be a reusable package:
253
+
254
+ ```text
255
+ packages/
256
+ └── paypal-addon/
257
+ └── src/env.schema.ts
258
+ ```
259
+
260
+ The ownership model is identical whether the contract belongs to the application, an internal package, or a published dependency.
261
+
262
+ ### 2. Generate the project view
263
+
264
+ During development or CI:
265
+
266
+ ```ts
267
+ import { generateEnvManifest } from "@maverickcer/env-cap/build"
268
+
269
+ await generateEnvManifest({
270
+ location: "src/generated/env.manifest.ts",
271
+ })
272
+ ```
273
+
274
+ The build process creates the application-wide view required for:
275
+
276
+ - environment manifests
277
+ - documentation
278
+ - `.env.example` files
279
+ - configuration reports
280
+
281
+ Every one of these draws a hard line between **declared** facts (author
282
+ metadata — `owner`, `sensitivity`, `expiresAt`, `retention` — presence is
283
+ checked, correctness never is) and **proven** facts (AST-derived —
284
+ `UNCONSUMED_OWNED_VARIABLE`, the dependency graph). See
285
+ [`specs/generated-artifacts.md`](specs/generated-artifacts.md) for the full
286
+ list of what's generated today, the seven canonical fact models each one
287
+ projects from, and what's deliberately deferred.
288
+
289
+ Schemas are analyzed statically.
290
+
291
+ They are never imported or executed during discovery.
292
+
293
+ This provides project-wide visibility without requiring runtime configuration to become centralized.
294
+
295
+ #### Change tracking via the persisted evidence artifact
296
+
297
+ `generateEnvManifest()` no longer tracks its own change history — that moved to a separate, optional
298
+ artifact: the full `EvidenceModel`, env-cap's canonical fact model covering the contract graph,
299
+ dependency/ownership findings, lifecycle data, and a change report diffed against whatever was
300
+ previously persisted. `generateEnvArtifacts()` always computes it; passing `evidence` also writes it
301
+ to disk:
302
+
303
+ ```ts
304
+ const result = await generateEnvArtifacts({
305
+ manifest: { location: "src/generated/env.manifest.ts" },
306
+ evidence: { location: "docs/env.evidence.json" },
307
+ })
308
+
309
+ console.log(result.evidence.change.manifest.addedVariables) // newly documented this run
310
+ console.log(result.evidence.change.manifest.updatedVariables) // field-level before/after for anything that changed
311
+ console.log(result.evidence.change.manifest.removedVariables) // no longer discovered at all
312
+ ```
313
+
314
+ `evidence.location` is independent of `manifest.location` — requesting it needs no other pass, and a
315
+ project with no `.ts` manifest at all can still generate a pure evidence report. Writing it also
316
+ writes a paired `docs/env.evidence.json.fingerprint` sidecar, a cheap content hash a later read
317
+ (`getEvidenceModel()`, for a report/projection script that doesn't want to pay for a full recompute
318
+ on every invocation) uses to skip regenerating when nothing relevant has changed.
319
+
320
+ **Commit both files, the same as you already commit `env.manifest.ts` itself.** "Since last
321
+ execution" means since the last commit on your branch — that's what makes the diff meaningful in CI and
322
+ reviewable in a pull request, not just a local curiosity. See
323
+ [ADR 0038](specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md) for the
324
+ full reasoning (superseding [ADR 0021](specs/decisions/0021-manifest-change-report-persisted-snapshot.md)'s
325
+ original manifest-adjacent design).
326
+
327
+ - **A diff is expected** any time a `documentEnv()` call's `description`/`owner`/`expiresAt`/
328
+ `refreshInstructions`/`required`/`extra` changes, or a contract's `active`/`category`/`exclusiveGroup`
329
+ changes — anything that isn't schema shape itself.
330
+ - **Regeneration is automatic.** Every `generate:env`/CI run that passes `--evidence` already
331
+ rewrites both files; there's no separate "update the snapshot" step to remember.
332
+ - **A diff signals real drift worth a second look** when it shows up somewhere nobody meant to touch —
333
+ an `updatedVariables` entry for a variable nobody intended to edit, or an `addedContracts`/
334
+ `removedContracts` entry from a change that was supposed to be unrelated.
335
+
336
+ The CLI's normal (non-`--check`) output prints the same summary as an "Evidence changes since the
337
+ last persisted snapshot" section whenever `--evidence <path>` is passed; run with `--json --evidence
338
+ <path>` for the same data in machine-readable form.
339
+
340
+ Separately, when two _active_ contracts document the same variable key with different metadata (e.g. two
341
+ features that happen to reuse a name, each with its own `description`/`owner`), that's reported as a
342
+ `duplicate-variable-documentation` warning in `result.warnings` — always a warning, never a hard error
343
+ (static analysis can't prove two descriptions are "wrong," only different), gated by the same
344
+ `onIncompatibility` option as every other compatibility warning.
345
+
346
+ ### 3. Validate once during startup
347
+
348
+ ```ts
349
+ import { validateEnv } from "@maverickcer/env-cap"
350
+ import { manifest } from "./generated/env.manifest"
351
+
352
+ await validateEnv({
353
+ manifest,
354
+ values: process.env,
355
+ })
356
+ ```
357
+
358
+ At startup, `validateEnv()` verifies the complete application environment boundary.
359
+
360
+ After validation:
361
+
362
+ ```ts
363
+ env.DATABASE_URL
364
+ ```
365
+
366
+ or:
367
+
368
+ ```ts
369
+ paymentsEnv.STRIPE_KEY
370
+ ```
371
+
372
+ returns the processed value according to the contract that owns it.
373
+
374
+ Before validation completes:
375
+
376
+ ```ts
377
+ paymentsEnv.STRIPE_KEY
378
+ ```
379
+
380
+ throws:
381
+
382
+ ```ts
383
+ EnvNotReadyError
384
+ ```
385
+
386
+ Validation failures are aggregated:
387
+
388
+ ```ts
389
+ EnvValidationError
390
+ ```
391
+
392
+ so applications receive the complete startup failure state instead of discovering missing or invalid variables one at a time.
393
+
394
+ Runtime access can remain centralized for simpler applications or become capability-scoped as ownership boundaries grow. Validation remains application-wide.
395
+
396
+ `validateEnv()` is idempotent for the life of the process: the first call's outcome (success or `EnvValidationError`) is cached and returned by every later call, without re-running any processor or validator — by design, since a real application validates once at startup and every later read should see that same, stable outcome. A test suite or a script that intentionally validates different `values` in the same process (as opposed to a real app's single startup call) needs `resetEnvCache()` between runs:
397
+
398
+ ```ts
399
+ import { resetEnvCache, validateEnv } from "@maverickcer/env-cap"
400
+
401
+ await validateEnv({ manifest, values: scenarioA })
402
+ resetEnvCache()
403
+ await validateEnv({ manifest, values: scenarioB }) // re-runs validation from scratch
404
+ ```
405
+
406
+ Without it, a second `validateEnv()` call with different `values` silently returns the first run's cached result instead of re-validating.
407
+
408
+ ## Runtime support matrix
409
+
410
+ | Environment | `.` (runtime) | `./helpers` | `./build` (CLI/tooling) |
411
+ | -------------------------------------------------------------- | ----------------------------- | ----------- | ------------------------------------------------------------- |
412
+ | Node.js 22+ (CJS or ESM) | ✅ | ✅ | ✅ |
413
+ | Browser bundle (Webpack/Vite/esbuild/etc.) | ✅ | ✅ ¹ | ❌ not applicable — build-only, never bundle this into an app |
414
+ | Edge/serverless (Cloudflare Workers, Vercel Edge, Deno Deploy) | ✅ | ✅ ¹ | ❌ not applicable |
415
+ | Bun | ✅ (conformance-tested in CI) | ✅ | ✅ |
416
+ | Deno | ✅ (conformance-tested in CI) | ✅ | ✅ |
417
+
418
+ ¹ Except `processors.base64()`, which returns a Node `Buffer`: use it only where `Buffer` exists, or decode with your own processor elsewhere.
419
+
420
+ The runtime (`.` and `./helpers`) has zero dependencies, never touches the filesystem, and never imports a Node module (the one Node global it uses is the `Buffer` that `processors.base64()` returns) — see [`specs/architecture.md`](specs/architecture.md). `./build` is Node-only developer tooling (uses `node:path` and the TypeScript compiler API — never `node:fs`, see [ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md)) meant for CI/npm-script use, never for shipping to a browser. Both ESM and CommonJS builds are published for every entry point (`package.json#exports`).
421
+
422
+ ### Requirements
423
+
424
+ Node.js `>=22`. TypeScript 5, 6 or 7 is only required for build-time manifest generation: a bundled TypeScript 6 parses the schemas when yours is 7, is bundled inside the package and used only by the build entry, and adds about 24 MB unpacked to the install. The runtime works in plain JavaScript. TypeScript consumers need `moduleResolution` set to `node16`, `nodenext` or `bundler` to resolve the subpath exports (`./build`, `./helpers`, ...); the legacy `node10` resolver is not supported. `@maverickcer/env-cap/eslint-plugin` also needs `@typescript-eslint/utils` installed (an optional peer).
425
+
426
+ ## Validation contexts
427
+
428
+ A schema entry may declare which **validation context** it belongs to. `validateEnv()` accepts the validation
429
+ contexts active for a given run, and skips every variable that doesn't match:
430
+
431
+ ```ts
432
+ DATABASE_URL: {
433
+ context: "server",
434
+ validator: validators.required(),
435
+ }
436
+ ```
437
+
438
+ ```ts
439
+ await validateEnv({
440
+ manifest,
441
+ values: process.env,
442
+ activeContexts: ["server"],
443
+ })
444
+ ```
445
+
446
+ **Matching rule:** a variable with no `context` participates in every run. A variable with a `context`
447
+ participates only when `activeContexts` contains that exact string — no prefix matching, wildcards, or
448
+ hierarchy. A skipped variable never runs its `default`/`processor`/`validator`, and reading it throws
449
+ `EnvNotReadyError`, exactly as if `validateEnv()` had never run for it.
450
+
451
+ `context` is entirely application-defined — env-cap never interprets, detects, or infers it. `"server"` and
452
+ `"client"` are just one example; a validation context can represent anything a validation run needs to
453
+ distinguish:
454
+
455
+ ```ts
456
+ DATABASE_URL: { context: "server", validator: validators.required() }
457
+ STRIPE_LIVE_KEY: { context: "production", validator: validators.required() }
458
+ QUEUE_CONCURRENCY: { context: "worker", default: 4 }
459
+ DEBUG_TRACE_ENDPOINT: { context: "development" }
460
+ ```
461
+
462
+ A run may activate more than one context at once — `activeContexts: ["server", "production"]` matches a
463
+ variable declaring either. This works the same regardless of framework: `env-cap` never inspects `window` or
464
+ `NODE_ENV` itself, the application computes `activeContexts` once, explicitly, before calling `validateEnv()`:
465
+
466
+ ```ts
467
+ // Works the same in a Next.js, TanStack Start, or plain Node app -- env-cap
468
+ // never inspects window/NODE_ENV itself; the application does, once, before
469
+ // calling validateEnv().
470
+ await validateEnv({
471
+ values: typeof window === "undefined" ? process.env : window.__ENV__,
472
+ manifest,
473
+ activeContexts: [
474
+ typeof window === "undefined" ? "server" : "client",
475
+ process.env.NODE_ENV === "production" ? "production" : "development",
476
+ ],
477
+ })
478
+ ```
479
+
480
+ When at least one variable declares a `context`, the generated manifest also exports every context it found,
481
+ named to match `activeContexts` itself so it can be passed straight through:
482
+
483
+ ```ts
484
+ // src/generated/env.manifest.ts (generated)
485
+ export const activeContexts = ["client", "server"]
486
+ export const manifest = [/* ... */]
487
+ ```
488
+
489
+ ```ts
490
+ import { activeContexts, manifest } from "./generated/env.manifest"
491
+
492
+ await validateEnv({ manifest, values: process.env, activeContexts })
493
+ ```
494
+
495
+ This is every context the manifest has — a convenient starting point, not a pre-scoped default. Importing it
496
+ unmodified into every process defeats the point of scoping contexts per deployment target in the first place;
497
+ narrow it (or import it under another name and filter it) the same way `src/server.ts`/`src/client.ts` in
498
+ [`test/integration/positive/team/validation-contexts`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/team/validation-contexts)
499
+ each hand-write their own narrowed `activeContexts: ["server"]` / `["client"]` instead of using this
500
+ export directly.
501
+
502
+ > **Validation contexts are not a bundling or security boundary, and not authorization.** They control whether
503
+ > `validateEnv()` processes a variable — nothing else. Putting a `context: "server"` variable in the same
504
+ > schema as `context: "client"` variables, feeding one manifest that a client bundle imports, does **not**
505
+ > keep the server-context variable's definition (including any literal `default`) out of that bundle —
506
+ > `activeContexts` filtering happens after the schema is already wherever it's going to be. If a variable must
507
+ > never reach a browser bundle at all, keep using separate discovery/generated manifests per contract (see
508
+ > ["Runtime and build-time are intentionally separate"](#architecture)
509
+ > and [ADR 0004](specs/decisions/0004-no-client-server-package-split.md)) — validation contexts are a
510
+ > complement to that boundary, not a replacement for it. Likewise, a string like `context: "admin"` does not
511
+ > restrict _who_ can read a value; it only decides whether a given run validates it. See
512
+ > [ADR 0022](specs/decisions/0022-validation-contexts.md) for the full set of invariants this feature commits to.
513
+
514
+ ## Reusable packages
515
+
516
+ A configuration contract can ship as its own installable package instead of living only inside the consuming application's source tree.
517
+
518
+ This works for both centralized application schemas and capability-owned contracts. A reusable package can expose the environment requirements it owns, allowing consuming applications to validate and generate visibility artifacts without manually copying configuration definitions.
519
+
520
+ See [`test/integration/positive/enterprise/paypal-addon`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/paypal-addon)/[`test/integration/positive/enterprise/paypal-consumer`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/paypal-consumer) for a complete, runnable example (see [`examples/`](examples/) for the three flagship, human-facing examples, and [`test/integration/`](https://github.com/MaverickCER/env-cap/tree/main/test/integration) for every other runnable scenario).
521
+
522
+ Discovery still never walks `node_modules` during its general file-discovery pass (`generateEnvManifest()`'s `include`/`exclude` globs), and that guarantee is unconditional.
523
+
524
+ Making a package-shipped contract discoverable is an opt-in mechanism (see [`VERSIONING.md`](VERSIONING.md) and [ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md)):
525
+
526
+ ```ts
527
+ // consuming app's build script
528
+ await generateEnvArtifacts({
529
+ packages: ["@acme/payments-sdk"], // explicit allowlist -- never implicit
530
+ manifest: { location: "src/env.manifest.ts" },
531
+ })
532
+ ```
533
+
534
+ The publishing package takes on two obligations:
535
+
536
+ 1. Declare `"envCap": { "schema": "./src/env.schema.ts" }` in its own `package.json`, pointing at its real, uncompiled `.ts` source (ship that file via `"files": ["dist", "src/env.schema.ts"]` alongside the compiled `dist/` used at runtime).
537
+
538
+ 2. Re-export the `createEnv()`-produced contract under the same name from its main entry point, so:
539
+
540
+ ```ts
541
+ import { paypalEnv } from "@acme/paypal-addon"
542
+ ```
543
+
544
+ resolves to the same contract discovered during build-time analysis.
545
+
546
+ Resolution never calls `readdir` on `node_modules` — it reads exactly one `package.json` per allow-listed package to find the declared field, then exactly one declared file, validated (path, extension, symlink target, size) before it is parsed.
547
+
548
+ See `SECURITY.md`'s "Avoids unnecessary traversal of dependency directories" section for the exact bounds.
549
+
550
+ ### Documenting a variable a package already explains
551
+
552
+ A variable can be declared in the package's contract and again in the application that consumes it. The application
553
+ does not repeat the explanation: it names the variable with only what is its own, and every field it leaves unset is
554
+ filled from the package's declaration.
555
+
556
+ ```ts
557
+ const credentials = { PAYPAL_CLIENT_SECRET: { default: "", validator: () => true } }
558
+ export const credentialsEnv = createEnv(credentials, { name: "credentials" })
559
+
560
+ documentEnv(credentials, {
561
+ variables: { PAYPAL_CLIENT_SECRET: { expiresAt: "2027-01-01", owner: "payments" } },
562
+ })
563
+ ```
564
+
565
+ Both declarations then report the package's `description`, `sensitivity` and `refreshInstructions` together with the
566
+ application's `expiresAt` and `owner`. A field the application sets itself is never replaced, and a field both set to
567
+ different values is reported as `DUPLICATE_VARIABLE_DOCUMENTATION`. Two of the application's own contracts never fill
568
+ each other (a service that can run on either of two databases documents each one's variable for itself); a field
569
+ both set differently is still reported. See
570
+ [ADR 0050](specs/decisions/0050-a-variable-declared-twice-is-documented-once.md).
571
+
572
+ ## TypeScript path aliases (paths/baseUrl)
573
+
574
+ If your project organizes its own source with a `tsconfig.json` path alias (`"@/lib/env"`, `"~/schema/env"`, ...), `env-cap` resolves it automatically — no configuration required:
575
+
576
+ ```ts
577
+ // tsconfig.json
578
+ { "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }
579
+ ```
580
+
581
+ ```ts
582
+ // src/consumer.ts
583
+ import { paymentsEnv } from "@/features/payments/env.schema.js"
584
+ paymentsEnv.STRIPE_KEY
585
+ ```
586
+
587
+ Without this, a contract only ever imported through an alias would be misreported as `abandoned` in the Dependency & Ownership Report, or its `documentEnv()` call left unlinked — the same class of false positive [ADR 0010](specs/decisions/0010-dependency-ownership-engine-scope-boundary.md)'s ownership engine exists to avoid.
588
+
589
+ See [`test/integration/positive/enterprise/tsconfig-aliases`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/tsconfig-aliases) for a complete, runnable example, and [`test/integration/positive/enterprise/tsconfig-aliases-consumer`](https://github.com/MaverickCER/env-cap/tree/main/test/integration/positive/enterprise/tsconfig-aliases-consumer) for the same producer/consumer pairing [Reusable packages](#reusable-packages) uses — proving this composes correctly with cross-package discovery (ADR 0014) in one real install (see [`examples/`](examples/) for the three flagship, human-facing examples, and [`test/integration/`](https://github.com/MaverickCER/env-cap/tree/main/test/integration) for every other runnable scenario).
590
+
591
+ Unlike [Reusable packages](#reusable-packages) above, this is on by default (see [`VERSIONING.md`](VERSIONING.md) and [ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md)): a project's own `tsconfig.json` never crosses a trust/versioning boundary the way an installed package does, so there's no safety reason to require opt-in. `env-cap` auto-detects `tsconfig.json` at `root`, exactly (no upward directory search, unlike bare `tsc`). Pass `tsconfig: "<path>"` to point at a different file (useful in monorepos where the relevant config isn't at `root`), or `tsconfig: false` to disable alias resolution entirely:
592
+
593
+ ```ts
594
+ await generateEnvArtifacts({
595
+ tsconfig: "tsconfig.build.json", // or `false` to disable
596
+ manifest: { location: "src/env.manifest.ts" },
597
+ })
598
+ ```
599
+
600
+ The actual `paths`/`baseUrl` matching is delegated entirely to the TypeScript compiler (`ts.resolveModuleName()`, the same function `tsc`/`tsserver` themselves use), never resolves into `node_modules` (that boundary stays exclusively [ADR 0014](specs/decisions/0014-cross-package-schema-discovery.md)'s), and only ever resolves to a real `.ts`/`.tsx` file.
601
+
602
+ ## Architecture
603
+
604
+ ### Runtime and build-time are intentionally separate
605
+
606
+ `env-cap` separates application execution from project-wide analysis.
607
+
608
+ ```text
609
+ Environment contract
610
+ |
611
+ |
612
+ +----+----+
613
+ | |
614
+ Runtime Build-time
615
+ | |
616
+ createEnv AST analysis
617
+ | |
618
+ validateEnv generate artifacts
619
+ |
620
+ Typed access
621
+ ```
622
+
623
+ Runtime:
624
+
625
+ - validates configuration
626
+ - exposes typed values
627
+ - contains no filesystem access
628
+ - does not discover files dynamically
629
+
630
+ Build-time:
631
+
632
+ - discovers contracts
633
+ - generates documentation
634
+ - creates manifests and operational visibility artifacts
635
+
636
+ This separation keeps application startup deterministic while allowing development and platform workflows to understand the complete configuration surface.
637
+
638
+ A project can begin with a centralized environment contract and adopt capability-owned contracts where ownership boundaries provide value. The runtime model remains the same: contracts define validated access, while build-time tooling provides application-wide visibility.
639
+
640
+ For the reasoning behind capability-owned configuration — code ownership, reusable packages, and platform visibility without runtime centralization — see [Why capability ownership?](https://maverickcer.github.io/env-cap/#why-context) on the website, and [specs/architecture.md](specs/architecture.md) for the full technical treatment.
641
+
642
+ ## Migration
643
+
644
+ `env-cap` is designed for incremental adoption.
645
+
646
+ Keep your existing tools and validation approach. Introduce contracts where they provide value, then move toward stronger ownership boundaries as your application grows.
647
+
648
+ ### From dotenv
649
+
650
+ Continue loading variables with dotenv.
651
+
652
+ Add validated contracts on top:
653
+
654
+ ```ts
655
+ import { createEnv } from "@maverickcer/env-cap"
656
+
657
+ export const env = createEnv({
658
+ DATABASE_URL: {
659
+ validator(value: string) {
660
+ return value.startsWith("postgres://") || "Expected a PostgreSQL connection string."
661
+ },
662
+ },
663
+ })
664
+ ```
665
+
666
+ No loader replacement is required.
667
+
668
+ ### From process.env
669
+
670
+ Replace scattered access:
671
+
672
+ ```ts
673
+ process.env.STRIPE_KEY
674
+ ```
675
+
676
+ with validated contract access:
677
+
678
+ ```ts
679
+ env.STRIPE_KEY
680
+ ```
681
+
682
+ As ownership boundaries become useful, contracts can move closer to the capabilities that consume them:
683
+
684
+ ```ts
685
+ paymentsEnv.STRIPE_KEY
686
+ ```
687
+
688
+ ### From Zod, envalid, or t3-env
689
+
690
+ Keep your existing validation logic.
691
+
692
+ `env-cap` organizes configuration ownership, lifecycle visibility, and application-wide validation boundaries; it does not replace specialized validation libraries.
693
+
694
+ Existing validators can be integrated directly:
695
+
696
+ ```ts
697
+ validator(value) {
698
+ return existingValidator(value) || "Invalid value";
699
+ }
700
+ ```
701
+
702
+ No large rewrite is required.
703
+
704
+ See [`specs/migrations/`](specs/migrations/) for the full, tool-specific guides this section summarizes.
705
+
706
+ ## Security model
707
+
708
+ `env-cap` is intentionally limited in scope.
709
+
710
+ The runtime:
711
+
712
+ - does not store secrets
713
+ - does not fetch secrets
714
+ - does not transmit telemetry
715
+ - does not execute lifecycle commands
716
+ - does not log secret values
717
+ - does not include documentation metadata in runtime contracts
718
+
719
+ Runtime contracts protect against accidental exposure:
720
+
721
+ ```ts
722
+ console.log(paymentsEnv)
723
+ ```
724
+
725
+ outputs:
726
+
727
+ ```txt
728
+ EnvContract("payments") { 1 variable(s) }
729
+ ```
730
+
731
+ not:
732
+
733
+ ```txt
734
+ {
735
+ STRIPE_KEY: "sk_live_..."
736
+ }
737
+ ```
738
+
739
+ Explicit access remains required:
740
+
741
+ ```ts
742
+ paymentsEnv.STRIPE_KEY
743
+ ```
744
+
745
+ Secret storage, rotation, and infrastructure management remain responsibilities of dedicated systems.
746
+
747
+ Full threat model, and what stays an application responsibility: [`SECURITY.md`](SECURITY.md). Decision-maker-level summary (bundle size, supply chain, LTS stance): [`ADOPTION.md`](ADOPTION.md).
748
+
749
+ ## Troubleshooting
750
+
751
+ Every error `env-cap` throws belongs to one of these classes. When debugging a CI failure or a startup crash, start by checking which one was received.
752
+
753
+ | Error | Thrown by | Common cause | Fix |
754
+ | --------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
755
+ | `EnvNotReadyError` | Reading `someEnv.KEY` | A contract was accessed before `validateEnv()` completed validation | Call `await validateEnv({ manifest, values })` during startup before application code accesses validated configuration |
756
+ | `EnvValidationError` | `validateEnv()` | One or more variables failed their processor or validator | Read `error.failures` — one entry per variable, each naming the contract, variable, and developer-supplied message. It never contains raw or processed values (see [Security model](#security-model)) |
757
+ | `EnvManifestGenerationError` | `generateEnvManifest()` | A provable contract conflict (for example, two contracts define incompatible processor return types for the same variable name), or `location` resolves outside `root` | Read `error.issues`; resolve the conflicting definitions or correct the output path |
758
+ | `EnvDocumentationGenerationError` | `generateDocumentation()` | `location`/`envExample.location` resolves outside `root` (undocumented contracts/variables never throw — see below) | Correct the output path |
759
+ | `EnvUsageAnalysisError` | `generateUsageReport()` | `report.location` resolves outside `root` (unused/unowned findings never throw — see below) | Correct the output path |
760
+ | `EnvProjectGenerationError` | `generateEnvArtifacts()` | Any of the above errors aggregated across requested generation steps (manifest/docs/usage), or a provable manifest-pass compatibility/exclusive-group issue | Apply the fix for the underlying error. `generateEnvArtifacts()` combines failures into one result instead of failing independently per generation step |
761
+
762
+ **Documentation completeness and dependency ownership never throw.** An undocumented contract/variable
763
+ or an unconsumed owned dependency is a heuristic signal, not a provable defect the way a manifest
764
+ compatibility conflict is — both have real, common false-positive causes (a webhook handler in another
765
+ repo, a shell script reading the variable, a package outside the `packages` allowlist). They're
766
+ reported as `Finding`s (`documentation`/`ownership` families) on the persisted evidence artifact
767
+ instead; gate CI on them yourself by reading `--evidence`'s `finding` field if you want that
768
+ enforced. See [ADR 0038](specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md).
769
+
770
+ **"My schema file's variable isn't showing up in the generated manifest/docs."**
771
+
772
+ Discovery only understands statically analyzable patterns — an inline object literal or a directly resolvable local/imported `const`.
773
+
774
+ A dynamically constructed schema (`createEnv(buildSchema())`) or a spread (`createEnv({ ...shared })`) may produce a parse warning instead of silently guessing.
775
+
776
+ Check `result.parseWarnings` or the CLI's non-JSON output for the specific reason (see [ADR 0002](specs/decisions/0002-static-analysis-never-execution.md)).
777
+
778
+ **"A contract imported through a `tsconfig.json` path alias shows up as abandoned / a `documentEnv()` call through an alias is unresolved."**
779
+
780
+ Confirm `tsconfig.json` is actually at `root` (auto-detection doesn't search upward) and declares `paths`/`baseUrl`, or that an explicit `tsconfig` option points at the right file. Confirm `tsconfig` wasn't set to `false`.
781
+
782
+ See [ADR 0023](specs/decisions/0023-tsconfig-path-alias-resolution.md) and [TypeScript path aliases](#typescript-path-aliases-pathsbaseurl) above.
783
+
784
+ **"A package's contract isn't discoverable even though I listed it in `packages`."**
785
+
786
+ Check `result.parseWarnings` for a `"(package) <name>"`-prefixed entry.
787
+
788
+ The allow-listed package must declare a valid `envCap.schema` field pointing to real `.ts`/`.tsx` source inside its own directory (see [Reusable packages](#reusable-packages)).
789
+
790
+ **"I called `validateEnv()` again with different `values` and got the same result as last time."**
791
+
792
+ `validateEnv()` caches its first outcome for the life of the process (see [Validate once during startup](#3-validate-once-during-startup)). Call `resetEnvCache()` before re-validating — normal for a test suite or a script exercising multiple scenarios, not something a running application should need.
793
+
794
+ ## CLI
795
+
796
+ Generate the manifest and the persisted evidence artifact directly from the command line:
797
+
798
+ ```bash
799
+ npx env-cap \
800
+ --location src/generated/env.manifest.ts \
801
+ --evidence docs/env.evidence.json \
802
+ --strict
803
+ ```
804
+
805
+ The CLI is designed for development workflows, CI pipelines, and platform automation.
806
+
807
+ The CLI's own surface is deliberately narrow -- see [ADR 0046](specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md):
808
+ only outputs with a real runtime consumer (the manifest) or that are inherent
809
+ to the tool's own evidence/reporting contract (`--evidence`/`--json`/`--check`)
810
+ get a flag. The rich Markdown docs catalog, the dependency & ownership
811
+ report, and a reconciled `.env.example` have no such consumer -- nothing
812
+ imports them the way application code imports the generated manifest -- so
813
+ generating them is a few lines of application code instead, calling
814
+ `@maverickcer/env-cap/build`'s exported `generateDocumentation()`/`generateUsageReport()`
815
+ directly:
816
+
817
+ ```ts
818
+ import { generateDocumentation, generateUsageReport } from "@maverickcer/env-cap/build"
819
+ import { nodeBuildFileSystem } from "@maverickcer/env-cap/node"
820
+
821
+ await generateDocumentation({
822
+ fs: nodeBuildFileSystem,
823
+ location: "docs/ENVIRONMENT.md",
824
+ // Never overwrites a file that already exists at `envExample.location` by
825
+ // default -- it writes a timestamped sibling instead, for you to
826
+ // diff/merge by hand. Pass `onExisting: "overwrite"` to replace it
827
+ // directly, or `"skip"` to write nothing at all when one is already
828
+ // present -- see `EnvExampleOnExisting`.
829
+ envExample: { location: ".env.example", onExisting: "overwrite" },
830
+ })
831
+
832
+ await generateUsageReport({
833
+ fs: nodeBuildFileSystem,
834
+ report: { location: "docs/ENV-OWNERSHIP.md" },
835
+ })
836
+ ```
837
+
838
+ `checkEnvArtifacts()` is the same function `--check` calls internally, and
839
+ takes the same `docs`/`usage` options -- see any of this repo's own
840
+ `examples/*/scripts/generate-docs/` directories for a complete, wired-up
841
+ `run.ts`/`check.ts` pair to copy from.
842
+
843
+ Common uses include:
844
+
845
+ - generating environment manifests
846
+ - generating the persisted evidence artifact for reporting/CI
847
+ - enforcing configuration ownership rules
848
+ - detecting undocumented or stale configuration changes
849
+ - producing machine-readable reports for automation
850
+
851
+ ### Options
852
+
853
+ At least one of `--location` or `--evidence` is required. Run `npx env-cap --help` for the same list.
854
+
855
+ | Flag | Meaning |
856
+ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
857
+ | `--root <path>` | Directory that globs resolve from (default: the current directory). |
858
+ | `--location <path>` | Output path for the generated manifest. |
859
+ | `--include <glob>` | Schema-discovery glob. Repeatable. Default: `**/env.schema.ts`. |
860
+ | `--exclude <glob>` | Glob to exclude from discovery. Repeatable. |
861
+ | `--package <name>` | Installed package to also discover a schema from, through its `envCap.schema` `package.json` field. Repeatable. |
862
+ | `--tsconfig <path>` | `tsconfig.json` (relative to root) whose `paths` and `baseUrl` resolve aliased imports during static analysis. Default: the `tsconfig.json` found at the root. |
863
+ | `--no-tsconfig` | Turn path-alias resolution off entirely. |
864
+ | `--evidence <path>` | Also write the persisted evidence artifact and its `.fingerprint` sidecar, for example `docs/env.evidence.json`. |
865
+ | `--strict` | Escalate every warning-severity finding to a hard error: compatibility, documentation and ownership. Nothing is written when it fires. Info findings never escalate. |
866
+ | `--strict-docs` | Escalate only documentation warnings (undocumented, stale or expiring entries, unresolvable `documentEnv()` links), independent of `--strict`. |
867
+ | `--strict-ownership` | Escalate only ownership warnings (abandoned contracts, unresolved consumers, unconsumed owned variables, indeterminate ownership), independent of `--strict`. |
868
+ | `--json` | Emit a machine-readable report instead of formatted text (see below). |
869
+ | `--check` | Verify generated artifacts are up to date without writing anything. Exits `1` if any is stale or missing. |
870
+ | `--help`, `-h` | Show the help text. |
871
+
872
+ ### `--json`
873
+
874
+ Add `--json` to emit a machine-readable report instead of formatted terminal output.
875
+
876
+ The output contains the same generated artifact information returned by `generateEnvArtifacts()` wrapped in a stable JSON envelope:
877
+
878
+ ```bash
879
+ npx env-cap \
880
+ --location src/generated/env.manifest.ts \
881
+ --evidence docs/env.evidence.json \
882
+ --json
883
+ ```
884
+
885
+ Example:
886
+
887
+ ```jsonc
888
+ {
889
+ "schemaVersion": 1,
890
+ "kind": "env-cap-report",
891
+ "toolVersion": "<installed env-cap version>",
892
+ "ok": true,
893
+ "manifest": {
894
+ "outputPath": "...",
895
+ "contracts": [/* discovered contracts */],
896
+ },
897
+ // "evidence" appears when --evidence is passed. "docs"/"usage" no longer
898
+ // appear from the CLI at all (ADR 0046) -- call `generateDocumentation()`/
899
+ // `generateUsageReport()` directly for that shape.
900
+ }
901
+ ```
902
+
903
+ The full field-by-field shape -- including `docs.catalog` entries, `manifest`, and
904
+ `usage` -- is defined by the [published JSON Schema](#published-json-schema) below
905
+ rather than repeated here.
906
+
907
+ `--json` changes output formatting only. Exit-code behavior remains unchanged.
908
+
909
+ New fields may be added without a `schemaVersion` change. Consumers should ignore properties they do not recognize.
910
+
911
+ See [ADR 0013](specs/decisions/0013-json-output-is-a-versioned-mirror.md).
912
+
913
+ #### Published JSON Schema
914
+
915
+ A real, published JSON Schema for the `--json` envelope lives at
916
+ [`schemas/env-cap-report.schema.json`](schemas/env-cap-report.schema.json), also
917
+ resolvable as `@maverickcer/env-cap/schema` -- for external, non-TypeScript tooling
918
+ (a Go service, a Python dashboard, a generic CI linter) to validate or codegen
919
+ against without hand-transcribing the shape above.
920
+
921
+ It's generated directly from `src/cli/json.ts`'s own types (never hand-authored), so
922
+ the two can't silently drift apart, and it evolves under the same additive-only rule
923
+ already established for `--json` itself: a new optional field is never a breaking
924
+ schema change; a changed or removed field is.
925
+
926
+ See [ADR 0019](specs/decisions/0019-published-json-schema-generated-from-types.md).
927
+
928
+ ### `--check`
929
+
930
+ Add `--check` to verify generated artifacts are current without modifying files.
931
+
932
+ This is useful as a CI drift check when a schema changes but generated artifacts were not updated:
933
+
934
+ ```bash
935
+ npx env-cap \
936
+ --location src/generated/env.manifest.ts \
937
+ --evidence docs/env.evidence.json \
938
+ --check
939
+ ```
940
+
941
+ The command exits:
942
+
943
+ - `0` when generated artifacts match the expected output
944
+ - `1` when artifacts are missing or stale
945
+
946
+ `--check` never writes to or modifies committed files, even when drift is detected.
947
+
948
+ With `--json`, the response includes an additive `checkResult` field containing the comparison result.
949
+
950
+ See [ADR 0016](specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md).
951
+
952
+ ## GitHub Action
953
+
954
+ The first-party GitHub Action runs `env-cap --json` and integrates configuration analysis into pull requests and scheduled maintenance workflows.
955
+
956
+ It provides:
957
+
958
+ - machine-readable configuration reports
959
+ - inline pull request annotations
960
+ - sticky summary comments
961
+ - scheduled rotation monitoring
962
+
963
+ Example:
964
+
965
+ ```yaml
966
+ # .github/workflows/env-cap.yml
967
+ name: env-cap
968
+
969
+ on:
970
+ pull_request:
971
+
972
+ permissions:
973
+ contents: read
974
+ pull-requests: write
975
+
976
+ jobs:
977
+ report:
978
+ runs-on: ubuntu-latest
979
+
980
+ steps:
981
+ - uses: actions/checkout@v4
982
+
983
+ - uses: maverickcer/env-cap@v0
984
+ with:
985
+ args: "--location src/generated/env.manifest.ts --evidence docs/env.evidence.json"
986
+ ```
987
+
988
+ The action runs the project's own installed `env-cap` (`devDependencies`) and never an unpinned
989
+ `latest`: with no local install it needs `with: version: "<x.y.z>"` and otherwise fails with an
990
+ explanation. Inputs reach the CLI through environment variables, not shell text, so a PR-controlled
991
+ value forwarded into `args` cannot become a command.
992
+
993
+ What this action reports (data-cap's sibling action reports the same sections minus the rotation
994
+ alert): inline `::warning`/`::error` annotations, one sticky pull-request comment per `report-key`,
995
+ and -- env-cap only, on runs with no pull request -- a GitHub issue for expiring or expired
996
+ variables (`rotation-alert`, needs `issues: write`), closed again once nothing is expiring.
997
+
998
+ `args` only reaches the CLI, so it can only drive `--location`/`--evidence`/
999
+ `--strict`-family flags (ADR 0046) -- the persisted evidence artifact this
1000
+ produces is what the Action's own PR annotations/summary comment/rotation
1001
+ alerts read from (Finding Model, ADR 0038), regardless of whether your repo
1002
+ also generates `docs/ENVIRONMENT.md`/`docs/ENV-OWNERSHIP.md` as a separate step (the scaffolded default is `ENV-OWNERSHIP.md` so it never collides with a sibling package's ownership report).
1003
+
1004
+ | Input | Default | Purpose |
1005
+ | ------------------- | --------------------- | ----------------------------------------------------------------------------------------------------- |
1006
+ | `args` | _(required)_ | Arguments passed to `env-cap --json`, such as `--location`, `--evidence`, and strict validation flags |
1007
+ | `working-directory` | `.` | Directory where `env-cap` executes |
1008
+ | `version` | _(latest)_ | Version to execute through `npx` when `env-cap` is not installed locally |
1009
+ | `comment` | `true` | Creates or updates a sticky pull request summary comment |
1010
+ | `annotations` | `true` | Emits GitHub workflow annotations for detected issues |
1011
+ | `rotation-alert` | `true` | Enables scheduled expiration reporting outside pull requests |
1012
+ | `report-key` | _(working-directory)_ | Identifies this report when multiple workflows run against the same pull request |
1013
+ | `github-token` | `${{ github.token }}` | Token used for the `gh` CLI calls that post/update PR comments and rotation-alert issues |
1014
+
1015
+ The Action does not create its own policy layer. Pass/fail behavior always follows the CLI exit code and whatever `--strict`/`--strict-docs`/`--strict-ownership` combination this invocation's own `args` input passes (ADR 0044 — see [Troubleshooting](#troubleshooting)). A finding family with no matching `--strict*` flag never fails the run on its own; read it from `--evidence`'s output and gate on it in your own workflow step if you want that enforced.
1016
+
1017
+ ### Monorepos
1018
+
1019
+ For monorepos running multiple `env-cap` checks in parallel, provide a unique `report-key` for each invocation.
1020
+
1021
+ This prevents separate jobs from overwriting each other's pull request comments.
1022
+
1023
+ For teams that want a single combined report across multiple packages, upload each job's `--json` output as an artifact and aggregate the results in a final workflow step.
1024
+
1025
+ ### Reusable packages and external contracts
1026
+
1027
+ Contracts discovered from explicitly included packages are reported through the same annotations and summary surfaces as local contracts.
1028
+
1029
+ Because `node_modules` is not part of a pull request diff, findings originating from installed packages cannot render as inline changed-file annotations. The sticky summary comment remains the complete reporting surface.
1030
+
1031
+ See [Reusable packages](#reusable-packages) for the package discovery model.
1032
+
1033
+ ### Scheduled rotation alerts
1034
+
1035
+ The same Action can run independently of pull requests to monitor configuration lifecycle metadata.
1036
+
1037
+ This is useful for detecting variables that are approaching expiration or have exceeded their documented rotation window.
1038
+
1039
+ Example:
1040
+
1041
+ ```yaml
1042
+ # .github/workflows/env-cap-rotation.yml
1043
+ name: env-cap rotation check
1044
+
1045
+ on:
1046
+ schedule:
1047
+ - cron: "0 9 * * 1"
1048
+ workflow_dispatch:
1049
+
1050
+ permissions:
1051
+ contents: read
1052
+ issues: write
1053
+
1054
+ jobs:
1055
+ check-rotation:
1056
+ runs-on: ubuntu-latest
1057
+
1058
+ steps:
1059
+ - uses: actions/checkout@v4
1060
+
1061
+ - uses: maverickcer/env-cap@v0
1062
+ with:
1063
+ args: "--location src/generated/env.manifest.ts --evidence docs/env.evidence.json"
1064
+ ```
1065
+
1066
+ The Action reads the rotation-alert list from the persisted evidence artifact's Lifecycle Model (`result.evidence.lifecycle.expiring`), so `--evidence` is required here — `--docs`/`--expiring-within-days` are not CLI flags (see ADR 0046); the expiring-soon window itself is always the library's 30-day default when driven through the CLI this way.
1067
+
1068
+ When running without a pull request context, the Action can create or update a GitHub issue containing expiring or expired configuration entries.
1069
+
1070
+ Once all reported variables are resolved, the issue is automatically closed.
1071
+
1072
+ Set `rotation-alert: "false"` to disable issue-based rotation reporting.
1073
+
1074
+ See [ADR 0018](specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md).
1075
+
1076
+ ## ESLint plugin
1077
+
1078
+ `@maverickcer/env-cap/eslint-plugin` provides a `no-raw-process-env` rule (and its filesystem analogue `no-node-fs`, below) that helps enforce environment ownership boundaries.
1079
+
1080
+ It flags direct `process.env` access outside approved contract definitions, making configuration ownership enforceable through tooling rather than relying only on team conventions.
1081
+
1082
+ ```bash
1083
+ npm install -D eslint
1084
+ ```
1085
+
1086
+ ```js
1087
+ // eslint.config.js
1088
+
1089
+ import envCapPlugin from "@maverickcer/env-cap/eslint-plugin"
1090
+
1091
+ export default [
1092
+ {
1093
+ files: ["**/*.ts"],
1094
+ plugins: {
1095
+ "env-cap": envCapPlugin,
1096
+ },
1097
+ rules: {
1098
+ "env-cap/no-raw-process-env": "error",
1099
+ },
1100
+ },
1101
+ ]
1102
+ ```
1103
+
1104
+ By default, `env.schema.ts` and `env.schema.tsx` files are exempt because their purpose is to define the environment contract consumed by `createEnv()`.
1105
+
1106
+ Other files must access validated contracts instead of reading environment variables directly.
1107
+
1108
+ For example:
1109
+
1110
+ ```ts
1111
+ process.env.STRIPE_KEY
1112
+ ```
1113
+
1114
+ becomes:
1115
+
1116
+ ```ts
1117
+ paymentsEnv.STRIPE_KEY
1118
+ ```
1119
+
1120
+ The rule does not prevent legitimate infrastructure or build-time code from accessing raw environment variables.
1121
+
1122
+ For approved exceptions, provide an explicit allow list:
1123
+
1124
+ ```js
1125
+ rules: {
1126
+ "env-cap/no-raw-process-env": [
1127
+ "error",
1128
+ {
1129
+ allow: ["scripts/bootstrap-secrets.ts"],
1130
+ },
1131
+ ],
1132
+ }
1133
+ ```
1134
+
1135
+ One-off exceptions can also use the standard ESLint disable comment:
1136
+
1137
+ ```ts
1138
+ // eslint-disable-next-line env-cap/no-raw-process-env
1139
+ process.env.BOOTSTRAP_TOKEN
1140
+ ```
1141
+
1142
+ The goal is not to eliminate every direct environment read. The goal is to make ownership boundaries intentional and reviewable.
1143
+
1144
+ See [ADR 0017](specs/decisions/0017-eslint-plugin-entry-point.md).
1145
+
1146
+ ### `no-node-fs`
1147
+
1148
+ The plugin also ships `no-node-fs`, the filesystem analogue of `no-raw-process-env`. It flags any `import`, `require`, or dynamic `import()` of `node:fs` (or `fs`, and their `/promises` subpaths) so a module accepts a filesystem capability from its caller instead of acquiring one implicitly — the discipline `env-cap`'s own `./build` surface follows (see [ADR 0040](specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md)).
1149
+
1150
+ ```js
1151
+ rules: {
1152
+ "env-cap/no-node-fs": [
1153
+ "error",
1154
+ {
1155
+ // globs for the executable entry points that legitimately construct
1156
+ // the concrete node:fs adapter -- nothing is exempt by default.
1157
+ allow: ["src/cli/**", "scripts/**"],
1158
+ },
1159
+ ],
1160
+ }
1161
+ ```
1162
+
1163
+ Nothing is exempt unless you list it: the rule never guesses at what counts as an executable capability boundary. A consuming project that runs `@maverickcer/env-cap/build` from its own script imports the ready-made adapter from `@maverickcer/env-cap/node` (`{ nodeBuildFileSystem }`) rather than reaching for `node:fs` itself.
1164
+
1165
+ Common questions about dotenv/Zod overlap, centralized configuration, AST analysis, incremental adoption, and ownership models are answered in the [FAQ](https://maverickcer.github.io/env-cap/#faq).
1166
+
1167
+ ## Performance characteristics
1168
+
1169
+ env-cap is designed to add predictable configuration validation without introducing
1170
+ runtime complexity into every environment variable access.
1171
+
1172
+ Runtime behavior:
1173
+
1174
+ - Environment initialization: O(N), where N is the number of defined variables.
1175
+ - Initial validation: O(N), where N is the number of variables being validated.
1176
+ - Variable lookup after initialization: O(1).
1177
+ - Repeated validation after the initial pass: O(1) through cached validation state.
1178
+
1179
+ This means applications pay validation and setup costs once during initialization,
1180
+ rather than repeatedly processing configuration during normal execution.
1181
+
1182
+ For comparison, conventional configuration patterns typically perform one of two
1183
+ operations:
1184
+
1185
+ 1. Build a configuration object and access properties:
1186
+ - Object construction: O(N)
1187
+ - Property lookup: O(1)
1188
+
1189
+ 2. Build a configuration object with inline processing/validation:
1190
+ - Object construction: O(N)
1191
+ - Processing cost: O(N)
1192
+ - Validation cost: O(N)
1193
+
1194
+ env-cap follows the second model's safety benefits while separating processing,
1195
+ validation, and access so repeated application usage remains constant-time.
1196
+
1197
+ See the [performance documentation](./benchmarks/README.md) for benchmark methodology
1198
+ and regression tracking.
1199
+
1200
+ ## Documentation index
1201
+
1202
+ | Doc | For |
1203
+ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
1204
+ | This Guide + the [docs site](https://maverickcer.github.io/env-cap/) | Using `env-cap` in an application |
1205
+ | [API reference](https://maverickcer.github.io/env-cap/api/) | Every exported symbol, generated from the types |
1206
+ | [`specs/architecture.md`](specs/architecture.md) + [`specs/decisions/`](specs/decisions/) | Why the package is shaped the way it is (ADRs) |
1207
+ | [`specs/migrations/`](specs/migrations/) | Adopting `env-cap` alongside dotenv / Zod / envalid / t3-env |
1208
+ | [`ADOPTION.md`](ADOPTION.md) | Decision-maker summary: security, size, LTS |
1209
+ | [`SECURITY.md`](SECURITY.md) | Full threat model and application responsibilities |
1210
+ | [`VERSIONING.md`](VERSIONING.md) | What semver covers; Stable / Experimental / Private tiers |
1211
+ | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Making a change |
1212
+ | [`CODE_REVIEW.md`](CODE_REVIEW.md) | What a reviewer checks before merging |
1213
+ | [`RELEASING.md`](RELEASING.md) | Maintainer release process |
1214
+ | [`SUPPORT.md`](SUPPORT.md) | Where to ask questions and file bugs |