oxlint-plugin-arch 0.2.1

package/src/rules/no-single-use-scalar-schema.ts

@@ -0,0 +1,164 @@
+import { defineRule } from '@oxlint/plugins'
+import {
+  astStaticMemberName,
+  exportsCollect,
+  optionsFirst,
+  schemasElements,
+  schemasIsAllowedElement,
+  schemasIsCall,
+} from '../utils/index.ts'
+import type { ESTree } from '@oxlint/plugins'
+
+interface NoSingleUseScalarSchemaOptions {
+  namespaces: string[]
+  methods: string[]
+  structuralMethods: string[]
+  allowZodScalars: boolean
+}
+
+function isScalarSchema(
+  node: ESTree.Expression,
+  namespaces: Set<string>,
+  structuralMethods: Set<string>,
+): node is ESTree.CallExpression {
+  if (node.type !== 'CallExpression' || node.callee.type !== 'MemberExpression') {
+    return false
+  }
+
+  if (schemasIsCall(node, namespaces)) {
+    const method = astStaticMemberName(node.callee)
+    return Boolean(method && !structuralMethods.has(method))
+  }
+
+  const modifier = astStaticMemberName(node.callee)
+  return Boolean(
+    modifier
+      && !structuralMethods.has(modifier)
+      && node.callee.object.type === 'CallExpression'
+      && isScalarSchema(node.callee.object, namespaces, structuralMethods),
+  )
+}
+
+function isDirectObjectField(
+  identifier: ESTree.IdentifierReference,
+  ancestors: ESTree.Node[],
+  namespaces: Set<string>,
+  structuralMethods: Set<string>,
+): boolean {
+  const property = ancestors.at(-1)
+  const object = ancestors.at(-2)
+  const call = ancestors.at(-3)
+
+  if (property?.type !== 'Property' || property.value !== identifier || object?.type !== 'ObjectExpression'
+    || call?.type !== 'CallExpression' || !schemasIsCall(call, namespaces)) {
+    return false
+  }
+
+  const method = call.callee.type === 'MemberExpression' ? astStaticMemberName(call.callee) : undefined
+  return Boolean(method === 'object' && structuralMethods.has(method) && call.arguments.includes(object))
+}
+
+function isAllowedStructuralElement(
+  identifier: ESTree.IdentifierReference,
+  initializer: ESTree.CallExpression,
+  ancestors: ESTree.Node[],
+  options: NoSingleUseScalarSchemaOptions,
+  namespaces: Set<string>,
+  structuralMethods: Set<string>,
+): boolean {
+  if (!options.allowZodScalars || !schemasIsAllowedElement(initializer, true, namespaces, structuralMethods)) {
+    return false
+  }
+
+  const parent = ancestors.at(-1)
+  const call = parent?.type === 'ArrayExpression' ? ancestors.at(-2) : parent
+
+  if (call?.type !== 'CallExpression' || !schemasIsCall(call, namespaces)) {
+    return false
+  }
+
+  const method = call.callee.type === 'MemberExpression' ? astStaticMemberName(call.callee) : undefined
+  return Boolean(method && options.methods.includes(method) && schemasElements(call).includes(identifier))
+}
+
+/**
+ * Reports a local scalar Zod schema binding used exactly once where the scalar can be written inline.
+ *
+ * Example: `const userId = z.number(); z.object({ id: userId })` fails; exported, reused, or inferred bindings pass.
+ */
+export const noSingleUseScalarSchema = defineRule({
+  meta: {
+    type: 'suggestion',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        namespaces: { type: 'array', items: { type: 'string' } },
+        methods: { type: 'array', items: { type: 'string' } },
+        structuralMethods: { type: 'array', items: { type: 'string' } },
+        allowZodScalars: { type: 'boolean' },
+      },
+    }],
+    defaultOptions: [{
+      namespaces: ['z'],
+      methods: ['array', 'union', 'record', 'tuple'],
+      structuralMethods: ['and', 'array', 'discriminatedUnion', 'intersection', 'lazy', 'object', 'or', 'pipe', 'record', 'transform', 'tuple', 'union'],
+      allowZodScalars: true,
+    }],
+    messages: { inline: 'Inline single-use scalar schema {{name}} at its only structural use.' },
+  },
+  create(context) {
+    const candidates: ESTree.VariableDeclarator[] = []
+
+    return {
+      VariableDeclaration(node) {
+        if (node.kind !== 'const') {
+          return
+        }
+
+        for (const declarator of node.declarations) {
+          if (declarator.id.type === 'Identifier' && declarator.init) {
+            candidates.push(declarator)
+          }
+        }
+      },
+      'Program:exit'(program) {
+        const options = optionsFirst<NoSingleUseScalarSchemaOptions>(context)
+        const namespaces = new Set(options.namespaces)
+        const structuralMethods = new Set(options.structuralMethods)
+        const exportedNames = new Set(exportsCollect(program).flatMap((binding) => binding.localName ? [binding.localName] : []))
+
+        for (const declarator of candidates) {
+          const name = declarator.id.type === 'Identifier' ? declarator.id.name : undefined
+          const initializer = declarator.init
+
+          if (!name || !initializer || exportedNames.has(name) || !isScalarSchema(initializer, namespaces, structuralMethods)) {
+            continue
+          }
+
+          const variable = context.sourceCode.getDeclaredVariables(declarator).find((candidate) => candidate.name === name)
+          const references = variable?.references.filter((reference) => reference.isRead()) ?? []
+
+          if (references.length !== 1) {
+            continue
+          }
+
+          const reference = references[0]
+          const identifier = reference.identifier as ESTree.IdentifierReference
+          const ancestors = context.sourceCode.getAncestors(identifier) as unknown as ESTree.Node[]
+          const inlineable = isDirectObjectField(identifier, ancestors, namespaces, structuralMethods)
+            || isAllowedStructuralElement(identifier, initializer, ancestors, options, namespaces, structuralMethods)
+
+          if (inlineable) {
+            // Deliberately report-only: moving construction can cross comments or observable statements.
+            context.report({
+              node: declarator.id,
+              messageId: 'inline',
+              data: { name },
+            })
+          }
+        }
+      },
+    }
+  },
+})

