@wrikka/create-docs 0.1.0

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

@@ -0,0 +1,111 @@
+/**
+ * Use case: load a single doc file by its slug and produce a DocPage.
+ * Orchestrates FS read → frontmatter parse → DocPage build.
+ */
+
+import type { AppError } from "@create-docs/shared/errors";
+import { fileNotFound, parseError } from "@create-docs/shared/errors";
+import { err, ok, type Result } from "@create-docs/shared/types/result";
+import { toPosixPath } from "@create-docs/shared/utils/string";
+import { buildDocPage } from "../../domain/operations/build-page";
+import {
+	isMarkdownFile,
+	parseFrontmatter,
+} from "../../domain/operations/parse";
+import type { FileReader } from "../../ports";
+import type { DocPage } from "../../types";
+import { FilePath } from "../../types";
+import type { ParseCache } from "../cache";
+
+export interface LoadDocPageDeps {
+	readonly reader: FileReader;
+	readonly docsDir: string;
+	readonly slug: string;
+	/** Optional edit-link config; if absent, no editUrl is attached. */
+	readonly editLink?: {
+		readonly enabled?: boolean;
+		readonly baseUrl?: string;
+		readonly branch?: string;
+	};
+	/** Optional mtime+size keyed cache. When provided, unchanged files are reused. */
+	readonly cache?: ParseCache<DocPage>;
+}
+
+export const loadDocPage = async (
+	deps: LoadDocPageDeps,
+): Promise<Result<DocPage, AppError>> => {
+	const { reader, docsDir, slug, editLink, cache } = deps;
+	const filePath = `${toPosixPath(docsDir).replace(/\/$/, "")}/${slug}.md`;
+	const fp = FilePath(filePath);
+	const exists = await reader.exists(fp);
+	if (!exists) {
+		const mdocPath = FilePath(
+			`${toPosixPath(docsDir).replace(/\/$/, "")}/${slug}.mdoc`,
+		);
+		const mdocExists = await reader.exists(mdocPath);
+		if (!mdocExists) return err(fileNotFound(filePath));
+		return readAndBuild(reader, mdocPath, slug, editLink, cache);
+	}
+	return readAndBuild(reader, fp, slug, editLink, cache);
+};
+
+const readAndBuild = async (
+	reader: FileReader,
+	filePath: FilePath,
+	slug: string,
+	editLink: LoadDocPageDeps["editLink"],
+	cache: ParseCache<DocPage> | undefined,
+): Promise<Result<DocPage, AppError>> => {
+	const statResult = await reader.stat(filePath);
+	if (statResult.ok && cache) {
+		const key = `${filePath}@${statResult.value.mtimeMs.toFixed(0)}:${statResult.value.size}`;
+		const hit = cache.get(key);
+		if (hit) return ok(hit);
+	}
+	const readResult = await reader.read(filePath);
+	if (!readResult.ok) return readResult;
+	const raw = readResult.value;
+	const fileName = filePath.split(/[/\\]/).pop() ?? "";
+	if (!isMarkdownFile(fileName)) {
+		return err(parseError(filePath, "Not a markdown file"));
+	}
+	const parsed = parseFrontmatter(raw);
+	const lastModifiedMs = statResult.ok ? statResult.value.mtimeMs : undefined;
+	const editUrl = computeEditUrl(String(filePath), editLink);
+	const page = buildDocPage({
+		slug,
+		filePath,
+		parsed,
+		...(lastModifiedMs !== undefined ? { lastModifiedMs } : {}),
+		...(editUrl !== undefined ? { editUrl } : {}),
+	});
+	if (statResult.ok && cache) {
+		const key = `${filePath}@${statResult.value.mtimeMs.toFixed(0)}:${statResult.value.size}`;
+		cache.set(key, page);
+	}
+	return ok(page);
+};
+
+const computeEditUrl = (
+	filePath: string,
+	editLink: LoadDocPageDeps["editLink"],
+): string | undefined => {
+	if (!editLink || editLink.enabled === false) return undefined;
+	const base = editLink.baseUrl ?? "";
+	if (base.length === 0) return undefined;
+	const branch = editLink.branch ?? "main";
+	const posix = filePath.replace(/\\/g, "/");
+	const trimmed = posix.replace(/^\/+/, "");
+	const tail = trimmed.startsWith("docs/") ? trimmed.slice(5) : trimmed;
+	return `${base.replace(/\/$/, "")}/edit/${branch}/${tail}`;
+};
+
+/** Load a doc page from raw content directly (test-friendly, no FS). */
+export const buildDocPageFromRaw = (
+	slug: string,
+	filePath: string,
+	raw: string,
+): Result<DocPage, AppError> => {
+	const parsed = parseFrontmatter(raw);
+	return ok(buildDocPage({ slug, filePath, parsed }));
+};

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

