@pyreon/lint is a framework-specific linter that catches Pyreon anti-patterns at the AST level — bare signal reads in JSX, props destructuring that breaks reactivity, browser globals in SSR code, bundler-coupled dev gates, and dozens more. It is powered by oxc-parser for fast ESTree/TS-ESTree parsing, ships a CLI (pyreon-lint), a programmatic API (lint / lintFile), watch mode, an AST cache, and an LSP server for editor integration.

It is complementary to oxlint/eslint, not a replacement: those catch general JS/TS issues; @pyreon/lint catches mistakes specific to Pyreon's signal model, JSX semantics, SSR contract, and package architecture. Every rule message is prescriptive — it states the fix — so the output is directly actionable by humans and AI assistants alike.

Installation

npm install -D @pyreon/lint

bun add -d @pyreon/lint

pnpm add -D @pyreon/lint

yarn add -D @pyreon/lint

Quick Start

# Lint the current directory with the recommended preset
pyreon-lint

# Strict mode for CI (warnings become errors), errors-only output
pyreon-lint --preset strict --quiet

# Auto-fix fixable issues
pyreon-lint --fix

# List every rule
pyreon-lint --list

Add it to your package.json scripts:

{
  "scripts": {
    "lint:pyreon": "pyreon-lint --preset recommended",
    "lint:pyreon:ci": "pyreon-lint --preset strict --quiet"
  }
}

pyreon-lint exits with code 1 when there are any errors (warnings and infos do not fail the process; use --preset strict to promote warnings to errors for CI gating).

CLI Usage

# Lint specific paths
pyreon-lint src/ app/

# Watch mode — re-lint on file changes
pyreon-lint --watch src/

# JSON output for tooling integration
pyreon-lint --format json

# Compact one-line-per-diagnostic output
pyreon-lint --format compact

# Override a specific rule's severity
pyreon-lint --rule pyreon/no-classname=off

# Override a rule's options (JSON object)
pyreon-lint --rule-options 'pyreon/no-window-in-ssr={"exemptPaths":["src/foundation/"]}' src/

# Use a custom config / ignore file
pyreon-lint --config ./custom-lint.json --ignore ./.customignore

# Start the LSP server (stdin/stdout JSON-RPC) for editor integration
pyreon-lint --lsp

Flags

Configuration

Config file

Create .pyreonlintrc.json in your project root:

{
  "$schema": "./node_modules/@pyreon/lint/schema/pyreonlintrc.schema.json",
  "preset": "recommended",
  "rules": {
    "pyreon/no-classname": "off",
    "pyreon/no-eager-import": "warn",
    "pyreon/no-window-in-ssr": [
      "error",
      { "exemptPaths": ["src/foundation/"] }
    ]
  },
  "include": ["src/"],
  "exclude": ["generated", ".test."]
}

The $schema reference enables IDE autocomplete + validation while editing the config in VSCode, IntelliJ, Zed, or any JSON-aware editor.

LintConfigFile shape

Rule entries

Each entry in rules is either a bare severity or a [severity, options] tuple (ESLint-style):

{
  "rules": {
    "pyreon/no-classname": "off",
    "pyreon/no-window-in-ssr": ["error", { "exemptPaths": ["packages/core/runtime-dom/"] }],
    "pyreon/require-browser-smoke-test": ["error", { "additionalPackages": ["@my-org/widgets"] }]
  }
}

Severities are "error", "warn", "info", or "off".

package.json field

Instead of a standalone file, you can put the config under a "pyreonlint" field in package.json:

{
  "pyreonlint": {
    "preset": "strict",
    "rules": {
      "pyreon/no-inline-style-object": "off"
    }
  }
}

Discovery order

loadConfig(cwd) walks up from the working directory toward the filesystem root, returning the first config it finds. Within each directory the search order is:

1. .pyreonlintrc.json

2. .pyreonlintrc

3. pyreonlint.config.json

4. package.json "pyreonlint" field

