asciidoclint 0.5.0

package/dist/rules/AD019.js

@@ -0,0 +1,58 @@
+import fs from "node:fs";
+import { isAsciiDocAnchorLine, isAsciiDocAttributeEntryLine, isAsciiDocBlockAttributeLine, isBlockDelimiter, isLineComment, isLineInProtectedBlock } from "./utils.js";
+export const AD019 = {
+    id: "AD019",
+    alias: "content-after-include",
+    description: "Text should not be attached directly after include directives",
+    tags: ["core", "structure", "includes"],
+    parser: "text",
+    docs: {
+        summary: "A paragraph immediately after an include directive can accidentally attach to included content.",
+        rationale: "A section boundary or blank-separated block after an include keeps merged documents predictable.",
+        badExamples: [{ code: "include::chapter.adoc[]\nThis paragraph attaches unexpectedly." }],
+        goodExamples: [{ code: "include::chapter.adoc[]\n\n== Next Section\n\nThis paragraph is separate." }],
+        fixability: "no",
+        fixHelper: "Insert a blank line after the include directive or ensure the included file ends with a blank line.",
+    },
+    function: ({ document }, onError) => {
+        for (const file of document.files) {
+            for (const [index, line] of file.lines.entries()) {
+                if (!/^include::[^\[]+\[[^\]]*]\s*$/.test(line.trim()) || isLineInProtectedBlock(document, file.file, index + 1)) {
+                    continue;
+                }
+                const include = document.includes.find((record) => record.range.start.file === file.file && record.range.start.line === index + 1);
+                if (include && (include.attributes.tag !== undefined || include.attributes.tags !== undefined || include.attributes.lines !== undefined)) {
+                    continue;
+                }
+                if (include?.resolvedTarget && includedFileEndsWithBlankLine(include.resolvedTarget)) {
+                    continue;
+                }
+                const next = file.lines[index + 1] ?? "";
+                if (next.trim() === ""
+                    || /^include::[^\[]+\[[^\]]*]\s*$/.test(next.trim())
+                    || isBlockDelimiter(next.trim())
+                    || isLineComment(next)
+                    || isAsciiDocAnchorLine(next)
+                    || isAsciiDocAttributeEntryLine(next)
+                    || isAsciiDocBlockAttributeLine(next)) {
+                    continue;
+                }
+                onError({
+                    severity: "warning",
+                    message: "Content immediately after include should start a clear block or section",
+                    range: { start: { file: file.file, line: index + 2, column: 1 } },
+                    fixHelper: "Insert a blank line after the include directive or ensure the included file ends with a blank line.",
+                });
+            }
+        }
+    },
+};
+function includedFileEndsWithBlankLine(file) {
+    try {
+        const content = fs.readFileSync(file, "utf8");
+        return /\r?\n\s*\r?\n\s*$/.test(content);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/rules/AD020.d.ts

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

package/dist/rules/AD020.js

@@ -0,0 +1,40 @@
+export const AD020 = {
+    id: "AD020",
+    alias: "appendix-section-level",
+    description: "Appendices should be section-level blocks in article documents",
+    tags: ["core", "structure"],
+    parser: "document",
+    docs: {
+        summary: "An appendix in an article document should use a section heading, not a second document title.",
+        rationale: "Asciidoctor documents article appendices as level-1 sections. A [appendix] block followed by = in an article triggers Asciidoctor's level-0 section error.",
+        badExamples: [{ code: "[appendix]\n= API Reference" }],
+        goodExamples: [
+            { code: "[appendix]\n== API Reference\n\n=== Child" },
+            { code: ":doctype: book\n\n= Book\n\n[appendix]\n= API Reference\n\n=== Child" },
+        ],
+        fixability: "no",
+        fixHelper: "In article documents, change the appendix heading to ==. Keep = only for a book appendix that is intentionally part-like.",
+    },
+    function: ({ document }, onError) => {
+        if (document.attributes.doctype === "book") {
+            return;
+        }
+        for (const file of document.files) {
+            for (const [index, line] of file.lines.entries()) {
+                if (line.trim() !== "[appendix]") {
+                    continue;
+                }
+                const title = file.lines[index + 1] ?? "";
+                if (!/^=\s+\S/.test(title)) {
+                    continue;
+                }
+                onError({
+                    severity: "warning",
+                    message: "Appendix should use a section-level heading",
+                    range: { start: { file: file.file, line: index + 2, column: 1 } },
+                    fixHelper: "Use == for an article appendix heading, with === or deeper headings for child sections. Keep = only for a book appendix that is intentionally part-like.",
+                });
+            }
+        }
+    },
+};

package/dist/rules/AD022.d.ts

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

package/dist/rules/AD022.js

@@ -0,0 +1,55 @@
+export const AD022 = {
+    id: "AD022",
+    alias: "circular-include",
+    description: "Include trees must not contain cycles",
+    tags: ["core", "includes", "structure"],
+    parser: "project",
+    docs: {
+        summary: "Include trees should not be circular.",
+        rationale: "Asciidoctor stops circular include expansion only after the include-depth limit is exceeded; reporting the actual cycle gives authors a direct repair target.",
+        fixability: "no",
+        fixHelper: "Remove one include from the reported cycle, or replace one edge with an xref or a smaller shared partial that does not include its parent.",
+        badExamples: [{ code: "include::a.adoc[]\n// a.adoc includes this file again" }],
+        goodExamples: [{ code: "include::chapter.adoc[]\ninclude::appendix.adoc[]" }],
+    },
+    function: ({ file, document }, onError) => {
+        const reportedCycles = new Set();
+        const explored = new Set();
+        const graph = new Map();
+        for (const include of document.includes) {
+            if (include.status !== "resolved" || !include.resolvedTarget) {
+                continue;
+            }
+            const source = include.range.start.file;
+            const targets = graph.get(source) ?? [];
+            targets.push({ target: include.resolvedTarget, range: include.range });
+            graph.set(source, targets);
+        }
+        const root = document.file || file;
+        visit(root, [root]);
+        function visit(current, stack) {
+            if (explored.has(current)) {
+                return;
+            }
+            for (const edge of graph.get(current) ?? []) {
+                const cycleStart = stack.indexOf(edge.target);
+                if (cycleStart !== -1) {
+                    const cycle = [...stack.slice(cycleStart), edge.target].join(" -> ");
+                    if (!reportedCycles.has(cycle)) {
+                        reportedCycles.add(cycle);
+                        onError({
+                            severity: "error",
+                            message: "Circular include detected",
+                            detail: cycle,
+                            range: edge.range,
+                            fixHelper: "Remove one include from the reported cycle, or replace one edge with an xref or a shared partial.",
+                        });
+                    }
+                    continue;
+                }
+                visit(edge.target, [...stack, edge.target]);
+            }
+            explored.add(current);
+        }
+    },
+};

package/dist/rules/AD023.d.ts

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

package/dist/rules/AD023.js

@@ -0,0 +1,59 @@
+import { parseAsciiDocAnchor } from "./utils.js";
+export const AD023 = {
+    id: "AD023",
+    alias: "empty-section",
+    description: "Sections should contain body content or child sections",
+    tags: ["core", "structure", "references"],
+    parser: "document",
+    docs: {
+        summary: "Sections should not be empty.",
+        rationale: "Asciidoctor accepts empty sections and creates section IDs for them, but visible empty outline nodes are usually conversion residue or unfinished structure.",
+        fixability: "no",
+        fixHelper: "Add body content, add a child section that belongs under this heading, or remove the empty section if it is only conversion/bookmark residue.",
+        badExamples: [{ code: "== Empty\n\n== Next" }],
+        goodExamples: [
+            { code: "== Overview\n\nContent." },
+            { code: "== Container\n\n=== Child\n\nContent." },
+        ],
+    },
+    function: ({ document }, onError) => {
+        for (const section of document.sections) {
+            if (section.level === 0 || section.children.length > 0 || hasSectionBodyContent(document, section)) {
+                continue;
+            }
+            onError({
+                severity: "info",
+                message: "Section has no body content or child sections",
+                range: section.titleRange,
+                fixHelper: "Add body content, add a child section, or remove the empty section if it is only conversion/bookmark residue.",
+            });
+        }
+    },
+};
+function hasSectionBodyContent(document, section) {
+    const file = document.files.find((candidate) => candidate.file === section.titleRange.start.file);
+    if (!file) {
+        return false;
+    }
+    const startLine = section.titleRange.start.line + 1;
+    const endLine = nextSiblingOrAncestorLine(document, section) ?? file.lines.length + 1;
+    for (let lineNumber = startLine; lineNumber < endLine; lineNumber += 1) {
+        const line = file.lines[lineNumber - 1] ?? "";
+        if (isBodyContentLine(line)) {
+            return true;
+        }
+    }
+    return false;
+}
+function nextSiblingOrAncestorLine(document, section) {
+    return document.sections
+        .filter((candidate) => candidate.titleRange.start.file === section.titleRange.start.file)
+        .filter((candidate) => candidate.titleRange.start.line > section.titleRange.start.line)
+        .filter((candidate) => candidate.level <= section.level)
+        .sort((left, right) => left.titleRange.start.line - right.titleRange.start.line)[0]
+        ?.titleRange.start.line;
+}
+function isBodyContentLine(line) {
+    const trimmed = line.trim();
+    return trimmed !== "" && !trimmed.startsWith("//") && !parseAsciiDocAnchor(line);
+}

package/dist/rules/AD024.d.ts

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

package/dist/rules/AD024.js

@@ -0,0 +1,30 @@
+export const AD024 = {
+    id: "AD024",
+    alias: "missing-include",
+    description: "Include targets should exist after attribute substitution",
+    tags: ["dependencies", "include"],
+    parser: "dependency",
+    docs: {
+        summary: "include:: targets should resolve to an existing file.",
+        rationale: "Asciidoctor reports missing required includes as parser diagnostics and renders an unresolved directive. AD024 reports the same dependency failure through the normalized dependency graph so it is configurable and available even when users focus on dependency rules.",
+        fixability: "no",
+        fixHelper: "Create the included file, fix the include target or attribute value, or mark the include optional when it is intentionally absent.",
+        badExamples: [{ code: "include::{chapter-file}[]" }],
+        goodExamples: [
+            { code: ":chapter-file: chapter.adoc\ninclude::{chapter-file}[]" },
+            { code: "include::optional-chapter.adoc[opts=optional]" },
+        ],
+    },
+    function: ({ dependencies }, onError) => {
+        for (const record of dependencies.records) {
+            if (record.type === "include" && record.status === "missing") {
+                onError({
+                    severity: "error",
+                    message: `Missing include target: ${record.target}`,
+                    range: record.range,
+                    fixHelper: "Create the included file, fix the include path or attribute value, or add opts=optional if the missing include is intentional.",
+                });
+            }
+        }
+    },
+};

package/dist/rules/AD025.d.ts

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

package/dist/rules/AD025.js

@@ -0,0 +1,32 @@
+export const AD025 = {
+    id: "AD025",
+    alias: "missing-image",
+    description: "Image targets should exist after attribute substitution",
+    tags: ["dependencies", "image"],
+    parser: "dependency",
+    docs: {
+        summary: "image:: targets should resolve to an existing file.",
+        rationale: "Asciidoctor can emit HTML that points at a missing image path, but publishable output is incomplete and PDF/data-uri style conversions need the asset at conversion time.",
+        fixability: "no",
+        fixHelper: "Create the image file, fix the image target or imagesdir value, or use a URL target when the image is intentionally remote.",
+        badExamples: [{ code: "image::missing.png[]" }],
+        goodExamples: [
+            { code: "image::diagram.png[Architecture diagram]" },
+            { code: ":imagesdir: images\nimage::diagram.png[Architecture diagram]" },
+            { code: "See image:icon.svg[Status icon]." },
+            { code: "image::https://example.com/diagram.png[Remote diagram]" },
+        ],
+    },
+    function: ({ dependencies }, onError) => {
+        for (const record of dependencies.records) {
+            if (record.type === "image" && record.status === "missing") {
+                onError({
+                    severity: "error",
+                    message: `Missing image target: ${record.target}`,
+                    range: record.range,
+                    fixHelper: "Create the image file, fix the image target or imagesdir value, or use a URL target when the image is intentionally remote.",
+                });
+            }
+        }
+    },
+};

package/dist/rules/AD026.d.ts

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

package/dist/rules/AD026.js

@@ -0,0 +1,26 @@
+export const AD026 = {
+    id: "AD026",
+    alias: "missing-xref",
+    description: "Cross-reference targets should resolve to an anchor or file",
+    tags: ["dependencies", "xref"],
+    parser: "dependency",
+    docs: {
+        summary: "xref and shorthand cross references should resolve to a known local anchor or file.",
+        badExamples: [{ code: "xref:missing-section[]\n\nSee <<missing-section>>." }],
+        goodExamples: [{ code: "[[overview]]\n== Overview\n\nxref:overview[]\n\nSee <<Overview>>." }],
+        fixability: "no",
+        fixHelper: "Create the referenced anchor/file or fix the xref target.",
+    },
+    function: ({ dependencies }, onError) => {
+        for (const record of dependencies.records) {
+            if (record.type === "xref" && record.status === "missing") {
+                onError({
+                    severity: "error",
+                    message: `Missing xref target: ${record.target}`,
+                    range: record.range,
+                    fixHelper: "Create the referenced anchor/file or fix the xref target.",
+                });
+            }
+        }
+    },
+};

package/dist/rules/AD027.d.ts

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

package/dist/rules/AD027.js

@@ -0,0 +1,31 @@
+export const AD027 = {
+    id: "AD027",
+    alias: "missing-local-link",
+    description: "Local link targets should resolve to existing files",
+    tags: ["dependencies", "links"],
+    parser: "dependency",
+    docs: {
+        summary: "Local link: targets should resolve to existing files.",
+        rationale: "Asciidoctor renders relative link: targets without checking the target file. A missing local target becomes a broken link in the published document.",
+        fixability: "no",
+        fixHelper: "Create the linked file, fix the local link target, or change the target to an xref or URL when that is the intended link type.",
+        badExamples: [{ code: "link:missing.pdf[Download]" }],
+        goodExamples: [
+            { code: "link:datasheet.pdf[Download]" },
+            { code: "link:tools.html#editors[Editors]" },
+            { code: "https://example.com/downloads/report.pdf[Download]" },
+        ],
+    },
+    function: ({ dependencies }, onError) => {
+        for (const record of dependencies.records) {
+            if (record.type === "attachment" && record.status === "missing") {
+                onError({
+                    severity: "error",
+                    message: `Missing local link target: ${record.target}`,
+                    range: record.range,
+                    fixHelper: "Create the linked file, fix the local link target, or use xref:/URL syntax if this is not a local file link.",
+                });
+            }
+        }
+    },
+};

package/dist/rules/AD028.d.ts

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

package/dist/rules/AD028.js

@@ -0,0 +1,113 @@
+import path from "node:path";
+import { isLineInProtectedBlock } from "./utils.js";
+const inlineImagePattern = /(^|[^\w:])image:(?!:)([^\s\[]+)\[((?:\\]|[^\]])*)]/g;
+export const AD028 = {
+    id: "AD028",
+    alias: "image-alt-text",
+    description: "Images should not explicitly set empty alt text",
+    tags: ["accessibility", "image"],
+    parser: "document",
+    docs: {
+        summary: "Image macros should not explicitly set empty alt text.",
+        rationale: "Asciidoctor derives fallback alt text from the image target when the attribute list is empty. An explicit empty alt attribute renders an empty alt value, which weakens accessible output and fallback text.",
+        fixability: "no",
+        fixHelper: "Replace the empty alt attribute with concise text that identifies the image purpose, or remove the explicit empty alt when the derived target name is acceptable.",
+        badExamples: [{ code: "image::diagram.png[alt=\"\"]\n\nClick image:play.png[\"\"] to start." }],
+        goodExamples: [{ code: "image::diagram.png[Architecture diagram]\n\nClick image:play.png[Play] to start." }],
+    },
+    function: ({ document }, onError) => {
+        for (const block of document.blocks.filter((candidate) => candidate.type === "image")) {
+            if (typeof block.attributes.alt !== "string" || block.attributes.alt.trim() === "") {
+                const target = String(block.attributes.target ?? "image");
+                onError({
+                    severity: "warning",
+                    message: `Image is missing alt text: ${path.basename(target)}`,
+                    range: block.range,
+                    fixHelper: "Add meaningful text as the first image macro attribute, such as image::target.png[Architecture diagram].",
+                });
+            }
+        }
+        for (const file of document.files) {
+            for (const [index, line] of file.lines.entries()) {
+                if (isLineInProtectedBlock(document, file.file, index + 1)) {
+                    continue;
+                }
+                for (const match of line.matchAll(inlineImagePattern)) {
+                    const attributes = match[3] ?? "";
+                    if (!hasExplicitEmptyAlt(attributes)) {
+                        continue;
+                    }
+                    const target = match[2] ?? "image";
+                    const prefixLength = match[1]?.length ?? 0;
+                    onError({
+                        severity: "warning",
+                        message: `Image is missing alt text: ${path.basename(target)}`,
+                        range: {
+                            start: {
+                                file: file.file,
+                                line: index + 1,
+                                column: (match.index ?? 0) + prefixLength + 1,
+                            },
+                        },
+                        fixHelper: "Add meaningful text as the first inline image macro attribute, such as image:target.png[Status icon].",
+                    });
+                }
+            }
+        }
+    },
+};
+function hasExplicitEmptyAlt(attributes) {
+    for (const [index, entry] of splitAttributeEntries(attributes).entries()) {
+        const named = entry.match(/^([A-Za-z_][A-Za-z0-9_.-]*)\s*=\s*(.*)$/);
+        if (named) {
+            const name = named[1] ?? "";
+            const value = named[2] ?? "";
+            if (name.toLowerCase() === "alt" && unquote(value).trim() === "") {
+                return true;
+            }
+            continue;
+        }
+        if (index === 0 && /^(['"])(?:\s*)\1$/.test(entry.trim())) {
+            return true;
+        }
+    }
+    return false;
+}
+function splitAttributeEntries(attributes) {
+    const entries = [];
+    let current = "";
+    let quote;
+    for (let index = 0; index < attributes.length; index += 1) {
+        const character = attributes[index] ?? "";
+        if (character === "\\" && index + 1 < attributes.length) {
+            current += character + (attributes[index + 1] ?? "");
+            index += 1;
+            continue;
+        }
+        if ((character === "\"" || character === "'") && quote === undefined) {
+            quote = character;
+            current += character;
+            continue;
+        }
+        if (character === quote) {
+            quote = undefined;
+            current += character;
+            continue;
+        }
+        if (character === "," && quote === undefined) {
+            entries.push(current.trim());
+            current = "";
+            continue;
+        }
+        current += character;
+    }
+    entries.push(current.trim());
+    return entries;
+}
+function unquote(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}

package/dist/rules/AD029.d.ts

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

package/dist/rules/AD029.js

@@ -0,0 +1,46 @@
+import { isLineInProtectedBlock, markdownResidueIssue } from "./utils.js";
+export const AD029 = {
+    id: "AD029",
+    alias: "markdown-link-image-residue",
+    description: "Markdown link and image residue should not render as text",
+    tags: ["conversion", "link", "image"],
+    parser: "text",
+    docs: {
+        summary: "Flag Markdown link, image, and reversed-link patterns that Asciidoctor renders as paragraph text instead of links or images.",
+        rationale: "Asciidoctor accepts some Markdown-compatible syntax, including Markdown-style headings and fenced code blocks. This rule only flags known conversion residue that does not become the intended AsciiDoc structure.",
+        fixability: "unsafe",
+        fixHelper: "Rewrite the residue using the intended AsciiDoc macro: link:target[text], xref:target[text], or image::target[Alt text].",
+        badExamples: [{ code: "See [Architecture](architecture.adoc).\n\n![Alt](image.png)\n\n(https://example.com)[Example]" }],
+        goodExamples: [{ code: "See xref:architecture.adoc[Architecture].\n\nimage::image.png[Alt]\n\nlink:https://example.com[Example]" }],
+    },
+    function: ({ document }, onError) => {
+        for (const file of document.files) {
+            for (const [index, line] of file.lines.entries()) {
+                if (isLineInProtectedBlock(document, file.file, index + 1)) {
+                    continue;
+                }
+                const issue = markdownResidueIssue(line);
+                if (!issue) {
+                    continue;
+                }
+                onError({
+                    severity: issue.severity,
+                    message: issue.message,
+                    range: { start: { file: file.file, line: index + 1, column: issue.column } },
+                    fixHelper: issue.fixHelper,
+                    fix: issue.replacement ? {
+                        applicability: "unsafe",
+                        edits: [{
+                                file: file.file,
+                                range: {
+                                    start: { file: file.file, line: index + 1, column: issue.column },
+                                    end: { file: file.file, line: index + 1, column: issue.endColumn },
+                                },
+                                replacement: issue.replacement,
+                            }],
+                    } : undefined,
+                });
+            }
+        }
+    },
+};

package/dist/rules/AD030.d.ts

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

package/dist/rules/AD030.js

@@ -0,0 +1,33 @@
+import { isLineInProtectedBlock, isLineInTableBlock } from "./utils.js";
+export const AD030 = {
+    id: "AD030",
+    alias: "markdown-table-residue",
+    description: "Markdown pipe table residue should not render as text",
+    tags: ["conversion", "table"],
+    parser: "text",
+    docs: {
+        summary: "Flag Markdown pipe table separator lines that Asciidoctor renders as paragraph text.",
+        rationale: "Asciidoctor documents Markdown-compatible headings, fenced code blocks, blockquotes, and thematic breaks, but not Markdown pipe tables. Converted Markdown tables often appear table-like in source while rendering as plain paragraphs.",
+        fixability: "no",
+        fixHelper: "Rewrite the Markdown pipe table as an AsciiDoc table delimited by |=== and verify column structure manually.",
+        badExamples: [{ code: "| A | B |\n|---|---|" }],
+        goodExamples: [{ code: "|===\n| A | B\n|===" }],
+    },
+    function: ({ document }, onError) => {
+        for (const file of document.files) {
+            for (const [index, line] of file.lines.entries()) {
+                if (!/^\s*\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?\s*$/.test(line)
+                    || isLineInProtectedBlock(document, file.file, index + 1)
+                    || isLineInTableBlock(document, file.file, index + 1)) {
+                    continue;
+                }
+                onError({
+                    severity: "warning",
+                    message: "Markdown pipe table separator renders as text in AsciiDoc",
+                    range: { start: { file: file.file, line: index + 1, column: 1 } },
+                    fixHelper: "Rewrite this as an AsciiDoc table delimited by |===.",
+                });
+            }
+        }
+    },
+};

package/dist/rules/AD031.d.ts

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

package/dist/rules/AD031.js

@@ -0,0 +1,66 @@
+import { isLineInProtectedBlock } from "./utils.js";
+const outerLinkPattern = /(?:link|xref):[^\s\[]+\[|https?:\/\/[^\s\[]+\[/g;
+const nestedLinkPattern = /(?:link|xref):[^\s\[]+\[|<<[^>]+>>/;
+export const AD031 = {
+    id: "AD031",
+    alias: "no-nested-link-text",
+    description: "Link text should not contain nested links or cross references",
+    tags: ["links", "conversion"],
+    parser: "text",
+    docs: {
+        summary: "Visible link text should not contain another AsciiDoc link, URL macro, or shorthand cross reference.",
+        rationale: "Nested link markup can render invalid nested anchors, malformed labels, or escaped reference text. This is often conversion residue from HTML or Markdown sources.",
+        fixability: "no",
+        fixHelper: "Replace the nested link markup with plain visible text, or split the sentence into separate links.",
+        badExamples: [{ code: "link:https://example.com[link:https://nested.example[Nested]]\n\nxref:target.adoc[<<target,Target>>]" }],
+        goodExamples: [{ code: "link:https://example.com[Example]" }],
+    },
+    function: ({ document }, onError) => {
+        for (const file of document.files) {
+            for (const [index, line] of file.lines.entries()) {
+                if (isLineInProtectedBlock(document, file.file, index + 1)) {
+                    continue;
+                }
+                for (const match of line.matchAll(outerLinkPattern)) {
+                    const attrStart = (match.index ?? 0) + match[0].length;
+                    const attrText = linkAttributeText(line, attrStart);
+                    if (!attrText || !nestedLinkPattern.test(attrText)) {
+                        continue;
+                    }
+                    onError({
+                        severity: "warning",
+                        message: "Link text should not contain nested links or cross references",
+                        range: { start: { file: file.file, line: index + 1, column: (match.index ?? 0) + 1 } },
+                        fixHelper: "Replace nested link markup with plain visible text, or split this into separate links.",
+                    });
+                }
+            }
+        }
+    },
+};
+function linkAttributeText(line, start) {
+    let depth = 1;
+    let escaped = false;
+    for (let index = start; index < line.length; index += 1) {
+        const character = line[index] ?? "";
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (character === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (character === "[") {
+            depth += 1;
+            continue;
+        }
+        if (character === "]") {
+            depth -= 1;
+            if (depth === 0) {
+                return line.slice(start, index);
+            }
+        }
+    }
+    return undefined;
+}

package/dist/rules/AD032.d.ts

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