@wrikka/create-docs 0.1.0

package/src/modules/comments/ports/comment-port.ts

@@ -0,0 +1,18 @@
+/**
+ * Port for comment operations.
+ */
+
+export type CommentPort = {
+	/**
+	 * Load comments for a page.
+	 */
+	readonly load: (
+		pageId: string,
+		config: unknown,
+	) => Promise<readonly unknown[]>;
+
+	/**
+	 * Submit a new comment.
+	 */
+	readonly submit: (comment: unknown, config: unknown) => Promise<void>;
+};

package/src/modules/comments/types/comments.ts

@@ -0,0 +1,19 @@
+/**
+ * Comment system types for user comments on documentation pages.
+ */
+
+export type Comment = {
+	readonly id: string;
+	readonly pageId: string;
+	readonly author: string;
+	readonly content: string;
+	readonly createdAt: string;
+	readonly updatedAt: string;
+};
+
+export type CommentConfig = {
+	readonly provider: "giscus" | "utterances" | "disqus" | "none";
+	readonly repo?: string;
+	readonly repoId?: string;
+	readonly theme?: string;
+};

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

@@ -0,0 +1 @@
+export { loadConfig } from "./loadConfig";

package/src/modules/config/application/usecases/loadConfig.ts

@@ -0,0 +1,38 @@
+/**
+ * Use case: load user config from a project file and merge with defaults.
+ * Pure orchestration — no I/O itself, delegates to ConfigLoader.
+ */
+
+import type { AppError } from "@create-docs/shared/errors";
+import { ok, type Result } from "@create-docs/shared/types/result";
+import {
+	resolveConfig,
+	type UserConfig,
+} from "../../domain/operations/resolve";
+import type { ConfigLoader } from "../../ports";
+import type { ResolvedDocsConfig } from "../../types";
+
+export interface LoadConfigDeps {
+	readonly loader: ConfigLoader;
+	readonly cwd: string;
+	readonly configPath: string;
+	readonly userOverride?: UserConfig;
+}
+
+export const loadConfig = async (
+	deps: LoadConfigDeps,
+): Promise<Result<ResolvedDocsConfig, AppError>> => {
+	const { loader, cwd, configPath, userOverride } = deps;
+
+	if (userOverride) {
+		return ok(resolveConfig(userOverride));
+	}
+
+	const result = await loader.load(cwd, configPath);
+	if (!result.ok) return result;
+	const fileConfig = result.value;
+	if (fileConfig === null) {
+		return ok(resolveConfig({}));
+	}
+	return ok(resolveConfig(fileConfig));
+};

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

@@ -0,0 +1 @@
+export { validateConfig } from "./validateConfig";

package/src/modules/config/application/workflows/validateConfig.ts

@@ -0,0 +1,14 @@
+/**
+ * Workflow: validate a config and return it (or fail).
+ * Pure — no I/O.
+ */
+
+import type { AppError } from "@create-docs/shared/errors";
+import type { Result } from "@create-docs/shared/types/result";
+import { validateDocsConfig } from "../../domain/validators";
+import type { DocsConfig } from "../../types";
+
+export type ValidateConfig = (c: DocsConfig) => Result<DocsConfig, AppError>;
+
+export const validateConfig: ValidateConfig = (c) =>
+	validateDocsConfig(c) as Result<DocsConfig, AppError>;

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

