speccle 0.11.0 → 0.15.0

package/dist/config.js

@@ -0,0 +1,117 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DEFAULT_DIALECT, DIALECT_NAMES } from "./dialects.js";
+import { detectPackageManager } from "./init.js";
+/** Where Speccle reads a repo's facts (ADR-0040). */
+export const CONFIG_DIR = ".speccle";
+export const CONFIG_FILE = `${CONFIG_DIR}/config.json`;
+/** Reads `.speccle/config.json`; undefined when the repo has no config yet. */
+export async function readConfig(root) {
+    let raw;
+    try {
+        raw = await readFile(join(root, CONFIG_FILE), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let config;
+    try {
+        config = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${CONFIG_FILE} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // A wrong dialect must be a loud, visible failure — that is the whole point of writing
+    // it down rather than guessing every time (ADR-0040).
+    assertDialect(config.dialect);
+    for (const override of config.overrides ?? []) {
+        if (override.dialect !== undefined)
+            assertDialect(override.dialect);
+    }
+    return config;
+}
+/**
+ * The dialect and suite in force at a root-relative path. Every override whose path is a
+ * prefix of `path` applies, most-specific last, so a longer override wins per field and a
+ * shorter one still fills a field the longer omits.
+ */
+export function resolveFacts(config, path) {
+    let { dialect, suite } = config;
+    const matching = (config.overrides ?? [])
+        .filter((override) => underPath(path, override.path))
+        .sort((a, b) => a.path.length - b.path.length);
+    for (const override of matching) {
+        if (override.dialect !== undefined)
+            dialect = override.dialect;
+        if (override.suite !== undefined)
+            suite = override.suite;
+    }
+    return { dialect, suite };
+}
+/** Speccle's first guess at a repo's facts — written down, then corrected by hand. */
+export async function detectConfig(root) {
+    const dialect = await detectDialect(root);
+    return { dialect, suite: await detectSuite(root, dialect) };
+}
+/**
+ * Writes `.speccle/config.json` from detection, or keeps an existing one untouched — the
+ * written record is the source of truth, never the detection (ADR-0040), the same posture
+ * `strength init` takes with the stack it provisions.
+ *
+ * When `payloadVersion` is given, it is (re)stamped onto both the skills and the lenses
+ * anchors even on the kept path: `init`/`update` materialize both from the same tarball, so
+ * the two anchors must move with them or a re-run would leave a recorded version behind the
+ * files it just wrote. The facts themselves stay kept — only the stamps follow the payload.
+ */
+export async function initConfig(root, payloadVersion) {
+    const stamped = (config) => payloadVersion === undefined
+        ? config
+        : { ...config, skillsVersion: payloadVersion, lensesVersion: payloadVersion };
+    const existing = await readConfig(root);
+    if (existing !== undefined) {
+        const config = stamped(existing);
+        const moved = payloadVersion !== undefined &&
+            (existing.skillsVersion !== payloadVersion || existing.lensesVersion !== payloadVersion);
+        if (moved)
+            await writeConfig(root, config);
+        return { root, file: CONFIG_FILE, action: "kept", config };
+    }
+    const config = stamped(await detectConfig(root));
+    await writeConfig(root, config);
+    return { root, file: CONFIG_FILE, action: "written", config };
+}
+export async function writeConfig(root, config) {
+    await mkdir(join(root, CONFIG_DIR), { recursive: true });
+    await writeFile(join(root, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n");
+}
+async function detectDialect(root) {
+    if (await exists(join(root, "Package.swift")))
+        return "swift";
+    // package.json or nothing: the TypeScript stack is the default dialect.
+    return DEFAULT_DIALECT;
+}
+// The default suite runs the repo's own `test` script, except a swift repo, whose
+// SwiftPM default cannot know an xcodebuild scheme (ADR-0040) — the human corrects it.
+async function detectSuite(root, dialect) {
+    if (dialect === "swift")
+        return "swift test";
+    const packageManager = await detectPackageManager(root);
+    return packageManager === "bun" ? "bun run test" : `${packageManager} test`;
+}
+function assertDialect(name) {
+    if (!DIALECT_NAMES.includes(name)) {
+        throw new Error(`${CONFIG_FILE}: unknown test dialect: ${name} — known dialects: ${DIALECT_NAMES.join(", ")}`);
+    }
+}
+function underPath(path, prefix) {
+    return path === prefix || path.startsWith(`${prefix}/`);
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/doctor.js

@@ -0,0 +1,141 @@
+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 { 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.
+ */
+export async function doctor(target) {
+    const root = resolve(target);
+    if (!(await isDirectory(root)))
+        throw new Error(`path not found: ${target}`);
+    const cli = await ownVersion();
+    const config = await readConfig(root);
+    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 provisioned = await anyPresent(root, STRYKER_CONFIG_NAMES);
+    const declared = await declaredDeps(root);
+    const deps = STRENGTH_DEPS.map((spec) => checkDep(spec, declared));
+    const stackStatus = !provisioned
+        ? "absent"
+        : deps.some((dep) => dep.status !== "ok")
+            ? "drift"
+            : "current";
+    const current = (status) => status === "current" || status === "absent";
+    const ok = current(skillsStatus) && current(lensesStatus) && stackStatus !== "drift";
+    return {
+        root,
+        cli,
+        skills: { recorded: skillsRecorded, bundled: cli, status: skillsStatus },
+        lenses: { recorded: lensesRecorded, bundled: cli, status: lensesStatus },
+        stack: { provisioned, deps, status: stackStatus },
+        ok,
+    };
+}
+function derivePayloadStatus(present, recorded, bundled) {
+    if (!present)
+        return "absent";
+    if (recorded === null)
+        return "unstamped";
+    const order = compareVersions(recorded, bundled);
+    return order === 0 ? "current" : order < 0 ? "stale" : "ahead";
+}
+function checkDep(spec, declared) {
+    const at = spec.lastIndexOf("@");
+    const name = spec.slice(0, at);
+    const wantedMajor = majorOf(spec.slice(at + 1)) ?? 0;
+    const range = declared.get(name);
+    if (range === undefined)
+        return { name, wantedMajor, declared: null, status: "missing" };
+    const declaredMajor = majorOf(range);
+    // A repo ahead of the preset is the consumer's choice, not drift to nag about; only a
+    // major below the preset is the "bump never propagated" bug this surface exists to catch.
+    const status = declaredMajor !== null && declaredMajor < wantedMajor ? "behind" : "ok";
+    return { name, wantedMajor, declared: range, status };
+}
+/** The union of a package.json's dependencies and devDependencies; empty when absent. */
+async function declaredDeps(root) {
+    let raw;
+    try {
+        raw = await readFile(join(root, "package.json"), "utf8");
+    }
+    catch {
+        return new Map();
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(raw);
+    }
+    catch {
+        return new Map();
+    }
+    return new Map(Object.entries({ ...pkg.dependencies, ...pkg.devDependencies }));
+}
+async function hasSkills(root) {
+    try {
+        const entries = await readdir(join(root, SKILLS_DIR), { withFileTypes: true });
+        return entries.some((entry) => entry.isDirectory());
+    }
+    catch {
+        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 anyPresent(root, names) {
+    for (const name of names) {
+        if (await exists(join(root, name)))
+            return true;
+    }
+    return false;
+}
+/** The leading integer of a version or range — 4 from "^4", "4.1.0", ">=4.0.0". */
+function majorOf(range) {
+    const digits = /\d+/.exec(range);
+    return digits === null ? null : Number(digits[0]);
+}
+function compareVersions(a, b) {
+    const [pa, pb] = [parseVersion(a), parseVersion(b)];
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] !== pb[i])
+            return pa[i] < pb[i] ? -1 : 1;
+    }
+    return 0;
+}
+/** [major, minor, patch] of a clean semver, prerelease and build metadata dropped. */
+function parseVersion(version) {
+    const core = version.split(/[-+]/)[0] ?? "";
+    const parts = core.split(".").map((part) => Number(part) || 0);
+    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/init.js

@@ -17,7 +17,7 @@ const LOCKFILES = [
     ["bun.lock", "bun"],
     ["bun.lockb", "bun"],
 ];
-const STRYKER_CONFIG_NAMES = ["stryker.config", "stryker.conf"].flatMap((base) => ["json", "js", "mjs", "cjs"].map((ext) => `${base}.${ext}`));
+export const STRYKER_CONFIG_NAMES = ["stryker.config", "stryker.conf"].flatMap((base) => ["json", "js", "mjs", "cjs"].map((ext) => `${base}.${ext}`));
 const VITEST_CONFIG_NAMES = ["vitest.config", "vite.config"].flatMap((base) => ["ts", "mts", "cts", "js", "mjs", "cjs"].map((ext) => `${base}.${ext}`));
 export function strykerConfig(packageManager, mutate) {
     return {
@@ -109,7 +109,8 @@ export async function detectDoubleLoad(root, settingsFile = join(homedir(), ".cl
         return false;
     }
 }
-async function ownVersion() {
+/** The installed CLI's own version — the `speccle@X` that ships this bin and its skills. */
+export async function ownVersion() {
     const raw = await readFile(new URL("../package.json", import.meta.url), "utf8");
     return JSON.parse(raw).version;
 }
@@ -123,7 +124,7 @@ async function readPackageJson(root) {
     }
     return JSON.parse(raw);
 }
-async function detectPackageManager(root) {
+export async function detectPackageManager(root) {
     for (const [lockfile, manager] of LOCKFILES) {
         if (await exists(join(root, lockfile)))
             return manager;
@@ -138,7 +139,7 @@ async function provision(root, existingNames, writeName, content) {
     await writeFile(join(root, writeName), content());
     return { file: writeName, action: "written" };
 }
-function installCommandFor(manager, deps) {
+export function installCommandFor(manager, deps) {
     const subcommand = manager === "npm" ? "install -D" : manager === "bun" ? "add -d" : "add -D";
     return `${manager} ${subcommand} ${deps.join(" ")}`;
 }

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"`);
+    }
+}