@untangle-code/parser-registry 0.0.0-stage → 0.1.1

package/src/languages/shared/call-detection.ts

@@ -0,0 +1,112 @@
+/**
+ * Call-site detection (architecture.md §6.5, spec.md §15.2). No resolution
+ * happens here — that is symbol-graph's job (task instructions, explicit).
+ *
+ * `require(...)` and dynamic `import(...)` are deliberately EXCLUDED here:
+ * they are modeled purely as `RawImport` entries (`import-detection.ts`) so
+ * the symbol-graph does not see the same source construct as both an import
+ * edge and a call edge.
+ */
+import type { RawCall } from "@untangle-code/domain";
+
+import type { FileTextContext } from "./node-utils.js";
+import { rangeOf } from "./node-utils.js";
+import type { SyntaxNode } from "./syntax.js";
+
+function argumentCountOf(node: SyntaxNode): number | undefined {
+  const args = node.childForFieldName("arguments");
+  return args !== null ? args.namedChildCount : undefined;
+}
+
+function isRequireOrDynamicImportCallee(functionNode: SyntaxNode): boolean {
+  return (
+    functionNode.type === "import" ||
+    (functionNode.type === "identifier" && functionNode.text === "require")
+  );
+}
+
+/** Detects a `call_expression` as a `RawCall`, or `null` for require/dynamic-import (see file doc). */
+export function detectCallExpression(
+  node: SyntaxNode,
+  callerScopeId: string,
+  ctx: FileTextContext,
+): RawCall | null {
+  const functionNode = node.childForFieldName("function");
+  if (functionNode === null) return null;
+  if (isRequireOrDynamicImportCallee(functionNode)) return null;
+
+  const range = rangeOf(node, ctx);
+  const argumentCount = argumentCountOf(node);
+
+  if (functionNode.type === "identifier") {
+    return {
+      calleeName: functionNode.text,
+      callerScopeId,
+      range,
+      ...(argumentCount !== undefined ? { argumentCount } : {}),
+    };
+  }
+
+  if (functionNode.type === "member_expression") {
+    const property = functionNode.childForFieldName("property");
+    const object = functionNode.childForFieldName("object");
+    if (property === null) return null;
+    return {
+      calleeName: property.text,
+      ...(object !== null ? { qualifier: object.text } : {}),
+      callerScopeId,
+      range,
+      ...(argumentCount !== undefined ? { argumentCount } : {}),
+    };
+  }
+
+  // Any other callee shape (IIFE, call result invoked again, computed
+  // member, etc.): fall back to the raw written expression text as the
+  // callee name so the call site is not silently dropped.
+  return {
+    calleeName: functionNode.text,
+    callerScopeId,
+    range,
+    ...(argumentCount !== undefined ? { argumentCount } : {}),
+  };
+}
+
+/** Detects a `new_expression` as a `RawCall` (constructor invocation). */
+export function detectNewExpression(
+  node: SyntaxNode,
+  callerScopeId: string,
+  ctx: FileTextContext,
+): RawCall | null {
+  const constructorNode = node.childForFieldName("constructor");
+  if (constructorNode === null) return null;
+  const range = rangeOf(node, ctx);
+  const args = node.childForFieldName("arguments");
+  const argumentCount = args !== null ? args.namedChildCount : undefined;
+
+  if (constructorNode.type === "identifier") {
+    return {
+      calleeName: constructorNode.text,
+      callerScopeId,
+      range,
+      ...(argumentCount !== undefined ? { argumentCount } : {}),
+    };
+  }
+  if (constructorNode.type === "member_expression") {
+    const property = constructorNode.childForFieldName("property");
+    const object = constructorNode.childForFieldName("object");
+    if (property === null) return null;
+    return {
+      calleeName: property.text,
+      ...(object !== null ? { qualifier: object.text } : {}),
+      callerScopeId,
+      range,
+      ...(argumentCount !== undefined ? { argumentCount } : {}),
+    };
+  }
+  return {
+    calleeName: constructorNode.text,
+    callerScopeId,
+    range,
+    ...(argumentCount !== undefined ? { argumentCount } : {}),
+  };
+}

