Skip to content

faouzi96/md-code-assist / .github/skills/diagnostic-mapping

diagnostic-mapping

Unverified

Expertise in mapping diagnostics from virtual documents back to original Markdown positions. Use when working on virtual document providers, LSP integration, diagnostic position translation, or inline error display.

Diagnostic Mapping

When to Use This Skill

  • Creating virtual documents for code blocks
  • Mapping LSP diagnostics to Markdown positions
  • Handling position offsets between documents
  • Integrating with VS Code's diagnostic system
  • Displaying inline errors in Markdown files

Architecture Overview

┌─────────────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│   Markdown File     │────▶│  Virtual Document    │────▶│  Language Server │
│   (source.md)       │     │  (virtual://...)     │     │  (LSP)           │
└─────────────────────┘     └──────────────────────┘     └─────────────────┘
         ▲                                                        │
         │                                                        │
         │              ┌──────────────────────┐                  │
         └──────────────│  Diagnostic Mapper   │◀─────────────────┘
                        │  (position mapping)  │    Diagnostics
                        └──────────────────────┘

Virtual Document Provider

import * as vscode from 'vscode';

interface VirtualDocument {
  uri: vscode.Uri;
  languageId: string;
  content: string;
  sourceUri: vscode.Uri;
  codeBlock: CodeBlock;
}

const virtualDocuments = new Map<string, VirtualDocument>();

export class VirtualDocumentProvider implements vscode.TextDocumentContentProvider {
  private _onDidChange = new vscode.EventEmitter<vscode.Uri>();
  readonly onDidChange = this._onDidChange.event;

  provideTextDocumentContent(uri: vscode.Uri): string {
    const doc = virtualDocuments.get(uri.toString());
    return doc?.content ?? '';
  }

  createVirtualDocument(
    sourceUri: vscode.Uri,
    codeBlock: CodeBlock,
    index: number
  ): VirtualDocument {
    const virtualUri = vscode.Uri.parse(
      `md-code-assist://virtual/${sourceUri.fsPath}/${index}.${codeBlock.language}`
    );

    const doc: VirtualDocument = {
      uri: virtualUri,
      languageId: codeBlock.language!,
      content: codeBlock.code,
      sourceUri,
      codeBlock,
    };

    virtualDocuments.set(virtualUri.toString(), doc);
    this._onDidChange.fire(virtualUri);

    return doc;
  }

  updateVirtualDocument(uri: vscode.Uri, content: string): void {
    const doc = virtualDocuments.get(uri.toString());
    if (doc) {
      doc.content = content;
      this._onDidChange.fire(uri);
    }
  }

  deleteVirtualDocument(uri: vscode.Uri): void {
    virtualDocuments.delete(uri.toString());
  }

  getVirtualDocument(uri: vscode.Uri): VirtualDocument | undefined {
    return virtualDocuments.get(uri.toString());
  }
}

Position Mapping

Understanding the Offset

Line 1: # Header
Line 2:
Line 3: ```javascript     ← codeBlock.startLine (fence)
Line 4: const x = 1;      ← First line of code (startLine + 1)
Line 5: const y = 2;      ← Second line of code (startLine + 2)
Line 6: ```               ← codeBlock.endLine (fence)
Line 7:
// Virtual document (0-indexed):
// Line 0: const x = 1;
// Line 1: const y = 2;

// Mapping formula:
// markdownLine = codeBlock.startLine + virtualLine + 1
// (startLine is the fence, +1 to get to first code line)

Diagnostic Mapper Implementation

import * as vscode from 'vscode';

export interface MappedDiagnostic {
  original: vscode.Diagnostic;
  mappedRange: vscode.Range;
  sourceUri: vscode.Uri;
}

export class DiagnosticMapper {
  /**
   * Map a diagnostic from virtual document coordinates
   * to Markdown document coordinates
   */
  mapDiagnostic(
    diagnostic: vscode.Diagnostic,
    virtualDoc: VirtualDocument
  ): MappedDiagnostic {
    const { codeBlock } = virtualDoc;
    const fenceLine = codeBlock.startLine; // 0-indexed

    // Map the range
    const mappedRange = new vscode.Range(
      this.mapPosition(diagnostic.range.start, fenceLine),
      this.mapPosition(diagnostic.range.end, fenceLine)
    );

    return {
      original: diagnostic,
      mappedRange,
      sourceUri: virtualDoc.sourceUri,
    };
  }

  private mapPosition(
    position: vscode.Position,
    fenceLine: number
  ): vscode.Position {
    // Virtual line 0 = Markdown line (fenceLine + 1)
    const markdownLine = fenceLine + position.line + 1;
    
    // Column stays the same (code block content is not indented in virtual doc)
    // But if the code block itself is indented, we'd need to add that offset
    const markdownColumn = position.character;

    return new vscode.Position(markdownLine, markdownColumn);
  }

  /**
   * Map multiple diagnostics for a code block
   */
  mapDiagnostics(
    diagnostics: vscode.Diagnostic[],
    virtualDoc: VirtualDocument
  ): MappedDiagnostic[] {
    return diagnostics.map((d) => this.mapDiagnostic(d, virtualDoc));
  }
}

Diagnostic Manager

import * as vscode from 'vscode';

export class DiagnosticManager {
  private collection: vscode.DiagnosticCollection;
  private mapper: DiagnosticMapper;
  private documentDiagnostics = new Map<string, vscode.Diagnostic[]>();

  constructor() {
    this.collection = vscode.languages.createDiagnosticCollection('mdCodeAssist');
    this.mapper = new DiagnosticMapper();
  }

  /**
   * Update diagnostics for a Markdown document
   */
  updateDiagnostics(
    markdownUri: vscode.Uri,
    virtualDocs: VirtualDocument[],
    diagnosticsPerBlock: Map<string, vscode.Diagnostic[]>
  ): void {
    const allMappedDiagnostics: vscode.Diagnostic[] = [];

    for (const virtualDoc of virtualDocs) {
      const blockDiagnostics = diagnosticsPerBlock.get(virtualDoc.uri.toString());
      if (!blockDiagnostics) continue;

      const mapped = this.mapper.mapDiagnostics(blockDiagnostics, virtualDoc);
      
      for (const { original, mappedRange } of mapped) {
        allMappedDiagnostics.push(
          new vscode.Diagnostic(
            mappedRange,
            original.message,
            original.severity
          )
        );
      }
    }

    this.collection.set(markdownUri, allMappedDiagnostics);
    this.documentDiagnostics.set(markdownUri.toString(), allMappedDiagnostics);
  }

  /**
   * Clear diagnostics for a document
   */
  clearDiagnostics(uri: vscode.Uri): void {
    this.collection.delete(uri);
    this.documentDiagnostics.delete(uri.toString());
  }

  dispose(): void {
    this.collection.dispose();
  }
}

Handling Indented Code Blocks

- List item:
  ```javascript
  const x = 1;
  ```
interface CodeBlock {
  // ... other fields
  indentation: number; // Number of spaces before the fence
}

private mapPosition(
  position: vscode.Position,
  fenceLine: number,
  indentation: number
): vscode.Position {
  const markdownLine = fenceLine + position.line + 1;
  // Add indentation offset to column
  const markdownColumn = position.character + indentation;
  return new vscode.Position(markdownLine, markdownColumn);
}

Triggering Diagnostics

export class DiagnosticTrigger {
  private debounceTimer: NodeJS.Timeout | undefined;
  private readonly debounceMs = 500;

  constructor(
    private virtualDocProvider: VirtualDocumentProvider,
    private diagnosticManager: DiagnosticManager
  ) {}

  /**
   * Trigger diagnostic refresh for a Markdown document
   */
  triggerDiagnostics(document: vscode.TextDocument): void {
    if (document.languageId !== 'markdown') return;

    // Debounce to avoid excessive processing
    if (this.debounceTimer) {
      clearTimeout(this.debounceTimer);
    }

    this.debounceTimer = setTimeout(() => {
      this.runDiagnostics(document);
    }, this.debounceMs);
  }

  private async runDiagnostics(document: vscode.TextDocument): Promise<void> {
    // 1. Parse Markdown and extract code blocks
    const codeBlocks = extractCodeBlocks(document.getText());

    // 2. Create/update virtual documents
    const virtualDocs = codeBlocks
      .filter((block) => block.language)
      .map((block, index) =>
        this.virtualDocProvider.createVirtualDocument(
          document.uri,
          block,
          index
        )
      );

    // 3. Request diagnostics from language services
    const diagnosticsPerBlock = await this.collectDiagnostics(virtualDocs);

    // 4. Map and display
    this.diagnosticManager.updateDiagnostics(
      document.uri,
      virtualDocs,
      diagnosticsPerBlock
    );
  }

  private async collectDiagnostics(
    virtualDocs: VirtualDocument[]
  ): Promise<Map<string, vscode.Diagnostic[]>> {
    const result = new Map<string, vscode.Diagnostic[]>();

    for (const doc of virtualDocs) {
      // Open the virtual document to trigger language services
      const textDoc = await vscode.workspace.openTextDocument(doc.uri);
      
      // Get diagnostics (may need to wait for language server)
      const diagnostics = vscode.languages.getDiagnostics(doc.uri);
      result.set(doc.uri.toString(), diagnostics);
    }

    return result;
  }
}

Common Issues

IssueCauseSolution
Off-by-one line errorsFence line not accounted forAdd +1 when mapping from virtual to Markdown
Wrong column positionsIndented code blocksTrack and add indentation offset
Stale diagnosticsDocument changedClear and re-run on onDidChangeTextDocument
Missing diagnosticsLanguage server not activatedEnsure language extension is installed and activated
Duplicate diagnosticsMultiple virtual docs for same blockUse unique URIs per code block
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall