@agentvibes/guardrails 0.1.0

package/rules/inline-map-row.yml

@@ -0,0 +1,107 @@
+# ── G1, rule 2 of 3: per-row observer extraction ───────────────────────
+#
+# The MobX list rule from CLAUDE.md: mapping an observable collection with the
+# row body written inline makes the PARENT track every field every row reads, so
+# one item's change invalidates the whole list. Extracting the row into its own
+# `observer` component localises the invalidation.
+#
+# The report's audit found this rule already obeyed everywhere it looked (131
+# `*Row.tsx` files in merkle alone) — so it lands as a ratchet on new code, not
+# as a cleanup campaign.
+#
+# Threshold: the mapped element must contain TWO OR MORE nested JSX elements
+# before this fires. That is what separates a row body from a wrapper, and it is
+# why these stay silent by design:
+#
+#   {xs.map(x => <li key={x.id}><Row item={x}/></li>)}        one nested element
+#   {xs.map(x => <li key={x.id}><a href={x.h}>{x.t}</a></li>)}  one nested element
+#
+# Both arguably want extracting too, but this rule is `error`, and an error that
+# fires on a one-element wrapper is an error people suppress. Under-match.
+#
+# Also out of scope by design: a `.map` outside JSX (`const rows = xs.map(…)`
+# assigned first, rendered as `{rows}`). Same defect, no JSX context to key on.
+id: inline-map-row
+language: tsx
+severity: error
+ignores:
+  - '**/*.test.tsx'
+  - '**/*.spec.tsx'
+  - '**/__tests__/**'
+  # A gallery/preview harness IS the markup it shows; extracting rows out of it
+  # would defeat the point of reading it as one page.
+  - '**/showcase/**'
+  - '**/*.stories.tsx'
+utils:
+  jsx-el:
+    any:
+      - kind: jsx_element
+      - kind: jsx_self_closing_element
+message: |
+  An inline row body inside `.map(...)`. The parent is an `observer`, so every
+  field this body reads is tracked by the PARENT — one item changing a single
+  field re-renders the entire list.
+  Extract the body into its own `observer` component and pass the item down:
+    {items.map(t => <TaskRow key={t.id} task={t} />)}
+  The parent then re-renders only on insert, remove and reorder; each row
+  re-renders on its own fields. See CLAUDE.md "MobX lists" and the
+  mobx-components skill.
+  Doesn't apply when the mapped children are pure data — constants or plain
+  props rather than observables.
+rule:
+  all:
+    - kind: jsx_element
+    # Anchor the finding on the row ROOT — the element the callback returns —
+    # so a deep body reports once at the line you would edit, instead of once
+    # per offending element on the way down. Nested JSX elements are direct
+    # children of their parent element, so an unqualified `inside` is exactly
+    # the "am I the outermost one" test.
+    - not:
+        inside:
+          kind: jsx_element
+    # Two or more nested JSX elements: one that has a JSX sibling before it.
+    # `stopBy: end` on `follows` is required — tree-sitter puts `jsx_text`
+    # nodes between JSX siblings, so the default immediate-sibling check never
+    # sees the element next door.
+    - has:
+        stopBy: end
+        all:
+          - matches: jsx-el
+          - follows:
+              stopBy: end
+              matches: jsx-el
+    # The enclosing component must BE an observer. This is not a narrowing of
+    # convenience — it is the rule's own rationale made into its scope: the
+    # defect is that the PARENT'S reactive scope tracks every field every row
+    # reads, and a component with no reactive scope has no such defect. It is
+    # also the only syntactically decidable form of CLAUDE.md's carve-out
+    # ("when the rendered children are pure data … the rule doesn't apply").
+    #
+    # Measured, not assumed: without this clause the rule fired 50 times in
+    # byoklab/components — a UI library and its examples/docs site, which
+    # contain no MobX whatsoever — where every hit was a false positive at
+    # `error` severity. With it, 0 there.
+    #
+    # A component that reads observables WITHOUT the wrap is a different defect
+    # and belongs to `missing-observer`, not here.
+    - inside:
+        stopBy: end
+        pattern: observer($$$)
+    - inside:
+        stopBy: end
+        all:
+          - pattern: $ARR.map($$$CB)
+          - inside:
+              stopBy: end
+              kind: jsx_expression
+          # CLAUDE.md's own carve-out: "When the rendered children are pure data
+          # (constants, plain props, not MobX observables), the rule doesn't
+          # apply." A literal array is the one case that is provably constant —
+          # observatory's SessionInfoSkeleton maps `[1, 2, 3, 4]` to draw four
+          # placeholder cards, which no amount of extraction improves.
+          - not:
+              has:
+                field: function
+                has:
+                  field: object
+                  kind: array

