#!/usr/bin/env bun

/**

* Enforces the project's React Query (TanStack Query v5) conventions.

*

* Biome and `check-api-validation-contracts.ts` cover formatting and the

* raw-fetch / contract boundary. This script catches React-Query-specific

* anti-patterns that neither covers:

*

* 1. missing-stale-time — useQuery/useInfiniteQuery/useSuspenseQuery without an explicit `staleTime`

* 2. queryfn-no-signal — an inline `queryFn` that takes no args (cannot forward the AbortSignal)

* 3. inline-query-key — `queryKey: ['literal', ...]` instead of a colocated key factory

* 4. key-factory-no-root — a `*Keys` factory in hooks/queries/** without an `all` root key

* 5. key-fetch-arg-drift — an identifier the queryFn forwards into the fetch (e.g. `workspaceId`)

* that is absent from the queryKey, so distinct fetch args collide on one

* cache entry. Conservative: only bare camelCase identifiers (never the

* requestJson contract arg, PascalCase/SCREAMING constants, or signal/

* pageParam machinery) are checked, and only when both a queryKey and an

* inline-arrow queryFn with a recognizable call are present.

*

* Enforcement model (mirrors check-api-validation-contracts.ts):

* - STRICT ZONE (apps/sim/hooks/queries/**): zero tolerance — any violation fails.

* - Elsewhere under apps/sim/**: ratcheted against scripts/check-react-query-patterns.baseline.json

* (fails only when a category's count rises above the recorded baseline).

*

* Escape hatch: put `// rq-lint-allow: <reason>` on the line directly above the

* flagged construct (up to 3 preceding comment lines tolerated). The reason must

* be non-empty.

*

* Usage:

* bun run scripts/check-react-query-patterns.ts # report

* bun run scripts/check-react-query-patterns.ts --check # CI gate (strict zone + ratchet)

* bun run scripts/check-react-query-patterns.ts --update-baseline

*/

import { readdir, readFile, writeFile } from 'node:fs/promises'

import path from 'node:path'

const ROOT = path.resolve(import.meta.dir, '..')

const APP_DIR = path.join(ROOT, 'apps/sim')

const BASELINE_PATH = path.join(ROOT, 'scripts/check-react-query-patterns.baseline.json')

const SKIP_DIRS = new Set(['node_modules', '.next', '.turbo', 'coverage', 'dist', 'build'])

const STRICT_PREFIX = 'apps/sim/hooks/queries/'

const ALLOW = 'rq-lint-allow:'

type Category =

| 'missing-stale-time'

| 'queryfn-no-signal'

| 'inline-query-key'

| 'key-factory-no-root'

| 'key-fetch-arg-drift'

interface Violation {

file: string

line: number

category: Category

message: string

snippet: string

}

const SUGGESTION: Record<Category, string> = {

'missing-stale-time':

'add an explicit staleTime (default 0 is rarely correct); e.g. staleTime: 60 * 1000',

'queryfn-no-signal':

'destructure the AbortSignal: queryFn: ({ signal }) => fetchX(..., signal) and forward it',

'inline-query-key':

'use a colocated hierarchical key factory (entityKeys.list(id)) instead of an inline literal key',

'key-factory-no-root':

'every *Keys factory in hooks/queries/** must expose an `all` root key for prefix invalidation',

'key-fetch-arg-drift':

'every identifier the queryFn passes to fetch/requestJson must also appear in the queryKey — ' +

'otherwise distinct fetch args collide on one cache entry (cross-tenant/param cache collision)',

}

async function walk(dir: string, out: string[] = []): Promise<string[]> {

let entries

try {

entries = await readdir(dir, { withFileTypes: true })

} catch {

return out

}

for (const entry of entries) {

if (SKIP_DIRS.has(entry.name)) continue

const full = path.join(dir, entry.name)

if (entry.isDirectory()) await walk(full, out)

else if (/\.(ts|tsx)$/.test(entry.name) && !/\.(test|spec)\.(ts|tsx)$/.test(entry.name))

out.push(full)

}

return out

}

