eslint.config.mjs

import js from '@eslint/js'
import ts from 'typescript-eslint'
import prettier from 'eslint-config-prettier'

// The one restricted module, hoisted because it must be repeated in the renderer block
// below: ESLint replaces a rule's options wholesale rather than merging them, so a
// renderer-specific `no-restricted-imports` that listed only its own patterns would
// silently drop this and reopen the Electron boundary for the whole renderer.
const NO_ELECTRON = {
  name: 'electron',
  allowTypeImports: true,
  message:
    'Importing Electron here couples the agent path to the desktop runtime. Inject the ' +
    'capability from an Electron entry point instead (see the handler seams in ' +
    'approval.ts / ask-user.ts), or `import type` if you only need its types. If this ' +
    'file genuinely IS a desktop entry point, add it to the allow-list in ' +
    'eslint.config.mjs — deliberately, and visibly in review.',
}

// Hoisted for the same reason as NO_ELECTRON above: ESLint replaces a rule's array
// options wholesale rather than merging them, so the renderer-specific
// `no-restricted-syntax` block below must repeat this selector or it would silently
// reopen the `in`-with-a-dynamic-key hole for the whole renderer.
const NO_DYNAMIC_IN = {
  selector: "BinaryExpression[operator='in'][left.type!='Literal']",
  message:
    'A dynamic key with `in` also matches inherited members (toString, constructor, ' +
    '__proto__, and five more). Use Object.hasOwn(record, key) — or keyOf(record) from ' +
    "@copse/std when you want a type predicate. A literal key (`'kind' in value`) is " +
    'fine and is not restricted.',
}

