feat: add sarif_diff_by_commits tool for SARIF-to-git-diff correlation

Implements a new MCP tool that accepts a SARIF file path and git ref range,
partitions SARIF results into "new" vs "pre-existing" based on file-level
or line-level overlap with the git diff, and returns structured output for
triage workflows.

- Add diffSarifByCommits() pure utility in sarif-utils.ts with types
- Register sarif_diff_by_commits tool in sarif-tools.ts
- Add parseGitDiffOutput() helper for unified diff parsing
- Add 14 unit tests for diffSarifByCommits() utility
- Add 5 unit tests for sarif_diff_by_commits tool handler
- Update server-tools.md documentation
- Update tool registration count from 7 to 8

Closes #209

Agent-Logs-Url: https://github.com/advanced-security/codeql-development-mcp-server/sessions/8abb21bb-8877-4628-90da-36ffc8eeb742

Co-authored-by: data-douser <70299490+data-douser@users.noreply.github.com>

Author: Copilot

server/dist/codeql-development-mcp-server.js

@@ -87,6 +87,52 @@ export interface SarifDiffResult {
   unchangedRules: SarifRuleSummary[];
 }
 
+/** A file changed in a git diff, with optional line ranges. */
+export interface DiffFileEntry {
+  /** Changed line ranges (hunks). Empty array means file-level only. */
+  hunks: Array<{ startLine: number; lineCount: number }>;
+  /** File path relative to the repository root. */
+  path: string;
+}
+
+/** Granularity for matching SARIF results against a git diff. */
+export type DiffGranularity = 'file' | 'line';
+
+/** A SARIF result classified by its relationship to a git diff. */
+export interface ClassifiedResult {
+  /** File path of the primary location. */
+  file: string;
+  /** Line number of the primary location (if available). */
+  line?: number;
+  /** Original result index in the SARIF run. */
+  resultIndex: number;
+  /** The rule ID that produced this result. */
+  ruleId: string;
+}
+
+/** Result of partitioning SARIF results by git diff overlap. */
+export interface SarifDiffByCommitsResult {
+  /** Granularity used for the classification. */
+  granularity: DiffGranularity;
+  /** Results whose primary location is in a file (and optionally line range) touched by the diff. */
+  newResults: ClassifiedResult[];
+  /** Results whose primary location is NOT in a changed file/line. */
+  preExistingResults: ClassifiedResult[];
+  /** Summary statistics. */
+  summary: {
+    /** Number of files in the diff. */
+    diffFileCount: number;
+    /** Git ref range used. */
+    refRange: string;
+    /** Total SARIF results examined. */
+    totalResults: number;
+    /** Number of results classified as new. */
+    totalNew: number;
+    /** Number of results classified as pre-existing. */
+    totalPreExisting: number;
+  };
+}
+
 // ---------------------------------------------------------------------------
 // SARIF rule helpers
 // ---------------------------------------------------------------------------
@@ -812,3 +858,117 @@ export function findOverlappingAlerts(
 
   return overlaps;
 }
