docsanity 0.1.0

package/dist/cli.cjs

@@ -0,0 +1,831 @@
+#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var cac = require('cac');
+var pc = require('picocolors');
+var readlevel = require('@didrod2539/readlevel');
+var linklint = require('@didrod2539/linklint');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var pc__default = /*#__PURE__*/_interopDefault(pc);
+
+// package.json
+var package_default = {
+  name: "docsanity",
+  version: "0.1.0",
+  description: "One command for docs-site health: broken links & dead anchors, orphan pages, SEO frontmatter (with site-wide duplicate title/description detection), readability grade, and Markdown structure/alt checks \u2014 unified into one score and report. Local, deterministic, no API key.",
+  type: "module",
+  main: "./dist/index.js",
+  module: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js",
+      require: "./dist/index.cjs"
+    }
+  },
+  bin: {
+    docsanity: "./dist/cli.js"
+  },
+  files: [
+    "dist"
+  ],
+  engines: {
+    node: ">=18"
+  },
+  scripts: {
+    build: "tsup",
+    test: "vitest run",
+    "test:watch": "vitest",
+    typecheck: "tsc --noEmit",
+    lint: "tsc --noEmit",
+    example: "node dist/cli.js scan examples/docs",
+    prepublishOnly: "npm run build"
+  },
+  keywords: [
+    "docs",
+    "documentation",
+    "docs-site",
+    "markdown",
+    "mdx",
+    "docusaurus",
+    "astro",
+    "nextra",
+    "broken-links",
+    "orphan-pages",
+    "frontmatter",
+    "seo",
+    "readability",
+    "link-checker",
+    "docs-linter",
+    "static-site",
+    "cli"
+  ],
+  author: "didrod205 (https://github.com/didrod205)",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/didrod205/docsanity.git"
+  },
+  bugs: {
+    url: "https://github.com/didrod205/docsanity/issues"
+  },
+  homepage: "https://github.com/didrod205/docsanity#readme",
+  dependencies: {
+    "@didrod2539/linklint": "^0.1.0",
+    "@didrod2539/readlevel": "^0.2.0",
+    cac: "^6.7.14",
+    picocolors: "^1.1.1"
+  },
+  devDependencies: {
+    "@types/node": "^22.10.0",
+    tsup: "^8.3.5",
+    typescript: "^5.7.2",
+    vitest: "^2.1.8"
+  }
+};
+function readabilityCheck(page, config) {
+  const text = page.md.text;
+  const wordCount = text ? text.split(/\s+/).filter(Boolean).length : 0;
+  if (wordCount < config.minWordsForReadability) {
+    return { findings: [] };
+  }
+  const a = readlevel.analyze(text);
+  const summary = {
+    grade: a.grade,
+    gradeLabel: a.gradeLabel,
+    ease: a.ease,
+    words: a.words,
+    readingTimeSeconds: a.readingTimeSeconds
+  };
+  const findings = [];
+  if (a.grade > config.maxGrade) {
+    findings.push({
+      dimension: "readability",
+      rule: "readability.too-hard",
+      severity: "warning",
+      message: `Reads at grade ${a.grade.toFixed(0)} (${a.gradeLabel}); target \u2264 grade ${config.maxGrade}`,
+      detail: `Flesch ease ${a.readability.fleschReadingEase.toFixed(0)} (${a.ease}), ${a.averageWordsPerSentence.toFixed(0)} words/sentence`,
+      fix: "Shorten sentences and prefer common words to lower the reading grade."
+    });
+  }
+  return { findings, summary };
+}
+
+// src/frontmatter.ts
+function unquote(raw) {
+  const s = raw.trim();
+  if (s.startsWith('"') && s.endsWith('"') && s.length >= 2 || s.startsWith("'") && s.endsWith("'") && s.length >= 2) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+function coerce(raw) {
+  const s = raw.trim();
+  if (s.startsWith("[") && s.endsWith("]")) {
+    return s.slice(1, -1).split(",").map((x) => unquote(x)).filter((x) => x.length > 0);
+  }
+  if (s === "true" || s === "false") return s === "true";
+  if (s !== "" && !Number.isNaN(Number(s)) && /^-?\d/.test(s)) return Number(s);
+  return unquote(s);
+}
+function parseFrontmatter(content) {
+  const normalized = content.replace(/^/, "");
+  const match = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(normalized);
+  if (!match) {
+    return { data: {}, body: content, offset: 0, present: false };
+  }
+  const block = match[1];
+  const data = {};
+  const lines = block.split(/\r?\n/);
+  let pendingListKey = null;
+  let pendingList = [];
+  const flush = () => {
+    if (pendingListKey !== null) {
+      data[pendingListKey] = pendingList;
+      pendingListKey = null;
+      pendingList = [];
+    }
+  };
+  for (const line of lines) {
+    if (/^\s*-\s+/.test(line) && pendingListKey !== null) {
+      pendingList.push(unquote(line.replace(/^\s*-\s+/, "")));
+      continue;
+    }
+    flush();
+    const kv = /^([A-Za-z0-9_.-]+):\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    const key = kv[1];
+    const value = kv[2];
+    if (value.trim() === "") {
+      pendingListKey = key;
+      pendingList = [];
+    } else {
+      data[key] = coerce(value);
+    }
+  }
+  flush();
+  const offset = match[0].split(/\r?\n/).length - 1;
+  return { data, body: normalized.slice(match[0].length), offset, present: true };
+}
+function asString(value) {
+  if (value === void 0) return "";
+  if (Array.isArray(value)) return value.join(", ");
+  return String(value).trim();
+}
+
+// src/checks/seo.ts
+function pageTitle(page) {
+  const fm = asString(page.frontmatter.data["title"]);
+  if (fm) return { value: fm, source: "frontmatter" };
+  const h1 = page.md.headings.find((h) => h.level === 1);
+  if (h1) return { value: h1.text, source: "h1" };
+  return { value: "", source: null };
+}
+function description(page) {
+  return asString(page.frontmatter.data["description"]);
+}
+function buildDuplicateIndex(pages) {
+  const titles = /* @__PURE__ */ new Map();
+  const descriptions = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    const t = pageTitle(page).value.trim().toLowerCase();
+    if (t) titles.set(t, [...titles.get(t) ?? [], page.relPath]);
+    const d = description(page).trim().toLowerCase();
+    if (d) descriptions.set(d, [...descriptions.get(d) ?? [], page.relPath]);
+  }
+  return { titles, descriptions };
+}
+function seoChecks(page, config, dup) {
+  const out = [];
+  const required = new Set(config.requireFrontmatter);
+  const title = pageTitle(page);
+  const desc = description(page);
+  if (required.has("title")) {
+    if (!title.value) {
+      out.push({
+        dimension: "seo",
+        rule: "seo.missing-title",
+        severity: "error",
+        message: "Page has no title (no frontmatter `title` and no H1)",
+        fix: "Add a `title:` to the frontmatter or an `# H1` heading."
+      });
+    } else if (title.source === "h1") {
+      out.push({
+        dimension: "seo",
+        rule: "seo.frontmatter-title",
+        severity: "info",
+        message: "Title comes from the H1; add an explicit frontmatter `title` for SEO control",
+        detail: `Using H1: "${title.value}"`
+      });
+    }
+    if (title.value && title.value.length > config.titleMax) {
+      out.push({
+        dimension: "seo",
+        rule: "seo.title-too-long",
+        severity: "warning",
+        message: `Title is ${title.value.length} chars (recommended \u2264 ${config.titleMax})`,
+        fix: "Shorten the title so it isn't truncated in search results."
+      });
+    }
+  }
+  if (required.has("description")) {
+    if (!desc) {
+      out.push({
+        dimension: "seo",
+        rule: "seo.missing-description",
+        severity: "warning",
+        message: "No frontmatter `description`",
+        fix: `Add a ${config.descriptionMin}\u2013${config.descriptionMax} char description for the search snippet.`
+      });
+    } else if (desc.length < config.descriptionMin) {
+      out.push({
+        dimension: "seo",
+        rule: "seo.description-short",
+        severity: "warning",
+        message: `Description is ${desc.length} chars (recommended \u2265 ${config.descriptionMin})`
+      });
+    } else if (desc.length > config.descriptionMax) {
+      out.push({
+        dimension: "seo",
+        rule: "seo.description-long",
+        severity: "warning",
+        message: `Description is ${desc.length} chars (recommended \u2264 ${config.descriptionMax})`,
+        fix: "Trim it so search engines don't truncate the snippet."
+      });
+    }
+  }
+  for (const key of config.requireFrontmatter) {
+    if (key === "title" || key === "description") continue;
+    if (!asString(page.frontmatter.data[key])) {
+      out.push({
+        dimension: "seo",
+        rule: `seo.missing-frontmatter`,
+        severity: "warning",
+        message: `Missing required frontmatter: \`${key}\``
+      });
+    }
+  }
+  const tKey = title.value.trim().toLowerCase();
+  const others = (dup.titles.get(tKey) ?? []).filter((p) => p !== page.relPath);
+  if (tKey && others.length) {
+    out.push({
+      dimension: "seo",
+      rule: "seo.duplicate-title",
+      severity: "warning",
+      message: `Duplicate title \u2014 also used by ${others.length} other page(s)`,
+      detail: others.slice(0, 3).join(", "),
+      fix: "Give each page a unique title; duplicates compete in search results."
+    });
+  }
+  const dKey = desc.trim().toLowerCase();
+  const dOthers = (dup.descriptions.get(dKey) ?? []).filter((p) => p !== page.relPath);
+  if (dKey && dOthers.length) {
+    out.push({
+      dimension: "seo",
+      rule: "seo.duplicate-description",
+      severity: "warning",
+      message: `Duplicate description \u2014 also used by ${dOthers.length} other page(s)`,
+      detail: dOthers.slice(0, 3).join(", "),
+      fix: "Write a unique description per page."
+    });
+  }
+  return out;
+}
+
+// src/checks/structure.ts
+function structureChecks(page, _config) {
+  const out = [];
+  const { headings, images, fences } = page.md;
+  const h1s = headings.filter((h) => h.level === 1);
+  if (h1s.length === 0) {
+    out.push({
+      dimension: "structure",
+      rule: "structure.no-h1",
+      severity: "warning",
+      message: "No H1 heading",
+      fix: "Start the page with a single `# Title`."
+    });
+  } else if (h1s.length > 1) {
+    out.push({
+      dimension: "structure",
+      rule: "structure.multiple-h1",
+      severity: "warning",
+      message: `${h1s.length} H1 headings (use exactly one)`,
+      line: h1s[1].line,
+      fix: "Demote the extra H1s to H2/H3 so the outline has one top level."
+    });
+  }
+  let prev = 0;
+  for (const h of headings) {
+    if (prev !== 0 && h.level > prev + 1) {
+      out.push({
+        dimension: "structure",
+        rule: "structure.skipped-heading",
+        severity: "warning",
+        message: `Heading jumps from H${prev} to H${h.level} ("${h.text}")`,
+        line: h.line,
+        fix: "Don't skip levels \u2014 screen readers and outlines rely on order."
+      });
+    }
+    prev = h.level;
+  }
+  for (const img of images) {
+    if (img.alt.trim() === "") {
+      out.push({
+        dimension: "structure",
+        rule: "structure.image-alt",
+        severity: "warning",
+        message: `Image has no alt text: ${img.src}`,
+        line: img.line,
+        fix: "Add descriptive alt text: `![what it shows](src)`."
+      });
+    }
+  }
+  for (const fence of fences) {
+    if (fence.lang === null) {
+      out.push({
+        dimension: "structure",
+        rule: "structure.code-language",
+        severity: "info",
+        message: "Code block has no language tag",
+        line: fence.line,
+        fix: "Add a language after the opening fence (e.g. ```ts) for highlighting."
+      });
+    }
+  }
+  return out;
+}
+
+// src/config.ts
+var DEFAULT_CONFIG = {
+  extensions: [".md", ".mdx", ".markdown"],
+  requireFrontmatter: ["title", "description"],
+  descriptionMin: 50,
+  descriptionMax: 160,
+  titleMax: 60,
+  maxGrade: 14,
+  minWordsForReadability: 80,
+  disable: [],
+  ignore: [],
+  minScore: 0
+};
+var CONFIG_FILENAMES = ["docsanity.config.json", ".docsanityrc.json", ".docsanityrc"];
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function mergeConfig(base, override) {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(override ?? {})) {
+    if (v !== void 0) out[k] = v;
+  }
+  return out;
+}
+function parseConfig(json, label = "config") {
+  let data;
+  try {
+    data = JSON.parse(json);
+  } catch (e) {
+    throw new Error(`invalid ${label}: ${e.message}`);
+  }
+  if (!isPlainObject(data)) throw new Error(`invalid ${label}: must be a JSON object`);
+  return mergeConfig(DEFAULT_CONFIG, data);
+}
+function isDimensionEnabled(config, dim) {
+  return !config.disable.includes(dim);
+}
+function mapSeverity(s) {
+  return s === "error" || s === "warning" || s === "info" ? s : "warning";
+}
+function linkFindings(root, pages) {
+  const inputs = pages.map((p) => ({ path: p.absPath, content: p.content }));
+  const project = linklint.buildProjectFromInputs(root, inputs);
+  const report = linklint.analyze(project, linklint.DEFAULT_CONFIG);
+  const byPath = /* @__PURE__ */ new Map();
+  for (const doc of report.documents) {
+    byPath.set(
+      doc.path,
+      doc.issues.map((i) => ({
+        dimension: "links",
+        rule: `links.${i.rule}`,
+        severity: mapSeverity(i.severity),
+        message: i.message,
+        line: i.line,
+        detail: i.detail,
+        fix: i.fix
+      }))
+    );
+  }
+  for (const abs of linklint.findOrphans(project)) {
+    const rel = path.relative(root, abs) || abs;
+    const list = byPath.get(rel) ?? [];
+    list.push({
+      dimension: "links",
+      rule: "links.orphan-document",
+      severity: "warning",
+      message: "Orphan page \u2014 nothing links here",
+      fix: "Link to it from an index/README, or remove it if it's obsolete."
+    });
+    byPath.set(rel, list);
+  }
+  return byPath;
+}
+
+// src/markdown.ts
+var FENCE_RE = /^(\s*)(`{3,}|~{3,})\s*([A-Za-z0-9_+-]*)/;
+var HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+var IMAGE_RE = /!\[([^\]]*)\]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g;
+var HTML_IMG_RE = /<img\b[^>]*>/gi;
+function htmlImgAlt(tag) {
+  const m = /\balt\s*=\s*["']([^"']*)["']/i.exec(tag);
+  return m ? m[1] : "";
+}
+function htmlImgSrc(tag) {
+  const m = /\bsrc\s*=\s*["']([^"']*)["']/i.exec(tag);
+  return m ? m[1] : "";
+}
+function parseMarkdown(body, lineOffset = 0) {
+  const lines = body.split(/\r?\n/);
+  const headings = [];
+  const images = [];
+  const fences = [];
+  const textParts = [];
+  let inFence = false;
+  let fenceMarker = "";
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const lineNo = i + 1 + lineOffset;
+    const fence = FENCE_RE.exec(raw);
+    if (fence && (!inFence || raw.trim().startsWith(fenceMarker))) {
+      const marker = fence[2];
+      if (!inFence) {
+        inFence = true;
+        fenceMarker = marker[0].repeat(3);
+        fences.push({ lang: fence[3] ? fence[3] : null, line: lineNo });
+      } else {
+        inFence = false;
+        fenceMarker = "";
+      }
+      continue;
+    }
+    if (inFence) continue;
+    const heading = HEADING_RE.exec(raw);
+    if (heading) {
+      headings.push({ level: heading[1].length, text: heading[2].trim(), line: lineNo });
+      textParts.push(heading[2].trim());
+      continue;
+    }
+    let m;
+    IMAGE_RE.lastIndex = 0;
+    while ((m = IMAGE_RE.exec(raw)) !== null) {
+      images.push({ alt: m[1], src: m[2], line: lineNo });
+    }
+    HTML_IMG_RE.lastIndex = 0;
+    while ((m = HTML_IMG_RE.exec(raw)) !== null) {
+      images.push({ alt: htmlImgAlt(m[0]), src: htmlImgSrc(m[0]), line: lineNo });
+    }
+    textParts.push(stripInline(raw));
+  }
+  return { headings, images, fences, text: textParts.join("\n").trim() };
+}
+function stripInline(line) {
+  return line.replace(IMAGE_RE, "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/`([^`]*)`/g, "$1").replace(/<[^>]+>/g, "").replace(/^[>\s]*>/g, "").replace(/^\s{0,3}([*+-]|\d+\.)\s+/g, "").replace(/[*_~]+/g, "").trim();
+}
+
+// src/page.ts
+function parsePage(absPath, relPath, content) {
+  const frontmatter = parseFrontmatter(content);
+  const md = parseMarkdown(frontmatter.body, frontmatter.offset);
+  return { absPath, relPath, content, frontmatter, md };
+}
+
+// src/score.ts
+var PENALTY = { error: 12, warning: 4, info: 1, pass: 0 };
+function scorePage(findings) {
+  let penalty = 0;
+  for (const f of findings) penalty += PENALTY[f.severity] ?? 0;
+  return Math.max(0, 100 - penalty);
+}
+function gradeFor(score) {
+  if (score >= 90) return "A";
+  if (score >= 80) return "B";
+  if (score >= 70) return "C";
+  if (score >= 60) return "D";
+  return "F";
+}
+
+// src/types.ts
+var DIMENSIONS = ["links", "seo", "readability", "structure"];
+var DIMENSION_LABELS = {
+  links: "Links & references",
+  seo: "SEO & frontmatter",
+  readability: "Readability",
+  structure: "Structure & a11y"
+};
+
+// src/analyze.ts
+function analyzeDocs(root, inputs, config, meta) {
+  const pages = inputs.map((i) => parsePage(i.absPath, i.relPath, i.content));
+  const ignore = new Set(config.ignore);
+  const dup = buildDuplicateIndex(pages);
+  const links = isDimensionEnabled(config, "links") ? linkFindings(root, pages) : /* @__PURE__ */ new Map();
+  const pageReports = pages.map((page) => {
+    const findings = [];
+    let readability;
+    if (isDimensionEnabled(config, "links")) {
+      findings.push(...links.get(page.relPath) ?? []);
+    }
+    if (isDimensionEnabled(config, "seo")) {
+      findings.push(...seoChecks(page, config, dup));
+    }
+    if (isDimensionEnabled(config, "structure")) {
+      findings.push(...structureChecks(page));
+    }
+    if (isDimensionEnabled(config, "readability")) {
+      const r = readabilityCheck(page, config);
+      findings.push(...r.findings);
+      readability = r.summary;
+    }
+    const kept = findings.filter((f) => !ignore.has(f.rule));
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const f of kept) {
+      if (f.severity === "error") counts.error++;
+      else if (f.severity === "warning") counts.warning++;
+      else if (f.severity === "info") counts.info++;
+    }
+    const score2 = scorePage(kept);
+    return {
+      path: page.relPath,
+      title: pageTitle(page).value || null,
+      score: score2,
+      grade: gradeFor(score2),
+      counts,
+      findings: kept,
+      readability
+    };
+  });
+  pageReports.sort((a, b) => a.path.localeCompare(b.path));
+  const errors = pageReports.reduce((s, p) => s + p.counts.error, 0);
+  const warnings = pageReports.reduce((s, p) => s + p.counts.warning, 0);
+  const infos = pageReports.reduce((s, p) => s + p.counts.info, 0);
+  const score = pageReports.length ? Math.round(pageReports.reduce((s, p) => s + p.score, 0) / pageReports.length) : 100;
+  const byDimension = Object.fromEntries(
+    DIMENSIONS.map((d) => [d, { errors: 0, warnings: 0, infos: 0 }])
+  );
+  for (const p of pageReports) {
+    for (const f of p.findings) {
+      const bucket = byDimension[f.dimension];
+      if (f.severity === "error") bucket.errors++;
+      else if (f.severity === "warning") bucket.warnings++;
+      else if (f.severity === "info") bucket.infos++;
+    }
+  }
+  return {
+    tool: "docsanity",
+    version: meta.version,
+    generatedAt: meta.generatedAt,
+    root,
+    summary: { pages: pageReports.length, score, grade: gradeFor(score), errors, warnings, infos, byDimension },
+    pages: pageReports
+  };
+}
+function loadConfig(explicitPath, cwd = process.cwd()) {
+  let file = explicitPath ? path.resolve(cwd, explicitPath) : void 0;
+  if (!file) {
+    for (const name of CONFIG_FILENAMES) {
+      const candidate = path.resolve(cwd, name);
+      if (fs.existsSync(candidate)) {
+        file = candidate;
+        break;
+      }
+    }
+  }
+  if (!file) return DEFAULT_CONFIG;
+  if (!fs.existsSync(file)) throw new Error(`config file not found: ${file}`);
+  return parseConfig(fs.readFileSync(file, "utf8"), `config ${file}`);
+}
+var IGNORE_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  ".docusaurus",
+  ".astro",
+  ".cache",
+  "coverage"
+]);
+function walk(dir, exts, out) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (IGNORE_DIRS.has(entry.name)) continue;
+      walk(path.join(dir, entry.name), exts, out);
+    } else if (entry.isFile() && exts.has(path.extname(entry.name).toLowerCase())) {
+      out.push(path.join(dir, entry.name));
+    }
+  }
+}
+function loadDocs(targets, config) {
+  const exts = new Set(config.extensions.map((e) => e.toLowerCase()));
+  const files = [];
+  let root = process.cwd();
+  if (targets.length === 1) {
+    const abs = path.resolve(targets[0]);
+    if (fs.statSync(abs).isDirectory()) root = abs;
+  }
+  for (const target of targets) {
+    const abs = path.resolve(target);
+    const stat = fs.statSync(abs);
+    if (stat.isDirectory()) walk(abs, exts, files);
+    else if (exts.has(path.extname(abs).toLowerCase())) files.push(abs);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const docs = [];
+  for (const file of files.sort()) {
+    if (seen.has(file)) continue;
+    seen.add(file);
+    docs.push({
+      absPath: file,
+      relPath: path.relative(root, file) || file,
+      content: fs.readFileSync(file, "utf8")
+    });
+  }
+  return { root, docs };
+}
+function sev(severity, text) {
+  if (severity === "error") return pc__default.default.red(text);
+  if (severity === "warning") return pc__default.default.yellow(text);
+  if (severity === "info") return pc__default.default.blue(text);
+  return pc__default.default.green(text);
+}
+var MARK = { error: "\u2717", warning: "\u26A0", info: "\u2139", pass: "\u2713" };
+function gradeColor(grade) {
+  if (grade === "A" || grade === "B") return pc__default.default.green;
+  if (grade === "C" || grade === "D") return pc__default.default.yellow;
+  return pc__default.default.red;
+}
+function printReport(report, quiet = false) {
+  for (const page of report.pages) {
+    const g2 = gradeColor(page.grade);
+    const head = `${pc__default.default.bold(page.path)}  ${g2(`${page.score}/100 (${page.grade})`)}`;
+    const meta = page.readability ? pc__default.default.dim(`  grade ${page.readability.grade.toFixed(0)} \xB7 ${page.readability.words}w`) : "";
+    console.log(`
+${head}${meta}`);
+    if (quiet) continue;
+    if (page.findings.length === 0) {
+      console.log(`  ${pc__default.default.green("\u2713 no issues")}`);
+      continue;
+    }
+    for (const f of page.findings) {
+      const where = f.line ? pc__default.default.dim(`L${f.line}`.padEnd(6)) : "".padEnd(6);
+      const mark = sev(f.severity, MARK[f.severity]);
+      console.log(`  ${mark} ${where} ${f.message} ${pc__default.default.dim(f.rule)}`);
+    }
+  }
+  const s = report.summary;
+  const g = gradeColor(s.grade);
+  console.log(`
+${pc__default.default.bold("Dimensions")}`);
+  for (const dim of Object.keys(s.byDimension)) {
+    const b = s.byDimension[dim];
+    const status = b.errors + b.warnings === 0 ? pc__default.default.green("clean") : `${pc__default.default.red(`${b.errors}e`)} ${pc__default.default.yellow(`${b.warnings}w`)}`;
+    console.log(`  ${DIMENSION_LABELS[dim].padEnd(22)} ${status}`);
+  }
+  console.log(
+    `
+${pc__default.default.bold("Overall")}  ${g(`${s.score}/100 (${s.grade})`)} ` + pc__default.default.dim(`\xB7 ${s.pages} page(s), ${s.errors} error(s), ${s.warnings} warning(s)`)
+  );
+}
+
+// src/report/json.ts
+function toJSON(report) {
+  return JSON.stringify(report, null, 2) + "\n";
+}
+
+// src/report/markdown.ts
+var ICON = { error: "\u2717", warning: "\u26A0", info: "\u2139", pass: "\u2713" };
+function toMarkdown(report) {
+  const s = report.summary;
+  const out = [];
+  out.push(`# docsanity report`);
+  out.push("");
+  out.push(
+    `**${s.score}/100 (${s.grade})** across **${s.pages}** page(s) \u2014 ${s.errors} error(s), ${s.warnings} warning(s), ${s.infos} info(s)`
+  );
+  out.push("");
+  out.push(`| Dimension | Errors | Warnings |`);
+  out.push(`| --------- | -----: | -------: |`);
+  for (const dim of Object.keys(report.summary.byDimension)) {
+    const b = report.summary.byDimension[dim];
+    out.push(`| ${DIMENSION_LABELS[dim]} | ${b.errors} | ${b.warnings} |`);
+  }
+  out.push("");
+  for (const page of report.pages) {
+    const head = `## ${page.path} \u2014 ${page.score}/100 (${page.grade})`;
+    out.push(head);
+    if (page.readability) {
+      out.push(
+        `_${page.readability.words} words \xB7 grade ${page.readability.grade.toFixed(0)} (${page.readability.gradeLabel}) \xB7 ${page.readability.ease}_`
+      );
+    }
+    out.push("");
+    if (page.findings.length === 0) {
+      out.push(`\u2713 No issues.`);
+      out.push("");
+      continue;
+    }
+    out.push(`| | Rule | Where | Message |`);
+    out.push(`| - | ---- | ----- | ------- |`);
+    for (const f of page.findings) {
+      const where = f.line ? `L${f.line}` : "";
+      out.push(`| ${ICON[f.severity]} | \`${f.rule}\` | ${where} | ${f.message.replace(/\|/g, "\\|")} |`);
+    }
+    out.push("");
+  }
+  out.push(`---`);
+  out.push(`<sub>Generated by docsanity v${report.version} \xB7 ${report.generatedAt}</sub>`);
+  out.push("");
+  return out.join("\n");
+}
+
+// src/cli.ts
+var cli = cac.cac("docsanity");
+function fail(message) {
+  console.error(`${pc__default.default.red("docsanity:")} ${message}`);
+  process.exit(2);
+}
+function parseDimensions(value) {
+  if (!value) return [];
+  const known = new Set(DIMENSIONS);
+  return value.split(",").map((s) => s.trim()).filter(Boolean).map((d) => {
+    if (!known.has(d)) fail(`unknown dimension "${d}". Known: ${DIMENSIONS.join(", ")}`);
+    return d;
+  });
+}
+cli.command("scan [...targets]", "Audit a docs directory or files").option("--config <file>", "Path to a config file").option("--disable <dims>", "Comma-separated dimensions to skip (links,seo,readability,structure)").option("--max-grade <n>", "Flag pages reading above this grade level").option("--json <file>", "Write a JSON report to this path").option("--md <file>", "Write a Markdown report to this path").option("--min-score <n>", "CI gate: exit non-zero if the overall score is below this").option("--quiet", "Show only per-page headers").example("  docsanity scan ./docs").example("  docsanity scan ./docs --min-score 85 --md docs-report.md").example("  docsanity scan ./docs --disable readability").action((targets, options) => {
+  if (!targets || targets.length === 0) fail("provide a docs directory or files to scan.");
+  try {
+    const config = loadConfig(options.config);
+    const disable = parseDimensions(options.disable);
+    if (disable.length) config.disable = [.../* @__PURE__ */ new Set([...config.disable, ...disable])];
+    if (options.maxGrade !== void 0) config.maxGrade = Number(options.maxGrade);
+    const { root, docs } = loadDocs(targets, config);
+    if (docs.length === 0) fail(`no matching files (${config.extensions.join(", ")}) found.`);
+    const report = analyzeDocs(root, docs, config, {
+      version: package_default.version,
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    printReport(report, Boolean(options.quiet));
+    if (options.json) {
+      fs.writeFileSync(path.resolve(options.json), toJSON(report));
+      console.log(pc__default.default.dim(`
+Wrote JSON report \u2192 ${options.json}`));
+    }
+    if (options.md) {
+      fs.writeFileSync(path.resolve(options.md), toMarkdown(report));
+      console.log(pc__default.default.dim(`Wrote Markdown report \u2192 ${options.md}`));
+    }
+    const minScore = options.minScore !== void 0 ? Number(options.minScore) : config.minScore;
+    if (report.summary.score < minScore) {
+      console.error(
+        `
+${pc__default.default.red("docsanity:")} score ${report.summary.score} is below the minimum ${minScore}.`
+      );
+      process.exit(1);
+    }
+  } catch (e) {
+    fail(e.message);
+  }
+});
+cli.command("report <input>", "Render a saved JSON report as Markdown").option("--md <file>", "Write Markdown to this path instead of stdout").action((input, options) => {
+  try {
+    const report = JSON.parse(fs.readFileSync(path.resolve(input), "utf8"));
+    const md = toMarkdown(report);
+    if (options.md) {
+      fs.writeFileSync(path.resolve(options.md), md);
+      console.log(`Wrote ${options.md}`);
+    } else {
+      process.stdout.write(md);
+    }
+  } catch (e) {
+    fail(e.message);
+  }
+});
+cli.command("init", "Write a docsanity.config.json with the defaults").option("--force", "Overwrite an existing config").action((options) => {
+  const file = path.resolve("docsanity.config.json");
+  if (fs.existsSync(file) && !options.force) {
+    console.error(`${pc__default.default.red("docsanity:")} docsanity.config.json already exists (use --force).`);
+    process.exit(1);
+  }
+  fs.writeFileSync(file, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
+  console.log("Created docsanity.config.json");
+});
+cli.help();
+cli.version(package_default.version);
+cli.parse();
+//# sourceMappingURL=cli.cjs.map
+//# sourceMappingURL=cli.cjs.map