@wix/web5-core 1.56.0

package/dist/cjs/patternAnalyzer/patternWriter.js

@@ -0,0 +1,106 @@
+"use strict";
+
+exports.__esModule = true;
+exports.serializePatternNode = serializePatternNode;
+function serializeQuantifier(q) {
+  switch (q.type) {
+    case 'star':
+      return '*';
+    case 'plus':
+      return '+';
+    case 'optional':
+      return '?';
+    case 'exact':
+      return `[${q.min}]`;
+    case 'range':
+      {
+        const min = q.min ?? 0;
+        const max = q.max;
+        if (min === 0 && max !== undefined) {
+          return `[-${max}]`;
+        }
+        if (max === undefined) {
+          return `[${min}-]`;
+        }
+        return `[${min}-${max}]`;
+      }
+  }
+}
+function serializeAttr(attr) {
+  switch (attr.operator) {
+    case 'exists':
+      return `[${attr.key}]`;
+    case 'equals':
+      return `[${attr.key}="${attr.value}"]`;
+    case 'contains':
+      return `[${attr.key}*="${attr.value}"]`;
+    case 'startsWith':
+      return `[${attr.key}^="${attr.value}"]`;
+    case 'endsWith':
+      return `[${attr.key}$="${attr.value}"]`;
+  }
+}
+
+/**
+ * Serialize a PatternNode back to a pattern string.
+ * This is the inverse of tokenize() + parse().
+ * Used by mergeDetector to express merged/suggested patterns.
+ */
+function serializePatternNode(node) {
+  switch (node.kind) {
+    case 'element':
+      {
+        var _node$htmlCommentAttr, _node$linkAttrs, _node$imageAttrs;
+        let s = node.element;
+        if (node.element === 'html_comment' && (_node$htmlCommentAttr = node.htmlCommentAttrs) != null && _node$htmlCommentAttr.length) {
+          s += node.htmlCommentAttrs.map(serializeAttr).join('');
+        }
+        if (node.element === 'link' && (_node$linkAttrs = node.linkAttrs) != null && _node$linkAttrs.length) {
+          s += node.linkAttrs.map(serializeAttr).join('');
+        }
+        if (node.element === 'image' && (_node$imageAttrs = node.imageAttrs) != null && _node$imageAttrs.length) {
+          s += node.imageAttrs.map(serializeAttr).join('');
+        }
+        if (node.quantifier) {
+          s += serializeQuantifier(node.quantifier);
+        }
+        return s;
+      }
+    case 'sequence':
+      return node.children.map(serializePatternNode).join(' > ');
+    case 'alternation':
+      {
+        // No parens here — when an alternation is inside a group, the group adds parens.
+        // When used directly in a sequence, no parens are needed (alternation has lower
+        // precedence than sequence anyway, so `a | b > c` parses as `a | (b > c)`).
+        const inner = node.choices.map(serializePatternNode).join(' | ');
+        return node.quantifier ? `${inner}${serializeQuantifier(node.quantifier)}` : inner;
+      }
+    case 'group':
+      {
+        const inner = serializePatternNode(node.pattern);
+        // Groups always have parens — they exist precisely to group for quantifiers
+        const s = `(${inner})`;
+        return node.quantifier ? `${s}${serializeQuantifier(node.quantifier)}` : s;
+      }
+    case 'list':
+      {
+        let s = 'list';
+        if (node.itemCount !== undefined || node.itemStructure !== undefined) {
+          s += '{item';
+          if (node.itemCount) {
+            s += serializeQuantifier(node.itemCount);
+          }
+          if (node.itemStructure) {
+            s += ':' + serializePatternNode(node.itemStructure);
+          }
+          s += '}';
+        }
+        if (node.quantifier) {
+          s += serializeQuantifier(node.quantifier);
+        }
+        return s;
+      }
+  }
+}
+//# sourceMappingURL=patternWriter.js.map

