speccle 0.11.0 → 0.15.0

package/dist/cli.js

@@ -1,22 +1,82 @@
 #!/usr/bin/env node
+import { calibrationReport, recordCalibration } from "./calibration.js";
 import { check } from "./check.js";
 import { claims } from "./claims.js";
+import { initConfig } from "./config.js";
 import { DEFAULT_DIALECT, DIALECT_NAMES } from "./dialects.js";
-import { init } from "./init.js";
+import { doctor } from "./doctor.js";
+import { init, ownVersion } from "./init.js";
+import { materializeLenses } from "./lenses.js";
 import { lint } from "./lint.js";
-import { renderCheck, renderClaims, renderHuman, renderInit, renderStrength } from "./render.js";
+import { recallRemedy, recordRemedy, REMEDY_ROUTES } from "./remedy.js";
+import { renderCalibrateRecord, renderCalibrateReport, renderCheck, renderClaims, renderConfigInit, renderDoctor, renderHuman, renderInit, renderLensesInit, renderRemedyRecall, renderRemedyRecord, renderReviewInit, renderReviewRun, renderRisk, renderSkillsInit, renderStrength, renderUpdate, renderVerify, } from "./render.js";
+import { scaffoldReviewWorkflow } from "./reviewinit.js";
+import { reviewRun } from "./reviewrun.js";
+import { risk } from "./risk.js";
+import { materializeSkills } from "./skills.js";
 import { DEFAULT_COVERAGE_SUMMARY, DEFAULT_MUTATION_REPORT, strength } from "./strength.js";
