@libar-dev/architect 1.0.0-pre.3

package/dist/validation/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @architect
+ * @architect-validation
+ * @architect-pattern DoDValidationTypes
+ * @architect-status completed
+ * @architect-used-by DoDValidator, AntiPatternDetector
+ * @architect-extract-shapes AntiPatternId, AntiPatternViolation, AntiPatternThresholds, AntiPatternThresholdsSchema, DEFAULT_THRESHOLDS, DoDValidationResult, DoDValidationSummary, getPhaseStatusEmoji, WithTagRegistry
+ *
+ * ## DoDValidationTypes - Type Definitions for DoD Validation
+ *
+ * Types and schemas for Definition of Done (DoD) validation and anti-pattern detection.
+ * Follows the project's schema-first pattern with Zod for runtime validation.
+ *
+ * ### When to Use
+ *
+ * - When implementing DoD validation logic
+ * - When extending anti-pattern detection rules
+ * - When consuming validation results in CLI or reports
+ */
+import { z } from 'zod';
+import type { Deliverable } from '../validation-schemas/dual-source.js';
+import type { TagRegistry } from '../validation-schemas/tag-registry.js';
+/**
+ * Base interface for options that accept a TagRegistry for prefix-aware behavior.
+ *
+ * Many validation functions need to be aware of the configured tag prefix
+ * (e.g., "@architect-" vs "@acme-"). This interface provides a consistent
+ * way to pass that configuration.
+ *
+ * ### When to Use
+ *
+ * Extend this interface when creating options for functions that:
+ * - Generate error messages referencing tag names
+ * - Detect tags in source code
+ * - Validate tag formats
+ *
+ * @example
+ * ```typescript
+ * export interface MyValidationOptions extends WithTagRegistry {
+ *   readonly strict?: boolean;
+ * }
+ * ```
+ */
+export interface WithTagRegistry {
+    /** Tag registry for prefix-aware behavior (defaults to @architect- if not provided) */
+    readonly registry?: TagRegistry;
+}
+/**
+ * Anti-pattern rule identifiers
+ *
+ * Each ID corresponds to a specific violation of the dual-source
+ * documentation architecture or process hygiene.
+ */
+export type AntiPatternId = 'tag-duplication' | 'process-in-code' | 'magic-comments' | 'scenario-bloat' | 'mega-feature';
+/**
+ * Zod schema for anti-pattern thresholds
+ *
+ * Configurable limits for detecting anti-patterns.
+ */
+export declare const AntiPatternThresholdsSchema: z.ZodObject<{
+    scenarioBloatThreshold: z.ZodDefault<z.ZodNumber>;
+    megaFeatureLineThreshold: z.ZodDefault<z.ZodNumber>;
+    magicCommentThreshold: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type AntiPatternThresholds = z.infer<typeof AntiPatternThresholdsSchema>;
+/**
+ * Default thresholds for anti-pattern detection
+ */
+export declare const DEFAULT_THRESHOLDS: AntiPatternThresholds;
+/**
+ * Anti-pattern detection result
+ *
+ * Reports a specific anti-pattern violation with context
+ * for remediation.
+ */
+export interface AntiPatternViolation {
+    /** Anti-pattern identifier */
+    readonly id: AntiPatternId;
+    /** Human-readable description */
+    readonly message: string;
+    /** File where violation was found */
+    readonly file: string;
+    /** Line number (if applicable) */
+    readonly line?: number;
+    /** Severity (error = architectural violation, warning = hygiene issue) */
+    readonly severity: 'error' | 'warning';
+    /** Fix guidance */
+    readonly fix?: string;
+}
+/**
+ * DoD validation result for a single phase/pattern
+ *
+ * Reports whether a completed phase meets Definition of Done criteria:
+ * 1. All deliverables must have "complete" status
+ * 2. At least one @acceptance-criteria scenario must exist
+ */
+export interface DoDValidationResult {
+    /** Pattern name being validated */
+    readonly patternName: string;
+    /** Phase number being validated */
+    readonly phase: number;
+    /** True if all DoD criteria are met */
+    readonly isDoDMet: boolean;
+    /** All deliverables from Background table */
+    readonly deliverables: readonly Deliverable[];
+    /** Deliverables that are not yet complete */
+    readonly incompleteDeliverables: readonly Deliverable[];
+    /** True if no @acceptance-criteria scenarios found */
+    readonly missingAcceptanceCriteria: boolean;
+    /** Human-readable validation messages */
+    readonly messages: readonly string[];
+}
+/**
+ * Aggregate DoD validation summary
+ *
+ * Summarizes validation across multiple phases for CLI output.
+ */
+export interface DoDValidationSummary {
+    /** Per-phase validation results */
+    readonly results: readonly DoDValidationResult[];
+    /** Total phases validated */
+    readonly totalPhases: number;
+    /** Phases that passed DoD */
+    readonly passedPhases: number;
+    /** Phases that failed DoD */
+    readonly failedPhases: number;
+}
+/**
+ * Get status emoji for phase-level aggregates.
+ *
+ * @param allComplete - Whether all patterns in the phase are complete
+ * @param anyActive - Whether any patterns in the phase are active/in-progress
+ * @returns Status emoji: ✅ if all complete, 🚧 if any active, 📋 otherwise
+ */
+export declare function getPhaseStatusEmoji(allComplete: boolean, anyActive: boolean): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/validation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/validation/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sCAAsC,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAC;AAMzE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC;CACjC;AAMD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB,iBAAiB,GACjB,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,cAAc,CAAC;AAEnB;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;iBAOtC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,qBAIhC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,mBAAmB;IACnB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9C,6CAA6C;IAC7C,QAAQ,CAAC,sBAAsB,EAAE,SAAS,WAAW,EAAE,CAAC;IACxD,sDAAsD;IACtD,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAC;IAC5C,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,6BAA6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAIpF"}

package/dist/validation/types.js

@@ -0,0 +1,56 @@
+/**
+ * @architect
+ * @architect-validation
+ * @architect-pattern DoDValidationTypes
+ * @architect-status completed
+ * @architect-used-by DoDValidator, AntiPatternDetector
+ * @architect-extract-shapes AntiPatternId, AntiPatternViolation, AntiPatternThresholds, AntiPatternThresholdsSchema, DEFAULT_THRESHOLDS, DoDValidationResult, DoDValidationSummary, getPhaseStatusEmoji, WithTagRegistry
+ *
+ * ## DoDValidationTypes - Type Definitions for DoD Validation
+ *
+ * Types and schemas for Definition of Done (DoD) validation and anti-pattern detection.
+ * Follows the project's schema-first pattern with Zod for runtime validation.
+ *
+ * ### When to Use
+ *
+ * - When implementing DoD validation logic
+ * - When extending anti-pattern detection rules
+ * - When consuming validation results in CLI or reports
+ */
+import { z } from 'zod';
+/**
+ * Zod schema for anti-pattern thresholds
+ *
+ * Configurable limits for detecting anti-patterns.
+ */
+export const AntiPatternThresholdsSchema = z.object({
+    /** Maximum scenarios per feature file before warning */
+    scenarioBloatThreshold: z.number().int().positive().default(30),
+    /** Maximum lines per feature file before warning */
+    megaFeatureLineThreshold: z.number().int().positive().default(750),
+    /** Maximum magic comments before warning */
+    magicCommentThreshold: z.number().int().positive().default(5),
+});
+/**
+ * Default thresholds for anti-pattern detection
+ */
+export const DEFAULT_THRESHOLDS = {
+    scenarioBloatThreshold: 30,
+    megaFeatureLineThreshold: 750,
+    magicCommentThreshold: 5,
+};
+/**
+ * Get status emoji for phase-level aggregates.
+ *
+ * @param allComplete - Whether all patterns in the phase are complete
+ * @param anyActive - Whether any patterns in the phase are active/in-progress
+ * @returns Status emoji: ✅ if all complete, 🚧 if any active, 📋 otherwise
+ */
+export function getPhaseStatusEmoji(allComplete, anyActive) {
+    if (allComplete)
+        return '✅';
+    if (anyActive)
+        return '🚧';
+    return '📋';
+}
+//# sourceMappingURL=types.js.map

package/dist/validation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/validation/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmDxB;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,wDAAwD;IACxD,sBAAsB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;IAC/D,oDAAoD;IACpD,wBAAwB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;IAClE,4CAA4C;IAC5C,qBAAqB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;CAC9D,CAAC,CAAC;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA0B;IACvD,sBAAsB,EAAE,EAAE;IAC1B,wBAAwB,EAAE,GAAG;IAC7B,qBAAqB,EAAE,CAAC;CACzB,CAAC;AA+DF;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAoB,EAAE,SAAkB;IAC1E,IAAI,WAAW;QAAE,OAAO,GAAG,CAAC;IAC5B,IAAI,SAAS;QAAE,OAAO,IAAI,CAAC;IAC3B,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/validation-schemas/codec-utils.d.ts

@@ -0,0 +1,188 @@
+/**
+ * @architect
+ * @architect-validation @architect-core
+ * @architect-pattern CodecUtils
+ * @architect-status completed
+ * @architect-uses Zod
+ * @architect-used-by WorkflowLoader, Orchestrator
+ * @architect-usecase "When loading JSON config files with type-safe validation"
+ * @architect-usecase "When serializing typed objects to formatted JSON"
+ *
+ * ## CodecUtils - Type-Safe JSON Codec Factories
+ *
+ * Provides factory functions for creating type-safe JSON parsing and serialization
+ * pipelines using Zod schemas. Replaces manual JSON.parse/stringify with single-step
+ * validated operations.
+ *
+ * ### When to Use
+ *
+ * - Use when loading JSON configuration files
+ * - Use when writing JSON output files with schema validation
+ * - Use when you want better error messages with file path context
+ *
+ * ### Key Concepts
+ *
+ * - **Input Codec**: Parses JSON string → validates → returns typed object
+ * - **Output Codec**: Validates object → serializes → returns formatted JSON string
+ * - **Error Context**: Adds file path and validation details to error messages
+ */
+import type { ZodType } from 'zod';
+import type { Result } from '../types/index.js';
+/**
+ * Error details for codec operations
+ */
+export interface CodecError {
+    /** Error type identifier */
+    type: 'codec-error';
+    /** Operation that failed: 'parse' or 'serialize' */
+    operation: 'parse' | 'serialize';
+    /** Optional source identifier (file path, URL, etc.) */
+    source?: string | undefined;
+    /** Human-readable error message */
+    message: string;
+    /** Detailed validation errors if schema validation failed */
+    validationErrors?: string[] | undefined;
+}
+/**
+ * JSON Input Codec - parses and validates JSON strings
+ *
+ * Combines JSON.parse and Zod schema validation into a single operation.
+ */
+export interface JsonInputCodec<T> {
+    /**
+     * Parse JSON string to typed object
+     *
+     * @param content - JSON string to parse
+     * @param source - Optional source identifier for error messages
+     * @returns Result with typed value or error
+     */
+    parse(content: string, source?: string): Result<T, CodecError>;
+    /**
+     * Safely parse JSON, returning undefined on failure
+     *
+     * @param content - JSON string to parse
+     * @returns Typed value or undefined
+     */
+    safeParse(content: string): T | undefined;
+}
+/**
+ * JSON Output Codec - validates and serializes objects to JSON
+ *
+ * Combines Zod validation and JSON.stringify into a single operation.
+ */
+export interface JsonOutputCodec<T> {
+    /**
+     * Serialize typed object to JSON string
+     *
+     * @param data - Object to serialize
+     * @param source - Optional source identifier for error messages
+     * @returns Result with JSON string or error
+     */
+    serialize(data: T, source?: string): Result<string, CodecError>;
+    /**
+     * Serialize with options
+     *
+     * @param data - Object to serialize
+     * @param options - Serialization options
+     * @returns Result with JSON string or error
+     */
+    serializeWithOptions(data: T, options: {
+        indent?: number | undefined;
+        source?: string | undefined;
+    }): Result<string, CodecError>;
+}
+/**
+ * Create a JSON input codec from a Zod schema
+ *
+ * The codec handles:
+ * - JSON parsing with syntax error handling
+ * - Zod schema validation
+ * - $schema field stripping (for JSON Schema references)
+ * - Detailed error messages with source context
+ *
+ * @param schema - Zod schema to validate against
+ * @returns JsonInputCodec instance
+ *
+ * @example
+ * ```typescript
+ * const WorkflowCodec = createJsonInputCodec(WorkflowConfigSchema);
+ *
+ * // Load and validate in one step
+ * const content = await fs.readFile("workflow.json", "utf-8");
+ * const result = WorkflowCodec.parse(content, "workflow.json");
+ *
+ * if (result.ok) {
+ *   // result.value is typed as WorkflowConfig
+ *   console.log(result.value.name);
+ * } else {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+export declare function createJsonInputCodec<T>(schema: ZodType<T>): JsonInputCodec<T>;
+/**
+ * Create a JSON output codec from a Zod schema
+ *
+ * The codec handles:
+ * - Zod schema validation before serialization
+ * - Formatted JSON output with configurable indentation
+ * - Detailed error messages with source context
+ *
+ * @param schema - Zod schema to validate against
+ * @param defaultIndent - Default indentation spaces (default: 2)
+ * @returns JsonOutputCodec instance
+ *
+ * @example
+ * ```typescript
+ * const RegistryCodec = createJsonOutputCodec(PatternRegistrySchema);
+ *
+ * const registry = { patterns: [...], metadata: {...} };
+ * const result = RegistryCodec.serialize(registry, "registry.json");
+ *
+ * if (result.ok) {
+ *   await fs.writeFile("registry.json", result.value, "utf-8");
+ * }
+ * ```
+ */
+export declare function createJsonOutputCodec<T>(schema: ZodType<T>, defaultIndent?: number): JsonOutputCodec<T>;
+/**
+ * Format codec error for console display
+ *
+ * @param error - Codec error
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * const result = codec.parse(content, "config.json");
+ * if (!result.ok) {
+ *   console.error(formatCodecError(result.error));
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export declare function formatCodecError(error: CodecError): string;
+/**
+ * Create a file loader that uses a codec for validation
+ *
+ * Combines file reading with codec parsing for a complete loading pipeline.
+ * This is a helper for the common pattern of reading a file and parsing it.
+ *
+ * @param codec - JsonInputCodec to use for parsing
+ * @param readFile - File reading function (e.g., fs.readFile)
+ * @returns Async function that loads and parses a file
+ *
+ * @example
+ * ```typescript
+ * import * as fs from "fs/promises";
+ *
+ * const WorkflowCodec = createJsonInputCodec(WorkflowConfigSchema);
+ * const loadWorkflow = createFileLoader(WorkflowCodec, (p) => fs.readFile(p, "utf-8"));
+ *
+ * const result = await loadWorkflow("config/workflow.json");
+ * if (result.ok) {
+ *   console.log(result.value.phases);
+ * }
+ * ```
+ */
+export declare function createFileLoader<T>(codec: JsonInputCodec<T>, readFile: (path: string) => Promise<string>): (path: string) => Promise<Result<T, CodecError>>;
+//# sourceMappingURL=codec-utils.d.ts.map

package/dist/validation-schemas/codec-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-utils.d.ts","sourceRoot":"","sources":["../../src/validation-schemas/codec-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,KAAK,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,oDAAoD;IACpD,SAAS,EAAE,OAAO,GAAG,WAAW,CAAC;IACjC,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAE/D;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAEhE;;;;;;OAMG;IACH,oBAAoB,CAClB,IAAI,EAAE,CAAC,EACP,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GACpE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC/B;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CA6C7E;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,aAAa,SAAI,GAChB,eAAe,CAAC,CAAC,CAAC,CA6CpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAS1D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EACxB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC1C,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAqClD"}

package/dist/validation-schemas/codec-utils.js

@@ -0,0 +1,258 @@
+/**
+ * @architect
+ * @architect-validation @architect-core
+ * @architect-pattern CodecUtils
+ * @architect-status completed
+ * @architect-uses Zod
+ * @architect-used-by WorkflowLoader, Orchestrator
+ * @architect-usecase "When loading JSON config files with type-safe validation"
+ * @architect-usecase "When serializing typed objects to formatted JSON"
+ *
+ * ## CodecUtils - Type-Safe JSON Codec Factories
+ *
+ * Provides factory functions for creating type-safe JSON parsing and serialization
+ * pipelines using Zod schemas. Replaces manual JSON.parse/stringify with single-step
+ * validated operations.
+ *
+ * ### When to Use
+ *
+ * - Use when loading JSON configuration files
+ * - Use when writing JSON output files with schema validation
+ * - Use when you want better error messages with file path context
+ *
+ * ### Key Concepts
+ *
+ * - **Input Codec**: Parses JSON string → validates → returns typed object
+ * - **Output Codec**: Validates object → serializes → returns formatted JSON string
+ * - **Error Context**: Adds file path and validation details to error messages
+ */
+import { Result as R } from '../types/index.js';
+/**
+ * Format Zod validation errors for display
+ *
+ * @param error - Zod error object
+ * @returns Array of formatted error strings
+ */
+function formatZodErrors(error) {
+    return error.issues.map((issue) => {
+        const pathStr = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+        return `  - ${pathStr}: ${issue.message}`;
+    });
+}
+/**
+ * Create a JSON input codec from a Zod schema
+ *
+ * The codec handles:
+ * - JSON parsing with syntax error handling
+ * - Zod schema validation
+ * - $schema field stripping (for JSON Schema references)
+ * - Detailed error messages with source context
+ *
+ * @param schema - Zod schema to validate against
+ * @returns JsonInputCodec instance
+ *
+ * @example
+ * ```typescript
+ * const WorkflowCodec = createJsonInputCodec(WorkflowConfigSchema);
+ *
+ * // Load and validate in one step
+ * const content = await fs.readFile("workflow.json", "utf-8");
+ * const result = WorkflowCodec.parse(content, "workflow.json");
+ *
+ * if (result.ok) {
+ *   // result.value is typed as WorkflowConfig
+ *   console.log(result.value.name);
+ * } else {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+export function createJsonInputCodec(schema) {
+    return {
+        parse(content, source) {
+            // Step 1: Parse JSON
+            let data;
+            try {
+                data = JSON.parse(content);
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                return R.err({
+                    type: 'codec-error',
+                    operation: 'parse',
+                    source,
+                    message: source ? `Invalid JSON in ${source}: ${message}` : `Invalid JSON: ${message}`,
+                });
+            }
+            // Step 2: Strip $schema field if present (JSON Schema references)
+            const configData = typeof data === 'object' && data !== null && '$schema' in data
+                ? (({ $schema: _, ...rest }) => rest)(data)
+                : data;
+            // Step 3: Validate with Zod
+            const parseResult = schema.safeParse(configData);
+            if (!parseResult.success) {
+                const validationErrors = formatZodErrors(parseResult.error);
+                return R.err({
+                    type: 'codec-error',
+                    operation: 'parse',
+                    source,
+                    message: source ? `Schema validation failed for ${source}` : 'Schema validation failed',
+                    validationErrors,
+                });
+            }
+            return R.ok(parseResult.data);
+        },
+        safeParse(content) {
+            const result = this.parse(content);
+            return result.ok ? result.value : undefined;
+        },
+    };
+}
+/**
+ * Create a JSON output codec from a Zod schema
+ *
+ * The codec handles:
+ * - Zod schema validation before serialization
+ * - Formatted JSON output with configurable indentation
+ * - Detailed error messages with source context
+ *
+ * @param schema - Zod schema to validate against
+ * @param defaultIndent - Default indentation spaces (default: 2)
+ * @returns JsonOutputCodec instance
+ *
+ * @example
+ * ```typescript
+ * const RegistryCodec = createJsonOutputCodec(PatternRegistrySchema);
+ *
+ * const registry = { patterns: [...], metadata: {...} };
+ * const result = RegistryCodec.serialize(registry, "registry.json");
+ *
+ * if (result.ok) {
+ *   await fs.writeFile("registry.json", result.value, "utf-8");
+ * }
+ * ```
+ */
+export function createJsonOutputCodec(schema, defaultIndent = 2) {
+    return {
+        serialize(data, source) {
+            return this.serializeWithOptions(data, { source, indent: defaultIndent });
+        },
+        serializeWithOptions(data, options = {}) {
+            const { indent = defaultIndent, source } = options;
+            // Validate before serialization
+            const parseResult = schema.safeParse(data);
+            if (!parseResult.success) {
+                const validationErrors = formatZodErrors(parseResult.error);
+                return R.err({
+                    type: 'codec-error',
+                    operation: 'serialize',
+                    source,
+                    message: source
+                        ? `Schema validation failed before serializing ${source}`
+                        : 'Schema validation failed before serialization',
+                    validationErrors,
+                });
+            }
+            // Serialize to JSON
+            try {
+                const jsonString = JSON.stringify(parseResult.data, null, indent);
+                return R.ok(jsonString);
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                return R.err({
+                    type: 'codec-error',
+                    operation: 'serialize',
+                    source,
+                    message: source
+                        ? `JSON serialization failed for ${source}: ${message}`
+                        : `JSON serialization failed: ${message}`,
+                });
+            }
+        },
+    };
+}
+/**
+ * Format codec error for console display
+ *
+ * @param error - Codec error
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * const result = codec.parse(content, "config.json");
+ * if (!result.ok) {
+ *   console.error(formatCodecError(result.error));
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export function formatCodecError(error) {
+    const lines = [`Codec error (${error.operation}): ${error.message}`];
+    if (error.validationErrors && error.validationErrors.length > 0) {
+        lines.push('Validation errors:');
+        lines.push(...error.validationErrors);
+    }
+    return lines.join('\n');
+}
+/**
+ * Create a file loader that uses a codec for validation
+ *
+ * Combines file reading with codec parsing for a complete loading pipeline.
+ * This is a helper for the common pattern of reading a file and parsing it.
+ *
+ * @param codec - JsonInputCodec to use for parsing
+ * @param readFile - File reading function (e.g., fs.readFile)
+ * @returns Async function that loads and parses a file
+ *
+ * @example
+ * ```typescript
+ * import * as fs from "fs/promises";
+ *
+ * const WorkflowCodec = createJsonInputCodec(WorkflowConfigSchema);
+ * const loadWorkflow = createFileLoader(WorkflowCodec, (p) => fs.readFile(p, "utf-8"));
+ *
+ * const result = await loadWorkflow("config/workflow.json");
+ * if (result.ok) {
+ *   console.log(result.value.phases);
+ * }
+ * ```
+ */
+export function createFileLoader(codec, readFile) {
+    return async (path) => {
+        try {
+            const content = await readFile(path);
+            return codec.parse(content, path);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            // Check for common file errors
+            if (e instanceof Error && 'code' in e) {
+                const nodeError = e;
+                if (nodeError.code === 'ENOENT') {
+                    return R.err({
+                        type: 'codec-error',
+                        operation: 'parse',
+                        source: path,
+                        message: `File not found: ${path}`,
+                    });
+                }
+                if (nodeError.code === 'EACCES') {
+                    return R.err({
+                        type: 'codec-error',
+                        operation: 'parse',
+                        source: path,
+                        message: `Permission denied: ${path}`,
+                    });
+                }
+            }
+            return R.err({
+                type: 'codec-error',
+                operation: 'parse',
+                source: path,
+                message: `Failed to read file ${path}: ${message}`,
+            });
+        }
+    };
+}
+//# sourceMappingURL=codec-utils.js.map

package/dist/validation-schemas/codec-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-utils.js","sourceRoot":"","sources":["../../src/validation-schemas/codec-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,EAAE,MAAM,IAAI,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAsEhD;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAe;IACtC,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAChC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACxE,OAAO,OAAO,OAAO,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IAC5C,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,oBAAoB,CAAI,MAAkB;IACxD,OAAO;QACL,KAAK,CAAC,OAAe,EAAE,MAAe;YACpC,qBAAqB;YACrB,IAAI,IAAa,CAAC;YAClB,IAAI,CAAC;gBACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC7B,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,OAAO,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBAC3D,OAAO,CAAC,CAAC,GAAG,CAAC;oBACX,IAAI,EAAE,aAAa;oBACnB,SAAS,EAAE,OAAO;oBAClB,MAAM;oBACN,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,mBAAmB,MAAM,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,iBAAiB,OAAO,EAAE;iBACvF,CAAC,CAAC;YACL,CAAC;YAED,kEAAkE;YAClE,MAAM,UAAU,GACd,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,SAAS,IAAI,IAAI;gBAC5D,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAA+B,CAAC;gBACtE,CAAC,CAAC,IAAI,CAAC;YAEX,4BAA4B;YAC5B,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;YAEjD,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;gBACzB,MAAM,gBAAgB,GAAG,eAAe,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;gBAC5D,OAAO,CAAC,CAAC,GAAG,CAAC;oBACX,IAAI,EAAE,aAAa;oBACnB,SAAS,EAAE,OAAO;oBAClB,MAAM;oBACN,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,gCAAgC,MAAM,EAAE,CAAC,CAAC,CAAC,0BAA0B;oBACvF,gBAAgB;iBACjB,CAAC,CAAC;YACL,CAAC;YAED,OAAO,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;QAED,SAAS,CAAC,OAAe;YACvB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACnC,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9C,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAkB,EAClB,aAAa,GAAG,CAAC;IAEjB,OAAO;QACL,SAAS,CAAC,IAAO,EAAE,MAAe;YAChC,OAAO,IAAI,CAAC,oBAAoB,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;QAC5E,CAAC;QAED,oBAAoB,CAClB,IAAO,EACP,UAAwE,EAAE;YAE1E,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;YAEnD,gCAAgC;YAChC,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAE3C,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;gBACzB,MAAM,gBAAgB,GAAG,eAAe,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;gBAC5D,OAAO,CAAC,CAAC,GAAG,CAAC;oBACX,IAAI,EAAE,aAAa;oBACnB,SAAS,EAAE,WAAW;oBACtB,MAAM;oBACN,OAAO,EAAE,MAAM;wBACb,CAAC,CAAC,+CAA+C,MAAM,EAAE;wBACzD,CAAC,CAAC,+CAA+C;oBACnD,gBAAgB;iBACjB,CAAC,CAAC;YACL,CAAC;YAED,oBAAoB;YACpB,IAAI,CAAC;gBACH,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;gBAClE,OAAO,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,OAAO,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBAC3D,OAAO,CAAC,CAAC,GAAG,CAAC;oBACX,IAAI,EAAE,aAAa;oBACnB,SAAS,EAAE,WAAW;oBACtB,MAAM;oBACN,OAAO,EAAE,MAAM;wBACb,CAAC,CAAC,iCAAiC,MAAM,KAAK,OAAO,EAAE;wBACvD,CAAC,CAAC,8BAA8B,OAAO,EAAE;iBAC5C,CAAC,CAAC;YACL,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAiB;IAChD,MAAM,KAAK,GAAG,CAAC,gBAAgB,KAAK,CAAC,SAAS,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAErE,IAAI,KAAK,CAAC,gBAAgB,IAAI,KAAK,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChE,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACxC,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAwB,EACxB,QAA2C;IAE3C,OAAO,KAAK,EAAE,IAAY,EAAkC,EAAE;QAC5D,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;YACrC,OAAO,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,OAAO,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAE3D,+BAA+B;YAC/B,IAAI,CAAC,YAAY,KAAK,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;gBACtC,MAAM,SAAS,GAAG,CAA0B,CAAC;gBAC7C,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAChC,OAAO,CAAC,CAAC,GAAG,CAAC;wBACX,IAAI,EAAE,aAAa;wBACnB,SAAS,EAAE,OAAO;wBAClB,MAAM,EAAE,IAAI;wBACZ,OAAO,EAAE,mBAAmB,IAAI,EAAE;qBACnC,CAAC,CAAC;gBACL,CAAC;gBACD,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAChC,OAAO,CAAC,CAAC,GAAG,CAAC;wBACX,IAAI,EAAE,aAAa;wBACnB,SAAS,EAAE,OAAO;wBAClB,MAAM,EAAE,IAAI;wBACZ,OAAO,EAAE,sBAAsB,IAAI,EAAE;qBACtC,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YAED,OAAO,CAAC,CAAC,GAAG,CAAC;gBACX,IAAI,EAAE,aAAa;gBACnB,SAAS,EAAE,OAAO;gBAClB,MAAM,EAAE,IAAI;gBACZ,OAAO,EAAE,uBAAuB,IAAI,KAAK,OAAO,EAAE;aACnD,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}