skills/plugins/document-navigator/docs/devtools/docs/docs/README.md

@suaveplan/docs - Server-tier markdown documentation toolkit: project-wide discovery, mdast-typed parsing, bidirectional reference graph, hierarchy builder, full-text scored search, typed DocsError registry, OpenTelemetry counters + histograms, Zod-validated DiscoverOptions, AbortSignal propagation.

Server-tier markdown documentation toolkit for Suaveplan. Discovers every .md file under a repo root, parses each via gray-matter + remark into a structured DocFile, builds a bidirectional reference graph, identifies orphans, materialises a per-category hierarchy tree, and answers scored full-text search queries. Ships a typed DocsError namespace, eight OpenTelemetry instruments, Zod-validated DiscoverOptions, and AbortSignal support throughout the async surface.

Documentation tree

• discovery — discoverDocs walks a project root directory and returns one structured DocFile per markdown file it can read. It i…
  • discover — discoverDocs walks a project root directory and returns one structured DocFile per markdown file it can read. It i…
• errors — The errors module owns the typed-error surface of @suaveplan/docs. Every failure path the package can take surfaces…
  • errors — The errors module owns the typed-error surface of @suaveplan/docs. Every failure path the package can take surfaces…
• build-graph — buildGraph consumes the flat array returned by discoverDocs (or any DocFile[] you construct from parseDoc direc…
• find-orphans — findOrphans projects the orphans array of a DocGraph into an actionable OrphanInfo[] sorted by package name, pa…
• hierarchy — buildHierarchy materialises a DocGraph into a tree (DocHierarchy) by treating every README as a root and recursiv…
  • build-hierarchy — buildHierarchy materialises a DocGraph into a tree (DocHierarchy) by treating every README as a root and recursiv…
• observability — The observability module assembles the OpenTelemetry instruments emitted by @suaveplan/docs. `createDocsObservabili…
  • observability — The observability module assembles the OpenTelemetry instruments emitted by @suaveplan/docs. `createDocsObservabili…
• parser — parseDoc turns the raw text of a single markdown file into a structured DocFile by composing gray-matter (frontma…
  • parse — parseDoc turns the raw text of a single markdown file into a structured DocFile by composing gray-matter (frontma…
• search — searchDocs answers a free-text query against a DocFile[] and returns ranked hits with snippet context. It is intent…
  • search — searchDocs answers a free-text query against a DocFile[] and returns ranked hits with snippet context. It is intent…

Install

bun add @suaveplan/docs

Quick start

import {
    buildGraph,
    buildHierarchy,
    discoverDocs,
    findOrphans,
    searchDocs,
} from "@suaveplan/docs";

const docs = await discoverDocs({ rootDir: "/path/to/project" });
const graph = buildGraph(docs);
const tree = buildHierarchy(graph);
const orphans = findOrphans(graph);
const hits = searchDocs(docs, "vault");

console.log(
    `${docs.length} docs, ${tree.roots.length} packages, ${orphans.length} orphans, ${hits.length} matches`
);

Modules

• discovery/discover.md — project-wide .md discovery with AbortSignal and IO-error surfacing.
• parser/parse.md — typed mdast parser with frontmatter, H1 extraction, and link harvesting.
• graph/build-graph.md — bidirectional reference graph + roots + orphans.
• graph/find-orphans.md — orphan listing with suggestedParent README pairing.
• hierarchy/build-hierarchy.md — hierarchy tree with configurable maxDepth.
• search/search.md — scored search with snippet context.
• errors/errors.md — DocsError + DOCS_CODES registry.
• observability/observability.md — OTel counters + histograms factory.