structure.ts

import path from 'node:path';
import { getBuildMeta, getNodeId, setBuildMeta, testFilterSQL } from '../db/index.js';
import { cachedStmt } from '../db/repository/cached-stmt.js';
import { debug } from '../infrastructure/logger.js';
import { getOrCreateChunkStmt } from '../shared/chunked-stmt-cache.js';
import { getAncestorDirs, normalizePath } from '../shared/constants.js';
import type {
  BetterSqlite3Database,
  SqliteStatement as DbSqliteStatement,
  StmtCache,
} from '../types.js';

// isBarrelProdReachable's two queries are identical text on every call (the
// interpolated test-file filter is a fixed set of LIKE patterns keyed only
// by column name) — cache them per-db so repeated calls (1-3 barrels per
// incremental build) skip re-preparing the same statement. Mirrors
// `prepare_cached` in the Rust `is_barrel_prod_reachable`.
const _barrelDirectStmt: StmtCache<{ reachable: number }> = new WeakMap();
const _barrelBackwardStmt: StmtCache<{ reachable: number }> = new WeakMap();

// ─── Build-time helpers ───────────────────────────────────────────────

interface NodeIdStmt {
  get(name: string, kind: string, file: string, line: number): { id: number } | undefined;
}

interface FileSymbolData {
  definitions: { name: string; kind: string; line: number }[];
  imports: unknown[];
  exports: unknown[];
  calls?: unknown[];
}

function cleanupPreviousData(
  db: BetterSqlite3Database,
  getNodeIdStmt: NodeIdStmt,
  isIncremental: boolean,
  changedFiles: string[] | null,
): void {
  if (isIncremental) {
    const affectedDirs = getAncestorDirs(changedFiles ?? []);
    const deleteContainsForDir = db.prepare(
      "DELETE FROM edges WHERE kind = 'contains' AND source_id IN (SELECT id FROM nodes WHERE name = ? AND kind = 'directory')",
    );
    const deleteMetricForNode = db.prepare('DELETE FROM node_metrics WHERE node_id = ?');
    db.transaction(() => {
      for (const dir of affectedDirs) {
        deleteContainsForDir.run(dir);
      }
      for (const f of changedFiles ?? []) {
        const fileRow = getNodeIdStmt.get(f, 'file', f, 0);
        if (fileRow) deleteMetricForNode.run(fileRow.id);
      }
      for (const dir of affectedDirs) {
        const dirRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
        if (dirRow) deleteMetricForNode.run(dirRow.id);
      }
    })();
  } else {
    db.exec(`
      DELETE FROM edges WHERE kind = 'contains'
        AND source_id IN (SELECT id FROM nodes WHERE kind = 'directory');
      DELETE FROM node_metrics;
      DELETE FROM nodes WHERE kind = 'directory';
    `);
  }
}

function collectAllDirectories(
  directories: Set<string> | Iterable<string>,
  fileSymbols: Map<string, FileSymbolData>,
): Set<string> {
  const allDirs = new Set<string>();
  for (const dir of directories) {
    let d = dir;
    while (d && d !== '.') {
      allDirs.add(d);
      d = normalizePath(path.dirname(d));
    }
  }
  for (const relPath of fileSymbols.keys()) {
    let d = normalizePath(path.dirname(relPath));
    while (d && d !== '.') {
      allDirs.add(d);
      d = normalizePath(path.dirname(d));
    }
  }
  return allDirs;
}

interface SqliteStatement {
  run(...params: unknown[]): unknown;
}

/** Insert file→parent-directory contains edges (incremental-aware). */
function insertFileToParentEdges(
  insertEdge: SqliteStatement,
  getNodeIdStmt: NodeIdStmt,
  fileSymbols: Map<string, FileSymbolData>,
  affectedDirs: Set<string> | null,
): void {
  for (const relPath of fileSymbols.keys()) {
    const dir = normalizePath(path.dirname(relPath));
    if (!dir || dir === '.') continue;
    if (affectedDirs && !affectedDirs.has(dir)) continue;
    const dirRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
    const fileRow = getNodeIdStmt.get(relPath, 'file', relPath, 0);
    if (dirRow && fileRow) {
      insertEdge.run(dirRow.id, fileRow.id, 'contains', 1.0, 0);
    }
  }
}

/** Insert child-directory→parent-directory contains edges (incremental-aware). */
function insertDirToParentEdges(
  insertEdge: SqliteStatement,
  getNodeIdStmt: NodeIdStmt,
  allDirs: Set<string>,
  affectedDirs: Set<string> | null,
): void {
  for (const dir of allDirs) {
    const parent = normalizePath(path.dirname(dir));
    if (!parent || parent === '.' || parent === dir) continue;
    if (affectedDirs && !affectedDirs.has(parent)) continue;
    const parentRow = getNodeIdStmt.get(parent, 'directory', parent, 0);
    const childRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
    if (parentRow && childRow) {
      insertEdge.run(parentRow.id, childRow.id, 'contains', 1.0, 0);
    }
  }
}

function insertContainsEdges(
  db: BetterSqlite3Database,
  insertEdge: SqliteStatement,
  getNodeIdStmt: NodeIdStmt,
  fileSymbols: Map<string, FileSymbolData>,
  allDirs: Set<string>,
  changedFiles: string[] | null,
): void {
  const isIncremental = changedFiles != null && changedFiles.length > 0;
  const affectedDirs = isIncremental ? getAncestorDirs(changedFiles ?? []) : null;

  db.transaction(() => {
    insertFileToParentEdges(insertEdge, getNodeIdStmt, fileSymbols, affectedDirs);
    insertDirToParentEdges(insertEdge, getNodeIdStmt, allDirs, affectedDirs);
  })();
}

interface ImportEdge {
  source_file: string;
  target_file: string;
}

