speccle 0.12.0 → 0.16.0

package/dist/render.js

@@ -29,11 +29,65 @@ export function renderSkillsInit(report) {
     lines.push("these are generated files — commit them; re-run `speccle init` to refresh");
     return lines.join("\n");
 }
+export function renderLensesInit(report) {
+    const lines = [`vendored ${plural(report.lenses.length, "lens", "lenses")} into ${report.dir}/`];
+    for (const { name, action } of report.lenses) {
+        const verb = action === "written" ? "wrote" : action;
+        lines.push(`  ${verb.padEnd(9)} ${name}`);
+    }
+    lines.push("");
+    lines.push("the baseline lenses are Speccle's — refreshed each run; house-conventions.md is yours to author");
+    return lines.join("\n");
+}
+export function renderReviewInit(report) {
+    const verb = report.action === "written" ? "wrote" : "refreshed";
+    const lines = [
+        `${verb} ${report.file} — pinned to speccle@${report.pin}`,
+        "",
+        `the driver is opt-in and needs a metered ${API_KEY_SECRET} repo secret; add it before the`,
+        "next pull request, or the review step fails with no key",
+        "",
+        "it finds and comments — fixes come back through the local `review` skill",
+        "whether the risk gate blocks a merge is branch protection: GitHub's setting, your call",
+    ];
+    if (report.action === "refreshed" && !report.movedPin) {
+        lines.splice(1, 0, "  (unchanged — the workflow already pinned this version)");
+    }
+    return lines.join("\n");
+}
+export function renderReviewRun(report) {
+    if (report.outcome === "already-reviewed") {
+        return join(`${report.repo}#${report.pr} — already reviewed by this driver, so nothing was posted`, "comment `@review` on the pull request to run again");
+    }
+    const lines = [];
+    const findings = report.findings.length;
+    lines.push(`${report.repo}#${report.pr} at ${report.headSha.slice(0, 7)} — ${plural(report.lenses.length, "lens", "lenses")} ran, ${plural(findings, "finding")}`);
+    for (const lens of report.lenses) {
+        lines.push(`  ${String(lens.findings).padStart(3)}  ${lens.name}`);
+    }
+    for (const skip of [...report.skippedLenses, ...report.skippedFiles]) {
+        lines.push(`  skipped  ${skip.name} — ${skip.reason}`);
+    }
+    lines.push("");
+    if (findings > 0) {
+        lines.push(`${report.comments} inline, ${report.unplaced} unplaced in the summary`);
+    }
+    const verdict = report.risk;
+    lines.push(verdict === null
+        ? `risk not computed — no shared history with ${report.base}`
+        : verdict.humanRequired
+            ? `risk ${verdict.score} ≥ threshold ${verdict.threshold} — human required; the gate step fails`
+            : `risk ${verdict.score} < threshold ${verdict.threshold} — the gate step passes`);
+    lines.push(report.outcome === "dry-run" ? "dry run — nothing was posted" : "posted one review");
+    return lines.join("\n");
+}
 export function renderDoctor(report) {
     const lines = [
         `speccle ${report.cli}`,
         "",
-        `skills   ${describeSkills(report.skills)}`,
+        `skills   ${describePayload(report.skills, "materialized")}`,
+        `lenses   ${describePayload(report.lenses, "vendored")}`,
+        `driver   ${describeDriver(report.driver)}`,
         `stack    ${describeStack(report.stack)}`,
     ];
     if (report.stack.status === "drift") {
@@ -45,7 +99,11 @@ export function renderDoctor(report) {
         }
     }
     lines.push("");
-    if (report.skills.status === "absent" && report.stack.status === "absent") {
+    const allAbsent = report.skills.status === "absent" &&
+        report.lenses.status === "absent" &&
+        report.driver.status === "absent" &&
+        report.stack.status === "absent";
+    if (allAbsent) {
         lines.push("Speccle is not set up here — run `speccle init`");
     }
     else if (report.ok) {
@@ -56,18 +114,37 @@ export function renderDoctor(report) {
     }
     return lines.join("\n");
 }
-function describeSkills(skills) {
-    switch (skills.status) {
+function describePayload(payload, verb) {
+    switch (payload.status) {
         case "current":
-            return `current (${skills.bundled})`;
+            return `current (${payload.bundled})`;
         case "stale":
-            return `stale — committed ${skills.recorded}, this CLI ships ${skills.bundled}`;
+            return `stale — committed ${payload.recorded}, this CLI ships ${payload.bundled}`;
         case "ahead":
-            return `ahead — committed ${skills.recorded} is newer than this CLI (${skills.bundled})`;
+            return `ahead — committed ${payload.recorded} is newer than this CLI (${payload.bundled})`;
         case "unstamped":
             return "present but unversioned — re-run `speccle init` to record the version";
         case "absent":
-            return "not materialized — run `speccle init`";
+            return `not ${verb} — run \`speccle init\``;
+    }
+}
+/**
+ * The driver's own arm, because its two ends differ from a vendored payload's: absent means
+ * the repo never opted into a metered CI driver — a choice, not a gap to fix — and every
+ * remedy is `review init`, which is also the only thing that moves the pin.
+ */
+function describeDriver(driver) {
+    switch (driver.status) {
+        case "current":
+            return `current (${driver.bundled})`;
+        case "stale":
+            return `stale — the workflow pins ${driver.recorded}, this CLI is ${driver.bundled}; re-run \`speccle review init\``;
+        case "ahead":
+            return `ahead — the workflow pins ${driver.recorded}, newer than this CLI (${driver.bundled})`;
+        case "unstamped":
+            return "present but unpinned — re-run `speccle review init` to pin a version";
+        case "absent":
+            return "not installed — opt in with `speccle review init`";
     }
 }
 function describeStack(stack) {
@@ -90,6 +167,24 @@ export function renderUpdate(report) {
     else {
         lines.push(`skills   ${report.skills.from ?? "unversioned"} → ${report.skills.to} — review & commit the diff`);
     }
+    if (report.lenses.from === null) {
+        lines.push(`lenses   vendored at ${report.lenses.to} — new; review & commit the diff`);
+    }
+    else if (report.lenses.from === report.lenses.to) {
+        lines.push(`lenses   already at ${report.lenses.to} — refreshed in place; review the diff`);
+    }
+    else {
+        lines.push(`lenses   ${report.lenses.from} → ${report.lenses.to} — review & commit the diff`);
+    }
+    if (report.driver.to === null) {
+        lines.push("driver   not installed — opt in with `speccle review init`");
+    }
+    else if (report.driver.from === report.driver.to) {
+        lines.push(`driver   already pinned to ${report.driver.to} — rewritten in place`);
+    }
+    else {
+        lines.push(`driver   ${report.driver.from ?? "unpinned"} → ${report.driver.to} — review & commit the diff`);
+    }
     if (report.stack.status === "absent") {
         lines.push("stack    not provisioned — run `speccle strength init`");
     }
@@ -128,21 +223,162 @@ function describeReport(check) {
         return `${check.path} — stale (${check.staleAgainst} is newer)`;
     return `${check.path} — fresh`;
 }
+import { API_KEY_SECRET } from "./reviewinit.js";
+export function renderVerify(report) {
+    const enforced = report.checks.filter((check) => check.status !== "inactive");
+    if (enforced.length === 0) {
+        const scanned = plural(report.changed.length, "changed file");
+        const authored = report.checks.length === 0 ? "no checks authored" : "no check applied";
+        return join(changeSetLine(report), `${authored} — ${scanned} scanned`);
+    }
+    const lines = [];
+    const header = changeSetLine(report);
+    if (header !== undefined)
+        lines.push(header, "");
+    for (const check of enforced.filter((check) => check.status === "breach")) {
+        lines.push(renderBreach(check));
+    }
+    if (lines.length > 0)
+        lines.push("");
+    const breaches = report.breaches;
+    const checks = plural(enforced.length, "check");
+    lines.push(report.clean ? `${checks}, clean` : `${checks}, ${plural(breaches, "breach", "breaches")}`);
+    return lines.join("\n");
+}
+function renderBreach(check) {
+    const lines = [`${check.id}  ${check.message}`];
+    for (const offender of check.offenders ?? [])
+        lines.push(`  ${offender}`);
+    if (check.because !== undefined)
+        lines.push(`  because ${check.because}`);
+    return lines.join("\n");
+}
+export function renderRisk(report) {
+    const lines = [];
+    const header = changeSetLine(report);
+    if (header !== undefined)
+        lines.push(header, "");
+    for (const signal of report.signals) {
+        lines.push(`${signal.id}  +${signal.weight}  ${signal.reason}`);
+        for (const item of signal.evidence)
+            lines.push(`  ${item}`);
+        if (signal.because !== undefined)
+            lines.push(`  because ${signal.because}`);
+    }
+    if (report.signals.length > 0)
+        lines.push("");
+    else
+        lines.push(`no risk signals fired — ${plural(report.changed.length, "changed file")} scanned`);
+    lines.push(report.humanRequired
+        ? `score ${report.score} ≥ threshold ${report.threshold} — human required, review stops at findings`
+        : `score ${report.score} < threshold ${report.threshold} — review may fix and report`);
+    // Legibility (ADR-0041): the computed score is a floor a risk lens may raise, never lower.
+    lines.push("this score is a floor — a risk lens may escalate it, never lower it");
+    return lines.join("\n");
+}
+export function renderCalibrateRecord(report) {
+    const entry = report.entry;
+    const floor = `score ${entry.score} vs threshold ${entry.threshold}`;
+    const gate = entry.humanRequired ? " — floor required a human" : "";
+    const escalated = entry.escalated ? " — a lens escalated" : "";
+    const verdict = `${entry.verdict.neededHuman ? "needed a human" : "no human needed"}, ${entry.verdict.foundReal ? "found something real" : "found nothing real"}`;
+    const lines = [
+        `recorded ${report.file} — ${plural(report.count, "entry", "entries")}`,
+        `  ${floor}${gate}${escalated}`,
+        `  verdict: ${verdict}`,
+    ];
+    if (entry.signals.length > 0)
+        lines.push(`  signals: ${entry.signals.join(", ")}`);
+    return lines.join("\n");
+}
+export function renderCalibrateReport(report) {
+    if (report.count === 0) {
+        return "no calibration entries yet — review some changes to build the record";
+    }
+    const changes = plural(report.count, "reviewed change");
+    const lines = [
+        `${changes} — ${report.neededByHuman} needed a human, floor gated ${report.gatedByFloor}`,
+    ];
+    if (report.floorMisses > 0) {
+        lines.push(`  ${plural(report.floorMisses, "floor miss", "floor misses")} — needed a human the floor did not catch`);
+    }
+    if (report.overSupervised > 0) {
+        lines.push(`  ${report.overSupervised} over-supervised — floor required a human the verdict did not`);
+    }
+    if (report.signals.length > 0) {
+        lines.push("");
+        const width = Math.max(...report.signals.map((signal) => signal.id.length));
+        for (const signal of report.signals) {
+            const note = signal.neverUseful
+                ? " — never on a change that mattered"
+                : signal.firedOnEveryNeeded
+                    ? " — on every change that needed a human"
+                    : "";
+            lines.push(`  ${signal.id.padEnd(width)}  ${signal.firedOnMattered}/${signal.fired} mattered${note}`);
+        }
+    }
+    lines.push("");
+    lines.push("proposals — evidence, not instructions (only a human reduces supervision):");
+    for (const proposal of report.proposals)
+        lines.push(`  ${proposal}`);
+    return lines.join("\n");
+}
+/** The route with its artefact, or the honest one-off — how a remedy's prevention reads on one line. */
+function remedyDestination(route, artefact) {
+    return route === "none" ? "one-off — no prevention artefact" : `${route} → ${artefact}`;
+}
+export function renderRemedyRecord(report) {
+    const entry = report.entry;
+    const lines = [
+        `recorded ${report.file} — ${plural(report.count, "remedy", "remedies")}`,
+        `  ${entry.class}: ${entry.finding}`,
+        `  fix: ${entry.fix}`,
+        `  remedy: ${remedyDestination(entry.route, entry.artefact)}`,
+    ];
+    if (entry.note !== undefined)
+        lines.push(`  note: ${entry.note}`);
+    return lines.join("\n");
+}
+export function renderRemedyRecall(report) {
+    if (report.count === 0) {
+        return `no remedy record yet — nothing to recall for "${report.query}"`;
+    }
+    if (report.matches.length === 0) {
+        const onRecord = plural(report.count, "remedy", "remedies");
+        return `no prior remedy for "${report.query}" — route it fresh, then record it (${onRecord} on record)`;
+    }
+    const found = plural(report.matches.length, "prior remedy", "prior remedies");
+    const lines = [`${found} for "${report.query}" — reuse to fix consistently:`];
+    for (const entry of report.matches) {
+        lines.push("");
+        lines.push(`  ${entry.class}  (${entry.at})`);
+        lines.push(`    finding: ${entry.finding}`);
+        lines.push(`    fix: ${entry.fix}`);
+        lines.push(`    remedy: ${remedyDestination(entry.route, entry.artefact)}`);
+        if (entry.note !== undefined)
+            lines.push(`    note: ${entry.note}`);
+    }
+    return lines.join("\n");
+}
 export function renderClaims(report) {
     if (report.features.length === 0)
         return "No SPEC.md files found.";
     const idWidth = Math.max(...report.features.flatMap((f) => f.criteria.map((c) => c.id.length)));
+    // Only a mixed pass needs to say which dialect read which slice; naming the one dialect
+    // above every spec in the common case is noise the footer already carries.
+    const mixed = report.dialects.length > 1;
     const lines = [];
     for (const feature of report.features) {
-        lines.push(feature.spec);
+        lines.push(mixed ? `${feature.spec}  (${feature.dialect})` : feature.spec);
         for (const c of feature.criteria) {
             const status = c.claimed ? plural(c.tests.length, "test name") : "unclaimed";
             lines.push(`  ${c.id.padEnd(idWidth)}  ${status.padEnd(13)}  ${c.statement}`);
         }
         lines.push("");
     }
+    const dialects = report.dialects.join(", ");
     if (report.testFiles.length === 0) {
-        lines.push(`no test files matched the ${report.dialect} dialect`);
+        lines.push(`no test files matched the ${dialects} dialect${mixed ? "s" : ""}`);
         lines.push("");
     }
     if (report.unclaimed.length > 0) {
@@ -162,7 +398,7 @@ export function renderClaims(report) {
     const claimed = report.features.reduce((n, f) => n + f.criteria.filter((c) => c.claimed).length, 0);
     const criteria = `${total} ${total === 1 ? "criterion" : "criteria"}`;
     const specs = plural(report.features.length, "spec file");
-    const counts = `${report.dialect} — ${specs}, ${criteria}, ${claimed} claimed`;
+    const counts = `${dialects} — ${specs}, ${criteria}, ${claimed} claimed`;
     lines.push(report.clean ? `${counts}, clean` : counts);
     return lines.join("\n");
 }
@@ -186,14 +422,26 @@ export function renderInit(report) {
         lines.push('  stryker config: coverageAnalysis "perTest", the json reporter');
         lines.push("  vitest config:  istanbul provider, json-summary reporter");
     }
+    if (report.supersededDeps.length > 0) {
+        lines.push("");
+        lines.push(`superseded devDependency: ${report.supersededDeps.join(", ")}`);
+        lines.push("this CLI publishes as speccle now — the old package is a stale binary beside");
+        lines.push(`the current one. Remove it yourself: ${report.removeCommand}`);
+    }
     if (report.doubleLoad) {
         lines.push("");
-        lines.push("warning: this repo vendors the speccle skills project-level AND the");
-        lines.push("speccle plugin is enabled user-level — two copies of every skill will");
-        lines.push("load. Disable one: /plugin (user-level) or remove .claude/skills/ here.");
+        lines.push(renderDoubleLoad());
     }
     return lines.join("\n");
 }
+/**
+ * One wording for both entry points. `speccle init` vendors the skills and `speccle strength
+ * init` provisions the stack; either run is a fair place to discover the double-load, so
+ * neither stays quiet about it (#183).
+ */
+export function renderDoubleLoad() {
+    return join("warning: this repo vendors the speccle skills project-level AND the", "speccle plugin is enabled user-level — two copies of every skill will", "load. Disable one: /plugin (user-level) or remove .claude/skills/ here.");
+}
 export function renderHuman(report) {
     if (report.files.length === 0)
         return "No SPEC.md files found.";
@@ -310,6 +558,19 @@ function ansi(text, code) {
 function bold(text, color) {
     return color ? ansi(text, "1") : text;
 }
-function plural(n, noun) {
-    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+function plural(n, noun, plural = `${noun}s`) {
+    return `${n} ${n === 1 ? noun : plural}`;
+}
+/**
+ * Names the change set a committed-range run was measured over — a score whose change set is
+ * invisible is not auditable, and the CI driver's whole output is read from a log. Absent for
+ * the working tree's pending change, where "what changed" is already in front of you.
+ */
+function changeSetLine(report) {
+    if (report.base === undefined)
+        return undefined;
+    return `change set: ${report.base}...HEAD — ${plural(report.changed.length, "file")}`;
+}
+function join(...lines) {
+    return lines.filter((line) => line !== undefined).join("\n");
 }

package/dist/reviewinit.js

@@ -0,0 +1,139 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { ownVersion } from "./init.js";
+/** Where the scaffolded workflow lands. One file: the driver itself ships in the tarball. */
+export const WORKFLOW_FILE = ".github/workflows/speccle-review.yml";
+/** The repo secret the CI driver cannot run without — and the reason the driver is opt-in. */
+export const API_KEY_SECRET = "ANTHROPIC_API_KEY";
+/**
+ * Scaffolds the review workflow — the CI driver's one artefact in a consumer repo (ADR-0047).
+ * The runner itself is not vendored: the workflow pins `speccle@<version>` and npm serves it, so
+ * the code doing the reviewing never comes from the branch being reviewed, and there is nothing
+ * committed here to drift from the CLI. Re-running is how a repo moves the pin.
+ */
+export async function scaffoldReviewWorkflow(root, version) {
+    const pin = version ?? (await ownVersion());
+    const path = join(root, WORKFLOW_FILE);
+    const existing = await readMaybe(path);
+    const workflow = renderWorkflow(pin);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, workflow);
+    return {
+        root,
+        file: WORKFLOW_FILE,
+        action: existing === undefined ? "written" : "refreshed",
+        pin,
+        movedPin: existing !== undefined && existing !== workflow,
+    };
+}
+/** The pinned version an already-scaffolded workflow names, or undefined when it names none. */
+export function pinnedVersion(workflow) {
+    return /\bspeccle@(\d+\.\d+\.\d+[^\s]*)/.exec(workflow)?.[1];
+}
+/**
+ * The workflow, with every hardening decision stated in a comment beside the line that enforces
+ * it: a scaffolded file is read by people deciding whether to trust it, and a guard whose reason
+ * is undocumented is a guard someone deletes.
+ */
+function renderWorkflow(pin) {
+    return `# Speccle review — the outer loop, running in CI. Written by \`speccle review init\`.
+#
+# It fans this repo's \`.speccle/lenses/\` over a pull request's change set, posts what they find
+# as one review with inline comments, and reports the deterministic risk verdict as a check.
+# It finds and comments; it never pushes a fix — fixes come back through the local \`review\`
+# skill, which can re-run the checks-gate and revert a fix that goes red.
+#
+# Before this can run:
+#   1. Add a metered ${API_KEY_SECRET} repo secret. This driver calls a model once per lens per
+#      pull request, which is why it is opt-in; the local \`review\` skill needs no key.
+#   2. Protect this file. Anyone who can edit a workflow can read the secrets it uses — put
+#      \`.github/\` behind CODEOWNERS or a branch protection rule.
+#
+# Re-run \`speccle review init\` to move the pinned version below.
+
+name: Speccle review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  # The rerun path: an \`@review\` comment on the pull request, gated on write access below.
+  issue_comment:
+    types: [created]
+
+# Least privilege: post a review, read the tree, nothing else.
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: speccle-review-\${{ github.event.pull_request.number || github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    # Two ways in, each gated. A pull request must come from a branch of this repo, never a
+    # fork: a fork's pull request must not reach the API key. A comment must come from someone
+    # who can already write here, or \`@review\` would be a way to spend the key from outside.
+    if: >-
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.head.repo.full_name == github.repository) ||
+      (github.event_name == 'issue_comment' &&
+       github.event.issue.pull_request != null &&
+       startsWith(github.event.comment.body, '@review') &&
+       contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association))
+    steps:
+      # The comment event carries no refs, so resolve them for both paths the same way.
+      - name: Resolve the pull request
+        id: pr
+        env:
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        run: |
+          number=\${{ github.event.pull_request.number || github.event.issue.number }}
+          pr=$(gh api "repos/\${{ github.repository }}/pulls/$number")
+          {
+            echo "number=$number"
+            echo "base=$(echo "$pr" | jq -r .base.ref)"
+            echo "head=$(echo "$pr" | jq -r .head.sha)"
+          } >> "$GITHUB_OUTPUT"
+
+      - uses: actions/checkout@v5
+        with:
+          # The head commit itself, not the synthetic merge commit: the change set under review
+          # is what the branch says, and the comment path would otherwise land on the default
+          # branch. The head is data here — the reviewing code comes from npm, pinned below.
+          ref: \${{ steps.pr.outputs.head }}
+          # \`risk\` measures from the merge base, which a shallow clone has no history to find.
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      # \`origin/\` prefixes the base ref because checkout leaves it as a remote-tracking ref;
+      # a bare branch name would not resolve.
+      - name: Review the change set
+        env:
+          ${API_KEY_SECRET}: \${{ secrets.${API_KEY_SECRET} }}
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        run: >-
+          npx -y speccle@${pin} review run
+          --pr \${{ steps.pr.outputs.number }}
+          --base origin/\${{ steps.pr.outputs.base }}
+          \${{ github.event_name == 'issue_comment' && '--force' || '' }}
+
+      # The status check. \`risk\` exits 1 at or above the review threshold, so a failing step is
+      # the failing check. Whether that blocks the merge is branch protection — GitHub's, and
+      # this repo's call to make, not Speccle's. It runs last so the findings post either way.
+      - name: Risk gate
+        run: npx -y speccle@${pin} risk --base origin/\${{ steps.pr.outputs.base }}
+`;
+}
+async function readMaybe(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}