@pyreon/lint 0.11.0

package/src/config/ignore.ts

@@ -0,0 +1,159 @@
+import { existsSync, readFileSync } from "node:fs"
+import { join, relative, resolve } from "node:path"
+
+/**
+ * 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(...)
+ * ```
+ */
+export function createIgnoreFilter(
+  cwd: string,
+  extraIgnore?: string | undefined,
+): (filePath: string) => boolean {
+  const patterns: string[] = []
+  const resolvedCwd = resolve(cwd)
+
+  // Load .pyreonlintignore
+  loadPatternsFromFile(join(resolvedCwd, ".pyreonlintignore"), patterns)
+
+  // Load .gitignore
+  loadPatternsFromFile(join(resolvedCwd, ".gitignore"), patterns)
+
+  // Load extra ignore file if provided
+  if (extraIgnore) {
+    loadPatternsFromFile(resolve(extraIgnore), patterns)
+  }
+
+  // Compile patterns into matchers
+  const matchers = patterns.map((p) => compileMatcher(p))
+
+  return (filePath: string): boolean => {
+    const rel = relative(resolvedCwd, resolve(filePath))
+    // Normalize to forward slashes
+    const normalized = rel.replace(/\\/g, "/")
+
+    for (const matcher of matchers) {
+      if (matcher(normalized)) return true
+    }
+    return false
+  }
+}
+
+function loadPatternsFromFile(filePath: string, patterns: string[]): void {
+  if (!existsSync(filePath)) return
+  try {
+    const content = readFileSync(filePath, "utf-8")
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim()
+      // Skip empty lines and comments
+      if (!trimmed || trimmed.startsWith("#")) continue
+      patterns.push(trimmed)
+    }
+  } catch {
+    // Ignore read errors
+  }
+}
+
+/**
+ * Compile a gitignore-style pattern into a matcher function.
+ * Supports: `*` (any non-slash chars), `**` (any path segment), `?` (single char),
+ * leading `/` (root-anchored), trailing `/` (directory only).
+ */
+function compileMatcher(pattern: string): (path: string) => boolean {
+  let p = pattern
+  let anchored = false
+
+  // Negated patterns (not supported — just skip them)
+  if (p.startsWith("!")) {
+    return () => false
+  }
+
+  // Leading slash means anchored to root
+  if (p.startsWith("/")) {
+    anchored = true
+    p = p.slice(1)
+  }
+
+  // Trailing slash means only match directories (we treat all paths as files, so strip it
+  // and match as a prefix)
+  let dirOnly = false
+  if (p.endsWith("/")) {
+    dirOnly = true
+    p = p.slice(0, -1)
+  }
+
+  const regex = globToRegex(p)
+
+  return (path: string): boolean => {
+    if (dirOnly) {
+      // Match as prefix: the pattern should match a directory portion
+      if (anchored) {
+        return regex.test(path) || path.startsWith(`${p}/`) || path === p
+      }
+      // Unanchored directory pattern — match anywhere in path
+      return regex.test(path) || path.includes(`/${p}/`) || path.startsWith(`${p}/`) || path === p
+    }
+
+    if (anchored) {
+      return regex.test(path)
+    }
+
+    // Unanchored pattern — try matching the full path, or just the basename
+    if (regex.test(path)) return true
+
+    // Also try matching against just the filename
+    const lastSlash = path.lastIndexOf("/")
+    if (lastSlash !== -1) {
+      const basename = path.slice(lastSlash + 1)
+      return regex.test(basename)
+    }
+
+    return false
+  }
+}
+
+const GLOB_CHAR_MAP: Record<string, string> = {
+  "?": "[^/]",
+  ".": "\\.",
+  "/": "/",
+}
+
+function handleStar(glob: string, pos: number): { pattern: string; advance: number } {
+  if (glob[pos + 1] === "*") {
+    if (glob[pos + 2] === "/") return { pattern: "(?:.*/)?", advance: 3 }
+    return { pattern: ".*", advance: 2 }
+  }
+  return { pattern: "[^/]*", advance: 1 }
+}
+
+function globToRegex(glob: string): RegExp {
+  let result = "^"
+  let i = 0
+
+  while (i < glob.length) {
+    const ch = glob[i] as string
+    if (ch === "*") {
+      const star = handleStar(glob, i)
+      result += star.pattern
+      i += star.advance
+    } else {
+      result += GLOB_CHAR_MAP[ch] ?? escapeRegex(ch)
+      i++
+    }
+  }
+
+  result += "$"
+  return new RegExp(result)
+}
+
+function escapeRegex(str: string): string {
+  return str.replace(/[\\^$+{}[\]|()]/g, "\\$&")
+}

