dotscope 0.1.0__py3-none-any.whl

dotscope/passes/backtest.py

@@ -0,0 +1,198 @@
+"""Scope backtesting: validate generated scopes against actual git history.
+
+Replays recent commits and measures whether each scope's includes would have
+covered the files that were actually changed. Self-corrects by suggesting
+missing includes.
+"""
+
+import os
+import subprocess
+from collections import defaultdict
+from typing import Dict, List, Set
+
+from ..models import (
+    BacktestReport,
+    BacktestResult,
+    MissingSuggestion,
+    ScopeConfig,
+)
+from ..resolver import resolve
+
+
+def backtest_scopes(
+    root: str,
+    scopes: List[ScopeConfig],
+    n_commits: int = 50,
+) -> BacktestReport:
+    """Validate scopes against git history.
+
+    For each recent commit, check whether the matched scope's resolved
+    file list would have included all changed files.
+    """
+    commits = _get_recent_commits(root, n_commits)
+    if not commits:
+        return BacktestReport()
+
+    # Resolve each scope to its file set, keyed by relative directory name
+    scope_file_sets: Dict[str, Set[str]] = {}
+    scope_dirs: Dict[str, ScopeConfig] = {}
+
+    for scope in scopes:
+        resolved = resolve(scope, follow_related=False, root=root)
+        rel_dir = os.path.relpath(scope.directory, root)
+        scope_file_sets[rel_dir] = set(resolved.files)
+        scope_dirs[rel_dir] = scope
+
+    # Track per-scope results
+    scope_commits: Dict[str, int] = defaultdict(int)
+    scope_covered: Dict[str, int] = defaultdict(int)
+    scope_misses: Dict[str, Dict[str, int]] = defaultdict(lambda: defaultdict(int))
+
+    for commit_files in commits:
+        # Match commit to scope(s) by directory prefix
+        matched_scopes = _match_commit_to_scopes(commit_files, scope_dirs, root)
+
+        for scope_dir in matched_scopes:
+            scope_commits[scope_dir] += 1
+            file_set = scope_file_sets.get(scope_dir, set())
+
+            all_covered = True
+            for changed_file in commit_files:
+                abs_changed = os.path.join(root, changed_file)
+                if abs_changed not in file_set:
+                    all_covered = False
+                    scope_misses[scope_dir][changed_file] += 1
+
+            if all_covered:
+                scope_covered[scope_dir] += 1
+
+    # Build results
+    results = []
+    for scope in scopes:
+        d = os.path.relpath(scope.directory, root)
+        total = scope_commits.get(d, 0)
+        covered = scope_covered.get(d, 0)
+        recall = covered / total if total > 0 else 1.0
+
+        misses = []
+        for path, count in sorted(
+            scope_misses.get(d, {}).items(), key=lambda x: -x[1]
+        ):
+            if count >= 2:  # Only suggest files that appear multiple times
+                misses.append(MissingSuggestion(
+                    path=path,
+                    appearances=count,
+                    would_improve_recall=True,
+                ))
+
+        results.append(BacktestResult(
+            scope_path=scope.path,
+            total_commits=total,
+            fully_covered=covered,
+            recall=round(recall, 3),
+            missing_includes=misses[:10],
+        ))
+
+    total_commits = len(commits)
+    total_covered = sum(r.fully_covered for r in results)
+    total_matched = sum(r.total_commits for r in results)
+    overall_recall = total_covered / total_matched if total_matched > 0 else 1.0
+
+    return BacktestReport(
+        results=results,
+        total_commits=total_commits,
+        overall_recall=round(overall_recall, 3),
+    )
+
+
+def auto_correct_scope(
+    scope: ScopeConfig,
+    result: BacktestResult,
+    root: str,
+    min_appearances: int = 3,
+) -> tuple[ScopeConfig, bool]:
+    """Auto-correct a scope's includes based on backtest results.
+
+    Returns (updated_scope, changed) tuple.
+    """
+    changed = False
+    for suggestion in result.missing_includes:
+        if suggestion.appearances >= min_appearances and suggestion.would_improve_recall:
+            if suggestion.path not in scope.includes:
+                scope.includes.append(suggestion.path)
+                changed = True
+    return scope, changed
+
+
+def format_backtest_report(report: BacktestReport) -> str:
+    """Human-readable backtest report."""
+    lines = [
+        f"Backtest: {report.total_commits} commits analyzed",
+        f"Overall recall: {report.overall_recall:.0%}",
+        "",
+    ]
+
+    for result in report.results:
+        scope_name = os.path.basename(os.path.dirname(result.scope_path))
+        recall_bar = "█" * int(result.recall * 10) + "░" * (10 - int(result.recall * 10))
+        lines.append(
+            f"  {scope_name}/.scope — recall: {recall_bar} {result.recall:.0%} "
+            f"({result.fully_covered}/{result.total_commits} commits)"
+        )
+
+        for miss in result.missing_includes[:5]:
+            lines.append(f"    missing: {miss.path} (appeared in {miss.appearances} commits)")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+def _get_recent_commits(root: str, n: int) -> List[List[str]]:
+    """Get file lists from recent commits."""
+    if not os.path.isdir(os.path.join(root, ".git")):
+        return []
+
+    try:
+        result = subprocess.run(
+            ["git", "log", f"--max-count={n}", "--pretty=format:%H", "--name-only"],
+            cwd=root, capture_output=True, text=True, timeout=15,
+        )
+        if result.returncode != 0:
+            return []
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return []
+
+    commits = []
+    current_files = []
+
+    for line in result.stdout.splitlines():
+        if len(line) == 40 and " " not in line:  # Commit hash
+            if current_files:
+                commits.append(current_files)
+                current_files = []
+        elif line.strip():
+            current_files.append(line.strip())
+
+    if current_files:
+        commits.append(current_files)
+
+    return commits
+
+
+def _match_commit_to_scopes(
+    commit_files: List[str],
+    scope_dirs: Dict[str, ScopeConfig],
+    root: str,
+) -> Set[str]:
+    """Match a commit's changed files to relevant scopes."""
+    matched = set()
+    for changed_file in commit_files:
+        parts = changed_file.split("/")
+        if len(parts) > 1:
+            top_dir = parts[0]
+            if top_dir in scope_dirs:
+                matched.add(top_dir)
+    return matched

