speccle 0.11.0

package/dist/discover.js

@@ -0,0 +1,29 @@
+import { readdir } from "node:fs/promises";
+import { basename, join } from "node:path";
+const SKIP_DIRS = new Set(["node_modules", "dist", "fixtures", "__fixtures__"]);
+export function discoverSpecs(root) {
+    return discoverFiles(root, (file) => basename(file) === "SPEC.md");
+}
+export function discoverTests(root, dialect) {
+    return discoverFiles(root, (file) => dialect.isTestFile(file));
+}
+/** `keep` receives each file's posix path relative to `root`. */
+export async function discoverFiles(root, keep) {
+    const found = [];
+    async function walk(abs, rel) {
+        for (const entry of await readdir(abs, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name) || entry.name.startsWith("."))
+                    continue;
+                await walk(join(abs, entry.name), rel === "" ? entry.name : `${rel}/${entry.name}`);
+            }
+            else if (entry.isFile()) {
+                const file = rel === "" ? entry.name : `${rel}/${entry.name}`;
+                if (keep(file))
+                    found.push(file);
+            }
+        }
+    }
+    await walk(root, "");
+    return found.sort();
+}

package/dist/init.js

@@ -0,0 +1,164 @@
+import { spawnSync } from "node:child_process";
+import { access, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { discoverSpecs } from "./discover.js";
+// The one stack the oracle join is proven on (ADR-0008), pinned to those majors.
+export const STRENGTH_DEPS = [
+    "vitest@^4",
+    "@vitest/coverage-istanbul@^4",
+    "@stryker-mutator/core@^9",
+    "@stryker-mutator/vitest-runner@^9",
+];
+const LOCKFILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["package-lock.json", "npm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+];
+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 {
+        $schema: "./node_modules/@stryker-mutator/core/schema/stryker-schema.json",
+        packageManager,
+        testRunner: "vitest",
+        plugins: ["@stryker-mutator/vitest-runner"],
+        coverageAnalysis: "perTest",
+        reporters: ["json", "progress"],
+        jsonReporter: { fileName: "reports/mutation/mutation.json" },
+        mutate,
+    };
+}
+export function vitestConfig(mutate) {
+    const include = mutate.filter((glob) => !glob.startsWith("!"));
+    const exclude = mutate.filter((glob) => glob.startsWith("!")).map((glob) => glob.slice(1));
+    const list = (globs) => globs.map((g) => JSON.stringify(g)).join(", ");
+    return `import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: "istanbul",
+      reporter: ["json-summary", "text"],
+      include: [${list(include)}],
+      exclude: [${list(exclude)}],
+    },
+  },
+});
+`;
+}
+export async function mutateGlobs(root) {
+    const specs = await discoverSpecs(root);
+    const dirs = [...new Set(specs.map((spec) => dirname(spec)))].sort();
+    if (dirs.length === 0 || dirs.includes("."))
+        return ["features/**/*.ts", "!features/**/*.test.ts"];
+    return [...dirs.map((dir) => `${dir}/**/*.ts`), ...dirs.map((dir) => `!${dir}/**/*.test.ts`)];
+}
+export async function init(root, options = {}) {
+    const packageJson = await readPackageJson(root);
+    const packageManager = await detectPackageManager(root);
+    const mutate = options.mutate?.length ? options.mutate : await mutateGlobs(root);
+    const declared = new Set([
+        ...Object.keys(packageJson.devDependencies ?? {}),
+        ...Object.keys(packageJson.dependencies ?? {}),
+    ]);
+    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 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)),
+    ];
+    let installRan = false;
+    if (installCommand !== null && !options.skipInstall) {
+        runInstall(root, installCommand);
+        installRan = true;
+    }
+    const doubleLoad = await detectDoubleLoad(root);
+    return {
+        root,
+        packageManager,
+        missingDeps,
+        installCommand,
+        installRan,
+        mutate,
+        files,
+        doubleLoad,
+    };
+}
+// The materialized copies must be the one source of truth: a target that vendors the
+// skills project-level should not also load the user-level plugin. Best-effort — the
+// settings shape is Claude Code's, not ours; absence of the file means no warning.
+export async function detectDoubleLoad(root, settingsFile = join(homedir(), ".claude", "settings.json")) {
+    if (!(await exists(join(root, ".claude", "skills", "feature", "SKILL.md"))))
+        return false;
+    let raw;
+    try {
+        raw = await readFile(settingsFile, "utf8");
+    }
+    catch {
+        return false;
+    }
+    try {
+        const settings = JSON.parse(raw);
+        return Object.entries(settings.enabledPlugins ?? {}).some(([plugin, enabled]) => enabled && plugin.startsWith("speccle@"));
+    }
+    catch {
+        return false;
+    }
+}
+async function ownVersion() {
+    const raw = await readFile(new URL("../package.json", import.meta.url), "utf8");
+    return JSON.parse(raw).version;
+}
+async function readPackageJson(root) {
+    let raw;
+    try {
+        raw = await readFile(join(root, "package.json"), "utf8");
+    }
+    catch {
+        throw new Error(`no package.json found in ${root} — run init at the target's root`);
+    }
+    return JSON.parse(raw);
+}
+async function detectPackageManager(root) {
+    for (const [lockfile, manager] of LOCKFILES) {
+        if (await exists(join(root, lockfile)))
+            return manager;
+    }
+    return "npm";
+}
+async function provision(root, existingNames, writeName, content) {
+    for (const name of existingNames) {
+        if (await exists(join(root, name)))
+            return { file: name, action: "kept" };
+    }
+    await writeFile(join(root, writeName), content());
+    return { file: writeName, action: "written" };
+}
+function installCommandFor(manager, deps) {
+    const subcommand = manager === "npm" ? "install -D" : manager === "bun" ? "add -d" : "add -D";
+    return `${manager} ${subcommand} ${deps.join(" ")}`;
+}
+function runInstall(root, command) {
+    const [manager, ...args] = command.split(" ");
+    const result = spawnSync(manager, args, { cwd: root, encoding: "utf8" });
+    if (result.error)
+        throw new Error(`${command} failed: ${result.error.message}`);
+    if (result.status !== 0)
+        throw new Error(`${command} failed (exit ${result.status}):\n${result.stderr}`);
+}
+function withoutVersion(spec) {
+    return spec.slice(0, spec.lastIndexOf("@"));
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lint.js

@@ -0,0 +1,20 @@
+import { readFile, stat } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { discoverSpecs } from "./discover.js";
+import { parseSpec } from "./spec.js";
+import { runRules } from "./rules/src/index.js";
+export async function lint(target) {
+    const abs = resolve(target);
+    let stats;
+    try {
+        stats = await stat(abs);
+    }
+    catch {
+        throw new Error(`path not found: ${target}`);
+    }
+    const root = stats.isFile() ? dirname(abs) : abs;
+    const files = stats.isFile() ? [basename(abs)] : await discoverSpecs(root);
+    const specs = await Promise.all(files.map(async (file) => parseSpec(await readFile(join(root, file), "utf8"), file)));
+    const violations = runRules(specs);
+    return { root, files, violations, clean: violations.length === 0 };
+}

package/dist/mutation.js

@@ -0,0 +1,103 @@
+/**
+ * The slice of the Stryker JSON report (mutation-testing-elements schema) the join needs.
+ * `killedBy` is deliberately absent: a kill counts for every covering criterion, so only
+ * the status matters (ADR-0011).
+ */
+/** Every status the schema defines. Killed and Timeout are kills; the rest are not. */
+const STATUSES = [
+    "Killed",
+    "Survived",
+    "NoCoverage",
+    "CompileError",
+    "RuntimeError",
+    "Timeout",
+    "Ignored",
+    "Pending",
+];
+const KILLED = new Set(["Killed", "Timeout"]);
+/** A mutant Stryker actually ran: it either died or survived. The others cannot be scored. */
+const SCORED = new Set(["Killed", "Survived", "Timeout"]);
+export function isKill(status) {
+    return KILLED.has(status);
+}
+export function isScored(status) {
+    return SCORED.has(status);
+}
+export function parseMutationReport(json, source) {
+    const fail = (detail) => {
+        throw new Error(`${source} is not a Stryker mutation report: ${detail}`);
+    };
+    if (!isRecord(json))
+        return fail("expected a JSON object");
+    const files = json.files;
+    if (!isRecord(files))
+        return fail("missing `files`");
+    const mutants = [];
+    for (const [file, entry] of Object.entries(files)) {
+        if (!isRecord(entry))
+            return fail(`\`files["${file}"]\` is not an object`);
+        const list = entry.mutants;
+        if (!Array.isArray(list))
+            return fail(`\`files["${file}"].mutants\` is not an array`);
+        for (const raw of list) {
+            if (!isRecord(raw))
+                return fail(`a mutant in "${file}" is not an object`);
+            const id = raw.id;
+            if (typeof id !== "string")
+                return fail(`a mutant in "${file}" has no string \`id\``);
+            const status = raw.status;
+            if (!isStatus(status))
+                return fail(`mutant ${id} has unknown status ${String(status)}`);
+            const start = isRecord(raw.location) ? raw.location.start : undefined;
+            if (!isRecord(start) || typeof start.line !== "number") {
+                return fail(`mutant ${id} has no \`location.start.line\``);
+            }
+            const replacement = raw.replacement;
+            mutants.push({
+                id,
+                file,
+                line: start.line,
+                column: typeof start.column === "number" ? start.column : 0,
+                mutator: typeof raw.mutatorName === "string" ? raw.mutatorName : "unknown",
+                replacement: typeof replacement === "string" ? replacement : undefined,
+                status,
+                static: raw.static === true,
+                coveredBy: stringArray(raw.coveredBy),
+            });
+        }
+    }
+    const testNames = new Map();
+    const testFiles = json.testFiles;
+    if (isRecord(testFiles)) {
+        for (const entry of Object.values(testFiles)) {
+            if (!isRecord(entry))
+                continue;
+            const tests = entry.tests;
+            if (!Array.isArray(tests))
+                continue;
+            for (const test of tests) {
+                if (!isRecord(test))
+                    continue;
+                const { id, name } = test;
+                if (typeof id === "string" && typeof name === "string")
+                    testNames.set(id, name);
+            }
+        }
+    }
+    const config = json.config;
+    const coverageAnalysis = isRecord(config) ? config.coverageAnalysis : undefined;
+    return {
+        mutants,
+        testNames,
+        coverageAnalysis: typeof coverageAnalysis === "string" ? coverageAnalysis : undefined,
+    };
+}
+function isStatus(value) {
+    return STATUSES.includes(value);
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/render.js

@@ -0,0 +1,209 @@
+export function renderCheck(report) {
+    const lines = [
+        `mutation  ${describeReport(report.mutation)}`,
+        `coverage  ${describeReport(report.coverage)}`,
+    ];
+    const ready = report.mutation.status === "fresh" && report.coverage.status === "fresh";
+    if (!ready) {
+        lines.push("reports must be regenerated before the heatmap is worth reading");
+    }
+    else if (report.evaluated) {
+        lines.push("already evaluated — nothing new to read");
+    }
+    else {
+        lines.push(`fresh and unread — touch ${report.marker} after evaluating the heatmap`);
+    }
+    return lines.join("\n");
+}
+function describeReport(check) {
+    if (check.status === "missing")
+        return `${check.path} — missing`;
+    if (check.status === "stale")
+        return `${check.path} — stale (${check.staleAgainst} is newer)`;
+    return `${check.path} — fresh`;
+}
+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)));
+    const lines = [];
+    for (const feature of report.features) {
+        lines.push(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("");
+    }
+    if (report.testFiles.length === 0) {
+        lines.push(`no test files matched the ${report.dialect} dialect`);
+        lines.push("");
+    }
+    if (report.unclaimed.length > 0) {
+        lines.push("unclaimed — no test name carries these tokens");
+        for (const id of report.unclaimed)
+            lines.push(`  ${id}`);
+        lines.push("");
+    }
+    if (report.unknownClaims.length > 0) {
+        lines.push("unknown claims — test names claim criteria that no spec declares");
+        for (const claim of report.unknownClaims) {
+            lines.push(`  ${claim.id}  ${[...new Set(claim.tests.map((t) => t.file))].join(", ")}`);
+        }
+        lines.push("");
+    }
+    const total = report.features.reduce((n, f) => n + f.criteria.length, 0);
+    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`;
+    lines.push(report.clean ? `${counts}, clean` : counts);
+    return lines.join("\n");
+}
+export function renderInit(report) {
+    const lines = [];
+    for (const { file, action } of report.files) {
+        lines.push(action === "written" ? `wrote ${file}` : `kept ${file} — already present, left untouched`);
+    }
+    if (report.missingDeps.length === 0) {
+        lines.push("devDependencies already present");
+    }
+    else if (report.installRan) {
+        lines.push(`installed ${report.missingDeps.join(", ")}`);
+    }
+    else {
+        lines.push(`missing devDependencies — run: ${report.installCommand}`);
+    }
+    if (report.files.some((f) => f.action === "kept")) {
+        lines.push("");
+        lines.push("kept files must carry the strength stack themselves:");
+        lines.push('  stryker config: coverageAnalysis "perTest", the json reporter');
+        lines.push("  vitest config:  istanbul provider, json-summary reporter");
+    }
+    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.");
+    }
+    return lines.join("\n");
+}
+export function renderHuman(report) {
+    if (report.files.length === 0)
+        return "No SPEC.md files found.";
+    const lines = [];
+    if (report.violations.length > 0) {
+        const lineWidth = Math.max(...report.violations.map((v) => String(v.line).length));
+        const ruleWidth = Math.max(...report.violations.map((v) => v.rule.length));
+        let currentFile;
+        for (const v of report.violations) {
+            if (v.file !== currentFile) {
+                if (currentFile !== undefined)
+                    lines.push("");
+                lines.push(v.file);
+                currentFile = v.file;
+            }
+            lines.push(`  ${String(v.line).padStart(lineWidth)}  ${v.rule.padEnd(ruleWidth)}  ${v.message}`);
+        }
+        lines.push("");
+    }
+    const files = plural(report.files.length, "spec file");
+    lines.push(report.clean ? `${files}, clean` : `${files}, ${plural(report.violations.length, "violation")}`);
+    return lines.join("\n");
+}
+const BAR_WIDTH = 20;
+const STRONG = 0.9;
+const WEAK = 0.7;
+export function renderStrength(report, color = false) {
+    if (report.features.length === 0)
+        return "No SPEC.md files found.";
+    const paint = color ? ansi : (text, _code) => text;
+    const dim = (text) => paint(text, "2");
+    const tint = (value, text) => value === null ? dim(text) : paint(text, value >= STRONG ? "32" : value >= WEAK ? "33" : "31");
+    const idWidth = Math.max(...report.features.flatMap((f) => f.criteria.map((c) => c.id.length)), 0);
+    const out = [];
+    for (const feature of report.features) {
+        out.push(bold(feature.spec, color));
+        for (const criterion of feature.criteria) {
+            out.push(renderCriterion(criterion, idWidth, tint, dim));
+            for (const survivor of criterion.survivors)
+                out.push(`      ${renderSite(survivor, dim)}`);
+        }
+        out.push(`  ${dim(`line coverage ${percent(feature.lineCoverage)}`)}`);
+        out.push("");
+    }
+    if (report.unclaimed.length > 0) {
+        out.push(`${tint(0, "unclaimed")} ${dim("— no test carries these tokens")}`);
+        for (const id of report.unclaimed)
+            out.push(`  ${id}`);
+        out.push("");
+    }
+    if (report.unknownClaims.length > 0) {
+        out.push(`${tint(0, "unknown claims")} ${dim("— tests claim criteria that no spec declares")}`);
+        for (const id of report.unknownClaims)
+            out.push(`  ${id}`);
+        out.push("");
+    }
+    if (report.unclaimedMutants.length > 0) {
+        out.push(`${tint(0, "unclaimed mutants")} ${dim("— scored mutants no criterion's tests cover")}`);
+        for (const site of report.unclaimedMutants)
+            out.push(`  ${renderSite(site, dim)}`);
+        out.push("");
+    }
+    const staticSurvived = report.staticMutants.survivors.length;
+    const staticTotal = report.staticMutants.killed + staticSurvived;
+    if (staticTotal > 0) {
+        out.push(`${tint(staticSurvived === 0 ? 1 : 0, "static mutants")} ` +
+            dim("— run at module load, attributable to no criterion"));
+        out.push(`  ${report.staticMutants.killed} killed, ${staticSurvived} survived`);
+        for (const site of report.staticMutants.survivors)
+            out.push(`  ${renderSite(site, dim)}`);
+        out.push("");
+    }
+    const survivors = report.covered - report.killed + staticSurvived;
+    out.push(`oracle strength ${tint(report.strength, percent(report.strength))} ` +
+        `${dim(`(${report.killed}/${report.covered})`)}   ` +
+        `line coverage ${dim(percent(report.lineCoverage))}`);
+    out.push(survivors === 0
+        ? dim("no surviving mutants")
+        : `${plural(survivors, "surviving mutant")}${dim(" — each one a change no test noticed")}`);
+    return out.join("\n");
+}
+function renderCriterion(criterion, idWidth, tint, dim) {
+    const id = criterion.id.padEnd(idWidth);
+    const counts = `${criterion.killed}/${criterion.covered}`.padStart(7);
+    if (!criterion.claimed) {
+        return `  ${id}  ${dim("░".repeat(BAR_WIDTH))}  ${tint(0, "unclaimed".padStart(6))}  ${dim(counts)}  ${criterion.statement}`;
+    }
+    return (`  ${id}  ${tint(criterion.strength, bar(criterion.strength))}  ` +
+        `${tint(criterion.strength, percent(criterion.strength).padStart(6))}  ` +
+        `${dim(counts)}  ${criterion.statement}`);
+}
+function renderSite(site, dim) {
+    const at = `${site.file}:${site.line}:${site.column}`;
+    const change = site.replacement === undefined ? "" : ` → ${collapse(site.replacement)}`;
+    return dim(`${at}  ${site.mutator}${change}`);
+}
+/** Mutant replacements can be whole statements; the heatmap shows one line of them. */
+function collapse(replacement) {
+    const single = replacement.replace(/\s+/g, " ").trim();
+    return single.length > 48 ? `${single.slice(0, 47)}…` : single;
+}
+function bar(value) {
+    if (value === null)
+        return "░".repeat(BAR_WIDTH);
+    const filled = Math.round(value * BAR_WIDTH);
+    return "█".repeat(filled) + "░".repeat(BAR_WIDTH - filled);
+}
+function percent(value) {
+    return value === null ? "—" : `${(value * 100).toFixed(1)}%`;
+}
+function ansi(text, code) {
+    return `\x1b[${code}m${text}\x1b[0m`;
+}
+function bold(text, color) {
+    return color ? ansi(text, "1") : text;
+}
+function plural(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}

package/dist/rules/src/index.js

@@ -0,0 +1,10 @@
+import { RULE_IDS } from "../../violation.js";
+import { structuralRules } from "./structural.js";
+import { qualityRules } from "./quality.js";
+export function runRules(specs) {
+    const violations = [...structuralRules(specs), ...qualityRules(specs)];
+    return violations.sort((a, b) => a.file.localeCompare(b.file) ||
+        a.line - b.line ||
+        RULE_IDS.indexOf(a.rule) - RULE_IDS.indexOf(b.rule) ||
+        a.message.localeCompare(b.message));
+}