@maverickcer/env-cap 0.7.5 → 0.7.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (278) hide show
  1. package/ADOPTION.md +12 -12
  2. package/AGENTS.md +85 -120
  3. package/CHANGELOG.md +27 -0
  4. package/CODE_REVIEW.md +5 -5
  5. package/CONTRIBUTING.md +5 -5
  6. package/GUIDE.md +42 -24
  7. package/README.md +52 -34
  8. package/RELEASING.md +78 -64
  9. package/SECURITY.md +15 -15
  10. package/VERSIONING.md +16 -15
  11. package/benchmarks/READING-BENCHMARKS.md +101 -85
  12. package/benchmarks/README.md +12 -9
  13. package/benchmarks/WRITING-BENCHMARKS.md +89 -79
  14. package/benchmarks/performance-buildtime/BENCHMARKS.md +20 -20
  15. package/benchmarks/performance-runtime/BENCHMARKS.md +107 -107
  16. package/dist/.dts/_ipc/build-fs.d.ts +3 -3
  17. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/display-path.d.ts +1 -1
  19. package/dist/.dts/_ipc/glob.d.ts +3 -2
  20. package/dist/.dts/_ipc/glob.d.ts.map +1 -1
  21. package/dist/.dts/_ipc/no-node-fs.d.ts +2 -2
  22. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  23. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  24. package/dist/.dts/_ipc/typescript.d.ts +4 -4
  25. package/dist/.dts/build/assemble-project.d.ts +14 -15
  26. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  27. package/dist/.dts/build/change-model.d.ts +14 -14
  28. package/dist/.dts/build/change-model.d.ts.map +1 -1
  29. package/dist/.dts/build/check-artifacts.d.ts +4 -4
  30. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  31. package/dist/.dts/build/citation-verification.d.ts +13 -14
  32. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  33. package/dist/.dts/build/compatibility.d.ts +24 -24
  34. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  35. package/dist/.dts/build/contract-model.d.ts +10 -10
  36. package/dist/.dts/build/contract-model.d.ts.map +1 -1
  37. package/dist/.dts/build/deep-equal.d.ts +2 -2
  38. package/dist/.dts/build/deep-freeze.d.ts +2 -2
  39. package/dist/.dts/build/dependency-graph.d.ts +48 -55
  40. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  41. package/dist/.dts/build/dependency-model.d.ts +18 -18
  42. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  43. package/dist/.dts/build/discover.d.ts +11 -11
  44. package/dist/.dts/build/discover.d.ts.map +1 -1
  45. package/dist/.dts/build/docs.d.ts +34 -38
  46. package/dist/.dts/build/docs.d.ts.map +1 -1
  47. package/dist/.dts/build/env-example.d.ts +13 -13
  48. package/dist/.dts/build/env-example.d.ts.map +1 -1
  49. package/dist/.dts/build/errors.d.ts +8 -8
  50. package/dist/.dts/build/evidence-cache.d.ts +23 -23
  51. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  52. package/dist/.dts/build/evidence-model.d.ts +3 -3
  53. package/dist/.dts/build/evidence-reference.d.ts +15 -15
  54. package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
  55. package/dist/.dts/build/evidence-snapshot.d.ts +47 -53
  56. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  57. package/dist/.dts/build/exclusive-group.d.ts +4 -4
  58. package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
  59. package/dist/.dts/build/finding-model.d.ts +12 -12
  60. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  61. package/dist/.dts/build/generate-documentation.d.ts +19 -19
  62. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  63. package/dist/.dts/build/generate-env-artifacts.d.ts +43 -43
  64. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  65. package/dist/.dts/build/generate-evidence.d.ts +19 -19
  66. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  67. package/dist/.dts/build/generate-manifest.d.ts +11 -12
  68. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  69. package/dist/.dts/build/generate-usage.d.ts +23 -24
  70. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  71. package/dist/.dts/build/generated-banner.d.ts +5 -5
  72. package/dist/.dts/build/governance-fields.d.ts +7 -7
  73. package/dist/.dts/build/humanize-key.d.ts +1 -1
  74. package/dist/.dts/build/humanize-key.d.ts.map +1 -1
  75. package/dist/.dts/build/index.d.ts +20 -36
  76. package/dist/.dts/build/index.d.ts.map +1 -1
  77. package/dist/.dts/build/lifecycle-model.d.ts +87 -85
  78. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  79. package/dist/.dts/build/link.d.ts +38 -39
  80. package/dist/.dts/build/link.d.ts.map +1 -1
  81. package/dist/.dts/build/literal-eval.d.ts +2 -2
  82. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  83. package/dist/.dts/build/live-expirations.d.ts +14 -13
  84. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  85. package/dist/.dts/build/manifest.d.ts +6 -6
  86. package/dist/.dts/build/map-utils.d.ts +4 -4
  87. package/dist/.dts/build/merge-documentation.d.ts +9 -8
  88. package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
  89. package/dist/.dts/build/ownership-model.d.ts +14 -15
  90. package/dist/.dts/build/ownership-model.d.ts.map +1 -1
  91. package/dist/.dts/build/parse.d.ts +20 -21
  92. package/dist/.dts/build/parse.d.ts.map +1 -1
  93. package/dist/.dts/build/reference-projections.d.ts +36 -38
  94. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  95. package/dist/.dts/build/resolution/resolve-import.d.ts +18 -14
  96. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  97. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +26 -26
  98. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  99. package/dist/.dts/build/resolution/resolve-within-root.d.ts +9 -9
  100. package/dist/.dts/build/sarif.d.ts +5 -5
  101. package/dist/.dts/build/sarif.d.ts.map +1 -1
  102. package/dist/.dts/build/scan-dependencies.d.ts +17 -16
  103. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  104. package/dist/.dts/build/sort-by-identity.d.ts +1 -1
  105. package/dist/.dts/build/source-position.d.ts +13 -13
  106. package/dist/.dts/build/tool-version.d.ts +1 -1
  107. package/dist/.dts/build/usage-report.d.ts +19 -19
  108. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  109. package/dist/.dts/eslint-plugin/index.d.ts +16 -5
  110. package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
  111. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
  112. package/dist/.dts/evidence/define-projection.d.ts +15 -16
  113. package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
  114. package/dist/.dts/evidence/index.d.ts +11 -15
  115. package/dist/.dts/evidence/index.d.ts.map +1 -1
  116. package/dist/.dts/helpers/index.d.ts +15 -18
  117. package/dist/.dts/helpers/index.d.ts.map +1 -1
  118. package/dist/.dts/helpers/validators.d.ts +2 -2
  119. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  120. package/dist/.dts/node/index.d.ts +19 -0
  121. package/dist/.dts/node/index.d.ts.map +1 -1
  122. package/dist/.dts/runtime/create.d.ts +3 -3
  123. package/dist/.dts/runtime/document.d.ts +90 -99
  124. package/dist/.dts/runtime/document.d.ts.map +1 -1
  125. package/dist/.dts/runtime/errors.d.ts +5 -5
  126. package/dist/.dts/runtime/reset.d.ts +1 -1
  127. package/dist/.dts/runtime/types.d.ts +23 -24
  128. package/dist/.dts/runtime/types.d.ts.map +1 -1
  129. package/dist/.dts/runtime/validate.d.ts +1 -1
  130. package/dist/.dts7/_ipc/build-fs.d.ts +3 -3
  131. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -1
  132. package/dist/.dts7/_ipc/display-path.d.ts +1 -1
  133. package/dist/.dts7/_ipc/glob.d.ts +3 -2
  134. package/dist/.dts7/_ipc/glob.d.ts.map +1 -1
  135. package/dist/.dts7/_ipc/no-node-fs.d.ts +2 -2
  136. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  137. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  138. package/dist/.dts7/_ipc/typescript.d.ts +4 -4
  139. package/dist/.dts7/build/assemble-project.d.ts +14 -15
  140. package/dist/.dts7/build/assemble-project.d.ts.map +1 -1
  141. package/dist/.dts7/build/change-model.d.ts +14 -14
  142. package/dist/.dts7/build/change-model.d.ts.map +1 -1
  143. package/dist/.dts7/build/check-artifacts.d.ts +4 -4
  144. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -1
  145. package/dist/.dts7/build/citation-verification.d.ts +13 -14
  146. package/dist/.dts7/build/citation-verification.d.ts.map +1 -1
  147. package/dist/.dts7/build/compatibility.d.ts +24 -24
  148. package/dist/.dts7/build/compatibility.d.ts.map +1 -1
  149. package/dist/.dts7/build/contract-model.d.ts +10 -10
  150. package/dist/.dts7/build/contract-model.d.ts.map +1 -1
  151. package/dist/.dts7/build/deep-equal.d.ts +2 -2
  152. package/dist/.dts7/build/deep-freeze.d.ts +2 -2
  153. package/dist/.dts7/build/dependency-graph.d.ts +48 -55
  154. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -1
  155. package/dist/.dts7/build/dependency-model.d.ts +18 -18
  156. package/dist/.dts7/build/dependency-model.d.ts.map +1 -1
  157. package/dist/.dts7/build/discover.d.ts +11 -11
  158. package/dist/.dts7/build/discover.d.ts.map +1 -1
  159. package/dist/.dts7/build/docs.d.ts +34 -38
  160. package/dist/.dts7/build/docs.d.ts.map +1 -1
  161. package/dist/.dts7/build/env-example.d.ts +13 -13
  162. package/dist/.dts7/build/env-example.d.ts.map +1 -1
  163. package/dist/.dts7/build/errors.d.ts +8 -8
  164. package/dist/.dts7/build/evidence-cache.d.ts +23 -23
  165. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -1
  166. package/dist/.dts7/build/evidence-model.d.ts +3 -3
  167. package/dist/.dts7/build/evidence-reference.d.ts +15 -15
  168. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -1
  169. package/dist/.dts7/build/evidence-snapshot.d.ts +47 -53
  170. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -1
  171. package/dist/.dts7/build/exclusive-group.d.ts +4 -4
  172. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -1
  173. package/dist/.dts7/build/finding-model.d.ts +12 -12
  174. package/dist/.dts7/build/finding-model.d.ts.map +1 -1
  175. package/dist/.dts7/build/generate-documentation.d.ts +19 -19
  176. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -1
  177. package/dist/.dts7/build/generate-env-artifacts.d.ts +43 -43
  178. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -1
  179. package/dist/.dts7/build/generate-evidence.d.ts +19 -19
  180. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -1
  181. package/dist/.dts7/build/generate-manifest.d.ts +11 -12
  182. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -1
  183. package/dist/.dts7/build/generate-usage.d.ts +23 -24
  184. package/dist/.dts7/build/generate-usage.d.ts.map +1 -1
  185. package/dist/.dts7/build/generated-banner.d.ts +5 -5
  186. package/dist/.dts7/build/governance-fields.d.ts +7 -7
  187. package/dist/.dts7/build/humanize-key.d.ts +1 -1
  188. package/dist/.dts7/build/humanize-key.d.ts.map +1 -1
  189. package/dist/.dts7/build/index.d.ts +20 -36
  190. package/dist/.dts7/build/index.d.ts.map +1 -1
  191. package/dist/.dts7/build/lifecycle-model.d.ts +87 -85
  192. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -1
  193. package/dist/.dts7/build/link.d.ts +38 -39
  194. package/dist/.dts7/build/link.d.ts.map +1 -1
  195. package/dist/.dts7/build/literal-eval.d.ts +2 -2
  196. package/dist/.dts7/build/literal-eval.d.ts.map +1 -1
  197. package/dist/.dts7/build/live-expirations.d.ts +14 -13
  198. package/dist/.dts7/build/live-expirations.d.ts.map +1 -1
  199. package/dist/.dts7/build/manifest.d.ts +6 -6
  200. package/dist/.dts7/build/map-utils.d.ts +4 -4
  201. package/dist/.dts7/build/merge-documentation.d.ts +9 -8
  202. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -1
  203. package/dist/.dts7/build/ownership-model.d.ts +14 -15
  204. package/dist/.dts7/build/ownership-model.d.ts.map +1 -1
  205. package/dist/.dts7/build/parse.d.ts +20 -21
  206. package/dist/.dts7/build/parse.d.ts.map +1 -1
  207. package/dist/.dts7/build/reference-projections.d.ts +36 -38
  208. package/dist/.dts7/build/reference-projections.d.ts.map +1 -1
  209. package/dist/.dts7/build/resolution/resolve-import.d.ts +18 -14
  210. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -1
  211. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +26 -26
  212. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -1
  213. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +9 -9
  214. package/dist/.dts7/build/sarif.d.ts +5 -5
  215. package/dist/.dts7/build/sarif.d.ts.map +1 -1
  216. package/dist/.dts7/build/scan-dependencies.d.ts +17 -16
  217. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -1
  218. package/dist/.dts7/build/sort-by-identity.d.ts +1 -1
  219. package/dist/.dts7/build/source-position.d.ts +13 -13
  220. package/dist/.dts7/build/tool-version.d.ts +1 -1
  221. package/dist/.dts7/build/usage-report.d.ts +19 -19
  222. package/dist/.dts7/build/usage-report.d.ts.map +1 -1
  223. package/dist/.dts7/eslint-plugin/index.d.ts +16 -5
  224. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -1
  225. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +4 -4
  226. package/dist/.dts7/evidence/define-projection.d.ts +15 -16
  227. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -1
  228. package/dist/.dts7/evidence/index.d.ts +11 -15
  229. package/dist/.dts7/evidence/index.d.ts.map +1 -1
  230. package/dist/.dts7/helpers/index.d.ts +15 -18
  231. package/dist/.dts7/helpers/index.d.ts.map +1 -1
  232. package/dist/.dts7/helpers/validators.d.ts +2 -2
  233. package/dist/.dts7/helpers/validators.d.ts.map +1 -1
  234. package/dist/.dts7/node/index.d.ts +19 -0
  235. package/dist/.dts7/node/index.d.ts.map +1 -1
  236. package/dist/.dts7/runtime/create.d.ts +3 -3
  237. package/dist/.dts7/runtime/document.d.ts +90 -99
  238. package/dist/.dts7/runtime/document.d.ts.map +1 -1
  239. package/dist/.dts7/runtime/errors.d.ts +5 -5
  240. package/dist/.dts7/runtime/reset.d.ts +1 -1
  241. package/dist/.dts7/runtime/types.d.ts +23 -24
  242. package/dist/.dts7/runtime/types.d.ts.map +1 -1
  243. package/dist/.dts7/runtime/validate.d.ts +1 -1
  244. package/dist/{build-DNAYWD2B.js → build-UEENZEUX.js} +37 -39
  245. package/dist/build-UEENZEUX.js.map +1 -0
  246. package/dist/build.cjs +36 -38
  247. package/dist/build.cjs.map +1 -1
  248. package/dist/build.js +36 -38
  249. package/dist/build.js.map +1 -1
  250. package/dist/{chunk-HAGMVMN5.js → chunk-TBL3O7IG.js} +2 -2
  251. package/dist/cli/index.js +29 -28
  252. package/dist/cli/index.js.map +1 -1
  253. package/dist/eslint-plugin/index.cjs.map +1 -1
  254. package/dist/eslint-plugin/index.js.map +1 -1
  255. package/dist/evidence.cjs +1 -1
  256. package/dist/evidence.cjs.map +1 -1
  257. package/dist/evidence.js +1 -1
  258. package/dist/evidence.js.map +1 -1
  259. package/dist/helpers.cjs +4 -4
  260. package/dist/helpers.cjs.map +1 -1
  261. package/dist/helpers.js +4 -4
  262. package/dist/helpers.js.map +1 -1
  263. package/dist/index.cjs.map +1 -1
  264. package/dist/index.js.map +1 -1
  265. package/examples/README.md +1 -1
  266. package/package.json +18 -10
  267. package/schemas/contract-model.schema.json +7 -7
  268. package/schemas/env-cap-report.schema.json +88 -88
  269. package/skills/env-cap/SKILL.md +12 -13
  270. package/skills/env-cap/references/api.md +1 -1
  271. package/specs/architecture.md +145 -120
  272. package/specs/generated-artifacts.md +78 -70
  273. package/specs/migrations/README.md +6 -6
  274. package/specs/migrations/from-centralized-schema.md +1 -1
  275. package/specs/migrations/from-t3-env.md +9 -9
  276. package/PROMPT.md +0 -89
  277. package/dist/build-DNAYWD2B.js.map +0 -1
  278. /package/dist/{chunk-HAGMVMN5.js.map → chunk-TBL3O7IG.js.map} +0 -0
