@mark1russell7/ste-lint 0.0.0-stage → 0.1.2

package/src/source/lines.ts

@@ -0,0 +1,91 @@
+/** A line of source text, and the file offset of its first character. */
+export type Line = {
+    readonly text : string;
+    readonly offset : number;
+};
+
+/**
+ * This function divides `text` into lines. The offset of each line starts at
+ * `base`. A `\r` before a `\n` is not part of the line text.
+ */
+export function splitLines(text : string, base : number = 0) : Line[] {
+    const lines : Line[] = [];
+    let start = 0;
+    for (let i = 0; i <= text.length; i++) {
+        if (i === text.length || text[i] === "\n") {
+            let end = i;
+            if (end > start && text[end - 1] === "\r") end--;
+            lines.push({ text : text.slice(start, end), offset : base + start });
+            start = i + 1;
+        }
+    }
+    return lines;
+}
+
+/** A 1-based line and column. */
+export type Position = {
+    readonly line : number;
+    readonly column : number;
+};
+
+/** This index changes file offsets into 1-based line and column numbers. */
+export class LineIndex {
+    private readonly starts : number[] = [0];
+
+    constructor(text : string) {
+        for (let i = 0; i < text.length; i++) {
+            if (text[i] === "\n") this.starts.push(i + 1);
+        }
+    }
+
+    /** The line and column of `offset`. */
+    position(offset : number) : Position {
+        let low = 0;
+        let high = this.starts.length - 1;
+        while (low < high) {
+            const middle = (low + high + 1) >> 1;
+            if (this.starts[middle]! <= offset) low = middle;
+            else high = middle - 1;
+        }
+        return { line : low + 1, column : offset - this.starts[low]! + 1 };
+    }
+}
+
+/** The number of columns of indentation at the start of `text`. A tab moves to the next multiple of 4. */
+export function indentWidth(text : string) : number {
+    let width = 0;
+    for (const char of text) {
+        if (char === " ") width++;
+        else if (char === "\t") width += 4 - (width % 4);
+        else break;
+    }
+    return width;
+}
+
+/** The part of `line` after the first `count` characters. The offset moves with the text. */
+export function sliceLine(line : Line, count : number) : Line {
+    const n = Math.min(Math.max(count, 0), line.text.length);
+    return { text : line.text.slice(n), offset : line.offset + n };
+}
+
+/**
+ * The part of `line` after `columns` columns of indentation. The function
+ * removes fewer characters when the line has less indentation.
+ */
+export function stripIndent(line : Line, columns : number) : Line {
+    let width = 0;
+    let i = 0;
+    while (i < line.text.length && width < columns) {
+        const char = line.text[i];
+        if (char === " ") width++;
+        else if (char === "\t") width += 4 - (width % 4);
+        else break;
+        i++;
+    }
+    return sliceLine(line, i);
+}
+
+/** True when the line has only white space. */
+export function isBlank(text : string) : boolean {
+    return text.trim().length === 0;
+}

