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

package/src/languages/shared/profile.ts

@@ -0,0 +1,184 @@
+/**
+ * Das SPRACHPROFIL: alles, was der vereinheitlichte Walk (`engine.ts`) ueber
+ * eine konkrete Sprache wissen muss — als Tabelle plus eine Handvoll Haken,
+ * nicht als verdrahtete Zeichenketten im Motor.
+ *
+ * WARUM (WP-220): bis Welle 6 stand die JS/TS-Familie fest im Motor. `engine.ts`
+ * nannte 48 verschiedene Knotenarten woertlich, `fingerprint.ts` kannte
+ * `"comment"` als Konstante, `chunks.ts` kannte `export_statement`. Solange es
+ * genau ein Backend und genau eine Sprachfamilie gab, war das billig und
+ * ehrlich. Mit dem zweiten Backend (`languages/astgrep-backend/`) waere daraus ein
+ * ZWEITER Motor neben dem ersten geworden — und damit das Gegenteil der These
+ * aus vision.md §1b, die wir belegen wollen: gleiche Leistung mit WENIGER
+ * Komplexitaet. Deshalb erst die Verallgemeinerung, dann das Backend.
+ *
+ * ZWEI ARTEN, EIN PROFIL ZU BAUEN:
+ *
+ *  1. `js-family-profile.ts` — die handgeschriebene Fassung fuer
+ *     TypeScript/JavaScript/TSX/JSX. Sie reicht die vorhandenen Detektoren
+ *     (`decisions.ts`, `import-detection.ts`, `call-detection.ts`,
+ *     `scope-naming.ts`, `scope-signature.ts`, `doc-binding.ts`) unveraendert
+ *     durch. Ihr Verhalten ist Zeile fuer Zeile das von vorher; die
+ *     Golden-Tests dieses Pakets sind der Beleg.
+ *
+ *  2. `table-profile.ts` — die tabellengetriebene Fassung fuer jede weitere
+ *     Sprache. Sie kennt keine Sprache, nur Rollen: welche Knotenart ist ein
+ *     Kommentar, welche oeffnet einen Scope, welche traegt eine Entscheidung.
+ *     Eine neue Sprache kostet damit eine Tabelle, keinen Motor.
+ *
+ * WAS HIER NICHT HINEINGEHOERT: alles Backendspezifische. Ein Profil sagt,
+ * WAS eine Knotenart bedeutet, nie, WIE der Baum entsteht. Das Backend steht
+ * in `create-adapter.ts` (tree-sitter) bzw. `languages/astgrep-backend/create-adapter.ts`.
+ */
+import type {
+  LiteralFact,
+  RawCall,
+  RawImport,
+  SourceRange,
+  SupportLevel,
+} from "@untangle-code/domain";
+
+import type { DecisionDetectionResult } from "./decisions.js";
+import type { FileTextContext } from "./node-utils.js";
+import type { ScopeNode } from "./scope-model.js";
+import type { SyntaxNode } from "./syntax.js";
+
+/** Die Fakten, die ein Knoten ausserhalb von Entscheidungen beitragen kann. */
+export interface ModuleFactSink {
+  imports: RawImport[];
+  calls: RawCall[];
+}
+
+/** Roh- und Normalform der Kopfzeile eines Symbols (siehe `signature.ts`). */
+export interface ScopeSignature {
+  raw?: string;
+  normalized: string;
+}
+
+/**
+ * Ein Sprachprofil. Jede Eigenschaft wird vom Walk GENAU EINMAL je Knoten
+ * gelesen; die Mengen sind deshalb `Set`s und keine Arrays.
+ */
+export interface LanguageProfile {
+  readonly languageId: string;
+  readonly extensions: readonly string[];
+  readonly supportLevel: SupportLevel;
+
+  // -- Knotenrollen ---------------------------------------------------------
+
+  /** Kommentarknoten: nie Operator, nie Operand, nie Teil eines Fingerabdrucks. */
+  readonly commentKinds: ReadonlySet<string>;
+  /**
+   * Knoten, deren ganzer Teilbaum als EIN Operand/Literal zaehlt (der Walk
+   * steigt nicht hinein). In der JS/TS-Familie `string` und `regex`.
+   */
+  readonly literalContainerKinds: ReadonlySet<string>;
+  /** Blattknoten, die ein Bezeichnervorkommen sind. */
+  readonly identifierLeafKinds: ReadonlySet<string>;
+  /** Blattknoten, die ein einfaches Literal sind. */
+  readonly simpleLiteralLeafKinds: ReadonlySet<string>;
+  /** Statische Textteile in einer Zeichenkettenschablone. */
+  readonly templateTextLeafKinds: ReadonlySet<string>;
+  /** Satzzeichenblaetter, die weder Operator noch Operand sind. */
+  readonly ignoredPunctuationKinds: ReadonlySet<string>;
+  /**
+   * Elternknotenarten, deren Blaetter reine Typsyntax sind (TS
+   * `predefined_type`): gezaehlt in `nodeKinds`, aber nie als Token.
+   */
+  readonly typeKeywordParentKinds: ReadonlySet<string>;
+  /** Funktionsartige Knoten — sie erzeugen zusaetzlich ein Lambda-Nesting. */
+  readonly functionLikeKinds: ReadonlySet<string>;
+
+  /** Literalart eines Container-Literals (`literalContainerKinds`). */
+  containerLiteralKind(kind: string): LiteralFact["literalKind"];
+  /** Literalart eines einfachen Literalblatts (`simpleLiteralLeafKinds`). */
+  simpleLiteralKind(kind: string): LiteralFact["literalKind"];
+  /** Deklaration oder Verweis? `fieldName` ist der Feldname im Elternknoten. */
+  identifierRole(fieldName: string | undefined, parentKind: string): "declaration" | "reference";
+
+  // -- Vorsieb --------------------------------------------------------------
+
+  /**
+   * Braucht ein innerer Knoten dieser Art ueberhaupt einen Knotenwrapper?
+   *
+   * Das ist das Vorsieb aus WP-95: fuer die grosse Mehrheit der inneren Knoten
+   * (Ausdruecke, Bloecke, Anweisungslisten) faellt die Grenzueberquerung
+   * vollstaendig weg. Wer hier `true` zurueckgibt, bezahlt je Knoten — beim
+   * ast-grep-Backend deutlich mehr als bei tree-sitter.
+   */
+  needsNode(kind: string): boolean;
+
+  // -- Scopes ---------------------------------------------------------------
+
+  /** Welche Art von Scope oeffnet dieser Knoten — oder keinen (`null`)? */
+  scopeKindOf(node: SyntaxNode): ScopeNode["kind"] | null;
+  /**
+   * Unterdrueckt einen sonst geoeffneten Scope (JS: ein Feld, dessen Wert
+   * selbst eine Funktion ist — die Funktion bekommt den Scope, nicht das Feld).
+   */
+  suppressesScope(node: SyntaxNode): boolean;
+  scopeName(node: SyntaxNode): string;
+  /**
+   * Ein Namensteil, der VOR den Scope-Namen gehoert, aber nicht aus einem
+   * Elternscope stammt (WP-237).
+   *
+   * Gos Methoden haengen nicht in ihrem Typ, sondern tragen ihn als Feld:
+   * `func (a *A) Run()` ist ein Geschwister von `type A struct{}`, kein Kind.
+   * Ohne diesen Zusatz heissen `(*A).Run` und `(*B).Run` beide `Run`, und der
+   * Symbolgraph haelt zwei verschiedene Methoden fuer dieselbe — eine
+   * Impact-Analyse auf einer Go-Codebasis waere damit schlicht falsch.
+   *
+   * Rueckgabe `undefined` heisst: dieser Knoten braucht keinen Zusatz.
+   */
+  scopeQualifier?(node: SyntaxNode): string | undefined;
+  scopeSignature(node: SyntaxNode, kind: ScopeNode["kind"], name: string): ScopeSignature;
+  docRange(node: SyntaxNode, ctx: FileTextContext): SourceRange | undefined;
+  visibility(node: SyntaxNode, name: string): string | undefined;
+  exportedNames(node: SyntaxNode, name: string): string[];
+
+  // -- Fakten ---------------------------------------------------------------
+
+  detectDecisionAndNesting(node: SyntaxNode): DecisionDetectionResult;
+  /**
+   * Importe und Aufrufe dieses Knotens. Schreibt DIREKT in `sink`, statt ein
+   * Ergebnisobjekt zu bauen: der Haken laeuft im Walk, und ein Objekt je
+   * Aufrufknoten waere reiner Muell fuer den Sammler.
+   */
+  collectModuleFacts(
+    node: SyntaxNode,
+    kind: string,
+    callerScopeId: string,
+    ctx: FileTextContext,
+    sink: ModuleFactSink,
+  ): void;
+
+  // -- Regionen (`chunks.ts`) -----------------------------------------------
+
+  /**
+   * Huellknoten, deren Bytes zum Symbol gehoeren (JS/TS: `export_statement`).
+   * Leer, wenn die Sprache keine solche Huelle kennt.
+   */
+  readonly exportWrapperKinds: ReadonlySet<string>;
+  /**
+   * Zusaetzliche Kindregionen eines Klassen-artigen Scopes, die selbst keinen
+   * Scope oeffnen, aber Inhalt tragen (JS/TS: `static { ... }`). Ohne sie
+   * fielen ihre Bytes durch den Mitgliederlauf — spec.md §8.4 verbietet das.
+   */
+  memberRegions(node: SyntaxNode, parentScopeId: string, ctx: FileTextContext): MemberRegion[];
+}
+
+/** Eine Region ohne Symbol, wie sie `memberRegions` liefert. */
+export interface MemberRegion {
+  range: SourceRange;
+  scopeId: string;
+  headerText: string;
+}
+
+/**
+ * Ausfuehrungseinheiten (spec.md §16.1) — bei jeder Sprache dieselben drei
+ * Arten. Der Dateirahmen ist gesondert ausfuehrbar (`engine.ts`); er kommt hier
+ * nie an, weil `scopeKindOf` niemals `"file"` liefert.
+ */
+export function isExecutableScopeKind(kind: ScopeNode["kind"]): boolean {
+  return kind === "function" || kind === "method" || kind === "constructor";
+}

