@agentvibes/guardrails 0.2.7 → 0.3.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 (265) hide show
  1. package/README.md +252 -5
  2. package/candidates/README.md +13 -13
  3. package/candidates/r10-as-cast.yml +4 -4
  4. package/candidates/r1d-scattered-numeric-const-in-component.yml +3 -3
  5. package/candidates/r2-helper-fn-in-tsx.yml +3 -3
  6. package/candidates/r3-hooks-outside-layout.yml +4 -4
  7. package/candidates/r6-jsx-comment-smell.yml +2 -2
  8. package/candidates/r7-raw-hsl-outside-tokens.yml +3 -3
  9. package/candidates/r8-inline-style-prop.yml +2 -2
  10. package/candidates/r9-optional-store-arg.yml +2 -2
  11. package/dist/astGrep.js +4 -2
  12. package/dist/astGrep.js.map +1 -1
  13. package/dist/cli.js +89 -6
  14. package/dist/cli.js.map +1 -1
  15. package/dist/cliArgsTest.d.ts +1 -0
  16. package/dist/cliArgsTest.js +44 -0
  17. package/dist/cliArgsTest.js.map +1 -0
  18. package/dist/doctor.d.ts +1 -1
  19. package/dist/doctor.js +58 -6
  20. package/dist/doctor.js.map +1 -1
  21. package/dist/fileSloc.d.ts +28 -0
  22. package/dist/fileSloc.js +72 -0
  23. package/dist/fileSloc.js.map +1 -0
  24. package/dist/fileSlocBaseline.d.ts +78 -0
  25. package/dist/fileSlocBaseline.js +173 -0
  26. package/dist/fileSlocBaseline.js.map +1 -0
  27. package/dist/fileSlocGate.d.ts +17 -0
  28. package/dist/fileSlocGate.js +75 -0
  29. package/dist/fileSlocGate.js.map +1 -0
  30. package/dist/fileSlocTest.d.ts +1 -0
  31. package/dist/fileSlocTest.js +172 -0
  32. package/dist/fileSlocTest.js.map +1 -0
  33. package/dist/fileWalk.js +1 -1
  34. package/dist/fileWalk.js.map +1 -1
  35. package/dist/findings.d.ts +1 -1
  36. package/dist/gateRed.d.ts +1 -1
  37. package/dist/gateRed.js +1 -0
  38. package/dist/gateRed.js.map +1 -1
  39. package/dist/gitDiff.d.ts +6 -0
  40. package/dist/gitDiff.js +25 -0
  41. package/dist/gitDiff.js.map +1 -1
  42. package/dist/hookStop.d.ts +2 -1
  43. package/dist/hookStop.js +7 -1
  44. package/dist/hookStop.js.map +1 -1
  45. package/dist/hookStopTest.d.ts +1 -1
  46. package/dist/hookStopTest.js +1 -0
  47. package/dist/hookStopTest.js.map +1 -1
  48. package/dist/init.js +1 -1
  49. package/dist/init.js.map +1 -1
  50. package/dist/initTest.d.ts +1 -1
  51. package/dist/initTest.js +2 -1
  52. package/dist/initTest.js.map +1 -1
  53. package/dist/iterateTest.d.ts +1 -1
  54. package/dist/iterateTest.js +1 -0
  55. package/dist/iterateTest.js.map +1 -1
  56. package/dist/jsxSuppress.js +1 -1
  57. package/dist/jsxSuppress.js.map +1 -1
  58. package/dist/jsxSuppressTest.d.ts +1 -1
  59. package/dist/jsxSuppressTest.js +4 -2
  60. package/dist/jsxSuppressTest.js.map +1 -1
  61. package/dist/leaksRed.d.ts +1 -1
  62. package/dist/leaksRed.js +1 -0
  63. package/dist/leaksRed.js.map +1 -1
  64. package/dist/metrics.d.ts +9 -0
  65. package/dist/metrics.js +96 -7
  66. package/dist/metrics.js.map +1 -1
  67. package/dist/metricsBaseline.js +1 -1
  68. package/dist/metricsBaseline.js.map +1 -1
  69. package/dist/metricsCollect.js +2 -45
  70. package/dist/metricsCollect.js.map +1 -1
  71. package/dist/metricsCycle.d.ts +1 -1
  72. package/dist/metricsCycle.js +1 -0
  73. package/dist/metricsCycle.js.map +1 -1
  74. package/dist/metricsTypes.d.ts +1 -1
  75. package/dist/overrideDeclarations.d.ts +35 -0
  76. package/dist/overrideDeclarations.js +94 -0
  77. package/dist/overrideDeclarations.js.map +1 -0
  78. package/dist/overrides.d.ts +35 -0
  79. package/dist/overrides.js +284 -0
  80. package/dist/overrides.js.map +1 -0
  81. package/dist/overridesTest.d.ts +1 -0
  82. package/dist/overridesTest.js +183 -0
  83. package/dist/overridesTest.js.map +1 -0
  84. package/dist/pipeOutputTest.d.ts +1 -1
  85. package/dist/pipeOutputTest.js +2 -1
  86. package/dist/pipeOutputTest.js.map +1 -1
  87. package/dist/presetDrift.d.ts +8 -0
  88. package/dist/presetDrift.js +91 -34
  89. package/dist/presetDrift.js.map +1 -1
  90. package/dist/presetDriftTest.d.ts +1 -1
  91. package/dist/presetDriftTest.js +3 -3
  92. package/dist/presetDriftTest.js.map +1 -1
  93. package/dist/record/config.d.ts +17 -0
  94. package/dist/record/config.js +83 -0
  95. package/dist/record/config.js.map +1 -0
  96. package/dist/record/index.d.ts +69 -0
  97. package/dist/record/index.js +8 -0
  98. package/dist/record/index.js.map +1 -0
  99. package/dist/record/record.d.ts +56 -0
  100. package/dist/record/record.js +111 -0
  101. package/dist/record/record.js.map +1 -0
  102. package/dist/record/repoKey.d.ts +8 -0
  103. package/dist/record/repoKey.js +70 -0
  104. package/dist/record/repoKey.js.map +1 -0
  105. package/dist/record/repoMetrics.d.ts +14 -0
  106. package/dist/record/repoMetrics.js +124 -0
  107. package/dist/record/repoMetrics.js.map +1 -0
  108. package/dist/record/runRecord.d.ts +60 -0
  109. package/dist/record/runRecord.js +2 -0
  110. package/dist/record/runRecord.js.map +1 -0
  111. package/dist/record/schema.d.ts +31 -0
  112. package/dist/record/schema.js +201 -0
  113. package/dist/record/schema.js.map +1 -0
  114. package/dist/record/writer.d.ts +22 -0
  115. package/dist/record/writer.js +341 -0
  116. package/dist/record/writer.js.map +1 -0
  117. package/dist/recordTest.d.ts +1 -0
  118. package/dist/recordTest.js +422 -0
  119. package/dist/recordTest.js.map +1 -0
  120. package/dist/renameDiffTest.d.ts +1 -1
  121. package/dist/renameDiffTest.js +2 -1
  122. package/dist/renameDiffTest.js.map +1 -1
  123. package/dist/repoRules.js +1 -1
  124. package/dist/repoRules.js.map +1 -1
  125. package/dist/repoRulesTest.d.ts +1 -1
  126. package/dist/repoRulesTest.js +2 -1
  127. package/dist/repoRulesTest.js.map +1 -1
  128. package/dist/screenScope.js +4 -5
  129. package/dist/screenScope.js.map +1 -1
  130. package/dist/screenScopeTest.d.ts +1 -1
  131. package/dist/screenScopeTest.js +2 -1
  132. package/dist/screenScopeTest.js.map +1 -1
  133. package/dist/severityTest.d.ts +1 -1
  134. package/dist/severityTest.js +1 -0
  135. package/dist/severityTest.js.map +1 -1
  136. package/dist/siblingCloneTest.js +12 -12
  137. package/dist/siblingCloneTest.js.map +1 -1
  138. package/dist/snapshot.d.ts +2 -0
  139. package/dist/snapshot.js +118 -0
  140. package/dist/snapshot.js.map +1 -0
  141. package/dist/snapshotTest.d.ts +1 -0
  142. package/dist/snapshotTest.js +194 -0
  143. package/dist/snapshotTest.js.map +1 -0
  144. package/dist/structure.js +2 -2
  145. package/dist/structure.js.map +1 -1
  146. package/dist/testIsolation.d.ts +1 -0
  147. package/dist/testIsolation.js +7 -0
  148. package/dist/testIsolation.js.map +1 -0
  149. package/dist/testPaths.d.ts +4 -0
  150. package/dist/testPaths.js +9 -0
  151. package/dist/testPaths.js.map +1 -0
  152. package/dist/testRules.js +33 -3
  153. package/dist/testRules.js.map +1 -1
  154. package/dist/time.d.ts +22 -0
  155. package/dist/time.js +77 -0
  156. package/dist/time.js.map +1 -0
  157. package/dist/timeTest.d.ts +1 -0
  158. package/dist/timeTest.js +103 -0
  159. package/dist/timeTest.js.map +1 -0
  160. package/dist/tomlTable.d.ts +1 -1
  161. package/dist/tomlTable.js +6 -3
  162. package/dist/tomlTable.js.map +1 -1
  163. package/dist/toolResolve.d.ts +6 -0
  164. package/dist/toolResolve.js +18 -0
  165. package/dist/toolResolve.js.map +1 -1
  166. package/dist/twinCoverageTest.js +2 -20
  167. package/dist/twinCoverageTest.js.map +1 -1
  168. package/dist/verify.d.ts +2 -1
  169. package/dist/verify.js +33 -5
  170. package/dist/verify.js.map +1 -1
  171. package/dist/verifyDiff.d.ts +3 -2
  172. package/dist/verifyDiff.js +58 -8
  173. package/dist/verifyDiff.js.map +1 -1
  174. package/dist/wiring.d.ts +31 -0
  175. package/dist/wiring.js +262 -0
  176. package/dist/wiring.js.map +1 -0
  177. package/dist/wiringTest.d.ts +1 -0
  178. package/dist/wiringTest.js +127 -0
  179. package/dist/wiringTest.js.map +1 -0
  180. package/package.json +18 -6
  181. package/rules/__fixtures__/demo-mode-by-default/bad.ts +1 -1
  182. package/rules/__fixtures__/demo-mode-by-default/bad.tsx +1 -1
  183. package/rules/__fixtures__/direct-store-import/bad.tsx +1 -1
  184. package/rules/__fixtures__/direct-store-import/good.tsx +2 -2
  185. package/rules/__fixtures__/discriminator-ternary/bad.ts +9 -0
  186. package/rules/__fixtures__/discriminator-ternary/bad.tsx +1 -1
  187. package/rules/__fixtures__/discriminator-ternary/good.ts +17 -0
  188. package/rules/__fixtures__/discriminator-ternary/good.tsx +1 -1
  189. package/rules/__fixtures__/hardcoded-url-in-component/components/bad.ts +9 -0
  190. package/rules/__fixtures__/hardcoded-url-in-component/components/good.ts +13 -0
  191. package/rules/__fixtures__/inline-map-row/bad.tsx +1 -1
  192. package/rules/__fixtures__/inline-map-row/good.tsx +1 -1
  193. package/rules/__fixtures__/match-bool-to-null/bad.ts +14 -0
  194. package/rules/__fixtures__/match-bool-to-null/bad.tsx +8 -0
  195. package/rules/__fixtures__/match-bool-to-null/good.ts +12 -0
  196. package/rules/__fixtures__/match-bool-to-null/good.tsx +12 -0
  197. package/rules/__fixtures__/missing-observer/bad.tsx +2 -2
  198. package/rules/__fixtures__/missing-observer/good.tsx +2 -2
  199. package/rules/__fixtures__/no-local-kit-clone/bad.ts +2 -2
  200. package/rules/__fixtures__/no-local-kit-clone/bad.tsx +2 -2
  201. package/rules/__fixtures__/state-loading-boolean-shape/good.ts +1 -1
  202. package/rules/__fixtures__/state-loading-boolean-shape/good.tsx +1 -1
  203. package/rules/__fixtures__/store-async-method/good.ts +1 -1
  204. package/rules/__fixtures__/store-async-method/good.tsx +1 -1
  205. package/rules/__fixtures__/store-context-provider/bad.ts +1 -1
  206. package/rules/__fixtures__/store-delegation-getter/bad.ts +1 -1
  207. package/rules/__fixtures__/store-delegation-getter/bad.tsx +1 -1
  208. package/rules/__fixtures__/store-delegation-getter/good.ts +3 -3
  209. package/rules/__fixtures__/store-delegation-getter/good.tsx +3 -3
  210. package/rules/__fixtures__/store-no-runinaction/bad.ts +1 -1
  211. package/rules/__fixtures__/store-no-runinaction/bad.tsx +1 -1
  212. package/rules/__fixtures__/store-no-runinaction/good.ts +1 -1
  213. package/rules/__fixtures__/store-no-runinaction/good.tsx +1 -1
  214. package/rules/__fixtures__/ts-pattern-dangling-match/bad.ts +1 -1
  215. package/rules/__fixtures__/ts-pattern-dangling-match/good.ts +2 -2
  216. package/rules/__fixtures__/ui-imports-app-store/src/ui/bad.ts +11 -0
  217. package/rules/__fixtures__/ui-imports-app-store/src/ui/good.ts +13 -0
  218. package/rules/__fixtures__/ui-imports-app-store/src/ui/good.tsx +1 -1
  219. package/rules/__fixtures__/view-imports-store/good.view.tsx +1 -1
  220. package/rules/as-any-escape-tsx.yml +2 -2
  221. package/rules/as-any-escape.yml +2 -2
  222. package/rules/catch-empty-tsx.yml +3 -3
  223. package/rules/catch-empty.yml +3 -3
  224. package/rules/demo-mode-by-default-ts.yml +6 -7
  225. package/rules/demo-mode-by-default.yml +6 -7
  226. package/rules/direct-store-import.yml +15 -16
  227. package/rules/discriminator-ternary-ts.yml +46 -0
  228. package/rules/discriminator-ternary.yml +3 -3
  229. package/rules/hardcoded-url-in-component-ts.yml +40 -0
  230. package/rules/hardcoded-url-in-component.yml +5 -8
  231. package/rules/inline-map-row.yml +7 -7
  232. package/rules/instanceof-map-set-tsx.yml +2 -2
  233. package/rules/instanceof-map-set.yml +2 -2
  234. package/rules/kind-if-without-match-tsx.yml +1 -1
  235. package/rules/literal-union-in-component-tsx.yml +2 -2
  236. package/rules/literal-union-in-component.yml +7 -7
  237. package/rules/match-bool-to-null-ts.yml +27 -0
  238. package/rules/missing-observer.yml +5 -5
  239. package/rules/no-local-kit-clone-tsx.yml +2 -2
  240. package/rules/no-local-kit-clone.yml +2 -2
  241. package/rules/non-exhaustive-match-tsx.yml +4 -7
  242. package/rules/non-exhaustive-match.yml +2 -2
  243. package/rules/page-store-bare-usememo-tsx.yml +1 -1
  244. package/rules/page-store-bare-usememo.yml +1 -1
  245. package/rules/screen-file-styling.yml +3 -3
  246. package/rules/silent-default-return-tsx.yml +1 -1
  247. package/rules/store-async-method-tsx.yml +1 -1
  248. package/rules/store-async-method.yml +1 -1
  249. package/rules/store-context-provider-tsx.yml +3 -3
  250. package/rules/store-context-provider.yml +5 -5
  251. package/rules/store-delegation-getter-tsx.yml +2 -2
  252. package/rules/store-delegation-getter.yml +2 -2
  253. package/rules/store-no-runinaction-tsx.yml +2 -2
  254. package/rules/store-no-runinaction.yml +2 -2
  255. package/rules/store-no-setinterval-poll-tsx.yml +1 -1
  256. package/rules/store-no-setinterval-poll.yml +1 -1
  257. package/rules/ts-pattern-dangling-match-tsx.yml +4 -4
  258. package/rules/ts-pattern-dangling-match.yml +4 -4
  259. package/rules/ui-imports-app-store-ts.yml +61 -0
  260. package/rules/ui-imports-app-store.yml +1 -1
  261. package/rules/view-file-logic.yml +5 -5
  262. package/rules/view-imports-store.yml +4 -5
  263. package/rules/zod-optional-nullable-tsx.yml +2 -2
  264. package/rules/zod-optional-nullable.yml +2 -2
  265. package/structure/rules/component-decl.yml +1 -1