function computeImportEdgeMaps(db: BetterSqlite3Database): {
  fanInMap: Map<string, number>;
  fanOutMap: Map<string, number>;
  importEdges: ImportEdge[];
} {
  const fanInMap = new Map<string, number>();
  const fanOutMap = new Map<string, number>();
  const importEdges = db
    .prepare(`
      SELECT n1.file AS source_file, n2.file AS target_file
      FROM edges e
      JOIN nodes n1 ON e.source_id = n1.id
      JOIN nodes n2 ON e.target_id = n2.id
      WHERE e.kind IN ('imports', 'imports-type')
        AND n1.file != n2.file
        AND n2.kind = 'file'
    `)
    .all() as ImportEdge[];

  for (const { source_file, target_file } of importEdges) {
    fanOutMap.set(source_file, (fanOutMap.get(source_file) || 0) + 1);
    fanInMap.set(target_file, (fanInMap.get(target_file) || 0) + 1);
  }
  return { fanInMap, fanOutMap, importEdges };
}

function computeFileMetrics(
  db: BetterSqlite3Database,
  upsertMetric: SqliteStatement,
  getNodeIdStmt: NodeIdStmt,
  fileSymbols: Map<string, FileSymbolData>,
  lineCountMap: Map<string, number>,
  fanInMap: Map<string, number>,
  fanOutMap: Map<string, number>,
): void {
  db.transaction(() => {
    // Batch-load import counts per file (distinct imported files,
    // matching the fast-path semantics in updateChangedFileMetrics).
    // Runs inside the transaction for parity with the Rust path.
    const importCountMap = new Map<string, number>();
    for (const row of db
      .prepare(
        `SELECT n1.file AS src, COUNT(DISTINCT n2.file) AS cnt FROM edges e
         JOIN nodes n1 ON e.source_id = n1.id
         JOIN nodes n2 ON e.target_id = n2.id
         WHERE e.kind = 'imports'
         GROUP BY n1.file`,
      )
      .all() as { src: string; cnt: number }[]) {
      importCountMap.set(row.src, row.cnt);
    }

    for (const [relPath, symbols] of fileSymbols) {
      const fileRow = getNodeIdStmt.get(relPath, 'file', relPath, 0);
      if (!fileRow) continue;

      const lineCount = lineCountMap.get(relPath) || 0;
      const seen = new Set<string>();
      let symbolCount = 0;
      for (const d of symbols.definitions) {
        const key = `${d.name}|${d.kind}|${d.line}`;
        if (!seen.has(key)) {
          seen.add(key);
          symbolCount++;
        }
      }
      const importCount = importCountMap.get(relPath) || 0;
      const exportCount = symbols.exports.length;
      const fanIn = fanInMap.get(relPath) || 0;
      const fanOut = fanOutMap.get(relPath) || 0;

      upsertMetric.run(
        fileRow.id,
        lineCount,
        symbolCount,
        importCount,
        exportCount,
        fanIn,
        fanOut,
        null,
        null,
      );
    }
  })();
}

/** Map each directory to the files it transitively contains. */
function buildDirFilesMap(
  allDirs: Set<string>,
  fileSymbols: Map<string, FileSymbolData>,
): Map<string, string[]> {
  const dirFiles = new Map<string, string[]>();
  for (const dir of allDirs) {
    dirFiles.set(dir, []);
  }
  for (const relPath of fileSymbols.keys()) {
    let d = normalizePath(path.dirname(relPath));
    while (d && d !== '.') {
      if (dirFiles.has(d)) {
        dirFiles.get(d)?.push(relPath);
      }
      d = normalizePath(path.dirname(d));
    }
  }
  return dirFiles;
}

/** Build reverse map: file -> set of ancestor directories. */
function buildFileToAncestorDirs(dirFiles: Map<string, string[]>): Map<string, Set<string>> {
  const fileToAncestorDirs = new Map<string, Set<string>>();
  for (const [dir, files] of dirFiles) {
    for (const f of files) {
      if (!fileToAncestorDirs.has(f)) fileToAncestorDirs.set(f, new Set());
      fileToAncestorDirs.get(f)?.add(dir);
    }
  }
  return fileToAncestorDirs;
}

/** Initialise a zero-count map for all known directories. */
function initDirEdgeCounts(
  allDirs: Set<string>,
): Map<string, { intra: number; fanIn: number; fanOut: number }> {
  const m = new Map<string, { intra: number; fanIn: number; fanOut: number }>();
  for (const dir of allDirs) m.set(dir, { intra: 0, fanIn: 0, fanOut: 0 });
  return m;
}

/** Accumulate source-side (intra / fanOut) counts for one import edge. */
function accumulateSrcDirCounts(
  srcDirs: Set<string>,
  tgtDirs: Set<string> | undefined,
  dirEdgeCounts: Map<string, { intra: number; fanIn: number; fanOut: number }>,
): void {
  for (const dir of srcDirs) {
    const counts = dirEdgeCounts.get(dir);
    if (!counts) continue;
    if (tgtDirs?.has(dir)) {
      counts.intra++;
    } else {
      counts.fanOut++;
    }
  }
}

/** Accumulate target-side (fanIn) counts for one import edge. */
function accumulateTgtDirCounts(
  tgtDirs: Set<string>,
  srcDirs: Set<string> | undefined,
  dirEdgeCounts: Map<string, { intra: number; fanIn: number; fanOut: number }>,
): void {
  for (const dir of tgtDirs) {
    if (srcDirs?.has(dir)) continue;
    const counts = dirEdgeCounts.get(dir);
    if (!counts) continue;
    counts.fanIn++;
  }
}

/** Count intra-directory, fan-in, and fan-out edges per directory. */
function countDirectoryEdges(
  allDirs: Set<string>,
  importEdges: ImportEdge[],
  fileToAncestorDirs: Map<string, Set<string>>,
): Map<string, { intra: number; fanIn: number; fanOut: number }> {
  const dirEdgeCounts = initDirEdgeCounts(allDirs);
  for (const { source_file, target_file } of importEdges) {
    const srcDirs = fileToAncestorDirs.get(source_file);
    const tgtDirs = fileToAncestorDirs.get(target_file);
    if (!srcDirs && !tgtDirs) continue;
    if (srcDirs) accumulateSrcDirCounts(srcDirs, tgtDirs, dirEdgeCounts);
    if (tgtDirs) accumulateTgtDirCounts(tgtDirs, srcDirs, dirEdgeCounts);
  }
  return dirEdgeCounts;
}

