codeclone-cli 1.0.0__tar.gz

codeclone_cli-1.0.0/.gitignore

@@ -0,0 +1,57 @@
+# Node
+node_modules/
+out/
+*.vsix
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Build artifacts
+*.log
+*.tmp
+
+# OS
+.DS_Store
+Thumbs.db
+site/.astro/
+site/dist/
+site/node_modules/
+.polyglot-cache.json

codeclone_cli-1.0.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: codeclone-cli
+Version: 1.0.0
+Summary: CodeClone CLI - Deterministic code coverage analysis
+Project-URL: Homepage, https://github.com/mcp-tool-shop-org/codeclone-suite
+Project-URL: Repository, https://github.com/mcp-tool-shop-org/codeclone-suite
+Project-URL: Documentation, https://github.com/mcp-tool-shop-org/codeclone-suite/blob/main/docs/EDITOR_INTEGRATION.md
+Author-email: mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>
+License-Expression: MIT
+Keywords: analysis,cli,coverage,testing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CodeClone CLI
+
+The analysis engine for CodeClone Suite. This CLI provides the protocol boundary for editor extensions.
+
+## Installation
+
+```bash
+pip install codeclone-cli
+```
+
+Or install from source:
+
+```bash
+cd engines/codeclone-cli
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Show version
+codeclone version --json
+
+# Analyze a repository
+codeclone analyze /path/to/repo --json
+```
+
+## Output Contract
+
+This CLI follows the [Editor Integration Specification](../../docs/EDITOR_INTEGRATION.md).
+
+- stdout is JSON only in `--json` mode
+- stderr is for human diagnostics
+- Exit codes: 0 (OK), 1 (PARTIAL), 2 (FAIL)
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

codeclone_cli-1.0.0/README.md

@@ -0,0 +1,45 @@
+# CodeClone CLI
+
+The analysis engine for CodeClone Suite. This CLI provides the protocol boundary for editor extensions.
+
+## Installation
+
+```bash
+pip install codeclone-cli
+```
+
+Or install from source:
+
+```bash
+cd engines/codeclone-cli
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Show version
+codeclone version --json
+
+# Analyze a repository
+codeclone analyze /path/to/repo --json
+```
+
+## Output Contract
+
+This CLI follows the [Editor Integration Specification](../../docs/EDITOR_INTEGRATION.md).
+
+- stdout is JSON only in `--json` mode
+- stderr is for human diagnostics
+- Exit codes: 0 (OK), 1 (PARTIAL), 2 (FAIL)
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

codeclone_cli-1.0.0/codeclone_cli.py

