oxlint-plugin-arch 0.2.1

package/src/rules/route-surface.ts

@@ -0,0 +1,62 @@
+import { defineRule } from '@oxlint/plugins'
+import {
+  declarationsTopLevelUnexportedFunctions,
+  exportsCollect,
+  optionsFirst,
+  routesInspectFunction,
+} from '../utils/index.ts'
+
+interface RouteSurfaceOptions {
+  exportName: string
+  bannedHooks: string[]
+  banIntrinsicJsx: boolean
+}
+
+/**
+ * Keeps route files on a small configurable surface: one export plus adapters without banned hooks or intrinsic JSX.
+ *
+ * Example: A route rendering `<UserPage />` passes; an adapter rendering `<div>` or calling `useState` fails.
+ */
+export const routeSurface = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        exportName: { type: 'string' },
+        bannedHooks: { type: 'array', items: { type: 'string' } },
+        banIntrinsicJsx: { type: 'boolean' },
+      },
+    }],
+    defaultOptions: [{ exportName: 'Route', bannedHooks: ['useState', 'useEffect', 'useMutation'], banIntrinsicJsx: true }],
+    messages: {
+      extraExport: "Route files may only export '{{expected}}'; found '{{actual}}'.",
+      hostJsx: 'Route adapter {{name}} must not render intrinsic JSX.',
+      bannedHook: 'Route adapter {{name}} must not call {{hook}}.',
+    },
+  },
+  createOnce(context) {
+    return {
+      Program(program) {
+        const { exportName, bannedHooks, banIntrinsicJsx } = optionsFirst<RouteSurfaceOptions>(context)
+
+        for (const binding of exportsCollect(program)) {
+          if (binding.exportedName !== exportName) {
+            context.report({
+              node: binding.node,
+              messageId: 'extraExport',
+              data: { expected: exportName, actual: binding.exportedName },
+            })
+          }
+        }
+
+        const banned = new Set(bannedHooks)
+
+        for (const item of declarationsTopLevelUnexportedFunctions(program)) {
+          routesInspectFunction(context, item, banned, banIntrinsicJsx)
+        }
+      },
+    }
+  },
+})

package/src/utils/helpers/ast.ts

@@ -0,0 +1,101 @@
+import type { ESTree } from '@oxlint/plugins'
+
+export type AstRuntimeFunction = ESTree.Function | ESTree.ArrowFunctionExpression
+
+export function astIsNode(value: unknown): value is ESTree.Node {
+  return value !== null && typeof value === 'object' && typeof Reflect.get(value, 'type') === 'string'
+}
+
+export function astVisit(node: unknown, ancestors: ESTree.Node[], callback: (node: ESTree.Node, ancestors: ESTree.Node[]) => void): void {
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      astVisit(child, ancestors, callback)
+    }
+    return
+  }
+
+  if (!astIsNode(node)) {
+    return
+  }
+
+  callback(node, ancestors)
+
+  for (const [key, value] of Object.entries(node)) {
+    if (!['parent', 'type', 'start', 'end', 'range', 'loc'].includes(key)) {
+      astVisit(value, [...ancestors, node], callback)
+    }
+  }
+}
+
+export function astContainsJsx(node: unknown): boolean {
+  let found = false
+  astVisit(node, [], (candidate) => {
+    if (candidate.type === 'JSXElement' || candidate.type === 'JSXFragment') {
+      found = true
+    }
+  })
+
+  return found
+}
+
+export function astNearestFunction(ancestors: readonly ESTree.Node[]): AstRuntimeFunction | undefined {
+  return [...ancestors].reverse().find((node): node is AstRuntimeFunction => node.type === 'FunctionDeclaration'
+    || node.type === 'FunctionExpression'
+    || node.type === 'ArrowFunctionExpression')
+}
+
+export function astDirectReturnExpressions(node: AstRuntimeFunction): ESTree.Expression[] {
+  if (node.type === 'ArrowFunctionExpression' && node.body.type !== 'BlockStatement') {
+    return [node.body]
+  }
+
+  const expressions: ESTree.Expression[] = []
+  astVisit(node.body, [node], (candidate, ancestors) => {
+    if (candidate.type === 'ReturnStatement' && candidate.argument && astNearestFunction(ancestors) === node) {
+      expressions.push(candidate.argument)
+    }
+  })
+
+  return expressions
+}
+
+export function astStaticMemberName(node: ESTree.MemberExpression): string | undefined {
+  return !node.computed && node.property.type === 'Identifier' ? node.property.name : undefined
+}
+
+export function astCallName(node: ESTree.CallExpression): string | undefined {
+  if (node.callee.type === 'Identifier') {
+    return node.callee.name
+  }
+
+  return node.callee.type === 'MemberExpression' ? astStaticMemberName(node.callee) : undefined
+}
+
+export function astImportedCallAliases(program: ESTree.Program): Map<string, string> {
+  const aliases = new Map<string, string>()
+
+  for (const statement of program.body) {
+    if (statement.type !== 'ImportDeclaration') {
+      continue
+    }
+
+    for (const specifier of statement.specifiers) {
+      if (specifier.type !== 'ImportSpecifier') {
+        continue
+      }
+
+      const imported = specifier.imported.type === 'Identifier' ? specifier.imported.name : specifier.imported.value
+      if (imported !== specifier.local.name) {
+        aliases.set(specifier.local.name, imported)
+      }
+    }
+  }
+
+  return aliases
+}
+
+export function astResolvedCallName(node: ESTree.CallExpression, aliases: ReadonlyMap<string, string>): string | undefined {
+  const name = astCallName(node)
+  return name ? aliases.get(name) ?? name : undefined
+}
+

