@untangle-code/cli 0.0.0-stage → 0.1.1

package/src/commands/flow/render.ts

@@ -0,0 +1,318 @@
+/**
+ * Die Darstellung des Symbolgraphen — reine Funktionen, kein I/O.
+ *
+ * DIE ZUSAGE DIESER DATEI, in einem Satz: KEINE KANTE OHNE IHRE
+ * AUFLOESUNGSART UND IHRE CONFIDENCE.
+ *
+ * Der Symbolgraph unterscheidet vier Auspraegungen (`exact`, `heuristic`,
+ * `ambiguous`, `unresolved`) und traegt zu jeder eine Confidence mit Basis und
+ * Signalen. Diese Unterschiede sind der eigentliche Wert des Graphen: ein
+ * Aufrufpfad, der ueber eine geratene Namensgleichheit fuehrt, ist eine ANDERE
+ * Aussage als einer ueber einen aufgeloesten Import. Wer beide gleich
+ * darstellt, hat die Information weggeworfen, fuer die der Graph gebaut wurde.
+ *
+ * Deshalb gilt hier zusaetzlich: EINE MEHRDEUTIGE KANTE ZEIGT ALLE
+ * KANDIDATEN, mit ihrem Gewicht. Es wird keiner ausgewaehlt — auch nicht
+ * „der wahrscheinlichste".
+ */
+import type { SkipLedgerEntryV1, SymbolEdgeV1, SymbolNodeV1 } from "@untangle-code/domain";
+import { compareCodepoints } from "@untangle-code/domain";
+import type {
+  AllCallPathsResultV1,
+  CallPathV1,
+  EntryPointSetV1,
+  ImpactResultV1,
+  ShortestCallPathResultV1,
+  SymbolGraphIndex,
+} from "@untangle-code/symbol-graph";
+
+import { describeSymbol } from "./select.js";
+
+/** Kurzform einer Kanten-Confidence: Wert, Basis, Signale. */
+export function describeConfidence(edge: SymbolEdgeV1): string {
+  return (
+    `Confidence ${edge.confidence.value.toFixed(3)} (${edge.confidence.basis}` +
+    `${edge.confidence.signals.length === 0 ? "" : `; ${edge.confidence.signals.join(", ")}`})`
+  );
+}
+
+/**
+ * Eine Kante in einer Zeile — und, wenn sie mehrdeutig oder unaufgeloest ist,
+ * in mehreren.
+ */
+export function describeEdge(edge: SymbolEdgeV1, indent: string): string[] {
+  const lines: string[] = [];
+  const qualifier = edge.toQualifier === undefined ? "" : `${edge.toQualifier}.`;
+  lines.push(
+    `${indent}${edge.kind} "${qualifier}${edge.toName}"  [${edge.resolution}]  ${describeConfidence(edge)}` +
+      (edge.crossRepo ? "  >> crosses a repository boundary" : ""),
+  );
+  if (edge.resolution === "exact" || edge.resolution === "heuristic") {
+    const target = edge.target;
+    if (target !== undefined) {
+      lines.push(`${indent}  -> ${target.qualifiedName}  ${target.filePath}`);
+    }
+  }
+  if (edge.resolution === "ambiguous") {
+    const candidates = [...(edge.candidates ?? [])].sort(
+      (left, right) =>
+        right.weight - left.weight || compareCodepoints(left.symbolId, right.symbolId),
+    );
+    lines.push(`${indent}  AMBIGUOUS: ${String(candidates.length)} candidates; none selected:`);
+    for (const candidate of candidates) {
+      lines.push(
+        `${indent}    ${candidate.weight.toFixed(3)}  ${candidate.qualifiedName}  ${candidate.filePath}`,
+      );
+    }
+  }
+  if (edge.resolution === "unresolved") {
+    lines.push(
+      `${indent}  UNRESOLVED: ${edge.unresolvedReason ?? "no reason given"} — ${edge.unresolvedDetail ?? ""}`.trimEnd(),
+    );
+  }
+  for (const site of edge.sites) {
+    lines.push(`${indent}  Location: ${site.filePath}:${String(site.range.startLine)}`);
+  }
+  if (edge.sites.length === 0 && edge.sitesMissingReason !== undefined) {
+    lines.push(`${indent}  no source location: ${edge.sitesMissingReason}`);
+  }
+  return lines;
+}
+
+/** Ein Aufrufpfad: Knoten, Kanten, und was den Pfad schwaecht. */
+export function renderPath(index: SymbolGraphIndex, path: CallPathV1, title: string): string[] {
+  const lines: string[] = [];
+  lines.push(
+    `${title}  Depth ${String(path.depth)}  Confidence ${path.confidence.toFixed(3)}  ` +
+      `weakest resolution: ${path.weakestResolution}` +
+      (path.containsAmbiguous ? "  INCLUDES AMBIGUOUS EDGES" : ""),
+  );
+  for (let i = 0; i < path.symbolIds.length; i++) {
+    const node = index.node(path.symbolIds[i] as string);
+    lines.push(`  ${node === null ? (path.symbolIds[i] as string) : describeSymbol(node)}`);
+    const edgeId = path.edgeIds[i];
+    if (edgeId === undefined) continue;
+    const edge = index.edge(edgeId);
+    if (edge === null) {
+      lines.push(`    (edge ${edgeId} missing from snapshot)`);
+      continue;
+    }
+    lines.push(...describeEdge(edge, "    "));
+  }
+  return lines;
+}
+
+/**
+ * Der kuerzeste Pfad — oder der benannte Grund, warum es keinen gibt.
+ *
+ * `wallTimeEnforced` ist kein Zierrat: das Zeitbudget der Suche wird nur
+ * geprueft, wenn ihr eine Zeitquelle mitgegeben wurde. Ohne sie steht in
+ * `limits.maxWallTimeMs` eine Zahl, an die sich nichts haelt — und eine
+ * Budgetzeile, die eine nicht durchgesetzte Grenze wie eine durchgesetzte
+ * ausgibt, ist genau die stille Unwahrheit, die E4 verbietet.
+ */
+export function renderShortest(
+  index: SymbolGraphIndex,
+  result: ShortestCallPathResultV1,
+  wallTimeEnforced = true,
+): string[] {
+  const lines: string[] = ["SHORTEST CALL PATH"];
+  if (result.path === null) {
+    lines.push(
+      `  NO PATH: ${result.missReason ?? "no reason given"}` +
+        (result.missDetail === undefined ? "" : ` — ${result.missDetail}`),
+    );
+  } else {
+    lines.push(...renderPath(index, result.path, "  Path"));
+  }
+  if (result.truncated) {
+    lines.push(`  TRUNCATED: ${result.truncationReason ?? "unknown"}; the search was incomplete.`);
+  }
+  lines.push(
+    `  Budgets: maxDepth=${String(result.limits.maxDepth)} maxNodes=${String(result.limits.maxNodes)} ` +
+      `maxEdges=${String(result.limits.maxEdges)} maxWallTimeMs=${String(result.limits.maxWallTimeMs)}` +
+      (wallTimeEnforced
+        ? ""
+        : " (maxWallTimeMs is not enforced: the search deliberately receives no " +
+          "clock, so repeated runs over the same index produce identical output)"),
+  );
+  return lines;
+}
+
+/** Alle Pfade bis Tiefe N — samt der verworfenen, die nie stumm verschwinden. */
+export function renderAllPaths(index: SymbolGraphIndex, result: AllCallPathsResultV1): string[] {
+  const lines: string[] = [`ALL CALL PATHS UP TO DEPTH ${String(result.maxDepth)}`];
+  if (result.paths.length === 0) {
+    lines.push(
+      `  NO PATH: ${result.missReason ?? "no reason given"}` +
+        (result.missDetail === undefined ? "" : ` — ${result.missDetail}`),
+    );
+  }
+  for (let i = 0; i < result.paths.length; i++) {
+    lines.push(...renderPath(index, result.paths[i] as CallPathV1, `  Path ${String(i + 1)}`));
+  }
+  if (result.pathLimitReached) {
+    const count = result.droppedPathCountExact
+      ? String(result.droppedPathCount)
+      : `at least ${String(result.droppedPathCount)}`;
+    lines.push(
+      `  PATH LIMIT REACHED: ${count} additional paths were discarded ` +
+        "(increase the limit with --limit).",
+    );
+  }
+  if (result.truncated) {
+    lines.push(`  TRUNCATED: ${result.truncationReason ?? "unknown"}.`);
+  }
+  lines.push(...renderLedgerEntries(result.skipped, "  "));
+  return lines;
+}
+
+/** Einstiegspunkte — als das, was sie sind: Heuristik mit Belegen. */
+export function renderEntryPoints(set: EntryPointSetV1, limit: number): string[] {
+  const lines: string[] = [
+    `ENTRY POINTS (${String(set.entryPoints.length)}) — heuristic, not a measurement`,
+  ];
+  const sorted = [...set.entryPoints].sort(
+    (left, right) =>
+      right.confidence.value - left.confidence.value ||
+      compareCodepoints(left.filePath, right.filePath) ||
+      compareCodepoints(left.symbolId, right.symbolId),
+  );
+  for (const entry of sorted.slice(0, limit)) {
+    lines.push(
+      `  ${entry.confidence.value.toFixed(3)}  ${entry.qualifiedName}  ${entry.filePath}  ` +
+        `[${entry.kinds.join(", ")}]`,
+    );
+    for (const signal of entry.signals) {
+      lines.push(`      ${signal.kind} (+${signal.weight.toFixed(2)}): ${signal.reason}`);
+    }
+  }
+  if (sorted.length > limit) {
+    lines.push(`  … ${String(sorted.length - limit)} more (increase --limit).`);
+  }
+  const kinds = Object.keys(set.countsByKind).sort(compareCodepoints);
+  lines.push(
+    `  by kind: ${kinds.map((kind) => `${kind} ${String(set.countsByKind[kind as keyof typeof set.countsByKind] ?? 0)}`).join(", ")}`,
+  );
+  return lines;
+}
+
+/** Impact: wer ist betroffen, wie sicher ist das, und was fehlt trotzdem. */
+export function renderImpact(
+  index: SymbolGraphIndex,
+  result: ImpactResultV1,
+  limit: number,
+): string[] {
+  const lines: string[] = [
+    `AFFECTED SYMBOLS (${String(result.affected.length)}) — confidence threshold ${result.minConfidence.toFixed(3)}`,
+  ];
+  const sorted = [...result.affected].sort(
+    (left, right) =>
+      right.confidence - left.confidence ||
+      left.minDepth - right.minDepth ||
+      compareCodepoints(left.symbolId, right.symbolId),
+  );
+  for (const affected of sorted.slice(0, limit)) {
+    lines.push(
+      `  ${affected.confidence.toFixed(3)}  ${affected.qualifiedName}  ${affected.filePath}  ` +
+        `Depth ${String(affected.depth)} (shortest path ${String(affected.minDepth)})  ` +
+        `weakest resolution: ${affected.weakestResolution}` +
+        (affected.throughAmbiguous ? "  VIA AMBIGUOUS EDGE" : ""),
+    );
+    for (const edgeId of affected.viaEdgeIds) {
+      const edge = index.edge(edgeId);
+      if (edge === null) {
+        lines.push(`      (edge ${edgeId} missing from snapshot)`);
+        continue;
+      }
+      lines.push(...describeEdge(edge, "      "));
+    }
+  }
+  if (sorted.length > limit) {
+    lines.push(`  … ${String(sorted.length - limit)} more (increase --limit).`);
+  }
+  lines.push(
+    `  Ambiguous edges involved: ${result.containsAmbiguousEdges ? `yes (${String(result.ambiguousEdgeIds.length)})` : "no"}`,
+  );
+  if (result.traversal.truncated) {
+    lines.push(
+      `  TRUNCATED: ${result.traversal.truncationReason ?? "unknown"}; the result is incomplete.`,
+    );
+  }
+  lines.push(...renderLedgerEntries(result.skipped, "  "));
+  return lines;
+}
+
+/** Was ein Symbol ruft und wer es ruft — jede Kante mit Art und Confidence. */
+export function renderSymbolOverview(index: SymbolGraphIndex, node: SymbolNodeV1): string[] {
+  const lines: string[] = [];
+  lines.push(`Symbol  ${describeSymbol(node)}`);
+  lines.push(
+    `  Repository ${node.repoId}  Lines ${String(node.startLine)}-${String(node.endLine)}  ` +
+      `incoming ${String(index.inDegree(node.id))}, outgoing ${String(index.outDegree(node.id))}`,
+  );
+  lines.push("");
+
+  const outgoing = index.outgoingEdges(node.id);
+  lines.push(`CALLEES (${String(outgoing.length)} edges, including unresolved edges)`);
+  if (outgoing.length === 0) lines.push("  (none)");
+  for (const edge of outgoing) {
+    lines.push(...describeEdge(edge, "  "));
+  }
+  lines.push("");
+
+  const callers = index.callers(node.id);
+  lines.push(`CALLERS (${String(callers.length)} bindings)`);
+  if (callers.length === 0) {
+    lines.push("  (no callers in the index; this may be an entry point, see --entry-points)");
+  }
+  for (const binding of callers) {
+    const caller = index.node(binding.symbolId);
+    lines.push(
+      `  ${binding.weight.toFixed(3)}  [${binding.resolution}${binding.ambiguous ? ", ambiguous" : ""}]  ` +
+        `${caller === null ? binding.symbolId : describeSymbol(caller)}`,
+    );
+  }
+  return lines;
+}
+
+/** Ledger-Eintraege: jede Auslassung mit Grund (E4). */
+export function renderLedgerEntries(
+  entries: readonly SkipLedgerEntryV1[],
+  indent: string,
+): string[] {
+  if (entries.length === 0) return [];
+  const lines: string[] = [`${indent}SKIPPED (${String(entries.length)}):`];
+  for (const entry of entries) {
+    lines.push(
+      `${indent}  ${entry.subjectId ?? entry.path ?? "(no item)"}  ${entry.reason}: ${entry.detail}`,
+    );
+  }
+  return lines;
+}
+
+/** Kennzahlen des Symbolgraphen, als Kopfzeile jeder Ausgabe. */
+export function renderSymbolGraphHeader(
+  index: SymbolGraphIndex,
+  generationId: string,
+  ledgerInShard: boolean,
+): string[] {
+  const metrics = index.graph.metrics;
+  const lines: string[] = [];
+  lines.push(`Symbol graph  Generation ${generationId}`);
+  lines.push(
+    `  ${String(metrics.nodeCount)} symbols, ${String(metrics.edgeCount)} edges from ${String(metrics.fileCount)} files`,
+  );
+  lines.push(
+    `  Resolution: exact ${(metrics.exactEdgeRate * 100).toFixed(1)} %, ` +
+      `ambiguous ${(metrics.ambiguousEdgeRate * 100).toFixed(1)} %, ` +
+      `unresolved ${(metrics.unresolvedEdgeRate * 100).toFixed(1)} %`,
+  );
+  if (!ledgerInShard) {
+    lines.push(
+      "  Note: the stored shard has no skip ledger; skipped " +
+        "graph-build items appear in the `untangle index` report.",
+    );
+  }
+  return lines;
+}

