asciidoclint 1.0.0 → 1.2.0

package/README.md

@@ -9,12 +9,39 @@ CLI, AI-agent, and editor workflows.
 
 ## Install the npm package
 
+`asciidoclint` requires Node.js 20 or newer. The package does not install or
+manage Node.js; use the Node.js version chosen by your shell, package manager, or
+higher-level tooling.
+
+Install globally when you want `asciidoclint` available as a shell command:
+
+```bash
+npm install -g asciidoclint
+```
+
+If the shell cannot find `asciidoclint` after install, npm's global bin
+directory may not be on `PATH`. It is usually:
+
+```bash
+$(npm prefix -g)/bin
+```
+
+For documentation repositories that need a pinned project-local install without
+creating a project-root `package.json`, install under `.asciidoclint`:
+
 ```bash
-npm install --save-dev asciidoclint
+npm --prefix .asciidoclint install asciidoclint@<version>
 ```
 
 ## Use the CLI
 
+The examples below use `npx asciidoclint` because that works even when npm's
+global bin directory is not on `PATH`. If `asciidoclint` is recognized by your
+shell, you can use `asciidoclint` instead.
+
+If the package is installed with the dedicated project-local layout, use
+`.asciidoclint/node_modules/.bin/asciidoclint`.
+
 Run lint:
 
 ```bash
@@ -60,26 +87,43 @@ reporting.
 
 ## Install the AI skill
 
-The repository ships an `asciidoclint` skill for AI agents. Install it from the
-npm package:
+The npm package includes an `asciidoclint` skill for AI agents. Installing the
+npm package does not automatically install the skill into agent roots; run
+`install-skill` explicitly.
+
+For a user-global skill install:
 
 ```bash
 npx asciidoclint install-skill
 ```
 
-Or install it directly from GitHub with the open skills CLI:
+This copies the bundled skill to `~/.agents/skills/asciidoclint` and creates
+`~/.claude/skills/asciidoclint` as a symbolic link to that copy.
+
+For a pinned project-local skill install:
 
 ```bash
-npx skills add f33lgood/asciidoclint --skill asciidoclint -a codex -g
+npm --prefix .asciidoclint install asciidoclint@<version>
+.asciidoclint/node_modules/.bin/asciidoclint install-skill --project
 ```
 
-Remove the installed skill when you want to use `asciidoclint` without AI skill
-assistance:
+This creates symbolic links at `.agents/skills/asciidoclint` and
+`.claude/skills/asciidoclint`, pointing to the skill source bundled with the
+package or checkout that ran `install-skill`. Add `--force` only when replacing
+an existing project-local skill install.
+
+Remove installed skills explicitly:
 
 ```bash
 npx asciidoclint uninstall-skill