+import { update } from "./update.js";
+import { verify } from "./verify.js";
 const USAGE = `Usage: speccle <command> [options]
 
 Commands:
+  init [path] [--json]           Record repo facts in .speccle/config.json, materialize the
+                                 skills into .claude/skills/ and the lenses into .speccle/lenses/
+  doctor [path] [--json]         Report staleness across the CLI, skills, lenses, and strength stack
+  update [path] [--json]         Refresh the skills and lenses as a diff; report stack and binary fixes
   lint [path] [--json]           Lint every SPEC.md under path (default: current directory)
   claims [path] [--json]         Join criteria to the test names that claim them — no reports needed
+  verify [path] [--json]         Run .speccle/checks/ against the change set: cross-file invariants
+  risk [path] [--json]           Score the change set from spec-aware signals; gate on the review threshold
+  calibrate record [path]        Append a calibration entry: the risk floor + your honest verdict
+  calibrate report [path]        Read the calibration record: signal reliability + the supported threshold
+  remedy record [path]           Record a remedy: the finding, the fix, and the prevention artefact
+  remedy recall [path]           Recall the known remedy for a finding's class — fix consistently
+  review init [path] [--json]    Scaffold the opt-in CI driver: a GitHub Actions workflow, pinned
+  review run [path]              Review a pull request with the lens panel and post one review.
+                                 The one command here that calls a model — needs a metered key
   strength [path] [--json]       Oracle-strength heatmap: per-criterion killed ÷ covered
   strength init [path] [--json]  Provision the strength stack: devDependencies + configs
+  --version, -v                  Print the installed CLI version
 
-claims options:
+claims / risk options:
   --dialect <name>    Test dialect: ${DIALECT_NAMES.join(", ")} (default: ${DEFAULT_DIALECT})
 
+verify / risk options:
+  --base <ref>        Read the change set from the commits between <ref> and HEAD, instead of the
+                      working tree's pending change — what a CI driver needs, where the tree is
+                      clean. Measured from the merge base, so it needs their shared history
+
+risk exit codes: 0 below the review threshold (review may fix), 1 at or above it (human required)
+
+calibrate record options:
+  --needed-human <true|false>  Did this change actually need a human? (required — the honest verdict)
+  --found-real <true|false>    Did the review find something real? (required)
+  --escalated                  A risk lens escalated beyond the deterministic floor
+  --note <text>                Free-text context for the entry
+  --dialect <name>             Test dialect: ${DIALECT_NAMES.join(", ")} (default: ${DEFAULT_DIALECT})
+
+remedy record options:
+  --class <handle>             Short, stable handle for the finding's class (required — the recall key)
+  --finding <text>             What the finding is (required)
+  --fix <text>                 The fix applied to the code (required)
+  --route <route>              Prevention route: ${REMEDY_ROUTES.join(", ")} (required)
+  --artefact <ref>             The prevention artefact: a .speccle/checks|lenses path or a SPEC
+                               criterion id (required for every route but none)
+  --note <text>                Free-text context for the entry
+
+remedy recall options:
+  --class <handle>             The finding's class to look up (required)
+
+review run options:
+  --pr <number>                The pull request to review (required)
+  --repo <owner/name>          Defaults to GITHUB_REPOSITORY
+  --base <ref>                 Base ref for the risk verdict (default: origin/<the PR's base>)
+  --force                      Review again even if this driver already reviewed the PR
+  --model <id>                 Overrides SPECCLE_REVIEW_MODEL
+  --dry-run                    Report what would be posted, and post nothing
+  Reads ANTHROPIC_API_KEY and GITHUB_TOKEN from the environment
+
 strength options:
   --check             Report whether the reports are fresh, stale, or missing — never runs them
   --mutation <file>   Stryker JSON report   (default: ${DEFAULT_MUTATION_REPORT})
@@ -30,12 +90,50 @@ strength init options:
 Exit codes: 0 clean, 1 violations, 2 usage error`;
 async function main(argv) {
     const [command, ...rest] = argv;
+    if (command === "--version" || command === "-v") {
+        console.log(await ownVersion());
+        return 0;
+    }
+    if (command === "init")
+        return runInit(rest);
+    if (command === "doctor")
+        return runDoctor(rest);
+    if (command === "update")
+        return runUpdate(rest);
     if (command === "lint")
         return runLint(rest);
     if (command === "claims")
         return runClaims(rest);
+    if (command === "verify")
+        return runVerify(rest);
+    if (command === "risk")
+        return runRisk(rest);
+    if (command === "calibrate" && rest[0] === "record")
+        return runCalibrateRecord(rest.slice(1));
+    if (command === "calibrate" && rest[0] === "report")
+        return runCalibrateReport(rest.slice(1));
+    if (command === "calibrate") {
+        console.error(`calibrate needs a subcommand: record or report\n\n${USAGE}`);
+        return 2;
+    }
+    if (command === "remedy" && rest[0] === "record")
+        return runRemedyRecord(rest.slice(1));
+    if (command === "remedy" && rest[0] === "recall")
+        return runRemedyRecall(rest.slice(1));
+    if (command === "remedy") {
+        console.error(`remedy needs a subcommand: record or recall\n\n${USAGE}`);
+        return 2;
+    }
+    if (command === "review" && rest[0] === "init")
+        return runReviewInit(rest.slice(1));
+    if (command === "review" && rest[0] === "run")
+        return runReviewRun(rest.slice(1));
+    if (command === "review") {
+        console.error(`review needs a subcommand: init or run\n\n${USAGE}`);
+        return 2;
+    }
     if (command === "strength" && rest[0] === "init")
-        return runInit(rest.slice(1));
+        return runStrengthInit(rest.slice(1));
     if (command === "strength")
         return runStrength(rest);
     console.error(USAGE);
@@ -79,6 +177,356 @@ async function runClaims(args) {
     console.log(json ? JSON.stringify(report, null, 2) : renderClaims(report));
     return report.clean ? 0 : 1;
 }
+async function runVerify(args) {
+    let json = false;
+    let base;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--base") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`--base needs a git ref\n\n${USAGE}`);
+                return 2;
+            }
+            base = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`verify takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await verify(positional[0] ?? ".", { ...(base !== undefined && { base }) });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderVerify(report));
+    return report.clean ? 0 : 1;
+}
+async function runRisk(args) {
+    let json = false;
+    let dialect;
+    let base;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--dialect" || arg === "--base") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs ${arg === "--base" ? "a git ref" : "a dialect name"}\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--dialect")
+                dialect = value;
+            else
+                base = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`risk takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await risk(positional[0] ?? ".", {
+            ...(dialect !== undefined && { dialect }),
+            ...(base !== undefined && { base }),
+        });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderRisk(report));
+    return report.humanRequired ? 1 : 0;
+}
+async function runCalibrateRecord(args) {
+    let json = false;
+    let dialect;
+    let neededHuman;
+    let foundReal;
+    let escalated = false;
+    let note;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--escalated")
+            escalated = true;
+        else if (arg === "--needed-human" || arg === "--found-real") {
+            const value = args[++i];
+            if (value !== "true" && value !== "false") {
+                console.error(`${arg} needs true or false\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--needed-human")
+                neededHuman = value === "true";
+            else
+                foundReal = value === "true";
+        }
+        else if (arg === "--note" || arg === "--dialect") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs a value\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--note")
+                note = value;
+            else
+                dialect = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`calibrate record takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    // The honest verdict is required, never defaulted — a fabricated verdict is the dishonest
+    // calibration data ADR-0042 exists to keep out of the record.
+    if (neededHuman === undefined || foundReal === undefined) {
+        console.error(`calibrate record needs --needed-human and --found-real\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await recordCalibration(positional[0] ?? ".", { neededHuman, foundReal, escalated, ...(note !== undefined && { note }) }, { ...(dialect !== undefined && { dialect }) });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderCalibrateRecord(report));
+    return 0;
+}
+async function runCalibrateReport(args) {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`calibrate report takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await calibrationReport(positional[0] ?? ".");
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderCalibrateReport(report));
+    return 0;
+}
+async function runRemedyRecord(args) {
+    let json = false;
+    let classHandle;
+    let finding;
+    let fix;
+    let route;
+    let artefact;
+    let note;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--class" ||
+            arg === "--finding" ||
+            arg === "--fix" ||
+            arg === "--route" ||
+            arg === "--artefact" ||
+            arg === "--note") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs a value\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--class")
+                classHandle = value;
+            else if (arg === "--finding")
+                finding = value;
+            else if (arg === "--fix")
+                fix = value;
+            else if (arg === "--route")
+                route = value;
+            else if (arg === "--artefact")
+                artefact = value;
+            else
+                note = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`remedy record takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    if (classHandle === undefined ||
+        finding === undefined ||
+        fix === undefined ||
+        route === undefined) {
+        console.error(`remedy record needs --class, --finding, --fix, and --route\n\n${USAGE}`);
+        return 2;
+    }
+    if (!REMEDY_ROUTES.includes(route)) {
+        console.error(`--route must be one of ${REMEDY_ROUTES.join(", ")}\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await recordRemedy(positional[0] ?? ".", {
+            class: classHandle,
+            finding,
+            fix,
+            route: route,
+            ...(artefact !== undefined && { artefact }),
+            ...(note !== undefined && { note }),
+        });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderRemedyRecord(report));
+    return 0;
+}
+async function runRemedyRecall(args) {
+    let json = false;
+    let classHandle;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--class") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`--class needs a value\n\n${USAGE}`);
+                return 2;
+            }
+            classHandle = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`remedy recall takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    if (classHandle === undefined) {
+        console.error(`remedy recall needs --class\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await recallRemedy(positional[0] ?? ".", classHandle);
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderRemedyRecall(report));
+    return 0;
+}
+async function runDoctor(args) {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`doctor takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await doctor(positional[0] ?? ".");
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderDoctor(report));
+    return report.ok ? 0 : 1;
+}
+async function runUpdate(args) {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`update takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await update(positional[0] ?? ".");
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderUpdate(report));
+    return 0;
+}
 async function runLint(args) {
     let json = false;
     const positional = [];
@@ -172,6 +620,150 @@ async function runStrength(args) {
     return 0;
 }
 async function runInit(args) {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`init takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    const root = positional[0] ?? ".";
+    let config;
+    let skills;
+    let lenses;
+    try {
+        // Materialize first, then stamp the version onto the config — so the recorded anchors
+        // only ever name the skills and lenses that actually landed on disk.
+        skills = await materializeSkills(root);
+        lenses = await materializeLenses(root);
+        config = await initConfig(root, await ownVersion());
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    if (json) {
+        console.log(JSON.stringify({ config, skills, lenses }, null, 2));
+    }
+    else {
+        console.log(renderConfigInit(config));
+        console.log("");
+        console.log(renderSkillsInit(skills));
+        console.log("");
+        console.log(renderLensesInit(lenses));
+    }
+    return 0;
+}
+async function runReviewInit(args) {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`review init takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await scaffoldReviewWorkflow(positional[0] ?? ".");
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderReviewInit(report));
+    return 0;
+}
+async function runReviewRun(args) {
+    let json = false;
+    let force = false;
+    let dryRun = false;
+    let pr;
+    let repo;
+    let base;
+    let model;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--force")
+            force = true;
+        else if (arg === "--dry-run")
+            dryRun = true;
+        else if (arg === "--pr" || arg === "--repo" || arg === "--base" || arg === "--model") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs a value\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--pr") {
+                const number = Number(value);
+                if (!Number.isInteger(number) || number <= 0) {
+                    console.error(`--pr needs a pull request number\n\n${USAGE}`);
+                    return 2;
+                }
+                pr = number;
+            }
+            else if (arg === "--repo")
+                repo = value;
+            else if (arg === "--base")
+                base = value;
+            else
+                model = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`review run takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    if (pr === undefined) {
+        console.error(`review run needs --pr\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await reviewRun(positional[0] ?? ".", {
+            pr,
+            force,
+            dryRun,
+            ...(repo !== undefined && { repo }),
+            ...(base !== undefined && { base }),
+            ...(model !== undefined && { model }),
+        });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderReviewRun(report));
+    // Posting findings is not a failure: the risk gate is the check, and it runs as its own step.
+    return 0;
+}
+async function runStrengthInit(args) {
     let json = false;
     let skipInstall = false;
     const mutate = [];