package/src/languages/shared/chunks.ts

@@ -0,0 +1,255 @@
+/**
+ * AstRegion tree construction from the `ScopeNode` tree (spec.md §8.2-§8.3).
+ *
+ * One `AstRegion` of kind `"module"` is returned, spanning the whole file,
+ * with a nested `children` tree the chunker descends into for large symbols
+ * (spec.md §8.3 step 6) — see domain `analysis.ts` `AstRegion.children` doc.
+ *
+ * `ChunkKind` (domain `types/common.ts`, spec.md §8.2) has no `"namespace"`
+ * member; a TS `namespace`/`module` scope maps to `"module"` (documented
+ * WP-06 decision, README "Entscheidungen") since it is itself a nested
+ * module-like grouping of symbols.
+ */
+import type { AstRegion, ChunkKind, SourceRange } from "@untangle-code/domain";
+import { UntangleError } from "@untangle-code/domain";
+
+import type { FileTextContext } from "./node-utils.js";
+import { rangeOf, unionRange } from "./node-utils.js";
+import type { LanguageProfile } from "./profile.js";
+import type { ScopeNode } from "./scope-model.js";
+import type { SyntaxNode } from "./syntax.js";
+
+function chunkKindOf(kind: ScopeNode["kind"]): ChunkKind {
+  switch (kind) {
+    case "function":
+      return "function";
+    case "method":
+      return "method";
+    case "constructor":
+      return "constructor";
+    case "class":
+      return "class_overview";
+    case "interface":
+      return "interface";
+    case "type":
+      return "type";
+    case "enum":
+      return "enum";
+    case "namespace":
+    case "file":
+      return "module";
+    case "property":
+      // Individual properties never reach here directly — see groupProperties.
+      return "property_group";
+  }
+}
+
+/**
+ * The full source span a symbol's chunk should carry: the scope node itself,
+ * widened to the wrapping `export` statement (`export function f ...` —
+ * the scope node is only the declaration, but the `export` keyword bytes
+ * belong to the symbol's chunk, not to an interstitial module gap) and to
+ * the bound doc/decorator range (spec.md §8.3 step 2).
+ */
+function ownRange(scope: ScopeNode, ctx: FileTextContext, profile: LanguageProfile): SourceRange {
+  let range = scope.range;
+  const parent = scope.node.parent;
+  if (parent !== null && profile.exportWrapperKinds.has(parent.type)) {
+    range = unionRange(rangeOf(parent, ctx), range);
+  }
+  return scope.docRange !== undefined ? unionRange(scope.docRange, range) : range;
+}
+
+/**
+ * Regionen fuer Inhalt, der KEINEN Scope oeffnet, aber Bytes traegt (JS/TS:
+ * `static { ... }` im Klassenrumpf). Welche Knoten das sind, weiss das
+ * Sprachprofil, nicht diese Datei — sonst stuende hier je Sprache eine weitere
+ * verdrahtete Knotenart. Ohne diese Regionen fielen ihre Bytes durch den
+ * Mitgliederlauf; spec.md §8.4 verbietet genau das (kein stiller Datenverlust).
+ */
+function extraMemberRegions(
+  scopeNode: SyntaxNode,
+  parentScopeId: string,
+  ctx: FileTextContext,
+  profile: LanguageProfile,
+): AstRegion[] {
+  return profile.memberRegions(scopeNode, parentScopeId, ctx).map((member) => ({
+    chunkKind: "property_group" as const,
+    range: member.range,
+    scopeId: member.scopeId,
+    headerText: member.headerText,
+    splittable: false,
+  }));
+}
+
+function toRegion(
+  scope: ScopeNode,
+  groupOrdinal: { next: number },
+  ctx: FileTextContext,
+  profile: LanguageProfile,
+): AstRegion {
+  let children = buildChildRegions(scope.children, scope.scopeId, groupOrdinal, ctx, profile);
+  if (scope.kind === "class") {
+    const extras = extraMemberRegions(scope.node, scope.scopeId, ctx, profile);
+    if (extras.length > 0) {
+      children = [...children, ...extras].sort((a, b) => a.range.startByte - b.range.startByte);
+    }
+  }
+  const headerText = scope.signature ?? scope.normalizedSignature;
+  return {
+    chunkKind: chunkKindOf(scope.kind),
+    range: ownRange(scope, ctx, profile),
+    scopeId: scope.scopeId,
+    ...(scope.qualifiedName.length > 0 ? { symbolFqn: scope.qualifiedName } : {}),
+    ...(headerText !== undefined && headerText.length > 0 ? { headerText } : {}),
+    splittable: children.length > 0,
+    ...(children.length > 0 ? { children } : {}),
+  };
+}
+
+/**
+ * Exported (in addition to being called from {@link buildChildRegions})
+ * so `chunks.test.ts` can exercise the WP-73 empty-list guard directly:
+ * `buildChildRegions`'s own `flushProperties` never calls this with an
+ * empty `properties` array, so that path cannot be reached end-to-end
+ * through `buildFileRegion` alone.
+ */
+export function propertyGroupRegion(
+  properties: ScopeNode[],
+  parentScopeId: string,
+  ordinal: number,
+  ctx: FileTextContext,
+  profile: LanguageProfile,
+): AstRegion {
+  const [firstProperty, ...restProperties] = properties;
+  if (firstProperty === undefined) {
+    // WP-73: `properties` must never be empty — the only caller
+    // (`flushProperties`) already guards on `pendingProperties.length === 0`
+    // and never reaches this function otherwise. An empty list here means
+    // that invariant was violated by a future caller; there is no
+    // meaningful `SourceRange` for zero properties, so this is an honest
+    // internal-defect report (E4) rather than a defined empty-range value
+    // that would silently mask the bug, and rather than the bare
+    // `Array.prototype.reduce` `TypeError: Reduce of empty array with no
+    // initial value` a caller would otherwise see.
+    throw new UntangleError(
+      "ANALYSIS_INCOMPLETE",
+      "propertyGroupRegion called with an empty properties list — a property_group region requires at least one property (spec.md §8.3)",
+      {
+        retryable: false,
+        operation: "chunk",
+        context: { parentScopeId, ordinal },
+      },
+    );
+  }
+  const range = restProperties.reduce(
+    (acc, property) => unionRange(acc, ownRange(property, ctx, profile)),
+    ownRange(firstProperty, ctx, profile),
+  );
+  return {
+    chunkKind: "property_group",
+    range,
+    scopeId: `${parentScopeId}#properties#${ordinal}`,
+    splittable: false,
+  };
+}
+
+/** Builds child regions for one scope, merging consecutive `property` children into `property_group`s. */
+function buildChildRegions(
+  children: ScopeNode[],
+  parentScopeId: string,
+  groupOrdinal: { next: number },
+  ctx: FileTextContext,
+  profile: LanguageProfile,
+): AstRegion[] {
+  const regions: AstRegion[] = [];
+  let pendingProperties: ScopeNode[] = [];
+
+  const flushProperties = (): void => {
+    if (pendingProperties.length === 0) return;
+    regions.push(
+      propertyGroupRegion(pendingProperties, parentScopeId, groupOrdinal.next, ctx, profile),
+    );
+    groupOrdinal.next += 1;
+    pendingProperties = [];
+  };
+
+  for (const child of children) {
+    if (child.kind === "property") {
+      pendingProperties.push(child);
+      continue;
+    }
+    flushProperties();
+    regions.push(toRegion(child, groupOrdinal, ctx, profile));
+  }
+  flushProperties();
+  return regions;
+}
+
+/** Leading file content (shebang/header comments/imports) before the first top-level region, if non-trivial. */
+/** Builds the single root ("module") `AstRegion` for a whole file. */
+export function buildFileRegion(
+  fileScope: ScopeNode,
+  ctx: FileTextContext,
+  profile: LanguageProfile,
+): AstRegion {
+  const groupOrdinal = { next: 0 };
+  const topLevelRegions = buildChildRegions(
+    fileScope.children,
+    fileScope.scopeId,
+    groupOrdinal,
+    ctx,
+    profile,
+  );
+
+  const firstRegion = topLevelRegions[0];
+  const preamble =
+    firstRegion !== undefined ? buildFilePreambleRegion(fileScope, firstRegion, ctx) : null;
+  const allChildren = preamble !== null ? [preamble, ...topLevelRegions] : topLevelRegions;
+
+  return {
+    chunkKind: "module",
+    range: fileScope.range,
+    scopeId: fileScope.scopeId,
+    splittable: allChildren.length > 0,
+    ...(allChildren.length > 0 ? { children: allChildren } : {}),
+  };
+}
+
+function buildFilePreambleRegion(
+  fileScope: ScopeNode,
+  firstChild: AstRegion,
+  ctx: FileTextContext,
+): AstRegion | null {
+  if (firstChild.range.startByte <= fileScope.range.startByte) return null;
+  const rawPreamble = ctx.sourceText.slice(
+    0,
+    indexForByteOffsetApprox(ctx, firstChild.range.startByte),
+  );
+  if (rawPreamble.trim().length === 0) return null;
+  return {
+    chunkKind: "file_preamble",
+    range: {
+      startLine: fileScope.range.startLine,
+      endLine: firstChild.range.startLine,
+      startByte: fileScope.range.startByte,
+      endByte: firstChild.range.startByte,
+    },
+    scopeId: fileScope.scopeId,
+    splittable: false,
+  };
+}
+
+// Approximates a UTF-16 slice index for a byte offset by scanning the
+// (small, preamble-sized) prefix — the preamble is always near the top of
+// the file, so this is O(preamble length), not O(file length).
+function indexForByteOffsetApprox(ctx: FileTextContext, byteOffset: number): number {
+  let low = 0;
+  let high = ctx.sourceText.length;
+  while (low < high) {
+    const mid = Math.floor((low + high) / 2);
+    if (ctx.byteTable.toByteOffset(mid) < byteOffset) low = mid + 1;
+    else high = mid;
+  }
+  return low;
+}

