@wrikka/create-docs 0.1.0

package/src/index.ts

@@ -0,0 +1,174 @@
+/**
+ * create-docs — Public API
+ *
+ * Vite plugin for documentation sites, built on Functional Clean Architecture
+ * with Vertical Slice Architecture. SolidJS-only support.
+ *
+ * ## Layer Map
+ *   - `src/shared/`     — pure utilities, types, errors (no dependencies)
+ *   - `src/modules/`    — feature modules (content, navigation, search, config, plugin)
+ *   - `src/adapters/`   — I/O implementations (Node FS, Vite, config loader)
+ *   - `src/presentation/` — entry points (Vite plugin, Solid components)
+ *
+ * ## Quick Start
+ *   ```ts
+ *   import { docsPlugin } from 'create-docs';
+ *
+ *   export default defineConfig({
+ *     plugins: [docsPlugin({ site: { title: 'My Docs' } })]
+ *   });
+ *   ```
+ */
+
+// --- Adapters (advanced usage) ---
+export {
+	createFsDocsLoader,
+	createMemoryDirectoryScanner,
+	createMemoryFileReader,
+	createNodeConfigLoader,
+	createNodeDocsWatcher,
+	memoryFileSystem,
+	nodeDirectoryScanner,
+	nodeFileReader,
+	nodeFileWatcher,
+} from "./adapters";
+export type {
+	CodeBlock,
+	CodeBlockOptions,
+} from "./code-block-enhancements";
+// --- Code Block Enhancements ---
+export { enhanceCodeBlocks } from "./code-block-enhancements";
+export type {
+	ApiConfig,
+	ApiEndpoint,
+	AuthType,
+	DocsConfig,
+	DocsPluginOptions,
+	EditLinkConfig,
+	HttpMethod,
+	LastUpdatedConfig,
+	ResolvedDocsConfig,
+	SearchConfig,
+	SiteConfig,
+	ThemeConfig,
+} from "./config";
+// --- Config (default + types + operations) ---
+export {
+	defaultDocsConfig,
+	resolveConfig,
+	validateDocsConfig,
+} from "./config";
+export type {
+	BadgeVariant,
+	DocFile,
+	DocId,
+	DocPage,
+	DocSlug,
+	FilePath,
+	Frontmatter,
+	ParsedContent,
+} from "./content";
+// --- Content (pages, frontmatter, parsing) ---
+export {
+	buildDocPage,
+	buildDocPageFromRaw,
+	parseFrontmatter,
+} from "./content";
+export type {
+	ContentValidator,
+	ValidationError,
+	ValidationOptions,
+	ValidationResult,
+} from "./content-validation";
+// --- Content Validation ---
+export { validate } from "./content-validation";
+export type {
+	CommitOptions,
+	GitAdapter,
+	GitStatus,
+	PushOptions,
+} from "./live-editor";
+// --- Live Editor with Git Integration ---
+export {
+	commitAndPush,
+	loadEditorState,
+	saveFile,
+} from "./live-editor";
+export type {
+	NavItem,
+	NavSection,
+	Sidebar,
+	SidebarGroup,
+	SidebarItem,
+} from "./navigation";
+// --- Navigation (sidebar, nav) — canonical owner of nav/sidebar types ---
+export {
+	buildNav,
+	buildSidebar,
+	formatGroupTitle,
+	groupDocsByFolder,
+} from "./navigation";
+export type { VirtualModuleSet } from "./plugin";
+// --- Plugin module (orchestration) ---
+export {
+	buildVirtualModules,
+	isMarkdownPath,
+	isVirtualDocsModule,
+} from "./plugin";
+export type { DocsPluginConfig } from "./presentation/vite-plugin";
+// --- Presentation (Vite plugin + Solid components) ---
+export {
+	default,
+	docsPlugin,
+	transformMarkdown,
+} from "./presentation/vite-plugin";
+export type { SearchEntry, SearchIndex } from "./search";
+// --- Search (index + query) ---
+export {
+	buildSearchIndex,
+	indexPages,
+	pageToSearchEntry,
+	search,
+} from "./search";
+export type {
+	MetaTagGenerator,
+	MetaTags,
+	SeoOptions,
+} from "./seo-optimization";
+// --- SEO Optimization ---
+export { optimizeSeo } from "./seo-optimization";
+// --- SolidJS UI Components ---
+// Note: Components are in presentation/solid/ directory
+// Import directly in your Solid project
+// --- Constants ---
+export {
+	DEFAULT_BASE_ROUTE,
+	DEFAULT_DOCS_DIR,
+	PLUGIN_NAME,
+	SUPPORTED_EXTENSIONS,
+	VIRTUAL_PREFIX,
+} from "./shared/constants";
+export type { Brand, Either, Option, Result } from "./shared/types";
+// --- Shared (FP primitives — re-exported for downstream modules) ---
+export {
+	err,
+	isErr,
+	isNone,
+	isOk,
+	isSome,
+	left,
+	none,
+	ok,
+	right,
+	some,
+} from "./shared/types";
+export type {
+	ContentParser,
+	TocItem,
+	TocOptions,
+} from "./toc-generator";
+// --- TOC Generator ---
+export {
+	generateFlatToc,
+	generateToc,
+} from "./toc-generator";

