dotscope 0.1.0__py3-none-any.whl

dotscope/storage/.scope

@@ -0,0 +1,64 @@
+description: Infrastructure — disk I/O, hooks, caching, state persistence
+includes:
+  - session_manager.py
+  - cache.py
+  - git_hooks.py
+  - claude_hooks.py
+  - onboarding.py
+  - timing.py
+  - near_miss.py
+  - incremental_state.py
+excludes:
+  - __pycache__/
+context: |
+  Storage reads and writes models.state to disk. Pure infrastructure.
+
+  ## session_manager.py
+  SessionManager class. Creates sessions (.dotscope/sessions/),
+  records observations (.dotscope/observations/). Matches commits
+  to sessions by timestamp overlap.
+
+  ## cache.py
+  Caches history analysis and graph hubs after ingest so the MCP
+  server can load them at startup without re-computing.
+
+  ## git_hooks.py
+  Two git hooks installed by `dotscope hook install`:
+    pre-commit: runs `dotscope check`, blocks on HOLDs (enforcement)
+    post-commit: runs `dotscope observe` + `dotscope incremental` (feedback)
+  Cross-platform: POSIX shell script or Python fallback for Windows.
+  Marks hook_installed in onboarding state.
+
+  ## claude_hooks.py
+  Claude Code PreToolUse hook installed by `dotscope hook claude`.
+  Writes .claude/hooks/pre-commit-check.sh and wires it into
+  .claude/settings.json. Defense-in-depth layer for Claude Code.
+
+  ## onboarding.py
+  Milestone tracking in .dotscope/onboarding.json. Gating rules:
+  counterfactuals after 3+ observations, health nudges after 7+ days.
+  Next-step prompts: ingest -> backtest -> conventions -> voice -> MCP -> hook -> stop.
+
+  ## timing.py
+  Appends operation timing (resolve, check, ingest) to timings.jsonl.
+  Used by dotscope bench.
+
+  ## near_miss.py
+  Persistent storage for near-miss detections and session scopes.
+
+  ## incremental_state.py
+  Tracks commits_since_last_full_ingest in .dotscope/incremental.json.
+  Reset after full ingest. Used to prompt for re-scan after 200 commits.
+
+  ## Gotchas
+  All file I/O uses encoding="utf-8" for Windows compatibility.
+  Session files are JSON, observation files are JSONL (append-only).
+  .dotscope/ is gitignored and fully rebuildable via `dotscope rebuild`.
+related:
+  - dotscope/models/.scope
+tags:
+  - storage
+  - sessions
+  - hooks
+  - caching
+tokens_estimate: 3800

dotscope/storage/__init__.py

@@ -0,0 +1 @@
+"""Storage layer: persistent state management."""

dotscope/storage/cache.py

