@wrikka/create-docs 0.1.0

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

@@ -0,0 +1,241 @@
+/**
+ * Pure frontmatter parser.
+ * No I/O. No exceptions thrown. Returns ParsedContent.
+ *
+ * Supports:
+ *   - Full YAML 1.2 via js-yaml adapter (nested objects, dates, anchors)
+ *   - Fallback to mini-parser for simple cases
+ *   - Scalar values: string, number, boolean, null
+ *   - Inline arrays: [a, b, c]
+ *   - List arrays:
+ *       tags:
+ *         - a
+ *         - b
+ *   - Quoted strings ("value" or 'value')
+ */
+import {
+	FRONTMATTER_DELIMITER,
+	SIDEBAR_DEFAULT_ORDER,
+} from "@create-docs/shared/constants";
+import { isString } from "@create-docs/shared/utils/object";
+import {
+	isBlank,
+	splitLines,
+	stripQuotes,
+	stripSuffix,
+} from "@create-docs/shared/utils/string";
+import { parseYaml } from "../../../yaml-parser/domain/operations/parse-yaml";
+import type { Frontmatter, ParsedContent, TocItem } from "../../types";
+
+const parseScalar = (raw: string): unknown => {
+	const value = stripQuotes(raw);
+	if (value === "true") return true;
+	if (value === "false") return false;
+	if (value === "null" || value === "~") return null;
+	if (value === "") return "";
+	if (/^-?\d+$/.test(value)) return Number.parseInt(value, 10);
+	if (/^-?\d*\.\d+$/.test(value)) return Number.parseFloat(value);
+	return value;
+};
+
+const parseInlineList = (raw: string): string[] => {
+	const inner = raw.slice(1, -1).trim();
+	if (inner.length === 0) return [];
+	return inner
+		.split(",")
+		.map((v) => stripQuotes(v.trim()))
+		.filter((v) => v.length > 0);
+};
+
+/** Parse a multi-line frontmatter block (without delimiters) into a typed object. */
+export const parseFrontmatterBlock = (
+	lines: readonly string[],
+): Frontmatter => {
+	const block = lines.join("\n");
+	const yamlResult = parseYaml(block);
+
+	if (
+		yamlResult.ok &&
+		typeof yamlResult.value === "object" &&
+		yamlResult.value !== null
+	) {
+		return yamlResult.value as Frontmatter;
+	}
+
+	// Fallback to mini-parser for simple cases
+	const out: Record<string, unknown> = {};
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i] ?? "";
+		const trimmed = line.trim();
+		if (trimmed.length === 0 || trimmed.startsWith("#")) {
+			i++;
+			continue;
+		}
+
+		const colonIdx = line.indexOf(":");
+		if (colonIdx < 0) {
+			i++;
+			continue;
+		}
+
+		const key = line.slice(0, colonIdx).trim();
+		const rest = line.slice(colonIdx + 1).trim();
+
+		if (rest === "" || rest === "|" || rest === ">") {
+			// List array starting on next line(s)
+			const items: string[] = [];
+			i++;
+			while (i < lines.length) {
+				const next = lines[i] ?? "";
+				if (!next.trim().startsWith("-")) break;
+				items.push(stripQuotes(next.trim().slice(1).trim()));
+				i++;
+			}
+			if (items.length > 0) out[key] = items;
+			continue;
+		}
+
+		if (rest.startsWith("[") && rest.endsWith("]")) {
+			out[key] = parseInlineList(rest);
+		} else {
+			out[key] = parseScalar(rest);
+		}
+		i++;
+	}
+	return out as Frontmatter;
+};
+
+/** Parse a raw markdown file's contents, separating frontmatter from body. */
+export const parseFrontmatter = (raw: string): ParsedContent => {
+	const lines = splitLines(raw);
+	if (lines[0]?.trim() !== FRONTMATTER_DELIMITER) {
+		return { frontmatter: {}, content: raw, rawContent: raw };
+	}
+
+	let endIdx = -1;
+	for (let i = 1; i < lines.length; i++) {
+		if (lines[i]?.trim() === FRONTMATTER_DELIMITER) {
+			endIdx = i;
+			break;
+		}
+	}
+
+	if (endIdx === -1) {
+		return { frontmatter: {}, content: raw, rawContent: raw };
+	}
+
+	const fmLines = lines.slice(1, endIdx);
+	const contentLines = lines.slice(endIdx + 1);
+	const frontmatter = parseFrontmatterBlock(fmLines);
+	const content = contentLines.join("\n");
+
+	return { frontmatter, content, rawContent: raw };
+};
+
+/** Extract a title from frontmatter or fall back to slug tail. */
+export const extractTitle = (
+	frontmatter: Frontmatter,
+	slug: string,
+): string => {
+	if (isString(frontmatter.title) && !isBlank(frontmatter.title)) {
+		return frontmatter.title;
+	}
+	const parts = slug.split("/");
+	return parts[parts.length - 1] ?? slug;
+};
+
+/** Extract a numeric order from frontmatter; default = SIDEBAR_DEFAULT_ORDER. */
+export const extractOrder = (frontmatter: Frontmatter): number => {
+	const o = frontmatter.order;
+	return typeof o === "number" && Number.isFinite(o)
+		? o
+		: SIDEBAR_DEFAULT_ORDER;
+};
+
+/** First path segment of a slug, used for grouping in sidebar. */
+export const extractGroup = (slug: string): string | undefined => {
+	const parts = slug.split("/");
+	return parts.length > 1 ? parts[0] : undefined;
+};
+
+/** Generate a deterministic id from a slug. */
+export const slugToId = (slug: string): string =>
+	slug.replace(/[/\\]/g, "-").replace(/^-/, "");
+
+/** Strip `.md` or `.mdoc` extension from a file name. */
+export const stripMarkdownExt = (fileName: string): string =>
+	stripSuffix(stripSuffix(fileName, ".mdoc"), ".md");
+
+/** Determine if a file name has a supported markdown extension. */
+export const isMarkdownFile = (fileName: string): boolean =>
+	fileName.endsWith(".md") || fileName.endsWith(".mdoc");
+
+/** Extract a description from frontmatter, if any. */
+export const extractDescription = (
+	frontmatter: Frontmatter,
+): string | undefined => {
+	const d = frontmatter.description;
+	return isString(d) && !isBlank(d) ? d : undefined;
+};
+
+/** Strip Markdown formatting from a body so we can index plain text. */
+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();
+
+/** Count words in a plain-text string. */
+export const countWords = (text: string): number => {
+	if (text.length === 0) return 0;
+	const t = text.trim();
+	if (t.length === 0) return 0;
+	return t.split(/\s+/).length;
+};
+
+/** Estimate reading time in minutes from a word count (default 220 wpm). */
+export const estimateReadingTime = (wordCount: number, wpm = 220): number =>
+	Math.max(1, Math.ceil(wordCount / wpm));
+
+/** Slugify a heading for an anchor id. Deduplicates across the document. */
+export const slugifyHeading = (raw: string): string => {
+	const base = raw
+		.toLowerCase()
+		.trim()
+		.replace(/[`*_~]+/g, "")
+		.replace(/[^\p{Letter}\p{Number}\s-]/gu, "")
+		.replace(/\s+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return base.length > 0 ? base : "section";
+};
+
+/** Extract a table of contents from markdown body (h1–h6). Dedupe anchor ids. */
+export const extractToc = (md: string): readonly TocItem[] => {
+	const lines = splitLines(md);
+	const seen = new Map<string, number>();
+	const items: TocItem[] = [];
+	for (const line of lines) {
+		const m = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+		if (!m) continue;
+		const depth = m[1]?.length as 1 | 2 | 3 | 4 | 5 | 6;
+		const text = m[2] ?? "";
+		if (text.length === 0) continue;
+		const base = slugifyHeading(text);
+		const count = seen.get(base) ?? 0;
+		seen.set(base, count + 1);
+		const id = count === 0 ? base : `${base}-${count}`;
+		items.push({ id, text, depth });
+	}
+	return items;
+};

package/src/modules/content/domain/validators/frontmatter.ts

@@ -0,0 +1,82 @@
+// Content Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { BADGE_VARIANTS } from "@create-docs/shared/constants";
+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 { BadgeVariant, Frontmatter } from "../../types";
+
+/**
+ * Badge Variant Schema
+ */
+export const badgeVariantSchema: Type = type(
+	"'default' | 'primary' | 'success' | 'warning' | 'danger'",
+);
+
+export type BadgeVariantSchema = typeof badgeVariantSchema.infer;
+
+/**
+ * Title Schema
+ */
+export const titleSchema: Type = type("string").narrow(
+	(title: string) => title.trim().length > 0,
+);
+
+/**
+ * Order Schema
+ */
+export const orderSchema: Type = type("number").narrow((order: number) =>
+	Number.isFinite(order),
+);
+
+export const validateBadgeVariant = (
+	v: unknown,
+): Result<BadgeVariant | undefined, ReturnType<typeof validationError>> => {
+	if (v === undefined) return ok(undefined);
+	const result = badgeVariantSchema(v);
+	if (result instanceof type.errors) {
+		return err(
+			validationError("Invalid badge variant", {
+				suggestions: [...BADGE_VARIANTS],
+			}),
+		);
+	}
+	return ok(v as BadgeVariant);
+};
+
+export const validateTitle = (
+	f: Frontmatter,
+): Result<string | undefined, ReturnType<typeof validationError>> => {
+	const t = f.title;
+	if (t === undefined) return ok(undefined);
+	const result = titleSchema(t);
+	if (result instanceof type.errors) {
+		return err(validationError("Title must be a non-empty string"));
+	}
+	return ok(t);
+};
+
+export const validateOrder = (
+	f: Frontmatter,
+): Result<number | undefined, ReturnType<typeof validationError>> => {
+	const o = f.order;
+	if (o === undefined) return ok(undefined);
+	const result = orderSchema(o);
+	if (result instanceof type.errors) {
+		return err(validationError("Order must be a finite number"));
+	}
+	return ok(o);
+};
+
+export const validateFrontmatter = (
+	f: Frontmatter,
+): Result<Frontmatter, ReturnType<typeof validationError>> => {
+	const titleResult = validateTitle(f);
+	if (!titleResult.ok) return titleResult;
+	const orderResult = validateOrder(f);
+	if (!orderResult.ok) return orderResult;
+	const badgeResult = validateBadgeVariant(f.badgeVariant);
+	if (!badgeResult.ok) return badgeResult;
+	return ok(f);
+};

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

@@ -0,0 +1,6 @@
+export {
+	validateBadgeVariant,
+	validateFrontmatter,
+	validateOrder,
+	validateTitle,
+} from "./frontmatter";

package/src/modules/content/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Public API for the content module.
+ *
+ * Re-exports types, pure operations, validators, use cases, and ports.
+ * Consumers (other modules, presentation) should import from here only.
+ */
+
+export * from "./application/cache";
+export * from "./application/usecases";
+export * from "./application/workflows";
+export {
+	contentChanged,
+	contentDiscovered,
+	contentParsed,
+	contentParseFailed,
+	contentRemoved,
+} from "./domain/events";
+export * from "./domain/operations";
+export * from "./domain/validators";
+export type {
+	ContentParser,
+	DirectoryEntry,
+	DirectoryScanner,
+	FileReader,
+	FileWatcher,
+} from "./ports";
+export * from "./types/public";

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

@@ -0,0 +1,45 @@
+/**
+ * Content module ports — interfaces that the application layer depends on
+ * to perform I/O. Adapters provide concrete implementations.
+ */
+
+import type { AppError } from "@create-docs/shared/errors";
+import type { Result } from "@create-docs/shared/types/result";
+import type { FilePath, ParsedContent } from "../types";
+
+/** Reads raw file contents from disk. */
+export interface FileReader {
+	read(filePath: FilePath): Promise<Result<string, AppError>>;
+	exists(filePath: FilePath): Promise<boolean>;
+	stat(
+		filePath: FilePath,
+	): Promise<Result<{ mtimeMs: number; size: number }, AppError>>;
+}
+
+/** Reads directory entries, recursively. */
+export interface DirectoryScanner {
+	list(dirPath: string): Promise<Result<readonly DirectoryEntry[], AppError>>;
+}
+
+/** A single entry returned by a directory scanner. */
+export interface DirectoryEntry {
+	readonly name: string;
+	readonly isDirectory: boolean;
+	readonly path: string;
+}
+
+/** Parses a raw file's content into structured data. */
+export interface ContentParser {
+	parse(raw: string): ParsedContent;
+}
+
+/** Watches a directory for file system changes. */
+export interface FileWatcher {
+	watch(
+		dir: string,
+		handlers: {
+			onChange: (filePath: string) => void;
+			onError: (err: unknown) => void;
+		},
+	): { close: () => void };
+}

package/src/modules/content/ports/velite.ts

@@ -0,0 +1,134 @@
+/**
+ * Velite-based port implementations
+ *
+ * Implements content module ports using Velite as the underlying engine.
+ * This replaces comark with Velite for framework-agnostic content processing.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { AppError } from "@create-docs/shared/errors";
+import { ioError } from "@create-docs/shared/errors";
+import type { Result } from "@create-docs/shared/types/result";
+import type { FilePath, Frontmatter, ParsedContent } from "../types";
+import type { DirectoryEntry } from "./index";
+
+const parseFrontmatter = (
+	raw: string,
+): { frontmatter: Frontmatter; content: string } => {
+	const match = raw.match(/^---\s*\n([\s\S]*?)\n---\s*\n?([\s\S]*)$/);
+	if (!match) {
+		return { frontmatter: {}, content: raw };
+	}
+
+	const lines = match[1].split("\n");
+	const frontmatter: Record<string, unknown> = {};
+
+	for (const line of lines) {
+		const [key, ...valueParts] = line.split(":");
+		if (key && valueParts.length > 0) {
+			const value = valueParts.join(":").trim();
+			frontmatter[key.trim()] = value;
+		}
+	}
+
+	return { frontmatter: frontmatter as Frontmatter, content: match[2] };
+};
+
+/**
+ * Velite-based content parser
+ * Parses markdown/MDX using YAML frontmatter and body split
+ */
+export const veliteParse = (raw: string): ParsedContent => {
+	const { frontmatter, content } = parseFrontmatter(raw);
+	return {
+		frontmatter,
+		content,
+		rawContent: raw,
+	};
+};
+
+/**
+ * Velite-based directory scanner
+ * Scans the directory for markdown/MDX content files
+ */
+export const veliteList = async (
+	dirPath: string,
+): Promise<Result<readonly DirectoryEntry[], AppError>> => {
+	try {
+		const entries = readdirSync(dirPath, { withFileTypes: true });
+		const value: DirectoryEntry[] = entries.map((entry) => ({
+			name: entry.name,
+			isDirectory: entry.isDirectory(),
+			path: join(dirPath, entry.name),
+		}));
+		return { ok: true, value };
+	} catch (error) {
+		return {
+			ok: false,
+			error: ioError(
+				dirPath,
+				error instanceof Error ? error.message : "Failed to scan directory",
+				error,
+			),
+		};
+	}
+};
+
+/**
+ * Velite-based file reader
+ * Reads raw file contents from disk
+ */
+export const veliteRead = async (
+	filePath: FilePath,
+): Promise<Result<string, AppError>> => {
+	try {
+		const value = readFileSync(filePath, "utf-8");
+		return { ok: true, value };
+	} catch (error) {
+		return {
+			ok: false,
+			error: ioError(
+				filePath,
+				error instanceof Error ? error.message : "Failed to read file",
+				error,
+			),
+		};
+	}
+};
+
+export const veliteExists = async (filePath: FilePath): Promise<boolean> => {
+	return existsSync(filePath);
+};
+
+export const veliteStat = async (
+	filePath: FilePath,
+): Promise<Result<{ mtimeMs: number; size: number }, AppError>> => {
+	try {
+		const stats = statSync(filePath);
+		return {
+			ok: true,
+			value: { mtimeMs: stats.mtimeMs, size: stats.size },
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: ioError(
+				filePath,
+				error instanceof Error ? error.message : "Failed to stat file",
+				error,
+			),
+		};
+	}
+};
+
+/**
+ * Default Velite port implementations
+ */
+export const veliteContentParser = { parse: veliteParse };
+export const veliteDirectoryScanner = { list: veliteList };
+export const veliteFileReader = {
+	read: veliteRead,
+	exists: veliteExists,
+	stat: veliteStat,
+};

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

@@ -0,0 +1,76 @@
+import type { Brand } from "@create-docs/shared/types";
+
+export type DocSlug = Brand<string, "DocSlug">;
+export type DocId = Brand<string, "DocId">;
+export type FilePath = Brand<string, "FilePath">;
+
+export const DocSlug = (s: string): DocSlug => s as DocSlug;
+export const DocId = (s: string): DocId => s as DocId;
+export const FilePath = (s: string): FilePath => s as FilePath;
+
+export type BadgeVariant = "default" | "success" | "warning" | "danger";
+
+/** A single heading extracted from page body. */
+export interface TocItem {
+	readonly id: string;
+	readonly text: string;
+	readonly depth: 1 | 2 | 3 | 4 | 5 | 6;
+}
+
+/** Per-page metadata derived from the body (not user-authored). */
+export interface PageMetadata {
+	readonly readingTime: number;
+	readonly wordCount: number;
+	readonly lastModified?: string;
+	readonly editUrl?: string;
+}
+
+/** Readonly data model for a doc page's frontmatter. */
+export interface Frontmatter {
+	readonly title?: string;
+	readonly description?: string;
+	readonly order?: number;
+	readonly badge?: string;
+	readonly badgeVariant?: BadgeVariant;
+	readonly collapsible?: boolean;
+	readonly category?: string;
+	readonly author?: string;
+	readonly lastUpdated?: string;
+	readonly tags?: readonly string[];
+	readonly draft?: boolean;
+	readonly [key: string]: unknown;
+}
+
+/** Parsed, normalized body of a markdown file (frontmatter stripped). */
+export interface ParsedContent {
+	readonly frontmatter: Frontmatter;
+	readonly content: string;
+	readonly rawContent: string;
+}
+
+/** A single doc page, ready for downstream consumption. */
+export interface DocPage {
+	readonly id: DocId;
+	readonly slug: DocSlug;
+	readonly title: string;
+	readonly description?: string;
+	readonly frontmatter: Frontmatter;
+	readonly content: string;
+	readonly rawContent: string;
+	readonly filePath: FilePath;
+	readonly group?: string;
+	readonly order: number;
+	readonly toc: readonly TocItem[];
+	readonly metadata: PageMetadata;
+}
+
+/** Lightweight descriptor for a file discovered during scanning. */
+export interface DocFile {
+	readonly id: DocId;
+	readonly slug: DocSlug;
+	readonly frontmatter: Frontmatter;
+	readonly rawContent: string;
+	readonly filePath: FilePath;
+	readonly group?: string;
+	readonly order: number;
+}

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

@@ -0,0 +1 @@
+export * from "./index";

package/src/modules/content-linting/application/builtin-linting-adapter.ts

@@ -0,0 +1,82 @@
+/**
+ * Built-in linting adapter implementation.
+ * Provides basic content linting rules.
+ */
+
+import { runLintRules } from "../domain/operations/linting-operations";
+import type { LintingPort } from "../ports/linting-port";
+import type { LintResult, LintRule } from "../types/linting";
+
+const DEFAULT_RULES: LintRule[] = [
+	{
+		id: "missing-title",
+		name: "Missing Title",
+		description: "Document must have a title in frontmatter",
+		severity: "error",
+	},
+	{
+		id: "missing-description",
+		name: "Missing Description",
+		description: "Document should have a description in frontmatter",
+		severity: "warning",
+	},
+];
+
+export const createBuiltinLintingAdapter = (): LintingPort => ({
+	lint: async (filePath: string, rules?: readonly unknown[]) => {
+		try {
+			const response = await fetch(filePath);
+			if (!response.ok) {
+				throw new Error(`Failed to load file: ${response.statusText}`);
+			}
+			const content = await response.text();
+
+			const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+			const frontmatter = frontmatterMatch?.[1]
+				? (JSON.parse(
+						frontmatterMatch[1].replace(/:/g, ":").replace(/'/g, '"'),
+					) as Record<string, unknown>)
+				: {};
+
+			const lintRules = (rules as LintRule[]) || DEFAULT_RULES;
+			const results = runLintRules(content, frontmatter, lintRules);
+
+			if (!results.ok) {
+				console.error("Linting error:", results.error);
+				return [];
+			}
+
+			return results.value;
+		} catch (error) {
+			console.error("Lint error:", error);
+			return [];
+		}
+	},
+
+	fix: async (filePath: string, results?: readonly unknown[]) => {
+		try {
+			const response = await fetch(filePath);
+			if (!response.ok) {
+				throw new Error(`Failed to load file: ${response.statusText}`);
+			}
+			const content = await response.text();
+
+			const lintResults = results as LintResult[];
+			let fixedContent = content;
+
+			for (const result of lintResults) {
+				if (result.ruleId === "missing-title" && result.severity === "error") {
+					if (!fixedContent.match(/^---\n[\s\S]*?\n---/)) {
+						fixedContent = `---\ntitle: "Untitled"\n---\n\n${fixedContent}`;
+					}
+				}
+			}
+
+			if (fixedContent !== content) {
+				console.log(`Fixed ${lintResults.length} issues in ${filePath}`);
+			}
+		} catch (error) {
+			console.error("Fix error:", error);
+		}
+	},
+});