package/src/rules/no-top-level-functions.ts

@@ -0,0 +1,77 @@
+import { defineRule } from '@oxlint/plugins'
+import { declarationsFunctionName, optionsFirst } from '../utils/index.ts'
+
+interface NoTopLevelFunctionsOptions {
+  banReExports: boolean
+  allowPattern?: string
+}
+
+/**
+ * Rejects top-level functions and function-valued variables, and can also reject re-exports.
+ *
+ * Example: A data-only constants file passes; `export const load = () => 1` fails.
+ */
+export const noTopLevelFunctions = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        banReExports: { type: 'boolean' },
+        allowPattern: { type: 'string' },
+      },
+    }],
+    defaultOptions: [{ banReExports: true }],
+    messages: {
+      noFunction: 'Files in this scope must not contain top-level function {{name}}.',
+      noReExport: 'Files in this scope must not re-export values.',
+    },
+  },
+  createOnce(context) {
+    return {
+      Program(program) {
+        const { banReExports, allowPattern } = optionsFirst<NoTopLevelFunctionsOptions>(context)
+        const allowed = allowPattern ? new RegExp(allowPattern) : null
+
+        for (const statement of program.body) {
+          if (banReExports && (statement.type === 'ExportAllDeclaration'
+            || (statement.type === 'ExportNamedDeclaration' && statement.source))) {
+            context.report({ node: statement, messageId: 'noReExport' })
+            continue
+          }
+
+          const declaration = statement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration'
+            ? statement.declaration
+            : statement
+
+          if (declaration?.type === 'FunctionDeclaration') {
+            if (!allowed?.test(declarationsFunctionName(declaration))) {
+              context.report({
+                node: declaration,
+                messageId: 'noFunction',
+                data: { name: declarationsFunctionName(declaration) },
+              })
+            }
+            continue
+          }
+
+          if (declaration?.type !== 'VariableDeclaration') {
+            continue
+          }
+
+          for (const item of declaration.declarations) {
+            if ((item.init?.type === 'FunctionExpression' || item.init?.type === 'ArrowFunctionExpression')
+              && !allowed?.test(declarationsFunctionName(item))) {
+              context.report({
+                node: item,
+                messageId: 'noFunction',
+                data: { name: declarationsFunctionName(item) },
+              })
+            }
+          }
+        }
+      },
+    }
+  },
+})

