[NEW PRIMITIVE] sarif_diff_by_commits — SARIF-to-git-diff correlation tool

[Copilot]

📝 Primitive Information

Primitive Details

• Type: Tool
• Name: sarif_diff_by_commits
• Domain: SARIF Analysis / Triage Workflows

⚠️ CRITICAL: PR SCOPE VALIDATION

✅ ALLOWED FILES:

• Server implementation files (server/src/**/*.ts)
• New primitive implementations (tools or resources)
• Updated registration files (server/src/tools/*.ts)
• Test files for the new primitive (server/test/**/*.ts)
• Documentation updates (README.md, server docs)
• Type definitions (server/src/types/*.ts)
• Supporting library files (server/src/lib/*.ts)
• Configuration files related to the primitive (package.json, tsconfig.json)
• Client integration test fixtures (client/integration-tests/**)
• Go test runner support (client/internal/testing/*.go)

🚫 FORBIDDEN FILES:

• Files unrelated to the MCP server implementation
• Temporary or test output files
• IDE configuration files
• Log files or debug output

🛑 MANDATORY PR VALIDATION CHECKLIST

• ONLY server implementation files are included
• NO temporary or output files are included
• NO unrelated configuration files are included
• ALL new functionality is properly tested

---

• Category: Code Quality, Triage Workflow

Primitive Metadata

• MCP Type: Tool (interactive)
• Input Schema: { sarifPath?, cacheKey?, refRange, repoPath?, granularity? }
• Output Format: SarifDiffByCommitsResult — partitioned results with summary statistics

🎯 Functionality Description

What This Primitive Does

Correlates SARIF analysis results with a git diff to classify each finding as "new" (introduced by the diff) or "pre-existing". Supports file-level and line-level granularity.

Previously, triaging SARIF results by branch required manually running git diff --name-only, parsing SARIF location URIs, and cross-referencing. This tool automates that entire workflow in a single call.

Use Cases

• Branch triage: After running codeql_database_analyze, identify which findings were introduced on the current branch vs inherited from the base
• PR review: Focus review on findings in files/lines actually changed by the PR
• Pipeline integration: Chain with sarif_list_rules and sarif_extract_rule to produce focused reports on new findings only

Example Usage

const result = await server.call('sarif_diff_by_commits', {
  sarifPath: '/path/to/results.sarif',
  refRange: 'main..HEAD',
  granularity: 'line',
});

Example Input/Output

// Input
{
  "sarifPath": "/path/to/results.sarif",
  "refRange": "main..HEAD",
  "granularity": "line"
}

// Output
{
  "granularity": "line",
  "newResults": [
    { "ruleId": "js/sql-injection", "file": "src/db.js", "line": 42, "resultIndex": 0 }
  ],
  "preExistingResults": [
    { "ruleId": "js/xss", "file": "src/views.js", "line": 30, "resultIndex": 2 }
  ],
  "summary": {
    "diffFileCount": 3,
    "refRange": "main..HEAD",
    "totalResults": 5,
    "totalNew": 2,
    "totalPreExisting": 3
  }
}

🧪 Implementation Details

Files Added/Modified

• Utility function + types: server/src/lib/sarif-utils.ts — diffSarifByCommits() pure function, DiffFileEntry, DiffGranularity, ClassifiedResult, SarifDiffByCommitsResult types
• Tool registration: server/src/tools/sarif-tools.ts — registerSarifDiffByCommitsTool() + parseGitDiffOutput() helper
• Utility tests: server/test/src/lib/sarif-utils.test.ts — 14 tests for diffSarifByCommits()
• Tool tests: server/test/src/tools/sarif-tools.test.ts — 5 handler tests, registration count 7→8
• Documentation: server/src/resources/server-tools.md — tool table + workflow section
• Go test runner: client/internal/testing/params.go — sarif_diff_by_commits case for param resolution
• Go unit test: client/internal/testing/params_test.go — TestBuildToolParams_SARIFDiffByCommitsWithConfig
• Integration test fixture: client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/ — SARIF fixture, test-config.json with assertions, before/after directories

Architecture Integration

The implementation separates concerns into two layers:

• Pure utility (diffSarifByCommits): No I/O, no side effects. Takes a SARIF document and pre-parsed diff entries, returns classified results. Directly unit-testable.
• Tool handler: Orchestrates SARIF loading (via existing loadSarif()) and git diff execution (via executeCLICommand), delegates classification to the pure utility.

parseGitDiffOutput() extracts file paths and hunk ranges from git diff --unified=0 output, producing DiffFileEntry[] with { path, hunks: [{ startLine, lineCount }] }.

URI matching reuses the existing normalizeUri() / urisMatch() infrastructure from sarif-utils so file:/// URIs, relative paths, and %SRCROOT% variants all work.

• Server Registration: Primitive properly registered with MCP server
• Error Handling: Comprehensive error handling implemented
• Logging: Appropriate logging added
• Type Safety: Full TypeScript type coverage
• Schema Validation: Zod schemas for input/output validation
• Session Tracking: Compatible with monitoring and reporting system
• Quality Assessment: Participates in quality score calculations

Design Patterns

• Follows Existing Patterns: Consistent with sarif_diff_runs, sarif_compare_alerts
• Modular Design: Pure utility + thin tool wrapper
• Dependency Management: Uses existing executeCLICommand for git; no new deps
• Performance Considerations: Single git diff call; linear scan over results

📋 Testing Coverage

Unit Tests

• Input Validation: Tests for missing SARIF, invalid paths, git failures
• Core Functionality: File-level and line-level granularity classification
• Error Conditions: Git diff failure, no SARIF source, no locations
• Integration: MCP tool handler with mocked executeCLICommand

Test Scenarios

1. File-level granularity (7 tests): All new, all pre-existing, partitioned, empty diff, no results, no locations, file:// URI normalization
2. Line-level granularity (5 tests): Within/outside hunks, multiple hunks, empty hunks fallback, single-line boundary
3. Classified result structure (2 tests): Field completeness, default granularity
4. Tool handler (5 tests): Success paths with mocked git, error handling, line-level mode
5. Go param resolution (1 test): Verifies sarifPath injection from before/ and config merging of refRange/granularity
6. Client integration (1 test, 6 assertions): file_level_classification — validates HEAD..HEAD empty diff classifies all 3 results as pre-existing

Test Files

• server/test/src/lib/sarif-utils.test.ts — 14 new tests (76 total)
• server/test/src/tools/sarif-tools.test.ts — 5 new tests (31 total)
• client/internal/testing/params_test.go — 1 new Go unit test
• client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/ — integration test fixture with SARIF, test-config.json (6 response assertions), README, before/after directories

🔗 References

Related Implementation

• sarif_diff_runs — same tool registration pattern, same loadSarif() helper
• computeLocationOverlap — related URI normalization logic reused here
• executeCLICommand — existing CLI executor with git in the allowlist

External References

• MCP Specification: Standard server.tool() registration
• CodeQL Documentation: SARIF v2.1.0 physicalLocation.artifactLocation.uri + region.startLine
• Implementation Examples: sarif_diff_runs, sarif_compare_alerts in same file

🚀 Server Integration

Registration Details

server.tool(
  'sarif_diff_by_commits',
  'Correlate SARIF results with a git diff to classify findings as "new" or "pre-existing".',
  {
    cacheKey: z.string().optional(),
    granularity: z.enum(['file', 'line']).optional().default('file'),
    refRange: z.string(),
    repoPath: z.string().optional(),
    sarifPath: z.string().optional(),
  },
  async ({ sarifPath, cacheKey, refRange, repoPath, granularity }) => { /* ... */ }
);

