@pyreon/lint 0.12.13 → 0.12.14

package/src/types.ts

@@ -42,23 +42,64 @@ export type RuleCategory =
   | 'accessibility'
   | 'router'
 
+/**
+ * Declared type of an option slot. Minimal on purpose — sufficient for
+ * the exemption patterns we actually use. Extend when a rule needs more.
+ */
+export type OptionType = 'string' | 'string[]' | 'number' | 'boolean'
+
+/**
+ * Schema for a rule's options bag — keys are option names, values are
+ * their declared types. Unknown keys in user config emit a warning;
+ * wrong-typed values disable the rule and emit an error. Rules with no
+ * schema accept any options (no validation).
+ */
+export type RuleOptionsSchema = Record<string, OptionType>
+
 export interface RuleMeta {
   id: string
   category: RuleCategory
   description: string
   severity: Severity
   fixable: boolean
+  /**
+   * Declared options shape. Validated once when a config enables the rule;
+   * bad options either get reported (unknown key → warn, wrong type →
+   * error + rule disabled for that run).
+   */
+  schema?: RuleOptionsSchema
 }
 
+// ── Rule Options ────────────────────────────────────────────────────────────
+//
+// Rules can be configured with an options object in addition to severity.
+// This lets users opt files out of a rule without hardcoding paths in the
+// rule source (which would ship to every consuming project).
+//
+// Convention: rules that support path-based exemption read
+// `options.exemptPaths: string[]` — each entry is a substring matched
+// against the file path. See `utils/exempt-paths.ts` for the helper.
+
+export type RuleOptions = Record<string, unknown>
+
 // ── Rule Context & Visitor ──────────────────────────────────────────────────
 
 export interface RuleContext {
   report(diagnostic: Omit<Diagnostic, 'ruleId' | 'severity' | 'loc'>): void
   getSourceText(): string
   getFilePath(): string
+  /** Options passed via config (tuple form: `[severity, options]`). */
+  getOptions(): RuleOptions
 }
 
