@wrikka/create-docs 0.1.0

package/src/modules/plugin/index.ts

@@ -0,0 +1,14 @@
+export * from "./application/usecases";
+export * from "./application/workflows";
+export {
+	pluginConfigResolved,
+	pluginError,
+	pluginFileWatched,
+	pluginInitialized,
+	pluginReloaded,
+	pluginVirtualModuleEmitted,
+} from "./domain/events";
+export * from "./domain/operations";
+export { validateResolvedConfig } from "./domain/validators";
+export type { DocsLoader, DocsWatcher } from "./ports";
+export * from "./types/public";

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

@@ -0,0 +1,21 @@
+/**
+ * Plugin module ports — interfaces for I/O the plugin needs from adapters.
+ */
+
+import type { ResolvedDocsConfig } from "@create-docs/modules/config";
+import type { DocPage } from "@create-docs/modules/content";
+import type { AppError } from "@create-docs/shared/errors";
+import type { Result } from "@create-docs/shared/types/result";
+
+export interface DocsLoader {
+	loadAll(
+		config: ResolvedDocsConfig,
+	): Promise<Result<readonly DocPage[], AppError>>;
+}
+
+export interface DocsWatcher {
+	watch(
+		docsDir: string,
+		onChange: (filePath: string) => void,
+	): { close: () => void };
+}

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

@@ -0,0 +1,27 @@
+import type { Brand } from "@create-docs/shared/types";
+
+export type VirtualModuleId = Brand<string, "VirtualModuleId">;
+export const VirtualModuleId = (s: string): VirtualModuleId =>
+	s as VirtualModuleId;
+
+export const VIRTUAL_DATA: VirtualModuleId =
+	VirtualModuleId("virtual:docs/data");
+export const VIRTUAL_SEARCH_INDEX: VirtualModuleId = VirtualModuleId(
+	"virtual:docs/search-index",
+);
+export const VIRTUAL_SIDEBAR: VirtualModuleId = VirtualModuleId(
+	"virtual:docs/sidebar",
+);
+export const VIRTUAL_NAV: VirtualModuleId = VirtualModuleId("virtual:docs/nav");
+
+export interface PluginContext {
+	readonly root: string;
+	readonly mode: "dev" | "build" | "test";
+}
+
+export interface PluginHooks {
+	readonly configResolved?: (config: PluginContext) => void;
+	readonly serverClosed?: () => void;
+	readonly fileChanged?: (filePath: string) => void;
+	readonly docsReloaded?: () => void;
+}

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

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

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

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

package/src/modules/search/application/usecases/indexPages.ts

@@ -0,0 +1,15 @@
+/**
+ * Use case: index all doc pages into a searchable structure.
+ */
+
+import type { DocPage } from "@create-docs/modules/content";
+import type { AppError } from "@create-docs/shared/errors";
+import { ok, type Result } from "@create-docs/shared/types/result";
+import { buildSearchIndex } from "../../domain/operations/buildIndex";
+import type { SearchIndex } from "../../types";
+
+export type IndexPages = (
+	pages: readonly DocPage[],
+) => Result<SearchIndex, AppError>;
+
+export const indexPages: IndexPages = (pages) => ok(buildSearchIndex(pages));

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

@@ -0,0 +1,32 @@
+export type SearchEvent =
+	| { readonly type: "search.index_built"; readonly entriesCount: number }
+	| {
+			readonly type: "search.index_rebuilt";
+			readonly reason: "content_changed" | "config_changed" | "manual";
+	  }
+	| {
+			readonly type: "search.query_executed";
+			readonly term: string;
+			readonly hits: number;
+	  };
+
+export const searchIndexBuilt = (entriesCount: number): SearchEvent => ({
+	type: "search.index_built",
+	entriesCount,
+});
+
+export const searchIndexRebuilt = (
+	reason: "content_changed" | "config_changed" | "manual",
+): SearchEvent => ({
+	type: "search.index_rebuilt",
+	reason,
+});
+
+export const searchQueryExecuted = (
+	term: string,
+	hits: number,
+): SearchEvent => ({
+	type: "search.query_executed",
+	term,
+	hits,
+});

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

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

package/src/modules/search/domain/operations/build-index.ts

