Add followBlueprintOrder option to export-workbook plugin

[devin-ai-integration]

Summary

Adds followBlueprintOrder option to fix column order mismatch between review screen and exports. When enabled, exports columns in sheet.config.fields order (matching UI) instead of API values object order.

Also includes correctness fixes and performance optimizations identified during code review:

• Transformer memoization to avoid redundant async calls
• Converts excludeFields to Set for O(1) lookups
• Fixes empty row handling to respect excludeFields and includeRecordIds
• Hoists blueprintKeys set outside record loop
• Sorts additional fields by key (not label) for stability
• Adds test to guard against xlsx upgrades breaking comment shape

Link to Devin run: https://app.devin.ai/sessions/2c390f0d20a740a196f83e9bd8187531
Requested by: christopher.harrison@flatfile.io (@cnharrison)

Please explain how to summarize this PR for the Changelog:

Added followBlueprintOrder option to export columns in blueprint order (matching review screen) instead of API values order. When enabled, handles duplicate labels, additional fields, and exports all blueprint fields in correct order. Includes performance optimizations (transformer memoization, Set-based field filtering) and fixes empty row handling to respect excludeFields and includeRecordIds.

Tell code reviewer how and what to test:

⚠️ CRITICAL: This was not integration tested in a real Flatfile environment. Unit tests (8/8) passed locally, but needs manual testing with real data before merge.

Key items to review and test:

1. Backward compatibility (MOST IMPORTANT)

• Verify existing exports WITHOUT followBlueprintOrder are completely unchanged
• Test with various sheet configurations to ensure no regressions
• Risk: Changes to formatCell, empty row handling, and memoization affect all exports

2. Duplicate label handling

• Create sheet with multiple fields that transform to same label (e.g., two "Employee ID" fields)
• Verify output shows "Employee ID" and "Employee ID (field.key)"
• Review: Is the "(key)" suffix format acceptable for production?

3. Additional fields ordering

• Add fields to records that aren't in blueprint
• Verify they appear sorted by key (not label) at the end of export
• Risk: Behavior change from previous implementation

4. Empty row handling

• Export empty sheet with excludeFields set - verify excluded fields don't appear
• Export empty sheet with includeRecordIds: true - verify recordId column appears
• Risk: Behavior change that could affect templates or automated processes

5. Customer scenario (78-field blueprint)

• Test with large blueprint (78+ fields) where only 6 are visible in UI
• Verify the 6 visible columns move from positions 19-24 to positions 1-6
• Verify all 78 blueprint fields export in correct order
• Context: This is the actual customer use case that motivated this PR

6. Performance

• Test with wide sheets (50+ fields, 1000+ records)
• Verify no significant slowdown from transformer memoization or header building
• Monitor memory usage with large datasets

How to enable:

exportWorkbookPlugin({
  followBlueprintOrder: true, // NEW: exports match review screen order
  // ... other options
})

What changed and why:

• followBlueprintOrder option: When true, builds explicit header from sheet.config.fields instead of inferring from Object.keys(row)
• Duplicate label handling: Multiple fields with same label get disambiguated as "Label (key)"
• Extras ordering: Additional fields sorted by key (not label) for stability across transformer changes
• Empty row fix: Now respects excludeFields and includeRecordIds for consistency
• Performance optimizations: Memoized transformer, Set for excludeFields, hoisted blueprintKeys
• Comment shape test: Guards against future xlsx upgrades changing comment API

Known limitations:

• Does NOT mirror UI visibility (hidden/pinned columns) - only mirrors field order
• Duplicate labels get "(key)" suffix - may not be ideal UX for all cases
• Not tested with very large datasets (10k+ records, 100+ fields)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[promptless]

📝 Documentation updates detected!

New suggestion: Add changelog entry for export-workbook followBlueprintOrder option

[devin-ai-integration]

Closing due to inactivity for more than 7 days. Configure here.