asciidoclint 0.5.0 → 1.0.0

package/README.md

@@ -1,45 +1,32 @@
 <p align="center">
   <img src="assets/logo.svg" width="160" height="160" alt="asciidoclint logo">
 </p>
-<p align="center">
-  <sub><code>assets/logo.svg</code> and <code>assets/icon.svg</code> were created with <a href="https://inkscape.org/">Inkscape</a>. The <strong>lint</strong> label uses <a href="https://www.jetbrains.com/lp/mono/">JetBrains Mono</a> (SIL Open Font License).</sub>
-</p>
 
 # asciidoclint
 
 `asciidoclint` is an AsciiDoc syntax, structure, and document-policy linter for
 CLI, AI-agent, and editor workflows.
 
-`asciidoclint` began as an in-house implementation and has been open-sourced
-under the MIT License since June 1, 2026.
-
-Design goals:
-
-- Provide a library-first, typed, plugin-friendly rule model.
-- Use Asciidoctor-backed diagnostics, source mapping, include awareness, and a
-  safe/unsafe fix model.
-- Keep generic AsciiDoc syntax/structure rules separate from project or
-  organization policy rules.
-
-Start with the architecture proposal:
+## Install the npm package
 
-- [Architecture](docs/architecture.md)
+```bash
+npm install --save-dev asciidoclint
+```
 
-## Install the npm package
+## Use the CLI
 
-Install in a project:
+Run lint:
 
 ```bash
-npm install --save-dev asciidoclint
+npx asciidoclint index.adoc
+npx asciidoclint --format json index.adoc
 ```
 
-Run the CLI:
+Apply deterministic fixes:
 
 ```bash
-npx asciidoclint docs/**/*.adoc
-npx asciidoclint --format json docs/**/*.adoc
-npx asciidoclint --fix docs/**/*.adoc
-npx asciidoclint --fix --unsafe docs/**/*.adoc
+npx asciidoclint --fix index.adoc
+npx asciidoclint --fix --unsafe index.adoc
 ```
 
 Inspect rules:
@@ -48,122 +35,80 @@ Inspect rules:
 npx asciidoclint --list-rules
 npx asciidoclint --explain AD001
 npx asciidoclint --explain heading-level-progression
+npx asciidoclint --explain AD001 --format json
 ```
 
-Load organization-specific conformance or style rules as custom rules:
+Use a project config file when the same lint settings should be reused:
 
 ```yaml
+# .asciidoclint/config.yaml
 extends:
   - asciidoclint:recommended
+```
 
-ignores:
-  - build/**
+Use a global config file for settings that should apply across projects:
 
+```yaml
+# ~/.asciidoclint/config.yaml
 customRules:
-  - ./lint-rules/ORG001-no-todo.js
-  - ./lint-rules/ORG002-section-policy.js
+  - "@example/asciidoclint-rules"
 ```
 
-Scaffold a custom rule without modifying `asciidoclint` source:
-
-```bash
-npx asciidoclint init-rule --pack my-org --id ORG001 --alias no-todo
-```
+See [docs/configuration.md](docs/configuration.md) for configuration fields and
+merge order. See [docs/waiver.md](docs/waiver.md) for source waiver syntax and
+reporting.
 
 ## Install the AI skill
 
-The repository ships an `asciidoclint` skill under `skills/asciidoclint`. The
-skill lets AI agents trigger lint, summarize results, apply safe fixes, apply
-explicit unsafe fixes, and use reported `fixHelper` guidance for focused
-AI-assisted repairs.
-
-Install the skill directly from GitHub with the open skills CLI:
+The repository ships an `asciidoclint` skill for AI agents. Install it from the
+npm package:
 
 ```bash
-npx skills add f33lgood/asciidoclint --skill asciidoclint -a codex -g
+npx asciidoclint install-skill
 ```
 
-The repository hides repo-maintenance skills from normal discovery, so the
-shorter form installs the public `asciidoclint` skill too:
+Or install it directly from GitHub with the open skills CLI:
 
 ```bash
-npx skills add f33lgood/asciidoclint
+npx skills add f33lgood/asciidoclint --skill asciidoclint -a codex -g
 ```
 
-If you already installed the npm package and want the matching bundled skill
-version, install it through the `asciidoclint` CLI:
+Remove the installed skill when you want to use `asciidoclint` without AI skill
+assistance:
 
 ```bash
