Copilot instructions

1---
2applyTo: "src/parsers/**/*.ts"
3---
4 
5# Parser Review Guidelines
6 
7## Crash Safety (Critical)
8 
9- Parsers MUST NOT throw to the caller — each runs inside `Promise.allSettled` and an uncaught error silently drops that tool's sessions from the index
10- Wrap JSON.parse calls and file-read loops in try-catch with an empty catch block to silently skip malformed data
11 
12```typescript
13// Good — CLI continues if one line is malformed
14for (const line of lines) {
15  try {
16    const data = JSON.parse(line);
17    // process...
18  } catch {
19    // Skip malformed line silently
20  }
21}
22 
23// Bad — one bad line crashes the entire parser
24for (const line of lines) {
25  const data = JSON.parse(line);
26}
27```
28 
29## Required Exports
30 
31Each parser file must export exactly two functions:
32 
33- `parse<Tool>Sessions(): Promise<UnifiedSession[]>` — file discovery and metadata extraction
34- `extract<Tool>Context(session: UnifiedSession, config?: VerbosityConfig): Promise<SessionContext>` — full conversation and tool activity extraction
35 
36Both must be registered in `src/parsers/registry.ts` with all `ToolAdapter` fields populated.
37 
38## JSONL Streaming
39 
40- Stream JSONL with helpers from `src/utils/jsonl.ts` (`readJsonlFile`, `scanJsonlHead`) when applicable
41- Never use `fs.readFileSync` for session files
42- Keep only the last ~10 messages in `recentMessages` — do not accumulate the entire conversation
43 
44## Tool Summarizer
45 
46- Always use `SummaryCollector` from `src/utils/tool-summarizer.ts` — never build `ToolUsageSummary[]` arrays manually
47- Call `collector.add(category, summary, filePath?, isWrite?)` for each tool invocation
48 
49## Shared Helpers
50 
51- Import `cleanSummary`, `extractRepoFromCwd`, `homeDir` from `src/utils/parser-helpers.ts`
52- Do not duplicate these utilities in individual parser files
53 
54## New Tool Checklist
55 
56Adding a new tool requires ALL five of:
57 
581. Parser file `src/parsers/<tool>.ts` exporting both required functions
592. Registry entry in `src/parsers/registry.ts` with all `ToolAdapter` fields
603. Type update in `src/types/tool-names.ts` — add to `SessionSource` union and `TOOL_NAMES` array
614. Fixture factory in `src/__tests__/fixtures/index.ts`
625. Conversion tests in `src/__tests__/unit-conversions.test.ts` for all N-1 paths in each direction
63