codedebrief 0.11.0__py3-none-any.whl

codedebrief/analysis/languages/_common.py

@@ -0,0 +1,68 @@
+"""Shared helpers for the tree-sitter language profiles.
+
+Centralizes the byte-slice text, named-children, and directory-as-module helpers every
+profile needs, plus the definition walker shared by class/method profiles, to avoid
+copy-paste drift across the language modules.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import Any
+
+from codedebrief.analysis.treesitter import LanguageProfile, TSDefinition
+
+
+def text(node: Any | None, source: bytes) -> str:
+    if node is None:
+        return ""
+    return source[node.start_byte : node.end_byte].decode("utf-8", "replace")
+
+
+def named(node: Any | None) -> Iterable[Any]:
+    return (child for child in node.children if child.is_named) if node is not None else ()
+
+
+def module_name(relative: str) -> str:
+    """The directory as a dotted module name, so files in one package share a namespace."""
+    return Path(relative).parent.as_posix().replace("/", ".").strip(".")
+
+
+def container_definitions(
+    containers: frozenset[str],
+    methods: frozenset[str],
+    *,
+    name_field: str = "name",
+    body_field: str = "body",
+) -> Callable[[Any, bytes, str, LanguageProfile], Iterable[TSDefinition]]:
+    """A `definitions()` for languages whose functions live inside class/module containers.
+
+    Recurses into each container, tagging found methods with the container name as owner,
+    and also yields matching top-level functions.
+    """
+
+    def definitions(
+        root: Any, source: bytes, relative: str, profile: LanguageProfile
+    ) -> Iterable[TSDefinition]:
+        yield from _walk(root, source, "")
+
+    def _walk(node: Any, source: bytes, owner: str) -> Iterable[TSDefinition]:
+        if node.type in containers:
+            name = text(node.child_by_field_name(name_field), source) or owner
+            body = node.child_by_field_name(body_field) or node.child_by_field_name(
+                "declaration_list"
+            )
+            for child in named(body if body is not None else node):
+                yield from _walk(child, source, name)
+            return
+        if node.type in methods:
+            name = text(node.child_by_field_name(name_field), source)
+            body = node.child_by_field_name(body_field)
+            if name and body is not None:
+                yield TSDefinition(name=name, node=node, body=body, owner=owner)
+            return
+        for child in named(node):
+            yield from _walk(child, source, owner)
+
+    return definitions

codedebrief/analysis/languages/c.py

@@ -0,0 +1,96 @@
+"""C language profile for the profile-driven tree-sitter analyzer."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+import tree_sitter_c
+
+from codedebrief.analysis.languages._common import module_name, text
+from codedebrief.analysis.treesitter import (
+    LanguageProfile,
+    TreeSitterAnalyzer,
+    TSDefinition,
+)
+from codedebrief.config import CodeDebriefConfig
+
+
+def _definitions(
+    root: Any, source: bytes, relative: str, profile: LanguageProfile
+) -> Iterable[TSDefinition]:
+    for node in root.children:
+        if node.type != "function_definition":
+            continue
+        name = _function_name(node.child_by_field_name("declarator"), source)
+        body = node.child_by_field_name("body")
+        if name and body is not None:
+            yield TSDefinition(name=name, node=node, body=body, owner="")
+
+
+def _function_name(declarator: Any | None, source: bytes) -> str:
+    """The identifier inside a (possibly pointer-wrapped) function_declarator."""
+    node = declarator
+    while node is not None:
+        if node.type == "identifier":
+            return text(node, source)
+        inner = node.child_by_field_name("declarator")
+        if inner is None:
+            break
+        node = inner
+    if node is not None:
+        ident = next((c for c in node.children if c.type == "identifier"), None)
+        return text(ident, source)
+    return ""
+
+
+def _classify(
+    definition: TSDefinition, relative: str, source: str, config: CodeDebriefConfig
+) -> tuple[str, str, bool]:
+    override = config.entrypoint_override(f"{relative}:{definition.name}")
+    if definition.name == "main":
+        return "c", "main", override if override is not None else True
+    is_static = any(
+        c.type == "storage_class_specifier" and c.text.decode() == "static"
+        for c in definition.node.children
+    )
+    public = config.include_public_functions and not is_static
+    return "generic", "function", override if override is not None else public
+
+
+def _is_test(relative: str, name: str) -> bool:
+    # Anchor to path SEGMENTS (a `test`/`tests` directory or a test_*.c / *_test.c file),
+    # not a substring of the whole path: `latest/` or `contest.c` must not count, and a
+    # real function named `test_harness` outside a test file must not be misclassified.
+    lowered = relative.lower()
+    segments = lowered.split("/")
+    filename = segments[-1]
+    return (
+        any(segment in {"test", "tests"} for segment in segments[:-1])
+        or filename.startswith("test_")
+        or filename.endswith(("_test.c", "_test.h"))
+    )
+
+
+C_PROFILE = LanguageProfile(
+    language="c",
+    grammar_loader=tree_sitter_c.language,
+    function_types=frozenset({"function_definition"}),
+    definitions=_definitions,
+    classify=_classify,
+    is_test=_is_test,
+    module_name=module_name,
+    block_types=frozenset({"compound_statement"}),
+    switch_types=frozenset({"switch_statement"}),
+    switch_value_field="condition",
+    case_types=frozenset({"case_statement"}),
+    default_when_no_value=True,
+    case_fall_through=True,
+    loop_types=frozenset({"for_statement", "while_statement", "do_statement"}),
+    assignment_types=frozenset({"declaration"}),
+)
+
+
+def build_analyzer(root: Path, config: CodeDebriefConfig) -> TreeSitterAnalyzer:
+    return TreeSitterAnalyzer(root, config, C_PROFILE)

