asciidoclint 0.5.0

package/dist/cli/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { lintFiles } from "../api/lint.js";
+import { loadRules, ruleMetadata } from "../api/rules.js";
+import { formatJson } from "../formatters/json.js";
+import { formatPretty } from "../formatters/pretty.js";
+import { resolveRuleReference, validateRules } from "../rules/registry.js";
+import { getVersion } from "../version.js";
+import { initRule } from "./init-rule.js";
+import { installSkill } from "./install-skill.js";
+const program = new Command();
+program
+    .name("asciidoclint")
+    .description("Lint AsciiDoc syntax, structure, dependencies, and policy")
+    .version(getVersion());
+program
+    .command("init-rule")
+    .description("scaffold a custom rule")
+    .requiredOption("--pack <name>", "rule pack name")
+    .requiredOption("--id <id>", "stable rule id")
+    .requiredOption("--alias <alias>", "readable rule alias")
+    .option("--directory <dir>", "rule directory", "lint-rules")
+    .action((options) => {
+    const files = initRule(options);
+    for (const file of files) {
+        console.log(file);
+    }
+});
+program
+    .command("install-skill")
+    .description("install the bundled Codex skill")
+    .option("--dest <directory>", "skills root directory")
+    .option("--project", "install into .codex/skills in the current project")
+    .option("--force", "replace an existing installed skill")
+    .action((options) => {
+    try {
+        const result = installSkill(options);
+        console.log(`Installed asciidoclint skill to ${result.destination}`);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 2;
+    }
+});
+program
+    .argument("[files...]", "AsciiDoc files or glob patterns")
+    .option("-f, --format <format>", "output format: pretty or json", "pretty")
+    .option("-c, --config <file>", "configuration file")
+    .option("--fix", "apply safe fixes")
+    .option("--unsafe", "also apply unsafe fixes with --fix")
+    .option("--output-diagnostics <file>", "write JSON diagnostics artifact for editor import")
+    .option("--list-rules", "list configured built-in and custom rules")
+    .option("--explain <rule>", "explain a configured rule by id or alias")
+    .option("--validate-rules", "validate configured rule registry")
+    .action(async (files, options) => {
+    const { rules } = await loadRules({ configFile: options.config });
+    if (options.validateRules) {
+        validateRules(rules);
+        console.log("Rule registry is valid");
+        return;
+    }
+    if (options.listRules) {
+        console.log(JSON.stringify(rules.map(ruleMetadata), null, 2));
+        return;
+    }
+    if (options.explain) {
+        const rule = resolveRuleReference(rules, options.explain);
+        if (!rule) {
+            console.error(`Unknown rule: ${options.explain}`);
+            process.exitCode = 2;
+            return;
+        }
+        console.log(JSON.stringify(ruleMetadata(rule), null, 2));
+        return;
+    }
+    const result = await lintFiles(files, {
+        configFile: options.config,
+        format: options.format,
+        fix: options.fix,
+        unsafeFixes: options.unsafe,
+        outputDiagnosticsFile: options.outputDiagnostics,
+    });
+    console.log(options.format === "json" ? formatJson(result) : formatPretty(result));
+    process.exitCode = result.findings.some((finding) => finding.severity === "error") ? 1 : 0;
+});
+await program.parseAsync();

package/dist/cli/init-rule.d.ts

@@ -0,0 +1,7 @@
+export interface InitRuleOptions {
+    pack: string;
+    id: string;
+    alias: string;
+    directory?: string;
+}
+export declare function initRule(options: InitRuleOptions): string[];

package/dist/cli/init-rule.js

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+export function initRule(options) {
+    const directory = path.resolve(options.directory ?? "lint-rules");
+    const basename = `${options.id}-${options.alias}`;
+    const rulePath = path.join(directory, `${basename}.ts`);
+    const testPath = path.join(directory, `${basename}.test.ts`);
+    const fixtureDirectory = path.join(directory, "fixtures", basename);
+    const badFixture = path.join(fixtureDirectory, "bad.adoc");
+    const goodFixture = path.join(fixtureDirectory, "good.adoc");
+    fs.mkdirSync(fixtureDirectory, { recursive: true });
+    writeNew(rulePath, ruleTemplate(options));
+    writeNew(testPath, testTemplate(options));
+    writeNew(badFixture, "This line has TODO work.\n");
+    writeNew(goodFixture, "This line links to issue PROJ-123.\n");
+    return [rulePath, testPath, badFixture, goodFixture];
+}
+function writeNew(file, content) {
+    if (fs.existsSync(file)) {
+        throw new Error(`Refusing to overwrite existing file: ${file}`);
+    }
+    fs.writeFileSync(file, content);
+}
+function ruleTemplate(options) {
+    return `import type { Rule } from "asciidoclint";
+
+export default {
+  id: "${options.id}",
+  alias: "${options.alias}",
+  description: "Describe what this rule checks",
+  tags: ["${options.pack}"],
+  docs: {
+    summary: "Explain the rule in one sentence.",
+    rationale: "Explain why the problematic structure should be avoided.",
+    badExamples: [{ code: "Problematic AsciiDoc example" }],
+    goodExamples: [{ code: "Expected AsciiDoc example" }],
+  },
+  parser: "text",
+  function: (params, onError) => {
+    params.lines.forEach((line, index) => {
+      const column = line.indexOf("TODO");
+      if (column !== -1) {
+        onError({
+          severity: "warning",
+          message: "Replace this placeholder rule logic",
+          range: {
+            start: {
+              file: params.file,
+              line: index + 1,
+              column: column + 1,
+            },
+          },
+        });
+      }
+    });
+  },
+} satisfies Rule;
+`;
+}
+function testTemplate(options) {
+    const basename = `${options.id}-${options.alias}`;
+    return `import { describe, expect, it } from "vitest";
+import rule from "./${basename}.js";
+
+describe("${options.id}/${options.alias}", () => {
+  it("has complete metadata", () => {
+    expect(rule.id).toBe("${options.id}");
+    expect(rule.alias).toBe("${options.alias}");
+    expect(rule.docs?.badExamples?.length).toBeGreaterThan(0);
+    expect(rule.docs?.goodExamples?.length).toBeGreaterThan(0);
+  });
+});
+`;
+}

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

