improvement(audits): ban ES2023 array methods repo-wide, catch whole-state partialize, strip inline directive comments

Author: waleedlatif1

.claude/rules/sim-components.md

@@ -33,15 +33,15 @@ export function Component({ requiredProp, optionalProp = false }: ComponentProps
 When rendering or sorting a list of rows against a lookup collection (members, folders, tags), keep the per-row work O(1):
 
 - **Precompute a lookup `Map` once**, never `array.find(...)` per row. Build `const byId = useMemo(() => { const m = new Map<string, T>(); for (const x of items ?? []) m.set(x.id, x); return m }, [items])` and read `byId.get(id)` in the sort comparator, `.map(...)`, and cell builders. A `.find` inside a sort comparator is O(n²·log n) — the worst offender. Depend memos on the derived `Map`, not the raw array.
-- **Sort a copy with `[...array].sort(cmp)`**, never `toSorted` in client code — see `sim-react-performance.md` → "Never mutate a shared array in place".
+- **Sort a copy with `[...array].sort(cmp)`**, never `toSorted` (`check:utils` bans it repo-wide) — see `sim-react-performance.md` → "Never mutate a shared array in place".
 - **Partition in a single pass** — when splitting one collection into several (`fileIds`/`folderIds`), do one `for…of` pushing into each bucket and return `{ a, b }` from a single `useMemo`, not two memos that each `map→filter→map` the same source twice.
 
 ## react-doctor (`bunx react-doctor`) — apply the wins, skip the false positives
 
 react-doctor diagnostics are hypotheses, not verdicts — confirm against the code before acting, and preserve behavior. Known repo-specific false positives to NOT "fix":
 
 - `no-barrel-import` — barrel imports are the repo convention (see sim-imports.md, "Barrel Exports"). Keep them.
-- `js-tosorted-immutable` — won't-fix in `'use client'` code (see "List-render performance" above); apply it only in server-only modules.
+- `js-tosorted-immutable` — won't-fix anywhere; `check:utils` bans the ES2023 array methods repo-wide.
 - `rerender-state-only-in-handlers` / "state set but never rendered" — a false positive when the `useState` is consumed by a `useEffect`/`useLayoutEffect` dependency (the effect must re-run on change). Only convert to a ref when nothing reads the value reactively.
 - `no-render-in-render` — a helper *called inline* (`{renderRow()}`) is reconciled by position and does **not** remount, so extracting it to a component is usually pure churn and can regress behavior (prop-drilling many closures, focus/scroll loss on the inner `<input>`). Apply it only when the helper is genuinely a *component defined during render*, or when the move is mechanical (a stateless, ref-free helper whose closures become a small, explicit prop set).
 - `async-await-in-loop` on an upload/progress loop where sequential execution is intentional (per-item progress, server backpressure) — leave it.

.claude/rules/sim-react-performance.md

@@ -77,7 +77,7 @@ return items.sort(compare)
 return [...items].sort(compare)
 ```
 
-**Do NOT reach for `toSorted()` / `toReversed()` / `with()` / `toSpliced()` on client render paths.** They are ES2023 *runtime* methods — and a tsconfig `"lib": ["ES2023"]` only makes them **type-check**, it does not make them **run**. Next/SWC compiles syntax but does **not** polyfill prototype methods, and the default browserslist still includes browsers without them (`toSorted` landed in Safari 16 / iOS 16, so any device capped at iOS 15 throws `TypeError: x.toSorted is not a function` and crashes the page). The perf difference vs `[...arr].sort()` is negligible (both allocate one array), so the copy-then-sort form is the correct default everywhere client code runs. Only consider the immutable methods in Node-only code (server routes, scripts) on Node ≥20, where the runtime is known.
+**Do NOT use `toSorted()` / `toReversed()` / `with()` / `toSpliced()`.** They are ES2023 *runtime* methods — and a tsconfig `"lib": ["ES2023"]` only makes them **type-check**, it does not make them **run**. Next/SWC compiles syntax but does **not** polyfill prototype methods, and the default browserslist still includes browsers without them (`toSorted` landed in Safari 16 / iOS 16, so any device capped at iOS 15 throws `TypeError: x.toSorted is not a function` and crashes the page). The perf difference vs `[...arr].sort()` is negligible (both allocate one array), so the copy-then-sort form is used everywhere: whether a module reaches the browser is not visible from its path, and `check:utils` bans the methods repo-wide.
 
 ## Run independent awaits in parallel
 

.cursor/rules/sim-components.mdc

@@ -34,15 +34,15 @@ export function Component({ requiredProp, optionalProp = false }: ComponentProps
 When rendering or sorting a list of rows against a lookup collection (members, folders, tags), keep the per-row work O(1):
 
 - **Precompute a lookup `Map` once**, never `array.find(...)` per row. Build `const byId = useMemo(() => { const m = new Map<string, T>(); for (const x of items ?? []) m.set(x.id, x); return m }, [items])` and read `byId.get(id)` in the sort comparator, `.map(...)`, and cell builders. A `.find` inside a sort comparator is O(n²·log n) — the worst offender. Depend memos on the derived `Map`, not the raw array.
-- **Sort a copy with `[...array].sort(cmp)`**, never `toSorted` in client code — see `sim-react-performance.md` → "Never mutate a shared array in place".
+- **Sort a copy with `[...array].sort(cmp)`**, never `toSorted` (`check:utils` bans it repo-wide) — see `sim-react-performance.md` → "Never mutate a shared array in place".
 - **Partition in a single pass** — when splitting one collection into several (`fileIds`/`folderIds`), do one `for…of` pushing into each bucket and return `{ a, b }` from a single `useMemo`, not two memos that each `map→filter→map` the same source twice.
 
 ## react-doctor (`bunx react-doctor`) — apply the wins, skip the false positives
 
 react-doctor diagnostics are hypotheses, not verdicts — confirm against the code before acting, and preserve behavior. Known repo-specific false positives to NOT "fix":
 
 - `no-barrel-import` — barrel imports are the repo convention (see sim-imports.md, "Barrel Exports"). Keep them.
-- `js-tosorted-immutable` — won't-fix in `'use client'` code (see "List-render performance" above); apply it only in server-only modules.
+- `js-tosorted-immutable` — won't-fix anywhere; `check:utils` bans the ES2023 array methods repo-wide.
 - `rerender-state-only-in-handlers` / "state set but never rendered" — a false positive when the `useState` is consumed by a `useEffect`/`useLayoutEffect` dependency (the effect must re-run on change). Only convert to a ref when nothing reads the value reactively.
 - `no-render-in-render` — a helper *called inline* (`{renderRow()}`) is reconciled by position and does **not** remount, so extracting it to a component is usually pure churn and can regress behavior (prop-drilling many closures, focus/scroll loss on the inner `<input>`). Apply it only when the helper is genuinely a *component defined during render*, or when the move is mechanical (a stateless, ref-free helper whose closures become a small, explicit prop set).
 - `async-await-in-loop` on an upload/progress loop where sequential execution is intentional (per-item progress, server backpressure) — leave it.

.cursor/rules/sim-react-performance.mdc

@@ -80,7 +80,7 @@ return items.sort(compare)
 return [...items].sort(compare)
 ```
 
-**Do NOT reach for `toSorted()` / `toReversed()` / `with()` / `toSpliced()` on client render paths.** They are ES2023 *runtime* methods — and a tsconfig `"lib": ["ES2023"]` only makes them **type-check**, it does not make them **run**. Next/SWC compiles syntax but does **not** polyfill prototype methods, and the default browserslist still includes browsers without them (`toSorted` landed in Safari 16 / iOS 16, so any device capped at iOS 15 throws `TypeError: x.toSorted is not a function` and crashes the page). The perf difference vs `[...arr].sort()` is negligible (both allocate one array), so the copy-then-sort form is the correct default everywhere client code runs. Only consider the immutable methods in Node-only code (server routes, scripts) on Node ≥20, where the runtime is known.
+**Do NOT use `toSorted()` / `toReversed()` / `with()` / `toSpliced()`.** They are ES2023 *runtime* methods — and a tsconfig `"lib": ["ES2023"]` only makes them **type-check**, it does not make them **run**. Next/SWC compiles syntax but does **not** polyfill prototype methods, and the default browserslist still includes browsers without them (`toSorted` landed in Safari 16 / iOS 16, so any device capped at iOS 15 throws `TypeError: x.toSorted is not a function` and crashes the page). The perf difference vs `[...arr].sort()` is negligible (both allocate one array), so the copy-then-sort form is used everywhere: whether a module reaches the browser is not visible from its path, and `check:utils` bans the methods repo-wide.
 
 ## Run independent awaits in parallel
 

CLAUDE.md

@@ -89,7 +89,7 @@ The `'use client'` server boundary, the app/worker runtime env split, and featur
 - **Imports**: absolute (`@/...`) only, never relative. A folder with 3+ exports gets an `index.ts` barrel; never re-export from a non-barrel file. `import type` for type-only imports. Order and lazy-loading through barrels: `.claude/rules/sim-imports.md`.
 - **TypeScript**: no `any` and no non-null `!` (use precise types or `unknown` with guards; `check:explicit-any` ratchets both); no export nothing imports (`check:unused-exports`); a props interface for every component; `as const` for constant objects/arrays; explicit ref types (`useRef<HTMLDivElement>(null)`).
 - **Unused bindings** fail lint (biome `noUnusedVariables`, `noUnusedFunctionParameters`): delete the dead variable, import, or parameter and update callers; write `catch {}` when the error is unused. Prefix `_` only for a parameter that must hold its position because a later one is used. `const { a, ...rest } = obj` to omit keys is allowed. The rules carry no autofix, so `bun run lint` will not rename anything for you.
-- **Components**: `'use client'` only for hooks or browser APIs. Structure order, extraction thresholds, and list-render rules: `.claude/rules/sim-components.md`. Render-performance idioms (lazy-init refs, hoisting, `Map` pre-indexing, `[...arr].sort()` never `toSorted()` on client paths): `.claude/rules/sim-react-performance.md`. For effect/state/memo/callback anti-patterns use the `/you-might-not-need-*` skills and verify against the running UI.
+- **Components**: `'use client'` only for hooks or browser APIs. Structure order, extraction thresholds, and list-render rules: `.claude/rules/sim-components.md`. Render-performance idioms (lazy-init refs, hoisting, `Map` pre-indexing, `[...arr].sort()`, never `toSorted()`): `.claude/rules/sim-react-performance.md`. For effect/state/memo/callback anti-patterns use the `/you-might-not-need-*` skills and verify against the running UI.
 - **State ownership**: React Query owns server data — never `useState` + `fetch`; shareable client view-state (tabs, filters, search, pagination, selected id) lives in the URL via `nuqs`; Zustand owns global client state; `useState` owns UI-only state. Hooks: `.claude/rules/sim-hooks.md`. Stores (`devtools`, `persist` only with an explicit `partialize` whitelist, workflow value invariants): `.claude/rules/sim-stores.md`. URL state: `.claude/rules/sim-url-state.md`.
 - **Utils**: inline a helper with one consumer; create `utils.ts` when 2+ files share it — in `lib/` (app-wide) or `feature/utils/` (feature-scoped). Check `lib/` before writing a new one.
 - **Lists and menus** mirror the order the user already reads elsewhere (toolbar, settings nav), encoded in one exported order constant (resource menus share `RESOURCE_MENU_ORDER`, a product order that does not mirror the sidebar); a separator marks only a change in what the action acts on (typically one, before the destructive action): `.claude/rules/sim-list-ordering.md`.

scripts/check-utils-enforcement.ts

@@ -4,7 +4,8 @@
  *
  * Most patterns point at an `@sim/utils` helper (CLAUDE.md "Common utilities"). A few encode
  * render-path rules from `.claude/rules/sim-react-performance.md` and `sim-styling.md` that no
- * linter covers: ES2023 array methods that Safari 15 lacks, `useRef(new X())` allocating on
+ * linter covers: ES2023 array methods that Safari 15 lacks (banned everywhere, since whether a
+ * module reaches the browser is not visible from its path and a copy-then-sort costs the same), `useRef(new X())` allocating on
  * every render, and `h-N w-N` where `size-N` is the convention.
  *
  * Biome's noRestrictedImports covers the import-based bans it lists — today `nanoid` and
@@ -18,7 +19,6 @@
  */
 import { readdir, readFile } from 'node:fs/promises'
 import path from 'node:path'
-import { leadingDirective } from './source-kind'
 
 const ROOT = path.resolve(import.meta.dir, '..')
 
@@ -43,25 +43,6 @@ const ALLOWLISTED_FILES = new Set([
   'packages/testing/src/factories/id.ts',
 ])
 
-/** App Router files Next only ever evaluates on the server, plus `*.server.ts` modules. */
-const SERVER_ONLY_FILE =
-  /\/(?:route|sitemap|robots|manifest)\.[jt]sx?$|\/(?:opengraph-image|twitter-image|icon|apple-icon)\.[^/]+$|\.server\.[jt]sx?$/
-
-/**
- * Files that ship to the browser: client directories plus any `'use client'` module. Server-only
- * code (route handlers, metadata routes, tests) may use Node 20+ runtime methods freely.
- */
-function isClientRenderPath(rel: string, content: string): boolean {
-  if (/\.(test|spec)\.[cm]?[jt]sx?$/.test(rel) || /\/app\/api\//.test(rel)) return false
-  if (SERVER_ONLY_FILE.test(rel)) return false
-  return (
-    /^apps\/sim\/(app|components|hooks|stores)\//.test(rel) ||
-    /^apps\/docs\/(app|components)\//.test(rel) ||
-    /^packages\/(emcn|workflow-renderer)\/src\//.test(rel) ||
-    leadingDirective(content) === 'use client'
-  )
-}
-
 /** `s.slice(0, n)` plus a suffix, by `+` or in a template literal; `\1` is `s` and `\2` is `n`. */
 const TRUNCATED = String.raw`(?:\`\$\{\1\.(?:slice|substring)\(\s*0\s*,\s*\2\s*\)\}[^\`$]*\`|\1\.(?:slice|substring)\(\s*0\s*,\s*\2\s*\)\s*\+\s*(?:'[^']*'|"[^"]*"|\w+))`
 /** Literal gate for both truncate patterns, whose backreferences are slow over every file. */
@@ -75,7 +56,6 @@ const BANNED_PATTERNS: Array<{
   description: string
   suggestion: string
   /** Restricts the pattern to matching files; unrestricted patterns apply everywhere. */
-  appliesTo?: (rel: string, content: string) => boolean
   /** Cheap literal test that skips the pattern on files that cannot match; memoized per file. */
   prefilter?: RegExp
 }> = [
@@ -167,9 +147,9 @@ const BANNED_PATTERNS: Array<{
   // Render-path rules (.claude/rules/sim-react-performance.md, sim-styling.md)
   {
     pattern: /\.(?:toSorted|toReversed|toSpliced)\s*\(|\.with\(\s*-?\d+\s*,/g,
-    description: 'ES2023 array method in browser code (throws on Safari/iOS 15)',
+    description:
+      'ES2023 array method (throws on Safari/iOS 15 wherever the module reaches the browser)',
     suggestion: 'a copy you then mutate: [...arr].sort(), [...arr].reverse(), [...arr].splice()',
-    appliesTo: isClientRenderPath,
   },
   {
     pattern: /\buseRef(?:<(?:[^<>]|<[^<>]*>)*>)?\(\s*new\s+[A-Z]\w*/g,
@@ -288,8 +268,7 @@ async function main() {
     }> = []
 
     const prefilterHits = new Map<RegExp, boolean>()
-    for (const { pattern, description, suggestion, appliesTo, prefilter } of BANNED_PATTERNS) {
-      if (appliesTo && !appliesTo(rel, content)) continue
+    for (const { pattern, description, suggestion, prefilter } of BANNED_PATTERNS) {
       if (prefilter) {
         let hit = prefilterHits.get(prefilter)
         if (hit === undefined) {

scripts/check-zustand-v5-selectors.ts

@@ -317,9 +317,11 @@ function auditPersist(file: string, source: string): Violation[] {
     if (closeParenIndex === -1) continue
     const call = source.slice(openParenIndex + 1, closeParenIndex)
     const hasPartialize = /\bpartialize\b/.test(call)
-    const spreadsState = /\bpartialize\s*:\s*\(?\s*(\w+)[^)]*\)?\s*=>\s*\(\s*\{\s*\.\.\.\1\b/.test(
-      call
-    )
+    /** `(s) => s`, `(s) => ({ ...s })`, or a block body returning either: the whole state persists. */
+    const spreadsState =
+      /\bpartialize\s*:\s*\(?\s*(\w+)[^)]*\)?\s*=>\s*(?:\1\b(?!\s*[.[])|\(\s*\{\s*\.\.\.\1\b|\{[^}]*\breturn\s+(?:\1\b(?!\s*[.[])|\{\s*\.\.\.\1\b))/.test(
+        call
+      )
     if (hasPartialize && !spreadsState) continue
     violations.push({
       file,

scripts/source-kind.ts

@@ -2,13 +2,13 @@
 const DIRECTIVE_STATEMENT = /^(['"])(use [a-z-]+)\1\s*;?$/
 
 /**
- * The directive a single source line states, e.g. `use client`, or null. A note may follow the
- * directive on the same line, so a trailing `//` or `/* *\/` comment comes off before matching.
+ * The directive a single source line states, e.g. `use client`, or null. Notes may sit on the same
+ * line, so `//` and inline `/* *\/` comments come off before matching.
  */
 export function directiveOn(line: string): string | null {
   const statement = line
-    .trim()
-    .replace(/(?:\/\/.*|\/\*.*?\*\/)\s*$/, '')
+    .replace(/\/\*.*?\*\//g, '')
+    .replace(/\/\/.*$/, '')
     .trim()
   return DIRECTIVE_STATEMENT.exec(statement)?.[2] ?? null
 }