nimbus-docs 0.1.4 → 0.1.6

package/dist/cli/index.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
+import { a as resolveRuleForCollection, i as parseSource, n as RULES, o as validateLintOptions, s as isRuleCode, t as IMPLEMENTED_CODES } from "../rules-DnAP-j89.js";
 import { spawn } from "node:child_process";
-import { dirname, join, relative } from "node:path";
+import fs, { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path, { dirname, join, relative } from "node:path";
 import mri from "mri";
 import * as p from "@clack/prompts";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { determineAgent } from "@vercel/detect-agent";
 
 //#region src/cli/_registry.generated.ts
@@ -209,6 +210,12 @@ const BUNDLED_INDEX = {
 			"title": "Component showcase",
 			"description": "Add a /components grid landing plus per-component showcase pages at /components/<slug>, driven by a dedicated content collection. For sites documenting their own UI library."
 		},
+		"lint-prose-textlint": {
+			"name": "lint-prose-textlint",
+			"type": "registry:feature",
+			"title": "Prose linting with textlint",
+			"description": "Add textlint with write-good, alex, and terminology rules — npm-native prose linting that runs alongside nimbus-docs lint."
+		},
 		"new-collection": {
 			"name": "new-collection",
 			"type": "registry:feature",
@@ -560,6 +567,579 @@ function printHumanInstructions(slug) {
 	stream.write(`  Run "${cmd} --print" and follow the instructions.\n`);
 }
 
+//#endregion
+//#region src/lint/disables.ts
+/**
+* Per-file and per-line disable directives — both designed so the disable
+* itself is greppable:
+*
+*   - Frontmatter `nimbusDisableRules: ["nimbus/internal-link"]` disables
+*     the listed codes for the whole file.
+*   - An inline `{/* nimbus-rule-disable-next-line nimbus/bare-url *​/}`
+*     comment disables the named code on the next non-blank line.
+*
+* Both require a rule code: an empty `nimbusDisableRules` array is a
+* reported error, so the reason for a disable is always visible.
+*/
+const INLINE_DISABLE = /\{\/\*\s*nimbus-rule-disable-next-line\s+(\S+)\s*\*\/\}/;
+function collectDisables(frontmatter, frontmatterRaw, frontmatterStartLine, lines) {
+	const fileDisabled = /* @__PURE__ */ new Set();
+	const lineDisabled = /* @__PURE__ */ new Map();
+	const problems = [];
+	if (frontmatter && "nimbusDisableRules" in frontmatter) {
+		const raw = frontmatter.nimbusDisableRules;
+		const at = locateFrontmatterKey(frontmatterRaw, "nimbusDisableRules", frontmatterStartLine);
+		if (!Array.isArray(raw)) problems.push({
+			message: "\"nimbusDisableRules\" must be an array of rule codes, e.g. [\"nimbus/internal-link\"].",
+			line: at.line,
+			column: at.column
+		});
+		else if (raw.length === 0) problems.push({
+			message: "\"nimbusDisableRules\" is empty — remove it, or name the rule code(s) you mean to disable so the reason stays greppable.",
+			line: at.line,
+			column: at.column
+		});
+		else for (const entry of raw) {
+			if (typeof entry !== "string") {
+				problems.push({
+					message: `"nimbusDisableRules" entry ${JSON.stringify(entry)} must be a string rule code.`,
+					line: at.line,
+					column: at.column
+				});
+				continue;
+			}
+			if (!isRuleCode(entry)) {
+				problems.push({
+					message: `"nimbusDisableRules" lists "${entry}", which is not a known rule code — typos here silently no-op, so we surface them.`,
+					line: at.line,
+					column: at.column
+				});
+				continue;
+			}
+			fileDisabled.add(entry);
+		}
+	}
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i].match(INLINE_DISABLE);
+		if (!match) continue;
+		const code = match[1];
+		if (!isRuleCode(code)) {
+			problems.push({
+				message: `inline disable references "${code}", which is not a known rule code — typos here silently no-op, so we surface them.`,
+				line: i + 1,
+				column: (match.index ?? 0) + 1
+			});
+			continue;
+		}
+		let target = -1;
+		for (let j = i + 1; j < lines.length; j++) if (lines[j].trim() !== "") {
+			target = j + 1;
+			break;
+		}
+		if (target === -1) continue;
+		const set = lineDisabled.get(target) ?? /* @__PURE__ */ new Set();
+		set.add(code);
+		lineDisabled.set(target, set);
+	}
+	return {
+		fileDisabled,
+		lineDisabled,
+		problems
+	};
+}
+/** Is a diagnostic for `code` on `line` suppressed by a disable directive? */
+function isDisabled(info, code, line) {
+	if (info.fileDisabled.has(code)) return true;
+	return info.lineDisabled.get(line)?.has(code) ?? false;
+}
+function locateFrontmatterKey(frontmatterRaw, key, startLine) {
+	if (frontmatterRaw) {
+		const rawLines = frontmatterRaw.split("\n");
+		for (let i = 0; i < rawLines.length; i++) {
+			const m = rawLines[i].match(new RegExp(`^(\\s*)${key}\\s*:`));
+			if (m) return {
+				line: startLine + i,
+				column: m[1].length + 1
+			};
+		}
+	}
+	return {
+		line: startLine,
+		column: 1
+	};
+}
+
+//#endregion
+//#region src/lint/fix.ts
+function applyFixes(source, diagnostics) {
+	const items = diagnostics.filter((d) => d.fix !== void 0 && d.fix.edits.length > 0).map((d) => {
+		const edits = d.fix.edits;
+		return {
+			diagnostic: d,
+			edits,
+			start: Math.min(...edits.map((e) => e.range[0])),
+			end: Math.max(...edits.map((e) => e.range[1]))
+		};
+	}).sort((a, b) => b.start - a.start);
+	let output = source;
+	let frontier = Number.POSITIVE_INFINITY;
+	const applied = /* @__PURE__ */ new Set();
+	for (const item of items) {
+		if (item.end > frontier) continue;
+		const ordered = [...item.edits].sort((a, b) => b.range[0] - a.range[0]);
+		for (const edit of ordered) output = output.slice(0, edit.range[0]) + edit.text + output.slice(edit.range[1]);
+		frontier = item.start;
+		applied.add(item.diagnostic);
+	}
+	return {
+		output,
+		fixed: applied.size,
+		applied
+	};
+}
+
+//#endregion
+//#region src/lint/engine.ts
+/**
+* The lint engine. Runs the registered rules over parsed files, resolves
+* each rule's severity from config, applies per-file and per-line disables,
+* and collects everything into the one `Diagnostic` envelope.
+*
+* Pure and synchronous: `lintFile` takes a `ParsedFile` and returns
+* `Diagnostic[]`, which is what the test harness drives directly. The
+* disk-walking entry points (`lintPaths`) sit on top.
+*/
+/** Lint one already-parsed file. */
+function lintFile(file, opts = {}) {
+	const forceEnable = opts.only !== void 0 && opts.rules?.[opts.only] === void 0;
+	const rules = forceEnable ? {
+		...opts.rules ?? {},
+		[opts.only]: "error"
+	} : opts.rules ?? {};
+	const collections = forceEnable ? stripCodeFromCollections(opts.collections ?? {}, opts.only) : opts.collections ?? {};
+	const out = [];
+	if (file.parseError) return [{
+		code: "nimbus/mdx-syntax",
+		severity: "error",
+		source: "docs-compiler",
+		file: file.path,
+		message: `MDX failed to parse: ${file.parseError.message}`,
+		line: file.parseError.line,
+		column: file.parseError.column
+	}];
+	const disables = collectDisables(file.frontmatter, file.frontmatterRaw, file.frontmatterStartLine, file.lines);
+	for (const problem of disables.problems) out.push({
+		code: "nimbus/frontmatter-shape",
+		severity: "error",
+		source: "docs-compiler",
+		file: file.path,
+		message: problem.message,
+		line: problem.line,
+		column: problem.column
+	});
+	for (const rule of RULES) {
+		if (opts.only && rule.code !== opts.only) continue;
+		const resolved = resolveRuleForCollection(rule.code, rules, collections, file.collection);
+		if (resolved.severity === "off") continue;
+		const severity = resolved.severity;
+		const reports = [];
+		try {
+			rule.run({
+				file,
+				options: resolved.options,
+				site: opts.site,
+				report: (report) => reports.push(report)
+			});
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`nimbus-docs: rule \`${rule.code}\` threw on ${file.path}: ${detail}\n`);
+			continue;
+		}
+		for (const report of reports) {
+			if (isDisabled(disables, rule.code, report.line)) continue;
+			out.push({
+				code: rule.code,
+				severity,
+				source: "docs-compiler",
+				file: file.path,
+				message: report.message,
+				line: report.line,
+				column: report.column,
+				endLine: report.endLine,
+				endColumn: report.endColumn,
+				fix: report.fix
+			});
+		}
+	}
+	out.sort((a, b) => a.line - b.line || a.column - b.column || a.code.localeCompare(b.code));
+	return out;
+}
+/** Lint a set of absolute file paths, reading + parsing each one. */
+function lintPaths(absPaths, projectRoot, opts = {}) {
+	const out = [];
+	for (const abs of absPaths) {
+		if (opts.signal?.aborted) break;
+		const rel = path.relative(projectRoot, abs);
+		try {
+			const parsed = parseSource(fs.readFileSync(abs, "utf8"), {
+				path: rel,
+				absPath: abs,
+				collection: inferCollection(rel)
+			});
+			out.push(...lintFile(parsed, opts));
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`nimbus-docs: skipped ${rel}: ${detail}\n`);
+		}
+	}
+	return out;
+}
+/**
+* Hard cap on per-file fix passes — a runaway rule that keeps emitting
+* convergence-breaking fixes won't hang the CLI. 10 is well above any
+* realistic chain (the longest in practice is 2–3: a fix unmasks a
+* second-tier finding the first pass shadowed).
+*/
+const MAX_FIX_PASSES = 10;
+/**
+* Lint + apply auto-fixes in place. Each file is read, linted, fixed, and
+* (when content changed) atomically rewritten via tmp-file + rename — so a
+* crash or SIGINT mid-write can't truncate the user's content. We iterate
+* each file until the output stabilizes or `MAX_FIX_PASSES` is hit; this
+* picks up diagnostics that were skipped on pass 1 due to overlap with
+* another applied fix, plus diagnostics a fix on pass 1 unmasked.
+*
+* A diagnostic stays in the report when it wasn't *actually* applied —
+* which includes the advisory-only case (a rule emits a `fix` with no
+* `edits`, like the did-you-mean hint on `internal-link`) and the
+* skipped-overlap case after the convergence cap. Both are real,
+* unresolved issues; suppressing them just because the diagnostic carries
+* a `fix` field would silently hide broken links and other
+* un-auto-fixable problems.
+*
+* Files that fail to read, parse, or write are skipped with a stderr
+* message and the run continues — one bad file shouldn't leave the rest
+* of the working tree half-fixed.
+*/
+function fixPaths(absPaths, projectRoot, opts = {}) {
+	let fixed = 0;
+	let filesChanged = 0;
+	const remaining = [];
+	for (const abs of absPaths) {
+		if (opts.signal?.aborted) break;
+		const rel = path.relative(projectRoot, abs);
+		try {
+			const original = fs.readFileSync(abs, "utf8");
+			let current = original;
+			let lastDiagnostics = [];
+			let lastApplied = /* @__PURE__ */ new Set();
+			for (let pass = 0; pass < MAX_FIX_PASSES; pass++) {
+				const diagnostics = lintFile(parseSource(current, {
+					path: rel,
+					absPath: abs,
+					collection: inferCollection(rel)
+				}), opts);
+				const result = applyFixes(current, diagnostics);
+				fixed += result.fixed;
+				lastDiagnostics = diagnostics;
+				lastApplied = result.applied;
+				if (result.output === current) break;
+				current = result.output;
+			}
+			if (current !== original) {
+				writeFileAtomicSync(abs, current);
+				filesChanged++;
+			}
+			for (const d of lastDiagnostics) if (!lastApplied.has(d)) remaining.push(d);
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`nimbus-docs: skipped ${rel}: ${detail}\n`);
+		}
+	}
+	return {
+		diagnostics: remaining,
+		fixed,
+		filesChanged
+	};
+}
+/**
+* Write atomically: serialize to a sibling tmp file, fsync, rename over the
+* target. A crash mid-write leaves the original intact instead of a
+* truncated .mdx. The tmp file lives next to the target so the rename is
+* a same-filesystem atomic op.
+*/
+function writeFileAtomicSync(abs, content) {
+	const tmp = `${abs}.nimbus-tmp-${process.pid}`;
+	const fd = fs.openSync(tmp, "w");
+	try {
+		fs.writeFileSync(fd, content, "utf8");
+		fs.fsyncSync(fd);
+	} finally {
+		fs.closeSync(fd);
+	}
+	try {
+		fs.renameSync(tmp, abs);
+	} catch (err) {
+		try {
+			fs.unlinkSync(tmp);
+		} catch {}
+		throw err;
+	}
+}
+function summarize(diagnostics, files) {
+	let errors = 0;
+	let warnings = 0;
+	for (const d of diagnostics) if (d.severity === "error") errors++;
+	else warnings++;
+	return {
+		errors,
+		warnings,
+		total: diagnostics.length,
+		files
+	};
+}
+/** Infer the collection name from a `src/content/<name>/…` path. */
+function inferCollection(relPath) {
+	const match = relPath.replace(/\\/g, "/").match(/(?:^|\/)src\/content\/([^/]+)\//);
+	return match ? match[1] : null;
+}
+/**
+* Return a new collections config with `code` removed from every per-
+* collection `rules` block. Used by `lintFile`'s `--rule` force-enable so
+* a per-collection "off" doesn't silently shadow the CLI flag — the
+* user explicitly asked to see this rule's findings.
+*/
+function stripCodeFromCollections(collections, code) {
+	const out = {};
+	for (const [name, cfg] of Object.entries(collections)) {
+		if (!cfg.rules || !(code in cfg.rules)) {
+			out[name] = cfg;
+			continue;
+		}
+		const { [code]: _stripped, ...remaining } = cfg.rules;
+		out[name] = {
+			...cfg,
+			rules: remaining
+		};
+	}
+	return out;
+}
+
+//#endregion
+//#region src/lint/discover.ts
+/**
+* File discovery for the CLI — walk the configured content directories for
+* `.mdx` files, skipping `node_modules` and dotfolders. Mirrors the walk
+* the MDX validator already uses, kept here so the lint CLI doesn't depend
+* on integration internals.
+*/
+function findMdxFiles(dirs) {
+	const out = [];
+	for (const dir of dirs) walk(dir, out);
+	out.sort();
+	return out;
+}
+function walk(dir, out) {
+	let entries;
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch (err) {
+		if (err.code === "ENOENT") return;
+		throw err;
+	}
+	for (const entry of entries) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+			walk(full, out);
+		} else if (entry.isFile() && entry.name.endsWith(".mdx")) out.push(full);
+	}
+}
+
+//#endregion
+//#region src/lint/format.ts
+const COLORS = {
+	reset: "\x1B[0m",
+	dim: "\x1B[2m",
+	red: "\x1B[31m",
+	yellow: "\x1B[33m",
+	green: "\x1B[32m",
+	bold: "\x1B[1m"
+};
+function formatPretty(diagnostics, summary, opts) {
+	const paint = (code, text) => opts.color ? `${code}${text}${COLORS.reset}` : text;
+	const shown = opts.quiet ? diagnostics.filter((d) => d.severity === "error") : diagnostics;
+	const lines = [];
+	for (const d of shown) {
+		const sev = d.severity === "error" ? paint(COLORS.red, "error") : paint(COLORS.yellow, "warn");
+		const loc = paint(COLORS.dim, `${d.file}:${d.line}:${d.column}`);
+		lines.push(`${loc}  ${sev}  ${paint(COLORS.dim, d.code)}`);
+		lines.push(`  ${d.message}`);
+		if (d.fix && d.fix.description) lines.push(`  ${paint(COLORS.dim, `fix: ${d.fix.description}`)}`);
+	}
+	if (summary.total === 0) return paint(COLORS.green, `✓ ${summary.files} file(s) lint clean.`);
+	const tally = `${summary.errors} error(s), ${summary.warnings} warning(s) across ${summary.files} file(s)`;
+	lines.push("");
+	lines.push(summary.errors > 0 ? paint(COLORS.red, `✗ ${tally}`) : paint(COLORS.yellow, `${tally}`));
+	return lines.join("\n");
+}
+function formatJson(diagnostics, summary) {
+	return JSON.stringify({
+		version: 1,
+		summary: {
+			errors: summary.errors,
+			warnings: summary.warnings,
+			total: summary.total,
+			files: summary.files
+		},
+		diagnostics
+	}, null, 2);
+}
+
+//#endregion
+//#region src/cli/lint.ts
+/**
+* `nimbus-docs lint` — the authoring-quality verdict for MDX content.
+*
+* Walks the content directories, runs the registered rules, prints
+* diagnostics, and exits non-zero when any `error`-severity finding
+* survives. The build is never gated by this command — drafts that fail
+* lint still render under `astro dev`.
+*
+* Severity overrides live with the integration
+* (`nimbus(config, { rules })`), which materializes them to
+* `.nimbus/lint.json` at build/dev time; this command reads that file when
+* present and otherwise runs every authoring rule at its default. In-file
+* disables (`nimbusDisableRules`, inline comments) work with no config.
+*/
+async function lintCommand(flags) {
+	const cwd = process.cwd();
+	const contentDir = path.join(cwd, "src", "content");
+	if (flags.rule) {
+		if (!isRuleCode(flags.rule)) {
+			process.stderr.write(`Unknown rule code: \`${flags.rule}\`. See https://nimbus-docs.com/lint for the rule list.\n`);
+			process.exit(1);
+		}
+		if (!IMPLEMENTED_CODES.has(flags.rule)) {
+			process.stderr.write(`Rule \`${flags.rule}\` is not implemented by \`nimbus-docs lint\`. Build validators run inside \`astro build\`, not here; planned rules haven't shipped yet. Implemented authoring rules: ${[...IMPLEMENTED_CODES].sort().join(", ")}.\n`);
+			process.exit(1);
+		}
+	}
+	const files = findMdxFiles([contentDir]);
+	if (files.length === 0) {
+		process.stderr.write(`No .mdx files found under ${path.relative(cwd, contentDir) || "."}. Run from your project root.
+`);
+		process.exit(0);
+	}
+	const { rules, collections, site } = loadMaterializedConfig(cwd);
+	const opts = {
+		rules,
+		collections,
+		site,
+		only: flags.rule
+	};
+	let diagnostics;
+	let interrupted = false;
+	if (flags.fix) {
+		const ac = new AbortController();
+		const onSigint = () => {
+			if (interrupted) {
+				process.stderr.write("\nnimbus-docs: forced exit.\n");
+				process.exit(130);
+			}
+			interrupted = true;
+			process.stderr.write("\nnimbus-docs: interrupted — finishing current file, then stopping. Press Ctrl-C again to force.\n");
+			ac.abort();
+		};
+		process.on("SIGINT", onSigint);
+		try {
+			const result = fixPaths(files, cwd, {
+				...opts,
+				signal: ac.signal
+			});
+			if (result.fixed > 0) process.stderr.write(`Fixed ${result.fixed} issue(s) across ${result.filesChanged} file(s).\n`);
+			if (interrupted) process.stderr.write(`nimbus-docs: stopped early — ${result.filesChanged} file(s) changed before interrupt.\n`);
+			diagnostics = result.diagnostics.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column);
+		} finally {
+			process.off("SIGINT", onSigint);
+		}
+	} else diagnostics = lintPaths(files, cwd, opts);
+	const summary = summarize(diagnostics, files.length);
+	if (flags.format === "json") process.stdout.write(formatJson(diagnostics, summary) + "\n");
+	else process.stdout.write(formatPretty(diagnostics, summary, {
+		color: shouldUseColor(flags.color),
+		quiet: flags.quiet
+	}) + "\n");
+	if (interrupted) process.exit(130);
+	process.exit(summary.errors > 0 ? 1 : 0);
+}
+/**
+* Resolve whether to emit ANSI escapes, in standard CLI precedence:
+*   1. Explicit `--color` / `--no-color` flag.
+*   2. `FORCE_COLOR` env (Node ecosystem convention) — any non-empty,
+*      non-zero value forces color on.
+*   3. `NO_COLOR` env (no-color.org) — any non-empty value forces color off.
+*   4. Auto-detect via `process.stdout.isTTY`.
+*/
+function shouldUseColor(explicit) {
+	if (explicit !== void 0) return explicit;
+	const force = process.env.FORCE_COLOR;
+	if (force !== void 0 && force !== "" && force !== "0") return true;
+	if (process.env.NO_COLOR !== void 0 && process.env.NO_COLOR !== "") return false;
+	return process.stdout.isTTY === true;
+}
+/**
+* Read the integration's materialized lint config from `.nimbus/lint.json`.
+* Returns empty defaults when the file is absent or unreadable (lint must
+* work before the first build).
+*
+* **Re-validates the parsed config** against `validateLintOptions`, the
+* same validator the integration ran at config-setup time. The materialized
+* file is normally machine-written, so failures here typically mean a
+* hand-edit or a stale schema. The CLI surfaces the validation error and
+* exits — silently ignoring a typo'd rule code in `lint.json` contradicts
+* the anti-silent-typo invariant the rest of the codebase enforces.
+*/
+function loadMaterializedConfig(cwd) {
+	const file = path.join(cwd, ".nimbus", "lint.json");
+	let raw;
+	try {
+		raw = fs.readFileSync(file, "utf8");
+	} catch {
+		return {
+			rules: {},
+			collections: {}
+		};
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		const detail = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`nimbus-docs: ${path.relative(cwd, file) || file} is not valid JSON — ${detail}. Delete the file (it'll be regenerated by \`astro build\`) or fix the syntax.
+`);
+		process.exit(1);
+	}
+	let validated;
+	try {
+		validated = validateLintOptions({
+			rules: parsed.rules,
+			collections: parsed.collections
+		}, IMPLEMENTED_CODES);
+	} catch (err) {
+		const detail = err instanceof Error ? err.message : String(err);
+		process.stderr.write(`${detail}\n\nThis shape lives in ${path.relative(cwd, file) || file} — usually machine-written by the Nimbus integration at \`astro build\`. If you've hand-edited it, fix or delete the file. Otherwise, re-run \`astro build\` to regenerate it.
+`);
+		process.exit(1);
+	}
+	const site = typeof parsed.site === "string" ? parsed.site : void 0;
+	return {
+		rules: validated.rules,
+		collections: validated.collections,
+		site
+	};
+}
+
 //#endregion
 //#region src/cli/index.ts
 /**
@@ -591,20 +1171,25 @@ const HELP = `
     list [--type ui|lib|feature]   List available registry items
     add                            Same as \`list\`
     add <slug>                     Install a component or hand off a feature
+    lint                           Lint .mdx content for authoring-quality issues
 
   Flags:
     --yes, -y                      Component: overwrite conflicts without prompting
     --print                        Feature: print markdown to stdout (skip agent detect)
     --type <ui|lib|feature>        \`list\`: filter by type
+    --format <json>                \`lint\`: machine-readable output
+    --rule <nimbus/...>            \`lint\`: run a single rule
+    --fix                          \`lint\`: apply auto-fixes in place
+    --quiet                        \`lint\`: errors only, suppress warnings
     --help, -h
     --version, -v
 
   Examples:
     nimbus-docs add dialog                              # component: resolve + install
-    nimbus-docs add 404-page                            # feature: detect agent or print
-                                                   #   pipe instructions for humans
     nimbus-docs add 404-page --print | claude           # explicit pipe to claude
-    nimbus-docs add 404-page --print | codex            # …or any other agent
+    nimbus-docs lint                                    # pretty output, exit non-zero on error
+    nimbus-docs lint --format=json                      # agent-readable diagnostics
+    nimbus-docs lint --rule=nimbus/single-h1            # one rule
 `;
 async function main() {
 	const args = mri(process.argv.slice(2), {
@@ -612,9 +1197,17 @@ async function main() {
 			"yes",
 			"print",
 			"help",
-			"version"
+			"version",
+			"quiet",
+			"color",
+			"fix"
 		],
-		string: ["type"],
+		string: [
+			"type",
+			"format",
+			"rule"
+		],
+		default: { color: void 0 },
 		alias: {
 			y: "yes",
 			h: "help",
@@ -626,10 +1219,20 @@ async function main() {
 		return;
 	}
 	if (args.version) {
-		process.stdout.write(`0.1.4\n`);
+		process.stdout.write(`0.1.6\n`);
 		return;
 	}
 	const [command, slug] = args._;
+	if (command === "lint") {
+		await lintCommand({
+			format: args.format,
+			quiet: args.quiet,
+			rule: args.rule,
+			color: args.color,
+			fix: args.fix
+		});
+		return;
+	}
 	if (command === "list" || command === "add" && !slug || !command) {
 		listCommand(args.type);
 		return;