chore: add debug scripts

[MasterPtato]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
rivetkit-serverless	Ready	Preview	Comment	Nov 20, 2025 8:52pm

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Nov 20, 2025 8:52pm
rivet-inspector	Ignored	Preview		Nov 20, 2025 8:52pm
rivet-site	Ignored	Preview		Nov 20, 2025 8:52pm

[MasterPtato]

• chore(rivetkit): implement new hibernating ws protocol #3464 : 2 dependent PRs (#3452 , #3487 )
• fix(actor-kv): fix listing keys #3484
• fix(guard): handle actor stopped during ws/req #3481
• chore: rename retry -> hibernate in runner protocol #3473
• fix(udb): update backoff algo #3469
• chore: write/update docs #3468
• chore: add debug scripts #3467 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: Add Debug Scripts

Summary

This PR adds debugging utilities to help visualize and analyze Rivet engine logs. The main additions are:

1. logfmt_to_gantt.ts - Converts logfmt logs to Mermaid Gantt charts
2. debug_mermaid.ts - Binary search tool for debugging problematic Mermaid gantt entries
3. Moves decode_audit_entry.js to the debug directory

Code Quality & Best Practices

Positive Aspects

• Well-structured code: Both scripts have clear separation of concerns with dedicated helper functions
• Good documentation: Usage instructions in comments at the top of files
• Type safety: Proper TypeScript interfaces for LogEntry and Task
• Robust parsing: Handles ANSI color codes, quoted values, and edge cases in logfmt parsing
• Flexible filtering: Time-based filtering with support for both absolute timestamps and time-of-day

Issues & Suggestions

1. Potential bugs in logfmt_to_gantt.ts

Line 505, 508, 513: Potential runtime error when workflow_id is undefined

const wfId = task.metadata.workflow_id.substring(0, 8);  // Could crash if undefined

The code assumes workflow_id exists for workflow and activity tasks in non-split mode, but only checks for it in signal tasks (line 513). Should add null checks or use optional chaining:

const wfId = task.metadata.workflow_id?.substring(0, 8) || 'unknown';

Line 225: No validation that entries array is non-empty before accessing entries[0].ts

const startTime = entries[0].ts;

While there's a check at line 171, subsequent filtering (lines 177-208) could leave the array empty. The empty check at line 204 should be moved after the time filtering logic.

2. Logic issues

Lines 188-191, 194-199: Inefficient array mutation

entries.splice(0, entries.length, ...entries.filter(...));

This creates a copy of the filtered array and splices it back. Better to use simple reassignment:

const filtered = entries.filter(...);
entries.length = 0;
entries.push(...filtered);

Or better yet, avoid mutation entirely and use a new variable.

Lines 317-323: Operation matching logic is fragile

for (const [k, task] of operationTasks.entries()) {
    if (k.startsWith(entry.operation_name) && !task.end) {
        task.end = entry.ts;
        break;
    }
}

This matches by string prefix, which could incorrectly match operations with similar names (e.g., "operation" would match "operation_call"). Should use exact name matching with timestamp-based pairing.

3. Error handling

Missing error handling for:

• File I/O operations (lines 157, 552) - Should catch and handle ENOENT, EACCES errors
• Invalid date parsing (line 59) - new Date(value) could return Invalid Date
• Fractional second parsing (line 64) - parseFloat could return NaN

Recommended pattern:

try {
    const content = readFileSync(inputFile, 'utf-8');
} catch (error) {
    console.error(`Failed to read file ${inputFile}:`, error.message);
    process.exit(1);
}

4. Performance considerations

Line 317-323: Nested loop for operation matching - O(n²) complexity if many operations
Consider using a Map with operation name as key to track pending operations for O(1) lookup.

Line 188-199: Creating new arrays for filtering when could filter once and store result

5. Code style issues

Hard-coded file paths: Lines 11, 145, 146 use /tmp/ paths. Consider:

• Making these configurable via environment variables
• Using os.tmpdir() for cross-platform compatibility
• Adding validation that paths exist/are writable

Magic numbers:

• Line 95: substring(0, 50) - Should be a named constant
• Line 518: 0.01 - Should be a named constant like MIN_DURATION_THRESHOLD_MS

Inconsistent string concatenation: Mix of template literals and string concatenation