package/src/utils/helpers/declarations.ts

@@ -0,0 +1,203 @@
+import { astVisit } from './ast.ts'
+import type { AstRuntimeFunction } from './ast.ts'
+import type { ReactComponentsCandidate } from './react-components.ts'
+import type { ESTree } from '@oxlint/plugins'
+
+export type DeclarationsRuntime = ESTree.VariableDeclaration | ESTree.Function | ESTree.Class | ESTree.TSEnumDeclaration
+
+export function declarationsTopLevelUnexportedFunctions(program: ESTree.Program): { name: string, node: ESTree.Function | ESTree.ArrowFunctionExpression }[] {
+  return program.body.flatMap((statement) => {
+    if (statement.type === 'FunctionDeclaration') {
+      return [{ name: statement.id?.name ?? '<anonymous>', node: statement }]
+    }
+
+    if (statement.type !== 'VariableDeclaration') {
+      return []
+    }
+
+    return statement.declarations.flatMap((item) => item.init?.type === 'FunctionExpression' || item.init?.type === 'ArrowFunctionExpression'
+      ? [{ name: item.id.type === 'Identifier' ? item.id.name : '<anonymous>', node: item.init }]
+      : [])
+  })
+}
+
+export function declarationsFileLevelFunctionCandidates(program: ESTree.Program): ReactComponentsCandidate[] {
+  const result: ReactComponentsCandidate[] = []
+
+  for (const statement of program.body) {
+    const declaration = statement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration' ? statement.declaration : statement
+
+    if (declaration?.type === 'FunctionDeclaration') {
+      result.push({ name: declaration.id?.name ?? '<anonymous>', node: declaration })
+      continue
+    }
+
+    if (declaration?.type !== 'VariableDeclaration' || declaration.kind !== 'const') {
+      continue
+    }
+
+    for (const item of declaration.declarations) {
+      if (item.init?.type === 'FunctionExpression' || item.init?.type === 'ArrowFunctionExpression') {
+        result.push({
+          name: item.id.type === 'Identifier' ? item.id.name : '<anonymous>',
+          node: declaration,
+          initializer: item.init,
+        })
+      }
+    }
+  }
+
+  return result
+}
+
+export function declarationsIsObjectParam(node: ESTree.ParamPattern): boolean {
+  if (node.type === 'ObjectPattern') {
+    return true
+  }
+
+  if (node.type === 'TSParameterProperty') {
+    return declarationsIsObjectParam(node.parameter)
+  }
+
+  const annotation = node.typeAnnotation?.typeAnnotation
+  return !annotation || annotation.type === 'TSTypeReference' || annotation.type === 'TSTypeLiteral' || annotation.type === 'TSIntersectionType'
+}
+
+export function declarationsFunctionName(node: ESTree.Function | ESTree.VariableDeclarator): string {
+  if (node.type === 'VariableDeclarator') {
+    return node.id.type === 'Identifier' ? node.id.name : '<anonymous>'
+  }
+
+  return node.id?.name ?? '<anonymous>'
+}
+
+export function declarationsIsRuntime(node: ESTree.Node): node is DeclarationsRuntime {
+  return node.type === 'VariableDeclaration' || node.type === 'FunctionDeclaration' || node.type === 'ClassDeclaration' || node.type === 'TSEnumDeclaration'
+}
+
+export function declarationsRuntimeName(node: DeclarationsRuntime): string {
+  if (node.type === 'VariableDeclaration') {
+    return node.declarations.map((item) => item.id.type === 'Identifier' ? item.id.name : '<anonymous>').join(', ')
+  }
+
+  return node.id?.name ?? '<anonymous>'
+}
+
+export function declarationsRuntimeKind(node: DeclarationsRuntime): 'class' | 'enum' | 'function' | 'variable' {
+  if (node.type === 'ClassDeclaration') {
+    return 'class'
+  }
+
+  if (node.type === 'TSEnumDeclaration') {
+    return 'enum'
+  }
+
+  if (node.type === 'FunctionDeclaration') {
+    return 'function'
+  }
+
+  return 'variable'
+}
+
+function declarationsUnwrapExpression(node: ESTree.Expression): ESTree.Expression {
+  if (node.type === 'ParenthesizedExpression' || node.type === 'TSAsExpression' || node.type === 'TSSatisfiesExpression'
+    || node.type === 'TSTypeAssertion' || node.type === 'TSNonNullExpression') {
+    return declarationsUnwrapExpression(node.expression)
+  }
+
+  if (node.type === 'ChainExpression') {
+    return declarationsUnwrapExpression(node.expression)
+  }
+
+  return node.type === 'AwaitExpression' && node.argument ? declarationsUnwrapExpression(node.argument) : node
+}
+
+export function declarationsIsTrivialExpression(node: ESTree.Expression): boolean {
+  const value = declarationsUnwrapExpression(node)
+
+  if (value.type === 'Identifier' || value.type === 'ThisExpression' || value.type === 'MetaProperty' || value.type.endsWith('Literal')) {
+    return true
+  }
+
+  if (value.type === 'TemplateLiteral') {
+    return value.expressions.length === 0
+  }
+
+  if (value.type === 'MemberExpression' || value.type === 'CallExpression' || value.type === 'NewExpression'
+    || value.type === 'TaggedTemplateExpression') {
+    return true
+  }
+
+  return value.type === 'LogicalExpression'
+    && declarationsIsTrivialExpression(value.left)
+    && declarationsIsTrivialExpression(value.right)
+}
+
+export function declarationsIsTrivialFunction(node: AstRuntimeFunction): boolean {
+  if (node.type === 'ArrowFunctionExpression' && node.body.type !== 'BlockStatement') {
+    return declarationsIsTrivialExpression(node.body)
+  }
+
+  if (!node.body || node.body.type !== 'BlockStatement') {
+    return false
+  }
+
+  const statements = node.body.body.filter((statement) => statement.type !== 'EmptyStatement'
+    && !(statement.type === 'ExpressionStatement' && statement.directive))
+
+  if (statements.length === 0) {
+    return true
+  }
+
+  if (statements.length > 1) {
+    return false
+  }
+
+  const statement = statements[0]
+  if (statement.type === 'ReturnStatement') {
+    return !statement.argument || declarationsIsTrivialExpression(statement.argument)
+  }
+
+  return statement.type === 'ExpressionStatement' && declarationsIsTrivialExpression(statement.expression)
+}
+
+export interface DeclarationsNamed {
+  name: string
+  node: ESTree.Node
+}
+
+export function declarationsCollectNamed(root: ESTree.Node): DeclarationsNamed[] {
+  const result: DeclarationsNamed[] = []
+
+  astVisit(root, [], (node, ancestors) => {
+    if ((node.type === 'FunctionDeclaration' || node.type === 'ClassDeclaration' || node.type === 'TSTypeAliasDeclaration'
+      || node.type === 'TSInterfaceDeclaration' || node.type === 'TSEnumDeclaration') && node.id?.name) {
+      result.push({ name: node.id.name, node })
+      return
+    }
+
+    if (node.type === 'VariableDeclarator' && node.id.type === 'Identifier'
+      && !ancestors.some((ancestor) => ancestor.type === 'ForStatement' || ancestor.type === 'ForInStatement'
+        || ancestor.type === 'ForOfStatement')) {
+      result.push({ name: node.id.name, node })
+    }
+  })
+
+  return result
+}
+
+export function declarationsCollectFunctions(root: ESTree.Node): { name: string, node: AstRuntimeFunction }[] {
+  return declarationsCollectNamed(root).flatMap((item) => {
+    if (item.node.type === 'FunctionDeclaration') {
+      return [{ name: item.name, node: item.node }]
+    }
+
+    if (item.node.type === 'VariableDeclarator'
+      && (item.node.init?.type === 'FunctionExpression' || item.node.init?.type === 'ArrowFunctionExpression')) {
+      return [{ name: item.name, node: item.node.init }]
+    }
+
+    return []
+  })
+}
+

