@maverickcer/env-cap 0.7.5 → 0.7.7

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 (279) hide show
  1. package/ADOPTION.md +12 -12
  2. package/AGENTS.md +85 -120
  3. package/CHANGELOG.md +36 -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-33O5SDTC.js} +37 -39
  245. package/dist/build-33O5SDTC.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-4D67AQFY.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 +20 -13
  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/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +9 -0
  273. package/specs/generated-artifacts.md +78 -70
  274. package/specs/migrations/README.md +6 -6
  275. package/specs/migrations/from-centralized-schema.md +1 -1
  276. package/specs/migrations/from-t3-env.md +9 -9
  277. package/PROMPT.md +0 -89
  278. package/dist/build-DNAYWD2B.js.map +0 -1
  279. /package/dist/{chunk-HAGMVMN5.js.map → chunk-4D67AQFY.js.map} +0 -0
package/dist/build.js CHANGED
@@ -378,7 +378,7 @@ async function discoverSchemaFiles(options) {
378
378
  const included = await discoverFiles(options);
379
379
  if (included.length > MAX_DISCOVERED_SCHEMA_FILES) {
380
380
  throw new Error(
381
- `discoverSchemaFiles: found ${String(included.length)} files matching "include" under ${options.root} -- more than the ${String(MAX_DISCOVERED_SCHEMA_FILES)}-file sanity limit. This almost always means "root" (or "include"/"exclude") resolved more broadly than intended -- e.g. an omitted "root" falling back to an unexpectedly large process.cwd() -- rather than a real project genuinely declaring this many contracts. Narrow "root"/"include"/"exclude" to the intended project boundary.`
381
+ `discoverSchemaFiles: found ${String(included.length)} files matching "include" under ${options.root}, more than the ${String(MAX_DISCOVERED_SCHEMA_FILES)}-file sanity limit. This usually means "root" (or "include"/"exclude") resolved more broadly than intended, for example an omitted "root" falling back to a large process.cwd(). Narrow "root"/"include"/"exclude" to the intended project boundary.`
382
382
  );
383
383
  }
384
384
  return included;
@@ -651,7 +651,7 @@ function extractSchemaVariable(key, definition, filePath, contextLabel, warnings
651
651
  } else {
652
652
  warnings.push({
653
653
  file: filePath,
654
- message: evaluated.ok && evaluated.value === "" ? `"context" for "${key}" in "${contextLabel}" is an empty string; ignoring it -- validation contexts must be non-empty.` : `"context" for "${key}" in "${contextLabel}" is not a statically-resolvable string literal; ignoring it.`
654
+ message: evaluated.ok && evaluated.value === "" ? `"context" for "${key}" in "${contextLabel}" is an empty string; ignoring it. Validation contexts must be non-empty.` : `"context" for "${key}" in "${contextLabel}" is not a statically-resolvable string literal; ignoring it.`
655
655
  });
656
656
  }
657
657
  }
@@ -1115,7 +1115,7 @@ function resolveWithinRoot(root, location, optionName, functionName) {
1115
1115
  severity: "error",
1116
1116
  variable: optionName,
1117
1117
  files: [location],
1118
- reason: `"${optionName}" ("${location}") resolves to "${resolved}", which is outside "root" ("${root}"). ${functionName}() refuses to write outside root -- use a path nested under root instead.`
1118
+ reason: `"${optionName}" ("${location}") resolves to "${resolved}", which is outside "root" ("${root}"). ${functionName}() refuses to write outside root. Use a path nested under root instead.`
1119
1119
  }
1120
1120
  };
1121
1121
  }
@@ -1164,7 +1164,7 @@ async function resolveUncached(packageName, root, fs) {
1164
1164
  return {
1165
1165
  ok: false,
1166
1166
  code: "PACKAGE_NOT_FOUND",
1167
- reason: `Package "${packageName}" listed in "packages" could not be resolved from "${root}" -- is it installed?`
1167
+ reason: `Package "${packageName}" listed in "packages" could not be resolved from "${root}". Is it installed?`
1168
1168
  };
1169
1169
  }
1170
1170
  const { packageJsonPath, packageDir } = located;
