@agentvibes/guardrails 0.1.0

package/rules/__fixtures__/screen-file-styling/good.screen.tsx

@@ -0,0 +1,8 @@
+// GOOD: the screen picks the model and composes views; styling lives in them.
+import { observer } from "mobx-react-lite";
+import { rootStore } from "./rootStore";
+import { GalleryGrid } from "./galleryGrid.view";
+
+export const GalleryScreen = observer(function GalleryScreen() {
+  return <GalleryGrid photos={rootStore.gallery.photos} />;
+});

package/rules/__fixtures__/state-loading-boolean-shape/bad.ts

@@ -0,0 +1,36 @@
+// Every type here MUST be reported by `state-loading-boolean-shape`.
+
+// The canonical boolean soup: loading + optional payload + optional error.
+export interface FetchState {
+  loading: boolean
+  data?: User[]
+  error?: string
+}
+
+// Multi-flag, no payload — the shape gallerykit's ImageLoadState really has.
+export interface ImageLoadState {
+  isLoading: boolean
+  isLoaded: boolean
+  isError: boolean
+  error: Event | null
+}
+
+// Null-union rather than optional; same set of impossible states.
+export interface AdapterState {
+  loading: boolean
+  data: Rows | null
+  error: string | null
+}
+
+// A type alias rather than an interface.
+export type PlaygroundState = {
+  isFetching: boolean
+  result?: QueryResult
+  error?: string
+}
+
+// `pending` is the same axis under another name.
+export interface SaveState {
+  pending: boolean
+  succeeded: boolean
+}

package/rules/__fixtures__/state-loading-boolean-shape/bad.tsx

@@ -0,0 +1,36 @@
+// Every type here MUST be reported by `state-loading-boolean-shape`.
+
+// The canonical boolean soup: loading + optional payload + optional error.
+export interface FetchState {
+  loading: boolean
+  data?: User[]
+  error?: string
+}
+
+// Multi-flag, no payload — the shape gallerykit's ImageLoadState really has.
+export interface ImageLoadState {
+  isLoading: boolean
+  isLoaded: boolean
+  isError: boolean
+  error: Event | null
+}
+
+// Null-union rather than optional; same set of impossible states.
+export interface AdapterState {
+  loading: boolean
+  data: Rows | null
+  error: string | null
+}
+
+// A type alias rather than an interface.
+export type PlaygroundState = {
+  isFetching: boolean
+  result?: QueryResult
+  error?: string
+}
+
+// `pending` is the same axis under another name.
+export interface SaveState {
+  pending: boolean
+  succeeded: boolean
+}

package/rules/__fixtures__/state-loading-boolean-shape/good.ts

@@ -0,0 +1,44 @@
+// NOTHING in this file may be reported by `state-loading-boolean-shape`.
+
+// The fix: one discriminant, payload only in the branch that has one.
+export type Resource<T> =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "ready"; data: T }
+  | { status: "error"; message: string }
+
+// Independent axes done RIGHT — this is SWR, not boolean soup: "has data" and
+// "a fetch is in flight" genuinely are orthogonal (report §14).
+export type QueryState<T> =
+  | { status: "pending"; fetchActivity: "idle" | "fetching" }
+  | { status: "success"; data: T; fetchActivity: "idle" | "fetching" }
+  | { status: "error"; error: string; fetchActivity: "idle" | "fetching" }
+
+// A LONE loading flag on a presentational component's props. One boolean
+// describing one thing, no payload, no second outcome field — there is no
+// invalid state to make unrepresentable. 71 raw `loading: boolean` sites exist
+// park-wide and most look like this; flagging them would be noise.
+export interface LoadMoreButtonProps {
+  loading?: boolean
+  onPress: () => void
+  label: string
+}
+
+export interface InfiniteScrollProps {
+  loading?: boolean
+  hasMore: boolean
+  onLoadMore: () => void
+}
+
+// A payload with no loading flag at all.
+export interface UserResponse {
+  data?: User
+  error?: string
+}
+
+// Booleans that are not about async outcome.
+export interface EditorFlags {
+  loading: boolean
+  readOnly: boolean
+  wrapLines: boolean
+}