@@ -0,0 +1,50 @@
+/**
+ * Config module domain events.
+ */
+import type { DocsConfig, ResolvedDocsConfig } from "../../types";
+
+export type ConfigEvent =
+	| {
+			readonly type: "config.loaded";
+			readonly source: "defaults" | "file" | "user";
+	  }
+	| { readonly type: "config.merged"; readonly keys: readonly string[] }
+	| { readonly type: "config.resolved"; readonly config: ResolvedDocsConfig }
+	| {
+			readonly type: "config.validated";
+			readonly valid: boolean;
+			readonly issues: number;
+	  }
+	| {
+			readonly type: "config.changed";
+			readonly previous: DocsConfig;
+			readonly next: DocsConfig;
+	  };
+
+export const configLoaded = (
+	source: "defaults" | "file" | "user",
+): ConfigEvent => ({ type: "config.loaded", source });
+export const configMerged = (keys: readonly string[]): ConfigEvent => ({
+	type: "config.merged",
+	keys,
+});
+export const configResolved = (config: ResolvedDocsConfig): ConfigEvent => ({
+	type: "config.resolved",
+	config,
+});
+export const configValidated = (
+	valid: boolean,
+	issues: number,
+): ConfigEvent => ({
+	type: "config.validated",
+	valid,
+	issues,
+});
+export const configChanged = (
+	previous: DocsConfig,
+	next: DocsConfig,
+): ConfigEvent => ({
+	type: "config.changed",
+	previous,
+	next,
+});

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

@@ -0,0 +1,9 @@
+export type {
+	DocsConfig,
+	DocsPluginOptions,
+	NavItem,
+	NavSection,
+	ResolvedDocsConfig,
+	SidebarGroup,
+	SiteConfig,
+} from "../../types";

package/src/modules/config/domain/operations/defaults.ts

@@ -0,0 +1,74 @@
+/**
+ * Default config — the canonical fallback for the docs site.
+ */
+import type { DocsConfig } from "../../types";
+
+export const defaultDocsConfig: DocsConfig = {
+	site: {
+		title: "Documentation",
+		description: "Documentation and guides",
+		logo: "/logo.svg",
+		github: "",
+		twitter: "",
+		version: "1.0.0",
+	},
+	nav: [
+		{
+			title: "Product",
+			items: [
+				{
+					label: "Getting Started",
+					href: "/docs/getting-started/introduction",
+				},
+				{ label: "Installation", href: "/docs/getting-started/installation" },
+				{ label: "Features", href: "/docs/product/features" },
+				{ label: "Configuration", href: "/docs/product/configuration" },
+			],
+		},
+		{
+			title: "Resources",
+			items: [
+				{ label: "FAQ", href: "/docs/resources/faq" },
+				{ label: "Best Practices", href: "/docs/resources/best-practices" },
+				{ label: "Troubleshooting", href: "/docs/resources/troubleshooting" },
+				{ label: "Integrations", href: "/docs/resources/integrations" },
+			],
+		},
+		{
+			title: "API",
+			items: [
+				{ label: "Overview", href: "/docs/api/overview" },
+				{ label: "Authentication", href: "/docs/api/authentication" },
+				{ label: "Endpoints", href: "/docs/api/endpoints" },
+				{ label: "API Tester", href: "/docs/api/tester" },
+			],
+		},
+	],
+	sidebar: [],
+	theme: {
+		primaryColor: "#3B82F6",
+		darkMode: true,
+		accentColor: "#8B5CF6",
+		codeTheme: "github-dark",
+	},
+	api: {
+		baseUrl: "/api/v1",
+		authType: "bearer",
+		authHeader: "Authorization",
+		testerEnabled: true,
+	},
+	search: {
+		enabled: true,
+		placeholder: "Search docs...",
+		shortcuts: ["⌘K", "Ctrl+K"],
+	},
+	editLink: {
+		enabled: true,
+		baseUrl: "",
+		branch: "main",
+	},
+	lastUpdated: {
+		enabled: true,
+		format: "dd MMM yyyy",
+	},
+};

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

@@ -0,0 +1,2 @@
+export { defaultDocsConfig } from "./defaults";
+export { resolveConfig, type UserConfig } from "./resolve";

