unitbob 0.4.4 → 0.5.0

package/dist/verbs/runLocal.js

@@ -1,5 +1,5 @@
 import { branchRunner, readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
-import { spend } from "../files/budget.js";
+import { digestOf, failureSet, readRunState, rememberFailures } from "../runner/failureDigest.js";
 import { validateStack } from "../runner/precheck.js";
 import { runBddSuite } from "../runner/bdd.js";
 import { runStructuralByRunner } from "./run.js";
@@ -15,6 +15,8 @@ export async function runLocal(config, args = [], deps) {
     const request = readSuiteBuildRequest(config.projectRoot);
     const { outputs, unreadable } = readHostSuiteOutputsPerBranch(request.output_path, request);
     const wanted = selectBranches(request, args);
+    const previous = readRunState(config.projectRoot);
+    let stuck = false;
     for (const suiteKind of wanted) {
         d.stdout.write(`\n── ${suiteKind} ──\n`);
         // An entry that exists but will not parse is a different problem from an
@@ -27,16 +29,47 @@ export async function runLocal(config, args = [], deps) {
             continue;
         }
         const ran = await runOneBranch(config, d, suiteKind, outputs.find((entry) => entry.suite_kind === suiteKind));
-        // Only a run that happened spends a repair round. A branch with no entry
-        // written yet, or one the stack cannot execute, produced nothing to repair
-        // against — charging it would exhaust the budget on rounds that never
-        // examined the suite.
+        // A branch with no entry written yet, or one the stack cannot execute,
+        // produced nothing to compare: it is the ordinary state halfway through a
+        // build, not a repair loop going nowhere.
         if (!ran)
             continue;
-        // Kept as compatibility diagnostics only. The bounded repair role owns the
-        // mechanical ceiling; this counter never stops execution or classifies reds.
-        spend(config.projectRoot, `run-local:${suiteKind}`);
+        if (compareFailures(config, d, suiteKind, ran, previous[suiteKind]))
+            stuck = true;
     }
+    return stuck ? 1 : 0;
+}
+// Spec 34-6, criterion 3. The whole stop condition, and it stops the branch
+// rather than the worker: the set of failures belongs to the branch, and a
+// repair worker looking only at its own slice cannot see that the branch as a
+// whole has stopped moving.
+//
+// Returns true when this branch is the one that has stopped moving.
+function compareFailures(config, d, suiteKind, ran, before) {
+    const failures = failureSet(ran.runner, ran.result.report);
+    // No comparable set: the run produced no readable report, which is a harness
+    // problem the loop never reached. Forget the branch so the next run that does
+    // produce one is a first run again, rather than a match against a set from
+    // before the harness broke.
+    if (!failures) {
+        rememberFailures(config.projectRoot, suiteKind, undefined);
+        return false;
+    }
+    // Green. Nothing to be stuck on, and remembering an empty set would stop a
+    // branch that passes twice in a row.
+    if (failures.length === 0) {
+        rememberFailures(config.projectRoot, suiteKind, undefined);
+        return false;
+    }
+    const digest = digestOf(failures);
+    rememberFailures(config.projectRoot, suiteKind, digest);
+    if (digest !== before)
+        return false;
+    d.stdout.write(`\nStopping ${suiteKind}: it just failed the same ${failures.length} case(s) as the previous run, ` +
+        'down to the first line of every message. The edits since then changed nothing this run can see.\n' +
+        'Look at the failures yourself, replan the slice, or record the branch as a build_error. ' +
+        'Running it again unchanged prints this same line.\n');
+    return true;
 }
 // Which branches to run. No argument runs every branch the request asked for —
 // the same "one suite, one run" shape both recipes insist on, so the default
@@ -53,48 +86,49 @@ function selectBranches(request, args) {
     }
     return named;
 }
