graphlint 0.1.0__py3-none-any.whl

graphlint/__init__.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+"""graphlint — Code Dependency Graph Analyzer."""
+
+from typing import Any
+
+__version__ = "0.1.0"
+
+__all__ = ["query", "build", "configure", "__version__"]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import public API names."""
+    if name == "query":
+        from graphlint.api import query as _query
+
+        return _query
+    if name == "build":
+        from graphlint.api import build as _build
+
+        return _build
+    if name == "configure":
+        from graphlint.api import configure as _configure
+
+        return _configure
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

graphlint/agent_tools.py

@@ -0,0 +1,263 @@
+# -*- coding: utf-8 -*-
+"""Agent tool integration — install/uninstall graphlint prompts for AI coding tools.
+
+Configures agent tools at the global level so graphlint's usage prompt is
+available in every project the agent opens.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import List, Tuple
+
+AGENT_PROMPT = """# graphlint — Dead Code Detection for Python
+
+## When to Use It
+- **After code modifications**: Run to check if your edits left behind dead or redundant code — components no longer reachable from any entry point
+- **Before analyzing a codebase**: Run to verify the dependency graph is correctly built and all expected entry points are recognized
+
+## Quick Commands
+```bash
+graphlint build --force              # Build/rebuild index (Full codebase scan, time consuming for large codebase)
+graphlint query                      # List dependency graphs (recommanded, auto incremental rebuild)
+graphlint query --json               # JSON output
+graphlint query -g <id> --detail full  # Full detail on one graph
+graphlint config show                # View current config
+```
+
+Use the -h option in each command to query detailed instructions (use only when necessary).
+
+## Key Parameters
+- `-g, --graph-id <int>` — Inspect a specific dependency graph
+- `--json, -j` — Structured output (JSON)
+- `-w, --warn-types <str>` — Filter: `dead_code`, `circular_ref`, `unused_import`
+- `-t, --include-tests` — Include test files in analysis
+- `-d, --detail <level>` — Detail: `auto`/`summary`/`full`/`minimal`
+- `-r, --root-dir <path>` — Project root directory
+- `-C, --exclude-clean` — Show only graphs with issues
+- `-f, --force` — Force full index rebuild
+- `--sort-by <field>` — Sort: `warnings`/`nodes`/`edges`/`name`
+
+## Usage Examples
+```bash
+# Check for dead code after a refactor
+graphlint query --json
+
+# Inspect a specific component's connections
+graphlint query -g 5 -d full
+
+# Scan all warnings sorted by severity
+graphlint query -C --sort-by warnings --json
+```\
+"""
+
+MARKER_START = "<!-- graphlint:start -->"
+MARKER_END = "<!-- graphlint:end -->"
+
+
+def _prompt_block() -> str:
+    return f"\n{MARKER_START}\n{AGENT_PROMPT}\n{MARKER_END}\n"
+
+
+def _expand(path: str) -> str:
+    """Expand ~ to home directory, normalize separators."""
+    return os.path.normpath(os.path.expanduser(path))
+
+
+# Tool definitions: (id, display_name, global_config_path, description)
+# All paths use ~ which is expanded at install/uninstall time.
+TOOLS: List[Tuple[str, str, str, str]] = [
+    (
+        "opencode",
+        "OpenCode CLI",
+        "~/.config/opencode/AGENTS.md",
+        "Global AGENTS.md — read by opencode in every project",
+    ),
+    (
+        "cursor",
+        "Cursor Editor",
+        "~/.cursorrules",
+        "Global .cursorrules — applies to all Cursor projects",
+    ),
+    (
+        "codex",
+        "Codex CLI",
+        "~/.codex/rules/graphlint.md",
+        "Global rules directory — recognized by Codex CLI",
+    ),
+    (
+        "cc",
+        "Claude Code (CLI)",
+        "~/.claude/CLAUDE.md",
+        "Global CLAUDE.md — read by Claude Code in every project",
+    ),
+]
+
+
+def _prompt_installed_in(filepath: str) -> bool:
+    if not os.path.isfile(filepath):
+        return False
+    with open(filepath, encoding="utf-8") as f:
+        return MARKER_START in f.read()
+
+
+def _write_prompt(filepath: str) -> bool:
+    try:
+        os.makedirs(os.path.dirname(filepath), exist_ok=True)
+        if os.path.isfile(filepath) and _prompt_installed_in(filepath):
+            return False
+        block = _prompt_block()
+        if os.path.isfile(filepath):
+            with open(filepath, "a", encoding="utf-8") as f:
+                f.write(block)
+        else:
+            with open(filepath, "w", encoding="utf-8") as f:
+                f.write(block)
+        return True
+    except OSError:
+        return False
+
+
+def _remove_prompt(filepath: str) -> bool:
+    if not os.path.isfile(filepath):
+        return False
+    try:
+        with open(filepath, encoding="utf-8") as f:
+            content = f.read()
+        if MARKER_START not in content:
+            return False
+        start = content.index(MARKER_START)
+        end = content.index(MARKER_END) + len(MARKER_END)
+        new_content = content[:start] + content[end:]
+        lines = new_content.splitlines(keepends=True)
+        cleaned = []
+        prev_empty = False
+        for line in lines:
+            if line.strip() == "":
+                if prev_empty:
+                    continue
+                prev_empty = True
+            else:
+                prev_empty = False
+            cleaned.append(line)
+        while cleaned and cleaned[0].strip() == "":
+            cleaned.pop(0)
+        while cleaned and cleaned[-1].strip() == "":
+            cleaned.pop()
+        new_content = "".join(cleaned)
+        if new_content.strip() == "":
+            os.remove(filepath)
+        else:
+            with open(filepath, "w", encoding="utf-8") as f:
+                f.write(new_content)
+        return True
+    except (OSError, ValueError):
+        return False
+
+
+def _resolve_paths(cwd: str = None) -> List[Tuple[str, str, str, str, str]]:
+    """Resolve tool paths, expanded from ~."""
+    resolved = []
+    for tool_id, display_name, rel_path, desc in TOOLS:
+        full_path = _expand(rel_path)
+        resolved.append((tool_id, display_name, rel_path, full_path, desc))
+    return resolved
+
+
+def _select_tools(message: str, resolved: List[Tuple]) -> List[Tuple]:
+    """Interactive multi-select prompt for agent tools."""
+    print(f"\n{message}\n")
+    for i, (_, display_name, rel_path, full_path, desc) in enumerate(resolved, 1):
+        status = "✓" if os.path.isfile(full_path) else " "
+        print(f"  [{i}] {display_name:<20} {rel_path}")
+        print(f"      {desc}")
+    print()
+    while True:
+        try:
+            raw = input(
+                "Enter numbers separated by comma (e.g. 1,3) or 'all': "
+            ).strip()
+            if raw.lower() == "all":
+                return list(resolved)
+            if not raw:
+                print("No selection. Aborting.")
+                return []
+            indices = [int(x.strip()) for x in raw.split(",")]
+            selected = []
+            for idx in indices:
+                if 1 <= idx <= len(resolved):
+                    selected.append(resolved[idx - 1])
+                else:
+                    print(f"  Invalid number: {idx}")
+                    break
+            else:
+                return selected
+        except (ValueError, KeyboardInterrupt):
+            print("Invalid input. Try again.")
+
+
+def install_tools(cwd: str = None) -> str:
+    """Interactively install graphlint prompt to selected agent tools (global)."""
+    resolved = _resolve_paths(cwd)
+    selected = _select_tools("Select agent tool(s) to install graphlint prompt:", resolved)
+    if not selected:
+        return "No tools selected."
+    results = []
+    for tool_id, display_name, rel_path, full_path, desc in selected:
+        if _write_prompt(full_path):
+            results.append(f"  ✓ {display_name} -> {full_path}")
+        else:
+            if _prompt_installed_in(full_path):
+                results.append(f"  - {display_name} ({rel_path}) — already installed")
+            else:
+                results.append(f"  ✗ {display_name} ({rel_path}) — failed to write")
+    return "Install results:\n" + "\n".join(results)
+
+
+def uninstall_tools(cwd: str = None) -> str:
+    """Interactively uninstall graphlint prompt from selected agent tools."""
+    resolved = _resolve_paths(cwd)
+    installed = [
+        t for t in resolved if _prompt_installed_in(t[3])
+    ]
+    if not installed:
+        return "No agent tools with graphlint prompt found."
+    print("\nDetected installations:\n")
+    for i, (tool_id, display_name, rel_path, full_path, desc) in enumerate(
+        installed, 1
+    ):
+        print(f"  [{i}] {display_name:<20} {rel_path}")
+    print()
+    while True:
+        try:
+            raw = input(
+                "Enter numbers to uninstall (comma separated) or 'all': "
+            ).strip()
+            if raw.lower() == "all":
+                selected = list(installed)
+                break
+            if not raw:
+                print("No selection. Aborting.")
+                return []
+            indices = [int(x.strip()) for x in raw.split(",")]
+            selected = []
+            for idx in indices:
+                if 1 <= idx <= len(installed):
+                    selected.append(installed[idx - 1])
+                else:
+                    print(f"  Invalid number: {idx}")
+                    break
+            else:
+                break
+        except (ValueError, KeyboardInterrupt):
+            print("Invalid input. Try again.")
+    if not selected:
+        return "No tools selected."
+    results = []
+    for tool_id, display_name, rel_path, full_path, desc in selected:
+        if _remove_prompt(full_path):
+            results.append(f"  ✓ {display_name} ({rel_path}) — removed")
+        else:
+            results.append(f"  ✗ {display_name} ({rel_path}) — failed to remove")
+    return "Uninstall results:\n" + "\n".join(results)

