@pyreon/lint 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/lint",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "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": {
@@ -53,5 +53,8 @@
   "dependencies": {
     "@oxc-project/types": "^0.123.0",
     "oxc-parser": "^0.123.0"
+  },
+  "devDependencies": {
+    "@pyreon/manifest": "0.13.1"
   }
 }

package/src/manifest.ts

@@ -0,0 +1,152 @@
+import { defineManifest } from '@pyreon/manifest'
+
+export default defineManifest({
+  name: '@pyreon/lint',
+  title: 'Pyreon-specific Linter',
+  tagline:
+    'Pyreon-specific linter — 59 rules across 12 categories, config files, watch mode, AST cache, CLI + LSP',
+  description:
+    'Pyreon-specific lint rules powered by `oxc-parser`. Covers reactivity (10), JSX (11), lifecycle (4), performance (4), SSR (3), architecture (7), store (3), form (3), styling (4), hooks (3), accessibility (3), router (4) — 59 rules total. Programmatic API (`lint`, `lintFile`), CLI (`pyreon-lint`), watch mode (fs.watch + 100ms debounce + AstCache), LSP server, and `.pyreonlintrc.json` config with per-rule options via ESLint-style tuple form. Notable rules: `pyreon/no-process-dev-gate` (auto-fixable; replaces dead-in-browser `typeof process` gates with `import.meta.env?.DEV`), `pyreon/require-browser-smoke-test` (locks in T1.1 browser-test durability).',
+  category: 'server',
+  features: [
+    '59 rules across 12 categories',
+    'lint(options) programmatic API + lintFile() low-level entry',
+    'CLI: pyreon-lint with --preset / --fix / --watch / --format / --rule-options',
+    '4 presets: recommended, strict, app, lib',
+    'Per-rule options via tuple form in config or `--rule-options id=\'{json}\'`',
+    'AstCache (FNV-1a hash) for repeat runs',
+    'LSP server for IDE integration (startLspServer)',
+    'Inline suppression: // pyreon-lint-ignore <rule> OR // pyreon-lint-disable-next-line <rule>',
+  ],
+  longExample: `import { lint, lintFile, allRules, getPreset, AstCache } from '@pyreon/lint'
+
+// Programmatic — typical CI usage
+const result = lint({ paths: ['src/'], preset: 'recommended' })
+console.log(result.totalErrors, result.totalWarnings)
+for (const d of result.configDiagnostics) console.log(d.ruleId, d.message)
+
+// Per-rule overrides on a single run
+lint({
+  paths: ['.'],
+  ruleOverrides: { 'pyreon/no-classname': 'off' },
+  ruleOptionsOverrides: {
+    'pyreon/no-window-in-ssr': { exemptPaths: ['src/foundation/'] },
+  },
+})
+
+// Low-level single-file API with AST cache (watch mode)
+const cache = new AstCache()
+const config = getPreset('recommended')
+const fileResult = lintFile('app.tsx', source, allRules, config, cache)
+
+// CLI
+//   pyreon-lint --preset strict --quiet                    # CI mode
+//   pyreon-lint --fix                                      # auto-fix
+//   pyreon-lint --watch src/                               # watch mode
+//   pyreon-lint --list                                     # list all 59 rules
+//   pyreon-lint --rule-options 'pyreon/no-window-in-ssr={"exemptPaths":["src/foundation/"]}' src/`,
+  api: [
+    {
+      name: 'lint',
+      kind: 'function',
+      signature: 'lint(options?: LintOptions): LintResult',
+      summary:
+        '59 rules across 12 categories. Auto-loads `.pyreonlintrc.json`. Presets: `recommended`, `strict`, `app`, `lib`. Per-rule options via tuple form in config (`["error", { exemptPaths: [...] }]`) or `ruleOptionsOverrides`. Wrong-typed options surface on `result.configDiagnostics`. Uses `oxc-parser` with AST caching.',
+      example: `import { lint } from "@pyreon/lint"
+
+const result = lint({ paths: ["src/"], preset: "recommended" })
+console.log(result.totalErrors, result.totalWarnings)
+// Config-level diagnostics (malformed rule options, etc.)
+for (const d of result.configDiagnostics) console.log(d.ruleId, d.message)
+
+// Severity overrides + per-rule options overrides
+lint({
+  paths: ["."],
+  ruleOverrides: { "pyreon/no-classname": "off" },
+  ruleOptionsOverrides: {
+    "pyreon/no-window-in-ssr": { exemptPaths: ["src/foundation/"] },
+  },
+})`,
+      seeAlso: ['lintFile', 'getPreset', 'AstCache'],
+    },
+    {
+      name: 'lintFile',
+      kind: 'function',
+      signature:
+        'lintFile(filePath: string, sourceText: string, rules: Rule[], config: LintConfig, cache?: AstCache, configDiagnosticsSink?: ConfigDiagnostic[]): LintFileResult',
+      summary:
+        'Low-level single-file API. Optional `AstCache` for repeat runs (FNV-1a hash keyed). Optional `configDiagnosticsSink` collects malformed-option diagnostics; without it they print to stderr.',
+      example: `import { lintFile, allRules, getPreset, AstCache } from "@pyreon/lint"
+
+const cache = new AstCache()
+const config = getPreset("recommended")
+const configSink: ConfigDiagnostic[] = []
+const result = lintFile("app.tsx", source, allRules, config, cache, configSink)`,
+      seeAlso: ['lint', 'AstCache'],
+    },
+    {
+      name: 'cli',
+      kind: 'function',
+      signature:
+        "pyreon-lint [--preset name] [--fix] [--format text|json|compact] [--quiet] [--watch] [--list] [--config path] [--ignore path] [--rule id=severity] [--rule-options id='{json}'] [path...]",
+      summary:
+        "CLI entry. Config: `.pyreonlintrc.json` (reference `schema/pyreonlintrc.schema.json` for IDE autocomplete) or `package.json`'s `'pyreonlint'` field. Ignore: `.pyreonlintignore` + `.gitignore`. Watch: `fs.watch` recursive with 100ms debounce. `--rule-options id='{json}'` passes per-rule options on a single run.",
+      example: `pyreon-lint --preset strict --quiet    # CI mode
+pyreon-lint --fix                       # auto-fix
+pyreon-lint --watch src/                # watch mode
+pyreon-lint --list                      # list all 59 rules
+pyreon-lint --format json               # machine-readable
+pyreon-lint --rule-options 'pyreon/no-window-in-ssr={"exemptPaths":["src/foundation/"]}' src/`,
+      seeAlso: ['lint'],
+    },
+    {
+      name: 'no-process-dev-gate',
+      kind: 'constant',
+      signature: 'rule: pyreon/no-process-dev-gate (architecture, error, auto-fixable)',
+      summary:
+        "The `typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'` pattern works in vitest (Node, `process` is defined) but is silently dead code in real Vite browser bundles because Vite does NOT polyfill `process` for the client. Every `console.warn` gated on the broken constant never fires for real users in dev mode — unit tests pass while users get nothing. Use `import.meta.env.DEV` instead — Vite/Rolldown literal-replace it at build time, prod tree-shakes the warning to zero bytes, and vitest sets it to `true` automatically. Server-only packages (`zero`, `core/server`, `core/runtime-server`, `vite-plugin`, `cli`, `lint`, `mcp`, `storybook`, `typescript`) and test files are exempt. Reference implementation: `packages/fundamentals/flow/src/layout.ts:warnIgnoredOptions`. The rule has an auto-fix that replaces the broken expression with `import.meta.env?.DEV === true`.",
+      example: `// ❌ Wrong — dead code in real Vite browser bundles
+const __DEV__ = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'
+if (__DEV__) console.warn('hello')
+
+// ✅ Correct — Vite literal-replaces import.meta.env.DEV at build time
+// @ts-ignore — provided by Vite/Rolldown at build time
+const __DEV__ = import.meta.env?.DEV === true
+if (__DEV__) console.warn('hello')`,
+      mistakes: [
+        "Copying the `typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'` pattern from existing codebases — it works in Node but is dead in browser bundles",
+        "Trying to test with `delete globalThis.process` — vitest's own `import.meta.env` depends on `process`, so deleting it breaks the FIXED gate too (not because the gate is wrong, but because vitest can't resolve it)",
+        'Adding `process: { env: { ... } }` polyfills to vite.config.ts as a workaround — fix the source instead',
+        "Using the rule for server-only packages — they're correctly exempt because Node always has `process`",
+      ],
+      seeAlso: ['require-browser-smoke-test'],
+    },
+    {
+      name: 'require-browser-smoke-test',
+      kind: 'constant',
+      signature:
+        'rule: pyreon/require-browser-smoke-test (architecture, error in recommended/strict/lib, off in app)',
+      summary:
+        "Locks in the durability of the T1.1 browser smoke harness (PRs #224, #227, #229, #231). Every browser-categorized package MUST ship at least one `*.browser.test.{ts,tsx}` file under `src/`. Without this rule, new browser packages can quietly ship without smoke coverage and we drift back to the world before T1.1 — happy-dom silently masks environment-divergence bugs (PR #197 mock-vnode metadata drop, PR #200 `typeof process` dead code, multi-word event delegation bug). Default browser-package list mirrors `.claude/rules/test-environment-parity.md`. The rule fires once per package on its `src/index.ts`, walks the package directory looking for `*.browser.test.*`, and reports if none are found. Off in `app` preset because apps don't ship as packages with smoke obligations.",
+      example: `// Per-package config (optional — defaults cover all known browser packages)
+{
+  "rules": {
+    "pyreon/require-browser-smoke-test": [
+      "error",
+      {
+        "additionalPackages": ["@my-org/my-browser-pkg"],
+        "exemptPaths": ["packages/experimental/"]
+      }
+    ]
+  }
+}`,
+      mistakes: [
+        'Adding a new browser-running package without a browser test — the rule will fail your PR',
+        'Hardcoding the browser-package list in the rule — the list lives in `.claude/rules/browser-packages.json` (single source of truth), not in the rule source',
+        'Disabling the rule globally — use `exemptPaths` to exempt specific packages still under construction',
+        'Shipping a `sanity.browser.test.ts` with `expect(1).toBe(1)` just to satisfy the rule — it passes but provides zero signal. The rule is a GATE, not a quality check; review actual contents on PR',
+      ],
+      seeAlso: ['no-process-dev-gate'],
+    },
+  ],
+})