-export type VisitorCallback = (node: any, parent?: any) => void
+/**
+ * Visitor callback. oxc's walker only passes the current node — it does NOT
+ * pass `parent`. Rules that need parent context must track it via
+ * enter/exit depth counters or pre-mark child nodes via WeakSet on the way
+ * in. An earlier `parent?: any` signature here was a false promise that
+ * silently disabled `parent.type === '…'` checks across multiple rules.
+ */
+export type VisitorCallback = (node: any) => void
 
 export interface VisitorCallbacks {
   [nodeType: string]: VisitorCallback
@@ -73,15 +114,25 @@ export interface Rule {
 
 // ── Configuration ───────────────────────────────────────────────────────────
 
+/**
+ * A rule entry is either a bare severity (`"error"`, `"warn"`, `"info"`,
+ * `"off"`) or a tuple `[severity, options]`. The tuple form lets consumers
+ * pass per-rule options without a bespoke API per rule.
+ *
+ *   "pyreon/no-window-in-ssr": "error"
+ *   "pyreon/no-window-in-ssr": ["error", { "exemptPaths": ["packages/core/runtime-dom/"] }]
+ */
+export type RuleEntry = Severity | readonly [Severity, RuleOptions]
+
 export interface LintConfig {
-  rules: Record<string, Severity>
+  rules: Record<string, RuleEntry>
   include?: string[] | undefined
   exclude?: string[] | undefined
 }
 
 export interface LintConfigFile {
   preset?: PresetName | undefined
-  rules?: Record<string, Severity> | undefined
+  rules?: Record<string, RuleEntry> | undefined
   include?: string[] | undefined
   exclude?: string[] | undefined
 }
@@ -96,11 +147,25 @@ export interface LintFileResult {
   fixedSource?: string | undefined
 }
 
+/**
+ * Config-level diagnostic — emitted by `validateRuleOptions` when a rule's
+ * configured options don't match its declared `schema`. Not tied to a
+ * source file; lives on `LintResult.configDiagnostics` so programmatic
+ * consumers (CI, LSP, JSON reporters) surface them alongside file diags.
+ */
+export interface ConfigDiagnostic {
+  ruleId: string
+  severity: 'error' | 'warn'
+  message: string
+}
+
 export interface LintResult {
   files: LintFileResult[]
   totalErrors: number
   totalWarnings: number
   totalInfos: number
+  /** Config-level diagnostics (malformed rule options, etc.). */
+  configDiagnostics: ConfigDiagnostic[]
 }
 
 // ── Lint Options ────────────────────────────────────────────────────────────
@@ -111,6 +176,12 @@ export interface LintOptions {
   fix?: boolean | undefined
   quiet?: boolean | undefined
   ruleOverrides?: Record<string, Severity> | undefined
+  /**
+   * Per-rule options overrides — typically populated from the
+   * `--rule-options id='{json}'` CLI flag. Merged on top of any
+   * options coming from the config file's tuple form.
+   */
+  ruleOptionsOverrides?: Record<string, RuleOptions> | undefined
   config?: string | undefined
   ignore?: string | undefined
 }

package/src/utils/component-context.ts

@@ -0,0 +1,106 @@
+/**
+ * Component / hook scope tracker for lint rules.
+ *
+ * Many rules in this package only matter *inside* a component or hook —
+ * e.g. `no-raw-setinterval` wants you to wrap timers in `onMount` so they
+ * are cleaned up when the component unmounts. A `setInterval` at module
+ * scope, in a utility function, or inside a test callback has its own
+ * lifecycle and doesn't need component-tied cleanup.
+ *
+ * Previously these rules used a path-string `isTestFile()` skip as a
+ * proxy for "outside component context". That's a heuristic — it
+ * accidentally exempts test files where the pattern *is* still wrong,
+ * and it accidentally fires on utility/library files where the pattern
+ * is fine.
+ *
+ * This tracker maintains a "component depth" counter via visitor
+ * callbacks. A function counts as a component or hook when its name
+ * follows the framework's naming conventions:
+ *   - `MyThing` (PascalCase) → component
+ *   - `useThing` (camelCase, `use` prefix + uppercase next char) → hook
+ *
+ * Rules consume it via `createComponentContextTracker()` and merge the
+ * returned `callbacks` into their visitor:
+ *
+ *   ```ts
+ *   create(context) {
+ *     const ctx = createComponentContextTracker()
+ *     return {
+ *       ...ctx.callbacks,
+ *       CallExpression(node) {
+ *         if (!ctx.isInComponentOrHook()) return
+ *         // ... existing rule logic ...
+ *       },
+ *     }
+ *   }
+ *   ```
+ *
+ * The tracker also recognizes named arrow / function expressions assigned
+ * to `const X = (props) => …`, since the framework treats those as
+ * components too. Anonymous callbacks (e.g. `it('...', () => { … })`,
+ * `setTimeout(() => { … }, 0)`, `arr.map(x => x)`) never push depth — so
+ * test bodies, IIFEs, and inline callbacks are correctly seen as
+ * "outside any component" without needing a path-based skip.
+ */
+
+import type { VisitorCallbacks } from '../types'
+
+const COMPONENT_NAME = /^[A-Z]/
+const HOOK_NAME = /^use[A-Z]/
+
+export function isComponentOrHookName(name: string | null | undefined): boolean {
+  if (!name) return false
+  return COMPONENT_NAME.test(name) || HOOK_NAME.test(name)
+}
+
+export interface ComponentContextTracker {
+  /** True iff the current AST position is inside a function recognised as a component or hook. */
+  isInComponentOrHook(): boolean
+  /**
+   * Visitor callbacks that maintain the depth counter. Spread them into the
+   * rule's returned visitor first; per-node listeners after override only
+   * the keys the rule itself implements (FunctionDeclaration etc. rarely).
+   */
+  callbacks: VisitorCallbacks
+}
+
+export function createComponentContextTracker(): ComponentContextTracker {
+  let depth = 0
+
+  // For arrow / function expressions assigned to a `const X = (...) => …`,
+  // we can't read the binding name from the function node — and the oxc
+  // visitor doesn't pass `parent` to callbacks. Instead, hook the parent
+  // `VariableDeclarator` enter/exit: it visits BEFORE its `init` child
+  // (the function expression) and EXITS AFTER, so a depth bump tied to
+  // the declarator correctly brackets the function body.
+  function declaratorIsComponentOrHook(node: any): boolean {
+    if (node?.id?.type !== 'Identifier') return false
+    const init = node.init
+    if (
+      init?.type !== 'ArrowFunctionExpression' &&
+      init?.type !== 'FunctionExpression'
+    )
+      return false
+    return isComponentOrHookName(node.id.name)
+  }
+
+  return {
+    isInComponentOrHook: () => depth > 0,
+    callbacks: {
+      // function MyComp() {} / function useFoo() {}
+      FunctionDeclaration(node: any) {
+        if (isComponentOrHookName(node.id?.name)) depth++
+      },
+      'FunctionDeclaration:exit'(node: any) {
+        if (isComponentOrHookName(node.id?.name)) depth--
+      },
+      // const MyComp = () => {} / const useFoo = function () {}
+      VariableDeclarator(node: any) {
+        if (declaratorIsComponentOrHook(node)) depth++
+      },
+      'VariableDeclarator:exit'(node: any) {
+        if (declaratorIsComponentOrHook(node)) depth--
+      },
+    },
+  }
+}

package/src/utils/exempt-paths.ts

@@ -0,0 +1,39 @@
+/**
+ * Helper for rules that support path-based exemption via options.
+ *
+ * Rules that need to be "turn-off-able for specific directories" (e.g.
+ * a package that IS the foundation the rule recommends against using
+ * directly) don't hardcode the paths anymore — they read an
+ * `exemptPaths: string[]` option from the user's config:
+ *
+ *   ```json
+ *   // .pyreonlintrc.json
+ *   {
+ *     "rules": {
+ *       "pyreon/no-window-in-ssr": [
+ *         "error",
+ *         { "exemptPaths": ["packages/core/runtime-dom/"] }
+ *       ]
+ *     }
+ *   }
+ *   ```
+ *
+ * Each entry is substring-matched against the file path (same convention
+ * the old hardcoded patterns used). Empty / missing → no exemptions,
+ * which is the correct default for a rule shipping to user apps.
+ */
+
+import type { RuleContext } from '../types'
+
+export function isPathExempt(ctx: RuleContext): boolean {
+  const options = ctx.getOptions()
+  const raw = options.exemptPaths
+  if (!Array.isArray(raw) || raw.length === 0) return false
+  const filePath = ctx.getFilePath()
+  for (const entry of raw) {
+    if (typeof entry === 'string' && entry.length > 0 && filePath.includes(entry)) {
+      return true
+    }
+  }
+  return false
+}

package/src/utils/file-roles.ts

@@ -0,0 +1,32 @@
+/**
+ * Universal file-path classifiers for lint rules.
+ *
+ * What belongs here:
+ *   - Conventions that exist in every project the linter runs on
+ *     (test files, example directories — the `*.test.*` convention
+ *     is not Pyreon-specific).
+ *
+ * What does NOT belong here:
+ *   - Monorepo-specific paths like `packages/core/runtime-dom/` —
+ *     those are implementation knowledge of one particular codebase
+ *     and have no meaning in a user's app. Exemptions for such paths
+ *     belong in the consuming project's lint config via the
+ *     `exemptPaths: string[]` rule option — see `utils/exempt-paths.ts`
+ *     and the Pyreon monorepo's `.pyreonlintrc.json` at repo root for
+ *     reference.
+ */
+
+/**
+ * Matches files that are tests by convention. Universal — the
+ * `*.test.*` / `*.spec.*` / `/tests/` / `/__tests__/` conventions
+ * exist in every codebase this linter runs on, not just Pyreon.
+ */
+export function isTestFile(filePath: string): boolean {
+  return (
+    filePath.includes('/tests/') ||
+    filePath.includes('/test/') ||
+    filePath.includes('/__tests__/') ||
+    filePath.includes('.test.') ||
+    filePath.includes('.spec.')
+  )
+}

package/src/utils/imports.ts

@@ -48,7 +48,10 @@ export const BROWSER_GLOBALS = new Set([
   'localStorage',
   'sessionStorage',
   'indexedDB',
-  'fetch',
+  // NOTE: `fetch` is intentionally OMITTED — it's a universal global in
+  // Node 18+, Bun, Deno, browsers, and edge runtimes. Code using it isn't
+  // browser-specific. (`XMLHttpRequest`/`WebSocket` are still here because
+  // they're DOM-only and Node code uses different libraries.)
   'XMLHttpRequest',
   'WebSocket',
   'requestAnimationFrame',

package/src/utils/validate-options.ts

@@ -0,0 +1,68 @@
+/**
+ * Validate a rule's user-configured options against its declared schema.
+ *
+ * Called once per (rule, options) pair at config-merge time — NOT per
+ * lint'd file. Separates config problems from source-code problems:
+ * wrong-typed options aren't a file diagnostic, they're a setup error
+ * for the tool.
+ *
+ * Return shape:
+ *   - `errors`:   hard failures. Runner disables the rule for this run.
+ *   - `warnings`: unknown option keys, typos, etc. Runner keeps the
+ *                 rule enabled but prints the warning so the user knows.
+ *
+ * Rules without `meta.schema` accept any options (no validation).
+ */
+
+import type { OptionType, Rule, RuleOptions, RuleOptionsSchema } from '../types'
+
+export interface ValidationResult {
+  errors: string[]
+  warnings: string[]
+}
+
+export function validateRuleOptions(rule: Rule, options: RuleOptions): ValidationResult {
+  const schema = rule.meta.schema
+  const errors: string[] = []
+  const warnings: string[] = []
+  if (!schema) return { errors, warnings }
+
+  for (const [key, value] of Object.entries(options)) {
+    const expected = schema[key]
+    if (expected === undefined) {
+      warnings.push(
+        `[${rule.meta.id}] unknown option "${key}" — allowed options: ${Object.keys(schema).join(', ') || '(none)'}`,
+      )
+      continue
+    }
+    if (!matchesType(value, expected)) {
+      errors.push(
+        `[${rule.meta.id}] option "${key}" must be ${expected}, got ${describe(value)}`,
+      )
+    }
+  }
+
+  return { errors, warnings }
+}
+
+function matchesType(value: unknown, type: OptionType): boolean {
+  switch (type) {
+    case 'string':
+      return typeof value === 'string'
+    case 'string[]':
+      return Array.isArray(value) && value.every((x) => typeof x === 'string')
+    case 'number':
+      return typeof value === 'number' && Number.isFinite(value)
+    case 'boolean':
+      return typeof value === 'boolean'
+  }
+}
+
+function describe(value: unknown): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) {
+    const types = new Set(value.map((x) => (x === null ? 'null' : typeof x)))
+    return `Array<${[...types].join(' | ') || 'empty'}>`
+  }
+  return typeof value
+}

package/src/watcher.ts

@@ -34,6 +34,7 @@ export function watchAndLint(options: LintOptions & { format: string }): void {
   const config = getPreset(preset)
 
   applyOverrides(config, options.ruleOverrides)
+  applyOptionsOverrides(config, options.ruleOptionsOverrides)
 
   const cwd = resolve('.')
   const isIgnored = createIgnoreFilter(cwd, options.ignore)
@@ -81,6 +82,21 @@ function applyOverrides(
   }
 }
 
+function applyOptionsOverrides(
+  config: LintConfig,
+  overrides?: Record<string, Record<string, unknown>> | undefined,
+): void {
+  if (!overrides) return
+  for (const [id, opts] of Object.entries(overrides)) {
+    const existing = config.rules[id]
+    const [severity, current]: [Severity, Record<string, unknown>] = Array.isArray(existing)
+      ? [existing[0] as Severity, (existing[1] ?? {}) as Record<string, unknown>]
+      : [(existing ?? 'off') as Severity, {}]
+    if (severity === 'off') continue
+    config.rules[id] = [severity, { ...current, ...opts }] as const
+  }
+}
+
 function relintFile(filePath: string, config: LintConfig, cache: AstCache, format: string): void {
   let source: string
   try {
@@ -98,6 +114,7 @@ function relintFile(filePath: string, config: LintConfig, cache: AstCache, forma
     totalErrors: 0,
     totalWarnings: 0,
     totalInfos: 0,
+    configDiagnostics: [],
   }
 
   for (const d of fileResult.diagnostics) {