dotscope 0.1.0__py3-none-any.whl

dotscope/storage/mcp_config.py

@@ -0,0 +1,98 @@
+"""Auto-detect IDE and configure MCP server.
+
+Finds Claude Desktop, Claude Code, and Cursor configs.
+Writes the dotscope MCP entry if not already present.
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def configure_mcp(repo_root: str) -> list:
+    """Detect IDEs and write MCP config. Returns list of configured IDEs."""
+    configured = []
+
+    # Claude Desktop
+    path = _claude_desktop_config_path()
+    if path:
+        if _add_mcp_entry(path, repo_root):
+            configured.append("Claude Desktop")
+
+    # Claude Code (.claude/settings.json in project)
+    cc_path = os.path.join(repo_root, ".claude", "settings.json")
+    if _add_mcp_entry(cc_path, None):
+        configured.append("Claude Code")
+
+    # Cursor (.cursor/mcp.json in project)
+    cursor_path = os.path.join(repo_root, ".cursor", "mcp.json")
+    if _add_mcp_entry_cursor(cursor_path, repo_root):
+        configured.append("Cursor")
+
+    return configured
+
+
+def _claude_desktop_config_path() -> str:
+    """Find Claude Desktop config file."""
+    if sys.platform == "darwin":
+        p = Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    elif sys.platform == "win32":
+        appdata = os.environ.get("APPDATA", "")
+        p = Path(appdata) / "Claude" / "claude_desktop_config.json"
+    else:
+        p = Path.home() / ".config" / "Claude" / "claude_desktop_config.json"
+
+    return str(p) if p.parent.exists() else ""
+
+
+def _add_mcp_entry(config_path: str, repo_root: str) -> bool:
+    """Add dotscope to an MCP config file. Returns True if written."""
+    try:
+        config = {}
+        if os.path.exists(config_path):
+            with open(config_path, "r", encoding="utf-8") as f:
+                config = json.load(f)
+
+        servers = config.setdefault("mcpServers", {})
+        if "dotscope" in servers:
+            return False  # Already configured
+
+        entry = {"command": "dotscope-mcp"}
+        if repo_root:
+            entry["args"] = ["--root", os.path.abspath(repo_root)]
+
+        servers["dotscope"] = entry
+
+        os.makedirs(os.path.dirname(config_path), exist_ok=True)
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(config, f, indent=2)
+
+        return True
+    except (IOError, json.JSONDecodeError, OSError):
+        return False
+
+
+def _add_mcp_entry_cursor(config_path: str, repo_root: str) -> bool:
+    """Add dotscope to Cursor's MCP config."""
+    try:
+        config = {}
+        if os.path.exists(config_path):
+            with open(config_path, "r", encoding="utf-8") as f:
+                config = json.load(f)
+
+        if "dotscope" in config:
+            return False
+
+        config["dotscope"] = {
+            "command": "dotscope-mcp",
+            "args": ["--root", os.path.abspath(repo_root)],
+        }
+
+        os.makedirs(os.path.dirname(config_path), exist_ok=True)
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(config, f, indent=2)
+
+        return True
+    except (IOError, json.JSONDecodeError, OSError):
+        return False

dotscope/storage/near_miss.py

