invar-tools 1.0.0__py3-none-any.whl

invar/core/extraction.py

@@ -0,0 +1,172 @@
+"""Extraction analysis for Guard (Phase 11 P25). No I/O operations.
+
+Analyzes function call relationships to suggest extractable groups
+when files approach size limits.
+"""
+
+from __future__ import annotations
+
+from deal import post, pre
+
+from invar.core.models import FileInfo, Symbol, SymbolKind
+
+
+@pre(lambda funcs: isinstance(funcs, dict))
+@post(lambda result: isinstance(result, dict))
+def _build_call_graph(funcs: dict[str, Symbol]) -> dict[str, set[str]]:
+    """Build bidirectional call graph for function grouping.
+
+    >>> from invar.core.models import Symbol, SymbolKind
+    >>> s = Symbol(name="a", kind=SymbolKind.FUNCTION, line=1, end_line=5, function_calls=["b"])
+    >>> g = _build_call_graph({"a": s})
+    >>> "a" in g
+    True
+    """
+    func_names = set(funcs.keys())
+    graph: dict[str, set[str]] = {name: set() for name in func_names}
+
+    for name, sym in funcs.items():
+        for called in sym.function_calls:
+            if called in func_names:
+                graph[name].add(called)
+                graph[called].add(name)
+    return graph
+
+
+@pre(lambda start, graph, visited: start and isinstance(graph, dict) and start in graph)
+@post(lambda result: isinstance(result, list))
+def _find_connected_component(start: str, graph: dict[str, set[str]], visited: set[str]) -> list[str]:
+    """BFS to find all functions connected to start.
+
+    >>> g = {"a": {"b"}, "b": {"a"}, "c": set()}
+    >>> v = set()
+    >>> _find_connected_component("a", g, v)
+    ['a', 'b']
+    """
+    component: list[str] = []
+    queue = [start]
+    while queue:
+        current = queue.pop(0)
+        if current in visited or current not in graph:
+            continue
+        visited.add(current)
+        component.append(current)
+        queue.extend(n for n in graph[current] if n not in visited)
+    return component
+
+
+@pre(lambda file_info: isinstance(file_info, FileInfo))
+def find_extractable_groups(file_info: FileInfo) -> list[dict]:
+    """
+    Find groups of related functions that could be extracted together.
+
+    Uses function call relationships to identify connected components.
+    Returns groups sorted by total lines (largest first).
+
+    Examples:
+        >>> from invar.core.models import FileInfo, Symbol, SymbolKind
+        >>> s1 = Symbol(name="main", kind=SymbolKind.FUNCTION, line=1, end_line=20,
+        ...     function_calls=["helper"])
+        >>> s2 = Symbol(name="helper", kind=SymbolKind.FUNCTION, line=21, end_line=30,
+        ...     function_calls=[])
+        >>> s3 = Symbol(name="unrelated", kind=SymbolKind.FUNCTION, line=31, end_line=40,
+        ...     function_calls=[])
+        >>> info = FileInfo(path="test.py", lines=40, symbols=[s1, s2, s3])
+        >>> groups = find_extractable_groups(info)
+        >>> len(groups)
+        2
+        >>> sorted(groups[0]["functions"])  # Largest group first
+        ['helper', 'main']
+        >>> groups[0]["lines"]
+        30
+    """
+    funcs = {
+        s.name: s for s in file_info.symbols if s.kind in (SymbolKind.FUNCTION, SymbolKind.METHOD)
+    }
+    if not funcs:
+        return []
+
+    graph = _build_call_graph(funcs)
+    visited: set[str] = set()
+    groups: list[dict] = []
+
+    for name in funcs:
+        if name in visited:
+            continue
+
+        component = _find_connected_component(name, graph, visited)
+        total_lines = sum(funcs[n].end_line - funcs[n].line + 1 for n in component)
+        deps = _get_group_dependencies(component, funcs, file_info.imports)
+
+        groups.append({
+            "functions": sorted(component),
+            "lines": total_lines,
+            "dependencies": sorted(deps),
+        })
+
+    groups.sort(key=lambda g: -g["lines"])
+    return groups
+
+
+@pre(lambda func_names, funcs, file_imports: all(n in funcs for n in func_names if n))
+@post(lambda result: isinstance(result, set))
+def _get_group_dependencies(
+    func_names: list[str],
+    funcs: dict[str, Symbol],
+    file_imports: list[str],
+) -> set[str]:
+    """Get external dependencies used by a group of functions.
+
+    >>> from invar.core.models import Symbol, SymbolKind
+    >>> s = Symbol(name="f", kind=SymbolKind.FUNCTION, line=1, end_line=5, internal_imports=["os"])
+    >>> _get_group_dependencies(["f"], {"f": s}, ["os", "sys"])
+    {'os'}
+    """
+    deps: set[str] = set()
+
+    for name in func_names:
+        if not name or name not in funcs:
+            continue
+        sym = funcs[name]
+        # Add internal imports used by this function
+        deps.update(sym.internal_imports)
+
+    # Filter to only include actual imports from file
+    # (some internal_imports might be from nested scopes)
+    return deps.intersection(set(file_imports)) if file_imports else deps
+
+
+@pre(lambda file_info, max_groups=3: isinstance(file_info, FileInfo))
+def format_extraction_hint(file_info: FileInfo, max_groups: int = 3) -> str:
+    """
+    Format extraction suggestions for file_size_warning.
+
+    P25: Shows extractable function groups with dependencies.
+
+    Examples:
+        >>> from invar.core.models import FileInfo, Symbol, SymbolKind
+        >>> s1 = Symbol(name="parse", kind=SymbolKind.FUNCTION, line=1, end_line=50,
+        ...     function_calls=["validate"], internal_imports=["ast"])
+        >>> s2 = Symbol(name="validate", kind=SymbolKind.FUNCTION, line=51, end_line=80,
+        ...     function_calls=[], internal_imports=["ast"])
+        >>> info = FileInfo(path="test.py", lines=100, symbols=[s1, s2], imports=["ast", "re"])
+        >>> hint = format_extraction_hint(info)
+        >>> "parse, validate" in hint
+        True
+        >>> "(80L)" in hint
+        True
+    """
+    groups = find_extractable_groups(file_info)
+
+    if not groups:
+        return ""
+
+    # Format top N groups
+    hints: list[str] = []
+    for i, group in enumerate(groups[:max_groups]):
+        funcs = ", ".join(group["functions"])
+        lines = group["lines"]
+        deps = ", ".join(group["dependencies"]) if group["dependencies"] else "none"
+        hints.append(f"[{chr(65 + i)}] {funcs} ({lines}L) | Deps: {deps}")
+
+    return "\n".join(hints)