Security Concerns

Low Risk Issues

1. Arbitrary file paths (lines 145-146): Scripts accept user-provided file paths without validation. Could potentially:

   • Read sensitive files if run with elevated permissions
   • Write to arbitrary locations

   Recommendation: Validate that paths are within expected directories or use a safelist.

2. Regular expression complexity (lines 40, 51): ANSI regex and logfmt regex should be tested for ReDoS vulnerabilities, though current patterns appear safe.

3. Process.exit() calls: Multiple calls without cleanup could leave resources in inconsistent state if extended in the future.

Performance Considerations

1. Memory usage: Large log files are loaded entirely into memory (line 157). For very large logs (>100MB), consider streaming or chunked processing.

2. O(n²) iteration: The operation matching logic could be optimized as mentioned above.

3. String operations: Multiple string replacements in sanitizeForMermaid could be combined into a single pass with a custom function.

Test Coverage

Missing tests: No tests are included for these utilities. Recommended test cases:

• Parsing various logfmt formats
• Handling malformed log entries
• Time filtering edge cases
• Empty log files
• Very large log files
• Invalid Mermaid characters in workflow/activity names

Additional Observations

Positive

• The sub-millisecond precision tracking is well-implemented
• Signal send/receive duration calculation is clever
• The split-by-workflow feature provides useful flexibility

Minor improvements

1. debug_mermaid.ts line 38: Using Math.max(...sectionStarts.filter(s => s < 10)) could fail if no sections exist or all are >= 10. Should handle edge case.

2. Type definitions: Consider moving interfaces to a shared types file if these scripts will be extended.

3. Configuration: Consider using a config file or environment variables for defaults instead of hard-coded values.

Overall Assessment

Recommendation: Approve with minor fixes

These are useful debugging tools that will help with development and troubleshooting. The code is generally well-written but has some potential runtime errors that should be fixed before merging:

Must fix:

• Add null checks for workflow_id access (logfmt_to_gantt.ts:505, 508)
• Move empty array check after time filtering logic

Should fix:

• Add error handling for file I/O
• Validate date parsing results
• Fix inefficient array mutation pattern

Nice to have:

• Add tests
• Extract magic numbers to constants
• Consider streaming for large files
• Use cross-platform temp directory resolution

[claude]

Code Review

Thank you for adding these debug utilities! These tools will be valuable for debugging and analyzing Rivet engine execution.

Positives

• Well-documented with clear usage instructions
• Practical utility for visualizing workflow execution
• Good TypeScript setup with proper package configuration
• Comprehensive logfmt parser handling ANSI colors and fractional seconds

Code Quality Issues

1. Potential null pointer exception (logfmt_to_gantt.ts:505, 508)
Lines 505 and 508 access task.metadata.workflow_id.substring(0, 8) without checking if workflow_id exists. Line 513 handles this correctly for signals with optional chaining. Should use: task.metadata.workflow_id?.substring(0, 8) || 'unknown'

2. Inconsistent array mutation (logfmt_to_gantt.ts:188, 194)
Using entries.splice(0, entries.length, ...entries.filter(...)) is unusual. Consider more idiomatic approaches.

3. Non-unique task keys (logfmt_to_gantt.ts:303)
Using timestamp in key could cause collisions if operations start at the same millisecond. Consider adding a counter.

4. Inefficient operation matching (logfmt_to_gantt.ts:317-323)
Iterating through all operations to find a match could match the wrong operation if multiple with same name are running.

Performance Considerations

• Large file handling: readFileSync loads entire file into memory. Consider streaming for large logs or add memory warning
• Quadratic complexity (debug_mermaid.ts:38): Math.max with spread and filter creates unnecessary intermediate arrays

Best Practices

• Hard-coded /tmp paths should be configurable
• Missing error handling around file operations
• metadata: Record<string, any> uses any - consider unknown or specific types
• service field defined but never used
• Magic numbers like 50 should be constants

Recommendations

1. Add null safety checks for workflow_id access (critical)
2. Add basic error handling around file I/O
3. Document expected log format
4. Consider --help flag support

Summary: Useful debugging tools with clean structure. Main concerns are null safety (critical) and large file handling. Recommend approval with suggested improvements for null safety.

[claude]