package/src/rules/no-trivial-functions.ts

@@ -0,0 +1,56 @@
+import { defineRule } from '@oxlint/plugins'
+import {
+  declarationsIsTrivialFunction,
+  declarationsTopLevelUnexportedFunctions,
+  exportsCollectFunctions,
+  optionsFirst,
+} from '../utils/index.ts'
+
+interface NoTrivialFunctionsOptions {
+  allowPattern?: string
+}
+
+/**
+ * Rejects top-level functions that are empty or only forward a lookup, identifier, or other call.
+ *
+ * Example: `export function loadUser(id: string) { return fetchUser(id) }` fails; a function with branching or extra statements passes.
+ */
+export const noTrivialFunctions = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        allowPattern: { type: 'string' },
+      },
+    }],
+    messages: {
+      trivial: 'Function {{name}} does nothing useful; inline it at the call site.',
+    },
+  },
+  createOnce(context) {
+    return {
+      Program(program) {
+        const { allowPattern } = optionsFirst<NoTrivialFunctionsOptions>(context, {})
+        const allowed = allowPattern ? new RegExp(allowPattern) : null
+        const seen = new Set<string>()
+
+        for (const item of [...exportsCollectFunctions(program), ...declarationsTopLevelUnexportedFunctions(program)]) {
+          const key = `${item.name}:${item.node.start}:${item.node.end}`
+
+          if (seen.has(key) || allowed?.test(item.name) || !declarationsIsTrivialFunction(item.node)) {
+            continue
+          }
+
+          seen.add(key)
+          context.report({
+            node: item.node,
+            messageId: 'trivial',
+            data: { name: item.name },
+          })
+        }
+      },
+    }
+  },
+})

package/src/rules/no-unescaped-like.ts

@@ -0,0 +1,67 @@
+import { defineRule } from '@oxlint/plugins'
+import {
+  astStaticMemberName,
+  optionsFirst,
+  sanitizersCallsConfigured,
+  sanitizersConfiguredBindings,
+} from '../utils/index.ts'
+
+interface NoUnescapedLikeOptions {
+  methods: string[]
+  sanitizers: string[]
+  allowSanitizedBindings?: boolean
+}
+
+/**
+ * Requires values passed to configured member methods to use a configured sanitizer call or sanitized binding.
+ *
+ * Example: `query.ilike(column, escape(term))` passes; passing `term` directly fails.
+ */
+export const noUnescapedLike = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        methods: { type: 'array', items: { type: 'string' } },
+        sanitizers: { type: 'array', items: { type: 'string' } },
+        allowSanitizedBindings: { type: 'boolean' },
+      },
+      required: ['methods', 'sanitizers'],
+    }],
+    messages: { unescaped: '.{{method}}() values must use a configured sanitizer.' },
+  },
+  createOnce(context) {
+    let sanitized = new Set<string>()
+    return {
+      Program(program) {
+        const { sanitizers, allowSanitizedBindings = true } = optionsFirst<NoUnescapedLikeOptions>(context)
+        sanitized = allowSanitizedBindings ? sanitizersConfiguredBindings(program, new Set(sanitizers)) : new Set()
+      },
+      CallExpression(node) {
+        if (node.callee.type !== 'MemberExpression') {
+          return
+        }
+
+        const { methods, sanitizers } = optionsFirst<NoUnescapedLikeOptions>(context)
+        const method = astStaticMemberName(node.callee)
+
+        if (!method || !methods.includes(method)) {
+          return
+        }
+
+        const value = node.arguments.at(-1)
+        const allowedIdentifier = value?.type === 'Identifier' && sanitized.has(value.name)
+
+        if (!sanitizersCallsConfigured(value, new Set(sanitizers)) && !allowedIdentifier) {
+          context.report({
+            node: value ?? node,
+            messageId: 'unescaped',
+            data: { method },
+          })
+        }
+      },
+    }
+  },
+})

package/src/rules/only-export-components.ts