+
+// ---------------------------------------------------------------------------
+// SARIF-to-git-diff correlation
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a SARIF URI matches a diff file path.
+ *
+ * SARIF URIs may be absolute (`file:///…`) or relative (`src/db.js`),
+ * while git diff paths are always relative to the repo root (e.g. `src/db.js`).
+ * We normalize both and use suffix matching so that cross-environment
+ * comparisons work (e.g. CI vs local).
+ */
+function diffPathMatchesSarifUri(diffPath: string, sarifUri: string): boolean {
+  return urisMatch(diffPath, sarifUri);
+}
+
+/**
+ * Check whether a line number falls within any of a file's changed hunks.
+ */
+function lineInHunks(line: number, hunks: Array<{ startLine: number; lineCount: number }>): boolean {
+  for (const hunk of hunks) {
+    const hunkEnd = hunk.startLine + Math.max(hunk.lineCount - 1, 0);
+    if (line >= hunk.startLine && line <= hunkEnd) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Partition SARIF results into "new" (touched by the diff) vs "pre-existing"
+ * based on file-level or line-level overlap with a set of changed files.
+ *
+ * This is a pure function — git operations are the caller's responsibility.
+ *
+ * @param sarif       The SARIF document to classify.
+ * @param diffFiles   Files changed in the git diff (with optional hunk info).
+ * @param refRange    Git ref range string for metadata (e.g. "main..HEAD").
+ * @param granularity 'file' (default) matches any result in a changed file;
+ *                    'line' additionally checks that the result's primary
+ *                    location line falls within a changed hunk.
+ */
+export function diffSarifByCommits(
+  sarif: SarifDocument,
+  diffFiles: DiffFileEntry[],
+  refRange: string,
+  granularity: DiffGranularity = 'file',
+): SarifDiffByCommitsResult {
+  const results = sarif.runs[0]?.results ?? [];
+
+  const newResults: ClassifiedResult[] = [];
+  const preExistingResults: ClassifiedResult[] = [];
+
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+    const primaryLoc = result.locations?.[0]?.physicalLocation;
+    const uri = primaryLoc?.artifactLocation?.uri;
+
+    if (!uri) {
+      // No location info — classify as pre-existing (conservative)
+      preExistingResults.push({
+        file: '<unknown>',
+        resultIndex: i,
+        ruleId: result.ruleId,
+      });
+      continue;
+    }
+
+    const startLine = primaryLoc?.region?.startLine;
+
+    // Find matching diff file
+    const matchingDiff = diffFiles.find(df => diffPathMatchesSarifUri(df.path, uri));
+
+    let isNew = false;
+    if (matchingDiff) {
+      if (granularity === 'file') {
+        isNew = true;
+      } else if (startLine !== undefined && matchingDiff.hunks.length > 0) {
+        isNew = lineInHunks(startLine, matchingDiff.hunks);
+      } else if (matchingDiff.hunks.length === 0) {
+        // No hunk info available — treat as file-level match
+        isNew = true;
+      }
+      // else: line granularity requested but no startLine on the result → pre-existing
+    }
+
+    const classified: ClassifiedResult = {
+      file: normalizeUri(uri),
+      line: startLine,
+      resultIndex: i,
+      ruleId: result.ruleId,
+    };
+
+    if (isNew) {
+      newResults.push(classified);
+    } else {
+      preExistingResults.push(classified);
+    }
+  }
+
+  return {
+    granularity,
+    newResults,
+    preExistingResults,
+    summary: {
+      diffFileCount: diffFiles.length,
+      refRange,
+      totalNew: newResults.length,
+      totalPreExisting: preExistingResults.length,
+      totalResults: results.length,
+    },
+  };
+}

server/dist/codeql-development-mcp-server.js.map

@@ -60,13 +60,14 @@ This resource provides a complete reference of the default tools exposed by the
 
 ## SARIF Analysis Tools
 
-| Tool                     | Description                                                                                          |
-| ------------------------ | ---------------------------------------------------------------------------------------------------- |
-| `sarif_extract_rule`     | Extract all data for a specific rule from multi-rule SARIF. Returns a valid SARIF JSON subset        |
-| `sarif_list_rules`       | List all rules in a SARIF file with result counts, severity, precision, and tags                     |
-| `sarif_rule_to_markdown` | Convert per-rule SARIF data to markdown with Mermaid dataflow diagrams                               |
-| `sarif_compare_alerts`   | Compare code locations of two SARIF alerts for overlap (sink, source, any-location, full-path modes) |
-| `sarif_diff_runs`        | Diff two SARIF files to find added, removed, and changed rules/results across analysis runs          |
+| Tool                      | Description                                                                                          |
+| ------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `sarif_compare_alerts`    | Compare code locations of two SARIF alerts for overlap (sink, source, any-location, full-path modes) |
+| `sarif_diff_by_commits`   | Correlate SARIF results with a git diff to classify findings as "new" or "pre-existing"              |
+| `sarif_diff_runs`         | Diff two SARIF files to find added, removed, and changed rules/results across analysis runs          |
+| `sarif_extract_rule`      | Extract all data for a specific rule from multi-rule SARIF. Returns a valid SARIF JSON subset        |
+| `sarif_list_rules`        | List all rules in a SARIF file with result counts, severity, precision, and tags                     |
+| `sarif_rule_to_markdown`  | Convert per-rule SARIF data to markdown with Mermaid dataflow diagrams                               |
 
 ### `sarif_list_rules` Response Format
 
@@ -157,7 +158,8 @@ Each rule object:
 5. `sarif_rule_to_markdown` — generate markdown report with Mermaid dataflow diagrams
 6. `sarif_compare_alerts` — compare two alerts for location overlap
 7. `sarif_diff_runs` — diff two SARIF files to detect behavioral changes across runs
-8. `query_results_cache_compare` with `ruleId` — compare results across databases
+8. `sarif_diff_by_commits` — correlate SARIF results with git diff to triage new vs pre-existing
+9. `query_results_cache_compare` with `ruleId` — compare results across databases
 
 ## Tool Input Conventions
 

server/src/lib/sarif-utils.ts

@@ -11,12 +11,14 @@ import { z } from 'zod';
 import {
   computeFingerprintOverlap,
   computeLocationOverlap,
+  diffSarifByCommits,
   diffSarifRules,
   extractRuleFromSarif,
   findOverlappingAlerts,
   listSarifRules,
   sarifRuleToMarkdown,
 } from '../lib/sarif-utils';
+import type { DiffFileEntry, DiffGranularity } from '../lib/sarif-utils';
 import { sessionDataManager } from '../lib/session-data-manager';
 import type { SarifResult, SarifRule } from '../types/sarif';
 import type { SarifDocument } from '../types/sarif';
@@ -26,12 +28,13 @@ import { logger } from '../utils/logger';
  * Register all SARIF analysis tools with the MCP server.
  */
 export function registerSarifTools(server: McpServer): void {
-  registerSarifExtractRuleTool(server);
-  registerSarifListRulesTool(server);
-  registerSarifRuleToMarkdownTool(server);
   registerSarifCompareAlertsTool(server);
   registerSarifDeduplicateRulesTool(server);
+  registerSarifDiffByCommitsTool(server);
   registerSarifDiffRunsTool(server);
+  registerSarifExtractRuleTool(server);
+  registerSarifListRulesTool(server);
+  registerSarifRuleToMarkdownTool(server);
   registerSarifStoreTool(server);
 
   logger.info('Registered SARIF analysis tools');
@@ -316,6 +319,98 @@ function registerSarifCompareAlertsTool(server: McpServer): void {
   );
 }
 
+// ---------------------------------------------------------------------------
+// sarif_diff_by_commits
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the output of `git diff --unified=0 --diff-filter=ACMR --no-color`
+ * into structured DiffFileEntry objects with hunk information.
+ *
+ * The unified diff format marks file headers with `--- a/path` / `+++ b/path`
+ * and hunk headers with `@@ -oldStart,oldCount +newStart,newCount @@`.
+ * We extract the new-side ("+") start/count from each hunk header.
+ */
+function parseGitDiffOutput(diffOutput: string): DiffFileEntry[] {
+  const files: DiffFileEntry[] = [];
+  let currentFile: DiffFileEntry | null = null;
+
+  for (const line of diffOutput.split('\n')) {
+    // New file header: +++ b/path/to/file
+    if (line.startsWith('+++ b/')) {
+      if (currentFile) files.push(currentFile);
+      currentFile = { hunks: [], path: line.substring(6) };
+      continue;
+    }
+
+    // Hunk header: @@ -old +newStart,newCount @@  or  @@ -old +newStart @@
+    if (currentFile && line.startsWith('@@')) {
+      const match = line.match(/@@ [^ ]+ \+(\d+)(?:,(\d+))? @@/);
+      if (match) {
+        const startLine = parseInt(match[1], 10);
+        const lineCount = match[2] !== undefined ? parseInt(match[2], 10) : 1;
+        if (lineCount > 0) {
+          currentFile.hunks.push({ startLine, lineCount });
+        }
+      }
+    }
+  }
+  if (currentFile) files.push(currentFile);
+
+  return files;
+}
+
+function registerSarifDiffByCommitsTool(server: McpServer): void {
+  server.tool(
+    'sarif_diff_by_commits',
+    'Correlate SARIF results with a git diff to classify findings as "new" (introduced in the diff) or "pre-existing". Accepts a SARIF file and a git ref range (e.g. "main..HEAD"). Supports file-level or line-level granularity.',
+    {
+      cacheKey: z.string().optional().describe('Cache key to read SARIF from (alternative to sarifPath).'),
+      granularity: z.enum(['file', 'line']).optional().default('file')
+        .describe('Matching granularity: "file" classifies any result in a changed file as new; "line" additionally checks that the result line falls within a changed hunk. Default: "file".'),
+      refRange: z.string().describe('Git ref range for the diff (e.g. "main..HEAD", "abc123..def456"). Passed directly to `git diff`.'),
+      repoPath: z.string().optional().describe('Path to the git repository. Defaults to the current working directory.'),
+      sarifPath: z.string().optional().describe('Path to the SARIF file.'),
+    },
+    async ({ sarifPath, cacheKey, refRange, repoPath, granularity }) => {
+      // Load SARIF
+      const loaded = loadSarif({ sarifPath, cacheKey });
+      if (loaded.error) {
+        return { content: [{ type: 'text' as const, text: loaded.error }] };
+      }
+
+      // Run git diff to get changed files with hunk info
+      const { executeCLICommand } = await import('../lib/cli-executor');
+      const gitArgs = ['diff', '--unified=0', '--diff-filter=ACMR', '--no-color', refRange];
+      const gitResult = await executeCLICommand({
+        args: gitArgs,
+        command: 'git',
+        cwd: repoPath,
+      });
+
+      if (!gitResult.success) {
+        return {
+          content: [{
+            type: 'text' as const,
+            text: `git diff failed: ${gitResult.error ?? gitResult.stderr}`,
+          }],
+        };
+      }
+
+      const diffFiles = parseGitDiffOutput(gitResult.stdout);
+      const g = granularity as DiffGranularity;
+      const result = diffSarifByCommits(loaded.sarif!, diffFiles, refRange, g);
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify(result, null, 2),
+        }],
+      };
+    },
+  );
+}
+
 // ---------------------------------------------------------------------------
 // sarif_diff_runs
 // ---------------------------------------------------------------------------