-// True when the runner actually executed the branch — which is what a repair
-// round is, and the only thing the caller charges the budget for.
+// Non-null when the runner actually executed the branch. Everything else — no
+// entry, a declared `build_error`, a stack that cannot run it — is a branch that
+// produced no result to compare against.
 async function runOneBranch(config, d, suiteKind, output) {
     // Nothing written for this branch yet. That is the ordinary state halfway
     // through a build, not an error — say what is missing and move to the peer.
     if (!output) {
         d.stdout.write(`Nothing to run: your answer has no entry for this branch yet. Write its suite under ` +
             `${branchRoot(config, suiteKind)} and add its entry to the answer, then run this again.\n`);
-        return false;
+        return null;
     }
     if (output.build_error) {
         d.stdout.write(`Not built, by your own answer: ${output.build_error.message}\n`);
-        return false;
+        return null;
     }
     let runner;
-    let suitePath;
+    let suitePaths;
     try {
         runner = branchRunner(output);
-        suitePath = mainPathOf(output);
+        suitePaths = artifactPathsOf(output);
     }
     catch (err) {
         d.stdout.write(`Cannot run this branch: ${err.message}\n`);
-        return false;
+        return null;
     }
     const check = d.validateStack(config.projectRoot, runner);
     if (!check.ok) {
         d.stdout.write(`Cannot run this branch: ${check.message ?? `this project does not match "${runner}".`}\n`);
-        return false;
+        return null;
     }
     let result;
     try {
         result =
             suiteKind === 'behavioral'
-                ? await d.runBehavioral(config.projectRoot, runner, suitePath)
-                : await d.runStructural(config.projectRoot, runner, suitePath);
+                ? await d.runBehavioral(config.projectRoot, runner, suitePaths[0])
+                : await d.runStructural(config.projectRoot, runner, suitePaths);
     }
     catch (err) {
         d.stdout.write(`The runner could not start: ${err.message}\n`);
-        return false;
+        return null;
     }
     d.stdout.write(report(result));
-    return true;
+    return { runner, result };
 }
 // The command first, and always — including on a green run. It is the answer to
 // "how do I run just this one file again", which is the question the whole
@@ -127,14 +161,26 @@ function outputTail(result) {
     const joined = bits.join('\n');
     return joined.length > OUTPUT_TAIL_CHARS ? joined.slice(-OUTPUT_TAIL_CHARS) : joined;
 }