codedebrief/analysis/languages/cpp.py

@@ -0,0 +1,146 @@
+"""C++ language profile for the profile-driven tree-sitter analyzer."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+import tree_sitter_cpp
+
+from codedebrief.analysis.languages._common import module_name, text
+from codedebrief.analysis.treesitter import (
+    LanguageProfile,
+    TreeSitterAnalyzer,
+    TSDefinition,
+)
+from codedebrief.config import CodeDebriefConfig
+
+
+def _definitions(
+    root: Any, source: bytes, relative: str, profile: LanguageProfile
+) -> Iterable[TSDefinition]:
+    yield from _walk(root, source, "")
+
+
+def _walk(node: Any, source: bytes, owner: str) -> Iterable[TSDefinition]:
+    if node.type in {"class_specifier", "struct_specifier", "namespace_definition"}:
+        name = text(node.child_by_field_name("name"), source)
+        next_owner = ".".join(part for part in (owner, name) if part)
+        body = node.child_by_field_name("body")
+        for child in body.children if body is not None else node.children:
+            if child.is_named:
+                yield from _walk(child, source, next_owner)
+        return
+    if node.type == "function_definition":
+        name, explicit_owner = _qualified_function_name(
+            node.child_by_field_name("declarator"), source
+        )
+        body = node.child_by_field_name("body")
+        if name and body is not None:
+            yield TSDefinition(name=name, node=node, body=body, owner=explicit_owner or owner)
+        return
+    for child in node.children:
+        if child.is_named:
+            yield from _walk(child, source, owner)
+
+
+def _qualified_function_name(declarator: Any | None, source: bytes) -> tuple[str, str]:
+    """Return (name, owner) from a possibly nested/qualified function declarator."""
+    target = declarator
+    while target is not None:
+        inner = target.child_by_field_name("declarator")
+        if inner is None:
+            break
+        target = inner
+    identifiers = _identifier_texts(target, source)
+    if not identifiers:
+        identifiers = _identifier_texts(declarator, source)
+    if not identifiers:
+        return "", ""
+    return identifiers[-1], ".".join(identifiers[:-1])
+
+
+def _identifier_texts(node: Any | None, source: bytes) -> list[str]:
+    if node is None:
+        return []
+    values: list[str] = []
+    stack = [node]
+    while stack:
+        current = stack.pop()
+        if current.type in {"identifier", "field_identifier", "type_identifier", "destructor_name"}:
+            values.append(text(current, source).lstrip("~"))
+            continue
+        stack.extend(reversed(current.children))
+    return [value for value in values if value]
+
+
+def _classify(
+    definition: TSDefinition, relative: str, source: str, config: CodeDebriefConfig
+) -> tuple[str, str, bool]:
+    owner_prefix = f"{definition.owner}." if definition.owner else ""
+    override = config.entrypoint_override(f"{relative}:{owner_prefix}{definition.name}")
+    if definition.name == "main" and not definition.owner:
+        return "cpp", "main", override if override is not None else True
+    public = config.include_public_functions and not _has_static_storage(definition.node)
+    return (
+        "generic",
+        "method" if definition.owner else "function",
+        (override if override is not None else public),
+    )
+
+
+def _has_static_storage(node: Any) -> bool:
+    return any(
+        child.type == "storage_class_specifier" and child.text.decode() == "static"
+        for child in node.children
+    )
+
+
+def _is_test(relative: str, name: str) -> bool:
+    lowered = relative.lower()
+    segments = lowered.split("/")
+    filename = segments[-1]
+    return (
+        any(segment in {"test", "tests"} for segment in segments[:-1])
+        or filename.startswith("test_")
+        or filename.endswith(
+            (
+                "_test.cc",
+                "_test.cpp",
+                "_test.cxx",
+                "_test.hh",
+                "_test.hpp",
+                "_test.hxx",
+            )
+        )
+    )
+
+
+CPP_PROFILE = LanguageProfile(
+    language="cpp",
+    grammar_loader=tree_sitter_cpp.language,
+    function_types=frozenset({"function_definition"}),
+    definitions=_definitions,
+    classify=_classify,
+    is_test=_is_test,
+    module_name=module_name,
+    block_types=frozenset({"compound_statement"}),
+    switch_types=frozenset({"switch_statement"}),
+    switch_value_field="condition",
+    case_types=frozenset({"case_statement"}),
+    default_when_no_value=True,
+    case_fall_through=True,
+    loop_types=frozenset(
+        {"for_statement", "while_statement", "do_statement", "range_based_for_statement"}
+    ),
+    throw_types=frozenset({"throw_statement"}),
+    call_types=frozenset({"call_expression"}),
+    try_type="try_statement",
+    catch_types=frozenset({"catch_clause"}),
+    assignment_types=frozenset({"declaration"}),
+)
+
+
+def build_analyzer(root: Path, config: CodeDebriefConfig) -> TreeSitterAnalyzer:
+    return TreeSitterAnalyzer(root, config, CPP_PROFILE)

codedebrief/analysis/languages/csharp.py

@@ -0,0 +1,137 @@
+"""C# language profile for the profile-driven tree-sitter analyzer."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import tree_sitter_c_sharp
+
+from codedebrief.analysis.common import DEFAULT as DEFAULT_LABEL
+from codedebrief.analysis.languages._common import container_definitions, module_name, named, text
+from codedebrief.analysis.treesitter import (
+    CaseInfo,
+    LanguageProfile,
+    TreeSitterAnalyzer,
+    TSDefinition,
+)
+from codedebrief.config import CodeDebriefConfig
+
+_CONTAINERS = frozenset(
+    {
+        "class_declaration",
+        "struct_declaration",
+        "record_declaration",
+        "interface_declaration",
+        "namespace_declaration",
+        "file_scoped_namespace_declaration",
+    }
+)
+_METHODS = frozenset({"method_declaration", "constructor_declaration", "local_function_statement"})
+_ROUTE_TAGS = ("HttpGet", "HttpPost", "Route", "HttpPut", "HttpDelete")
+
+
+def _modifiers(node: Any, source: bytes) -> str:
+    kinds = {"modifier", "attribute_list"}
+    return " ".join(text(c, source) for c in node.children if c.type in kinds)
+
+
+def _classify(
+    definition: TSDefinition, relative: str, source: str, config: CodeDebriefConfig
+) -> tuple[str, str, bool]:
+    override = config.entrypoint_override(f"{relative}:{definition.owner}.{definition.name}")
+    modifiers = _modifiers(definition.node, source.encode("utf-8"))
+    if definition.name == "Main":
+        return "csharp", "main", override if override is not None else True
+    if any(tag in modifiers for tag in _ROUTE_TAGS):
+        return "aspnet", "route", override if override is not None else True
+    public = config.include_public_functions and "public" in modifiers
+    return "generic", "method", override if override is not None else public
+
+
+def _is_test(relative: str, name: str) -> bool:
+    # Anchor to path SEGMENTS and the C# *Test.cs / *Tests.cs class-file convention, not a
+    # substring of the whole path or a bare `Test`-prefixed method name (`TestRunner`,
+    # `TestData`...) - those are real methods. The file suffix is matched case-sensitively
+    # so `Latest.cs` (a real class) does not look like a test.
+    segments = relative.split("/")
+    return any(segment.lower() in {"test", "tests"} for segment in segments[:-1]) or segments[
+        -1
+    ].endswith(("Test.cs", "Tests.cs"))
+
+
+def _import_map(root: Any, source: bytes, relative: str) -> dict[str, str]:
+    mapping: dict[str, str] = {}
+    for directive in root.children:
+        if directive.type != "using_directive":
+            continue
+        specifier = _using_specifier(directive, source)
+        if not specifier:
+            continue
+        alias = directive.child_by_field_name("name")
+        is_static = any(child.type == "static" for child in directive.children)
+        if alias is not None:
+            mapping[text(alias, source)] = f"{specifier}:"
+        elif is_static:
+            mapping[f"__static_using__:{specifier}"] = f"{specifier}:"
+        else:
+            mapping[f"__namespace_using__:{specifier}"] = f"{specifier}:"
+    return mapping
+
+
+def _using_specifier(directive: Any, source: bytes) -> str:
+    for child in directive.children:
+        if child.type in {"qualified_name", "alias_qualified_name"}:
+            return text(child, source)
+    alias = directive.child_by_field_name("name")
+    for child in directive.children:
+        if child.type == "identifier" and child is not alias:
+            value = text(child, source)
+            if value != "static":
+                return value
+    return ""
+
+
+def _switch_cases(switch_node: Any, source: bytes, profile: LanguageProfile) -> list[CaseInfo]:
+    body = switch_node.child_by_field_name("body")
+    cases: list[CaseInfo] = []
+    for section in named(body):
+        if section.type != "switch_section":
+            continue
+        labels = [c for c in named(section) if "pattern" in c.type or "switch_label" in c.type]
+        statements = [c for c in named(section) if c not in labels]
+        values = [text(label, source) for label in labels]
+        if not values:
+            cases.append(CaseInfo(DEFAULT_LABEL, True, [], statements))
+        else:
+            cases.append(CaseInfo(", ".join(values), False, values, statements))
+    return cases
+
+
+CSHARP_PROFILE = LanguageProfile(
+    language="csharp",
+    grammar_loader=tree_sitter_c_sharp.language,
+    function_types=_METHODS,
+    definitions=container_definitions(_CONTAINERS, _METHODS),
+    classify=_classify,
+    is_test=_is_test,
+    module_name=module_name,
+    import_map=_import_map,
+    dependency_module_suffixes=(".cs",),
+    dependency_package_directories=True,
+    switch_types=frozenset({"switch_statement"}),
+    switch_value_field="value",
+    switch_cases=_switch_cases,
+    loop_types=frozenset({"for_statement", "foreach_statement", "while_statement", "do_statement"}),
+    throw_types=frozenset({"throw_statement"}),
+    call_types=frozenset({"invocation_expression"}),
+    try_type="try_statement",
+    catch_types=frozenset({"catch_clause"}),
+    finally_types=frozenset({"finally_clause"}),
+    assignment_types=frozenset({"local_declaration_statement", "assignment_expression"}),
+    nested_def_types=frozenset({"lambda_expression", "anonymous_method_expression"}),
+)
+
+
+def build_analyzer(root: Path, config: CodeDebriefConfig) -> TreeSitterAnalyzer:
+    return TreeSitterAnalyzer(root, config, CSHARP_PROFILE)