package/src/utils/helpers/exports.ts

@@ -0,0 +1,158 @@
+import type { AstRuntimeFunction } from './ast.ts'
+import type { ESTree } from '@oxlint/plugins'
+
+export interface ExportsBinding {
+  exportedName: string
+  localName?: string
+  node: ESTree.Node
+  declaration?: ESTree.Declaration
+  initializer?: ESTree.Expression | null
+  typeOnly: boolean
+  default: boolean
+  reExport: boolean
+}
+
+export interface ExportsFunction {
+  name: string
+  node: AstRuntimeFunction
+}
+
+function moduleExportName(node: ESTree.ModuleExportName): string {
+  return node.type === 'Identifier' ? node.name : node.value
+}
+
+function declarationBindings(declaration: ESTree.Declaration | null): ExportsBinding[] {
+  if (!declaration || declaration.type === 'TSModuleDeclaration') {
+    return []
+  }
+
+  if (declaration.type === 'VariableDeclaration') {
+    return declaration.declarations.map((item) => ({
+      exportedName: item.id.type === 'Identifier' ? item.id.name : '<anonymous>',
+      localName: item.id.type === 'Identifier' ? item.id.name : undefined,
+      node: declaration,
+      declaration,
+      initializer: item.init,
+      typeOnly: false,
+      default: false,
+      reExport: false,
+    }))
+  }
+
+  const name = declaration.id?.name ?? '<anonymous>'
+  return [{
+    exportedName: name,
+    localName: declaration.id?.name,
+    node: declaration,
+    declaration,
+    typeOnly: declaration.type === 'TSInterfaceDeclaration'
+      || declaration.type === 'TSTypeAliasDeclaration'
+      || declaration.type === 'TSDeclareFunction',
+    default: false,
+    reExport: false,
+  }]
+}
+
+function localBindings(program: ESTree.Program): Map<string, ExportsBinding> {
+  const result = new Map<string, ExportsBinding>()
+
+  for (const statement of program.body) {
+    if (statement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration') {
+      continue
+    }
+
+    if (statement.type.endsWith('Declaration')) {
+      for (const binding of declarationBindings(statement as ESTree.Declaration)) {
+        if (binding.localName) {
+          result.set(binding.localName, binding)
+        }
+      }
+    }
+  }
+
+  return result
+}
+
+export function exportsCollect(program: ESTree.Program): ExportsBinding[] {
+  const locals = localBindings(program)
+
+  return program.body.flatMap((statement) => {
+    if (statement.type === 'ExportAllDeclaration') {
+      return [{
+        exportedName: '*',
+        node: statement,
+        typeOnly: statement.exportKind === 'type',
+        default: false,
+        reExport: true,
+      }]
+    }
+
+    if (statement.type === 'ExportDefaultDeclaration') {
+      if (statement.declaration.type === 'Identifier') {
+        const local = locals.get(statement.declaration.name)
+        return [{
+          ...(local ?? {
+            exportedName: 'default',
+            node: statement,
+            typeOnly: false,
+            default: true,
+            reExport: false,
+          }),
+          exportedName: 'default',
+          localName: local?.localName ?? statement.declaration.name,
+          default: true,
+        }]
+      }
+
+      if (statement.declaration.type.endsWith('Declaration')) {
+        const bindings = declarationBindings(statement.declaration as ESTree.Declaration)
+        return bindings.length > 0
+          ? bindings.map((binding) => ({ ...binding, exportedName: 'default', default: true }))
+          : [{ exportedName: 'default', node: statement, typeOnly: false, default: true, reExport: false }]
+      }
+
+      return [{ exportedName: 'default', node: statement, typeOnly: false, default: true, reExport: false }]
+    }
+
+    if (statement.type !== 'ExportNamedDeclaration') {
+      return []
+    }
+
+    return [
+      ...declarationBindings(statement.declaration),
+      ...statement.specifiers.map((specifier) => {
+        const localName = moduleExportName(specifier.local)
+        const local = locals.get(localName)
+        return {
+          ...(local ?? {
+            exportedName: moduleExportName(specifier.exported),
+            node: specifier,
+            typeOnly: false,
+            default: false,
+            reExport: Boolean(statement.source),
+          }),
+          exportedName: moduleExportName(specifier.exported),
+          localName,
+          node: local?.node ?? specifier,
+          typeOnly: specifier.exportKind === 'type' || statement.exportKind === 'type' || Boolean(local?.typeOnly),
+          default: moduleExportName(specifier.exported) === 'default',
+          reExport: Boolean(statement.source),
+        }
+      }),
+    ]
+  })
+}
+
+export function exportsCollectFunctions(program: ESTree.Program): ExportsFunction[] {
+  return exportsCollect(program).flatMap((binding) => {
+    const name = binding.localName ?? binding.exportedName
+
+    if (binding.declaration?.type === 'FunctionDeclaration') {
+      return [{ name, node: binding.declaration }]
+    }
+
+    return binding.initializer?.type === 'FunctionExpression' || binding.initializer?.type === 'ArrowFunctionExpression'
+      ? [{ name, node: binding.initializer }]
+      : []
+  })
+}