/** Returns the substring of `src` for the balanced bracket group starting at `open` (index of the opening bracket). */

function matchBalanced(src: string, open: number, openCh: string, closeCh: string): string {

let depth = 0

let inStr: string | null = null

for (let i = open; i < src.length; i++) {

const ch = src[i]

const prev = src[i - 1]

if (inStr) {

if (ch === inStr && prev !== '\\') inStr = null

continue

}

if (ch === '"' || ch === "'" || ch === '`') {

inStr = ch

continue

}

if (ch === openCh) depth++

else if (ch === closeCh) {

depth--

if (depth === 0) return src.slice(open, i + 1)

}

}

return src.slice(open)

}

function lineAt(content: string, index: number): number {

let line = 1

for (let i = 0; i < index && i < content.length; i++) if (content[i] === '\n') line++

return line

}

/** True if a `// rq-lint-allow: <reason>` annotation sits within the 3 lines above `line` (1-based). */

function hasAllow(lines: string[], line: number): boolean {

for (let i = line - 2; i >= 0 && i >= line - 5; i--) {

const text = lines[i]?.trim() ?? ''

if (text.includes(ALLOW)) {

const reason = text.slice(text.indexOf(ALLOW) + ALLOW.length).trim()

return reason.length > 0

}

if (text.length > 0 && !text.startsWith('//') && !text.startsWith('*')) break

}

return false

}

const QUERY_CALL = /\b(useQuery|useInfiniteQuery|useSuspenseQuery|useSuspenseInfiniteQuery)\s*\(/g

const QUERYFN_NOARG = /queryFn\s*:\s*(?:async\s+)?\(\s*\)\s*=>/

const QUERYFN_PRESENT = /queryFn\s*:/

const INLINE_KEY = /queryKey\s*:\s*\[\s*[`'"]/

const KEYS_FACTORY = /\b(?:export\s+)?const\s+\w*[kK]eys\s*[:=][^=]*?=?\s*\{/g

/**

* Identifiers that are part of the queryFn machinery (not fetch params) and

* must never be flagged as drift even though they appear in the call.

*/

const QUERYFN_NOISE = new Set([

'signal',

'pageParam',

'meta',

'queryKey',

'direction',

'client',

'true',

'false',

'null',

'undefined',

])

/**

* Extracts the value slice of `key: ...` from an options object, reading up to

* the property-terminating top-level comma. Nested brackets (arrays, calls, and

* arrow-function bodies including their own param parens) are skipped via depth

* tracking, so this correctly returns the whole `({ signal }) => fetchX(...)`

* arrow for `queryFn`, not just its parameter list.

*/

function extractOptionValue(obj: string, key: string): string | null {

const re = new RegExp(`\\b${key}\\s*:`, 'g')

const m = re.exec(obj)

if (!m) return null

let i = m.index + m[0].length

while (i < obj.length && /\s/.test(obj[i])) i++

let depth = 0

let inStr: string | null = null

let j = i

for (; j < obj.length; j++) {

const c = obj[j]

const prev = obj[j - 1]

if (inStr) {

if (c === inStr && prev !== '\\') inStr = null

continue

}

if (c === '"' || c === "'" || c === '`') {

inStr = c

continue

}

if (c === '(' || c === '[' || c === '{') depth++

else if (c === ')' || c === ']' || c === '}') {

if (depth === 0) break

depth--

} else if (c === ',' && depth === 0) break

}

return obj.slice(i, j)

}

/**

* "key/fetch-arg drift": an identifier the queryFn forwards into the fetch

* (the args of the first call expression inside the queryFn body) that does NOT

* textually appear in the queryKey. Conservative — only fires when both the

* queryKey and an inline-arrow queryFn with a recognizable call are present, and

* only for bare identifiers (optionally `x as T` / `x!`), never member access,

* literals, or queryFn machinery (signal/pageParam/etc.).

*/

