@wrikka/create-docs 0.1.0

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

@@ -0,0 +1,58 @@
+/**
+ * Domain events for content linting
+ */
+export interface LintingStartedEvent {
+	readonly type: "LINTING_STARTED";
+	readonly timestamp: number;
+	readonly filePath: string;
+}
+
+export interface LintingCompletedEvent {
+	readonly type: "LINTING_COMPLETED";
+	readonly timestamp: number;
+	readonly filePath: string;
+	readonly issueCount: number;
+}
+
+export interface IssueFoundEvent {
+	readonly type: "ISSUE_FOUND";
+	readonly timestamp: number;
+	readonly ruleId: string;
+	readonly message: string;
+}
+
+export type ContentLintingDomainEvent =
+	| LintingStartedEvent
+	| LintingCompletedEvent
+	| IssueFoundEvent;
+
+export const createLintingStartedEvent = (
+	filePath: string,
+	now: number = Date.now(),
+): LintingStartedEvent => ({
+	type: "LINTING_STARTED",
+	timestamp: now,
+	filePath,
+});
+
+export const createLintingCompletedEvent = (
+	filePath: string,
+	issueCount: number,
+	now: number = Date.now(),
+): LintingCompletedEvent => ({
+	type: "LINTING_COMPLETED",
+	timestamp: now,
+	filePath,
+	issueCount,
+});
+
+export const createIssueFoundEvent = (
+	ruleId: string,
+	message: string,
+	now: number = Date.now(),
+): IssueFoundEvent => ({
+	type: "ISSUE_FOUND",
+	timestamp: now,
+	ruleId,
+	message,
+});

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

@@ -0,0 +1,46 @@
+/**
+ * Domain models for content linting
+ */
+export interface LintRule {
+	readonly id: string;
+	readonly name: string;
+	readonly description: string;
+	readonly severity: "error" | "warning" | "info";
+	readonly enabled: boolean;
+}
+
+export interface LintIssue {
+	readonly ruleId: string;
+	readonly message: string;
+	readonly line: number;
+	readonly column: number;
+	readonly severity: "error" | "warning" | "info";
+}
+
+export const createLintRule = (
+	id: string,
+	name: string,
+	description: string,
+	severity: LintRule["severity"],
+	enabled: boolean = true,
+): LintRule => ({
+	id,
+	name,
+	description,
+	severity,
+	enabled,
+});
+
+export const createLintIssue = (
+	ruleId: string,
+	message: string,
+	line: number,
+	column: number,
+	severity: LintIssue["severity"],
+): LintIssue => ({
+	ruleId,
+	message,
+	line,
+	column,
+	severity,
+});

package/src/modules/content-linting/domain/operations/linting-operations.ts

@@ -0,0 +1,82 @@
+/**
+ * Pure content linting 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 { LintResult, LintRule } from "../../types/linting";
+
+export type LintingError = {
+	readonly kind: "linting-error";
+	readonly message: string;
+};
+
+/**
+ * Check for missing title in frontmatter.
+ */
+export const checkMissingTitle = (frontmatter: unknown): LintResult | null => {
+	if (!frontmatter || typeof frontmatter !== "object") return null;
+	const fm = frontmatter as Record<string, unknown>;
+	if (!fm.title) {
+		return {
+			ruleId: "missing-title",
+			message: "Document is missing a title",
+			line: 1,
+			column: 1,
+			severity: "error",
+		};
+	}
+	return null;
+};
+
+/**
+ * Check for missing description in frontmatter.
+ */
+export const checkMissingDescription = (
+	frontmatter: unknown,
+): LintResult | null => {
+	if (!frontmatter || typeof frontmatter !== "object") return null;
+	const fm = frontmatter as Record<string, unknown>;
+	if (!fm.description) {
+		return {
+			ruleId: "missing-description",
+			message: "Document is missing a description",
+			line: 1,
+			column: 1,
+			severity: "warning",
+		};
+	}
+	return null;
+};
+
+/**
+ * Run all lint rules on content.
+ */
+export const runLintRules = (
+	_content: string,
+	frontmatter: unknown,
+	rules: readonly LintRule[],
+): Result<readonly LintResult[], LintingError> => {
+	try {
+		const results: LintResult[] = [];
+
+		for (const rule of rules) {
+			if (rule.id === "missing-title") {
+				const result = checkMissingTitle(frontmatter);
+				if (result) results.push(result);
+			}
+			if (rule.id === "missing-description") {
+				const result = checkMissingDescription(frontmatter);
+				if (result) results.push(result);
+			}
+		}
+
+		return ok(results);
+	} catch (error) {
+		return err({
+			kind: "linting-error",
+			message: error instanceof Error ? error.message : "Unknown error",
+		});
+	}
+};

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

