dotscope 0.1.0__py3-none-any.whl

dotscope/passes/sentinel/checks/convention.py

@@ -0,0 +1,54 @@
+"""Convention drift detection: check modified files against conventions."""
+
+from typing import Dict, List
+
+from ..models import CheckCategory, CheckResult, ConventionRule, Severity
+from ....models.core import FileAnalysis
+from ...convention_compliance import convention_severity
+from ...convention_parser import check_convention_rules, matches_convention
+
+
+def check_conventions(
+    modified_files: List[str],
+    added_lines: Dict[str, List[str]],
+    conventions: List[ConventionRule],
+    ast_data: Dict[str, FileAnalysis],
+) -> List[CheckResult]:
+    """Check modified files for convention drift.
+
+    Returns HOLDs for conventions with >=80% compliance,
+    NOTEs for 50-79%, and skips retired conventions.
+    """
+    results = []
+
+    for filepath in modified_files:
+        analysis = ast_data.get(filepath)
+        if not analysis:
+            continue
+
+        for rule in conventions:
+            severity = convention_severity(rule.compliance)
+            if severity == "retired":
+                continue
+
+            if matches_convention(analysis, filepath, rule.match_criteria):
+                violations = check_convention_rules(analysis, filepath, rule.rules)
+                for v in violations:
+                    results.append(CheckResult(
+                        passed=False,
+                        category=CheckCategory.CONVENTION,
+                        severity=(
+                            Severity.NUDGE if severity in ("hold", "nudge")
+                            else Severity.NOTE
+                        ),
+                        message=f"Convention drift: {rule.name}",
+                        detail=(
+                            f"{filepath} is recognized as a '{rule.name}'.\n"
+                            f"Violation: {v}\n"
+                            f"Convention compliance: {rule.compliance:.0%}"
+                        ),
+                        file=filepath,
+                        suggestion=rule.description,
+                    ))
+
+    return results

dotscope/passes/sentinel/checks/direction.py

@@ -0,0 +1,71 @@
+"""Dependency direction check: new imports that reverse established flow."""
+
+import re
+from typing import Dict, List, Optional
+
+from ..models import CheckCategory, CheckResult, Severity
+
+
+def check_dependency_direction(
+    added_lines: Dict[str, List[str]],
+    graph_hubs: Dict[str, object],
+    scopes: Dict[str, dict],
+) -> List[CheckResult]:
+    """Detect new imports that reverse established dependency direction.
+
+    If models/ is imported BY api/ (not the other way around),
+    a new 'from api import ...' in models/ is a direction reversal.
+    """
+    results = []
+
+    # Build direction map from graph hubs: module → set of modules it imports
+    import_directions = {}  # type: Dict[str, set]
+    for hub_file, hub_data in graph_hubs.items():
+        if isinstance(hub_data, dict):
+            imported_by = hub_data.get("imported_by", [])
+            module = hub_file.split("/")[0] if "/" in hub_file else ""
+            if module:
+                for importer in imported_by:
+                    imp_module = importer.split("/")[0] if "/" in importer else ""
+                    if imp_module and imp_module != module:
+                        import_directions.setdefault(imp_module, set()).add(module)
+
+    if not import_directions:
+        return results
+
+    import_re = re.compile(
+        r'(?:from\s+(\S+)\s+import|import\s+(\S+))'
+    )
+
+    for filepath, lines in added_lines.items():
+        file_module = filepath.split("/")[0] if "/" in filepath else ""
+        if not file_module:
+            continue
+
+        for line_text in lines:
+            m = import_re.search(line_text)
+            if not m:
+                continue
+
+            imported = m.group(1) or m.group(2) or ""
+            imported_module = imported.split(".")[0]
+
+            if not imported_module or imported_module == file_module:
+                continue
+
+            # Check: does imported_module normally import file_module?
+            # If so, this new import reverses the established direction.
+            if file_module in import_directions.get(imported_module, set()):
+                results.append(CheckResult(
+                    passed=False,
+                    category=CheckCategory.DIRECTION,
+                    severity=Severity.NOTE,
+                    message=(
+                        f"New import in {filepath}: {imported_module} "
+                        f"is imported BY {file_module}, not the other way around"
+                    ),
+                    detail=f"{file_module}/ normally does not import from {imported_module}/",
+                    file=filepath,
+                ))
+
+    return results

