dotscope 1.2.0__tar.gz → 1.2.2__tar.gz

{dotscope-1.2.0 → dotscope-1.2.2}/.github/workflows/python-publish.yml

@@ -49,7 +49,7 @@ jobs:
     # Dedicated environments with protections for publishing are strongly recommended.
     # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
     environment:
-      name: pypi
+      name: dotscope environment
       # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
       # url: https://pypi.org/p/YOURPROJECT
       #

dotscope-1.2.2/CLAUDE.md

@@ -0,0 +1,10 @@
+# CLAUDE.md
+
+This repo uses dotscope. Before touching code:
+
+1. `codebase_search("your task description")` — not manual file reads
+2. `dotscope_check` before every commit
+3. If check returns HOLDs, fix them before committing
+
+dotscope provides: dependency graph, implicit contracts, conventions,
+and file locks. Use its tools instead of guessing.

dotscope-1.2.2/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: dotscope
+Version: 1.2.2
+Summary: Agents see files. You see architecture. dotscope gives agents the architecture.
+Author: Supremum
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,coding,context,mcp,scope
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: tree-sitter-go>=0.23.0
+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: numpy; extra == 'all'
+Requires-Dist: sentence-transformers; extra == 'all'
+Requires-Dist: tiktoken; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+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'
+Provides-Extra: search
+Requires-Dist: numpy; extra == 'search'
+Requires-Dist: sentence-transformers; extra == 'search'
+Provides-Extra: tokens
+Requires-Dist: tiktoken; extra == 'tokens'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="logo.png" alt="dotscope" width="400">
+</p>
+
+Your agent writes code that compiles, passes tests, and breaks production.
+
+It changed a backend endpoint without touching the frontend that calls it.
+It put a file in `src/helpers/` instead of next to the module that uses it.
+It ignored the convention every other file follows. Two agents working at
+the same time silently overwrote each other.
+
+The agent sees files. You see architecture. dotscope closes that gap.
+
+```
+$ dotscope ingest
+
+  Analyzing dependency graph...
+  Mining git history...
+  Discovering conventions...
+
+  Discoveries:
+  - version.py and environment.prod.ts always change together
+  - workflow-edit-dialog.component.ts and models.py are tightly coupled
+
+  Validation (49 commits backtested):
+  - Overall recall: 78%
+  - Token reduction: 67% (1.3M → 437K avg)
+
+  Output: 3 .scope files written.
+```
+
+One MCP tool call. The agent gets the relevant code, its dependency
+neighborhood, implicit contracts from git history, convention rules,
+swarm lock status, and action hints. One call, not five.
+
+dotscope learns from every commit. Files agents consistently need get
+ranked higher. Conventions that hold get enforced harder. Rules that
+get overridden get quieter. Recall starts at 78% and climbs past 91%.
+
+```
+pip install dotscope && dotscope init
+```
+
+Zero dependencies. Python 3.9+ stdlib only. MIT.
+
+[How It Works](docs/how-it-works.md) · [Scope Files](docs/scope-file.md) · [Agent Instructions](AGENT_INSTRUCTIONS.md) · [MIT](LICENSE)

dotscope-1.2.2/README.md

