dotscope 0.1.0__py3-none-any.whl

dotscope/models/.scope

@@ -0,0 +1,45 @@
+description: Data models — the single source of truth for all types
+includes:
+  - core.py
+  - history.py
+  - intent.py
+  - state.py
+  - passes.py
+context: |
+  Five domain files. Each owns a distinct category of data.
+  Models NEVER import from functional modules — they are the foundation.
+
+  ## core.py — Static Architecture
+  ScopeConfig, FileAnalysis, DependencyGraph, FileNode, ResolvedImport,
+  ExportedSymbol, ClassInfo, FunctionInfo, ModuleBoundary.
+  What the codebase IS right now.
+
+  ## history.py — Empirical Behavior
+  ImplicitContract, FileHistory, ChangeCoupling, HistoryAnalysis.
+  How the codebase behaves over time. Mined from git.
+
+  ## intent.py — Human Rulebook
+  IntentDirective, Assertion, ContextExhaustionError, CheckResult,
+  ProposedFix, Severity, CheckCategory, Constraint, WarningPair, NearMiss.
+  How the codebase MUST be treated. Enforcement targets.
+
+  ## state.py — Persistent Memory
+  SessionLog, ObservationLog, BenchReport, RegressionCase, BisectionResult,
+  FileUtilityScore, Lesson, ObservedInvariant, Counterfactual, SessionStats.
+  Schemas for .dotscope/ JSON event logs.
+
+  ## passes.py — Transient Outputs
+  IngestPlan, PlannedScope, VirtualScope.
+  DTOs that live only during a single operation.
+
+  ## Gotchas
+  The old dotscope/models.py is a backward-compat re-export facade.
+  New code should import from dotscope.models (the package), not the file.
+related:
+  - dotscope/passes/.scope
+  - dotscope/storage/.scope
+tags:
+  - models
+  - dataclasses
+  - types
+tokens_estimate: 4500

dotscope/models/__init__.py

@@ -0,0 +1,7 @@
+"""Unified model facade: re-exports all data models from sub-modules."""
+
+from .core import *  # noqa: F401,F403
+from .history import *  # noqa: F401,F403
+from .intent import *  # noqa: F401,F403
+from .state import *  # noqa: F401,F403
+from .passes import *  # noqa: F401,F403

dotscope/models/core.py

