Xcode Build Orchestrator

#!/usr/bin/env python3

import argparse
import json
import os
import platform
import re
import shutil
import statistics
import subprocess
import sys
import tempfile
import time
from datetime import datetime, timezone
from pathlib import Path
from typing import Dict, List, Optional


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Benchmark Xcode clean and incremental builds.")
    group = parser.add_mutually_exclusive_group(required=True)
    group.add_argument("--workspace", help="Path to the .xcworkspace file")
    group.add_argument("--project", help="Path to the .xcodeproj file")
    parser.add_argument("--scheme", required=True, help="Scheme to build")
    parser.add_argument("--configuration", default="Debug", help="Build configuration")
    parser.add_argument("--destination", help="xcodebuild destination string")
    parser.add_argument("--derived-data-path", help="DerivedData path override")
    parser.add_argument("--output-dir", default=".build-benchmark", help="Output directory for artifacts")
    parser.add_argument("--repeats", type=int, default=3, help="Measured runs per build type")
    parser.add_argument("--skip-warmup", action="store_true", help="Skip the validation build")
    parser.add_argument(
        "--touch-file",
        help="Path to a source file to touch before each incremental build. "
        "When provided, measures a real edit-rebuild loop instead of a zero-change build.",
    )
    parser.add_argument(
        "--no-cached-clean",
        action="store_true",
        help="Skip cached clean builds even when COMPILATION_CACHE_ENABLE_CACHING is detected.",
    )
    parser.add_argument(
        "--extra-arg",
        action="append",
        default=[],
        help="Additional xcodebuild argument to append. Can be passed multiple times.",
    )
    return parser.parse_args()


def command_base(args: argparse.Namespace) -> List[str]:
    command = ["xcodebuild"]
    if args.workspace:
        command.extend(["-workspace", args.workspace])
    if args.project:
        command.extend(["-project", args.project])
    command.extend(["-scheme", args.scheme, "-configuration", args.configuration])
    if args.destination:
        command.extend(["-destination", args.destination])
    if args.derived_data_path:
        command.extend(["-derivedDataPath", args.derived_data_path])
    command.extend(args.extra_arg)
    return command


def shell_join(parts: List[str]) -> str:
    return " ".join(subprocess.list2cmdline([part]) for part in parts)


_TASK_COUNT_RE = re.compile(r"^(.+?)\s*\((\d+)\s+tasks?\)$")


def _extract_task_count(name: str) -> tuple[str, Optional[int]]:
    """Split 'Category (N tasks)' into ('Category', N)."""
    match = _TASK_COUNT_RE.match(name)
    if match:
        return match.group(1).strip(), int(match.group(2))
    return name, None


def parse_timing_summary(output: str) -> List[Dict]:
    categories: Dict[str, float] = {}
    task_counts: Dict[str, Optional[int]] = {}
    for raw_line in output.splitlines():
        line = raw_line.strip()
        if not line:
            continue
        for suffix in (" seconds", " second", " sec"):
            if not line.endswith(suffix):
                continue
            trimmed = line[: -len(suffix)]
            if "|" in trimmed:
                name_part, _, seconds_text = trimmed.rpartition("|")
            else:
                name_part, _, seconds_text = trimmed.rpartition(" ")
            try:
                seconds = float(seconds_text.strip())
            except ValueError:
                continue
            cleaned_name = name_part.replace("  ", " ").strip(" -:")
            if len(cleaned_name) < 3:
                continue
            base_name, count = _extract_task_count(cleaned_name)
            categories[base_name] = categories.get(base_name, 0.0) + seconds
            if count is not None:
                task_counts[base_name] = (task_counts.get(base_name) or 0) + count
            break
    result: List[Dict] = []
    for name, seconds in sorted(categories.items(), key=lambda item: item[1], reverse=True):
        entry: Dict = {"name": name, "seconds": round(seconds, 3)}
        if name in task_counts:
            entry["task_count"] = task_counts[name]
        result.append(entry)
    return result


def run_command(command: List[str]) -> subprocess.CompletedProcess:
    return subprocess.run(command, capture_output=True, text=True)


def stats_for(runs: List[Dict[str, object]]) -> Dict[str, float]:
    durations = [run["duration_seconds"] for run in runs if run.get("success")]
    if not durations:
        return {
            "count": 0,
            "min_seconds": 0.0,
            "max_seconds": 0.0,
            "median_seconds": 0.0,
            "average_seconds": 0.0,
        }
    return {
        "count": len(durations),
        "min_seconds": round(min(durations), 3),
        "max_seconds": round(max(durations), 3),
        "median_seconds": round(statistics.median(durations), 3),
        "average_seconds": round(statistics.fmean(durations), 3),
    }


def xcode_version() -> str:
    result = run_command(["xcodebuild", "-version"])
    return result.stdout.strip() if result.returncode == 0 else "unknown"


def detect_compilation_caching(base_command: List[str]) -> bool:
    """Check whether COMPILATION_CACHE_ENABLE_CACHING is enabled in the resolved build settings."""
    result = run_command([*base_command, "-showBuildSettings"])
    if result.returncode != 0:
        return False
    for line in result.stdout.splitlines():
        stripped = line.strip()
        if stripped.startswith("COMPILATION_CACHE_ENABLE_CACHING") and "=" in stripped:
            value = stripped.split("=", 1)[1].strip()
            return value == "YES"
    return False