-npx asciidoclint install-skill
+npx asciidoclint uninstall-skill
 ```
 
-Useful installer options:
+The public skill exposes these user-facing workflows:
 
-```bash
-npx asciidoclint install-skill --project
-npx asciidoclint install-skill --dest ./tmp/skills --force
-```
+| Workflow | Purpose |
+|---|---|
+| `lint-summary` | Run lint and summarize findings by severity, rule, file, waiver status, and fixability. |
+| `agentic-fix` | Use lint guidance and local source context to repair findings that deterministic fixes cannot safely handle. |
+| `waivers` | Add narrow source waivers and verify waiver syntax. |
+| `rule-create` | Create project-local or shared custom rules. |
+| `rule-review` | Review rule behavior, overlap, documentation, and tests. |
+| `feedback` | Prepare a sanitized, paste-ready GitHub issue message. |
 
-## VS Code and Cursor extension
+## VS Code / Open VSX-Compatible Extension
 
-`asciidoclint` is also available as a VS Code/Cursor extension. The extension
-shows lint issues as source-file diagnostics in the editor and Problems panel,
-including diagnostics mapped back to included source files.
+`asciidoclint` is also available as a VS Code / Open VSX-compatible extension.
+Editors compatible with VS Code's diagnostic model can use it to show lint
+issues in the editor and Problems panel, including diagnostics mapped back to
+included source files.
 
 The extension can import CLI diagnostics written by:
 
 ```bash
 npx asciidoclint --format json \
   --output-diagnostics .asciidoclint/diagnostics.json \
-  docs/index.adoc
+  index.adoc
 ```
 
 See [packages/vscode-asciidoclint](packages/vscode-asciidoclint/README.md) for
 extension commands and settings.
 
-## Use this repository
-
-Install dependencies:
-
-```bash
-npm install
-```
-
-Run the check loop:
-
-```bash
-npm run check
-```
-
-Run coverage only:
-
-```bash
-npm run test:coverage
-```
-
-Coverage thresholds and the latest metrics are documented in
-[docs/reports/report-coverage.md](docs/reports/report-coverage.md).
-
-Run the CLI from source:
-
-```bash
-npx tsx src/cli/index.ts test/fixtures/api/structural_errors.adoc
-npx tsx src/cli/index.ts --format json test/fixtures/api/structural_errors.adoc
-npx tsx src/cli/index.ts --fix test/fixtures/api/structure_only.adoc
-npx tsx src/cli/index.ts install-skill --dest ./tmp/skills --force
-```
-
-Build and package the VS Code/Cursor extension:
-
-```bash
-npm run build:extension
-npm test -w vscode-asciidoclint
-npm run package -w vscode-asciidoclint
-```
-
-Install the generated `.vsix` in Cursor with **Extensions: Install from VSIX**,
-then run **asciidoclint: Lint Current File** or **asciidoclint: Lint Workspace**.
-
 ## Built-in Rules
 
 | ID / Alias | Short description |
@@ -207,13 +152,19 @@ then run **asciidoclint: Lint Current File** or **asciidoclint: Lint Workspace**
 | `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 |
-
-Detailed per-rule docs live under `docs/rules/`; `--explain` exposes the same
-metadata programmatically.
+| `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 |
+| `ADW04/unknown-waiver-rule-id` | Waiver rule IDs should be defined rules |
+| `ADW05/unpaired-waiver-enable-block` | Waiver enable-block directives should have a preceding disable-block |
+| `ADW06/unpaired-waiver-disable-block` | Waiver disable-block directives should have a following enable-block |
+| `ADW07/mismatched-waiver-block-rule-list` | Waiver block delimiters should use matching rule lists |
+| `ADW08/waiver-targets-waiver-rule` | Source waivers should not target ADW waiver diagnostics |
 
 ## Tags
 
-Tags group related rules and can be used to enable or disable classes of rules.
+Tags group related rules and can be used to enable or disable classes of normal
+rules. `ADW##` waiver diagnostics use tags for discovery, but remain always on.
 
 | Group | IDs |
 |---|---|
@@ -232,6 +183,7 @@ Tags group related rules and can be used to enable or disable classes of rules.
 | `lists` | `AD008`, `AD036` |
 | `parser` | `AD000` |
 | `table` | `AD004`, `AD010`, `AD017`, `AD030` |
