feat: added multiple tsconfig union target derivation

- TypeScript config resolution and validation (`ts.readConfigFile`, file readability checks)
- Canonical normalization pipeline:
  - `path.resolve`
  - `Set` + `.sort()` for deterministic dedupe ordering
- Multi-tsconfig union target derivation
- ESLint target glob normalization:
  - extension-bearing pattern detection
  - extensionless expansion with supported extension set
- Include/exclude/forceInclude merge behavior across multiple tsconfigs
- Cross-tsconfig overlap heuristics for ignore filtering
- Parser project alignment in ESLint runtime:
  - `@typescript-eslint/parser` project list synchronized with runtime-derived tsconfig set
- Domain engine + ESLint domain detection alignment with runtime target derivation
- Jest regression testing with temp filesystem fixtures
- ESM/Jest mocking limitations (read-only exports / non-configurable properties)

Files and Code Sections:

- `src/config.ts` (modified)
  - Why important: central canonical tsconfig list normalization for all downstream consumers.
  - Key edits:
    - added tsconfig readability validation (not just exists)
    - dedupe + deterministic sort for tsconfigPaths and forceInclude
    - fallback root tsconfig only if readable
  - Key snippet:
    ```ts
    function isReadableTsconfigPath(tsconfigPath: string): boolean {
      let stats: fs.Stats;
      try {
        stats = fs.statSync(tsconfigPath);
      } catch {
        return false;
      }

      if (!stats.isFile()) {
        return false;
      }

      const readResult = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
      return readResult.error == null;
    }

    function sanitizeTsconfigPaths(rawValue: unknown, root: string): string[] {
      return dedupeAndSort(
        toStringArray(rawValue)
          .map((tsconfigPath) => path.resolve(root, tsconfigPath))
          .filter((tsconfigPath) => isReadableTsconfigPath(tsconfigPath)),
      );
    }
    ```

