From 30f1a0879133496742a4cdb8e6ac0324441e629d Mon Sep 17 00:00:00 2001 From: MCR-3 Date: Sun, 11 Oct 2026 10:45:57 +0200 Subject: [PATCH 1/6] refactor(backend): let a language plugin claim an extension conditionally C owns `.h` outright, but a header in a project that also holds C++ files is C++. The dispatcher mapped each extension to exactly one plugin, so it had no way to express that. A plugin can now list `conditional_extensions` and decide per load, in `claims()`, whether it takes them. The dispatcher asks once per distinct extension, in registry order, and falls back to the unconditional owner when nobody claims it, so a load that has no claimant routes exactly as before. --- backend/analyzer.py | 20 +++++++++++++++++++- backend/languages/base.py | 29 ++++++++++++++++++++++++----- backend/languages/c.py | 3 ++- 3 files changed, 45 insertions(+), 7 deletions(-) diff --git a/backend/analyzer.py b/backend/analyzer.py index a004d89..fe8e30e 100644 --- a/backend/analyzer.py +++ b/backend/analyzer.py @@ -1,6 +1,10 @@ """Multi-language dispatcher: groups sources by extension, hands each slice to its language plugin (see backend/languages/), and merges the results. +An extension goes to the first plugin that claims it for this load through +`conditional_extensions` / `claims()` (C++ taking `.h` when the root holds a +C++-only file), and otherwise to its unconditional owner. + Every plugin returns the same {"files", "functions", "edges"} shape (see backend/languages/base.py), so merging across languages is just concatenation - function/file ids are already namespaced by file path, so @@ -12,8 +16,10 @@ import json import os import sys +from collections.abc import Collection from .languages import EXTENSION_TO_LANGUAGE, LANGUAGES, SKIP_DIRS, SUPPORTED_EXTENSIONS +from .languages.base import LanguagePlugin def _collect_source_files(root: str) -> list[str]: @@ -29,15 +35,27 @@ def _collect_source_files(root: str) -> list[str]: return found +def _owner(ext: str, paths: Collection[str]) -> LanguagePlugin | None: + """The plugin that takes `ext` in this load: the first (registry order) to + claim it conditionally, otherwise its unconditional owner.""" + for lang in LANGUAGES: + if ext in lang.conditional_extensions and lang.claims(ext, paths): + return lang + return EXTENSION_TO_LANGUAGE.get(ext) + + def analyze_sources(sources: dict[str, str], root: str = "") -> dict: """Analyze in-memory sources, e.g. files picked and read in the browser. sources: rel_path (forward slashes) -> file content, already read. """ by_language: dict[str, dict[str, str]] = {} + owners: dict[str, LanguagePlugin | None] = {} for rel_path, content in sources.items(): ext = os.path.splitext(rel_path)[1] - lang = EXTENSION_TO_LANGUAGE.get(ext) + if ext not in owners: + owners[ext] = _owner(ext, sources.keys()) + lang = owners[ext] if lang is None: continue by_language.setdefault(lang.id, {})[rel_path] = content diff --git a/backend/languages/base.py b/backend/languages/base.py index 07b9419..bd6bf7d 100644 --- a/backend/languages/base.py +++ b/backend/languages/base.py @@ -1,14 +1,16 @@ """Shared types and the plugin contract every backend/languages/*.py module implements. -Each language plugin gets a slice of sources (already filtered to its own -extensions) and returns the same {"files", "functions", "edges"} shape, -built from the same FunctionInfo schema, so the frontend contract stays -identical no matter which languages produced it. +Each language plugin gets a slice of sources (already filtered to the +extensions it owns or claimed for this load) and returns the same +{"files", "functions", "edges"} shape, built from the same FunctionInfo +schema, so the frontend contract stays identical no matter which languages +produced it. """ from __future__ import annotations from abc import ABC, abstractmethod +from collections.abc import Collection from dataclasses import dataclass, field # Directories skipped while walking a disk tree, shared across all languages @@ -86,10 +88,27 @@ class LanguagePlugin(ABC): id: str # "python", "rust" - stamped onto each file/function unless the plugin sets its own label: str # "Python", "Rust" extensions: frozenset[str] # {".py"}, {".rs"} - dot-prefixed, lowercase + # Extensions this plugin MAY claim, in addition to `extensions` - dot-prefixed, + # lowercase. `extensions` are owned unconditionally (C keeps `.h` as the + # fallback); a conditional extension goes to this plugin only for a load where + # `claims()` says so (C++ takes `.h` when the root holds a C++-only file). + conditional_extensions: frozenset[str] = frozenset() + + def claims(self, ext: str, paths: Collection[str]) -> bool: + """Whether this plugin takes files with the extension `ext` (one of its + `conditional_extensions`) in this load. + + `paths` is every relative path (forward slashes) handed to the analyzer, + of any language. The dispatcher asks once per distinct extension per + load, in registry order; the first plugin to claim it wins, and when none + does the unconditional owner (`extensions`) gets the files. Default: False. + """ + return False @abstractmethod def analyze(self, sources: dict[str, str]) -> dict: - """sources: rel_path (forward slashes) -> content, already filtered to `extensions`. + """sources: rel_path (forward slashes) -> content, already filtered to + `extensions` plus any `conditional_extensions` this plugin claimed. Returns {"files": [...], "functions": {...}, "edges": [...]} - the same shape the top-level analyzer.py dispatcher returns, scoped to diff --git a/backend/languages/c.py b/backend/languages/c.py index b7d65df..c234f5d 100644 --- a/backend/languages/c.py +++ b/backend/languages/c.py @@ -1,6 +1,7 @@ """C language plugin: tree-sitter-based analysis of C source trees. -Owns `.c` and `.h` (until C++ lands, a header is always C). Nothing is +Owns `.c` and `.h`, except that the C++ plugin claims `.h` when the picked +root contains a C++-only extension; a C-only root is unaffected. Nothing is preprocessed or compiled: the plugin reads the text of each file as written, and resolves calls by name, following the way a C program's names are actually visible. From 0bea854b88bd93a27a661ff84b3f1dfd86aae623 Mon Sep 17 00:00:00 2001 From: MCR-3 Date: Sun, 11 Oct 2026 10:45:57 +0200 Subject: [PATCH 2/6] refactor(backend): read C++ declarator shapes in the shared C-family helpers The C++ plugin reuses these helpers, but a few C++ parameter and declarator shapes were invisible to them: default arguments, `&` and `&&` declarators, parameter packs and the bare `...` token. Teach `extract_params` and the declarator walkers about them; none of these nodes occur in a C tree, so the C plugin's output is unchanged. `walk_top_level` now uses a stack instead of recursion so deeply nested `#if` blocks cannot exhaust Python's recursion limit. --- backend/languages/cfamily.py | 55 +++++++++++++++++++++++++++--------- 1 file changed, 42 insertions(+), 13 deletions(-) diff --git a/backend/languages/cfamily.py b/backend/languages/cfamily.py index 4b6d0eb..1c2b3f6 100644 --- a/backend/languages/cfamily.py +++ b/backend/languages/cfamily.py @@ -3,8 +3,10 @@ C and C++ are separate plugins (separate Languages, badges and highlighting), but they read the same declarator syntax, the same comment conventions and the same `#include` directives. Everything here works on a plain tree-sitter -tree and knows nothing about either plugin's resolution rules, so the C++ -plugin can reuse it unchanged. +tree and knows nothing about either plugin's resolution rules. The few C++ +node shapes handled here (`&name`, `...args`, default arguments, a bare `...` +token) never occur in a C tree, so what the C plugin gets back is unaffected +by them. """ from __future__ import annotations @@ -37,6 +39,7 @@ { "pointer_declarator", "reference_declarator", + "variadic_declarator", "array_declarator", "function_declarator", "parenthesized_declarator", @@ -44,6 +47,10 @@ "init_declarator", } ) +# C++ wrappers that carry their inner declarator as an unnamed child: `&name`, `&&name`, `...args`. +_UNNAMED_INNER_TYPES = frozenset({"reference_declarator", "variadic_declarator"}) +# A function parameter: `int n`, and in C++ `int n = 3` and `Args &&...args`. +PARAMETER_TYPES = frozenset({"parameter_declaration", "optional_parameter_declaration", "variadic_parameter_declaration"}) def node_text(node: Node | None, source: bytes) -> str: @@ -70,10 +77,14 @@ def split_lines(source: str) -> list[str]: def walk_top_level(node: Node, transparent: frozenset[str] = TRANSPARENT_TYPES) -> Iterator[Node]: - """Every top-level item under `node`, looking through preprocessor branches and linkage blocks.""" - for child in node.children: + """Every top-level item under `node`, in source order, looking through preprocessor branches and linkage + blocks (with a stack rather than recursion, so no depth of nested `#if` can exhaust Python's). + """ + stack = list(reversed(node.children)) + while stack: + child = stack.pop() if child.type in transparent: - yield from walk_top_level(child, transparent) + stack.extend(reversed(child.children)) else: yield child @@ -100,6 +111,13 @@ def declarator_name(declarator: Node | None, source: bytes) -> str | None: return node_text(declarator_name_node(declarator), source) or None +def _inner_declarator(declarator: Node) -> Node | None: + inner = declarator.child_by_field_name("declarator") + if inner is None and declarator.type in _UNNAMED_INNER_TYPES: + inner = next((c for c in declarator.named_children if c.type in _NAME_TYPES or c.type in _WRAPPER_TYPES), None) + return inner + + def function_declarator_of(declarator: Node | None) -> Node | None: """The `function_declarator` in a definition's declarator chain (`*dup(...)` wraps one in a pointer).""" while declarator is not None: @@ -107,7 +125,7 @@ def function_declarator_of(declarator: Node | None) -> Node | None: return declarator if declarator.type not in _WRAPPER_TYPES: return None - declarator = declarator.child_by_field_name("declarator") + declarator = _inner_declarator(declarator) return None @@ -130,7 +148,7 @@ def pointer_depth(declarator: Node | None) -> int: depth += 1 elif declarator.type not in _WRAPPER_TYPES: break - declarator = declarator.child_by_field_name("declarator") + declarator = _inner_declarator(declarator) return depth @@ -145,26 +163,37 @@ def extract_params(fn_declarator: Node | None, source: bytes) -> list[dict]: """A function declarator's parameters as {"name", "annotation", "default"}, with the C type as the annotation. `(void)` is no parameters; `...` is a parameter named `...`; an old-style `f(a, b)` name list is kept as names. + A C++ default argument (`int n = 3`) is the default, and a pack (`Args &&...args`) keeps its `...` in the type. """ params_node = fn_declarator.child_by_field_name("parameters") if fn_declarator is not None else None params: list[dict] = [] if params_node is None: return params - for child in params_node.named_children: - if child.type == "parameter_declaration": + for child in params_node.children: + if not child.is_named: + if child.type == "...": # C++ has the C-style ellipsis as a bare token, C as a variadic_parameter + params.append({"name": "...", "annotation": None, "default": None}) + continue + if child.type in PARAMETER_TYPES: + default_node = child.child_by_field_name("default_value") + default = None + end_byte = child.end_byte + if default_node is not None: + default = _collapse(node_text(default_node, source)) + end_byte = next((c.start_byte for c in child.children if c.type == "="), default_node.start_byte) + raw = source[child.start_byte : end_byte] name_node = declarator_name_node(child.child_by_field_name("declarator")) if name_node is None: - text = _collapse(node_text(child, source)) + text = _collapse(raw.decode("utf-8", "replace")) if text == "void" and len(params_node.named_children) == 1: continue - params.append({"name": text, "annotation": None, "default": None}) + params.append({"name": text, "annotation": None, "default": default}) continue # the type is everything in the parameter except the name itself start = name_node.start_byte - child.start_byte end = name_node.end_byte - child.start_byte - raw = source[child.start_byte : child.end_byte] annotation = _collapse((raw[:start] + raw[end:]).decode("utf-8", "replace")) - params.append({"name": node_text(name_node, source), "annotation": annotation or None, "default": None}) + params.append({"name": node_text(name_node, source), "annotation": annotation or None, "default": default}) elif child.type == "variadic_parameter": params.append({"name": "...", "annotation": None, "default": None}) elif child.type == "identifier": From 921accc82969905d3eea026a6552a2884ca01999 Mon Sep 17 00:00:00 2001 From: MCR-3 Date: Sun, 11 Oct 2026 10:45:57 +0200 Subject: [PATCH 3/6] feat(backend): add C++ language plugin Reads `.cc .cpp .cxx .hpp .hh .hxx`, and claims `.h` when the picked root holds any of those, with tree-sitter-cpp and the C-family helpers. Functions are definitions with a body: free functions, in-class and out-of-class methods, constructors, destructors and operators, named by their scoped qualname, with a parameter-type suffix only for overloads that collide in one file. Calls resolve by C++'s own scoping (class and bases, namespaces, using declarations, then the C plugin's include-based visibility) and member calls by the receiver's declared type. When a type is not visible the call links only to the one loaded method of that name, and a tie never produces a guessed edge. Virtual calls link to the declared class's own method, never fanning out to overrides. --- backend/languages/__init__.py | 13 +- backend/languages/cpp.py | 1218 +++++++++++++++++++++++++++++++++ backend/requirements.txt | 1 + 3 files changed, 1228 insertions(+), 4 deletions(-) create mode 100644 backend/languages/cpp.py diff --git a/backend/languages/__init__.py b/backend/languages/__init__.py index cb60bfe..f7b8379 100644 --- a/backend/languages/__init__.py +++ b/backend/languages/__init__.py @@ -2,22 +2,27 @@ To add a language: implement a LanguagePlugin in a new module (see python.py / rust.py) and add an instance to LANGUAGES below. Nothing -outside this package needs to change - analyzer.py dispatches purely off -file extension. +outside this package needs to change - analyzer.py dispatches off file +extension (and, for an extension a plugin only claims conditionally, such as +C++ taking `.h`, off that plugin's `claims()`; see base.py). """ from __future__ import annotations from .base import SKIP_DIRS, LanguagePlugin from .c import CLanguage +from .cpp import CppLanguage from .python import PythonLanguage from .rust import RustLanguage from .typescript import TypeScriptLanguage -LANGUAGES: list[LanguagePlugin] = [PythonLanguage(), RustLanguage(), TypeScriptLanguage(), CLanguage()] +LANGUAGES: list[LanguagePlugin] = [PythonLanguage(), RustLanguage(), TypeScriptLanguage(), CLanguage(), CppLanguage()] +# Each extension's unconditional owner; a plugin's `conditional_extensions` are not in here (see analyzer.py). EXTENSION_TO_LANGUAGE: dict[str, LanguagePlugin] = {ext: lang for lang in LANGUAGES for ext in lang.extensions} -SUPPORTED_EXTENSIONS: frozenset[str] = frozenset(EXTENSION_TO_LANGUAGE) +SUPPORTED_EXTENSIONS: frozenset[str] = frozenset( + ext for lang in LANGUAGES for ext in lang.extensions | lang.conditional_extensions +) __all__ = ["SKIP_DIRS", "LanguagePlugin", "LANGUAGES", "EXTENSION_TO_LANGUAGE", "SUPPORTED_EXTENSIONS"] diff --git a/backend/languages/cpp.py b/backend/languages/cpp.py new file mode 100644 index 0000000..9c1c396 --- /dev/null +++ b/backend/languages/cpp.py @@ -0,0 +1,1218 @@ +"""C++ language plugin: tree-sitter-based analysis of C++ source trees. + +Owns `.cc`, `.cpp`, `.cxx`, `.hpp`, `.hh` and `.hxx`, and claims `.h` for a +load that contains any of those (in a C-only load a header stays C). C and +C++ are separate plugins, so no Call edge joins a C file to a C++ one. As in +the C plugin, nothing is preprocessed or compiled: the plugin reads each file +as written and resolves calls by name, following C++'s own scoping, and it +never picks one candidate out of several. + +Functions are definitions only, a function with a body: free functions, +methods defined in their class or out of it (`void Catalog::add(...) {}`), +constructors, destructors, operators and conversion operators. A declaration +alone (an in-class or header prototype, `= default`, `= delete`, a pure +virtual) is not a Function. `qualname` is the scoped name, `ns::Class::method` +(`Outer::Inner::method` for a nested class), `className` is the qualified +class a method belongs to, and `module` is the file path without its +extension. Template arguments are dropped, so a template is one Function. A +friend function defined in its class belongs to the enclosing namespace. +Lambdas are not Functions: a call inside one belongs to the Function the +lambda is written in. The id is `::`. Overloads defined in one +file get their parameter types as a suffix in `name`, `qualname` and the id +(`add(int)`, `add(const std::string &)`, `at(int) const`); a name defined once +in its file keeps its plain name, and identical definitions in one file (the +branches of an `#ifdef`) get `#2`, `#3` appended to the id. + +The contiguous own-line comment block directly above a definition (above its +`template <...>` line, if any) is its docstring, as in C. A definition with +no such comment takes the one above a declaration of the same qualified name +(the in-class prototype, a header prototype) in its own file or a file it +reaches through quoted includes. Default arguments written only on such a +declaration still count when a call is matched by its number of arguments. + +A call resolves at the first step that finds any candidate. When that step +finds several (overloads, or definitions in several files), the call links +only if the number of arguments, counting default arguments and `...`, +leaves exactly one of them. +- An unqualified `f()` is looked up in the enclosing class and its loaded + base classes (so `m()` in a method finds the method wherever it is + defined), then in each enclosing namespace from the innermost out, then in + what the file's `using namespace ns;` and `using ns::f;` bring in, then at + global scope. Outside a class the C plugin's visibility applies: the same + file first, then files reached through quoted `#include "..."` and the + `.cpp`/`.cc`/`.cxx` files implementing those headers (same file stem, the + header's own directory first), then the one definition visible anywhere. A + `static` free function, or one in an anonymous namespace, is visible only + in its own file and in files that include it. +- `Class::m()` and `ns::f()` find their qualifier from the enclosing scopes + outwards (`::f()` only at global scope), then look the name up in that + class and its bases, or in that namespace. +- `this->m()`, `obj.m()` and `obj->m()` look the method up in the receiver's + class, then its bases, the first class of the chain that defines it + winning: a call through a `Base &` links to `Base::run` when it has a body, + never to the overrides. The receiver's class is the enclosing class for + `this`, the declared type of a parameter, a local variable or a data member + of a loaded class (`items_`, `this->items_`, `order.item`), or the target of + a `static_cast(...)`-style cast; `const Foo &`, `Foo *`, + `std::unique_ptr`, `std::shared_ptr` and a `using` or `typedef` + alias of one all mean `Foo`. When the type is not visible (`auto`, a + template parameter, a returned value, a member that was not loaded), or the + class chain has no definition of the method (a pure virtual), the call + links to the one loaded method of that name, if there is exactly one. A + visible type that is not a loaded class (`std::string`, `int`) links + nothing. +- A constructor is called by `new T(...)`, `T(...)`, `T{...}`, `T var(...)`, + `T var{...}` and a base initializer `: Base(...)`; `T var(x);`, which C++'s + grammar also reads as a function declaration, is taken as a variable unless + `x` names a class. A plain `T var;`, a copy and a destruction are not + linked. +- A call whose name is a parameter or a local variable (`cb(x)`, a lambda + held in a variable) is indirect and never linked. + +Real limits: nothing is preprocessed, so a function defined by a macro is not +a Function, a call hidden in a macro is invisible, and a class body holding +an unknown macro (`Q_OBJECT`) can lose methods to tree-sitter's error +recovery (such a file is flagged with an error but keeps whatever functions +were recovered from it); every `#ifdef` branch is parsed; templates are not +instantiated, so a call on a value of a template parameter's type only gets +the unique-name fallback; there is no argument-dependent lookup and no +overload resolution by argument types; operator expressions (`a + b`) and +implicit conversions are not linked; calls through function pointers, +member pointers and `std::function` are not linked; and virtual dispatch to +overrides is not followed. +""" + +from __future__ import annotations + +import math +import os +import posixpath +import re +import tree_sitter_cpp +from collections.abc import Collection +from dataclasses import dataclass, field, replace +from tree_sitter import Language, Node, Parser + +from .base import FunctionInfo, LanguagePlugin, build_edges, dedupe_calls +from .cfamily import ( + PARAMETER_TYPES, + TRANSPARENT_TYPES, + comment_block_above, + declarator_name_node, + extract_params, + function_declarator_of, + is_static, + make_code_lines, + node_text, + prepare_source, + quoted_includes, + reached_files, + resolve_include, + split_lines, + suffix_index, +) + +_CPP_LANGUAGE = Language(tree_sitter_cpp.language()) + +# A header is implemented by a source file of the same stem. +_HEADER_EXTENSIONS = frozenset({".h", ".hh", ".hpp", ".hxx"}) +_SOURCE_EXTENSIONS = frozenset({".cc", ".cpp", ".cxx"}) + +_CLASS_TYPES = frozenset({"class_specifier", "struct_specifier", "union_specifier"}) +# Nodes whose children are items of the same scope: a namespace or class body, an `#ifdef` branch. +_CONTAINER_TYPES = TRANSPARENT_TYPES | {"field_declaration_list"} +_TYPE_PARAMETER_TYPES = frozenset( + { + "type_parameter_declaration", + "optional_type_parameter_declaration", + "variadic_type_parameter_declaration", + "template_template_parameter_declaration", + } +) +# Declarators a definition's function declarator can sit in: `Foo &Foo::get()`, `char *name()`. +_DEFINITION_WRAPPERS = frozenset( + {"pointer_declarator", "reference_declarator", "attributed_declarator", "parenthesized_declarator"} +) +_DECLARATOR_TYPES = _DEFINITION_WRAPPERS | {"function_declarator", "operator_cast", "qualified_identifier"} +# Types whose meaning is only known once the program is compiled: a variable of one has no visible class. +_OPAQUE_TYPES = frozenset({"placeholder_type_specifier", "decltype", "dependent_type"}) +_SMART_POINTERS = frozenset({"unique_ptr", "shared_ptr"}) +_CASTS = frozenset({"static_cast", "dynamic_cast", "reinterpret_cast", "const_cast"}) +# Nodes pass 2 inspects for calls; everything else is only walked through. +_CALL_SITES = frozenset({"call_expression", "new_expression", "compound_literal_expression", "declaration", "field_initializer"}) + +# The class of a variable whose type is not visible (`auto`, a template parameter): calls on it fall +# back to the one loaded method of the name. Never a valid class name. +_OPAQUE = "?" + + +@dataclass(frozen=True) +class _Scope: + """Where a walk is: the enclosing namespaces and class, as written.""" + + namespace: tuple[str, ...] = () + cls: str | None = None # the qualified class whose body this is + local: bool = False # inside an anonymous namespace + template_params: frozenset[str] = frozenset() + + +@dataclass +class _CppFile: + rel_path: str # forward slashes + module: str # the path without its extension + source: bytes + lines: list[str] + include_paths: list[str] = field(default_factory=list) # the quoted paths as written + # each `using` as (the namespace it sits in, the path written, whether it is a `using namespace`) + using: list[tuple[tuple[str, ...], tuple[str, ...], bool]] = field(default_factory=list) + using_namespaces: list[str] = field(default_factory=list) # qualified, from `using namespace ns;` + using_names: dict[str, list[str]] = field(default_factory=dict) # name -> qualified names, from `using ns::f;` + + +@dataclass +class _Class: + # each base as (its name as written, the scopes it is looked up from, the file) + bases: list[tuple[tuple[str, ...], tuple[str, ...], str]] = field(default_factory=list) + # data member -> (its type's class name as parts, None for a type naming no class, or _OPAQUE; lookup scopes; file) + fields: dict[str, tuple[tuple[str, ...] | str | None, tuple[str, ...], str]] = field(default_factory=dict) + chain: list[str] | None = None # the class, then its loaded bases depth first; filled on first use + + +@dataclass +class _Decl: + """A function definition or declaration, as read in pass 1.""" + + file: _CppFile + scope: _Scope + written: tuple[str, ...] # the qualifier before the name: ("Catalog",) for `Catalog::add` + name: str # `add`, `Catalog`, `~Catalog`, `operator+=`, `operator bool` + friend: bool + params: list[dict] + signature: str # `(const Item &, int) const`: the parameter types and trailing qualifiers, normalised + min_args: int + max_args: float + # set once every file is read + owner: str = "" # the qualified class or namespace it belongs to; "" is the global namespace + is_method: bool = False + lookup: tuple[str, ...] = () # the scopes an unqualified name is looked up in, innermost first, ending with "" + # definitions only + node: Node | None = None # the function_definition + span: Node | None = None # the outermost node the definition is written as (`template <...>`, `friend`) + local: bool = False # visible only to its own file and its includers + # declarations only + doc: str | None = None + + @property + def qualname(self) -> str: + return _join(self.owner, self.name) + + +def _join(*parts: str) -> str: + return "::".join(part for part in parts if part) + + +def _scopes_of(qualified: str) -> tuple[str, ...]: + """A scope and every scope enclosing it, innermost first: `a::B` -> ("a::B", "a", "").""" + parts = qualified.split("::") if qualified else [] + return tuple("::".join(parts[:i]) for i in range(len(parts), -1, -1)) + + +def _collapse(text: str) -> str: + return re.sub(r"\s+", " ", text).strip() + + +def _operator_name(text: str) -> str: + """`operator +=` -> `operator+=`, `operator new [ ]` -> `operator new[]`.""" + rest = _collapse(text[len("operator") :]) + if rest[:1].isalpha() or rest[:1] == "_": + return "operator " + re.sub(r"\s+(?=[\[\]])", "", rest) + return "operator" + rest.replace(" ", "") + + +def _normalise_type(text: str) -> str: + """One spelling per type: `const Foo&` and `const Foo &` -> `const Foo &`, `std::map< int,Foo* >` -> + `std::map`.""" + text = re.sub(r"\s*([*&]+)\s*", r" \1 ", text) + text = re.sub(r"\s*([<>()\[\]])\s*", r"\1", text) + text = re.sub(r"\s*,\s*", ", ", text) + return _collapse(text) + + +def _name_parts(node: Node | None, source: bytes) -> tuple[tuple[str, ...], str] | None: + """A declarator's or a call's name as (qualifier as written, name), template arguments dropped: + `Box::get` -> (("Box",), "get"), `twice` -> ((), "twice"). A leading `::` is an empty first part. + """ + if node is None: + return None + kind = node.type + if kind in ("identifier", "field_identifier", "type_identifier", "namespace_identifier"): + return (), node_text(node, source) + if kind == "destructor_name": + inner = node.named_children[0] if node.named_children else None + return ((), "~" + node_text(inner, source)) if inner is not None else None + if kind == "operator_name": + return (), _operator_name(node_text(node, source)) + if kind == "operator_cast": + return (), "operator " + _collapse(node_text(node.child_by_field_name("type"), source)) + if kind in ("template_function", "template_method", "template_type"): + return _name_parts(node.child_by_field_name("name"), source) + if kind in ("dependent_name", "parenthesized_declarator"): # `obj.template m()`, `int (f)(int)` + return _name_parts(node.named_children[0] if node.named_children else None, source) + if kind == "qualified_identifier": # `a::b::c` nests to the right: (a, (b, c)) + written: list[str] = [] + while node is not None and node.type == "qualified_identifier": + scope = node.child_by_field_name("scope") + outer = _name_parts(scope, source) if scope is not None else ((), "") + if outer is None: + return None + written.extend((*outer[0], outer[1])) + node = node.child_by_field_name("name") + rest = _name_parts(node, source) + return ((*written, *rest[0]), rest[1]) if rest is not None else None + return None + + +def _function_parts(declarator: Node | None) -> tuple[Node, Node | None] | None: + """A function declarator's name node and the node holding its parameters, or None for anything else + (a variable, a function pointer). Conversion operators (`operator bool() const`) have their own shape. + """ + while declarator is not None: + kind = declarator.type + if kind == "function_declarator": + name = declarator.child_by_field_name("declarator") + return (name, declarator) if name is not None else None + if kind == "operator_cast": + return declarator, declarator.child_by_field_name("declarator") + if kind == "qualified_identifier": # `Foo::operator bool() const` + last = declarator + while last is not None and last.type == "qualified_identifier": + last = last.child_by_field_name("name") + if last is not None and last.type == "operator_cast": + return declarator, last.child_by_field_name("declarator") + return None + if kind not in _DEFINITION_WRAPPERS: + return None + declarator = declarator.child_by_field_name("declarator") or next( + (c for c in declarator.named_children if c.type in _DECLARATOR_TYPES), None + ) + return None + + +def _signature(params: list[dict], holder: Node | None, source: bytes) -> str: + types = [_normalise_type(p["annotation"] or p["name"]) for p in params] + trailing = holder.children if holder is not None else [] + qualifiers = [node_text(c, source) for c in trailing if c.type in ("type_qualifier", "ref_qualifier")] + suffix = " " + " ".join(qualifiers) if qualifiers else "" + return f"({', '.join(types)}){suffix}" + + +def _arity(params: list[dict]) -> tuple[int, float]: + """How many arguments a call can pass: (required, most), `...` and parameter packs taking any number.""" + required = total = 0 + variadic = False + for p in params: + if p["name"] == "..." or (p["annotation"] or p["name"]).endswith("..."): + variadic = True + continue + total += 1 + if p["default"] is None: + required += 1 + return required, math.inf if variadic else total + + +def _arg_count(args: Node | None) -> int: + return sum(1 for c in args.named_children if c.type != "comment") if args is not None else 0 + + +def _return_type(fn_node: Node, holder: Node | None, source: bytes) -> str | None: + """A definition's return type as written: `const`, the type, then its `*` and `&`; a trailing `-> T` wins.""" + trailing = next((c for c in holder.children if c.type == "trailing_return_type"), None) if holder else None + if trailing is not None: + return _collapse(node_text(trailing, source).removeprefix("->")) or None + type_node = fn_node.child_by_field_name("type") + if type_node is None: + return None # constructors, destructors, conversion operators + qualifiers = [node_text(c, source) for c in fn_node.children if c.type == "type_qualifier"] + text = _collapse(" ".join([*(q for q in qualifiers if q in ("const", "volatile")), node_text(type_node, source)])) + marks = "" + declarator = fn_node.child_by_field_name("declarator") + while declarator is not None and declarator.type in ("pointer_declarator", "reference_declarator"): + marks += "*" if declarator.type == "pointer_declarator" else node_text(declarator.children[0], source) + declarator = declarator.child_by_field_name("declarator") or next( + (c for c in declarator.named_children if c.type in _DECLARATOR_TYPES), None + ) + return f"{text} {marks}" if marks else text + + +def _type_name(node: Node | None, source: bytes) -> tuple[tuple[str, ...], bool] | None: + """The class name a type is written with, as parts, and whether a smart pointer was looked through: + `const ns::Foo` -> (("ns", "Foo"), False), `std::unique_ptr` -> (("Foo",), True). None for a type + that cannot name a class (`int`, a function type). + """ + wrapped = False + while node is not None: + kind = node.type + if kind in _CLASS_TYPES: # `struct Foo *p` + node = node.child_by_field_name("name") + continue + template = node + if kind == "qualified_identifier": # `std::unique_ptr` + last = node.child_by_field_name("name") + template = last if last is not None and last.type == "template_type" else node + if template.type == "template_type" and node_text(template.child_by_field_name("name"), source) in _SMART_POINTERS: + args = template.child_by_field_name("arguments") + first = args.named_children[0] if args is not None and args.named_children else None + node = first.child_by_field_name("type") if first is not None else None + wrapped = True + continue + if kind in ("type_identifier", "template_type", "qualified_identifier"): + parts = _name_parts(node, source) + return (tuple(p for p in (*parts[0], parts[1]) if p), wrapped) if parts is not None else None + return None + return None + + +def _template_params(node: Node, source: bytes) -> frozenset[str]: + """The type parameters a `template <...>` introduces.""" + params = node.child_by_field_name("parameters") + names = set() + for param in params.named_children if params is not None else []: + if param.type not in _TYPE_PARAMETER_TYPES: + continue + name = param.child_by_field_name("name") or next((c for c in param.named_children if c.type == "type_identifier"), None) + if name is not None: + names.add(node_text(name, source)) + return frozenset(names) + + +def _typedef_name(declarator: Node | None, source: bytes) -> str | None: + """The name a `typedef` introduces, through `*` and `&`: `typedef Foo *FooRef;` -> `FooRef`.""" + while declarator is not None and declarator.type in ("pointer_declarator", "reference_declarator"): + declarator = declarator.child_by_field_name("declarator") or next(iter(declarator.named_children), None) + return node_text(declarator, source) if declarator is not None and declarator.type == "type_identifier" else None + + +def _bare_name(param: Node, source: bytes) -> tuple[str, ...] | None: + """`x` in `Foo var(x);`, which tree-sitter reads as a parameter of type `x` (the vexing parse).""" + if param.type != "parameter_declaration" or param.child_by_field_name("declarator") is not None: + return None + type_node = param.child_by_field_name("type") + if type_node is None or type_node.type not in ("type_identifier", "qualified_identifier") or len(param.named_children) != 1: + return None + parts = _name_parts(type_node, source) + return tuple(p for p in (*parts[0], parts[1]) if p) if parts is not None else None + + +class _CppAnalyzer: + def __init__(self, sources: dict[str, str]): + self.sources = sources + self.files: dict[str, _CppFile] = {} + self.functions: dict[str, FunctionInfo] = {} + self.file_errors: dict[str, str] = {} + self.file_functions: dict[str, list[str]] = {} + self._definitions: list[_Decl] = [] # in file order + self._declarations: list[_Decl] = [] + self._classes: dict[str, _Class] = {} # qualified name -> its bases and data members + self._namespaces: set[str] = set() # qualified names + self._raw_aliases: list[tuple[str, tuple[tuple[str, ...], bool] | None, tuple[str, ...], _CppFile]] = [] + self._aliases: dict[str, tuple[str | None, bool]] = {} # alias -> (the class it names, through a smart pointer?) + self._by_qualname: dict[str, list[str]] = {} # qualname (no overload suffix) -> function ids, every file + self._methods_by_name: dict[str, list[str]] = {} # bare method name -> function ids + self._defs: dict[str, _Decl] = {} # function id -> its definition + self._declared: dict[str, list[_Decl]] = {} # qualname -> its declarations + self._reached: dict[str, list[str]] = {} + self._reached_sets: dict[str, set[str]] = {} + self._implementations: dict[str, set[str]] = {} # file -> the source files implementing the headers it reaches + self._resolved: dict[tuple, str | None] = {} + + def analyze(self) -> dict: + self._parse_files() + self._place_declarations() + self._link_includes() + self._register_functions() + self._fill_missing_docstrings() + self._resolve_calls() + return self._to_response() + + # -- pass 1: parse everything, collect definitions, declarations, classes and namespaces -- + + def _parse_files(self) -> None: + parser = Parser(_CPP_LANGUAGE) + for rel_path, raw in sorted(self.sources.items()): + self.file_functions.setdefault(rel_path, []) + source = prepare_source(raw) + source_bytes = source.encode("utf-8") + tree = parser.parse(source_bytes) + if tree.root_node.has_error: + self.file_errors[rel_path] = "SyntaxError: C++ source has one or more parse errors" + + module = posixpath.splitext(rel_path)[0] + cfile = _CppFile(rel_path, module, source_bytes, split_lines(source)) + cfile.include_paths = quoted_includes(tree.root_node, source_bytes) + self.files[rel_path] = cfile + self._walk(cfile, tree.root_node) + + def _walk(self, cfile: _CppFile, root: Node) -> None: + """Visits every item of a file, namespace and class bodies included, in source order. A stack stands in + for recursion, so no depth of nesting can exhaust Python's.""" + # the root's children, whatever the root is: a badly broken file's root is an ERROR node + pending: list[tuple[Node, _Scope, Node | None]] = [(child, _Scope(), None) for child in reversed(root.children)] + while pending: + node, scope, span = pending.pop() + pending.extend(reversed(self._visit(cfile, node, scope, span or node))) + + def _visit(self, cfile: _CppFile, node: Node, scope: _Scope, span: Node) -> list[tuple[Node, _Scope, Node | None]]: + """Registers what `node` declares, and returns the nodes inside it still to visit, in source order, each + with its scope and, when it is wrapped (`template <...>`), the node its lines and comment start at.""" + kind = node.type + source = cfile.source + if kind in _CONTAINER_TYPES: + return [(child, scope, None) for child in node.children] + if kind == "function_definition": + self._add_definition(cfile, node, span, scope, friend=False) + elif kind == "template_declaration": + inner = replace(scope, template_params=scope.template_params | _template_params(node, source)) + skipped = ("template_parameter_list", "requires_clause", "comment") + return [(c, inner, span) for c in node.named_children if c.type not in skipped] + elif kind == "namespace_definition": + return self._add_namespace(cfile, node, scope) + elif kind in _CLASS_TYPES: + return self._add_class(cfile, node, scope, None) + elif kind in ("declaration", "field_declaration"): + type_node = node.child_by_field_name("type") + self._add_declarations(cfile, node, span, scope, friend=False) + if scope.cls is not None: + self._add_fields(cfile, node, scope) + if type_node is not None and type_node.type in _CLASS_TYPES: + return self._add_class(cfile, type_node, scope, None) + elif kind == "friend_declaration": + for child in node.named_children: + if child.type == "function_definition": + self._add_definition(cfile, child, span, scope, friend=True) + elif child.type == "declaration": + self._add_declarations(cfile, child, span, scope, friend=True) + elif kind == "type_definition": + type_node = node.child_by_field_name("type") + names = [_typedef_name(d, source) for d in node.children_by_field_name("declarator")] + for name in names: + if name: + self._add_alias(cfile, scope, name, type_node) + if type_node is not None and type_node.type in _CLASS_TYPES: + return self._add_class(cfile, type_node, scope, next((n for n in names if n), None)) + elif kind == "alias_declaration": + name = node_text(node.child_by_field_name("name"), source) + descriptor = node.child_by_field_name("type") + if name and descriptor is not None: + self._add_alias(cfile, scope, name, descriptor.child_by_field_name("type")) + elif kind == "using_declaration" and scope.cls is None: # in a class, `using Base::f;` adds nothing the bases don't + target = next((c for c in node.named_children if c.type in ("identifier", "qualified_identifier")), None) + parts = _name_parts(target, source) + if parts is not None: + path = tuple(p for p in (*parts[0], parts[1]) if p) + is_namespace = any(c.type == "namespace" for c in node.children) + cfile.using.append((scope.namespace, path, is_namespace)) + return [] + + def _add_namespace(self, cfile: _CppFile, node: Node, scope: _Scope) -> list[tuple[Node, _Scope, Node | None]]: + body = node.child_by_field_name("body") + if body is None: + return [] + name_node = node.child_by_field_name("name") + if name_node is None: + inner = replace(scope, local=True) # an anonymous namespace: its names stay in this file + else: + if name_node.type == "nested_namespace_specifier": # `namespace a::b {` + parts = tuple(node_text(c, cfile.source) for c in name_node.named_children if c.type == "namespace_identifier") + else: + parts = (node_text(name_node, cfile.source),) + namespace = scope.namespace + parts + for i in range(1, len(namespace) + 1): + self._namespaces.add("::".join(namespace[:i])) + inner = replace(scope, namespace=namespace) + return [(body, inner, None)] + + def _add_class( + self, cfile: _CppFile, node: Node, scope: _Scope, fallback_name: str | None + ) -> list[tuple[Node, _Scope, Node | None]]: + body = node.child_by_field_name("body") + if body is None: + return [] # a forward declaration, or an elaborated type (`struct Foo *p`) + name_node = node.child_by_field_name("name") + parts = _name_parts(name_node, cfile.source) if name_node is not None else ((), fallback_name or "") + if parts is None or not parts[1]: + return [] # an anonymous class: its methods have no name to be called by + enclosing = scope.cls or _join(*scope.namespace) + qualname = _join(enclosing, *parts[0], parts[1]) + cls = self._classes.setdefault(qualname, _Class()) + lookup = _scopes_of(enclosing) + for clause in node.children: + if clause.type != "base_class_clause": + continue + for base in clause.named_children: + base_parts = _name_parts(base, cfile.source) if base.type != "access_specifier" else None + if base_parts is not None: + cls.bases.append((tuple(p for p in (*base_parts[0], base_parts[1]) if p), lookup, cfile.rel_path)) + return [(body, replace(scope, cls=qualname), None)] + + def _add_fields(self, cfile: _CppFile, node: Node, scope: _Scope) -> None: + """Remembers the declared type of each data member, so `member_.m()` is typed like a local.""" + type_node = node.child_by_field_name("type") + named = _type_name(type_node, cfile.source) + if type_node is None or type_node.type in _OPAQUE_TYPES: + parts: tuple[str, ...] | str | None = _OPAQUE + elif named is None: + parts = None + else: + parts = _OPAQUE if len(named[0]) == 1 and named[0][0] in scope.template_params else named[0] + fields = self._classes[scope.cls].fields + for declarator in node.children_by_field_name("declarator"): + if _function_parts(declarator) is not None: + continue + name_node = declarator_name_node(declarator) + if name_node is not None and name_node.type == "field_identifier": + fields[node_text(name_node, cfile.source)] = (parts, _scopes_of(scope.cls), cfile.rel_path) + + def _add_alias(self, cfile: _CppFile, scope: _Scope, name: str, type_node: Node | None) -> None: + enclosing = scope.cls or _join(*scope.namespace) + self._raw_aliases.append((_join(enclosing, name), _type_name(type_node, cfile.source), _scopes_of(enclosing), cfile)) + + def _read_declaration(self, cfile: _CppFile, declarator: Node | None, scope: _Scope, friend: bool) -> _Decl | None: + parts = _function_parts(declarator) + if parts is None: + return None + name_node, holder = parts + named = _name_parts(name_node, cfile.source) + if named is None or not named[1]: + return None + params = extract_params(holder, cfile.source) + min_args, max_args = _arity(params) + written = tuple(p for p in named[0] if p) + signature = _signature(params, holder, cfile.source) + return _Decl(cfile, scope, written, named[1], friend, params, signature, min_args, max_args) + + def _add_definition(self, cfile: _CppFile, fn_node: Node, span: Node, scope: _Scope, friend: bool) -> None: + if fn_node.child_by_field_name("body") is None: + return # `= default`, `= delete` + decl = self._read_declaration(cfile, fn_node.child_by_field_name("declarator"), scope, friend) + if decl is None: + return # tree-sitter's recovery of something that is not a plain definition + decl.node = fn_node + decl.span = span + decl.local = scope.local or (scope.cls is None and not decl.written and is_static(fn_node, cfile.source)) + self._definitions.append(decl) + + def _add_declarations(self, cfile: _CppFile, node: Node, span: Node, scope: _Scope, friend: bool) -> None: + """Remembers each function a declaration declares: its comment documents a definition elsewhere, and its + default arguments count when calls to that definition are matched by argument count.""" + doc = None + for declarator in node.children_by_field_name("declarator"): + decl = self._read_declaration(cfile, declarator, scope, friend) + if decl is None: + continue + doc = doc or comment_block_above(span, cfile.source, cfile.lines) + decl.doc = doc + self._declarations.append(decl) + + # -- between the passes: owners, names and what each file can see -- + + def _resolve_written(self, written: tuple[str, ...], namespace: tuple[str, ...]) -> str: + """The class or namespace a qualifier written in `namespace` names: the innermost known match, else the + qualifier taken as relative to `namespace`.""" + for i in range(len(namespace), -1, -1): + candidate = "::".join(namespace[:i] + written) + if candidate in self._classes or candidate in self._namespaces: + return candidate + return "::".join(namespace + written) + + def _place_declarations(self) -> None: + for decl in [*self._definitions, *self._declarations]: + scope = decl.scope + if scope.cls is not None and not decl.friend: + decl.owner, decl.is_method = scope.cls, True + elif decl.written: # `void Catalog::add(...)`, `void ns::helper()` + decl.owner = self._resolve_written(decl.written, scope.namespace) + decl.is_method = decl.owner not in self._namespaces + if decl.is_method: + self._classes.setdefault(decl.owner, _Class()) # a class whose body was not loaded + else: + decl.owner, decl.is_method = _join(*scope.namespace), False + # a friend defined in its class is a namespace function, but its body still sees the class + decl.lookup = _scopes_of(scope.cls if decl.friend and scope.cls and not decl.written else decl.owner) + + for cfile in self.files.values(): + for namespace, path, is_namespace in cfile.using: + if is_namespace: + target = self._resolve_written(path, namespace) + if target not in cfile.using_namespaces: + cfile.using_namespaces.append(target) + elif len(path) > 1: + qualified = _join(self._resolve_written(path[:-1], namespace), path[-1]) + cfile.using_names.setdefault(path[-1], []).append(qualified) + + for qualname, named, lookup, cfile in self._raw_aliases: # in file order, so an alias can name an earlier one + if named is None: + self._aliases[qualname] = (None, False) + continue + parts, wrapped = named + target, through_pointer = self._class_entry(parts, lookup, cfile) or (None, False) + self._aliases[qualname] = (target, wrapped or through_pointer) + + def _link_includes(self) -> None: + loaded = set(self.files) + by_suffix = suffix_index(loaded) + direct: dict[str, list[str]] = {} + for rel_path, cfile in self.files.items(): + resolved = (resolve_include(rel_path, path, loaded, by_suffix) for path in cfile.include_paths) + direct[rel_path] = [target for target in resolved if target is not None and target != rel_path] + + stems = {rel_path: posixpath.splitext(posixpath.basename(rel_path)) for rel_path in self.files} + by_stem: dict[str, list[str]] = {} + for rel_path, (stem, ext) in stems.items(): + if ext in _SOURCE_EXTENSIONS: + by_stem.setdefault(stem, []).append(rel_path) + implementing: dict[str, list[str]] = {} + for rel_path, (stem, ext) in stems.items(): + if ext not in _HEADER_EXTENSIONS: + continue + candidates = by_stem.get(stem, []) + beside = [c for c in candidates if posixpath.dirname(c) == posixpath.dirname(rel_path)] + implementing[rel_path] = beside or candidates + + for rel_path in self.files: + reached = reached_files(rel_path, direct) + self._reached[rel_path] = reached + self._reached_sets[rel_path] = set(reached) + self._implementations[rel_path] = { + impl for header in reached for impl in implementing.get(header, []) if impl != rel_path + } + + def _register_functions(self) -> None: + for decl in self._declarations: + self._declared.setdefault(decl.qualname, []).append(decl) + + by_file: dict[str, list[_Decl]] = {} + for decl in self._definitions: + by_file.setdefault(decl.file.rel_path, []).append(decl) + for rel_path, defs in by_file.items(): + signatures: dict[str, set[str]] = {} + for decl in defs: + signatures.setdefault(decl.qualname, set()).add(decl.signature) + taken: dict[str, int] = {} + for decl in defs: + suffix = decl.signature if len(signatures[decl.qualname]) > 1 else "" + func_id = f"{rel_path}::{decl.qualname}{suffix}" + taken[func_id] = taken.get(func_id, 0) + 1 + if taken[func_id] > 1: + func_id += f"#{taken[func_id]}" + for proto in self._declared.get(decl.qualname, []): + if proto.signature == decl.signature: + decl.min_args = min(decl.min_args, proto.min_args) + self._add_function(func_id, decl, suffix) + + def _add_function(self, func_id: str, decl: _Decl, suffix: str) -> None: + cfile = decl.file + start_line = decl.span.start_point[0] + 1 + end_line = decl.node.end_point[0] + 1 + holder = _function_parts(decl.node.child_by_field_name("declarator"))[1] + self.functions[func_id] = FunctionInfo( + id=func_id, + name=decl.name + suffix, + qualname=decl.qualname + suffix, + file=cfile.rel_path, + module=cfile.module, + class_name=decl.owner if decl.is_method else None, + lineno=start_line, + end_lineno=end_line, + params=decl.params, + returns=_return_type(decl.node, holder, cfile.source), + docstring=comment_block_above(decl.span, cfile.source, cfile.lines), + is_async=False, + code_lines=make_code_lines(cfile.lines, start_line, end_line), + ) + self.file_functions[cfile.rel_path].append(func_id) + self._defs[func_id] = decl + self._by_qualname.setdefault(decl.qualname, []).append(func_id) + if decl.is_method: + self._methods_by_name.setdefault(decl.name, []).append(func_id) + + def _fill_missing_docstrings(self) -> None: + for func_id, info in self.functions.items(): + if info.docstring is not None: + continue + decl = self._defs[func_id] + declared = self._declared.get(decl.qualname) + if not declared: + continue + order = {rel_path: i for i, rel_path in enumerate([info.file, *self._reached[info.file]])} + protos = [p for p in declared if p.file.rel_path in order] + if not protos: + continue + protos.sort(key=lambda p: order[p.file.rel_path]) + exact = [p for p in protos if p.signature == decl.signature and p.doc] + if exact: + info.docstring = exact[0].doc + elif len({p.signature for p in protos}) == 1: # not overloaded: the declaration is this definition's + info.docstring = next((p.doc for p in protos if p.doc), None) + + # -- pass 2: resolve calls -- + + def _resolve_calls(self) -> None: + for func_id, info in self.functions.items(): + decl = self._defs[func_id] + fn_node = decl.node + roots = [c for c in fn_node.children if c.type == "field_initializer_list"] + body = fn_node.child_by_field_name("body") + if body is not None: + roots.append(body) + variables, constructed = self._variables(decl, roots) + found: list[tuple[int, str]] = [] + stack = list(reversed(roots)) + while stack: + node = stack.pop() + if node.type in _CALL_SITES: + found.extend(self._call_targets(decl, variables, constructed, node)) + stack.extend(reversed(node.children)) # so calls come out in source order + dedupe_calls(info, found) + decl.node = decl.span = None # the trees are no longer needed + + def _variables(self, decl: _Decl, roots: list[Node]) -> tuple[dict[str, str | None], set[tuple[int, int]]]: + """Every parameter and local variable of a function, lambdas included, with the class its type names + (`_OPAQUE` when the type is not visible, None when it is not a loaded class), plus the `Foo var(x)` + declarations that construct a variable rather than declare a function.""" + source = decl.file.source + variables: dict[str, str | None] = {} + + def declare(name: str, value: str | None) -> None: + variables[name] = _OPAQUE if name in variables and variables[name] != value else value + + def declare_param(param: Node) -> None: + name_node = declarator_name_node(param.child_by_field_name("declarator")) + if name_node is not None and name_node.type == "identifier": + declare(node_text(name_node, source), self._type_of(decl, param.child_by_field_name("type"))) + + holder = _function_parts(decl.node.child_by_field_name("declarator"))[1] + params = holder.child_by_field_name("parameters") if holder is not None else None + for param in params.named_children if params is not None else []: + if param.type in PARAMETER_TYPES: + declare_param(param) + + maybe_constructed: list[tuple[Node, Node | None]] = [] + stack = list(roots) + while stack: + node = stack.pop() + kind = node.type + if kind == "declaration": + type_node = node.child_by_field_name("type") + for declarator in node.children_by_field_name("declarator"): + if declarator.type == "function_declarator": + maybe_constructed.append((declarator, type_node)) + continue + target = declarator + if declarator.type == "init_declarator": + target = declarator.child_by_field_name("declarator") + if target is not None and target.type == "structured_binding_declarator": # `auto [a, b] = ...` + for name in target.named_children: + declare(node_text(name, source), _OPAQUE) + continue + if function_declarator_of(target) is not None: + continue # a prototype inside the body names a function, not a variable + name_node = declarator_name_node(target) + if name_node is not None and name_node.type == "identifier": + declare(node_text(name_node, source), self._type_of(decl, type_node)) + elif kind in PARAMETER_TYPES: # a lambda's or a catch clause's + declare_param(node) + elif kind == "for_range_loop": + name_node = declarator_name_node(node.child_by_field_name("declarator")) + if name_node is not None and name_node.type == "identifier": + declare(node_text(name_node, source), self._type_of(decl, node.child_by_field_name("type"))) + stack.extend(node.named_children) + + # `Foo var(x);` reads as a prototype of a function `var` taking an `x`. Inside a body it is far more + # likely a variable constructed from `x`, and is taken as one unless some "parameter" names a class. + constructed: set[tuple[int, int]] = set() + for declarator, type_node in maybe_constructed: + name_node = declarator.child_by_field_name("declarator") + args = declarator.child_by_field_name("parameters") + names = [_bare_name(c, source) for c in args.named_children if c.type != "comment"] if args is not None else [] + if name_node is None or name_node.type != "identifier" or not names: + continue + if not all(self._is_value(decl, variables, n) for n in names): + continue + declare(node_text(name_node, source), self._type_of(decl, type_node)) + constructed.add((declarator.start_byte, declarator.end_byte)) + return variables, constructed + + def _is_value(self, decl: _Decl, variables: dict[str, str | None], name: tuple[str, ...] | None) -> bool: + """Whether a name in `Foo var(x)` can be a value: a variable, or any name that is not a type.""" + if name is None: + return False + if len(name) == 1 and name[0] in variables: + return True + if len(name) == 1 and name[0] in decl.scope.template_params: + return False + return self._find_class(name, decl, constructing=False) is None + + def _call_targets( + self, decl: _Decl, variables: dict[str, str | None], constructed: set[tuple[int, int]], node: Node + ) -> list[tuple[int, str]]: + """The (line, callee id) of each call `node` makes, for the node kinds in `_CALL_SITES`.""" + kind = node.type + line = node.start_point[0] + 1 + type_node = node.child_by_field_name("type") + target = None + if kind == "call_expression": + argc = _arg_count(node.child_by_field_name("arguments")) + target = self._resolve_call(decl, variables, node.child_by_field_name("function"), argc) + elif kind == "new_expression": + if node.child_by_field_name("declarator") is None: # not `new T[n]` + target = self._construct(decl, type_node, _arg_count(node.child_by_field_name("arguments"))) + elif kind == "compound_literal_expression": # `T{...}` + target = self._construct(decl, type_node, _arg_count(node.child_by_field_name("value"))) + elif kind == "field_initializer": # `: Base(...)` in a constructor + named = [c for c in node.named_children if c.type != "comment"] + parts = _name_parts(named[0], decl.file.source) if len(named) == 2 else None + if parts is not None: + cls = self._find_class(tuple(p for p in (*parts[0], parts[1]) if p), decl, constructing=True) + if cls is not None: + target = self._constructor(decl.file.rel_path, cls, _arg_count(named[1])) + elif kind == "declaration": # `T var(...)`, `T var{...}` + found = [] + for declarator in node.children_by_field_name("declarator"): + argc = None + if declarator.type == "init_declarator": + inner = declarator.child_by_field_name("declarator") + value = declarator.child_by_field_name("value") + initialized = value is not None and value.type in ("argument_list", "initializer_list") + if inner is not None and inner.type == "identifier" and initialized: + argc = _arg_count(value) + elif (declarator.start_byte, declarator.end_byte) in constructed: + argc = _arg_count(declarator.child_by_field_name("parameters")) + if argc is not None: + found_target = self._construct(decl, type_node, argc) + if found_target: + found.append((declarator.start_point[0] + 1, found_target)) + return found + return [(line, target)] if target else [] + + def _resolve_call(self, decl: _Decl, variables: dict[str, str | None], func: Node | None, argc: int) -> str | None: + if func is None: + return None + source = decl.file.source + kind = func.type + if kind in ("identifier", "template_function"): # `f(x)`, `f(x)` + parts = _name_parts(func, source) + if parts is None or parts[0] or parts[1] in variables: + return None # a call through a parameter or a local (a function pointer, a lambda) is not linked + return self._resolve_unqualified(decl, parts[1], argc) + if kind == "qualified_identifier": # `Catalog::make()`, `ns::f()`, `::f()` + parts = _name_parts(func, source) + if parts is None: + return None + written, name = parts + return self._resolve_qualified(decl, tuple(p for p in written if p), name, argc, written[:1] == ("",)) + if kind == "field_expression": # `obj.m()`, `obj->m()`, `this->m()` + parts = _name_parts(func.child_by_field_name("field"), source) + if parts is None: + return None + written, name = parts + written = tuple(p for p in written if p) + if written: # `obj.Base::m()` + target = self._find_scope(written, decl) + found = self._members(target, name) if target in self._classes else [] + return self._pick_member(decl.file.rel_path, found, argc) + cls = self._receiver_class(decl, variables, func.child_by_field_name("argument")) + return self._resolve_method(decl.file.rel_path, cls, name, argc) + return None # `(*fp)(x)`, `tbl[i](x)`, `make()(x)`: calls through an expression are not linked + + def _receiver_class(self, decl: _Decl, variables: dict[str, str | None], expr: Node | None) -> str | None: + """The class of the object a method is called on: `this`, a typed variable, a typed data member reached + through either (`this->items_`, `order.item`), or a cast's target type.""" + source = decl.file.source + members: list[str] = [] # `a.b.c` -> ["c", "b"], read back from `a` outwards + while expr is not None: + if expr.type in ("parenthesized_expression", "pointer_expression"): # `(*this)`, `*it` + expr = expr.child_by_field_name("argument") or next(iter(expr.named_children), None) + elif expr.type == "field_expression": + member = expr.child_by_field_name("field") + if member is None or member.type != "field_identifier": + return _OPAQUE + members.append(node_text(member, source)) + expr = expr.child_by_field_name("argument") + else: + break + cls = _OPAQUE + if expr is None: + return _OPAQUE + if expr.type == "this": + cls = decl.owner if decl.is_method else _OPAQUE + elif expr.type == "identifier": + name = node_text(expr, source) + if name in variables: + cls = variables[name] + elif decl.is_method: + cls = self._field_class(decl.owner, name) # a data member, or a global (`_OPAQUE`) + elif expr.type == "call_expression": # `static_cast(p)->m()` + func = expr.child_by_field_name("function") + is_template = func is not None and func.type == "template_function" + if is_template and node_text(func.child_by_field_name("name"), source) in _CASTS: + args = func.child_by_field_name("arguments") + first = args.named_children[0] if args is not None and args.named_children else None + if first is not None and first.type == "type_descriptor": + cls = self._type_of(decl, first.child_by_field_name("type")) + for name in reversed(members): + if cls is None or cls == _OPAQUE: + return _OPAQUE # a member of something untyped, or of a type that was not loaded + cls = self._field_class(cls, name) + return cls + + # -- lookups, each cached -- + + def _cached(self, key: tuple, compute) -> str | None: + if key not in self._resolved: + self._resolved[key] = compute() + return self._resolved[key] + + def _resolve_unqualified(self, decl: _Decl, name: str, argc: int) -> str | None: + if name in decl.scope.template_params: + return None # `T(x)`: a conversion to a template parameter's type + key = ("unqualified", decl.file.rel_path, decl.lookup, name, argc) + return self._cached(key, lambda: self._lookup_unqualified(decl, name, argc)) + + def _lookup_unqualified(self, decl: _Decl, name: str, argc: int) -> str | None: + cfile = decl.file + rel_path = cfile.rel_path + # (1) the enclosing classes and their bases, then the enclosing namespaces, innermost first + for scope in decl.lookup[:-1]: + if scope in self._classes: + found = self._members(scope, name) + if found: + return self._pick_member(rel_path, found, argc) + if any(_join(owner, name) in self._declared for owner in self._chain(scope)): + return self._lookup_method(rel_path, _OPAQUE, name, argc) # a pure virtual: as for `this->m()` + else: + found = self._visible(rel_path, self._by_qualname.get(f"{scope}::{name}", [])) + if found: + return self._pick(found, argc) + # (2) what `using namespace ns;` and `using ns::f;` bring in + candidates = [fid for ns in cfile.using_namespaces for fid in self._by_qualname.get(_join(ns, name), [])] + candidates += [fid for qualified in cfile.using_names.get(name, []) for fid in self._by_qualname.get(qualified, [])] + found = self._visible(rel_path, list(dict.fromkeys(candidates))) + if found: + return self._pick(found, argc) + # (3) the global namespace, the way C sees it + found = self._visible(rel_path, self._by_qualname.get(name, [])) + if found: + return self._pick(found, argc) + # (4) `Foo(x)`: a class's constructor + cls = self._find_class((name,), decl, constructing=True) + return self._constructor(rel_path, cls, argc) if cls is not None else None + + def _resolve_qualified(self, decl: _Decl, written: tuple[str, ...], name: str, argc: int, is_global: bool) -> str | None: + rel_path = decl.file.rel_path + key = ("qualified", rel_path, decl.lookup, written, name, argc, is_global) + return self._cached(key, lambda: self._lookup_qualified(decl, written, name, argc, is_global)) + + def _lookup_qualified(self, decl: _Decl, written: tuple[str, ...], name: str, argc: int, is_global: bool) -> str | None: + rel_path = decl.file.rel_path + if not written: # `::f()` + found = self._visible(rel_path, self._by_qualname.get(name, [])) + return self._pick(found, argc) if found else None + target = self._find_scope(written, decl, ("",) if is_global else None) + if target is None: + return None # `std::sort()`: a scope that was not loaded + if target in self._classes: + found = self._members(target, name) + if found: + return self._pick_member(rel_path, found, argc) + else: + found = self._visible(rel_path, self._by_qualname.get(f"{target}::{name}", [])) + if found: + return self._pick(found, argc) + nested = _join(target, name) # `ns::Foo(x)`: a constructor + return self._constructor(rel_path, nested, argc) if nested in self._classes else None + + def _resolve_method(self, rel_path: str, cls: str | None, name: str, argc: int) -> str | None: + """A call on a receiver of class `cls` (`_OPAQUE` when its type is not visible).""" + if cls is None: + return None # a visible type that is not a loaded class: `std::string`, `int` + return self._cached(("method", rel_path, cls, name, argc), lambda: self._lookup_method(rel_path, cls, name, argc)) + + def _lookup_method(self, rel_path: str, cls: str, name: str, argc: int) -> str | None: + found = self._members(cls, name) if cls != _OPAQUE else [] + if found: + return self._pick_member(rel_path, found, argc) + # the type is not visible, or its classes define no such method: the one loaded method of that name + methods = self._methods_by_name.get(name, []) + return methods[0] if len(methods) == 1 else None + + def _construct(self, decl: _Decl, type_node: Node | None, argc: int) -> str | None: + cls = self._type_of(decl, type_node, constructing=True) + if cls is None or cls == _OPAQUE: + return None + return self._constructor(decl.file.rel_path, cls, argc) + + def _constructor(self, rel_path: str, cls: str, argc: int) -> str | None: + found = self._by_qualname.get(_join(cls, cls.rsplit("::", 1)[-1]), []) + return self._pick_member(rel_path, found, argc) + + def _type_of(self, decl: _Decl, type_node: Node | None, constructing: bool = False) -> str | None: + """The loaded class a declared type names, `_OPAQUE` when the type is not visible, None otherwise. + + A smart pointer (`std::unique_ptr`) names its pointee, except when the question is which + constructor a declaration calls (`constructing`). + """ + if type_node is None or type_node.type in _OPAQUE_TYPES: + return _OPAQUE + named = _type_name(type_node, decl.file.source) + if named is None: + return None + parts, wrapped = named + if wrapped and constructing: + return None + if len(parts) == 1 and parts[0] in decl.scope.template_params: + return _OPAQUE + return self._find_class(parts, decl, constructing) + + def _find_class(self, parts: tuple[str, ...], decl: _Decl, constructing: bool) -> str | None: + key = ("class", decl.file.rel_path, decl.lookup, parts, constructing) + return self._cached(key, lambda: self._lookup_class(parts, decl.lookup, decl.file, constructing)) + + def _lookup_class(self, parts: tuple[str, ...], lookup: tuple[str, ...], cfile: _CppFile, constructing: bool) -> str | None: + target, wrapped = self._class_entry(parts, lookup, cfile) or (None, False) + return None if wrapped and constructing else target + + def _class_entry(self, parts: tuple[str, ...], lookup: tuple[str, ...], cfile: _CppFile) -> tuple[str | None, bool] | None: + """The class a type name finds from `lookup` outwards, and whether it went through a smart-pointer alias; + None when the name finds nothing.""" + for scope in (*lookup, *cfile.using_namespaces): + candidate = _join(scope, *parts) + if candidate in self._classes: + return candidate, False + if candidate in self._aliases: + return self._aliases[candidate] + return None + + def _field_class(self, cls: str, name: str) -> str | None: + """What a data member's declared type names, like `_type_of`; `_OPAQUE` for a member that was not loaded.""" + return self._cached(("field", cls, name), lambda: self._lookup_field(cls, name)) + + def _lookup_field(self, cls: str, name: str) -> str | None: + for owner in self._chain(cls): + info = self._classes.get(owner) + if info is not None and name in info.fields: + parts, lookup, rel_path = info.fields[name] + if parts is None or parts == _OPAQUE: + return parts + return self._lookup_class(parts, lookup, self.files[rel_path], constructing=False) + return _OPAQUE + + def _find_scope(self, written: tuple[str, ...], decl: _Decl, lookup: tuple[str, ...] | None = None) -> str | None: + """The class or namespace a qualifier names, looked up from the enclosing scopes outwards.""" + for scope in (*(decl.lookup if lookup is None else lookup), *decl.file.using_namespaces): + candidate = _join(scope, *written) + if candidate in self._classes or candidate in self._namespaces: + return candidate + target, wrapped = self._aliases.get(candidate, (None, True)) + if target is not None and not wrapped: + return target + return None + + def _chain(self, cls: str) -> list[str]: + """A class and its loaded base classes, depth first, in declaration order.""" + info = self._classes.get(cls) + if info is None: + return [cls] + if info.chain is None: + chain: list[str] = [] + seen: set[str] = set() + pending = [cls] + while pending: + current = pending.pop() + if current in seen: + continue # a diamond, or an inheritance cycle in broken code + seen.add(current) + chain.append(current) + current_info = self._classes.get(current) + bases = [ + self._lookup_class(parts, lookup, self.files[rel_path], constructing=False) + for parts, lookup, rel_path in (current_info.bases if current_info else []) + ] + pending.extend(reversed([base for base in bases if base is not None])) + info.chain = chain + return info.chain + + def _members(self, cls: str, name: str) -> list[str]: + for owner in self._chain(cls): + found = self._by_qualname.get(f"{owner}::{name}") + if found: + return found + return [] + + # -- choosing among candidates -- + + def _visible(self, rel_path: str, candidates: list[str]) -> list[str]: + """The candidates a file sees first, the way C resolves a name: the same file, then the files it reaches + through includes and the files implementing those, then every definition visible from anywhere.""" + if not candidates: + return [] + same = [fid for fid in candidates if self._defs[fid].file.rel_path == rel_path] + if same: + return same + reached = self._reached_sets[rel_path] + implementations = self._implementations[rel_path] + near = [] + for fid in candidates: + decl = self._defs[fid] + if decl.file.rel_path in reached or (decl.file.rel_path in implementations and not decl.local): + near.append(fid) + if near: + return near + return [fid for fid in candidates if not self._defs[fid].local] + + def _pick_member(self, rel_path: str, candidates: list[str], argc: int) -> str | None: + """One of a class's definitions of a name, as `_pick` chooses, among those in this file, the files it + reaches and the files implementing those when there are any (so two unrelated classes of one name, each + in its own anonymous namespace, stay apart), else among all those visible from anywhere.""" + reached = self._reached_sets[rel_path] + implementations = self._implementations[rel_path] + near = [] + for fid in candidates: + path = self._defs[fid].file.rel_path + if path == rel_path or path in reached or path in implementations: + near.append(fid) + return self._pick(near or [fid for fid in candidates if not self._defs[fid].local], argc) + + def _pick(self, candidates: list[str], argc: int) -> str | None: + """The one candidate, or the one the argument count leaves; None when that is not exactly one.""" + if len(candidates) == 1: + return candidates[0] + fitting = [fid for fid in candidates if self._defs[fid].min_args <= argc <= self._defs[fid].max_args] + return fitting[0] if len(fitting) == 1 else None + + # -- output -- + + def _to_response(self) -> dict: + edges = build_edges(self.functions) + files = [ + {"path": rel_path, "functions": ids, "error": self.file_errors.get(rel_path)} + for rel_path, ids in sorted(self.file_functions.items()) + ] + return { + "files": files, + "functions": {fid: info.to_dict() for fid, info in self.functions.items()}, + "edges": edges, + } + + +class CppLanguage(LanguagePlugin): + id = "cpp" + label = "C++" + extensions = frozenset({".cc", ".cpp", ".cxx", ".hpp", ".hh", ".hxx"}) + conditional_extensions = frozenset({".h"}) + + def claims(self, ext: str, paths: Collection[str]) -> bool: + """`.h` is C++ in a load holding any C++-only file, and stays C in a C-only one.""" + return ext in self.conditional_extensions and any(os.path.splitext(p)[1] in self.extensions for p in paths) + + def analyze(self, sources: dict[str, str]) -> dict: + return _CppAnalyzer(sources).analyze() diff --git a/backend/requirements.txt b/backend/requirements.txt index 586678e..dbb341a 100644 --- a/backend/requirements.txt +++ b/backend/requirements.txt @@ -4,3 +4,4 @@ tree-sitter>=0.23 tree-sitter-rust>=0.23 tree-sitter-typescript>=0.23 tree-sitter-c>=0.23 +tree-sitter-cpp>=0.23 From 81165220c9e2662df1ae6c5e9d6501cc119ed326 Mon Sep 17 00:00:00 2001 From: MCR-3 Date: Sun, 11 Oct 2026 10:46:03 +0200 Subject: [PATCH 4/6] chore: add sample_cpp_project fixture A small catalogue app in the same spirit as the other sample projects, written to exercise what the C++ plugin resolves: a namespace, a class with in-class and out-of-class methods, a constructor, destructor and operator, overloads, function and class templates, a lambda, a virtual call through a base reference, an `auto` receiver, and a `.h` header that is C++ because `.cpp` files sit beside it. --- sample_cpp_project/catalog.cpp | 24 ++++++++++++++++ sample_cpp_project/catalog.hpp | 30 ++++++++++++++++++++ sample_cpp_project/exporter.cpp | 23 +++++++++++++++ sample_cpp_project/exporter.hpp | 32 +++++++++++++++++++++ sample_cpp_project/main.cpp | 47 +++++++++++++++++++++++++++++++ sample_cpp_project/models.cpp | 20 +++++++++++++ sample_cpp_project/models.h | 30 ++++++++++++++++++++ sample_cpp_project/processing.cpp | 34 ++++++++++++++++++++++ sample_cpp_project/processing.hpp | 39 +++++++++++++++++++++++++ sample_cpp_project/storage.cpp | 30 ++++++++++++++++++++ sample_cpp_project/storage.hpp | 25 ++++++++++++++++ 11 files changed, 334 insertions(+) create mode 100644 sample_cpp_project/catalog.cpp create mode 100644 sample_cpp_project/catalog.hpp create mode 100644 sample_cpp_project/exporter.cpp create mode 100644 sample_cpp_project/exporter.hpp create mode 100644 sample_cpp_project/main.cpp create mode 100644 sample_cpp_project/models.cpp create mode 100644 sample_cpp_project/models.h create mode 100644 sample_cpp_project/processing.cpp create mode 100644 sample_cpp_project/processing.hpp create mode 100644 sample_cpp_project/storage.cpp create mode 100644 sample_cpp_project/storage.hpp diff --git a/sample_cpp_project/catalog.cpp b/sample_cpp_project/catalog.cpp new file mode 100644 index 0000000..5e3008a --- /dev/null +++ b/sample_cpp_project/catalog.cpp @@ -0,0 +1,24 @@ +#include "catalog.hpp" + +namespace inventory { + +void Catalog::add(const Item &item, int quantity) { + for (int i = 0; i < quantity; ++i) { + items_.push_back(item); + } +} + +void Catalog::add(const std::string &name, double weight) { + add(Item(name, weight)); +} + +const Item *Catalog::find(const std::string &name) const { + for (const Item &item : items_) { + if (item.name() == name) { + return &item; + } + } + return nullptr; +} + +} // namespace inventory diff --git a/sample_cpp_project/catalog.hpp b/sample_cpp_project/catalog.hpp new file mode 100644 index 0000000..f8f1a1b --- /dev/null +++ b/sample_cpp_project/catalog.hpp @@ -0,0 +1,30 @@ +#pragma once + +#include +#include +#include + +#include "models.h" + +namespace inventory { + +// Every item in stock, in the order it was added. +class Catalog { +public: + // Adds `quantity` copies of an item. + void add(const Item &item, int quantity = 1); + + // Adds an item made from its name and weight. + void add(const std::string &name, double weight); + + // The first item with that name, or nullptr. + const Item *find(const std::string &name) const; + + const std::vector &items() const { return items_; } + std::size_t size() const { return items_.size(); } + +private: + std::vector items_; +}; + +} // namespace inventory diff --git a/sample_cpp_project/exporter.cpp b/sample_cpp_project/exporter.cpp new file mode 100644 index 0000000..3a1145f --- /dev/null +++ b/sample_cpp_project/exporter.cpp @@ -0,0 +1,23 @@ +#include "exporter.hpp" + +namespace inventory { + +void Exporter::write(const Item &item) { + out_ << item.describe() << '\n'; +} + +void Exporter::write_all(const std::vector &items) { + for (const Item &item : items) { + write(item); + } +} + +void CsvExporter::header() { + out_ << "name,weight\n"; +} + +void CsvExporter::write(const Item &item) { + out_ << item.name() << ',' << item.weight() << '\n'; +} + +} // namespace inventory diff --git a/sample_cpp_project/exporter.hpp b/sample_cpp_project/exporter.hpp new file mode 100644 index 0000000..85b7d25 --- /dev/null +++ b/sample_cpp_project/exporter.hpp @@ -0,0 +1,32 @@ +#pragma once + +#include +#include + +#include "models.h" + +namespace inventory { + +// Writes items to a stream, one plain line each. +class Exporter { +public: + explicit Exporter(std::ostream &out) : out_(out) {} + virtual ~Exporter() = default; + + virtual void write(const Item &item); + void write_all(const std::vector &items); + +protected: + std::ostream &out_; +}; + +// Writes items as comma-separated values. +class CsvExporter : public Exporter { +public: + explicit CsvExporter(std::ostream &out) : Exporter(out) {} + + void header(); + void write(const Item &item) override; +}; + +} // namespace inventory diff --git a/sample_cpp_project/main.cpp b/sample_cpp_project/main.cpp new file mode 100644 index 0000000..7f461b0 --- /dev/null +++ b/sample_cpp_project/main.cpp @@ -0,0 +1,47 @@ +#include +#include + +#include "catalog.hpp" +#include "exporter.hpp" +#include "processing.hpp" +#include "storage.hpp" + +using namespace inventory; + +// Sends every item through an exporter. `write` is virtual: the call is wired +// to Exporter::write, the declared class's own method, not to an override. +static void export_catalog(Exporter &exporter, const Catalog &catalog) { + for (const Item &item : catalog.items()) { + exporter.write(item); + } +} + +// Entry point of the sample: stock a catalog, weigh it, export it and save it. +int main() { + Catalog catalog; + catalog.add("alpha", 3.0); // both overloads take two arguments: not wired + catalog.add(Item("beta", 5.0)); // only add(const Item &, int) takes one + catalog.add(Item("gamma", 0.5)); + + auto heaviest = catalog.find("beta"); // auto: wired because one method is named describe + if (heaviest != nullptr) { + std::cout << heaviest->describe() << '\n'; + } + + std::size_t shown = processing::cap(catalog.size(), 10); + std::cout << "showing " << shown << " of " << catalog.size() << " items\n"; + + processing::Tally heavy(0); // Tally, deduced from the argument + for (const Item &item : processing::heavier_than(catalog, 1.0)) { + heavy.add(1); + std::cout << "heavy: " << item.describe() << '\n'; + } + std::cout << heavy.total() << " heavy items, " << processing::total_weight(catalog) << " kg in all\n"; + + Exporter plain(std::cout); + export_catalog(plain, catalog); + + Store store("inventory.csv"); + store.save(catalog); + return 0; +} diff --git a/sample_cpp_project/models.cpp b/sample_cpp_project/models.cpp new file mode 100644 index 0000000..765eec3 --- /dev/null +++ b/sample_cpp_project/models.cpp @@ -0,0 +1,20 @@ +#include "models.h" + +#include +#include + +namespace inventory { + +Item::Item(std::string name, double weight) : name_(std::move(name)), weight_(weight) {} + +std::string Item::describe() const { + std::ostringstream out; + out << name() << " (" << weight() << " kg)"; + return out.str(); +} + +bool Item::operator<(const Item &other) const { + return weight() < other.weight(); +} + +} // namespace inventory diff --git a/sample_cpp_project/models.h b/sample_cpp_project/models.h new file mode 100644 index 0000000..dfa9594 --- /dev/null +++ b/sample_cpp_project/models.h @@ -0,0 +1,30 @@ +#ifndef INVENTORY_MODELS_H +#define INVENTORY_MODELS_H + +#include + +namespace inventory { + +// A named thing kept in stock. +class Item { +public: + /* Builds an item; the weight is in kilograms. */ + Item(std::string name, double weight); + + const std::string &name() const { return name_; } + double weight() const { return weight_; } + + /// Human-readable label, e.g. "alpha (3 kg)". + std::string describe() const; + + // Items are ordered by weight, lightest first. + bool operator<(const Item &other) const; + +private: + std::string name_; + double weight_; +}; + +} // namespace inventory + +#endif diff --git a/sample_cpp_project/processing.cpp b/sample_cpp_project/processing.cpp new file mode 100644 index 0000000..f5997f6 --- /dev/null +++ b/sample_cpp_project/processing.cpp @@ -0,0 +1,34 @@ +#include "processing.hpp" + +namespace inventory::processing { + +namespace { + +bool is_heavy(const Item &item, double limit) { + return item.weight() > limit; +} + +} // namespace + +double total_weight(const Catalog &catalog) { + Tally tally(0.0); + for (const Item &item : catalog.items()) { + tally.add(item.weight()); + } + return tally.total(); +} + +std::vector heavier_than(const Catalog &catalog, double limit) { + std::vector found; + auto keep = [&](const Item &item) { + if (is_heavy(item, limit)) { + found.push_back(item); + } + }; + for (const Item &item : catalog.items()) { + keep(item); + } + return found; +} + +} // namespace inventory::processing diff --git a/sample_cpp_project/processing.hpp b/sample_cpp_project/processing.hpp new file mode 100644 index 0000000..b670943 --- /dev/null +++ b/sample_cpp_project/processing.hpp @@ -0,0 +1,39 @@ +#pragma once + +#include + +#include "catalog.hpp" + +namespace inventory::processing { + +// The value, or `limit` when the value is above it. +template +T cap(T value, T limit) { + return limit < value ? limit : value; +} + +// A running total of any numeric type; each step is capped at 1000. +template +class Tally { +public: + explicit Tally(T start) : total_(start) {} + + void add(T value) { total_ += cap(value, T(1000)); } + T total() const; + +private: + T total_; +}; + +template +T Tally::total() const { + return total_; +} + +// Sum of all the weights in a catalog. +double total_weight(const Catalog &catalog); + +// The items heavier than `limit`, in catalog order. +std::vector heavier_than(const Catalog &catalog, double limit); + +} // namespace inventory::processing diff --git a/sample_cpp_project/storage.cpp b/sample_cpp_project/storage.cpp new file mode 100644 index 0000000..d6e2bae --- /dev/null +++ b/sample_cpp_project/storage.cpp @@ -0,0 +1,30 @@ +#include "storage.hpp" + +#include + +#include "exporter.hpp" + +namespace inventory { + +Store::Store(const std::string &path) : file_(path) { + log("opened"); +} + +Store::~Store() { + file_.flush(); + log("closed"); +} + +void Store::save(const Catalog &catalog) { + CsvExporter csv(file_); + csv.header(); + csv.write_all(catalog.items()); + saved_ += static_cast(catalog.size()); + log("saved"); +} + +void Store::log(const char *event) const { + std::clog << "store " << event << " (" << saved_ << " items)\n"; +} + +} // namespace inventory diff --git a/sample_cpp_project/storage.hpp b/sample_cpp_project/storage.hpp new file mode 100644 index 0000000..aa16512 --- /dev/null +++ b/sample_cpp_project/storage.hpp @@ -0,0 +1,25 @@ +#pragma once + +#include +#include + +#include "catalog.hpp" + +namespace inventory { + +// Saves catalogs to a CSV file, which stays open as long as the store does. +class Store { +public: + explicit Store(const std::string &path); + ~Store(); + + void save(const Catalog &catalog); + +private: + void log(const char *event) const; + + std::ofstream file_; + int saved_ = 0; +}; + +} // namespace inventory From 41b2a6965b8f8cd453afcaa66d3e34abac8aae36 Mon Sep 17 00:00:00 2001 From: MCR-3 Date: Sun, 11 Oct 2026 10:46:03 +0200 Subject: [PATCH 5/6] feat(frontend): add C++ to the language registry and highlighting Registers the `cpp` language with its extensions, a badge color that keeps the dark monogram text above 4.5:1 contrast, and the Prism `cpp` grammar, and names C++ in the empty-state hints. `.h` stays on the C entry: the backend decides per project which plugin reads a header, and the frontend only displays the language each file carries. --- frontend/src/components/FunctionNode.tsx | 1 + frontend/src/components/GraphCanvas.tsx | 2 +- frontend/src/components/Sidebar.tsx | 2 +- frontend/src/languages.ts | 10 ++++++++++ 4 files changed, 13 insertions(+), 2 deletions(-) diff --git a/frontend/src/components/FunctionNode.tsx b/frontend/src/components/FunctionNode.tsx index 939009e..c8351d5 100644 --- a/frontend/src/components/FunctionNode.tsx +++ b/frontend/src/components/FunctionNode.tsx @@ -4,6 +4,7 @@ import Prism from "prismjs"; import "prismjs/components/prism-python"; import "prismjs/components/prism-rust"; import "prismjs/components/prism-c"; +import "prismjs/components/prism-cpp"; import "prismjs/components/prism-typescript"; import "prismjs/components/prism-jsx"; import "prismjs/components/prism-tsx"; diff --git a/frontend/src/components/GraphCanvas.tsx b/frontend/src/components/GraphCanvas.tsx index 55d7ec6..47f10a7 100644 --- a/frontend/src/components/GraphCanvas.tsx +++ b/frontend/src/components/GraphCanvas.tsx @@ -348,7 +348,7 @@ export function GraphCanvas() {
⬡
Function Viewer
-
Load a Python, Rust, TypeScript, JavaScript or C file or folder from the sidebar to draw its call graph.
+
Load a Python, Rust, TypeScript, JavaScript, C or C++ file or folder from the sidebar to draw its call graph.
)} {error &&
{error}
} {!graph && !error && ( -
Pick a Python, Rust, TypeScript, JavaScript or C file or a folder from your computer, every function inside is analyzed and its calls to other loaded functions become wires.
+
Pick a Python, Rust, TypeScript, JavaScript, C or C++ file or a folder from your computer, every function inside is analyzed and its calls to other loaded functions become wires.
)} diff --git a/frontend/src/languages.ts b/frontend/src/languages.ts index ff721d6..cfe1cba 100644 --- a/frontend/src/languages.ts +++ b/frontend/src/languages.ts @@ -16,6 +16,16 @@ export const LANGUAGES: LanguageDef[] = [ { id: "rust", label: "Rust", extensions: [".rs"], color: "#dea584", mono: "RS" }, // A C definition always states its return type, so there is no "unannotated" case to show as None. { id: "c", label: "C", extensions: [".c", ".h"], color: "#a8b9cc", mono: "C", unannotatedReturn: null }, + // `.h` stays on C as the fallback: the backend makes a header C++ only when the same root holds C++ + // files, and the frontend reads the language off each file and function, never off its extension. + { + id: "cpp", + label: "C++", + extensions: [".cc", ".cpp", ".cxx", ".hpp", ".hh", ".hxx"], + color: "#659ad2", + mono: "C++", + unannotatedReturn: null, + }, // The superset grammars: they also cover JSX/TSX markup, and highlight plain code the same. // A missing return annotation there means "not stated", not "returns nothing". { From 633ea7bdc2c340256885ea7566db9dd66ba38860 Mon Sep 17 00:00:00 2001 From: MCR-3 Date: Sun, 11 Oct 2026 10:46:04 +0200 Subject: [PATCH 6/6] docs: document C++ support Adds C++ to the supported-languages table, the sample projects and the backend tour, with the plugin's limits, and the C++ fixture to the analyzer regression check. Records the `.h` routing rule in CLAUDE.md and the C/C++ separation in the glossary, since neither is visible from reading a single plugin. Closes #34 --- CLAUDE.md | 3 ++- CONTEXT.md | 2 +- README.md | 11 +++++++---- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8c75eea..1fcdc3f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,7 +42,7 @@ There is **no test suite**. Verify by hand: - Frontend: `docker compose exec frontend npm run build` and `docker compose exec frontend npm run lint` (or run them in `frontend/` without Docker). - Backend: with `docker compose up` running, `GET localhost:8000/api/health`. -- Analyzer or language-plugin changes: `docker compose exec backend python -m backend.analyzer ` on `sample_project`, `sample_rust_project`, `sample_typescript_project` and `sample_c_project` before and after, and compare function and edge counts. An unexplained drop in edges is a regression. +- Analyzer or language-plugin changes: `docker compose exec backend python -m backend.analyzer ` on `sample_project`, `sample_rust_project`, `sample_typescript_project`, `sample_c_project` and `sample_cpp_project` before and after, and compare function and edge counts. An unexplained drop in edges is a regression. CI (`.github/workflows/pr-checks.yml`) only runs the frontend build and the backend health check. It does not lint and does not exercise the analyzer, so green CI says little about analysis correctness. @@ -54,6 +54,7 @@ CI (`.github/workflows/pr-checks.yml`) only runs the frontend build and the back - **The theme is applied in two places.** The inline script in `frontend/index.html` sets `data-theme` before first paint, and `frontend/src/theme.ts` owns it afterwards. They share the storage key and the resolution rules; keep them in sync. Colors belong in the tokens at the top of `index.css`, never as literals (the function card header and the language badge text are the deliberately theme-independent surfaces). - **Paths must be relative to the picked folder's contents**, with the folder's own name stripped (`localFiles.ts`). Module-name derivation and import resolution in the plugins depend on it. - **Vocabulary lives in `CONTEXT.md`; use its terms.** The code hasn't caught up on two of them: **File mode** is still `"folder"` in the code (`OrgMode`, `FolderFrame`, `layoutFolderGraph`), and **Trace up / Trace down** is still `showFlow`. Don't rename these as a drive-by; use the glossary term in prose and the code name in code. +- **`.h` is C or C++ per load, not per file.** The C++ plugin's `claims()` takes every `.h` when the picked root holds any C++-only extension (`.cc`, `.cpp`, `.cxx`, `.hpp`, `.hh`, `.hxx`), so the same header is C in one project and C++ in another, and one load's headers never split between the two. - Function and file ids are namespaced by file path so languages can't collide when merged. - Only calls between functions that were actually loaded are resolved. Calls inside Rust macro invocations are invisible. - CORS is `*` on purpose: the GitHub Pages frontend calls the Render API cross-origin. diff --git a/CONTEXT.md b/CONTEXT.md index fd2f4f8..1a3e5af 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -25,7 +25,7 @@ _Avoid_: Start function, root function What a source file is written in, as shown by its badge, its Explorer icon and its syntax highlighting. A file has exactly one Language. **Language plugin**: -The support for one programming language, or for a family of closely related ones whose files import each other (TypeScript and JavaScript share one): the piece that knows how to read those languages' functions and their calls. One plugin may read several Languages; each file keeps its own. +The support for one programming language, or for a family of closely related ones whose files import each other (TypeScript and JavaScript share one): the piece that knows how to read those languages' functions and their calls. One plugin may read several Languages; each file keeps its own. C and C++ are separate plugins, so no Call edge joins a C file to a C++ one (a `.h` file goes to whichever of the two reads its Picked root). _Avoid_: Parser ### Roots diff --git a/README.md b/README.md index 7b5284d..3401aa0 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,8 @@ The goal is to make the flow of a codebase visible instead of jumping between fi | Rust | `.rs` | | TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | | JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | -| C | `.c`, `.h` | +| C | `.c`, `.h` (unless the folder also holds C++ files) | +| C++ | `.cc`, `.cpp`, `.cxx`, `.hpp`, `.hh`, `.hxx`, plus `.h` when the folder also holds C++ files | More languages can be added without touching the frontend - see [Backend](#backend) below. @@ -46,7 +47,7 @@ npm install npm run dev ``` -Open http://localhost:5173 and load a folder or file from the sidebar. Try `sample_project` (Python), `sample_rust_project` (Rust), `sample_typescript_project` (TypeScript and JavaScript) or `sample_c_project` (C) for a quick demo. +Open http://localhost:5173 and load a folder or file from the sidebar. Try `sample_project` (Python), `sample_rust_project` (Rust), `sample_typescript_project` (TypeScript and JavaScript), `sample_c_project` (C) or `sample_cpp_project` (C++) for a quick demo. ## Codebase @@ -57,16 +58,18 @@ sample_project/ Python demo fixture used for manual testing sample_rust_project/ Rust demo fixture used for manual testing sample_typescript_project/ TypeScript + JavaScript demo fixture used for manual testing sample_c_project/ C demo fixture used for manual testing +sample_cpp_project/ C++ demo fixture used for manual testing ``` ### Backend -- `analyzer.py`: the dispatcher. Groups the files it's given by extension, hands each slice to its language plugin, and merges the results into one graph. Function and file ids are namespaced by path, so merging across languages can't collide. +- `analyzer.py`: the dispatcher. Groups the files it's given by extension, hands each slice to its language plugin, and merges the results into one graph. An extension normally belongs to one plugin, but a plugin may claim one conditionally per load (`conditional_extensions` and `claims()` in `languages/base.py`); that is how `.h` goes to C or C++. Function and file ids are namespaced by path, so merging across languages can't collide. - `languages/`: one module per language, each implementing the same `LanguagePlugin` contract (`languages/base.py`) - parse every file, extract each function's signature/docstring/source lines, and resolve which loaded functions it calls (direct calls, `module.func()`, `self.method()`, constructors/associated functions). Only calls between functions that were actually loaded get resolved. Adding a language means adding one new module here and registering it in `languages/__init__.py`; nothing else changes. - `python.py`: parses with the stdlib `ast`. - `rust.py`: parses with `tree-sitter` + `tree-sitter-rust` (functions, `impl` methods, `use`-based and bare-path module resolution). Calls made inside a macro invocation (`println!`, `format!`, ...) aren't visible to it - macro arguments are an opaque token stream, not parsed expressions. - `typescript.py`: one plugin for TypeScript and JavaScript, parsed with `tree-sitter` + `tree-sitter-typescript` (the `typescript` grammar for `.ts`, `.tsx` for everything else). It stamps each file with its own language, so a `.ts` file and a `.js` file get their own badge but can call each other. Reads ESM and basic CommonJS imports, resolves relative specifiers and (by unique path suffix) aliases, and ignores `.d.ts` and minified files. There's no separate "JS mode": a missing annotation is just a missing annotation. Its docstring lists exactly what it resolves and what it can't (JSX elements, inheritance, dynamic calls, ...). - - `c.py` (with `cfamily.py`, tree-sitter helpers meant to be shared with a C++ plugin): parses with `tree-sitter` + `tree-sitter-c` and owns `.c` and `.h`. Only definitions are Functions; a prototype in a header never is, but its comment documents a definition that has none. Calls are resolved by name in C's own visibility order: the same file, then files reached through quoted `#include "..."` (and the `.c` file implementing an included header), then the one non-static definition anywhere in the picked folder. A `static` function is visible only in its own file, and two or more candidates mean no wire rather than a guess. Nothing is preprocessed or compiled, so functions defined by macros aren't Functions, calls hidden in macro bodies are invisible, every `#ifdef` branch is parsed, and function-pointer calls (`cb(x)`, `s->handler(x)`) aren't linked, including a call through a parameter or local variable named like a loaded function. A file tree-sitter can't fully parse is flagged but keeps the functions it recovered. + - `c.py` (with `cfamily.py`, tree-sitter helpers shared by the C and C++ plugins): parses with `tree-sitter` + `tree-sitter-c` and owns `.c`, and `.h` unless the C++ plugin claims it. Only definitions are Functions; a prototype in a header never is, but its comment documents a definition that has none. Calls are resolved by name in C's own visibility order: the same file, then files reached through quoted `#include "..."` (and the `.c` file implementing an included header), then the one non-static definition anywhere in the picked folder. A `static` function is visible only in its own file, and two or more candidates mean no wire rather than a guess. Nothing is preprocessed or compiled, so functions defined by macros aren't Functions, calls hidden in macro bodies are invisible, every `#ifdef` branch is parsed, and function-pointer calls (`cb(x)`, `s->handler(x)`) aren't linked, including a call through a parameter or local variable named like a loaded function. A file tree-sitter can't fully parse is flagged but keeps the functions it recovered. + - `cpp.py`: parses with `tree-sitter` + `tree-sitter-cpp`, owns `.cc`, `.cpp`, `.cxx`, `.hpp`, `.hh` and `.hxx`, and claims `.h` when the picked folder holds any of those (a C-only folder's headers stay C). C and C++ are separate plugins, so no wire joins a C file to a C++ one. Functions are definitions with a body: free functions, methods defined in or out of their class, constructors, destructors and operators; lambdas aren't Functions, and a template is one Function. `qualname` is the scoped name (`ns::Class::method`); overloads defined in one file get their parameter types appended (`add(int)`, `at(int) const`), a name defined once keeps its plain name. Calls resolve by name through C++'s scopes (the enclosing class and its loaded bases, enclosing namespaces, `using` declarations, then C's include-based visibility), and when a step finds several candidates the call links only if the argument count leaves exactly one. A member call resolves by the receiver's declared type (a parameter, local variable or data member; smart pointers and aliases unwrapped), falling back to the one loaded method of that name when the type isn't visible (`auto`, a template parameter). Nothing is preprocessed or compiled: no template instantiation, no argument-dependent lookup, no overload resolution by argument types; operator expressions and calls through function pointers or `std::function` aren't linked, and virtual dispatch isn't followed, so a call through a `Base *` links to `Base::run`, never to every override. Macros hide functions and calls as in C. - `main.py`: the FastAPI app. `GET /api/browse` powers the server-side folder picker, `POST /api/analyze` runs the analyzer and returns the graph as JSON. Also serves the built frontend in production. ### Frontend