@mark1russell7/ste-lint 0.0.0-bootstrap.0 → 0.1.1

package/src/source/inline.ts

@@ -0,0 +1,416 @@
+/**
+ * Inline normalization. This step changes the text of a block into "clean"
+ * text that the tokenizer can read:
+ *
+ * - Each code span, `{@link ...}` tag, URL, MDX expression and quoted text
+ *   becomes one placeholder character. STE Rule 8.6 counts quoted text and
+ *   text in a different font as one word. The word rules do not examine the
+ *   text in a placeholder.
+ * - Link text stays. Link destinations, images, footnote references, HTML
+ *   tags, JSX tags and emphasis markers go away.
+ * - HTML entities become the characters that they show.
+ *
+ * Each character of the clean text keeps the file offset of its source
+ * character, so findings point to the correct line and column.
+ */
+
+import { findBacktickRun } from "./blocks.js";
+import type { Line } from "./lines.js";
+
+/** The character that holds the place of a code span, link tag, URL or quoted text. */
+export const PLACEHOLDER = "";
+
+export type PlaceholderKind = "code" | "link" | "url" | "quote" | "expr";
+
+export type Placeholder = {
+    readonly kind : PlaceholderKind;
+    /** The text in the placeholder, without its delimiters. */
+    readonly text : string;
+    /** The file offset of the first character. */
+    readonly start : number;
+    /** The file offset after the last character. */
+    readonly end : number;
+};
+
+export type InlineText = {
+    readonly clean : string;
+    /** The file offset of each character of `clean`. */
+    readonly offsets : readonly number[];
+    /** The placeholders, by their index in `clean`. */
+    readonly placeholders : ReadonlyMap<number, Placeholder>;
+};
+
+export type InlineOptions = {
+    readonly mdx : boolean;
+    readonly tsdoc : boolean;
+};
+
+// A map, not an object literal, so that "&constructor;" does not find an Object property.
+const ENTITIES : ReadonlyMap<string, string> = new Map([
+    ["amp", "&"], ["lt", "<"], ["gt", ">"], ["quot", "\""], ["apos", "'"], ["nbsp", " "], ["mdash", "—"],
+    ["ndash", "–"], ["hellip", "…"], ["copy", "©"], ["reg", "®"], ["trade", "™"],
+    ["times", "×"], ["rarr", "→"], ["larr", "←"], ["harr", "↔"], ["rsquo", "’"],
+    ["lsquo", "‘"], ["rdquo", "”"], ["ldquo", "“"], ["middot", "·"], ["bull", "•"],
+    ["deg", "°"], ["micro", "µ"], ["plusmn", "±"], ["le", "≤"], ["ge", "≥"],
+]);
+
+/** HTML elements whose content is code, so the content becomes one placeholder. */
+const CODE_ELEMENTS = new Set(["code", "kbd", "samp", "var", "tt"]);
+
+const ASCII_PUNCTUATION = /[!-/:-@[-`{-~]/;
+const ALPHANUMERIC = /[\p{L}\p{N}]/u;
+
+class Builder {
+    clean = "";
+    readonly offsets : number[] = [];
+    readonly placeholders = new Map<number, Placeholder>();
+
+    constructor(private readonly raw : string, private readonly rawOffsets : readonly number[]) {}
+
+    char(rawIndex : number) : void {
+        this.emit(this.raw[rawIndex]!, rawIndex);
+    }
+
+    /** This method adds `text` to the clean text, with one offset for each UTF-16 unit, also for a character outside the BMP. */
+    emit(text : string, rawIndex : number) : void {
+        this.clean += text;
+        for (let k = 0; k < text.length; k++) this.offsets.push(this.rawOffsets[rawIndex]!);
+    }
+
+    placeholder(kind : PlaceholderKind, text : string, rawStart : number, rawEnd : number) : void {
+        this.placeholders.set(this.clean.length, {
+            kind,
+            text,
+            start : this.rawOffsets[rawStart]!,
+            end : this.rawOffsets[Math.max(rawStart, rawEnd - 1)]! + 1,
+        });
+        this.emit(PLACEHOLDER, rawStart);
+    }
+}
+
+/** This function normalizes the inline content of a block. Refer to the module comment. */
+export function normalizeInline(lines : readonly Line[], options : InlineOptions) : InlineText {
+    let raw = "";
+    const rawOffsets : number[] = [];
+    lines.forEach((line, n) => {
+        if (n > 0) {
+            const previous = lines[n - 1]!;
+            raw += "\n";
+            rawOffsets.push(previous.offset + previous.text.length);
+        }
+        raw += line.text;
+        for (let k = 0; k < line.text.length; k++) rawOffsets.push(line.offset + k);
+    });
+    const last = lines[lines.length - 1];
+    rawOffsets.push(last === undefined ? 0 : last.offset + last.text.length);
+
+    const builder = new Builder(raw, rawOffsets);
+    scan(raw, 0, raw.length, builder, options);
+    return { clean : builder.clean, offsets : builder.offsets, placeholders : builder.placeholders };
+}
+
+function isAlphanumeric(char : string | undefined) : boolean {
+    return char !== undefined && ALPHANUMERIC.test(char);
+}
+
+function scan(raw : string, from : number, to : number, out : Builder, options : InlineOptions) : void {
+    let i = from;
+    while (i < to) {
+        const char = raw[i]!;
+        const next = raw[i + 1];
+
+        if (char === "\\" && next !== undefined && i + 1 < to && ASCII_PUNCTUATION.test(next)) {
+            out.char(i + 1);
+            i += 2;
+            continue;
+        }
+
+        if (char === "`") {
+            let run = 1;
+            while (raw[i + run] === "`") run++;
+            const close = findBacktickRun(raw, i + run, run);
+            if (close !== -1 && close + run <= to) {
+                out.placeholder("code", raw.slice(i + run, close).trim(), i, close + run);
+                i = close + run;
+            } else {
+                for (let k = 0; k < run; k++) out.char(i + k);
+                i += run;
+            }
+            continue;
+        }
+
+        if (char === "<") {
+            const end = scanAngle(raw, i, to, out);
+            if (end !== -1) {
+                i = end;
+                continue;
+            }
+        }
+
+        if (char === "{") {
+            const end = scanBrace(raw, i, to, out, options);
+            if (end !== -1) {
+                i = end;
+                continue;
+            }
+        }
+
+        if (char === "!" && next === "[") {
+            const end = linkEnd(raw, i + 1, to);
+            if (end !== null) {
+                i = end.end;
+                continue;
+            }
+        }
+
+        if (char === "[") {
+            if (/^\[\^[^\]\s]+\]/.test(raw.slice(i, to))) {
+                i = raw.indexOf("]", i) + 1;
+                continue;
+            }
+            const end = linkEnd(raw, i, to);
+            if (end !== null) {
+                scan(raw, i + 1, end.textEnd, out, options);
+                i = end.end;
+                continue;
+            }
+        }
+
+        if ((char === "h" || char === "w") && !isAlphanumeric(raw[i - 1])) {
+            const url = /^(?:https?:\/\/|www\.)[^\s<>"`]*[^\s<>"`.,;:!?')\]]/.exec(raw.slice(i, to));
+            if (url) {
+                let text = url[0];
+                // A ")" after the URL is part of it only when the URL has a "(" without a partner.
+                const count = (pattern : RegExp) : number => (text.match(pattern) ?? []).length;
+                while (raw[i + text.length] === ")" && i + text.length < to && count(/\(/g) > count(/\)/g)) text += ")";
+                out.placeholder("url", text, i, i + text.length);
+                i += text.length;
+                continue;
+            }
+        }
+
+        if (char === "*") {
+            const before = raw[i - 1];
+            const after = raw[i + 1];
+            const spaced = (before === undefined || /\s/.test(before)) && (after === undefined || /\s/.test(after));
+            if (spaced) out.char(i);
+            i++;
+            continue;
+        }
+
+        if (char === "_") {
+            if (isAlphanumeric(raw[i - 1]) && isAlphanumeric(raw[i + 1])) out.char(i);
+            i++;
+            continue;
+        }
+
+        if (char === "~" && next === "~") {
+            i += 2;
+            continue;
+        }
+
+        if (char === "&") {
+            const entity = /^&(#\d{1,7}|#[xX][0-9a-fA-F]{1,6}|[A-Za-z][A-Za-z0-9]{1,31});/.exec(raw.slice(i, to));
+            const decoded = entity ? decodeEntity(entity[1]!) : null;
+            if (entity && decoded !== null) {
+                out.emit(decoded, i);
+                i += entity[0].length;
+                continue;
+            }
+        }
+
+        if (char === "\"" || char === "“" || char === "'" || char === "‘") {
+            const end = scanQuote(raw, i, to, out);
+            if (end !== -1) {
+                i = end;
+                continue;
+            }
+        }
+
+        out.char(i);
+        i++;
+    }
+}
+
+function decodeEntity(name : string) : string | null {
+    if (name.startsWith("#x") || name.startsWith("#X")) return safeCodePoint(Number.parseInt(name.slice(2), 16));
+    if (name.startsWith("#")) return safeCodePoint(Number.parseInt(name.slice(1), 10));
+    return ENTITIES.get(name.toLowerCase()) ?? null;
+}
+
+function safeCodePoint(value : number) : string | null {
+    return Number.isInteger(value) && value > 0 && value <= 0x10FFFF ? String.fromCodePoint(value) : null;
+}
+
+/** This function handles `<...>`: autolinks, comments, HTML tags and JSX tags. The result is the index after it, or -1. */
+function scanAngle(raw : string, i : number, to : number, out : Builder) : number {
+    const rest = raw.slice(i, to);
+    const autolink = /^<((?:https?|mailto|ftp):[^\s<>]*|[^\s<>@]+@[^\s<>]+\.[^\s<>]+)>/.exec(rest);
+    if (autolink) {
+        out.placeholder("url", autolink[1]!, i, i + autolink[0].length);
+        return i + autolink[0].length;
+    }
+    if (rest.startsWith("<!--")) {
+        const close = raw.indexOf("-->", i + 4);
+        return close === -1 || close + 3 > to ? to : close + 3;
+    }
+    const tag = /^<(\/?)([A-Za-z][A-Za-z0-9.:_-]*)?/.exec(rest);
+    if (!tag || (tag[2] === undefined && !/^<\/?>/.test(rest))) return -1;
+    const tagEnd = findAngleClose(raw, i + 1, to);
+    if (tagEnd === -1) return -1;
+    const name = (tag[2] ?? "").toLowerCase();
+    if (tag[1] === "" && CODE_ELEMENTS.has(name)) {
+        const closeTag = raw.toLowerCase().indexOf(`</${name}>`, tagEnd);
+        if (closeTag !== -1 && closeTag + name.length + 3 <= to) {
+            out.placeholder("code", raw.slice(tagEnd, closeTag).trim(), i, closeTag + name.length + 3);
+            return closeTag + name.length + 3;
+        }
+    }
+    if (name === "br") out.emit(" ", i);
+    return tagEnd;
+}
+
+/** The index after the `>` that closes a tag. Quotes and `{...}` can contain `>`. */
+function findAngleClose(raw : string, from : number, to : number) : number {
+    let quote : string | null = null;
+    let depth = 0;
+    for (let i = from; i < to; i++) {
+        const char = raw[i]!;
+        if (quote !== null) {
+            if (char === quote) quote = null;
+        } else if (char === "\"" || char === "'") {
+            quote = char;
+        } else if (char === "{") {
+            depth++;
+        } else if (char === "}") {
+            depth = Math.max(0, depth - 1);
+        } else if (char === "<" && depth === 0) {
+            return -1;
+        } else if (char === ">" && depth === 0) {
+            return i + 1;
+        }
+    }
+    return -1;
+}
+
+/** This function handles `{@link ...}` in TSDoc and `{...}` in MDX. The result is the index after it, or -1. */
+function scanBrace(raw : string, i : number, to : number, out : Builder, options : InlineOptions) : number {
+    const isTag = options.tsdoc && raw[i + 1] === "@";
+    if (!isTag && !options.mdx) return -1;
+    let depth = 0;
+    let quote : string | null = null;
+    for (let k = i; k < to; k++) {
+        const char = raw[k]!;
+        if (quote !== null) {
+            if (char === quote) quote = null;
+            continue;
+        }
+        if (!isTag && (char === "\"" || char === "'" || char === "`")) {
+            quote = char;
+        } else if (char === "{") {
+            depth++;
+        } else if (char === "}") {
+            depth--;
+            if (depth === 0) {
+                const inner = raw.slice(i + 1, k).trim();
+                if (!isTag && inner.startsWith("/*") && inner.endsWith("*/")) return k + 1;
+                out.placeholder(isTag ? "link" : "expr", inner, i, k + 1);
+                return k + 1;
+            }
+        }
+    }
+    return -1;
+}
+
+type LinkEnd = {
+    /** The index of the `]` after the link text. */
+    readonly textEnd : number;
+    /** The index after the link destination or reference. */
+    readonly end : number;
+};
+
+/** The end of an inline link `[text](url)` or a reference link `[text][ref]` that starts at `start`, or null. */
+function linkEnd(raw : string, start : number, to : number) : LinkEnd | null {
+    let depth = 0;
+    let i = start;
+    let textEnd = -1;
+    while (i < to) {
+        const char = raw[i]!;
+        if (char === "\\") {
+            i += 2;
+            continue;
+        }
+        if (char === "`") {
+            let run = 1;
+            while (raw[i + run] === "`") run++;
+            const close = findBacktickRun(raw, i + run, run);
+            i = close === -1 ? i + run : close + run;
+            continue;
+        }
+        if (char === "[") depth++;
+        if (char === "]") {
+            depth--;
+            if (depth === 0) {
+                textEnd = i;
+                break;
+            }
+        }
+        i++;
+    }
+    if (textEnd === -1) return null;
+    const after = raw[textEnd + 1];
+    if (after === "(") {
+        let parens = 0;
+        let quote : string | null = null;
+        for (let k = textEnd + 1; k < to; k++) {
+            const char = raw[k]!;
+            if (quote !== null) {
+                if (char === quote) quote = null;
+            } else if (char === "\"" && parens > 0) {
+                quote = char;
+            } else if (char === "(") {
+                parens++;
+            } else if (char === ")") {
+                parens--;
+                if (parens === 0) return { textEnd, end : k + 1 };
+            }
+        }
+        return null;
+    }
+    if (after === "[") {
+        const close = raw.indexOf("]", textEnd + 2);
+        if (close !== -1 && close < to) return { textEnd, end : close + 1 };
+    }
+    return null;
+}
+
+/**
+ * This function handles quoted text. Double quotes always pair. A single
+ * quote pairs only when it cannot be an apostrophe. Then white space or an
+ * opening bracket comes before it, and white space or punctuation comes
+ * after its partner. The result is the index after the quote, or -1.
+ */
+function scanQuote(raw : string, i : number, to : number, out : Builder) : number {
+    const open = raw[i]!;
+    const close = open === "“" ? "”" : open === "‘" ? "’" : open;
+    const before = raw[i - 1];
+    if (isAlphanumeric(before)) return -1;
+    const single = open === "'" || open === "‘";
+    if (single && before !== undefined && !/[\s([{]/.test(before)) return -1;
+    if (raw[i + 1] === undefined || /\s/.test(raw[i + 1]!)) return -1;
+    const limit = Math.min(to, i + (single ? 60 : 300));
+    for (let k = i + 1; k < limit; k++) {
+        if (raw[k] !== close) continue;
+        const after = raw[k + 1];
+        if (single && after !== undefined && !/[\s.,;:!?)\]}]/.test(after)) continue;
+        if (!single && isAlphanumeric(after)) continue;
+        if (/\s/.test(raw[k - 1]!)) continue;
+        const text = raw.slice(i + 1, k);
+        out.placeholder("quote", text, i, k + 1);
+        const final = text[text.length - 1];
+        // A quoted sentence can end the sentence around it.
+        if (final === "." || final === "!" || final === "?") out.emit(final, k - 1);
+        return k + 1;
+    }
+    return -1;
+}

