@agentvibes/guardrails 0.1.0

package/rules/no-local-kit-clone-tsx.yml

@@ -0,0 +1,104 @@
+# ── the .tsx half of `no-local-kit-clone` ──
+#
+# ast-grep's `typescript` and `tsx` languages are DISJOINT: a `language:
+# typescript` rule reads .ts and never .tsx. `demo-mode-by-default-ts.yml`
+# records this repo learning that the hard way, so it is measured here rather
+# than assumed — 30 .tsx files in the park call make(Auto)Observable, and the
+# five twins with hits add 29 findings the .ts halves cannot see.
+#
+# Keep this file's `rule:` block IDENTICAL to `no-local-kit-clone.yml`.
+# Suppressing needs THIS id: `ast-grep-ignore: no-local-kit-clone-tsx`.
+#
+# ── wave 1, store rule 6 of 7 ──────────────────────────────────────────
+#
+# Report §13 step 1: the same handful of primitives is redeclared in repo after
+# repo — 7 local `Resource<T>` unions, 6 copies of `diagnostics.ts` inside a
+# single monorepo, a `usePageStore` improvised on `useMemo` with no dispose.
+# They drift: the discriminator alone is spelled `kind` in three repos, `status`
+# in two and `state` in one, so the "same" type does not typecheck against
+# itself across a boundary.
+#
+# TWO CARVE-OUTS, both deliberate, because an error-tier rule that fires on the
+# canonical definition is worse than no rule:
+#
+#  1. The kit package itself. `@agentvibes/kit` DOES NOT EXIST YET — the glob
+#     below currently guards a path with nothing behind it, and is here so the
+#     package can be created without immediately tripping its own rule. Until it
+#     is published, this rule names a destination that cannot yet be imported;
+#     that is the honest state of it, and the reason it is worth having anyway
+#     is to stop the count of copies growing while the package is built.
+#  2. `packages/observable-query/` in Retouch4Me — the reference implementation
+#     being promoted INTO the kit (§14). Telling it to import itself would be
+#     nonsense.
+#
+# `Resource` must carry type parameters to match. Without that the rule hits
+# `interface Resource { name; url; type; description }` in VolumePhotography — a
+# page listing conference links, nothing to do with async state.
+id: no-local-kit-clone-tsx
+language: tsx
+severity: error
+ignores:
+  - '**/node_modules/**'
+  - '**/packages/kit/**'
+  - '**/agentvibes-kit/**'
+  - '**/packages/observable-query/**'
+  - '**/*.test.tsx'
+  - '**/*.spec.tsx'
+  - '**/__tests__/**'
+message: |
+  A local redeclaration of a primitive that belongs to the shared kit. Every
+  copy drifts — across this codebase the same async union is discriminated by
+  `kind` in three repos, `status` in two and `state` in one, so the "same" type
+  will not typecheck against itself across a package boundary, and a fix to one
+  copy reaches none of the others.
+  Import it instead:
+    Resource<T> / QueryState<T>           → @agentvibes/kit/resource
+    usePageStore, QueryView, ShowWhen     → @agentvibes/kit/react
+    warnDegraded, warnNotImplemented      → @agentvibes/kit/diagnostics
+  If this IS the canonical definition — the kit package, or the implementation
+  being promoted into it — it belongs behind the path carve-outs at the top of
+  this rule rather than behind a suppression comment.
+  NOTE: `@agentvibes/kit` is not published yet, so today this rule freezes the
+  number of copies rather than offering an import you can actually write. Until
+  it ships, editing the declaration line of an existing copy needs a suppression
+  with a reason — the rule is here to stop copy number eight, not to claim the
+  migration is available.
+rule:
+  any:
+    # type Resource<T> = … / type QueryState<T> = …
+    - all:
+        - kind: type_alias_declaration
+        - has:
+            field: name
+            regex: '^(Resource|QueryResource|QueryState)$'
+        # Type parameters required: an unrelated domain `interface Resource`
+        # naming a link or a document is not this.
+        - has:
+            field: type_parameters
+            kind: type_parameters
+    # class Resource<T> / class ObservableQuery<T>
+    - all:
+        - kind: class_declaration
+        - has:
+            field: name
+            regex: '^(Resource|ObservableQuery|QueryResource)$'
+        - has:
+            field: type_parameters
+            kind: type_parameters
+    # function warnDegraded(…) / function usePageStore(…)
+    - all:
+        - kind: function_declaration
+        - has:
+            field: name
+            regex: '^(warnDegraded|warnNotImplemented|usePageStore|resetDiagnostics)$'
+    # const usePageStore = (…) => … / const warnDegraded = function (…) …
+    - all:
+        - kind: variable_declarator
+        - has:
+            field: name
+            regex: '^(warnDegraded|warnNotImplemented|usePageStore|resetDiagnostics)$'
+        - has:
+            field: value
+            any:
+              - kind: arrow_function
+              - kind: function_expression

