codeupipe 0.1.0__py3-none-any.whl

codeupipe/linter/assemble_report.py

@@ -0,0 +1,140 @@
+"""
+AssembleReport: Merge all analysis data into a unified health report.
+"""
+
+from datetime import datetime, timezone
+
+from codeupipe import Payload
+
+
+STALE_THRESHOLD_DAYS = 90
+
+
+def _compute_health_score(coverage_pct: float, orphan_count: int,
+                          stale_count: int, total_components: int) -> str:
+    """Compute a letter grade health score.
+
+    Scoring:
+        Start at 100 points.
+        - Deduct (100 - coverage_pct) * 0.6   (coverage is 60% of score)
+        - Deduct orphan_ratio * 20              (orphans are 20% of score)
+        - Deduct stale_ratio * 20               (staleness is 20% of score)
+
+    Grades: A >= 90, B >= 80, C >= 70, D >= 60, F < 60
+    """
+    if total_components == 0:
+        return "A"
+
+    score = 100.0
+    score -= (100.0 - coverage_pct) * 0.6
+    orphan_ratio = orphan_count / total_components if total_components else 0
+    score -= orphan_ratio * 20
+    stale_ratio = stale_count / total_components if total_components else 0
+    score -= stale_ratio * 20
+
+    score = max(0.0, min(100.0, score))
+
+    if score >= 90:
+        return "A"
+    elif score >= 80:
+        return "B"
+    elif score >= 70:
+        return "C"
+    elif score >= 60:
+        return "D"
+    else:
+        return "F"
+
+
+class AssembleReport:
+    """
+    Filter (sync): Merge coverage, orphan, and git data into a unified report.
+
+    Input keys:
+        - coverage (list[dict]): from MapCoverage
+        - summary (dict): from ReportGaps
+        - gaps (list[dict]): from ReportGaps
+        - orphaned_components (list[dict]): from DetectOrphans
+        - orphaned_tests (list[dict]): from DetectOrphans
+        - import_map (dict): from DetectOrphans
+        - git_info (dict): from GitHistory
+        - directory (str): component directory
+
+    Output keys (added):
+        - report (dict): unified report structure
+    """
+
+    def call(self, payload: Payload) -> Payload:
+        coverage = payload.get("coverage", [])
+        summary = payload.get("summary", {})
+        gaps = payload.get("gaps", [])
+        orphaned_components = payload.get("orphaned_components", [])
+        orphaned_tests = payload.get("orphaned_tests", [])
+        import_map = payload.get("import_map", {})
+        git_info = payload.get("git_info", {})
+        directory = payload.get("directory", "")
+
+        orphaned_names = {o["name"] for o in orphaned_components}
+
+        # Build enriched component list
+        components = []
+        for cov in coverage:
+            file_path = cov["file"]
+            git = git_info.get(file_path, {
+                "last_modified": None,
+                "last_author": None,
+                "commit_count": 0,
+                "days_since_change": None,
+            })
+
+            components.append({
+                "name": cov["name"],
+                "kind": cov["kind"],
+                "file": file_path,
+                "methods": cov["methods"],
+                "coverage_pct": cov["coverage_pct"],
+                "test_count": cov["test_count"],
+                "untested_methods": cov["untested_methods"],
+                "orphaned": cov["name"] in orphaned_names,
+                "imported_by": import_map.get(cov["name"], []),
+                "git": git,
+            })
+
+        # Detect stale files
+        stale_files = []
+        for file_path, info in git_info.items():
+            days = info.get("days_since_change")
+            if days is not None and days > STALE_THRESHOLD_DAYS:
+                stale_files.append({
+                    "file": file_path,
+                    "days_since_change": days,
+                    "last_modified": info.get("last_modified"),
+                    "last_author": info.get("last_author"),
+                })
+
+        # Compute health score
+        total = summary.get("total_components", 0)
+        health_score = _compute_health_score(
+            coverage_pct=summary.get("overall_pct", 100.0),
+            orphan_count=len(orphaned_components),
+            stale_count=len(stale_files),
+            total_components=total,
+        )
+
+        report = {
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+            "directory": directory,
+            "components": components,
+            "orphaned_components": orphaned_components,
+            "orphaned_tests": orphaned_tests,
+            "stale_files": stale_files,
+            "summary": {
+                **summary,
+                "orphaned_count": len(orphaned_components),
+                "orphaned_test_count": len(orphaned_tests),
+                "stale_count": len(stale_files),
+                "health_score": health_score,
+            },
+        }
+
+        return payload.insert("report", report)