def measure_build(
    base_command: List[str],
    artifact_stem: str,
    output_dir: Path,
    build_type: str,
    run_index: int,
) -> Dict[str, object]:
    build_command = [*base_command, "build", "-showBuildTimingSummary"]
    started = time.perf_counter()
    result = run_command(build_command)
    elapsed = round(time.perf_counter() - started, 3)
    log_path = output_dir / f"{artifact_stem}-{build_type}-{run_index}.log"
    log_path.write_text(result.stdout + result.stderr)
    return {
        "id": f"{build_type}-{run_index}",
        "build_type": build_type,
        "duration_seconds": elapsed,
        "success": result.returncode == 0,
        "exit_code": result.returncode,
        "command": shell_join(build_command),
        "raw_log_path": str(log_path),
        "timing_summary_categories": parse_timing_summary(result.stdout + result.stderr),
    }


def main() -> int:
    args = parse_args()
    output_dir = Path(args.output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)

    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    artifact_stem = f"{timestamp}-{args.scheme.replace(' ', '-').lower()}"
    base_command = command_base(args)

    if not args.skip_warmup:
        warmup = run_command([*base_command, "build"])
        if warmup.returncode != 0:
          sys.stderr.write(warmup.stdout + warmup.stderr)
          return warmup.returncode
        warmup_clean = run_command([*base_command, "clean"])
        if warmup_clean.returncode != 0:
            sys.stderr.write(warmup_clean.stdout + warmup_clean.stderr)
            return warmup_clean.returncode
        warmup_rebuild = run_command([*base_command, "build"])
        if warmup_rebuild.returncode != 0:
            sys.stderr.write(warmup_rebuild.stdout + warmup_rebuild.stderr)
            return warmup_rebuild.returncode

    runs: Dict[str, list] = {"clean": [], "incremental": []}

    for index in range(1, args.repeats + 1):
        clean_result = run_command([*base_command, "clean"])
        clean_log_path = output_dir / f"{artifact_stem}-clean-prep-{index}.log"
        clean_log_path.write_text(clean_result.stdout + clean_result.stderr)
        if clean_result.returncode != 0:
            sys.stderr.write(clean_result.stdout + clean_result.stderr)
            return clean_result.returncode
        runs["clean"].append(measure_build(base_command, artifact_stem, output_dir, "clean", index))

    # --- Cached clean builds ---------------------------------------------------
    # When COMPILATION_CACHE_ENABLE_CACHING is enabled, the compilation cache lives outside
    # DerivedData and survives product deletion.  We measure "cached clean"
    # builds by pointing DerivedData at a temp directory, warming the cache with
    # one build, then deleting the DerivedData directory (but not the cache)
    # before each measured rebuild.  This captures the realistic scenario:
    # branch switching, pulling changes, or Clean Build Folder.
    should_cached_clean = not args.no_cached_clean and detect_compilation_caching(base_command)
    if should_cached_clean:
        dd_path = Path(args.derived_data_path) if args.derived_data_path else Path(
            tempfile.mkdtemp(prefix="xcode-bench-dd-")
        )
        cached_cmd = list(base_command)
        if not args.derived_data_path:
            cached_cmd.extend(["-derivedDataPath", str(dd_path)])

        cache_warmup = run_command([*cached_cmd, "build"])
        if cache_warmup.returncode != 0:
            sys.stderr.write("Warning: cached clean warmup build failed, skipping cached clean benchmarks.\n")
            sys.stderr.write(cache_warmup.stdout + cache_warmup.stderr)
            should_cached_clean = False

    if should_cached_clean:
        runs["cached_clean"] = []
        for index in range(1, args.repeats + 1):
            shutil.rmtree(dd_path, ignore_errors=True)
            runs["cached_clean"].append(
                measure_build(cached_cmd, artifact_stem, output_dir, "cached-clean", index)
            )
        shutil.rmtree(dd_path, ignore_errors=True)

    # --- Incremental / zero-change builds --------------------------------------
    incremental_label = "incremental"
    if args.touch_file:
        touch_path = Path(args.touch_file)
        if not touch_path.exists():
            sys.stderr.write(f"--touch-file path does not exist: {touch_path}\n")
            return 1
        incremental_label = "incremental"
    else:
        incremental_label = "zero-change"

    for index in range(1, args.repeats + 1):
        if args.touch_file:
            touch_path.touch()
        runs["incremental"].append(
            measure_build(base_command, artifact_stem, output_dir, incremental_label, index)
        )

    summary: Dict[str, object] = {
        "clean": stats_for(runs["clean"]),
        "incremental": stats_for(runs["incremental"]),
    }
    if "cached_clean" in runs:
        summary["cached_clean"] = stats_for(runs["cached_clean"])

    artifact = {
        "schema_version": "1.2.0" if "cached_clean" in runs else "1.1.0",
        "created_at": datetime.now(timezone.utc).isoformat(),
        "build": {
            "entrypoint": "workspace" if args.workspace else "project",
            "path": args.workspace or args.project,
            "scheme": args.scheme,
            "configuration": args.configuration,
            "destination": args.destination or "",
            "derived_data_path": args.derived_data_path or "",
            "command": shell_join(base_command),
        },
        "environment": {
            "host": platform.node(),
            "macos_version": platform.platform(),
            "xcode_version": xcode_version(),
            "cwd": os.getcwd(),
        },
        "runs": runs,
        "summary": summary,
        "notes": [f"touch-file: {args.touch_file}"] if args.touch_file else [],
    }

    artifact_path = output_dir / f"{artifact_stem}.json"
    artifact_path.write_text(json.dumps(artifact, indent=2) + "\n")

    print(f"Saved benchmark artifact: {artifact_path}")
    print(f"Clean median: {artifact['summary']['clean']['median_seconds']}s")
    if "cached_clean" in artifact["summary"]:
        print(f"Cached clean median: {artifact['summary']['cached_clean']['median_seconds']}s")
    inc_label = "Incremental" if args.touch_file else "Zero-change"
    print(f"{inc_label} median: {artifact['summary']['incremental']['median_seconds']}s")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3