package/rules/no-local-kit-clone.yml

@@ -0,0 +1,93 @@
+# ── wave 1, store rule 6 of 7 ──────────────────────────────────────────
+#
+# Report §13 step 1: the same handful of primitives is redeclared in repo after
+# repo — 7 local `Resource<T>` unions, 6 copies of `diagnostics.ts` inside a
+# single monorepo, a `usePageStore` improvised on `useMemo` with no dispose.
+# They drift: the discriminator alone is spelled `kind` in three repos, `status`
+# in two and `state` in one, so the "same" type does not typecheck against
+# itself across a boundary.
+#
+# TWO CARVE-OUTS, both deliberate, because an error-tier rule that fires on the
+# canonical definition is worse than no rule:
+#
+#  1. The kit package itself. `@agentvibes/kit` DOES NOT EXIST YET — the glob
+#     below currently guards a path with nothing behind it, and is here so the
+#     package can be created without immediately tripping its own rule. Until it
+#     is published, this rule names a destination that cannot yet be imported;
+#     that is the honest state of it, and the reason it is worth having anyway
+#     is to stop the count of copies growing while the package is built.
+#  2. `packages/observable-query/` in Retouch4Me — the reference implementation
+#     being promoted INTO the kit (§14). Telling it to import itself would be
+#     nonsense.
+#
+# `Resource` must carry type parameters to match. Without that the rule hits
+# `interface Resource { name; url; type; description }` in VolumePhotography — a
+# page listing conference links, nothing to do with async state.
+id: no-local-kit-clone
+language: typescript
+severity: error
+ignores:
+  - '**/node_modules/**'
+  - '**/packages/kit/**'
+  - '**/agentvibes-kit/**'
+  - '**/packages/observable-query/**'
+  - '**/*.test.ts'
+  - '**/*.spec.ts'
+  - '**/__tests__/**'
+message: |
+  A local redeclaration of a primitive that belongs to the shared kit. Every
+  copy drifts — across this codebase the same async union is discriminated by
+  `kind` in three repos, `status` in two and `state` in one, so the "same" type
+  will not typecheck against itself across a package boundary, and a fix to one
+  copy reaches none of the others.
+  Import it instead:
+    Resource<T> / QueryState<T>           → @agentvibes/kit/resource
+    usePageStore, QueryView, ShowWhen     → @agentvibes/kit/react
+    warnDegraded, warnNotImplemented      → @agentvibes/kit/diagnostics
+  If this IS the canonical definition — the kit package, or the implementation
+  being promoted into it — it belongs behind the path carve-outs at the top of
+  this rule rather than behind a suppression comment.
+  NOTE: `@agentvibes/kit` is not published yet, so today this rule freezes the
+  number of copies rather than offering an import you can actually write. Until
+  it ships, editing the declaration line of an existing copy needs a suppression
+  with a reason — the rule is here to stop copy number eight, not to claim the
+  migration is available.
+rule:
+  any:
+    # type Resource<T> = … / type QueryState<T> = …
+    - all:
+        - kind: type_alias_declaration
+        - has:
+            field: name
+            regex: '^(Resource|QueryResource|QueryState)$'
+        # Type parameters required: an unrelated domain `interface Resource`
+        # naming a link or a document is not this.
+        - has:
+            field: type_parameters
+            kind: type_parameters
+    # class Resource<T> / class ObservableQuery<T>
+    - all:
+        - kind: class_declaration
+        - has:
+            field: name
+            regex: '^(Resource|ObservableQuery|QueryResource)$'
+        - has:
+            field: type_parameters
+            kind: type_parameters
+    # function warnDegraded(…) / function usePageStore(…)
+    - all:
+        - kind: function_declaration
+        - has:
+            field: name
+            regex: '^(warnDegraded|warnNotImplemented|usePageStore|resetDiagnostics)$'
+    # const usePageStore = (…) => … / const warnDegraded = function (…) …
+    - all:
+        - kind: variable_declarator
+        - has:
+            field: name
+            regex: '^(warnDegraded|warnNotImplemented|usePageStore|resetDiagnostics)$'
+        - has:
+            field: value
+            any:
+              - kind: arrow_function
+              - kind: function_expression

