oxlint-plugin-arch 0.2.1

package/src/rules/no-extra-factory-keys.ts

@@ -0,0 +1,58 @@
+import { defineRule } from '@oxlint/plugins'
+import {
+  factoriesCollectTopLevel,
+  factoriesDirectlyReturnedObjects,
+  factoriesObjectPropertyName,
+  optionsFirst,
+} from '../utils/index.ts'
+
+interface NoExtraFactoryKeysOptions {
+  keys: string[]
+  factoryPattern?: string
+}
+
+/**
+ * Checks direct object returns from selected top-level factories and rejects keys outside the configured allow-list.
+ *
+ * Example: With `keys: [run]`, `return { run }` passes while `return { run, preview }` fails.
+ */
+export const noExtraFactoryKeys = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        keys: { type: 'array', items: { type: 'string' } },
+        factoryPattern: { type: 'string' },
+      },
+      required: ['keys'],
+    }],
+    messages: {
+      extraKey: "Factory '{{factory}}' must not return key '{{key}}'; allowed keys: {{allowed}}.",
+    },
+  },
+  createOnce(context) {
+    return {
+      Program(program) {
+        const { keys, factoryPattern = '^make[A-Z]' } = optionsFirst<NoExtraFactoryKeysOptions>(context)
+
+        for (const factory of factoriesCollectTopLevel(program, new RegExp(factoryPattern))) {
+          for (const object of factoriesDirectlyReturnedObjects(factory)) {
+            for (const property of object.properties) {
+              const key = factoriesObjectPropertyName(property)
+
+              if (!key || !keys.includes(key)) {
+                context.report({
+                  node: property,
+                  messageId: 'extraKey',
+                  data: { factory: factory.name, key: key ?? '<computed or spread>', allowed: keys.join(', ') },
+                })
+              }
+            }
+          }
+        }
+      },
+    }
+  },
+})

package/src/rules/no-file-level-helpers.ts

@@ -0,0 +1,58 @@
+import { defineRule } from '@oxlint/plugins'
+import { declarationsFileLevelFunctionCandidates, optionsFirst, reactComponentsIsLike } from '../utils/index.ts'
+
+interface NoFileLevelHelpersOptions {
+  allowPattern?: string
+  detectComponents?: boolean
+  hookPattern?: string
+}
+
+/**
+ * Rejects top-level functions unless they are recognized components, hooks, or names allowed by configuration.
+ *
+ * Example: `useDialog` can pass as a hook, while a file-level `buildPayload` helper fails.
+ */
+export const noFileLevelHelpers = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        allowPattern: { type: 'string' },
+        detectComponents: { type: 'boolean' },
+        hookPattern: { type: 'string' },
+      },
+    }],
+    messages: {
+      helper: 'File-level helper {{name}} must move inside its owning component or hook.',
+    },
+  },
+  createOnce(context) {
+    return {
+      Program(program) {
+        const {
+          allowPattern,
+          detectComponents = true,
+          hookPattern = '^use[A-Z]',
+        } = optionsFirst<NoFileLevelHelpersOptions>(context, {})
+        const allowed = allowPattern ? new RegExp(allowPattern) : null
+        const hooks = new RegExp(hookPattern)
+
+        for (const candidate of declarationsFileLevelFunctionCandidates(program)) {
+          if ((detectComponents && reactComponentsIsLike(program, candidate))
+            || hooks.test(candidate.name)
+            || allowed?.test(candidate.name)) {
+            continue
+          }
+
+          context.report({
+            node: candidate.node,
+            messageId: 'helper',
+            data: { name: candidate.name },
+          })
+        }
+      },
+    }
+  },
+})

package/src/rules/no-imported-type-alias.ts

