feat(steps): a run of calls that happens once per item says so

A body drawn once, with nothing to say it repeats, is a quiet lie about the
order — so the reading now reads the loops a site is written inside, the same
way it reads its conditions: one climb up the same ancestors, per language,
`for` / `foreach` / `for … in` / `while` / `do` / `repeat`, with the header as
written (`item of items`, `queue.length > 0`) and where the loop starts.

Loops and forks nest in either direction, and neither reading knows about the
other, so the block builder merges them by where each construct BEGINS: on one
ancestor chain the outer one always starts first, which rebuilds the nesting
from the positions alone. A `for` inside an `if` and an `if` inside a `for` come
out the way the code has them.

With it, the per-framework readings are pinned: an Express handler with its
helper drawn inside the reply it builds, a FastAPI `raise HTTPException` ending
the arm it is in, a Spring early `return` as the other arm of its `if` (with
the comparison flipped, not wrapped), an ASP.NET handler's two outcomes, and a
Nest controller read on through the service it delegates to.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01REFyW9hmNrxhwN5wxRoAkC

src/graph/branch-guards.ts

@@ -947,6 +947,114 @@ export async function guardsInSource(
   }
 }
 
+/** Loops for one site in source text — the test seam; production reads files. */
+export async function loopsInSource(source: string, language: Language, line: number, column: number | null = null): Promise<SiteLoop[]> {
+  if (!supportsBranchGuards(language)) return [];
+  const tree = await parse(source, language);
+  if (!tree) return [];
+  try {
+    return loopsInTree(tree.rootNode, source, language, line, column);
+  } finally {
+    tree.delete();
+  }
+}
+
+/** A loop a site is written inside: its header as written, and where the loop starts. */
+export interface SiteLoop {
+  /** `const item of items`, `i = 0; i < n; i++`, `queue.length > 0` — the header, without its keyword. */
+  text: string;
+  /** `each` for a `for` / `foreach` / `for … in`, `while` for a `while` / `do` / `repeat`. */
+  kind: 'each' | 'while';
+  /** Where the loop starts, `line:column` — the same identity a guard's `branch` carries. */
+  branch: string;
+}
+
+/** Loop node types across the grammars with rules here. A type absent yields nothing, never a wrong label. */
+const LOOP_TYPES: ReadonlyMap<string, 'each' | 'while'> = new Map([
+  ['for_statement', 'each'],
+  ['for_in_statement', 'each'],
+  ['for_of_statement', 'each'],
+  ['for_each_statement', 'each'],
+  ['enhanced_for_statement', 'each'],
+  ['foreach_statement', 'each'],
+  ['for_range_loop', 'each'],
+  ['for_expression', 'each'],
+  ['while_statement', 'while'],
+  ['while_expression', 'while'],
+  ['do_statement', 'while'],
+  ['do_while_statement', 'while'],
+  ['repeat_while_statement', 'while'],
+]);
+
+/**
+ * The loops a site is written inside, outermost first — what tells a reading in
+ * the code's order that a run of calls happens once PER ITEM rather than once.
+ * The climb is the guards' climb (the same boundaries, the same transparent
+ * inline functions), so a callback's body is read in its own function and a
+ * `.forEach` body under the loop it is written in.
+ */
+export function loopsInTree(root: SyntaxNode, source: string, language: Language, line: number, column: number | null): SiteLoop[] {
+  const rules = RULES_BY_LANGUAGE.get(language);
+  if (!rules) return [];
+  const row = line - 1;
+  if (row < 0) return [];
+  let col = column ?? 0;
+  if (column === null) {
+    const text = source.split('\n')[row] ?? '';
+    const first = text.search(/\S/);
+    col = first < 0 ? 0 : first;
+  }
+  let node: SyntaxNode | null = innermostAt(root, row, col);
+  if (!node) return [];
+  const found: SiteLoop[] = [];
+  while (node) {
+    const parent: SyntaxNode | null = node.parent;
+    if (!parent || rules.boundaries.has(parent.type)) break;
+    if (rules.inlineFunctions.has(parent.type)) {
+      const holder = parent.parent?.type ?? '';
+      if (rules.bindingParents.has(holder)) break;
+      node = parent;
+      continue;
+    }
+    const kind = LOOP_TYPES.get(parent.type);
+    // The header, not the body: a site is in the loop only when it is under it.
+    if (kind && !isField(parent, 'condition', node) && !isField(parent, 'value', node)) {
+      const text = loopHeader(parent);
+      if (text) found.push({ text, kind, branch: branchKey(parent) });
+    }
+    node = parent;
+  }
+  found.reverse();
+  return found;
+}
+
+/** Loops for many sites in one file, keyed by {@link siteKey}. */
+export async function loopsForFile(absPath: string, language: Language, sites: readonly CallSite[]): Promise<Map<string, SiteLoop[]>> {
+  const out = new Map<string, SiteLoop[]>();
+  if (!supportsBranchGuards(language) || sites.length === 0) return out;
+  const cached = await treeFor(absPath, language);
+  if (!cached) return out;
+  for (const site of sites) {
+    const key = siteKey(site);
+    if (!out.has(key)) out.set(key, loopsInTree(cached.tree.rootNode, cached.source, language, site.line, site.column ?? null));
+  }
+  return out;
+}
+
+/** A loop's header as written, keyword and braces dropped: `item of items`, `queue.length > 0`. */
+function loopHeader(loop: SyntaxNode): string {
+  const body = loop.childForFieldName('body') ?? namedChildren(loop).find((c) => BLOCKISH.has(c.type)) ?? null;
+  const raw = body && body.startIndex > loop.startIndex ? loop.text.slice(0, body.startIndex - loop.startIndex) : loop.text;
+  let text = raw.replace(/\s+/g, ' ').trim();
+  text = text.replace(/^(?:for|foreach|while|do|repeat)\b\s*/i, '');
+  text = text.replace(/[{:]\s*$/, '').trim();
+  const inner = /^\((.*)\)$/s.exec(text);
+  if (inner) text = inner[1]!.trim();
+  // `const item of items` reads as `item of items`; the binding word is noise here.
+  text = text.replace(/^(?:const|let|var|val|final)\s+/, '');
+  return cut(text, 60);
+}
+
 /**
  * The walk. `line` is 1-based, `column` 0-based (null → first non-blank).
  * Returns the guards outermost first — execution order, the way a reader

src/ui-server/api/program.ts

@@ -26,7 +26,7 @@
  * string can never say.
  */
 
-import { guardLabel, type BranchGuard } from '../../graph/branch-guards';
+import { guardLabel, type BranchGuard, type SiteLoop } from '../../graph/branch-guards';
 import type { WireNodeRef } from './wire';
 
 // =============================================================================
@@ -63,7 +63,17 @@ export type WireItem =
    * after this function returns (`later`), or calls started together
    * (`together`).
    */
-  | { kind: 'block'; block: 'inline' | 'loop' | 'later' | 'together'; by?: string; via?: WireNodeRef; within?: string; body: WireBlock; again?: true }
+  | {
+      kind: 'block';
+      block: 'inline' | 'loop' | 'later' | 'together';
+      by?: string;
+      /** For a loop: whether it runs once per item or while a condition holds. */
+      loop?: 'each' | 'while';
+      via?: WireNodeRef;
+      within?: string;
+      body: WireBlock;
+      again?: true;
+    }
   /** Where the reading stopped: a helper that calls itself, or a cap the walk hit. */
   | { kind: 'cut'; why: 'folded' | 'depth' };
 
@@ -91,6 +101,8 @@ export interface ProgramSite {
   within?: string;
   /** The conditions it runs under, outermost first. */
   guards: BranchGuard[];
+  /** The loops it is written inside, outermost first. */
+  loops?: SiteLoop[];
   /** What fires it, when something binds it — a callback runs LATER. */
   trigger?: { kind: string; name: string; of?: string | null };
 }
@@ -151,50 +163,36 @@ function blockFor(input: ProgramInput, fn: string, path: readonly string[], stat
   if (sites.length === 0) return [];
 
   const root: WireBlock = [];
-  /** The forks open at the site being placed, outermost first. */
-  const stack: Array<{ branch: string; fork: Extract<WireItem, { kind: 'fork' }>; armKey: string; arm: WireArm; exit?: WireArmEnd }> = [];
-  const blockAt = (depth: number): WireBlock => (depth === 0 ? root : stack[depth - 1]!.arm.body);
+  /** The constructs open at the site being placed, outermost first. */
+  const stack: Open[] = [];
+  const bodyAt = (depth: number): WireBlock => (depth === 0 ? root : stack[depth - 1]!.body);
 
   for (const site of sites) {
-    const guards = site.guards;
+    const scopes = scopesOf(site);
 
-    // The longest prefix of open forks the site still sits under, arm and all.
+    // The longest run of open constructs the site still sits inside — same
+    // construct AND, for a fork, the same arm of it.
     let keep = 0;
-    while (keep < stack.length && keep < guards.length && stack[keep]!.branch === guards[keep]!.branch && stack[keep]!.armKey === armKey(guards[keep]!)) {
-      keep++;
-    }
-    // The level after it may still be the SAME decision taken the other way —
-    // an `else`, another `case`, the code after an early exit. That keeps the
-    // fork and opens its other arm; anything deeper is closed either way.
-    if (keep < stack.length && keep < guards.length && stack[keep]!.branch === guards[keep]!.branch) {
+    while (keep < stack.length && keep < scopes.length && sameScope(stack[keep]!, scopes[keep]!)) keep++;
+    // The construct after it may still be the SAME decision taken the other
+    // way — an `else`, another `case`, the code after an early exit. That keeps
+    // the fork and opens its other arm; anything deeper is closed either way.
+    const open = stack[keep];
+    const scope = scopes[keep];
+    if (open && scope && open.branch === scope.branch && open.fork && scope.kind === 'guard') {
       stack.length = keep + 1;
-      const open = stack[keep]!;
-      open.armKey = armKey(guards[keep]!);
-      open.arm = armFor(open.fork, guards[keep]!);
+      open.armKey = armKey(scope.guard);
+      open.body = armFor(open.fork, scope.guard).body;
       keep++;
     } else {
       stack.length = keep;
     }
-    for (let i = keep; i < guards.length; i++) {
-      const g = guards[i]!;
-      // The decision as a reader says it, not as the guard stores it: a
-      // disjunction keeps the parentheses that stop `a || b` from reading as
-      // two ways of arriving (`guardLabel` is the one place that decides).
-      const fork: Extract<WireItem, { kind: 'fork' }> = { kind: 'fork', on: guardLabel([{ ...g, negated: false }]), form: formOf(g), arms: [] };
-      // An early exit is a fork whose OTHER arm left before this site could
-      // run: `if (!product) throw` — the throw is written first, so it is the
-      // first arm, and it is empty because nothing in the picture happens there.
-      if (g.form === 'guard' && g.negated) {
-        fork.arms.push({ when: guardLabel([{ ...g, negated: false }]), ends: g.exit ?? 'return', body: [] });
-      }
-      blockAt(i).push(fork);
-      stack.push({ branch: g.branch, fork, armKey: armKey(g), arm: armFor(fork, g) });
-    }
+    for (let i = keep; i < scopes.length; i++) stack.push(openScope(bodyAt(i), scopes[i]!));
 
     const item = itemFor(input, site, path, state);
     if (item !== null) {
       state.items++;
-      place(blockAt(guards.length), item, site);
+      place(bodyAt(scopes.length), item, site);
     }
   }
 
@@ -203,6 +201,66 @@ function blockFor(input: ProgramInput, fn: string, path: readonly string[], stat
   return root;
 }
 
+/** A construct the reading is inside: a loop, or one arm of a fork. */
+interface Open {
+  branch: string;
+  /** Set for a fork; a loop has only its body. */
+  fork?: Extract<WireItem, { kind: 'fork' }>;
+  armKey?: string;
+  /** Where items at this level go. */
+  body: WireBlock;
+}
+
+type Scope = { kind: 'guard'; branch: string; guard: BranchGuard } | { kind: 'loop'; branch: string; loop: SiteLoop };
+
+/**
+ * The constructs a site is written inside, outermost first: its guards and its
+ * loops merged by where each one STARTS. Both were read by the same climb up
+ * the same ancestors, and on one ancestor chain an outer construct always
+ * begins before an inner one — so the positions alone rebuild the nesting,
+ * without either reading having to know about the other.
+ */
+function scopesOf(site: ProgramSite): Scope[] {
+  const guards: Scope[] = site.guards.map((guard) => ({ kind: 'guard' as const, branch: guard.branch, guard }));
+  const loops: Scope[] = (site.loops ?? []).map((loop) => ({ kind: 'loop' as const, branch: loop.branch, loop }));
+  if (loops.length === 0) return guards;
+  return [...guards, ...loops].sort((a, b) => at(a.branch) - at(b.branch) || a.branch.localeCompare(b.branch));
+}
+
+/** A `line:column` branch as one number, for ordering constructs by where they start. */
+function at(branch: string): number {
+  const [line, column] = branch.split(':');
+  return (Number(line) || 0) * 10000 + (Number(column) || 0);
+}
+
+function sameScope(open: Open, scope: Scope): boolean {
+  if (open.branch !== scope.branch) return false;
+  if (scope.kind === 'loop') return !open.fork;
+  return !!open.fork && open.armKey === armKey(scope.guard);
+}
+
+/** Open a construct: a bracketed loop, or a fork with the arm this site is in. */
+function openScope(into: WireBlock, scope: Scope): Open {
+  if (scope.kind === 'loop') {
+    const block: WireItem = { kind: 'block', block: 'loop', by: scope.loop.text, loop: scope.loop.kind, body: [] };
+    into.push(block);
+    return { branch: scope.branch, body: (block as Extract<WireItem, { kind: 'block' }>).body };
+  }
+  const g = scope.guard;
+  // The decision as a reader says it, not as the guard stores it: a
+  // disjunction keeps the parentheses that stop `a || b` from reading as two
+  // ways of arriving (`guardLabel` is the one place that decides).
+  const fork: Extract<WireItem, { kind: 'fork' }> = { kind: 'fork', on: guardLabel([{ ...g, negated: false }]), form: formOf(g), arms: [] };
+  // An early exit is a fork whose OTHER arm left before this site could run:
+  // `if (!product) throw` — the throw is written first, so it is the first arm,
+  // and it is empty because nothing in the picture happens there.
+  if (g.form === 'guard' && g.negated) {
+    fork.arms.push({ when: guardLabel([{ ...g, negated: false }]), ends: g.exit ?? 'return', body: [] });
+  }
+  into.push(fork);
+  return { branch: scope.branch, fork, armKey: armKey(g), body: armFor(fork, g).body };
+}
+
 /** What one recorded site draws as. */
 function itemFor(input: ProgramInput, site: ProgramSite, path: readonly string[], state: Reading): WireItem | null {
   if (site.into) {

src/ui-server/api/steps.ts

@@ -41,7 +41,7 @@ import type CodeGraph from '../../index';
 import type { Edge, Language, Node, UnresolvedReference } from '../../types';
 import { badRequest, intParam, notFound } from './respond';
 import { createSiteReader } from './when';
-import type { BranchGuard, SiteTrigger } from '../../graph/branch-guards';
+import type { BranchGuard, SiteLoop, SiteTrigger } from '../../graph/branch-guards';
 import { buildProgram, type ProgramSite, type WireProgram } from './program';
 import { classifyEffect, implicitResponseStatus, responseStatus, type Effect } from './effects';
 import { guardLabel } from '../../graph/branch-guards';
@@ -383,6 +383,8 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS
   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);
@@ -553,7 +555,8 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS
     hop: HopSite,
     guards: readonly BranchGuard[],
     what: { step?: string; link?: string; into?: string },
-    trigger: WireStepTrigger | null = null
+    trigger: WireStepTrigger | null = null,
+    loops: readonly SiteLoop[] = []
   ): void => {
     let sites = programs.get(fn.id);
     if (!sites) {
@@ -567,6 +570,7 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS
       at: { line: hop.line, column: hop.column, end: hop.end },
       ...(hop.within ? { within: hop.within } : {}),
       guards: [...guards],
+      ...(loops.length > 0 ? { loops: [...loops] } : {}),
       ...(trigger ? { trigger } : {}),
     });
   };
@@ -754,7 +758,7 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS
     if (!target.first) target.first = hop;
     const fired = trigger ?? (await triggerAt(fold.node, at));
     const id = link(step, target, 'effect', fold.chain, [...fold.whens, when], wireSite, null, fired, hop.within);
-    record(fold.node, local, guards, { step: target.id, link: id }, fired);
+    record(fold.node, local, guards, { step: target.id, link: id }, fired, await loopsAt(fold.node, at));
     return true;
   };
 
@@ -1145,7 +1149,7 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS
           const hop = fold.first ?? local;
           if (!to.first) to.first = hop;
           const id = link(step, to, a.linkKind, fold.chain, [...fold.whens, when], site, a.e, a.trigger, hop.within);
-          record(fold.node, local, guards, { step: to.id, link: id }, a.trigger);
+          record(fold.node, local, guards, { step: to.id, link: id }, a.trigger, await loopsAt(fold.node, at));
           if (to.root !== null && !explored.has(to.id)) {
             explored.add(to.id);
             queue.push(to);
@@ -1183,7 +1187,7 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS
               const local = await hopAt(fold.node, at, target.name);
               const hop = fold.first ?? local;
               const id = link(step, known, 'calls', fold.chain, [...fold.whens, guardLabel(guards)], await withArgs(a.site, fold.node, at), e, a.trigger, hop.within);
-              record(fold.node, local, guards, { step: known.id, link: id }, a.trigger);
+              record(fold.node, local, guards, { step: known.id, link: id }, a.trigger, await loopsAt(fold.node, at));
             }
             continue;
           }
