dotscope 0.1.0__py3-none-any.whl

dotscope/composer.py

@@ -0,0 +1,147 @@
+"""Scope composition algebra.
+
+Supports expressions like:
+    auth+payments     — merge (union of files, concatenate context)
+    auth-tests        — subtract (remove files matching subtracted scope)
+    auth&api          — intersect (only files in both)
+    auth@context      — modifier (context only, no files)
+
+Operators bind left-to-right, no precedence. @ is a suffix modifier.
+"""
+
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Optional
+
+from .discovery import find_scope, find_repo_root
+from .models import ResolvedScope
+from .resolver import resolve
+from .tokens import estimate_scope_tokens, estimate_context_tokens
+
+
+class Op(Enum):
+    MERGE = "+"
+    SUBTRACT = "-"
+    INTERSECT = "&"
+
+
+@dataclass
+class ScopeRef:
+    """A reference to a scope with optional modifier."""
+    name: str
+    context_only: bool = False
+
+
+@dataclass
+class ScopeOp:
+    """An operation in a scope expression."""
+    operator: Optional[Op]  # None for the first operand
+    ref: ScopeRef
+
+
+def parse_expression(expr: str) -> List[ScopeOp]:
+    """Parse a scope expression into a list of operations.
+
+    Examples:
+        "auth"              → [ScopeOp(None, ScopeRef("auth"))]
+        "auth+payments"     → [ScopeOp(None, "auth"), ScopeOp(MERGE, "payments")]
+        "auth-tests"        → [ScopeOp(None, "auth"), ScopeOp(SUBTRACT, "tests")]
+        "auth@context"      → [ScopeOp(None, ScopeRef("auth", context_only=True))]
+    """
+    expr = expr.strip()
+    if not expr:
+        raise ValueError("Empty scope expression")
+
+    # Tokenize on operators, keeping the operators
+    tokens = re.split(r"([+\-&])", expr)
+    tokens = [t.strip() for t in tokens if t.strip()]
+
+    ops: List[ScopeOp] = []
+    current_op: Optional[Op] = None
+
+    for token in tokens:
+        if token in ("+", "-", "&"):
+            current_op = Op(token)
+        else:
+            ref = _parse_ref(token)
+            ops.append(ScopeOp(operator=current_op, ref=ref))
+            current_op = None
+
+    if not ops:
+        raise ValueError(f"Invalid scope expression: {expr}")
+
+    return ops
+
+
+def _parse_ref(token: str) -> ScopeRef:
+    """Parse a scope reference, handling @modifier."""
+    if "@" in token:
+        name, modifier = token.split("@", 1)
+        if modifier == "context":
+            return ScopeRef(name=name, context_only=True)
+        else:
+            raise ValueError(f"Unknown modifier @{modifier}. Supported: @context")
+    return ScopeRef(name=token)
+
+
+def compose(
+    expr: str,
+    root: Optional[str] = None,
+    follow_related: bool = True,
+) -> ResolvedScope:
+    """Resolve a scope expression to a ResolvedScope.
+
+    This is the main entry point for scope composition.
+    """
+    if root is None:
+        root = find_repo_root()
+    if root is None:
+        raise ValueError("Could not find repository root. No .scopes, .git, or .scope found.")
+
+    ops = parse_expression(expr)
+    result: Optional[ResolvedScope] = None
+
+    for op in ops:
+        # Resolve the scope reference
+        config = find_scope(op.ref.name, root)
+        if config is None:
+            # Lazy ingest: generate scope on demand
+            from .passes.lazy import lazy_ingest_module
+            config = lazy_ingest_module(root, op.ref.name)
+            if config is None:
+                raise ValueError(f"Scope not found: {op.ref.name}")
+
+        resolved = resolve(config, follow_related=follow_related, root=root)
+
+        # Apply @context modifier
+        if op.ref.context_only:
+            resolved = ResolvedScope(
+                files=[],
+                context=resolved.context,
+                token_estimate=estimate_context_tokens(resolved.context),
+                scope_chain=resolved.scope_chain,
+                truncated=False,
+            )
+
+        # Apply operator
+        if result is None:
+            result = resolved
+        elif op.operator == Op.MERGE:
+            result = result.merge(resolved)
+        elif op.operator == Op.SUBTRACT:
+            result = result.subtract(resolved)
+            # Recalculate tokens after subtraction
+            result.token_estimate = (
+                estimate_scope_tokens(result.files)
+                + estimate_context_tokens(result.context)
+            )
+        elif op.operator == Op.INTERSECT:
+            result = result.intersect(resolved)
+            result.token_estimate = (
+                estimate_scope_tokens(result.files)
+                + estimate_context_tokens(result.context)
+            )
+
+    return result or ResolvedScope()

