@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.
- package/README.md +252 -5
- package/candidates/README.md +13 -13
- package/candidates/r10-as-cast.yml +4 -4
- package/candidates/r1d-scattered-numeric-const-in-component.yml +3 -3
- package/candidates/r2-helper-fn-in-tsx.yml +3 -3
- package/candidates/r3-hooks-outside-layout.yml +4 -4
- package/candidates/r6-jsx-comment-smell.yml +2 -2
- package/candidates/r7-raw-hsl-outside-tokens.yml +3 -3
- package/candidates/r8-inline-style-prop.yml +2 -2
- package/candidates/r9-optional-store-arg.yml +2 -2
- package/dist/astGrep.js +4 -2
- package/dist/astGrep.js.map +1 -1
- package/dist/cli.js +89 -6
- package/dist/cli.js.map +1 -1
- package/dist/cliArgsTest.d.ts +1 -0
- package/dist/cliArgsTest.js +44 -0
- package/dist/cliArgsTest.js.map +1 -0
- package/dist/doctor.d.ts +1 -1
- package/dist/doctor.js +58 -6
- package/dist/doctor.js.map +1 -1
- package/dist/fileSloc.d.ts +28 -0
- package/dist/fileSloc.js +72 -0
- package/dist/fileSloc.js.map +1 -0
- package/dist/fileSlocBaseline.d.ts +78 -0
- package/dist/fileSlocBaseline.js +173 -0
- package/dist/fileSlocBaseline.js.map +1 -0
- package/dist/fileSlocGate.d.ts +17 -0
- package/dist/fileSlocGate.js +75 -0
- package/dist/fileSlocGate.js.map +1 -0
- package/dist/fileSlocTest.d.ts +1 -0
- package/dist/fileSlocTest.js +172 -0
- package/dist/fileSlocTest.js.map +1 -0
- package/dist/fileWalk.js +1 -1
- package/dist/fileWalk.js.map +1 -1
- package/dist/findings.d.ts +1 -1
- package/dist/gateRed.d.ts +1 -1
- package/dist/gateRed.js +1 -0
- package/dist/gateRed.js.map +1 -1
- package/dist/gitDiff.d.ts +6 -0
- package/dist/gitDiff.js +25 -0
- package/dist/gitDiff.js.map +1 -1
- package/dist/hookStop.d.ts +2 -1
- package/dist/hookStop.js +7 -1
- package/dist/hookStop.js.map +1 -1
- package/dist/hookStopTest.d.ts +1 -1
- package/dist/hookStopTest.js +1 -0
- package/dist/hookStopTest.js.map +1 -1
- package/dist/init.js +1 -1
- package/dist/init.js.map +1 -1
- package/dist/initTest.d.ts +1 -1
- package/dist/initTest.js +2 -1
- package/dist/initTest.js.map +1 -1
- package/dist/iterateTest.d.ts +1 -1
- package/dist/iterateTest.js +1 -0
- package/dist/iterateTest.js.map +1 -1
- package/dist/jsxSuppress.js +1 -1
- package/dist/jsxSuppress.js.map +1 -1
- package/dist/jsxSuppressTest.d.ts +1 -1
- package/dist/jsxSuppressTest.js +4 -2
- package/dist/jsxSuppressTest.js.map +1 -1
- package/dist/leaksRed.d.ts +1 -1
- package/dist/leaksRed.js +1 -0
- package/dist/leaksRed.js.map +1 -1
- package/dist/metrics.d.ts +9 -0
- package/dist/metrics.js +96 -7
- package/dist/metrics.js.map +1 -1
- package/dist/metricsBaseline.js +1 -1
- package/dist/metricsBaseline.js.map +1 -1
- package/dist/metricsCollect.js +2 -45
- package/dist/metricsCollect.js.map +1 -1
- package/dist/metricsCycle.d.ts +1 -1
- package/dist/metricsCycle.js +1 -0
- package/dist/metricsCycle.js.map +1 -1
- package/dist/metricsTypes.d.ts +1 -1
- package/dist/overrideDeclarations.d.ts +35 -0
- package/dist/overrideDeclarations.js +94 -0
- package/dist/overrideDeclarations.js.map +1 -0
- package/dist/overrides.d.ts +35 -0
- package/dist/overrides.js +284 -0
- package/dist/overrides.js.map +1 -0
- package/dist/overridesTest.d.ts +1 -0
- package/dist/overridesTest.js +183 -0
- package/dist/overridesTest.js.map +1 -0
- package/dist/pipeOutputTest.d.ts +1 -1
- package/dist/pipeOutputTest.js +2 -1
- package/dist/pipeOutputTest.js.map +1 -1
- package/dist/presetDrift.d.ts +8 -0
- package/dist/presetDrift.js +91 -34
- package/dist/presetDrift.js.map +1 -1
- package/dist/presetDriftTest.d.ts +1 -1
- package/dist/presetDriftTest.js +3 -3
- package/dist/presetDriftTest.js.map +1 -1
- package/dist/record/config.d.ts +17 -0
- package/dist/record/config.js +83 -0
- package/dist/record/config.js.map +1 -0
- package/dist/record/index.d.ts +69 -0
- package/dist/record/index.js +8 -0
- package/dist/record/index.js.map +1 -0
- package/dist/record/record.d.ts +56 -0
- package/dist/record/record.js +111 -0
- package/dist/record/record.js.map +1 -0
- package/dist/record/repoKey.d.ts +8 -0
- package/dist/record/repoKey.js +70 -0
- package/dist/record/repoKey.js.map +1 -0
- package/dist/record/repoMetrics.d.ts +14 -0
- package/dist/record/repoMetrics.js +124 -0
- package/dist/record/repoMetrics.js.map +1 -0
- package/dist/record/runRecord.d.ts +60 -0
- package/dist/record/runRecord.js +2 -0
- package/dist/record/runRecord.js.map +1 -0
- package/dist/record/schema.d.ts +31 -0
- package/dist/record/schema.js +201 -0
- package/dist/record/schema.js.map +1 -0
- package/dist/record/writer.d.ts +22 -0
- package/dist/record/writer.js +341 -0
- package/dist/record/writer.js.map +1 -0
- package/dist/recordTest.d.ts +1 -0
- package/dist/recordTest.js +422 -0
- package/dist/recordTest.js.map +1 -0
- package/dist/renameDiffTest.d.ts +1 -1
- package/dist/renameDiffTest.js +2 -1
- package/dist/renameDiffTest.js.map +1 -1
- package/dist/repoRules.js +1 -1
- package/dist/repoRules.js.map +1 -1
- package/dist/repoRulesTest.d.ts +1 -1
- package/dist/repoRulesTest.js +2 -1
- package/dist/repoRulesTest.js.map +1 -1
- package/dist/screenScope.js +4 -5
- package/dist/screenScope.js.map +1 -1
- package/dist/screenScopeTest.d.ts +1 -1
- package/dist/screenScopeTest.js +2 -1
- package/dist/screenScopeTest.js.map +1 -1
- package/dist/severityTest.d.ts +1 -1
- package/dist/severityTest.js +1 -0
- package/dist/severityTest.js.map +1 -1
- package/dist/siblingCloneTest.js +12 -12
- package/dist/siblingCloneTest.js.map +1 -1
- package/dist/snapshot.d.ts +2 -0
- package/dist/snapshot.js +118 -0
- package/dist/snapshot.js.map +1 -0
- package/dist/snapshotTest.d.ts +1 -0
- package/dist/snapshotTest.js +194 -0
- package/dist/snapshotTest.js.map +1 -0
- package/dist/structure.js +2 -2
- package/dist/structure.js.map +1 -1
- package/dist/testIsolation.d.ts +1 -0
- package/dist/testIsolation.js +7 -0
- package/dist/testIsolation.js.map +1 -0
- package/dist/testPaths.d.ts +4 -0
- package/dist/testPaths.js +9 -0
- package/dist/testPaths.js.map +1 -0
- package/dist/testRules.js +33 -3
- package/dist/testRules.js.map +1 -1
- package/dist/time.d.ts +22 -0
- package/dist/time.js +77 -0
- package/dist/time.js.map +1 -0
- package/dist/timeTest.d.ts +1 -0
- package/dist/timeTest.js +103 -0
- package/dist/timeTest.js.map +1 -0
- package/dist/tomlTable.d.ts +1 -1
- package/dist/tomlTable.js +6 -3
- package/dist/tomlTable.js.map +1 -1
- package/dist/toolResolve.d.ts +6 -0
- package/dist/toolResolve.js +18 -0
- package/dist/toolResolve.js.map +1 -1
- package/dist/twinCoverageTest.js +2 -20
- package/dist/twinCoverageTest.js.map +1 -1
- package/dist/verify.d.ts +2 -1
- package/dist/verify.js +33 -5
- package/dist/verify.js.map +1 -1
- package/dist/verifyDiff.d.ts +3 -2
- package/dist/verifyDiff.js +58 -8
- package/dist/verifyDiff.js.map +1 -1
- package/dist/wiring.d.ts +31 -0
- package/dist/wiring.js +262 -0
- package/dist/wiring.js.map +1 -0
- package/dist/wiringTest.d.ts +1 -0
- package/dist/wiringTest.js +127 -0
- package/dist/wiringTest.js.map +1 -0
- package/package.json +18 -6
- package/rules/__fixtures__/demo-mode-by-default/bad.ts +1 -1
- package/rules/__fixtures__/demo-mode-by-default/bad.tsx +1 -1
- package/rules/__fixtures__/direct-store-import/bad.tsx +1 -1
- package/rules/__fixtures__/direct-store-import/good.tsx +2 -2
- package/rules/__fixtures__/discriminator-ternary/bad.ts +9 -0
- package/rules/__fixtures__/discriminator-ternary/bad.tsx +1 -1
- package/rules/__fixtures__/discriminator-ternary/good.ts +17 -0
- package/rules/__fixtures__/discriminator-ternary/good.tsx +1 -1
- package/rules/__fixtures__/hardcoded-url-in-component/components/bad.ts +9 -0
- package/rules/__fixtures__/hardcoded-url-in-component/components/good.ts +13 -0
- package/rules/__fixtures__/inline-map-row/bad.tsx +1 -1
- package/rules/__fixtures__/inline-map-row/good.tsx +1 -1
- package/rules/__fixtures__/match-bool-to-null/bad.ts +14 -0
- package/rules/__fixtures__/match-bool-to-null/bad.tsx +8 -0
- package/rules/__fixtures__/match-bool-to-null/good.ts +12 -0
- package/rules/__fixtures__/match-bool-to-null/good.tsx +12 -0
- package/rules/__fixtures__/missing-observer/bad.tsx +2 -2
- package/rules/__fixtures__/missing-observer/good.tsx +2 -2
- package/rules/__fixtures__/no-local-kit-clone/bad.ts +2 -2
- package/rules/__fixtures__/no-local-kit-clone/bad.tsx +2 -2
- package/rules/__fixtures__/state-loading-boolean-shape/good.ts +1 -1
- package/rules/__fixtures__/state-loading-boolean-shape/good.tsx +1 -1
- package/rules/__fixtures__/store-async-method/good.ts +1 -1
- package/rules/__fixtures__/store-async-method/good.tsx +1 -1
- package/rules/__fixtures__/store-context-provider/bad.ts +1 -1
- package/rules/__fixtures__/store-delegation-getter/bad.ts +1 -1
- package/rules/__fixtures__/store-delegation-getter/bad.tsx +1 -1
- package/rules/__fixtures__/store-delegation-getter/good.ts +3 -3
- package/rules/__fixtures__/store-delegation-getter/good.tsx +3 -3
- package/rules/__fixtures__/store-no-runinaction/bad.ts +1 -1
- package/rules/__fixtures__/store-no-runinaction/bad.tsx +1 -1
- package/rules/__fixtures__/store-no-runinaction/good.ts +1 -1
- package/rules/__fixtures__/store-no-runinaction/good.tsx +1 -1
- package/rules/__fixtures__/ts-pattern-dangling-match/bad.ts +1 -1
- package/rules/__fixtures__/ts-pattern-dangling-match/good.ts +2 -2
- package/rules/__fixtures__/ui-imports-app-store/src/ui/bad.ts +11 -0
- package/rules/__fixtures__/ui-imports-app-store/src/ui/good.ts +13 -0
- package/rules/__fixtures__/ui-imports-app-store/src/ui/good.tsx +1 -1
- package/rules/__fixtures__/view-imports-store/good.view.tsx +1 -1
- package/rules/as-any-escape-tsx.yml +2 -2
- package/rules/as-any-escape.yml +2 -2
- package/rules/catch-empty-tsx.yml +3 -3
- package/rules/catch-empty.yml +3 -3
- package/rules/demo-mode-by-default-ts.yml +6 -7
- package/rules/demo-mode-by-default.yml +6 -7
- package/rules/direct-store-import.yml +15 -16
- package/rules/discriminator-ternary-ts.yml +46 -0
- package/rules/discriminator-ternary.yml +3 -3
- package/rules/hardcoded-url-in-component-ts.yml +40 -0
- package/rules/hardcoded-url-in-component.yml +5 -8
- package/rules/inline-map-row.yml +7 -7
- package/rules/instanceof-map-set-tsx.yml +2 -2
- package/rules/instanceof-map-set.yml +2 -2
- package/rules/kind-if-without-match-tsx.yml +1 -1
- package/rules/literal-union-in-component-tsx.yml +2 -2
- package/rules/literal-union-in-component.yml +7 -7
- package/rules/match-bool-to-null-ts.yml +27 -0
- package/rules/missing-observer.yml +5 -5
- package/rules/no-local-kit-clone-tsx.yml +2 -2
- package/rules/no-local-kit-clone.yml +2 -2
- package/rules/non-exhaustive-match-tsx.yml +4 -7
- package/rules/non-exhaustive-match.yml +2 -2
- package/rules/page-store-bare-usememo-tsx.yml +1 -1
- package/rules/page-store-bare-usememo.yml +1 -1
- package/rules/screen-file-styling.yml +3 -3
- package/rules/silent-default-return-tsx.yml +1 -1
- package/rules/store-async-method-tsx.yml +1 -1
- package/rules/store-async-method.yml +1 -1
- package/rules/store-context-provider-tsx.yml +3 -3
- package/rules/store-context-provider.yml +5 -5
- package/rules/store-delegation-getter-tsx.yml +2 -2
- package/rules/store-delegation-getter.yml +2 -2
- package/rules/store-no-runinaction-tsx.yml +2 -2
- package/rules/store-no-runinaction.yml +2 -2
- package/rules/store-no-setinterval-poll-tsx.yml +1 -1
- package/rules/store-no-setinterval-poll.yml +1 -1
- package/rules/ts-pattern-dangling-match-tsx.yml +4 -4
- package/rules/ts-pattern-dangling-match.yml +4 -4
- package/rules/ui-imports-app-store-ts.yml +61 -0
- package/rules/ui-imports-app-store.yml +1 -1
- package/rules/view-file-logic.yml +5 -5
- package/rules/view-imports-store.yml +4 -5
- package/rules/zod-optional-nullable-tsx.yml +2 -2
- package/rules/zod-optional-nullable.yml +2 -2
- 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
|
|
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
|
-
|
|
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
|
|
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
|
|
package/candidates/README.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# candidates/ — triaged, wave 2
|
|
2
2
|
|
|
3
|
-
The 11
|
|
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
|
|
6
|
-
house rule, so they keep living in the
|
|
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
|
|
16
|
-
| r14-literal-union-in-component | `literal-union-in-component` | Already a house rule —
|
|
17
|
-
| r1a-hardcoded-url-in-component | `hardcoded-url-in-component` | Enforces
|
|
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
|
|
24
|
-
| r1d-scattered-numeric-const-in-component | 25 hits, but "module-level ALL_CAPS numeric belongs in tokens.ts" is a
|
|
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
|
|
27
|
-
| r6-jsx-comment-smell | "A JSX comment is a smell" at severity `hint`. House code uses JSX comments for real explanation (
|
|
28
|
-
| r7-raw-hsl-outside-tokens | Points at `apps
|
|
29
|
-
| r8-inline-style-prop | **Stale as well as local.** It tells you to prefer NativeWind `className` over `style={{}}` — but
|
|
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
|
|
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
|
-
|
|
8
|
+
Origin: rule R10 of the 2026-05-03 code-quality audit.
|
|
9
9
|
files:
|
|
10
|
-
- "apps/
|
|
11
|
-
- "apps
|
|
12
|
-
- "apps
|
|
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
|
|
6
|
+
Move to apps/<app>/lib/tokens.ts (layout dimensions) or a per-module
|
|
7
7
|
constants.ts (timeouts, thresholds, limits).
|
|
8
|
-
|
|
8
|
+
Origin: rule R1 of the 2026-05-03 code-quality audit.
|
|
9
9
|
files:
|
|
10
|
-
- "apps
|
|
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
|
|
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
|
-
|
|
13
|
+
Origin: rule R2 of the 2026-05-03 code-quality audit.
|
|
14
14
|
files:
|
|
15
|
-
- "apps
|
|
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
|
|
9
|
-
- apps
|
|
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
|
-
|
|
12
|
+
Origin: rule R3 of the 2026-05-03 code-quality audit.
|
|
13
13
|
files:
|
|
14
|
-
- "apps
|
|
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
|
-
|
|
8
|
+
Origin: rule R6 of the 2026-05-03 code-quality audit.
|
|
9
9
|
files:
|
|
10
|
-
- "apps
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
8
|
+
Origin: rule R8 of the 2026-05-03 code-quality audit.
|
|
9
9
|
files:
|
|
10
|
-
- "apps
|
|
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
|
-
|
|
11
|
+
Origin: rule R9 of the 2026-05-03 code-quality audit.
|
|
12
12
|
files:
|
|
13
|
-
- "apps/
|
|
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,
|
|
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}).
|
|
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,
|
package/dist/astGrep.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"astGrep.js","sourceRoot":"","sources":["../src/astGrep.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAW/C,wEAAwE;AACxE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;CAAG;AAchD,4EAA4E;AAC5E,MAAM,UAAU,IAAI,CAClB,UAAkB,EAClB,OAAiB,EACjB,YAAsB,EAAE;IAExB,MAAM,IAAI,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACrC,MAAM,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;IACnC,IAAI,GAAG,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAC9D,MAAM,GAAG,GAAG,SAAS,CACnB,GAAG,
|
|
1
|
+
{"version":3,"file":"astGrep.js","sourceRoot":"","sources":["../src/astGrep.ts"],"names":[],"mappings":"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"}
|