package/src/languages/shared/scope-model.ts

@@ -0,0 +1,43 @@
+import type { SourceRange } from "@untangle-code/domain";
+
+import type { SyntaxNode } from "./syntax.js";
+
+/**
+ * Internal (package-private) representation of one symbol scope, built once
+ * per parse by `engine.ts#analyze` and then projected into the public
+ * `ExtractedSymbol[]` / `SymbolScopeFact[]` / `AstRegion[]` shapes by
+ * `extractSymbols.ts`, `complexity.ts` and `chunks.ts` respectively. Keeping
+ * ONE tree as the single source of truth guarantees `scopeId`s line up
+ * exactly across `extractSymbols`, `computeComplexity` and `extractCalls`,
+ * since all three are projections of the same walk.
+ */
+export interface ScopeNode {
+  scopeId: string;
+  /** Adapter-internal kind: superset of ExtractedSymbol.kind plus "file". */
+  kind:
+    | "file"
+    | "function"
+    | "method"
+    | "constructor"
+    | "class"
+    | "interface"
+    | "type"
+    | "enum"
+    | "namespace"
+    | "property";
+  name: string;
+  qualifiedName: string;
+  parentQualifiedName?: string;
+  range: SourceRange;
+  docRange?: SourceRange;
+  signature?: string;
+  normalizedSignature: string;
+  exportedNames: string[];
+  visibility?: string;
+  executable: boolean;
+  astHash: string;
+  tokenFingerprint: string;
+  /** The tree-sitter node whose range/body IS this scope (used only within this package). */
+  node: SyntaxNode;
+  children: ScopeNode[];
+}