codeupipe/linter/check_bundle.py

@@ -0,0 +1,47 @@
+"""
+CheckBundle: CUP008 — stale __init__.py bundle detection.
+"""
+
+from pathlib import Path
+
+from codeupipe import Payload
+
+
+class CheckBundle:
+    """
+    Filter (sync): Detect modules missing from a cup-bundle generated __init__.py.
+
+    Input keys:
+        - directory (str): path to the scanned directory
+        - files (list[dict]): file analyses from ScanDirectory
+        - issues (list): accumulated lint issues
+
+    Output keys (modified):
+        - issues (list): with CUP008 violations appended
+    """
+
+    def call(self, payload: Payload) -> Payload:
+        directory = payload.get("directory")
+        files = payload.get("files", [])
+        issues = list(payload.get("issues", []))
+
+        dir_path = Path(directory)
+        init_file = dir_path / "__init__.py"
+
+        if not init_file.exists():
+            return payload.insert("issues", issues)
+
+        init_content = init_file.read_text()
+        if "Auto-generated by: cup bundle" not in init_content:
+            return payload.insert("issues", issues)
+
+        for info in files:
+            module = info["stem"]
+            if f"from .{module} import" not in init_content:
+                issues.append((
+                    "CUP008", "warning", str(init_file),
+                    f"Bundle is stale: module '{module}' not exported. "
+                    f"Run: cup bundle {directory}"
+                ))
+
+        return payload.insert("issues", issues)

codeupipe/linter/check_index.py

@@ -0,0 +1,88 @@
+"""
+CheckIndex: Verify INDEX.md covers the project's key source files.
+
+Scans the project for Python source files under the package directory
+and checks that each is referenced (directly or via its parent __init__)
+in cup:ref markers within INDEX.md. Reports unmapped files as issues.
+"""
+
+from pathlib import Path
+
+from codeupipe import Payload
+
+
+# Files/patterns that don't need explicit index coverage
+_IGNORE_PATTERNS = {
+    "__pycache__",
+    ".pyc",
+    "py.typed",
+}
+
+
+class CheckIndex:
+    """
+    Filter (sync): Verify INDEX.md maps the project structure.
+
+    Input keys:
+        - directory (str): root directory to scan
+        - doc_refs (list[dict]): from ScanDocs (all cup:ref markers)
+
+    Output keys (added):
+        - index_issues (list[dict]): unmapped files, each with:
+            file (str), message (str)
+    """
+
+    def call(self, payload: Payload) -> Payload:
+        directory = Path(payload.get("directory", "."))
+        doc_refs = payload.get("doc_refs", [])
+
+        # Collect all file paths referenced in cup:ref markers across all docs
+        referenced = set()
+        for ref in doc_refs:
+            referenced.add(ref["file"])
+
+        # Discover key source files: __init__.py is the structural anchor,
+        # plus any .py files that define public exports (non-__init__)
+        package_dir = directory / "codeupipe"
+        if not package_dir.is_dir():
+            return payload.insert("index_issues", [])
+
+        source_files = set()
+        for py_file in sorted(package_dir.rglob("*.py")):
+            rel = str(py_file.relative_to(directory))
+
+            # Skip __pycache__ and other noise
+            if any(p in rel for p in _IGNORE_PATTERNS):
+                continue
+
+            # Skip individual filter files inside linter/ and converter/
+            # (the __init__.py for those packages is sufficient coverage)
+            parts = py_file.parts
+            in_subpackage = False
+            for sub in ("linter", "converter"):
+                if sub in parts:
+                    sub_idx = parts.index(sub)
+                    # If it's deeper than the direct children, always skip
+                    if len(parts) > sub_idx + 2:
+                        in_subpackage = True
+                    # Direct children that aren't __init__.py or *_pipeline.py
+                    elif (len(parts) == sub_idx + 2
+                          and py_file.name != "__init__.py"
+                          and not py_file.name.endswith("_pipeline.py")):
+                        in_subpackage = True
+
+            if in_subpackage:
+                continue
+
+            source_files.add(rel)
+
+        # Check which source files are not referenced
+        issues = []
+        for src in sorted(source_files):
+            if src not in referenced:
+                issues.append({
+                    "file": src,
+                    "message": f"Source file '{src}' not referenced in any cup:ref marker",
+                })
+
+        return payload.insert("index_issues", issues)