package/src/tests/ast-utils.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, it } from 'vitest'
+import {
+  getJSXAttribute,
+  getJSXTagName,
+  getSpan,
+  hasJSXAttribute,
+  hasJSXChild,
+  isArrayMapCall,
+  isBrowserGlobal,
+  isCallTo,
+  isCallToAny,
+  isDestructuring,
+  isFunction,
+  isInsideDevGuard,
+  isInsideFunction,
+  isInsideJSX,
+  isInsideOnMount,
+  isInsideTypeofGuard,
+  isJSXElement,
+  isLogicalAndWithJSX,
+  isMemberCallTo,
+  isPeekCall,
+  isSetCall,
+  isTernaryWithJSX,
+} from '../utils/ast'
+
+// Coverage gap closed in PR #323. The ast utils are pure node-shape
+// predicates used by ~40 lint rules. Pinning their behavior here so
+// a future refactor that touches the AST builder doesn't silently
+// invalidate the rule layer.
+
+const ident = (name: string) => ({ type: 'Identifier', name })
+const callExpr = (callee: any, args: any[] = []) => ({
+  type: 'CallExpression',
+  callee,
+  arguments: args,
+})
+const member = (object: any, property: any) => ({ type: 'MemberExpression', object, property })
+const jsxIdent = (name: string) => ({ type: 'JSXIdentifier', name })
+const jsxElement = (tag: string, attrs: any[] = [], children: any[] = []) => ({
+  type: 'JSXElement',
+  openingElement: { attributes: attrs, name: jsxIdent(tag) },
+  children,
+})
+const jsxAttr = (name: string, value?: any) => ({
+  type: 'JSXAttribute',
+  name: jsxIdent(name),
+  value,
+})
+
+describe('ast utils — call expression predicates', () => {
+  it('isCallTo matches direct identifier calls', () => {
+    expect(isCallTo(callExpr(ident('signal'), []), 'signal')).toBe(true)
+    expect(isCallTo(callExpr(ident('signal'), []), 'computed')).toBe(false)
+    expect(isCallTo(callExpr(member(ident('a'), ident('b'))), 'a')).toBe(false)
+    expect(isCallTo({ type: 'BinaryExpression' }, 'signal')).toBe(false)
+  })
+
+  it('isCallToAny matches any of a name set', () => {
+    const set = new Set(['signal', 'computed', 'effect'])
+    expect(isCallToAny(callExpr(ident('signal')), set)).toBe(true)
+    expect(isCallToAny(callExpr(ident('effect')), set)).toBe(true)
+    expect(isCallToAny(callExpr(ident('useState')), set)).toBe(false)
+  })
+
+  it('isMemberCallTo matches `obj.method()` form', () => {
+    const node = callExpr(member(ident('console'), ident('log')))
+    expect(isMemberCallTo(node, 'console', 'log')).toBe(true)
+    expect(isMemberCallTo(node, 'console', 'warn')).toBe(false)
+    expect(isMemberCallTo(node, 'window', 'log')).toBe(false)
+  })
+
+  it('isArrayMapCall matches any `.map(...)` call', () => {
+    expect(isArrayMapCall(callExpr(member(ident('items'), ident('map'))))).toBe(true)
+    expect(isArrayMapCall(callExpr(member(ident('items'), ident('filter'))))).toBe(false)
+    expect(isArrayMapCall(callExpr(ident('map')))).toBe(false)
+  })
+
+  it('isPeekCall and isSetCall match `obj.peek()` and `obj.set()`', () => {
+    expect(isPeekCall(callExpr(member(ident('count'), ident('peek'))))).toBe(true)
+    expect(isPeekCall(callExpr(member(ident('count'), ident('value'))))).toBe(false)
+    expect(isSetCall(callExpr(member(ident('count'), ident('set'))))).toBe(true)
+    expect(isSetCall(callExpr(member(ident('count'), ident('peek'))))).toBe(false)
+  })
+})
+
+describe('ast utils — JSX predicates', () => {
+  it('isJSXElement recognises JSXElement and JSXFragment', () => {
+    expect(isJSXElement(jsxElement('div'))).toBe(true)
+    expect(isJSXElement({ type: 'JSXFragment' })).toBe(true)
+    expect(isJSXElement({ type: 'CallExpression' })).toBe(false)
+  })
+
+  it('getJSXTagName returns plain identifier name', () => {
+    expect(getJSXTagName(jsxElement('div'))).toBe('div')
+  })
+
+  it('getJSXTagName returns dotted form for JSXMemberExpression', () => {
+    const node = {
+      type: 'JSXElement',
+      openingElement: {
+        name: { type: 'JSXMemberExpression', object: { name: 'My' }, property: { name: 'Comp' } },
+      },
+    }
+    expect(getJSXTagName(node)).toBe('My.Comp')
+  })
+
+  it('getJSXTagName returns null for fragments and missing opening', () => {
+    expect(getJSXTagName({ type: 'JSXFragment' })).toBeNull()
+    expect(getJSXTagName({ type: 'JSXElement' })).toBeNull()
+  })
+
+  it('getJSXAttribute / hasJSXAttribute look up by name', () => {
+    const opening = { attributes: [jsxAttr('class', 'a'), jsxAttr('id', 'x')] }
+    expect(getJSXAttribute(opening, 'class')).toBeTruthy()
+    expect(getJSXAttribute(opening, 'missing')).toBeNull()
+    expect(hasJSXAttribute(opening, 'id')).toBe(true)
+    expect(hasJSXAttribute(opening, 'no')).toBe(false)
+  })
+
+  it('hasJSXAttribute handles missing attributes array', () => {
+    expect(hasJSXAttribute({}, 'x')).toBe(false)
+  })
+
+  it('hasJSXChild detects nested JSX elements', () => {
+    const inner = jsxElement('span')
+    const outer = jsxElement('div', [], [inner])
+    expect(hasJSXChild(outer)).toBe(true)
+  })
+
+  it('hasJSXChild returns false for fragments', () => {
+    expect(hasJSXChild({ type: 'JSXFragment' })).toBe(false)
+  })
+
+  it('hasJSXChild returns false when only text children', () => {
+    expect(hasJSXChild(jsxElement('div', [], [{ type: 'JSXText' }]))).toBe(false)
+  })
+
+  it('isTernaryWithJSX detects JSX in either branch', () => {
+    const ternary = (c: any, a: any) => ({ type: 'ConditionalExpression', consequent: c, alternate: a })
+    expect(isTernaryWithJSX(ternary(jsxElement('a'), { type: 'NullLiteral' }))).toBe(true)
+    expect(isTernaryWithJSX(ternary({ type: 'NullLiteral' }, jsxElement('b')))).toBe(true)
+    expect(isTernaryWithJSX(ternary({ type: 'NullLiteral' }, { type: 'NullLiteral' }))).toBe(false)
+    expect(isTernaryWithJSX({ type: 'BinaryExpression' })).toBe(false)
+  })
+
+  it('isTernaryWithJSX unwraps ParenthesizedExpression', () => {
+    const ternary = {
+      type: 'ConditionalExpression',
+      consequent: { type: 'ParenthesizedExpression', expression: jsxElement('a') },
+      alternate: { type: 'NullLiteral' },
+    }
+    expect(isTernaryWithJSX(ternary)).toBe(true)
+  })
+
+  it('isLogicalAndWithJSX detects `cond && <JSX />`', () => {
+    expect(
+      isLogicalAndWithJSX({ type: 'LogicalExpression', operator: '&&', right: jsxElement('div') }),
+    ).toBe(true)
+    expect(
+      isLogicalAndWithJSX({ type: 'LogicalExpression', operator: '||', right: jsxElement('div') }),
+    ).toBe(false)
+    expect(
+      isLogicalAndWithJSX({ type: 'LogicalExpression', operator: '&&', right: { type: 'NullLiteral' } }),
+    ).toBe(false)
+    expect(isLogicalAndWithJSX({ type: 'BinaryExpression' })).toBe(false)
+  })
+})
+
+describe('ast utils — ancestor predicates', () => {
+  it('isInsideFunction detects function ancestors', () => {
+    expect(isInsideFunction([{ type: 'IfStatement' }, { type: 'FunctionDeclaration' }])).toBe(true)
+    expect(isInsideFunction([{ type: 'ArrowFunctionExpression' }])).toBe(true)
+    expect(isInsideFunction([{ type: 'FunctionExpression' }])).toBe(true)
+    expect(isInsideFunction([{ type: 'IfStatement' }])).toBe(false)
+  })
+
+  it('isInsideJSX detects JSX ancestors', () => {
+    expect(isInsideJSX([{ type: 'JSXElement' }])).toBe(true)
+    expect(isInsideJSX([{ type: 'JSXFragment' }])).toBe(true)
+    expect(isInsideJSX([{ type: 'IfStatement' }])).toBe(false)
+  })
+
+  it('isInsideDevGuard detects `if (__DEV__)` wrapping', () => {
+    expect(
+      isInsideDevGuard([{ type: 'IfStatement', test: { type: 'Identifier', name: '__DEV__' } }]),
+    ).toBe(true)
+    expect(
+      isInsideDevGuard([{ type: 'IfStatement', test: { type: 'Identifier', name: 'something' } }]),
+    ).toBe(false)
+  })
+
+  it('isInsideOnMount detects `onMount(() => …)` wrapping', () => {
+    expect(
+      isInsideOnMount([{ type: 'CallExpression', callee: { type: 'Identifier', name: 'onMount' } }]),
+    ).toBe(true)
+    expect(
+      isInsideOnMount([{ type: 'CallExpression', callee: { type: 'Identifier', name: 'effect' } }]),
+    ).toBe(false)
+  })
+
+  it('isInsideTypeofGuard detects `typeof X !== "undefined"` wrapping', () => {
+    const guard = {
+      type: 'IfStatement',
+      test: {
+        type: 'BinaryExpression',
+        left: { type: 'UnaryExpression', operator: 'typeof' },
+      },
+    }
+    expect(isInsideTypeofGuard([guard])).toBe(true)
+    expect(isInsideTypeofGuard([{ type: 'IfStatement', test: { type: 'Identifier' } }])).toBe(false)
+  })
+})
+
+describe('ast utils — misc', () => {
+  it('isFunction recognises all function node types', () => {
+    expect(isFunction({ type: 'FunctionDeclaration' })).toBe(true)
+    expect(isFunction({ type: 'FunctionExpression' })).toBe(true)
+    expect(isFunction({ type: 'ArrowFunctionExpression' })).toBe(true)
+    expect(isFunction({ type: 'CallExpression' })).toBe(false)
+  })
+
+  it('isDestructuring recognises object and array patterns', () => {
+    expect(isDestructuring({ type: 'ObjectPattern' })).toBe(true)
+    expect(isDestructuring({ type: 'ArrayPattern' })).toBe(true)
+    expect(isDestructuring({ type: 'Identifier' })).toBe(false)
+  })
+
+  it('isBrowserGlobal recognises window/document/etc.', () => {
+    expect(isBrowserGlobal(ident('window'))).toBe(true)
+    expect(isBrowserGlobal(ident('document'))).toBe(true)
+    expect(isBrowserGlobal(ident('fooBar'))).toBe(false)
+    expect(isBrowserGlobal({ type: 'CallExpression' })).toBe(false)
+  })
+
+  it('getSpan returns { start, end } from byte offsets', () => {
+    expect(getSpan({ start: 12, end: 30 })).toEqual({ start: 12, end: 30 })
+  })
+})

