dotscope 0.1.0__py3-none-any.whl

dotscope/discovery.py

@@ -0,0 +1,104 @@
+"""Discover repo roots, .scope files, and .scopes index files."""
+
+
+import os
+from typing import List, Optional
+
+from .constants import SKIP_DIRS
+from .models import ScopeConfig, ScopesIndex
+
+
+def find_repo_root(start_dir: Optional[str] = None) -> Optional[str]:
+    """Walk up from start_dir looking for .scopes, .git, or a .scope file.
+
+    Returns the directory containing the marker, or None.
+    """
+    current = os.path.abspath(start_dir or os.getcwd())
+
+    while True:
+        if os.path.isfile(os.path.join(current, ".scopes")):
+            return current
+        if os.path.isdir(os.path.join(current, ".git")):
+            return current
+        if os.path.isfile(os.path.join(current, ".scope")):
+            return current
+
+        parent = os.path.dirname(current)
+        if parent == current:
+            break
+        current = parent
+
+    return None
+
+
+def find_all_scopes(root: str) -> List[str]:
+    """Find all .scope files under root, returning absolute paths.
+
+    Skips common directories that should never be scanned.
+    """
+    scope_files = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+
+        if ".scope" in filenames:
+            scope_files.append(os.path.join(dirpath, ".scope"))
+
+    return sorted(scope_files)
+
+
+def load_index(root: str) -> Optional[ScopesIndex]:
+    """Load .scopes index from repo root, if it exists."""
+    from .parser import parse_scopes_index
+
+    index_path = os.path.join(root, ".scopes")
+    if os.path.isfile(index_path):
+        return parse_scopes_index(index_path)
+    return None
+
+
+def find_scope(name_or_path: str, root: Optional[str] = None) -> Optional[ScopeConfig]:
+    """Resolve a scope by name (from index), path, or directory.
+
+    Resolution order:
+    1. If name_or_path is a file path ending in .scope, parse it directly
+    2. If name_or_path is a directory containing .scope, parse that
+    3. Look up in .scopes index by name
+    4. Look for name_or_path/.scope relative to root
+    """
+    from .parser import parse_scope_file
+
+    # Direct .scope file path
+    if name_or_path.endswith(".scope") and os.path.isfile(name_or_path):
+        return parse_scope_file(name_or_path)
+
+    # Absolute directory containing .scope
+    if os.path.isdir(name_or_path):
+        scope_path = os.path.join(name_or_path, ".scope")
+        if os.path.isfile(scope_path):
+            return parse_scope_file(scope_path)
+
+    # Need root for index and relative lookups
+    if root is None:
+        root = find_repo_root()
+    if root is None:
+        return None
+
+    # Check .scopes index
+    index = load_index(root)
+    if index and name_or_path in index.scopes:
+        entry = index.scopes[name_or_path]
+        scope_path = os.path.join(root, entry.path)
+        if os.path.isfile(scope_path):
+            return parse_scope_file(scope_path)
+
+    # Try as relative directory
+    candidate = os.path.join(root, name_or_path, ".scope")
+    if os.path.isfile(candidate):
+        return parse_scope_file(candidate)
+
+    # Try as relative path to .scope
+    candidate = os.path.join(root, name_or_path)
+    if candidate.endswith(".scope") and os.path.isfile(candidate):
+        return parse_scope_file(candidate)
+
+    return None

dotscope/formatter.py