@@ -0,0 +1,288 @@
+"""Core data models: the static architecture of a codebase."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class StructuredContext:
+    """Context with optional named sections (## headers within the context block)."""
+
+    raw: str
+    sections: Dict[str, str] = field(default_factory=dict)
+
+    def query(self, section: Optional[str] = None) -> str:
+        if section is None:
+            return self.raw
+        key = section.lower().strip()
+        for name, content in self.sections.items():
+            if name.lower() == key:
+                return content
+        return ""
+
+    def __str__(self) -> str:
+        return self.raw
+
+
+@dataclass
+class ScopeConfig:
+    """Parsed .scope file."""
+
+    path: str  # Absolute path to the .scope file
+    description: str
+    includes: List[str] = field(default_factory=list)
+    excludes: List[str] = field(default_factory=list)
+    context: Optional[StructuredContext] = None
+    related: List[str] = field(default_factory=list)
+    owners: List[str] = field(default_factory=list)
+    tags: List[str] = field(default_factory=list)
+    tokens_estimate: Optional[int] = None
+
+    @property
+    def context_str(self) -> str:
+        if self.context is None:
+            return ""
+        return self.context.raw
+
+    @property
+    def directory(self) -> str:
+        """Directory containing this .scope file."""
+        import os
+
+        return os.path.dirname(self.path)
+
+
+@dataclass
+class ScopeEntry:
+    """Entry in the .scopes index file."""
+
+    name: str
+    path: str
+    keywords: List[str] = field(default_factory=list)
+    description: Optional[str] = None
+
+
+@dataclass
+class ScopesIndex:
+    """Parsed .scopes index file (repo root)."""
+
+    version: int = 1
+    scopes: Dict[str, ScopeEntry] = field(default_factory=dict)
+    defaults: Dict[str, object] = field(default_factory=dict)
+    total_repo_tokens: int = 0
+
+    @property
+    def max_tokens(self) -> int:
+        return int(self.defaults.get("max_tokens", 8000))
+
+    @property
+    def include_related(self) -> bool:
+        return bool(self.defaults.get("include_related", False))
+
+
+@dataclass
+class ResolvedScope:
+    """Result of resolving a scope to concrete files."""
+
+    files: List[str] = field(default_factory=list)
+    context: str = ""
+    token_estimate: int = 0
+    scope_chain: List[str] = field(default_factory=list)
+    truncated: bool = False
+    excluded_files: List[str] = field(default_factory=list)
+
+    def merge(self, other: "ResolvedScope") -> "ResolvedScope":
+        """Merge two resolved scopes (union)."""
+        seen = set(self.files)
+        merged_files = list(self.files)
+        for f in other.files:
+            if f not in seen:
+                merged_files.append(f)
+                seen.add(f)
+
+        ctx_parts = [p for p in [self.context, other.context] if p]
+        return ResolvedScope(
+            files=merged_files,
+            context="\n\n".join(ctx_parts),
+            token_estimate=self.token_estimate + other.token_estimate,
+            scope_chain=list(dict.fromkeys(self.scope_chain + other.scope_chain)),
+            truncated=self.truncated or other.truncated,
+        )
+
+    def subtract(self, other: "ResolvedScope") -> "ResolvedScope":
+        """Remove files present in other scope."""
+        other_set = set(other.files)
+        return ResolvedScope(
+            files=[f for f in self.files if f not in other_set],
+            context=self.context,
+            token_estimate=0,  # recalculated after
+            scope_chain=self.scope_chain,
+            truncated=self.truncated,
+        )
+
+    def intersect(self, other: "ResolvedScope") -> "ResolvedScope":
+        """Keep only files present in both scopes."""
+        other_set = set(other.files)
+        ctx_parts = [p for p in [self.context, other.context] if p]
+        return ResolvedScope(
+            files=[f for f in self.files if f in other_set],
+            context="\n\n".join(ctx_parts),
+            token_estimate=0,
+            scope_chain=list(dict.fromkeys(self.scope_chain + other.scope_chain)),
+            truncated=self.truncated or other.truncated,
+        )
+
+
+@dataclass
+class TokenBudget:
+    """Token budget for progressive file loading."""
+
+    max_tokens: int
+    context_reserved: int = 0
+    remaining: int = 0
+
+    def __post_init__(self):
+        self.remaining = self.max_tokens - self.context_reserved
+
+
+# ---------------------------------------------------------------------------
+# AST analysis models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ResolvedImport:
+    """A single import statement, resolved to its structural meaning."""
+    raw: str
+    module: str = ""                       # Top-level module (e.g., "auth")
+    resolved_path: Optional[str] = None    # Target file path, or None if external
+    names: List[str] = field(default_factory=list)
+    is_relative: bool = False
+    is_star: bool = False
+    is_conditional: bool = False
+    is_type_only: bool = False             # Inside TYPE_CHECKING block
+    line: int = 0
+
+
+@dataclass
+class ExportedSymbol:
+    """A symbol exported by a module."""
+    name: str
+    kind: str  # "function", "class", "constant", "variable"
+    is_public: bool = True
+
+
+@dataclass
+class ClassInfo:
+    """Structural summary of a class definition."""
+    name: str
+    bases: List[str] = field(default_factory=list)
+    methods: List[str] = field(default_factory=list)
+    method_count: int = 0
+    decorators: List[str] = field(default_factory=list)
+    is_abstract: bool = False
+    is_public: bool = True
+    line: int = 0
+
+
+@dataclass
+class FunctionInfo:
+    """Structural summary of a function definition."""
+    name: str
+    params: List[str] = field(default_factory=list)
+    arg_count: int = 0
+    return_type: Optional[str] = None
+    decorators: List[str] = field(default_factory=list)
+    is_public: bool = True
+    is_async: bool = False
+    complexity: int = 0                    # Count of if/for/while/try in body
+    line: int = 0
+
+
+@dataclass
+class FileAnalysis:
+    """Complete structural analysis of a single source file."""
+    path: str
+    language: str
+    imports: List[ResolvedImport] = field(default_factory=list)
+    exports: List[ExportedSymbol] = field(default_factory=list)
+    classes: List[ClassInfo] = field(default_factory=list)
+    functions: List[FunctionInfo] = field(default_factory=list)
+    decorators_used: List[str] = field(default_factory=list)  # All unique decorators
+    is_init: bool = False                  # True for __init__.py
+    reexports: List[str] = field(default_factory=list)  # Imported then re-exported
+    node_count: int = 0                    # Total AST nodes (complexity proxy)
+    docstring: Optional[str] = None
+    all_list: Optional[List[str]] = None
+    is_entry_point: bool = False
+
+    @property
+    def public_api(self) -> List[str]:
+        if self.all_list is not None:
+            return self.all_list
+        names = []
+        for cls in self.classes:
+            if cls.is_public:
+                names.append(cls.name)
+        for fn in self.functions:
+            if fn.is_public:
+                names.append(fn.name)
+        for exp in self.exports:
+            if exp.is_public and exp.name not in names:
+                names.append(exp.name)
+        return names
+
+    @property
+    def import_paths(self) -> List[str]:
+        return [i.resolved_path for i in self.imports if i.resolved_path]
+
+
+# Keep ModuleAPI as alias for backward compatibility during migration
+ModuleAPI = FileAnalysis
+
+
+# ---------------------------------------------------------------------------
+# Graph dataclasses (data only, no builder functions)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class FileNode:
+    """A file in the dependency graph."""
+    path: str  # Relative to root
+    language: str
+    imports: List[str] = field(default_factory=list)
+    imported_by: List[str] = field(default_factory=list)
+    api: Optional[ModuleAPI] = None
+
+
+@dataclass
+class ModuleBoundary:
+    """A detected module boundary (candidate scope)."""
+    directory: str
+    files: List[str] = field(default_factory=list)
+    internal_edges: int = 0
+    external_edges: int = 0
+    external_deps: List[str] = field(default_factory=list)
+    depended_on_by: List[str] = field(default_factory=list)
+    cohesion: float = 0.0
+    churn: int = 0
+    hotspot_files: List[str] = field(default_factory=list)
+
+
+@dataclass
+class DependencyGraph:
+    """Full dependency graph of a codebase."""
+    root: str
+    files: Dict[str, FileNode] = field(default_factory=dict)
+    edges: List[tuple] = field(default_factory=list)
+    modules: List[ModuleBoundary] = field(default_factory=list)
+    apis: Dict[str, ModuleAPI] = field(default_factory=dict)
+
+
+@dataclass
+class ConventionNode:
+    """A file's membership in a convention, with any rule violations."""
+    name: str          # Convention name, e.g. "REST Controller"
+    file_path: str
+    target_name: str   # Class or function name
+    violations: List[str] = field(default_factory=list)
+    matched_by: List[str] = field(default_factory=list)  # Which criteria matched

dotscope/models/history.py

@@ -0,0 +1,73 @@
+"""History data models: the empirical ledger from git mining."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Tuple
+
+
+@dataclass
+class FileChange:
+    """A file changed in a commit, with line counts."""
+    path: str
+    insertions: int = 0
+    deletions: int = 0
+
+    @property
+    def magnitude(self) -> int:
+        return self.insertions + self.deletions
+
+
+@dataclass
+class CommitInfo:
+    """A single git commit."""
+    hash: str
+    timestamp: str
+    message: str
+    files: List[str] = field(default_factory=list)
+    changes: List[FileChange] = field(default_factory=list)
+
+    @property
+    def total_lines(self) -> int:
+        return sum(c.magnitude for c in self.changes)
+
+
+@dataclass
+class FileHistory:
+    """History stats for a single file."""
+    path: str
+    commit_count: int = 0
+    total_lines_changed: int = 0
+    last_modified: str = ""
+    stability: str = ""  # "stable", "volatile", "tweaked"
+
+
+@dataclass
+class ChangeCoupling:
+    """Two files that frequently change together."""
+    file_a: str
+    file_b: str
+    co_changes: int  # How many commits touch both
+    total_a: int  # Total commits touching A
+    total_b: int  # Total commits touching B
+    coupling_strength: float = 0.0  # co_changes / min(total_a, total_b)
+
+
+@dataclass
+class ImplicitContract:
+    """An observed pattern: when X changes, Y always changes too."""
+    trigger_file: str
+    coupled_file: str
+    confidence: float  # How often Y changes when X changes
+    occurrences: int
+    description: str = ""
+
+
+@dataclass
+class HistoryAnalysis:
+    """Full git history analysis results."""
+    commits_analyzed: int = 0
+    file_histories: Dict[str, FileHistory] = field(default_factory=dict)
+    hotspots: List[Tuple[str, int]] = field(default_factory=list)  # (file, churn)
+    change_couplings: List[ChangeCoupling] = field(default_factory=list)
+    implicit_contracts: List[ImplicitContract] = field(default_factory=list)
+    recent_summaries: Dict[str, List[str]] = field(default_factory=dict)  # module -> commit messages
+    module_churn: Dict[str, int] = field(default_factory=dict)  # module -> total changes

dotscope/models/intent.py

@@ -0,0 +1,213 @@
+"""Intent data models: the human rulebook for enforcement."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional
+
+
+class Severity(Enum):
+    GUARD = "guard"  # Blocks commit. Protective wall.
+    NUDGE = "nudge"  # Prints warning. Does not block. Course correction.
+    NOTE = "note"    # Informational.
+    HOLD = "hold"    # Backwards compat — treated same as GUARD
+
+    @property
+    def blocks_commit(self) -> bool:
+        return self.value in ("guard", "hold")
+
+
+class CheckCategory(Enum):
+    BOUNDARY = "boundary_violation"
+    CONTRACT = "implicit_contract"
+    ANTIPATTERN = "anti_pattern"
+    DIRECTION = "dependency_direction"
+    STABILITY = "stability_concern"
+    INTENT = "architectural_intent"
+    CONVENTION = "convention_violation"
+    VOICE = "voice_violation"
+
+
+@dataclass
+class IntentDirective:
+    """A declared architectural intent."""
+    directive: str  # "decouple", "deprecate", "freeze", "consolidate"
+    modules: List[str] = field(default_factory=list)
+    files: List[str] = field(default_factory=list)
+    reason: str = ""
+    replacement: Optional[str] = None
+    target: Optional[str] = None
+    set_by: str = "developer"
+    set_at: str = ""
+    id: str = ""  # Auto-generated slug
+
+
+@dataclass
+class Constraint:
+    """A single constraint surfaced during resolve_scope (prophylactic mode)."""
+    category: str  # "contract", "anti_pattern", "dependency_boundary", "stability", "intent"
+    message: str
+    file: Optional[str] = None
+    confidence: float = 1.0
+    metadata: Dict[str, object] = field(default_factory=dict)
+
+
+@dataclass
+class ProposedFix:
+    """A machine-generated fix proposal the agent can apply."""
+    file: str
+    reason: str
+    predicted_sections: List[str] = field(default_factory=list)
+    proposed_diff: Optional[str] = None  # Unified diff
+    confidence: float = 0.5
+
+
+@dataclass
+class CheckResult:
+    """A single check finding."""
+    passed: bool
+    category: CheckCategory
+    severity: Severity
+    message: str
+    detail: str = ""
+    file: Optional[str] = None
+    suggestion: Optional[str] = None
+    proposed_fix: Optional[ProposedFix] = None
+    can_acknowledge: bool = False
+    acknowledge_id: Optional[str] = None
+
+
+@dataclass
+class CheckReport:
+    """Aggregate report from all checks against a diff."""
+    passed: bool
+    results: List[CheckResult] = field(default_factory=list)
+    files_checked: int = 0
+    checks_run: int = 0
+
+    @property
+    def guards(self) -> List[CheckResult]:
+        return [r for r in self.results if not r.passed and r.severity.blocks_commit]
+
+    @property
+    def nudges(self) -> List[CheckResult]:
+        return [r for r in self.results if not r.passed and r.severity == Severity.NUDGE]
+
+    @property
+    def notes(self) -> List[CheckResult]:
+        return [r for r in self.results if not r.passed and r.severity == Severity.NOTE]
+
+    @property
+    def holds(self) -> List[CheckResult]:
+        """Backwards compat alias for guards."""
+        return self.guards
+
+
+# ---------------------------------------------------------------------------
+# Assertions
+# ---------------------------------------------------------------------------
+
+class ContextExhaustionError(Exception):
+    """Token budget cannot satisfy required assertions."""
+
+    def __init__(
+        self,
+        assertion_type: str,
+        detail: str,
+        file: Optional[str] = None,
+        file_tokens: int = 0,
+        budget: int = 0,
+        tokens_used: int = 0,
+        reason: str = "",
+        suggestion: str = "",
+    ):
+        self.assertion_type = assertion_type
+        self.detail = detail
+        self.file = file
+        self.file_tokens = file_tokens
+        self.budget = budget
+        self.tokens_used = tokens_used
+        self.reason = reason
+        self.suggestion = suggestion
+        super().__init__(detail)
+
+    def to_dict(self) -> dict:
+        return {
+            "error": "context_exhaustion",
+            "assertion_failed": {
+                "type": self.assertion_type,
+                "detail": self.detail,
+                "file": self.file,
+                "file_tokens": self.file_tokens,
+                "budget": self.budget,
+                "reason": self.reason,
+            },
+            "suggestion": self.suggestion,
+        }
+
+
+@dataclass
+class Assertion:
+    """A single architectural assertion."""
+    scope: str = "*"  # Scope name or "*" for all
+    ensure_includes: List[str] = field(default_factory=list)
+    ensure_context_contains: List[str] = field(default_factory=list)
+    ensure_constraints: bool = False
+    reason: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Near-miss dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass
+class WarningPair:
+    """An extracted (anti_pattern, safe_pattern) pair from scope context."""
+    anti_pattern: str
+    safe_pattern: str
+    context_line: str
+    scope: str
+
+
+@dataclass
+class NearMiss:
+    """A detected near-miss event."""
+    scope: str
+    event: str
+    context_used: str
+    potential_impact: str
+
+
+# ---------------------------------------------------------------------------
+# Convention dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ConventionRule:
+    """A structural convention: discovered or hand-authored."""
+    name: str
+    source: str = "discovered"  # "discovered" | "hand_authored"
+    match_criteria: Dict[str, list] = field(default_factory=dict)  # {"any_of": [...], "all_of": [...]}
+    rules: Dict[str, object] = field(default_factory=dict)  # {"prohibited_imports": [...], ...}
+    description: str = ""
+    compliance: float = 1.0
+    last_checked: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Voice dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass
+class DiscoveredVoice:
+    """Coding style profile: discovered from codebase or prescriptive defaults."""
+    mode: str = "adaptive"  # "prescriptive" | "adaptive"
+    rules: Dict[str, str] = field(default_factory=dict)
+    stats: Dict[str, float] = field(default_factory=dict)
+    enforce: Dict[str, object] = field(default_factory=dict)
+
+
+@dataclass
+class CanonicalExample:
+    """A representative file for a convention's coding style."""
+    file_path: str = ""
+    snippet: Optional[str] = None

dotscope/models/passes.py

@@ -0,0 +1,58 @@
+"""Pass data models: ephemeral outputs from analysis passes."""
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from .core import ConventionNode, DependencyGraph, ScopeConfig, ScopesIndex, ScopeEntry
+from .history import HistoryAnalysis
+from .intent import ConventionRule
+from .state import BacktestReport
+
+
+@dataclass
+class IngestPlan:
+    """Plan for .scope files to be created."""
+    root: str
+    scopes: List["PlannedScope"] = field(default_factory=list)
+    index: Optional[ScopesIndex] = None
+    graph_summary: str = ""
+    history_summary: str = ""
+    backtest_summary: str = ""
+    # Structured data for discovery rendering
+    graph: Optional[DependencyGraph] = None
+    history: Optional[HistoryAnalysis] = None
+    backtest_report: Optional[BacktestReport] = None
+    virtual_scopes: List[ScopeConfig] = field(default_factory=list)
+    discovered_conventions: List[ConventionRule] = field(default_factory=list)
+    total_repo_files: int = 0
+    total_repo_tokens: int = 0
+
+
+@dataclass
+class PlannedScope:
+    """A .scope file to be created."""
+    directory: str  # Relative to root
+    config: ScopeConfig
+    confidence: float  # How confident we are in this scope boundary
+    signals: List[str]  # What signals contributed to this scope
+
+
+@dataclass
+class VirtualScope:
+    """A detected cross-cutting scope."""
+    name: str
+    hub_file: str
+    files: List[str]
+    cohesion: float
+    directories_spanned: int
+
+
+@dataclass
+class SemanticDiffReport:
+    """Structural diff translated to convention-level changes."""
+    added: List[ConventionNode] = field(default_factory=list)
+    removed: List[ConventionNode] = field(default_factory=list)
+    modified: List[tuple] = field(default_factory=list)  # (before, after) pairs
+    dependency_changes: List[str] = field(default_factory=list)
+    all_conventions_upheld: bool = True
+    counterfactual: Optional[str] = None