@pyreon/lint 0.11.0

package/lib/types/index.d.ts

@@ -0,0 +1,260 @@
+//#region src/types.d.ts
+type Severity = "error" | "warn" | "info" | "off";
+interface SourceLocation {
+  line: number;
+  column: number;
+}
+interface Span {
+  start: number;
+  end: number;
+}
+interface Fix {
+  span: Span;
+  replacement: string;
+}
+interface Diagnostic {
+  ruleId: string;
+  severity: Severity;
+  message: string;
+  span: Span;
+  loc: SourceLocation;
+  fix?: Fix | undefined;
+}
+type RuleCategory = "reactivity" | "jsx" | "lifecycle" | "performance" | "ssr" | "architecture" | "store" | "form" | "styling" | "hooks" | "accessibility" | "router";
+interface RuleMeta {
+  id: string;
+  category: RuleCategory;
+  description: string;
+  severity: Severity;
+  fixable: boolean;
+}
+interface RuleContext {
+  report(diagnostic: Omit<Diagnostic, "ruleId" | "severity" | "loc">): void;
+  getSourceText(): string;
+  getFilePath(): string;
+}
+type VisitorCallback = (node: any, parent?: any) => void;
+interface VisitorCallbacks {
+  [nodeType: string]: VisitorCallback;
+}
+interface Rule {
+  meta: RuleMeta;
+  create(context: RuleContext): VisitorCallbacks;
+}
+interface LintConfig {
+  rules: Record<string, Severity>;
+  include?: string[] | undefined;
+  exclude?: string[] | undefined;
+}
+interface LintConfigFile {
+  preset?: PresetName | undefined;
+  rules?: Record<string, Severity> | undefined;
+  include?: string[] | undefined;
+  exclude?: string[] | undefined;
+}
+type PresetName = "recommended" | "strict" | "app" | "lib";
+interface LintFileResult {
+  filePath: string;
+  diagnostics: Diagnostic[];
+  fixedSource?: string | undefined;
+}
+interface LintResult {
+  files: LintFileResult[];
+  totalErrors: number;
+  totalWarnings: number;
+  totalInfos: number;
+}
+interface LintOptions {
+  paths: string[];
+  preset?: PresetName | undefined;
+  fix?: boolean | undefined;
+  quiet?: boolean | undefined;
+  ruleOverrides?: Record<string, Severity> | undefined;
+  config?: string | undefined;
+  ignore?: string | undefined;
+}
+interface ImportInfo {
+  source: string;
+  specifiers: Array<{
+    imported: string;
+    local: string;
+  }>;
+  isDefault: boolean;
+  isNamespace: boolean;
+}
+//#endregion
+//#region src/utils/source.d.ts
+/**
+ * Fast offset→line/column conversion using binary search over precomputed line starts.
+ */
+declare class LineIndex {
+  private lineStarts;
+  constructor(sourceText: string);
+  /** Convert a byte offset to a 1-based line and 0-based column. */
+  locate(offset: number): SourceLocation;
+}
+//#endregion
+//#region src/cache.d.ts
+/**
+ * Simple in-memory cache for parsed ASTs keyed by file content hash.
+ *
+ * Uses FNV-1a hash of source text as cache key for fast lookups
+ * during repeat runs (e.g., watch mode).
+ *
+ * @example
+ * ```ts
+ * import { AstCache } from "@pyreon/lint"
+ *
+ * const cache = new AstCache()
+ * const cached = cache.get(sourceText)
+ * if (!cached) {
+ *   const parsed = parse(sourceText)
+ *   cache.set(sourceText, parsed)
+ * }
+ * ```
+ */
+declare class AstCache {
+  private cache;
+  get(sourceText: string): {
+    program: any;
+    lineIndex: LineIndex;
+  } | undefined;
+  set(sourceText: string, value: {
+    program: any;
+    lineIndex: LineIndex;
+  }): void;
+  clear(): void;
+  get size(): number;
+}
+//#endregion
+//#region src/config/ignore.d.ts
+/**
+ * Create a filter function that returns true if a file path should be ignored.
+ *
+ * Loads patterns from `.pyreonlintignore` and `.gitignore` in the given directory.
+ *
+ * @example
+ * ```ts
+ * import { createIgnoreFilter } from "@pyreon/lint"
+ *
+ * const isIgnored = createIgnoreFilter(process.cwd())
+ * if (!isIgnored("src/app.tsx")) lintFile(...)
+ * ```
+ */
+declare function createIgnoreFilter(cwd: string, extraIgnore?: string | undefined): (filePath: string) => boolean;
+//#endregion
+//#region src/config/loader.d.ts
+/**
+ * Load a lint config file from the given directory or its parents.
+ *
+ * Search order:
+ * 1. `.pyreonlintrc.json`
+ * 2. `.pyreonlintrc`
+ * 3. `pyreonlint.config.json`
+ * 4. `package.json` `"pyreonlint"` field
+ *
+ * @example
+ * ```ts
+ * import { loadConfig } from "@pyreon/lint"
+ *
+ * const config = loadConfig(process.cwd())
+ * if (config) console.log(config.preset)
+ * ```
+ */
+declare function loadConfig(cwd: string): LintConfigFile | null;
+/**
+ * Load a config file from a specific path.
+ */
+declare function loadConfigFromPath(filePath: string): LintConfigFile | null;
+//#endregion
+//#region src/config/presets.d.ts
+declare function getPreset(name: PresetName): LintConfig;
+//#endregion
+//#region src/lint.d.ts
+/**
+ * Lint files and return results.
+ *
+ * @example
+ * ```ts
+ * import { lint } from "@pyreon/lint"
+ *
+ * const result = lint({ paths: ["src/"], preset: "recommended" })
+ * console.log(result.totalErrors) // 0
+ * ```
+ */
+declare function lint(options: LintOptions): LintResult;
+/**
+ * List all available rules with their metadata.
+ *
+ * @example
+ * ```ts
+ * import { listRules } from "@pyreon/lint"
+ *
+ * for (const rule of listRules()) {
+ *   console.log(`${rule.id} (${rule.severity}): ${rule.description}`)
+ * }
+ * ```
+ */
+declare function listRules(): RuleMeta[];
+//#endregion
+//#region src/reporter.d.ts
+/**
+ * Format results as human-readable colored text.
+ */
+declare function formatText(result: LintResult): string;
+/**
+ * Format results as JSON.
+ */
+declare function formatJSON(result: LintResult): string;
+/**
+ * Format results as compact single-line-per-diagnostic output.
+ */
+declare function formatCompact(result: LintResult): string;
+//#endregion
+//#region src/rules/index.d.ts
+declare const allRules: Rule[];
+//#endregion
+//#region src/runner.d.ts
+/**
+ * Lint a single file and return diagnostics.
+ *
+ * @example
+ * ```ts
+ * const result = lintFile("app.tsx", source, allRules, getPreset("recommended"))
+ * 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;
+/**
+ * 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/imports.d.ts
+declare function isPyreonImport(source: string): boolean;
+declare function isPyreonPackage(source: string): boolean;
+declare function extractImportInfo(node: any): ImportInfo | null;
+declare function importsName(imports: ImportInfo[], name: string, fromPackage?: string): boolean;
+declare function getLocalName(imports: ImportInfo[], name: string, fromPackage?: string): string | null;
+//#endregion
+//#region src/watcher.d.ts
+/**
+ * Watch directories and re-lint changed files.
+ *
+ * Uses `fs.watch` (recursive) with 100ms debounce.
+ * Caches ASTs for unchanged files.
+ *
+ * @example
+ * ```ts
+ * import { watchAndLint } from "@pyreon/lint"
+ *
+ * watchAndLint({ paths: ["src/"], preset: "recommended", format: "text" })
+ * ```
+ */
+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, watchAndLint };
+//# sourceMappingURL=index2.d.ts.map

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