"""Run a single Xcode build with -Xfrontend diagnostics to find slow type-checking."""

import argparse
import json
import re
import subprocess
import sys
import time
from datetime import datetime, timezone
from pathlib import Path
from typing import Dict, List, Optional

_TYPECHECK_RE = re.compile(
    r"^(?P<file>.+?):(?P<line>\d+):(?P<col>\d+): warning: "
    r"(?P<kind>instance method|global function|getter|type-check|expression) "
    r"'?(?P<name>[^']*?)'?\s+took\s+(?P<ms>\d+)ms\s+to\s+type-check"
)

_EXPRESSION_RE = re.compile(
    r"^(?P<file>.+?):(?P<line>\d+):(?P<col>\d+): warning: "
    r"expression took\s+(?P<ms>\d+)ms\s+to\s+type-check"
)

_FILE_TIME_RE = re.compile(
    r"^\s*(?P<seconds>\d+(?:\.\d+)?)\s+seconds\s+.*\s+compiling\s+(?P<file>\S+)"
)


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Run an Xcode build with -Xfrontend type-checking diagnostics."
    )
    group = parser.add_mutually_exclusive_group(required=True)
    group.add_argument("--workspace", help="Path to the .xcworkspace file")
    group.add_argument("--project", help="Path to the .xcodeproj file")
    parser.add_argument("--scheme", required=True, help="Scheme to build")
    parser.add_argument("--configuration", default="Debug", help="Build configuration")
    parser.add_argument("--destination", help="xcodebuild destination string")
    parser.add_argument("--derived-data-path", help="DerivedData path override")
    parser.add_argument("--output-dir", default=".build-benchmark", help="Output directory")
    parser.add_argument(
        "--threshold",
        type=int,
        default=100,
        help="Millisecond threshold for -warn-long-function-bodies and "
        "-warn-long-expression-type-checking (default: 100)",
    )
    parser.add_argument("--skip-clean", action="store_true", help="Skip clean before build")
    parser.add_argument(
        "--per-file-timing",
        action="store_true",
        help="Add -Xfrontend -debug-time-compilation to report per-file compile times.",
    )
    parser.add_argument(
        "--stats-output",
        action="store_true",
        help="Add -Xfrontend -stats-output-dir to collect detailed compiler statistics.",
    )
    parser.add_argument(
        "--extra-arg",
        action="append",
        default=[],
        help="Additional xcodebuild argument. Can be passed multiple times.",
    )
    return parser.parse_args()


def command_base(args: argparse.Namespace) -> List[str]:
    command = ["xcodebuild"]
    if args.workspace:
        command.extend(["-workspace", args.workspace])
    if args.project:
        command.extend(["-project", args.project])
    command.extend(["-scheme", args.scheme, "-configuration", args.configuration])
    if args.destination:
        command.extend(["-destination", args.destination])
    if args.derived_data_path:
        command.extend(["-derivedDataPath", args.derived_data_path])
    command.extend(args.extra_arg)
    return command


def parse_diagnostics(output: str) -> List[Dict]:
    """Extract type-checking warnings from xcodebuild output."""
    warnings: List[Dict] = []
    seen = set()
    for raw_line in output.splitlines():
        line = raw_line.strip()
        match = _TYPECHECK_RE.match(line)
        if match:
            key = (match.group("file"), match.group("line"), match.group("col"), "function-body")
            if key in seen:
                continue
            seen.add(key)
            warnings.append(
                {
                    "file": match.group("file"),
                    "line": int(match.group("line")),
                    "column": int(match.group("col")),
                    "duration_ms": int(match.group("ms")),
                    "kind": "function-body",
                    "name": match.group("name"),
                }
            )
            continue
        match = _EXPRESSION_RE.match(line)
        if match:
            key = (match.group("file"), match.group("line"), match.group("col"), "expression")
            if key in seen:
                continue
            seen.add(key)
            warnings.append(
                {
                    "file": match.group("file"),
                    "line": int(match.group("line")),
                    "column": int(match.group("col")),
                    "duration_ms": int(match.group("ms")),
                    "kind": "expression",
                    "name": "",
                }
            )
    warnings.sort(key=lambda w: w["duration_ms"], reverse=True)
    return warnings


def parse_file_timings(output: str) -> List[Dict]:
    """Extract per-file compile times from -debug-time-compilation output."""
    timings: List[Dict] = []
    seen = set()
    for raw_line in output.splitlines():
        match = _FILE_TIME_RE.match(raw_line.strip())
        if match:
            filepath = match.group("file")
            if filepath in seen:
                continue
            seen.add(filepath)
            timings.append(
                {
                    "file": filepath,
                    "duration_seconds": float(match.group("seconds")),
                }
            )
    timings.sort(key=lambda t: t["duration_seconds"], reverse=True)
    return timings


