@agentvibes/guardrails 0.1.0

package/rules/__fixtures__/store-new-map/bad.tsx

@@ -0,0 +1,22 @@
+// Every field here MUST be reported by `store-new-map`.
+import { makeAutoObservable } from "mobx"
+
+export class GalleryStore {
+  // Observable field, non-observable contents: .set() notifies nobody.
+  entries = new Map<string, Row>()
+  byId = new Map()
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+}
+
+export class CalendarStore {
+  // Annotated, but this field is not the one exempted.
+  monthCache = new Map<string, Day[]>()
+  private _other = new Map<string, number>()
+
+  constructor() {
+    makeAutoObservable(this, { somethingElse: false })
+  }
+}

package/rules/__fixtures__/store-new-map/good.ts

@@ -0,0 +1,41 @@
+// NOTHING in this file may be reported by `store-new-map`.
+import { makeAutoObservable, observable } from "mobx"
+
+export class GalleryStore {
+  // The fix: mutations are tracked.
+  entries = observable.map<string, Row>()
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+}
+
+// The LEGAL pattern the rule must not break: a private cache explicitly
+// annotated non-observable. Nothing renders from it, so a plain Map is right.
+export class MainPageStore {
+  private _jobInfoCache = new Map<string, JobInfo>()
+  jobs: Job[] = []
+
+  constructor() {
+    makeAutoObservable(this, { _jobInfoCache: false })
+  }
+}
+
+// Several exempted fields at once.
+export class MetricsStore {
+  private counters = new Map<string, number>()
+  private gauges = new Map<string, number>()
+  total = 0
+
+  constructor() {
+    makeAutoObservable(this, { counters: false, gauges: false })
+  }
+}
+
+// Not a store: a plain service class.
+export class MetricsService {
+  private counters = new Map<string, number>()
+}
+
+// Module-level constant, not a store field.
+export const REGISTRY = new Map<string, string>()

package/rules/__fixtures__/store-new-map/good.tsx

@@ -0,0 +1,41 @@
+// NOTHING in this file may be reported by `store-new-map`.
+import { makeAutoObservable, observable } from "mobx"
+
+export class GalleryStore {
+  // The fix: mutations are tracked.
+  entries = observable.map<string, Row>()
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+}
+
+// The LEGAL pattern the rule must not break: a private cache explicitly
+// annotated non-observable. Nothing renders from it, so a plain Map is right.
+export class MainPageStore {
+  private _jobInfoCache = new Map<string, JobInfo>()
+  jobs: Job[] = []
+
+  constructor() {
+    makeAutoObservable(this, { _jobInfoCache: false })
+  }
+}
+
+// Several exempted fields at once.
+export class MetricsStore {
+  private counters = new Map<string, number>()
+  private gauges = new Map<string, number>()
+  total = 0
+
+  constructor() {
+    makeAutoObservable(this, { counters: false, gauges: false })
+  }
+}
+
+// Not a store: a plain service class.
+export class MetricsService {
+  private counters = new Map<string, number>()
+}
+
+// Module-level constant, not a store field.
+export const REGISTRY = new Map<string, string>()

package/rules/__fixtures__/store-no-runinaction/bad.ts

@@ -0,0 +1,67 @@
+// Every runInAction call in this file MUST be reported by `store-no-runinaction`.
+import { makeAutoObservable, runInAction } from "mobx"
+
+export class GitStore {
+  loading = false
+  branch: string | null = null
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  async refresh(dir: string): Promise<void> {
+    runInAction(() => {
+      this.loading = true
+    })
+    const branch = await readBranch(dir)
+    runInAction(() => {
+      this.branch = branch
+      this.loading = false
+    })
+  }
+
+  // Nested inside a callback — still inside the store class.
+  subscribe(): void {
+    onChange(() => {
+      runInAction(() => {
+        this.branch = null
+      })
+    })
+  }
+}
+
+// The generic-argument spelling of the annotation. A `pattern:
+// makeAutoObservable($$$)` does not match a call carrying explicit type
+// arguments, which is how SiteCraft's project.store.ts — 7 real call sites —
+// went missing from the first version of this rule.
+export class ProjectStore {
+  private _buildTimer: number | null = null
+  projects: string[] = []
+
+  constructor() {
+    makeAutoObservable<this, "_buildTimer">(this, { _buildTimer: false })
+  }
+
+  async load(): Promise<void> {
+    const list = await fetchProjects()
+    runInAction(() => {
+      this.projects = list
+    })
+  }
+}
+
+// `makeObservable` is the other spelling of the same thing.
+export class SessionStore {
+  items: string[] = []
+
+  constructor() {
+    makeObservable(this, { items: observable })
+  }
+
+  async pull(): Promise<void> {
+    const items = await fetchItems()
+    runInAction(() => {
+      this.items = items
+    })
+  }
+}