package/src/modules/config/domain/operations/resolve.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure operations for building and merging configs.
+ * No I/O. No mutation of inputs.
+ */
+import {
+	DEFAULT_BASE_ROUTE,
+	DEFAULT_DOCS_DIR,
+} from "@create-docs/shared/constants";
+import type {
+	DocsConfig,
+	DocsPluginOptions,
+	ResolvedDocsConfig,
+} from "../../types";
+import { defaultDocsConfig } from "./defaults";
+
+export type UserConfig = Partial<DocsConfig> & DocsPluginOptions;
+
+export const resolveConfig = (user: UserConfig = {}): ResolvedDocsConfig => ({
+	...defaultDocsConfig,
+	...user,
+	nav: user.nav ?? defaultDocsConfig.nav,
+	sidebar: user.sidebar ?? defaultDocsConfig.sidebar,
+	site: { ...defaultDocsConfig.site, ...(user.site ?? {}) },
+	theme: mergeOptional(defaultDocsConfig.theme, user.theme),
+	api: mergeOptional(defaultDocsConfig.api, user.api),
+	search: mergeOptional(defaultDocsConfig.search, user.search),
+	editLink: mergeOptional(defaultDocsConfig.editLink, user.editLink),
+	lastUpdated: mergeOptional(defaultDocsConfig.lastUpdated, user.lastUpdated),
+	docsDir: user.docsDir ?? DEFAULT_DOCS_DIR,
+	baseRoute: user.baseRoute ?? DEFAULT_BASE_ROUTE,
+});
+
+const mergeOptional = <T>(
+	a: T | undefined,
+	b: T | undefined,
+): T | undefined => {
+	if (a === undefined) return b;
+	if (b === undefined) return a;
+	return { ...a, ...b };
+};

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

@@ -0,0 +1,152 @@
+// Config Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { API_AUTH_TYPES } from "@create-docs/shared/constants";
+import { type AppError, configError } from "@create-docs/shared/errors";
+import { err, ok, type Result } from "@create-docs/shared/types/result";
+import { type Type, type } from "arktype";
+import type { ApiEndpoint, DocsConfig } from "../../types";
+
+/**
+ * Site Schema
+ */
+export const siteSchema: Type = type({
+	title: "string >= 1",
+	description: "string >= 1",
+});
+
+/**
+ * API Schema
+ */
+export const apiSchema: Type = type({
+	baseUrl: "string >= 1",
+	authType: type("'bearer' | 'apiKey' | 'oauth2'"),
+});
+
+/**
+ * API Endpoint Schema
+ */
+export const apiEndpointSchema: Type = type({
+	method: type("'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'"),
+	path: "string >= 1",
+	description: "string >= 1",
+});
+
+export interface ValidationIssue {
+	readonly path: string;
+	readonly message: string;
+	readonly hint?: string;
+	readonly suggestions?: readonly string[];
+}
+
+const isNonEmptyString = (v: unknown): v is string =>
+	typeof v === "string" && v.trim().length > 0;
+
+const validateSite = (site: DocsConfig["site"]): ValidationIssue[] => {
+	const issues: ValidationIssue[] = [];
+	if (!isNonEmptyString(site.title)) {
+		issues.push({
+			path: "site.title",
+			message: "must be a non-empty string",
+		});
+	}
+	if (!isNonEmptyString(site.description)) {
+		issues.push({
+			path: "site.description",
+			message: "must be a non-empty string",
+		});
+	}
+	return issues;
+};
+
+const validateApi = (api: DocsConfig["api"]): ValidationIssue[] => {
+	const issues: ValidationIssue[] = [];
+	if (api === undefined) return issues;
+	if (!isNonEmptyString(api.baseUrl)) {
+		issues.push({
+			path: "api.baseUrl",
+			message: "must be a non-empty string",
+		});
+	}
+	const authTypes = API_AUTH_TYPES as readonly string[];
+	if (!authTypes.includes(api.authType)) {
+		issues.push({
+			path: "api.authType",
+			message: `must be one of: ${API_AUTH_TYPES.join(", ")}`,
+			suggestions: [...API_AUTH_TYPES],
+		});
+	}
+	return issues;
+};
+
+export const validateSiteSchema = (
+	s: DocsConfig["site"],
+): Result<DocsConfig["site"], AppError> => {
+	const issues = validateSite(s);
+	if (issues.length === 0) return ok(s);
+	const first = issues[0];
+	return err(
+		configError(first.message, {
+			path: first.path,
+			...(first.suggestions ? { suggestions: first.suggestions } : {}),
+		}),
+	);
+};
+
+export const validateApiSchema = (
+	a: DocsConfig["api"],
+): Result<DocsConfig["api"] | undefined, AppError> => {
+	if (a === undefined) return ok(undefined);
+	const issues = validateApi(a);
+	if (issues.length === 0) return ok(a);
+	const first = issues[0];
+	return err(
+		configError(first.message, {
+			path: first.path,
+			...(first.suggestions ? { suggestions: first.suggestions } : {}),
+		}),
+	);
+};
+
+export const validateApiEndpoint = (
+	e: ApiEndpoint,
+	path: string,
+): Result<ApiEndpoint, AppError> => {
+	const result = apiEndpointSchema(e);
+	if (result instanceof type.errors) {
+		return err(
+			configError(result.summary, {
+				path: `${path}`,
+			}),
+		);
+	}
+	return ok(e);
+};
+
+/** Collect all issues in one pass — returns every problem at once. */
+export const validateDocsConfigAll = (
+	c: DocsConfig,
+): { ok: true } | { ok: false; issues: readonly ValidationIssue[] } => {
+	const issues: ValidationIssue[] = [
+		...validateSite(c.site),
+		...validateApi(c.api),
+	];
+	if (issues.length > 0) return { ok: false, issues };
+	return { ok: true };
+};
+
+export const validateDocsConfig = (
+	c: DocsConfig,
+): Result<DocsConfig, AppError> => {
+	const all = validateDocsConfigAll(c);
+	if (all.ok) return ok(c);
+	const first = all.issues[0];
+	if (!first) return ok(c);
+	return err(
+		configError(first.message, {
+			path: first.path,
+			...(first.suggestions ? { suggestions: first.suggestions } : {}),
+			...(first.hint ? { context: { hint: first.hint } } : {}),
+		}),
+	);
+};

