@agentvibes/guardrails 0.1.0 → 0.2.0

package/rules/__fixtures__/kind-if-without-match/good.tsx

@@ -0,0 +1,13 @@
+// NOTHING in this file may be reported by `kind-if-without-match-tsx`.
+import { match } from "ts-pattern"
+
+export const A = (r: R) =>
+  match(r)
+    .with({ kind: "idle" }, () => <Spinner />)
+    .with({ kind: "ready" }, () => <List />)
+    .exhaustive()
+
+export const B = (r: R) => {
+  if (r.count === 0) return <Empty />
+  return <List />
+}

package/rules/__fixtures__/literal-union-in-component/components/bad.tsx

@@ -0,0 +1,16 @@
+// Every type here MUST be reported by `literal-union-in-component-tsx`.
+// Path matters: the rule is scoped to component/screen/app directories.
+//
+// This is the file the rule was named for and never saw. Under
+// `language: typescript` the `**/components/**/*.tsx` glob in the rule could
+// not match anything — the `.tsx` arm makes those glob lines real.
+
+// Enum-style UI state redeclared in the file that renders it.
+export type Tab = "tasks" | "habits" | "stream"
+export type LoadPhase = "idle" | "loading" | "ready" | "error"
+type Align = "start" | "center" | "end"
+export type Tone = "neutral" | "danger" | "success" | "warning"
+
+export const TabBar = ({ tab, align }: { tab: Tab; align: Align }) => (
+  <nav data-align={align}>{tab}</nav>
+)

package/rules/__fixtures__/literal-union-in-component/components/good.tsx

@@ -0,0 +1,25 @@
+// NOTHING in this file may be reported by `literal-union-in-component-tsx`.
+
+// The fix: consume the shared type, do not restate it.
+import type { Tab } from "../../stores/uiStore"
+import type { Tone } from "../../lib/tone"
+
+export interface TabBarProps {
+  tab: Tab
+  tone: Tone
+}
+
+// A single-member alias is not an enum-style union.
+export type Only = "one"
+
+// A union of non-literals is a different thing entirely.
+export type Id = string | number
+export type Handler = (() => void) | undefined
+
+// A discriminated union of OBJECT shapes is the pattern this codebase wants
+// everywhere — it is not a bare string enum and must not be flagged.
+export type Resource<T> =
+  | { status: "idle" }
+  | { status: "ready"; data: T }
+
+export const TabBar = ({ tab, tone }: TabBarProps) => <nav data-tone={tone}>{tab}</nav>

package/rules/__fixtures__/non-exhaustive-match/bad.tsx

@@ -0,0 +1,12 @@
+// Every chain here MUST be reported by `non-exhaustive-match-tsx`.
+// The .ts arm (`non-exhaustive-match`) does NOT see this file: ast-grep's
+// `typescript` and `tsx` languages are disjoint.
+import { match } from "ts-pattern"
+
+export const A = (r: R) => match(r).with({ kind: "idle" }, () => <Spinner />).otherwise(() => null)
+
+export const B = (r: R) =>
+  match(r)
+    .with({ kind: "idle" }, () => <Spinner />)
+    .with({ kind: "ready" }, () => <List />)
+    .otherwise(() => <Empty />)

package/rules/__fixtures__/non-exhaustive-match/good.tsx

@@ -0,0 +1,14 @@
+// NOTHING in this file may be reported by `non-exhaustive-match-tsx`.
+import { match } from "ts-pattern"
+
+export const A = (r: R) =>
+  match(r)
+    .with({ kind: "idle" }, () => <Spinner />)
+    .with({ kind: "ready" }, () => <List />)
+    .exhaustive()
+
+// The false-positive pins carried over from good.ts: the rule anchors to a
+// ts-pattern `match()` chain, so a method merely NAMED `otherwise` is not a
+// finding. A revert to the old bare `$X.otherwise($$$)` body fails here.
+export const q = someBuilder.otherwise(() => 1)
+export const r = config.fallback.otherwise