def main() -> int:
    args = parse_args()
    output_dir = Path(args.output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)

    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    scheme_slug = args.scheme.replace(" ", "-").lower()
    artifact_stem = f"{timestamp}-{scheme_slug}"
    base = command_base(args)

    if not args.skip_clean:
        print("Cleaning build products...")
        clean = subprocess.run([*base, "clean"], capture_output=True, text=True)
        if clean.returncode != 0:
            sys.stderr.write(clean.stdout + clean.stderr)
            return clean.returncode

    threshold = str(args.threshold)
    swift_flags = (
        f"$(inherited) -Xfrontend -warn-long-function-bodies={threshold} "
        f"-Xfrontend -warn-long-expression-type-checking={threshold}"
    )
    if args.per_file_timing:
        swift_flags += " -Xfrontend -debug-time-compilation"

    stats_dir: Optional[Path] = None
    if args.stats_output:
        stats_dir = output_dir / f"{artifact_stem}-stats"
        stats_dir.mkdir(parents=True, exist_ok=True)
        swift_flags += f" -Xfrontend -stats-output-dir -Xfrontend {stats_dir}"

    build_command = [
        *base,
        "build",
        "-showBuildTimingSummary",
        f"OTHER_SWIFT_FLAGS={swift_flags}",
    ]

    extras = []
    if args.per_file_timing:
        extras.append("per-file timing")
    if args.stats_output:
        extras.append("stats output")
    extras_label = f" + {', '.join(extras)}" if extras else ""
    print(f"Building with type-check threshold {threshold}ms{extras_label}...")
    started = time.perf_counter()
    result = subprocess.run(build_command, capture_output=True, text=True)
    elapsed = round(time.perf_counter() - started, 3)

    combined_output = result.stdout + result.stderr
    log_path = output_dir / f"{artifact_stem}-diagnostics.log"
    log_path.write_text(combined_output)

    warnings = parse_diagnostics(combined_output)

    file_timings: Optional[List[Dict]] = None
    if args.per_file_timing:
        file_timings = parse_file_timings(combined_output)

    artifact = {
        "schema_version": "1.0.0",
        "created_at": datetime.now(timezone.utc).isoformat(),
        "type": "compilation-diagnostics",
        "build": {
            "entrypoint": "workspace" if args.workspace else "project",
            "path": args.workspace or args.project,
            "scheme": args.scheme,
            "configuration": args.configuration,
            "destination": args.destination or "",
        },
        "threshold_ms": args.threshold,
        "build_duration_seconds": elapsed,
        "build_success": result.returncode == 0,
        "raw_log_path": str(log_path),
        "warnings": warnings,
        "summary": {
            "total_warnings": len(warnings),
            "function_body_warnings": sum(1 for w in warnings if w["kind"] == "function-body"),
            "expression_warnings": sum(1 for w in warnings if w["kind"] == "expression"),
            "slowest_ms": warnings[0]["duration_ms"] if warnings else 0,
        },
    }

    if file_timings is not None:
        artifact["per_file_timings"] = file_timings
    if stats_dir is not None:
        artifact["stats_dir"] = str(stats_dir)

    artifact_path = output_dir / f"{artifact_stem}-diagnostics.json"
    artifact_path.write_text(json.dumps(artifact, indent=2) + "\n")

    print(f"\nSaved diagnostics artifact: {artifact_path}")
    print(f"Build {'succeeded' if result.returncode == 0 else 'failed'} in {elapsed}s")
    print(f"Found {len(warnings)} type-check warnings above {threshold}ms threshold\n")

    if warnings:
        print(f"{'Duration':>10}  {'Kind':<15}  {'Location'}")
        print(f"{'--------':>10}  {'----':<15}  {'--------'}")
        for w in warnings[:20]:
            loc = f"{w['file']}:{w['line']}:{w['column']}"
            label = w["name"] if w["name"] else "(expression)"
            print(f"{w['duration_ms']:>8}ms  {w['kind']:<15}  {loc}  {label}")
        if len(warnings) > 20:
            print(f"\n  ... and {len(warnings) - 20} more (see {artifact_path})")
    else:
        print("No type-checking hotspots found above threshold.")

    if file_timings:
        print(f"\nPer-file compile times (top 20):\n")
        print(f"{'Duration':>12}  {'File'}")
        print(f"{'--------':>12}  {'----'}")
        for t in file_timings[:20]:
            print(f"{t['duration_seconds']:>10.3f}s  {t['file']}")
        if len(file_timings) > 20:
            print(f"\n  ... and {len(file_timings) - 20} more (see {artifact_path})")

    if stats_dir is not None:
        stat_files = list(stats_dir.glob("*.json"))
        print(f"\nCompiler statistics: {len(stat_files)} files written to {stats_dir}")

    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3

"""Generate a Markdown optimization report from benchmark and diagnostics artifacts."""

import argparse
import json
import re
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Dict, List, Optional, Tuple


# ---------------------------------------------------------------------------
# pbxproj helpers
# ---------------------------------------------------------------------------

_SETTING_RE = re.compile(r"^\s*([A-Z_][A-Z_0-9]*)\s*=\s*(.+?)\s*;", re.MULTILINE)

_CONFIG_ID_RE = re.compile(r"([0-9A-F]{24})\s*/\*\s*(Debug|Release)\s*\*/")

_CONFIG_LIST_RE = re.compile(
    r"([0-9A-F]{24})\s*/\*\s*Build configuration list for "
    r"(?P<kind>PBXProject|PBXNativeTarget)\s+\"(?P<name>[^\"]+)\"\s*\*/"
)