package/rules/__fixtures__/store-no-runinaction/bad.tsx

@@ -0,0 +1,67 @@
+// Every runInAction call in this file MUST be reported by `store-no-runinaction`.
+import { makeAutoObservable, runInAction } from "mobx"
+
+export class GitStore {
+  loading = false
+  branch: string | null = null
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  async refresh(dir: string): Promise<void> {
+    runInAction(() => {
+      this.loading = true
+    })
+    const branch = await readBranch(dir)
+    runInAction(() => {
+      this.branch = branch
+      this.loading = false
+    })
+  }
+
+  // Nested inside a callback — still inside the store class.
+  subscribe(): void {
+    onChange(() => {
+      runInAction(() => {
+        this.branch = null
+      })
+    })
+  }
+}
+
+// The generic-argument spelling of the annotation. A `pattern:
+// makeAutoObservable($$$)` does not match a call carrying explicit type
+// arguments, which is how SiteCraft's project.store.ts — 7 real call sites —
+// went missing from the first version of this rule.
+export class ProjectStore {
+  private _buildTimer: number | null = null
+  projects: string[] = []
+
+  constructor() {
+    makeAutoObservable<this, "_buildTimer">(this, { _buildTimer: false })
+  }
+
+  async load(): Promise<void> {
+    const list = await fetchProjects()
+    runInAction(() => {
+      this.projects = list
+    })
+  }
+}
+
+// `makeObservable` is the other spelling of the same thing.
+export class SessionStore {
+  items: string[] = []
+
+  constructor() {
+    makeObservable(this, { items: observable })
+  }
+
+  async pull(): Promise<void> {
+    const items = await fetchItems()
+    runInAction(() => {
+      this.items = items
+    })
+  }
+}

package/rules/__fixtures__/store-no-runinaction/good.ts

@@ -0,0 +1,39 @@
+// NOTHING in this file may be reported by `store-no-runinaction`.
+import { flow, makeAutoObservable } from "mobx"
+
+// The fix: a flow. Every yield point resumes inside an action, so there is
+// nothing left for runInAction to wrap.
+export class GitStore {
+  loading = false
+  branch: string | null = null
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  refresh = flow(function* (this: GitStore, dir: string) {
+    this.loading = true
+    this.branch = yield readBranch(dir)
+    this.loading = false
+  })
+}
+
+// A plain class with no MobX annotation is not a store. `runInAction` here
+// would be pointless rather than banned, and this rule is about stores.
+export class PlainCache {
+  entries: string[] = []
+
+  add(entry: string): void {
+    this.entries.push(entry)
+  }
+}
+
+// A module-level helper that is not inside any store class.
+export function describeBranch(branch: string): string {
+  return `on ${branch}`
+}
+
+// Importing the symbol is not calling it. The report's "66 runInAction in
+// SiteCraft" counted 7 import lines exactly like this one; the real call-site
+// count is 59.
+export { runInAction } from "mobx"

package/rules/__fixtures__/store-no-runinaction/good.tsx

@@ -0,0 +1,39 @@
+// NOTHING in this file may be reported by `store-no-runinaction`.
+import { flow, makeAutoObservable } from "mobx"
+
+// The fix: a flow. Every yield point resumes inside an action, so there is
+// nothing left for runInAction to wrap.
+export class GitStore {
+  loading = false
+  branch: string | null = null
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  refresh = flow(function* (this: GitStore, dir: string) {
+    this.loading = true
+    this.branch = yield readBranch(dir)
+    this.loading = false
+  })
+}
+
+// A plain class with no MobX annotation is not a store. `runInAction` here
+// would be pointless rather than banned, and this rule is about stores.
+export class PlainCache {
+  entries: string[] = []
+
+  add(entry: string): void {
+    this.entries.push(entry)
+  }
+}
+
+// A module-level helper that is not inside any store class.
+export function describeBranch(branch: string): string {
+  return `on ${branch}`
+}
+
+// Importing the symbol is not calling it. The report's "66 runInAction in
+// SiteCraft" counted 7 import lines exactly like this one; the real call-site
+// count is 59.
+export { runInAction } from "mobx"

package/rules/__fixtures__/store-no-setinterval-poll/bad.ts