@@ -0,0 +1,183 @@
+"""Near-miss detection: disasters that didn't happen.
+
+Extracts warning pairs from scope context, compares against commit diffs,
+and stores detected near-misses for the agent channel.
+"""
+
+import json
+import os
+import re
+import time
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from ..models.intent import NearMiss, WarningPair  # noqa: F401
+
+
+# Regex patterns for extracting warning pairs from context
+_PAIR_PATTERNS = [
+    # "Never call .delete(), use .deactivate()"
+    r"[Nn]ever\s+(?:call\s+)?(\S+).*?use\s+(\S+)",
+    # "Don't use X, use Y instead"
+    r"[Dd]on'?t\s+(?:use\s+)?(\S+).*?use\s+(\S+)",
+    # "Avoid X — use Y"
+    r"[Aa]void\s+(\S+).*?use\s+(\S+)",
+    # "X is deprecated, use Y"
+    r"(\S+)\s+is\s+deprecated.*?use\s+(\S+)",
+]
+
+
+def extract_warning_pairs(
+    scope_name: str, context: str,
+) -> List[WarningPair]:
+    """Extract (anti_pattern, safe_pattern) pairs from scope context."""
+    pairs = []
+    for line in context.splitlines():
+        stripped = line.strip().lstrip("- ")
+        if not stripped:
+            continue
+        for pattern in _PAIR_PATTERNS:
+            match = re.search(pattern, stripped)
+            if match:
+                pairs.append(WarningPair(
+                    anti_pattern=match.group(1).strip(".,;:()"),
+                    safe_pattern=match.group(2).strip(".,;:()"),
+                    context_line=stripped,
+                    scope=scope_name,
+                ))
+                break
+    return pairs
+
+
+def detect_near_misses(
+    diff_text: str,
+    scope_contexts: Dict[str, str],
+) -> List[NearMiss]:
+    """Detect near-misses by comparing commit diff against scope warnings.
+
+    Args:
+        diff_text: The full commit diff
+        scope_contexts: {scope_name: context_str} for scopes resolved in session
+    """
+    if not diff_text:
+        return []
+
+    near_misses = []
+    diff_lower = diff_text.lower()
+
+    for scope_name, context in scope_contexts.items():
+        if not context:
+            continue
+
+        pairs = extract_warning_pairs(scope_name, context)
+        for pair in pairs:
+            anti_in_diff = pair.anti_pattern.lower() in diff_lower
+            safe_in_diff = pair.safe_pattern.lower() in diff_lower
+
+            if safe_in_diff and not anti_in_diff:
+                near_misses.append(NearMiss(
+                    scope=scope_name,
+                    event=(
+                        f"Agent used {pair.safe_pattern}"
+                        f" instead of {pair.anti_pattern}"
+                    ),
+                    context_used=pair.context_line,
+                    potential_impact=(
+                        f"Using {pair.anti_pattern} instead of {pair.safe_pattern}"
+                        f" would have violated the constraint:"
+                        f" {pair.context_line}"
+                    ),
+                ))
+
+    return near_misses[:5]  # Cap
+
+
+def store_near_misses(root: str, near_misses: List[NearMiss]) -> None:
+    """Append near-misses to .dotscope/near_misses.jsonl."""
+    path = Path(root) / ".dotscope" / "near_misses.jsonl"
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(path, "a", encoding="utf-8") as f:
+        for nm in near_misses:
+            f.write(json.dumps({
+                "scope": nm.scope,
+                "event": nm.event,
+                "context_used": nm.context_used,
+                "potential_impact": nm.potential_impact,
+                "timestamp": time.time(),
+            }) + "\n")
+
+    # Cap at 100 entries
+    _truncate_jsonl(path, max_entries=100)
+
+
+def load_recent_near_misses(
+    root: str, scope: str, max_age_hours: int = 48,
+) -> List[dict]:
+    """Load near-misses from ..dotscope/near_misses.jsonl."""
+    path = Path(root) / ".dotscope" / "near_misses.jsonl"
+    if not path.exists():
+        return []
+
+    cutoff = time.time() - (max_age_hours * 3600)
+    results = []
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            if not line.strip():
+                continue
+            entry = json.loads(line)
+            if entry.get("scope") != scope:
+                continue
+            if entry.get("timestamp", 0) < cutoff:
+                continue
+            hours_ago = max(1, int((time.time() - entry["timestamp"]) / 3600))
+            results.append({
+                "event": entry["event"],
+                "context_used": entry["context_used"],
+                "potential_impact": entry["potential_impact"],
+                "detected": f"{hours_ago}h ago",
+            })
+    except (json.JSONDecodeError, KeyError):
+        pass
+
+    return results
+
+
+def save_session_scopes(root: str, scopes: list) -> None:
+    """Write resolved scopes to .dotscope/last_session.json for post-commit hook."""
+    if not scopes:
+        return
+    path = Path(root) / ".dotscope" / "last_session.json"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps({
+        "scopes": scopes,
+        "ended_at": time.time(),
+    }), encoding="utf-8")
+
+
+def load_session_scopes(root: str) -> List[str]:
+    """Load scopes from the last MCP session."""
+    path = Path(root) / ".dotscope" / "last_session.json"
+    if not path.exists():
+        return []
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        # Only use if session ended within 4 hours
+        if time.time() - data.get("ended_at", 0) > 14400:
+            return []
+        return data.get("scopes", [])
+    except (json.JSONDecodeError, KeyError):
+        return []
+
+
+def _truncate_jsonl(path: Path, max_entries: int = 100) -> None:
+    """Keep only the last N entries in a JSONL file."""
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+        if len(lines) > max_entries:
+            path.write_text(
+                "\n".join(lines[-max_entries:]) + "\n",
+                encoding="utf-8",
+            )
+    except Exception:
+        pass