+| `waiver` | `ADW01`, `ADW02`, `ADW03`, `ADW04`, `ADW05`, `ADW06`, `ADW07`, `ADW08` |
 | `whitespace` | `AD034` |
 | `references` | `AD023` |
 | `links` | `AD027`, `AD031`, `AD042`, `AD044` |
@@ -240,19 +192,16 @@ Tags group related rules and can be used to enable or disable classes of rules.
 | `maintainability` | `AD045` |
 | `xref` | `AD026`, `AD042`, `AD044` |
 
-## Rule ID Namespaces
-
-Built-in rule IDs use one reserved namespace:
-
-- `AD###` - all built-in `asciidoclint` rules.
+## Documentation
 
-Rule responsibility is expressed through tags such as `headings`,
-`dependencies`, `policy`, and `cleanup`, not through multiple built-in ID
-prefixes. This keeps built-in IDs predictable as the rule set grows.
-
-Company, product, or template-specific rules should not be built-ins. Use a
-three-letter custom prefix such as `ORG`, `ABC`, or a team-owned namespace. The
-registry rejects duplicate IDs and aliases across built-in and custom rules.
+Start with the architecture proposal:
 
-The rule-by-rule rendering and severity rationale is in
-[docs/rules/rule-necessity.md](docs/rules/rule-necessity.md).
+- [Architecture](docs/architecture.md)
+- [Configuration](docs/configuration.md)
+- [Rule architecture](docs/rule-architecture.md)
+- [Waivers](docs/waiver.md)
+- [Custom rules](docs/custom-rules.md)
+
+Detailed per-rule docs live under [docs/rules](docs/rules/). The CLI exposes
+the rule catalog through `--list-rules`, readable rule help through `--explain`,
+and structured rule metadata through `--explain <rule> --format json`.

