@pyreon/lint 0.11.0

package/src/types.ts

@@ -0,0 +1,125 @@
+// ── Severity & Diagnostics ──────────────────────────────────────────────────
+
+export type Severity = "error" | "warn" | "info" | "off"
+
+export interface SourceLocation {
+  line: number
+  column: number
+}
+
+export interface Span {
+  start: number
+  end: number
+}
+
+export interface Fix {
+  span: Span
+  replacement: string
+}
+
+export interface Diagnostic {
+  ruleId: string
+  severity: Severity
+  message: string
+  span: Span
+  loc: SourceLocation
+  fix?: Fix | undefined
+}
+
+// ── Rule Metadata ───────────────────────────────────────────────────────────
+
+export type RuleCategory =
+  | "reactivity"
+  | "jsx"
+  | "lifecycle"
+  | "performance"
+  | "ssr"
+  | "architecture"
+  | "store"
+  | "form"
+  | "styling"
+  | "hooks"
+  | "accessibility"
+  | "router"
+
+export interface RuleMeta {
+  id: string
+  category: RuleCategory
+  description: string
+  severity: Severity
+  fixable: boolean
+}
+
+// ── Rule Context & Visitor ──────────────────────────────────────────────────
+
+export interface RuleContext {
+  report(diagnostic: Omit<Diagnostic, "ruleId" | "severity" | "loc">): void
+  getSourceText(): string
+  getFilePath(): string
+}
+
+export type VisitorCallback = (node: any, parent?: any) => void
+
+export interface VisitorCallbacks {
+  [nodeType: string]: VisitorCallback
+}
+
+// ── Rule Definition ─────────────────────────────────────────────────────────
+
+export interface Rule {
+  meta: RuleMeta
+  create(context: RuleContext): VisitorCallbacks
+}
+
+// ── Configuration ───────────────────────────────────────────────────────────
+
+export interface LintConfig {
+  rules: Record<string, Severity>
+  include?: string[] | undefined
+  exclude?: string[] | undefined
+}
+
+export interface LintConfigFile {
+  preset?: PresetName | undefined
+  rules?: Record<string, Severity> | undefined
+  include?: string[] | undefined
+  exclude?: string[] | undefined
+}
+
+export type PresetName = "recommended" | "strict" | "app" | "lib"
+
+// ── Results ─────────────────────────────────────────────────────────────────
+
+export interface LintFileResult {
+  filePath: string
+  diagnostics: Diagnostic[]
+  fixedSource?: string | undefined
+}
+
+export interface LintResult {
+  files: LintFileResult[]
+  totalErrors: number
+  totalWarnings: number
+  totalInfos: number
+}
+
+// ── Lint Options ────────────────────────────────────────────────────────────
+
+export interface LintOptions {
+  paths: string[]
+  preset?: PresetName | undefined
+  fix?: boolean | undefined
+  quiet?: boolean | undefined
+  ruleOverrides?: Record<string, Severity> | undefined
+  config?: string | undefined
+  ignore?: string | undefined
+}
+
+// ── Import Info ─────────────────────────────────────────────────────────────
+
+export interface ImportInfo {
+  source: string
+  specifiers: Array<{ imported: string; local: string }>
+  isDefault: boolean
+  isNamespace: boolean
+}

package/src/utils/ast.ts