codeupipe/linter/check_naming.py

@@ -0,0 +1,47 @@
+"""
+CheckNaming: CUP007 — snake_case file name enforcement.
+"""
+
+import re
+
+from codeupipe import Payload
+
+
+_SNAKE_RE = re.compile(r"^[a-z][a-z0-9]*(_[a-z0-9]+)*$")
+
+
+def _to_snake(name: str) -> str:
+    """Convert PascalCase or mixed to snake_case."""
+    s = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)
+    s = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s)
+    return re.sub(r"[\s\-]+", "_", s).lower()
+
+
+class CheckNaming:
+    """
+    Filter (sync): Check that file names follow snake_case convention.
+
+    Input keys:
+        - files (list[dict]): file analyses from ScanDirectory
+        - issues (list): accumulated lint issues
+
+    Output keys (modified):
+        - issues (list): with CUP007 violations appended
+    """
+
+    def call(self, payload: Payload) -> Payload:
+        files = payload.get("files", [])
+        issues = list(payload.get("issues", []))
+
+        for info in files:
+            stem = info["stem"]
+            rel = info["path"]
+            if not _SNAKE_RE.match(stem):
+                expected = _to_snake(stem)
+                issues.append((
+                    "CUP007", "warning", rel,
+                    f"File name '{stem}.py' is not snake_case. "
+                    f"Expected: '{expected}.py'"
+                ))
+
+        return payload.insert("issues", issues)

codeupipe/linter/check_protocols.py

@@ -0,0 +1,73 @@
+"""
+CheckProtocols: CUP003–CUP006 — protocol compliance enforcement.
+"""
+
+from codeupipe import Payload
+
+
+_HOOK_METHODS = {"before", "after", "on_error"}
+
+
+class CheckProtocols:
+    """
+    Filter (sync): Verify each component has its required protocol methods.
+
+    Rules:
+        CUP003: Filter missing call()
+        CUP004: Tap missing observe()
+        CUP005: StreamFilter missing stream()
+        CUP006: Hook missing lifecycle methods (before, after, on_error)
+
+    Input keys:
+        - files (list[dict]): file analyses from ScanDirectory
+        - issues (list): accumulated lint issues
+
+    Output keys (modified):
+        - issues (list): with CUP003–CUP006 violations appended
+    """
+
+    def call(self, payload: Payload) -> Payload:
+        files = payload.get("files", [])
+        issues = list(payload.get("issues", []))
+
+        for info in files:
+            if info["error"]:
+                issues.append((
+                    "CUP000", "error", info["path"],
+                    f"Syntax error: {info['error']}"
+                ))
+                continue
+
+            for class_name, ctype, methods in info["classes"]:
+                if ctype is None:
+                    continue
+
+                if ctype == "filter" and "call" not in methods:
+                    issues.append((
+                        "CUP003", "error", info["path"],
+                        f"Filter '{class_name}' is missing call() method."
+                    ))
+
+                if ctype == "tap" and "observe" not in methods:
+                    issues.append((
+                        "CUP004", "error", info["path"],
+                        f"Tap '{class_name}' is missing observe() method."
+                    ))
+
+                if ctype == "stream-filter" and "stream" not in methods:
+                    issues.append((
+                        "CUP005", "error", info["path"],
+                        f"StreamFilter '{class_name}' is missing stream() method."
+                    ))
+
+                if ctype == "hook":
+                    missing = _HOOK_METHODS - methods
+                    if missing:
+                        issues.append((
+                            "CUP006", "error", info["path"],
+                            f"Hook '{class_name}' is missing: "
+                            f"{', '.join(sorted(missing))}. "
+                            f"Hooks need before(), after(), and on_error()."
+                        ))
+
+        return payload.insert("issues", issues)

codeupipe/linter/check_structure.py

