@pyreon/lint 0.11.0

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

@@ -0,0 +1,33 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan, hasJSXAttribute } from "../../utils/ast"
+
+export const overlayA11y: Rule = {
+  meta: {
+    id: "pyreon/overlay-a11y",
+    category: "accessibility",
+    description: "Warn when <Overlay> is missing role, 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 !== "Overlay") return
+
+        const hasRole = hasJSXAttribute(node, "role")
+        const hasLabel = hasJSXAttribute(node, "aria-label")
+        const hasLabelledBy = hasJSXAttribute(node, "aria-labelledby")
+
+        if (!hasRole && !hasLabel && !hasLabelledBy) {
+          context.report({
+            message:
+              "`<Overlay>` missing `role`, `aria-label`, or `aria-labelledby` — provide accessibility attributes for screen readers.",
+            span: getSpan(node),
+          })
+        }
+      },
+    }
+    return callbacks
+  },
+}

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

@@ -0,0 +1,38 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan, hasJSXAttribute } from "../../utils/ast"
+
+export const toastA11y: Rule = {
+  meta: {
+    id: "pyreon/toast-a11y",
+    category: "accessibility",
+    description: "Warn when toast-like components are missing role or aria-live attributes.",
+    severity: "warn",
+    fixable: false,
+  },
+  create(context) {
+    const callbacks: VisitorCallbacks = {
+      JSXOpeningElement(node: any) {
+        const name = node.name
+        if (!name || name.type !== "JSXIdentifier") return
+
+        const tagName: string = name.name
+        // Skip non-PascalCase and the Toaster container itself
+        if (tagName === "Toaster") return
+        const firstChar = tagName[0]
+        if (!firstChar || firstChar !== firstChar.toUpperCase()) return
+        if (!tagName.toLowerCase().includes("toast")) return
+
+        const hasRole = hasJSXAttribute(node, "role")
+        const hasAriaLive = hasJSXAttribute(node, "aria-live")
+
+        if (!hasRole && !hasAriaLive) {
+          context.report({
+            message: `Toast component \`<${tagName}>\` missing \`role\` or \`aria-live\` — add \`role="alert"\` and \`aria-live="polite"\` for screen reader accessibility.`,
+            span: getSpan(node),
+          })
+        }
+      },
+    }
+    return callbacks
+  },
+}

package/src/rules/architecture/dev-guard-warnings.ts

@@ -0,0 +1,57 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan } from "../../utils/ast"
+
+export const devGuardWarnings: Rule = {
+  meta: {
+    id: "pyreon/dev-guard-warnings",
+    category: "architecture",
+    description: "Require console.warn/error calls to be wrapped in `if (__DEV__)` guards.",
+    severity: "error",
+    fixable: false,
+  },
+  create(context) {
+    const filePath = context.getFilePath()
+    // Skip test and example files
+    if (
+      filePath.includes("/tests/") ||
+      filePath.includes("/test/") ||
+      filePath.includes("/examples/") ||
+      filePath.includes(".test.") ||
+      filePath.includes(".spec.")
+    ) {
+      return {}
+    }
+
+    let devGuardDepth = 0
+    const callbacks: VisitorCallbacks = {
+      IfStatement(node: any) {
+        if (node.test?.type === "Identifier" && node.test.name === "__DEV__") {
+          devGuardDepth++
+        }
+      },
+      "IfStatement:exit"(node: any) {
+        if (node.test?.type === "Identifier" && node.test.name === "__DEV__") {
+          devGuardDepth--
+        }
+      },
+      CallExpression(node: any) {
+        if (devGuardDepth > 0) return
+
+        const callee = node.callee
+        if (
+          callee?.type === "MemberExpression" &&
+          callee.object?.type === "Identifier" &&
+          callee.object.name === "console" &&
+          callee.property?.type === "Identifier" &&
+          (callee.property.name === "warn" || callee.property.name === "error")
+        ) {
+          context.report({
+            message: `\`console.${callee.property.name}()\` without \`__DEV__\` guard — dev warnings must be tree-shakeable in production. Wrap in \`if (__DEV__) { ... }\`.`,
+            span: getSpan(node),
+          })
+        }
+      },
+    }
+    return callbacks
+  },
+}