@@ -0,0 +1,10 @@
+export interface InstallSkillOptions {
+    dest?: string;
+    project?: boolean;
+    force?: boolean;
+}
+export interface InstallSkillResult {
+    source: string;
+    destination: string;
+}
+export declare function installSkill(options?: InstallSkillOptions): InstallSkillResult;

package/dist/cli/install-skill.js

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const skillName = "asciidoclint";
+export function installSkill(options = {}) {
+    const source = findBundledSkill();
+    const root = options.dest
+        ? path.resolve(options.dest)
+        : options.project
+            ? path.resolve(process.cwd(), ".codex", "skills")
+            : path.join(process.env.CODEX_HOME ?? path.join(os.homedir(), ".codex"), "skills");
+    const destination = path.join(root, skillName);
+    if (fs.existsSync(destination)) {
+        if (!options.force) {
+            throw new Error(`${destination} already exists; pass --force to replace it`);
+        }
+        fs.rmSync(destination, { recursive: true, force: true });
+    }
+    fs.mkdirSync(root, { recursive: true });
+    fs.cpSync(source, destination, { recursive: true });
+    return { source, destination };
+}
+function findBundledSkill() {
+    let current = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = path.join(current, "skills", skillName);
+        if (fs.existsSync(path.join(candidate, "SKILL.md"))) {
+            return candidate;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new Error(`Could not find bundled ${skillName} skill`);
+        }
+        current = parent;
+    }
+}

package/dist/formatters/json.d.ts

@@ -0,0 +1,2 @@
+import type { LintResult } from "../types.js";
+export declare function formatJson(result: LintResult): string;

package/dist/formatters/json.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+export function formatJson(result) {
+    return JSON.stringify({
+        files: result.files.map((file) => path.relative(process.cwd(), file)),
+        findings: result.findings.map((finding) => ({
+            ...finding,
+            range: {
+                ...finding.range,
+                start: {
+                    ...finding.range.start,
+                    file: path.relative(process.cwd(), finding.range.start.file),
+                },
+                end: finding.range.end
+                    ? {
+                        ...finding.range.end,
+                        file: path.relative(process.cwd(), finding.range.end.file),
+                    }
+                    : undefined,
+            },
+        })),
+        summary: summarize(result),
+    }, null, 2);
+}
+function summarize(result) {
+    return result.findings.reduce((summary, finding) => {
+        summary.total += 1;
+        summary[finding.severity] += 1;
+        return summary;
+    }, { total: 0, error: 0, warning: 0, info: 0 });
+}

package/dist/formatters/pretty.d.ts

@@ -0,0 +1,2 @@
+import type { LintResult } from "../types.js";
+export declare function formatPretty(result: LintResult): string;

package/dist/formatters/pretty.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+import { ruleLabel } from "../rules/builtin.js";
+export function formatPretty(result) {
+    if (result.findings.length === 0) {
+        return "0 findings";
+    }
+    const lines = [];
+    for (const finding of result.findings) {
+        lines.push(primaryLine(finding));
+        if (finding.context) {
+            lines.push(`  ${finding.context}`);
+        }
+        if (finding.fixHelper) {
+            lines.push(`  fix helper: ${finding.fixHelper}`);
+        }
+        lines.push("");
+    }
+    const summary = result.findings.reduce((counts, finding) => {
+        counts.total += 1;
+        counts[finding.severity] += 1;
+        if (finding.fix?.applicability === "safe") {
+            counts.safe += 1;
+        }
+        if (finding.fix?.applicability === "unsafe") {
+            counts.unsafe += 1;
+        }
+        return counts;
+    }, { total: 0, error: 0, warning: 0, info: 0, safe: 0, unsafe: 0 });
+    lines.push(`${summary.total} findings: ${summary.error} errors, ${summary.warning} warnings, ${summary.info} info`);
+    if (summary.safe) {
+        lines.push(`${summary.safe} safe fixes available; run with --fix to apply them`);
+    }
+    if (summary.unsafe) {
+        lines.push(`${summary.unsafe} unsafe fixes available; run with --fix --unsafe to apply them`);
+    }
+    return lines.join("\n");
+}
+function primaryLine(finding) {
+    const file = path.relative(process.cwd(), finding.range.start.file);
+    return `${file}:${finding.range.start.line}:${finding.range.start.column} ${ruleLabel(finding)} ${finding.severity} ${finding.message}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { lintFiles } from "./api/lint.js";
+export { loadRules, ruleMetadata } from "./api/rules.js";
+export { builtInRules } from "./rules/builtin.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { lintFiles } from "./api/lint.js";
+export { loadRules, ruleMetadata } from "./api/rules.js";
+export { builtInRules } from "./rules/builtin.js";

package/dist/parsers/asciidoctor.d.ts

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