docsanity 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,226 @@
+/** Core types for docsanity. */
+type Severity = "error" | "warning" | "info" | "pass";
+/** The four health dimensions docsanity unifies into one report. */
+type Dimension = "links" | "seo" | "readability" | "structure";
+declare const DIMENSIONS: Dimension[];
+declare const DIMENSION_LABELS: Record<Dimension, string>;
+interface Finding {
+    dimension: Dimension;
+    /** Stable id, e.g. "seo.missing-description". */
+    rule: string;
+    severity: Severity;
+    message: string;
+    /** 1-based line number, when known. */
+    line?: number;
+    detail?: string;
+    fix?: string;
+}
+interface ReadabilitySummary {
+    grade: number;
+    gradeLabel: string;
+    ease: string;
+    words: number;
+    readingTimeSeconds: number;
+}
+interface PageReport {
+    /** Path relative to the scanned root. */
+    path: string;
+    title: string | null;
+    score: number;
+    grade: string;
+    counts: {
+        error: number;
+        warning: number;
+        info: number;
+    };
+    findings: Finding[];
+    readability?: ReadabilitySummary;
+}
+interface DocsReport {
+    tool: "docsanity";
+    version: string;
+    generatedAt: string;
+    root: string;
+    summary: {
+        pages: number;
+        score: number;
+        grade: string;
+        errors: number;
+        warnings: number;
+        infos: number;
+        byDimension: Record<Dimension, {
+            errors: number;
+            warnings: number;
+            infos: number;
+        }>;
+    };
+    pages: PageReport[];
+}
+interface Config {
+    /** File extensions to scan. */
+    extensions: string[];
+    /** Frontmatter keys every page must have (non-empty). */
+    requireFrontmatter: string[];
+    /** Recommended meta-description length window. */
+    descriptionMin: number;
+    descriptionMax: number;
+    /** Warn when a title is longer than this (characters). */
+    titleMax: number;
+    /** Warn when a page's reading grade exceeds this. */
+    maxGrade: number;
+    /** Minimum word count before readability is scored. */
+    minWordsForReadability: number;
+    /** Dimensions to skip entirely. */
+    disable: Dimension[];
+    /** Rule ids to ignore (e.g. "structure.code-language"). */
+    ignore: string[];
+    /** CI gate: overall score floor. */
+    minScore: number;
+}
+
+/**
+ * The orchestrator: parse every page once, run all four dimensions over the
+ * shared page set (so site-wide checks like duplicate titles and orphan pages
+ * work), and fold everything into one unified report with a combined score.
+ */
+
+interface InputDoc {
+    absPath: string;
+    relPath: string;
+    content: string;
+}
+interface AnalyzeMeta {
+    version: string;
+    generatedAt: string;
+}
+/** Analyze a set of documentation pages into a unified {@link DocsReport}. */
+declare function analyzeDocs(root: string, inputs: InputDoc[], config: Config, meta: AnalyzeMeta): DocsReport;
+
+/**
+ * A small, dependency-free YAML-frontmatter parser. Docs sites (Docusaurus,
+ * Astro, Nextra, Hugo, Jekyll, …) put metadata in a `---` fenced block at the
+ * top of each Markdown file. We only need scalars and simple lists, so we parse
+ * those directly rather than pulling in a full YAML engine.
+ */
+type FrontmatterValue = string | string[] | boolean | number;
+interface Frontmatter {
+    data: Record<string, FrontmatterValue>;
+    /** The document body with the frontmatter block removed. */
+    body: string;
+    /** Number of lines the frontmatter occupied (so body line numbers can be offset). */
+    offset: number;
+    present: boolean;
+}
+/** Parse a leading `---` frontmatter block. Returns empty data when absent. */
+declare function parseFrontmatter(content: string): Frontmatter;
+/** Get a frontmatter value as a trimmed string (lists join with ", "). */
+declare function asString(value: FrontmatterValue | undefined): string;
+
+/**
+ * Lightweight Markdown extraction — headings, images, code fences and a plain
+ * text projection — without a full Markdown parser. We track fenced code blocks
+ * so `#` inside a code sample is never mistaken for a heading.
+ */
+interface Heading {
+    level: number;
+    text: string;
+    line: number;
+}
+interface MdImage {
+    alt: string;
+    src: string;
+    line: number;
+}
+interface CodeFence {
+    lang: string | null;
+    line: number;
+}
+interface MarkdownModel {
+    headings: Heading[];
+    images: MdImage[];
+    fences: CodeFence[];
+    /** Plain-text projection suitable for readability scoring. */
+    text: string;
+}
+declare function parseMarkdown(body: string, lineOffset?: number): MarkdownModel;
+
+/** A parsed documentation page: frontmatter + extracted Markdown model. */
+
+interface Page {
+    /** Absolute path (needed for cross-file link resolution). */
+    absPath: string;
+    /** Path relative to the scanned root (for display). */
+    relPath: string;
+    content: string;
+    frontmatter: Frontmatter;
+    md: MarkdownModel;
+}
+declare function parsePage(absPath: string, relPath: string, content: string): Page;
+
+/**
+ * SEO & frontmatter checks. Beyond per-page frontmatter completeness, this
+ * includes the **site-wide** checks no single-file linter can do: duplicate
+ * titles and duplicate meta descriptions across the whole docs set (both hurt
+ * search ranking). That cross-page view is the point of a suite.
+ */
+
+interface DuplicateIndex {
+    titles: Map<string, string[]>;
+    descriptions: Map<string, string[]>;
+}
+/** Resolve a page's effective title: explicit frontmatter, else the first H1. */
+declare function pageTitle(page: Page): {
+    value: string;
+    source: "frontmatter" | "h1" | null;
+};
+/** Build the cross-page duplicate index (value → list of page paths). */
+declare function buildDuplicateIndex(pages: Page[]): DuplicateIndex;
+declare function seoChecks(page: Page, config: Config, dup: DuplicateIndex): Finding[];
+
+/**
+ * Structure & accessibility checks on Markdown — the docs-relevant subset of an
+ * HTML a11y linter: a single H1, no skipped heading levels, images with alt
+ * text, and fenced code blocks that declare a language (for correct syntax
+ * highlighting and screen-reader hints).
+ */
+
+declare function structureChecks(page: Page, _config: Config): Finding[];
+
+/**
+ * Readability check — leverages the `readlevel` engine on each page's prose and
+ * flags pages that read harder than the configured grade ceiling. Docs that are
+ * too dense lose readers (and AI answer engines that prefer clear sources).
+ */
+
+interface ReadabilityResult {
+    findings: Finding[];
+    summary?: ReadabilitySummary;
+}
+declare function readabilityCheck(page: Page, config: Config): ReadabilityResult;
+
+/**
+ * Links & references — leverages the `linklint` engine, which already builds a
+ * cross-file project graph and finds broken relative links, dead `#anchors`,
+ * missing images, undefined references and **orphan pages** (nothing links to
+ * them). docsanity runs it once over the whole set and folds its findings into
+ * the unified per-page report, keyed by each page's root-relative path.
+ */
+
+/** Run linklint over all pages; return findings keyed by root-relative path. */
+declare function linkFindings(root: string, pages: Page[]): Map<string, Finding[]>;
+
+/** Weighted scoring: turn findings into a 0–100 score and an A–F grade. */
+
+/** Page score: 100 minus capped, weighted penalties for its findings. */
+declare function scorePage(findings: Finding[]): number;
+declare function gradeFor(score: number): string;
+
+/** Configuration defaults, parsing, and resolution (pure — no file I/O). */
+
+declare const DEFAULT_CONFIG: Config;
+declare const CONFIG_FILENAMES: string[];
+declare function mergeConfig(base: Config, override: Partial<Config>): Config;
+declare function parseConfig(json: string, label?: string): Config;
+declare function isDimensionEnabled(config: Config, dim: Dimension): boolean;
+
+export { type AnalyzeMeta, CONFIG_FILENAMES, type Config, DEFAULT_CONFIG, DIMENSIONS, DIMENSION_LABELS, type Dimension, type DocsReport, type Finding, type Frontmatter, type Heading, type InputDoc, type MarkdownModel, type Page, type PageReport, type ReadabilitySummary, type Severity, analyzeDocs, asString, buildDuplicateIndex, gradeFor, isDimensionEnabled, linkFindings, mergeConfig, pageTitle, parseConfig, parseFrontmatter, parseMarkdown, parsePage, readabilityCheck, scorePage, seoChecks, structureChecks };