/** Count unique symbols in a list of files. */
function countSymbolsInFiles(files: string[], fileSymbols: Map<string, FileSymbolData>): number {
  let symbolCount = 0;
  for (const f of files) {
    const sym = fileSymbols.get(f);
    if (sym) {
      const seen = new Set<string>();
      for (const d of sym.definitions) {
        const key = `${d.name}|${d.kind}|${d.line}`;
        if (!seen.has(key)) {
          seen.add(key);
          symbolCount++;
        }
      }
    }
  }
  return symbolCount;
}

function computeDirectoryMetrics(
  db: BetterSqlite3Database,
  upsertMetric: SqliteStatement,
  getNodeIdStmt: NodeIdStmt,
  fileSymbols: Map<string, FileSymbolData>,
  allDirs: Set<string>,
  importEdges: ImportEdge[],
): void {
  const dirFiles = buildDirFilesMap(allDirs, fileSymbols);
  const fileToAncestorDirs = buildFileToAncestorDirs(dirFiles);
  const dirEdgeCounts = countDirectoryEdges(allDirs, importEdges, fileToAncestorDirs);

  db.transaction(() => {
    for (const [dir, files] of dirFiles) {
      const dirRow = getNodeIdStmt.get(dir, 'directory', dir, 0);
      if (!dirRow) continue;

      const fileCount = files.length;
      const symbolCount = countSymbolsInFiles(files, fileSymbols);

      const counts = dirEdgeCounts.get(dir) || { intra: 0, fanIn: 0, fanOut: 0 };
      const totalEdges = counts.intra + counts.fanIn + counts.fanOut;
      const cohesion = totalEdges > 0 ? counts.intra / totalEdges : null;

      upsertMetric.run(
        dirRow.id,
        null,
        symbolCount,
        null,
        null,
        counts.fanIn,
        counts.fanOut,
        cohesion,
        fileCount,
      );
    }
  })();
}

// ─── Build-time: insert directory nodes, contains edges, and metrics ────

export function buildStructure(
  db: BetterSqlite3Database,
  fileSymbols: Map<string, FileSymbolData>,
  _rootDir: string,
  lineCountMap: Map<string, number>,
  directories: Set<string>,
  changedFiles?: string[] | null,
): void {
  const insertNode = db.prepare(
    'INSERT OR IGNORE INTO nodes (name, kind, file, line, end_line) VALUES (?, ?, ?, ?, ?)',
  );
  const getNodeIdStmt: NodeIdStmt = {
    get: (name: string, kind: string, file: string, line: number) => {
      const id = getNodeId(db, name, kind, file, line);
      return id != null ? { id } : undefined;
    },
  };
  const insertEdge = db.prepare(
    'INSERT INTO edges (source_id, target_id, kind, confidence, dynamic) VALUES (?, ?, ?, ?, ?)',
  );
  const upsertMetric = db.prepare(`
    INSERT OR REPLACE INTO node_metrics
      (node_id, line_count, symbol_count, import_count, export_count, fan_in, fan_out, cohesion, file_count)
    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
  `);

  const isIncremental = changedFiles != null && changedFiles.length > 0;

  cleanupPreviousData(db, getNodeIdStmt, isIncremental, changedFiles ?? null);

  const allDirs = collectAllDirectories(directories, fileSymbols);

  db.transaction(() => {
    for (const dir of allDirs) {
      insertNode.run(dir, 'directory', dir, 0, null);
    }
  })();

  insertContainsEdges(db, insertEdge, getNodeIdStmt, fileSymbols, allDirs, changedFiles ?? null);

  const { fanInMap, fanOutMap, importEdges } = computeImportEdgeMaps(db);

  computeFileMetrics(
    db,
    upsertMetric,
    getNodeIdStmt,
    fileSymbols,
    lineCountMap,
    fanInMap,
    fanOutMap,
  );

  computeDirectoryMetrics(db, upsertMetric, getNodeIdStmt, fileSymbols, allDirs, importEdges);

  debug(`Structure: ${allDirs.size} directories, ${fileSymbols.size} files with metrics`);
}

// ─── Node role classification ─────────────────────────────────────────

// Re-export from classifier for backward compatibility
export { FRAMEWORK_ENTRY_PREFIXES } from '../graph/classifiers/roles.js';

import { classifyRoles, median } from '../graph/classifiers/roles.js';

interface RoleSummary {
  entry: number;
  core: number;
  utility: number;
  adapter: number;
  dead: number;
  'dead-leaf': number;
  'dead-entry': number;
  'dead-ffi': number;
  'dead-unresolved': number;
  'test-only': number;
  leaf: number;
  [key: string]: number;
}

/**
 * Classify every node in the graph into a role (core, entry, utility, etc.).
 *
 * When `changedFiles` is provided, only nodes from those files (and their
 * edge neighbours) are reclassified. The returned `RoleSummary` in that case
 * reflects **only the affected subset**, not the entire graph. Callers that
 * need graph-wide totals should perform a full classification (omit
 * `changedFiles`) or query the DB directly.
 */
export function classifyNodeRoles(
  db: BetterSqlite3Database,
  changedFiles?: string[] | null,
): RoleSummary {
  const emptySummary: RoleSummary = {
    entry: 0,
    core: 0,
    utility: 0,
    adapter: 0,
    dead: 0,
    'dead-leaf': 0,
    'dead-entry': 0,
    'dead-ffi': 0,
    'dead-unresolved': 0,
    'test-only': 0,
    leaf: 0,
  };

  // Incremental path: only reclassify nodes from affected files
  if (changedFiles && changedFiles.length > 0) {
    return classifyNodeRolesIncremental(db, changedFiles, emptySummary);
  }

  return classifyNodeRolesFull(db, emptySummary);
}

// ─── Shared role-classification helpers ───────────────────────────────

/**
 * Build a role summary and group node IDs by role from classifier output.
 * Shared between full and incremental classification paths.
 */