package/rules/instanceof-map-set-tsx.yml

@@ -0,0 +1,46 @@
+# ── rule body adopted from faceless-photo-lib `no-instanceof-map-set` (wave 2 triage) ──
+# The two rules were duplicates; the faceless implementation is strictly better,
+# so the canon id keeps its message and takes that body. Why it is better here:
+# the old patterns named only Map and Set; WeakMap and WeakSet have exactly the
+# same cross-realm failure and were invisible.
+#
+# The .tsx half of `instanceof-map-set`.
+#
+# ast-grep's `typescript` and `tsx` languages are DISJOINT, not nested: a rule
+# at `language: typescript` matches `.ts` and NEVER `.tsx`, so `instanceof-map-set`
+# was blind to every React component file. Verified by effect — byte-identical
+# content in `p.ts` and `p.tsx`, the first flagged and the second silent.
+#
+# Three ways to cover both were tried and two were rejected on measurement:
+#   - `language: [typescript, tsx]` — ast-grep refuses to parse the rule.
+#   - `languageGlobs: {tsx: ["*.ts"]}` — reassigns `.ts` to the tsx language, so
+#     EVERY remaining `language: typescript` rule goes dark. Measured corpus-wide:
+#     5 rules blinded, 6,094 findings lost against 334 gained. It would have
+#     looked like a coverage win.
+#   - two files with the SAME id — "Error: Duplicate rule id".
+# So: a separate id per language. The trailing `-tsx` is what you suppress with
+# in a .tsx file, and the finding prints the id, so copying from the output is
+# always right.
+#
+# Keep this file's `rule:` block IDENTICAL to `instanceof-map-set.yml`. They are one
+# rule wearing two ids because the tool has no way to say "both languages".
+id: instanceof-map-set-tsx
+language: tsx
+severity: error
+message: |
+  Do NOT use `instanceof Map / Set`. Data crossing serialization/immer/MobX boundaries
+  loses its runtime type. Duck-type capabilities instead, or use a typed accessor.
+  See defensive-errors Rule 3 and Rule 4b.
+  Suppressing this one needs the id you see above — `ast-grep-ignore: instanceof-map-set-tsx`.
+  `instanceof-map-set` is a DIFFERENT rule (the .ts arm) and does not cover it; ast-grep
+  matches suppression ids exactly. A bare `// ast-grep-ignore` suppresses every
+  rule on the line, and a wrong id is reported back as `unused-suppression`.
+rule:
+  kind: binary_expression
+  all:
+    - has:
+        field: operator
+        regex: "^instanceof$"
+    - has:
+        field: right
+        regex: "^(Map|Set|WeakMap|WeakSet)$"

package/rules/instanceof-map-set.yml

@@ -0,0 +1,22 @@
+# ── rule body adopted from faceless-photo-lib `no-instanceof-map-set` (wave 2 triage) ──
+# The two rules were duplicates; the faceless implementation is strictly better,
+# so the canon id keeps its message and takes that body. Why it is better here:
+# the old patterns named only Map and Set; WeakMap and WeakSet have exactly the
+# same cross-realm failure and were invisible.
+#
+id: instanceof-map-set
+language: typescript
+severity: error
+message: |
+  Do NOT use `instanceof Map / Set`. Data crossing serialization/immer/MobX boundaries
+  loses its runtime type. Duck-type capabilities instead, or use a typed accessor.
+  See defensive-errors Rule 3 and Rule 4b.
+rule:
+  kind: binary_expression
+  all:
+    - has:
+        field: operator
+        regex: "^instanceof$"
+    - has:
+        field: right
+        regex: "^(Map|Set|WeakMap|WeakSet)$"

package/rules/json-roundtrip.yml