Compatibility

• MCP Protocol Version: Compatible with current MCP version
• Node.js Version: Compatible with required Node.js version
• Dependencies: No new dependencies — uses existing executeCLICommand
• TypeScript Version: Compatible with project TypeScript version

Performance Considerations

• Memory Usage: Linear in SARIF result count × diff file count
• Execution Time: Dominated by single git diff subprocess call
• Concurrency: Stateless pure function; thread-safe
• Resource Cleanup: No resources to clean up

🔍 Quality Assurance

Code Quality

• TypeScript Compilation: Compiles without errors
• Linting: Passes ESLint checks
• Formatting: Follows project formatting
• Documentation: JSDoc on all public interfaces

Validation Testing

• Manual Testing: Verified build, bundle, lint
• Automated Testing: All 107 SARIF-related server tests pass; Go unit tests pass
• Integration Testing: Client integration test fixture with file_level_classification test case; tool handler tested with mocked git output
• Error Path Testing: Missing SARIF, invalid refs, git failures

Security Considerations

• Input Sanitization: refRange passed to executeCLICommand which uses execFile (no shell)
• No Code Injection: git is in the allowlist; args sanitized by existing infrastructure
• Resource Limits: Inherits existing CLI command timeout (5 min default)
• Error Information: Error messages expose only git stderr, not internal state

👥 Review Guidelines

