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

package/dist/source/lines.js

@@ -0,0 +1,83 @@
+/**
+ * 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, base = 0) {
+    const lines = [];
+    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;
+}
+/** This index changes file offsets into 1-based line and column numbers. */
+export class LineIndex {
+    starts = [0];
+    constructor(text) {
+        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) {
+        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) {
+    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, count) {
+    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, columns) {
+    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) {
+    return text.trim().length === 0;
+}
+//# sourceMappingURL=lines.js.map

package/dist/source/lines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lines.js","sourceRoot":"","sources":["../../src/source/lines.ts"],"names":[],"mappings":"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"}

package/dist/source/markdown.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Prose extraction from Markdown and MDX files.
+ */
+import type { ExtractedBlock } from "../units.js";
+import { type ProseBlock } from "./blocks.js";
+import { type Line } from "./lines.js";
+import { 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 declare function stripFrontMatter(lines: readonly Line[]): readonly Line[];
+/** The file offsets of the first and the last character of a block. */
+export declare function blockRange(block: ProseBlock): {
+    start: number;
+    end: number;
+};
+/** This function extracts the prose blocks and the suppressions of a Markdown or MDX file. */
+export declare function extractMarkdown(text: string, options: {
+    readonly mdx: boolean;
+}): Extraction;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/source/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/source/markdown.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAwB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE3E,MAAM,MAAM,UAAU,GAAG;IACrB,QAAQ,CAAC,MAAM,EAAG,SAAS,cAAc,EAAE,CAAC;IAC5C,QAAQ,CAAC,YAAY,EAAG,SAAS,WAAW,EAAE,CAAC;CAClD,CAAC;AAEF,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,KAAK,EAAG,SAAS,IAAI,EAAE,GAAI,SAAS,IAAI,EAAE,CAQ1E;AAED,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,KAAK,EAAG,UAAU,GAAI;IAAE,KAAK,EAAG,MAAM,CAAC;IAAC,GAAG,EAAG,MAAM,CAAA;CAAE,CAIhF;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,IAAI,EAAG,MAAM,EAAE,OAAO,EAAG;IAAE,QAAQ,CAAC,GAAG,EAAG,OAAO,CAAA;CAAE,GAAI,UAAU,CAehG"}

package/dist/source/markdown.js

@@ -0,0 +1,42 @@
+/**
+ * Prose extraction from Markdown and MDX files.
+ */
+import { parseBlocks } from "./blocks.js";
+import { splitLines } from "./lines.js";
+import { SuppressionCollector } from "./suppressions.js";
+/** This function removes YAML (`---`) or TOML (`+++`) front matter at the start of the file. */
+export function stripFrontMatter(lines) {
+    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) {
+    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, options) {
+    const lines = stripFrontMatter(splitLines(text));
+    const collector = new SuppressionCollector();
+    const blocks = [];
+    const origin = { source: options.mdx ? "mdx" : "markdown", 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) };
+}
+//# sourceMappingURL=markdown.js.map

package/dist/source/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../../src/source/markdown.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,WAAW,EAAmB,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAa,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAoB,MAAM,mBAAmB,CAAC;AAO3E,gGAAgG;AAChG,MAAM,UAAU,gBAAgB,CAAC,KAAuB;IACpD,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IACvC,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACrD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACtC,IAAI,IAAI,KAAK,KAAK,IAAI,CAAC,KAAK,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,UAAU,CAAC,KAAkB;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;IAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;IAClD,OAAO,EAAE,KAAK,EAAG,KAAK,CAAC,MAAM,EAAE,GAAG,EAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;AAC1E,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,eAAe,CAAC,IAAa,EAAE,OAAoC;IAC/E,MAAM,KAAK,GAAG,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,GAAsB,EAAE,CAAC;IACrC,MAAM,MAAM,GAAG,EAAE,MAAM,EAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,KAAc,CAAC,CAAC,CAAC,UAAmB,EAAE,YAAY,EAAG,IAAI,EAAE,QAAQ,EAAG,IAAI,EAAE,CAAC;IACrH,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;QAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC7B,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YAC3B,SAAS;QACb,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QAChC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;AACpE,CAAC"}

package/dist/source/suppressions.d.ts

@@ -0,0 +1,38 @@
+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;
+};
+/**
+ * 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 declare class SuppressionCollector {
+    private readonly ranges;
+    private readonly open;
+    private pending;
+    directive(directive: Directive): void;
+    /**
+     * 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;
+    /** 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;
+    /** The suppressions. Open ranges stop at `fileEnd`. */
+    finish(fileEnd: number): Suppression[];
+}
+/** True when a suppression covers a finding of `rule` at `offset`. */
+export declare function isSuppressed(suppressions: readonly Suppression[], rule: string, offset: number): boolean;
+//# sourceMappingURL=suppressions.d.ts.map