Code Review for PR #3467: Add Debug Scripts

Thanks for adding these debug utilities! Overall, these are well-structured and useful tools. Here are my findings:

✅ Strengths

• Well-documented with clear usage instructions
• Good TypeScript typing with proper interfaces
• Useful features like --split-by-workflow and time filtering
• Good file organization moving decode_audit_entry.js to scripts/debug/

🐛 Issues Found

1. Missing Error Handling (debug_mermaid.ts:11-12, logfmt_to_gantt.ts:157)
File operations lack try-catch blocks. If files don't exist, scripts crash ungracefully.

2. Potential -Infinity Bug (debug_mermaid.ts:38)
Math.max(...sectionStarts.filter(s => s < 10)) returns -Infinity if filter returns empty array.

3. Performance: Inefficient Array Mutation (logfmt_to_gantt.ts:188-191)
Using splice(0, length, ...filter()) creates two array copies in memory - inefficient for large logs.

4. Performance: Regex Recreation (logfmt_to_gantt.ts:51)
Regex is recreated on every parseLogfmt call. Should be defined as module-level constant.

5. Type Safety (logfmt_to_gantt.ts:505, 508)
task.metadata.workflow_id.substring(0, 8) can throw if workflow_id is undefined. Use optional chaining.

6. Edge Case (logfmt_to_gantt.ts:225, 391)
If all entries filtered out by time filter, accessing entries[0].ts throws. Empty check is at line 171 but should be after time filtering (line 208).

7. Code Duplication
Duration calculation logic (lines 440-452 and 487-500) is duplicated. Extract to helper function.

💡 Suggestions

• Add --help flag for both scripts
• Extract hardcoded paths to constants
• Add package.json improvements: remove unused main field, add private: true, populate description
• Consider adding example log files in scripts/debug/examples/

🔒 Security: ✅ Excellent

No injection risks, no sensitive data handling issues.

✨ Assessment

Quality: ⭐⭐⭐⭐☆ | Maintainability: ⭐⭐⭐⭐☆ | Security: ⭐⭐⭐⭐⭐

Issues are mostly about robustness and performance, not critical bugs. Great work!

[claude]

Code Review for PR #3467: Add Debug Scripts

Overview

This PR adds useful debugging utilities for analyzing Rivet engine logs. The code is well-structured and functional, but there are several areas for improvement.

Strengths

1. Valuable tooling - These scripts provide practical debugging capabilities for workflow visualization and log analysis
2. Good separation of concerns - Each script has a clear, focused purpose
3. Comprehensive parsing - The logfmt parser handles various log entry types workflows activities signals operations
4. Sub-millisecond precision - Nice attention to detail with fractional second tracking
5. Flexible filtering - Time-based filtering and workflow splitting options are useful features

[claude]

Issues and Recommendations

1. Type Safety Issues

In logfmt_to_gantt.ts line 560 and debug_mermaid.ts line 97 the CommonJS pattern wont work properly in TypeScript ESM context:

if (require.main === module) {
    main();
}

Recommendation: Since these are scripts with tsx shebangs simply call main directly at the bottom of the file.

2. Error Handling Gaps

File I/O operations lack error handling throughout both scripts. For example in debug_mermaid.ts lines 11-12:

const content = readFileSync(inputFile, 'utf-8');

Recommendation: Wrap file operations in try-catch blocks to handle missing files or permission errors gracefully.

[claude]

3. Potential Bugs

a) Confusing array mutation pattern in logfmt_to_gantt.ts lines 185-199:

entries.splice(0, entries.length, ...entries.filter(entry => { }));

This creates a temporary copy of the entire array which is memory-intensive. Better approach:

const filtered = entries.filter(entry => { });
entries.length = 0;
entries.push(...filtered);

b) Hardcoded placeholder date at logfmt_to_gantt.ts line 121:

startTimeFilter = new Date('2000-01-01T' + timeStr + 'Z');

Using a magic date for time-of-day comparisons is fragile. Extract to a named constant with clear explanation.

[claude]

4. Performance Considerations

a) Inefficient operation matching at logfmt_to_gantt.ts lines 324-332:

for (const [k, task] of operationTasks.entries()) {
    if (k.startsWith(entry.operation_name) && !task.end) {
        task.end = entry.ts;
        break;
    }
}