- `src/utils.ts` (modified heavily)
  - Why important: target derivation moved from single-tsconfig to full union; include/exclude/forceInclude correctness; parser project runtime alignment.
  - Key edits:
    - `buildPatterns` now accepts all tsconfig paths (not first entry)
    - include normalization preserves extension-bearing entries, expands only extensionless patterns
    - tsconfig-relative include/exclude rebased to cwd
    - cross-tsconfig exclude overlap handling + forceInclude ignore suppression
    - deterministic dedupe/sort for files and ignores
    - runtime `overrideConfig` injects parserOptions.project from same resolved config used for target derivation
  - Key snippets:
    ```ts
    function buildPatterns(
      tsconfigPaths: readonly string[],
      forceInclude: string[] = [],
      cwd = process.cwd(),
      forceIncludeBaseDir = cwd,
    ): { files: string[]; ignore: string[] } { ... }
    ```

    ```ts
    function hasExtensionOrGlobExtensionPattern(value: string): boolean {
      return /(^|\/)[^/]*\.[^/]*$/.test(value);
    }

    function expandExtensionlessPattern(value: string): string {
      const normalized = normalizeGlobValue(value).replace(/\/+$/, '');
      if (normalized.length === 0) return '';
      if (hasExtensionOrGlobExtensionPattern(normalized)) return normalized;
      if (!GLOB_META_PATTERN.test(normalized)) {
        return `${normalized}/**/*${ESLINT_TARGET_EXTENSION_GLOB}`;
      }
      if (normalized === '**') return `**/*${ESLINT_TARGET_EXTENSION_GLOB}`;
      if (normalized.endsWith('/**')) return `${normalized}/*${ESLINT_TARGET_EXTENSION_GLOB}`;
      return `${normalized}${ESLINT_TARGET_EXTENSION_GLOB}`;
    }
    ```

    ```ts
    const lintConfig = resolvedConfig ?? resolveLintConfig();
    const parserProjectOverride = {
      languageOptions: {
        parserOptions: {
          project: lintConfig.domains.eslint.tsconfigPaths,
        },
      },
    };

    const eslint = new ESLint({
      overrideConfigFile: configPath || defaultConfigPath,
      ...
      overrideConfig: parserProjectOverride,
    });
    ```

- `src/domains/eslint.ts` (modified)
  - Why important: ESLint domain detection now uses canonical multi-tsconfig union logic (same derivation family as run path).
  - Key edits:
    - new `resolveESLintDetectionPatterns` using `resolveLintConfig` + `utils.buildPatterns(...)`
    - default detection falls back to default roots only when no tsconfigs/files are derivable
  - Key snippet:
    ```ts
    function resolveESLintDetectionPatterns(
      eslintPatterns: readonly string[] | undefined,
    ): string[] {
      if (eslintPatterns != null && eslintPatterns.length > 0) {
        return [...eslintPatterns];
      }

      const resolvedConfig = resolveLintConfig();
      const { tsconfigPaths, forceInclude } = resolvedConfig.domains.eslint;
      if (tsconfigPaths.length === 0) return DEFAULT_ESLINT_SEARCH_ROOTS;

      const { files } = utils.buildPatterns(
        tsconfigPaths,
        forceInclude,
        process.cwd(),
        resolvedConfig.root,
      );
      if (files.length === 0) return DEFAULT_ESLINT_SEARCH_ROOTS;
      return files;
    }
    ```

- `src/configs/js.ts` (read, not modified)
  - Why important: confirmed parser project already sourced from `resolveLintConfig().domains.eslint.tsconfigPaths`; alignment then enforced at runtime via `src/utils.ts`.

- `tests/config.test.ts` (modified)
  - Why important: regression coverage for canonical normalization, deterministic sort, dedupe, missing/unreadable filtering.
  - Key changes:
    - switched from brittle mocking to real temp-file fixtures
    - added/updated tests asserting dedupe/sort and unreadable tsconfig filtering
  - Representative assertions:
    ```ts
    expect(resolved.domains.eslint.tsconfigPaths).toStrictEqual([
      path.resolve(repoRoot, 'workspace', 'packages/core', 'tsconfig.json'),
      path.resolve(repoRoot, 'workspace', 'tsconfig.json'),
    ]);
    ```

- `tests/domains/index.test.ts` (modified)
  - Why important: regression coverage for domain-level multi-tsconfig detection and buildPatterns behavior.
  - Added tests:
    - `eslint detection derives scope from canonical multi-tsconfig union`
    - `preserves extension-bearing include entries while expanding extensionless entries`
    - `exclude and forceInclude interactions are stable across multiple tsconfigs`
  - Representative assertion:
    ```ts
    expect(patterns.files).toContain('pkg-one/src/**/*.tsx');
    expect(patterns.files).toContain(
      'pkg-two/src/**/*.{js,mjs,cjs,jsx,ts,tsx,mts,cts,json}',
    );
    ```

- `tests/bin/lint.test.ts` (modified)
  - Why important: user-visible CLI stability behavior update.
  - Changes:
    - test for canonical lint script flags updated to `.resolves.toBeUndefined()` after alignment fix
    - added `default run tolerates missing configured tsconfig paths`
  - Representative snippet:
    ```ts
    await expect(
      main(['node', 'matrixai-lint', '--domain', 'eslint']),
    ).resolves.toBeUndefined();
    ```

- `plans/refactor/STATE.md` (modified)
  - Why important: milestone state/documentation update required by user.
  - Added section: `Implemented in full multi-tsconfig targeting alignment slice`, documenting guarantees and touched areas.

Author: CMCDragonkai

plans/refactor/STATE.md

@@ -5,6 +5,31 @@
 - First implementation slice for CLI execution semantics has been delivered.
 - The target architecture is described in [`PLAN.md`](PLAN.md).
 
+## Implemented in full multi-tsconfig targeting alignment slice
+
+- Completed canonical tsconfig normalization in [`src/config.ts`](../../src/config.ts):
+  - all configured `domains.eslint.tsconfigPaths` are resolved to absolute paths
+  - unreadable or missing tsconfig files are filtered out
+  - resulting tsconfig list is deduplicated and deterministically sorted
+  - fallback to root `tsconfig.json` remains when available and readable
+- Completed union-based ESLint target derivation in [`src/utils.ts`](../../src/utils.ts):
+  - target files are now derived from the union of all configured tsconfig includes
+  - excludes are merged with cross-tsconfig overlap handling
+  - `forceInclude` is merged on top and can suppress matching ignore entries
+  - file and ignore output is deduplicated and deterministically sorted
+- Completed include normalization correctness in [`src/utils.ts`](../../src/utils.ts):
+  - include entries that already carry an extension/glob extension are preserved as-is
+  - only extensionless include entries are expanded with supported ESLint extensions
+  - malformed glob synthesis paths from blanket suffixing are eliminated
+- Completed parser-project/target alignment across ESLint runtime paths:
+  - [`src/configs/js.ts`](../../src/configs/js.ts) continues to source parser project from resolved tsconfig list
+  - [`src/utils.ts`](../../src/utils.ts) now injects parser `project` override from the same resolved config used for target derivation
+  - [`src/domains/eslint.ts`](../../src/domains/eslint.ts) detection now derives default scope from the same multi-tsconfig union logic
+- Added regression coverage for multi-tsconfig alignment:
+  - config normalization and missing/unreadable filtering in [`tests/config.test.ts`](../../tests/config.test.ts)
+  - multi-tsconfig detection and include/exclude/forceInclude behaviors in [`tests/domains/index.test.ts`](../../tests/domains/index.test.ts)
+  - user-visible stability with missing configured tsconfig path in [`tests/bin/lint.test.ts`](../../tests/bin/lint.test.ts)
+
 ## Implemented in config-schema cleanup + API-boundary slice
 
 - Completed lint runtime config loading/normalization using a single explicit schema:

src/config.ts

@@ -6,6 +6,7 @@ import type {
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
+import ts from 'typescript';
 
 const MATRIXAI_LINT_CONFIG_FILENAME = 'matrixai-lint-config.json';
 
@@ -29,14 +30,40 @@ function stripLeadingDotSlash(value: string): string {
   return value.replace(/^\.\//, '');
 }
 
+function dedupeAndSort(values: readonly string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+function isReadableTsconfigPath(tsconfigPath: string): boolean {
+  let stats: fs.Stats;
+  try {
+    stats = fs.statSync(tsconfigPath);
+  } catch {
+    return false;
+  }
+
+  if (!stats.isFile()) {
+    return false;
+  }
+
+  const readResult = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+  return readResult.error == null;
+}
+
 function sanitizeTsconfigPaths(rawValue: unknown, root: string): string[] {
-  return toStringArray(rawValue)
-    .map((tsconfigPath) => path.resolve(root, tsconfigPath))
-    .filter((tsconfigPath) => fs.existsSync(tsconfigPath));
+  return dedupeAndSort(
+    toStringArray(rawValue)
+      .map((tsconfigPath) => path.resolve(root, tsconfigPath))
+      .filter((tsconfigPath) => isReadableTsconfigPath(tsconfigPath)),
+  );
 }
 
 function sanitizeForceInclude(rawValue: unknown): string[] {
-  return toStringArray(rawValue).map((glob) => stripLeadingDotSlash(glob));
+  return dedupeAndSort(
+    toStringArray(rawValue)
+      .map((glob) => stripLeadingDotSlash(glob))
+      .filter((glob) => glob.length > 0),
+  );
 }
 
 function normalizeLintConfig({
@@ -63,19 +90,21 @@ function normalizeLintConfig({
     ? rawDomains.eslint
     : ({} as Record<string, unknown>);
 
-  const tsconfigPaths = sanitizeTsconfigPaths(
+  let tsconfigPaths = sanitizeTsconfigPaths(
     rawEslintDomain.tsconfigPaths,
     resolvedRoot,
   );
   const forceInclude = sanitizeForceInclude(rawEslintDomain.forceInclude);
 
   if (tsconfigPaths.length === 0) {
     const rootTsconfigPath = path.join(resolvedRoot, 'tsconfig.json');
-    if (fs.existsSync(rootTsconfigPath)) {
+    if (isReadableTsconfigPath(rootTsconfigPath)) {
       tsconfigPaths.push(rootTsconfigPath);
     }
   }
 
+  tsconfigPaths = dedupeAndSort(tsconfigPaths);
+
   return {
     version: 2,
     root: resolvedRoot,

src/domains/eslint.ts

@@ -5,6 +5,7 @@ import {
   resolveSearchRootsFromPatterns,
 } from './files.js';
 import * as utils from '../utils.js';
+import { resolveLintConfig } from '../config.js';
 
 const ESLINT_FILE_EXTENSIONS = [
   '.js',
@@ -20,15 +21,39 @@ const ESLINT_FILE_EXTENSIONS = [
 
 const DEFAULT_ESLINT_SEARCH_ROOTS = ['./src', './scripts', './tests'];
 
+function resolveESLintDetectionPatterns(
+  eslintPatterns: readonly string[] | undefined,
+): string[] {
+  if (eslintPatterns != null && eslintPatterns.length > 0) {
+    return [...eslintPatterns];
+  }
+
+  const resolvedConfig = resolveLintConfig();
+  const { tsconfigPaths, forceInclude } = resolvedConfig.domains.eslint;
+
+  if (tsconfigPaths.length === 0) {
+    return DEFAULT_ESLINT_SEARCH_ROOTS;
+  }
+
+  const { files } = utils.buildPatterns(
+    tsconfigPaths,
+    forceInclude,
+    process.cwd(),
+    resolvedConfig.root,
+  );
+  if (files.length === 0) {
+    return DEFAULT_ESLINT_SEARCH_ROOTS;
+  }
+
+  return files;
+}
+
 function createESLintDomainPlugin(): LintDomainPlugin {
   return {
     domain: 'eslint',
     description: 'Lint JavaScript/TypeScript/JSON files with ESLint.',
     detect: ({ eslintPatterns }) => {
-      const patterns =
-        eslintPatterns != null && eslintPatterns.length > 0
-          ? eslintPatterns
-          : DEFAULT_ESLINT_SEARCH_ROOTS;
+      const patterns = resolveESLintDetectionPatterns(eslintPatterns);
       const searchRoots = resolveSearchRootsFromPatterns(patterns);
       const matchedFiles = collectFilesByExtensions(
         searchRoots,