@pyreon/lint 0.12.12 → 0.12.14

package/src/rules/architecture/dev-guard-warnings.ts

@@ -1,5 +1,7 @@
 import type { Rule, VisitorCallbacks } from '../../types'
 import { getSpan } from '../../utils/ast'
+import { isPathExempt } from '../../utils/exempt-paths'
+import { isTestFile } from '../../utils/file-roles'
 
 export const devGuardWarnings: Rule = {
   meta: {
@@ -8,31 +10,183 @@ export const devGuardWarnings: Rule = {
     description: 'Require console.warn/error calls to be wrapped in `if (__DEV__)` guards.',
     severity: 'error',
     fixable: false,
+    schema: { exemptPaths: 'string[]', devFlagNames: 'string[]' },
   },
   create(context) {
-    const filePath = context.getFilePath()
-    // Skip test and example files
-    if (
-      filePath.includes('/tests/') ||
-      filePath.includes('/test/') ||
-      filePath.includes('/examples/') ||
-      filePath.includes('.test.') ||
-      filePath.includes('.spec.')
-    ) {
-      return {}
+    // Skip test files — universal convention (`*.test.*` etc. exist in
+    // every project this linter runs on and don't ship to production).
+    if (isTestFile(context.getFilePath())) return {}
+
+    // Configurable `exemptPaths` — projects opt out directories where the
+    // rule's premise doesn't apply (server-only code where dev/prod is
+    // `process.env.NODE_ENV`, or example / demo directories that ship
+    // as documentation rather than production).
+    if (isPathExempt(context)) return {}
+
+    // Project-level additions to the built-in dev-flag name list. Merged
+    // with the defaults so a custom flag like `__DEBUG__` still picks up
+    // the built-in `__DEV__`/`IS_DEVELOPMENT`/etc. without restating them.
+    const userFlagNames = context.getOptions().devFlagNames
+    const extraFlagNames = Array.isArray(userFlagNames)
+      ? userFlagNames.filter((n): n is string => typeof n === 'string')
+      : []
+
+    // Identifiers bound via `const X = <devFlag expression>` — e.g.
+    // `const IS_DEVELOPMENT = import.meta.env.DEV === true`. These act as
+    // the same dev-mode gate as the raw flag at their call sites.
+    const devFlagBoundConsts = new Set<string>()
+    function exprResolvesToDevFlag(expr: any): boolean {
+      if (!expr) return false
+      if (expr.type === 'ChainExpression') return exprResolvesToDevFlag(expr.expression)
+      if (isDevFlag(expr)) return true
+      // `import.meta.env.DEV === true` / `true === import.meta.env.DEV`
+      if (
+        expr.type === 'BinaryExpression' &&
+        (expr.operator === '===' || expr.operator === '==')
+      ) {
+        return exprResolvesToDevFlag(expr.left) || exprResolvesToDevFlag(expr.right)
+      }
+      return false
+    }
+
+    // Conventional identifier names treated as dev-mode gates. Covers both
+    // local `const __DEV__ = …` style and imported flags like `IS_DEV` /
+    // `IS_DEVELOPMENT` from a package's shared utils module. The rule can't
+    // follow cross-module imports to verify that the binding really resolves
+    // to `import.meta.env.DEV`, so we fall back to the name convention —
+    // consistent with how the existing `__DEV__` identifier works. Projects
+    // can extend the list via the `devFlagNames` rule option.
+    const DEV_FLAG_NAMES = new Set<string>([
+      '__DEV__',
+      'IS_DEV',
+      'IS_DEVELOPMENT',
+      'isDev',
+      ...extraFlagNames,
+    ])
+
+    // Direct dev-mode flags this rule treats as guards.
+    function isDevFlag(node: any): boolean {
+      if (!node) return false
+      if (node.type === 'ChainExpression') return isDevFlag(node.expression)
+      // Conventional dev-flag identifier names.
+      if (node.type === 'Identifier' && DEV_FLAG_NAMES.has(node.name)) return true
+      // Const-bound dev flag, e.g. `const devMode = import.meta.env.DEV`.
+      if (node.type === 'Identifier' && devFlagBoundConsts.has(node.name)) return true
+      // `import.meta.env.DEV` (and `import.meta.env?.DEV` after ChainExpression unwrap)
+      if (
+        node.type === 'MemberExpression' &&
+        node.property?.type === 'Identifier' &&
+        node.property.name === 'DEV'
+      ) {
+        const obj = node.object
+        if (
+          obj?.type === 'MemberExpression' &&
+          obj.property?.type === 'Identifier' &&
+          obj.property.name === 'env' &&
+          obj.object?.type === 'MetaProperty'
+        )
+          return true
+      }
+      return false
+    }
+
+    // Match `<flag>`, `<flag> && X`, `X && <flag>`, `<flag> === true`, etc.
+    // `&&` only — `||` doesn't guarantee dev-only execution.
+    function containsDevGuard(test: any): boolean {
+      if (!test) return false
+      if (isDevFlag(test)) return true
+      if (test.type === 'LogicalExpression' && test.operator === '&&') {
+        return containsDevGuard(test.left) || containsDevGuard(test.right)
+      }
+      // `flag === true` or `true === flag` — common after `?? === true` shape.
+      if (
+        test.type === 'BinaryExpression' &&
+        (test.operator === '===' || test.operator === '==')
+      ) {
+        return isDevFlag(test.left) || isDevFlag(test.right)
+      }
+      return false
+    }
+
+    // Detects an early-return DEV guard at the head of a function body:
+    //   `if (!__DEV__) return`  /  `if (!import.meta.env.DEV) return`
+    // Everything after this in the function is implicitly dev-only.
+    function isEarlyReturnDevGuard(node: any): boolean {
+      if (!node || node.type !== 'IfStatement') return false
+      const t = node.test
+      const arg = t?.type === 'UnaryExpression' && t.operator === '!' ? t.argument : null
+      if (!arg) return false
+      if (!isDevFlag(arg)) return false
+      const c = node.consequent
+      if (c?.type === 'ReturnStatement') return true
+      if (c?.type === 'BlockStatement' && c.body.length === 1 && c.body[0]?.type === 'ReturnStatement') return true
+      return false
     }
 
     let devGuardDepth = 0
+    let catchDepth = 0
+    // For each function we enter, record whether its first statement is an
+    // early-return DEV guard. If yes, the function's body is dev-only and
+    // we treat it as one guard depth for the duration.
+    const funcGuardStack: number[] = []
+    function enterFunction(node: any) {
+      const body = node?.body
+      const stmts = body?.type === 'BlockStatement' ? body.body : null
+      let guarded = 0
+      if (stmts && stmts.length > 0 && isEarlyReturnDevGuard(stmts[0])) {
+        guarded = 1
+        devGuardDepth++
+      }
+      funcGuardStack.push(guarded)
+    }
+    function exitFunction() {
+      const g = funcGuardStack.pop() ?? 0
+      if (g > 0) devGuardDepth -= g
+    }
+
     const callbacks: VisitorCallbacks = {
-      IfStatement(node: any) {
-        if (node.test?.type === 'Identifier' && node.test.name === '__DEV__') {
-          devGuardDepth++
+      VariableDeclaration(node: any) {
+        for (const decl of node.declarations ?? []) {
+          if (decl.id?.type === 'Identifier' && exprResolvesToDevFlag(decl.init)) {
+            devFlagBoundConsts.add(decl.id.name)
+          }
         }
       },
+      FunctionDeclaration: enterFunction,
+      'FunctionDeclaration:exit': exitFunction,
+      FunctionExpression: enterFunction,
+      'FunctionExpression:exit': exitFunction,
+      ArrowFunctionExpression: enterFunction,
+      'ArrowFunctionExpression:exit': exitFunction,
+
+      IfStatement(node: any) {
+        if (containsDevGuard(node.test)) devGuardDepth++
+      },
       'IfStatement:exit'(node: any) {
-        if (node.test?.type === 'Identifier' && node.test.name === '__DEV__') {
-          devGuardDepth--
-        }
+        if (containsDevGuard(node.test)) devGuardDepth--
+      },
+      // Conditional expression as a statement — `__DEV__ && console.warn(...)`
+      // and `__DEV__ ? console.warn(...) : null` are equivalent dev-only hints.
+      LogicalExpression(node: any) {
+        if (node.operator === '&&' && containsDevGuard(node.left)) devGuardDepth++
+      },
+      'LogicalExpression:exit'(node: any) {
+        if (node.operator === '&&' && containsDevGuard(node.left)) devGuardDepth--
+      },
+      ConditionalExpression(node: any) {
+        if (containsDevGuard(node.test)) devGuardDepth++
+      },
+      'ConditionalExpression:exit'(node: any) {
+        if (containsDevGuard(node.test)) devGuardDepth--
+      },
+      // `console.error` in a catch block is legitimate production error
+      // reporting (the error already happened — surfacing it isn't a dev hint).
+      // `console.warn` in catch is still flagged: warnings should be DEV-only.
+      CatchClause() {
+        catchDepth++
+      },
+      'CatchClause:exit'() {
+        catchDepth--
       },
       CallExpression(node: any) {
         if (devGuardDepth > 0) return
@@ -45,8 +199,9 @@ export const devGuardWarnings: Rule = {
           callee.property?.type === 'Identifier' &&
           (callee.property.name === 'warn' || callee.property.name === 'error')
         ) {
+          if (callee.property.name === 'error' && catchDepth > 0) return
           context.report({
-            message: `\`console.${callee.property.name}()\` without \`__DEV__\` guard — dev warnings must be tree-shakeable in production. Wrap in \`if (__DEV__) { ... }\`.`,
+            message: `\`console.${callee.property.name}()\` without \`__DEV__\` guard — dev warnings must be tree-shakeable in production. Wrap in \`if (__DEV__) { ... }\` (or \`__DEV__ && ...\`). Production error logging in \`catch\` blocks is exempt for \`console.error\`.`,
             span: getSpan(node),
           })
         }

package/src/rules/architecture/no-circular-import.ts

@@ -1,6 +1,7 @@
 import type { Rule, VisitorCallbacks } from '../../types'
 import { getSpan } from '../../utils/ast'
 import { isPyreonImport } from '../../utils/imports'
+import { isTestFile } from '../../utils/file-roles'
 
 const LAYER_ORDER: Record<string, number> = {
   '@pyreon/reactivity': 0,
@@ -35,6 +36,12 @@ export const noCircularImport: Rule = {
   },
   create(context) {
     const filePath = context.getFilePath()
+    // Tests don't ship as part of the layered production dep graph — they're
+    // verification scaffolding. Cross-layer imports are routine and correct
+    // there (e.g. a `runtime-dom` test importing `renderToString` from
+    // `runtime-server` to compare SSR vs CSR output). Path-based skip is the
+    // semantic truth for this rule, not a heuristic.
+    if (isTestFile(filePath)) return {}
     const fileLayer = getFileLayer(filePath)
     if (fileLayer === null) return {}
 

package/src/rules/architecture/no-process-dev-gate.ts

@@ -1,5 +1,7 @@
 import type { Rule, VisitorCallbacks } from '../../types'
 import { getSpan } from '../../utils/ast'
+import { isPathExempt } from '../../utils/exempt-paths'
+import { isTestFile } from '../../utils/file-roles'
 
 /**
  * `pyreon/no-process-dev-gate` — flag the broken `typeof process` dev-mode gate
@@ -33,35 +35,19 @@ import { getSpan } from '../../utils/ast'
  * Does NOT delete the const declaration — that has to happen by hand because
  * the variable name and downstream usages may need updating in callers.
  *
- * **Server-package exception**: server-only files run in Node where `process`
- * is always defined, so the pattern is correct there. The rule skips files
- * matching `packages/zero/`, `packages/core/server/`, `packages/core/runtime-server/`,
- * `packages/tools/vite-plugin/`, and any file containing `/server/` in its
- * path. Add new server packages to `SERVER_PACKAGE_PATTERNS` below.
- */
-/**
- * File-path patterns for server-only packages. Substring match against the
- * file path passed to the rule. Patterns intentionally do NOT start with `/`
- * so they match both absolute paths (`/Users/.../packages/zero/...`) and
- * relative paths (`packages/zero/...`) — different lint runners pass paths
- * differently.
+ * **Server-only exemption**: projects configure `exemptPaths` per-file for
+ * server-only code (Node environments where `process` is always defined and
+ * the pattern is correct). Configure in `.pyreonlintrc.json`:
+ *
+ *     {
+ *       "rules": {
+ *         "pyreon/no-process-dev-gate": [
+ *           "error",
+ *           { "exemptPaths": ["packages/zero/", "packages/core/server/"] }
+ *         ]
+ *       }
+ *     }
  */
-const SERVER_PACKAGE_PATTERNS = [
-  'packages/zero/',
-  'packages/core/server/',
-  'packages/core/runtime-server/',
-  'packages/tools/vite-plugin/',
-  'packages/tools/cli/',
-  'packages/tools/lint/',
-  'packages/tools/mcp/',
-  'packages/tools/storybook/',
-  'packages/tools/typescript/',
-  'scripts/',
-]
-
-function isServerOnlyFile(filePath: string): boolean {
-  return SERVER_PACKAGE_PATTERNS.some((pat) => filePath.includes(pat))
-}
 
 export const noProcessDevGate: Rule = {
   meta: {
@@ -73,25 +59,12 @@ export const noProcessDevGate: Rule = {
     fixable: true,
   },
   create(context) {
-    const filePath = context.getFilePath()
-
     // Skip test files — vitest has `process`, the gate works there, and
-    // tests are not shipped to users.
-    if (
-      filePath.includes('/tests/') ||
-      filePath.includes('/test/') ||
-      filePath.includes('/__tests__/') ||
-      filePath.includes('.test.') ||
-      filePath.includes('.spec.')
-    ) {
-      return {}
-    }
+    // tests are not shipped to users. Universal, not a heuristic.
+    if (isTestFile(context.getFilePath())) return {}
 
-    // Skip server-only packages — they run in Node where `process` is
-    // always defined, so the pattern is correct there.
-    if (isServerOnlyFile(filePath)) {
-      return {}
-    }
+    // Configurable `exemptPaths` option for server-only directories.
+    if (isPathExempt(context)) return {}
 
     /**
      * Match the broken pattern at the AST level. We're looking for any

package/src/rules/architecture/require-browser-smoke-test.ts

@@ -0,0 +1,227 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import path from 'node:path'
+import type { Rule, VisitorCallbacks } from '../../types'
+import { isPathExempt } from '../../utils/exempt-paths'
+
+/**
+ * `pyreon/require-browser-smoke-test` — every browser-categorized package
+ * must ship at least one `*.browser.test.{ts,tsx}` file under `src/`.
+ *
+ * Locks in the durability of the T1.1 browser smoke harness (PRs #224,
+ * #227, #229, #231). Without this rule, any new browser-running package
+ * can quietly ship without a real-browser smoke test and we drift back
+ * to the world before T1.1 — where happy-dom silently masks
+ * environment-divergence bugs (PR #197 mock-vnode metadata drop, PR
+ * #200 `typeof process` dead code, the multi-word event delegation bug
+ * fixed alongside PR #231).
+ *
+ * **What it checks**: when linting a package's `src/index.ts`, the rule
+ * looks at the package directory for any file matching
+ * `**\/*.browser.test.{ts,tsx}`. If none are found AND the package's
+ * name appears in the browser-categorized list, the rule reports an
+ * error on `src/index.ts`.
+ *
+ * **Why src/index.ts only**: the rule needs to fire exactly once per
+ * package, not per file. `src/index.ts` is a stable per-package entry
+ * point. Files inside the package are not browser-test files
+ * themselves, so they get skipped via the path check.
+ *
+ * **Default browser packages list**: matches the categorization in
+ * `.claude/rules/test-environment-parity.md`. Override via the
+ * `additionalPackages` option to opt in new packages, or via
+ * `exemptPaths` to opt out (e.g. for a brand-new package still under
+ * construction).
+ *
+ * @example Configuration in `.pyreonlintrc.json`
+ * ```json
+ * {
+ *   "rules": {
+ *     "pyreon/require-browser-smoke-test": [
+ *       "error",
+ *       {
+ *         "additionalPackages": ["@my-org/my-browser-pkg"],
+ *         "exemptPaths": ["packages/experimental/"]
+ *       }
+ *     ]
+ *   }
+ * }
+ * ```
+ *
+ * **Known limitation — file existence, not test quality.** The rule only
+ * checks that at least one `*.browser.test.*` file exists under `src/`;
+ * it cannot assess whether the test is meaningful. A package could ship
+ * `sanity.browser.test.ts` with `expect(1).toBe(1)` and satisfy the
+ * rule. That's accepted by design — the rule is a *gate* against
+ * packages shipping with zero smoke coverage, not a quality check.
+ * Review the actual test contents on PR. If drive-by one-liner tests
+ * become a pattern, add a per-package coverage threshold or a
+ * complementary rule that inspects test file contents.
+ */
+
+/**
+ * Single source of truth for browser-categorized packages lives at
+ * `.claude/rules/browser-packages.json`. Loading it lazily here means:
+ *
+ *   1. Updating the list never requires re-publishing `@pyreon/lint`.
+ *   2. The script `scripts/check-browser-smoke.ts` + the human-readable
+ *      `.claude/rules/test-environment-parity.md` share the same source,
+ *      so they can't drift out of sync silently.
+ *
+ * The JSON is searched for by walking up from the linted file's directory
+ * to the first ancestor containing `.claude/rules/browser-packages.json`.
+ * If not found (rule running in a consumer repo that doesn't ship the
+ * JSON), the rule falls back to an empty list — `additionalPackages`
+ * becomes the only signal and the rule stays opt-in, not a footgun.
+ *
+ * Cached globally because the list is tiny and lint runs lint thousands
+ * of files per invocation.
+ */
+let _cachedBrowserPackages: Set<string> | null = null
+
+function loadBrowserPackages(fromFile: string): Set<string> {
+  if (_cachedBrowserPackages) return _cachedBrowserPackages
+  let dir = path.dirname(fromFile)
+  // Walk up to /; bounded in practice by the project root.
+  for (let i = 0; i < 30; i++) {
+    const candidate = path.join(dir, '.claude', 'rules', 'browser-packages.json')
+    if (existsSync(candidate)) {
+      try {
+        const fs = require('node:fs') as typeof import('node:fs')
+        const parsed = JSON.parse(fs.readFileSync(candidate, 'utf8')) as {
+          packages?: unknown
+        }
+        if (Array.isArray(parsed.packages)) {
+          _cachedBrowserPackages = new Set(
+            parsed.packages.filter((p): p is string => typeof p === 'string'),
+          )
+          return _cachedBrowserPackages
+        }
+      } catch {
+        // fall through to empty-list fallback
+      }
+      break
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  _cachedBrowserPackages = new Set()
+  return _cachedBrowserPackages
+}
+
+/**
+ * Test-only: reset the cached list so unit tests can exercise the
+ * filesystem-discovery path multiple times within one process.
+ */
+export function _resetBrowserPackagesCache(): void {
+  _cachedBrowserPackages = null
+}
+
+/**
+ * Walk a directory looking for `*.browser.test.{ts,tsx}` files. Bails
+ * on the first match — we only need to know `at least one exists`,
+ * not enumerate them. Skips `node_modules`, `lib`, `dist`, and dot
+ * directories so a package's own dependencies don't pollute the check.
+ */
+function hasBrowserTest(dir: string): boolean {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return false
+  }
+  for (const name of entries) {
+    if (name.startsWith('.') || name === 'node_modules' || name === 'lib' || name === 'dist') {
+      continue
+    }
+    const full = path.join(dir, name)
+    let isDir = false
+    try {
+      isDir = statSync(full).isDirectory()
+    } catch {
+      continue
+    }
+    if (isDir) {
+      if (hasBrowserTest(full)) return true
+      continue
+    }
+    if (/\.browser\.test\.(?:ts|tsx)$/.test(name)) return true
+  }
+  return false
+}
+
+/**
+ * Read the package.json `name` field for the directory containing the
+ * given src/index.ts file. Returns null if not found.
+ */
+function readPackageName(srcIndexPath: string): string | null {
+  // src/index.ts -> ../package.json
+  const pkgPath = path.resolve(path.dirname(srcIndexPath), '..', 'package.json')
+  if (!existsSync(pkgPath)) return null
+  try {
+    // Read synchronously; cheap for one file per package per lint run.
+    const text = require('node:fs').readFileSync(pkgPath, 'utf8') as string
+    const parsed = JSON.parse(text) as { name?: unknown }
+    return typeof parsed.name === 'string' ? parsed.name : null
+  } catch {
+    return null
+  }
+}
+
+export const requireBrowserSmokeTest: Rule = {
+  meta: {
+    id: 'pyreon/require-browser-smoke-test',
+    category: 'architecture',
+    description:
+      'Every browser-categorized package must ship at least one `*.browser.test.{ts,tsx}` file under `src/`. Locks in the T1.1 browser smoke harness.',
+    severity: 'error',
+    fixable: false,
+    schema: {
+      additionalPackages: 'string[]',
+      exemptPaths: 'string[]',
+    },
+  },
+  create(context): VisitorCallbacks {
+    const filePath = context.getFilePath()
+
+    // Run exactly once per package: only on `<package>/src/index.ts`
+    // (or .tsx). Test files in the package are excluded automatically
+    // because they don't match this pattern.
+    if (
+      !filePath.endsWith('/src/index.ts') &&
+      !filePath.endsWith('/src/index.tsx')
+    ) {
+      return {}
+    }
+
+    if (isPathExempt(context)) return {}
+
+    const pkgName = readPackageName(filePath)
+    if (pkgName == null) return {}
+
+    const options = context.getOptions()
+    const additional = Array.isArray(options.additionalPackages)
+      ? (options.additionalPackages.filter((s) => typeof s === 'string') as string[])
+      : []
+    const browserPackages = new Set(loadBrowserPackages(filePath))
+    for (const p of additional) browserPackages.add(p)
+
+    if (!browserPackages.has(pkgName)) return {}
+
+    const pkgDir = path.dirname(path.dirname(filePath)) // strip /src/index.ts
+    if (hasBrowserTest(pkgDir)) return {}
+
+    return {
+      'Program:exit'(node: { start?: number; end?: number }) {
+        context.report({
+          message:
+            `[Pyreon] Browser-categorized package "${pkgName}" has no \`*.browser.test.{ts,tsx}\` file. ` +
+            `Add at least one real-browser smoke test under \`src/\` to catch environment-divergence bugs ` +
+            `that happy-dom hides (typeof process dead code, real pointer events, computed styles, etc.). ` +
+            `See .claude/rules/test-environment-parity.md for the recipe.`,
+          span: { start: node.start ?? 0, end: node.end ?? 0 },
+        })
+      },
+    }
+  },
+}

package/src/rules/form/no-submit-without-validation.ts

@@ -1,5 +1,6 @@
 import type { Rule, VisitorCallbacks } from '../../types'
 import { getSpan, isCallTo } from '../../utils/ast'
+import { isTestFile } from '../../utils/file-roles'
 
 export const noSubmitWithoutValidation: Rule = {
   meta: {
@@ -10,6 +11,14 @@ export const noSubmitWithoutValidation: Rule = {
     fixable: false,
   },
   create(context) {
+    // Heuristic: skip test files. The rule fires on any `useForm({ onSubmit })`
+    // missing validators, but tests deliberately exercise the un-validated
+    // path. A truly precise check would need to detect "this `useForm` is
+    // a test stub vs a real production form" — impractical at lint level.
+    // Keep the heuristic; consumers who want to test forms with validation
+    // explicitly opted-out should use `// pyreon-lint-disable-next-line`.
+    if (isTestFile(context.getFilePath())) return {}
+
     const callbacks: VisitorCallbacks = {
       CallExpression(node: any) {
         if (!isCallTo(node, 'useForm')) return

package/src/rules/form/no-unregistered-field.ts

@@ -1,5 +1,6 @@
 import type { Rule, VisitorCallbacks } from '../../types'
 import { getSpan, isCallTo } from '../../utils/ast'
+import { isTestFile } from '../../utils/file-roles'
 
 export const noUnregisteredField: Rule = {
   meta: {
@@ -10,6 +11,14 @@ export const noUnregisteredField: Rule = {
     fixable: false,
   },
   create(context) {
+    // Heuristic: skip test files. The rule fires when `useField()` is
+    // called but no matching `register()` is found — usually a real bug
+    // (the field is dead). But form tests routinely call `useField` to
+    // assert field state without rendering a real DOM input. A precise
+    // check would need to detect "the return is not destructured into
+    // props passed to a JSX element" — impractical at lint level.
+    if (isTestFile(context.getFilePath())) return {}
+
     const fieldDecls = new Map<string, { span: { start: number; end: number } }>()
     const registeredNames = new Set<string>()
 

package/src/rules/hooks/no-raw-addeventlistener.ts

@@ -1,5 +1,6 @@
 import type { Rule, VisitorCallbacks } from '../../types'
 import { getSpan } from '../../utils/ast'
+import { isPathExempt } from '../../utils/exempt-paths'
 
 export const noRawAddEventListener: Rule = {
   meta: {
@@ -8,8 +9,14 @@ export const noRawAddEventListener: Rule = {
     description: 'Suggest useEventListener() instead of raw .addEventListener() calls.',
     severity: 'info',
     fixable: false,
+    schema: { exemptPaths: 'string[]' },
   },
   create(context) {
+    // Configurable `exemptPaths` — for packages that IMPLEMENT the cleanup
+    // wrapper this rule recommends (they can't use themselves). Configure
+    // per-project; user apps typically leave empty.
+    if (isPathExempt(context)) return {}
+
     const callbacks: VisitorCallbacks = {
       CallExpression(node: any) {
         const callee = node.callee

package/src/rules/hooks/no-raw-localstorage.ts

@@ -1,5 +1,6 @@
 import type { Rule, VisitorCallbacks } from '../../types'
 import { getSpan } from '../../utils/ast'
+import { createComponentContextTracker } from '../../utils/component-context'
 
 const STORAGE_OBJECTS = new Set(['localStorage', 'sessionStorage'])
 const STORAGE_METHODS = new Set(['getItem', 'setItem', 'removeItem'])
@@ -8,13 +9,23 @@ export const noRawLocalStorage: Rule = {
   meta: {
     id: 'pyreon/no-raw-localstorage',
     category: 'hooks',
-    description: 'Suggest useStorage() instead of raw localStorage/sessionStorage access.',
+    description:
+      'Suggest useStorage() instead of raw localStorage/sessionStorage inside a component or hook.',
     severity: 'info',
     fixable: false,
   },
   create(context) {
+    // The rule's premise — "use the reactive, cross-tab synced wrapper" —
+    // only applies inside a component / hook. Module-level config readers,
+    // utility helpers, and storage-library internals legitimately use the
+    // raw API. Foundation-package opt-out (e.g. `@pyreon/storage` itself)
+    // belongs in the consuming project's lint config, not in rule source.
+    const ctx = createComponentContextTracker()
+
     const callbacks: VisitorCallbacks = {
+      ...ctx.callbacks,
       CallExpression(node: any) {
+        if (!ctx.isInComponentOrHook()) return
         const callee = node.callee
         if (!callee || callee.type !== 'MemberExpression') return
         if (