fuzzprep 0.1.0__py3-none-any.whl

fuzzprep/library_builder/environments/verification.py

@@ -0,0 +1,125 @@
+"""The build gate: one script that decides whether a build passed, and where to run it.
+
+`agents/scripts/check_build.sh` is the only definition of "the build passed". This module
+decides only where it runs — as a host subprocess, or inside the workspace's own OSS-Fuzz
+image with the workspace mounted. The pipeline and every repair agent go through here, so an
+agent verifies its fix against the same assertions the pipeline applies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from fuzzprep.core.resources import agent_script
+from fuzzprep.core.subprocesses import MergedOutput, run_command_streaming
+from fuzzprep.library_builder.environments.base import Environment
+from fuzzprep.library_builder.timeouts import DEFAULT_BUILD_TIMEOUT_SECONDS
+
+
+@dataclass
+class VerificationResult(MergedOutput):
+    """The atomic pass/fail outcome of the shared check_build.sh script."""
+
+    passed: bool
+    command: list[str]
+    stdout: str
+    stderr: str
+    duration_seconds: float
+
+
+def gate_keeps_artifacts(*, library_llm_used: bool, bypass_scratch_validation: bool) -> bool:
+    """Whether the gate may reuse the workspace's install/ instead of rebuilding the library.
+
+    True only when a valid install/ is already there and nothing has changed the build since:
+    the deterministic library build produced it, or the caller traded the from-scratch
+    guarantee for speed with --bypass-scratch-validation.
+
+    One definition, because two callers must reach the same answer -- the pipeline's own gate,
+    and the command a repair agent is told to run. When they disagreed, the agent paid a full
+    cold rebuild of the library the pipeline had deliberately decided to keep.
+    """
+    return bypass_scratch_validation or not library_llm_used
+
+
+def verification_command(
+    workspace: Path, *, environment: Environment, project_name: str, keep_artifacts: bool = False
+) -> list[str]:
+    """The gate invocation for workspace, without running it.
+
+    Shared by run_verification and by callers that already know the answer — a probe that
+    failed — and only need a command to report as "reproduce with".
+
+    keep_artifacts drops the gate's deletion of install/ and build/, so the library build is
+    skipped rather than repeated. Only for a caller that already built the library from
+    nothing; see the comment on that deletion in check_build.sh.
+
+    The path is resolved because every gate script cds to the workspace it is handed while
+    _run also sets cwd to it, so a relative path would be applied twice. It also makes the
+    reported command runnable from any directory.
+    """
+    workspace = workspace.resolve()
+    options = ["--keep-artifacts"] if keep_artifacts else []
+    if environment is Environment.OSS_FUZZ:
+        return [
+            "bash",
+            str(agent_script("check_build_in_container.sh")),
+            str(workspace),
+            project_name,
+            *options,
+        ]
+    return ["bash", str(agent_script("check_build.sh")), str(workspace), *options]
+
+
+def run_verification(
+    workspace: Path,
+    *,
+    environment: Environment,
+    project_name: str,
+    keep_artifacts: bool = False,
+    timeout: int = DEFAULT_BUILD_TIMEOUT_SECONDS,
+) -> VerificationResult:
+    """Run the gate for workspace in the given environment."""
+    command = verification_command(
+        workspace,
+        environment=environment,
+        project_name=project_name,
+        keep_artifacts=keep_artifacts,
+    )
+    return _run(command, cwd=workspace.resolve(), timeout=timeout)
+
+
+def run_from_scratch_docker_verification(
+    project_dir: Path,
+    *,
+    project_name: str,
+    timeout: int = DEFAULT_BUILD_TIMEOUT_SECONDS,
+) -> VerificationResult:
+    """Build project_dir's Dockerfile with nothing mounted and run OSS-Fuzz's `compile`.
+
+    The gate mounts the workspace, which is what puts the artifacts on the host — and also
+    what lets a broken clone or apt layer pass unnoticed, since the mount supplies what the
+    image failed to. This check keeps the mounted gate honest, so it runs once per successful
+    oss-fuzz run, immediately before generation.
+
+    project_dir is resolved for the same reason verification_command resolves it.
+    """
+    project_dir = project_dir.resolve()
+    command = [
+        "bash",
+        str(agent_script("check_dockerfile_from_scratch.sh")),
+        str(project_dir),
+        project_name,
+    ]
+    return _run(command, cwd=project_dir, timeout=timeout)
+
+
+def _run(command: list[str], *, cwd: Path, timeout: int) -> VerificationResult:
+    result = run_command_streaming(command, cwd, timeout)
+    return VerificationResult(
+        passed=result.exit_code == 0,
+        command=command,
+        stdout=result.stdout,
+        stderr=result.stderr,
+        duration_seconds=result.duration_seconds,
+    )

fuzzprep/library_builder/exploration.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+from pathlib import Path
+
+from fuzzprep.core.files import write_executable
+from fuzzprep.core.subprocesses import Runner, run_command_streaming
+from fuzzprep.library_builder.build_parameters import BuildParameters
+from fuzzprep.library_builder.environments.base import Environment
+from fuzzprep.library_builder.models import (
+    AgentReport,
+    AnalysisResult,
+    BuildExplorationResult,
+    BuildPaths,
+    BuildSystem,
+)
+from fuzzprep.library_builder.scripts import build_library_script
+from fuzzprep.library_builder.timeouts import DEFAULT_BUILD_TIMEOUT_SECONDS
+
+logger = logging.getLogger(__name__)
+
+_BEAR_NOT_FOUND_ERROR = (
+    "bear not found on PATH; install bear to capture compile_commands.json for "
+    "Make/Autotools builds"
+)
+
+_MAKE_LIKE_SYSTEMS = (BuildSystem.MAKEFILE, BuildSystem.AUTOTOOLS)
+
+
+def is_standard_source_layout(analysis: AnalysisResult, workdir: Path) -> bool:
+    """True when the source was cloned to workdir/src, the layout generated output expects.
+
+    build_library.sh's paths can then be $SCRIPT_DIR-relative, so the same script works
+    unmodified from the workspace and from a generated output directory.
+    """
+    return analysis.source_path.resolve() == (workdir / "src").resolve()
+
+
+def write_build_library_script(
+    analysis: AnalysisResult, workdir: Path, *, parameters: BuildParameters | None = None
+) -> tuple[Path, bool]:
+    """Write build_library.sh into workdir/build_library.sh.
+
+    With the standard workdir/src layout the paths are $SCRIPT_DIR-relative, so the script
+    can be published verbatim; otherwise they fall back to absolute. Returns (script_path,
+    standard_layout) so callers know whether BuildExplorationResult.script_path can be set.
+
+    Separate from explore() because OssFuzzExecutor needs this file on disk before building
+    the workspace image, which COPYs it.
+    """
+    workdir = workdir.resolve()
+    standard_layout = is_standard_source_layout(analysis, workdir)
+    source_dir = "$SCRIPT_DIR/src" if standard_layout else str(analysis.source_path.resolve())
+
+    parameters = parameters or BuildParameters.defaults()
+    script = build_library_script(
+        analysis.build_system,
+        BuildPaths(
+            source_dir=source_dir,
+            build_dir="$BUILD_PREFIX/build",
+            install_dir="$BUILD_PREFIX/install",
+        ),
+        autotools_setup=analysis.autotools_setup,
+        configure_args=parameters.library_configure_args,
+        cc=parameters.cc,
+        cxx=parameters.cxx,
+        cflags=parameters.library_cflags,
+        cxxflags=parameters.library_cxxflags,
+    )
+    script_path = write_executable(workdir / "build_library.sh", script)
+    return script_path, standard_layout
+
+
+def explore(  # noqa: PLR0913 -- 4 keyword-only inputs, each independently meaningful
+    analysis: AnalysisResult,
+    workdir: Path,
+    *,
+    timeout: int = DEFAULT_BUILD_TIMEOUT_SECONDS,
+    environment: Environment = Environment.LOCAL,
+    run: Runner | None = None,
+    parameters: BuildParameters | None = None,
+) -> BuildExplorationResult:
+    """Write a build_library.sh into workdir and run it in the given environment.
+
+    environment decides whether the build command is wrapped with `bear`, and is recorded on
+    the returned result; the script text itself is environment-independent. run defaults to
+    streaming as a host subprocess; a caller building inside a container passes a run
+    primitive that wraps the command in `docker run`.
+    """
+    workdir = workdir.resolve()
+    build_dir = workdir / "build"
+    install_dir = workdir / "install"
+
+    if build_dir.exists():
+        shutil.rmtree(build_dir)
+    build_dir.mkdir(parents=True)
+
+    if install_dir.exists():
+        shutil.rmtree(install_dir)
+    install_dir.mkdir(parents=True)
+
+    script_path, standard_layout = write_build_library_script(
+        analysis, workdir, parameters=parameters
+    )
+
+    if analysis.build_system == BuildSystem.UNKNOWN:
+        return BuildExplorationResult(
+            build_system=analysis.build_system,
+            succeeded=False,
+            command=[],
+            stdout="",
+            stderr="",
+            exit_code=-1,
+            duration_seconds=0.0,
+            environment=environment,
+        )
+
+    command = _build_command(analysis.build_system, environment, script_path)
+
+    runner = run if run is not None else run_command_streaming
+    result = runner(command, workdir, timeout)
+
+    succeeded = result.exit_code == 0
+    stderr = result.stderr
+    if succeeded:
+        validation_errors = validate_install_artifacts(install_dir)
+        if validation_errors:
+            succeeded = False
+            stderr += "\n" + "\n".join(validation_errors)
+
+    return BuildExplorationResult(
+        build_system=analysis.build_system,
+        succeeded=succeeded,
+        command=command,
+        stdout=result.stdout,
+        stderr=stderr,
+        exit_code=result.exit_code,
+        duration_seconds=result.duration_seconds,
+        install_dir=install_dir,
+        script_path=script_path if standard_layout else None,
+        environment=environment,
+    )
+
+
+def _build_command(
+    build_system: BuildSystem, environment: Environment, script_path: Path
+) -> list[str]:
+    """Choose the canonical build invocation, wrapping Make/Autotools with `bear --`.
+
+    The wrap is unconditional in the oss-fuzz environment, where bear is always present. On the
+    local host it is best-effort: a missing bear must not fail the build, and it is the gate's
+    own bear wrap that decides whether a capture ships (see workspace.find_compile_commands).
+    """
+    plain = ["bash", str(script_path.name)]
+    if build_system not in _MAKE_LIKE_SYSTEMS:
+        return plain
+    if environment is Environment.OSS_FUZZ or shutil.which("bear") is not None:
+        return ["bear", "--", *plain]
+    return plain
+
+
+def compile_commands_absent_reason(build_system: BuildSystem) -> str:
+    """Why the gate's build left no compile_commands.json behind.
+
+    CMake and Meson emit one themselves, so for those a missing file means the build did not
+    reach the point of writing it. Make and Autotools have no equivalent and need bear, which
+    is only best-effort on a host.
+    """
+    if build_system in _MAKE_LIKE_SYSTEMS and shutil.which("bear") is None:
+        return _BEAR_NOT_FOUND_ERROR
+    return "the build produced none"
+
+
+def _string_list(value: object) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        return []
+    return [str(item) for item in value]
+
+
+def read_agent_report(workdir: Path) -> AgentReport | None:
+    """Read and delete workdir/agent_report.json, tolerantly parsing its contents.
+
+    Returns None if the file is absent, is not valid JSON, or is not a JSON object. Deletes
+    the file whenever it existed, so a later invocation cannot pick up a stale report.
+    """
+    report_path = workdir / "agent_report.json"
+    if not report_path.exists():
+        return None
+    try:
+        data = json.loads(report_path.read_text())
+        if not isinstance(data, dict):
+            return None
+        summary = data.get("summary")
+        return AgentReport(
+            summary=summary if isinstance(summary, str) else None,
+            missing_libs=_string_list(data.get("missing_libs")),
+            missing_apt_packages=_string_list(data.get("missing_apt_packages")),
+            extra_include_paths=_string_list(data.get("extra_include_paths")),
+            extra_library_paths=_string_list(data.get("extra_library_paths")),
+        )
+    except (json.JSONDecodeError, OSError):
+        return None
+    finally:
+        report_path.unlink(missing_ok=True)
+
+
+def validate_install_artifacts(install_dir: Path) -> list[str]:
+    errors = []
+    lib_dir = install_dir / "lib"
+    if not lib_dir.exists() or not any(lib_dir.glob("*.a")):
+        errors.append(f"no static libraries (*.a) found in {lib_dir}")
+    include_dir = install_dir / "include"
+    if not include_dir.exists() or not any(include_dir.iterdir()):
+        errors.append(f"no headers found in {include_dir}")
+    return errors

fuzzprep/library_builder/generation.py

@@ -0,0 +1,325 @@
+"""Publishing the verified workspace as the output directory.
+
+There is one output shape, whichever environment verified it: the workspace copied verbatim,
+so the shipped scripts are the ones that passed, plus what only makes sense outside the
+workspace — `setup.sh`, the built `install/` tree, the build's `compile_commands.json`, and a
+README naming the environment this run actually exercised.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from fuzzprep.core.files import copy_executable, write_executable
+from fuzzprep.library_builder import workspace
+from fuzzprep.library_builder.environments.base import Environment
+from fuzzprep.library_builder.models import (
+    AnalysisResult,
+    BuildExplorationResult,
+    GenerationResult,
+    HarnessExplorationResult,
+)
+from fuzzprep.library_builder.scripts import HARNESS_SOURCE_DIR
+
+# Copied from the workspace verbatim: the validated scripts, plus the OSS-Fuzz project files
+# around them.
+_COPIED_SCRIPTS = ("build.sh", "build_library.sh", "compile_harness.sh", "compile_harnesses.sh")
+_COPIED_FILES = ("project.yaml",)
+
+# Build products and run metadata: worth shipping, but never part of the docker build context,
+# since the container rebuilds from its own fresh clone.
+_DOCKERIGNORE = ("install/\n", "compile_commands.json\n", "stats.json\n", "logs/\n", "out/\n")
+
+
+class MissingInstallTreeError(Exception):
+    """Generation was asked to publish a build whose install tree it cannot find."""
+
+
+@dataclass(frozen=True)
+class GenerationInputs:
+    """Everything generation needs beyond the workspace itself.
+
+    Grouped because they all answer one question — what this run actually did — and each
+    appears in the README as well as in a generated file.
+    """
+
+    analysis: AnalysisResult
+    build: BuildExplorationResult
+    harness: HarnessExplorationResult
+    system_packages: list[str]
+    environment: Environment
+    agent_backend: str | None
+    scratch_validation_bypassed: bool = False
+
+
+def generate(workspace_dir: Path, output_path: Path, inputs: GenerationInputs) -> GenerationResult:
+    """Copy the verified workspace to output_path and add the host-side resources.
+
+    The output is itself an OSS-Fuzz project and a standalone host build tree at once:
+    `docker build .` works, and so does `setup.sh` followed by `build_library.sh`.
+    """
+    output_path.mkdir(parents=True)
+    files: list[Path] = [
+        *_copy_project_files(workspace_dir, output_path, inputs.system_packages),
+        *_copy_harness_source(workspace_dir, output_path),
+        _write_setup_sh(output_path, inputs.analysis, inputs.system_packages),
+        _write_dockerignore(output_path),
+    ]
+    _copy_install_tree(inputs.build, output_path)
+    compile_commands = _copy_compile_commands(workspace_dir, output_path)
+    if compile_commands is not None:
+        files.append(compile_commands)
+    files.append(
+        write_readme(output_path, inputs, build_tree=workspace_dir if compile_commands else None)
+    )
+
+    return GenerationResult(
+        project_name=inputs.analysis.project_name,
+        output_path=output_path,
+        files=files,
+    )
+
+
+def _copy_project_files(
+    workspace_dir: Path, output_path: Path, system_packages: list[str]
+) -> list[Path]:
+    """Copy the scripts and project files the workspace validated, verbatim.
+
+    The Dockerfile is the exception: the shipped copy must not depend on `bear`, which the
+    workspace image carries only so compile_commands.json can be captured.
+    """
+    copied = [copy_executable(workspace_dir / name, output_path / name) for name in _COPIED_SCRIPTS]
+    for name in _COPIED_FILES:
+        shutil.copy2(workspace_dir / name, output_path / name)
+        copied.append(output_path / name)
+
+    dockerfile = output_path / "Dockerfile"
+    dockerfile.write_text(
+        workspace.strip_bear_dependency((workspace_dir / "Dockerfile").read_text())
+    )
+    workspace.inject_apt_packages(output_path, system_packages)
+    copied.append(dockerfile)
+    return copied
+
+
+def _copy_harness_source(workspace_dir: Path, output_path: Path) -> list[Path]:
+    """Copy harness_source/* verbatim, including whichever default_fuzzer extension discovery
+    settled on."""
+    source_dir = workspace_dir / HARNESS_SOURCE_DIR
+    destination_dir = output_path / HARNESS_SOURCE_DIR
+    destination_dir.mkdir()
+    copied: list[Path] = []
+    for entry in sorted(source_dir.iterdir()):
+        destination = destination_dir / entry.name
+        shutil.copy2(entry, destination)
+        copied.append(destination)
+    return copied
+
+
+def _copy_install_tree(build: BuildExplorationResult, output_path: Path) -> None:
+    """Publish the built library — the artifact a user links their first harness against.
+
+    Shipped for every environment: compile_harness.sh links against install/, so an output
+    directory without it hands the user a script that cannot run. Raises rather than skipping,
+    because generation only runs after a verified build: a missing tree here means the result
+    lost track of one that exists, and skipping it published an unusable project as a success.
+    """
+    install_dir = build.install_dir
+    if install_dir is None:
+        msg = (
+            "the verified build result records no install tree, so the generated project has "
+            "no library for compile_harness.sh to link against"
+        )
+        raise MissingInstallTreeError(msg)
+    if not install_dir.is_dir():
+        msg = f"the verified build's install tree is missing at {install_dir}"
+        raise MissingInstallTreeError(msg)
+    shutil.copytree(install_dir, output_path / "install", symlinks=True)
+
+
+def _copy_compile_commands(workspace_dir: Path, output_path: Path) -> Path | None:
+    """Copy compile_commands.json into the output directory, keeping its workspace paths.
+
+    A compilation database only means anything next to the build tree it describes, and the
+    output directory ships `install/` alone -- no `src/`, no `build/`. So the paths are left
+    pointing at `.fuzzprep/<project>/`, where the tree that produced them still stands;
+    rewriting them to the output directory named files that were never copied there, and
+    tooling chdirs into each entry's `directory` before it reads anything.
+    """
+    captured = workspace.find_compile_commands(workspace_dir)
+    if captured is None:
+        return None
+    destination = output_path / "compile_commands.json"
+    destination.write_text(usable_compile_commands(captured.read_text()))
+    return destination
+
+
+def _write_dockerignore(output_path: Path) -> Path:
+    """Keep the build products out of the docker build context.
+
+    The image rebuilds the library from its own clone, so sending install/ — hundreds of MB
+    for a large library — would only slow every build down.
+    """
+    path = output_path / ".dockerignore"
+    path.write_text("".join(_DOCKERIGNORE))
+    return path
+
+
+def _write_setup_sh(
+    output_path: Path, analysis: AnalysisResult, system_packages: list[str]
+) -> Path:
+    """Write setup.sh — clone the library and install its build dependencies.
+
+    The host counterpart of the Dockerfile's clone and apt layers, so it uses the same
+    `apt-get update && apt-get install` form. `sudo` is resolved when the script runs, since
+    the generating host's uid says nothing about the consuming host's.
+    """
+    lines = [
+        "#!/bin/bash\n",
+        "set -euo pipefail\n",
+        "\n",
+        'SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"\n',
+        "\n",
+        f'git clone --recursive {analysis.clone_url} "$SCRIPT_DIR/src"\n',
+    ]
+    if analysis.repo_ref is not None:
+        lines.append(f'git -C "$SCRIPT_DIR/src" checkout {analysis.repo_ref}\n')
+    lines.append("\n")
+    if system_packages:
+        lines += [
+            'if [ "$(id -u)" -eq 0 ]; then\n',
+            '  SUDO=""\n',
+            "else\n",
+            '  SUDO="sudo"\n',
+            "fi\n",
+            "$SUDO apt-get update\n",
+            f"$SUDO apt-get install -y --no-install-recommends {' '.join(system_packages)}\n",
+        ]
+    else:
+        lines.append("# No build dependencies were discovered for this library.\n")
+    return write_executable(output_path / "setup.sh", "".join(lines))
+
+
+def usable_compile_commands(text: str) -> str:
+    """Drop the entries a clang tool cannot replay, keeping the rest verbatim.
+
+    `bear` records every compiler exec the build made, not just the ones that compiled library
+    sources. Three kinds of entry come back unusable, and each is fatal rather than noisy:
+    a `directory` CMake has since deleted (its `CMakeScratch/TryCompile-*` dirs) aborts the
+    whole run, because a clang tool chdirs there before it parses; a raw `-cc1` invocation is
+    rejected argument by argument when the driver is asked to replay it; and CMake's own
+    `CMakeFiles/` probe sources are not part of the library at all.
+    """
+    entries = json.loads(text)
+    return json.dumps([entry for entry in entries if _entry_is_usable(entry)], indent=2)
+
+
+def _entry_is_usable(entry: dict) -> bool:
+    directory, file = entry.get("directory"), entry.get("file")
+    if not isinstance(directory, str) or not isinstance(file, str):
+        return False
+    if not Path(directory).is_dir() or not Path(file).is_file():
+        return False
+    if "CMakeFiles" in Path(file).parts:
+        return False
+    arguments = entry.get("arguments")
+    if isinstance(arguments, list) and "-cc1" in arguments:
+        return False
+    command = entry.get("command")
+    return not (isinstance(command, str) and "-cc1" in command.split())
+
+
+def _compile_commands_section(build_tree: Path | None) -> str:
+    """The README's account of where the shipped compilation database points.
+
+    A database is only readable next to the tree it describes, and this directory is not that
+    tree, so the section names the one it is — and says nothing at all when no database shipped.
+    """
+    if build_tree is None:
+        return ""
+    return f"""
+## compile_commands.json
+
+`compile_commands.json` describes the build this run made, so its paths point into that
+build tree at `{build_tree}` — not into this directory, which ships `install/` alone.
+It reads correctly for as long as that tree stands; re-run FuzzPrep to refresh it.
+"""
+
+
+def write_readme(output_path: Path, inputs: GenerationInputs, *, build_tree: Path | None) -> Path:
+    """Write README.md — what to run, and what this run actually proved.
+
+    The directory provisions both environments but only one was exercised, so the README says
+    which. Otherwise it implies the host scripts and the Dockerfile were both verified.
+
+    build_tree is the workspace the shipped compile_commands.json describes, or None when the
+    build captured none; naming it is what stops a reader from taking those paths for this
+    directory's own.
+    """
+    analysis = inputs.analysis
+    verified, unverified = (
+        ("oss-fuzz (in the container)", "The host scripts (setup.sh, build_library.sh) are")
+        if inputs.environment is Environment.OSS_FUZZ
+        else (
+            "local (on the host)",
+            "The container path (Dockerfile, build.sh under `compile`) is",
+        )
+    )
+    harness_stub = f"{HARNESS_SOURCE_DIR}/default_fuzzer.*"
+    scratch_note = (
+        "\n- **Not proven from scratch.** This run used `--bypass-scratch-validation`, so the "
+        "library was never rebuilt into an empty tree to confirm the result. The artifacts "
+        "here are the ones the run produced, not ones shown to reproduce."
+        if inputs.scratch_validation_bypassed
+        else ""
+    )
+    text = f"""# {analysis.project_name} — fuzzing build
+
+Prepared by FuzzPrep. This directory is both an OSS-Fuzz project and a standalone
+host build tree.
+
+## What this run verified
+
+- **Verified: {verified}.** {unverified} generated but was not executed by this run.
+- Build system: {analysis.build_system.value}
+- Repository: {analysis.clone_url} (ref: {analysis.repo_ref or "default branch"})
+- Repair agent: {inputs.agent_backend or "none"}
+- Verified with: `{" ".join(inputs.harness.command or inputs.build.command) or "n/a"}`{scratch_note}
+
+## Run it on the host
+
+```bash
+./setup.sh              # clone the library and install its build dependencies
+./build_library.sh      # build and install it into install/
+./compile_harnesses.sh  # compile every harness in {HARNESS_SOURCE_DIR}/ into out/
+```
+
+`install/` already holds the library this run built, so `compile_harnesses.sh` works
+without re-running the first two steps.
+
+## Run it as an OSS-Fuzz project
+
+```bash
+docker build -t {analysis.project_name}:fuzz .
+docker run --rm --entrypoint bash {analysis.project_name}:fuzz -c compile
+```
+
+Or copy this directory into `oss-fuzz/projects/{analysis.project_name}` and use
+`infra/helper.py build_fuzzers {analysis.project_name}`.
+
+## Write a real harness
+
+`{harness_stub}` is a stub: it returns 0 without calling the library. Drop your own
+harness source into `{HARNESS_SOURCE_DIR}/` — `compile_harnesses.sh` compiles every
+`.c`/`.cc`/`.cpp`/`.cxx` file in there and names each binary after its source.
+
+Note that the link line was proven against the stub, so it confirms the static archives
+and their system dependencies link — not that the installed headers in `install/include`
+are usable.
+{_compile_commands_section(build_tree)}"""
+    path = output_path / "README.md"
+    path.write_text(text)
+    return path