package/src/commands/flow/select.ts

@@ -0,0 +1,101 @@
+/**
+ * Von einem getippten Symbolnamen zum Knoten des Symbolgraphen.
+ *
+ * DIE REGEL DIESES MODULS IST DIESELBE WIE DIE DES SYMBOLGRAPHEN SELBST: bei
+ * mehreren Kandidaten wird KEINER heimlich gewaehlt. `untangle flow` zeigt
+ * dann alle und verlangt eine Entscheidung. Ein Werkzeug, das hier raet,
+ * beantwortet eine andere Frage als die gestellte — und sagt es nicht.
+ *
+ * Erlaubte Schreibweisen, von der staerksten zur schwaechsten:
+ *   `sym_ab12…`          die Symbol-ID
+ *   `Klasse.methode`     der qualifizierte Name
+ *   `pfad/datei.ts:name` Name in einer bestimmten Datei
+ *   `name`               der blosse Name
+ */
+import type { SymbolNodeV1 } from "@untangle-code/domain";
+import { compareCodepoints } from "@untangle-code/domain";
+
+export type SymbolSelectionV1 =
+  | {
+      status: "found";
+      node: SymbolNodeV1;
+      matchedBy: "symbol_id" | "qualified_name" | "file_and_name" | "name";
+    }
+  | { status: "ambiguous"; candidates: SymbolNodeV1[]; matchedBy: string }
+  | { status: "absent"; near: SymbolNodeV1[] };
+
+function order(left: SymbolNodeV1, right: SymbolNodeV1): number {
+  return (
+    compareCodepoints(left.filePath, right.filePath) ||
+    left.startLine - right.startLine ||
+    compareCodepoints(left.id, right.id)
+  );
+}
+
+/** Beschreibt einen Kandidaten so, dass der Nutzer ihn eindeutig nachtippen kann. */
+export function describeSymbol(node: SymbolNodeV1): string {
+  return `${node.qualifiedName}  ${node.filePath}:${String(node.startLine)}  [${node.kind}]`;
+}
+
+export function selectSymbolNode(nodes: readonly SymbolNodeV1[], query: string): SymbolSelectionV1 {
+  const trimmed = query.trim();
+
+  const byId = nodes.filter((node) => node.id === trimmed);
+  if (byId.length === 1) {
+    return { status: "found", node: byId[0] as SymbolNodeV1, matchedBy: "symbol_id" };
+  }
+
+  const byQualified = nodes.filter((node) => node.qualifiedName === trimmed);
+  if (byQualified.length === 1) {
+    return { status: "found", node: byQualified[0] as SymbolNodeV1, matchedBy: "qualified_name" };
+  }
+  if (byQualified.length > 1) {
+    return {
+      status: "ambiguous",
+      candidates: [...byQualified].sort(order),
+      matchedBy: "qualified_name",
+    };
+  }
+
+  // `pfad/datei.ts:name` — der Doppelpunkt trennt nur, wenn rechts davon kein
+  // Pfadtrenner mehr steht.
+  const separator = trimmed.lastIndexOf(":");
+  if (separator > 0 && !trimmed.slice(separator + 1).includes("/")) {
+    const filePart = trimmed.slice(0, separator).replaceAll("\\", "/");
+    const namePart = trimmed.slice(separator + 1);
+    const inFile = nodes.filter(
+      (node) =>
+        (node.name === namePart || node.qualifiedName === namePart) &&
+        (node.filePath === filePart || node.filePath.endsWith(`/${filePart}`)),
+    );
+    if (inFile.length === 1) {
+      return { status: "found", node: inFile[0] as SymbolNodeV1, matchedBy: "file_and_name" };
+    }
+    if (inFile.length > 1) {
+      return {
+        status: "ambiguous",
+        candidates: [...inFile].sort(order),
+        matchedBy: "file_and_name",
+      };
+    }
+  }
+
+  const byName = nodes.filter((node) => node.name === trimmed);
+  if (byName.length === 1) {
+    return { status: "found", node: byName[0] as SymbolNodeV1, matchedBy: "name" };
+  }
+  if (byName.length > 1) {
+    return { status: "ambiguous", candidates: [...byName].sort(order), matchedBy: "name" };
+  }
+
+  const lowered = trimmed.toLowerCase();
+  const near = nodes
+    .filter(
+      (node) =>
+        node.name.toLowerCase().includes(lowered) ||
+        node.qualifiedName.toLowerCase().includes(lowered),
+    )
+    .sort(order)
+    .slice(0, 10);
+  return { status: "absent", near };
+}

