speccle 0.11.0

package/dist/rules/src/quality.js

@@ -0,0 +1,259 @@
+/** Quality rules judge the heading statement only — the body is never linted (ADR-0007). */
+export function qualityRules(specs) {
+    const out = [];
+    for (const spec of specs) {
+        for (const c of spec.criteria) {
+            if (!c.wellFormed)
+                continue;
+            // Stryker disable next-line all: an empty statement yields no quality violation; the skip only saves work
+            if (c.statement === "")
+                continue;
+            out.push(...weaselWording(spec, c), ...compoundCriterion(spec, c), ...unmeasurable(spec, c), ...codeVoice(spec, c));
+        }
+    }
+    return out;
+}
+/** Contract, not config: extending this list means changing docs/convention.md. */
+export const WEASEL_TERMS = [
+    "should",
+    "appropriately",
+    "properly",
+    "correctly",
+    "gracefully",
+    "seamlessly",
+    "efficiently",
+    "effectively",
+    "robust",
+    "robustly",
+    "reasonable",
+    "reasonably",
+    "adequate",
+    "adequately",
+    "sufficient",
+    "sufficiently",
+    "fast",
+    "quickly",
+    "performant",
+    "user-friendly",
+    "intuitive",
+    "easy",
+    "easily",
+    "simple",
+    "simply",
+    "flexible",
+    "sane",
+    "sensible",
+    "as needed",
+    "as appropriate",
+    "as expected",
+    "if necessary",
+    "if needed",
+    "when possible",
+    "where applicable",
+    "etc",
+    "and so on",
+    "works well",
+];
+const WEASEL_MATCHERS = WEASEL_TERMS.map((term) => ({
+    term,
+    regex: wordBoundaryRegex(term),
+}));
+function weaselWording(spec, c) {
+    const target = stripCodeSpans(c.statement);
+    return WEASEL_MATCHERS.filter(({ regex }) => regex.test(target)).map(({ term }) => ({
+        rule: "weasel-wording",
+        file: spec.file,
+        line: c.line,
+        message: `weasel wording: "${term}"`,
+    }));
+}
+/** One bare "and"/"or" never flags — a compound noun phrase names one thing. */
+const COMPOUND_SIGNALS = [
+    { regex: /;/, message: () => "a semicolon joins independent clauses" },
+    {
+        regex: /,\s+(and|or)\b/i,
+        message: (m) => `a comma before "${m[1].toLowerCase()}" joins independent clauses`,
+    },
+    {
+        regex: /\b(and also|as well as)\b/i,
+        message: (m) => `"${m[1].toLowerCase()}" joins independent clauses`,
+    },
+    // \s, not \s+: .test() treats them identically and \s+ leaves an unkillable mutant
+    { regex: /[.!?]\s/, message: () => "a second sentence starts mid-statement" },
+];
+const ABBREVIATIONS = /\b(e\.g\.|i\.e\.|vs\.|etc\.)/gi;
+const BARE_CONJUNCTION = /\b(and|or)\b/gi;
+function compoundCriterion(spec, c) {
+    const target = stripCodeSpans(c.statement).replace(ABBREVIATIONS, " ");
+    for (const signal of COMPOUND_SIGNALS) {
+        const match = signal.regex.exec(target);
+        if (match) {
+            return [
+                {
+                    rule: "compound-criterion",
+                    file: spec.file,
+                    line: c.line,
+                    message: `compound criterion: ${signal.message(match)}`,
+                },
+            ];
+        }
+    }
+    const second = secondBareConjunction(target);
+    if (second !== null) {
+        return [
+            {
+                rule: "compound-criterion",
+                file: spec.file,
+                line: c.line,
+                message: `compound criterion: a second bare "${second}" joins another clause`,
+            },
+        ];
+    }
+    return [];
+}
+/** Two bare conjunctions in the main clause read as a list of behaviours. Conjunctions
+ *  inside a condition ("when the card is expired and the retry limit is reached")
+ *  qualify one outcome and are not counted. */
+function secondBareConjunction(target) {
+    const mainClause = target.split(SUBORDINATOR)[0] ?? "";
+    // Stryker disable next-line ArrayDeclaration: the fallback is read only for its length, and a planted element still leaves it under two
+    const conjunctions = mainClause.match(BARE_CONJUNCTION) ?? [];
+    return conjunctions.length >= 2 ? conjunctions[1].toLowerCase() : null;
+}
+/**
+ * Predicates that name activity without naming an outcome. Contract, not config: this is
+ * the whole of what `unmeasurable` knows, so the rule under-flags rather than gatekeeping
+ * a spec's vocabulary — an unrecognised domain verb ("a refund credits the customer") is
+ * measurable and passes.
+ */
+export const VACUOUS_PREDICATES = [
+    "is handled",
+    "are handled",
+    "is supported",
+    "are supported",
+    "is implemented",
+    "are implemented",
+    "is done",
+    "are done",
+    "is correct",
+    "are correct",
+    "is responsible for",
+    "are responsible for",
+    "works",
+    "working",
+    "behaves",
+    "happens",
+    "occurs",
+    "handles",
+    "supports",
+    "deals with",
+    "takes care of",
+];
+export const OUTCOME_COMPARATORS = [
+    "at least",
+    "at most",
+    "no more than",
+    "more than",
+    "fewer than",
+    "less than",
+    "exactly",
+    "only when",
+    "only if",
+    "never",
+    "always",
+    "within",
+    "empty",
+    "non-empty",
+    "null",
+    "true",
+    "false",
+    "zero",
+    "once",
+    "unchanged",
+];
+const VACUOUS_MATCHERS = VACUOUS_PREDICATES.map((predicate) => ({
+    predicate,
+    regex: wordBoundaryRegex(predicate),
+}));
+const COMPARATOR_MATCHERS = OUTCOME_COMPARATORS.map(wordBoundaryRegex);
+const QUANTITY = /\d|%/;
+const SUBORDINATOR = /\b(?:when|whenever|if|unless|after|before|while|until|once|given)\b/i;
+/**
+ * A trailing `is <adjective>` names a property. Lowercase-only: a capitalised word is a
+ * literal ("the response is JSON"), as is a code span, which is stripped before matching.
+ * An `-ed` word is a participle naming an outcome ("the order is cancelled").
+ */
+const COPULA_PROPERTY = /\b(?:is|are)\s+(?:not\s+)?([a-z][a-z-]*)\s*$/;
+function unmeasurable(spec, c) {
+    const target = stripCodeSpans(c.statement);
+    const vacuous = VACUOUS_MATCHERS.find(({ regex }) => regex.test(target));
+    const message = vacuous
+        ? `no measurable outcome: "${vacuous.predicate}" asserts nothing observable`
+        : namesOnlyAProperty(target)
+            ? "no measurable outcome: names a property, not an observable outcome"
+            : null;
+    if (message === null)
+        return [];
+    return [{ rule: "unmeasurable", file: spec.file, line: c.line, message }];
+}
+/** Only the main clause is judged — a copula inside a condition ("when the basket is large")
+ *  qualifies an outcome asserted elsewhere in the statement. */
+function namesOnlyAProperty(target) {
+    if (QUANTITY.test(target) || COMPARATOR_MATCHERS.some((regex) => regex.test(target))) {
+        return false;
+    }
+    const mainClause = target.split(SUBORDINATOR)[0] ?? target;
+    const match = COPULA_PROPERTY.exec(mainClause);
+    return match !== null && !match[1].endsWith("ed");
+}
+const CODE_SPAN = /`[^`]*`/;
+/** Contract, not config: extending this list means changing docs/convention.md. */
+export const FILE_EXTENSIONS = [
+    "cjs",
+    "css",
+    "html",
+    "js",
+    "json",
+    "jsx",
+    "md",
+    "mjs",
+    "sh",
+    "toml",
+    "ts",
+    "tsx",
+    "txt",
+    "yaml",
+    "yml",
+];
+const FILE_PATH = new RegExp(`\\b[\\w./-]*\\.(?:${FILE_EXTENSIONS.join("|")})\\b`);
+/**
+ * camelCase (two or more leading lowercase letters, so brand names like iPhone pass),
+ * snake_case, or call parentheses. Plain acronyms (JSON, HTTP) pass — under-flagging
+ * by design, like `unmeasurable`.
+ */
+const IDENTIFIER = /\b(?:[a-z][a-z0-9]+[A-Z][A-Za-z0-9]*|\w+_\w+|[A-Za-z_$][\w$]*\([^()]*\))/;
+/** Judges the raw statement: here a code span is the strongest signal, not a literal. */
+function codeVoice(spec, c) {
+    const signal = codeVoiceSignal(c.statement);
+    if (signal === null)
+        return [];
+    return [{ rule: "code-voice", file: spec.file, line: c.line, message: `code voice: ${signal}` }];
+}
+function codeVoiceSignal(statement) {
+    const span = CODE_SPAN.exec(statement);
+    if (span)
+        return `code span ${span[0]} belongs in the criterion body`;
+    const path = FILE_PATH.exec(statement);
+    if (path)
+        return `file path "${path[0]}" belongs in the criterion body`;
+    const identifier = IDENTIFIER.exec(statement);
+    if (identifier)
+        return `identifier "${identifier[0]}" belongs in the criterion body`;
+    return null;
+}
+function stripCodeSpans(text) {
+    return text.replace(/`[^`]*`/g, " ");
+}
+function wordBoundaryRegex(term) {
+    return new RegExp(`\\b${term.replace(/[-\s]/g, "[-\\s]")}\\b`, "i");
+}