+npx asciidoclint uninstall-skill --project
 ```
 
+Normal npm uninstall removes package files only. It does not remove
+`~/.agents/skills/asciidoclint`, `~/.claude/skills/asciidoclint`,
+`.agents/skills/asciidoclint`, or `.claude/skills/asciidoclint`; run
+`uninstall-skill` for those.
+
 The public skill exposes these user-facing workflows:
 
 | Workflow | Purpose |
@@ -122,6 +166,7 @@ extension commands and settings.
 | `AD006/included-document-title` | Included AsciiDoc files should not introduce a level-0 title without level offset |
 | `AD007/heading-depth-limit` | Section headings should not exceed Asciidoctor's supported depth |
 | `AD008/blank-before-list` | Lists should be separated from preceding paragraph text |
+| `AD009/blank-after-list` | Lists should be separated from following structural blocks |
 | `AD010/table-title` | Table blocks should have a title |
 | `AD011/image-title` | Block images should have a title |
 | `AD012/diagram-title` | Diagram blocks should have a title |
@@ -129,14 +174,14 @@ extension commands and settings.
 | `AD016/malformed-figure-caption` | Figure captions should use AsciiDoc title syntax |
 | `AD017/malformed-table-caption` | Table captions should use AsciiDoc title syntax |
 | `AD019/content-after-include` | Text should not be attached directly after include directives |
-| `AD020/appendix-section-level` | Appendices should be section-level blocks in article documents |
+| `AD020/appendix-placement` | Appendix markers should apply to documented appendix section levels |
 | `AD022/circular-include` | Include trees must not contain cycles |
 | `AD023/empty-section` | Sections should contain body content or child sections |
 | `AD024/missing-include` | Include targets should exist after attribute substitution |
 | `AD025/missing-image` | Image targets should exist after attribute substitution |
 | `AD026/missing-xref` | Cross-reference targets should resolve to an anchor or file |
 | `AD027/missing-local-link` | Local link targets should resolve to existing files |
-| `AD028/image-alt-text` | Images should not explicitly set empty alt text |
+| `AD028/image-alt-text` | Images should provide meaningful alt text |
 | `AD029/markdown-link-image-residue` | Markdown link and image residue should not render as text |
 | `AD030/markdown-table-residue` | Markdown pipe table residue should not render as text |
 | `AD031/no-nested-link-text` | Link text should not contain nested links or cross references |
@@ -152,6 +197,20 @@ extension commands and settings.
 | `AD043/section-title-start-left` | Section title syntax should start at the beginning of the line |
 | `AD044/local-adoc-link` | Local AsciiDoc files should be referenced with xref, not link |
 | `AD045/markdown-heading-mix` | Markdown-compatible headings should not be mixed with AsciiDoc headings |
+| `AD046/preface-placement` | Preface sections should match documented book placement |
+| `AD047/abstract-placement` | Abstract sections should match documented article placement |
+| `AD048/bibliography-placement` | Bibliography markers should apply to documented bibliography sections |
+| `AD049/glossary-placement` | Glossary markers should apply to documented glossary section levels |
+| `AD050/index-placement` | Index markers should apply to documented index section levels |
+| `AD051/partintro-placement` | Part introduction markers should apply to the introductory block of a book part |
+| `AD052/acknowledgments-placement` | Acknowledgments markers should apply to documented book section levels |
+| `AD053/dedication-placement` | Dedication markers should apply to documented book section levels |
+| `AD054/colophon-placement` | Colophon markers should apply to documented book section levels |
+| `AD055/docx-anchor-caption-residue` | DOCX anchor caption residue should be converted to AsciiDoc titles |
+| `AD056/dangling-blank-list-continuation` | Blank list continuations should not capture following content |
+| `AD057/semantic-anchor-target` | Semantic anchors should attach to the matching block type |
+| `AD058/docx-bookmark-hash-residue` | DOCX bookmark/hash residue should be cleaned up |
+| `AD059/docx-nested-table-structure` | DOCX-converted nested tables should use valid nested table separators and shallow nesting |
 | `ADW01/unknown-waiver-directive` | Waiver directive names should be known |
 | `ADW02/missing-waiver-rule-list` | Waiver directives should include a rule list |
 | `ADW03/malformed-waiver-rule-list` | Waiver rule lists should use comma-separated rule IDs |
@@ -168,26 +227,30 @@ rules. `ADW##` waiver diagnostics use tags for discovery, but remain always on.
 
 | Group | IDs |
 |---|---|
-| `blank_lines` | `AD008` |
+| `anchor` | `AD057` |
+| `blank_lines` | `AD008`, `AD009` |
 | `blocks` | `AD003`, `AD032`, `AD035` |
 | `accessibility` | `AD028`, `AD042` |
-| `cleanup` | `AD032`, `AD034`, `AD035`, `AD036`, `AD037`, `AD039`, `AD040`, `AD041` |
-| `conversion` | `AD029`, `AD030`, `AD031`, `AD036`, `AD037`, `AD039`, `AD040` |
+| `cleanup` | `AD032`, `AD034`, `AD035`, `AD036`, `AD037`, `AD039`, `AD040`, `AD041`, `AD055`, `AD058`, `AD059` |
+| `conversion` | `AD029`, `AD030`, `AD031`, `AD037`, `AD039`, `AD040`, `AD055`, `AD056`, `AD058`, `AD059` |
+| `docx` | `AD016`, `AD017`, `AD028`, `AD055`, `AD056`, `AD058`, `AD059` |
 | `dependencies` | `AD024`, `AD025`, `AD026`, `AD027` |
 | `diagram` | `AD012` |
 | `format` | `AD041` |
 | `headings` | `AD001`, `AD002`, `AD005`, `AD006`, `AD007`, `AD043`, `AD045` |
-| `image` | `AD011`, `AD013`, `AD016`, `AD025`, `AD028` |
+| `image` | `AD011`, `AD013`, `AD016`, `AD025`, `AD028`, `AD057` |
 | `include` | `AD006`, `AD019`, `AD022`, `AD024` |
 | `inline` | `AD041` |
-| `lists` | `AD008`, `AD036` |
+| `list` | `AD056` |
+| `lists` | `AD008`, `AD009`, `AD036` |
+| `pandoc` | `AD059` |
 | `parser` | `AD000` |