package/rules/non-exhaustive-match.yml

@@ -0,0 +1,34 @@
+# ── rule body adopted from faceless-photo-lib `ts-pattern-prefer-exhaustive` (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 `pattern: $X.otherwise($$$)` fired on ANY `.otherwise()` method, not just
+# a ts-pattern chain — a false-positive class. Anchoring to a `match()` chain
+# removes it. Measured: +1 finding, 0 lost.
+#
+id: non-exhaustive-match
+language: typescript
+severity: warning
+message: |
+  `.otherwise()` catches unmatched variants silently. Prefer `.exhaustive()` so adding a
+  new union variant becomes a compile error everywhere it's branched on.
+  See defensive-errors Rule 2 and pattern-matching skill.
+rule:
+  all:
+    - kind: call_expression
+      has:
+        field: function
+        kind: identifier
+        regex: "^match$"
+    - inside:
+        stopBy:
+          not:
+            any:
+              - kind: member_expression
+              - kind: call_expression
+        kind: call_expression
+        has:
+          field: function
+          kind: member_expression
+          has:
+            field: property
+            regex: "^otherwise$"

package/rules/page-store-bare-usememo-tsx.yml

@@ -0,0 +1,47 @@
+# ── simple-components, rule 2 of 4 ─────────────────────────────────────
+#
+# A page store built by a bare `useMemo` has no `dispose()` and no protection
+# against StrictMode's double-mount, so its reactions and subscriptions outlive
+# the page that opened it. Report §8: the `PageStoreManager` the mobx-models
+# skill prescribes exists in exactly one repo of the park, and everywhere else
+# page stores are hand-rolled on `useMemo` — one of them carrying the comment
+# "PageStoreManager is not yet wired — use direct useMemo".
+#
+# The canon rule `no-local-kit-clone` bans DECLARING your own `usePageStore`;
+# this bans skipping it. Different sites, no overlap.
+#
+# The .tsx half: ast-grep's `typescript` and `tsx` languages are disjoint, so the
+# same rule ships twice under two ids. This is the half that matters most — page
+# stores are created in components. Suppress with the id the finding PRINTS.
+id: page-store-bare-usememo-tsx
+language: tsx
+severity: error
+ignores:
+  - '**/*.test.tsx'
+  - '**/*.spec.tsx'
+  - '**/__tests__/**'
+message: |
+  A store constructed inside a bare `useMemo`. `useMemo` is a cache, not a
+  lifecycle: React may drop and rebuild the value, and it never tells anyone the
+  old one is dead — so the store's reactions, intervals and subscriptions keep
+  running, and StrictMode's double-mount builds two of them.
+  Use the sanctioned hook, which owns creation, ref-counting and disposal:
+    const store = usePageStore(() => new GalleryPageStore(rootStore, slug), [slug])
+  It ships in `@agentvibes/kit/react`. Pass dependencies to the constructor
+  explicitly so the store stays testable with `new GalleryPageStore(fake, "x")`
+  and no render at all.
+  See the simple-components skill (§store access) and report §8.
+rule:
+  all:
+    - kind: call_expression
+    - has:
+        field: function
+        kind: identifier
+        regex: '^useMemo$'
+    - has:
+        stopBy: end
+        kind: new_expression
+        has:
+          field: constructor
+          kind: identifier
+          regex: 'Store$'

package/rules/page-store-bare-usememo.yml