package/src/tests/imports.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it } from 'vitest'
+import {
+  extractImportInfo,
+  getLocalName,
+  importsName,
+  isPyreonImport,
+  isPyreonPackage,
+} from '../utils/imports'
+
+// Coverage gap closed in PR #323. The imports utils are pure AST
+// readers — `extractImportInfo` walks an oxc-style ImportDeclaration
+// node, the rest are convenience predicates over the resulting
+// ImportInfo shape. Used by ~30 lint rules; unit-tested here so a
+// future refactor doesn't silently break import-aware rules.
+
+const importDecl = (
+  source: string,
+  specifiers: Array<{ kind: 'default' | 'ns' | 'named'; imported?: string; local: string }>,
+) => ({
+  type: 'ImportDeclaration',
+  source: { value: source },
+  specifiers: specifiers.map((s) => {
+    if (s.kind === 'default') return { type: 'ImportDefaultSpecifier', local: { name: s.local } }
+    if (s.kind === 'ns') return { type: 'ImportNamespaceSpecifier', local: { name: s.local } }
+    return {
+      type: 'ImportSpecifier',
+      imported: { type: 'Identifier', name: s.imported },
+      local: { name: s.local },
+    }
+  }),
+})
+
+describe('imports utils — Pyreon import classifiers', () => {
+  it('isPyreonImport recognises @pyreon/* sources', () => {
+    expect(isPyreonImport('@pyreon/core')).toBe(true)
+    expect(isPyreonImport('@pyreon/router')).toBe(true)
+    expect(isPyreonImport('react')).toBe(false)
+    expect(isPyreonImport('@vue/runtime-core')).toBe(false)
+  })
+
+  it('isPyreonPackage matches the same prefix', () => {
+    expect(isPyreonPackage('@pyreon/flow')).toBe(true)
+    expect(isPyreonPackage('react')).toBe(false)
+  })
+})
+
+describe('imports utils — extractImportInfo', () => {
+  it('returns null for non-ImportDeclaration nodes', () => {
+    expect(extractImportInfo({ type: 'ExpressionStatement' })).toBeNull()
+  })
+
+  it('returns null when source value is missing', () => {
+    expect(extractImportInfo({ type: 'ImportDeclaration', source: {}, specifiers: [] })).toBeNull()
+  })
+
+  it('extracts default import', () => {
+    const info = extractImportInfo(importDecl('react', [{ kind: 'default', local: 'React' }]))
+    expect(info).toEqual({
+      source: 'react',
+      specifiers: [{ imported: 'default', local: 'React' }],
+      isDefault: true,
+      isNamespace: false,
+    })
+  })
+
+  it('extracts namespace import', () => {
+    const info = extractImportInfo(importDecl('@pyreon/core', [{ kind: 'ns', local: 'P' }]))
+    expect(info).toEqual({
+      source: '@pyreon/core',
+      specifiers: [{ imported: '*', local: 'P' }],
+      isDefault: false,
+      isNamespace: true,
+    })
+  })
+
+  it('extracts named imports (Identifier form)', () => {
+    const info = extractImportInfo(
+      importDecl('@pyreon/reactivity', [
+        { kind: 'named', imported: 'signal', local: 'signal' },
+        { kind: 'named', imported: 'computed', local: 'computed' },
+      ]),
+    )
+    expect(info?.source).toBe('@pyreon/reactivity')
+    expect(info?.specifiers).toEqual([
+      { imported: 'signal', local: 'signal' },
+      { imported: 'computed', local: 'computed' },
+    ])
+    expect(info?.isDefault).toBe(false)
+    expect(info?.isNamespace).toBe(false)
+  })
+
+  it('extracts named imports with renaming (local name differs)', () => {
+    const info = extractImportInfo(
+      importDecl('@pyreon/core', [
+        { kind: 'named', imported: 'h', local: 'createElement' },
+      ]),
+    )
+    expect(info?.specifiers).toEqual([{ imported: 'h', local: 'createElement' }])
+  })
+
+  it('handles imported as Literal (string-keyed export — type Literal node)', () => {
+    const info = extractImportInfo({
+      type: 'ImportDeclaration',
+      source: { value: '@pyreon/core' },
+      specifiers: [
+        {
+          type: 'ImportSpecifier',
+          imported: { type: 'Literal', value: 'use client' },
+          local: { name: 'useClient' },
+        },
+      ],
+    })
+    expect(info?.specifiers).toEqual([{ imported: 'use client', local: 'useClient' }])
+  })
+
+  it('handles missing specifiers array', () => {
+    const info = extractImportInfo({
+      type: 'ImportDeclaration',
+      source: { value: 'noop' },
+    })
+    expect(info?.specifiers).toEqual([])
+  })
+
+  it('mixed default + named not standardly emitted but the builder is permissive', () => {
+    const info = extractImportInfo(
+      importDecl('react', [
+        { kind: 'default', local: 'React' },
+        { kind: 'named', imported: 'useState', local: 'useState' },
+      ]),
+    )
+    expect(info?.isDefault).toBe(true)
+    expect(info?.specifiers).toHaveLength(2)
+  })
+})
+
+describe('imports utils — importsName', () => {
+  const imports = [
+    extractImportInfo(
+      importDecl('@pyreon/reactivity', [{ kind: 'named', imported: 'signal', local: 'signal' }]),
+    )!,
+    extractImportInfo(
+      importDecl('@pyreon/core', [{ kind: 'named', imported: 'h', local: 'h' }]),
+    )!,
+  ]
+
+  it('returns true when an import imports the named export', () => {
+    expect(importsName(imports, 'signal')).toBe(true)
+    expect(importsName(imports, 'h')).toBe(true)
+  })
+
+  it('returns false when the name is not imported', () => {
+    expect(importsName(imports, 'computed')).toBe(false)
+  })
+
+  it('respects fromPackage filter — same name from different package returns false', () => {
+    expect(importsName(imports, 'signal', '@pyreon/reactivity')).toBe(true)
+    expect(importsName(imports, 'signal', '@pyreon/core')).toBe(false)
+  })
+})
+
+describe('imports utils — getLocalName', () => {
+  const imports = [
+    extractImportInfo(
+      importDecl('@pyreon/core', [
+        { kind: 'named', imported: 'h', local: 'createElement' },
+      ]),
+    )!,
+  ]
+
+  it('returns the local alias when the export is imported', () => {
+    expect(getLocalName(imports, 'h')).toBe('createElement')
+  })
+
+  it('returns null when not imported', () => {
+    expect(getLocalName(imports, 'unused')).toBeNull()
+  })
+
+  it('respects fromPackage filter', () => {
+    expect(getLocalName(imports, 'h', '@pyreon/core')).toBe('createElement')
+    expect(getLocalName(imports, 'h', 'react')).toBeNull()
+  })
+})

