Function expandViaGraph

src/context/import-graph.ts:216–265

(
  graph: ImportGraph,
  seeds: string[],
  opts: { hops?: number; maxFiles?: number; hubDamping?: boolean } = {},
)

 * since "how does X work / why is X broken" usually lives in what X uses.
 */
export function expandViaGraph(
  graph: ImportGraph,
  seeds: string[],
  opts: { hops?: number; maxFiles?: number; hubDamping?: boolean } = {},
): Array<{ file: string; distance: number; weight: number }> {
  const hops = opts.hops ?? 1;
  const maxFiles = opts.maxFiles ?? 12;
  const hubDamping = opts.hubDamping !== false;

  // distance + which direction we first reached it (down=dependency, up=dependent)
  const dist = new Map<string, number>();
  const viaDownstream = new Map<string, boolean>();
  for (const s of seeds) if (graph.files.has(s)) { dist.set(s, 0); viaDownstream.set(s, true); }

  let frontier = [...dist.keys()];
  for (let h = 1; h <= hops; h++) {
    const next: string[] = [];
    for (const f of frontier) {
      const downstream = graph.out.get(f) ?? new Set<string>();
      const upstream = graph.in.get(f) ?? new Set<string>();
      for (const nbr of downstream) {
        if (!dist.has(nbr)) { dist.set(nbr, h); viaDownstream.set(nbr, true); next.push(nbr); }
      }
      for (const nbr of upstream) {
        if (!dist.has(nbr)) { dist.set(nbr, h); viaDownstream.set(nbr, false); next.push(nbr); }
      }
    }
    frontier = next;
  }

  const inDegreeOf = (f: string): number => (graph.in.get(f)?.size ?? 0);

  const scored = [...dist.entries()].map(([file, distance]) => {
    // Base relevance decays with distance; seeds are 1.0.
    let weight = distance === 0 ? 1.0 : 1.0 / (distance + 1);
    // Downstream (dependencies) are more relevant than upstream (dependents).
    if (distance > 0 && !viaDownstream.get(file)) weight *= 0.6;
    // Hub damping: demote files imported by many others (low query specificity).
    if (hubDamping && distance > 0) {
      const deg = inDegreeOf(file);
      weight *= 1 / Math.log2(2 + deg);
    }
    return { file, distance, weight };
  });

  // Seeds always kept; non-seeds ranked by weight, then taken up to the cap.
  const seedRows = scored.filter(s => s.distance === 0);
  const rest = scored.filter(s => s.distance > 0).sort((a, b) => b.weight - a.weight);
  return [...seedRows, ...rest].slice(0, maxFiles);
}