@@ -0,0 +1,83 @@
+import { defineRule } from '@oxlint/plugins'
+import type { ESTree } from '@oxlint/plugins'
+
+function importedAliasTarget(declaration: ESTree.Declaration | null, imports: Set<string>): string | undefined {
+  if (declaration?.type !== 'TSTypeAliasDeclaration'
+    || declaration.typeAnnotation.type !== 'TSTypeReference'
+    || declaration.typeAnnotation.typeName.type !== 'Identifier'
+    || !imports.has(declaration.typeAnnotation.typeName.name)) {
+    return undefined
+  }
+
+  return declaration.typeAnnotation.typeName.name
+}
+
+function specifierLocalName(specifier: ESTree.ExportSpecifier): string {
+  return specifier.local.type === 'Identifier' ? specifier.local.name : specifier.local.value
+}
+
+/**
+ * Rejects exported type aliases that merely rename an imported type without adding information.
+ *
+ * Example: `export type User = UserDto` fails when `UserDto` is imported; intersections and unions pass.
+ */
+export const noImportedTypeAlias = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [],
+    messages: {
+      alias: "Exported type '{{alias}}' must not re-alias imported type '{{name}}'.",
+    },
+  },
+  createOnce(context) {
+    return {
+      Program(program) {
+        const imports = new Set(program.body.flatMap((statement) => statement.type === 'ImportDeclaration'
+          ? statement.specifiers.map((specifier) => specifier.local.name)
+          : []))
+        const aliases = new Map<string, string>()
+
+        for (const statement of program.body) {
+          const declaration = statement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration'
+            ? statement.declaration
+            : statement
+          const imported = declaration && declaration.type.endsWith('Declaration')
+            ? importedAliasTarget(declaration as ESTree.Declaration, imports)
+            : undefined
+
+          if (declaration?.type === 'TSTypeAliasDeclaration' && imported) {
+            aliases.set(declaration.id.name, imported)
+          }
+        }
+
+        for (const statement of program.body) {
+          if (statement.type !== 'ExportNamedDeclaration') {
+            continue
+          }
+
+          const inline = importedAliasTarget(statement.declaration, imports)
+          if (inline && statement.declaration?.type === 'TSTypeAliasDeclaration') {
+            context.report({
+              node: statement.declaration,
+              messageId: 'alias',
+              data: { alias: statement.declaration.id.name, name: inline },
+            })
+          }
+
+          for (const specifier of statement.specifiers) {
+            const local = specifierLocalName(specifier)
+            const imported = aliases.get(local)
+
+            if (imported) {
+              context.report({
+                node: specifier,
+                messageId: 'alias',
+                data: { alias: local, name: imported },
+              })
+            }
+          }
+        }
+      },
+    }
+  },
+})

package/src/rules/no-inline-schema-elements.ts

@@ -0,0 +1,70 @@
+import { defineRule } from '@oxlint/plugins'
+import {
+  astStaticMemberName,
+  optionsFirst,
+  schemasElements,
+  schemasIsAllowedElement,
+  schemasIsCall,
+} from '../utils/index.ts'
+
+interface NoInlineSchemaElementsOptions {
+  namespaces: string[]
+  methods: string[]
+  structuralMethods: string[]
+  allowZodScalars: boolean
+}
+
+/**
+ * Requires configured schema combinators to reference named schemas instead of defining structural schemas inline.
+ *
+ * Example: `z.array(userSchema)` passes; `z.array(z.object({ id: z.string() }))` fails.
+ */
+export const noInlineSchemaElements = defineRule({
+  meta: {
+    type: 'problem',
+    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: ['array', 'discriminatedUnion', 'intersection', 'lazy', 'object', 'record', 'tuple', 'union'],
+      allowZodScalars: true,
+    }],
+    messages: { inline: 'z.{{method}}() elements must use named schemas.' },
+  },
+  createOnce(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== 'MemberExpression') {
+          return
+        }
+
+        const options = optionsFirst<NoInlineSchemaElementsOptions>(context)
+        const namespaces = new Set(options.namespaces)
+        const method = astStaticMemberName(node.callee)
+
+        if (!schemasIsCall(node, namespaces) || !method || !options.methods.includes(method)) {
+          return
+        }
+
+        for (const element of schemasElements(node)) {
+          if (!schemasIsAllowedElement(element, options.allowZodScalars, namespaces, new Set(options.structuralMethods))) {
+            context.report({
+              node: element,
+              messageId: 'inline',
+              data: { method },
+            })
+          }
+        }
+      },
+    }
+  },
+})

package/src/rules/no-local-schema-construction.ts