@@ -0,0 +1,19 @@
+// Every setInterval call here MUST be reported by `store-no-setinterval-poll`.
+import { makeAutoObservable } from "mobx"
+
+export class LiveDataStore {
+  rows: Row[] = []
+  private timer: ReturnType<typeof setInterval> | undefined
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  start(): void {
+    this.timer = setInterval(() => void this.refresh(), POLL_MS)
+  }
+
+  startSynthetic(sink: Sink): void {
+    setInterval(() => sink.onRow(this.emitSyntheticRow()), SSE_TICK_MS)
+  }
+}

package/rules/__fixtures__/store-no-setinterval-poll/bad.tsx

@@ -0,0 +1,19 @@
+// Every setInterval call here MUST be reported by `store-no-setinterval-poll`.
+import { makeAutoObservable } from "mobx"
+
+export class LiveDataStore {
+  rows: Row[] = []
+  private timer: ReturnType<typeof setInterval> | undefined
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  start(): void {
+    this.timer = setInterval(() => void this.refresh(), POLL_MS)
+  }
+
+  startSynthetic(sink: Sink): void {
+    setInterval(() => sink.onRow(this.emitSyntheticRow()), SSE_TICK_MS)
+  }
+}

package/rules/__fixtures__/store-no-setinterval-poll/good.ts

@@ -0,0 +1,29 @@
+// NOTHING in this file may be reported by `store-no-setinterval-poll`.
+import { makeAutoObservable } from "mobx"
+
+export class LiveDataStore {
+  rows: Row[] = []
+
+  // A TYPE position, not a call. The commonest way `setInterval` appears in a
+  // store field declaration, and it must stay silent.
+  private timer: ReturnType<typeof setInterval> | undefined
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  // The fix: the Query object owns the disposer, the in-flight dedup and the
+  // visibility handling.
+  readonly rowsQuery = new Query(() => fetchRows(), { refetchInterval: POLL_MS })
+
+  stop(): void {
+    clearInterval(this.timer)
+  }
+}
+
+// Not a store: a plain scheduler class.
+export class Ticker {
+  start(): void {
+    setInterval(() => this.tick(), 1000)
+  }
+}

package/rules/__fixtures__/store-no-setinterval-poll/good.tsx

@@ -0,0 +1,29 @@
+// NOTHING in this file may be reported by `store-no-setinterval-poll`.
+import { makeAutoObservable } from "mobx"
+
+export class LiveDataStore {
+  rows: Row[] = []
+
+  // A TYPE position, not a call. The commonest way `setInterval` appears in a
+  // store field declaration, and it must stay silent.
+  private timer: ReturnType<typeof setInterval> | undefined
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  // The fix: the Query object owns the disposer, the in-flight dedup and the
+  // visibility handling.
+  readonly rowsQuery = new Query(() => fetchRows(), { refetchInterval: POLL_MS })
+
+  stop(): void {
+    clearInterval(this.timer)
+  }
+}
+
+// Not a store: a plain scheduler class.
+export class Ticker {
+  start(): void {
+    setInterval(() => this.tick(), 1000)
+  }
+}

package/rules/__fixtures__/ts-pattern-dangling-match/bad.ts

@@ -0,0 +1,20 @@
+// Every match chain here MUST be reported by `ts-pattern-dangling-match`.
+import { match } from "ts-pattern"
+
+// A real observatory chain with its terminator deleted: evaluates to a builder
+// object, which is truthy, so the caller keeps compiling and every arm is dead.
+export function label(r: Resource<string>): string {
+  return match(r)
+    .with({ kind: "idle" }, () => "idle")
+    .with({ kind: "ready" }, ({ value }) => value)
+}
+
+// The hard case: a dangling chain nested inside a callback of an OUTER
+// terminated chain. The spine-walk must not let the outer terminator mask it.
+export function label3(r: Resource<Item[]>): string {
+  return match(r)
+    .with({ kind: "ready" }, ({ value }) =>
+      value.map((it) => match(it).with({ t: "a" }, () => "A")).join(","),
+    )
+    .otherwise(() => "")
+}

package/rules/__fixtures__/ts-pattern-dangling-match/good.ts