package/dist/rules/src/structural.js

@@ -0,0 +1,119 @@
+export function structuralRules(specs) {
+    return [
+        ...missingKey(specs),
+        ...keyCollision(specs),
+        ...keyMismatch(specs),
+        ...malformedId(specs),
+        ...duplicateId(specs),
+        ...emptyStatement(specs),
+    ];
+}
+function missingKey(specs) {
+    return specs.flatMap((spec) => {
+        if (spec.key === undefined) {
+            return [
+                {
+                    rule: "missing-key",
+                    file: spec.file,
+                    line: 1,
+                    message: 'frontmatter "key" is missing',
+                },
+            ];
+        }
+        if (!spec.key.valid) {
+            return [
+                {
+                    rule: "missing-key",
+                    file: spec.file,
+                    line: spec.key.line,
+                    message: `frontmatter key "${spec.key.raw}" is malformed: expected [A-Z][A-Z0-9]{1,9}`,
+                },
+            ];
+        }
+        return [];
+    });
+}
+function keyCollision(specs) {
+    const byKey = new Map();
+    for (const spec of specs) {
+        if (spec.key?.valid) {
+            const group = byKey.get(spec.key.raw) ?? [];
+            group.push(spec);
+            byKey.set(spec.key.raw, group);
+        }
+    }
+    const out = [];
+    for (const [key, group] of byKey) {
+        if (group.length < 2)
+            continue;
+        for (const spec of group) {
+            const others = group.filter((s) => s !== spec).map((s) => s.file);
+            out.push({
+                rule: "key-collision",
+                file: spec.file,
+                line: spec.key.line,
+                message: `feature key "${key}" is also declared in ${others.join(", ")}`,
+            });
+        }
+    }
+    return out;
+}
+function keyMismatch(specs) {
+    return specs.flatMap((spec) => {
+        if (!spec.key?.valid)
+            return [];
+        const declared = spec.key.raw;
+        return wellFormed(spec)
+            .filter((c) => c.key !== declared)
+            .map((c) => ({
+            rule: "key-mismatch",
+            file: spec.file,
+            line: c.line,
+            message: `criterion id [${c.id}] does not match the feature key "${declared}"`,
+        }));
+    });
+}
+function malformedId(specs) {
+    return specs.flatMap((spec) => spec.criteria
+        .filter((c) => !c.wellFormed)
+        .map((c) => ({
+        rule: "malformed-id",
+        file: spec.file,
+        line: c.line,
+        message: `H2 "${c.heading}" has no well-formed [KEY-n] token`,
+    })));
+}
+function duplicateId(specs) {
+    const firstSeen = new Map();
+    const out = [];
+    for (const spec of specs) {
+        for (const c of wellFormed(spec)) {
+            const first = firstSeen.get(c.id);
+            if (first === undefined) {
+                firstSeen.set(c.id, { file: spec.file, line: c.line });
+            }
+            else {
+                out.push({
+                    rule: "duplicate-id",
+                    file: spec.file,
+                    line: c.line,
+                    message: `criterion id [${c.id}] is already used at ${first.file}:${first.line}`,
+                });
+            }
+        }
+    }
+    return out;
+}
+function emptyStatement(specs) {
+    return specs.flatMap((spec) => wellFormed(spec)
+        .filter((c) => c.statement === "")
+        .map((c) => ({
+        rule: "empty-statement",
+        file: spec.file,
+        line: c.line,
+        message: `criterion [${c.id}] has a token but no statement`,
+    })));
+}
+function wellFormed(spec) {
+    return spec.criteria.filter((c) => c.wellFormed);
+}

