chore(eslint): add ESLint toolchain and clean src to strict 0/0 (#1165)

* chore(eslint): add eslint toolchain and configs

* fix(eslint): resolve gradual-config errors (rules-of-hooks, no-empty, prefer-const, …)

* chore(eslint): clear unused vars in config, contexts, app and test

* chore(eslint): clear unused vars in api and music-network

* chore(eslint): clear unused vars in utils

* chore(eslint): clear unused vars in store

* chore(eslint): clear unused vars in cover and hooks

* chore(eslint): clear unused vars in components

* chore(eslint): clear unused vars in pages

* chore(eslint): remove explicit any in src

* chore(eslint): align react-hooks exhaustive-deps

* chore(eslint): zero gradual config on src

* chore(eslint): strict hook rules in store and utils

* chore(eslint): strict hook rules in hooks and cover

* chore(eslint): strict hook rules in components

* chore(eslint): strict hook rules in pages and contexts

* chore(eslint): document scripts ignore in eslint config

* chore(eslint): add lint script and zero strict findings

* chore(eslint): address review round 1 (gradual 0/0, per-site disable reasons)

* chore(eslint): tighten two set-state disable comments (review round 2 LOW)

* chore(nix): sync npmDepsHash with package-lock.json

* docs(changelog): add Under the Hood entry for ESLint setup (PR #1165)

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

src/components/settings/AddServerForm.tsx

@@ -96,6 +96,8 @@ export function AddServerForm({
 
   useEffect(() => {
     if (!initialInvite) return;
+    // React Compiler set-state-in-effect rule: local state synced with store/prop inputs when the effect’s dependencies change.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     setBlockPasswordReveal(true);
     setForm(f => ({
       ...f,

src/components/settings/AppearanceTab.tsx

@@ -154,7 +154,7 @@ export function AppearanceTab() {
                         <WindowButtonPreview
                           key={style}
                           style={style}
-                          label={t(`settings.windowButtons${style.charAt(0).toUpperCase() + style.slice(1)}` as any)}
+                          label={t(`settings.windowButtons${style.charAt(0).toUpperCase() + style.slice(1)}`)}
                           selected={auth.windowButtonStyle === style}
                           onClick={() => auth.setWindowButtonStyle(style)}
                         />
@@ -301,7 +301,7 @@ export function AppearanceTab() {
                 <SeekbarPreview
                   key={style}
                   style={style}
-                  label={t(`settings.seekbar${style.charAt(0).toUpperCase() + style.slice(1)}` as any)}
+                  label={t(`settings.seekbar${style.charAt(0).toUpperCase() + style.slice(1)}`)}
                   selected={auth.seekbarStyle === style}
                   onClick={() => auth.setSeekbarStyle(style)}
                 />

src/components/settings/ArtistLayoutCustomizer.tsx

@@ -42,9 +42,13 @@ export function ArtistLayoutCustomizer() {
   const [dropTarget, setDropTarget] = useState<ArtistDropTarget>(null);
   const dropTargetRef = useRef<ArtistDropTarget>(null);
   const sectionsRef = useRef(sections);
+  // React Compiler refs rule: ref kept in sync with the latest value for use in effects/handlers/cleanup; not render data.
+  // eslint-disable-next-line react-hooks/refs
   sectionsRef.current = sections;
 
   useEffect(() => {
+    // React Compiler set-state-in-effect rule: local state synced with store/prop inputs when the effect’s dependencies change.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     if (!isPsyDragging) { dropTargetRef.current = null; setDropTarget(null); }
   }, [isPsyDragging]);
 

src/components/settings/LyricsSourcesCustomizer.tsx

@@ -48,9 +48,13 @@ export function LyricsSourcesCustomizer() {
   const [dropTarget, setDropTarget] = useState<LyricsDropTarget>(null);
   const dropTargetRef = useRef<LyricsDropTarget>(null);
   const sourcesRef = useRef(lyricsSources);
+  // React Compiler refs rule: ref kept in sync with the latest value for use in effects/handlers/cleanup; not render data.
+  // eslint-disable-next-line react-hooks/refs
   sourcesRef.current = lyricsSources;
 
   useEffect(() => {
+    // React Compiler set-state-in-effect rule: local state synced with store/prop inputs when the effect’s dependencies change.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     if (!isPsyDragging) { dropTargetRef.current = null; setDropTarget(null); }
   }, [isPsyDragging]);
 

src/components/settings/LyricsTab.tsx

@@ -34,8 +34,8 @@ export function LyricsTab() {
               <div key={style}>
                 {i > 0 && <div className="settings-section-divider" />}
                 <SettingsToggle
-                  label={t(`settings.sidebarLyricsStyle${key}` as any)}
-                  desc={t(`settings.sidebarLyricsStyle${key}Desc` as any)}
+                  label={t(`settings.sidebarLyricsStyle${key}`)}
+                  desc={t(`settings.sidebarLyricsStyle${key}Desc`)}
                   checked={sidebarLyricsStyle === style}
                   onChange={c => setSidebarLyricsStyle(c ? style : other)}
                 />

src/components/settings/QueueToolbarCustomizer.tsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
-import { Blend, GripVertical, Infinity, ListMusic, MoveRight, Share2, Shuffle, Trash2, Waves } from 'lucide-react';
+import { Blend, GripVertical, Infinity as InfinityIcon, ListMusic, MoveRight, Share2, Shuffle, Trash2, Waves } from 'lucide-react';
 import { useDragDrop, useDragSource } from '../../contexts/DragDropContext';
 import { useQueueToolbarStore, QueueToolbarButtonId } from '../../store/queueToolbarStore';
 
@@ -15,7 +15,7 @@ const QUEUE_TOOLBAR_BUTTON_ICONS: Record<QueueToolbarButtonId, typeof Shuffle |
   gapless: MoveRight,
   crossfade: Waves,
   autodj: Blend,
-  infinite: Infinity,
+  infinite: InfinityIcon,
 };
 
 const QUEUE_TOOLBAR_LABEL_KEYS: Record<QueueToolbarButtonId, string> = {
@@ -56,9 +56,13 @@ export function QueueToolbarCustomizer() {
   const [dropTarget, setDropTarget] = useState<QueueToolbarDropTarget>(null);
   const dropTargetRef = useRef<QueueToolbarDropTarget>(null);
   const buttonsRef = useRef(buttons);
+  // React Compiler refs rule: ref kept in sync with the latest value for use in effects/handlers/cleanup; not render data.
+  // eslint-disable-next-line react-hooks/refs
   buttonsRef.current = buttons;
 
   useEffect(() => {
+    // React Compiler set-state-in-effect rule: local state synced with store/prop inputs when the effect’s dependencies change.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     if (!isPsyDragging) { dropTargetRef.current = null; setDropTarget(null); }
   }, [isPsyDragging]);
 

src/components/settings/ServersTab.tsx

@@ -82,6 +82,8 @@ export function ServersTab({
   const [serverDropTarget, setServerDropTarget] = useState<ServerDropTarget>(null);
   const serverDropTargetRef = useRef<ServerDropTarget>(null);
   const serversRef = useRef(auth.servers);
+  // React Compiler refs rule: ref kept in sync with the latest value for use in effects/handlers/cleanup; not render data.
+  // eslint-disable-next-line react-hooks/refs
   serversRef.current = auth.servers;
   const addServerInviteAnchorRef = useRef<HTMLDivElement>(null);
 
@@ -94,6 +96,8 @@ export function ServersTab({
   // ServersTab is already mounted (initial mount is handled via useState).
   useEffect(() => {
     if (initialInvite) {
+      // React Compiler set-state-in-effect rule: local state synced with store/prop inputs when the effect’s dependencies change.
+      // eslint-disable-next-line react-hooks/set-state-in-effect
       setPastedServerInvite(initialInvite);
       setShowAddForm(true);
     }
@@ -103,6 +107,8 @@ export function ServersTab({
   useEffect(() => {
     if (!psyDragState.isDragging) {
       serverDropTargetRef.current = null;
+      // React Compiler set-state-in-effect rule: local state synced with store/prop inputs when the effect’s dependencies change.
+      // eslint-disable-next-line react-hooks/set-state-in-effect
       setServerDropTarget(null);
     }
   }, [psyDragState.isDragging]);

src/components/settings/SidebarCustomizer.tsx

@@ -38,6 +38,8 @@ export function SidebarCustomizer() {
   const [dropTarget, setDropTarget] = useState<DropTarget>(null);
   const dropTargetRef = useRef<DropTarget>(null);
   const itemsRef = useRef(items);
+  // React Compiler refs rule: ref kept in sync with the latest value for use in effects/handlers/cleanup; not render data.
+  // eslint-disable-next-line react-hooks/refs
   itemsRef.current = items;
   const randomNavMode = useAuthStore(s => s.randomNavMode);
   const setRandomNavMode = useAuthStore(s => s.setRandomNavMode);
@@ -59,6 +61,8 @@ export function SidebarCustomizer() {
   const systemItems  = items.filter(cfg => ALL_NAV_ITEMS[cfg.id]?.section === 'system');
 
   useEffect(() => {
+    // React Compiler set-state-in-effect rule: local state synced with store/prop inputs when the effect’s dependencies change.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     if (!isPsyDragging) { dropTargetRef.current = null; setDropTarget(null); }
   }, [isPsyDragging]);
 

src/components/settings/ThemeStoreSection.tsx

@@ -91,6 +91,8 @@ export function ThemeStoreSection() {
   const thumbUrl = (rel: string) =>
     generatedAt ? `${assetUrl(rel)}?v=${encodeURIComponent(generatedAt)}` : assetUrl(rel);
 
+  // React Compiler set-state-in-effect rule: state set from an async result resolved in this effect.
+  // eslint-disable-next-line react-hooks/set-state-in-effect
   useEffect(() => { load(false); }, []);
 
   const installedMap = useMemo(() => {
@@ -123,6 +125,8 @@ export function ThemeStoreSection() {
 
   // A changed filter can shrink the result set below the current page; reset to
   // the first page whenever the query or mode filter changes.
+  // React Compiler set-state-in-effect rule: local state synced with store/prop inputs when the effect’s dependencies change.
+  // eslint-disable-next-line react-hooks/set-state-in-effect
   useEffect(() => { setPage(1); }, [query, mode, sortMode, animFilter]);
 
   const pageCount = Math.max(1, Math.ceil(filtered.length / PAGE_SIZE));

src/components/settings/UserForm.tsx

@@ -20,7 +20,7 @@ export interface UserFormState {
   libraryIds: number[];
 }
 
-export function initialUserFormState(u: NdUser | undefined, allLibraries: NdLibrary[]): UserFormState {
+function initialUserFormState(u: NdUser | undefined, allLibraries: NdLibrary[]): UserFormState {
   const defaultIds = allLibraries.map(l => l.id);
   return {
     userName: u?.userName ?? '',
@@ -61,11 +61,15 @@ export function UserForm({
   const isEdit = !!initial;
 
   useEffect(() => {
+    // React Compiler set-state-in-effect rule: local state synced with store/prop inputs when the effect’s dependencies change.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     setShowNewUserRequiredErrors(false);
   }, [initial?.id]);
 
   useEffect(() => {
     if (!isEdit && form.userName.trim() && form.name.trim() && form.password.trim()) {
+      // React Compiler set-state-in-effect rule: local state synced with store/prop inputs when the effect’s dependencies change.
+      // eslint-disable-next-line react-hooks/set-state-in-effect
       setShowNewUserRequiredErrors(false);
     }
   }, [isEdit, form.userName, form.name, form.password]);

src/components/settings/musicNetwork/MusicNetworkSection.tsx

@@ -32,6 +32,8 @@ export function MusicNetworkSection() {
 
   // Profile stats (scrobbles / member-since) for the enrichment primary.
   useEffect(() => {
+    // React Compiler set-state-in-effect rule: state set from an async result resolved in this effect.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
     if (!enrichmentPrimaryId) { setPrimaryProfile(null); return; }
     let cancelled = false;
     setPrimaryProfile(null);

src/components/settings/settingsSearch.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
+import type { TFunction } from 'i18next';
 import { matchScore } from './settingsTabs';
 import { searchSettings } from './settingsSearch';
 
@@ -31,17 +32,17 @@ describe('matchScore', () => {
 
 describe('searchSettings', () => {
   it('finds AudioMuse by product name', () => {
-    const hits = searchSettings('AudioMuse', 'library', t as any);
+    const hits = searchSettings('AudioMuse', 'library', t as unknown as TFunction);
     expect(hits.some(h => h.title.includes('AudioMuse'))).toBe(true);
   });
 
   it('finds global volume shortcuts', () => {
-    const hits = searchSettings('Volume', 'library', t as any);
+    const hits = searchSettings('Volume', 'library', t as unknown as TFunction);
     expect(hits.some(h => h.title === 'Volume up')).toBe(true);
     expect(hits.some(h => h.title === 'Volume down')).toBe(true);
   });
 
   it('returns nothing for nonsense queries', () => {
-    expect(searchSettings('aaaaaaa', 'library', t as any)).toEqual([]);
+    expect(searchSettings('aaaaaaa', 'library', t as unknown as TFunction)).toEqual([]);
   });
 });

src/components/settings/settingsSearch.ts

@@ -17,11 +17,11 @@ export function searchSettings(query: string, activeTab: Tab, t: TFunction): Set
   const hits: SettingsSearchHit[] = [];
 
   for (const entry of SETTINGS_INDEX) {
-    const title = t(entry.titleKey as any);
+    const title = t(entry.titleKey);
     const hay = entry.keywords ? `${title} ${entry.keywords}` : title;
     const score = matchScore(hay, q);
     if (score <= 0) continue;
-    const focusTitle = entry.focusTitleKey ? t(entry.focusTitleKey as any) : title;
+    const focusTitle = entry.focusTitleKey ? t(entry.focusTitleKey) : title;
     hits.push({ tab: entry.tab, title, focusTitle, score, key: entry.titleKey });
   }