@oculum/scanner 1.0.14 → 1.0.15

package/src/parse/call-graph.ts

@@ -0,0 +1,419 @@
+/**
+ * Intra-file Call Graph Builder
+ *
+ * Builds a bidirectional call graph from a parsed AST, tracking which functions
+ * call which other functions within the same file. Used for taint analysis
+ * and understanding code flow in security-relevant contexts.
+ */
+
+import type Parser from 'tree-sitter'
+import { walkAST, findEnclosingFunction, type ParsedAST } from './ast'
+import { resolveCallTarget } from '../detect/ast-rules/helpers/call-analysis'
+import { collectVariableAliases } from '../detect/ast-rules/helpers/scope-analysis'
+import { resolvePythonCallTarget } from '../detect/ast-rules/helpers/python-helpers'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CallGraph {
+  functions: Map<string, FunctionNode>
+  calls: Map<string, Set<string>>
+  calledBy: Map<string, Set<string>>
+}
+
+export interface FunctionNode {
+  name: string
+  node: Parser.SyntaxNode
+  params: string[]
+  isAsync: boolean
+  isExported: boolean
+}
+
+// ============================================================================
+// Graph Building
+// ============================================================================
+
+const MODULE_SCOPE = '<module>'
+
+/**
+ * Build a call graph from a parsed AST.
+ * Tracks all function declarations and intra-file call relationships.
+ */
+export function buildCallGraph(ast: ParsedAST): CallGraph {
+  const root = ast.tree.rootNode
+  const functions = new Map<string, FunctionNode>()
+  const calls = new Map<string, Set<string>>()
+  const calledBy = new Map<string, Set<string>>()
+
+  // Step 1: Collect all function declarations
+  collectFunctions(root, functions)
+
+  // Step 2: Collect aliases for resolving indirect calls
+  const aliases = collectVariableAliases(root)
+
+  // Detect language from root node type
+  const isPython = root.type === 'module'
+
+  // Step 3: Walk all call expressions, resolve targets, build edges
+  walkAST(root, (node) => {
+    if (isPython) {
+      if (node.type !== 'call') return false
+    } else {
+      if (node.type !== 'call_expression' && node.type !== 'new_expression') return false
+    }
+
+    // Resolve the call target (JS or Python)
+    let resolved: { type: string; name: string; object?: string } | null = null
+    if (isPython) {
+      resolved = resolvePythonCallTarget(node)
+    } else {
+      resolved = resolveCallTarget(node, aliases)
+    }
+    if (!resolved) return false
+
+    // Determine the callee name — for member calls like this.bar() or self.bar()
+    let calleeName = resolved.name
+
+    // Only track calls to functions defined in this file
+    if (!functions.has(calleeName)) {
+      // For this.method() / self.method() calls, try ClassName.method
+      if (resolved.type === 'member' && (resolved.object === 'this' || resolved.object === 'self')) {
+        const className = getEnclosingClassName(node)
+        if (className) {
+          const qualified = `${className}.${resolved.name}`
+          if (functions.has(qualified)) {
+            calleeName = qualified
+          } else {
+            return false
+          }
+        } else {
+          return false
+        }
+      } else {
+        return false
+      }
+    }
+
+    // Determine the caller
+    const enclosing = findEnclosingFunction(node)
+    const callerName = enclosing ? getFunctionName(enclosing, root) : MODULE_SCOPE
+
+    if (!callerName) return false
+
+    // Add edge: caller → callee
+    if (!calls.has(callerName)) calls.set(callerName, new Set())
+    calls.get(callerName)!.add(calleeName)
+
+    if (!calledBy.has(calleeName)) calledBy.set(calleeName, new Set())
+    calledBy.get(calleeName)!.add(callerName)
+
+    return false
+  })
+
+  return { functions, calls, calledBy }
+}
+
+// ============================================================================
+// Function Collection
+// ============================================================================
+
+export function collectFunctions(root: Parser.SyntaxNode, functions: Map<string, FunctionNode>): void {
+  walkAST(root, (node) => {
+    let fnNode: FunctionNode | null = null
+
+    switch (node.type) {
+      case 'function_declaration':
+      case 'generator_function_declaration':
+        fnNode = parseFunctionDeclaration(node, root)
+        break
+
+      case 'variable_declarator':
+        fnNode = parseVariableFunction(node, root)
+        break
+
+      case 'method_definition':
+        fnNode = parseMethodDefinition(node, root)
+        break
+
+      case 'function_definition':
+        fnNode = parsePythonFunctionDefinition(node, root)
+        break
+
+      case 'decorated_definition': {
+        const inner = node.namedChildren.find(c => c.type === 'function_definition')
+        if (inner) fnNode = parsePythonFunctionDefinition(inner, root)
+        break
+      }
+    }
+
+    if (fnNode) {
+      functions.set(fnNode.name, fnNode)
+    }
+
+    return false
+  })
+}
+
+function parseFunctionDeclaration(node: Parser.SyntaxNode, root: Parser.SyntaxNode): FunctionNode | null {
+  const nameNode = node.childForFieldName('name')
+  if (!nameNode) return null
+
+  return {
+    name: nameNode.text,
+    node,
+    params: extractParams(node),
+    isAsync: hasAsyncKeyword(node),
+    isExported: isNodeExported(node, root),
+  }
+}
+
+function parseVariableFunction(node: Parser.SyntaxNode, root: Parser.SyntaxNode): FunctionNode | null {
+  const nameNode = node.childForFieldName('name')
+  const valueNode = node.childForFieldName('value')
+  if (!nameNode || !valueNode) return null
+  if (nameNode.type !== 'identifier') return null
+
+  if (
+    valueNode.type !== 'arrow_function' &&
+    valueNode.type !== 'function_expression' &&
+    valueNode.type !== 'function'
+  ) {
+    return null
+  }
+
+  return {
+    name: nameNode.text,
+    node: valueNode,
+    params: extractParams(valueNode),
+    isAsync: hasAsyncKeyword(valueNode),
+    isExported: isNodeExported(node, root),
+  }
+}
+
+function parseMethodDefinition(node: Parser.SyntaxNode, root: Parser.SyntaxNode): FunctionNode | null {
+  const nameNode = node.childForFieldName('name')
+  if (!nameNode) return null
+
+  // Check if inside a class
+  const className = getEnclosingClassName(node)
+  const methodName = nameNode.text
+
+  return {
+    name: className ? `${className}.${methodName}` : methodName,
+    node,
+    params: extractParams(node),
+    isAsync: hasAsyncKeyword(node),
+    isExported: isNodeExported(node, root),
+  }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function parsePythonFunctionDefinition(node: Parser.SyntaxNode, root: Parser.SyntaxNode): FunctionNode | null {
+  const nameNode = node.childForFieldName('name')
+  if (!nameNode) return null
+  const className = getEnclosingClassName(node)
+  return {
+    name: className ? `${className}.${nameNode.text}` : nameNode.text,
+    node,
+    params: extractPythonParams(node, !!className),
+    isAsync: node.children[0]?.text === 'async',
+    isExported: isPythonTopLevel(node, root),
+  }
+}
+
+function extractPythonParams(node: Parser.SyntaxNode, isMethod: boolean): string[] {
+  const params = node.childForFieldName('parameters')
+  if (!params) return []
+  const names: string[] = []
+  let isFirst = true
+  for (const child of params.namedChildren) {
+    let name: string | null = null
+    if (child.type === 'identifier') {
+      name = child.text
+    } else if (child.type === 'typed_parameter' || child.type === 'default_parameter' || child.type === 'typed_default_parameter') {
+      name = child.namedChildren.find(c => c.type === 'identifier')?.text ?? null
+    } else if (child.type === 'list_splat_pattern' || child.type === 'dictionary_splat_pattern') {
+      name = child.namedChildren.find(c => c.type === 'identifier')?.text ?? null
+    }
+    if (name) {
+      if (isMethod && isFirst && (name === 'self' || name === 'cls')) {
+        isFirst = false
+        continue
+      }
+      isFirst = false
+      names.push(name)
+    }
+  }
+  return names
+}
+
+function isPythonTopLevel(node: Parser.SyntaxNode, root: Parser.SyntaxNode): boolean {
+  if (root.type !== 'module') return false
+  let current = node.parent
+  while (current) {
+    if (current.type === 'module') return true
+    if (current.type === 'decorated_definition') { current = current.parent; continue }
+    if (current.type === 'function_definition' || current.type === 'class_definition') return false
+    current = current.parent
+  }
+  return false
+}
+
+function extractParams(node: Parser.SyntaxNode): string[] {
+  const params = node.childForFieldName('parameters')
+  if (!params) return []
+
+  const names: string[] = []
+  for (const child of params.namedChildren) {
+    if (child.type === 'identifier') {
+      names.push(child.text)
+    } else if (child.type === 'required_parameter' || child.type === 'optional_parameter') {
+      const pattern = child.childForFieldName('pattern')
+      if (pattern?.type === 'identifier') {
+        names.push(pattern.text)
+      }
+    } else if (child.type === 'assignment_pattern') {
+      const left = child.childForFieldName('left')
+      if (left?.type === 'identifier') {
+        names.push(left.text)
+      }
+    }
+  }
+  return names
+}
+
+function hasAsyncKeyword(node: Parser.SyntaxNode): boolean {
+  // Check for 'async' token in the node's children
+  for (const child of node.children) {
+    if (child.type === 'async') return true
+    // For arrow functions, async appears before parameters
+    if (child.text === 'async' && child.type !== 'identifier') return true
+  }
+  return false
+}
+
+function isNodeExported(node: Parser.SyntaxNode, _root: Parser.SyntaxNode): boolean {
+  // Check if parent is export_statement
+  let current: Parser.SyntaxNode | null = node.parent
+  while (current) {
+    if (current.type === 'export_statement') return true
+    // Stop climbing at statement boundaries
+    if (
+      current.type === 'program' ||
+      current.type === 'statement_block'
+    ) {
+      break
+    }
+    current = current.parent
+  }
+  return false
+}
+
+function getEnclosingClassName(node: Parser.SyntaxNode): string | null {
+  let current = node.parent
+  while (current) {
+    if (current.type === 'class_declaration' || current.type === 'class' || current.type === 'class_definition') {
+      const nameNode = current.childForFieldName('name')
+      return nameNode?.text ?? null
+    }
+    current = current.parent
+  }
+  return null
+}
+
+/**
+ * Get the name of a function node. Used to identify the caller
+ * when we find a call expression inside a function body.
+ */
+function getFunctionName(fnNode: Parser.SyntaxNode, root: Parser.SyntaxNode): string | null {
+  // function_declaration / generator_function_declaration → name field
+  if (fnNode.type === 'function_declaration' || fnNode.type === 'generator_function_declaration') {
+    return fnNode.childForFieldName('name')?.text ?? null
+  }
+
+  // method_definition → possibly prefixed with class name
+  if (fnNode.type === 'method_definition') {
+    const methodName = fnNode.childForFieldName('name')?.text
+    if (!methodName) return null
+    const className = getEnclosingClassName(fnNode)
+    return className ? `${className}.${methodName}` : methodName
+  }
+
+  // Python function_definition
+  if (fnNode.type === 'function_definition') {
+    const name = fnNode.childForFieldName('name')?.text
+    if (!name) return null
+    const className = getEnclosingClassName(fnNode)
+    return className ? `${className}.${name}` : name
+  }
+
+  // arrow_function / function_expression → look at parent variable_declarator
+  if (fnNode.type === 'arrow_function' || fnNode.type === 'function_expression' || fnNode.type === 'function') {
+    const parent = fnNode.parent
+    if (parent?.type === 'variable_declarator') {
+      const nameNode = parent.childForFieldName('name')
+      if (nameNode?.type === 'identifier') return nameNode.text
+    }
+    // Could be assigned in an assignment_expression
+    if (parent?.type === 'assignment_expression') {
+      const left = parent.childForFieldName('left')
+      if (left?.type === 'identifier') return left.text
+    }
+  }
+
+  return null
+}
+
+// ============================================================================
+// Query Functions
+// ============================================================================
+
+/**
+ * Get all functions that call the given function.
+ */
+export function getCallersOf(graph: CallGraph, functionName: string): string[] {
+  const callers = graph.calledBy.get(functionName)
+  return callers ? [...callers] : []
+}
+
+/**
+ * Get all functions called by the given function.
+ */
+export function getCalleesOf(graph: CallGraph, functionName: string): string[] {
+  const callees = graph.calls.get(functionName)
+  return callees ? [...callees] : []
+}
+
+/**
+ * Find a call path from one function to another using BFS.
+ * Returns the chain as an array including both endpoints, or null if no path exists.
+ */
+export function getCallChain(graph: CallGraph, from: string, to: string): string[] | null {
+  if (from === to) return [from]
+
+  const visited = new Set<string>()
+  const queue: Array<{ node: string; path: string[] }> = [{ node: from, path: [from] }]
+  visited.add(from)
+
+  while (queue.length > 0) {
+    const { node, path } = queue.shift()!
+    const callees = graph.calls.get(node)
+    if (!callees) continue
+
+    for (const callee of callees) {
+      if (callee === to) {
+        return [...path, callee]
+      }
+      if (!visited.has(callee)) {
+        visited.add(callee)
+        queue.push({ node: callee, path: [...path, callee] })
+      }
+    }
+  }
+
+  return null
+}

package/src/parse/file-classifier.ts

@@ -51,9 +51,9 @@ export function isTestOrMockFile(filePath: string): boolean {
   const testPatterns = [
     /\.(test|spec)\.(ts|tsx|js|jsx)$/i,
     /\/__tests__\//i,
-    /\/test\//i,
-    /\/tests\//i,
-    /\/testing\//i,                           // testing directories (e.g., docker/testing/)
+    /(^|\/)test\//i,
+    /(^|\/)tests\//i,
+    /(^|\/)testing\//i,                       // testing directories (e.g., docker/testing/)
     /\/mock/i,
     /\/mocks\//i,
     /\/fixtures?\//i,
@@ -65,6 +65,12 @@ export function isTestOrMockFile(filePath: string): boolean {
     /\/playwright\//i,                        // Playwright tests
     /\/vitest\//i,                            // Vitest
     /\/jest\//i,                              // Jest
+    /\.Tests\./i,                             // C# test project namespace (e.g., StockCraft.Infrastructure.Tests)
+    /\.Test\./i,                              // C# test project namespace singular
+    /\.test\.cs$/i,                           // C# test file suffix
+    /\.spec\.cs$/i,                           // C# spec file suffix
+    /Test\.cs$/i,                             // Files ending in Test.cs
+    /Tests\.cs$/i,                            // Files ending in Tests.cs
   ]
   return testPatterns.some(pattern => pattern.test(filePath))
 }
@@ -79,10 +85,12 @@ export function isExampleFile(filePath: string): boolean {
     filePath.includes('.sample') ||
     filePath.includes('.template') ||
     filePath.includes('README') ||
-    filePath.includes('/examples/') ||
-    filePath.includes('/example/') ||
-    filePath.includes('/demo/') ||
-    filePath.includes('/demos/')
+    filePath.includes('/examples/') || filePath.startsWith('examples/') ||
+    filePath.includes('/example/')  || filePath.startsWith('example/') ||
+    filePath.includes('/demo/')     || filePath.startsWith('demo/') ||
+    filePath.includes('/demos/')    || filePath.startsWith('demos/') ||
+    filePath.includes('.Development.') ||
+    filePath.toLowerCase().includes('launchsettings')
   )
 }
 
@@ -93,14 +101,14 @@ export function isExampleFile(filePath: string): boolean {
  */
 export function isExampleDirectory(filePath: string): boolean {
   const examplePatterns = [
-    /\/examples?\//i,
-    /\/demos?\//i,
-    /\/templates?\//i,
-    /\/samples?\//i,
-    /\/tutorials?\//i,
-    /\/cookbook\//i,
-    /\/quickstart\//i,
-    /\/getting-started\//i,
+    /(^|\/)examples?\//i,
+    /(^|\/)demos?\//i,
+    /(^|\/)templates?\//i,
+    /(^|\/)samples?\//i,
+    /(^|\/)tutorials?\//i,
+    /(^|\/)cookbook\//i,
+    /(^|\/)quickstart\//i,
+    /(^|\/)getting-started\//i,
   ]
   return examplePatterns.some(pattern => pattern.test(filePath))
 }
@@ -137,6 +145,7 @@ export function isLibraryCode(filePath: string): boolean {
 export function isFixtureFile(filePath: string): boolean {
   const fixturePatterns = [
     /__fixtures__\//i,
+    /__testfixtures__\//i,
     /\.fixture\./i,
     /fixtures?\//i,
     /testdata\//i,
@@ -291,6 +300,7 @@ export function isEducationalVulnerabilityFile(filePath: string): boolean {
     /\/vuln-examples?\//i,
     /\/challenge-\d+/i,  // OWASP Juice Shop challenges
     /\/exploit-examples?\//i,
+    /\/codefixes?\//i,   // OWASP Juice Shop code fix exercises
   ]
   return patterns.some(p => p.test(filePath))
 }
@@ -502,6 +512,50 @@ export function isAgentSkillFile(filePath: string): boolean {
   return skillPatterns.some(p => p.test(filePath))
 }
 
+/**
+ * Check if file is an AI rules/configuration file (superset of isAgentSkillFile)
+ * Includes all agent skill paths PLUS broader AI tool config files that are
+ * targets for the "Rules File Backdoor" attack (invisible Unicode payloads,
+ * stealth instructions).
+ *
+ * Covers: .cursorrules, .windsurfrules, CLAUDE.md (root), .cursor/*, .claude/*,
+ * .gemini/*, .github/copilot-instructions.md, .github/agents/*, Windsurf
+ * global_rules.md, .mdc files in AI directories, etc.
+ */
+export function isAIRulesFile(filePath: string): boolean {
+  // First check: all agent skill files are also AI rules files
+  if (isAgentSkillFile(filePath)) return true
+
+  const rulesPatterns = [
+    // Root CLAUDE.md (not matched by isAgentSkillFile)
+    /\/CLAUDE\.md$/i,
+    /^CLAUDE\.md$/i,
+
+    // .cursorrules / .windsurfrules at root (bare paths without directory prefix)
+    /^\.cursorrules$/i,
+    /^\.windsurfrules$/i,
+
+    // Windsurf
+    /\/\.windsurfrules$/i,
+    /\/global_rules\.md$/i,
+
+    // Gemini
+    /\/\.gemini\//i,
+
+    // Cursor extended paths
+    /\/\.cursor\/commands\//i,
+    /\/\.cursor\/tools\//i,
+
+    // Claude extended paths
+    /\/\.claude\/settings\.json$/i,
+    /\/\.claude\/instructions\.md$/i,
+
+    // .mdc files (Cursor rules format)
+    /\.mdc$/i,
+  ]
+  return rulesPatterns.some(p => p.test(filePath))
+}
+
 // ============================================================================
 // Code Line Context Detection
 // ============================================================================

package/src/parse/node-index.ts

@@ -0,0 +1,118 @@
+/**
+ * Node Index — Single-Pass AST Index
+ *
+ * Walks a tree-sitter AST once and builds a Map<string, SyntaxNode[]>
+ * index grouping every node by its type. Rules then iterate their
+ * specific node types from the map instead of walking the entire tree.
+ *
+ * This eliminates ~24 redundant full tree walks per file (one per rule).
+ */
+
+import type Parser from 'tree-sitter'
+
+export type NodeIndex = Map<string, Parser.SyntaxNode[]>
+
+/**
+ * Build a node index from a tree-sitter root node.
+ * Single DFS walk using a cursor for efficiency.
+ */
+export function buildNodeIndex(root: Parser.SyntaxNode): NodeIndex {
+  const index: NodeIndex = new Map()
+  const cursor = root.walk()
+  let reachedRoot = false
+
+  while (!reachedRoot) {
+    const node = cursor.currentNode
+
+    if (node.isNamed) {
+      const type = node.type
+      let arr = index.get(type)
+      if (!arr) {
+        arr = []
+        index.set(type, arr)
+      }
+      arr.push(node)
+    }
+
+    if (cursor.gotoFirstChild()) {
+      continue
+    }
+
+    if (cursor.gotoNextSibling()) {
+      continue
+    }
+
+    while (true) {
+      if (!cursor.gotoParent()) {
+        reachedRoot = true
+        break
+      }
+      if (cursor.gotoNextSibling()) {
+        break
+      }
+    }
+  }
+
+  return index
+}
+
+// ============================================================================
+// LRU Cache
+// ============================================================================
+
+const NODE_INDEX_CACHE_MAX = 500
+const nodeIndexCache = new Map<string, NodeIndex>()
+
+/**
+ * Build a node index with LRU caching by language + content hash.
+ * Same pattern as AST cache and type-extractor cache.
+ */
+export function buildNodeIndexCached(
+  root: Parser.SyntaxNode,
+  language: string,
+  hash: string,
+): NodeIndex {
+  const key = `${language}:${hash}`
+  const cached = nodeIndexCache.get(key)
+  if (cached) return cached
+
+  const index = buildNodeIndex(root)
+
+  // LRU eviction
+  if (nodeIndexCache.size >= NODE_INDEX_CACHE_MAX) {
+    const firstKey = nodeIndexCache.keys().next().value
+    if (firstKey) nodeIndexCache.delete(firstKey)
+  }
+
+  nodeIndexCache.set(key, index)
+  return index
+}
+
+/**
+ * Clear the node index cache. Used in tests.
+ */
+export function clearNodeIndexCache(): void {
+  nodeIndexCache.clear()
+}
+
+/**
+ * Get nodes of one or more types from the index.
+ * Single type: returns the array directly (no copy).
+ * Multiple types: concatenates arrays.
+ */
+export function getNodes(index: NodeIndex, ...types: string[]): Parser.SyntaxNode[] {
+  if (types.length === 1) {
+    return index.get(types[0]) ?? []
+  }
+
+  const result: Parser.SyntaxNode[] = []
+  for (const type of types) {
+    const arr = index.get(type)
+    if (arr) {
+      for (const node of arr) {
+        result.push(node)
+      }
+    }
+  }
+  return result
+}