package/src/rules/architecture/no-circular-import.ts

@@ -0,0 +1,59 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan } from "../../utils/ast"
+import { isPyreonImport } from "../../utils/imports"
+
+const LAYER_ORDER: Record<string, number> = {
+  "@pyreon/reactivity": 0,
+  "@pyreon/core": 1,
+  "@pyreon/compiler": 1,
+  "@pyreon/runtime-dom": 2,
+  "@pyreon/runtime-server": 2,
+  "@pyreon/router": 3,
+  "@pyreon/head": 4,
+  "@pyreon/server": 5,
+}
+
+function getLayer(source: string): number | null {
+  return LAYER_ORDER[source] ?? null
+}
+
+function getFileLayer(filePath: string): number | null {
+  for (const [pkg, layer] of Object.entries(LAYER_ORDER)) {
+    const pkgName = pkg.replace("@pyreon/", "")
+    if (filePath.includes(`/packages/core/${pkgName}/`)) return layer
+  }
+  return null
+}
+
+export const noCircularImport: Rule = {
+  meta: {
+    id: "pyreon/no-circular-import",
+    category: "architecture",
+    description: "Enforce package layer order to prevent circular imports between core packages.",
+    severity: "error",
+    fixable: false,
+  },
+  create(context) {
+    const filePath = context.getFilePath()
+    const fileLayer = getFileLayer(filePath)
+    if (fileLayer === null) return {}
+
+    const callbacks: VisitorCallbacks = {
+      ImportDeclaration(node: any) {
+        const source = node.source?.value as string
+        if (!source || !isPyreonImport(source)) return
+
+        const importLayer = getLayer(source)
+        if (importLayer === null) return
+
+        if (importLayer >= fileLayer) {
+          context.report({
+            message: `Importing \`${source}\` (layer ${importLayer}) from layer ${fileLayer} — this violates the package layer order and may cause circular imports.`,
+            span: getSpan(node),
+          })
+        }
+      },
+    }
+    return callbacks
+  },
+}

package/src/rules/architecture/no-cross-layer-import.ts

@@ -0,0 +1,75 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan } from "../../utils/ast"
+import { isPyreonImport } from "../../utils/imports"
+
+type PackageCategory = "core" | "fundamentals" | "tools" | "ui-system"
+
+const CORE_PACKAGES = new Set([
+  "@pyreon/reactivity",
+  "@pyreon/core",
+  "@pyreon/compiler",
+  "@pyreon/runtime-dom",
+  "@pyreon/runtime-server",
+  "@pyreon/router",
+  "@pyreon/head",
+  "@pyreon/server",
+])
+
+const UI_PACKAGES = new Set([
+  "@pyreon/ui-core",
+  "@pyreon/styler",
+  "@pyreon/unistyle",
+  "@pyreon/elements",
+  "@pyreon/attrs",
+  "@pyreon/rocketstyle",
+  "@pyreon/coolgrid",
+  "@pyreon/kinetic",
+  "@pyreon/kinetic-presets",
+  "@pyreon/connector-document",
+  "@pyreon/document-primitives",
+])
+
+function getImportCategory(source: string): PackageCategory | null {
+  if (CORE_PACKAGES.has(source)) return "core"
+  if (UI_PACKAGES.has(source)) return "ui-system"
+  return null
+}
+
+function getFileCategory(filePath: string): PackageCategory | null {
+  if (filePath.includes("/packages/core/")) return "core"
+  if (filePath.includes("/packages/ui-system/")) return "ui-system"
+  if (filePath.includes("/packages/fundamentals/")) return "fundamentals"
+  if (filePath.includes("/packages/tools/")) return "tools"
+  return null
+}
+
+export const noCrossLayerImport: Rule = {
+  meta: {
+    id: "pyreon/no-cross-layer-import",
+    category: "architecture",
+    description: "Prevent core packages from importing ui-system packages.",
+    severity: "error",
+    fixable: false,
+  },
+  create(context) {
+    const filePath = context.getFilePath()
+    const fileCategory = getFileCategory(filePath)
+    if (fileCategory !== "core") return {}
+
+    const callbacks: VisitorCallbacks = {
+      ImportDeclaration(node: any) {
+        const source = node.source?.value as string
+        if (!source || !isPyreonImport(source)) return
+
+        const importCategory = getImportCategory(source)
+        if (importCategory === "ui-system") {
+          context.report({
+            message: `Core package importing ui-system package \`${source}\` — core packages must not depend on ui-system.`,
+            span: getSpan(node),
+          })
+        }
+      },
+    }
+    return callbacks
+  },
+}

