legal-markdown-js 0.1.0

package/dist/errors/index.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * @fileoverview Custom Error Classes for Legal Markdown Processing
+ *
+ * This module provides a comprehensive set of custom error classes for the Legal Markdown
+ * processing system. All errors inherit from a base LegalMarkdownError class that provides
+ * structured error handling with error codes and contextual information.
+ *
+ * Features:
+ * - Base LegalMarkdownError class with error codes and context
+ * - Specialized error classes for different failure scenarios
+ * - Structured error information for debugging and user feedback
+ * - Proper stack trace preservation
+ * - Contextual data attachment for detailed error reporting
+ * - Type-safe error handling throughout the system
+ *
+ * @example
+ * ```typescript
+ * import { YamlParsingError, FileNotFoundError, ValidationError } from './errors';
+ *
+ * // YAML parsing error
+ * throw new YamlParsingError('Invalid YAML syntax', { line: 5, column: 12 });
+ *
+ * // File not found error
+ * throw new FileNotFoundError('./missing-file.md', { operation: 'import' });
+ *
+ * // Validation error
+ * throw new ValidationError('Field is required', 'client.name', { value: '' });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProcessingError = exports.ValidationError = exports.MetadataExportError = exports.ImportProcessingError = exports.FileNotFoundError = exports.YamlParsingError = exports.LegalMarkdownError = void 0;
+/**
+ * Base error class for all Legal Markdown processing errors
+ *
+ * Provides structured error handling with error codes and contextual information.
+ * All other error types in the system inherit from this base class.
+ *
+ * @class LegalMarkdownError
+ * @extends {Error}
+ * @example
+ * ```typescript
+ * import { LegalMarkdownError } from './errors';
+ *
+ * // Create a custom error with context
+ * const error = new LegalMarkdownError(
+ *   'Processing failed',
+ *   'PROCESSING_ERROR',
+ *   { file: 'contract.md', step: 'field-resolution' }
+ * );
+ *
+ * console.log(error.code); // 'PROCESSING_ERROR'
+ * console.log(error.context); // { file: 'contract.md', step: 'field-resolution' }
+ * ```
+ */
+class LegalMarkdownError extends Error {
+    /**
+     * Creates a new LegalMarkdownError instance
+     *
+     * @param {string} message - Human-readable error message
+     * @param {string} code - Error code for programmatic handling
+     * @param {Record<string, unknown>} [context] - Optional contextual data
+     * @example
+     * ```typescript
+     * const error = new LegalMarkdownError(
+     *   'Field resolution failed',
+     *   'FIELD_RESOLUTION_ERROR',
+     *   { fieldName: 'client.name', value: undefined }
+     * );
+     * ```
+     */
+    constructor(message, code, context) {
+        super(message);
+        this.name = 'LegalMarkdownError';
+        this.code = code;
+        this.context = context;
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, LegalMarkdownError);
+        }
+    }
+}
+exports.LegalMarkdownError = LegalMarkdownError;
+/**
+ * Error thrown when YAML frontmatter parsing fails
+ *
+ * @class YamlParsingError
+ * @extends {LegalMarkdownError}
+ * @example
+ * ```typescript
+ * import { YamlParsingError } from './errors';
+ *
+ * // YAML parsing error with context
+ * throw new YamlParsingError('Invalid YAML syntax at line 5', {
+ *   line: 5,
+ *   column: 12,
+ *   yamlContent: 'title: "Unterminated string...'
+ * });
+ * ```
+ */
+class YamlParsingError extends LegalMarkdownError {
+    /**
+     * Creates a new YamlParsingError instance
+     *
+     * @param {string} message - Human-readable error message describing the YAML parsing issue
+     * @param {Record<string, unknown>} [context] - Optional contextual data like line number, column, etc.
+     */
+    constructor(message, context) {
+        super(message, 'YAML_PARSING_ERROR', context);
+        this.name = 'YamlParsingError';
+    }
+}
+exports.YamlParsingError = YamlParsingError;
+/**
+ * Error thrown when a required file cannot be found
+ *
+ * @class FileNotFoundError
+ * @extends {LegalMarkdownError}
+ * @example
+ * ```typescript
+ * import { FileNotFoundError } from './errors';
+ *
+ * // File not found during import
+ * throw new FileNotFoundError('./imports/header.md', {
+ *   operation: 'import',
+ *   basePath: './documents'
+ * });
+ * ```
+ */
+class FileNotFoundError extends LegalMarkdownError {
+    /**
+     * Creates a new FileNotFoundError instance
+     *
+     * @param {string} filePath - The path of the file that could not be found
+     * @param {Record<string, unknown>} [context] - Optional contextual data like operation type, base path, etc.
+     */
+    constructor(filePath, context) {
+        super(`File not found: ${filePath}`, 'FILE_NOT_FOUND', { filePath, ...context });
+        this.name = 'FileNotFoundError';
+    }
+}
+exports.FileNotFoundError = FileNotFoundError;
+/**
+ * Error thrown when import processing fails
+ *
+ * @class ImportProcessingError
+ * @extends {LegalMarkdownError}
+ * @example
+ * ```typescript
+ * import { ImportProcessingError } from './errors';
+ *
+ * // Import processing error
+ * throw new ImportProcessingError(
+ *   'Circular import detected',
+ *   './imports/header.md',
+ *   { importChain: ['main.md', 'header.md', 'header.md'] }
+ * );
+ * ```
+ */
+class ImportProcessingError extends LegalMarkdownError {
+    /**
+     * Creates a new ImportProcessingError instance
+     *
+     * @param {string} message - Human-readable error message describing the import processing issue
+     * @param {string} [filePath] - Optional file path where the import error occurred
+     * @param {Record<string, unknown>} [context] - Optional contextual data like import chain, operation details, etc.
+     */
+    constructor(message, filePath, context) {
+        super(message, 'IMPORT_PROCESSING_ERROR', { filePath, ...context });
+        this.name = 'ImportProcessingError';
+    }
+}
+exports.ImportProcessingError = ImportProcessingError;
+/**
+ * Error thrown when metadata export operations fail
+ *
+ * @class MetadataExportError
+ * @extends {LegalMarkdownError}
+ * @example
+ * ```typescript
+ * import { MetadataExportError } from './errors';
+ *
+ * // Metadata export error
+ * throw new MetadataExportError(
+ *   'Failed to write metadata file',
+ *   './output/metadata.yaml',
+ *   { format: 'yaml', permissions: 'denied' }
+ * );
+ * ```
+ */
+class MetadataExportError extends LegalMarkdownError {
+    /**
+     * Creates a new MetadataExportError instance
+     *
+     * @param {string} message - Human-readable error message describing the metadata export issue
+     * @param {string} [exportPath] - Optional path where the export was attempted
+     * @param {Record<string, unknown>} [context] - Optional contextual data like export format, permissions, etc.
+     */
+    constructor(message, exportPath, context) {
+        super(message, 'METADATA_EXPORT_ERROR', { exportPath, ...context });
+        this.name = 'MetadataExportError';
+    }
+}
+exports.MetadataExportError = MetadataExportError;
+/**
+ * Error thrown when document validation fails
+ *
+ * @class ValidationError
+ * @extends {LegalMarkdownError}
+ * @example
+ * ```typescript
+ * import { ValidationError } from './errors';
+ *
+ * // Validation error for a specific field
+ * throw new ValidationError(
+ *   'Field value is required',
+ *   'client.name',
+ *   { value: '', required: true, type: 'string' }
+ * );
+ * ```
+ */
+class ValidationError extends LegalMarkdownError {
+    /**
+     * Creates a new ValidationError instance
+     *
+     * @param {string} message - Human-readable error message describing the validation issue
+     * @param {string} [field] - Optional field name that failed validation
+     * @param {Record<string, unknown>} [context] - Optional contextual data like expected value, validation rules, etc.
+     */
+    constructor(message, field, context) {
+        super(message, 'VALIDATION_ERROR', { field, ...context });
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Error thrown when general processing operations fail
+ *
+ * @class ProcessingError
+ * @extends {LegalMarkdownError}
+ * @example
+ * ```typescript
+ * import { ProcessingError } from './errors';
+ *
+ * // Processing error with processor information
+ * throw new ProcessingError(
+ *   'Field resolution failed',
+ *   'field-processor',
+ *   { fieldCount: 25, failedFields: ['client.name', 'date'] }
+ * );
+ * ```
+ */
+class ProcessingError extends LegalMarkdownError {
+    /**
+     * Creates a new ProcessingError instance
+     *
+     * @param {string} message - Human-readable error message describing the processing issue
+     * @param {string} [processor] - Optional name of the processor that failed
+     * @param {Record<string, unknown>} [context] - Optional contextual data like processing stage, affected items, etc.
+     */
+    constructor(message, processor, context) {
+        super(message, 'PROCESSING_ERROR', { processor, ...context });
+        this.name = 'ProcessingError';
+    }
+}
+exports.ProcessingError = ProcessingError;
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAM3C;;;;;;;;;;;;;;OAcG;IACH,YAAY,OAAe,EAAE,IAAY,EAAE,OAAiC;QAC1E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAEvB,qFAAqF;QACrF,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;CACF;AAhCD,gDAgCC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,gBAAiB,SAAQ,kBAAkB;IACtD;;;;;OAKG;IACH,YAAY,OAAe,EAAE,OAAiC;QAC5D,KAAK,CAAC,OAAO,EAAE,oBAAoB,EAAE,OAAO,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAXD,4CAWC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAa,iBAAkB,SAAQ,kBAAkB;IACvD;;;;;OAKG;IACH,YAAY,QAAgB,EAAE,OAAiC;QAC7D,KAAK,CAAC,mBAAmB,QAAQ,EAAE,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;QACjF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAXD,8CAWC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,qBAAsB,SAAQ,kBAAkB;IAC3D;;;;;;OAMG;IACH,YAAY,OAAe,EAAE,QAAiB,EAAE,OAAiC;QAC/E,KAAK,CAAC,OAAO,EAAE,yBAAyB,EAAE,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAZD,sDAYC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,mBAAoB,SAAQ,kBAAkB;IACzD;;;;;;OAMG;IACH,YAAY,OAAe,EAAE,UAAmB,EAAE,OAAiC;QACjF,KAAK,CAAC,OAAO,EAAE,uBAAuB,EAAE,EAAE,UAAU,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAZD,kDAYC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,eAAgB,SAAQ,kBAAkB;IACrD;;;;;;OAMG;IACH,YAAY,OAAe,EAAE,KAAc,EAAE,OAAiC;QAC5E,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAZD,0CAYC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,eAAgB,SAAQ,kBAAkB;IACrD;;;;;;OAMG;IACH,YAAY,OAAe,EAAE,SAAkB,EAAE,OAAiC;QAChF,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAZD,0CAYC"}

package/dist/extensions/batch-processor.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview Batch Processing Module for Legal Markdown Documents
+ *
+ * This module provides functionality for processing multiple Legal Markdown files
+ * in batch operations. It supports recursive directory processing, concurrent
+ * file operations, progress tracking, and error handling.
+ *
+ * Features:
+ * - Batch processing of multiple Legal Markdown files
+ * - Recursive directory traversal with pattern matching
+ * - Concurrent processing with configurable concurrency limits
+ * - Progress tracking and error reporting callbacks
+ * - Directory structure preservation in output
+ * - File extension filtering and exclusion patterns
+ * - Metadata export support for batch operations
+ * - Statistics and performance tracking
+ *
+ * @example
+ * ```typescript
+ * import { processBatch } from './batch-processor';
+ *
+ * // Basic batch processing
+ * const result = await processBatch({
+ *   inputDir: './legal-docs',
+ *   outputDir: './output',
+ *   extensions: ['.md'],
+ *   recursive: true
+ * });
+ *
+ * // Advanced batch processing with callbacks
+ * const result = await processBatch({
+ *   inputDir: './contracts',
+ *   outputDir: './processed-contracts',
+ *   extensions: ['.md', '.txt'],
+ *   recursive: true,
+ *   concurrency: 3,
+ *   exclude: ['temp', 'backup'],
+ *   onProgress: (processed, total, currentFile) => {
+ *     console.log(`Progress: ${processed}/${total} - ${currentFile}`);
+ *   },
+ *   onError: (file, error) => {
+ *     console.error(`Error processing ${file}:`, error.message);
+ *   }
+ * });
+ * ```
+ */
+import { LegalMarkdownOptions } from '@types';
+/**
+ * Configuration options for batch processing operations
+ *
+ * Extends LegalMarkdownOptions to include batch-specific settings like
+ * directory paths, concurrency control, and progress callbacks.
+ *
+ * @interface BatchProcessingOptions
+ * @extends {LegalMarkdownOptions}
+ * @example
+ * ```typescript
+ * const options: BatchProcessingOptions = {
+ *   inputDir: './legal-documents',
+ *   outputDir: './processed-documents',
+ *   extensions: ['.md', '.txt'],
+ *   recursive: true,
+ *   preserveStructure: true,
+ *   exclude: ['temp', 'backup'],
+ *   concurrency: 5,
+ *   onProgress: (processed, total, currentFile) => {
+ *     console.log(`Processing: ${currentFile} (${processed}/${total})`);
+ *   }
+ * };
+ * ```
+ */
+export interface BatchProcessingOptions extends LegalMarkdownOptions {
+    /** Input directory containing files to process */
+    inputDir: string;
+    /** Output directory for processed files */
+    outputDir: string;
+    /** File extensions to process (defaults to ['.md', '.txt']) */
+    extensions?: string[];
+    /** Whether to process subdirectories recursively */
+    recursive?: boolean;
+    /** Whether to preserve directory structure in output */
+    preserveStructure?: boolean;
+    /** Pattern to exclude files/directories */
+    exclude?: string[];
+    /** Maximum number of concurrent file processing operations */
+    concurrency?: number;
+    /** Callback for progress updates during batch processing */
+    onProgress?: (processed: number, total: number, currentFile: string) => void;
+    /** Callback for handling errors during file processing */
+    onError?: (file: string, error: Error) => void;
+}
+/**
+ * Result of batch processing operation
+ *
+ * Contains statistics and details about the batch processing operation,
+ * including success/failure counts, file lists, and timing information.
+ *
+ * @interface BatchProcessingResult
+ * @example
+ * ```typescript
+ * const result = await processBatch(options);
+ *
+ * console.log(`Successfully processed: ${result.totalProcessed} files`);
+ * console.log(`Failed: ${result.totalErrors} files`);
+ * console.log(`Processing time: ${result.processingTime}ms`);
+ *
+ * // List failed files
+ * result.failedFiles.forEach(({ file, error }) => {
+ *   console.error(`Failed to process ${file}: ${error}`);
+ * });
+ * ```
+ */
+export interface BatchProcessingResult {
+    /** Total number of files successfully processed */
+    totalProcessed: number;
+    /** Number of files that failed processing */
+    totalErrors: number;
+    /** List of successfully processed file paths */
+    successfulFiles: string[];
+    /** List of failed files with error messages */
+    failedFiles: Array<{
+        file: string;
+        error: string;
+    }>;
+    /** Total processing time in milliseconds */
+    processingTime: number;
+}
+/**
+ * Processes multiple legal markdown files in batch
+ *
+ * This function performs batch processing of Legal Markdown files with support
+ * for recursive directory traversal, concurrent processing, and progress tracking.
+ * It automatically handles file discovery, directory creation, and error management.
+ *
+ * @async
+ * @function processBatch
+ * @param {BatchProcessingOptions} options - Configuration options for batch processing
+ * @returns {Promise<BatchProcessingResult>} A promise that resolves to the processing result
+ * @throws {Error} When input directory doesn't exist or other setup errors occur
+ * @example
+ * ```typescript
+ * import { processBatch } from './batch-processor';
+ *
+ * // Process all .md files in a directory
+ * const result = await processBatch({
+ *   inputDir: './legal-documents',
+ *   outputDir: './processed-documents',
+ *   extensions: ['.md'],
+ *   recursive: true,
+ *   preserveStructure: true,
+ *   concurrency: 3,
+ *   onProgress: (processed, total, currentFile) => {
+ *     console.log(`Progress: ${processed}/${total} - ${path.basename(currentFile)}`);
+ *   },
+ *   onError: (file, error) => {
+ *     console.error(`Error processing ${file}:`, error.message);
+ *   }
+ * });
+ *
+ * console.log(`Processed ${result.totalProcessed} files successfully`);
+ * console.log(`${result.totalErrors} files failed processing`);
+ * ```
+ */
+export declare function processBatch(options: BatchProcessingOptions): Promise<BatchProcessingResult>;
+/**
+ * Utility function to get processing statistics from batch processing results
+ *
+ * Calculates useful statistics about the batch processing operation including
+ * success rate, average processing time per file, and throughput metrics.
+ *
+ * @function getProcessingStats
+ * @param {BatchProcessingResult} result - The batch processing result to analyze
+ * @returns {Object} Object containing processing statistics
+ * @returns {number} returns.successRate - Success rate as a percentage (0-100)
+ * @returns {number} returns.averageTimePerFile - Average processing time per file in milliseconds
+ * @returns {number} returns.filesPerSecond - Processing throughput in files per second
+ * @example
+ * ```typescript
+ * import { processBatch, getProcessingStats } from './batch-processor';
+ *
+ * const result = await processBatch({
+ *   inputDir: './documents',
+ *   outputDir: './output'
+ * });
+ *
+ * const stats = getProcessingStats(result);
+ * console.log(`Success rate: ${stats.successRate.toFixed(2)}%`);
+ * console.log(`Average time per file: ${stats.averageTimePerFile.toFixed(2)}ms`);
+ * console.log(`Throughput: ${stats.filesPerSecond.toFixed(2)} files/second`);
+ * ```
+ */
+export declare function getProcessingStats(result: BatchProcessingResult): {
+    successRate: number;
+    averageTimePerFile: number;
+    filesPerSecond: number;
+};
+//# sourceMappingURL=batch-processor.d.ts.map

package/dist/extensions/batch-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-processor.d.ts","sourceRoot":"","sources":["../../src/extensions/batch-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAKH,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAQ9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IAClE,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IAEjB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAElB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,wDAAwD;IACxD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAE7E,0DAA0D;IAC1D,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IAEvB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IAEpB,gDAAgD;IAChD,eAAe,EAAE,MAAM,EAAE,CAAC;IAE1B,+CAA+C;IAC/C,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEpD,4CAA4C;IAC5C,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAsEhC;AA4ND;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,qBAAqB,GAAG;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;CACxB,CAYA"}