package/dist/api/fixes.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 export function applyFixes(findings, unsafeFixes) {
     const allowed = unsafeFixes ? ["safe", "unsafe"] : ["safe"];
     const edits = findings.flatMap((finding) => {
-        if (!finding.fix || !allowed.includes(finding.fix.applicability)) {
+        if (finding.waived || !finding.fix || !allowed.includes(finding.fix.applicability)) {
             return [];
         }
         return finding.fix.edits;

package/dist/api/lint.js

@@ -6,6 +6,7 @@ import { helpers } from "../rules/helpers.js";
 import { getVersion } from "../version.js";
 import { applyFixes } from "./fixes.js";
 import { loadRules } from "./rules.js";
+import { applyWaivers } from "./waivers.js";
 export async function lintFiles(patterns, options = {}) {
     return lintFilesInternal(patterns, options, false);
 }
@@ -14,9 +15,14 @@ async function lintFilesInternal(patterns, options, afterFix) {
     const { config, rules } = await loadRules(options);
     const files = await expandFiles(patterns, cwd, config);
     const enabledRules = filterEnabledRules(rules, config);
+    const knownRuleIds = new Set(["AD000", ...rules.map((rule) => rule.id)]);
     const findings = [];
+    const parsedFiles = new Map();
     for (const file of files) {
         const document = parseDocument(file);
+        for (const parsedFile of document.files) {
+            parsedFiles.set(path.resolve(parsedFile.file), parsedFile);
+        }
         mergeAsciidoctorBlocks(document, await collectParserBlocks(file));
         mergeAsciidoctorReferenceTargets(document, await collectParserReferenceTargets(file));
         resolveDocumentXrefs(document);
@@ -45,7 +51,7 @@ async function lintFilesInternal(patterns, options, afterFix) {
             });
         }
     }
-    const result = { files, findings: sortFindings(findings) };
+    const result = { files, findings: sortFindings(applyWaivers(findings, [...parsedFiles.values()], knownRuleIds)) };
     if (options.fix && !afterFix) {
         applyFixes(result.findings, options.unsafeFixes ?? false);
         return lintFilesInternal(patterns, { ...options, fix: false }, true);

package/dist/api/rules.d.ts

@@ -5,29 +5,37 @@ export interface Config {
     customRules?: string[];
     ignores?: string[];
     rules?: Record<string, RuleSetting>;
-    editor?: EditorConfig;
-    baseDir?: string;
 }
 export type RuleSetting = boolean | {
     severity?: "error" | "warning" | "info";
     enabled?: boolean;
 };
-export interface EditorConfig {
-    defaultScope?: "file" | "document" | "workspace";
-    lintOnSave?: boolean;
-    followSymlinks?: boolean;
-    importCliDiagnostics?: boolean;
-}
 export interface RuleLoadOptions {
     configFile?: string;
     customRules?: string[];
     cwd?: string;
+    homeDir?: string;
+    noGlobalConfig?: boolean;
+}
+export interface ConfigSource {
+    kind: "global" | "project" | "explicit";
+    file: string;
+}
+export interface ConfigLoadOptions {
+    configFile?: string;
+    cwd?: string;
+    homeDir?: string;
+    noGlobalConfig?: boolean;
 }
 export declare function loadRules(options?: RuleLoadOptions): Promise<{
     config: Config;
     rules: Rule[];
 }>;
 export declare function ruleMetadata(rule: Rule): object;
-export declare function loadConfig(configFile: string | undefined, cwd: string): Config;
+export declare function loadConfig(configFile: string | undefined, cwd: string, options?: ConfigLoadOptions): Config;
+export declare function loadConfigDetails(options?: ConfigLoadOptions): {
+    config: Config;
+    sources: ConfigSource[];
+};
 export declare function loadCustomRules(references: string[], cwd: string): Promise<Rule[]>;
 export declare function normalizeConfig(config: Config | undefined): Config;

package/dist/api/rules.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import yaml from "js-yaml";
@@ -6,9 +7,9 @@ import { builtInRules } from "../rules/builtin.js";
 import { validateRules } from "../rules/registry.js";
 export async function loadRules(options = {}) {
     const cwd = path.resolve(options.cwd ?? process.cwd());
-    const config = loadConfig(options.configFile, cwd);
+    const config = loadConfig(options.configFile, cwd, options);
     const customRules = [
-        ...await loadCustomRules(config.customRules ?? [], config.baseDir ?? cwd),
+        ...await loadCustomRules(config.customRules ?? [], cwd),
         ...await loadCustomRules(options.customRules ?? [], cwd),
     ];
     const rules = [...builtInRules, ...customRules];
@@ -26,18 +27,19 @@ export function ruleMetadata(rule) {
         docs: rule.docs,
     };
 }
-export function loadConfig(configFile, cwd) {
-    const candidates = configFile ? [configFile] : [".asciidoclint.yaml", ".asciidoclint.yml"];
-    for (const candidate of candidates) {
-        const absolute = path.resolve(cwd, candidate);
-        if (fs.existsSync(absolute)) {
-            return {
-                ...normalizeConfig(yaml.load(fs.readFileSync(absolute, "utf8"))),
-                baseDir: path.dirname(absolute),
-            };
-        }
-    }
-    return {};
+export function loadConfig(configFile, cwd, options = {}) {
+    return loadConfigDetails({ ...options, configFile, cwd }).config;
+}
+export function loadConfigDetails(options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const sources = configSources({
+        configFile: options.configFile,
+        cwd,
+        homeDir: options.homeDir,
+        noGlobalConfig: options.noGlobalConfig,
+    });
+    const config = sources.reduce((base, source) => (mergeConfig(base, configFromFile(source.file))), {});
+    return { config, sources };
 }
 export async function loadCustomRules(references, cwd) {
     const rules = [];
@@ -63,20 +65,71 @@ export function normalizeConfig(config) {
 function mergeConfig(base, override) {
     return {
         extends: override.extends ?? base.extends,
-        baseDir: override.baseDir ?? base.baseDir,
         documents: [...(base.documents ?? []), ...(override.documents ?? [])],
         customRules: [...(base.customRules ?? []), ...(override.customRules ?? [])],
         ignores: [...(base.ignores ?? []), ...(override.ignores ?? [])],
-        editor: {
-            ...(base.editor ?? {}),
-            ...(override.editor ?? {}),
-        },
         rules: {
             ...(base.rules ?? {}),
             ...(override.rules ?? {}),
         },
     };
 }
+function configSources(options) {
+    const sources = [];
+    if (!options.noGlobalConfig) {
+        const global = path.join(path.resolve(options.homeDir ?? os.homedir()), ".asciidoclint", "config.yaml");
+        if (fs.existsSync(global)) {
+            sources.push({ kind: "global", file: global });
+        }
+    }
+    if (options.configFile) {
+        const explicit = path.resolve(options.cwd, options.configFile);
+        if (fs.existsSync(explicit)) {
+            sources.push({ kind: "explicit", file: explicit });
+        }
+        return sources;
+    }
+    const project = findProjectConfig(options.cwd);
+    if (project) {
+        sources.push({ kind: "project", file: project });
+    }
+    return sources;
+}
+function findProjectConfig(cwd) {
+    let directory = path.resolve(cwd);
+    while (true) {
+        const candidate = path.join(directory, ".asciidoclint", "config.yaml");
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            return undefined;
+        }
+        directory = parent;
+    }
+}
+function configFromFile(file) {
+    const baseDir = configReferenceBaseDir(file);
+    const loaded = normalizeConfig(yaml.load(fs.readFileSync(file, "utf8")));
+    return {
+        ...loaded,
+        customRules: loaded.customRules?.map((reference) => resolveConfigReference(reference, baseDir)),
+    };
+}
+function configReferenceBaseDir(file) {
+    const directory = path.dirname(file);
+    if (path.basename(file) === "config.yaml" && path.basename(directory) === ".asciidoclint") {
+        return path.dirname(directory);
+    }
+    return directory;
+}
+function resolveConfigReference(reference, baseDir) {
+    if (reference.startsWith(".") || reference.startsWith("/")) {
+        return path.resolve(baseDir, reference);
+    }
+    return reference;
+}
 function presetConfig(name) {
     const rules = {};
     const enableByTag = (tag) => {
@@ -102,10 +155,51 @@ function presetConfig(name) {
     }
 }
 function resolveImport(reference, cwd) {
-    if (reference.startsWith(".") || reference.startsWith("/") || /\.(ts|mts|cts|m?js|cjs)$/.test(reference)) {
-        return pathToFileURL(path.resolve(cwd, reference)).href;
+    if (!isLocalReference(reference)) {
+        return reference;
     }
-    return reference;
+    const absolute = path.resolve(cwd, reference);
+    if (fs.existsSync(absolute) && fs.statSync(absolute).isDirectory()) {
+        return pathToFileURL(resolveRulePackageEntry(absolute)).href;
+    }
+    return pathToFileURL(absolute).href;
+}
+function isLocalReference(reference) {
+    return reference.startsWith(".") || reference.startsWith("/") || /\.(ts|mts|cts|m?js|cjs)$/.test(reference);
+}
+function resolveRulePackageEntry(directory) {
+    const packageJson = path.join(directory, "package.json");
+    const packageEntry = fs.existsSync(packageJson) ? packageEntryFromJson(packageJson) : undefined;
+    const candidates = [
+        packageEntry && path.resolve(directory, packageEntry),
+        path.join(directory, "dist", "index.js"),
+        path.join(directory, "dist", "index.mjs"),
+        path.join(directory, "src", "index.js"),
+        path.join(directory, "src", "index.mjs"),
+        path.join(directory, "src", "index.ts"),
+        path.join(directory, "src", "index.mts"),
+        path.join(directory, "index.js"),
+        path.join(directory, "index.mjs"),
+        path.join(directory, "index.ts"),
+    ].filter((candidate) => Boolean(candidate));
+    const entry = candidates.find((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile());
+    if (!entry) {
+        throw new Error(`Custom rule package has no loadable entry: ${directory}`);
+    }
+    return entry;
+}
+function packageEntryFromJson(file) {
+    const packageJson = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (typeof packageJson.exports === "string") {
+        return packageJson.exports;
+    }
+    if (packageJson.exports && typeof packageJson.exports["."] === "string") {
+        return packageJson.exports["."];
+    }
+    if (packageJson.exports && typeof packageJson.exports["."] === "object") {
+        return packageJson.exports["."].import ?? packageJson.exports["."].default;
+    }
+    return packageJson.module ?? packageJson.main;
 }
 function asArray(value) {
     if (!value) {

package/dist/api/waivers.d.ts

@@ -0,0 +1,2 @@
+import type { LintFinding, ParsedFile } from "../types.js";
+export declare function applyWaivers(findings: LintFinding[], files: ParsedFile[], knownRuleIds: Set<string>): LintFinding[];