function buildRoleSummary(
  rows: { id: number }[],
  leafRows: { id: number }[],
  roleMap: Map<string, string>,
  emptySummary: RoleSummary,
): { summary: RoleSummary; idsByRole: Map<string, number[]> } {
  const summary: RoleSummary = { ...emptySummary };
  const idsByRole = new Map<string, number[]>();

  // Leaf kinds are always dead-leaf — skip classifier
  if (leafRows.length > 0) {
    const leafIds: number[] = [];
    for (const row of leafRows) leafIds.push(row.id);
    idsByRole.set('dead-leaf', leafIds);
    summary.dead += leafRows.length;
    summary['dead-leaf'] += leafRows.length;
  }

  for (const row of rows) {
    const role = roleMap.get(String(row.id)) || 'leaf';
    if (role.startsWith('dead')) summary.dead++;
    summary[role] = (summary[role] || 0) + 1;
    let ids = idsByRole.get(role);
    if (!ids) {
      ids = [];
      idsByRole.set(role, ids);
    }
    ids.push(row.id);
  }

  return { summary, idsByRole };
}

/**
 * Batch-update node roles in the database. Executes a reset callback
 * first (full resets all nodes, incremental resets only affected files),
 * then writes new roles in chunks.
 */
function batchUpdateRoles(
  db: BetterSqlite3Database,
  idsByRole: Map<string, number[]>,
  resetFn: () => void,
): void {
  const ROLE_CHUNK = 500;
  const roleStmtCache = new Map<number, DbSqliteStatement>();
  db.transaction(() => {
    resetFn();
    for (const [role, ids] of idsByRole) {
      for (let i = 0; i < ids.length; i += ROLE_CHUNK) {
        const end = Math.min(i + ROLE_CHUNK, ids.length);
        const chunkSize = end - i;
        const stmt = getOrCreateChunkStmt(roleStmtCache, db, chunkSize, (n) => {
          const placeholders = Array.from({ length: n }, () => '?').join(',');
          return `UPDATE nodes SET role = ? WHERE id IN (${placeholders})`;
        });
        const vals: unknown[] = [role];
        for (let j = i; j < end; j++) vals.push(ids[j]);
        stmt.run(...vals);
      }
    }
  })();
}

interface CallableNodeRow {
  id: number;
  name: string;
  kind: string;
  file: string;
  fan_in: number;
  fan_out: number;
}

/**
 * Kinds that are consumed via annotations/references rather than calls.
 * These do not count as "active callables" for the hasActiveFileSiblings heuristic.
 */
const ANNOTATION_ONLY_KINDS = new Set([
  'constant',
  'struct',
  'enum',
  'trait',
  'type',
  'interface',
  'record',
]);

/**
 * Build two active-files sets from callable rows:
 *
 * - `activeFiles`: files with at least one non-annotation-only callable with
 *   `fan_in > 0 || fan_out > 0`. Used for annotation-only kinds (constants,
 *   type defs) which have no callers by design.
 *
 * - `calledActiveFiles`: files with at least one non-annotation-only callable
 *   with `fan_in > 0` (strictly called). Used for method/function kinds to
 *   prevent a self-sibling loop: a function with `fanIn=0, fanOut>0` as the
 *   only callable in its file must NOT count itself as an "active sibling" and
 *   thus promote itself to `leaf`.
 */
function buildActiveFilesSet(rows: CallableNodeRow[]): {
  activeFiles: Set<string>;
  calledActiveFiles: Set<string>;
} {
  const activeFiles = new Set<string>();
  const calledActiveFiles = new Set<string>();
  for (const r of rows) {
    if (!ANNOTATION_ONLY_KINDS.has(r.kind)) {
      if (r.fan_in > 0 || r.fan_out > 0) {
        activeFiles.add(r.file);
      }
      if (r.fan_in > 0) {
        calledActiveFiles.add(r.file);
      }
    }
  }
  return { activeFiles, calledActiveFiles };
}

/** Map callable rows to classifier input objects, attaching exported/prod-fan-in/active-file metadata. */
function buildClassifierInput(
  rows: CallableNodeRow[],
  exportedIds: Set<number>,
  prodFanInMap: Map<number, number>,
  activeFiles: Set<string>,
  calledActiveFiles: Set<string>,
): Array<{
  id: string;
  name: string;
  kind: string;
  file: string;
  fanIn: number;
  fanOut: number;
  isExported: boolean;
  productionFanIn: number;
  hasActiveFileSiblings: boolean | undefined;
}> {
  return rows.map((r) => ({
    id: String(r.id),
    name: r.name,
    kind: r.kind,
    file: r.file,
    fanIn: r.fan_in,
    fanOut: r.fan_out,
    isExported: exportedIds.has(r.id),
    productionFanIn: prodFanInMap.get(r.id) || 0,
    // Set hasActiveFileSiblings for annotation-only kinds (constants, type defs)
    // AND for method/function — the latter two can have fanIn === 0 due to
    // untraced call-site patterns (interface dispatch, logical-or defaults).
    // The classifier interprets this field differently per kind (see classifyUnreferencedNode).
    //
    // IMPORTANT: method/function use calledActiveFiles (fan_in > 0 only) to
    // prevent a self-sibling false negative: a function with fanIn=0, fanOut>0
    // as the sole callable in its file must NOT see its own file as "active"
    // and promote itself to leaf.
    hasActiveFileSiblings: ANNOTATION_ONLY_KINDS.has(r.kind)
      ? activeFiles.has(r.file)
      : r.kind === 'method' || r.kind === 'function'
        ? calledActiveFiles.has(r.file)
        : undefined,
  }));
}

// ─── Median cache helpers ─────────────────────────────────────────────────────

const ROLES_MEDIANS_KEY = 'roles_medians';

// Invalidate cached medians when the edge count drifts past this threshold.
// A 1-file rebuild adds/removes < 100 edges — well within the margin.
const MEDIAN_INVALIDATION_DELTA = 500;

