spec-ctx 0.0.0-stage → 0.1.0

package/dist/lint/cli.js

@@ -0,0 +1,253 @@
+// REQ-LINT-001 `specctx lint tells|ste`: the flags, output, and exit codes of scripts/tells-lint.py and scripts/ste-lint.py.
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { PyFloat, pyInt, pyJson, pyStrip, round1 } from "./py.js";
+import { lintSte, STE_IDS } from "./ste.js";
+import { lintTells, TELLS_IDS } from "./tells.js";
+export const LINTERS = ["tells", "ste"];
+export class LintUsage extends Error {
+}
+const OPTIONS = ["--json", "--baseline", "--disable", "--selftest", "--help"];
+const TAKES_VALUE = new Set(["--baseline", "--disable"]);
+const NEGATIVE_NUMBER = /^-\d+$|^-\d*\.\d+$/;
+/**
+ * The argparse rules of the two scripts. `tells` accepts option prefixes and one run of files.
+ * `ste` accepts no prefixes and files between options.
+ */
+export function parseLintArgs(linter, argv) {
+    const a = { files: [], json: false, baseline: 0, disable: null, selftest: false, help: false };
+    const extra = [];
+    let runs = 0;
+    let lastWasFile = false;
+    let onlyFiles = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const isOption = !onlyFiles && arg.startsWith("-") && arg !== "-" && !NEGATIVE_NUMBER.test(arg);
+        if (!isOption) {
+            if (!lastWasFile)
+                runs++;
+            lastWasFile = true;
+            if (linter === "ste" || runs === 1)
+                a.files.push(arg);
+            else
+                extra.push(arg);
+            continue;
+        }
+        if (arg === "--") {
+            onlyFiles = true;
+            lastWasFile = false;
+            continue;
+        }
+        lastWasFile = false;
+        let name = arg;
+        let value;
+        const eq = arg.indexOf("=");
+        if (arg.startsWith("--") && eq > 0) {
+            name = arg.slice(0, eq);
+            value = arg.slice(eq + 1);
+        }
+        if (name === "-h")
+            name = "--help";
+        if (!OPTIONS.includes(name)) {
+            const hits = linter === "tells" && name.startsWith("--") ? OPTIONS.filter((o) => o.startsWith(name)) : [];
+            if (hits.length === 1)
+                name = hits[0];
+            else if (hits.length > 1)
+                throw new LintUsage(`ambiguous option: ${name} could match ${hits.join(", ")}`);
+            else {
+                extra.push(arg);
+                continue;
+            }
+        }
+        if (TAKES_VALUE.has(name)) {
+            if (value === undefined) {
+                const next = argv[i + 1];
+                if (next === undefined || (next.startsWith("-") && !NEGATIVE_NUMBER.test(next)))
+                    throw new LintUsage(`argument ${name}: expected one argument`);
+                value = next;
+                i++;
+            }
+            if (name === "--baseline") {
+                const n = pyInt(value);
+                if (linter === "tells" && Number.isNaN(n))
+                    throw new LintUsage(`argument --baseline: invalid int value: '${value}'`);
+                if (linter === "ste" && !(n >= 0))
+                    throw new LintUsage(`argument --baseline: expected a non-negative integer, got '${value}'`);
+                a.baseline = n;
+            }
+            else {
+                if (linter === "ste")
+                    checkRules(linter, value, true);
+                a.disable = value;
+            }
+        }
+        else if (value !== undefined) {
+            throw new LintUsage(`argument ${name}: ignored explicit argument '${value}'`);
+        }
+        else if (name === "--json")
+            a.json = true;
+        else if (name === "--selftest")
+            a.selftest = true;
+        else
+            a.help = true;
+        if (a.help)
+            return a;
+    }
+    if (extra.length)
+        throw new LintUsage(`unrecognized arguments: ${extra.join(" ")}`);
+    return a;
+}
+/** The rule IDs in a --disable value. An unknown ID is a usage error. */
+export function checkRules(linter, value, argparse = false) {
+    const ids = linter === "tells" ? TELLS_IDS : STE_IDS;
+    const rules = new Set(linter === "tells" ? value.split(",").map(pyStrip).filter(Boolean) : value.split(",").filter(Boolean));
+    const unknown = [...rules].filter((r) => !ids.includes(r)).sort();
+    if (unknown.length) {
+        const msg = `unknown rule(s): ${unknown.join(", ")}`;
+        throw new LintUsage(argparse ? `argument --disable: ${msg}. Known rules: ${[...ids].sort().join(", ")}` : msg);
+    }
+    return rules;
+}
+/** The file text as Python reads it: UTF-8, universal newlines. */
+function readText(io, p) {
+    const abs = resolve(io.cwd, p);
+    let st;
+    try {
+        st = statSync(abs);
+    }
+    catch {
+        throw new LintUsage(`cannot read ${p}: No such file or directory`);
+    }
+    if (st.isDirectory())
+        throw new LintUsage(`cannot read ${p}: Is a directory`);
+    try {
+        return readFileSync(abs, "utf8").replace(/\r\n?/g, "\n");
+    }
+    catch {
+        throw new LintUsage(`cannot read ${p}: Permission denied`);
+    }
+}
+function readStdin() {
+    try {
+        return readFileSync(0, "utf8").replace(/\r\n?/g, "\n");
+    }
+    catch {
+        return "";
+    }
+}
+const USAGE = {
+    tells: "usage: specctx lint tells [-h] [--json] [--baseline BASELINE] [--disable DISABLE] [--selftest] [files ...]\n",
+    ste: "usage: specctx lint ste [-h] [--json] [--baseline N] [--disable RULES] [--selftest] [FILE ...]\n",
+};
+/** `specctx lint <linter> ...`. Exit 0, 1 when hard findings exceed the baseline, 2 on a usage error. */
+export async function runLint(argv, io) {
+    const linter = argv[0];
+    if ((linter === "--help" || linter === "-h") && argv.length === 1) {
+        const { helpFor } = await import("../cli/help.js");
+        io.out(helpFor("lint"));
+        return 0;
+    }
+    if (linter !== "tells" && linter !== "ste") {
+        io.err(`specctx: lint needs a subcommand: ${LINTERS.join(", ")}\n`);
+        return 2;
+    }
+    const usage = (msg) => {
+        io.err(`${USAGE[linter]}specctx lint ${linter}: error: ${msg}\n`);
+        return 2;
+    };
+    let a;
+    try {
+        a = parseLintArgs(linter, argv.slice(1));
+    }
+    catch (e) {
+        if (e instanceof LintUsage)
+            return usage(e.message);
+        throw e;
+    }
+    if (a.help) {
+        // REQ-CLI-006 the lint pages render from the help table in the same layout
+        const { helpFor } = await import("../cli/help.js");
+        io.out(helpFor(`lint ${linter}`));
+        return 0;
+    }
+    if (a.selftest) {
+        const { selftestTells, selftestSte } = await import("./selftest.js");
+        return linter === "tells" ? selftestTells(io) : selftestSte(io);
+    }
+    return linter === "tells" ? runTells(a, io) : runSte(a, io, usage);
+}
+function runTells(a, io) {
+    let disabled;
+    try {
+        disabled = checkRules("tells", a.disable ?? "");
+    }
+    catch (e) {
+        io.err(`${e.message}\n`);
+        return 2;
+    }
+    const sources = [];
+    if (a.files.length) {
+        for (const p of a.files) {
+            try {
+                sources.push([p, readText(io, p)]);
+            }
+            catch (e) {
+                io.err(`${e.message}\n`);
+                return 2;
+            }
+        }
+    }
+    else
+        sources.push(["<stdin>", readStdin()]);
+    let hard = 0;
+    const report = [];
+    let out = "";
+    for (const [name, text] of sources) {
+        const fs = lintTells(text, disabled);
+        hard += fs.filter((f) => f.level === "hard").length;
+        report.push({ file: name, findings: fs });
+        if (!a.json)
+            for (const f of fs)
+                out += `${name}:${f.line}: [${f.level}] ${f.rule}: ${f.match}\n`;
+    }
+    out += a.json ? pyJson(report, false) + "\n" : `${hard} hard finding(s), baseline ${a.baseline}\n`;
+    io.out(out);
+    return hard > a.baseline ? 1 : 0;
+}
+function runSte(a, io, usage) {
+    const disabled = new Set(a.disable === null ? [] : a.disable.split(",").filter(Boolean));
+    let findings = [];
+    let words = 0;
+    if (a.files.length) {
+        for (const p of a.files) {
+            let text;
+            try {
+                text = readText(io, p);
+            }
+            catch (e) {
+                return usage(e.message);
+            }
+            const r = lintSte(text, p);
+            findings.push(...r.findings);
+            words += r.words;
+        }
+    }
+    else
+        ({ findings, words } = lintSte(readStdin()));
+    findings = findings.filter((f) => !disabled.has(f.rule));
+    const hard = findings.filter((f) => f.level === "advisory-free").length;
+    io.out(steReport(findings, words, a.json, hard, a.baseline));
+    return hard > a.baseline ? 1 : 0;
+}
+export function steReport(findings, words, json, hard, baseline) {
+    const rate = words ? round1((findings.length * 100) / words) : "0.0";
+    if (json) {
+        return pyJson({ violations: findings, count: findings.length, hard_count: hard, baseline, words, per_100_words: new PyFloat(rate) }, true) + "\n";
+    }
+    let out = "";
+    for (const f of findings)
+        out += `${f.file}:${f.line}:${f.col} ${f.rule}: ${f.message} [${f.match}]\n`;
+    out += `\n${findings.length} violations (${hard} hard, baseline ${baseline}), ${words} words, ${rate} per 100 words\n`;
+    out += "Hedges/modality (may, might, could) are never flagged: confidence is content.\n";
+    return out;
+}

