ctrlcode 0.1.0__py3-none-any.whl

ctrlcode/fuzzing/oracle_adapter.py

@@ -0,0 +1,135 @@
+"""Oracle adaptation engine - adapts historical oracles to new code."""
+
+import logging
+from typing import Optional
+
+from ..providers.base import Provider
+from .context import ContextDerivation
+
+logger = logging.getLogger(__name__)
+
+
+class OracleAdapter:
+    """Adapts historical oracles to new code using LLM reasoning.
+
+    When similar code is found in history, instead of deriving a fresh oracle
+    from scratch, we adapt the existing oracle to the new code. This saves
+    LLM calls and maintains consistency across similar implementations.
+    """
+
+    def __init__(self, provider: Provider):
+        """Initialize oracle adapter.
+
+        Args:
+            provider: LLM provider for adaptation
+        """
+        self.provider = provider
+
+    async def adapt_oracle(
+        self,
+        old_oracle: ContextDerivation,
+        old_code: str,
+        new_code: str,
+        user_request: str,
+        similarity_score: float,
+    ) -> Optional[ContextDerivation]:
+        """Adapt historical oracle to new code.
+
+        Args:
+            old_oracle: Historical context derivation to adapt
+            old_code: Historical code the oracle was derived from
+            new_code: New code to adapt oracle for
+            user_request: User specification for new code
+            similarity_score: Cosine similarity between old and new code
+
+        Returns:
+            Adapted ContextDerivation or None if adaptation fails
+        """
+        system_prompt = """You are a senior systems analyst specializing in adapting behavioral
+contracts to similar code implementations.
+
+You will be given:
+1. An EXISTING behavioral oracle derived from similar code
+2. The ORIGINAL code that oracle was derived from
+3. The NEW code that needs an oracle
+4. The user's specification for the new code
+5. The similarity score between old and new code
+
+Your job is to ADAPT the existing oracle to the new code, rather than deriving
+from scratch. Focus on:
+- What changed between old and new code?
+- Which behavioral invariants remain the same?
+- Which invariants need updating?
+- Any new integration contracts or edge cases?
+
+Output the ADAPTED oracle as structured JSON matching the original format with
+all 6 sections + function_invariants:
+
+1. system_placement
+2. environmental_constraints
+3. integration_contracts
+4. behavioral_invariants
+5. edge_case_surface
+6. implicit_assumptions
+7. function_invariants (dict mapping function names to their specific invariants)
+
+Be conservative: if you're unsure whether an invariant still applies, include it
+with a note. Better to over-specify than under-specify."""
+
+        user_message = f"""## Similarity Score
+{similarity_score:.2%} match with historical code
+
+## Historical Code
+```python
+{old_code}
+```
+
+## Historical Oracle
+```json
+{old_oracle.to_json()}
+```
+
+## New Code
+```python
+{new_code}
+```
+
+## User Specification for New Code
+{user_request}
+
+## Task
+Adapt the historical oracle to the new code. Identify what changed and update
+the oracle accordingly. Output as structured JSON."""
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_message},
+        ]
+
+        try:
+            response = await self.provider.generate(messages)
+            response_text = response.get("text", "").strip()
+
+            # Parse JSON response
+            if "```json" in response_text:
+                start = response_text.find("```json") + 7
+                end = response_text.find("```", start)
+                response_text = response_text[start:end].strip()
+            elif "```" in response_text:
+                start = response_text.find("```") + 3
+                end = response_text.find("```", start)
+                response_text = response_text[start:end].strip()
+
+            import json
+
+            data = json.loads(response_text)
+            adapted = ContextDerivation.from_dict(data)
+
+            logger.info(
+                f"Successfully adapted oracle from historical code (similarity: {similarity_score:.2%})"
+            )
+            return adapted
+
+        except Exception as e:
+            logger.warning(f"Failed to adapt historical oracle: {e}")
+            return None

ctrlcode/linters/__init__.py

@@ -0,0 +1,11 @@
+"""Custom linters for golden principles enforcement."""
+
+from .yolo_parsing import lint_file as lint_yolo_parsing
+from .hand_rolled_utils import lint_file as lint_hand_rolled_utils
+from .yolo_parsing import Violation
+
+__all__ = [
+    "lint_yolo_parsing",
+    "lint_hand_rolled_utils",
+    "Violation",
+]

