Tooling for support-email log processing and triage

[jcschaff]

Summary

Adds a Python pipeline that turns a directory of forwarded VCell support emails (.eml containing embedded JSON error reports) into structured CSVs for spreadsheet-driven bug triage. Found one real concurrency bug already during initial use — see #1669, a separate PR fixing the bug this tooling uncovered.

What's in the box

• tools/parse_support_email.py — single Python script, batch-mode entry point. Emits four CSVs:
  • emails.csv — one row per email, with an incident_id that collapses resubmissions (users who hit "Send" repeatedly as their log grows produce multiple emails sharing a long log prefix; we hash the first 1024 chars and group by it).
  • traces.csv — one row per (email, stack-trace), with four cluster keys at decreasing granularity (top-5, top-2, top-1, innermost-VCell), plus parsed file/class/method, plus the full trace text for diagnosis.
  • file_pivot.csv — primary triage view, one row per innermost-VCell source file, with a code-presence check that grep's vcell-*/src/main/java to confirm whether the file/method still exists in the live tree.
  • version_pivot.csv — secondary, by signature.
• docs/support_emails/README.md — full pipeline documentation: input format, output schemas, design decisions, learnings (notably "absence of a bug in a newer version is not evidence of a fix at small N").
• docs/support_emails/.gitignore — excludes both raw .eml/.json inputs and the derived analysis CSVs (which carry the same user-submitted log content).
• .claude/commands/analyze-support-email.md — slash command for single-file analysis (preserved from initial WIP).

Design decisions

• Brace-balanced JSON extraction with string-state tracking. A naïve depth-counter fails when log content has literal {/}.
• Multiple cluster keys per trace. Top-5 is too strict (lambda numbering / AWT chains differ across submissions); innermost-VCell is the most useful headline. All four keys stored so re-clustering needs no re-parsing.
• Cluster by deepest cause, not outer wrapper. Caused by: chains are walked to find the actual throw site; otherwise traces wrapped by a catch-all (e.g. populateDataSymbolMetadata wrapping all math-mapping failures) all collapse into the wrapper file. The clustering fix landed mid-PR after this exact bug was caught — see commit Cluster traces by deepest cause, not outer wrapper.
• Code-presence verification. With small N and no systematic fixing culture, "absent in newer version" isn't evidence of a fix. Whether the file+method still exists in the current tree is a binary fact you can verify in seconds, and is a more reliable filter for "this cluster is worth investigating now."
• No raw email content in VCS. Reports include user identifiers, file paths, and model names. Both raw .eml and derived CSVs are gitignored.

Validation it works

Used on a 75-email corpus (4 software versions, all build_47 dominant). After resubmission collapse: 33 incidents across 50 distinct innermost-VCell source files. Top result was a thread-safety bug in InternalUnitDefinition.round (52 traces, 7 incidents) that's fixed in the companion PR #1669. The tool's value is mostly in producing that kind of focused, evidence-backed bug list from messy raw reports.

Workflow

# Drop new emails into docs/support_emails/, then:
python3 tools/parse_support_email.py --batch docs/support_emails \
  --out-emails        docs/support_emails/emails.csv \
  --out-traces        docs/support_emails/traces.csv \
  --out-file-pivot    docs/support_emails/file_pivot.csv \
  --out-version-pivot docs/support_emails/version_pivot.csv

Open file_pivot.csv first.

Test plan

• Parser handles 75-email corpus without parse failures
• Code-presence check correctly flags UserCancelException.java as method_missing (a stale code path the old wrapper-clustering hid)
• Sanity-check the README's documented columns match the output (skim review)
• Try dropping a fresh email after merge and re-running

Notes for review

• The branch starts from a WIP commit (Jim's original parser). Squashing on merge is fine; the three follow-up commits are logically distinct.
• Pure tooling/docs change; no Java touched. CI should be a no-op.

🤖 Generated with Claude Code