@tanstack/eslint-plugin-router 1.20.3-alpha.1

package/src/__tests__/create-route-property-order.utils.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, test } from 'vitest'
+import {
+  getCheckedProperties,
+  sortDataByOrder,
+} from '../rules/create-route-property-order/create-route-property-order.utils'
+
+describe('create-route-property-order utils', () => {
+  describe('sortDataByOrder', () => {
+    const testCases = [
+      {
+        data: [{ key: 'a' }, { key: 'c' }, { key: 'b' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: [{ key: 'a' }, { key: 'b' }, { key: 'c' }],
+      },
+      {
+        data: [{ key: 'b' }, { key: 'a' }, { key: 'c' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: [{ key: 'a' }, { key: 'b' }, { key: 'c' }],
+      },
+      {
+        data: [{ key: 'a' }, { key: 'b' }, { key: 'c' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: null,
+      },
+      {
+        data: [{ key: 'a' }, { key: 'b' }, { key: 'c' }, { key: 'd' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: null,
+      },
+      {
+        data: [{ key: 'a' }, { key: 'b' }, { key: 'd' }, { key: 'c' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: null,
+      },
+      {
+        data: [{ key: 'd' }, { key: 'a' }, { key: 'b' }, { key: 'c' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: null,
+      },
+      {
+        data: [{ key: 'd' }, { key: 'b' }, { key: 'a' }, { key: 'c' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: [{ key: 'd' }, { key: 'a' }, { key: 'b' }, { key: 'c' }],
+      },
+      {
+        data: [{ key: 'd' }, { key: 'b' }, { key: 'a' }, { key: 'c' }],
+        orderArray: [
+          [['a', 'b'], ['d']],
+          [['d'], ['c']],
+        ],
+        key: 'key',
+        expected: [{ key: 'b' }, { key: 'a' }, { key: 'd' }, { key: 'c' }],
+      },
+      {
+        data: [
+          { key: 'd' },
+          { key: 'b' },
+          { key: 'a' },
+          { key: 'c' },
+          { key: 'f' },
+        ],
+        orderArray: [
+          [
+            ['a', 'b'],
+            ['d', 'f'],
+          ],
+          [['d'], ['c']],
+        ],
+        key: 'key',
+        expected: [
+          { key: 'b' },
+          { key: 'a' },
+          { key: 'd' },
+          { key: 'f' },
+          { key: 'c' },
+        ],
+      },
+      {
+        data: [
+          { key: 'd' },
+          { key: 'b' },
+          { key: 'a' },
+          { key: 'c' },
+          { key: 'f' },
+        ],
+        orderArray: [
+          [
+            ['a', 'b'],
+            ['d', 'f'],
+          ],
+          [['d', 'f'], ['c']],
+        ],
+        key: 'key',
+        expected: [
+          { key: 'b' },
+          { key: 'a' },
+          { key: 'd' },
+          { key: 'f' },
+          { key: 'c' },
+        ],
+      },
+    ] as const
+    test.each(testCases)(
+      '$data $orderArray $key $expected',
+      ({ data, orderArray, key, expected }) => {
+        const sortedData = sortDataByOrder(data, orderArray, key)
+        expect(sortedData).toEqual(expected)
+      },
+    )
+  })
+})
+
+describe('getCheckedProperties', () => {
+  const testCases = [
+    {
+      orderRules: [
+        [['a', 'b'], ['c']],
+        [['c'], ['d']],
+      ],
+      expected: ['a', 'b', 'c', 'd'],
+    },
+    {
+      orderRules: [
+        [['a', 'b'], ['c']],
+        [['d'], ['e']],
+      ],
+      expected: ['a', 'b', 'c', 'd', 'e'],
+    },
+    {
+      orderRules: [
+        [['a', 'b'], ['c']],
+        [['d'], ['e']],
+        [['c'], ['f']],
+      ],
+      expected: ['a', 'b', 'c', 'd', 'e', 'f'],
+    },
+    {
+      orderRules: [
+        [['a', 'b'], ['c']],
+        [['d'], ['e']],
+        [['c'], ['f']],
+        [['f'], ['g']],
+      ],
+      expected: ['a', 'b', 'c', 'd', 'e', 'f', 'g'],
+    },
+  ] as const
+  test.each(testCases)('$orderRules $expected', ({ orderRules, expected }) => {
+    const checkedProperties = getCheckedProperties(orderRules)
+    expect(checkedProperties).toEqual(expected)
+  })
+})

package/src/__tests__/test-utils.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from 'vitest'
+import {
+  expectArrayEqualIgnoreOrder,
+  generateInterleavedCombinations,
+  generatePartialCombinations,
+  generatePermutations,
+} from './test-utils'
+
+describe('test-utils', () => {
+  describe('generatePermutations', () => {
+    const testCases = [
+      {
+        input: ['a', 'b', 'c'],
+        expected: [
+          ['a', 'b', 'c'],
+          ['a', 'c', 'b'],
+          ['b', 'a', 'c'],
+          ['b', 'c', 'a'],
+          ['c', 'a', 'b'],
+          ['c', 'b', 'a'],
+        ],
+      },
+      {
+        input: ['a', 'b'],
+        expected: [
+          ['a', 'b'],
+          ['b', 'a'],
+        ],
+      },
+      {
+        input: ['a'],
+        expected: [['a']],
+      },
+    ]
+    test.each(testCases)('$input $expected', ({ input, expected }) => {
+      const permutations = generatePermutations(input)
+      expect(permutations).toEqual(expected)
+    })
+  })
+
+  describe('generatePartialCombinations', () => {
+    const testCases = [
+      {
+        input: ['a', 'b', 'c'],
+        minLength: 2,
+        expected: [
+          ['a', 'b'],
+          ['a', 'c'],
+          ['b', 'c'],
+          ['a', 'b', 'c'],
+        ],
+      },
+      {
+        input: ['a', 'b'],
+        expected: [['a', 'b']],
+        minLength: 2,
+      },
+      {
+        input: ['a'],
+        expected: [],
+        minLength: 2,
+      },
+      {
+        input: ['a'],
+        expected: [['a']],
+        minLength: 1,
+      },
+      {
+        input: ['a'],
+        expected: [[], ['a']],
+        minLength: 0,
+      },
+    ]
+    test.each(testCases)(
+      '$input $minLength $expected ',
+      ({ input, minLength, expected }) => {
+        const combinations = generatePartialCombinations(input, minLength)
+        expectArrayEqualIgnoreOrder(combinations, expected)
+      },
+    )
+  })
+
+  describe('generateInterleavedCombinations', () => {
+    const testCases = [
+      {
+        data: ['a', 'b'],
+        additional: ['x'],
+        expected: [
+          ['a', 'b'],
+          ['x', 'a', 'b'],
+          ['a', 'x', 'b'],
+          ['a', 'b', 'x'],
+        ],
+      },
+    ]
+    test.each(testCases)(
+      '$input $expected',
+      ({ data, additional, expected }) => {
+        const combinations = generateInterleavedCombinations(data, additional)
+        expectArrayEqualIgnoreOrder(combinations, expected)
+      },
+    )
+  })
+})

package/src/__tests__/test-utils.ts

@@ -0,0 +1,108 @@
+import { expect } from 'vitest'
+
+export function generatePermutations<T>(arr: Array<T>): Array<Array<T>> {
+  if (arr.length <= 1) {
+    return [arr]
+  }
+
+  const result: Array<Array<T>> = []
+  for (let i = 0; i < arr.length; i++) {
+    const rest = arr.slice(0, i).concat(arr.slice(i + 1))
+    const restPermutations = generatePermutations(rest)
+    for (const perm of restPermutations) {
+      result.push([arr[i]!, ...perm])
+    }
+  }
+
+  return result
+}
+
+export function generatePartialCombinations<T>(
+  arr: ReadonlyArray<T>,
+  minLength: number,
+): Array<Array<T>> {
+  const result: Array<Array<T>> = []
+
+  function backtrack(start: number, current: Array<T>) {
+    if (current.length > minLength - 1) {
+      result.push([...current])
+    }
+    for (let i = start; i < arr.length; i++) {
+      current.push(arr[i]!)
+      backtrack(i + 1, current)
+      current.pop()
+    }
+  }
+  backtrack(0, [])
+  return result
+}
+
+export function expectArrayEqualIgnoreOrder<T>(a: Array<T>, b: Array<T>) {
+  expect([...a].sort()).toEqual([...b].sort())
+}
+
+export function normalizeIndent(template: TemplateStringsArray) {
+  const codeLines = template[0]?.split('\n') ?? ['']
+  const leftPadding = codeLines[1]?.match(/\s+/)?.[0] ?? ''
+  return codeLines.map((line) => line.slice(leftPadding.length)).join('\n')
+}
+
+export function generateInterleavedCombinations<
+  TData,
+  TAdditional,
+  TResult extends TData | TAdditional,
+>(
+  data: Array<TData> | ReadonlyArray<TData>,
+  additional: Array<TAdditional> | ReadonlyArray<TAdditional>,
+): Array<Array<TResult>> {
+  const result: Array<Array<TResult>> = []
+
+  function getSubsets(array: Array<TAdditional>): Array<Array<TAdditional>> {
+    return array.reduce(
+      (subsets, value) => {
+        return subsets.concat(subsets.map((set) => [...set, value]))
+      },
+      [[]] as Array<Array<TAdditional>>,
+    )
+  }
+
+  function insertAtPositions(
+    data: Array<TResult>,
+    subset: Array<TResult>,
+  ): Array<Array<TResult>> {
+    const combinations: Array<Array<TResult>> = []
+
+    const recurse = (
+      currentData: Array<TResult>,
+      currentSubset: Array<TResult>,
+      start: number,
+    ): void => {
+      if (currentSubset.length === 0) {
+        combinations.push([...currentData])
+        return
+      }
+
+      for (let i = start; i <= currentData.length; i++) {
+        const newData = [
+          ...currentData.slice(0, i),
+          currentSubset[0]!,
+          ...currentData.slice(i),
+        ]
+        recurse(newData, currentSubset.slice(1), i + 1)
+      }
+    }
+
+    recurse(data, subset, 0)
+    return combinations
+  }
+
+  const subsets = getSubsets(additional as Array<TAdditional>)
+
+  subsets.forEach((subset) => {
+    result.push(
+      ...insertAtPositions(data as Array<TResult>, subset as Array<TResult>),
+    )
+  })
+
+  return result
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+import { rules } from './rules'
+import type { ESLint, Linter } from 'eslint'
+import type { RuleModule } from '@typescript-eslint/utils/ts-eslint'
+
+type RuleKey = keyof typeof rules
+
+interface Plugin extends Omit<ESLint.Plugin, 'rules'> {
+  rules: Record<RuleKey, RuleModule<any, any, any>>
+  configs: {
+    recommended: ESLint.ConfigData
+    'flat/recommended': Array<Linter.FlatConfig>
+  }
+}
+
+const plugin: Plugin = {
+  meta: {
+    name: '@tanstack/eslint-plugin-router',
+  },
+  configs: {} as Plugin['configs'],
+  rules,
+}
+
+// Assign configs here so we can reference `plugin`
+Object.assign(plugin.configs, {
+  recommended: {
+    plugins: ['@tanstack/eslint-plugin-router'],
+    rules: {
+      '@tanstack/router/create-route-property-order': 'warn',
+    },
+  },
+  'flat/recommended': [
+    {
+      plugins: {
+        '@tanstack/router': plugin,
+      },
+      rules: {
+        '@tanstack/router/create-route-property-order': 'warn',
+      },
+    },
+  ],
+})
+
+export default plugin

package/src/rules/create-route-property-order/constants.ts

@@ -0,0 +1,40 @@
+import { getCheckedProperties } from './create-route-property-order.utils'
+
+export const createRouteFunctionsIndirect = [
+  'createFileRoute',
+  'createRootRouteWithContext',
+] as const
+export const createRouteFunctionsDirect = [
+  'createRootRoute',
+  'createRoute',
+] as const
+
+export const createRouteFunctions = [
+  ...createRouteFunctionsDirect,
+  ...createRouteFunctionsIndirect,
+] as const
+
+export type CreateRouteFunction = (typeof createRouteFunctions)[number]
+
+export const sortRules = [
+  [['params', 'validateSearch'], ['search']],
+  [['search'], ['loaderDeps']],
+  [['loaderDeps'], ['context']],
+  [['context'], ['beforeLoad']],
+  [['beforeLoad'], ['loader']],
+  [
+    ['loader'],
+    [
+      'onEnter',
+      'onStay',
+      'onLeave',
+      'head',
+      'scripts',
+      'headers',
+      'remountDeps',
+    ],
+  ],
+] as const
+
+export type CheckedProperties = (typeof sortRules)[number][number][number]
+export const checkedProperties = getCheckedProperties(sortRules)

package/src/rules/create-route-property-order/create-route-property-order.rule.ts

@@ -0,0 +1,124 @@
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils'
+
+import { getDocsUrl } from '../../utils/get-docs-url'
+import { detectTanstackRouterImports } from '../../utils/detect-router-imports'
+import { sortDataByOrder } from './create-route-property-order.utils'
+import {
+  createRouteFunctions,
+  createRouteFunctionsIndirect,
+  sortRules,
+} from './constants'
+import type { CreateRouteFunction } from './constants'
+import type { ExtraRuleDocs } from '../../types'
+
+const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl)
+
+const createRouteFunctionSet = new Set(createRouteFunctions)
+function isCreateRouteFunction(node: any): node is CreateRouteFunction {
+  return createRouteFunctionSet.has(node)
+}
+
+export const name = 'create-route-property-order'
+
+export const rule = createRule({
+  name,
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ensure correct order of inference sensitive properties for createRoute functions',
+      recommended: 'error',
+    },
+    messages: {
+      invalidOrder: 'Invalid order of properties for `{{function}}`.',
+    },
+    schema: [],
+    hasSuggestions: true,
+    fixable: 'code',
+  },
+  defaultOptions: [],
+
+  create: detectTanstackRouterImports((context) => {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== AST_NODE_TYPES.Identifier) {
+          return
+        }
+        const createRouteFunction = node.callee.name
+        if (!isCreateRouteFunction(createRouteFunction)) {
+          return
+        }
+        let args = node.arguments
+        if (createRouteFunctionsIndirect.includes(createRouteFunction as any)) {
+          if (node.parent.type === AST_NODE_TYPES.CallExpression) {
+            args = node.parent.arguments
+          } else {
+            return
+          }
+        }
+
+        const argument = args[0]
+        if (argument === undefined || argument.type !== 'ObjectExpression') {
+          return
+        }
+
+        const allProperties = argument.properties
+        // no need to sort if there is at max 1 property
+        if (allProperties.length < 2) {
+          return
+        }
+
+        const properties = allProperties.flatMap((p) => {
+          if (
+            p.type === AST_NODE_TYPES.Property &&
+            p.key.type === AST_NODE_TYPES.Identifier
+          ) {
+            return { name: p.key.name, property: p }
+          } else if (p.type === AST_NODE_TYPES.SpreadElement) {
+            if (p.argument.type === AST_NODE_TYPES.Identifier) {
+              return { name: p.argument.name, property: p }
+            } else {
+              throw new Error('Unsupported spread element')
+            }
+          }
+          return []
+        })
+
+        const sortedProperties = sortDataByOrder(properties, sortRules, 'name')
+        if (sortedProperties === null) {
+          return
+        }
+        context.report({
+          node: argument,
+          data: { function: node.callee.name },
+          messageId: 'invalidOrder',
+          fix(fixer) {
+            const sourceCode = context.sourceCode
+
+            const text = sortedProperties.reduce(
+              (sourceText, specifier, index) => {
+                let text = ''
+                if (index < allProperties.length - 1) {
+                  text = sourceCode
+                    .getText()
+                    .slice(
+                      allProperties[index]!.range[1],
+                      allProperties[index + 1]!.range[0],
+                    )
+                }
+                return (
+                  sourceText + sourceCode.getText(specifier.property) + text
+                )
+              },
+              '',
+            )
+            return fixer.replaceTextRange(
+              [allProperties[0]!.range[0], allProperties.at(-1)!.range[1]],
+              text,
+            )
+          },
+        })
+      },
+    }
+  }),
+})

package/src/rules/create-route-property-order/create-route-property-order.utils.ts

@@ -0,0 +1,73 @@
+export function sortDataByOrder<T, TKey extends keyof T>(
+  data: Array<T> | ReadonlyArray<T>,
+  orderRules: ReadonlyArray<
+    Readonly<[ReadonlyArray<T[TKey]>, ReadonlyArray<T[TKey]>]>
+  >,
+  key: TKey,
+): Array<T> | null {
+  const getSubsetIndex = (
+    item: T[TKey],
+    subsets: ReadonlyArray<ReadonlyArray<T[TKey]> | Array<T[TKey]>>,
+  ): number | null => {
+    for (let i = 0; i < subsets.length; i++) {
+      if (subsets[i]?.includes(item)) {
+        return i
+      }
+    }
+    return null
+  }
+
+  const orderSets = orderRules.reduce(
+    (sets, [A, B]) => [...sets, A, B],
+    [] as Array<ReadonlyArray<T[TKey]> | Array<T[TKey]>>,
+  )
+
+  const inOrderArray = data.filter(
+    (item) => getSubsetIndex(item[key], orderSets) !== null,
+  )
+
+  let wasResorted = false as boolean
+
+  // Sort by the relative order defined by the rules
+  const sortedArray = inOrderArray.sort((a, b) => {
+    const aKey = a[key],
+      bKey = b[key]
+    const aSubsetIndex = getSubsetIndex(aKey, orderSets)
+    const bSubsetIndex = getSubsetIndex(bKey, orderSets)
+
+    // If both items belong to different subsets, sort by their subset order
+    if (
+      aSubsetIndex !== null &&
+      bSubsetIndex !== null &&
+      aSubsetIndex !== bSubsetIndex
+    ) {
+      return aSubsetIndex - bSubsetIndex
+    }
+
+    // If both items belong to the same subset or neither is in the subset, keep their relative order
+    return 0
+  })
+
+  const inOrderIterator = sortedArray.values()
+  const result = data.map((item) => {
+    if (getSubsetIndex(item[key], orderSets) !== null) {
+      const sortedItem = inOrderIterator.next().value!
+      if (sortedItem[key] !== item[key]) {
+        wasResorted = true
+      }
+      return sortedItem
+    }
+    return item
+  })
+
+  if (!wasResorted) {
+    return null
+  }
+  return result
+}
+
+export function getCheckedProperties<T>(
+  orderRules: ReadonlyArray<ReadonlyArray<ReadonlyArray<T>>>,
+): ReadonlyArray<T> {
+  return [...new Set<T>(orderRules.flat(2))]
+}

package/src/rules.ts

@@ -0,0 +1,15 @@
+import * as createRoutePropertyOrder from './rules/create-route-property-order/create-route-property-order.rule'
+import type { ESLintUtils } from '@typescript-eslint/utils'
+import type { ExtraRuleDocs } from './types'
+
+export const rules: Record<
+  string,
+  ESLintUtils.RuleModule<
+    string,
+    ReadonlyArray<unknown>,
+    ExtraRuleDocs,
+    ESLintUtils.RuleListener
+  >
+> = {
+  [createRoutePropertyOrder.name]: createRoutePropertyOrder.rule,
+}

package/src/types.ts

@@ -0,0 +1,3 @@
+export type ExtraRuleDocs = {
+  recommended: 'strict' | 'error' | 'warn'
+}