Scanner System Overview

The VDK scanner is the core intelligence behind project analysis. It performs deep inspection of your codebase to understand architecture, patterns, technologies, and conventions, then generates intelligent rules for AI assistants.

How Scanning Works

The scanner operates in multiple phases to build a comprehensive understanding of your project:

📁 File Discovery → 🔍 Analysis → 🎯 Pattern Detection → 📝 Rule Generation

Phase 1: File Discovery

The scanner traverses your project directory structure:

File Enumeration: Lists all files and directories
Filtering: Applies ignore patterns (gitignore, node_modules, etc.)
Categorization: Groups files by type and purpose
Metadata Collection: Gathers file stats, sizes, and relationships

// Example: File discovery process
{
  totalFiles: 247,
  scannedFiles: 198,
  skippedFiles: 49,
  categories: {
    source: 156,
    config: 23,
    documentation: 12,
    assets: 7
  }
}

Phase 2: Technology Analysis

The scanner identifies your technology stack:

Language Detection

Primary and secondary languages
Version requirements
Language-specific patterns

Framework Identification

Web frameworks (React, Vue, Angular)
Backend frameworks (Express, Django, Spring)
Meta-frameworks (Next.js, Nuxt, SvelteKit)

Tool Recognition

Build tools (Vite, Webpack, Parcel)
Testing frameworks (Jest, Vitest, Cypress)
Linting and formatting tools

// Example: Technology analysis output
{
  languages: {
    primary: "TypeScript",
    secondary: ["JavaScript", "CSS"],
    versions: {
      typescript: "5.0.0",
      node: "18.0.0"
    }
  },
  frameworks: {
    frontend: "React",
    backend: "Node.js",
    metaFramework: "Next.js"
  },
  tools: {
    bundler: "Webpack",
    testing: "Jest",
    linting: "ESLint"
  }
}

Phase 3: Pattern Detection

The scanner identifies architectural and coding patterns:

Architectural Patterns

MVC (Model-View-Controller)
MVVM (Model-View-ViewModel)
Component Architecture
Microservices
Layered Architecture

Code Organization Patterns

Feature-based structure
Domain-driven design
Atomic design system
Module federation

Coding Patterns

Design patterns (Singleton, Factory, Observer)
React patterns (HOCs, Render Props, Hooks)
State management patterns
API patterns (REST, GraphQL, tRPC)

// Example: Pattern detection results
{
  architecture: {
    primary: "Component-based",
    secondary: ["Feature-based organization"]
  },
  patterns: {
    react: ["Custom Hooks", "Context API", "Compound Components"],
    state: ["Zustand", "React Query"],
    api: ["REST", "Route Handlers"]
  },
  organization: {
    structure: "Feature-based",
    componentPattern: "Atomic Design",
    testStructure: "Co-located"
  }
}

Phase 4: Dependency Analysis

Understanding your project's dependencies and their usage:

Package Analysis

Production dependencies
Development dependencies
Peer dependencies
Version constraints

Usage Patterns

How dependencies are imported
Configuration patterns
Integration approaches

Ecosystem Integration

Framework-specific packages
Plugin architectures
Extension systems

// Example: Dependency analysis
{
  dependencies: {
    production: 45,
    development: 23,
    peer: 3
  },
  usage: {
    "react": {
      importStyle: "named",
      patterns: ["hooks", "components"],
      frequency: "high"
    },
    "@tanstack/react-query": {
      importStyle: "default",
      patterns: ["data-fetching"],
      frequency: "medium"
    }
  }
}

Scanner Components

ProjectScanner

The main orchestrator that coordinates the scanning process:

import { ProjectScanner } from '@vibe-dev-kit/cli/scanner';

const scanner = new ProjectScanner({
  projectPath: './my-project',
  deepScan: true,
  ignorePatterns: ['**/node_modules/**']
});

const results = await scanner.scanProject();

Key Methods:

scanProject() - Main scanning entry point
analyze() - Deep analysis of discovered files
generateRules() - Create AI assistant rules from analysis

AdvancedPatternDetector

Specialized component for identifying complex patterns:

import { AdvancedPatternDetector } from '@vibe-dev-kit/cli/scanner/core';

const detector = new AdvancedPatternDetector({
  analysisLevel: 'comprehensive'
});

const patterns = await detector.detectPatterns(fileTree);

Pattern Types:

Architectural: MVC, MVVM, Microservices
Structural: Component organization, file naming
Behavioral: State management, data flow
Integration: API patterns, third-party usage

TechnologyAnalyzer

Identifies and analyzes technology stack:

import { TechnologyAnalyzer } from '@vibe-dev-kit/cli/scanner/core';