@@ -0,0 +1,9 @@
+id: json-roundtrip
+language: typescript
+severity: warning
+message: |
+  JSON.parse(JSON.stringify(x)) loses Maps, Sets, TypedArrays, class instances, circular refs.
+  Use a typed serializer with Zod validation at the boundary.
+  See defensive-errors Rule 5.
+rule:
+  pattern: "JSON.parse(JSON.stringify($X))"

package/rules/jsx-cond-and.yml

@@ -0,0 +1,16 @@
+id: jsx-cond-and
+language: tsx
+severity: warning
+message: |
+  `{cond && <JSX/>}` in JSX silently drops the !cond branch (renders falsy).
+  Use the `<ShowWhen cond={cond}>{() => <JSX/>}</ShowWhen>` helper — it's an
+  observer (MobX-reactive) and communicates intent "show this subtree when cond".
+  For branches where both arms render something non-null, use match().exhaustive().
+  See defensive-errors Rule 1 & 2.
+rule:
+  any:
+    # Self-closing: {cond && <Foo />}
+    - pattern: $COND && <$TAG />
+    # With children: {cond && <Foo>…</Foo>}
+    - pattern: $COND && <$TAG>$$$CHILDREN</$TAG>
+    - pattern: $COND && <$TAG $$$PROPS>$$$CHILDREN</$TAG>

package/rules/jsx-ternary.yml