package/src/source/markdown.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from "vitest";
+import { isDelimiterRow, parseBlocks, parseDirective, splitCells, type Block, type ProseBlock } from "./blocks.js";
+import { splitLines } from "./lines.js";
+import { extractMarkdown, stripFrontMatter } from "./markdown.js";
+
+const prose = (blocks : readonly Block[]) : ProseBlock[] => blocks.filter((block) : block is ProseBlock => block.kind !== "directive");
+
+/** The text of each prose block, with its kind. */
+function outline(markdown : string, mdx : boolean = false) : string[] {
+    return prose(extractMarkdown(markdown, { mdx }).blocks.map((entry) => entry.block)).map((block) => {
+        const text = block.lines.map((line) => line.text).join(" / ");
+        const list = block.list === null ? "" : block.list.ordered ? " (ol)" : " (ul)";
+        const extra = block.kind === "heading" ? ` h${block.headingDepth}` : block.tableHeader ? " th" : "";
+        return `${block.kind}${extra}${list}${block.quote ? " (quote)" : ""}: ${text}`;
+    });
+}
+
+describe("Markdown block extraction", () => {
+    it("keeps paragraphs and headings, and joins the lines of a paragraph", () => {
+        expect(outline("# Title\n\nFirst line\nsecond line.\n\n## Part ##\n\nText.")).toEqual([
+            "heading h1: Title",
+            "paragraph: First line / second line.",
+            "heading h2: Part",
+            "paragraph: Text.",
+        ]);
+    });
+
+    it("finds setext headings", () => {
+        expect(outline("Title\n=====\n\nSub\n---\n")).toEqual(["heading h1: Title", "heading h2: Sub"]);
+    });
+
+    it("removes fenced code, indented code and thematic breaks", () => {
+        const markdown = "Before.\n\n```ts\nconst a = 1; // should\n```\n\n~~~\nmay\n~~~\n\n    indented code;\n\n***\n\nAfter.";
+        expect(outline(markdown)).toEqual(["paragraph: Before.", "paragraph: After."]);
+    });
+
+    it("does not treat an indented line in a paragraph as code", () => {
+        expect(outline("A paragraph\n    that continues.")).toEqual(["paragraph: A paragraph / that continues."]);
+    });
+
+    it("does not treat a backtick run with a backtick in its info string as a fence", () => {
+        expect(outline("``` `x` ```\n\nNext.")).toEqual(["paragraph: ``` `x` ```", "paragraph: Next."]);
+    });
+
+    it("keeps an unclosed fence as code to the end of the file", () => {
+        expect(outline("Text.\n\n```\ncode\nmore")).toEqual(["paragraph: Text."]);
+    });
+
+    it("gives each list item as a block, with the list type", () => {
+        const markdown = "- one\n- two\n  continues\n\n1. step one\n2. step two\n   - nested\n";
+        expect(outline(markdown)).toEqual([
+            "paragraph (ul): one",
+            "paragraph (ul): two / continues",
+            "paragraph (ol): step one",
+            "paragraph (ol): step two",
+            "paragraph (ul): nested",
+        ]);
+    });
+
+    it("accepts lazy continuation lines in a list item", () => {
+        expect(outline("- item one\ncontinues here\n- item two")).toEqual([
+            "paragraph (ul): item one / continues here",
+            "paragraph (ul): item two",
+        ]);
+    });
+
+    it("keeps a paragraph after a list item that has a blank line before it", () => {
+        expect(outline("- item\n\n  second paragraph\n\nOutside.")).toEqual([
+            "paragraph (ul): item",
+            "paragraph (ul): second paragraph",
+            "paragraph: Outside.",
+        ]);
+    });
+
+    it("lets a bullet list interrupt a paragraph, but not an ordered list that starts after 1", () => {
+        expect(outline("Lead-in:\n- item")).toEqual(["paragraph: Lead-in:", "paragraph (ul): item"]);
+        expect(outline("The year\n2024. was good")).toEqual(["paragraph: The year / 2024. was good"]);
+    });
+
+    it("handles empty list items and wide markers", () => {
+        expect(outline("-\n  text\n\n-      code\n")).toEqual(["paragraph (ul): text"]);
+    });
+
+    it("parses block quotes and removes a GitHub alert marker", () => {
+        expect(outline("> [!NOTE]\n> The note text.\nlazy line.\n\n> # Quoted heading")).toEqual([
+            "paragraph (quote): The note text. / lazy line.",
+            "heading h1 (quote): Quoted heading",
+        ]);
+    });
+
+    it("gives table cells as separate blocks, and marks the header cells", () => {
+        const markdown = "| Name | Use |\n| --- | :-: |\n| `a\\|b` | Shows the value. |\n| x | |\n\nAfter.";
+        expect(outline(markdown)).toEqual([
+            "table-cell th: Name",
+            "table-cell th: Use",
+            "table-cell: `a\\|b`",
+            "table-cell: Shows the value.",
+            "table-cell: x",
+            "paragraph: After.",
+        ]);
+    });
+
+    it("finds a table directly after a paragraph", () => {
+        expect(outline("Intro\n| a | b |\n|---|---|\n| c | d |")).toEqual([
+            "paragraph: Intro",
+            "table-cell th: a",
+            "table-cell th: b",
+            "table-cell: c",
+            "table-cell: d",
+        ]);
+    });
+
+    it("removes HTML blocks, raw HTML elements and complete tag lines", () => {
+        const markdown = "<div align=\"center\">\nhidden text\n</div>\n\n<script>\nlet a;\n\nb();\n</script>\n\n<img src=\"x.png\">\n\nShown <b>bold</b> text.";
+        expect(outline(markdown)).toEqual(["paragraph: Shown <b>bold</b> text."]);
+    });
+
+    it("removes link reference definitions and Docusaurus admonition markers", () => {
+        expect(outline("[ref]: https://example.com\n\n:::note\nThe note.\n:::")).toEqual(["paragraph: The note."]);
+    });
+
+    it("removes YAML and TOML front matter", () => {
+        expect(outline("---\ntitle: Should not count\n---\nBody.")).toEqual(["paragraph: Body."]);
+        expect(outline("+++\ntitle = \"x\"\n+++\nBody.")).toEqual(["paragraph: Body."]);
+        const lines = splitLines("---\nno end");
+        expect(stripFrontMatter(lines)).toBe(lines);
+    });
+});
+
+describe("MDX", () => {
+    it("removes import and export lines, JSX tags and expressions, but keeps the prose in a component", () => {
+        const mdx = [
+            "import { Chart } from \"./chart\";",
+            "export const meta = { title : \"x\" };",
+            "",
+            "<Note>",
+            "The prose in the note.",
+            "</Note>",
+            "",
+            "<Chart",
+            "  data={[1, 2]}",
+            "  title=\"a > b\"",
+            "/>",
+            "",
+            "<Callout>Inline prose.</Callout>",
+            "",
+            "{props.value > 2 ? \"a\" : \"b\"}",
+            "",
+            "Text.",
+        ].join("\n");
+        expect(outline(mdx, true)).toEqual([
+            "paragraph: The prose in the note.",
+            "paragraph: Inline prose.</Callout>",
+            "paragraph: Text.",
+        ]);
+    });
+
+    it("keeps an expression block that does not close as code to the end", () => {
+        expect(outline("Text.\n\n{open(", true)).toEqual(["paragraph: Text."]);
+    });
+
+    it("finds a tag end at the end of the file when the tag does not close", () => {
+        expect(outline("<Open\n  attr", true)).toEqual([]);
+    });
+});
+
+describe("directives", () => {
+    it("reads the command, the rules and an optional reason", () => {
+        expect(parseDirective(" ste-disable-next modal-verb, semicolon -- quoted text ", 7)).toEqual({
+            kind : "directive",
+            command : "disable-next",
+            rules : ["modal-verb", "semicolon"],
+            offset : 7,
+        });
+        expect(parseDirective("ste-enable", 0)?.rules).toEqual([]);
+        expect(parseDirective("a normal comment", 0)).toBeNull();
+    });
+
+    it("comes from HTML comments and MDX comments", () => {
+        const blocks = parseBlocks(splitLines("<!-- ste-disable\nmodal-verb -->\n\n{/* ste-enable */}\n"), { mdx : true });
+        expect(blocks.map((block) => block.kind === "directive" ? block.command : block.kind)).toEqual(["disable", "enable"]);
+    });
+
+    it("makes suppressions for ranges and for the next block", () => {
+        const markdown = "<!-- ste-disable-next semicolon -->\nA; B.\n\nC; D.\n\n<!-- ste-disable -->\nE.\n<!-- ste-enable -->\nF.";
+        const extraction = extractMarkdown(markdown, { mdx : false });
+        expect(extraction.suppressions).toHaveLength(2);
+        const [next, range] = extraction.suppressions;
+        expect(markdown.slice(next!.start, next!.end)).toBe("A; B.");
+        expect([...next!.rules!]).toEqual(["semicolon"]);
+        expect(markdown.slice(range!.start, range!.end)).toContain("E.");
+        expect(range!.rules).toBeNull();
+    });
+});
+
+describe("table helpers", () => {
+    it("finds delimiter rows", () => {
+        expect(isDelimiterRow("| --- | :---: |")).toBe(true);
+        expect(isDelimiterRow("--- | ---")).toBe(true);
+        expect(isDelimiterRow("---")).toBe(false);
+        expect(isDelimiterRow("| a | b |")).toBe(false);
+    });
+
+    it("divides rows into cells, but not at an escaped pipe or a pipe in code", () => {
+        const cells = splitCells({ text : "| a | `x | y` | c \\| d |", offset : 0 });
+        expect(cells.map((cell) => cell.text)).toEqual(["a", "`x | y`", "c \\| d"]);
+        expect(cells[0]!.offset).toBe(2);
+        expect(splitCells({ text : "a | `open", offset : 0 }).map((cell) => cell.text)).toEqual(["a", "`open"]);
+    });
+});

