springdocker 1.0.1__py3-none-any.whl

springdocker/commands.py

@@ -0,0 +1,388 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import cast
+
+from .benchmarks.generate import generate_benchmark_assets
+from .benchmarks.runner import run_benchmarks
+from .errors import EXIT_FAILURE, EXIT_OK, EXIT_USAGE, print_error, print_warning
+from .project_detect import inspect_project
+from .regression import format_regression_json, format_regression_table
+from .services import benchmark_service, dockerfile_service, project_service
+
+
+def run_checked(command: list[str], cwd: Path) -> int:
+    print("$ " + " ".join(command))
+    completed = subprocess.run(command, cwd=cwd)
+    return completed.returncode
+
+
+def cmd_doctor(project_root: Path, build_tool: str | None) -> int:
+    try:
+        info = project_service.load_project_info(project_root, build_tool)
+    except ValueError as exc:
+        print_error(str(exc))
+        return EXIT_USAGE
+
+    print(f"project_root: {info.root}")
+    print(f"build_tool: {info.build_tool}")
+    print(f"spring_markers: {'yes' if info.has_spring_markers else 'no'}")
+    if not info.has_spring_markers:
+        print_warning("Spring Boot markers were not found; continue only if this is intentional.")
+    return EXIT_OK
+
+
+def _render_inspect_table(info) -> str:
+    lines = [
+        "| Field | Value |",
+        "|---|---|",
+        f"| Project root | {info.root} |",
+        f"| Build tool | {info.build_tool} |",
+        f"| Spring markers | {'yes' if info.has_spring_markers else 'no'} |",
+        f"| Java version | {info.java_version if info.java_version is not None else '-'} |",
+        f"| Spring Boot version | {info.spring_boot_version or '-'} |",
+        f"| Config exists | {'yes' if info.config_exists else 'no'} |",
+        f"| Generated Dockerfiles | {', '.join(info.generated_dockerfiles) or '-'} |",
+        f"| Direct dependencies | {', '.join(info.direct_dependencies) or '-'} |",
+        f"| Reflection hits | {len(info.reflection_hits)} |",
+        f"| Runtime compatibility | {info.runtime_compatibility} |",
+        f"| Recommendations | {'; '.join(info.recommendations) or '-'} |",
+    ]
+    return "\n".join(lines)
+
+
+def cmd_inspect(project_root: Path, build_tool: str | None, output_format: str) -> int:
+    try:
+        info = project_service.load_project_details(project_root, build_tool)
+    except ValueError as exc:
+        print_error(str(exc))
+        return EXIT_USAGE
+
+    payload = {
+        "project_root": str(info.root),
+        "build_tool": info.build_tool,
+        "has_spring_markers": info.has_spring_markers,
+        "java_version": info.java_version,
+        "spring_boot_version": info.spring_boot_version,
+        "direct_dependencies": list(info.direct_dependencies),
+        "config_exists": info.config_exists,
+        "generated_dockerfiles": list(info.generated_dockerfiles),
+        "reflection_hits": list(info.reflection_hits),
+        "runtime_compatibility": info.runtime_compatibility,
+        "recommendations": list(info.recommendations),
+    }
+    if output_format == "json":
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(_render_inspect_table(info))
+    return EXIT_OK
+
+
+def _render_explain_table(payload: dict[str, object]) -> str:
+    features = cast(list[dict[str, object]], payload.get("features", []))
+    feature_names = ", ".join(
+        str(feature["name"]) for feature in features if feature.get("enabled") and "name" in feature
+    )
+    notes = cast(list[str], payload.get("notes", []))
+    return "\n".join(
+        [
+            "| Field | Value |",
+            "|---|---|",
+            f"| Source | {payload.get('source', '-')} |",
+            f"| Build tool | {payload.get('build_tool') or '-'} |",
+            f"| Java version | {payload.get('java_version') if payload.get('java_version') is not None else '-'} |",
+            f"| Stage count | {payload.get('stage_count', '-')} |",
+            f"| Features | {feature_names or '-'} |",
+            f"| Summary | {payload.get('summary', '-')} |",
+            f"| Notes | {'; '.join(notes) if notes else '-'} |",
+        ]
+    )
+
+
+def cmd_benchmark_compare(
+    project_root: Path,
+    raw_csv: str,
+    baseline_variant: str,
+    output_format: str,
+    scenario: str | None,
+) -> int:
+    try:
+        rendered = benchmark_service.render_comparison(
+            project_root=project_root,
+            raw_csv=raw_csv,
+            baseline_variant=baseline_variant,
+            output_format=output_format,
+            scenario=scenario,
+        )
+    except ValueError as exc:
+        print_error(str(exc))
+        return EXIT_USAGE
+
+    print(rendered)
+    return EXIT_OK
+
+
+def cmd_explain(project_root: Path, dockerfile_path: str, output_format: str) -> int:
+    try:
+        payload = dockerfile_service.explain_dockerfile(project_root, dockerfile_path)
+    except ValueError as exc:
+        print_error(str(exc))
+        return EXIT_USAGE
+
+    if output_format == "json":
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(_render_explain_table(payload))
+    return EXIT_OK
+
+
+def cmd_init(
+    project_root: Path,
+    build_tool: str | None,
+    config_path: Path,
+    profile: str,
+    force: bool,
+    print_only: bool,
+) -> int:
+    try:
+        result = project_service.prepare_default_config(
+            project_root=project_root,
+            build_tool=build_tool,
+            config_path=config_path,
+            profile=profile,
+            force=force,
+            print_only=print_only,
+        )
+    except ValueError as exc:
+        print_error(str(exc))
+        return EXIT_USAGE
+    except FileExistsError as exc:
+        print_error(str(exc))
+        print("hint: rerun with --force to overwrite", file=sys.stderr)
+        return EXIT_USAGE
+
+    if result.rendered is not None:
+        print(result.rendered)
+        return EXIT_OK
+
+    print(f"wrote config: {config_path}")
+    print("next: springdocker benchmark run")
+    return EXIT_OK
+
+
+def _use_legacy_scripts(explicit: bool) -> bool:
+    if explicit:
+        return True
+    return os.environ.get("SPRINGDOCKER_LEGACY_SCRIPTS", "").lower() in {"1", "true", "yes", "on"}
+
+
+def cmd_dockerfile_generate(
+    project_root: Path,
+    build_tool: str | None,
+    output: str,
+    java_version: int,
+    must_have_modules_file: str | None,
+    extra_args: list[str],
+    use_legacy_scripts: bool,
+) -> int:
+    try:
+        info = inspect_project(project_root, build_tool)
+    except ValueError as exc:
+        print_error(str(exc))
+        return EXIT_USAGE
+
+    if _use_legacy_scripts(use_legacy_scripts):
+        script = project_root / "tools" / "dockerfile_wizard.py"
+        if not script.exists():
+            print_error(f"missing script: {script}")
+            return EXIT_USAGE
+
+        cmd = [
+            "python3",
+            str(script),
+            "--build-tool",
+            info.build_tool,
+            "--output",
+            output,
+        ]
+        cmd.extend(extra_args)
+        return run_checked(cmd, project_root)
+
+    try:
+        generated = dockerfile_service.generate_dockerfile(
+            project_root=project_root,
+            output_path=output,
+            build_tool=info.build_tool,
+            java_version=java_version,
+            must_have_modules_file=must_have_modules_file,
+        )
+    except ValueError as exc:
+        print_error(str(exc))
+        return EXIT_USAGE
+    for warning in generated.plugin_warnings:
+        print_warning(warning)
+    print(f"wrote dockerfile: {generated.path}")
+    return EXIT_OK
+
+
+def cmd_benchmark_generate(
+    project_root: Path,
+    build_tool: str | None,
+    java_version: int,
+    use_legacy_scripts: bool,
+) -> int:
+    try:
+        info = inspect_project(project_root, build_tool)
+    except ValueError as exc:
+        print_error(str(exc))
+        return EXIT_USAGE
+
+    if _use_legacy_scripts(use_legacy_scripts):
+        script = project_root / "benchmarks" / "setup_benchmark_folders.py"
+        if not script.exists():
+            print_error(f"missing script: {script}")
+            return EXIT_USAGE
+
+        return run_checked(
+            [
+                "python3",
+                str(script),
+                "--build-tool",
+                info.build_tool,
+                "--java-version",
+                str(java_version),
+            ],
+            project_root,
+        )
+
+    generate_benchmark_assets(project_root=project_root, build_tool=info.build_tool, java_version=java_version)
+    print("generated benchmark scenarios")
+    return EXIT_OK
+
+
+def cmd_benchmark_run(
+    project_root: Path,
+    build_tool: str | None,
+    profile: str,
+    extra_args: list[str],
+    cpuset_cpus: str | None,
+    memory_limit: str | None,
+    warmup_runs: int,
+    normalized_runtime: bool,
+    use_legacy_scripts: bool,
+    max_workers: int = 1,
+) -> int:
+    try:
+        info = inspect_project(project_root, build_tool)
+    except ValueError as exc:
+        print_error(str(exc))
+        return EXIT_USAGE
+
+    try:
+        benchmark_service.validate_reproducibility_with_legacy(
+            use_legacy_scripts=use_legacy_scripts,
+            cpuset_cpus=cpuset_cpus,
+            memory_limit=memory_limit,
+            warmup_runs=warmup_runs,
+            max_workers=max_workers,
+            normalized_runtime=normalized_runtime,
+        )
+    except ValueError as exc:
+        print_error(str(exc))
+        return EXIT_USAGE
+
+    if _use_legacy_scripts(use_legacy_scripts):
+        script = project_root / "benchmarks" / "common" / "run_all_benchmarks.py"
+        if not script.exists():
+            print_error(f"missing script: {script}")
+            return EXIT_USAGE
+
+        cmd = [
+            "python3",
+            str(script),
+            "--profile",
+            profile,
+            "--build-tool",
+            info.build_tool,
+        ]
+        cmd.extend(extra_args)
+        return run_checked(cmd, project_root)
+
+    return run_benchmarks(
+        project_root=project_root,
+        build_tool=info.build_tool,
+        profile=profile,
+        extra_args=extra_args,
+        cpuset_cpus=cpuset_cpus,
+        memory_limit=memory_limit,
+        warmup_runs=warmup_runs,
+        max_workers=max_workers,
+        normalized_runtime=normalized_runtime,
+    )
+
+
+def cmd_benchmark_analyze(
+    project_root: Path,
+    raw_csv: str,
+    output_format: str,
+    scenario: str | None,
+    variant: str | None,
+    output_path: str | None,
+    fail_on_success_rate_below: float | None,
+    baseline_path: str | None,
+    fail_on_regression_above: float | None,
+) -> int:
+    try:
+        outcome = benchmark_service.analyze_csv(
+            project_root=project_root,
+            raw_csv=raw_csv,
+            output_format=output_format,
+            scenario=scenario,
+            variant=variant,
+            output_path=output_path,
+            fail_on_success_rate_below=fail_on_success_rate_below,
+            baseline_path=baseline_path,
+            fail_on_regression_above=fail_on_regression_above,
+        )
+    except ValueError as exc:
+        print_error(str(exc))
+        return EXIT_USAGE
+
+    if outcome.rendered == "No rows matched the provided filters.":
+        print(outcome.rendered)
+        return EXIT_OK
+
+    if outcome.output_destination is not None:
+        destination = outcome.output_destination
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(outcome.rendered + "\n", encoding="utf-8")
+        print(f"wrote analysis: {destination}")
+    else:
+        print(outcome.rendered)
+
+    if outcome.success_rate_violations:
+        for violation in outcome.success_rate_violations:
+            print_error(violation)
+        return EXIT_FAILURE
+
+    if outcome.baseline_missing is not None:
+        print_warning(f"baseline report not found; skipping regression check: {outcome.baseline_missing}")
+        return EXIT_OK
+
+    if outcome.regression_violations:
+        rendered_violations = (
+            format_regression_json(list(outcome.regression_violations))
+            if output_format == "json"
+            else format_regression_table(list(outcome.regression_violations))
+        )
+        print(rendered_violations)
+        print_error(
+            f"regressions above {outcome.regression_threshold_pct:.1f}% detected against {outcome.baseline_path_used}"
+        )
+        return EXIT_FAILURE
+
+    return EXIT_OK

