devcouncil 0.3.0 → 0.4.0

package/src/devcouncil/indexing/graph/okf_export.py

@@ -0,0 +1,65 @@
+"""Compatibility facade for code-graph OKF export.
+
+Prefers the shared implementation in :mod:`devcouncil.indexing.graph.export`
+and re-exports helpers used by wiki link conventions.
+
+devcouncil: allow-unwired — thin re-export surface; callers use graph.export directly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List
+
+from devcouncil.indexing.graph.export import (
+    build_code_graph_okf,
+    export_graphml,
+    file_doc_rel,
+    write_code_graph_okf,
+)
+from devcouncil.indexing.graph.export_links import (
+    GRAPH_FROM_WIKI,
+    WIKI_FROM_GRAPH,
+    cross_bundle_file_link,
+    file_doc_path,
+    relative_md_link,
+    slugify_area,
+    subsystem_doc_path,
+    wired_to_bullets,
+)
+from devcouncil.indexing.graph.schema import CodeGraph
+
+# Public aliases matching the Phase-7 plan names
+build_graph_okf_bundle = build_code_graph_okf
+graph_to_graphml = export_graphml
+
+
+def export_graph_okf(
+    graph: CodeGraph,
+    out_dir: Path,
+    *,
+    root: Path | None = None,
+    project_name: str = "Code Graph",
+) -> List[Path]:
+    """Write an OKF v0.1 bundle for ``graph`` under ``out_dir``."""
+    base = root or Path(".")
+    _out, written = write_code_graph_okf(
+        base, out_dir, graph=graph, project_name=project_name
+    )
+    return written
+
+
+__all__ = [
+    "GRAPH_FROM_WIKI",
+    "WIKI_FROM_GRAPH",
+    "build_graph_okf_bundle",
+    "cross_bundle_file_link",
+    "export_graph_okf",
+    "file_doc_path",
+    "file_doc_rel",
+    "graph_to_graphml",
+    "relative_md_link",
+    "slugify_area",
+    "subsystem_doc_path",
+    "wired_to_bullets",
+]

package/src/devcouncil/indexing/graph/pdg/__init__.py

@@ -0,0 +1,67 @@
+"""Program dependence graph (PDG) layer — CFG, reaching-def, CDG, taint."""
+
+from __future__ import annotations
+
+from devcouncil.indexing.graph.pdg.build import (
+    build_pdg_for_paths,
+    load_pdg_layer,
+    merge_pdg_into_graph,
+)
+from devcouncil.indexing.graph.pdg.cdg import build_cdg
+from devcouncil.indexing.graph.pdg.cfg import CFGResult, block_for_line, build_cfg_for_function
+from devcouncil.indexing.graph.pdg.reaching_def import (
+    BlockDefUse,
+    block_def_use,
+    compute_reaching_defs,
+)
+from devcouncil.indexing.graph.pdg.schema import (
+    PDG_VERSION,
+    BasicBlock,
+    CDGEdge,
+    CFGEdge,
+    DataDepEdge,
+    FilePDG,
+    FunctionPDG,
+    PDGLayer,
+    TaintCategory,
+    TaintFinding,
+)
+from devcouncil.indexing.graph.pdg.taint import analyze_taint
+from devcouncil.indexing.graph.pdg.query import (
+    explain_pdg_taint,
+    explain_taint,
+    query_controls,
+    query_flows,
+    query_pdg_controls,
+    query_pdg_flows,
+)
+
+__all__ = [
+    "PDG_VERSION",
+    "BasicBlock",
+    "BlockDefUse",
+    "CDGEdge",
+    "CFGEdge",
+    "CFGResult",
+    "DataDepEdge",
+    "FilePDG",
+    "FunctionPDG",
+    "PDGLayer",
+    "TaintCategory",
+    "TaintFinding",
+    "analyze_taint",
+    "block_def_use",
+    "block_for_line",
+    "build_cdg",
+    "build_cfg_for_function",
+    "build_pdg_for_paths",
+    "compute_reaching_defs",
+    "explain_pdg_taint",
+    "explain_taint",
+    "load_pdg_layer",
+    "merge_pdg_into_graph",
+    "query_controls",
+    "query_flows",
+    "query_pdg_controls",
+    "query_pdg_flows",
+]

package/src/devcouncil/indexing/graph/pdg/build.py

@@ -0,0 +1,11 @@
+"""Thin re-export of PDG build helpers (see graph.build)."""
+
+from __future__ import annotations
+
+from devcouncil.indexing.graph.build import (
+    build_pdg_for_paths,
+    load_pdg_layer,
+    merge_pdg_into_graph,
+)
+
+__all__ = ["build_pdg_for_paths", "load_pdg_layer", "merge_pdg_into_graph"]

package/src/devcouncil/indexing/graph/pdg/cdg.py

@@ -0,0 +1,41 @@
+"""Control-dependence graph from CFG branch structure (MVP)."""
+
+from __future__ import annotations
+
+import ast
+from typing import List, Set
+
+from devcouncil.indexing.graph.pdg.cfg import CFGResult
+from devcouncil.indexing.graph.pdg.schema import BasicBlock, CDGEdge
+
+
+def _is_guard_block(block: BasicBlock) -> bool:
+    text = block.text.strip()
+    return text.startswith("return") or text.startswith("raise")
+
+
+def build_cdg(cfg: CFGResult, func_node: ast.AST) -> List[CDGEdge]:
+    """Build CDG edges from branch terminators to dependent blocks."""
+    del func_node  # reserved for richer branch conditions
+    cdg: List[CDGEdge] = []
+    seen: Set[tuple[str, str, str]] = set()
+    branch_kinds = {"true", "false", "loop", "exception"}
+    for edge in cfg.edges:
+        if edge.kind not in branch_kinds:
+            continue
+        branch = "T" if edge.kind in {"true", "loop"} else "F"
+        key = (edge.source, edge.target, branch)
+        if key in seen:
+            continue
+        seen.add(key)
+        dependent = next((b for b in cfg.blocks if b.id == edge.target), None)
+        guard = bool(dependent and _is_guard_block(dependent))
+        cdg.append(
+            CDGEdge(
+                controller=edge.source,
+                dependent=edge.target,
+                branch=branch,
+                guard=guard,
+            )
+        )
+    return cdg

package/src/devcouncil/indexing/graph/pdg/cfg.py

@@ -0,0 +1,199 @@
+"""Python AST control-flow graph builder (intra-procedural MVP)."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set, Tuple
+
+from devcouncil.indexing.graph.pdg.schema import BasicBlock, CFGEdge
+
+
+@dataclass
+class CFGResult:
+    blocks: List[BasicBlock] = field(default_factory=list)
+    edges: List[CFGEdge] = field(default_factory=list)
+    entry: str = ""
+    exits: List[str] = field(default_factory=list)
+    block_by_line: Dict[int, str] = field(default_factory=dict)
+
+
+def _block_id(path: str, qualname: str, start_line: int, index: int) -> str:
+    return f"{path}::{qualname}:{start_line}:bb{index}"
+
+
+def _stmt_lines(stmts: List[ast.stmt]) -> Tuple[int, int]:
+    lines: List[int] = []
+    for stmt in stmts:
+        if hasattr(stmt, "lineno"):
+            lines.append(int(stmt.lineno))
+        if hasattr(stmt, "end_lineno") and stmt.end_lineno:
+            lines.append(int(stmt.end_lineno))
+    if not lines:
+        return 0, 0
+    return min(lines), max(lines)
+
+
+def _first_line(node: ast.AST, default: int = 0) -> int:
+    return int(getattr(node, "lineno", default) or default)
+
+
+def _is_leader(stmt: ast.stmt) -> bool:
+    return isinstance(
+        stmt,
+        (ast.If, ast.While, ast.For, ast.AsyncFor, ast.Try, ast.Return, ast.Raise, ast.Break, ast.Continue),
+    )
+
+
+class _CFGBuilder:
+    def __init__(self, path: str, qualname: str, source_lines: List[str]) -> None:
+        self.path = path
+        self.qualname = qualname
+        self.source_lines = source_lines
+        self.blocks: List[BasicBlock] = []
+        self.edges: List[CFGEdge] = []
+        self._index = 0
+        self.block_by_line: Dict[int, str] = {}
+        self.exits: Set[str] = set()
+
+    def _new_block(self, stmts: List[ast.stmt]) -> str:
+        start, end = _stmt_lines(stmts)
+        if not start and self.blocks:
+            start = self.blocks[-1].end_line or self.blocks[-1].start_line
+            end = start
+        bid = _block_id(self.path, self.qualname, start or 1, self._index)
+        self._index += 1
+        text_lines: List[str] = []
+        line_nums: List[int] = []
+        for stmt in stmts:
+            ln = _first_line(stmt)
+            if ln:
+                line_nums.append(ln)
+                if 0 < ln <= len(self.source_lines):
+                    text_lines.append(self.source_lines[ln - 1].rstrip())
+        block = BasicBlock(
+            id=bid,
+            start_line=start or 1,
+            end_line=end or start or 1,
+            text="\n".join(text_lines),
+            lines=line_nums,
+        )
+        self.blocks.append(block)
+        for ln in line_nums:
+            self.block_by_line.setdefault(ln, bid)
+        return bid
+
+    def _connect(self, source: Optional[str], target: Optional[str], kind: str = "fallthrough") -> None:
+        if source and target and source != target:
+            self.edges.append(CFGEdge(source=source, target=target, kind=kind))
+
+    def _build_stmts(self, stmts: List[ast.stmt], *, after: Optional[str] = None) -> Tuple[Optional[str], List[str]]:
+        if not stmts:
+            return after, []
+        current_after = after
+        pending_exits: List[str] = []
+        i = 0
+        while i < len(stmts):
+            group: List[ast.stmt] = []
+            while i < len(stmts) and not _is_leader(stmts[i]):
+                group.append(stmts[i])
+                i += 1
+            block_id: Optional[str] = None
+            if group:
+                block_id = self._new_block(group)
+                self._connect(current_after, block_id)
+                current_after = block_id
+            if i >= len(stmts):
+                break
+            stmt = stmts[i]
+            i += 1
+            if isinstance(stmt, (ast.Return, ast.Raise)):
+                term = block_id or current_after or self._new_block([stmt])
+                ln = _first_line(stmt)
+                if ln:
+                    self.block_by_line[ln] = term
+                self.exits.add(term)
+                current_after = None
+            elif isinstance(stmt, ast.If):
+                test_block = block_id or current_after or self._new_block([stmt])
+                then_end, then_exits = self._build_stmts(stmt.body)
+                else_end, else_exits = self._build_stmts(stmt.orelse) if stmt.orelse else (test_block, [])
+                merge = self._new_block([])
+                if then_end:
+                    self._connect(then_end, merge)
+                    self._connect(test_block, then_end, "true")
+                else:
+                    self._connect(test_block, merge, "true")
+                if stmt.orelse:
+                    if else_end:
+                        self._connect(else_end, merge)
+                        self._connect(test_block, else_end, "false")
+                    else:
+                        self._connect(test_block, merge, "false")
+                else:
+                    self._connect(test_block, merge, "false")
+                pending_exits.extend(then_exits + else_exits)
+                current_after = merge
+            elif isinstance(stmt, (ast.While, ast.For, ast.AsyncFor)):
+                loop_header = block_id or current_after or self._new_block([stmt])
+                body_end, body_exits = self._build_stmts(stmt.body)
+                if body_end:
+                    self._connect(body_end, loop_header, "loop")
+                after_loop = self._new_block([])
+                self._connect(loop_header, after_loop, "false")
+                pending_exits.extend(body_exits)
+                current_after = after_loop
+            elif isinstance(stmt, ast.Try):
+                _ = block_id or current_after or self._new_block([stmt])
+                try_end, try_exits = self._build_stmts(stmt.body)
+                join = self._new_block([])
+                if try_end:
+                    self._connect(try_end, join)
+                for handler in stmt.handlers:
+                    h_end, h_exits = self._build_stmts(handler.body)
+                    if h_end:
+                        self._connect(h_end, join, "exception")
+                    pending_exits.extend(h_exits)
+                pending_exits.extend(try_exits)
+                current_after = join
+            else:
+                group2 = [stmt]
+                while i < len(stmts) and not _is_leader(stmts[i]):
+                    group2.append(stmts[i])
+                    i += 1
+                bid2 = self._new_block(group2)
+                self._connect(current_after, bid2)
+                current_after = bid2
+        return current_after, pending_exits
+
+    def build(self, body: List[ast.stmt]) -> CFGResult:
+        entry = self._new_block([])
+        end, exits = self._build_stmts(body, after=entry)
+        if end:
+            self.exits.add(end)
+        self.exits.update(exits)
+        return CFGResult(
+            blocks=self.blocks,
+            edges=self.edges,
+            entry=entry,
+            exits=sorted(self.exits),
+            block_by_line=self.block_by_line,
+        )
+
+
+def build_cfg_for_function(
+    path: str,
+    qualname: str,
+    node: ast.AST,
+    source_lines: List[str],
+) -> CFGResult:
+    body: List[ast.stmt] = []
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        body = list(node.body)
+    elif isinstance(node, ast.Module):
+        body = list(node.body)
+    return _CFGBuilder(path, qualname, source_lines).build(body)
+
+
+def block_for_line(cfg: CFGResult, line: int) -> Optional[str]:
+    return cfg.block_by_line.get(line)