package/src/source/markdown.ts

@@ -0,0 +1,49 @@
+/**
+ * Prose extraction from Markdown and MDX files.
+ */
+
+import type { ExtractedBlock } from "../units.js";
+import { parseBlocks, type ProseBlock } from "./blocks.js";
+import { splitLines, type Line } from "./lines.js";
+import { SuppressionCollector, type Suppression } from "./suppressions.js";
+
+export type Extraction = {
+    readonly blocks : readonly ExtractedBlock[];
+    readonly suppressions : readonly Suppression[];
+};
+
+/** This function removes YAML (`---`) or TOML (`+++`) front matter at the start of the file. */
+export function stripFrontMatter(lines : readonly Line[]) : readonly Line[] {
+    const first = lines[0]?.text.trimEnd();
+    if (first !== "---" && first !== "+++") return lines;
+    for (let i = 1; i < lines.length; i++) {
+        const text = lines[i]!.text.trimEnd();
+        if (text === first || (first === "---" && text === "...")) return lines.slice(i + 1);
+    }
+    return lines;
+}
+
+/** The file offsets of the first and the last character of a block. */
+export function blockRange(block : ProseBlock) : { start : number; end : number } {
+    const first = block.lines[0]!;
+    const last = block.lines[block.lines.length - 1]!;
+    return { start : first.offset, end : last.offset + last.text.length };
+}
+
+/** This function extracts the prose blocks and the suppressions of a Markdown or MDX file. */
+export function extractMarkdown(text : string, options : { readonly mdx : boolean }) : Extraction {
+    const lines = stripFrontMatter(splitLines(text));
+    const collector = new SuppressionCollector();
+    const blocks : ExtractedBlock[] = [];
+    const origin = { source : options.mdx ? "mdx" as const : "markdown" as const, tsdocSection : null, tsdocTag : null };
+    for (const block of parseBlocks(lines, options)) {
+        if (block.kind === "directive") {
+            collector.directive(block);
+            continue;
+        }
+        const range = blockRange(block);
+        collector.block(range.start, range.end);
+        blocks.push({ block, origin });
+    }
+    return { blocks, suppressions : collector.finish(text.length) };
+}