ctrlcode/linters/hand_rolled_utils.py

@@ -0,0 +1,221 @@
+"""Hand-rolled utilities linter - detects duplicate patterns."""
+
+import ast
+import re
+from pathlib import Path
+from typing import Iterator
+from dataclasses import dataclass
+
+
+@dataclass
+class Violation:
+    """A linting violation."""
+
+    file: str
+    line: int
+    column: int
+    message: str
+    severity: str
+    fix_suggestion: str
+    principle: str
+
+
+class HandRolledUtilsDetector(ast.NodeVisitor):
+    """AST visitor to detect hand-rolled utility patterns."""
+
+    def __init__(self, filepath: str, source: str):
+        """
+        Initialize detector.
+
+        Args:
+            filepath: Path to file being analyzed
+            source: Source code content
+        """
+        self.filepath = filepath
+        self.source = source
+        self.violations: list[Violation] = []
+
+    def visit_For(self, node: ast.For) -> None:
+        """Detect retry patterns in for loops."""
+        # Pattern: for i in range(N): try: ... except: ...
+        if isinstance(node.iter, ast.Call):
+            if isinstance(node.iter.func, ast.Name) and node.iter.func.id == "range":
+                # Check if body has try/except
+                has_try_except = any(isinstance(stmt, ast.Try) for stmt in node.body)
+
+                if has_try_except:
+                    # Get source snippet
+                    try:
+                        source_lines = self.source.split("\n")
+                        snippet = source_lines[node.lineno - 1][:50] + "..."
+                    except Exception:
+                        snippet = "retry loop"
+
+                    violation = Violation(
+                        file=self.filepath,
+                        line=node.lineno,
+                        column=node.col_offset,
+                        message=f"Hand-rolled retry logic detected: {snippet}",
+                        severity="info",
+                        fix_suggestion="""Use shared retry utility:
+
+from ctrlcode.utils import retry
+
+@retry(max_attempts=3, backoff_base=2.0)
+def your_function():
+    # Your code here
+    pass
+
+Why: Centralizes retry logic, ensures consistency across codebase.
+See: docs/golden-principles/prefer-shared-utils.md""",
+                        principle="prefer-shared-utils"
+                    )
+
+                    self.violations.append(violation)
+
+        self.generic_visit(node)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+        """Detect common utility function patterns."""
+        # Check for retry in function name
+        if "retry" in node.name.lower():
+            violation = Violation(
+                file=self.filepath,
+                line=node.lineno,
+                column=node.col_offset,
+                message=f"Custom retry function '{node.name}' - consider using shared utility",
+                severity="info",
+                fix_suggestion="""Use shared retry utility instead:
+
+from ctrlcode.utils import retry
+
+# Remove this function and use decorator:
+@retry(max_attempts=3)
+def your_function():
+    pass
+
+Why: Shared utilities are tested, maintained, and consistent.
+See: docs/golden-principles/prefer-shared-utils.md""",
+                principle="prefer-shared-utils"
+            )
+
+            self.violations.append(violation)
+
+        self.generic_visit(node)
+
+
+def detect_print_statements(filepath: Path, source: str) -> list[Violation]:
+    """
+    Detect print statements (should use logging).
+
+    Args:
+        filepath: Path to file
+        source: Source code
+
+    Returns:
+        List of violations
+    """
+    violations = []
+
+    for lineno, line in enumerate(source.split("\n"), start=1):
+        # Skip comments
+        if line.strip().startswith("#"):
+            continue
+
+        # Detect print() calls (not in strings)
+        if re.search(r'\bprint\s*\(', line):
+            violations.append(Violation(
+                file=str(filepath),
+                line=lineno,
+                column=line.find("print"),
+                message="Using print() instead of structured logging",
+                severity="warning",
+                fix_suggestion="""Use structured logging:
+
+import structlog
+logger = structlog.get_logger(__name__)
+
+# Instead of:
+# print(f"Processing {item}")
+
+# Use:
+logger.info("processing.started", item=item)
+
+Why: Enables log querying, filtering, and agent analysis.
+See: docs/golden-principles/structured-logging.md""",
+                principle="structured-logging"
+            ))
+
+    return violations
+
+
+def lint_file(filepath: Path) -> list[Violation]:
+    """
+    Lint a Python file for hand-rolled utilities.
+
+    Args:
+        filepath: Path to Python file
+
+    Returns:
+        List of violations found
+    """
+    try:
+        source = filepath.read_text()
+        tree = ast.parse(source, filename=str(filepath))
+
+        detector = HandRolledUtilsDetector(str(filepath), source)
+        detector.visit(tree)
+
+        # Add print statement detection
+        print_violations = detect_print_statements(filepath, source)
+        detector.violations.extend(print_violations)
+
+        return detector.violations
+
+    except SyntaxError:
+        return []
+    except Exception:
+        return []
+
+
+def lint_directory(directory: Path, pattern: str = "**/*.py") -> Iterator[Violation]:
+    """
+    Lint all Python files in directory.
+
+    Args:
+        directory: Root directory to search
+        pattern: Glob pattern for files to lint
+
+    Yields:
+        Violations found
+    """
+    for filepath in directory.glob(pattern):
+        if filepath.is_file():
+            # Skip test files and virtual environments
+            if "test" in str(filepath) or ".venv" in str(filepath):
+                continue
+
+            for violation in lint_file(filepath):
+                yield violation
+
+
+def format_violation(violation: Violation) -> str:
+    """
+    Format violation for output.
+
+    Args:
+        violation: Violation to format
+
+    Returns:
+        Formatted string
+    """
+    severity_symbol = "ℹ️" if violation.severity == "info" else "⚠️"
+
+    return f"""{severity_symbol} Hand-Rolled Utility Detected
+File: {violation.file}:{violation.line}:{violation.column}
+Rule: golden-principles/{violation.principle}.md
+
+{violation.message}
+
+FIX: {violation.fix_suggestion}
+"""