package/src/utils/helpers/factories.ts

@@ -0,0 +1,67 @@
+import { astNearestFunction, astVisit } from './ast.ts'
+import { namingPascalCase } from './naming.ts'
+import type { ESTree } from '@oxlint/plugins'
+
+export interface FactoriesFunction {
+  name: string
+  node: ESTree.Function | ESTree.ArrowFunctionExpression
+}
+
+export function factoriesExpandTemplate(template: string, groups: Record<string, string>): string {
+  return template.replaceAll(/\{([^}]+)\}/g, (placeholder, key: string) => {
+    const group = groups[key.toLowerCase()]
+
+    if (!group) {
+      return placeholder
+    }
+
+    return /^[A-Z]/.test(key) ? namingPascalCase(group) : group
+  })
+}
+
+export function factoriesCollectTopLevel(program: ESTree.Program, pattern: RegExp): FactoriesFunction[] {
+  return program.body.flatMap((statement) => {
+    const declaration = statement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration' ? statement.declaration : statement
+
+    if (declaration?.type === 'FunctionDeclaration') {
+      const name = declaration.id?.name ?? '<anonymous>'
+      return pattern.test(name) ? [{ name, node: declaration }] : []
+    }
+
+    if (declaration?.type !== 'VariableDeclaration') {
+      return []
+    }
+
+    return declaration.declarations.flatMap((item) => item.id.type === 'Identifier' && pattern.test(item.id.name)
+      && (item.init?.type === 'FunctionExpression' || item.init?.type === 'ArrowFunctionExpression')
+      ? [{ name: item.id.name, node: item.init }]
+      : [])
+  })
+}
+
+export function factoriesDirectlyReturnedObjects(factory: FactoriesFunction): ESTree.ObjectExpression[] {
+  if (factory.node.type === 'ArrowFunctionExpression' && factory.node.body.type === 'ObjectExpression') {
+    return [factory.node.body]
+  }
+
+  const result: ESTree.ObjectExpression[] = []
+  astVisit(factory.node.body, [factory.node], (node, ancestors) => {
+    if (node.type === 'ReturnStatement' && node.argument?.type === 'ObjectExpression' && astNearestFunction(ancestors) === factory.node) {
+      result.push(node.argument)
+    }
+  })
+
+  return result
+}
+
+export function factoriesObjectPropertyName(property: ESTree.ObjectPropertyKind): string | undefined {
+  if (property.type === 'SpreadElement' || property.computed) {
+    return
+  }
+
+  if (property.key.type === 'Identifier') {
+    return property.key.name
+  }
+
+  return property.key.type === 'Literal' && typeof property.key.value === 'string' ? property.key.value : undefined
+}