package/src/source/suppressions.ts

@@ -0,0 +1,79 @@
+import type { Directive } from "./blocks.js";
+
+/** A range of the file in which some rules (or all rules) do not report findings. */
+export type Suppression = {
+    readonly start : number;
+    readonly end : number;
+    /** The rule IDs, or null for all rules. */
+    readonly rules : ReadonlySet<string> | null;
+};
+
+type OpenRange = { start : number; rules : Set<string> | null };
+
+/**
+ * This class collects suppressions from directive comments:
+ *
+ * - `ste-disable [rules]` starts a range. `ste-enable [rules]` stops it.
+ *   Without an `ste-enable`, the range continues to the end of the file.
+ * - `ste-disable-next [rules]` applies to the next block only: the next
+ *   paragraph, heading, list item or table row in Markdown, or the next doc
+ *   comment in TypeScript.
+ *
+ * Without rule IDs, a directive applies to all rules.
+ */
+export class SuppressionCollector {
+    private readonly ranges : Suppression[] = [];
+    private readonly open : OpenRange[] = [];
+    private pending : Set<string> | null | undefined = undefined;
+
+    directive(directive : Directive) : void {
+        const rules = directive.rules.length === 0 ? null : new Set(directive.rules);
+        if (directive.command === "disable-next") {
+            this.pending = rules;
+        } else if (directive.command === "disable") {
+            this.open.push({ start : directive.offset, rules });
+        } else {
+            this.enable(directive.offset, rules);
+        }
+    }
+
+    /**
+     * A plain `ste-enable` stops all open ranges. An `ste-enable` with rule
+     * IDs stops those rules only. A range for all rules stops only at a
+     * plain `ste-enable`.
+     */
+    private enable(offset : number, rules : Set<string> | null) : void {
+        for (let i = this.open.length - 1; i >= 0; i--) {
+            const range = this.open[i]!;
+            if (rules === null) {
+                this.ranges.push({ start : range.start, end : offset, rules : range.rules });
+                this.open.splice(i, 1);
+                continue;
+            }
+            if (range.rules === null) continue;
+            const closing = [...range.rules].filter((rule) => rules.has(rule));
+            if (closing.length === 0) continue;
+            this.ranges.push({ start : range.start, end : offset, rules : new Set(closing) });
+            this.open.splice(i, 1);
+            const remaining = [...range.rules].filter((rule) => !rules.has(rule));
+            if (remaining.length > 0) this.open.push({ start : range.start, rules : new Set(remaining) });
+        }
+    }
+
+    /** This method tells the collector about the next block, so that a pending `ste-disable-next` applies to it. */
+    block(start : number, end : number) : void {
+        if (this.pending === undefined) return;
+        this.ranges.push({ start, end, rules : this.pending });
+        this.pending = undefined;
+    }
+
+    /** The suppressions. Open ranges stop at `fileEnd`. */
+    finish(fileEnd : number) : Suppression[] {
+        return [...this.ranges, ...this.open.map((range) => ({ start : range.start, end : fileEnd, rules : range.rules }))];
+    }
+}
+
+/** True when a suppression covers a finding of `rule` at `offset`. */
+export function isSuppressed(suppressions : readonly Suppression[], rule : string, offset : number) : boolean {
+    return suppressions.some((range) => offset >= range.start && offset <= range.end && (range.rules === null || range.rules.has(rule)));
+}