package/src/tests/manifest-snapshot.test.ts

@@ -0,0 +1,30 @@
+import {
+  renderApiReferenceEntries,
+  renderLlmsFullSection,
+  renderLlmsTxtLine,
+} from '@pyreon/manifest'
+import manifest from '../manifest'
+
+describe('gen-docs — lint snapshot', () => {
+  it('renders a llms.txt bullet starting with the package prefix', () => {
+    const line = renderLlmsTxtLine(manifest)
+    expect(line.startsWith('- @pyreon/lint —')).toBe(true)
+  })
+
+  it('renders a llms-full.txt section with the right header', () => {
+    const section = renderLlmsFullSection(manifest)
+    expect(section.startsWith('## @pyreon/lint —')).toBe(true)
+    expect(section).toContain('```typescript')
+  })
+
+  it('renders MCP api-reference entries for every api[] item', () => {
+    const record = renderApiReferenceEntries(manifest)
+    expect(Object.keys(record).sort()).toEqual([
+      'lint/cli',
+      'lint/lint',
+      'lint/lintFile',
+      'lint/no-process-dev-gate',
+      'lint/require-browser-smoke-test',
+    ])
+  })
+})

package/src/tests/reporter.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it } from 'vitest'
+import { formatCompact, formatJSON, formatText } from '../reporter'
+import type { LintResult } from '../types'
+
+// Coverage gap closed in PR #323. The reporter module renders LintResult
+// shapes into one of three formats (text / JSON / compact). Pure pretty-
+// printing — no I/O, no async — but uncovered until now.
+
+const span = (start: number, end: number) => ({ start, end })
+
+const fileWithErr = {
+  filePath: '/abs/foo.ts',
+  diagnostics: [
+    {
+      ruleId: 'pyreon/no-window-in-ssr',
+      severity: 'error' as const,
+      message: 'window is undefined in SSR',
+      loc: { line: 12, column: 4 },
+      span: span(0, 6),
+    },
+  ],
+}
+const fileWithMixed = {
+  filePath: '/abs/bar.ts',
+  diagnostics: [
+    {
+      ruleId: 'pyreon/no-bare-signal-in-jsx',
+      severity: 'warn' as const,
+      message: 'bare signal in JSX text',
+      loc: { line: 5, column: 10 },
+      span: span(20, 26),
+    },
+    {
+      ruleId: 'pyreon/use-pyreon-hooks',
+      severity: 'info' as const,
+      message: 'consider useEventListener',
+      loc: { line: 7, column: 2 },
+      span: span(40, 60),
+    },
+  ],
+}
+const cleanFile = {
+  filePath: '/abs/clean.ts',
+  diagnostics: [],
+}
+
+const result: LintResult = {
+  files: [fileWithErr, fileWithMixed, cleanFile],
+  totalErrors: 1,
+  totalWarnings: 1,
+  totalInfos: 1,
+  configDiagnostics: [],
+}
+
+const empty: LintResult = {
+  files: [],
+  totalErrors: 0,
+  totalWarnings: 0,
+  totalInfos: 0,
+  configDiagnostics: [],
+}
+
+describe('reporter — formatText', () => {
+  it('renders file paths, locations, severities, messages, and rule ids', () => {
+    const text = formatText(result)
+    expect(text).toContain('/abs/foo.ts')
+    expect(text).toContain('/abs/bar.ts')
+    expect(text).toContain('12:4')
+    expect(text).toContain('5:10')
+    expect(text).toContain('window is undefined in SSR')
+    expect(text).toContain('pyreon/no-window-in-ssr')
+    expect(text).toContain('pyreon/no-bare-signal-in-jsx')
+    // 'error' / 'warning' / 'info' strings appear (ANSI-coloured)
+    expect(text).toContain('error')
+    expect(text).toContain('warning')
+    expect(text).toContain('info')
+  })
+
+  it('omits files with no diagnostics from the body', () => {
+    const text = formatText(result)
+    expect(text).not.toContain('/abs/clean.ts')
+  })
+
+  it('renders the trailing summary with pluralisation', () => {
+    const text = formatText(result)
+    expect(text).toMatch(/1 error/)
+    expect(text).toMatch(/1 warning/)
+    expect(text).toMatch(/1 info/)
+  })
+
+  it('pluralises errors and warnings when count > 1', () => {
+    const multi: LintResult = {
+      files: [
+        {
+          filePath: '/x.ts',
+          diagnostics: [
+            { ruleId: 'r', severity: 'error', message: 'm', loc: { line: 1, column: 1 }, span: span(0, 1) },
+            { ruleId: 'r', severity: 'error', message: 'm', loc: { line: 2, column: 1 }, span: span(2, 3) },
+            { ruleId: 'r', severity: 'warn', message: 'm', loc: { line: 3, column: 1 }, span: span(4, 5) },
+            { ruleId: 'r', severity: 'warn', message: 'm', loc: { line: 4, column: 1 }, span: span(6, 7) },
+          ],
+        },
+      ],
+      totalErrors: 2,
+      totalWarnings: 2,
+      totalInfos: 0,
+      configDiagnostics: [],
+    }
+    const text = formatText(multi)
+    expect(text).toMatch(/2 errors/)
+    expect(text).toMatch(/2 warnings/)
+  })
+
+  it('returns empty-ish output for a clean result (no summary)', () => {
+    const text = formatText(empty)
+    expect(text.trim()).toBe('')
+  })
+})
+
+describe('reporter — formatJSON', () => {
+  it('round-trips through JSON.parse', () => {
+    const json = formatJSON(result)
+    expect(JSON.parse(json)).toEqual(result)
+  })
+
+  it('produces indented output (multi-line)', () => {
+    const json = formatJSON(result)
+    expect(json.split('\n').length).toBeGreaterThan(1)
+  })
+
+  it('handles empty results', () => {
+    expect(JSON.parse(formatJSON(empty))).toEqual(empty)
+  })
+})
+
+describe('reporter — formatCompact', () => {
+  it('emits one line per diagnostic in `path:line:col: severity [ruleId] message` form', () => {
+    const text = formatCompact(result)
+    const lines = text.split('\n')
+    expect(lines).toHaveLength(3)
+    expect(lines[0]).toBe(
+      '/abs/foo.ts:12:4: error [pyreon/no-window-in-ssr] window is undefined in SSR',
+    )
+    expect(lines[1]).toBe(
+      '/abs/bar.ts:5:10: warn [pyreon/no-bare-signal-in-jsx] bare signal in JSX text',
+    )
+    expect(lines[2]).toBe(
+      '/abs/bar.ts:7:2: info [pyreon/use-pyreon-hooks] consider useEventListener',
+    )
+  })
+
+  it('emits empty string when there are no diagnostics', () => {
+    expect(formatCompact(empty)).toBe('')
+  })
+})