dotscope/storage/onboarding.py

@@ -0,0 +1,150 @@
+"""Stage-aware onboarding: guide the developer from skepticism to dependency.
+
+Tracks milestones in .dotscope/onboarding.json. Used to:
+1. Tailor "next step" prompts (one at a time, never nag)
+2. Gate complexity (counterfactuals after 3+ observations, health after 7+ days)
+3. Celebrate milestones (first session, first observation, first counterfactual)
+"""
+
+import json
+import os
+import time
+from typing import Optional
+
+
+def load_onboarding(repo_root: str) -> dict:
+    """Load onboarding state, creating default if missing."""
+    path = _onboarding_path(repo_root)
+    if os.path.exists(path):
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            pass
+    return _default_state()
+
+
+def save_onboarding(repo_root: str, state: dict) -> None:
+    """Persist onboarding state."""
+    dot_dir = os.path.join(repo_root, ".dotscope")
+    os.makedirs(dot_dir, exist_ok=True)
+    path = _onboarding_path(repo_root)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(state, f, indent=2)
+
+
+def mark_milestone(repo_root: str, milestone: str) -> dict:
+    """Record a milestone timestamp if not already set."""
+    state = load_onboarding(repo_root)
+    if milestone in state and state[milestone] is None:
+        state[milestone] = _now()
+        save_onboarding(repo_root, state)
+    return state
+
+
+def increment_counter(repo_root: str, counter: str) -> dict:
+    """Increment a counter (sessions_completed, observations_recorded)."""
+    state = load_onboarding(repo_root)
+    state[counter] = state.get(counter, 0) + 1
+    save_onboarding(repo_root, state)
+    return state
+
+
+# ---------------------------------------------------------------------------
+# Gating rules: when to show what
+# ---------------------------------------------------------------------------
+
+def should_show_counterfactuals(state: dict) -> bool:
+    """Counterfactuals need observation data to be meaningful."""
+    return state.get("observations_recorded", 0) >= 3
+
+
+def should_show_health_nudges(state: dict) -> bool:
+    """Health nudges aren't relevant on day 1."""
+    first = state.get("first_ingest")
+    if not first:
+        return False
+    try:
+        elapsed = time.time() - _parse_ts(first)
+        return elapsed >= 7 * 86400  # 7 days
+    except (ValueError, TypeError):
+        return True  # If we can't parse, show them
+
+
+def next_step(state: dict) -> Optional[str]:
+    """Return the single next action the developer should take, or None."""
+    if not state.get("first_backtest"):
+        return "Next: `dotscope check --backtest`"
+    if not state.get("conventions_reviewed"):
+        return "Next: `dotscope conventions`"
+    if not state.get("voice_reviewed"):
+        return "Next: `dotscope voice`"
+    if not state.get("first_session"):
+        return "Next: Add dotscope to your agent (docs/mcp-setup.md)"
+    if not state.get("hook_installed"):
+        return "Next: `dotscope hook install`"
+    return None  # Onboarded. Stop prompting.
+
+
+def milestone_message(state: dict) -> Optional[str]:
+    """Return a milestone celebration message, or None."""
+    sessions = state.get("sessions_completed", 0)
+    observations = state.get("observations_recorded", 0)
+
+    if sessions == 1:
+        return "First session tracked."
+    if observations == 1:
+        return "Feedback loop active — scopes will improve with use."
+    if sessions == 5:
+        return f"5 sessions completed. {observations} observations recorded."
+    return None
+
+
+def version_control_tip(state: dict) -> Optional[str]:
+    """One-time tip about committing .scope files. Shown on first ingest only."""
+    if state.get("vc_tip_shown"):
+        return None
+    return (
+        "Commit .scope files and intent.yaml. .dotscope/ is gitignored and rebuilds."
+    )
+
+
+def mark_vc_tip_shown(repo_root: str) -> None:
+    """Record that the version control tip has been shown."""
+    state = load_onboarding(repo_root)
+    state["vc_tip_shown"] = True
+    save_onboarding(repo_root, state)
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+def _onboarding_path(repo_root: str) -> str:
+    return os.path.join(repo_root, ".dotscope", "onboarding.json")
+
+
+def _default_state() -> dict:
+    return {
+        "first_ingest": None,
+        "first_backtest": None,
+        "first_session": None,
+        "hook_installed": None,
+        "first_observation": None,
+        "first_check_hold": None,
+        "conventions_reviewed": None,
+        "voice_reviewed": None,
+        "sessions_completed": 0,
+        "observations_recorded": 0,
+        "vc_tip_shown": False,
+    }
+
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _parse_ts(ts: str) -> float:
+    """Parse ISO timestamp to epoch seconds."""
+    from datetime import datetime as dt
+    return dt.fromisoformat(ts.replace("Z", "+00:00")).timestamp()