@@ -0,0 +1,43 @@
+# ── simple-components, rule 2 of 4 ─────────────────────────────────────
+#
+# A page store built by a bare `useMemo` has no `dispose()` and no protection
+# against StrictMode's double-mount, so its reactions and subscriptions outlive
+# the page that opened it. Report §8: the `PageStoreManager` the mobx-models
+# skill prescribes exists in exactly one repo of the park, and everywhere else
+# page stores are hand-rolled on `useMemo` — one of them carrying the comment
+# "PageStoreManager is not yet wired — use direct useMemo".
+#
+# The canon rule `no-local-kit-clone` bans DECLARING your own `usePageStore`;
+# this bans skipping it. Different sites, no overlap.
+id: page-store-bare-usememo
+language: typescript
+severity: error
+ignores:
+  - '**/*.test.ts'
+  - '**/*.spec.ts'
+  - '**/__tests__/**'
+message: |
+  A store constructed inside a bare `useMemo`. `useMemo` is a cache, not a
+  lifecycle: React may drop and rebuild the value, and it never tells anyone the
+  old one is dead — so the store's reactions, intervals and subscriptions keep
+  running, and StrictMode's double-mount builds two of them.
+  Use the sanctioned hook, which owns creation, ref-counting and disposal:
+    const store = usePageStore(() => new GalleryPageStore(rootStore, slug), [slug])
+  It ships in `@agentvibes/kit/react`. Pass dependencies to the constructor
+  explicitly so the store stays testable with `new GalleryPageStore(fake, "x")`
+  and no render at all.
+  See the simple-components skill (§store access) and report §8.
+rule:
+  all:
+    - kind: call_expression
+    - has:
+        field: function
+        kind: identifier
+        regex: '^useMemo$'
+    - has:
+        stopBy: end
+        kind: new_expression
+        has:
+          field: constructor
+          kind: identifier
+          regex: 'Store$'

package/rules/screen-file-styling.yml

@@ -0,0 +1,29 @@
+# ── simple-components, rule 4 of 4 ─────────────────────────────────────
+#
+# The logic half of the two-tier split (decision D8, report §9): a screen picks
+# the models, matches the state and composes views. It carries no styling.
+#
+# Scoped to `**/*.screen.tsx` and nothing else, deliberately. The contract says
+# "logic components carry no styles", but there is no mechanical way to tell an
+# unmarked `.tsx` logic component from a plain one, and a blanket ban on
+# `className` would fire on every file of a Tailwind app. `*.screen.tsx` is the
+# one filename the convention makes explicit, so it is the one place the rule can
+# be right without a manifest.
+#
+# WARNING TIER: same reason as `view-file-logic` — D8 is recommendation-tier.
+id: screen-file-styling
+language: tsx
+severity: warning
+files:
+  - '**/*.screen.tsx'
+message: |
+  Styling on a screen. A screen's whole job is choosing models, matching state
+  and composing views; the moment it carries `className` or `style` it has taken
+  on a second job and starts growing the layout it should have delegated.
+  Move the markup into a `*.view.tsx` (or a shared UI primitive) and let the
+  screen pass it data.
+  See the simple-components skill (§two-tier) and report §9.
+rule:
+  all:
+    - kind: jsx_attribute
+    - regex: '^(className|style)='

package/rules/silent-default-return.yml

@@ -0,0 +1,17 @@
+id: silent-default-return
+language: typescript
+severity: warning
+message: |
+  Silent-default return on negation. Hides upstream bugs.
+  Throw with a contextual message, or return an explicit discriminated failure variant.
+  See defensive-errors Rule 1.
+rule:
+  any:
+    - pattern: "if (!$X) return null"
+    - pattern: "if (!$X) return []"
+    - pattern: "if (!$X) return 0"
+    - pattern: "if (!$X) return \"\""
+    - pattern: "if ($X === undefined) return null"
+    - pattern: "if ($X === undefined) return []"
+    - pattern: "if ($X == null) return null"
+    - pattern: "if ($X == null) return []"

package/rules/state-loading-boolean-shape-tsx.yml

