springdocker 1.0.1__py3-none-any.whl

springdocker/regression.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .analyze import VariantSummary
+
+
+@dataclass(frozen=True)
+class RegressionViolation:
+    scenario: str
+    variant: str
+    metric: str
+    baseline: float | None
+    current: float | None
+    delta_pct: float | None
+
+
+METRICS = (
+    ("startup_avg_ms", "startup_avg_ms"),
+    ("startup_p95_ms", "startup_p95_ms"),
+    ("image_mb_avg", "image_mb_avg"),
+)
+
+
+def _metric_value(summary: VariantSummary, field: str) -> float | None:
+    return getattr(summary, field)
+
+
+def _pct_change(current: float, baseline: float) -> float:
+    return ((current - baseline) / baseline) * 100.0
+
+
+def load_summaries(path: Path) -> list[VariantSummary]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, list):
+        raise ValueError("baseline report must be a JSON list")
+
+    summaries: list[VariantSummary] = []
+    for item in payload:
+        if not isinstance(item, dict):
+            raise ValueError("baseline report must contain JSON objects")
+        summaries.append(
+            VariantSummary(
+                scenario=str(item.get("scenario", "")),
+                variant=str(item.get("variant", "")),
+                runs=int(item.get("runs", 0)),
+                build_avg_ms=item.get("build_avg_ms"),
+                build_stddev_ms=item.get("build_stddev_ms"),
+                build_ci95_low_ms=item.get("build_ci95_low_ms"),
+                build_ci95_high_ms=item.get("build_ci95_high_ms"),
+                startup_avg_ms=item.get("startup_avg_ms"),
+                startup_p95_ms=item.get("startup_p95_ms"),
+                startup_p99_ms=item.get("startup_p99_ms"),
+                startup_stddev_ms=item.get("startup_stddev_ms"),
+                startup_ci95_low_ms=item.get("startup_ci95_low_ms"),
+                startup_ci95_high_ms=item.get("startup_ci95_high_ms"),
+                gc_pause_ms_avg=item.get("gc_pause_ms_avg"),
+                alloc_mb_avg=item.get("alloc_mb_avg"),
+                startup_phase_boot_ms_avg=item.get("startup_phase_boot_ms_avg"),
+                startup_phase_context_ms_avg=item.get("startup_phase_context_ms_avg"),
+                startup_phase_web_server_ms_avg=item.get("startup_phase_web_server_ms_avg"),
+                startup_phase_total_ms_avg=item.get("startup_phase_total_ms_avg"),
+                image_mb_avg=item.get("image_mb_avg"),
+                success_rate_pct=float(item.get("success_rate_pct", 0.0)),
+                rss_mb_avg=item.get("rss_mb_avg"),
+                cpu_pct_avg=item.get("cpu_pct_avg"),
+                host=item.get("host"),
+                docker_version=item.get("docker_version"),
+                run_profile=item.get("run_profile"),
+            )
+        )
+    return summaries
+
+
+def detect_regressions(
+    baseline: list[VariantSummary], current: list[VariantSummary], threshold_pct: float
+) -> list[RegressionViolation]:
+    baseline_map = {(summary.scenario, summary.variant): summary for summary in baseline}
+    current_map = {(summary.scenario, summary.variant): summary for summary in current}
+    violations: list[RegressionViolation] = []
+
+    for key, baseline_summary in sorted(baseline_map.items()):
+        current_summary = current_map.get(key)
+        if current_summary is None:
+            continue
+        for metric_name, field in METRICS:
+            baseline_value = _metric_value(baseline_summary, field)
+            current_value = _metric_value(current_summary, field)
+            if baseline_value is None and current_value is None:
+                continue
+            if baseline_value is None and current_value is not None:
+                continue
+            if baseline_value is not None and current_value is None:
+                violations.append(
+                    RegressionViolation(
+                        scenario=baseline_summary.scenario,
+                        variant=baseline_summary.variant,
+                        metric=metric_name,
+                        baseline=baseline_value,
+                        current=None,
+                        delta_pct=None,
+                    )
+                )
+                continue
+            assert baseline_value is not None
+            assert current_value is not None
+            delta_pct = _pct_change(current_value, baseline_value)
+            if delta_pct > threshold_pct:
+                violations.append(
+                    RegressionViolation(
+                        scenario=baseline_summary.scenario,
+                        variant=baseline_summary.variant,
+                        metric=metric_name,
+                        baseline=baseline_value,
+                        current=current_value,
+                        delta_pct=delta_pct,
+                    )
+                )
+    return violations
+
+
+def format_regression_table(violations: list[RegressionViolation]) -> str:
+    lines = [
+        "| Scenario | Variant | Metric | Baseline | Current | Δ% |",
+        "|---|---|---|---:|---:|---:|",
+    ]
+    for violation in violations:
+        baseline = "-" if violation.baseline is None else f"{violation.baseline:.2f}"
+        current = "-" if violation.current is None else f"{violation.current:.2f}"
+        delta = "-" if violation.delta_pct is None else f"{violation.delta_pct:+.1f}%"
+        lines.append(
+            f"| {violation.scenario} | {violation.variant} | {violation.metric} | {baseline} | {current} | {delta} |"
+        )
+    return "\n".join(lines)
+
+
+def format_regression_json(violations: list[RegressionViolation]) -> str:
+    payload = [
+        {
+            "scenario": violation.scenario,
+            "variant": violation.variant,
+            "metric": violation.metric,
+            "baseline": violation.baseline,
+            "current": violation.current,
+            "delta_pct": violation.delta_pct,
+        }
+        for violation in violations
+    ]
+    return json.dumps(payload, indent=2, sort_keys=True)