package/dist/source/suppressions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suppressions.d.ts","sourceRoot":"","sources":["../../src/source/suppressions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,qFAAqF;AACrF,MAAM,MAAM,WAAW,GAAG;IACtB,QAAQ,CAAC,KAAK,EAAG,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAG,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAG,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CAC/C,CAAC;AAIF;;;;;;;;;;GAUG;AACH,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC,OAAO,CAAC,OAAO,CAA8C;IAE7D,SAAS,CAAC,SAAS,EAAG,SAAS,GAAI,IAAI;IAWvC;;;;OAIG;IACH,OAAO,CAAC,MAAM;IAkBd,gHAAgH;IAChH,KAAK,CAAC,KAAK,EAAG,MAAM,EAAE,GAAG,EAAG,MAAM,GAAI,IAAI;IAM1C,uDAAuD;IACvD,MAAM,CAAC,OAAO,EAAG,MAAM,GAAI,WAAW,EAAE;CAG3C;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,YAAY,EAAG,SAAS,WAAW,EAAE,EAAE,IAAI,EAAG,MAAM,EAAE,MAAM,EAAG,MAAM,GAAI,OAAO,CAE5G"}

package/dist/source/suppressions.js

@@ -0,0 +1,69 @@
+/**
+ * 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 {
+    ranges = [];
+    open = [];
+    pending = undefined;
+    directive(directive) {
+        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`.
+     */
+    enable(offset, rules) {
+        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, end) {
+        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) {
+        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, rule, offset) {
+    return suppressions.some((range) => offset >= range.start && offset <= range.end && (range.rules === null || range.rules.has(rule)));
+}
+//# sourceMappingURL=suppressions.js.map

package/dist/source/suppressions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suppressions.js","sourceRoot":"","sources":["../../src/source/suppressions.ts"],"names":[],"mappings":"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"}

package/dist/source/tsdoc.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Prose extraction from the doc comments (`/** ... *\/`) of TypeScript and
+ * JavaScript files.
+ *
+ * The TypeScript compiler parses the file. The extractor then examines only
+ * the trivia between tokens. Thus, text in strings, template literals,
+ * regular expressions and JSX does not become a comment.
+ */
+import type { TsdocSection } from "../units.js";
+import { type Line } from "./lines.js";
+import type { Extraction } from "./markdown.js";
+export type CommentKind = "line" | "block" | "doc";
+export type CommentRange = {
+    readonly kind: CommentKind;
+    /** The file offset of the first `/`. */
+    readonly pos: number;
+    /** The file offset after the comment. */
+    readonly end: number;
+};
+/** This function finds all comments in a file. The comments come in file order. */
+export declare function collectComments(text: string, fileName: string): CommentRange[];
+/**
+ * This function removes the comment syntax from the lines of a doc comment:
+ *
+ * - `/**` on the first line
+ * - `*\/` on the last line
+ * - The `*` and one space at the start of the other lines.
+ */
+export declare function docCommentLines(text: string, comment: CommentRange): Line[];
+type Section = {
+    readonly section: TsdocSection;
+    readonly tag: string | null;
+    readonly lines: Line[];
+};
+/** This function divides the lines of a doc comment into the summary and the block tag sections. */
+export declare function splitSections(lines: readonly Line[]): Section[];
+/** This function extracts the prose blocks of the doc comments of a file, and the suppressions. */
+export declare function extractTsdoc(text: string, fileName: string): Extraction;
+export {};
+//# sourceMappingURL=tsdoc.d.ts.map

