asciidoclint 0.5.0

package/dist/types.d.ts

@@ -0,0 +1,166 @@
+export type Severity = "error" | "warning" | "info";
+export type ParserKind = "text" | "document" | "dependency" | "project";
+export type Fixability = "safe" | "unsafe" | "no";
+export type FixApplicability = Exclude<Fixability, "no">;
+export interface SourcePosition {
+    file: string;
+    line: number;
+    column: number;
+}
+export interface SourceRange {
+    start: SourcePosition;
+    end?: SourcePosition;
+}
+export interface TextEdit {
+    file: string;
+    range: SourceRange;
+    replacement: string;
+}
+export interface Fix {
+    applicability: FixApplicability;
+    edits: TextEdit[];
+}
+export interface LintFinding {
+    ruleId: string;
+    alias?: string;
+    severity: Severity;
+    message: string;
+    range: SourceRange;
+    detail?: string;
+    context?: string;
+    fixHelper?: string;
+    fix?: Fix;
+}
+export interface RuleExample {
+    title?: string;
+    code: string;
+}
+export interface RuleDocs {
+    summary: string;
+    url?: URL;
+    rationale?: string;
+    badExamples?: RuleExample[];
+    goodExamples?: RuleExample[];
+    fixability?: Fixability;
+    /** Default repair guidance for all findings from this rule. */
+    fixHelper?: string;
+}
+export interface Rule {
+    id: string;
+    alias?: string;
+    description: string;
+    tags: string[];
+    docs?: RuleDocs;
+    parser: ParserKind;
+    configSchema?: unknown;
+    asynchronous?: boolean;
+    function: (params: RuleParams, onError: ReportFinding) => void | Promise<void>;
+}
+export type ReportFinding = (finding: Omit<LintFinding, "ruleId" | "alias"> & Partial<Pick<LintFinding, "ruleId" | "alias">>) => void;
+export interface RuleParams {
+    file: string;
+    lines: string[];
+    document: NormalizedDocument;
+    dependencies: DependencyGraph;
+    parserDiagnostics: LintFinding[];
+    config: unknown;
+    version: string;
+    helpers: RuleHelpers;
+}
+export interface NormalizedDocument {
+    file: string;
+    lines: string[];
+    attributes: Record<string, string>;
+    sections: SectionNode[];
+    blocks: BlockNode[];
+    referenceTargets: ReferenceTarget[];
+    includes: IncludeRecord[];
+    dependencies: DependencyGraph;
+    diagnostics: LintFinding[];
+    sourceMap: SourceMapRecord[];
+    conditionals: ConditionalRecord[];
+    files: ParsedFile[];
+}
+export interface ReferenceTarget {
+    id: string;
+    file: string;
+    aliases?: string[];
+    source?: "asciidoctor" | "tolerant";
+}
+export interface ParsedFile {
+    file: string;
+    lines: string[];
+}
+export interface SectionNode {
+    kind: "section";
+    title: string;
+    level: number;
+    range: SourceRange;
+    titleRange: SourceRange;
+    parent?: SectionNode;
+    children: SectionNode[];
+    blocks: BlockNode[];
+}
+export interface BlockNode {
+    kind: "block";
+    type: BlockType;
+    style?: string;
+    title?: string;
+    attributes: Record<string, string | boolean>;
+    table?: TableInfo;
+    range: SourceRange;
+    contentRange?: SourceRange;
+    parentSection?: SectionNode;
+}
+export interface TableInfo {
+    columnCount?: number;
+    renderedCellCount?: number;
+    renderedCellSourceLines?: number[];
+}
+export type BlockType = "paragraph" | "listing" | "literal" | "source" | "example" | "sidebar" | "quote" | "table" | "image" | "admonition" | "passthrough" | "stem" | "diagram" | "comment" | "unknown";
+export interface IncludeRecord {
+    target: string;
+    resolvedTarget?: string;
+    range: SourceRange;
+    status: "resolved" | "missing" | "skipped";
+    attributes: Record<string, string | boolean>;
+}
+export interface DependencyRecord {
+    type: "include" | "image" | "xref" | "attachment";
+    target: string;
+    resolvedTarget?: string;
+    range: SourceRange;
+    status: "resolved" | "missing" | "skipped";
+}
+export interface DependencyGraph {
+    records: DependencyRecord[];
+}
+export interface SourceMapRecord {
+    expandedLine: number;
+    source: SourcePosition;
+}
+export interface ConditionalRecord {
+    directive: "ifdef" | "ifndef";
+    attribute: string;
+    active: boolean;
+    range: SourceRange;
+}
+export interface RuleHelpers {
+    findSections: (document: NormalizedDocument) => SectionNode[];
+    findBlocks: (document: NormalizedDocument, type?: BlockType) => BlockNode[];
+    isSourceLikeBlock: (block: BlockNode) => boolean;
+}
+export interface LintOptions {
+    configFile?: string;
+    format?: "pretty" | "json";
+    customRules?: string[];
+    cwd?: string;
+    fix?: boolean;
+    unsafeFixes?: boolean;
+    parserDiagnostics?: boolean;
+    outputDiagnosticsFile?: string;
+}
+export interface LintResult {
+    files: string[];
+    findings: LintFinding[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.5.0";
+export declare function getVersion(): string;

package/dist/version.js

@@ -0,0 +1,4 @@
+export const VERSION = "0.5.0";
+export function getVersion() {
+    return VERSION;
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "asciidoclint",
+  "version": "0.5.0",
+  "description": "AsciiDoc syntax, structure, and document-policy linter",
+  "author": "Shawn Hu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/f33lgood/asciidoclint.git"
+  },
+  "bugs": {
+    "url": "https://github.com/f33lgood/asciidoclint/issues"
+  },
+  "homepage": "https://github.com/f33lgood/asciidoclint#readme",
+  "type": "module",
+  "files": [
+    "assets",
+    "dist",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js",
+    "!dist/compare",
+    "skills"
+  ],
+  "workspaces": [
+    "packages/*"
+  ],
+  "bin": {
+    "asciidoclint": "dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "version:sync": "tsx scripts/sync-version.ts",
+    "version:check": "tsx scripts/sync-version.ts --check",
+    "build": "tsc -p tsconfig.json",
+    "build:extension": "npm run build && npm run build -w ./packages/vscode-asciidoclint",
+    "test": "vitest run src/api/*.test.ts src/cli/*.test.ts src/formatters/*.test.ts src/rules/*.test.ts",
+    "test:extension": "npm test -w ./packages/vscode-asciidoclint",
+    "test:coverage": "vitest run --coverage",
+    "lint:fixtures": "tsx src/cli/index.ts --format json \"test/fixtures/**/*.adoc\"",
+    "check": "npm run version:check && npm run build && npm test && npm run test:coverage && npm run build:extension && npm run test:extension",
+    "release:npm:dry-run": "npm run version:check && npm run build && npm pack --dry-run",
+    "release:npm:publish": "npm run version:check && npm run build && npm publish --access public",
+    "release:npm:publish:provenance": "npm run version:check && npm run build && npm publish --access public --provenance",
+    "release:vscode:package": "npm run version:check && npm run build:extension && npm run package -w ./packages/vscode-asciidoclint",
+    "release:vscode:publish": "npm run version:check && npm run build:extension && npm run publish:marketplace -w ./packages/vscode-asciidoclint",
+    "release:open-vsx:publish": "npm run release:vscode:package && npm run publish:open-vsx -w ./packages/vscode-asciidoclint"
+  },
+  "dependencies": {
+    "asciidoctor": "^3.0.4",
+    "commander": "^14.0.0",
+    "fast-glob": "^3.3.3",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.4"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/asciidoclint/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: asciidoclint
+description: Use when linting, summarizing, or fixing AsciiDoc files with asciidoclint, including safe fixes, explicit unsafe fixes, diagnostics artifacts, and AI-assisted repairs based on asciidoclint findings.
+---
+
+# asciidoclint
+
+Use this skill for AsciiDoc linting and repair workflows. Prefer the workspace
+`asciidoclint` install when present so project configuration and custom rules
+match CI.
+
+## Tool Resolution
+
+Use this order:
+
+1. `./node_modules/.bin/asciidoclint`
+2. `npx asciidoclint`
+3. `npx -y asciidoclint@latest`
+
+Run from the repository or document workspace root unless the user names a
+specific directory.
+
+## Check
+
+For lint-only requests, run:
+
+```bash
+npx asciidoclint --format json <targets>
+```
+
+If no targets are provided, use the current workspace's AsciiDoc files or the
+tool default. Summarize findings by severity, rule, file, and fixability. Report
+safe and unsafe fix availability separately.
+
+## Safe Fixes
+
+For safe-fix requests, run:
+
+```bash
+npx asciidoclint --fix --format json <targets>
+```
+
+Then rerun without `--fix` and summarize remaining findings. Safe fixes are
+deterministic edits emitted by rules.
+
+## Unsafe Fixes
+
+Only run unsafe fixes when the user explicitly asks for unsafe fixes:
+
+```bash
+npx asciidoclint --fix --unsafe --format json <targets>
+```
+
+Then rerun lint and summarize remaining findings. Unsafe fixes may alter
+rendered structure, link semantics, or author intent.
+
+## Editor Diagnostics Artifact
+
+When the user wants CLI results visible in VS Code or Cursor, write the
+diagnostics artifact:
+
+```bash
+npx asciidoclint --format json \
+  --output-diagnostics .asciidoclint/diagnostics.json \
+  <targets>
+```
+
+The asciidoclint extension can import this artifact into editor diagnostics.
+
+## AI-Assisted Repairs
+
+When the user asks for intelligent, AI, or LLM repair:
+
+1. Run lint with JSON output.
+2. Group findings by source file.
+3. Read only affected ranges plus nearby context.
+4. Use each finding's `ruleId`, `alias`, `message`, `detail`, `context`, and
+   `fixHelper` as the repair instruction.
+5. Apply focused edits.
+6. Rerun asciidoclint.
+7. Report fixed and remaining findings.
+
+Do not invent broad prose/style rewrites unless the finding requires them. Keep
+repairs scoped to the reported AsciiDoc issue.

package/skills/asciidoclint/references/ai-fix-policy.md

@@ -0,0 +1,11 @@
+# AI Repair Policy
+
+Prefer deterministic fixes first:
+
+1. Safe automatic fixes.
+2. Explicit unsafe automatic fixes only when requested.
+3. AI-assisted edits for remaining findings.
+
+For AI-assisted edits, treat `fixHelper` as the primary instruction. Preserve
+document meaning unless the rule explicitly requires a semantic change. Rerun
+`asciidoclint` after edits and report remaining findings.

package/skills/asciidoclint/references/result-schema.md

@@ -0,0 +1,22 @@
+# asciidoclint Result Schema
+
+Use `--format json` for machine-readable output.
+
+Top-level fields:
+
+- `files`: absolute file paths linted by the engine.
+- `findings`: ordered lint findings.
+
+Finding fields:
+
+- `ruleId`: stable rule ID such as `AD001`.
+- `alias`: optional readable rule alias.
+- `severity`: `error`, `warning`, or `info`.
+- `message`: concise diagnostic message.
+- `detail`: optional additional detail.
+- `context`: optional source context.
+- `fixHelper`: optional repair instruction for humans or AI agents.
+- `range.start.file`, `range.start.line`, `range.start.column`: source
+  location.
+- `fix.applicability`: `safe` or `unsafe` when an automatic edit exists.
+- `fix.edits`: text edits emitted by deterministic rules.