@wrikka/create-docs 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,475 @@
+/**
+* Domain error types — tagged unions for typed failures.
+*
+* Each module can extend this with its own error variants, but
+* all errors should flow through these base types at boundaries.
+*/
+type AppErrorKind = "file_not_found" | "parse_error" | "validation_error" | "config_error" | "io_error" | "plugin_error";
+interface AppError {
+	readonly kind: AppErrorKind;
+	readonly message: string;
+	readonly cause?: unknown;
+	readonly context?: Readonly<Record<string, unknown>>;
+	/** JSON-pointer-like path to the offending field (e.g. "site.title"). */
+	readonly path?: string;
+	/** Actionable hint shown to the user (e.g. allowed values). */
+	readonly hint?: string;
+	/** Documentation URL related to this error. */
+	readonly docsUrl?: string;
+	/** Allowed values, for inline suggestions. */
+	readonly suggestions?: readonly string[];
+}
+/**
+* Result<T, E> — A pure algebraic data type for synchronous operations
+* that can fail with a typed error.
+*
+* Use this over throwing exceptions at the boundaries (domain, application).
+* Domain must never throw — only return Result.
+*
+* @example
+*   const divide = (a: number, b: number): Result<number, string> =>
+*     b === 0 ? err('Division by zero') : ok(a / b);
+*/
+type Result<
+	T,
+	E
+> = {
+	readonly ok: true;
+	readonly value: T;
+} | {
+	readonly ok: false;
+	readonly error: E;
+};
+declare const ok: <T>(value: T) => Result<T, never>;
+declare const err: <E>(error: E) => Result<never, E>;
+declare const isOk: <
+	T,
+	E
+>(r: Result<T, E>) => r is {
+	ok: true;
+	value: T;
+};
+declare const isErr: <
+	T,
+	E
+>(r: Result<T, E>) => r is {
+	ok: false;
+	error: E;
+};
+/**
+* Brand<T, B> — A nominal type for primitives (preventing ID mixups at compile time).
+*
+* @example
+*   type UserId = Brand<string, 'UserId'>;
+*   type PostId = Brand<string, 'PostId'>;
+*   const get = (id: UserId) => ...;
+*   get('abc' as UserId); // OK
+*   get('abc' as PostId); // compile error
+*/
+type Brand<
+	T,
+	B extends string
+> = T & {
+	readonly __brand: B;
+};
+/**
+* Either<L, R> — A pure algebraic data type for a value that can be one of two types.
+*
+* Convention: L = "left" (often an error/short-circuit), R = "right" (success/continuation).
+*
+* Use this when you need to model two valid outcomes (e.g., a value OR a reason it isn't applicable)
+* without committing to Result's "err" semantics.
+*/
+type Either<
+	L,
+	R
+> = {
+	readonly tag: "left";
+	readonly left: L;
+} | {
+	readonly tag: "right";
+	readonly right: R;
+};
+declare const left: <L>(value: L) => Either<L, never>;
+declare const right: <R>(value: R) => Either<never, R>;
+/**
+* Option<T> — A pure algebraic data type for values that may be absent.
+*
+* Use this to model nullable values without `null | undefined` leakage.
+*
+* @example
+*   const findUser = (id: string): Option<User> =>
+*     users.has(id) ? some(users.get(id)!) : none;
+*/
+type Option<T> = {
+	readonly kind: "some";
+	readonly value: T;
+} | {
+	readonly kind: "none";
+};
+declare const some: <T>(value: T) => Option<T>;
+declare const none: <T = never>() => Option<T>;
+declare const isSome: <T>(o: Option<T>) => o is {
+	kind: "some";
+	value: T;
+};
+declare const isNone: <T>(o: Option<T>) => o is {
+	kind: "none";
+};
+type BadgeVariant = "default" | "success" | "warning" | "danger";
+interface NavItem {
+	readonly label: string;
+	readonly href?: string;
+	readonly items?: readonly NavItem[];
+	readonly badge?: string;
+	readonly icon?: string;
+}
+interface NavSection {
+	readonly title: string;
+	readonly items: readonly NavItem[];
+}
+interface SidebarItem {
+	readonly title: string;
+	readonly slug: string;
+	readonly badge?: string;
+	readonly badgeVariant?: BadgeVariant;
+	readonly items?: readonly SidebarItem[];
+}
+interface SidebarGroup {
+	readonly title: string;
+	readonly icon?: string;
+	readonly items: readonly SidebarItem[];
+	readonly collapsed?: boolean;
+}
+type DocSlug = Brand<string, "DocSlug">;
+type DocId = Brand<string, "DocId">;
+type FilePath = Brand<string, "FilePath">;
+type BadgeVariant2 = "default" | "success" | "warning" | "danger";
+/** A single heading extracted from page body. */
+interface TocItem {
+	readonly id: string;
+	readonly text: string;
+	readonly depth: 1 | 2 | 3 | 4 | 5 | 6;
+}
+/** Per-page metadata derived from the body (not user-authored). */
+interface PageMetadata {
+	readonly readingTime: number;
+	readonly wordCount: number;
+	readonly lastModified?: string;
+	readonly editUrl?: string;
+}
+/** Readonly data model for a doc page's frontmatter. */
+interface Frontmatter {
+	readonly title?: string;
+	readonly description?: string;
+	readonly order?: number;
+	readonly badge?: string;
+	readonly badgeVariant?: BadgeVariant2;
+	readonly collapsible?: boolean;
+	readonly category?: string;
+	readonly author?: string;
+	readonly lastUpdated?: string;
+	readonly tags?: readonly string[];
+	readonly draft?: boolean;
+	readonly [key: string]: unknown;
+}
+/** A single doc page, ready for downstream consumption. */
+interface DocPage {
+	readonly id: DocId;
+	readonly slug: DocSlug;
+	readonly title: string;
+	readonly description?: string;
+	readonly frontmatter: Frontmatter;
+	readonly content: string;
+	readonly rawContent: string;
+	readonly filePath: FilePath;
+	readonly group?: string;
+	readonly order: number;
+	readonly toc: readonly TocItem[];
+	readonly metadata: PageMetadata;
+}
+/** Reads raw file contents from disk. */
+interface FileReader {
+	read(filePath: FilePath): Promise<Result<string, AppError>>;
+	exists(filePath: FilePath): Promise<boolean>;
+	stat(filePath: FilePath): Promise<Result<{
+		mtimeMs: number;
+		size: number;
+	}, AppError>>;
+}
+/** Reads directory entries, recursively. */
+interface DirectoryScanner {
+	list(dirPath: string): Promise<Result<readonly DirectoryEntry[], AppError>>;
+}
+/** A single entry returned by a directory scanner. */
+interface DirectoryEntry {
+	readonly name: string;
+	readonly isDirectory: boolean;
+	readonly path: string;
+}
+/** Watches a directory for file system changes. */
+interface FileWatcher {
+	watch(dir: string, handlers: {
+		onChange: (filePath: string) => void;
+		onError: (err: unknown) => void;
+	}): {
+		close: () => void;
+	};
+}
+type AuthType = "bearer" | "apiKey" | "oauth2";
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+interface ApiEndpoint {
+	readonly method: HttpMethod;
+	readonly path: string;
+	readonly description: string;
+	readonly group: string;
+	readonly requiresAuth?: boolean;
+	readonly requestBody?: {
+		readonly description: string;
+		readonly example?: string;
+		readonly schema?: Record<string, unknown>;
+	};
+	readonly response?: {
+		readonly description: string;
+		readonly example?: string;
+		readonly schema?: Record<string, unknown>;
+	};
+	readonly queryParams?: readonly {
+		readonly name: string;
+		readonly type: string;
+		readonly description: string;
+		readonly required?: boolean;
+		readonly default?: string;
+	}[];
+	readonly pathParams?: readonly {
+		readonly name: string;
+		readonly type: string;
+		readonly description: string;
+	}[];
+	readonly headers?: readonly {
+		readonly name: string;
+		readonly type: string;
+		readonly description: string;
+		readonly required?: boolean;
+	}[];
+}
+interface ThemeConfig {
+	readonly primaryColor?: string;
+	readonly darkMode?: boolean;
+	readonly accentColor?: string;
+	readonly codeTheme?: string;
+}
+interface SiteConfig {
+	readonly title: string;
+	readonly description: string;
+	readonly logo?: string;
+	readonly logoDark?: string;
+	readonly github?: string;
+	readonly twitter?: string;
+	readonly version?: string;
+}
+interface ApiConfig {
+	readonly baseUrl: string;
+	readonly authType: AuthType;
+	readonly authHeader?: string;
+	readonly defaultHeaders?: Record<string, string>;
+	readonly testerEnabled?: boolean;
+	readonly endpoints?: readonly ApiEndpoint[];
+}
+interface SearchConfig {
+	readonly enabled?: boolean;
+	readonly placeholder?: string;
+	readonly shortcuts?: readonly string[];
+}
+interface EditLinkConfig {
+	readonly enabled?: boolean;
+	readonly baseUrl?: string;
+	readonly branch?: string;
+}
+interface LastUpdatedConfig {
+	readonly enabled?: boolean;
+	readonly format?: string;
+}
+interface DocsConfig {
+	readonly site: SiteConfig;
+	readonly nav: readonly NavSection[];
+	readonly sidebar: readonly SidebarGroup[];
+	readonly theme?: ThemeConfig;
+	readonly api?: ApiConfig;
+	readonly search?: SearchConfig;
+	readonly editLink?: EditLinkConfig;
+	readonly lastUpdated?: LastUpdatedConfig;
+}
+/** Plugin-specific options layered on top of DocsConfig. */
+interface DocsPluginOptions {
+	readonly docsDir?: string;
+	readonly baseRoute?: string;
+}
+type ResolvedDocsConfig = DocsConfig & {
+	readonly docsDir: string;
+	readonly baseRoute: string;
+};
+type UserConfig = Partial<DocsConfig> & DocsPluginOptions;
+/** Loads a DocsConfig from a project file (e.g. docs/docs.config.ts). */
+interface ConfigLoader {
+	load(cwd: string, configPath: string): Promise<Result<Partial<DocsConfig> | null, AppError>>;
+}
+declare const createNodeConfigLoader: () => ConfigLoader;
+interface DocsLoader {
+	loadAll(config: ResolvedDocsConfig): Promise<Result<readonly DocPage[], AppError>>;
+}
+interface DocsWatcher {
+	watch(docsDir: string, onChange: (filePath: string) => void): {
+		close: () => void;
+	};
+}
+declare const createFsDocsLoader: () => DocsLoader;
+interface MemoryFileSystem {
+	readonly files: ReadonlyMap<string, string>;
+	readonly directories: ReadonlyMap<string, readonly string[]>;
+}
+declare const memoryFileSystem: (files: ReadonlyMap<string, string>, directories: ReadonlyMap<string, readonly string[]>) => MemoryFileSystem;
+declare const createMemoryFileReader: (fs: MemoryFileSystem) => FileReader;
+declare const createMemoryDirectoryScanner: (fs: MemoryFileSystem) => DirectoryScanner;
+declare const nodeFileReader: FileReader;
+declare const nodeDirectoryScanner: DirectoryScanner;
+declare const nodeFileWatcher: FileWatcher;
+declare const createNodeDocsWatcher: () => DocsWatcher;
+type CodeBlock = unknown;
+type CodeBlockOptions = unknown;
+declare const enhanceCodeBlocks: () => null;
+type ApiConfig2 = unknown;
+type ApiEndpoint2 = unknown;
+type AuthType2 = unknown;
+type DocsConfig2 = unknown;
+type DocsPluginOptions2 = unknown;
+type EditLinkConfig2 = unknown;
+type HttpMethod2 = unknown;
+type LastUpdatedConfig2 = unknown;
+type ResolvedDocsConfig2 = unknown;
+type SearchConfig2 = unknown;
+type SiteConfig2 = unknown;
+type ThemeConfig2 = unknown;
+declare const defaultDocsConfig2: () => null;
+declare const resolveConfig2: () => null;
+declare const validateDocsConfig2: () => null;
+type BadgeVariant3 = unknown;
+type DocFile2 = unknown;
+type DocId2 = unknown;
+type DocPage2 = unknown;
+type DocSlug2 = unknown;
+type FilePath2 = unknown;
+type Frontmatter2 = unknown;
+type ParsedContent2 = unknown;
+declare const buildDocPage2: () => null;
+declare const buildDocPageFromRaw2: () => null;
+declare const parseFrontmatter2: () => null;
+type ContentValidator = unknown;
+type ValidationError = unknown;
+type ValidationOptions = unknown;
+type ValidationResult = unknown;
+declare const validate: () => null;
+type CommitOptions2 = unknown;
+type GitAdapter2 = unknown;
+type GitStatus2 = unknown;
+type PushOptions2 = unknown;
+declare const commitAndPush: () => null;
+declare const loadEditorState: () => null;
+declare const saveFile: () => null;
+type NavItem2 = unknown;
+type NavSection2 = unknown;
+type Sidebar2 = unknown;
+type SidebarGroup2 = unknown;
+type SidebarItem2 = unknown;
+declare const buildNav2: () => null;
+declare const buildSidebar2: () => null;
+declare const formatGroupTitle2: () => null;
+declare const groupDocsByFolder2: () => null;
+type VirtualModuleSet2 = unknown;
+declare const buildVirtualModules2: () => null;
+declare const isMarkdownPath2: () => null;
+declare const isVirtualDocsModule2: () => null;
+import { Plugin } from "vite";
+type WatchMode = "native" | "polling";
+interface DocsPluginConfig extends Partial<UserConfig> {
+	/** Optional: explicit config object passed by the consumer. */
+	readonly userConfig?: UserConfig;
+	/** Optional: pre-resolved plugin options override. */
+	readonly options?: DocsPluginOptions;
+	/** Force a full browser reload on HMR (default: false, granular invalidation). */
+	readonly fullReload?: boolean;
+	/** Watcher mode. Default: 'native'. Use 'polling' for Linux subdir reliability. */
+	readonly watchMode?: WatchMode;
+	/** Polling interval in ms when watchMode='polling'. Default: 300. */
+	readonly pollingIntervalMs?: number;
+	/** Per-page transformation hook. Invoked after parse, before serialisation. */
+	readonly transformPage?: (page: DocPage) => DocPage | Promise<DocPage>;
+}
+declare const docsPlugin: (cfg?: DocsPluginConfig) => Plugin;
+type MarkdownToSvelte = (raw: string, deps: {
+	readonly parse: (content: string) => Promise<unknown>;
+}) => Promise<string>;
+declare const transformMarkdown: MarkdownToSvelte;
+type SearchEntry2 = unknown;
+type SearchIndex2 = unknown;
+declare const buildSearchIndex2: () => null;
+declare const indexPages2: () => null;
+declare const pageToSearchEntry2: () => null;
+declare const search2: () => null;
+type MetaTagGenerator = unknown;
+type MetaTags = unknown;
+type SeoOptions = unknown;
+declare const optimizeSeo: () => null;
+/**
+* Compile-time static constants. These are the only safe values
+* to import in the domain layer (where I/O is forbidden).
+*/
+declare const DEFAULT_DOCS_DIR: "docs";
+declare const DEFAULT_BASE_ROUTE: "/docs";
+declare const VIRTUAL_PREFIX: "virtual:docs/";
+declare const PLUGIN_NAME: "vite-plugin-docs";
+declare const SUPPORTED_EXTENSIONS: readonly [".md", ".mdoc"];
+/**
+* TOC Generator Types
+*
+* Domain types for table of contents generation
+*/
+/**
+* TOC item
+*/
+interface TocItem2 {
+	/** Heading text */
+	text: string;
+	/** Heading level (1-6) */
+	level: number;
+	/** Anchor ID */
+	id: string;
+	/** Child items */
+	children?: TocItem2[];
+}
+/**
+* TOC options
+*/
+interface TocOptions {
+	/** Max depth */
+	maxDepth?: number;
+	/** Min depth */
+	minDepth?: number;
+	/** Include headings */
+	include?: string[];
+	/** Exclude headings */
+	exclude?: string[];
+}
+/** Content parser port */
+interface ContentParser2 {
+	parse: (raw: string) => unknown;
+}
+/**
+* Generate TOC from markdown content
+*/
+declare const generateToc: (content: string, options?: TocOptions) => TocItem2[];
+/**
+* Generate flat TOC from markdown content
+*/
+declare const generateFlatToc: (content: string, options?: TocOptions) => TocItem2[];
+export { ApiConfig2 as ApiConfig, ApiEndpoint2 as ApiEndpoint, AuthType2 as AuthType, BadgeVariant3 as BadgeVariant, Brand, CodeBlock, CodeBlockOptions, CommitOptions2 as CommitOptions, ContentParser2 as ContentParser, ContentValidator, DEFAULT_BASE_ROUTE, DEFAULT_DOCS_DIR, DocFile2 as DocFile, DocId2 as DocId, DocPage2 as DocPage, DocSlug2 as DocSlug, DocsConfig2 as DocsConfig, DocsPluginConfig, DocsPluginOptions2 as DocsPluginOptions, EditLinkConfig2 as EditLinkConfig, Either, FilePath2 as FilePath, Frontmatter2 as Frontmatter, GitAdapter2 as GitAdapter, GitStatus2 as GitStatus, HttpMethod2 as HttpMethod, LastUpdatedConfig2 as LastUpdatedConfig, MetaTagGenerator, MetaTags, NavItem2 as NavItem, NavSection2 as NavSection, Option, PLUGIN_NAME, ParsedContent2 as ParsedContent, PushOptions2 as PushOptions, ResolvedDocsConfig2 as ResolvedDocsConfig, Result, SUPPORTED_EXTENSIONS, SearchConfig2 as SearchConfig, SearchEntry2 as SearchEntry, SearchIndex2 as SearchIndex, SeoOptions, Sidebar2 as Sidebar, SidebarGroup2 as SidebarGroup, SidebarItem2 as SidebarItem, SiteConfig2 as SiteConfig, ThemeConfig2 as ThemeConfig, TocItem2 as TocItem, TocOptions, VIRTUAL_PREFIX, ValidationError, ValidationOptions, ValidationResult, VirtualModuleSet2 as VirtualModuleSet, buildDocPage2 as buildDocPage, buildDocPageFromRaw2 as buildDocPageFromRaw, buildNav2 as buildNav, buildSearchIndex2 as buildSearchIndex, buildSidebar2 as buildSidebar, buildVirtualModules2 as buildVirtualModules, commitAndPush, createFsDocsLoader, createMemoryDirectoryScanner, createMemoryFileReader, createNodeConfigLoader, createNodeDocsWatcher, docsPlugin as default, defaultDocsConfig2 as defaultDocsConfig, docsPlugin, enhanceCodeBlocks, err, formatGroupTitle2 as formatGroupTitle, generateFlatToc, generateToc, groupDocsByFolder2 as groupDocsByFolder, indexPages2 as indexPages, isErr, isMarkdownPath2 as isMarkdownPath, isNone, isOk, isSome, isVirtualDocsModule2 as isVirtualDocsModule, left, loadEditorState, memoryFileSystem, nodeDirectoryScanner, nodeFileReader, nodeFileWatcher, none, ok, optimizeSeo, pageToSearchEntry2 as pageToSearchEntry, parseFrontmatter2 as parseFrontmatter, resolveConfig2 as resolveConfig, right, saveFile, search2 as search, some, transformMarkdown, validate, validateDocsConfig2 as validateDocsConfig };