def _parse_all_build_configs(pbxproj: str) -> Dict[str, Tuple[str, Dict[str, str]]]:
    """Return {config_id: (config_name, {key: value})} for every XCBuildConfiguration."""
    configs: Dict[str, Tuple[str, Dict[str, str]]] = {}
    for match in re.finditer(
        r"([0-9A-F]{24})\s*/\*\s*(Debug|Release)\s*\*/\s*=\s*\{\s*"
        r"isa\s*=\s*XCBuildConfiguration;\s*buildSettings\s*=\s*\{([^}]*)\}",
        pbxproj,
        re.DOTALL,
    ):
        config_id = match.group(1)
        config_name = match.group(2)
        body = match.group(3)
        settings: Dict[str, str] = {}
        for s in _SETTING_RE.finditer(body):
            val = s.group(2).strip().strip('"')
            settings[s.group(1)] = val
        configs[config_id] = (config_name, settings)
    return configs


def _resolve_config_list(
    pbxproj: str, all_configs: Dict[str, Tuple[str, Dict[str, str]]], kind: str
) -> Dict[str, Dict[str, Dict[str, str]]]:
    """Resolve configuration lists for a given kind (PBXProject or PBXNativeTarget)."""
    results: Dict[str, Dict[str, Dict[str, str]]] = {}
    for list_match in _CONFIG_LIST_RE.finditer(pbxproj):
        if list_match.group("kind") != kind:
            continue
        entity_name = list_match.group("name")
        list_id = list_match.group(1)
        block_start = pbxproj.find(f"{list_id} /*", list_match.end())
        if block_start == -1:
            block_start = list_match.start()
        block = pbxproj[block_start : block_start + 500]
        configs: Dict[str, Dict[str, str]] = {}
        for cid_match in _CONFIG_ID_RE.finditer(block):
            cid = cid_match.group(1)
            if cid in all_configs:
                cname, settings = all_configs[cid]
                configs[cname] = settings
        if configs:
            results[entity_name] = configs
    return results


def _parse_project_level_configs(pbxproj: str) -> Dict[str, Dict[str, str]]:
    """Extract project-level Debug and Release build settings."""
    all_configs = _parse_all_build_configs(pbxproj)
    resolved = _resolve_config_list(pbxproj, all_configs, "PBXProject")
    if resolved:
        return next(iter(resolved.values()))
    return {}


def _parse_target_configs(pbxproj: str) -> Dict[str, Dict[str, Dict[str, str]]]:
    """Extract per-target Debug and Release build settings."""
    all_configs = _parse_all_build_configs(pbxproj)
    return _resolve_config_list(pbxproj, all_configs, "PBXNativeTarget")


# ---------------------------------------------------------------------------
# Best-practices audit
# ---------------------------------------------------------------------------

_DEBUG_EXPECTATIONS: List[Tuple[str, str, str]] = [
    ("SWIFT_COMPILATION_MODE", "singlefile", "Single-file mode recompiles only changed files (Xcode UI: Incremental)"),
    ("SWIFT_OPTIMIZATION_LEVEL", "-Onone", "Optimization passes add compile time without debug benefit"),
    ("GCC_OPTIMIZATION_LEVEL", "0", "C/ObjC optimization adds compile time without debug benefit"),
    ("ONLY_ACTIVE_ARCH", "YES", "Building all architectures multiplies compile and link time"),
    ("DEBUG_INFORMATION_FORMAT", "dwarf", "dwarf-with-dsym generates a separate dSYM, adding overhead"),
    ("ENABLE_TESTABILITY", "YES", "Required for @testable import during development"),
    ("EAGER_LINKING", "YES", "Allows linker to start before all compilation finishes, reducing wall-clock time"),
]

_GENERAL_EXPECTATIONS: List[Tuple[str, str, str]] = [
    ("COMPILATION_CACHE_ENABLE_CACHING", "YES", "Caches compilation results so repeat builds of unchanged inputs are served from cache. Measured 5-14% faster clean builds across tested projects; benefit compounds during branch switching and pulling changes"),
]

_RELEASE_EXPECTATIONS: List[Tuple[str, str, str]] = [
    ("SWIFT_COMPILATION_MODE", "wholemodule", "Whole-module optimization produces faster runtime code"),
    ("SWIFT_OPTIMIZATION_LEVEL", "-O", "Optimized binaries for production (-Osize also acceptable)"),
    ("GCC_OPTIMIZATION_LEVEL", "s", "Optimizes C/ObjC for size in release"),
    ("ONLY_ACTIVE_ARCH", "NO", "Release builds must include all architectures for distribution"),
    ("DEBUG_INFORMATION_FORMAT", "dwarf-with-dsym", "dSYM bundles are needed for crash symbolication"),
    ("ENABLE_TESTABILITY", "NO", "Removes internal-symbol export overhead from release builds"),
]

_CONSISTENCY_KEYS = [
    "SWIFT_COMPILATION_MODE",
    "SWIFT_OPTIMIZATION_LEVEL",
    "ONLY_ACTIVE_ARCH",
    "DEBUG_INFORMATION_FORMAT",
]


def _effective_value(
    project: Dict[str, str], target: Dict[str, str], key: str
) -> Optional[str]:
    return target.get(key, project.get(key))


