@pyreon/lint 0.12.12 → 0.12.14

package/src/tests/runner.test.ts

@@ -4,7 +4,7 @@ import { loadConfig } from '../config/loader'
 import { getPreset } from '../config/presets'
 import { allRules } from '../rules/index'
 import { applyFixes, lintFile } from '../runner'
-import type { LintConfig, Rule } from '../types'
+import type { ConfigDiagnostic, LintConfig, Rule } from '../types'
 import { LineIndex } from '../utils/source'
 
 // Helper to create a config that enables all rules at default severity
@@ -12,6 +12,23 @@ function defaultConfig(): LintConfig {
   return getPreset('recommended')
 }
 
+/** Build a config where one rule is configured with `exemptPaths` options. */
+function configWithExemptPaths(ruleId: string, paths: string[]): LintConfig {
+  const base = getPreset('recommended')
+  const existing = base.rules[ruleId]
+  const severity = Array.isArray(existing) ? existing[0] : existing
+  if (severity === undefined || severity === 'off') {
+    throw new Error(`configWithExemptPaths: rule ${ruleId} is off in recommended preset`)
+  }
+  return {
+    ...base,
+    rules: {
+      ...base.rules,
+      [ruleId]: [severity, { exemptPaths: paths }] as const,
+    },
+  }
+}
+
 // Helper to lint a string with specific rules
 function lintSource(
   source: string,
@@ -36,8 +53,8 @@ function lintWith(ruleId: string, source: string, filePath?: string) {
 // ── Rule Metadata ───────────────────────────────────────────────────────────
 
 describe('Rule metadata', () => {
-  it('should have 58 rules', () => {
-    expect(allRules.length).toBe(58)
+  it('should have 59 rules', () => {
+    expect(allRules.length).toBe(59)
   })
 
   it('should have unique rule IDs', () => {
@@ -82,7 +99,7 @@ describe('Rule metadata', () => {
     expect(counts.lifecycle).toBe(4)
     expect(counts.performance).toBe(4)
     expect(counts.ssr).toBe(3)
-    expect(counts.architecture).toBe(6)
+    expect(counts.architecture).toBe(7)
     expect(counts.store).toBe(3)
     expect(counts.form).toBe(3)
     expect(counts.styling).toBe(4)
@@ -563,6 +580,30 @@ describe('SSR rules', () => {
     expect(diags.length).toBe(0)
   })
 
+  it('pyreon/no-window-in-ssr: exempt via configured exemptPaths', () => {
+    const source = `const w = window.innerWidth; document.createElement('div')`
+    const cfg = configWithExemptPaths('pyreon/no-window-in-ssr', [
+      'packages/core/runtime-dom/',
+    ])
+    const result = lintFile('packages/core/runtime-dom/src/foo.ts', source, allRules, cfg)
+    const diags = findByRule(result, 'pyreon/no-window-in-ssr')
+    expect(diags.length).toBe(0)
+  })
+
+  it('pyreon/no-window-in-ssr: fires in same path when exemptPaths is not configured', () => {
+    const source = `const w = window.innerWidth`
+    const result = lintFile(
+      'packages/core/runtime-dom/src/foo.ts',
+      source,
+      allRules,
+      defaultConfig(),
+    )
+    const diags = findByRule(result, 'pyreon/no-window-in-ssr')
+    // With no exemptPaths configured, the rule applies everywhere —
+    // this is the correct default for a rule shipping to user apps.
+    expect(diags.length).toBeGreaterThanOrEqual(1)
+  })
+
   it('pyreon/no-mismatch-risk: flags Date.now() in JSX', () => {
     const source = `const App = () => <div>{Date.now()}</div>`
     const result = lintSource(source)
@@ -616,6 +657,75 @@ describe('Architecture rules', () => {
     expect(diags.length).toBe(0)
   })
 
+  it('pyreon/dev-guard-warnings: clean inside `if (__DEV__ && X)` compound guard', () => {
+    const source = `if (__DEV__ && cond) { console.warn("x") }`
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/dev-guard-warnings')
+    expect(diags.length).toBe(0)
+  })
+
+  it('pyreon/dev-guard-warnings: clean inside `if (X && __DEV__)` compound guard', () => {
+    const source = `if (cond && __DEV__) { console.warn("x") }`
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/dev-guard-warnings')
+    expect(diags.length).toBe(0)
+  })
+
+  it('pyreon/dev-guard-warnings: clean inside `__DEV__ && console.warn(...)` short-circuit', () => {
+    const source = `__DEV__ && console.warn("x")`
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/dev-guard-warnings')
+    expect(diags.length).toBe(0)
+  })
+
+  it('pyreon/dev-guard-warnings: clean inside `__DEV__ ? warn : null` ternary', () => {
+    const source = `__DEV__ ? console.warn("x") : null`
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/dev-guard-warnings')
+    expect(diags.length).toBe(0)
+  })
+
+  it('pyreon/dev-guard-warnings: exempts console.error inside catch (production error reporting)', () => {
+    const source = `try { foo() } catch (err) { console.error("[Pyreon]", err) }`
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/dev-guard-warnings')
+    expect(diags.length).toBe(0)
+  })
+
+  it('pyreon/dev-guard-warnings: still flags console.warn inside catch (warns must be DEV-only)', () => {
+    const source = `try { foo() } catch (err) { console.warn("[Pyreon]", err) }`
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/dev-guard-warnings')
+    expect(diags.length).toBe(1)
+  })
+
+  it('pyreon/dev-guard-warnings: clean inside `if (import.meta.env.DEV)` guard', () => {
+    const source = `if (import.meta.env.DEV) { console.warn("x") }`
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/dev-guard-warnings')
+    expect(diags.length).toBe(0)
+  })
+
+  it('pyreon/dev-guard-warnings: clean after early-return DEV guard at top of function', () => {
+    const source = `function warn() {
+      if (!__DEV__) return
+      console.warn("a"); console.warn("b"); console.warn("c")
+    }`
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/dev-guard-warnings')
+    expect(diags.length).toBe(0)
+  })
+
+  it('pyreon/dev-guard-warnings: clean after early-return `import.meta.env.DEV` guard', () => {
+    const source = `function warn() {
+      if (!import.meta.env?.DEV) return
+      console.warn("x")
+    }`
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/dev-guard-warnings')
+    expect(diags.length).toBe(0)
+  })
+
   // ── pyreon/no-process-dev-gate ────────────────────────────────────────────
   // The recurring browser-dead-code bug we fixed in PR #200. Tests cover:
   //   - the canonical broken pattern (typeof process first, NODE_ENV second)
@@ -678,27 +788,29 @@ describe('Architecture rules', () => {
     expect(diags.length).toBe(0)
   })
 
-  it('pyreon/no-process-dev-gate: exempts server-only packages (Node always has process)', () => {
+  it('pyreon/no-process-dev-gate: exempt via configured exemptPaths (server-only code)', () => {
     const source = `const __DEV__ = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'`
-    // packages/core/server/ is the SSR adapter — runs in Node, the pattern is correct there.
-    const result = lintFile(
-      'packages/core/server/src/handler.ts',
-      source,
-      allRules,
-      defaultConfig(),
-    )
+    const cfg = configWithExemptPaths('pyreon/no-process-dev-gate', [
+      'packages/core/server/',
+    ])
+    const result = lintFile('packages/core/server/src/handler.ts', source, allRules, cfg)
     const diags = findByRule(result, 'pyreon/no-process-dev-gate')
     expect(diags.length).toBe(0)
   })
 
-  it('pyreon/no-process-dev-gate: exempts runtime-server, zero, vite-plugin', () => {
+  it('pyreon/no-process-dev-gate: exemptPaths covers multiple directories', () => {
     const source = `const __DEV__ = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'`
+    const cfg = configWithExemptPaths('pyreon/no-process-dev-gate', [
+      'packages/core/runtime-server/',
+      'packages/zero/',
+      'packages/tools/vite-plugin/',
+    ])
     for (const path of [
       'packages/core/runtime-server/src/index.ts',
       'packages/zero/zero/src/logger.ts',
       'packages/tools/vite-plugin/src/index.ts',
     ]) {
-      const result = lintFile(path, source, allRules, defaultConfig())
+      const result = lintFile(path, source, allRules, cfg)
       const diags = findByRule(result, 'pyreon/no-process-dev-gate')
       expect(diags.length, `expected ${path} to be exempt`).toBe(0)
     }
@@ -915,8 +1027,11 @@ defineStore("user", () => {})
     expect(diags.length).toBe(0)
   })
 
-  it('pyreon/no-mutate-store-state: flags store.signal.set()', () => {
-    const result = lintWith('pyreon/no-mutate-store-state', `userStore.count.set(5)`)
+  it('pyreon/no-mutate-store-state: flags store.signal.set() inside a component', () => {
+    const result = lintWith(
+      'pyreon/no-mutate-store-state',
+      `function MyComp() { userStore.count.set(5) }`,
+    )
     expect(result.diagnostics.length).toBe(1)
   })
 
@@ -1059,15 +1174,47 @@ describe('Hooks rules', () => {
     expect(diags.length).toBe(1)
   })
 
-  it('pyreon/no-raw-setinterval: flags setInterval outside onMount', () => {
-    const source = `setInterval(() => {}, 1000)`
+  it('pyreon/no-raw-addeventlistener: exempt via configured exemptPaths', () => {
+    const source = `el.addEventListener("click", handler)`
+    const cfg = configWithExemptPaths('pyreon/no-raw-addeventlistener', [
+      'packages/core/runtime-dom/',
+      'packages/fundamentals/hooks/',
+    ])
+    for (const path of [
+      'packages/core/runtime-dom/src/delegate.ts',
+      'packages/fundamentals/hooks/src/useClickOutside.ts',
+    ]) {
+      const result = lintFile(path, source, allRules, cfg)
+      const diags = findByRule(result, 'pyreon/no-raw-addeventlistener')
+      expect(diags.length, `expected ${path} to be exempt`).toBe(0)
+    }
+  })
+
+  it('pyreon/no-raw-setinterval: flags setInterval inside a component (outside onMount)', () => {
+    const source = `function MyComp() { setInterval(() => {}, 1000) }`
     const result = lintSource(source)
     const diags = findByRule(result, 'pyreon/no-raw-setinterval')
     expect(diags.length).toBe(1)
   })
 
-  it('pyreon/no-raw-localstorage: flags localStorage.getItem()', () => {
-    const source = `const v = localStorage.getItem("key")`
+  it('pyreon/no-raw-setinterval: exempt via configured exemptPaths', () => {
+    // Wrap in a component so component-context fires; exemptPaths then overrides.
+    const source = `function useInterval() { setInterval(() => callback(), d) }`
+    const cfg = configWithExemptPaths('pyreon/no-raw-setinterval', [
+      'packages/fundamentals/hooks/',
+    ])
+    const result = lintFile(
+      'packages/fundamentals/hooks/src/useInterval.ts',
+      source,
+      allRules,
+      cfg,
+    )
+    const diags = findByRule(result, 'pyreon/no-raw-setinterval')
+    expect(diags.length).toBe(0)
+  })
+
+  it('pyreon/no-raw-localstorage: flags localStorage.getItem() inside a component', () => {
+    const source = `function MyComp() { const v = localStorage.getItem("key") }`
     const result = lintSource(source)
     const diags = findByRule(result, 'pyreon/no-raw-localstorage')
     expect(diags.length).toBe(1)
@@ -1273,7 +1420,7 @@ describe('Ignore filter', () => {
 describe('Presets', () => {
   it('recommended should include all rules', () => {
     const config = getPreset('recommended')
-    expect(Object.keys(config.rules).length).toBe(58)
+    expect(Object.keys(config.rules).length).toBe(59)
   })
 
   it('strict should promote all warns to errors', () => {
@@ -1310,3 +1457,1408 @@ describe('Presets', () => {
     expect(lib.rules['pyreon/no-process-dev-gate']).toBe('error')
   })
 })
+
+// ── Component-context detection (B-rules) ──────────────────────────────────
+//
+// Four rules only matter inside a component or hook setup body. They no
+// longer rely on `isTestFile` path heuristics — the
+// `createComponentContextTracker()` utility detects the semantic context
+// directly. Module-level + utility-function callsites are exempt by design;
+// test callbacks (anonymous arrows passed to `it()`) are exempt because
+// they aren't named like a component or hook.
+
+describe('component-context exemption (rules that only fire inside components/hooks)', () => {
+  const cases: Array<[string, string]> = [
+    ['pyreon/no-raw-setinterval', `setInterval(() => {}, 100)`],
+    ['pyreon/no-dynamic-styled', `function helper() { styled('div')\`color:red\` }`],
+    ['pyreon/no-raw-localstorage', `localStorage.getItem('k')`],
+    ['pyreon/no-mutate-store-state', `store.count.set(5)`],
+  ]
+
+  for (const [rule, source] of cases) {
+    it(`${rule}: silent at module scope (no component on the stack)`, () => {
+      const result = lintSource(source)
+      const diags = findByRule(result, rule)
+      expect(diags.length).toBe(0)
+    })
+
+    it(`${rule}: silent in plain utility function (PascalCase / use-prefix not present)`, () => {
+      const wrapped = `function doStuff() { ${source} }`
+      const result = lintSource(wrapped)
+      const diags = findByRule(result, rule)
+      expect(diags.length).toBe(0)
+    })
+
+    it(`${rule}: silent in a test callback (anonymous arrow)`, () => {
+      const wrapped = `it('does the thing', () => { ${source} })`
+      const result = lintSource(wrapped)
+      const diags = findByRule(result, rule)
+      expect(diags.length).toBe(0)
+    })
+
+    it(`${rule}: fires inside a PascalCase component`, () => {
+      const wrapped = `function MyComp() { ${source} }`
+      const result = lintSource(wrapped)
+      const diags = findByRule(result, rule)
+      expect(diags.length).toBeGreaterThanOrEqual(1)
+    })
+
+    it(`${rule}: fires inside a use-prefixed hook`, () => {
+      const wrapped = `function useThing() { ${source} }`
+      const result = lintSource(wrapped)
+      const diags = findByRule(result, rule)
+      expect(diags.length).toBeGreaterThanOrEqual(1)
+    })
+
+    it(`${rule}: fires inside an arrow-form component (\`const MyComp = () => …\`)`, () => {
+      const wrapped = `const MyComp = () => { ${source} }`
+      const result = lintSource(wrapped)
+      const diags = findByRule(result, rule)
+      expect(diags.length).toBeGreaterThanOrEqual(1)
+    })
+
+    it(`${rule}: fires inside an arrow-form hook (\`const useFoo = () => …\`)`, () => {
+      const wrapped = `const useFoo = () => { ${source} }`
+      const result = lintSource(wrapped)
+      const diags = findByRule(result, rule)
+      expect(diags.length).toBeGreaterThanOrEqual(1)
+    })
+  }
+})
+
+// Arrow-form hook implementations are now correctly detected by
+// `no-theme-outside-provider` (fixes a silent bug where the rule ignored
+// the most common React/Solid hook idiom).
+describe('no-theme-outside-provider: arrow-form hook implementation', () => {
+  it('silent inside `const useFoo = (...) => { useTheme() }` (hook delegates provider to caller)', () => {
+    const source = `
+      import { useTheme } from '@pyreon/styler'
+      export const useThemeValue = (path) => {
+        const theme = useTheme()
+        return theme?.[path]
+      }
+    `
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/no-theme-outside-provider')
+    expect(diags.length).toBe(0)
+  })
+
+  it('still fires inside a non-hook arrow function calling useTheme', () => {
+    const source = `
+      import { useTheme } from '@pyreon/styler'
+      export const getColor = () => useTheme()?.colors?.primary
+    `
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/no-theme-outside-provider')
+    expect(diags.length).toBeGreaterThanOrEqual(1)
+  })
+})
+
+// `no-window-in-ssr` recognizes the const-captured typeof guard idiom:
+// `const isBrowser = typeof window !== 'undefined'; if (isBrowser) { window.X }`.
+describe('no-window-in-ssr: const-captured typeof guard', () => {
+  it('silent under `if (isBrowser)` after `const isBrowser = typeof window !== "undefined"`', () => {
+    const source = `
+      const isBrowser = typeof window !== 'undefined'
+      if (isBrowser) {
+        window.addEventListener('online', () => {})
+      }
+    `
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/no-window-in-ssr')
+    expect(diags.length).toBe(0)
+  })
+
+  it('still fires when the const is not a typeof check', () => {
+    const source = `
+      const isBrowser = true
+      if (isBrowser) {
+        window.addEventListener('online', () => {})
+      }
+    `
+    const result = lintSource(source)
+    const diags = findByRule(result, 'pyreon/no-window-in-ssr')
+    expect(diags.length).toBeGreaterThanOrEqual(1)
+  })
+})
+
+// `no-window-in-ssr` precision improvements introduced alongside the hooks
+// anti-pattern cleanup. Each block targets one of the silent-false-positive
+// sources previously caused by oxc's visitor not passing `parent`.
+describe('no-window-in-ssr: precision (oxc no-parent fixes)', () => {
+  it('silent when `typeof X` is the expression itself (the mention of X is not a global ref)', () => {
+    const source = `const t = typeof window`
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent for member-expression property names (x.addEventListener)', () => {
+    const source = `function f(x) { x.addEventListener('click', () => {}) }`
+    const result = lintSource(source)
+    // `addEventListener` is a property name, not a global — must not fire.
+    // (`x` is also not a browser global.)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent for object-property keys ({ document: 1 })', () => {
+    const source = `const o = { document: 1, window: 2 }`
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent for import-specifier names', () => {
+    const source = `import { window as w } from './foo'`
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent for TS type-position identifiers (let x: Window)', () => {
+    const source = `let x: Window | null = null`
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent under early-return-on-typeof guard', () => {
+    const source = `
+      function load() {
+        if (typeof window === 'undefined') return
+        window.addEventListener('online', () => {})
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent under OR-chained early-return-on-typeof guard', () => {
+    const source = `
+      function load() {
+        if (typeof window === 'undefined' || typeof IntersectionObserver === 'undefined') return
+        const o = new IntersectionObserver(() => {})
+        window.addEventListener('online', () => {})
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent inside onUnmount / onCleanup / renderEffect', () => {
+    const source = `
+      onUnmount(() => { window.removeEventListener('x', () => {}) })
+      onCleanup(() => { document.body.style.overflow = '' })
+      renderEffect(() => { const w = window.innerWidth })
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent in ternary consequent of typeof check', () => {
+    const source = `const w = typeof window !== 'undefined' ? window.innerWidth : 0`
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('still fires for the negated form body (safety check on testIsTypeofGuard split)', () => {
+    // `if (typeof window === 'undefined') { window.X }` — the body is the
+    // SSR-fallback branch, NOT a browser-safe zone. Must fire.
+    const source = `
+      if (typeof window === 'undefined') {
+        const w = window.innerWidth
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBeGreaterThanOrEqual(1)
+  })
+})
+
+// Additional precision: `IS_BROWSER && active()` as ternary/if test — the
+// LogicalAnd short-circuits so the body only runs when the typeof-derived
+// const is truthy. Common pattern in Portal/Overlay conditional rendering.
+describe('no-window-in-ssr: logical-and guards with typeof-derived const', () => {
+  it('silent under `IS_BROWSER && cond()` ternary test', () => {
+    const source = `
+      const IS_BROWSER = typeof window !== 'undefined'
+      const vnode = IS_BROWSER && cond() ? document.body : null
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent under `cond() && IS_BROWSER` ternary test (either side)', () => {
+    const source = `
+      const IS_BROWSER = typeof window !== 'undefined'
+      const vnode = cond() && IS_BROWSER ? document.body : null
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('fires when neither side is a typeof guard', () => {
+    const source = `
+      const vnode = flag && cond() ? document.body : null
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBeGreaterThanOrEqual(1)
+  })
+})
+
+// The `render` VNode-producing helper from `@pyreon/ui-core` takes a
+// ComponentFn/string/VNode and returns a VNodeChild — its call sites in JSX
+// always produce a VNode, not a signal value. Exempted from the bare-signal
+// heuristic.
+describe('no-bare-signal-in-jsx: render() helper exemption', () => {
+  it('silent for render(content, props) in JSX text', () => {
+    const source = `const App = () => <div>{render(own.trigger, { active: true })}</div>`
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-bare-signal-in-jsx').length).toBe(0)
+  })
+
+  it('still fires for other bare identifiers in JSX text', () => {
+    const source = `const App = () => <div>{count()}</div>`
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-bare-signal-in-jsx').length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('silent for h() hyperscript in JSX text (VNode-producing helper)', () => {
+    const source = `const App = () => <Show>{h('span', null, 'y')}</Show>`
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-bare-signal-in-jsx').length).toBe(0)
+  })
+
+  it('silent for cloneVNode() in JSX text (VNode-producing helper)', () => {
+    const source = `const App = (props) => <Show>{cloneVNode(props.children, { ref: r })}</Show>`
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-bare-signal-in-jsx').length).toBe(0)
+  })
+})
+
+// `no-window-in-ssr` — `watch()` from @pyreon/reactivity and
+// `requestAnimationFrame` are safe contexts: their callbacks only fire
+// after initial setup / inside a browser frame. watch is handled
+// precisely: only the 2nd arg (callback) is safe, the 1st (source) is
+// evaluated at setup and stays under normal analysis.
+describe('no-window-in-ssr: watch() and requestAnimationFrame safe contexts', () => {
+  it('silent in the callback arg of watch(source, callback)', () => {
+    const source = `
+      watch(() => stage(), (s) => {
+        cancelAnimationFrame(frameId)
+      })
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('FIRES for browser globals in the SOURCE arg of watch (setup-time)', () => {
+    // The source arg runs at setup to track signals — browser globals there
+    // would break SSR. Only the 2nd-arg callback is deferred.
+    const source = `
+      watch(() => window.innerWidth, (w) => {})
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('silent inside requestAnimationFrame callback', () => {
+    const source = `
+      requestAnimationFrame(() => {
+        const w = window.innerWidth
+      })
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+})
+
+// `no-window-in-ssr` — parameter-shadowing and typeof-derived const via
+// logical-and chains. Driven by false-positives surfaced in @pyreon/router.
+describe('no-window-in-ssr: parameter shadowing + typeof-derived AND chains', () => {
+  it('silent when a function parameter named `location` shadows the global', () => {
+    const source = `
+      function push(location) {
+        if (typeof location === 'string') return location.toUpperCase()
+        return JSON.stringify(location)
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('still fires when the global is used in a sibling scope without shadowing', () => {
+    const source = `
+      function push(location) { return location }
+      const hostname = window.location.hostname
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('silent under `if (useVT)` when useVT binds from `_isBrowser && ... && typeof X === "function"`', () => {
+    const source = `
+      const _isBrowser = typeof window !== 'undefined'
+      const useVT = _isBrowser && meta && typeof document.startViewTransition === 'function'
+      if (useVT) {
+        document.startViewTransition(() => {})
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent for destructured parameter named `location`', () => {
+    const source = `
+      function route({ location, path }) { return location + path }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent when a browser-global name is shadowed by a top-level import binding', () => {
+    // `import { history } from '@codemirror/commands'` — every later
+    // `history` identifier in the file is the import, not `window.history`.
+    const source = `
+      import { history } from '@codemirror/commands'
+      const ext = history()
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent for default-import binding shadowing a browser global', () => {
+    const source = `
+      import history from '@codemirror/commands'
+      const ext = history()
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent for namespace-import binding shadowing a browser global', () => {
+    const source = `
+      import * as location from './location-utils'
+      const x = location()
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent under `if (handler)` when handler is bound via `_isBrowser ? fn : null`', () => {
+    // Ternary-derived bindings: `handler` is only non-null when the guard
+    // was truthy, so `if (handler)` implicitly asserts the guard held.
+    const source = `
+      const _isBrowser = typeof window !== 'undefined'
+      const handler = _isBrowser ? (e) => e.preventDefault() : null
+      if (handler) {
+        window.addEventListener('beforeunload', handler)
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent under `if (h)` when h is bound via `_isBrowser && mode === X ? fn : null`', () => {
+    const source = `
+      const _isBrowser = typeof window !== 'undefined'
+      const h = _isBrowser && mode === 'history' ? () => {} : null
+      if (h) { window.addEventListener('popstate', h) }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+})
+
+// Inline suppression — both the long-form and short-form syntaxes are accepted.
+describe('inline suppression comments', () => {
+  it('suppresses next-line diagnostic via `// pyreon-lint-ignore <rule-id>`', () => {
+    const source = [
+      'const x = signal(0)',
+      '// pyreon-lint-ignore pyreon/no-peek-in-tracked',
+      'const c = computed(() => x.peek())',
+    ].join('\n')
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-peek-in-tracked').length).toBe(0)
+  })
+
+  it('suppresses next-line diagnostic via `// pyreon-lint-disable-next-line <rule-id>` (alias)', () => {
+    const source = [
+      'const x = signal(0)',
+      '// pyreon-lint-disable-next-line pyreon/no-peek-in-tracked',
+      'const c = computed(() => x.peek())',
+    ].join('\n')
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-peek-in-tracked').length).toBe(0)
+  })
+
+  it('still fires when the suppression comment names a different rule', () => {
+    const source = [
+      'const x = signal(0)',
+      '// pyreon-lint-disable-next-line pyreon/no-window-in-ssr',
+      'const c = computed(() => x.peek())',
+    ].join('\n')
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-peek-in-tracked').length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('bare suppression (no rule id) suppresses ALL diagnostics on the next line', () => {
+    const source = [
+      'const x = signal(0)',
+      '// pyreon-lint-disable-next-line',
+      'const c = computed(() => x.peek())',
+    ].join('\n')
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-peek-in-tracked').length).toBe(0)
+  })
+
+  it('does NOT match typoed variants like `// pyreon-lint-ignored` (word-boundary)', () => {
+    const source = [
+      'const x = signal(0)',
+      '// pyreon-lint-ignored pyreon/no-peek-in-tracked',
+      'const c = computed(() => x.peek())',
+    ].join('\n')
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-peek-in-tracked').length).toBeGreaterThanOrEqual(1)
+  })
+})
+
+// Early-return guards with `throw` (not just `return`) — common in entry-point
+// functions like `startClient` that hard-fail in SSR rather than silently
+// no-op. Both `no-window-in-ssr` and `no-dom-in-setup` recognise the form.
+describe('early-return guards: throw terminator', () => {
+  it('no-window-in-ssr silent under `if (typeof X === "undefined") throw …` early-return', () => {
+    const source = `
+      function startClient() {
+        if (typeof document === 'undefined') throw new Error('browser only')
+        const el = document.body
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('no-dom-in-setup silent under `if (typeof document === "undefined") return` at function head', () => {
+    const source = `
+      function loadScript() {
+        if (typeof document === 'undefined') return
+        const x = document.getElementById('app')
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-dom-in-setup').length).toBe(0)
+  })
+
+  it('no-dom-in-setup silent under `if (typeof window === "undefined") throw …` early-return', () => {
+    const source = `
+      function init() {
+        if (typeof window === 'undefined') throw new Error('browser only')
+        const x = document.querySelector('#app')
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-dom-in-setup').length).toBe(0)
+  })
+
+  it('no-dom-in-setup still fires without an early-return guard', () => {
+    const source = `
+      function init() {
+        const x = document.querySelector('#app')
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-dom-in-setup').length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('no-window-in-ssr does NOT fire on `fetch` (universal in Node 18+/Bun/Deno/browsers/edge)', () => {
+    const source = `
+      async function loadJson(url) {
+        const res = await fetch(url)
+        return res.json()
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+})
+
+// Typeof-guard functions — `function isBrowser() { return typeof window !==
+// 'undefined' }` is structurally a typeof check at its call sites. Common
+// pattern in storage adapters and SSR-aware utilities. Conventional names
+// (`isBrowser`/`isClient`/`isServer`/`isSSR`) are pre-seeded so cross-module
+// imports work without follow-the-import analysis.
+describe('no-window-in-ssr: typeof-guard functions', () => {
+  it('silent under `if (!isBrowser()) return` early-return (locally-defined)', () => {
+    const source = `
+      function isBrowser() { return typeof window !== 'undefined' }
+      function getStorage() {
+        if (!isBrowser()) return null
+        return window.localStorage
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent under `if (isBrowser())` positive guard (arrow form)', () => {
+    const source = `
+      const isBrowser = () => typeof window !== 'undefined'
+      function attach() {
+        if (isBrowser()) {
+          window.addEventListener('storage', () => {})
+        }
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent under `!isBrowser()` even when imported (name-based fallback)', () => {
+    const source = `
+      import { isBrowser } from './utils'
+      function getStorage() {
+        if (!isBrowser()) return null
+        return window.localStorage
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('silent for a function with AND-chained typeof body', () => {
+    const source = `
+      function isBrowser() {
+        return typeof window !== 'undefined' && typeof document !== 'undefined'
+      }
+      function read() {
+        if (!isBrowser()) return null
+        return document.cookie
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+  })
+
+  it('still fires for a non-conventional function name with no typeof body', () => {
+    const source = `
+      function notAGuard() { return true }
+      function getStorage() {
+        if (!notAGuard()) return null
+        return window.localStorage
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBeGreaterThanOrEqual(1)
+  })
+})
+
+// `no-imperative-navigate-in-render` — navigate calls inside nested
+// functions (event handlers, effect callbacks, ref callbacks) are deferred
+// execution and must not be flagged.
+describe('no-imperative-navigate-in-render: deferred-execution callbacks', () => {
+  it('silent when router.push is inside an event handler assigned to a local const', () => {
+    const source = `
+      const RouterLink = (props) => {
+        const handleClick = (e) => {
+          router.push(props.to)
+        }
+        return <a onClick={handleClick} />
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-imperative-navigate-in-render').length).toBe(0)
+  })
+
+  it('silent when navigate is inside a setTimeout callback', () => {
+    const source = `
+      const Comp = (props) => {
+        setTimeout(() => { navigate('/home') }, 100)
+        return <div />
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-imperative-navigate-in-render').length).toBe(0)
+  })
+
+  it('still fires for router.push directly in component body', () => {
+    const source = `
+      const Comp = (props) => {
+        router.push('/elsewhere')
+        return <div />
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-imperative-navigate-in-render').length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('fires when a nested fn is DEFINED and immediately CALLED in the render body', () => {
+    // `const fn = () => router.push(); fn()` — the navigate runs synchronously
+    // on every render (same infinite-loop bug as a direct call).
+    const source = `
+      const Comp = (props) => {
+        const goHome = () => router.push('/home')
+        goHome()
+        return <div />
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-imperative-navigate-in-render').length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('silent when a nested fn containing navigate is defined but NOT called synchronously', () => {
+    // Defined-and-stored pattern — the navigate never runs during render.
+    const source = `
+      const Comp = (props) => {
+        const goHome = () => navigate('/home')
+        return <a onClick={goHome} />
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-imperative-navigate-in-render').length).toBe(0)
+  })
+})
+
+// `no-dom-in-setup` — recognises `requestAnimationFrame`, `onUnmount`,
+// `onCleanup`, `renderEffect` as safe contexts (post-mount browser only).
+describe('no-dom-in-setup: expanded safe-context set', () => {
+  it('silent inside requestAnimationFrame callback', () => {
+    const source = `
+      requestAnimationFrame(() => {
+        const el = document.getElementById('x')
+      })
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-dom-in-setup').length).toBe(0)
+  })
+
+  it('silent inside onCleanup / onUnmount / renderEffect', () => {
+    const source = `
+      onCleanup(() => { document.querySelector('.x') })
+      onUnmount(() => { document.getElementById('y') })
+      renderEffect(() => { document.getElementsByClassName('z') })
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/no-dom-in-setup').length).toBe(0)
+  })
+})
+
+// `dev-guard-warnings` — conventional name-based flag recognition. The rule
+// can't follow cross-module imports to verify a binding really resolves to
+// `import.meta.env.DEV`, so well-known dev-flag identifiers (`__DEV__`,
+// `IS_DEV`, `IS_DEVELOPMENT`, `isDev`) are recognised by name.
+describe('dev-guard-warnings: dev-flag identifier conventions', () => {
+  it('silent under `if (!IS_DEVELOPMENT) return` early-return guard', () => {
+    const source = `
+      function devWarn(msg) {
+        if (!IS_DEVELOPMENT) return
+        console.warn(msg)
+      }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/dev-guard-warnings').length).toBe(0)
+  })
+
+  it('silent under `IS_DEV && console.warn(...)` logical-and guard', () => {
+    const source = `IS_DEV && console.warn('hello')`
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/dev-guard-warnings').length).toBe(0)
+  })
+
+  it('still fires without any guard', () => {
+    const source = `console.warn('no guard')`
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/dev-guard-warnings').length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('silent under locally-bound dev flag: `const D = import.meta.env.DEV === true; if (D) { console.warn(…) }`', () => {
+    const source = `
+      const D = import.meta.env.DEV === true
+      if (D) { console.warn('boom') }
+    `
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/dev-guard-warnings').length).toBe(0)
+  })
+
+  it('user-supplied `devFlagNames` extends the default set', () => {
+    const source = `
+      if (__DEBUG__) { console.warn('hello') }
+      // Built-ins still work:
+      if (__DEV__) { console.warn('world') }
+    `
+    const base = getPreset('recommended')
+    const existing = base.rules['pyreon/dev-guard-warnings']
+    const severity = Array.isArray(existing) ? existing[0] : existing
+    const cfg: LintConfig = {
+      ...base,
+      rules: {
+        ...base.rules,
+        'pyreon/dev-guard-warnings': [severity as 'error', { devFlagNames: ['__DEBUG__'] }],
+      },
+    }
+    const result = lintFile('src/foo.ts', source, allRules, cfg)
+    expect(findByRule(result, 'pyreon/dev-guard-warnings').length).toBe(0)
+  })
+
+  it('unknown identifier does NOT act as a guard (negative case)', () => {
+    const source = `if (random_flag) { console.warn('hi') }`
+    const result = lintSource(source)
+    expect(findByRule(result, 'pyreon/dev-guard-warnings').length).toBeGreaterThanOrEqual(1)
+  })
+})
+
+// ── Test-file heuristic (C-rules) ────────────────────────────────────────────
+//
+// Three rules can't distinguish "intentional test stub" from "real production
+// usage" purely from the AST (the rule's premise is intent-dependent: did
+// you forget validation, did you mean to duplicate this id, did you mean
+// to leave the field unregistered). For these we keep an explicit test-file
+// heuristic and document it as such — a `// pyreon-lint-disable-next-line`
+// is the right tool for intentional exceptions in production code.
+//
+// `no-circular-import` also keeps file-path skip but for a different reason —
+// tests don't ship as part of the layered production dep graph, so the
+// layer-order discipline genuinely doesn't apply to them. Categorical, not
+// a heuristic.
+
+describe('test-file heuristic (rules that intentionally skip *.test.* files)', () => {
+  const cases: Array<[string, string, string]> = [
+    ['pyreon/no-submit-without-validation', 'src/tests/form.test.tsx', `useForm({ onSubmit: () => {} })`],
+    ['pyreon/no-duplicate-store-id', 'src/tests/store.test.ts', `defineStore('a', () => {}); defineStore('a', () => {})`],
+    ['pyreon/no-unregistered-field', 'src/tests/form.test.ts', `const f = useField(form, 'x')`],
+    ['pyreon/no-circular-import', 'packages/core/runtime-dom/src/tests/integration.test.ts', `import { renderToString } from '@pyreon/runtime-server'`],
+  ]
+
+  for (const [rule, filePath, source] of cases) {
+    it(`${rule}: exempt in ${filePath}`, () => {
+      const result = lintFile(filePath, source, allRules, defaultConfig())
+      const diags = findByRule(result, rule)
+      expect(diags.length).toBe(0)
+    })
+  }
+})
+
+// ── Rule options schema validation ───────────────────────────────────────────
+
+describe('rule options schema', () => {
+  beforeEach(async () => {
+    const { _resetConfigDiagnosticsCache } = await import('../runner')
+    _resetConfigDiagnosticsCache()
+  })
+
+  it('wrong-typed option disables the rule + surfaces a config diagnostic', () => {
+    // `exemptPaths` declared as string[]; user passes a string. Cast via
+    // JSON.parse so we exercise the runtime validator (TypeScript would
+    // otherwise reject the literal at compile time).
+    const badOptions = JSON.parse(
+      `{"exemptPaths":"packages/core/runtime-dom/"}`,
+    ) as Record<string, unknown>
+    const cfg: LintConfig = {
+      rules: { 'pyreon/no-window-in-ssr': ['error', badOptions] },
+    }
+    const source = `const w = window.innerWidth`
+    const sink: ConfigDiagnostic[] = []
+    const result = lintFile(
+      'packages/core/runtime-dom/src/foo.ts',
+      source,
+      allRules,
+      cfg,
+      undefined,
+      sink,
+    )
+    // Rule disabled → no file diagnostic for this rule (even though the
+    // source WOULD trip it with a valid config).
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+    // Config diagnostic surfaces in the sink (not just stderr).
+    expect(sink.some((d) => d.severity === 'error' && d.message.includes('must be string[]'))).toBe(
+      true,
+    )
+  })
+
+  it('unknown option surfaces a warning diagnostic but keeps the rule enabled', () => {
+    const cfg: LintConfig = {
+      rules: {
+        'pyreon/no-window-in-ssr': [
+          'error',
+          { typo: 'oops', exemptPaths: ['packages/core/runtime-dom/'] },
+        ],
+      },
+    }
+    const source = `const w = window.innerWidth`
+    const sink: ConfigDiagnostic[] = []
+    const result = lintFile(
+      'packages/core/runtime-dom/src/foo.ts',
+      source,
+      allRules,
+      cfg,
+      undefined,
+      sink,
+    )
+    // Rule still works (real exemptPaths still applied).
+    expect(findByRule(result, 'pyreon/no-window-in-ssr').length).toBe(0)
+    // Warning surfaces.
+    expect(sink.some((d) => d.severity === 'warn' && d.message.includes('unknown option "typo"'))).toBe(
+      true,
+    )
+  })
+
+  it('schema-less rules accept any options without validation diagnostics', () => {
+    // `no-map-in-jsx` has no schema — options pass through.
+    const cfg: LintConfig = {
+      rules: { 'pyreon/no-map-in-jsx': ['warn', { whatever: [1, 2, 3] }] },
+    }
+    const source = `const X = () => <div>{items.map(i => <span>{i}</span>)}</div>`
+    const sink: ConfigDiagnostic[] = []
+    const result = lintFile('src/Foo.tsx', source, allRules, cfg, undefined, sink)
+    expect(findByRule(result, 'pyreon/no-map-in-jsx').length).toBeGreaterThanOrEqual(1)
+    expect(sink.length).toBe(0)
+  })
+
+  it('config diagnostics flow through `lint()` to LintResult.configDiagnostics', async () => {
+    // End-to-end: `lint()` on a tmp dir with bad config → result has the diagnostic.
+    const { tmpdir } = await import('node:os')
+    const { mkdtempSync, writeFileSync, rmSync } = await import('node:fs')
+    const { join } = await import('node:path')
+    const dir = mkdtempSync(join(tmpdir(), 'pyreon-lint-cfg-bad-'))
+    try {
+      writeFileSync(join(dir, '.pyreonlintrc.json'), JSON.stringify({
+        preset: 'recommended',
+        rules: { 'pyreon/no-window-in-ssr': ['error', { exemptPaths: 'oops-not-array' }] },
+      }))
+      writeFileSync(join(dir, 'foo.ts'), `const w = window.innerWidth`)
+
+      const { lint } = await import('../lint')
+      const result = lint({ paths: [dir], config: join(dir, '.pyreonlintrc.json') })
+      expect(result.configDiagnostics.length).toBeGreaterThanOrEqual(1)
+      expect(result.configDiagnostics.some((d) => d.message.includes('must be string[]'))).toBe(true)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})
+
+// ── CLI --rule-options parser ────────────────────────────────────────────────
+
+describe('parseRuleOptionsOverride (CLI flag parser)', () => {
+  let parser: typeof import('../cli').parseRuleOptionsOverride
+  beforeAll(async () => {
+    parser = (await import('../cli')).parseRuleOptionsOverride
+  })
+
+  it('parses valid `id={"key":[...]}` payload', () => {
+    const sink: Record<string, Record<string, unknown>> = {}
+    parser(`pyreon/no-window-in-ssr={"exemptPaths":["src/foundation/"]}`, sink)
+    expect(sink['pyreon/no-window-in-ssr']).toEqual({ exemptPaths: ['src/foundation/'] })
+  })
+
+  it('rejects malformed JSON (logs to stderr, leaves sink untouched)', () => {
+    const errs: string[] = []
+    const orig = console.error
+    console.error = (...a: unknown[]) => errs.push(a.map(String).join(' '))
+    try {
+      const sink: Record<string, Record<string, unknown>> = {}
+      parser(`pyreon/foo={not json}`, sink)
+      expect(Object.keys(sink).length).toBe(0)
+      expect(errs.some((e) => e.includes('invalid JSON'))).toBe(true)
+    } finally {
+      console.error = orig
+    }
+  })
+
+  it('rejects non-object JSON payload (e.g. an array)', () => {
+    const errs: string[] = []
+    const orig = console.error
+    console.error = (...a: unknown[]) => errs.push(a.map(String).join(' '))
+    try {
+      const sink: Record<string, Record<string, unknown>> = {}
+      parser(`pyreon/foo=[1,2,3]`, sink)
+      expect(Object.keys(sink).length).toBe(0)
+      expect(errs.some((e) => e.includes('expected JSON object'))).toBe(true)
+    } finally {
+      console.error = orig
+    }
+  })
+
+  it('ignores empty value', () => {
+    const sink: Record<string, Record<string, unknown>> = {}
+    parser(undefined, sink)
+    parser('', sink)
+    expect(Object.keys(sink).length).toBe(0)
+  })
+
+  it('ignores value missing the `=` separator', () => {
+    const sink: Record<string, Record<string, unknown>> = {}
+    parser('pyreon/foo-no-eq', sink)
+    expect(Object.keys(sink).length).toBe(0)
+  })
+
+  it('preserves rule IDs that contain `=` after the first separator', () => {
+    const sink: Record<string, Record<string, unknown>> = {}
+    parser(`pyreon/x={"foo":"a=b=c"}`, sink)
+    expect(sink['pyreon/x']).toEqual({ foo: 'a=b=c' })
+  })
+})
+
+// ── CLI ruleOptionsOverrides → lint() integration ───────────────────────────
+
+describe('lint() ruleOptionsOverrides (CLI --rule-options pathway)', () => {
+  it('CLI options override merge on top of file-config options', async () => {
+    const { tmpdir } = await import('node:os')
+    const { mkdtempSync, writeFileSync, rmSync } = await import('node:fs')
+    const { join } = await import('node:path')
+    const dir = mkdtempSync(join(tmpdir(), 'pyreon-lint-cli-opts-'))
+    try {
+      // No rc file — just CLI override.
+      writeFileSync(join(dir, 'foo.tsx'), `const w = window.innerWidth`)
+      const { lint } = await import('../lint')
+
+      // Without override → rule fires.
+      const before = lint({ paths: [dir] })
+      const beforeCount = before.files.flatMap((f) => f.diagnostics)
+        .filter((d) => d.ruleId === 'pyreon/no-window-in-ssr').length
+      expect(beforeCount).toBeGreaterThanOrEqual(1)
+
+      // With CLI override exempting the dir → rule silent.
+      const after = lint({
+        paths: [dir],
+        ruleOptionsOverrides: {
+          'pyreon/no-window-in-ssr': { exemptPaths: [dir] },
+        },
+      })
+      const afterCount = after.files.flatMap((f) => f.diagnostics)
+        .filter((d) => d.ruleId === 'pyreon/no-window-in-ssr').length
+      expect(afterCount).toBe(0)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})
+
+// ── /examples/ regression assertion ─────────────────────────────────────────
+//
+// This PR moves the `/examples/` skip out of `dev-guard-warnings` rule source
+// (Pyreon convention, not universal) and into the monorepo's own
+// `.pyreonlintrc.json`. Without that config, the rule now fires inside
+// `/examples/`. This test pins that behavior change so future readers see
+// it intentionally regressed for users who relied on the implicit skip.
+
+describe('dev-guard-warnings: /examples/ skip moved to config', () => {
+  it('fires in /examples/ when no exemptPaths are configured', () => {
+    const source = `console.warn("oops")`
+    const result = lintFile(
+      'examples/my-app/src/index.tsx',
+      source,
+      allRules,
+      defaultConfig(),
+    )
+    expect(findByRule(result, 'pyreon/dev-guard-warnings').length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('silent in /examples/ when configured via exemptPaths', () => {
+    const source = `console.warn("oops")`
+    const cfg = configWithExemptPaths('pyreon/dev-guard-warnings', ['examples/'])
+    const result = lintFile('examples/my-app/src/index.tsx', source, allRules, cfg)
+    expect(findByRule(result, 'pyreon/dev-guard-warnings').length).toBe(0)
+  })
+})
+
+// ── End-to-end: .pyreonlintrc.json round-trip ────────────────────────────────
+
+describe('config-file round-trip', () => {
+  it('loads tuple-form rule entries from .pyreonlintrc.json and applies exemptPaths', async () => {
+    const { tmpdir } = await import('node:os')
+    const { mkdtempSync, writeFileSync, rmSync } = await import('node:fs')
+    const { join } = await import('node:path')
+    const dir = mkdtempSync(join(tmpdir(), 'pyreon-lint-cfg-'))
+    try {
+      // Write a config that uses the tuple form.
+      writeFileSync(
+        join(dir, '.pyreonlintrc.json'),
+        JSON.stringify({
+          preset: 'recommended',
+          rules: {
+            'pyreon/no-window-in-ssr': ['error', { exemptPaths: ['src/foundation/'] }],
+          },
+        }),
+      )
+
+      const { loadConfig } = await import('../config/loader')
+      const loaded = loadConfig(dir)
+      expect(loaded).toBeTruthy()
+      expect(loaded?.rules?.['pyreon/no-window-in-ssr']).toBeInstanceOf(Array)
+
+      // Build a runtime config from the loaded file + exercise the rule.
+      const base = getPreset('recommended')
+      const runtimeCfg: LintConfig = {
+        ...base,
+        rules: { ...base.rules, ...(loaded?.rules ?? {}) },
+      }
+
+      // In an exempt path — rule silent.
+      const exempt = lintFile(
+        'src/foundation/raw-window.ts',
+        `const w = window.innerWidth`,
+        allRules,
+        runtimeCfg,
+      )
+      expect(findByRule(exempt, 'pyreon/no-window-in-ssr').length).toBe(0)
+
+      // Outside the exempt path — rule fires.
+      const fires = lintFile(
+        'src/components/Hero.tsx',
+        `const w = window.innerWidth`,
+        allRules,
+        runtimeCfg,
+      )
+      expect(findByRule(fires, 'pyreon/no-window-in-ssr').length).toBeGreaterThanOrEqual(1)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})
+
+// ── pyreon/require-browser-smoke-test ─────────────────────────────────────
+//
+// Locks in the durability of the T1.1 browser smoke harness. Without this
+// rule, any new browser-running package can quietly ship without smoke
+// coverage and we drift back to the world before T1.1.
+
+describe('pyreon/require-browser-smoke-test', () => {
+  // Helpers shared by the suite — set up a fake MONOREPO with a
+  // `.claude/rules/browser-packages.json` at the root and a fake
+  // package under `packages/<name>/`. The rule discovers the JSON by
+  // walking upward from the linted file, so we mirror that structure.
+  async function setupFakePackage(opts: {
+    pkgName: string
+    withBrowserTest: boolean
+    browserPackagesOverride?: string[]
+  }): Promise<{ rootDir: string; indexPath: string; pkgDir: string; cleanup: () => void }> {
+    const { mkdirSync, mkdtempSync, rmSync, writeFileSync } = await import('node:fs')
+    const { tmpdir } = await import('node:os')
+    const { join } = await import('node:path')
+    const rule = await import('../rules/architecture/require-browser-smoke-test')
+
+    // Reset the module-level cache so earlier tests' JSON doesn't leak in.
+    rule._resetBrowserPackagesCache()
+
+    const rootDir = mkdtempSync(join(tmpdir(), 'pyreon-require-browser-smoke-'))
+    mkdirSync(join(rootDir, '.claude', 'rules'), { recursive: true })
+    const packages = opts.browserPackagesOverride ?? [
+      '@pyreon/runtime-dom',
+      '@pyreon/router',
+      '@pyreon/head',
+      '@pyreon/flow',
+      '@pyreon/code',
+      '@pyreon/charts',
+      '@pyreon/document-primitives',
+      '@pyreon/connector-document',
+      '@pyreon/elements',
+      '@pyreon/styler',
+      '@pyreon/unistyle',
+      '@pyreon/rocketstyle',
+      '@pyreon/coolgrid',
+      '@pyreon/kinetic',
+      '@pyreon/ui-components',
+      '@pyreon/ui-primitives',
+      '@pyreon/ui-theme',
+      '@pyreon/react-compat',
+      '@pyreon/preact-compat',
+      '@pyreon/vue-compat',
+      '@pyreon/solid-compat',
+    ]
+    writeFileSync(
+      join(rootDir, '.claude', 'rules', 'browser-packages.json'),
+      JSON.stringify({ packages }),
+    )
+
+    const pkgDir = join(rootDir, 'packages', opts.pkgName.replace('@pyreon/', ''))
+    mkdirSync(join(pkgDir, 'src'), { recursive: true })
+    writeFileSync(
+      join(pkgDir, 'package.json'),
+      JSON.stringify({ name: opts.pkgName, version: '0.0.0' }),
+    )
+    const indexPath = join(pkgDir, 'src', 'index.ts')
+    writeFileSync(indexPath, `export const x = 1\n`)
+    if (opts.withBrowserTest) {
+      writeFileSync(
+        join(pkgDir, 'src', 'mount.browser.test.ts'),
+        `import { it } from 'vitest'; it('ok', () => {})\n`,
+      )
+    }
+    return {
+      rootDir,
+      pkgDir,
+      indexPath,
+      cleanup: () => {
+        rule._resetBrowserPackagesCache()
+        rmSync(rootDir, { recursive: true, force: true })
+      },
+    }
+  }
+
+  it('reports an error when a browser package ships no .browser.test.* file', async () => {
+    const fake = await setupFakePackage({
+      pkgName: '@pyreon/runtime-dom', // a real browser package name
+      withBrowserTest: false,
+    })
+    try {
+      const result = lintWith(
+        'pyreon/require-browser-smoke-test',
+        `export const x = 1`,
+        fake.indexPath,
+      )
+      const diags = findByRule(result, 'pyreon/require-browser-smoke-test')
+      expect(diags.length).toBe(1)
+      expect(diags[0]?.message).toMatch(/no `\*\.browser\.test/)
+      expect(diags[0]?.message).toMatch(/@pyreon\/runtime-dom/)
+    } finally {
+      fake.cleanup()
+    }
+  })
+
+  it('passes when the package has at least one .browser.test.ts file', async () => {
+    const fake = await setupFakePackage({
+      pkgName: '@pyreon/runtime-dom',
+      withBrowserTest: true,
+    })
+    try {
+      const result = lintWith(
+        'pyreon/require-browser-smoke-test',
+        `export const x = 1`,
+        fake.indexPath,
+      )
+      expect(findByRule(result, 'pyreon/require-browser-smoke-test').length).toBe(0)
+    } finally {
+      fake.cleanup()
+    }
+  })
+
+  it('skips packages not in the browser-categorized list', async () => {
+    const fake = await setupFakePackage({
+      pkgName: '@pyreon/server', // server-only, not categorized
+      withBrowserTest: false,
+    })
+    try {
+      const result = lintWith(
+        'pyreon/require-browser-smoke-test',
+        `export const x = 1`,
+        fake.indexPath,
+      )
+      expect(findByRule(result, 'pyreon/require-browser-smoke-test').length).toBe(0)
+    } finally {
+      fake.cleanup()
+    }
+  })
+
+  it('runs only on src/index.ts — internal files are skipped', async () => {
+    const fake = await setupFakePackage({
+      pkgName: '@pyreon/runtime-dom',
+      withBrowserTest: false,
+    })
+    try {
+      const { writeFileSync } = await import('node:fs')
+      const { join } = await import('node:path')
+      const internalPath = join(fake.pkgDir, 'src', 'internal.ts')
+      writeFileSync(internalPath, `export const y = 2\n`)
+      const result = lintWith(
+        'pyreon/require-browser-smoke-test',
+        `export const y = 2`,
+        internalPath,
+      )
+      // Internal file → no report (rule short-circuits).
+      expect(findByRule(result, 'pyreon/require-browser-smoke-test').length).toBe(0)
+    } finally {
+      fake.cleanup()
+    }
+  })
+
+  it('additionalPackages option opts new packages into the requirement', async () => {
+    const fake = await setupFakePackage({
+      pkgName: '@my-org/my-browser-pkg', // not in the default list
+      withBrowserTest: false,
+    })
+    try {
+      const cfg: LintConfig = {
+        rules: {
+          'pyreon/require-browser-smoke-test': [
+            'error',
+            { additionalPackages: ['@my-org/my-browser-pkg'] },
+          ],
+        },
+      }
+      const result = lintFile(
+        fake.indexPath,
+        `export const x = 1`,
+        allRules,
+        cfg,
+      )
+      expect(findByRule(result, 'pyreon/require-browser-smoke-test').length).toBe(1)
+    } finally {
+      fake.cleanup()
+    }
+  })
+
+  it('exemptPaths option opts packages out of the requirement', async () => {
+    const fake = await setupFakePackage({
+      pkgName: '@pyreon/runtime-dom',
+      withBrowserTest: false,
+    })
+    try {
+      const cfg: LintConfig = {
+        rules: {
+          'pyreon/require-browser-smoke-test': [
+            'error',
+            { exemptPaths: [fake.pkgDir] },
+          ],
+        },
+      }
+      const result = lintFile(
+        fake.indexPath,
+        `export const x = 1`,
+        allRules,
+        cfg,
+      )
+      expect(findByRule(result, 'pyreon/require-browser-smoke-test').length).toBe(0)
+    } finally {
+      fake.cleanup()
+    }
+  })
+
+  // ── Edge cases for the directory walker + single-source-of-truth ──────
+
+  it('finds a .browser.test.tsx file (not just .ts extension)', async () => {
+    const fake = await setupFakePackage({
+      pkgName: '@pyreon/runtime-dom',
+      withBrowserTest: false,
+    })
+    try {
+      const { writeFileSync } = await import('node:fs')
+      const { join } = await import('node:path')
+      writeFileSync(
+        join(fake.pkgDir, 'src', 'mount.browser.test.tsx'),
+        `export {}`,
+      )
+      const result = lintWith(
+        'pyreon/require-browser-smoke-test',
+        `export const x = 1`,
+        fake.indexPath,
+      )
+      expect(findByRule(result, 'pyreon/require-browser-smoke-test').length).toBe(0)
+    } finally {
+      fake.cleanup()
+    }
+  })
+
+  it('finds a browser test nested deep inside src/', async () => {
+    const fake = await setupFakePackage({
+      pkgName: '@pyreon/runtime-dom',
+      withBrowserTest: false,
+    })
+    try {
+      const { mkdirSync, writeFileSync } = await import('node:fs')
+      const { join } = await import('node:path')
+      const deep = join(fake.pkgDir, 'src', 'a', 'b', 'c', 'd')
+      mkdirSync(deep, { recursive: true })
+      writeFileSync(join(deep, 'nested.browser.test.ts'), `export {}`)
+      const result = lintWith(
+        'pyreon/require-browser-smoke-test',
+        `export const x = 1`,
+        fake.indexPath,
+      )
+      expect(findByRule(result, 'pyreon/require-browser-smoke-test').length).toBe(0)
+    } finally {
+      fake.cleanup()
+    }
+  })
+
+  it('skips node_modules / lib / dist / dotfolders when scanning', async () => {
+    // A package has NO real browser test but its node_modules contains
+    // transitive browser tests (e.g. a dependency's dist). The rule must
+    // not count those — they're not this package's contract.
+    const fake = await setupFakePackage({
+      pkgName: '@pyreon/runtime-dom',
+      withBrowserTest: false,
+    })
+    try {
+      const { mkdirSync, writeFileSync } = await import('node:fs')
+      const { join } = await import('node:path')
+      const nm = join(fake.pkgDir, 'node_modules', 'some-dep', 'src')
+      mkdirSync(nm, { recursive: true })
+      writeFileSync(join(nm, 'fake.browser.test.ts'), `export {}`)
+      const lib = join(fake.pkgDir, 'lib')
+      mkdirSync(lib, { recursive: true })
+      writeFileSync(join(lib, 'built.browser.test.ts'), `export {}`)
+      const result = lintWith(
+        'pyreon/require-browser-smoke-test',
+        `export const x = 1`,
+        fake.indexPath,
+      )
+      // Still reports missing — node_modules/lib contents don't count.
+      expect(findByRule(result, 'pyreon/require-browser-smoke-test').length).toBe(1)
+    } finally {
+      fake.cleanup()
+    }
+  })
+
+  it('falls back to empty list when browser-packages.json is absent (safe default)', async () => {
+    // A consumer repo that uses @pyreon/lint but doesn't ship the JSON.
+    // The rule should become a no-op (or only fire on explicit
+    // additionalPackages) so it doesn't false-positive every index.ts.
+    const { mkdirSync, mkdtempSync, rmSync, writeFileSync } = await import('node:fs')
+    const { tmpdir } = await import('node:os')
+    const { join } = await import('node:path')
+    const rule = await import('../rules/architecture/require-browser-smoke-test')
+    rule._resetBrowserPackagesCache()
+
+    const rootDir = mkdtempSync(join(tmpdir(), 'pyreon-lint-no-json-'))
+    try {
+      const pkgDir = join(rootDir, 'packages', 'runtime-dom')
+      mkdirSync(join(pkgDir, 'src'), { recursive: true })
+      writeFileSync(
+        join(pkgDir, 'package.json'),
+        JSON.stringify({ name: '@pyreon/runtime-dom' }),
+      )
+      const indexPath = join(pkgDir, 'src', 'index.ts')
+      writeFileSync(indexPath, `export const x = 1`)
+      const result = lintWith(
+        'pyreon/require-browser-smoke-test',
+        `export const x = 1`,
+        indexPath,
+      )
+      // No JSON found → empty list → rule stays silent.
+      expect(findByRule(result, 'pyreon/require-browser-smoke-test').length).toBe(0)
+    } finally {
+      rule._resetBrowserPackagesCache()
+      rmSync(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  it('malformed browser-packages.json falls back to empty (no crash, no false positives)', async () => {
+    const { mkdirSync, mkdtempSync, rmSync, writeFileSync } = await import('node:fs')
+    const { tmpdir } = await import('node:os')
+    const { join } = await import('node:path')
+    const rule = await import('../rules/architecture/require-browser-smoke-test')
+    rule._resetBrowserPackagesCache()
+
+    const rootDir = mkdtempSync(join(tmpdir(), 'pyreon-lint-bad-json-'))
+    try {
+      mkdirSync(join(rootDir, '.claude', 'rules'), { recursive: true })
+      writeFileSync(
+        join(rootDir, '.claude', 'rules', 'browser-packages.json'),
+        `{ not valid json`,
+      )
+      const pkgDir = join(rootDir, 'packages', 'runtime-dom')
+      mkdirSync(join(pkgDir, 'src'), { recursive: true })
+      writeFileSync(
+        join(pkgDir, 'package.json'),
+        JSON.stringify({ name: '@pyreon/runtime-dom' }),
+      )
+      const indexPath = join(pkgDir, 'src', 'index.ts')
+      writeFileSync(indexPath, `export const x = 1`)
+      const result = lintWith(
+        'pyreon/require-browser-smoke-test',
+        `export const x = 1`,
+        indexPath,
+      )
+      // Parse failure → empty list → rule stays silent (no crash).
+      expect(findByRule(result, 'pyreon/require-browser-smoke-test').length).toBe(0)
+    } finally {
+      rule._resetBrowserPackagesCache()
+      rmSync(rootDir, { recursive: true, force: true })
+    }
+  })
+})