package/src/languages/shared/scope-naming.ts

@@ -0,0 +1,124 @@
+/**
+ * Name/signature/visibility derivation for one scope-opening node.
+ *
+ * A scope-opening node (function/method/class/interface/type/enum/property,
+ * see `node-kinds.ts#SCOPE_OPENING_TYPES`) is either self-naming (its own
+ * `name` field) or anonymous, in which case the name is borrowed from the
+ * enclosing syntactic context — `const x = () => {}`, `{ key: () => {} }`,
+ * `x.y = function () {}`, `export default function () {}`, or a class field
+ * initialized with an arrow function (spec.md §8.3 step 3: "Top-Level-Symbole
+ * bestimmen").
+ */
+import { CLASS_TYPES, FIELD_TYPES, FUNCTION_LIKE_TYPES, METHOD_TYPE } from "./node-kinds.js";
+import { unquote } from "./node-utils.js";
+import type { SyntaxNode } from "./syntax.js";
+
+const ANONYMOUS_NAME = "<anonymous>";
+
+/** Derives the declared or contextually-borrowed name of a scope-opening node. */
+export function resolveScopeName(node: SyntaxNode): string {
+  const ownName = node.childForFieldName("name");
+  if (ownName !== null) {
+    return ownName.type === "computed_property_name" ? ownName.text : unquote(ownName.text);
+  }
+
+  if (FIELD_TYPES.has(node.type)) {
+    const property = node.childForFieldName("property");
+    if (property !== null) return unquote(property.text);
+  }
+
+  if (
+    FUNCTION_LIKE_TYPES.has(node.type) ||
+    node.type === METHOD_TYPE ||
+    CLASS_TYPES.has(node.type)
+  ) {
+    const parent = node.parent;
+    if (parent === null) return ANONYMOUS_NAME;
+
+    switch (parent.type) {
+      case "variable_declarator": {
+        const declaratorName = parent.childForFieldName("name");
+        return declaratorName !== null && declaratorName.type === "identifier"
+          ? declaratorName.text
+          : ANONYMOUS_NAME;
+      }
+      case "pair":
+      case "pair_pattern": {
+        const key = parent.childForFieldName("key");
+        return key !== null ? unquote(key.text) : ANONYMOUS_NAME;
+      }
+      case "assignment_expression": {
+        const left = parent.childForFieldName("left");
+        if (left === null) return ANONYMOUS_NAME;
+        if (left.type === "identifier") return left.text;
+        if (left.type === "member_expression") {
+          const property = left.childForFieldName("property");
+          return property !== null ? property.text : ANONYMOUS_NAME;
+        }
+        return ANONYMOUS_NAME;
+      }
+      case "field_definition":
+      case "public_field_definition": {
+        const property = parent.childForFieldName("property");
+        return property !== null ? unquote(property.text) : ANONYMOUS_NAME;
+      }
+      case "export_statement":
+        return "default";
+      default:
+        return ANONYMOUS_NAME;
+    }
+  }
+
+  return ANONYMOUS_NAME;
+}
+
+/**
+ * True when a field's initializer is itself a function-like node: in that
+ * case the FIELD does not get its own scope — the function value does,
+ * borrowing the field's property name (avoids a redundant doubled
+ * `Class.field.field` qualified name for `class C { handler = () => {} }`).
+ */
+export function fieldDelegatesToFunctionValue(node: SyntaxNode): boolean {
+  if (!FIELD_TYPES.has(node.type)) return false;
+  const value = node.childForFieldName("value");
+  return value !== null && (FUNCTION_LIKE_TYPES.has(value.type) || value.type === "class");
+}
+
+const VISIBILITY_MODIFIER_TYPE = "accessibility_modifier";
+
+/** `public`/`private`/`protected` if explicit, `"private"` for a `#name`, else `undefined` (implicit public). */
+export function resolveVisibility(node: SyntaxNode, name: string): string | undefined {
+  const modifier = node.children.find((child) => child.type === VISIBILITY_MODIFIER_TYPE);
+  if (modifier !== undefined) return modifier.text;
+  if (name.startsWith("#")) return "private";
+  return undefined;
+}
+
+/**
+ * Names this declaration exports, per spec.md §8.3 step 2/§14 (best-effort:
+ * only direct `export` / `export default` wrapping the declaration itself is
+ * recognized — a later `export { name }` clause elsewhere in the file is a
+ * documented simplification, see README "Entscheidungen").
+ */
+export function resolveExportedNames(node: SyntaxNode, name: string): string[] {
+  let current: SyntaxNode | null = node;
+  // Walk up through wrapping declarator/declaration nodes that carry no name of their own.
+  while (current !== null) {
+    const parent: SyntaxNode | null = current.parent;
+    if (parent === null) return [];
+    if (parent.type === "export_statement") {
+      const hasDefault = parent.children.some((child) => child.type === "default");
+      return [hasDefault ? "default" : name];
+    }
+    if (
+      parent.type === "variable_declarator" ||
+      parent.type === "lexical_declaration" ||
+      parent.type === "variable_declaration"
+    ) {
+      current = parent;
+      continue;
+    }
+    return [];
+  }
+  return [];
+}

