dotscope 0.1.0__py3-none-any.whl

dotscope/models/state.py

@@ -0,0 +1,250 @@
+"""State data models: the persistent memory layer."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set
+
+
+# ---------------------------------------------------------------------------
+# Observation layer models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SessionLog:
+    """Records a single scope resolution event (the prediction)."""
+    session_id: str
+    timestamp: float
+    scope_expr: str
+    task: Optional[str] = None
+    predicted_files: List[str] = field(default_factory=list)
+    context_hash: str = ""
+
+
+@dataclass
+class ObservationLog:
+    """Records what actually happened after a resolution (the outcome)."""
+    commit_hash: str
+    session_id: str
+    actual_files_modified: List[str] = field(default_factory=list)
+    predicted_not_touched: List[str] = field(default_factory=list)
+    touched_not_predicted: List[str] = field(default_factory=list)
+    recall: float = 0.0
+    precision: float = 0.0
+    timestamp: float = 0.0
+
+
+# ---------------------------------------------------------------------------
+# Health models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class HealthIssue:
+    """A single health issue found during scope analysis."""
+    scope_path: str
+    severity: str  # "error", "warning", "info"
+    category: str  # "staleness", "coverage", "drift", "broken_path"
+    message: str
+
+
+@dataclass
+class HealthReport:
+    """Full health report across all scopes."""
+    issues: List[HealthIssue] = field(default_factory=list)
+    scopes_checked: int = 0
+    directories_total: int = 0
+    directories_covered: int = 0
+
+    @property
+    def coverage_pct(self) -> float:
+        if self.directories_total == 0:
+            return 100.0
+        return (self.directories_covered / self.directories_total) * 100
+
+    @property
+    def errors(self) -> List[HealthIssue]:
+        return [i for i in self.issues if i.severity == "error"]
+
+    @property
+    def warnings(self) -> List[HealthIssue]:
+        return [i for i in self.issues if i.severity == "warning"]
+
+
+# ---------------------------------------------------------------------------
+# Backtest models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class MissingSuggestion:
+    """A file that should be added to a scope's includes."""
+    path: str
+    appearances: int
+    would_improve_recall: bool = True
+
+
+@dataclass
+class BacktestResult:
+    """Backtest result for a single scope."""
+    scope_path: str
+    total_commits: int = 0
+    fully_covered: int = 0
+    recall: float = 0.0
+    missing_includes: List[MissingSuggestion] = field(default_factory=list)
+
+
+@dataclass
+class BacktestReport:
+    """Full backtest report across all scopes."""
+    results: List[BacktestResult] = field(default_factory=list)
+    total_commits: int = 0
+    overall_recall: float = 0.0
+
+
+# ---------------------------------------------------------------------------
+# Bench
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BenchReport:
+    # Token efficiency
+    avg_tokens_resolved: int = 0
+    avg_tokens_used: int = 0
+    efficiency_ratio: float = 0.0
+
+    # Hold rate
+    total_commits: int = 0
+    commits_with_holds: int = 0
+    holds_acknowledged: int = 0
+    effective_hold_rate: float = 0.0
+
+    # Compilation speed
+    resolve_median_ms: float = 0.0
+    resolve_p95_ms: float = 0.0
+    check_median_ms: float = 0.0
+    check_p95_ms: float = 0.0
+
+    # Scope health
+    scopes_above_80_recall: int = 0
+    total_scopes: int = 0
+    stale_scopes: int = 0
+    avg_observations: float = 0.0
+
+
+# ---------------------------------------------------------------------------
+# Regression
+# ---------------------------------------------------------------------------
+
+@dataclass
+class RegressionCase:
+    """A frozen successful session used as a regression test."""
+    id: str
+    scope_expr: str
+    budget: Optional[int] = None
+    task: Optional[str] = None
+    expected_files: List[str] = field(default_factory=list)
+    expected_context_hash: str = ""
+    actual_recall: float = 0.0
+    timestamp: str = ""
+
+
+@dataclass
+class ReplayResult:
+    """Result of replaying a regression case against current state."""
+    case: RegressionCase
+    new_files: List[str] = field(default_factory=list)
+    new_context_hash: str = ""
+    files_added: List[str] = field(default_factory=list)
+    files_dropped: List[str] = field(default_factory=list)
+    context_changed: bool = False
+    is_regression: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Debug
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BisectionResult:
+    """Root cause analysis of a bad agent session."""
+    session_id: str
+    files_that_mattered: List[str] = field(default_factory=list)
+    files_that_didnt_help: List[str] = field(default_factory=list)
+    context_sections_relevant: List[str] = field(default_factory=list)
+    context_sections_irrelevant: List[str] = field(default_factory=list)
+    constraints_honored: List[dict] = field(default_factory=list)
+    constraints_violated: List[dict] = field(default_factory=list)
+    missing_files: List[str] = field(default_factory=list)
+    diagnosis: str = ""  # "resolution_gap" | "constraint_gap" | "agent_ignored" | "context_conflict"
+    recommendations: List[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Visibility
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SessionStats:
+    """Raw stats accumulated during an MCP session."""
+    scopes_resolved: int = 0
+    tokens_served: int = 0
+    tokens_available: int = 0
+    context_fields_used: int = 0
+    attribution_hints_served: int = 0
+    health_warnings_surfaced: int = 0
+    unique_scopes: Set[str] = field(default_factory=set)
+    constraints_served: List[dict] = field(default_factory=list)
+    started_at: Optional[str] = None
+    last_activity: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Counterfactual
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Counterfactual:
+    """A bad thing that didn't happen because dotscope was there."""
+    type: str  # "anti_pattern_avoided", "contract_honored", "intent_respected"
+    description: str
+    source: str  # Where the knowledge came from
+    severity: str = "high"  # "high" or "medium"
+
+
+# ---------------------------------------------------------------------------
+# Utility
+# ---------------------------------------------------------------------------
+
+@dataclass
+class FileUtilityScore:
+    """Utility score for a single file, derived from observations."""
+    path: str
+    resolve_count: int = 0       # Sessions that included this file
+    touch_count: int = 0         # Observations where this file was modified
+    utility_ratio: float = 0.0   # touch_count / resolve_count
+    last_touched: float = 0.0
+    last_resolved: float = 0.0
+
+
+# ---------------------------------------------------------------------------
+# Lessons
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Lesson:
+    """A machine-generated lesson from observation patterns."""
+    trigger: str
+    observation: str
+    lesson_text: str
+    confidence: float
+    created: float
+    source_sessions: List[str] = field(default_factory=list)
+    acknowledged: bool = False
+
+
+@dataclass
+class ObservedInvariant:
+    """An evidence-based boundary constraint."""
+    boundary: str          # e.g., "auth -> payments"
+    direction: str         # "no_import"
+    held_since: str        # ISO date
+    commit_count: int
+    confidence: float
+    violations: List[str] = field(default_factory=list)

dotscope/models.py

@@ -0,0 +1,9 @@
+"""Core data models for dotscope.
+
+This file is a backward-compatibility facade. All dataclasses are now
+defined in dotscope/models/ sub-modules and re-exported here.
+"""
+
+# Re-export everything so `from dotscope.models import X` still works
+from .models.core import *  # noqa: F401,F403
+from .models.state import *  # noqa: F401,F403

dotscope/near_miss.py

@@ -0,0 +1,3 @@
+"""Backward-compatibility stub. Moved to dotscope.storage.near_miss."""
+from .storage.near_miss import *  # noqa: F401,F403
+from .models.intent import NearMiss, WarningPair  # noqa: F401

dotscope/onboarding.py

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

dotscope/parser.py

@@ -0,0 +1,387 @@
+"""Minimal YAML subset parser for .scope and .scopes files.
+
+Handles the subset needed: scalars, lists, block scalars (|), comments.
+No external dependencies.
+"""
+
+
+import os
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+from .context import parse_context
+from .models import ScopeConfig, ScopeEntry, ScopesIndex
+
+
+def parse_scope_file(path: str) -> ScopeConfig:
+    """Parse a .scope file into a ScopeConfig."""
+    path = os.path.abspath(path)
+    with open(path, "r", encoding="utf-8") as f:
+        text = f.read()
+
+    data = _parse_yaml(text)
+
+    description = data.get("description", "")
+    if not description:
+        raise ValueError(f"Missing required 'description' field in {path}")
+
+    context_raw = data.get("context", "")
+    context = parse_context(context_raw) if context_raw else None
+
+    tokens_est = data.get("tokens_estimate")
+    if tokens_est is not None:
+        tokens_est = int(tokens_est)
+
+    return ScopeConfig(
+        path=path,
+        description=str(description),
+        includes=_as_list(data.get("includes", [])),
+        excludes=_as_list(data.get("excludes", [])),
+        context=context,
+        related=_as_list(data.get("related", [])),
+        owners=_as_list(data.get("owners", [])),
+        tags=_as_list(data.get("tags", [])),
+        tokens_estimate=tokens_est,
+    )
+
+
+def parse_scopes_index(path: str) -> ScopesIndex:
+    """Parse a .scopes index file."""
+    path = os.path.abspath(path)
+    with open(path, "r", encoding="utf-8") as f:
+        text = f.read()
+
+    data = _parse_yaml(text)
+
+    version = int(data.get("version", 1))
+    defaults = data.get("defaults", {})
+    if isinstance(defaults, str):
+        defaults = {}
+
+    scopes_raw = data.get("scopes", {})
+    scopes = {}
+    if isinstance(scopes_raw, dict):
+        for name, entry_data in scopes_raw.items():
+            if isinstance(entry_data, dict):
+                keywords = entry_data.get("keywords", [])
+                if isinstance(keywords, str):
+                    # Handle inline [a, b, c] syntax
+                    keywords = _parse_inline_list(keywords)
+                scopes[name] = ScopeEntry(
+                    name=name,
+                    path=str(entry_data.get("path", "")),
+                    keywords=keywords,
+                    description=entry_data.get("description"),
+                )
+
+    total_repo_tokens = int(data.get("total_repo_tokens", 0))
+    return ScopesIndex(
+        version=version, scopes=scopes, defaults=defaults,
+        total_repo_tokens=total_repo_tokens,
+    )
+
+
+def serialize_scope(config: ScopeConfig) -> str:
+    """Serialize a ScopeConfig back to .scope YAML format."""
+    lines = []
+
+    lines.append(f"description: {config.description}")
+
+    if config.includes:
+        lines.append("includes:")
+        for inc in config.includes:
+            lines.append(f"  - {inc}")
+
+    if config.excludes:
+        lines.append("excludes:")
+        for exc in config.excludes:
+            if any(c in exc for c in "*?["):
+                lines.append(f'  - "{exc}"')
+            else:
+                lines.append(f"  - {exc}")
+
+    if config.context:
+        lines.append("context: |")
+        for line in config.context_str.splitlines():
+            lines.append(f"  {line}")
+
+    if config.related:
+        lines.append("related:")
+        for rel in config.related:
+            lines.append(f"  - {rel}")
+
+    if config.owners:
+        lines.append("owners:")
+        for owner in config.owners:
+            lines.append(f'  - "{owner}"')
+
+    if config.tags:
+        lines.append("tags:")
+        for tag in config.tags:
+            lines.append(f"  - {tag}")
+
+    if config.tokens_estimate is not None:
+        lines.append(f"tokens_estimate: {config.tokens_estimate}")
+
+    return "\n".join(lines) + "\n"
+
+
+# ---------------------------------------------------------------------------
+# Internal YAML subset parser
+# ---------------------------------------------------------------------------
+
+def _parse_yaml(text: str) -> Dict[str, Any]:
+    """Parse a YAML subset: scalars, lists, block scalars, nested maps (1 level)."""
+    result: Dict[str, Any] = {}
+    lines = text.splitlines()
+    i = 0
+
+    while i < len(lines):
+        line = lines[i]
+        stripped = _strip_comment(line)
+
+        # Skip blank / comment-only lines
+        if not stripped.strip():
+            i += 1
+            continue
+
+        indent = _indent_level(line)
+
+        # Only process top-level keys (indent 0)
+        if indent > 0:
+            i += 1
+            continue
+
+        key, value, i = _parse_key_value(lines, i)
+        if key is not None:
+            result[key] = value
+
+    return result
+
+
+def _parse_key_value(lines: List[str], i: int) -> Tuple[Optional[str], Any, int]:
+    """Parse a key-value pair starting at line i. Returns (key, value, next_i)."""
+    line = _strip_comment(lines[i]).strip()
+
+    m = re.match(r'^(["\']?)([^"\':\s][^"\':]*)(\1)\s*:\s*(.*)', line)
+    if not m:
+        return None, None, i + 1
+
+    key = m.group(2).strip()
+    rest = m.group(4).strip()
+
+    i += 1
+
+    # Block scalar: key: |
+    if rest == "|":
+        value, i = _parse_block_scalar(lines, i)
+        return key, value, i
+
+    # Check if next lines are list items or nested map
+    if not rest and i < len(lines):
+        next_stripped = _strip_comment(lines[i]).strip() if i < len(lines) else ""
+        if next_stripped.startswith("- "):
+            value, i = _parse_list(lines, i)
+            return key, value, i
+        elif ":" in next_stripped and not next_stripped.startswith("-"):
+            value, i = _parse_nested_map(lines, i)
+            return key, value, i
+
+    # Inline value
+    if rest:
+        # Inline list: [a, b, c]
+        if rest.startswith("[") and rest.endswith("]"):
+            return key, _parse_inline_list(rest), i
+
+        # Quoted string
+        if (rest.startswith('"') and rest.endswith('"')) or (
+            rest.startswith("'") and rest.endswith("'")
+        ):
+            return key, rest[1:-1], i
+
+        # Try numeric
+        try:
+            if "." in rest:
+                return key, float(rest), i
+            return key, int(rest), i
+        except ValueError:
+            pass
+
+        # Boolean
+        if rest.lower() in ("true", "yes"):
+            return key, True, i
+        if rest.lower() in ("false", "no"):
+            return key, False, i
+
+        return key, rest, i
+
+    return key, "", i
+
+
+def _parse_block_scalar(lines: List[str], i: int) -> Tuple[str, int]:
+    """Parse a block scalar (| style) starting at line i."""
+    block_lines = []
+    if i >= len(lines):
+        return "", i
+
+    # Determine base indent from first content line
+    base_indent = _indent_level(lines[i])
+    if base_indent == 0:
+        return "", i
+
+    while i < len(lines):
+        line = lines[i]
+        if not line.strip():
+            block_lines.append("")
+            i += 1
+            continue
+        current_indent = _indent_level(line)
+        if current_indent < base_indent:
+            break
+        block_lines.append(line[base_indent:])
+        i += 1
+
+    # Strip trailing empty lines
+    while block_lines and not block_lines[-1]:
+        block_lines.pop()
+
+    return "\n".join(block_lines), i
+
+
+def _parse_list(lines: List[str], i: int) -> Tuple[List[str], int]:
+    """Parse a YAML list starting at line i."""
+    items = []
+    if i >= len(lines):
+        return items, i
+
+    base_indent = _indent_level(lines[i])
+
+    while i < len(lines):
+        line = lines[i]
+        stripped = _strip_comment(line).strip()
+
+        if not stripped:
+            i += 1
+            continue
+
+        current_indent = _indent_level(line)
+        if current_indent < base_indent:
+            break
+
+        if stripped.startswith("- "):
+            item = stripped[2:].strip()
+            # Strip quotes
+            if (item.startswith('"') and item.endswith('"')) or (
+                item.startswith("'") and item.endswith("'")
+            ):
+                item = item[1:-1]
+            # Strip inline comments from list items (e.g., "payments/.scope  # shares user model")
+            comment_match = re.match(r'^([^#]*?)\s+#\s+.*$', item)
+            if comment_match:
+                item = comment_match.group(1).strip()
+            items.append(item)
+        elif current_indent > base_indent:
+            pass  # continuation line, skip
+        else:
+            break
+
+        i += 1
+
+    return items, i
+
+
+def _parse_nested_map(lines: List[str], i: int) -> Tuple[Dict[str, Any], int]:
+    """Parse a one-level nested map."""
+    result: Dict[str, Any] = {}
+    if i >= len(lines):
+        return result, i
+
+    base_indent = _indent_level(lines[i])
+
+    while i < len(lines):
+        line = lines[i]
+        stripped = _strip_comment(line).strip()
+
+        if not stripped:
+            i += 1
+            continue
+
+        current_indent = _indent_level(line)
+        if current_indent < base_indent:
+            break
+
+        if current_indent == base_indent:
+            # This is a nested key
+            key, value, i = _parse_key_value(lines, i)
+            if key is not None:
+                result[key] = value
+        else:
+            i += 1
+
+    return result, i
+
+
+def _parse_inline_list(text: str) -> List[str]:
+    """Parse [a, b, c] into a list. Handles quoted values containing commas."""
+    inner = text.strip()
+    if inner.startswith("["):
+        inner = inner[1:]
+    if inner.endswith("]"):
+        inner = inner[:-1]
+
+    # State-machine split: only split on commas outside quotes
+    items = []
+    current: List[str] = []
+    in_quote = None
+
+    for ch in inner:
+        if ch in ('"', "'"):
+            if in_quote == ch:
+                in_quote = None
+            elif in_quote is None:
+                in_quote = ch
+            else:
+                current.append(ch)
+            continue
+        if ch == "," and in_quote is None:
+            val = "".join(current).strip()
+            if val:
+                items.append(val)
+            current = []
+            continue
+        current.append(ch)
+
+    val = "".join(current).strip()
+    if val:
+        items.append(val)
+    return items
+
+
+def _strip_comment(line: str) -> str:
+    """Strip trailing # comments, respecting quotes."""
+    in_quote = None
+    for idx, ch in enumerate(line):
+        if ch in ('"', "'"):
+            if in_quote == ch:
+                in_quote = None
+            elif in_quote is None:
+                in_quote = ch
+        elif ch == "#" and in_quote is None:
+            # Only strip if preceded by whitespace or at start
+            if idx == 0 or line[idx - 1] in (" ", "\t"):
+                return line[:idx]
+    return line
+
+
+def _indent_level(line: str) -> int:
+    """Count leading spaces."""
+    return len(line) - len(line.lstrip(" "))
+
+
+def _as_list(val: Any) -> List[str]:
+    """Ensure a value is a list of strings."""
+    if isinstance(val, list):
+        return [str(v) for v in val]
+    if isinstance(val, str) and val:
+        return [val]
+    return []