@wrikka/create-docs 0.1.0

package/src/modules/search-highlighting/application/dom-highlighting-adapter.ts

@@ -0,0 +1,36 @@
+/**
+ * DOM highlighting adapter implementation.
+ * Provides client-side search highlighting.
+ */
+
+import {
+	applyHighlighting,
+	findMatches,
+} from "../domain/operations/highlighting-operations";
+import type { HighlightingPort } from "../ports/highlighting-port";
+import type { HighlightConfig } from "../types/highlighting";
+
+export const createDomHighlightingAdapter = (): HighlightingPort => ({
+	highlight: async (content: string, query: string, config?: unknown) => {
+		const highlightConfig: HighlightConfig =
+			config && typeof config === "object"
+				? (config as HighlightConfig)
+				: {
+						enabled: true,
+						caseSensitive: false,
+						highlightClass: "search-highlight",
+					};
+
+		const matchesResult = findMatches(content, query, highlightConfig);
+		if (!matchesResult.ok) {
+			return content;
+		}
+
+		const highlighted = applyHighlighting(
+			content,
+			matchesResult.value,
+			highlightConfig.highlightClass,
+		);
+		return highlighted;
+	},
+});

package/src/modules/search-highlighting/domain/operations/highlighting-operations.ts

@@ -0,0 +1,72 @@
+/**
+ * Pure search highlighting 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 { HighlightConfig, HighlightMatch } from "../../types/highlighting";
+
+export type HighlightingError = {
+	readonly kind: "highlighting-error";
+	readonly message: string;
+};
+
+/**
+ * Find all matches of a query in text.
+ */
+export const findMatches = (
+	text: string,
+	query: string,
+	config: HighlightConfig,
+): Result<readonly HighlightMatch[], HighlightingError> => {
+	try {
+		if (query.length === 0) return ok([]);
+
+		const matches: HighlightMatch[] = [];
+		const searchRegex = new RegExp(
+			query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+			config.caseSensitive ? "g" : "gi",
+		);
+
+		let match: RegExpExecArray | null = searchRegex.exec(text);
+		while (match !== null) {
+			matches.push({
+				text: match[0],
+				start: match.index,
+				end: match.index + match[0].length,
+			});
+			match = searchRegex.exec(text);
+		}
+
+		return ok(matches);
+	} catch (error) {
+		return err({
+			kind: "highlighting-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Apply highlighting to text with matches.
+ */
+export const applyHighlighting = (
+	text: string,
+	matches: readonly HighlightMatch[],
+	highlightClass: string,
+): string => {
+	if (matches.length === 0) return text;
+
+	let result = "";
+	let lastIndex = 0;
+
+	for (const match of matches) {
+		result += text.slice(lastIndex, match.start);
+		result += `<mark class="${highlightClass}">${match.text}</mark>`;
+		lastIndex = match.end;
+	}
+
+	result += text.slice(lastIndex);
+	return result;
+};

package/src/modules/search-highlighting/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public API for the search-highlighting module.
+ */
+
+export { createDomHighlightingAdapter } from "./application/dom-highlighting-adapter";
+export * from "./domain/operations/highlighting-operations";
+export * from "./ports/highlighting-port";
+export * from "./types/highlighting";

package/src/modules/search-highlighting/ports/highlighting-port.ts

@@ -0,0 +1,14 @@
+/**
+ * Port for search highlighting operations.
+ */
+
+export type HighlightingPort = {
+	/**
+	 * Highlight search terms in content.
+	 */
+	readonly highlight: (
+		content: string,
+		query: string,
+		config: unknown,
+	) => Promise<string>;
+};

package/src/modules/search-highlighting/types/highlighting.ts

@@ -0,0 +1,15 @@
+/**
+ * Search highlighting types for highlighting search terms in content.
+ */
+
+export type HighlightConfig = {
+	readonly enabled: boolean;
+	readonly highlightClass: string;
+	readonly caseSensitive: boolean;
+};
+
+export type HighlightMatch = {
+	readonly text: string;
+	readonly start: number;
+	readonly end: number;
+};

package/src/modules/seo-optimization/application/usecases/index.ts

@@ -0,0 +1,18 @@
+/**
+ * SEO Optimization Use Cases
+ *
+ * Orchestration layer for SEO optimization
+ */
+
+import { generateMetaTags } from "../../domain";
+import type { MetaTags, SeoOptions } from "../../types";
+
+/**
+ * Optimize content for SEO
+ */
+export const optimizeSeo = (
+	content: string,
+	options: SeoOptions = {},
+): MetaTags => {
+	return generateMetaTags(content, options);
+};

package/src/modules/seo-optimization/domain/index.ts

@@ -0,0 +1,12 @@
+/**
+ * SEO Optimization Domain
+ *
+ * Pure business logic for SEO optimization
+ */
+
+export {
+	extractDescription,
+	extractKeywords,
+	extractTitle,
+	generateMetaTags,
+} from "./seoOperations";

package/src/modules/seo-optimization/domain/seoOperations.ts

@@ -0,0 +1,92 @@
+/**
+ * SEO Operations
+ *
+ * Pure functions for SEO optimization
+ */
+
+import type { MetaTags, SeoOptions } from "../types";
+
+/**
+ * Extract title from markdown content
+ */
+export const extractTitle = (content: string): string | null => {
+	const titleMatch = content.match(/^#\s+(.+)$/m);
+	return titleMatch?.[1] ? titleMatch[1].trim() : null;
+};
+
+/**
+ * Extract description from markdown content
+ */
+export const extractDescription = (
+	content: string,
+	maxLength = 160,
+): string => {
+	const lines = content.split("\n");
+	const descriptionLines: string[] = [];
+
+	for (const line of lines) {
+		if (line.startsWith("#")) continue;
+		if (line.trim() === "") continue;
+		if (line.startsWith("```")) break;
+
+		descriptionLines.push(line.trim());
+		if (descriptionLines.join(" ").length >= maxLength) break;
+	}
+
+	const description = descriptionLines.join(" ");
+	return description.length > maxLength
+		? `${description.substring(0, maxLength - 3)}...`
+		: description;
+};
+
+/**
+ * Extract keywords from markdown content
+ */
+export const extractKeywords = (content: string): string[] => {
+	const words = content
+		.toLowerCase()
+		.replace(/[^\w\s]/g, "")
+		.split(/\s+/)
+		.filter((word) => word.length > 3);
+
+	const frequency: Record<string, number> = {};
+	for (const word of words) {
+		frequency[word] = (frequency[word] || 0) + 1;
+	}
+
+	const sorted = Object.entries(frequency)
+		.sort(([, a], [, b]) => b - a)
+		.slice(0, 10)
+		.map(([word]) => word);
+
+	return sorted;
+};
+
+/**
+ * Generate meta tags from content
+ */
+export const generateMetaTags = (
+	content: string,
+	options: SeoOptions = {},
+): MetaTags => {
+	const title = extractTitle(content);
+	const description = extractDescription(content);
+	const keywords = extractKeywords(content);
+
+	const metaTags: MetaTags = {
+		title: title || undefined,
+		description,
+		keywords,
+	};
+
+	if (options.generateOg) {
+		metaTags.ogTitle = title || undefined;
+		metaTags.ogDescription = description;
+	}
+
+	if (options.generateTwitter) {
+		metaTags.twitterCard = "summary_large_image";
+	}
+
+	return metaTags;
+};

package/src/modules/seo-optimization/index.ts

@@ -0,0 +1,8 @@
+/**
+ * SEO Optimization Module
+ *
+ * SEO optimization for documentation
+ */
+
+export { optimizeSeo } from "./application/usecases";
+export * from "./domain";

package/src/modules/seo-optimization/ports/index.ts

@@ -0,0 +1,18 @@
+/**
+ * SEO Optimization Ports
+ *
+ * Module-specific interfaces for SEO optimization
+ */
+
+import type { MetaTags, SeoOptions } from "../types";
+
+/**
+ * Meta tag generator interface
+ */
+export interface MetaTagGenerator {
+	/** Generate meta tags HTML */
+	generateMetaHtml(tags: MetaTags): string;
+}
+
+// Re-export types for convenience
+export type { MetaTags, SeoOptions };

package/src/modules/seo-optimization/types/index.ts

@@ -0,0 +1,41 @@
+/**
+ * SEO Optimization Types
+ *
+ * Domain types for SEO optimization
+ */
+
+/**
+ * Meta tags
+ */
+export interface MetaTags {
+	/** Title */
+	title?: string;
+	/** Description */
+	description?: string;
+	/** Keywords */
+	keywords?: string[];
+	/** Author */
+	author?: string;
+	/** Open Graph title */
+	ogTitle?: string;
+	/** Open Graph description */
+	ogDescription?: string;
+	/** Open Graph image */
+	ogImage?: string;
+	/** Twitter card */
+	twitterCard?: "summary" | "summary_large_image";
+}
+
+/**
+ * SEO options
+ */
+export interface SeoOptions {
+	/** Generate meta tags */
+	generateMeta?: boolean;
+	/** Generate Open Graph tags */
+	generateOg?: boolean;
+	/** Generate Twitter card tags */
+	generateTwitter?: boolean;
+	/** Generate canonical URL */
+	generateCanonical?: boolean;
+}

package/src/modules/theme/application/css-theme-adapter.ts

@@ -0,0 +1,50 @@
+/**
+ * CSS theme adapter implementation.
+ * Provides CSS-based theme application.
+ */
+
+import { getCssVariables } from "../domain/operations/theme-operations";
+import type { ThemePort } from "../ports/theme-port";
+import type { ThemeConfig } from "../types/theme";
+
+export const createCssThemeAdapter = (): ThemePort => ({
+	loadTheme: async (themePath: string) => {
+		if (typeof window === "undefined") {
+			return {};
+		}
+
+		try {
+			const response = await fetch(themePath);
+			if (!response.ok) {
+				throw new Error(`Failed to load theme: ${response.statusText}`);
+			}
+			const content = await response.text();
+			return content;
+		} catch (error) {
+			console.error("Theme load error:", error);
+			return {};
+		}
+	},
+
+	applyTheme: async (config?: unknown) => {
+		if (typeof window === "undefined") {
+			return;
+		}
+
+		const themeConfig = config as ThemeConfig;
+		if (!themeConfig) {
+			return;
+		}
+
+		const cssVarsResult = getCssVariables(themeConfig);
+		if (!cssVarsResult.ok) {
+			console.error("Failed to get CSS variables:", cssVarsResult.error);
+			return;
+		}
+
+		const root = document.documentElement;
+		for (const [key, value] of Object.entries(cssVarsResult.value)) {
+			root.style.setProperty(key, value);
+		}
+	},
+});

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

@@ -0,0 +1,68 @@
+/**
+ * Pure theme 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 { ThemeConfig, ThemeVariant } from "../../types/theme";
+
+export type ThemeError = {
+	readonly kind: "theme-error";
+	readonly message: string;
+};
+
+/**
+ * Validate theme config.
+ */
+export const validateThemeConfig = (config: ThemeConfig): boolean => {
+	if (!config.name) return false;
+	if (!config.colors || Object.keys(config.colors).length === 0) return false;
+	return true;
+};
+
+/**
+ * Get CSS variables from theme config.
+ */
+export const getCssVariables = (
+	config: ThemeConfig,
+): Result<Record<string, string>, ThemeError> => {
+	try {
+		const variables: Record<string, string> = {};
+
+		for (const [key, value] of Object.entries(config.colors)) {
+			variables[`--color-${key}`] = value;
+		}
+
+		for (const [key, value] of Object.entries(config.spacing)) {
+			variables[`--spacing-${key}`] = `${value}px`;
+		}
+
+		return ok(variables);
+	} catch (error) {
+		return err({
+			kind: "theme-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Apply theme variant.
+ */
+export const applyThemeVariant = (
+	config: ThemeConfig,
+	variant: ThemeVariant,
+): ThemeConfig => {
+	if (variant === "dark") {
+		return {
+			...config,
+			colors: {
+				...config.colors,
+				background: "#1a1a1a",
+				foreground: "#ffffff",
+			},
+		};
+	}
+	return config;
+};

package/src/modules/theme/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public API for the theme module.
+ */
+
+export { createCssThemeAdapter } from "./application/css-theme-adapter";
+export * from "./domain/operations/theme-operations";
+export * from "./ports/theme-port";
+export * from "./types/theme";

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

@@ -0,0 +1,8 @@
+import type { ThemeConfig } from "../types/theme";
+
+export type ThemePort = {
+	readonly loadTheme: (
+		themePath: string,
+	) => Promise<Record<string, string> | string>;
+	readonly applyTheme: (config?: ThemeConfig) => Promise<void>;
+};

package/src/modules/theme/types/theme.ts

@@ -0,0 +1,12 @@
+/**
+ * Theme types for custom theme system.
+ */
+
+export type ThemeConfig = {
+	readonly name: string;
+	readonly colors: Readonly<Record<string, string>>;
+	readonly fonts: Readonly<Record<string, string>>;
+	readonly spacing: Readonly<Record<string, number>>;
+};
+
+export type ThemeVariant = "light" | "dark" | "auto";

package/src/modules/toc/application/markdown-toc-adapter.ts

@@ -0,0 +1,106 @@
+/**
+ * Markdown TOC adapter implementation.
+ * Provides TOC generation from markdown content using native string parsing.
+ */
+
+import { parseError, pluginError } from "@create-docs/shared/errors";
+import {
+	buildHierarchicalToc,
+	generateTocId,
+} from "../domain/operations/toc-operations";
+import type { TocPort } from "../ports/toc-port";
+import type { TocConfig, TocItemEnhanced } from "../types/toc";
+
+const defaultTocConfig: TocConfig = {
+	enabled: true,
+	maxDepth: 6,
+	minHeadingLevel: 1,
+	includeSubheadings: true,
+};
+
+const resolveTocConfig = (config: unknown): TocConfig => {
+	const cfg = config as Partial<TocConfig> | undefined;
+	if (!cfg) return defaultTocConfig;
+	return {
+		enabled: cfg.enabled ?? defaultTocConfig.enabled,
+		maxDepth: cfg.maxDepth ?? defaultTocConfig.maxDepth,
+		minHeadingLevel: cfg.minHeadingLevel ?? defaultTocConfig.minHeadingLevel,
+		includeSubheadings:
+			cfg.includeSubheadings ?? defaultTocConfig.includeSubheadings,
+	};
+};
+
+const stripMarkdownLinks = (text: string): string =>
+	text.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+
+const extractHeadingsFromMarkdown = (
+	content: string,
+	config: TocConfig,
+): readonly TocItemEnhanced[] => {
+	const headings: TocItemEnhanced[] = [];
+	let inCodeBlock = false;
+
+	for (const raw of content.split(/\r?\n/)) {
+		const line = raw.trim();
+
+		if (line.startsWith("```")) {
+			inCodeBlock = !inCodeBlock;
+			continue;
+		}
+
+		if (inCodeBlock) continue;
+
+		const match = line.match(/^(#{1,6})\s+(.+)$/);
+		if (!match) continue;
+
+		const level = match[1].length;
+		if (level < config.minHeadingLevel || level > config.maxDepth) continue;
+
+		const text = stripMarkdownLinks(match[2].trim());
+		headings.push({
+			id: generateTocId(text),
+			text,
+			level,
+		});
+	}
+
+	return headings;
+};
+
+const isTocItem = (value: unknown): value is TocItemEnhanced =>
+	value !== null &&
+	typeof value === "object" &&
+	"id" in value &&
+	"text" in value &&
+	"level" in value;
+
+export const createMarkdownTocAdapter = (): TocPort => ({
+	extractHeadings: async (content: string, config?: unknown) => {
+		try {
+			const cfg = resolveTocConfig(config);
+			return extractHeadingsFromMarkdown(content, cfg);
+		} catch (error) {
+			throw parseError("<input>", "Failed to extract headings", error);
+		}
+	},
+
+	generateToc: async (headings: readonly unknown[], config?: unknown) => {
+		try {
+			const cfg = resolveTocConfig(config);
+			const typedHeadings = headings.filter(isTocItem);
+			const result = buildHierarchicalToc(typedHeadings, cfg);
+
+			if (!result.ok) {
+				throw pluginError("Failed to build hierarchical TOC", {
+					context: { error: String(result.error) },
+				});
+			}
+
+			return result.value;
+		} catch (error) {
+			throw pluginError("Failed to generate TOC", {
+				context: { config, error: String(error) },
+			});
+		}
+	},
+});

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

@@ -0,0 +1,92 @@
+/**
+ * Pure TOC 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 { TocConfig, TocItemEnhanced } from "../../types/toc";
+
+export type TocError = {
+	readonly kind: "toc-error";
+	readonly message: string;
+};
+
+/**
+ * Build hierarchical TOC from flat headings.
+ */
+export const buildHierarchicalToc = (
+	headings: readonly TocItemEnhanced[],
+	config: TocConfig,
+): Result<TocItemEnhanced[], TocError> => {
+	try {
+		const root: TocItemEnhanced[] = [];
+		const stack: TocItemEnhanced[] = [];
+
+		for (const heading of headings) {
+			if (heading.level < config.minHeadingLevel) continue;
+			if (heading.level > config.maxDepth) continue;
+
+			while (stack.length > 0) {
+				const top = stack[stack.length - 1];
+				if (top && top.level >= heading.level) {
+					stack.pop();
+				} else {
+					break;
+				}
+			}
+
+			const item: TocItemEnhanced = { ...heading, children: [] };
+
+			if (stack.length === 0) {
+				root.push(item);
+			} else {
+				const parent = stack[stack.length - 1];
+				if (parent?.children) {
+					parent.children = [...parent.children, item];
+				}
+			}
+
+			stack.push(item);
+		}
+
+		return ok(root);
+	} catch (error) {
+		return err({
+			kind: "toc-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Generate TOC ID from heading text.
+ */
+export const generateTocId = (text: string): string => {
+	return text
+		.toLowerCase()
+		.replace(/[^a-z0-9\s-]/g, "")
+		.trim()
+		.replace(/\s+/g, "-");
+};
+
+/**
+ * Flatten hierarchical TOC.
+ */
+export const flattenToc = (
+	toc: readonly TocItemEnhanced[],
+): readonly TocItemEnhanced[] => {
+	const result: TocItemEnhanced[] = [];
+
+	const flatten = (items: readonly TocItemEnhanced[]) => {
+		for (const item of items) {
+			result.push({ ...item, children: undefined });
+			if (item.children) {
+				flatten(item.children);
+			}
+		}
+	};
+
+	flatten(toc);
+	return result;
+};