Discovery miner: TypeScript/JavaScript API routes (Express, Next.js)

[Dimwiddle]

Summary

Extract HTTP route definitions from TypeScript/JavaScript web framework files using tree-sitter. Supports Express and Next.js App Router.

Depends on: #124, #125, #126

New file

src/specleft/discovery/miners/typescript/routes.py

import uuid
from specleft.discovery.models import SupportedLanguage, MinerResult, DiscoveredItem, ItemKind, ApiRouteMeta
from specleft.discovery.context import MinerContext

class TypeScriptRouteMiner:
    miner_id = uuid.UUID("b06e8c32-c793-41dc-91de-12635d6c4f69")
    name = "typescript_api_routes"
    languages = frozenset({SupportedLanguage.TYPESCRIPT, SupportedLanguage.JAVASCRIPT})

    def mine(self, ctx: MinerContext) -> MinerResult: ...

Framework detection

Read from ctx.frameworks.get(SupportedLanguage.TYPESCRIPT, []) / ctx.frameworks.get(SupportedLanguage.JAVASCRIPT, []). Do NOT re-parse package.json.

Detection strategies per framework

Express:
Tree-sitter query on ctx.file_index.files_by_language(SupportedLanguage.TYPESCRIPT) + JAVASCRIPT: call expressions where callee is member expression on app/router, method is get|post|put|patch|delete|use. First string argument is path.

Next.js App Router (file-based):
Use ctx.file_index.files_matching("**/app/**/route.ts", "**/app/**/route.js"). Named exports export async function GET(request) — HTTP method from export name. Path inferred from file path relative to app/: app/users/[id]/route.ts → /users/{id}.

Typed metadata

Each item's metadata dict must conform to ApiRouteMeta:

ApiRouteMeta(
    http_method         = "DELETE",
    path                = "/api/users/{id}",
    framework           = "nextjs",
    handler_name        = "DELETE",
    is_file_based_route = True,
)

name: "{METHOD} {path}"
language: SupportedLanguage.TYPESCRIPT or SupportedLanguage.JAVASCRIPT based on file extension

Acceptance criteria

• router.get("/health", handler) → item with method=GET, path=/health, framework=express
• .ts files get SupportedLanguage.TYPESCRIPT; .js files get SupportedLanguage.JAVASCRIPT
• Each item's metadata validates against ApiRouteMeta
• app/api/users/[id]/route.ts exporting function DELETE → method=DELETE, path=/api/users/{id}, is_file_based_route=True
• Next.js file with multiple exports (GET, POST) produces 2 separate items
• Uses ctx.file_index and ctx.frameworks — no direct filesystem or manifest parsing
• Tests in tests/discovery/miners/test_typescript_routes.py
• Update scenarios and tests in features/feature-spec-discovery.md to cover the functionality introduced by this issue

[Dimwiddle]

Implementation Notes

Branch: codex/130-typescript-api-routes
Approach: Implement a TypeScript/JavaScript route miner that uses shared discovery context (ctx.file_index, ctx.frameworks, ctx.registry) to extract Express and Next.js App Router routes and emit validated ApiRouteMeta metadata.

Decisions

• Use framework gating from ctx.frameworks to avoid scanning unsupported patterns.
• Reuse route path normalization behavior aligned with the Python route miner ([id] -> {id}) for consistency.
• Next.js App Router exports are detected from parsed source text (export function METHOD) while file discovery still uses ctx.file_index and parser validation still flows through ctx.registry.

Tasks

• Implement TypeScriptRouteMiner in src/specleft/discovery/miners/typescript/routes.py
• Wire miner exports/registration into discovery pipeline
• Add unit tests in tests/discovery/miners/test_typescript_routes.py
• Add/adjust TypeScript route fixtures for Express and Next.js patterns
• Update discovery feature scenarios/tests in features/feature-spec-discovery.md
• Run lint and tests for issue acceptance criteria

[Dimwiddle]

Follow-up (deferred): Broader Next.js route coverage

Current miner behavior intentionally focuses on App Router file-based routes (app/**/route.ts|route.js, including src/app/**/...).

If broader Next.js support is needed later, we can extend coverage with:

1. Pages Router support
   • Mine pages/api/** and src/pages/api/** handlers.
2. Configurable Next route roots
   • Add discovery config (e.g. next_route_roots) so projects with custom structure can opt in.
3. Keep App Router constraints
   • Continue requiring file-based route locations for App Router to avoid false positives from generic export function GET/POST patterns.

This is optional and can be implemented in a follow-up issue if/when required.