package/src/config/loader.ts

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import type { LintConfigFile } from "../types"
+
+const CONFIG_FILENAMES = [".pyreonlintrc.json", ".pyreonlintrc", "pyreonlint.config.json"]
+
+/**
+ * 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)
+ * ```
+ */
+export function loadConfig(cwd: string): LintConfigFile | null {
+  let dir = resolve(cwd)
+  const root = dirname(dir)
+
+  while (true) {
+    const found = searchDirectory(dir)
+    if (found !== null) return found
+
+    const parent = dirname(dir)
+    if (parent === dir || parent === root) break
+    dir = parent
+  }
+
+  return null
+}
+
+function searchDirectory(dir: string): LintConfigFile | null {
+  for (const filename of CONFIG_FILENAMES) {
+    const content = tryReadJson(join(dir, filename))
+    if (content !== null) return content
+  }
+  return extractPkgConfig(join(dir, "package.json"))
+}
+
+function extractPkgConfig(pkgPath: string): LintConfigFile | null {
+  const pkg = tryReadJson(pkgPath)
+  if (pkg === null || typeof pkg !== "object" || !("pyreonlint" in pkg)) return null
+  const field = (pkg as Record<string, unknown>).pyreonlint
+  if (field && typeof field === "object") return field as LintConfigFile
+  return null
+}
+
+/**
+ * Load a config file from a specific path.
+ */
+export function loadConfigFromPath(filePath: string): LintConfigFile | null {
+  return tryReadJson(resolve(filePath))
+}
+
+function tryReadJson(filePath: string): any | null {
+  if (!existsSync(filePath)) return null
+  try {
+    const raw = readFileSync(filePath, "utf-8").trim()
+    if (!raw) return null
+    return JSON.parse(raw)
+  } catch {
+    return null
+  }
+}

package/src/config/presets.ts

@@ -0,0 +1,62 @@
+import { allRules } from "../rules/index"
+import type { LintConfig, PresetName, Severity } from "../types"
+
+/** Build a config where every rule uses its default severity. */
+function buildRecommended(): LintConfig {
+  const rules: Record<string, Severity> = {}
+  for (const rule of allRules) {
+    rules[rule.meta.id] = rule.meta.severity
+  }
+  return { rules }
+}
+
+/** 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)) {
+    rules[id] = sev === "warn" ? "error" : sev
+  }
+  return { rules }
+}
+
+/** Build app config — recommended but disable library-only rules. */
+function buildApp(): LintConfig {
+  const base = buildRecommended()
+  return {
+    rules: {
+      ...base.rules,
+      "pyreon/dev-guard-warnings": "off",
+      "pyreon/no-error-without-prefix": "off",
+      "pyreon/no-circular-import": "off",
+      "pyreon/no-cross-layer-import": "off",
+    },
+  }
+}
+
+/** Build lib config — strict + all architecture rules as error. */
+function buildLib(): LintConfig {
+  const base = buildStrict()
+  return {
+    rules: {
+      ...base.rules,
+      "pyreon/no-circular-import": "error",
+      "pyreon/no-cross-layer-import": "error",
+      "pyreon/dev-guard-warnings": "error",
+      "pyreon/no-error-without-prefix": "error",
+    },
+  }
+}
+
+const presetBuilders: Record<PresetName, () => LintConfig> = {
+  recommended: buildRecommended,
+  strict: buildStrict,
+  app: buildApp,
+  lib: buildLib,
+}
+
+export function getPreset(name: PresetName): LintConfig {
+  return presetBuilders[name]()
+}
+
+export { buildApp, buildLib, buildRecommended, buildStrict }

