@libar-dev/architect 1.0.0-pre.3

package/dist/types/errors.js

@@ -0,0 +1,251 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern ErrorFactoryTypes
+ * @architect-status completed
+ * @architect-implements ErrorFactories
+ * @architect-product-area CoreTypes
+ *
+ * ## Error Factories - Type Definitions
+ *
+ * Structured, discriminated error types with factory functions.
+ * Each error type has a unique `type` discriminator for exhaustive pattern matching.
+ *
+ * **When to Use:** When creating or handling domain-specific errors — use these factory types instead of plain Error for exhaustive matching.
+ */
+/**
+ * Create a FileSystemError
+ *
+ * @param file - File path that caused the error
+ * @param reason - Specific reason for the failure
+ * @param originalError - Optional underlying error
+ * @returns Structured FileSystemError
+ *
+ * @example
+ * ```typescript
+ * const error = createFileSystemError(
+ *   '/path/to/file.ts',
+ *   'NOT_FOUND',
+ *   new Error('ENOENT')
+ * );
+ * ```
+ */
+export function createFileSystemError(file, reason, originalError) {
+    const reasonMessages = {
+        NOT_FOUND: `File not found: ${file}`,
+        NO_PERMISSION: `Permission denied: ${file}`,
+        NOT_A_FILE: `Not a file: ${file}`,
+        OTHER: `File system error: ${file}`,
+    };
+    // Use spread to conditionally include optional fields
+    return {
+        type: 'FILE_SYSTEM_ERROR',
+        message: reasonMessages[reason],
+        file,
+        reason,
+        ...(originalError !== undefined && { originalError }),
+    };
+}
+/**
+ * Create a FileParseError
+ *
+ * @param file - File path that failed to parse
+ * @param reason - Description of parsing failure
+ * @param location - Optional line/column information
+ * @param originalError - Optional underlying error
+ * @returns Structured FileParseError
+ *
+ * @example
+ * ```typescript
+ * const error = createFileParseError(
+ *   '/path/to/file.ts',
+ *   'Unexpected token',
+ *   { line: 42, column: 10 },
+ *   originalError
+ * );
+ * ```
+ */
+export function createFileParseError(file, reason, location, originalError) {
+    const locationStr = location ? ` at line ${location.line}, column ${location.column}` : '';
+    // Use spread to conditionally include optional fields
+    return {
+        type: 'FILE_PARSE_ERROR',
+        message: `Failed to parse ${file}${locationStr}: ${reason}`,
+        file,
+        reason,
+        ...(location && { line: location.line, column: location.column }),
+        ...(originalError !== undefined && { originalError }),
+    };
+}
+/**
+ * Create a DirectiveValidationError
+ *
+ * @param file - Source file containing invalid directive
+ * @param line - Line number where directive was found
+ * @param reason - Why validation failed
+ * @param directive - Optional directive text snippet
+ * @returns Structured DirectiveValidationError
+ *
+ * @example
+ * ```typescript
+ * const error = createDirectiveValidationError(
+ *   'src/utils.ts',
+ *   42,
+ *   'Missing required tags',
+ *   '@architect-'
+ * );
+ * ```
+ */
+export function createDirectiveValidationError(file, line, reason, directive) {
+    // Use spread to conditionally include optional fields
+    return {
+        type: 'DIRECTIVE_VALIDATION_ERROR',
+        message: `Directive validation failed at ${file}:${line}: ${reason}`,
+        file,
+        line,
+        reason,
+        ...(directive !== undefined && { directive }),
+    };
+}
+/**
+ * Create a PatternValidationError
+ *
+ * @param file - Source file containing invalid pattern
+ * @param patternName - Name of the invalid pattern
+ * @param reason - Why validation failed
+ * @param validationErrors - Specific validation errors from schema
+ * @returns Structured PatternValidationError
+ *
+ * @example
+ * ```typescript
+ * const error = createPatternValidationError(
+ *   asSourceFilePath('src/types.ts'),
+ *   'User Schema',
+ *   'Invalid pattern structure',
+ *   ['tags: Required', 'description: Must be non-empty']
+ * );
+ * ```
+ */
+export function createPatternValidationError(file, patternName, reason, validationErrors) {
+    // Use spread to conditionally include optional fields
+    return {
+        type: 'PATTERN_VALIDATION_ERROR',
+        message: `Pattern validation failed for "${patternName}" in ${file}: ${reason}`,
+        file,
+        patternName,
+        reason,
+        ...(validationErrors !== undefined && { validationErrors }),
+    };
+}
+/**
+ * Create a FeatureParseError
+ *
+ * @param file - Feature file path that failed to parse
+ * @param reason - Description of parsing failure
+ * @param originalError - Optional underlying error
+ * @returns Structured FeatureParseError
+ *
+ * @example
+ * ```typescript
+ * const error = createFeatureParseError(
+ *   '/path/to/test.feature',
+ *   'Invalid Gherkin syntax',
+ *   originalError
+ * );
+ * ```
+ */
+export function createFeatureParseError(file, reason, originalError) {
+    return {
+        type: 'FEATURE_PARSE_ERROR',
+        message: `Failed to parse feature file ${file}: ${reason}`,
+        file,
+        reason,
+        ...(originalError !== undefined && { originalError }),
+    };
+}
+/**
+ * Create a ProcessMetadataValidationError
+ *
+ * @param file - Feature file path containing invalid process metadata
+ * @param reason - Description of validation failure
+ * @param validationErrors - Specific Zod validation errors
+ * @returns Structured ProcessMetadataValidationError
+ *
+ * @example
+ * ```typescript
+ * const error = createProcessMetadataValidationError(
+ *   '/path/to/test.feature',
+ *   'Schema validation failed',
+ *   ['status: Invalid enum value', 'phase: Expected number']
+ * );
+ * ```
+ */
+export function createProcessMetadataValidationError(file, reason, validationErrors) {
+    return {
+        type: 'PROCESS_METADATA_VALIDATION_ERROR',
+        message: `Process metadata validation failed in ${file}: ${reason}`,
+        file,
+        reason,
+        ...(validationErrors !== undefined && { validationErrors }),
+    };
+}
+/**
+ * Create a DeliverableValidationError
+ *
+ * @param file - Feature file path containing invalid deliverable
+ * @param reason - Description of validation failure
+ * @param deliverableName - Optional name of the invalid deliverable
+ * @param validationErrors - Specific Zod validation errors
+ * @returns Structured DeliverableValidationError
+ *
+ * @example
+ * ```typescript
+ * const error = createDeliverableValidationError(
+ *   '/path/to/test.feature',
+ *   'Invalid deliverable data',
+ *   'MyDeliverable',
+ *   ['name: Required', 'tests: Expected number']
+ * );
+ * ```
+ */
+export function createDeliverableValidationError(file, reason, deliverableName, validationErrors) {
+    const nameStr = deliverableName ? ` "${deliverableName}"` : '';
+    return {
+        type: 'DELIVERABLE_VALIDATION_ERROR',
+        message: `Deliverable${nameStr} validation failed in ${file}: ${reason}`,
+        file,
+        reason,
+        ...(deliverableName !== undefined && { deliverableName }),
+        ...(validationErrors !== undefined && { validationErrors }),
+    };
+}
+/**
+ * Create a GherkinPatternValidationError
+ *
+ * @param file - Feature file path containing invalid pattern
+ * @param patternName - Name of the pattern that failed validation
+ * @param reason - Description of validation failure
+ * @param validationErrors - Specific Zod validation errors
+ * @returns Structured GherkinPatternValidationError
+ *
+ * @example
+ * ```typescript
+ * const error = createGherkinPatternValidationError(
+ *   '/path/to/test.feature',
+ *   'MyPattern',
+ *   'Pattern schema validation failed',
+ *   ['id: Required', 'category: Invalid enum']
+ * );
+ * ```
+ */
+export function createGherkinPatternValidationError(file, patternName, reason, validationErrors) {
+    return {
+        type: 'GHERKIN_PATTERN_VALIDATION_ERROR',
+        message: `Gherkin pattern "${patternName}" validation failed in ${file}: ${reason}`,
+        file,
+        patternName,
+        reason,
+        ...(validationErrors !== undefined && { validationErrors }),
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/types/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,41 @@
+export { Result, type Ok, type Err } from './result.js';
+export type { PatternId, ModuleId, CategoryName, SourceFilePath, OutputFilePath, RegistryFilePath, DirectiveTag, } from './branded.js';
+export { asPatternId, asModuleId, asCategoryName, asSourceFilePath, asOutputFilePath, asRegistryFilePath, asDirectiveTag, } from './branded.js';
+export type { BaseDocError, DocError, ScanError, ExtractionError, GenerationError, BatchError, FileSystemError, FileParseError, DirectiveValidationError, PatternValidationError, RegistryValidationError, MarkdownGenerationError, FileWriteError, ConfigError, } from './errors.js';
+export { createFileSystemError, createFileParseError, createDirectiveValidationError, createPatternValidationError, createFeatureParseError, } from './errors.js';
+/**
+ * Position information in source file
+ * Schema: validation-schemas/doc-directive.ts
+ */
+export type { Position } from '../validation-schemas/doc-directive.js';
+/**
+ * Parsed @architect-* directive from JSDoc comment
+ * Schema: validation-schemas/doc-directive.ts
+ */
+export type { DocDirective } from '../validation-schemas/doc-directive.js';
+/**
+ * Information about exported symbols (discriminated union)
+ * Schema: validation-schemas/export-info.ts
+ */
+export type { ExportInfo } from '../validation-schemas/export-info.js';
+/**
+ * Source file information
+ * Schema: validation-schemas/extracted-pattern.ts
+ */
+export type { SourceInfo } from '../validation-schemas/extracted-pattern.js';
+/**
+ * Complete extracted pattern with code and metadata
+ * Schema: validation-schemas/extracted-pattern.ts
+ */
+export type { ExtractedPattern } from '../validation-schemas/extracted-pattern.js';
+/**
+ * Scanner configuration
+ * Schema: validation-schemas/config.ts
+ */
+export type { ScannerConfig } from '../validation-schemas/config.js';
+/**
+ * Generator configuration
+ * Schema: validation-schemas/config.ts
+ */
+export type { GeneratorConfig } from '../validation-schemas/config.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,KAAK,GAAG,EAAE,MAAM,aAAa,CAAC;AAGxD,YAAY,EACV,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,WAAW,EACX,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,GACf,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,eAAe,EACf,eAAe,EACf,UAAU,EACV,eAAe,EACf,cAAc,EACd,wBAAwB,EACxB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,cAAc,EACd,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,8BAA8B,EAC9B,4BAA4B,EAC5B,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAKrB;;;GAGG;AACH,YAAY,EAAE,QAAQ,EAAE,MAAM,wCAAwC,CAAC;AAEvE;;;GAGG;AACH,YAAY,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AAE3E;;;GAGG;AACH,YAAY,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAEvE;;;GAGG;AACH,YAAY,EAAE,UAAU,EAAE,MAAM,4CAA4C,CAAC;AAE7E;;;GAGG;AACH,YAAY,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAEnF;;;GAGG;AACH,YAAY,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE;;;GAGG;AACH,YAAY,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,5 @@
+// Export Result monad - value export also provides the type
+export { Result } from './result.js';
+export { asPatternId, asModuleId, asCategoryName, asSourceFilePath, asOutputFilePath, asRegistryFilePath, asDirectiveTag, } from './branded.js';
+export { createFileSystemError, createFileParseError, createDirectiveValidationError, createPatternValidationError, createFeatureParseError, } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,OAAO,EAAE,MAAM,EAAqB,MAAM,aAAa,CAAC;AAaxD,OAAO,EACL,WAAW,EACX,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,GACf,MAAM,cAAc,CAAC;AAoBtB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,8BAA8B,EAC9B,4BAA4B,EAC5B,uBAAuB,GACxB,MAAM,aAAa,CAAC"}

package/dist/types/result.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern ResultMonadTypes
+ * @architect-status completed
+ * @architect-implements ResultMonad
+ * @architect-product-area CoreTypes
+ *
+ * ## Result Monad - Type Definitions
+ *
+ * Explicit error handling via discriminated union.
+ * Functions return `Result.ok(value)` or `Result.err(error)` instead of throwing.
+ *
+ * **When to Use:** When a function can fail with a recoverable error — return Result instead of throwing exceptions.
+ */
+/**
+ * Success result containing a value
+ */
+export type Ok<T> = {
+    ok: true;
+    value: T;
+};
+/**
+ * Error result containing an error
+ */
+export type Err<E> = {
+    ok: false;
+    error: E;
+};
+/**
+ * Result type representing either success (Ok) or failure (Err)
+ *
+ * @architect-shape
+ * @architect-include core-types
+ * @typeParam T - The success value type
+ * @typeParam E - The error type (defaults to Error)
+ */
+export type Result<T, E = Error> = Ok<T> | Err<E>;
+/**
+ * Result utilities for creating and inspecting Result values
+ */
+export declare const Result: {
+    /**
+     * Create a success result
+     */
+    ok: <T>(value: T) => Result<T, never>;
+    /**
+     * Create an error result
+     */
+    err: <E = Error>(error: E) => Result<never, E>;
+    /**
+     * Type guard for success results
+     */
+    isOk: <T, E>(result: Result<T, E>) => result is Ok<T>;
+    /**
+     * Type guard for error results
+     */
+    isErr: <T, E>(result: Result<T, E>) => result is Err<E>;
+    /**
+     * Extract value or throw error.
+     * If the error is not an Error instance, it will be wrapped in one
+     * to ensure proper stack traces and error handling.
+     */
+    unwrap: <T, E>(result: Result<T, E>) => T;
+    /**
+     * Extract value or return default
+     */
+    unwrapOr: <T, E>(result: Result<T, E>, defaultValue: T) => T;
+    /**
+     * Transform success value
+     */
+    map: <T, U, E>(result: Result<T, E>, fn: (value: T) => U) => Result<U, E>;
+    /**
+     * Transform error value
+     */
+    mapErr: <T, E, F>(result: Result<T, E>, fn: (error: E) => F) => Result<T, F>;
+};
+//# sourceMappingURL=result.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/types/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;GAEG;AACH,MAAM,MAAM,EAAE,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE3C;;GAEG;AACH,MAAM,MAAM,GAAG,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,MAAM;IACjB;;OAEG;SACE,CAAC,SAAS,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC;IAEnC;;OAEG;UACG,CAAC,iBAAiB,CAAC,KAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IAE5C;;OAEG;WACI,CAAC,EAAE,CAAC,UAAU,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC;IAEnD;;OAEG;YACK,CAAC,EAAE,CAAC,UAAU,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC;IAErD;;;;OAIG;aACM,CAAC,EAAE,CAAC,UAAU,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAAC;IAgBvC;;OAEG;eACQ,CAAC,EAAE,CAAC,UAAU,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,gBAAgB,CAAC,KAAG,CAAC;IAG1D;;OAEG;UACG,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAOvE;;OAEG;aACM,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;CAM3E,CAAC"}

package/dist/types/result.js

@@ -0,0 +1,78 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern ResultMonadTypes
+ * @architect-status completed
+ * @architect-implements ResultMonad
+ * @architect-product-area CoreTypes
+ *
+ * ## Result Monad - Type Definitions
+ *
+ * Explicit error handling via discriminated union.
+ * Functions return `Result.ok(value)` or `Result.err(error)` instead of throwing.
+ *
+ * **When to Use:** When a function can fail with a recoverable error — return Result instead of throwing exceptions.
+ */
+/**
+ * Result utilities for creating and inspecting Result values
+ */
+export const Result = {
+    /**
+     * Create a success result
+     */
+    ok: (value) => ({ ok: true, value }),
+    /**
+     * Create an error result
+     */
+    err: (error) => ({ ok: false, error }),
+    /**
+     * Type guard for success results
+     */
+    isOk: (result) => result.ok,
+    /**
+     * Type guard for error results
+     */
+    isErr: (result) => !result.ok,
+    /**
+     * Extract value or throw error.
+     * If the error is not an Error instance, it will be wrapped in one
+     * to ensure proper stack traces and error handling.
+     */
+    unwrap: (result) => {
+        if (result.ok) {
+            return result.value;
+        }
+        // Ensure we always throw an Error instance for proper stack traces
+        if (result.error instanceof Error) {
+            throw result.error;
+        }
+        // Wrap non-Error objects to preserve information and provide stack trace
+        const errorMessage = typeof result.error === 'object' && result.error !== null
+            ? JSON.stringify(result.error)
+            : String(result.error);
+        throw new Error(errorMessage);
+    },
+    /**
+     * Extract value or return default
+     */
+    unwrapOr: (result, defaultValue) => result.ok ? result.value : defaultValue,
+    /**
+     * Transform success value
+     */
+    map: (result, fn) => {
+        if (result.ok) {
+            return { ok: true, value: fn(result.value) };
+        }
+        return result;
+    },
+    /**
+     * Transform error value
+     */
+    mapErr: (result, fn) => {
+        if (result.ok) {
+            return result;
+        }
+        return { ok: false, error: fn(result.error) };
+    },
+};
+//# sourceMappingURL=result.js.map

package/dist/types/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/types/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAsBH;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB;;OAEG;IACH,EAAE,EAAE,CAAI,KAAQ,EAAoB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAE5D;;OAEG;IACH,GAAG,EAAE,CAAY,KAAQ,EAAoB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAEtE;;OAEG;IACH,IAAI,EAAE,CAAO,MAAoB,EAAmB,EAAE,CAAC,MAAM,CAAC,EAAE;IAEhE;;OAEG;IACH,KAAK,EAAE,CAAO,MAAoB,EAAoB,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE;IAEnE;;;;OAIG;IACH,MAAM,EAAE,CAAO,MAAoB,EAAK,EAAE;QACxC,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,MAAM,CAAC,KAAK,CAAC;QACtB,CAAC;QACD,mEAAmE;QACnE,IAAI,MAAM,CAAC,KAAK,YAAY,KAAK,EAAE,CAAC;YAClC,MAAM,MAAM,CAAC,KAAK,CAAC;QACrB,CAAC;QACD,yEAAyE;QACzE,MAAM,YAAY,GAChB,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI;YACvD,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC;YAC9B,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,QAAQ,EAAE,CAAO,MAAoB,EAAE,YAAe,EAAK,EAAE,CAC3D,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY;IAEzC;;OAEG;IACH,GAAG,EAAE,CAAU,MAAoB,EAAE,EAAmB,EAAgB,EAAE;QACxE,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,MAAM,EAAE,CAAU,MAAoB,EAAE,EAAmB,EAAgB,EAAE;QAC3E,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAChD,CAAC;CACF,CAAC"}

package/dist/utils/collection-utils.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern CollectionUtilities
+ * @architect-status completed
+ * @architect-used-by SectionRenderer, DocExtractor
+ *
+ * ## CollectionUtilities - Array and Map Operations
+ *
+ * Provides shared utilities for working with arrays and collections,
+ * such as grouping items by a key function.
+ *
+ * ### When to Use
+ *
+ * - Use `groupBy()` when categorizing patterns by category, status, or other key
+ * - Use when aggregating items for section rendering (e.g., patterns by domain)
+ */
+/**
+ * Group items by a key function
+ *
+ * Creates a Map where each key maps to an array of items that share that key.
+ * This is a generic utility that replaces duplicate groupByX implementations.
+ *
+ * @typeParam T - Type of items in the collection
+ * @typeParam K - Type of the grouping key (must be usable as Map key)
+ * @param items - Array of items to group
+ * @param keyFn - Function to extract the grouping key from each item
+ * @returns Map from keys to arrays of items
+ *
+ * @example
+ * ```typescript
+ * interface Pattern { name: string; category: string; status?: string; }
+ *
+ * const patterns: Pattern[] = [
+ *   { name: 'Auth', category: 'core' },
+ *   { name: 'Logger', category: 'core' },
+ *   { name: 'Store', category: 'infra' }
+ * ];
+ *
+ * // Group by category
+ * const byCategory = groupBy(patterns, p => p.category);
+ * // Map { 'core' => [Auth, Logger], 'infra' => [Store] }
+ *
+ * // Group by status with default
+ * const byStatus = groupBy(patterns, p => p.status ?? 'implemented');
+ * ```
+ */
+export declare function groupBy<T, K>(items: readonly T[], keyFn: (item: T) => K): Map<K, T[]>;
+//# sourceMappingURL=collection-utils.d.ts.map

package/dist/utils/collection-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-utils.d.ts","sourceRoot":"","sources":["../../src/utils/collection-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAWrF"}

package/dist/utils/collection-utils.js

@@ -0,0 +1,58 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern CollectionUtilities
+ * @architect-status completed
+ * @architect-used-by SectionRenderer, DocExtractor
+ *
+ * ## CollectionUtilities - Array and Map Operations
+ *
+ * Provides shared utilities for working with arrays and collections,
+ * such as grouping items by a key function.
+ *
+ * ### When to Use
+ *
+ * - Use `groupBy()` when categorizing patterns by category, status, or other key
+ * - Use when aggregating items for section rendering (e.g., patterns by domain)
+ */
+/**
+ * Group items by a key function
+ *
+ * Creates a Map where each key maps to an array of items that share that key.
+ * This is a generic utility that replaces duplicate groupByX implementations.
+ *
+ * @typeParam T - Type of items in the collection
+ * @typeParam K - Type of the grouping key (must be usable as Map key)
+ * @param items - Array of items to group
+ * @param keyFn - Function to extract the grouping key from each item
+ * @returns Map from keys to arrays of items
+ *
+ * @example
+ * ```typescript
+ * interface Pattern { name: string; category: string; status?: string; }
+ *
+ * const patterns: Pattern[] = [
+ *   { name: 'Auth', category: 'core' },
+ *   { name: 'Logger', category: 'core' },
+ *   { name: 'Store', category: 'infra' }
+ * ];
+ *
+ * // Group by category
+ * const byCategory = groupBy(patterns, p => p.category);
+ * // Map { 'core' => [Auth, Logger], 'infra' => [Store] }
+ *
+ * // Group by status with default
+ * const byStatus = groupBy(patterns, p => p.status ?? 'implemented');
+ * ```
+ */
+export function groupBy(items, keyFn) {
+    const groups = new Map();
+    for (const item of items) {
+        const key = keyFn(item);
+        const existing = groups.get(key) ?? [];
+        existing.push(item);
+        groups.set(key, existing);
+    }
+    return groups;
+}
+//# sourceMappingURL=collection-utils.js.map

package/dist/utils/collection-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-utils.js","sourceRoot":"","sources":["../../src/utils/collection-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,OAAO,CAAO,KAAmB,EAAE,KAAqB;IACtE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IAEjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACvC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/id-utils.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @architect
+ * @architect-core
+ * @architect-pattern PatternIdGenerator
+ * @architect-status completed
+ * @architect-used-by DocExtractor, GherkinExtractor
+ *
+ * ## Pattern ID Generator - Deterministic ID Generation
+ *
+ * Generates unique, deterministic pattern IDs based on file path and line number.
+ * Uses MD5 hashing to produce stable 8-character identifiers.
+ *
+ * ### When to Use
+ *
+ * - When extracting patterns from TypeScript or Gherkin files
+ * - When needing stable IDs that survive re-extraction
+ * - When correlating patterns across multiple extraction runs
+ *
+ * ### Key Concepts
+ *
+ * - **Deterministic**: Same file + line always produces same ID
+ * - **Collision-resistant**: MD5 hash provides adequate uniqueness for pattern counts
+ * - **Human-friendly prefix**: `pattern-` prefix aids debugging and identification
+ */
+/**
+ * Generate a deterministic pattern ID from file path and line number
+ *
+ * Creates a unique identifier based on the combination of file path and
+ * starting line number. The same inputs will always produce the same output,
+ * making pattern IDs stable across multiple extraction runs.
+ *
+ * @param filePath - Relative file path (e.g., 'src/utils.ts')
+ * @param line - Line number where the pattern starts
+ * @returns Pattern ID in format 'pattern-{8-char-hash}'
+ *
+ * @example
+ * ```typescript
+ * const id1 = generatePatternId('src/utils.ts', 42);
+ * const id2 = generatePatternId('src/utils.ts', 42);
+ *
+ * console.log(id1 === id2); // true (deterministic)
+ * console.log(id1); // 'pattern-a1b2c3d4'
+ * ```
+ */
+export declare function generatePatternId(filePath: string, line: number): string;
+//# sourceMappingURL=id-utils.d.ts.map

package/dist/utils/id-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-utils.d.ts","sourceRoot":"","sources":["../../src/utils/id-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIxE"}