feat(graph): add NestJS controller route resolver

[abhinav-phi]

What

• Adds a NestJS FrameworkResolver for decorator-defined HTTP controller routes.
• Detects NestJS through @nestjs/core or @nestjs/common dependencies.
• Recognizes @Controller() prefixes and HTTP method decorators such as @Get(), @Post(), @Put(), @Patch(), @Delete(), @Options(), @Head(), and @All().
• Emits stable route nodes and function_ref references to controller methods.
• Resolves same-file handlers only when the target is unambiguous.
• Adds a NestJS fixture, focused resolver tests, and framework-registry wiring.

Why

Closes #98.

This teaches the code graph about NestJS controller routing without changing the frozen FrameworkResolver interface or graph-core semantics.

Scope boundaries

This PR is limited to statically recognizable HTTP controller routes. Dependency-injection edges, guards, pipes, interceptors, middleware, gateways, GraphQL, microservices, and runtime decorator evaluation remain out of scope.

How to test

npm run typecheck
npm test
npm run build

Focused review should verify:

• Positive and negative NestJS detection.
• Controller-prefix and method-path normalization.
• Multiple HTTP methods and parameterized paths.
• Stable route-node identity.
• Confident same-file handler resolution.
• Missing or ambiguous handlers remain unresolved.
• No graph identity, reconciliation, schema, or drift-semantics changes.

[abhinav-phi]

Hi @theDakshJaitly @Yashasvi2229 — this PR has been open since mid-July with no reviews, so I gave it some maintenance:

• Rebased onto latest main (it had fallen ~340 commits behind).
• Verified locally: npm run typecheck, npm run build, and the resolver test suite all pass.
• All CI checks on this branch are green.

The implementation targets the frozen FrameworkResolver interface, which is unchanged on current main, so no adaptation was needed beyond the rebase.