package/src/index.ts

@@ -0,0 +1,40 @@
+// Core API
+export { AstCache } from "./cache"
+export { createIgnoreFilter } from "./config/ignore"
+export { loadConfig, loadConfigFromPath } from "./config/loader"
+export { getPreset } from "./config/presets"
+export { lint, listRules } from "./lint"
+export { formatCompact, formatJSON, formatText } from "./reporter"
+// Rules
+export { allRules } from "./rules/index"
+export { applyFixes, lintFile } from "./runner"
+// Types
+export type {
+  Diagnostic,
+  Fix,
+  ImportInfo,
+  LintConfig,
+  LintConfigFile,
+  LintFileResult,
+  LintOptions,
+  LintResult,
+  PresetName,
+  Rule,
+  RuleCategory,
+  RuleContext,
+  RuleMeta,
+  Severity,
+  SourceLocation,
+  Span,
+  VisitorCallbacks,
+} from "./types"
+export {
+  extractImportInfo,
+  getLocalName,
+  importsName,
+  isPyreonImport,
+  isPyreonPackage,
+} from "./utils/imports"
+// Utilities
+export { LineIndex } from "./utils/source"
+export { watchAndLint } from "./watcher"

package/src/lint.ts

@@ -0,0 +1,226 @@
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { AstCache } from "./cache"
+import { createIgnoreFilter } from "./config/ignore"
+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"
+
+const JS_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs"])
+
+function isHiddenOrVendor(entry: string): boolean {
+  return entry.startsWith(".") || entry === "node_modules" || entry === "lib" || entry === "dist"
+}
+
+function hasJsExtension(filePath: string): boolean {
+  const ext = filePath.slice(filePath.lastIndexOf("."))
+  return JS_EXTENSIONS.has(ext)
+}
+
+function matchesPatterns(
+  filePath: string,
+  include?: string[] | undefined,
+  exclude?: string[] | undefined,
+): boolean {
+  if (exclude) {
+    for (const pattern of exclude) {
+      if (filePath.includes(pattern)) return false
+    }
+  }
+  if (include && include.length > 0) {
+    for (const pattern of include) {
+      if (filePath.includes(pattern)) return true
+    }
+    return false
+  }
+  return true
+}
+
+function walkDirectory(
+  dir: string,
+  files: string[],
+  isIgnored: (filePath: string) => boolean,
+  include?: string[] | undefined,
+  exclude?: string[] | undefined,
+): void {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    if (isHiddenOrVendor(entry)) continue
+    const full = join(dir, entry)
+    if (isIgnored(full)) continue
+    processEntry(full, files, isIgnored, include, exclude)
+  }
+}
+
+function processEntry(
+  full: string,
+  files: string[],
+  isIgnored: (filePath: string) => boolean,
+  include?: string[] | undefined,
+  exclude?: string[] | undefined,
+): void {
+  let stat: ReturnType<typeof statSync>
+  try {
+    stat = statSync(full)
+  } catch {
+    return
+  }
+  if (stat.isDirectory()) {
+    walkDirectory(full, files, isIgnored, include, exclude)
+  } else if (stat.isFile() && hasJsExtension(full) && matchesPatterns(full, include, exclude)) {
+    files.push(full)
+  }
+}
+
+function collectFiles(
+  dir: string,
+  isIgnored: (filePath: string) => boolean,
+  include?: string[] | undefined,
+  exclude?: string[] | undefined,
+): string[] {
+  const files: string[] = []
+  walkDirectory(dir, files, isIgnored, include, exclude)
+  return files
+}
+
+function buildConfig(options: LintOptions): {
+  config: LintConfig
+  include: string[] | undefined
+  exclude: string[] | undefined
+  isIgnored: (filePath: string) => boolean
+} {
+  const cwd = resolve(".")
+  const fileConfig = options.config ? loadConfigFromPath(options.config) : loadConfig(cwd)
+
+  const presetName = options.preset ?? fileConfig?.preset ?? "recommended"
+  const config = getPreset(presetName)
+
+  // Merge config file rule overrides
+  if (fileConfig?.rules) {
+    for (const [id, severity] of Object.entries(fileConfig.rules)) {
+      config.rules[id] = severity
+    }
+  }
+
+  // CLI rule overrides (highest priority)
+  if (options.ruleOverrides) {
+    for (const [id, severity] of Object.entries(options.ruleOverrides)) {
+      config.rules[id] = severity
+    }
+  }
+
+  return {
+    config,
+    include: fileConfig?.include,
+    exclude: fileConfig?.exclude,
+    isIgnored: createIgnoreFilter(cwd, options.ignore),
+  }
+}
+
+function gatherFiles(
+  paths: string[],
+  isIgnored: (filePath: string) => boolean,
+  include?: string[] | undefined,
+  exclude?: string[] | undefined,
+): string[] {
+  const files: string[] = []
+  for (const p of paths) {
+    const resolved = resolve(p)
+    let stat: ReturnType<typeof statSync>
+    try {
+      stat = statSync(resolved)
+    } catch {
+      continue
+    }
+    if (stat.isDirectory()) {
+      files.push(...collectFiles(resolved, isIgnored, include, exclude))
+    } else if (stat.isFile() && !isIgnored(resolved)) {
+      files.push(resolved)
+    }
+  }
+  return files
+}
+
+function applyFixesToFile(fileResult: LintFileResult, source: string): void {
+  const fixable = fileResult.diagnostics.filter((d) => d.fix)
+  if (fixable.length === 0) return
+  const fixed = applyFixes(source, fileResult.diagnostics)
+  writeFileSync(fileResult.filePath, fixed, "utf-8")
+  fileResult.fixedSource = fixed
+  fileResult.diagnostics = fileResult.diagnostics.filter((d) => !d.fix)
+}
+
+function countDiagnostics(fileResult: LintFileResult, results: LintResult): void {
+  for (const d of fileResult.diagnostics) {
+    if (d.severity === "error") results.totalErrors++
+    else if (d.severity === "warn") results.totalWarnings++
+    else if (d.severity === "info") results.totalInfos++
+  }
+}
+
+/**
+ * Lint files and return results.
+ *
+ * @example
+ * ```ts
+ * import { lint } from "@pyreon/lint"
+ *
+ * const result = lint({ paths: ["src/"], preset: "recommended" })
+ * console.log(result.totalErrors) // 0
+ * ```
+ */
+export function lint(options: LintOptions): LintResult {
+  const { config, include, exclude, isIgnored } = buildConfig(options)
+  const cache = new AstCache()
+  const files = gatherFiles(options.paths, isIgnored, include, exclude)
+
+  const results: LintResult = {
+    files: [],
+    totalErrors: 0,
+    totalWarnings: 0,
+    totalInfos: 0,
+  }
+
+  for (const filePath of files) {
+    let source: string
+    try {
+      source = readFileSync(filePath, "utf-8")
+    } catch {
+      continue
+    }
+    const fileResult = lintFile(filePath, source, allRules, config, cache)
+    if (options.fix) {
+      applyFixesToFile(fileResult, source)
+    }
+    if (options.quiet) {
+      fileResult.diagnostics = fileResult.diagnostics.filter((d) => d.severity === "error")
+    }
+    countDiagnostics(fileResult, results)
+    results.files.push(fileResult)
+  }
+
+  return results
+}
+
+/**
+ * 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}`)
+ * }
+ * ```
+ */
+export function listRules(): RuleMeta[] {
+  return allRules.map((r) => r.meta)
+}