ctrlcode/linters/yolo_parsing.py

@@ -0,0 +1,217 @@
+"""YOLO parsing linter - detects dict access without validation."""
+
+import ast
+from pathlib import Path
+from typing import Iterator
+from dataclasses import dataclass
+
+
+@dataclass
+class Violation:
+    """A linting violation."""
+
+    file: str
+    line: int
+    column: int
+    message: str
+    severity: str
+    fix_suggestion: str
+    principle: str
+
+
+class YoloParsingDetector(ast.NodeVisitor):
+    """AST visitor to detect dictionary access without validation."""
+
+    def __init__(self, filepath: str):
+        """
+        Initialize detector.
+
+        Args:
+            filepath: Path to file being analyzed
+        """
+        self.filepath = filepath
+        self.violations: list[Violation] = []
+        self.in_validation_context = False
+        self.validated_names: set[str] = set()
+
+    def visit_Try(self, node: ast.Try) -> None:
+        """Track try blocks (might be validation)."""
+        # Check if this is validation pattern (try/except KeyError)
+        has_keyerror = any(
+            isinstance(handler.type, ast.Name) and handler.type.id == "KeyError"
+            for handler in node.handlers
+            if handler.type
+        )
+
+        if has_keyerror:
+            self.in_validation_context = True
+            self.generic_visit(node)
+            self.in_validation_context = False
+        else:
+            self.generic_visit(node)
+
+    def visit_Call(self, node: ast.Call) -> None:
+        """Track validation function calls."""
+        # Check for schema validation patterns
+        if isinstance(node.func, ast.Attribute):
+            # Pydantic: Model(**data), Model.parse(data)
+            if node.func.attr in ("parse", "parse_obj", "parse_raw"):
+                if node.args:
+                    arg = node.args[0]
+                    if isinstance(arg, ast.Name):
+                        self.validated_names.add(arg.id)
+
+        # Check for dataclass instantiation
+        if isinstance(node.func, ast.Name):
+            # Assuming uppercase names are classes/validators
+            if node.func.id and node.func.id[0].isupper():
+                for keyword in node.keywords:
+                    if isinstance(keyword.value, ast.Name):
+                        self.validated_names.add(keyword.value.id)
+
+        self.generic_visit(node)
+
+    def visit_Subscript(self, node: ast.Subscript) -> None:
+        """Detect dictionary subscript access."""
+        # Skip if in validation context
+        if self.in_validation_context:
+            self.generic_visit(node)
+            return
+
+        # Check if this is dict access on a variable
+        if isinstance(node.value, ast.Name):
+            var_name = node.value.id
+
+            # Skip if already validated
+            if var_name in self.validated_names:
+                self.generic_visit(node)
+                return
+
+            # Skip common safe patterns
+            if var_name in ("self", "cls", "os", "sys"):
+                self.generic_visit(node)
+                return
+
+            # Nested subscript (e.g., data["user"]["email"])
+            if isinstance(node.slice, ast.Constant) and isinstance(node.slice.value, str):
+                # This looks like YOLO dict access
+                key = node.slice.value
+
+                violation = Violation(
+                    file=self.filepath,
+                    line=node.lineno,
+                    column=node.col_offset,
+                    message=f'Accessing {var_name}["{key}"] without validation',
+                    severity="warning",
+                    fix_suggestion=f"""Use schema validation at boundary:
+
+from dataclasses import dataclass
+
+@dataclass
+class DataSchema:
+    {key}: str  # Define expected structure
+
+validated = DataSchema(**{var_name})
+value = validated.{key}
+
+Why: Prevents runtime crashes from unexpected data shapes.
+See: docs/golden-principles/no-yolo-parsing.md""",
+                    principle="no-yolo-parsing"
+                )
+
+                self.violations.append(violation)
+
+        # Check for chained subscripts (data["user"]["email"])
+        elif isinstance(node.value, ast.Subscript):
+            # This is nested dict access - likely YOLO
+            violation = Violation(
+                file=self.filepath,
+                line=node.lineno,
+                column=node.col_offset,
+                message="Nested dict access without validation",
+                severity="warning",
+                fix_suggestion="""Use schema validation to define structure:
+
+from dataclasses import dataclass
+
+@dataclass
+class UserData:
+    user: dict  # Or better: user: User (nested dataclass)
+
+validated = UserData(**data)
+value = validated.user["field"]
+
+Why: Makes data contract explicit and fails fast on malformed input.
+See: docs/golden-principles/no-yolo-parsing.md""",
+                principle="no-yolo-parsing"
+            )
+
+            self.violations.append(violation)
+
+        self.generic_visit(node)
+
+
+def lint_file(filepath: Path) -> list[Violation]:
+    """
+    Lint a Python file for YOLO parsing violations.
+
+    Args:
+        filepath: Path to Python file
+
+    Returns:
+        List of violations found
+    """
+    try:
+        source = filepath.read_text()
+        tree = ast.parse(source, filename=str(filepath))
+
+        detector = YoloParsingDetector(str(filepath))
+        detector.visit(tree)
+
+        return detector.violations
+
+    except SyntaxError:
+        # File has syntax errors, skip
+        return []
+    except Exception:
+        # Other errors, skip
+        return []
+
+
+def lint_directory(directory: Path, pattern: str = "**/*.py") -> Iterator[Violation]:
+    """
+    Lint all Python files in directory.
+
+    Args:
+        directory: Root directory to search
+        pattern: Glob pattern for files to lint
+
+    Yields:
+        Violations found
+    """
+    for filepath in directory.glob(pattern):
+        if filepath.is_file():
+            for violation in lint_file(filepath):
+                yield violation
+
+
+def format_violation(violation: Violation) -> str:
+    """
+    Format violation for output.
+
+    Args:
+        violation: Violation to format
+
+    Returns:
+        Formatted string
+    """
+    severity_symbol = "⚠️" if violation.severity == "warning" else "❌"
+
+    return f"""{severity_symbol} YOLO Parsing Detected
+File: {violation.file}:{violation.line}:{violation.column}
+Rule: golden-principles/{violation.principle}.md
+
+{violation.message}
+
+FIX: {violation.fix_suggestion}
+"""

ctrlcode/metrics/__init__.py

@@ -0,0 +1,6 @@
+"""Metrics tracking for ctrl+code."""
+
+from .dashboard import MetricsDashboard, MetricsSummary
+from .tech_debt import TechDebtMetrics, TechDebtSnapshot
+
+__all__ = ["MetricsDashboard", "MetricsSummary", "TechDebtMetrics", "TechDebtSnapshot"]