@wrikka/create-docs 0.1.0

package/src/modules/navigation/index.ts

@@ -0,0 +1,15 @@
+export * from "./application/usecases";
+export {
+	navGenerated,
+	navRebuilt,
+	sidebarGroupBuilt,
+} from "./domain/events";
+export * from "./domain/operations";
+export {
+	validateNavItem,
+	validateNavSection,
+	validateSidebarGroup,
+	validateSidebarItem,
+} from "./domain/validators";
+export type { ContentSource } from "./ports";
+export * from "./types/public";

package/src/modules/navigation/ports/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Navigation module ports — interfaces to other modules (no I/O).
+ */
+import type { DocFile } from "@create-docs/modules/content";
+
+/** Read access to the content module's scanned files. */
+export interface ContentSource {
+	readonly allFiles: () => readonly DocFile[];
+}

package/src/modules/navigation/types/index.ts

@@ -0,0 +1,38 @@
+import type { Brand } from "@create-docs/shared/types";
+
+export type NavItemHref = Brand<string, "NavItemHref">;
+export const NavItemHref = (s: string): NavItemHref => s as NavItemHref;
+
+export type BadgeVariant = "default" | "success" | "warning" | "danger";
+
+export interface NavItem {
+	readonly label: string;
+	readonly href?: string;
+	readonly items?: readonly NavItem[];
+	readonly badge?: string;
+	readonly icon?: string;
+}
+
+export interface NavSection {
+	readonly title: string;
+	readonly items: readonly NavItem[];
+}
+
+export interface SidebarItem {
+	readonly title: string;
+	readonly slug: string;
+	readonly badge?: string;
+	readonly badgeVariant?: BadgeVariant;
+	readonly items?: readonly SidebarItem[];
+}
+
+export interface SidebarGroup {
+	readonly title: string;
+	readonly icon?: string;
+	readonly items: readonly SidebarItem[];
+	readonly collapsed?: boolean;
+}
+
+export interface Sidebar {
+	readonly groups: readonly SidebarGroup[];
+}

package/src/modules/navigation/types/public.ts

@@ -0,0 +1,9 @@
+export type {
+	BadgeVariant,
+	NavItem,
+	NavItemHref,
+	NavSection,
+	Sidebar,
+	SidebarGroup,
+	SidebarItem,
+} from "./index";

package/src/modules/openapi/application/swagger-parser-adapter.ts

