@wrikka/create-docs 0.1.0

package/src/modules/toc/index.ts

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

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

@@ -0,0 +1,21 @@
+/**
+ * Port for TOC operations.
+ */
+
+export type TocPort = {
+	/**
+	 * Extract headings from markdown content.
+	 */
+	readonly extractHeadings: (
+		content: string,
+		config: unknown,
+	) => Promise<readonly unknown[]>;
+
+	/**
+	 * Generate TOC from headings.
+	 */
+	readonly generateToc: (
+		headings: readonly unknown[],
+		config: unknown,
+	) => Promise<unknown>;
+};

package/src/modules/toc/types/toc.ts

@@ -0,0 +1,17 @@
+/**
+ * Table of Contents types for enhanced TOC features.
+ */
+
+export type TocConfig = {
+	readonly enabled: boolean;
+	readonly maxDepth: number;
+	readonly minHeadingLevel: number;
+	readonly includeSubheadings: boolean;
+};
+
+export type TocItemEnhanced = {
+	readonly id: string;
+	readonly text: string;
+	readonly level: number;
+	children?: TocItemEnhanced[];
+};

package/src/modules/toc-generator/application/usecases/index.ts

@@ -0,0 +1,30 @@
+/**
+ * TOC Generator Use Cases
+ *
+ * Orchestration layer for TOC generation
+ */
+
+import { buildTocTree, flattenToc, parseHeadings } from "../../domain";
+import type { TocItem, TocOptions } from "../../types";
+
+/**
+ * Generate TOC from markdown content
+ */
+export const generateToc = (
+	content: string,
+	options: TocOptions = {},
+): TocItem[] => {
+	const headings = parseHeadings(content);
+	return buildTocTree(headings, options);
+};
+
+/**
+ * Generate flat TOC from markdown content
+ */
+export const generateFlatToc = (
+	content: string,
+	options: TocOptions = {},
+): TocItem[] => {
+	const toc = generateToc(content, options);
+	return flattenToc(toc);
+};

package/src/modules/toc-generator/domain/index.ts

@@ -0,0 +1,12 @@
+/**
+ * TOC Generator Domain
+ *
+ * Pure business logic for TOC generation
+ */
+
+export {
+	buildTocTree,
+	flattenToc,
+	generateSlug,
+	parseHeadings,
+} from "./tocOperations";

package/src/modules/toc-generator/domain/tocOperations.ts

