ネストテーブルとrowspanの処理方法（HTMLテーブルパースの難所）

ement): string[][] { const rows = Array.from(tableElement.rows); const grid: string[][] = []; const occupied: Set<string> = new Set();

rows.forEach((rowEl, rIdx) => { if (!grid[rIdx]) grid[rIdx] = []; let cIdx = 0;

Array.from(rowEl.cells).forEach((cell) => {
  while (occupied.has(`${rIdx}-${cIdx}`)) cIdx++;

  const rSpan = Math.max(1, parseInt(cell.getAttribute("rowspan") || "1", 10));
  const cSpan = Math.max(1, parseInt(cell.getAttribute("colspan") || "1", 10));
  const text = cell.textContent?.trim() ?? "";

  for (let dr = 0; dr < rSpan; dr++) {
    const targetRow = rIdx + dr;
    if (!grid[targetRow]) grid[targetRow] = [];
    for (let dc = 0; dc < cSpan; dc++) {
      const targetCol = cIdx + dc;
      occupied.add(`${targetRow}-${targetCol}`);
      grid[targetRow][targetCol] = text;
    }
  }
  cIdx += cSpan;
});

});

// Normalize row lengths const maxCols = Math.max(...grid.map((r) => r.length), 0); return grid.map((row) => { const normalized = new Array(maxCols).fill(""); row.forEach((val, i) => (normalized[i] = val)); return normalized; }); }

**Architecture Rationale:** Using a `Set` for occupied coordinates provides O(1) collision checks. Normalizing row lengths after expansion guarantees downstream stages receive uniform arrays. This stage is deliberately pure: it only resolves layout, never filters content.

### Stage 2: Noise Isolation
Real-world tables contain UI elements that mimic data rows. Navigation links, full-width titles, and nested layout tables must be identified and removed before header resolution.

```typescript
function isolateNoiseRows(matrix: string[][]): { cleanMatrix: string[][]; headerOffset: number } {
  const navPatterns = [/^v\s*t\s*e/i, /^\[v\]\s*\[t\]\s*\[e\]/i, /^navigate/i];
  let headerOffset = 0;

  for (let i = 0; i < Math.min(3, matrix.length); i++) {
    const row = matrix[i];
    const firstCell = row[0] ?? "";

    if (navPatterns.some((p) => p.test(firstCell))) {
      headerOffset = i + 1;
      break;
    }

    const uniqueValues = new Set(row.filter((c) => c.trim()).slice(0, 3));
    if (uniqueValues.size === 1 && firstCell.length > 25) {
      headerOffset = i + 1;
      break;
    }
  }

  return { cleanMatrix: matrix.slice(headerOffset), headerOffset };
}

Architecture Rationale: Heuristic thresholds (e.g., length > 25, uniqueValues.size === 1) are configurable rather than hardcoded. This prevents false positives on legitimate short headers while catching full-width title banners. The function returns an offset, allowing downstream stages to preserve original indexing if needed.

Stage 3: Multi-Level Header Resolution

Sports and financial tables frequently use grouped column headers. The first row contains category names, the second contains specific metrics. Both must be merged into a single header array.

function resolveGroupedHeaders(matrix: string[][]): string[][] {
  if (matrix.length < 2) return matrix;

  const [topRow, subRow] = matrix;
  let repeatCount = 0;

  for (let i = 1; i < topRow.length; i++) {
    if (topRow[i] && topRow[i] === topRow[i - 1]) repeatCount++;
  }

  const repeatRatio = repeatCount / Math.max(1, topRow.length - 1);
  const topUnique = new Set(topRow.filter((c) => c.trim())).size;
  const subUnique = new Set(subRow.filter((c) => c.trim())).size;

  if (repeatRatio > 0.35 && subUnique > topUnique) {
    const merged = subRow.map((sub, idx) => {
      const group = topRow[idx]?.trim() ?? "";
      const metric = sub.trim();
      if (!group || group.toLowerCase() === metric.toLowerCase()) return metric;
      return `${group} - ${metric}`;
    });
    return [merged, ...matrix.slice(2)];
  }

  return matrix;
}

Architecture Rationale: The repeatRatio > 0.35 threshold detects colspan expansion without requiring exact matches. Merging preserves hierarchy while flattening the structure for downstream consumption. This stage only activates when statistical evidence confirms a grouped layout.

Stage 4: Horizontal Duplication Normalization

Encyclopedic tables often tile data horizontally to save vertical space. Two identical column sets appear side-by-side. The parser must detect this pattern and stack the halves vertically.

function normalizeHorizontalTiling(matrix: string[][]): string[][] {
  if (matrix.length < 2) return matrix;

  const header = matrix[0];
  const half = Math.floor(header.length / 2);
  if (half < 2) return matrix;

  const left = header.slice(0, half);
  const right = header.slice(half, half * 2);

  const isMirrored = left.every((l, i) => l.toLowerCase() === right[i]?.toLowerCase());
  if (!isMirrored) return matrix;

  const normalized = [left];
  for (let i = 1; i < matrix.length; i++) {
    const row = matrix[i];
    normalized.push(row.slice(0, half));
    const rightHalf = row.slice(half, half * 2);
    if (rightHalf.some((c) => c.trim())) {
      normalized.push(rightHalf);
    }
  }
  return normalized;
}

Architecture Rationale: Case-insensitive header comparison prevents false negatives from casing variations. Empty right-half rows are skipped to avoid padding artifacts. The function returns early if tiling isn't detected, preserving performance on standard tables.

Pipeline Orchestration

export function parseComplexTable(tableEl: HTMLTableElement): string[][] {
  let grid = buildVirtualGrid(tableEl);
  const { cleanMatrix } = isolateNoiseRows(grid);
  grid = cleanMatrix;
  grid = resolveGroupedHeaders(grid);
  grid = normalizeHorizontalTiling(grid);
  return grid;
}

Why this architecture works: Each stage is idempotent and stateless. The pipeline can be extended with additional filters (e.g., footer removal, data type coercion) without breaking existing logic. Testing becomes modular: fixtures can be injected at any stage to verify isolation behavior.

Pitfall Guide

Pitfall	Explanation	Fix
Direct DOM Row Iteration	Iterating table.rows assumes each row maps to one logical data row. rowspan creates invisible placeholders that shift subsequent columns.	Always construct a virtual grid first. Treat DOM cells as layout instructions, not data containers.
Ignoring colSpan During Expansion	Focusing only on rowspan leaves horizontal spans unhandled, causing column misalignment when headers use colspan.	Resolve both rowSpan and colSpan simultaneously during grid construction. Use a coordinate occupancy map to prevent overlaps.
Hardcoding Header Detection	Assuming the first row is always the header fails on tables with navigation links, titles, or multi-tier headers.	Use statistical heuristics (uniqueness ratio, length thresholds, pattern matching) to dynamically locate the header offset.
Blindly Flattening Nested Tables	Extracting textContent from a cell containing a nested table merges unrelated data streams, corrupting schema alignment.	Detect nested tables via DOM ancestry traversal. Strip them before text extraction, or process them as independent entities.
Assuming Uniform Column Counts	Real-world tables often have ragged edges due to missing cells or layout artifacts. Downstream parsers crash on length mismatches.	Normalize all rows to the maximum column count after grid expansion. Fill missing positions with empty strings or null.
Whitespace & Formatting Artifacts	Browser rendering injects non-breaking spaces, zero-width characters, and line breaks that break regex matching and equality checks.	Sanitize text content using trim() and regex normalization (/\s+/g, " ") before any comparison or storage.
Skipping Validation Against Source	Parsers that don't verify output against the original DOM silently drop data or misalign rows, leading to downstream corruption.	Implement a checksum or row-count validation step. Compare extracted dimensions against table.rows.length and table.cells.length.

Production Tip: For large tables (>500 rows), avoid synchronous DOM manipulation in the browser. Use requestAnimationFrame to chunk grid construction, or offload parsing to a Web Worker. In Node.js environments, stream HTML parsing with parse5 or linkedom to avoid loading the entire document into memory.

Production Bundle

Action Checklist

• Grid First: Always resolve spans into a 2D matrix before extracting values or detecting headers.
• Sanitize Early: Strip whitespace, zero-width characters, and nested layout tables before heuristic analysis.
• Threshold Configuration: Expose noise detection ratios and length limits as configurable parameters, not hardcoded constants.
• Stage Isolation: Keep grid construction, noise filtering, header resolution, and normalization in separate, testable functions.
• Validation Layer: Add a post-parsing step that verifies row/column counts match expected schema dimensions.
• Fixture Testing: Maintain a suite of HTML snippets covering rowspan, colSpan, nested tables, nav rows, and horizontal tiling.
• Performance Guardrails: Chunk large DOM operations or use streaming parsers to prevent main-thread blocking.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Internal clean datasets (known schema)	Naive DOM iteration	Low overhead, predictable structure	Minimal
Public web scraping (heterogeneous sources)	Virtual Grid + Heuristics	Handles spans, noise, and multi-tier layouts deterministically	Moderate (dev time)
Legacy enterprise portals (dynamic JS rendering)	Headless browser + Virtual Grid	Resolves client-side rendered tables before parsing	High (infrastructure)
Rapid prototyping / low volume	LLM-assisted extraction	Contextual understanding, minimal code	High ($/token, latency)

Configuration Template

export interface TableParserConfig {
  noisePatterns: RegExp[];
  titleLengthThreshold: number;
  groupRepeatRatio: number;
  horizontalTilingEnabled: boolean;
  maxHeaderSearchDepth: number;
  sanitizeWhitespace: boolean;
}

export const defaultConfig: TableParserConfig = {
  noisePatterns: [/^v\s*t\s*e/i, /^\[v\]\s*\[t\]\s*\[e\]/i, /^navigate/i],
  titleLengthThreshold: 25,
  groupRepeatRatio: 0.35,
  horizontalTilingEnabled: true,
  maxHeaderSearchDepth: 3,
  sanitizeWhitespace: true,
};

Quick Start Guide

1. Install Dependencies: Use native DOM APIs in browsers, or linkedom/jsdom in Node.js. No external parsing libraries required.
2. Initialize Parser: Import the pipeline functions and apply defaultConfig or override thresholds for your target sources.
3. Inject HTML: Pass a HTMLTableElement or parsed DOM node to parseComplexTable(). The function returns a normalized string[][].
4. Validate Output: Check result.length and result[0].length against expected schema. Run fixture tests to verify span and noise handling.
5. Integrate: Pipe the output into your ETL pipeline, CSV serializer, or database mapper. Add type coercion (numbers, dates) as a final transformation step.