package/src/devcouncil/indexing/graph/pdg/query.py

@@ -0,0 +1,21 @@
+"""Thin re-export of PDG query helpers (see graph.query)."""
+
+from __future__ import annotations
+
+from devcouncil.indexing.graph.query import (
+    explain_pdg_taint,
+    explain_taint,
+    query_controls,
+    query_flows,
+    query_pdg_controls,
+    query_pdg_flows,
+)
+
+__all__ = [
+    "explain_pdg_taint",
+    "explain_taint",
+    "query_controls",
+    "query_flows",
+    "query_pdg_controls",
+    "query_pdg_flows",
+]

package/src/devcouncil/indexing/graph/pdg/reaching_def.py

@@ -0,0 +1,126 @@
+"""Reaching-definitions analysis on a CFG."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Set, Tuple
+
+from devcouncil.indexing.graph.pdg.cfg import CFGResult
+from devcouncil.indexing.graph.pdg.schema import DataDepEdge
+
+
+@dataclass
+class BlockDefUse:
+    gen: Set[Tuple[str, int]] = field(default_factory=set)
+    kill: Set[str] = field(default_factory=set)
+    use: Set[Tuple[str, int]] = field(default_factory=set)
+
+
+def _store_target(node: ast.AST) -> str | None:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return None
+
+
+class _DefUseVisitor(ast.NodeVisitor):
+    def __init__(self, block_lines: Set[int]) -> None:
+        self.block_lines = block_lines
+        self.gen: Set[Tuple[str, int]] = set()
+        self.kill: Set[str] = set()
+        self.use: Set[Tuple[str, int]] = set()
+
+    def _in_block(self, node: ast.AST) -> bool:
+        ln = getattr(node, "lineno", None)
+        return ln is not None and int(ln) in self.block_lines
+
+    def visit_Name(self, node: ast.Name) -> None:
+        if not self._in_block(node):
+            return
+        if isinstance(node.ctx, ast.Load):
+            self.use.add((node.id, int(node.lineno)))
+        elif isinstance(node.ctx, ast.Store):
+            self.gen.add((node.id, int(node.lineno)))
+            self.kill.add(node.id)
+
+    def visit_Attribute(self, node: ast.Attribute) -> None:
+        if isinstance(node.ctx, ast.Load) and self._in_block(node):
+            self.use.add((node.attr, int(node.lineno)))
+        self.generic_visit(node)
+
+    def visit_arg(self, node: ast.arg) -> None:
+        if node.lineno in self.block_lines:
+            self.gen.add((node.arg, int(node.lineno)))
+
+
+def block_def_use(node: ast.AST, block_lines: Iterable[int]) -> BlockDefUse:
+    lines = set(block_lines)
+    visitor = _DefUseVisitor(lines)
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        for arg in node.args.args + node.args.kwonlyargs:
+            if arg.lineno in lines:
+                visitor.gen.add((arg.arg, int(arg.lineno)))
+        for d in node.args.defaults + node.args.kw_defaults:
+            if d is not None:
+                visitor.visit(d)
+        visitor.visit(node)
+    else:
+        visitor.visit(node)
+    return BlockDefUse(gen=visitor.gen, kill=visitor.kill, use=visitor.use)
+
+
+def compute_reaching_defs(
+    cfg: CFGResult,
+    func_node: ast.AST,
+) -> List[DataDepEdge]:
+    """Iterative reaching-definitions; emit def->use edges."""
+    block_map = {b.id: set(b.lines) for b in cfg.blocks}
+    in_sets: Dict[str, Set[Tuple[str, int]]] = {b.id: set() for b in cfg.blocks}
+    out_sets: Dict[str, Set[Tuple[str, int]]] = {b.id: set() for b in cfg.blocks}
+    du: Dict[str, BlockDefUse] = {}
+    for block in cfg.blocks:
+        du[block.id] = block_def_use(func_node, block_map[block.id])
+
+    preds: Dict[str, Set[str]] = {b.id: set() for b in cfg.blocks}
+    for edge in cfg.edges:
+        preds.setdefault(edge.target, set()).add(edge.source)
+
+    changed = True
+    while changed:
+        changed = False
+        for block in cfg.blocks:
+            bid = block.id
+            new_in: Set[Tuple[str, int]] = set()
+            for pred in preds.get(bid, set()):
+                new_in |= out_sets.get(pred, set())
+            if new_in != in_sets[bid]:
+                in_sets[bid] = new_in
+                changed = True
+            gen = du[bid].gen
+            kill = du[bid].kill
+            new_out = (new_in - {(v, ln) for v, ln in new_in if v in kill}) | gen
+            if new_out != out_sets[bid]:
+                out_sets[bid] = new_out
+                changed = True
+
+    edges: List[DataDepEdge] = []
+    for block in cfg.blocks:
+        bid = block.id
+        reaching = in_sets[bid] | du[bid].gen
+        for var, use_line in du[bid].use:
+            for def_var, def_line in reaching:
+                if def_var == var and def_line <= use_line:
+                    def_block = cfg.block_by_line.get(def_line, bid)
+                    use_block = cfg.block_by_line.get(use_line, bid)
+                    edges.append(
+                        DataDepEdge(
+                            variable=var,
+                            def_line=def_line,
+                            use_line=use_line,
+                            def_block=def_block,
+                            use_block=use_block,
+                        )
+                    )
+    return edges