package/src/languages/shared/scope-signature.ts

@@ -0,0 +1,108 @@
+/**
+ * Signature text composition per scope kind (see `signature.ts` for the
+ * normalization primitives this builds on, and its doc comment for the
+ * normative whitespace/defaults/optional-marker/type-annotation rules).
+ */
+import { FUNCTION_LIKE_TYPES, METHOD_TYPE } from "./node-kinds.js";
+import {
+  normalizeHeaderText,
+  normalizeParameterList,
+  normalizeReturnType,
+  normalizeTypeParameterList,
+} from "./signature.js";
+import type { SyntaxNode } from "./syntax.js";
+
+const MODIFIER_ORDER = [
+  "accessibility_modifier",
+  "static",
+  "abstract",
+  "override_modifier",
+  "readonly",
+  "declare",
+  "async",
+] as const;
+
+function collectModifiers(node: SyntaxNode): string[] {
+  const found: string[] = [];
+  for (const modifierType of MODIFIER_ORDER) {
+    const child = node.children.find((c) => c.type === modifierType);
+    if (child !== undefined) found.push(child.text);
+  }
+  return found;
+}
+
+function isGenerator(node: SyntaxNode): boolean {
+  return node.children.some((child) => child.type === "*");
+}
+
+function accessorKeyword(node: SyntaxNode): "get" | "set" | undefined {
+  const hasGet = node.children.some((child) => child.type === "get");
+  const hasSet = node.children.some((child) => child.type === "set");
+  return hasGet ? "get" : hasSet ? "set" : undefined;
+}
+
+interface FunctionSignature {
+  raw: string;
+  normalized: string;
+}
+
+/** Builds the signature for a function/arrow/method-shaped scope node. */
+export function buildFunctionSignature(node: SyntaxNode, name: string): FunctionSignature {
+  const typeParamsNode = node.childForFieldName("type_parameters");
+  const parametersNode = node.childForFieldName("parameters");
+  const returnTypeNode = node.childForFieldName("return_type");
+
+  const modifiers = collectModifiers(node);
+  const accessor = accessorKeyword(node);
+  const generatorMarker = isGenerator(node) ? "*" : "";
+
+  const headParts = [...modifiers];
+  if (accessor !== undefined) headParts.push(accessor);
+  const head =
+    headParts.length > 0
+      ? `${headParts.join(" ")} ${generatorMarker}${name}`
+      : `${generatorMarker}${name}`;
+
+  const rawTypeParams = typeParamsNode?.text;
+  const rawParams =
+    parametersNode?.text ??
+    (node.childForFieldName("parameter")?.text !== undefined
+      ? `(${node.childForFieldName("parameter")?.text})`
+      : "()");
+  const rawReturnType = returnTypeNode?.text;
+
+  const raw = `${head}${rawTypeParams ?? ""}${rawParams}${rawReturnType !== undefined ? rawReturnType : ""}`;
+
+  const normalizedTypeParams = normalizeTypeParameterList(rawTypeParams);
+  const normalizedParams = normalizeParameterList(rawParams);
+  const normalizedReturnType = normalizeReturnType(rawReturnType);
+  const normalized = `${head}${normalizedTypeParams}${normalizedParams}${normalizedReturnType}`;
+
+  return { raw, normalized };
+}
+
+/** Builds the signature for a class/interface/enum/type-alias/namespace scope node. */
+export function buildHeaderSignature(node: SyntaxNode): FunctionSignature {
+  const bodyNode = node.childForFieldName("body");
+  const raw =
+    bodyNode !== null
+      ? node.text.slice(0, bodyNode.startIndex - node.startIndex).trimEnd()
+      : node.text.replace(/;\s*$/, "");
+  return { raw, normalized: normalizeHeaderText(raw) };
+}
+
+/** Builds the signature for a class field / property scope node. */
+export function buildPropertySignature(node: SyntaxNode, name: string): FunctionSignature {
+  const typeNode = node.childForFieldName("type");
+  const modifiers = collectModifiers(node);
+  const head = modifiers.length > 0 ? `${modifiers.join(" ")} ${name}` : name;
+  const rawType = typeNode?.text;
+  const raw = `${head}${rawType ?? ""}`;
+  const normalized =
+    rawType !== undefined ? `${head}${normalizeReturnType(rawType)}` : normalizeHeaderText(head);
+  return { raw, normalized };
+}
+
+export function isFunctionLikeScope(nodeType: string): boolean {
+  return FUNCTION_LIKE_TYPES.has(nodeType) || nodeType === METHOD_TYPE;
+}