/**
 * Full edge-table GROUP BY scan — O(M). Only runs on cache miss.
 *
 * Joins `nodes` to restrict to the same non-leaf kinds that
 * `classifyNodeRolesFull` uses when computing medians from in-memory rows
 * (excludes 'file', 'directory', 'parameter', 'property'). This keeps the
 * two paths consistent so a cold-cache fallback produces the same distribution
 * as the full-build cached value.
 *
 * Also returns the filtered edge count used for computing the medians so the
 * caller can pass it directly to `writeMedianCache` without a second query.
 */
function computeGlobalMediansFromEdges(db: BetterSqlite3Database): {
  fanIn: number;
  fanOut: number;
  edgeCount: number;
} {
  const excludedKinds = `('file', 'directory', 'parameter', 'property')`;
  const fanInRows = db
    .prepare(
      `SELECT COUNT(*) AS cnt FROM edges e
       JOIN nodes t ON e.target_id = t.id
       WHERE e.kind IN ('calls', 'imports-type')
         AND t.kind NOT IN ${excludedKinds}
       GROUP BY e.target_id`,
    )
    .all() as { cnt: number }[];
  const fanOutRows = db
    .prepare(
      `SELECT COUNT(*) AS cnt FROM edges e
       JOIN nodes s ON e.source_id = s.id
       WHERE e.kind = 'calls'
         AND s.kind NOT IN ${excludedKinds}
       GROUP BY e.source_id`,
    )
    .all() as { cnt: number }[];
  const fanInDist = fanInRows.map((r) => r.cnt).sort((a, b) => a - b);
  const fanOutDist = fanOutRows.map((r) => r.cnt).sort((a, b) => a - b);
  // Sum of fanInRows[*].cnt equals the total edge count for the relevant
  // edge subset — no extra COUNT query needed.
  const edgeCount = fanInRows.reduce((acc, r) => acc + r.cnt, 0);
  return { fanIn: median(fanInDist), fanOut: median(fanOutDist), edgeCount };
}

/**
 * Read cached role medians from build_meta. Returns null when absent or stale
 * (edge count moved beyond MEDIAN_INVALIDATION_DELTA from the cached value).
 *
 * The staleness check uses the same edge subset (calls + imports-type) that
 * the medians are derived from, so only changes to the edges that actually
 * influence fan-in/fan-out can evict the cache.
 */
function readCachedMedians(db: BetterSqlite3Database): { fanIn: number; fanOut: number } | null {
  const raw = getBuildMeta(db, ROLES_MEDIANS_KEY);
  if (!raw) return null;
  try {
    const cached = JSON.parse(raw) as { fanIn: number; fanOut: number; edgeCount: number };
    // Count only the edge kinds that drive median computation — same subset
    // used by computeGlobalMediansFromEdges and classifyNodeRolesFull.
    const currentCount = (
      db
        .prepare(`SELECT COUNT(*) AS cnt FROM edges WHERE kind IN ('calls', 'imports-type')`)
        .get() as { cnt: number }
    ).cnt;
    if (
      Math.abs(currentCount - cached.edgeCount) >
      Math.max(MEDIAN_INVALIDATION_DELTA, cached.edgeCount * 0.1)
    )
      return null;
    return { fanIn: cached.fanIn, fanOut: cached.fanOut };
  } catch (e) {
    debug(`readCachedMedians: failed to parse cached medians — ${e}`);
    return null;
  }
}

/**
 * Persist global role medians + current edge count to build_meta.
 *
 * @param edgeCount - pre-computed calls+imports-type edge count. When provided,
 *   the function skips the COUNT query entirely. Pass when the count is already
 *   known at the call site (e.g. from `computeGlobalMediansFromEdges`).
 */
function writeMedianCache(
  db: BetterSqlite3Database,
  medians: { fanIn: number; fanOut: number },
  edgeCount?: number,
): void {
  const cnt =
    edgeCount ??
    (
      db
        .prepare(`SELECT COUNT(*) AS cnt FROM edges WHERE kind IN ('calls', 'imports-type')`)
        .get() as { cnt: number }
    ).cnt;
  setBuildMeta(db, { [ROLES_MEDIANS_KEY]: JSON.stringify({ ...medians, edgeCount: cnt }) });
}