@@ -0,0 +1,46 @@
+<p align="center">
+  <img src="logo.png" alt="dotscope" width="400">
+</p>
+
+Your agent writes code that compiles, passes tests, and breaks production.
+
+It changed a backend endpoint without touching the frontend that calls it.
+It put a file in `src/helpers/` instead of next to the module that uses it.
+It ignored the convention every other file follows. Two agents working at
+the same time silently overwrote each other.
+
+The agent sees files. You see architecture. dotscope closes that gap.
+
+```
+$ dotscope ingest
+
+  Analyzing dependency graph...
+  Mining git history...
+  Discovering conventions...
+
+  Discoveries:
+  - version.py and environment.prod.ts always change together
+  - workflow-edit-dialog.component.ts and models.py are tightly coupled
+
+  Validation (49 commits backtested):
+  - Overall recall: 78%
+  - Token reduction: 67% (1.3M → 437K avg)
+
+  Output: 3 .scope files written.
+```
+
+One MCP tool call. The agent gets the relevant code, its dependency
+neighborhood, implicit contracts from git history, convention rules,
+swarm lock status, and action hints. One call, not five.
+
+dotscope learns from every commit. Files agents consistently need get
+ranked higher. Conventions that hold get enforced harder. Rules that
+get overridden get quieter. Recall starts at 78% and climbs past 91%.
+
+```
+pip install dotscope && dotscope init
+```
+
+Zero dependencies. Python 3.9+ stdlib only. MIT.
+
+[How It Works](docs/how-it-works.md) · [Scope Files](docs/scope-file.md) · [Agent Instructions](AGENT_INSTRUCTIONS.md) · [MIT](LICENSE)

{dotscope-1.2.0/.claude/worktrees/hopeful-chatelet → dotscope-1.2.2}/dotscope/__init__.py

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

{dotscope-1.2.0/.claude/worktrees/hopeful-chatelet → dotscope-1.2.2}/dotscope/cli.py

@@ -354,12 +354,18 @@ def _cmd_init(args):
     except Exception as e:
         print(f"dotscope: MCP config failed: {e}", file=sys.stderr)
 
-    # 4. Write AGENT_INSTRUCTIONS.md
+    # 4. Write AGENT_INSTRUCTIONS.md + CLAUDE.md
     try:
         _write_agent_instructions(root, quiet)
     except Exception as e:
         if not quiet:
             print(f"dotscope: agent instructions failed: {e}", file=sys.stderr)
+    try:
+        from .storage.claude_hooks import write_claude_md
+        write_claude_md(root)
+    except Exception as e:
+        if not quiet:
+            print(f"dotscope: CLAUDE.md failed: {e}", file=sys.stderr)
 
     # 5. Backtest as counterfactual demo
     if not quiet:

{dotscope-1.2.0/.claude/worktrees/hopeful-chatelet → dotscope-1.2.2}/dotscope/constants.py

@@ -2,20 +2,44 @@
 
 # Directories to always skip when walking a codebase
 SKIP_DIRS = frozenset({
+    # Version control
     ".git",
+    # Package managers
     "node_modules",
+    "vendor",
+    # Python
     "__pycache__",
     "venv",
     ".venv",
     "env",
     ".env",
-    "dist",
-    "build",
     ".tox",
     ".mypy_cache",
     ".ruff_cache",
     ".eggs",
     ".pytest_cache",
+    # Build output
+    "dist",
+    "build",
+    "out",
+    "target",
+    "bin",
+    "obj",
+    # JS/TS frameworks
+    ".next",
+    ".nuxt",
+    ".output",
+    ".parcel-cache",
+    # Caches
+    ".cache",
+    ".gradle",
+    ".terraform",
+    # Test/coverage output
+    "coverage",
+    "test-results",
+    # dotscope / Claude
+    ".dotscope",
+    ".claude",
 })
 
 # Source file extensions

{dotscope-1.2.0 → dotscope-1.2.2}/dotscope/formatter.py