function findKeyFetchArgDrift(obj: string): string[] {

const keyExpr = extractOptionValue(obj, 'queryKey')

const fnExpr = extractOptionValue(obj, 'queryFn')

if (!keyExpr || !fnExpr) return []

// Drop the arrow prefix (`async`, `(params) =>`, optional `{ return`) so the

// search begins at the queryFn body, then locate the first call expression and

// balance its argument list.

const bodyStart = /=>\s*(?:\{\s*(?:return\s+)?)?/.exec(fnExpr)

const body = bodyStart ? fnExpr.slice(bodyStart.index + bodyStart[0].length) : fnExpr

const call = /(?:await\s+)?([A-Za-z_$][\w$.]*)\s*\(/.exec(body)

if (!call) return []

const callee = call[1]

const openParen = call.index + call[0].length - 1

const argList = matchBalanced(body, openParen, '(', ')')

// Split top-level args.

const args: string[] = []

let depth = 0

let cur = ''

for (let i = 1; i < argList.length - 1; i++) {

const c = argList[i]

if (c === '(' || c === '[' || c === '{') depth++

else if (c === ')' || c === ']' || c === '}') depth--

if (c === ',' && depth === 0) {

args.push(cur)

cur = ''

} else cur += c

}

if (cur.trim()) args.push(cur)

// `requestJson(contract, ...)` / `ensureQueryData(contract, ...)` etc. take the

// contract constant as their first arg — that is module-level config, never a

// per-hook identifier, so drop it before checking.

const dropsFirstArg = /(?:^|\.)(requestJson|requestText|ensureQueryData|fetchQuery)$/.test(callee)

const checkArgs = dropsFirstArg ? args.slice(1) : args

const drifted: string[] = []

for (const raw of checkArgs) {

const id = raw

.trim()

.replace(/\s+as\s+[\w$.<>[\]| ]+$/, '')

.replace(/!+$/, '')

.trim()

// Only bare identifiers; skip member access, calls, literals, destructures, spreads.

if (!/^[A-Za-z_$][\w$]*$/.test(id)) continue

if (QUERYFN_NOISE.has(id)) continue

// Skip module-level constants (contracts/config), which are camelCase config

// ending in `Contract`, PascalCase, or SCREAMING_SNAKE — never hook params.

if (/Contract$/.test(id) || /^[A-Z]/.test(id) || /^[A-Z0-9_]+$/.test(id)) continue

// Present in the key (as a whole word) → no drift.

const inKey = new RegExp(`\\b${id}\\b`).test(keyExpr)

if (!inKey && !drifted.includes(id)) drifted.push(id)

}

return drifted

}

function scanFile(rel: string, content: string): Violation[] {

const lines = content.split('\n')

const violations: Violation[] = []

const add = (index: number, category: Category, snippet: string) => {

const line = lineAt(content, index)

if (hasAllow(lines, line)) return

violations.push({ file: rel, line, category, message: SUGGESTION[category], snippet })

}

// 1 & 2: query call objects — staleTime + queryFn signal

QUERY_CALL.lastIndex = 0

let m: RegExpExecArray | null = QUERY_CALL.exec(content)

for (; m !== null; m = QUERY_CALL.exec(content)) {

const parenStart = m.index + m[0].length - 1

const arg = matchBalanced(content, parenStart, '(', ')')

// Only inspect the literal options object form `useQuery({ ... })`.

const braceRel = arg.indexOf('{')

if (braceRel === -1) continue

const obj = matchBalanced(arg, braceRel, '{', '}')

// Accept both `staleTime: ...` and the shorthand `staleTime,`; skip objects that spread options (...opts).

if (!/\bstaleTime\b/.test(obj) && !/\.\.\.\w/.test(obj)) {

add(m.index, 'missing-stale-time', `${m[1]}({ ... }) without staleTime`)

}

if (QUERYFN_PRESENT.test(obj) && QUERYFN_NOARG.test(obj)) {

add(m.index, 'queryfn-no-signal', `${m[1]} queryFn takes no args`)

}

for (const id of findKeyFetchArgDrift(obj)) {

add(

m.index,

'key-fetch-arg-drift',

`${m[1]}: '${id}' passed to fetch but absent from queryKey`

)

}

}

// 3: inline query keys

for (let i = 0; i < lines.length; i++) {

if (INLINE_KEY.test(lines[i])) {

const line = i + 1

if (!hasAllow(lines, line)) {

violations.push({

file: rel,

line,

category: 'inline-query-key',

message: SUGGESTION['inline-query-key'],

snippet: lines[i].trim(),

})

}

}

}

// 4: key factory must have an `all` root (hooks/queries/** only, excluding util key files that compose others)

if (rel.startsWith(STRICT_PREFIX)) {

KEYS_FACTORY.lastIndex = 0

let k: RegExpExecArray | null = KEYS_FACTORY.exec(content)

for (; k !== null; k = KEYS_FACTORY.exec(content)) {

const braceIdx = content.indexOf('{', k.index)

if (braceIdx === -1) continue

const obj = matchBalanced(content, braceIdx, '{', '}')

if (!/\ball\s*:/.test(obj)) {

add(k.index, 'key-factory-no-root', 'key factory missing `all` root key')

}

}

}

return violations

}

interface Baseline {

generatedFrom: string

counts: Record<string, number>

}

async function loadBaseline(): Promise<Baseline> {

try {

return JSON.parse(await readFile(BASELINE_PATH, 'utf8'))

} catch {

return { generatedFrom: 'none', counts: {} }

}

}

async function main() {

const update = process.argv.includes('--update-baseline')

const check = process.argv.includes('--check')

const files = await walk(APP_DIR)

const all: Violation[] = []

for (const file of files) {

const rel = path.relative(ROOT, file)

const content = await readFile(file, 'utf8')

if (!/\buse(Query|InfiniteQuery|SuspenseQuery|Mutation)\b|[kK]eys\s*[:=]/.test(content))

continue

all.push(...scanFile(rel, content))

}

const strict = all.filter((v) => v.file.startsWith(STRICT_PREFIX))

const ratchet = all.filter((v) => !v.file.startsWith(STRICT_PREFIX))

const counts: Record<string, number> = {}

for (const v of ratchet) counts[v.category] = (counts[v.category] ?? 0) + 1

if (update) {

const baseline: Baseline = { generatedFrom: 'apps/sim (non-strict zone)', counts }

await writeFile(BASELINE_PATH, `${JSON.stringify(baseline, null, 2)}\n`)

console.log(`✓ Baseline written: ${JSON.stringify(counts)}`)

process.exit(0)

}

console.log(`React Query pattern audit — scanned ${files.length} files`)

console.log(` strict zone (${STRICT_PREFIX}**) violations: ${strict.length}`)

console.log(` ratchet zone violations: ${ratchet.length} ${JSON.stringify(counts)}`)

let failed = false

if (strict.length > 0) {

failed = true

console.error(`\n✗ ${strict.length} violation(s) in the strict zone (${STRICT_PREFIX}**):\n`)

for (const v of strict) {

console.error(` ${v.file}:${v.line} [${v.category}]`)

console.error(` ${v.snippet}`)

console.error(` → ${v.message}\n`)

}

}

if (!check && ratchet.length > 0) {

console.error(`\nRatchet-zone occurrences (not failing without --check):`)

for (const v of ratchet) {

console.error(` ${v.file}:${v.line} [${v.category}] ${v.snippet}`)

}

}

if (check) {

const baseline = await loadBaseline()

for (const [category, count] of Object.entries(counts)) {

const base = baseline.counts[category] ?? 0

if (count > base) {

failed = true

console.error(

`\n✗ ratchet regression: ${category} rose to ${count} (baseline ${base}). ` +

`Fix the new occurrence(s) or annotate with // ${ALLOW} <reason>.`

)

for (const v of ratchet.filter((x) => x.category === category)) {

console.error(` ${v.file}:${v.line} ${v.snippet}`)

}

}

}

}

if (failed) process.exit(1)

console.log('\n✓ React Query pattern audit passed.')

process.exit(0)

}

main()