package/dist/spec.js

@@ -0,0 +1,88 @@
+export const KEY_PATTERN = /^[A-Z][A-Z0-9]{1,9}$/;
+const ID_TOKEN = /^\[([A-Z][A-Z0-9]{1,9})-([1-9][0-9]*)\]$/;
+/** A `[KEY-n]` token anywhere in a test's full concatenated name (ADR-0004). */
+export const CLAIM_TOKEN = /\[([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)\]/g;
+/**
+ * `KEY_n`, bounded by underscores or non-alphanumerics: `test_CHECKOUT_1_taxRounds`
+ * claims CHECKOUT-1, while `testCHECKOUT_1` and `CHECKOUT_1Fixture` do not.
+ */
+const IDENTIFIER_CLAIM_TOKEN = /(?<![A-Za-z0-9])([A-Z][A-Z0-9]{1,9})_([1-9][0-9]*)(?![A-Za-z0-9])/g;
+/** Every criterion id a test name claims, always in the bracketed `KEY-n` form. */
+export function readClaimedIds(name, spelling) {
+    if (spelling === "bracketed")
+        return [...name.matchAll(CLAIM_TOKEN)].map((m) => m[1]);
+    return [...name.matchAll(IDENTIFIER_CLAIM_TOKEN)].map((m) => `${m[1]}-${m[2]}`);
+}
+/** Sorts `KEY-n` ids by key, then numerically by n. */
+export function compareCriterionIds(a, b) {
+    const [aKey, aN] = splitId(a);
+    const [bKey, bN] = splitId(b);
+    return aKey === bKey ? aN - bN : aKey.localeCompare(bKey);
+}
+function splitId(id) {
+    const dash = id.lastIndexOf("-");
+    return [id.slice(0, dash), Number(id.slice(dash + 1))];
+}
+export function parseSpec(content, file) {
+    const lines = content.split(/\r?\n/);
+    let bodyStart = 0;
+    let key;
+    if (lines[0]?.trim() === "---") {
+        const close = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+        if (close > 0) {
+            bodyStart = close + 1;
+            for (let i = 1; i < close; i++) {
+                const match = /^key:\s*(.*)$/.exec(lines[i] ?? "");
+                if (match) {
+                    const raw = unquote(match[1].trim());
+                    key = { raw, line: i + 1, valid: KEY_PATTERN.test(raw) };
+                    break;
+                }
+            }
+        }
+    }
+    const criteria = [];
+    let fence;
+    for (let i = bodyStart; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        const fenceMatch = /^(`{3,}|~{3,})/.exec(line.trimStart());
+        if (fenceMatch) {
+            const marker = fenceMatch[1][0];
+            if (fence === undefined)
+                fence = marker;
+            else if (marker === fence)
+                fence = undefined;
+            continue;
+        }
+        if (fence !== undefined)
+            continue;
+        const h2 = /^##(?!#)\s+(.*?)\s*$/.exec(line);
+        if (!h2)
+            continue;
+        const heading = h2[1].replace(/\s+#+$/, "");
+        criteria.push(parseHeading(heading, i + 1));
+    }
+    return { file, key, criteria };
+}
+function parseHeading(heading, line) {
+    const token = /^(\[[^\]]*\])\s*(.*)$/.exec(heading);
+    if (token) {
+        const id = ID_TOKEN.exec(token[1]);
+        if (id) {
+            return {
+                wellFormed: true,
+                id: `${id[1]}-${id[2]}`,
+                key: id[1],
+                n: Number(id[2]),
+                statement: token[2].trim(),
+                line,
+                heading,
+            };
+        }
+    }
+    return { wellFormed: false, line, heading };
+}
+function unquote(value) {
+    const quoted = /^(["'])(.*)\1$/.exec(value);
+    return quoted ? quoted[2] : value;
+}

package/dist/strength.js

@@ -0,0 +1,187 @@
+import { readFile, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { coverageUnder, parseCoverageSummary } from "./coverage.js";
+import { discoverSpecs } from "./discover.js";
+import { isKill, isScored, parseMutationReport } from "./mutation.js";
+import { CLAIM_TOKEN, compareCriterionIds, parseSpec } from "./spec.js";
+export const DEFAULT_MUTATION_REPORT = "reports/mutation/mutation.json";
+export const DEFAULT_COVERAGE_SUMMARY = "coverage/coverage-summary.json";
+export async function strength(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 report = parseMutationReport(await readJson(mutationPath), rel(root, mutationPath));
+    if (report.coverageAnalysis !== undefined && report.coverageAnalysis !== "perTest") {
+        throw new Error(`${rel(root, mutationPath)} was produced with coverageAnalysis "${report.coverageAnalysis}"; ` +
+            `oracle strength needs "perTest" to know which tests covered each mutant`);
+    }
+    const coveragePath = resolve(root, options.coverageSummary ?? DEFAULT_COVERAGE_SUMMARY);
+    const coverage = await readCoverage(coveragePath, root);
+    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, { criterion, spec: spec.file });
+            }
+        }
+    }
+    const claimsByTest = new Map();
+    const claimedIds = new Set();
+    for (const [id, name] of report.testNames) {
+        const claims = [...name.matchAll(CLAIM_TOKEN)].map((m) => m[1]);
+        claimsByTest.set(id, claims);
+        for (const claim of claims)
+            claimedIds.add(claim);
+    }
+    const tally = new Map();
+    const featureTally = new Map();
+    let covered = 0;
+    let killed = 0;
+    const unclaimedMutants = [];
+    let staticKilled = 0;
+    const staticSurvivors = [];
+    for (const mutant of report.mutants) {
+        if (!isScored(mutant.status))
+            continue;
+        if (mutant.static) {
+            if (isKill(mutant.status))
+                staticKilled++;
+            else
+                staticSurvivors.push(toSite(mutant));
+            continue;
+        }
+        const claims = new Set();
+        for (const testId of mutant.coveredBy) {
+            for (const claim of claimsByTest.get(testId) ?? []) {
+                if (criteria.has(claim))
+                    claims.add(claim);
+            }
+        }
+        if (claims.size === 0) {
+            unclaimedMutants.push(toSite(mutant));
+            continue;
+        }
+        // ADR-0011: any test's kill counts for every criterion whose tests covered the mutant.
+        const kill = isKill(mutant.status);
+        covered++;
+        if (kill)
+            killed++;
+        for (const id of claims) {
+            const entry = tally.get(id) ?? { covered: 0, killed: 0, survivors: [] };
+            entry.covered++;
+            if (kill)
+                entry.killed++;
+            else
+                entry.survivors.push(toSite(mutant));
+            tally.set(id, entry);
+        }
+        const features = new Set([...claims].map((id) => criteria.get(id).spec));
+        for (const spec of features) {
+            const entry = featureTally.get(spec) ?? { covered: 0, killed: 0 };
+            entry.covered++;
+            if (kill)
+                entry.killed++;
+            featureTally.set(spec, entry);
+        }
+    }
+    const features = specs.map((spec) => {
+        const own = [...criteria.values()]
+            .filter((c) => c.spec === spec.file)
+            .map(({ criterion }) => {
+            const entry = tally.get(criterion.id);
+            return {
+                id: criterion.id,
+                statement: criterion.statement,
+                claimed: claimedIds.has(criterion.id),
+                covered: entry?.covered ?? 0,
+                killed: entry?.killed ?? 0,
+                strength: ratio(entry?.killed ?? 0, entry?.covered ?? 0),
+                survivors: (entry?.survivors ?? []).sort(bySourcePosition),
+            };
+        })
+            .sort(byCriterionId);
+        const totals = featureTally.get(spec.file) ?? { covered: 0, killed: 0 };
+        const lines = coverage && coverageUnder(coverage, dirname(spec.file));
+        return {
+            key: spec.key?.raw,
+            spec: spec.file,
+            covered: totals.covered,
+            killed: totals.killed,
+            strength: ratio(totals.killed, totals.covered),
+            lineCoverage: lines ? ratio(lines.covered, lines.total) : null,
+            criteria: own,
+        };
+    });
+    const unknownClaims = [...claimedIds].filter((id) => !criteria.has(id)).sort();
+    const unclaimed = [...criteria.keys()].filter((id) => !claimedIds.has(id)).sort();
+    return {
+        root,
+        covered,
+        killed,
+        strength: ratio(killed, covered),
+        lineCoverage: coverage?.total ? ratio(coverage.total.covered, coverage.total.total) : null,
+        features,
+        unclaimed,
+        unknownClaims,
+        unclaimedMutants: unclaimedMutants.sort(bySourcePosition),
+        staticMutants: { killed: staticKilled, survivors: staticSurvivors.sort(bySourcePosition) },
+    };
+}
+function toSite(mutant) {
+    return {
+        file: mutant.file,
+        line: mutant.line,
+        column: mutant.column,
+        mutator: mutant.mutator,
+        replacement: mutant.replacement,
+    };
+}
+/** Stryker does not order mutants stably across runs; a Speccle tool's output must be. */
+function bySourcePosition(a, b) {
+    return a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column;
+}
+function byCriterionId(a, b) {
+    return compareCriterionIds(a.id, b.id);
+}
+function ratio(numerator, denominator) {
+    return denominator === 0 ? null : numerator / denominator;
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function readJson(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        throw new Error(`report not found: ${path}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON: ${err instanceof Error ? err.message : ""}`);
+    }
+}
+/** Coverage is the naïve baseline, not the measurement: its absence is not fatal. */
+async function readCoverage(path, root) {
+    try {
+        await stat(path);
+    }
+    catch {
+        return undefined;
+    }
+    return parseCoverageSummary(await readJson(path), root, rel(root, path));
+}
+function rel(root, path) {
+    return path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+}

package/dist/violation.js

@@ -0,0 +1,13 @@
+/** Order matches the table in docs/convention.md and drives violation sorting. */
+export const RULE_IDS = [
+    "missing-key",
+    "key-collision",
+    "key-mismatch",
+    "malformed-id",
+    "duplicate-id",
+    "empty-statement",
+    "weasel-wording",
+    "compound-criterion",
+    "unmeasurable",
+    "code-voice",
+];