@@ -0,0 +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/rules/index.ts","../../../src/runner.ts","../../../src/utils/imports.ts","../../../src/watcher.ts"],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@pyreon/lint",
+  "version": "0.11.0",
+  "description": "Pyreon-specific linter — 55 rules for signals, JSX, SSR, performance, router, and architecture",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pyreon/pyreon.git",
+    "directory": "packages/tools/lint"
+  },
+  "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/lint#readme",
+  "bugs": {
+    "url": "https://github.com/pyreon/pyreon/issues"
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "bin": {
+    "pyreon-lint": "./lib/cli.js"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./lib/index.js",
+      "types": "./lib/types/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "vl_rolldown_build",
+    "dev": "vl_rolldown_build-watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "oxc-parser": "^0.121.0",
+    "@oxc-project/types": "^0.121.0"
+  },
+  "devDependencies": {
+    "oxc-parser": "^0.121.0",
+    "@oxc-project/types": "^0.121.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cache.ts

@@ -0,0 +1,51 @@
+import type { LineIndex } from "./utils/source"
+
+/**
+ * Simple in-memory cache for parsed ASTs keyed by file content hash.
+ *
+ * Uses FNV-1a hash of source text as cache key for fast lookups
+ * during repeat runs (e.g., watch mode).
+ *
+ * @example
+ * ```ts
+ * import { AstCache } from "@pyreon/lint"
+ *
+ * const cache = new AstCache()
+ * const cached = cache.get(sourceText)
+ * if (!cached) {
+ *   const parsed = parse(sourceText)
+ *   cache.set(sourceText, parsed)
+ * }
+ * ```
+ */
+export class AstCache {
+  private cache = new Map<string, { program: any; lineIndex: LineIndex }>()
+
+  get(sourceText: string): { program: any; lineIndex: LineIndex } | undefined {
+    const key = fnv1aHash(sourceText)
+    return this.cache.get(key)
+  }
+
+  set(sourceText: string, value: { program: any; lineIndex: LineIndex }): void {
+    const key = fnv1aHash(sourceText)
+    this.cache.set(key, value)
+  }
+
+  clear(): void {
+    this.cache.clear()
+  }
+
+  get size(): number {
+    return this.cache.size
+  }
+}
+
+/** FNV-1a hash — fast, non-cryptographic, low collision rate. */
+function fnv1aHash(str: string): string {
+  let hash = 0x811c9dc5 // FNV offset basis
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i)
+    hash = (hash * 0x01000193) | 0 // FNV prime, keep 32-bit
+  }
+  return (hash >>> 0).toString(36)
+}

