legal-markdown-js 2.4.0 → 2.5.0

package/README.md

@@ -60,16 +60,29 @@ legal-md document.md --html --css styles.css
 ### Programmatic Usage
 
 ```typescript
-import { processLegalMarkdown } from 'legal-markdown-js';
+import {
+  processLegalMarkdown,
+  processLegalMarkdownAsync,
+} from 'legal-markdown-js';
 
+// Synchronous processing (legacy)
 const result = processLegalMarkdown(content, {
   basePath: './documents',
   exportMetadata: true,
   exportFormat: 'json',
 });
 
-console.log(result.content);
-console.log(result.metadata);
+// Asynchronous processing with modern pipeline (recommended)
+const asyncResult = await processLegalMarkdownAsync(content, {
+  basePath: './documents',
+  exportMetadata: true,
+  exportFormat: 'json',
+  enableFieldTracking: true,
+});
+
+console.log(asyncResult.content);
+console.log(asyncResult.metadata);
+console.log(asyncResult.fieldReport); // Enhanced field tracking
 ```
 
 ## Key Features
@@ -94,13 +107,58 @@ Additional features available only in the Node.js version:
 
 - **Mixins System**: Template substitution and helpers with `{{variable}}`
   syntax
+- **AST-Based Processing**: Modern AST-based mixin processing to prevent text
+  contamination (v2.4.0+)
+- **Pipeline Architecture**: Configurable step-based processing pipeline with
+  dependency management and performance monitoring (v2.4.0+)
 - **PDF Generation**: Professional PDF output with styling and field
   highlighting
 - **HTML Generation**: Custom HTML output with CSS support
-- **Template Loops**: Array iteration with `[#items]...[/items]` syntax
+- **Template Loops**: Array iteration with `{{#items}}...{{/items}}` syntax
 - **Helper Functions**: Date, number, and string formatting helpers
 - **Force Commands**: Document-driven configuration with embedded CLI options
 - **Batch Processing**: Multi-file processing with concurrency control
+- **Field Tracking**: Enhanced field tracking with proper categorization for
+  document review
+
+## Architecture & Performance
+
+### Modern Pipeline System (v2.4.0+)
+
+Legal Markdown JS features a completely rewritten processing pipeline that
+provides:
+
+- **Step-Based Architecture**: Configurable processing steps with dependency
+  management
+- **AST-Based Processing**: Modern AST parsing for mixin processing to prevent
+  text contamination
+- **Performance Monitoring**: Built-in step profiling and performance metrics
+- **Error Recovery**: Graceful fallback to legacy processing when needed
+- **Field Tracking**: Enhanced field tracking with proper status categorization
+
+#### Processing Order
+
+The new pipeline ensures correct processing order to prevent conflicts:
+
+1. **YAML Front Matter** - Parse document metadata
+2. **Import Processing** - Handle file imports and inclusions
+3. **Optional Clauses** - Process conditional text blocks
+4. **Cross-References** - Resolve internal document references
+5. **Template Loops** - Expand array iterations first
+6. **AST Mixin Processing** - Process variables and helpers (avoids loop
+   conflicts)
+7. **Header Processing** - Apply numbering and formatting
+8. **Field Tracking** - Apply highlighting and generate reports
+
+#### API Usage
+
+```typescript
+// Use the modern async API for best performance
+const result = await processLegalMarkdownAsync(content, options);
+
+// Automatic fallback to legacy processing if needed
+// No code changes required for existing applications
+```
 
 ## Documentation
 

package/dist/core/index.d.ts

@@ -14,6 +14,8 @@
  * - Mixin system for reusable content
  * - Date processing utilities
  * - Metadata export capabilities
+ * - Base processor interfaces for pipeline management
+ * - Core field tracking infrastructure
  *
  * @example
  * ```typescript
@@ -21,12 +23,21 @@
  *   parseYamlFrontMatter,
  *   processHeaders,
  *   processOptionalClauses,
- *   processCrossReferences
+ *   processCrossReferences,
+ *   BaseProcessor,
+ *   FieldState
  * } from './core';
  *
  * // Use core processors in a custom pipeline
  * const { content, metadata } = parseYamlFrontMatter(rawContent);
  * const processed = processHeaders(content, metadata);
+ *
+ * // Implement a custom processor
+ * class MyProcessor implements BaseProcessor {
+ *   name = 'my-processor';
+ *   isEnabled(options) { return true; }
+ *   process(content, metadata, options) { return content; }
+ * }
  * ```
  */
 export * from './parsers/yaml-parser';
