@oculum/scanner 1.0.12 → 1.0.13

package/src/model/module-graph.ts

@@ -0,0 +1,254 @@
+/**
+ * Module Graph — Build a project-wide dependency graph from import/export statements.
+ *
+ * Provides forward edges (depends-on) and reverse edges (imported-by) for
+ * cross-file analysis. Detects circular imports via DFS.
+ */
+
+import type { ScanFile } from '../shared/types'
+import {
+  extractAllImports,
+  extractExports,
+  resolveImportPath,
+  buildFileIndex,
+} from './import-resolver'
+import type { ParsedImport, ParsedExport } from './import-resolver'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ResolvedImport extends ParsedImport {
+  resolvedPath: string | null   // null if unresolved (node_modules, missing)
+}
+
+export interface ModuleNode {
+  filePath: string
+  imports: ResolvedImport[]
+  exports: ParsedExport[]
+  dependsOn: Set<string>         // forward edges (resolved file paths)
+  importedBy: Set<string>        // reverse edges
+}
+
+export interface ModuleGraphStats {
+  totalFiles: number
+  totalEdges: number
+  circularImportCount: number
+  duration: number
+}
+
+export interface ModuleGraph {
+  nodes: Map<string, ModuleNode>
+  circularImports: Set<string>    // files participating in circular deps
+  stats: ModuleGraphStats
+}
+
+// ============================================================================
+// Graph Construction
+// ============================================================================
+
+const CODE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.py'])
+
+function isCodeFile(filePath: string): boolean {
+  const ext = filePath.substring(filePath.lastIndexOf('.'))
+  return CODE_EXTENSIONS.has(ext.toLowerCase())
+}
+
+/**
+ * Build a project-wide module graph from scanned files.
+ *
+ * For each code file: extract imports, resolve paths, extract exports.
+ * Build forward (dependsOn) and reverse (importedBy) edges.
+ * Detect circular imports via DFS.
+ */
+export function buildModuleGraph(files: ScanFile[]): ModuleGraph {
+  const startTime = Date.now()
+  const fileIndex = buildFileIndex(files)
+  const nodes = new Map<string, ModuleNode>()
+  let totalEdges = 0
+
+  // Phase 1: Build nodes with imports and exports
+  for (const file of files) {
+    if (!isCodeFile(file.path)) continue
+
+    const imports = extractAllImports(file.content, file.path)
+    const fileExports = extractExports(file.content, file.path)
+
+    const resolvedImports: ResolvedImport[] = imports
+      .filter(imp => imp.isLocal)
+      .map(imp => {
+        const resolved = resolveImportPath(imp.importPath, file.path, fileIndex)
+        return {
+          ...imp,
+          resolvedPath: resolved?.path ?? null,
+        }
+      })
+
+    const dependsOn = new Set<string>()
+    for (const ri of resolvedImports) {
+      if (ri.resolvedPath) {
+        dependsOn.add(ri.resolvedPath)
+        totalEdges++
+      }
+    }
+
+    nodes.set(file.path, {
+      filePath: file.path,
+      imports: resolvedImports,
+      exports: fileExports,
+      dependsOn,
+      importedBy: new Set(),
+    })
+  }
+
+  // Phase 2: Build reverse edges
+  for (const [filePath, node] of nodes) {
+    for (const dep of node.dependsOn) {
+      const depNode = nodes.get(dep)
+      if (depNode) {
+        depNode.importedBy.add(filePath)
+      }
+    }
+  }
+
+  // Phase 3: Detect circular imports via DFS
+  const circularImports = detectCircularImports(nodes)
+
+  return {
+    nodes,
+    circularImports,
+    stats: {
+      totalFiles: nodes.size,
+      totalEdges,
+      circularImportCount: circularImports.size,
+      duration: Date.now() - startTime,
+    },
+  }
+}
+
+// ============================================================================
+// Symbol Resolution
+// ============================================================================
+
+/**
+ * Resolve what file and export an imported symbol refers to.
+ * Follows one-hop re-exports through barrel files.
+ */
+export function resolveImportedName(
+  graph: ModuleGraph,
+  fromFile: string,
+  importedName: string
+): { filePath: string; exportName: string } | null {
+  const node = graph.nodes.get(fromFile)
+  if (!node) return null
+
+  // Find the import that provides this name
+  for (const imp of node.imports) {
+    if (!imp.resolvedPath) continue
+
+    // Check if this import provides the requested name
+    const providesName = imp.importedNames.includes(importedName) ||
+      (imp.isNamespace && imp.importedNames[0] === importedName) ||
+      (importedName === 'default' && imp.importedNames.includes('default'))
+
+    if (!providesName) continue
+
+    const targetNode = graph.nodes.get(imp.resolvedPath)
+    if (!targetNode) return { filePath: imp.resolvedPath, exportName: importedName }
+
+    // Check if target directly exports this name
+    const directExport = targetNode.exports.find(e =>
+      e.name === importedName || (importedName === 'default' && e.isDefault)
+    )
+
+    if (directExport) {
+      // If it's a re-export, follow one hop
+      if (directExport.kind === 'reexport' && directExport.sourceModule) {
+        const reExportTarget = findReExportTarget(graph, imp.resolvedPath, directExport)
+        if (reExportTarget) return reExportTarget
+      }
+      return { filePath: imp.resolvedPath, exportName: directExport.name }
+    }
+
+    // Target might be a barrel file — check re-exports
+    for (const exp of targetNode.exports) {
+      if (exp.kind === 'reexport' && exp.name === importedName && exp.sourceModule) {
+        const reExportTarget = findReExportTarget(graph, imp.resolvedPath, exp)
+        if (reExportTarget) return reExportTarget
+      }
+    }
+
+    // Name not found in exports but import resolved — return best guess
+    return { filePath: imp.resolvedPath, exportName: importedName }
+  }
+
+  return null
+}
+
+function findReExportTarget(
+  graph: ModuleGraph,
+  fromFile: string,
+  exp: ParsedExport
+): { filePath: string; exportName: string } | null {
+  if (!exp.sourceModule) return null
+
+  const fromNode = graph.nodes.get(fromFile)
+  if (!fromNode) return null
+
+  // Find the resolved import matching the re-export source
+  for (const imp of fromNode.imports) {
+    if (imp.importPath === exp.sourceModule && imp.resolvedPath) {
+      return { filePath: imp.resolvedPath, exportName: exp.name }
+    }
+  }
+
+  // If we have a re-export import in the node's import list
+  for (const imp of fromNode.imports) {
+    if (imp.isReExport && imp.importPath === exp.sourceModule && imp.resolvedPath) {
+      return { filePath: imp.resolvedPath, exportName: exp.name }
+    }
+  }
+
+  return null
+}
+
+// ============================================================================
+// Circular Import Detection
+// ============================================================================
+
+function detectCircularImports(nodes: Map<string, ModuleNode>): Set<string> {
+  const circular = new Set<string>()
+  const visited = new Set<string>()
+  const inStack = new Set<string>()
+
+  function dfs(filePath: string): void {
+    if (inStack.has(filePath)) {
+      circular.add(filePath)
+      return
+    }
+    if (visited.has(filePath)) return
+
+    visited.add(filePath)
+    inStack.add(filePath)
+
+    const node = nodes.get(filePath)
+    if (node) {
+      for (const dep of node.dependsOn) {
+        if (inStack.has(dep)) {
+          circular.add(filePath)
+          circular.add(dep)
+        } else {
+          dfs(dep)
+        }
+      }
+    }
+
+    inStack.delete(filePath)
+  }
+
+  for (const filePath of nodes.keys()) {
+    dfs(filePath)
+  }
+
+  return circular
+}