package/rules/__fixtures__/state-loading-boolean-shape/good.tsx

@@ -0,0 +1,44 @@
+// NOTHING in this file may be reported by `state-loading-boolean-shape`.
+
+// The fix: one discriminant, payload only in the branch that has one.
+export type Resource<T> =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "ready"; data: T }
+  | { status: "error"; message: string }
+
+// Independent axes done RIGHT — this is SWR, not boolean soup: "has data" and
+// "a fetch is in flight" genuinely are orthogonal (report §14).
+export type QueryState<T> =
+  | { status: "pending"; fetchActivity: "idle" | "fetching" }
+  | { status: "success"; data: T; fetchActivity: "idle" | "fetching" }
+  | { status: "error"; error: string; fetchActivity: "idle" | "fetching" }
+
+// A LONE loading flag on a presentational component's props. One boolean
+// describing one thing, no payload, no second outcome field — there is no
+// invalid state to make unrepresentable. 71 raw `loading: boolean` sites exist
+// park-wide and most look like this; flagging them would be noise.
+export interface LoadMoreButtonProps {
+  loading?: boolean
+  onPress: () => void
+  label: string
+}
+
+export interface InfiniteScrollProps {
+  loading?: boolean
+  hasMore: boolean
+  onLoadMore: () => void
+}
+
+// A payload with no loading flag at all.
+export interface UserResponse {
+  data?: User
+  error?: string
+}
+
+// Booleans that are not about async outcome.
+export interface EditorFlags {
+  loading: boolean
+  readOnly: boolean
+  wrapLines: boolean
+}

package/rules/__fixtures__/store-async-method/bad.ts

@@ -0,0 +1,37 @@
+// Every async method here MUST be reported by `store-async-method`.
+import { makeAutoObservable } from "mobx"
+
+export class ProjectStore {
+  projects: string[] = []
+  current: string | null = null
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  // The action ends at the await; the assignment after it is unbatched.
+  async load(): Promise<void> {
+    const list = await fetchProjects()
+    this.projects = list
+  }
+
+  // Two awaits, two holes.
+  async open(id: string): Promise<void> {
+    this.current = await resolveId(id)
+    this.projects = await fetchProjects()
+  }
+
+  private async refreshQuietly(): Promise<void> {
+    this.projects = await fetchProjects()
+  }
+}
+
+export class SessionStore {
+  token = ""
+  constructor() {
+    makeObservable(this, { token: observable })
+  }
+  async authenticate(): Promise<void> {
+    this.token = await getToken()
+  }
+}

package/rules/__fixtures__/store-async-method/bad.tsx

@@ -0,0 +1,37 @@
+// Every async method here MUST be reported by `store-async-method`.
+import { makeAutoObservable } from "mobx"
+
+export class ProjectStore {
+  projects: string[] = []
+  current: string | null = null
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  // The action ends at the await; the assignment after it is unbatched.
+  async load(): Promise<void> {
+    const list = await fetchProjects()
+    this.projects = list
+  }
+
+  // Two awaits, two holes.
+  async open(id: string): Promise<void> {
+    this.current = await resolveId(id)
+    this.projects = await fetchProjects()
+  }
+
+  private async refreshQuietly(): Promise<void> {
+    this.projects = await fetchProjects()
+  }
+}
+
+export class SessionStore {
+  token = ""
+  constructor() {
+    makeObservable(this, { token: observable })
+  }
+  async authenticate(): Promise<void> {
+    this.token = await getToken()
+  }
+}

package/rules/__fixtures__/store-async-method/good.ts