package/src/commands/graph/boundaries-input.ts

@@ -0,0 +1,63 @@
+import * as z from "zod/v4";
+
+/** Repository-relative roots are selectors, never filesystem escape paths. */
+const rootSelector = z
+  .string()
+  .max(4096)
+  .refine(
+    (value) =>
+      value === "" ||
+      (!value.startsWith("/") &&
+          !/[:\\*?[\]{}]/u.test(value) &&
+        value.split("/").every((part) => part !== "" && part !== "." && part !== "..") &&
+        !Array.from(value).some((character) => character.charCodeAt(0) < 32)),
+    "Expected a literal repository-relative directory (empty string selects the repository root).",
+  );
+
+const origin = z
+  .string()
+  .max(4096)
+  .refine((value) => {
+    try {
+      const url = new URL(value);
+      return (
+        ["http:", "https:"].includes(url.protocol) &&
+        !url.username &&
+        !url.password &&
+        url.pathname === "/" &&
+        !url.search &&
+        !url.hash
+      );
+    } catch {
+      return false;
+    }
+  }, "Expected an HTTP(S) origin without credentials, path, query or fragment.");
+
+export const httpServiceBindingSchema = z
+  .object({
+    id: z.string().trim().min(1).max(256),
+    frontendRoots: z.array(rootSelector).min(1).max(32),
+    backendRoots: z.array(rootSelector).min(1).max(32),
+    sameOrigin: z.boolean().optional(),
+    origins: z.array(origin).max(32).optional(),
+  })
+  .strict();
+
+export const httpServiceBindingsSchema = z
+  .array(httpServiceBindingSchema)
+  .max(100)
+  .superRefine((services, ctx) => {
+    const ids = new Set<string>();
+    services.forEach((service, i) => {
+      if (ids.has(service.id))
+        ctx.addIssue({ code: "custom", path: [i, "id"], message: "Service ids must be unique." });
+      ids.add(service.id);
+    });
+  });
+
+export const httpServicesFileSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    services: httpServiceBindingsSchema,
+  })
+  .strict();

