0079. duolith build --report writes build-report.json and prints a summary
- Status: Accepted (Mik, 17 Nov 2026)
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval
- Planning item: WP13 (the build report),
docs/plan/contracts.md(Build report)
Context
The build report is a contract owned by the execution ladder and read by editors, the tool server and docs (docs/plan/contracts.md), at spec/schemas/build-report.schema.json, which was not written. People need to see which rung each screen landed on and why; tools need the same as JSON.
Decision
- **
duolith build [project] --report** writesbuild-report.jsonin the output folder and prints a table: one row per screen and component (rung, bytes, bytes rung 0 saved, bindings, events, file and route), each Rust module, warnings, and totals. With--jsonthe same report is thereportfield of the command's JSON answer. - **Its shape is
spec/schemas/build-report.schema.json, version 1:**target; the bytecode gate (decision 0076);screens(pages, layouts, the not-found screen) andcomponents(the project's and the kit parts it uses), each withkind,source,route,module,rung(0 or 1),script(none,source,bytecode),reason(why not rung 0),bytes,savedBytes,bindings,events,effects,modules,warnings;modules(each Rust module: rung 3, WebAssembly and loader bytes, used by); andtotals. camelCase, as every JSON the framework writes. - Counted as bindings: bound text, bound attributes and props,
class:conditions,<show>conditions, lists, andbind:pairs; events apart. Effects are imports of framework packages other than@duolith/clientand@duolith/kit(D21: one scope). Warnings are the ladder's (a constant list too long to write out); the analyzer has no warnings yet. pnpm checkbuilds every example with--reportand validates each report against the schema (packages/modules/test/build-report.test.ts).
Alternatives considered
| Option | Why not |
|---|---|
| Write the report outside the output folder | Two places to clean; the output folder is what a build produced |
A separate duolith report command | Builds the project twice to know sizes |
| Report gzip sizes | A compression library for one number; raw sizes compare the same way |
Consequences
- The schema is a contract: changing a field is a new
versionand a decision. - The report sits beside the site; a host serves it like any file, and it holds nothing private (file names and sizes).