--config <path> bypasses the walk and loads that file directly.

Resolution precedence

For a single run, rule severity/options are resolved in this order (later wins):

1. The base preset (--preset flag → config-file preset → recommended)

2. Config-file rules entries

3. CLI --rule <id>=<sev> severity overrides / programmatic ruleOverrides

4. CLI --rule-options <id>=<json> options overrides / programmatic ruleOptionsOverrides

Per-rule options & exemptPaths

Several rules read an exemptPaths: string[] option — each entry is a substring matched against the file path, letting you opt specific files/directories out of a rule without hardcoding paths in the rule source (which would ship to every consuming project). Rules that honor exemptPaths today:

no-window-in-ssr, prefer-isserver, no-bare-signal-in-jsx, no-unbatched-updates, no-props-destructure, no-imperative-effect-on-create, no-heavy-import-only-in-handler, dev-guard-warnings, no-error-without-prefix, no-process-dev-gate, no-module-signal-in-server-package, no-query-selector-cast-in-test, require-browser-smoke-test, vitest-config-uses-shared, no-raw-addeventlistener, no-raw-setinterval, and every opt-in best-practice rule (frontend/*, query-options-as-function, rx-prefer-pipe, i18n-prefer-trans-for-rich-jsx, prefer-typed-search-params, no-storage-write-as-call, no-signal-in-form-initial-values).

require-browser-smoke-test additionally accepts additionalPackages: string[] to opt new browser packages into its coverage check.

{
  "rules": {
    "pyreon/no-window-in-ssr": ["error", { "exemptPaths": ["src/client-only/"] }]
  }
}

Option validation

Each rule that takes options declares an option shape in meta.schema (Record<string, 'string' | 'string[]' | 'number' | 'boolean'>). The runner validates user-supplied options once per (rule, options) pair:

• Unknown option key → a warn-severity config diagnostic; the rule still runs.

• Wrong-typed value → an error-severity config diagnostic; the rule is disabled for the run.

These config-level diagnostics surface on LintResult.configDiagnostics (and on stderr / the JSON reporter) so CI, the LSP, and JSON consumers all see them alongside file diagnostics.

Ignore file

Create .pyreonlintignore (same format as .gitignore):

# Ignore generated code
src/generated/
**/*.gen.ts

# Ignore test fixtures
src/tests/fixtures/

.gitignore patterns are respected automatically in addition to .pyreonlintignore. Pass --ignore <path> to load a custom ignore file.

Inline suppression

Suppress a diagnostic on the immediately following line with a comment. Two equivalent syntaxes are accepted — pyreon-lint-ignore (short) and pyreon-lint-disable-next-line (long-form, the convention several rule docstrings use):

// pyreon-lint-disable-next-line pyreon/no-peek-in-tracked
if (next === editor.value.peek()) return // intentional loop-prevention read

// pyreon-lint-ignore pyreon/no-window-in-ssr
const w = window.innerWidth // guarded elsewhere

// pyreon-lint-ignore
// ^ omitting the rule id suppresses EVERY rule on the next line
const x = someBroadlyFlaggedExpression()

Omitting the rule id suppresses all rules on the next line; including it suppresses only that rule. The comment must match exactly — word-boundary matching means a typo like // pyreon-lint-ignored is not treated as a suppression (so a misspelled directive fails loudly rather than silently disabling the rule).

Presets

@pyreon/lint ships five presets. The first four cover the common lifecycle (dev → CI → app/library); best-practices opts you into the full opinionated rule surface.

recommended

All rules at their declared default severity, except opt-in best-practice rules (meta.optIn), which are forced off so they never add unexpected noise.

strict

recommended with every warn promoted to error. info rules stay info; off (opt-in) rules stay off. This is the CI/pre-commit preset — any warning now fails the run.

app

recommended with the library-only architecture rules turned off, because applications don't ship as packages with those obligations:

• pyreon/dev-guard-warnings → off

• pyreon/no-error-without-prefix → off

• pyreon/no-circular-import → off

• pyreon/no-cross-layer-import → off

• pyreon/require-browser-smoke-test → off

lib

strict, plus every architecture rule forced to error:

• pyreon/no-circular-import

• pyreon/no-cross-layer-import

• pyreon/dev-guard-warnings

• pyreon/no-error-without-prefix

• pyreon/no-process-dev-gate

• pyreon/require-browser-smoke-test

For Pyreon packages and libraries — the strongest preset.

best-practices

recommended plus every opt-in best-practice rule enabled at its declared severity. The opt-in rules (the frontend, query, rx, i18n, storage categories + form's no-signal-in-form-initial-values + router's prefer-typed-search-params) are off in all other presets by design — best practices are opinionated, so you opt in explicitly. Library-scoped opt-in rules still self-gate on your package.json dependencies even under best-practices, so you only see rules for libraries you actually use.

Opt-in best-practice rules

Rules tagged opt-in (meta.optIn) are off in recommended / strict / app / lib. Enable them either wholesale via --preset best-practices / "preset": "best-practices", or per-rule:

{
  "preset": "recommended",
  "rules": {
    "pyreon/require-img-alt": "error",
    "pyreon/query-options-as-function": "error",
    "pyreon/rx-prefer-pipe": "off"
  }
}

Per-rule config in your config file always wins over the preset — enable one, disable another, change severity, or scope with exemptPaths.

Dependency auto-detection

Library-scoped opt-in rules — query, rx, i18n, storage, form's no-signal-in-form-initial-values, router's prefer-typed-search-params, and frontend's prefer-zero-image — only activate when the linted project actually declares the relevant @pyreon/* package in its package.json (dependencies / devDependencies / peerDependencies / optionalDependencies). A project that doesn't use @pyreon/query never sees query-options-as-function — zero config, zero noise. The check (isProjectDependency) walks up to the nearest package.json and is cached per manifest. Per-rule config still overrides if you want to force a rule on or off regardless of deps.

Rules

Performance

Linting is embarrassingly parallel — a file's diagnostics depend only on that file and the resolved config — so runs above a few hundred files are split across a worker pool instead of walking one core. The config is resolved once on the main thread and handed to workers as data, so no worker re-reads .pyreonlintrc.json or can disagree with its siblings about what is enabled.

Three properties are deliberate:

• Results are re-sorted by path. Workers finish in whatever order they finish; output that shifted between runs would make CI diffs useless.

• Small runs stay sequential. Below the threshold, spawning workers costs more than the work — a tool that is slower on lint one-file.ts to be faster on the whole repo is a bad trade.

• Whether the pool is used is DECIDED, never discovered by failing. planRun() reports the reason a run is sequential — below-threshold, source-entry (a .ts entry can't be loaded by a worker, which is the workspace/dev layout), or entry-missing. Attempting a spawn that is known to fail and catching the result would make a genuine worker crash indistinguishable from routine unavailability.

• A worker that genuinely fails is NOT silent. On a read-only run it prints why and completes sequentially. Under --fix it stops with guidance instead: workers that already succeeded have written their files, and re-running over a half-modified tree is only safe if every fixer is idempotent — an assumption the code cannot enforce.

The programmatic lint() stays synchronous for the LSP and watch mode; lintAsync() is the parallel driver, and a test locks that the two produce identical diagnostics over the same corpus.

Autofix

--fix applies fixes that are unambiguous. A fix may carry several edits — prefer-isserver rewrites typeof window !== 'undefined' to isClient and adds the import, as one fix — and a multi-edit fix is applied whole or not at all, because half of that pair is broken code.

Overlapping fixes from different rules are deferred, not applied blind: the first in source order wins, the other stays reported for a later pass. Fixes are deliberately conservative about intent:

• no-signal-call-write fixes count(5) → count.set(5), but leaves count(prev => prev + 1) alone — that reads as update intent, and .set(fn) would store the function as the value.

• prefer-isserver refuses to fix through a namespace or type-only import, where adding a specifier would produce code that doesn't compile.

• no-peek-in-tracked has no fixer at all: .peek() inside a tracked scope is frequently intentional loop-prevention, so rewriting it would turn "skip writes during a write" into an infinite loop.

Reading fixes programmatically? Diagnostic.fix is Fix | readonly Fix[] — normalize with fixEdits(d.fix).

Getting started

pyreon-lint --init   # writes .pyreonlintrc.json
pyreon-lint .

--init picks the preset from your project rather than always writing recommended — a package with an entry point gets lib (which enables the library-author rules), anything else gets app. It points $schema at the installed schema so your editor completes rule ids and rejects typos, and it refuses to overwrite an existing config.

The file it writes is deliberately minimal — a schema reference and a preset, nothing else. Scaffolding every rule at its current severity would freeze today's defaults into your file, so a later improvement to recommended would never reach you.

The linter also works with no config at all, defaulting to recommended.

Security

A security group, on by default in every standard preset:

Both are deliberately conservative: they read static values only. A dynamic href={u} or rel={r} might well be correct, and a rule that can't prove otherwise stays quiet — a security rule that cries wolf is one people switch off.

no-script-url normalizes the way a browser does before matching the scheme, so it catches the bypasses a naive prefix check misses: leading control characters, and embedded ones like java\tscript:. no-target-blank-without-rel still reports rel="noopener" alone — modern browsers imply noopener, but nothing implies noreferrer, and the referring URL can identify a user or tenant. Its autofix only adds a missing rel; a partially-correct one is reported and left alone rather than silently rewritten.

Accessibility is on by default

Six a11y rules ship on in every standard preset — require-img-alt, anchor-is-valid, no-autofocus, no-redundant-role, no-positive-tabindex and primitive-media-needs-label. Each is an unambiguous WCAG failure with a counterpart in oxlint's correctness tier, so a fresh Pyreon app gets the same a11y floor an ESLint user expects. primitive-media-needs-label is dependency-gated, so it stays silent unless you use @pyreon/primitives.

What remains opt-in is deliberately a different class: layout shift (img-requires-dimensions, content-visibility-needs-intrinsic-size), heuristic detection that can't see across components (heading-order, color-contrast), and @pyreon/zero preferences (prefer-zero-image, no-discarded-optimize-fields). Enable those with the best-practices preset or per rule.

Rule groups

Every rule belongs to one of four groups — the axis the 19 categories don't capture: what knowledge does this rule require, and does it ship?

Categories live underneath, so a query rule is group: 'pkg', category: 'query'. Set a whole group in one line — applied after the preset and before per-rule entries, so an explicit rule always wins:

{
  "preset": "best-practices",
  "groups": { "a11y": "off" },
  "rules": { "pyreon/require-img-alt": "error" }
}

Options shared by more than one rule

Some options are a property of the project, not of one rule. portablePaths names the directories whose source has to survive three targets — and five rules in the portable group need that same answer. Repeating it per rule turns your config into a hand-maintained copy of the rule registry: add a sixth portable rule and it is silently inert in every project that listed the other five.

settings says it once:

{
  "preset": "recommended",
  "groups": { "portable": "warn" },
  "settings": { "portablePaths": ["src/"] }
}

A key is seeded into a rule's options only when that rule declares it in its own schema, so a shared key can never reach a rule that would reject it as unknown. Per-rule options still win, so you can widen the shared answer and narrow it for one rule:

{
  "settings": { "portablePaths": ["src/"] },
  "rules": {
    "pyreon/no-out-of-subset-construct": ["warn", { "portablePaths": ["src/shared/"] }]
  }
}

A settings key that no rule declares is reported as a config error — a typo here would otherwise be as silent as a typo'd rule id.

pyreon-lint --list groups its output the same way. There is deliberately no js or ts group: those are for general JS/TS correctness rules, which this package does not have yet, and an empty group would advertise coverage that doesn't exist.

Why isn't a rule firing?

A rule can be silently inert for four independent reasons, and three of them are invisible in your config: its severity is off; it is an opt-in best-practice rule; it is monorepo-scoped; or it is dependency-gated and your project doesn't declare the library it covers. They compose, so a rule is often off for more than one reason and fixing one changes nothing.

--why-off reports every reason that applies, each with the edit that lifts it:

pyreon-lint --why-off pyreon/rx-prefer-pipe

  pyreon/rx-prefer-pipe

  ✗ WILL NOT RUN — severity: off

  [severity-off]
    The resolved config sets this rule to `off`.
    fix: Set `"pyreon/rx-prefer-pipe": "info"` in .pyreonlintrc.json.

  [opt-in]
    This is an opt-in best-practice rule, so every standard preset forces it off.
    fix: Select the `best-practices` preset, or enable this rule by id.

  [dependency-missing]
    This rule only applies to projects using `@pyreon/rx`, which is not a declared dependency here.
    fix: Nothing to fix — the rule is correctly silent. Add `@pyreon/rx` if you meant to use it.

The dependency gate is checked relative to a file, so pass a path (pyreon-lint --why-off <id> src/) when you want that reason evaluated. An unknown id exits non-zero and suggests the near miss. Programmatic equivalent: explainRuleState(id, { config, filePath }).

There are 132 rules across 25 categories. Six of them are monorepo-scoped (meta.scope: 'monorepo') — no-circular-import, no-cross-layer-import, no-error-without-prefix, no-query-selector-cast-in-test, require-browser-smoke-test, vitest-config-uses-shared. They encode the Pyreon repository's own conventions (its layer order, its private internal packages, its [Pyreon] error prefix) rather than anything about Pyreon-the-framework, so every preset a consumer selects forces them off, best-practices included. The Pyreon repo re-enables them by id in its own .pyreonlintrc.json, which keeps that dependency visible in config instead of hidden inside a shared preset. The frontend, query, rx, i18n, and storage categories (plus the two opt-in rules in form and router) are opt-in best-practice rules — off in the standard presets. Run pyreon-lint --list for the authoritative list with live severities.

Categories at a glance

Opt-in (ᵒ) rules below are off in recommended/strict/app/lib — enable via best-practices or per-rule config; library-scoped ones additionally auto-gate on package.json deps.

Reactivity (15)

JSX (11)

Lifecycle (6)

Performance (6)

SSR (4)

Architecture (10)

Store (3)

Form (4)

Styling (5)

Hooks (3)

Accessibility (3)

Router (5)

SSG (3)

Route-scoped (src/routes/) rules for @pyreon/zero static-site generation.

Frontend (10) ᵒ

Opt-in frontend best practices — accessibility + layout-shift (CLS) + asset optimization. All off in the standard presets.

Query (1) ᵒ

Auto-gated on a @pyreon/query dependency.

Rx (1) ᵒ

Auto-gated on a @pyreon/rx dependency.

I18n (1) ᵒ

Auto-gated on a @pyreon/i18n dependency.

Storage (1) ᵒ

Auto-gated on a @pyreon/storage dependency.

Notable Rules

pyreon/no-process-dev-gate (auto-fixable)

Pyreon ships libraries to npm; consumers compile with whatever bundler they use — Vite, Webpack (Next.js), Rolldown, esbuild, Rollup, Parcel, or Bun. Two dev-gate patterns are broken in library code and this rule flags both:

• typeof process !== 'undefined' && process.env.NODE_ENV !== 'production' — dead code in real Vite browser bundles, because Vite does not polyfill process. The whole expression statically folds to false and the dev warning never fires.

• import.meta.env.DEV (and (import.meta as ViteMeta).env?.DEV === true) — Vite/Rolldown-only. Under Webpack/Next.js, esbuild, Rollup, Parcel, or Bun, import.meta.env is undefined and the warning never fires, even in development.

// ❌ flagged — dead in real Vite browser bundles
if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production') warn()
// ❌ flagged — Vite/Rolldown-only, undefined elsewhere
if (import.meta.env.DEV) warn()

// ✅ auto-fixed to the bundler-agnostic convention
if (process.env.NODE_ENV !== 'production') warn()

Every modern bundler auto-replaces process.env.NODE_ENV at consumer build time and tree-shakes the dev branch to zero bytes in production — no consumer config needed. The companion rule pyreon/dev-guard-warnings recognises if (process.env.NODE_ENV === 'production') return as a valid early-return guard so warnings in the function body don't fire spuriously. Server-only packages are exempt because they always run in Node where process is real. Stays on in app — the bug hits user-facing browser code regardless of project type.

pyreon/require-browser-smoke-test

Every browser-categorized package must ship at least one *.browser.test.{ts,tsx} file under src/. The rule fires once per package on its src/index.ts, walks the package directory for browser smoke tests, and reports if none exist. This locks in the browser smoke harness: without it, new browser-running packages can silently ship without real-Chromium coverage, and happy-dom masks environment-divergence bugs (mock-vnode metadata drops, typeof process dead code, event-delegation bugs that only surface in a real browser). The default browser-package list mirrors .claude/rules/browser-packages.json; extend via additionalPackages, opt out via exemptPaths. Off in app, forced to error in lib.

{
  "rules": {
    "pyreon/require-browser-smoke-test": [
      "error",
      {
        "additionalPackages": ["@my-org/my-browser-pkg"],
        "exemptPaths": ["packages/experimental/"]
      }
    ]
  }
}

pyreon/no-imperative-effect-on-create

effect() is for pure reactive subscriptions (signal reads driving signal writes). When an effect() callback at component-body scope does imperative work — fetch(), setTimeout/setInterval, requestAnimationFrame/requestIdleCallback, queueMicrotask, or document.* / window.* / localStorage.* / sessionStorage.* access — that work allocates per instance and runs synchronously during component setup, which compounds badly under many instances. Move it into onMount(() => { ... }):

// ❌ flagged — imperative work in a per-instance effect
effect(() => {
  document.addEventListener('keydown', onKey)
})

// ✅ imperative work belongs in onMount
onMount(() => {
  document.addEventListener('keydown', onKey)
  return () => document.removeEventListener('keydown', onKey)
})

Pure effects (effect(() => sum.set(a() + b())), effect(() => console.log(count()))) are not flagged. Foundation hooks (@pyreon/hooks, @pyreon/rx) are exempt via exemptPaths — they're the abstraction layer that wraps timers/listeners for users.

pyreon/no-async-effect

async functions passed to effect(), renderEffect(), or computed() only track signal reads up to the first await — reads after an await happen in a detached microtask with no active tracking context, so the effect never re-runs when those signals change. Read every tracked signal synchronously before the first await, or move the async work into an event handler / onMount.

pyreon/no-signal-call-write & pyreon/no-signal-in-props

no-signal-call-write flags sig(value) where sig was declared const sig = signal(...) / computed(...) — the callable form is read-only; the argument is ignored. Use sig.set(value) or sig.update(fn). no-signal-in-props flags <Comp x={sig()} /> shapes where the signal value is captured once unless the compiler wraps it — prefer the props.x access pattern (or pass the accessor) so the prop stays reactive.

pyreon/no-context-destructure

Destructuring useContext() (const { mode } = useContext(Ctx)) captures the value once at setup time. If the provider exposes values via getters (get mode()), destructuring evaluates the getter immediately and the value becomes static. Keep the context object reference and read properties lazily inside reactive scopes: const ctx = useContext(Ctx) then ctx.mode.

pyreon/no-iterate-children-without-resolve

Library code that iterates props.children at the VNode level — cloneVNode(children, …), (Array.isArray(children) ? children : [children]).map/filter(…), or reading children.props — must first unwrap a possible compiler-emitted accessor function. The compiler's prop-inlining wrap can deliver props.children as a function; iterating it directly silently produces {type: undefined} → <undefined> DOM tags. Resolve at body entry with resolveChildren(…) or typeof X === 'function' ? X() : X.

pyreon/query-options-as-function (auto-fixable, dep-gated)

@pyreon/query hooks take options as a function so queryKey can read signals and refetch reactively. An options object literal captures the key once. --fix wraps it:

// ❌ flagged — captures id() once
useQuery({ queryKey: ['user', id()], queryFn: fetchUser })

// ✅ auto-fixed — refetches when id() changes
useQuery(() => ({ queryKey: ['user', id()], queryFn: fetchUser }))

useMutation is excluded (its options are imperative — no tracking). This rule is also a proactive MCP validate detector, so an AI assistant flags it before commit, not just after running lint.

Programmatic API

import { lint, listRules } from '@pyreon/lint'

// Lint a directory tree
const result = lint({ paths: ['src/'], preset: 'recommended' })
console.log(result.totalErrors, result.totalWarnings, result.totalInfos)

// Surface config-level diagnostics (malformed rule options, etc.)
for (const d of result.configDiagnostics) console.log(d.severity, d.ruleId, d.message)

// Enumerate every rule's metadata
for (const rule of listRules()) {
  console.log(`${rule.id} (${rule.category}, ${rule.severity})${rule.fixable ? ' [fixable]' : ''}`)
}

lint(options) — the high-level entry

LintOptions:

Returns LintResult: { files, totalErrors, totalWarnings, totalInfos, configDiagnostics }. Each files[i] is a LintFileResult ({ filePath, diagnostics, fixedSource? }).

// Severity + options overrides on a single run
lint({
  paths: ['.'],
  ruleOverrides: { 'pyreon/no-classname': 'off' },
  ruleOptionsOverrides: {
    'pyreon/no-window-in-ssr': { exemptPaths: ['src/foundation/'] },
  },
})

lintFile(...) — the low-level single-file entry

For tooling that owns the file-gathering loop (watchers, editors, custom CI). Takes a parsed-or-to-be-parsed source string, the rule set, a config, and an optional AST cache:

import { lintFile, allRules, getPreset, AstCache } from '@pyreon/lint'
import type { ConfigDiagnostic } from '@pyreon/lint'

const cache = new AstCache()
const config = getPreset('recommended')
const configSink: ConfigDiagnostic[] = []

// First call parses + caches the AST (FNV-1a hash keyed by source text)
const r1 = lintFile('app.tsx', source, allRules, config, cache, configSink)

// Same source → cache hit, no re-parse
const r2 = lintFile('app.tsx', source, allRules, config, cache, configSink)

lintFile(filePath, sourceText, rules, config, cache?, configDiagnosticsSink?) returns LintFileResult. Pass a configDiagnosticsSink array to collect malformed-option diagnostics; without it they print to stderr. Inline suppression comments and option validation are applied inside lintFile, so every entry point (CLI, lint, watcher, LSP) behaves identically.

applyFixes(source, diagnostics)

Apply every fixable diagnostic to a source string and return the result. Fixes are sorted by position descending and applied end-to-start so earlier offsets stay valid:

import { applyFixes } from '@pyreon/lint'

const fixed = applyFixes(source, fileResult.diagnostics)

(lint({ fix: true }) and pyreon-lint --fix use this internally and write the result back to disk.)

getPreset(name), allRules, listRules()

import { getPreset, allRules, listRules } from '@pyreon/lint'

const config = getPreset('strict')   // resolve a preset to a LintConfig
allRules                              // Rule[] — the full rule set (used by lintFile)
listRules()                           // RuleMeta[] — id, category, severity, fixable, description

loadConfig / loadConfigFromPath

import { loadConfig, loadConfigFromPath } from '@pyreon/lint'

const fromCwd = loadConfig(process.cwd())            // walks up for .pyreonlintrc.json / package.json field
const fromFile = loadConfigFromPath('./lint.json')   // load a specific file

loadConfig returns LintConfigFile | null; loadConfigFromPath returns the parsed JSON or null if missing/invalid.

createIgnoreFilter

import { createIgnoreFilter } from '@pyreon/lint'

const isIgnored = createIgnoreFilter(process.cwd(), './.customignore')
isIgnored('/abs/path/to/file.ts') // boolean — honors .pyreonlintignore + .gitignore + the custom file

AstCache

import { AstCache } from '@pyreon/lint'

const cache = new AstCache() // FNV-1a hash keyed by source text — share across lintFile calls in watch mode

The cache keys parsed ASTs by a hash of the source text, so re-linting an unchanged file (the common case in watch mode and the LSP) skips re-parsing entirely.

Reporters

import { formatText, formatJSON, formatCompact } from '@pyreon/lint'

console.log(formatText(result))     // human-readable, colorized when stdout is a TTY
console.log(formatJSON(result))     // machine-readable
console.log(formatCompact(result))  // one line per diagnostic

isProjectDependency / file-role utilities

import { isProjectDependency, isTestFile, isPathExempt } from '@pyreon/lint'

isProjectDependency('@pyreon/query', '/abs/path/to/file.ts') // dep-gating used by opt-in rules
isTestFile('/abs/src/foo.test.ts')                            // true
isPathExempt('/abs/src/foundation/x.ts', ['src/foundation/']) // true — the exemptPaths helper

@pyreon/lint also re-exports import-analysis helpers used by the rules themselves — extractImportInfo, getLocalName, importsName, isPyreonImport, isPyreonPackage, and the LineIndex offset→line/column mapper — for authors building their own AST tooling on top of the same primitives.

Watch mode

import { watchAndLint } from '@pyreon/lint'

watchAndLint({
  paths: ['src/'],
  preset: 'recommended',
  format: 'text', // 'text' | 'json' | 'compact'
})

watchAndLint uses fs.watch (recursive) with a 100ms debounce and the shared AstCache, clearing the screen and re-printing on each change. It accepts the same LintOptions fields as lint plus a required format.

LSP server

@pyreon/lint ships a Language Server Protocol server for in-editor diagnostics and inlay hints that surface the compiler's reactivity analysis at the cursor:

pyreon-lint --lsp

import { startLspServer } from '@pyreon/lint'

startLspServer() // speaks JSON-RPC over stdin/stdout

The server advertises textDocumentSync: full and inlayHintProvider: true. On textDocument/didOpen / didChange it publishes diagnostics; on textDocument/inlayHint it renders structural reactivity facts as end-of-span ghost text. When the PYREON_LPIH_CACHE environment variable points at a live-program-inlay-hints cache file, the server also overlays live runtime data — signal fire counts, effect re-runs — at the source line that created each primitive (🔥 signal fired N×). PYREON_LPIH_PATH_MAP (format from1=to1;from2=to2) remaps host paths to container paths for dev-container / remote setups.

CI integration

# .github/workflows/lint.yml
- name: Pyreon lint
  run: bunx pyreon-lint --preset strict --quiet

--preset strict promotes every warning to an error so the job fails on any deviation; --quiet keeps the output to errors only. The --format json output ({ files, totalErrors, totalWarnings, totalInfos, configDiagnostics }) feeds dashboards and custom gates. For a ratcheted burn-down (counts may only decrease), pair the JSON output with a baseline file.

API Reference

Functions

Values & classes

Types

RuleMeta shape

interface RuleMeta {
  id: string                  // e.g. 'pyreon/no-bare-signal-in-jsx'
  category: RuleCategory
  description: string
  severity: Severity          // default severity
  fixable: boolean
  schema?: RuleOptionsSchema  // declared option shape, validated against user config
  optIn?: boolean             // opt-in best-practice rule (off in standard presets)
}

Diagnostic shape

interface Diagnostic {
  ruleId: string
  severity: Severity
  message: string
  span: { start: number; end: number }
  loc: { line: number; column: number }
  fix?: { span: Span; replacement: string }
}