@@ -57,7 +57,7 @@ def _format_plain(resolved: ResolvedScope, root: Optional[str], show_tokens: boo
 
 
 def _format_json(resolved: ResolvedScope, root: Optional[str]) -> str:
-    """JSON format: full object."""
+    """JSON format: full object with all compiled retrieval fields."""
     data = {
         "files": [make_relative(f, root) for f in resolved.files],
         "context": resolved.context,
@@ -69,6 +69,18 @@ def _format_json(resolved: ResolvedScope, root: Optional[str]) -> str:
     if resolved.excluded_files:
         data["excluded_count"] = len(resolved.excluded_files)
 
+    # Compiled retrieval fields (populated by codebase_search)
+    if resolved.flattened_abstractions:
+        data["flattened_abstractions"] = resolved.flattened_abstractions
+    if resolved.constraints:
+        data["constraints"] = resolved.constraints
+    if resolved.routing:
+        data["routing"] = resolved.routing
+    if resolved.action_hints:
+        data["action_hints"] = resolved.action_hints
+    if resolved.retrieval_metadata:
+        data["retrieval_metadata"] = resolved.retrieval_metadata
+
     return json.dumps(data, indent=2)
 
 

{dotscope-1.2.0/.claude/worktrees/hopeful-chatelet → dotscope-1.2.2}/dotscope/generate/engine.py

@@ -118,8 +118,8 @@ def _load_config(root: str) -> GenerateConfig:
         return GenerateConfig()
 
     try:
-        from ..parser import _parse_yaml_simple
-        data = _parse_yaml_simple(config_path.read_text(encoding="utf-8"))
+        from ..parser import _parse_yaml
+        data = _parse_yaml(config_path.read_text(encoding="utf-8"))
         gen = data.get("generate", {})
         return GenerateConfig(
             output_dir=gen.get("output_dir", "docs/dotscope"),

dotscope-1.2.2/dotscope/ignore.py

@@ -0,0 +1,59 @@
+""".dotscopeignore support — gitignore-style exclusion patterns.
+
+Loaded once at scan start, passed through the pipeline. No per-file IO.
+"""
+
+import fnmatch
+import os
+from pathlib import Path
+from typing import List
+
+
+def load_ignore_patterns(repo_root: str) -> List[str]:
+    """Load .dotscopeignore patterns. Returns empty list if no file."""
+    ignore_path = os.path.join(repo_root, ".dotscopeignore")
+    if not os.path.exists(ignore_path):
+        return []
+
+    patterns = []
+    try:
+        with open(ignore_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                patterns.append(line)
+    except (IOError, OSError):
+        return []
+    return patterns
+
+
+def should_skip(
+    path: str,
+    skip_dirs: frozenset,
+    ignore_patterns: List[str],
+) -> bool:
+    """Check if a path should be skipped.
+
+    Order: hardcoded skip_dirs first (O(1) lookup),
+    then .dotscopeignore patterns (glob matching).
+    """
+    parts = Path(path).parts
+    for part in parts:
+        if part in skip_dirs:
+            return True
+
+    for pattern in ignore_patterns:
+        if fnmatch.fnmatch(path, pattern):
+            return True
+        # Directory patterns: "renderer/target/" matches any file under it
+        if pattern.endswith("/"):
+            dir_prefix = pattern.rstrip("/")
+            if path.startswith(dir_prefix + "/") or path.startswith(dir_prefix + os.sep):
+                return True
+            # Also match against any path component
+            for part in parts:
+                if fnmatch.fnmatch(part, dir_prefix):
+                    return True
+
+    return False

{dotscope-1.2.0/.claude/worktrees/hopeful-chatelet → dotscope-1.2.2}/dotscope/ingest.py

@@ -29,6 +29,26 @@ from .paths import (
 from .tokens import estimate_scope_tokens
 
 
+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 _log_ingest_error(root: str, message: str) -> None:
+    """Append error to .dotscope/error.log for debugging."""
+    try:
+        log_dir = os.path.join(root, ".dotscope")
+        os.makedirs(log_dir, exist_ok=True)
+        import time
+        with open(os.path.join(log_dir, "error.log"), "a", encoding="utf-8") as f:
+            f.write(f"[{time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())}] {message}\n")
+    except Exception:
+        pass  # Logging failure should never block ingest
+
+
 def ingest(
     root: str,
     mine_history: bool = True,
@@ -168,8 +188,8 @@ def ingest(
             artifacts_path = os.path.join(root, ".dotscope_artifacts.yaml")
             if os.path.isfile(artifacts_path):
                 try:
-                    from .parser import _parse_yaml_simple
-                    artifacts_data = _parse_yaml_simple(
+                    from .parser import _parse_yaml
+                    artifacts_data = _parse_yaml(
                         open(artifacts_path, "r", encoding="utf-8").read()
                     )
                     for artifact in artifacts_data.get("artifacts", []):
@@ -191,13 +211,41 @@ def ingest(
                 except Exception:
                     pass
 
+            # Cap chunk count to prevent OOM on large repos
+            max_chunks = getattr(args, "max_chunks", 50_000) if args else 50_000
+            if len(all_chunks) > max_chunks:
+                # Prefer source files over tests/configs
+                def _chunk_priority(c):
+                    p = c.file_path.lower()
+                    if "/test" in p or p.startswith("test"):
+                        return 2
+                    if any(p.endswith(e) for e in (".json", ".yaml", ".yml", ".toml")):
+                        return 1
+                    return 0
+                all_chunks.sort(key=lambda c: (_chunk_priority(c), c.file_path))
+                _safe_print(
+                    f"dotscope: {len(all_chunks)} chunks exceeds limit,"
+                    f" keeping top {max_chunks}",
+                    file=sys.stderr,
+                )
+                all_chunks = all_chunks[:max_chunks]
+
             if all_chunks:
                 index = build_vector_index(root, all_chunks)
                 progress.finish(f"{index.chunk_count} chunks, {index.model_name}")
             else:
                 progress.finish("0 chunks")
         except Exception as e:
-            progress.finish(f"skipped ({e})")
+            import traceback
+            _safe_print(
+                f"dotscope: search index failed: {e}\n"
+                f"  Scopes still work. Search will be unavailable.\n"
+                f"  Try: dotscope ingest . --max-chunks 25000",
+                file=sys.stderr,
+            )
+            # Log full traceback for debugging
+            _log_ingest_error(root, traceback.format_exc())
+            progress.finish("failed")
 
     # Step 4: Synthesize scope files
     progress.start("generating scopes")

{dotscope-1.2.0 → dotscope-1.2.2}/dotscope/mcp_server.py

@@ -1256,7 +1256,20 @@ def main():
             task_type=task_type,
             no_observe=no_observe or False,
         )
-        return format_resolved(resolved, fmt="json", root=root)
+        result = json.loads(format_resolved(resolved, fmt="json", root=root))
+
+        # Add next_steps based on what was found
+        next_steps = []
+        if resolved.constraints:
+            next_steps.append("Run dotscope_check before committing.")
+            if any(c.get("severity") == "GUARD" for c in resolved.constraints):
+                next_steps.append("GUARD-level constraints found. These will block your commit.")
+        if result.get("retrieval_metadata", {}).get("index_freshness") == "stale":
+            next_steps.append("Index is stale. Run dotscope ingest to refresh.")
+        if next_steps:
+            result["next_steps"] = next_steps
+
+        return json.dumps(result, indent=2)
 
     # -------------------------------------------------------------------
     # Swarm Lock MCP tools
@@ -1453,5 +1466,112 @@ def _route_by_imports(planned_imports: list, root: str) -> Optional[dict]:
     }
 
 
+    # -------------------------------------------------------------------
+    # Swarm helpers
+    # -------------------------------------------------------------------
+
+    def _find_root():
+        from .discovery import find_repo_root
+        return find_repo_root() or "."
+
+    def _get_graph(root):
+        from .passes.graph_builder import build_graph
+        return build_graph(root)
+
+    def _load_index(root):
+        from .discovery import load_index
+        return load_index(root)
+
+    def _load_invariants(root):
+        inv_path = os.path.join(root, ".dotscope", "invariants.json")
+        if os.path.isfile(inv_path):
+            try:
+                with open(inv_path, "r", encoding="utf-8") as f:
+                    return json.load(f)
+            except Exception:
+                pass
+        return {}
+
+    # -------------------------------------------------------------------
+    # Swarm Intelligence MCP tools
+    # -------------------------------------------------------------------
+
+    @mcp.tool()
+    def partition_search_space(
+        intent: str,
+        n_partitions: int = 3,
+    ) -> dict:
+        """Divide an exploratory task into non-overlapping starting points.
+
+        Uses semantic search to find relevant files, then graph analysis
+        to cleave them into decoupled partitions. Scouts assigned to
+        different partitions are guaranteed to start in structurally
+        independent domains.
+
+        Args:
+            intent: Natural language description of what to investigate
+            n_partitions: Number of parallel scouts to support (2-10)
+
+        May return fewer partitions than requested if search results
+        are highly localized. Check len(partitions), not n_partitions.
+        """
+        from .swarm.partition import partition_search_space as _partition
+        root = _root or _find_root()
+        graph = _get_graph(root)
+        index = _load_index(root)
+        invariants = _load_invariants(root)
+        return _partition(intent, n_partitions, root, graph, index, invariants)
+
+    @mcp.tool()
+    def resolve_trace(
+        entry_file: str,
+        max_depth: int = 3,
+        focus: str = "",
+    ) -> dict:
+        """Resolve context along a specific execution path.
+
+        Follows imports from entry_file up to max_depth. Returns unified
+        context covering all scopes crossed, deduplicated, with only the
+        constraints relevant to files in the trace.
+
+        Args:
+            entry_file: Starting point for the trace
+            max_depth: How many import levels to follow (default 3, max 10)
+            focus: Optional keyword to filter context relevance
+                   (e.g., "memory" to prioritize memory-related context)
+        """
+        from .swarm.trace import resolve_trace as _trace
+        root = _root or _find_root()
+        graph = _get_graph(root)
+        index = _load_index(root)
+        invariants = _load_invariants(root)
+        return _trace(
+            entry_file, max_depth, focus or None,
+            root, graph, index, invariants,
+        )
+
+    @mcp.tool()
+    def merge_scout_findings(
+        scout_reports: list,
+    ) -> dict:
+        """Cross-reference scout findings against codebase physics.
+
+        Takes raw scout reports (flagged files + notes) and returns
+        structurally validated connections, convergence points,
+        and a unified blast radius.
+
+        Each scout report should contain:
+          scout_id: int
+          flagged_files: List[str]
+          notes: str (natural language findings)
+          confidence: float (0-1, scout's self-assessed confidence)
+        """
+        from .swarm.merge import merge_scout_findings as _merge
+        root = _root or _find_root()
+        graph = _get_graph(root)
+        invariants = _load_invariants(root)
+        return _merge(scout_reports, root, graph, invariants)
+
+
 if __name__ == "__main__":
     main()

{dotscope-1.2.0 → dotscope-1.2.2}/dotscope/models/core.py

@@ -94,6 +94,10 @@ class ResolvedScope:
     # Compiled Retrieval extensions (populated by codebase_search only)
     flattened_abstractions: Dict[str, dict] = field(default_factory=dict)
     retrieval_metadata: Optional[dict] = None
+    # Structured constraints (contracts, anti-patterns, conventions, intents)
+    constraints: List[dict] = field(default_factory=list)
+    # Routing guidance (convention blueprints, voice rules)
+    routing: List[dict] = field(default_factory=list)
     # Action hints: imperative directives derived from constraints and locks
     action_hints: List[str] = field(default_factory=list)
 

{dotscope-1.2.0/.claude/worktrees/hopeful-chatelet → dotscope-1.2.2}/dotscope/passes/graph_builder.py

@@ -14,6 +14,7 @@ from ..ast_analyzer import (
     resolve_python_import,
 )
 from ..constants import LANG_MAP, SKIP_DIRS
+from ..ignore import load_ignore_patterns, should_skip
 from ..models.core import (
     DependencyGraph,
     FileNode,
@@ -201,15 +202,25 @@ def transitive_dependents(graph: DependencyGraph, file: str) -> Set[str]:
 def _collect_source_files(root: str) -> List[Tuple[str, str]]:
     """Walk the tree and collect (relative_path, language)."""
     lang_map = {k: v.lower() for k, v in LANG_MAP.items()}
+    ignore_patterns = load_ignore_patterns(root)
     results = []
 
     for dirpath, dirnames, filenames in os.walk(root):
-        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        dirnames[:] = [
+            d for d in dirnames
+            if d not in SKIP_DIRS
+            and not should_skip(
+                os.path.relpath(os.path.join(dirpath, d), root),
+                SKIP_DIRS,
+                ignore_patterns,
+            )
+        ]
         for fn in filenames:
             ext = os.path.splitext(fn)[1].lower()
             if ext in lang_map:
                 rel = normalize_relative_path(os.path.relpath(os.path.join(dirpath, fn), root))
-                results.append((rel, lang_map[ext]))
+                if not should_skip(rel, frozenset(), ignore_patterns):
+                    results.append((rel, lang_map[ext]))
 
     return sorted(results)
 

{dotscope-1.2.0 → dotscope-1.2.2}/dotscope/scanner.py

@@ -12,6 +12,7 @@ from typing import List, Optional, Set, Tuple
 
 from .constants import LANG_MAP, SKIP_DIRS
 from .context import parse_context
+from .ignore import load_ignore_patterns, should_skip
 from .models import ScopeConfig
 from .tokens import estimate_file_tokens
 
@@ -100,11 +101,27 @@ def _scan_files(path: str) -> Tuple[List[str], Counter, int]:
     lang_counts: Counter = Counter()
     total_tokens = 0
 
+    # Load .dotscopeignore patterns from the repo root (or nearest parent)
+    ignore_patterns = load_ignore_patterns(path)
+
     for dirpath, dirnames, filenames in os.walk(path):
-        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        dirnames[:] = [
+            d for d in dirnames
+            if d not in SKIP_DIRS
+            and not should_skip(
+                os.path.relpath(os.path.join(dirpath, d), path),
+                SKIP_DIRS,
+                ignore_patterns,
+            )
+        ]
 
         for filename in filenames:
             full = os.path.join(dirpath, filename)
+            rel = os.path.relpath(full, path)
+
+            if should_skip(rel, frozenset(), ignore_patterns):
+                continue
+
             files.append(full)
 
             ext = os.path.splitext(filename)[1].lower()

{dotscope-1.2.0/.claude/worktrees/hopeful-chatelet → dotscope-1.2.2}/dotscope/search/retriever.py

@@ -283,12 +283,30 @@ def _dense_search(query: str, embeddings, limit: int = 50) -> List[Tuple[int, fl
         return []
 
 
-def _embed_texts(texts: List[str]):
-    """Embed texts using sentence-transformers. Returns numpy array or None."""
+def _embed_texts(texts: List[str], batch_size: int = 512):
+    """Embed texts in batches using sentence-transformers. Returns numpy array or None."""
     try:
         from sentence_transformers import SentenceTransformer
+        import numpy as np
+
         model = SentenceTransformer("all-MiniLM-L6-v2")
-        return model.encode(texts, show_progress_bar=False, convert_to_numpy=True)
+
+        if len(texts) <= batch_size:
+            return model.encode(texts, show_progress_bar=False, convert_to_numpy=True)
+
+        # Batch to avoid OOM on large repos
+        all_embeddings = []
+        for i in range(0, len(texts), batch_size):
+            batch = texts[i:i + batch_size]
+            try:
+                embeddings = model.encode(batch, show_progress_bar=False, convert_to_numpy=True)
+                all_embeddings.append(embeddings)
+            except Exception:
+                continue  # Skip failed batch, keep going
+
+        if not all_embeddings:
+            return None
+        return np.vstack(all_embeddings)
     except ImportError:
         return None