@@ -1,26 +1,28 @@
1
1
  # Generated artifacts: what `env-cap` produces, and what it deliberately doesn't
2
2
 
3
- This is the canonical place — for a human or an AI agent working in this
4
- repository or a consuming project — to check before assuming `env-cap`
5
- generates something it doesn't. Every artifact below is produced by
6
- `generateEnvArtifacts()` (or, for the manifest/evidence outputs only, the
7
- `env-cap` CLI, its thin wrapper for those two — see [ADR
8
- 0046](decisions/0046-cli-restricted-to-runtime-and-evidence-output.md): the
9
- documentation catalog, `.env.example`, and the ownership report have no CLI
10
- flag at all, only a direct `generateDocumentation()`/`generateUsageReport()`
11
- call); nothing here is generated by a separate, independently-derived
12
- pipeline. Concretely:
13
- `computeArtifacts` (the function both `generateEnvArtifacts` and
14
- `checkArtifacts` share) runs one `assembleProject()` parse/link pass, then
15
- builds all seven canonical fact models (ADR 0024) from that single result —
16
- every artifact in this file is a projection of that same run's models, not a
3
+ Check this page before assuming `env-cap` generates something it doesn't. It
4
+ is the canonical place for that check, for a human or an AI agent working in
5
+ this repository or a consuming project.
6
+
7
+ Every artifact below is produced by `generateEnvArtifacts()`. Nothing here is
8
+ generated by a separate, independently-derived pipeline. The `env-cap` CLI is
9
+ a thin wrapper for the manifest/evidence outputs only (see
10
+ [ADR 0046](decisions/0046-cli-restricted-to-runtime-and-evidence-output.md)).
11
+ The documentation catalog, `.env.example`, and the ownership report have no
12
+ CLI flag at all, only a direct `generateDocumentation()`/`generateUsageReport()`
13
+ call.
14
+
15
+ Concretely, `computeArtifacts` (the function both `generateEnvArtifacts` and
16
+ `checkArtifacts` share) runs one `assembleProject()` parse/link pass. It then
17
+ builds all seven canonical fact models (ADR 0024) from that single result.
18
+ Every artifact in this file is a projection of that same run's models, not a
17
19
  second, independently-assembled source. `--evidence <path>` writes the