springdocker/services/__init__.py

@@ -0,0 +1,2 @@
+from __future__ import annotations
+

springdocker/services/benchmark_service.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..analyze import format_json, format_table, summarize_csv
+from ..compare import compare_summaries, format_delta_json, format_delta_table
+from ..regression import RegressionViolation, detect_regressions, load_summaries
+
+
+def resolve_path(project_root: Path, raw_path: str) -> Path:
+    path = Path(raw_path)
+    if not path.is_absolute():
+        path = project_root / path
+    return path
+
+
+def validate_reproducibility_with_legacy(
+    use_legacy_scripts: bool,
+    cpuset_cpus: str | None,
+    memory_limit: str | None,
+    warmup_runs: int,
+    max_workers: int,
+    normalized_runtime: bool,
+) -> None:
+    if use_legacy_scripts and any([cpuset_cpus, memory_limit, warmup_runs > 0, max_workers > 1, normalized_runtime]):
+        raise ValueError("benchmark reproducibility/concurrency controls require the internal benchmark runner")
+
+
+def render_comparison(
+    project_root: Path,
+    raw_csv: str,
+    baseline_variant: str,
+    output_format: str,
+    scenario: str | None,
+) -> str:
+    csv_path = resolve_path(project_root, raw_csv)
+    if not csv_path.exists():
+        raise ValueError(f"missing CSV file: {csv_path}")
+    summaries = summarize_csv(csv_path, scenario=scenario)
+    deltas = compare_summaries(baseline_variant, summaries)
+    return format_delta_json(deltas) if output_format == "json" else format_delta_table(deltas)
+
+
+@dataclass(frozen=True)
+class AnalyzeOutcome:
+    rendered: str
+    output_destination: Path | None
+    success_rate_violations: tuple[str, ...]
+    regression_violations: tuple[RegressionViolation, ...]
+    baseline_missing: Path | None
+    baseline_path_used: Path | None
+    regression_threshold_pct: float
+
+
+def analyze_csv(
+    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,
+) -> AnalyzeOutcome:
+    csv_path = resolve_path(project_root, raw_csv)
+    if not csv_path.exists():
+        raise ValueError(f"missing CSV file: {csv_path}")
+    if fail_on_success_rate_below is not None and not 0.0 <= fail_on_success_rate_below <= 100.0:
+        raise ValueError("--fail-on-success-rate-below must be between 0 and 100")
+
+    summaries = summarize_csv(csv_path, scenario=scenario, variant=variant)
+    if not summaries:
+        return AnalyzeOutcome(
+            rendered="No rows matched the provided filters.",
+            output_destination=None,
+            success_rate_violations=(),
+            regression_violations=(),
+            baseline_missing=None,
+            baseline_path_used=None,
+            regression_threshold_pct=fail_on_regression_above or 20.0,
+        )
+
+    rendered = format_json(summaries) if output_format == "json" else format_table(summaries)
+    destination: Path | None = None
+    if output_path:
+        destination = resolve_path(project_root, output_path)
+
+    violations: list[str] = []
+    if fail_on_success_rate_below is not None:
+        violations = [
+            f"success_rate below threshold for {summary.scenario}/{summary.variant}: "
+            f"{summary.success_rate_pct:.1f}% < {fail_on_success_rate_below:.1f}%"
+            for summary in summaries
+            if summary.success_rate_pct < fail_on_success_rate_below
+        ]
+
+    baseline_missing: Path | None = None
+    baseline_path_used: Path | None = None
+    regression_violations: list[RegressionViolation] = []
+    threshold = fail_on_regression_above or 20.0
+    if baseline_path is not None:
+        baseline_file = resolve_path(project_root, baseline_path)
+        baseline_path_used = baseline_file
+        if not baseline_file.exists():
+            baseline_missing = baseline_file
+        else:
+            baseline_summaries = load_summaries(baseline_file)
+            regression_violations = detect_regressions(
+                baseline=baseline_summaries,
+                current=summaries,
+                threshold_pct=threshold,
+            )
+
+    return AnalyzeOutcome(
+        rendered=rendered,
+        output_destination=destination,
+        success_rate_violations=tuple(violations),
+        regression_violations=tuple(regression_violations),
+        baseline_missing=baseline_missing,
+        baseline_path_used=baseline_path_used,
+        regression_threshold_pct=threshold,
+    )

