@untangle-code/complexity 0.0.0-stage → 0.1.1

package/src/scope-identity.ts

@@ -0,0 +1,240 @@
+/**
+ * Eindeutige Scope-Identitaet fuer die Aggregation (WP-82).
+ *
+ * ## Warum es dieses Modul gibt
+ *
+ * spec.md §16.10 verlangt die Deduplizierung ueber `metrics_scope_id`. Das
+ * setzt voraus, dass diese Id GENAU EINEN Scope bezeichnet. Der Bezeichner,
+ * den die Sprachadapter heute liefern — `SymbolScopeFact.symbolScopeId` — tut
+ * das innerhalb einer Datei NICHT: er wird aus dem qualifizierten Namen plus
+ * einem Ordinal gebildet, das je Elternscope zaehlt. Zwei anonyme Callbacks
+ * unter zwei verschiedenen, ebenfalls anonymen Eltern bekommen damit beide den
+ * qualifizierten Namen `<anonymous>.<anonymous>` und beide das Ordinal 0 —
+ * dieselbe Id fuer zwei verschiedene Scopes. Am eigenen Repo betrifft das rund
+ * ein Fuenftel aller Scopes.
+ *
+ * Die Folge waere nicht nur eine schiefe Summe, sondern stiller Inhaltsverlust
+ * (E4): `aggregate()` verwirft den zweiten Scope als Dublette,
+ * `selectSymbolFacts()` liefert die VEREINIGUNG der Facts beider Scopes, und
+ * `buildSymbolIR()` baut die IR fuer denjenigen, der die interne Map zuletzt
+ * gewonnen hat.
+ *
+ * ## Was dieses Modul tut
+ *
+ * `withUniqueScopeIds()` schreibt einen Facts-Satz auf nachweislich eindeutige
+ * Scope-Ids um: Byte-Range statt Name plus Ordinal. Jede Fact-Zuordnung wird
+ * ueber Byte-Containment neu aufgeloest (der ENGSTE Scope, der die Id des
+ * Facts traegt und dessen Range den Fact enthaelt). Die aufgetretenen
+ * Kollisionen werden GEZAEHLT UND ZURUECKGEGEBEN, nicht stillschweigend
+ * geheilt — wer den Bericht liest, sieht, dass die Adapter-Id das Problem hat,
+ * und nicht nur, dass jemand daran vorbeigearbeitet hat.
+ *
+ * Das ist eine Reparatur an der Datenkante, KEIN Ersatz fuer die Behebung im
+ * Adapter. Sobald `symbolScopeId` je Datei eindeutig ist, bleibt `collisions`
+ * leer und dieses Modul kann entfallen.
+ *
+ * ## Grenze (bewusst, nicht verschwiegen)
+ *
+ * `NodeKindFact` traegt als einzige Fact-Art KEINE `SourceRange` (domain
+ * `analysis.ts`); ihre Zuordnung ist ueber Containment daher nicht
+ * reparierbar. Sie wird auf den ERSTEN Scope mit der jeweiligen Adapter-Id
+ * abgebildet und die Zahl der so behandelten Facts in
+ * `nodeKindsAttributedByFallback` ausgewiesen. Betroffen sind nur die
+ * syntaktischen Metriken (`computeSyntactic`), nicht Cyclomatic/Cognitive.
+ */
+import type {
+  ComplexityFacts,
+  NodeKindFact,
+  RawCall,
+  SourceRange,
+  SymbolScopeFact,
+} from "@untangle-code/domain";
+import { ID_COMPONENT_SEPARATOR, compareCodepoints } from "@untangle-code/domain";
+
+import { containsRange } from "./scope.js";
+
+/** Eine Adapter-Id, die mehr als einen Scope bezeichnet. */
+export interface ScopeIdCollisionV1 {
+  /** Die mehrdeutige `symbolScopeId` aus dem Sprachadapter. */
+  adapterScopeId: string;
+  /** Wie viele verschiedene Scopes sie bezeichnet (>= 2). */
+  scopeCount: number;
+  /** Startzeilen der betroffenen Scopes, aufsteigend — zum Nachschlagen. */
+  startLines: number[];
+}
+
+export interface UniqueScopeIdsResultV1 {
+  /** Facts mit eindeutigen Scope-Ids; sonst strukturgleich zur Eingabe. */
+  facts: ComplexityFacts;
+  /** Aufrufe mit umgeschriebenem `callerScopeId`. */
+  calls: RawCall[];
+  /** Abbildung neue Id -> urspruengliche Adapter-Id, fuer Diagnosen. */
+  originalScopeIds: Map<string, string>;
+  /** Jede mehrdeutige Adapter-Id, nach Codepoints sortiert. Leer heisst: alles war eindeutig. */
+  collisions: ScopeIdCollisionV1[];
+  /** `NodeKindFact`s ohne Range, die per Fallback zugeordnet wurden (siehe Modul-Doku). */
+  nodeKindsAttributedByFallback: number;
+}
+
+interface Rewritten {
+  scope: SymbolScopeFact;
+  uniqueId: string;
+}
+
+/** Byte-Range-basierte, innerhalb einer Datei eindeutige Id. */
+function uniqueIdFor(prefix: string, range: SourceRange): string {
+  return [prefix, "scope", String(range.startByte), String(range.endByte)].join(
+    ID_COMPONENT_SEPARATOR,
+  );
+}
+
+/** Innerster Scope aus `candidates`, dessen Range `range` enthaelt. */
+function innermostOwner(
+  candidates: readonly Rewritten[],
+  range: SourceRange,
+): Rewritten | undefined {
+  let best: Rewritten | undefined;
+  for (const candidate of candidates) {
+    if (!containsRange(candidate.scope.range, range)) continue;
+    if (
+      best === undefined ||
+      candidate.scope.range.endByte - candidate.scope.range.startByte <
+        best.scope.range.endByte - best.scope.range.startByte
+    ) {
+      best = candidate;
+    }
+  }
+  return best;
+}
+
+/**
+ * Schreibt einen Facts-Satz auf eindeutige Scope-Ids um.
+ *
+ * @param facts Facts einer Datei, wie der Sprachadapter sie liefert.
+ * @param calls Rohaufrufe derselben Datei (`extractCalls`); ihr
+ *   `callerScopeId` wird mit umgeschrieben, damit die Rekursionsmarkierung in
+ *   `buildSymbolIR` weiter greift.
+ * @param idPrefix Praefix der neuen Ids, ueblicherweise der repo-relative
+ *   Pfad. Er macht die Ids ueber Dateigrenzen hinweg eindeutig; innerhalb der
+ *   Datei sorgt die Byte-Range dafuer.
+ *
+ * Kann ein Fact ueber Containment keinem Scope zugeordnet werden (er laege
+ * ausserhalb jeder Range seines eigenen Scopes — ein Adapterfehler anderer
+ * Art), bleibt seine Adapter-Id stehen. Die Aggregation sieht dann einen
+ * unbekannten Eltern-Scope und meldet ihn als Invariantenverstoss, statt eine
+ * saubere Zahl vorzutaeuschen.
+ */
+export function withUniqueScopeIds(
+  facts: ComplexityFacts,
+  calls: readonly RawCall[],
+  idPrefix: string,
+): UniqueScopeIdsResultV1 {
+  const rewritten: Rewritten[] = facts.symbolScopes.map((scope) => ({
+    scope,
+    uniqueId: uniqueIdFor(idPrefix, scope.range),
+  }));
+
+  const byAdapterId = new Map<string, Rewritten[]>();
+  for (const entry of rewritten) {
+    const bucket = byAdapterId.get(entry.scope.symbolScopeId) ?? [];
+    bucket.push(entry);
+    byAdapterId.set(entry.scope.symbolScopeId, bucket);
+  }
+
+  const collisions: ScopeIdCollisionV1[] = [];
+  for (const [adapterScopeId, bucket] of byAdapterId) {
+    if (bucket.length < 2) continue;
+    collisions.push({
+      adapterScopeId,
+      scopeCount: bucket.length,
+      startLines: bucket.map((entry) => entry.scope.range.startLine).sort((a, b) => a - b),
+    });
+  }
+  collisions.sort((a, b) => compareCodepoints(a.adapterScopeId, b.adapterScopeId));
+
+  const originalScopeIds = new Map<string, string>();
+  for (const entry of rewritten) originalScopeIds.set(entry.uniqueId, entry.scope.symbolScopeId);
+
+  /** Neue Id fuer einen Fact mit Range. */
+  const resolve = (adapterScopeId: string, range: SourceRange): string => {
+    const bucket = byAdapterId.get(adapterScopeId);
+    if (bucket === undefined || bucket.length === 0) return adapterScopeId;
+    const first = bucket[0] as Rewritten;
+    if (bucket.length === 1) return first.uniqueId;
+    const owner = innermostOwner(bucket, range);
+    return owner === undefined ? adapterScopeId : owner.uniqueId;
+  };
+
+  let nodeKindsAttributedByFallback = 0;
+  const mappedNodeKinds: NodeKindFact[] = facts.nodeKinds.map((fact) => {
+    const bucket = byAdapterId.get(fact.symbolScopeId);
+    if (bucket === undefined || bucket.length === 0) return fact;
+    if (bucket.length > 1) nodeKindsAttributedByFallback++;
+    return { ...fact, symbolScopeId: (bucket[0] as Rewritten).uniqueId };
+  });
+
+  const mappedScopes: SymbolScopeFact[] = rewritten.map((entry) => {
+    const parentAdapterId = entry.scope.parentScopeId;
+    if (parentAdapterId === undefined) {
+      return { ...entry.scope, symbolScopeId: entry.uniqueId };
+    }
+    const parentBucket = byAdapterId.get(parentAdapterId);
+    let parentId: string;
+    if (parentBucket === undefined || parentBucket.length === 0) {
+      parentId = parentAdapterId;
+    } else if (parentBucket.length === 1) {
+      parentId = (parentBucket[0] as Rewritten).uniqueId;
+    } else {
+      const owner = innermostOwner(
+        parentBucket.filter((candidate) => candidate !== entry),
+        entry.scope.range,
+      );
+      parentId = owner === undefined ? parentAdapterId : owner.uniqueId;
+    }
+    return { ...entry.scope, symbolScopeId: entry.uniqueId, parentScopeId: parentId };
+  });
+
+  const nextFacts: ComplexityFacts = {
+    symbolScopes: mappedScopes,
+    decisions: facts.decisions.map((fact) => ({
+      ...fact,
+      symbolScopeId: resolve(fact.symbolScopeId, fact.range),
+    })),
+    nestingEvents: facts.nestingEvents.map((fact) => ({
+      ...fact,
+      symbolScopeId: resolve(fact.symbolScopeId, fact.range),
+    })),
+    operators: facts.operators.map((fact) => ({
+      ...fact,
+      symbolScopeId: resolve(fact.symbolScopeId, fact.range),
+    })),
+    operands: facts.operands.map((fact) => ({
+      ...fact,
+      symbolScopeId: resolve(fact.symbolScopeId, fact.range),
+    })),
+    nodeKinds: mappedNodeKinds,
+    comments: facts.comments,
+    identifiers: facts.identifiers.map((fact) => ({
+      ...fact,
+      symbolScopeId: resolve(fact.symbolScopeId, fact.range),
+    })),
+    literals: facts.literals.map((fact) => ({
+      ...fact,
+      symbolScopeId: resolve(fact.symbolScopeId, fact.range),
+    })),
+    parseDiagnostics: facts.parseDiagnostics,
+  };
+
+  const nextCalls: RawCall[] = calls.map((call) => ({
+    ...call,
+    callerScopeId: resolve(call.callerScopeId, call.range),
+  }));
+
+  return {
+    facts: nextFacts,
+    calls: nextCalls,
+    originalScopeIds,
+    collisions,
+    nodeKindsAttributedByFallback,
+  };
+}

