orca/config/oxlint-plugins/app-store-performance.mjs

const ALLOCATING_METHODS = new Set([
  'filter',
  'flat',
  'flatMap',
  'map',
  'toReversed',
  'toSorted',
  'toSpliced',
  'with'
])
const ALLOCATING_OBJECT_STATICS = new Set([
  'assign',
  'create',
  'entries',
  'fromEntries',
  'keys',
  'values'
])
const FUNCTION_NODES = new Set([
  'ArrowFunctionExpression',
  'FunctionDeclaration',
  'FunctionExpression'
])

function identifierName(node) {
  return node?.type === 'Identifier' ? node.name : null
}

function propertyName(node) {
  if (node?.type !== 'MemberExpression') {
    return null
  }
  if (!node.computed) {
    return identifierName(node.property)
  }
  return node.property?.type === 'Literal' && typeof node.property.value === 'string'
    ? node.property.value
    : null
}

function functionNode(node) {
  return FUNCTION_NODES.has(node?.type) ? node : null
}

function returnedExpressions(selector) {
  if (!functionNode(selector)) {
    return []
  }
  if (selector.body.type !== 'BlockStatement') {
    return [selector.body]
  }
  const expressions = []
  const visit = (node) => {
    if (!node || typeof node !== 'object') {
      return
    }
    if (node !== selector.body && FUNCTION_NODES.has(node.type)) {
      return
    }
    if (node.type === 'ReturnStatement') {
      if (node.argument) {
        expressions.push(node.argument)
      }
      return
    }
    for (const [key, child] of Object.entries(node)) {
      if (key === 'parent') {
        continue
      }
      if (Array.isArray(child)) {
        child.forEach(visit)
      } else {
        visit(child)
      }
    }
  }
  visit(selector.body)
  return expressions
}

function unwrapShallowSelector(selector, state) {
  if (
    selector?.type === 'CallExpression' &&
    selector.callee.type === 'Identifier' &&
    state.hookNames.has(selector.callee.name) &&
    state.shallowHooks.has(variableFor(selector.callee, state))
  ) {
    return { selector: selector.arguments[0], shallow: true }
  }
  return { selector, shallow: false }
}

function isIdentitySelector(selector) {
  const parameter = functionNode(selector)?.params[0]
  if (parameter?.type !== 'Identifier') {
    return false
  }
  return returnedExpressions(selector).some(
    (expression) => expression.type === 'Identifier' && expression.name === parameter.name
  )
}

// Inline selectors flag ANY allocating branch; delegated helpers require EVERY branch so cache.get(k) ?? build(state) remains valid.
function allocates(expression, everyBranch) {
  const branches =
    expression?.type === 'ConditionalExpression'
      ? [expression.consequent, expression.alternate]
      : expression?.type === 'LogicalExpression'
        ? [expression.left, expression.right]
        : null
  if (branches) {
    return everyBranch
      ? branches.every((branch) => allocates(branch, true))
      : branches.some((branch) => allocates(branch, false))
  }
  if (
    expression?.type === 'ArrayExpression' ||
    expression?.type === 'ObjectExpression' ||
    expression?.type === 'NewExpression'
  ) {
    return true
  }
  if (expression?.type !== 'CallExpression') {
    return false
  }
  const callee = expression.callee
  const method = propertyName(callee)
  return (
    ALLOCATING_METHODS.has(method) ||
    (identifierName(callee.object) === 'Object' && ALLOCATING_OBJECT_STATICS.has(method))
  )
}

function isAllocatingExpression(expression) {
  return allocates(expression, false)
}

// Project-local zustand hooks follow the use<Name>Store convention; React's
// useSyncExternalStore matches that shape but is not a store subscription.
const STORE_HOOK_NAME = /^use[A-Z][A-Za-z0-9]*Store$/
const NON_STORE_HOOKS = new Set(['useSyncExternalStore'])

function isLocalModuleSource(source) {
  return typeof source === 'string' && (source.startsWith('.') || source.startsWith('@/'))
}

/** Module scope only: a component-local helper must not shadow a same-named import. */
function isModuleScope(node) {
  const parent = node.parent
  return (
    parent?.type === 'Program' ||
    (parent?.type === 'ExportNamedDeclaration' && parent.parent?.type === 'Program')
  )
}

/** Resolve the binding at the use site, including nested lexical shadows. */
function variableFor(node, state) {
  const name = identifierName(node)
  for (let scope = name && state.sourceCode.getScope(node); scope; scope = scope.upper) {
    const variable = scope.set.get(name)
    if (variable) {
      return variable
    }
  }
  return null
}

