speccle 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Alton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# speccle
+
+The deterministic tooling the skills invoke: one bin, three commands —
+
+```
+speccle lint            # enforce the convention over a repo's specs
+speccle claims          # join criteria to the test names that claim them
+speccle strength        # oracle-strength heatmap: per-criterion killed ÷ covered
+speccle strength init   # provision the strength stack into a target
+```
+
+- `lint` — enforce the [convention](https://github.com/matthewalton/speccle/blob/main/docs/convention.md) over a repo's specs.
+- `claims` — join every criterion to the test names carrying its id, statically. No
+  reports needed, so it is cheap enough to gate on.
+- `strength` — join specs + Stryker mutation report + coverage into per-criterion
+  `killed ÷ covered`.
+- `strength init` — the setup `strength` measures against: install the stack's
+  devDependencies and write the preset configs.
+
+The bin is named after the package; every command is an explicit subcommand (a bare
+invocation is a usage error, exit code 2). `strength` names the measurement — oracle
+strength — not the heatmap rendering of it.
+
+Everything here is a **Speccle tool**: deterministic, independently runnable, emits
+typed JSON, never calls an LLM (see [CONTEXT.md](https://github.com/matthewalton/speccle/blob/main/CONTEXT.md)).
+
+## lint
+
+```sh
+speccle lint [path] [--json]
+```
+
+Lints every `SPEC.md` under `path` (default: current directory; a file path lints just
+that file) against the nine fixed rules in
+[docs/convention.md](https://github.com/matthewalton/speccle/blob/main/docs/convention.md) — six structural, three quality
+heuristics judging the heading statement only. One severity, no configuration.
+
+Output is human terminal text by default; `--json` emits the typed `LintReport`
+(see [`src/lint.ts`](src/lint.ts)) — the contract other tooling consumes. Exit codes:
+`0` clean, `1` violations, `2` usage error.
+
+## claims
+
+```sh
+speccle claims [path] [--json] [--dialect <name>]
+```
+
+Joins every criterion under `path` to the test names that claim it, read statically from
+the test files — no mutation or coverage reports, so it runs in seconds. A criterion no
+test name claims is **unclaimed**; a token claiming a criterion no spec declares is an
+**unknown claim**. Only test files under a spec's own folder count, so unrelated tooling
+tests can never phantom-claim.
+
+`--dialect` names the **test dialect**: which files are tests, and how a test's full name
+is read.
+
+| dialect               | test files                              | names read                                                             |
+| --------------------- | --------------------------------------- | ---------------------------------------------------------------------- |
+| `ts-vitest` (default) | `*.test.*`, `*.spec.*`                  | `describe` / `it` / `test` titles                                      |
+| `swift`               | `*Tests.swift`, anything under `Tests/` | `@Test("…")` / `@Suite("…")` display names, `func test…()` identifiers |
+
+Dialects are named and owned by speccle — a repo declares which one it is on,
+never how that dialect works, so a clean run means the same thing in every repo. An
+unsupported stack is a usage error, not a silent empty result. Where a framework gives a
+test no string name, the criterion id takes its identifier-safe spelling:
+`func test_CHECKOUT_1_taxRounds()` claims `CHECKOUT-1`. Reports always render the
+bracketed form.
+
+Names are read statically, so a name built dynamically shows up as unclaimed — the
+failure mode is a false alarm, never a silent pass. `--json` emits the typed
+`ClaimsReport` (see [`src/claims.ts`](src/claims.ts)). Exit codes: `0` every criterion
+claimed and no unknown claims, `1` otherwise, `2` usage error.
+
+## strength
+
+```sh
+speccle strength [path] [--json] [--mutation <file>] [--coverage <file>]
+```
+
+Joins three inputs into one number per **acceptance criterion**: the `SPEC.md` files under
+`path`, a StrykerJS mutation report, and an Istanbul `json-summary`. A test claims a
+criterion by carrying its `[KEY-n]` token anywhere in its full concatenated name, describe
+titles included.
+
+```
+features/checkout/SPEC.md
+  CHECKOUT-1  ████████████████████  100.0%    14/14  Tax rounds half-up to 2dp per line item
+  CHECKOUT-2  ████████████████████  100.0%      7/7  An empty basket totals zero
+  CHECKOUT-3  ██████████████████░░   88.2%    15/17  Checkout rejects a basket of more than 100 line items
+      features/checkout/checkout.ts:13:11  StringLiteral → ``
+      features/checkout/checkout.ts:14:17  StringLiteral → ""
+  line coverage 100.0%
+
+oracle strength 95.7% (44/46)   line coverage 100.0%
+2 surviving mutants — each one a change no test noticed
+```
+
+**Oracle strength** is `killed ÷ covered` — of the mutants a criterion's tests execute, the
+fraction the suite kills. A kill counts for every criterion covering that mutant, not only
+the one whose test detected it, so
+**a criterion below 100% always has at least one surviving mutant listed beneath it** —
+the exact code change no test noticed, which is what `strengthen` routes on. Line coverage
+sits alongside as the naïve baseline, precisely so the gap between them is visible.
+
+The command reads reports; it never runs Stryker. Defaults are `reports/mutation/mutation.json`
+and `coverage/coverage-summary.json`, relative to `path`. Mutants Stryker never ran
+(`NoCoverage`) or could not run (`CompileError`, `RuntimeError`, `Ignored`, `Pending`) are
+excluded from both sides of the ratio.
+
+The target project must run Stryker with `coverageAnalysis: "perTest"` — without it the
+report carries no `coveredBy`, and `strength` refuses rather than guessing. A criterion no
+test claims is reported as **unclaimed**, not as zero strength; tokens claiming a criterion
+no spec declares are reported too.
+
+`--json` emits the typed `StrengthReport` (see [`src/strength.ts`](src/strength.ts)). The
+command exits `0` whenever it produced a report — judging a diff against a threshold is a
+separate concern.
+
+## strength init
+
+```sh
+speccle strength init [path] [--json] [--skip-install] [--mutate <glob>]...
+```
+
+Provisions the stack `strength` measures against — the explicit command the
+`strengthen` skill offers when a target is missing pieces,
+instead of a hand-assembled config recipe. In one run it:
+
+- installs the missing devDependencies — `speccle` itself, caret-pinned to the
+  running oracle's own version, plus the stack pinned to the majors the join is proven
+  on (`vitest@^4`, `@vitest/coverage-istanbul@^4`, `@stryker-mutator/core@^9`,
+  `@stryker-mutator/vitest-runner@^9`) — using the package manager the target's
+  lockfile names (pnpm / npm / yarn / bun);
+- writes `stryker.config.json` with the load-bearing preset fields —
+  `coverageAnalysis: "perTest"` and the `json` reporter at
+  `reports/mutation/mutation.json` (the paths `strength` reads by default) — and mutate
+  globs derived from the `SPEC.md` folders under `path` (no specs yet →
+  `features/**/*.ts`; override with `--mutate`, repeatable);
+- writes a `vitest.config.ts` with the istanbul provider and `json-summary` reporter.
+
+Init also warns (best-effort, via `~/.claude/settings.json`) when the target vendors
+the speccle skills project-level in `.claude/skills/` while a user-level speccle plugin
+is still enabled — two copies of every skill would load.
+
+An existing Stryker or vitest/vite config is **kept, never overwritten** — init reports
+it and names the fields it must carry itself. The command is idempotent: re-running
+changes nothing that is already in place. `--skip-install` reports the install command
+instead of running it; `--json` emits the typed `InitReport` (see
+[`src/init.ts`](src/init.ts)). Running init at a target's root **is** the consent to
+write there — there is no postinstall hook or implicit trigger. Exit codes: `0` done,
+`2` usage error (including a `path` with no `package.json`).
+
+After init, the loop is the standard one:
+
+```sh
+npx vitest run --coverage    # → coverage/coverage-summary.json
+npx stryker run              # → reports/mutation/mutation.json
+speccle strength .
+```
+
+Repo-specific blind spots stay the target's decision: edit the written config's `mutate`
+globs to exclude what mutation can't reach (e.g. entry files only exercised through
+child processes).
+
+## Development
+
+TypeScript ESM, zero runtime dependencies. Node ≥ 24 runs the sources directly:
+
+```sh
+node src/cli.ts lint ../../targets/checkout   # no build needed
+pnpm test                                  # vitest: unit + e2e
+pnpm build                                 # tsc → dist/ (what the bin points at)
+```
+
+Spec parsing lives in [`src/spec.ts`](src/spec.ts), written once and shared by lint
+and the heatmap. The [toy target project](https://github.com/matthewalton/speccle/blob/main/targets/checkout) is the clean
+proving ground; the dirty regression fixtures live in
+[`test/fixtures`](test/fixtures).

package/dist/check.js

@@ -0,0 +1,74 @@
+import { stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { discoverFiles, discoverSpecs } from "./discover.js";
+import { DEFAULT_COVERAGE_SUMMARY, DEFAULT_MUTATION_REPORT } from "./strength.js";
+export async function check(target, options = {}) {
+    const root = resolve(target);
+    if (!(await isDirectory(root)))
+        throw new Error(`path not found: ${target}`);
+    const mutationPath = resolve(root, options.mutationReport ?? DEFAULT_MUTATION_REPORT);
+    const coveragePath = resolve(root, options.coverageSummary ?? DEFAULT_COVERAGE_SUMMARY);
+    const markerPath = join(dirname(mutationPath), ".speccle-evaluated");
+    const newest = await newestSliceFile(root, new Set([mutationPath, coveragePath, markerPath]));
+    const mutation = await checkReport(root, mutationPath, newest);
+    const coverage = await checkReport(root, coveragePath, newest);
+    const markerTime = await mtime(markerPath);
+    const mutationTime = await mtime(mutationPath);
+    const coverageTime = await mtime(coveragePath);
+    const evaluated = markerTime !== undefined &&
+        mutationTime !== undefined &&
+        coverageTime !== undefined &&
+        markerTime >= mutationTime &&
+        markerTime >= coverageTime;
+    return { root, mutation, coverage, evaluated, marker: rel(root, markerPath) };
+}
+/** The newest file in any spec's folder subtree — what a report must post-date. */
+async function newestSliceFile(root, exclude) {
+    const folders = new Set((await discoverSpecs(root)).map((spec) => dirname(spec)));
+    const seen = new Set();
+    let newest;
+    for (const folder of folders) {
+        const abs = folder === "." ? root : join(root, folder);
+        for (const file of await discoverFiles(abs, () => true)) {
+            const relPath = folder === "." ? file : `${folder}/${file}`;
+            const absPath = join(abs, file);
+            if (seen.has(relPath) || exclude.has(absPath))
+                continue;
+            seen.add(relPath);
+            const mtimeMs = await mtime(absPath);
+            if (mtimeMs === undefined)
+                continue;
+            if (newest === undefined || mtimeMs > newest.mtimeMs)
+                newest = { file: relPath, mtimeMs };
+        }
+    }
+    return newest;
+}
+async function checkReport(root, path, newest) {
+    const reportTime = await mtime(path);
+    if (reportTime === undefined)
+        return { path: rel(root, path), status: "missing" };
+    if (newest !== undefined && newest.mtimeMs > reportTime) {
+        return { path: rel(root, path), status: "stale", staleAgainst: newest.file };
+    }
+    return { path: rel(root, path), status: "fresh" };
+}
+async function mtime(path) {
+    try {
+        return (await stat(path)).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function rel(root, path) {
+    return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+}

package/dist/claims.js

@@ -0,0 +1,80 @@
+import { readFile, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { DEFAULT_DIALECT, resolveDialect } from "./dialects.js";
+import { discoverSpecs, discoverTests } from "./discover.js";
+import { compareCriterionIds, parseSpec, readClaimedIds } from "./spec.js";
+export async function claims(target, options = {}) {
+    const dialect = resolveDialect(options.dialect ?? DEFAULT_DIALECT);
+    const root = resolve(target);
+    if (!(await isDirectory(root)))
+        throw new Error(`path not found: ${target}`);
+    const specFiles = await discoverSpecs(root);
+    const specs = await Promise.all(specFiles.map(async (file) => parseSpec(await readFile(join(root, file), "utf8"), file)));
+    const criteria = new Map();
+    for (const spec of specs) {
+        for (const criterion of spec.criteria) {
+            if (criterion.wellFormed && !criteria.has(criterion.id)) {
+                criteria.set(criterion.id, { statement: criterion.statement, spec: spec.file });
+            }
+        }
+    }
+    // A slice's tests live in its own folder: only test files under a spec's folder
+    // count, so unrelated tooling tests can never claim (or phantom-claim) a criterion.
+    const folders = [...new Set(specFiles.map((file) => dirname(file)))];
+    const found = new Set();
+    for (const folder of folders) {
+        const abs = folder === "." ? root : join(root, folder);
+        for (const file of await discoverTests(abs, dialect)) {
+            found.add(folder === "." ? file : `${folder}/${file}`);
+        }
+    }
+    const testFiles = [...found].sort();
+    const claimsById = new Map();
+    for (const file of testFiles) {
+        const source = await readFile(join(root, file), "utf8");
+        for (const { name, spelling } of dialect.readTestNames(source)) {
+            for (const id of readClaimedIds(name, spelling)) {
+                const entry = claimsById.get(id) ?? [];
+                entry.push({ file, name });
+                claimsById.set(id, entry);
+            }
+        }
+    }
+    const features = specs.map((spec) => ({
+        key: spec.key?.raw,
+        spec: spec.file,
+        criteria: [...criteria.entries()]
+            .filter(([, value]) => value.spec === spec.file)
+            .map(([id, value]) => ({
+            id,
+            statement: value.statement,
+            claimed: claimsById.has(id),
+            tests: claimsById.get(id) ?? [],
+        }))
+            .sort((a, b) => compareCriterionIds(a.id, b.id)),
+    }));
+    const unclaimed = [...criteria.keys()]
+        .filter((id) => !claimsById.has(id))
+        .sort(compareCriterionIds);
+    const unknownClaims = [...claimsById.entries()]
+        .filter(([id]) => !criteria.has(id))
+        .map(([id, tests]) => ({ id, tests }))
+        .sort((a, b) => compareCriterionIds(a.id, b.id));
+    return {
+        root,
+        dialect: dialect.name,
+        testFiles,
+        features,
+        unclaimed,
+        unknownClaims,
+        clean: unclaimed.length === 0 && unknownClaims.length === 0,
+    };
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+import { check } from "./check.js";
+import { claims } from "./claims.js";
+import { DEFAULT_DIALECT, DIALECT_NAMES } from "./dialects.js";
+import { init } from "./init.js";
+import { lint } from "./lint.js";
+import { renderCheck, renderClaims, renderHuman, renderInit, renderStrength } from "./render.js";
+import { DEFAULT_COVERAGE_SUMMARY, DEFAULT_MUTATION_REPORT, strength } from "./strength.js";
+const USAGE = `Usage: speccle <command> [options]
+
+Commands:
+  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
+  strength [path] [--json]       Oracle-strength heatmap: per-criterion killed ÷ covered
+  strength init [path] [--json]  Provision the strength stack: devDependencies + configs
+
+claims options:
+  --dialect <name>    Test dialect: ${DIALECT_NAMES.join(", ")} (default: ${DEFAULT_DIALECT})
+
+strength options:
+  --check             Report whether the reports are fresh, stale, or missing — never runs them
+  --mutation <file>   Stryker JSON report   (default: ${DEFAULT_MUTATION_REPORT})
+  --coverage <file>   Istanbul json-summary (default: ${DEFAULT_COVERAGE_SUMMARY})
+
+strength init options:
+  --mutate <glob>     Mutate glob for the Stryker config, repeatable
+                      (default: derived from the SPEC.md folders under path)
+  --skip-install      Report the install command instead of running it
+
+Exit codes: 0 clean, 1 violations, 2 usage error`;
+async function main(argv) {
+    const [command, ...rest] = argv;
+    if (command === "lint")
+        return runLint(rest);
+    if (command === "claims")
+        return runClaims(rest);
+    if (command === "strength" && rest[0] === "init")
+        return runInit(rest.slice(1));
+    if (command === "strength")
+        return runStrength(rest);
+    console.error(USAGE);
+    return 2;
+}
+async function runClaims(args) {
+    let json = false;
+    let dialect;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--dialect") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`--dialect needs a dialect name\n\n${USAGE}`);
+                return 2;
+            }
+            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(`claims takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await claims(positional[0] ?? ".", { ...(dialect !== undefined && { dialect }) });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderClaims(report));
+    return report.clean ? 0 : 1;
+}
+async function runLint(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(`lint takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await lint(positional[0] ?? ".");
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderHuman(report));
+    return report.clean ? 0 : 1;
+}
+async function runStrength(args) {
+    let json = false;
+    let checkOnly = false;
+    let mutationReport;
+    let coverageSummary;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--check")
+            checkOnly = true;
+        else if (arg === "--mutation" || arg === "--coverage") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs a file path\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--mutation")
+                mutationReport = value;
+            else
+                coverageSummary = 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(`strength takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    const options = {
+        ...(mutationReport !== undefined && { mutationReport }),
+        ...(coverageSummary !== undefined && { coverageSummary }),
+    };
+    if (checkOnly) {
+        let checkReport;
+        try {
+            checkReport = await check(positional[0] ?? ".", options);
+        }
+        catch (err) {
+            console.error(message(err));
+            return 2;
+        }
+        console.log(json ? JSON.stringify(checkReport, null, 2) : renderCheck(checkReport));
+        return checkReport.mutation.status === "fresh" && checkReport.coverage.status === "fresh"
+            ? 0
+            : 1;
+    }
+    let report;
+    try {
+        report = await strength(positional[0] ?? ".", options);
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    const color = process.stdout.isTTY && process.env.NO_COLOR === undefined;
+    console.log(json ? JSON.stringify(report, null, 2) : renderStrength(report, color));
+    return 0;
+}
+async function runInit(args) {
+    let json = false;
+    let skipInstall = false;
+    const mutate = [];
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--skip-install")
+            skipInstall = true;
+        else if (arg === "--mutate") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`--mutate needs a glob\n\n${USAGE}`);
+                return 2;
+            }
+            mutate.push(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(`strength init takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await init(positional[0] ?? ".", { mutate, skipInstall });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderInit(report));
+    return 0;
+}
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+process.exitCode = await main(process.argv.slice(2));

package/dist/coverage.js

@@ -0,0 +1,48 @@
+import { isAbsolute, relative, resolve } from "node:path";
+export function parseCoverageSummary(json, root, source) {
+    if (!isRecord(json)) {
+        throw new Error(`${source} is not an Istanbul json-summary report: expected a JSON object`);
+    }
+    const files = new Map();
+    let total;
+    for (const [key, entry] of Object.entries(json)) {
+        const lines = isRecord(entry) ? readLines(entry.lines) : undefined;
+        if (!lines)
+            continue;
+        if (key === "total")
+            total = lines;
+        else
+            files.set(toRootRelative(key, root), lines);
+    }
+    return { files, total };
+}
+/** Sums the files under `dir`; undefined when the summary knows nothing about it. */
+export function coverageUnder(summary, dir) {
+    const prefix = dir === "" ? "" : `${dir}/`;
+    let covered = 0;
+    let total = 0;
+    let matched = false;
+    for (const [file, lines] of summary.files) {
+        if (!file.startsWith(prefix))
+            continue;
+        matched = true;
+        covered += lines.covered;
+        total += lines.total;
+    }
+    return matched ? { covered, total } : undefined;
+}
+function readLines(value) {
+    if (!isRecord(value))
+        return undefined;
+    const { covered, total } = value;
+    if (typeof covered !== "number" || typeof total !== "number")
+        return undefined;
+    return { covered, total };
+}
+function toRootRelative(key, root) {
+    const rel = isAbsolute(key) ? relative(root, key) : relative(root, resolve(root, key));
+    return rel.split(/[\\/]/).join("/");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/dialects.js

@@ -0,0 +1,43 @@
+const TS_TEST_FILE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+const TS_TEST_TITLE = /\b(?:describe|it|test)(?:\.[\w.]+)*\s*\(\s*(["'`])((?:\\.|(?!\1).)*)\1/g;
+const TS_VITEST = {
+    name: "ts-vitest",
+    isTestFile: (file) => TS_TEST_FILE.test(file),
+    readTestNames: (source) => [...source.matchAll(TS_TEST_TITLE)].map((m) => ({ name: m[2], spelling: "bracketed" })),
+};
+/** `LadderTests.swift` — or any `.swift` file under a `Tests` directory. */
+const SWIFT_TEST_FILE = /Tests?\.swift$/;
+/** Swift Testing display names — `@Test("…")`, `@Suite("…")`: the string is the name. */
+const SWIFT_DISPLAY_NAME = /@(?:Test|Suite)\s*\(\s*"((?:\\.|[^"\\])*)"/g;
+/** XCTest methods: the name is the identifier, so the id takes its identifier-safe spelling. */
+const XCTEST_METHOD = /\bfunc\s+(test[A-Za-z0-9_]*)\s*\(/g;
+/** A `@Test`/`@Suite` declaration carrying no display name — its identifier is the name. */
+const SWIFT_ANNOTATED_DECL = /@(?:Test|Suite)\b(?!\s*\(\s*")(?:\s*\([^()]*\))?(?:\s+(?:@\w+|open|public|internal|fileprivate|private|final|static))*\s+(?:actor|class|enum|func|struct)\s+([A-Za-z_]\w*)/g;
+const SWIFT = {
+    name: "swift",
+    isTestFile: (file) => SWIFT_TEST_FILE.test(file) || (file.endsWith(".swift") && file.split("/").includes("Tests")),
+    readTestNames(source) {
+        const found = [...source.matchAll(SWIFT_DISPLAY_NAME)].map((m) => ({ at: m.index, name: m[1], spelling: "bracketed" }));
+        // The two identifier scans overlap on an annotated `func test…`, and an identifier
+        // names exactly one declaration, so the same name is never read twice.
+        const seen = new Set();
+        for (const m of [...source.matchAll(XCTEST_METHOD), ...source.matchAll(SWIFT_ANNOTATED_DECL)]) {
+            if (seen.has(m[1]))
+                continue;
+            seen.add(m[1]);
+            found.push({ at: m.index, name: m[1], spelling: "identifier" });
+        }
+        return found.sort((a, b) => a.at - b.at).map(({ name, spelling }) => ({ name, spelling }));
+    },
+};
+const DIALECTS = new Map([TS_VITEST, SWIFT].map((dialect) => [dialect.name, dialect]));
+export const DEFAULT_DIALECT = TS_VITEST.name;
+export const DIALECT_NAMES = [...DIALECTS.keys()];
+/** An unsupported stack is unsupported, and says so (ADR-0038). */
+export function resolveDialect(name) {
+    const dialect = DIALECTS.get(name);
+    if (!dialect) {
+        throw new Error(`unknown test dialect: ${name} — known dialects: ${DIALECT_NAMES.join(", ")}`);
+    }
+    return dialect;
+}