@@ -0,0 +1,162 @@
+import { defineRule } from '@oxlint/plugins'
+import {
+  namingPosixPath,
+  optionsFirst,
+  schemasIsConstruction,
+  schemasIsRuntimeImport,
+  schemasIsRuntimeReexport,
+  schemasRuntimeImportLocals,
+} from '../utils/index.ts'
+
+interface NoLocalSchemaConstructionOptions {
+  packages?: string[]
+  namespaces?: string[]
+  allowIn?: string[]
+  allowPathPatterns?: string[]
+  message?: string
+  runtimeImportMessage?: string
+  constructionMessage?: string
+}
+
+const defaultRuntimeImportMessage = 'Do not import runtime schema constructors from {{source}}; import a named schema instead.'
+const defaultConstructionMessage = 'Do not construct schemas locally; import a named schema instead.'
+
+function formatMessage(template: string, data: Record<string, string>): string {
+  return Object.entries(data).reduce((result, [key, value]) => result.replaceAll(`{{${key}}}`, value), template)
+}
+
+/**
+ * Rejects runtime schema-library imports and local schema construction, while allowing imported named schemas.
+ *
+ * Example: `schemaResolver(userSchema)` passes after importing `userSchema`; `import { z } from 'zod'` and `z.object({})` fail.
+ */
+export const noLocalSchemaConstruction = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        packages: { type: 'array', items: { type: 'string' } },
+        namespaces: { type: 'array', items: { type: 'string' } },
+        allowIn: { type: 'array', items: { type: 'string' } },
+        allowPathPatterns: { type: 'array', items: { type: 'string' } },
+        message: { type: 'string' },
+        runtimeImportMessage: { type: 'string' },
+        constructionMessage: { type: 'string' },
+      },
+    }],
+    defaultOptions: [{
+      packages: ['zod'],
+      namespaces: ['z'],
+    }],
+    messages: {
+      runtimeImport: '{{message}}',
+      construction: '{{message}}',
+    },
+  },
+  createOnce(context) {
+    let constructors = new Set<string>()
+
+    return {
+      before() {
+        const {
+          namespaces = ['z'],
+          allowIn = [],
+          allowPathPatterns = [],
+        } = optionsFirst<NoLocalSchemaConstructionOptions>(context, {})
+        const filename = namingPosixPath(context.filename)
+        constructors = new Set(namespaces)
+
+        if (allowIn.some((suffix) => filename.endsWith(suffix))
+          || allowPathPatterns.some((pattern) => new RegExp(pattern).test(filename))) {
+          return false
+        }
+      },
+      ImportDeclaration(node) {
+        const {
+          packages = ['zod'],
+          message,
+          runtimeImportMessage,
+        } = optionsFirst<NoLocalSchemaConstructionOptions>(context, {})
+
+        if (!schemasIsRuntimeImport(node, new Set(packages))) {
+          return
+        }
+
+        for (const name of schemasRuntimeImportLocals(node)) {
+          constructors.add(name)
+        }
+
+        context.report({
+          node,
+          messageId: 'runtimeImport',
+          data: {
+            message: formatMessage(
+              runtimeImportMessage ?? message ?? defaultRuntimeImportMessage,
+              { source: node.source.value },
+            ),
+          },
+        })
+      },
+      ExportNamedDeclaration(node) {
+        const {
+          packages = ['zod'],
+          message,
+          runtimeImportMessage,
+        } = optionsFirst<NoLocalSchemaConstructionOptions>(context, {})
+
+        if (!schemasIsRuntimeReexport(node, new Set(packages)) || !node.source) {
+          return
+        }
+
+        context.report({
+          node,
+          messageId: 'runtimeImport',
+          data: {
+            message: formatMessage(
+              runtimeImportMessage ?? message ?? defaultRuntimeImportMessage,
+              { source: node.source.value },
+            ),
+          },
+        })
+      },
+      ExportAllDeclaration(node) {
+        const {
+          packages = ['zod'],
+          message,
+          runtimeImportMessage,
+        } = optionsFirst<NoLocalSchemaConstructionOptions>(context, {})
+
+        if (!schemasIsRuntimeReexport(node, new Set(packages))) {
+          return
+        }
+
+        context.report({
+          node,
+          messageId: 'runtimeImport',
+          data: {
+            message: formatMessage(
+              runtimeImportMessage ?? message ?? defaultRuntimeImportMessage,
+              { source: node.source.value },
+            ),
+          },
+        })
+      },
+      CallExpression(node) {
+        if (!schemasIsConstruction(node, constructors)) {
+          return
+        }
+
+        const { message, constructionMessage } = optionsFirst<NoLocalSchemaConstructionOptions>(context, {})
+        context.report({
+          node,
+          messageId: 'construction',
+          data: {
+            message: formatMessage(constructionMessage ?? message ?? defaultConstructionMessage, {}),
+          },
+        })
+      },
+    }
+  },
+})