package/dist/cjs/patternAnalyzer/patternWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["serializeQuantifier","q","type","min","max","undefined","serializeAttr","attr","operator","key","value","serializePatternNode","node","kind","_node$htmlCommentAttr","_node$linkAttrs","_node$imageAttrs","s","element","htmlCommentAttrs","length","map","join","linkAttrs","imageAttrs","quantifier","children","inner","choices","pattern","itemCount","itemStructure"],"sources":["../../../src/patternAnalyzer/patternWriter.ts"],"sourcesContent":["import type {\n  PatternNode,\n  Quantifier,\n  HtmlCommentAttribute,\n  LinkAttribute,\n  ImageAttribute,\n} from '../patternValidator/types';\n\nfunction serializeQuantifier(q: Quantifier): string {\n  switch (q.type) {\n    case 'star':\n      return '*';\n    case 'plus':\n      return '+';\n    case 'optional':\n      return '?';\n    case 'exact':\n      return `[${q.min}]`;\n    case 'range': {\n      const min = q.min ?? 0;\n      const max = q.max;\n      if (min === 0 && max !== undefined) {\n        return `[-${max}]`;\n      }\n      if (max === undefined) {\n        return `[${min}-]`;\n      }\n      return `[${min}-${max}]`;\n    }\n  }\n}\n\nfunction serializeAttr(\n  attr: HtmlCommentAttribute | LinkAttribute | ImageAttribute,\n): string {\n  switch (attr.operator) {\n    case 'exists':\n      return `[${attr.key}]`;\n    case 'equals':\n      return `[${attr.key}=\"${attr.value}\"]`;\n    case 'contains':\n      return `[${attr.key}*=\"${attr.value}\"]`;\n    case 'startsWith':\n      return `[${attr.key}^=\"${attr.value}\"]`;\n    case 'endsWith':\n      return `[${attr.key}$=\"${attr.value}\"]`;\n  }\n}\n\n/**\n * Serialize a PatternNode back to a pattern string.\n * This is the inverse of tokenize() + parse().\n * Used by mergeDetector to express merged/suggested patterns.\n */\nexport function serializePatternNode(node: PatternNode): string {\n  switch (node.kind) {\n    case 'element': {\n      let s = node.element;\n      if (node.element === 'html_comment' && node.htmlCommentAttrs?.length) {\n        s += node.htmlCommentAttrs.map(serializeAttr).join('');\n      }\n      if (node.element === 'link' && node.linkAttrs?.length) {\n        s += node.linkAttrs.map(serializeAttr).join('');\n      }\n      if (node.element === 'image' && node.imageAttrs?.length) {\n        s += node.imageAttrs.map(serializeAttr).join('');\n      }\n      if (node.quantifier) {\n        s += serializeQuantifier(node.quantifier);\n      }\n      return s;\n    }\n\n    case 'sequence':\n      return node.children.map(serializePatternNode).join(' > ');\n\n    case 'alternation': {\n      // No parens here — when an alternation is inside a group, the group adds parens.\n      // When used directly in a sequence, no parens are needed (alternation has lower\n      // precedence than sequence anyway, so `a | b > c` parses as `a | (b > c)`).\n      const inner = node.choices.map(serializePatternNode).join(' | ');\n      return node.quantifier\n        ? `${inner}${serializeQuantifier(node.quantifier)}`\n        : inner;\n    }\n\n    case 'group': {\n      const inner = serializePatternNode(node.pattern);\n      // Groups always have parens — they exist precisely to group for quantifiers\n      const s = `(${inner})`;\n      return node.quantifier\n        ? `${s}${serializeQuantifier(node.quantifier)}`\n        : s;\n    }\n\n    case 'list': {\n      let s = 'list';\n      if (node.itemCount !== undefined || node.itemStructure !== undefined) {\n        s += '{item';\n        if (node.itemCount) {\n          s += serializeQuantifier(node.itemCount);\n        }\n        if (node.itemStructure) {\n          s += ':' + serializePatternNode(node.itemStructure);\n        }\n        s += '}';\n      }\n      if (node.quantifier) {\n        s += serializeQuantifier(node.quantifier);\n      }\n      return s;\n    }\n  }\n}\n"],"mappings":"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","ignoreList":[]}

package/dist/cjs/patternAnalyzer/run.js