@@ -0,0 +1,192 @@
+import type { Span } from "../types"
+import { BROWSER_GLOBALS } from "./imports"
+
+/** Check if a node is a call expression to a specific function name. */
+export function isCallTo(node: any, name: string): boolean {
+  return (
+    node.type === "CallExpression" &&
+    node.callee?.type === "Identifier" &&
+    node.callee.name === name
+  )
+}
+
+/** Check if a node is a call expression to any of the given function names. */
+export function isCallToAny(node: any, names: Set<string>): boolean {
+  return (
+    node.type === "CallExpression" &&
+    node.callee?.type === "Identifier" &&
+    names.has(node.callee.name)
+  )
+}
+
+/** Check if a node is a member call like `obj.method()`. */
+export function isMemberCallTo(node: any, objectName: string, methodName: string): boolean {
+  return (
+    node.type === "CallExpression" &&
+    node.callee?.type === "MemberExpression" &&
+    node.callee.object?.type === "Identifier" &&
+    node.callee.object.name === objectName &&
+    node.callee.property?.type === "Identifier" &&
+    node.callee.property.name === methodName
+  )
+}
+
+/** Check if a node is a JSX element (opening or self-closing). */
+export function isJSXElement(node: any): boolean {
+  return node.type === "JSXElement" || node.type === "JSXFragment"
+}
+
+/** Get the tag name of a JSX element. */
+export function getJSXTagName(node: any): string | null {
+  if (node.type === "JSXElement") {
+    const opening = node.openingElement
+    if (!opening) return null
+    const name = opening.name
+    if (name?.type === "JSXIdentifier") return name.name
+    if (name?.type === "JSXMemberExpression") {
+      return `${name.object?.name ?? ""}.${name.property?.name ?? ""}`
+    }
+  }
+  return null
+}
+
+/** Get a JSX attribute by name from an opening element. */
+export function getJSXAttribute(openingElement: any, attrName: string): any | null {
+  const attrs = openingElement.attributes ?? []
+  for (const attr of attrs) {
+    if (
+      attr.type === "JSXAttribute" &&
+      attr.name?.type === "JSXIdentifier" &&
+      attr.name.name === attrName
+    ) {
+      return attr
+    }
+  }
+  return null
+}
+
+/** Check if a JSX opening element has an attribute. */
+export function hasJSXAttribute(openingElement: any, attrName: string): boolean {
+  return getJSXAttribute(openingElement, attrName) !== null
+}
+
+/** Check if a node is inside a function (arrow or regular). */
+export function isInsideFunction(ancestors: any[]): boolean {
+  return ancestors.some(
+    (a) =>
+      a.type === "FunctionDeclaration" ||
+      a.type === "FunctionExpression" ||
+      a.type === "ArrowFunctionExpression",
+  )
+}
+
+/** Check if a node is inside JSX. */
+export function isInsideJSX(ancestors: any[]): boolean {
+  return ancestors.some((a) => a.type === "JSXElement" || a.type === "JSXFragment")
+}
+
+/** Check if a node is an array .map() call. */
+export function isArrayMapCall(node: any): boolean {
+  return (
+    node.type === "CallExpression" &&
+    node.callee?.type === "MemberExpression" &&
+    node.callee.property?.type === "Identifier" &&
+    node.callee.property.name === "map"
+  )
+}
+
+/** Check if a node is a function expression or arrow function. */
+export function isFunction(node: any): boolean {
+  return (
+    node.type === "FunctionDeclaration" ||
+    node.type === "FunctionExpression" ||
+    node.type === "ArrowFunctionExpression"
+  )
+}
+
+/** Check if a node is a destructuring pattern. */
+export function isDestructuring(node: any): boolean {
+  return node.type === "ObjectPattern" || node.type === "ArrayPattern"
+}
+
+/** Check if a node is a ternary with JSX in either branch. */
+export function isTernaryWithJSX(node: any): boolean {
+  if (node.type !== "ConditionalExpression") return false
+  return containsJSX(node.consequent) || containsJSX(node.alternate)
+}
+
+/** Check if a node contains JSX anywhere. */
+function containsJSX(node: any): boolean {
+  if (!node) return false
+  if (node.type === "JSXElement" || node.type === "JSXFragment") return true
+  if (node.type === "ParenthesizedExpression") return containsJSX(node.expression)
+  return false
+}
+
+/** Check if a JSX element has JSX children. */
+export function hasJSXChild(node: any): boolean {
+  if (node.type !== "JSXElement") return false
+  return (node.children ?? []).some((c: any) => c.type === "JSXElement" || c.type === "JSXFragment")
+}
+
+/** Check if a node is a logical AND with JSX. */
+export function isLogicalAndWithJSX(node: any): boolean {
+  if (node.type !== "LogicalExpression" || node.operator !== "&&") return false
+  return containsJSX(node.right)
+}
+
+/** Check if a node is a .peek() call. */
+export function isPeekCall(node: any): boolean {
+  return (
+    node.type === "CallExpression" &&
+    node.callee?.type === "MemberExpression" &&
+    node.callee.property?.type === "Identifier" &&
+    node.callee.property.name === "peek"
+  )
+}
+
+/** Check if a node is a .set() call. */
+export function isSetCall(node: any): boolean {
+  return (
+    node.type === "CallExpression" &&
+    node.callee?.type === "MemberExpression" &&
+    node.callee.property?.type === "Identifier" &&
+    node.callee.property.name === "set"
+  )
+}
+
+/** Check if a node references a browser global. */
+export function isBrowserGlobal(node: any): boolean {
+  return node.type === "Identifier" && BROWSER_GLOBALS.has(node.name)
+}
+
+/** Get the span (byte offsets) of a node. */
+export function getSpan(node: any): Span {
+  return { start: node.start as number, end: node.end as number }
+}
+
+/** Check if a node is inside a `if (__DEV__)` guard. */
+export function isInsideDevGuard(ancestors: any[]): boolean {
+  return ancestors.some(
+    (a) => a.type === "IfStatement" && a.test?.type === "Identifier" && a.test.name === "__DEV__",
+  )
+}
+
+/** Check if a node is inside an onMount callback. */
+export function isInsideOnMount(ancestors: any[]): boolean {
+  return ancestors.some(
+    (a) =>
+      a.type === "CallExpression" && a.callee?.type === "Identifier" && a.callee.name === "onMount",
+  )
+}
+
+/** Check if a node is inside a typeof guard (e.g., `typeof window !== "undefined"`). */
+export function isInsideTypeofGuard(ancestors: any[]): boolean {
+  return ancestors.some(
+    (a) =>
+      a.type === "IfStatement" &&
+      a.test?.type === "BinaryExpression" &&
+      a.test.left?.type === "UnaryExpression" &&
+      a.test.left.operator === "typeof",
+  )
+}