export default ts.config(
  {
    ignores: [
      'dist/',
      'dist-test/',
      'dist-types/',
      'coverage/',
      'node_modules/',
      // Local dependency stores and nested review worktrees can contain complete
      // copies of the repository. The standalone `eslint .` shard must not walk them.
      '.pnpm-store/',
      '.pr-validation/',
      '.tmp/',
      // Generated benchmark outputs, private research scripts and downloaded model caches.
      // The maintained benchmark harnesses under benchmarks/ are linted separately below.
      'bench-results/',
      '.claude/**',
      'eslint.config.mjs',
      'eslint.hook.config.mjs',
      'wdio.conf.ts',
      'wdio.ci.conf.ts',
      'wdio.eval.conf.ts',
      'wdio.demo.conf.ts',
      // One-line side-effect import of the preload for the Tauri ws-bridge
      // bundle; in no tsconfig project (the preload typechecks under
      // tsconfig.node.json, this entry is browser-side). See scripts/build-tauri.mts.
      'src/sidecar/ws-bridge/entry.ts',
      'tests/e2e/**',
      'tests/demo/**',
      'tests/fixtures/git-changes-repo/**',
      // Bench-task fixture repos: code for the agent under eval to fix, not project code.
      'benchmarks/fixtures/**',
      'benchmarks/steer/fixtures/**',
      // Review-bench cases: the head trees carry the defects the reviewer is
      // measured on (an unused timer is one of them), so a linter must not "fix" them.
      'benchmarks/review/cases/**',
    ],
  },
  js.configs.recommended,
  ...ts.configs.strictTypeChecked,
  prettier,
  {
    // Adapter implementations must accept every input their shared contract
    // permits. Method signatures bypass strictFunctionTypes' parameter checks;
    // function properties retain them. Start with these three adapter seams
    // rather than changing unrelated interface and overload declarations (#1323).
    files: [
      'packages/hooks-dialects/src/dialect-adapter.ts',
      'src/main/services/github/backend/backend.ts',
      'src/main/services/workspace-fs/workspace-fs.ts',
    ],
    rules: {
      '@typescript-eslint/method-signature-style': ['error', 'property'],
    },
  },
  {
    // A stale `// eslint-disable` is as misleading as a missing one: it implies a
    // rule fires here when it no longer does. Fail the build on unused directives
    // so the inline-suppression inventory stays honest as the code changes.
    linterOptions: { reportUnusedDisableDirectives: 'error' },
  },
  {
    languageOptions: {
      parserOptions: { project: ['./tsconfig.node.json', './tsconfig.web.json'] },
    },
  },
  {
    rules: {
      '@typescript-eslint/no-unused-vars': [
        'error',
        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
      ],
      '@typescript-eslint/no-unnecessary-type-assertion': 'error',
      // Catch union members silently dropped by a `switch`. Switches that
      // intentionally lean on `default` to drop the rest (chunk/session-update
      // adapters, errno maps) stay valid via `considerDefaultExhaustiveForUnions`;
      // a switch with no `default` must still handle every member explicitly.
      '@typescript-eslint/switch-exhaustiveness-check': [
        'error',
        { considerDefaultExhaustiveForUnions: true },
      ],
      // Ban `{ ... } as T` object-literal casts: they silently bypass excess-property
      // checks, so a typo'd or stale field type-checks clean. Annotate the binding
      // (`const x: T = { ... }`) or use `satisfies T` instead. Other `as` casts stay
      // allowed for now — narrowing those further is tracked separately.
      '@typescript-eslint/consistent-type-assertions': [
        'error',
        { assertionStyle: 'as', objectLiteralTypeAssertions: 'never' },
      ],
      // #508 high-churn rules, enabled as errors but held to a shrink-only
      // baseline in `eslint-suppressions.json` (ESLint bulk suppressions). Today's
      // violations are recorded there and don't fail the build; any NEW violation
      // does. As sites are fixed, run `npm run lint:prune` to shrink the baseline —
      // it can only get smaller. See the "Type-safety & lint discipline" section
      // in AGENTS.md.
      '@typescript-eslint/no-unsafe-type-assertion': 'error',
      '@typescript-eslint/prefer-nullish-coalescing': 'error',
      '@typescript-eslint/no-this-alias': 'off',
      '@typescript-eslint/explicit-module-boundary-types': 'error',
      '@typescript-eslint/explicit-function-return-type': 'error',
      // `in` walks the prototype chain, so `key in RECORD` with a key that did not
      // come from a literal answers **true** for the eight members every object
      // literal inherits: toString, constructor, valueOf, hasOwnProperty,
      // __proto__, isPrototypeOf, propertyIsEnumerable, toLocaleString. A gate
      // written that way says "yes, that key is allowed" for all eight, and
      // whatever runs next reads an inherited function instead of the value it
      // expected. That is not hypothetical — it was the body of the
      // `settings:set` writability gate and of `plugins:setSetting`, which took
      // its key straight off the renderer and then wrote it into the pack's bag.
      //
      // Only a DYNAMIC key is restricted. `'filePath' in payload` is the
      // unrelated and entirely fine idiom for discriminating an object union,
      // and there are 248 of those; a blanket ban on `in` would bury the ten
      // that mattered. Tests are exempt below, because several of them use `in`
      // deliberately to assert the prototype behaviour this rule exists to stop.
      'no-restricted-syntax': ['error', NO_DYNAMIC_IN],
      'no-empty': ['error', { allowEmptyCatch: true }],
      'no-control-regex': 'off',
    },
  },
  {
    // Keep the agent path importable without Electron. `agent-path-electron-surface.test.ts`
    // already proves the product's agent construction runs under plain Node, but it does so
    // by walking the import graph from three named roots — so a file that is not yet
    // reachable can take a runtime Electron dependency freely, and only turns some later,
    // unrelated PR red once something imports it. This rule enforces the same boundary at
    // every file, and reports it where the mistake is made.
    //
    // Type-only imports stay allowed everywhere (`allowTypeImports`): TypeScript erases
    // them, so Node never resolves Electron, and several pure modules legitimately type
    // their injected handles as `BrowserWindow` / `IpcMain`.
    //
    // Only the bare `electron` module is restricted. `electron-updater` and
    // `electron-store` are separate packages and do not match a `paths` entry; bringing
    // them under the boundary is a follow-up, not a silent side effect of this rule.
    // `.mts` is listed alongside `.ts` because `src/shared` has two of them, and shared
    // code is exactly where an Electron import would do the most damage.
    files: ['src/**/*.ts', 'src/**/*.mts', 'packages/*/src/**/*.ts', 'packages/*/src/**/*.mts'],
    rules: {
      '@typescript-eslint/no-restricted-imports': [
        'error',
        {
          paths: [NO_ELECTRON],
        },
      ],
    },
  },
  {
    // Plan-usage credential discovery runs from the Settings IPC handler on the
    // Electron main thread. Keep file reads awaitable so a credential file cannot
    // block the renderer while the five-minute usage cache is cold. This block
    // follows the broad agent-path import rule because ESLint replaces rule
    // options instead of merging them.
    files: ['src/main/services/plan-usage-bridge.ts'],
    rules: {
      '@typescript-eslint/no-restricted-imports': [
        'error',
        {
          paths: [
            NO_ELECTRON,
            {
              name: 'node:fs',
              importNames: ['readFileSync'],
              message:
                'Settings plan-usage discovery runs on the main thread; use node:fs/promises readFile instead.',
            },
            {
              name: 'fs',
              importNames: ['readFileSync'],
              message:
                'Settings plan-usage discovery runs on the main thread; use node:fs/promises readFile instead.',
            },
          ],
        },
      ],
      'no-restricted-syntax': [
        'error',
        {
          selector: "BinaryExpression[operator='in'][left.type!='Literal']",
          message:
            'A dynamic key with `in` also matches inherited members (toString, constructor, ' +
            '__proto__, and five more). Use Object.hasOwn(record, key) — or keyOf(record) from ' +
            "@copse/std when you want a type predicate. A literal key (`'kind' in value`) is " +
            'fine and is not restricted.',
        },
        {
          selector:
            "CallExpression[callee.type='MemberExpression'][callee.property.name='readFileSync']",
          message:
            'Settings plan-usage discovery runs on the main thread; use node:fs/promises readFile instead.',
        },
      ],
    },
  },
  {
    // The renderer runs in a browser context: no Node builtins, ever. Nothing imports one
    // today, which is exactly why this is cheap to add — a rule with no violations costs
    // nothing and prevents the FIRST one, which is the only cheap moment to prevent it.
    // A `node:fs` import here fails at runtime rather than at build, so the current
    // guarantee is "nobody has tried yet".
    //
    // Repeating NO_ELECTRON is required, not redundant: ESLint replaces a rule's options
    // rather than merging them, so omitting it here would turn the Electron boundary off
    // across the whole renderer.
    //
    // The three direction rules that cannot be expressed as specifier globs
    // (renderer -> main, shared -> main/renderer, packages -> src) live in
    // `scripts/module-boundaries.test.ts`, which resolves the import and asks which zone
    // the file lands in. Relative specifiers vary by nesting depth, and
    // `src/renderer/main.ts` exists — so any glob loose enough to catch
    // `../../main/services/x.ts` also blocks the renderer importing its own entry point.
    //
    // Renderer TESTS are exempt, and have to be: they are component tests run by Node's
    // test runner over happy-dom (see tests/setup-dom.ts), so they import `node:test` and
    // `node:assert/strict` by construction — 314 such imports across 153 files today. The
    // boundary protects the SHIPPED renderer bundle, which contains no test file. They
    // still fall through to the block above, so the Electron ban continues to apply to
    // them; only the Node-builtin ban is lifted.
    files: ['src/renderer/**/*.ts', 'src/renderer/**/*.mts'],
    ignores: ['src/renderer/**/*.test.ts'],
    rules: {
      '@typescript-eslint/no-restricted-imports': [
        'error',
        {
          paths: [NO_ELECTRON],
          patterns: [
            {
              group: ['node:*'],
              allowTypeImports: true,
              message:
                'The renderer is a browser context and has no Node builtins at runtime. Reach the ' +
                'filesystem, processes, or the network through the preload bridge (`preload/api.d.ts`), ' +
                'or move the logic to src/shared if it is pure.',
            },
          ],
        },
      ],
      // #2497 — native `confirm()`/`alert()` render as a blocking OS-native dialog in
      // Electron, not the in-app UI the rest of the renderer uses (PR #1030). Route
      // through `showConfirmDialog` (src/renderer/views/confirm-dialog.ts) instead.
      // Repeating NO_DYNAMIC_IN is required, not redundant — see its definition above.
      'no-restricted-globals': [
        'error',
        {
          name: 'confirm',
          message:
            'Native confirm() renders as a blocking OS dialog, not the in-app one. Use ' +
            'showConfirmDialog from ./confirm-dialog.ts (or the relative path to it) instead.',
        },
        {
          name: 'alert',
          message:
            'Native alert() renders as a blocking OS dialog, not the in-app UI. Show the ' +
            'message in the view instead (an error line, a status line, or showConfirmDialog ' +
            'from ./confirm-dialog.ts).',
        },
      ],
      'no-restricted-syntax': [
        'error',
        NO_DYNAMIC_IN,
        {
          selector:
            "CallExpression[callee.type='MemberExpression'][callee.object.name=/^(window|globalThis)$/][callee.property.name=/^(confirm|alert)$/]",
          message:
            'Native window.confirm()/window.alert() render as a blocking OS dialog, not the ' +
            'in-app UI. Use showConfirmDialog from ./confirm-dialog.ts instead.',
        },
      ],
    },
  },
  {
    // The Electron surface: every file that may hold a runtime `electron` import. Kept as an
    // explicit list rather than a glob over `src/main/**` because the point of the rule is
    // that `src/main` is NOT the boundary — 18 of its ~400 files need Electron, and the rest
    // are a portable agent runtime that merely lives beside them.
    //
    // `windows/` and `ipc/` are wholesale: both directories exist to own the desktop shell
    // and IPC surface. `preload/` bridges the renderer and cannot work without it. The
    // six services below are the leaky ones — each is a desktop capability behind a seam
    // (auto-update, dialogs, tray/menu prompts, the browser panel, SSH IPC), and each is a
    // candidate for the `*-electron.ts` suffix convention if that is ever adopted.
    //
    // The renderer is deliberately absent: it reaches Electron only through the preload
    // bridge, and today imports it nowhere.
    files: [
      'src/preload/**/*.ts',
      'src/main/index.ts',
      'src/main/app-init.ts',
      'src/main/app-icon.ts',
      'src/main/windows/**/*.ts',
      'src/main/ipc/**/*.ts',
      'src/main/services/auto-update.ts',
      'src/main/services/close-confirm.ts',
      'src/main/services/update-prompt.ts',
      'src/main/services/user-alerts-electron.ts',
      'src/main/services/plugins/plugin-browser-panel.ts',
      'src/main/services/ssh-workspace/ssh-workspace-ipc.ts',
      // DEBUG BRANCH: patches `ipcMain.handle` to time every channel. It is by
      // definition part of the IPC surface — instrumenting IPC without importing
      // Electron is not a thing — so it belongs on this list rather than behind
      // an injected seam that would need threading through every caller.
      'src/main/services/diagnostics/perf-ipc.ts',
    ],
    rules: {
      '@typescript-eslint/no-restricted-imports': 'off',
    },
  },
  {
    files: [
      'src/**/*.test.ts',
      'packages/*/src/**/*.test.ts',
      'scripts/**/*.test.ts',
      'tests/**/*.ts',
    ],
    rules: {
      '@typescript-eslint/no-floating-promises': 'off',
      // Test doubles must stay `async` to match the real async interfaces they
      // stand in for (provider `stream`, tool `executeTool`, etc.) even with no
      // internal await; de-asyncing would break their type contract.
      '@typescript-eslint/require-await': 'off',
      '@typescript-eslint/no-explicit-any': 'off',
      // Tests build partial doubles as object literals cast to the real type
      // (a fake `Response`, a stub `HTMLElement`). That's the deliberate test
      // pattern, so the object-literal-cast ban only applies to production code.
      '@typescript-eslint/consistent-type-assertions': 'off',
      // Several tests reach for `key in record` precisely to demonstrate that it
      // accepts prototype keys — the behaviour the production rule forbids. A
      // test that cannot state the wrong answer cannot pin the right one.
      'no-restricted-syntax': 'off',
    },
  },
  {
    // Plain CommonJS scripts aren't part of the typed tsconfig projects, so
    // disable type-aware linting and provide Node CJS globals for them.
    files: ['**/*.cjs'],
    extends: [ts.configs.disableTypeChecked],
    languageOptions: {
      sourceType: 'commonjs',
      globals: {
        process: 'readonly',
        console: 'readonly',
        require: 'readonly',
        module: 'writable',
        exports: 'writable',
        __dirname: 'readonly',
        __filename: 'readonly',
        Buffer: 'readonly',
      },
    },
    rules: {
      // .cjs files are executed directly by node and can't carry TypeScript
      // return-type annotations, so this rule can't be satisfied here.
      '@typescript-eslint/explicit-function-return-type': 'off',
      // `require` is the only module syntax a .cjs file has; the ban exists to
      // keep it out of the TypeScript sources, which this block already excludes.
      '@typescript-eslint/no-require-imports': 'off',
    },
  },
  {
    // Standalone test fixtures that are spawned as real child processes (see
    // tests/fixtures/mock-acp-agent.mjs). They run as plain ESM under `node`,
    // not through the test bundler, so they carry no TS annotations and are not
    // part of the TS project graph.
    // `packages/*/bin/*.mjs` are the one-line executable shims a workspace
    // package's `bin` points at (`copse-review`): the same shape, for the same
    // reason.
    files: ['tests/fixtures/*.mjs', 'packages/*/bin/*.mjs'],
    extends: [ts.configs.disableTypeChecked],
    languageOptions: {
      sourceType: 'module',
      globals: {
        process: 'readonly',
        console: 'readonly',
        Buffer: 'readonly',
        ReadableStream: 'readonly',
        AbortController: 'readonly',
      },
    },
    rules: {
      '@typescript-eslint/explicit-function-return-type': 'off',
    },
  },
  {
    files: ['benchmarks/shell-scope/scripts/lib/**/*.mts'],
    languageOptions: {
      parserOptions: { project: ['./benchmarks/shell-scope/tsconfig.json'] },
    },
  },
  {
    // Reproducible research runners are native Node ESM, not TypeScript app code.
    // Keep ordinary JS linting; typed adapter libraries use the scoped project above.
    files: ['benchmarks/shell-scope/scripts/**/*.mjs'],
    extends: [ts.configs.disableTypeChecked],
    languageOptions: {
      sourceType: 'module',
      globals: {
        process: 'readonly',
        console: 'readonly',
        Buffer: 'readonly',
        URL: 'readonly',
        performance: 'readonly',
        TextDecoder: 'readonly',
        ReadableStream: 'readonly',
        WritableStream: 'readonly',
        setTimeout: 'readonly',
        clearTimeout: 'readonly',
        structuredClone: 'readonly',
      },
    },
    // TypeScript-only annotation requirements cannot be expressed in these .mjs files.
    rules: {
      '@typescript-eslint/explicit-function-return-type': 'off',
      '@typescript-eslint/explicit-module-boundary-types': 'off',
    },
  },
  {
    // Executable resources shipped inside built-in skills run directly under
    // Node and are copied as-is, so they are not part of a TypeScript project.
    files: ['assets/skills/**/*.mjs'],
    extends: [ts.configs.disableTypeChecked],
    languageOptions: {
      sourceType: 'module',
      globals: {
        process: 'readonly',
      },
    },
    rules: {
      '@typescript-eslint/explicit-function-return-type': 'off',
    },
  },
  {
    // Static ESM worker host copied to dist; not part of the TS project graph.
    files: ['src/renderer/monaco/esm-worker-host.js'],
    extends: [ts.configs.disableTypeChecked],
    languageOptions: {
      sourceType: 'module',
      globals: {
        URL: 'readonly',
        globalThis: 'readonly',
        importScripts: 'readonly',
      },
    },
  },
  {
    // Static-site scripts: plain browser JS served as-is, with no TS project to
    // type-check against. Demo sites are copied next to the browser build.
    files: [
      'site/**/*.js',
      'prototypes/**/*.js',
      'src/shared/demo-sites/**/*.js',
      'benchmarks/benchmark-explorer/**/*.js',
    ],
    extends: [ts.configs.disableTypeChecked],
    languageOptions: {
      sourceType: 'script',
      globals: {
        window: 'readonly',
        document: 'readonly',
        FormData: 'readonly',
        Blob: 'readonly',
        Intl: 'readonly',
        Map: 'readonly',
        Set: 'readonly',
        URL: 'readonly',
        URLSearchParams: 'readonly',
        fetch: 'readonly',
        addEventListener: 'readonly',
        getComputedStyle: 'readonly',
        Image: 'readonly',
        location: 'readonly',
        XMLSerializer: 'readonly',
      },
    },
    rules: {
      '@typescript-eslint/explicit-function-return-type': 'off',
      // Plain JS cannot annotate its exports; the rule would flag every ES-module prototype.
      '@typescript-eslint/explicit-module-boundary-types': 'off',
    },
  },
  {
    // Synchronous first-paint theme script copied to dist; not part of the TS project graph.
    files: ['src/renderer/theme-boot.js'],
    extends: [ts.configs.disableTypeChecked],
    languageOptions: {
      sourceType: 'script',
      globals: {
        window: 'readonly',
        document: 'readonly',
        URLSearchParams: 'readonly',
      },
    },
    rules: {
      '@typescript-eslint/explicit-function-return-type': 'off',
    },
  },
)