Function resolveHop

src/ui-server/api/trails.ts:143–203

(cg: CodeGraph, hop: StoredHop)

 * stranger in the middle of somebody's explanation.
 */
export function resolveHop(cg: CodeGraph, hop: StoredHop): WireTrailHop {
  const base = {
    dir: hop.dir,
    name: hop.name,
    qualifiedName: hop.qualifiedName,
    kind: hop.kind,
    savedFile: hop.file,
    savedLine: hop.line,
  };

  const byId = hop.id ? cg.getNode(hop.id) : null;
  if (byId && matches(byId, hop)) {
    return { ...base, status: 'ok', id: byId.id, file: byId.filePath, line: byId.startLine, note: null };
  }

  const candidates = cg
    .getNodesByQualifiedName(hop.qualifiedName)
    .filter((node) => hop.kind === '' || node.kind === hop.kind);

  if (candidates.length === 0) {
    return {
      ...base,
      status: 'missing',
      id: null,
      file: null,
      line: null,
      note: `no longer in the index — moved or renamed since this trail was saved`,
    };
  }

  const sameFile = candidates.filter((node) => node.filePath === hop.file);
  if (sameFile.length === 1) {
    const node = sameFile[0] as Node;
    return { ...base, status: 'ok', id: node.id, file: node.filePath, line: node.startLine, note: null };
  }

  if (candidates.length === 1) {
    const node = candidates[0] as Node;
    return {
      ...base,
      status: 'moved',
      id: node.id,
      file: node.filePath,
      line: node.startLine,
      note: `moved from ${hop.file || 'an unrecorded file'} to ${node.filePath}`,
    };
  }

  // Several symbols carry this name and none of them is where it used to be.
  // The best guess is offered — a row nobody can open is not more honest, it
  // is just less useful — but it is labelled as a guess.
  const pick = (sameFile[0] ?? candidates[0]) as Node;
  return {
    ...base,
    status: 'ambiguous',
    id: pick.id,
    file: pick.filePath,
    line: pick.startLine,