@@ -0,0 +1,50 @@
+// Content Linting Domain Schemas - Arktype validation schemas
+// Following /follow-arktype workflow for type-safe runtime validation
+
+import { type Type, type } from "arktype";
+
+/**
+ * Rule Name Schema
+ */
+export const ruleNameSchema: Type = type("string >= 1");
+
+export type RuleName = typeof ruleNameSchema.infer;
+
+/**
+ * Severity Schema
+ */
+export const severitySchema: Type = type("'error' | 'warning' | 'info'");
+
+export type Severity = typeof severitySchema.infer;
+
+/**
+ * Validation errors
+ */
+export class ValidationError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}
+
+/**
+ * Validate rule name using Arktype
+ */
+export const validateRuleName = (name: unknown): RuleName => {
+	const result = ruleNameSchema(name);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Rule name must be a non-empty string");
+	}
+	return result as RuleName;
+};
+
+/**
+ * Validate severity using Arktype
+ */
+export const validateSeverity = (severity: unknown): Severity => {
+	const result = severitySchema(severity);
+	if (result instanceof type.errors) {
+		throw new ValidationError("Invalid severity level");
+	}
+	return result as Severity;
+};

package/src/modules/content-linting/index.ts

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

package/src/modules/content-linting/ports/linting-port.ts

@@ -0,0 +1,21 @@
+/**
+ * Port for content linting operations.
+ */
+
+export type LintingPort = {
+	/**
+	 * Lint content file.
+	 */
+	readonly lint: (
+		filePath: string,
+		rules: readonly unknown[],
+	) => Promise<readonly unknown[]>;
+
+	/**
+	 * Fix lint issues.
+	 */
+	readonly fix: (
+		filePath: string,
+		results: readonly unknown[],
+	) => Promise<void>;
+};

package/src/modules/content-linting/types/linting.ts

@@ -0,0 +1,18 @@
+/**
+ * Content linting types for validating documentation content.
+ */
+
+export type LintRule = {
+	readonly id: string;
+	readonly name: string;
+	readonly description: string;
+	readonly severity: "error" | "warning" | "info";
+};
+
+export type LintResult = {
+	readonly ruleId: string;
+	readonly message: string;
+	readonly line: number;
+	readonly column: number;
+	readonly severity: "error" | "warning" | "info";
+};

package/src/modules/content-validation/application/usecases/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Content Validation Use Cases
+ *
+ * Orchestration layer for content validation
+ */
+
+import { validateContent } from "../../domain";
+import type { ValidationOptions, ValidationResult } from "../../types";
+
+/**
+ * Validate content
+ */
+export const validate = (
+	content: string,
+	options: ValidationOptions = {},
+): ValidationResult => {
+	return validateContent(content, options);
+};

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

@@ -0,0 +1,7 @@
+/**
+ * Content Validation Domain Events
+ *
+ * Domain event types for content validation
+ */
+
+// Placeholder for future domain events

package/src/modules/content-validation/domain/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Content Validation Domain
+ *
+ * Pure business logic for content validation
+ */
+
+export * from "./events";
+export * from "./models";
+export {
+	validateCodeBlocks,
+	validateContent,
+	validateHeadings,
+	validateImages,
+	validateLinks,
+} from "./operations";
+export * from "./validators";

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

