dotscope 1.2.2__tar.gz → 1.3.0__tar.gz

dotscope-1.3.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python -m pytest tests/test_mcp_config.py tests/test_mcp_server.py -v)"
+    ]
+  }
+}

dotscope-1.3.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "dotscope": {
+      "type": "stdio",
+      "command": "dotscope-mcp"
+    }
+  }
+}

dotscope-1.3.0/.virtual/isolated-hubs.scope

@@ -0,0 +1,14 @@
+description: Detected dense God-Objects. Emitting directive to isolate hubs.
+includes:
+  - dotscope/discovery.py
+  - dotscope/models.py
+  - dotscope/parser.py
+context: |
+  ## Cloud Directive
+  This virtual scope isolates objects that cross the semantic failure threshold for AI context.
+  
+  ### Constraints
+  - prohibited_imports: *
+tags:
+  - virtual
+  - federated-directive

{dotscope-1.2.2 → dotscope-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotscope
-Version: 1.2.2
+Version: 1.3.0
 Summary: Agents see files. You see architecture. dotscope gives agents the architecture.
 Author: Supremum
 License-Expression: MIT
@@ -17,7 +17,7 @@ Requires-Dist: tree-sitter-javascript>=0.23.0
 Requires-Dist: tree-sitter-typescript>=0.23.0
 Requires-Dist: tree-sitter>=0.23.0
 Provides-Extra: all
-Requires-Dist: mcp>=1.2.0; extra == 'all'
+Requires-Dist: mcp<3,>=1.2.0; extra == 'all'
 Requires-Dist: numpy; extra == 'all'
 Requires-Dist: sentence-transformers; extra == 'all'
 Requires-Dist: tiktoken; extra == 'all'
@@ -27,7 +27,7 @@ Requires-Dist: ruff; extra == 'dev'
 Provides-Extra: embeddings
 Requires-Dist: sentence-transformers; extra == 'embeddings'
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.2.0; extra == 'mcp'
+Requires-Dist: mcp<3,>=1.2.0; extra == 'mcp'
 Provides-Extra: search
 Requires-Dist: numpy; extra == 'search'
 Requires-Dist: sentence-transformers; extra == 'search'

{dotscope-1.2.2 → dotscope-1.3.0}/docs/mcp-setup.md

@@ -2,18 +2,25 @@
 
 dotscope's primary interface for agents is an MCP server. The agent calls `resolve_scope` to get files, context, and constraints. dotscope tracks every call for the feedback loop.
 
+**Supported clients:** Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, OpenAI Codex CLI, JetBrains AI, Zed
+
 ## Install
 
 ```bash
 pip install dotscope[mcp]
 ```
 
+## Quick Setup
+
+Run `dotscope init` in your project root. It auto-detects installed editors and writes config for each one.
+
 ## Claude Desktop
 
 Edit your config file:
 
 **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+**Linux:** `~/.config/Claude/claude_desktop_config.json`
 
 ```json
 {
@@ -30,12 +37,13 @@ Omit `--root` to use the current working directory. Restart Claude Desktop after
 
 ## Claude Code
 
-Add to your project's `.claude/settings.json` or the global settings:
+Add a `.mcp.json` file to your project root (preferred):
 
 ```json
 {
   "mcpServers": {
     "dotscope": {
+      "type": "stdio",
       "command": "dotscope-mcp"
     }
   }
@@ -46,7 +54,7 @@ No `--root` needed. Claude Code launches from the project directory.
 
 ## Cursor
 
-Settings > MCP Servers:
+Add to `.cursor/mcp.json` in your project root:
 
 ```json
 {
@@ -57,6 +65,76 @@ Settings > MCP Servers:
 }
 ```
 
+Note: Cursor uses a flat structure (no `mcpServers` wrapper).
+
+## Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json` (global config):
+
+```json
+{
+  "mcpServers": {
+    "dotscope": {
+      "command": "dotscope-mcp",
+      "args": ["--root", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+## VS Code Copilot
+
+Add to `.vscode/mcp.json` in your project root:
+
+```json
+{
+  "servers": {
+    "dotscope": {
+      "command": "dotscope-mcp"
+    }
+  }
+}
+```
+
+Note: VS Code uses `servers` as the top-level key (not `mcpServers`).
+
+## OpenAI Codex CLI
+
+Add to `.codex/config.toml` in your project root (or `~/.codex/config.toml` for global):
+
+```toml
+[mcp_servers.dotscope]
+command = "dotscope-mcp"
+```
+
+## JetBrains AI
+
+Configure manually via the IDE:
+
+1. Open **Settings > Tools > AI Assistant > Model Context Protocol (MCP)**
+2. Add a new local server:
+   - **Command:** `dotscope-mcp`
+   - **Arguments:** `--root /path/to/your/project`
+3. Click OK and restart the AI Assistant
+
+## Zed
+
+Add to `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "dotscope": {
+      "source": "custom",
+      "command": "dotscope-mcp",
+      "args": ["--root", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+Or use Agent Panel (Cmd+Shift+A) > Settings > "Add Custom Server".
+
 ## Verifying
 
 Ask your agent: "What scopes are available?" It should call `list_scopes` and show what dotscope generated during ingest.

{dotscope-1.2.2 → dotscope-1.3.0}/dotscope/__init__.py

@@ -1,3 +1,3 @@
 """dotscope — Directory-scoped context boundaries for AI coding agents."""
 
-__version__ = "1.2.2"
+__version__ = "1.3.0"

dotscope-1.3.0/dotscope/cli/__init__.py

@@ -0,0 +1,320 @@
+from .core import _cmd_resolve, _cmd_context, _cmd_match, _cmd_init, _cmd_intent, _cmd_utility
+from .observability import _cmd_stats, _cmd_tree, _cmd_health, _cmd_validate, _cmd_virtual, _cmd_lessons, _cmd_invariants, _cmd_rebuild, _cmd_test_compiler, _cmd_bench, _cmd_debug
+from .ingest import _cmd_ingest, _cmd_impact, _cmd_backtest, _cmd_conventions, _cmd_diff
+from .hooks import _cmd_observe, _cmd_incremental, _cmd_hook, _cmd_refresh, _cmd_check, _cmd_check_backtest, _cmd_voice
+
+
+"""CLI entry point for dotscope."""
+
+import argparse
+
+import os
+
+import sys
+
+def _safe_print(text, **kwargs):
+    """Print with ASCII fallback for Windows cp1252 terminals."""
+    try:
+        print(text, **kwargs)
+    except UnicodeEncodeError:
+        print(text.encode("ascii", errors="replace").decode("ascii"), **kwargs)
+
+def main(argv=None):
+    from ..textio import consume_decode_warnings
+
+    consume_decode_warnings()
+
+    # Intercept help before argparse touches it
+    args_list = argv if argv is not None else sys.argv[1:]
+    if not args_list or args_list == ["help"] or args_list == ["--help"] or args_list == ["-h"]:
+        from ..help import print_help
+        print_help()
+        return
+    if len(args_list) >= 2 and args_list[1] in ("--help", "-h"):
+        from ..help import print_help, HELP_COMMANDS
+        cmd = args_list[0]
+        if cmd in HELP_COMMANDS:
+            print_help(cmd)
+            return
+        # Fall through to argparse for unknown commands
+
+    parser = argparse.ArgumentParser(
+        prog="dotscope",
+        description="Directory-scoped context boundaries for AI coding agents",
+        add_help=False,
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {_version()}")
+    parser.add_argument("-h", "--help", action="store_true", dest="show_help")
+
+    sub = parser.add_subparsers(dest="command")
+
+    # --- resolve ---
+    p_resolve = sub.add_parser("resolve", help="Resolve a scope expression to files")
+    p_resolve.add_argument("scope", help="Scope name, path, or expression (e.g., auth+payments)")
+    p_resolve.add_argument("--budget", type=int, default=None, help="Max tokens (context + files)")
+    p_resolve.add_argument("--tokens", action="store_true", help="Show per-file token counts")
+    p_resolve.add_argument("--json", action="store_true", help="Output as JSON")
+    p_resolve.add_argument("--cursor", action="store_true", help="Output as .cursorrules format")
+    p_resolve.add_argument("--no-related", action="store_true", help="Don't follow related scopes")
+    p_resolve.add_argument("--task", default=None, help="Task description for relevance ranking")
+
+    # --- context ---
+    p_context = sub.add_parser("context", help="Print context for a scope")
+    p_context.add_argument("scope", help="Scope name or path")
+    p_context.add_argument("--section", default=None, help="Filter to a named section")
+
+    # --- match ---
+    p_match = sub.add_parser("match", help="Match a task description to scope(s)")
+    p_match.add_argument("task", help="Task description string")
+
+    # --- init ---
+    p_init = sub.add_parser("init", help="One command: ingest, install hooks, configure agents")
+    p_init.add_argument("path", nargs="?", default=".", help="Repository root")
+    p_init.add_argument("--quiet", action="store_true", help="Suppress progress (for CI)")
+
+    # --- validate ---
+    sub.add_parser("validate", help="Check all .scope files for broken paths")
+
+    # --- stats ---
+    sub.add_parser("stats", help="Token savings report across all scopes")
+
+    # --- tree ---
+    sub.add_parser("tree", help="Visual tree of all scopes and relationships")
+
+    # --- health ---
+    sub.add_parser("health", help="Scope health: staleness, coverage, drift")
+
+    # --- ingest ---
+    p_ingest = sub.add_parser("ingest", help="Reverse-engineer .scope files from an existing codebase")
+    p_ingest.add_argument("--dir", default=".", help="Repository root to ingest")
+    p_ingest.add_argument("--no-history", action="store_true", help="Skip git history mining")
+    p_ingest.add_argument("--no-docs", action="store_true", help="Skip doc absorption")
+    p_ingest.add_argument("--dry-run", action="store_true", help="Plan only, don't write files")
+    p_ingest.add_argument("--max-commits", type=int, default=500, help="Max git commits to analyze")
+    p_ingest.add_argument("--quiet", action="store_true", help="Suppress progress output (for CI)")
+    p_ingest.add_argument("--voice", choices=["prescriptive", "adaptive"], default=None,
+                          help="Override voice mode (prescriptive for new, adaptive for existing)")
+
+    # --- voice ---
+    p_voice = sub.add_parser("voice", help="View and manage code voice")
+    p_voice.add_argument("--upgrade", metavar="RULE", help="Upgrade enforcement for a rule (typing, bare_excepts)")
+    p_voice.add_argument("--reset", action="store_true", help="Reset voice to defaults")
+    p_voice.add_argument("--json", action="store_true", help="Machine-readable output")
+
+    # --- impact ---
+    p_impact = sub.add_parser("impact", help="Predict blast radius of changes to a file")
+    p_impact.add_argument("file", help="File path to analyze impact for")
+
+    # --- backtest ---
+    p_backtest = sub.add_parser("backtest", help="Validate scopes against git history")
+    p_backtest.add_argument("--commits", type=int, default=50, help="Number of commits to test against")
+
+    # --- observe ---
+    p_observe = sub.add_parser("observe", help="Record observation for a commit (called by post-commit hook)")
+    p_observe.add_argument("commit", help="Commit hash to observe")
+
+    # --- incremental ---
+    p_incremental = sub.add_parser("incremental", help="Incremental scope update (called by post-commit hook)")
+    p_incremental.add_argument("commit", help="Commit hash")
+
+    # --- hook ---
+    p_hook = sub.add_parser("hook", help="Manage git hooks")
+    hook_sub = p_hook.add_subparsers(dest="hook_action")
+    hook_sub.add_parser("install", help="Install post-commit observer hook")
+    hook_sub.add_parser("uninstall", help="Remove post-commit observer hook")
+    hook_sub.add_parser("status", help="Check if hook is installed")
+    hook_sub.add_parser("claude", help="Install Claude Code pre-commit enforcement")
+
+    # --- refresh ---
+    p_refresh = sub.add_parser("refresh", help="Refresh scopes (synchronous by default)")
+    p_refresh.add_argument("scopes", nargs="*", help="Scope names to refresh (omit for full repo)")
+    p_refresh.add_argument("--repo", action="store_true", help="Force full repo refresh")
+    p_refresh.add_argument("--async", dest="run_async", action="store_true", help="Queue and return (legacy async mode)")
+    refresh_sub = p_refresh.add_subparsers(dest="refresh_action")
+    p_refresh_enqueue = refresh_sub.add_parser("enqueue", help="Queue runtime refresh work")
+    p_refresh_enqueue.add_argument("scopes", nargs="*", help="Scope names to refresh")
+    p_refresh_enqueue.add_argument("--commit", default=None, help="Classify a commit into refresh work")
+    p_refresh_enqueue.add_argument("--repo", action="store_true", help="Enqueue a full repo runtime refresh")
+    p_refresh_enqueue.add_argument("--reason", default="", help="Reason stored with the queued job")
+    p_refresh_run = refresh_sub.add_parser("run", help="Run queued refresh work")
+    p_refresh_run.add_argument("--drain", action="store_true", help="Drain the entire queue")
+    refresh_sub.add_parser("status", help="Show refresh worker and queue status")
+
+    # --- utility ---
+    p_utility = sub.add_parser("utility", help="Show utility scores for a scope")
+    p_utility.add_argument("scope", help="Scope name")
+
+    # --- virtual ---
+    sub.add_parser("virtual", help="Detect and show virtual (cross-cutting) scopes")
+
+    # --- lessons ---
+    p_lessons = sub.add_parser("lessons", help="Show lessons for a scope")
+    p_lessons.add_argument("scope", help="Scope name")
+
+    # --- invariants ---
+    p_invariants = sub.add_parser("invariants", help="Show observed invariants for a scope")
+    p_invariants.add_argument("scope", help="Scope name")
+
+    # --- rebuild ---
+    sub.add_parser("rebuild", help="Rebuild derived state from event logs")
+
+    # --- check ---
+    p_check = sub.add_parser("check", help="Validate a diff against codebase rules")
+    p_check.add_argument("--diff", default=None, help="Path to diff file (default: staged changes)")
+    p_check.add_argument("--session", default=None, help="Session ID for boundary checking")
+    p_check.add_argument("--acknowledge", action="append", default=[], help="Acknowledge a hold by ID")
+    p_check.add_argument("--backtest", action="store_true", help="Replay recent commits against checks")
+    p_check.add_argument("--commits", type=int, default=10, help="Commits to replay in backtest mode")
+    p_check.add_argument("--json", dest="json_output", action="store_true", help="Output as JSON")
+    p_check.add_argument("--explain", action="store_true", help="Show full provenance for each finding")
+
+    # --- intent ---
+    p_intent = sub.add_parser("intent", help="Manage architectural intents")
+    intent_sub = p_intent.add_subparsers(dest="intent_action")
+    p_intent_add = intent_sub.add_parser("add", help="Add an architectural intent")
+    p_intent_add.add_argument("directive", choices=["decouple", "deprecate", "freeze", "consolidate"])
+    p_intent_add.add_argument("targets", nargs="+", help="Modules or files")
+    p_intent_add.add_argument("--reason", default="", help="Why this intent exists")
+    p_intent_add.add_argument("--replacement", default=None, help="Replacement (for deprecate)")
+    p_intent_add.add_argument("--target", default=None, help="Consolidation target")
+    p_intent_list = intent_sub.add_parser("list", help="List all intents")
+    p_intent_rm = intent_sub.add_parser("remove", help="Remove an intent by ID")
+    p_intent_rm.add_argument("id", help="Intent ID to remove")
+
+    # --- conventions ---
+    p_conv = sub.add_parser("conventions", help="List or discover conventions")
+    p_conv.add_argument("--discover", action="store_true", help="Discover conventions from codebase")
+    p_conv.add_argument("--accept", action="store_true", help="Accept discovered conventions")
+    p_conv.add_argument("--json", dest="json_output", action="store_true", help="Output as JSON")
+
+    # --- diff ---
+    p_diff = sub.add_parser("diff", help="Semantic diff against conventions")
+    p_diff.add_argument("ref", nargs="?", default=None, help="Git ref to diff against")
+    p_diff.add_argument("--staged", action="store_true", help="Diff staged changes")
+    p_diff.add_argument("--json", dest="json_output", action="store_true", help="Output as JSON")
+
+    # --- test-compiler ---
+    p_tc = sub.add_parser("test-compiler", help="Replay frozen sessions as regression tests")
+    p_tc.add_argument("--scope", default=None, help="Filter to a specific scope")
+
+    # --- bench ---
+    p_bench = sub.add_parser("bench", help="Performance and accuracy benchmarks")
+    p_bench.add_argument("--json", dest="json_output", action="store_true", help="JSON output")
+
+    # --- debug ---
+    p_debug = sub.add_parser("debug", help="Bisect a bad session to find root cause")
+    p_debug.add_argument("session_id", nargs="?", default=None, help="Session ID to debug")
+    p_debug.add_argument("--last", action="store_true", help="Debug most recent bad session")
+    p_debug.add_argument("--list", dest="list_bad", action="store_true", help="List bad sessions")
+
+    args = parser.parse_args(argv)
+
+    if args.command is None or getattr(args, "show_help", False):
+        from ..help import print_help
+        print_help()
+        return
+
+    try:
+        handler = {
+            "resolve": _cmd_resolve,
+            "context": _cmd_context,
+            "match": _cmd_match,
+            "init": _cmd_init,
+            "validate": _cmd_validate,
+            "stats": _cmd_stats,
+            "tree": _cmd_tree,
+            "health": _cmd_health,
+            "ingest": _cmd_ingest,
+            "impact": _cmd_impact,
+            "backtest": _cmd_backtest,
+            "observe": _cmd_observe,
+            "incremental": _cmd_incremental,
+            "hook": _cmd_hook,
+            "refresh": _cmd_refresh,
+            "utility": _cmd_utility,
+            "virtual": _cmd_virtual,
+            "lessons": _cmd_lessons,
+            "invariants": _cmd_invariants,
+            "rebuild": _cmd_rebuild,
+            "check": _cmd_check,
+            "intent": _cmd_intent,
+            "conventions": _cmd_conventions,
+            "diff": _cmd_diff,
+            "voice": _cmd_voice,
+            "test-compiler": _cmd_test_compiler,
+            "bench": _cmd_bench,
+            "debug": _cmd_debug,
+        }[args.command]
+        handler(args)
+    except (ValueError, FileNotFoundError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    finally:
+        warnings = consume_decode_warnings()
+        if warnings:
+            count = len(warnings)
+            noun = "file" if count == 1 else "files"
+            _safe_print(
+                f"dotscope: decoded {count} repo {noun} with replacement; "
+                "run `dotscope health` for details",
+                file=sys.stderr,
+            )
+
+def _print_counterfactual(ingest_result, backtest, violations):
+    """Format init output as a counterfactual story."""
+    scopes = ingest_result.get("scopes_written", 0) if isinstance(ingest_result, dict) else 0
+    contracts = ingest_result.get("contracts_found", 0) if isinstance(ingest_result, dict) else 0
+    conventions = ingest_result.get("conventions_found", 0) if isinstance(ingest_result, dict) else 0
+
+    recall = backtest.get("overall_recall", 0)
+
+    lines = [""]
+    lines.append(f"  {scopes} scopes, {contracts} contracts, {conventions} conventions, {recall:.0%} recall")
+    lines.append("")
+
+    if violations > 0:
+        lines.append(f"  What dotscope would have caught in your last 50 commits:")
+        lines.append(f"    {violations} files that agents would have missed")
+    lines.append("")
+    lines.append("  Your agents are ready.")
+    lines.append("")
+
+    print("\n".join(lines), file=sys.stderr)
+
+def _write_agent_instructions(root: str, quiet: bool = False):
+    """Write AGENT_INSTRUCTIONS.md to the target repo if it doesn't exist."""
+    target = os.path.join(root, "AGENT_INSTRUCTIONS.md")
+    if os.path.exists(target):
+        if not quiet:
+            print("dotscope: AGENT_INSTRUCTIONS.md already exists, skipping", file=sys.stderr)
+        return
+
+    # Load the template from the dotscope package
+    package_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    template = os.path.join(package_dir, "AGENT_INSTRUCTIONS.md")
+
+    if os.path.isfile(template):
+        import shutil
+        shutil.copy2(template, target)
+    else:
+        # Fallback: write a minimal version
+        with open(target, "w", encoding="utf-8") as f:
+            f.write("# dotscope Agent Instructions\n\n")
+            f.write("Start every task with `codebase_search`. Run `dotscope_check` before every commit.\n\n")
+            f.write("See https://github.com/nxrobins/dotscope for full documentation.\n")
+
+    if not quiet:
+        print("dotscope: AGENT_INSTRUCTIONS.md written", file=sys.stderr)
+
+def _print_summary(ingest_result):
+    """Fallback when backtest isn't available."""
+    print("", file=sys.stderr)
+    print("  Your agents are ready.", file=sys.stderr)
+    print("", file=sys.stderr)
+
+def _version():
+    from .. import __version__
+    return __version__
+
+if __name__ == "__main__":
+    main()