-// The suite blob's own project-relative path, exactly as the runners expect it.
-function mainPathOf(output) {
+// The suite blob's own project-relative paths, exactly as the runners expect
+// them: the main file first, then every other file of the branch. The main file
+// stopped being the whole suite in spec 42, §6 — a branch is one file per
+// assignment now — and running it alone would exercise a fraction of what the
+// answer claims to guard.
+//
+// The behavioral runners are given the main `.feature` and find the rest
+// themselves: all three are pointed at the directory (`bdd.ts`), which is why a
+// multi-file behavioral branch already worked before this spec.
+function artifactPathsOf(output) {
     const file = output.suite_file;
     const path = file?.path;
     if (typeof path !== 'string' || !path) {
         throw new Error('this branch names no suite file to run.');
     }
-    return path;
+    const support = Array.isArray(file?.support_files) ? file.support_files : [];
+    const rest = support
+        .map((entry) => entry?.path)
+        .filter((candidate) => typeof candidate === 'string' && candidate.length > 0);
+    return [path, ...rest];
 }
 function branchRoot(config, suiteKind) {
     const request = readSuiteBuildRequest(config.projectRoot);

package/dist/verbs/suitePrepare.js

@@ -1,11 +1,11 @@
-import { clearSpending } from "../files/budget.js";
+import { clearRunState } from "../runner/failureDigest.js";
 import { materializeHelper } from "../files/guardrails.js";
 import { materializeBehavioralWorld } from "../files/behavioral.js";
 import { recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { bootCheck, SIGNAL_STRENGTH } from "../runner/bootcheck.js";
-import { anyStackPrecheck, detectBddRunner, detectStructuralRunner } from "../runner/precheck.js";
+import { anyStackPrecheck, detectBddRunner, detectStructuralRunner, runnerReadyPrecheck } from "../runner/precheck.js";
 import { selectRunnerEnvelope, withInstalledRunnerVersion } from "../runner/manifest.js";
-import { ensureRunner } from "../runner/provision.js";
+import { ensureRunner, ensureStructuralRunner } from "../runner/provision.js";
 import { probeBehavioralWorld } from "../runner/worldProbe.js";
 import { Wire } from "../wire.js";
 // The complete envelope for one branch, or null when this machine cannot
@@ -46,7 +46,8 @@ function runnerEnvelopeFor(packet, runner, projectRoot) {
         : envelope;
 }
 // Confirm at least one supported stack is present, materialize the Ruby boot
-// helper a generated RSpec suite would require, then fetch both peer assignments
+// helper an RSpec suite would need — only in a Ruby project — then fetch both
+// peer assignments
 // (spec 32) and each branch's recipe, and write the host's task to
 // `.unitbob/suite-build/request.json`. No model is called and no source is read
 // here — that is the host's job, framed by the two generation recipes. An
@@ -60,8 +61,10 @@ export async function suitePrepare(config, args = [], deps) {
         getRecipe: (name) => wire.getRecipe(name),
         getSuitePacketsBatch: () => wire.getSuitePacketsBatch(),
         precheck: anyStackPrecheck,
+        confirmRunner: (projectRoot, runner) => runnerReadyPrecheck(projectRoot, runner),
         bootCheck: (projectRoot, runner) => bootCheck(projectRoot, runner),
         ensureRunner: deps?.ensureRunner ?? ensureRunner,
+        ensureStructuralRunner: deps?.ensureStructuralRunner ?? ensureStructuralRunner,
         worldProbe: deps?.worldProbe ?? probeBehavioralWorld,
         runnerEnvelope: runnerEnvelopeFor,
         stdout: process.stdout,
@@ -70,7 +73,36 @@ export async function suitePrepare(config, args = [], deps) {
     const check = actual.precheck(config.projectRoot);
     if (!check.ok)
         throw new Error(check.message ?? 'Unsupported runtime.');
-    materializeHelper(config.projectRoot);
+    // Ruby only. This wrote `unitbob_helper.rb` and `rspec.opts` into every
+    // project it touched, so a Flask app and a NestJS app each came away with a
+    // Ruby file they never asked for and cannot run — the product leaving another
+    // stack's litter in someone's repository.
+    if (detectStructuralRunner(config.projectRoot) === 'rspec')
+        materializeHelper(config.projectRoot);
+    // The stack is known; now make it runnable. A vibecoder who has never
+    // installed a test runner is the ordinary customer, not an edge case, so the
+    // runner (and, where the language allows it, the application's own
+    // dependencies) is installed under `.unitbob/` rather than reported as a
+    // reason they cannot use the product. Nothing in their project is written to.
+    //
+    // A project that already has its runner is left completely alone — see
+    // `ensureStructuralRunner` — so this costs nothing on a set-up machine.
+    const setupNotices = [];
+    if (check.runner) {
+        const provisioned = await actual.ensureStructuralRunner(config.projectRoot, check.runner);
+        if (provisioned.status === 'fixable') {
+            const steps = provisioned.checklist?.length ? `\n  - ${provisioned.checklist.join('\n  - ')}` : '';
+            throw new Error(`The ${check.runner} runner could not be installed under .unitbob/, and nothing can run without it: ` +
+                `${provisioned.message ?? 'provisioning failed'}${steps}\nNothing was written and nothing was uploaded.`);
+        }
+        setupNotices.push(...(provisioned.checklist ?? []));
+        // Confirm rather than assume. Provisioning reporting success and the runner
+        // actually being startable are two different facts, and this is the cheap
+        // one to check before a whole generation is built on it.
+        const ready = actual.confirmRunner(config.projectRoot, check.runner);
+        if (!ready.ok)
+            throw new Error(ready.message ?? `The ${check.runner} runner is not available.`);
+    }
     // Spec 32-6. Before anything is fetched or written, find out whether the suite
     // would get off the ground at all. It runs here, after the boot helper exists
     // and before the network, so a project whose suite cannot start costs one
@@ -153,13 +185,11 @@ export async function suitePrepare(config, args = [], deps) {
         throw new Error(`No suite branch can be built this run:\n${blockedNotices.join('\n')}\nNothing was written and nothing was uploaded.`);
     }
     const request = writeSuiteBuildRequest(config.projectRoot, branches, defectContext);
-    // A new request is a new build, and a new build starts on the whole budget
-    // (spec 34-2). Said out loud, because re-running this verb is a documented
-    // step of the loop — the fixable-runner path below ends by asking for it — so
-    // a reset that happened silently would be a ceiling that quietly is not one.
-    if (clearSpending(config.projectRoot)) {
-        actual.stdout.write('Starting a fresh build: the review and run counts from the previous one are cleared.\n');
-    }
+    // A new request is a new build, and a new build has no previous run to be
+    // stuck against (spec 34-6, criterion 3). Re-running this verb is a documented
+    // step of the loop, so a failure set remembered from the build before it would
+    // stop a branch that has not run once yet.
+    clearRunState(config.projectRoot);
     const kinds = branches.map((branch) => branch.suite_kind).join(' and ');
     const nextCommand = branches.some((branch) => branch.suite_kind === 'behavioral')
         ? '`unitbob suite-review-prepare` before upload'
@@ -172,6 +202,9 @@ export async function suitePrepare(config, args = [], deps) {
         `then run ${nextCommand}.\n`);
     // A fixable runner blocker is not a failure: the structural suite still builds this run. Tell the
     // vibecoder the one command that unblocks the behavioral peer, then re-run suite-prepare.
+    if (setupNotices.length > 0) {
+        actual.stdout.write('\nOne setup step is worth knowing about before you generate:\n  - ' + setupNotices.join('\n  - ') + '\n');
+    }
     if (fixableNotices.length > 0) {
         actual.stdout.write('\nBehavioral suite skipped this run — its runner or connector-owned World profile is not ready. ' +
             'This is a fixable setup step, not a build failure, and it does not affect the structural suite:\n' +
@@ -226,9 +259,10 @@ function bootFinding(boot, runner) {
     // the one the vibecoder can paste into a search.
     const next = boot.cause === 'defect_in_code'
         ? 'Fix that, then run `unitbob suite-prepare` again.'
-        : "Unitbob does not install your project's own dependencies — that would rewrite your Gemfile.lock " +
-            'or package-lock.json. Run the install your project needs (`bundle install`, `npm install`, ' +
-            '`pip install -r requirements.txt`), then run `unitbob suite-prepare` again.';
+        : 'Unitbob installs the runner, and your declared dependencies with it, into `.unitbob/runners/` — ' +
+            'it never writes to your project. Something outside that file is still missing here. Run the ' +
+            'install your project needs (`bundle install`, `npm install`, `pip install -r requirements.txt`), ' +
+            'then run `unitbob suite-prepare` again.';
     return (`${headline}\n\n` +
         `  ${boot.message}\n\n` +
         `${boot.detail}\n\n` +

package/dist/verbs/suiteReviewPrepare.js

@@ -6,7 +6,6 @@ import { copyBehavioralRunnerEnvironment, filesLostOnMaterialize, materializeBeh
 import { runBddSuite } from "../runner/bdd.js";
 import { boundReport } from "../runner/boundReport.js";
 import { branchRunner, readHostSuiteOutputs, readSuiteBuildRequest, reviewRequestPath, writeBehavioralReviewRequest, } from "../files/suiteBuild.js";
-import { spend } from "../files/budget.js";
 export async function suiteReviewPrepare(config, _args = [], deps) {
     const actual = {
         runCandidate: runCandidate,
@@ -38,27 +37,6 @@ export async function suiteReviewPrepare(config, _args = [], deps) {
     const request = writeBehavioralReviewRequest(config.projectRoot, behavioral, candidateRun, buildRequest.known_defect_context, fixedCandidateRun);
     actual.stdout.write(`Behavioral review request written to ${reviewRequestPath(config.projectRoot)}\n`);
     actual.stdout.write(`Next: have an independent reviewer inspect this exact candidate and write bdd_quality_review and known_defect_probe to ${request.output_path}, then run \`unitbob put-suite-build\`.\n`);
-    // Counted after the request is written, never before it. Refusing the round
-    // would rebuild the autobrella deadlock on a different number: the branch
-    // could not publish, so the work would be lost again for the sake of the
-    // ceiling meant to protect it. What the ceiling buys is a sentence.
-    const round = spend(config.projectRoot, 'review_rounds');
-    const budget = buildRequest.budget;
-    if (budget && round > budget.review_rounds) {
-        actual.stdout.write(lastRoundNotice(round, budget.review_rounds));
-    }
-}
-// Says what to do, not that something is forbidden. This is only sayable because
-// spec 34-2 already made an imperfect suite publishable: before it, "publish what
-// you have" was not available to the reviewer at all, and the only way to record
-// a bad Scenario was to take the branch down.
-function lastRoundNotice(round, allowed) {
-    return (`\nThis is review round ${round}; the budget for this build was ${allowed}. Treat it as the last round ` +
-        'and publish what you have.\n' +
-        'A Scenario the reviewer still objects to does not hold the branch back: it is recorded with ' +
-        '`verdict: "does_not_pass"` and a `reviewer_objection_text` saying what is wrong, the branch publishes, ' +
-        'and the objection is read afterwards by the operator. Another round of rewriting buys less than ' +
-        'publishing the objection does.\n');
 }
 async function runCandidate(projectRoot, output, revision) {
     if (revision)