@@ -0,0 +1,114 @@
+"""Cache structured ingest data to .dotscope/ for MCP server consumption.
+
+Serializes HistoryAnalysis and DependencyGraph to JSON after ingest.
+MCP server loads them on startup for attribution hints and near-miss detection.
+"""
+
+import json
+import os
+from dataclasses import asdict
+from pathlib import Path
+from typing import Optional
+
+from ..graph import DependencyGraph, FileNode, ModuleBoundary
+from ..history import (
+    HistoryAnalysis, FileHistory, ChangeCoupling, ImplicitContract,
+)
+
+
+def cache_ingest_data(
+    root: str,
+    history: Optional[HistoryAnalysis] = None,
+    graph: Optional[DependencyGraph] = None,
+) -> None:
+    """Cache history and graph to .dotscope/ after ingest."""
+    dot_dir = Path(root) / ".dotscope"
+    dot_dir.mkdir(exist_ok=True)
+
+    if history and history.commits_analyzed > 0:
+        data = {
+            "commits_analyzed": history.commits_analyzed,
+            "implicit_contracts": [
+                {
+                    "trigger_file": ic.trigger_file,
+                    "coupled_file": ic.coupled_file,
+                    "confidence": ic.confidence,
+                    "occurrences": ic.occurrences,
+                    "description": ic.description,
+                }
+                for ic in history.implicit_contracts
+            ],
+            "hotspots": history.hotspots[:20],
+            "file_stabilities": {
+                path: {"stability": fh.stability, "commit_count": fh.commit_count}
+                for path, fh in history.file_histories.items()
+                if fh.stability
+            },
+        }
+        with open(dot_dir / "history.json", "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+    if graph and graph.files:
+        # Only cache what attribution hints need: imported_by fan-in
+        hubs = {}
+        for path, node in graph.files.items():
+            if len(node.imported_by) >= 3:
+                hubs[path] = {
+                    "imported_by_count": len(node.imported_by),
+                    "imported_by_dirs": sorted(set(
+                        str(Path(p).parts[0]) for p in node.imported_by
+                        if "/" in p
+                    )),
+                }
+        if hubs:
+            with open(dot_dir / "graph_hubs.json", "w", encoding="utf-8") as f:
+                json.dump(hubs, f, indent=2)
+
+
+def load_cached_history(root: str) -> Optional[HistoryAnalysis]:
+    """Load cached history from ..dotscope/history.json."""
+    path = Path(root) / ".dotscope" / "history.json"
+    if not path.exists():
+        return None
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        history = HistoryAnalysis(
+            commits_analyzed=data.get("commits_analyzed", 0),
+        )
+        for ic_data in data.get("implicit_contracts", []):
+            history.implicit_contracts.append(ImplicitContract(
+                trigger_file=ic_data["trigger_file"],
+                coupled_file=ic_data["coupled_file"],
+                confidence=ic_data["confidence"],
+                occurrences=ic_data["occurrences"],
+                description=ic_data.get("description", ""),
+            ))
+        for path_str, fh_data in data.get("file_stabilities", {}).items():
+            history.file_histories[path_str] = FileHistory(
+                path=path_str,
+                stability=fh_data.get("stability", ""),
+                commit_count=fh_data.get("commit_count", 0),
+            )
+        history.hotspots = data.get("hotspots", [])
+        return history
+    except (json.JSONDecodeError, KeyError):
+        return None
+
+
+def load_cached_graph_hubs(root: str) -> dict:
+    """Load cached graph hub data from ..dotscope/graph_hubs.json.
+
+    Returns: {path: {"imported_by_count": int, "imported_by_dirs": [str]}}
+    """
+    path = Path(root) / ".dotscope" / "graph_hubs.json"
+    if not path.exists():
+        return {}
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, KeyError):
+        return {}

dotscope/storage/claude_hooks.py