dotscope/passes/budget_allocator.py

@@ -0,0 +1,164 @@
+"""Token budgeting: rank files, fill to budget, progressive loading.
+
+Context is always included first. Then files are ranked and loaded
+until the budget is exhausted.
+"""
+
+
+from typing import List, Optional
+
+from ..models import ResolvedScope
+from ..tokens import estimate_file_tokens, estimate_context_tokens
+
+
+def apply_budget(
+    resolved: ResolvedScope,
+    max_tokens: int,
+    task: Optional[str] = None,
+    utility_scores: Optional[dict] = None,
+    required_files: Optional[set] = None,
+) -> ResolvedScope:
+    """Apply a token budget to a resolved scope.
+
+    Algorithm:
+    1. Reserve tokens for context (always included)
+    2. Rank files by relevance tier and size, weighted by utility
+    3. Fill files until budget is exhausted
+    4. Set truncated=True if files were dropped
+
+    Args:
+        resolved: The fully resolved scope
+        max_tokens: Maximum total tokens (context + files)
+        task: Optional task description for relevance ranking
+        utility_scores: Historical file utility data from observations
+    """
+    if max_tokens <= 0:
+        return ResolvedScope(
+            files=[],
+            context=resolved.context,
+            token_estimate=estimate_context_tokens(resolved.context),
+            scope_chain=resolved.scope_chain,
+            truncated=True,
+        )
+
+    # Context always goes first
+    context_tokens = estimate_context_tokens(resolved.context)
+    remaining = max_tokens - context_tokens
+
+    if remaining <= 0:
+        # Budget only fits context (or not even that)
+        return ResolvedScope(
+            files=[],
+            context=resolved.context[:max_tokens * 4],  # rough trim
+            token_estimate=max_tokens,
+            scope_chain=resolved.scope_chain,
+            truncated=True,
+        )
+
+    # Rank and score files (utility data flows through when available)
+    scored_files = _rank_files(resolved.files, task, utility_scores)
+
+    # Required files get infinite utility — selected first, unconditionally
+    required = required_files or set()
+    if required:
+        scored_files = _boost_required(scored_files, required)
+
+    # Fill within budget
+    selected_files: List[str] = []
+    total_file_tokens = 0
+
+    for path, score in scored_files:
+        file_tokens = estimate_file_tokens(path)
+        if total_file_tokens + file_tokens <= remaining:
+            selected_files.append(path)
+            total_file_tokens += file_tokens
+        elif path in required:
+            # Required file doesn't fit — hard error
+            from ..assertions import ContextExhaustionError
+            raise ContextExhaustionError(
+                assertion_type="ensure_includes",
+                detail=f"Budget ({max_tokens}) cannot fit required file: {path} ({file_tokens} tokens)",
+                file=path,
+                file_tokens=file_tokens,
+                budget=max_tokens,
+                tokens_used=context_tokens + total_file_tokens,
+                suggestion=f"Increase budget to at least {context_tokens + total_file_tokens + file_tokens}",
+            )
+        # Don't break early — a smaller file later might still fit
+
+    truncated = len(selected_files) < len(resolved.files)
+
+    return ResolvedScope(
+        files=selected_files,
+        context=resolved.context,
+        token_estimate=context_tokens + total_file_tokens,
+        scope_chain=resolved.scope_chain,
+        truncated=truncated,
+        excluded_files=[f for f in resolved.files if f not in set(selected_files)],
+    )
+
+
+def _rank_files(
+    files: List[str],
+    task: Optional[str] = None,
+    utility_scores: Optional[dict] = None,
+) -> List[tuple]:
+    """Rank files by relevance, layering historical utility over static heuristics."""
+    import os
+    from ..utility import effective_score as _effective_score
+
+    task_words = set()
+    if task:
+        task_words = {w.lower() for w in task.split() if len(w) > 2}
+
+    scored = []
+    for path in files:
+        score = 1.0
+        basename = os.path.basename(path).lower()
+        rel_parts = path.lower().split(os.sep)
+
+        if any(p in ("tests", "test", "fixtures", "migrations", "__pycache__") for p in rel_parts):
+            score *= 0.5
+
+        if basename.endswith((".generated.py", ".generated.ts", ".lock", ".min.js")):
+            score *= 0.3
+
+        if task_words:
+            name_words = set(
+                w for w in basename.replace("_", " ").replace("-", " ").replace(".", " ").split()
+                if len(w) > 2
+            )
+            overlap = len(task_words & name_words)
+            if overlap:
+                score *= 1.0 + (overlap * 0.5)
+
+        tokens = estimate_file_tokens(path)
+        if tokens > 0:
+            if tokens < 200:
+                score *= 1.2
+            elif tokens > 2000:
+                score *= 0.8
+
+        # Layer utility data on top of heuristics
+        utility = utility_scores.get(path) if utility_scores else None
+        score = _effective_score(score, utility, is_explicit_include=True)
+
+        scored.append((path, score, tokens))
+
+    scored.sort(key=lambda x: (-x[1], x[2]))
+    return [(path, score) for path, score, _ in scored]
+
+
+def _boost_required(
+    scored_files: List[tuple],
+    required: set,
+) -> List[tuple]:
+    """Boost required files to infinite utility so they're selected first."""
+    boosted = []
+    for path, score in scored_files:
+        if path in required:
+            boosted.append((path, float("inf")))
+        else:
+            boosted.append((path, score))
+    boosted.sort(key=lambda x: -x[1])
+    return boosted