For Reviewers

• ⚠️ SCOPE COMPLIANCE: PR contains only server implementation files and client integration tests
• ⚠️ NO UNRELATED FILES: No temporary, output, or unrelated files
• Functionality: Primitive works as described
• Test Coverage: Comprehensive test coverage across server unit tests, tool handler tests, Go unit tests, and client integration tests
• Code Quality: Follows project standards
• Documentation: Clear documentation and examples
• Performance: Acceptable performance characteristics
• Integration: Properly integrated with MCP server
• Type Safety: Full TypeScript coverage
• Error Handling: Robust error handling

Testing Instructions

# Full build and test
npm run build-and-test

# Server tests only
npm test --workspace=server

# Specific test files
npx vitest run server/test/src/lib/sarif-utils.test.ts server/test/src/tools/sarif-tools.test.ts

# Go unit tests (client)
make -C client test-unit

# Lint
npm run lint:fix

# Client integration tests (requires running MCP server)
make -C client test-integration

📊 Impact Analysis

Server Impact

• Startup Time: No impact — one additional server.tool() registration
• Memory Usage: No persistent state
• API Surface: Adds 1 tool to existing 7 SARIF tools (now 8)
• Dependencies: Zero new dependencies

AI Assistant Benefits

• Enhanced Capabilities: Automates manual SARIF-to-git-diff cross-referencing
• Improved Accuracy: Precise file/line classification replaces manual triage
• Better Coverage: Enables branch-aware SARIF analysis workflows
• Workflow Integration: Chains with sarif_list_rules, sarif_extract_rule, sarif_rule_to_markdown
• Quality Measurement: Contributes to monitoring and quality assessment

Monitoring & Reporting Integration

• Session Tracking: Compatible with session-based development tracking
• Quality Metrics: Contributes to multi-dimensional quality scoring
• Usage Analytics: Standard tool call tracking
• Test-Driven Workflow: Integrates with test-driven development practices

Maintenance Considerations

• Code Maintainability: Pure utility function + thin tool wrapper
• Test Maintainability: Tests use same fixtures/patterns as existing SARIF tests
• Documentation: Updated server-tools.md resource
• Compatibility: Forward-compatible — supports both file and line granularity

🔄 Deployment Considerations

Rollout Strategy

• Safe Deployment: Additive-only change; no existing tools modified
• Feature Flag: Not needed — tool is always registered with other SARIF tools
• Monitoring: Standard tool call logging
• Rollback: Safe to remove without affecting other tools

Migration Notes

No migration required. The tool is a new addition to the existing SARIF tool suite.

[data-douser]

@copilot Any new MCP tool must have at least one covering client integration test in order to validate (or invalidate) the proper functionality of the new tool. Our new sarif_diff_by_commits needs to be much more extensively tested.

[Copilot]

@copilot Any new MCP tool must have at least one covering client integration test in order to validate (or invalidate) the proper functionality of the new tool. Our new sarif_diff_by_commits needs t...

Added in 9723dbf:

Go integration test runner support:

• sarif_diff_by_commits case in client/internal/testing/params.go — resolves sarifPath from before/ dir, merges refRange, repoPath, and granularity from test-config.json
• Go unit test in params_test.go verifying param resolution

Client integration test fixture (client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/):

• SARIF with 3 results (2 rules, 3 files)
• Uses HEAD..HEAD ref range (empty diff → deterministic: all results pre-existing)
• test-config.json assertions validate totalNew=0, totalPreExisting=3, totalResults=3, granularity, and result partition keys

Combined with the existing 14 diffSarifByCommits() utility tests and 5 tool handler tests, total coverage across all layers:

• Server unit tests (sarif-utils.ts): 14 tests
• Server tool handler tests (sarif-tools.ts): 5 tests
• Go client unit test (params_test.go): 1 test
• Client integration test fixture: 1 test with 6 assertions

[Copilot]

Pull request overview

Adds a new SARIF analysis MCP tool, sarif_diff_by_commits, to correlate SARIF findings with a git diff over a commit range and classify results as “new” vs “pre-existing”, with supporting docs and tests across server + client integration runner.

Changes:

• Implemented diffSarifByCommits() (pure classification) and integrated it into a new sarif_diff_by_commits MCP tool that shells out to git diff --unified=0.
• Added server unit tests for classification logic and tool handler behavior, and updated SARIF tool registration expectations (7 → 8).
• Added client-side param injection support plus a new integration test fixture for file-level classification.

Show a summary per file