@@ -1759,7 +1759,7 @@ function buildChangeModel(manifest, currentContracts, root) {
1759
1759
  file: addedRef.file,
1760
1760
  exportName: addedRef.exportName,
1761
1761
  // Resolved from the contract this rename was declared on, not carried
1762
- // on the ref -- see `ContractRef` (`evidence-reference.ts`).
1762
+ // on the ref: see `ContractRef` (`evidence-reference.ts`).
1763
1763
  contractName: contract.contractName,
1764
1764
  previousKey: removedRef.key,
1765
1765
  currentKey: addedRef.key
@@ -1819,7 +1819,7 @@ function detectCompatibilityIssues(contracts) {
1819
1819
  variable: key,
1820
1820
  files: [a.file, b.file],
1821
1821
  code: "PROCESSOR_SOURCE_CONFLICT",
1822
- reason: `"${a.contractName}" and "${b.contractName}" both declare a processor for this variable with different implementations. Return types could not be statically verified -- add explicit return type annotations, or confirm they produce equivalent output.`
1822
+ reason: `"${a.contractName}" and "${b.contractName}" both declare a processor for this variable with different implementations. Return types could not be statically verified. Add explicit return type annotations, or confirm they produce equivalent output.`
1823
1823
  });
1824
1824
  }
1825
1825
  if (a.variable.hasValidator && b.variable.hasValidator && a.variable.validatorSource !== b.variable.validatorSource) {
@@ -1828,7 +1828,7 @@ function detectCompatibilityIssues(contracts) {
1828
1828
  variable: key,
1829
1829
  files: [a.file, b.file],
1830
1830
  code: "VALIDATOR_SOURCE_CONFLICT",
1831
- reason: `"${a.contractName}" and "${b.contractName}" both declare a validator for this variable with different implementations. Validator logic cannot be statically compared -- confirm they enforce compatible rules.`
1831
+ reason: `"${a.contractName}" and "${b.contractName}" both declare a validator for this variable with different implementations. Validator logic cannot be statically compared. Confirm they enforce compatible rules.`
1832
1832
  });
1833
1833
  }
1834
1834
  const divergences = documentationDivergences(a.variable, b.variable);
@@ -1889,7 +1889,7 @@ function detectDuplicateVariableShapes(contracts) {
1889
1889
  variable: `${a.key} / ${b.key}`,
1890
1890
  files: [a.file, b.file],
1891
1891
  code: "DUPLICATE_VARIABLE_SHAPE_ACROSS_CONTRACTS",
1892
- reason: `"${a.key}" (${a.contractName}) and "${b.key}" (${b.contractName}) declare an identical shape (type ${a.shape.valueType}, processor: ${a.shape.hasProcessor ? "yes" : "no"}, validator: ${a.shape.hasValidator ? "yes" : "no"}). Informational only -- they may be the same underlying value modelled twice, or two unrelated values that happen to look alike. Nothing is required.`
1892
+ reason: `"${a.key}" (${a.contractName}) and "${b.key}" (${b.contractName}) declare an identical shape (type ${a.shape.valueType}, processor: ${a.shape.hasProcessor ? "yes" : "no"}, validator: ${a.shape.hasValidator ? "yes" : "no"}). Informational only: they may be the same underlying value modelled twice, or two unrelated values that happen to look alike. Nothing is required.`
1893
1893
  });
1894
1894
  }
1895
1895
  }
@@ -2113,11 +2113,9 @@ function scanFileForDependencies(filePath, sourceText) {
2113
2113
  filePath,
2114
2114
  sourceText,
2115
2115
  ts.ScriptTarget.Latest,
2116
- // Load-bearing, unlike before: `ts.getCombinedNodeFlags()` (used to tell
2117
- // a `const` declaration apart from `let`/`var` when resolving alias
2118
- // candidates) walks parent pointers internally. Flipping this to `false`
2119
- // now breaks const-detection silently rather than merely being an
2120
- // unobserved no-op -- do not remove parent-pointer tracking here.
2116
+ // Load-bearing: `ts.getCombinedNodeFlags()` walks parent pointers. It
2117
+ // tells a `const` declaration from `let`/`var` when resolving alias
2118
+ // candidates. Setting this to `false` breaks const-detection silently.
2121
2119
  true,
2122
2120
  scriptKind
2123
2121
  );
@@ -2230,8 +2228,8 @@ function createGeneratedBanner(describe) {
2230
2228
  return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2231
2229
  },
2232
2230
  // Not a bare `startsWith`: a shebang, a `"use strict"` pragma or a license header pushes a real marker
2233
- // off line one, and a stricter check would read a genuinely generated file as hand-written, which a
2234
- // dependency scan would take as "a real consumer imports this" and so permanently mask an abandoned
2231
+ // off line one. A stricter check would read a genuinely generated file as hand-written. A dependency
2232
+ // scan would take that as "a real consumer imports this", and so permanently mask an abandoned
2235
2233
  // contract. The first 20 non-empty lines clear every realistic preamble without scanning a whole file.