const analyzer = new TechnologyAnalyzer();
const techStack = await analyzer.analyzeTechnologies(projectPath);

Analysis Areas:

Package.json parsing
Configuration file analysis
Import/require pattern detection
Framework-specific file identification

DependencyAnalyzer

Analyzes project dependencies and their relationships:

import { DependencyAnalyzer } from '@vibe-dev-kit/cli/scanner/core';

const analyzer = new DependencyAnalyzer();
const dependencies = await analyzer.analyzeDependencies(projectPath);

Analysis Output:

Dependency graph
Usage patterns
Version compatibility
Security considerations

Scanning Options

Basic Options

vdk init --projectPath ./my-project

Deep Scanning

Enable comprehensive analysis:

vdk init --deep

Deep scanning includes:

AST (Abstract Syntax Tree) parsing
Cross-file relationship analysis
Complex pattern detection
Performance impact analysis

Custom Ignore Patterns

vdk init --ignorePattern "**/dist/**" "**/coverage/**" "**/*.test.js"

GitIgnore Integration

vdk init --use-gitignore

Automatically respects your .gitignore patterns.

Scanner Output

Project Context

{
  projectName: "my-nextjs-app",
  projectType: "web-application",
  language: "typescript",
  framework: "nextjs",
  version: "14.0.0"
}

Technology Stack

{
  frontend: {
    framework: "React",
    metaFramework: "Next.js",
    styling: "Tailwind CSS",
    stateManagement: "Zustand"
  },
  backend: {
    runtime: "Node.js",
    database: "PostgreSQL",
    orm: "Prisma"
  },
  tools: {
    bundler: "Webpack",
    testing: "Jest",
    linting: "ESLint + Prettier"
  }
}

Architectural Insights

{
  patterns: {
    architecture: "App Router",
    components: "Server Components + Client Components",
    dataFlow: "Server Actions + React Query",
    organization: "Feature-based"
  },
  conventions: {
    naming: "camelCase",
    fileStructure: "kebab-case",
    imports: "absolute paths",
    styling: "utility-first"
  }
}

Configuration

Scanner Configuration File

Create vdk.config.json for custom scanner settings:

{
  "scanner": {
    "deepScan": true,
    "analysisLevel": "comprehensive",
    "ignorePatterns": [
      "**/node_modules/**",
      "**/dist/**",
      "**/*.test.ts"
    ],
    "includePatterns": [
      "src/**/*.{ts,tsx,js,jsx}",
      "app/**/*.{ts,tsx}",
      "components/**/*.{ts,tsx}"
    ],
    "languageAnalysis": {
      "typescript": {
        "parseDecorators": true,
        "strictMode": true
      },
      "javascript": {
        "esVersion": "ES2022"
      }
    },
    "patternDetection": {
      "architectural": true,
      "design": true,
      "organizational": true
    }
  }
}

Environment Variables

# Enable debug output
export VDK_DEBUG=true

# Increase scan timeout
export VDK_SCAN_TIMEOUT=300000

# Custom templates directory
export VDK_TEMPLATES_DIR=/path/to/templates

# Disable certain analyzers
export VDK_DISABLE_ANALYZERS=java,swift

Performance Considerations

Scan Time Optimization

File Count Impact:

Small projects (< 100 files): ~2-5 seconds
Medium projects (100-1000 files): ~5-15 seconds
Large projects (> 1000 files): ~15-60 seconds

Optimization Strategies:

Use appropriate ignore patterns
Disable deep scan for quick iterations
Focus scan on specific directories
Use incremental scanning for large codebases

Memory Usage

Typical Memory Usage:

Small projects: ~50-100 MB
Medium projects: ~100-300 MB
Large projects: ~300-800 MB

Memory Optimization:

# Limit memory usage
export NODE_OPTIONS="--max-old-space-size=4096"

# Stream processing for large projects
vdk init --stream-processing

Error Handling

Common Scan Errors

Permission Errors:

Error: EACCES: permission denied, scandir '/protected-directory'

Solution: Adjust file permissions or add to ignore patterns

Memory Errors:

Error: JavaScript heap out of memory

Solution: Increase Node.js memory limit or use streaming mode

Timeout Errors:

Error: Scan timeout after 120000ms

Solution: Increase timeout or reduce scan scope

Debugging Scanner Issues

# Enable verbose debugging
VDK_DEBUG=true vdk init --verbose

# Analyze specific directory only
vdk init --projectPath ./src

# Skip problematic analyzers
VDK_DISABLE_ANALYZERS=typescript vdk init

Next Steps

Pattern Detection - Deep dive into pattern recognition
Technology Analysis - Understanding technology detection
Configuration Guide - Advanced scanner configuration
Custom Analyzers - Creating custom analysis components

Scanner

On this page