package/src/{utils → model}/oauth-flow-detector.ts

@@ -4,7 +4,7 @@
  * to prevent false positives when state is implemented correctly but split across files.
  */
 
-import type { ScanFile } from '../types'
+import type { ScanFile } from '../shared/types'
 
 export interface OAuthFlowContext {
   /** Whether state generation is detected in any file */

package/src/{utils/project-context-builder.ts → model/project-context.ts}

@@ -13,7 +13,7 @@
  * - Framework detection
  */
 
-import type { ScanFile } from '../types'
+import type { ScanFile } from '../shared/types'
 import { detectGlobalAuthMiddleware, detectUserScopingPatterns, type MiddlewareAuthConfig } from './middleware-detector'
 import { detectAuthHelpers, type AuthHelperContext, type AuthHelper } from './auth-helper-detector'
 import { detectOAuthFlow, isOAuthStateImplemented, getOAuthFlowSummary, type OAuthFlowContext } from './oauth-flow-detector'

package/src/model/route-auth-resolver.ts

@@ -0,0 +1,216 @@
+/**
+ * Route Auth Resolver
+ *
+ * Resolves authentication chains for discovered routes by combining
+ * multiple auth signals: direct middleware, mount-level, global,
+ * filesystem middleware, route hierarchy, and throwing auth helpers.
+ */
+
+import type { ScanFile } from '../shared/types'
+import type { RouteMap, RouteDefinition, MountPoint } from './route-discovery'
+import type { MiddlewareAuthConfig } from './middleware-detector'
+import { isRouteProtectedByMiddleware } from './middleware-detector'
+import { getRouteProtectionContext } from './route-hierarchy'
+import { extractBlock } from './route-discovery/utils'
+import type { ModuleGraph } from './module-graph'
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Pattern to identify auth-enforcing middleware.
+ * Must be specific to avoid false positives on generic middleware names like
+ * "verify" (could be challenge verification), "session" (could be session tracking).
+ *
+ * Strategy: Match "auth" as a prefix/component in any position (handles camelCase
+ * like authMiddleware, passportAuth, isAuthenticated). Also match specific
+ * non-auth-prefixed terms (verifyToken, jwtVerify, clerk, etc.).
+ * Does NOT match generic "verify", "guard", "require", "session", "protect" alone.
+ */
+const AUTH_MIDDLEWARE_PATTERN = /auth|isAuthorized|isAuthenticated|passport|verifyToken|verifyJwt|jwtAuth|jwtVerify|bearerAuth|clerk/i
+
+const THROWING_AUTH_PATTERNS = [
+  /getCurrentUser(?:Id)?\s*\(/,
+  /auth\(\)\.protect/,
+  /requireAuth\s*\(/,
+  /getSession\s*\(/,
+  /assertAuthenticated\s*\(/,
+  /ensureAuth\s*\(/,
+]
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Resolve auth middleware for all routes in the route map.
+ *
+ * Resolution sources (priority order):
+ * 1. Direct middleware on route definition (already populated by extractors)
+ * 2. Mount-level middleware (app.use('/api', authMw))
+ * 2.5. Cross-file mount auth (file B imported by A which has mount-level auth)
+ * 3. Global middleware (app.use(authMw))
+ * 4. Next.js filesystem middleware (via isRouteProtectedByMiddleware)
+ * 5. Route hierarchy (via getRouteProtectionContext)
+ * 6. Throwing auth helpers in handler body
+ *
+ * Returns a new RouteMap with authMiddleware populated.
+ */
+export function resolveRouteAuth(
+  routeMap: RouteMap,
+  mountPoints: MountPoint[],
+  files: ScanFile[],
+  middlewareConfig: MiddlewareAuthConfig,
+  moduleGraph?: ModuleGraph
+): RouteMap {
+  const fileContentMap = new Map(files.map(f => [f.path, f.content]))
+
+  const resolvedRoutes = routeMap.routes.map(route => {
+    const resolved = { ...route, authMiddleware: [...route.authMiddleware] }
+
+    // 2. Mount-level middleware
+    const mountAuth = findMountLevelAuth(route.path, mountPoints)
+    for (const mw of mountAuth) {
+      if (!resolved.authMiddleware.includes(mw)) {
+        resolved.authMiddleware.push(mw)
+      }
+    }
+
+    // 2.5. Cross-file mount auth (if module graph available)
+    if (moduleGraph && resolved.authMiddleware.length === 0) {
+      const crossFileAuth = findCrossFileMountAuth(route, moduleGraph, mountPoints)
+      for (const mw of crossFileAuth) {
+        if (!resolved.authMiddleware.includes(mw)) {
+          resolved.authMiddleware.push(mw)
+        }
+      }
+    }
+
+    // 3. Global middleware
+    const globalAuth = findGlobalAuth(mountPoints)
+    for (const mw of globalAuth) {
+      if (!resolved.authMiddleware.includes(mw)) {
+        resolved.authMiddleware.push(mw)
+      }
+    }
+
+    // 4. Next.js middleware.ts protection (uses the full path matching from middleware-detector)
+    if (middlewareConfig.hasAuthMiddleware) {
+      const mwResult = isRouteProtectedByMiddleware(route.path, middlewareConfig)
+      if (mwResult.isProtected) {
+        const mwLabel = `middleware.ts:${middlewareConfig.authType || 'unknown'}`
+        if (!resolved.authMiddleware.includes(mwLabel)) {
+          resolved.authMiddleware.push(mwLabel)
+        }
+      }
+    }
+
+    // 5. Route hierarchy (filesystem-based protection groups)
+    const hierarchy = getRouteProtectionContext(route.filePath)
+    if (hierarchy.isInProtectedHierarchy) {
+      for (const source of hierarchy.protectionSource) {
+        if (!resolved.authMiddleware.includes(source)) {
+          resolved.authMiddleware.push(source)
+        }
+      }
+    }
+
+    // 6. Throwing auth helpers in handler body
+    const content = fileContentMap.get(route.filePath)
+    if (content && resolved.authMiddleware.length === 0) {
+      const handlerContent = extractHandlerContent(content, route.handlerLine)
+      if (hasThrowingAuthHelper(handlerContent)) {
+        resolved.authMiddleware.push('throwing_auth_helper')
+      }
+    }
+
+    return resolved
+  })
+
+  // Rebuild fileToRoutes
+  const fileToRoutes = new Map<string, RouteDefinition[]>()
+  for (const route of resolvedRoutes) {
+    const existing = fileToRoutes.get(route.filePath) || []
+    existing.push(route)
+    fileToRoutes.set(route.filePath, existing)
+  }
+
+  return { routes: resolvedRoutes, fileToRoutes }
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+/**
+ * Find auth middleware from files that import the route's file.
+ * If server.ts has app.use('/api', authMw, require('./routes/api')) and
+ * routes/api.ts defines routes, those routes inherit the mount-level auth.
+ */
+function findCrossFileMountAuth(
+  route: RouteDefinition,
+  graph: ModuleGraph,
+  mountPoints: MountPoint[]
+): string[] {
+  const authMiddleware: string[] = []
+  const node = graph.nodes.get(route.filePath)
+  if (!node) return authMiddleware
+
+  // Check files that import this route's file
+  for (const importerPath of node.importedBy) {
+    // Find mount points in the importing file that have auth middleware
+    const importerMounts = mountPoints.filter(mp => mp.filePath === importerPath)
+    for (const mount of importerMounts) {
+      if (mount.isGlobal) continue
+      // Check if the route path matches the mount path (with boundary check)
+      if (route.path === mount.path || route.path.startsWith(mount.path + '/')) {
+        const authMw = mount.middleware.filter(m => AUTH_MIDDLEWARE_PATTERN.test(m))
+        for (const mw of authMw) {
+          if (!authMiddleware.includes(mw)) {
+            authMiddleware.push(`cross-file:${mw}`)
+          }
+        }
+      }
+    }
+  }
+
+  return authMiddleware
+}
+
+function findMountLevelAuth(routePath: string, mountPoints: MountPoint[]): string[] {
+  const authMiddleware: string[] = []
+
+  for (const mount of mountPoints) {
+    if (mount.isGlobal) continue
+    // Check if the route path matches the mount path (with boundary check)
+    if (routePath === mount.path || routePath.startsWith(mount.path + '/')) {
+      const authMw = mount.middleware.filter(m => AUTH_MIDDLEWARE_PATTERN.test(m))
+      authMiddleware.push(...authMw)
+    }
+  }
+
+  return authMiddleware
+}
+
+function findGlobalAuth(mountPoints: MountPoint[]): string[] {
+  const authMiddleware: string[] = []
+
+  for (const mount of mountPoints) {
+    if (!mount.isGlobal) continue
+    const authMw = mount.middleware.filter(m => AUTH_MIDDLEWARE_PATTERN.test(m))
+    authMiddleware.push(...authMw)
+  }
+
+  return authMiddleware
+}
+
+function extractHandlerContent(content: string, handlerLine: number): string {
+  const lines = content.split('\n')
+  const start = Math.max(0, handlerLine - 1)
+  return extractBlock(lines, start)
+}
+
+function hasThrowingAuthHelper(content: string): boolean {
+  return THROWING_AUTH_PATTERNS.some(p => p.test(content))
+}