easy-coding-harness 0.10.0-beta.0 → 0.10.0-beta.2

package/templates/runtime/tools/easy_coding_java_coverage.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""Gate changed Java production lines with one or more JaCoCo XML reports."""
+
+import argparse
+import ast
+import hashlib
+import json
+import re
+import subprocess
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+
+DEFAULT_THRESHOLD = 90
+HUNK_PATTERN = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@")
+TEST_PATH_PARTS = {"test", "tests", "testfixtures", "integrationtest"}
+
+
+class CoverageError(Exception):
+    pass
+
+
+def run_git(repo: Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", "-C", str(repo), *args],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise CoverageError(result.stderr.strip() or "git command failed")
+    return result.stdout
+
+
+def changed_java_lines(repo: Path, base: str) -> dict[str, set[int]]:
+    diff = run_git(
+        repo,
+        "-c",
+        "core.quotePath=false",
+        "diff",
+        "--unified=0",
+        "--no-ext-diff",
+        base,
+        "--",
+        "*.java",
+    )
+    changed: dict[str, set[int]] = {}
+    current: str | None = None
+    new_line = 0
+    for line in diff.splitlines():
+        if line.startswith("+++ "):
+            target = line[4:].strip()
+            if target.startswith('"'):
+                try:
+                    target = ast.literal_eval(target)
+                except (SyntaxError, ValueError) as error:
+                    raise CoverageError(f"Cannot decode Git diff path: {target}") from error
+            current = None if target == "/dev/null" else target.removeprefix("b/")
+            if current and not is_production_java(current):
+                current = None
+            continue
+        match = HUNK_PATTERN.match(line)
+        if match:
+            new_line = int(match.group(1))
+            continue
+        if current is None or line.startswith(("--- ", "diff ", "index ")):
+            continue
+        if line.startswith("+") and not line.startswith("+++"):
+            changed.setdefault(current, set()).add(new_line)
+            new_line += 1
+        elif not line.startswith("-"):
+            new_line += 1
+    untracked = run_git(
+        repo,
+        "ls-files",
+        "--others",
+        "--exclude-standard",
+        "-z",
+        "--",
+        "*.java",
+    )
+    for file_path in filter(None, untracked.split("\0")):
+        if not is_production_java(file_path):
+            continue
+        candidate = repo / file_path
+        try:
+            line_count = len(candidate.read_text(encoding="utf-8").splitlines())
+        except (OSError, UnicodeError) as error:
+            raise CoverageError(f"Cannot read untracked Java source {file_path}: {error}") from error
+        changed.setdefault(file_path, set()).update(range(1, line_count + 1))
+    return changed
+
+
+def is_production_java(file_path: str) -> bool:
+    path = Path(file_path)
+    if path.suffix != ".java":
+        return False
+    parts = {part.lower() for part in path.parts}
+    if TEST_PATH_PARTS & parts:
+        return False
+    return True
+
+
+def report_module_prefix(report: Path, repo: Path) -> str:
+    relative = report.resolve().relative_to(repo.resolve()).as_posix()
+    if "/target/site/jacoco-aggregate/" in f"/{relative}":
+        return ""
+    markers = ("/target/", "/build/reports/")
+    for marker in markers:
+        if marker in f"/{relative}":
+            prefix = f"/{relative}".split(marker, 1)[0].lstrip("/")
+            return f"{prefix}/" if prefix else ""
+    return ""
+
+
+def parse_reports(
+    repo: Path, reports: list[Path]
+) -> tuple[list[tuple[str, str, dict[int, bool], Path]], str]:
+    sources: list[tuple[str, str, dict[int, bool], Path]] = []
+    digest = hashlib.sha256()
+    for report in reports:
+        try:
+            payload = report.read_bytes()
+            root = ET.fromstring(payload)
+        except (OSError, ET.ParseError) as error:
+            raise CoverageError(f"Cannot read JaCoCo XML report {report}: {error}") from error
+        try:
+            report_name = report.resolve().relative_to(repo.resolve()).as_posix()
+        except ValueError as error:
+            raise CoverageError(f"JaCoCo XML report must be inside the Git repository: {report}") from error
+        digest.update(report_name.encode())
+        digest.update(b"\0")
+        digest.update(payload)
+        digest.update(b"\0")
+        prefix = report_module_prefix(report, repo)
+        for package in root.findall(".//package"):
+            package_name = package.get("name", "").strip("/")
+            for source in package.findall("sourcefile"):
+                source_name = source.get("name", "")
+                suffix = "/".join(part for part in (package_name, source_name) if part)
+                executable: dict[int, bool] = {}
+                try:
+                    for line in source.findall("line"):
+                        number = int(line.get("nr", "0"))
+                        covered = int(line.get("ci", "0")) > 0 or int(line.get("cb", "0")) > 0
+                        executable[number] = executable.get(number, False) or covered
+                except ValueError as error:
+                    raise CoverageError(f"Invalid JaCoCo line counters in {report}") from error
+                sources.append((prefix, suffix, executable, report))
+    return sources, digest.hexdigest()
+
+
+def discover_reports(repo: Path) -> list[Path]:
+    regular = [
+        *repo.glob("**/target/site/jacoco/jacoco.xml"),
+        *repo.glob("**/build/reports/jacoco/**/jacocoTestReport.xml"),
+    ]
+    reports = sorted({candidate.resolve() for candidate in regular if candidate.is_file()})
+    if reports:
+        return reports
+    aggregate = repo.glob("**/target/site/jacoco-aggregate/jacoco.xml")
+    return sorted({candidate.resolve() for candidate in aggregate if candidate.is_file()})
+
+
+def read_project_threshold(repo: Path) -> int:
+    path = repo / ".easy-coding" / "config.yaml"
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return DEFAULT_THRESHOLD
+    in_behavior = False
+    behavior_indent = 0
+    schema_version = 0
+    for raw in lines:
+        clean = raw.split("#", 1)[0].rstrip()
+        stripped = clean.strip()
+        if not stripped:
+            continue
+        indent = len(clean) - len(clean.lstrip(" "))
+        if stripped == "behavior:":
+            in_behavior = True
+            behavior_indent = indent
+            continue
+        if in_behavior and indent <= behavior_indent:
+            in_behavior = False
+        if not in_behavior and indent == 0 and stripped.startswith("version:"):
+            try:
+                schema_version = int(stripped.split(":", 1)[1].strip().strip("'\""))
+            except ValueError:
+                schema_version = 0
+            continue
+        if (
+            schema_version >= 4
+            and in_behavior
+            and stripped.startswith("tdd_coverage_threshold:")
+        ):
+            try:
+                value = int(stripped.split(":", 1)[1].strip().strip("'\""))
+            except ValueError as error:
+                raise CoverageError("Invalid behavior.tdd_coverage_threshold") from error
+            if not 1 <= value <= 100:
+                raise CoverageError("TDD coverage threshold must be from 1 to 100")
+            return value
+    return DEFAULT_THRESHOLD
+
+
+def calculate(
+    repo: Path, base: str, reports: list[Path], threshold: int
+) -> dict[str, object]:
+    baseline_sha = run_git(repo, "rev-parse", "--verify", f"{base}^{{commit}}").strip()
+    if re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", baseline_sha) is None:
+        raise CoverageError(f"Invalid Git baseline commit: {base}")
+    try:
+        run_git(repo, "merge-base", "--is-ancestor", baseline_sha, "HEAD")
+    except CoverageError as error:
+        raise CoverageError(
+            f"Git baseline {baseline_sha} is not an ancestor of HEAD"
+        ) from error
+    changed = changed_java_lines(repo, base)
+    sources, report_sha = parse_reports(repo, reports)
+    covered = 0
+    total = 0
+    files: list[dict[str, object]] = []
+    missing: list[str] = []
+    for file_path, added_lines in sorted(changed.items()):
+        matches: list[tuple[dict[int, bool], Path]] = []
+        for prefix, suffix, lines, report in sources:
+            if (not prefix or file_path.startswith(prefix)) and file_path.endswith(suffix):
+                matches.append((lines, report))
+        if len(matches) != 1:
+            missing.append(file_path)
+            continue
+        executable, matched_report = matches[0]
+        source_path = repo / file_path
+        try:
+            if matched_report.stat().st_mtime_ns < source_path.stat().st_mtime_ns:
+                raise CoverageError(
+                    f"JaCoCo XML report is older than modified Java source {file_path}; regenerate unit-test coverage"
+                )
+        except OSError as error:
+            raise CoverageError(
+                f"Cannot compare JaCoCo report freshness for {file_path}: {error}"
+            ) from error
+        relevant = sorted(added_lines & executable.keys())
+        file_covered = sum(1 for number in relevant if executable[number])
+        covered += file_covered
+        total += len(relevant)
+        files.append(
+            {
+                "path": file_path,
+                "covered_lines": file_covered,
+                "total_lines": len(relevant),
+            }
+        )
+    if missing:
+        raise CoverageError(
+            "Modified production Java files are missing or ambiguous in JaCoCo XML: "
+            + ", ".join(missing)
+        )
+    percentage = 100.0 if total == 0 else round(covered * 100.0 / total, 2)
+    applicable = total > 0
+    return {
+        "baseline_sha": baseline_sha,
+        "covered_lines": covered,
+        "total_lines": total,
+        "percentage": percentage,
+        "threshold": threshold,
+        "applicable": applicable,
+        "not_applicable_reason": None if applicable else "no modified executable production Java lines",
+        "passed": percentage >= threshold,
+        "report_paths": [str(report.resolve().relative_to(repo.resolve())) for report in reports],
+        "report_sha256": report_sha,
+        "files": files,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subcommands = parser.add_subparsers(dest="command", required=True)
+    check = subcommands.add_parser("check")
+    check.add_argument("--base", required=True)
+    check.add_argument("--repo", default=".")
+    check.add_argument("--report", action="append", default=[])
+    check.add_argument("--threshold", type=int)
+    check.add_argument("--output")
+    args = parser.parse_args()
+    try:
+        requested_repo = Path(args.repo).resolve()
+        repo = Path(run_git(requested_repo, "rev-parse", "--show-toplevel").strip()).resolve()
+        threshold = (
+            args.threshold
+            if args.threshold is not None
+            else read_project_threshold(repo)
+        )
+        if not 1 <= threshold <= 100:
+            raise CoverageError("TDD coverage threshold must be from 1 to 100")
+        reports = (
+            sorted({Path(item).resolve() for item in args.report})
+            if args.report
+            else discover_reports(repo)
+        )
+        if not reports:
+            raise CoverageError("No JaCoCo XML report found; pass --report or generate one first")
+        result = calculate(repo, args.base, reports, threshold)
+        payload = json.dumps(result, ensure_ascii=False, indent=2)
+        if args.output:
+            Path(args.output).write_text(payload + "\n", encoding="utf-8")
+        print(payload)
+        return 0 if result["passed"] else 1
+    except CoverageError as error:
+        print(json.dumps({"passed": False, "error": str(error)}, ensure_ascii=False), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/runtime/tools/easy_coding_tdd_readiness.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python3
+"""Record and verify Easy Coding Java TDD infrastructure readiness.
+
+This tool validates infrastructure only. It never measures repository-wide coverage and never
+creates business tests. Coverage acceptance remains scoped to production lines changed after a
+task's frozen baseline.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shlex
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+SCHEMA = "easy-coding/tdd-readiness-v1"
+COVERAGE_SCOPE = "changed-production-lines"
+RECEIPT = Path(".easy-coding/tdd/readiness.json")
+TDD_BASE_VARIABLE = "EASY_CODING_TDD_BASE_SHA"
+TDD_THRESHOLD_VARIABLE = "EASY_CODING_TDD_THRESHOLD"
+COVERAGE_TOOL_PATH = ".easy-coding/tools/easy_coding_java_coverage.py"
+JAVA_BUILD_FILE_NAMES = {"pom.xml", "build.gradle", "build.gradle.kts"}
+GITLAB_CI_ENTRY_FILES = {".gitlab-ci.yml", ".gitlab-ci.yaml"}
+
+
+class ReadinessError(RuntimeError):
+    pass
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def project_file(root: Path, value: str) -> tuple[str, Path]:
+    candidate = Path(value)
+    if candidate.is_absolute():
+        resolved = candidate.resolve()
+    else:
+        resolved = (root / candidate).resolve()
+    try:
+        relative = resolved.relative_to(root.resolve()).as_posix()
+    except ValueError as error:
+        raise ReadinessError(f"Path escapes project root: {value}") from error
+    if not resolved.is_file():
+        raise ReadinessError(f"Required file is missing: {relative}")
+    return relative, resolved
+
+
+def file_record(root: Path, value: str) -> dict[str, str]:
+    relative, resolved = project_file(root, value)
+    return {"path": relative, "sha256": sha256(resolved)}
+
+
+def safe_report_pattern(value: str) -> bool:
+    candidate = Path(value)
+    return bool(value.strip()) and not candidate.is_absolute() and ".." not in candidate.parts
+
+
+def required_gate_variables(command: str) -> bool:
+    try:
+        tokens = shlex.split(command)
+    except ValueError:
+        return False
+    options: dict[str, str] = {}
+    for index, token in enumerate(tokens[:-1]):
+        if token in {"--base", "--threshold"}:
+            options[token] = tokens[index + 1]
+    return options.get("--base") in {
+        f"${TDD_BASE_VARIABLE}",
+        "$" + "{" + TDD_BASE_VARIABLE + "}",
+    } and options.get("--threshold") in {
+        f"${TDD_THRESHOLD_VARIABLE}",
+        "$" + "{" + TDD_THRESHOLD_VARIABLE + "}",
+    }
+
+
+def ci_contract_reasons(contents: list[str]) -> list[str]:
+    combined = "\n".join(
+        re.sub(r"\s+#.*$", "", re.sub(r"^\s*#.*$", "", line))
+        for line in "\n".join(contents).splitlines()
+    )
+    lowered = combined.lower()
+    reasons: list[str] = []
+    for marker in (
+        "jacoco",
+        "artifacts",
+        COVERAGE_TOOL_PATH,
+        TDD_BASE_VARIABLE,
+        TDD_THRESHOLD_VARIABLE,
+    ):
+        if marker.lower() not in lowered:
+            reasons.append(f"CI files do not contain required marker: {marker}")
+    if not required_gate_variables(combined):
+        reasons.append(
+            "CI changed-line gate must use the task baseline and threshold variables"
+        )
+    if re.search(r"(?:^|\n)\s*stage\s*:\s*['\"]?test['\"]?\s*(?:#.*)?(?:\n|$)", combined, re.I) is None:
+        reasons.append("CI files do not declare a TEST-stage job")
+    return reasons
+
+
+def parse_records(root: Path, value: object, field: str, reasons: list[str]) -> list[str]:
+    if not isinstance(value, list) or not value:
+        reasons.append(f"{field} must contain at least one file")
+        return []
+    contents: list[str] = []
+    for item in value:
+        if not isinstance(item, dict):
+            reasons.append(f"{field} contains an invalid record")
+            continue
+        file_name = item.get("path")
+        expected = item.get("sha256")
+        if not isinstance(file_name, str) or not isinstance(expected, str):
+            reasons.append(f"{field} contains an invalid path or SHA-256")
+            continue
+        try:
+            _, resolved = project_file(root, file_name)
+            if sha256(resolved) != expected:
+                reasons.append(f"readiness file changed: {file_name}")
+            contents.append(resolved.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, ReadinessError) as error:
+            reasons.append(str(error))
+    return contents
+
+
+def inspect(root: Path) -> dict[str, object]:
+    receipt = root / RECEIPT
+    if not receipt.is_file():
+        return {
+            "status": "needs_init",
+            "coverage_scope": COVERAGE_SCOPE,
+            "reasons": ["TDD readiness receipt is missing"],
+            "receipt": RECEIPT.as_posix(),
+        }
+    try:
+        manifest = json.loads(receipt.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return {
+            "status": "needs_init",
+            "coverage_scope": COVERAGE_SCOPE,
+            "reasons": ["TDD readiness receipt is invalid"],
+            "receipt": RECEIPT.as_posix(),
+        }
+
+    reasons: list[str] = []
+    if not isinstance(manifest, dict):
+        reasons.append("TDD readiness receipt must be a JSON object")
+        manifest = {}
+    if manifest.get("schema") != SCHEMA:
+        reasons.append("unsupported readiness schema")
+    if manifest.get("provider") != "gitlab":
+        reasons.append("readiness provider must be gitlab")
+    if manifest.get("coverage_scope") != COVERAGE_SCOPE:
+        reasons.append("coverage scope must be changed-production-lines")
+    if manifest.get("historical_coverage_required") is not False:
+        reasons.append("historical coverage must remain disabled")
+    patterns = manifest.get("coverage_report_patterns")
+    if not isinstance(patterns, list) or not patterns or not all(
+        isinstance(item, str) and safe_report_pattern(item) for item in patterns
+    ):
+        reasons.append(
+            "coverage_report_patterns must contain safe project-relative report patterns"
+        )
+    gate = manifest.get("changed_line_gate_command")
+    if not isinstance(gate, str) or COVERAGE_TOOL_PATH not in gate:
+        reasons.append("changed-line coverage gate command is missing")
+    elif not required_gate_variables(gate):
+        reasons.append(
+            "changed-line coverage gate must use the task baseline and threshold variables"
+        )
+
+    manifest_build_files = manifest.get("build_files")
+    manifest_ci_files = manifest.get("ci_files")
+    manifest_tool_files = manifest.get("tool_files")
+    build_contents = parse_records(root, manifest_build_files, "build_files", reasons)
+    ci_contents = parse_records(root, manifest_ci_files, "ci_files", reasons)
+    parse_records(root, manifest_tool_files, "tool_files", reasons)
+    build_paths = {
+        Path(item.get("path", "")).name
+        for item in manifest_build_files
+        if isinstance(item, dict) and isinstance(item.get("path"), str)
+    } if isinstance(manifest_build_files, list) else set()
+    ci_paths = {
+        item.get("path", "").replace("\\", "/")
+        for item in manifest_ci_files
+        if isinstance(item, dict) and isinstance(item.get("path"), str)
+    } if isinstance(manifest_ci_files, list) else set()
+    if not build_paths.intersection(JAVA_BUILD_FILE_NAMES):
+        reasons.append("build_files must include a Maven or Gradle Java build file")
+    if not ci_paths.intersection(GITLAB_CI_ENTRY_FILES):
+        reasons.append("ci_files must include the project-root GitLab CI entry file")
+    tool_paths = {
+        item.get("path", "").replace("\\", "/")
+        for item in manifest_tool_files
+        if isinstance(item, dict) and isinstance(item.get("path"), str)
+    } if isinstance(manifest_tool_files, list) else set()
+    if COVERAGE_TOOL_PATH not in tool_paths:
+        reasons.append(f"tool_files must include {COVERAGE_TOOL_PATH}")
+    if not any("jacoco" in content.lower() for content in build_contents):
+        reasons.append("build files do not configure JaCoCo")
+    reasons.extend(ci_contract_reasons(ci_contents))
+
+    return {
+        "status": "ready" if not reasons else "needs_init",
+        "coverage_scope": COVERAGE_SCOPE,
+        "reasons": list(dict.fromkeys(reasons)),
+        "receipt": RECEIPT.as_posix(),
+    }
+
+
+def record(args: argparse.Namespace, root: Path) -> dict[str, object]:
+    if not args.build_file:
+        raise ReadinessError("At least one --build-file is required.")
+    if not args.ci_file:
+        raise ReadinessError("At least one --ci-file is required.")
+    if not args.coverage_report:
+        raise ReadinessError("At least one --coverage-report is required.")
+    if not all(safe_report_pattern(value) for value in args.coverage_report):
+        raise ReadinessError("--coverage-report values must be safe project-relative patterns.")
+    if COVERAGE_TOOL_PATH not in args.gate_command:
+        raise ReadinessError(f"--gate-command must invoke {COVERAGE_TOOL_PATH}.")
+    if not required_gate_variables(args.gate_command):
+        raise ReadinessError(
+            "--gate-command must use $EASY_CODING_TDD_BASE_SHA and "
+            "$EASY_CODING_TDD_THRESHOLD."
+        )
+
+    build_records = [file_record(root, value) for value in args.build_file]
+    ci_records = [file_record(root, value) for value in args.ci_file]
+    tool_records = [file_record(root, COVERAGE_TOOL_PATH)]
+    if not any(Path(item["path"]).name in JAVA_BUILD_FILE_NAMES for item in build_records):
+        raise ReadinessError("--build-file must include pom.xml, build.gradle, or build.gradle.kts.")
+    if not any(item["path"] in GITLAB_CI_ENTRY_FILES for item in ci_records):
+        raise ReadinessError(
+            "--ci-file must include the project-root .gitlab-ci.yml or .gitlab-ci.yaml."
+        )
+    build_contents = [
+        (root / record_item["path"]).read_text(encoding="utf-8")
+        for record_item in build_records
+    ]
+    ci_contents = [
+        (root / record_item["path"]).read_text(encoding="utf-8") for record_item in ci_records
+    ]
+    if not any("jacoco" in content.lower() for content in build_contents):
+        raise ReadinessError("Build files must configure JaCoCo before readiness can be recorded.")
+    ci_reasons = ci_contract_reasons(ci_contents)
+    if ci_reasons:
+        raise ReadinessError("; ".join(ci_reasons))
+
+    manifest = {
+        "schema": SCHEMA,
+        "provider": "gitlab",
+        "coverage_scope": COVERAGE_SCOPE,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "generated_by": args.agent,
+        "build_files": build_records,
+        "ci_files": ci_records,
+        "tool_files": tool_records,
+        "coverage_report_patterns": args.coverage_report,
+        "changed_line_gate_command": args.gate_command,
+        "historical_coverage_required": False,
+    }
+    receipt = root / RECEIPT
+    receipt.parent.mkdir(parents=True, exist_ok=True)
+    temporary = receipt.with_suffix(f".tmp-{os.getpid()}")
+    temporary.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    temporary.replace(receipt)
+    result = inspect(root)
+    if result["status"] != "ready":
+        raise ReadinessError("Recorded readiness receipt did not pass validation.")
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Easy Coding Java TDD readiness tool")
+    parser.add_argument("--cwd", default=".")
+    subcommands = parser.add_subparsers(dest="command", required=True)
+    subcommands.add_parser("check")
+    record_parser = subcommands.add_parser("record")
+    record_parser.add_argument("--build-file", action="append", default=[])
+    record_parser.add_argument("--ci-file", action="append", default=[])
+    record_parser.add_argument("--coverage-report", action="append", default=[])
+    record_parser.add_argument("--gate-command", required=True)
+    record_parser.add_argument("--agent", required=True)
+    args = parser.parse_args()
+    root = Path(args.cwd).resolve()
+    try:
+        result = inspect(root) if args.command == "check" else record(args, root)
+    except (OSError, UnicodeError, ReadinessError) as error:
+        print(json.dumps({"status": "needs_init", "reasons": [str(error)]}, ensure_ascii=False))
+        return 2
+    print(json.dumps(result, ensure_ascii=False))
+    return 0 if result["status"] == "ready" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())