package/dist/lint/py.js

@@ -0,0 +1,152 @@
+// REQ-LINT-001 Python `re`, `str`, and `json` behavior that the two linters depend on.
+// Python patterns are Unicode aware. JavaScript `\w`, `\b`, `\s`, and `\d` are not, so the ports use these classes.
+import { cpLen, pyStrip } from "../util/pystr.js";
+export { cpLen, pyStrip };
+/** Python `\w`: a letter, a number, or the underscore. */
+export const W = "[\\p{L}\\p{N}_]";
+/** Python `[^\W_]`: a letter or a number. */
+export const WN = "[\\p{L}\\p{N}]";
+/** Python `\b`. */
+export const B = `(?:(?<=${W})(?!${W})|(?<!${W})(?=${W}))`;
+const SP = "\\t-\\r\\x1c-\\x20\\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000";
+/** Python `\s`, the set of `str.isspace()`. */
+export const S = `[${SP}]`;
+/** Python `\S`. */
+export const NS = `[^${SP}]`;
+/** Python `\d`. */
+export const D = "\\p{Nd}";
+/** A Unicode pattern. `flags` holds the Python flags as JavaScript letters: i, m, g. */
+export function re(src, flags = "") {
+    return new RegExp(src, "u" + flags);
+}
+/** Python `re.escape` for the word lists. Only the characters that JavaScript needs. */
+export function esc(s) {
+    return s.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+}
+/** Python `str.splitlines()`. */
+export function splitlines(s) {
+    const out = s.split(/\r\n|[\n\r\x0b\x0c\x1c\x1d\x1e\x85\u2028\u2029]/);
+    if (out.length && out[out.length - 1] === "")
+        out.pop();
+    return out;
+}
+const LEAD = new RegExp(`^${S}+`, "u");
+const TRAIL = new RegExp(`${S}+$`, "u");
+export const lstrip = (s) => s.replace(LEAD, "");
+export const rstrip = (s) => s.replace(TRAIL, "");
+/** Python `str.lstrip(chars)`. */
+export function lstripChars(s, chars) {
+    let i = 0;
+    while (i < s.length && chars.includes(s[i]))
+        i++;
+    return s.slice(i);
+}
+/** Python `str.split()` with no argument. */
+export function pySplit(s) {
+    const t = pyStrip(s);
+    return t === "" ? [] : t.split(new RegExp(`${S}+`, "u"));
+}
+/** Python `s[:n]` on code points. */
+export function cpSlice(s, n) {
+    return Array.from(s).slice(0, n).join("");
+}
+/** The code point index of a UTF-16 index in s. */
+export function cpAt(s, i) {
+    return cpLen(s.slice(0, i));
+}
+/** Python `str.isupper()` on one character. */
+export function isUpper(ch) {
+    return /^\p{Uppercase}$/u.test(ch);
+}
+/** Python `int(s)` for the flag values, ASCII digits only. NaN on a bad value. */
+export function pyInt(s) {
+    const t = pyStrip(s);
+    return /^[+-]?\d+(?:_\d+)*$/.test(t) ? Number(t.replace(/_/g, "")) : NaN;
+}
+/** Python `round(x, 1)`: half to even on the exact binary value. The result as Python prints it. */
+export function round1(x) {
+    const neg = x < 0;
+    const [int, frac = ""] = Math.abs(x).toFixed(100).split(".");
+    const d = Number(frac[0] ?? "0");
+    const rest = frac.slice(1).replace(/0+$/, "");
+    let tenths = BigInt(int) * 10n + BigInt(d);
+    if (rest > "5" || (rest === "5" && d % 2 === 1) || (rest.startsWith("5") && rest.length > 1))
+        tenths += 1n;
+    const s = `${tenths / 10n}.${tenths % 10n}`;
+    return neg && tenths !== 0n ? "-" + s : s;
+}
+/** A float for `pyJson`. Python prints it with a decimal point. */
+export class PyFloat {
+    text;
+    constructor(text) {
+        this.text = text;
+    }
+}
+function jsonStr(s, ascii) {
+    let out = '"';
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        const ch = s[i];
+        if (ch === '"')
+            out += '\\"';
+        else if (ch === "\\")
+            out += "\\\\";
+        else if (ch === "\n")
+            out += "\\n";
+        else if (ch === "\r")
+            out += "\\r";
+        else if (ch === "\t")
+            out += "\\t";
+        else if (ch === "\b")
+            out += "\\b";
+        else if (ch === "\f")
+            out += "\\f";
+        else if (c < 0x20 || (ascii && c > 0x7e))
+            out += "\\u" + c.toString(16).padStart(4, "0");
+        else
+            out += ch;
+    }
+    return out + '"';
+}
+/** Python `json.dumps(v, indent=2, ensure_ascii=ascii)`. */
+export function pyJson(v, ascii, level = 0) {
+    const pad = "  ".repeat(level + 1);
+    const end = "  ".repeat(level);
+    if (v instanceof PyFloat)
+        return v.text;
+    if (typeof v === "string")
+        return jsonStr(v, ascii);
+    if (typeof v === "number")
+        return String(v);
+    if (typeof v === "boolean")
+        return v ? "true" : "false";
+    if (v === null || v === undefined)
+        return "null";
+    if (Array.isArray(v)) {
+        if (!v.length)
+            return "[]";
+        return "[\n" + v.map((x) => pad + pyJson(x, ascii, level + 1)).join(",\n") + "\n" + end + "]";
+    }
+    const keys = Object.keys(v);
+    if (!keys.length)
+        return "{}";
+    return "{\n" + keys.map((k) => `${pad}${jsonStr(k, ascii)}: ${pyJson(v[k], ascii, level + 1)}`).join(",\n") + "\n" + end + "}";
+}
+/** The line number of a UTF-16 position: one more than the count of newlines before it. */
+export function lineIndex(text) {
+    const nl = [];
+    for (let i = text.indexOf("\n"); i !== -1; i = text.indexOf("\n", i + 1))
+        nl.push(i);
+    return (pos) => {
+        let lo = 0;
+        let hi = nl.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (nl[mid] < pos)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return lo + 1;
+    };
+}