18
- composed Evidence Model to disk directly, as JSON, for a project that wants
19
- the canonical artifact itself rather than only its Markdown projections.
20
+ composed Evidence Model to disk directly, as JSON. That serves a project that
21
+ wants the canonical artifact itself rather than only its Markdown projections.
20
22
 
21
23
  **Every artifact in this table is evidence that can _support_ a review
22
- process — a security review, a privacy review, a platform audit — never a
23
- compliance claim.** Static analysis of one repository cannot, by itself,
24
+ process, never a compliance claim**. Such a process might be a security
25
+ review, a privacy review, or a platform audit. Static analysis of one repository cannot, by itself,
24
26
  establish compliance with any external standard. Every rendered artifact
25
27
  that carries this claim opens with the same disclaimer
26
28
  (`evidenceDisclaimer()` in `generated-banner.ts`, byte-identical to
@@ -33,48 +35,51 @@ data-cap's own):
33
35
 
34
36
  ## Declared vs. proven vs. evidence
35
37
 
36
- Every fact in every generated artifact is one of exactly three kinds, and a
38
+ Every fact in every generated artifact is one of exactly three kinds. A
37
39
  rendering function may never blend them or imply one is another:
38
40
 
39
- - **Declared** — metadata the author wrote via `documentEnv()`'s
40
- `VariableDocs`/`ContractDocs`: `description`, `owner`, `sensitivity`,
41
- `expiresAt`, `refreshInstructions`, `setupInstructions`, `required`,
42
- `deprecated`/`deprecatedReason`/`removeBy`, `renamedFrom`, `purpose`,
43
- `legalBasis`, `retention`, `dataResidency`, `auditRequired`, `metadata`.
44
- Presence is checked; correctness, adequacy, and enforcement are never
45
- claimed. A report may say a variable's retention policy is _"documented,"_
46
- never that it is _"sufficient"_ or _"enforced."_
47
- - **Proven** — facts derived by AST analysis of the actual source: whether a
48
- declared variable is actually read anywhere in the scanned surface
49
- (`UNCONSUMED_OWNED_VARIABLE`), which files import/reference a given
50
- contract (Dependency Model), and every exclusive-group/compatibility
51
- conflict between contracts (`FindingCode`'s compatibility family). These
52
- are statically provable from the code that exists today, in this
41
+ - **Declared**: metadata the author wrote via `documentEnv()`'s
42
+ `VariableDocs`/`ContractDocs`. The fields are `description`, `owner`,
43
+ `sensitivity`, `expiresAt`, `refreshInstructions`, `setupInstructions`,
44
+ `required`, `deprecated`/`deprecatedReason`/`removeBy`, `renamedFrom`,
45
+ `purpose`, `legalBasis`, `retention`, `dataResidency`, `auditRequired`,
46
+ `metadata`. Presence is checked; correctness, adequacy, and enforcement are
47
+ never claimed. A report may say a variable's retention policy is
48
+ _"documented,"_ never that it is _"sufficient"_ or _"enforced."_
49
+ - **Proven**: facts derived by AST analysis of the actual source. They cover:
50
+ - whether a declared variable is actually read anywhere in the scanned
51
+ surface (`UNCONSUMED_OWNED_VARIABLE`);
52
+ - which files import/reference a given contract (Dependency Model);
53
+ - every exclusive-group/compatibility conflict between contracts
54
+ (`FindingCode`'s compatibility family).
55
+
56
+ These are statically provable from the code that exists today, in this
53
57
  repository, at analysis time.
54
- - **A third case, named explicitly because it's neither** —
55
- `VariableDocs.evidence.dynamicAccess` (ADR 0053-equivalent citation
56
- mechanism, mirroring data-cap's identical design) is declared, like every
57
- other governance field, but unlike every other one it's re-verified every
58
- run against a persisted content hash of the cited file
58
+
59
+ - **A third case, named explicitly because it's neither**:
60
+ `VariableDocs.evidence.dynamicAccess`. It uses an ADR 0053-equivalent
61
+ citation mechanism, mirroring data-cap's identical design. It is declared,
62
+ like every other governance field. Unlike every other one, it's re-verified
63
+ every run against a persisted content hash of the cited file
59
64
  (`MISSING_DYNAMIC_ACCESS_CITATION`/`STALE_DYNAMIC_ACCESS_CITATION`). A
60
65
  passing check establishes only that the citation is currently _supported
61
- by its own citation/integrity state_ — the cited file exists and hasn't
62
- visibly changed since the developer wrote it — never that the described
63
- access has been proven to happen there. No rendering of this field ever
64
- uses "verified" or "proven" language for this reason.
66
+ by its own citation/integrity state_. That means the cited file exists and
67
+ hasn't visibly changed since the developer wrote it. It never means the
68
+ described access has been proven to happen there. No rendering of this
69
+ field ever uses "verified" or "proven" language for this reason.
65
70
 
66
71
  ## Built in this release
67
72
 
68
- | Artifact | Generator | What it answers |
69
- | -------------------------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
70
- | **Manifest** (`--location`) | `generateEnvManifest` (Contract Model) | A single, deterministic `.ts` file re-exporting every _active_ contract — a projection of the Contract Model, not a second source of truth. `runtime/validate.ts` validates real `process.env` values against exactly this manifest. |
71
- | **Documentation catalog** (`generateDocumentation()` — no CLI flag, ADR 0046) | `generateDocumentation` | Per-contract variables: `description` ("why"), `owner`/`sensitivity`/`purpose`/`legalBasis`/`retention`/`dataResidency` (labeled declared, not verified), plus a live "expiring soon or already expired" section sourced from the Lifecycle Model. |
72
- | **`.env.example`** (`generateDocumentation()`'s `envExample` option — no CLI flag, ADR 0046) | `generateDocumentation` | One line per active variable, generated from the same declared metadata the documentation catalog renders — never hand-maintained, never a second copy of the schema to drift from the real one. |
73
- | **Dependency & Ownership report** (`generateUsageReport()` — no CLI flag, ADR 0046) | `generateUsage` (Dependency + Ownership Model) | The owner → variables matrix, plus a real, in-repo, AST-proven consumer graph: which files actually read which variable — never guessed at. `UNCONSUMED_OWNED_VARIABLE`/`ABANDONED_CONTRACT` are warnings; `UNRESOLVED_CONSUMER`/`INDETERMINATE_OWNERSHIP` stay info, escalated only by `--strict-ownership`. |
74
- | **Evidence Model** (`--evidence`, ADR 0038) | `generateEvidenceModel` | The composed `EvidenceModel` (ADR 0024's seventh model) as JSON, plus a paired `.fingerprint` sidecar — Contract/Dependency/Ownership/Finding/Lifecycle/Change models, whichever were computed this run. Always composed in-memory even without this flag; the flag only controls whether it's additionally written to disk. |
75
- | **JSON report** (`--json`) | CLI (`src/cli/json.ts`) | The full result — every finding, every generator's output, and the composed Evidence Model — as one versioned envelope (`@maverickcer/env-cap/schema`), for a CI step or another tool to consume without parsing human-readable text. |
76
- | **Drift check** (`--check`) | `checkArtifacts` | Recomputes every requested artifact and diffs it against disk — writes nothing, exits non-zero if anything is stale or missing. Its exit code reflects staleness only, independent of `--strict*` finding severity. |
77
- | **SARIF log** | `buildSarifLog` (library export) | A SARIF 2.1.0 adapter over the Finding Model, for a security-tooling pipeline that already ingests SARIF. Not CLI-wired — an ordinary consumer of the public Finding Model type, called directly by whichever project needs it (the same boundary Phase 4/5's own generator scripts sit behind). |
73
+ | Artifact | Generator | What it answers |
74
+ | ------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75
+ | **Manifest** (`--location`) | `generateEnvManifest` (Contract Model) | A single, deterministic `.ts` file re-exporting every _active_ contract, projected from the Contract Model (not a second source of truth). `runtime/validate.ts` validates real `process.env` values against exactly this manifest. |
76
+ | **Documentation catalog** (`generateDocumentation()`, no CLI flag, ADR 0046) | `generateDocumentation` | Per-contract variables: `description` ("why") and `owner`/`sensitivity`/`purpose`/`legalBasis`/`retention`/`dataResidency` (labeled declared, not verified). It also has a live "expiring soon or already expired" section sourced from the Lifecycle Model. |
77
+ | **`.env.example`** (`generateDocumentation()`'s `envExample` option, no CLI flag, ADR 0046) | `generateDocumentation` | One line per active variable, generated from the same declared metadata the documentation catalog renders. It is never hand-maintained, and never a second copy of the schema to drift from the real one. |
78
+ | **Dependency & Ownership report** (`generateUsageReport()`, no CLI flag, ADR 0046) | `generateUsage` (Dependency + Ownership Model) | The owner → variables matrix, plus a real, in-repo, AST-proven consumer graph: which files actually read which variable, never guessed at. `UNCONSUMED_OWNED_VARIABLE`/`ABANDONED_CONTRACT` are warnings; `UNRESOLVED_CONSUMER`/`INDETERMINATE_OWNERSHIP` stay info, escalated only by `--strict-ownership`. |
79
+ | **Evidence Model** (`--evidence`, ADR 0038) | `generateEvidenceModel` | The composed `EvidenceModel` (ADR 0024's seventh model) as JSON, plus a paired `.fingerprint` sidecar, holding whichever Contract/Dependency/Ownership/Finding/Lifecycle/Change models were computed this run. It is always composed in memory; the flag only controls whether it's additionally written to disk. |
80
+ | **JSON report** (`--json`) | CLI (`src/cli/json.ts`) | The full result as one versioned envelope (`@maverickcer/env-cap/schema`): every finding, every generator's output, and the composed Evidence Model. A CI step or another tool can consume it without parsing human-readable text. |
81
+ | **Drift check** (`--check`) | `checkArtifacts` | Recomputes every requested artifact and diffs it against disk; it writes nothing and exits non-zero if anything is stale or missing. Its exit code reflects staleness only, independent of `--strict*` finding severity. |
82
+ | **SARIF log** | `buildSarifLog` (library export) | A SARIF 2.1.0 adapter over the Finding Model, for a security-tooling pipeline that already ingests SARIF. It is not CLI-wired. Whichever project needs it calls it directly, as an ordinary consumer of the public Finding Model type (the same boundary Phase 4/5's own generator scripts sit behind). |
78
83
 
79
84
  ## Standard-format documents
80
85
 
@@ -91,26 +96,29 @@ checks the format, and generation fails if that test is gone.
91
96
 
92
97
  ## Canonical fact models (ADR 0024)
93
98
 
94
- Seven canonical, versioned, JSON-serializable models — the machine-readable
95
- surface every rendered artifact above is a projection of, and what
96
- `defineEvidenceProjection()` consumers (below) read instead of re-deriving
97
- facts from raw source.
99
+ Seven canonical, versioned, JSON-serializable models form the
100
+ machine-readable surface that every rendered artifact above is a projection
101
+ of. `defineEvidenceProjection()` consumers (below) read them instead of
102
+ re-deriving facts from raw source.
98
103
 
99
104
  | Model | Builder | What it answers |
100
105
  | ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
101
- | Contract Model | `buildContractModel` | Every discovered contract (active or not) and its variables — the schema shape itself, projected and sorted deterministically. |
102
- | Dependency Model | `buildDependencyModel` | Every proven consumer relationship, indexed by contract/variable and by consuming file — the fact the ownership report projects, computed once. |
106
+ | Contract Model | `buildContractModel` | Every discovered contract (active or not) and its variables: the schema shape itself, projected and sorted deterministically. |
107
+ | Dependency Model | `buildDependencyModel` | Every proven consumer relationship, indexed by contract/variable and by consuming file. It is the fact the ownership report projects, computed once. |
103
108
  | Ownership Model | `buildOwnershipModel` | Every contract and variable's effective owner, plus first-class `unownedContracts`/`unownedVariables` arrays. |
104
- | Finding Model | `buildFindingModel` | Every rule violation and derived risk signal, unified behind one shape with a stable `code` and a structured `EvidenceReference` — the input the SARIF adapter and Evidence Model compose from. |
109
+ | Finding Model | `buildFindingModel` | Every rule violation and derived risk signal, unified behind one shape with a stable `code` and a structured `EvidenceReference`. The SARIF adapter and Evidence Model compose from it. |
105
110
  | Lifecycle Model | `buildLifecycleModel` | Every contract and variable's lifecycle data: expiry, deprecation, rename correlation. |
106
- | Change Model | `buildChangeModel` | What changed since the last persisted evidence snapshot — the manifest diff, keyed for a "changes since last report" section. |
107
- | Evidence Model | `generateEvidenceModel` | The composition of the other six into one artifact — what every reference projection below reads. Two of the seven are separately published as JSON Schema (`@maverickcer/env-cap/schema`, `@maverickcer/env-cap/schema/contract-model`); the rest are TypeScript-typed only, not yet independently schema'd. |
108
-
109
- A first wave of reference projections ships alongside the models themselves
110
- — `configurationReference`, `ownershipSummary`, and `expiringSoonReport`
111
- (all built through `defineEvidenceProjection()`), plus `buildSarifLog` (a
112
- SARIF 2.1.0 adapter over Finding Model). Every one of these is an ordinary
113
- consumer of the public model types above — none has a privileged internal
114
- path a downstream tool couldn't also use. A future open-standard projection would be
115
- architecturally no different: another `defineEvidenceProjection()` consumer,
116
- not a bespoke script bypassing this model.
111
+ | Change Model | `buildChangeModel` | What changed since the last persisted evidence snapshot: the manifest diff, keyed for a "changes since last report" section. |
112
+ | Evidence Model | `generateEvidenceModel` | The composition of the other six into one artifact, which every reference projection below reads. Two of the seven are separately published as JSON Schema (`@maverickcer/env-cap/schema`, `@maverickcer/env-cap/schema/contract-model`); the rest are TypeScript-typed only, not yet independently schema'd. |
113
+
114
+ A first wave of reference projections ships alongside the models themselves:
115
+
116
+ - `configurationReference`, `ownershipSummary`, and `expiringSoonReport`, all
117
+ built through `defineEvidenceProjection()`;
118
+ - `buildSarifLog`, a SARIF 2.1.0 adapter over Finding Model.
119
+
120
+ Every one of these is an ordinary consumer of the public model types above.
121
+ None has a privileged internal path a downstream tool couldn't also use. A
122
+ future open-standard projection would be architecturally no different. It
123
+ would be another `defineEvidenceProjection()` consumer, not a bespoke script
124
+ bypassing this model.
@@ -10,12 +10,12 @@ Migration does not require replacing your validation approach immediately. The r
10
10
 
11
11
  ## Guides
12
12
 
13
- - [From `dotenv`](from-dotenv.md) -- keep `dotenv` loading values, add capability-owned contracts on top.
14
- - [From raw `process.env`](from-process-env.md) -- replace scattered `process.env.X` access with owned, validated contracts.
15
- - [From a centralized environment schema](from-centralized-schema.md) -- split a single `env.ts`/`env.schema.ts` file into capability-owned schemas.
16
- - [From Zod](from-zod.md) -- keep Zod for validation, move ownership to capabilities.
17
- - [From envalid](from-envalid.md) -- keep envalid's validators, move ownership to capabilities.
18
- - [From t3-env](from-t3-env.md) -- keep t3-env's client/server split conceptually, replace the centralized object with capability-owned contracts.
13
+ - [From `dotenv`](from-dotenv.md): keep `dotenv` loading values, add capability-owned contracts on top.
14
+ - [From raw `process.env`](from-process-env.md): replace scattered `process.env.X` access with owned, validated contracts.
15
+ - [From a centralized environment schema](from-centralized-schema.md): split a single `env.ts`/`env.schema.ts` file into capability-owned schemas.
16
+ - [From Zod](from-zod.md): keep Zod for validation, move ownership to capabilities.
17
+ - [From envalid](from-envalid.md): keep envalid's validators, move ownership to capabilities.
18
+ - [From t3-env](from-t3-env.md): keep t3-env's client/server split conceptually, replace the centralized object with capability-owned contracts.
19
19
 
20
20
  ## Migration strategy
21
21
 
@@ -22,7 +22,7 @@ export const env = createConfig({
22
22
  });
23
23
  ```
24
24
 
25
- Centralized schemas are a reasonable starting point. They provide a clear location for configuration and make small applications easy to understand.
25
+ Centralized schemas are a reasonable starting point. They provide a clear location for configuration and make small applications straightforward to understand.
26
26
 
27
27
  As applications grow, however, the centralized file becomes a shared ownership boundary:
28
28
 
@@ -43,7 +43,7 @@ A centralized environment object is often the right choice when:
43
43
  - one team owns the application
44
44
  - configuration is relatively small
45
45
  - all variables belong to the same deployment boundary
46
- - a single application schema is easy to maintain
46
+ - a single application schema stays maintainable
47
47
 
48
48
  Example:
49
49
 
@@ -250,13 +250,13 @@ client.contract.ts
250
250
  The application build decides which contracts are included.
251
251
 
252
252
  This keeps the runtime small and avoids creating artificial package boundaries. This remains the
253
- recommended default, and the only mechanism that actually keeps a server-only variable's source out of a
254
- client bundle -- see [ADR 0004](../decisions/0004-no-client-server-package-split.md).
253
+ recommended default. It is also the only mechanism that actually keeps a server-only variable's source out
254
+ of a client bundle (see [ADR 0004](../decisions/0004-no-client-server-package-split.md)).
255
255
 
256
- If you'd rather keep `server`/`client` variables declared in one schema location instead of splitting into
257
- two contract files, `context`/`activeContexts` (see the README's ["Validation
258
- contexts"](../../GUIDE.md#validation-contexts) section, [ADR 0022](../decisions/0022-validation-contexts.md))
259
- is the closer analogue to t3-env's `server`/`client` grouping:
256
+ You may prefer to keep `server`/`client` variables declared in one schema location instead of splitting into
257
+ two contract files. In that case, `context`/`activeContexts` is the closer analogue to t3-env's
258
+ `server`/`client` grouping (see GUIDE.md's ["Validation contexts"](../../GUIDE.md#validation-contexts)
259
+ section and [ADR 0022](../decisions/0022-validation-contexts.md)):
260
260
 
261
261
  ```ts
262
262
  createEnv({
@@ -273,7 +273,7 @@ await validateEnv({ manifest, values: window.__ENV__, activeContexts: ["client"]
273
273
  ```
274
274
 
275
275
  This only controls whether `validateEnv()` processes a variable, not whether its definition ships to the
276
- browser -- it's a convenience for teams that don't need a hard module boundary, not a substitute for one. If
276
+ browser. It's a convenience for teams that don't need a hard module boundary, not a substitute for one. If
277
277
  `DATABASE_URL` must never appear in a client bundle at all, use the two-manifest approach above instead.
278
278
 
279
279
  ## Migrating a Next.js application
@@ -366,7 +366,7 @@ The runtime remains modular while platform teams still have a complete inventory
366
366
  t3-env may remain the better choice when:
367
367
 
368
368
  - your application has one configuration owner
369
- - the centralized schema is easy to maintain
369
+ - the centralized schema stays maintainable
370
370
  - capability boundaries are not important
371
371
  - documentation and lifecycle tracking are handled elsewhere
372
372
 
package/PROMPT.md DELETED
@@ -1,89 +0,0 @@
1
- ## AI-Assisted Integration
2
-
3
- env-cap is designed to integrate with existing application architectures rather than replace them blindly.
4
-
5
- If you use an AI coding assistant, provide it with the following prompt before asking it to modify your project. This helps the assistant understand both your application's architecture and env-cap's design principles before making changes.
6
-
7
- Replace `<YOUR_PROJECT_CONTEXT>` with any additional context about your application before submitting the prompt.
8
-
9
- ```text
10
- You are integrating env-cap into an existing production codebase.
11
-
12
- Package source:
13
- https://github.com/maverickcer/env-cap
14
-
15
- Before making any changes, first study the env-cap repository above, including:
16
-
17
- - README.md
18
- - Architecture documentation
19
- - ADRs (architectural decision records)
20
- - Examples
21
- - Migration guides
22
- - Package exports and API design
23
-
24
- Understand the package's intended architecture and constraints before proposing an implementation.
25
-
26
- Your role is to act as a senior/staff-level engineer performing an infrastructure integration review.
27
-
28
- Application context:
29
- <YOUR_PROJECT_CONTEXT>
30
-
31
- First, analyze this repository and understand:
32
-
33
- 1. Application architecture:
34
- - Framework and runtime(s)
35
- - Build system and bundler behavior
36
- - Monorepo/package boundaries (if applicable)
37
- - Server/client boundaries
38
- - Deployment environments
39
- - CI/CD environment configuration
40
- - Existing environment loading and validation flow
41
-
42
- 2. Current configuration system:
43
- - Where environment variables are defined
44
- - Where they are consumed
45
- - Existing validation logic
46
- - Existing documentation or generated configuration artifacts
47
- - Security-sensitive variables
48
- - Client-exposed variables
49
-
50
- 3. Integration approach:
51
- - Determine where env-cap contracts should live
52
- - Identify existing environment boundaries
53
- - Determine whether validation contexts are appropriate
54
- - Determine whether separate manifests/contracts are needed
55
- - Identify migration risks
56
-
57
- Follow env-cap's architectural principles:
58
-
59
- - Runtime validation and build-time analysis are separate concerns.
60
- - Generated artifacts are derived outputs, not manually maintained files.
61
- - Server-only secrets must remain outside client bundles.
62
- - Validation contexts control validation participation only; they are not a security boundary.
63
- - Application code determines active validation contexts explicitly.
64
- - Do not add framework-specific behavior to env-cap usage.
65
- - Avoid unnecessary wrappers or abstractions unless they solve a real application need.
66
-
67
- Before changing code, provide:
68
-
69
- 1. Current environment configuration architecture summary.
70
- 2. Recommended env-cap integration strategy.
71
- 3. Proposed migration steps.
72
- 4. Files that should change.
73
- 5. Risks and mitigations.
74
- 6. Questions requiring developer decisions.
75
-
76
- Do not implement changes until the plan has been reviewed and approved.
77
-
78
- After approval:
79
-
80
- - Implement changes incrementally.
81
- - Preserve existing behavior where possible.
82
- - Add or update tests.
83
- - Verify generated documentation/artifacts.
84
- - Verify type safety.
85
- - Verify build output.
86
- - Verify CI/CD compatibility.
87
-
88
- For the best results, provide your AI assistant access to both your repository and the env-cap repository. The assistant should understand your application's architecture before recommending how env-cap fits into it.
89
- ```