@@ -0,0 +1,104 @@
+/**
+ * TOC Operations
+ *
+ * Pure functions for table of contents generation
+ */
+
+import type { Heading, TocItem, TocOptions } from "../types";
+
+/**
+ * Parse headings from markdown content
+ */
+export const parseHeadings = (content: string): Heading[] => {
+	const headings: Heading[] = [];
+	const lines = content.split("\n");
+
+	for (const line of lines) {
+		const match = line.match(/^(#{1,6})\s+(.+)$/);
+		if (match) {
+			headings.push({
+				text: match[2].trim(),
+				level: match[1].length,
+				line: lines.indexOf(line) + 1,
+			});
+		}
+	}
+
+	return headings;
+};
+
+/**
+ * Generate slug from text
+ */
+export const generateSlug = (text: string): string => {
+	return text
+		.toLowerCase()
+		.replace(/[^\w\s-]/g, "")
+		.replace(/\s+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-|-$/g, "");
+};
+
+/**
+ * Build TOC tree from headings
+ */
+export const buildTocTree = (
+	headings: Heading[],
+	options: TocOptions = {},
+): TocItem[] => {
+	const { maxDepth = 6, minDepth = 1, include = [], exclude = [] } = options;
+
+	const filteredHeadings = headings.filter((heading) => {
+		if (heading.level < minDepth || heading.level > maxDepth) return false;
+		if (include.length > 0 && !include.includes(heading.text)) return false;
+		if (exclude.length > 0 && exclude.includes(heading.text)) return false;
+		return true;
+	});
+
+	const root: TocItem[] = [];
+	const stack: { item: TocItem; level: number }[] = [];
+
+	for (const heading of filteredHeadings) {
+		const item: TocItem = {
+			text: heading.text,
+			level: heading.level,
+			id: generateSlug(heading.text),
+		};
+
+		// Pop stack until we find the parent
+		while (stack.length > 0 && stack[stack.length - 1].level >= heading.level) {
+			stack.pop();
+		}
+
+		if (stack.length === 0) {
+			root.push(item);
+		} else {
+			const parent = stack[stack.length - 1].item;
+			if (!parent.children) parent.children = [];
+			parent.children.push(item);
+		}
+
+		stack.push({ item, level: heading.level });
+	}
+
+	return root;
+};
+
+/**
+ * Flatten TOC tree to list
+ */
+export const flattenToc = (toc: TocItem[]): TocItem[] => {
+	const result: TocItem[] = [];
+
+	const traverse = (items: TocItem[]) => {
+		for (const item of items) {
+			result.push(item);
+			if (item.children) {
+				traverse(item.children);
+			}
+		}
+	};
+
+	traverse(toc);
+	return result;
+};

package/src/modules/toc-generator/index.ts

@@ -0,0 +1,9 @@
+/**
+ * TOC Generator Module
+ *
+ * Table of contents generation for documentation
+ */
+
+export { generateFlatToc, generateToc } from "./application/usecases";
+export * from "./domain";
+export * from "./types";

package/src/modules/toc-generator/ports/index.ts

@@ -0,0 +1,20 @@
+/**
+ * TOC Generator Ports
+ *
+ * Module-specific interfaces for TOC generation
+ */
+
+import type { TocItem, TocOptions } from "../types";
+
+/**
+ * Content parser interface
+ */
+export interface ContentParser {
+	/** Parse content and return headings */
+	parseHeadings(
+		content: string,
+	): Promise<{ text: string; level: number; line: number }[]>;
+}
+
+// Re-export types for convenience
+export type { TocItem, TocOptions };

package/src/modules/toc-generator/types/index.ts

@@ -0,0 +1,50 @@
+/**
+ * TOC Generator Types
+ *
+ * Domain types for table of contents generation
+ */
+
+/**
+ * TOC item
+ */
+export interface TocItem {
+	/** Heading text */
+	text: string;
+	/** Heading level (1-6) */
+	level: number;
+	/** Anchor ID */
+	id: string;
+	/** Child items */
+	children?: TocItem[];
+}
+
+/**
+ * TOC options
+ */
+export interface TocOptions {
+	/** Max depth */
+	maxDepth?: number;
+	/** Min depth */
+	minDepth?: number;
+	/** Include headings */
+	include?: string[];
+	/** Exclude headings */
+	exclude?: string[];
+}
+
+/**
+ * Heading
+ */
+export interface Heading {
+	/** Heading text */
+	text: string;
+	/** Heading level */
+	level: number;
+	/** Line number */
+	line: number;
+}
+
+/** Content parser port */
+export interface ContentParser {
+	parse: (raw: string) => unknown;
+}

package/src/modules/version-control/domain/events/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Domain events for version control
+ */
+export interface VersionCreatedEvent {
+	readonly type: "VERSION_CREATED";
+	readonly timestamp: number;
+	readonly versionNumber: string;
+	readonly author: string;
+}
+
+export interface VersionRestoredEvent {
+	readonly type: "VERSION_RESTORED";
+	readonly timestamp: number;
+	readonly versionNumber: string;
+}
+
+export type VersionControlDomainEvent =
+	| VersionCreatedEvent
+	| VersionRestoredEvent;
+
+export const createVersionCreatedEvent = (
+	versionNumber: string,
+	author: string,
+	now: number = Date.now(),
+): VersionCreatedEvent => ({
+	type: "VERSION_CREATED",
+	timestamp: now,
+	versionNumber,
+	author,
+});
+
+export const createVersionRestoredEvent = (
+	versionNumber: string,
+	now: number = Date.now(),
+): VersionRestoredEvent => ({
+	type: "VERSION_RESTORED",
+	timestamp: now,
+	versionNumber,
+});

package/src/modules/version-control/domain/models/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Domain models for version control
+ */
+export interface Version {
+	readonly id: string;
+	readonly number: string;
+	readonly timestamp: number;
+	readonly author: string;
+	readonly message: string;
+}
+
+export const createVersion = (
+	id: string,
+	number: string,
+	author: string,
+	message: string,
+	options?: { timestamp?: number },
+	now: number = Date.now(),
+): Version => ({
+	id,
+	number,
+	author,
+	message,
+	timestamp: options?.timestamp ?? now,
+});

package/src/modules/version-control/domain/validators/index.ts

@@ -0,0 +1,50 @@
+// Version Control Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Version Number Schema
+ */
+export const versionNumberSchema: Type = type(/^\d+\.\d+\.\d+$/);
+
+export type VersionNumber = typeof versionNumberSchema.infer;
+
+/**
+ * Author Schema
+ */
+export const authorSchema: Type = type("string >= 1");
+
+export type Author = typeof authorSchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate version number using Arktype
+ */
+export const validateVersionNumber = (number: unknown): VersionNumber => {
+	const result = versionNumberSchema(number);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Version number must be in format x.y.z");
+	}
+	return result as VersionNumber;
+};
+
+/**
+ * Validate author using Arktype
+ */
+export const validateAuthor = (author: unknown): Author => {
+	const result = authorSchema(author);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Author must be a non-empty string");
+	}
+	return result as Author;
+};