@@ -0,0 +1,140 @@
+"use strict";
+
+var _index = require("./index");
+var _fs = require("fs");
+var _path = require("path");
+const outputFlagIndex = process.argv.indexOf('--output');
+const OUTPUT_MD = outputFlagIndex >= 0 ? process.argv[outputFlagIndex + 1] : 'pattern-analysis-report.md';
+const OUTPUT_JSON = OUTPUT_MD.replace(/\.md$/, '.json');
+function run() {
+  console.log('Running pattern analysis...\n');
+  const startTime = Date.now();
+  const report = (0, _index.runAnalysis)();
+  const elapsed = Date.now() - startTime;
+
+  // Write JSON
+  const jsonPath = (0, _path.resolve)(OUTPUT_JSON);
+  (0, _fs.writeFileSync)(jsonPath, JSON.stringify(report, null, 2), 'utf-8');
+  console.log(`JSON report: ${jsonPath}`);
+
+  // Write Markdown
+  const md = renderMarkdown(report);
+  const mdPath = (0, _path.resolve)(OUTPUT_MD);
+  (0, _fs.writeFileSync)(mdPath, md, 'utf-8');
+  console.log(`Markdown report: ${mdPath}\n`);
+
+  // Console summary
+  const fullConflicts = report.conflicts.filter(c => c.severity === 'full').length;
+  const partialConflicts = report.conflicts.filter(c => c.severity === 'partial').length;
+  const failingValidations = report.parserValidation.filter(r => r.failures.length > 0).length;
+  console.log(`=== Analysis Summary (${elapsed}ms) ===`);
+  console.log(`Definitions:          ${report.totalDefinitions}`);
+  console.log(`Patterns:             ${report.totalPatterns}`);
+  console.log(`Conflicts:            ${report.conflicts.length} (${fullConflicts} full, ${partialConflicts} partial)`);
+  console.log(`Parser issues:        ${failingValidations} patterns with failures`);
+  console.log(`Merge opportunities:  ${report.mergeOpportunities.length}`);
+}
+function renderMarkdown(report) {
+  const lines = [];
+  lines.push('# Pattern Analysis Report');
+  lines.push('');
+  lines.push(`Generated: ${report.generatedAt}`);
+  lines.push('');
+  lines.push(`**${report.totalDefinitions}** definitions · **${report.totalPatterns}** patterns`);
+  lines.push('');
+
+  // ── Definitions table ──────────────────────────────────────────────────────
+  lines.push('## Definitions (in priority order)');
+  lines.push('');
+  lines.push('| # | Section Type | Patterns | Samples Generated |');
+  lines.push('|---|-------------|---------|-------------------|');
+  for (const d of report.definitions) {
+    lines.push(`| ${d.priority} | \`${d.sectionType}\` | ${d.patterns.length} | ${d.samplesGenerated} |`);
+  }
+  lines.push('');
+
+  // ── Conflict Detection ─────────────────────────────────────────────────────
+  lines.push('## Conflict Detection');
+  lines.push('');
+  lines.push('> **Note:** Sample-based analysis — not exhaustive. `FULL` means every generated sample');
+  lines.push('> was captured by a higher-priority definition. Conflicts may be intentional');
+  lines.push('> (e.g. the definition relies on `parse()` returning `null` to differentiate).');
+  lines.push('');
+  if (report.conflicts.length === 0) {
+    lines.push('No conflicts detected.');
+    lines.push('');
+  } else {
+    for (const c of report.conflicts) {
+      renderConflict(c, lines);
+    }
+  }
+
+  // ── Parser Validation ──────────────────────────────────────────────────────
+  lines.push('## Parser Validation');
+  lines.push('');
+  const failing = report.parserValidation.filter(r => r.failures.length > 0);
+  if (failing.length === 0) {
+    lines.push('All patterns passed — `parse()` returned non-null for all generated samples.');
+    lines.push('');
+  } else {
+    lines.push(`${failing.length} pattern(s) had issues:`);
+    lines.push('');
+    for (const r of failing) {
+      renderValidationFailure(r, lines);
+    }
+  }
+
+  // ── Merge Opportunities ────────────────────────────────────────────────────
+  lines.push('## Merge Opportunities');
+  lines.push('');
+  if (report.mergeOpportunities.length === 0) {
+    lines.push('No merge opportunities detected.');
+    lines.push('');
+  } else {
+    for (const m of report.mergeOpportunities) {
+      renderMergeOpportunity(m, lines);
+    }
+  }
+  return lines.join('\n');
+}
+function renderConflict(c, lines) {
+  const badge = c.severity === 'full' ? '`FULL`' : '`PARTIAL`';
+  lines.push(`### ${badge} \`${c.shadowedDefinition}\` (p${c.shadowedPriority}) shadowed by \`${c.shadowingDefinition}\` (p${c.shadowingPriority})`);
+  lines.push('');
+  lines.push(`- **Victim pattern:** \`${c.shadowedPattern}\``);
+  lines.push(`- **Stealing pattern:** \`${c.shadowingPattern}\``);
+  lines.push('');
+  if (c.samples.length > 0) {
+    lines.push('**Example markdown that triggers the conflict:**');
+    lines.push('');
+    lines.push('```markdown');
+    lines.push(c.samples[0].markdown);
+    lines.push('```');
+  }
+  lines.push('');
+}
+function renderValidationFailure(r, lines) {
+  lines.push(`### \`${r.sectionType}\` — ${r.samplesPassedCount}/${r.samplesTestedCount} samples passed`);
+  lines.push('');
+  lines.push(`Pattern: \`${r.pattern}\``);
+  lines.push('');
+  for (const f of r.failures.slice(0, 3)) {
+    lines.push(`- **${f.error}**${f.detail ? ': ' + f.detail : ''}`);
+    const indented = f.markdown.split('\n').map(l => '  ' + l).join('\n');
+    lines.push('  ```markdown');
+    lines.push(indented);
+    lines.push('  ```');
+  }
+  lines.push('');
+}
+function renderMergeOpportunity(m, lines) {
+  lines.push(`### \`${m.sectionType}\` — \`${m.kind}\``);
+  lines.push('');
+  lines.push(`- **Pattern 1:** \`${m.pattern1}\``);
+  lines.push(`- **Pattern 2:** \`${m.pattern2}\``);
+  lines.push(`- **Suggestion:** \`${m.suggestedPattern}\``);
+  lines.push(`- **Rationale:** ${m.rationale}`);
+  lines.push('');
+}
+run();
+//# sourceMappingURL=run.js.map

