diagnostics

Imported from xdkp/oh-my-claudecode (src/tools/diagnostics/AGENTS.md). Install upstream with npx skills add xdkp/oh-my-claudecode --skill diagnostics. Copyright stays with the author.

diagnostics

Project-level diagnostics via TypeScript compiler (tsc) or LSP aggregation.

Purpose

This directory provides project-wide type checking and error detection:

• Primary: tsc --noEmit for fast, comprehensive TypeScript checking
• Fallback: LSP iteration when tsc is unavailable
• Powers the lsp_diagnostics_directory tool

Key Files

For AI Agents

Working In This Directory

Strategy Selection

// Auto-select best strategy
const result = await runDirectoryDiagnostics(directory, 'auto');

// Force specific strategy
const tscResult = await runDirectoryDiagnostics(directory, 'tsc');
const lspResult = await runDirectoryDiagnostics(directory, 'lsp');

Strategy logic:

if (strategy === 'auto') {
  useStrategy = hasTsconfig ? 'tsc' : 'lsp';
}

TSC Runner

Uses tsc --noEmit --pretty false for parseable output:

// Output format: file(line,col): error TS1234: message
const regex = /^(.+)\((\d+),(\d+)\):\s+(error|warning)\s+(TS\d+):\s+(.+)$/gm;

Advantages:

• Fast (single process)
• Comprehensive (full project type checking)
• Accurate (uses tsconfig.json)

LSP Aggregator

Fallback that iterates through files:

for (const file of files) {
  const client = await lspClientManager.getClientForFile(file);
  await client.openDocument(file);
  await sleep(LSP_DIAGNOSTICS_WAIT_MS); // 300ms for server processing
  const diagnostics = client.getDiagnostics(file);
}

Use when:

• No tsconfig.json
• Multi-language project
• Need per-file incremental checking

Common Patterns

Result format:

interface DirectoryDiagnosticResult {
  strategy: 'tsc' | 'lsp';
  success: boolean;
  errorCount: number;
  warningCount: number;
  diagnostics: string;  // Formatted output
  summary: string;      // Human-readable summary
}

Testing Requirements

# Test with a TypeScript project
npm test -- --grep "diagnostics"

Dependencies

Internal

• ../lsp/ - LSP client for aggregation mode

External

Performance Comparison

Recommendation: Always prefer tsc for TypeScript projects.