package/src/rules/no-rederive-schema.ts

@@ -0,0 +1,66 @@
+import { defineRule } from '@oxlint/plugins'
+import { optionsFirst, schemasTypeOperator } from '../utils/index.ts'
+
+interface NoRederiveSchemaOptions {
+  from: string[]
+  namespaces?: string[]
+  operators?: string[]
+}
+
+/**
+ * Prevents deriving types from configured imported schemas when the package should export and consume a named type.
+ *
+ * Example: `z.infer<typeof importedSchema>` fails; deriving from a same-file schema passes.
+ */
+export const noRederiveSchema = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        from: { type: 'array', items: { type: 'string' } },
+        namespaces: { type: 'array', items: { type: 'string' } },
+        operators: { type: 'array', items: { type: 'string' } },
+      },
+      required: ['from'],
+    }],
+    messages: {
+      rederive: 'Do not derive {{operator}} from imported schema {{schema}}; import its DTO type.',
+    },
+  },
+  createOnce(context) {
+    let imported = new Set<string>()
+
+    return {
+      Program(program) {
+        const { from } = optionsFirst<NoRederiveSchemaOptions>(context)
+        imported = new Set(program.body.flatMap((statement) => statement.type === 'ImportDeclaration'
+          && from.includes(statement.source.value)
+          ? statement.specifiers.map((specifier) => specifier.local.name)
+          : []))
+      },
+      TSTypeReference(node) {
+        const {
+          namespaces = ['z'],
+          operators = ['infer', 'input'],
+        } = optionsFirst<NoRederiveSchemaOptions>(context)
+        const operator = schemasTypeOperator(node, new Set(namespaces), new Set(operators))
+        const parameter = node.typeArguments?.params[0]
+
+        if (!operator
+          || parameter?.type !== 'TSTypeQuery'
+          || parameter.exprName.type !== 'Identifier'
+          || !imported.has(parameter.exprName.name)) {
+          return
+        }
+
+        context.report({
+          node,
+          messageId: 'rederive',
+          data: { operator, schema: parameter.exprName.name },
+        })
+      },
+    }
+  },
+})

package/src/rules/no-restricted-files.ts

@@ -0,0 +1,40 @@
+import { defineRule } from '@oxlint/plugins'
+import { optionsFirst } from '../utils/index.ts'
+
+interface NoRestrictedFilesOptions {
+  message: string
+}
+
+/**
+ * Reports every file matched by the consumer glob, making forbidden file locations or extensions lintable.
+ *
+ * Example: Enable it for hook TSX files to require hooks to use `.ts` files.
+ */
+export const noRestrictedFiles = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        message: { type: 'string' },
+      },
+      required: ['message'],
+    }],
+    messages: {
+      restricted: '{{message}}',
+    },
+  },
+  createOnce(context) {
+    return {
+      Program(program) {
+        const { message } = optionsFirst<NoRestrictedFilesOptions>(context)
+        context.report({
+          node: program,
+          messageId: 'restricted',
+          data: { message },
+        })
+      },
+    }
+  },
+})

package/src/rules/no-restricted-token.ts