@@ -0,0 +1,35 @@
+id: jsx-ternary
+language: tsx
+severity: warning
+utils:
+  # A JSX subtree, however many redundant parens wrap it.
+  is-jsx:
+    any:
+      - kind: jsx_element
+      - kind: jsx_self_closing_element
+      - all:
+          - kind: parenthesized_expression
+          - has:
+              matches: is-jsx
+message: |
+  `cond ? <A/> : <B/>` branches on state with a ternary — the other half of the
+  ban `jsx-cond-and` enforces (react.md: "NEVER branch on state with
+  `if`/`switch`/ternary or `{cond && <JSX/>}`").
+  Both arms render, so nothing leaks into the DOM — what it costs is the build
+  break: widen what is being branched on and the second arm silently absorbs
+  the new case.
+    cond ? <A/> : <B/>   → match(value).with(…, () => <A/>).otherwise(() => <B/>)
+                           or a two-arm .exhaustive() when the union is closed
+    xs.length === 0 ? … → match(xs).with([], () => <Empty/>).otherwise(…)
+    cond ? <A/> : null   → <ShowWhen cond={cond}>{() => <A/>}</ShowWhen>
+  Match the value, not a boolean derived from it — that is what makes adding a
+  variant a type error. See defensive-errors Rule 1 & 2.
+rule:
+  kind: ternary_expression
+  any:
+    - has:
+        field: consequence
+        matches: is-jsx
+    - has:
+        field: alternative
+        matches: is-jsx

package/rules/kind-if-without-match.yml

@@ -0,0 +1,13 @@
+id: kind-if-without-match
+language: typescript
+severity: warning
+message: |
+  Discriminated-union branching with if/else silently ignores new variants.
+  Use match($X).with({kind: ...}, ...).exhaustive() from ts-pattern.
+  See defensive-errors Rule 2 and the pattern-matching skill.
+rule:
+  any:
+    - pattern: "if ($X.kind === $_) $_"
+    - pattern: "if ($X.type === $_) $_"
+    - pattern: "if ($X.status === $_) $_"
+    - pattern: "if ($X._obj === $_) $_"

package/rules/literal-union-in-component.yml

@@ -0,0 +1,71 @@
+# PROMOTED to canon in wave 2 from PPA `r14-literal-union-in-component` (rule-triage).
+#
+# Generic, not PPA-specific: the house store layout already states it — report §8
+# puts «string-literal union'ы вроде `type Tab = "tasks" | "habits"`, которым
+# запрещено жить в файлах компонентов» in the `ui/` tier of the four-level model.
+# The PPA original hard-coded `apps/ppa/components/**` and `apps/ppa/app/**`;
+# the globs below are the same intent stated for any repo.
+#
+# 23 hits across tg-gallery + observatory with the PPA globs stripped, so it is
+# a live rule elsewhere and not a local house style.
+id: literal-union-in-component
+language: typescript
+severity: warning
+files:
+  - '**/components/**/*.ts'
+  - '**/components/**/*.tsx'
+  - '**/screens/**/*.ts'
+  - '**/screens/**/*.tsx'
+  - '**/app/**/*.ts'
+  - '**/app/**/*.tsx'
+ignores:
+  - '**/__tests__/**'
+  - '**/*.test.ts'
+  - '**/*.test.tsx'
+  - '**/_fixture.ts'
+  - '**/_fixtures.ts'
+message: |
+  A string-literal union declared inside a component file. Every component that
+  touches the same concept redeclares it, and the copies drift — one file grows
+  a `"archived"` member the others never hear about, and nothing fails to build
+  because each copy is internally consistent.
+  Move it to where the state it describes lives:
+    - a UI-tier store, next to the actions that mutate it, when it IS state
+      (`type Tab = "tasks" | "habits"` belongs to the store that owns the tab), or
+    - a shared module as a typed constant + alias when it is purely lexical
+      (file kinds, palette names) with no state attached.
+  Component prop types then consume the shared type instead of restating it.
+  See the mobx-models skill and report §8.
+rule:
+  all:
+    - kind: type_alias_declaration
+    # Two or more STRING members on the union's own spine. The spine matters:
+    # tree-sitter nests unions left-associatively, so a 3-member union is
+    # `union_type(union_type(lit, lit), lit)` and a 2-member one is
+    # `union_type(lit, lit)` — hence the two arms. Searching with `stopBy: end`
+    # instead would reach literals nested INSIDE object members and flag
+    # `{ status: "idle" } | { status: "ready" }`, the discriminated union this
+    # codebase wants everywhere.
+    - has:
+        field: value
+        kind: union_type
+        any:
+          # three or more members
+          - has:
+              kind: union_type
+              has:
+                kind: literal_type
+                has:
+                  kind: string
+          # exactly two members
+          - has:
+              all:
+                - kind: literal_type
+                - has:
+                    kind: string
+                - follows:
+                    stopBy: end
+                    all:
+                      - kind: literal_type
+                      - has:
+                          kind: string

package/rules/match-bool-to-null.yml

@@ -0,0 +1,15 @@
+id: match-bool-to-null
+language: tsx
+severity: warning
+message: |
+  `match(cond).with(true, ...).with(false, () => null).exhaustive()` is the
+  ceremonial form of "maybe render this subtree". Use the purpose-built helper:
+    <ShowWhen cond={cond}>{() => <JSX/>}</ShowWhen>
+  ShowWhen is an observer (MobX-reactive), lazily evaluates children, and
+  communicates intent. If BOTH arms render something non-null, keep match().
+rule:
+  pattern: |
+    match($COND)
+      .with(true, () => $$$A)
+      .with(false, () => null)
+      .exhaustive()

package/rules/missing-observer.yml

@@ -0,0 +1,189 @@
+# ── G1, rule 1 of 3: the observer wrap ─────────────────────────────────
+#
+# `missing-observer` has been listed under "Validation" in mobx-components/SKILL.md
+# for months while existing in no rules/ directory at all. The sketch that was
+# published alongside it (ast-grep/SKILL.md) could not have matched the canonical
+# code even if it had been installed: it required the literal body
+#
+#   export const $NAME = () => { $$$  useStore()  $$$ }
+#
+# — a bare `useStore()` statement. Every real call site destructures
+# (`const { data, ui } = useStore()`), so the pattern matched nothing anywhere in
+# the park. This is the rule written against the shapes that are actually there.
+#
+# Deliberately UNDER-matching, and at `warning` rather than `error`. "Reads
+# observable data" is not a syntactic property — a component can hold an
+# observable that arrived through any prop under any name. Guessing wider buys
+# false positives, and a rule that cries wolf is a rule people turn off. Two
+# arms only, both of which name the store at the call site:
+#
+#   1. it calls a `use…Store` hook, or
+#   2. it takes a prop literally named `model` or `store` AND dereferences it.
+#
+# What it therefore MISSES, on purpose: a component handed an observable under
+# any other prop name (`session={s}`, `photo={p}`). Those still need the wrap;
+# this rule is not the thing that will tell you.
+#
+# Known false-positive class, accepted at warning tier: a `use…Store` hook can
+# return non-observable services next to the stores — `const { platform } =
+# useStore()` in tg-gallery's ShareButton pulls a platform adapter, and a
+# component reading only that does not strictly need the wrap. Wrapping it is
+# harmless; the rule does not distinguish.
+id: missing-observer
+language: tsx
+severity: warning
+ignores:
+  - '**/*.test.tsx'
+  - '**/*.spec.tsx'
+  - '**/__tests__/**'
+  - '**/showcase/**'
+  - '**/*.stories.tsx'
+utils:
+  # A fragment (`<>…</>`) parses as a `jsx_element` with empty tags in this
+  # grammar, so these two kinds cover every JSX return shape.
+  jsx-node:
+    any:
+      - kind: jsx_element
+      - kind: jsx_self_closing_element
+  # `useStore()`, `useGalleryStore()`, `usePageStore()`, `useRootStore()`.
+  store-hook-call:
+    kind: call_expression
+    has:
+      field: function
+      kind: identifier
+      regex: '^use(Store|[A-Z][A-Za-z0-9]*Store)$'
+  # Every name a store hook can introduce, in the three spellings the park uses.
+  # Binding these is what lets the rule tell `ui.groupBy` (a plain `UIManifest`
+  # prop) apart from `uiStore.x` (the store) — without it the rule fires on any
+  # dotted value in the markup, which is how observatory's deliberately-plain
+  # `RichEntityListView` got flagged for rendering `groupBy={ui.groupBy}`.
+  store-binding:
+    any:
+      # const { data, ui } = useStore()
+      - all:
+          - kind: shorthand_property_identifier_pattern
+          - inside:
+              kind: object_pattern
+              inside:
+                kind: variable_declarator
+                has:
+                  field: value
+                  matches: store-hook-call
+      # const { ui: uiStore } = useStore()  → the local alias
+      - all:
+          - kind: identifier
+          - inside:
+              kind: pair_pattern
+              field: value
+              inside:
+                kind: object_pattern
+                inside:
+                  kind: variable_declarator
+                  has:
+                    field: value
+                    matches: store-hook-call
+      # const store = useStore()
+      - all:
+          - kind: identifier
+          - inside:
+              kind: variable_declarator
+              field: name
+              has:
+                field: value
+                matches: store-hook-call
+  # Read DURING RENDER — which is what creates the subscription an observer
+  # wrap is needed to service — as opposed to touched only from a handler or an
+  # effect, neither of which subscribes anything.
+  #
+  # Stated as an exclusion of the two deferred positions rather than as "appears
+  # inside JSX", because real components mostly do NOT dereference the store in
+  # the markup: tg-gallery's GalleryView reads `const layoutType =
+  # themeStore.layout.type` and `match(galleryStore.detailState)`, observatory's
+  # SessionsTreeSection reads `data.sessions.filter(...)` — all render reads,
+  # none of them inside a JSX expression. An "inside JSX" test missed every one.
+  # The test is structural: a read sitting inside a NESTED function is deferred,
+  # a read at the component's own body level runs during render.
+  #
+  # It works because the component is itself a function. A body-level read has
+  # exactly one function ancestor — the component. Anything deferred has two or
+  # more: `useEffect(() => …)`, `onOpen={(e) => uiStore.open(e.id)}`, and
+  # `const onPress = () => ui.close(id)` all put a second function in between.
+  # So "is there a function ancestor that itself has a function ancestor" asks
+  # exactly the right question, and asks it without enumerating hook names or
+  # handler spellings — an enumerated list missed the local-handler form and the
+  # good fixture caught it.
+  render-position:
+    not:
+      inside:
+        stopBy: end
+        all:
+          - any:
+              - kind: arrow_function
+              - kind: function_expression
+              - kind: function_declaration
+          - inside:
+              stopBy: end
+              any:
+                - kind: arrow_function
+                - kind: function_expression
+                - kind: function_declaration
+message: |
+  A component that reads observable state without an `observer(...)` wrap. It
+  renders once with whatever the store held at mount and then goes quiet —
+  nothing subscribes it to the fields it read, so the screen silently shows
+  stale data until some ancestor happens to re-render it.
+  Wrap the component: `export const X = observer(({ model }: Props) => …)`.
+  Scope note: this fires only when the store is named at the call site — a
+  `use…Store` hook, or a `model`/`store` prop being dereferenced. A component
+  handed an observable under any other prop name still needs the wrap and this
+  rule will not catch it. See the mobx-components skill.
+rule:
+  all:
+    - any:
+        - kind: variable_declarator
+        - kind: function_declaration
+    # PascalCase — a component, not a custom hook. A hook may read the store
+    # freely; the wrap belongs on whoever renders with it.
+    - has:
+        field: name
+        regex: '^[A-Z][A-Za-z0-9]*$'
+    - has:
+        stopBy: end
+        matches: jsx-node
+    # The component must RENDER a field off something the store gave it. Both
+    # halves matter: a component that pulls a store only to call an action from
+    # a handler needs no wrap (observatory writes two of those on purpose), and
+    # a dotted value in the markup means nothing unless the dotted thing came
+    # from a store. `$SLICE` ties the two clauses together.
+    - any:
+        # Arm 1: a binding introduced by a `use…Store` hook, then rendered.
+        - all:
+            - has:
+                stopBy: end
+                all:
+                  - matches: store-binding
+                  - pattern: $SLICE
+            - has:
+                stopBy: end
+                all:
+                  - pattern: $SLICE.$FIELD
+                  - matches: render-position
+        # Arm 2: a prop literally named `model` or `store`, then rendered.
+        - all:
+            - has:
+                stopBy: end
+                kind: shorthand_property_identifier_pattern
+                regex: '^(model|store)$'
+            - has:
+                stopBy: end
+                all:
+                  - kind: member_expression
+                  - has:
+                      field: object
+                      kind: identifier
+                      regex: '^(model|store)$'
+                  - matches: render-position
+    - not:
+        has:
+          stopBy: end
+          pattern: observer($$$)

package/rules/mobx-effect-observable-dep.yml

@@ -0,0 +1,23 @@
+id: mobx-effect-observable-dep
+language: tsx
+severity: warning
+message: |
+  useEffect whose dependency array reads observable state (`someStore.field`).
+  React is being used to react to MobX — but MobX already does that, correctly,
+  without a render pass in between. A dependency array cannot track an
+  observable it did not read during render, so this drifts.
+  Derived value → `computed get`. Side effect on state change → a `reaction()`
+  in the store (I/O boundaries only). Load on route change → the page-level
+  fetch convention, where the dependency is the route param, not a store field.
+  Passing the store itself (`[slug, galleryStore]`) is fine — that is a stable
+  reference, not a state read.
+rule:
+  all:
+    - pattern: useEffect($CB, [$$$DEPS])
+    - has:
+        field: arguments
+        has:
+          kind: array
+          has:
+            kind: member_expression
+            regex: '[Ss]tore\.'

package/rules/mobx-effect-store-write.yml

@@ -0,0 +1,21 @@
+id: mobx-effect-store-write
+language: tsx
+severity: error
+message: |
+  useEffect that writes to a store. This is `reaction()`-as-state-sync wearing a
+  useEffect costume — the same anti-pattern the mobx-models skill already bans,
+  just moved into the component tree where it re-runs on render instead of on
+  state change.
+  Move it into the store: a flow, an action called at the end of the flow that
+  produced the state, or a `computed get` if the value is derived.
+  See mobx-components "Anti-pattern: reaction() for state synchronization".
+rule:
+  all:
+    - pattern: useEffect($$$)
+    - has:
+        stopBy: end
+        kind: assignment_expression
+        has:
+          field: left
+          kind: member_expression
+          regex: '[Ss]tore\.'

package/rules/mobx-usestate-from-store.yml

@@ -0,0 +1,20 @@
+id: mobx-usestate-from-store
+language: tsx
+severity: warning
+message: |
+  useState seeded from observable state. Now there are two copies of the same
+  value and nothing keeps them in sync — which is why the next line is usually a
+  useEffect that re-assigns it on every id change (with an eslint/biome ignore
+  comment admitting the dependency list is a lie).
+  A draft being edited is a real thing — put it in the store (or a small
+  UI-state model) so it is observable, or reset it with `key={id}` on the child
+  instead of syncing it by effect. Read-only display needs no local copy at all.
+rule:
+  all:
+    - pattern: useState($INIT)
+    - has:
+        field: arguments
+        has:
+          stopBy: end
+          kind: member_expression
+          regex: '[Ss]tore\.'