package/src/rules/architecture/no-deep-import.ts

@@ -0,0 +1,32 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan } from "../../utils/ast"
+import { isPyreonImport } from "../../utils/imports"
+
+const DEEP_IMPORT_PATTERN = /@pyreon\/[^/]+\/(src|dist|lib)\//
+
+export const noDeepImport: Rule = {
+  meta: {
+    id: "pyreon/no-deep-import",
+    category: "architecture",
+    description:
+      "Disallow importing from @pyreon/*/src/, /dist/, or /lib/ — use public exports instead.",
+    severity: "warn",
+    fixable: false,
+  },
+  create(context) {
+    const callbacks: VisitorCallbacks = {
+      ImportDeclaration(node: any) {
+        const source = node.source?.value as string
+        if (!source || !isPyreonImport(source)) return
+
+        if (DEEP_IMPORT_PATTERN.test(source)) {
+          context.report({
+            message: `Deep import \`${source}\` — import from the package's public exports instead.`,
+            span: getSpan(node),
+          })
+        }
+      },
+    }
+    return callbacks
+  },
+}

package/src/rules/architecture/no-error-without-prefix.ts

@@ -0,0 +1,75 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan } from "../../utils/ast"
+
+export const noErrorWithoutPrefix: Rule = {
+  meta: {
+    id: "pyreon/no-error-without-prefix",
+    category: "architecture",
+    description: "Require error messages to be prefixed with [Pyreon].",
+    severity: "warn",
+    fixable: true,
+  },
+  create(context) {
+    const filePath = context.getFilePath()
+    // Skip test files
+    if (
+      filePath.includes("/tests/") ||
+      filePath.includes("/test/") ||
+      filePath.includes(".test.") ||
+      filePath.includes(".spec.")
+    ) {
+      return {}
+    }
+
+    const callbacks: VisitorCallbacks = {
+      ThrowStatement(node: any) {
+        const arg = node.argument
+        if (!arg || arg.type !== "NewExpression") return
+        const callee = arg.callee
+        if (!callee || callee.type !== "Identifier" || callee.name !== "Error") return
+
+        const args = arg.arguments
+        if (!args || args.length === 0) return
+
+        const firstArg = args[0]
+        if (!firstArg) return
+
+        if (firstArg.type === "Literal" || firstArg.type === "StringLiteral") {
+          const value = firstArg.value as string
+          if (typeof value === "string" && !value.startsWith("[Pyreon]")) {
+            const argSpan = getSpan(firstArg)
+            // Fix: add [Pyreon] prefix
+            const quote = context.getSourceText()[argSpan.start]
+            const fixedValue = `${quote}[Pyreon] ${value}${quote}`
+            context.report({
+              message:
+                "Error message missing `[Pyreon]` prefix — all framework errors should be prefixed for identification.",
+              span: getSpan(node),
+              fix: { span: argSpan, replacement: fixedValue },
+            })
+          }
+        }
+
+        if (firstArg.type === "TemplateLiteral") {
+          const quasis = firstArg.quasis
+          if (quasis && quasis.length > 0) {
+            const first = quasis[0]
+            const raw = first.value?.raw ?? first.value?.cooked ?? ""
+            if (!raw.startsWith("[Pyreon]")) {
+              const argSpan = getSpan(firstArg)
+              const source = context.getSourceText().slice(argSpan.start, argSpan.end)
+              const fixed = source.replace(/^`/, "`[Pyreon] ")
+              context.report({
+                message:
+                  "Error message missing `[Pyreon]` prefix — all framework errors should be prefixed for identification.",
+                span: getSpan(node),
+                fix: { span: argSpan, replacement: fixed },
+              })
+            }
+          }
+        }
+      },
+    }
+    return callbacks
+  },
+}

package/src/rules/form/no-submit-without-validation.ts

@@ -0,0 +1,45 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan, isCallTo } from "../../utils/ast"
+
+export const noSubmitWithoutValidation: Rule = {
+  meta: {
+    id: "pyreon/no-submit-without-validation",
+    category: "form",
+    description: "Warn when useForm() has onSubmit but no validators or schema.",
+    severity: "warn",
+    fixable: false,
+  },
+  create(context) {
+    const callbacks: VisitorCallbacks = {
+      CallExpression(node: any) {
+        if (!isCallTo(node, "useForm")) return
+        const args = node.arguments
+        if (!args || args.length === 0) return
+
+        const options = args[0]
+        if (!options || options.type !== "ObjectExpression") return
+
+        let hasOnSubmit = false
+        let hasValidation = false
+
+        for (const prop of options.properties ?? []) {
+          if (prop.type !== "Property") continue
+          const key = prop.key
+          if (!key) continue
+          const name = key.type === "Identifier" ? key.name : null
+          if (name === "onSubmit") hasOnSubmit = true
+          if (name === "validators" || name === "schema") hasValidation = true
+        }
+
+        if (hasOnSubmit && !hasValidation) {
+          context.report({
+            message:
+              "`useForm()` has `onSubmit` without `validators` or `schema` — consider adding validation for data integrity.",
+            span: getSpan(node),
+          })
+        }
+      },
+    }
+    return callbacks
+  },
+}