package/README.md CHANGED
@@ -47,10 +47,12 @@ All subcommands accept `--json`.
47
47
  | command | what | exit |
48
48
  |---|---|---|
49
49
  | `guardrails verify [paths]` | full scan: rule canon + text-greps + structure (one component per file, 120-line error / 90-line warning) | 1 on any error-tier finding |
50
- | `guardrails verify-diff [--base R]` | ratchet: error-tier findings on lines your diff ADDED vs merge-base; falls back to whole-file, then whole-tree — never to silence | 1 on new findings only |
50
+ | `guardrails verify-diff [--base R]` | ratchet: error-tier findings on lines your diff ADDED vs merge-base; falls back to whole-file, then whole-tree — never to silence; also judges every file the diff grew against the [per-file length ratchet](#per-file-length-ratchet) | 1 on new findings only |
51
51
  | `guardrails doctor` | tool versions + resolution route, ruleset SHA, config discovery | 1 if a tool is missing |
52
52
  | `guardrails init` | writes `sgconfig.yml`, `biome.json` (extends the preset), and a detected-and-materialized `[stack]` in `.agentvibes/project.toml` | 0 |
53
- | `guardrails metrics [paths]` | per-component (loc, hooks, props, observer, JSX depth, branching), per-file (sloc, context-cost) and per-project metrics; `--check` compares the GATED set against the committed `.guardrails/metrics.json` baseline (recomputes facts, never trusts the file); `--update-baseline` tightens it (2% hysteresis, never loosens without `--force`); `--snapshot` appends a JSONL trend row | 1 on ratchet regression, 2 when `--check` finds no baseline |
53
+ | `guardrails metrics [paths]` | per-component (loc, hooks, props, observer, JSX depth, branching), per-file (sloc, context-cost) and per-project metrics; `--check` compares the GATED set against the committed `.guardrails/metrics.json` baseline (recomputes facts, never trusts the file); `--update-baseline` tightens it (2% hysteresis, never loosens without `--force`); `--snapshot` appends a JSONL trend row. Both `--check` and `--update-baseline` also run the [per-file length ratchet](#per-file-length-ratchet) | 1 on ratchet regression, 2 when `--check` finds no baseline or the length threshold is invalid |
54
+ | `guardrails snapshot [path]` | records one checkout (default `.`) into the [recording database](#recording), whether or not that repo uses guardrails; writes nothing into it | 2 when the path is not a directory or the record cannot be written; never 1 |
55
+ | `guardrails time [--name N] -- CMD` | runs CMD with its output passed through; while [recording](#recording), stores its wall-clock time in ms as metric N (default `build_ms`) when it exits 0 | CMD's own exit code; 127 when CMD cannot start; 2 on a usage error |
54
56
 
55
57
  Gated (ratchet, lower = better): p90 component_loc, useState density,
56
58
  inline-map-row count, p90 context-cost, runInAction count, async-in-store,
@@ -72,6 +74,51 @@ where the outcome is recorded twice (loading flag + second outcome/payload
72
74
  field), while the metric also counts lone boolean progress-flag declarations
73
75
  (`loading = false` class fields) — the wider Resource<T> migration target.
74
76
 
77
+ ## Per-file length ratchet
78
+
79
+ No production file may hold more than **500 SLOC** (lines minus imports,
80
+ blank lines and comment-only lines — the `file_sloc` that `metrics` reports).
81
+ Test files, stories, showcases and `.d.ts` files are excluded, as for every
82
+ metric. So is every file in a test directory (`tests/`, `test/`, `e2e/`,
83
+ `spec/`, `__tests__/`, `__e2e__/`, `__mocks__/`), such as a shared harness or an
84
+ end-to-end script; the recorded `files_over_sloc_limit` counts the same files.
85
+ Files that were already longer when a repo adopted the ratchet are
86
+ listed in a committed baseline, `.guardrails/file-sloc.json`, each with its own
87
+ ceiling:
88
+
89
+ ```json
90
+ { "version": 1, "threshold": 500, "files": { "src/legacy/bigStore.ts": 812 } }
91
+ ```
92
+
93
+ - A listed file fails when it grows past its ceiling.
94
+ - Any other file fails when it crosses the threshold (exactly 500 passes).
95
+ - `guardrails metrics --update-baseline` lowers a ceiling as soon as its file
96
+ shrinks (no hysteresis: SLOC is an exact count), and drops the entry once the
97
+ file is back under the threshold or deleted. It never raises a ceiling and
98
+ never lists a new file; only the first creation and `--force` do, and that
99
+ diff is reviewed like any other loosening.
100
+ - A renamed listed file keeps its ceiling: renames since the merge base are
101
+ followed by `verify-diff`, `metrics --check` and `--update-baseline`.
102
+
103
+ Where it runs: `guardrails metrics --check` judges every file in its targets;
104
+ `guardrails verify-diff` (and so `hook-stop`) judges only the files the diff
105
+ grew — untracked files and files with added lines on the added-lines rung,
106
+ every changed file on the whole-file rung, every file on the whole-tree rung.
107
+ A pure rename or a deletions-only edit is not judged. Without a baseline file
108
+ nothing is grandfathered: run `guardrails metrics --update-baseline` once and
109
+ commit `.guardrails/file-sloc.json` next to `metrics.json`.
110
+
111
+ The threshold is configurable; a value that is not a positive integer exits 2
112
+ instead of falling back to the default:
113
+
114
+ ```toml
115
+ # .agentvibes/project.toml
116
+ [metrics]
117
+ max_file_sloc = 400
118
+ ```
119
+
120
+ `GUARDRAILS_MAX_FILE_SLOC` in the environment overrides the file.
121
+
75
122
  ## CI gate (reusable workflow)
76
123
 
77
124
  Add the whole gate as one job:
@@ -99,7 +146,7 @@ the relative escapes resolve. **Each sibling path is removed and re-cloned on
99
146
  every run.** A self-hosted runner keeps its `_work` directory between jobs and
100
147
  `actions/checkout` cleans only its own path, so the leftovers used to make the
101
148
  step exit 128 on every run after the first — before install, so the ratchet
102
- showed as `skipped` rather than as not-run (is-8774fe0e). Re-cloning also keeps
149
+ showed as `skipped` rather than as not-run. Re-cloning also keeps
103
150
  the sibling current: gating against last week's sibling is a wrong answer, not
104
151
  a cheap one. Listing the repo under test in `sibling_repos` is refused — that
105
152
  path holds the run's own checkout. Private siblings additionally need
@@ -222,7 +269,7 @@ than restyling: `$schema`, `files` (a repo decides which of ITS paths are
222
269
  linted), a language block such as `css.parser.tailwindDirectives`, and an
223
270
  `overrides` entry that only turns `suspicious.noConsole` off for some paths (a
224
271
  CLI has to print) or `suspicious.noEmptyBlockStatements` off for TEST paths.
225
- The owner ruled on 2026-10-05 (epic is-a70a5963) that a key is allowed exactly
272
+ A key is allowed exactly
226
273
  when this check allows it, so this list and the code are one rulebook.
227
274
 
228
275
  **Drift gates everywhere.** `verify` exits 2 and `doctor` exits 1, with the
@@ -234,6 +281,206 @@ inert and can be deleted. Valid and invalid example trees are in
234
281
  The reusable gate workflow runs `verify-diff`, not `verify`, so a repo should
235
282
  add a `guardrails doctor` (or `verify`) step to its own CI to gate drift there.
236
283
 
284
+ A rule the list above does not allow becomes legal when the repo declares it
285
+ with a reason (see "Overrides" below): an `[[override]]` with
286
+ `kind = "biome-rule"`, the same `<group>/<rule>`, the override entry's
287
+ `includes` exactly as `paths` (none for a repo-wide `linter.rules`), and a
288
+ non-empty `reason`. A top-level `linter` is then allowed only when it holds
289
+ nothing but declared `rules`. A declaration with other paths or no reason does
290
+ not count, and `extends`, the formatter keys, `assist` and a second config are
291
+ never escapable: they fork the preset.
292
+
293
+ ## Overrides
294
+
295
+ An override is any place a repo deviates from the canon. `guardrails verify`
296
+ and `guardrails doctor` list every one with its reason. Each override is a
297
+ warning finding, `canon-overridden`, even when it has a reason: the reason makes
298
+ the deviation legitimate, not invisible. A reason-less one is a second warning,
299
+ `override-without-reason`. Warnings do not change an exit code. A repo that is
300
+ wired but overrides anything counts as partially wired, not fully wired.
301
+ `verify --json` and `doctor --json` carry the list as `overrides`; from
302
+ code, `collectOverrides(root)` from `@agentvibes/guardrails/overrides` returns it.
303
+
304
+ | kind | what | where the reason goes |
305
+ |---|---|---|
306
+ | `ast-grep-ignore` | `// ast-grep-ignore: <id>[, <id>]`, `/* … */`, the JSX form `{/* … */}`, and the bare `// ast-grep-ignore` (every rule, listed as `*`) | in the comment: `-- <why>` after the ids |
307
+ | `biome-ignore` | `// biome-ignore[-all\|-start] lint/<group>/<rule>` | in the comment: `: <why>`; biome's placeholder `<explanation>` is not a reason |
308
+ | `verify-scope` | `[verify] screens`, `kit_source`, `exclude` | `[[override]]`, `rule` = the key |
309
+ | `biome-rule` | a rule in a `biome.json` `overrides` entry or in `linter.rules`, `noConsole` included | `[[override]]`, `rule` = `<group>/<rule>`, `paths` = the entry's `includes` |
310
+ | `repo-rule-shadow` | a rule in a repo `ruleDir` that reuses a canon rule id | `[[override]]`, `rule` = the id |
311
+ | `metrics-limit` | `[metrics] max_file_sloc` above the default 500 | `[[override]]`, `rule = "max_file_sloc"` |
312
+
313
+ ```toml
314
+ # .agentvibes/project.toml
315
+ [[override]]
316
+ kind = "biome-rule"
317
+ rule = "suspicious/noUndeclaredEnvVars"
318
+ paths = ["**/scripts/**"]
319
+ reason = "deploy scripts read env set by the CI runner"
320
+ ```
321
+
322
+ Not overrides: a `[severity]` raise and a lower `max_file_sloc` make the gate
323
+ stricter, and a severity lowering is refused outright. A declaration that
324
+ matches nothing in the repo is a warning, `override-declared-unused`. An
325
+ `[[override]]` table that does not parse, or names an unknown kind or key, is
326
+ drift: `verify` exits 2 and `doctor` exits 1 with the entry named.
327
+
328
+ Inline directives are read only where they start a line. A directive after code
329
+ on the same line is not listed. Text that looks like a directive at the start of
330
+ a line inside a template string is listed, because the scan does not parse
331
+ strings.
332
+
333
+ ## Wiring
334
+
335
+ `guardrails doctor` reports whether guardrails actually runs in the repo, as
336
+ separate checks, each with its evidence (`doctor --json` → `wiring`; from
337
+ code, `detectWiring(root)` from `@agentvibes/guardrails/wiring`):
338
+
339
+ | check | passes when |
340
+ |---|---|
341
+ | `installed` | the root `package.json` lists `@agentvibes/guardrails` in `dependencies` or `devDependencies` |
342
+ | `sgconfig-canon` | `sgconfig.yml` `ruleDirs` lists `node_modules/@agentvibes/guardrails/rules`, so editors and bare `ast-grep` runs see the canon |
343
+ | `lint-script` | the `lint` or `check` script runs `guardrails verify\|verify-diff\|doctor\|metrics\|leaks`, directly, through one other package script, or through one file it runs (`scripts/lint/gate.sh`) |
344
+ | `ci` | a file in `.github/workflows`, `.gitea/workflows` or `.gitlab-ci.yml` uses the reusable gate, runs guardrails, or runs the lint script that passed above |
345
+ | `hook-postedit` | `.claude/settings.json` has a `PostToolUse` hook whose command runs `guardrails hook-postedit`, through any wrapper |
346
+ | `hook-stop` | the same for a `Stop` hook and `guardrails hook-stop` |
347
+ | `preset` | no undeclared biome preset drift |
348
+
349
+ The state is `on` when every check passes AND the repo has no override of the
350
+ canon (see "Overrides"); `off` when nothing but the preset check passes;
351
+ `partial` otherwise, which includes "fully wired, but overrides something".
352
+ Wiring is a report: it never changes `doctor`'s exit code, which stays the
353
+ tools-and-drift verdict.
354
+
355
+ ## Recording
356
+
357
+ guardrails can write what each run saw into a SQLite database, one row per
358
+ run, for dashboards and terminal views that compare many repos. Recording is
359
+ off unless you turn it on.
360
+
361
+ | `GUARDRAILS_RECORD` | effect |
362
+ |---|---|
363
+ | unset, empty or `0` | nothing is recorded |
364
+ | `1` | record to the configured database, else the default one |
365
+ | a path (`~/` is expanded) | record to that database |
366
+
367
+ - Configured database: `[record] db = "<path>"` in
368
+ `$XDG_CONFIG_HOME/agentvibes/guardrails.toml` (`~/.config/…` when
369
+ `XDG_CONFIG_HOME` is unset). Any other key under `[record]` is an error.
370
+ - Default database: `$XDG_STATE_HOME/agentvibes/guardrails.sqlite`
371
+ (`~/.local/state/…` when unset). The directory is created on first write.
372
+
373
+ `verify`, `verify-diff`, `metrics`, `hook-stop` and `time` record. `hook-postedit`,
374
+ `doctor`, `init`, `leaks`, `deploy` and `iterate` do not. A database that
375
+ cannot be written prints one line on stderr and never changes the exit code:
376
+ a state database is not a gate.
377
+
378
+ `guardrails snapshot [path]` always records: with `GUARDRAILS_RECORD`
379
+ unset it uses the configured or default database. It measures every part
380
+ over the whole checkout, each on its own: a part that fails (preset drift, a
381
+ repo `sgconfig.yml` pointing at a canon that is not installed, a bad
382
+ `[[override]]` table) is recorded `unavailable` with the reason, and the
383
+ rest is still recorded. So a repo that does not use guardrails gets wiring
384
+ `off` and its metrics. It writes nothing into the repo, and a relative
385
+ `GUARDRAILS_RECORD` path is resolved where the command was typed. To record
386
+ many repos: `for r in ~/src/*/; do guardrails snapshot "$r"; done`. Node 22.13 or later is needed
387
+ (`node:sqlite`); it is loaded only when a run records.
388
+
389
+ Readers import `SCHEMA_VERSION`, the table and column maps and row types from
390
+ `@agentvibes/guardrails/record`. The database is in WAL mode, so a reader can
391
+ read while a run writes; writers wait up to 5 s for each other.
392
+
393
+ ### What a run measures
394
+
395
+ A run records four parts. Each is `measured` (over the `full` checkout, a
396
+ `diff`, or given `paths`), `unavailable` (attempted, failed; with the
397
+ reason), or `skipped` (this command does not measure it).
398
+
399
+ | command | findings | overrides | wiring | metrics |
400
+ |---|---|---|---|---|
401
+ | `verify` | all tiers, `full` or `paths` | same scope | `full` | skipped |
402
+ | `verify-diff` | error tier only, `diff` | `full` | `full` | skipped |
403
+ | `hook-stop` | error tier only, `diff` | skipped | skipped | skipped |
404
+ | `metrics` | skipped | skipped | skipped | `full` or `paths` |
405
+ | `snapshot` | all tiers, `full` | `full` | `full` | `full` |
406
+ | `time` | skipped | skipped | skipped | `full` (one metric), or `unavailable` when CMD did not exit 0 |
407
+
408
+ ### Schema (version 1)
409
+
410
+ Times are ISO-8601 UTC text. Booleans are `0`/`1`. `NULL` means "not
411
+ measured", never zero. The schema version is `PRAGMA user_version`; a newer
412
+ version than this guardrails knows is refused, never written.
413
+
414
+ **History tables** (appended, never rewritten):
415
+
416
+ | table | one row per | columns |
417
+ |---|---|---|
418
+ | `repos` | repo | `key` (unique), `host`, `owner`, `name` |
419
+ | `runs` | run | `repo_id`, `at`, `command`, `root`, `sha`, `branch`, `duration_ms`, `exit_code`, `guardrails_version`, `node_version`, `ast_grep_version`, `biome_version`, `wiring`, `errors`, `warnings`, `overrides`, `overrides_without_reason` |
420
+ | `run_parts` | run × part | `run_id`, `part` (`findings`/`overrides`/`wiring`/`metrics`), `status` (`measured`/`unavailable`/`skipped`), `scope` (`full`/`diff`/`paths`), `reason` |
421
+ | `run_wiring` | run × wiring check | `run_id`, `check_id`, `pass`, `detail` |
422
+ | `run_rule_counts` | run × rule × tier × source | `run_id`, `rule`, `tier`, `source`, `count` |
423
+ | `run_findings` | finding, at most 200 per run, errors first | `run_id`, `rule`, `tier`, `source`, `file`, `line`, `message` |
424
+ | `run_overrides` | override | `run_id`, `kind`, `rule`, `where`, `file`, `line`, `reason`, `has_reason` |
425
+
426
+ The repo key is `host/owner/name` from the `origin` remote: lowercase,
427
+ without `.git`, without `user:token@`, without a port. The scp form
428
+ (`git@host:owner/name`) and `ssh://` are read too. A GitLab subgroup stays in
429
+ the owner (`group/sub`). A checkout with no usable origin is
430
+ `local/<directory>`.
431
+
432
+ `runs.errors` and `runs.warnings` count code findings only: the
433
+ `canon-overridden` and `override-without-reason` warnings restate
434
+ `runs.overrides`, so they are counted there, and kept by source in
435
+ `run_rule_counts`. `runs.warnings` is `NULL` for an error-tier-only run.
436
+
437
+ **Latest tables**, for faceted browsers: one row per entity, refreshed for a
438
+ repo inside the same transaction as each run. Every one is `STRICT`, has a
439
+ single `id INTEGER PRIMARY KEY`, and only `INTEGER`, `REAL` and `TEXT`
440
+ columns. A part refreshes them only when measured over the `full` checkout,
441
+ so a diff run or a metrics run never blanks what a full `verify` measured;
442
+ the `*_run_id` columns say which run each group of columns came from.
443
+
444
+ | table | one row per | columns |
445
+ |---|---|---|
446
+ | `projects_latest` | repo | `key`, `host`, `owner`, `name`; `wiring` (`off`/`partial`/`on`); `wiring_installed`, `wiring_sgconfig_canon`, `wiring_lint_script`, `wiring_ci`, `wiring_hook_postedit`, `wiring_hook_stop`, `wiring_preset`; `errors`, `warnings`, `overrides`, `overrides_without_reason`; `sloc`, `files`, `avg_file_sloc` (REAL), `files_over_sloc_limit`, `run_in_action`, `worktrees`, `local_branches`, `build_ms`; `last_run_at`, `last_sha`, `last_branch`, `last_command`; `wiring_run_id`, `findings_run_id`, `overrides_run_id` |
447
+ | `findings_latest` | code finding of the latest full `verify` | `repo`, `rule`, `tier`, `file`, `line`, `message` |
448
+ | `overrides_latest` | override of the latest full measurement | `repo`, `kind`, `rule`, `where`, `reason`, `has_reason`, `file`, `line` |
449
+ | `metric_history` | run × metric | `run_id`, `repo`, `at`, `metric`, `value` (REAL) |
450
+
451
+ `metric_history` holds, for each full-scope `metrics` or `snapshot` run:
452
+
453
+ - every `metrics --json` number under its key (`p90ComponentLoc`,
454
+ `runInActionCount`, `fileCount`, `hooksTotal.useState`, …);
455
+ - `sloc` (the production TS/TSX SLOC that `metrics` measures per file),
456
+ `avg_file_sloc`, `files_over_sloc_limit` (files over `max_file_sloc`);
457
+ - `loc` (non-blank lines of the project's code files: tracked plus
458
+ untracked-but-not-ignored, files over 2 MB skipped), `loc_files`, and
459
+ `loc.<language>` (`loc.typescript`, `loc.tsx`, `loc.css`, `loc.rust`, …;
460
+ `LANGUAGES` in `@agentvibes/guardrails/record` is the extension map);
461
+ - `git_worktrees` (open worktrees, the main one included) and
462
+ `git_local_branches`;
463
+ - `errors`, `warnings`, `overrides` and `overrides_without_reason` from a
464
+ full `verify` or `snapshot`.
465
+
466
+ `guardrails time -- pnpm build` adds `build_ms` (or the `--name` metric,
467
+ matching `[a-z][a-z0-9_.]*`). Everything after the first `--` is the
468
+ command's, so its flags never reach guardrails. A run that does not exit 0
469
+ is still recorded, with its exit code, but stores no time: a build that
470
+ failed halfway is not a build time. A time run changes only its own metric
471
+ in `projects_latest`; the other columns keep their values.
472
+
473
+ `projects_latest` reads `files` from `fileCount`, `run_in_action` from
474
+ `runInActionCount`, `worktrees` and `local_branches` from the `git_*`
475
+ metrics, and the other metric columns by their own names.
476
+
477
+ "Wired but overridden" is `wiring = 'partial' AND overrides > 0`:
478
+
479
+ ```sh
480
+ sqlite3 ~/.local/state/agentvibes/guardrails.sqlite \
481
+ "SELECT key, overrides, overrides_without_reason FROM projects_latest WHERE wiring = 'partial' AND overrides > 0"
482
+ ```
483
+
237
484
  ## Rules and fixtures
238
485
 
239
486
  - `rules/` — the canon. Stable ids, each message is a mini-manual (why + fix).
@@ -245,7 +492,7 @@ add a `guardrails doctor` (or `verify`) step to its own CI to gate drift there.
245
492
  - `structure/` — the `component-decl` marker rule the CLI turns into
246
493
  `react-multi-component` / `react-component-too-long` /
247
494
  `react-component-needs-folder` findings.
248
- - `candidates/` — triaged in wave 2. Three PPA R-rules were promoted into
495
+ - `candidates/` — triaged in wave 2. Three source-app R-rules were promoted into
249
496
  `rules/`; the eight that remain are repo-local by decision, with the reason
250
497
  for each recorded in `candidates/README.md`. Still loaded nowhere.
251
498
 
@@ -1,9 +1,9 @@
1
1
  # candidates/ — triaged, wave 2
2
2
 
3
- The 11 PPA R-rules that came verbatim from `merkle-substrate/apps/ppa/.ast-grep/rules/`
3
+ The 11 R-rules that came verbatim from one consumer app's (the source app's) `.ast-grep/rules/`
4
4
  have been triaged. **Three were promoted into `rules/` and deleted from here.**
5
- The eight below stay **repo-local**: they encode a PPA convention rather than a
6
- house rule, so they keep living in the PPA repo and load through the repo-local
5
+ The eight below stay **repo-local**: they encode a source-app convention rather than a
6
+ house rule, so they keep living in the source app repo and load through the repo-local
7
7
  `ruleDirs` entry (see the package README, "Repo-local extra rules").
8
8
 
9
9
  They are still NOT in the package `sgconfig.yml` and load nowhere from here.
@@ -12,19 +12,19 @@ They are still NOT in the package `sgconfig.yml` and load nowhere from here.
12
12
 
13
13
  | R-rule | canon id | why |
14
14
  |---|---|---|
15
- | r4-ternary-on-discriminator | `discriminator-ternary` | 18 hits outside PPA, and measured **disjoint** from both rules it looked like a duplicate of: `∩ jsx-ternary = 0`, `∩ kind-if-without-match = 0`. The three partition the space — `if` on a discriminator, ternary yielding JSX, ternary yielding values. A `not: is-jsx` clause makes that disjointness structural rather than lucky. |
16
- | r14-literal-union-in-component | `literal-union-in-component` | Already a house rule — report §8 bans string-literal unions from component files in the `ui/` tier. Globs generalised from `apps/ppa/**` to `**/components/**`, `**/screens/**`, `**/app/**`. |
17
- | r1a-hardcoded-url-in-component | `hardcoded-url-in-component` | Enforces CLAUDE.md "No localhost": every service URL comes from `dev url`, never a literal. Same reusability boundary `ui-imports-app-store` guards from the other side. |
15
+ | r4-ternary-on-discriminator | `discriminator-ternary` | 18 hits outside the source app, and measured **disjoint** from both rules it looked like a duplicate of: `∩ jsx-ternary = 0`, `∩ kind-if-without-match = 0`. The three partition the space — `if` on a discriminator, ternary yielding JSX, ternary yielding values. A `not: is-jsx` clause makes that disjointness structural rather than lucky. |
16
+ | r14-literal-union-in-component | `literal-union-in-component` | Already a house rule — the house store layout bans string-literal unions from component files in the `ui/` tier. Globs generalised from `apps/<app>/**` to `**/components/**`, `**/screens/**`, `**/app/**`. |
17
+ | r1a-hardcoded-url-in-component | `hardcoded-url-in-component` | Enforces the "No localhost" convention: every service URL comes from `dev url`, never a literal. Same reusability boundary `ui-imports-app-store` guards from the other side. |
18
18
 
19
19
  ## Staying repo-local
20
20
 
21
21
  | R-rule | why it is not canon |
22
22
  |---|---|
23
- | r10-as-cast | 121 hits in tg-gallery + observatory alone. `as Type` is legitimate at boundaries this codebase does not yet route through Zod, and `as-any-escape` already covers the escape-hatch half. Canon-promoting it buys a suppression campaign. |
24
- | r1d-scattered-numeric-const-in-component | 25 hits, but "module-level ALL_CAPS numeric belongs in tokens.ts" is a PPA layout convention, not a house rule. |
23
+ | r10-as-cast | 121 hits in two consumer apps alone. `as Type` is legitimate at boundaries this codebase does not yet route through Zod, and `as-any-escape` already covers the escape-hatch half. Canon-promoting it buys a suppression campaign. |
24
+ | r1d-scattered-numeric-const-in-component | 25 hits, but "module-level ALL_CAPS numeric belongs in tokens.ts" is a source-app layout convention, not a house rule. |
25
25
  | r2-helper-fn-in-tsx | Its own message admits "unavoidable false positives — it can't distinguish PascalCase observer-wrapped components from helpers". A rule its author documents as broken does not become canon. (The stated cause, "metavariable regex unsupported in ast-grep 0.42", no longer holds on 0.45 — so a corrected version is a real candidate for a later wave, but it would be a new rule, not this one.) |
26
- | r3-hooks-outside-layout | Bans useState/useEffect/useMemo outside two named layout files. That is PPA's architectural stance; the house rule (C24) permits a hook that owns DOM or lifecycle, and `usePageStore` is sanctioned. |
27
- | r6-jsx-comment-smell | "A JSX comment is a smell" at severity `hint`. House code uses JSX comments for real explanation (tg-gallery, observatory); this is a PPA style preference. |
28
- | r7-raw-hsl-outside-tokens | Points at `apps/ppa/lib/tokens.ts`. Tailwind remains a legal manifest value for web apps, so a raw-colour ban cannot be unconditional canon. |
29
- | r8-inline-style-prop | **Stale as well as local.** It tells you to prefer NativeWind `className` over `style={{}}` — but decision #10 (2026-08-28) converges PPA to *theme-inline*, which makes inline style from a theme hook the intended idiom. The rule now argues against the decision it lives under; PPA should retire or invert it. |
30
- | r9-optional-store-arg | Flags every `?:` parameter and property in store source. The principle is house-wide (make invalid states unrepresentable), but the rule as written has no way to tell a genuine optional from a modelled one, which is why PPA scoped it to two directories with three ignores. |
26
+ | r3-hooks-outside-layout | Bans useState/useEffect/useMemo outside two named layout files. That is the source app's architectural stance; the house convention permits a hook that owns DOM or lifecycle, and `usePageStore` is sanctioned. |
27
+ | r6-jsx-comment-smell | "A JSX comment is a smell" at severity `hint`. House code uses JSX comments for real explanation (two consumer apps); this is a source-app style preference. |
28
+ | r7-raw-hsl-outside-tokens | Points at `apps/<app>/lib/tokens.ts`. Tailwind remains a legal manifest value for web apps, so a raw-colour ban cannot be unconditional canon. |
29
+ | r8-inline-style-prop | **Stale as well as local.** It tells you to prefer NativeWind `className` over `style={{}}` — but a later decision converges the source app to *theme-inline*, which makes inline style from a theme hook the intended idiom. The rule now argues against the decision it lives under; the source app should retire or invert it. |
30
+ | r9-optional-store-arg | Flags every `?:` parameter and property in store source. The principle is house-wide (make invalid states unrepresentable), but the rule as written has no way to tell a genuine optional from a modelled one, which is why the source app scoped it to two directories with three ignores. |
@@ -5,11 +5,11 @@ message: |
5
5
  R10 — `as Type` cast. Use Zod .safeParse() at boundaries, type guards,
6
6
  or fix the source type. Allowed: `as const`, `as never` (test stubs),
7
7
  `as any` (still flagged separately by defensive-errors as-any-escape).
8
- See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R10.
8
+ Origin: rule R10 of the 2026-05-03 code-quality audit.
9
9
  files:
10
- - "apps/ppa-libs/store/src/**/*.ts"
11
- - "apps/ppa/**/*.ts"
12
- - "apps/ppa/**/*.tsx"
10
+ - "apps/app-libs/store/src/**/*.ts"
11
+ - "apps/<app>/**/*.ts"
12
+ - "apps/<app>/**/*.tsx"
13
13
  ignores:
14
14
  - "**/__tests__/**"
15
15
  - "**/*.test.ts"
@@ -3,11 +3,11 @@ language: tsx
3
3
  severity: warning
4
4
  message: |
5
5
  R1d — Module-level numeric ALL_CAPS constant in a component file.
6
- Move to apps/ppa/lib/tokens.ts (layout dimensions) or a per-module
6
+ Move to apps/<app>/lib/tokens.ts (layout dimensions) or a per-module
7
7
  constants.ts (timeouts, thresholds, limits).
8
- See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R1.
8
+ Origin: rule R1 of the 2026-05-03 code-quality audit.
9
9
  files:
10
- - "apps/ppa/components/**/*.tsx"
10
+ - "apps/<app>/components/**/*.tsx"
11
11
  rule:
12
12
  kind: variable_declarator
13
13
  regex: '^[A-Z][A-Z0-9_]+ = -?[0-9]'
@@ -4,15 +4,15 @@ severity: warning
4
4
  message: |
5
5
  R2 — Helper function declared in a component file. Move to either:
6
6
  - the appropriate MobX store as a `get` (computed) or method (action), or
7
- - apps/ppa/lib/<scope>/ as a stateless utility.
7
+ - apps/<app>/lib/<scope>/ as a stateless utility.
8
8
  Component files should be thin views; logic lives in stores.
9
9
  Note: this rule has unavoidable false positives — it can't distinguish
10
10
  PascalCase observer-wrapped components from helpers without metavariable
11
11
  regex (unsupported in ast-grep 0.42). Filter visually or use the
12
12
  scripts/lint/helpers-in-tsx.sh wrapper which adds a camelCase guard.
13
- See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R2.
13
+ Origin: rule R2 of the 2026-05-03 code-quality audit.
14
14
  files:
15
- - "apps/ppa/components/**/*.tsx"
15
+ - "apps/<app>/components/**/*.tsx"
16
16
  rule:
17
17
  any:
18
18
  # Arrow functions WITH explicit return type — strongest signal of "helper"
@@ -5,13 +5,13 @@ message: |
5
5
  R3 — React hook (useState/useCallback/useMemo/useEffect) outside a
6
6
  layout/page root. Promote local state to a ui-tier MobX store and
7
7
  bind via plain props. The only legitimate hook callsites are:
8
- - apps/ppa/app/_layout.tsx
9
- - apps/ppa/app/(app)/_layout.tsx
8
+ - apps/<app>/app/_layout.tsx
9
+ - apps/<app>/app/(app)/_layout.tsx
10
10
  - PageStoreManager.getOrCreate(...) wrapping at a route root
11
11
  - Animation primitives (mark with `// hooks-ok: animation` comment)
12
- See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R3.
12
+ Origin: rule R3 of the 2026-05-03 code-quality audit.
13
13
  files:
14
- - "apps/ppa/components/**/*.tsx"
14
+ - "apps/<app>/components/**/*.tsx"
15
15
  rule:
16
16
  any:
17
17
  - pattern: 'useState($$$)'
@@ -5,9 +5,9 @@ message: |
5
5
  R6 — JSX comment ({/* ... */}) is a smell. The element it labels
6
6
  deserves a name — extract a named observer subcomponent.
7
7
  Use the /refactor-jsx-comment slash command to extract.
8
- See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R6.
8
+ Origin: rule R6 of the 2026-05-03 code-quality audit.
9
9
  files:
10
- - "apps/ppa/components/**/*.tsx"
10
+ - "apps/<app>/components/**/*.tsx"
11
11
  rule:
12
12
  kind: jsx_expression
13
13
  has:
@@ -3,12 +3,12 @@ language: tsx
3
3
  severity: warning
4
4
  message: |
5
5
  R7 — Raw hsl(...) string in a component. Use useTokens() and the
6
- semantic tokens defined in apps/ppa/lib/tokens.ts. If the token
6
+ semantic tokens defined in apps/<app>/lib/tokens.ts. If the token
7
7
  you need doesn't exist, ADD it to tokens.ts/themed-tokens.ts first.
8
- See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R7
8
+ Origin: rule R7 of the 2026-05-03 code-quality audit.
9
9
  and AGENTS.md (HSL/tokens rule).
10
10
  files:
11
- - "apps/ppa/components/**/*.tsx"
11
+ - "apps/<app>/components/**/*.tsx"
12
12
  ignores:
13
13
  - "**/_fixture.ts"
14
14
  - "**/__tests__/**"
@@ -5,9 +5,9 @@ message: |
5
5
  R8 — Inline style={{}} prop. Prefer NativeWind className for static
6
6
  values (color, spacing, layout, radius). Reserve style={{}} for
7
7
  genuinely dynamic values: animated transforms, computed widths/positions.
8
- See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R8.
8
+ Origin: rule R8 of the 2026-05-03 code-quality audit.
9
9
  files:
10
- - "apps/ppa/components/**/*.tsx"
10
+ - "apps/<app>/components/**/*.tsx"
11
11
  rule:
12
12
  kind: jsx_attribute
13
13
  regex: '^style=\{\{'
@@ -8,9 +8,9 @@ message: |
8
8
  split into N narrow methods.
9
9
  Boundary cases (wrapping isomorphic-git, etc.) are exempt via the
10
10
  ignores list below.
11
- See <vault>/_agent/Notes/2026-05-03-code-quality-rules.md R9.
11
+ Origin: rule R9 of the 2026-05-03 code-quality audit.
12
12
  files:
13
- - "apps/ppa-libs/store/src/**/*.ts"
13
+ - "apps/app-libs/store/src/**/*.ts"
14
14
  - "packages/gitapp-store/src/**/*.ts"
15
15
  ignores:
16
16
  - "**/__tests__/**"
package/dist/astGrep.js CHANGED
@@ -9,7 +9,9 @@ export function scan(configPath, targets, extraArgs = []) {
9
9
  const [cmd, ...prefix] = tool.argv;
10
10
  if (cmd === undefined)
11
11
  throw new Error("empty ast-grep argv");
12
- const res = spawnSync(cmd, [...prefix, "scan", "-c", configPath, ...extraArgs, "--json", ...targets], {
12
+ const res = spawnSync(cmd,
13
+ // `--` ends option parsing, so a target can never be read as a flag.
14
+ [...prefix, "scan", "-c", configPath, ...extraArgs, "--json", "--", ...targets], {
13
15
  encoding: "utf8",
14
16
  maxBuffer: 256 * 1024 * 1024,
15
17
  });
@@ -33,7 +35,7 @@ export function scan(configPath, targets, extraArgs = []) {
33
35
  parsed = JSON.parse(out);
34
36
  }
35
37
  catch {
36
- throw new Error(`ast-grep produced unparsable JSON (exit ${res.status}). stderr:\n${res.stderr.slice(0, 2000)}`);
38
+ throw new Error(`ast-grep produced unparsable JSON (exit ${res.status}). stdout starts:\n${out.slice(0, 500)}\nstderr:\n${res.stderr.slice(0, 2000)}`);
37
39
  }
38
40
  return parsed.map((m) => ({
39
41
  ruleId: m.ruleId,
@@ -1 +1 @@
1
- {"version":3,"file":"astGrep.js","sourceRoot":"","sources":["../src/astGrep.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"astGrep.js","sourceRoot":"","sources":["../src/astGrep.ts"],"names":[],"mappings":"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"}