package/dist/cjs/patternAnalyzer/run.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_index","require","_fs","_path","outputFlagIndex","process","argv","indexOf","OUTPUT_MD","OUTPUT_JSON","replace","run","console","log","startTime","Date","now","report","runAnalysis","elapsed","jsonPath","resolve","writeFileSync","JSON","stringify","md","renderMarkdown","mdPath","fullConflicts","conflicts","filter","c","severity","length","partialConflicts","failingValidations","parserValidation","r","failures","totalDefinitions","totalPatterns","mergeOpportunities","lines","push","generatedAt","d","definitions","priority","sectionType","patterns","samplesGenerated","renderConflict","failing","renderValidationFailure","m","renderMergeOpportunity","join","badge","shadowedDefinition","shadowedPriority","shadowingDefinition","shadowingPriority","shadowedPattern","shadowingPattern","samples","markdown","samplesPassedCount","samplesTestedCount","pattern","f","slice","error","detail","indented","split","map","l","kind","pattern1","pattern2","suggestedPattern","rationale"],"sources":["../../../src/patternAnalyzer/run.ts"],"sourcesContent":["import { runAnalysis } from './index';\nimport type {\n  AnalysisReport,\n  ConflictReport,\n  ParserValidationReport,\n  MergeOpportunity,\n} from './types';\nimport { writeFileSync } from 'fs';\nimport { resolve } from 'path';\n\nconst outputFlagIndex = process.argv.indexOf('--output');\nconst OUTPUT_MD =\n  outputFlagIndex >= 0\n    ? process.argv[outputFlagIndex + 1]\n    : 'pattern-analysis-report.md';\nconst OUTPUT_JSON = OUTPUT_MD.replace(/\\.md$/, '.json');\n\nfunction run(): void {\n  console.log('Running pattern analysis...\\n');\n  const startTime = Date.now();\n\n  const report = runAnalysis();\n  const elapsed = Date.now() - startTime;\n\n  // Write JSON\n  const jsonPath = resolve(OUTPUT_JSON);\n  writeFileSync(jsonPath, JSON.stringify(report, null, 2), 'utf-8');\n  console.log(`JSON report: ${jsonPath}`);\n\n  // Write Markdown\n  const md = renderMarkdown(report);\n  const mdPath = resolve(OUTPUT_MD);\n  writeFileSync(mdPath, md, 'utf-8');\n  console.log(`Markdown report: ${mdPath}\\n`);\n\n  // Console summary\n  const fullConflicts = report.conflicts.filter(\n    (c) => c.severity === 'full',\n  ).length;\n  const partialConflicts = report.conflicts.filter(\n    (c) => c.severity === 'partial',\n  ).length;\n  const failingValidations = report.parserValidation.filter(\n    (r) => r.failures.length > 0,\n  ).length;\n\n  console.log(`=== Analysis Summary (${elapsed}ms) ===`);\n  console.log(`Definitions:          ${report.totalDefinitions}`);\n  console.log(`Patterns:             ${report.totalPatterns}`);\n  console.log(\n    `Conflicts:            ${report.conflicts.length} (${fullConflicts} full, ${partialConflicts} partial)`,\n  );\n  console.log(\n    `Parser issues:        ${failingValidations} patterns with failures`,\n  );\n  console.log(`Merge opportunities:  ${report.mergeOpportunities.length}`);\n}\n\nfunction renderMarkdown(report: AnalysisReport): string {\n  const lines: string[] = [];\n\n  lines.push('# Pattern Analysis Report');\n  lines.push('');\n  lines.push(`Generated: ${report.generatedAt}`);\n  lines.push('');\n  lines.push(\n    `**${report.totalDefinitions}** definitions · **${report.totalPatterns}** patterns`,\n  );\n  lines.push('');\n\n  // ── Definitions table ──────────────────────────────────────────────────────\n  lines.push('## Definitions (in priority order)');\n  lines.push('');\n  lines.push('| # | Section Type | Patterns | Samples Generated |');\n  lines.push('|---|-------------|---------|-------------------|');\n  for (const d of report.definitions) {\n    lines.push(\n      `| ${d.priority} | \\`${d.sectionType}\\` | ${d.patterns.length} | ${d.samplesGenerated} |`,\n    );\n  }\n  lines.push('');\n\n  // ── Conflict Detection ─────────────────────────────────────────────────────\n  lines.push('## Conflict Detection');\n  lines.push('');\n  lines.push(\n    '> **Note:** Sample-based analysis — not exhaustive. `FULL` means every generated sample',\n  );\n  lines.push(\n    '> was captured by a higher-priority definition. Conflicts may be intentional',\n  );\n  lines.push(\n    '> (e.g. the definition relies on `parse()` returning `null` to differentiate).',\n  );\n  lines.push('');\n\n  if (report.conflicts.length === 0) {\n    lines.push('No conflicts detected.');\n    lines.push('');\n  } else {\n    for (const c of report.conflicts) {\n      renderConflict(c, lines);\n    }\n  }\n\n  // ── Parser Validation ──────────────────────────────────────────────────────\n  lines.push('## Parser Validation');\n  lines.push('');\n  const failing = report.parserValidation.filter((r) => r.failures.length > 0);\n  if (failing.length === 0) {\n    lines.push(\n      'All patterns passed — `parse()` returned non-null for all generated samples.',\n    );\n    lines.push('');\n  } else {\n    lines.push(`${failing.length} pattern(s) had issues:`);\n    lines.push('');\n    for (const r of failing) {\n      renderValidationFailure(r, lines);\n    }\n  }\n\n  // ── Merge Opportunities ────────────────────────────────────────────────────\n  lines.push('## Merge Opportunities');\n  lines.push('');\n  if (report.mergeOpportunities.length === 0) {\n    lines.push('No merge opportunities detected.');\n    lines.push('');\n  } else {\n    for (const m of report.mergeOpportunities) {\n      renderMergeOpportunity(m, lines);\n    }\n  }\n\n  return lines.join('\\n');\n}\n\nfunction renderConflict(c: ConflictReport, lines: string[]): void {\n  const badge = c.severity === 'full' ? '`FULL`' : '`PARTIAL`';\n  lines.push(\n    `### ${badge} \\`${c.shadowedDefinition}\\` (p${c.shadowedPriority}) shadowed by \\`${c.shadowingDefinition}\\` (p${c.shadowingPriority})`,\n  );\n  lines.push('');\n  lines.push(`- **Victim pattern:** \\`${c.shadowedPattern}\\``);\n  lines.push(`- **Stealing pattern:** \\`${c.shadowingPattern}\\``);\n  lines.push('');\n  if (c.samples.length > 0) {\n    lines.push('**Example markdown that triggers the conflict:**');\n    lines.push('');\n    lines.push('```markdown');\n    lines.push(c.samples[0].markdown);\n    lines.push('```');\n  }\n  lines.push('');\n}\n\nfunction renderValidationFailure(\n  r: ParserValidationReport,\n  lines: string[],\n): void {\n  lines.push(\n    `### \\`${r.sectionType}\\` — ${r.samplesPassedCount}/${r.samplesTestedCount} samples passed`,\n  );\n  lines.push('');\n  lines.push(`Pattern: \\`${r.pattern}\\``);\n  lines.push('');\n  for (const f of r.failures.slice(0, 3)) {\n    lines.push(`- **${f.error}**${f.detail ? ': ' + f.detail : ''}`);\n    const indented = f.markdown\n      .split('\\n')\n      .map((l) => '  ' + l)\n      .join('\\n');\n    lines.push('  ```markdown');\n    lines.push(indented);\n    lines.push('  ```');\n  }\n  lines.push('');\n}\n\nfunction renderMergeOpportunity(m: MergeOpportunity, lines: string[]): void {\n  lines.push(`### \\`${m.sectionType}\\` — \\`${m.kind}\\``);\n  lines.push('');\n  lines.push(`- **Pattern 1:** \\`${m.pattern1}\\``);\n  lines.push(`- **Pattern 2:** \\`${m.pattern2}\\``);\n  lines.push(`- **Suggestion:** \\`${m.suggestedPattern}\\``);\n  lines.push(`- **Rationale:** ${m.rationale}`);\n  lines.push('');\n}\n\nrun();\n"],"mappings":"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","ignoreList":[]}

package/dist/cjs/patternAnalyzer/types.js

@@ -0,0 +1,4 @@
+"use strict";
+
+exports.__esModule = true;
+//# sourceMappingURL=types.js.map

package/dist/cjs/patternAnalyzer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sources":["../../../src/patternAnalyzer/types.ts"],"sourcesContent":["import type { SectionDefinition } from '../component/section-definition';\n\nexport interface DefinitionEntry {\n  priority: number;\n  sectionType: string;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  definition: SectionDefinition<any>;\n}\n\nexport interface ConflictCase {\n  markdown: string;\n  generatedFrom: string;\n}\n\nexport interface ConflictReport {\n  shadowedDefinition: string;\n  shadowedPriority: number;\n  shadowedPattern: string;\n  shadowingDefinition: string;\n  shadowingPriority: number;\n  shadowingPattern: string;\n  samples: ConflictCase[];\n  /** full = every generated sample was captured by a higher-priority definition */\n  severity: 'full' | 'partial';\n}\n\nexport interface ValidationFailure {\n  markdown: string;\n  generatedFrom: string;\n  error: 'parse_returned_null' | 'parse_threw';\n  detail?: string;\n}\n\nexport interface ParserValidationReport {\n  sectionType: string;\n  pattern: string;\n  failures: ValidationFailure[];\n  samplesTestedCount: number;\n  samplesPassedCount: number;\n}\n\nexport type MergeKind =\n  | 'subsumption'\n  | 'quantifier_widening'\n  | 'alternation_extension'\n  | 'optional_element';\n\nexport interface MergeOpportunity {\n  sectionType: string;\n  pattern1: string;\n  pattern2: string;\n  kind: MergeKind;\n  suggestedPattern: string;\n  rationale: string;\n}\n\nexport interface DefinitionSummary {\n  sectionType: string;\n  priority: number;\n  patterns: string[];\n  samplesGenerated: number;\n}\n\nexport interface AnalysisReport {\n  generatedAt: string;\n  totalDefinitions: number;\n  totalPatterns: number;\n  definitions: DefinitionSummary[];\n  conflicts: ConflictReport[];\n  parserValidation: ParserValidationReport[];\n  mergeOpportunities: MergeOpportunity[];\n}\n"],"mappings":"","ignoreList":[]}

package/dist/cjs/patternValidator/ERROR_MESSAGES.md

@@ -0,0 +1,110 @@
+# Pattern Validator - Error Messages
+
+The pattern validator now provides detailed error messages to help debug pattern matching issues.
+
+## Usage
+
+To get detailed error messages, pass `true` as the third parameter to `validatePattern`:
+
+```typescript
+import { validatePattern } from './patternValidator';
+
+const blocks = ['h2', 'list{[t, link, link]}'];
+const pattern = 'h2 > list{item[1]:t > link}';
+
+// Get detailed error information
+const result = validatePattern(blocks, pattern, true);
+
+if (!result.valid) {
+  console.error('Validation failed:', result.error);
+}
+```
+
+## Error Types
+
+### 1. Item Count Mismatch
+
+When a list has the wrong number of items:
+
+```typescript
+const blocks = ['h2', 'list{[t], [t], [t]}'];
+const pattern = 'h2 > list{item[2]:t}';
+
+const result = validatePattern(blocks, pattern, true);
+// Error: "Expected exactly 2 items in list, but got 3 items"
+```
+
+### 2. Item Structure Mismatch
+
+When a list item doesn't match the expected pattern:
+
+```typescript
+const blocks = ['h2', 'list{[t, link, link]}'];
+const pattern = 'h2 > list{item[1]:t > link}';
+
+const result = validatePattern(blocks, pattern, true);
+// Error: "Item #1 [t, link, link] does not match expected pattern: t > link"
+```
+
+### 3. Unexpected Element
+
+When an element appears that doesn't match the pattern:
+
+```typescript
+const blocks = ['h2', 'image', 't'];
+const pattern = 'h2 > t > link';
+
+const result = validatePattern(blocks, pattern, true);
+// Error: "Unexpected element 'image' at position 2. Pattern does not match."
+```
+
+### 4. Incomplete Pattern
+
+When the pattern expects more elements:
+
+```typescript
+const blocks = ['h2', 't'];
+const pattern = 'h2 > t > link > image';
+
+const result = validatePattern(blocks, pattern, true);
+// Error: "Pattern matching incomplete. Expected more elements after position 2."
+```
+
+### 5. Unexpected List
+
+When a list appears where the pattern doesn't expect one:
+
+```typescript
+const blocks = ['h2', 'list{[t]}'];
+const pattern = 'h2 > t';
+
+const result = validatePattern(blocks, pattern, true);
+// Error: "Unexpected list at position 2. Pattern does not expect a list here."
+```
+
+## Return Type
+
+When called with `returnDetails: true`, the function returns:
+
+```typescript
+type PatternValidationResult = {
+  valid: boolean;
+  error?: string;
+};
+```
+
+- `valid`: `true` if the pattern matches, `false` otherwise
+- `error`: Detailed error message (only present when `valid` is `false`)
+
+## Backward Compatibility
+
+The original boolean return type is still supported:
+
+```typescript
+// Returns boolean
+const isValid = validatePattern(blocks, pattern);
+
+// Returns PatternValidationResult
+const result = validatePattern(blocks, pattern, true);
+```
+