package/rules/__fixtures__/silent-default-return/bad.ts

@@ -0,0 +1,9 @@
+// Every return here MUST be reported by `silent-default-return`.
+export const a = (x?: T) => { if (!x) return null; return use(x) }
+export const b = (x?: T[]) => { if (!x) return []; return x }
+export const c = (x?: number) => { if (!x) return 0; return x }
+export const d = (x?: string) => { if (!x) return ""; return x }
+export const e = (x?: T) => { if (x === undefined) return null; return use(x) }
+export const f = (x?: T[]) => { if (x === undefined) return []; return x }
+export const g = (x?: T) => { if (x == null) return null; return use(x) }
+export const h = (x?: T[]) => { if (x == null) return []; return x }

package/rules/__fixtures__/silent-default-return/bad.tsx

@@ -0,0 +1,10 @@
+// Every return here MUST be reported by `silent-default-return-tsx`.
+// The .ts arm (`silent-default-return`) does NOT see this file.
+export const A = (x?: T) => { if (!x) return null; return <Use v={x} /> }
+export const b = (x?: T[]) => { if (!x) return []; return x }
+export const c = (x?: number) => { if (!x) return 0; return x }
+export const d = (x?: string) => { if (!x) return ""; return x }
+export const E = (x?: T) => { if (x === undefined) return null; return <Use v={x} /> }
+export const f = (x?: T[]) => { if (x === undefined) return []; return x }
+export const G = (x?: T) => { if (x == null) return null; return <Use v={x} /> }
+export const h = (x?: T[]) => { if (x == null) return []; return x }

package/rules/__fixtures__/silent-default-return/good.ts

@@ -0,0 +1,17 @@
+// NOTHING in this file may be reported by `silent-default-return`.
+export const a = (x?: T) => {
+  if (!x) throw new Error("a(): x is required; caller passed nothing")
+  return use(x)
+}
+
+// An explicit discriminated failure variant is the sanctioned shape.
+export const b = (x?: T) => {
+  if (!x) return { kind: "failure", reason: "missing-x" } as const
+  return { kind: "success", value: use(x) } as const
+}
+
+// The rule is the SILENT default, not every early return.
+export const c = (x?: T) => {
+  if (!x) return fallbackFor(x)
+  return use(x)
+}

package/rules/__fixtures__/silent-default-return/good.tsx

@@ -0,0 +1,11 @@
+// NOTHING in this file may be reported by `silent-default-return-tsx`.
+export const A = (x?: T) => {
+  if (!x) throw new Error("A(): x is required; the caller rendered it with nothing")
+  return <Use v={x} />
+}
+
+// Rendering an explicit empty state is not a silent default.
+export const B = (x?: T) => {
+  if (!x) return <Empty reason="no-x" />
+  return <Use v={x} />
+}

package/rules/demo-mode-by-default-ts.yml

@@ -35,6 +35,12 @@
 # Validated against the real pre-fix store.tsx: 1 hit at the exact declaration,
 # 0 on the fixed version, 0 across substrate-app, tg-gallery webapp and
 # agent-workbench web.
+#
+# 2026-09-06 (is-9e66ec5a): the value matcher was widened to accept
+# `as const` / `as <Type>` / `satisfies <Type>` around the literal. This is an
+# error-tier rule, so the widening was measured before landing: 0 new findings
+# in the seven repos that run this gate, and 0 across every repo under
+# ~/gits/github — the only hits corpus-wide are this package's own fixtures.
 id: demo-mode-by-default-ts
 language: typescript
 severity: error
@@ -52,9 +58,19 @@ rule:
     - has:
         field: key
         regex: '^(kind|mode|backend|source|dataSource|driver|adapter|transport|client)$'