package/src/live-editor/index.ts

@@ -0,0 +1,7 @@
+export type CommitOptions = unknown;
+export type GitAdapter = unknown;
+export type GitStatus = unknown;
+export type PushOptions = unknown;
+export const commitAndPush = () => null;
+export const loadEditorState = () => null;
+export const saveFile = () => null;

package/src/modules/analytics/application/plausible-adapter.ts

@@ -0,0 +1,103 @@
+/**
+ * Plausible adapter implementation.
+ * Provides Plausible analytics integration via the REST event API.
+ */
+
+import { configError, pluginError } from "@create-docs/shared/errors";
+import type { AnalyticsPort } from "../ports/analytics-port";
+import type { AnalyticsConfig, AnalyticsEvent } from "../types/analytics";
+
+type PlausibleAnalyticsConfig = AnalyticsConfig & {
+	readonly apiHost?: string;
+	readonly endpoint?: string;
+};
+
+const PLAUSIBLE_DEFAULT_HOST = "https://plausible.io";
+
+export const createPlausibleAdapter = (domain: string): AnalyticsPort => {
+	if (!domain.trim()) {
+		throw configError("Plausible domain is required", {
+			context: { domain },
+			hint: "Pass the site domain to createPlausibleAdapter.",
+		});
+	}
+
+	const resolveApiHost = (
+		config: PlausibleAnalyticsConfig | undefined,
+	): string =>
+		(config?.apiHost ?? config?.endpoint ?? PLAUSIBLE_DEFAULT_HOST).replace(
+			/\/+$/,
+			"",
+		);
+
+	const resolveTrackingEndpoint = (apiHost: string): string =>
+		apiHost.endsWith("/api/event") ? apiHost : `${apiHost}/api/event`;
+
+	const resolveUrl = (event: AnalyticsEvent): string => {
+		if (event.url) return event.url;
+
+		if (typeof location !== "undefined") {
+			return location.href;
+		}
+
+		return `https://${domain}${
+			event.type === "pageview" ? "/" : `/${event.type}`
+		}`;
+	};
+
+	return {
+		track: async (event: unknown, config?: unknown) => {
+			const analyticsEvent = event as AnalyticsEvent;
+			const cfg = config as PlausibleAnalyticsConfig | undefined;
+			const apiHost = resolveApiHost(cfg);
+			const endpoint = resolveTrackingEndpoint(apiHost);
+			const url = resolveUrl(analyticsEvent);
+
+			const payload = {
+				name: analyticsEvent.type,
+				url,
+				domain,
+				props: {
+					...(analyticsEvent.query ? { query: analyticsEvent.query } : {}),
+					...(analyticsEvent.target ? { target: analyticsEvent.target } : {}),
+				},
+			};
+
+			try {
+				const response = await fetch(endpoint, {
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify(payload),
+					keepalive: true,
+				});
+
+				if (!response.ok) {
+					throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+				}
+			} catch (error) {
+				throw pluginError("Plausible tracking failed", {
+					context: { domain, endpoint, event: analyticsEvent },
+					hint: "Verify the Plausible API host is reachable and the domain is correct.",
+					cause: error,
+				});
+			}
+		},
+
+		init: async (config?: unknown) => {
+			const cfg = config as PlausibleAnalyticsConfig | undefined;
+			const apiHost = resolveApiHost(cfg);
+
+			try {
+				const response = await fetch(apiHost, { method: "HEAD" });
+				if (!response.ok && response.status !== 404) {
+					throw new Error(`Host responded with HTTP ${response.status}`);
+				}
+			} catch (error) {
+				throw pluginError("Plausible initialization failed", {
+					context: { domain, apiHost },
+					cause: error,
+				});
+			}
+		},
+	};
+};

package/src/modules/analytics/application/umami-adapter.ts

