invar-tools 1.0.0__py3-none-any.whl

invar/core/references.py

@@ -0,0 +1,180 @@
+"""
+Reference counting for Perception (Phase 4).
+
+This module provides functions to count cross-file symbol references.
+Analyzes AST to find Name, Call, and Attribute nodes that reference known symbols.
+
+No I/O operations - receives parsed data only.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections import defaultdict
+
+from deal import post, pre
+
+from invar.core.models import FileInfo, PerceptionMap, SymbolKind, SymbolRefs
+
+
+@pre(lambda source, known_symbols: isinstance(source, str) and len(source) > 0)
+@post(lambda result: isinstance(result, list))
+def find_references_in_source(source: str, known_symbols: set[str]) -> list[tuple[str, int]]:
+    """
+    Find references to known symbols in source code.
+
+    Returns list of (symbol_name, line_number) for each reference found.
+    Deduplicates: each (symbol, line) pair counted once.
+
+    Examples:
+        >>> refs = find_references_in_source("x = foo()\\nbar(x)", {"foo", "bar"})
+        >>> sorted(refs)
+        [('bar', 2), ('foo', 1)]
+        >>> find_references_in_source("x = unknown()", {"foo"})
+        []
+    """
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, TypeError, ValueError):
+        return []
+
+    seen: set[tuple[str, int]] = set()
+
+    for node in ast.walk(tree):
+        # Count function calls: foo()
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+            name = node.func.id
+            if name in known_symbols:
+                line = getattr(node, "lineno", 0)
+                seen.add((name, line))
+
+    return list(seen)
+
+
+@pre(lambda file_infos: isinstance(file_infos, list))
+@post(lambda result: isinstance(result, dict))
+def build_symbol_table(file_infos: list[FileInfo]) -> dict[str, str]:
+    """
+    Build a mapping of symbol names to their defining file.
+
+    Returns dict of {symbol_name: file_path}.
+
+    Examples:
+        >>> from invar.core.models import FileInfo, Symbol, SymbolKind
+        >>> sym = Symbol(name="foo", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> info = FileInfo(path="core/calc.py", lines=10, symbols=[sym])
+        >>> table = build_symbol_table([info])
+        >>> table["foo"]
+        'core/calc.py'
+    """
+    symbol_table: dict[str, str] = {}
+
+    for file_info in file_infos:
+        for symbol in file_info.symbols:
+            if symbol.kind in (SymbolKind.FUNCTION, SymbolKind.CLASS):
+                # Use simple name (may have collisions, that's OK for now)
+                symbol_table[symbol.name] = file_info.path
+
+    return symbol_table
+
+
+@pre(lambda file_infos, sources: isinstance(file_infos, list))
+def count_cross_file_references(
+    file_infos: list[FileInfo], sources: dict[str, str]
+) -> dict[str, int]:
+    """
+    Count cross-file references for all symbols.
+
+    Returns dict of {"file::symbol": reference_count}.
+    Only counts references from OTHER files (excludes self-references).
+
+    Examples:
+        >>> from invar.core.models import FileInfo, Symbol, SymbolKind
+        >>> sym = Symbol(name="foo", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> info = FileInfo(path="a.py", lines=10, symbols=[sym])
+        >>> sources = {"a.py": "def foo(): pass", "b.py": "foo()"}
+        >>> info2 = FileInfo(path="b.py", lines=5, symbols=[])
+        >>> refs = count_cross_file_references([info, info2], sources)
+        >>> refs.get("a.py::foo", 0)
+        1
+    """
+    # Build symbol table: name -> defining file
+    symbol_table = build_symbol_table(file_infos)
+    known_symbols = set(symbol_table.keys())
+
+    # Count references from each file
+    ref_counts: dict[str, int] = defaultdict(int)
+
+    for file_info in file_infos:
+        source = sources.get(file_info.path, "")
+        if not source:
+            continue
+
+        references = find_references_in_source(source, known_symbols)
+
+        for symbol_name, _ in references:
+            defining_file = symbol_table.get(symbol_name)
+            if defining_file and defining_file != file_info.path:
+                # Cross-file reference: increment count
+                key = f"{defining_file}::{symbol_name}"
+                ref_counts[key] += 1
+
+    return dict(ref_counts)
+
+
+@pre(lambda file_infos, sources, project_root: (
+    isinstance(file_infos, list) and
+    isinstance(project_root, str) and len(project_root) > 0
+))
+def build_perception_map(
+    file_infos: list[FileInfo], sources: dict[str, str], project_root: str
+) -> PerceptionMap:
+    """
+    Build complete perception map with reference counts.
+
+    Examples:
+        >>> from invar.core.models import FileInfo, Symbol, SymbolKind
+        >>> sym = Symbol(name="foo", kind=SymbolKind.FUNCTION, line=1, end_line=5)
+        >>> info = FileInfo(path="a.py", lines=10, symbols=[sym])
+        >>> pm = build_perception_map([info], {"a.py": "def foo(): pass"}, "/test")
+        >>> pm.total_symbols
+        1
+    """
+    ref_counts = count_cross_file_references(file_infos, sources)
+
+    # Build SymbolRefs list
+    symbol_refs: list[SymbolRefs] = []
+    total_symbols = 0
+
+    for file_info in file_infos:
+        for symbol in file_info.symbols:
+            if symbol.kind in (SymbolKind.FUNCTION, SymbolKind.CLASS):
+                key = f"{file_info.path}::{symbol.name}"
+                count = ref_counts.get(key, 0)
+                symbol_refs.append(
+                    SymbolRefs(
+                        symbol=symbol,
+                        file_path=file_info.path,
+                        ref_count=count,
+                    )
+                )
+                total_symbols += 1
+
+    # Sort by reference count (descending)
+    symbol_refs.sort(key=lambda sr: sr.ref_count, reverse=True)
+
+    try:
+        return PerceptionMap(
+            project_root=project_root,
+            total_files=len(file_infos),
+            total_symbols=total_symbols,
+            symbols=symbol_refs,
+        )
+    except Exception:
+        # Handle CrossHair symbolic value validation failures
+        return PerceptionMap(
+            project_root="",
+            total_files=0,
+            total_symbols=0,
+            symbols=[],
+        )

invar/core/rule_meta.py

@@ -0,0 +1,203 @@
+"""
+Centralized rule metadata for Guard rules.
+
+Phase 9.2 P3: Single source of truth for rule information.
+Used by: hints (P5), --agent output, invar rules command.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from deal import post
+
+from invar.core.models import Severity
+
+
+class RuleCategory(str, Enum):
+    """Categories for grouping rules."""
+
+    SIZE = "size"
+    CONTRACTS = "contracts"
+    PURITY = "purity"
+    SHELL = "shell"
+    DOCS = "docs"
+
+
+@dataclass(frozen=True)
+class RuleMeta:
+    """
+    Metadata for a Guard rule.
+
+    Examples:
+        >>> meta = RULE_META["file_size"]
+        >>> meta.category
+        <RuleCategory.SIZE: 'size'>
+        >>> "Split" in meta.hint
+        True
+    """
+
+    name: str
+    severity: Severity
+    category: RuleCategory
+    detects: str
+    cannot_detect: tuple[str, ...]
+    hint: str
+
+
+# All rule metadata definitions
+RULE_META: dict[str, RuleMeta] = {
+    # Size rules
+    "file_size": RuleMeta(
+        name="file_size",
+        severity=Severity.ERROR,
+        category=RuleCategory.SIZE,
+        detects="File exceeds max_file_lines limit",
+        cannot_detect=("Code complexity", "Logical cohesion", "Coupling between modules"),
+        hint="Split into smaller modules by responsibility",
+    ),
+    "file_size_warning": RuleMeta(
+        name="file_size_warning",
+        severity=Severity.WARNING,
+        category=RuleCategory.SIZE,
+        detects="File approaching max_file_lines limit (80% threshold)",
+        cannot_detect=("Whether split is actually needed",),
+        hint="Consider splitting before reaching limit",
+    ),
+    "function_size": RuleMeta(
+        name="function_size",
+        severity=Severity.WARNING,
+        category=RuleCategory.SIZE,
+        detects="Function exceeds max_function_lines limit",
+        cannot_detect=("Algorithm complexity", "Whether extraction helps readability"),
+        hint="Extract helper functions or simplify logic",
+    ),
+    # Contract rules
+    "missing_contract": RuleMeta(
+        name="missing_contract",
+        severity=Severity.ERROR,
+        category=RuleCategory.CONTRACTS,
+        detects="Core function without @pre or @post decorator",
+        cannot_detect=("Contract quality", "Whether contract is meaningful"),
+        hint="Ask: what inputs are invalid? what does output guarantee?",
+    ),
+    "empty_contract": RuleMeta(
+        name="empty_contract",
+        severity=Severity.ERROR,
+        category=RuleCategory.CONTRACTS,
+        detects="Contract with tautology like @pre(lambda: True)",
+        cannot_detect=("Subtle tautologies", "Semantic correctness"),
+        hint="Replace lambda: True with actual constraint on inputs/output",
+    ),
+    "redundant_type_contract": RuleMeta(
+        name="redundant_type_contract",
+        severity=Severity.INFO,
+        category=RuleCategory.CONTRACTS,
+        detects="Contract only checks types already in annotations",
+        cannot_detect=("Whether better constraints exist",),
+        hint="Add value constraints beyond type checks if possible",
+    ),
+    "param_mismatch": RuleMeta(
+        name="param_mismatch",
+        severity=Severity.ERROR,
+        category=RuleCategory.CONTRACTS,
+        detects="@pre lambda parameters don't match function signature",
+        cannot_detect=("Runtime binding errors",),
+        hint="Lambda must accept ALL function parameters (include defaults like x=10)",
+    ),
+    "must_use_ignored": RuleMeta(
+        name="must_use_ignored",
+        severity=Severity.WARNING,
+        category=RuleCategory.CONTRACTS,
+        detects="Return value of @must_use function is ignored",
+        cannot_detect=("Cross-module must_use", "Dynamic function references"),
+        hint="Assign or use the return value - it may contain errors or resources",
+    ),
+    # Purity rules
+    "forbidden_import": RuleMeta(
+        name="forbidden_import",
+        severity=Severity.ERROR,
+        category=RuleCategory.PURITY,
+        detects="Core module imports I/O libraries (os, sys, pathlib, etc.)",
+        cannot_detect=("Transitive imports", "Dynamic imports"),
+        hint="Move I/O operations to Shell layer",
+    ),
+    "internal_import": RuleMeta(
+        name="internal_import",
+        severity=Severity.WARNING,
+        category=RuleCategory.PURITY,
+        detects="Import statement inside function body",
+        cannot_detect=("Lazy imports for performance", "Circular import workarounds"),
+        hint="Move import to module top-level or justify with comment",
+    ),
+    "impure_call": RuleMeta(
+        name="impure_call",
+        severity=Severity.ERROR,
+        category=RuleCategory.PURITY,
+        detects="Call to impure function (datetime.now, random.*, print, open)",
+        cannot_detect=("Custom impure functions", "Impurity via method calls"),
+        hint="Inject impure values as parameters or move to Shell",
+    ),
+    # Shell rules
+    "shell_result": RuleMeta(
+        name="shell_result",
+        severity=Severity.WARNING,
+        category=RuleCategory.SHELL,
+        detects="Shell function not returning Result[T, E]",
+        cannot_detect=("Result usage correctness", "Error handling quality"),
+        hint="Wrap return value with Success() or return Failure()",
+    ),
+    # Documentation rules
+    "missing_doctest": RuleMeta(
+        name="missing_doctest",
+        severity=Severity.WARNING,
+        category=RuleCategory.DOCS,
+        detects="Core function without doctest examples",
+        cannot_detect=("Doctest quality", "Edge case coverage"),
+        hint="Add >>> examples showing typical usage and edge cases",
+    ),
+}
+
+
+@post(lambda result: result is None or isinstance(result, RuleMeta))
+def get_rule_meta(rule_name: str) -> RuleMeta | None:
+    """
+    Get metadata for a rule by name.
+
+    Examples:
+        >>> meta = get_rule_meta("file_size")
+        >>> meta is not None
+        True
+        >>> get_rule_meta("nonexistent") is None
+        True
+    """
+    return RULE_META.get(rule_name)
+
+
+@post(lambda result: len(result) > 0)
+def get_all_rule_names() -> list[str]:
+    """
+    Get list of all rule names.
+
+    Examples:
+        >>> names = get_all_rule_names()
+        >>> "file_size" in names
+        True
+        >>> len(names) >= 10
+        True
+    """
+    return list(RULE_META.keys())
+
+
+@post(lambda result: isinstance(result, list))
+def get_rules_by_category(category: RuleCategory) -> list[RuleMeta]:
+    """
+    Get all rules in a category.
+
+    Examples:
+        >>> size_rules = get_rules_by_category(RuleCategory.SIZE)
+        >>> len(size_rules) >= 2
+        True
+    """
+    return [meta for meta in RULE_META.values() if meta.category == category]