@@ -0,0 +1,41 @@
+"""
+CheckStructure: CUP001 — one component per file enforcement.
+"""
+
+from codeupipe import Payload
+
+
+class CheckStructure:
+    """
+    Filter (sync): Flag files containing multiple CUP components.
+
+    Input keys:
+        - files (list[dict]): file analyses from ScanDirectory
+        - issues (list): accumulated lint issues
+
+    Output keys (modified):
+        - issues (list): with CUP001 violations appended
+    """
+
+    def call(self, payload: Payload) -> Payload:
+        files = payload.get("files", [])
+        issues = list(payload.get("issues", []))
+
+        for info in files:
+            if info["error"]:
+                continue
+
+            component_classes = [
+                (name, ctype)
+                for name, ctype, _ in info["classes"]
+                if ctype is not None
+            ]
+            if len(component_classes) > 1:
+                names = [f"{n} ({t})" for n, t in component_classes]
+                issues.append((
+                    "CUP001", "error", info["path"],
+                    f"Multiple components in one file: {', '.join(names)}. "
+                    f"Use one component per file."
+                ))
+
+        return payload.insert("issues", issues)

codeupipe/linter/check_symbols.py

@@ -0,0 +1,116 @@
+"""
+CheckSymbols: AST-verify that referenced symbols exist in source files.
+
+Parses each referenced source file and checks that the symbols mentioned
+in cup:ref markers actually exist as top-level classes, functions, or
+class attributes/methods.
+"""
+
+import ast
+from pathlib import Path
+from typing import List, Optional, Set
+
+from codeupipe import Payload
+
+
+def _collect_top_level_names(tree: ast.Module) -> Set[str]:
+    """Collect top-level class and function names from an AST."""
+    names = set()
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+            names.add(node.name)
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    names.add(target.id)
+    return names
+
+
+def _collect_class_members(tree: ast.Module, class_name: str) -> Set[str]:
+    """Collect method and assignment attribute names within a class."""
+    members = set()
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.ClassDef) and node.name == class_name:
+            for child in ast.iter_child_nodes(node):
+                if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    members.add(child.name)
+                elif isinstance(child, ast.Assign):
+                    for target in child.targets:
+                        if isinstance(target, ast.Name):
+                            members.add(target.id)
+            # Also check __init__ for self.attr assignments
+            for child in ast.walk(node):
+                if isinstance(child, ast.Assign):
+                    for target in child.targets:
+                        if (isinstance(target, ast.Attribute)
+                                and isinstance(target.value, ast.Name)
+                                and target.value.id == "self"):
+                            members.add(target.attr)
+    return members
+
+
+class CheckSymbols:
+    """
+    Filter (sync): Verify referenced symbols exist in source files.
+
+    Input keys:
+        - directory (str): root directory
+        - resolved_refs (list[dict]): from ResolveRefs
+
+    Output keys (added):
+        - symbol_issues (list[dict]): symbols not found, each with:
+            symbol, file, doc_path, line
+    """
+
+    def call(self, payload: Payload) -> Payload:
+        resolved = payload.get("resolved_refs", [])
+        issues: List[dict] = []
+
+        for ref in resolved:
+            if not ref.get("exists", False):
+                continue
+
+            symbols = ref.get("symbols", [])
+            if not symbols:
+                continue
+
+            abs_path = ref["abs_path"]
+            try:
+                source = Path(abs_path).read_text(encoding="utf-8", errors="replace")
+                tree = ast.parse(source)
+            except (SyntaxError, OSError):
+                continue
+
+            top_names = _collect_top_level_names(tree)
+
+            for symbol in symbols:
+                if "." in symbol:
+                    # Dotted: Class.member
+                    parts = symbol.split(".", 1)
+                    class_name, member_name = parts[0], parts[1]
+                    if class_name not in top_names:
+                        issues.append({
+                            "symbol": symbol,
+                            "file": ref["file"],
+                            "doc_path": ref["doc_path"],
+                            "line": ref["line"],
+                        })
+                    else:
+                        members = _collect_class_members(tree, class_name)
+                        if member_name not in members:
+                            issues.append({
+                                "symbol": symbol,
+                                "file": ref["file"],
+                                "doc_path": ref["doc_path"],
+                                "line": ref["line"],
+                            })
+                else:
+                    if symbol not in top_names:
+                        issues.append({
+                            "symbol": symbol,
+                            "file": ref["file"],
+                            "doc_path": ref["doc_path"],
+                            "line": ref["line"],
+                        })
+
+        return payload.insert("symbol_issues", issues)

