AGENTS.md

1<!-- Parent: ../AGENTS.md -->
2<!-- Generated: 2026-01-28 | Updated: 2026-01-28 -->
3 
4# diagnostics
5 
6Project-level diagnostics via TypeScript compiler (tsc) or LSP aggregation.
7 
8## Purpose
9 
10This directory provides project-wide type checking and error detection:
11- **Primary**: `tsc --noEmit` for fast, comprehensive TypeScript checking
12- **Fallback**: LSP iteration when tsc is unavailable
13- Powers the `lsp_diagnostics_directory` tool
14 
15## Key Files
16 
17| File | Description |
18|------|-------------|
19| `index.ts` | Main entry - `runDirectoryDiagnostics()` with strategy selection |
20| `tsc-runner.ts` | TypeScript compiler runner - parses `tsc --noEmit` output |
21| `lsp-aggregator.ts` | LSP fallback - iterates files and collects diagnostics |
22 
23## For AI Agents
24 
25### Working In This Directory
26 
27#### Strategy Selection
28 
29```typescript
30// Auto-select best strategy
31const result = await runDirectoryDiagnostics(directory, 'auto');
32 
33// Force specific strategy
34const tscResult = await runDirectoryDiagnostics(directory, 'tsc');
35const lspResult = await runDirectoryDiagnostics(directory, 'lsp');
36```
37 
38**Strategy logic:**
39```typescript
40if (strategy === 'auto') {
41  useStrategy = hasTsconfig ? 'tsc' : 'lsp';
42}
43```
44 
45#### TSC Runner
46 
47Uses `tsc --noEmit --pretty false` for parseable output:
48```typescript
49// Output format: file(line,col): error TS1234: message
50const regex = /^(.+)\((\d+),(\d+)\):\s+(error|warning)\s+(TS\d+):\s+(.+)$/gm;
51```
52 
53**Advantages:**
54- Fast (single process)
55- Comprehensive (full project type checking)
56- Accurate (uses tsconfig.json)
57 
58#### LSP Aggregator
59 
60Fallback that iterates through files:
61```typescript
62for (const file of files) {
63  const client = await lspClientManager.getClientForFile(file);
64  await client.openDocument(file);
65  await sleep(LSP_DIAGNOSTICS_WAIT_MS); // 300ms for server processing
66  const diagnostics = client.getDiagnostics(file);
67}
68```
69 
70**Use when:**
71- No tsconfig.json
72- Multi-language project
73- Need per-file incremental checking
74 
75### Common Patterns
76 
77**Result format:**
78```typescript
79interface DirectoryDiagnosticResult {
80  strategy: 'tsc' | 'lsp';
81  success: boolean;
82  errorCount: number;
83  warningCount: number;
84  diagnostics: string;  // Formatted output
85  summary: string;      // Human-readable summary
86}
87```
88 
89### Testing Requirements
90 
91```bash
92# Test with a TypeScript project
93npm test -- --grep &quot;diagnostics&quot;
94```
95 
96## Dependencies
97 
98### Internal
99- `../lsp/` - LSP client for aggregation mode
100 
101### External
102| Package | Purpose |
103|---------|---------|
104| `child_process` | Running tsc |
105| `fs`, `path` | File system operations |
106 
107## Performance Comparison
108 
109| Strategy | Speed | Accuracy | Requirements |
110|----------|-------|----------|--------------|
111| `tsc` | Fast (~1-5s) | High | tsconfig.json |
112| `lsp` | Slow (~0.3s/file) | Medium | Language server installed |
113 
114**Recommendation**: Always prefer `tsc` for TypeScript projects.
115 
116<!-- MANUAL: -->
117