package/src/rules/form/no-unregistered-field.ts

@@ -0,0 +1,45 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan, isCallTo } from "../../utils/ast"
+
+export const noUnregisteredField: Rule = {
+  meta: {
+    id: "pyreon/no-unregistered-field",
+    category: "form",
+    description: "Warn when useField() is called without a corresponding register() call.",
+    severity: "warn",
+    fixable: false,
+  },
+  create(context) {
+    const fieldDecls = new Map<string, { span: { start: number; end: number } }>()
+    const registeredNames = new Set<string>()
+
+    const callbacks: VisitorCallbacks = {
+      VariableDeclarator(node: any) {
+        const init = node.init
+        if (!init || !isCallTo(init, "useField")) return
+        const id = node.id
+        if (!id || id.type !== "Identifier") return
+        fieldDecls.set(id.name, { span: getSpan(node) })
+      },
+      CallExpression(node: any) {
+        const callee = node.callee
+        if (!callee || callee.type !== "MemberExpression") return
+        if (callee.property?.type !== "Identifier" || callee.property.name !== "register") return
+        if (callee.object?.type === "Identifier") {
+          registeredNames.add(callee.object.name)
+        }
+      },
+      "Program:exit"() {
+        for (const [name, { span }] of fieldDecls) {
+          if (!registeredNames.has(name)) {
+            context.report({
+              message: `\`useField()\` result \`${name}\` is never registered — call \`${name}.register()\` to connect it to the form.`,
+              span,
+            })
+          }
+        }
+      },
+    }
+    return callbacks
+  },
+}

package/src/rules/form/prefer-field-array.ts

@@ -0,0 +1,41 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan, isCallTo } from "../../utils/ast"
+import { extractImportInfo } from "../../utils/imports"
+
+export const preferFieldArray: Rule = {
+  meta: {
+    id: "pyreon/prefer-field-array",
+    category: "form",
+    description: "Suggest useFieldArray() instead of signal([]) in files that import @pyreon/form.",
+    severity: "info",
+    fixable: false,
+  },
+  create(context) {
+    let importsForm = false
+
+    const callbacks: VisitorCallbacks = {
+      ImportDeclaration(node: any) {
+        const info = extractImportInfo(node)
+        if (info && info.source === "@pyreon/form") {
+          importsForm = true
+        }
+      },
+      CallExpression(node: any) {
+        if (!importsForm) return
+        if (!isCallTo(node, "signal")) return
+
+        const args = node.arguments
+        if (!args || args.length === 0) return
+        const firstArg = args[0]
+        if (firstArg?.type === "ArrayExpression") {
+          context.report({
+            message:
+              "`signal([])` in a form file — consider using `useFieldArray()` for dynamic array fields with stable keys.",
+            span: getSpan(node),
+          })
+        }
+      },
+    }
+    return callbacks
+  },
+}