package/src/source/tsdoc.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest";
+import { collectComments, docCommentLines, extractTsdoc, splitSections } from "./tsdoc.js";
+
+describe("collectComments", () => {
+    it("finds line, block and doc comments, but not comment syntax in strings, templates or regular expressions", () => {
+        const source = [
+            "#!/usr/bin/env node",
+            "// line",
+            "/* block */",
+            "/** doc */",
+            "const a = \"/** not a comment */\";",
+            "const b = `/** ${a} */`;",
+            "const c = /\\/\\*\\* x \\*\\//;",
+            "/**/ const d = 1;",
+            "function f(/** inline doc */ x : number) { return x; }",
+            "/** at the end */",
+        ].join("\n");
+        const comments = collectComments(source, "a.ts").map((comment) => [comment.kind, source.slice(comment.pos, comment.end)]);
+        expect(comments).toEqual([
+            ["line", "// line"],
+            ["block", "/* block */"],
+            ["doc", "/** doc */"],
+            ["block", "/**/"],
+            ["doc", "/** inline doc */"],
+            ["doc", "/** at the end */"],
+        ]);
+    });
+
+    it("parses TSX, and does not read JSX text as a comment", () => {
+        const source = "/** Doc. */\nexport const A = () => <div>/** text */</div>;\n";
+        expect(collectComments(source, "a.tsx").map((comment) => source.slice(comment.pos, comment.end))).toEqual(["/** Doc. */"]);
+    });
+
+    it("parses JavaScript files", () => {
+        expect(collectComments("/** Doc. */\nexport const a = 1;", "a.mjs")).toHaveLength(1);
+        expect(collectComments("/** Doc. */\nconst A = <b/>;", "a.jsx")).toHaveLength(1);
+    });
+});
+
+describe("docCommentLines", () => {
+    it("removes the comment syntax and keeps the file offsets", () => {
+        const source = "/**\n * First line.\n *   indented\n no star\n */";
+        const comment = collectComments(source, "a.ts")[0]!;
+        const lines = docCommentLines(source, comment);
+        expect(lines.map((line) => line.text)).toEqual(["", "First line.", "  indented", "no star", ""]);
+        expect(source.slice(lines[1]!.offset, lines[1]!.offset + 5)).toBe("First");
+    });
+
+    it("handles a comment on one line", () => {
+        const source = "/** Short. */";
+        const lines = docCommentLines(source, collectComments(source, "a.ts")[0]!);
+        expect(lines.map((line) => line.text)).toEqual([" Short. "]);
+    });
+});
+
+describe("splitSections", () => {
+    const sections = (body : string) => splitSections(body.split("\n").map((text, index) => ({ text, offset : index * 100 })))
+        .map((section) => `${section.section}${section.tag === null ? "" : ` @${section.tag}`}: ${section.lines.map((line) => line.text).join(" / ")}`);
+
+    it("divides the summary and the block tags, and removes tag names, types and parameter names", () => {
+        expect(sections([
+            "Summary text.",
+            "@param name - The name.",
+            "@param {string} [other=1] Other value",
+            "  that continues.",
+            "@typeParam T - The type.",
+            "@returns {number} The count.",
+            "@throws {Error} - When it fails.",
+            "@remarks",
+            "More text.",
+            "@deprecated Use something else.",
+        ].join("\n"))).toEqual([
+            "summary: Summary text.",
+            "tag @param: The name.",
+            "tag @param: Other value /   that continues.",
+            "tag @typeParam: The type.",
+            "tag @returns: The count.",
+            "tag @throws: When it fails.",
+            "remarks @remarks:  / More text.",
+            "tag @deprecated: Use something else.",
+        ]);
+    });
+
+    it("skips @example and other sections that are not prose", () => {
+        expect(sections("Summary.\n@example\nconst x = f(); // should\n@since 1.0\n@param a - Text.")).toEqual([
+            "summary: Summary.",
+            "tag @param: Text.",
+        ]);
+    });
+
+    it("does not find tags in fenced code or in names such as @lag/core", () => {
+        expect(sections("Text.\n```\n@param not a tag\n```\n@lag/core is a package.")).toEqual([
+            "summary: Text. / ``` / @param not a tag / ``` / @lag/core is a package.",
+        ]);
+    });
+});
+
+describe("extractTsdoc", () => {
+    it("gives the prose blocks of each doc comment with their origin", () => {
+        const source = [
+            "/**",
+            " * Summary sentence.",
+            " *",
+            " * - item one;",
+            " * @param value - The value.",
+            " */",
+            "export function f(value : number) : number { return value; }",
+        ].join("\n");
+        const { blocks } = extractTsdoc(source, "f.ts");
+        expect(blocks.map((entry) => [entry.origin.tsdocSection, entry.origin.tsdocTag, entry.block.list !== null, entry.block.lines.map((line) => line.text).join(" ")])).toEqual([
+            ["summary", null, false, "Summary sentence."],
+            ["summary", null, true, "item one;"],
+            ["tag", "param", false, "The value."],
+        ]);
+    });
+
+    it("makes suppressions from line comments before a doc comment and from ranges", () => {
+        const source = [
+            "// ste-disable-next semicolon",
+            "/** A; b. */",
+            "/* ste-disable */",
+            "/** C; d. */",
+            "// ste-enable",
+            "/** E; f. */",
+        ].join("\n");
+        const { suppressions } = extractTsdoc(source, "a.ts");
+        expect(suppressions.map((range) => source.slice(range.start, range.end))).toEqual([
+            "/** A; b. */",
+            "/* ste-disable */\n/** C; d. */\n",
+        ]);
+    });
+
+    it("reads a directive inside a doc comment", () => {
+        const { suppressions } = extractTsdoc("/**\n * <!-- ste-disable -->\n * Text.\n */", "a.ts");
+        expect(suppressions).toHaveLength(1);
+    });
+});