dotscope/passes/sentinel/checks/intent.py

@@ -0,0 +1,207 @@
+"""Architectural intent checks: validate changes against declared direction."""
+
+import re
+from typing import Dict, List
+
+from ..models import CheckCategory, CheckResult, ProposedFix, Severity, IntentDirective
+
+
+def check_intent_holds(
+    modified_files: List[str],
+    added_lines: Dict[str, List[str]],
+    intents: List[IntentDirective],
+) -> List[CheckResult]:
+    """Check for HOLD-level intent violations (deprecate, freeze)."""
+    results = []
+
+    for intent in intents:
+        if intent.directive == "deprecate":
+            results.extend(_check_deprecate(added_lines, intent))
+        elif intent.directive == "freeze":
+            results.extend(_check_freeze(modified_files, intent))
+
+    return results
+
+
+def check_intent_notes(
+    modified_files: List[str],
+    added_lines: Dict[str, List[str]],
+    intents: List[IntentDirective],
+) -> List[CheckResult]:
+    """Check for NOTE-level intent violations (decouple, consolidate)."""
+    results = []
+
+    for intent in intents:
+        if intent.directive == "decouple":
+            results.extend(_check_decouple(added_lines, intent))
+        elif intent.directive == "consolidate":
+            results.extend(_check_consolidate(modified_files, intent))
+
+    return results
+
+
+def _check_deprecate(
+    added_lines: Dict[str, List[str]],
+    intent: IntentDirective,
+) -> List[CheckResult]:
+    """New usage of deprecated files is a HOLD."""
+    results = []
+    deprecated = set(intent.files)
+
+    import_re = re.compile(
+        r'(?:from\s+(\S+)\s+import|import\s+(\S+))'
+    )
+
+    from ..line_filter import strip_comments_and_strings
+
+    for filepath, lines in added_lines.items():
+        # Don't flag the deprecated file itself
+        if filepath in deprecated:
+            continue
+
+        for line_text in lines:
+            code_only = strip_comments_and_strings(line_text)
+            if not code_only.strip():
+                continue
+            m = import_re.search(code_only)
+            if not m:
+                continue
+            imported = (m.group(1) or m.group(2) or "").replace(".", "/")
+            for dep_file in deprecated:
+                dep_module = dep_file.replace(".py", "").replace("/", ".")
+                dep_path = dep_file.replace(".py", "")
+                if dep_module in (m.group(1) or "") or dep_path in imported:
+                    fix = None
+                    if intent.replacement:
+                        fix = ProposedFix(
+                            file=intent.replacement,
+                            reason=f"Use {intent.replacement} instead of {dep_file}",
+                            confidence=1.0,
+                        )
+                    results.append(CheckResult(
+                        passed=False,
+                        category=CheckCategory.INTENT,
+                        severity=Severity.GUARD,
+                        message=f"{dep_file} is deprecated: {intent.reason}",
+                        detail=f"New import in {filepath}",
+                        file=filepath,
+                        suggestion=f"Use {intent.replacement}" if intent.replacement else "Remove usage",
+                        proposed_fix=fix,
+                        can_acknowledge=True,
+                        acknowledge_id=f"intent_deprecate_{intent.id}",
+                    ))
+                    break
+
+    return results
+
+
+def _check_freeze(
+    modified_files: List[str],
+    intent: IntentDirective,
+) -> List[CheckResult]:
+    """Any change to frozen modules is a GUARD."""
+    results = []
+    frozen = set(intent.modules)
+
+    for filepath in modified_files:
+        for module in frozen:
+            if filepath.startswith(module):
+                results.append(CheckResult(
+                    passed=False,
+                    category=CheckCategory.INTENT,
+                    severity=Severity.GUARD,
+                    message=f"{module} is frozen: {intent.reason}",
+                    detail=f"Modified {filepath}",
+                    file=filepath,
+                    suggestion="Requires explicit acknowledgment to proceed",
+                    can_acknowledge=True,
+                    acknowledge_id=f"intent_freeze_{intent.id}",
+                ))
+                break
+
+    return results
+
+
+def _check_decouple(
+    added_lines: Dict[str, List[str]],
+    intent: IntentDirective,
+) -> List[CheckResult]:
+    """New coupling between decoupling-targeted modules is a NOTE."""
+    results = []
+    if len(intent.modules) < 2:
+        return results
+
+    modules = intent.modules
+    import_re = re.compile(
+        r'(?:from\s+(\S+)\s+import|import\s+(\S+))'
+    )
+
+    from ..line_filter import strip_comments_and_strings
+
+    for filepath, lines in added_lines.items():
+        file_module = _file_to_module(filepath)
+        if file_module not in modules:
+            continue
+
+        for line_text in lines:
+            code_only = strip_comments_and_strings(line_text)
+            if not code_only.strip():
+                continue
+            m = import_re.search(code_only)
+            if not m:
+                continue
+            imported = (m.group(1) or m.group(2) or "").split(".")[0]
+            imported_mod = imported + "/"
+            if imported_mod in modules and imported_mod != file_module:
+                results.append(CheckResult(
+                    passed=False,
+                    category=CheckCategory.INTENT,
+                    severity=Severity.NOTE,
+                    message=(
+                        f"New coupling: {file_module} -> {imported_mod} "
+                        f"(intent: decouple, set {intent.set_at})"
+                    ),
+                    detail=intent.reason,
+                    file=filepath,
+                ))
+                break  # One per file
+
+    return results
+
+
+def _check_consolidate(
+    modified_files: List[str],
+    intent: IntentDirective,
+) -> List[CheckResult]:
+    """Code moving away from consolidation target is a NOTE."""
+    results = []
+    if not intent.target or len(intent.modules) < 1:
+        return results
+
+    target = intent.target
+    source_modules = [m for m in intent.modules if m != target]
+
+    for filepath in modified_files:
+        for mod in source_modules:
+            if filepath.startswith(mod):
+                # A change to a source module (not moving toward target) is a note
+                results.append(CheckResult(
+                    passed=False,
+                    category=CheckCategory.INTENT,
+                    severity=Severity.NOTE,
+                    message=(
+                        f"Changes to {mod}, intent is to consolidate into {target} "
+                        f"(set {intent.set_at})"
+                    ),
+                    detail=intent.reason,
+                    file=filepath,
+                ))
+                break
+
+    return results
+
+
+def _file_to_module(filepath: str) -> str:
+    """Extract the top-level module directory from a file path."""
+    parts = filepath.split("/")
+    return parts[0] + "/" if len(parts) > 1 else ""