package/src/modules/config/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Public API for the config module.
+ */
+
+export * from "./application/usecases";
+export * from "./application/workflows";
+export {
+	configChanged,
+	configLoaded,
+	configMerged,
+	configResolved,
+	configValidated,
+} from "./domain/events";
+export * from "./domain/operations";
+export {
+	validateApiEndpoint,
+	validateApiSchema as validateApi,
+	validateDocsConfig,
+	validateDocsConfigAll,
+	validateSiteSchema as validateSite,
+} from "./domain/validators";
+export type { ConfigLoader } from "./ports";
+export * from "./types/public";

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

@@ -0,0 +1,15 @@
+/**
+ * Config module ports — interfaces for I/O.
+ */
+
+import type { AppError } from "@create-docs/shared/errors";
+import type { Result } from "@create-docs/shared/types/result";
+import type { DocsConfig } from "../types";
+
+/** Loads a DocsConfig from a project file (e.g. docs/docs.config.ts). */
+export interface ConfigLoader {
+	load(
+		cwd: string,
+		configPath: string,
+	): Promise<Result<Partial<DocsConfig> | null, AppError>>;
+}

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

@@ -0,0 +1,113 @@
+import type {
+	BadgeVariant,
+	NavItem,
+	NavSection,
+	SidebarGroup,
+	SidebarItem,
+} from "@create-docs/modules/navigation";
+
+export type { BadgeVariant, NavItem, NavSection, SidebarGroup, SidebarItem };
+
+export type AuthType = "bearer" | "apiKey" | "oauth2";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export 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;
+	}[];
+}
+
+export interface ThemeConfig {
+	readonly primaryColor?: string;
+	readonly darkMode?: boolean;
+	readonly accentColor?: string;
+	readonly codeTheme?: string;
+}
+
+export interface SiteConfig {
+	readonly title: string;
+	readonly description: string;
+	readonly logo?: string;
+	readonly logoDark?: string;
+	readonly github?: string;
+	readonly twitter?: string;
+	readonly version?: string;
+}
+
+export interface ApiConfig {
+	readonly baseUrl: string;
+	readonly authType: AuthType;
+	readonly authHeader?: string;
+	readonly defaultHeaders?: Record<string, string>;
+	readonly testerEnabled?: boolean;
+	readonly endpoints?: readonly ApiEndpoint[];
+}
+
+export interface SearchConfig {
+	readonly enabled?: boolean;
+	readonly placeholder?: string;
+	readonly shortcuts?: readonly string[];
+}
+
+export interface EditLinkConfig {
+	readonly enabled?: boolean;
+	readonly baseUrl?: string;
+	readonly branch?: string;
+}
+
+export interface LastUpdatedConfig {
+	readonly enabled?: boolean;
+	readonly format?: string;
+}
+
+export 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. */
+export interface DocsPluginOptions {
+	readonly docsDir?: string;
+	readonly baseRoute?: string;
+}
+
+export type ResolvedDocsConfig = DocsConfig & {
+	readonly docsDir: string;
+	readonly baseRoute: string;
+};

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