-| `table` | `AD004`, `AD010`, `AD017`, `AD030` |
+| `table` | `AD004`, `AD010`, `AD017`, `AD030`, `AD057`, `AD059` |
 | `waiver` | `ADW01`, `ADW02`, `ADW03`, `ADW04`, `ADW05`, `ADW06`, `ADW07`, `ADW08` |
 | `whitespace` | `AD034` |
 | `references` | `AD023` |
 | `links` | `AD027`, `AD031`, `AD042`, `AD044` |
-| `structure` | `AD043` |
+| `structure` | `AD009`, `AD019`, `AD020`, `AD022`, `AD023`, `AD043`, `AD046`, `AD047`, `AD048`, `AD049`, `AD050`, `AD051`, `AD052`, `AD053`, `AD054`, `AD056`, `AD057` |
 | `markdown-compatibility` | `AD045` |
 | `maintainability` | `AD045` |
 | `xref` | `AD026`, `AD042`, `AD044` |

package/dist/api/lint.js

@@ -23,6 +23,7 @@ async function lintFilesInternal(patterns, options, afterFix) {
         for (const parsedFile of document.files) {
             parsedFiles.set(path.resolve(parsedFile.file), parsedFile);
         }
+        mergeAsciidoctorSections(document, await collectParserSections(file));
         mergeAsciidoctorBlocks(document, await collectParserBlocks(file));
         mergeAsciidoctorReferenceTargets(document, await collectParserReferenceTargets(file));
         resolveDocumentXrefs(document);
@@ -69,24 +70,60 @@ async function collectParserBlocks(file) {
     const { collectAsciidoctorBlocks } = await import("../parsers/asciidoctor.js");
     return collectAsciidoctorBlocks(file);
 }
+async function collectParserSections(file) {
+    const { collectAsciidoctorSections } = await import("../parsers/asciidoctor.js");
+    return collectAsciidoctorSections(file);
+}
 async function collectParserReferenceTargets(file) {
     const { collectAsciidoctorReferenceTargets } = await import("../parsers/asciidoctor.js");
     return collectAsciidoctorReferenceTargets(file);
 }
+function mergeAsciidoctorSections(document, sections) {
+    if (!sections.length) {
+        return;
+    }
+    for (const section of sections) {
+        const existing = document.sections.find((candidate) => (path.resolve(candidate.range.start.file) === path.resolve(section.range.start.file)
+            && candidate.range.start.line === section.range.start.line
+            && candidate.title === section.title));
+        if (!existing) {
+            continue;
+        }
+        existing.sectname = section.sectname;
+        existing.source = "asciidoctor";
+        if (!existing.style && section.style) {
+            existing.style = section.style;
+        }
+    }
+}
 function mergeAsciidoctorBlocks(document, blocks) {
     if (!blocks.length) {
         return;
     }
-    const authoritativeTypes = new Set(blocks.map((block) => block.type));
+    const authoritativeTypes = new Set(blocks
+        .filter((block) => ["table", "image", "diagram"].includes(block.type))
+        .map((block) => block.type));
     const authoritativeFiles = new Set(blocks.map((block) => path.resolve(block.range.start.file)));
-    document.blocks = [
+    const merged = [
         ...document.blocks.filter((block) => (!authoritativeTypes.has(block.type)
             || !authoritativeFiles.has(path.resolve(block.range.start.file)))),
-        ...blocks,
-    ].sort((a, b) => (a.range.start.file.localeCompare(b.range.start.file)
+    ];
+    for (const block of blocks) {
+        if (!merged.some((candidate) => sameBlock(candidate, block))) {
+            merged.push(block);
+        }
+    }
+    document.blocks = merged.sort((a, b) => (a.range.start.file.localeCompare(b.range.start.file)
         || a.range.start.line - b.range.start.line
         || a.range.start.column - b.range.start.column));
 }
+function sameBlock(a, b) {
+    return path.resolve(a.range.start.file) === path.resolve(b.range.start.file)
+        && a.range.start.line === b.range.start.line
+        && a.range.start.column === b.range.start.column
+        && a.type === b.type
+        && a.style === b.style;
+}
 function mergeAsciidoctorReferenceTargets(document, targets) {
     const byKey = new Map();
     for (const target of document.referenceTargets) {

package/dist/api/rules.js

@@ -90,7 +90,7 @@ function configSources(options) {
         return sources;
     }
     const project = findProjectConfig(options.cwd);
-    if (project) {
+    if (project && !sources.some((source) => path.resolve(source.file) === path.resolve(project))) {
         sources.push({ kind: "project", file: project });
     }
     return sources;

package/dist/cli/index.js

@@ -38,13 +38,13 @@ program
     .command("install-skill")
     .description("install the bundled AI-agent skill")
     .option("--dest <directory>", "skills root directory")
-    .option("--agent <agent>", "target agent: codex, cursor, claude-code, or openclaw", "codex")
-    .option("--project", "install into the target agent's project skills directory")
+    .option("--agent <agent>", "deprecated; fails with guidance instead of selecting a skill root")
+    .option("--project", "install into project .agents and .claude skill roots")
     .option("--force", "replace an existing installed skill")
     .action((options) => {
     try {
         const result = installSkill(options);
-        console.log(`Installed asciidoclint skill to ${result.destination}`);
+        console.log(`Installed asciidoclint skill to ${result.destinations.join(", ")}`);
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
@@ -55,14 +55,14 @@ program
     .command("uninstall-skill")
     .description("uninstall the AI-agent skill")
     .option("--dest <directory>", "skills root directory")
-    .option("--agent <agent>", "target agent: codex, cursor, claude-code, or openclaw", "codex")
-    .option("--project", "uninstall from the target agent's project skills directory")
+    .option("--agent <agent>", "deprecated; fails with guidance instead of selecting a skill root")
+    .option("--project", "uninstall from project .agents and .claude skill roots")
     .action((options) => {
     try {
         const result = uninstallSkill(options);
         console.log(result.removed
-            ? `Uninstalled asciidoclint skill from ${result.destination}`
-            : `No asciidoclint skill installed at ${result.destination}`);
+            ? `Uninstalled asciidoclint skill from ${result.removedDestinations.join(", ")}`
+            : `No asciidoclint skill installed at ${result.destinations.join(", ")}`);
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));

package/dist/cli/install-skill.d.ts

@@ -3,19 +3,24 @@ export interface InstallSkillOptions {
     project?: boolean;
     agent?: SupportedSkillAgent;
     force?: boolean;
+    homeDir?: string;
 }
 export interface InstallSkillResult {
     source: string;
     destination: string;
+    destinations: string[];
 }
 export interface UninstallSkillOptions {
     dest?: string;
     project?: boolean;
     agent?: SupportedSkillAgent;
+    homeDir?: string;
 }
 export interface UninstallSkillResult {
     destination: string;
+    destinations: string[];
     removed: boolean;
+    removedDestinations: string[];
 }
 export type SupportedSkillAgent = "codex" | "cursor" | "claude-code" | "openclaw";
 export declare function installSkill(options?: InstallSkillOptions): InstallSkillResult;

package/dist/cli/install-skill.js

@@ -3,60 +3,149 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 const skillName = "asciidoclint";
-const defaultAgent = "codex";
-const skillAgentRoots = {
-    codex: {
-        project: path.join(".agents", "skills"),
-        global: path.join(os.homedir(), ".codex", "skills"),
-    },
-    cursor: {
-        project: path.join(".agents", "skills"),
-        global: path.join(os.homedir(), ".cursor", "skills"),
-    },
-    "claude-code": {
-        project: path.join(".claude", "skills"),
-        global: path.join(os.homedir(), ".claude", "skills"),
-    },
-    openclaw: {
-        project: "skills",
-        global: path.join(os.homedir(), ".openclaw", "skills"),
-    },
-};
+const deprecatedAgentMessage = "--agent is deprecated and no longer selects a skill root. Use the command without --agent for the default global roots, add --project for project roots, or use --dest <directory> for a custom root.";
 export function installSkill(options = {}) {
+    rejectDeprecatedAgentOption(options.agent);
     const source = findBundledSkill();
-    const root = resolveSkillsRoot(options);
-    const destination = path.join(root, skillName);
+    if (options.dest) {
+        const destination = path.join(path.resolve(options.dest), skillName);
+        installCopy(source, destination, options.force);
+        return { source, destination, destinations: [destination] };
+    }
+    if (options.project) {
+        const destinations = projectSkillDestinations(process.cwd());
+        prepareDestinations(destinations, options.force);
+        installPreparedDestinations(destinations, (destination) => writeSymlink(source, destination));
+        return { source, destination: destinations[0], destinations };
+    }
+    const { common, claude } = globalSkillDestinations(options.homeDir);
+    prepareDestinations([common, claude], options.force);
+    installPreparedDestinations([common, claude], (destination) => {
+        if (destination === common) {
+            writeCopy(source, common);
+            return;
+        }
+        writeSymlink(common, claude);
+    });
+    return { source, destination: common, destinations: [common, claude] };
+}
+export function uninstallSkill(options = {}) {
+    rejectDeprecatedAgentOption(options.agent);
+    const destinations = uninstallDestinations(options);
+    const removedDestinations = [];
+    for (const destination of destinations) {
+        if (pathExists(destination)) {
+            removePath(destination);
+            removedDestinations.push(destination);
+        }
+    }
+    return {
+        // For global uninstall, destinations are ordered for removal safety:
+        // Claude symlink first, then the common copy.
+        destination: destinations[0],
+        destinations,
+        removed: removedDestinations.length > 0,
+        removedDestinations,
+    };
+}
+function rejectDeprecatedAgentOption(agent) {
+    if (agent) {
+        throw new Error(deprecatedAgentMessage);
+    }
+}
+function uninstallDestinations(options) {
+    if (options.dest) {
+        return [path.join(path.resolve(options.dest), skillName)];
+    }
+    if (options.project) {
+        return projectSkillDestinations(process.cwd());
+    }
+    const { common, claude } = globalSkillDestinations(options.homeDir);
+    return [claude, common];
+}
+function projectSkillDestinations(root) {
+    return [
+        path.resolve(root, ".agents", "skills", skillName),
+        path.resolve(root, ".claude", "skills", skillName),
+    ];
+}
+function globalSkillDestinations(homeDir = os.homedir()) {
+    return {
+        common: path.join(homeDir, ".agents", "skills", skillName),
+        claude: path.join(homeDir, ".claude", "skills", skillName),
+    };
+}
+function installCopy(source, destination, force = false) {
     if (path.resolve(source) === path.resolve(destination)) {
-        return { source, destination };
+        return;
     }
-    if (fs.existsSync(destination)) {
-        if (!options.force) {
-            throw new Error(`${destination} already exists; pass --force to replace it`);
+    prepareDestination(destination, force);
+    writeCopy(source, destination);
+}
+function prepareDestinations(destinations, force = false) {
+    for (const destination of destinations) {
+        prepareDestination(destination, force);
+    }
+}
+function installPreparedDestinations(destinations, write) {
+    const written = [];
+    try {
+        for (const destination of destinations) {
+            write(destination);
+            written.push(destination);
         }
-        fs.rmSync(destination, { recursive: true, force: true });
     }
-    fs.mkdirSync(root, { recursive: true });
+    catch (error) {
+        rollbackWrittenDestinations(written);
+        throw error;
+    }
+}
+function rollbackWrittenDestinations(destinations) {
+    for (const destination of destinations.slice().reverse()) {
+        if (pathExists(destination)) {
+            removePath(destination);
+        }
+    }
+}
+function writeCopy(source, destination) {
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
     fs.cpSync(source, destination, { recursive: true });
-    return { source, destination };
 }
-export function uninstallSkill(options = {}) {
-    const destination = path.join(resolveSkillsRoot(options), skillName);
-    const removed = fs.existsSync(destination);
-    if (removed) {
-        fs.rmSync(destination, { recursive: true, force: true });
+function writeSymlink(source, destination) {
+    if (path.resolve(source) === path.resolve(destination)) {
+        return;
     }
-    return { destination, removed };
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.symlinkSync(path.relative(path.dirname(destination), source), destination, "dir");
 }
-function resolveSkillsRoot(options) {
-    if (options.dest) {
-        return path.resolve(options.dest);
+function prepareDestination(destination, force) {
+    if (!pathExists(destination)) {
+        return;
+    }
+    if (!force) {
+        throw new Error(`${destination} already exists; pass --force to replace it`);
+    }
+    removePath(destination);
+}
+function removePath(file) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) {
+        fs.unlinkSync(file);
+        return;
+    }
+    fs.rmSync(file, { recursive: true, force: true });
+}
+function pathExists(file) {
+    try {
+        fs.lstatSync(file);
+        return true;
     }
-    const agent = options.agent ?? defaultAgent;
-    const roots = skillAgentRoots[agent];
-    if (!roots) {
-        throw new Error(`Unsupported skill agent: ${agent}`);
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
     }
-    return options.project ? path.resolve(process.cwd(), roots.project) : roots.global;
 }
 function findBundledSkill() {
     let current = path.dirname(fileURLToPath(import.meta.url));

package/dist/parsers/asciidoctor.d.ts

@@ -1,4 +1,5 @@
-import type { BlockNode, LintFinding, ReferenceTarget } from "../types.js";
+import type { BlockNode, LintFinding, ReferenceTarget, SectionNode } from "../types.js";
 export declare function collectAsciidoctorDiagnostics(file: string): LintFinding[];
 export declare function collectAsciidoctorBlocks(file: string): BlockNode[];
+export declare function collectAsciidoctorSections(file: string): SectionNode[];
 export declare function collectAsciidoctorReferenceTargets(file: string): ReferenceTarget[];