dotscope/passes/sentinel/checks/stability.py

@@ -0,0 +1,66 @@
+"""Stability concern check: large changes to stable files."""
+
+from typing import Dict, List
+
+from ..models import CheckCategory, CheckResult, Severity
+
+# Threshold: a file is "stable" and a change is "large" above this
+LARGE_CHANGE_LINES = 20
+
+
+def check_stability(
+    modified_files: List[str],
+    diff_text: str,
+    invariants: dict,
+) -> List[CheckResult]:
+    """Flag large changes to files classified as stable."""
+    stabilities = invariants.get("file_stabilities", {})
+    if not stabilities:
+        return []
+
+    # Count added lines per file in the diff
+    file_additions = _count_additions(diff_text)
+    results = []
+
+    for filepath in modified_files:
+        info = stabilities.get(filepath)
+        if not info:
+            continue
+
+        classification = info.get("classification", "")
+        if classification != "stable":
+            continue
+
+        additions = file_additions.get(filepath, 0)
+        if additions < LARGE_CHANGE_LINES:
+            continue
+
+        commit_count = info.get("commit_count", 0)
+        results.append(CheckResult(
+            passed=False,
+            category=CheckCategory.STABILITY,
+            severity=Severity.NOTE,
+            message=(
+                f"{filepath}: stable file ({commit_count} commits), "
+                f"this diff changes {additions} lines"
+            ),
+            detail="Large changes to stable files deserve extra review",
+            file=filepath,
+        ))
+
+    return results
+
+
+def _count_additions(diff_text: str) -> Dict[str, int]:
+    """Count added lines per file in a unified diff."""
+    counts: Dict[str, int] = {}
+    current_file = ""
+
+    for line in diff_text.splitlines():
+        if line.startswith("diff --git"):
+            parts = line.split(" b/", 1)
+            current_file = parts[1] if len(parts) > 1 else ""
+        elif line.startswith("+") and not line.startswith("+++") and current_file:
+            counts[current_file] = counts.get(current_file, 0) + 1
+
+    return counts