@@ -0,0 +1,102 @@
+# ── the .tsx half of `state-loading-boolean-shape` ──
+#
+# ast-grep's `typescript` and `tsx` languages are DISJOINT: a `language:
+# typescript` rule reads .ts and never .tsx. `demo-mode-by-default-ts.yml`
+# records this repo learning that the hard way, so it is measured here rather
+# than assumed — 30 .tsx files in the park call make(Auto)Observable, and the
+# five twins with hits add 29 findings the .ts halves cannot see.
+#
+# Keep this file's `rule:` block IDENTICAL to `state-loading-boolean-shape.yml`.
+# Suppressing needs THIS id: `ast-grep-ignore: state-loading-boolean-shape-tsx`.
+#
+# ── wave 1, store rule 4 of 7 ──────────────────────────────────────────
+#
+# The boolean-soup async shape: `{ loading: boolean, data?: T, error?: E }`.
+# Four booleans' worth of states, of which most are nonsense — loading AND
+# error, loaded with no data, error with data — and nothing stops any of them
+# being constructed. It is the exact shape `Resource<T>` exists to replace.
+#
+# SCOPE, measured rather than guessed. The naive test — "a `loading: boolean`
+# field" — hits 71 sites park-wide, and most are legitimate: a `LoadMoreButton`
+# taking `loading?: boolean` as a prop is one boolean describing one thing, and
+# there is no invalid state to make unrepresentable. What makes the shape a
+# defect is that the async OUTCOME is recorded in more than one independently
+# settable place. So the rule requires a second field: another outcome boolean
+# (`isLoaded`, `isError`, `success`…), or a payload/error field that is optional
+# or null-unioned. A lone `loading?: boolean` stays silent, correctly.
+#
+# What that produces: 8 in `.ts` + 13 in `.tsx` = 21. The report's target of 114
+# is a DIFFERENT population — the migration target for `Resource<T>` adoption,
+# which also counts the 81 class fields spelled `loading = false` (a class
+# property, not a type declaration) plus hook-local boolean pairs. This rule is
+# scoped to type and interface declarations, so 21 is its honest number and the
+# remaining ~93 are not silently claimed.
+id: state-loading-boolean-shape-tsx
+language: tsx
+severity: error
+ignores:
+  - '**/*.test.tsx'
+  - '**/*.spec.tsx'
+  - '**/__tests__/**'
+utils:
+  bool-prop:
+    kind: property_signature
+    has:
+      stopBy: end
+      kind: predefined_type
+      regex: '^boolean$'
+  loading-flag:
+    all:
+      - matches: bool-prop
+      - has:
+          field: name
+          regex: '^(loading|isLoading|fetching|isFetching|busy|isBusy|pending|isPending)$'
+  # A SECOND place the same outcome is recorded. Deliberately excludes the
+  # loading family so a lone loading flag cannot satisfy both halves.
+  outcome-flag:
+    all:
+      - matches: bool-prop
+      - has:
+          field: name
+          regex: '^(loaded|isLoaded|error|isError|hasError|success|isSuccess|succeeded|failed|isFailed|done|isDone|ready|isReady)$'
+  # A payload or error that may or may not be there — the other way the shape
+  # admits "loaded but empty" and "errored but full".
+  payload-field:
+    kind: property_signature
+    all:
+      - has:
+          field: name
+          regex: '^(data|error|value|result|items|response|payload)$'
+      - any:
+          - regex: '\?\s*:'
+          - has:
+              stopBy: end
+              kind: union_type
+              regex: '(null|undefined)'
+message: |
+  An async state recorded as a boolean plus optional payload. The type admits
+  states that cannot happen — loading with an error, done with no data, an
+  error carrying data — so every reader has to re-derive which combination is
+  real, and they disagree.
+  Use a discriminated union, where the payload lives in the branch that has it:
+    { loading: boolean; data?: T; error?: string }
+    → | { status: "idle" }
+      | { status: "loading" }
+      | { status: "ready"; data: T }
+      | { status: "error"; message: string }
+  Then `match(state).with({ status: "ready" }, ({ data }) => …).exhaustive()`
+  makes adding a state a build error instead of a silent fallthrough.
+  For fetch-shaped data prefer the shared Query/`Resource<T>` rather than
+  hand-rolling the union again. See defensive-errors Rule 1 and the
+  mobx-models skill.
+rule:
+  all:
+    - any:
+        - kind: interface_body
+        - kind: object_type
+    - has:
+        matches: loading-flag
+    - has:
+        any:
+          - matches: outcome-flag
+          - matches: payload-field