@@ -0,0 +1,157 @@
+"""Output formatting: plain, json, cursor."""
+
+import json
+import os
+from typing import Optional
+
+from .models import ResolvedScope
+from .paths import make_relative
+
+
+def format_resolved(
+    resolved: ResolvedScope,
+    fmt: str = "plain",
+    root: Optional[str] = None,
+    show_tokens: bool = False,
+) -> str:
+    """Format a resolved scope for output.
+
+    Formats:
+        plain  — One file path per line, with comments for context/excludes
+        json   — Full JSON object
+        cursor — .cursorrules-style: context + file list for pasting into agent prompts
+    """
+    if fmt == "json":
+        return _format_json(resolved, root)
+    elif fmt == "cursor":
+        return _format_cursor(resolved, root)
+    else:
+        return _format_plain(resolved, root, show_tokens)
+
+
+def _format_plain(resolved: ResolvedScope, root: Optional[str], show_tokens: bool) -> str:
+    """Plain format: one file per line."""
+    lines = []
+
+    for f in resolved.files:
+        path = make_relative(f, root)
+        if show_tokens:
+            from .tokens import estimate_file_tokens
+            tokens = estimate_file_tokens(f)
+            lines.append(f"{path}  # {tokens} tokens")
+        else:
+            lines.append(path)
+
+    if resolved.excluded_files:
+        lines.append("")
+        lines.append(f"# Excluded: {len(resolved.excluded_files)} files")
+
+    if resolved.truncated:
+        lines.append(f"# Truncated to fit token budget ({resolved.token_estimate} tokens)")
+
+    if resolved.context:
+        lines.append("")
+        lines.append(f"# Context: {len(resolved.context)} chars, from {len(resolved.scope_chain)} scope(s)")
+
+    return "\n".join(lines)
+
+
+def _format_json(resolved: ResolvedScope, root: Optional[str]) -> str:
+    """JSON format: full object."""
+    data = {
+        "files": [make_relative(f, root) for f in resolved.files],
+        "context": resolved.context,
+        "token_estimate": resolved.token_estimate,
+        "scope_chain": [make_relative(s, root) for s in resolved.scope_chain],
+        "truncated": resolved.truncated,
+        "file_count": len(resolved.files),
+    }
+    if resolved.excluded_files:
+        data["excluded_count"] = len(resolved.excluded_files)
+
+    return json.dumps(data, indent=2)
+
+
+def _format_cursor(resolved: ResolvedScope, root: Optional[str]) -> str:
+    """Cursor-style format for pasting into agent prompts or .cursorrules."""
+    parts = []
+
+    if resolved.context:
+        parts.append("# Scope Context")
+        parts.append("")
+        parts.append(resolved.context)
+        parts.append("")
+
+    if resolved.files:
+        parts.append("# Relevant Files")
+        parts.append("")
+        for f in resolved.files:
+            parts.append(f"- {make_relative(f, root)}")
+
+    if resolved.truncated:
+        parts.append("")
+        parts.append(f"# Note: file list truncated to {resolved.token_estimate} tokens")
+
+    return "\n".join(parts)
+
+
+def format_stats(
+    scope_stats: list,
+    total_files: int,
+    total_tokens: int,
+) -> str:
+    """Format the stats report."""
+    lines = [
+        f"Repository: {total_files} files, ~{total_tokens:,} tokens",
+        "",
+        f"{'Scope':<20} {'Files':>6} {'Tokens':>8} {'Savings':>8}",
+    ]
+
+    for name, file_count, token_count in scope_stats:
+        if total_tokens > 0:
+            savings = (1 - token_count / total_tokens) * 100
+            lines.append(f"{name:<20} {file_count:>6} {token_count:>8,} {savings:>7.1f}%")
+        else:
+            lines.append(f"{name:<20} {file_count:>6} {token_count:>8,}     N/A")
+
+    if scope_stats and total_tokens > 0:
+        avg_savings = sum(
+            (1 - tc / total_tokens) * 100 for _, _, tc in scope_stats
+        ) / len(scope_stats)
+        lines.append("")
+        lines.append(f"Average context reduction: {avg_savings:.1f}%")
+
+        avg_tokens = sum(tc for _, _, tc in scope_stats) / len(scope_stats)
+        cost_per_call = (total_tokens - avg_tokens) / 1_000_000 * 3
+        lines.append(f"Estimated cost savings at $3/M tokens: ${cost_per_call:.2f} per agent call")
+
+    return "\n".join(lines)
+
+
+def format_tree(scopes: list, root: str) -> str:
+    """Format a visual tree of scopes and relationships."""
+    if not scopes:
+        return "No .scope files found."
+
+    lines = [os.path.basename(root) + "/"]
+
+    for i, (scope_path, config) in enumerate(scopes):
+        is_last = i == len(scopes) - 1
+        prefix = "└── " if is_last else "├── "
+        rel = os.path.relpath(scope_path, root)
+        desc = config.description if config else "?"
+
+        lines.append(f"{prefix}{rel}")
+        lines.append(f"{'    ' if is_last else '│   '}  {desc}")
+
+        if config and config.related:
+            for j, related in enumerate(config.related):
+                r_is_last = j == len(config.related) - 1
+                r_prefix = "    └─→ " if r_is_last else "    ├─→ "
+                if not is_last:
+                    r_prefix = "│   " + r_prefix[4:]
+                lines.append(f"{r_prefix}{related}")
+
+    return "\n".join(lines)
+
+