/** Inline function, or a module-scope selector referenced by its lexical binding. */
function resolveSelector(argument, state) {
  if (functionNode(argument)) {
    return argument
  }
  const definition = variableFor(argument, state)?.defs[0]
  const declaration = definition?.node
  if (
    definition?.type === 'FunctionName' &&
    declaration.type === 'FunctionDeclaration' &&
    isModuleScope(declaration)
  ) {
    return declaration
  }
  return definition?.type === 'Variable' &&
    declaration.type === 'VariableDeclarator' &&
    isModuleScope(declaration.parent)
    ? functionNode(declaration.init)
    : null
}

// Inspect one delegated module helper hop to catch hidden allocations; leave unresolved helpers alone.
function expandThroughNamedHelper(expression, state) {
  const helper =
    expression?.type === 'CallExpression' && expression.callee.type === 'Identifier'
      ? resolveSelector(expression.callee, state)
      : undefined
  const returned = helper ? returnedExpressions(helper) : []
  return returned.length > 0 && returned.every((entry) => allocates(entry, true))
    ? returned
    : [expression]
}

function createRuleState(sourceCode) {
  return {
    appStoreHooks: new Set(),
    shallowHooks: new Set(),
    hookNames: new Set(),
    sourceCode,
    deferredCalls: []
  }
}

function recordImports(node, state) {
  const source = node.source?.value
  for (const specifier of node.specifiers) {
    if (specifier.type !== 'ImportSpecifier') {
      continue
    }
    const imported = identifierName(specifier.imported)
    const shallow = source === 'zustand/react/shallow' && imported === 'useShallow'
    // useAppStore is the app store wherever it is re-exported from; sibling
    // stores are trusted by naming convention only when they come from this codebase.
    const store =
      STORE_HOOK_NAME.test(imported ?? '') &&
      !NON_STORE_HOOKS.has(imported) &&
      (imported === 'useAppStore' || isLocalModuleSource(source))
    // Why: getScope builds the whole scope tree, so only resolve bindings this rule tracks.
    const variable = shallow || store ? variableFor(specifier.local, state) : null
    if (!variable) {
      continue
    }
    state.hookNames.add(specifier.local.name)
    if (shallow) {
      state.shallowHooks.add(variable)
    } else {
      state.appStoreHooks.add(variable)
    }
  }
}

function isAppStoreCall(node, state) {
  return (
    node.callee.type === 'Identifier' &&
    state.hookNames.has(node.callee.name) &&
    state.appStoreHooks.has(variableFor(node.callee, state)) &&
    node.optional !== true
  )
}

function requireSelectorRule(sourceCode) {
  const state = createRuleState(sourceCode)
  return {
    ImportDeclaration(node) {
      recordImports(node, state)
    },
    CallExpression(node) {
      if (isAppStoreCall(node, state) && node.arguments.length === 0) {
        this.report({
          node,
          message:
            'Pass a selector to useAppStore so the component does not rerender for every store write.'
        })
      }
    }
  }
}

// Judge at Program:exit so selectors declared after call sites resolve.
function deferredSelectorRule(sourceCode, inspect) {
  const state = createRuleState(sourceCode)
  return {
    ImportDeclaration(node) {
      recordImports(node, state)
    },
    CallExpression(node) {
      if (isAppStoreCall(node, state)) {
        state.deferredCalls.push(node)
      }
    },
    'Program:exit'() {
      for (const node of state.deferredCalls) {
        const { selector: argument, shallow } = unwrapShallowSelector(node.arguments[0], state)
        const report = inspect({
          selector: resolveSelector(argument, state),
          shallow,
          state
        })
        if (report) {
          this.report(report)
        }
      }
    }
  }
}

function noIdentitySelectorRule(sourceCode) {
  return deferredSelectorRule(sourceCode, ({ selector }) =>
    isIdentitySelector(selector)
      ? {
          node: selector,
          message:
            'Select the smallest required fields instead of subscribing to the entire app store.'
        }
      : null
  )
}

function noFreshSelectorResultRule(sourceCode) {
  return deferredSelectorRule(sourceCode, ({ selector, shallow, state }) => {
    if (shallow || !selector) {
      return null
    }
    const freshResult = returnedExpressions(selector)
      .flatMap((expression) => expandThroughNamedHelper(expression, state))
      .find(isAllocatingExpression)
    return freshResult
      ? {
          node: freshResult,
          message:
            'This selector returns a fresh reference on every store write; select a stable field, cache the result, or use useShallow.'
        }
      : null
  })
}

// Host observations replace this map on every meaningful change (runtime-status.ts).
const HOT_STORE_FIELDS = new Set(['runtimeStatusByEnvironmentId'])