package/src/modules/versioning/application/fs-version-loader.ts

@@ -0,0 +1,44 @@
+/**
+ * File system adapter for version loading.
+ */
+
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { ioError } from "@create-docs/shared/errors";
+import type { VersionLoaderPort } from "../ports/version-loader-port";
+
+export const createFsVersionLoader = (): VersionLoaderPort => ({
+	scanVersions: async (docsDir: string) => {
+		try {
+			const entries = await readdir(docsDir, { withFileTypes: true });
+			return entries
+				.filter((entry) => entry.isDirectory())
+				.map((entry) => entry.name);
+		} catch (error) {
+			throw ioError(docsDir, "Failed to scan versions", error);
+		}
+	},
+
+	loadVersionDocs: async (version: string, docsDir: string) => {
+		const versionDir = join(docsDir, version);
+		try {
+			const entries = await readdir(versionDir, {
+				withFileTypes: true,
+				recursive: true,
+			});
+			const results: string[] = [];
+			for (const entry of entries) {
+				if (
+					entry.isFile() &&
+					(entry.name.endsWith(".md") || entry.name.endsWith(".mdoc"))
+				) {
+					const parentPath = entry.parentPath || versionDir;
+					results.push(join(parentPath, entry.name));
+				}
+			}
+			return results;
+		} catch (error) {
+			throw ioError(versionDir, "Failed to load version docs", error);
+		}
+	},
+});

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

@@ -0,0 +1,80 @@
+/**
+ * Pure versioning operations.
+ * No I/O. No exceptions thrown.
+ */
+
+import type {
+	Version,
+	VersionConfig,
+	VersionedDocPage,
+} from "../../types/versioning";
+
+/**
+ * Extract version from a slug path.
+ * Example: "v1/getting-started/introduction" -> "v1"
+ */
+export const extractVersionFromSlug = (
+	slug: string,
+	versions: readonly Version[],
+): Version | null => {
+	const parts = slug.split("/");
+	const firstPart = parts[0];
+	if (firstPart && versions.includes(firstPart)) {
+		return firstPart;
+	}
+	return null;
+};
+
+/**
+ * Remove version prefix from a slug.
+ * Example: "v1/getting-started/introduction" -> "getting-started/introduction"
+ */
+export const removeVersionFromSlug = (
+	slug: string,
+	version: Version,
+): string => {
+	return slug.startsWith(`${version}/`) ? slug.slice(version.length + 1) : slug;
+};
+
+/**
+ * Add version prefix to a slug.
+ * Example: "getting-started/introduction" + "v1" -> "v1/getting-started/introduction"
+ */
+export const addVersionToSlug = (slug: string, version: Version): string => {
+	return `${version}/${slug}`;
+};
+
+/**
+ * Group doc pages by version.
+ */
+export const groupDocsByVersion = (
+	pages: readonly VersionedDocPage[],
+): Readonly<Record<Version, readonly VersionedDocPage[]>> => {
+	const groups: Record<string, VersionedDocPage[]> = {};
+	for (const page of pages) {
+		const { version } = page;
+		if (!groups[version]) {
+			groups[version] = [];
+		}
+		groups[version].push(page);
+	}
+	return groups;
+};
+
+/**
+ * Validate version config.
+ */
+export const validateVersionConfig = (config: VersionConfig): boolean => {
+	if (
+		!config.defaultVersion ||
+		!config.versions.includes(config.defaultVersion)
+	) {
+		return false;
+	}
+	for (const version of config.versions) {
+		if (!config.versionPaths[version]) {
+			return false;
+		}
+	}
+	return true;
+};