@@ -0,0 +1,178 @@
+/**
+ * Swagger-parser adapter implementation.
+ * Provides OpenAPI 3 schema parsing and validation using js-yaml and native fetch.
+ */
+
+import { parseError } from "@create-docs/shared/errors";
+import { JSON_SCHEMA, load } from "js-yaml";
+import type { OpenApiParserPort } from "../ports/openapi-parser-port";
+import type {
+	OpenApiEndpoint,
+	OpenApiMediaType,
+	OpenApiParameter,
+	OpenApiRequestBody,
+	OpenApiResponse,
+} from "../types/openapi";
+
+const loadRaw = async (source: string): Promise<string> => {
+	if (/^https?:\/\//i.test(source)) {
+		const response = await fetch(source);
+		if (!response.ok) {
+			throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+		}
+		return response.text();
+	}
+
+	if (source.startsWith("file://")) {
+		return Bun.file(source.slice(7)).text();
+	}
+
+	if (/\.(?:yaml|yml|json)$/i.test(source)) {
+		try {
+			return await Bun.file(source).text();
+		} catch {
+			// Fall through and treat the source as raw text.
+		}
+	}
+
+	return source;
+};
+
+const parseText = (raw: string): unknown => {
+	const text = raw.trim();
+	if (text.startsWith("{") || text.startsWith("[")) {
+		return JSON.parse(text);
+	}
+	return load(text, { schema: JSON_SCHEMA });
+};
+
+const toParameter = (value: unknown): OpenApiParameter => {
+	const p = value as Record<string, unknown>;
+	return {
+		name: typeof p.name === "string" ? p.name : "",
+		in: (p.in as OpenApiParameter["in"]) ?? "query",
+		required: Boolean(p.required),
+		schema: p.schema,
+		description: typeof p.description === "string" ? p.description : undefined,
+	};
+};
+
+const toMediaTypes = (
+	value: unknown,
+): Readonly<Record<string, OpenApiMediaType>> => {
+	if (!value || typeof value !== "object") return {};
+	const record: Record<string, OpenApiMediaType> = {};
+	for (const [key, media] of Object.entries(value as Record<string, unknown>)) {
+		const m = media as Record<string, unknown>;
+		record[key] = {
+			schema: m?.schema,
+			example: m?.example,
+		};
+	}
+	return record;
+};
+
+const toRequestBody = (value: unknown): OpenApiRequestBody => {
+	const body = value as Record<string, unknown>;
+	return {
+		description:
+			typeof body.description === "string" ? body.description : undefined,
+		required: Boolean(body.required),
+		content: toMediaTypes(body.content),
+	};
+};
+
+const toResponses = (
+	value: unknown,
+): Readonly<Record<string, OpenApiResponse>> => {
+	if (!value || typeof value !== "object") return {};
+	const record: Record<string, OpenApiResponse> = {};
+	for (const [code, response] of Object.entries(
+		value as Record<string, unknown>,
+	)) {
+		const r = response as Record<string, unknown>;
+		record[code] = {
+			description: typeof r.description === "string" ? r.description : "",
+			content: toMediaTypes(r.content),
+		};
+	}
+	return record;
+};
+
+const extractEndpoints = (
+	spec: Record<string, unknown>,
+): readonly OpenApiEndpoint[] => {
+	const paths = spec.paths as Record<string, unknown> | undefined;
+	if (!paths || typeof paths !== "object") return [];
+
+	const endpoints: OpenApiEndpoint[] = [];
+	const methods = new Set(["GET", "POST", "PUT", "DELETE", "PATCH"]);
+
+	for (const [path, operations] of Object.entries(paths)) {
+		if (!operations || typeof operations !== "object") continue;
+
+		for (const [method, operation] of Object.entries(
+			operations as Record<string, unknown>,
+		)) {
+			const upperMethod = method.toUpperCase();
+			if (!methods.has(upperMethod)) continue;
+
+			const op = operation as Record<string, unknown> | undefined;
+			if (!op) continue;
+
+			const parameters = Array.isArray(op.parameters)
+				? op.parameters.map(toParameter)
+				: [];
+
+			endpoints.push({
+				method: upperMethod as OpenApiEndpoint["method"],
+				path,
+				summary: typeof op.summary === "string" ? op.summary : undefined,
+				description:
+					typeof op.description === "string" ? op.description : undefined,
+				parameters,
+				requestBody:
+					op.requestBody && typeof op.requestBody === "object"
+						? toRequestBody(op.requestBody)
+						: undefined,
+				responses: toResponses(op.responses),
+			});
+		}
+	}
+
+	return endpoints;
+};
+
+export const createSwaggerParserAdapter = (): OpenApiParserPort => ({
+	parse: async (source: string) => {
+		try {
+			const raw = await loadRaw(source);
+			const parsed = parseText(raw) as Record<string, unknown>;
+			return extractEndpoints(parsed);
+		} catch (error) {
+			throw parseError(source, "Failed to parse OpenAPI spec", error);
+		}
+	},
+
+	validate: async (schema: unknown) => {
+		if (Array.isArray(schema)) {
+			return schema.every(
+				(item) =>
+					item &&
+					typeof (item as Record<string, unknown>).method === "string" &&
+					typeof (item as Record<string, unknown>).path === "string",
+			);
+		}
+
+		if (typeof schema !== "object" || schema === null) {
+			return false;
+		}
+
+		const s = schema as Record<string, unknown>;
+		return (
+			("openapi" in s || "swagger" in s) &&
+			typeof s.paths === "object" &&
+			s.paths !== null
+		);
+	},
+});