package/src/rules/hooks/no-raw-addeventlistener.ts

@@ -0,0 +1,28 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan } from "../../utils/ast"
+
+export const noRawAddEventListener: Rule = {
+  meta: {
+    id: "pyreon/no-raw-addeventlistener",
+    category: "hooks",
+    description: "Suggest useEventListener() instead of raw .addEventListener() calls.",
+    severity: "info",
+    fixable: false,
+  },
+  create(context) {
+    const callbacks: VisitorCallbacks = {
+      CallExpression(node: any) {
+        const callee = node.callee
+        if (!callee || callee.type !== "MemberExpression") return
+        if (callee.property?.type !== "Identifier" || callee.property.name !== "addEventListener")
+          return
+        context.report({
+          message:
+            "Raw `.addEventListener()` — consider using `useEventListener()` from `@pyreon/hooks` for auto-cleanup on unmount.",
+          span: getSpan(node),
+        })
+      },
+    }
+    return callbacks
+  },
+}

package/src/rules/hooks/no-raw-localstorage.ts

@@ -0,0 +1,35 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan } from "../../utils/ast"
+
+const STORAGE_OBJECTS = new Set(["localStorage", "sessionStorage"])
+const STORAGE_METHODS = new Set(["getItem", "setItem", "removeItem"])
+
+export const noRawLocalStorage: Rule = {
+  meta: {
+    id: "pyreon/no-raw-localstorage",
+    category: "hooks",
+    description: "Suggest useStorage() instead of raw localStorage/sessionStorage access.",
+    severity: "info",
+    fixable: false,
+  },
+  create(context) {
+    const callbacks: VisitorCallbacks = {
+      CallExpression(node: any) {
+        const callee = node.callee
+        if (!callee || callee.type !== "MemberExpression") return
+        if (
+          callee.object?.type === "Identifier" &&
+          STORAGE_OBJECTS.has(callee.object.name) &&
+          callee.property?.type === "Identifier" &&
+          STORAGE_METHODS.has(callee.property.name)
+        ) {
+          context.report({
+            message: `Raw \`${callee.object.name}.${callee.property.name}()\` — consider using \`useStorage()\` from \`@pyreon/storage\` for reactive, cross-tab synced storage.`,
+            span: getSpan(node),
+          })
+        }
+      },
+    }
+    return callbacks
+  },
+}

package/src/rules/hooks/no-raw-setinterval.ts

@@ -0,0 +1,41 @@
+import type { Rule, VisitorCallbacks } from "../../types"
+import { getSpan, isCallTo } from "../../utils/ast"
+
+const TIMER_FNS = new Set(["setInterval", "setTimeout"])
+
+export const noRawSetInterval: Rule = {
+  meta: {
+    id: "pyreon/no-raw-setinterval",
+    category: "hooks",
+    description: "Suggest wrapping setInterval/setTimeout in onMount for automatic cleanup.",
+    severity: "info",
+    fixable: false,
+  },
+  create(context) {
+    let mountDepth = 0
+    const callbacks: VisitorCallbacks = {
+      CallExpression(node: any) {
+        if (isCallTo(node, "onMount")) {
+          mountDepth++
+        }
+
+        if (mountDepth > 0) return
+
+        const callee = node.callee
+        if (!callee || callee.type !== "Identifier") return
+        if (TIMER_FNS.has(callee.name)) {
+          context.report({
+            message: `\`${callee.name}()\` outside \`onMount\` — wrap in \`onMount(() => { ... return () => clear... })\` for automatic cleanup.`,
+            span: getSpan(node),
+          })
+        }
+      },
+      "CallExpression:exit"(node: any) {
+        if (isCallTo(node, "onMount")) {
+          mountDepth--
+        }
+      },
+    }
+    return callbacks
+  },
+}