package/src/source/jsx.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { extractJsxText } from "./jsx.js";
+
+function blocksOf(source : string) {
+    return extractJsxText(source, "page.tsx").blocks.map(({ block }) => ({
+        kind : block.kind,
+        text : block.lines.map(line => line.text).join("|"),
+        offset : block.lines[0]!.offset,
+    }));
+}
+
+describe("extractJsxText", () => {
+    it("gives the text of an element as one block, with inline elements and expressions in it", () => {
+        const source = "const a = <p>There are no results. Use <code>pnpm results</code> for {count} runs.</p>;";
+        expect(blocksOf(source)).toEqual([{
+            kind : "paragraph",
+            text : "There are no results. Use |`x`| for |{x}| runs.",
+            offset : source.indexOf("There"),
+        }]);
+    });
+
+    it("gives headings and labels their own kinds", () => {
+        const source = "const a = <div><h2>The results</h2><button>Start the run</button></div>;";
+        expect(blocksOf(source).map(b => [b.kind, b.text])).toEqual([["heading", "The results"], ["table-cell", "Start the run"]]);
+    });
+
+    it("divides the text at block elements, and finds the JSX inside expressions", () => {
+        const source = "const a = <section>First text.<ul>{items.map(i => <li key={i}>Item text.</li>)}</ul>Last text.</section>;";
+        expect(blocksOf(source).map(b => b.text)).toEqual(["First text.", "Item text.", "Last text."]);
+    });
+
+    it("gives the text attributes, and ignores the other attributes", () => {
+        const source = 'const a = <PlotFigure title="The drift chart" className="wide" description={"x"} aria-label="Drift" />;';
+        expect(blocksOf(source).map(b => b.text)).toEqual(["The drift chart", "Drift"]);
+    });
+
+    it("ignores elements without words", () => {
+        expect(blocksOf("const a = <p>{value} {unit}</p>;")).toEqual([]);
+        expect(blocksOf("const a = <p>   </p>;")).toEqual([]);
+    });
+
+    it("keeps the text of inline elements in the paragraph", () => {
+        const source = "const a = <p>Read the <Link to=\"/docs\">documentation</Link> first.</p>;";
+        expect(blocksOf(source).map(b => b.text)).toEqual(["Read the |documentation| first."]);
+    });
+});