@@ -1210,7 +1214,7 @@ export async function buildSteps(cg: CodeGraph, projectRoot: string, query: URLS
           const first = fold.first ?? local;
           // The helper is drawn where it is CALLED: its own records are its
           // body, and this is the site the rail nests them under.
-          record(fold.node, local, guards, { into: target.id }, a.trigger);
+          record(fold.node, local, guards, { into: target.id }, a.trigger, await loopsAt(fold.node, at));
           next.push({ node: target, chain: [...fold.chain, target], whens: [...fold.whens, guardLabel(guards)], first });
         }
       }

src/ui-server/api/when.ts

@@ -19,6 +19,7 @@ import {
   decoratorsForFile,
   guardLabel,
   guardsForFile,
+  loopsForFile,
   memberTypesForFile,
   siteKey,
   supportsBranchGuards,
@@ -26,6 +27,7 @@ import {
   type BranchGuard,
   type CallSiteText,
   type DefinitionDecorators,
+  type SiteLoop,
   type SiteTrigger,
 } from '../../graph/branch-guards';
 import { resolveProjectFile } from '../security';
@@ -106,6 +108,8 @@ export interface SiteReader {
    * What {@link SiteReader.when} joins; empty when unconditional or unreadable.
    */
   guards(caller: { filePath: string; language: Language }, site: { line?: number; column?: number }): Promise<BranchGuard[]>;
+  /** The loops the site is written inside, outermost first — a run of calls that happens once per item. */
+  loops(caller: { filePath: string; language: Language }, site: { line?: number; column?: number }): Promise<SiteLoop[]>;
   /** What the site passes, abbreviated (`'userEmail', values.email`); null when unreadable. '' for an empty list. */
   args(caller: { filePath: string; language: Language }, site: { line?: number; column?: number }): Promise<string | null>;
   /** What fires the site — the JSX prop, `on*` option or runs-later call it is written under; null when nothing binds it. */
@@ -175,6 +179,15 @@ export function createSiteReader(cg: CodeGraph, projectRoot: string, maxSites =
     async when(caller, site) {
       return guardLabel(await guards(caller, site));
     },
+    async loops(caller, site) {
+      // Not counted against the budget: the tree is parsed for the site's
+      // guards anyway, and this is a second climb up the same nodes.
+      if (!site.line || !supportsBranchGuards(caller.language)) return [];
+      const file = resolve(caller);
+      if (!file) return [];
+      const key = { line: site.line, column: typeof site.column === 'number' ? site.column : null };
+      return (await loopsForFile(file.abs, file.language, [key])).get(siteKey(key)) ?? [];
+    },
     async args(caller, site) {
       if (!site.line || sites >= maxSites || !supportsBranchGuards(caller.language)) return null;
       const file = resolve(caller);