@@ -0,0 +1,33 @@
+/**
+ * Content Validation Domain Models
+ *
+ * Readonly data models for content validation
+ */
+
+/**
+ * Validation error model
+ */
+export interface ValidationError {
+	readonly message: string;
+	readonly line?: number;
+	readonly column?: number;
+	readonly severity: "error" | "warning" | "info";
+}
+
+/**
+ * Validation result model
+ */
+export interface ValidationResult {
+	readonly valid: boolean;
+	readonly errors: readonly ValidationError[];
+}
+
+/**
+ * Validation options model
+ */
+export interface ValidationOptions {
+	readonly checkHeadings?: boolean;
+	readonly checkLinks?: boolean;
+	readonly checkImages?: boolean;
+	readonly checkCodeBlocks?: boolean;
+}

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

@@ -0,0 +1,157 @@
+/**
+ * Content Validation Operations
+ *
+ * Pure functions for content validation
+ */
+
+import type {
+	ValidationError,
+	ValidationOptions,
+	ValidationResult,
+} from "../types";
+
+/**
+ * Validate heading hierarchy
+ */
+export const validateHeadings = (content: string): ValidationError[] => {
+	const errors: ValidationError[] = [];
+	const lines = content.split("\n");
+	let lastLevel = 0;
+
+	for (const line of lines) {
+		const match = line.match(/^(#{1,6})\s+(.+)$/);
+		if (match) {
+			const level = match[1].length;
+			const lineNum = lines.indexOf(line) + 1;
+
+			if (level > lastLevel + 1) {
+				errors.push({
+					message: `Heading level ${level} should not be more than one level deeper than ${lastLevel}`,
+					line: lineNum,
+					severity: "warning",
+				});
+			}
+
+			lastLevel = level;
+		}
+	}
+
+	return errors;
+};
+
+/**
+ * Validate links
+ */
+export const validateLinks = (content: string): ValidationError[] => {
+	const errors: ValidationError[] = [];
+	const lines = content.split("\n");
+
+	for (const line of lines) {
+		const linkMatch = line.match(/\[([^\]]+)\]\(([^)]+)\)/);
+		if (linkMatch) {
+			const url = linkMatch[2];
+			const lineNum = lines.indexOf(line) + 1;
+
+			if (
+				!url.startsWith("http") &&
+				!url.startsWith("#") &&
+				!url.startsWith("/")
+			) {
+				errors.push({
+					message: `Link "${url}" should be absolute or start with # or /`,
+					line: lineNum,
+					severity: "warning",
+				});
+			}
+		}
+	}
+
+	return errors;
+};
+
+/**
+ * Validate images
+ */
+export const validateImages = (content: string): ValidationError[] => {
+	const errors: ValidationError[] = [];
+	const lines = content.split("\n");
+
+	for (const line of lines) {
+		const imageMatch = line.match(/!\[([^\]]*)\]\(([^)]+)\)/);
+		if (imageMatch) {
+			const alt = imageMatch[1];
+			const lineNum = lines.indexOf(line) + 1;
+
+			if (!alt) {
+				errors.push({
+					message: "Image should have alt text",
+					line: lineNum,
+					severity: "error",
+				});
+			}
+		}
+	}
+
+	return errors;
+};
+
+/**
+ * Validate code blocks
+ */
+export const validateCodeBlocks = (content: string): ValidationError[] => {
+	const errors: ValidationError[] = [];
+	const lines = content.split("\n");
+	let inCodeBlock = false;
+	let codeBlockStart = 0;
+
+	for (const line of lines) {
+		const codeMatch = line.match(/^```(\w+)?$/);
+		if (codeMatch && !inCodeBlock) {
+			inCodeBlock = true;
+			codeBlockStart = lines.indexOf(line) + 1;
+		} else if (line === "```" && inCodeBlock) {
+			inCodeBlock = false;
+		}
+	}
+
+	if (inCodeBlock) {
+		errors.push({
+			message: "Unclosed code block",
+			line: codeBlockStart,
+			severity: "error",
+		});
+	}
+
+	return errors;
+};
+
+/**
+ * Validate content
+ */
+export const validateContent = (
+	content: string,
+	options: ValidationOptions = {},
+): ValidationResult => {
+	const errors: ValidationError[] = [];
+
+	if (options.checkHeadings !== false) {
+		errors.push(...validateHeadings(content));
+	}
+
+	if (options.checkLinks !== false) {
+		errors.push(...validateLinks(content));
+	}
+
+	if (options.checkImages !== false) {
+		errors.push(...validateImages(content));
+	}
+
+	if (options.checkCodeBlocks !== false) {
+		errors.push(...validateCodeBlocks(content));
+	}
+
+	return {
+		valid: errors.filter((e) => e.severity === "error").length === 0,
+		errors,
+	};
+};

