Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

refactor(core): move per-language parser helpers into ingestion/lang_helpers (#2584)

Raghav Chamadiya280a30f290ab
diff --git a/docs/architecture/language-support.md b/docs/architecture/language-support.md
index 4591c5481..218b24b84 100644
--- a/docs/architecture/language-support.md
+++ b/docs/architecture/language-support.md
@@ -622,7 +622,7 @@ parse, where hitting it corrupts everything downstream. Object Pascal is the cur
`.dpr`/`.dpk`/`.lpr` project files write `unit in 'path.pas'` clauses in their
`uses` list, a syntax tree-sitter-pascal has no rule for, and hitting one used to
corrupt every unit named after it in the same clause. Its sanitizer
-(`prepare_pascal_source` in `ingestion/parser_helpers.py`) is gated on `path`'s
+(`prepare_pascal_source` in `ingestion/lang_helpers/source_prep.py`) is gated on `path`'s
extension (that syntax is invalid in a plain `.pas`/`.pp` unit file) and is a
no-op everywhere else, same contract as the `_LOCATORS` path. Registering a
sanitizer this way, rather than as an if-block in `parser.py`, means it stays
diff --git a/packages/core/src/repowise/core/ingestion/lang_helpers/__init__.py b/packages/core/src/repowise/core/ingestion/lang_helpers/__init__.py
new file mode 100644
index 000000000..83c12b9b1
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/lang_helpers/__init__.py
@@ -0,0 +1,4 @@
+"""Per-language tree-sitter helpers the ingestion parser calls.
+
+``parser_helpers`` re-exports every name ``parser.py`` imports from here.
+"""
diff --git a/packages/core/src/repowise/core/ingestion/lang_helpers/elixir.py b/packages/core/src/repowise/core/ingestion/lang_helpers/elixir.py
new file mode 100644
index 000000000..b0db4bf37
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/lang_helpers/elixir.py
@@ -0,0 +1,244 @@
+"""Elixir definition, module-parent and call-filter helpers."""
+
+from __future__ import annotations
+
+from tree_sitter import Node
+
+from ..extractors import node_text
+
+# Elixir keywords that DEFINE rather than call. Every one of them parses as a
+# `call` whose target identifier holds the keyword text, so the head it takes
+# (`add(a, b)` in `def add(a, b)`) is a `call` node too.
+_ELIXIR_DEFINITION_KEYWORDS = frozenset(
+ {
+ "def",
+ "defp",
+ "defmacro",
+ "defmacrop",
+ "defguard",
+ "defguardp",
+ "defdelegate",
+ "defmodule",
+ "defprotocol",
+ "defimpl",
+ "defexception",
+ "defstruct",
+ }
+)
+
+# Module attributes whose body is a type expression, not code. `@spec
+# add(integer(), integer()) :: integer()` holds three `call` nodes and calls
+# nothing; every other attribute (`@config Application.compile_env(…)`) holds
+# real code and keeps its edges.
+_ELIXIR_TYPESPEC_ATTRIBUTES = frozenset(
+ {"spec", "type", "typep", "opaque", "callback", "macrocallback"}
+)
+
+# Elixir keywords that own a nested definition -- the parent a `def` reports.
+# `defimpl` is here because its definitions belong to the implementation module
+# the compiler generates, not to whatever module the block happens to sit in.
+_ELIXIR_MODULE_KEYWORDS = frozenset({"defmodule", "defprotocol", "defimpl"})
+
+# Node kinds that hold a list of statements. Reaching one while walking out of
+# an expression means the enclosing statement has been left.
+_ELIXIR_STATEMENT_HOLDERS = frozenset({"do_block", "block", "source", "stab_clause"})
+
+
+def _elixir_call_target_name(call_node: Node, src: str) -> str | None:
+ """The keyword or function name in an Elixir ``call`` node's target."""
+ if call_node.type != "call":
+ return None
+ target = call_node.child_by_field_name("target")
+ if target is None or target.type != "identifier":
+ return None
+ return node_text(target, src).strip() or None
+
+
+def _elixir_call_is_definitional(node: Node, src: str) -> bool:
+ """True when an Elixir ``call`` node defines or describes, never invokes.
+
+ Two shapes reach the call queries and must not become graph edges, and
+ neither can be excluded by a query predicate, which sees only the node's
+ own text and not its parent:
+
+ * a definition head -- ``def add(a, b)`` puts ``add(a, b)`` in the
+ ``arguments`` of a call to ``def``, so the head reads as a call to the
+ function being defined (a self-edge on every function in the repo). The
+ ``when``-guard form wraps that head in a ``binary_operator`` first.
+ * a module attribute -- ``@doc "…"`` is a call to ``doc``, and any
+ ``@whatever value`` is a call to ``whatever``. Inside a typespec
+ attribute the body is types, so its calls are dropped too; inside any
+ other attribute the body is ordinary code and keeps its edges.
+ """
+ return _elixir_is_definition_head(node, src) or _elixir_in_attribute(node, src)
+
+
+def _elixir_is_definition_head(node: Node, src: str) -> bool:
+ """True when *node* (or its ``when`` guard) is the first argument of a ``def``."""
+ head = _elixir_guarded_head(node)
+ parent = head.parent
+ if parent is None or parent.type != "arguments":
+ return False
+ named = parent.named_children
+ if not named or named[0].id != head.id:
+ return False
+ outer = parent.parent
+ return outer is not None and _elixir_call_target_name(outer, src) in _ELIXIR_DEFINITION_KEYWORDS
+
+
+def _elixir_guarded_head(node: Node) -> Node:
+ """The ``when`` expression *node* is the left side of, else *node* itself."""
+ parent = node.parent
+ if parent is None or parent.type != "binary_operator":
+ return node
+ operator = parent.child_by_field_name("operator")
+ if operator is None or operator.type != "when":
+ return node
+ left = parent.child_by_field_name("left")
+ return parent if left is not None and left.id == node.id else node
+
+
+def _elixir_in_attribute(node: Node, src: str) -> bool:
+ """True when *node* is a module attribute's name or sits in a typespec body."""
+ # Bounded by the statement, not a hop count: a union return type nests one
+ # binary_operator per member, so a typespec has no fixed depth.
+ ancestor: Node | None = node
+ while ancestor is not None:
+ holder = ancestor.parent
+ if holder is None or holder.type in _ELIXIR_STATEMENT_HOLDERS:
+ return False
+ if _elixir_is_attribute_operator(holder):
+ return (
+ ancestor.id == node.id
+ or _elixir_call_target_name(ancestor, src) in _ELIXIR_TYPESPEC_ATTRIBUTES
+ )
+ ancestor = holder
+ return False
+
+
+def _elixir_is_attribute_operator(node: Node) -> bool:
+ if node.type != "unary_operator":
+ return False
+ operator = node.child_by_field_name("operator")
+ return operator is not None and operator.type == "@"
+
+
+def _elixir_arguments(call_node: Node) -> Node | None:
+ return next((child for child in call_node.named_children if child.type == "arguments"), None)
+
+
+def _elixir_definition_alias(call_node: Node, src: str) -> str | None:
+ """The first ``alias`` argument of a definition call, i.e. its module name."""
+ arguments = _elixir_arguments(call_node)
+ if arguments is None or not arguments.named_children:
+ return None
+ first = arguments.named_children[0]
+ if first.type != "alias":
+ return None
+ return node_text(first, src).strip() or None
+
+
+def _elixir_defimpl_for_type(call_node: Node, src: str) -> str | None:
+ """The ``for:`` type of a ``defimpl Proto, for: Type`` block."""
+ arguments = _elixir_arguments(call_node)
+ if arguments is None:
+ return None
+ for child in arguments.named_children:
+ if child.type != "keywords":
+ continue
+ value = _elixir_keyword_value(child, "for", src)
+ if value is not None:
+ return node_text(value, src).strip() or None
+ return None
+
+
+def _elixir_keyword_value(keywords: Node, key_name: str, src: str) -> Node | None:
+ """The value node of the first ``key_name:`` pair in a keyword list."""
+ for pair in keywords.named_children:
+ key = pair.child_by_field_name("key")
+ value = pair.child_by_field_name("value")
+ if key is None or value is None:
+ continue
+ if node_text(key, src).strip().rstrip(":") == key_name:
+ return value
+ return None
+
+
+def _elixir_enclosing_module_alias(node: Node, src: str) -> str | None:
+ """The nearest enclosing ``defmodule``/``defprotocol`` name."""
+ ancestor = node.parent
+ while ancestor is not None:
+ if _elixir_call_target_name(ancestor, src) in ("defmodule", "defprotocol"):
+ return _elixir_definition_alias(ancestor, src)
+ ancestor = ancestor.parent
+ return None
+
+
+def _elixir_defimpl_name(call_node: Node, src: str) -> str | None:
+ """The module name the compiler generates for a ``defimpl`` block.
+
+ ``defimpl Printable, for: Tuple`` compiles to a module called
+ ``Printable.Tuple``, and that name is used here. Without it the
+ definitions inside the block are attributed to whatever module encloses it,
+ where they read as unused exports of a module that never declared them, and
+ two implementations of one protocol in one file mint two symbols under one
+ id.
+
+ The ``for:``-less form is only legal inside a ``defmodule`` and implements
+ the protocol for that module, so the enclosing module supplies the type.
+ """
+ protocol = _elixir_definition_alias(call_node, src)
+ if protocol is None:
+ return None
+ target_type = _elixir_defimpl_for_type(call_node, src) or _elixir_enclosing_module_alias(
+ call_node, src
+ )
+ return f"{protocol}.{target_type}" if target_type else protocol
+
+
+def _elixir_symbol_name(def_node: Node, default_name: str, src: str) -> str:
+ """The name a captured Elixir definition carries.
+
+ Only ``defimpl`` differs from its captured text; everything else names
+ itself. See ``_elixir_defimpl_name``.
+ """
+ if _elixir_call_target_name(def_node, src) != "defimpl":
+ return default_name
+ return _elixir_defimpl_name(def_node, src) or default_name
+
+
+def _elixir_is_template_definition(def_node: Node, src: str) -> bool:
+ """True for a definition inside ``quote do ... end``.
+
+ A ``def`` in a ``quote`` block is the body of a macro: it defines nothing in
+ the module that writes it and everything in the module that later invokes
+ the macro, which is a module no parser can name. Captured as a symbol it
+ reads as a method of the wrong module, and then as an unused export of it.
+ """
+ ancestor = def_node.parent
+ while ancestor is not None:
+ if _elixir_call_target_name(ancestor, src) == "quote":
+ return True
+ ancestor = ancestor.parent
+ return False
+
+
+def _elixir_module_parent(def_node: Node, src: str) -> str | None:
+ """Return the enclosing ``defmodule``/``defprotocol`` name, or None.
+
+ The generic nesting walk in ``ASTParser._find_parent`` reads
+ ``ancestor.child_by_field_name("name")``, and an Elixir ``call`` has no
+ ``name`` field -- the module name is the first argument of a call to
+ ``defmodule``. Nesting is the only thing that says which module a
+ function belongs to, so without this every ``def`` reads as a free
+ function.
+ """
+ ancestor = def_node.parent
+ while ancestor is not None:
+ keyword = _elixir_call_target_name(ancestor, src)
+ if keyword in _ELIXIR_MODULE_KEYWORDS:
+ if keyword == "defimpl":
+ return _elixir_defimpl_name(ancestor, src)
+ return _elixir_definition_alias(ancestor, src)
+ ancestor = ancestor.parent
+ return None
diff --git a/packages/core/src/repowise/core/ingestion/lang_helpers/fsharp.py b/packages/core/src/repowise/core/ingestion/lang_helpers/fsharp.py
new file mode 100644
index 000000000..2495861eb
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/lang_helpers/fsharp.py
@@ -0,0 +1,161 @@
+"""F# binding, nesting and owner-name helpers."""
+
+from __future__ import annotations
+
+from tree_sitter import Node
+
+from ..extractors import node_text
+
+# The two nodes fsharp.scm captures as @symbol.def for a `let` binding. One
+# `function_or_value_defn` holds every clause of a `let rec f ... and g ...`
+# group, so a clause is delimited by the next one of these, not by the node.
+_FSHARP_BINDING_LEFT = ("function_declaration_left", "value_declaration_left")
+
+# A binding whose ancestors include one of these sits inside another
+# binding's body, so it is a local, not a member of the module or type.
+_FSHARP_BODY_OWNERS = (
+ "function_or_value_defn",
+ "method_or_prop_defn",
+ "fun_expression",
+ # A top-level `do` block is executed code, not a declaration site.
+ "do",
+ "do_expression",
+)
+
+# Type shapes whose `type_name` child names the enclosing type of a member.
+_FSHARP_TYPE_OWNERS = (
+ "anon_type_defn",
+ "record_type_defn",
+ "union_type_defn",
+ "enum_type_defn",
+ "delegate_type_defn",
+ "type_abbrev_defn",
+ "type_extension",
+)
+
+
+def _fsharp_binding_is_nested(left_node: Node) -> bool:
+ """True when a ``let`` binding is local to another binding's body.
+
+ A nested ``let`` has the same node shape as a top-level one -- the
+ grammar distinguishes them only by what encloses them -- so the generic
+ callable-ancestor filter cannot see it: that filter looks for an
+ ancestor whose *own* type is a captured callable, and the captured node
+ here is the binding's left-hand side, never an ancestor of anything.
+ A ``let`` directly inside a type body is deliberately not nested: it is
+ that type's field.
+ """
+ ancestor = left_node.parent # the binding's own function_or_value_defn
+ ancestor = ancestor.parent if ancestor is not None else None
+ while ancestor is not None:
+ if ancestor.type in _FSHARP_BODY_OWNERS:
+ return True
+ ancestor = ancestor.parent
+ return False
+
+
+def _fsharp_binding_end_line(left_node: Node) -> int:
+ """Last line of the clause introduced by *left_node*, 1-indexed.
+
+ Walks forward to the next clause's left-hand side rather than taking the
+ left node's next sibling, because a return-type annotation
+ (``let f x : int = ...``) sits between the left node and the body.
+ """
+ parent = left_node.parent
+ if parent is None:
+ return left_node.end_point[0] + 1
+ end = left_node.end_point[0] + 1
+ seen = False
+ for child in parent.named_children:
+ if child.id == left_node.id:
+ seen = True
+ continue
+ if not seen:
+ continue
+ if child.type in _FSHARP_BINDING_LEFT or child.type == "xml_doc":
+ # A doc comment inside the defn belongs to the clause after it.
+ break
+ end = max(end, child.end_point[0] + 1)
+ return end
+
+
+def _fsharp_binding_has_params(left_node: Node) -> bool:
+ """True when a value_declaration_left actually binds a function.
+
+ let total (xs: int list) : int = ... has parameters, but the return
+ type makes the grammar read the whole head as one value pattern: the
+ name and every parameter pattern become siblings inside a single
+ identifier_pattern. A plain let x: int = 5 leaves that node with
+ the name alone, which is what separates the two.
+ """
+ holder = next(
+ (c for c in left_node.named_children if c.type == "identifier_pattern"), None
+ )
+ return holder is not None and holder.named_child_count > 1
+
+
+def _fsharp_parent_is_type(def_node: Node) -> bool:
+ """True when the innermost owner enclosing an F# symbol is a type rather
+ than a nested module.
+
+ A ``let`` inside ``module Inner = ...`` is still a plain function, not a
+ method -- only a type body turns a binding into a member. The generic
+ function-to-method promotion in parser.py has no notion of "module", so
+ it needs this to tell the two owners apart before promoting.
+ """
+ ancestor = def_node.parent
+ while ancestor is not None:
+ if ancestor.type in _FSHARP_TYPE_OWNERS:
+ return True
+ if ancestor.type == "module_defn":
+ return False
+ ancestor = ancestor.parent
+ return False
+
+
+def _fsharp_owner_name(owner: Node, src: str) -> str | None:
+ """The declared name of one F# type or nested-module node."""
+ if owner.type == "module_defn":
+ ident = next((c for c in owner.named_children if c.type == "identifier"), None)
+ return node_text(ident, src).strip() if ident is not None else None
+ name_node = _fsharp_type_name_node(owner)
+ if name_node is None:
+ return None
+ return node_text(name_node, src).strip() or None
+
+
+def _fsharp_type_name_node(owner: Node) -> Node | None:
+ """The node naming a type owner, reduced to the last segment of a dotted name."""
+ name_node = owner.child_by_field_name("type_name")
+ if name_node is None:
+ holder = next((c for c in owner.named_children if c.type == "type_name"), None)
+ name_node = holder.child_by_field_name("type_name") if holder else None
+ if name_node is None or name_node.type != "long_identifier":
+ return name_node
+ idents = [c for c in name_node.named_children if c.type == "identifier"]
+ return idents[-1] if idents else name_node
+
+
+def _fsharp_parent_name(def_node: Node, src: str) -> str | None:
+ """Return the dotted owner path of an F# symbol.
+
+ No F# type node carries a ``name`` field -- the name lives on a
+ ``type_name`` child, tagged with a ``type_name`` field of its own -- so
+ the generic nesting walk in ``_find_parent`` finds nothing to read.
+
+ Every enclosing nested module joins the path, not just the nearest
+ owner: one file may hold ``module A`` and ``module B`` each declaring a
+ ``type Dup`` with a ``Go`` member, and a symbol id is path plus parent
+ plus name, so a nearest-owner parent would give both members one id.
+ A file-level ``module``/``namespace`` header is skipped, since it is the
+ whole file and distinguishes nothing within it.
+ """
+ parts: list[str] = []
+ ancestor = def_node.parent
+ while ancestor is not None:
+ if ancestor.type in _FSHARP_TYPE_OWNERS or ancestor.type == "module_defn":
+ name = _fsharp_owner_name(ancestor, src)
+ if name:
+ parts.append(name)
+ ancestor = ancestor.parent
+ return ".".join(reversed(parts)) or None
diff --git a/packages/core/src/repowise/core/ingestion/lang_helpers/objc.py b/packages/core/src/repowise/core/ingestion/lang_helpers/objc.py
new file mode 100644
index 000000000..378931e11
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/lang_helpers/objc.py
@@ -0,0 +1,269 @@
+"""Objective-C naming, container, message-send and dedupe helpers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from tree_sitter import Node
+
+from ..extractors import node_text
+
+if TYPE_CHECKING:
+ from ..models import Symbol
+
+_OBJC_METHOD_NODE_TYPES = frozenset({"method_declaration", "method_definition"})
+_OBJC_CLASS_NODE_TYPES = frozenset({"class_interface", "class_implementation"})
+
+# A declaration and the definition that answers it, keyed the way the dedup
+# below pairs them.
+_OBJC_DEFINITION_NODE_TYPES = frozenset({"class_implementation", "method_definition"})
+_OBJC_DECLARATION_NODE_TYPES = frozenset({"class_interface", "method_declaration"})
+
+# Macros that expand to nothing but are spelled as a bare identifier, so the
+# grammar makes them a keyword child of the method they trail.
+_OBJC_TRAILING_MACRO_NAMES = frozenset({
+ "NS_DESIGNATED_INITIALIZER", "NS_UNAVAILABLE", "NS_REQUIRES_SUPER",
+ "NS_RETURNS_INNER_POINTER", "NS_REFINED_FOR_SWIFT", "NS_SWIFT_UI_ACTOR",
+ "NS_REQUIRES_NIL_TERMINATION", "UNAVAILABLE_ATTRIBUTE", "DEPRECATED_ATTRIBUTE",
+})
+
+# ``typedef NS_ENUM(NSInteger, Kind) { KindA }`` shapes. See _objc_is_macro_enum.
+_OBJC_ENUM_MACRO_NAMES = frozenset({
+ "NS_ENUM", "NS_OPTIONS", "NS_CLOSED_ENUM", "NS_ERROR_ENUM",
+ "CF_ENUM", "CF_OPTIONS", "CF_CLOSED_ENUM",
+})
+
+
+def _objc_selector_name(def_node: Node, default_name: str, src: str) -> str:
+ """Join a method's keyword parts into its full selector.
+
+ A keyword is an ``identifier`` child that a ``method_parameter`` follows;
+ anything trailing the last parameter is an attribute macro, not part of
+ the name. See the Objective-C section of the architecture doc.
+ """
+ if def_node.type not in _OBJC_METHOD_NODE_TYPES:
+ return default_name
+ parts = _objc_selector_keywords(def_node, src)
+ if parts:
+ return "".join(f"{p}:" for p in parts)
+ # No parameters at all: the selector is the first keyword, unadorned.
+ return _objc_unary_selector(def_node, src) or default_name
+
+
+def _objc_selector_keywords(def_node: Node, src: str) -> list[str]:
+ parts: list[str] = []
+ pending: str | None = None
+ for child in def_node.children:
+ if child.type == "identifier":
+ # Only an identifier followed by a method_parameter is a keyword;
+ # a trailing one is a macro such as NS_DESIGNATED_INITIALIZER.
+ pending = node_text(child, src).strip() or None
+ elif child.type == "method_parameter":
+ if pending is not None:
+ parts.append(pending)
+ pending = None
+ elif child.type in ("compound_statement", ";"):
+ break
+ return parts
+
+
+def _objc_unary_selector(def_node: Node, src: str) -> str | None:
+ first = next((c for c in def_node.children if c.type == "identifier"), None)
+ if first is None:
+ return None
+ text = node_text(first, src).strip()
+ if not text or text in _OBJC_TRAILING_MACRO_NAMES:
+ return None
+ return text
+
+
+def _objc_is_macro_enum(def_node: Node, src: str) -> bool:
+ """True for a ``typedef NS_ENUM(Type, Name) { … }`` typedef.
+
+ This grammar has no rule for the macro, so the name argument and the brace
+ body land in ERROR nodes and only the *enumerators* survive as
+ ``declarator`` children. Capturing those mints a symbol per enum case named
+ as though it were the type, and never one for the type itself, so the whole
+ typedef is skipped: no symbol beats a wrong one.
+ """
+ if def_node.type != "type_definition":
+ return False
+ for child in def_node.children:
+ if child.type != "macro_type_specifier":
+ continue
+ name = child.child_by_field_name("name")
+ if name is not None and node_text(name, src).strip() in _OBJC_ENUM_MACRO_NAMES:
+ return True
+ return False
+
+
+def _objc_category_name(def_node: Node, default_name: str, src: str) -> str:
+ """Name a category for the class it extends plus its own name.
+
+ Two categories on one class are two declarations about it, so naming both
+ for the class alone would merge them. A class extension (``Foo ()``) binds
+ no ``category`` field and keeps the plain name.
+ """
+ if def_node.type not in _OBJC_CLASS_NODE_TYPES:
+ return default_name
+ category = def_node.child_by_field_name("category")
+ if category is None:
+ return default_name
+ text = node_text(category, src).strip()
+ return f"{default_name}({text})" if text else default_name
+
+
+def _objc_symbol_name(def_node: Node, default_name: str, src: str) -> str:
+ """The name a captured Objective-C definition carries."""
+ if def_node.type in _OBJC_METHOD_NODE_TYPES:
+ return _objc_selector_name(def_node, default_name, src)
+ return _objc_category_name(def_node, default_name, src)
+
+
+def _objc_container_node(def_node: Node, container_types: frozenset[str]) -> Node | None:
+ """The ``@interface`` / ``@implementation`` / ``@protocol`` around a member."""
+ ancestor = def_node.parent
+ while ancestor is not None:
+ if ancestor.type in container_types:
+ return ancestor
+ ancestor = ancestor.parent
+ return None
+
+
+def _objc_container_parent(def_node: Node, container_types: frozenset[str], src: str) -> str | None:
+ """The name of the container a method or property is declared in.
+
+ The generic nesting walk finds the same ancestor and then reads a ``name``
+ field these nodes do not have: each carries its name as a bare first
+ ``identifier`` child. Members of a category take the category's own name.
+ """
+ container = _objc_container_node(def_node, container_types)
+ if container is None:
+ return None
+ identifier = next((c for c in container.children if c.type == "identifier"), None)
+ if identifier is None:
+ return None
+ name = node_text(identifier, src).strip()
+ return _objc_category_name(container, name, src) if name else None
+
+
+def _objc_message_selector(site_node: Node, target_node: Node, src: str) -> str | None:
+ """Join a message send's keyword parts, or None for a repeat match.
+
+ ``[view setTitle:t forState:s]`` binds one ``method:`` child per keyword,
+ so the one query pattern matches once per keyword. Returns the joined
+ selector for the match carrying the first keyword and None for every later
+ one, so the extra matches are dropped rather than emitted as targets that
+ name nothing. The node's own ``:`` tokens say whether the selector takes
+ arguments: ``[obj run]`` is ``run`` and ``[obj run:x]`` is ``run:``.
+ """
+ methods = site_node.children_by_field_name("method")
+ if not methods or methods[0].id != target_node.id:
+ return None
+ parts = [node_text(m, src).strip() for m in methods]
+ parts = [p for p in parts if p]
+ if not parts:
+ return None
+ takes_arguments = any(c.type == ":" for c in site_node.children)
+ if not takes_arguments:
+ return parts[0]
+ return "".join(f"{p}:" for p in parts)
+
+
+def _objc_call_is_block_variable(site_node: Node, target_name: str, src: str) -> bool:
+ """True when a bare-identifier call invokes a block held in a variable.
+
+ Objective-C invokes a block with C call syntax, so ``completionBlock(hit)``
+ is a ``call_expression`` on a bare identifier that nothing in the grammar
+ separates from a call to a C function. Names like this are ubiquitous as
+ both a parameter and a ``@property``, so without the scope check the
+ resolver binds the invocation to an unrelated class's property.
+ """
+ node: Node | None = site_node
+ while node is not None:
+ if node.type == "compound_statement":
+ if _objc_block_declares(node, target_name, src):
+ return True
+ elif node.type == "method_definition":
+ return any(
+ child.type == "method_parameter"
+ and _objc_declares_name(child, target_name, src)
+ for child in node.children
+ )
+ elif node.type == "function_definition":
+ declarator = node.child_by_field_name("declarator")
+ return declarator is not None and _objc_declares_name(declarator, target_name, src)
+ node = node.parent
+ return False
+
+
+def _objc_block_declares(block: Node, name: str, src: str) -> bool:
+ """True when a statement directly in *block* declares *name*."""
+ return any(
+ statement.type == "declaration" and _objc_declares_name(statement, name, src)
+ for statement in block.named_children
+ )
+
+
+def _objc_declares_name(node: Node, name: str, src: str) -> bool:
+ """True when *node* binds *name* as a parameter or a variable.
+
+ A declarator nests (``void (^block)(int)``, ``Handler done = ^{}``), so
+ every identifier under the node is checked rather than only the direct
+ children. The node is a parameter or a declaration, never a body, so the
+ walk stays small; a nested block body is skipped for the same reason.
+ """
+ stack = [node]
+ while stack:
+ current = stack.pop()
+ if current.type in ("identifier", "field_identifier"):
+ if node_text(current, src).strip() == name:
+ return True
+ elif current.type != "compound_statement":
+ stack.extend(current.children)
+ return False
+
+
+def _objc_container_family(container_kind: str | None) -> str | None:
+ """Which namespace a member belongs to: a protocol's, or a class's.
+
+ An ``@interface`` and its ``@implementation`` are the same class, so a
+ declaration in one must still dedupe against a definition in the other; a
+ ``@protocol`` of the same name is a different thing entirely.
+ """
+ return "protocol" if container_kind == "protocol_declaration" else container_kind and "class"
+
+
+def _dedupe_objc_interface_symbols(
+ symbols: list[Symbol], node_types: list[str], container_kinds: list[str | None]
+) -> list[Symbol]:
+ """Collapse a declaration into the definition standing beside it.
+
+ A ``.m`` routinely opens with a class extension (``@interface Foo ()``)
+ declaring the private methods its ``@implementation Foo`` then defines, so
+ each builds the same symbol id twice in one file. The definition wins: it
+ carries the body. Across two files the split is real and both symbols are
+ kept, marked with ``is_declaration`` the way a C header's prototype and its
+ ``.c`` definition already are.
+
+ The key carries the container kind because a protocol and a class may share
+ a name in one file, and ``-ping`` on the protocol is then a different method
+ from ``-ping`` on the class. Keyed on the name and not the signature:
+ Objective-C has no overloading, and a declaration and its definition
+ routinely differ in parameter names and nullability annotations.
+ """
+ definition_keys = {
+ (_objc_container_family(kind), s.parent_name, s.name)
+ for s, nt, kind in zip(symbols, node_types, container_kinds, strict=True)
+ if nt in _OBJC_DEFINITION_NODE_TYPES
+ }
+ seen_declarations: set[tuple[str | None, str | None, str]] = set()
+ kept: list[Symbol] = []
+ for symbol, node_type, kind in zip(symbols, node_types, container_kinds, strict=True):
+ if node_type in _OBJC_DECLARATION_NODE_TYPES:
+ key = (_objc_container_family(kind), symbol.parent_name, symbol.name)
+ if key in definition_keys or key in seen_declarations:
+ continue
+ seen_declarations.add(key)
+ kept.append(symbol)
+ return kept
diff --git a/packages/core/src/repowise/core/ingestion/lang_helpers/pascal.py b/packages/core/src/repowise/core/ingestion/lang_helpers/pascal.py
new file mode 100644
index 000000000..744f010ae
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/lang_helpers/pascal.py
@@ -0,0 +1,79 @@
+"""Pascal qualified-parent and interface/implementation dedupe helpers."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from tree_sitter import Node
+
+from ..extractors import node_text
+
+if TYPE_CHECKING:
+ from ..models import Symbol
+
+_WHITESPACE_RE = re.compile(r"\s+")
+
+
+def _qualified_pascal_parent(name_node: Node, src: str) -> str | None:
+ """Return the owning class for a Pascal out-of-line method header.
+
+ In ``function TCalculator.Add(...)`` the captured name is the
+ ``genericDot``'s ``rhs`` and the class is its ``lhs``. Nesting cannot find
+ it: the ``defProc`` sits in the implementation section, outside the
+ class's ``declType``. Handles the plain and the generic-method
+ (``rhs: genericTpl``) shapes. Reads with ``node_text`` because slicing a
+ decoded ``str`` by byte offsets misaligns on non-ASCII identifiers.
+
+ Returns ``None`` for a free function/procedure.
+ """
+ parent = name_node.parent
+ if parent is not None and parent.type == "genericTpl":
+ parent = parent.parent
+ if parent is None or parent.type != "genericDot":
+ return None
+ lhs = parent.child_by_field_name("lhs")
+ if lhs is None:
+ return None
+ text = node_text(lhs, src).strip()
+ return text or None
+
+
+def _dedupe_pascal_interface_symbols(
+ symbols: list[Symbol], node_types: list[str]
+) -> list[Symbol]:
+ """Drop an interface-section method signature once its implementation
+ is also present, so the two don't become two graph nodes for one method.
+
+ Pascal declares a signature in the ``interface`` section (``declProc``,
+ no body) and the body in ``implementation`` (``defProc``). Once both
+ resolve to one parent, only the ``defProc`` is kept, since it carries the
+ body ``get_symbol`` should return.
+
+ Keyed on the normalized signature (see ``_pascal_dedupe_key``) rather than
+ the name, so an interface-only ``overload;`` sibling survives when a
+ different overload of the same name is implemented. Parameter names need
+ not match between the two halves in Pascal, so a renamed parameter still
+ defeats the dedupe and leaves both symbols.
+ """
+ impl_keys = {
+ _pascal_dedupe_key(s.parent_name, s.signature)
+ for s, nt in zip(symbols, node_types, strict=True)
+ if nt == "defProc"
+ }
+ return [
+ s
+ for s, nt in zip(symbols, node_types, strict=True)
+ if not (nt == "declProc" and _pascal_dedupe_key(s.parent_name, s.signature) in impl_keys)
+ ]
+
+
+def _pascal_dedupe_key(parent_name: str | None, signature: str) -> tuple[str | None, str]:
+ """Normalize a (parent, signature) pair for Pascal's interface/impl dedup.
+
+ Whitespace-insensitive, because the two halves wrap long parameter lists
+ differently, and case-insensitive, because Pascal identifiers are.
+ """
+ parent_key = parent_name.lower() if parent_name else None
+ sig_key = _WHITESPACE_RE.sub("", signature).lower()
+ return (parent_key, sig_key)
diff --git a/packages/core/src/repowise/core/ingestion/lang_helpers/source_prep.py b/packages/core/src/repowise/core/ingestion/lang_helpers/source_prep.py
new file mode 100644
index 000000000..578e50cba
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/lang_helpers/source_prep.py
@@ -0,0 +1,119 @@
+"""Byte-preserving source sanitizers for grammar gaps in Pascal and Objective-C."""
+
+from __future__ import annotations
+
+import re
+
+_PASCAL_USES_IN_CLAUSE_RE = re.compile(rb"\bin\b[ \t]*'(?:[^'\r\n]|'')*'")
+
+
+def _sanitize_pascal_project_source(source: bytes) -> bytes:
+ """Blank Delphi/FPC project-file ``unit in 'path.pas'`` clauses.
+
+ ``.dpr``/``.dpk``/``.lpr`` files map units to paths in the ``uses``
+ clause (``uses MyUnit in 'src\\MyUnit.pas';``), and the Delphi IDE writes
+ that form for every unit it adds. tree-sitter-pascal has no rule for it:
+ error recovery folds the ``in``, the path and every later unit into one
+ corrupt ``moduleName`` node, so the rest of the ``uses`` list is lost before
+ any query runs. The regex keeps a doubled ``''`` inside the literal.
+ """
+ return _blank_matches(source, _PASCAL_USES_IN_CLAUSE_RE)
+
+
+def _blank_matches(source: bytes, pattern: re.Pattern[bytes]) -> bytes:
+ """Overwrite every match of *pattern* with spaces, keeping the length.
+
+ The shared half of every byte-preserving source sanitizer: a construct the
+ grammar has no rule for is replaced in place, never removed, so line
+ numbers and byte offsets for everything else in the file survive. Spaces
+ and never a newline, so no pattern can consume a line break it did not
+ match.
+ """
+ if not pattern.search(source):
+ return source
+ out = bytearray(source)
+ for match in pattern.finditer(source):
+ start, end = match.span()
+ out[start:end] = b" " * (end - start)
+ return bytes(out)
+
+
+_PASCAL_PROJECT_EXTENSIONS = (".dpr", ".dpk", ".lpr")
+
+
+def prepare_pascal_source(source: bytes, path: str | None) -> bytes:
+ """Single entry point for every Pascal byte-preserving sanitizer.
+
+ Called through :func:`~.sfc_source.prepare_source`, the hook the parser and
+ the health walkers already run before parsing, so ``parser.py`` needs no
+ Pascal branch. Gated on *path*'s extension because the ``in '...'`` syntax
+ is invalid in a plain unit file.
+
+ An anonymous ``array[...] of record`` element type still parses badly and
+ is not blanked here: its ERROR spans can cover the class's own closing
+ ``end;``, so blanking them breaks the structure they meant to fix. That
+ case degrades to a wrong parent for the one class, like any grammar gap.
+ """
+ if path and path.lower().endswith(_PASCAL_PROJECT_EXTENSIONS):
+ return _sanitize_pascal_project_source(source)
+ return source
+
+
+# Whole-line macros that expand to nothing a parser needs but which this
+# grammar reads as the start of a C declaration, swallowing whatever follows
+# into an ERROR node. Only bare whole-line forms are listed: a macro that
+# opens a real declaration (``FOUNDATION_EXPORT NSString *const kFoo;``) must
+# stay, and a call-shaped one (``NS_ENUM(NSInteger, Kind)``) is a different
+# problem that blanking a line cannot fix.
+_OBJC_BARE_MACRO_LINE_RE = re.compile(
+ rb"^[ \t]*(?:NS_ASSUME_NONNULL_BEGIN|NS_ASSUME_NONNULL_END"
+ rb"|NS_HEADER_AUDIT_BEGIN\([^)\r\n]*\)|NS_HEADER_AUDIT_END"
+ rb"|CF_ASSUME_NONNULL_BEGIN|CF_ASSUME_NONNULL_END"
+ rb"|NS_REFINED_FOR_SWIFT|NS_SWIFT_UI_ACTOR)[ \t]*(?=\r?\n|$)",
+ re.MULTILINE,
+)
+
+
+# Availability / naming attributes written call-shaped after a declaration
+# (``- (void)done NS_SWIFT_NAME(done())``). The grammar reads the macro as a
+# declarator it cannot close, recovery fails to resync at the ``;``, and every
+# later call in the file loses its enclosing method.
+#
+# Enumerated by name because ``NS_ENUM(NSInteger, Kind)`` and
+# ``NSLog(@"%@", x)`` share the ``IDENT(...)`` shape. Only a form that ends a
+# declaration qualifies: followed by ``;``, a body's ``{``, or end of line. The
+# same name before a ``,`` or ``)`` is left alone.
+_OBJC_TRAILING_MACRO_RE = re.compile(
+ rb"(?<![A-Za-z0-9_])(?:AF_API_AVAILABLE|API_AVAILABLE|API_DEPRECATED"
+ rb"|NS_SWIFT_NAME|NS_AVAILABLE|NS_DEPRECATED)"
+ rb"\((?:[^()\r\n]|\([^()\r\n]*\))*\)[ \t]*(?=[;{]|\r?$)",
+ re.MULTILINE,
+)
+
+
+def _blank_objc_trailing_macros(source: bytes) -> bytes:
+ """Blank trailing call-shaped attribute macros, keeping the terminator.
+
+ The ``;``/``{`` the pattern looks ahead to stays in place so the
+ declaration itself still ends where it always did; only the macro's own
+ span is overwritten. Same offset contract as every other sanitizer here.
+ """
+ return _blank_matches(source, _OBJC_TRAILING_MACRO_RE)
+
+
+def prepare_objectivec_source(source: bytes) -> bytes:
+ """Blank nullability-audit macros, bare and call-shaped, preserving offsets.
+
+ ``NS_ASSUME_NONNULL_BEGIN`` is not a preprocessor directive and this
+ grammar has no rule for it, so it parses as the opening of a C declaration
+ and error recovery folds the whole ``@interface … @end`` block after it
+ into one ERROR node. The macro wraps almost every modern Objective-C
+ header, so this is the dominant parse failure in real source.
+
+ The same failure has a second shape: a declaration whose *last* token is a
+ call-shaped availability attribute (``API_AVAILABLE(ios(10))``,
+ ``NS_SWIFT_NAME(...)``). There the recovery never resyncs at the closing
+ ``;``, so one trailing attribute derails the remainder of the file. Both
+ passes blank in place, so every offset outside a match is unchanged.
+ """
+ return _blank_objc_trailing_macros(_blank_matches(source, _OBJC_BARE_MACRO_LINE_RE))
diff --git a/packages/core/src/repowise/core/ingestion/lang_helpers/type_heads.py b/packages/core/src/repowise/core/ingestion/lang_helpers/type_heads.py
new file mode 100644
index 000000000..7616a467b
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/lang_helpers/type_heads.py
@@ -0,0 +1,693 @@
+"""Per-language head-identifier extractors for ``@param.type`` captures."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from tree_sitter import Node
+
+from ..extractors import fsharp_type_name, node_text
+from ..language_data import get_builtin_types
+from ..type_names import is_resolvable_type_name
+
+_PARAM_ORIGIN_BY_ANCESTOR: dict[str, str] = {
+ "type_argument_list": "generic_argument",
+ "typeof_expression": "typeof",
+ "constructor_declaration": "ctor_param",
+ "method_declaration": "method_param",
+ "delegate_declaration": "delegate_param",
+ "record_declaration": "ctor_param",
+ "class_declaration": "ctor_param",
+ "struct_declaration": "ctor_param",
+ # Go type positions — node types are Go-only so they never collide with
+ # the C# entries above. The origin is provenance only; resolution treats
+ # all type-use edges equally.
+ "field_declaration": "field_type",
+ "parameter_declaration": "param_type",
+ "composite_literal": "composite_literal",
+ # TypeScript / JavaScript type positions. Walk-up matches the nearest
+ # enclosing declaration; the parameter / field / heritage nodes sit
+ # closer than ``class_declaration`` so this dispatch is unambiguous.
+ "required_parameter": "param_type",
+ "optional_parameter": "param_type",
+ "property_signature": "field_type",
+ "public_field_definition": "field_type",
+ "function_declaration": "return_type",
+ "method_definition": "return_type",
+ "method_signature": "return_type",
+ "arrow_function": "return_type",
+ "function_signature": "return_type",
+ "type_alias_declaration": "type_alias",
+ "type_parameter": "generic_constraint",
+ "extends_clause": "extends",
+ "extends_type_clause": "extends",
+ "implements_clause": "implements",
+ # JVM (Java + Kotlin) type positions. Note: ``parameter`` is NOT
+ # mapped here because tree-sitter-c-sharp also uses ``parameter``
+ # for ctor params and adding it would override C#'s walk to the
+ # enclosing ``constructor_declaration``. Kotlin function-parameter
+ # origin therefore falls through to ``function_declaration`` →
+ # "return_type" (imprecise but harmless — origin is provenance only).
+ "formal_parameter": "param_type",
+ "object_creation_expression": "composite_literal",
+ "local_variable_declaration": "field_type",
+ "superclass": "extends",
+ "super_interfaces": "implements",
+ "type_list": "implements",
+ "class_parameter": "ctor_param", # Kotlin primary-ctor parameter
+ "variable_declaration": "field_type", # Kotlin property declaration
+ "delegation_specifier": "extends", # Kotlin class : Bar()
+ # Pascal type positions — node types are Pascal-only, no collision risk.
+ "declField": "field_type",
+ "declArg": "param_type",
+ "declVar": "local_var_type",
+ "declProc": "return_type",
+ "exprArgs": "framework_ctor", # Application.CreateForm(TClass, Var)
+}
+
+
+def _classify_param_origin(type_node: Node) -> str:
+ """Walk up to find the enclosing declaration and map to an origin tag.
+
+ The walk stops at the first matching ancestor or after a small depth
+ cap. Falling off the cap means the capture was outside a recognised
+ declaration shape (shouldn't happen given the query patterns, but
+ guards against grammar drift); we tag those ``method_param``.
+ """
+ cur: Node | None = type_node
+ for _ in range(8):
+ if cur is None:
+ break
+ origin = _PARAM_ORIGIN_BY_ANCESTOR.get(cur.type)
+ if origin is not None:
+ return origin
+ cur = cur.parent
+ return "method_param"
+
+
+# ---------------------------------------------------------------------------
+# Shared walk
+# ---------------------------------------------------------------------------
+
+# One step of a head walk: the head's text when this node names the type, the
+# node to descend into when it wraps one, or None when there is no single head.
+HeadStep = Callable[[Node, str], str | Node | None]
+
+
+def _walk_to_head(type_node: Node, src: str, step: HeadStep, max_depth: int) -> str | None:
+ """Follow *step* down from *type_node* until it yields the head's text."""
+ node: Node | None = type_node
+ for _ in range(max_depth):
+ if node is None:
+ return None
+ outcome = step(node, src)
+ if isinstance(outcome, str):
+ return outcome
+ node = outcome
+ return None
+
+
+def _resolvable(text: str | None, language: str) -> str | None:
+ return text if text and is_resolvable_type_name(text, language) else None
+
+
+def _first_named_child(node: Node) -> Node | None:
+ return node.named_children[0] if node.named_children else None
+
+
+def _first_descendant(node: Node, type_name: str) -> Node | None:
+ stack = [node]
+ while stack:
+ current = stack.pop()
+ if current.type == type_name:
+ return current
+ stack.extend(current.children)
+ return None
+
+
+# ---------------------------------------------------------------------------
+# C# (the default extractor)
+# ---------------------------------------------------------------------------
+
+_CSHARP_MODIFIER_TYPES = ("nullable_type", "ref_type", "pointer_type", "array_type")
+_CSHARP_MODIFIER_TRIVIA = (",", "?", "*", "&", "ref", "out", "in", "[", "]")
+
+
+def _head_type_identifier(type_node: Node, src: str) -> str | None:
+ """Return the head identifier of a C# type expression, or None.
+
+ Examples:
+ ``IBasketService`` → "IBasketService"
+ ``IList<Basket>`` → "IList"
+ ``Acme.Catalog.IRepository<T>`` → "IRepository"
+ ``ref readonly Span<byte>`` → "Span"
+ ``string`` → None (built-in)
+ ``int?`` → None
+ ``T`` → None (likely a generic param)
+
+ The point of returning the head identifier is that the
+ DotNetProjectIndex type-name lookup is keyed by unqualified type
+ name. Generic-arg recursion is intentionally NOT done here — each generic
+ argument is captured from its own ``type_argument_list`` node, including
+ nested arguments and invocation-only type uses.
+ """
+ head_node = _csharp_unwrap_modifiers(type_node)
+ if head_node is None or head_node.type == "tuple_type":
+ # Tuple elements aren't single types.
+ return None
+ return _resolvable(_csharp_head_text(head_node, src), "csharp")
+
+
+def _csharp_unwrap_modifiers(type_node: Node) -> Node | None:
+ """Strip nullable / ref / pointer / array shells down to the named type.
+
+ tree-sitter-c-sharp puts the inner type at field ``type`` or as the first
+ non-trivia child.
+ """
+ head_node: Node | None = type_node
+ for _ in range(6):
+ if head_node is None or head_node.type not in _CSHARP_MODIFIER_TYPES:
+ return head_node
+ inner = head_node.child_by_field_name("type")
+ if inner is None:
+ inner = next(
+ (c for c in head_node.children if c.type not in _CSHARP_MODIFIER_TRIVIA),
+ None,
+ )
+ head_node = inner
+ return head_node
+
+
+def _csharp_head_text(head_node: Node, src: str) -> str:
+ kind = head_node.type
+ if kind in ("identifier", "predefined_type"):
+ return node_text(head_node, src)
+ if kind == "generic_name":
+ name_child = head_node.child_by_field_name("name") or next(
+ (c for c in head_node.children if c.type == "identifier"),
+ None,
+ )
+ return node_text(name_child, src) if name_child else ""
+ if kind == "qualified_name":
+ # `Foo.Bar.Baz` — take the rightmost identifier
+ idents = [c for c in head_node.children if c.type == "identifier"]
+ return node_text(idents[-1], src) if idents else ""
+ # Unknown shape — fall back to first identifier in the subtree
+ ident = _first_descendant(head_node, "identifier")
+ return node_text(ident, src) if ident else ""
+
+
+# ---------------------------------------------------------------------------
+# Go type-reference head extraction
+# ---------------------------------------------------------------------------
+
+# Go shells that name their inner type by field.
+_GO_INNER_FIELD = {
+ "generic_type": "type",
+ "slice_type": "element",
+ "array_type": "element",
+ "map_type": "value",
+ "channel_type": "value",
+}
+
+
+def _go_head_type_identifier(type_node: Node, src: str) -> str | None:
+ """Return the head type name of a Go type expression, or None.
+
+ Unwraps the modifier shells Go layers around a named type so the
+ resolver sees the bare identifier it indexes by:
+
+ ``Options`` → "Options"
+ ``*Cache`` → "Cache"
+ ``[]Partition`` → "Partition"
+ ``map[string]Config`` → "Config" (value type; string filtered)
+ ``chan Event`` → "Event"
+ ``dynacache.Cache`` → "Cache" (qualifier dropped)
+ ``List[Inner]`` → "List" (generic head)
+ ``string`` / ``int`` → None (builtin)
+ ``(Foo, error)`` → None (parameter_list; the inner
+ declarations are captured
+ separately)
+ ``interface{...}`` / ``struct{...}`` / ``func(...)`` → None (anonymous)
+
+ The qualifier in ``pkg.Cache`` is intentionally dropped: the Go type-ref
+ strategy resolves the bare name against same-package siblings and
+ imported package files, mirroring the Rust strategy. Keeping the head
+ name unqualified matches the symbol-index keys.
+ """
+ return _resolvable(_walk_to_head(type_node, src, _go_head_step, 8), "go")
+
+
+def _go_head_step(node: Node, src: str) -> str | Node | None:
+ kind = node.type
+ if kind == "type_identifier":
+ return node_text(node, src)
+ if kind == "qualified_type":
+ name = node.child_by_field_name("name") or next(
+ (c for c in reversed(node.children) if c.type == "type_identifier"),
+ None,
+ )
+ return node_text(name, src) if name else ""
+ field = _GO_INNER_FIELD.get(kind)
+ if field is not None:
+ return node.child_by_field_name(field)
+ if kind in ("pointer_type", "parenthesized_type"):
+ # No field name on the inner type — take the first named child.
+ return _first_named_child(node)
+ # parameter_list (multi-return), interface_type, struct_type,
+ # function_type, and anything else: no single named type to resolve.
+ return None
+
+
+# ---------------------------------------------------------------------------
+# C / C++ type-reference head extraction
+# ---------------------------------------------------------------------------
+
+_C_AGGREGATE_SPECIFIERS = ("struct_specifier", "union_specifier", "enum_specifier", "class_specifier")
+
+
+def _c_head_type_identifier(type_node: Node, src: str) -> str | None:
+ """Return the head type name of a C / C++ type expression, or None.
+
+ In C the pointer / array shells wrap the *declarator*, not the type,
+ so the captured ``type:`` field is the bare type node:
+
+ ``JSON_Value`` → "JSON_Value"
+ ``struct JSON_Object`` → "JSON_Object" (named struct ref)
+ ``int`` / ``unsigned long`` → None (primitive)
+ ``size_t`` → None (stdlib typedef)
+ ``Acme::Widget`` (C++) → "Widget" (rightmost name)
+ ``std::vector<T>`` (C++) → "vector" (template head)
+ anonymous ``struct {...}`` → None
+ """
+ # cpp shares this extractor; the builtin set is identical for both.
+ return _resolvable(_walk_to_head(type_node, src, _c_head_step, 6), "c")
+
+
+def _c_head_step(node: Node, src: str) -> str | Node | None:
+ kind = node.type
+ if kind == "type_identifier":
+ return node_text(node, src)
+ if kind in ("primitive_type", "sized_type_specifier"):
+ return None
+ if kind in _C_AGGREGATE_SPECIFIERS:
+ name = node.child_by_field_name("name")
+ # An anonymous aggregate has no named type to resolve.
+ return node_text(name, src) if name is not None else None
+ if kind == "template_type":
+ return node.child_by_field_name("name")
+ if kind == "qualified_identifier":
+ # ``NS::Type`` — take the rightmost name component.
+ name = node.child_by_field_name("name")
+ if name is not None:
+ return name
+ return node.named_children[-1] if node.named_children else None
+ # type_qualifier (const/volatile) wrappers and anything else:
+ # descend into the first named child.
+ return _first_named_child(node)
+
+
+# ---------------------------------------------------------------------------
+# TypeScript / JavaScript type-reference head extraction
+# ---------------------------------------------------------------------------
+
+# Shapes whose head is not a single name. The leaves inside them are captured
+# by their own ``@param.type`` patterns, so they still resolve.
+_TS_NO_SINGLE_HEAD = frozenset({
+ "predefined_type",
+ "union_type", "intersection_type", "function_type",
+ "constructor_type", "object_type", "literal_type",
+ "tuple_type", "conditional_type", "mapped_type",
+ "index_type_query", "type_query", "lookup_type",
+ "template_literal_type", "infer_type", "readonly_type",
+})
+
+
+def _ts_head_type_identifier(type_node: Node, src: str) -> str | None:
+ """Return the head identifier of a TypeScript/JavaScript type, or None.
+
+ Unwraps the modifier shells TS layers around a named type so the
+ resolver sees the bare identifier:
+
+ ``Foo`` → "Foo"
+ ``Foo[]`` → "Foo" (array_type)
+ ``Promise<Foo>`` → "Promise" → filtered (builtin)
+ ``ns.Foo`` → "Foo" (nested_type_identifier)
+ ``Foo | null`` → None (union — ambiguous head)
+ ``(x: A) => B`` → None (function_type — A/B are
+ captured separately as their
+ own param/return positions)
+ ``{ x: number }`` → None (anonymous object type)
+ ``string`` / ``number`` → None (predefined / builtin)
+ ``T`` → None (single-uppercase generic)
+
+ Union / intersection / function / object types return None because
+ the head isn't a single name; the underlying parameter / field
+ captures for each leaf already produced their own ``@param.type``
+ captures so the bare leaves are still resolved.
+ """
+ return _resolvable(_walk_to_head(type_node, src, _ts_head_step, 8), "typescript")
+
+
+def _ts_head_step(node: Node, src: str) -> str | Node | None:
+ kind = node.type
+ if kind in ("type_identifier", "identifier"):
+ # ``extends_clause`` of a class uses ``identifier`` (E in
+ # ``class D extends E``); treat it as a type name.
+ return node_text(node, src)
+ if kind in _TS_NO_SINGLE_HEAD:
+ return None
+ if kind == "generic_type":
+ # ``Foo<T>`` — descend to the bare name; generic args are
+ # captured separately if they hold user types.
+ return node.child_by_field_name("name") or next(
+ (c for c in node.named_children if c.type != "type_arguments"),
+ None,
+ )
+ if kind == "nested_type_identifier":
+ # ``ns.Foo`` — rightmost name component is the type itself.
+ return node.child_by_field_name("name") or next(
+ (c for c in reversed(node.named_children) if c.type == "type_identifier"),
+ None,
+ )
+ # ``T[]``, parentheses, a stray type_annotation, a ``constraint`` and
+ # anything else (type_predicate, asserts, ...) wrap the type as their
+ # first named child.
+ return _first_named_child(node)
+
+
+# ---------------------------------------------------------------------------
+# Java type-reference head extraction
+# ---------------------------------------------------------------------------
+
+_JAVA_PRIMITIVE_TYPES = ("void_type", "integral_type", "floating_point_type", "boolean_type")
+
+
+def _java_head_type_identifier(type_node: Node, src: str) -> str | None:
+ """Return the head type identifier of a Java type expression, or None.
+
+ Examples:
+ ``Bar`` → "Bar"
+ ``java.util.List<Foo>`` → "List" → filtered (builtin)
+ ``com.x.y.Z`` → "Z"
+ ``Foo.Bar`` → "Bar" (inner type)
+ ``Foo[]`` → "Foo"
+ ``int`` / ``void`` / ``long`` → None
+ ``T`` → None (generic parameter)
+ """
+ return _resolvable(_walk_to_head(type_node, src, _java_head_step, 8), "java")
+
+
+def _java_head_step(node: Node, src: str) -> str | Node | None:
+ kind = node.type
+ if kind == "type_identifier":
+ return node_text(node, src)
+ if kind in _JAVA_PRIMITIVE_TYPES:
+ return None
+ if kind == "scoped_type_identifier":
+ # ``com.x.y.Z`` / ``Foo.Bar`` — take the rightmost type_identifier
+ inner_ids = [c for c in node.children if c.type == "type_identifier"]
+ return node_text(inner_ids[-1], src) if inner_ids else None
+ if kind == "generic_type":
+ # ``Foo<T>`` — descend to the bare name; generic args are
+ # captured separately by their own type_arguments inner captures.
+ return next(
+ (c for c in node.named_children
+ if c.type in ("type_identifier", "scoped_type_identifier")),
+ None,
+ )
+ if kind == "annotated_type":
+ # ``@NonNull Foo`` — last named child is the type.
+ return next(
+ (c for c in reversed(node.named_children)
+ if c.type not in ("annotation", "marker_annotation")),
+ None,
+ )
+ # ``Foo[]`` and anything else (wildcard, type_parameter, ...): descend.
+ return _first_named_child(node)
+
+
+# ---------------------------------------------------------------------------
+# Kotlin type-reference head extraction
+# ---------------------------------------------------------------------------
+
+def _kotlin_head_type_identifier(type_node: Node, src: str) -> str | None:
+ """Return the head identifier of a Kotlin type expression, or None.
+
+ Examples:
+ ``Bar`` → "Bar"
+ ``Foo?`` → "Foo" (nullable_type unwrapped)
+ ``List<Foo>`` → "List" → filtered (builtin)
+ ``com.x.Foo`` → "Foo" (dotted user_type)
+ ``Foo.Bar`` → "Bar"
+ ``() -> Foo`` → None (function_type — skipped)
+ ``Unit`` / ``Any`` / ``String`` → None (builtin)
+ """
+ return _resolvable(_walk_to_head(type_node, src, _kotlin_head_step, 8), "kotlin")
+
+
+def _kotlin_head_step(node: Node, src: str) -> str | Node | None:
+ kind = node.type
+ if kind == "user_type":
+ # ``Foo`` / ``Foo<...>`` / ``ns.Foo``.
+ # Children: identifier, type_arguments, possibly more dotted parts.
+ # Rightmost identifier is the head; type_arguments contains the
+ # generic args (captured separately by their own type-ref).
+ inner_ids = [c for c in node.children if c.type == "identifier"]
+ return node_text(inner_ids[-1], src) if inner_ids else None
+ if kind == "identifier":
+ return node_text(node, src)
+ if kind in ("function_type", "parenthesized_type"):
+ # () -> Foo, (() -> Foo) — leaf type names are not captured.
+ return None
+ # ``Foo?``, a type_reference, a ``<out Foo>`` projection and anything
+ # else wrap the type as their first named child.
+ return _first_named_child(node)
+
+
+# ---------------------------------------------------------------------------
+# Rust type-reference head extraction
+# ---------------------------------------------------------------------------
+
+# Builtin, or no single head name to resolve.
+_RUST_NO_SINGLE_HEAD = (
+ "primitive_type", "tuple_type", "unit_type", "array_type",
+ "function_type", "never_type", "empty_type",
+)
+
+
+def _rust_head_type_identifier(type_node: Node, src: str) -> str | None:
+ """Return the head identifier of a Rust type expression, or None.
+
+ tree-sitter-rust spells a type name ``type_identifier`` where the
+ C#-shaped default expects ``identifier``, and a scoped path keeps the type
+ in its ``name`` field, so the default cannot serve.
+
+ Examples:
+ ``MyType`` -> "MyType"
+ ``&Other`` / ``&mut T`` -> "Other" (reference_type unwrapped)
+ ``dyn MyTrait`` -> "MyTrait"
+ ``impl Shape`` -> "Shape"
+ ``Box<Inner>`` -> "Box" -> filtered (builtin)
+ ``std::io::Error`` -> "Error" (rightmost component)
+ ``u32`` / ``String`` -> None (builtin)
+ ``T`` -> None (single-letter generic param)
+
+ Generic arguments are not recursed into: ``Vec<Foo>`` yields the head
+ ``Vec`` only. Foo reaches the resolver through its own capture, matching
+ the Go and Kotlin extractors.
+ """
+ return _resolvable(_walk_to_head(type_node, src, _rust_head_step, 8), "rust")
+
+
+def _rust_head_step(node: Node, src: str) -> str | Node | None:
+ kind = node.type
+ if kind == "type_identifier":
+ return node_text(node, src)
+ if kind == "scoped_type_identifier":
+ # ``std::io::Error`` — the type is the rightmost component.
+ return node.child_by_field_name("name")
+ if kind in ("reference_type", "pointer_type", "generic_type"):
+ # ``&T`` / ``&mut T`` / ``*const T`` put the referent in the type
+ # field (``mut`` and ``const`` are unnamed children), and
+ # ``Box<Inner>`` its constructor; args are captured separately.
+ return node.child_by_field_name("type")
+ if kind in ("dynamic_type", "abstract_type"):
+ # ``dyn Trait`` / ``impl Trait`` — sole named child is the trait.
+ return node.child_by_field_name("trait") or _first_named_child(node)
+ if kind in _RUST_NO_SINGLE_HEAD:
+ return None
+ # Unknown shape - descend into the first named child and re-classify.
+ return _first_named_child(node)
+
+
+def _rust_type_param_name(param: Node, src: str) -> str | None:
+ """Return the bound name of a ``type_parameter``/``const_parameter`` node.
+
+ Both node types put the binding name first, before any trait bound or
+ default (``T: Clone``, ``D = Foo``, ``const N: usize``) — later
+ ``type_identifier`` children are constraints, not the binding itself.
+ """
+ for child in param.children:
+ if child.type in ("type_identifier", "identifier"):
+ return node_text(child, src).strip()
+ return None
+
+
+def _rust_binds_type_param(item: Node, target_name: str, src: str) -> bool:
+ """True if *item*'s own ``<...>`` list binds *target_name*."""
+ return any(
+ param.type in ("type_parameter", "const_parameter")
+ and _rust_type_param_name(param, src) == target_name
+ for child in item.children
+ if child.type == "type_parameters"
+ for param in child.children
+ )
+
+
+def _rust_shadowed_by_type_param(node: Node, target_name: str, src: str) -> bool:
+ """True if *target_name* is bound as a generic type parameter by an
+ ancestor item of *node* (``struct Wrapper<Item> { value: Item }``).
+
+ Rust's field/generic-argument type captures can't distinguish a type
+ parameter's own name from a real type reference — both are plain
+ ``type_identifier`` nodes. Without this check, a type parameter that
+ happens to share a name with a real struct/enum produces a false
+ "used" edge to that struct, hiding it from dead-code detection even
+ when it is genuinely unreferenced.
+ """
+ ancestor = node.parent
+ while ancestor is not None:
+ if _rust_binds_type_param(ancestor, target_name, src):
+ return True
+ ancestor = ancestor.parent
+ return False
+
+
+# ---------------------------------------------------------------------------
+# Pascal, F#, Elixir and Objective-C type-reference head extraction
+# ---------------------------------------------------------------------------
+
+# The child holding the type name in a generic or unit-qualified ``typeref``.
+_PASCAL_HEAD_FIELD = {"typerefTpl": "entity", "typerefDot": "rhs"}
+
+
+def _pascal_head_type_identifier(type_node: Node, src: str) -> str | None:
+ """Return the head identifier of a Pascal ``typeref`` type expression.
+
+ Examples:
+ ``TFoo`` → "TFoo"
+ ``TList<TBar>`` → "TList" (generic head only; the arg
+ isn't captured separately -- no
+ ``typerefArgs``-scoped query pattern
+ exists yet)
+ ``Ns.TQualified`` → "TQualified" (rightmost segment;
+ Pascal's unit-qualification puts the
+ type name last, same convention as
+ C#'s ``qualified_name`` handling)
+ ``Integer`` / ``TObject`` → None (builtin / VCL root type, never
+ has an in-repo declaration)
+
+ ``type_node`` is the ``typeref`` node pascal.scm captures directly (a
+ ``declProc`` return type) or via the intermediate ``type`` wrapper
+ (field/parameter/local-variable positions) -- the wrapper itself is
+ never captured, only the ``typeref`` inside it, so this always starts
+ from ``typeref`` regardless of which position it came from. A
+ ``typeref`` wraps exactly one of: a bare ``identifier``, a generic
+ ``typerefTpl`` (``entity`` field holds the head), or a qualified
+ ``typerefDot`` (``rhs`` field holds the type name -- ``lhs`` is the
+ unit qualifier).
+ """
+ head: Node | None = type_node
+ if head.type == "typeref":
+ head = _first_named_child(head)
+ if head is None:
+ return None
+ field = _PASCAL_HEAD_FIELD.get(head.type)
+ if field is not None:
+ head = head.child_by_field_name(field)
+ if head is None or head.type != "identifier":
+ return None
+ text = node_text(head, src).strip()
+ if not text or text in get_builtin_types("pascal"):
+ return None
+ return text
+
+
+def _fsharp_head_type_identifier(type_node: Node, src: str) -> str | None:
+ """The resolvable head of an F# type annotation.
+
+ ``fsharp_type_name`` does the walk; this adds the filter the type-
+ reference pass needs, since a primitive or an FSharp.Core type
+ constructor never has an in-repo declaration.
+ """
+ text = fsharp_type_name(type_node, src)
+ if not text or text in get_builtin_types("fsharp"):
+ return None
+ return text
+
+
+def _elixir_head_type_identifier(type_node: Node, src: str) -> str | None:
+ """Return the module name in an Elixir type position.
+
+ A captured type is always a whole ``alias`` leaf (``%Foo.Bar{}``,
+ ``@behaviour GenServer``), and the grammar keeps a dotted module name in
+ one node, so the head is the node's own text. No unwrapping to do, and no
+ generic-argument shape to recurse into -- unlike every other language
+ here, which is why the shared C#-shaped extractor cannot serve.
+ """
+ if type_node.type != "alias":
+ return None
+ return node_text(type_node, src).strip() or None
+
+
+def _objc_head_type_identifier(type_node: Node, src: str) -> str | None:
+ """Return the head class name of an Objective-C type position, or None.
+
+ Examples:
+ ``(NSString *)`` -> None (Foundation, never in-repo)
+ ``(MyClient *)`` -> "MyClient"
+ ``(instancetype)`` -> None (builtin)
+ ``(void)`` / ``(id)`` -> None (primitive / builtin)
+ ``@class Helper;`` -> "Helper"
+
+ The capture is a ``type_name`` wrapper for a method return or parameter
+ type, a bare ``type_identifier`` for a property, and a plain
+ ``identifier`` for a ``@class`` forward declaration or a protocol name, so
+ all four shapes start here. A pointer star lives in an
+ ``abstract_pointer_declarator`` inside the ``type_name``, which is skipped
+ rather than unwrapped: the star is not part of the name.
+ """
+ return _resolvable(_walk_to_head(type_node, src, _objc_head_step, 6), "objectivec")
+
+
+def _objc_head_step(node: Node, src: str) -> str | Node | None:
+ kind = node.type
+ if kind in ("type_identifier", "identifier"):
+ return node_text(node, src).strip()
+ if kind in ("primitive_type", "sized_type_specifier", "typedefed_specifier"):
+ return None
+ if kind in ("struct_specifier", "union_specifier", "enum_specifier"):
+ name = node.child_by_field_name("name")
+ # An anonymous aggregate has no named type to resolve.
+ return node_text(name, src).strip() if name is not None else None
+ return _first_named_child(node)
+
+
+# Per-language head-identifier extractor for ``@param.type`` captures.
+# Defaults to the C#-shaped extractor; languages with a differently-shaped
+# type grammar register their own here.
+TYPE_HEAD_EXTRACTORS: dict[str, Callable[[Node, str], str | None]] = {
+ "go": _go_head_type_identifier,
+ "c": _c_head_type_identifier,
+ "cpp": _c_head_type_identifier,
+ "typescript": _ts_head_type_identifier,
+ "javascript": _ts_head_type_identifier,
+ "java": _java_head_type_identifier,
+ "kotlin": _kotlin_head_type_identifier,
+ "rust": _rust_head_type_identifier,
+ "pascal": _pascal_head_type_identifier,
+ "elixir": _elixir_head_type_identifier,
+ "fsharp": _fsharp_head_type_identifier,
+ "objectivec": _objc_head_type_identifier,
+}
diff --git a/packages/core/src/repowise/core/ingestion/languages/specs/pascal.py b/packages/core/src/repowise/core/ingestion/languages/specs/pascal.py
index 55f65ad75..c0df0cf61 100644
--- a/packages/core/src/repowise/core/ingestion/languages/specs/pascal.py
+++ b/packages/core/src/repowise/core/ingestion/languages/specs/pascal.py
@@ -73,7 +73,7 @@ SPEC = LanguageSpec(
# latter overlap with builtin_parents above) -- none of these ever have
# an in-repo declaration, so resolving them as a type reference is a
# guaranteed miss. Read back via get_builtin_types("pascal") in
- # parser_helpers.py's head-identifier extractor.
+ # lang_helpers/type_heads.py's head-identifier extractor.
builtin_types=frozenset({
"Integer", "Cardinal", "Boolean", "ByteBool", "WordBool", "LongBool",
"String", "AnsiString", "WideString", "UnicodeString", "ShortString",
diff --git a/packages/core/src/repowise/core/ingestion/parser_helpers.py b/packages/core/src/repowise/core/ingestion/parser_helpers.py
index 7b11f9b71..dce4aa97b 100644
--- a/packages/core/src/repowise/core/ingestion/parser_helpers.py
+++ b/packages/core/src/repowise/core/ingestion/parser_helpers.py
@@ -1,61 +1,125 @@
"""Stateless AST helper functions used by :class:`~.parser.ASTParser`.
-Pure tree-sitter node utilities (query execution, qualified-name building,
-C# type-head extraction, call-argument counting, enclosing-symbol lookup,
-…) extracted from ``parser.py`` so that module holds the parser class and
-this one holds the free functions it calls. No state, no imports from
-``parser`` — keeping this a leaf so there is no import cycle.
+Language-neutral tree-sitter utilities live here; per-language helpers live in
+:mod:`.lang_helpers` and are re-exported so ``parser.py`` imports one module.
+No imports from ``parser``, so there is no import cycle.
"""
from __future__ import annotations
-import re
-from collections.abc import Callable
from pathlib import Path
-from typing import TYPE_CHECKING
import structlog
from tree_sitter import Node
-from .extractors import fsharp_type_name, node_text
-from .language_data import get_builtin_types
-from .type_names import is_resolvable_type_name
-
-if TYPE_CHECKING:
- from .models import Symbol
+from .extractors import node_text
+from .lang_helpers.elixir import (
+ _elixir_call_is_definitional,
+ _elixir_is_template_definition,
+ _elixir_module_parent,
+ _elixir_symbol_name,
+)
+from .lang_helpers.fsharp import (
+ _fsharp_binding_end_line,
+ _fsharp_binding_has_params,
+ _fsharp_binding_is_nested,
+ _fsharp_parent_is_type,
+ _fsharp_parent_name,
+)
+from .lang_helpers.objc import (
+ _dedupe_objc_interface_symbols,
+ _objc_call_is_block_variable,
+ _objc_container_node,
+ _objc_container_parent,
+ _objc_is_macro_enum,
+ _objc_message_selector,
+ _objc_symbol_name,
+)
+from .lang_helpers.pascal import _dedupe_pascal_interface_symbols, _qualified_pascal_parent
+from .lang_helpers.source_prep import prepare_objectivec_source, prepare_pascal_source
+from .lang_helpers.type_heads import (
+ TYPE_HEAD_EXTRACTORS,
+ _classify_param_origin,
+ _head_type_identifier,
+ _rust_head_type_identifier,
+ _rust_shadowed_by_type_param,
+)
log = structlog.get_logger(__name__)
-# Private alias for internal use (mirrors the one in parser.py)
-_node_text = node_text
-
-_WHITESPACE_RE = re.compile(r"\s+")
+__all__ = [
+ "TYPE_HEAD_EXTRACTORS",
+ "_build_qualified_name",
+ "_classify_param_origin",
+ "_collect_error_nodes",
+ "_count_arguments",
+ "_dedupe_objc_interface_symbols",
+ "_dedupe_pascal_interface_symbols",
+ "_elixir_call_is_definitional",
+ "_elixir_is_template_definition",
+ "_elixir_module_parent",
+ "_elixir_symbol_name",
+ "_find_enclosing_symbol",
+ "_fsharp_binding_end_line",
+ "_fsharp_binding_has_params",
+ "_fsharp_binding_is_nested",
+ "_fsharp_parent_is_type",
+ "_fsharp_parent_name",
+ "_has_callable_ancestor",
+ "_head_type_identifier",
+ "_is_async_node",
+ "_objc_call_is_block_variable",
+ "_objc_container_node",
+ "_objc_container_parent",
+ "_objc_is_macro_enum",
+ "_objc_message_selector",
+ "_objc_symbol_name",
+ "_qualified_cpp_parent",
+ "_qualified_pascal_parent",
+ "_run_query",
+ "_rust_head_type_identifier",
+ "_rust_shadowed_by_type_param",
+ "prepare_objectivec_source",
+ "prepare_pascal_source",
+]
def _run_query(query: object, root_node: Node) -> list[dict[str, list[Node]]]:
"""Execute a tree-sitter query and return a list of capture dicts."""
results: list[dict[str, list[Node]]] = []
try:
- from tree_sitter import QueryCursor # type: ignore[attr-defined]
-
- cursor = QueryCursor(query) # type: ignore[call-arg]
- for match in cursor.matches(root_node):
- if hasattr(match, "captures"):
- results.append(match.captures)
- elif isinstance(match, tuple) and len(match) == 2:
- _, caps = match
- results.append(caps)
+ _append_cursor_captures(query, root_node, results)
except Exception:
- try:
- for item in query.matches(root_node): # type: ignore[attr-defined]
- if isinstance(item, tuple) and len(item) == 2:
- _, caps = item
- results.append(caps)
- except Exception as exc:
- log.warning("query.matches() failed", error=str(exc))
+ # Older py-tree-sitter has no QueryCursor; matches collected before a
+ # failure are kept and the legacy API appends after them.
+ _append_legacy_captures(query, root_node, results)
return results
+def _append_cursor_captures(
+ query: object, root_node: Node, results: list[dict[str, list[Node]]]
+) -> None:
+ from tree_sitter import QueryCursor # type: ignore[attr-defined]
+
+ cursor = QueryCursor(query) # type: ignore[call-arg]
+ for match in cursor.matches(root_node):
+ if hasattr(match, "captures"):
+ results.append(match.captures)
+ elif isinstance(match, tuple) and len(match) == 2:
+ results.append(match[1])
+
+
+def _append_legacy_captures(
+ query: object, root_node: Node, results: list[dict[str, list[Node]]]
+) -> None:
+ try:
+ for item in query.matches(root_node): # type: ignore[attr-defined]
+ if isinstance(item, tuple) and len(item) == 2:
+ results.append(item[1])
+ except Exception as exc:
+ log.warning("query.matches() failed", error=str(exc))
+
+
def _collect_error_nodes(root: Node) -> list[str]:
"""Return error descriptions for any ERROR nodes in the tree."""
errors: list[str] = []
@@ -130,258 +194,6 @@ def _qualified_cpp_parent(name_node: Node, src: str) -> str | None:
return text.rsplit("::", 1)[-1] or None
-# Elixir keywords that DEFINE rather than call. Every one of them parses as a
-# `call` whose target identifier holds the keyword text, so the head it takes
-# (`add(a, b)` in `def add(a, b)`) is a `call` node too.
-_ELIXIR_DEFINITION_KEYWORDS = frozenset(
- {
- "def",
- "defp",
- "defmacro",
- "defmacrop",
- "defguard",
- "defguardp",
- "defdelegate",
- "defmodule",
- "defprotocol",
- "defimpl",
- "defexception",
- "defstruct",
- }
-)
-
-# Module attributes whose body is a type expression, not code. `@spec
-# add(integer(), integer()) :: integer()` holds three `call` nodes and calls
-# nothing; every other attribute (`@config Application.compile_env(…)`) holds
-# real code and keeps its edges.
-_ELIXIR_TYPESPEC_ATTRIBUTES = frozenset(
- {"spec", "type", "typep", "opaque", "callback", "macrocallback"}
-)
-
-# Elixir keywords that own a nested definition -- the parent a `def` reports.
-# `defimpl` is here because its definitions belong to the implementation module
-# the compiler generates, not to whatever module the block happens to sit in.
-_ELIXIR_MODULE_KEYWORDS = frozenset({"defmodule", "defprotocol", "defimpl"})
-
-# Node kinds that hold a list of statements. Reaching one while walking out of
-# an expression means the enclosing statement has been left.
-_ELIXIR_STATEMENT_HOLDERS = frozenset({"do_block", "block", "source", "stab_clause"})
-
-
-def _elixir_call_target_name(call_node: Node, src: str) -> str | None:
- """The keyword or function name in an Elixir ``call`` node's target."""
- if call_node.type != "call":
- return None
- target = call_node.child_by_field_name("target")
- if target is None or target.type != "identifier":
- return None
- return node_text(target, src).strip() or None
-
-
-def _elixir_call_is_definitional(node: Node, src: str) -> bool:
- """True when an Elixir ``call`` node defines or describes, never invokes.
-
- Two shapes reach the call queries and must not become graph edges, and
- neither can be excluded by a query predicate, which sees only the node's
- own text and not its parent:
-
- * a definition head -- ``def add(a, b)`` puts ``add(a, b)`` in the
- ``arguments`` of a call to ``def``, so the head reads as a call to the
- function being defined (a self-edge on every function in the repo). The
- ``when``-guard form wraps that head in a ``binary_operator`` first.
- * a module attribute -- ``@doc "…"`` is a call to ``doc``, and any
- ``@whatever value`` is a call to ``whatever``. Inside a typespec
- attribute the body is types, so its calls are dropped too; inside any
- other attribute the body is ordinary code and keeps its edges.
- """
- head = node
- parent = head.parent
- if parent is not None and parent.type == "binary_operator":
- operator = parent.child_by_field_name("operator")
- if (
- operator is not None
- and operator.type == "when"
- and parent.child_by_field_name("left") is not None
- and parent.child_by_field_name("left").id == head.id
- ):
- head, parent = parent, parent.parent
- if parent is not None and parent.type == "arguments":
- outer = parent.parent
- named = parent.named_children
- if (
- outer is not None
- and named
- and named[0].id == head.id
- and _elixir_call_target_name(outer, src) in _ELIXIR_DEFINITION_KEYWORDS
- ):
- return True
-
- # Walk out to the `@` unary_operator that opens this statement. Bounded by
- # the statement rather than by a hop count: a union return type nests one
- # binary_operator per member, so `@spec f(t) :: a() | b() | c() | d()` sits
- # deeper than any fixed budget and used to leak its type names as calls.
- ancestor: Node | None = node
- while ancestor is not None:
- holder = ancestor.parent
- if holder is None or holder.type in _ELIXIR_STATEMENT_HOLDERS:
- return False
- if holder.type == "unary_operator":
- operator = holder.child_by_field_name("operator")
- if operator is not None and operator.type == "@":
- if ancestor.id == node.id:
- return True
- return _elixir_call_target_name(ancestor, src) in _ELIXIR_TYPESPEC_ATTRIBUTES
- ancestor = holder
- return False
-
-
-def _elixir_definition_alias(call_node: Node, src: str) -> str | None:
- """The first ``alias`` argument of a definition call, i.e. its module name."""
- arguments = next(
- (child for child in call_node.named_children if child.type == "arguments"), None
- )
- if arguments is None or not arguments.named_children:
- return None
- first = arguments.named_children[0]
- if first.type != "alias":
- return None
- return node_text(first, src).strip() or None
-
-
-def _elixir_defimpl_for_type(call_node: Node, src: str) -> str | None:
- """The ``for:`` type of a ``defimpl Proto, for: Type`` block."""
- arguments = next(
- (child for child in call_node.named_children if child.type == "arguments"), None
- )
- if arguments is None:
- return None
- for child in arguments.named_children:
- if child.type != "keywords":
- continue
- for pair in child.named_children:
- key = pair.child_by_field_name("key")
- value = pair.child_by_field_name("value")
- if key is None or value is None:
- continue
- if node_text(key, src).strip().rstrip(":") == "for":
- return node_text(value, src).strip() or None
- return None
-
-
-def _elixir_enclosing_module_alias(node: Node, src: str) -> str | None:
- """The nearest enclosing ``defmodule``/``defprotocol`` name."""
- ancestor = node.parent
- while ancestor is not None:
- if _elixir_call_target_name(ancestor, src) in ("defmodule", "defprotocol"):
- return _elixir_definition_alias(ancestor, src)
- ancestor = ancestor.parent
- return None
-
-
-def _elixir_defimpl_name(call_node: Node, src: str) -> str | None:
- """The module name the compiler generates for a ``defimpl`` block.
-
- ``defimpl Jason.Encoder, for: Tuple`` compiles to a module called
- ``Jason.Encoder.Tuple``, and that name is used here. Without it the
- definitions inside the block are attributed to whatever module encloses it,
- where they read as unused exports of a module that never declared them, and
- two implementations of one protocol in one file mint two symbols under one
- id.
-
- The ``for:``-less form is only legal inside a ``defmodule`` and implements
- the protocol for that module, so the enclosing module supplies the type.
- """
- protocol = _elixir_definition_alias(call_node, src)
- if protocol is None:
- return None
- target_type = _elixir_defimpl_for_type(call_node, src) or _elixir_enclosing_module_alias(
- call_node, src
- )
- return f"{protocol}.{target_type}" if target_type else protocol
-
-
-def _elixir_symbol_name(def_node: Node, default_name: str, src: str) -> str:
- """The name a captured Elixir definition carries.
-
- Only ``defimpl`` differs from its captured text; everything else names
- itself. See ``_elixir_defimpl_name``.
- """
- if _elixir_call_target_name(def_node, src) != "defimpl":
- return default_name
- return _elixir_defimpl_name(def_node, src) or default_name
-
-
-def _elixir_is_template_definition(def_node: Node, src: str) -> bool:
- """True for a definition inside ``quote do ... end``.
-
- A ``def`` in a ``quote`` block is the body of a macro: it defines nothing in
- the module that writes it and everything in the module that later invokes
- the macro, which is a module no parser can name. Captured as a symbol it
- reads as a method of the wrong module, and then as an unused export of it.
- """
- ancestor = def_node.parent
- while ancestor is not None:
- if _elixir_call_target_name(ancestor, src) == "quote":
- return True
- ancestor = ancestor.parent
- return False
-
-
-def _elixir_module_parent(def_node: Node, src: str) -> str | None:
- """Return the enclosing ``defmodule``/``defprotocol`` name, or None.
-
- The generic nesting walk in ``ASTParser._find_parent`` reads
- ``ancestor.child_by_field_name("name")``, and an Elixir ``call`` has no
- ``name`` field -- the module name is the first argument of a call to
- ``defmodule``. Nesting is the only thing that says which module a
- function belongs to, so without this every ``def`` reads as a free
- function.
- """
- ancestor = def_node.parent
- while ancestor is not None:
- keyword = _elixir_call_target_name(ancestor, src)
- if keyword in _ELIXIR_MODULE_KEYWORDS:
- if keyword == "defimpl":
- return _elixir_defimpl_name(ancestor, src)
- return _elixir_definition_alias(ancestor, src)
- ancestor = ancestor.parent
- return None
-
-
-def _qualified_pascal_parent(name_node: Node, src: str) -> str | None:
- """Return the owning class for a Pascal out-of-line method header.
-
- ``function TCalculator.Add(...): Integer;`` in an implementation
- section is captured by pascal.scm's ``genericDot`` patterns, where the
- bare ``@symbol.name`` is the ``rhs`` (``Add``) and the qualifying type
- lives in the sibling ``lhs`` field (``TCalculator``). Nesting-based
- ``_find_parent`` can't see this: the ``defProc`` node sits in the
- unit's implementation section, physically outside the class's
- ``declType`` body declared in the interface section. Handles both the
- plain (``genericDot rhs: identifier``) and generic-method
- (``genericDot rhs: genericTpl entity: identifier``) query shapes.
-
- Uses ``node_text`` (tree-sitter's own byte-accurate decode), not raw
- ``src`` byte-offset slicing — Pascal identifiers and unit names are
- frequently non-ASCII (Cyrillic) in this codebase's real-world sources,
- and slicing a decoded ``str`` by *byte* offsets misaligns on any
- multi-byte character.
-
- Returns ``None`` when the name node isn't inside a qualified header
- (i.e. a free function/procedure).
- """
- parent = name_node.parent
- if parent is not None and parent.type == "genericTpl":
- parent = parent.parent
- if parent is None or parent.type != "genericDot":
- return None
- lhs = parent.child_by_field_name("lhs")
- if lhs is None:
- return None
- text = node_text(lhs, src).strip()
- return text or None
-
-
def _build_qualified_name(file_path: str, parent_name: str | None, name: str) -> str:
module = Path(file_path).with_suffix("").as_posix().replace("/", ".")
if parent_name:
@@ -389,1355 +201,6 @@ def _build_qualified_name(file_path: str, parent_name: str | None, name: str) ->
return f"{module}.{name}"
-_PASCAL_USES_IN_CLAUSE_RE = re.compile(rb"\bin\b[ \t]*'(?:[^'\r\n]|'')*'")
-
-
-def _sanitize_pascal_project_source(source: bytes) -> bytes:
- """Blank Delphi/FPC project-file ``unit in 'path.pas'`` clauses.
-
- ``.dpr``/``.dpk``/``.lpr`` project files map each unit to its source
- path right in the ``uses`` clause -- ``uses SysUtils, MyUnit in
- 'src\\MyUnit.pas';`` -- and Delphi's IDE writes this automatically for
- every unit added to a project, making it the norm rather than the
- exception in real ``.dpr``/``.dpk`` files (confirmed against this
- repo's own ``MTN2.dpr``: every non-RTL unit uses it).
-
- tree-sitter-pascal's grammar has no rule for the trailing ``in
- '...'`` at all. Hitting it mid-``declUses`` doesn't just fail that
- one unit -- the parser's error recovery folds the ``in``, the path
- string, and every subsequent comma-separated unit into one corrupted
- ``moduleName`` node spanning to wherever it happens to resync, so a
- single ``in`` clause was silently swallowing the rest of the ``uses``
- list (observed on ``MTN2.dpr``: 4 imports extracted instead of ~80,
- the 4th holding several KB of raw multi-line garbage as its
- ``module_path``). This is an upstream grammar gap, not something a
- ``.scm`` query can route around -- the AST itself is malformed before
- any query runs.
-
- Blanks the matched span with spaces (never a raw newline -- a Pascal
- string literal can't contain one, so no line is fully consumed) to
- preserve every other byte offset in the file, so line numbers for
- symbols/imports/calls elsewhere are unaffected. `'ABC'` doesn't need
- the doubled-quote (`''`) escape handled specially for *finding* the
- end of the string here (the regex already treats `''` as staying
- inside the literal), only for correctness of the match's own extent.
-
- Scoped to project files specifically: this syntax is invalid outside
- a ``uses`` clause and ``.pas``/``.pp`` unit files can't legally carry
- it, so there's nothing to blank there and no reason to run the regex
- over every unit file in a codebase.
- """
- return _blank_matches(source, _PASCAL_USES_IN_CLAUSE_RE)
-
-
-def _blank_matches(source: bytes, pattern: re.Pattern[bytes]) -> bytes:
- """Overwrite every match of *pattern* with spaces, keeping the length.
-
- The shared half of every byte-preserving source sanitizer: a construct the
- grammar has no rule for is replaced in place, never removed, so line
- numbers and byte offsets for everything else in the file survive. Spaces
- and never a newline, so no pattern can consume a line break it did not
- match.
- """
- if not pattern.search(source):
- return source
- out = bytearray(source)
- for match in pattern.finditer(source):
- start, end = match.span()
- out[start:end] = b" " * (end - start)
- return bytes(out)
-
-
-_PASCAL_PROJECT_EXTENSIONS = (".dpr", ".dpk", ".lpr")
-
-
-def prepare_pascal_source(source: bytes, path: str | None) -> bytes:
- """Single entry point for every Pascal byte-preserving sanitizer.
-
- Called from :func:`~.sfc_source.prepare_source` -- the same
- registry-dispatched hook every other tree-sitter consumer (the
- ingestion parser, plus the complexity/dataflow/duplication health
- walkers) already calls before handing bytes to a ``Parser`` -- rather
- than parser.py special-casing Pascal in its own if-blocks. That keeps
- ``docs/architecture/language-support.md``'s "zero changes to
- parser.py" promise for a new language, and means the health walkers
- get the same clean projection the ingestion parser does instead of
- parsing raw bytes.
-
- Only wraps ``_sanitize_pascal_project_source`` (``.dpr``/``.dpk``/
- ``.lpr`` ``in '...'`` clauses), gated on *path*'s extension since that
- syntax is invalid in a plain unit file. An earlier revision of this
- function also blanked whatever an anonymous ``array[...] of record``
- element type's parse errors touched, discovered via ERROR-node spans
- from a throwaway parse. Dropped after review (PR #1353): tree-sitter's
- error recovery for that construct doesn't cleanly wrap the bad
- construct in one ERROR node -- on the reviewer's repro, one of the
- spans it found was the class's own legitimate closing ``end;``, and
- blanking it produced the exact same broken structure (the following
- method detached from its class) as running no sanitizer at all. A
- correct fix needs a nesting-aware nested-record/variant-part scanner,
- which is more surface area than one occurrence in one file (see the
- dropped function's own docstring) justifies; the anon-record case is
- left to degrade to a wrong parent for that one class, same as any
- other unhandled grammar gap.
- """
- if path and path.lower().endswith(_PASCAL_PROJECT_EXTENSIONS):
- return _sanitize_pascal_project_source(source)
- return source
-
-
-def _dedupe_pascal_interface_symbols(
- symbols: list[Symbol], node_types: list[str]
-) -> list[Symbol]:
- """Drop an interface-section method signature once its implementation
- is also present, so the two don't become two graph nodes for one method.
-
- Pascal declares a method's signature once in the ``interface`` section
- (``declProc``, no body) and its full body once in the
- ``implementation`` section (``defProc``) — two distinct physical AST
- nodes pascal.scm both legitimately captures (see the query file's
- comment). Once ``_find_parent`` (nesting) and ``_qualified_pascal_parent``
- (the ``TFoo.Method`` header) resolve both to the same
- ``(parent_name, name)``, keep only the ``defProc`` version: it carries
- the real body, which is what ``get_symbol`` should return, and the
- ``declProc`` duplicate would otherwise leave two ``Add`` nodes in the
- graph for one logical method.
-
- Keyed on ``(parent_name, signature)`` — normalized, see
- ``_pascal_dedupe_key`` — rather than just ``(parent_name, name)`` so
- that Pascal ``overload;`` siblings (same name, different parameter
- lists) are told apart: an interface-only overload must survive even
- when a *different* overload of the same name has a same-file
- implementation (verified against a reproduction where a 2-overload
- class with only one variant implemented was silently losing the
- other variant's interface declaration).
-
- Normalization matters in practice, not just in theory: scanned
- against a real ~150-file Delphi codebase, 168 method pairs shared a
- class+name but escaped a raw-signature-text match — almost all of
- them a long parameter list wrapped across lines differently between
- the compact interface declaration and the implementation (extremely
- common Delphi formatting), a handful differing only by identifier
- case (Pascal is case-insensitive, so ``TFoo.Add`` and
- ``TFOO.ADD`` name the same method). ``_pascal_dedupe_key`` strips all
- whitespace and lowercases before comparing so both collapse
- correctly.
-
- Still imperfect: Pascal's compiler doesn't require parameter *names*
- to match between an interface declaration and its implementation
- (only the types, for overload resolution), so a same-file rename
- between the two still produces different normalized keys and defeats
- this dedup, leaving both symbols. Unlike the whitespace/case cases
- above, no evidence of this actually happening was found in the real
- codebase this was checked against — left as a documented gap rather
- than parsing parameter types out of ``declArgs`` for an exact match.
- """
- impl_keys = {
- _pascal_dedupe_key(s.parent_name, s.signature)
- for s, nt in zip(symbols, node_types, strict=True)
- if nt == "defProc"
- }
- return [
- s
- for s, nt in zip(symbols, node_types, strict=True)
- if not (nt == "declProc" and _pascal_dedupe_key(s.parent_name, s.signature) in impl_keys)
- ]
-
-
-def _pascal_dedupe_key(parent_name: str | None, signature: str) -> tuple[str | None, str]:
- """Normalize a (parent, signature) pair for Pascal's interface/impl dedup.
-
- Whitespace-insensitive (multi-line parameter lists get reformatted
- between the interface declaration and the implementation constantly
- in real Delphi code) and case-insensitive (identifiers are
- case-insensitive in Pascal, so this needs to hold for the *class*
- name half of the key too, not just the signature).
- """
- parent_key = parent_name.lower() if parent_name else None
- sig_key = _WHITESPACE_RE.sub("", signature).lower()
- return (parent_key, sig_key)
-
-
-# ---------------------------------------------------------------------------
-# Objective-C helpers
-# ---------------------------------------------------------------------------
-
-_OBJC_METHOD_NODE_TYPES = frozenset({"method_declaration", "method_definition"})
-_OBJC_CLASS_NODE_TYPES = frozenset({"class_interface", "class_implementation"})
-
-# A declaration and the definition that answers it, keyed the way the dedup
-# below pairs them.
-_OBJC_DEFINITION_NODE_TYPES = frozenset({"class_implementation", "method_definition"})
-_OBJC_DECLARATION_NODE_TYPES = frozenset({"class_interface", "method_declaration"})
-
-# Macros that expand to nothing but are spelled as a bare identifier, so the
-# grammar makes them a keyword child of the method they trail.
-_OBJC_TRAILING_MACRO_NAMES = frozenset({
- "NS_DESIGNATED_INITIALIZER", "NS_UNAVAILABLE", "NS_REQUIRES_SUPER",
- "NS_RETURNS_INNER_POINTER", "NS_REFINED_FOR_SWIFT", "NS_SWIFT_UI_ACTOR",
- "NS_REQUIRES_NIL_TERMINATION", "UNAVAILABLE_ATTRIBUTE", "DEPRECATED_ATTRIBUTE",
-})
-
-# ``typedef NS_ENUM(NSInteger, Kind) { KindA }`` shapes. See _objc_is_macro_enum.
-_OBJC_ENUM_MACRO_NAMES = frozenset({
- "NS_ENUM", "NS_OPTIONS", "NS_CLOSED_ENUM", "NS_ERROR_ENUM",
- "CF_ENUM", "CF_OPTIONS", "CF_CLOSED_ENUM",
-})
-
-
-def _objc_selector_name(def_node: Node, default_name: str, src: str) -> str:
- """Join a method's keyword parts into its full selector.
-
- A keyword is an ``identifier`` child that a ``method_parameter`` follows;
- anything trailing the last parameter is an attribute macro, not part of
- the name. See the Objective-C section of the architecture doc.
- """
- if def_node.type not in _OBJC_METHOD_NODE_TYPES:
- return default_name
- parts: list[str] = []
- pending: str | None = None
- for child in def_node.children:
- if child.type == "identifier":
- # Only the identifier immediately before a method_parameter is a
- # keyword; a bare trailing one is a macro like
- # NS_DESIGNATED_INITIALIZER, which would otherwise join into the
- # selector and stop the header pairing with its implementation.
- pending = _node_text(child, src).strip() or None
- elif child.type == "method_parameter":
- if pending is not None:
- parts.append(pending)
- pending = None
- elif child.type in ("compound_statement", ";"):
- break
- if parts:
- return "".join(f"{p}:" for p in parts)
- # No parameters at all: the selector is the first keyword, unadorned.
- first = next((c for c in def_node.children if c.type == "identifier"), None)
- if first is None:
- return default_name
- text = _node_text(first, src).strip()
- if not text or text in _OBJC_TRAILING_MACRO_NAMES:
- return default_name
- return text
-
-
-def _objc_is_macro_enum(def_node: Node, src: str) -> bool:
- """True for a ``typedef NS_ENUM(Type, Name) { … }`` typedef.
-
- This grammar has no rule for the macro, so the name argument and the brace
- body land in ERROR nodes and only the *enumerators* survive as
- ``declarator`` children. Capturing those mints a symbol per enum case named
- as though it were the type, and never one for the type itself, so the whole
- typedef is skipped: no symbol beats a wrong one.
- """
- if def_node.type != "type_definition":
- return False
- for child in def_node.children:
- if child.type != "macro_type_specifier":
- continue
- name = child.child_by_field_name("name")
- if name is not None and _node_text(name, src).strip() in _OBJC_ENUM_MACRO_NAMES:
- return True
- return False
-
-
-def _objc_category_name(def_node: Node, default_name: str, src: str) -> str:
- """Name a category for the class it extends plus its own name.
-
- Two categories on one class are two declarations about it, so naming both
- for the class alone would merge them. A class extension (``Foo ()``) binds
- no ``category`` field and keeps the plain name.
- """
- if def_node.type not in _OBJC_CLASS_NODE_TYPES:
- return default_name
- category = def_node.child_by_field_name("category")
- if category is None:
- return default_name
- text = _node_text(category, src).strip()
- return f"{default_name}({text})" if text else default_name
-
-
-def _objc_symbol_name(def_node: Node, default_name: str, src: str) -> str:
- """The name a captured Objective-C definition carries."""
- if def_node.type in _OBJC_METHOD_NODE_TYPES:
- return _objc_selector_name(def_node, default_name, src)
- return _objc_category_name(def_node, default_name, src)
-
-
-def _objc_container_node(def_node: Node, container_types: frozenset[str]) -> Node | None:
- """The ``@interface`` / ``@implementation`` / ``@protocol`` around a member."""
- ancestor = def_node.parent
- while ancestor is not None:
- if ancestor.type in container_types:
- return ancestor
- ancestor = ancestor.parent
- return None
-
-
-def _objc_container_parent(def_node: Node, container_types: frozenset[str], src: str) -> str | None:
- """The name of the container a method or property is declared in.
-
- The generic nesting walk finds the same ancestor and then reads a ``name``
- field these nodes do not have: each carries its name as a bare first
- ``identifier`` child. Members of a category take the category's own name.
- """
- container = _objc_container_node(def_node, container_types)
- if container is None:
- return None
- identifier = next((c for c in container.children if c.type == "identifier"), None)
- if identifier is None:
- return None
- name = _node_text(identifier, src).strip()
- return _objc_category_name(container, name, src) if name else None
-
-
-def _objc_message_selector(site_node: Node, target_node: Node, src: str) -> str | None:
- """Join a message send's keyword parts, or None for a repeat match.
-
- ``[view setTitle:t forState:s]`` binds one ``method:`` child per keyword,
- so the one query pattern matches once per keyword. Returns the joined
- selector for the match carrying the first keyword and None for every later
- one, so the extra matches are dropped rather than emitted as targets that
- name nothing. The node's own ``:`` tokens say whether the selector takes
- arguments: ``[obj run]`` is ``run`` and ``[obj run:x]`` is ``run:``.
- """
- methods = site_node.children_by_field_name("method")
- if not methods or methods[0].id != target_node.id:
- return None
- parts = [_node_text(m, src).strip() for m in methods]
- parts = [p for p in parts if p]
- if not parts:
- return None
- takes_arguments = any(c.type == ":" for c in site_node.children)
- if not takes_arguments:
- return parts[0]
- return "".join(f"{p}:" for p in parts)
-
-
-def _objc_call_is_block_variable(site_node: Node, target_name: str, src: str) -> bool:
- """True when a bare-identifier call invokes a block held in a variable.
-
- Objective-C invokes a block with C call syntax, so ``completionBlock(hit)``
- is a ``call_expression`` on a bare identifier that nothing in the grammar
- separates from a call to a C function. Names like this are ubiquitous as
- both a parameter and a ``@property``, so without the scope check the
- resolver binds the invocation to an unrelated class's property.
- """
- node: Node | None = site_node
- while node is not None:
- if node.type == "compound_statement":
- for statement in node.named_children:
- if statement.type == "declaration" and _objc_declares_name(
- statement, target_name, src
- ):
- return True
- elif node.type == "method_definition":
- return any(
- child.type == "method_parameter"
- and _objc_declares_name(child, target_name, src)
- for child in node.children
- )
- elif node.type == "function_definition":
- declarator = node.child_by_field_name("declarator")
- return declarator is not None and _objc_declares_name(declarator, target_name, src)
- node = node.parent
- return False
-
-
-def _objc_declares_name(node: Node, name: str, src: str) -> bool:
- """True when *node* binds *name* as a parameter or a variable.
-
- A declarator nests (``void (^block)(int)``, ``SDBlock done = ^{}``), so
- every identifier under the node is checked rather than only the direct
- children. The node is a parameter or a declaration, never a body, so the
- walk stays small; a nested block body is skipped for the same reason.
- """
- stack = [node]
- while stack:
- current = stack.pop()
- if current.type in ("identifier", "field_identifier"):
- if _node_text(current, src).strip() == name:
- return True
- elif current.type != "compound_statement":
- stack.extend(current.children)
- return False
-
-
-def _objc_container_family(container_kind: str | None) -> str | None:
- """Which namespace a member belongs to: a protocol's, or a class's.
-
- An ``@interface`` and its ``@implementation`` are the same class, so a
- declaration in one must still dedupe against a definition in the other; a
- ``@protocol`` of the same name is a different thing entirely.
- """
- return "protocol" if container_kind == "protocol_declaration" else container_kind and "class"
-
-
-def _dedupe_objc_interface_symbols(
- symbols: list[Symbol], node_types: list[str], container_kinds: list[str | None]
-) -> list[Symbol]:
- """Collapse a declaration into the definition standing beside it.
-
- A ``.m`` routinely opens with a class extension (``@interface Foo ()``)
- declaring the private methods its ``@implementation Foo`` then defines, so
- each builds the same symbol id twice in one file. The definition wins: it
- carries the body. Across two files the split is real and both symbols are
- kept, marked with ``is_declaration`` the way a C header's prototype and its
- ``.c`` definition already are.
-
- The key carries the container kind because a protocol and a class may share
- a name in one file, and ``-ping`` on the protocol is then a different method
- from ``-ping`` on the class. Keyed on the name and not the signature:
- Objective-C has no overloading, and a declaration and its definition
- routinely differ in parameter names and nullability annotations.
- """
- definition_keys = {
- (_objc_container_family(kind), s.parent_name, s.name)
- for s, nt, kind in zip(symbols, node_types, container_kinds, strict=True)
- if nt in _OBJC_DEFINITION_NODE_TYPES
- }
- seen_declarations: set[tuple[str | None, str | None, str]] = set()
- kept: list[Symbol] = []
- for symbol, node_type, kind in zip(symbols, node_types, container_kinds, strict=True):
- if node_type in _OBJC_DECLARATION_NODE_TYPES:
- key = (_objc_container_family(kind), symbol.parent_name, symbol.name)
- if key in definition_keys or key in seen_declarations:
- continue
- seen_declarations.add(key)
- kept.append(symbol)
- return kept
-
-
-# Whole-line macros that expand to nothing a parser needs but which this
-# grammar reads as the start of a C declaration, swallowing whatever follows
-# into an ERROR node. Only bare whole-line forms are listed: a macro that
-# opens a real declaration (``FOUNDATION_EXPORT NSString *const kFoo;``) must
-# stay, and a call-shaped one (``NS_ENUM(NSInteger, Kind)``) is a different
-# problem that blanking a line cannot fix.
-_OBJC_BARE_MACRO_LINE_RE = re.compile(
- rb"^[ \t]*(?:NS_ASSUME_NONNULL_BEGIN|NS_ASSUME_NONNULL_END"
- rb"|NS_HEADER_AUDIT_BEGIN\([^)\r\n]*\)|NS_HEADER_AUDIT_END"
- rb"|CF_ASSUME_NONNULL_BEGIN|CF_ASSUME_NONNULL_END"
- rb"|NS_REFINED_FOR_SWIFT|NS_SWIFT_UI_ACTOR)[ \t]*(?=\r?\n|$)",
- re.MULTILINE,
-)
-
-
-# Availability / naming attributes written *call-shaped* after a declaration
-# (``@property (...) Foo *bar AF_API_AVAILABLE(ios(10));``,
-# ``- (void)done NS_SWIFT_NAME(done())``). The bare whole-line pass above
-# cannot see these: the macro is the last token of a declaration the grammar
-# otherwise reads fine, and it reads as a declarator or attribute list the
-# grammar cannot close. Error recovery then fails to resync at the ``;`` and
-# the damage runs past the declaration into the rest of the file, so the
-# enclosing method of every call after it is lost and those calls are credited
-# to ``__module__`` instead of their real caller. Measured on AFNetworking's
-# ``AFURLSessionManager.m``: 822 ERROR nodes before, 2 after.
-#
-# Enumerated by name, the same shape as the list above, because the grammar
-# cannot tell an attribute from a call on its own. ``NS_ENUM(NSInteger, Kind)``
-# after a ``typedef`` and ``NSLog(@"%@", x)`` both look like
-# ``IDENT(...)``; a general rule would blank real code and a match-everything
-# rule for these names is no safer. Only a form that *terminates* a declaration
-# qualifies: the macro must be followed by the closing ``;``, the ``{`` opening
-# a method body, or the end of the line (a definition may put the brace on the
-# next one). The same name inside an argument list or a comparison sits before
-# a ``,``/``)`` and is left alone.
-_OBJC_TRAILING_MACRO_RE = re.compile(
- rb"(?<![A-Za-z0-9_])(?:AF_API_AVAILABLE|API_AVAILABLE|API_DEPRECATED"
- rb"|NS_SWIFT_NAME|NS_AVAILABLE|NS_DEPRECATED)"
- rb"\((?:[^()\r\n]|\([^()\r\n]*\))*\)[ \t]*(?=[;{]|\r?$)",
- re.MULTILINE,
-)
-
-
-def _blank_objc_trailing_macros(source: bytes) -> bytes:
- """Blank trailing call-shaped attribute macros, keeping the terminator.
-
- The ``;``/``{`` the pattern looks ahead to stays in place so the
- declaration itself still ends where it always did; only the macro's own
- span is overwritten. Same offset contract as every other sanitizer here.
- """
- return _blank_matches(source, _OBJC_TRAILING_MACRO_RE)
-
-
-def prepare_objectivec_source(source: bytes) -> bytes:
- """Blank nullability-audit macros, bare and call-shaped, preserving offsets.
-
- ``NS_ASSUME_NONNULL_BEGIN`` is not a preprocessor directive and this
- grammar has no rule for it, so it parses as the opening of a C declaration
- and error recovery folds the whole ``@interface … @end`` block after it
- into one ERROR node. The macro wraps almost every modern Objective-C
- header, so this is the dominant parse failure in real source.
-
- The same failure has a second shape: a declaration whose *last* token is a
- call-shaped availability attribute (``AF_API_AVAILABLE(ios(10), ...)``,
- ``NS_SWIFT_NAME(...)``). There the recovery never resyncs at the closing
- ``;``, so one trailing attribute derails the remainder of the file. Both
- passes blank in place, so every offset outside a match is unchanged.
- """
- return _blank_objc_trailing_macros(_blank_matches(source, _OBJC_BARE_MACRO_LINE_RE))
-
-
-# ---------------------------------------------------------------------------
-# Type reference helpers (used by _extract_type_refs)
-# ---------------------------------------------------------------------------
-
-_PARAM_ORIGIN_BY_ANCESTOR: dict[str, str] = {
- "type_argument_list": "generic_argument",
- "typeof_expression": "typeof",
- "constructor_declaration": "ctor_param",
- "method_declaration": "method_param",
- "delegate_declaration": "delegate_param",
- "record_declaration": "ctor_param",
- "class_declaration": "ctor_param",
- "struct_declaration": "ctor_param",
- # Go type positions — node types are Go-only so they never collide with
- # the C# entries above. The origin is provenance only; resolution treats
- # all type-use edges equally.
- "field_declaration": "field_type",
- "parameter_declaration": "param_type",
- "composite_literal": "composite_literal",
- # TypeScript / JavaScript type positions. Walk-up matches the nearest
- # enclosing declaration; the parameter / field / heritage nodes sit
- # closer than ``class_declaration`` so this dispatch is unambiguous.
- "required_parameter": "param_type",
- "optional_parameter": "param_type",
- "property_signature": "field_type",
- "public_field_definition": "field_type",
- "function_declaration": "return_type",
- "method_definition": "return_type",
- "method_signature": "return_type",
- "arrow_function": "return_type",
- "function_signature": "return_type",
- "type_alias_declaration": "type_alias",
- "type_parameter": "generic_constraint",
- "extends_clause": "extends",
- "extends_type_clause": "extends",
- "implements_clause": "implements",
- # JVM (Java + Kotlin) type positions. Note: ``parameter`` is NOT
- # mapped here because tree-sitter-c-sharp also uses ``parameter``
- # for ctor params and adding it would override C#'s walk to the
- # enclosing ``constructor_declaration``. Kotlin function-parameter
- # origin therefore falls through to ``function_declaration`` →
- # "return_type" (imprecise but harmless — origin is provenance only).
- "formal_parameter": "param_type",
- "object_creation_expression": "composite_literal",
- "local_variable_declaration": "field_type",
- "superclass": "extends",
- "super_interfaces": "implements",
- "type_list": "implements",
- "class_parameter": "ctor_param", # Kotlin primary-ctor parameter
- "variable_declaration": "field_type", # Kotlin property declaration
- "delegation_specifier": "extends", # Kotlin class : Bar()
- # Pascal type positions — node types are Pascal-only, no collision risk.
- "declField": "field_type",
- "declArg": "param_type",
- "declVar": "local_var_type",
- "declProc": "return_type",
- "exprArgs": "framework_ctor", # Application.CreateForm(TClass, Var)
-}
-
-
-def _head_type_identifier(type_node: Node, src: str) -> str | None:
- """Return the head identifier of a C# type expression, or None.
-
- Examples:
- ``IBasketService`` → "IBasketService"
- ``IList<Basket>`` → "IList"
- ``Acme.Catalog.IRepository<T>`` → "IRepository"
- ``ref readonly Span<byte>`` → "Span"
- ``string`` → None (built-in)
- ``int?`` → None
- ``T`` → None (likely a generic param)
-
- The point of returning the head identifier is that the
- DotNetProjectIndex type-name lookup is keyed by unqualified type
- name. Generic-arg recursion is intentionally NOT done here — each generic
- argument is captured from its own ``type_argument_list`` node, including
- nested arguments and invocation-only type uses.
- """
- head_node: Node | None = type_node
-
- # Unwrap modifier wrappers: nullable_type, ref_type, pointer_type,
- # array_type, tuple_type. tree-sitter-c-sharp puts the inner type
- # at field "type" or as the first non-trivia child.
- for _ in range(6):
- if head_node is None:
- return None
- if head_node.type in ("nullable_type", "ref_type", "pointer_type", "array_type"):
- inner = head_node.child_by_field_name("type")
- if inner is None:
- # Fall back to first identifier-bearing child
- inner = next(
- (
- c
- for c in head_node.children
- if c.type not in (",", "?", "*", "&", "ref", "out", "in", "[", "]")
- ),
- None,
- )
- head_node = inner
- continue
- break
-
- if head_node is None:
- return None
-
- if head_node.type == "identifier" or head_node.type == "predefined_type":
- text = _node_text(head_node, src)
- elif head_node.type == "generic_name":
- name_child = head_node.child_by_field_name("name") or next(
- (c for c in head_node.children if c.type == "identifier"),
- None,
- )
- text = _node_text(name_child, src) if name_child else ""
- elif head_node.type == "qualified_name":
- # `Foo.Bar.Baz` — take the rightmost identifier
- idents = [c for c in head_node.children if c.type == "identifier"]
- text = _node_text(idents[-1], src) if idents else ""
- elif head_node.type == "tuple_type":
- return None # Tuple elements aren't single types
- else:
- # Unknown shape — fall back to first identifier in the subtree
- ident = _first_descendant(head_node, "identifier")
- text = _node_text(ident, src) if ident else ""
-
- return text if is_resolvable_type_name(text, "csharp") else None
-
-
-def _first_descendant(node: Node, type_name: str) -> Node | None:
- stack = [node]
- while stack:
- current = stack.pop()
- if current.type == type_name:
- return current
- stack.extend(current.children)
- return None
-
-
-def _classify_param_origin(type_node: Node) -> str:
- """Walk up to find the enclosing declaration and map to an origin tag.
-
- The walk stops at the first matching ancestor or after a small depth
- cap. Falling off the cap means the capture was outside a recognised
- declaration shape (shouldn't happen given the query patterns, but
- guards against grammar drift); we tag those ``method_param``.
- """
- cur: Node | None = type_node
- for _ in range(8):
- if cur is None:
- break
- origin = _PARAM_ORIGIN_BY_ANCESTOR.get(cur.type)
- if origin is not None:
- return origin
- cur = cur.parent
- return "method_param"
-
-
-# ---------------------------------------------------------------------------
-# Go type-reference head extraction
-# ---------------------------------------------------------------------------
-
-def _go_head_type_identifier(type_node: Node, src: str) -> str | None:
- """Return the head type name of a Go type expression, or None.
-
- Unwraps the modifier shells Go layers around a named type so the
- resolver sees the bare identifier it indexes by:
-
- ``Options`` → "Options"
- ``*Cache`` → "Cache"
- ``[]Partition`` → "Partition"
- ``map[string]Config`` → "Config" (value type; string filtered)
- ``chan Event`` → "Event"
- ``dynacache.Cache`` → "Cache" (qualifier dropped)
- ``List[Inner]`` → "List" (generic head)
- ``string`` / ``int`` → None (builtin)
- ``(Foo, error)`` → None (parameter_list; the inner
- declarations are captured
- separately)
- ``interface{...}`` / ``struct{...}`` / ``func(...)`` → None (anonymous)
-
- The qualifier in ``pkg.Cache`` is intentionally dropped: the Go type-ref
- strategy resolves the bare name against same-package siblings and
- imported package files, mirroring the Rust strategy. Keeping the head
- name unqualified matches the symbol-index keys.
- """
- node: Node | None = type_node
- text = ""
- for _ in range(8):
- if node is None:
- return None
- kind = node.type
- if kind == "type_identifier":
- text = _node_text(node, src)
- break
- if kind == "qualified_type":
- name = node.child_by_field_name("name") or next(
- (c for c in reversed(node.children) if c.type == "type_identifier"),
- None,
- )
- text = _node_text(name, src) if name else ""
- break
- if kind == "generic_type":
- node = node.child_by_field_name("type")
- continue
- if kind in ("slice_type", "array_type"):
- node = node.child_by_field_name("element")
- continue
- if kind == "map_type":
- node = node.child_by_field_name("value")
- continue
- if kind == "channel_type":
- node = node.child_by_field_name("value")
- continue
- if kind in ("pointer_type", "parenthesized_type"):
- # No field name on the inner type — take the first named child.
- node = node.named_children[0] if node.named_children else None
- continue
- # parameter_list (multi-return), interface_type, struct_type,
- # function_type, and anything else: no single named type to resolve.
- return None
- else:
- return None
-
- return text if is_resolvable_type_name(text, "go") else None
-
-
-# ---------------------------------------------------------------------------
-# C / C++ type-reference head extraction
-# ---------------------------------------------------------------------------
-
-def _c_head_type_identifier(type_node: Node, src: str) -> str | None:
- """Return the head type name of a C / C++ type expression, or None.
-
- In C the pointer / array shells wrap the *declarator*, not the type,
- so the captured ``type:`` field is the bare type node:
-
- ``JSON_Value`` → "JSON_Value"
- ``struct JSON_Object`` → "JSON_Object" (named struct ref)
- ``int`` / ``unsigned long`` → None (primitive)
- ``size_t`` → None (stdlib typedef)
- ``Acme::Widget`` (C++) → "Widget" (rightmost name)
- ``std::vector<T>`` (C++) → "vector" (template head)
- anonymous ``struct {...}`` → None
- """
- node: Node | None = type_node
- text = ""
- for _ in range(6):
- if node is None:
- return None
- kind = node.type
- if kind == "type_identifier":
- text = _node_text(node, src)
- break
- if kind in ("primitive_type", "sized_type_specifier"):
- return None
- if kind in ("struct_specifier", "union_specifier", "enum_specifier", "class_specifier"):
- name = node.child_by_field_name("name")
- if name is None:
- return None # anonymous aggregate — no named type to resolve
- text = _node_text(name, src)
- break
- if kind == "template_type":
- node = node.child_by_field_name("name")
- continue
- if kind == "qualified_identifier":
- # ``NS::Type`` — take the rightmost name component.
- name = node.child_by_field_name("name")
- node = name if name is not None else (
- node.named_children[-1] if node.named_children else None
- )
- continue
- # type_qualifier (const/volatile) wrappers and anything else:
- # descend into the first named child.
- node = node.named_children[0] if node.named_children else None
- else:
- return None
-
- # cpp shares this extractor; the builtin set is identical for both.
- return text if is_resolvable_type_name(text, "c") else None
-
-
-# ---------------------------------------------------------------------------
-# TypeScript / JavaScript type-reference head extraction
-# ---------------------------------------------------------------------------
-
-def _ts_head_type_identifier(type_node: Node, src: str) -> str | None:
- """Return the head identifier of a TypeScript/JavaScript type, or None.
-
- Unwraps the modifier shells TS layers around a named type so the
- resolver sees the bare identifier:
-
- ``Foo`` → "Foo"
- ``Foo[]`` → "Foo" (array_type)
- ``Promise<Foo>`` → "Promise" → filtered (builtin)
- ``ns.Foo`` → "Foo" (nested_type_identifier)
- ``Foo | null`` → None (union — ambiguous head)
- ``(x: A) => B`` → None (function_type — A/B are
- captured separately as their
- own param/return positions)
- ``{ x: number }`` → None (anonymous object type)
- ``string`` / ``number`` → None (predefined / builtin)
- ``T`` → None (single-uppercase generic)
-
- Union / intersection / function / object types return None because
- the head isn't a single name; the underlying parameter / field
- captures for each leaf already produced their own ``@param.type``
- captures so the bare leaves are still resolved.
- """
- node: Node | None = type_node
- text = ""
- for _ in range(8):
- if node is None:
- return None
- kind = node.type
- if kind == "type_identifier":
- text = _node_text(node, src)
- break
- if kind == "identifier":
- # ``extends_clause`` of a class uses ``identifier`` (E in
- # ``class D extends E``); treat it as a type name.
- text = _node_text(node, src)
- break
- if kind == "predefined_type":
- return None
- if kind in ("union_type", "intersection_type", "function_type",
- "constructor_type", "object_type", "literal_type",
- "tuple_type", "conditional_type", "mapped_type",
- "index_type_query", "type_query", "lookup_type",
- "template_literal_type", "infer_type", "readonly_type"):
- return None
- if kind == "generic_type":
- # ``Foo<T>`` — descend to the bare name; generic args are
- # captured separately if they hold user types.
- inner = node.child_by_field_name("name") or next(
- (c for c in node.named_children if c.type != "type_arguments"),
- None,
- )
- node = inner
- continue
- if kind == "nested_type_identifier":
- # ``ns.Foo`` — rightmost name component is the type itself.
- name = node.child_by_field_name("name") or next(
- (c for c in reversed(node.named_children)
- if c.type == "type_identifier"),
- None,
- )
- node = name
- continue
- if kind == "array_type":
- # ``T[]`` — element is the first named child.
- node = next(iter(node.named_children), None)
- continue
- if kind == "parenthesized_type":
- node = next(iter(node.named_children), None)
- continue
- if kind == "type_annotation":
- # Shouldn't be reached given the query strips the annotation,
- # but defensive: descend past the colon to the type itself.
- node = next(iter(node.named_children), None)
- continue
- if kind == "constraint":
- # ``extends Cons`` inside a type_parameter — the constraint
- # node wraps the actual constraint type.
- node = next(iter(node.named_children), None)
- continue
- # Anything else (type_predicate, asserts, type_assertion, ...)
- # — descend into the first named child and re-classify.
- node = next(iter(node.named_children), None)
- else:
- return None
-
- return text if is_resolvable_type_name(text, "typescript") else None
-
-
-# ---------------------------------------------------------------------------
-# Java type-reference head extraction
-# ---------------------------------------------------------------------------
-
-def _java_head_type_identifier(type_node: Node, src: str) -> str | None:
- """Return the head type identifier of a Java type expression, or None.
-
- Examples:
- ``Bar`` → "Bar"
- ``java.util.List<Foo>`` → "List" → filtered (builtin)
- ``com.x.y.Z`` → "Z"
- ``Foo.Bar`` → "Bar" (inner type)
- ``Foo[]`` → "Foo"
- ``int`` / ``void`` / ``long`` → None
- ``T`` → None (generic parameter)
- """
- node: Node | None = type_node
- text = ""
- for _ in range(8):
- if node is None:
- return None
- kind = node.type
- if kind == "type_identifier":
- text = _node_text(node, src)
- break
- if kind in (
- "void_type", "integral_type", "floating_point_type",
- "boolean_type",
- ):
- return None
- if kind == "scoped_type_identifier":
- # ``com.x.y.Z`` / ``Foo.Bar`` — take the rightmost type_identifier
- inner_ids = [c for c in node.children if c.type == "type_identifier"]
- if not inner_ids:
- return None
- text = _node_text(inner_ids[-1], src)
- break
- if kind == "generic_type":
- # ``Foo<T>`` — descend to the bare name; generic args are
- # captured separately by their own type_arguments inner captures.
- inner = next(
- (c for c in node.named_children
- if c.type in ("type_identifier", "scoped_type_identifier")),
- None,
- )
- node = inner
- continue
- if kind == "array_type":
- # ``Foo[]`` — element child has no field name; take first named.
- inner = next(iter(node.named_children), None)
- node = inner
- continue
- if kind == "annotated_type":
- # ``@NonNull Foo`` — last named child is the type.
- node = next(
- (c for c in reversed(node.named_children)
- if c.type not in ("annotation", "marker_annotation")),
- None,
- )
- continue
- # Anything else (wildcard, type_parameter, ...) — descend.
- node = next(iter(node.named_children), None)
- else:
- return None
-
- return text if is_resolvable_type_name(text, "java") else None
-
-
-# ---------------------------------------------------------------------------
-# Kotlin type-reference head extraction
-# ---------------------------------------------------------------------------
-
-def _kotlin_head_type_identifier(type_node: Node, src: str) -> str | None:
- """Return the head identifier of a Kotlin type expression, or None.
-
- Examples:
- ``Bar`` → "Bar"
- ``Foo?`` → "Foo" (nullable_type unwrapped)
- ``List<Foo>`` → "List" → filtered (builtin)
- ``com.x.Foo`` → "Foo" (dotted user_type)
- ``Foo.Bar`` → "Bar"
- ``() -> Foo`` → None (function_type — skipped)
- ``Unit`` / ``Any`` / ``String`` → None (builtin)
- """
- node: Node | None = type_node
- text = ""
- for _ in range(8):
- if node is None:
- return None
- kind = node.type
- if kind == "user_type":
- # ``Foo`` / ``Foo<...>`` / ``ns.Foo``.
- # Children: identifier, type_arguments, possibly more dotted parts.
- # Rightmost identifier is the head; type_arguments contains the
- # generic args (captured separately by their own type-ref).
- inner_ids = [c for c in node.children if c.type == "identifier"]
- if not inner_ids:
- return None
- text = _node_text(inner_ids[-1], src)
- break
- if kind == "identifier":
- text = _node_text(node, src)
- break
- if kind == "nullable_type":
- # Unwrap ``Foo?`` to the underlying user_type.
- inner = next(iter(node.named_children), None)
- node = inner
- continue
- if kind in ("function_type", "parenthesized_type"):
- # () -> Foo, (() -> Foo) — leaf type names are not captured.
- return None
- if kind == "type_reference":
- node = next(iter(node.named_children), None)
- continue
- if kind == "type_projection":
- # `<out Foo>` / `<in Foo>` / `<Foo>` — last named child is the type.
- node = next(iter(node.named_children), None)
- continue
- # Anything else — descend.
- node = next(iter(node.named_children), None)
- else:
- return None
-
- return text if is_resolvable_type_name(text, "kotlin") else None
-
-
-# ---------------------------------------------------------------------------
-# Rust type-reference head extraction
-# ---------------------------------------------------------------------------
-
-def _rust_head_type_identifier(type_node: Node, src: str) -> str | None:
- """Return the head identifier of a Rust type expression, or None.
-
- Rust needs its own extractor because the C#-shaped default spells a type
- name ``identifier`` while tree-sitter-rust spells it ``type_identifier``.
- The default therefore returned None for every bare Rust type, and for
- ``std::io::Error`` returned the leftmost segment ``io`` — a crate name,
- not the type.
-
- Examples:
- ``MyType`` -> "MyType"
- ``&Other`` / ``&mut T`` -> "Other" (reference_type unwrapped)
- ``dyn MyTrait`` -> "MyTrait"
- ``impl Shape`` -> "Shape"
- ``Box<Inner>`` -> "Box" -> filtered (builtin)
- ``std::io::Error`` -> "Error" (rightmost component)
- ``u32`` / ``String`` -> None (builtin)
- ``T`` -> None (single-letter generic param)
-
- Generic arguments are not recursed into: ``Vec<Foo>`` yields the head
- ``Vec`` only. Foo reaches the resolver through its own capture, matching
- the Go and Kotlin extractors.
- """
- node: Node | None = type_node
- text = ""
- for _ in range(8):
- if node is None:
- return None
- kind = node.type
- if kind == "type_identifier":
- text = _node_text(node, src)
- break
- if kind == "scoped_type_identifier":
- # ``std::io::Error`` — the type is the rightmost component.
- name = node.child_by_field_name("name")
- if name is None:
- return None
- node = name
- continue
- if kind in ("reference_type", "pointer_type"):
- # ``&T`` / ``&mut T`` / ``*const T`` — the type field is the
- # referent; ``mut`` and ``const`` are unnamed children.
- node = node.child_by_field_name("type")
- continue
- if kind == "generic_type":
- # ``Box<Inner>`` — head is the constructor, args are captured
- # separately.
- node = node.child_by_field_name("type")
- continue
- if kind in ("dynamic_type", "abstract_type"):
- # ``dyn Trait`` / ``impl Trait`` — sole named child is the trait.
- node = node.child_by_field_name("trait") or next(
- iter(node.named_children), None
- )
- continue
- if kind in ("primitive_type", "tuple_type", "unit_type", "array_type",
- "function_type", "never_type", "empty_type"):
- # Builtin, or no single head name to resolve.
- return None
- # Unknown shape - descend into the first named child and re-classify.
- node = next(iter(node.named_children), None)
-
- return text if is_resolvable_type_name(text, "rust") else None
-
-
-def _pascal_head_type_identifier(type_node: Node, src: str) -> str | None:
- """Return the head identifier of a Pascal ``typeref`` type expression.
-
- Examples:
- ``TFoo`` → "TFoo"
- ``TList<TBar>`` → "TList" (generic head only; the arg
- isn't captured separately -- no
- ``typerefArgs``-scoped query pattern
- exists yet)
- ``Ns.TQualified`` → "TQualified" (rightmost segment;
- Pascal's unit-qualification puts the
- type name last, same convention as
- C#'s ``qualified_name`` handling)
- ``Integer`` / ``TObject`` → None (builtin / VCL root type, never
- has an in-repo declaration)
-
- ``type_node`` is the ``typeref`` node pascal.scm captures directly (a
- ``declProc`` return type) or via the intermediate ``type`` wrapper
- (field/parameter/local-variable positions) -- the wrapper itself is
- never captured, only the ``typeref`` inside it, so this always starts
- from ``typeref`` regardless of which position it came from. A
- ``typeref`` wraps exactly one of: a bare ``identifier``, a generic
- ``typerefTpl`` (``entity`` field holds the head), or a qualified
- ``typerefDot`` (``rhs`` field holds the type name -- ``lhs`` is the
- unit qualifier).
- """
- head = type_node
- if head.type == "typeref":
- head = next(iter(head.named_children), None)
- if head is None:
- return None
- if head.type == "typerefTpl":
- entity = head.child_by_field_name("entity")
- if entity is None:
- return None
- head = entity
- elif head.type == "typerefDot":
- rhs = head.child_by_field_name("rhs")
- if rhs is None:
- return None
- head = rhs
-
- if head.type != "identifier":
- return None
- text = node_text(head, src).strip()
- if not text or text in get_builtin_types("pascal"):
- return None
- return text
-
-
-# ---------------------------------------------------------------------------
-# F# binding, parent and type-head helpers
-# ---------------------------------------------------------------------------
-
-# The two nodes fsharp.scm captures as @symbol.def for a `let` binding. One
-# `function_or_value_defn` holds every clause of a `let rec f ... and g ...`
-# group, so a clause is delimited by the next one of these, not by the node.
-_FSHARP_BINDING_LEFT = ("function_declaration_left", "value_declaration_left")
-
-# A binding whose ancestors include one of these sits inside another
-# binding's body, so it is a local, not a member of the module or type.
-_FSHARP_BODY_OWNERS = (
- "function_or_value_defn",
- "method_or_prop_defn",
- "fun_expression",
- # A top-level `do` block is executed code, not a declaration site.
- "do",
- "do_expression",
-)
-
-# Type shapes whose `type_name` child names the enclosing type of a member.
-_FSHARP_TYPE_OWNERS = (
- "anon_type_defn",
- "record_type_defn",
- "union_type_defn",
- "enum_type_defn",
- "delegate_type_defn",
- "type_abbrev_defn",
- "type_extension",
-)
-
-
-def _fsharp_binding_is_nested(left_node: Node) -> bool:
- """True when a ``let`` binding is local to another binding's body.
-
- A nested ``let`` has the same node shape as a top-level one -- the
- grammar distinguishes them only by what encloses them -- so the generic
- callable-ancestor filter cannot see it: that filter looks for an
- ancestor whose *own* type is a captured callable, and the captured node
- here is the binding's left-hand side, never an ancestor of anything.
- A ``let`` directly inside a type body is deliberately not nested: it is
- that type's field.
- """
- ancestor = left_node.parent # the binding's own function_or_value_defn
- ancestor = ancestor.parent if ancestor is not None else None
- while ancestor is not None:
- if ancestor.type in _FSHARP_BODY_OWNERS:
- return True
- ancestor = ancestor.parent
- return False
-
-
-def _fsharp_binding_end_line(left_node: Node) -> int:
- """Last line of the clause introduced by *left_node*, 1-indexed.
-
- Walks forward to the next clause's left-hand side rather than taking the
- left node's next sibling, because a return-type annotation
- (``let f x : int = ...``) sits between the left node and the body.
- """
- parent = left_node.parent
- if parent is None:
- return left_node.end_point[0] + 1
- end = left_node.end_point[0] + 1
- seen = False
- for child in parent.named_children:
- if child.id == left_node.id:
- seen = True
- continue
- if not seen:
- continue
- if child.type in _FSHARP_BINDING_LEFT or child.type == "xml_doc":
- # A doc comment inside the defn belongs to the clause after it.
- break
- end = max(end, child.end_point[0] + 1)
- return end
-
-
-def _fsharp_binding_has_params(left_node: Node) -> bool:
- """True when a value_declaration_left actually binds a function.
-
- let total (xs: int list) : int = ... has parameters, but the return
- type makes the grammar read the whole head as one value pattern: the
- name and every parameter pattern become siblings inside a single
- identifier_pattern. A plain let x: int = 5 leaves that node with
- the name alone, which is what separates the two.
- """
- holder = next(
- (c for c in left_node.named_children if c.type == "identifier_pattern"), None
- )
- return holder is not None and holder.named_child_count > 1
-
-
-def _fsharp_parent_is_type(def_node: Node) -> bool:
- """True when the innermost owner enclosing an F# symbol is a type rather
- than a nested module.
-
- A ``let`` inside ``module Inner = ...`` is still a plain function, not a
- method -- only a type body turns a binding into a member. The generic
- function-to-method promotion in parser.py has no notion of "module", so
- it needs this to tell the two owners apart before promoting.
- """
- ancestor = def_node.parent
- while ancestor is not None:
- if ancestor.type in _FSHARP_TYPE_OWNERS:
- return True
- if ancestor.type == "module_defn":
- return False
- ancestor = ancestor.parent
- return False
-
-
-def _fsharp_owner_name(owner: Node, src: str) -> str | None:
- """The declared name of one F# type or nested-module node."""
- if owner.type == "module_defn":
- ident = next((c for c in owner.named_children if c.type == "identifier"), None)
- return node_text(ident, src).strip() if ident is not None else None
- name_node = owner.child_by_field_name("type_name")
- if name_node is None:
- holder = next((c for c in owner.named_children if c.type == "type_name"), None)
- name_node = holder.child_by_field_name("type_name") if holder else None
- if name_node is None:
- return None
- if name_node.type == "long_identifier":
- idents = [c for c in name_node.named_children if c.type == "identifier"]
- name_node = idents[-1] if idents else name_node
- return node_text(name_node, src).strip() or None
-
-
-def _fsharp_parent_name(def_node: Node, src: str) -> str | None:
- """Return the dotted owner path of an F# symbol.
-
- No F# type node carries a ``name`` field -- the name lives on a
- ``type_name`` child, tagged with a ``type_name`` field of its own -- so
- the generic nesting walk in ``_find_parent`` finds nothing to read.
-
- Every enclosing nested module joins the path, not just the nearest
- owner: one file may hold ``module A`` and ``module B`` each declaring a
- ``type Dup`` with a ``Go`` member, and a symbol id is path plus parent
- plus name, so a nearest-owner parent would give both members one id.
- A file-level ``module``/``namespace`` header is skipped, since it is the
- whole file and distinguishes nothing within it.
- """
- parts: list[str] = []
- ancestor = def_node.parent
- while ancestor is not None:
- if ancestor.type in _FSHARP_TYPE_OWNERS or ancestor.type == "module_defn":
- name = _fsharp_owner_name(ancestor, src)
- if name:
- parts.append(name)
- ancestor = ancestor.parent
- return ".".join(reversed(parts)) or None
-
-
-def _fsharp_head_type_identifier(type_node: Node, src: str) -> str | None:
- """The resolvable head of an F# type annotation.
-
- ``fsharp_type_name`` does the walk; this adds the filter the type-
- reference pass needs, since a primitive or an FSharp.Core type
- constructor never has an in-repo declaration.
- """
- text = fsharp_type_name(type_node, src)
- if not text or text in get_builtin_types("fsharp"):
- return None
- return text
-
-
-# Per-language head-identifier extractor for ``@param.type`` captures.
-# Defaults to the C#-shaped extractor; languages with a differently-shaped
-# type grammar register their own here.
-def _elixir_head_type_identifier(type_node: Node, src: str) -> str | None:
- """Return the module name in an Elixir type position.
-
- A captured type is always a whole ``alias`` leaf (``%Foo.Bar{}``,
- ``@behaviour GenServer``), and the grammar keeps a dotted module name in
- one node, so the head is the node's own text. No unwrapping to do, and no
- generic-argument shape to recurse into -- unlike every other language
- here, which is why the shared C#-shaped extractor cannot serve.
- """
- if type_node.type != "alias":
- return None
- return node_text(type_node, src).strip() or None
-
-
-def _objc_head_type_identifier(type_node: Node, src: str) -> str | None:
- """Return the head class name of an Objective-C type position, or None.
-
- Examples:
- ``(NSString *)`` -> None (Foundation, never in-repo)
- ``(AFHTTPClient *)`` -> the name
- ``(instancetype)`` -> None (builtin)
- ``(void)`` / ``(id)`` -> None (primitive / builtin)
- ``@class Helper;`` -> "Helper"
-
- The capture is a ``type_name`` wrapper for a method return or parameter
- type, a bare ``type_identifier`` for a property, and a plain
- ``identifier`` for a ``@class`` forward declaration or a protocol name, so
- all four shapes start here. A pointer star lives in an
- ``abstract_pointer_declarator`` inside the ``type_name``, which is skipped
- rather than unwrapped: the star is not part of the name.
- """
- node: Node | None = type_node
- for _ in range(6):
- if node is None:
- return None
- kind = node.type
- if kind in ("type_identifier", "identifier"):
- text = _node_text(node, src).strip()
- return text if is_resolvable_type_name(text, "objectivec") else None
- if kind in ("primitive_type", "sized_type_specifier", "typedefed_specifier"):
- return None
- if kind in ("struct_specifier", "union_specifier", "enum_specifier"):
- name = node.child_by_field_name("name")
- if name is None:
- return None # anonymous aggregate -- no named type to resolve
- text = _node_text(name, src).strip()
- return text if is_resolvable_type_name(text, "objectivec") else None
- node = node.named_children[0] if node.named_children else None
- return None
-
-
-TYPE_HEAD_EXTRACTORS: dict[str, Callable[[Node, str], str | None]] = {
- "go": _go_head_type_identifier,
- "c": _c_head_type_identifier,
- "cpp": _c_head_type_identifier,
- "typescript": _ts_head_type_identifier,
- "javascript": _ts_head_type_identifier,
- "java": _java_head_type_identifier,
- "kotlin": _kotlin_head_type_identifier,
- "rust": _rust_head_type_identifier,
- "pascal": _pascal_head_type_identifier,
- "elixir": _elixir_head_type_identifier,
- "fsharp": _fsharp_head_type_identifier,
- "objectivec": _objc_head_type_identifier,
-}
-
-
-# ---------------------------------------------------------------------------
-# Call extraction helpers
-# ---------------------------------------------------------------------------
-
-
def _count_arguments(arg_node: Node) -> int:
"""Count the number of arguments in an argument/argument_list node.
@@ -1754,44 +217,6 @@ def _count_arguments(arg_node: Node) -> int:
)
-def _rust_type_param_name(param: Node, src: str) -> str | None:
- """Return the bound name of a ``type_parameter``/``const_parameter`` node.
-
- Both node types put the binding name first, before any trait bound or
- default (``T: Clone``, ``D = Foo``, ``const N: usize``) — later
- ``type_identifier`` children are constraints, not the binding itself.
- """
- for child in param.children:
- if child.type in ("type_identifier", "identifier"):
- return node_text(child, src).strip()
- return None
-
-
-def _rust_shadowed_by_type_param(node: Node, target_name: str, src: str) -> bool:
- """True if *target_name* is bound as a generic type parameter by an
- ancestor item of *node* (``struct Wrapper<Item> { value: Item }``).
-
- Rust's field/generic-argument type captures can't distinguish a type
- parameter's own name from a real type reference — both are plain
- ``type_identifier`` nodes. Without this check, a type parameter that
- happens to share a name with a real struct/enum produces a false
- "used" edge to that struct, hiding it from dead-code detection even
- when it is genuinely unreferenced.
- """
- ancestor = node.parent
- while ancestor is not None:
- for child in ancestor.children:
- if child.type != "type_parameters":
- continue
- for param in child.children:
- if param.type not in ("type_parameter", "const_parameter"):
- continue
- if _rust_type_param_name(param, src) == target_name:
- return True
- ancestor = ancestor.parent
- return False
-
-
def _find_enclosing_symbol(
line: int,
symbol_ranges: list[tuple[int, int, str]],
diff --git a/packages/core/src/repowise/core/ingestion/queries/c.scm b/packages/core/src/repowise/core/ingestion/queries/c.scm
index f0e857606..7cf9d048e 100644
--- a/packages/core/src/repowise/core/ingestion/queries/c.scm
+++ b/packages/core/src/repowise/core/ingestion/queries/c.scm
@@ -105,7 +105,7 @@
; no import statement naming the type — only the ``#include`` of the header.
; Without these captures every header struct reads as an unused export. The
; shared ``@param.type`` capture name routes through the C head extractor
-; (see parser_helpers.TYPE_HEAD_EXTRACTORS), which drops the pointer/array
+; (see lang_helpers.type_heads.TYPE_HEAD_EXTRACTORS), which drops the pointer/array
; declarator wrapping (it lives on the declarator side in C, not the type)
; and filters primitive builtins. Mirrors the Go / C# captures.
diff --git a/packages/core/src/repowise/core/ingestion/queries/cpp.scm b/packages/core/src/repowise/core/ingestion/queries/cpp.scm
index 2104d50b6..39e04d666 100644
--- a/packages/core/src/repowise/core/ingestion/queries/cpp.scm
+++ b/packages/core/src/repowise/core/ingestion/queries/cpp.scm
@@ -370,7 +370,7 @@
; carries no import statement naming the type — only the ``#include``.
; Without these captures every header type reads as an unused export. The
; shared ``@param.type`` capture name routes through the C head extractor
-; (see parser_helpers.TYPE_HEAD_EXTRACTORS); pointer/array declarator
+; (see lang_helpers.type_heads.TYPE_HEAD_EXTRACTORS); pointer/array declarator
; wrapping lives on the declarator side, and primitive builtins are filtered.
; Parameter types: void f(Widget *w)
diff --git a/packages/core/src/repowise/core/ingestion/queries/elixir.scm b/packages/core/src/repowise/core/ingestion/queries/elixir.scm
index 47661d9f4..828b79202 100644
--- a/packages/core/src/repowise/core/ingestion/queries/elixir.scm
+++ b/packages/core/src/repowise/core/ingestion/queries/elixir.scm
@@ -34,7 +34,7 @@
; module attribute (`@doc "…"`, `@spec f(t) :: t`) is a `call` under a `@`
; unary_operator, the call patterns below would mint an edge for each one.
; Those two shapes are dropped by `_elixir_call_is_definitional` in
-; parser_helpers.py, which is structural, a predicate cannot see a parent.
+; lang_helpers/elixir.py, which is structural, a predicate cannot see a parent.
; Reserved keyword targets (`def`, `if`, `case`, …) are Kernel macros and are
; dropped by name through the spec's `builtin_calls`.
diff --git a/packages/core/src/repowise/core/ingestion/queries/java.scm b/packages/core/src/repowise/core/ingestion/queries/java.scm
index ff4674fa9..c1a5ccc94 100644
--- a/packages/core/src/repowise/core/ingestion/queries/java.scm
+++ b/packages/core/src/repowise/core/ingestion/queries/java.scm
@@ -177,7 +177,7 @@
; type of a factory, the element type of ``new Foo()``. The single
; ``@param.type`` capture is reused across languages
; (see parser._extract_type_refs); the Java head extractor in
-; parser_helpers.py unwraps ``T[]`` / ``Foo<...>`` / ``ns.Foo`` / annotated
+; lang_helpers/type_heads.py unwraps ``T[]`` / ``Foo<...>`` / ``ns.Foo`` / annotated
; types and filters primitives plus the most ubiquitous ``java.lang`` /
; ``java.util`` / ``java.util.function`` builtins.
diff --git a/packages/core/src/repowise/core/ingestion/queries/kotlin.scm b/packages/core/src/repowise/core/ingestion/queries/kotlin.scm
index 4c7d5f633..6b896adf1 100644
--- a/packages/core/src/repowise/core/ingestion/queries/kotlin.scm
+++ b/packages/core/src/repowise/core/ingestion/queries/kotlin.scm
@@ -111,7 +111,7 @@
; of which carry an import statement of their own. The single
; ``@param.type`` capture is reused across languages
; (see parser._extract_type_refs); the Kotlin head extractor in
-; parser_helpers.py unwraps ``Foo?`` / ``List<Foo>`` / dotted ``ns.Foo`` and
+; lang_helpers/type_heads.py unwraps ``Foo?`` / ``List<Foo>`` / dotted ``ns.Foo`` and
; filters the kotlin-stdlib ubiquitous types.
; Function parameter: fun f(x: Bar) — `(user_type)` and `(nullable_type)`
diff --git a/packages/core/src/repowise/core/ingestion/queries/pascal.scm b/packages/core/src/repowise/core/ingestion/queries/pascal.scm
index 433aeb348..8ff4faf4a 100644
--- a/packages/core/src/repowise/core/ingestion/queries/pascal.scm
+++ b/packages/core/src/repowise/core/ingestion/queries/pascal.scm
@@ -229,7 +229,7 @@
; pascal.scm had no `@param.type` captures (unlike C#/Go/Java/Kotlin/TS).
; ``parser.py:_extract_type_refs`` collects these into TypeReference
; records generically; ``_pascal_head_type_identifier`` in
-; parser_helpers.py unwraps the `typeref` shape (plain / generic
+; lang_helpers/type_heads.py unwraps the `typeref` shape (plain / generic
; `typerefTpl` / qualified `typerefDot`) down to the head identifier.
; Verified against MTN2: TConsoleBuffer / TDialogHost read as having zero
; importers despite being referenced in 10-18 files, exclusively through
diff --git a/packages/core/src/repowise/core/ingestion/queries/rust.scm b/packages/core/src/repowise/core/ingestion/queries/rust.scm
index 2cbf657fb..157cf67a4 100644
--- a/packages/core/src/repowise/core/ingestion/queries/rust.scm
+++ b/packages/core/src/repowise/core/ingestion/queries/rust.scm
@@ -338,7 +338,7 @@
;
; Each pattern captures the parameter/return type node itself (whatever shape
; it is), not just a bare ``type_identifier``; the Rust head extractor in
-; parser_helpers.py unwraps ``&T`` / ``Box<T>`` / ``dyn T`` / ``impl T`` /
+; lang_helpers/type_heads.py unwraps ``&T`` / ``Box<T>`` / ``dyn T`` / ``impl T`` /
; ``std::io::Error`` down to the head identifier, and filters the 55 rust
; builtins, so a wrapper capture cannot mint a wrong edge -- it resolves to
; the same head name a bare capture would, or to nothing.
diff --git a/packages/core/src/repowise/core/ingestion/queries/typescript.scm b/packages/core/src/repowise/core/ingestion/queries/typescript.scm
index 96538dcdd..bfe0f35d4 100644
--- a/packages/core/src/repowise/core/ingestion/queries/typescript.scm
+++ b/packages/core/src/repowise/core/ingestion/queries/typescript.scm
@@ -281,7 +281,7 @@
;
; Mirrors the C# / Go pattern: a single ``@param.type`` capture name fans
; in every position where a user-defined type appears outside an import
-; statement. The TypeScript head extractor in parser_helpers.py unwraps
+; statement. The TypeScript head extractor in lang_helpers/type_heads.py unwraps
; ``Foo[]`` / ``Promise<Foo>`` / ``ns.Foo`` / ``Foo | Bar`` shells and
; filters TS builtins (``string`` / ``number`` / ``Promise`` / ...). The
; result lets the dead-code analyzer see an ``interface Foo`` referenced
diff --git a/packages/core/src/repowise/core/ingestion/sfc_source.py b/packages/core/src/repowise/core/ingestion/sfc_source.py
index d421a8234..dd6b81ef3 100644
--- a/packages/core/src/repowise/core/ingestion/sfc_source.py
+++ b/packages/core/src/repowise/core/ingestion/sfc_source.py
@@ -41,7 +41,7 @@ not reads, so keeping them would mint phantom identifier references.
:func:`prepare_source` is also where a language registers a byte-preserving
sanitizer for a grammar gap that has nothing to do with multi-language files —
Pascal's project-file ``uses X in 'path'`` clauses being the current example,
-handled by ``prepare_pascal_source`` in ``parser_helpers.py``. Same contract as
+handled by ``prepare_pascal_source`` in ``lang_helpers/source_prep.py``. Same contract as
a :class:`Locator`, no-op unless the language matches.
"""
diff --git a/tests/unit/test_no_bare_type_name_copies.py b/tests/unit/test_no_bare_type_name_copies.py
index 02608af51..13fffa110 100644
--- a/tests/unit/test_no_bare_type_name_copies.py
+++ b/tests/unit/test_no_bare_type_name_copies.py
@@ -15,7 +15,7 @@ over the whole tree it would match hundreds of legitimate uses and mean nothing.
Ceiling: string shape only. A copy that reaches for ``re``, splits on a
separator held in a variable, or navigates the syntax tree instead of the text
-stays invisible — the per-language head extractors in ``parser_helpers.py`` are
+stays invisible — the per-language head extractors in ``lang_helpers/type_heads.py`` are
node walks and are deliberately out of reach. It catches the shape that
actually recurred here.
@@ -54,6 +54,7 @@ _SCOPE = (
_INGESTION / "framework_edges",
_INGESTION / "languages",
_INGESTION / "parser_helpers.py",
+ _INGESTION / "lang_helpers",
_INGESTION / "type_ref_resolution.py",
_INGESTION / "call_resolver.py",
_INGESTION / "heritage_resolver.py",