Is anything blocking this from review — or would you like changes first? Happy to iterate. (Tracking issue: #98, which this resolves.)

[theDakshJaitly]

Yeah our bad, got caught up in the new release, sorry for the delay in review

We will review asap, thanks for the rebase as well

[theyashasvipandey]

Thanks for this one @abhinav-phi, and for the rebase. The resolver is additive, detection is solid, and the happy path works end to end: I ran real rebuildGraph builds over a small NestJS project and every route linked to the right method (GET /users/:id → UsersController::findOne), including same-named methods in different controller files. The resolver suites pass too.

I then probed the extractor against the decorator forms real NestJS code uses. Three things need fixing before merge.

Must fix

1. Two routes with the same method + path fail the whole graph build

The route id is generateNodeId(filePath, "route", routeName), so two routes with the same name in one file get the same id, and the engine rejects duplicate ids. The whole build throws, not just this file. NestJS's own versioning pattern triggers it:

@Controller('users')
export class UsersController {
  @Version('1') @Get() findAllV1() {}
  @Version('2') @Get() findAllV2() {}
}

Graph staging invariant failed: duplicate node id route:9fe09bb0999fbf19a48312a2d9fa2d6e.

@Get() + @Get('/') in one controller does the same, and so does an old handler left in a block comment. The Express resolver avoids this by putting the handler in the signature (GET /users -> findAllV1) and adding an ordinal to the role. Doing the same here fixes it. Please add the @Version case as a test.

2. Non-string @Controller arguments give wrong paths

DECORATOR_REGEX only matches @Controller() with a string or no argument. Any other form is skipped entirely, so the prefix is either lost or inherited from the previous controller in the file:

source	derived	expected
@Controller({ path: 'users', version: '1' }) + @Get(':id')	GET /:id	GET /users/:id
same, after an @Controller('admin') class in the file	GET /admin/:id	GET /users/:id
@Controller(USERS_PATH)	GET /:id	unknown
@Controller(['users', 'people']) + @Get()	GET /	GET /users, GET /people

The object form is common (it's how controller versioning and host routing are declared), so please parse { path: '…' }. For the forms that can't be read statically (a constant, an array), skip that controller's routes rather than emitting a wrong path. Either way, every @Controller(...) should reset the prefix so nothing carries over.

3. Commented-out decorators create phantom routes

The regex runs over the raw file text, comments included:

@Controller('users')
export class UsersController {
  // @Get('legacy')
  @Get(':id')
  findOne() {}
}

This produces both GET /users/:id and a phantom GET /users/legacy, both pointing at findOne. Blanking comments out before scanning (with spaces, so offsets and line numbers stay correct) fixes this and the block-comment case in #1.

Should fix

4. Two controllers in one file lose their links

Resolution matches the handler by name within the file, so two controllers in one file that both have findAll leave both routes unresolved. I confirmed this in a real build. #98 asks to prefer the class context. The TypeScript extractor already names methods UsersController::findAll, so tracking the class that follows each @Controller and matching on qualifiedName resolves both.

Smaller things

• Parenthesis skipping isn't string-aware. @ApiOperation({ summary: 'List users :)' }) between @Get() and the method silently drops the route. Rare, but it fails without any signal.
• Array method paths. @Get(['list', 'all']) produces no route.
• Integration test. The unit tests use a fake context. One test through rebuildGraph (like the Next.js resolver's in feat(graph): add Next.js App Router route resolver #179) would have caught 1 and 4.
• Edge label. resolvedBy: "framework" / confidence 1 doesn't identify the resolver; Express uses express-route-handler / 0.8 for the same evidence. Something like nestjs-route-handler would match.
• Fixture and header comments. The fixture has leftover notes ("Missing handler name (anonymous function)… let's just make it a normal one"), and the file header mentions a single-controller-per-file assumption the code doesn't make. Worth tidying.
• CHANGELOG. Please add an entry under ## [Unreleased] → ### Added, as feat(graph): add Next.js App Router route resolver #179 does.

[abhinav-phi]

All findings addressed — thanks for probing the decorator forms; every one of these reproduced locally.

Must fixes

1. Duplicate ids — the handler now rides in the signature (GET /users -> findAllV1) and an ordinal joins the role (nestjs-route:<n>), mirroring Express. The @Version('1')/@Version('2') case is in the fixture and asserted: three GET /users nodes, three distinct ids. Comment-blanking (must-fix 3) removes the block-comment variant entirely.
2. Non-string @Controller arguments — extractBalancedArgs (string-aware) now reads the full argument text: empty → no prefix; string literal → prefix; object form → path property ({ path: 'users', version: '1' } → GET /users/:id); constants and arrays → that controller's routes are skipped rather than guessed, per your instruction. Every @Controller(...) resets the prefix and binds to the next class declaration, so nothing carries over between controllers.
3. Commented decorators — comments are blanked with spaces before scanning (state machine over line/block comments), so offsets and line numbers survive while // @Get('legacy') and block-comment handlers stop being code. Tested.

Should fix 4 — the reference now carries candidates: [::] from extraction; resolution prefers a same-file qualified-name match when the simple name is ambiguous. Two controllers with findAll in one file both resolve (test included).

Smaller things — paren skipping is string-aware (@ApiOperation({ summary: 'List users :)' }) test added); @Get([...]) non-literals skip (consistent with the controller rule); an end-to-end rebuildGraph test now covers versioned routes + commented decorators; edge label is nestjs-route-handler at confidence 0.8 with the integration query updated; fixture notes and the stale header comment are gone; CHANGELOG entry added under ## [Unreleased] → ### Added on this branch.

The one deliberate non-change: @Get(['list', 'all']) emits nothing (array paths skip like unreadable controller args) — happy to fan those out instead if you'd rather.

[theyashasvipandey]

Thanks @abhinav-phi, I checked out ad61598, ran the resolver suites, the new integration test and typecheck (all green), then re-ran the round-1 probes plus real rebuildGraph builds. Fixed and verified: versioned routes get distinct ids, commented-out decorators are gone, the object-form prefix works and no longer leaks between controllers, constants and arrays are skipped, the :) string no longer breaks scanning, two controllers in one file each resolve to their own findAll, and the edge label is nestjs-route-handler / 0.8.

A few things before merge:

1. Inline decorators now link the wrong handler (regression)

The line-based rewrite looks for the handler after the end of the decorator's line, so a decorator written on the same line as its method picks up the next method instead. Real build:

@Controller('users')
export class UsersController {
  @Get() list() { return []; }
  @Get(':id') findOne(@Param('id') id: string) { return { id }; }
}

This produces one route, GET /users -> findOne (wrong handler), and GET /users/:id is lost. Round 1 handled this form correctly. Scanning from just after the decorator's closing ) (you already have it from extractBalancedArgs) fixes it. Please add this snippet as a test.

2. { path: CONSTANT } still produces a wrong path

@Controller({ path: USERS_PATH, version: '1' }) + @Get(':id') gives GET /:id. When the object has a path key that isn't a string literal, it should skip like the bare-constant form. An object with no path at all ({ host: '…' }) is correctly unprefixed.

3. Rebase and CHANGELOG

• The PR now conflicts with main in frameworks/index.ts, since feat(graph): add Next.js App Router route resolver #179 registered nextjsResolver on the same line. The registry becomes [expressResolver, nextjsResolver, nestjsResolver], with both exports kept.
• The CHANGELOG entry isn't in the branch. ad61598 doesn't touch CHANGELOG.md, so it probably didn't get committed. Please add it under ## [Unreleased] → ### Added.

Smaller, fine as follow-ups:

• A @Controller({ ... }) whose object spans several lines skips the whole controller, because extractBalancedArgs only reads one line. It fails safe, but that's a common formatting of the object form.
• @Controller('/users/') + @Get('/:id/') gives GET /users//:id. The prefix's trailing slash isn't trimmed before joining.
• Template-literal paths such as @Get(`${BASE}/x`) become GET /users/${BASE}/x. A template containing ${ should be treated as unreadable.
• Arrays in @Get([...]) skipping is fine by me.

[abhinav-phi]

Okay... on it... on your orders ma'am 🫡

[abhinav-phi]

Round-2 follow-up complete — every item from your review is addressed in 57ebdcb:

1. Inline decorators linked the wrong handler (regression) — fixed properly: the balanced-args reader now returns the decorator's closing-paren offset, and the handler scan starts there, so @Get() list() { ... } binds list, not the next method. Your exact snippet is a test (both decorators on one line, both routes, right handlers).

2. { path: CONSTANT } — an object with a path key whose value is not a string literal now skips the controller's routes, same as the bare-constant form; { host: '…' } (no path key) stays unprefixed as you confirmed. Test covers both plus the reset-after-skip ordering.

3. Rebase + CHANGELOG — rebased onto current main; the registry keeps all three resolvers ([expressResolver, nextjsResolver, nestjsResolver]), and a full CHANGELOG entry was added under ## [Unreleased] → ### Added.

The smaller items, since they were one-liners: trailing slash on the controller prefix is trimmed before joining (/users/ + /:id/ → GET /users/:id, tested), and backtick paths containing ${ are treated as unreadable and skipped rather than emitted verbatim (tested). The multi-line @Controller({…}) object and array method paths remain follow-ups as you suggested.

CI: all checks green on the rebased head (check 22.22.0/24, hub-browser, release-performance, storage-portability macos+windows). Ready for re-review when you get a moment — thanks for the precise probes, the inline-decorator catch in particular was a real regression I introduced.