File	Description
server/src/lib/sarif-utils.ts	Adds diff correlation types and diffSarifByCommits() classification logic.
server/src/tools/sarif-tools.ts	Registers the new tool, runs git diff, parses unified diff hunks, and returns classified JSON.
server/src/resources/server-tools.md	Documents the new SARIF tool in the server tools reference and workflow list.
server/test/src/lib/sarif-utils.test.ts	Adds unit tests for file/line granularity classification behavior.
server/test/src/tools/sarif-tools.test.ts	Updates tool registration count and adds handler tests for sarif_diff_by_commits.
server/dist/codeql-development-mcp-server.js	Updates bundled build artifact to include the new tool and utility code.
client/internal/testing/params.go	Adds sarif_diff_by_commits param construction (inject SARIF path + merge config args).
client/internal/testing/params_test.go	Adds a Go unit test verifying param injection/merge for the new tool.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/test-config.json	Adds integration test config and response assertions.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/README.md	Documents the integration test purpose and expectations.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/before/results.sarif	Adds SARIF fixture input with 3 results in 3 files.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/before/monitoring-state.json	Adds integration “before” monitoring state.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/after/results.sarif	Mirrors expected SARIF fixture state post-run (unchanged file).
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/after/monitoring-state.json	Adds integration “after” monitoring state.

Copilot's findings

• Files reviewed: 13/15 changed files
• Comments generated: 3

[Copilot]

Pull request overview

Adds a new SARIF triage tool (sarif_diff_by_commits) to correlate SARIF results with a git ref-range diff, classifying findings as “new” vs “pre-existing”, and integrates it across server, tests, docs, and client integration fixtures.

Changes:

• Implement diffSarifByCommits() in server/src/lib/sarif-utils.ts and wire a new sarif_diff_by_commits MCP tool in server/src/tools/sarif-tools.ts (runs git diff --unified=0 and parses hunks).
• Add/extend server unit tests and tool-handler tests for the new primitive.
• Add client param-resolution support + Go unit test + an integration-test fixture for file-level classification.

Show a summary per file

File	Description
server/src/lib/sarif-utils.ts	Adds diff correlation types and the pure diffSarifByCommits() classifier.
server/src/tools/sarif-tools.ts	Registers sarif_diff_by_commits and parses git diff output into hunks/files.
server/test/src/lib/sarif-utils.test.ts	Adds unit tests covering file/line granularity classification behaviors.
server/test/src/tools/sarif-tools.test.ts	Adds handler tests for sarif_diff_by_commits and updates tool registration count.
server/src/resources/server-tools.md	Documents the new tool in the SARIF tools table and workflow list.
server/dist/codeql-development-mcp-server.js	Updates bundled build artifact to include the new tool/utility.
client/internal/testing/params.go	Adds integration-runner param resolution for sarif_diff_by_commits.
client/internal/testing/params_test.go	Adds a Go unit test validating params injection/merge for the new tool.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/test-config.json	Adds a fixture config and response assertions for file-level classification.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/README.md	Documents intent/inputs/expected behavior of the integration test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/before/results.sarif	SARIF input fixture with 3 results across 3 files.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/before/monitoring-state.json	Integration test monitoring metadata (before).
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/after/results.sarif	Post-run fixture (unchanged SARIF).
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/after/monitoring-state.json	Integration test monitoring metadata (after).

Copilot's findings

• Files reviewed: 13/15 changed files
• Comments generated: 3

[Copilot]

Pull request overview

Adds a new SARIF triage tool (sarif_diff_by_commits) to correlate SARIF findings with a git diff across a commit ref range, enabling “new vs pre-existing” classification at file or line granularity.

Changes:

• Implement diffSarifByCommits() (pure utility) and supporting diff/correlation types in server/src/lib/sarif-utils.ts.
• Register new MCP tool sarif_diff_by_commits in server/src/tools/sarif-tools.ts, including git diff parsing and refRange validation.
• Add server/unit/tool tests, update tool documentation, and extend client integration test harness + fixtures for the new tool.

Show a summary per file

