@wrikka/create-docs 0.1.0

package/src/modules/api-docs/domain/events/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Domain events for API docs
+ */
+export interface ApiEndpointAddedEvent {
+	readonly type: "API_ENDPOINT_ADDED";
+	readonly timestamp: number;
+	readonly path: string;
+	readonly method: string;
+}
+
+export interface ApiEndpointUpdatedEvent {
+	readonly type: "API_ENDPOINT_UPDATED";
+	readonly timestamp: number;
+	readonly path: string;
+	readonly method: string;
+}
+
+export type ApiDocsDomainEvent =
+	| ApiEndpointAddedEvent
+	| ApiEndpointUpdatedEvent;
+
+export const createApiEndpointAddedEvent = (
+	path: string,
+	method: string,
+	now: number = Date.now(),
+): ApiEndpointAddedEvent => ({
+	type: "API_ENDPOINT_ADDED",
+	timestamp: now,
+	path,
+	method,
+});
+
+export const createApiEndpointUpdatedEvent = (
+	path: string,
+	method: string,
+	now: number = Date.now(),
+): ApiEndpointUpdatedEvent => ({
+	type: "API_ENDPOINT_UPDATED",
+	timestamp: now,
+	path,
+	method,
+});

package/src/modules/api-docs/domain/models/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Domain models for API docs
+ */
+export interface ApiEndpoint {
+	readonly path: string;
+	readonly method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+	readonly description: string;
+	readonly parameters?: ReadonlyArray<ApiParameter>;
+}
+
+export interface ApiParameter {
+	readonly name: string;
+	readonly type: string;
+	readonly required: boolean;
+	readonly description: string;
+}
+
+export const createApiEndpoint = (
+	path: string,
+	method: ApiEndpoint["method"],
+	description: string,
+	parameters?: ReadonlyArray<ApiParameter>,
+): ApiEndpoint => ({
+	path,
+	method,
+	description,
+	parameters,
+});
+
+export const createApiParameter = (
+	name: string,
+	type: string,
+	required: boolean,
+	description: string,
+): ApiParameter => ({
+	name,
+	type,
+	required,
+	description,
+});