+    # The literal, optionally wrapped in `as const` / `as Mode` /
+    # `satisfies Mode` (is-9e66ec5a). Without the tail, `{ kind: "demo" }` was
+    # a finding and `{ kind: "demo" as const }` was not — and `as const` is the
+    # spelling people reach for precisely when the object has no type
+    # annotation to carry the literal type. DataSpool's retired local
+    # `no-fake-defaults` caught it, so adopting the canon had been a coverage
+    # regression; the reviewer sent both gate PRs back over it.
+    #
+    # The leading and trailing `.` are the quote character, so `"demo-ish"`
+    # still does not match: the alternation must be the WHOLE string body.
     - has:
         field: value
-        regex: '^.(demo|mock|fixture|fake|stub|sample|seed).$'
+        regex: '^.(demo|mock|fixture|fake|stub|sample|seed).( +(as|satisfies) +.+)?$'
     - not:
         inside:
           stopBy: end

package/rules/demo-mode-by-default.yml

@@ -15,6 +15,12 @@
 # Validated against the real pre-fix store.tsx: 1 hit at the exact declaration,
 # 0 on the fixed version, 0 across substrate-app, tg-gallery webapp and
 # agent-workbench web.
+#
+# 2026-09-06 (is-9e66ec5a): the value matcher was widened to accept
+# `as const` / `as <Type>` / `satisfies <Type>` around the literal. This is an
+# error-tier rule, so the widening was measured before landing: 0 new findings
+# in the seven repos that run this gate, and 0 across every repo under
+# ~/gits/github — the only hits corpus-wide are this package's own fixtures.
 id: demo-mode-by-default
 language: tsx
 severity: error
@@ -30,9 +36,19 @@ rule:
     - has:
         field: key
         regex: '^(kind|mode|backend|source|dataSource|driver|adapter|transport|client)$'
+    # The literal, optionally wrapped in `as const` / `as Mode` /
+    # `satisfies Mode` (is-9e66ec5a). Without the tail, `{ kind: "demo" }` was
+    # a finding and `{ kind: "demo" as const }` was not — and `as const` is the
+    # spelling people reach for precisely when the object has no type
+    # annotation to carry the literal type. DataSpool's retired local
+    # `no-fake-defaults` caught it, so adopting the canon had been a coverage
+    # regression; the reviewer sent both gate PRs back over it.
+    #
+    # The leading and trailing `.` are the quote character, so `"demo-ish"`
+    # still does not match: the alternation must be the WHOLE string body.
     - has:
         field: value
-        regex: '^.(demo|mock|fixture|fake|stub|sample|seed).$'
+        regex: '^.(demo|mock|fixture|fake|stub|sample|seed).( +(as|satisfies) +.+)?$'
     - not:
         inside:
           stopBy: end

package/rules/json-roundtrip-tsx.yml

@@ -0,0 +1,26 @@
+# ── the .tsx half of `json-roundtrip` ──
+#
+# ast-grep's `typescript` and `tsx` languages are DISJOINT, not nested: a rule
+# at `language: typescript` matches `.ts` and NEVER `.tsx`. `json-roundtrip`
+# was therefore blind to every React component file. The mechanism, and the
+# three alternatives that were tried and rejected on measurement, are written
+# out once in `catch-empty-tsx.yml`; the short version is that ast-grep has no
+# way to say "both languages", so a twin id per language is the only option.
+#
+# Measured 2026-09-06 across the same five repos: 0 findings. A clean zero,
+# not a broken one — the rule fires on a known positive in its fixture. Closing
+# a language gap at zero cost is the same call `demo-mode-by-default-ts` made.
+#
+# Keep this file's `rule:` block IDENTICAL to `json-roundtrip.yml`.
+#
+id: json-roundtrip-tsx
+language: tsx
+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.
+  Suppressing this one needs the id you see above — `ast-grep-ignore: json-roundtrip-tsx`.
+  `json-roundtrip` is a DIFFERENT rule (the .ts arm) and does not cover it.
+rule:
+  pattern: "JSON.parse(JSON.stringify($X))"

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