dotscope/constants.py

@@ -0,0 +1,45 @@
+"""Shared constants — single source of truth for all modules."""
+
+# Directories to always skip when walking a codebase
+SKIP_DIRS = frozenset({
+    ".git",
+    "node_modules",
+    "__pycache__",
+    "venv",
+    ".venv",
+    "env",
+    ".env",
+    "dist",
+    "build",
+    ".tox",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".eggs",
+    ".pytest_cache",
+})
+
+# Source file extensions
+SOURCE_EXTS = frozenset({
+    ".py", ".js", ".ts", ".tsx", ".jsx",
+    ".go", ".rs", ".rb", ".java", ".kt",
+    ".swift", ".c", ".cpp", ".cs", ".php",
+})
+
+# Extension → language name
+LANG_MAP = {
+    ".py": "Python",
+    ".js": "JavaScript",
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".jsx": "JavaScript",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".rb": "Ruby",
+    ".java": "Java",
+    ".kt": "Kotlin",
+    ".swift": "Swift",
+    ".c": "C",
+    ".cpp": "C++",
+    ".cs": "C#",
+    ".php": "PHP",
+}

dotscope/context.py

@@ -0,0 +1,60 @@
+"""Structured context parsing and querying.
+
+Convention: ## Section Name headers within a context block create named sections.
+Agents can query specific sections (e.g., "gotchas", "invariants").
+"""
+
+
+import re
+from typing import Optional
+
+from .models import StructuredContext
+
+
+def parse_context(raw: str) -> StructuredContext:
+    """Parse a context string into a StructuredContext with optional sections.
+
+    Sections are delimited by ## headers within the context block:
+        ## Invariants
+        Some invariant text...
+
+        ## Gotchas
+        Watch out for...
+
+    If no ## headers are found, the entire string is the raw context with no sections.
+    """
+    if not raw or not raw.strip():
+        return StructuredContext(raw="", sections={})
+
+    raw = raw.strip()
+    sections: dict[str, str] = {}
+
+    # Split on ## headers
+    parts = re.split(r"^##\s+(.+)$", raw, flags=re.MULTILINE)
+
+    # parts[0] is text before any header (preamble)
+    # Then alternating: header_name, content, header_name, content, ...
+    if len(parts) <= 1:
+        # No sections found — the whole thing is raw context
+        return StructuredContext(raw=raw, sections={})
+
+    preamble = parts[0].strip()
+    i = 1
+    while i < len(parts) - 1:
+        section_name = parts[i].strip()
+        section_content = parts[i + 1].strip()
+        sections[section_name] = section_content
+        i += 2
+
+    # If there's a preamble, add it as a special section
+    if preamble:
+        sections["_preamble"] = preamble
+
+    return StructuredContext(raw=raw, sections=sections)
+
+
+def query_context(ctx: Optional[StructuredContext], section: Optional[str] = None) -> str:
+    """Query context, optionally filtering to a named section."""
+    if ctx is None:
+        return ""
+    return ctx.query(section)

dotscope/counterfactual.py