@@ -34,7 +45,9 @@ export * from './processors/header-processor';
 export * from './processors/clause-processor';
 export * from './processors/reference-processor';
 export * from './processors/import-processor';
-export * from './processors/mixin-processor';
+export * from '../extensions/ast-mixin-processor';
 export * from './processors/date-processor';
 export * from './exporters/metadata-exporter';
+export * from './processors/base-processor';
+export * from './tracking/field-state';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAGH,cAAc,uBAAuB,CAAC;AAGtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAG5C,cAAc,+BAA+B,CAAC;AAG9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC"}

package/dist/core/index.js

@@ -15,6 +15,8 @@
  * - Mixin system for reusable content
  * - Date processing utilities
  * - Metadata export capabilities
+ * - Base processor interfaces for pipeline management
+ * - Core field tracking infrastructure
  *
  * @example
  * ```typescript
@@ -22,12 +24,21 @@
  *   parseYamlFrontMatter,
  *   processHeaders,
  *   processOptionalClauses,
- *   processCrossReferences
+ *   processCrossReferences,
+ *   BaseProcessor,
+ *   FieldState
  * } from './core';
  *
  * // Use core processors in a custom pipeline
  * const { content, metadata } = parseYamlFrontMatter(rawContent);
  * const processed = processHeaders(content, metadata);
+ *
+ * // Implement a custom processor
+ * class MyProcessor implements BaseProcessor {
+ *   name = 'my-processor';
+ *   isEnabled(options) { return true; }
+ *   process(content, metadata, options) { return content; }
+ * }
  * ```
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -45,12 +56,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// Core parsers
 __exportStar(require("./parsers/yaml-parser"), exports);
+// Core processors
 __exportStar(require("./processors/header-processor"), exports);
 __exportStar(require("./processors/clause-processor"), exports);
 __exportStar(require("./processors/reference-processor"), exports);
 __exportStar(require("./processors/import-processor"), exports);
-__exportStar(require("./processors/mixin-processor"), exports);
+__exportStar(require("../extensions/ast-mixin-processor"), exports);
 __exportStar(require("./processors/date-processor"), exports);
+// Core exporters
 __exportStar(require("./exporters/metadata-exporter"), exports);
+// Core infrastructure for pipeline management
+__exportStar(require("./processors/base-processor"), exports);
+__exportStar(require("./tracking/field-state"), exports);
 //# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;;;;;;;;;;;;;;;AAEH,wDAAsC;AACtC,gEAA8C;AAC9C,gEAA8C;AAC9C,mEAAiD;AACjD,gEAA8C;AAC9C,+DAA6C;AAC7C,8DAA4C;AAC5C,gEAA8C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;;;;;;;;;;;;;;;;AAEH,eAAe;AACf,wDAAsC;AAEtC,kBAAkB;AAClB,gEAA8C;AAC9C,gEAA8C;AAC9C,mEAAiD;AACjD,gEAA8C;AAC9C,oEAAkD;AAClD,8DAA4C;AAE5C,iBAAiB;AACjB,gEAA8C;AAE9C,8CAA8C;AAC9C,8DAA4C;AAC5C,yDAAuC"}

package/dist/core/processors/base-processor.d.ts