package/src/cli.ts

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+import { lint, listRules } from "./lint"
+import { formatCompact, formatJSON, formatText } from "./reporter"
+import type { PresetName, Severity } from "./types"
+import { watchAndLint } from "./watcher"
+
+const VERSION = "0.10.0"
+
+function printUsage() {
+  console.log(`
+  pyreon-lint [options] [path...]
+
+  Options:
+    --preset <name>    Preset: recommended (default), strict, app, lib
+    --fix              Auto-fix fixable issues
+    --format <fmt>     Output: text (default), json, compact
+    --quiet            Only show errors
+    --list             List all available rules
+    --rule <id>=<sev>  Override rule severity
+    --config <path>    Config file path
+    --ignore <path>    Ignore file path
+    --watch            Watch mode — re-lint on file changes
+    --help, -h         Show this help
+    --version, -v      Show version
+`)
+}
+
+function printList() {
+  const rules = listRules()
+  const maxId = Math.max(...rules.map((r) => r.id.length))
+  const maxCat = Math.max(...rules.map((r) => r.category.length))
+
+  for (const rule of rules) {
+    const fixLabel = rule.fixable ? " [fixable]" : ""
+    const id = rule.id.padEnd(maxId)
+    const cat = rule.category.padEnd(maxCat)
+    const sev = rule.severity.padEnd(5)
+    console.log(`  ${id}  ${cat}  ${sev}  ${rule.description}${fixLabel}`)
+  }
+
+  console.log(`\n  ${rules.length} rules total`)
+}
+
+interface CliArgs {
+  preset: PresetName
+  fix: boolean
+  format: "text" | "json" | "compact"
+  quiet: boolean
+  showList: boolean
+  showHelp: boolean
+  showVersion: boolean
+  watchMode: boolean
+  configPath: string | undefined
+  ignorePath: string | undefined
+  ruleOverrides: Record<string, Severity>
+  paths: string[]
+}
+
+const BOOLEAN_FLAGS: Record<string, keyof CliArgs> = {
+  "--help": "showHelp",
+  "-h": "showHelp",
+  "--version": "showVersion",
+  "-v": "showVersion",
+  "--list": "showList",
+  "--fix": "fix",
+  "--quiet": "quiet",
+  "--watch": "watchMode",
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const result: CliArgs = {
+    preset: "recommended",
+    fix: false,
+    format: "text",
+    quiet: false,
+    showList: false,
+    showHelp: false,
+    showVersion: false,
+    watchMode: false,
+    configPath: undefined,
+    ignorePath: undefined,
+    ruleOverrides: {},
+    paths: [],
+  }
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i] as string
+    const boolKey = BOOLEAN_FLAGS[arg]
+
+    if (boolKey) {
+      ;(result as unknown as Record<string, unknown>)[boolKey] = true
+      continue
+    }
+
+    const consumed = parseValueFlag(arg, argv[i + 1], result)
+    i += consumed
+  }
+
+  return result
+}
+
+/** Returns number of extra args consumed (0 or 1). */
+function parseValueFlag(arg: string, nextArg: string | undefined, result: CliArgs): number {
+  if (arg === "--preset") {
+    result.preset = (nextArg ?? "recommended") as PresetName
+    return 1
+  }
+  if (arg === "--format") {
+    result.format = (nextArg ?? "text") as "text" | "json" | "compact"
+    return 1
+  }
+  if (arg === "--config") {
+    result.configPath = nextArg
+    return 1
+  }
+  if (arg === "--ignore") {
+    result.ignorePath = nextArg
+    return 1
+  }
+  if (arg === "--rule") {
+    parseRuleOverride(nextArg, result.ruleOverrides)
+    return 1
+  }
+  if (arg) {
+    result.paths.push(arg)
+  }
+  return 0
+}
+
+function parseRuleOverride(val: string | undefined, overrides: Record<string, Severity>): void {
+  if (!val) return
+  const eqIdx = val.lastIndexOf("=")
+  if (eqIdx === -1) return
+  const ruleId = val.slice(0, eqIdx)
+  const severity = val.slice(eqIdx + 1) as Severity
+  overrides[ruleId] = severity
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+
+  if (args.showHelp) {
+    printUsage()
+    process.exit(0)
+  }
+
+  if (args.showVersion) {
+    console.log(`pyreon-lint v${VERSION}`)
+    process.exit(0)
+  }
+
+  if (args.showList) {
+    printList()
+    process.exit(0)
+  }
+
+  if (args.paths.length === 0) {
+    args.paths.push(".")
+  }
+
+  if (args.watchMode) {
+    watchAndLint({
+      paths: args.paths,
+      preset: args.preset,
+      fix: args.fix,
+      quiet: args.quiet,
+      ruleOverrides: args.ruleOverrides,
+      config: args.configPath,
+      ignore: args.ignorePath,
+      format: args.format,
+    })
+    return
+  }
+
+  const result = lint({
+    paths: args.paths,
+    preset: args.preset,
+    fix: args.fix,
+    quiet: args.quiet,
+    ruleOverrides: args.ruleOverrides,
+    config: args.configPath,
+    ignore: args.ignorePath,
+  })
+
+  if (args.format === "json") {
+    console.log(formatJSON(result))
+  } else if (args.format === "compact") {
+    console.log(formatCompact(result))
+  } else {
+    const output = formatText(result)
+    if (output) console.log(output)
+  }
+
+  if (result.totalErrors > 0) {
+    process.exit(1)
+  }
+}
+
+main()