@@ -0,0 +1,31 @@
+# ── the .tsx half of `kind-if-without-match` ──
+#
+# ast-grep's `typescript` and `tsx` languages are DISJOINT, not nested: a rule
+# at `language: typescript` matches `.ts` and NEVER `.tsx`. `kind-if-without-match`
+# was therefore blind to every React component file. The mechanism, and the
+# three alternatives that were tried and rejected on measurement, are written
+# out once in `catch-empty-tsx.yml`; the short version is that ast-grep has no
+# way to say "both languages", so a twin id per language is the only option.
+#
+# Measured 2026-09-06 across the same five repos: 29 findings in `.tsx`
+# (SiteCraft 1, faceless 2, observatory 6, tg-gallery 2, merkle-substrate 18).
+# `if (x.kind === …)` branching lives in components at least as often as in
+# plain modules, which is precisely where the union grows a variant unnoticed.
+#
+# Keep this file's `rule:` block IDENTICAL to `kind-if-without-match.yml`.
+#
+id: kind-if-without-match-tsx
+language: tsx
+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.
+  Suppressing this one needs the id you see above — `ast-grep-ignore: kind-if-without-match-tsx`.
+  `kind-if-without-match` is a DIFFERENT rule (the .ts arm) and does not cover it.
+rule:
+  any:
+    - pattern: "if ($X.kind === $_) $_"
+    - pattern: "if ($X.type === $_) $_"
+    - pattern: "if ($X.status === $_) $_"
+    - pattern: "if ($X._obj === $_) $_"

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

@@ -0,0 +1,81 @@
+# ── the .tsx half of `literal-union-in-component` ──
+#
+# ast-grep's `typescript` and `tsx` languages are DISJOINT, not nested: a rule
+# at `language: typescript` matches `.ts` and NEVER `.tsx`. `literal-union-in-component`
+# was therefore blind to every React component file. The mechanism, and the
+# three alternatives that were tried and rejected on measurement, are written
+# out once in `catch-empty-tsx.yml`; the short version is that ast-grep has no
+# way to say "both languages", so a twin id per language is the only option.
+#
+# Measured 2026-09-06 across the same five repos: 41 findings in `.tsx`
+# (SiteCraft 1, faceless 7, observatory 9, tg-gallery 6, merkle-substrate 18).
+# This twin restores intent rather than extending it: the `files:` globs below
+# already list `**/components/**/*.tsx` and `**/screens/**/*.tsx`, and under
+# `language: typescript` those three lines could never match anything. The rule
+# is named `-in-component` and was blind to components.
+#
+# Keep this file's `rule:` block IDENTICAL to `literal-union-in-component.yml`.
+#
+id: literal-union-in-component-tsx
+language: tsx
+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.
+  Suppressing this one needs the id you see above — `ast-grep-ignore: literal-union-in-component-tsx`.
+  `literal-union-in-component` is a DIFFERENT rule (the .ts arm) and does not cover it.
+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/no-local-kit-clone-tsx.yml

@@ -34,7 +34,23 @@
 # `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.
+# CARVE-OUT 1 IS NOW A REPO DECLARATION, not only a glob (is-086a90ac).
+# `@agentvibes/kit` exists since 2026-09 and lives in its own repo, where verify
+# sees its files as `src/resource/resource.ts` — neither `**/packages/kit/**`
+# nor `**/agentvibes-kit/**` matches that, and no path glob can tell that tree
+# from any other repo's `src/`. So the kit repo says so itself:
+#
+#   [verify]
+#   kit_source = "^src/"
+#
+# together with the `appliesTo: not-kit-source` marker below. Same mechanism
+# `[verify] screens` uses (is-7067a0b8): the repo states a fact about itself,
+# the canon says which rules stand down for it. The globs stay for monorepos
+# that vendor the kit under `packages/kit/`.
+#
 id: no-local-kit-clone-tsx