def _check(actual: Optional[str], expected: str) -> bool:
    if actual is None:
        if expected in ("singlefile",):
            return True
        return False
    if expected == "-O" and actual in ("-O", '"-O"', '"-Osize"', "-Osize"):
        return True
    return actual.strip('"') == expected


def _merged_project_settings(
    project_configs: Dict[str, Dict[str, str]],
) -> Dict[str, str]:
    """Return a flat dict of all settings across Debug and Release for general checks."""
    merged: Dict[str, str] = {}
    for config in project_configs.values():
        merged.update(config)
    return merged


def _audit_config(
    project_settings: Dict[str, str],
    expectations: List[Tuple[str, str, str]],
    config_name: str,
) -> List[str]:
    lines: List[str] = []
    for key, expected, _reason in expectations:
        actual = project_settings.get(key)
        display_actual = actual if actual else "(unset)"
        passed = _check(actual, expected)
        mark = "[x]" if passed else "[ ]"
        lines.append(f"- {mark} `{key}`: `{display_actual}` (recommended: `{expected}`)")
    return lines


def _audit_consistency(
    project_configs: Dict[str, Dict[str, str]],
    target_configs: Dict[str, Dict[str, Dict[str, str]]],
) -> List[str]:
    lines: List[str] = []
    for key in _CONSISTENCY_KEYS:
        overrides = []
        for target_name, configs in target_configs.items():
            for config_name in ("Debug", "Release"):
                target_settings = configs.get(config_name, {})
                if key in target_settings:
                    proj_val = project_configs.get(config_name, {}).get(key, "(unset)")
                    tgt_val = target_settings[key]
                    if tgt_val != proj_val:
                        overrides.append(
                            f"{target_name} ({config_name}): `{tgt_val}` vs project `{proj_val}`"
                        )
        if overrides:
            lines.append(f"- [ ] `{key}` has target-level overrides:")
            for o in overrides:
                lines.append(f"  - {o}")
        else:
            lines.append(f"- [x] `{key}` is consistent across all targets")
    return lines


# ---------------------------------------------------------------------------
# Auto-generated recommendations from audit
# ---------------------------------------------------------------------------


def _auto_recommendations_from_audit(
    project_configs: Dict[str, Dict[str, str]],
) -> Dict[str, Any]:
    """Generate basic recommendations from failing build settings audit checks."""
    items: List[Dict[str, str]] = []

    debug_settings = project_configs.get("Debug", {})
    for key, expected, reason in _DEBUG_EXPECTATIONS:
        if not _check(debug_settings.get(key), expected):
            actual = debug_settings.get(key, "(unset)")
            items.append({
                "title": f"Set `{key}` to `{expected}` for Debug",
                "category": "build-settings",
                "observed_evidence": f"Current value: `{actual}`. {reason}.",
                "estimated_impact": "Medium",
                "confidence": "High",
                "risk_level": "Low",
            })

    merged = {}
    for config in project_configs.values():
        merged.update(config)
    for key, expected, reason in _GENERAL_EXPECTATIONS:
        if not _check(merged.get(key), expected):
            actual = merged.get(key, "(unset)")
            items.append({
                "title": f"Enable `{key} = {expected}`",
                "category": "build-settings",
                "observed_evidence": f"Current value: `{actual}`. {reason}.",
                "estimated_impact": "High",
                "confidence": "High",
                "risk_level": "Low",
            })

    release_settings = project_configs.get("Release", {})
    for key, expected, reason in _RELEASE_EXPECTATIONS:
        if not _check(release_settings.get(key), expected):
            actual = release_settings.get(key, "(unset)")
            items.append({
                "title": f"Set `{key}` to `{expected}` for Release",
                "category": "build-settings",
                "observed_evidence": f"Current value: `{actual}`. {reason}.",
                "estimated_impact": "Medium",
                "confidence": "High",
                "risk_level": "Low",
            })

    if not items:
        return {"recommendations": []}
    return {"recommendations": items}


# ---------------------------------------------------------------------------
# Report generation
# ---------------------------------------------------------------------------


def _section_context(benchmark: Dict[str, Any]) -> str:
    build = benchmark.get("build", {})
    env = benchmark.get("environment", {})
    lines = [
        "## Project Context\n",
        f"- **Project:** `{build.get('path', 'unknown')}`",
        f"- **Scheme:** `{build.get('scheme', 'unknown')}`",
        f"- **Configuration:** `{build.get('configuration', 'unknown')}`",
        f"- **Destination:** `{build.get('destination', 'unknown')}`",
        f"- **Xcode:** {env.get('xcode_version', 'unknown').replace(chr(10), ' ')}",
        f"- **macOS:** {env.get('macos_version', 'unknown')}",
        f"- **Date:** {benchmark.get('created_at', 'unknown')}",
        f"- **Benchmark artifact:** `{benchmark.get('_artifact_path', 'unknown')}`",
    ]
    return "\n".join(lines)