codeupipe/linter/check_tests.py

@@ -0,0 +1,48 @@
+"""
+CheckTests: CUP002 — missing test file detection.
+"""
+
+from pathlib import Path
+
+from codeupipe import Payload
+
+
+class CheckTests:
+    """
+    Filter (sync): Flag components that have no corresponding test file.
+
+    Input keys:
+        - files (list[dict]): file analyses from ScanDirectory
+        - issues (list): accumulated lint issues
+        - tests_dir (str, optional): path to tests directory (default: "tests")
+
+    Output keys (modified):
+        - issues (list): with CUP002 violations appended
+    """
+
+    def call(self, payload: Payload) -> Payload:
+        files = payload.get("files", [])
+        issues = list(payload.get("issues", []))
+        tests_dir = payload.get("tests_dir", "tests")
+
+        for info in files:
+            if info["error"]:
+                continue
+
+            stem = info["stem"]
+            test_file = Path(tests_dir) / f"test_{stem}.py"
+
+            has_components = any(
+                ctype is not None for _, ctype, _ in info["classes"]
+            )
+            has_builders = any(
+                f.startswith("build_") for f in info["functions"]
+            )
+
+            if (has_components or has_builders) and not test_file.exists():
+                issues.append((
+                    "CUP002", "warning", info["path"],
+                    f"No test file found. Expected: {test_file}"
+                ))
+
+        return payload.insert("issues", issues)

codeupipe/linter/coverage_pipeline.py

@@ -0,0 +1,39 @@
+"""
+CoveragePipeline: AST-based component coverage mapping — built with CUP.
+
+Scans a component directory and its tests to produce:
+  - Per-component method coverage map
+  - Untested method gaps
+  - Aggregate coverage summary
+"""
+
+from codeupipe import Pipeline, Payload
+
+# TODO: update import paths to match your project layout
+from .scan_components import ScanComponents
+from .scan_tests import ScanTests
+from .map_coverage import MapCoverage
+from .report_gaps import ReportGaps
+
+
+def build_coverage_pipeline() -> Pipeline:
+    """
+    Construct the CoveragePipeline pipeline.
+
+    Steps:
+        1. ScanComponents (Filter)
+        2. ScanTests (Filter)
+        3. MapCoverage (Filter)
+        4. ReportGaps (Filter)
+
+    Use pipeline.run(payload) for single-payload execution.
+    Use pipeline.stream(source) for streaming execution.
+    """
+    pipeline = Pipeline()
+
+    pipeline.add_filter(ScanComponents(), "scan_components")
+    pipeline.add_filter(ScanTests(), "scan_tests")
+    pipeline.add_filter(MapCoverage(), "map_coverage")
+    pipeline.add_filter(ReportGaps(), "report_gaps")
+
+    return pipeline

codeupipe/linter/detect_drift.py

@@ -0,0 +1,44 @@
+"""
+DetectDrift: Compare stored hashes with current file content hashes.
+
+Flags doc references where the stored hash no longer matches the current
+file contents, indicating the source has changed since the doc was written.
+"""
+
+from codeupipe import Payload
+
+
+class DetectDrift:
+    """
+    Filter (sync): Detect hash drift between docs and source files.
+
+    Input keys:
+        - resolved_refs (list[dict]): from ResolveRefs
+
+    Output keys (added):
+        - drifted_refs (list[dict]): refs with hash mismatches, each with:
+            file, stored_hash, current_hash, doc_path, line
+    """
+
+    def call(self, payload: Payload) -> Payload:
+        resolved = payload.get("resolved_refs", [])
+        drifted = []
+
+        for ref in resolved:
+            stored_hash = ref.get("hash")
+            if stored_hash is None:
+                # No stored hash — symbol-only mode, skip drift check
+                continue
+
+            current_hash = ref.get("current_hash")
+
+            if current_hash != stored_hash:
+                drifted.append({
+                    "file": ref["file"],
+                    "stored_hash": stored_hash,
+                    "current_hash": current_hash,
+                    "doc_path": ref["doc_path"],
+                    "line": ref["line"],
+                })
+
+        return payload.insert("drifted_refs", drifted)