+metadata:
+  appliesTo: not-kit-source
 language: tsx
 severity: error
 ignores:

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

@@ -23,7 +23,23 @@
 # `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.
+# CARVE-OUT 1 IS NOW A REPO DECLARATION, not only a glob (is-086a90ac).
+# `@agentvibes/kit` exists since 2026-09 and lives in its own repo, where verify
+# sees its files as `src/resource/resource.ts` — neither `**/packages/kit/**`
+# nor `**/agentvibes-kit/**` matches that, and no path glob can tell that tree
+# from any other repo's `src/`. So the kit repo says so itself:
+#
+#   [verify]
+#   kit_source = "^src/"
+#
+# together with the `appliesTo: not-kit-source` marker below. Same mechanism
+# `[verify] screens` uses (is-7067a0b8): the repo states a fact about itself,
+# the canon says which rules stand down for it. The globs stay for monorepos
+# that vendor the kit under `packages/kit/`.
+#
 id: no-local-kit-clone
+metadata:
+  appliesTo: not-kit-source
 language: typescript
 severity: error
 ignores:

package/rules/non-exhaustive-match-tsx.yml

@@ -0,0 +1,48 @@
+# ── the .tsx half of `non-exhaustive-match` ──
+#
+# ast-grep's `typescript` and `tsx` languages are DISJOINT, not nested: a rule
+# at `language: typescript` matches `.ts` and NEVER `.tsx`. `non-exhaustive-match`
+# was therefore blind to every React component file. The mechanism, and the
+# three alternatives that were tried and rejected on measurement, are written
+# out once in `catch-empty-tsx.yml`; the short version is that ast-grep has no
+# way to say "both languages", so a twin id per language is the only option.
+#
+# Measured 2026-09-06 across the five repos that consume guardrails
+# (SiteCraftMonorepo 40, faceless-photo-lib 28, agent-session-observatory 18,
+# tg-gallery 47, merkle-substrate 52): 185 `.otherwise()` chains in `.tsx` the
+# `.ts` arm never saw. Adding them was the owner's call — decision D4 in
+# doc-e4526f1a parks the question of banning `.otherwise()` outright, so the
+# owner was asked whether to surface the .tsx half before D4 lands and answered
+# «1» (add the twin now, severity warning) on 2026-09-06, is-8385d5dd.
+#
+# Keep this file's `rule:` block IDENTICAL to `non-exhaustive-match.yml`.
+#
+id: non-exhaustive-match-tsx
+language: tsx
+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.
+  Suppressing this one needs the id you see above — `ast-grep-ignore: non-exhaustive-match-tsx`.
+  `non-exhaustive-match` is a DIFFERENT rule (the .ts arm) and does not cover it.
+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/silent-default-return-tsx.yml

@@ -0,0 +1,33 @@
+# ── the .tsx half of `silent-default-return` ──
+#
+# ast-grep's `typescript` and `tsx` languages are DISJOINT, not nested: a rule
+# at `language: typescript` matches `.ts` and NEVER `.tsx`. `silent-default-return`
+# was therefore blind to every React component file. The mechanism, and the
+# three alternatives that were tried and rejected on measurement, are written
+# out once in `catch-empty-tsx.yml`; the short version is that ast-grep has no
+# way to say "both languages", so a twin id per language is the only option.
+#
+# Measured 2026-09-06 across the same five repos: 24 findings in `.tsx`
+# (SiteCraft 3, faceless 0, observatory 9, tg-gallery 0, merkle-substrate 12).
+#
+# Keep this file's `rule:` block IDENTICAL to `silent-default-return.yml`.
+#
+id: silent-default-return-tsx
+language: tsx
+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.
+  Suppressing this one needs the id you see above — `ast-grep-ignore: silent-default-return-tsx`.
+  `silent-default-return` is a DIFFERENT rule (the .ts arm) and does not cover it.
+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 []"