dotscope/passes/convention_compliance.py

@@ -0,0 +1,40 @@
+"""Convention compliance: track how well conventions are followed."""
+
+from typing import Dict, List
+
+from ..models import ConventionNode, ConventionRule, FileAnalysis
+from .convention_parser import matches_convention
+
+
+def compute_compliance(
+    convention: ConventionRule,
+    nodes: List[ConventionNode],
+    ast_data: Dict[str, FileAnalysis],
+) -> float:
+    """What percentage of matching files follow all rules?"""
+    matching_files = [
+        path for path, analysis in ast_data.items()
+        if matches_convention(analysis, path, convention.match_criteria)
+    ]
+    if not matching_files:
+        return 1.0
+
+    compliant = sum(
+        1 for n in nodes
+        if n.name == convention.name and not n.violations
+    )
+    return compliant / len(matching_files)
+
+
+def convention_severity(compliance: float) -> str:
+    """Map compliance ratio to enforcement severity.
+
+    100-80%: nudge (course correction)
+    79-50%:  note (informational)
+    <50%:    retired (not enforced)
+    """
+    if compliance >= 0.80:
+        return "nudge"
+    if compliance >= 0.50:
+        return "note"
+    return "retired"

dotscope/passes/convention_discovery.py

@@ -0,0 +1,247 @@
+"""Convention discovery: mine structural patterns from AST data."""
+
+import os
+import re
+from collections import defaultdict
+from typing import Dict, List, Optional, Set, Tuple
+
+from ..models import ConventionRule, DependencyGraph, FileAnalysis, HistoryAnalysis
+
+
+def discover_conventions(
+    ast_data: Dict[str, FileAnalysis],
+    graph: DependencyGraph,
+    history: Optional[HistoryAnalysis] = None,
+) -> List[ConventionRule]:
+    """Mine structural patterns that repeat across files.
+
+    Uses multi-pass clustering to avoid grouping only by directory:
+      Pass 1: Group by shared decorators (e.g., all @app.route files)
+      Pass 2: Group by shared base classes (e.g., all BaseModel subclasses)
+      Pass 3: Group by shared suffix/prefix (e.g., *_repo.py)
+
+    Cross-cutting conventions (decorator-based, base-class-based) are
+    discovered before directory-based ones. A file can match multiple
+    passes — deduplication happens after all passes complete.
+    """
+    conventions = []
+    claimed_files: Set[str] = set()
+
+    # Pass 1: Shared decorators (strongest signal, survives refactors)
+    decorator_groups: Dict[str, List[Tuple[str, FileAnalysis]]] = defaultdict(list)
+    for path, analysis in ast_data.items():
+        for dec in (analysis.decorators_used or []):
+            normalized = _normalize_decorator(dec)
+            decorator_groups[normalized].append((path, analysis))
+
+    for dec, files in decorator_groups.items():
+        if len(files) >= 3:
+            conv = _build_convention_from_group(
+                files, graph, signal_type="decorator", signal_value=dec
+            )
+            if conv:
+                conventions.append(conv)
+                claimed_files.update(f[0] for f in files)
+
+    # Pass 2: Shared base classes
+    base_groups: Dict[str, List[Tuple[str, FileAnalysis]]] = defaultdict(list)
+    for path, analysis in ast_data.items():
+        if path in claimed_files:
+            continue
+        for cls in (analysis.classes or []):
+            for base in (cls.bases or []):
+                base_groups[base].append((path, analysis))
+
+    for base, files in base_groups.items():
+        if len(files) >= 3:
+            conv = _build_convention_from_group(
+                files, graph, signal_type="base_class", signal_value=base
+            )
+            if conv:
+                conventions.append(conv)
+                claimed_files.update(f[0] for f in files)
+
+    # Pass 3: Shared suffix/prefix (weakest signal, path-dependent)
+    suffix_groups: Dict[str, List[Tuple[str, FileAnalysis]]] = defaultdict(list)
+    for path, analysis in ast_data.items():
+        if path in claimed_files:
+            continue
+        stem = os.path.splitext(os.path.basename(path))[0]
+        for suffix in _extract_suffixes(stem):
+            suffix_groups[suffix].append((path, analysis))
+
+    for suffix, files in suffix_groups.items():
+        if len(files) >= 3:
+            conv = _build_convention_from_group(
+                files, graph, signal_type="suffix", signal_value=suffix
+            )
+            if conv:
+                conventions.append(conv)
+
+    return conventions
+
+
+def _normalize_decorator(dec: str) -> str:
+    """Normalize a decorator string for grouping.
+
+    '@app.route("/users")' -> 'app.route'
+    '@router.get' -> 'router.get'
+    """
+    dec = dec.lstrip("@")
+    # Strip arguments
+    paren = dec.find("(")
+    if paren != -1:
+        dec = dec[:paren]
+    return dec.strip()
+
+
+def _extract_suffixes(stem: str) -> List[str]:
+    """Extract meaningful suffixes from a filename stem.
+
+    "user_controller" -> ["_controller"]
+    "billing_repo" -> ["_repo"]
+    """
+    known = (
+        "_controller", "_service", "_repo", "_repository",
+        "_handler", "_manager", "_factory", "_helper",
+        "_view", "_model", "_test", "_middleware",
+    )
+    result = []
+    for suffix in known:
+        if stem.endswith(suffix):
+            result.append(suffix)
+    return result
+
+
+def _build_convention_from_group(
+    files: List[Tuple[str, FileAnalysis]],
+    graph: DependencyGraph,
+    signal_type: str,
+    signal_value: str,
+) -> Optional[ConventionRule]:
+    """Build a ConventionRule from a group of files sharing a structural trait."""
+    paths = [f[0] for f in files]
+    analyses = [f[1] for f in files]
+
+    match_criteria = _derive_match_criteria(paths, analyses, signal_type, signal_value)
+    if not match_criteria:
+        return None
+
+    rules = _derive_rules(paths, analyses, graph)
+    name = _derive_name(signal_type, signal_value)
+
+    return ConventionRule(
+        name=name,
+        source="discovered",
+        match_criteria=match_criteria,
+        rules=rules,
+        description=f"Discovered from {len(files)} files sharing {signal_type}: {signal_value}",
+        compliance=1.0,
+    )
+
+
+def _derive_name(signal_type: str, signal_value: str) -> str:
+    """Generate a human-readable convention name."""
+    if signal_type == "decorator":
+        # "@app.route" -> "Route Handler"
+        parts = signal_value.split(".")
+        name = parts[-1] if parts else signal_value
+        return name.replace("_", " ").title()
+    elif signal_type == "base_class":
+        return f"{signal_value} Subclass"
+    elif signal_type == "suffix":
+        # "_controller" -> "Controller"
+        return signal_value.lstrip("_").replace("_", " ").title()
+    return signal_value
+
+
+def _derive_match_criteria(
+    paths: List[str],
+    analyses: List[FileAnalysis],
+    signal_type: str,
+    signal_value: str,
+) -> dict:
+    """Find common structural traits across files sharing a fingerprint."""
+    any_of = []
+    all_of = []
+
+    # Primary signal goes into any_of
+    if signal_type == "decorator":
+        any_of.append({"has_decorator": re.escape(signal_value)})
+    elif signal_type == "base_class":
+        any_of.append({"base_class": signal_value})
+    elif signal_type == "suffix":
+        pattern = f".*{re.escape(signal_value)}\\.py"
+        any_of.append({"file_path": pattern})
+
+    # Common directory as secondary hint
+    dirs = set(os.path.dirname(p) for p in paths)
+    if len(dirs) == 1:
+        dir_pattern = re.escape(dirs.pop()) + "/.*\\.py"
+        any_of.append({"file_path": dir_pattern})
+
+    criteria = {}
+    if any_of:
+        criteria["any_of"] = any_of
+    if all_of:
+        criteria["all_of"] = all_of
+    return criteria
+
+
+def _derive_rules(
+    paths: List[str],
+    analyses: List[FileAnalysis],
+    graph: DependencyGraph,
+) -> dict:
+    """Find universal behavioral patterns (potential rules)."""
+    rules = {}
+
+    # Universal methods (all files implement these)
+    if all(a.classes for a in analyses):
+        all_methods = [
+            set(a.classes[0].methods)
+            for a in analyses if a.classes
+        ]
+        if all_methods:
+            common_methods = set.intersection(*all_methods)
+            required = sorted(m for m in common_methods if not m.startswith("_"))
+            if required:
+                rules["required_methods"] = required
+
+    # Universal non-imports (no file imports these)
+    all_imports: Set[str] = set()
+    for a in analyses:
+        for imp in (a.imports or []):
+            if imp.module:
+                all_imports.add(imp.module)
+
+    # Check against all imports in codebase to find conspicuous absences
+    all_codebase_imports: Set[str] = set()
+    for node in graph.files.values():
+        for imp_path in (node.imports or []):
+            # Extract module name from path
+            module = os.path.splitext(os.path.basename(imp_path))[0] if imp_path else ""
+            if module:
+                all_codebase_imports.add(module)
+
+    common_absences = all_codebase_imports - all_imports
+    if common_absences:
+        frequent_elsewhere = [
+            imp for imp in common_absences
+            if _import_frequency(imp, graph) >= 3
+        ]
+        if frequent_elsewhere:
+            rules["prohibited_imports"] = sorted(frequent_elsewhere[:5])
+
+    return rules
+
+
+def _import_frequency(module: str, graph: DependencyGraph) -> int:
+    """Count how many files import a given module."""
+    count = 0
+    for node in graph.files.values():
+        for imp_path in (node.imports or []):
+            if module in imp_path:
+                count += 1
+                break
+    return count