graphlint/analyzer/__init__.py

@@ -0,0 +1 @@
+"""AST parsing, dependency graph building, and entry point detection."""

graphlint/analyzer/_ast_visitor.py

@@ -0,0 +1,361 @@
+# -*- coding: utf-8 -*-
+"""AST visitor — traverses AST to extract nodes, imports, and name usages."""
+
+from __future__ import annotations
+
+import ast
+from typing import List, Set
+
+from graphlint.analyzer._types import NodeInfo
+from graphlint.analyzer.decorators import DecoratorResolver
+from graphlint.analyzer.imports import ImportAnalyzer, ImportInfo
+
+
+class ASTVisitor(ast.NodeVisitor):
+    """Custom AST visitor that extracts nodes, imports, and name usages."""
+
+    def __init__(
+        self,
+        module_qualified: str,
+        file_path: str,
+        import_analyzer: ImportAnalyzer,
+        decorator_resolver: DecoratorResolver,
+    ) -> None:
+        """Initialize the AST visitor."""
+        super().__init__()
+        self.module_qualified: str = module_qualified
+        self.file_path: str = file_path
+        self.import_analyzer: ImportAnalyzer = import_analyzer
+        self.decorator_resolver: DecoratorResolver = decorator_resolver
+
+        self.nodes: List[NodeInfo] = []
+        self.imports: List[ImportInfo] = []
+        self.name_usages: Set[str] = set()
+
+        self._context: List[str] = [module_qualified]
+        self._current_class_id: int = 0
+        self._current_func_id: int = 0
+        self._node_id: int = 1
+
+    # ------------------------------------------------------------------
+    # Generic visit
+    # ------------------------------------------------------------------
+
+    def visit(self, node: ast.AST) -> None:
+        """Override visit to gracefully degrade on error."""
+        try:
+            super().visit(node)
+        except Exception as exc:
+            import sys
+
+            print(
+                f"[graphlint] AST visit error in {self.file_path}: {exc}",
+                file=sys.stderr,
+            )
+
+    def generic_visit(self, node: ast.AST) -> None:
+        """Generic visit: collect name usages."""
+        if isinstance(node, ast.Name):
+            if isinstance(node.ctx, ast.Load):
+                self.name_usages.add(node.id)
+        elif isinstance(node, ast.Attribute):
+            self.name_usages.add(node.attr)
+            if isinstance(node.value, ast.Name):
+                self.name_usages.add(node.value.id)
+        super().generic_visit(node)
+
+    # ------------------------------------------------------------------
+    # Import visit
+    # ------------------------------------------------------------------
+
+    def visit_Import(self, node: ast.Import) -> None:
+        """Process import xxx statements."""
+        infos = self.import_analyzer.analyze_import(node)
+        self.imports.extend(infos)
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
+        """Process from xxx import yyy statements."""
+        infos = self.import_analyzer.analyze_import(node)
+        self.imports.extend(infos)
+        self.generic_visit(node)
+
+    # ------------------------------------------------------------------
+    # Class definition
+    # ------------------------------------------------------------------
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        """Process a class definition."""
+        qualified = ".".join(self._context + [node.name])
+        dec_infos = self.decorator_resolver.extract_decorator_names(
+            node.decorator_list, self.module_qualified
+        )
+        dec_names = [d.qualified_name for d in dec_infos]
+        docstring = self._get_docstring(node)
+        is_deprecated, dep_msg = DecoratorResolver.check_deprecated(
+            node.decorator_list, docstring
+        )
+
+        class_node = NodeInfo(
+            file_id=0,
+            name=node.name,
+            qualified_name=qualified,
+            node_type="class",
+            line_start=node.lineno,
+            line_end=node.end_lineno or node.lineno,
+            col_offset=node.col_offset,
+            parent_node_id=0,
+            is_deprecated=is_deprecated,
+            deprecation_msg=dep_msg,
+            type_annotation="",
+            is_async=False,
+            decorators=dec_names,
+            docstring=docstring,
+            is_entry=False,
+        )
+        class_node_id = self._add_node(class_node)
+        prev_class_id = self._current_class_id
+        self._current_class_id = class_node_id
+        self._context.append(node.name)
+
+        for base in node.bases:
+            self.visit(base)
+        for dec in node.decorator_list:
+            self.visit(dec)
+        for item in node.body:
+            self.visit(item)
+
+        self._context.pop()
+        self._current_class_id = prev_class_id
+
+    # ------------------------------------------------------------------
+    # Function definition
+    # ------------------------------------------------------------------
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        """Process a function definition."""
+        self._handle_function(node, is_async=False)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
+        """Process an async function definition."""
+        self._handle_function(node, is_async=True)
+
+    def _handle_function(
+        self, node: ast.FunctionDef | ast.AsyncFunctionDef, is_async: bool
+    ) -> None:
+        """Shared logic for function/method definitions."""
+        is_method = self._current_class_id != 0
+        qualified = ".".join(self._context + [node.name])
+        node_type = "method" if is_method else "function"
+
+        dec_infos = self.decorator_resolver.extract_decorator_names(
+            node.decorator_list, self.module_qualified
+        )
+        dec_names = [d.qualified_name for d in dec_infos]
+        docstring = self._get_docstring(node)
+        is_deprecated, dep_msg = DecoratorResolver.check_deprecated(
+            node.decorator_list, docstring
+        )
+
+        type_ann = ""
+        if node.returns:
+            try:
+                type_ann = ast.unparse(node.returns)
+            except Exception:
+                type_ann = ""
+
+        func_node = NodeInfo(
+            file_id=0,
+            name=node.name,
+            qualified_name=qualified,
+            node_type=node_type,
+            line_start=node.lineno,
+            line_end=node.end_lineno or node.lineno,
+            col_offset=node.col_offset,
+            parent_node_id=self._current_class_id,
+            is_deprecated=is_deprecated,
+            deprecation_msg=dep_msg,
+            type_annotation=type_ann,
+            is_async=is_async,
+            decorators=dec_names,
+            docstring=docstring,
+            is_entry=False,
+        )
+        func_node_id = self._add_node(func_node)
+
+        for dec in node.decorator_list:
+            self.visit(dec)
+        if node.returns:
+            self.visit(node.returns)
+        if hasattr(node, "args") and isinstance(node.args, ast.arguments):
+            for arg in ast.iter_child_nodes(node.args):
+                self.visit(arg)
+
+        prev_class_id = self._current_class_id
+        prev_func_id = self._current_func_id
+        self._current_class_id = 0
+        self._current_func_id = func_node_id
+        self._context.append(node.name)
+        for item in node.body:
+            self.visit(item)
+        self._context.pop()
+        self._current_class_id = prev_class_id
+        self._current_func_id = prev_func_id
+
+    # ------------------------------------------------------------------
+    # Variable / field
+    # ------------------------------------------------------------------
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        """Process assignment statements (module-level or class fields)."""
+        is_class_level = self._current_class_id != 0
+        is_func_level = not is_class_level and self._current_func_id != 0
+        node_type = "field" if is_class_level else "variable"
+        if is_class_level:
+            parent_id = self._current_class_id
+        elif is_func_level:
+            parent_id = self._current_func_id
+        else:
+            parent_id = 0
+
+        for target in node.targets:
+            self._extract_target(target, node_type, parent_id, node)
+
+        self.generic_visit(node)
+
+    def visit_AnnAssign(self, node: ast.AnnAssign) -> None:
+        """Process annotated assignment statements."""
+        if node.target is None:
+            self.generic_visit(node)
+            return
+
+        is_class_level = self._current_class_id != 0
+        is_func_level = not is_class_level and self._current_func_id != 0
+        node_type = "field" if is_class_level else "variable"
+        if is_class_level:
+            parent_id = self._current_class_id
+        elif is_func_level:
+            parent_id = self._current_func_id
+        else:
+            parent_id = 0
+
+        type_ann = ""
+        if node.annotation:
+            try:
+                type_ann = ast.unparse(node.annotation)
+            except Exception:
+                type_ann = ""
+            self.visit(node.annotation)
+
+        self._extract_annotated_target(
+            node.target, node_type, parent_id, node, type_ann
+        )
+        self.generic_visit(node)
+
+    # ------------------------------------------------------------------
+    # Target extraction helpers
+    # ------------------------------------------------------------------
+
+    def _extract_target(
+        self,
+        target: ast.expr,
+        node_type: str,
+        parent_id: int,
+        assign_node: ast.Assign,
+    ) -> None:
+        """Extract variable/field nodes from assignment targets."""
+        if isinstance(target, ast.Name):
+            qualified = ".".join(self._context + [target.id])
+            self._add_node(
+                NodeInfo(
+                    file_id=0,
+                    name=target.id,
+                    qualified_name=qualified,
+                    node_type=node_type,
+                    line_start=assign_node.lineno,
+                    line_end=assign_node.end_lineno or assign_node.lineno,
+                    col_offset=assign_node.col_offset,
+                    parent_node_id=parent_id,
+                )
+            )
+        elif isinstance(target, ast.Attribute):
+            if isinstance(target.value, ast.Attribute):
+                return
+            qualified = ".".join(self._context + [target.attr])
+            self._add_node(
+                NodeInfo(
+                    file_id=0,
+                    name=target.attr,
+                    qualified_name=qualified,
+                    node_type=node_type,
+                    line_start=assign_node.lineno,
+                    line_end=assign_node.end_lineno or assign_node.lineno,
+                    col_offset=assign_node.col_offset,
+                    parent_node_id=parent_id,
+                )
+            )
+        elif isinstance(target, (ast.Tuple, ast.List)):
+            for elt in target.elts:
+                self._extract_target(elt, node_type, parent_id, assign_node)
+
+    def _extract_annotated_target(
+        self,
+        target: ast.expr,
+        node_type: str,
+        parent_id: int,
+        node: ast.AnnAssign,
+        type_ann: str,
+    ) -> None:
+        """Extract nodes from annotated assignment targets."""
+        if isinstance(target, ast.Name):
+            qualified = ".".join(self._context + [target.id])
+            self._add_node(
+                NodeInfo(
+                    file_id=0,
+                    name=target.id,
+                    qualified_name=qualified,
+                    node_type=node_type,
+                    line_start=node.lineno,
+                    line_end=node.end_lineno or node.lineno,
+                    col_offset=node.col_offset,
+                    parent_node_id=parent_id,
+                    type_annotation=type_ann,
+                )
+            )
+        elif isinstance(target, ast.Attribute):
+            if isinstance(target.value, ast.Attribute):
+                return
+            qualified = ".".join(self._context + [target.attr])
+            self._add_node(
+                NodeInfo(
+                    file_id=0,
+                    name=target.attr,
+                    qualified_name=qualified,
+                    node_type=node_type,
+                    line_start=node.lineno,
+                    line_end=node.end_lineno or node.lineno,
+                    col_offset=node.col_offset,
+                    parent_node_id=parent_id,
+                    type_annotation=type_ann,
+                )
+            )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _add_node(self, node: NodeInfo) -> int:
+        """Add a node and return its ID."""
+        node_id = self._node_id
+        self._node_id += 1
+        node.id = node_id
+        self.nodes.append(node)
+        return node_id
+
+    @staticmethod
+    def _get_docstring(node: ast.AST) -> str:
+        """Extract docstring (truncated to 500 chars)."""
+        ds = ast.get_docstring(node) or ""  # type: ignore[arg-type]
+        if len(ds) > 500:
+            ds = ds[:497] + "..."
+        return ds