v4.0.0 - Support for New 14-Column Usage Report Format

🚀 v4.0.0 - Major Release

Breaking Changes 💥

• workflowName is now optional in UsageReportLine type to support the new 14-column GitHub usage report format
• The library now accepts both 14-column (new) and 15-column (legacy) formats automatically

New Features ✨

14-Column Format Support

• Automatically detects and parses the new 14-column usage report format that excludes the workflow_name field
• Maintains full backward compatibility with existing 15-column format
• Format detection is transparent - no configuration needed

Enhanced Error Handling 🛡️

• Gracefully skips malformed CSV rows with warnings instead of crashing
• Added try-catch blocks in file parsing functions for better reliability
• Continues processing valid rows even when encountering invalid data

Improved Robustness 💪

• Handles CSV rows with embedded commas that exceed expected column counts
• Validates column count strictly (14 or 15 columns only)
• Scientific notation support for numeric values (e.g., 9.4086E-05)

Testing Improvements 🧪

Added comprehensive test coverage for real-world scenarios:

• Empty string values in all fields
• Zero, negative, and very large numbers
• High-precision decimal handling
• Different date formats and ranges
• Special characters in usernames, organizations, and repositories
• Whitespace preservation
• Long workflow paths
• New product types (copilot, packages, git_lfs)
• Mixed format handling
• Invalid line skipping

Test count increased from 10 to 20 tests with 100% pass rate!

Technical Details 📋

Format Differences

14-Column Format (New):

date, product, sku, quantity, unit_type, applied_cost_per_quantity, 
gross_amount, discount_amount, net_amount, username, organization, 
repository, workflow_path, cost_center_name

15-Column Format (Legacy):

formatted_date, product, sku, quantity, unit_type, applied_cost_per_quantity,
gross_amount, discount_amount, net_amount, username, organization,
repository_name, workflow_name, workflow_path, cost_center_name

Migration Guide

If you were previously accessing workflowName:

// Before (v3.x)
const name = line.workflowName; // Always defined

// After (v4.0.0)
const name = line.workflowName; // May be undefined for 14-column format
if (line.workflowName) {
  // Handle workflow name
}

For most use cases, no code changes are required as the parser handles both formats automatically.

Files Changed 📝

• src/types.ts - Made workflowName optional
• src/usage-report.ts - Added format detection and error handling
• src/node.ts - Enhanced file reading with try-catch blocks
• tests/main.test.ts - Expanded test suite with 10 new comprehensive tests
• tests/data/usageReport_14col_sample.csv - Added sample 14-column test data
• package.json - Version bump to 4.0.0

Upgrade Notes 📦

npm install github-usage-report@4.0.0

This is a major version bump due to the breaking change in the UsageReportLine type. However, the change is minimal and most codebases will not require modifications.

---

Full Changelog: v3.1.0...v4.0.0