package/dist/source/tsdoc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsdoc.d.ts","sourceRoot":"","sources":["../../src/source/tsdoc.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAA+B,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAAyB,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AAEnD,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAC;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,GAAG,EAAG,MAAM,CAAC;IACtB,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAG,MAAM,CAAC;CACzB,CAAC;AA8BF,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,IAAI,EAAG,MAAM,EAAE,QAAQ,EAAG,MAAM,GAAI,YAAY,EAAE,CAsCjF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAG,MAAM,EAAE,OAAO,EAAG,YAAY,GAAI,IAAI,EAAE,CAQ9E;AAED,KAAK,OAAO,GAAG;IACX,QAAQ,CAAC,OAAO,EAAG,YAAY,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAG,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAG,IAAI,EAAE,CAAC;CAC3B,CAAC;AAaF,oGAAoG;AACpG,wBAAgB,aAAa,CAAC,KAAK,EAAG,SAAS,IAAI,EAAE,GAAI,OAAO,EAAE,CAgCjE;AAED,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,IAAI,EAAG,MAAM,EAAE,QAAQ,EAAG,MAAM,GAAI,UAAU,CAuB1E"}

package/dist/source/tsdoc.js

@@ -0,0 +1,176 @@
+/**
+ * Prose extraction from the doc comments (`/** ... *\/`) of TypeScript and
+ * JavaScript files.
+ *
+ * The TypeScript compiler parses the file. The extractor then examines only
+ * the trivia between tokens. Thus, text in strings, template literals,
+ * regular expressions and JSX does not become a comment.
+ */
+import ts from "typescript";
+import { parseBlocks, parseDirective } from "./blocks.js";
+import { sliceLine, splitLines } from "./lines.js";
+import { SuppressionCollector } from "./suppressions.js";
+/** Tags whose content is not prose: code, values, names and other data. */
+const SKIPPED_TAGS = new Set([
+    "example", "default", "defaultvalue", "since", "version", "author", "license", "module", "category",
+    "group", "file", "fileoverview", "overview", "typedef", "type", "callback", "enum", "class", "constructor",
+    "extends", "augments", "implements", "satisfies", "overload", "import", "link", "linkcode", "linkplain",
+    "jsx", "jsxfrag", "jsximportsource", "jsxruntime", "ts-check", "ts-nocheck", "ts-ignore", "ts-expect-error",
+    "vitest-environment", "jest-environment", "eslint-disable", "copyright", "summary-only",
+]);
+/** Tags whose content is the same type of text as the summary. */
+const REMARKS_TAGS = new Set(["remarks", "privateremarks", "description", "summary", "classdesc"]);
+/** Tags that have a name before their text: `@param name - text`. */
+const NAMED_TAGS = new Set(["param", "typeparam", "template", "property", "prop", "arg", "argument"]);
+/** Tags that can have a type before their text: `@throws {Error} text`. */
+const TYPED_TAGS = new Set(["returns", "return", "throws", "exception", "yields", "yield"]);
+const TAG_LINE = /^[ \t]*@([A-Za-z][\w-]*)(?=[\s{]|$)/;
+function scriptKind(fileName) {
+    const lower = fileName.toLowerCase();
+    if (lower.endsWith(".tsx"))
+        return ts.ScriptKind.TSX;
+    if (lower.endsWith(".jsx"))
+        return ts.ScriptKind.JSX;
+    if (/\.[mc]?js$/.test(lower))
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}
+/** This function finds all comments in a file. The comments come in file order. */
+export function collectComments(text, fileName) {
+    const sourceFile = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, scriptKind(fileName));
+    const comments = [];
+    const scanTrivia = (from, to) => {
+        let i = from;
+        if (i === 0 && text.startsWith("#!")) {
+            const lineEnd = text.indexOf("\n");
+            i = lineEnd === -1 ? to : lineEnd;
+        }
+        while (i < to) {
+            if (text[i] === "/" && text[i + 1] === "/") {
+                const lineEnd = text.indexOf("\n", i);
+                const end = lineEnd === -1 || lineEnd > to ? to : lineEnd;
+                comments.push({ kind: "line", pos: i, end });
+                i = end;
+            }
+            else if (text[i] === "/" && text[i + 1] === "*") {
+                const close = text.indexOf("*/", i + 2);
+                const end = close === -1 ? to : Math.min(close + 2, to);
+                const isDoc = text.startsWith("/**", i) && !text.startsWith("/**/", i);
+                comments.push({ kind: isDoc ? "doc" : "block", pos: i, end });
+                i = end;
+            }
+            else {
+                i++;
+            }
+        }
+    };
+    const isJsDoc = (node) => node.kind >= ts.SyntaxKind.FirstJSDocNode && node.kind <= ts.SyntaxKind.LastJSDocNode;
+    const visit = (node) => {
+        // A token can have a JSDoc child, for example the end-of-file token after a final doc comment. It is still a token.
+        const children = node.getChildren(sourceFile).filter((child) => !isJsDoc(child));
+        if (children.length === 0) {
+            scanTrivia(node.getFullStart(), node.getStart(sourceFile));
+            return;
+        }
+        for (const child of children)
+            visit(child);
+    };
+    visit(sourceFile);
+    return comments;
+}
+/**
+ * This function removes the comment syntax from the lines of a doc comment:
+ *
+ * - `/**` on the first line
+ * - `*\/` on the last line
+ * - The `*` and one space at the start of the other lines.
+ */
+export function docCommentLines(text, comment) {
+    const inner = text.slice(comment.pos + 3, Math.max(comment.pos + 3, comment.end - 2));
+    return splitLines(inner, comment.pos + 3).map((line, index) => {
+        if (index === 0)
+            return line;
+        const prefix = /^[ \t]*\*(?!\/)[ \t]?/.exec(line.text);
+        if (prefix)
+            return sliceLine(line, prefix[0].length);
+        return sliceLine(line, line.text.length - line.text.trimStart().length);
+    });
+}
+/** This function removes the tag, and the type and the name after the tag, from the first line of a block tag. */
+function tagContent(line, tag, tagEnd) {
+    const rest = sliceLine(line, tagEnd);
+    const lower = tag.toLowerCase();
+    let prefix;
+    if (NAMED_TAGS.has(lower))
+        prefix = /^\s*(?:\{[^}]*\}\s*)?(?:\[[^\]]*\]|[\w$.]+)?\s*(?:-\s+|-$)?/;
+    else if (TYPED_TAGS.has(lower))
+        prefix = /^\s*(?:\{[^}]*\}\s*)?(?:-\s+)?/;
+    else
+        prefix = /^\s*(?:-\s+)?/;
+    return sliceLine(rest, prefix.exec(rest.text)[0].length);
+}
+/** This function divides the lines of a doc comment into the summary and the block tag sections. */
+export function splitSections(lines) {
+    const sections = [];
+    let current = { section: "summary", tag: null, lines: [] };
+    let fence = null;
+    for (const line of lines) {
+        const fenceMatch = /^[ \t]*(`{3,}|~{3,})/.exec(line.text);
+        if (fence !== null) {
+            if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length)
+                fence = null;
+            current?.lines.push(line);
+            continue;
+        }
+        if (fenceMatch)
+            fence = fenceMatch[1];
+        const tag = fence === null ? TAG_LINE.exec(line.text) : null;
+        if (tag === null) {
+            current?.lines.push(line);
+            continue;
+        }
+        if (current !== null)
+            sections.push(current);
+        const name = tag[1];
+        const lower = name.toLowerCase();
+        if (SKIPPED_TAGS.has(lower)) {
+            current = null;
+            continue;
+        }
+        current = {
+            section: REMARKS_TAGS.has(lower) ? "remarks" : "tag",
+            tag: name,
+            lines: [tagContent(line, name, tag[0].length)],
+        };
+    }
+    if (current !== null)
+        sections.push(current);
+    return sections.filter((section) => section.lines.length > 0);
+}
+/** This function extracts the prose blocks of the doc comments of a file, and the suppressions. */
+export function extractTsdoc(text, fileName) {
+    const collector = new SuppressionCollector();
+    const blocks = [];
+    for (const comment of collectComments(text, fileName)) {
+        if (comment.kind !== "doc") {
+            const body = comment.kind === "line" ? text.slice(comment.pos + 2, comment.end) : text.slice(comment.pos + 2, comment.end - 2);
+            const directive = parseDirective(body, comment.pos);
+            if (directive !== null)
+                collector.directive(directive);
+            continue;
+        }
+        collector.block(comment.pos, comment.end);
+        for (const section of splitSections(docCommentLines(text, comment))) {
+            const origin = { source: "tsdoc", tsdocSection: section.section, tsdocTag: section.tag };
+            for (const block of parseBlocks(section.lines, { mdx: false })) {
+                if (block.kind === "directive") {
+                    collector.directive(block);
+                    continue;
+                }
+                blocks.push({ block, origin });
+            }
+        }
+    }
+    return { blocks, suppressions: collector.finish(text.length) };
+}
+//# sourceMappingURL=tsdoc.js.map

package/dist/source/tsdoc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsdoc.js","sourceRoot":"","sources":["../../src/source/tsdoc.ts"],"names":[],"mappings":"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"}

package/dist/text/grammar.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Grammar heuristics. The linter has no part-of-speech tagger. These
+ * functions look at the words near a word to guess its function. Each
+ * heuristic prefers to miss a problem than to report a false one.
+ */
+import { type Token } from "./tokens.js";
+/**
+ * The possible base forms of a word: the word itself, and the word without
+ * the endings -s, -es, -ies, -ed, -d, -ied and -ing. The list can contain
+ * forms that are not words. The callers look up each form in a word list.
+ */
+export declare function lemmas(word: string): string[];
+/** True when one of the base forms of `word` is in `words`. */
+export declare function hasLemmaIn(word: string, words: ReadonlySet<string>): boolean;
+/** True when `word` can be a past participle: an irregular participle, or a word that ends in -ed. */
+export declare function isParticiple(word: string): boolean;
+/** True for a word that is an auxiliary verb: a form of "be", "have" or "do", or a modal verb. */
+export declare function isAuxiliary(token: Token | undefined): boolean;
+/** The index of the next token that is a word or a placeholder, or -1. */
+export declare function nextCounted(tokens: readonly Token[], from: number): number;
+/** True when the token can start the object of a verb: a determiner, a pronoun, a number, a placeholder or an adverb. */
+export declare function startsObject(token: Token | undefined): boolean;
+export type ImperativeOptions = {
+    /** Base forms of verbs, for example the common verbs and the technical verbs of the glossary. */
+    readonly verbs: ReadonlySet<string>;
+};
+/**
+ * True when the sentence is an instruction (imperative). The heuristic:
+ *
+ * 1. Skip the adverbs at the start, for example "then", "first" and "please".
+ * 2. If the sentence starts with a condition or purpose clause ("If ...,",
+ *    "To ...,", "When ...,"), continue after the first comma.
+ * 3. "Do not", "Never", "Make sure" and "Be sure" start an instruction.
+ * 4. Otherwise, the first word must be the base form of a known verb. The
+ *    next words must not show that the first word is a noun subject. Thus,
+ *    the next word is not an auxiliary verb or "of". Also, the next two
+ *    words are not a plural noun and a verb ("Test runs take 5 s").
+ */
+export declare function isInstruction(tokens: readonly Token[], options: ImperativeOptions): boolean;
+export type VerbUseOptions = {
+    readonly verbs: ReadonlySet<string>;
+};
+/**
+ * True when the word at `index` is likely a verb, not a noun or an
+ * adjective. The heuristic is conservative. It is true only when the words
+ * near the word show a verb. It looks at these words:
+ *
+ * - The word before. These words show a verb: "to", a modal verb, a form
+ *   of "do", a subject pronoun, a form of "be" or "have" (for participles).
+ * - The start of the sentence, for an imperative
+ * - The word after, for an -s form: an object, for example "the", a
+ *   pronoun, code or a number
+ * - A determiner before the word, which shows a noun ("the call", "a run").
+ */
+export declare function isVerbUse(tokens: readonly Token[], index: number, options: VerbUseOptions): boolean;
+/**
+ * True when the -ing word at `index` is a verb. The heuristic finds four
+ * uses:
+ *
+ * - After a form of "be": "is running", "is still running"
+ * - After a preposition, with an object: "by calling `stop()`", "after
+ *   waiting for the worker"
+ * - At the start of a clause, with an object: "Using the worker, ..."
+ * - After a word that is not a determiner, with an object (a reduced
+ *   clause): "a timer firing every 5 ms".
+ *
+ * A noun ("the timing") or an adjective before a noun ("existing code")
+ * is not a verb use.
+ */
+export declare function isIngVerbUse(tokens: readonly Token[], index: number): boolean;
+/** True when the token is the first word of the sentence or the first word after a comma, colon or opening parenthesis. */
+export declare function isClauseStart(tokens: readonly Token[], index: number): boolean;
+export type Passive = {
+    /** The index of the first word of the construction: the modal verb, "has" in "has to be", or the form of "be". */
+    readonly start: number;
+    /** The index of the form of "be" or "get". */
+    readonly auxiliary: number;
+    /** The index of the past participle. */
+    readonly participle: number;
+    /** True when a modal verb or "has to", "needs to" or "is to" shows an obligation: "must be set". */
+    readonly obligation: boolean;
+    /** True when a modal verb or "to" comes before "be": "can be set", "to be set". */
+    readonly modal: boolean;
+    /** True when "by" comes after the participle. */
+    readonly agent: boolean;
+    /** True when a condition word ("if", "when", "make sure that") comes before, in the same clause. */
+    readonly inCondition: boolean;
+};
+/** This function finds the passive constructions in a sentence: a form of "be" or "get" and a past participle. */
+export declare function findPassives(tokens: readonly Token[]): Passive[];
+//# sourceMappingURL=grammar.d.ts.map

package/dist/text/grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/text/grammar.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAA+B,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAqBtE;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAG,MAAM,GAAI,MAAM,EAAE,CAwB/C;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,IAAI,EAAG,MAAM,EAAE,KAAK,EAAG,WAAW,CAAC,MAAM,CAAC,GAAI,OAAO,CAE/E;AAED,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,IAAI,EAAG,MAAM,GAAI,OAAO,CAGpD;AAED,kGAAkG;AAClG,wBAAgB,WAAW,CAAC,KAAK,EAAG,KAAK,GAAG,SAAS,GAAI,OAAO,CAE/D;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,MAAM,EAAG,SAAS,KAAK,EAAE,EAAE,IAAI,EAAG,MAAM,GAAI,MAAM,CAG7E;AAOD,yHAAyH;AACzH,wBAAgB,YAAY,CAAC,KAAK,EAAG,KAAK,GAAG,SAAS,GAAI,OAAO,CAShE;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC5B,iGAAiG;IACjG,QAAQ,CAAC,KAAK,EAAG,WAAW,CAAC,MAAM,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAG,SAAS,KAAK,EAAE,EAAE,OAAO,EAAG,iBAAiB,GAAI,OAAO,CA6B9F;AAED,MAAM,MAAM,cAAc,GAAG;IACzB,QAAQ,CAAC,KAAK,EAAG,WAAW,CAAC,MAAM,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAG,SAAS,KAAK,EAAE,EAAE,KAAK,EAAG,MAAM,EAAE,OAAO,EAAG,cAAc,GAAI,OAAO,CAyCvG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAG,SAAS,KAAK,EAAE,EAAE,KAAK,EAAG,MAAM,GAAI,OAAO,CAahF;AAED,2HAA2H;AAC3H,wBAAgB,aAAa,CAAC,MAAM,EAAG,SAAS,KAAK,EAAE,EAAE,KAAK,EAAG,MAAM,GAAI,OAAO,CAOjF;AAED,MAAM,MAAM,OAAO,GAAG;IAClB,kHAAkH;IAClH,QAAQ,CAAC,KAAK,EAAG,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAG,MAAM,CAAC;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAG,MAAM,CAAC;IAC7B,oGAAoG;IACpG,QAAQ,CAAC,UAAU,EAAG,OAAO,CAAC;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAG,OAAO,CAAC;IACzB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAG,OAAO,CAAC;IACzB,oGAAoG;IACpG,QAAQ,CAAC,WAAW,EAAG,OAAO,CAAC;CAClC,CAAC;AAIF,kHAAkH;AAClH,wBAAgB,YAAY,CAAC,MAAM,EAAG,SAAS,KAAK,EAAE,GAAI,OAAO,EAAE,CA+BlE"}