package/rules/state-loading-boolean-shape.yml

@@ -0,0 +1,91 @@
+# ── wave 1, store rule 4 of 7 ──────────────────────────────────────────
+#
+# The boolean-soup async shape: `{ loading: boolean, data?: T, error?: E }`.
+# Four booleans' worth of states, of which most are nonsense — loading AND
+# error, loaded with no data, error with data — and nothing stops any of them
+# being constructed. It is the exact shape `Resource<T>` exists to replace.
+#
+# SCOPE, measured rather than guessed. The naive test — "a `loading: boolean`
+# field" — hits 71 sites park-wide, and most are legitimate: a `LoadMoreButton`
+# taking `loading?: boolean` as a prop is one boolean describing one thing, and
+# there is no invalid state to make unrepresentable. What makes the shape a
+# defect is that the async OUTCOME is recorded in more than one independently
+# settable place. So the rule requires a second field: another outcome boolean
+# (`isLoaded`, `isError`, `success`…), or a payload/error field that is optional
+# or null-unioned. A lone `loading?: boolean` stays silent, correctly.
+#
+# What that produces: 8 in `.ts` + 13 in `.tsx` = 21. The report's target of 114
+# is a DIFFERENT population — the migration target for `Resource<T>` adoption,
+# which also counts the 81 class fields spelled `loading = false` (a class
+# property, not a type declaration) plus hook-local boolean pairs. This rule is
+# scoped to type and interface declarations, so 21 is its honest number and the
+# remaining ~93 are not silently claimed.
+id: state-loading-boolean-shape
+language: typescript
+severity: error
+ignores:
+  - '**/*.test.ts'
+  - '**/*.spec.ts'
+  - '**/__tests__/**'
+utils:
+  bool-prop:
+    kind: property_signature
+    has:
+      stopBy: end
+      kind: predefined_type
+      regex: '^boolean$'
+  loading-flag:
+    all:
+      - matches: bool-prop
+      - has:
+          field: name
+          regex: '^(loading|isLoading|fetching|isFetching|busy|isBusy|pending|isPending)$'
+  # A SECOND place the same outcome is recorded. Deliberately excludes the
+  # loading family so a lone loading flag cannot satisfy both halves.
+  outcome-flag:
+    all:
+      - matches: bool-prop
+      - has:
+          field: name
+          regex: '^(loaded|isLoaded|error|isError|hasError|success|isSuccess|succeeded|failed|isFailed|done|isDone|ready|isReady)$'
+  # A payload or error that may or may not be there — the other way the shape
+  # admits "loaded but empty" and "errored but full".
+  payload-field:
+    kind: property_signature
+    all:
+      - has:
+          field: name
+          regex: '^(data|error|value|result|items|response|payload)$'
+      - any:
+          - regex: '\?\s*:'
+          - has:
+              stopBy: end
+              kind: union_type
+              regex: '(null|undefined)'
+message: |
+  An async state recorded as a boolean plus optional payload. The type admits
+  states that cannot happen — loading with an error, done with no data, an
+  error carrying data — so every reader has to re-derive which combination is
+  real, and they disagree.
+  Use a discriminated union, where the payload lives in the branch that has it:
+    { loading: boolean; data?: T; error?: string }
+    → | { status: "idle" }
+      | { status: "loading" }
+      | { status: "ready"; data: T }
+      | { status: "error"; message: string }
+  Then `match(state).with({ status: "ready" }, ({ data }) => …).exhaustive()`
+  makes adding a state a build error instead of a silent fallthrough.
+  For fetch-shaped data prefer the shared Query/`Resource<T>` rather than
+  hand-rolling the union again. See defensive-errors Rule 1 and the
+  mobx-models skill.
+rule:
+  all:
+    - any:
+        - kind: interface_body
+        - kind: object_type
+    - has:
+        matches: loading-flag
+    - has:
+        any:
+          - matches: outcome-flag
+          - matches: payload-field

