speccle 0.12.0 → 0.16.0

package/dist/doctor.js

@@ -2,12 +2,15 @@ import { access, readdir, readFile, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { readConfig } from "./config.js";
 import { ownVersion, STRENGTH_DEPS, STRYKER_CONFIG_NAMES } from "./init.js";
+import { LENSES_DIR } from "./lenses.js";
+import { pinnedVersion, WORKFLOW_FILE } from "./reviewinit.js";
 import { SKILLS_DIR } from "./skills.js";
 /**
- * Reports the truth about the three things that drift in a Speccle consumer — the CLI, the
- * committed skills, and the strength stack — and never mutates a byte (#182, ADR-0046).
- * Offline and deterministic: it compares the repo against the installed CLI, not against
- * the npm registry — "is there a newer release" is `update`'s network job, not this one's.
+ * Reports the truth about everything that drifts in a Speccle consumer — the CLI, the
+ * committed skills and lenses, the CI driver's pin, and the strength stack — and never
+ * mutates a byte (#182, ADR-0046). Offline and deterministic: it compares the repo against
+ * the installed CLI, not against the npm registry — "is there a newer release" is `update`'s
+ * network job, not this one's.
  */
 export async function doctor(target) {
     const root = resolve(target);
@@ -15,8 +18,13 @@ export async function doctor(target) {
         throw new Error(`path not found: ${target}`);
     const cli = await ownVersion();
     const config = await readConfig(root);
-    const recorded = config?.skillsVersion ?? null;
-    const skillsStatus = deriveSkillsStatus(await hasSkills(root), recorded, cli);
+    const skillsRecorded = config?.skillsVersion ?? null;
+    const skillsStatus = derivePayloadStatus(await hasSkills(root), skillsRecorded, cli);
+    const lensesRecorded = config?.lensesVersion ?? null;
+    const lensesStatus = derivePayloadStatus(await hasLenses(root), lensesRecorded, cli);
+    const workflow = await readMaybe(join(root, WORKFLOW_FILE));
+    const driverPin = workflow === undefined ? null : (pinnedVersion(workflow) ?? null);
+    const driverStatus = derivePayloadStatus(workflow !== undefined, driverPin, cli);
     const provisioned = await anyPresent(root, STRYKER_CONFIG_NAMES);
     const declared = await declaredDeps(root);
     const deps = STRENGTH_DEPS.map((spec) => checkDep(spec, declared));
@@ -25,16 +33,22 @@ export async function doctor(target) {
         : deps.some((dep) => dep.status !== "ok")
             ? "drift"
             : "current";
-    const ok = (skillsStatus === "current" || skillsStatus === "absent") && stackStatus !== "drift";
+    const current = (status) => status === "current" || status === "absent";
+    const ok = current(skillsStatus) &&
+        current(lensesStatus) &&
+        current(driverStatus) &&
+        stackStatus !== "drift";
     return {
         root,
         cli,
-        skills: { recorded, bundled: cli, status: skillsStatus },
+        skills: { recorded: skillsRecorded, bundled: cli, status: skillsStatus },
+        lenses: { recorded: lensesRecorded, bundled: cli, status: lensesStatus },
+        driver: { recorded: driverPin, bundled: cli, status: driverStatus },
         stack: { provisioned, deps, status: stackStatus },
         ok,
     };
 }
-function deriveSkillsStatus(present, recorded, bundled) {
+function derivePayloadStatus(present, recorded, bundled) {
     if (!present)
         return "absent";
     if (recorded === null)
@@ -82,6 +96,23 @@ async function hasSkills(root) {
         return false;
     }
 }
+async function hasLenses(root) {
+    try {
+        const entries = await readdir(join(root, LENSES_DIR));
+        return entries.some((entry) => entry.endsWith(".md"));
+    }
+    catch {
+        return false;
+    }
+}
+async function readMaybe(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
 async function anyPresent(root, names) {
     for (const name of names) {
         if (await exists(join(root, name)))

package/dist/git.js

@@ -0,0 +1,23 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+/**
+ * Spawning by name makes every call walk PATH, and the misses are what cost — measured at ~8ms
+ * each on macOS, against ~2ms for git itself. Under `npx`/`pnpm` the caller's PATH puts a dozen
+ * or more entries ahead of git's, so `risk`, which reads a baseline once per changed spec file,
+ * paid that walk per file. Resolved once here instead: the binary is fixed at module load rather
+ * than per call, which suits a short-lived CLI but means a PATH edit mid-process is not seen.
+ */
+const GIT = (process.env.PATH ?? "")
+    .split(delimiter)
+    .map((dir) => join(dir, "git"))
+    .find((candidate) => existsSync(candidate)) ?? "git";
+/** Run one git command in `root`, with the binary resolved once. */
+export function git(root, args) {
+    return spawnSync(GIT, args, { cwd: root, encoding: "utf8" });
+}
+/** Git's stdout, or undefined when the command could not run or failed. */
+export function gitStdout(root, args) {
+    const result = git(root, args);
+    return result.error === undefined && result.status === 0 ? result.stdout : undefined;
+}

package/dist/init.js

@@ -10,6 +10,10 @@ export const STRENGTH_DEPS = [
     "@stryker-mutator/core@^9",
     "@stryker-mutator/vitest-runner@^9",
 ];
+// Names this CLI has published under before (ADR-0045). A repo provisioned under an old name
+// keeps that package beside the current one, and `node_modules/.bin/` still exposes its stale
+// binary — dead weight the ladder never picks, but weight the repo should know it is carrying.
+export const SUPERSEDED_DEPS = ["speccle-oracle"];
 const LOCKFILES = [
     ["pnpm-lock.yaml", "pnpm"],
     ["package-lock.json", "npm"],
@@ -67,6 +71,8 @@ export async function init(root, options = {}) {
     const wantedDeps = [`speccle@^${await ownVersion()}`, ...STRENGTH_DEPS];
     const missingDeps = wantedDeps.filter((spec) => !declared.has(withoutVersion(spec)));
     const installCommand = missingDeps.length > 0 ? installCommandFor(packageManager, missingDeps) : null;
+    const supersededDeps = SUPERSEDED_DEPS.filter((name) => declared.has(name));
+    const removeCommand = supersededDeps.length > 0 ? removeCommandFor(packageManager, supersededDeps) : null;
     const files = [
         await provision(root, STRYKER_CONFIG_NAMES, "stryker.config.json", () => JSON.stringify(strykerConfig(packageManager, mutate), null, 2) + "\n"),
         await provision(root, VITEST_CONFIG_NAMES, "vitest.config.ts", () => vitestConfig(mutate)),
@@ -83,6 +89,8 @@ export async function init(root, options = {}) {
         missingDeps,
         installCommand,
         installRan,
+        supersededDeps,
+        removeCommand,
         mutate,
         files,
         doubleLoad,
@@ -143,6 +151,10 @@ export function installCommandFor(manager, deps) {
     const subcommand = manager === "npm" ? "install -D" : manager === "bun" ? "add -d" : "add -D";
     return `${manager} ${subcommand} ${deps.join(" ")}`;
 }
+export function removeCommandFor(manager, deps) {
+    const subcommand = manager === "npm" ? "uninstall" : "remove";
+    return `${manager} ${subcommand} ${deps.join(" ")}`;
+}
 function runInstall(root, command) {
     const [manager, ...args] = command.split(" ");
     const result = spawnSync(manager, args, { cwd: root, encoding: "utf8" });

package/dist/lenses.js

@@ -0,0 +1,68 @@
+import { access, copyFile, mkdir, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Where materialized lenses land in a target repo — the dimensions `review` fans out over. */
+export const LENSES_DIR = ".speccle/lenses";
+/**
+ * The one lens that ships as a template and is the repo's own to author (ADR-0043) — its
+ * house-conventions lens is the real IP Speccle cannot write. It is written once, when
+ * absent, and a refresh never overwrites it: clobbering an authored lens would be exactly
+ * the data loss the "with a lock" property exists to prevent.
+ */
+export const TEMPLATE_LENS = "house-conventions.md";
+/**
+ * Vendors the baseline lenses into the target's `.speccle/lenses/`, so `review` has a panel
+ * to fan out over on any repo day one (ADR-0043). The baseline lenses are Speccle's and are
+ * overwritten on every run — the same "the tarball is the source of truth" posture the skills
+ * take (ADR-0046) — but the house-conventions template is the repo's own and is only ever
+ * written when absent. Any lens the repo authored itself is left untouched: only the bundled
+ * names are considered, so a repo-added lens is never seen, let alone removed.
+ */
+export async function materializeLenses(root, source) {
+    const from = source ?? bundledLensesDir();
+    const names = await lensNames(from);
+    const target = join(root, LENSES_DIR);
+    await mkdir(target, { recursive: true });
+    const lenses = [];
+    for (const name of names) {
+        const dest = join(target, name);
+        const present = await exists(dest);
+        if (name === TEMPLATE_LENS) {
+            if (!present)
+                await copyFile(join(from, name), dest);
+            lenses.push({ name, action: present ? "kept" : "written" });
+            continue;
+        }
+        await copyFile(join(from, name), dest);
+        lenses.push({ name, action: present ? "refreshed" : "written" });
+    }
+    return { root, dir: LENSES_DIR, source: from, lenses };
+}
+async function lensNames(source) {
+    let entries;
+    try {
+        entries = await readdir(source);
+    }
+    catch {
+        throw new Error(`no bundled lenses to materialize at ${source}`);
+    }
+    return entries.filter((entry) => entry.endsWith(".md")).sort();
+}
+/**
+ * The shipped lenses: a top-level `lenses/` beside `dist/` in the published tarball. Unlike
+ * the skills — copied in from the plugin at build time — the lens sources live in this
+ * package already, so the same relative path resolves whether the CLI runs from `dist/` or
+ * straight from `src/`; no build-time bundle and no source fallback are needed.
+ */
+function bundledLensesDir() {
+    return fileURLToPath(new URL("../lenses", import.meta.url));
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/remedy.js

@@ -0,0 +1,133 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { isDirectory, messageOf } from "./changeset.js";
+/** Where the meta loop keeps its remedy record (ADR-0043): append-only, one entry per line. */
+export const REMEDY_FILE = ".speccle/remedies.jsonl";
+/**
+ * The prevention routes the remedy record owns — ADR-0043's routing table minus its risk-weight
+ * row, which is the calibration record's ({@link ./calibration.ts}, ADR-0042). `none` is the honest
+ * one-off: a finding whose class is not worth preventing, so it names no artefact.
+ */
+export const REMEDY_ROUTES = ["check", "criterion", "lens", "none"];
+/** Where each route's prevention artefact lives — named in the error when one is missing. */
+const ARTEFACT_HOME = {
+    check: "a .speccle/checks/ path",
+    criterion: "a SPEC.md criterion id",
+    lens: "a .speccle/lenses/ path",
+};
+/**
+ * Appends one remedy: the finding, the fix applied, and the prevention route with its artefact.
+ * Every route but `none` must name its artefact — the record is only worth consulting if it points
+ * at the prevention it chose; a `none` remedy names nothing, because a one-off prevents nothing.
+ */
+export async function recordRemedy(target, input, options = {}) {
+    const root = resolve(target);
+    if (!(await isDirectory(root)))
+        throw new Error(`path not found: ${target}`);
+    const classHandle = input.class.trim();
+    if (classHandle === "")
+        throw new Error("a remedy needs a --class (the finding's class handle)");
+    if (input.finding.trim() === "")
+        throw new Error("a remedy needs a --finding");
+    if (input.fix.trim() === "")
+        throw new Error("a remedy needs a --fix");
+    if (!REMEDY_ROUTES.includes(input.route)) {
+        throw new Error(`unknown route "${input.route}": one of ${REMEDY_ROUTES.join(", ")}`);
+    }
+    const artefact = (input.artefact ?? "").trim();
+    if (input.route === "none" && artefact !== "") {
+        throw new Error("a none remedy prevents nothing — it names no --artefact");
+    }
+    if (input.route !== "none" && artefact === "") {
+        throw new Error(`a ${input.route} remedy needs an --artefact (${ARTEFACT_HOME[input.route]})`);
+    }
+    const entry = {
+        at: (options.now ?? (() => new Date().toISOString()))(),
+        class: classHandle,
+        finding: input.finding.trim(),
+        fix: input.fix.trim(),
+        route: input.route,
+        ...(artefact !== "" && { artefact }),
+        ...(input.note !== undefined && input.note.trim() !== "" && { note: input.note.trim() }),
+    };
+    const file = join(root, REMEDY_FILE);
+    await mkdir(dirname(file), { recursive: true });
+    await appendFile(file, JSON.stringify(entry) + "\n");
+    return { root, file: REMEDY_FILE, entry, count: (await readEntries(root)).length };
+}
+/**
+ * Looks up the known-correct remedy for a finding's class so a repeat gets the same answer. Matches
+ * deterministically on the class handle's tokens (lowercased alphanumeric runs): an entry matches
+ * when one side's tokens are a subset of the other's, so `missing-roundtrip` still recalls
+ * `missing-model-roundtrip-test`. Most-recent first — the latest answer to a class wins.
+ */
+export async function recallRemedy(target, query) {
+    const root = resolve(target);
+    if (!(await isDirectory(root)))
+        throw new Error(`path not found: ${target}`);
+    const entries = await readEntries(root);
+    const wanted = classTokens(query);
+    const matches = wanted.size === 0
+        ? []
+        : entries
+            .filter((entry) => {
+            const have = classTokens(entry.class);
+            return have.size > 0 && (isSubset(wanted, have) || isSubset(have, wanted));
+        })
+            .reverse();
+    return { root, file: REMEDY_FILE, query, matches, count: entries.length };
+}
+/** A class handle's comparison tokens: lowercased alphanumeric runs, e.g. `model`, `roundtrip`. */
+function classTokens(handle) {
+    return new Set(handle
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean));
+}
+function isSubset(a, b) {
+    for (const token of a)
+        if (!b.has(token))
+            return false;
+    return true;
+}
+async function readEntries(root) {
+    let raw;
+    try {
+        raw = await readFile(join(root, REMEDY_FILE), "utf8");
+    }
+    catch {
+        return []; // no record yet: nothing has been remedied.
+    }
+    const entries = [];
+    const lines = raw.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line === "")
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch (err) {
+            throw new Error(`${REMEDY_FILE}:${i + 1} is not valid JSON: ${messageOf(err)}`);
+        }
+        assertEntry(entry, i + 1);
+        entries.push(entry);
+    }
+    return entries;
+}
+// A malformed entry must fail loudly, naming the line — a silently-dropped remedy is a hole in the
+// memory the meta loop consults to fix consistently, exactly what ADR-0043 keeps in one place.
+function assertEntry(entry, line) {
+    const at = `${REMEDY_FILE}:${line}`;
+    const nonEmpty = (value) => typeof value === "string" && value.trim() !== "";
+    if (!nonEmpty(entry.class) || !nonEmpty(entry.finding) || !nonEmpty(entry.fix)) {
+        throw new Error(`${at}: "class", "finding", and "fix" must be non-empty strings`);
+    }
+    if (!REMEDY_ROUTES.includes(entry.route)) {
+        throw new Error(`${at}: "route" must be one of ${REMEDY_ROUTES.join(", ")}`);
+    }
+    if (entry.route === "none" ? entry.artefact !== undefined : !nonEmpty(entry.artefact)) {
+        throw new Error(`${at}: a ${entry.route} remedy ${entry.route === "none" ? "names no" : "needs an"} "artefact"`);
+    }
+}