@@ -0,0 +1,180 @@
+"""Counterfactual detection: what didn't happen because dotscope was there.
+
+Three sources:
+1. Anti-patterns avoided (from near-miss data)
+2. Contracts honored (agent modified both sides of a coupled pair)
+3. Intents respected (agent didn't violate declared architectural direction)
+
+Only surfaces counterfactuals where the constraint was in the resolve response
+the agent received. Coincidences don't count.
+"""
+
+import re
+from typing import Dict, List, Optional, Set
+
+from .models.state import Counterfactual  # noqa: F401
+
+
+def compute_counterfactuals(
+    constraints_served: List[dict],
+    modified_files: Set[str],
+    diff_text: str,
+    near_misses: Optional[List] = None,
+    invariants: Optional[dict] = None,
+    intents: Optional[list] = None,
+) -> List[Counterfactual]:
+    """Compute what dotscope prevented during this session.
+
+    Args:
+        constraints_served: Constraints the agent received via resolve_scope
+        modified_files: Files the agent actually modified
+        diff_text: Combined diff of all commits in this session
+        near_misses: Near-miss detections from observation
+        invariants: Cached invariants (contracts, stabilities)
+        intents: Architectural intents
+    """
+    results: List[Counterfactual] = []
+
+    # 1. Anti-patterns avoided (from near-miss data)
+    if near_misses:
+        for nm in near_misses:
+            event = nm.get("event", "") if isinstance(nm, dict) else getattr(nm, "event", "")
+            scope = nm.get("scope", "") if isinstance(nm, dict) else getattr(nm, "scope", "")
+            if event:
+                results.append(Counterfactual(
+                    type="anti_pattern_avoided",
+                    description=event,
+                    source=f"{scope} scope context" if scope else "scope context",
+                    severity="high",
+                ))
+
+    # 2. Contracts honored — agent modified both sides of a coupled pair
+    if invariants and modified_files:
+        served_contracts = _extract_served_contracts(constraints_served)
+        for contract in invariants.get("contracts", []):
+            trigger = contract.get("trigger_file", "")
+            coupled = contract.get("coupled_file", "")
+            confidence = contract.get("confidence", 0.0)
+
+            if confidence < 0.65:
+                continue
+
+            # Both modified AND the contract was in the constraints the agent saw
+            if (trigger in modified_files
+                    and coupled in modified_files
+                    and _contract_was_served(trigger, coupled, served_contracts)):
+                results.append(Counterfactual(
+                    type="contract_honored",
+                    description=f"Agent included {coupled} alongside {trigger}",
+                    source=f"implicit contract ({confidence:.0%} co-change)",
+                    severity="high",
+                ))
+
+    # 3. Intents respected — agent didn't violate declared direction
+    if intents and modified_files and diff_text:
+        served_intents = _extract_served_intents(constraints_served)
+        for intent in intents:
+            if not isinstance(intent, dict):
+                directive = getattr(intent, "directive", "")
+                modules = getattr(intent, "modules", [])
+            else:
+                directive = intent.get("directive", "")
+                modules = intent.get("modules", [])
+
+            if directive != "decouple" or len(modules) < 2:
+                continue
+
+            # Was this intent served to the agent?
+            if not _intent_was_served(directive, modules, served_intents):
+                continue
+
+            # Did the agent touch either module without new coupling?
+            touched_modules = set()
+            for f in modified_files:
+                for m in modules:
+                    if f.startswith(m):
+                        touched_modules.add(m)
+
+            if len(touched_modules) >= 1 and not _has_new_coupling(modules, diff_text):
+                mod_str = " and ".join(m.rstrip("/") for m in modules)
+                results.append(Counterfactual(
+                    type="intent_respected",
+                    description=f"Agent avoided new coupling between {mod_str}",
+                    source=f"intent: decouple {' '.join(modules)}",
+                    severity="medium",
+                ))
+
+    return results
+
+
+def format_counterfactuals_terminal(counterfactuals: List[Counterfactual]) -> str:
+    """Format counterfactuals for terminal display."""
+    if not counterfactuals:
+        return ""
+
+    lines = ["", "  What dotscope prevented:"]
+    for cf in counterfactuals:
+        lines.append(f"    {cf.description}")
+        lines.append(f"      <- {cf.source}")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+def _extract_served_contracts(constraints: List[dict]) -> List[dict]:
+    """Extract contract constraints from what was served."""
+    return [c for c in constraints if c.get("category") == "contract"]
+
+
+def _extract_served_intents(constraints: List[dict]) -> List[dict]:
+    """Extract intent constraints from what was served."""
+    return [c for c in constraints if c.get("category") == "intent"]
+
+
+def _contract_was_served(
+    trigger: str, coupled: str, served: List[dict]
+) -> bool:
+    """Check if a specific contract was in the served constraints."""
+    for c in served:
+        msg = c.get("message", "")
+        if trigger in msg and coupled in msg:
+            return True
+        if coupled in msg and trigger in msg:
+            return True
+    return False
+
+
+def _intent_was_served(
+    directive: str, modules: List[str], served: List[dict]
+) -> bool:
+    """Check if a specific intent was in the served constraints."""
+    for c in served:
+        msg = c.get("message", "")
+        if directive in msg and any(m.rstrip("/") in msg for m in modules):
+            return True
+    return False
+
+
+def _has_new_coupling(modules: List[str], diff_text: str) -> bool:
+    """Check if the diff introduces new imports between the listed modules."""
+    import_re = re.compile(r'(?:from\s+(\S+)\s+import|import\s+(\S+))')
+    current_file = ""
+
+    for line in diff_text.splitlines():
+        if line.startswith("diff --git"):
+            parts = line.split(" b/", 1)
+            current_file = parts[1] if len(parts) > 1 else ""
+        elif line.startswith("+") and not line.startswith("+++"):
+            m = import_re.search(line)
+            if not m:
+                continue
+            imported = (m.group(1) or m.group(2) or "").split(".")[0]
+            imported_mod = imported + "/"
+
+            file_mod = current_file.split("/")[0] + "/" if "/" in current_file else ""
+            if file_mod in modules and imported_mod in modules and file_mod != imported_mod:
+                return True
+
+    return False