This O(n) linear search happens for every operation response. Consider tracking active operations separately with a Map.

b) Memory usage for large files: Both scripts use readFileSync which loads entire files into memory. For large log files over 100MB consider streaming line-by-line using readline.

[claude]

5. Code Style and Conventions

a) Magic numbers without explanation at various lines:

.substring(0, 50);     // Line 95
.substring(0, 8);      // Line 405
if (duration > 0.01)   // Line 420

Extract as named constants:

const MAX_MERMAID_NAME_LENGTH = 50;
const WORKFLOW_ID_DISPLAY_LENGTH = 8;
const MIN_DURATION_TO_DISPLAY_MS = 0.01;

b) Inconsistent quote style: Mix of single and double quotes throughout. Pick one style and stick to it.

c) Missing documentation: Key functions like parseLogfmt sanitizeForMermaid and formatDuration would benefit from JSDoc comments.

[claude]

6. Security and Testing

Security considerations:

• Path validation: User-provided paths are used directly without validation. Consider basic validation to prevent directory traversal attacks though this is low severity for debug scripts.
• The custom stripAnsi function is fine but consider using the battle-tested strip-ansi npm package for completeness.

Test coverage:

• No tests provided. For utility scripts like these consider adding unit tests for parsing functions parseLogfmt sanitizeForMermaid formatDuration plus integration tests with sample log files and edge case handling.

[claude]

Prioritized Recommendations

High Priority - blocking:

1. Fix or remove the require.main === module pattern for ESM compatibility
2. Add try-catch blocks around all file I/O operations
3. Add a brief comment documenting the expected log format

Medium Priority - nice to have:
4. Refactor the array splice pattern for clarity
5. Extract magic numbers to named constants
6. Add JSDoc comments to public functions
7. Optimize the operation matching loop

Low Priority - polish:
8. Add unit tests for core parsing logic
9. Standardize quote style
10. Consider streaming for large files
11. Add path validation

Conclusion

These are valuable debugging utilities that will help with workflow analysis. The core logic is solid and well-thought-out. The main issues are around error handling robustness and some TypeScript Node.js compatibility concerns.

Recommendation: Request changes for high-priority items especially error handling and the require.main pattern then approve after those are addressed.

[claude]

Code Review

Overview

This PR adds helpful debugging scripts for analyzing Rivet Engine logs and visualizing execution timelines. The additions are well-structured and provide valuable tooling for development and debugging workflows.

Positive Aspects ✅

1. Well-organized structure: Moving decode_audit_entry.js into a dedicated scripts/debug/ directory improves organization
2. Comprehensive tooling: The two new TypeScript scripts provide valuable debugging capabilities:
   • logfmt_to_gantt.ts - Parses logs and generates Mermaid Gantt charts
   • debug_mermaid.ts - Binary search tool for debugging problematic Mermaid charts
3. Good documentation: Scripts include usage instructions in comments
4. Proper TypeScript setup: Includes appropriate configuration files (tsconfig.json, turbo.json, package.json)

Issues & Recommendations

1. File Reading Error Handling ⚠️

In both scripts, file reads lack error handling:

// logfmt_to_gantt.ts:145
const content = readFileSync(inputFile, 'utf-8');

// debug_mermaid.ts:11
const content = readFileSync(inputFile, 'utf-8');

Recommendation: Add try-catch blocks to provide user-friendly error messages:

try {
  const content = readFileSync(inputFile, 'utf-8');
} catch (error) {
  console.error(`Failed to read file ${inputFile}: ${error.message}`);
  process.exit(1);
}

2. Date Parsing Without Validation ⚠️

logfmt_to_gantt.ts:57-76 - The parseLogfmt function parses dates but doesn't validate them:

entry.ts = new Date(value);

If the timestamp is malformed, this creates an Invalid Date object that may cause issues downstream.

Recommendation: Validate dates after parsing:

const date = new Date(value);
if (isNaN(date.getTime())) {
  console.warn(`Invalid timestamp in log entry: ${value}`);
  return null;
}
entry.ts = date;

3. Array Mutation Pattern 💡

logfmt_to_gantt.ts:184-195 uses an unusual array mutation pattern:

entries.splice(0, entries.length, ...entries.filter(entry => {
  // filtering logic
}));