@@ -0,0 +1,73 @@
+// NOTHING in this file may be reported by `store-async-method`.
+import { flow, makeAutoObservable, runInAction } from "mobx"
+
+export class ProjectStore {
+  projects: string[] = []
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  // The fix: a flow resumes inside an action at every yield.
+  load = flow(function* (this: ProjectStore) {
+    this.projects = yield fetchProjects()
+  })
+
+  // Already reported by `store-no-runinaction` at error tier, and the fix is
+  // the same conversion. Reporting it twice would read as two problems, so this
+  // rule stands down when runInAction is present.
+  async loadLegacy(): Promise<void> {
+    const list = await fetchProjects()
+    runInAction(() => {
+      this.projects = list
+    })
+  }
+
+  // Not async.
+  reset(): void {
+    this.projects = []
+  }
+}
+
+// A plain class with no MobX annotation is not a store; async methods on it
+// have no action semantics to lose.
+export class ApiClient {
+  async get(url: string): Promise<Response> {
+    return fetch(url)
+  }
+}
+
+// ── the false-positive class this rule was narrowed to exclude ─────────
+// Private async helpers that do pure I/O and never touch an observable field.
+// There is no action coverage to lose, so there is nothing to convert. Real:
+// SiteCraft's walkDir / collectAllFiles / uploadFile — 10 of the rule's 12
+// hits in that repo before the mutation requirement was added.
+export class ContentStore {
+  files: string[] = []
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  private async walkDir(fs: FileSystem, dir: string, items: Meta[]): Promise<void> {
+    let entries: string[]
+    try {
+      entries = await fs.readdir(dir)
+    } catch {
+      return
+    }
+    for (const e of entries) items.push(await fs.stat(e))
+  }
+
+  private async collectAllFiles(fs: FileSystem, dir: string): Promise<Record<string, string>> {
+    const result: Record<string, string> = {}
+    await this.walkFs(fs, dir, result)
+    return result
+  }
+
+  async uploadFile(targetDir: string, name: string, data: Uint8Array): Promise<string> {
+    const path = `${targetDir}/${name}`
+    await this.fs.writeFile(path, data)
+    return path
+  }
+}

package/rules/__fixtures__/store-async-method/good.tsx

@@ -0,0 +1,73 @@
+// NOTHING in this file may be reported by `store-async-method`.
+import { flow, makeAutoObservable, runInAction } from "mobx"
+
+export class ProjectStore {
+  projects: string[] = []
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  // The fix: a flow resumes inside an action at every yield.
+  load = flow(function* (this: ProjectStore) {
+    this.projects = yield fetchProjects()
+  })
+
+  // Already reported by `store-no-runinaction` at error tier, and the fix is
+  // the same conversion. Reporting it twice would read as two problems, so this
+  // rule stands down when runInAction is present.
+  async loadLegacy(): Promise<void> {
+    const list = await fetchProjects()
+    runInAction(() => {
+      this.projects = list
+    })
+  }
+
+  // Not async.
+  reset(): void {
+    this.projects = []
+  }
+}
+
+// A plain class with no MobX annotation is not a store; async methods on it
+// have no action semantics to lose.
+export class ApiClient {
+  async get(url: string): Promise<Response> {
+    return fetch(url)
+  }
+}
+
+// ── the false-positive class this rule was narrowed to exclude ─────────
+// Private async helpers that do pure I/O and never touch an observable field.
+// There is no action coverage to lose, so there is nothing to convert. Real:
+// SiteCraft's walkDir / collectAllFiles / uploadFile — 10 of the rule's 12
+// hits in that repo before the mutation requirement was added.
+export class ContentStore {
+  files: string[] = []
+
+  constructor() {
+    makeAutoObservable(this)
+  }
+
+  private async walkDir(fs: FileSystem, dir: string, items: Meta[]): Promise<void> {
+    let entries: string[]
+    try {
+      entries = await fs.readdir(dir)
+    } catch {
+      return
+    }
+    for (const e of entries) items.push(await fs.stat(e))
+  }
+
+  private async collectAllFiles(fs: FileSystem, dir: string): Promise<Record<string, string>> {
+    const result: Record<string, string> = {}
+    await this.walkFs(fs, dir, result)
+    return result
+  }
+
+  async uploadFile(targetDir: string, name: string, data: Uint8Array): Promise<string> {
+    const path = `${targetDir}/${name}`
+    await this.fs.writeFile(path, data)
+    return path
+  }
+}

package/rules/__fixtures__/store-context-provider/bad.ts