@@ -0,0 +1,109 @@
+/**
+ * Umami adapter implementation.
+ * Provides Umami analytics integration via the REST tracking API.
+ */
+
+import { configError, pluginError } from "@create-docs/shared/errors";
+import type { AnalyticsPort } from "../ports/analytics-port";
+import type { AnalyticsConfig, AnalyticsEvent } from "../types/analytics";
+
+type UmamiAnalyticsConfig = AnalyticsConfig & {
+	readonly umamiHost?: string;
+	readonly endpoint?: string;
+};
+
+export const createUmamiAdapter = (siteId: string): AnalyticsPort => {
+	if (!siteId.trim()) {
+		throw configError("Umami siteId is required", {
+			context: { siteId },
+			hint: "Pass a valid Umami website ID to createUmamiAdapter.",
+		});
+	}
+
+	const resolveHost = (
+		config: UmamiAnalyticsConfig | undefined,
+	): string | undefined => config?.umamiHost ?? config?.endpoint;
+
+	const resolveTrackingEndpoint = (host: string): string => {
+		const normalized = host.replace(/\/+$/, "");
+		return `${normalized}/api/collect`;
+	};
+
+	const resolveUrl = (event: AnalyticsEvent, host: string): string =>
+		event.url ?? (typeof location !== "undefined" ? location.href : `${host}/`);
+
+	return {
+		track: async (event: unknown, config?: unknown) => {
+			const analyticsEvent = event as AnalyticsEvent;
+			const cfg = config as UmamiAnalyticsConfig | undefined;
+			const host = resolveHost(cfg);
+
+			if (!host?.trim()) {
+				throw configError("Umami host/endpoint is required", {
+					context: { siteId, config },
+					hint: "Provide umamiHost or endpoint in the analytics config.",
+				});
+			}
+
+			const endpoint = resolveTrackingEndpoint(host);
+			const url = resolveUrl(analyticsEvent, host);
+			const payload = {
+				type: analyticsEvent.type === "pageview" ? "pageview" : "event",
+				payload: {
+					website: siteId,
+					url,
+					...(analyticsEvent.type !== "pageview"
+						? { name: analyticsEvent.type }
+						: {}),
+					...(analyticsEvent.target ? { title: analyticsEvent.target } : {}),
+					...(analyticsEvent.query
+						? { data: { query: analyticsEvent.query } }
+						: {}),
+				},
+			};
+
+			try {
+				const response = await fetch(endpoint, {
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify(payload),
+					keepalive: true,
+				});
+
+				if (!response.ok) {
+					throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+				}
+			} catch (error) {
+				throw pluginError("Umami tracking failed", {
+					context: { siteId, endpoint, event: analyticsEvent },
+					hint: "Verify the Umami host is reachable and the siteId is correct.",
+					cause: error,
+				});
+			}
+		},
+
+		init: async (config?: unknown) => {
+			const cfg = config as UmamiAnalyticsConfig | undefined;
+			const host = resolveHost(cfg);
+
+			if (!host?.trim()) {
+				throw configError("Umami host/endpoint is required", {
+					context: { siteId, config },
+					hint: "Provide umamiHost or endpoint in the analytics config.",
+				});
+			}
+
+			try {
+				const response = await fetch(host, { method: "HEAD" });
+				if (!response.ok && response.status !== 405) {
+					throw new Error(`Host responded with HTTP ${response.status}`);
+				}
+			} catch (error) {
+				throw pluginError("Umami initialization failed", {
+					context: { siteId, host },
+					cause: error,
+				});
+			}
+		},
+	};
+};

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

@@ -0,0 +1,37 @@
+/**
+ * Domain events for analytics
+ */
+export interface PageViewedEvent {
+	readonly type: "PAGE_VIEWED";
+	readonly timestamp: number;
+	readonly path: string;
+}
+
+export interface SearchPerformedEvent {
+	readonly type: "SEARCH_PERFORMED";
+	readonly timestamp: number;
+	readonly query: string;
+	readonly resultsCount: number;
+}
+
+export type AnalyticsDomainEvent = PageViewedEvent | SearchPerformedEvent;
+
+export const createPageViewedEvent = (
+	path: string,
+	now: number = Date.now(),
+): PageViewedEvent => ({
+	type: "PAGE_VIEWED",
+	timestamp: now,
+	path,
+});
+
+export const createSearchPerformedEvent = (
+	query: string,
+	resultsCount: number,
+	now: number = Date.now(),
+): SearchPerformedEvent => ({
+	type: "SEARCH_PERFORMED",
+	timestamp: now,
+	query,
+	resultsCount,
+});

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

@@ -0,0 +1,35 @@
+/**
+ * Domain models for analytics
+ */
+export interface PageView {
+	readonly path: string;
+	readonly timestamp: number;
+	readonly duration?: number;
+}
+
+export interface SearchQuery {
+	readonly query: string;
+	readonly timestamp: number;
+	readonly resultsCount: number;
+}
+
+export const createPageView = (
+	path: string,
+	options?: { duration?: number; timestamp?: number },
+	now: number = Date.now(),
+): PageView => ({
+	path,
+	timestamp: options?.timestamp ?? now,
+	duration: options?.duration,
+});
+
+export const createSearchQuery = (
+	query: string,
+	resultsCount: number,
+	options?: { timestamp?: number },
+	now: number = Date.now(),
+): SearchQuery => ({
+	query,
+	timestamp: options?.timestamp ?? now,
+	resultsCount,
+});