dotscope/graph.py

@@ -0,0 +1,3 @@
+"""Backward-compatibility stub. Moved to dotscope.passes.graph_builder."""
+from .passes.graph_builder import *  # noqa: F401,F403
+from .models.core import DependencyGraph, FileNode, ModuleBoundary  # noqa: F401

dotscope/health.py

@@ -0,0 +1,212 @@
+"""Scope health monitoring: staleness, coverage gaps, import drift."""
+
+
+import os
+import re
+from typing import List, Optional, Set
+
+from .constants import SKIP_DIRS, SOURCE_EXTS
+from .models import HealthIssue, HealthReport, ScopeConfig
+
+
+def full_health_report(root: str) -> HealthReport:
+    """Run all health checks and return a combined report."""
+    from .discovery import find_all_scopes
+    from .parser import parse_scope_file
+
+    scope_files = find_all_scopes(root)
+    issues: List[HealthIssue] = []
+    scoped_dirs: Set[str] = set()
+
+    for sf in scope_files:
+        try:
+            config = parse_scope_file(sf)
+        except (ValueError, IOError) as e:
+            issues.append(HealthIssue(
+                scope_path=sf, severity="error",
+                category="parse", message=str(e),
+            ))
+            continue
+
+        scoped_dirs.add(os.path.dirname(sf))
+
+        issues.extend(check_staleness(config, root))
+        issues.extend(check_broken_paths(config, root))
+        issues.extend(check_import_drift(config))
+
+    # Coverage check
+    all_dirs = _find_source_dirs(root)
+    uncovered = all_dirs - scoped_dirs
+    coverage_issues = check_coverage(uncovered, root)
+    issues.extend(coverage_issues)
+
+    return HealthReport(
+        issues=issues,
+        scopes_checked=len(scope_files),
+        directories_total=len(all_dirs),
+        directories_covered=len(scoped_dirs),
+    )
+
+
+def check_staleness(config: ScopeConfig, root: str) -> List[HealthIssue]:
+    """Check if files in scope have been modified more recently than the .scope file."""
+    issues = []
+    scope_mtime = _get_mtime(config.path)
+    if scope_mtime is None:
+        return issues
+
+    stale_files = []
+
+    for inc in config.includes:
+        full = os.path.normpath(os.path.join(root, inc))
+        if inc.endswith("/") or os.path.isdir(full.rstrip("/")):
+            dir_path = full.rstrip("/")
+            if os.path.isdir(dir_path):
+                for dirpath, _, filenames in os.walk(dir_path):
+                    for fn in filenames:
+                        fp = os.path.join(dirpath, fn)
+                        fmtime = _get_mtime(fp)
+                        if fmtime and fmtime > scope_mtime:
+                            stale_files.append(os.path.relpath(fp, root))
+        elif os.path.isfile(full):
+            fmtime = _get_mtime(full)
+            if fmtime and fmtime > scope_mtime:
+                stale_files.append(os.path.relpath(full, root))
+
+    if stale_files:
+        count = len(stale_files)
+        sample = stale_files[:3]
+        msg = f"{count} file(s) modified since .scope was last updated: {', '.join(sample)}"
+        if count > 3:
+            msg += f" (+{count - 3} more)"
+        issues.append(HealthIssue(
+            scope_path=config.path, severity="warning",
+            category="staleness", message=msg,
+        ))
+
+    return issues
+
+
+def check_broken_paths(config: ScopeConfig, root: str = "") -> List[HealthIssue]:
+    """Check for include/related paths that don't exist."""
+    from .paths import path_exists, strip_inline_comment
+
+    issues = []
+    scope_dir = config.directory
+    base = root or scope_dir
+
+    for inc in config.includes:
+        if not path_exists(base, inc):
+            issues.append(HealthIssue(
+                scope_path=config.path, severity="error",
+                category="broken_path", message=f"include not found: {inc}",
+            ))
+
+    for rel in config.related:
+        clean = strip_inline_comment(rel)
+        # Related paths are repo-root-relative; try root first, then scope dir
+        if not path_exists(base, clean) and not path_exists(scope_dir, clean):
+            issues.append(HealthIssue(
+                scope_path=config.path, severity="warning",
+                category="broken_path", message=f"related scope not found: {clean}",
+            ))
+
+    return issues
+
+
+def check_import_drift(config: ScopeConfig) -> List[HealthIssue]:
+    """Check if imports in scoped files reference modules not in includes."""
+    issues = []
+    scope_dir = config.directory
+    included_dirs = set()
+
+    for inc in config.includes:
+        full = os.path.normpath(os.path.join(scope_dir, inc))
+        if inc.endswith("/") or os.path.isdir(full.rstrip("/")):
+            included_dirs.add(os.path.basename(full.rstrip("/")))
+        else:
+            included_dirs.add(os.path.dirname(inc).split("/")[0] if "/" in inc else "")
+
+    # Find Python files in includes and check their imports
+    drifted = set()
+    parent = os.path.dirname(scope_dir)
+
+    for inc in config.includes:
+        full = os.path.normpath(os.path.join(scope_dir, inc))
+        files = []
+        if os.path.isdir(full.rstrip("/")):
+            for dp, _, fns in os.walk(full.rstrip("/")):
+                for fn in fns:
+                    if fn.endswith(".py"):
+                        files.append(os.path.join(dp, fn))
+        elif full.endswith(".py") and os.path.isfile(full):
+            files.append(full)
+
+        for f in files:
+            try:
+                with open(f, "r", encoding="utf-8", errors="replace") as fh:
+                    for line in fh:
+                        m = re.match(r"from\s+([\w.]+)\s+import", line.strip())
+                        if m:
+                            module = m.group(1).split(".")[0]
+                            candidate = os.path.join(parent, module)
+                            if (
+                                os.path.isdir(candidate)
+                                and module not in included_dirs
+                                and candidate != scope_dir
+                                and module not in SKIP_DIRS
+                            ):
+                                drifted.add(module)
+            except (IOError, OSError):
+                continue
+
+    if drifted:
+        msg = f"imports reference modules not in includes: {', '.join(sorted(drifted))}"
+        issues.append(HealthIssue(
+            scope_path=config.path, severity="info",
+            category="drift", message=msg,
+        ))
+
+    return issues
+
+
+def check_coverage(uncovered: Set[str], root: str) -> List[HealthIssue]:
+    """Report directories that have source files but no .scope."""
+    issues = []
+    for d in sorted(uncovered):
+        rel = os.path.relpath(d, root)
+        # Only report if directory has source files
+        has_source = any(
+            fn.endswith((".py", ".js", ".ts", ".go", ".rs", ".rb", ".java"))
+            for fn in os.listdir(d)
+            if os.path.isfile(os.path.join(d, fn))
+        )
+        if has_source:
+            issues.append(HealthIssue(
+                scope_path="", severity="info",
+                category="coverage", message=f"no .scope file: {rel}/",
+            ))
+
+    return issues
+
+
+def _find_source_dirs(root: str) -> Set[str]:
+    """Find all directories under root that contain source files."""
+    source_exts = SOURCE_EXTS
+    dirs = set()
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+
+        if any(os.path.splitext(f)[1] in source_exts for f in filenames):
+            dirs.add(dirpath)
+
+    return dirs
+
+
+def _get_mtime(path: str) -> Optional[float]:
+    """Get file modification time, None if not accessible."""
+    try:
+        return os.path.getmtime(path)
+    except OSError:
+        return None