codedebrief/analysis/languages/go.py

@@ -0,0 +1,157 @@
+"""Go language profile for the profile-driven tree-sitter analyzer."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+import tree_sitter_go
+
+from codedebrief.analysis.languages._common import module_name, text
+from codedebrief.analysis.treesitter import (
+    LanguageProfile,
+    TreeSitterAnalyzer,
+    TSDefinition,
+)
+from codedebrief.config import CodeDebriefConfig
+from codedebrief.model import Flow
+
+_TEST_PREFIXES = ("Test", "Benchmark", "Example", "Fuzz")
+
+
+def _definitions(
+    root: Any, source: bytes, relative: str, profile: LanguageProfile
+) -> Iterable[TSDefinition]:
+    for node in root.children:
+        if node.type == "function_declaration":
+            name = text(node.child_by_field_name("name"), source)
+            body = node.child_by_field_name("body")
+            if name and body is not None:
+                yield TSDefinition(name=name, node=node, body=body, owner="")
+        elif node.type == "method_declaration":
+            name = text(node.child_by_field_name("name"), source)
+            body = node.child_by_field_name("body")
+            owner = _receiver_type(node.child_by_field_name("receiver"), source)
+            if name and body is not None:
+                yield TSDefinition(name=name, node=node, body=body, owner=owner)
+
+
+def _receiver_type(receiver: Any | None, source: bytes) -> str:
+    if receiver is None:
+        return ""
+    stack = [receiver]
+    while stack:
+        current = stack.pop()
+        if current.type == "type_identifier":
+            return text(current, source)
+        stack.extend(current.children)
+    return ""
+
+
+def _import_map(root: Any, source: bytes, relative: str) -> dict[str, str]:
+    mapping: dict[str, str] = {}
+    for declaration in root.children:
+        if declaration.type != "import_declaration":
+            continue
+        for spec in _import_specs(declaration):
+            path = _import_path(spec, source)
+            if not path:
+                continue
+            module = path.replace("/", ".").strip(".")
+            if not module:
+                continue
+            alias = _import_alias(spec, source)
+            if alias in {"_", "."}:
+                mapping[f"__side_effect_import__:{module}"] = f"{module}:"
+                continue
+            binding = alias or path.rsplit("/", 1)[-1]
+            if binding:
+                mapping[binding] = f"{module}:"
+    return mapping
+
+
+def _import_specs(declaration: Any) -> Iterable[Any]:
+    stack = deque(declaration.children)
+    while stack:
+        current = stack.popleft()
+        if current.type == "import_spec":
+            yield current
+            continue
+        stack.extendleft(reversed(current.children))
+
+
+def _import_path(spec: Any, source: bytes) -> str:
+    literal = next(
+        (
+            child
+            for child in spec.children
+            if child.type in {"interpreted_string_literal", "raw_string_literal"}
+        ),
+        None,
+    )
+    return text(literal, source).strip('"`')
+
+
+def _import_alias(spec: Any, source: bytes) -> str:
+    for child in spec.children:
+        if child.type in {"package_identifier", "blank_identifier", "dot"}:
+            return text(child, source)
+    return ""
+
+
+def _classify(
+    definition: TSDefinition, relative: str, source: str, config: CodeDebriefConfig
+) -> tuple[str, str, bool]:
+    owner_prefix = f"{definition.owner}." if definition.owner else ""
+    override = config.entrypoint_override(f"{relative}:{owner_prefix}{definition.name}")
+    exported = definition.name[:1].isupper()
+    if definition.name == "main" and not definition.owner:
+        return "go", "main", override if override is not None else True
+    entry_kind = "method" if definition.owner else "function"
+    public = config.include_public_functions and exported
+    return "generic", entry_kind, override if override is not None else public
+
+
+def _is_test(relative: str, name: str) -> bool:
+    return relative.endswith("_test.go") or name.startswith(_TEST_PREFIXES)
+
+
+def _dependency_path_filter(relative: str) -> bool:
+    return not relative.endswith("_test.go")
+
+
+def _entry_label(flow: Flow) -> str:
+    prefix = {"main": "Main", "test": "Test"}.get(flow.entry_kind)
+    return f"{prefix}: {flow.name}" if prefix else flow.name
+
+
+GO_PROFILE = LanguageProfile(
+    language="go",
+    grammar_loader=tree_sitter_go.language,
+    function_types=frozenset({"function_declaration", "method_declaration"}),
+    definitions=_definitions,
+    classify=_classify,
+    is_test=_is_test,
+    module_name=module_name,
+    import_map=_import_map,
+    dependency_module_suffixes=(".go",),
+    dependency_package_directories=True,
+    dependency_path_filter=_dependency_path_filter,
+    entry_label=_entry_label,
+    switch_types=frozenset({"expression_switch_statement", "type_switch_statement"}),
+    switch_body_field=None,
+    case_types=frozenset({"expression_case", "type_case"}),
+    default_types=frozenset({"default_case", "communication_case"}),
+    case_value_field="value",
+    loop_types=frozenset({"for_statement"}),
+    throw_types=frozenset(),
+    assignment_types=frozenset({"short_var_declaration", "assignment_statement"}),
+    assignment_target_field="left",
+    nested_def_types=frozenset({"func_literal"}),
+)
+
+
+def build_analyzer(root: Path, config: CodeDebriefConfig) -> TreeSitterAnalyzer:
+    return TreeSitterAnalyzer(root, config, GO_PROFILE)