Function buildSteps

src/ui-server/api/steps.ts:397–1487

(cg: CodeGraph, projectRoot: string, query: URLSearchParams)

}

export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLSearchParams): Promise<WireStepsPayload> {
  const started = Date.now();
  const depthCap = intParam(query, 'depth', { min: 1, max: MAX_DEPTH, default: DEFAULT_DEPTH });
  const limit = intParam(query, 'limit', { min: 20, max: MAX_LIMIT, default: DEFAULT_LIMIT });
  const through = query.get('through') === '1';
  const stats = cg.getStats();
  const index = { lastIndexedAt: cg.getLastIndexedAt() ?? null, edges: stats.edgeCount, files: stats.fileCount };

  const { anchor, ambiguous } = resolveAnchor(cg, query);

  // Route → where its code starts: the handler a resolver named, the page a
  // screen file exports, or the route itself standing in for an inline
  // handler (`route-roots.ts`) — and what kind of project this is, for the
  // words the viewer uses.
  const routes = cg.getNodesByKind('route');
  const roots = routeRoots(cg, routes);
  const project = projectKind(routes, stats.edgesByKind?.navigates ?? 0);

  const reader = createSiteReader(cg, projectRoot, MAX_WHEN_SITES);
  const calls = createSiteReader(cg, projectRoot, MAX_CALL_SITES);
  /** The conditions a site runs under, structured — one read, joined where a string is wanted. */
  const guardsAt = (caller: Node, site: { line?: number; column?: number }) => reader.guards(caller, site);
  /** The loops a site is written inside — a run of calls that happens once per item. */
  const loopsAt = (caller: Node, site: { line?: number; column?: number }) => reader.loops(caller, site);
  const argsAt = (caller: Node, site: { line?: number; column?: number }) => reader.args(caller, site);
  const withArgs = async (site: WireStepSite, caller: Node, at: { line?: number; column?: number }): Promise<WireStepSite> => {
    const args = await argsAt(caller, at);
    return args === null ? site : { ...site, args };
  };
  /** The call as written at a site, and what it passes — one read for both. */
  const callAt = (caller: Node, site: { line?: number; column?: number; callee?: string }) => calls.callSite(caller, site);
  /** A hop's position with its call's span and enclosing call, read from the tree; the bare position when unreadable. */
  const hopAt = async (caller: Node, at: { line?: number; column?: number }, callee?: string): Promise<HopSite> => {
    const line = at.line ?? caller.startLine;
    const column = at.column ?? 0;
    const read = at.line ? await callAt(caller, { ...at, ...(callee ? { callee } : {}) }) : null;
    // The read must be THIS call. An inline handler's edges carry the ROUTE's
    // line (`router.post('/users/login', async (req, res) => {`), where the
    // only call is the registration itself — and taking its span would make
    // every call in the handler read as written inside it, and so as running
    // first. A miss is a bare position: no span to nest by, no `within`.
    const last = (n: string) => n.replace(/\([^()]*\)/g, '').split(/[.:]/).pop() ?? n;
    const usable = read !== null && (!callee || last(read.callee) === last(callee));
    if (!usable) return { file: caller.filePath, line, column, end: { line, column }, within: null };
    return {
      file: caller.filePath,
      line: read.span?.start.line ?? line,
      column: read.span?.start.column ?? column,
      end: read.span?.end ?? { line, column },
      within: read.within ?? null,
    };
  };
  const pointHop = (caller: Node, at: { line?: number; column?: number }): HopSite => {
    const line = at.line ?? caller.startLine;
    const column = at.column ?? 0;
    return { file: caller.filePath, line, column, end: { line, column }, within: null };
  };