@yannelli/paseo-linear-plugin 1.0.0 → 1.1.0-beta.0

package/shared/graph-model.ts

@@ -0,0 +1,319 @@
+import type { AgentFocus } from "./activity";
+import type { LabelSide, Placed } from "./graph-geometry";
+import type { FileLink, LinkKind } from "./links";
+import type { MapTile } from "./map-model";
+
+// The Linear Live graph: files are vertices and the links between them, such as imports, are
+// edges. Files sit near others in their folder and take their sub-issue's color; the issue and
+// its sub-issues join the files the plan gave them. Pure, so tests can check the layout.
+
+export type GraphNodeKind = "issue" | "subissue" | "file";
+export type GraphEdgeKind = "owns" | LinkKind;
+
+export interface GraphNode {
+  id: string;
+  kind: GraphNodeKind;
+  label: string;
+  /** Issue key whose color the node takes. */
+  owner: string | null;
+  /** Repo path, for file nodes. */
+  path: string | null;
+  tile: MapTile | null;
+  /** Up to two folder levels, which files of one neighborhood share. */
+  folder: string | null;
+  /** Files left out to keep the graph readable. */
+  folded: number;
+}
+
+export interface GraphEdge {
+  id: string;
+  from: string;
+  to: string;
+  kind: GraphEdgeKind;
+}
+
+export interface Graph {
+  root: string;
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+export interface GraphInput {
+  issue: string;
+  children: readonly string[];
+  tiles: readonly MapTile[];
+  links?: readonly FileLink[];
+}
+
+const MAX_UNTOUCHED_PER_OWNER = 6;
+export const MAX_GRAPH_FILES = 120;
+const STRENGTH: Record<GraphEdgeKind, number> = { import: 4, link: 3, mention: 2, owns: 1 };
+
+export const issueNodeId = (key: string) => `issue:${key.toUpperCase()}`;
+export const subIssueNodeId = (key: string) => `sub:${key.toUpperCase()}`;
+export const fileNodeId = (path: string) => `file:${path}`;
+
+export function folderOf(path: string): string {
+  const parts = path.split("/").slice(0, -1);
+  return parts.length ? parts.slice(0, 2).join("/") : ".";
+}
+
+/** The files the graph shows: every touched file, then predicted ones up to a cap per issue. */
+export function graphFiles(input: GraphInput): { tiles: MapTile[]; folded: Map<string, number> } {
+  const children = new Set(input.children.map((key) => key.toUpperCase()));
+  const parent = input.issue.toUpperCase();
+  const ownerOf = (tile: MapTile) => (tile.owner && children.has(tile.owner.toUpperCase()) ? tile.owner.toUpperCase() : parent);
+  const tiles = input.tiles.filter((tile) => !tile.ghost);
+  const chosen = tiles.filter((tile) => tile.touch !== "none").slice(0, MAX_GRAPH_FILES);
+  const folded = new Map<string, number>();
+  const perOwner = new Map<string, number>();
+  for (const tile of tiles) {
+    if (tile.touch !== "none" || !tile.onMap) continue;
+    const owner = ownerOf(tile);
+    const count = perOwner.get(owner) ?? 0;
+    if (count >= MAX_UNTOUCHED_PER_OWNER || chosen.length >= MAX_GRAPH_FILES) {
+      folded.set(owner, (folded.get(owner) ?? 0) + 1);
+      continue;
+    }
+    perOwner.set(owner, count + 1);
+    chosen.push(tile);
+  }
+  return { tiles: chosen, folded };
+}
+
+export function buildGraph(input: GraphInput): Graph {
+  const parentKey = input.issue.toUpperCase();
+  const root = issueNodeId(parentKey);
+  const children = new Set(input.children.map((key) => key.toUpperCase()));
+  const nodes = new Map<string, GraphNode>();
+  const edges = new Map<string, GraphEdge>();
+  const { tiles, folded } = graphFiles(input);
+  const add = (node: GraphNode) => nodes.set(node.id, node);
+  const join = (from: string, to: string, kind: GraphEdgeKind) => {
+    if (from === to || !nodes.has(from) || !nodes.has(to)) return;
+    const [a, b] = from < to ? [from, to] : [to, from];
+    const id = `${a}>${b}`;
+    const known = edges.get(id);
+    if (!known || STRENGTH[kind] > STRENGTH[known.kind]) edges.set(id, { id, from, to, kind });
+  };
+  const hub = (key: string) => (children.has(key) ? subIssueNodeId(key) : root);
+  add({ id: root, kind: "issue", label: parentKey, owner: parentKey, path: null, tile: null, folder: null, folded: folded.get(parentKey) ?? 0 });
+  for (const key of children) {
+    add({ id: subIssueNodeId(key), kind: "subissue", label: key, owner: key, path: null, tile: null, folder: null, folded: folded.get(key) ?? 0 });
+    join(root, subIssueNodeId(key), "owns");
+  }
+  for (const tile of tiles) {
+    const id = fileNodeId(tile.path);
+    const label = tile.path.split("/").pop() ?? tile.path;
+    add({ id, kind: "file", label, owner: tile.owner, path: tile.path, tile, folder: folderOf(tile.path), folded: 0 });
+    if (tile.onMap && tile.owner) join(hub(tile.owner.toUpperCase()), id, "owns");
+  }
+  for (const link of input.links ?? []) join(fileNodeId(link.from), fileNodeId(link.to), link.kind);
+  return { root, nodes: [...nodes.values()], edges: [...edges.values()] };
+}
+
+/** Changes only when a node or an edge comes or goes; then the layout runs again. */
+export function graphKey(graph: Graph): string {
+  const ids = graph.nodes.map((node) => node.id).sort();
+  const links = graph.edges.map((edge) => edge.id).sort();
+  return `${ids.join("|")}#${links.join("|")}`;
+}
+
+const MAX_HOPS = 6;
+
+/** The shortest walk between two nodes along edges, or a straight hop when there is none. */
+export function graphPath(graph: Graph, from: string, to: string): string[] {
+  const ids = new Set(graph.nodes.map((node) => node.id));
+  if (!ids.has(to)) return [];
+  if (!ids.has(from) || from === to) return [to];
+  const next = new Map<string, string[]>();
+  for (const edge of graph.edges) {
+    next.set(edge.from, [...(next.get(edge.from) ?? []), edge.to]);
+    next.set(edge.to, [...(next.get(edge.to) ?? []), edge.from]);
+  }
+  const came = new Map<string, string>([[from, from]]);
+  const queue = [from];
+  for (let index = 0; index < queue.length && !came.has(to); index += 1) {
+    const at = queue[index] as string;
+    for (const neighbor of [...(next.get(at) ?? [])].sort()) {
+      if (came.has(neighbor)) continue;
+      came.set(neighbor, at);
+      queue.push(neighbor);
+    }
+  }
+  if (!came.has(to)) return [from, to];
+  const path = [to];
+  while (path[0] !== from) path.unshift(came.get(path[0] as string) as string);
+  return path.length - 1 > MAX_HOPS ? [from, to] : path;
+}
+
+/** The node an agent works on: its file or sub-issue when the graph has it, else the issue. */
+export function focusNode(graph: Graph, focus: AgentFocus | null): string {
+  if (!focus) return graph.root;
+  const id = focus.kind === "issue" ? subIssueNodeId(focus.key) : fileNodeId(focus.path);
+  return graph.nodes.some((node) => node.id === id) ? id : graph.root;
+}
+
+function mulberry32(seed: number) {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let value = state;
+    value = Math.imul(value ^ (value >>> 15), value | 1);
+    value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+    return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function hash(text: string): number {
+  let value = 2166136261;
+  for (let index = 0; index < text.length; index += 1) value = Math.imul(value ^ text.charCodeAt(index), 16777619);
+  return value >>> 0;
+}
+
+// Edge length as a share of the ideal spacing, and how hard the edge pulls.
+const SPRINGS: Record<GraphEdgeKind, { length: number; weight: number }> = {
+  import: { length: 0.6, weight: 1 },
+  link: { length: 0.7, weight: 0.7 },
+  mention: { length: 0.9, weight: 0.35 },
+  owns: { length: 1, weight: 0.3 },
+};
+const GRAVITY = 0.05;
+const COHESION = 0.35;
+const ANCHOR = 6;
+
+function sideOf(point: { x: number; y: number }, center: { x: number; y: number }): LabelSide {
+  if (point.x > center.x + 30) return "right";
+  if (point.x < center.x - 30) return "left";
+  return point.y > center.y ? "below" : "above";
+}
+
+// Force layout: nodes push apart, edges pull together, files drift toward their folder's middle,
+// and the issue stays fixed in the center. A warm start holds nodes near where they were.
+export function layoutGraph(
+  graph: Graph,
+  width: number,
+  height: number,
+  previous: ReadonlyMap<string, { x: number; y: number }> = new Map(),
+): Map<string, Placed> {
+  const random = mulberry32(hash(graphKey(graph)));
+  const center = { x: width / 2, y: height / 2 };
+  const padX = Math.min(96, width * 0.14);
+  const padY = 40;
+  const clamp = (x: number, y: number) => ({
+    x: Math.min(width - padX, Math.max(padX, x)),
+    y: Math.min(height - padY, Math.max(padY, y)),
+  });
+  const nodes = graph.nodes;
+  const k = Math.sqrt((width * height) / Math.max(1, nodes.length)) * 0.72;
+  const folders = [...new Set(nodes.flatMap((node) => (node.folder ? [node.folder] : [])))].sort();
+  const position = new Map<string, { x: number; y: number }>();
+  let warm = 0;
+  for (const node of nodes) {
+    const before = previous.get(node.id);
+    if (node.id === graph.root) position.set(node.id, { ...center });
+    else if (before) {
+      position.set(node.id, clamp(before.x, before.y));
+      warm += 1;
+    } else {
+      // Each folder starts in its own direction, so neighborhoods form quickly.
+      const slot = node.folder ? folders.indexOf(node.folder) : folders.length + (hash(node.id) % 7);
+      const angle = (slot / Math.max(1, folders.length + 1)) * Math.PI * 2 + random() * 0.6;
+      const reach = (node.kind === "file" ? 0.55 + random() * 0.35 : 0.3) * Math.min(width, height) * 0.5;
+      position.set(node.id, clamp(center.x + Math.cos(angle) * reach * (width / height), center.y + Math.sin(angle) * reach));
+    }
+  }
+  const coldStart = warm < nodes.length / 2;
+  const iterations = coldStart ? 300 : 90;
+  let temperature = coldStart ? Math.min(width, height) / 5 : k / 4;
+  const cooling = temperature / (iterations + 1);
+  const short = Math.min(width, height);
+  const pull = { x: (GRAVITY * k * short) / width, y: (GRAVITY * k * short) / height };
+  const ids = nodes.map((node) => node.id);
+  for (let step = 0; step < iterations; step += 1) {
+    const moves = new Map(ids.map((id) => [id, { x: 0, y: 0 }]));
+    for (let a = 0; a < ids.length; a += 1) {
+      const pa = position.get(ids[a] as string) as { x: number; y: number };
+      const ma = moves.get(ids[a] as string) as { x: number; y: number };
+      for (let b = a + 1; b < ids.length; b += 1) {
+        const pb = position.get(ids[b] as string) as { x: number; y: number };
+        const mb = moves.get(ids[b] as string) as { x: number; y: number };
+        const dx = pa.x - pb.x || (random() - 0.5) * 0.01;
+        const dy = pa.y - pb.y || (random() - 0.5) * 0.01;
+        const distance = Math.max(0.5, Math.hypot(dx, dy));
+        const force = (k * k) / distance;
+        ma.x += (dx / distance) * force;
+        ma.y += (dy / distance) * force;
+        mb.x -= (dx / distance) * force;
+        mb.y -= (dy / distance) * force;
+      }
+    }
+    for (const edge of graph.edges) {
+      const pa = position.get(edge.from);
+      const pb = position.get(edge.to);
+      if (!pa || !pb) continue;
+      const spring = SPRINGS[edge.kind];
+      const dx = pa.x - pb.x;
+      const dy = pa.y - pb.y;
+      const distance = Math.max(0.5, Math.hypot(dx, dy));
+      const force = (spring.weight * distance * distance) / (k * spring.length);
+      const ma = moves.get(edge.from) as { x: number; y: number };
+      const mb = moves.get(edge.to) as { x: number; y: number };
+      ma.x -= (dx / distance) * force;
+      ma.y -= (dy / distance) * force;
+      mb.x += (dx / distance) * force;
+      mb.y += (dy / distance) * force;
+    }
+    const middles = new Map<string, { x: number; y: number; count: number }>();
+    for (const node of nodes) {
+      if (!node.folder) continue;
+      const point = position.get(node.id) as { x: number; y: number };
+      const sum = middles.get(node.folder) ?? { x: 0, y: 0, count: 0 };
+      middles.set(node.folder, { x: sum.x + point.x, y: sum.y + point.y, count: sum.count + 1 });
+    }
+    for (const node of nodes) {
+      if (node.id === graph.root) continue;
+      const point = position.get(node.id) as { x: number; y: number };
+      const move = moves.get(node.id) as { x: number; y: number };
+      move.x += (center.x - point.x) * pull.x;
+      move.y += (center.y - point.y) * pull.y;
+      const middle = node.folder ? middles.get(node.folder) : undefined;
+      if (middle && middle.count > 1) {
+        const dx = middle.x / middle.count - point.x;
+        const dy = middle.y / middle.count - point.y;
+        const distance = Math.hypot(dx, dy);
+        move.x += (dx * distance * COHESION) / k;
+        move.y += (dy * distance * COHESION) / k;
+      }
+      const home = coldStart ? undefined : previous.get(node.id);
+      if (home) {
+        move.x += (home.x - point.x) * ANCHOR;
+        move.y += (home.y - point.y) * ANCHOR;
+      }
+      const length = Math.max(0.01, Math.hypot(move.x, move.y));
+      const limit = Math.min(length, temperature);
+      position.set(node.id, clamp(point.x + (move.x / length) * limit, point.y + (move.y / length) * limit));
+    }
+    temperature = Math.max(0.5, temperature - cooling);
+  }
+  return new Map(
+    nodes.map((node) => {
+      const point = position.get(node.id) as { x: number; y: number };
+      return [node.id, { ...point, side: node.kind === "file" ? sideOf(point, center) : "below" }];
+    }),
+  );
+}
+
+/** Where each folder's files gather, for folders with enough files to name. */
+export function folderCenters(graph: Graph, positions: ReadonlyMap<string, { x: number; y: number }>, minimum = 3) {
+  const sums = new Map<string, { x: number; y: number; top: number; count: number }>();
+  for (const node of graph.nodes) {
+    const at = node.folder ? positions.get(node.id) : undefined;
+    if (!at || !node.folder) continue;
+    const sum = sums.get(node.folder) ?? { x: 0, y: 0, top: Number.POSITIVE_INFINITY, count: 0 };
+    sums.set(node.folder, { x: sum.x + at.x, y: sum.y + at.y, top: Math.min(sum.top, at.y), count: sum.count + 1 });
+  }
+  return [...sums.entries()]
+    .filter(([, sum]) => sum.count >= minimum)
+    .map(([folder, sum]) => ({ folder, x: sum.x / sum.count, y: sum.y / sum.count, top: sum.top, count: sum.count }));
+}

package/shared/links.ts

@@ -0,0 +1,252 @@
+// Links between repository files, for the Linear Live graph: code imports in common languages,
+// links in Markdown, HTML, and CSS, entry points in package files, and repo paths named in
+// config and scripts. Pure: the daemon reads the files and checks which candidates exist.
+
+export type LinkKind = "import" | "link" | "mention";
+
+export interface FileLink {
+  from: string;
+  to: string;
+  kind: LinkKind;
+}
+
+/** A reference found in a file, with the repo paths it may point to, best first. */
+export interface Reference {
+  kind: LinkKind;
+  candidates: string[];
+}
+
+export interface LinkContext {
+  /** Path aliases from tsconfig or jsconfig, such as "@/" to "src/". */
+  aliases: readonly { prefix: string; targets: readonly string[] }[];
+  /** Workspace packages by name, with their folder and entry file. */
+  packages: ReadonlyMap<string, { dir: string; entry: string | null }>;
+  /** The module path from go.mod. */
+  goModule: string | null;
+}
+
+export const EMPTY_CONTEXT: LinkContext = { aliases: [], packages: new Map(), goModule: null };
+
+const SCRIPT_EXTENSIONS = [".ts", ".tsx", ".d.ts", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".json", ".vue", ".svelte"];
+/** A Go import names a package folder; this suffix asks the daemon for the folder's Go files. */
+export const GO_PACKAGE = "/*.go";
+
+function extension(file: string): string {
+  const name = file.split("/").pop() ?? file;
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot).toLowerCase() : "";
+}
+
+function dirname(file: string): string {
+  const index = file.lastIndexOf("/");
+  return index < 0 ? "" : file.slice(0, index);
+}
+
+/** Joins and normalizes a repo path; null when it leaves the repository. */
+export function joinPath(base: string, target: string): string | null {
+  const parts: string[] = [];
+  for (const part of `${base}/${target}`.split("/")) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      if (parts.length === 0) return null;
+      parts.pop();
+    } else parts.push(part);
+  }
+  return parts.length ? parts.join("/") : null;
+}
+
+function all(pattern: RegExp, text: string, group = 1): string[] {
+  return [...text.matchAll(pattern)].map((match) => match[group] ?? "").filter(Boolean);
+}
+
+// A script specifier may leave out the extension, name a folder with an index file, or name
+// the .js file that a .ts file compiles to.
+function scriptCandidates(base: string): string[] {
+  const list = [base, ...SCRIPT_EXTENSIONS.map((ext) => base + ext), ...SCRIPT_EXTENSIONS.map((ext) => `${base}/index${ext}`)];
+  const compiled = /\.(m|c)?jsx?$/.exec(base);
+  if (compiled) {
+    const stem = base.slice(0, -compiled[0].length);
+    list.unshift(`${stem}.ts`, `${stem}.tsx`, `${stem}.${compiled[1] ?? ""}ts`);
+  }
+  return list;
+}
+
+function scriptSpecifier(from: string, spec: string, context: LinkContext): string[] {
+  if (spec.startsWith(".")) {
+    const base = joinPath(dirname(from), spec);
+    return base ? scriptCandidates(base) : [];
+  }
+  for (const alias of context.aliases) {
+    if (!spec.startsWith(alias.prefix)) continue;
+    return alias.targets.flatMap((target) => {
+      const base = joinPath(target, spec.slice(alias.prefix.length));
+      return base ? scriptCandidates(base) : [];
+    });
+  }
+  for (const [name, pkg] of context.packages) {
+    if (spec === name && pkg.entry) return scriptCandidates(pkg.entry);
+    if (spec.startsWith(`${name}/`)) {
+      const base = joinPath(pkg.dir, spec.slice(name.length + 1));
+      return base ? [...scriptCandidates(base), ...scriptCandidates(joinPath(pkg.dir, `src/${spec.slice(name.length + 1)}`) ?? base)] : [];
+    }
+  }
+  return [];
+}
+
+function scriptImports(text: string): string[] {
+  return [
+    ...all(/\b(?:import|export)\s+(?:type\s+)?[^'"`;]*?\bfrom\s*["']([^"']+)["']/g, text),
+    ...all(/\bimport\s*["']([^"']+)["']/g, text),
+    ...all(/\b(?:require|import)\s*\(\s*["']([^"']+)["']\s*\)/g, text),
+  ];
+}
+
+function pythonImports(from: string, text: string): string[][] {
+  const results: string[][] = [];
+  const module = (base: string, name: string) => {
+    const stem = joinPath(base, name.replace(/\./g, "/"));
+    return stem ? [`${stem}.py`, `${stem}.pyi`, `${stem}/__init__.py`] : [];
+  };
+  for (const match of text.matchAll(/^\s*from\s+(\.*)([\w.]*)\s+import\s+([\w*, ()]+)/gm)) {
+    const [, dots = "", name = "", names = ""] = match;
+    if (dots) {
+      let base = dirname(from);
+      for (let level = 1; level < dots.length; level += 1) base = dirname(base);
+      if (name) results.push(module(base, name));
+      else for (const item of names.replace(/[()]/g, "").split(",")) results.push(module(base, item.trim()));
+    } else results.push([...module("", name), ...module("src", name)]);
+  }
+  for (const match of text.matchAll(/^\s*import\s+([\w.]+(?:\s*,\s*[\w.]+)*)/gm)) {
+    for (const name of (match[1] ?? "").split(",")) results.push([...module("", name.trim()), ...module("src", name.trim())]);
+  }
+  return results;
+}
+
+function goImports(text: string, context: LinkContext): string[][] {
+  if (!context.goModule) return [];
+  const prefix = `${context.goModule}/`;
+  const specs = [...all(/^\s*import\s+(?:\w+\s+)?"([^"]+)"/gm, text)];
+  for (const block of all(/^\s*import\s*\(([\s\S]*?)\)/gm, text)) specs.push(...all(/"([^"]+)"/g, block));
+  return specs.filter((spec) => spec.startsWith(prefix)).map((spec) => [`${spec.slice(prefix.length)}${GO_PACKAGE}`]);
+}
+
+function rustImports(from: string, text: string): string[][] {
+  const name = from.split("/").pop() ?? "";
+  const own = /^(mod|lib|main)\.rs$/.test(name) ? dirname(from) : joinPath(dirname(from), name.replace(/\.rs$/, ""));
+  const results = all(/^\s*(?:pub\s+)?mod\s+(\w+)\s*;/gm, text).map((mod) => [`${own ?? ""}/${mod}.rs`, `${own ?? ""}/${mod}/mod.rs`].map((file) => file.replace(/^\//, "")));
+  for (const spec of all(/^\s*(?:pub\s+)?use\s+crate::([\w:]+)/gm, text)) {
+    const parts = spec.split("::");
+    for (let size = parts.length; size > 0; size -= 1) {
+      const stem = `src/${parts.slice(0, size).join("/")}`;
+      results.push([`${stem}.rs`, `${stem}/mod.rs`]);
+    }
+  }
+  return results;
+}
+
+// Repo paths named in config, scripts, and prose: a word with a slash and an extension, or a
+// relative path. Each is tried from the file's folder and from the repository root.
+function mentions(from: string, text: string): string[][] {
+  const words = all(/(?:^|[\s"'`(=:,[])((?:\.{1,2}\/)?[\w@.-]+(?:\/[\w@.-]+)+\.[A-Za-z][\w]{0,7})(?=$|[\s"'`),:;\]#?])/gm, text);
+  return [...new Set(words)].map((word) => {
+    const local = joinPath(dirname(from), word);
+    const rooted = word.startsWith(".") ? null : joinPath("", word);
+    return [local, rooted].filter((candidate): candidate is string => candidate !== null);
+  });
+}
+
+function markdownLinks(from: string, text: string): string[][] {
+  return all(/\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g, text)
+    .map((target) => target.split("#")[0] ?? "")
+    .filter((target) => target && !/^[a-z][\w+.-]*:/i.test(target))
+    .map((target) => {
+      const resolved = target.startsWith("/") ? joinPath("", target) : joinPath(dirname(from), decodeURI(target));
+      return resolved ? [resolved, `${resolved}/README.md`] : [];
+    });
+}
+
+function packageEntries(from: string, text: string): string[][] {
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    return [];
+  }
+  const strings: string[] = [];
+  const collect = (value: unknown) => {
+    if (typeof value === "string") strings.push(value);
+    else if (value && typeof value === "object") for (const inner of Object.values(value)) collect(inner);
+  };
+  for (const key of ["main", "module", "types", "typings", "bin", "exports", "browser"]) collect(pkg[key]);
+  const dir = dirname(from);
+  const entries = strings.filter((value) => /^\.?\.?\/?[\w@.-]/.test(value) && !value.includes("*"));
+  const scripts = mentions(from, Object.values((pkg.scripts as Record<string, string>) ?? {}).join("\n"));
+  return [...entries.map((value) => [joinPath(dir, value)].filter((entry): entry is string => entry !== null)), ...scripts];
+}
+
+/** The references in one file, with candidate paths for each. */
+export function fileReferences(from: string, text: string, context: LinkContext = EMPTY_CONTEXT): Reference[] {
+  const ext = extension(from);
+  const name = from.split("/").pop() ?? "";
+  const refs: Reference[] = [];
+  const add = (kind: LinkKind, lists: string[][]) => {
+    for (const candidates of lists) if (candidates.length) refs.push({ kind, candidates });
+  };
+  if ([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".vue", ".svelte", ".astro"].includes(ext)) {
+    add("import", scriptImports(text).map((spec) => scriptSpecifier(from, spec, context)));
+  } else if (ext === ".py" || ext === ".pyi") add("import", pythonImports(from, text));
+  else if (ext === ".go") add("import", goImports(text, context));
+  else if (ext === ".rs") add("import", rustImports(from, text));
+  else if (ext === ".rb") {
+    add("import", all(/\brequire_relative\s*\(?\s*["']([^"']+)["']/g, text).map((spec) => {
+      const base = joinPath(dirname(from), spec);
+      return base ? [base.endsWith(".rb") ? base : `${base}.rb`] : [];
+    }));
+  } else if ([".css", ".scss", ".sass", ".less"].includes(ext)) {
+    add("link", all(/@(?:import|use|forward)\s+(?:url\()?["']([^"']+)["']/g, text).map((spec) => {
+      const base = joinPath(dirname(from), spec);
+      if (!base) return [];
+      const partial = `${dirname(base)}/_${base.split("/").pop()}`.replace(/^\//, "");
+      return [base, `${base}.css`, `${base}.scss`, `${partial}.scss`, `${base}.less`];
+    }));
+  } else if (ext === ".md" || ext === ".mdx") add("link", markdownLinks(from, text));
+  else if (ext === ".html" || ext === ".htm") {
+    add("link", all(/\b(?:src|href)\s*=\s*["']([^"'#?]+)["']/g, text)
+      .filter((target) => !/^[a-z][\w+.-]*:|^\/\//i.test(target))
+      .map((target) => [joinPath(target.startsWith("/") ? "" : dirname(from), target)].filter((value): value is string => value !== null)));
+  } else if (name === "package.json") add("link", packageEntries(from, text));
+  else if (/^[tj]sconfig(\..+)?\.json$/.test(name)) {
+    add("link", all(/"extends"\s*:\s*"(\.[^"]+)"/g, text).map((spec) => {
+      const base = joinPath(dirname(from), spec);
+      return base ? [base, `${base}.json`] : [];
+    }));
+  }
+  // Every text file can name repo paths, as a workflow names the script it runs.
+  add("mention", mentions(from, text));
+  return refs;
+}
+
+/** Reads tsconfig paths, such as {"@/*": ["./src/*"]}, as prefix aliases. */
+export function aliasesFrom(config: unknown, configDir = ""): LinkContext["aliases"] {
+  const options = (config as { compilerOptions?: { baseUrl?: string; paths?: Record<string, string[]> } })?.compilerOptions;
+  const base = joinPath(configDir, options?.baseUrl ?? ".") ?? "";
+  return Object.entries(options?.paths ?? {}).flatMap(([pattern, targets]) => {
+    if (!pattern.endsWith("*") || !Array.isArray(targets)) return [];
+    const resolved = targets
+      .filter((target) => typeof target === "string" && target.endsWith("*"))
+      .map((target) => joinPath(base, target.slice(0, -1)) ?? "");
+    return [{ prefix: pattern.slice(0, -1), targets: resolved }];
+  });
+}
+
+/** Strips comments and trailing commas, which tsconfig files allow. */
+export function parseLooseJson(text: string): unknown {
+  const clean = text
+    .replace(/("(?:[^"\\]|\\.)*")|\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (match, string: string | undefined) => string ?? "")
+    .replace(/,(\s*[}\]])/g, "$1");
+  try {
+    return JSON.parse(clean);
+  } catch {
+    return null;
+  }
+}