package/src/languages/shared/create-adapter.ts

@@ -0,0 +1,136 @@
+/**
+ * Wires one `Dialect` config into a full `LanguageAdapter` (domain
+ * `analysis.ts`), backed by the shared tree-sitter engine.
+ *
+ * See `engine.ts`'s doc comment for why every extraction method is a
+ * projection over one memoized `AnalysisResult`.
+ */
+import type {
+  AstRegion,
+  ComplexityFacts,
+  HalsteadTokens,
+  LanguageAdapter,
+  ParsedAst,
+  ParseResult,
+  RawCall,
+  RawImport,
+  SourceFile,
+} from "@untangle-code/domain";
+
+import { buildByteOffsetTable } from "../../text/byte-offset-table.js";
+
+import { buildFileRegion } from "./chunks.js";
+import type { Dialect } from "./dialect.js";
+import type { AnalysisResult } from "./engine.js";
+import { analyzeTree } from "./engine.js";
+import { extractedSymbolsOf } from "./extract-symbols.js";
+import { loadGrammar, loadParserCtor } from "./grammar-loader.js";
+import { createJsFamilyProfile } from "./js-family-profile.js";
+import type { FileTextContext } from "./node-utils.js";
+import { collectParseDiagnostics } from "./parse-diagnostics.js";
+import { parseWithBuffer } from "./parse-limits.js";
+import type { LanguageProfile } from "./profile.js";
+import type { TsTree } from "./tree-sitter-types.js";
+
+/** The opaque payload stored in `ParsedAst.root` by this package's `parse()`. */
+interface TreeSitterAstRoot {
+  tree: TsTree;
+  ctx: FileTextContext;
+  fileId: string;
+  profile: LanguageProfile;
+}
+
+const analysisCache = new WeakMap<ParsedAst, AnalysisResult>();
+
+/**
+ * `ComplexityFacts.parseDiagnostics` ist der EINZIGE Kanal, ueber den
+ * nachgelagerte Rechnungen (`computeSyntactic`, Berichte, Skip-Ledger) davon
+ * erfahren, dass der Syntaxbaum einer Datei beschaedigt ist. `analyzeTree`
+ * sieht die Diagnosen nicht — sie entstehen in `parse()` und haengen am
+ * `ParsedAst`. Wurde das Feld hier nicht befuellt, blieb es AUSNAHMSLOS leer:
+ * `parse_error_node_count` und `missing_node_count` meldeten dann fuer jede
+ * Datei 0, auch fuer eine mit `parseQuality: "partial"` und 25 Fehlerknoten.
+ * Genau dieses stille Verschlucken verbietet E4.
+ */
+function getAnalysis(ast: ParsedAst): AnalysisResult {
+  const cached = analysisCache.get(ast);
+  if (cached !== undefined) return cached;
+  const root = ast.root as TreeSitterAstRoot;
+  const analyzed = analyzeTree(root.tree.rootNode, root.ctx, root.fileId, root.profile);
+  const result: AnalysisResult = {
+    ...analyzed,
+    facts: { ...analyzed.facts, parseDiagnostics: ast.diagnostics },
+  };
+  analysisCache.set(ast, result);
+  return result;
+}
+
+export function createTreeSitterAdapter(dialect: Dialect): LanguageAdapter {
+  // EIN Profil je Adapter, einmal gebaut: die Mengen darin sind unveraenderlich,
+  // und der Walk liest sie je Knoten (`engine.ts`).
+  const profile = createJsFamilyProfile(dialect);
+
+  return {
+    languageId: dialect.languageId,
+    extensions: dialect.extensions,
+    supportLevel: dialect.supportLevel,
+
+    parse(source: SourceFile): ParseResult {
+      const ParserCtor = loadParserCtor();
+      const language = loadGrammar(dialect.grammar);
+      const parser = new ParserCtor();
+      parser.setLanguage(language);
+      // NIE `parser.parse(source.content)` — ohne `bufferSize` wirft die native
+      // Bindung fuer jede Datei ueber 32 KiB `Invalid argument` (WP-215).
+      // `parseWithBuffer` prueft die Groessengrenze, setzt den Puffer und
+      // benennt jede Ausnahme (WP-216).
+      const tree = parseWithBuffer(parser, source.content);
+
+      const byteTable = buildByteOffsetTable(source.content);
+      const ctx: FileTextContext = { sourceText: source.content, byteTable };
+      const { parseQuality, diagnostics, errorNodeCount, missingNodeCount } =
+        collectParseDiagnostics(tree.rootNode, ctx);
+
+      if (parseQuality === "failed") {
+        return { parseQuality, ast: null, diagnostics, errorNodeCount, missingNodeCount };
+      }
+
+      const root: TreeSitterAstRoot = { tree, ctx, fileId: source.fileId, profile };
+      return {
+        parseQuality,
+        ast: { languageId: dialect.languageId, parseQuality, root, diagnostics },
+        diagnostics,
+        errorNodeCount,
+        missingNodeCount,
+      };
+    },
+
+    extractChunks(ast): AstRegion[] {
+      const { scopeTree } = getAnalysis(ast);
+      const root = ast.root as TreeSitterAstRoot;
+      return [buildFileRegion(scopeTree, root.ctx, root.profile)];
+    },
+
+    extractSymbols(ast) {
+      const { scopeTree } = getAnalysis(ast);
+      return extractedSymbolsOf(scopeTree);
+    },
+
+    extractImports(ast): RawImport[] {
+      return getAnalysis(ast).imports;
+    },
+
+    extractCalls(ast): RawCall[] {
+      return getAnalysis(ast).calls;
+    },
+
+    computeComplexity(ast): ComplexityFacts {
+      return getAnalysis(ast).facts;
+    },
+
+    tokenizeForHalstead(ast): HalsteadTokens {
+      const { facts } = getAnalysis(ast);
+      return { operators: facts.operators, operands: facts.operands };
+    },
+  };
+}