invar/core/formatter.py

@@ -0,0 +1,281 @@
+"""
+Output formatting for Perception (Phase 4) and Guard (Phase 8).
+
+This module provides functions to format perception and guard output.
+Supports both human-readable (Rich) and machine-readable (JSON) formats.
+
+No I/O operations - returns formatted strings/dicts only.
+"""
+
+from __future__ import annotations
+
+from deal import post, pre
+
+from invar.core.models import GuardReport, PerceptionMap, Symbol, SymbolRefs, Violation
+from invar.core.rule_meta import get_rule_meta
+
+
+@pre(lambda perception_map, top_n=0: isinstance(perception_map, PerceptionMap))
+def format_map_text(perception_map: PerceptionMap, top_n: int = 0) -> str:
+    """
+    Format perception map as plain text.
+
+    Args:
+        perception_map: The perception map to format
+        top_n: If > 0, only show top N symbols by reference count
+
+    Examples:
+        >>> from invar.core.models import PerceptionMap
+        >>> pm = PerceptionMap(project_root="/test", total_files=1, total_symbols=0)
+        >>> "Project:" in format_map_text(pm)
+        True
+    """
+    lines: list[str] = []
+    lines.append(f"Project: {perception_map.project_root}")
+    lines.append(f"Files: {perception_map.total_files}")
+    lines.append(f"Symbols: {perception_map.total_symbols}")
+    lines.append("")
+
+    symbols = perception_map.symbols
+    if top_n > 0:
+        symbols = symbols[:top_n]
+
+    if not symbols:
+        lines.append("No symbols found.")
+        return "\n".join(lines)
+
+    # Group by reference count level
+    hot = [s for s in symbols if s.ref_count > 10]
+    warm = [s for s in symbols if 3 <= s.ref_count <= 10]
+    cold = [s for s in symbols if s.ref_count < 3]
+
+    for label, group, level in [
+        ("Hot (refs > 10)", hot, "hot"),
+        ("Warm (refs 3-10)", warm, "warm"),
+        ("Cold (refs < 3)", cold, "cold"),
+    ]:
+        if group:
+            lines.append(f"=== {label} ===")
+            for sr in group:
+                lines.extend(_format_symbol_detail(sr, level=level))
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+@pre(lambda sr, level: isinstance(sr, SymbolRefs) and level in ("hot", "warm", "cold"))
+@post(lambda result: all(isinstance(line, str) for line in result))
+def _format_symbol_detail(sr: SymbolRefs, level: str) -> list[str]:
+    """Format a single symbol with appropriate detail level."""
+    lines: list[str] = []
+    sym = sr.symbol
+    sig = sym.signature or f"({sym.name})"
+
+    if level == "hot":
+        # Full detail: signature + docstring + contracts
+        lines.append(f"  {sr.file_path}::{sym.name}{sig}  [refs: {sr.ref_count}]")
+        if sym.docstring:
+            first_line = sym.docstring.split("\n")[0].strip()
+            if first_line:
+                lines.append(f"    | {first_line}")
+        if sym.contracts:
+            for c in sym.contracts:
+                lines.append(f"    | @{c.kind}: {c.expression}")
+    elif level == "warm":
+        # Medium: signature + contracts summary
+        lines.append(f"  {sr.file_path}::{sym.name}{sig}  [refs: {sr.ref_count}]")
+        if sym.contracts:
+            kinds = [c.kind for c in sym.contracts]
+            lines.append(f"    | contracts: {', '.join(kinds)}")
+    else:
+        # Minimal: name only
+        lines.append(f"  {sr.file_path}::{sym.name}  [refs: {sr.ref_count}]")
+
+    return lines
+
+
+@pre(lambda perception_map, top_n=0: isinstance(perception_map, PerceptionMap) and top_n >= 0)
+def format_map_json(perception_map: PerceptionMap, top_n: int = 0) -> dict:
+    """
+    Format perception map as JSON-serializable dict.
+
+    Args:
+        perception_map: The perception map to format.
+        top_n: Limit to top N symbols by ref_count. 0 means all symbols.
+
+    Examples:
+        >>> from invar.core.models import PerceptionMap
+        >>> pm = PerceptionMap(project_root="/test", total_files=1, total_symbols=0)
+        >>> d = format_map_json(pm)
+        >>> d["project_root"]
+        '/test'
+    """
+    symbols = perception_map.symbols
+    if top_n > 0:
+        symbols = symbols[:top_n]
+    return {
+        "project_root": perception_map.project_root,
+        "total_files": perception_map.total_files,
+        "total_symbols": perception_map.total_symbols,
+        "symbols": [_symbol_refs_to_dict(sr) for sr in symbols],
+    }
+
+
+@pre(lambda sr: isinstance(sr, SymbolRefs))
+@post(lambda result: "name" in result and "ref_count" in result)
+def _symbol_refs_to_dict(sr: SymbolRefs) -> dict:
+    """Convert SymbolRefs to dict."""
+    sym = sr.symbol
+    return {
+        "file": sr.file_path,
+        "name": sym.name,
+        "kind": sym.kind.value,
+        "line": sym.line,
+        "signature": sym.signature,
+        "ref_count": sr.ref_count,
+        "docstring": sym.docstring,
+        "contracts": [{"kind": c.kind, "expression": c.expression} for c in sym.contracts],
+    }
+
+
+@pre(lambda symbol, file_path: isinstance(symbol, Symbol))
+def format_signature(symbol: Symbol, file_path: str) -> str:
+    """
+    Format a single symbol signature.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="foo", kind=SymbolKind.FUNCTION, line=1, end_line=5,
+        ...     signature="(x: int) -> int")
+        >>> format_signature(sym, "test.py")
+        'test.py::foo(x: int) -> int'
+    """
+    sig = symbol.signature or ""
+    return f"{file_path}::{symbol.name}{sig}"
+
+
+@pre(lambda symbols, file_path: isinstance(symbols, list))
+def format_signatures_text(symbols: list[Symbol], file_path: str) -> str:
+    """
+    Format multiple signatures as text.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="foo", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> format_signatures_text([sym], "test.py")
+        'test.py::foo'
+    """
+    lines = [format_signature(sym, file_path) for sym in symbols]
+    return "\n".join(lines)
+
+
+@pre(lambda symbols, file_path: isinstance(symbols, list))
+def format_signatures_json(symbols: list[Symbol], file_path: str) -> dict:
+    """
+    Format signatures as JSON-serializable dict.
+
+    Examples:
+        >>> from invar.core.models import Symbol, SymbolKind
+        >>> sym = Symbol(name="foo", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> d = format_signatures_json([sym], "test.py")
+        >>> d["file"]
+        'test.py'
+    """
+    return {
+        "file": file_path,
+        "symbols": [
+            {
+                "name": sym.name,
+                "kind": sym.kind.value,
+                "line": sym.line,
+                "signature": sym.signature,
+                "docstring": sym.docstring,
+                "contracts": [{"kind": c.kind, "expression": c.expression} for c in sym.contracts],
+            }
+            for sym in symbols
+        ],
+    }
+
+
+# Phase 8.2: Agent-mode formatting
+
+
+@pre(lambda report: isinstance(report, GuardReport))
+def format_guard_agent(report: GuardReport) -> dict:
+    """
+    Format Guard report for Agent consumption (Phase 8.2).
+
+    Provides structured output with actionable fix instructions.
+
+    Examples:
+        >>> from invar.core.models import GuardReport, Violation, Severity
+        >>> report = GuardReport(files_checked=1)
+        >>> v = Violation(rule="missing_contract", severity=Severity.WARNING,
+        ...     file="test.py", line=10, message="Function 'foo' has no contract",
+        ...     suggestion="Add: @pre(lambda x: x >= 0)")
+        >>> report.add_violation(v)
+        >>> d = format_guard_agent(report)
+        >>> d["status"]
+        'passed'
+        >>> len(d["fixes"])
+        1
+    """
+    return {
+        "status": "passed" if report.passed else "failed",
+        "summary": {
+            "files_checked": report.files_checked,
+            "errors": report.errors,
+            "warnings": report.warnings,
+            "infos": report.infos,
+        },
+        "fixes": [_violation_to_fix(v) for v in report.violations],
+    }
+
+
+@pre(lambda v: isinstance(v, Violation))
+def _violation_to_fix(v: Violation) -> dict:
+    """Convert a Violation to an Agent-friendly fix instruction."""
+    fix_info = _parse_suggestion(v.suggestion, v.rule) if v.suggestion else None
+
+    # Phase 9.2 P3: Include rule metadata
+    result: dict = {
+        "file": v.file,
+        "line": v.line,
+        "rule": v.rule,
+        "severity": v.severity.value,
+        "message": v.message,
+        "fix": fix_info,
+    }
+
+    meta = get_rule_meta(v.rule)
+    if meta:
+        result["rule_meta"] = {
+            "category": meta.category.value,
+            "detects": meta.detects,
+            "cannot_detect": list(meta.cannot_detect),
+            "hint": meta.hint,
+        }
+
+    return result
+
+
+@pre(lambda suggestion, rule: suggestion is None or isinstance(suggestion, str))
+def _parse_suggestion(suggestion: str | None, rule: str) -> dict | None:
+    """Parse suggestion string into structured fix instruction."""
+    if not suggestion:
+        return None
+
+    # Parse "Add: @pre(...)" style suggestions
+    if suggestion.startswith("Add: "):
+        return {"action": "add_decorator", "code": suggestion[5:]}
+
+    # Parse "Replace with: @pre(...)" style suggestions
+    if suggestion.startswith("Replace with: "):
+        return {"action": "replace_decorator", "code": suggestion[14:]}
+
+    # Parse "Replace with business logic: @pre(...)" style
+    if suggestion.startswith("Replace with business logic: "):
+        return {"action": "replace_decorator", "code": suggestion[29:]}
+
+    # Default: return as instruction text
+    return {"action": "manual", "instruction": suggestion}