def _section_baseline(benchmark: Dict[str, Any]) -> str:
    summary = benchmark.get("summary", {})
    clean = summary.get("clean", {})
    cached_clean = summary.get("cached_clean", {})
    incremental = summary.get("incremental", {})
    has_cached = bool(cached_clean and cached_clean.get("count", 0) > 0)

    if has_cached:
        lines = [
            "## Baseline Benchmarks\n",
            "| Metric | Clean | Cached Clean | Incremental |",
            "|--------|-------|-------------|-------------|",
            f"| Median | {clean.get('median_seconds', 0):.3f}s | {cached_clean.get('median_seconds', 0):.3f}s | {incremental.get('median_seconds', 0):.3f}s |",
            f"| Min | {clean.get('min_seconds', 0):.3f}s | {cached_clean.get('min_seconds', 0):.3f}s | {incremental.get('min_seconds', 0):.3f}s |",
            f"| Max | {clean.get('max_seconds', 0):.3f}s | {cached_clean.get('max_seconds', 0):.3f}s | {incremental.get('max_seconds', 0):.3f}s |",
            f"| Runs | {clean.get('count', 0)} | {cached_clean.get('count', 0)} | {incremental.get('count', 0)} |",
        ]
        lines.append(
            "\n> **Cached Clean** = clean build with a warm compilation cache. "
            "This is the realistic scenario for branch switching, pulling changes, or "
            "Clean Build Folder. The compilation cache lives outside DerivedData and "
            "survives product deletion.\n"
        )
    else:
        lines = [
            "## Baseline Benchmarks\n",
            "| Metric | Clean | Incremental |",
            "|--------|-------|-------------|",
            f"| Median | {clean.get('median_seconds', 0):.3f}s | {incremental.get('median_seconds', 0):.3f}s |",
            f"| Min | {clean.get('min_seconds', 0):.3f}s | {incremental.get('min_seconds', 0):.3f}s |",
            f"| Max | {clean.get('max_seconds', 0):.3f}s | {incremental.get('max_seconds', 0):.3f}s |",
            f"| Runs | {clean.get('count', 0)} | {incremental.get('count', 0)} |",
        ]

    build_types = ["clean", "cached_clean", "incremental"] if has_cached else ["clean", "incremental"]
    label_map = {"clean": "Clean", "cached_clean": "Cached Clean", "incremental": "Incremental"}
    for build_type in build_types:
        runs = benchmark.get("runs", {}).get(build_type, [])
        all_cats: Dict[str, Dict] = {}
        for run in runs:
            for cat in run.get("timing_summary_categories", []):
                name = cat["name"]
                if name not in all_cats:
                    all_cats[name] = {"seconds": 0.0, "task_count": 0}
                all_cats[name]["seconds"] += cat["seconds"]
                all_cats[name]["task_count"] += cat.get("task_count", 0)
        if all_cats:
            count = len(runs) or 1
            ranked = sorted(all_cats.items(), key=lambda x: x[1]["seconds"], reverse=True)
            label = label_map.get(build_type, build_type.title())
            lines.append(f"\n### {label} Build Timing Summary\n")
            lines.append(
                "> **Note:** These are aggregated task times across all CPU cores. "
                "Because Xcode runs many tasks in parallel, these totals typically exceed "
                "the actual build wait time shown above. A large number here does not mean "
                "it is blocking your build.\n"
            )
            lines.append("| Category | Tasks | Seconds |")
            lines.append("|----------|------:|--------:|")
            for name, data in ranked:
                avg_sec = data["seconds"] / count
                tasks = data["task_count"] // count if data["task_count"] else ""
                lines.append(f"| {name} | {tasks} | {avg_sec:.3f}s |")

    return "\n".join(lines)


def _section_settings_audit(
    project_configs: Dict[str, Dict[str, str]],
    target_configs: Dict[str, Dict[str, Dict[str, str]]],
) -> str:
    lines = ["## Build Settings Audit\n"]

    lines.append("### Debug Configuration\n")
    lines.extend(_audit_config(project_configs.get("Debug", {}), _DEBUG_EXPECTATIONS, "Debug"))

    lines.append("\n### General (All Configurations)\n")
    merged = _merged_project_settings(project_configs)
    lines.extend(_audit_config(merged, _GENERAL_EXPECTATIONS, "General"))

    lines.append("\n### Release Configuration\n")
    lines.extend(_audit_config(project_configs.get("Release", {}), _RELEASE_EXPECTATIONS, "Release"))

    lines.append("\n### Cross-Target Consistency\n")
    lines.extend(_audit_consistency(project_configs, target_configs))

    return "\n".join(lines)


def _section_diagnostics(diagnostics: Optional[Dict[str, Any]]) -> str:
    if diagnostics is None:
        return "## Compilation Diagnostics\n\nNo diagnostics artifact provided. Run `diagnose_compilation.py` to identify type-checking hotspots."
    warnings = diagnostics.get("warnings", [])
    summary = diagnostics.get("summary", {})
    threshold = diagnostics.get("threshold_ms", 100)
    lines = [
        "## Compilation Diagnostics\n",
        f"Threshold: {threshold}ms | "
        f"Total warnings: {summary.get('total_warnings', 0)} | "
        f"Function bodies: {summary.get('function_body_warnings', 0)} | "
        f"Expressions: {summary.get('expression_warnings', 0)}\n",
    ]
    if warnings:
        lines.append("| Duration | Kind | File | Line | Name |")
        lines.append("|---------:|------|------|-----:|------|")
        for w in warnings[:30]:
            short_file = Path(w["file"]).name
            name = w.get("name", "") or "(expression)"
            lines.append(
                f"| {w['duration_ms']}ms | {w['kind']} | {short_file} | {w['line']} | {name} |"
            )
        if len(warnings) > 30:
            lines.append(f"\n*... and {len(warnings) - 30} more warnings (see full artifact)*")
    else:
        lines.append("No type-checking hotspots found above threshold.")
    return "\n".join(lines)