@@ -0,0 +1,19 @@
+export type {
+	ApiConfig,
+	ApiEndpoint,
+	AuthType,
+	BadgeVariant,
+	DocsConfig,
+	DocsPluginOptions,
+	EditLinkConfig,
+	HttpMethod,
+	LastUpdatedConfig,
+	NavItem,
+	NavSection,
+	ResolvedDocsConfig,
+	SearchConfig,
+	SidebarGroup,
+	SidebarItem,
+	SiteConfig,
+	ThemeConfig,
+} from "./index";

package/src/modules/content/application/cache/index.ts

@@ -0,0 +1,6 @@
+export {
+	type CacheEntry,
+	type CacheKeyParts,
+	makeCacheKey,
+	ParseCache,
+} from "./parseCache";

package/src/modules/content/application/cache/parse-cache.ts

@@ -0,0 +1,6 @@
+export {
+	type CacheEntry,
+	type CacheKeyParts,
+	makeCacheKey,
+	ParseCache,
+} from "./parseCache";

package/src/modules/content/application/cache/parseCache.ts

@@ -0,0 +1,56 @@
+/**
+ * mtime+size keyed parse cache.
+ *
+ * Skips re-parsing files whose mtime and size have not changed since the
+ * last build. Pure — no I/O. Designed to be wrapped by an outer Map keyed
+ * by absolute file path.
+ */
+
+export interface CacheKeyParts {
+	readonly mtimeMs: number;
+	readonly size: number;
+}
+
+export interface CacheEntry<T> {
+	readonly key: string;
+	readonly value: T;
+}
+
+/** Build a stable cache key from a file path and stat info. */
+export const makeCacheKey = (filePath: string, parts: CacheKeyParts): string =>
+	`${filePath}@${parts.mtimeMs.toFixed(0)}:${parts.size}`;
+
+/**
+ * Simple bounded parse cache with LRU-like eviction.
+ */
+export class ParseCache<T> {
+	private map = new Map<string, T>();
+
+	constructor(private max: number = 1024) {}
+
+	get(key: string): T | undefined {
+		return this.map.get(key);
+	}
+
+	set(key: string, value: T): void {
+		if (this.map.has(key)) this.map.delete(key);
+		this.map.set(key, value);
+
+		if (this.map.size > this.max) {
+			const oldest = this.map.keys().next().value;
+			if (oldest !== undefined) this.map.delete(oldest);
+		}
+	}
+
+	has(key: string): boolean {
+		return this.map.has(key);
+	}
+
+	clear(): void {
+		this.map.clear();
+	}
+
+	get size(): number {
+		return this.map.size;
+	}
+}

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

@@ -0,0 +1,2 @@
+export { buildDocPageFromRaw, loadDocPage } from "./loadDocPage";
+export { scanDocsDir } from "./scanDocsDir";

package/src/modules/content/application/usecases/load-doc-page.ts

@@ -0,0 +1 @@
+export { buildDocPageFromRaw, loadDocPage } from "./loadDocPage";