@@ -0,0 +1,16 @@
+// BAD: the whole context channel D1 removes — provider, hook, null-check.
+import { createContext, useContext } from "react";
+
+type RootStore = { readonly ready: boolean };
+
+export const StoreContext = createContext<RootStore | null>(null);
+
+export const useStore = (): RootStore => {
+  const store = useContext(StoreContext);
+  if (store === null) throw new Error("StoreProvider missing");
+  return store;
+};
+
+export function readReady(): boolean {
+  return useStore().ready;
+}

package/rules/__fixtures__/store-context-provider/bad.tsx

@@ -0,0 +1,24 @@
+// BAD: provider + hook, the shape every store-bearing app in the park still has.
+import { createContext, useContext } from "react";
+
+type RootStore = { readonly ready: boolean };
+
+const StoreContext = createContext<RootStore | null>(null);
+
+export function useStore(): RootStore {
+  const store = useContext(StoreContext);
+  if (store === null) throw new Error("StoreProvider missing");
+  return store;
+}
+
+export function App(props: { readonly store: RootStore }) {
+  return (
+    <StoreContext.Provider value={props.store}>
+      <ReadyBadge />
+    </StoreContext.Provider>
+  );
+}
+
+function ReadyBadge() {
+  return <span>{String(useStore().ready)}</span>;
+}

package/rules/__fixtures__/store-context-provider/good.ts

@@ -0,0 +1,13 @@
+// GOOD: one module-level store, dependencies injected once from the entry file.
+type RootStore = { readonly ready: boolean };
+
+let instance: RootStore | undefined;
+
+export function initRootStore(deps: RootStore): void {
+  instance = deps;
+}
+
+export function getRootStore(): RootStore {
+  if (instance === undefined) throw new Error("initRootStore() has not run yet");
+  return instance;
+}

package/rules/__fixtures__/store-context-provider/good.tsx

@@ -0,0 +1,11 @@
+// GOOD: the screen imports the singleton directly, the row gets a prop.
+import { observer } from "mobx-react-lite";
+import { rootStore } from "./rootStore";
+
+export const AppScreen = observer(function AppScreen() {
+  return <ReadyBadge ready={rootStore.ready} />;
+});
+
+function ReadyBadge(props: { readonly ready: boolean }) {
+  return <span>{String(props.ready)}</span>;
+}

package/rules/__fixtures__/store-delegation-getter/bad.ts

@@ -0,0 +1,30 @@
+// Every getter here MUST be reported by `store-delegation-getter`.
+import { makeAutoObservable } from "mobx"
+
+export class AppStore {
+  constructor(
+    public userStore: UserStore,
+    public connectionStore: ConnectionStore,
+  ) {
+    makeAutoObservable(this)
+  }
+
+  // A second name for someone else's field.
+  get userName(): string {
+    return this.userStore.name
+  }
+
+  get userId(): string {
+    return this.userStore.id
+  }
+
+  // The real shape found in the park (2 sites, metro/byok survey).
+  get isConnected(): boolean {
+    return this.connectionStore.isConnected
+  }
+
+  // Single-expression body, same defect.
+  get retryCount(): number {
+    return this.connectionStore.retries
+  }
+}

package/rules/__fixtures__/store-delegation-getter/bad.tsx

@@ -0,0 +1,30 @@
+// Every getter here MUST be reported by `store-delegation-getter`.
+import { makeAutoObservable } from "mobx"
+
+export class AppStore {
+  constructor(
+    public userStore: UserStore,
+    public connectionStore: ConnectionStore,
+  ) {
+    makeAutoObservable(this)
+  }
+
+  // A second name for someone else's field.
+  get userName(): string {
+    return this.userStore.name
+  }
+
+  get userId(): string {
+    return this.userStore.id
+  }
+
+  // The real shape found in the park (2 sites, metro/byok survey).
+  get isConnected(): boolean {
+    return this.connectionStore.isConnected
+  }
+
+  // Single-expression body, same defect.
+  get retryCount(): number {
+    return this.connectionStore.retries
+  }
+}

package/rules/__fixtures__/store-delegation-getter/good.ts