package/src/source/jsx.ts

@@ -0,0 +1,147 @@
+/**
+ * Prose extraction from the JSX of TSX and JSX files: the text that a user
+ * interface shows.
+ *
+ * An element with text children is one block. Inline elements (`strong`,
+ * `a`, `code` and the other elements in `INLINE_ELEMENTS`) and `{...}`
+ * expressions stay in the text of their parent. A code element and an
+ * expression become one placeholder, which counts as one word. An element
+ * with other children gives one block for each run of its text between
+ * those children. The JSX inside an expression gives its own blocks.
+ *
+ * The values of the attributes in `TEXT_ATTRIBUTES` (for example `title`
+ * and `aria-label`) are blocks too, when they are string literals.
+ */
+
+import ts from "typescript";
+import type { ExtractedBlock, BlockOrigin } from "../units.js";
+import type { ProseBlock } from "./blocks.js";
+import { splitLines, type Line } from "./lines.js";
+import type { Extraction } from "./markdown.js";
+
+/** Elements whose text stays in the text of the parent element. */
+const INLINE_ELEMENTS = new Set([
+    "a", "abbr", "b", "bdi", "bdo", "br", "cite", "code", "data", "dfn", "em", "i", "kbd", "mark", "q", "s",
+    "samp", "small", "span", "strong", "sub", "sup", "time", "u", "var", "wbr", "Link", "NavLink",
+]);
+
+/** Inline elements whose content is code: each one is one placeholder. */
+const CODE_ELEMENTS = new Set(["code", "kbd", "samp", "var"]);
+
+/** Elements whose text is a heading. */
+const HEADING_ELEMENTS = new Set(["h1", "h2", "h3", "h4", "h5", "h6"]);
+
+/** Elements whose text is a label or a short fragment, not a sentence. The word rules apply, the sentence rules do not. */
+const FRAGMENT_ELEMENTS = new Set(["button", "label", "legend", "option", "th", "td", "dt", "summary", "caption", "title"]);
+
+/** Attributes whose string value is text that a reader sees or hears. */
+const TEXT_ATTRIBUTES = new Set(["title", "aria-label", "aria-description", "alt", "placeholder", "label", "caption", "description", "summary"]);
+
+const ORIGIN : BlockOrigin = { source : "jsx", tsdocSection : null, tsdocTag : null };
+
+function tagName(node : ts.JsxElement | ts.JsxSelfClosingElement) : string {
+    const name = ts.isJsxElement(node) ? node.openingElement.tagName : node.tagName;
+    return name.getText();
+}
+
+function isInline(child : ts.JsxChild) : boolean {
+    if (ts.isJsxText(child) || ts.isJsxExpression(child)) return true;
+    if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) return INLINE_ELEMENTS.has(tagName(child));
+    return false;
+}
+
+function kindOf(name : string) : { kind : ProseBlock["kind"]; depth : number } {
+    if (HEADING_ELEMENTS.has(name)) return { kind : "heading", depth : Number(name.slice(1)) };
+    if (FRAGMENT_ELEMENTS.has(name)) return { kind : "table-cell", depth : 0 };
+    return { kind : "paragraph", depth : 0 };
+}
+
+/** This function extracts the text blocks of the JSX of a file. */
+export function extractJsxText(text : string, fileName : string) : Extraction {
+    const sourceFile = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const blocks : ExtractedBlock[] = [];
+
+    const push = (kind : ProseBlock["kind"], lines : readonly Line[], depth : number) : void => {
+        blocks.push({ block : { kind, lines, list : null, quote : false, headingDepth : depth, tableHeader : false }, origin : ORIGIN });
+    };
+
+    /** The lines of one inline child. The JSX inside an expression goes to `visit`. */
+    const linesOf = (child : ts.JsxChild) : { lines : Line[]; words : boolean } => {
+        if (ts.isJsxText(child)) {
+            const start = child.getFullStart();
+            const raw = text.slice(start, child.getEnd());
+            return { lines : splitLines(raw, start), words : /\p{L}/u.test(raw) };
+        }
+        if (ts.isJsxExpression(child)) {
+            if (!child.expression) return { lines : [], words : false };
+            ts.forEachChild(child.expression, visit);
+            return { lines : [{ text : "{x}", offset : child.getStart() }], words : false };
+        }
+        if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
+            const name = tagName(child);
+            if (ts.isJsxSelfClosingElement(child) || CODE_ELEMENTS.has(name)) {
+                if (ts.isJsxSelfClosingElement(child) || name === "br") return { lines : [], words : false };
+                return { lines : [{ text : "`x`", offset : child.getStart() }], words : false };
+            }
+            visitAttributes(child.openingElement.attributes);
+            const parts = child.children.map(linesOf);
+            return { lines : parts.flatMap(part => part.lines), words : parts.some(part => part.words) };
+        }
+        return { lines : [], words : false };
+    };
+
+    const addRun = (children : readonly ts.JsxChild[], kind : ProseBlock["kind"], depth : number) : void => {
+        const parts = children.map(linesOf);
+        if (parts.some(part => part.words)) push(kind, parts.flatMap(part => part.lines), depth);
+    };
+
+    const visitChildren = (children : ts.NodeArray<ts.JsxChild>, name : string) : void => {
+        const { kind, depth } = kindOf(name);
+        let run : ts.JsxChild[] = [];
+        for (const child of children) {
+            if (isInline(child)) {
+                run.push(child);
+                continue;
+            }
+            addRun(run, kind, depth);
+            run = [];
+            visit(child);
+        }
+        addRun(run, kind, depth);
+    };
+
+    function visitAttributes(attributes : ts.JsxAttributes) : void {
+        for (const property of attributes.properties) {
+            if (!ts.isJsxAttribute(property) || !property.initializer) continue;
+            const value = property.initializer;
+            if (ts.isJsxExpression(value)) {
+                if (value.expression) ts.forEachChild(value.expression, visit);
+                continue;
+            }
+            if (!TEXT_ATTRIBUTES.has(property.name.getText())) continue;
+            if (ts.isStringLiteral(value) && /\p{L}/u.test(value.text)) {
+                push("table-cell", [{ text : value.text, offset : value.getStart() + 1 }], 0);
+            }
+        }
+    }
+
+    function visit(node : ts.Node) : void {
+        if (ts.isJsxElement(node)) {
+            visitAttributes(node.openingElement.attributes);
+            visitChildren(node.children, tagName(node));
+            return;
+        }
+        if (ts.isJsxSelfClosingElement(node)) {
+            visitAttributes(node.attributes);
+            return;
+        }
+        if (ts.isJsxFragment(node)) {
+            visitChildren(node.children, "fragment");
+            return;
+        }
+        ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return { blocks, suppressions : [] };
+}