package/src/modules/api-docs/domain/operations/api-docs-operations.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure API docs 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 { ApiDocsConfig, ApiEndpoint } from "../../types/api-docs";
+
+export type ApiDocsError = {
+	readonly kind: "api-docs-error";
+	readonly message: string;
+};
+
+/**
+ * Group endpoints by path prefix.
+ */
+export const groupEndpointsByPath = (
+	endpoints: readonly ApiEndpoint[],
+): Result<Record<string, readonly ApiEndpoint[]>, ApiDocsError> => {
+	try {
+		const groups: Record<string, ApiEndpoint[]> = {};
+
+		for (const endpoint of endpoints) {
+			const prefix = endpoint.path.split("/")[1] || "root";
+			if (!groups[prefix]) {
+				groups[prefix] = [];
+			}
+			groups[prefix].push(endpoint);
+		}
+
+		return ok(groups);
+	} catch (error) {
+		return err({
+			kind: "api-docs-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};
+
+/**
+ * Generate markdown from endpoint.
+ */
+export const generateEndpointMarkdown = (endpoint: ApiEndpoint): string => {
+	return `## ${endpoint.method.toUpperCase()} ${endpoint.path}
+
+${endpoint.description}
+`;
+};
+
+/**
+ * Validate API docs config.
+ */
+export const validateApiDocsConfig = (config: ApiDocsConfig): boolean => {
+	if (!config.source) return false;
+	if (!config.sourcePath) return false;
+	if (!config.outputPath) return false;
+	return true;
+};

package/src/modules/api-docs/domain/validators/index.ts

@@ -0,0 +1,56 @@
+// API Docs Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * API Path Schema
+ */
+export const apiPathSchema: Type = type("string >= 1").narrow((path: string) =>
+	path.startsWith("/"),
+);
+
+export type ApiPath = typeof apiPathSchema.infer;
+
+/**
+ * HTTP Method Schema
+ */
+export const httpMethodSchema: Type = type(
+	"'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'",
+);
+
+export type HttpMethod = typeof httpMethodSchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate API path using Arktype
+ */
+export const validateApiPath = (path: unknown): ApiPath => {
+	const result = apiPathSchema(path);
+	if (result instanceof type.errors) {
+		throw new ValidationError(
+			"API path must be a non-empty string starting with /",
+		);
+	}
+	return result as ApiPath;
+};
+
+/**
+ * Validate HTTP method using Arktype
+ */
+export const validateHttpMethod = (method: unknown): HttpMethod => {
+	const result = httpMethodSchema(method);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Invalid HTTP method");
+	}
+	return result as HttpMethod;
+};

package/src/modules/api-docs/index.ts

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

package/src/modules/api-docs/ports/api-docs-port.ts

@@ -0,0 +1,21 @@
+/**
+ * Port for API docs operations.
+ */
+
+export type ApiDocsPort = {
+	/**
+	 * Extract API endpoints from source.
+	 */
+	readonly extractEndpoints: (
+		sourcePath: string,
+		config: unknown,
+	) => Promise<readonly unknown[]>;
+
+	/**
+	 * Generate documentation from endpoints.
+	 */
+	readonly generateDocs: (
+		endpoints: readonly unknown[],
+		outputPath: string,
+	) => Promise<void>;
+};

package/src/modules/api-docs/types/api-docs.ts

@@ -0,0 +1,15 @@
+/**
+ * API docs types for auto-generating API documentation.
+ */
+
+export type ApiDocsConfig = {
+	readonly source: "openapi" | "typescript" | "graphql";
+	readonly sourcePath: string;
+	readonly outputPath: string;
+};
+
+export type ApiEndpoint = {
+	readonly path: string;
+	readonly method: string;
+	readonly description: string;
+};

package/src/modules/api-reference/openapi.ts

@@ -0,0 +1,166 @@
+/**
+ * Browser-safe OpenAPI → ApiEndpoint adapter.
+ * Accepts a spec object, JSON/YAML string, or URL.
+ */
+
+import { JSON_SCHEMA, load } from "js-yaml";
+import type {
+	ApiEndpoint,
+	ApiParameter,
+	HttpMethod,
+} from "../../runtime/types";
+
+const METHODS = new Set(["get", "post", "put", "delete", "patch"]);
+
+const slug = (method: string, path: string, opId?: string): string =>
+	opId ??
+	`${method}-${path}`
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "");
+
+const exampleFromSchema = (schema: unknown): unknown => {
+	if (!schema || typeof schema !== "object") return undefined;
+	const s = schema as Record<string, unknown>;
+	if (s.example !== undefined) return s.example;
+	if (s.default !== undefined) return s.default;
+	if (Array.isArray(s.enum)) return s.enum[0];
+	if (s.type === "object" && s.properties) {
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(
+			s.properties as Record<string, unknown>,
+		)) {
+			const ex = exampleFromSchema(v);
+			if (ex !== undefined) out[k] = ex;
+		}
+		return Object.keys(out).length > 0 ? out : undefined;
+	}
+	if (s.type === "array" && s.items) {
+		const ex = exampleFromSchema(s.items);
+		return ex !== undefined ? [ex] : [];
+	}
+	if (s.type === "string") return "string";
+	if (s.type === "number" || s.type === "integer") return 0;
+	if (s.type === "boolean") return true;
+	return undefined;
+};
+
+const jsonContent = (
+	content: unknown,
+): { example?: unknown; contentType?: string } => {
+	if (!content || typeof content !== "object") return {};
+	const record = content as Record<string, Record<string, unknown>>;
+	const ct =
+		Object.keys(record).find((k) => k.includes("json")) ??
+		Object.keys(record)[0];
+	if (!ct) return {};
+	const media = record[ct];
+	return {
+		contentType: ct,
+		example: media?.example ?? exampleFromSchema(media?.schema),
+	};
+};
+
+/** Parse a spec object into endpoints grouped-ready ApiEndpoint[]. */
+export function endpointsFromOpenApiSpec(
+	spec: Record<string, unknown>,
+	options?: { server?: string },
+): ApiEndpoint[] {
+	const paths = spec.paths as Record<string, unknown> | undefined;
+	if (!paths || typeof paths !== "object") return [];
+
+	const servers = spec.servers as { url?: string }[] | undefined;
+	const defaultServer = options?.server ?? servers?.[0]?.url;
+
+	const endpoints: ApiEndpoint[] = [];
+	for (const [path, item] of Object.entries(paths)) {
+		if (!item || typeof item !== "object") continue;
+		for (const [method, operation] of Object.entries(
+			item as Record<string, unknown>,
+		)) {
+			if (!METHODS.has(method) || !operation || typeof operation !== "object")
+				continue;
+			const op = operation as Record<string, unknown>;
+			const tags = Array.isArray(op.tags) ? (op.tags as string[]) : [];
+			const parameters: ApiParameter[] = Array.isArray(op.parameters)
+				? op.parameters.map((p: Record<string, unknown>) => ({
+						name: String(p.name ?? ""),
+						in: (p.in as ApiParameter["in"]) ?? "query",
+						required: Boolean(p.required),
+						description:
+							typeof p.description === "string" ? p.description : undefined,
+						schema: p.schema,
+						example: p.example ?? exampleFromSchema(p.schema),
+					}))
+				: [];
+
+			const body = op.requestBody as Record<string, unknown> | undefined;
+			const bodyContent = body ? jsonContent(body.content) : {};
+
+			const responses: ApiEndpoint["responses"] = {};
+			const resps = op.responses as Record<string, unknown> | undefined;
+			if (resps) {
+				for (const [code, r] of Object.entries(resps)) {
+					const rec = r as Record<string, unknown>;
+					responses[code] = {
+						description:
+							typeof rec.description === "string" ? rec.description : "",
+						example: jsonContent(rec.content).example,
+					};
+				}
+			}
+
+			endpoints.push({
+				id: slug(
+					method,
+					path,
+					typeof op.operationId === "string" ? op.operationId : undefined,
+				),
+				method: method.toUpperCase() as HttpMethod,
+				path,
+				summary: typeof op.summary === "string" ? op.summary : undefined,
+				description:
+					typeof op.description === "string" ? op.description : undefined,
+				tag: tags[0],
+				parameters,
+				requestBody: body
+					? {
+							description:
+								typeof body.description === "string"
+									? body.description
+									: undefined,
+							required: Boolean(body.required),
+							example: bodyContent.example,
+							contentType: bodyContent.contentType,
+						}
+					: undefined,
+				responses,
+				server: defaultServer,
+			});
+		}
+	}
+	return endpoints;
+}
+
+/** Load endpoints from a spec object, raw JSON/YAML text, or URL. */
+export async function endpointsFromOpenApi(
+	source: Record<string, unknown> | string,
+	options?: { server?: string },
+): Promise<ApiEndpoint[]> {
+	let spec: Record<string, unknown>;
+	if (typeof source === "object" && source !== null) {
+		spec = source;
+	} else {
+		let text = source;
+		if (/^https?:\/\//i.test(text) || /^\.?\//.test(text)) {
+			const res = await fetch(text);
+			if (!res.ok) throw new Error(`Failed to fetch spec: ${res.status}`);
+			text = await res.text();
+		}
+		const trimmed = text.trim();
+		spec = trimmed.startsWith("{")
+			? JSON.parse(trimmed)
+			: (load(trimmed, { schema: JSON_SCHEMA }) as Record<string, unknown>);
+	}
+	return endpointsFromOpenApiSpec(spec, options);
+}

package/src/modules/api-reference/orpc.ts

@@ -0,0 +1,94 @@
+/**
+ * oRPC-native adapter: walk a router object and turn each procedure
+ * into an ApiEndpoint for the reference + playground.
+ *
+ * oRPC HTTP default: POST /<basePath>/<dot.separated.path> with
+ * `{ "json": <input> }` bodies (RPCHandler). Route metadata is read
+ * defensively from `~orpc` so custom OpenAPIHandler routes work too.
+ */
+
+import type { ApiEndpoint, HttpMethod } from "../../runtime/types";
+
+type UnknownRecord = Record<string, unknown>;
+
+const asRecord = (v: unknown): UnknownRecord | undefined =>
+	v && typeof v === "object" ? (v as UnknownRecord) : undefined;
+
+const readRoute = (proc: unknown): UnknownRecord | undefined => {
+	const meta = asRecord(asRecord(proc)?.["~orpc"]);
+	if (!meta) return undefined;
+	const direct = asRecord(meta.route);
+	if (direct) return direct;
+	const contract = asRecord(meta.procedureContract);
+	return asRecord(asRecord(contract?.["~orpc"])?.route);
+};
+
+export interface OrpcAdapterOptions {
+	/** e.g. "/rpc" — used when a procedure has no explicit route.path. */
+	basePath?: string;
+	/** Absolute server URL for the playground. Defaults to same-origin. */
+	server?: string;
+	/** Group all endpoints under this tag when no meta tags exist. */
+	tag?: string;
+}
+
+export function endpointsFromOrpcRouter(
+	router: unknown,
+	options: OrpcAdapterOptions = {},
+): ApiEndpoint[] {
+	const basePath = options.basePath ?? "/rpc";
+	const endpoints: ApiEndpoint[] = [];
+
+	const walk = (node: unknown, keyPath: string[]) => {
+		const rec = asRecord(node);
+		if (!rec) return;
+
+		const route = readRoute(node);
+		if (route) {
+			const method = (
+				typeof route.method === "string" ? route.method : "POST"
+			).toUpperCase() as HttpMethod;
+			const dotPath = keyPath.join(".");
+			const path =
+				typeof route.path === "string" ? route.path : `${basePath}/${dotPath}`;
+			const summary =
+				(typeof route.summary === "string" && route.summary) || dotPath;
+			endpoints.push({
+				id: dotPath.replace(/[^a-zA-Z0-9]+/g, "-"),
+				method,
+				path,
+				summary,
+				description:
+					typeof route.description === "string"
+						? route.description
+						: `oRPC procedure \`${dotPath}\`. Send input as \`{ "json": <input> }\`.`,
+				tag: options.tag ?? keyPath[0],
+				parameters: [],
+				requestBody:
+					method === "GET"
+						? undefined
+						: {
+								required: false,
+								contentType: "application/json",
+								example: { json: {} },
+							},
+				responses: {
+					"200": {
+						description: "oRPC JSON response",
+						example: { json: {} },
+					},
+				},
+				server: options.server,
+			});
+			return;
+		}
+
+		for (const [key, value] of Object.entries(rec)) {
+			if (key.startsWith("~") || key.startsWith("_")) continue;
+			walk(value, [...keyPath, key]);
+		}
+	};
+
+	walk(router, []);
+	return endpoints;
+}

package/src/modules/code-block-enhancements/application/usecases/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Code Block Enhancements Use Cases
+ *
+ * Orchestration layer for code block enhancements
+ */
+
+import {
+	addLineNumbers,
+	enhanceCodeBlock,
+	parseCodeBlocks,
+} from "../../domain";
+import type { CodeBlockOptions } from "../../types";
+
+/**
+ * Enhance all code blocks in markdown content
+ */
+export const enhanceCodeBlocks = (
+	content: string,
+	options: CodeBlockOptions = {},
+): string => {
+	const codeBlocks = parseCodeBlocks(content);
+	let enhancedContent = content;
+
+	for (const block of codeBlocks) {
+		const enhanced = enhanceCodeBlock(block, options);
+		const originalCode = block.code;
+		const newCode = enhanced.lineNumbers
+			? addLineNumbers(originalCode)
+			: originalCode;
+
+		// Replace code block in content
+		enhancedContent = enhancedContent.replace(
+			`\`\`\`${block.language || ""}${block.filename ? ` ${block.filename}` : ""}\n${originalCode}\n\`\`\``,
+			`\`\`\`${enhanced.language || ""}${enhanced.filename ? ` ${enhanced.filename}` : ""}\n${newCode}\n\`\`\``,
+		);
+	}
+
+	return enhancedContent;
+};

package/src/modules/code-block-enhancements/domain/code-operations.ts

@@ -0,0 +1,72 @@
+/**
+ * Code Block Operations
+ *
+ * Pure functions for code block enhancements
+ */
+
+import type { CodeBlock, CodeBlockOptions } from "../types";
+
+/**
+ * Parse code blocks from markdown content
+ */
+export const parseCodeBlocks = (content: string): CodeBlock[] => {
+	const codeBlocks: CodeBlock[] = [];
+	const lines = content.split("\n");
+	let inCodeBlock = false;
+	let currentBlock: Partial<CodeBlock> = {};
+	let codeLines: string[] = [];
+
+	for (const line of lines) {
+		const codeMatch = line.match(/^```(\w+)?\s*(.*)?$/);
+		const endMatch = line.match(/^```$/);
+
+		if (codeMatch && !inCodeBlock) {
+			inCodeBlock = true;
+			currentBlock = {
+				language: codeMatch[1] || undefined,
+				filename: codeMatch[2] || undefined,
+			};
+			codeLines = [];
+		} else if (endMatch && inCodeBlock) {
+			inCodeBlock = false;
+			currentBlock.code = codeLines.join("\n");
+			codeBlocks.push(currentBlock as CodeBlock);
+			currentBlock = {};
+			codeLines = [];
+		} else if (inCodeBlock) {
+			codeLines.push(line);
+		}
+	}
+
+	return codeBlocks;
+};
+
+/**
+ * Enhance code block with options
+ */
+export const enhanceCodeBlock = (
+	block: CodeBlock,
+	options: CodeBlockOptions = {},
+): CodeBlock => {
+	return {
+		...block,
+		lineNumbers: options.lineNumbers ?? true,
+		highlightLines: options.highlightLines || block.highlightLines,
+		filename: options.filename || block.filename,
+	};
+};
+
+/**
+ * Add line numbers to code
+ */
+export const addLineNumbers = (code: string): string => {
+	const lines = code.split("\n");
+	const maxDigits = lines.length.toString().length;
+
+	return lines
+		.map((line, index) => {
+			const lineNumber = (index + 1).toString().padStart(maxDigits, " ");
+			return `${lineNumber} | ${line}`;
+		})
+		.join("\n");
+};

package/src/modules/code-block-enhancements/domain/events/index.ts

@@ -0,0 +1,58 @@
+/**
+ * Domain events for code block enhancements
+ */
+export interface CodeBlockCopiedEvent {
+	readonly type: "CODE_BLOCK_COPIED";
+	readonly timestamp: number;
+	readonly blockId: string;
+}
+
+export interface CodeBlockDownloadedEvent {
+	readonly type: "CODE_BLOCK_DOWNLOADED";
+	readonly timestamp: number;
+	readonly blockId: string;
+	readonly filename: string;
+}
+
+export interface LineHighlightedEvent {
+	readonly type: "LINE_HIGHLIGHTED";
+	readonly timestamp: number;
+	readonly blockId: string;
+	readonly lineNumber: number;
+}
+
+export type CodeBlockEnhancementsDomainEvent =
+	| CodeBlockCopiedEvent
+	| CodeBlockDownloadedEvent
+	| LineHighlightedEvent;
+
+export const createCodeBlockCopiedEvent = (
+	blockId: string,
+	now: number = Date.now(),
+): CodeBlockCopiedEvent => ({
+	type: "CODE_BLOCK_COPIED",
+	timestamp: now,
+	blockId,
+});
+
+export const createCodeBlockDownloadedEvent = (
+	blockId: string,
+	filename: string,
+	now: number = Date.now(),
+): CodeBlockDownloadedEvent => ({
+	type: "CODE_BLOCK_DOWNLOADED",
+	timestamp: now,
+	blockId,
+	filename,
+});
+
+export const createLineHighlightedEvent = (
+	blockId: string,
+	lineNumber: number,
+	now: number = Date.now(),
+): LineHighlightedEvent => ({
+	type: "LINE_HIGHLIGHTED",
+	timestamp: now,
+	blockId,
+	lineNumber,
+});

package/src/modules/code-block-enhancements/domain/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Code Block Enhancements Domain
+ *
+ * Pure business logic for code block enhancements
+ */
+
+export {
+	addLineNumbers,
+	enhanceCodeBlock,
+	parseCodeBlocks,
+} from "./code-operations";