@pyreon/lint 0.12.12 → 0.12.14

package/lib/types/index.d.ts

@@ -21,19 +21,47 @@ interface Diagnostic {
   fix?: Fix | undefined;
 }
 type RuleCategory = 'reactivity' | 'jsx' | 'lifecycle' | 'performance' | 'ssr' | 'architecture' | 'store' | 'form' | 'styling' | 'hooks' | '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.
+ */
+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).
+ */
+type RuleOptionsSchema = Record<string, OptionType>;
 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;
 }
+type RuleOptions = Record<string, unknown>;
 interface RuleContext {
   report(diagnostic: Omit<Diagnostic, 'ruleId' | 'severity' | 'loc'>): void;
   getSourceText(): string;
   getFilePath(): string;
+  /** Options passed via config (tuple form: `[severity, options]`). */
+  getOptions(): RuleOptions;
 }
-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.
+ */
+type VisitorCallback = (node: any) => void;
 interface VisitorCallbacks {
   [nodeType: string]: VisitorCallback;
 }
@@ -41,14 +69,23 @@ interface Rule {
   meta: RuleMeta;
   create(context: RuleContext): VisitorCallbacks;
 }
+/**
+ * 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/"] }]
+ */
+type RuleEntry = Severity | readonly [Severity, RuleOptions];
 interface LintConfig {
-  rules: Record<string, Severity>;
+  rules: Record<string, RuleEntry>;
   include?: string[] | undefined;
   exclude?: string[] | undefined;
 }
 interface LintConfigFile {
   preset?: PresetName | undefined;
-  rules?: Record<string, Severity> | undefined;
+  rules?: Record<string, RuleEntry> | undefined;
   include?: string[] | undefined;
   exclude?: string[] | undefined;
 }