package/src/modules/analytics/domain/operations/analytics-operations.ts

@@ -0,0 +1,67 @@
+/**
+ * Pure analytics 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 { AnalyticsConfig } from "../../types/analytics";
+
+export type AnalyticsError = {
+	readonly kind: "analytics-error";
+	readonly message: string;
+};
+
+/**
+ * Track page view event.
+ */
+export const trackPageView = (
+	_url: string,
+	_config: AnalyticsConfig,
+): Result<void, AnalyticsError> => {
+	try {
+		// This will be implemented via adapter
+		return ok(undefined);
+	} catch (error) {
+		return err({
+			kind: "analytics-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Track search query event.
+ */
+export const trackSearch = (
+	_query: string,
+	_config: AnalyticsConfig,
+): Result<void, AnalyticsError> => {
+	try {
+		// This will be implemented via adapter
+		return ok(undefined);
+	} catch (error) {
+		return err({
+			kind: "analytics-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Track click event.
+ */
+export const trackClick = (
+	_target: string,
+	_config: AnalyticsConfig,
+): Result<void, AnalyticsError> => {
+	try {
+		// This will be implemented via adapter
+		return ok(undefined);
+	} catch (error) {
+		return err({
+			kind: "analytics-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};

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

@@ -0,0 +1,50 @@
+// Analytics Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Path Schema
+ */
+export const pathSchema: Type = type("string >= 1");
+
+export type Path = typeof pathSchema.infer;
+
+/**
+ * Search Query Schema
+ */
+export const searchQuerySchema: Type = type("string >= 1");
+
+export type SearchQuery = typeof searchQuerySchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate path using Arktype
+ */
+export const validatePath = (path: unknown): Path => {
+	const result = pathSchema(path);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Path must be a non-empty string");
+	}
+	return result as Path;
+};
+
+/**
+ * Validate search query using Arktype
+ */
+export const validateSearchQuery = (query: unknown): SearchQuery => {
+	const result = searchQuerySchema(query);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Search query must be a non-empty string");
+	}
+	return result as SearchQuery;
+};

package/src/modules/analytics/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Public API for the analytics module.
+ */
+
+export { createPlausibleAdapter } from "./application/plausible-adapter";
+export { createUmamiAdapter } from "./application/umami-adapter";
+export * from "./domain/operations/analytics-operations";
+export * from "./ports/analytics-port";
+export * from "./types/analytics";

package/src/modules/analytics/ports/analytics-port.ts

@@ -0,0 +1,17 @@
+/**
+ * Port for analytics operations.
+ */
+
+import type { AnalyticsEvent } from "../types/analytics";
+
+export type AnalyticsPort = {
+	/**
+	 * Track analytics event.
+	 */
+	readonly track: (event: AnalyticsEvent, config: unknown) => Promise<void>;
+
+	/**
+	 * Initialize analytics.
+	 */
+	readonly init: (config: unknown) => Promise<void>;
+};

package/src/modules/analytics/types/analytics.ts

@@ -0,0 +1,16 @@
+/**
+ * Analytics types for tracking page views and user engagement.
+ */
+
+export type AnalyticsConfig = {
+	readonly provider: "plausible" | "umami" | "google-analytics" | "none";
+	readonly siteId?: string;
+	readonly domain?: string;
+};
+
+export type AnalyticsEvent = {
+	readonly type: "pageview" | "search" | "click";
+	readonly url?: string;
+	readonly query?: string;
+	readonly target?: string;
+};

package/src/modules/api-docs/application/type-docs-adapter.ts

@@ -0,0 +1,34 @@
+/**
+ * TypeDoc adapter implementation.
+ * Provides a safe placeholder for API docs generation from TypeScript.
+ */
+
+import { configError, ioError, pluginError } from "@create-docs/shared/errors";
+import type { ApiDocsPort } from "../ports/api-docs-port";
+
+const TYPEDOC_MISSING_ERROR =
+	"TypeDoc is not installed. Generating API docs from TypeScript requires the typedoc package.";
+
+export const createTypeDocAdapter = (): ApiDocsPort => ({
+	extractEndpoints: async (sourcePath: string, _config?: unknown) => {
+		if (!sourcePath.trim()) {
+			throw configError("TypeDoc sourcePath is required", {
+				context: { sourcePath },
+			});
+		}
+
+		throw ioError(sourcePath, TYPEDOC_MISSING_ERROR);
+	},
+
+	generateDocs: async (_endpoints: readonly unknown[], outputPath: string) => {
+		if (!outputPath.trim()) {
+			throw configError("TypeDoc outputPath is required", {
+				context: { outputPath },
+			});
+		}
+
+		throw pluginError(TYPEDOC_MISSING_ERROR, {
+			context: { outputPath },
+		});
+	},
+});