@@ -0,0 +1,78 @@
+import { defineRule } from '@oxlint/plugins'
+import {
+  namingFileBasename,
+  optionsFirst,
+  reactComponentsExportCandidates,
+  reactComponentsIsLike,
+  reactComponentsPascalFromBasename,
+} from '../utils/index.ts'
+
+interface OnlyExportComponentsOptions {
+  matchFileName?: boolean
+}
+
+/**
+ * Allows only React components and type exports, with optional matching between component names and filenames.
+ *
+ * Example: `button.tsx` exporting `Button` passes; exporting a plain `buttonConfig` value fails.
+ */
+export const onlyExportComponents = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        matchFileName: { type: 'boolean' },
+      },
+    }],
+    messages: {
+      nonComponent: "Export '{{name}}' must be a React component or type.",
+      nameMismatch: "Component export '{{name}}' must match '{{expected}}' or its prefix.",
+    },
+  },
+  createOnce(context) {
+    return {
+      Program(program) {
+        const { matchFileName = true } = optionsFirst<OnlyExportComponentsOptions>(context, {})
+        const expected = reactComponentsPascalFromBasename(namingFileBasename(context.filename))
+        const components = []
+
+        for (const candidate of reactComponentsExportCandidates(program)) {
+          if (candidate.typeOnly) {
+            continue
+          }
+
+          if (!reactComponentsIsLike(program, candidate)) {
+            context.report({
+              node: candidate.node,
+              messageId: 'nonComponent',
+              data: { name: candidate.name, expected },
+            })
+            continue
+          }
+
+          components.push(candidate)
+        }
+
+        if (components.length === 0 || !matchFileName) {
+          return
+        }
+
+        const expectedKey = expected.toLowerCase()
+        const exact = components.some((candidate) => candidate.name.toLowerCase() === expectedKey)
+        const allPrefixed = components.every((candidate) => candidate.name.toLowerCase().startsWith(expectedKey))
+
+        if (!exact && !allPrefixed) {
+          for (const candidate of components) {
+            context.report({
+              node: candidate.node,
+              messageId: 'nameMismatch',
+              data: { name: candidate.name, expected },
+            })
+          }
+        }
+      },
+    }
+  },
+})

package/src/rules/require-file-factory.ts

@@ -0,0 +1,67 @@
+import { defineRule } from '@oxlint/plugins'
+import {
+  declarationsCollectFunctions,
+  exportsCollectFunctions,
+  namingFileBasename,
+  namingPascalCase,
+  optionsFirst,
+} from '../utils/index.ts'
+
+interface RequireFileFactoryOptions {
+  factory: string
+  allDeclarations?: boolean
+}
+
+/**
+ * Derives one expected factory name from the filename and requires that function to exist.
+ *
+ * Example: With `make{Stem}`, `email-renderer.ts` requires `makeEmailRenderer`.
+ */
+export const requireFileFactory = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        factory: { type: 'string' },
+        allDeclarations: { type: 'boolean' },
+      },
+      required: ['factory'],
+    }],
+    messages: {
+      factory: "Function '{{actual}}' must be named '{{expected}}'.",
+    },
+  },
+  createOnce(context) {
+    return {
+      Program(program) {
+        const { factory, allDeclarations = false } = optionsFirst<RequireFileFactoryOptions>(context)
+        const stem = namingFileBasename(context.filename).replace(/\.(tsx?|jsx?)$/, '')
+        const expected = factory
+          .replaceAll('{Stem}', namingPascalCase(stem))
+          .replaceAll('{stem}', stem)
+        const functions = allDeclarations ? declarationsCollectFunctions(program) : exportsCollectFunctions(program)
+
+        if (functions.length === 0) {
+          context.report({
+            node: program,
+            messageId: 'factory',
+            data: { actual: '<none>', expected },
+          })
+          return
+        }
+
+        for (const item of functions) {
+          if (item.name !== expected) {
+            context.report({
+              node: item.node,
+              messageId: 'factory',
+              data: { actual: item.name, expected },
+            })
+          }
+        }
+      },
+    }
+  },
+})

package/src/rules/require-object-params.ts