Recommendation: Use standard reassignment for clarity:

const filtered = entries.filter(entry => {
  // filtering logic
});
entries.length = 0;
entries.push(...filtered);
// Or simply: entries = filtered; if you can reassign the variable

4. Hardcoded File Paths 💡

Default paths are hardcoded in multiple places:

• logfmt_to_gantt.ts:144: /tmp/rivet-engine.log
• logfmt_to_gantt.ts:145: /tmp/rivet-engine-gantt.md
• debug_mermaid.ts:11: /tmp/rivet-engine-gantt.md

Recommendation: Consider using environment variables or a config file for default paths to make the scripts more flexible.

5. Package.json Version Mismatch 🔍

scripts/debug/package.json:3 sets version to 2.0.21, which seems arbitrary for a new debug tooling package.

Recommendation: Consider starting at 1.0.0 or aligning with the main project version.

6. Missing Type Safety 💡

The logfmt parser uses any types in the catch-all property:

[key: string]: any;

While this is practical for a debug script, consider documenting expected additional fields or using a more specific type if the log format is well-defined.

7. Memory Consideration 🔍

logfmt_to_gantt.ts:148 reads the entire log file into memory. For very large log files, this could be problematic.

Recommendation: Consider streaming for production use, though for debug scripts this is likely acceptable. Add a comment if there are expected file size limits.

Security Considerations

✅ No major security concerns - These are debug/dev scripts:

• Not part of production code
• File operations are limited to reading log files and writing markdown output
• No external network calls or dangerous operations
• No user-supplied code execution

Testing

❓ No tests included - For utility scripts like these, tests aren't strictly necessary, but consider adding:

• Sample log file fixtures for validation
• Unit tests for parsing functions
• Integration tests to ensure generated Mermaid syntax is valid

Performance Considerations

The scripts are generally efficient for their purpose:

• ✅ Single-pass log parsing
• ✅ Reasonable data structures (Maps for lookups)
• ✅ Sorting only happens once after all tasks are collected

Summary

This is a solid addition to the debugging toolset. The code is well-structured and functional. The main improvements would be:

1. Add error handling for file I/O operations
2. Validate date parsing
3. Simplify the array filtering pattern
4. Consider making file paths more configurable

Recommendation: ✅ Approve with minor suggestions - The issues noted are minor and don't block merging. They can be addressed in follow-up improvements if needed.

[claude]

PR Review: Debug Scripts Addition

Thanks for adding these debug utilities! Overall, this is a useful addition to the codebase for debugging and visualizing Rivet engine execution. Here's my detailed feedback:

Code Quality & Best Practices

Positive Points:

• Well-structured TypeScript with proper type definitions
• Clear function separation and single responsibility principle
• Good use of interfaces (LogEntry, Task) for type safety
• Comprehensive comment documentation explaining usage

Improvement Suggestions:

1. Error Handling (logfmt_to_gantt.ts):

   • Lines 117-135: Date parsing could fail with invalid input. Consider wrapping in try-catch:

   try {
     startTimeFilter = new Date(timeStr);
     if (isNaN(startTimeFilter.getTime())) {
       console.error(`Invalid start time: ${timeStr}`);
       process.exit(1);
     }
   } catch (e) {
     console.error(`Failed to parse start time: ${timeStr}`);
     process.exit(1);
   }

2. File I/O Error Handling:

   • Lines 157, 552: readFileSync and writeFileSync should have try-catch blocks to handle missing files or permission errors gracefully

3. Code Duplication:

   • Lines 440-452 and 488-500: Duration calculation logic is duplicated. Extract to a helper function:

   function calculateDuration(task: Task): number {
     if (task.type === 'signal' && task.metadata.is_recv && task.metadata.send_ts) {
       const sendTime = task.metadata.send_ts as Date;
       const sendFrac = task.metadata.send_frac as number;
       const durationMs = task.start.getTime() - sendTime.getTime();
       const durationFracSec = task.startFracSec - sendFrac;
       return durationMs + durationFracSec * 1000;
     }
     const durationMs = task.end!.getTime() - task.start.getTime();
     const durationFracSec = (task.endFracSec || 0) - task.startFracSec;
     return durationMs + durationFracSec * 1000;
   }

