@docvia/ir

pnpm add @docvia/ir

import { docviaError, transformToIR } from "@docvia/ir";
import type { IRDocument, IRNode, docviaConfig } from "@docvia/ir";

// Lighter subpath when you only need the transform
import { transformToIR, normalizeProps } from "@docvia/ir/transform";

class docviaError extends Error {
  readonly name: "docviaError";
  constructor(
    code: docviaErrorCode,
    message: string,
    file?: string,
    loc?: { readonly line: number; readonly column: number },
    cause?: Error,
  );
}

import { docviaError } from "@docvia/ir";

try {
  // ...some docvia operation
} catch (err) {
  if (err instanceof docviaError) {
    console.error(`[${err.code}] ${err.message}`);
    if (err.file) console.error(`  in ${err.file}`);
  }
}

type HydrationMode = "none" | "client:load" | "client:idle" | "client:visible";

interface IRNode {
  readonly type: IRNodeType;
  readonly props: Readonly<Record<string, unknown>>;
  readonly children: readonly IRNode[];
  readonly id?: string;
}

type Dependency =
  | { readonly type: "file"; readonly path: string }
  | { readonly type: "asset"; readonly path: string }
  | { readonly type: "component"; readonly name: string };

interface HeadingMeta {
  readonly depth: number;
  readonly text: string;
  readonly id: string;
}

interface FrontmatterData {
  readonly title: string;
  readonly description: string;
  readonly slug?: string;
  readonly tags: readonly string[];
  readonly draft?: boolean;
  readonly order?: number;
  readonly [key: string]: unknown;
}

interface IRDocument {
  readonly slug: string;
  readonly frontmatter: FrontmatterData;
  readonly children: readonly IRNode[];
  readonly headings: readonly HeadingMeta[];
  readonly dependencies: readonly Dependency[];
  readonly contentHash: string;
}

interface PageMeta {
  readonly slug: string;
  readonly title: string;
  readonly description: string;
  readonly headings: readonly HeadingMeta[];
  readonly contentHash: string;
  readonly lastModified: number;
  readonly tags: readonly string[];
  readonly order?: number;
}

interface RenderedPage {
  readonly slug: string;
  readonly code: string;
  readonly contentHash: string;
  readonly map?: RawSourceMap;
  readonly assets?: readonly AssetReference[];
  readonly imports?: readonly string[];
}

interface AssetReference {
  readonly originalPath: string;
  readonly emittedPath: string;
  readonly hash: string;
}

interface RendererAdapter {
  readonly name: string;
  renderPage(doc: IRDocument): Promise<RenderedPage>;
  renderManifest(pages: readonly PageMeta[]): Promise<string>;
}

interface FileEntry {
  readonly path: string;
  readonly relativePath: string;
  readonly content: string;
  readonly hash: string;
}

interface CompilerOptions {
  readonly sourceDir: string;
  readonly outDir: string;
  readonly renderer: RendererAdapter;
  readonly plugins: readonly docviaPlugin[];
  readonly config: docviaConfig;
  readonly projectRoot?: string;
  readonly incremental?: boolean;
}

interface CompileResult {
  readonly pages: readonly PageMeta[];
  readonly searchIndex?: string;
  readonly duration: number;
  readonly stats: {
    readonly total: number;
    readonly compiled: number;
    readonly cached: number;
  };
}

type HookPhase = "pre" | "normal" | "post";

interface docviaPlugin {
  readonly name: string;
  readonly version: string;
  readonly phase?: HookPhase;
  readonly priority?: number;
  cacheKey?(): string;
  beforeParse?(file: FileEntry): Promise<FileEntry> | FileEntry;
  afterParse?(ast: unknown, file: FileEntry): Promise<unknown> | unknown;
  beforeTransform?(ast: unknown, meta: FrontmatterData): Promise<unknown> | unknown;
  afterTransform?(doc: IRDocument): Promise<IRDocument> | IRDocument;
  beforeRender?(doc: IRDocument): Promise<IRDocument> | IRDocument;
}

interface ComponentConfig {
  readonly path: string;
  readonly hydrate?: boolean;
  readonly defaultProps?: Record<string, unknown>;
}

interface CollectionConfig {
  readonly name: string;
  readonly sourceDir: string;
  readonly baseUrl?: string;
}

interface docviaConfig {
  readonly sourceDir: string;
  readonly outDir: string;
  readonly plugins: readonly docviaPlugin[];
  readonly renderer?: RendererAdapter;
  readonly components?: Record<string, ComponentConfig>;
  readonly collections?: readonly CollectionConfig[];
  readonly frontmatter?: FrontmatterSchema;
  readonly markdown: { readonly remarkPlugins: readonly unknown[] };
  readonly syntax: {
    readonly highlighter: "shiki" | "prism";
    readonly theme: string;
    readonly langs: readonly string[];
  };
  readonly theme: {
    readonly name: string;
    readonly options: Readonly<Record<string, unknown>>;
  };
}

function transformToIR(
  ast: HastRoot,
  frontmatter: FrontmatterData,
  filePath: string,
): IRDocument

function normalizeProps(
  properties?: Record<string, unknown>,
): Record<string, unknown>

import { parseMarkdown } from "@docvia/core";
import { extractFrontmatter, validateFrontmatter } from "@docvia/schema";
import { transformToIR, docviaError } from "@docvia/ir";
import type { IRDocument } from "@docvia/ir";

async function buildDocument(
  rawSource: string,
  relativePath: string,
): Promise<IRDocument> {
  try {
    const { data, content } = extractFrontmatter(rawSource);
    const frontmatter = validateFrontmatter(data, relativePath);
    const { ast } = await parseMarkdown(content);
    return transformToIR(ast, frontmatter, relativePath);
  } catch (err) {
    if (err instanceof docviaError) {
      throw new Error(`[${err.code}] ${relativePath}: ${err.message}`);
    }
    throw err;
  }
}