[ISSUE-14] Add BuildGraph, BuildSummary, and optional BuildReport

[Gonza10V]

Motivation

• Provide deterministic, offline-reporting artifacts derived from existing StageResult/FullBuildResult data so users can inspect what happened and why without coupling reporting to executor state or adding scheduling logic.
• Always produce a compact BuildSummary while making the detailed BuildReport opt-in via options to avoid unnecessary work in default runs.

Description

• Added BuildSummary and pure builder build_summary(result) with deterministic serializers to_dict(), to_json(), and to_markdown() that count final products, missing inputs, approvals, and warnings. (src/buildcompiler/reporting/summary.py)
• Implemented reporting-only BuildGraph with BuildGraphNode/BuildGraphEdge, deterministic dedupe, to_dict() and summary() and a pure build_graph(result) that derives nodes/edges from stage results, final products, missing inputs, and approvals without mutating results or scheduling. (src/buildcompiler/reporting/graph.py)
• Implemented BuildReport and supporting dataclasses (StageReportSection, RouteReport, RecommendedAction, DependencyChainStep) plus build_report(result, graph) which extracts selected/rejected routes from StageResult.protocol_artifacts, explains blockers, recommends next actions and produces dependency-chain + graph summary; serialization helpers are provided and outputs are deterministic. (src/buildcompiler/reporting/report.py)
• Wired reporting into the executor so FullBuildExecutor.execute(...) now: constructs a preliminary FullBuildResult, builds the reporting-only graph, always generates and attaches a BuildSummary, and attaches a BuildReport only when options.reporting.include_detailed_report is true; reporting exports were added to src/buildcompiler/reporting/__init__.py. (src/buildcompiler/execution/executor.py)
• Added focused unit tests and a reporting fixture covering summary, graph, report, and executor reporting integration. (tests/unit/reporting/*, tests/unit/execution/test_executor_reporting.py)

Testing

• Import smoke: python -c "from buildcompiler.reporting import BuildGraph, BuildSummary, BuildReport" — passed.
• Executor import: python -c "from buildcompiler.execution import FullBuildExecutor" — passed.
• Targeted pytest run: pytest tests/unit/reporting/test_summary.py tests/unit/reporting/test_graph.py tests/unit/reporting/test_report.py tests/unit/execution/test_executor_reporting.py tests/unit/execution/test_executor.py — all tests passed (12 passed).
• Attempted full automated workflow with uv to create venv and run tests: failed due to external network restriction when fetching optional dependency SBOLInventory (network 403), which is unrelated to these changes and prevented the uv-driven run; smallest successful command set was the direct pytest invocation above.
• Repo lint check ruff check . reported pre-existing repository issues outside the scope of this PR; those are deferred to separate cleanup.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

BuildCompiler/src/buildcompiler/reporting/report.py

Line 133 in b7f7214

if not result.missing_inputs and not result.required_approvals

Base executive summary on build status as well as blockers

This branch can emit a success-sounding summary even when the overall build failed, because it only checks missing_inputs and required_approvals. If a stage fails without producing blockers (for example, an execution error path with empty missing inputs), status can be failed while executive_summary says the build completed, which makes the detailed report internally inconsistent and misleading for users triaging failures.

---

BuildCompiler/src/buildcompiler/reporting/report.py

Line 147 in b7f7214

missing_inputs=[asdict(x) | {"source_stage": x.source_stage.value, "required_stage": str(x.required_stage)} for x in result.missing_inputs],

Serialize required_stage with enum values in report output

Using str(x.required_stage) produces enum repr strings like BuildStage.ASSEMBLY_LVL1 instead of the contract-style stage value (assembly_lvl1), while other stage fields in this report use .value. That creates inconsistent output formats for required_stage and forces downstream consumers to handle two representations ("fatal" vs enum repr) for the same field.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".