package/src/scope.ts

@@ -0,0 +1,77 @@
+/**
+ * Facts scoping and byte/line utilities shared by every calculator
+ * (architecture.md §15.1). Every calculator is scope-agnostic: it operates on
+ * whatever `ComplexityFacts` it is handed. `selectSymbolFacts` is how a
+ * caller narrows file-level facts down to one symbol's facts before calling
+ * a calculator for `scope: "symbol"`; passing the file's facts unfiltered is
+ * how a caller computes `scope: "file"`.
+ */
+import type { ComplexityFacts, SourceRange } from "@untangle-code/domain";
+
+function byScope<T extends { symbolScopeId: string }>(
+  items: readonly T[],
+  symbolScopeId: string,
+): T[] {
+  return items.filter((item) => item.symbolScopeId === symbolScopeId);
+}
+
+/** True iff `inner` lies fully inside `outer` (byte-interval containment, both inclusive/exclusive per domain convention). */
+export function containsRange(outer: SourceRange, inner: SourceRange): boolean {
+  return outer.startByte <= inner.startByte && inner.endByte <= outer.endByte;
+}
+
+/** True iff `outer` strictly contains `inner` (contains, but is not the identical range). */
+export function strictlyContainsRange(outer: SourceRange, inner: SourceRange): boolean {
+  if (!containsRange(outer, inner)) return false;
+  return outer.startByte !== inner.startByte || outer.endByte !== inner.endByte;
+}
+
+/** Stable identity key for deduplicating facts that reference the same source span. */
+export function rangeKey(range: SourceRange): string {
+  return `${range.startByte}:${range.endByte}`;
+}
+
+/**
+ * Narrows file-level `ComplexityFacts` to the facts belonging to one symbol
+ * scope. Fact kinds that carry `symbolScopeId` (decisions, nestingEvents,
+ * operators, operands, nodeKinds, identifiers, literals) are filtered by
+ * exact id match — a symbol's own facts are attributed directly to it, never
+ * inherited from nested named symbols, which get their own `SymbolScopeFact`
+ * and their own facts (architecture.md §15.1; Untangle decision, see
+ * README "Entscheidungen" #1). `comments` and `parseDiagnostics` carry no
+ * `symbolScopeId` and are instead filtered by byte-range containment inside
+ * the symbol's own range.
+ *
+ * Returns empty fact arrays (rather than throwing) when `symbolScopeId` is
+ * not present in `facts.symbolScopes` — a caller passing a stale id gets an
+ * empty-but-valid `ComplexityFacts`, not a crash.
+ */
+export function selectSymbolFacts(facts: ComplexityFacts, symbolScopeId: string): ComplexityFacts {
+  const symbolScope = facts.symbolScopes.find((s) => s.symbolScopeId === symbolScopeId);
+  const range = symbolScope?.range;
+  return {
+    symbolScopes: facts.symbolScopes.filter((s) => s.symbolScopeId === symbolScopeId),
+    decisions: byScope(facts.decisions, symbolScopeId),
+    nestingEvents: byScope(facts.nestingEvents, symbolScopeId),
+    operators: byScope(facts.operators, symbolScopeId),
+    operands: byScope(facts.operands, symbolScopeId),
+    nodeKinds: byScope(facts.nodeKinds, symbolScopeId),
+    comments: range ? facts.comments.filter((r) => containsRange(range, r)) : [],
+    identifiers: byScope(facts.identifiers, symbolScopeId),
+    literals: byScope(facts.literals, symbolScopeId),
+    parseDiagnostics: range
+      ? facts.parseDiagnostics.filter((d) => containsRange(range, d.range))
+      : [],
+  };
+}
+
+/** Slices `sourceText` by a byte-offset `SourceRange` (UTF-8, per domain convention). */
+export function sliceByRange(sourceText: string, range: SourceRange): string {
+  const buf = Buffer.from(sourceText, "utf8");
+  return buf.subarray(range.startByte, range.endByte).toString("utf8");
+}
+
+/** Splits text into physical lines, normalizing CRLF/CR to LF first. */
+export function splitLines(text: string): string[] {
+  return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+}