dotscope/passes/sentinel/checks/voice.py

@@ -0,0 +1,108 @@
+"""Voice check: bare excepts and missing type hints on new functions."""
+
+import ast
+import os
+from typing import Dict, List, Optional
+
+from ..models import CheckCategory, CheckResult, Severity
+
+
+def check_voice(
+    modified_files: List[str],
+    added_lines: Dict[str, List[str]],
+    voice_config: Optional[dict],
+    repo_root: str,
+) -> List[CheckResult]:
+    """Mechanical voice checks. Only fires for rules with enforce != false."""
+    if not voice_config:
+        return []
+
+    enforce = voice_config.get("enforce", {})
+    if not enforce:
+        return []
+
+    results = []
+
+    for filepath in modified_files:
+        if not filepath.endswith(".py"):
+            continue
+
+        full_path = os.path.join(repo_root, filepath)
+        if not os.path.isfile(full_path):
+            continue
+
+        try:
+            with open(full_path, "r", encoding="utf-8") as f:
+                source = f.read()
+            tree = ast.parse(source)
+        except (SyntaxError, IOError, UnicodeDecodeError):
+            continue
+
+        # Bare excepts
+        bare_level = enforce.get("bare_excepts")
+        if bare_level and bare_level is not False:
+            severity = Severity.NUDGE if bare_level == "hold" else Severity.NOTE
+            for node in ast.walk(tree):
+                if isinstance(node, ast.ExceptHandler) and node.type is None:
+                    results.append(CheckResult(
+                        passed=False,
+                        category=CheckCategory.VOICE,
+                        severity=severity,
+                        message=f"Bare except in {filepath}:{node.lineno}",
+                        detail="Catch a specific exception type.",
+                        file=filepath,
+                        suggestion="Replace `except:` with `except SpecificError:`",
+                    ))
+
+        # Missing type hints (only on new/modified functions)
+        hint_level = enforce.get("missing_type_hints")
+        if hint_level and hint_level is not False:
+            severity = Severity.NUDGE if hint_level == "hold" else Severity.NOTE
+
+            # Filter to code-only lines (exclude comments and strings)
+            from ..line_filter import strip_comments_and_strings
+            code_lines = []
+            for line in added_lines.get(filepath, []):
+                code = strip_comments_and_strings(line)
+                if code.strip():
+                    code_lines.append(code)
+
+            for node in ast.walk(tree):
+                if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    continue
+
+                # Check if this function definition appears in code-only added lines
+                func_line = f"def {node.name}("
+                async_line = f"async def {node.name}("
+                is_new = any(
+                    func_line in line or async_line in line
+                    for line in code_lines
+                )
+                if not is_new:
+                    continue
+
+                # Skip dunder methods and test functions
+                if node.name.startswith("__") or node.name.startswith("test_"):
+                    continue
+
+                has_hints = bool(node.returns)
+                if not has_hints:
+                    # Check if any param has annotation (skip self/cls)
+                    params = [
+                        a for a in node.args.args
+                        if a.arg not in ("self", "cls")
+                    ]
+                    has_hints = any(a.annotation for a in params)
+
+                if not has_hints:
+                    results.append(CheckResult(
+                        passed=False,
+                        category=CheckCategory.VOICE,
+                        severity=severity,
+                        message=f"Missing type hints: {filepath}:{node.name}()",
+                        detail="Add type hints to function signature.",
+                        file=filepath,
+                        suggestion=f"Add type hints to {node.name}()",
+                    ))
+
+    return results