File	Description
server/src/lib/sarif-utils.ts	Adds diff/correlation types and the diffSarifByCommits() classifier utility.
server/src/tools/sarif-tools.ts	Registers sarif_diff_by_commits, runs git diff, parses hunks, and returns classification output.
server/src/resources/server-tools.md	Documents the new tool in the SARIF tools table and recommended workflow list.
server/test/src/lib/sarif-utils.test.ts	Adds unit tests covering file/line classification behavior for diffSarifByCommits().
server/test/src/tools/sarif-tools.test.ts	Updates registration count and adds handler tests for sarif_diff_by_commits with mocked git output.
server/dist/codeql-development-mcp-server.js	Updates bundled build artifact to include the new tool and utility logic.
client/internal/testing/params.go	Adds parameter-resolution support for sarif_diff_by_commits integration tests (SARIF path injection + config merge).
client/internal/testing/params_test.go	Adds a unit test for sarif_diff_by_commits param building and introduces a project-local tmp helper.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/test-config.json	New integration test config for file-level classification with an empty diff.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/before/results.sarif	SARIF fixture input for file-level integration test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/before/monitoring-state.json	Monitoring metadata for file-level integration test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/after/results.sarif	Expected SARIF fixture in after-state for file-level integration test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/after/monitoring-state.json	Expected monitoring outcome for file-level integration test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/README.md	Explains file-level integration test intent and expectations.
client/integration-tests/primitives/tools/sarif_diff_by_commits/line_level_classification/test-config.json	New integration test config for line-level classification with an empty diff.
client/integration-tests/primitives/tools/sarif_diff_by_commits/line_level_classification/before/results.sarif	SARIF fixture input for line-level integration test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/line_level_classification/before/monitoring-state.json	Monitoring metadata for line-level integration test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/line_level_classification/after/results.sarif	Expected SARIF fixture in after-state for line-level integration test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/line_level_classification/after/monitoring-state.json	Expected monitoring outcome for line-level integration test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/line_level_classification/README.md	Explains line-level integration test intent and expectations.

Copilot's findings

• Files reviewed: 19/21 changed files
• Comments generated: 4

[Copilot]

Pull request overview

Adds a new SARIF analysis MCP tool (sarif_diff_by_commits) that correlates SARIF results to git diff output, enabling “new vs pre-existing” triage at file or line granularity. This fits into the existing SARIF tool suite by extending sarif-utils with a pure classifier and wiring it into server/src/tools/sarif-tools.ts, plus test coverage and client integration fixtures.

Changes:

• Add diffSarifByCommits() + supporting types to classify SARIF results using parsed git diff hunks.
• Register the new sarif_diff_by_commits tool and document it in the server tools resource.
• Add unit/tool tests plus client param resolution and integration test fixtures for file/line modes.

Show a summary per file

File	Description
server/src/lib/sarif-utils.ts	Adds diff-by-commits classification types and the diffSarifByCommits() implementation.
server/src/tools/sarif-tools.ts	Registers sarif_diff_by_commits, runs git diff, parses hunks, and returns classified output.
server/src/resources/server-tools.md	Documents the new SARIF tool in the tools table and workflow section.
server/test/src/lib/sarif-utils.test.ts	Adds unit tests covering file/line classification behavior and edge cases.
server/test/src/tools/sarif-tools.test.ts	Adds handler tests for sarif_diff_by_commits and updates registration count/expectations.
server/dist/codeql-development-mcp-server.js	Updates built server bundle to include the new tool and library logic.
client/internal/testing/params.go	Adds tool param injection/merging logic for sarif_diff_by_commits integration tests.
client/internal/testing/params_test.go	Updates temp dir strategy and adds a unit test validating params for sarif_diff_by_commits.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/test-config.json	Adds integration test config/assertions for file-level classification on empty diff.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/before/results.sarif	Adds SARIF fixture input for file-level integration test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/before/monitoring-state.json	Adds monitoring state fixture for file-level test “before” state.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/after/results.sarif	Captures expected “after” filesystem state for file-level test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/after/monitoring-state.json	Captures expected success monitoring state for file-level test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/file_level_classification/README.md	Documents the file-level integration test scenario and expectations.
client/integration-tests/primitives/tools/sarif_diff_by_commits/line_level_classification/test-config.json	Adds integration test config/assertions for line-level classification on empty diff.
client/integration-tests/primitives/tools/sarif_diff_by_commits/line_level_classification/before/results.sarif	Adds SARIF fixture input for line-level integration test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/line_level_classification/before/monitoring-state.json	Adds monitoring state fixture for line-level test “before” state.
client/integration-tests/primitives/tools/sarif_diff_by_commits/line_level_classification/after/results.sarif	Captures expected “after” filesystem state for line-level test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/line_level_classification/after/monitoring-state.json	Captures expected success monitoring state for line-level test.
client/integration-tests/primitives/tools/sarif_diff_by_commits/line_level_classification/README.md	Documents the line-level integration test scenario and expectations.

Copilot's findings

• Files reviewed: 19/21 changed files
• Comments generated: 1