build: the status row counts the work of the build

A clean build of xlings counted 1195 steps on its status row, of which 503 were
placements of the cache pass and 460 were dependency scans, and read 967/1195
when its first compile began. Ninja passes now have a kind. The cache pass is a
placement pass: its Cached lines are written as before and its steps are not
counted. The scans that wait on no action run in a pass of their own, before
the main pass, shown as Scanning f/t; a scan that waits on a package's prepare
or check action stays in the main pass, which keeps such an action from
holding back every compile. Building f/t is the main pass: 0/232 at the first
compile of the same build. The fast path runs the same passes. A failed scan
pass ends the build with its own output. A build of named goals scans in its
main pass.

Measured on xlings: the scan pass takes 20 ms on an edit and about 0.3 s on a
clean build, whose scans all ended in the first quarter second of the main
pass before.

Author: speak-agent

src/build/execute.cppm

@@ -1290,10 +1290,29 @@ std::optional<int> run_ninja_fast(const std::string& ninjaProgram,
     int status = 0;
     bool reported = false;
     const auto prefixes = read_ninja_command_prefixes(ninjaPath);
+    // The scan pass comes first here as on the full path (build wall-time
+    // plan, W2): the same passes, so the same counts.
+    std::optional<std::vector<std::string>> scanArgv;
+    {
+        std::ifstream in(ninjaPath, std::ios::binary);
+        std::string text{std::istreambuf_iterator<char>(in), {}};
+        if (text.find("\nbuild " + std::string(mcpp::build::kScannedGoal) + " : phony")
+            != std::string::npos) {
+            scanArgv = argv;
+            scanArgv->push_back(std::string(mcpp::build::kScannedGoal));
+        }
+    }
     if (reporting) {
         mcpp::build::progress::Build report(outputDir);
-        auto run = mcpp::build::run_ninja_reporting(argv, childEnv, std::chrono::milliseconds{0},
-                                                    report, verbose, prefixes);
+        mcpp::build::NinjaRun run;
+        if (scanArgv)
+            run = mcpp::build::run_ninja_reporting(*scanArgv, childEnv, std::chrono::milliseconds{0},
+                                                   report, verbose, prefixes,
+                                                   mcpp::build::progress::PassKind::Scan);
+        // A failed scan ends the build with its own output.
+        if (run.exitCode == 0 && !run.timedOut)
+            run = mcpp::build::run_ninja_reporting(argv, childEnv, std::chrono::milliseconds{0},
+                                                   report, verbose, prefixes);
         out = std::move(run.output);
         status = run.exitCode;
         reported = run.reported;
@@ -1305,7 +1324,9 @@ std::optional<int> run_ninja_fast(const std::string& ninjaProgram,
         // Nobody reads this ninja's progress: it reports no action start
         // (build progress design 2026-09-29, §6.4).
         childEnv.emplace_back(std::string(mcpp::build::progress::kStartsEnv), "");
-        auto r = mcpp::platform::process::capture_exec(argv, childEnv);
+        mcpp::platform::process::RunResult r;
+        if (scanArgv) r = mcpp::platform::process::capture_exec(*scanArgv, childEnv);
+        if (r.exit_code == 0) r = mcpp::platform::process::capture_exec(argv, childEnv);
         out = std::move(r.output);
         status = r.exit_code;
     }

src/build/ninja_backend.cppm

@@ -95,7 +95,14 @@ NinjaRun run_ninja_reporting(const std::vector<std::string>& argv,
                              std::chrono::milliseconds deadline,
                              mcpp::build::progress::Build& progress,
                              bool verbose,
-                             std::span<const std::string> commandPrefixes);
+                             std::span<const std::string> commandPrefixes,
+                             mcpp::build::progress::PassKind kind =
+                                 mcpp::build::progress::PassKind::Work);
+
+// The goal of the scan pass (build wall-time plan, W2): the dyndep file of
+// every unit whose scan waits on no action. Present in build.ninja when the
+// graph scans such a unit.
+inline constexpr std::string_view kScannedGoal = "_mcpp_scanned";
 
 // The step record of a plan (design §6.3): how the plan names its packages,
 // and which package each statement of `attribution` is for.
@@ -1175,10 +1182,11 @@ NinjaRun run_ninja_reporting(const std::vector<std::string>& argv,
                              std::chrono::milliseconds deadline,
                              mcpp::build::progress::Build& progress,
                              bool verbose,
-                             std::span<const std::string> commandPrefixes) {
+                             std::span<const std::string> commandPrefixes,
+                             mcpp::build::progress::PassKind kind) {
     NinjaRun run;
     for (auto& kv : progress.environment()) env.push_back(std::move(kv));
-    progress.pass_begin();
+    progress.pass_begin(kind);
     // The lines after `FAILED:` up to the next status line are the failed
     // step's command and output; the lines after a status line alone are a
     // successful step's output, which only --verbose shows (as before).
@@ -2692,6 +2700,22 @@ std::string emit_ninja_string(const BuildPlan& plan, std::string* placements,
         }
         append("\n");
 
+        // THE SCAN PASS'S GOAL (build wall-time plan, W2): the dyndep file of
+        // every unit whose scan waits on no action. A scan waits on its
+        // package's actions that precede compilation (`order_only_for`), and
+        // a pass over those scans would hold every compile behind the longest
+        // such action; they stay in the main pass.
+        {
+            std::string goal;
+            for (auto& ddi : ddi_paths) {
+                auto it = actionOutputsByPackage.find(ddiOwner[ddi]);
+                if (it != actionOutputsByPackage.end() && !it->second.empty()) continue;
+                goal += " " + ddi + ".dd";
+            }
+            if (!goal.empty())
+                append(std::format("build {} : phony{}\n\n", kScannedGoal, goal));
+        }
+
         // ── Phase 3: compile edges with per-file dyndep. ────────────────
         // Each compile edge references its OWN .dd file instead of a global one.
         // P2: module compile edges get a $bmi_out variable for BMI preservation.
@@ -4286,7 +4310,8 @@ std::expected<BuildResult, BuildError> NinjaBackend::build(const BuildPlan& plan
             std::vector<std::string> pre{ninjaProgram, "-C", plan.outputDir.string(),
                                          std::string(kStagedCacheGoal)};
             (void)run_ninja_reporting(pre, nenv, preDeadline, *opts.progress, opts.verbose,
-                                      command_prefixes(flags, plan));
+                                      command_prefixes(flags, plan),
+                                      mcpp::build::progress::PassKind::Placement);
         } else {
             std::vector<std::string> pre{ninjaProgram, "--quiet", "-C", plan.outputDir.string(),
                                          std::string(kStagedCacheGoal)};
@@ -4299,13 +4324,62 @@ std::expected<BuildResult, BuildError> NinjaBackend::build(const BuildPlan& plan
         stage("ninja-staged-cache");
     }
 
+    // THE SCANS THAT WAIT ON NO ACTION RUN IN A PASS OF THEIR OWN, after the
+    // cache pass and before the main pass (build wall-time plan, W2). The
+    // main pass's count then states the work of the build, its compiles,
+    // links, archives and actions, instead of 460 scans of which all end in
+    // the first quarter second; and every dyndep file of those units is
+    // current when the main pass loads them, as the cache pass arranges for
+    // its placements (ninja-build/ninja#2662). A build of named goals (a test,
+    // a target) scans in its main pass: a pass over every scan would scan
+    // units its goals never compile.
     bool buildTimedOut = false;
     bool reported = false;
     std::string out;
     int ninjaExit = 0;
+    bool scanFailed = false;
+    if (goalArg.empty()
+        && manifest.find("\nbuild " + std::string(kScannedGoal) + " : phony") != std::string::npos) {
+        const auto scanDeadline =
+            std::chrono::milliseconds(static_cast<long long>(opts.buildTimeoutSecs) * 1000);
+        std::vector<std::string> scan{ninjaProgram};
+        if (!opts.verbose && !opts.progress) scan.push_back("--quiet");
+        scan.insert(scan.end(), {std::string("-C"), plan.outputDir.string()});
+        if (opts.verbose) scan.push_back("-v");
+        scan.push_back(std::string(kScannedGoal));
+        if (opts.parallelJobs) scan.push_back(std::format("-j{}", opts.parallelJobs));
+        if (opts.progress) {
+            auto run = run_ninja_reporting(scan, nenv, scanDeadline, *opts.progress, opts.verbose,
+                                           command_prefixes(flags, plan),
+                                           mcpp::build::progress::PassKind::Scan);
+            if (run.exitCode != 0 || run.timedOut) {
+                out = std::move(run.output);
+                ninjaExit = run.exitCode;
+                buildTimedOut = run.timedOut;
+                reported = run.reported;
+                scanFailed = true;
+            }
+        } else {
+            auto scanEnv = nenv;
+            scanEnv.emplace_back(std::string(mcpp::build::progress::kStartsEnv), "");
+            auto cap = mcpp::platform::process::capture_exec_deadline(
+                scan, scanEnv, scanDeadline, &buildTimedOut);
+            if (cap.exit_code != 0 || buildTimedOut) {
+                out = std::move(cap.output);
+                ninjaExit = cap.exit_code;
+                scanFailed = true;
+            }
+        }
+        stage("ninja-scan");
+    }
+
+    // A failed scan ends the build with its own output: the main pass would
+    // run the failed step again and state its diagnostics a second time.
     const auto deadline =
         std::chrono::milliseconds(static_cast<long long>(opts.buildTimeoutSecs) * 1000);
-    if (opts.progress) {
+    if (scanFailed) {
+        // `out`, `ninjaExit`, `buildTimedOut` and `reported` are the scan's.
+    } else if (opts.progress) {
         auto run = run_ninja_reporting(nargv, nenv, deadline, *opts.progress, opts.verbose,
                                        command_prefixes(flags, plan));
         out = std::move(run.output);

src/build/progress.cppm

@@ -190,6 +190,8 @@ enum class ProgramOutcome { Ran, Cached, Failed };
 void open(bool verbose);
 // Closes it: the region is erased. Idempotent.
 void close();
+// The status row as the region would draw it now.
+std::string status_row();
 // The number of configurations the command builds: with more than one, a
 // package line names its configuration.
 void configurations(std::size_t n);
@@ -215,6 +217,16 @@ void defer_finished();
 void finish_deferred();
 
 // One build directory's ninja runs within this command.
+// WHAT A NINJA PASS IS FOR, AND WHETHER ITS STEPS ARE COUNTED (build wall-time
+// plan, W2). `Building f/t` states the work of the build: its compiles, links,
+// archives and actions. The cache pass places files the global cache serves,
+// which its `Cached` lines report; counted, its 503 placements and the 460
+// dependency scans of a clean build of xlings put the count at 81% when the
+// first compile began. A placement pass is therefore read but not counted, and
+// the scans that wait on no action run in a pass of their own, shown as
+// `Scanning f/t`.
+enum class PassKind { Placement, Scan, Work };
+
 class Build {
 public:
     // Opaque: its definition is this module's own.
@@ -234,8 +246,8 @@ public:
 
     // The environment ninja runs with: NINJA_STATUS and the start file.
     std::vector<std::pair<std::string, std::string>> environment() const;
-    // One ninja invocation.
-    void pass_begin();
+    // One ninja invocation, of the kind `kind` (see PassKind).
+    void pass_begin(PassKind kind = PassKind::Work);
     void status(const StatusLine& line);
     // A `FAILED: <outputs>` line. For the command's first failure, returns
     // the failed step's package as a line names it (empty when the step is
@@ -634,7 +646,7 @@ void record_action_start(std::string_view stamp) {
 // ─── The model ───────────────────────────────────────────────────────────
 
 // Not exported, and not TU-local either: `Build::Impl` holds them.
-enum class Phase { Planning, Programs, Building, Stopping, Checking };
+enum class Phase { Planning, Programs, Scanning, Building, Stopping, Checking };
 
 struct Program {
     std::string name;
@@ -672,6 +684,7 @@ struct Build::Impl {
     std::size_t finished = 0, total = 0;          // this pass
     std::optional<std::size_t> unstarted;         // this pass, from `%u`
     bool        inPass = false;
+    PassKind    kind = PassKind::Work;            // this pass; only Work passes count
     // The log of this pass.
     std::filesystem::path logPath;
     std::string logTail;             // the file's last bytes when the pass began
@@ -991,12 +1004,18 @@ std::string phase_status(Report& r, std::string_view cells) {
     std::string current;
     long long oldest = std::numeric_limits<long long>::max();
     std::size_t done = 0, total = 0, remaining = 0;
+    std::size_t scanDone = 0, scanTotal = 0;
     bool tail = true;   // every build in a pass has started its last step
     bool anyPass = false;
     for (auto const& b : live_builds(r)) {
-        done  += b->doneBefore + b->finished;
-        total += b->totalBefore + b->total;
-        if (b->inPass) {
+        const bool work = b->kind == PassKind::Work;
+        done  += b->doneBefore + (work ? b->finished : 0);
+        total += b->totalBefore + (work ? b->total : 0);
+        if (b->inPass && b->kind == PassKind::Scan) {
+            scanDone  += b->finished;
+            scanTotal += b->total;
+        }
+        if (b->inPass && work) {
             anyPass = true;
             if (!b->unstarted || *b->unstarted > 0) tail = false;
             else remaining += b->total > b->finished ? b->total - b->finished : 0;
@@ -1026,6 +1045,10 @@ std::string phase_status(Report& r, std::string_view cells) {
         counts = std::format("{}/{}", finishedPrograms, r.programs.size());
         break;
     }
+    case Phase::Scanning:
+        phase = "Scanning";
+        if (scanTotal > 0) counts = std::format("{}/{}", scanDone, scanTotal);
+        break;
     case Phase::Building:
     case Phase::Stopping:
         phase = r.phase == Phase::Building ? "Building" : "Stopping";
@@ -1066,8 +1089,9 @@ mcpp::ui::Frame frame() {
     } else if (r.animation) {
         std::size_t done = 0, total = 0;
         for (auto const& b : live_builds(r)) {
-            done  += b->doneBefore + b->finished;
-            total += b->totalBefore + b->total;
+            const bool work = b->kind == PassKind::Work;
+            done  += b->doneBefore + (work ? b->finished : 0);
+            total += b->totalBefore + (work ? b->total : 0);
         }
         const auto now = now_ms();
         screen::Input in;
@@ -1281,6 +1305,10 @@ void checking() {
     mcpp::ui::touch_region();
 }
 
+std::string status_row() {
+    return frame().status;
+}
+
 void defer_finished() {
     auto& r = report();
     std::lock_guard lock(r.m);
@@ -1394,18 +1422,23 @@ std::vector<std::pair<std::string, std::string>> Build::environment() const {
             {std::string(kStartsEnv), (impl_->dir / kStartsFile).string()}};
 }
 
-void Build::pass_begin() {
+void Build::pass_begin(PassKind kind) {
     auto& r = report();
     {
         std::lock_guard lock(r.m);
         auto& b = *impl_;
-        b.doneBefore  += b.finished;
-        b.totalBefore += b.total;
+        if (b.kind == PassKind::Work) {
+            b.doneBefore  += b.finished;
+            b.totalBefore += b.total;
+        }
+        b.kind = kind;
         b.finished = b.total = 0;
         b.unstarted.reset();
         b.passStart = now_ms();
         if (!r.buildStart) r.buildStart = b.passStart;
-        r.phase = Phase::Building;
+        // A placement pass keeps the phase it found (`Planning`).
+        if (kind == PassKind::Work) r.phase = Phase::Building;
+        else if (kind == PassKind::Scan) r.phase = Phase::Scanning;
         b.inPass = true;
         b.ends.clear();
         b.logPath = b.dir / ".ninja_log";

tests/unit/test_build_progress.cpp

@@ -390,6 +390,43 @@ TEST(ProgressModel, APackageTheCacheServesIsNamedCachedWithItsUnits) {
     EXPECT_EQ(count(out, "compat.ftxui"), 1u) << out;
 }
 
+// ─── What the count counts (build wall-time plan, W2) ────────────────────
+//
+// `Building f/t` states the work of the build. A clean build of xlings counted
+// 1195 steps, 503 of them placements of the cache pass and 460 dependency
+// scans, and read 967/1195 when its first compile began. A placement pass is
+// read but not counted, a scan pass shows as `Scanning f/t`, and the main pass
+// alone is `Building f/t`.
+TEST(ProgressModel, OnlyTheMainPassIsCountedAsBuilding) {
+    mcpp::ui::disable_color();
+    Tmp tmp;
+    Record rec;
+    rec.packages = {{"app", true, "app", 0, 1, "v0.1.0 (.)", "project"}};
+    rec.steps = 1;
+    Build b(tmp.path);
+    b.set_record(rec);
+    testing::internal::CaptureStdout();
+    b.pass_begin(mcpp::build::progress::PassKind::Placement);
+    b.status({503, 503, 1, 0, {}});
+    const auto placing = mcpp::build::progress::status_row();
+    b.pass_end();
+    b.pass_begin(mcpp::build::progress::PassKind::Scan);
+    b.status({200, 460, 2, 100, {}});
+    const auto scanning = mcpp::build::progress::status_row();
+    b.pass_end();
+    b.pass_begin(mcpp::build::progress::PassKind::Work);
+    b.status({1, 232, 3, 200, {}});
+    const auto building = mcpp::build::progress::status_row();
+    b.pass_end();
+    b.finish(true);
+    testing::internal::GetCapturedStdout();
+    EXPECT_EQ(placing.find("503"), std::string::npos) << placing;
+    EXPECT_NE(scanning.find("Scanning"), std::string::npos) << scanning;
+    EXPECT_NE(scanning.find("200/460"), std::string::npos) << scanning;
+    EXPECT_NE(building.find("Building"), std::string::npos) << building;
+    EXPECT_NE(building.find(" 1/232"), std::string::npos) << building;
+}
+
 TEST(ProgressModel, AFailureNamesItsPackageOnce) {
     mcpp::ui::disable_color();
     Tmp tmp;