package/src/modules/openapi/domain/operations/parse-openapi.ts

@@ -0,0 +1,46 @@
+/**
+ * Pure OpenAPI parser operations.
+ * No I/O. No exceptions thrown. Returns Result types.
+ */
+
+import type { Result } from "@create-docs/shared/types";
+import { err, ok } from "@create-docs/shared/types";
+import type { OpenApiEndpoint } from "../../types/openapi";
+
+export type OpenApiParseError = {
+	readonly kind: "openapi-parse-error";
+	readonly message: string;
+};
+
+/**
+ * Parse OpenAPI 3 schema to typed endpoints.
+ */
+export const parseOpenApiSchema = (
+	_schema: unknown,
+): Result<readonly OpenApiEndpoint[], OpenApiParseError> => {
+	try {
+		// This will be implemented via adapter (swagger-parser)
+		// For now, return empty array
+		return ok([]);
+	} catch (error) {
+		return err({
+			kind: "openapi-parse-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Convert OpenAPI endpoint to internal ApiEndpoint format.
+ */
+export const openApiToApiEndpoint = (endpoint: OpenApiEndpoint): unknown => {
+	return {
+		method: endpoint.method,
+		path: endpoint.path,
+		summary: endpoint.summary,
+		description: endpoint.description,
+		parameters: endpoint.parameters,
+		requestBody: endpoint.requestBody,
+		responses: endpoint.responses,
+	};
+};

package/src/modules/openapi/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public API for the openapi module.
+ */
+
+export { createSwaggerParserAdapter } from "./application/swagger-parser-adapter";
+export * from "./domain/operations/parse-openapi";
+export * from "./ports/openapi-parser-port";
+export * from "./types/openapi";

package/src/modules/openapi/ports/openapi-parser-port.ts

@@ -0,0 +1,15 @@
+/**
+ * Port for OpenAPI parsing operations.
+ */
+
+export type OpenApiParserPort = {
+	/**
+	 * Parse OpenAPI 3 schema from file or URL.
+	 */
+	readonly parse: (source: string) => Promise<unknown>;
+
+	/**
+	 * Validate OpenAPI 3 schema.
+	 */
+	readonly validate: (schema: unknown) => Promise<boolean>;
+};

package/src/modules/openapi/types/openapi.ts

@@ -0,0 +1,37 @@
+/**
+ * OpenAPI types for API documentation import.
+ */
+
+export type OpenApiEndpoint = {
+	readonly method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+	readonly path: string;
+	readonly summary?: string;
+	readonly description?: string;
+	readonly parameters?: readonly OpenApiParameter[];
+	readonly requestBody?: OpenApiRequestBody;
+	readonly responses?: Readonly<Record<string, OpenApiResponse>>;
+};
+
+export type OpenApiParameter = {
+	readonly name: string;
+	readonly in: "query" | "path" | "header" | "cookie";
+	readonly required: boolean;
+	readonly schema?: unknown;
+	readonly description?: string;
+};
+
+export type OpenApiRequestBody = {
+	readonly description?: string;
+	readonly required: boolean;
+	readonly content?: Readonly<Record<string, OpenApiMediaType>>;
+};
+
+export type OpenApiMediaType = {
+	readonly schema?: unknown;
+	readonly example?: unknown;
+};
+
+export type OpenApiResponse = {
+	readonly description: string;
+	readonly content?: Readonly<Record<string, OpenApiMediaType>>;
+};

package/src/modules/plugin/application/usecases/build-virtual-modules.ts

@@ -0,0 +1,53 @@
+/**
+ * Use case: build all virtual module source codes from a resolved config and pages.
+ * Returns a pure data structure (no Vite coupling).
+ */
+
+import type { ResolvedDocsConfig } from "@create-docs/modules/config";
+import type { DocPage } from "@create-docs/modules/content";
+import type { NavSection, SidebarGroup } from "@create-docs/modules/navigation";
+import type { SearchIndex } from "@create-docs/modules/search";
+import type { AppError } from "@create-docs/shared/errors";
+import { ok, type Result } from "@create-docs/shared/types/result";
+import {
+	buildConfigModule,
+	buildDocsDataModule,
+	buildNavModule,
+	buildSearchIndexModule,
+	buildSidebarModule,
+} from "../../domain/operations/build-virtual";
+
+export interface VirtualModuleSet {
+	readonly "virtual:docs/data": string;
+	readonly "virtual:docs/sidebar": string;
+	readonly "virtual:docs/nav": string;
+	readonly "virtual:docs/search-index": string;
+	readonly "virtual:docs/config": string;
+}
+
+export interface BuildVirtualModulesInput {
+	readonly config: ResolvedDocsConfig;
+	readonly pages: readonly DocPage[];
+	readonly sidebar: readonly SidebarGroup[];
+	readonly nav: readonly NavSection[];
+	readonly searchIndex: SearchIndex;
+}
+
+export type BuildVirtualModules = (
+	input: BuildVirtualModulesInput,
+) => Result<VirtualModuleSet, AppError>;
+
+export const buildVirtualModules: BuildVirtualModules = ({
+	config,
+	pages,
+	sidebar,
+	nav,
+	searchIndex,
+}) =>
+	ok({
+		"virtual:docs/data": buildDocsDataModule(pages),
+		"virtual:docs/sidebar": buildSidebarModule(sidebar),
+		"virtual:docs/nav": buildNavModule(nav),
+		"virtual:docs/search-index": buildSearchIndexModule(searchIndex),
+		"virtual:docs/config": buildConfigModule(config),
+	});

package/src/modules/plugin/application/usecases/index.ts

@@ -0,0 +1 @@
+export { buildVirtualModules } from "./build-virtual-modules";

package/src/modules/plugin/application/workflows/build-docs.ts

@@ -0,0 +1,79 @@
+/**
+ * Use case: full docs build pipeline. Orchestrates:
+ *   1. scan docs dir → DocFile[]
+ *   2. load+parse each file → DocPage[]
+ *   3. build sidebar, nav, search index
+ *   4. produce virtual module source codes
+ *
+ * All I/O is delegated through ports; this function is fully testable with in-memory adapters.
+ */
+
+import type { ResolvedDocsConfig } from "@create-docs/modules/config";
+import { processDocsWorkflow } from "@create-docs/modules/content";
+import { buildNav, buildSidebar } from "@create-docs/modules/navigation";
+import { indexPages } from "@create-docs/modules/search";
+import type { AppError } from "@create-docs/shared/errors";
+import { ok, type Result } from "@create-docs/shared/types/result";
+import type { DocsLoader } from "../../ports";
+import {
+	buildVirtualModules,
+	type VirtualModuleSet,
+} from "../usecases/build-virtual-modules";
+
+export interface BuildDocsInput {
+	readonly config: ResolvedDocsConfig;
+	readonly loader: DocsLoader;
+	/** Optional page transformation hook. Invoked on each page after parsing. */
+	readonly transformPage?: (
+		page: import("@create-docs/modules/content").DocPage,
+	) =>
+		| import("@create-docs/modules/content").DocPage
+		| Promise<import("@create-docs/modules/content").DocPage>;
+}
+
+export type BuildDocs = (
+	input: BuildDocsInput,
+) => Promise<Result<VirtualModuleSet, AppError>>;
+
+export const buildDocs: BuildDocs = async ({
+	config,
+	loader,
+	transformPage,
+}) => {
+	const loaded = await loader.loadAll(config);
+	if (!loaded.ok) return loaded;
+	let pages = loaded.value;
+
+	// Optional page transformation hook
+	if (transformPage) {
+		const next: import("@create-docs/modules/content").DocPage[] = [];
+		for (const p of pages) next.push(await transformPage(p));
+		pages = next;
+	}
+
+	// Sidebar: prefer explicit config, otherwise auto-generate from pages
+	const sidebarResult = buildSidebar({
+		configured: config.sidebar,
+		pages,
+	});
+	if (!sidebarResult.ok) return sidebarResult;
+	const sidebar = sidebarResult.value;
+
+	// Nav from config
+	const navResult = buildNav(config.nav);
+	if (!navResult.ok) return navResult;
+	const nav = navResult.value;
+
+	// Search index
+	const searchResult = indexPages(pages);
+	if (!searchResult.ok) return searchResult;
+	const searchIndex = searchResult.value;
+
+	const vms = buildVirtualModules({ config, pages, sidebar, nav, searchIndex });
+	if (!vms.ok) return vms;
+
+	return ok(vms.value);
+};
+
+// Re-export for backwards-compat with adapter layer
+export { processDocsWorkflow };

package/src/modules/plugin/application/workflows/index.ts

@@ -0,0 +1 @@
+export * from "../workflows/build-docs";

package/src/modules/plugin/domain/events/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Plugin module domain events.
+ */
+
+import type { ResolvedDocsConfig } from "@create-docs/modules/config";
+
+export type PluginEvent =
+	| { readonly type: "plugin.initialized"; readonly config: ResolvedDocsConfig }
+	| {
+			readonly type: "plugin.config_resolved";
+			readonly docsDir: string;
+			readonly baseRoute: string;
+	  }
+	| {
+			readonly type: "plugin.virtual_module_emitted";
+			readonly id: string;
+			readonly bytes: number;
+	  }
+	| { readonly type: "plugin.file_watched"; readonly path: string }
+	| { readonly type: "plugin.reloaded"; readonly pages: number }
+	| {
+			readonly type: "plugin.error";
+			readonly phase: "init" | "scan" | "transform" | "watch";
+			readonly message: string;
+	  };
+
+export const pluginInitialized = (config: ResolvedDocsConfig): PluginEvent => ({
+	type: "plugin.initialized",
+	config,
+});
+export const pluginConfigResolved = (
+	docsDir: string,
+	baseRoute: string,
+): PluginEvent => ({
+	type: "plugin.config_resolved",
+	docsDir,
+	baseRoute,
+});
+export const pluginVirtualModuleEmitted = (
+	id: string,
+	bytes: number,
+): PluginEvent => ({
+	type: "plugin.virtual_module_emitted",
+	id,
+	bytes,
+});
+export const pluginFileWatched = (path: string): PluginEvent => ({
+	type: "plugin.file_watched",
+	path,
+});
+export const pluginReloaded = (pages: number): PluginEvent => ({
+	type: "plugin.reloaded",
+	pages,
+});
+export const pluginError = (
+	phase: "init" | "scan" | "transform" | "watch",
+	message: string,
+): PluginEvent => ({
+	type: "plugin.error",
+	phase,
+	message,
+});

package/src/modules/plugin/domain/models/index.ts

@@ -0,0 +1 @@
+export type { PluginContext, PluginHooks } from "../../types";

package/src/modules/plugin/domain/operations/build-virtual.ts

@@ -0,0 +1,76 @@
+/**
+ * Pure operations for generating virtual module source code (Vite-loadable ESM).
+ * No I/O, no exceptions. Returns strings ready to be emitted as virtual module code.
+ */
+
+import type { ResolvedDocsConfig } from "@create-docs/modules/config";
+import type { DocPage, FilePath } from "@create-docs/modules/content";
+import type { NavSection, SidebarGroup } from "@create-docs/modules/navigation";
+import {
+	VIRTUAL_DATA,
+	VIRTUAL_NAV,
+	VIRTUAL_SEARCH_INDEX,
+	VIRTUAL_SIDEBAR,
+} from "@create-docs/modules/plugin/types";
+import type { SearchIndex } from "@create-docs/modules/search";
+import { isString } from "@create-docs/shared/utils/object";
+
+const serializeForESM = (value: unknown): string =>
+	JSON.stringify(value, replacer, 2);
+
+const replacer = (_key: string, value: unknown): unknown => {
+	if (value === undefined) return undefined;
+	return value;
+};
+
+export const buildDocsDataModule = (pages: readonly DocPage[]): string => {
+	const exported = pages.map((p) => ({
+		id: String(p.id),
+		slug: String(p.slug),
+		title: p.title,
+		description: p.description,
+		frontmatter: p.frontmatter,
+		rawContent: p.rawContent,
+		content: p.content,
+		filePath: String(p.filePath),
+	}));
+	return `export const docsData = ${serializeForESM(exported)};`;
+};
+
+export const buildSidebarModule = (groups: readonly SidebarGroup[]): string =>
+	`export const sidebar = ${serializeForESM(groups)};`;
+
+export const buildNavModule = (sections: readonly NavSection[]): string =>
+	`export const nav = ${serializeForESM(sections)};`;
+
+export const buildSearchIndexModule = (index: SearchIndex): string =>
+	`export const searchIndex = ${serializeForESM(index.entries)};`;
+
+export const buildConfigModule = (
+	config: ResolvedDocsConfig,
+): string => `export const docsConfig = ${serializeForESM(config)};
+export const site = ${serializeForESM(config.site)};
+export const nav = ${serializeForESM(config.nav)};
+export const sidebar = ${serializeForESM(config.sidebar)};
+export const api = ${serializeForESM(config.api)};
+export const search = ${serializeForESM(config.search)};
+export const editLink = ${serializeForESM(config.editLink)};
+export const lastUpdated = ${serializeForESM(config.lastUpdated)};`;
+
+export const resolveVirtualModule = (id: string): string | undefined => {
+	if (id === VIRTUAL_DATA) return "data";
+	if (id === VIRTUAL_SIDEBAR) return "sidebar";
+	if (id === VIRTUAL_NAV) return "nav";
+	if (id === VIRTUAL_SEARCH_INDEX) return "search-index";
+	return undefined;
+};
+
+export const isVirtualDocsModule = (id: string): boolean =>
+	id.startsWith("virtual:docs/");
+
+export const pathToFilePath = (p: string): FilePath => p as unknown as FilePath;
+
+export const isMarkdownPath = (p: string): boolean => {
+	if (!isString(p)) return false;
+	return p.endsWith(".md") || p.endsWith(".mdoc");
+};

package/src/modules/plugin/domain/operations/index.ts

@@ -0,0 +1,11 @@
+export {
+	buildConfigModule,
+	buildDocsDataModule,
+	buildNavModule,
+	buildSearchIndexModule,
+	buildSidebarModule,
+	isMarkdownPath,
+	isVirtualDocsModule,
+	pathToFilePath,
+	resolveVirtualModule,
+} from "./build-virtual";

package/src/modules/plugin/domain/validators/index.ts

@@ -0,0 +1,30 @@
+// Plugin Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import type { ResolvedDocsConfig } from "@create-docs/modules/config";
+import { pluginError } from "@create-docs/shared/errors";
+import { err, ok, type Result } from "@create-docs/shared/types/result";
+import { type Type, type } from "arktype";
+
+/**
+ * Resolved Config Schema
+ */
+export const resolvedConfigSchema: Type = type({
+	docsDir: "string >= 1",
+	baseRoute: "string >= 1",
+});
+
+export type ResolvedConfigSchema = typeof resolvedConfigSchema.infer;
+
+/**
+ * Validate resolved config using Arktype
+ */
+export const validateResolvedConfig = (
+	c: ResolvedDocsConfig,
+): Result<ResolvedDocsConfig, ReturnType<typeof pluginError>> => {
+	const result = resolvedConfigSchema(c);
+	if (result instanceof type.errors) {
+		return err(pluginError(result.summary, { path: "docsDir" }));
+	}
+	return ok(c);
+};