codeledger 0.1.0__py3-none-any.whl

codeledger/__init__.py

@@ -0,0 +1,4 @@
+"""CodeLedger — Auto-generated code comprehension for AI-assisted development."""
+
+__version__ = "0.1.0"
+__app_name__ = "codeledger"

codeledger/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running codeledger as `python -m codeledger`."""
+
+from codeledger.cli import app
+
+if __name__ == "__main__":
+    app()

codeledger/classifier/__init__.py

@@ -0,0 +1,21 @@
+"""Classifier package — session classification and change deferral."""
+
+from codeledger.classifier.session import (
+    SessionClassification,
+    SessionType,
+    classify_session,
+)
+from codeledger.classifier.deferred import (
+    PendingChanges,
+    load_pending,
+    save_pending,
+)
+
+__all__ = [
+    "PendingChanges",
+    "SessionClassification",
+    "SessionType",
+    "classify_session",
+    "load_pending",
+    "save_pending",
+]

codeledger/classifier/deferred.py

@@ -0,0 +1,143 @@
+"""Deferred change accumulator — buffers trivial sessions until flush threshold."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from ruamel.yaml import YAML
+
+from codeledger.scanner.change_dag import ChangeMetrics
+
+yaml = YAML()
+yaml.default_flow_style = False
+
+PENDING_FILE = ".codeledger/.pending_changes.yaml"
+
+
+@dataclass
+class DeferredSession:
+    """Record of a deferred trivial session."""
+
+    session_id: str
+    timestamp: str
+    files_changed: list[str]
+    summary: str
+    magnitude: float
+
+
+@dataclass
+class PendingChanges:
+    """Accumulated deferred changes waiting to be flushed."""
+
+    pending_sessions: list[DeferredSession] = field(default_factory=list)
+    accumulated_magnitude: float = 0.0
+    sessions_deferred: int = 0
+
+    def should_flush(
+        self,
+        flush_threshold: float = 0.40,
+        max_deferred: int = 5,
+    ) -> bool:
+        """Check if accumulated changes should trigger a documentation flush."""
+        if self.sessions_deferred >= max_deferred:
+            return True
+        if self.accumulated_magnitude >= flush_threshold:
+            return True
+        return False
+
+    def add_session(
+        self,
+        changed_paths: list[str],
+        metrics: ChangeMetrics,
+        summary: str = "",
+    ) -> None:
+        """Add a deferred session to the pending buffer."""
+        now = datetime.now(timezone.utc)
+        session_id = f"deferred_{now.strftime('%Y%m%d_%H%M%S')}"
+
+        if not summary:
+            summary = (
+                f"{metrics.files_changed} files, "
+                f"{metrics.lines_added}+ / {metrics.lines_removed}- lines"
+            )
+
+        session = DeferredSession(
+            session_id=session_id,
+            timestamp=now.isoformat(),
+            files_changed=changed_paths,
+            summary=summary,
+            magnitude=metrics.total_magnitude,
+        )
+
+        self.pending_sessions.append(session)
+        self.accumulated_magnitude += metrics.total_magnitude
+        self.sessions_deferred += 1
+
+    def flush(self) -> list[DeferredSession]:
+        """Flush all pending sessions and return them. Resets the buffer."""
+        flushed = list(self.pending_sessions)
+        self.pending_sessions = []
+        self.accumulated_magnitude = 0.0
+        self.sessions_deferred = 0
+        return flushed
+
+    def to_dict(self) -> dict:
+        return {
+            "pending_sessions": [
+                {
+                    "session_id": s.session_id,
+                    "timestamp": s.timestamp,
+                    "files_changed": s.files_changed,
+                    "summary": s.summary,
+                    "magnitude": s.magnitude,
+                }
+                for s in self.pending_sessions
+            ],
+            "accumulated_magnitude": round(self.accumulated_magnitude, 4),
+            "sessions_deferred": self.sessions_deferred,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "PendingChanges":
+        sessions = [
+            DeferredSession(
+                session_id=s["session_id"],
+                timestamp=s["timestamp"],
+                files_changed=s.get("files_changed", []),
+                summary=s.get("summary", ""),
+                magnitude=s.get("magnitude", 0.0),
+            )
+            for s in data.get("pending_sessions", [])
+        ]
+        return cls(
+            pending_sessions=sessions,
+            accumulated_magnitude=data.get("accumulated_magnitude", 0.0),
+            sessions_deferred=data.get("sessions_deferred", 0),
+        )
+
+
+def load_pending(project_root: Path) -> PendingChanges:
+    """Load pending changes from disk."""
+    filepath = project_root / PENDING_FILE
+    if not filepath.exists():
+        return PendingChanges()
+
+    with open(filepath, "r", encoding="utf-8") as f:
+        data = yaml.load(f)
+
+    if not data:
+        return PendingChanges()
+
+    return PendingChanges.from_dict(data)
+
+
+def save_pending(project_root: Path, pending: PendingChanges) -> None:
+    """Save pending changes to disk."""
+    filepath = project_root / PENDING_FILE
+    filepath.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(filepath, "w", encoding="utf-8") as f:
+        yaml.dump(pending.to_dict(), f)

codeledger/classifier/rules.py

@@ -0,0 +1,116 @@
+"""Rule-based session classifier — MVP classifier using configurable thresholds."""
+
+from __future__ import annotations
+
+from codeledger.classifier.session import (
+    SESSION_BUDGETS,
+    SessionClassification,
+    SessionType,
+)
+from codeledger.scanner.change_dag import ChangeMetrics
+
+
+def classify_with_rules(
+    metrics: ChangeMetrics,
+    trivial_max_files: int = 2,
+    trivial_max_lines: int = 30,
+    minor_max_files: int = 5,
+    minor_max_lines: int = 150,
+    standard_max_files: int = 15,
+    standard_max_lines: int = 500,
+) -> SessionClassification:
+    """Classify a session using rule-based thresholds.
+
+    Decision order:
+    1. Refactor detection (deletes + creates with low net change)
+    2. Trivial (very small changes)
+    3. Minor / Standard / Major (by size)
+    """
+    net_lines = metrics.lines_added + metrics.lines_removed
+
+    # --- Refactor detection ---
+    if (
+        metrics.files_deleted > 0
+        and metrics.new_files_created > 0
+        and abs(metrics.net_lines) < 50
+        and metrics.files_changed >= 3
+    ):
+        budgets = SESSION_BUDGETS[SessionType.REFACTOR]
+        return SessionClassification(
+            session_type=SessionType.REFACTOR,
+            confidence=0.85,
+            input_token_budget=budgets[0],
+            output_token_budget=budgets[1],
+            reason=(
+                f"Refactor detected: {metrics.files_deleted} deleted, "
+                f"{metrics.new_files_created} created, "
+                f"low net line change ({metrics.net_lines})"
+            ),
+        )
+
+    # --- Trivial ---
+    if (
+        metrics.files_changed <= trivial_max_files
+        and net_lines <= trivial_max_lines
+        and metrics.new_files_created == 0
+        and not metrics.has_structural_changes
+    ):
+        budgets = SESSION_BUDGETS[SessionType.TRIVIAL]
+        return SessionClassification(
+            session_type=SessionType.TRIVIAL,
+            confidence=0.90,
+            input_token_budget=budgets[0],
+            output_token_budget=budgets[1],
+            reason=(
+                f"Trivial: {metrics.files_changed} files, "
+                f"{net_lines} lines changed"
+            ),
+        )
+
+    # --- Minor ---
+    if (
+        metrics.files_changed <= minor_max_files
+        and net_lines <= minor_max_lines
+    ):
+        budgets = SESSION_BUDGETS[SessionType.MINOR]
+        return SessionClassification(
+            session_type=SessionType.MINOR,
+            confidence=0.85,
+            input_token_budget=budgets[0],
+            output_token_budget=budgets[1],
+            reason=(
+                f"Minor: {metrics.files_changed} files, "
+                f"{net_lines} lines changed"
+            ),
+        )
+
+    # --- Standard ---
+    if (
+        metrics.files_changed <= standard_max_files
+        and net_lines <= standard_max_lines
+    ):
+        budgets = SESSION_BUDGETS[SessionType.STANDARD]
+        return SessionClassification(
+            session_type=SessionType.STANDARD,
+            confidence=0.85,
+            input_token_budget=budgets[0],
+            output_token_budget=budgets[1],
+            reason=(
+                f"Standard: {metrics.files_changed} files, "
+                f"{net_lines} lines changed"
+            ),
+        )
+
+    # --- Major ---
+    budgets = SESSION_BUDGETS[SessionType.MAJOR]
+    return SessionClassification(
+        session_type=SessionType.MAJOR,
+        confidence=0.80,
+        input_token_budget=budgets[0],
+        output_token_budget=budgets[1],
+        reason=(
+            f"Major: {metrics.files_changed} files, "
+            f"{net_lines} lines changed, "
+            f"{metrics.new_files_created} new files"
+        ),
+    )

codeledger/classifier/session.py

@@ -0,0 +1,60 @@
+"""Session types and classification interface."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from codeledger.scanner.change_dag import ChangeMetrics
+
+
+class SessionType(str, Enum):
+    TRIVIAL = "trivial"
+    MINOR = "minor"
+    STANDARD = "standard"
+    MAJOR = "major"
+    REFACTOR = "refactor"
+
+
+@dataclass
+class SessionClassification:
+    """Result of classifying a development session."""
+
+    session_type: SessionType
+    confidence: float  # 0.0 - 1.0
+    input_token_budget: int
+    output_token_budget: int
+    reason: str
+
+    @property
+    def should_defer(self) -> bool:
+        return self.session_type == SessionType.TRIVIAL
+
+
+# Token budgets per session type
+SESSION_BUDGETS: dict[SessionType, tuple[int, int]] = {
+    SessionType.TRIVIAL: (0, 0),        # deferred, no generation
+    SessionType.MINOR: (500, 1500),      # micro-doc
+    SessionType.STANDARD: (2000, 5000),  # normal doc
+    SessionType.MAJOR: (4000, 8000),     # comprehensive doc
+    SessionType.REFACTOR: (1500, 3000),  # refactor-focused doc
+}
+
+
+def classify_session(
+    metrics: ChangeMetrics,
+    use_slm: bool = False,
+) -> SessionClassification:
+    """Classify a development session based on change metrics.
+
+    Routes to SLM or rule-based classifier.
+    """
+    if use_slm:
+        try:
+            from codeledger.classifier.slm import classify_with_slm
+            return classify_with_slm(metrics)
+        except ImportError:
+            pass  # Fall through to rules
+
+    from codeledger.classifier.rules import classify_with_rules
+    return classify_with_rules(metrics)

codeledger/classifier/slm.py

@@ -0,0 +1,19 @@
+"""SLM-based classifier — optional enhanced classification using a local model."""
+
+from __future__ import annotations
+
+from codeledger.classifier.session import (
+    SessionClassification,
+)
+from codeledger.scanner.change_dag import ChangeMetrics
+
+
+def classify_with_slm(metrics: ChangeMetrics) -> SessionClassification:
+    """Classify a session using a local SLM.
+
+    Requires the `codeledger[slm]` extra. Falls back to rule-based
+    classification when the SLM dependencies are not installed.
+    """
+    from codeledger.classifier.rules import classify_with_rules
+
+    return classify_with_rules(metrics)