@oculum/scanner 1.0.12 → 1.0.13

package/src/model/route-discovery/express.ts

@@ -0,0 +1,251 @@
+/**
+ * Express/Fastify/Hono/Koa Route Extractor
+ *
+ * Detects route definitions and mount points from Express-style frameworks.
+ * Also handles Fastify (preHandler), Hono, and Koa route patterns.
+ */
+
+import type { RouteDefinition, RouteInput, MountPoint, RouteFramework } from './types'
+import { extractBlock } from './utils'
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'all']
+
+const RATE_LIMIT_PATTERN = /rateLimit|rateLimiter|throttle|slowDown/i
+
+const PUBLIC_ENDPOINT_PATTERN = /^\/(health|healthz|ready|readyz|ping|status|favicon\.ico|robots\.txt|sitemap\.xml|\.well-known)\/?$/i
+
+/**
+ * Pattern to identify auth-enforcing middleware on routes.
+ * Must be specific — "verify" alone matches too broadly (e.g., verify.challengeChecks).
+ */
+const AUTH_MIDDLEWARE_PATTERN = /auth|isAuthorized|isAuthenticated|isAccounting|isAdmin|isDeluxe|passport|verifyToken|verifyJwt|jwtAuth|jwtVerify|bearerAuth|clerk|denyAll/i
+
+// Input source patterns to scan for in handler bodies
+const INPUT_PATTERNS: Array<{ pattern: RegExp; source: RouteInput['source'] }> = [
+  { pattern: /req\.body|request\.body|ctx\.request\.body|c\.req\.json|c\.req\.parseBody/i, source: 'body' },
+  { pattern: /req\.query|request\.query|ctx\.query|c\.req\.query|searchParams/i, source: 'query' },
+  { pattern: /req\.params|request\.params|ctx\.params|c\.req\.param/i, source: 'params' },
+  { pattern: /req\.headers|request\.headers|ctx\.headers|c\.req\.header/i, source: 'headers' },
+  { pattern: /req\.cookies|request\.cookies|ctx\.cookies/i, source: 'cookies' },
+  { pattern: /req\.files?|request\.files?|multer|upload\./i, source: 'files' },
+]
+
+// ============================================================================
+// Route Extraction
+// ============================================================================
+
+/**
+ * Extract Express/Fastify/Hono/Koa routes from file content.
+ *
+ * Patterns detected:
+ * - app.get('/path', handler) / router.post(...) / server.put(...)
+ * - Fastify route({ method, url, preHandler, handler })
+ * - Hono app.get('/path', handler)
+ */
+export function extractExpressRoutes(content: string, filePath: string): RouteDefinition[] {
+  const routes: RouteDefinition[] = []
+  const lines = content.split('\n')
+  const framework = detectExpressFamily(content)
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const lineNum = i + 1
+
+    // Pattern: <identifier>.get('/path', ...middleware, handler)
+    // Matches any receiver (app, router, server, custom names) calling an HTTP method
+    // with a path argument starting with '/'
+    const routeMatch = line.match(
+      /\b\w+\s*\.\s*(get|post|put|patch|delete|head|options|all)\s*\(\s*['"`]([^'"`]+)['"`]/i
+    )
+
+    if (routeMatch && routeMatch[2].startsWith('/')) {
+      const method = routeMatch[1].toUpperCase()
+      const path = routeMatch[2]
+      const middleware = extractMiddlewareFromLine(line)
+      const handlerBody = extractHandlerBody(lines, i)
+      const inputs = detectInputSources(handlerBody)
+
+      routes.push({
+        filePath,
+        methods: [method],
+        path,
+        handler: extractHandlerName(line) || 'anonymous',
+        handlerLine: lineNum,
+        framework,
+        authMiddleware: middleware.filter(m => AUTH_MIDDLEWARE_PATTERN.test(m)),
+        rateLimiting: middleware.some(m => RATE_LIMIT_PATTERN.test(m)) ||
+                      RATE_LIMIT_PATTERN.test(handlerBody),
+        isPublic: PUBLIC_ENDPOINT_PATTERN.test(path),
+        inputs,
+      })
+      continue
+    }
+
+    // Fastify route object pattern: server.route({ method: 'GET', url: '/path', ... })
+    const fastifyMatch = line.match(/\.route\s*\(\s*\{/)
+    if (fastifyMatch) {
+      const blockText = extractBlock(lines, i)
+      const methodMatch = blockText.match(/method\s*:\s*['"`](\w+)['"`]/)
+      const urlMatch = blockText.match(/url\s*:\s*['"`]([^'"`]+)['"`]/)
+      if (methodMatch && urlMatch) {
+        const preHandlerMatch = blockText.match(/preHandler\s*:\s*\[([^\]]*)\]/)
+        const preHandlerMiddleware = preHandlerMatch
+          ? preHandlerMatch[1].split(',').map(m => m.trim()).filter(Boolean)
+          : []
+        const inputs = detectInputSources(blockText)
+
+        routes.push({
+          filePath,
+          methods: [methodMatch[1].toUpperCase()],
+          path: urlMatch[1],
+          handler: 'route_handler',
+          handlerLine: lineNum,
+          framework: 'fastify',
+          authMiddleware: preHandlerMiddleware.filter(m => AUTH_MIDDLEWARE_PATTERN.test(m)),
+          rateLimiting: preHandlerMiddleware.some(m => RATE_LIMIT_PATTERN.test(m)),
+          isPublic: PUBLIC_ENDPOINT_PATTERN.test(urlMatch[1]),
+          inputs,
+        })
+      }
+    }
+  }
+
+  return routes
+}
+
+// ============================================================================
+// Mount Point Extraction
+// ============================================================================
+
+/**
+ * Extract mount points (app.use) from file content.
+ *
+ * Patterns:
+ * - app.use('/api', authMiddleware) — path-scoped mount
+ * - app.use(helmet()) — global mount (no path)
+ */
+export function extractMountPoints(content: string, filePath: string): MountPoint[] {
+  const mounts: MountPoint[] = []
+  const lines = content.split('\n')
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const lineNum = i + 1
+
+    // app.use('/path', middleware) — path-scoped
+    const scopedMatch = line.match(
+      /(?:app|router|server)\s*\.use\s*\(\s*['"`]([^'"`]+)['"`]\s*,\s*(.+)\)/
+    )
+    if (scopedMatch) {
+      const middleware = extractMiddlewareNames(scopedMatch[2])
+      if (middleware.length > 0) {
+        mounts.push({
+          path: scopedMatch[1],
+          middleware,
+          line: lineNum,
+          isGlobal: false,
+          filePath,
+        })
+      }
+      continue
+    }
+
+    // app.use(middleware) — global (no path argument)
+    // Check that line has .use( but no string as first argument
+    const globalUseMatch = line.match(/(?:app|router|server)\s*\.use\s*\(/)
+    if (globalUseMatch && !scopedMatch) {
+      // Verify no string path (already handled above)
+      const afterUse = line.slice(line.indexOf('.use(') + 5)
+      if (!/^\s*['"`]/.test(afterUse)) {
+        // Extract middleware names from the arguments
+        const argsStr = extractParenContent(line, line.indexOf('.use(') + 4)
+        const middleware = extractMiddlewareNames(argsStr)
+        if (middleware.length > 0) {
+          mounts.push({
+            path: '/',
+            middleware,
+            line: lineNum,
+            isGlobal: true,
+            filePath,
+          })
+        }
+      }
+    }
+  }
+
+  return mounts
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+function detectExpressFamily(content: string): RouteFramework {
+  if (/require\s*\(\s*['"]fastify['"]\)|from\s+['"]fastify['"]/.test(content)) return 'fastify'
+  if (/require\s*\(\s*['"]hono['"]\)|from\s+['"]hono['"]/.test(content)) return 'hono'
+  if (/require\s*\(\s*['"]koa['"]\)|from\s+['"]koa['"]/.test(content)) return 'koa'
+  return 'express'
+}
+
+function extractMiddlewareFromLine(line: string): string[] {
+  // Extract arguments between the path string and the last argument (handler)
+  // e.g., app.post('/path', auth, validate, handler) → ['auth', 'validate']
+  const afterPath = line.replace(/^[^(]*\(\s*['"`][^'"`]*['"`]\s*,\s*/, '')
+  const args = afterPath.replace(/\)\s*;?\s*$/, '').split(',').map(a => a.trim()).filter(Boolean)
+  // Remove the last argument (the handler function) if there are multiple
+  if (args.length > 1) {
+    return args.slice(0, -1).map(a => a.replace(/\(.*\)/, '').trim())
+  }
+  return []
+}
+
+function extractHandlerName(line: string): string | null {
+  // Look for named function reference as last argument
+  const match = line.match(/,\s*(\w+)\s*\)\s*;?\s*$/)
+  if (match && !match[1].match(/^(async|function|req|res|next|ctx|c)$/)) {
+    return match[1]
+  }
+  return null
+}
+
+function extractParenContent(line: string, openParenIndex: number): string {
+  let depth = 0
+  let start = openParenIndex + 1
+  for (let i = openParenIndex; i < line.length; i++) {
+    if (line[i] === '(') depth++
+    if (line[i] === ')') {
+      depth--
+      if (depth === 0) {
+        return line.slice(start, i)
+      }
+    }
+  }
+  return line.slice(start)
+}
+
+function extractMiddlewareNames(text: string): string[] {
+  return text
+    .split(',')
+    .map(m => m.trim().replace(/\(.*\)/, '').trim())
+    .filter(m => m.length > 0 && /^[a-zA-Z_$]/.test(m))
+}
+
+function extractHandlerBody(lines: string[], startLine: number): string {
+  return extractBlock(lines, startLine)
+}
+
+function detectInputSources(body: string): RouteInput[] {
+  const inputs: RouteInput[] = []
+  const seen = new Set<string>()
+  for (const { pattern, source } of INPUT_PATTERNS) {
+    if (pattern.test(body) && !seen.has(source)) {
+      seen.add(source)
+      inputs.push({ source })
+    }
+  }
+  return inputs
+}

package/src/model/route-discovery/index.ts

@@ -0,0 +1,83 @@
+/**
+ * Route Discovery Orchestrator
+ *
+ * Runs all framework-specific route extractors, deduplicates routes,
+ * and builds the unified RouteMap.
+ */
+
+import type { ScanFile } from '../../shared/types'
+import type { RouteMap, RouteDefinition, MountPoint } from './types'
+import { createEmptyRouteMap } from './types'
+import { extractExpressRoutes, extractMountPoints } from './express'
+import { extractNextJSRoutes } from './nextjs'
+import { extractPythonRoutes } from './python'
+
+// Re-export types for convenience
+export type { RouteMap, RouteDefinition, RouteInput, MountPoint, RouteFramework } from './types'
+export { createEmptyRouteMap } from './types'
+
+/**
+ * Discover all routes across all supported frameworks.
+ *
+ * Runs Express, Next.js, and Python extractors, deduplicates,
+ * and builds the fileToRoutes index.
+ */
+export function discoverRoutes(
+  files: ScanFile[],
+  frameworkPrimary: string | undefined
+): { routeMap: RouteMap; mountPoints: MountPoint[] } {
+  const allRoutes: RouteDefinition[] = []
+  const allMountPoints: MountPoint[] = []
+
+  for (const file of files) {
+    // Express/Fastify/Hono/Koa
+    const expressRoutes = extractExpressRoutes(file.content, file.path)
+    allRoutes.push(...expressRoutes)
+
+    const mounts = extractMountPoints(file.content, file.path)
+    allMountPoints.push(...mounts)
+
+    // Python (Flask/Django)
+    const pythonRoutes = extractPythonRoutes(file.content, file.path)
+    allRoutes.push(...pythonRoutes)
+  }
+
+  // Next.js (needs all files at once for filesystem-based routing)
+  const nextjsRoutes = extractNextJSRoutes(files, frameworkPrimary)
+  allRoutes.push(...nextjsRoutes)
+
+  // Deduplicate: same file + path + method combo
+  const deduped = deduplicateRoutes(allRoutes)
+
+  // Build fileToRoutes index
+  const fileToRoutes = new Map<string, RouteDefinition[]>()
+  for (const route of deduped) {
+    const existing = fileToRoutes.get(route.filePath) || []
+    existing.push(route)
+    fileToRoutes.set(route.filePath, existing)
+  }
+
+  return {
+    routeMap: { routes: deduped, fileToRoutes },
+    mountPoints: allMountPoints,
+  }
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+function deduplicateRoutes(routes: RouteDefinition[]): RouteDefinition[] {
+  const seen = new Set<string>()
+  const result: RouteDefinition[] = []
+
+  for (const route of routes) {
+    const key = `${route.filePath}:${route.path}:${[...route.methods].sort().join(',')}`
+    if (!seen.has(key)) {
+      seen.add(key)
+      result.push(route)
+    }
+  }
+
+  return result
+}

package/src/model/route-discovery/nextjs.ts

@@ -0,0 +1,216 @@
+/**
+ * Next.js Route Extractor
+ *
+ * Detects routes from Next.js App Router and Pages Router conventions.
+ * Derives route paths from the filesystem structure.
+ */
+
+import type { ScanFile } from '../../shared/types'
+import type { RouteDefinition, RouteInput, RouteFramework } from './types'
+import { getRouteProtectionContext } from '../route-hierarchy'
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const APP_ROUTER_ROUTE_FILE = /\/app\/(.+)\/route\.(ts|js|tsx|jsx)$/
+const PAGES_API_FILE = /\/pages\/api\/(.+)\.(ts|js|tsx|jsx)$/
+
+const PUBLIC_ENDPOINT_PATTERN = /^\/(health|healthz|ready|readyz|ping|status|favicon\.ico|robots\.txt|sitemap\.xml|\.well-known)\/?$/i
+
+const DEFAULT_HANDLER_EXPORT = /export\s+default\s+(?:async\s+)?function\s*(\w*)/
+
+// Input source patterns for Next.js handlers
+const NEXTJS_INPUT_PATTERNS: Array<{ pattern: RegExp; source: RouteInput['source'] }> = [
+  { pattern: /request\.json\(\)|req\.body|await\s+request\.json/i, source: 'body' },
+  { pattern: /searchParams|nextUrl\.searchParams|url\.searchParams|req\.query/i, source: 'query' },
+  { pattern: /params\.|context\.params|props\.params/i, source: 'params' },
+  { pattern: /request\.headers|req\.headers|headers\(\)/i, source: 'headers' },
+  { pattern: /cookies\(\)|request\.cookies|req\.cookies/i, source: 'cookies' },
+  { pattern: /formData\(\)|request\.formData/i, source: 'files' },
+]
+
+// ============================================================================
+// Route Extraction
+// ============================================================================
+
+/**
+ * Extract Next.js routes from scanned files.
+ *
+ * Detects App Router (export function GET/POST in route files)
+ * and Pages Router (export default in pages/api files).
+ */
+export function extractNextJSRoutes(
+  files: ScanFile[],
+  frameworkPrimary: string | undefined
+): RouteDefinition[] {
+  // Only run for Next.js projects (or if framework not detected, try anyway)
+  if (frameworkPrimary && frameworkPrimary !== 'nextjs') return []
+
+  const routes: RouteDefinition[] = []
+
+  for (const file of files) {
+    // App Router route files
+    const appMatch = file.path.match(APP_ROUTER_ROUTE_FILE)
+    if (appMatch) {
+      const routePath = deriveAppRouterPath(appMatch[1])
+      const methods = extractExportedMethods(file.content)
+      const protection = getRouteProtectionContext(file.path)
+      const inputs = detectNextJSInputSources(file.content)
+
+      if (methods.length === 0) continue
+
+      for (const method of methods) {
+        routes.push({
+          filePath: file.path,
+          methods: [method.name],
+          path: routePath,
+          handler: method.name,
+          handlerLine: method.line,
+          framework: 'nextjs_app',
+          authMiddleware: protection.isInProtectedHierarchy ? protection.protectionSource : [],
+          rateLimiting: false,
+          isPublic: PUBLIC_ENDPOINT_PATTERN.test(routePath),
+          inputs,
+        })
+      }
+      continue
+    }
+
+    // Pages Router API files
+    const pagesMatch = file.path.match(PAGES_API_FILE)
+    if (pagesMatch) {
+      const routePath = derivePagesRouterPath(pagesMatch[1])
+      const handlerLine = findDefaultExportLine(file.content)
+      const inputs = detectNextJSInputSources(file.content)
+      const methods = detectPagesRouterMethods(file.content)
+
+      routes.push({
+        filePath: file.path,
+        methods,
+        path: routePath,
+        handler: 'default',
+        handlerLine,
+        framework: 'nextjs_pages',
+        authMiddleware: [],
+        rateLimiting: false,
+        isPublic: PUBLIC_ENDPOINT_PATTERN.test(routePath),
+        inputs,
+      })
+    }
+  }
+
+  return routes
+}
+
+// ============================================================================
+// Path Derivation
+// ============================================================================
+
+/**
+ * Derive API path from App Router filesystem path.
+ * e.g., "api/users/[id]/route.ts" → "/api/users/:id"
+ *
+ * - Dynamic segments [id] → :id
+ * - Catch-all [...slug] → :slug*
+ * - Optional catch-all [[...slug]] → :slug*
+ * - Route groups (dashboard) are stripped
+ */
+function deriveAppRouterPath(relativePath: string): string {
+  let path = '/' + relativePath
+    // Strip route groups like (dashboard), (auth)
+    .replace(/\([^)]+\)\//g, '')
+    // Optional catch-all [[...param]]
+    .replace(/\[\[\.\.\.(\w+)\]\]/g, ':$1*')
+    // Catch-all [...param]
+    .replace(/\[\.\.\.(\w+)\]/g, ':$1*')
+    // Dynamic segments [param]
+    .replace(/\[(\w+)\]/g, ':$1')
+
+  // Clean up double slashes
+  path = path.replace(/\/+/g, '/')
+  // Remove trailing slash
+  if (path.length > 1 && path.endsWith('/')) {
+    path = path.slice(0, -1)
+  }
+
+  return path
+}
+
+/**
+ * Derive API path from Pages Router filesystem path.
+ * e.g., "users/[id]" → "/api/users/:id"
+ */
+function derivePagesRouterPath(relativePath: string): string {
+  let path = '/api/' + relativePath
+    .replace(/\[\.\.\.(\w+)\]/g, ':$1*')
+    .replace(/\[(\w+)\]/g, ':$1')
+
+  // Remove /index suffix
+  path = path.replace(/\/index$/, '')
+
+  // Clean up
+  path = path.replace(/\/+/g, '/')
+  if (path.length > 1 && path.endsWith('/')) {
+    path = path.slice(0, -1)
+  }
+
+  return path
+}
+
+// ============================================================================
+// Content Analysis
+// ============================================================================
+
+interface ExportedMethod {
+  name: string
+  line: number
+}
+
+function extractExportedMethods(content: string): ExportedMethod[] {
+  const methods: ExportedMethod[] = []
+  const lines = content.split('\n')
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(/export\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s*\(/)
+    if (match) {
+      methods.push({ name: match[1], line: i + 1 })
+    }
+  }
+
+  return methods
+}
+
+function findDefaultExportLine(content: string): number {
+  const lines = content.split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    if (DEFAULT_HANDLER_EXPORT.test(lines[i])) {
+      return i + 1
+    }
+  }
+  return 1
+}
+
+function detectPagesRouterMethods(content: string): string[] {
+  // Check for explicit method checks in the handler
+  const methodChecks = content.match(/req\.method\s*===?\s*['"`](GET|POST|PUT|PATCH|DELETE)['"`]/gi)
+  if (methodChecks) {
+    return [...new Set(methodChecks.map(m => {
+      const match = m.match(/['"`](GET|POST|PUT|PATCH|DELETE)['"`]/i)
+      return match ? match[1].toUpperCase() : 'ALL'
+    }))]
+  }
+  return ['ALL']
+}
+
+function detectNextJSInputSources(content: string): RouteInput[] {
+  const inputs: RouteInput[] = []
+  const seen = new Set<string>()
+  for (const { pattern, source } of NEXTJS_INPUT_PATTERNS) {
+    if (pattern.test(content) && !seen.has(source)) {
+      seen.add(source)
+      inputs.push({ source })
+    }
+  }
+  return inputs
+}