package/src/utils/imports.ts

@@ -0,0 +1,122 @@
+import type { ImportInfo } from "../types"
+
+export type { ImportInfo }
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+export const PYREON_PREFIX = "@pyreon/"
+
+export const REACTIVITY_APIS = new Set([
+  "signal",
+  "computed",
+  "effect",
+  "batch",
+  "onCleanup",
+  "createSelector",
+  "createStore",
+  "untrack",
+])
+
+export const LIFECYCLE_APIS = new Set(["onMount", "onUnmount"])
+
+export const CONTEXT_APIS = new Set(["createContext", "provide", "pushContext", "popContext"])
+
+export const JSX_COMPONENTS = new Set([
+  "For",
+  "Show",
+  "Switch",
+  "Match",
+  "Dynamic",
+  "ErrorBoundary",
+  "Suspense",
+  "Portal",
+])
+
+export const HEAVY_PACKAGES = new Set([
+  "@pyreon/charts",
+  "@pyreon/code",
+  "@pyreon/document",
+  "@pyreon/flow",
+])
+
+export const BROWSER_GLOBALS = new Set([
+  "window",
+  "document",
+  "navigator",
+  "location",
+  "history",
+  "localStorage",
+  "sessionStorage",
+  "indexedDB",
+  "fetch",
+  "XMLHttpRequest",
+  "WebSocket",
+  "requestAnimationFrame",
+  "cancelAnimationFrame",
+  "IntersectionObserver",
+  "MutationObserver",
+  "ResizeObserver",
+  "matchMedia",
+  "getComputedStyle",
+  "addEventListener",
+  "removeEventListener",
+])
+
+// ── Functions ───────────────────────────────────────────────────────────────
+
+export function isPyreonImport(source: string): boolean {
+  return source.startsWith(PYREON_PREFIX)
+}
+
+export function isPyreonPackage(source: string): boolean {
+  return source.startsWith(PYREON_PREFIX)
+}
+
+export function extractImportInfo(node: any): ImportInfo | null {
+  if (node.type !== "ImportDeclaration") return null
+
+  const source = node.source?.value as string
+  if (!source) return null
+
+  const specifiers: ImportInfo["specifiers"] = []
+  let isDefault = false
+  let isNamespace = false
+
+  for (const spec of node.specifiers ?? []) {
+    if (spec.type === "ImportDefaultSpecifier") {
+      isDefault = true
+      specifiers.push({ imported: "default", local: spec.local?.name ?? "" })
+    } else if (spec.type === "ImportNamespaceSpecifier") {
+      isNamespace = true
+      specifiers.push({ imported: "*", local: spec.local?.name ?? "" })
+    } else if (spec.type === "ImportSpecifier") {
+      const imported =
+        spec.imported?.type === "Identifier" ? spec.imported.name : (spec.imported?.value ?? "")
+      specifiers.push({ imported, local: spec.local?.name ?? "" })
+    }
+  }
+
+  return { source, specifiers, isDefault, isNamespace }
+}
+
+export function importsName(imports: ImportInfo[], name: string, fromPackage?: string): boolean {
+  return imports.some(
+    (imp) =>
+      (!fromPackage || imp.source === fromPackage) &&
+      imp.specifiers.some((s) => s.imported === name),
+  )
+}
+
+export function getLocalName(
+  imports: ImportInfo[],
+  name: string,
+  fromPackage?: string,
+): string | null {
+  for (const imp of imports) {
+    if (fromPackage && imp.source !== fromPackage) continue
+    for (const s of imp.specifiers) {
+      if (s.imported === name) return s.local
+    }
+  }
+  return null
+}