dotscope/help.py

@@ -0,0 +1,204 @@
+"""Hand-written help text following the voice spec.
+
+Dense, no filler, examples before options. argparse handles parsing;
+this module handles display.
+"""
+
+HELP_ROOT = """\
+Usage: dotscope <command>
+
+  init                      One command: ingest, hooks, MCP config
+  resolve <scope>           Serve context to an agent
+  check                     Verify routing (guards block, nudges guide)
+  conventions               View and manage conventions
+  voice                     View and manage code style
+  health                    Scope staleness and drift
+
+  ingest .                  Re-ingest (full scan)
+  intent                    Declare architectural direction
+  diff --staged             Semantic diff
+  hook install              Re-install hooks
+  bench                     Performance metrics
+  test-compiler             Regression suite
+  debug --last              Diagnose a bad session
+
+Run dotscope <command> --help for details."""
+
+HELP_INGEST = """\
+Usage: dotscope ingest <path> [options]
+
+  dotscope ingest .                    Full codebase ingest
+  dotscope ingest auth/                Single module
+  dotscope ingest . --max-commits 500  Deeper history mining
+  dotscope ingest . --quiet            Suppress progress (for CI)
+
+Options:
+  --max-commits <n>    Git commits to mine (default: 500)
+  --no-history         Skip git history mining
+  --no-docs            Skip doc absorption
+  --quiet              Suppress progress output
+  --dry-run            Show what would be generated without writing"""
+
+HELP_RESOLVE = """\
+Usage: dotscope resolve <scope> [options]
+
+  dotscope resolve auth                Files and context for auth/
+  dotscope resolve auth --budget 4000  Best 4K tokens
+  dotscope resolve auth+payments       Union of two scopes
+  dotscope resolve auth@context        Context only, no files
+
+Options:
+  --budget <tokens>    Token limit
+  --task <description> Filter constraints by relevance
+  --json               Machine-readable output
+  --no-related         Don't follow related scopes"""
+
+HELP_CHECK = """\
+Usage: dotscope check [options]
+
+  dotscope check                          Validate staged changes
+  dotscope check --diff changes.patch     Check arbitrary diff
+  dotscope check --backtest --commits 10  Replay history
+  dotscope check --acknowledge <id>       Acknowledge a guard
+
+Three severities:
+  GUARD    Blocks commit. Frozen modules, deprecated imports.
+  NUDGE    Prints guidance. Contracts, conventions, anti-patterns.
+  NOTE     Informational. Direction reversals, stability.
+
+Options:
+  --staged             Check staged changes (default)
+  --diff <file>        Check arbitrary diff file
+  --backtest           Replay commits instead of checking staged
+  --commits <n>        Commits to replay (with --backtest)
+  --acknowledge <id>   Acknowledge a guard and proceed
+  --json               Machine-readable output"""
+
+HELP_INTENT = """\
+Usage: dotscope intent <action> [options]
+
+  dotscope intent list                                    Show all intents
+  dotscope intent add decouple auth/ payments/            Decouple modules
+  dotscope intent add freeze core/                        Freeze a module
+  dotscope intent add deprecate old.py --replacement new.py
+  dotscope intent remove <id>                             Remove an intent
+
+Directives:
+  decouple <mod> <mod>   Discourage new coupling between modules
+  deprecate <file>       Flag new usage as a hold
+  freeze <module>        Require acknowledgment for any change
+  consolidate <m> <m>    Encourage merging toward a target"""
+
+HELP_CONVENTIONS = """\
+Usage: dotscope conventions [options]
+
+  dotscope conventions                List all conventions + compliance
+  dotscope conventions --discover     Re-run discovery against codebase
+  dotscope conventions --accept       Accept all discovered conventions
+  dotscope conventions --review       Interactive review
+
+Options:
+  --discover           Re-run convention discovery
+  --accept             Accept discovered conventions
+  --review             Review discovered conventions interactively"""
+
+HELP_VOICE = """\
+Usage: dotscope voice [options]
+
+  dotscope voice                      Show current voice config
+  dotscope voice --upgrade typing     Upgrade enforcement level
+  dotscope voice --json               Machine-readable output
+
+Options:
+  --upgrade <rule>     Upgrade enforcement (typing, bare_excepts)
+  --json               Machine-readable output"""
+
+HELP_DIFF = """\
+Usage: dotscope diff [options]
+
+  dotscope diff --staged               Semantic diff of staged changes
+  dotscope diff HEAD~1                  Semantic diff against last commit
+  dotscope diff HEAD~5..HEAD            Range of commits
+
+Options:
+  --staged             Diff staged changes (default)
+  --json               Machine-readable output"""
+
+HELP_BENCH = """\
+Usage: dotscope bench [options]
+
+  dotscope bench                       Full benchmark report
+  dotscope bench --json                Machine-readable output
+
+Options:
+  --json               Machine-readable output"""
+
+HELP_TEST_COMPILER = """\
+Usage: dotscope test-compiler [options]
+
+  dotscope test-compiler               Replay all regression cases
+  dotscope test-compiler --scope auth  Replay regressions for auth only
+
+Options:
+  --scope <name>       Filter to a specific scope"""
+
+HELP_DEBUG = """\
+Usage: dotscope debug [options]
+
+  dotscope debug --last                Debug most recent bad session
+  dotscope debug <session_id>          Debug a specific session
+  dotscope debug --list                List sessions with low recall
+
+Options:
+  --last               Debug most recent session with low recall
+  --list               List debuggable sessions
+  --json               Machine-readable output"""
+
+HELP_HEALTH = """\
+Usage: dotscope health [options]
+
+  dotscope health                      All scopes
+  dotscope health auth                 Single scope
+  dotscope health --json               Machine-readable output
+
+Options:
+  --json               Machine-readable output"""
+
+HELP_HOOK = """\
+Usage: dotscope hook <action>
+
+  dotscope hook install                Install pre-commit + post-commit hooks
+  dotscope hook claude                 Install Claude Code pre-commit enforcement
+  dotscope hook uninstall              Remove all dotscope hooks
+  dotscope hook status                 Check what's installed
+
+Pre-commit blocks on GUARDs only. NUDGEs and NOTEs pass through.
+Post-commit records observations for the feedback loop."""
+
+HELP_COMMANDS = {
+    "ingest": HELP_INGEST,
+    "resolve": HELP_RESOLVE,
+    "check": HELP_CHECK,
+    "intent": HELP_INTENT,
+    "conventions": HELP_CONVENTIONS,
+    "diff": HELP_DIFF,
+    "voice": HELP_VOICE,
+    "bench": HELP_BENCH,
+    "test-compiler": HELP_TEST_COMPILER,
+    "debug": HELP_DEBUG,
+    "health": HELP_HEALTH,
+    "hook": HELP_HOOK,
+}
+
+
+def print_help(command=None):
+    """Print help for a command, or root help if no command given."""
+    if command is None:
+        print(HELP_ROOT)
+    elif command in HELP_COMMANDS:
+        print(HELP_COMMANDS[command])
+    else:
+        import sys
+        print(f"Unknown command: {command}\n")
+        print("Run dotscope --help to see available commands.")
+        sys.exit(1)

dotscope/history.py

@@ -0,0 +1,6 @@
+"""Backward-compatibility stub. Moved to dotscope.passes.history_miner."""
+from .passes.history_miner import *  # noqa: F401,F403
+from .models.history import (  # noqa: F401
+    FileChange, CommitInfo, FileHistory,
+    ChangeCoupling, ImplicitContract, HistoryAnalysis,
+)

dotscope/hooks.py

@@ -0,0 +1,2 @@
+"""Backward-compatibility stub. Moved to dotscope.storage.git_hooks."""
+from .storage.git_hooks import *  # noqa: F401,F403