package/src/utils/helpers/index.ts

@@ -0,0 +1,11 @@
+export * from './ast.ts'
+export * from './declarations.ts'
+export * from './exports.ts'
+export * from './factories.ts'
+export * from './naming.ts'
+export * from './options.ts'
+export * from './orpc.ts'
+export * from './react-components.ts'
+export * from './routes.ts'
+export * from './sanitizers.ts'
+export * from './schemas.ts'

package/src/utils/helpers/naming.ts

@@ -0,0 +1,89 @@
+export function namingPosixPath(filePath: string): string {
+  return filePath.replaceAll('\\', '/')
+}
+
+export function namingFileBasename(filePath: string): string {
+  const normalized = namingPosixPath(filePath)
+  const slash = normalized.lastIndexOf('/')
+  return slash === -1 ? normalized : normalized.slice(slash + 1)
+}
+
+export function namingDirSegments(filePath: string): string[] {
+  const parts = namingPosixPath(filePath).split('/').filter(Boolean)
+  return parts.slice(0, -1)
+}
+
+export function namingSegmentsAfter(filePath: string, after: string): string[] | undefined {
+  const dirs = namingDirSegments(filePath)
+  const marker = after.split('/').filter(Boolean)
+
+  if (marker.length === 0) {
+    return undefined
+  }
+
+  for (let index = dirs.length - marker.length; index >= 0; index -= 1) {
+    if (marker.every((part, offset) => dirs[index + offset] === part)) {
+      return dirs.slice(index + marker.length)
+    }
+  }
+}
+
+export function namingFolderPrefixes(
+  folders: string[],
+  separator: string,
+  singularize: 'none' | 'trailing-s',
+): string[] {
+  const joined = folders.join(separator)
+  const last = folders.at(-1) ?? ''
+  const prefixes = [joined]
+
+  if (singularize === 'trailing-s' && last.endsWith('s') && last.length > 1) {
+    prefixes.push([...folders.slice(0, -1), last.slice(0, -1)].join(separator))
+  }
+
+  return prefixes.filter(Boolean)
+}
+
+export function namingPascalCase(value: string): string {
+  return value
+    .split(/[-_\s.]+/)
+    .filter(Boolean)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join('')
+}
+
+export function namingCamelCase(value: string): string {
+  const next = namingPascalCase(value)
+  return `${next.charAt(0).toLowerCase()}${next.slice(1)}`
+}
+
+export function namingMatchTemplate(
+  basename: string,
+  template: string,
+  placeholderPattern = '[a-z0-9-]+',
+): Record<string, string> | null {
+  let pattern = ''
+  let index = 0
+
+  while (index < template.length) {
+    const char = template[index]
+
+    if (char === '{') {
+      const end = template.indexOf('}', index)
+
+      if (end === -1) {
+        return null
+      }
+
+      const key = template.slice(index + 1, end)
+      pattern += `(?<${key}>${placeholderPattern})`
+      index = end + 1
+      continue
+    }
+
+    pattern += /[.+^${}()|[\]\\]/.test(char) ? `\\${char}` : char
+    index += 1
+  }
+
+  return new RegExp(`^${pattern}$`).exec(basename)?.groups ?? null
+}

package/src/utils/helpers/options.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@oxlint/plugins'
+
+export function optionsFirst<T>(context: Context, fallback?: T): T {
+  return (context.options[0] ?? fallback) as unknown as T
+}