4. Type Safety:

   • Line 505, 508: task.metadata.workflow_id.substring(0, 8) could fail if workflow_id is undefined. Use optional chaining:

   const wfId = task.metadata.workflow_id?.substring(0, 8) || 'unknown';

Potential Bugs

1. Race Condition in Activity Tracking (line 294-298):

   • If multiple activities with the same name run concurrently at the same location/iteration, only the last "activity success" will be captured
   • Consider including a unique identifier (timestamp or counter) in the key

2. Operation Matching Logic (lines 317-323):

   • The current approach finds "most recent matching operation" by iterating through a Map, but Map iteration order isn't guaranteed to be insertion order for all operations
   • Consider using an array or explicit tracking of insertion order

3. Empty File Handling (debug_mermaid.ts line 38):

   • Math.max(...sectionStarts.filter(s => s < 10)) will return -Infinity if no sections found, causing unexpected behavior
   • Add validation: const filtered = sectionStarts.filter(s => s < 10); const maxIdx = filtered.length > 0 ? Math.max(...filtered) : 0;

4. Index Bounds (line 225):

   • const startTime = entries[0].ts; assumes entries is not empty, but this is checked at line 171. Good defensive programming!

Performance Considerations

1. Memory Usage (line 157-158):

   • Reading entire log file into memory with readFileSync could be problematic for very large log files
   • Consider streaming approach for production use:

   import { createReadStream } from 'fs';
   import { createInterface } from 'readline';

2. Array Operations (lines 188-199):

   • Using entries.splice(0, entries.length, ...entries.filter(...)) creates a new array then splices it back
   • More efficient: const filteredEntries = entries.filter(...); entries.length = 0; entries.push(...filteredEntries);
   • Or simply reassign: entries = entries.filter(...)

3. Map Iterations (line 317):

   • Iterating through entire operationTasks map to find a match is O(n) per operation
   • Consider a more efficient data structure or separate tracking for open operations

Security Concerns

1. Path Traversal (lines 145-146):

   • User-supplied file paths are used directly without validation
   • While this is a debug script, consider adding basic path validation to prevent accidental writes outside intended directories

2. Input Sanitization:

   • The sanitizeForMermaid function (lines 87-96) is good, but consider documenting what characters are dangerous in Mermaid syntax
   • The regex patterns could potentially cause ReDoS with malicious input, though unlikely in this context

Test Coverage

Missing Tests:

• No tests are included for these scripts
• Consider adding:
  • Unit tests for parsing functions (parseLogfmt, sanitizeForMermaid, formatDuration)
  • Integration tests with sample log files
  • Edge case tests (empty files, malformed entries, timestamp edge cases)

Test Recommendations:

// Example test cases to consider
describe('parseLogfmt', () => {
  it('should parse valid logfmt line', () => { /* ... */ });
  it('should handle quoted values with spaces', () => { /* ... */ });
  it('should return null for invalid lines', () => { /* ... */ });
  it('should strip ANSI color codes', () => { /* ... */ });
});

Additional Suggestions

1. CLI Argument Parsing:

   • Consider using a proper CLI argument parser like commander or yargs for better UX
   • Would make the complex filtering logic in lines 137-143 cleaner

2. Configuration:

   • Hardcoded paths (/tmp/rivet-engine.log) could be configurable
   • Consider adding a config file or environment variables

3. Documentation:

   • Add README.md in scripts/debug/ explaining:
     • What each script does
     • Example usage scenarios
     • Sample output
     • Common troubleshooting

4. Package.json (lines added):

   • Missing actual dependencies (tsx is used as shebang but not listed)
   • Consider adding: "tsx": "^4.0.0" to devDependencies

Summary

Strengths:

• Clear, readable code with good structure
• Useful debugging functionality for complex workflow analysis
• Proper TypeScript typing

Priority Fixes:

1. Add error handling for file I/O operations
2. Extract duplicated duration calculation logic
3. Add null safety for workflow_id access
4. Fix empty array handling in debug_mermaid.ts

Nice to Have:

• Add basic test coverage
• Improve memory efficiency for large files
• Add proper CLI argument parsing
• Document usage in README

This is solid debug tooling! With the suggested improvements, it'll be even more robust and maintainable.

[claude]

PR Review: Debug Scripts

