unitbob 0.2.6 → 0.2.7

package/dist/files/behavioral.js

@@ -1,4 +1,4 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
 // The behavioral suite lives under its own root: the main `.feature` plus its
@@ -34,6 +34,39 @@ export function materializeBehavioral(projectRoot, artifact, runner) {
     }
     return { mainPath };
 }
+// Everything under the behavioral root that the next materialization will
+// delete: it wipes every top-level entry outside the runner environment and
+// writes back only the files the answer listed, so a step file the answer forgot
+// is gone and its steps come back undefined — a harness break reported far from
+// its cause. One file per capability makes forgetting one much easier than a
+// single file for the whole product ever did.
+//
+// The whole root is walked, not just the directories the answer happens to use:
+// the file most likely to be forgotten is the one in a directory the answer
+// never mentions — `features/support/env.rb` is exactly that shape.
+export function filesLostOnMaterialize(projectRoot, artifact, runner) {
+    const behavioralRoot = join(projectRoot, BEHAVIORAL_DIR);
+    if (!existsSync(behavioralRoot))
+        return [];
+    const listed = new Set([artifact.path, ...(artifact.support_files ?? []).map((file) => file.path)]);
+    const runnerEntries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
+    return readdirSync(behavioralRoot)
+        .filter((entry) => !runnerEntries.has(entry))
+        .flatMap((entry) => filesUnder(projectRoot, `${BEHAVIORAL_DIR}/${entry}`))
+        .filter((path) => !listed.has(path))
+        .sort();
+}
+// The real files under `relative`. Symlinks are not followed: materialization
+// removes the link, not what it points at, and naming the target here would read
+// as a warning about a file that was never in danger.
+function filesUnder(projectRoot, relative) {
+    const stats = lstatSync(join(projectRoot, relative));
+    if (stats.isFile())
+        return [relative];
+    if (!stats.isDirectory())
+        return [];
+    return readdirSync(join(projectRoot, relative)).flatMap((entry) => filesUnder(projectRoot, `${relative}/${entry}`));
+}
 export function copyBehavioralRunnerEnvironment(sourceRoot, targetRoot, runner) {
     const entries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
     for (const entry of entries) {

package/dist/files/suiteBuild.js

@@ -1,6 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
 export function requestPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'request.json');
@@ -14,25 +14,40 @@ export function reviewOutputPath(projectRoot) {
 export function reviewRequestPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'review-request.json');
 }