springdocker/services/dockerfile_service.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..dockerfile import DockerfileOptions, build_dockerfile, explain_dockerfile_text
+from ..plugins import apply_dockerfile_mutators
+
+
+def resolve_path(project_root: Path, raw_path: str) -> Path:
+    path = Path(raw_path)
+    if not path.is_absolute():
+        path = project_root / path
+    return path
+
+
+def parse_must_have_modules(project_root: Path, must_have_modules_file: str | None) -> tuple[str, ...]:
+    if not must_have_modules_file:
+        return ()
+    modules_path = resolve_path(project_root, must_have_modules_file)
+    if not modules_path.exists():
+        raise ValueError(f"missing must-have modules file: {modules_path}")
+    parsed: list[str] = []
+    seen: set[str] = set()
+    for line in modules_path.read_text(encoding="utf-8").splitlines():
+        entry = line.split("#", 1)[0].strip()
+        if not entry:
+            continue
+        for token in [part.strip() for part in entry.split(",")]:
+            if not token:
+                continue
+            if not re.fullmatch(r"[A-Za-z0-9._-]+", token):
+                raise ValueError(f"invalid module name in {modules_path}: {token}")
+            if token not in seen:
+                parsed.append(token)
+                seen.add(token)
+    return tuple(parsed)
+
+
+def generate_dockerfile(
+    project_root: Path,
+    output_path: str,
+    build_tool: str,
+    java_version: int,
+    must_have_modules_file: str | None,
+) -> GeneratedDockerfile:
+    must_have_modules = parse_must_have_modules(project_root, must_have_modules_file)
+    options = DockerfileOptions(
+        build_tool=build_tool,
+        java_version=java_version,
+        must_have_modules=must_have_modules,
+    )
+    generated = apply_dockerfile_mutators(
+        dockerfile_text=build_dockerfile(options),
+        options=options,
+    )
+    destination = resolve_path(project_root, output_path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(generated.dockerfile_text, encoding="utf-8")
+    return GeneratedDockerfile(path=destination, plugin_warnings=generated.warnings)
+
+
+@dataclass(frozen=True)
+class GeneratedDockerfile:
+    path: Path
+    plugin_warnings: tuple[str, ...]
+
+
+def explain_dockerfile(project_root: Path, dockerfile_path: str) -> dict[str, object]:
+    path = resolve_path(project_root, dockerfile_path)
+    if not path.exists():
+        raise ValueError(f"missing Dockerfile: {path}")
+    payload = dict(explain_dockerfile_text(path.read_text(encoding="utf-8")))
+    payload["path"] = str(path)
+    return payload

springdocker/services/project_service.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..config import render_default_config, write_default_config
+from ..project_detect import inspect_project, inspect_project_details
+
+
+def load_project_info(project_root: Path, build_tool: str | None):
+    return inspect_project(project_root, build_tool)
+
+
+def load_project_details(project_root: Path, build_tool: str | None):
+    return inspect_project_details(project_root, build_tool)
+
+
+@dataclass(frozen=True)
+class InitConfigResult:
+    rendered: str | None
+    written_path: Path | None
+
+
+def prepare_default_config(
+    project_root: Path,
+    build_tool: str | None,
+    config_path: Path,
+    profile: str,
+    force: bool,
+    print_only: bool,
+) -> InitConfigResult:
+    info = inspect_project(project_root, build_tool)
+    if print_only:
+        return InitConfigResult(rendered=render_default_config(build_tool=info.build_tool, profile=profile), written_path=None)
+    write_default_config(path=config_path, build_tool=info.build_tool, profile=profile, force=force)
+    return InitConfigResult(rendered=None, written_path=config_path)
+

springdocker-1.0.1.dist-info/METADATA

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: springdocker
+Version: 1.0.1
+Summary: CLI for Spring Boot Dockerfile and benchmark workflows (Maven/Gradle).
+Author: springdocker contributors
+License: UNLICENSED
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+
+# springdocker CLI
+
+CLI for Spring Boot Dockerfile and benchmark workflows across Maven and Gradle projects.
+
+## Install
+
+### Local editable
+
+```bash
+python3 -m pip install -e .
+```
+
+### pipx
+
+```bash
+pipx install springdocker
+springdocker --help
+```
+
+Upgrade:
+
+```bash
+pipx upgrade springdocker
+```
+
+### uv
+
+```bash
+uv tool install springdocker
+uv tool upgrade springdocker
+```
+
+## Quick usage
+
+```bash
+springdocker init --project-root samples/java-spring-docker --build-tool maven --profile quick
+springdocker doctor --project-root samples/java-spring-docker
+springdocker inspect --project-root samples/java-spring-docker --format json
+springdocker explain --project-root samples/java-spring-docker Dockerfile.generated --format json
+springdocker benchmark compare --project-root samples/java-spring-docker benchmarks/03-custom-jre-jlink/results/raw.csv --baseline-variant with-jlink-runtime --format json
+springdocker dockerfile generate --project-root samples/java-spring-docker --output Dockerfile.generated
+springdocker benchmark generate --project-root samples/java-spring-docker --java-version 25
+springdocker benchmark run --project-root samples/java-spring-docker --profile quick --runner-arg --skip-native
+springdocker benchmark analyze --project-root samples/java-spring-docker benchmarks/04-jep483-aot-cache/results/raw.csv --format table
+springdocker benchmark analyze --project-root samples/java-spring-docker benchmarks/04-jep483-aot-cache/results/raw.csv --format json --output benchmarks/04-jep483-aot-cache/results/summary.json
+springdocker benchmark analyze --project-root samples/java-spring-docker benchmarks/04-jep483-aot-cache/results/raw.csv --fail-on-success-rate-below 95
+springdocker benchmark analyze --project-root samples/java-spring-docker benchmarks/04-jep483-aot-cache/results/raw.csv --baseline benchmarks/04-jep483-aot-cache/results/baseline.json --fail-on-regression-above 20
+```
+
+## Config file (`.springdocker.toml`)
+
+All command resolvers use precedence:
+
+1. CLI flags
+2. `.springdocker.toml`
+3. defaults
+
+Example:
+
+```toml
+[project]
+build_tool = "maven"
+
+[doctor]
+build_tool = "maven"
+
+[dockerfile]
+output = "Dockerfile.generated"
+java_version = 25
+must_have_modules_file = "must-have.txt"
+legacy_scripts = false
+wizard_args = []
+
+[benchmark.generate]
+java_version = 25
+legacy_scripts = false
+
+[benchmark.run]
+profile = "quick"
+runner_args = ["--skip-native"]
+cpuset_cpus = "0-1"
+memory_limit = "2g"
+warmup_runs = 1
+max_workers = 1
+normalized_runtime = true
+legacy_scripts = false
+```
+
+When `dockerfile.must_have_modules_file` is set, springdocker reads modules from that file
+(`must-have.txt` style, one module per line, `#` comments allowed) and injects them into
+the jlink module list for reflection/dynamic-loading edge cases.
+
+Create template config:
+
+```bash
+springdocker init --project-root samples/java-spring-docker --build-tool gradle
+springdocker init --project-root samples/java-spring-docker --build-tool gradle --profile full --print
+```
+
+## Legacy compatibility mode
+
+Main command paths are internal and do not require project script files.
+
+To force script wrappers for compatibility:
+
+```bash
+springdocker dockerfile generate --use-legacy-scripts ...
+springdocker benchmark generate --use-legacy-scripts ...
+springdocker benchmark run --use-legacy-scripts ...
+```
+
+or set:
+
+```bash
+export SPRINGDOCKER_LEGACY_SCRIPTS=1
+```
+
+## Inspect command
+
+`springdocker inspect` prints static metadata about the target project:
+
+- detected build tool
+- Spring Boot version when present
+- Java version when present
+- direct dependency coordinates
+- generated Dockerfile artifacts in the project root
+- basic runtime compatibility guidance
+
+Use `--format json` for machine-readable output.
+
+## Explain command
+
+`springdocker explain` reads a springdocker-generated Dockerfile and describes the optimizations it contains:
+
+- multi-stage layout
+- BuildKit cache usage
+- jlink runtime stage
+- non-root runtime
+- tuned JVM flags
+- curated must-have modules
+
+Use `--format json` when you want stable structured output.
+
+## Security hardening
+
+See `docs/security-hardening.md` for the runtime hardening defaults and recommended `docker run` flags.
+
+## Binary distribution
+
+See `docs/distribution.md` for packaging notes and sample Homebrew, Scoop, standalone binary, and Docker runtime artifacts.
+
+## Multi-architecture builds
+
+See `docs/multiarch.md` for the Buildx-friendly Dockerfile output and example multi-arch build command.
+
+## Compare command
+
+`springdocker benchmark compare` compares each variant against a required baseline variant and reports deltas.
+
+- `--baseline-variant` selects the variant to compare against.
+- `--scenario` narrows the CSV to one scenario.
+- `--format json` produces machine-readable deltas.
+
+## Benchmark run reproducibility
+
+`springdocker benchmark run` supports deterministic benchmark controls for local or CI runs:
+
+- `--cpuset-cpus` pins benchmark containers to specific CPUs.
+- `--memory` caps container memory.
+- `--warmup-runs` executes discarded warmup probes before recording results.
+- `--max-workers` runs standard scenarios concurrently with controlled worker count.
+- `--normalized-runtime` applies read-only, no-new-privileges, and tmpfs isolation.
+
+These settings can also come from `[benchmark.run]` in `.springdocker.toml`.

springdocker-1.0.1.dist-info/RECORD

@@ -0,0 +1,23 @@
+springdocker/__init__.py,sha256=33B3aRpZXrsoZ7GLyStF7MzVgIHt47MlR_EhxEjQZ9E,272
+springdocker/analyze.py,sha256=z_j29739dZF_R4T7jwakTWgOMfuelQEwkrkVC0jDDQw,11992
+springdocker/cli.py,sha256=3uVF0NByriJLPwvVVrxD-e9XsZmOYT0sa7EhFzD3RcE,12315
+springdocker/commands.py,sha256=QBvyjPAt7y7iAVA226dBNxgJNZh9-WWvRPMkZ4JDcPA,12397
+springdocker/compare.py,sha256=dK-h7hKEJoI8GlKmd8AZAV5--5SlZ7_C_kW0ighXooY,4931
+springdocker/config.py,sha256=t9n5a8FUMETHO0r_udeYHUvNODAlxu1xXJN4l6I34cA,14660
+springdocker/dockerfile.py,sha256=9Ov5vigs31AFe8LZOT_eyXRw1JSIVt6mwR2CDoqS49M,12504
+springdocker/errors.py,sha256=nwBquBupwIB9VTWeyrtDlKXVXqOmvpDe6-oEUsFPfo8,275
+springdocker/plugins.py,sha256=7uGnMRl4Dah_isi8SyLfELlUmDh4HWfNG6J5ky77mFg,2857
+springdocker/project_detect.py,sha256=cih0zh9ZVZgtzfcXNeJZ7EwA7GDSkCZbI7EqSI1nr-8,9189
+springdocker/regression.py,sha256=gOaPs0Fabs_-RGlp7xECBpXYL-jGNoSLKLCftK2t-Oc,6003
+springdocker/benchmarks/__init__.py,sha256=WiQrmreDaPt7F3PhIkZQKaeYhegrolZEaL589su99sI,51
+springdocker/benchmarks/generate.py,sha256=pHw5QrusKBqncgSdU1mCIoiaWS5KpiXKqdkZVW6oQmA,4069
+springdocker/benchmarks/runner.py,sha256=AjEErI6ysN3aDXAEfM7wEXdP8gPp-CupVvCq_FboxTU,12210
+springdocker/services/__init__.py,sha256=PHh4jqD7i0aL8W8hXThczKcT4xsNZiXanBxOH5IOW5I,36
+springdocker/services/benchmark_service.py,sha256=Skj9x5w6Ix6rGVuTJWmeWPhx7qtvzI3SdYW5h2ElMsI,4480
+springdocker/services/dockerfile_service.py,sha256=S1z1EkKePTqA96zaTRfAb7z59Z0BkrQzHah3MASPPzU,2630
+springdocker/services/project_service.py,sha256=A0iUVyNvcHRDdq2khSvLk_MU7CSHuGdn0PRfiFKFUFA,1147
+springdocker-1.0.1.dist-info/METADATA,sha256=EK3D1tOBmHU5eQijJRqa8cO8Az1WWM-EwN12YWhMUNI,5818
+springdocker-1.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+springdocker-1.0.1.dist-info/entry_points.txt,sha256=KthNZ57ZMW6pFk6BMXuKpJYp6lOjHAebaDv5nSkvIOU,55
+springdocker-1.0.1.dist-info/top_level.txt,sha256=7HhuHYUI1oB5IcfzRfIoX4D6jld22B-NWtvDPcOnneU,13
+springdocker-1.0.1.dist-info/RECORD,,

springdocker-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

springdocker-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+springdocker = springdocker.cli:main

springdocker-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+springdocker