package/src/utils/index.ts

@@ -0,0 +1,39 @@
+export {
+  getJSXAttribute,
+  getJSXTagName,
+  getSpan,
+  hasJSXAttribute,
+  hasJSXChild,
+  isArrayMapCall,
+  isBrowserGlobal,
+  isCallTo,
+  isCallToAny,
+  isDestructuring,
+  isFunction,
+  isInsideDevGuard,
+  isInsideFunction,
+  isInsideJSX,
+  isInsideOnMount,
+  isInsideTypeofGuard,
+  isJSXElement,
+  isLogicalAndWithJSX,
+  isMemberCallTo,
+  isPeekCall,
+  isSetCall,
+  isTernaryWithJSX,
+} from "./ast"
+export {
+  BROWSER_GLOBALS,
+  CONTEXT_APIS,
+  extractImportInfo,
+  getLocalName,
+  HEAVY_PACKAGES,
+  importsName,
+  isPyreonImport,
+  isPyreonPackage,
+  JSX_COMPONENTS,
+  LIFECYCLE_APIS,
+  PYREON_PREFIX,
+  REACTIVITY_APIS,
+} from "./imports"
+export { LineIndex } from "./source"

package/src/utils/source.ts

@@ -0,0 +1,36 @@
+import type { SourceLocation } from "../types"
+
+/**
+ * Fast offset→line/column conversion using binary search over precomputed line starts.
+ */
+export class LineIndex {
+  private lineStarts: number[]
+
+  constructor(sourceText: string) {
+    this.lineStarts = [0]
+    for (let i = 0; i < sourceText.length; i++) {
+      if (sourceText[i] === "\n") {
+        this.lineStarts.push(i + 1)
+      }
+    }
+  }
+
+  /** Convert a byte offset to a 1-based line and 0-based column. */
+  locate(offset: number): SourceLocation {
+    let lo = 0
+    let hi = this.lineStarts.length - 1
+
+    while (lo <= hi) {
+      const mid = (lo + hi) >>> 1
+      if ((this.lineStarts[mid] as number) <= offset) {
+        lo = mid + 1
+      } else {
+        hi = mid - 1
+      }
+    }
+
+    const line = lo // 1-based (lo points one past the found index)
+    const column = offset - (this.lineStarts[line - 1] as number)
+    return { line, column }
+  }
+}