@@ -0,0 +1,65 @@
+// NOTHING in this file may be reported by `store-delegation-getter`.
+import { makeAutoObservable } from "mobx"
+
+// ── The data-wrapper pattern: 89 of the 91 single-line `return this.X.y`
+// getters measured across byok, metro, SiteCraft and observatory look exactly
+// like this. A model holding a plain record and republishing its fields as
+// observable getters is the sanctioned shape (byok packages/shared/src/models/
+// model.ts, metro apps/web-pmetro/src/stores/domain/station.store.ts).
+export class Model {
+  readonly data: ModelRecordData
+
+  constructor(data: ModelRecordData) {
+    this.data = data
+    makeAutoObservable(this, { data: false })
+  }
+
+  get id(): string {
+    return this.data.id
+  }
+  get slug(): string {
+    return this.data.slug
+  }
+  get name(): string {
+    return this.data.name
+  }
+  get backend(): ModelBackend {
+    return this.data.backend
+  }
+}
+
+export class AppStore {
+  constructor(public userStore: UserStore) {
+    makeAutoObservable(this)
+  }
+
+  // A real derivation — combines, formats, decides. This is what computeds are
+  // for and it is not an alias.
+  get greeting(): string {
+    return `Hello, ${this.userStore.name}!`
+  }
+
+  get hasName(): boolean {
+    return this.userStore.name.length > 0
+  }
+
+  // Computed on the way out, so not a bare forward.
+  get displayName(): string {
+    const raw = this.userStore.name
+    return raw.trim() === "" ? "anonymous" : raw
+  }
+
+  // Reads its OWN field, not another store's.
+  get ready(): boolean {
+    return this.loaded
+  }
+
+  // KNOWN, DELIBERATE MISS. A rootStore reference conventionally named `root`
+  // (WireDrill spells it that way, annotated `{ root: false }`) is a genuine
+  // store-to-store alias that this rule does not catch — the name test keys on
+  // a `Store` suffix, and widening it to `root` starts pulling `this.data`-shaped
+  // names back into scope. Pinned here so the gap stays a decision.
+  get rootUser(): User {
+    return this.root.user
+  }
+}

package/rules/__fixtures__/store-delegation-getter/good.tsx

@@ -0,0 +1,65 @@
+// NOTHING in this file may be reported by `store-delegation-getter`.
+import { makeAutoObservable } from "mobx"
+
+// ── The data-wrapper pattern: 89 of the 91 single-line `return this.X.y`
+// getters measured across byok, metro, SiteCraft and observatory look exactly
+// like this. A model holding a plain record and republishing its fields as
+// observable getters is the sanctioned shape (byok packages/shared/src/models/
+// model.ts, metro apps/web-pmetro/src/stores/domain/station.store.ts).
+export class Model {
+  readonly data: ModelRecordData
+
+  constructor(data: ModelRecordData) {
+    this.data = data
+    makeAutoObservable(this, { data: false })
+  }
+
+  get id(): string {
+    return this.data.id
+  }
+  get slug(): string {
+    return this.data.slug
+  }
+  get name(): string {
+    return this.data.name
+  }
+  get backend(): ModelBackend {
+    return this.data.backend
+  }
+}
+
+export class AppStore {
+  constructor(public userStore: UserStore) {
+    makeAutoObservable(this)
+  }
+
+  // A real derivation — combines, formats, decides. This is what computeds are
+  // for and it is not an alias.
+  get greeting(): string {
+    return `Hello, ${this.userStore.name}!`
+  }
+
+  get hasName(): boolean {
+    return this.userStore.name.length > 0
+  }
+
+  // Computed on the way out, so not a bare forward.
+  get displayName(): string {
+    const raw = this.userStore.name
+    return raw.trim() === "" ? "anonymous" : raw
+  }
+
+  // Reads its OWN field, not another store's.
+  get ready(): boolean {
+    return this.loaded
+  }
+
+  // KNOWN, DELIBERATE MISS. A rootStore reference conventionally named `root`
+  // (WireDrill spells it that way, annotated `{ root: false }`) is a genuine
+  // store-to-store alias that this rule does not catch — the name test keys on
+  // a `Store` suffix, and widening it to `root` starts pulling `this.data`-shaped
+  // names back into scope. Pinned here so the gap stays a decision.
+  get rootUser(): User {
+    return this.root.user
+  }
+}

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

@@ -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 })
+  }
+}