@@ -0,0 +1,168 @@
+/**
+ * @fileoverview Base Processor Interface for Legal Markdown Processing Pipeline
+ *
+ * This module defines the fundamental interface that all processors in the Legal Markdown
+ * pipeline must implement. It provides a standardized contract for processing steps,
+ * enabling the pipeline manager to orchestrate document processing in a consistent manner.
+ *
+ * Features:
+ * - Standardized processor interface
+ * - Enable/disable logic per processor
+ * - Consistent processing contract
+ * - Pipeline orchestration support
+ * - Backward compatibility with existing processors
+ *
+ * @example
+ * ```typescript
+ * import { BaseProcessor } from './base-processor';
+ *
+ * class MyCustomProcessor implements BaseProcessor {
+ *   name = 'my-custom-processor';
+ *
+ *   isEnabled(options: LegalMarkdownOptions): boolean {
+ *     return !options.noCustomProcessing;
+ *   }
+ *
+ *   process(content: string, metadata: Record<string, any>, options: any): string {
+ *     // Custom processing logic
+ *     return processedContent;
+ *   }
+ * }
+ * ```
+ */
+import { LegalMarkdownOptions } from '@types';
+/**
+ * Base interface that all processors in the Legal Markdown pipeline must implement
+ *
+ * This interface ensures consistency across all processing steps and enables
+ * the pipeline manager to coordinate document processing effectively.
+ *
+ * @interface BaseProcessor
+ * @example
+ * ```typescript
+ * class MixinProcessor implements BaseProcessor {
+ *   name = 'mixins';
+ *
+ *   isEnabled(options: LegalMarkdownOptions): boolean {
+ *     return !options.noMixins;
+ *   }
+ *
+ *   process(content: string, metadata: Record<string, any>, options: LegalMarkdownOptions): string {
+ *     return processMixins(content, metadata, options);
+ *   }
+ * }
+ * ```
+ */
+export interface BaseProcessor {
+    /** Unique name identifier for this processor */
+    readonly name: string;
+    /**
+     * Determines whether this processor should be executed based on the provided options
+     *
+     * @param options - The Legal Markdown processing options
+     * @returns True if the processor should be executed, false otherwise
+     * @example
+     * ```typescript
+     * // Processor that runs unless explicitly disabled
+     * isEnabled(options: LegalMarkdownOptions): boolean {
+     *   return !options.noMixins;
+     * }
+     *
+     * // Processor that only runs when specific option is enabled
+     * isEnabled(options: LegalMarkdownOptions): boolean {
+     *   return options.enableAdvancedFeatures;
+     * }
+     * ```
+     */
+    isEnabled(options: LegalMarkdownOptions): boolean;
+    /**
+     * Processes the document content according to this processor's specific logic
+     *
+     * @param content - The document content to process
+     * @param metadata - The document metadata (YAML front matter, etc.)
+     * @param options - The Legal Markdown processing options
+     * @returns The processed content
+     * @throws {Error} When processing fails critically
+     * @example
+     * ```typescript
+     * process(content: string, metadata: Record<string, any>, options: LegalMarkdownOptions): string {
+     *   if (!this.isEnabled(options)) {
+     *     return content; // Return unchanged if disabled
+     *   }
+     *
+     *   try {
+     *     return this.performProcessing(content, metadata, options);
+     *   } catch (error) {
+     *     console.warn(`Processor ${this.name} failed, returning original content:`, error);
+     *     return content; // Graceful fallback
+     *   }
+     * }
+     * ```
+     */
+    process(content: string, metadata: Record<string, any>, options: LegalMarkdownOptions): string;
+}
+/**
+ * Abstract base class that provides common functionality for processors
+ *
+ * This class implements common patterns and provides utility methods that
+ * most processors will need, reducing boilerplate code.
+ *
+ * @abstract
+ * @class AbstractProcessor
+ * @implements {BaseProcessor}
+ * @example
+ * ```typescript
+ * class MyProcessor extends AbstractProcessor {
+ *   name = 'my-processor';
+ *
+ *   isEnabled(options: LegalMarkdownOptions): boolean {
+ *     return !options.noMyProcessor;
+ *   }
+ *
+ *   protected performProcessing(content: string, metadata: Record<string, any>, options: LegalMarkdownOptions): string {
+ *     // Actual processing logic here
+ *     return processedContent;
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class AbstractProcessor implements BaseProcessor {
+    abstract readonly name: string;
+    abstract isEnabled(options: LegalMarkdownOptions): boolean;
+    /**
+     * Template method that handles common processing patterns
+     *
+     * This method provides error handling, logging, and other common functionality,
+     * delegating the actual processing to the performProcessing method.
+     */
+    process(content: string, metadata: Record<string, any>, options: LegalMarkdownOptions): string;
+    /**
+     * Abstract method where subclasses implement their specific processing logic
+     *
+     * @param content - The document content to process
+     * @param metadata - The document metadata
+     * @param options - The processing options
+     * @returns The processed content
+     * @protected
+     */
+    protected abstract performProcessing(content: string, metadata: Record<string, any>, options: LegalMarkdownOptions): string;
+    /**
+     * Utility method to check if content has already been processed by another step
+     *
+     * This helps prevent double-processing and conflicts between processors.
+     *
+     * @param content - The content to check
+     * @returns True if content appears to have been processed (contains spans, etc.)
+     * @protected
+     */
+    protected hasBeenProcessed(content: string): boolean;
+    /**
+     * Utility method to log processing information in debug mode
+     *
+     * @param message - The message to log
+     * @param data - Optional data to include in the log
+     * @protected
+     */
+    protected debug(message: string, data?: any): void;
+}
+//# sourceMappingURL=base-processor.d.ts.map