springdocker/compare.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Iterable
+
+from .analyze import VariantSummary
+
+
+@dataclass(frozen=True)
+class VariantDelta:
+    scenario: str
+    variant: str
+    baseline_variant: str
+    is_baseline: bool
+    build_delta_ms: float | None
+    build_delta_pct: float | None
+    startup_delta_ms: float | None
+    startup_delta_pct: float | None
+    image_delta_mb: float | None
+    image_delta_pct: float | None
+
+
+def _pct_delta(value: float | None, baseline: float | None) -> float | None:
+    if value is None or baseline is None or baseline == 0:
+        return None
+    return ((value - baseline) / baseline) * 100.0
+
+
+def _abs_delta(value: float | None, baseline: float | None) -> float | None:
+    if value is None or baseline is None:
+        return None
+    return value - baseline
+
+
+def compare_summaries(baseline_variant: str, summaries: list[VariantSummary]) -> list[VariantDelta]:
+    by_scenario: dict[str, list[VariantSummary]] = {}
+    for summary in summaries:
+        by_scenario.setdefault(summary.scenario, []).append(summary)
+
+    deltas: list[VariantDelta] = []
+    for scenario, items in sorted(by_scenario.items()):
+        baseline = next((item for item in items if item.variant == baseline_variant), None)
+        if baseline is None:
+            available = ", ".join(sorted(item.variant for item in items)) or "-"
+            raise ValueError(f"baseline variant '{baseline_variant}' not found for scenario '{scenario}'; available: {available}")
+
+        deltas.append(
+            VariantDelta(
+                scenario=scenario,
+                variant=baseline.variant,
+                baseline_variant=baseline_variant,
+                is_baseline=True,
+                build_delta_ms=0.0,
+                build_delta_pct=0.0,
+                startup_delta_ms=0.0,
+                startup_delta_pct=0.0,
+                image_delta_mb=0.0,
+                image_delta_pct=0.0,
+            )
+        )
+
+        for item in sorted(items, key=lambda summary: summary.variant):
+            if item.variant == baseline_variant:
+                continue
+            deltas.append(
+                VariantDelta(
+                    scenario=scenario,
+                    variant=item.variant,
+                    baseline_variant=baseline_variant,
+                    is_baseline=False,
+                    build_delta_ms=_abs_delta(item.build_avg_ms, baseline.build_avg_ms),
+                    build_delta_pct=_pct_delta(item.build_avg_ms, baseline.build_avg_ms),
+                    startup_delta_ms=_abs_delta(item.startup_avg_ms, baseline.startup_avg_ms),
+                    startup_delta_pct=_pct_delta(item.startup_avg_ms, baseline.startup_avg_ms),
+                    image_delta_mb=_abs_delta(item.image_mb_avg, baseline.image_mb_avg),
+                    image_delta_pct=_pct_delta(item.image_mb_avg, baseline.image_mb_avg),
+                )
+            )
+
+    return deltas
+
+
+def _render_delta(value: float | None, suffix: str = "") -> str:
+    if value is None:
+        return "-"
+    if suffix == "%":
+        return f"{value:+.1f}%"
+    if suffix == "mb":
+        return f"{value:+.2f}"
+    if suffix == "ms":
+        return f"{value:+.1f}"
+    return f"{value:+.1f}"
+
+
+def format_delta_table(deltas: Iterable[VariantDelta]) -> str:
+    lines = [
+        "| Scenario | Variant | Baseline | Build Δms | Build Δ% | Startup Δms | Startup Δ% | Image ΔMB | Image Δ% |",
+        "|---|---|---|---:|---:|---:|---:|---:|---:|",
+    ]
+    for delta in deltas:
+        lines.append(
+            "| "
+            + " | ".join(
+                [
+                    delta.scenario,
+                    delta.variant,
+                    delta.baseline_variant,
+                    _render_delta(delta.build_delta_ms, "ms"),
+                    _render_delta(delta.build_delta_pct, "%"),
+                    _render_delta(delta.startup_delta_ms, "ms"),
+                    _render_delta(delta.startup_delta_pct, "%"),
+                    _render_delta(delta.image_delta_mb, "mb"),
+                    _render_delta(delta.image_delta_pct, "%"),
+                ]
+            )
+            + " |"
+        )
+    return "\n".join(lines)
+
+
+def format_delta_json(deltas: Iterable[VariantDelta]) -> str:
+    payload = [
+        {
+            "scenario": delta.scenario,
+            "variant": delta.variant,
+            "baseline_variant": delta.baseline_variant,
+            "is_baseline": delta.is_baseline,
+            "build_delta_ms": delta.build_delta_ms,
+            "build_delta_pct": delta.build_delta_pct,
+            "startup_delta_ms": delta.startup_delta_ms,
+            "startup_delta_pct": delta.startup_delta_pct,
+            "image_delta_mb": delta.image_delta_mb,
+            "image_delta_pct": delta.image_delta_pct,
+        }
+        for delta in deltas
+    ]
+    return json.dumps(payload, indent=2, sort_keys=True)