@@ -0,0 +1,119 @@
+"""Claude Code hook installation for automatic pre-commit routing verification.
+
+Writes a PreToolUse hook that intercepts git commit commands and runs
+dotscope check. GUARDs block the commit (exit 2). NUDGEs and NOTEs pass through.
+"""
+
+import json
+import os
+import stat
+
+
+_HOOK_SCRIPT = """\
+#!/bin/bash
+# dotscope pre-commit enforcement for Claude Code
+#
+# Intercepts git commit commands and runs dotscope check on staged changes.
+# Exit 2 blocks the commit and feeds the error back to the agent.
+# Non-commit Bash commands pass through untouched.
+
+set -e
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+# Only intercept git commit commands
+case "$COMMAND" in
+    git\\ commit*) ;;
+    *) exit 0 ;;
+esac
+
+# Run dotscope check on staged changes (30s timeout, fail open)
+if command -v timeout >/dev/null 2>&1; then
+    OUTPUT=$(timeout 30 python3 -m dotscope.cli check 2>&1) || true
+elif command -v gtimeout >/dev/null 2>&1; then
+    OUTPUT=$(gtimeout 30 python3 -m dotscope.cli check 2>&1) || true
+else
+    OUTPUT=$(python3 -m dotscope.cli check 2>&1) || true
+fi
+
+# Only GUARDs block. NUDGEs and NOTEs pass through.
+if echo "$OUTPUT" | grep -qE "GUARD|HOLD"; then
+    echo "$OUTPUT" >&2
+    echo "" >&2
+    echo "dotscope: commit blocked -- address guards before committing" >&2
+    exit 2
+fi
+
+# NUDGEs and NOTEs are guidance, not gates
+if echo "$OUTPUT" | grep -qE "NUDGE|NOTE"; then
+    echo "$OUTPUT" >&2
+fi
+
+exit 0
+"""
+
+
+def install_claude_hook(repo_root: str) -> str:
+    """Install Claude Code pre-commit enforcement hook.
+
+    Creates .claude/hooks/pre-commit-check.sh and wires it into
+    .claude/settings.json as a PreToolUse hook on Bash commands.
+
+    Preserves existing settings.json content (permissions, other hooks).
+    """
+    claude_dir = os.path.join(repo_root, ".claude")
+    hooks_dir = os.path.join(claude_dir, "hooks")
+    os.makedirs(hooks_dir, exist_ok=True)
+
+    # Write the hook script
+    script_path = os.path.join(hooks_dir, "pre-commit-check.sh")
+    with open(script_path, "w", encoding="utf-8") as f:
+        f.write(_HOOK_SCRIPT)
+    try:
+        os.chmod(script_path, os.stat(script_path).st_mode | stat.S_IEXEC)
+    except OSError:
+        pass
+
+    # Load or create settings.json
+    settings_path = os.path.join(claude_dir, "settings.json")
+    settings = {}
+    if os.path.exists(settings_path):
+        try:
+            with open(settings_path, "r", encoding="utf-8") as f:
+                settings = json.load(f)
+        except (json.JSONDecodeError, IOError):
+            settings = {}
+
+    # Add the hook (idempotent)
+    hooks = settings.setdefault("hooks", {})
+    pre_tool = hooks.setdefault("PreToolUse", [])
+
+    # Check if already installed
+    hook_entry = {
+        "matcher": "Bash",
+        "hooks": [
+            {
+                "type": "command",
+                "command": ".claude/hooks/pre-commit-check.sh",
+            }
+        ],
+    }
+
+    already = any(
+        entry.get("matcher") == "Bash"
+        and any(
+            h.get("command", "").endswith("pre-commit-check.sh")
+            for h in entry.get("hooks", [])
+        )
+        for entry in pre_tool
+    )
+
+    if not already:
+        pre_tool.append(hook_entry)
+
+    with open(settings_path, "w", encoding="utf-8") as f:
+        json.dump(settings, f, indent=2)
+        f.write("\n")
+
+    return f"Claude Code hook installed: {script_path}"

dotscope/storage/git_hooks.py