package/src/modules/versioning/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public API for the versioning module.
+ */
+
+export { createFsVersionLoader } from "./application/fs-version-loader";
+export * from "./domain/operations/versioning-operations";
+export * from "./ports/version-loader-port";
+export * from "./types/versioning";

package/src/modules/versioning/ports/version-loader-port.ts

@@ -0,0 +1,18 @@
+/**
+ * Port for version loading operations.
+ */
+
+export type VersionLoaderPort = {
+	/**
+	 * Scan docs directory for version-specific folders.
+	 */
+	readonly scanVersions: (docsDir: string) => Promise<readonly string[]>;
+
+	/**
+	 * Load docs for a specific version.
+	 */
+	readonly loadVersionDocs: (
+		version: string,
+		docsDir: string,
+	) => Promise<readonly string[]>;
+};

package/src/modules/versioning/types/versioning.ts

@@ -0,0 +1,17 @@
+/**
+ * Versioning types for multi-version documentation support.
+ */
+
+export type Version = string;
+
+export type VersionConfig = {
+	readonly defaultVersion: Version;
+	readonly versions: readonly Version[];
+	readonly versionPaths: Readonly<Record<Version, string>>;
+};
+
+export type VersionedDocPage = {
+	readonly version: Version;
+	readonly slug: string;
+	readonly originalSlug: string;
+};

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

@@ -0,0 +1,55 @@
+/**
+ * Domain events for workflow
+ */
+export interface WorkflowStartedEvent {
+	readonly type: "WORKFLOW_STARTED";
+	readonly timestamp: number;
+	readonly workflowId: string;
+}
+
+export interface WorkflowCompletedEvent {
+	readonly type: "WORKFLOW_COMPLETED";
+	readonly timestamp: number;
+	readonly workflowId: string;
+}
+
+export interface StepCompletedEvent {
+	readonly type: "STEP_COMPLETED";
+	readonly timestamp: number;
+	readonly workflowId: string;
+	readonly stepId: string;
+}
+
+export type WorkflowDomainEvent =
+	| WorkflowStartedEvent
+	| WorkflowCompletedEvent
+	| StepCompletedEvent;
+
+export const createWorkflowStartedEvent = (
+	workflowId: string,
+	now: number = Date.now(),
+): WorkflowStartedEvent => ({
+	type: "WORKFLOW_STARTED",
+	timestamp: now,
+	workflowId,
+});
+
+export const createWorkflowCompletedEvent = (
+	workflowId: string,
+	now: number = Date.now(),
+): WorkflowCompletedEvent => ({
+	type: "WORKFLOW_COMPLETED",
+	timestamp: now,
+	workflowId,
+});
+
+export const createStepCompletedEvent = (
+	workflowId: string,
+	stepId: string,
+	now: number = Date.now(),
+): StepCompletedEvent => ({
+	type: "STEP_COMPLETED",
+	timestamp: now,
+	workflowId,
+	stepId,
+});

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

@@ -0,0 +1,40 @@
+/**
+ * Domain models for workflow
+ */
+export interface WorkflowStep {
+	readonly id: string;
+	readonly name: string;
+	readonly description: string;
+	readonly status: "pending" | "in-progress" | "completed" | "failed";
+}
+
+export interface Workflow {
+	readonly id: string;
+	readonly name: string;
+	readonly steps: readonly WorkflowStep[];
+	readonly currentStepIndex: number;
+}
+
+export const createWorkflowStep = (
+	id: string,
+	name: string,
+	description: string,
+	status: WorkflowStep["status"] = "pending",
+): WorkflowStep => ({
+	id,
+	name,
+	description,
+	status,
+});
+
+export const createWorkflow = (
+	id: string,
+	name: string,
+	steps: readonly WorkflowStep[],
+	currentStepIndex: number = 0,
+): Workflow => ({
+	id,
+	name,
+	steps,
+	currentStepIndex,
+});