+export function candidateRunPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'candidate-run.json');
+}
 export function writeBehavioralReviewRequest(projectRoot, output, candidateRun, knownDefectContext = { status: 'not_supplied' }, fixedCandidateRun) {
     const metadata = output.test_metadata;
     const candidateDigest = suiteCandidateDigest(output);
+    const evidence = {
+        candidate_digest: candidateDigest,
+        known_defect_context: knownDefectContext,
+        candidate_run: { candidate_digest: candidateDigest, ...candidateRun },
+        ...(fixedCandidateRun ? {
+            fixed_candidate_run: { candidate_digest: candidateDigest, ...fixedCandidateRun },
+        } : {}),
+    };
+    writeArtifact(candidateRunPath(projectRoot), evidence);
     const request = {
         candidate_digest: candidateDigest,
         suite_file: output.suite_file,
         capabilities: metadata?.capabilities,
         output_path: reviewOutputPath(projectRoot),
         known_defect_context: knownDefectContext,
-        candidate_run: { candidate_digest: candidateDigest, ...candidateRun },
-        ...(fixedCandidateRun ? {
-            fixed_candidate_run: { candidate_digest: candidateDigest, ...fixedCandidateRun },
+        // Only a supplied defect gives the reviewer something to read a run for.
+        ...(knownDefectContext.status === 'supplied' ? {
+            candidate_run: evidence.candidate_run,
+            ...(evidence.fixed_candidate_run ? { fixed_candidate_run: evidence.fixed_candidate_run } : {}),
         } : {}),
     };
-    const path = reviewRequestPath(projectRoot);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`);
+    writeArtifact(reviewRequestPath(projectRoot), request);
     return request;
 }
+function writeArtifact(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
 // The connector-owned runner strategy this branch selected. Reading it out of
 // the envelope is transport, like every other `runner_manifest` access in this
 // module — callers only ever get back the strategy name they dispatch on.
@@ -77,36 +92,79 @@ export function readBehavioralReview(projectRoot, output) {
     }
     const review = parseJson(readFileSync(path, 'utf8'), path);
     if (!review || review.candidate_digest !== suiteCandidateDigest(output)) {
-        throw new Error(`${path} does not review the current behavioral suite candidate.`);
+        throw new Error(`${path} ${staleReviewReason(projectRoot, review, output)}`);
     }
     if (!('bdd_quality_review' in review) || !('known_defect_probe' in review)) {
         throw new Error(`${path} must contain bdd_quality_review and known_defect_probe.`);
     }
-    const request = readBehavioralReviewRequest(projectRoot, output);
+    const evidence = readCandidateRunEvidence(projectRoot, output);
     return {
         ...review,
-        candidate_run: request.candidate_run,
-        ...(request.fixed_candidate_run ? { fixed_candidate_run: request.fixed_candidate_run } : {}),
+        candidate_run: evidence.candidate_run,
+        ...(evidence.fixed_candidate_run ? { fixed_candidate_run: evidence.fixed_candidate_run } : {}),
     };
 }
-function readBehavioralReviewRequest(projectRoot, output) {
-    const path = reviewRequestPath(projectRoot);
-    const request = parseJson(readFileSync(path, 'utf8'), path);
-    const run = request?.candidate_run;
+// Why a review does not bind — two different mistakes with one symptom.
+//
+// The likelier one, now that a branch may answer with a bare `{ path }`: the
+// review was right when it was written, and the candidate changed afterwards.
+// Editing one step file is enough, and nothing in the answer has to change for
+// it — so the digest moves with no visible cause, and "this does not review the
+// current candidate" sends the reader off to audit the reviewer instead of their
+// own last edit.
+//
+// The connector's own evidence file settles which mistake it was: it carries the
+// digest of the candidate that was actually run at review time. Agreeing with
+// the review and disagreeing with what is on disk now means the candidate moved
+// after the review. Otherwise the review really is about a different candidate.
+function staleReviewReason(projectRoot, review, output) {
+    const evidencePath = candidateRunPath(projectRoot);
+    if (review && existsSync(evidencePath)) {
+        const evidence = parseJson(readFileSync(evidencePath, 'utf8'), evidencePath);
+        if (evidence && evidence.candidate_digest === review.candidate_digest) {
+            return 'reviewed this suite as it stood at review time, and it has changed since — re-run ' +
+                '`unitbob suite-review-prepare` and have the reviewer look at the changed suite.';
+        }
+    }
+    return 'does not review the current behavioral suite candidate.';
+}
+// The runs the connector made of this exact candidate, and the defect choice
+// they were made under. One file, read on its own: the evidence the upload
+// carries must not depend on what the reviewer was shown, and reaching back into
+// the reviewer's request for the defect choice would have re-created exactly
+// that dependency.
+function readCandidateRunEvidence(projectRoot, output) {
+    const path = candidateRunPath(projectRoot);
+    if (!existsSync(path)) {
+        throw new Error(`${path} not found — run \`unitbob suite-review-prepare\` to record the candidate's run.`);
+    }
+    const file = parseJson(readFileSync(path, 'utf8'), path);
     const digest = suiteCandidateDigest(output);
-    if (!request || request.candidate_digest !== digest || !run || run.candidate_digest !== digest ||
-        typeof run.revision !== 'string' || !run.revision || typeof run.run_result !== 'string' || !run.run_result) {
+    if (!file || file.candidate_digest !== digest || !isRunEvidence(file.candidate_run, digest)) {
         throw new Error(`${path} has no connector runner evidence for the current behavioral candidate.`);
     }
-    const context = request.known_defect_context;
-    if (context?.status === 'supplied' && context.fixed_revision) {
-        const fixed = request.fixed_candidate_run;
-        if (!fixed || fixed.candidate_digest !== digest || fixed.revision !== context.fixed_revision ||
-            typeof fixed.run_result !== 'string' || !fixed.run_result) {
+    // Demanded, not defaulted. `readKnownDefectContext` reads a missing field as
+    // `not_supplied`, which is right for a file someone else may have written and
+    // wrong here: the connector writes this one itself, always with the choice it
+    // was given. Missing means the file is damaged, and taking it as "no defect
+    // was supplied" would turn that into a silently skipped fixed-revision check.
+    if (file.known_defect_context === undefined) {
+        throw new Error(`${path} records no known_defect_context — run \`unitbob suite-review-prepare\` again.`);
+    }
+    const context = readKnownDefectContext(file.known_defect_context, path);
+    if (context.status === 'supplied' && context.fixed_revision) {
+        const fixed = file.fixed_candidate_run;
+        if (!isRunEvidence(fixed, digest) || fixed?.revision !== context.fixed_revision) {
             throw new Error(`${path} has no connector runner evidence for fixed revision ${context.fixed_revision}.`);
         }
     }
-    return request;
+    return file;
+}
+function isRunEvidence(value, digest) {
+    const run = value;
+    return Boolean(run && run.candidate_digest === digest &&
+        typeof run.revision === 'string' && run.revision &&
+        typeof run.run_result === 'string' && run.run_result);
 }
 export function writeSuiteBuildRequest(projectRoot, branches, knownDefectContext = { status: 'not_supplied' }) {
     const request = {
@@ -173,9 +231,9 @@ export function readHostSuiteOutputs(path, request) {
         throw new Error(`${path} is malformed: expected a branches array, one entry per contract system.`);
     }
     const rootFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch.path_root]));
-    return branches.map((entry) => readBranch(entry, rootFor, path));
+    return branches.map((entry) => readBranch(entry, rootFor, path, request.project_root));
 }
-function readBranch(entry, rootFor, path) {
+function readBranch(entry, rootFor, path, projectRoot) {
     if (!entry || typeof entry !== 'object') {
         throw new Error(`${path} is malformed: each branch must be an object.`);
     }
@@ -201,32 +259,64 @@ function readBranch(entry, rootFor, path) {
     }
     return {
         suite_kind: suiteKind,
-        suite_file: resolveSuiteFile(branch.suite_file, root, path, suiteKind),
+        suite_file: resolveSuiteFile(branch.suite_file, root, path, suiteKind, projectRoot),
         runner_manifest: manifest,
         test_metadata: branch.test_metadata,
     };
 }
-// The host inlines every file's `content`; each path is checked safe under this
-// branch's root before anything is accepted.
-function resolveSuiteFile(file, root, path, suiteKind) {
+// Each path is checked safe under this branch's root before anything is
+// accepted. `content` may be inlined, but it does not have to be: the host wrote
+// and ran these files on disk before answering, so a bare `{ path }` means "the
+// file already under that path is the answer". Re-serializing a whole suite into
+// this JSON on every rebuild was the single largest cost in the build loop, and
+// the copy was never more trustworthy than the file that was actually executed.
+function resolveSuiteFile(file, root, path, suiteKind, projectRoot) {
     if (!file || typeof file !== 'object') {
         throw new Error(`${path}: the ${suiteKind} branch is missing suite_file.`);
     }
     const envelope = file;
-    const main = readOneFile(envelope, root, path, suiteKind, false);
+    const main = readOneFile(envelope, root, path, suiteKind, false, projectRoot);
     const support = Array.isArray(envelope.support_files)
-        ? envelope.support_files.map((entry) => readOneFile(entry, root, path, suiteKind, true))
+        ? envelope.support_files.map((entry) => readOneFile(entry, root, path, suiteKind, true, projectRoot))
         : [];
     return support.length > 0 ? { ...main, support_files: support } : main;
 }
-function readOneFile(file, root, path, suiteKind, support) {
+function readOneFile(file, root, path, suiteKind, support, projectRoot) {
     const filePath = typeof file.path === 'string' ? file.path : '';
     assertUnitbobPath(filePath, root);
     if (typeof file.content === 'string' && file.content.trim()) {
         return { path: filePath, content: file.content };
     }
-    const label = support ? 'support file' : 'suite_file';
-    throw new Error(`${path}: the ${suiteKind} ${label} at "${filePath}" has no inline content.`);
+    if (file.content !== undefined) {
+        throw new Error(`${path}: the ${suiteKind} ${fileLabel(support)} at "${filePath}" has empty content.`);
+    }
+    const onDisk = join(projectRoot, filePath);
+    if (!existsSync(onDisk)) {
+        throw new Error(`${path}: the ${suiteKind} ${fileLabel(support)} names "${filePath}", but no such file exists — write it before answering, or inline its content.`);
+    }
+    // `assertUnitbobPath` judges the path text; it cannot see that a safe-looking
+    // name is a link out of the suite root — nor that the directory holding it is.
+    // Inlined content could never reach outside the answer, so reading from disk
+    // is where that check has to be made: these bytes are uploaded.
+    //
+    // Only the project root is resolved, and the suite root is then joined onto it
+    // as text. Resolving the suite root too would let a linked `.unitbob/<kind>/`
+    // vouch for itself — every file under it resolves neatly under the link's own
+    // target. Resolving nothing at all would fail honest projects instead, because
+    // a macOS temp or home path is itself reached through a link.
+    // The wire's `path_root` carries a trailing slash; `join` keeps it.
+    const suiteRoot = join(realpathSync(projectRoot), root).replace(/[\\/]+$/, '');
+    if (!realpathSync(onDisk).startsWith(`${suiteRoot}${sep}`)) {
+        throw new Error(`${path}: the ${suiteKind} ${fileLabel(support)} at "${filePath}" resolves outside the suite root — suite files must be real files under it.`);
+    }
+    const content = readFileSync(onDisk, 'utf8');
+    if (!content.trim()) {
+        throw new Error(`${path}: the ${suiteKind} ${fileLabel(support)} at "${filePath}" is empty.`);
+    }
+    return { path: filePath, content };
+}
+function fileLabel(support) {
+    return support ? 'support file' : 'suite_file';
 }
 function parseJson(raw, path) {
     try {

package/dist/verbs/suiteReviewPrepare.js

@@ -2,7 +2,7 @@ import { execFileSync } from 'node:child_process';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { copyBehavioralRunnerEnvironment, materializeBehavioral } from "../files/behavioral.js";
+import { copyBehavioralRunnerEnvironment, filesLostOnMaterialize, materializeBehavioral, } from "../files/behavioral.js";
 import { runBddSuite } from "../runner/bdd.js";
 import { boundReport } from "../runner/boundReport.js";
 import { branchRunner, readHostSuiteOutputs, readSuiteBuildRequest, reviewRequestPath, writeBehavioralReviewRequest, } from "../files/suiteBuild.js";
@@ -20,6 +20,13 @@ export async function suiteReviewPrepare(config, _args = [], deps) {
     if (behavioral.build_error) {
         throw new Error(`The behavioral candidate could not be reviewed: ${behavioral.build_error.message}`);
     }
+    // Say this before the run, not after: the run materializes the answer, and
+    // that is where a forgotten file turns into undefined steps — by then it is
+    // already gone.
+    const lost = filesLostOnMaterialize(config.projectRoot, behavioral.suite_file, branchRunner(behavioral));
+    if (lost.length > 0) {
+        actual.stdout.write(`Warning: these files sit with the suite but are not in its answer, and running it will delete them: ${lost.join(', ')}.\n`);
+    }
     const candidateRun = await actual.runCandidate(config.projectRoot, behavioral);
     const fixedRevision = buildRequest.known_defect_context.status === 'supplied'
         ? buildRequest.known_defect_context.fixed_revision

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Unitbob connector — thin local hands for the Unitbob Rails brain. Owns no domain logic: it runs tools, relays bytes over the wire, and prints what the server returns.",
   "type": "module",
   "bin": {