function classifyNodeRolesFull(db: BetterSqlite3Database, emptySummary: RoleSummary): RoleSummary {
  // Property kind (class/struct fields) can never have callers/callees.
  // Classify them directly as dead-leaf without the expensive fan-in/fan-out JOINs.
  //
  // `parameter` is deliberately NOT included here (#1723): a parameter's liveness
  // is a local dataflow question (is it referenced within its own function body),
  // not a call-graph reachability question, so "no incoming call edges" carries
  // zero dead-code signal for it. Parameters are also excluded from the main
  // query below, so they never receive a role at all — the same treatment as
  // `file`/`directory` nodes.
  const leafRows = db
    .prepare(
      `SELECT n.id
      FROM nodes n
      WHERE n.kind = 'property'`,
    )
    .all() as { id: number }[];

  // Only compute fan-in/fan-out for callable/classifiable nodes
  const rows = db
    .prepare(
      `SELECT n.id, n.name, n.kind, n.file,
        COALESCE(fi.cnt, 0) AS fan_in,
        COALESCE(fo.cnt, 0) AS fan_out
      FROM nodes n
      LEFT JOIN (
        SELECT target_id, COUNT(*) AS cnt FROM edges WHERE kind IN ('calls', 'imports-type') GROUP BY target_id
      ) fi ON n.id = fi.target_id
      LEFT JOIN (
        SELECT source_id, COUNT(*) AS cnt FROM edges WHERE kind = 'calls' GROUP BY source_id
      ) fo ON n.id = fo.source_id
      WHERE n.kind NOT IN ('file', 'directory', 'parameter', 'property')`,
    )
    .all() as CallableNodeRow[];

  if (rows.length === 0 && leafRows.length === 0) return emptySummary;

  const exportedIds = new Set(
    (
      db
        .prepare(
          `SELECT DISTINCT e.target_id
        FROM edges e
        JOIN nodes caller ON e.source_id = caller.id
        JOIN nodes target ON e.target_id = target.id
        WHERE e.kind IN ('calls', 'imports-type') AND caller.file != target.file`,
        )
        .all() as { target_id: number }[]
    ).map((r) => r.target_id),
  );

  // Mark symbols as exported when their files are targets of reexports edges
  // from production-reachable barrels (traces through multi-level chains) (#837)
  //
  // `method` is excluded (#1780): a `reexports` edge only ever concerns
  // top-level module bindings (functions, classes, types, constants, ...) — a
  // class/interface method can never be an independently re-exportable
  // binding on its own, so inheriting "exported" status from a co-located
  // top-level re-export is a category error. Without this exclusion, e.g. an
  // abstract base class's zero-fan-in method declarations were promoted to
  // `entry` merely because some other symbol in the same file was re-exported
  // through a barrel.
  const reexportExported = db
    .prepare(
      `WITH RECURSIVE prod_reachable(file_id) AS (
        SELECT DISTINCT e.target_id
        FROM edges e
        JOIN nodes src ON e.source_id = src.id
        WHERE e.kind IN ('imports', 'dynamic-imports', 'imports-type')
          AND src.kind = 'file'
          ${testFilterSQL('src.file')}
        UNION
        SELECT e.target_id
        FROM edges e
        JOIN prod_reachable pr ON e.source_id = pr.file_id
        WHERE e.kind = 'reexports'
      )
      SELECT DISTINCT n.id
      FROM nodes n
      JOIN nodes f ON f.file = n.file AND f.kind = 'file'
      WHERE f.id IN (
        SELECT e.target_id FROM edges e
        WHERE e.kind = 'reexports'
          AND e.source_id IN (SELECT file_id FROM prod_reachable)
      )
      AND n.kind NOT IN ('file', 'directory', 'parameter', 'property', 'method')`,
    )
    .all() as { id: number }[];
  for (const r of reexportExported) exportedIds.add(r.id);

  // Mark symbols with exported=1 as exported — the extractor sets this flag when the
  // author writes `export interface Foo { }` / `export type Bar = ...` / `export function`.
  // Cross-file edge inference misses these when the symbol is only used as a type annotation
  // within the same file (no calls/imports-type edge is produced for same-file type usage).
  // This fixes false dead-unresolved classification for exported interfaces with no external callers (#1583).
  const explicitlyExported = db
    .prepare(
      `SELECT id FROM nodes
      WHERE exported = 1
        AND kind NOT IN ('file', 'directory', 'parameter', 'property')`,
    )
    .all() as { id: number }[];
  for (const r of explicitlyExported) exportedIds.add(r.id);

  // Compute production fan-in (excluding callers in test files)
  const prodFanInMap = new Map<number, number>();
  const prodRows = db
    .prepare(
      `SELECT e.target_id, COUNT(*) AS cnt
      FROM edges e
      JOIN nodes caller ON e.source_id = caller.id
      WHERE e.kind IN ('calls', 'imports-type')
        ${testFilterSQL('caller.file')}
      GROUP BY e.target_id`,
    )
    .all() as { target_id: number; cnt: number }[];
  for (const r of prodRows) {
    prodFanInMap.set(r.target_id, r.cnt);
  }

  // Delegate classification to the pure-logic classifier.
  // Compute medians from the already-loaded rows (no extra DB round-trip),
  // pass them as overrides to avoid recomputing inside classifyRoles,
  // and cache them for subsequent incremental builds.
  const { activeFiles, calledActiveFiles } = buildActiveFilesSet(rows);
  const classifierInput = buildClassifierInput(
    rows,
    exportedIds,
    prodFanInMap,
    activeFiles,
    calledActiveFiles,
  );
  const nonZeroFanIn = classifierInput
    .filter((n) => n.fanIn > 0)
    .map((n) => n.fanIn)
    .sort((a, b) => a - b);
  const nonZeroFanOut = classifierInput
    .filter((n) => n.fanOut > 0)
    .map((n) => n.fanOut)
    .sort((a, b) => a - b);
  const globalMedians = { fanIn: median(nonZeroFanIn), fanOut: median(nonZeroFanOut) };
  const roleMap = classifyRoles(classifierInput, globalMedians);
  // Derive the edge count from already-loaded in-memory rows: summing fan_in
  // across all nodes equals COUNT(*) FROM edges WHERE kind IN ('calls','imports-type'),
  // since the full-build query left-joins every matching edge exactly once per target.
  // Passing this avoids an extra COUNT query on the full-build path.
  const inMemoryEdgeCount = rows.reduce((acc, r) => acc + r.fan_in, 0);
  writeMedianCache(db, globalMedians, inMemoryEdgeCount);

  const { summary, idsByRole } = buildRoleSummary(rows, leafRows, roleMap, emptySummary);

  batchUpdateRoles(db, idsByRole, () => {
    db.prepare('UPDATE nodes SET role = NULL').run();
  });

  return summary;
}

/**
 * Direct barrels: files that directly re-export (one hop) into any of the
 * given target files. Used by `classifyNodeRolesIncremental`'s scoped
 * alternative to the full `prod_reachable` recursive CTE — see
 * `isBarrelProdReachable`. Mirrors Rust `find_direct_reexport_barrels`.
 */
function findDirectReexportBarrels(
  db: BetterSqlite3Database,
  allAffectedFiles: string[],
): string[] {
  const placeholders = allAffectedFiles.map(() => '?').join(',');
  const rows = db
    .prepare(
      `SELECT DISTINCT n1.file AS file FROM edges e
         JOIN nodes n1 ON e.source_id = n1.id
         JOIN nodes n2 ON e.target_id = n2.id
       WHERE e.kind = 'reexports' AND n2.file IN (${placeholders})`,
    )
    .all(...allAffectedFiles) as { file: string }[];
  return rows.map((r) => r.file);
}

/**
 * True when `barrelFile` is production-reachable — i.e. a member of the same
 * `prod_reachable` set `classifyNodeRolesFull`'s recursive CTE computes
 * globally (a non-test file directly imports it, or reaches it transitively
 * through a chain of `reexports` edges) — but answered for one specific file
 * instead of materializing the whole graph's closure. Mirrors Rust
 * `is_barrel_prod_reachable` — see that function's doc comment for the
 * measured cost difference (#1855) and the reachability argument.
 */