def _section_recommendations(recommendations: Optional[Dict[str, Any]]) -> str:
    if recommendations is None:
        return "## Prioritized Recommendations\n\nNo recommendations artifact provided."
    items = recommendations.get("recommendations", [])
    if not items:
        return "## Prioritized Recommendations\n\nNo recommendations found."
    lines = ["## Prioritized Recommendations\n"]
    for i, item in enumerate(items, 1):
        title = item.get("title", "Untitled")
        lines.append(f"### {i}. {title}\n")
        for field, label in [
            ("wait_time_impact", "Wait-Time Impact"),
            ("actionability", "Actionability"),
            ("category", "Category"),
            ("observed_evidence", "Evidence"),
            ("estimated_impact", "Impact"),
            ("confidence", "Confidence"),
            ("risk_level", "Risk"),
            ("scope", "Scope"),
        ]:
            val = item.get(field)
            if val is None:
                continue
            if isinstance(val, list):
                lines.append(f"**{label}:**")
                for entry in val:
                    lines.append(f"- {entry}")
            else:
                lines.append(f"**{label}:** {val}")
        lines.append("")
    return "\n".join(lines)


def _section_approval(recommendations: Optional[Dict[str, Any]]) -> str:
    if recommendations is None:
        return "## Approval Checklist\n\nNo recommendations to approve."
    items = recommendations.get("recommendations", [])
    if not items:
        return "## Approval Checklist\n\nNo recommendations to approve."
    lines = ["## Approval Checklist\n"]
    for i, item in enumerate(items, 1):
        title = item.get("title", "Untitled")
        wait_impact = item.get("wait_time_impact", "")
        impact = item.get("estimated_impact", "")
        risk = item.get("risk_level", "")
        actionability = item.get("actionability", "")
        impact_str = wait_impact if wait_impact else impact
        actionability_str = f" | Actionability: {actionability}" if actionability else ""
        lines.append(f"- [ ] **{i}. {title}** -- Impact: {impact_str}{actionability_str} | Risk: {risk}")
    return "\n".join(lines)


def _section_next_steps(benchmark: Dict[str, Any]) -> str:
    build = benchmark.get("build", {})
    command = build.get("command", "xcodebuild build")
    lines = [
        "## Next Steps\n",
        "After implementing approved changes, re-benchmark with the same inputs:\n",
        "```bash",
        f"python3 scripts/benchmark_builds.py \\",
    ]
    if build.get("entrypoint") == "workspace":
        lines.append(f"  --workspace {build.get('path', 'App.xcworkspace')} \\")
    else:
        lines.append(f"  --project {build.get('path', 'App.xcodeproj')} \\")
    lines.extend([
        f"  --scheme {build.get('scheme', 'App')} \\",
        f"  --configuration {build.get('configuration', 'Debug')} \\",
    ])
    if build.get("destination"):
        lines.append(f'  --destination "{build["destination"]}" \\')
    lines.append("  --output-dir .build-benchmark")
    lines.append("```\n")
    lines.append("Compare the new wall-clock medians against the baseline. Report results as:")
    lines.append('"Your [clean/incremental] build now takes X.Xs (was Y.Ys) -- Z.Zs faster/slower."')
    return "\n".join(lines)


# ---------------------------------------------------------------------------
# Main
# ---------------------------------------------------------------------------


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Generate a Markdown build optimization report.")
    parser.add_argument("--benchmark", required=True, help="Path to benchmark JSON artifact")
    parser.add_argument("--recommendations", help="Path to recommendations JSON")
    parser.add_argument("--diagnostics", help="Path to diagnostics JSON")
    parser.add_argument("--project-path", help="Path to .xcodeproj for build settings audit")
    parser.add_argument("--output", help="Output Markdown path (default: stdout)")
    return parser.parse_args()


def main() -> int:
    args = parse_args()

    benchmark = json.loads(Path(args.benchmark).read_text())
    benchmark["_artifact_path"] = args.benchmark

    recommendations = None
    if args.recommendations:
        recommendations = json.loads(Path(args.recommendations).read_text())

    diagnostics = None
    if args.diagnostics:
        diagnostics = json.loads(Path(args.diagnostics).read_text())

    project_configs: Dict[str, Dict[str, str]] = {}
    target_configs: Dict[str, Dict[str, Dict[str, str]]] = {}
    if args.project_path:
        pbxproj_path = Path(args.project_path) / "project.pbxproj"
        if pbxproj_path.exists():
            pbxproj = pbxproj_path.read_text()
            project_configs = _parse_project_level_configs(pbxproj)
            target_configs = _parse_target_configs(pbxproj)

    if recommendations is None and project_configs:
        auto = _auto_recommendations_from_audit(project_configs)
        if auto["recommendations"]:
            recommendations = auto

    sections = [
        "# Xcode Build Optimization Plan\n",
        _section_context(benchmark),
        _section_baseline(benchmark),
    ]

    if project_configs:
        sections.append(_section_settings_audit(project_configs, target_configs))

    sections.append(_section_diagnostics(diagnostics))
    sections.append(_section_recommendations(recommendations))
    sections.append(_section_approval(recommendations))
    sections.append(_section_next_steps(benchmark))

    report = "\n\n".join(sections) + "\n"

    if args.output:
        Path(args.output).write_text(report)
        print(f"Saved optimization report: {args.output}")
    else:
        print(report, end="")

    return 0


if __name__ == "__main__":
    raise SystemExit(main())