codepulse-engine 0.1.0__py3-none-any.whl

codepulse/parser/javascript.py

@@ -0,0 +1,428 @@
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+from tree_sitter_languages import get_parser
+
+from codepulse.models import CallReference, ImportItem, ImportStatement, Symbol, SymbolType
+from codepulse.parser.base import LanguageParser
+
+
+class JavaScriptParser(LanguageParser):
+    """AST parser for JavaScript and TypeScript source code using Tree-sitter."""
+
+    def __init__(self, is_typescript: bool = False) -> None:
+        self._is_typescript = is_typescript
+        try:
+            self._parser = get_parser("typescript" if is_typescript else "javascript")
+        except Exception:
+            # Fallback to javascript parser
+            self._parser = get_parser("javascript")
+
+    @property
+    def language(self) -> str:
+        return "typescript" if self._is_typescript else "javascript"
+
+    def extract_symbols(self, source_code: str, file_path: str = "") -> list[Symbol]:
+        source_bytes = source_code.encode("utf-8")
+        tree = self._parser.parse(source_bytes)
+        symbols: list[Symbol] = []
+
+        def walk(node: Any, parent_class: str | None = None) -> None:
+            # 1. Function Declarations: function foo() {}
+            if node.type in ("function_declaration", "generator_function_declaration"):
+                sym = self._parse_function_declaration(node, source_bytes, file_path, parent_class)
+                if sym:
+                    symbols.append(sym)
+                body_node = node.child_by_field_name("body")
+                if body_node:
+                    for child in body_node.children:
+                        walk(child, parent_class=sym.name if sym else parent_class)
+                return
+
+            # 2. Variable declarations with arrow functions / function expressions: const foo = () => {}
+            elif node.type == "lexical_declaration" or node.type == "variable_declaration":
+                syms = self._parse_variable_functions(node, source_bytes, file_path, parent_class)
+                symbols.extend(syms)
+                for child in node.children:
+                    walk(child, parent_class)
+                return
+
+            # 3. Class Declarations: class MyClass {}
+            elif node.type == "class_declaration":
+                sym = self._parse_class_declaration(node, source_bytes, file_path, parent_class)
+                if sym:
+                    symbols.append(sym)
+                body_node = node.child_by_field_name("body")
+                if body_node:
+                    for child in body_node.children:
+                        walk(child, parent_class=sym.name if sym else parent_class)
+                return
+
+            # 4. Method Definitions inside class body: foo() {}
+            elif node.type == "method_definition":
+                sym = self._parse_method_definition(node, source_bytes, file_path, parent_class)
+                if sym:
+                    symbols.append(sym)
+                body_node = node.child_by_field_name("body")
+                if body_node:
+                    for child in body_node.children:
+                        walk(child, parent_class=sym.name if sym else parent_class)
+                return
+
+            for child in node.children:
+                walk(child, parent_class)
+
+        walk(tree.root_node)
+        return symbols
+
+    def _parse_function_declaration(
+        self, node: Any, source_bytes: bytes, file_path: str, parent_class: str | None
+    ) -> Symbol | None:
+        name_node = node.child_by_field_name("name")
+        if not name_node:
+            return None
+
+        name = source_bytes[name_node.start_byte:name_node.end_byte].decode("utf-8", errors="replace")
+        start_line = node.start_point[0] + 1
+        end_line = node.end_point[0] + 1
+        body_text = source_bytes[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+        docstring = self._extract_jsdoc(node, source_bytes)
+        signature = self._extract_signature(node, source_bytes)
+        complexity = self._calculate_complexity(node)
+
+        return Symbol(
+            name=name,
+            type=SymbolType.METHOD if parent_class else SymbolType.FUNCTION,
+            file_path=file_path,
+            start_line=start_line,
+            end_line=end_line,
+            signature=signature,
+            docstring=docstring,
+            body=body_text,
+            body_hash=hashlib.sha256(body_text.strip().encode("utf-8")).hexdigest(),
+            language=self.language,
+            parent_symbol=parent_class,
+            complexity=complexity,
+        )
+
+    def _parse_variable_functions(
+        self, node: Any, source_bytes: bytes, file_path: str, parent_class: str | None
+    ) -> list[Symbol]:
+        results: list[Symbol] = []
+        for child in node.children:
+            if child.type == "variable_declarator":
+                name_n = child.child_by_field_name("name")
+                value_n = child.child_by_field_name("value")
+                if name_n and value_n and value_n.type in ("arrow_function", "function_expression"):
+                    name = source_bytes[name_n.start_byte:name_n.end_byte].decode("utf-8", errors="replace")
+                    start_line = node.start_point[0] + 1
+                    end_line = node.end_point[0] + 1
+                    body_text = source_bytes[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+                    docstring = self._extract_jsdoc(node, source_bytes)
+                    signature = self._extract_signature(node, source_bytes)
+                    complexity = self._calculate_complexity(value_n)
+
+                    results.append(
+                        Symbol(
+                            name=name,
+                            type=SymbolType.METHOD if parent_class else SymbolType.FUNCTION,
+                            file_path=file_path,
+                            start_line=start_line,
+                            end_line=end_line,
+                            signature=signature,
+                            docstring=docstring,
+                            body=body_text,
+                            body_hash=hashlib.sha256(body_text.strip().encode("utf-8")).hexdigest(),
+                            language=self.language,
+                            parent_symbol=parent_class,
+                            complexity=complexity,
+                        )
+                    )
+        return results
+
+    def _parse_class_declaration(
+        self, node: Any, source_bytes: bytes, file_path: str, parent_class: str | None
+    ) -> Symbol | None:
+        name_node = node.child_by_field_name("name")
+        if not name_node:
+            return None
+
+        name = source_bytes[name_node.start_byte:name_node.end_byte].decode("utf-8", errors="replace")
+        start_line = node.start_point[0] + 1
+        end_line = node.end_point[0] + 1
+        body_text = source_bytes[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+        docstring = self._extract_jsdoc(node, source_bytes)
+        signature = self._extract_signature(node, source_bytes)
+        base_classes = self._extract_base_classes(node, source_bytes)
+
+        return Symbol(
+            name=name,
+            type=SymbolType.CLASS,
+            file_path=file_path,
+            start_line=start_line,
+            end_line=end_line,
+            signature=signature,
+            docstring=docstring,
+            body=body_text,
+            body_hash=hashlib.sha256(body_text.strip().encode("utf-8")).hexdigest(),
+            language=self.language,
+            parent_symbol=parent_class,
+            complexity=1,
+            base_classes=base_classes,
+        )
+
+    def _extract_base_classes(self, node: Any, source_bytes: bytes) -> list[str]:
+        """
+        Phase 4.1 (roadmap §37 item 4.1: "Base-class/inheritance
+        extraction (Python + JS/TS)"). Confirmed via direct tree-sitter
+        grammar probes during this milestone's own design audit that the
+        PLAIN JAVASCRIPT and TYPESCRIPT grammars shape `class_heritage`
+        differently:
+
+          - Plain JavaScript: `class_declaration -> class_heritage ->
+            (extends, <base expression>)` -- the base expression is a
+            DIRECT child of `class_heritage` (no wrapper node).
+          - TypeScript: `class_declaration -> class_heritage ->
+            extends_clause -> (extends, <base expression>)`, with an
+            optional SIBLING `implements_clause` (interface
+            implementation) inside `class_heritage` alongside
+            `extends_clause`. `implements_clause` is DELIBERATELY never
+            inspected here -- interface implementation is a different
+            relationship than base-class inheritance, out of this
+            milestone's exact scope (roadmap §37 item 4.1 names
+            "base-class/inheritance extraction," not "implements");
+            only ever looking WITHIN `extends_clause` when present is
+            what keeps `implements_clause` categorically unreachable
+            here, not an extra exclusion check.
+
+        `<base expression>` is either an `identifier` (`Base`) or a
+        `member_expression` (`ns.Base`, a dotted/namespace-qualified
+        base) -- the only two node types that can actually name a base
+        class in either grammar. Returns the raw text exactly as
+        written; resolution happens separately in `CallGraphBuilder`.
+        """
+        heritage = None
+        for child in node.children:
+            if child.type == "class_heritage":
+                heritage = child
+                break
+        if heritage is None:
+            return []
+
+        extends_clause = None
+        for child in heritage.children:
+            if child.type == "extends_clause":
+                extends_clause = child
+                break
+
+        # TypeScript wraps the base expression in extends_clause (and
+        # that is the ONLY place searched, so implements_clause -- a
+        # sibling of extends_clause, never a descendant of it -- is
+        # never reached). Plain JavaScript has no such wrapper -- the
+        # base expression is a direct child of class_heritage itself.
+        search_within = extends_clause if extends_clause is not None else heritage
+
+        bases: list[str] = []
+        for child in search_within.children:
+            if child.type in ("identifier", "member_expression", "type_identifier"):
+                bases.append(
+                    source_bytes[child.start_byte:child.end_byte].decode("utf-8", errors="replace")
+                )
+        return bases
+
+    def _parse_method_definition(
+        self, node: Any, source_bytes: bytes, file_path: str, parent_class: str | None
+    ) -> Symbol | None:
+        name_node = node.child_by_field_name("name")
+        if not name_node:
+            return None
+
+        name = source_bytes[name_node.start_byte:name_node.end_byte].decode("utf-8", errors="replace")
+        start_line = node.start_point[0] + 1
+        end_line = node.end_point[0] + 1
+        body_text = source_bytes[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+        docstring = self._extract_jsdoc(node, source_bytes)
+        signature = self._extract_signature(node, source_bytes)
+        complexity = self._calculate_complexity(node)
+
+        return Symbol(
+            name=name,
+            type=SymbolType.METHOD,
+            file_path=file_path,
+            start_line=start_line,
+            end_line=end_line,
+            signature=signature,
+            docstring=docstring,
+            body=body_text,
+            body_hash=hashlib.sha256(body_text.strip().encode("utf-8")).hexdigest(),
+            language=self.language,
+            parent_symbol=parent_class,
+            complexity=complexity,
+        )
+
+    def _extract_jsdoc(self, node: Any, source_bytes: bytes) -> str | None:
+        # Check previous sibling for comment
+        prev = node.prev_sibling
+        if prev and prev.type == "comment":
+            cmt = source_bytes[prev.start_byte:prev.end_byte].decode("utf-8", errors="replace")
+            if cmt.startswith("/**") and cmt.endswith("*/"):
+                lines = [l.strip().lstrip("/*").rstrip("*/").lstrip("*").strip() for l in cmt.splitlines()]
+                clean_lines = [l for l in lines if l]
+                return "\n".join(clean_lines) if clean_lines else None
+            elif cmt.startswith("//"):
+                return cmt.lstrip("/").strip()
+        return None
+
+    def _extract_signature(self, node: Any, source_bytes: bytes) -> str:
+        body_node = node.child_by_field_name("body")
+        if body_node:
+            sig_bytes = source_bytes[node.start_byte:body_node.start_byte]
+            sig_text = sig_bytes.decode("utf-8", errors="replace").strip()
+            return " ".join(sig_text.split())
+        
+        full_text = source_bytes[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+        return full_text.splitlines()[0].strip().rstrip("{").strip()
+
+    def _calculate_complexity(self, node: Any) -> int:
+        complexity = 1
+        branching_types = {
+            "if_statement", "for_statement", "for_in_statement", "while_statement",
+            "do_statement", "catch_clause", "switch_case", "ternary_expression",
+            "binary_expression"  # Logical && and ||
+        }
+
+        def count_branches(n: Any) -> None:
+            nonlocal complexity
+            if n.type in branching_types:
+                complexity += 1
+            for child in n.children:
+                count_branches(child)
+
+        count_branches(node)
+        return complexity
+
+    def extract_imports(self, source_code: str, file_path: str = "") -> list[ImportStatement]:
+        source_bytes = source_code.encode("utf-8")
+        tree = self._parser.parse(source_bytes)
+        imports: list[ImportStatement] = []
+
+        def walk(node: Any) -> None:
+            # ES6: import { a, b as c } from './module';
+            # ES6: import React from 'react';
+            # ES6: import * as path from 'path';
+            if node.type == "import_statement":
+                line_num = node.start_point[0] + 1
+                source_node = node.child_by_field_name("source")
+                module_name = ""
+                if source_node:
+                    module_name = source_bytes[source_node.start_byte:source_node.end_byte].decode("utf-8").strip("'\"")
+
+                is_relative = module_name.startswith(".")
+                level = 1 if module_name.startswith("./") else (2 if module_name.startswith("../") else 0)
+
+                items: list[ImportItem] = []
+                for child in node.children:
+                    if child.type == "import_clause":
+                        for sub in child.children:
+                            if sub.type == "identifier":
+                                default_name = source_bytes[sub.start_byte:sub.end_byte].decode("utf-8")
+                                items.append(ImportItem(name=default_name, alias="default"))
+                            elif sub.type == "named_imports":
+                                for spec in sub.children:
+                                    if spec.type == "import_specifier":
+                                        name_n = spec.child_by_field_name("name")
+                                        alias_n = spec.child_by_field_name("alias")
+                                        if name_n:
+                                            item_name = source_bytes[name_n.start_byte:name_n.end_byte].decode("utf-8")
+                                            alias = source_bytes[alias_n.start_byte:alias_n.end_byte].decode("utf-8") if alias_n else None
+                                            items.append(ImportItem(name=item_name, alias=alias))
+                            elif sub.type == "namespace_import":
+                                for ns_child in sub.children:
+                                    if ns_child.type == "identifier":
+                                        alias = source_bytes[ns_child.start_byte:ns_child.end_byte].decode("utf-8")
+                                        items.append(ImportItem(name="*", alias=alias))
+
+                imports.append(
+                    ImportStatement(
+                        module=module_name,
+                        items=items,
+                        is_relative=is_relative,
+                        level=level,
+                        line_number=line_num,
+                        file_path=file_path,
+                    )
+                )
+
+            # CommonJS: const foo = require('foo')
+            elif node.type == "call_expression":
+                func_n = node.child_by_field_name("function")
+                args_n = node.child_by_field_name("arguments")
+                if func_n and args_n:
+                    fn_name = source_bytes[func_n.start_byte:func_n.end_byte].decode("utf-8", errors="replace")
+                    if fn_name == "require" and args_n.children:
+                        for arg in args_n.children:
+                            if arg.type == "string":
+                                mod_name = source_bytes[arg.start_byte:arg.end_byte].decode("utf-8").strip("'\"")
+                                line_num = node.start_point[0] + 1
+                                is_rel = mod_name.startswith(".")
+                                imports.append(
+                                    ImportStatement(
+                                        module=mod_name,
+                                        items=[],
+                                        is_relative=is_rel,
+                                        level=1 if mod_name.startswith("./") else (2 if mod_name.startswith("../") else 0),
+                                        line_number=line_num,
+                                        file_path=file_path,
+                                    )
+                                )
+
+            for child in node.children:
+                walk(child)
+
+        walk(tree.root_node)
+        return imports
+
+    def extract_calls(
+        self, source_code: str, file_path: str = "", symbols: list[Symbol] | None = None
+    ) -> list[CallReference]:
+        if symbols is None:
+            symbols = self.extract_symbols(source_code, file_path=file_path)
+
+        source_bytes = source_code.encode("utf-8")
+        tree = self._parser.parse(source_bytes)
+        calls: list[CallReference] = []
+
+        def find_enclosing_symbol(line: int) -> str:
+            matching = [s for s in symbols if s.start_line <= line <= s.end_line]
+            if not matching:
+                return "<module>"
+            matching.sort(key=lambda s: (s.end_line - s.start_line))
+            return matching[0].name
+
+        def walk(node: Any) -> None:
+            if node.type == "call_expression":
+                func_node = node.child_by_field_name("function")
+                if func_node:
+                    callee_name = source_bytes[func_node.start_byte:func_node.end_byte].decode("utf-8", errors="replace")
+                    if func_node.type == "member_expression":
+                        prop_node = func_node.child_by_field_name("property")
+                        if prop_node:
+                            callee_name = source_bytes[prop_node.start_byte:prop_node.end_byte].decode("utf-8", errors="replace")
+
+                    line_num = node.start_point[0] + 1
+                    caller = find_enclosing_symbol(line_num)
+                    calls.append(
+                        CallReference(
+                            caller_symbol=caller,
+                            callee_name=callee_name,
+                            line_number=line_num,
+                            file_path=file_path,
+                        )
+                    )
+
+            for child in node.children:
+                walk(child)
+
+        walk(tree.root_node)
+        return calls

codepulse/parser/module_graph.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from typing import Any
+
+import networkx as nx
+
+from codepulse.models import FileParseResult
+from codepulse.parser.graph import ImportResolver
+
+
+class ModuleGraphBuilder:
+    """
+    Phase 4.3 (roadmap §37 item 4.3: "Deterministic module-clustering
+    via import graph"; §11 "Architecture discovery": "module/dependency-
+    cluster detection via the existing import graph... to identify
+    likely 'modules' and 'entry points'"; §45 backlog B18: "New
+    graph-analysis module").
+
+    Deliberately kept SEPARATE from `CallGraphBuilder` (roadmap §37
+    item 4.3's own instruction) -- this class operates on the
+    FILE-LEVEL import graph, not the symbol-level call/inheritance
+    graph. It reuses `ImportResolver.resolve_import_path` exactly as
+    written (no second import resolver, no duplicated resolution
+    logic) purely to turn each file's own `ImportStatement`s into
+    file-to-file edges.
+
+    Library/shared-core only, per this milestone's explicit approved
+    scope -- no REST route, CLI command, or MCP tool consumes this yet.
+    A future one can, through `IndexingEngine.analyze_module_structure`,
+    without duplicating any of this construction logic.
+
+    2026-10-12 (user-approved, CODEPULSE_FUTURE_CHANGES.md item 15): the
+    resolved file-to-file edges are now persisted (`module_edges`) and a
+    graph can be rebuilt from them with `from_edges`, so module structure
+    survives a restart. `snapshot` computes just the files and edges (no
+    clustering) for the index-time write; `from_edges` then produces a
+    graph identical, in every public structure, to one built from parse
+    results.
+
+    Graph semantics (approved, roadmap §37 item 4.3 audit):
+      - Nodes are every file this repository's parser actually parsed
+        (`ImportResolver.files`), INCLUDING files with zero imports in
+        either direction -- isolated files are never silently omitted.
+      - An edge `source_file -> target_file` exists if `source_file`
+        contains at least one import statement that
+        `ImportResolver.resolve_import_path` resolves to `target_file`
+        (a real, repository-local file). Multiple import statements in
+        `source_file` resolving to the SAME `target_file` collapse to
+        exactly one edge -- this graph represents file-to-file
+        dependency EXISTENCE, not a raw import-statement count (unlike
+        `CallGraphEdge.call_count`, which deliberately does count).
+      - An import that does not resolve to a real file in this
+        repository (an external package, a stdlib module, or a genuine
+        parser gap) never becomes an edge and never creates a node for
+        the unresolved target -- `ImportResolver.resolve_import_path`
+        is the single source of truth for "does this import point at
+        one of this repository's own files," reused unmodified.
+      - A file importing itself is not recorded as a self-loop edge.
+
+    `in_degree`/`out_degree` are computed from this exact edge set (the
+    distinct-file-pair notion above), never from raw import-statement
+    counts. They are exposed as RAW, uninterpreted signals -- no
+    "importance"/"centrality"/"API probability" score is computed or
+    stored anywhere in this class. §11's own literal heuristic (kept
+    exactly as worded, not silently reversed to match conventional
+    "entry point" intuition): a file with many inbound and few outbound
+    edges is read by the roadmap as looking like an API/entry point; a
+    file with many outbound and few inbound edges is read as looking
+    like a utility/leaf module. `rank_by_inbound`/`rank_by_outbound`
+    below surface the raw degree data sorted for each of those two
+    readings -- they attach no label, score, or threshold of any kind.
+
+    Clustering (approved, roadmap §37 item 4.3 audit -- empirically
+    evaluated against CodePulse's own repository before this decision
+    was made, not assumed): plain connected components over this same
+    file graph was tried first and produced one 27-file component plus
+    one singleton on this project's own `codepulse/` package -- not
+    "coherent module clusters" by any reasonable reading, and a
+    measured failure of B18's own self-referential DoD. Seeded Louvain
+    community detection (`networkx.algorithms.community.
+    louvain_communities`) over an UNDIRECTED view of the same edge set
+    produced multiple genuinely coherent clusters on the same
+    repository and is the approved algorithm. `_LOUVAIN_SEED` is fixed
+    and NOT exposed as a caller-supplied parameter this milestone --
+    empirically verified (same audit) that the identical seed produces
+    byte-identical output across repeated runs and across independent
+    processes with different `PYTHONHASHSEED` values, while a
+    different seed can produce a different partition of the same
+    graph. The seed is therefore part of this class's deterministic
+    contract, not an incidental default. Clusters are NEVER read as an
+    objective "correct" decomposition of the codebase -- they are a
+    deterministic, graph-derived grouping, reproducible for a given
+    snapshot and seed, nothing more.
+    """
+
+    _LOUVAIN_SEED = 0
+
+    def __init__(self, parse_results: dict[str, FileParseResult] | list[FileParseResult]) -> None:
+        self.resolver = ImportResolver(parse_results)
+        self.files: list[str] = sorted(self.resolver.files.keys())
+
+        self.adjacency: dict[str, set[str]] = {f: set() for f in self.files}
+        self.reverse_adjacency: dict[str, set[str]] = {f: set() for f in self.files}
+
+        for file_path, target in self._resolve_edges(self.resolver):
+            self.adjacency[file_path].add(target)
+            self.reverse_adjacency[target].add(file_path)
+
+        self.in_degree: dict[str, int] = {f: len(self.reverse_adjacency[f]) for f in self.files}
+        self.out_degree: dict[str, int] = {f: len(self.adjacency[f]) for f in self.files}
+
+        self.clusters: list[dict[str, Any]] = self._compute_clusters()
+
+    @staticmethod
+    def _resolve_edges(resolver: ImportResolver) -> list[tuple[str, str]]:
+        """
+        The single place import statements become file-to-file edges, shared
+        by a full build (`__init__`) and `snapshot` so the two can never
+        disagree about what an edge is.
+        """
+        edges: list[tuple[str, str]] = []
+        for file_path, res in resolver.files.items():
+            for imp in res.imports:
+                target = resolver.resolve_import_path(file_path, imp)
+                # `resolve_import_path` only ever returns a key already
+                # present in `resolver.files` -- the `in resolver.files`
+                # check is a defensive, explicit restatement of "only
+                # resolved, repository-local imports become edges," not
+                # a case this can actually fail today.
+                if target and target != file_path and target in resolver.files:
+                    edges.append((file_path, target))
+        return edges
+
+    @classmethod
+    def snapshot(
+        cls, parse_results: dict[str, FileParseResult] | list[FileParseResult]
+    ) -> tuple[list[str], list[tuple[str, str]]]:
+        """
+        `(files, edges)` for these parse results: every parsed file
+        (sorted, isolated ones included) and the distinct, sorted
+        `(source_file, target_file)` resolved edges -- WITHOUT computing
+        clusters/degrees. This is what the indexer persists on every run,
+        so it must stay cheap; `from_edges` accepts exactly this pair.
+        """
+        resolver = ImportResolver(parse_results)
+        return sorted(resolver.files.keys()), sorted(set(cls._resolve_edges(resolver)))
+
+    @property
+    def edges(self) -> list[tuple[str, str]]:
+        """Sorted `(source_file, target_file)` pairs; the exact set `from_edges` accepts."""
+        return sorted((src, tgt) for src, targets in self.adjacency.items() for tgt in targets)
+
+    @classmethod
+    def from_edges(cls, files: list[str], edges: list[tuple[str, str]]) -> "ModuleGraphBuilder":
+        """
+        Rebuilds the graph from the persisted node list (every parsed file,
+        including isolated ones) and resolved edges, with no parse results.
+        Every public structure -- adjacency, degrees, clusters, rankings --
+        is identical to a graph built from parse results with the same
+        files and edges (clustering is deterministic for a given graph and
+        seed). An edge naming a file that is not in `files` is ignored,
+        never allowed to invent a node.
+
+        `resolver` is empty on a restored graph; nothing public reads it.
+        """
+        graph = cls([])
+        graph.files = sorted(set(files))
+        known = set(graph.files)
+        graph.adjacency = {f: set() for f in graph.files}
+        graph.reverse_adjacency = {f: set() for f in graph.files}
+        for src, tgt in edges:
+            if src in known and tgt in known and src != tgt:
+                graph.adjacency[src].add(tgt)
+                graph.reverse_adjacency[tgt].add(src)
+        graph.in_degree = {f: len(graph.reverse_adjacency[f]) for f in graph.files}
+        graph.out_degree = {f: len(graph.adjacency[f]) for f in graph.files}
+        graph.clusters = graph._compute_clusters()
+        return graph
+
+    def _compute_clusters(self) -> list[dict[str, Any]]:
+        graph = nx.Graph()
+        graph.add_nodes_from(self.files)
+        for src, targets in self.adjacency.items():
+            for tgt in targets:
+                graph.add_edge(src, tgt)
+
+        raw_communities = nx.algorithms.community.louvain_communities(
+            graph, seed=self._LOUVAIN_SEED
+        )
+
+        # NetworkX's own community container order is arbitrary/internal
+        # -- never used as the public id. Each community's own files are
+        # sorted lexicographically first, then communities themselves
+        # are sorted by (size descending, lexicographically-smallest
+        # member), and only THEN assigned sequential ids in that order,
+        # so the same graph and seed always produce the same clusters in
+        # the same order with the same ids, regardless of container
+        # iteration order.
+        sorted_file_lists = sorted(
+            (sorted(community) for community in raw_communities),
+            key=lambda files: (-len(files), files[0]),
+        )
+        return [{"id": idx, "files": files} for idx, files in enumerate(sorted_file_lists)]
+
+    def rank_by_inbound(self) -> list[dict[str, Any]]:
+        """
+        Raw per-file degree data, sorted by `(-in_degree, out_degree,
+        file_path)` -- roadmap §11's literal "many inbound, few
+        outbound" heuristic reading (files ranked at the top here are
+        what the roadmap describes as looking like APIs/entry points;
+        see this class's own docstring for why that wording is kept
+        exactly as written rather than reversed to match conventional
+        "entry point" intuition). No score, label, or threshold is
+        attached -- only the measured `in_degree`/`out_degree` values.
+        """
+        return [
+            {"file": f, "in_degree": self.in_degree[f], "out_degree": self.out_degree[f]}
+            for f in sorted(self.files, key=lambda f: (-self.in_degree[f], self.out_degree[f], f))
+        ]
+
+    def rank_by_outbound(self) -> list[dict[str, Any]]:
+        """
+        Raw per-file degree data, sorted by `(-out_degree, in_degree,
+        file_path)` -- roadmap §11's literal "many outbound, few
+        inbound" heuristic reading (files ranked at the top here are
+        what the roadmap describes as looking like utility/leaf
+        modules). No score, label, or threshold is attached.
+        """
+        return [
+            {"file": f, "in_degree": self.in_degree[f], "out_degree": self.out_degree[f]}
+            for f in sorted(self.files, key=lambda f: (-self.out_degree[f], self.in_degree[f], f))
+        ]