package/src/commands/graph/boundaries.ts

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+
+import { analyzeFrontendBoundaries } from "@untangle-code/core";
+import type { HttpServiceBindingV1 } from "@untangle-code/domain";
+
+import { enumFlag, integerFlag, stringFlag, type ParsedArgs } from "../../cli/args.js";
+import type { CommandContext } from "../../cli/command.js";
+import { EXIT, OperationalError, UsageError } from "../../cli/exit.js";
+import { line } from "../../cli/io.js";
+import { loadWorkspace } from "../../cli/workspace.js";
+
+import { httpServicesFileSchema } from "./boundaries-input.js";
+
+interface ServiceControl {
+  path: string;
+  status: "loaded" | "missing";
+  contentHash?: string;
+}
+
+function inside(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative !== ".." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative);
+}
+
+function readServices(
+  root: string,
+  requested: string | undefined,
+): {
+  services: HttpServiceBindingV1[];
+  control: ServiceControl;
+  verify: () => void;
+} {
+  const selected = requested ?? ".untangle/services.json";
+  const candidate = path.resolve(root, selected);
+  if (!inside(root, candidate))
+    throw new UsageError("Service configuration must be inside the project root.");
+  const controlPath = path.relative(root, candidate).split(path.sep).join("/");
+  let physical: string;
+  try {
+    physical = realpathSync(candidate);
+  } catch (error) {
+    if (requested === undefined && (error as NodeJS.ErrnoException).code === "ENOENT") {
+      return {
+        services: [],
+        control: { path: controlPath, status: "missing" },
+        verify: () => {
+          try {
+            realpathSync(candidate);
+          } catch (failure) {
+            if ((failure as NodeJS.ErrnoException).code === "ENOENT") return;
+            throw failure;
+          }
+          throw new OperationalError(
+            "Service configuration appeared during the analysis; repeat it.",
+          );
+        },
+      };
+    }
+    throw new OperationalError("Service configuration could not be read.");
+  }
+  if (!inside(root, physical))
+    throw new UsageError("Service configuration resolves outside the project root.");
+  const stat = statSync(physical);
+  if (!stat.isFile() || stat.size > 1024 * 1024)
+    throw new UsageError("Service configuration must be a regular JSON file no larger than 1 MiB.");
+  const bytes = readFileSync(physical);
+  let raw: unknown;
+  try {
+    raw = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    throw new UsageError("Service configuration is not valid UTF-8 JSON.");
+  }
+  const parsed = httpServicesFileSchema.safeParse(raw);
+  if (!parsed.success)
+    throw new UsageError(
+      "Invalid service configuration: " +
+        parsed.error.issues.map((issue) => issue.path.join(".") + ": " + issue.message).join("; "),
+    );
+  const digest = (value: Uint8Array) => createHash("sha256").update(value).digest("hex");
+  const contentHash = digest(bytes);
+  return {
+    services: parsed.data.services.map((service) => ({
+      id: service.id,
+      frontendRoots: service.frontendRoots,
+      backendRoots: service.backendRoots,
+      ...(service.sameOrigin === undefined ? {} : { sameOrigin: service.sameOrigin }),
+      ...(service.origins === undefined ? {} : { origins: service.origins }),
+    })),
+    control: { path: controlPath, status: "loaded", contentHash },
+    verify: () => {
+      if (realpathSync(candidate) !== physical || digest(readFileSync(physical)) !== contentHash)
+        throw new OperationalError("Service configuration changed during the analysis; repeat it.");
+    },
+  };
+}
+
+export async function runBoundaries(ctx: CommandContext, args: ParsedArgs): Promise<number> {
+  const allowed = new Set(["root", "services", "path", "max-relations", "format"]);
+  for (const flag of Object.keys(args.flags))
+    if (!allowed.has(flag))
+      throw new UsageError(`Option --${flag} is not supported by graph boundaries.`);
+  const format = enumFlag(args, "format", ["text", "json"] as const, "text");
+  const maxRelations = integerFlag(args, "max-relations", 200);
+  if (maxRelations < 1 || maxRelations > 1000)
+    throw new UsageError("--max-relations must be between 1 and 1000.");
+  const rootFlag = stringFlag(args, "root");
+  const workspace = loadWorkspace({
+    cwd: path.resolve(ctx.cwd, rootFlag ?? "."),
+    env: ctx.env,
+    strict: true,
+  });
+  const root = realpathSync(
+    rootFlag === undefined ? workspace.root : path.resolve(ctx.cwd, rootFlag),
+  );
+  const services = readServices(root, stringFlag(args, "services"));
+  const selectedPath = stringFlag(args, "path");
+  if (
+    selectedPath !== undefined &&
+    (!selectedPath ||
+      selectedPath.length > 4096 ||
+      selectedPath.startsWith("/") ||
+        /[:\\*?[\]{}]/u.test(selectedPath) ||
+      selectedPath.split("/").some((part) => !part || part === "." || part === ".."))
+  )
+    throw new UsageError("--path must be one literal repository-relative file path.");
+  const repository = (workspace.config.repositories ?? []).find(
+    (entry) => path.resolve(workspace.load.sources.configBaseDir, entry.path) === root,
+  );
+  const report = await analyzeFrontendBoundaries({
+    root,
+    services: services.services,
+    maxRelations,
+    ...(selectedPath === undefined ? {} : { path: selectedPath }),
+    ...(repository?.exclude === undefined
+      ? {}
+      : { inventoryScope: { additionalDefaultExcludes: repository.exclude } }),
+    signal: ctx.signal,
+  });
+  ctx.signal.throwIfAborted();
+  services.verify();
+  const data = { ...report, servicesManifest: services.control };
+  if (format === "json") line(ctx.io, JSON.stringify(data, null, 2));
+  else {
+    line(
+      ctx.io,
+      `Frontend/backend HTTP dependencies: ${report.status}; sources ${report.freshness.status}`,
+    );
+    line(
+      ctx.io,
+      `${report.http.summary.endpoints} endpoints; ${report.http.summary.requests} requests: ${report.http.summary.resolved} resolved, ${report.http.summary.ambiguous} ambiguous, ${report.http.summary.unresolved} unresolved.`,
+    );
+    for (const request of report.http.requests) {
+      line(
+        ctx.io,
+        `${request.source.path}:${request.source.range.startLine} ${request.method ?? "?"} ${request.path ?? "?"} [${request.status}]`,
+      );
+      for (const target of request.targets) {
+        const route = target.provenance.find((item) => item.kind === "route");
+        line(
+          ctx.io,
+          `  -> ${target.serviceId ?? "unbound"} ${target.handler}${route ? " " + route.path + ":" + route.range.startLine : ""}`,
+        );
+      }
+      if (request.reason) line(ctx.io, "  " + request.reason);
+    }
+    for (const importer of report.importContext.requestImporters)
+      line(
+        ctx.io,
+        `Import context: ${importer.path} -> ${importer.requestPath} (${importer.distance} import edges; no function-call proof)`,
+      );
+    line(
+      ctx.io,
+      `Feature associations: ${report.features.associationCount}; declared dependsOn remains unchanged.`,
+    );
+    if (report.truncation.truncated)
+      line(ctx.io, "Output was truncated; inspect the JSON counts and limits.");
+    for (const limitation of report.limitations) line(ctx.io, "Limit: " + limitation);
+  }
+  return report.freshness.status === "stale" ? EXIT.environment : EXIT.ok;
+}

package/src/commands/graph/bounds.ts

@@ -0,0 +1,25 @@
+/**
+ * Memory-bounded projection of one file's direct edges.
+ *
+ * Persisted snapshots already keep their edges in canonical order. Iterating
+ * that snapshot directly avoids materialising the complete high-degree result
+ * returned by `RestoredFileGraph.edgesFrom` immediately before JSON encoding.
+ * We still count every matching edge so the visible omission count is exact.
+ */
+export function boundDirectEdges<T extends { readonly fromFileId: string }>(
+  candidates: Iterable<T>,
+  fromFileId: string,
+  maxEdges: number,
+): { edges: T[]; truncated: boolean; omittedCount: number } {
+  const edges: T[] = [];
+  let matchingCount = 0;
+
+  for (const edge of candidates) {
+    if (edge.fromFileId !== fromFileId) continue;
+    matchingCount += 1;
+    if (edges.length < maxEdges) edges.push(edge);
+  }
+
+  const omittedCount = matchingCount - edges.length;
+  return { edges, truncated: omittedCount > 0, omittedCount };
+}