package/src/reporter.ts

@@ -0,0 +1,85 @@
+import type { LintResult, Severity } from "./types"
+
+// ANSI colors
+const BOLD = "\x1b[1m"
+const RED = "\x1b[31m"
+const YELLOW = "\x1b[33m"
+const BLUE = "\x1b[34m"
+const DIM = "\x1b[2m"
+const RESET = "\x1b[0m"
+
+const SEVERITY_SYMBOL: Record<Severity, string> = {
+  error: `${RED}\u2716${RESET}`,
+  warn: `${YELLOW}\u26A0${RESET}`,
+  info: `${BLUE}\u2139${RESET}`,
+  off: "",
+}
+
+const SEVERITY_LABEL: Record<Severity, string> = {
+  error: `${RED}error${RESET}`,
+  warn: `${YELLOW}warning${RESET}`,
+  info: `${BLUE}info${RESET}`,
+  off: "",
+}
+
+/**
+ * Format results as human-readable colored text.
+ */
+export function formatText(result: LintResult): string {
+  const lines: string[] = []
+
+  for (const file of result.files) {
+    if (file.diagnostics.length === 0) continue
+
+    lines.push("")
+    lines.push(`${BOLD}${file.filePath}${RESET}`)
+
+    for (const d of file.diagnostics) {
+      const loc = `${DIM}${d.loc.line}:${d.loc.column}${RESET}`
+      const severity = SEVERITY_LABEL[d.severity]
+      const ruleId = `${DIM}${d.ruleId}${RESET}`
+      lines.push(`  ${loc}  ${severity}  ${d.message}  ${ruleId}`)
+    }
+  }
+
+  const total = result.totalErrors + result.totalWarnings + result.totalInfos
+  if (total > 0) {
+    lines.push("")
+    const parts: string[] = []
+    if (result.totalErrors > 0)
+      parts.push(`${RED}${result.totalErrors} error${result.totalErrors === 1 ? "" : "s"}${RESET}`)
+    if (result.totalWarnings > 0)
+      parts.push(
+        `${YELLOW}${result.totalWarnings} warning${result.totalWarnings === 1 ? "" : "s"}${RESET}`,
+      )
+    if (result.totalInfos > 0) parts.push(`${BLUE}${result.totalInfos} info${RESET}`)
+    lines.push(`${SEVERITY_SYMBOL.error} ${parts.join(", ")}`)
+    lines.push("")
+  }
+
+  return lines.join("\n")
+}
+
+/**
+ * Format results as JSON.
+ */
+export function formatJSON(result: LintResult): string {
+  return JSON.stringify(result, null, 2)
+}
+
+/**
+ * Format results as compact single-line-per-diagnostic output.
+ */
+export function formatCompact(result: LintResult): string {
+  const lines: string[] = []
+
+  for (const file of result.files) {
+    for (const d of file.diagnostics) {
+      lines.push(
+        `${file.filePath}:${d.loc.line}:${d.loc.column}: ${d.severity} [${d.ruleId}] ${d.message}`,
+      )
+    }
+  }
+
+  return lines.join("\n")
+}

package/src/rules/accessibility/dialog-a11y.ts

@@ -0,0 +1,32 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan, hasJSXAttribute } from "../../utils/ast"
+
+export const dialogA11y: Rule = {
+  meta: {
+    id: "pyreon/dialog-a11y",
+    category: "accessibility",
+    description: "Warn when <dialog> is missing aria-label or aria-labelledby.",
+    severity: "warn",
+    fixable: false,
+  },
+  create(context) {
+    const callbacks: VisitorCallbacks = {
+      JSXOpeningElement(node: any) {
+        const name = node.name
+        if (!name || name.type !== "JSXIdentifier" || name.name !== "dialog") return
+
+        const hasLabel = hasJSXAttribute(node, "aria-label")
+        const hasLabelledBy = hasJSXAttribute(node, "aria-labelledby")
+
+        if (!hasLabel && !hasLabelledBy) {
+          context.report({
+            message:
+              "`<dialog>` missing `aria-label` or `aria-labelledby` — provide an accessible label for screen readers.",
+            span: getSpan(node),
+          })
+        }
+      },
+    }
+    return callbacks
+  },
+}