function selectorLocalConstant(variable, selector) {
  const definition = variable?.defs[0]
  const declaration = definition?.node
  if (definition?.type !== 'Variable' || declaration.parent.kind !== 'const') {
    return null
  }
  for (let parent = declaration.parent; parent; parent = parent.parent) {
    if (parent === selector) {
      return declaration
    }
  }
  return null
}

// Resolve only the selector parameter and its local const aliases, never a same-named outer value.
function selectorValue(expression, selector, state, seen = new Set()) {
  if (expression?.type === 'MemberExpression') {
    const field = propertyName(expression)
    return HOT_STORE_FIELDS.has(field) &&
      selectorValue(expression.object, selector, state, seen) === 'state'
      ? field
      : null
  }
  const variable = variableFor(expression, state)
  if (!variable || seen.has(variable)) {
    return null
  }
  seen.add(variable)
  const parameter = selector.params[0]
  if (parameter?.type === 'Identifier' && variableFor(parameter, state) === variable) {
    return 'state'
  }
  const declaration = selectorLocalConstant(variable, selector)
  const pattern = declaration?.id ?? parameter
  if (pattern?.type === 'ObjectPattern') {
    const property = pattern.properties.find(
      (entry) => entry.type === 'Property' && variable.identifiers.includes(entry.value)
    )
    const field = property && !property.computed ? identifierName(property.key) : null
    if (
      HOT_STORE_FIELDS.has(field) &&
      (pattern === parameter || selectorValue(declaration.init, selector, state, seen) === 'state')
    ) {
      return field
    }
  }
  return declaration?.id.type === 'Identifier'
    ? selectorValue(declaration.init, selector, state, seen)
    : null
}

function noWholeHotMapSelectorRule(sourceCode) {
  return deferredSelectorRule(sourceCode, ({ selector, state }) => {
    if (!selector) {
      return null
    }
    const result = returnedExpressions(selector).find((expression) =>
      HOT_STORE_FIELDS.has(selectorValue(expression, selector, state))
    )
    return result
      ? {
          node: result,
          message:
            'This whole host-status map changes for every host. Select the derived answer for your own host/item with a stable result (see paired-runtime-parking-capabilities.ts), or add a disable comment with a reason if this consumer needs every host.'
        }
      : null
  })
}

/** useShallow compares one level deep, so a fresh reference nested inside its result never matches. */
function nestedFreshValues(expression) {
  if (expression?.type === 'ObjectExpression') {
    return expression.properties
      .map((property) => (property.type === 'Property' ? property.value : null))
      .filter(Boolean)
  }
  if (expression?.type === 'ArrayExpression') {
    return expression.elements.filter(Boolean)
  }
  return []
}

function noNestedFreshUnderShallowRule(sourceCode) {
  return deferredSelectorRule(sourceCode, ({ selector, shallow, state }) => {
    if (!shallow || !selector) {
      return null
    }
    const nestedFresh = returnedExpressions(selector)
      .flatMap((expression) => expandThroughNamedHelper(expression, state))
      .flatMap(nestedFreshValues)
      .flatMap((expression) => expandThroughNamedHelper(expression, state))
      .find(isAllocatingExpression)
    return nestedFresh
      ? {
          node: nestedFresh,
          message:
            'useShallow compares only one level deep, so this nested fresh reference changes on every store write and defeats the memo; project the primitives the component actually renders.'
        }
      : null
  })
}

// Skip JS AST deserialization in files that cannot name a store hook.
const STORE_HOOK_TEXT = /use[A-Z][A-Za-z0-9]*Store/

function bindContext(createVisitors) {
  return (context) => {
    if (!STORE_HOOK_TEXT.test(context.sourceCode.text) && !context.sourceCode.text.includes('\\')) {
      return {}
    }
    if (
      createVisitors === noWholeHotMapSelectorRule &&
      /\.(?:test|spec)\.[^/\\]+$/.test(context.filename)
    ) {
      return {}
    }
    const visitors = createVisitors(context.sourceCode)
    for (const [nodeType, visit] of Object.entries(visitors)) {
      visitors[nodeType] = visit.bind(context)
    }
    return visitors
  }
}

export default {
  meta: { name: 'app-store-performance' },
  rules: {
    'require-selector': { create: bindContext(requireSelectorRule) },
    'no-identity-selector': { create: bindContext(noIdentitySelectorRule) },
    'no-fresh-selector-result': { create: bindContext(noFreshSelectorResultRule) },
    'no-whole-hot-map-selector': { create: bindContext(noWholeHotMapSelectorRule) },
    'no-nested-fresh-under-shallow': { create: bindContext(noNestedFreshUnderShallowRule) }
  }
}