@@ -0,0 +1,277 @@
+"""Git hook management for dotscope.
+
+Two hooks:
+  pre-commit  — routing verification. Runs dotscope check, blocks on GUARDs only.
+  post-commit — feedback loop. Runs observe + incremental, never blocks.
+
+Both are deliberately minimal. All logic lives in Python.
+
+On Windows (no /bin/sh), we write Python-based hooks instead.
+Git for Windows invokes extensionless hook files via its bundled sh,
+but we also handle the pure-Windows case.
+"""
+
+import os
+import stat
+import sys
+from pathlib import Path
+
+_POST_MARKER = "# dotscope auto-observer"
+_INCREMENTAL_MARKER = "# dotscope incremental"
+_PRE_MARKER = "# dotscope pre-commit"
+
+# ---------------------------------------------------------------------------
+# Pre-commit hook: routing verification (blocks on GUARDs only)
+# ---------------------------------------------------------------------------
+
+_PRE_COMMIT_SH = """\
+#!/bin/sh
+# dotscope pre-commit
+# Runs dotscope check on staged changes. Only GUARDs block the commit.
+# NUDGEs and NOTEs print but pass through.
+# Timeout after 30 seconds — fail open if dotscope hangs.
+if command -v timeout >/dev/null 2>&1; then
+    OUTPUT=$(timeout 30 python3 -m dotscope.cli check 2>&1) || true
+elif command -v gtimeout >/dev/null 2>&1; then
+    OUTPUT=$(gtimeout 30 python3 -m dotscope.cli check 2>&1) || true
+else
+    OUTPUT=$(python3 -m dotscope.cli check 2>&1) || true
+fi
+if echo "$OUTPUT" | grep -qE "GUARD|HOLD"; then
+    echo "$OUTPUT" >&2
+    echo "" >&2
+    echo "dotscope: commit blocked -- address guards before committing" >&2
+    exit 1
+fi
+if echo "$OUTPUT" | grep -qE "NUDGE|NOTE"; then
+    echo "$OUTPUT" >&2
+fi
+"""
+
+_PRE_COMMIT_PY = """\
+#!/usr/bin/env python3
+# dotscope pre-commit
+import subprocess, sys
+try:
+    result = subprocess.run(
+        [sys.executable, "-m", "dotscope.cli", "check"],
+        capture_output=True, text=True, timeout=30,
+    )
+    output = result.stdout + result.stderr
+    if "GUARD" in output or "HOLD" in output:
+        print(output, file=sys.stderr)
+        print("", file=sys.stderr)
+        print("dotscope: commit blocked -- address guards before committing", file=sys.stderr)
+        sys.exit(1)
+    if "NUDGE" in output or "NOTE" in output:
+        print(output, file=sys.stderr)
+except Exception:
+    pass  # If dotscope fails, don't block
+"""
+
+# ---------------------------------------------------------------------------
+# Post-commit hook: feedback loop (never blocks)
+# ---------------------------------------------------------------------------
+
+_POST_COMMIT_SH = """\
+#!/bin/sh
+# dotscope auto-observer
+COMMIT_HASH=$(git rev-parse HEAD)
+# Capture observation output for agent feedback (Gap 4)
+OUTPUT=$(python3 -m dotscope.cli observe "$COMMIT_HASH" 2>&1) || true
+if [ -n "$OUTPUT" ]; then
+    echo "$OUTPUT" >&2
+fi
+# dotscope incremental
+python3 -m dotscope.cli incremental "$COMMIT_HASH" 2>/dev/null || true
+"""
+
+_POST_COMMIT_PY = """\
+#!/usr/bin/env python3
+# dotscope auto-observer
+import subprocess, sys
+try:
+    result = subprocess.run(["git", "rev-parse", "HEAD"],
+                            capture_output=True, text=True, timeout=10)
+    if result.returncode == 0:
+        commit = result.stdout.strip()
+        subprocess.run([sys.executable, "-m", "dotscope.cli", "observe", commit],
+                       timeout=30, capture_output=True)
+        # dotscope incremental
+        subprocess.run([sys.executable, "-m", "dotscope.cli", "incremental", commit],
+                       timeout=30, capture_output=True)
+except Exception:
+    pass  # Never block commits
+"""
+
+
+def _is_windows_native() -> bool:
+    """True if running on Windows without Git Bash / MSYS2 / WSL."""
+    if os.name != "nt":
+        return False
+    return not (os.environ.get("MSYSTEM") or os.environ.get("SHELL"))
+
+
+def _write_hook(hook_path: Path, content: str, marker: str) -> str:
+    """Write or append a hook file. Returns the path as string."""
+    hook_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if hook_path.exists():
+        existing = hook_path.read_text(encoding="utf-8")
+        if marker in existing:
+            return str(hook_path)  # Already installed
+        # Append to existing hook
+        with open(hook_path, "a", encoding="utf-8") as f:
+            f.write(f"\n{content}")
+    else:
+        hook_path.write_text(content, encoding="utf-8")
+
+    # Make executable
+    try:
+        hook_path.chmod(hook_path.stat().st_mode | stat.S_IEXEC)
+    except OSError:
+        pass
+
+    return str(hook_path)
+
+
+def _remove_hook_lines(hook_path: Path, marker: str) -> bool:
+    """Remove lines associated with a marker from a hook file."""
+    if not hook_path.exists():
+        return False
+
+    content = hook_path.read_text(encoding="utf-8")
+    if marker not in content:
+        return False
+
+    lines = content.splitlines()
+    filtered = []
+    in_block = False
+    for line in lines:
+        if marker in line:
+            in_block = True
+            continue
+        if in_block and ("dotscope" in line or "COMMIT_HASH" in line
+                         or "subprocess" in line or "OUTPUT" in line
+                         or line.strip().startswith("if ") or line.strip().startswith("echo ")
+                         or line.strip().startswith("exit ") or line.strip().startswith("fi")
+                         or line.strip().startswith("print(") or line.strip().startswith("sys.exit")
+                         or line.strip().startswith("result =") or line.strip().startswith("output =")
+                         or line.strip().startswith("except") or line.strip().startswith("try:")
+                         or line.strip().startswith("pass")):
+            continue
+        in_block = False
+        filtered.append(line)
+
+    remaining = "\n".join(filtered).strip()
+    shebang_only = remaining in ("#!/bin/sh", "#!/usr/bin/env python3")
+    if not remaining or shebang_only:
+        hook_path.unlink()
+    else:
+        hook_path.write_text(remaining + "\n", encoding="utf-8")
+
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def install_hook(repo_root: str) -> str:
+    """Install both pre-commit and post-commit hooks. Returns summary."""
+    hooks_dir = Path(repo_root) / ".git" / "hooks"
+    results = []
+
+    # Pre-commit (enforcement)
+    pre_path = hooks_dir / "pre-commit"
+    if _is_windows_native():
+        pre_content = _PRE_COMMIT_PY
+    else:
+        pre_content = _PRE_COMMIT_SH
+    path = _write_hook(pre_path, pre_content, _PRE_MARKER)
+    results.append(f"pre-commit: {path}")
+
+    # Post-commit (feedback loop)
+    post_path = hooks_dir / "post-commit"
+    if _is_windows_native():
+        post_content = _POST_COMMIT_PY
+    else:
+        post_content = _POST_COMMIT_SH
+
+    if post_path.exists():
+        existing = post_path.read_text(encoding="utf-8")
+        if _POST_MARKER in existing:
+            # Upgrade: add incremental line if missing
+            if _INCREMENTAL_MARKER not in existing:
+                incremental_line = (
+                    '# dotscope incremental\n'
+                    'python3 -m dotscope.cli incremental "$COMMIT_HASH" 2>/dev/null || true\n'
+                )
+                with open(post_path, "a", encoding="utf-8") as f:
+                    f.write(f"\n{incremental_line}")
+            results.append(f"post-commit: {post_path} (existing, upgraded)")
+        else:
+            path = _write_hook(post_path, post_content, _POST_MARKER)
+            results.append(f"post-commit: {path}")
+    else:
+        path = _write_hook(post_path, post_content, _POST_MARKER)
+        results.append(f"post-commit: {path}")
+
+    # Onboarding
+    try:
+        from .onboarding import mark_milestone
+        mark_milestone(repo_root, "hook_installed")
+    except Exception:
+        pass
+
+    return "\n".join(results)
+
+
+def uninstall_hook(repo_root: str) -> bool:
+    """Remove dotscope from both hook files. Returns True if anything removed."""
+    hooks_dir = Path(repo_root) / ".git" / "hooks"
+    removed = False
+
+    removed |= _remove_hook_lines(hooks_dir / "pre-commit", _PRE_MARKER)
+    removed |= _remove_hook_lines(hooks_dir / "post-commit", _POST_MARKER)
+    removed |= _remove_hook_lines(hooks_dir / "post-commit", _INCREMENTAL_MARKER)
+
+    return removed
+
+
+def is_hook_installed(repo_root: str) -> bool:
+    """Check if dotscope hooks are installed."""
+    hooks_dir = Path(repo_root) / ".git" / "hooks"
+
+    pre_installed = False
+    post_installed = False
+
+    pre_path = hooks_dir / "pre-commit"
+    if pre_path.exists():
+        pre_installed = _PRE_MARKER in pre_path.read_text(encoding="utf-8")
+
+    post_path = hooks_dir / "post-commit"
+    if post_path.exists():
+        post_installed = _POST_MARKER in post_path.read_text(encoding="utf-8")
+
+    return pre_installed or post_installed
+
+
+def hook_status(repo_root: str) -> str:
+    """Return a human-readable hook status."""
+    hooks_dir = Path(repo_root) / ".git" / "hooks"
+    parts = []
+
+    pre_path = hooks_dir / "pre-commit"
+    if pre_path.exists() and _PRE_MARKER in pre_path.read_text(encoding="utf-8"):
+        parts.append("pre-commit: installed (enforcement)")
+    else:
+        parts.append("pre-commit: not installed")
+
+    post_path = hooks_dir / "post-commit"
+    if post_path.exists() and _POST_MARKER in post_path.read_text(encoding="utf-8"):
+        parts.append("post-commit: installed (feedback loop)")
+    else:
+        parts.append("post-commit: not installed")
+
+    return "\n".join(parts)