@@ -0,0 +1,32 @@
+import { defineRule } from '@oxlint/plugins'
+import { declarationsIsObjectParam, exportsCollectFunctions } from '../utils/index.ts'
+
+/**
+ * Requires exported functions to take at most one object-shaped parameter instead of positional arguments.
+ *
+ * Example: `createUser({ name })` passes; `createUser(name, email)` fails.
+ */
+export const requireObjectParams = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [],
+    messages: {
+      objectParams: 'Exported function {{name}} must accept at most one object parameter.',
+    },
+  },
+  createOnce(context) {
+    return {
+      Program(program) {
+        for (const item of exportsCollectFunctions(program)) {
+          if (item.node.params.length > 1 || item.node.params.some((param) => !declarationsIsObjectParam(param))) {
+            context.report({
+              node: item.node,
+              messageId: 'objectParams',
+              data: { name: item.name },
+            })
+          }
+        }
+      },
+    }
+  },
+})

package/src/rules/require-orpc-output.ts

@@ -0,0 +1,64 @@
+import { defineRule } from '@oxlint/plugins'
+import {
+  astStaticMemberName,
+  optionsFirst,
+  orpcFindChainCall,
+  orpcIsNamedOrComposedArgument,
+} from '../utils/index.ts'
+
+interface RequireOrpcOutputOptions {
+  composers: string[]
+  handlerMethod?: string
+  outputMethod?: string
+}
+
+/**
+ * Checks oRPC procedure chains for a configured output method before the configured handler method.
+ *
+ * Example: `.output(userSchema).handler(...)` passes; `.handler(...)` without output fails.
+ */
+export const requireOrpcOutput = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        composers: { type: 'array', items: { type: 'string' } },
+        handlerMethod: { type: 'string' },
+        outputMethod: { type: 'string' },
+      },
+      required: ['composers'],
+    }],
+    messages: {
+      missing: 'oRPC procedures must declare .output() before .handler().',
+      invalid: 'oRPC .output() must use a named schema or configured composer with a named schema.',
+    },
+  },
+  createOnce(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== 'MemberExpression') {
+          return
+        }
+
+        const { composers, handlerMethod = 'handler', outputMethod = 'output' } = optionsFirst<RequireOrpcOutputOptions>(context)
+
+        if (astStaticMemberName(node.callee) !== handlerMethod) {
+          return
+        }
+
+        const output = orpcFindChainCall(node.callee.object, outputMethod)
+
+        if (!output) {
+          context.report({ node, messageId: 'missing' })
+          return
+        }
+
+        if (!orpcIsNamedOrComposedArgument(output.arguments[0], new Set(composers))) {
+          context.report({ node: output, messageId: 'invalid' })
+        }
+      },
+    }
+  },
+})

package/src/rules/require-paired-call.ts

@@ -0,0 +1,71 @@
+import { defineRule } from '@oxlint/plugins'
+import { astImportedCallAliases, astResolvedCallName, optionsFirst } from '../utils/index.ts'
+import type { ESTree } from '@oxlint/plugins'
+
+interface RequirePairedCallOptions {
+  when: string
+  require: string
+}
+
+/**
+ * Requires a second configured call whenever the trigger call appears anywhere in the same file.
+ *
+ * Example: A file calling `useForm` can require a call to `standardSchemaResolver`.
+ */
+export const requirePairedCall = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        when: { type: 'string' },
+        require: { type: 'string' },
+      },
+      required: ['when', 'require'],
+    }],
+    messages: {
+      paired: '{{when}} requires a call to {{require}} in the same file.',
+    },
+  },
+  createOnce(context) {
+    let aliases = new Map<string, string>()
+    let firstWhen: ESTree.CallExpression | null = null
+    let sawRequired = false
+
+    return {
+      before() {
+        aliases = new Map()
+        firstWhen = null
+        sawRequired = false
+      },
+      Program(program) {
+        aliases = astImportedCallAliases(program)
+      },
+      CallExpression(node) {
+        const { when, require } = optionsFirst<RequirePairedCallOptions>(context)
+        const name = astResolvedCallName(node, aliases)
+
+        if (name === when && !firstWhen) {
+          firstWhen = node
+        }
+
+        if (name === require) {
+          sawRequired = true
+        }
+      },
+      after() {
+        if (!firstWhen || sawRequired) {
+          return
+        }
+
+        const { when, require } = optionsFirst<RequirePairedCallOptions>(context)
+        context.report({
+          node: firstWhen,
+          messageId: 'paired',
+          data: { when, require },
+        })
+      },
+    }
+  },
+})