package/src/modules/content-validation/domain/types/index.ts

@@ -0,0 +1,17 @@
+export type ValidationError = Readonly<{
+	message: string;
+	line?: number;
+	severity: "error" | "warning";
+}>;
+
+export type ValidationOptions = Readonly<{
+	checkHeadings?: boolean;
+	checkLinks?: boolean;
+	checkImages?: boolean;
+	checkCodeBlocks?: boolean;
+}>;
+
+export type ValidationResult = Readonly<{
+	valid: boolean;
+	errors: readonly ValidationError[];
+}>;

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

@@ -0,0 +1,8 @@
+/**
+ * Content Validation Domain Validators
+ *
+ * Pure validation functions for content validation
+ */
+
+// Placeholder for future validation logic
+

package/src/modules/content-validation/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Content Validation Module
+ *
+ * Content validation for documentation
+ */
+
+export { validate } from "./application/usecases";
+export * from "./domain";
+export * from "./ports";

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

@@ -0,0 +1,15 @@
+/**
+ * Content Validation Ports
+ *
+ * Module-specific interfaces for content validation
+ */
+
+import type { ValidationOptions, ValidationResult } from "../types";
+
+/**
+ * Content validator interface
+ */
+export interface ContentValidator {
+	/** Validate content */
+	validate(content: string, options?: ValidationOptions): ValidationResult;
+}

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

@@ -0,0 +1,5 @@
+export type {
+	ValidationError,
+	ValidationOptions,
+	ValidationResult,
+} from "../domain/types";

package/src/modules/export/application/puppeteer-export-adapter.ts

@@ -0,0 +1,63 @@
+/**
+ * Puppeteer export adapter implementation.
+ * Provides PDF/EPUB export using Puppeteer.
+ */
+
+import { processExportResult } from "../domain/operations/export-operations";
+import type { ExportPort } from "../ports/export-port";
+import type { ExportConfig } from "../types/export";
+
+const PUPPETEER_MISSING_ERROR =
+	"Puppeteer is not installed. PDF/EPUB export requires the puppeteer package and a Chromium binary.";
+
+export const createPuppeteerExportAdapter = (): ExportPort => ({
+	exportToPdf: async (_content: string, config?: unknown) => {
+		try {
+			if (typeof window !== "undefined") {
+				return processExportResult(
+					false,
+					"",
+					"PDF export is only supported in a Node.js build environment with Puppeteer.",
+				);
+			}
+
+			const exportConfig = config as ExportConfig;
+			if (!exportConfig?.outputDir) {
+				return processExportResult(false, "", "Output directory not specified");
+			}
+
+			return processExportResult(false, "", PUPPETEER_MISSING_ERROR);
+		} catch (error) {
+			return processExportResult(
+				false,
+				"",
+				error instanceof Error ? error.message : "Unknown error",
+			);
+		}
+	},
+
+	exportToEpub: async (_content: string, config?: unknown) => {
+		try {
+			if (typeof window !== "undefined") {
+				return processExportResult(
+					false,
+					"",
+					"EPUB export is only supported in a Node.js build environment with Puppeteer.",
+				);
+			}
+
+			const exportConfig = config as ExportConfig;
+			if (!exportConfig?.outputDir) {
+				return processExportResult(false, "", "Output directory not specified");
+			}
+
+			return processExportResult(false, "", PUPPETEER_MISSING_ERROR);
+		} catch (error) {
+			return processExportResult(
+				false,
+				"",
+				error instanceof Error ? error.message : "Unknown error",
+			);
+		}
+	},
+});