dotscope/storage/incremental_state.py

@@ -0,0 +1,61 @@
+"""Persistent state for continuous ingest.
+
+Tracks how many commits have passed since the last full ingest,
+so dotscope can prompt for a full re-scan when incremental updates
+have drifted far enough.
+"""
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Dict
+
+
+@dataclass
+class IncrementalState:
+    """State tracking for continuous ingest."""
+    commits_since_last_full_ingest: int = 0
+    last_full_ingest_timestamp: str = ""
+    last_incremental_commit: str = ""
+    uncovered_new_files: int = 0
+
+
+def load_incremental_state(root: str) -> IncrementalState:
+    """Load incremental state from .dotscope/incremental.json."""
+    path = os.path.join(root, ".dotscope", "incremental.json")
+    if os.path.exists(path):
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            return IncrementalState(
+                commits_since_last_full_ingest=data.get("commits_since_last_full_ingest", 0),
+                last_full_ingest_timestamp=data.get("last_full_ingest_timestamp", ""),
+                last_incremental_commit=data.get("last_incremental_commit", ""),
+                uncovered_new_files=data.get("uncovered_new_files", 0),
+            )
+        except (json.JSONDecodeError, IOError):
+            pass
+    return IncrementalState()
+
+
+def save_incremental_state(root: str, state: IncrementalState) -> None:
+    """Persist incremental state to .dotscope/incremental.json."""
+    dot_dir = os.path.join(root, ".dotscope")
+    os.makedirs(dot_dir, exist_ok=True)
+    path = os.path.join(dot_dir, "incremental.json")
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump({
+            "commits_since_last_full_ingest": state.commits_since_last_full_ingest,
+            "last_full_ingest_timestamp": state.last_full_ingest_timestamp,
+            "last_incremental_commit": state.last_incremental_commit,
+            "uncovered_new_files": state.uncovered_new_files,
+        }, f, indent=2)
+
+
+def reset_incremental_state(root: str) -> None:
+    """Reset state after a full ingest."""
+    import time
+    state = IncrementalState(
+        last_full_ingest_timestamp=time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    )
+    save_incremental_state(root, state)