package/dist/core/processors/base-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-processor.d.ts","sourceRoot":"","sources":["../../../src/core/processors/base-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC;IAElD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAAC;CAChG;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8BAAsB,iBAAkB,YAAW,aAAa;IAC9D,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO;IAE1D;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,oBAAoB,GAAG,MAAM;IAa9F;;;;;;;;OAQG;IACH,SAAS,CAAC,QAAQ,CAAC,iBAAiB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,OAAO,EAAE,oBAAoB,GAC5B,MAAM;IAET;;;;;;;;OAQG;IACH,SAAS,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAQpD;;;;;;OAMG;IACH,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;CAKnD"}

package/dist/core/processors/base-processor.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * @fileoverview Base Processor Interface for Legal Markdown Processing Pipeline
+ *
+ * This module defines the fundamental interface that all processors in the Legal Markdown
+ * pipeline must implement. It provides a standardized contract for processing steps,
+ * enabling the pipeline manager to orchestrate document processing in a consistent manner.
+ *
+ * Features:
+ * - Standardized processor interface
+ * - Enable/disable logic per processor
+ * - Consistent processing contract
+ * - Pipeline orchestration support
+ * - Backward compatibility with existing processors
+ *
+ * @example
+ * ```typescript
+ * import { BaseProcessor } from './base-processor';
+ *
+ * class MyCustomProcessor implements BaseProcessor {
+ *   name = 'my-custom-processor';
+ *
+ *   isEnabled(options: LegalMarkdownOptions): boolean {
+ *     return !options.noCustomProcessing;
+ *   }
+ *
+ *   process(content: string, metadata: Record<string, any>, options: any): string {
+ *     // Custom processing logic
+ *     return processedContent;
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractProcessor = void 0;
+/**
+ * Abstract base class that provides common functionality for processors
+ *
+ * This class implements common patterns and provides utility methods that
+ * most processors will need, reducing boilerplate code.
+ *
+ * @abstract
+ * @class AbstractProcessor
+ * @implements {BaseProcessor}
+ * @example
+ * ```typescript
+ * class MyProcessor extends AbstractProcessor {
+ *   name = 'my-processor';
+ *
+ *   isEnabled(options: LegalMarkdownOptions): boolean {
+ *     return !options.noMyProcessor;
+ *   }
+ *
+ *   protected performProcessing(content: string, metadata: Record<string, any>, options: LegalMarkdownOptions): string {
+ *     // Actual processing logic here
+ *     return processedContent;
+ *   }
+ * }
+ * ```
+ */
+class AbstractProcessor {
+    /**
+     * Template method that handles common processing patterns
+     *
+     * This method provides error handling, logging, and other common functionality,
+     * delegating the actual processing to the performProcessing method.
+     */
+    process(content, metadata, options) {
+        if (!this.isEnabled(options)) {
+            return content;
+        }
+        try {
+            return this.performProcessing(content, metadata, options);
+        }
+        catch (error) {
+            console.warn(`Processor '${this.name}' failed, returning original content:`, error);
+            return content;
+        }
+    }
+    /**
+     * Utility method to check if content has already been processed by another step
+     *
+     * This helps prevent double-processing and conflicts between processors.
+     *
+     * @param content - The content to check
+     * @returns True if content appears to have been processed (contains spans, etc.)
+     * @protected
+     */
+    hasBeenProcessed(content) {
+        return (content.includes('class="imported-value"') ||
+            content.includes('class="missing-value"') ||
+            content.includes('class="highlight"'));
+    }
+    /**
+     * Utility method to log processing information in debug mode
+     *
+     * @param message - The message to log
+     * @param data - Optional data to include in the log
+     * @protected
+     */
+    debug(message, data) {
+        if (process.env.NODE_ENV === 'development') {
+            console.log(`[${this.name.toUpperCase()}] ${message}`, data || '');
+        }
+    }
+}
+exports.AbstractProcessor = AbstractProcessor;
+//# sourceMappingURL=base-processor.js.map

package/dist/core/processors/base-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-processor.js","sourceRoot":"","sources":["../../../src/core/processors/base-processor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;AA6EH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAsB,iBAAiB;IAIrC;;;;;OAKG;IACH,OAAO,CAAC,OAAe,EAAE,QAA6B,EAAE,OAA6B;QACnF,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7B,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,IAAI,uCAAuC,EAAE,KAAK,CAAC,CAAC;YACpF,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAiBD;;;;;;;;OAQG;IACO,gBAAgB,CAAC,OAAe;QACxC,OAAO,CACL,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAC;YAC1C,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAC;YACzC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CACtC,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACO,KAAK,CAAC,OAAe,EAAE,IAAU;QACzC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;YAC3C,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,OAAO,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;CACF;AAnED,8CAmEC"}