@@ -0,0 +1,6 @@
+export {
+	buildSearchIndex,
+	pageToSearchEntry,
+	plainText,
+	tokenize,
+} from "./buildIndex";

package/src/modules/search/domain/operations/buildIndex.ts

@@ -0,0 +1,70 @@
+/**
+ * Pure operations for building and querying a search index.
+ */
+
+import type { DocPage } from "@create-docs/modules/content";
+import { SEARCH_CONTENT_LIMIT } from "@create-docs/shared/constants";
+import { truncate } from "@create-docs/shared/utils/string";
+import type { SearchEntry, SearchIndex } from "../../types";
+
+export const pageToSearchEntry = (page: DocPage): SearchEntry => {
+	const text = plainText(page.content);
+	const terms = tokenize(`${page.title} ${page.description ?? ""} ${text}`);
+	return {
+		id: String(page.id),
+		slug: String(page.slug),
+		title: page.title,
+		description: page.description ?? "",
+		content: truncate(text, SEARCH_CONTENT_LIMIT, ""),
+		terms,
+	};
+};
+
+export const buildSearchIndex = (pages: readonly DocPage[]): SearchIndex => {
+	const entries = pages.map(pageToSearchEntry);
+	const inverted: Record<string, string[]> = {};
+	let totalLength = 0;
+	for (const e of entries) {
+		const seen = new Set<string>();
+		for (const term of e.terms) {
+			if (seen.has(term)) continue;
+			seen.add(term);
+			const list = inverted[term] ?? [];
+			list.push(e.id);
+			inverted[term] = list;
+		}
+		totalLength += e.terms.length;
+	}
+	return {
+		entries,
+		inverted,
+		avgDocLength: entries.length === 0 ? 0 : totalLength / entries.length,
+	};
+};
+
+/** Strip markdown formatting for full-text search. */
+export const plainText = (md: string): string =>
+	md
+		.replace(/```[\s\S]*?```/g, " ") // fenced code
+		.replace(/~~~[\s\S]*?~~~/g, " ") // tilde code
+		.replace(/`[^`\n]*`/g, " ") // inline code
+		.replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1") // images
+		.replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") // links
+		.replace(/^#{1,6}\s+/gm, "") // headings
+		.replace(/^\s*[-*+]\s+/gm, "") // bullets
+		.replace(/^\s*\d+\.\s+/gm, "") // ordered list
+		.replace(/^>\s?/gm, "") // blockquote
+		.replace(/[*_~]+/g, "") // emphasis
+		.replace(/\s+/g, " ")
+		.trim();
+
+/** Tokenize a string into lowercase terms (length >= 2), stripping diacritics. */
+export const tokenize = (s: string): string[] => {
+	if (s.length === 0) return [];
+	return s
+		.toLowerCase()
+		.normalize("NFD")
+		.replace(/[\u0300-\u036f]/g, "")
+		.split(/[^\p{Letter}\p{Number}]+/u)
+		.filter((t) => t.length >= 2);
+};

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

@@ -0,0 +1,7 @@
+export {
+	buildSearchIndex,
+	pageToSearchEntry,
+	plainText,
+	tokenize,
+} from "./buildIndex";
+export { levenshtein, search } from "./query";

package/src/modules/search/domain/operations/query.ts

@@ -0,0 +1,186 @@
+/**
+ * Pure search query operations.
+ *
+ * Scoring = BM25-lite over tokenized terms + title prefix boost + Levenshtein
+ * fuzzy fallback (distance <= 2) when the literal term is not found.
+ */
+
+import type { SearchEntry, SearchIndex } from "../../types";
+import { tokenize } from "./buildIndex";
+
+export interface SearchQuery {
+	readonly term: string;
+	readonly limit?: number;
+	/** When true, allow fuzzy (Levenshtein <=2) fallback. Default: true. */
+	readonly fuzzy?: boolean;
+}
+
+export interface SearchHit {
+	readonly entry: SearchEntry;
+	readonly score: number;
+}
+
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+const TITLE_BOOST = 5;
+const PREFIX_BOOST = 2;
+const FUZZY_PENALTY = 0.5;
+export const levenshtein = (a: string, b: string, max = 3): number => {
+	if (a === b) return 0;
+	const la = a.length;
+	const lb = b.length;
+	if (Math.abs(la - lb) > max) return max + 1;
+	if (la === 0) return lb;
+	if (lb === 0) return la;
+	const prev: number[] = new Array<number>(lb + 1);
+	const curr: number[] = new Array<number>(lb + 1);
+	for (let j = 0; j <= lb; j++) prev[j] = j;
+	for (let i = 1; i <= la; i++) {
+		curr[0] = i;
+		let rowMin = curr[0] ?? i;
+		for (let j = 1; j <= lb; j++) {
+			const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+			const c1 = (curr[j - 1] ?? 0) + 1;
+			const c2 = (prev[j] ?? 0) + 1;
+			const c3 = (prev[j - 1] ?? 0) + cost;
+			curr[j] = Math.min(c1, c2, c3);
+			const v = curr[j];
+			if (v !== undefined && v < rowMin) rowMin = v;
+		}
+		if (rowMin > max) return max + 1;
+		for (let j = 0; j <= lb; j++) {
+			const v = curr[j];
+			if (v !== undefined) prev[j] = v;
+		}
+	}
+	return prev[lb] ?? 0;
+};
+
+const bm25 = (
+	tf: number,
+	df: number,
+	docLength: number,
+	avgDocLength: number,
+	totalDocs: number,
+): number => {
+	if (tf === 0) return 0;
+	const idf = Math.log(1 + (totalDocs - df + 0.5) / (df + 0.5));
+	const norm = 1 - BM25_B + (BM25_B * docLength) / Math.max(1, avgDocLength);
+	return idf * ((tf * (BM25_K1 + 1)) / (tf + BM25_K1 * norm));
+};
+
+/** Case-insensitive, tokenized search with BM25-lite scoring. */
+export const search = (
+	index: SearchIndex,
+	query: SearchQuery,
+): readonly SearchHit[] => {
+	const rawTerm = query.term.trim();
+	if (rawTerm.length === 0) return [];
+	const fuzzy = query.fuzzy !== false;
+	const limit = query.limit ?? 20;
+
+	const terms = tokenize(rawTerm);
+	if (terms.length === 0) return [];
+
+	const totalDocs = index.entries.length;
+	const avgDoc = index.avgDocLength;
+	const idToEntry = new Map<string, SearchEntry>();
+	for (const e of index.entries) idToEntry.set(e.id, e);
+
+	interface ScoredDoc {
+		score: number;
+		matchedExact: boolean;
+	}
+
+	const docScores = new Map<string, ScoredDoc>();
+
+	for (const term of terms) {
+		// 1. Exact term lookup
+		const exact = index.inverted[term];
+		if (exact) {
+			for (const id of exact) {
+				const entry = idToEntry.get(id);
+				if (!entry) continue;
+				let tf = 0;
+				for (const t of entry.terms) if (t === term) tf++;
+				const score = bm25(
+					tf,
+					exact.length,
+					entry.terms.length,
+					avgDoc,
+					totalDocs,
+				);
+				const prev = docScores.get(id);
+				docScores.set(id, {
+					score: (prev?.score ?? 0) + score,
+					matchedExact: prev?.matchedExact ?? true,
+				});
+			}
+			continue;
+		}
+
+		// 2. Fuzzy fallback: find the best matching key per candidate doc.
+		if (!fuzzy) continue;
+		const seen = new Set<string>();
+		const fuzzyHits: { id: string; matchedKey: string; dist: number }[] = [];
+		for (const key of Object.keys(index.inverted)) {
+			if (Math.abs(key.length - term.length) > 2) continue;
+			const d = levenshtein(key, term, 2);
+			if (d <= 2) {
+				const list = index.inverted[key] ?? [];
+				for (const id of list) {
+					if (seen.has(id)) continue;
+					seen.add(id);
+					fuzzyHits.push({ id, matchedKey: key, dist: d });
+				}
+			}
+		}
+
+		// 3. Per candidate, find the closest matching term in the entry's own terms
+		//    so we can score via bm25 with a real tf.
+		for (const hit of fuzzyHits) {
+			const entry = idToEntry.get(hit.id);
+			if (!entry) continue;
+			// Reuse dist from index key (already a good proxy). Compute tf for that key.
+			let tf = 0;
+			for (const t of entry.terms) if (t === hit.matchedKey) tf++;
+			if (tf === 0) {
+				// Fallback: count how many entry terms are within distance 2 of the query term.
+				for (const t of entry.terms) {
+					if (Math.abs(t.length - term.length) > 2) continue;
+					if (levenshtein(t, term, 2) <= 2) tf++;
+				}
+			}
+			const score =
+				bm25(tf, fuzzyHits.length, entry.terms.length, avgDoc, totalDocs) *
+				FUZZY_PENALTY;
+			const prev = docScores.get(hit.id);
+			docScores.set(hit.id, {
+				score: (prev?.score ?? 0) + score,
+				matchedExact: prev?.matchedExact ?? false,
+			});
+		}
+	}
+
+	// Title boost: substring or prefix match on the title gets extra weight.
+	for (const e of index.entries) {
+		const cur = docScores.get(e.id);
+		if (!cur || cur.score === 0) continue;
+		const titleLow = e.title.toLowerCase();
+		if (titleLow.includes(rawTerm.toLowerCase())) {
+			cur.score += TITLE_BOOST;
+		}
+		if (titleLow.startsWith(terms[0] ?? "")) {
+			cur.score += PREFIX_BOOST;
+		}
+	}
+
+	const hits: SearchHit[] = [];
+	for (const [id, cur] of docScores.entries()) {
+		if (cur.score <= 0) continue;
+		const entry = idToEntry.get(id);
+		if (entry) hits.push({ entry, score: cur.score });
+	}
+	hits.sort((a, b) => b.score - a.score);
+	return hits.slice(0, limit);
+};

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

@@ -0,0 +1,32 @@
+// Search Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { validationError } from "@create-docs/shared/errors";
+import { err, ok, type Result } from "@create-docs/shared/types/result";
+import { type Type, type } from "arktype";
+import type { SearchEntry } from "../../types";
+
+/**
+ * Search Entry Schema
+ */
+export const searchEntrySchema: Type = type({
+	id: "string >= 1",
+	slug: "string >= 1",
+	title: "string >= 1",
+});
+
+export type SearchEntrySchema = typeof searchEntrySchema.infer;
+
+/**
+ * Validate search entry using Arktype
+ */
+export const validateSearchEntry = (
+	e: SearchEntry,
+	path: string,
+): Result<SearchEntry, ReturnType<typeof validationError>> => {
+	const result = searchEntrySchema(e);
+	if (result instanceof type.errors) {
+		return err(validationError(result.summary, { path }));
+	}
+	return ok(e);
+};

package/src/modules/search/index.ts

@@ -0,0 +1,9 @@
+export * from "./application/usecases";
+export {
+	searchIndexBuilt,
+	searchIndexRebuilt,
+	searchQueryExecuted,
+} from "./domain/events";
+export * from "./domain/operations";
+export { validateSearchEntry } from "./domain/validators";
+export * from "./types/public";

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

@@ -0,0 +1,22 @@
+import type { Brand } from "@create-docs/shared/types";
+
+export type SearchDocId = Brand<string, "SearchDocId">;
+export const SearchDocId = (s: string): SearchDocId => s as SearchDocId;
+
+export interface SearchEntry {
+	readonly id: string;
+	readonly slug: string;
+	readonly title: string;
+	readonly description: string;
+	readonly content: string;
+	/** Pre-tokenized content terms (lowercase, length >= 2). */
+	readonly terms: readonly string[];
+}
+
+export interface SearchIndex {
+	readonly entries: readonly SearchEntry[];
+	/** Token → entry ids that contain it (BM25-ready). */
+	readonly inverted: Readonly<Record<string, readonly string[]>>;
+	/** Average document length across the corpus (used by BM25). */
+	readonly avgDocLength: number;
+}

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

@@ -0,0 +1 @@
+export type { SearchDocId, SearchEntry, SearchIndex } from "./index";

package/src/modules/search-analytics/application/local-storage-adapter.ts

@@ -0,0 +1,68 @@
+/**
+ * Local storage adapter implementation.
+ * Provides search analytics using browser local storage.
+ */
+
+import type { SearchAnalyticsPort } from "../ports/search-analytics-port";
+import type { SearchEvent } from "../types/search-analytics";
+
+const STORAGE_KEY = "search-analytics-events";
+const MAX_EVENTS = 1000;
+
+export const createLocalStorageAdapter = (): SearchAnalyticsPort => ({
+	trackEvent: async (event: SearchEvent, _config?: unknown) => {
+		if (typeof window === "undefined") {
+			return;
+		}
+
+		try {
+			const stored = localStorage.getItem(STORAGE_KEY);
+			const events: SearchEvent[] = stored ? JSON.parse(stored) : [];
+
+			events.push(event);
+
+			if (events.length > MAX_EVENTS) {
+				events.shift();
+			}
+
+			localStorage.setItem(STORAGE_KEY, JSON.stringify(events));
+		} catch (error) {
+			console.error("Failed to track search event:", error);
+		}
+	},
+
+	getAnalytics: async (dateRange?: unknown, _config?: unknown) => {
+		if (typeof window === "undefined") {
+			return [];
+		}
+
+		try {
+			const stored = localStorage.getItem(STORAGE_KEY);
+			if (!stored) {
+				return [];
+			}
+
+			const events: SearchEvent[] = JSON.parse(stored);
+
+			if (dateRange && typeof dateRange === "object") {
+				const { since, until } = dateRange as {
+					since?: string;
+					until?: string;
+				};
+				if (since || until) {
+					return events.filter((event) => {
+						const eventDate = new Date(event.timestamp);
+						if (since && eventDate < new Date(since)) return false;
+						if (until && eventDate > new Date(until)) return false;
+						return true;
+					});
+				}
+			}
+
+			return events;
+		} catch (error) {
+			console.error("Failed to get search analytics:", error);
+			return [];
+		}
+	},
+});

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

@@ -0,0 +1,74 @@
+/**
+ * Pure search 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 {
+	SearchAnalyticsConfig,
+	SearchEvent,
+} from "../../types/search-analytics";
+
+export type SearchAnalyticsError = {
+	readonly kind: "search-analytics-error";
+	readonly message: string;
+};
+
+/**
+ * Aggregate search queries by frequency.
+ */
+export const aggregateQueries = (
+	events: readonly SearchEvent[],
+): Result<Record<string, number>, SearchAnalyticsError> => {
+	try {
+		const counts: Record<string, number> = {};
+
+		for (const event of events) {
+			if (event.type === "query") {
+				const query = event.query.toLowerCase();
+				counts[query] = (counts[query] || 0) + 1;
+			}
+		}
+
+		return ok(counts);
+	} catch (error) {
+		return err({
+			kind: "search-analytics-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Calculate search success rate.
+ */
+export const calculateSuccessRate = (
+	events: readonly SearchEvent[],
+): Result<number, SearchAnalyticsError> => {
+	try {
+		const queryEvents = events.filter((e) => e.type === "query");
+		const noResultEvents = events.filter((e) => e.type === "no-results");
+
+		if (queryEvents.length === 0) return ok(100);
+
+		const successRate =
+			((queryEvents.length - noResultEvents.length) / queryEvents.length) * 100;
+		return ok(successRate);
+	} catch (error) {
+		return err({
+			kind: "search-analytics-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Validate search analytics config.
+ */
+export const validateSearchAnalyticsConfig = (
+	config: SearchAnalyticsConfig,
+): boolean => {
+	if (!config.enabled) return false;
+	return true;
+};

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

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

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

@@ -0,0 +1,20 @@
+/**
+ * Port for search analytics operations.
+ */
+
+import type { SearchEvent } from "../types/search-analytics";
+
+export type SearchAnalyticsPort = {
+	/**
+	 * Track search event.
+	 */
+	readonly trackEvent: (event: SearchEvent, config: unknown) => Promise<void>;
+
+	/**
+	 * Get search analytics data.
+	 */
+	readonly getAnalytics: (
+		dateRange: unknown,
+		config: unknown,
+	) => Promise<readonly SearchEvent[]>;
+};

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

@@ -0,0 +1,16 @@
+/**
+ * Search analytics types for tracking search behavior.
+ */
+
+export type SearchAnalyticsConfig = {
+	readonly enabled: boolean;
+	readonly trackQueries: boolean;
+	readonly trackClicks: boolean;
+};
+
+export type SearchEvent = {
+	readonly type: "query" | "click" | "no-results";
+	readonly query: string;
+	readonly timestamp: string;
+	readonly resultCount?: number;
+};