unitbob 0.2.8 → 0.3.0

package/dist/verbs/validateBuild.js

@@ -0,0 +1,240 @@
+import { readHostSuiteOutputsPerBranch, readSuiteBuildRequest, } from "../files/suiteBuild.js";
+// The assignment, reduced to what a local check can compare against. Ids are
+// recovered from `contract_key`, which the server derives as `contract:<id>` and
+// both sides copy verbatim — so nothing here has to know whether this branch's
+// ids are called `interface_id` or `capability_id`.
+const CONTRACT_PREFIX = 'contract:';
+export function collectBuildProblems(request, outputs) {
+    const problems = [];
+    const branchFor = new Map(request.branches.map((branch) => [branch.suite_kind, branch]));
+    for (const output of outputs) {
+        // The host said plainly that it could not build this one. That is an answer,
+        // not a malformed answer, and the server records it as such.
+        if (output.build_error)
+            continue;
+        const branch = branchFor.get(output.suite_kind);
+        if (!branch)
+            continue; // reading the answer already refused this one
+        const add = (message) => { problems.push({ branch: output.suite_kind, message }); };
+        checkRunnerManifest(branch, output, add);
+        checkAssignment(branch, output, add);
+    }
+    return problems;
+}
+// After spec 32-5 the envelope comes down from the server inside the request, so
+// there is nothing here to derive — only to confirm the host copied it. This is
+// the field most likely to be rejected after all the work is done, which is
+// exactly why it is worth a second of checking beforehand.
+function checkRunnerManifest(branch, output, add) {
+    if (branch.runner_manifest === undefined)
+        return;
+    if (!sameJson(branch.runner_manifest, output.runner_manifest)) {
+        add('runner_manifest does not match the one the request issued. Copy it verbatim — the server ' +
+            'accepts only the exact combinations it named.\n' +
+            `      issued:   ${stableJson(branch.runner_manifest)}\n` +
+            `      answered: ${stableJson(output.runner_manifest)}`);
+    }
+}
+// Every assigned id accounted for exactly once, and every marker the one the
+// server minted. A marker the host invented or edited severs the only join
+// between a runner's output and the map, so it cannot be allowed to travel.
+function checkAssignment(branch, output, add) {
+    const assigned = assignedCases(branch.assignment);
+    if (assigned.length === 0) {
+        // An assignment with no cases in it is normal — a map with nothing to guard
+        // yet. An assignment that has content this walker could not read is not: the
+        // check would pass everything from then on and never say why. Fail open, but
+        // never fail open quietly.
+        if (hasContent(branch.assignment)) {
+            add('this branch\'s assignment could not be read, so its coverage was not checked here. ' +
+                'The server still checks it; if this persists the connector is older than the assignment format.');
+        }
+        return;
+    }
+    const metadata = output.test_metadata;
+    const entries = Array.isArray(metadata?.capabilities) ? metadata.capabilities : null;
+    if (!entries) {
+        add('test_metadata must carry a capabilities array, one entry per assigned id.');
+        return;
+    }
+    const byId = new Map(assigned.map((entry) => [entry.id, entry]));
+    const idKey = idKeyOf(branch.assignment, assigned);
+    const seen = new Map();
+    const suiteText = suiteBytes(output);
+    for (const entry of entries) {
+        const row = (entry ?? {});
+        const id = String(idKey ? row[idKey] ?? '' : '');
+        const expected = byId.get(id);
+        if (!expected) {
+            add(`test_metadata names "${id || '(no id)'}", which is not in this branch's assignment.`);
+            continue;
+        }
+        seen.set(id, (seen.get(id) ?? 0) + 1);
+        checkOneCase(row, id, expected, suiteText, add);
+    }
+    for (const [id, count] of seen) {
+        if (count > 1)
+            add(`${id} is answered ${count} times — every assigned id is answered exactly once.`);
+    }
+    const missing = assigned.filter((entry) => !seen.has(entry.id)).map((entry) => entry.id).sort();
+    if (missing.length > 0) {
+        add(`no answer for ${missing.length} assigned id(s): ${missing.join(', ')}.`);
+    }
+}
+function checkOneCase(row, id, expected, suiteText, add) {
+    const status = String(row.status ?? '');
+    if (status === 'unguarded') {
+        if (!String(row.reason ?? '').trim()) {
+            add(`${id} is unguarded but gives no business reason for it.`);
+        }
+        return;
+    }
+    if (status !== 'covered') {
+        add(`${id} must be answered "covered" or "unguarded" (got ${JSON.stringify(status)}).`);
+        return;
+    }
+    if (String(row.contract_key ?? '') !== expected.contract_key) {
+        add(`${id} carries contract_key ${JSON.stringify(row.contract_key)} — it must be copied verbatim as "${expected.contract_key}".`);
+    }
+    if (String(row.case_marker ?? '') !== expected.case_marker) {
+        add(`${id} carries case_marker ${JSON.stringify(row.case_marker)} — it must be copied verbatim as "${expected.case_marker}". Markers are never minted or edited locally.`);
+        return;
+    }
+    // Declared covered, but the marker never made it into a test name or a
+    // Gherkin tag. The server refuses this, and rightly: without the marker in the
+    // suite there is nothing to join a result to, so the capability would report
+    // as a mismatch rather than as the green it claims.
+    if (suiteText && !suiteText.includes(expected.case_marker)) {
+        add(`${id} is answered "covered", but its marker ${expected.case_marker} appears nowhere in the suite files.`);
+    }
+}
+// Which field names the id. Read off the *assignment*, where the answer is
+// exact: the id is already known (it is `contract_key` minus its prefix), so the
+// field holding it can be identified rather than guessed.
+//
+// An earlier version searched the host's answer for any string field whose value
+// happened to be an assigned id. That usually landed on the right key and could
+// just as well have landed on a `headline` that echoed the id. Neither branch's
+// key name is written down here either way — `interface_id` and `capability_id`
+// stay the server's business.
+function idKeyOf(assignment, cases) {
+    const ids = new Set(cases.map((entry) => entry.id));
+    let found = null;
+    const walk = (value) => {
+        if (found)
+            return;
+        if (Array.isArray(value)) {
+            value.forEach(walk);
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const row = value;
+        if (typeof row.contract_key === 'string') {
+            const id = row.contract_key.slice(CONTRACT_PREFIX.length);
+            for (const [key, candidate] of Object.entries(row)) {
+                if (key !== 'contract_key' && candidate === id && ids.has(id)) {
+                    found = key;
+                    return;
+                }
+            }
+        }
+        Object.values(row).forEach(walk);
+    };
+    walk(assignment);
+    return found;
+}
+// Does the assignment carry anything at all? Distinguishes "nothing to guard"
+// from "we could not read what was there".
+function hasContent(assignment) {
+    if (Array.isArray(assignment))
+        return assignment.length > 0;
+    if (!assignment || typeof assignment !== 'object')
+        return false;
+    return Object.values(assignment).some(hasContent);
+}
+// The assignment is an opaque body the server composed, so it is walked rather
+// than destructured: every object carrying a `contract_key` is one assigned
+// case, wherever the shape happens to nest it.
+function assignedCases(assignment) {
+    const found = [];
+    const walk = (value) => {
+        if (Array.isArray(value)) {
+            value.forEach(walk);
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        const row = value;
+        const key = row.contract_key;
+        const marker = row.case_marker;
+        if (typeof key === 'string' && key.startsWith(CONTRACT_PREFIX) && typeof marker === 'string') {
+            found.push({ id: key.slice(CONTRACT_PREFIX.length), contract_key: key, case_marker: marker });
+        }
+        Object.values(row).forEach(walk);
+    };
+    walk(assignment);
+    return found;
+}
+// Every byte of the branch's suite, main file and support files together, for
+// the "is the marker actually in there" check.
+function suiteBytes(output) {
+    const file = output.suite_file;
+    if (!file)
+        return '';
+    return [file.content, ...(Array.isArray(file.support_files) ? file.support_files.map((f) => f.content) : [])]
+        .filter((content) => typeof content === 'string')
+        .join('\n');
+}
+function sameJson(a, b) {
+    return stableJson(a) === stableJson(b);
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const object = value;
+        return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableJson(object[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+// Reads the task and the answer and reports every problem it can see. Reading
+// the answer is itself a check — safe paths, files that exist, a parseable
+// envelope — and it is done branch by branch, so a bad entry in one contributes
+// its problem and the other is still examined. Only the answer file as a whole
+// can stop the pass, because then there is no document left to read.
+export function validateBuildProblems(config) {
+    const request = readSuiteBuildRequest(config.projectRoot);
+    const { outputs, unreadable } = readHostSuiteOutputsPerBranch(request.output_path, request);
+    return [
+        ...unreadable.map((entry) => ({ branch: entry.suite_kind, message: entry.message })),
+        ...collectBuildProblems(request, outputs),
+    ];
+}
+// One branch's problems, for the line that reports it unpublished alongside its
+// peer. `put-suite-build` blocks per branch, so its message is per branch too.
+export function formatBranchProblems(messages) {
+    if (messages.length === 1)
+        return messages[0];
+    return `${messages.length} problems in this branch's answer:\n${messages.map((m) => `      - ${m}`).join('\n')}`;
+}
+// One report, not a queue of one-at-a-time discoveries. Fixing one thing to be
+// told the next costs a full round trip each time, and the round trip is the
+// expensive part.
+export function formatProblems(problems) {
+    const lines = problems.map((problem) => `  ${problem.branch}: ${problem.message}`);
+    return (`Your suite answer has ${problems.length} problem${problems.length === 1 ? '' : 's'}:\n` +
+        `${lines.join('\n')}\n` +
+        'Fix all of them, then answer again. The Unitbob server has the last word on ' +
+        'what it accepts; this check just finds the common problems in seconds instead ' +
+        'of after the whole build.\n');
+}
+export async function validateBuild(config, _args = [], deps) {
+    const stdout = deps?.stdout ?? process.stdout;
+    const problems = validateBuildProblems(config);
+    if (problems.length === 0) {
+        stdout.write('Your suite answer looks well-formed. Run `unitbob put-suite-build` to publish it.\n');
+        return;
+    }
+    throw new Error(formatProblems(problems));
+}

package/dist/wire.js

@@ -4,7 +4,12 @@ export class WireError extends Error {
 }
 // POST /repos/register — the linking bootstrap (spec 28). A standalone function
 // rather than a Wire method because at link time there is no Config yet: only a
-// server URL and the project's folder name. Idempotent on the server.
+// server URL and the project's folder name.
+//
+// It is no longer idempotent, and must not be called on an already-linked
+// project: since spec 33 every call mints a brand-new project. Looking one up by
+// folder name is exactly what used to let two people with a `myapp` write into
+// the same repository.
 export async function registerRepo(server, name) {
     const url = `${server}/repos/register`;
     let res;
@@ -33,7 +38,11 @@ export async function registerRepo(server, name) {
     if (typeof payload.id !== 'number' || !Number.isInteger(payload.id)) {
         throw new WireError(`POST ${url} returned a malformed payload: expected an integer id.`);
     }
-    return payload.id;
+    if (typeof payload.token !== 'string' || payload.token.length === 0) {
+        throw new WireError(`POST ${url} returned no project token — this Unitbob server is older than this connector. ` +
+            'Upgrade the server, or pin an older unitbob version.');
+    }
+    return { id: payload.id, token: payload.token };
 }
 export class Wire {
     config;
@@ -188,11 +197,16 @@ export class Wire {
         }
         return suite;
     }
+    // Every wire call carries the project's token (spec 33). Without it the brain
+    // answers 404 — never 403, which would confirm the project exists.
     async send(method, url, body) {
+        const headers = { authorization: `Bearer ${this.config.token}` };
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
         try {
             return await fetch(url, {
                 method,
-                headers: body === undefined ? undefined : { 'content-type': 'application/json' },
+                headers,
                 body: body === undefined ? undefined : JSON.stringify(body),
             });
         }
@@ -205,6 +219,14 @@ export class Wire {
     async ensureOk(res, what) {
         if (res.ok)
             return;
+        // A 404 on the wire means one of two things and there is no way to tell them
+        // apart from here — by design, since telling them apart is what would let a
+        // stranger discover which projects exist. Both have the same cure.
+        if (res.status === 404) {
+            throw new WireError(`This project is linked to a repository the server at ${this.config.server} does not have, ` +
+                'or the token in .unitbob.json does not open it. Delete .unitbob.json to link again ' +
+                '(the old project, along with its map and checks, stays where it is).');
+        }
         let detail = '';
         try {
             detail = (await res.text()).slice(0, 500);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "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": {