@@ -0,0 +1,877 @@
+#!/usr/bin/env python3
+"""
+CodeClone CLI - Deterministic code coverage analysis.
+
+This CLI provides the protocol boundary for editor extensions.
+stdout is JSON only in --json mode. stderr is for human diagnostics.
+"""
+
+import argparse
+import json
+import platform
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+__version__ = "0.2.0"
+SCHEMA_VERSION = "0.1"
+
+
+# =============================================================================
+# Diagnostic Codes (frozen for v0.1)
+# =============================================================================
+
+
+class DiagnosticCode:
+    """Canonical diagnostic codes per EDITOR_INTEGRATION.md"""
+
+    # Evidence-only codes (Increment A)
+    UNTESTED_MODULE = "UNTESTED_MODULE"
+    LINE_UNCOVERED = "LINE_UNCOVERED"
+    COVERAGE_DATA_MISSING = "COVERAGE_DATA_MISSING"
+    COVERAGE_FILE_STALE = "COVERAGE_FILE_STALE"
+    COVERAGE_REPORT_PARSE_ERROR = "COVERAGE_REPORT_PARSE_ERROR"
+    DIAGNOSTICS_TRUNCATED = "DIAGNOSTICS_TRUNCATED"
+
+    # Reason codes (Increment B - future)
+    GUARD_BLOCKS_EXECUTION = "GUARD_BLOCKS_EXECUTION"
+    EXCEPTION_NEVER_TRIGGERED = "EXCEPTION_NEVER_TRIGGERED"
+    EARLY_RETURN_BLOCKS_CODE = "EARLY_RETURN_BLOCKS_CODE"
+    BRANCH_NEVER_TAKEN = "BRANCH_NEVER_TAKEN"
+
+    # Toolchain codes
+    TOOLCHAIN_ERROR = "TOOLCHAIN_ERROR"
+    REPO_ROOT_NOT_FOUND = "REPO_ROOT_NOT_FOUND"
+    CONFIG_INVALID = "CONFIG_INVALID"
+
+
+# Maximum diagnostics per file and total
+MAX_DIAGNOSTICS_PER_FILE = 10
+MAX_TOTAL_DIAGNOSTICS = 100
+STALENESS_THRESHOLD_SECONDS = 3600
+
+# Codes promoted to error under --strict-evidence
+STRICT_EVIDENCE_CODES = frozenset(
+    {
+        DiagnosticCode.COVERAGE_FILE_STALE,
+    }
+)
+
+
+class Severity:
+    """Diagnostic severity levels"""
+
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+# =============================================================================
+# Coverage Data Structures
+# =============================================================================
+
+
+@dataclass
+class FileCoverage:
+    """Coverage data for a single file."""
+
+    path: str
+    executed_lines: set[int] = field(default_factory=set)
+    missing_lines: set[int] = field(default_factory=set)
+    excluded_lines: set[int] = field(default_factory=set)
+    total_statements: int = 0
+    covered_statements: int = 0
+
+    @property
+    def coverage_percent(self) -> float:
+        if self.total_statements == 0:
+            return 0.0
+        return (self.covered_statements / self.total_statements) * 100
+
+
+@dataclass
+class CoverageReport:
+    """Parsed coverage report."""
+
+    files: dict[str, FileCoverage] = field(default_factory=dict)
+    total_statements: int = 0
+    covered_statements: int = 0
+    source_path: str | None = None
+    coverage_mtime: float | None = None  # mtime of coverage file for staleness check
+
+    @property
+    def coverage_percent(self) -> float:
+        if self.total_statements == 0:
+            return 0.0
+        return (self.covered_statements / self.total_statements) * 100
+
+
+@dataclass
+class AnalysisContext:
+    """Context accumulated during analysis for building summary."""
+
+    files_analyzed: int = 0
+    coverage_percent: float | None = None
+    dropped_count: int = 0
+    stale_file_count: int = 0
+    coverage_json_path: str | None = None
+    coverage_json_mtime: float | None = None
+
+
+# =============================================================================
+# Coverage Parsing
+# =============================================================================
+
+
+def find_coverage_file(repo_root: Path) -> Path | None:
+    """Find coverage.json in the repository.
+
+    Looks for:
+    1. coverage.json (coverage.py JSON output)
+    2. .coverage.json (alternate location)
+    3. htmlcov/status.json (coverage.py HTML report)
+    """
+    candidates = [
+        repo_root / "coverage.json",
+        repo_root / ".coverage.json",
+        repo_root / "htmlcov" / "status.json",
+    ]
+
+    for path in candidates:
+        if path.exists() and path.is_file():
+            return path
+
+    return None
+
+
+def parse_coverage_json(
+    coverage_path: Path, repo_root: Path
+) -> tuple[CoverageReport | None, str | None]:
+    """Parse coverage.py JSON format.
+
+    Handles the standard coverage.py JSON output format:
+    {
+        "meta": {...},
+        "files": {
+            "path/to/file.py": {
+                "executed_lines": [1, 2, 3],
+                "missing_lines": [4, 5],
+                "excluded_lines": [],
+                "summary": {
+                    "num_statements": 10,
+                    "covered_lines": 5,
+                    ...
+                }
+            }
+        },
+        "totals": {...}
+    }
+
+    Returns:
+        (report, error_message) - report is None if parsing failed
+    """
+    try:
+        with open(coverage_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except json.JSONDecodeError as e:
+        return None, f"Invalid JSON at line {e.lineno}: {e.msg}"
+    except OSError as e:
+        return None, f"Cannot read file: {e}"
+
+    # Validate expected structure
+    if not isinstance(data, dict):
+        return None, "Coverage file must be a JSON object"
+
+    if "files" not in data:
+        return None, "Coverage file missing 'files' field (expected coverage.py format)"
+
+    report = CoverageReport(source_path=str(coverage_path))
+
+    # Store coverage file mtime for staleness check
+    try:
+        report.coverage_mtime = coverage_path.stat().st_mtime
+    except OSError:
+        report.coverage_mtime = None
+
+    # Handle coverage.py format
+    files_data = data.get("files", {})
+
+    for file_path, file_data in files_data.items():
+        # Normalize path relative to repo root
+        try:
+            abs_path = Path(file_path)
+            if not abs_path.is_absolute():
+                abs_path = repo_root / file_path
+            rel_path = abs_path.relative_to(repo_root)
+        except ValueError:
+            rel_path = Path(file_path)
+
+        fc = FileCoverage(path=str(rel_path))
+
+        # Parse line data
+        fc.executed_lines = set(file_data.get("executed_lines", []))
+        fc.missing_lines = set(file_data.get("missing_lines", []))
+        fc.excluded_lines = set(file_data.get("excluded_lines", []))
+
+        # Parse summary
+        summary = file_data.get("summary", {})
+        fc.total_statements = summary.get("num_statements", 0)
+        fc.covered_statements = summary.get("covered_lines", len(fc.executed_lines))
+
+        report.files[str(rel_path)] = fc
+        report.total_statements += fc.total_statements
+        report.covered_statements += fc.covered_statements
+
+    return report, None
+
+
+def check_coverage_staleness(
+    report: CoverageReport,
+    repo_root: Path,
+    threshold_seconds: float = STALENESS_THRESHOLD_SECONDS,
+) -> tuple[dict[str, Any] | None, int]:
+    """Check if coverage data is stale (older than source files).
+
+    Returns:
+        (diagnostic_or_none, stale_file_count)
+    """
+    if report.coverage_mtime is None:
+        return None, 0
+
+    # Count files newer than coverage
+    stale_count = 0
+    newest_source_mtime: float | None = None
+    newest_source_path: str | None = None
+
+    for file_path in report.files.keys():
+        full_path = repo_root / file_path
+        if full_path.exists():
+            try:
+                mtime = full_path.stat().st_mtime
+                if mtime > report.coverage_mtime + threshold_seconds:
+                    stale_count += 1
+                if newest_source_mtime is None or mtime > newest_source_mtime:
+                    newest_source_mtime = mtime
+                    newest_source_path = file_path
+            except OSError:
+                continue
+
+    if newest_source_mtime is None:
+        return None, 0
+
+    # Check if source is newer than coverage by threshold
+    age_diff = newest_source_mtime - report.coverage_mtime
+    if age_diff > threshold_seconds:
+        hours_stale = int(age_diff / 3600)
+        diag = build_diagnostic(
+            code=DiagnosticCode.COVERAGE_FILE_STALE,
+            severity=Severity.WARNING,
+            message=f"Coverage data may be stale ({hours_stale}h behind source changes)",
+            evidence=[
+                f"Coverage file: {report.source_path}",
+                f"Newest source: {newest_source_path}",
+                f"Source is {hours_stale} hours newer than coverage",
+            ],
+            suggestions=[
+                "Run tests with coverage again: pytest --cov=. --cov-report=json",
+            ],
+        )
+        return diag, stale_count
+
+    return None, 0
+
+
+# =============================================================================
+# Analysis Engine
+# =============================================================================
+
+
+def analyze_coverage(
+    repo_root: Path, files_analyzed: int
+) -> tuple[CoverageReport | None, list[dict[str, Any]], AnalysisContext]:
+    """Analyze coverage data and generate diagnostics.
+
+    Returns:
+        (coverage_report, diagnostics, context)
+    """
+    diagnostics: list[dict[str, Any]] = []
+    truncated_count = 0
+    ctx = AnalysisContext(files_analyzed=files_analyzed)
+
+    # Find coverage file
+    coverage_path = find_coverage_file(repo_root)
+
+    if coverage_path is None:
+        diagnostics.append(
+            build_diagnostic(
+                code=DiagnosticCode.COVERAGE_DATA_MISSING,
+                severity=Severity.WARNING,
+                message="No coverage data found. Run tests with coverage first.",
+                evidence=[
+                    "Looked for: coverage.json, .coverage.json, htmlcov/status.json"
+                ],
+                suggestions=[
+                    "Run: pytest --cov=. --cov-report=json",
+                    "Or: coverage run -m pytest && coverage json",
+                ],
+            )
+        )
+        return None, diagnostics, ctx
+
+    # Parse coverage data
+    report, parse_error = parse_coverage_json(coverage_path, repo_root)
+
+    if report is None:
+        diagnostics.append(
+            build_diagnostic(
+                code=DiagnosticCode.COVERAGE_REPORT_PARSE_ERROR,
+                severity=Severity.ERROR,
+                message=f"Failed to parse coverage file: {parse_error}",
+                file=str(coverage_path.relative_to(repo_root))
+                if coverage_path.is_relative_to(repo_root)
+                else str(coverage_path),
+                suggestions=[
+                    "Check coverage file format is valid JSON",
+                    "Regenerate with: coverage json",
+                ],
+            )
+        )
+        return None, diagnostics, ctx
+
+    # Store evidence metadata in context
+    ctx.coverage_json_path = str(coverage_path)
+    ctx.coverage_json_mtime = report.coverage_mtime
+    ctx.coverage_percent = report.coverage_percent
+
+    # Check for stale coverage data
+    staleness_diag, stale_count = check_coverage_staleness(report, repo_root)
+    ctx.stale_file_count = stale_count
+    if staleness_diag:
+        diagnostics.append(staleness_diag)
+
+    # Generate diagnostics for each file
+    file_diag_counts: dict[str, int] = {}
+
+    for file_path, file_cov in report.files.items():
+        # Check total diagnostic limit
+        if len(diagnostics) >= MAX_TOTAL_DIAGNOSTICS:
+            truncated_count += 1
+            break
+
+        # Skip test files
+        if is_test_file(file_path):
+            continue
+
+        file_diag_counts[file_path] = 0
+
+        # Check for completely untested modules
+        if file_cov.coverage_percent == 0 and file_cov.total_statements > 0:
+            diagnostics.append(
+                build_diagnostic(
+                    code=DiagnosticCode.UNTESTED_MODULE,
+                    severity=Severity.WARNING,
+                    message=f"Module has no test coverage: {file_path}",
+                    file=file_path,
+                    line=1,
+                    evidence=[
+                        f"0% line coverage ({file_cov.total_statements} statements)",
+                        "No executed lines found",
+                    ],
+                    suggestions=[
+                        f"Add tests for {Path(file_path).stem}",
+                    ],
+                )
+            )
+            file_diag_counts[file_path] += 1
+            continue
+
+        # Report uncovered line ranges (group consecutive lines)
+        if file_cov.missing_lines:
+            ranges = group_line_ranges(sorted(file_cov.missing_lines))
+
+            # Limit per file
+            max_for_file = min(
+                MAX_DIAGNOSTICS_PER_FILE - file_diag_counts[file_path], 5
+            )
+            for start, end in ranges[:max_for_file]:
+                if len(diagnostics) >= MAX_TOTAL_DIAGNOSTICS:
+                    truncated_count += 1
+                    break
+
+                if start == end:
+                    msg = f"Line {start} not covered"
+                    line_desc = f"Line {start}"
+                else:
+                    msg = f"Lines {start}-{end} not covered"
+                    line_desc = f"Lines {start}-{end}"
+
+                diagnostics.append(
+                    build_diagnostic(
+                        code=DiagnosticCode.LINE_UNCOVERED,
+                        severity=Severity.INFO,
+                        message=msg,
+                        file=file_path,
+                        line=start,
+                        end_line=end if end != start else None,
+                        evidence=[
+                            f"{line_desc} never executed during tests",
+                            f"File coverage: {file_cov.coverage_percent:.1f}%",
+                        ],
+                    )
+                )
+                file_diag_counts[file_path] += 1
+
+            # If more ranges were truncated, note it
+            if len(ranges) > max_for_file:
+                remaining = len(ranges) - max_for_file
+                truncated_count += remaining
+
+    # Store dropped count in context before adding truncation diagnostic
+    ctx.dropped_count = truncated_count
+
+    # Add truncation diagnostic if we hit limits
+    if truncated_count > 0:
+        diagnostics.append(
+            build_diagnostic(
+                code=DiagnosticCode.DIAGNOSTICS_TRUNCATED,
+                severity=Severity.INFO,
+                message=f"{truncated_count} additional findings not shown",
+                evidence=[
+                    f"Limit: {MAX_TOTAL_DIAGNOSTICS} diagnostics, {MAX_DIAGNOSTICS_PER_FILE} per file",
+                    "Run with higher limits or fix existing issues first",
+                ],
+            )
+        )
+
+    return report, diagnostics, ctx
+
+
+def group_line_ranges(lines: list[int]) -> list[tuple[int, int]]:
+    """Group consecutive line numbers into ranges.
+
+    [1, 2, 3, 5, 7, 8, 9] -> [(1, 3), (5, 5), (7, 9)]
+    """
+    if not lines:
+        return []
+
+    ranges: list[tuple[int, int]] = []
+    start = lines[0]
+    end = lines[0]
+
+    for line in lines[1:]:
+        if line == end + 1:
+            end = line
+        else:
+            ranges.append((start, end))
+            start = line
+            end = line
+
+    ranges.append((start, end))
+    return ranges
+
+
+def is_test_file(path: str) -> bool:
+    """Check if a file is a test file."""
+    p = Path(path)
+    name = p.name.lower()
+
+    # Common test file patterns
+    if name.startswith("test_") or name.endswith("_test.py"):
+        return True
+    if name == "conftest.py":
+        return True
+
+    # Test directories
+    parts = p.parts
+    if "tests" in parts or "test" in parts:
+        return True
+
+    return False
+
+
+def find_python_files(repo_root: Path) -> list[Path]:
+    """Find all Python files in the repository."""
+    files = []
+
+    for path in repo_root.rglob("*.py"):
+        # Skip hidden directories and common excludes
+        parts = path.relative_to(repo_root).parts
+        if any(p.startswith(".") for p in parts):
+            continue
+        if any(
+            p in ("venv", ".venv", "node_modules", "__pycache__", "build", "dist")
+            for p in parts
+        ):
+            continue
+
+        files.append(path)
+
+    return files
+
+
+# =============================================================================
+# Output Builders
+# =============================================================================
+
+
+def build_version_response() -> dict[str, Any]:
+    """Build version --json response."""
+    return {
+        "cli_version": __version__,
+        "schema_version": SCHEMA_VERSION,
+        "python_version": platform.python_version(),
+        "platform": platform.system(),
+    }
+
+
+def build_summary(
+    diagnostics: list[dict[str, Any]],
+    ctx: AnalysisContext,
+) -> dict[str, Any]:
+    """Build the structured summary object."""
+    # Count by severity
+    errors = sum(1 for d in diagnostics if d["severity"] == Severity.ERROR)
+    warnings = sum(1 for d in diagnostics if d["severity"] == Severity.WARNING)
+    info = sum(1 for d in diagnostics if d["severity"] == Severity.INFO)
+
+    # Build by_code breakdown
+    by_code: dict[str, dict[str, Any]] = {}
+    for d in diagnostics:
+        code = d["code"]
+        if code not in by_code:
+            by_code[code] = {"count": 0, "severity": d["severity"]}
+        by_code[code]["count"] += 1
+
+    # Build evidence section (only if we have coverage data)
+    evidence: dict[str, Any] = {}
+    if ctx.coverage_json_path:
+        evidence["coverage_json_path"] = ctx.coverage_json_path
+    if ctx.coverage_json_mtime is not None:
+        evidence["coverage_json_mtime"] = datetime.fromtimestamp(
+            ctx.coverage_json_mtime, tz=timezone.utc
+        ).isoformat()
+    evidence["staleness_threshold_seconds"] = STALENESS_THRESHOLD_SECONDS
+    evidence["stale_file_count"] = ctx.stale_file_count
+
+    summary: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION,
+        "totals": {
+            "files_analyzed": ctx.files_analyzed,
+            "diagnostics_emitted": len(diagnostics),
+            "coverage_percent": ctx.coverage_percent,
+            "errors": errors,
+            "warnings": warnings,
+            "info": info,
+        },
+        "by_code": by_code,
+        "truncation": {
+            "is_truncated": ctx.dropped_count > 0,
+            "max_total": MAX_TOTAL_DIAGNOSTICS,
+            "max_per_file": MAX_DIAGNOSTICS_PER_FILE,
+            "emitted": len(diagnostics),
+            "dropped": ctx.dropped_count,
+        },
+    }
+
+    # Only include evidence if we have any data
+    if evidence:
+        summary["evidence"] = evidence
+
+    return summary
+
+
+def apply_strict_evidence(
+    diagnostics: list[dict[str, Any]],
+    summary: dict[str, Any],
+) -> None:
+    """Apply --strict-evidence transforms in place.
+
+    Promotes STRICT_EVIDENCE_CODES from warning to error.
+    Updates both diagnostics list and summary to stay consistent.
+    """
+    promoted_count = 0
+
+    # Transform diagnostics
+    for diag in diagnostics:
+        if (
+            diag["code"] in STRICT_EVIDENCE_CODES
+            and diag["severity"] == Severity.WARNING
+        ):
+            diag["severity"] = Severity.ERROR
+            promoted_count += 1
+
+    # Always mark the policy in summary for debuggability
+    summary["policy"] = {"strict_evidence": True}
+
+    if promoted_count == 0:
+        return
+
+    # Update summary totals
+    summary["totals"]["errors"] += promoted_count
+    summary["totals"]["warnings"] -= promoted_count
+
+    # Update by_code severities
+    for code in STRICT_EVIDENCE_CODES:
+        if code in summary["by_code"]:
+            summary["by_code"][code]["severity"] = Severity.ERROR
+
+
+def build_analyze_response(
+    status: str,
+    repo_root: str,
+    diagnostics: list[dict[str, Any]],
+    ctx: AnalysisContext,
+) -> dict[str, Any]:
+    """Build analyze --json response."""
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "status": status,
+        "repo_root": repo_root,
+        "summary": build_summary(diagnostics, ctx),
+        "diagnostics": diagnostics,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def build_diagnostic(
+    code: str,
+    severity: str,
+    message: str,
+    file: str | None = None,
+    line: int | None = None,
+    column: int | None = None,
+    end_line: int | None = None,
+    end_column: int | None = None,
+    evidence: list[str] | None = None,
+    suggestions: list[str] | None = None,
+) -> dict[str, Any]:
+    """Build a single diagnostic entry."""
+    diag: dict[str, Any] = {
+        "code": code,
+        "severity": severity,
+        "message": message,
+    }
+    if file is not None:
+        diag["file"] = file
+    if line is not None:
+        diag["line"] = line
+    if column is not None:
+        diag["column"] = column
+    if end_line is not None:
+        diag["end_line"] = end_line
+    if end_column is not None:
+        diag["end_column"] = end_column
+    if evidence:
+        diag["evidence"] = evidence
+    if suggestions:
+        diag["suggestions"] = suggestions
+    return diag
+
+
+# =============================================================================
+# Commands
+# =============================================================================
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    """Handle version command."""
+    if args.json:
+        print(json.dumps(build_version_response(), indent=2))
+    else:
+        print(f"codeclone {__version__}")
+        print(f"Schema version: {SCHEMA_VERSION}")
+        print(f"Python: {platform.python_version()}")
+        print(f"Platform: {platform.system()}")
+    return 0
+
+
+def cmd_analyze(args: argparse.Namespace) -> int:
+    """Handle analyze command."""
+    repo_root = Path(args.repo_root).resolve()
+    repo_root_str = str(repo_root)
+
+    # Check if repo exists
+    if not repo_root.exists():
+        ctx = AnalysisContext()
+        diags = [
+            build_diagnostic(
+                code=DiagnosticCode.REPO_ROOT_NOT_FOUND,
+                severity=Severity.ERROR,
+                message=f"Repository root does not exist: {repo_root_str}",
+                suggestions=["Check the path and try again"],
+            )
+        ]
+        if args.json:
+            response = build_analyze_response(
+                status="FAIL",
+                repo_root=repo_root_str,
+                diagnostics=diags,
+                ctx=ctx,
+            )
+            print(json.dumps(response, indent=2))
+        else:
+            print(
+                f"Error: Repository root does not exist: {repo_root_str}",
+                file=sys.stderr,
+            )
+        return 2
+
+    if not repo_root.is_dir():
+        ctx = AnalysisContext()
+        diags = [
+            build_diagnostic(
+                code=DiagnosticCode.REPO_ROOT_NOT_FOUND,
+                severity=Severity.ERROR,
+                message=f"Repository root is not a directory: {repo_root_str}",
+                suggestions=["Provide a directory path, not a file"],
+            )
+        ]
+        if args.json:
+            response = build_analyze_response(
+                status="FAIL",
+                repo_root=repo_root_str,
+                diagnostics=diags,
+                ctx=ctx,
+            )
+            print(json.dumps(response, indent=2))
+        else:
+            print(
+                f"Error: Repository root is not a directory: {repo_root_str}",
+                file=sys.stderr,
+            )
+        return 2
+
+    # Find Python files
+    python_files = find_python_files(repo_root)
+    files_analyzed = len(python_files)
+
+    # Run analysis
+    report, diagnostics, ctx = analyze_coverage(repo_root, files_analyzed)
+
+    # Build summary (natural severities first)
+    summary = build_summary(diagnostics, ctx)
+
+    # Apply strict-evidence transform if requested
+    if args.strict_evidence:
+        apply_strict_evidence(diagnostics, summary)
+
+    # Determine status from (potentially transformed) diagnostics
+    has_errors = any(d["severity"] == Severity.ERROR for d in diagnostics)
+    has_warnings = any(d["severity"] == Severity.WARNING for d in diagnostics)
+
+    if has_errors:
+        status = "FAIL"
+        exit_code = 2
+    elif has_warnings:
+        status = "PARTIAL"
+        exit_code = 1
+    else:
+        status = "OK"
+        exit_code = 0
+
+    if args.json:
+        response = {
+            "schema_version": SCHEMA_VERSION,
+            "status": status,
+            "repo_root": repo_root_str,
+            "summary": summary,
+            "diagnostics": diagnostics,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        print(json.dumps(response, indent=2))
+    else:
+        print(f"Analyzing: {repo_root_str}")
+        print(f"Files analyzed: {ctx.files_analyzed}")
+        if ctx.coverage_percent is not None:
+            print(f"Coverage: {ctx.coverage_percent:.1f}%")
+        print(f"Status: {status}")
+        print(f"Diagnostics: {len(diagnostics)}")
+
+        if diagnostics:
+            print("\nFindings:")
+            for d in diagnostics[:10]:  # Limit human output
+                sev = d["severity"].upper()
+                code = d["code"]
+                msg = d["message"]
+                print(f"  [{sev}] {code}: {msg}")
+            if len(diagnostics) > 10:
+                print(f"  ... and {len(diagnostics) - 10} more")
+
+        # Human-friendly summary footer (uses pre-built summary)
+        totals = summary["totals"]
+        trunc = summary["truncation"]
+        print(
+            f"\nErrors: {totals['errors']}, Warnings: {totals['warnings']}, Info: {totals['info']}",
+            end="",
+        )
+        if trunc["is_truncated"]:
+            print(f", Dropped: {trunc['dropped']}")
+        else:
+            print()
+
+    return exit_code
+
+
+# =============================================================================
+# CLI Entry Point
+# =============================================================================
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="codeclone",
+        description="CodeClone - Deterministic code coverage analysis",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # version command
+    version_parser = subparsers.add_parser("version", help="Show version information")
+    version_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON",
+    )
+
+    # analyze command
+    analyze_parser = subparsers.add_parser("analyze", help="Analyze a repository")
+    analyze_parser.add_argument(
+        "repo_root",
+        help="Path to repository root",
+    )
+    analyze_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON (required for editor integration)",
+    )
+    analyze_parser.add_argument(
+        "--strict-evidence",
+        action="store_true",
+        help="Promote evidence freshness warnings (COVERAGE_FILE_STALE) to errors; exit 2 when coverage is stale",
+    )
+
+    return parser
+
+
+def main() -> int:
+    """Main entry point."""
+    parser = create_parser()
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        return 1
+
+    if args.command == "version":
+        return cmd_version(args)
+    elif args.command == "analyze":
+        return cmd_analyze(args)
+    else:
+        parser.print_help()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

codeclone_cli-1.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codeclone-cli"
+version = "1.0.0"
+description = "CodeClone CLI - Deterministic code coverage analysis"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "mcp-tool-shop", email = "64996768+mcp-tool-shop@users.noreply.github.com" }
+]
+keywords = ["coverage", "testing", "analysis", "cli"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "jsonschema>=4.0",
+    "mypy>=1.0",
+    "ruff>=0.4",
+]
+
+[project.scripts]
+codeclone = "codeclone_cli:main"
+
+[project.urls]
+Homepage = "https://github.com/mcp-tool-shop-org/codeclone-suite"
+Repository = "https://github.com/mcp-tool-shop-org/codeclone-suite"
+Documentation = "https://github.com/mcp-tool-shop-org/codeclone-suite/blob/main/docs/EDITOR_INTEGRATION.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]