Vastly improve API surface check: support framework-specific endpoint detection

[jdelfino]

Problem

The current API surface guardrail check (in ) only detects generic language-level exports:

• JS/TS: export statements
• Python: top-level class and def
• Go: exported functions and types
• Rust: pub items
• OpenAPI/Swagger spec files

This misses the most important API changes: framework-specific endpoint definitions.

When an agent adds app.post('/users', handler) in Express or @app.get("/items") in FastAPI, these are API contract changes with downstream impact — but the current check doesn't detect them.

Proposed Solution

Extend lib/api-patterns.js to detect framework-specific API endpoint patterns across popular web frameworks.

High-priority frameworks (covers 80% of use cases)

JavaScript/TypeScript:

• Express.js: app.{get,post,put,delete,patch}(), router.{get,post,...}()
• Next.js: API route files in pages/api/\* or app/\*\*/route.{js,ts}
• Fastify: fastify.{get,post,...}(), app.route()
• Koa: router.{get,post,...}()
• Hono: app.{get,post,...}()

Python:

• FastAPI: @app.{get,post,...}, @router.{get,post,...}, APIRouter()
• Flask: @app.route(), @blueprint.route()
• Django: URL pattern changes in urls.py (path(), re_path())
• Django REST Framework: @api_view, ViewSet classes

Go:

• Standard library: http.HandleFunc(), mux.HandleFunc()
• Gin: router.{GET,POST,...}()
• Echo: e.{GET,POST,...}()
• Chi: r.{Get,Post,...}()
• Fiber: app.{Get,Post,...}()

Rust:

• Actix Web: #[get], #[post], route macros
• Axum: Router::new().route()
• Rocket: #[get], #[post] attributes
• Warp: filter combinations for routes

Ruby:

• Rails: changes to config/routes.rb
• Sinatra: get '/path', post '/path'

Java:

• Spring Boot: @GetMapping, @PostMapping, @RequestMapping
• JAX-RS: @Path, @GET, @POST

C#/.NET:

• ASP.NET Core: [HttpGet], [HttpPost], [Route] attributes
• Minimal APIs: app.MapGet(), app.MapPost()

PHP:

• Laravel: route changes in routes/ files
• Symfony: route annotations/attributes

Detection strategy

1. Pattern matching: Regex patterns for each framework's route definition syntax
2. File-based detection: Special handling for route files (Next.js API routes, Django urls.py, Rails routes.rb)
3. Annotation/decorator detection: Python decorators, Java/C# attributes, Rust macros
4. Method call detection: Framework-specific router methods

Example output

When the check detects:

+ app.post('/api/users', createUser)
+ @app.get("/items/{item_id}")
+ router.GET("/health", healthCheck)

Annotations should say:

• API endpoint added: POST /api/users (Express.js)
• API endpoint added: GET /items/{item_id} (FastAPI)
• API endpoint added: GET /health (Gin)

Implementation

• Extend detectAPIChanges() to accept framework detection
• Add framework-specific pattern dictionaries
• Auto-detect framework from common files (package.json, requirements.txt, go.mod, etc.)
• Add tests for each framework's patterns
• Update annotations to include framework name and HTTP method + path

Success criteria

• Detects 80%+ of API endpoint additions/changes across the top 20 web frameworks
• Provides actionable annotations with method, path, and framework name
• Minimal false positives (doesn't flag every function call)

Related

This addresses the design doc's statement:

API surface change detection. Detect changes to exported functions, public interfaces, API endpoints. These have outsized downstream impact that agents don't understand without organizational context.

The current implementation handles exports and interfaces well, but misses the critical API endpoints piece.