baume-code-correlator

name

baume-code-correlator

description

This skill should be used when the user asks "where is this API endpoint implemented", "find the code for this route", "which file handles this endpoint", "map API findings to code", or needs to correlate OpenAPI spec paths with source code locations. Also use when creating fix plans for code-first API projects (NestJS, Fastify, Express) after running baume-review, or when user mentions "find my NestJS controller", "locate Fastify route handler", "Express route definition".

Baume Code Correlator

Map Baume review findings to code locations for code-first API projects.

Preferred Approach: MCP Correlate Tool

IMPORTANT: If the mcp__baume__baume-correlate tool is available, use it instead of manual correlation. The MCP tool:

• Takes a reviewId from baume-review
• Automatically detects framework from package.json
• Uses MCP sampling for accurate code location
• Batch processes all findings efficiently
• Returns ExtendedFinding[] with file:line references

Use mcp__baume__baume-correlate with:
- reviewId: {review-id-from-baume-review}
- projectRoot: {absolute-path-to-project}
- specPath: {absolute-path-to-spec} (optional, for context extraction)
- framework: "nestjs" | "fastify" | "express" | "unknown" (optional hint)
- correlationLevel: "minimal" | "moderate" | "thorough" (optional, default: "moderate")

The manual process below is a fallback for when MCP tools are not available.

When to Use (Manual Fallback)

This skill activates when:

• Creating a fix plan after baume-review for a code-first project
• User asks "where is this endpoint implemented?"
• User wants to fix API issues and needs to know which files to modify
• Mapping OpenAPI spec paths to source code
• MCP correlate tool is not available

Prerequisites

• Baume review findings (from baume-review MCP tool or review document)
• Access to project source code
• OpenAPI spec (to extract operation context)

Correlation Process

Step 1: Gather Inputs

From MCP tool results: If baume-review was called, use the findings from that response.

From review document: If working from .baume/reviews/*.md, read the document to get:

• spec_path from frontmatter
• Findings list with ruleId, path, severity

Step 2: Extract Operations from Findings

Parse each finding's path field to extract method and API path:

"GET /users/{id}" → method: GET, path: /users/{id}
"POST /orders"    → method: POST, path: /orders

Dedupe by method+path (multiple findings may target same endpoint).

Step 3: Detect Framework

Read package.json in project root:

• @nestjs/core → NestJS (decorators: @Controller, @Get, @Post)
• fastify → Fastify (route methods: .get, .post, app.route)
• express → Express (router methods: router.get, app.get)

Step 4: Find Code Locations

For each unique operation, spawn a baume-code-locator agent:

Task: baume-code-locator
Prompt: Find the code that implements this API operation:
  - method: GET
  - path: /users/{id}
  - operationId: getUserById (if available from spec)
  - framework: nestjs
  - rootDir: /project

Spawn up to 5 agents in parallel for efficiency.

Step 5: Compile Extended Findings

For each finding, build this structure:

{
  "finding": {
    "ruleId": "aip122/plural-resources",
    "severity": "warning",
    "path": "GET /user/{id}",
    "message": "Resource name should be plural",
    "suggestion": "Rename to /users/{id}",
    "fix": { "type": "rename-path-segment", "..." }
  },
  "specContext": {
    "method": "GET",
    "path": "/user/{id}",
    "operationId": "getUser",
    "summary": "Get a user by ID",
    "tags": ["users"]
  },
  "codeLocations": [
    {
      "file": "src/users/users.controller.ts",
      "line": 42,
      "type": "controller",
      "confidence": "high",
      "snippet": "@Get(':id')\nasync getUser(@Param('id') id: string) { ... }",
      "reasoning": "@Get decorator matches, operationId in @ApiOperation"
    }
  ],
  "suggestedDiffs": {
    "specDiff": "...",
    "codeDiffs": [{ "file": "...", "diff": "...", "description": "..." }]
  }
}

Step 6: Generate Suggested Diffs

For deterministic fixes, pre-populate code diffs using templates from diff-templates.md.

fix.type	Code Diff
rename-path-segment	Update @Controller('user') → @Controller('users')
rename-parameter	Update @Param name
change-status-code	Add/update @HttpCode(201)
remove-request-body	Remove @Body() parameter
add-parameter	Partial - provide template
add-schema	No - too complex, guidance only

Step 7: Output Correlation

Write to .baume/correlations/{date}-{spec-name}.json:

{
  "extendedFindings": [
    /* ... */
  ],
  "framework": "nestjs",
  "generatedAt": "2025-01-15T10:30:00Z",
  "reviewPath": ".baume/reviews/...",
  "specPath": "openapi.yaml",
  "summary": {
    "correlated": 6,
    "notFound": 2,
    "totalFindings": 8
  }
}

Output Format

Report results to user:

## Correlation Complete

| Operation       | Code Location                      | Confidence |
| --------------- | ---------------------------------- | ---------- |
| GET /users/{id} | src/users/users.controller.ts:42   | high       |
| POST /users     | src/users/users.controller.ts:28   | high       |
| GET /orders     | src/orders/orders.controller.ts:15 | medium     |

**Not found:** DELETE /admin/cache, GET /health

Correlation saved to: .baume/correlations/2025-01-15-orders-api.json

MCP Tools Reference

baume-review: Analyze OpenAPI spec against AIP rules. Returns findings with reviewId.

Call: mcp__baume__baume-review with specPath or specUrl
Returns: { reviewId, findings[], summary, findingsPath, findingsUrl }

baume-correlate: Correlate Baume review findings with code locations.

Call: mcp__baume__baume-correlate with reviewId, projectRoot, specPath, framework
Returns: { extendedFindings[], framework, summary, correlationPath }

baume-apply-fixes: Apply suggested fixes to spec (after correlation, to fix spec issues).

Call: mcp__baume__baume-apply-fixes with reviewId, specPath/specUrl, writeBack, dryRun
Returns: { summary, downloadUrl, modifiedSpec }

Agent Reference

baume-code-locator: Find code implementing a single API operation.

• Input: method, path, operationId, tags, rootDir, framework
• Output: CodeLocation[] with file:line, confidence, snippets

File Locations

Purpose	Path
Review documents	.baume/reviews/*.md
Correlation output	.baume/correlations/*.json
Code locator agent	plugins/baume/agents/baume-code-locator.md
Diff templates	diff-templates.md

Related

• Use /baume-plan after correlation to create a fix plan
• Use /baume-validate to verify fixes against the plan
• Use baume-code-locator agent directly for single operation lookup
• See aip-knowledge skill for AIP rule explanations