2236
2234
  // A line counts only when the marker opens a comment, as `generatedBanner` writes it, so code or prose that
2237
2235
  // merely quotes the marker is not mistaken for a generated file.
@@ -2439,7 +2437,7 @@ function deriveOwnershipFindings(graph) {
2439
2437
  if (contract.ambiguousBarrelFiles.length > 0) {
2440
2438
  unresolvedConsumers.push({
2441
2439
  ...identity,
2442
- reason: `Not directly imported anywhere, but ${contract.ambiguousBarrelFiles.length} file(s) import "${contract.exportName}" through a specifier that resolves to a file containing an unresolved "export * from" re-export -- cannot determine whether this contract is forwarded by it. Files: ${contract.ambiguousBarrelFiles.join(", ")}.`
2440
+ reason: `Not directly imported anywhere, but ${contract.ambiguousBarrelFiles.length} file(s) import "${contract.exportName}" through a specifier that resolves to a file containing an unresolved "export * from" re-export, so whether this contract is forwarded by it cannot be determined. Files: ${contract.ambiguousBarrelFiles.join(", ")}.`
2443
2441
  });
2444
2442
  } else {
2445
2443
  abandoned.push(identity);
@@ -2461,7 +2459,7 @@ function deriveOwnershipFindings(graph) {
2461
2459
  if (info.status === "unconsumed") {
2462
2460
  unconsumedOwned.push({ ...identity, key });
2463
2461
  } else if (info.status === "indeterminate") {
2464
- const reason = info.evidence === "dynamic-access" ? `Dynamic (computed) property access was observed on "${contract.exportName}" -- cannot determine whether "${key}" is read. Searched: ${surfaces}. Dynamic access observed at: ${formatSites(contract.dynamicAccessSites)}.` : `Contract "${contract.exportName}" is used in a way this scanner's local dataflow analysis cannot follow (a rest binding, nested destructuring, a computed key, an ambiguous alias, or the contract passed/referenced directly) -- cannot determine whether "${key}" is read. Searched: ${surfaces}. Escaped at: ${formatEscapeSites(contract.escapeSites)}.`;
2462
+ const reason = info.evidence === "dynamic-access" ? `Dynamic (computed) property access was observed on "${contract.exportName}", so whether "${key}" is read cannot be determined. Searched: ${surfaces}. Dynamic access observed at: ${formatSites(contract.dynamicAccessSites)}.` : `Contract "${contract.exportName}" is used in a way this scanner's local dataflow analysis cannot follow (a rest binding, nested destructuring, a computed key, an ambiguous alias, or the contract passed/referenced directly), so whether "${key}" is read cannot be determined. Searched: ${surfaces}. Escaped at: ${formatEscapeSites(contract.escapeSites)}.`;
2465
2463
  indeterminate.push({
2466
2464
  ...identity,
2467
2465
  key,
@@ -2631,7 +2629,7 @@ function detectExclusiveGroupIssues(contracts) {
2631
2629
  severity: "error",
2632
2630
  variable: `Exclusive group "${group}"`,
2633
2631
  files: [a.file, b.file],
2634
- reason: `"${a.contractName}" and "${b.contractName}" are both active and both declare exclusiveGroup "${group}" -- only one active contract per exclusive group is allowed. Set active: false on whichever one isn't in use.`
2632
+ reason: `"${a.contractName}" and "${b.contractName}" are both active and both declare exclusiveGroup "${group}". Only one active contract per exclusive group is allowed. Set active: false on whichever one isn't in use.`
2635
2633
  });
2636
2634
  }
2637
2635
  }
@@ -2704,11 +2702,11 @@ function defaultExclude() {
2704
2702
  return [
2705
2703
  // `discoverSchemaFiles()`'s own walk (`discover.ts`) hardcodes skipping
2706
2704
  // a directory literally named "node_modules" or ".git" via its own
2707
- // `isAlwaysSkippedDirName()` check, regardless of `exclude` -- it never
2705
+ // `isAlwaysSkippedDirName()` check, regardless of `exclude`: it never
2708
2706
  // even descends into either to test a glob pattern against it. These
2709
2707
  // two entries are provably redundant (kept for readers/tooling that
2710
2708
  // inspect `exclude` directly, and as defense if that hardcoding ever
2711
- // changes) -- hand-verified: emptying both and running the full
2709
+ // changes). Hand-verified: emptying both and running the full
2712
2710
  // `vitest run` leaves all 1243 tests passing.
2713
2711
  "**/node_modules/**",
2714
2712
  "**/dist/**",
@@ -2796,7 +2794,7 @@ function renderAbandoned(findings) {
2796
2794
  const lines = [
2797
2795
  "## Abandoned ownership",
2798
2796
  "",
2799
- "Contracts never imported anywhere in the scanned repository -- a feature's schema outliving the feature.",
2797
+ "Contracts never imported anywhere in the scanned repository: a feature's schema outliving the feature.",
2800
2798
  "",
2801
2799
  "| Contract | Owner | File |",
2802
2800
  "|---|---|---|"
@@ -2811,7 +2809,7 @@ function renderUnresolvedConsumers(findings) {
2811
2809
  const lines = [
2812
2810
  "## Unresolved consumers (barrel re-exports)",
2813
2811
  "",
2814
- "Contracts reachable only through an unresolved `export * from` barrel re-export -- cannot be proven abandoned or consumed. Advisory only; never fails a build.",
2812
+ "Contracts reachable only through an unresolved `export * from` barrel re-export. They cannot be proven abandoned or consumed. Advisory only; never fails a build.",
2815
2813
  ""
2816
2814
  ];
2817
2815
  for (const f of sortedByContractName(findings))
@@ -2833,7 +2831,7 @@ function renderUnconsumedOwned(findings, scannedSurfaces) {
2833
2831
  "",
2834
2832
  `Searched: ${surfaces}.`,
2835
2833
  "",
2836
- 'A blank Stale/missing citations cell is the strongest "looks genuinely unused" signal -- no developer has ever claimed otherwise. A non-blank cell means someone specifically claimed dynamic access here via `dynamicAccess`, and that claim can no longer be verified (ADR 0037) -- check with them before deleting.',
2834
+ 'A blank Stale/missing citations cell is the strongest "looks unused" signal: no developer has ever claimed otherwise. A non-blank cell means someone specifically claimed dynamic access here via `dynamicAccess`, and that claim can no longer be verified (ADR 0037). Check with them before deleting.',
2837
2835
  "",
2838
2836
  "| Variable | Contract | Owner | Stale/missing citations |",
2839
2837
  "|---|---|---|---|"
@@ -2850,7 +2848,7 @@ function renderIndeterminate(findings) {
2850
2848
  const lines = [
2851
2849
  "## Indeterminate (dynamic access)",
2852
2850
  "",
2853
- "Dynamic (computed) property access was observed -- usage cannot be determined statically. Never guessed at.",
2851
+ "Dynamic (computed) property access was observed, so usage cannot be determined statically. Never guessed at.",
2854
2852
  "",
2855
2853
  "| Variable | Contract | Reason | Stale/missing citations |",
2856
2854
  "|---|---|---|---|"
@@ -2871,7 +2869,7 @@ function renderAsserted(findings) {
2871
2869
  const lines = [
2872
2870
  "## Asserted (developer-acknowledged dynamic access)",
2873
2871
  "",
2874
- "Variables env-cap's own scan would otherwise flag as unconsumed or indeterminate, but a developer has cited exactly where the dynamic access happens via `dynamicAccess`. The raw static status is shown alongside the citation, never hidden behind it -- a citation is a re-acknowledgment, not proof.",
2872
+ "Variables env-cap's own scan would otherwise flag as unconsumed or indeterminate, but a developer has cited exactly where the dynamic access happens via `dynamicAccess`. The raw static status is shown alongside the citation, never hidden behind it. A citation is a re-acknowledgment, not proof.",
2875
2873
  "",
2876
2874
  "| Variable | Contract | Static status | Developer assertion |",
2877
2875
  "|---|---|---|---|"
@@ -3205,7 +3203,7 @@ function buildFindingModel(input) {
3205
3203
  severity: "info",
3206
3204
  code: "NONSTANDARD_SENSITIVITY_LEVEL",
3207
3205
  family: "documentation",
3208
- message: `"${n.key ?? n.exportName}" declares sensitivity "${n.sensitivity}", which isn't one of the standard levels (secret/credential/pii/config) -- still honored verbatim, just flagged for vocabulary drift.`,
3206
+ message: `"${n.key ?? n.exportName}" declares sensitivity "${n.sensitivity}", which isn't one of the standard levels (secret/credential/pii/config). It is still honored verbatim, only flagged for vocabulary drift.`,
3209
3207
  location: {
3210
3208
  model: "contract",
3211
3209
  file: displayPath(root, n.file),
@@ -3289,7 +3287,7 @@ function buildFindingModel(input) {
3289
3287
  contractName: i.contractName,
3290
3288
  file: void 0,
3291
3289
  variable: i.key,
3292
- // Multiple candidate sites, never one representative pointer -- see
3290
+ // Multiple candidate sites, never one representative pointer: see
3293
3291
  // `IndeterminateOwnershipFinding.dynamicAccessSites` for the full list.
3294
3292
  position: NO_POSITION
3295
3293
  }
@@ -3306,12 +3304,12 @@ function buildFindingModel(input) {
3306
3304
  model: "ownership",
3307
3305
  contractName: p.contractName,
3308
3306
  // p.file (DynamicAccessCitationProblem.file) is already
3309
- // root-relative -- unlike every other .file above, not a raw
3310
- // absolute path -- so no displayPath() conversion here.
3307
+ // root-relative (unlike every other .file above, not a raw
3308
+ // absolute path) so no displayPath() conversion here.
3311
3309
  file: p.file,
3312
3310
  variable: p.key,
3313
3311
  // The one ownership-family finding with a genuinely meaningful
3314
- // position -- exactly where the (now-stale/missing) citation points.
3312
+ // position: exactly where the (now-stale/missing) citation points.
3315
3313
  position: p.position
3316
3314
  }
3317
3315
  });
@@ -3348,7 +3346,7 @@ function defineEvidenceProjection(schema) {
3348
3346
  }
3349
3347
  function readOnlyMembraneError() {
3350
3348
  return new TypeError(
3351
- "EvidenceModel is read-only inside a projector -- a projection must be a pure function of its evidence argument. See ADR 0032."
3349
+ "EvidenceModel is read-only inside a projector. A projection must be a pure function of its evidence argument. See ADR 0032."
3352
3350
  );
3353
3351
  }
3354
3352
  function createTrackingProxy(evidence) {
@@ -4081,7 +4079,7 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
4081
4079
  lines.push(
4082
4080
  ...renderVariableLines(dup.variable, {
4083
4081
  commented: true,
4084
- note: `Also declared by "${dup.contract.contractName}" -- see "${first.contract.contractName}" above.`
4082
+ note: `Also declared by "${dup.contract.contractName}". See "${first.contract.contractName}" above.`
4085
4083
  })
4086
4084
  );
4087
4085
  }
@@ -4093,7 +4091,7 @@ function renderEnvExample(contracts, reconciliationHeader = []) {
4093
4091
  lines.push(
4094
4092
  ...renderVariableLines(first.variable, {
4095
4093
  commented: true,
4096
- note: `Disabled -- feature "${first.contract.contractName}" is not active.`
4094
+ note: `Disabled: feature "${first.contract.contractName}" is not active.`
4097
4095
  })
4098
4096
  );
4099
4097
  }
@@ -4495,7 +4493,7 @@ function buildOwnershipModel(contracts, root) {
4495
4493
 
4496
4494
  // src/build/tool-version.ts
4497
4495
  function readToolVersion() {
4498
- return "0.7.5";
4496
+ return "0.7.7";
4499
4497
  }
4500
4498
 
4501
4499
  // src/build/generate-evidence.ts
@@ -5012,7 +5010,7 @@ async function checkEnvArtifacts(options) {
5012
5010
  path: c.docs.envExamplePath,
5013
5011
  status: driftCount > 0 ? "stale" : "ok",
5014
5012
  // exactOptionalPropertyTypes: omit the key entirely rather than
5015
- // set it to `undefined` -- `detail` is absent when there's
5013
+ // set it to `undefined`; `detail` is absent when there's
5016
5014
  // nothing to report, not present-but-empty.
5017
5015
  ...driftCount > 0 ? {
5018
5016
  detail: `${staleVariables.length} stale, ${variablesToComment.length} to comment, ${variablesToAdd.length} to add`
@@ -5079,9 +5077,9 @@ function buildSarifLog(findingModel) {
5079
5077
  rules: ruleIds.map((id) => ({ id }))
5080
5078
  }
5081
5079
  },
5082
- // exactOptionalPropertyTypes: spread `locations` in only when
5083
- // sarifLocations() actually has one, rather than ever setting the
5084
- // key to `undefined` explicitly.
5080
+ // Under `exactOptionalPropertyTypes` the key must be absent, never
5081
+ // `undefined`. So `locations` is spread in only when
5082
+ // `sarifLocations()` has one.
5085
5083
  results: findingModel.findings.map((finding) => {
5086
5084
  const locations = sarifLocations(finding);
5087
5085
  return {