package/src/source/lines.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { indentWidth, isBlank, LineIndex, sliceLine, splitLines, stripIndent } from "./lines.js";
+
+describe("splitLines", () => {
+    it("gives each line with the offset of its first character", () => {
+        expect(splitLines("ab\ncd\n")).toEqual([
+            { text : "ab", offset : 0 },
+            { text : "cd", offset : 3 },
+            { text : "", offset : 6 },
+        ]);
+    });
+
+    it("removes the \\r of a CRLF line end and adds the base offset", () => {
+        expect(splitLines("a\r\nb", 10)).toEqual([
+            { text : "a", offset : 10 },
+            { text : "b", offset : 13 },
+        ]);
+    });
+});
+
+describe("LineIndex", () => {
+    it("changes offsets into 1-based lines and columns", () => {
+        const index = new LineIndex("ab\ncd\n\nx");
+        expect(index.position(0)).toEqual({ line : 1, column : 1 });
+        expect(index.position(1)).toEqual({ line : 1, column : 2 });
+        expect(index.position(3)).toEqual({ line : 2, column : 1 });
+        expect(index.position(6)).toEqual({ line : 3, column : 1 });
+        expect(index.position(7)).toEqual({ line : 4, column : 1 });
+    });
+});
+
+describe("indentation helpers", () => {
+    it("counts spaces and tabs as columns", () => {
+        expect(indentWidth("   x")).toBe(3);
+        expect(indentWidth("\tx")).toBe(4);
+        expect(indentWidth("  \tx")).toBe(4);
+        expect(indentWidth("x")).toBe(0);
+    });
+
+    it("removes indentation and moves the offset", () => {
+        expect(stripIndent({ text : "    code", offset : 5 }, 2)).toEqual({ text : "  code", offset : 7 });
+        expect(stripIndent({ text : " x", offset : 0 }, 4)).toEqual({ text : "x", offset : 1 });
+        expect(stripIndent({ text : "\tx", offset : 0 }, 4)).toEqual({ text : "x", offset : 1 });
+        expect(sliceLine({ text : "abc", offset : 1 }, 10)).toEqual({ text : "", offset : 4 });
+    });
+
+    it("finds blank lines", () => {
+        expect(isBlank(" \t ")).toBe(true);
+        expect(isBlank(" a ")).toBe(false);
+    });
+});