package/src/watcher.ts

@@ -0,0 +1,118 @@
+import { readFileSync, watch } from "node:fs"
+import { resolve } from "node:path"
+import { AstCache } from "./cache"
+import { createIgnoreFilter } from "./config/ignore"
+import { getPreset } from "./config/presets"
+import { formatCompact, formatJSON, formatText } from "./reporter"
+import { allRules } from "./rules/index"
+import { lintFile } from "./runner"
+import type { LintConfig, LintOptions, LintResult, Severity } from "./types"
+
+const JS_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mts", ".mjs"])
+
+function hasJsExtension(filePath: string): boolean {
+  const ext = filePath.slice(filePath.lastIndexOf("."))
+  return JS_EXTENSIONS.has(ext)
+}
+
+function formatOutput(result: LintResult, format: string): string {
+  if (format === "json") return formatJSON(result)
+  if (format === "compact") return formatCompact(result)
+  return formatText(result)
+}
+
+/**
+ * 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" })
+ * ```
+ */
+export function watchAndLint(options: LintOptions & { format: string }): void {
+  const cache = new AstCache()
+  const preset = options.preset ?? "recommended"
+  const config = getPreset(preset)
+
+  applyOverrides(config, options.ruleOverrides)
+
+  const cwd = resolve(".")
+  const isIgnored = createIgnoreFilter(cwd, options.ignore)
+
+  // Debounce map: filePath -> timeout
+  const pending = new Map<string, ReturnType<typeof setTimeout>>()
+
+  // eslint-disable-next-line no-console
+  console.log(`\x1b[2m[pyreon-lint] Watching for changes...\x1b[0m\n`)
+
+  for (const p of options.paths) {
+    const dir = resolve(p)
+    try {
+      watch(dir, { recursive: true }, (_event, filename) => {
+        if (!filename) return
+        const filePath = resolve(dir, filename)
+
+        if (!hasJsExtension(filePath) || isIgnored(filePath)) return
+
+        // Debounce: clear existing timeout for this file
+        const existing = pending.get(filePath)
+        if (existing) clearTimeout(existing)
+
+        pending.set(
+          filePath,
+          setTimeout(() => {
+            pending.delete(filePath)
+            relintFile(filePath, config, cache, options.format)
+          }, 100),
+        )
+      })
+    } catch {
+      console.error(`[pyreon-lint] Could not watch: ${dir}`)
+    }
+  }
+}
+
+function applyOverrides(
+  config: LintConfig,
+  overrides?: Record<string, Severity> | undefined,
+): void {
+  if (!overrides) return
+  for (const [id, severity] of Object.entries(overrides)) {
+    config.rules[id] = severity
+  }
+}
+
+function relintFile(filePath: string, config: LintConfig, cache: AstCache, format: string): void {
+  let source: string
+  try {
+    source = readFileSync(filePath, "utf-8")
+  } catch {
+    return
+  }
+
+  const fileResult = lintFile(filePath, source, allRules, config, cache)
+
+  if (fileResult.diagnostics.length === 0) return
+
+  const result: LintResult = {
+    files: [fileResult],
+    totalErrors: 0,
+    totalWarnings: 0,
+    totalInfos: 0,
+  }
+
+  for (const d of fileResult.diagnostics) {
+    if (d.severity === "error") result.totalErrors++
+    else if (d.severity === "warn") result.totalWarnings++
+    else if (d.severity === "info") result.totalInfos++
+  }
+
+  // Clear screen and print
+  process.stdout.write("\x1b[2J\x1b[H")
+  console.log(formatOutput(result, format))
+}