@@ -0,0 +1,71 @@
+import { defineRule } from '@oxlint/plugins'
+import { namingPosixPath, optionsFirst } from '../utils/index.ts'
+import type { ESTree } from '@oxlint/plugins'
+
+interface NoRestrictedTokenOptions {
+  token: string
+  allowIn: string[]
+  allowPathPatterns?: string[]
+}
+
+function tokenIsTypeOnlyImport(node: ESTree.Node): boolean {
+  const parent = node.parent
+
+  if (parent?.type === 'ImportSpecifier') {
+    return parent.importKind === 'type'
+      || (parent.parent.type === 'ImportDeclaration' && parent.parent.importKind === 'type')
+  }
+
+  return (parent?.type === 'ImportDefaultSpecifier' || parent?.type === 'ImportNamespaceSpecifier')
+    && parent.parent.type === 'ImportDeclaration'
+    && parent.parent.importKind === 'type'
+}
+
+/**
+ * Restricts one identifier to configured owner paths while leaving path selection to the consumer.
+ *
+ * Example: `RouterClient` can be allowed in `rpc.client.ts` and rejected everywhere else.
+ */
+export const noRestrictedToken = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        token: { type: 'string' },
+        allowIn: { type: 'array', items: { type: 'string' } },
+        allowPathPatterns: { type: 'array', items: { type: 'string' } },
+      },
+      required: ['token', 'allowIn'],
+    }],
+    messages: {
+      restricted: "'{{token}}' may only appear in configured owner paths.",
+    },
+  },
+  createOnce(context) {
+    return {
+      before() {
+        const options = optionsFirst<NoRestrictedTokenOptions>(context)
+        const filename = namingPosixPath(context.filename)
+        const allowed = options.allowIn.some((suffix) => filename.endsWith(suffix))
+          || (options.allowPathPatterns ?? []).some((pattern) => new RegExp(pattern).test(filename))
+
+        if (allowed) {
+          return false
+        }
+      },
+      Identifier(node) {
+        const { token } = optionsFirst<NoRestrictedTokenOptions>(context)
+
+        if (node.name === token && !tokenIsTypeOnlyImport(node)) {
+          context.report({
+            node,
+            messageId: 'restricted',
+            data: { token },
+          })
+        }
+      },
+    }
+  },
+})

package/src/rules/no-runtime-in-types.ts

@@ -0,0 +1,72 @@
+import { defineRule } from '@oxlint/plugins'
+import {
+  declarationsIsRuntime,
+  declarationsRuntimeKind,
+  declarationsRuntimeName,
+  optionsFirst,
+} from '../utils/index.ts'
+
+interface NoRuntimeInTypesOptions {
+  allow?: ('class' | 'default' | 'enum' | 'function' | 'variable')[]
+}
+
+/**
+ * Keeps consumer-selected type modules free of runtime declarations, with optional declaration-category exceptions.
+ *
+ * Example: An interface passes; `export const value = 1` fails unless variables are allowed.
+ */
+export const noRuntimeInTypes = defineRule({
+  meta: {
+    type: 'problem',
+    schema: [{
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        allow: {
+          type: 'array',
+          items: { type: 'string', enum: ['class', 'default', 'enum', 'function', 'variable'] },
+        },
+      },
+    }],
+    messages: {
+      runtimeValue: 'Types files must not contain runtime value {{name}}.',
+    },
+  },
+  createOnce(context) {
+    return {
+      Program(program) {
+        const { allow = [] } = optionsFirst<NoRuntimeInTypesOptions>(context, {})
+
+        for (const statement of program.body) {
+          const declaration = statement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration'
+            ? statement.declaration
+            : statement
+
+          if (!declaration) {
+            continue
+          }
+
+          if (declarationsIsRuntime(declaration)) {
+            if (!declaration.declare && !allow.includes(declarationsRuntimeKind(declaration))) {
+              context.report({
+                node: declaration,
+                messageId: 'runtimeValue',
+                data: { name: declarationsRuntimeName(declaration) },
+              })
+            }
+            continue
+          }
+
+          if (!allow.includes('default') && statement.type === 'ExportDefaultDeclaration'
+            && declaration.type !== 'TSInterfaceDeclaration' && declaration.type !== 'TSTypeAliasDeclaration') {
+            context.report({
+              node: statement,
+              messageId: 'runtimeValue',
+              data: { name: 'default' },
+            })
+          }
+        }
+      },
+    }
+  },
+})