package/src/structural.ts

@@ -0,0 +1,132 @@
+/**
+ * StructuralCalculator (spec.md §16.5).
+ *
+ * Facts-derivable metrics are computed directly from `ComplexityFacts` (plus
+ * `sourceText`/`scopeRange` for the line-based ones). Coupling and API-surface
+ * metrics (`fan_in`, `fan_out`, `import_in_degree`, `import_out_degree`,
+ * `afferent_coupling`, `efferent_coupling`, `instability`,
+ * `inheritance_depth`, `public_api_count`) need whole-repository graph/export
+ * knowledge this facts-only package does not have — per the work order they
+ * are accepted as `StructuralExternalInput` and are only ever present in the
+ * output when the caller actually supplies them; they are never defaulted or
+ * guessed (see README "Entscheidungen" #4 for `instability`'s one derived
+ * exception).
+ *
+ * `parameter_count`, `return_count` and `exit_point_count` use a best-effort
+ * node-kind classifier (see `node-kind-heuristics.ts`) since `SymbolScopeFact`
+ * carries no structured parameter list — see README "Entscheidungen" #5 and
+ * `openIssues`.
+ */
+import type { ComplexityFacts, SourceRange } from "@untangle-code/domain";
+
+import { classifyNodeKind } from "./node-kind-heuristics.js";
+import { strictlyContainsRange } from "./scope.js";
+import { classifyLines } from "./text-lines.js";
+import type { MetricsResult, StructuralExternalInput } from "./types.js";
+
+const FUNCTION_KINDS = new Set(["function", "arrow_function", "function_expression"]);
+const METHOD_KINDS = new Set(["method", "constructor"]);
+const CLASS_KINDS = new Set(["class"]);
+const INTERFACE_KINDS = new Set(["interface"]);
+
+function countByScopeKind(facts: ComplexityFacts, kinds: Set<string>): number {
+  return facts.symbolScopes.filter((s) => kinds.has(s.kind.toLowerCase())).length;
+}
+
+/** Interval-nesting depth of `target` among `pool`: 1 + number of other ranges in `pool` that strictly contain it. */
+function nestingDepthOf(target: SourceRange, pool: readonly SourceRange[]): number {
+  let depth = 1;
+  for (const other of pool) {
+    if (other === target) continue;
+    if (strictlyContainsRange(other, target)) depth++;
+  }
+  return depth;
+}
+
+function mean(values: readonly number[]): number {
+  if (values.length === 0) return 0;
+  return values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+
+/**
+ * @param facts Facts already narrowed to the target scope (see `selectSymbolFacts`).
+ * @param sourceText Full original file content (UTF-8) — needed because
+ *   `SourceRange` byte offsets are file-absolute.
+ * @param scopeRange The scope's own range (a `SymbolScopeFact.range` for
+ *   `scope: "symbol"`, or the whole-file range for `scope: "file"`).
+ */
+export function computeStructural(
+  facts: ComplexityFacts,
+  sourceText: string,
+  scopeRange: SourceRange,
+  external: StructuralExternalInput = {},
+  algorithmVersion = "untangle-structural-v1",
+): MetricsResult {
+  const { physicalLoc, commentLines, docLines, blankLines } = classifyLines(
+    sourceText,
+    scopeRange,
+    facts.comments,
+  );
+  const sloc = Math.max(physicalLoc - blankLines.size - commentLines.size, 0);
+
+  const nonContinuationNesting = facts.nestingEvents
+    .filter((n) => !n.continuation)
+    .map((n) => n.range);
+  const nestingDepths = nonContinuationNesting.map((range) =>
+    nestingDepthOf(range, nonContinuationNesting),
+  );
+
+  let parameterCount = 0;
+  let returnCount = 0;
+  let exitPointCount = 0;
+  for (const node of facts.nodeKinds) {
+    const classified = classifyNodeKind(node.kind);
+    if (classified === "parameter") parameterCount++;
+    if (classified === "return") {
+      returnCount++;
+      exitPointCount++;
+    }
+    if (classified === "exit") exitPointCount++;
+  }
+
+  const metrics: Record<string, number> = {
+    physical_loc: physicalLoc,
+    sloc,
+    blank_lines: blankLines.size,
+    comment_lines: commentLines.size,
+    doc_lines: docLines.size,
+    function_count: countByScopeKind(facts, FUNCTION_KINDS),
+    method_count: countByScopeKind(facts, METHOD_KINDS),
+    class_count: countByScopeKind(facts, CLASS_KINDS),
+    interface_count: countByScopeKind(facts, INTERFACE_KINDS),
+    parameter_count: parameterCount,
+    return_count: returnCount,
+    exit_point_count: exitPointCount,
+    max_nesting: nestingDepths.length > 0 ? Math.max(...nestingDepths) : 0,
+    avg_nesting: mean(nestingDepths),
+  };
+
+  if (external.fanIn !== undefined) metrics["fan_in"] = external.fanIn;
+  if (external.fanOut !== undefined) metrics["fan_out"] = external.fanOut;
+  if (external.importInDegree !== undefined) metrics["import_in_degree"] = external.importInDegree;
+  if (external.importOutDegree !== undefined)
+    metrics["import_out_degree"] = external.importOutDegree;
+  if (external.afferentCoupling !== undefined)
+    metrics["afferent_coupling"] = external.afferentCoupling;
+  if (external.efferentCoupling !== undefined)
+    metrics["efferent_coupling"] = external.efferentCoupling;
+  if (external.inheritanceDepth !== undefined)
+    metrics["inheritance_depth"] = external.inheritanceDepth;
+  if (external.publicApiCount !== undefined) metrics["public_api_count"] = external.publicApiCount;
+
+  if (external.instability !== undefined) {
+    metrics["instability"] = external.instability;
+  } else if (external.afferentCoupling !== undefined && external.efferentCoupling !== undefined) {
+    const denom = external.afferentCoupling + external.efferentCoupling;
+    if (denom > 0) {
+      metrics["instability"] = external.efferentCoupling / denom;
+    }
+  }
+
+  return { metrics, algorithmVersion };
+}

package/src/syntactic.ts

@@ -0,0 +1,183 @@
+/**
+ * SyntacticCalculator (spec.md §16.8).
+ *
+ * `ast_node_count`/`ast_max_depth`/`ast_avg_depth`/`node_kind_entropy` and the
+ * construct counters are derived straight from `ComplexityFacts.nodeKinds`
+ * (each entry already carries its own AST depth) and the other typed fact
+ * arrays.
+ *
+ * `ast_branching_factor_avg`/`ast_branching_factor_max` (spec.md §16.8,
+ * "Mindestens") are reconstructed EXACTLY from the `nodeKinds` sequence:
+ * the adapter's single walk emits one `NodeKindFact` per visited node in
+ * DFS PRE-ORDER (that ordering is this calculator's input contract for the
+ * two branching keys; `selectSymbolFacts` filtering preserves it), and in a
+ * pre-order depth sequence every node's parent is the nearest preceding
+ * entry with a smaller depth — so per-node child counts, and from them the
+ * branching factors, follow without any parent pointers. This is the real
+ * AST branching factor, not an approximation (see README "Entscheidungen"
+ * #7); the optional `irRoot` is only used as a fallback when `nodeKinds` is
+ * empty (e.g. hand-built IR fixtures), because the sparse control-flow IR
+ * would otherwise understate branching.
+ */
+import type { ComplexityFacts, ComplexityIRNode, NodeKindFact } from "@untangle-code/domain";
+
+import { frequenciesOf, shannonEntropy } from "./entropy.js";
+import { classifyNodeKind, isAsyncNodeKind, isExceptionNodeKind } from "./node-kind-heuristics.js";
+import { rangeKey } from "./scope.js";
+import type { MetricsResult } from "./types.js";
+
+function mean(values: readonly number[]): number {
+  if (values.length === 0) return 0;
+  return values.reduce((s, v) => s + v, 0) / values.length;
+}
+
+interface BranchingStats {
+  avg: number;
+  max: number;
+}
+
+/**
+ * Exact per-node child counts from a DFS pre-order depth sequence (see the
+ * module doc): a stack of "open" ancestor indices is maintained; each new
+ * node closes every open node with depth >= its own, and the remaining top
+ * (nearest preceding smaller depth) is its parent. Works on scope-filtered
+ * sequences too — a scope's facts form contiguous pre-order fragments whose
+ * missing outer ancestors simply make their subtree roots forest roots, and
+ * child counts then cover exactly the scope's OWN nodes, consistent with
+ * every other metric computed from scope-narrowed facts.
+ */
+function computeBranchingFromPreorderDepths(nodeKinds: readonly NodeKindFact[]): BranchingStats {
+  const childCounts = new Array<number>(nodeKinds.length).fill(0);
+  const openAncestors: number[] = [];
+  for (let i = 0; i < nodeKinds.length; i += 1) {
+    const depth = (nodeKinds[i] as NodeKindFact).depth;
+    while (
+      openAncestors.length > 0 &&
+      (nodeKinds[openAncestors[openAncestors.length - 1] as number] as NodeKindFact).depth >= depth
+    ) {
+      openAncestors.pop();
+    }
+    const parentIndex = openAncestors[openAncestors.length - 1];
+    if (parentIndex !== undefined) {
+      childCounts[parentIndex] = (childCounts[parentIndex] as number) + 1;
+    }
+    openAncestors.push(i);
+  }
+  let max = 0;
+  for (const count of childCounts) {
+    if (count > max) max = count;
+  }
+  return { avg: mean(childCounts), max };
+}
+
+function computeBranching(root: ComplexityIRNode): BranchingStats {
+  const branchCounts: number[] = [];
+  const stack: ComplexityIRNode[] = [root];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (!node) continue;
+    branchCounts.push(node.children.length);
+    for (const child of node.children) stack.push(child);
+  }
+  return {
+    avg: mean(branchCounts),
+    max: branchCounts.length > 0 ? Math.max(...branchCounts) : 0,
+  };
+}
+
+/**
+ * @param facts Facts already narrowed to the target scope.
+ * @param sloc The scope's own SLOC, as computed by `computeStructural` —
+ *   passed in rather than recomputed so `ast_nodes_per_sloc` is consistent
+ *   with the structural snapshot instead of a second, possibly divergent,
+ *   line-scan.
+ * @param irRoot Optional IR subtree for the same scope; only used as the
+ *   branching-factor source when `facts.nodeKinds` is empty (the pre-order
+ *   reconstruction over real node-kind facts is exact and takes precedence).
+ */
+export function computeSyntactic(
+  facts: ComplexityFacts,
+  sloc: number,
+  irRoot?: ComplexityIRNode,
+  algorithmVersion = "untangle-syntactic-v1",
+): MetricsResult {
+  const depths = facts.nodeKinds.map((n) => n.depth);
+  const astNodeCount = facts.nodeKinds.length;
+
+  const controlFlowKeys = new Set<string>();
+  for (const d of facts.decisions) controlFlowKeys.add(rangeKey(d.range));
+  for (const n of facts.nestingEvents) controlFlowKeys.add(rangeKey(n.range));
+  const controlFlowNodeCount = controlFlowKeys.size;
+
+  // Ranged exception constructs (catch clauses) are deduplicated by range,
+  // since adapters may emit both a DecisionFact and a NestingFact for the
+  // same `catch`. Node-kind-only signals (e.g. a bare `throw_statement`,
+  // which carries no dedicated fact type) have no range to dedupe by and are
+  // simply counted in addition.
+  const exceptionRangeKeys = new Set<string>();
+  for (const n of facts.nestingEvents) {
+    if (n.construct === "catch") exceptionRangeKeys.add(rangeKey(n.range));
+  }
+  for (const d of facts.decisions) {
+    if (d.kind === "catch") exceptionRangeKeys.add(rangeKey(d.range));
+  }
+  const throwLikeNodeCount = facts.nodeKinds.filter(
+    (n) => isExceptionNodeKind(n.kind) && !n.kind.toLowerCase().includes("catch"),
+  ).length;
+  const exceptionConstructCount = exceptionRangeKeys.size + throwLikeNodeCount;
+
+  const nodeKindFrequencies = frequenciesOf(facts.nodeKinds, (n) => n.kind);
+
+  const metrics: Record<string, number> = {
+    ast_node_count: astNodeCount,
+    ast_max_depth: depths.length > 0 ? Math.max(...depths) : 0,
+    ast_avg_depth: mean(depths),
+    statement_count: facts.nodeKinds.filter((n) => classifyNodeKind(n.kind) === "statement").length,
+    expression_count: facts.nodeKinds.filter((n) => classifyNodeKind(n.kind) === "expression")
+      .length,
+    declaration_count: facts.nodeKinds.filter((n) => classifyNodeKind(n.kind) === "declaration")
+      .length,
+    control_flow_node_count: controlFlowNodeCount,
+    control_flow_density: astNodeCount > 0 ? controlFlowNodeCount / astNodeCount : 0,
+    lambda_count: facts.nestingEvents.filter((n) => n.construct === "lambda").length,
+    async_construct_count: facts.nodeKinds.filter((n) => isAsyncNodeKind(n.kind)).length,
+    exception_construct_count: exceptionConstructCount,
+    pattern_match_count: facts.decisions.filter((d) => d.kind === "pattern_alternative").length,
+    node_kind_entropy: shannonEntropy(nodeKindFrequencies.values()),
+    ast_nodes_per_sloc: astNodeCount / Math.max(sloc, 1),
+    parse_error_node_count: facts.parseDiagnostics.filter((d) => d.kind === "error_node").length,
+    missing_node_count: facts.parseDiagnostics.filter((d) => d.kind === "missing_node").length,
+    // WP-185: DIE ZWEI ZAHLEN OBEN SIND NICHT DIE GANZE WAHRHEIT.
+    //
+    // `ParseDiagnostic.kind` kennt vier Werte (`error_node`, `missing_node`,
+    // `fallback`, `other`). Die beiden Kennzahlen oben zaehlen genau zwei
+    // davon — und ein Adapter, dessen Parser keine tree-sitter-Fehlerknoten
+    // kennt, meldet seine Syntaxfehler als `"other"`. Gemessen am eigenen
+    // Python-Adapter: eine Datei mit `parseQuality: "partial"` und
+    // `ParseResult.errorNodeCount: 5` erzeugt fuenf Diagnosen der Art
+    // `"other"` — und `parse_error_node_count` stand trotzdem auf 0. Zwei
+    // Zeugen desselben Laufs widersprachen einander, und der, der das Haus
+    // verlaesst, war der falsche. Wer 0 liest, schliesst auf einen heilen
+    // Baum; das ist die Sorte stiller Fehlaussage, die E4 verbietet.
+    //
+    // Die beiden vorhandenen Kennzahlen bleiben unveraendert — sie bedeuten
+    // weiterhin genau, was ihr Name sagt. Ergaenzt werden zwei, die den Rest
+    // sichtbar machen, statt ihn unter einer 0 verschwinden zu lassen.
+    parse_diagnostic_count: facts.parseDiagnostics.length,
+    unclassified_parse_error_count: facts.parseDiagnostics.filter(
+      (d) => d.severity === "error" && d.kind !== "error_node" && d.kind !== "missing_node",
+    ).length,
+  };
+
+  if (facts.nodeKinds.length > 0) {
+    const branching = computeBranchingFromPreorderDepths(facts.nodeKinds);
+    metrics["ast_branching_factor_avg"] = branching.avg;
+    metrics["ast_branching_factor_max"] = branching.max;
+  } else if (irRoot) {
+    const branching = computeBranching(irRoot);
+    metrics["ast_branching_factor_avg"] = branching.avg;
+    metrics["ast_branching_factor_max"] = branching.max;
+  }
+
+  return { metrics, algorithmVersion };
+}