function isBarrelProdReachable(db: BetterSqlite3Database, barrelFile: string): boolean {
  // Fast path: barrelFile itself is directly imported by a non-test file
  // (the base case of the original `prod_reachable` definition).
  const direct = cachedStmt(
    _barrelDirectStmt,
    db,
    `SELECT EXISTS(
         SELECT 1 FROM edges e
           JOIN nodes src ON e.source_id = src.id
           JOIN nodes tgt ON e.target_id = tgt.id
         WHERE e.kind IN ('imports', 'dynamic-imports', 'imports-type')
           AND src.kind = 'file' AND tgt.kind = 'file' AND tgt.file = ?
           ${testFilterSQL('src.file')}
       ) AS reachable`,
  ).get(barrelFile) as { reachable: number };
  if (direct.reachable) return true;

  // Slow path: walk `reexports` edges backward from barrelFile (who
  // re-exports INTO barrelFile, transitively) looking for an ancestor
  // that's directly imported by production. `UNION` (not `UNION ALL`)
  // dedupes on `file`, which both bounds the search to barrelFile's own
  // chain and guarantees termination if the chain contains a cycle.
  const backward = cachedStmt(
    _barrelBackwardStmt,
    db,
    `WITH RECURSIVE ancestors(file) AS (
         SELECT ? AS file
         UNION
         SELECT DISTINCT n1.file FROM edges e
           JOIN nodes n1 ON e.source_id = n1.id
           JOIN nodes n2 ON e.target_id = n2.id
           JOIN ancestors a ON n2.file = a.file
         WHERE e.kind = 'reexports'
       )
       SELECT EXISTS(
         SELECT 1 FROM ancestors a
           JOIN nodes af ON af.file = a.file AND af.kind = 'file'
           JOIN edges e2 ON e2.target_id = af.id
           JOIN nodes src2 ON e2.source_id = src2.id
         WHERE e2.kind IN ('imports', 'dynamic-imports', 'imports-type')
           AND src2.kind = 'file'
           ${testFilterSQL('src2.file')}
       ) AS reachable`,
  ).get(barrelFile) as { reachable: number };
  return !!backward.reachable;
}

/**
 * Incremental role classification: only reclassify nodes from changed files
 * plus their immediate edge neighbours (callers and callees in other files).
 *
 * Uses indexed point lookups for fan-in/fan-out instead of full table scans.
 * Global medians are read from the build_meta cache written by the last full
 * classification; the cache is only recomputed when the edge count drifts
 * beyond MEDIAN_INVALIDATION_DELTA (i.e. large structural changes).
 * Unchanged files not connected to changed files keep their roles from the
 * previous build.
 */