package/dist/lint/selftest.js

@@ -0,0 +1,246 @@
+// REQ-LINT-001 the --selftest suites of scripts/tells-lint.py and scripts/ste-lint.py, case by case.
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { checkRules, runLint } from "./cli.js";
+import { lintSte } from "./ste.js";
+import { lintTells } from "./tells.js";
+class SelftestFail extends Error {
+}
+function ok(cond, what) {
+    if (!cond)
+        throw new SelftestFail(typeof what === "string" ? what : JSON.stringify(what));
+}
+function report(io, name, fn, pass) {
+    const done = (e) => {
+        if (e === undefined) {
+            io.out(pass + "\n");
+            return 0;
+        }
+        if (e instanceof SelftestFail) {
+            io.err(`${name}: selftest failed: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    };
+    try {
+        const r = fn();
+        return r instanceof Promise ? r.then(() => done(), done) : done();
+    }
+    catch (e) {
+        return done(e);
+    }
+}
+export function selftestTells(io) {
+    return report(io, "tells", () => {
+        const bad = "It's not just a tool, it's a mirror. The policy — announced today — applies. " +
+            "Great question! Let's dive in. At its core it is robust and seamless.\n" +
+            "- **Speed:** fast\n";
+        const good = "The request may have failed. Check the client version. The tool shows your habits.";
+        const fBad = new Set(lintTells(bad).map((f) => f.rule));
+        const fGood = lintTells(good);
+        const want = ["not-x-its-y", "dash", "chat-residue", "run-up", "deep-saying", "stock-word", "bold-label"];
+        const missing = want.filter((w) => !fBad.has(w));
+        ok(!missing.length, `selftest: missing ${missing.join(", ")}`);
+        ok(!fGood.length, fGood);
+        // REQ-LINT-001 the cases the oracle added for the dash contrast and the inflected stock words
+        const hits = [
+            ["It's not a tool: it's a mirror.", "not-x-its-y"],
+            ["It's not a tool; it is a mirror.", "not-x-its-y"],
+            ["It's not just a linter \u2014 it's a gate.", "not-x-its-y"],
+            ["It's not just a linter - it's a gate.", "not-x-its-y"],
+            ["The team leverages the cache and leveraged it, leveraging more.", "stock-word"],
+            ["Two deep dives and a tapestry of testaments.", "stock-word"],
+        ];
+        for (const [text, rule] of hits)
+            ok(lintTells(text).some((x) => x.rule === rule), `selftest: ${rule} missed ${JSON.stringify(text)}`);
+        const misses = [
+            ["It's not here. The tool works.", "not-x-its-y"],
+            ["It's not a well-known fact, so we check.", "not-x-its-y"],
+            ["Use a lever to lift the load.", "stock-word"],
+        ];
+        for (const [text, rule] of misses)
+            ok(!lintTells(text).some((x) => x.rule === rule), `selftest: ${rule} false positive on ${JSON.stringify(text)}`);
+    }, "selftest ok");
+}
+const rules = (fs, id) => fs.filter((f) => f.rule === id);
+const has = (fs, id) => fs.some((f) => f.rule === id);
+const L = (text, file) => lintSte(text, file).findings;
+const eq = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+export function selftestSte(io) {
+    return report(io, "ste", async () => {
+        let f = L("The panel is removed; spin up the job. Perform an analysis of the seamless log. We have received the report.");
+        for (const e of ["semicolon", "phrasal-verb", "nominalization", "marketing-adjective", "passive-voice", "present-perfect"])
+            ok(has(f, e), e);
+        // hedges must never be flagged, including modal + perfect infinitive
+        f = L("The request may have failed. It could be a timeout. The disk might have filled.");
+        ok(!f.length, f);
+        // irregular participles: "has run" is a compound tense as much as "has failed"
+        f = L("The task has run. The job has set the flag. We have begun.");
+        ok(rules(f, "present-perfect").length === 3, f);
+        ok(!has(L("The job may have run."), "present-perfect"), "may have run");
+        // modal perfects remain protected across negation and variable whitespace
+        for (const modal of ["may", "might", "could", "should", "would", "must"]) {
+            for (const gap of [" ", "  ", "\t", " not "])
+                ok(!has(L(`The task ${modal}${gap}have run.`), "present-perfect"), modal + gap);
+        }
+        ok(!has(L("The task couldn't have run. The task MAY NOT HAVE RUN."), "present-perfect"), "couldn't");
+        f = L("The task has run. We have begun. The flag is set.");
+        ok(rules(f, "present-perfect").length === 2, f);
+        ok(has(f, "passive-voice"), f);
+        ok(!has(L("The task is gone."), "passive-voice"), "is gone");
+        // code blocks skipped
+        ok(!L("```\nx = a; y = b\n```").length, "fence");
+        // all supported list markers, case variants, and trailing whitespace
+        f = rules(L("- Confirm the target and\n* Record the result OR  \n+ Close the panel\n1. Start the task and\n2) Stop the task OR"), "dangling-conjunction");
+        ok(f.length === 4, f);
+        ok(eq(f.map((x) => x.line), [1, 2, 4, 5]), f);
+        ok(eq(f.map((x) => x.col), [1, 1, 1, 1]), f);
+        ok(f.every((x) => x.level === "advisory-free"), f);
+        // valid continuation lines and standalone four-space code are ignored
+        ok(!has(L("  - Confirm the target and\n    record the result."), "dangling-conjunction"), "continuation");
+        f = rules(L("- Confirm the target\n  and"), "dangling-conjunction");
+        ok(f.length === 1 && f[0].line === 2, f);
+        ok(f[0].col === 3, f);
+        ok(!has(L("    - code and"), "dangling-conjunction"), "code");
+        ok(!has(L("> - Confirm the target and\n> - Record the result or"), "dangling-conjunction"), "quote");
+        f = rules(L("- Do this and\n~~~\ncode and\n~~~"), "dangling-conjunction");
+        ok(f.length === 1 && f[0].line === 1, f);
+        ok(!has(L("```text\n- code and\n```"), "dangling-conjunction"), "fenced");
+        // one- and three-space markers and ordered continuation width
+        ok(!has(L(" - Start the task and\n   record the result."), "dangling-conjunction"), "one space");
+        ok(!has(L("-  Start the task and\n   record the result."), "dangling-conjunction"), "two gap");
+        ok(!has(L("-\tStart the task and"), "dangling-conjunction"), "tab");
+        f = rules(L("   - Start the task and", "fixture.md"), "dangling-conjunction");
+        ok(f.length === 1 && f[0].col === 4, f);
+        ok(f[0].file === "fixture.md", f);
+        ok(f[0].match.endsWith("and"), f);
+        ok(f[0].message.includes("Complete the item"), f);
+        ok(rules(L("100. Start the task and\n  unrelated text"), "dangling-conjunction").length === 1, "100.");
+        ok(!has(L("- Start the task and.\n- Stop the task or,"), "dangling-conjunction"), "punctuated");
+        ok(!has(L("- Start the task and\n\n  record the result."), "dangling-conjunction"), "blank");
+        ok(eq(rules(L("- Parent item and\n  - Nested item or"), "dangling-conjunction").map((x) => x.line), [1, 2]), "nested");
+        // ordinary prose, inline code, and fenced code are ignored
+        ok(!has(L("The process may include steps and"), "dangling-conjunction"), "prose");
+        ok(!has(L("- Use `and` as a label"), "dangling-conjunction"), "code and");
+        ok(!has(L("- Combine `left` and `right`"), "dangling-conjunction"), "combine");
+        ok(!has(L("~~~\n- code and\n~~~"), "dangling-conjunction"), "tilde");
+        ok(has(L(Array(30).fill("word").join(" ") + "."), "long-sentence"), "30 words");
+        // Markdown table syntax is layout, not prose. Each cell stays lintable.
+        const range = (a, b) => Array.from({ length: b - a }, (_, i) => `term${a + i}`).join(" ");
+        const shortCell = range(1, 25) + ".";
+        for (const table of [`| Label | Detail |\n| --- | --- |\n| Clear | ${shortCell} |`, `Label | Detail\n--- | ---\nClear | ${shortCell}`]) {
+            const r = lintSte(table);
+            ok(!has(r.findings, "long-sentence"), r.findings);
+            ok(r.words === 27, r.words);
+        }
+        const longCell = range(1, 27) + ".";
+        f = rules(L(`| Label | Detail |\n| --- | --- |\n| Clear | ${longCell} |`), "long-sentence");
+        ok(f.length === 1, f);
+        ok(f[0].match === "26 words", f);
+        // synonym rotation: second member flagged, first named as the keeper
+        f = rules(L("Check the config file. Then verify the output. Verify twice."), "synonym-rotation");
+        ok(f.length === 1 && f[0].message.includes("'verify' and 'check'"), f);
+        ok(!has(L("Check the config. Check the output."), "synonym-rotation"), "one term");
+        // per-file labels
+        ok(L("a; b", "x.md")[0].file === "x.md", "file");
+        // inline code is masked, not deleted, so columns match the source
+        f = rules(L("Run `make all` then spin up the node."), "phrasal-verb");
+        ok(f.length === 1 && f[0].col === 21, f);
+        // a sentence ends after closing quotes and brackets
+        const twenty = Array(20).fill("word").join(" ");
+        ok(!has(L(`He asked "${twenty}?" Then ${twenty} ended. (It ${twenty}.) Next.`), "long-sentence"), "quotes");
+        // abbreviations do not end a sentence
+        ok(has(L(`Use a tool, e.g. the ${twenty} linter here now.`), "long-sentence"), "e.g.");
+        ok(has(L(`Compare A vs. B in the ${twenty} test.`), "long-sentence"), "vs.");
+        // a sentence wrapped across lines is counted once, at its start
+        f = rules(L(`Intro text here.\nThe ${twenty}\nwrapped tail words go here.`), "long-sentence");
+        ok(f.length === 1, f);
+        ok(f[0].line === 2 && f[0].col === 1, f);
+        ok(has(L(`- Item ${twenty}\n  continued in the same item.`), "long-sentence"), "item");
+        // blank lines, headings, rules, list items, and quotes end a prose block
+        for (const sep of ["\n\n", "\n# Heading\n", "\n---\n", "\n- ", "\n> "])
+            ok(!has(L(`First ${twenty} line${sep}Second ${twenty} line.`), "long-sentence"), sep);
+        // a GitHub alert marker on the first line of a quote is not a word of the body
+        const body = Array(25).fill("word").join(" ") + ".";
+        for (const alert of ["> [!NOTE]", "> [!tip]", ">[!Warning]", ">  [!CAUTION]  "])
+            ok(!has(L(`${alert}\n> ${body}`), "long-sentence"), alert);
+        for (const text of [`Text.\n\n> [!NOTE]\n> ${body}`, `> Text.\n~~~\ncode\n~~~\n> [!NOTE]\n> ${body}`])
+            ok(!has(L(text), "long-sentence"), text);
+        const words26 = (fs) => eq(rules(fs, "long-sentence").map((x) => x.match), ["26 words"]);
+        // inside HTML containers the marker is text: marker plus body is 26 words
+        for (const [open, close] of [["<details>", "</details>"], ['<DIV class="note">', "</DIV>"], ["<section><details>", "</details></section>"]]) {
+            ok(words26(L(`${open}\n\n> [!NOTE]\n> ${body}\n\n${close}`)), open);
+            ok(!has(L(`${open}\n${close}\n\n> [!NOTE]\n> ${body}`), "long-sentence"), open);
+        }
+        ok(!has(L(`> [!NOTE]\n> ${body}`), "long-sentence"), "note");
+        // an inner close or a fenced closing tag must not close the outer container
+        for (const content of ["<details>\n<div>\n</div>", "<details>\n~~~\n</details>\n~~~"])
+            ok(words26(L(`${content}\n\n> [!NOTE]\n> ${body}\n\n</details>`)), content);
+        // fenced, commented, inline, void, and self-closing tags do not open containers
+        for (const content of ["```html\n<details>\n```", "<!-- <details> -->", "<span>Text.</span>", "<hr>", "<div />", "<details></details>", "</details>"]) {
+            ok(!has(L(`${content}\n\n> [!NOTE]\n> ${body}`), "long-sentence"), content);
+        }
+        // GitHub shows these markers as text, so they stay words
+        for (const text of [
+            `> [!FOO]\n> ${body}`, `> [!NOTE] ${body}`, `> Intro.\n> [!NOTE]\n> ${body}`,
+            `> > [!NOTE]\n> > ${body}`, `> Intro.\ncontinuation.\n> [!NOTE]\n> ${body}`,
+            `- Item.\n\n  > [!NOTE]\n  > ${body}`,
+            `Text.\n> [!NOTE]\n> ${body}`, `   > [!NOTE]\n   > ${body}`,
+        ])
+            ok(words26(L(text)), text);
+        // a bold or italic lead sentence ends at its closing emphasis marker
+        ok(!has(L(`**Lead.** The ${twenty} more words here now.`), "long-sentence"), "bold lead");
+        ok(!has(L(`_Note._ The ${twenty} more words here now.`), "long-sentence"), "italic lead");
+        ok(has(L(`See **e.g.** the ${twenty} linter here now.`), "long-sentence"), "bold e.g.");
+        // a dotted abbreviation ends a sentence before a capitalized word
+        ok(!has(L(`The team shipped it in the U.S. Then ${twenty} today.`), "long-sentence"), "U.S.");
+        // nested list items, quoted list items, and HTML lines end a prose block
+        for (const text of [
+            `- First item\n    - First ${twenty} line\n      - Second ${twenty} line`,
+            `> - First ${twenty} line\n> - Second ${twenty} line`,
+            `<!-- First ${twenty} line -->\nSecond ${twenty} line.`,
+            `> First ${twenty} line.\n>\n> Second ${twenty} line.`,
+        ])
+            ok(!has(L(text), "long-sentence"), text);
+        // a blockquote prefix is not a word in a wrapped quoted sentence
+        ok(!has(L("> " + Array(5).fill("word word word word word").join("\n> ") + "."), "long-sentence"), "quote prefix");
+        // a list marker is not a word either, in every marker style
+        const twentyFive = range(1, 26) + ".";
+        for (const marker of ["-", "*", "+", "1.", "1)", "  -", "> -"])
+            ok(!has(L(`${marker} ${twentyFive}`), "long-sentence"), marker);
+        f = rules(L(`- term0 ${twentyFive}`), "long-sentence");
+        ok(eq(f.map((x) => [x.match, x.col]), [["26 words", 3]]), f);
+        // a code span at the line start does not turn the next token into a list marker
+        ok(words26(L(`\`label\` 1) ${twentyFive}`)), "label");
+        // bare punctuation is not a word: code span separators and spaced dashes
+        for (const separator of [", ", " ", " / "]) {
+            const names = Array.from({ length: 30 }, (_, i) => `\`a${i}\``).join(separator);
+            ok(!has(L(`The adapters are ${names}.`), "long-sentence"), separator);
+        }
+        ok(!has(L(range(1, 25) + " — term25."), "long-sentence"), "dash");
+        ok(words26(L(`Use \`make\` — ${twentyFive}`)), "make");
+        // a long block stays linear: one short sentence per line, no blank lines
+        ok(!has(L("The agent read the log.\n".repeat(20000)), "long-sentence"), "linear");
+        // flags may appear between file paths
+        const tmp = mkdtempSync(join(tmpdir(), "specctx-ste-"));
+        try {
+            const paths = ["a.md", "b.md"].map((n) => join(tmp, n));
+            for (const p of paths)
+                writeFileSync(p, "Short line here.\n");
+            let out = "";
+            const sink = { cwd: tmp, out: (s) => (out += s), err: () => { } };
+            ok((await runLint(["ste", paths[0], "--json", paths[1]], sink)) === 0, "intermixed");
+            ok(JSON.parse(out).words === 6, out);
+        }
+        finally {
+            rmSync(tmp, { recursive: true, force: true });
+        }
+        // command line parsing rejects typos and bad values
+        for (const bad of [["--basline", "3"], ["--baseline"], ["--baseline", "x"], ["--baseline", "-1"], ["--disable", "passive"], ["--base", "3"]]) {
+            const sink = { cwd: tmpdir(), out: () => { }, err: () => { } };
+            ok((await runLint(["ste", ...bad], sink)) === 2, bad);
+        }
+        ok(eq([...checkRules("ste", "passive-voice,present-perfect")].sort(), ["passive-voice", "present-perfect"]), "rule list");
+    }, "selftest OK");
+}