package/src/languages/shared/signature.ts

@@ -0,0 +1,149 @@
+/**
+ * Signature text normalization for the JS/TS grammar family.
+ *
+ * Normative requirement (WP-06 task, spec.md §5.5): `normalizedSignature`
+ * feeds `buildSymbolId`, so it MUST be stable across:
+ *
+ * 1. Whitespace — any run of spaces/tabs/newlines collapses to a single
+ *    space; spacing around `,`, `:`, `(`, `)`, `<`, `>`, `?:` is
+ *    canonicalized rather than preserved verbatim.
+ * 2. Default values — `= <expr>` parameter/type-parameter initializers are
+ *    STRIPPED. Rationale: giving a parameter a default value is (mostly) a
+ *    call-site convenience, not a new overload; keeping it in the identity
+ *    signature would needlessly change a symbol's id on a body-only-feeling
+ *    edit. The optional marker (see next point) already captures "callers
+ *    may omit this argument".
+ * 3. Optional markers — TypeScript's trailing `?` on a parameter name is
+ *    KEPT and canonicalized to sit directly against the following `:`
+ *    (`a ?:string` and `a?: string` both become `a?: string`) because it
+ *    changes the call contract independent of any default value.
+ * 4. Type annotations — kept verbatim (modulo the same whitespace rules)
+ *    because they are part of the observable contract.
+ *
+ * Known limitation (documented, not a defect): default-value stripping and
+ * top-level-comma splitting use a bracket-DEPTH scanner, not a full
+ * expression parser. A `<` used as a less-than operator inside a default
+ * expression (e.g. `(a = b < c ? 1 : 2)`) is misread as a generic open
+ * bracket and can throw off depth tracking for the rest of that one
+ * parameter. This is vanishingly rare in default-value position and is
+ * accepted as a WP-06 scoping decision (see README "Entscheidungen").
+ */
+
+const OPEN_BRACKETS = new Set(["(", "[", "{", "<"]);
+const CLOSE_BRACKETS = new Set([")", "]", "}", ">"]);
+
+/** Collapses whitespace and canonicalizes spacing around common punctuation. */
+export function normalizeSpacing(text: string): string {
+  return text
+    .replace(/\s+/g, " ")
+    .replace(/\s*\?\s*:/g, "?:")
+    .replace(/\s*:\s*/g, ": ")
+    .replace(/\s*,\s*/g, ", ")
+    .replace(/\(\s+/g, "(")
+    .replace(/\s+\)/g, ")")
+    .replace(/<\s+/g, "<")
+    .replace(/\s+>/g, ">")
+    .replace(/\.\.\.\s+/g, "...")
+    .replace(/\s{2,}/g, " ")
+    .trim();
+}
+
+/**
+ * Splits `content` on top-level occurrences of `separator` (depth 0 with
+ * respect to `(`, `[`, `{`, `<`/`>`). Used to split parameter lists and
+ * type-parameter lists without being confused by nested generics/objects.
+ */
+export function splitTopLevel(content: string, separator: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of content) {
+    if (OPEN_BRACKETS.has(ch)) depth += 1;
+    else if (CLOSE_BRACKETS.has(ch)) depth = Math.max(0, depth - 1);
+    if (ch === separator && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  parts.push(current);
+  return parts;
+}
+
+/**
+ * Index of the top-level `=` that introduces a default value, or -1.
+ * Excludes `=>`, `==`, `===`, `!=`, `!==`, `<=`, `>=`.
+ */
+function findTopLevelDefaultEquals(text: string): number {
+  let depth = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i] as string;
+    if (OPEN_BRACKETS.has(ch)) {
+      depth += 1;
+      continue;
+    }
+    if (CLOSE_BRACKETS.has(ch)) {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (ch === "=" && depth === 0) {
+      const prev = i > 0 ? text[i - 1] : "";
+      const next = i + 1 < text.length ? text[i + 1] : "";
+      const isCompoundOperator =
+        next === "=" || next === ">" || prev === "!" || prev === "<" || prev === ">";
+      if (!isCompoundOperator) return i;
+    }
+  }
+  return -1;
+}
+
+/** Strips a single parameter's/type-parameter's default value (`= <expr>`), keeping any `?`/type annotation before it. */
+export function stripDefaultValue(entry: string): string {
+  const eqIndex = findTopLevelDefaultEquals(entry);
+  return eqIndex === -1 ? entry : entry.slice(0, eqIndex).trimEnd();
+}
+
+/**
+ * Normalizes a formal-parameter-list text (including its outer parens),
+ * e.g. `(a: number = 1, b ?: string)` -> `(a: number, b?: string)`.
+ */
+export function normalizeParameterList(paramsText: string): string {
+  const trimmed = paramsText.trim();
+  const hasParens = trimmed.startsWith("(") && trimmed.endsWith(")");
+  const inner = hasParens ? trimmed.slice(1, -1) : trimmed;
+  const entries = splitTopLevel(inner, ",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  const normalizedEntries = entries.map((entry) => normalizeSpacing(stripDefaultValue(entry)));
+  return `(${normalizedEntries.join(", ")})`;
+}
+
+/**
+ * Normalizes a type-parameter list text (including its outer `<>`), e.g.
+ * `<T extends object = {}, U>` -> `<T extends object, U>`.
+ */
+export function normalizeTypeParameterList(typeParamsText: string | undefined): string {
+  if (typeParamsText === undefined || typeParamsText.trim().length === 0) return "";
+  const trimmed = typeParamsText.trim();
+  const hasBrackets = trimmed.startsWith("<") && trimmed.endsWith(">");
+  const inner = hasBrackets ? trimmed.slice(1, -1) : trimmed;
+  const entries = splitTopLevel(inner, ",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  if (entries.length === 0) return "";
+  const normalizedEntries = entries.map((entry) => normalizeSpacing(stripDefaultValue(entry)));
+  return `<${normalizedEntries.join(", ")}>`;
+}
+
+/** Normalizes a return-type annotation text (e.g. ` : Promise<void> ` -> `: Promise<void>`). */
+export function normalizeReturnType(returnTypeText: string | undefined): string {
+  if (returnTypeText === undefined || returnTypeText.trim().length === 0) return "";
+  const normalized = normalizeSpacing(returnTypeText);
+  return normalized.startsWith(":") ? normalized : `: ${normalized}`;
+}
+
+/** Normalizes an arbitrary header text (class/interface/type/enum declarations). */
+export function normalizeHeaderText(headerText: string): string {
+  return normalizeSpacing(headerText.replace(/;\s*$/, ""));
+}