dotscope 0.1.0__py3-none-any.whl

dotscope/passes/lazy.py

@@ -0,0 +1,152 @@
+"""Lazy ingest: generate a single scope on demand when resolve can't find one.
+
+When an agent (or CLI) resolves a module that hasn't been ingested yet,
+this module builds a minimal scope from a partial graph and filtered history.
+Full ingest fills in transitive dependencies and cross-module contracts later.
+"""
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+from ..absorber import absorb_docs
+from ..context import parse_context
+from ..history import HistoryAnalysis, analyze_history
+from ..models.core import ScopeConfig
+from ..models.passes import PlannedScope
+from ..parser import serialize_scope
+from ..progress import ProgressEmitter
+from ..tokens import estimate_scope_tokens
+
+
+def lazy_ingest_module(
+    root: str,
+    module_name: str,
+    quiet: bool = True,
+) -> Optional[ScopeConfig]:
+    """Ingest a single module on demand.
+
+    Returns the ScopeConfig if successful, None if module dir doesn't exist.
+    """
+    module_name = module_name.rstrip("/")
+    module_path = os.path.join(root, module_name)
+    if not os.path.isdir(module_path):
+        return None
+
+    progress = ProgressEmitter(quiet=quiet)
+
+    # Collect module files
+    from .graph_builder import _collect_source_files, build_partial_graph
+    all_files = _collect_source_files(root)
+    module_files = [
+        (rel, lang) for rel, lang in all_files
+        if rel.startswith(module_name + "/") or rel.startswith(module_name + os.sep)
+    ]
+    if not module_files:
+        return None
+
+    # Partial graph: module files + one level of imports
+    progress.start(f"lazy ingest {module_name}/ (graph)")
+    graph = build_partial_graph(root, module_files)
+    progress.finish(f"{len(graph.files)} files")
+
+    # Filtered history: recent commits touching this module
+    progress.start(f"lazy ingest {module_name}/ (history)")
+    history = HistoryAnalysis()
+    try:
+        history = analyze_history(
+            root, max_commits=50, paths=[module_name + "/"],
+        )
+    except Exception:
+        pass
+    progress.finish(f"{history.commits_analyzed} commits")
+
+    # Synthesize one scope
+    scope_path = os.path.join(root, module_name, ".scope")
+    includes = [module_name + "/"]
+
+    # Add cross-module imports from the partial graph
+    for path, node in graph.files.items():
+        if path.startswith(module_name + "/"):
+            for imp in node.imports:
+                if not imp.startswith(module_name + "/") and imp not in includes:
+                    includes.append(imp)
+
+    # Context from history
+    context_parts = []
+    if history.implicit_contracts:
+        context_parts.append("## Implicit Contracts (from git history)")
+        for ic in history.implicit_contracts[:5]:
+            context_parts.append(f"- {ic.description}")
+
+    # Stability
+    stability_lines = []
+    for rel, _ in module_files:
+        fh = history.file_histories.get(rel)
+        if fh and fh.stability and fh.commit_count >= 3:
+            stability_lines.append(
+                f"- {os.path.basename(rel)}: {fh.stability} ({fh.commit_count} commits)"
+            )
+    if stability_lines:
+        context_parts.append("## Stability")
+        context_parts.extend(stability_lines[:10])
+
+    if not context_parts:
+        context_parts.append(
+            f"{module_name} module — {len(module_files)} files."
+        )
+
+    context = parse_context("\n".join(context_parts))
+
+    # Tags
+    tags = [module_name.lower()]
+
+    # Token estimate
+    full_paths = [os.path.join(root, rel) for rel, _ in module_files]
+    token_est = estimate_scope_tokens(full_paths)
+
+    config = ScopeConfig(
+        path=scope_path,
+        description=f"{module_name} module ({len(module_files)} files)",
+        includes=includes,
+        excludes=[f"{module_name}/__pycache__/", "*.pyc"],
+        context=context,
+        related=[],
+        owners=[],
+        tags=tags,
+        tokens_estimate=token_est,
+    )
+
+    # Write scope file
+    os.makedirs(os.path.dirname(scope_path), exist_ok=True)
+    content = serialize_scope(config)
+    with open(scope_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+    # Update .scopes index
+    from ..ingest import append_to_index
+    planned = PlannedScope(
+        directory=module_name,
+        config=config,
+        confidence=0.5,
+        signals=["lazy: on-demand ingest"],
+    )
+    try:
+        append_to_index(root, planned)
+    except Exception:
+        pass  # Index update is best-effort
+
+    # Mark that a full re-ingest is needed
+    dot_dir = os.path.join(root, ".dotscope")
+    os.makedirs(dot_dir, exist_ok=True)
+    marker = os.path.join(dot_dir, "needs_full_ingest")
+    Path(marker).touch()
+
+    if not quiet:
+        print(
+            f"dotscope: {module_name}/ scoped on demand",
+            file=sys.stderr,
+        )
+
+    return config

dotscope/passes/semantic_diff.py

@@ -0,0 +1,160 @@
+"""Semantic diff: translate git diff into convention-level structural changes."""
+
+import os
+import subprocess
+from typing import Dict, List, Optional
+
+from ..models import ConventionNode, ConventionRule, FileAnalysis, SemanticDiffReport
+from .convention_parser import parse_conventions
+
+
+def semantic_diff(
+    diff_text: str,
+    repo_root: str,
+    conventions: List[ConventionRule],
+) -> SemanticDiffReport:
+    """Translate a git diff into convention-level changes.
+
+    Parses the AST at two points in time:
+      1. HEAD commit (using `git show HEAD:<file>` for each modified file)
+      2. Working directory (current files on disk)
+
+    Compares the ConventionNode graphs to determine structural changes.
+    """
+    modified_files = _extract_modified_files(diff_text)
+    if not modified_files or not conventions:
+        return SemanticDiffReport()
+
+    # Parse conventions at HEAD
+    head_ast = {}
+    for filepath in modified_files:
+        source = _git_show_head(repo_root, filepath)
+        if source:
+            analysis = _parse_source(source, filepath)
+            if analysis:
+                head_ast[filepath] = analysis
+
+    nodes_before = parse_conventions(head_ast, conventions)
+
+    # Parse conventions at working directory
+    working_ast = {}
+    for filepath in modified_files:
+        full_path = os.path.join(repo_root, filepath)
+        if os.path.exists(full_path):
+            try:
+                with open(full_path, "r", encoding="utf-8") as f:
+                    source = f.read()
+                analysis = _parse_source(source, filepath)
+                if analysis:
+                    working_ast[filepath] = analysis
+            except (IOError, UnicodeDecodeError):
+                pass
+
+    nodes_after = parse_conventions(working_ast, conventions)
+
+    before_map = {(n.file_path, n.name): n for n in nodes_before}
+    after_map = {(n.file_path, n.name): n for n in nodes_after}
+
+    added = []
+    removed = []
+    modified = []
+
+    for key, node in after_map.items():
+        if key not in before_map:
+            added.append(node)
+        elif before_map[key].violations != node.violations:
+            modified.append((before_map[key], node))
+
+    for key, node in before_map.items():
+        if key not in after_map:
+            removed.append(node)
+
+    all_upheld = all(not n.violations for n in after_map.values())
+
+    return SemanticDiffReport(
+        added=added,
+        removed=removed,
+        modified=modified,
+        all_conventions_upheld=all_upheld,
+    )
+
+
+def format_semantic_diff(report: SemanticDiffReport) -> str:
+    """Format a SemanticDiffReport for terminal output."""
+    lines = ["Semantic Diff:"]
+
+    for node in report.added:
+        lines.append(f"  [ADDED]    {node.name}: {node.file_path}")
+    for node in report.removed:
+        lines.append(f"  [REMOVED]  {node.name}: {node.file_path}")
+    for before, after in report.modified:
+        lines.append(f"  [MODIFIED] {after.name}: {after.file_path}")
+        for v in after.violations:
+            lines.append(f"             ! {v}")
+    for dep in report.dependency_changes:
+        lines.append(f"  [MODIFIED] Dependency: {dep}")
+
+    lines.append("")
+    if report.all_conventions_upheld:
+        lines.append("  Conventions: All upheld")
+    else:
+        violation_count = sum(
+            len(n.violations) for n in
+            [node for _, node in report.modified] +
+            report.added
+        )
+        lines.append(f"  Conventions: {violation_count} violation(s)")
+
+    if report.counterfactual:
+        lines.append("")
+        lines.append(f"  {report.counterfactual}")
+
+    return "\n".join(lines)
+
+
+def _extract_modified_files(diff_text: str) -> List[str]:
+    """Extract file paths from unified diff."""
+    files = []
+    for line in diff_text.splitlines():
+        if line.startswith("diff --git"):
+            parts = line.split(" b/", 1)
+            if len(parts) > 1:
+                filepath = parts[1]
+                if filepath not in files:
+                    files.append(filepath)
+    return files
+
+
+def _git_show_head(repo_root: str, filepath: str) -> Optional[str]:
+    """Get file content at HEAD."""
+    try:
+        result = subprocess.run(
+            ["git", "show", f"HEAD:{filepath}"],
+            cwd=repo_root, capture_output=True, text=True, timeout=5,
+        )
+        if result.returncode == 0:
+            return result.stdout
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+    return None
+
+
+def _parse_source(source: str, filepath: str) -> Optional[FileAnalysis]:
+    """Parse source code into FileAnalysis."""
+    try:
+        from .ast_analyzer import analyze_file
+        import tempfile
+        # Write to temp file for analyze_file (it reads from disk)
+        ext = os.path.splitext(filepath)[1]
+        lang = {".py": "python", ".js": "javascript", ".ts": "typescript", ".go": "go"}.get(ext)
+        if not lang:
+            return None
+        with tempfile.NamedTemporaryFile(mode="w", suffix=ext, delete=False, encoding="utf-8") as tf:
+            tf.write(source)
+            tf.flush()
+            try:
+                return analyze_file(tf.name, lang)
+            finally:
+                os.unlink(tf.name)
+    except Exception:
+        return None

dotscope/passes/sentinel/__init__.py

@@ -0,0 +1 @@
+"""Architectural enforcement for dotscope."""

dotscope/passes/sentinel/acknowledge.py

@@ -0,0 +1,222 @@
+"""Acknowledgment recording and confidence decay."""
+
+import json
+import os
+import time
+from typing import Dict, List, Optional
+
+# Defaults (overridable via .dotscope/config.yaml)
+DECAY_RATE = 0.1
+DECAY_THRESHOLD = 3
+DECAY_WINDOW_DAYS = 30
+MIN_CONFIDENCE = 0.3
+
+
+def record_acknowledgment(
+    repo_root: str,
+    ack_id: str,
+    reason: str,
+    session_id: Optional[str] = None,
+) -> dict:
+    """Record an acknowledgment in .dotscope/acknowledgments.jsonl."""
+    dot_dir = os.path.join(repo_root, ".dotscope")
+    os.makedirs(dot_dir, exist_ok=True)
+
+    entry = {
+        "id": ack_id,
+        "reason": reason,
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "session_id": session_id or "",
+    }
+
+    path = os.path.join(dot_dir, "acknowledgments.jsonl")
+    with open(path, "a", encoding="utf-8") as f:
+        f.write(json.dumps(entry) + "\n")
+
+    return entry
+
+
+def load_acknowledgments(repo_root: str) -> List[dict]:
+    """Load all acknowledgments."""
+    path = os.path.join(repo_root, ".dotscope", "acknowledgments.jsonl")
+    if not os.path.exists(path):
+        return []
+
+    entries = []
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    return entries
+
+
+def is_acknowledged(repo_root: str, ack_id: str) -> bool:
+    """Check if a hold has been acknowledged.
+
+    Returns True if previously acknowledged AND confidence has not
+    decayed below the HOLD threshold (0.5). Constraints acknowledged
+    3+ times within 30 days lose confidence — below 0.5 they become
+    NOTEs instead of HOLDs, so this returns False (not "acknowledged"
+    as a HOLD pass-through).
+    """
+    acks = load_acknowledgments(repo_root)
+    if not any(a["id"] == ack_id for a in acks):
+        return False
+
+    # Apply decay: if confidence drops below 0.5, the constraint
+    # should remain active (as a NOTE), not be silently passed
+    confidence = compute_decayed_confidence(1.0, ack_id, acks)
+    return confidence >= 0.5
+
+
+def compute_decayed_confidence(
+    base_confidence: float,
+    ack_id: str,
+    acknowledgments: List[dict],
+) -> float:
+    """Apply confidence decay based on repeated acknowledgments.
+
+    After DECAY_THRESHOLD acknowledgments within DECAY_WINDOW_DAYS,
+    each additional acknowledgment drops confidence by DECAY_RATE.
+    Never drops below MIN_CONFIDENCE.
+    """
+    now = time.time()
+    window_seconds = DECAY_WINDOW_DAYS * 86400
+
+    recent = [
+        a for a in acknowledgments
+        if a.get("id") == ack_id and _parse_timestamp(a.get("timestamp", "")) > now - window_seconds
+    ]
+
+    count = len(recent)
+    if count <= DECAY_THRESHOLD:
+        return base_confidence
+
+    excess = count - DECAY_THRESHOLD
+    decayed = base_confidence - (excess * DECAY_RATE)
+    return max(decayed, MIN_CONFIDENCE)
+
+
+# ---------------------------------------------------------------------------
+# Gap 3: NUDGE escalation — repeated nudges become guards
+# ---------------------------------------------------------------------------
+
+ESCALATION_THRESHOLD = 3  # nudge fires this many times → escalate to GUARD
+ESCALATION_WINDOW_DAYS = 30
+
+
+def record_nudge_occurrence(repo_root: str, check_id: str) -> None:
+    """Track that a nudge fired. Used for escalation tracking."""
+    if not check_id:
+        return
+    dot_dir = os.path.join(repo_root, ".dotscope")
+    os.makedirs(dot_dir, exist_ok=True)
+
+    entry = {
+        "id": check_id,
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+
+    path = os.path.join(dot_dir, "nudge_occurrences.jsonl")
+    with open(path, "a", encoding="utf-8") as f:
+        f.write(json.dumps(entry) + "\n")
+
+
+def record_nudge_resolution(repo_root: str, check_id: str) -> None:
+    """Record that a nudge's underlying issue was fixed.
+
+    Resets the escalation counter so the nudge doesn't instantly
+    re-escalate if the issue recurs later.
+    """
+    if not check_id:
+        return
+    dot_dir = os.path.join(repo_root, ".dotscope")
+    os.makedirs(dot_dir, exist_ok=True)
+
+    entry = {
+        "id": check_id,
+        "resolved": True,
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+
+    path = os.path.join(dot_dir, "nudge_occurrences.jsonl")
+    with open(path, "a", encoding="utf-8") as f:
+        f.write(json.dumps(entry) + "\n")
+
+
+def is_escalated(repo_root: str, check_id: str) -> bool:
+    """Has this nudge been ignored enough times to escalate to GUARD?
+
+    3+ occurrences within 30 days *since the last resolution* means
+    the agent is ignoring the guidance. Escalate.
+
+    If the issue was resolved (nudge stopped firing) and then recurred,
+    the counter restarts from the resolution point.
+    """
+    if not check_id:
+        return False
+    path = os.path.join(repo_root, ".dotscope", "nudge_occurrences.jsonl")
+    if not os.path.exists(path):
+        return False
+
+    now = time.time()
+    window = ESCALATION_WINDOW_DAYS * 86400
+
+    # Find the last resolution timestamp for this check
+    last_resolved = 0.0
+    count = 0
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                    if entry.get("id") != check_id:
+                        continue
+                    ts = _parse_timestamp(entry.get("timestamp", ""))
+                    if entry.get("resolved"):
+                        last_resolved = max(last_resolved, ts)
+                except json.JSONDecodeError:
+                    continue
+    except IOError:
+        return False
+
+    # Count occurrences after last resolution and within window
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                    if entry.get("id") != check_id:
+                        continue
+                    if entry.get("resolved"):
+                        continue
+                    ts = _parse_timestamp(entry.get("timestamp", ""))
+                    if ts > last_resolved and ts > now - window:
+                        count += 1
+                except json.JSONDecodeError:
+                    continue
+    except IOError:
+        return False
+
+    return count >= ESCALATION_THRESHOLD
+
+
+def _parse_timestamp(ts: str) -> float:
+    """Parse ISO timestamp to epoch seconds."""
+    try:
+        from datetime import datetime
+        dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        return dt.timestamp()
+    except (ValueError, AttributeError):
+        return 0.0