@@ -58,11 +95,24 @@ interface LintFileResult {
   diagnostics: Diagnostic[];
   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.
+ */
+interface ConfigDiagnostic {
+  ruleId: string;
+  severity: 'error' | 'warn';
+  message: string;
+}
 interface LintResult {
   files: LintFileResult[];
   totalErrors: number;
   totalWarnings: number;
   totalInfos: number;
+  /** Config-level diagnostics (malformed rule options, etc.). */
+  configDiagnostics: ConfigDiagnostic[];
 }
 interface LintOptions {
   paths: string[];
@@ -70,6 +120,12 @@ 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;
 }
@@ -212,24 +268,6 @@ declare function formatJSON(result: LintResult): string;
 declare function formatCompact(result: LintResult): string;
 //#endregion
 //#region src/lsp/index.d.ts
-/**
- * Minimal LSP server for @pyreon/lint.
- *
- * Provides real-time Pyreon-specific diagnostics in editors that support
- * the Language Server Protocol (VS Code, Neovim, etc.).
- *
- * Usage: pyreon-lint --lsp
- *
- * The server communicates via JSON-RPC over stdin/stdout following the
- * LSP specification (https://microsoft.github.io/language-server-protocol/).
- *
- * Supported capabilities:
- * - textDocument/didOpen — lint on open
- * - textDocument/didSave — lint on save
- * - textDocument/didChange — lint on change (debounced)
- *
- * @module
- */
 /**
  * Start the LSP server. Reads JSON-RPC messages from stdin,
  * processes them, and writes responses to stdout.
@@ -249,13 +287,48 @@ declare const allRules: Rule[];
  * for (const d of result.diagnostics) console.log(d.message)
  * ```
  */
-declare function lintFile(filePath: string, sourceText: string, rules: Rule[], config: LintConfig, cache?: AstCache | undefined): LintFileResult;
+declare function lintFile(filePath: string, sourceText: string, rules: Rule[], config: LintConfig, cache?: AstCache | undefined,
+/**
+ * Optional sink for config-level diagnostics (malformed rule options).
+ * When provided, diagnostics are appended to it instead of printed to
+ * stderr — `lint()` uses this to surface them on `LintResult`.
+ */
+
+configDiagnosticsSink?: ConfigDiagnostic[]): LintFileResult;
 /**
  * Apply all auto-fixes to a source text.
  * Fixes are applied in reverse order to maintain correct offsets.
  */
 declare function applyFixes(sourceText: string, diagnostics: Diagnostic[]): string;
 //#endregion
+//#region src/utils/exempt-paths.d.ts
+declare function isPathExempt(ctx: RuleContext): boolean;
+//#endregion
+//#region src/utils/file-roles.d.ts
+/**
+ * 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.
+ */
+declare function isTestFile(filePath: string): boolean;
+//#endregion
 //#region src/utils/imports.d.ts
 declare function isPyreonImport(source: string): boolean;
 declare function isPyreonPackage(source: string): boolean;
@@ -281,5 +354,5 @@ declare function watchAndLint(options: LintOptions & {
   format: string;
 }): void;
 //#endregion
-export { AstCache, type Diagnostic, type Fix, type ImportInfo, LineIndex, type LintConfig, type LintConfigFile, type LintFileResult, type LintOptions, type LintResult, type PresetName, type Rule, type RuleCategory, type RuleContext, type RuleMeta, type Severity, type SourceLocation, type Span, type VisitorCallbacks, allRules, applyFixes, createIgnoreFilter, extractImportInfo, formatCompact, formatJSON, formatText, getLocalName, getPreset, importsName, isPyreonImport, isPyreonPackage, lint, lintFile, listRules, loadConfig, loadConfigFromPath, startLspServer, watchAndLint };
+export { AstCache, type ConfigDiagnostic, type Diagnostic, type Fix, type ImportInfo, LineIndex, type LintConfig, type LintConfigFile, type LintFileResult, type LintOptions, type LintResult, type OptionType, type PresetName, type Rule, type RuleCategory, type RuleContext, type RuleEntry, type RuleMeta, type RuleOptions, type RuleOptionsSchema, type Severity, type SourceLocation, type Span, type VisitorCallbacks, allRules, applyFixes, createIgnoreFilter, extractImportInfo, formatCompact, formatJSON, formatText, getLocalName, getPreset, importsName, isPathExempt, isPyreonImport, isPyreonPackage, isTestFile, lint, lintFile, listRules, loadConfig, loadConfigFromPath, startLspServer, watchAndLint };
 //# sourceMappingURL=index2.d.ts.map

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/types.ts","../../../src/utils/source.ts","../../../src/cache.ts","../../../src/config/ignore.ts","../../../src/config/loader.ts","../../../src/config/presets.ts","../../../src/lint.ts","../../../src/reporter.ts","../../../src/lsp/index.ts","../../../src/rules/index.ts","../../../src/runner.ts","../../../src/utils/imports.ts","../../../src/watcher.ts"],"mappings":"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"}
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/types.ts","../../../src/utils/source.ts","../../../src/cache.ts","../../../src/config/ignore.ts","../../../src/config/loader.ts","../../../src/config/presets.ts","../../../src/lint.ts","../../../src/reporter.ts","../../../src/lsp/index.ts","../../../src/rules/index.ts","../../../src/runner.ts","../../../src/utils/exempt-paths.ts","../../../src/utils/file-roles.ts","../../../src/utils/imports.ts","../../../src/watcher.ts"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/lint",
-  "version": "0.12.12",
+  "version": "0.12.14",
   "description": "Pyreon-specific linter — 56 rules for signals, JSX, SSR, performance, router, and architecture",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/lint#readme",
   "bugs": {
@@ -18,6 +18,7 @@
   "files": [
     "lib",
     "src",
+    "schema",
     "README.md",
     "LICENSE"
   ],

package/schema/pyreonlintrc.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://pyreon.dev/schemas/pyreonlintrc.json",
+  "title": "@pyreon/lint configuration",
+  "description": "Schema for .pyreonlintrc.json — configures the @pyreon/lint linter. Reference this in your config via `\"$schema\": \"./node_modules/@pyreon/lint/schema/pyreonlintrc.schema.json\"` for IDE autocomplete + validation.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "preset": {
+      "description": "Base preset to extend. Recommended is the safe default. Use `lib` for strict mode + architecture rules; `app` to disable lib-only rules.",
+      "enum": ["recommended", "strict", "app", "lib"]
+    },
+    "rules": {
+      "description": "Per-rule configuration. Each entry is either a bare severity (`\"error\"` / `\"warn\"` / `\"info\"` / `\"off\"`) or an `[severity, options]` tuple. Rules that support path-based exemption read `options.exemptPaths: string[]`.",
+      "type": "object",
+      "patternProperties": {
+        "^.+$": {
+          "oneOf": [
+            { "$ref": "#/definitions/severity" },
+            {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 2,
+              "items": [
+                { "$ref": "#/definitions/severity" },
+                { "$ref": "#/definitions/ruleOptions" }
+              ]
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "include": {
+      "description": "Glob patterns of files to lint (relative to the config file).",
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "exclude": {
+      "description": "Glob patterns of files to skip (relative to the config file). `.pyreonlintignore` and `.gitignore` are honored automatically.",
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "definitions": {
+    "severity": {
+      "enum": ["error", "warn", "info", "off"],
+      "description": "Diagnostic severity. `off` disables the rule entirely."
+    },
+    "ruleOptions": {
+      "type": "object",
+      "description": "Per-rule options. Most rules support `exemptPaths: string[]` for path-based exemption (each entry is a substring matched against the file path).",
+      "properties": {
+        "exemptPaths": {
+          "description": "File-path substrings to exempt from this rule. Useful for foundation packages that legitimately implement what the rule recommends (e.g. a DOM renderer cannot use `useEventListener`).",
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/src/cli.ts

@@ -18,7 +18,8 @@ function printUsage() {
     --format <fmt>     Output: text (default), json, compact
     --quiet            Only show errors
     --list             List all available rules
-    --rule <id>=<sev>  Override rule severity
+    --rule <id>=<sev>          Override rule severity (e.g. --rule pyreon/no-window-in-ssr=off)
+    --rule-options <id>=<json> Override rule options (e.g. --rule-options pyreon/no-window-in-ssr='{"exemptPaths":["src/foundation/"]}')
     --config <path>    Config file path
     --ignore <path>    Ignore file path
     --watch            Watch mode — re-lint on file changes
@@ -57,6 +58,8 @@ interface CliArgs {
   configPath: string | undefined
   ignorePath: string | undefined
   ruleOverrides: Record<string, Severity>
+  /** Per-rule options parsed from `--rule-options id='{json}'`. */
+  ruleOptionsOverrides: Record<string, Record<string, unknown>>
   paths: string[]
 }
 
@@ -86,6 +89,7 @@ function parseArgs(argv: string[]): CliArgs {
     configPath: undefined,
     ignorePath: undefined,
     ruleOverrides: {},
+    ruleOptionsOverrides: {},
     paths: [],
   }
 
@@ -127,6 +131,10 @@ function parseValueFlag(arg: string, nextArg: string | undefined, result: CliArg
     parseRuleOverride(nextArg, result.ruleOverrides)
     return 1
   }
+  if (arg === '--rule-options') {
+    parseRuleOptionsOverride(nextArg, result.ruleOptionsOverrides)
+    return 1
+  }
   if (arg) {
     result.paths.push(arg)
   }
@@ -142,6 +150,32 @@ function parseRuleOverride(val: string | undefined, overrides: Record<string, Se
   overrides[ruleId] = severity
 }
 
+/** Exported for testing only. */
+export function parseRuleOptionsOverride(
+  val: string | undefined,
+  overrides: Record<string, Record<string, unknown>>,
+): void {
+  if (!val) return
+  const eqIdx = val.indexOf('=')
+  if (eqIdx === -1) return
+  const ruleId = val.slice(0, eqIdx)
+  const json = val.slice(eqIdx + 1)
+  try {
+    const parsed = JSON.parse(json)
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      overrides[ruleId] = parsed as Record<string, unknown>
+    } else {
+      // oxlint-disable-next-line no-console
+      console.error(
+        `[pyreon-lint] --rule-options ${ruleId}: expected JSON object, got ${typeof parsed}`,
+      )
+    }
+  } catch (err) {
+    // oxlint-disable-next-line no-console
+    console.error(`[pyreon-lint] --rule-options ${ruleId}: invalid JSON — ${(err as Error).message}`)
+  }
+}
+
 function main() {
   const args = parseArgs(process.argv.slice(2))
 
@@ -176,6 +210,7 @@ function main() {
       fix: args.fix,
       quiet: args.quiet,
       ruleOverrides: args.ruleOverrides,
+      ruleOptionsOverrides: args.ruleOptionsOverrides,
       config: args.configPath,
       ignore: args.ignorePath,
       format: args.format,
@@ -189,6 +224,7 @@ function main() {
     fix: args.fix,
     quiet: args.quiet,
     ruleOverrides: args.ruleOverrides,
+    ruleOptionsOverrides: args.ruleOptionsOverrides,
     config: args.configPath,
     ignore: args.ignorePath,
   })
@@ -207,4 +243,10 @@ function main() {
   }
 }
 
-main()
+// Only invoke `main()` when this module is the entry point. Importing
+// CLI internals from tests must NOT trigger a real lint run +
+// `process.exit`. `import.meta.main === true` under Bun when the file
+// is the script; `undefined` / `false` under static imports.
+if ((import.meta as { main?: boolean }).main === true) {
+  main()
+}

package/src/config/presets.ts

@@ -10,11 +10,18 @@ function buildRecommended(): LintConfig {
   return { rules }
 }
 
+function severityOf(entry: LintConfig['rules'][string]): Severity {
+  // Presets are built from bare severities (no tuple form). If a future
+  // preset adds tuple form, extract the severity from the tuple.
+  return Array.isArray(entry) ? (entry[0] as Severity) : (entry as Severity)
+}
+
 /** Build a config where every warn is promoted to error. */
 function buildStrict(): LintConfig {
   const base = buildRecommended()
   const rules: Record<string, Severity> = {}
-  for (const [id, sev] of Object.entries(base.rules)) {
+  for (const [id, entry] of Object.entries(base.rules)) {
+    const sev = severityOf(entry)
     rules[id] = sev === 'warn' ? 'error' : sev
   }
   return { rules }
@@ -30,6 +37,10 @@ function buildApp(): LintConfig {
       'pyreon/no-error-without-prefix': 'off',
       'pyreon/no-circular-import': 'off',
       'pyreon/no-cross-layer-import': 'off',
+      // `require-browser-smoke-test` is a per-package contract that
+      // applies to published libraries — apps don't ship as packages
+      // with smoke obligations.
+      'pyreon/require-browser-smoke-test': 'off',
       // `no-process-dev-gate` stays ON in `app` preset because the bug
       // hits user-facing browser code regardless of whether it's a lib
       // or an app.
@@ -48,6 +59,7 @@ function buildLib(): LintConfig {
       'pyreon/dev-guard-warnings': 'error',
       'pyreon/no-error-without-prefix': 'error',
       'pyreon/no-process-dev-gate': 'error',
+      'pyreon/require-browser-smoke-test': 'error',
     },
   }
 }

package/src/index.ts

@@ -12,6 +12,7 @@ export { allRules } from './rules/index'
 export { applyFixes, lintFile } from './runner'
 // Types
 export type {
+  ConfigDiagnostic,
   Diagnostic,
   Fix,
   ImportInfo,
@@ -20,16 +21,22 @@ export type {
   LintFileResult,
   LintOptions,
   LintResult,
+  OptionType,
   PresetName,
   Rule,
   RuleCategory,
   RuleContext,
+  RuleEntry,
   RuleMeta,
+  RuleOptions,
+  RuleOptionsSchema,
   Severity,
   SourceLocation,
   Span,
   VisitorCallbacks,
 } from './types'
+export { isPathExempt } from './utils/exempt-paths'
+export { isTestFile } from './utils/file-roles'
 export {
   extractImportInfo,
   getLocalName,

package/src/lint.ts

@@ -6,7 +6,16 @@ import { loadConfig, loadConfigFromPath } from './config/loader'
 import { getPreset } from './config/presets'
 import { allRules } from './rules/index'
 import { applyFixes, lintFile } from './runner'
-import type { LintConfig, LintFileResult, LintOptions, LintResult, RuleMeta } from './types'
+import type {
+  ConfigDiagnostic,
+  LintConfig,
+  LintFileResult,
+  LintOptions,
+  LintResult,
+  RuleMeta,
+  RuleOptions,
+  Severity,
+} from './types'
 import { hasJsExtension } from './utils/index'
 
 function isHiddenOrVendor(entry: string): boolean {
@@ -96,20 +105,40 @@ function buildConfig(options: LintOptions): {
   const presetName = options.preset ?? fileConfig?.preset ?? 'recommended'
   const config = getPreset(presetName)
 
-  // Merge config file rule overrides
+  // Merge config file rule overrides. Entries can be a bare severity or a
+  // `[severity, options]` tuple — passed through verbatim; the runner
+  // normalizes at use-site.
   if (fileConfig?.rules) {
-    for (const [id, severity] of Object.entries(fileConfig.rules)) {
-      config.rules[id] = severity
+    for (const [id, entry] of Object.entries(fileConfig.rules)) {
+      config.rules[id] = entry
     }
   }
 
-  // CLI rule overrides (highest priority)
+  // CLI rule severity overrides (highest priority for severity).
   if (options.ruleOverrides) {
     for (const [id, severity] of Object.entries(options.ruleOverrides)) {
       config.rules[id] = severity
     }
   }
 
+  // CLI rule options overrides (`--rule-options id='{json}'`). Merged
+  // on top of any options already configured for the rule. If the rule
+  // is currently bare-severity, we promote it to tuple form using its
+  // existing severity (or `recommended` default if not present).
+  if (options.ruleOptionsOverrides) {
+    for (const [id, optionOverrides] of Object.entries(options.ruleOptionsOverrides)) {
+      const existing = config.rules[id]
+      const [currentSeverity, currentOptions]: [Severity, RuleOptions] = Array.isArray(existing)
+        ? [existing[0] as Severity, (existing[1] ?? {}) as RuleOptions]
+        : [(existing ?? 'off') as Severity, {}]
+      if (currentSeverity === 'off') continue
+      config.rules[id] = [
+        currentSeverity,
+        { ...currentOptions, ...optionOverrides },
+      ] as const
+    }
+  }
+
   return {
     config,
     include: fileConfig?.include,
@@ -175,11 +204,13 @@ export function lint(options: LintOptions): LintResult {
   const cache = new AstCache()
   const files = gatherFiles(options.paths, isIgnored, include, exclude)
 
+  const configDiagnostics: ConfigDiagnostic[] = []
   const results: LintResult = {
     files: [],
     totalErrors: 0,
     totalWarnings: 0,
     totalInfos: 0,
+    configDiagnostics,
   }
 
   for (const filePath of files) {
@@ -189,7 +220,7 @@ export function lint(options: LintOptions): LintResult {
     } catch {
       continue
     }
-    const fileResult = lintFile(filePath, source, allRules, config, cache)
+    const fileResult = lintFile(filePath, source, allRules, config, cache, configDiagnostics)
     if (options.fix) {
       applyFixesToFile(fileResult, source)
     }

package/src/lsp/index.ts

@@ -20,11 +20,24 @@
 import { AstCache } from '../cache'
 import { getPreset } from '../config/presets'
 import { allRules } from '../rules/index'
-import { lintFile } from '../runner'
+import { _resetConfigDiagnosticsCache, lintFile } from '../runner'
 import type { Diagnostic, LintConfig } from '../types'
 
 const cache = new AstCache()
-const config: LintConfig = getPreset('recommended')
+let config: LintConfig = getPreset('recommended')
+
+/**
+ * Reload the LSP's lint config. Resets the runner's per-process
+ * validation cache so newly-configured options are re-validated against
+ * rule schemas on the next lint pass — needed when the user edits
+ * `.pyreonlintrc.json` mid-session. Future hookup point for an LSP
+ * `workspace/didChangeConfiguration` notification.
+ */
+export function _reloadConfig(next: LintConfig): void {
+  config = next
+  _resetConfigDiagnosticsCache()
+  cache.clear()
+}
 
 // ─── JSON-RPC message types ────────────────────────────────────────────────