This PR adds useful debug scripts for analyzing Rivet Engine logs and Mermaid diagrams. Overall, the code is well-structured and functional for debug tooling. Here are my observations and recommendations:

Strengths

✅ Good utility value - These scripts solve real debugging needs (log visualization and Mermaid troubleshooting)
✅ Clear documentation - Scripts include usage comments and helpful console output
✅ Robust parsing - The logfmt parser handles ANSI colors, quoted values, and sub-millisecond precision
✅ Flexible filtering - The logfmt_to_gantt.ts supports multiple filter options (--split-by-workflow, --start-time, --end-time)

Issues & Recommendations

1. Potential Null Reference Bug 🐛

Location: logfmt_to_gantt.ts:505, logfmt_to_gantt.ts:508

const wfId = task.metadata.workflow_id.substring(0, 8);

Issue: When task.type === 'workflow' or 'activity', workflow_id might be undefined, causing a runtime error. Line 513 already handles this correctly with optional chaining.

Fix:

const wfId = task.metadata.workflow_id?.substring(0, 8) || 'unknown';

2. Code Duplication

Locations: logfmt_to_gantt.ts:440-452 and logfmt_to_gantt.ts:488-500

The duration calculation logic is duplicated. Consider extracting it to a helper function:

function calculateTaskDuration(task: Task): number {
  if (task.type === 'signal' && task.metadata.is_recv && task.metadata.send_ts) {
    const sendTime = task.metadata.send_ts as Date;
    const sendFrac = task.metadata.send_frac as number;
    const durationMs = task.start.getTime() - sendTime.getTime();
    const durationFracSec = task.startFracSec - sendFrac;
    return durationMs + durationFracSec * 1000;
  }
  const durationMs = task.end\!.getTime() - task.start.getTime();
  const durationFracSec = (task.endFracSec || 0) - task.startFracSec;
  return durationMs + durationFracSec * 1000;
}

3. Regex Parsing Limitation

Location: logfmt_to_gantt.ts:51

const regex = /(\w+)=(?:"([^"]*)"|(\S+))/g;

Issue: This regex won't handle:

• Escaped quotes inside quoted values (key="value with \"quotes\"")
• Values with spaces that aren't quoted
• Empty string values

For debug scripts, this is probably acceptable, but worth documenting as a known limitation.

4. Type Safety Concern

Location: logfmt_to_gantt.ts:24

[key: string]: any;

Using any reduces type safety. Consider using unknown or a more specific union type for better type safety.

5. Package.json Metadata 📦

Location: scripts/debug/package.json:4-5

"description": "",
"main": "index.js",

These fields are empty/incorrect. Consider:

• Adding a proper description: "Debug scripts for Rivet Engine log analysis"
• Removing or correcting main field since this isn't a library

6. Minor: Hardcoded Paths

Locations: Multiple files use /tmp/ paths

While fine for debug scripts, consider documenting this in the file comments or making paths configurable via environment variables for better cross-platform support (Windows doesn't use /tmp/).

Security

✅ No security concerns - These are development/debug tools with no external network access or sensitive data handling
✅ File operations are limited to reading log files and writing output files

Testing

⚠️ No tests included - For debug scripts this is acceptable, but consider:

• Adding example log files in a test fixtures directory
• Documenting expected input/output formats

Performance

✅ Efficient for debug tooling - Using Maps for lookups, single-pass parsing
⚠️ Could be memory-intensive for very large log files (loads entire file into memory)

Suggested Minor Improvements

1. Error handling - Add try-catch around file operations with more descriptive error messages
2. Input validation - Validate file existence before reading
3. Progress indicators - For large log files, show progress during parsing
4. Export formats - Consider supporting JSON output alongside Mermaid

Verdict

This is good pragmatic debug tooling. The issues identified are minor and don't prevent merging, but fixing the null reference bug on lines 505/508 would prevent potential runtime errors.

Recommendation: ✅ Approve with suggestion to fix the workflow_id null reference bug

[graphite-app]

Merge activity

• Nov 21, 2:40 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Nov 21, 2:42 AM UTC: CI is running for this pull request on a draft pull request (#3515) due to your merge queue CI optimization settings.
• Nov 21, 2:43 AM UTC: Merged by the Graphite merge queue via draft PR: #3515.