@@ -0,0 +1,35 @@
+// NOTHING in this file may be reported by `ts-pattern-dangling-match`.
+import { match } from "ts-pattern"
+
+export function label(r: Resource<string>): string {
+  return match(r)
+    .with({ kind: "idle" }, () => "idle")
+    .with({ kind: "ready" }, ({ value }) => value)
+    .exhaustive()
+}
+
+// `.otherwise()` and `.run()` terminate a chain too. Whether `.exhaustive()`
+// should be PREFERRED over `.otherwise()` is a separate question the owner has
+// deferred (decision #4); this rule is only about a chain that ends nowhere.
+export function label2(r: Resource<string>): string {
+  return match(r).with({ kind: "idle" }, () => "idle").otherwise(() => "?")
+}
+
+export function label4(r: Resource<string>): string {
+  return match(r).with({ kind: "idle" }, () => "idle").run()
+}
+
+// Per-arm comments are why the terminator is matched structurally rather than
+// with a surface pattern: `smart` strictness compares comment nodes too.
+export function label5(r: Resource<string>): string {
+  return match(r)
+    // the boring case
+    .with({ kind: "idle" }, () => "idle")
+    // the interesting one
+    .with({ kind: "ready" }, ({ value }) => value)
+    .exhaustive()
+}
+
+// String.prototype.match is not ts-pattern and must never be confused for it.
+export const m = "abc".match(/b/)
+export const m2 = someText.match(pattern)?.[0]

package/rules/__fixtures__/ui-imports-app-store/src/ui/bad.tsx

@@ -0,0 +1,13 @@
+// Every import in this file MUST be reported by `ui-imports-app-store`.
+// Path matters: the rule is scoped to `**/src/ui/**`, so this fixture has to
+// live under `src/ui/` for the rule to see it at all.
+
+import { galleryStore } from "../../stores/galleryStore"
+import { GalleryStore } from "../../stores/galleryStore"
+import { rootStore } from "../../store/rootStore"
+import { useStore } from "../../stores/StoreContext"
+import photoStore from "../../stores/photoStore"
+
+export const Panel = ({ label }: { label: string }) => (
+  <div>{label}{galleryStore.n}{GalleryStore.name}{rootStore.n}{useStore.name}{photoStore.n}</div>
+)

package/rules/__fixtures__/ui-imports-app-store/src/ui/good.tsx

@@ -0,0 +1,23 @@
+// NOTHING in this file may be reported by `ui-imports-app-store`.
+
+// X7 (report §2): a reusable UI component typed against the view-model
+// interface the store implements is exactly what the mobx-models view-model
+// pattern prescribes. `import type` erases at build time — the component
+// depends on a shape, not on an app store — so it must not trip the rule that
+// bans importing the store itself.
+import type { IGalleryModel } from "../../stores/galleryStore"
+import type { RootStore } from "../../store/rootStore"
+import type Photo from "../../stores/photo"
+import type * as StoreTypes from "../../stores/types"
+import { type IUiModel, type ITabModel } from "../../stores/uiStore"
+
+// Ordinary UI-package dependencies.
+import { cn } from "../../lib/cn"
+
+export const Panel = ({
+  model,
+  ui,
+}: {
+  model: IGalleryModel
+  ui: IUiModel
+}) => <div className={cn("panel")}>{model.title} {ui.tab}</div>

package/rules/__fixtures__/view-file-logic/bad.view.tsx

@@ -0,0 +1,16 @@
+// BAD: a view that decides. Hook, match, ternary — all three belong upstairs.
+import { useState } from "react";
+import { match } from "ts-pattern";
+
+export function StatusBadge(props: { readonly status: "ok" | "bad"; readonly label: string }) {
+  const [open, setOpen] = useState(false);
+  const tone = match(props.status)
+    .with("ok", () => "green")
+    .with("bad", () => "red")
+    .exhaustive();
+  return (
+    <span onClick={() => setOpen(true)} style={{ color: tone }}>
+      {open ? props.label : ""}
+    </span>
+  );
+}

package/rules/__fixtures__/view-file-logic/good.view.tsx

@@ -0,0 +1,7 @@
+// GOOD: props in, JSX out. The tone was decided upstairs; useTheme is exempt.
+import { useTheme } from "./theme";
+
+export function StatusBadge(props: { readonly tone: string; readonly label: string }) {
+  const theme = useTheme();
+  return <span style={{ color: props.tone, fontFamily: theme.font }}>{props.label}</span>;
+}

package/rules/__fixtures__/view-imports-store/bad.view.tsx

@@ -0,0 +1,13 @@
+// Every import in this file MUST be reported by `view-imports-store`.
+// A `*.view.tsx` is props in, JSX out — it may not reach a store by any route,
+// not even the global rootStore that a screen is allowed to import.
+
+import { rootStore } from "../../stores/rootStore"
+import { galleryStore } from "../../stores/galleryStore"
+import { GalleryStore } from "../../stores/galleryStore"
+import { useStore } from "../../stores/StoreContext"
+import { SESSION_KEY } from "../../stores/keys"
+
+export const GalleryHeaderView = ({ title }: { title: string }) => (
+  <h1 data-k={SESSION_KEY}>{title}{rootStore.n}{galleryStore.n}{GalleryStore.name}{useStore.name}</h1>
+)