@@ -0,0 +1,105 @@
+/**
+ * Use case: scan a docs directory and produce a list of DocFile descriptors.
+ *
+ * This is the orchestration glue between the FS adapter and the pure domain
+ * operations. It does no I/O itself — it only sequences calls through ports.
+ */
+
+import type { AppError } from "@create-docs/shared/errors";
+import { fileNotFound } from "@create-docs/shared/errors";
+import { err, ok, type Result } from "@create-docs/shared/types/result";
+import { toPosixPath } from "@create-docs/shared/utils/string";
+import {
+	extractGroup,
+	isMarkdownFile,
+	slugToId,
+	stripMarkdownExt,
+} from "../../domain/operations/parse";
+import type { DirectoryScanner, FileReader } from "../../ports";
+import type { DocFile } from "../../types";
+import { DocId, DocSlug, FilePath } from "../../types";
+
+export interface ScanDocsDirDeps {
+	readonly scanner: DirectoryScanner;
+	readonly reader: FileReader;
+	readonly docsDir: string;
+}
+
+export const scanDocsDir = async (
+	deps: ScanDocsDirDeps,
+): Promise<Result<readonly DocFile[], AppError>> => {
+	const { scanner, reader, docsDir } = deps;
+	const rootExists = await reader.exists(FilePath(docsDir));
+	if (!rootExists) return err(fileNotFound(docsDir));
+
+	const files = await collectFiles(scanner, docsDir);
+	const docs: DocFile[] = [];
+	for (const filePath of files) {
+		const readResult = await reader.read(FilePath(filePath));
+		if (!readResult.ok) continue; // skip unreadable files; an event can be raised elsewhere
+		const raw = readResult.value;
+
+		// Only parse .md/.mdoc files; the extension check is also a safety guard.
+		const fileName = filePath.split(/[/\\]/).pop() ?? "";
+		if (!isMarkdownFile(fileName)) continue;
+
+		const relPath = toPosixPath(filePath)
+			.slice(toPosixPath(docsDir).length)
+			.replace(/^\//, "");
+		const slug = stripMarkdownExt(relPath);
+		const id = DocId(slugToId(slug));
+		const group = extractGroup(slug);
+
+		// Lazy frontmatter extract — only the order field is needed at scan time.
+		// Full parse happens in the loadContent use case.
+		const order = extractQuickOrder(raw);
+
+		docs.push({
+			id,
+			slug: DocSlug(slug),
+			frontmatter: {},
+			rawContent: raw,
+			filePath: FilePath(filePath),
+			...(group !== undefined ? { group } : {}),
+			order,
+		});
+	}
+	docs.sort((a, b) => a.order - b.order);
+	return ok(docs);
+};
+
+const extractQuickOrder = (raw: string): number => {
+	const lines = raw.split("\n");
+	if (lines[0]?.trim() !== "---") return Number.MAX_SAFE_INTEGER;
+	let end = -1;
+	for (let i = 1; i < lines.length; i++) {
+		if (lines[i]?.trim() === "---") {
+			end = i;
+			break;
+		}
+	}
+	if (end === -1) return Number.MAX_SAFE_INTEGER;
+	for (let i = 1; i < end; i++) {
+		const line = lines[i] ?? "";
+		const m = line.match(/^order:\s*(\d+)/);
+		if (m?.[1]) return Number.parseInt(m[1], 10);
+	}
+	return Number.MAX_SAFE_INTEGER;
+};
+
+const collectFiles = async (
+	scanner: DirectoryScanner,
+	dir: string,
+): Promise<string[]> => {
+	const result = await scanner.list(dir);
+	if (!result.ok) return [];
+	const out: string[] = [];
+	for (const entry of result.value) {
+		if (entry.isDirectory) {
+			out.push(...(await collectFiles(scanner, entry.path)));
+		} else if (isMarkdownFile(entry.name)) {
+			out.push(entry.path);
+		}
+	}
+	return out;
+};

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

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

package/src/modules/content/application/workflows/processDocs.ts

@@ -0,0 +1,51 @@
+/**
+ * Workflow: process all docs in a directory into fully-built DocPages.
+ * Used by the Vite plugin's `load(id)` virtual modules.
+ */
+
+import type { AppError } from "@create-docs/shared/errors";
+import { ok, type Result } from "@create-docs/shared/types/result";
+import type { DirectoryScanner, FileReader } from "../../ports";
+import type { DocPage } from "../../types";
+import type { ParseCache } from "../cache";
+import { loadDocPage } from "../usecases/loadDocPage";
+import { scanDocsDir } from "../usecases/scanDocsDir";
+
+export interface ProcessDocsWorkflowDeps {
+	readonly scanner: DirectoryScanner;
+	readonly reader: FileReader;
+	readonly docsDir: string;
+	/** Optional edit-link config; threaded into per-page editUrl computation. */
+	readonly editLink?: {
+		readonly enabled?: boolean;
+		readonly baseUrl?: string;
+		readonly branch?: string;
+	};
+	/** Optional mtime+size cache, shared across reloads. */
+	readonly cache?: ParseCache<DocPage>;
+}
+
+export const processDocsWorkflow = async (
+	deps: ProcessDocsWorkflowDeps,
+): Promise<Result<readonly DocPage[], AppError>> => {
+	const scanned = await scanDocsDir({
+		scanner: deps.scanner,
+		reader: deps.reader,
+		docsDir: deps.docsDir,
+	});
+	if (!scanned.ok) return scanned;
+
+	const pages: DocPage[] = [];
+	for (const file of scanned.value) {
+		const slug = typeof file.slug === "string" ? file.slug : String(file.slug);
+		const pageResult = await loadDocPage({
+			reader: deps.reader,
+			docsDir: deps.docsDir,
+			slug,
+			...(deps.editLink !== undefined ? { editLink: deps.editLink } : {}),
+			...(deps.cache !== undefined ? { cache: deps.cache } : {}),
+		});
+		if (pageResult.ok) pages.push(pageResult.value);
+	}
+	return ok(pages);
+};

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

@@ -0,0 +1,61 @@
+/**
+ * Domain events — pure event types. No handlers, no I/O.
+ * Handlers live in presentation/events.
+ */
+import type { DocPage, FilePath } from "../../types";
+
+export type ContentEvent =
+	| {
+			readonly type: "content.discovered";
+			readonly filePath: FilePath;
+			readonly slug: string;
+	  }
+	| { readonly type: "content.parsed"; readonly page: DocPage }
+	| { readonly type: "content.changed"; readonly filePath: FilePath }
+	| {
+			readonly type: "content.removed";
+			readonly filePath: FilePath;
+			readonly slug: string;
+	  }
+	| {
+			readonly type: "content.parse_failed";
+			readonly filePath: FilePath;
+			readonly reason: string;
+	  };
+
+export const contentDiscovered = (
+	filePath: FilePath,
+	slug: string,
+): ContentEvent => ({
+	type: "content.discovered",
+	filePath,
+	slug,
+});
+
+export const contentParsed = (page: DocPage): ContentEvent => ({
+	type: "content.parsed",
+	page,
+});
+
+export const contentChanged = (filePath: FilePath): ContentEvent => ({
+	type: "content.changed",
+	filePath,
+});
+
+export const contentRemoved = (
+	filePath: FilePath,
+	slug: string,
+): ContentEvent => ({
+	type: "content.removed",
+	filePath,
+	slug,
+});
+
+export const contentParseFailed = (
+	filePath: FilePath,
+	reason: string,
+): ContentEvent => ({
+	type: "content.parse_failed",
+	filePath,
+	reason,
+});

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

@@ -0,0 +1,13 @@
+/**
+ * Domain models — pure data shapes, no behavior.
+ * Re-exported for module consumers; the canonical source is `types/`.
+ */
+export type {
+	DocFile,
+	DocId,
+	DocPage,
+	DocSlug,
+	FilePath,
+	Frontmatter,
+	ParsedContent,
+} from "../../types";

package/src/modules/content/domain/operations/build-page.ts

@@ -0,0 +1,146 @@
+/**
+ * Pure domain operation for constructing a DocPage from parsed markdown.
+ */
+
+import { toPosixPath } from "@create-docs/shared/utils/string";
+import type { DocPage, Frontmatter, ParsedContent, TocItem } from "../../types";
+import { DocId, DocSlug, FilePath } from "../../types";
+
+export interface BuildDocPageInput {
+	slug: string;
+	filePath: string;
+	parsed: ParsedContent;
+	lastModifiedMs?: number;
+	editUrl?: string;
+}
+
+export interface EditLinkConfig {
+	readonly enabled?: boolean;
+	readonly baseUrl?: string;
+	readonly branch?: string;
+}
+
+const parseToc = (content: string): readonly TocItem[] => {
+	const headings: TocItem[] = [];
+	const seen = new Set<string>();
+	for (const line of content.split(/\r?\n/)) {
+		const match = line.match(/^(#{1,6})\s+(.+)$/);
+		if (!match) continue;
+		const depth = match[1].length as TocItem["depth"];
+		const rawText = match[2].trim();
+		// Strip markdown links, emphasis, and inline code markers.
+		const text = rawText
+			.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+			.replace(/[*_`]/g, "");
+		let id = text
+			.toLowerCase()
+			.replace(/[^a-z0-9\s-]/g, "")
+			.replace(/\s+/g, "-")
+			.replace(/-+/g, "-")
+			.replace(/^-+|-+$/g, "");
+		if (!id) id = `heading-${headings.length}`;
+		if (seen.has(id)) {
+			let suffix = 1;
+			let candidate = `${id}-${suffix}`;
+			while (seen.has(candidate)) {
+				suffix++;
+				candidate = `${id}-${suffix}`;
+			}
+			id = candidate;
+		}
+		seen.add(id);
+		headings.push({ id, text, depth });
+	}
+	return headings;
+};
+
+const deriveTitle = (
+	frontmatter: Frontmatter,
+	filePath: string,
+	slug: string,
+): string => {
+	if (typeof frontmatter.title === "string" && frontmatter.title.trim()) {
+		return frontmatter.title.trim();
+	}
+	const name = filePath.split(/[/\\]/).pop() ?? slug;
+	const withoutExt = name.replace(/\.mdx?$/i, "");
+	const last = withoutExt.replace(/[-_]/g, " ").split(" ").pop() ?? withoutExt;
+	return last.charAt(0).toUpperCase() + last.slice(1);
+};
+
+const deriveGroup = (
+	frontmatter: Frontmatter,
+	slug: string,
+): string | undefined => {
+	if (typeof frontmatter.category === "string" && frontmatter.category.trim()) {
+		return frontmatter.category.trim();
+	}
+	const firstSegment = slug.split("/")[0];
+	if (firstSegment && firstSegment !== slug) {
+		return firstSegment;
+	}
+	return undefined;
+};
+
+const computeMetadata = (
+	content: string,
+	lastModifiedMs: number | undefined,
+	editUrl: string | undefined,
+): DocPage["metadata"] => {
+	const words = content
+		.replace(/[#*_`[\](){}|]/g, " ")
+		.split(/\s+/)
+		.filter((w) => w.length > 0).length;
+	const readingTime = Math.max(1, Math.round(words / 200));
+	const metadata: DocPage["metadata"] = {
+		readingTime,
+		wordCount: words,
+		...(lastModifiedMs !== undefined
+			? { lastModified: new Date(lastModifiedMs).toISOString() }
+			: {}),
+		...(editUrl !== undefined ? { editUrl } : {}),
+	};
+	return metadata;
+};
+
+export const buildEditUrl = (
+	filePath: string,
+	editLink: EditLinkConfig,
+): string | undefined => {
+	if (editLink.enabled === false) return undefined;
+	const base = editLink.baseUrl ?? "";
+	if (base.length === 0) return undefined;
+	const branch = editLink.branch ?? "main";
+	const posix = toPosixPath(filePath).replace(/^\/+/, "");
+	const tail = posix.startsWith("docs/") ? posix.slice(5) : posix;
+	return `${base.replace(/\/$/, "")}/edit/${branch}/${tail}`;
+};
+
+export const buildDocPage = (input: BuildDocPageInput): DocPage => {
+	const { slug, filePath, parsed, lastModifiedMs, editUrl } = input;
+	const title = deriveTitle(parsed.frontmatter, filePath, slug);
+	const description =
+		typeof parsed.frontmatter.description === "string"
+			? parsed.frontmatter.description
+			: undefined;
+	const group = deriveGroup(parsed.frontmatter, slug);
+	const order =
+		typeof parsed.frontmatter.order === "number" ? parsed.frontmatter.order : 0;
+	const toc = parseToc(parsed.content);
+	const id = slug.replace(/\//g, "-");
+
+	return {
+		id: DocId(id),
+		slug: DocSlug(slug),
+		title,
+		description,
+		frontmatter: parsed.frontmatter,
+		content: parsed.content,
+		rawContent: parsed.rawContent,
+		filePath: FilePath(filePath),
+		group,
+		order,
+		toc,
+		metadata: computeMetadata(parsed.content, lastModifiedMs, editUrl),
+	};
+};

package/src/modules/content/domain/operations/buildPage.ts

@@ -0,0 +1,93 @@
+/**
+ * Pure operations for normalizing a parsed content into a DocPage model.
+ * No I/O, no exceptions.
+ */
+
+import type { DocPage, Frontmatter, ParsedContent } from "../../types";
+import { DocId, DocSlug, FilePath } from "../../types";
+import {
+	countWords,
+	estimateReadingTime,
+	extractDescription,
+	extractGroup,
+	extractOrder,
+	extractTitle,
+	extractToc,
+	plainText,
+	slugToId,
+} from "./parse";
+
+export interface BuildDocPageInput {
+	readonly slug: string;
+	readonly filePath: string;
+	readonly parsed: ParsedContent;
+	/** Optional mtime (ms since epoch) from the underlying FS. */
+	readonly lastModifiedMs?: number;
+	/** Optional per-page edit URL (resolved from config.editLink). */
+	readonly editUrl?: string;
+}
+
+export const buildDocPage = ({
+	slug,
+	filePath,
+	parsed,
+	lastModifiedMs,
+	editUrl,
+}: BuildDocPageInput): DocPage => {
+	const { frontmatter, content, rawContent } = parsed;
+	const id = DocId(slugToId(slug));
+	const group = extractGroup(slug);
+	const text = plainText(content);
+	const wordCount = countWords(text);
+	const readingTime = estimateReadingTime(wordCount);
+	const toc = extractToc(content);
+	const metadata: DocPage["metadata"] = {
+		readingTime,
+		wordCount,
+		...(lastModifiedMs !== undefined
+			? { lastModified: new Date(lastModifiedMs).toISOString() }
+			: {}),
+		...(editUrl !== undefined ? { editUrl } : {}),
+	};
+	return {
+		id,
+		slug: DocSlug(slug),
+		title: extractTitle(frontmatter, slug),
+		...maybeDescription(frontmatter),
+		frontmatter,
+		content,
+		rawContent,
+		filePath: FilePath(filePath),
+		...(group !== undefined ? { group } : {}),
+		order: extractOrder(frontmatter),
+		toc,
+		metadata,
+	};
+};
+
+const maybeDescription = (
+	f: Frontmatter,
+): { description: string } | Record<string, never> => {
+	const d = extractDescription(f);
+	return d !== undefined ? { description: d } : {};
+};
+
+/** Compute an edit URL for a file path from the edit-link config. */
+export const buildEditUrl = (
+	filePath: string,
+	editLink:
+		| { enabled?: boolean; baseUrl?: string; branch?: string }
+		| undefined,
+): string | undefined => {
+	if (!editLink || editLink.enabled === false) return undefined;
+	const base = editLink.baseUrl ?? "";
+	if (base.length === 0) return undefined;
+	const branch = editLink.branch ?? "main";
+	const posix = filePath.replace(/\\/g, "/");
+	const trimmed = posix.replace(/^\/+/, "");
+	const tail = trimmed.startsWith("docs/") ? trimmed.slice(5) : trimmed;
+	return `${stripTrailingSlash(base)}/edit/${branch}/${tail}`;
+};
+
+const stripTrailingSlash = (s: string): string =>
+	s.endsWith("/") ? s.slice(0, -1) : s;

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

@@ -0,0 +1,17 @@
+export { buildDocPage, buildEditUrl } from "./buildPage";
+export {
+	countWords,
+	estimateReadingTime,
+	extractDescription,
+	extractGroup,
+	extractOrder,
+	extractTitle,
+	extractToc,
+	isMarkdownFile,
+	parseFrontmatter,
+	parseFrontmatterBlock,
+	plainText,
+	slugifyHeading,
+	slugToId,
+	stripMarkdownExt,
+} from "./parse";