@oculum/scanner 1.0.11 → 1.0.13

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

@@ -0,0 +1,214 @@
+/**
+ * Python Route Extractor (Flask + Django)
+ *
+ * Detects route definitions from Flask decorators and Django URL patterns.
+ */
+
+import type { RouteDefinition, RouteInput, RouteFramework } from './types'
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const PUBLIC_ENDPOINT_PATTERN = /^\/(health|healthz|ready|readyz|ping|status)\/?$/i
+
+const AUTH_DECORATOR_PATTERN = /login_required|auth_required|requires_auth|permission_required|jwt_required|token_required/i
+
+const RATE_LIMIT_PATTERN = /rate_limit|ratelimit|throttle|limiter/i
+
+const PYTHON_INPUT_PATTERNS: Array<{ pattern: RegExp; source: RouteInput['source'] }> = [
+  { pattern: /request\.json|request\.get_json|request\.data|request\.form|request\.POST|request\.body/i, source: 'body' },
+  { pattern: /request\.args|request\.GET|request\.query_params/i, source: 'query' },
+  { pattern: /request\.view_args|kwargs\[|self\.kwargs/i, source: 'params' },
+  { pattern: /request\.headers|request\.META/i, source: 'headers' },
+  { pattern: /request\.cookies|request\.COOKIES/i, source: 'cookies' },
+  { pattern: /request\.files|request\.FILES/i, source: 'files' },
+]
+
+// ============================================================================
+// Route Extraction
+// ============================================================================
+
+/**
+ * Extract Flask/Django routes from Python file content.
+ *
+ * Detects:
+ * - Flask: @app.route('/path', methods=['GET'])
+ * - Flask: @blueprint.route(...)
+ * - Django: path('api/search/', views.search_view) in urlpatterns
+ */
+export function extractPythonRoutes(content: string, filePath: string): RouteDefinition[] {
+  const routes: RouteDefinition[] = []
+  const ext = filePath.substring(filePath.lastIndexOf('.'))
+  if (ext !== '.py') return routes
+
+  const lines = content.split('\n')
+
+  // Detect Flask routes
+  const flaskRoutes = extractFlaskRoutes(lines, filePath)
+  routes.push(...flaskRoutes)
+
+  // Detect Django URL patterns
+  const djangoRoutes = extractDjangoRoutes(lines, filePath, content)
+  routes.push(...djangoRoutes)
+
+  return routes
+}
+
+// ============================================================================
+// Flask Extraction
+// ============================================================================
+
+function extractFlaskRoutes(lines: string[], filePath: string): RouteDefinition[] {
+  const routes: RouteDefinition[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+
+    // @app.route('/path', methods=['GET', 'POST'])
+    // @blueprint.route('/path')
+    const routeMatch = line.match(
+      /@\s*(?:\w+)\s*\.route\s*\(\s*['"]([^'"]+)['"](?:\s*,\s*methods\s*=\s*\[([^\]]*)\])?\s*\)/
+    )
+
+    if (routeMatch) {
+      const path = routeMatch[1]
+      const methodsStr = routeMatch[2]
+      const methods = methodsStr
+        ? methodsStr.replace(/['"]/g, '').split(',').map(m => m.trim().toUpperCase()).filter(Boolean)
+        : ['GET']
+
+      // Scan decorators above the route for auth/rate-limiting
+      const decorators = collectDecorators(lines, i)
+      const authDecorators = decorators.filter(d => AUTH_DECORATOR_PATTERN.test(d))
+      const hasRateLimit = decorators.some(d => RATE_LIMIT_PATTERN.test(d))
+
+      // Find the function definition below the decorator
+      const handlerInfo = findFunctionBelow(lines, i)
+      const handlerBody = handlerInfo
+        ? extractPythonFunctionBody(lines, handlerInfo.line - 1)
+        : ''
+      const inputs = detectPythonInputSources(handlerBody)
+
+      routes.push({
+        filePath,
+        methods,
+        path: normalizeFlaskPath(path),
+        handler: handlerInfo?.name || 'unknown',
+        handlerLine: handlerInfo?.line || i + 1,
+        framework: 'flask',
+        authMiddleware: authDecorators,
+        rateLimiting: hasRateLimit,
+        isPublic: PUBLIC_ENDPOINT_PATTERN.test(path),
+        inputs,
+      })
+    }
+  }
+
+  return routes
+}
+
+// ============================================================================
+// Django Extraction
+// ============================================================================
+
+function extractDjangoRoutes(lines: string[], filePath: string, fullContent: string): RouteDefinition[] {
+  const routes: RouteDefinition[] = []
+
+  // Only look in files that contain urlpatterns
+  if (!fullContent.includes('urlpatterns')) return routes
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+
+    // path('api/search/', views.search_view, name='search')
+    // path('api/users/<int:pk>/', UserViewSet.as_view())
+    const pathMatch = line.match(
+      /path\s*\(\s*['"]([^'"]*)['"]\s*,\s*([^,)]+)/
+    )
+
+    if (pathMatch) {
+      const routePath = '/' + pathMatch[1].replace(/^\//, '')
+      const viewRef = pathMatch[2].trim()
+
+      routes.push({
+        filePath,
+        methods: ['ALL'], // Django views handle all methods by default
+        path: normalizeDjangoPath(routePath),
+        handler: viewRef.replace(/\.as_view\(\)/, ''),
+        handlerLine: i + 1,
+        framework: 'django',
+        authMiddleware: [],
+        rateLimiting: false,
+        isPublic: PUBLIC_ENDPOINT_PATTERN.test(routePath),
+        inputs: [],
+      })
+    }
+  }
+
+  return routes
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+function collectDecorators(lines: string[], routeDecoratorLine: number): string[] {
+  const decorators: string[] = []
+  // Look backwards from the route decorator for other decorators
+  for (let j = routeDecoratorLine - 1; j >= Math.max(0, routeDecoratorLine - 10); j--) {
+    const trimmed = lines[j].trim()
+    if (trimmed.startsWith('@')) {
+      decorators.push(trimmed)
+    } else if (trimmed.length > 0) {
+      break // Stop at first non-decorator, non-empty line
+    }
+  }
+  // Also look at lines between route decorator and function def
+  for (let j = routeDecoratorLine + 1; j < Math.min(lines.length, routeDecoratorLine + 5); j++) {
+    const trimmed = lines[j].trim()
+    if (trimmed.startsWith('@')) {
+      decorators.push(trimmed)
+    } else if (trimmed.startsWith('def ') || trimmed.startsWith('async def ')) {
+      break
+    }
+  }
+  return decorators
+}
+
+function findFunctionBelow(lines: string[], decoratorLine: number): { name: string; line: number } | null {
+  for (let j = decoratorLine + 1; j < Math.min(lines.length, decoratorLine + 10); j++) {
+    const match = lines[j].match(/(?:async\s+)?def\s+(\w+)\s*\(/)
+    if (match) {
+      return { name: match[1], line: j + 1 }
+    }
+  }
+  return null
+}
+
+function extractPythonFunctionBody(lines: string[], defLineIndex: number): string {
+  const end = Math.min(defLineIndex + 30, lines.length)
+  return lines.slice(defLineIndex, end).join('\n')
+}
+
+function normalizeFlaskPath(path: string): string {
+  // Convert Flask path params <type:name> or <name> to :name
+  return path.replace(/<(?:\w+:)?(\w+)>/g, ':$1')
+}
+
+function normalizeDjangoPath(path: string): string {
+  // Convert Django path params <int:pk> or <str:slug> to :pk / :slug
+  return path.replace(/<(?:\w+:)?(\w+)>/g, ':$1')
+}
+
+function detectPythonInputSources(body: string): RouteInput[] {
+  const inputs: RouteInput[] = []
+  const seen = new Set<string>()
+  for (const { pattern, source } of PYTHON_INPUT_PATTERNS) {
+    if (pattern.test(body) && !seen.has(source)) {
+      seen.add(source)
+      inputs.push({ source })
+    }
+  }
+  return inputs
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Route Discovery Types
+ *
+ * Type definitions for route extraction, mapping, and auth resolution.
+ * Used by CE Phase 2 to provide route context to scoring and AI validation.
+ */
+
+export type RouteFramework =
+  | 'express' | 'nextjs_app' | 'nextjs_pages' | 'fastify'
+  | 'hono' | 'koa' | 'nestjs' | 'django' | 'flask' | 'rails'
+
+export interface RouteDefinition {
+  filePath: string
+  methods: string[]             // ['GET'], ['POST','PUT'], or ['ALL']
+  path: string                  // '/api/users/:id'
+  handler: string               // function name or 'default'
+  handlerLine: number           // 1-based
+  framework: RouteFramework
+  authMiddleware: string[]      // populated by resolver
+  rateLimiting: boolean
+  isPublic: boolean
+  inputs: RouteInput[]
+}
+
+export interface RouteInput {
+  source: 'body' | 'query' | 'params' | 'headers' | 'cookies' | 'files'
+  knownParams?: string[]
+}
+
+export interface RouteMap {
+  routes: RouteDefinition[]
+  fileToRoutes: Map<string, RouteDefinition[]>
+}
+
+export interface MountPoint {
+  path: string
+  middleware: string[]
+  line: number
+  isGlobal: boolean
+  filePath: string
+}
+
+export function createEmptyRouteMap(): RouteMap {
+  return {
+    routes: [],
+    fileToRoutes: new Map(),
+  }
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Route Discovery Utilities
+ *
+ * Shared helpers used across route discovery, scoring, and validation.
+ */
+
+import type { RouteDefinition } from './types'
+
+/**
+ * Find the route whose handler line is closest to (and at or before) the finding line.
+ * Falls back to the closest route overall if none are before the finding.
+ */
+export function findClosestRoute(routes: RouteDefinition[], findingLine: number): RouteDefinition | null {
+  let best: RouteDefinition | null = null
+  let bestDistance = Infinity
+
+  for (const route of routes) {
+    const distance = findingLine - route.handlerLine
+    if (distance >= 0 && distance < bestDistance) {
+      best = route
+      bestDistance = distance
+    }
+  }
+
+  // If no route is before the finding, return the closest one overall
+  if (!best && routes.length > 0) {
+    best = routes.reduce((a, b) =>
+      Math.abs(a.handlerLine - findingLine) < Math.abs(b.handlerLine - findingLine) ? a : b
+    )
+  }
+
+  return best
+}
+
+/**
+ * Extract a brace-delimited block starting from a given line.
+ * Tracks brace depth to find the matching closing brace.
+ * Falls back to 50-line limit if no closing brace is found.
+ */
+export function extractBlock(lines: string[], startLine: number): string {
+  let depth = 0
+  let started = false
+  const result: string[] = []
+  for (let i = startLine; i < Math.min(startLine + 50, lines.length); i++) {
+    const line = lines[i]
+    result.push(line)
+    for (const ch of line) {
+      if (ch === '{') { depth++; started = true }
+      if (ch === '}') depth--
+    }
+    if (started && depth <= 0) break
+  }
+  return result.join('\n')
+}

package/src/model/route-hierarchy.ts

@@ -0,0 +1,250 @@
+/**
+ * Route Hierarchy Utility
+ * Understands framework-specific route hierarchy conventions
+ *
+ * This addresses false positives where routes inside authenticated layouts
+ * are flagged for "missing auth" when they inherit protection from parents.
+ *
+ * Key insight: Modern frameworks use layouts/middleware that protect entire
+ * route subtrees - child routes inherit this protection.
+ */
+
+export interface RouteProtectionContext {
+  /** Whether this route is in a protected hierarchy */
+  isInProtectedHierarchy: boolean
+  /** Sources of protection (e.g., ["Remix _authenticated+ layout"]) */
+  protectionSource: string[]
+  /** Framework detected */
+  framework?: 'remix' | 'nextjs' | 'sveltekit' | 'nuxt' | 'unknown'
+  /** Whether this is in an admin section */
+  isAdminRoute: boolean
+}
+
+/**
+ * Framework-specific route conventions
+ */
+const FRAMEWORK_ROUTE_CONVENTIONS = {
+  remix: {
+    // Pathless layout routes - children inherit from parent
+    protectedLayouts: [
+      { pattern: /_authenticated\+/, name: 'Remix _authenticated+ layout' },
+      { pattern: /\(authenticated\)/, name: 'Remix (authenticated) route group' },
+      { pattern: /_protected\+/, name: 'Remix _protected+ layout' },
+      { pattern: /\(protected\)/, name: 'Remix (protected) route group' },
+      { pattern: /__authenticated/, name: 'Remix __authenticated layout' },
+      { pattern: /_auth\+/, name: 'Remix _auth+ layout' },
+    ],
+    adminLayouts: [
+      { pattern: /admin\+/, name: 'Remix admin+ layout' },
+      { pattern: /\(admin\)/, name: 'Remix (admin) route group' },
+      { pattern: /_admin\+/, name: 'Remix _admin+ layout' },
+      { pattern: /__admin/, name: 'Remix __admin layout' },
+    ],
+    // Detection pattern for Remix routes
+    routeDetection: /routes\//,
+  },
+
+  nextjs: {
+    protectedGroups: [
+      { pattern: /\(authenticated\)/, name: 'Next.js (authenticated) route group' },
+      { pattern: /\(protected\)/, name: 'Next.js (protected) route group' },
+      { pattern: /\(dashboard\)/, name: 'Next.js (dashboard) route group' },
+      { pattern: /\(private\)/, name: 'Next.js (private) route group' },
+      { pattern: /\(secure\)/, name: 'Next.js (secure) route group' },
+      { pattern: /\(user\)/, name: 'Next.js (user) route group' },
+      { pattern: /\(account\)/, name: 'Next.js (account) route group' },
+      { pattern: /\(app\)/, name: 'Next.js (app) route group' },
+    ],
+    adminGroups: [
+      { pattern: /\(admin\)/, name: 'Next.js (admin) route group' },
+    ],
+    // Detection pattern for Next.js App Router
+    routeDetection: /\/app\//,
+  },
+
+  sveltekit: {
+    protectedGroups: [
+      { pattern: /\(authenticated\)/, name: 'SvelteKit (authenticated) group' },
+      { pattern: /\(protected\)/, name: 'SvelteKit (protected) group' },
+      { pattern: /\(authed\)/, name: 'SvelteKit (authed) group' },
+    ],
+    adminGroups: [
+      { pattern: /\(admin\)/, name: 'SvelteKit (admin) group' },
+    ],
+    routeDetection: /\/routes\//,
+  },
+}
+
+/**
+ * Generic protected path patterns (framework-agnostic)
+ */
+const GENERIC_PROTECTED_PATTERNS = [
+  // Dashboard sections typically require auth
+  { pattern: /\/dashboard\//, name: 'Dashboard section' },
+  // Account/settings sections
+  { pattern: /\/account\//, name: 'Account section' },
+  { pattern: /\/settings\//, name: 'Settings section' },
+  { pattern: /\/profile\//, name: 'Profile section' },
+  // Admin sections
+  { pattern: /\/admin\//, name: 'Admin section' },
+  // User-specific routes with dynamic segments
+  { pattern: /\/users\/\[/, name: 'User-specific route' },
+  { pattern: /\/user\/\[/, name: 'User-specific route' },
+  // My-* routes (personal content)
+  { pattern: /\/my-/, name: 'Personal content route' },
+]
+
+/**
+ * Admin path patterns
+ */
+const ADMIN_PATH_PATTERNS = [
+  /\/admin\//i,
+  /\(admin\)/i,
+  /_admin\+/i,
+  /admin\+/i,
+  /\/backoffice\//i,
+  /\/management\//i,
+]
+
+/**
+ * Detect which framework this file belongs to
+ */
+function detectFramework(filePath: string): RouteProtectionContext['framework'] {
+  // Check for Remix patterns
+  if (FRAMEWORK_ROUTE_CONVENTIONS.remix.routeDetection.test(filePath)) {
+    // Remix uses routes/ directory
+    if (/_authenticated\+|_\w+\+/.test(filePath)) {
+      return 'remix'
+    }
+  }
+
+  // Check for Next.js App Router patterns
+  if (FRAMEWORK_ROUTE_CONVENTIONS.nextjs.routeDetection.test(filePath)) {
+    return 'nextjs'
+  }
+
+  // Check for SvelteKit patterns
+  if (FRAMEWORK_ROUTE_CONVENTIONS.sveltekit.routeDetection.test(filePath)) {
+    return 'sveltekit'
+  }
+
+  return 'unknown'
+}
+
+/**
+ * Get route protection context for a file path
+ *
+ * @param filePath - The full file path to analyze
+ * @returns RouteProtectionContext with protection information
+ */
+export function getRouteProtectionContext(filePath: string): RouteProtectionContext {
+  const sources: string[] = []
+  const framework = detectFramework(filePath)
+  let isAdminRoute = false
+
+  // Check Remix conventions
+  for (const layout of FRAMEWORK_ROUTE_CONVENTIONS.remix.protectedLayouts) {
+    if (layout.pattern.test(filePath)) {
+      sources.push(layout.name)
+    }
+  }
+  for (const layout of FRAMEWORK_ROUTE_CONVENTIONS.remix.adminLayouts) {
+    if (layout.pattern.test(filePath)) {
+      sources.push(layout.name)
+      isAdminRoute = true
+    }
+  }
+
+  // Check Next.js conventions
+  for (const group of FRAMEWORK_ROUTE_CONVENTIONS.nextjs.protectedGroups) {
+    if (group.pattern.test(filePath)) {
+      sources.push(group.name)
+    }
+  }
+  for (const group of FRAMEWORK_ROUTE_CONVENTIONS.nextjs.adminGroups) {
+    if (group.pattern.test(filePath)) {
+      sources.push(group.name)
+      isAdminRoute = true
+    }
+  }
+
+  // Check SvelteKit conventions
+  for (const group of FRAMEWORK_ROUTE_CONVENTIONS.sveltekit.protectedGroups) {
+    if (group.pattern.test(filePath)) {
+      sources.push(group.name)
+    }
+  }
+  for (const group of FRAMEWORK_ROUTE_CONVENTIONS.sveltekit.adminGroups) {
+    if (group.pattern.test(filePath)) {
+      sources.push(group.name)
+      isAdminRoute = true
+    }
+  }
+
+  // Check generic protected patterns
+  for (const pattern of GENERIC_PROTECTED_PATTERNS) {
+    if (pattern.pattern.test(filePath)) {
+      sources.push(pattern.name)
+    }
+  }
+
+  // Check if this is an admin route
+  if (!isAdminRoute) {
+    isAdminRoute = ADMIN_PATH_PATTERNS.some(pattern => pattern.test(filePath))
+  }
+
+  return {
+    isInProtectedHierarchy: sources.length > 0,
+    protectionSource: sources,
+    framework,
+    isAdminRoute,
+  }
+}
+
+/**
+ * Check if a file path is inside a protected route hierarchy
+ *
+ * @param filePath - The full file path
+ * @returns true if the route is protected by its hierarchy
+ */
+export function isProtectedByRouteHierarchy(filePath: string): boolean {
+  const context = getRouteProtectionContext(filePath)
+  return context.isInProtectedHierarchy
+}
+
+/**
+ * Check if a file path is inside an admin route section
+ *
+ * @param filePath - The full file path
+ * @returns true if this is an admin route
+ */
+export function isAdminRoute(filePath: string): boolean {
+  const context = getRouteProtectionContext(filePath)
+  return context.isAdminRoute
+}
+
+/**
+ * Check if a component is likely used only within authenticated routes
+ * Useful for components in /components/admin/ or similar
+ *
+ * @param filePath - The full file path
+ * @returns true if this component is likely only used in authenticated contexts
+ */
+export function isAuthenticatedOnlyComponent(filePath: string): boolean {
+  const authenticatedComponentPatterns = [
+    /\/components\/admin\//i,
+    /\/components\/dashboard\//i,
+    /\/components\/user\//i,
+    /\/components\/account\//i,
+    /\/components\/settings\//i,
+    /\/components\/protected\//i,
+    /\/components\/private\//i,
+    /\/components\/authenticated\//i,
+    // Features that are inherently authenticated
+    /\/features\/dashboard\//i,
+    /\/features\/admin\//i,
+    /\/features\/account\//i,
+  ]
+
+  return authenticatedComponentPatterns.some(pattern => pattern.test(filePath))
+}