dotscope/debug.py

@@ -0,0 +1,220 @@
+"""Context bisection: debug why an agent session produced a bad outcome.
+
+Deterministic. No LLM calls. Bisects files, context sections, and
+constraints to identify the root cause.
+"""
+
+import json
+import os
+from typing import Dict, List, Optional, Tuple
+
+from .models.state import BisectionResult  # noqa: F401
+
+
+def debug_session(
+    session_id: str,
+    repo_root: str,
+) -> Optional[BisectionResult]:
+    """Bisect a session to find root cause of bad outcome."""
+    session = _load_session(repo_root, session_id)
+    observation = _load_observation(repo_root, session_id)
+
+    if not session or not observation:
+        return None
+
+    recall = observation.get("recall", 1.0)
+    if recall >= 0.8:
+        return None  # Nothing to debug
+
+    resolved_files = set(session.get("predicted_files", []))
+    actual_files = set(observation.get("actual_files_modified", []))
+
+    # Bisect files
+    files_that_mattered = sorted(resolved_files & actual_files)
+    files_that_didnt_help = sorted(resolved_files - actual_files)
+    missing_files = sorted(actual_files - resolved_files)
+
+    # Bisect context
+    context = session.get("context", "")
+    sections = _parse_sections(context)
+    relevant = []
+    irrelevant = []
+    for name, text in sections.items():
+        if any(f in text or os.path.basename(f) in text for f in actual_files):
+            relevant.append(name)
+        else:
+            irrelevant.append(name)
+
+    # Bisect constraints
+    constraints = session.get("constraints_served", [])
+    honored = []
+    violated = []
+    for c in constraints:
+        if _constraint_violated(c, observation):
+            violated.append(c)
+        else:
+            honored.append(c)
+
+    # Diagnose
+    diagnosis, recommendations = _diagnose(
+        missing_files, violated, files_that_didnt_help,
+    )
+
+    return BisectionResult(
+        session_id=session_id,
+        files_that_mattered=files_that_mattered,
+        files_that_didnt_help=files_that_didnt_help,
+        context_sections_relevant=relevant,
+        context_sections_irrelevant=irrelevant,
+        constraints_honored=honored,
+        constraints_violated=violated,
+        missing_files=missing_files,
+        diagnosis=diagnosis,
+        recommendations=recommendations,
+    )
+
+
+def list_bad_sessions(repo_root: str, limit: int = 10) -> List[dict]:
+    """List sessions with low recall for debugging."""
+    from .sessions import SessionManager
+    mgr = SessionManager(repo_root)
+    observations = mgr.get_observations(limit=200)
+    sessions = mgr.get_sessions(limit=200)
+    session_map = {s.session_id: s for s in sessions}
+
+    bad = []
+    for obs in observations:
+        if obs.recall < 0.8:
+            s = session_map.get(obs.session_id)
+            bad.append({
+                "session_id": obs.session_id,
+                "scope": s.scope_expr if s else "unknown",
+                "recall": obs.recall,
+                "gaps": obs.touched_not_predicted[:3],
+            })
+
+    return bad[:limit]
+
+
+def format_debug_report(result: BisectionResult) -> str:
+    """Format bisection result for terminal output."""
+    lines = [f"dotscope debug: session {result.session_id}\n"]
+
+    lines.append("  File Bisection")
+    if result.files_that_mattered:
+        lines.append(f"    Files that mattered: {', '.join(result.files_that_mattered)}")
+    if result.files_that_didnt_help:
+        lines.append(f"    Files that didn't help: {', '.join(result.files_that_didnt_help)}")
+    if result.missing_files:
+        lines.append(f"    Missing files: {', '.join(result.missing_files)}")
+    lines.append("")
+
+    if result.context_sections_relevant or result.context_sections_irrelevant:
+        lines.append("  Context Bisection")
+        for s in result.context_sections_relevant:
+            lines.append(f"    Relevant: {s}")
+        for s in result.context_sections_irrelevant:
+            lines.append(f"    Irrelevant: {s}")
+        lines.append("")
+
+    if result.constraints_violated:
+        lines.append("  Constraints Violated")
+        for c in result.constraints_violated:
+            lines.append(f"    {c.get('message', 'unknown')}")
+        lines.append("")
+
+    lines.append(f"  Diagnosis: {result.diagnosis}")
+    for rec in result.recommendations:
+        lines.append(f"    -> {rec}")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+def _load_session(repo_root: str, session_id: str) -> Optional[dict]:
+    """Load a session file."""
+    path = os.path.join(repo_root, ".dotscope", "sessions", f"{session_id}.json")
+    if not os.path.exists(path):
+        return None
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _load_observation(repo_root: str, session_id: str) -> Optional[dict]:
+    """Find observation matching a session."""
+    from .sessions import SessionManager
+    mgr = SessionManager(repo_root)
+    for obs in mgr.get_observations(limit=200):
+        if obs.session_id == session_id:
+            return {
+                "actual_files_modified": obs.actual_files_modified,
+                "recall": obs.recall,
+                "touched_not_predicted": obs.touched_not_predicted,
+            }
+    return None
+
+
+def _parse_sections(context: str) -> Dict[str, str]:
+    """Parse context into named sections (## headers)."""
+    sections: Dict[str, str] = {}
+    current = "main"
+    lines: List[str] = []
+
+    for line in context.splitlines():
+        if line.startswith("## "):
+            if lines:
+                sections[current] = "\n".join(lines)
+            current = line[3:].strip()
+            lines = []
+        else:
+            lines.append(line)
+
+    if lines:
+        sections[current] = "\n".join(lines)
+    return sections
+
+
+def _constraint_violated(constraint: dict, observation: dict) -> bool:
+    """Check if a served constraint was violated in the observation."""
+    msg = constraint.get("message", "").lower()
+    actual = set(observation.get("actual_files_modified", []))
+
+    # Contract: check if both sides were modified
+    if "modify" in msg and "review" in msg:
+        for f in actual:
+            if f.lower() in msg:
+                # One side modified — check if the other was too
+                return True  # Simplified: if contract mentioned, check presence
+
+    return False
+
+
+def _diagnose(
+    missing_files: List[str],
+    constraints_violated: List[dict],
+    files_unused: List[str],
+) -> Tuple[str, List[str]]:
+    """Determine root cause and recommendations."""
+    recommendations = []
+
+    if missing_files:
+        for f in missing_files[:3]:
+            recommendations.append(f"Add {f} to scope includes or add assertion ensure_includes: [{f}]")
+        return "resolution_gap", recommendations
+
+    if constraints_violated and not missing_files:
+        for c in constraints_violated:
+            recommendations.append(
+                f"Agent ignored constraint: {c.get('message', '')[:60]}. "
+                f"Consider strengthening to HOLD."
+            )
+        return "agent_ignored", recommendations
+
+    if not missing_files and not constraints_violated:
+        recommendations.append("Add anti-patterns or intent directives for the patterns that caused the bad commit")
+        return "constraint_gap", recommendations
+
+    return "context_conflict", ["Review scope context for contradictory guidance"]