dotscope/storage/session_manager.py

@@ -0,0 +1,195 @@
+"""Session tracking and observation: the feedback loop.
+
+Sessions record what dotscope predicted an agent would need.
+Observations record what actually happened (post-commit).
+Together they close the loop between prediction and reality.
+
+All data is append-only. Derived views (utility scores, lessons)
+are computed from these logs and can be rebuilt.
+"""
+
+import hashlib
+import json
+import os
+import subprocess
+import time
+import uuid
+from pathlib import Path
+from typing import List, Optional
+
+from ..models import ObservationLog, SessionLog
+
+
+class SessionManager:
+    """Manages the .dotscope/ state directory and the session lifecycle."""
+
+    def __init__(self, root: str):
+        self.root = Path(root)
+        self.dot_dir = self.root / ".dotscope"
+        self.sessions_dir = self.dot_dir / "sessions"
+        self.obs_dir = self.dot_dir / "observations"
+
+    def ensure_initialized(self):
+        """Create .dotscope/ with schema version and .gitignore."""
+        for d in [self.sessions_dir, self.obs_dir]:
+            d.mkdir(parents=True, exist_ok=True)
+
+        version_file = self.dot_dir / "schema_version"
+        if not version_file.exists():
+            version_file.write_text("1", encoding="utf-8")
+
+        gitignore = self.dot_dir / ".gitignore"
+        if not gitignore.exists():
+            gitignore.write_text("*\n", encoding="utf-8")
+
+    def create_session(
+        self,
+        scope_expr: str,
+        task: Optional[str],
+        files: List[str],
+        context: str,
+    ) -> str:
+        """Record a scope resolution event (the prediction). Returns session ID."""
+        self.ensure_initialized()
+
+        session_id = uuid.uuid4().hex[:8]
+        session = SessionLog(
+            session_id=session_id,
+            timestamp=time.time(),
+            scope_expr=scope_expr,
+            task=task,
+            predicted_files=files,
+            context_hash=hashlib.sha256(context.encode()).hexdigest()[:16],
+        )
+
+        path = self.sessions_dir / f"{session_id}.json"
+        path.write_text(json.dumps({
+            "session_id": session.session_id,
+            "timestamp": session.timestamp,
+            "scope_expr": session.scope_expr,
+            "task": session.task,
+            "predicted_files": session.predicted_files,
+            "context_hash": session.context_hash,
+        }, indent=2), encoding="utf-8")
+
+        return session_id
+
+    def record_observation(self, commit_hash: str) -> Optional[ObservationLog]:
+        """Match a commit to a session and log what actually happened."""
+        self.ensure_initialized()
+
+        modified_files = self._get_commit_files(commit_hash)
+        if not modified_files:
+            return None
+
+        session = self._find_relevant_session(modified_files)
+        if not session:
+            return None
+
+        predicted_set = set(session.predicted_files)
+        actual_set = set(modified_files)
+
+        intersection = predicted_set & actual_set
+        predicted_not_touched = sorted(predicted_set - actual_set)
+        touched_not_predicted = sorted(actual_set - predicted_set)
+
+        recall = len(intersection) / len(actual_set) if actual_set else 1.0
+        precision = len(intersection) / len(predicted_set) if predicted_set else 1.0
+
+        obs = ObservationLog(
+            commit_hash=commit_hash,
+            session_id=session.session_id,
+            actual_files_modified=modified_files,
+            predicted_not_touched=predicted_not_touched,
+            touched_not_predicted=touched_not_predicted,
+            recall=round(recall, 3),
+            precision=round(precision, 3),
+            timestamp=time.time(),
+        )
+
+        path = self.obs_dir / f"{commit_hash[:8]}.json"
+        path.write_text(json.dumps({
+            "commit_hash": obs.commit_hash,
+            "session_id": obs.session_id,
+            "actual_files_modified": obs.actual_files_modified,
+            "predicted_not_touched": obs.predicted_not_touched,
+            "touched_not_predicted": obs.touched_not_predicted,
+            "recall": obs.recall,
+            "precision": obs.precision,
+            "timestamp": obs.timestamp,
+        }, indent=2), encoding="utf-8")
+
+        return obs
+
+    def get_sessions(self, limit: int = 50) -> List[SessionLog]:
+        """Load recent sessions, newest first."""
+        sessions = []
+        for p in sorted(self.sessions_dir.glob("*.json"), key=os.path.getmtime, reverse=True):
+            if len(sessions) >= limit:
+                break
+            try:
+                data = json.loads(p.read_text(encoding="utf-8"))
+                sessions.append(SessionLog(**data))
+            except (json.JSONDecodeError, TypeError):
+                continue
+        return sessions
+
+    def get_observations(self, limit: int = 50) -> List[ObservationLog]:
+        """Load recent observations, newest first."""
+        observations = []
+        for p in sorted(self.obs_dir.glob("*.json"), key=os.path.getmtime, reverse=True):
+            if len(observations) >= limit:
+                break
+            try:
+                data = json.loads(p.read_text(encoding="utf-8"))
+                observations.append(ObservationLog(**data))
+            except (json.JSONDecodeError, TypeError):
+                continue
+        return observations
+
+    def _get_commit_files(self, commit_hash: str) -> List[str]:
+        """Extract modified files from a commit."""
+        try:
+            result = subprocess.run(
+                ["git", "diff-tree", "--no-commit-id", "--name-only", "-r", commit_hash],
+                cwd=str(self.root),
+                capture_output=True, text=True, timeout=10,
+            )
+            if result.returncode != 0:
+                return []
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            return []
+        return [f.strip() for f in result.stdout.splitlines() if f.strip()]
+
+    def _find_relevant_session(self, modified_files: List[str]) -> Optional[SessionLog]:
+        """Match a commit to the best-fit session via Jaccard overlap.
+
+        Only considers sessions from the last 4 hours.
+        Requires minimum 10% Jaccard score to avoid spurious matches.
+        """
+        modified_set = set(modified_files)
+        best_session = None
+        best_score = 0.0
+        cutoff = time.time() - (4 * 3600)
+
+        for p in sorted(self.sessions_dir.glob("*.json"), key=os.path.getmtime, reverse=True):
+            if os.path.getmtime(p) < cutoff:
+                break
+            try:
+                data = json.loads(p.read_text(encoding="utf-8"))
+                session = SessionLog(**data)
+            except (json.JSONDecodeError, TypeError):
+                continue
+
+            predicted_set = set(session.predicted_files)
+            intersection = modified_set & predicted_set
+            union = modified_set | predicted_set
+            jaccard = len(intersection) / len(union) if union else 0.0
+
+            if jaccard > best_score:
+                best_score = jaccard
+                best_session = session
+
+        if best_score < 0.1:
+            return None
+        return best_session