package/dist/index.d.ts

@@ -0,0 +1,226 @@
+/** Core types for docsanity. */
+type Severity = "error" | "warning" | "info" | "pass";
+/** The four health dimensions docsanity unifies into one report. */
+type Dimension = "links" | "seo" | "readability" | "structure";
+declare const DIMENSIONS: Dimension[];
+declare const DIMENSION_LABELS: Record<Dimension, string>;
+interface Finding {
+    dimension: Dimension;
+    /** Stable id, e.g. "seo.missing-description". */
+    rule: string;
+    severity: Severity;
+    message: string;
+    /** 1-based line number, when known. */
+    line?: number;
+    detail?: string;
+    fix?: string;
+}
+interface ReadabilitySummary {
+    grade: number;
+    gradeLabel: string;
+    ease: string;
+    words: number;
+    readingTimeSeconds: number;
+}
+interface PageReport {
+    /** Path relative to the scanned root. */
+    path: string;
+    title: string | null;
+    score: number;
+    grade: string;
+    counts: {
+        error: number;
+        warning: number;
+        info: number;
+    };
+    findings: Finding[];
+    readability?: ReadabilitySummary;
+}
+interface DocsReport {
+    tool: "docsanity";
+    version: string;
+    generatedAt: string;
+    root: string;
+    summary: {
+        pages: number;
+        score: number;
+        grade: string;
+        errors: number;
+        warnings: number;
+        infos: number;
+        byDimension: Record<Dimension, {
+            errors: number;
+            warnings: number;
+            infos: number;
+        }>;
+    };
+    pages: PageReport[];
+}
+interface Config {
+    /** File extensions to scan. */
+    extensions: string[];
+    /** Frontmatter keys every page must have (non-empty). */
+    requireFrontmatter: string[];
+    /** Recommended meta-description length window. */
+    descriptionMin: number;
+    descriptionMax: number;
+    /** Warn when a title is longer than this (characters). */
+    titleMax: number;
+    /** Warn when a page's reading grade exceeds this. */
+    maxGrade: number;
+    /** Minimum word count before readability is scored. */
+    minWordsForReadability: number;
+    /** Dimensions to skip entirely. */
+    disable: Dimension[];
+    /** Rule ids to ignore (e.g. "structure.code-language"). */
+    ignore: string[];
+    /** CI gate: overall score floor. */
+    minScore: number;
+}
+
+/**
+ * The orchestrator: parse every page once, run all four dimensions over the
+ * shared page set (so site-wide checks like duplicate titles and orphan pages
+ * work), and fold everything into one unified report with a combined score.
+ */
+
+interface InputDoc {
+    absPath: string;
+    relPath: string;
+    content: string;
+}
+interface AnalyzeMeta {
+    version: string;
+    generatedAt: string;
+}
+/** Analyze a set of documentation pages into a unified {@link DocsReport}. */
+declare function analyzeDocs(root: string, inputs: InputDoc[], config: Config, meta: AnalyzeMeta): DocsReport;
+
+/**
+ * A small, dependency-free YAML-frontmatter parser. Docs sites (Docusaurus,
+ * Astro, Nextra, Hugo, Jekyll, …) put metadata in a `---` fenced block at the
+ * top of each Markdown file. We only need scalars and simple lists, so we parse
+ * those directly rather than pulling in a full YAML engine.
+ */
+type FrontmatterValue = string | string[] | boolean | number;
+interface Frontmatter {
+    data: Record<string, FrontmatterValue>;
+    /** The document body with the frontmatter block removed. */
+    body: string;
+    /** Number of lines the frontmatter occupied (so body line numbers can be offset). */
+    offset: number;
+    present: boolean;
+}
+/** Parse a leading `---` frontmatter block. Returns empty data when absent. */
+declare function parseFrontmatter(content: string): Frontmatter;
+/** Get a frontmatter value as a trimmed string (lists join with ", "). */
+declare function asString(value: FrontmatterValue | undefined): string;
+
+/**
+ * Lightweight Markdown extraction — headings, images, code fences and a plain
+ * text projection — without a full Markdown parser. We track fenced code blocks
+ * so `#` inside a code sample is never mistaken for a heading.
+ */
+interface Heading {
+    level: number;
+    text: string;
+    line: number;
+}
+interface MdImage {
+    alt: string;
+    src: string;
+    line: number;
+}
+interface CodeFence {
+    lang: string | null;
+    line: number;
+}
+interface MarkdownModel {
+    headings: Heading[];
+    images: MdImage[];
+    fences: CodeFence[];
+    /** Plain-text projection suitable for readability scoring. */
+    text: string;
+}
+declare function parseMarkdown(body: string, lineOffset?: number): MarkdownModel;
+
+/** A parsed documentation page: frontmatter + extracted Markdown model. */
+
+interface Page {
+    /** Absolute path (needed for cross-file link resolution). */
+    absPath: string;
+    /** Path relative to the scanned root (for display). */
+    relPath: string;
+    content: string;
+    frontmatter: Frontmatter;
+    md: MarkdownModel;
+}
+declare function parsePage(absPath: string, relPath: string, content: string): Page;
+
+/**
+ * SEO & frontmatter checks. Beyond per-page frontmatter completeness, this
+ * includes the **site-wide** checks no single-file linter can do: duplicate
+ * titles and duplicate meta descriptions across the whole docs set (both hurt
+ * search ranking). That cross-page view is the point of a suite.
+ */
+
+interface DuplicateIndex {
+    titles: Map<string, string[]>;
+    descriptions: Map<string, string[]>;
+}
+/** Resolve a page's effective title: explicit frontmatter, else the first H1. */
+declare function pageTitle(page: Page): {
+    value: string;
+    source: "frontmatter" | "h1" | null;
+};
+/** Build the cross-page duplicate index (value → list of page paths). */
+declare function buildDuplicateIndex(pages: Page[]): DuplicateIndex;
+declare function seoChecks(page: Page, config: Config, dup: DuplicateIndex): Finding[];
+
+/**
+ * Structure & accessibility checks on Markdown — the docs-relevant subset of an
+ * HTML a11y linter: a single H1, no skipped heading levels, images with alt
+ * text, and fenced code blocks that declare a language (for correct syntax
+ * highlighting and screen-reader hints).
+ */
+
+declare function structureChecks(page: Page, _config: Config): Finding[];
+
+/**
+ * Readability check — leverages the `readlevel` engine on each page's prose and
+ * flags pages that read harder than the configured grade ceiling. Docs that are
+ * too dense lose readers (and AI answer engines that prefer clear sources).
+ */
+
+interface ReadabilityResult {
+    findings: Finding[];
+    summary?: ReadabilitySummary;
+}
+declare function readabilityCheck(page: Page, config: Config): ReadabilityResult;
+
+/**
+ * Links & references — leverages the `linklint` engine, which already builds a
+ * cross-file project graph and finds broken relative links, dead `#anchors`,
+ * missing images, undefined references and **orphan pages** (nothing links to
+ * them). docsanity runs it once over the whole set and folds its findings into
+ * the unified per-page report, keyed by each page's root-relative path.
+ */
+
+/** Run linklint over all pages; return findings keyed by root-relative path. */
+declare function linkFindings(root: string, pages: Page[]): Map<string, Finding[]>;
+
+/** Weighted scoring: turn findings into a 0–100 score and an A–F grade. */
+
+/** Page score: 100 minus capped, weighted penalties for its findings. */
+declare function scorePage(findings: Finding[]): number;
+declare function gradeFor(score: number): string;
+
+/** Configuration defaults, parsing, and resolution (pure — no file I/O). */
+
+declare const DEFAULT_CONFIG: Config;
+declare const CONFIG_FILENAMES: string[];
+declare function mergeConfig(base: Config, override: Partial<Config>): Config;
+declare function parseConfig(json: string, label?: string): Config;
+declare function isDimensionEnabled(config: Config, dim: Dimension): boolean;
+
+export { type AnalyzeMeta, CONFIG_FILENAMES, type Config, DEFAULT_CONFIG, DIMENSIONS, DIMENSION_LABELS, type Dimension, type DocsReport, type Finding, type Frontmatter, type Heading, type InputDoc, type MarkdownModel, type Page, type PageReport, type ReadabilitySummary, type Severity, analyzeDocs, asString, buildDuplicateIndex, gradeFor, isDimensionEnabled, linkFindings, mergeConfig, pageTitle, parseConfig, parseFrontmatter, parseMarkdown, parsePage, readabilityCheck, scorePage, seoChecks, structureChecks };

package/dist/index.js

@@ -0,0 +1,3 @@
+export { CONFIG_FILENAMES, DEFAULT_CONFIG, DIMENSIONS, DIMENSION_LABELS, analyzeDocs, asString, buildDuplicateIndex, gradeFor, isDimensionEnabled, linkFindings, mergeConfig, pageTitle, parseConfig, parseFrontmatter, parseMarkdown, parsePage, readabilityCheck, scorePage, seoChecks, structureChecks } from './chunk-DQY4MKSJ.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "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 — 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"
+  }
+}