package/rules/store-async-method-tsx.yml

@@ -0,0 +1,108 @@
+# ── the .tsx half of `store-async-method` ──
+#
+# ast-grep's `typescript` and `tsx` languages are DISJOINT: a `language:
+# typescript` rule reads .ts and never .tsx. `demo-mode-by-default-ts.yml`
+# records this repo learning that the hard way, so it is measured here rather
+# than assumed — 30 .tsx files in the park call make(Auto)Observable.
+#
+# Keep this file's `rule:` block IDENTICAL to `store-async-method.yml`.
+# Suppressing needs THIS id: `ast-grep-ignore: store-async-method-tsx`.
+#
+# ── wave 1, store rule 2 of 7 ──────────────────────────────────────────
+#
+# The other half of `store-no-runinaction`, and the reason that rule has so much
+# to find: an `async` method's continuation after each `await` is NOT covered by
+# the action `makeAutoObservable` created. Every assignment past the first await
+# is an unbatched mutation outside an action.
+#
+# Deliberately does NOT fire when the method already contains `runInAction` —
+# that method is reported by `store-no-runinaction` at `error`, and the fix is
+# the same conversion. Two findings prescribing one change read as two problems,
+# and the error-tier one is the one worth showing.
+#
+# So this rule catches the quieter half: the async store method that mutates
+# without even the hand-patched `runInAction`, where nothing marks the hole.
+id: store-async-method-tsx
+language: tsx
+severity: warning
+ignores:
+  - '**/*.test.tsx'
+  - '**/*.spec.tsx'
+  - '**/__tests__/**'
+utils:
+  store-class:
+    kind: class_declaration
+    has:
+      stopBy: end
+      kind: call_expression
+      has:
+        field: function
+        kind: identifier
+        regex: '^make(Auto)?Observable$'
+  contains-runinaction:
+    has:
+      stopBy: end
+      kind: call_expression
+      has:
+        field: function
+        kind: identifier
+        regex: '^runInAction$'
+  # An observable MUTATION — which is the whole defect. Without this clause the
+  # rule fires on any async method, and in SiteCraft 10 of its 12 hits were
+  # private I/O helpers (`walkDir`, `collectAllFiles`, `uploadFile`) that await
+  # a filesystem and never touch a field. Those have no action coverage to lose,
+  # so at warning tier they were pure noise.
+  mutates-this:
+    has:
+      stopBy: end
+      any:
+        # this.field = … / this.field += …
+        - all:
+            - any:
+                - kind: assignment_expression
+                - kind: augmented_assignment_expression
+            - has:
+                field: left
+                kind: member_expression
+                has:
+                  field: object
+                  kind: this
+        # this.list.push(…), this.map.set(…), … — mutation through a method.
+        - all:
+            - kind: call_expression
+            - has:
+                field: function
+                kind: member_expression
+                all:
+                  - has:
+                      field: property
+                      regex: '^(push|pop|shift|unshift|splice|sort|reverse|set|delete|clear|add)$'
+                  - has:
+                      field: object
+                      kind: member_expression
+                      has:
+                        field: object
+                        kind: this
+message: |
+  An `async` method on a store class. The action that `makeAutoObservable`
+  wrapped around it ends at the first `await` — everything after resumes
+  OUTSIDE it, so each assignment there is an unbatched mutation and observers
+  see the half-updated store between them.
+  Use a `flow`, which resumes inside an action at every yield:
+    async load() { this.x = await f(); this.y = await g() }
+    → load = flow(function* (this: Store) { this.x = yield f(); this.y = yield g() })
+  Scope: this fires only when the method actually MUTATES an observable —
+  assigns `this.field` or calls `push`/`set`/`delete` on one. A private async
+  helper that only does I/O and returns has no action coverage to lose and stays
+  silent.
+  See the mobx-models skill.
+rule:
+  all:
+    - kind: method_definition
+    - regex: '^((private|public|protected|static|override|abstract)\s+)*async\s'
+    - inside:
+        stopBy: end
+        matches: store-class
+    - matches: mutates-this
+    - not:
+        matches: contains-runinaction