asciidoclint 0.5.0

package/dist/rules/AD045.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "../types.js";
+export declare const AD045: Rule;

package/dist/rules/AD045.js

@@ -0,0 +1,66 @@
+import { isLineInProtectedBlock } from "./utils.js";
+const headingPattern = /^(=+|#+)\s+\S/;
+export const AD045 = {
+    id: "AD045",
+    alias: "markdown-heading-mix",
+    description: "Markdown-compatible headings should not be mixed with AsciiDoc headings",
+    tags: ["headings", "markdown-compatibility", "maintainability"],
+    parser: "document",
+    docs: {
+        summary: "Do not mix AsciiDoc = headings and Markdown-compatible # headings in one document graph.",
+        rationale: "Asciidoctor accepts Markdown-style headings as optional compatibility syntax, so using them is not invalid. Mixing both marker styles in one document tree makes hierarchy review and style maintenance harder.",
+        fixability: "unsafe",
+        fixHelper: "Convert the less common heading marker style to the dominant style in the document graph, preserving the marker length.",
+        badExamples: [{ code: "= Title\n\n== Overview\n\n## Markdown-style Section" }],
+        goodExamples: [
+            { code: "= Title\n\n== Overview\n\n== AsciiDoc-style Section" },
+            { code: "## Overview\n\n## Markdown-style Section" },
+        ],
+    },
+    function: ({ document }, onError) => {
+        const headings = [];
+        for (const file of document.files) {
+            for (const [index, line] of file.lines.entries()) {
+                if (isLineInProtectedBlock(document, file.file, index + 1)) {
+                    continue;
+                }
+                const match = line.match(headingPattern);
+                if (!match) {
+                    continue;
+                }
+                const marker = match[1] ?? "";
+                headings.push({
+                    style: marker.startsWith("#") ? "markdown" : "asciidoc",
+                    marker,
+                    range: {
+                        start: { file: file.file, line: index + 1, column: 1 },
+                        end: { file: file.file, line: index + 1, column: marker.length + 1 },
+                    },
+                });
+            }
+        }
+        const asciidocCount = headings.filter((heading) => heading.style === "asciidoc").length;
+        const markdownCount = headings.filter((heading) => heading.style === "markdown").length;
+        if (asciidocCount === 0 || markdownCount === 0) {
+            return;
+        }
+        const dominant = asciidocCount >= markdownCount ? "asciidoc" : "markdown";
+        for (const heading of headings.filter((candidate) => candidate.style !== dominant)) {
+            const replacementMarker = dominant === "asciidoc" ? "=".repeat(heading.marker.length) : "#".repeat(heading.marker.length);
+            onError({
+                severity: "info",
+                message: `Markdown-compatible heading style is mixed with AsciiDoc heading style: ${heading.marker}`,
+                range: heading.range,
+                fixHelper: `Use ${replacementMarker} to match the dominant ${dominant === "asciidoc" ? "AsciiDoc" : "Markdown-compatible"} heading style in this document graph.`,
+                fix: {
+                    applicability: "unsafe",
+                    edits: [{
+                            file: heading.range.start.file,
+                            range: heading.range,
+                            replacement: replacementMarker,
+                        }],
+                },
+            });
+        }
+    },
+};

package/dist/rules/builtin.d.ts

@@ -0,0 +1,3 @@
+import type { LintFinding, Rule } from "../types.js";
+export declare const builtInRules: Rule[];
+export declare function ruleLabel(finding: Pick<LintFinding, "ruleId" | "alias">): string;

package/dist/rules/builtin.js

@@ -0,0 +1,81 @@
+import { AD001 } from "./AD001.js";
+import { AD002 } from "./AD002.js";
+import { AD003 } from "./AD003.js";
+import { AD004 } from "./AD004.js";
+import { AD005 } from "./AD005.js";
+import { AD006 } from "./AD006.js";
+import { AD007 } from "./AD007.js";
+import { AD008 } from "./AD008.js";
+import { AD010 } from "./AD010.js";
+import { AD011 } from "./AD011.js";
+import { AD012 } from "./AD012.js";
+import { AD013 } from "./AD013.js";
+import { AD016 } from "./AD016.js";
+import { AD017 } from "./AD017.js";
+import { AD019 } from "./AD019.js";
+import { AD020 } from "./AD020.js";
+import { AD022 } from "./AD022.js";
+import { AD023 } from "./AD023.js";
+import { AD032 } from "./AD032.js";
+import { AD034 } from "./AD034.js";
+import { AD035 } from "./AD035.js";
+import { AD036 } from "./AD036.js";
+import { AD037 } from "./AD037.js";
+import { AD039 } from "./AD039.js";
+import { AD040 } from "./AD040.js";
+import { AD041 } from "./AD041.js";
+import { AD042 } from "./AD042.js";
+import { AD043 } from "./AD043.js";
+import { AD044 } from "./AD044.js";
+import { AD045 } from "./AD045.js";
+import { AD024 } from "./AD024.js";
+import { AD025 } from "./AD025.js";
+import { AD026 } from "./AD026.js";
+import { AD027 } from "./AD027.js";
+import { AD028 } from "./AD028.js";
+import { AD029 } from "./AD029.js";
+import { AD030 } from "./AD030.js";
+import { AD031 } from "./AD031.js";
+export const builtInRules = [
+    AD001,
+    AD002,
+    AD003,
+    AD004,
+    AD005,
+    AD006,
+    AD007,
+    AD008,
+    AD010,
+    AD011,
+    AD012,
+    AD013,
+    AD016,
+    AD017,
+    AD019,
+    AD020,
+    AD022,
+    AD023,
+    AD024,
+    AD025,
+    AD026,
+    AD027,
+    AD028,
+    AD029,
+    AD030,
+    AD031,
+    AD032,
+    AD034,
+    AD035,
+    AD036,
+    AD037,
+    AD039,
+    AD040,
+    AD041,
+    AD042,
+    AD043,
+    AD044,
+    AD045,
+];
+export function ruleLabel(finding) {
+    return finding.alias ? `${finding.ruleId}/${finding.alias}` : finding.ruleId;
+}

package/dist/rules/helpers.d.ts

@@ -0,0 +1,2 @@
+import type { RuleHelpers } from "../types.js";
+export declare const helpers: RuleHelpers;

package/dist/rules/helpers.js

@@ -0,0 +1,11 @@
+export const helpers = {
+    findSections(document) {
+        return document.sections;
+    },
+    findBlocks(document, type) {
+        return type ? document.blocks.filter((block) => block.type === type) : document.blocks;
+    },
+    isSourceLikeBlock(block) {
+        return ["source", "listing", "literal", "passthrough", "stem"].includes(block.type);
+    },
+};

package/dist/rules/registry.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from "../types.js";
+export declare function validateRules(rules: Rule[]): void;
+export declare function resolveRuleReference(rules: Rule[], reference: string): Rule | undefined;

package/dist/rules/registry.js

@@ -0,0 +1,34 @@
+export function validateRules(rules) {
+    const ids = new Set();
+    const aliases = new Set();
+    for (const rule of rules) {
+        if (!rule.id) {
+            throw new Error("Rule is missing required id");
+        }
+        if (ids.has(rule.id)) {
+            throw new Error(`Duplicate rule id: ${rule.id}`);
+        }
+        if (aliases.has(rule.id)) {
+            throw new Error(`Rule id collides with an alias: ${rule.id}`);
+        }
+        ids.add(rule.id);
+        if (rule.alias) {
+            if (aliases.has(rule.alias)) {
+                throw new Error(`Duplicate rule alias: ${rule.alias}`);
+            }
+            if (ids.has(rule.alias)) {
+                throw new Error(`Rule alias collides with an id: ${rule.alias}`);
+            }
+            aliases.add(rule.alias);
+        }
+        if (!rule.description) {
+            throw new Error(`Rule ${rule.id} is missing description`);
+        }
+        if (!rule.docs?.summary) {
+            throw new Error(`Rule ${rule.id} is missing docs.summary`);
+        }
+    }
+}
+export function resolveRuleReference(rules, reference) {
+    return rules.find((rule) => rule.id === reference || rule.alias === reference);
+}

package/dist/rules/utils.d.ts

@@ -0,0 +1,42 @@
+import type { BlockType, NormalizedDocument, SectionNode } from "../types.js";
+export declare function groupSectionsByFile(sections: SectionNode[]): Map<string, SectionNode[]>;
+export declare function parseColumnCount(line: string): number | undefined;
+export declare function countTableCells(line: string): number;
+export declare function isComplexTableCellLine(line: string): boolean;
+export declare function isBlockDelimiter(value: string): boolean;
+export declare function blockDelimiterType(value: string): BlockType | undefined;
+export declare function isListMarkerLine(line: string): boolean;
+export declare function isListMarkerResidueLine(line: string): boolean;
+export declare function isUnderlineResidueLine(line: string): boolean;
+export declare function isLineComment(line: string): boolean;
+export declare function isLineInCommentParagraph(lines: string[], index: number): boolean;
+export declare function listMarkerContent(line: string): {
+    content: string;
+    offset: number;
+};
+export declare function isAsciiDocTitleLine(line: string): boolean;
+export declare function getAsciiDocTitle(line: string): string | undefined;
+export declare function isAsciiDocSectionTitleLine(line: string): boolean;
+export declare function isAsciiDocAnchorLine(line: string): boolean;
+export declare function isAsciiDocBlockAttributeLine(line: string): boolean;
+export declare function isAsciiDocAttributeEntryLine(line: string): boolean;
+export declare function isExemptBeforeListLine(line: string): boolean;
+export declare function hasTitleImmediatelyBefore(lines: string[], index: number): boolean;
+export declare function findPrecedingTitleLineIndex(lines: string[], index: number): number | undefined;
+export declare function hasAnchorForTitledBlock(lines: string[], index: number): boolean;
+export declare function getAnchorForTitledBlock(lines: string[], index: number): string | undefined;
+export declare function parseAsciiDocAnchor(line: string): string | undefined;
+export declare function hasExplicitId(id: string | boolean | undefined): boolean;
+export declare function precedingAttributeLines(lines: string[], index: number): string[];
+export declare function isDiagramStyleLine(line: string): boolean;
+export declare function isLineInProtectedBlock(document: NormalizedDocument, file: string, line: number): boolean;
+export declare function isLineInTableBlock(document: NormalizedDocument, file: string, line: number): boolean;
+export declare function markdownResidueIssue(line: string): {
+    message: string;
+    fixHelper: string;
+    column: number;
+    endColumn: number;
+    replacement?: string;
+    severity: "warning" | "error";
+} | undefined;
+export declare function getRequiredSections(config: unknown): string[];

package/dist/rules/utils.js

@@ -0,0 +1,274 @@
+import path from "node:path";
+export function groupSectionsByFile(sections) {
+    const result = new Map();
+    for (const section of sections) {
+        const list = result.get(section.range.start.file) ?? [];
+        list.push(section);
+        result.set(section.range.start.file, list);
+    }
+    return result;
+}
+export function parseColumnCount(line) {
+    const match = line.match(/cols="([^"]+)"/);
+    if (!match) {
+        return undefined;
+    }
+    return (match[1] ?? "").split(",").filter(Boolean).length;
+}
+export function countTableCells(line) {
+    return [...line.matchAll(/(?<!\\)\|/g)].length;
+}
+export function isComplexTableCellLine(line) {
+    const trimmed = line.trim();
+    return /(^|\s)(?:\.\d+\+|\d+\+|\d+\.\d+\+|[a-z])\|/i.test(trimmed)
+        || /\b[aehlmdsv]\|/.test(trimmed)
+        || /\+$/.test(trimmed);
+}
+export function isBlockDelimiter(value) {
+    return blockDelimiterType(value) !== undefined;
+}
+export function blockDelimiterType(value) {
+    const trimmed = value.trim();
+    if (/^={4,}$/.test(trimmed)) {
+        return "example";
+    }
+    if (/^-{4,}$/.test(trimmed)) {
+        return "listing";
+    }
+    if (/^\.{4,}$/.test(trimmed)) {
+        return "literal";
+    }
+    if (/^\+{4,}$/.test(trimmed)) {
+        return "passthrough";
+    }
+    if (/^_{4,}$/.test(trimmed)) {
+        return "quote";
+    }
+    if (/^\*{4,}$/.test(trimmed)) {
+        return "sidebar";
+    }
+    if (/^\/{4,}$/.test(trimmed)) {
+        return "comment";
+    }
+    if (trimmed === "--") {
+        return "unknown";
+    }
+    if (/^[|,!:]={3,}$/.test(trimmed)) {
+        return "table";
+    }
+    return undefined;
+}
+export function isListMarkerLine(line) {
+    return isUnorderedOrOrderedListMarkerLine(line) || isDescriptionListMarkerLine(line);
+}
+export function isListMarkerResidueLine(line) {
+    const trimmed = line.trim();
+    return !isBlockDelimiter(trimmed) && /^(?:\*+|-|\.+|\d+\.)$/.test(trimmed);
+}
+export function isUnderlineResidueLine(line) {
+    return line.trim() === "___";
+}
+function isUnorderedOrOrderedListMarkerLine(line) {
+    return /^(\s*)([*-]+|\d+\.|\.+)\s+\S/.test(line);
+}
+function isDescriptionListMarkerLine(line) {
+    return /^\s*\S.*?(?::::|:::|::|;;)(?:\s+\S|\s*$)/.test(line);
+}
+export function isLineComment(line) {
+    return line.trimStart().startsWith("//");
+}
+export function isLineInCommentParagraph(lines, index) {
+    if ((lines[index] ?? "").trim() === "") {
+        return false;
+    }
+    let cursor = index - 1;
+    while (cursor >= 0 && (lines[cursor] ?? "").trim() !== "") {
+        if ((lines[cursor] ?? "").trim() === "[comment]") {
+            return true;
+        }
+        cursor -= 1;
+    }
+    return false;
+}
+export function listMarkerContent(line) {
+    const match = line.match(/^(\s*)([*-]+|\d+\.|\.+)\s+(\S.*)$/);
+    if (!match) {
+        const descriptionMatch = line.match(/^(\s*)\S.*?(?::::|:::|::|;;)(?:\s+(\S.*)|\s*$)/);
+        if (!descriptionMatch) {
+            return { content: line, offset: 0 };
+        }
+        const offset = (descriptionMatch[0]?.length ?? 0) - (descriptionMatch[2]?.length ?? 0);
+        return { content: descriptionMatch[2] ?? "", offset };
+    }
+    return {
+        content: match[3] ?? "",
+        offset: (match[1]?.length ?? 0) + (match[2]?.length ?? 0) + 1,
+    };
+}
+export function isAsciiDocTitleLine(line) {
+    const trimmed = line.trim();
+    return /^\.[^\s.].+/.test(trimmed) || /^\[[^\]]*\btitle\s*=/.test(trimmed);
+}
+export function getAsciiDocTitle(line) {
+    const trimmed = line.trim();
+    const blockTitle = trimmed.match(/^\.(?!\s|\.)((?:.|\s)+)$/);
+    if (blockTitle) {
+        return blockTitle[1]?.trim();
+    }
+    const attributeTitle = trimmed.match(/^\[[^\]]*\btitle\s*=\s*(?:"([^"]*)"|'([^']*)'|([^,\]]+))/);
+    return attributeTitle ? (attributeTitle[1] ?? attributeTitle[2] ?? attributeTitle[3] ?? "").trim() : undefined;
+}
+export function isAsciiDocSectionTitleLine(line) {
+    return /^(=+|#+)\s+\S/.test(line.trim());
+}
+export function isAsciiDocAnchorLine(line) {
+    return parseAsciiDocAnchor(line) !== undefined;
+}
+export function isAsciiDocBlockAttributeLine(line) {
+    return /^\[[^\]]*]\s*$/.test(line.trim()) && !isAsciiDocAnchorLine(line);
+}
+export function isAsciiDocAttributeEntryLine(line) {
+    return /^:[^:\s][^:\n]*:\s*.*$/.test(line.trim());
+}
+export function isExemptBeforeListLine(line) {
+    const trimmed = line.trim();
+    return trimmed === ""
+        || trimmed === "+"
+        || /^\/\//.test(trimmed)
+        || isAsciiDocSectionTitleLine(line)
+        || isListMarkerLine(line)
+        || isBlockDelimiter(trimmed)
+        || isAsciiDocTitleLine(line)
+        || isAsciiDocAnchorLine(line)
+        || isAsciiDocBlockAttributeLine(line);
+}
+export function hasTitleImmediatelyBefore(lines, index) {
+    return findPrecedingTitleLineIndex(lines, index) !== undefined;
+}
+export function findPrecedingTitleLineIndex(lines, index) {
+    let cursor = index - 1;
+    while (cursor >= 0) {
+        const line = lines[cursor] ?? "";
+        if (isAsciiDocTitleLine(line)) {
+            return cursor;
+        }
+        if (!isAsciiDocAnchorLine(line) && !isAsciiDocBlockAttributeLine(line) && line.trim() !== "") {
+            return undefined;
+        }
+        cursor -= 1;
+    }
+    return undefined;
+}
+export function hasAnchorForTitledBlock(lines, index) {
+    return getAnchorForTitledBlock(lines, index) !== undefined;
+}
+export function getAnchorForTitledBlock(lines, index) {
+    const titleIndex = findPrecedingTitleLineIndex(lines, index);
+    if (titleIndex === undefined) {
+        return undefined;
+    }
+    for (let cursor = titleIndex + 1; cursor < index; cursor += 1) {
+        const anchor = parseAsciiDocAnchor(lines[cursor] ?? "");
+        if (anchor) {
+            return anchor;
+        }
+    }
+    let cursor = titleIndex - 1;
+    while (cursor >= 0 && isAsciiDocBlockAttributeLine(lines[cursor] ?? "")) {
+        cursor -= 1;
+    }
+    return cursor >= 0 ? parseAsciiDocAnchor(lines[cursor] ?? "") : undefined;
+}
+export function parseAsciiDocAnchor(line) {
+    const match = line.trim().match(/^\[\[([^\]]+)]]\s*$|^\[#([^,\]\s]+)(?:,[^\]]*)?]\s*$/);
+    return match ? (match[1] ?? match[2]) : undefined;
+}
+export function hasExplicitId(id) {
+    return typeof id === "string" ? id.trim().length > 0 : id === true;
+}
+export function precedingAttributeLines(lines, index) {
+    const attributes = [];
+    let cursor = index - 1;
+    while (cursor >= 0) {
+        const line = lines[cursor] ?? "";
+        if (isAsciiDocBlockAttributeLine(line)) {
+            attributes.unshift(line.trim());
+            cursor -= 1;
+            continue;
+        }
+        if (isAsciiDocAnchorLine(line) || isAsciiDocTitleLine(line)) {
+            cursor -= 1;
+            continue;
+        }
+        break;
+    }
+    return attributes;
+}
+export function isDiagramStyleLine(line) {
+    return /^\[(?:a2s|actdiag|blockdiag|bytefield|dbml|ditaa|dot|dpic|drawio|erd|gnuplot|goat|graphviz|lilypond|matplotlib|mermaid|mmpviz|mscgen|nomnoml|nwdiag|packetdiag|penrose|pikchr|pintora|plantuml|rackdiag|seqdiag|shaape|smcat|state-machine-cat|structurizr|svgbob|symbolator|syntrax|umlet|vega|vega-lite|vegalite|wavedrom)(?:,|\])/.test(line.trim());
+}
+export function isLineInProtectedBlock(document, file, line) {
+    return document.blocks.some((block) => (path.resolve(block.range.start.file) === path.resolve(file)
+        && ["listing", "literal", "passthrough", "source", "stem", "diagram", "comment"].includes(block.type)
+        && block.range.start.line < line
+        && (block.range.end?.line ?? block.range.start.line) > line));
+}
+export function isLineInTableBlock(document, file, line) {
+    return document.blocks.some((block) => (path.resolve(block.range.start.file) === path.resolve(file)
+        && block.type === "table"
+        && block.range.start.line < line
+        && (block.range.end?.line ?? block.range.start.line) > line));
+}
+export function markdownResidueIssue(line) {
+    const markdownImage = line.match(/!\[[^\]]*]\([^)]+\)/);
+    if (markdownImage?.index !== undefined) {
+        const parsed = markdownImage[0].match(/^!\[([^\]]*)]\(([^)]+)\)$/);
+        const standalone = line.trim() === markdownImage[0];
+        return {
+            severity: "warning",
+            message: "Markdown image syntax renders as text in AsciiDoc",
+            fixHelper: "Use image::target[Alt text].",
+            column: markdownImage.index + 1,
+            endColumn: markdownImage.index + markdownImage[0].length + 1,
+            replacement: parsed ? `${standalone ? "image::" : "image:"}${parsed[2] ?? ""}[${parsed[1] ?? ""}]` : undefined,
+        };
+    }
+    const markdownLink = line.match(/(?<!!)\[[^\]]+]\([^)]+\)/);
+    if (markdownLink?.index !== undefined) {
+        const parsed = markdownLink[0].match(/^\[([^\]]+)]\(([^)]+)\)$/);
+        return {
+            severity: "warning",
+            message: "Markdown link syntax renders as text in AsciiDoc",
+            fixHelper: "Use link:target[text] or xref:target[text].",
+            column: markdownLink.index + 1,
+            endColumn: markdownLink.index + markdownLink[0].length + 1,
+            replacement: parsed ? `${adocLinkMacro(parsed[2] ?? "")}:${parsed[2] ?? ""}[${parsed[1] ?? ""}]` : undefined,
+        };
+    }
+    const reversedMarkdownLink = line.match(/\([^)]+\)\[[^\]]+]/);
+    if (reversedMarkdownLink?.index !== undefined) {
+        const parsed = reversedMarkdownLink[0].match(/^\(([^)]+)\)\[([^\]]+)]$/);
+        return {
+            severity: "warning",
+            message: "Reversed Markdown link residue renders as text in AsciiDoc",
+            fixHelper: "Use link:target[text] or xref:target[text].",
+            column: reversedMarkdownLink.index + 1,
+            endColumn: reversedMarkdownLink.index + reversedMarkdownLink[0].length + 1,
+            replacement: parsed ? `${adocLinkMacro(parsed[1] ?? "")}:${parsed[1] ?? ""}[${parsed[2] ?? ""}]` : undefined,
+        };
+    }
+    return undefined;
+}
+function adocLinkMacro(target) {
+    return /\.(?:adoc|asciidoc|asc)(?:#|$)/i.test(target) ? "xref" : "link";
+}
+export function getRequiredSections(config) {
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+        return [];
+    }
+    const requiredSections = config.requiredSections;
+    if (!Array.isArray(requiredSections)) {
+        return [];
+    }
+    return requiredSections.filter((section) => typeof section === "string");
+}