function classifyNodeRolesIncremental(
  db: BetterSqlite3Database,
  changedFiles: string[],
  emptySummary: RoleSummary,
): RoleSummary {
  // Expand affected set: include files containing nodes that are edge neighbours
  // of changed-file nodes. This ensures that removing a call from file A to a
  // node in file B causes B's roles to be recalculated (fan_in changed).
  //
  // Written as a UNION of two directional joins rather than a single
  // OR-based self-join (`JOIN nodes n1 ON (e.source_id = n1.id OR
  // e.target_id = n1.id)`, likewise for `n2`). The OR-join can't be served
  // by an index on either side of the OR, so better-sqlite3/SQLite falls
  // back to scanning every edge matching `e.kind IN (...)` and probing both
  // endpoints per row. Each directional half below is a plain equi-join on
  // source_id/target_id, letting the planner drive the scan from
  // idx_edges_kind_source/idx_edges_kind_target directly. `UNION` (not
  // `UNION ALL`) dedupes the combined result the same way the original
  // query's `DISTINCT` did. Same result set, measured ~2.4x faster
  // (#1855 — this query's cost, compounded by the symbol-level
  // `reexports` edges added in #1849, was a major contributor to the
  // "1-file rebuild" benchmark regression when the changed file is itself
  // a barrel/re-export hub).
  const seedPlaceholders = changedFiles.map(() => '?').join(',');
  const neighbourFiles = db
    .prepare(
      `SELECT n2.file AS file FROM edges e
         JOIN nodes n1 ON e.source_id = n1.id
         JOIN nodes n2 ON e.target_id = n2.id
         WHERE e.kind IN ('calls', 'imports-type', 'reexports')
           AND n1.file IN (${seedPlaceholders}) AND n2.file NOT IN (${seedPlaceholders})
           AND n2.kind NOT IN ('file', 'directory')
       UNION
       SELECT n1.file AS file FROM edges e
         JOIN nodes n1 ON e.source_id = n1.id
         JOIN nodes n2 ON e.target_id = n2.id
         WHERE e.kind IN ('calls', 'imports-type', 'reexports')
           AND n2.file IN (${seedPlaceholders}) AND n1.file NOT IN (${seedPlaceholders})
           AND n1.kind NOT IN ('file', 'directory')`,
    )
    .all(...changedFiles, ...changedFiles, ...changedFiles, ...changedFiles) as { file: string }[];
  const allAffectedFiles = [...changedFiles, ...neighbourFiles.map((r) => r.file)];
  const placeholders = allAffectedFiles.map(() => '?').join(',');

  // 1. Read global medians from cache; fall back to full edge scan only on miss.
  // The median barely moves for a 1-file change, so the cache is almost always
  // valid, eliminating 2× full edge-table GROUP BY queries (~10-15 ms on large graphs).
  const cachedMedians = readCachedMedians(db);
  let globalMedians: { fanIn: number; fanOut: number };
  if (cachedMedians) {
    globalMedians = cachedMedians;
  } else {
    const computed = computeGlobalMediansFromEdges(db);
    // Pass the edgeCount returned by computeGlobalMediansFromEdges so
    // writeMedianCache does not issue a second COUNT query.
    writeMedianCache(db, computed, computed.edgeCount);
    globalMedians = computed;
  }

  // 2a. Property kind (class/struct fields) in affected files — always dead-leaf.
  // `parameter` is intentionally excluded (#1723) — see classifyNodeRolesFull for
  // the rationale. Parameters stay unclassified (role = NULL) after the reset below.
  const leafRows = db
    .prepare(
      `SELECT n.id FROM nodes n
      WHERE n.kind = 'property'
        AND n.file IN (${placeholders})`,
    )
    .all(...allAffectedFiles) as { id: number }[];

  // 2b. Get callable nodes using indexed correlated subqueries (fast point lookups)
  const rows = db
    .prepare(
      `SELECT n.id, n.name, n.kind, n.file,
        (SELECT COUNT(*) FROM edges WHERE kind IN ('calls', 'imports-type') AND target_id = n.id) AS fan_in,
        (SELECT COUNT(*) FROM edges WHERE kind = 'calls' AND source_id = n.id) AS fan_out
      FROM nodes n
      WHERE n.kind NOT IN ('file', 'directory', 'parameter', 'property')
        AND n.file IN (${placeholders})`,
    )
    .all(...allAffectedFiles) as CallableNodeRow[];

  if (rows.length === 0 && leafRows.length === 0) return emptySummary;

  // 3. Get exported status for affected nodes only (scoped to changed files)
  const exportedIds = new Set(
    (
      db
        .prepare(
          `SELECT DISTINCT e.target_id
          FROM edges e
          JOIN nodes caller ON e.source_id = caller.id
          JOIN nodes target ON e.target_id = target.id
          WHERE e.kind IN ('calls', 'imports-type') AND caller.file != target.file
            AND target.file IN (${placeholders})`,
        )
        .all(...allAffectedFiles) as { target_id: number }[]
    ).map((r) => r.target_id),
  );

  // 3b. Mark symbols as exported when their files are targets of reexports edges
  // from production-reachable barrels (traces through multi-level chains) (#837).
  //
  // classifyNodeRolesFull's step 3b answers this by materializing the global
  // `prod_reachable` closure (every file reachable from any production
  // import, extended through reexports chains) because it has no smaller
  // scope to exploit — it's already processing every file. Here, only
  // `allAffectedFiles` (the changed files plus their one-hop neighbours) can
  // possibly be reexport targets we care about, so instead: find the small
  // set of barrels that directly reexport into `allAffectedFiles` (typically
  // 1-3 files), then answer "is this specific barrel production-reachable"
  // with a backward-scoped check instead of the whole-graph forward closure
  // (see `isBarrelProdReachable`).
  //
  // `method` is excluded (#1780) — see classifyNodeRolesFull for rationale.
  const reexportBarrels = findDirectReexportBarrels(db, allAffectedFiles);
  const reachableBarrels = reexportBarrels.filter((b) => isBarrelProdReachable(db, b));
  if (reachableBarrels.length > 0) {
    const barrelPlaceholders = reachableBarrels.map(() => '?').join(',');
    const reexportExported = db
      .prepare(
        `SELECT DISTINCT n.id
        FROM nodes n
        JOIN nodes f ON f.file = n.file AND f.kind = 'file'
        JOIN edges e ON e.target_id = f.id
        JOIN nodes b ON e.source_id = b.id
        WHERE e.kind = 'reexports' AND b.file IN (${barrelPlaceholders})
          AND n.kind NOT IN ('file', 'directory', 'parameter', 'property', 'method')
          AND n.file IN (${placeholders})`,
      )
      .all(...reachableBarrels, ...allAffectedFiles) as { id: number }[];
    for (const r of reexportExported) exportedIds.add(r.id);
  }

  // 3c. Mark symbols with exported=1 as exported — the extractor sets this flag when the
  // author writes `export interface Foo { }` / `export type Bar = ...` / `export function`.
  // Cross-file edge inference misses these when the symbol is only used as a type annotation
  // within the same file (no calls/imports-type edge is produced for same-file type usage).
  // Scoped to affected files only for the incremental path (#1583).
  const explicitlyExported = db
    .prepare(
      `SELECT id FROM nodes
      WHERE exported = 1
        AND kind NOT IN ('file', 'directory', 'parameter', 'property')
        AND file IN (${placeholders})`,
    )
    .all(...allAffectedFiles) as { id: number }[];
  for (const r of explicitlyExported) exportedIds.add(r.id);

  // 4. Production fan-in for affected nodes only
  const prodFanInMap = new Map<number, number>();
  const prodRows = db
    .prepare(
      `SELECT e.target_id, COUNT(*) AS cnt
      FROM edges e
      JOIN nodes caller ON e.source_id = caller.id
      JOIN nodes target ON e.target_id = target.id
      WHERE e.kind IN ('calls', 'imports-type')
        AND target.file IN (${placeholders})
        ${testFilterSQL('caller.file')}
      GROUP BY e.target_id`,
    )
    .all(...allAffectedFiles) as { target_id: number; cnt: number }[];
  for (const r of prodRows) {
    prodFanInMap.set(r.target_id, r.cnt);
  }

  // 5. Classify affected nodes using global medians
  const { activeFiles, calledActiveFiles } = buildActiveFilesSet(rows);
  const classifierInput = buildClassifierInput(
    rows,
    exportedIds,
    prodFanInMap,
    activeFiles,
    calledActiveFiles,
  );
  const roleMap = classifyRoles(classifierInput, globalMedians);

  // 6. Build summary (only for affected nodes) and update only those nodes
  const { summary, idsByRole } = buildRoleSummary(rows, leafRows, roleMap, emptySummary);

  batchUpdateRoles(db, idsByRole, () => {
    // Reset roles only for affected files' nodes
    db.prepare(
      `UPDATE nodes SET role = NULL WHERE file IN (${placeholders}) AND kind NOT IN ('file', 'directory')`,
    ).run(...allAffectedFiles);
  });

  return summary;
}

// ─── Query functions (re-exported from structure-query.ts) ────────────
// Split to separate query-time concerns (DB reads, sorting, pagination)
// from build-time concerns (directory insertion, metrics computation, role classification).
export { hotspotsData, moduleBoundariesData, structureData } from './structure-query.js';