package/src/languages/shared/decisions.ts

@@ -0,0 +1,204 @@
+/**
+ * Decision-point and nesting-event detection (spec.md §16.2-§16.4).
+ *
+ * Called once per non-leaf node during the main walk (`engine.ts`); returns
+ * the zero-or-one `DecisionFact`/`NestingFact` pair this specific node
+ * contributes (attribution to a `symbolScopeId` happens in the caller,
+ * which knows the current scope).
+ */
+import type { DecisionKind } from "@untangle-code/domain";
+
+import {
+  BINARY_EXPRESSION,
+  CATCH_CLAUSE,
+  IF_STATEMENT,
+  JUMP_STATEMENT_TYPES,
+  LOOP_TYPES,
+  SWITCH_CASE,
+  SWITCH_STATEMENT,
+  TERNARY_EXPRESSION,
+} from "./node-kinds.js";
+import type { SyntaxNode } from "./syntax.js";
+
+export interface DetectedDecision {
+  kind: DecisionKind;
+  countsForClassic: boolean;
+  countsForExtended: boolean;
+  logicalGroupId?: string;
+  /**
+   * Wie oft dieser EINE Knoten die Entscheidung beitraegt (Vorgabe: 1).
+   *
+   * WOFUER: eine Grammatik kann eine n-stellige Alternative FLACH ablegen.
+   * Rusts `or_pattern` ist linksrekursiv — `A | B | C` sind zwei
+   * verschachtelte Knoten, also zwei Entscheidungen ohne weiteres Zutun.
+   * Pythons `union_pattern` ist FLACH: `case 1 | 2 | 3` ist EIN Knoten mit
+   * drei Zweigen. Ohne diese Zahl kostete `1 | 2 | 3` genauso viel wie
+   * `1 | 2`, und die Metrik behauptete eine Gleichheit, die es nicht gibt.
+   *
+   * Die zusaetzlichen Entscheidungen teilen sich den Bereich des Knotens:
+   * die Alternativen liegen darin, und ein erfundener engerer Bereich waere
+   * eine Angabe, die der Baum nicht hergibt.
+   */
+  repeat?: number;
+}
+
+export interface DetectedNesting {
+  construct: string;
+  continuation: boolean;
+}
+
+export interface DecisionDetectionResult {
+  decision?: DetectedDecision;
+  nesting?: DetectedNesting;
+}
+
+function isElseIf(node: SyntaxNode): boolean {
+  return node.parent !== null && node.parent.type === "else_clause";
+}
+
+/** A guard clause: `if (cond) return/throw/break/continue;` with no `else`. */
+function isGuardClause(node: SyntaxNode): boolean {
+  if (node.childForFieldName("alternative") !== null) return false;
+  const consequence = node.childForFieldName("consequence");
+  if (consequence === null) return false;
+  const soleStatement =
+    consequence.type === "statement_block"
+      ? consequence.namedChildCount === 1
+        ? consequence.namedChild(0)
+        : null
+      : consequence;
+  return soleStatement !== null && JUMP_STATEMENT_TYPES.has(soleStatement.type);
+}
+
+/**
+ * Finds the topmost node in a maximal chain of the same binary operator (for
+ * grouping §16.3/§16.4) and derives a stable id for it from its position in
+ * the source (`startIndex`, the group top node's byte offset) rather than
+ * tree-sitter's runtime `node.id`. `node.id` is a native-binding identifier
+ * (effectively a heap address) that is NOT stable across processes or even
+ * across repeated parses of the identical source within the same process —
+ * two parse runs of the same file can and do produce different `node.id`
+ * values. `startIndex` is deterministic: the same source byte range always
+ * yields the same id, which is what vision.md §8.5's determinism principle
+ * requires once `ComplexityFacts` are persisted or compared across runs.
+ */
+function logicalGroupIdFor(node: SyntaxNode, operatorText: string): string {
+  let top = node;
+  while (top.parent !== null && top.parent.type === BINARY_EXPRESSION) {
+    const parentOperator = top.parent.childForFieldName("operator")?.text;
+    if (parentOperator !== operatorText) break;
+    top = top.parent;
+  }
+  return `logical-${top.startIndex}`;
+}
+
+/**
+ * Die Knotentypen, fuer die {@link detectDecisionAndNesting} ueberhaupt etwas
+ * anderes als `{}` liefern kann — abgeleitet aus den Verzweigungen unten und
+ * durch `decisions.test.ts` an sie gebunden.
+ *
+ * WOZU: der Cursor-Walk (`engine.ts`, WP-95) materialisiert einen
+ * `SyntaxNode`-Wrapper nur dann, wenn ein Detektor ihn wirklich braucht. Ohne
+ * dieses Vorsieb muesste er fuer JEDEN inneren Knoten einen Wrapper bauen —
+ * also genau die Grenzueberquerung wieder einfuehren, die der Cursor spart.
+ */
+const DECISION_CANDIDATE_TYPES: ReadonlySet<string> = new Set([
+  IF_STATEMENT,
+  ...LOOP_TYPES,
+  CATCH_CLAUSE,
+  TERNARY_EXPRESSION,
+  SWITCH_STATEMENT,
+  SWITCH_CASE,
+  BINARY_EXPRESSION,
+]);
+
+/** Kann ein Knoten dieses Typs eine Entscheidung oder ein Nesting-Ereignis tragen? */
+export function mayCarryDecisionOrNesting(nodeType: string): boolean {
+  return DECISION_CANDIDATE_TYPES.has(nodeType);
+}
+
+export function detectDecisionAndNesting(node: SyntaxNode): DecisionDetectionResult {
+  if (node.type === IF_STATEMENT) {
+    if (isElseIf(node)) {
+      return {
+        decision: { kind: "else_if", countsForClassic: true, countsForExtended: true },
+        nesting: { construct: "if", continuation: true },
+      };
+    }
+    const kind: DecisionKind = isGuardClause(node) ? "guard" : "if";
+    return {
+      decision: { kind, countsForClassic: true, countsForExtended: true },
+      nesting: { construct: "if", continuation: false },
+    };
+  }
+
+  if (LOOP_TYPES.has(node.type)) {
+    return {
+      decision: { kind: "loop", countsForClassic: true, countsForExtended: true },
+      nesting: { construct: "loop", continuation: false },
+    };
+  }
+
+  if (node.type === CATCH_CLAUSE) {
+    return {
+      decision: { kind: "catch", countsForClassic: true, countsForExtended: true },
+      nesting: { construct: "catch", continuation: false },
+    };
+  }
+
+  if (node.type === TERNARY_EXPRESSION) {
+    return {
+      decision: { kind: "ternary", countsForClassic: true, countsForExtended: true },
+      nesting: { construct: "ternary", continuation: false },
+    };
+  }
+
+  if (node.type === SWITCH_STATEMENT) {
+    return { nesting: { construct: "switch", continuation: false } };
+  }
+
+  if (node.type === SWITCH_CASE) {
+    return { decision: { kind: "case", countsForClassic: true, countsForExtended: true } };
+  }
+
+  if (node.type === BINARY_EXPRESSION) {
+    const operator = node.childForFieldName("operator")?.text;
+    if (operator === "&&") {
+      return {
+        decision: {
+          kind: "logical_and",
+          countsForClassic: false,
+          countsForExtended: true,
+          logicalGroupId: logicalGroupIdFor(node, "&&"),
+        },
+      };
+    }
+    if (operator === "||") {
+      return {
+        decision: {
+          kind: "logical_or",
+          countsForClassic: false,
+          countsForExtended: true,
+          logicalGroupId: logicalGroupIdFor(node, "||"),
+        },
+      };
+    }
+    if (operator === "??") {
+      return {
+        decision: {
+          kind: "short_circuit",
+          countsForClassic: false,
+          countsForExtended: true,
+          logicalGroupId: logicalGroupIdFor(node, "??"),
+        },
+      };
+    }
+  }
+
+  return {};
+}
+
+/** Nesting construct for a lambda/local-function boundary (spec.md §16.4). */
+export function lambdaNesting(): DetectedNesting {
+  return { construct: "lambda", continuation: false };
+}