package/rules/__fixtures__/view-imports-store/good.view.tsx

@@ -0,0 +1,23 @@
+// NOTHING in this file may be reported by `view-imports-store`.
+
+// A view is typed against the model interface it renders (C40). The type
+// vanishes at build time, so it is a contract, not a store dependency.
+import type { IGalleryModel } from "../../stores/galleryStore"
+import { type IUiModel } from "../../stores/uiStore"
+
+// Everything else a view is allowed to touch: shared UI primitives and pure
+// formatting helpers.
+import { Badge } from "../../components/Badge/Badge"
+import { formatBytes } from "../../lib/format"
+
+export const GalleryHeaderView = ({
+  model,
+  ui,
+}: {
+  model: IGalleryModel
+  ui: IUiModel
+}) => (
+  <h1>
+    {model.title} <Badge label={formatBytes(model.size)} /> {ui.tab}
+  </h1>
+)

package/rules/__fixtures__/zod-optional-nullable/bad.ts

@@ -0,0 +1,10 @@
+// Every call here MUST be reported by `zod-optional-nullable`.
+import { z } from "zod"
+export const A = z.object({ name: z.string().optional() })
+export const B = z.object({ age: z.number().nullable() })
+export const C = z.object({ bio: z.string().nullish() })
+// ADDED BY THE WAVE-2 UPGRADE: the old `z.$T().optional()` matched only a
+// DIRECT call on `z`, so a chained builder and a named schema both escaped.
+export const D = z.object({ name: z.string().min(1).optional() })
+export const E = UserSchema.optional()
+export const F = z.object({ tag: z.enum(["a", "b"]).trim().nullable() })

package/rules/__fixtures__/zod-optional-nullable/bad.tsx

@@ -0,0 +1,17 @@
+// Every call here MUST be reported by `zod-optional-nullable-tsx`.
+// The .tsx twin of bad.ts, placed where this rule actually needed to see:
+// a validation schema sitting right next to the component that uses it.
+import { z } from "zod"
+
+export const A = z.object({ name: z.string().optional() })
+export const B = z.object({ age: z.number().nullable() })
+export const C = z.object({ bio: z.string().nullish() })
+// ADDED BY THE WAVE-2 UPGRADE: the old `z.$T().optional()` matched only a
+// DIRECT call on `z`, so a chained builder and a named schema both escaped.
+export const D = z.object({ name: z.string().min(1).optional() })
+export const E = UserSchema.optional()
+export const F = z.object({ tag: z.enum(["a", "b"]).trim().nullable() })
+
+export const ProfileForm = () => {
+  return <form aria-label="profile">{A.shape.name.description}</form>
+}

package/rules/__fixtures__/zod-optional-nullable/good.ts

@@ -0,0 +1,16 @@
+// NOTHING in this file may be reported by `zod-optional-nullable`.
+import { z } from "zod"
+
+// The fix: model the absence as a variant, so "missing" and "present" are
+// distinguishable states rather than one field that might be undefined.
+export const User = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("anonymous") }),
+  z.object({ status: z.literal("named"), name: z.string() }),
+])
+
+export const Plain = z.object({ name: z.string(), age: z.number() })
+
+// `.optional()` on something that is not a zod schema — the receiver anchor is
+// what keeps an unrelated builder with the same method name out of this rule.
+export const q = queryBuilder.optional()
+export const p = protoField.nullable()

package/rules/__fixtures__/zod-optional-nullable/good.tsx

@@ -0,0 +1,20 @@
+// NOTHING in this file may be reported by `zod-optional-nullable-tsx`.
+import { z } from "zod"
+
+// The fix: model the absence as a variant, so "missing" and "present" are
+// distinguishable states rather than one field that might be undefined.
+export const User = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("anonymous") }),
+  z.object({ status: z.literal("named"), name: z.string() }),
+])
+
+export const Plain = z.object({ name: z.string(), age: z.number() })
+
+// `.optional()` on something that is not a zod schema — the receiver anchor is
+// what keeps an unrelated builder with the same method name out of this rule.
+export const q = queryBuilder.optional()
+export const p = protoField.nullable()
+
+export const ProfileForm = () => {
+  return <form aria-label="profile">{Plain.shape.name.description}</form>
+}