@aria_asi/cli 0.2.0

package/dist/aria-web/src/lib/codebase-scanner.js

@@ -0,0 +1,1730 @@
+/**
+ * Auto codebase discovery scanner — produces a compressed "schema image"
+ * that eliminates cold starts for any LLM.
+ *
+ * Scans a directory and detects language, framework, package manager, database,
+ * ORM, test framework, entry points, project structure, dependencies, and
+ * architecture patterns. Outputs a SchemaImage object and a human-readable
+ * compressed text block.
+ *
+ * Zero external dependencies — uses only Node.js built-ins (fs, path, crypto,
+ * child_process, events). Optional chokidar support for file watching.
+ *
+ * @module codebase-scanner
+ */
+import { createHash } from 'crypto';
+import { execSync } from 'child_process';
+import { promises as fsp, watch as fsWatch } from 'fs';
+import * as path from 'path';
+// ---------------------------------------------------------------------------
+// Constants — detection maps
+// ---------------------------------------------------------------------------
+const IGNORE_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.svn',
+    '.hg',
+    '.next',
+    '.nuxt',
+    'dist',
+    'build',
+    'out',
+    'target',
+    '__pycache__',
+    '.tox',
+    '.venv',
+    'venv',
+    '.env',
+    'vendor',
+    '.turbo',
+    '.cache',
+    'coverage',
+    '.nyc_output',
+    '.sass-cache',
+    'tmp',
+    'temp',
+    '.idea',
+    '.vscode',
+    '.DS_Store',
+]);
+const MAX_FILE_SIZE = 1_048_576; // 1 MB
+const MAX_SCAN_DEPTH = 4;
+const CACHE_TTL_MS = 30_000;
+const LANG_MAP = {
+    typescript: {
+        configFile: 'tsconfig.json',
+        extPriority: 'ts,tsx',
+        // version read from package.json devDependencies in detectLanguageAndPackageManager
+    },
+    javascript: {
+        configFile: 'package.json',
+        extPriority: 'js,jsx,mjs,cjs',
+    },
+    python: {
+        configFile: 'pyproject.toml',
+        extPriority: 'py',
+        versionFile: '.python-version',
+        versionFromConfig: () => '',
+    },
+    rust: {
+        configFile: 'Cargo.toml',
+        extPriority: 'rs',
+        versionFromConfig: (raw) => {
+            const m = raw.match(/edition\s*=\s*"(\d+)"/);
+            return m ? `edition ${m[1]}` : '';
+        },
+    },
+    go: {
+        configFile: 'go.mod',
+        extPriority: 'go',
+        versionFromConfig: (raw) => {
+            const m = raw.match(/^go\s+(\S+)/m);
+            return m ? `Go ${m[1]}` : '';
+        },
+    },
+    ruby: {
+        configFile: 'Gemfile',
+        extPriority: 'rb',
+        versionFile: '.ruby-version',
+        versionFromConfig: () => '',
+    },
+    java: {
+        configFile: 'pom.xml',
+        extPriority: 'java,kt',
+        versionFromConfig: () => '',
+    },
+    kotlin: {
+        configFile: 'build.gradle.kts',
+        extPriority: 'kt,kts',
+    },
+    cpp: {
+        configFile: 'CMakeLists.txt',
+        extPriority: 'cpp,cxx,h,hpp,cc',
+    },
+    csharp: {
+        configFile: '*.csproj',
+        extPriority: 'cs',
+    },
+    swift: {
+        configFile: 'Package.swift',
+        extPriority: 'swift',
+    },
+    php: {
+        configFile: 'composer.json',
+        extPriority: 'php',
+    },
+};
+// framework detection: dependency name in package.json → framework label
+const JS_FRAMEWORK_MAP = {
+    next: 'Next.js',
+    nuxt: 'Nuxt',
+    'react-scripts': 'Create React App',
+    gatsby: 'Gatsby',
+    svelte: 'SvelteKit',
+    '@sveltejs/kit': 'SvelteKit',
+    '@remix-run/react': 'Remix',
+    '@remix-run/serve': 'Remix',
+    '@angular/core': 'Angular',
+    astro: 'Astro',
+    express: 'Express',
+    fastify: 'Fastify',
+    koa: 'Koa',
+    '@hapi/hapi': 'Hapi',
+    '@nestjs/core': 'NestJS',
+    'strapi-admin': 'Strapi',
+    egg: 'Egg.js',
+    'adonisjs/core': 'AdonisJS',
+};
+const PY_FRAMEWORK_MAP = {
+    fastapi: 'FastAPI',
+    django: 'Django',
+    flask: 'Flask',
+    'aiohttp.web': 'aiohttp',
+    starlette: 'Starlette',
+    litestar: 'Litestar',
+    pyramid: 'Pyramid',
+    falcon: 'Falcon',
+    sanic: 'Sanic',
+    bottle: 'Bottle',
+};
+const RS_FRAMEWORK_MAP = {
+    axum: 'Axum',
+    actix: 'Actix Web',
+    rocket: 'Rocket',
+    warp: 'Warp',
+    tide: 'Tide',
+    poem: 'Poem',
+    salvo: 'Salvo',
+};
+const RB_FRAMEWORK_MAP = {
+    rails: 'Rails',
+    sinatra: 'Sinatra',
+    grape: 'Grape',
+    hanami: 'Hanami',
+};
+const GO_FRAMEWORK_MAP = {
+    gin: 'Gin',
+    echo: 'Echo',
+    fiber: 'Fiber',
+    chi: 'Chi',
+    gorilla: 'Gorilla Mux',
+    iris: 'Iris',
+    beego: 'Beego',
+};
+// Package manager lock files
+const PKG_MANAGER_MAP = {
+    'pnpm-lock.yaml': 'pnpm',
+    'yarn.lock': 'yarn',
+    'package-lock.json': 'npm',
+    'bun.lockb': 'bun',
+    'bun.lock': 'bun',
+    'Cargo.lock': 'cargo',
+    'go.sum': 'go mod',
+    'Gemfile.lock': 'bundler',
+    'poetry.lock': 'poetry',
+    'Pipfile.lock': 'pipenv',
+    'composer.lock': 'composer',
+};
+// Database provider indicators (from env / Prisma / connection strings)
+const DB_INDICATORS = [
+    { pattern: /postgres(?:ql)?:\/\//i, label: 'Postgres' },
+    { pattern: /mysql:\/\//i, label: 'MySQL' },
+    { pattern: /mongodb(?:\+srv)?:\/\//i, label: 'MongoDB' },
+    { pattern: /sqlite:/i, label: 'SQLite' },
+    { pattern: /redis:\/\//i, label: 'Redis' },
+    { pattern: /DATABASE_URL\s*=\s*postgres/i, label: 'Postgres' },
+    { pattern: /DATABASE_URL\s*=\s*mysql/i, label: 'MySQL' },
+    { pattern: /REDIS_URL/i, label: 'Redis' },
+    { pattern: /MONGODB_URI/i, label: 'MongoDB' },
+];
+const ORM_MAP = {
+    prisma: 'Prisma',
+    '@prisma/client': 'Prisma',
+    typeorm: 'TypeORM',
+    mikro: 'MikroORM',
+    '@mikro-orm/core': 'MikroORM',
+    sequelize: 'Sequelize',
+    knex: 'Knex',
+    objection: 'Objection',
+    bookshelf: 'Bookshelf',
+    mongoose: 'Mongoose',
+    drizzle: 'Drizzle ORM',
+    'drizzle-orm': 'Drizzle ORM',
+    sqlalchemy: 'SQLAlchemy',
+    diesel: 'Diesel',
+    'sqlx-core': 'SQLx',
+    gorm: 'GORM',
+    activerecord: 'ActiveRecord',
+};
+const TEST_FRAMEWORK_MAP = {
+    jest: 'Jest',
+    vitest: 'Vitest',
+    '@playwright/test': 'Playwright',
+    mocha: 'Mocha',
+    jasmine: 'Jasmine',
+    ava: 'Ava',
+    tap: 'Tap',
+    cypress: 'Cypress',
+};
+const TEST_FILE_PATTERNS = [
+    /\.test\./,
+    /\.spec\./,
+    /_test\./,
+    /test_/,
+    /\.test\.tsx?$/,
+    /\.spec\.tsx?$/,
+    /\.test\.jsx?$/,
+    /\.spec\.jsx?$/,
+    /_test\.py$/,
+    /test_.*\.py$/,
+    /_test\.go$/,
+    /_spec\.rb$/,
+];
+// ---------------------------------------------------------------------------
+// Directory-purpose inference
+// ---------------------------------------------------------------------------
+const DIR_PURPOSE_MAP = [
+    { names: ['pages', 'routes', 'app'], purpose: 'routes' },
+    { names: ['components', 'component', 'ui'], purpose: 'components' },
+    { names: ['lib', 'utils', 'utility', 'util', 'helpers', 'helper', 'shared'], purpose: 'utilities' },
+    { names: ['services', 'service'], purpose: 'services' },
+    { names: ['hooks', 'hook'], purpose: 'hooks' },
+    { names: ['models', 'model', 'entities', 'entity'], purpose: 'models' },
+    { names: ['controllers', 'controller'], purpose: 'controllers' },
+    { names: ['middleware', 'middlewares'], purpose: 'middleware' },
+    { names: ['store', 'stores', 'state'], purpose: 'store' },
+    { names: ['types', 'type', 'interfaces', '@types', 'typedefs'], purpose: 'types' },
+    { names: ['config', 'configs', 'configuration', 'settings'], purpose: 'config' },
+    { names: ['styles', 'style', 'css', 'scss', 'less'], purpose: 'styles' },
+    { names: ['public', 'static', 'assets', 'images', 'img'], purpose: 'assets' },
+    { names: ['tests', 'test', '__tests__', 'spec', 'e2e', 'integration', 'cypress'], purpose: 'tests' },
+    { names: ['e2e', 'cypress', 'playwright'], purpose: 'e2e-tests' },
+    { names: ['docs', 'doc', 'documentation'], purpose: 'docs' },
+    { names: ['scripts', 'script', 'bin', 'tools'], purpose: 'scripts' },
+    { names: ['migrations', 'migration', 'migrate', 'seed', 'seeds'], purpose: 'migrations' },
+    { names: ['infra', 'infrastructure', 'k8s', 'kubernetes', 'terraform', 'helm', 'docker'], purpose: 'infrastructure' },
+    { names: ['prisma'], purpose: 'prisma' },
+    { names: ['api'], purpose: 'api' },
+    { names: ['db', 'database', 'databases', 'sql'], purpose: 'db' },
+];
+const KEY_PATTERN_RULES = [
+    {
+        label: 'JWT authentication',
+        files: ['auth.ts', 'auth.js', 'auth.py', 'authorization.ts', 'jwt.ts'],
+        deps: ['jsonwebtoken', 'jose', 'pyjwt', 'jwt'],
+        contentRegex: /\b(jwt|jsonwebtoken|jose)\b/i,
+    },
+    {
+        label: 'OAuth / social login',
+        deps: ['next-auth', '@auth/core', 'oauthlib', 'omniauth'],
+        contentRegex: /\b(oauth|openid\s*connect)\b/i,
+    },
+    {
+        label: 'Role-based access control (RBAC)',
+        files: ['roles.ts', 'permissions.ts', 'rbac.ts', 'authorization.ts', 'guards.ts'],
+        contentRegex: /\b(role|permission|rbac|hasRole|checkPermission|Ability)\b/i,
+    },
+    {
+        label: 'Input validation with schema library',
+        deps: ['zod', 'yup', 'joi', 'pydantic', 'marshmallow', 'class-validator'],
+        contentRegex: /\b(z\.|yup\.|joi\.|BaseModel|@IsString|@IsInt)\b/i,
+    },
+    {
+        label: 'Server actions for mutations',
+        files: ['actions.ts', 'actions.tsx'],
+        contentRegex: /['"]use server['"]/,
+    },
+    {
+        label: 'API route handlers',
+        files: ['route.ts', 'route.tsx', 'api.ts', 'handler.ts'],
+    },
+    {
+        label: 'Middleware chain',
+        files: ['middleware.ts', 'middleware.js', 'middlewares.ts'],
+        contentRegex: /\b(app\.use|router\.use|@Middleware|middleware)\b/i,
+    },
+    {
+        label: 'Webhook handling',
+        files: ['webhook.ts', 'webhooks.ts', 'webhook.py'],
+        deps: ['stripe', 'github-webhook-handler'],
+        contentRegex: /\b(webhook|stripe\.webhooks)\b/i,
+    },
+    {
+        label: 'Payment processing',
+        deps: ['stripe', 'paypal', '@stripe/stripe-js', 'braintree', 'square'],
+        contentRegex: /\b(stripe|payment|checkout|invoice)\b/i,
+    },
+    {
+        label: 'Email sending',
+        deps: ['nodemailer', 'resend', '@sendgrid/mail', 'mailgun'],
+        contentRegex: /\b(sendMail|transporter\.send|sendEmail|mail\.send)\b/i,
+    },
+    {
+        label: 'Job queue',
+        deps: ['bull', 'bullmq', 'bee-queue', 'celery', 'rq', 'sidekiq'],
+        contentRegex: /\b(Queue|Job|enqueue|Worker|processJob)\b/i,
+    },
+    {
+        label: 'Caching layer',
+        deps: ['redis', 'ioredis', 'lru-cache', 'cache-manager', '@nestjs/cache-manager'],
+        contentRegex: /\b(cache|caching|redis\.|createCache)\b/i,
+    },
+    {
+        label: 'Data fetching / React Query',
+        deps: ['@tanstack/react-query', 'swr', '@trpc/client', 'react-query'],
+    },
+    {
+        label: 'State management',
+        deps: ['zustand', 'jotai', 'redux', '@reduxjs/toolkit', 'recoil', 'mobx', 'valtio', 'pinia', 'vuex'],
+    },
+    {
+        label: 'WebSocket communication',
+        deps: ['ws', 'socket.io', '@nestjs/websockets', 'uWebSockets.js', 'sockjs'],
+        contentRegex: /\b(WebSocket|socket\.io|ws\.on|socket\.emit)\b/i,
+    },
+    {
+        label: 'GraphQL API',
+        deps: ['graphql', '@apollo/server', 'apollo-server', '@nestjs/graphql', 'graphene', 'strawberry-graphql'],
+        contentRegex: /\b(gql|graphql|ApolloServer|Query|Mutation)\b/i,
+    },
+    {
+        label: 'REST API',
+        files: ['api.ts', 'api.js', 'api.py', 'routes.py', 'router.ts'],
+    },
+    {
+        label: 'Internationalization (i18n)',
+        deps: ['i18next', 'next-i18next', 'react-intl', 'vue-i18n', 'gettext'],
+        files: ['i18n.ts', 'locales/', 'translations/'],
+    },
+    {
+        label: 'Feature flags',
+        deps: ['launchdarkly', '@launchdarkly/node-server-sdk', 'unleash', 'flagsmith'],
+    },
+    {
+        label: 'CLI interface',
+        deps: ['commander', 'yargs', 'clack', '@inquirer/prompts', 'clap', 'click'],
+        files: ['cli.ts', 'cli.js', 'cli.py', 'main.go'],
+    },
+];
+// ---------------------------------------------------------------------------
+// Entry-point file names (ordered by likelihood)
+// ---------------------------------------------------------------------------
+const ENTRY_POINT_CANDIDATES = [
+    'src/app/layout.tsx',
+    'src/app/page.tsx',
+    'src/pages/_app.tsx',
+    'src/pages/_app.ts',
+    'src/pages/index.tsx',
+    'src/pages/index.ts',
+    'src/index.ts',
+    'src/index.tsx',
+    'src/main.ts',
+    'src/main.tsx',
+    'src/main.js',
+    'src/server.ts',
+    'src/server.js',
+    'src/app.ts',
+    'src/app.js',
+    'server.ts',
+    'server.js',
+    'index.ts',
+    'index.js',
+    'main.ts',
+    'main.js',
+    'app.ts',
+    'app.js',
+    'src/main.rs',
+    'main.rs',
+    'src/main.go',
+    'main.go',
+    'src/app.py',
+    'app.py',
+    'main.py',
+    'src/__main__.py',
+    'src/main.rb',
+    'main.rb',
+    'src/Main.java',
+    'src/main/java',
+    'next.config.js',
+    'next.config.ts',
+    'next.config.mjs',
+];
+const scanCache = new Map();
+function cacheKey(rootPath) {
+    return createHash('md5').update(rootPath).digest('hex');
+}
+function getCached(rootPath) {
+    const key = cacheKey(rootPath);
+    const entry = scanCache.get(key);
+    if (!entry)
+        return null;
+    if (Date.now() - entry.timestamp > CACHE_TTL_MS) {
+        scanCache.delete(key);
+        return null;
+    }
+    return entry.image;
+}
+function setCached(rootPath, image) {
+    scanCache.set(cacheKey(rootPath), {
+        image,
+        timestamp: Date.now(),
+        hash: '',
+    });
+}
+function clearCache() {
+    scanCache.clear();
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function pathExists(p) {
+    try {
+        await fsp.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function safeReadFile(filePath) {
+    try {
+        const stat = await fsp.stat(filePath);
+        if (stat.size > MAX_FILE_SIZE)
+            return '';
+        return await fsp.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+async function safeReadJson(filePath) {
+    const raw = await safeReadFile(filePath);
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function readFirstLines(raw, count) {
+    const lines = raw.split('\n');
+    if (lines.length <= count)
+        return raw;
+    return lines.slice(0, count).join('\n');
+}
+/** Read .gitignore patterns from a file and return a set of ignore globs. */
+function parseGitignore(content) {
+    return content
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith('#'));
+}
+/** Check if a relative path should be ignored based on ignore patterns and built-in ignore dirs. */
+function shouldIgnorePath(relativePath, ignorePatterns, options) {
+    const parts = relativePath.split(path.sep);
+    for (const part of parts) {
+        if (options.ignoreDirs.has(part))
+            return true;
+        if (part.startsWith('.'))
+            return true;
+    }
+    for (const pattern of ignorePatterns) {
+        if (pattern.startsWith('/')) {
+            const clean = pattern.slice(1);
+            if (clean === relativePath)
+                return true;
+            if (clean.endsWith('/') && relativePath.startsWith(clean))
+                return true;
+            if (relativePath === clean)
+                return true;
+            if (relativePath.startsWith(clean + '/'))
+                return true;
+        }
+        else if (pattern.endsWith('/')) {
+            const clean = pattern.slice(0, -1);
+            if (relativePath === clean)
+                return true;
+            if (relativePath.startsWith(clean + '/'))
+                return true;
+            if (parts.includes(clean))
+                return true;
+        }
+        else {
+            if (relativePath === pattern)
+                return true;
+            if (relativePath.endsWith('/' + pattern))
+                return true;
+            if (parts.includes(pattern))
+                return true;
+        }
+    }
+    return false;
+}
+/** Infer the purpose of a directory based on its name. */
+function inferDirectoryPurpose(dirName, parentPurpose) {
+    const lower = dirName.toLowerCase();
+    for (const entry of DIR_PURPOSE_MAP) {
+        if (entry.names.includes(lower)) {
+            return entry.purpose;
+        }
+    }
+    if (parentPurpose === 'routes')
+        return 'routes';
+    if (dirName.startsWith('page') || dirName.startsWith('route'))
+        return 'routes';
+    return 'root';
+}
+/** Check if a file is a test file. */
+function isTestFile(fileName) {
+    return TEST_FILE_PATTERNS.some((p) => p.test(fileName));
+}
+async function detectLanguageAndPackageManager(rootPath) {
+    let language = 'unknown';
+    let version = '';
+    let configFile = '';
+    let packageManager = 'unknown';
+    // Check config files for language detection
+    const configChecks = [];
+    for (const [lang, entry] of Object.entries(LANG_MAP)) {
+        const fp = path.join(rootPath, entry.configFile);
+        configChecks.push([lang, fp]);
+    }
+    for (const [lang, fp] of configChecks) {
+        if (await pathExists(fp)) {
+            const entry = LANG_MAP[lang];
+            language = lang;
+            configFile = entry.configFile;
+            // Detect version
+            if (entry.versionFromConfig) {
+                const raw = await safeReadFile(fp);
+                if (raw)
+                    version = entry.versionFromConfig(raw);
+            }
+            if (!version && entry.versionFile) {
+                const verRaw = await safeReadFile(path.join(rootPath, entry.versionFile));
+                if (verRaw) {
+                    version = verRaw.trim().replace('v', '');
+                }
+            }
+            break;
+        }
+    }
+    // If no config file found, fall back to extension counting
+    if (language === 'unknown') {
+        language = await detectLanguageByExtensions(rootPath);
+    }
+    // Typescript vs JavaScript refinement
+    if (language === 'javascript') {
+        const tsconfig = await pathExists(path.join(rootPath, 'tsconfig.json'));
+        if (tsconfig) {
+            language = 'typescript';
+            configFile = 'tsconfig.json';
+        }
+    }
+    // TypeScript version from package.json (not from tsconfig.json)
+    if (!version && (language === 'typescript' || language === 'javascript')) {
+        const pkgRaw = await safeReadFile(path.join(rootPath, 'package.json'));
+        if (pkgRaw) {
+            try {
+                const pkg = JSON.parse(pkgRaw);
+                const deps = { ...(pkg.devDependencies || {}), ...(pkg.dependencies || {}) };
+                if (deps.typescript) {
+                    version = deps.typescript;
+                }
+            }
+            catch {
+                // ignore parse errors
+            }
+        }
+    }
+    // Package manager detection
+    for (const [lockFile, manager] of Object.entries(PKG_MANAGER_MAP)) {
+        if (await pathExists(path.join(rootPath, lockFile))) {
+            packageManager = manager;
+            break;
+        }
+    }
+    // Fallback: check for requirements.txt (pip)
+    if (packageManager === 'unknown') {
+        if (await pathExists(path.join(rootPath, 'requirements.txt'))) {
+            packageManager = 'pip';
+        }
+        else if (await pathExists(path.join(rootPath, 'pyproject.toml'))) {
+            packageManager = 'poetry';
+        }
+        else if (await pathExists(path.join(rootPath, 'Pipfile'))) {
+            packageManager = 'pipenv';
+        }
+    }
+    return { language, version, configFile, packageManager };
+}
+async function detectLanguageByExtensions(rootPath) {
+    const extCounts = {};
+    let scanned = 0;
+    const maxScan = 500;
+    try {
+        const entries = await fsp.readdir(rootPath);
+        for (const entry of entries) {
+            if (scanned > maxScan)
+                break;
+            const fullPath = path.join(rootPath, entry);
+            try {
+                const stat = await fsp.stat(fullPath);
+                if (stat.isDirectory()) {
+                    if (IGNORE_DIRS.has(entry))
+                        continue;
+                    const subExts = await countExtensionsInDir(fullPath, 2, maxScan - scanned);
+                    scanned += subExts.scanned;
+                    for (const [ext, count] of Object.entries(subExts.exts)) {
+                        extCounts[ext] = (extCounts[ext] || 0) + count;
+                    }
+                }
+                else {
+                    const ext = path.extname(entry).toLowerCase();
+                    if (ext)
+                        extCounts[ext] = (extCounts[ext] || 0) + 1;
+                    scanned++;
+                }
+            }
+            catch {
+                // skip unreadable
+            }
+        }
+    }
+    catch {
+        // empty directory
+    }
+    // Map extensions to languages
+    const langScores = {};
+    const extToLang = {
+        '.ts': 'typescript',
+        '.tsx': 'typescript',
+        '.js': 'javascript',
+        '.jsx': 'javascript',
+        '.mjs': 'javascript',
+        '.cjs': 'javascript',
+        '.py': 'python',
+        '.rs': 'rust',
+        '.go': 'go',
+        '.rb': 'ruby',
+        '.java': 'java',
+        '.kt': 'kotlin',
+        '.kts': 'kotlin',
+        '.cpp': 'cpp',
+        '.cxx': 'cpp',
+        '.hpp': 'cpp',
+        '.h': 'cpp',
+        '.c': 'cpp',
+        '.cs': 'csharp',
+        '.swift': 'swift',
+        '.php': 'php',
+    };
+    for (const [ext, count] of Object.entries(extCounts)) {
+        const lang = extToLang[ext];
+        if (lang) {
+            langScores[lang] = (langScores[lang] || 0) + count;
+        }
+    }
+    let bestLang = 'unknown';
+    let bestScore = 0;
+    for (const [lang, score] of Object.entries(langScores)) {
+        if (score > bestScore) {
+            bestScore = score;
+            bestLang = lang;
+        }
+    }
+    return bestLang;
+}
+async function countExtensionsInDir(dirPath, depth, remaining) {
+    const exts = {};
+    let scanned = 0;
+    if (depth <= 0 || remaining <= 0)
+        return { exts, scanned };
+    try {
+        const entries = await fsp.readdir(dirPath);
+        for (const entry of entries) {
+            if (scanned >= remaining)
+                break;
+            const full = path.join(dirPath, entry);
+            try {
+                const stat = await fsp.stat(full);
+                if (stat.isDirectory()) {
+                    if (IGNORE_DIRS.has(entry))
+                        continue;
+                    const sub = await countExtensionsInDir(full, depth - 1, remaining - scanned);
+                    for (const [ext, count] of Object.entries(sub.exts)) {
+                        exts[ext] = (exts[ext] || 0) + count;
+                    }
+                    scanned += sub.scanned;
+                }
+                else {
+                    const ext = path.extname(entry).toLowerCase();
+                    if (ext)
+                        exts[ext] = (exts[ext] || 0) + 1;
+                    scanned++;
+                }
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    catch {
+        // skip
+    }
+    return { exts, scanned };
+}
+// ---------------------------------------------------------------------------
+// Framework detection
+// ---------------------------------------------------------------------------
+async function detectFramework(rootPath, language) {
+    if (language === 'typescript' || language === 'javascript') {
+        const pkg = await safeReadJson(path.join(rootPath, 'package.json'));
+        if (!pkg)
+            return '';
+        const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+        for (const [name, label] of Object.entries(JS_FRAMEWORK_MAP)) {
+            if (deps[name]) {
+                const version = deps[name].replace(/^\^|~/, '');
+                // Detect App Router vs Pages Router for Next.js
+                if (name === 'next' && (await pathExists(path.join(rootPath, 'src/app/layout.tsx')) || await pathExists(path.join(rootPath, 'src/app/page.tsx')))) {
+                    return `Next.js ${version} (App Router)`;
+                }
+                if (name === 'next' && (await pathExists(path.join(rootPath, 'src/pages/_app.tsx')))) {
+                    return `Next.js ${version} (Pages Router)`;
+                }
+                return `${label} ${version}`;
+            }
+        }
+        return '';
+    }
+    if (language === 'python') {
+        const pyproject = await safeReadFile(path.join(rootPath, 'pyproject.toml'));
+        const reqs = await safeReadFile(path.join(rootPath, 'requirements.txt'));
+        const combined = (pyproject + '\n' + reqs).toLowerCase();
+        for (const [name, label] of Object.entries(PY_FRAMEWORK_MAP)) {
+            if (combined.includes(name))
+                return label;
+        }
+        return '';
+    }
+    if (language === 'rust') {
+        const cargo = await safeReadFile(path.join(rootPath, 'Cargo.toml')).then((r) => r.toLowerCase());
+        if (!cargo)
+            return '';
+        for (const [name, label] of Object.entries(RS_FRAMEWORK_MAP)) {
+            if (cargo.includes(name))
+                return label;
+        }
+        return '';
+    }
+    if (language === 'go') {
+        const gomod = await safeReadFile(path.join(rootPath, 'go.mod')).then((r) => r.toLowerCase());
+        if (!gomod)
+            return '';
+        for (const [name, label] of Object.entries(GO_FRAMEWORK_MAP)) {
+            if (gomod.includes(name))
+                return label;
+        }
+        return '';
+    }
+    if (language === 'ruby') {
+        const gemfile = await safeReadFile(path.join(rootPath, 'Gemfile')).then((r) => r.toLowerCase());
+        if (!gemfile)
+            return '';
+        for (const [name, label] of Object.entries(RB_FRAMEWORK_MAP)) {
+            if (gemfile.includes(name))
+                return label;
+        }
+        return '';
+    }
+    return '';
+}
+// ---------------------------------------------------------------------------
+// Database & ORM detection
+// ---------------------------------------------------------------------------
+async function detectDatabaseAndORM(rootPath, language) {
+    let database = null;
+    let orm = null;
+    // Check .env files for database URLs
+    for (const envFile of ['.env', '.env.local', '.env.development', '.env.production']) {
+        const envRaw = await safeReadFile(path.join(rootPath, envFile));
+        if (envRaw) {
+            for (const indicator of DB_INDICATORS) {
+                if (indicator.pattern.test(envRaw)) {
+                    if (!database)
+                        database = indicator.label;
+                }
+            }
+        }
+    }
+    // Check Prisma schema for provider
+    const prismaSchema = await safeReadFile(path.join(rootPath, 'prisma/schema.prisma'));
+    if (prismaSchema) {
+        const providerMatch = prismaSchema.match(/provider\s*=\s*"(\w+)"/);
+        if (providerMatch) {
+            const prov = providerMatch[1];
+            const providerMap = {
+                postgresql: 'Postgres',
+                mysql: 'MySQL',
+                sqlite: 'SQLite',
+                sqlserver: 'SQL Server',
+                mongodb: 'MongoDB',
+                cockroachdb: 'CockroachDB',
+            };
+            database = providerMap[prov] || prov;
+        }
+        const modelCount = (prismaSchema.match(/model\s+\w+\s*\{/g) || []).length;
+        orm = `Prisma (${modelCount} ${modelCount === 1 ? 'model' : 'models'})`;
+    }
+    // Check for ORM in package.json (JS/TS projects)
+    if (!orm && (language === 'typescript' || language === 'javascript')) {
+        const pkg = await safeReadJson(path.join(rootPath, 'package.json'));
+        if (pkg) {
+            const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+            for (const [name, label] of Object.entries(ORM_MAP)) {
+                if (deps[name]) {
+                    orm = label;
+                    if (!database && name === 'mongoose')
+                        database = 'MongoDB';
+                    break;
+                }
+            }
+            // Infer database from packages
+            if (!database) {
+                if (deps['pg'])
+                    database = 'Postgres';
+                else if (deps['mysql2'])
+                    database = 'MySQL';
+                else if (deps['mongodb'] || deps['mongoose'])
+                    database = 'MongoDB';
+                else if (deps['better-sqlite3'] || deps['sqlite3'])
+                    database = 'SQLite';
+                else if (deps['redis'] || deps['ioredis'])
+                    database = 'Redis';
+            }
+        }
+    }
+    // Check Python ORM/Database
+    if (language === 'python') {
+        const reqs = await safeReadFile(path.join(rootPath, 'requirements.txt'));
+        const pyproject = await safeReadFile(path.join(rootPath, 'pyproject.toml'));
+        const combined = (reqs + '\n' + pyproject).toLowerCase();
+        if (combined.includes('sqlalchemy')) {
+            if (!orm)
+                orm = 'SQLAlchemy';
+        }
+        if (combined.includes('django') && !orm) {
+            orm = 'Django ORM';
+        }
+        if (combined.includes('psycopg2') && !database)
+            database = 'Postgres';
+        if (combined.includes('pymongo') && !database)
+            database = 'MongoDB';
+        if (combined.includes('redis') && !database)
+            database = 'Redis';
+    }
+    // Check Rust ORM
+    if (language === 'rust') {
+        const cargo = (await safeReadFile(path.join(rootPath, 'Cargo.toml'))).toLowerCase();
+        if (cargo.includes('diesel') && !orm)
+            orm = 'Diesel';
+        if (cargo.includes('sqlx') && !orm)
+            orm = 'SQLx';
+    }
+    return { database, orm };
+}
+// ---------------------------------------------------------------------------
+// Test framework detection
+// ---------------------------------------------------------------------------
+async function detectTestFramework(rootPath, language) {
+    if (language === 'typescript' || language === 'javascript') {
+        const pkg = await safeReadJson(path.join(rootPath, 'package.json'));
+        if (!pkg)
+            return null;
+        const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+        for (const [name, label] of Object.entries(TEST_FRAMEWORK_MAP)) {
+            if (deps[name]) {
+                if (name === 'vitest' && deps['@playwright/test'])
+                    return 'Vitest + Playwright';
+                if (name === 'jest' && deps['@playwright/test'])
+                    return 'Jest + Playwright';
+                return label;
+            }
+        }
+        // Config file checks
+        if (await pathExists(path.join(rootPath, 'jest.config.ts')) || await pathExists(path.join(rootPath, 'jest.config.js')))
+            return 'Jest';
+        if (await pathExists(path.join(rootPath, 'vitest.config.ts')) || await pathExists(path.join(rootPath, 'vitest.config.js')))
+            return 'Vitest';
+        if (await pathExists(path.join(rootPath, 'playwright.config.ts')))
+            return 'Playwright';
+        return null;
+    }
+    if (language === 'python') {
+        if (await pathExists(path.join(rootPath, 'pytest.ini')) ||
+            await pathExists(path.join(rootPath, 'pyproject.toml'))) {
+            const pyproject = await safeReadFile(path.join(rootPath, 'pyproject.toml'));
+            if (pyproject && pyproject.includes('[tool.pytest'))
+                return 'pytest';
+        }
+        const reqs = await safeReadFile(path.join(rootPath, 'requirements.txt'));
+        if (reqs && /pytest/.test(reqs))
+            return 'pytest';
+        return null;
+    }
+    if (language === 'rust')
+        return 'cargo test';
+    if (language === 'go')
+        return 'go test';
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Entry-point detection
+// ---------------------------------------------------------------------------
+async function detectEntryPoints(rootPath) {
+    const found = [];
+    for (const candidate of ENTRY_POINT_CANDIDATES) {
+        if (found.length >= 8)
+            break;
+        if (await pathExists(path.join(rootPath, candidate))) {
+            found.push(candidate);
+        }
+    }
+    // If nothing found, look for any index/main files
+    if (found.length === 0) {
+        const srcDir = path.join(rootPath, 'src');
+        if (await pathExists(srcDir)) {
+            try {
+                const entries = await fsp.readdir(srcDir);
+                for (const e of entries) {
+                    if (/^(index|main|app|server|cli)\./.test(e)) {
+                        found.push(`src/${e}`);
+                    }
+                }
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    return found;
+}
+// ---------------------------------------------------------------------------
+// Dependency extraction
+// ---------------------------------------------------------------------------
+async function extractDependencies(rootPath, language) {
+    const deps = [];
+    if (language === 'typescript' || language === 'javascript') {
+        const pkg = await safeReadJson(path.join(rootPath, 'package.json'));
+        if (pkg) {
+            const prod = pkg.dependencies;
+            const dev = pkg.devDependencies;
+            if (prod) {
+                for (const [name, version] of Object.entries(prod)) {
+                    deps.push({ name, version, type: 'production' });
+                }
+            }
+            if (dev) {
+                for (const [name, version] of Object.entries(dev)) {
+                    deps.push({ name, version, type: 'dev' });
+                }
+            }
+        }
+    }
+    if (language === 'rust') {
+        const cargoRaw = await safeReadFile(path.join(rootPath, 'Cargo.toml'));
+        if (cargoRaw) {
+            const inDeps = cargoRaw.includes('[dependencies]');
+            let inSection = false;
+            for (const line of cargoRaw.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed === '[dependencies]') {
+                    inSection = true;
+                    continue;
+                }
+                if (trimmed.startsWith('[') && inSection) {
+                    inSection = false;
+                    continue;
+                }
+                if (inSection && trimmed && !trimmed.startsWith('#')) {
+                    const depMatch = trimmed.match(/^(\S+)\s*=\s*"([^"]+)"/);
+                    if (depMatch) {
+                        deps.push({ name: depMatch[1], version: depMatch[2], type: 'production' });
+                    }
+                    else {
+                        const nameOnly = trimmed.split('=')[0]?.trim();
+                        if (nameOnly && !nameOnly.startsWith('[')) {
+                            deps.push({ name: nameOnly, version: '', type: 'production' });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (language === 'go') {
+        const gomod = await safeReadFile(path.join(rootPath, 'go.mod'));
+        if (gomod) {
+            const lines = gomod.split('\n');
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed.startsWith('require ')) {
+                    const parts = trimmed.slice(8).split(/\s+/);
+                    if (parts.length >= 2) {
+                        deps.push({ name: parts[0], version: parts[1], type: 'production' });
+                    }
+                }
+            }
+        }
+    }
+    if (language === 'ruby') {
+        const gemfile = await safeReadFile(path.join(rootPath, 'Gemfile'));
+        if (gemfile) {
+            for (const line of gemfile.split('\n')) {
+                const m = line.match(/gem\s+['"](\S+)['"](?:,\s*['"]([^'"]+)['"])?/);
+                if (m) {
+                    deps.push({ name: m[1], version: m[2] || '', type: 'production' });
+                }
+            }
+        }
+    }
+    if (language === 'python') {
+        const reqs = await safeReadFile(path.join(rootPath, 'requirements.txt'));
+        if (reqs) {
+            for (const line of reqs.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('-')) {
+                    const pair = trimmed.split(/[=<>~!]+/);
+                    const name = pair[0].trim();
+                    const ver = trimmed.slice(name.length).trim().replace(/^[=<>~!]+/, '');
+                    if (name)
+                        deps.push({ name, version: ver, type: 'production' });
+                }
+            }
+        }
+    }
+    return deps;
+}
+// ---------------------------------------------------------------------------
+// Directory structure scanning
+// ---------------------------------------------------------------------------
+async function scanDirectoryStructure(dirPath, relativePath, depth, options, ignorePatterns) {
+    const name = path.basename(dirPath);
+    const result = {
+        path: relativePath || '.',
+        name,
+        purpose: inferDirectoryPurpose(name),
+        itemCount: 0,
+        notableFiles: [],
+        children: [],
+    };
+    if (depth > options.maxDepth)
+        return result;
+    let entries;
+    try {
+        entries = await fsp.readdir(dirPath);
+    }
+    catch {
+        return result;
+    }
+    const files = [];
+    const dirs = [];
+    for (const entry of entries) {
+        const relEntry = relativePath ? path.join(relativePath, entry) : entry;
+        if (shouldIgnorePath(relEntry, ignorePatterns, options))
+            continue;
+        try {
+            const fullPath = path.join(dirPath, entry);
+            const stat = await fsp.stat(fullPath);
+            if (stat.isDirectory()) {
+                dirs.push(entry);
+            }
+            else if (stat.isFile()) {
+                files.push(entry);
+            }
+        }
+        catch {
+            // skip unreadable
+        }
+    }
+    result.itemCount = dirs.length + files.length;
+    // Sort and collect notable files
+    const sortedFiles = files.sort();
+    const keyFiles = sortedFiles.filter((f) => {
+        const lf = f.toLowerCase();
+        return (!lf.startsWith('.') &&
+            !lf.endsWith('.map') &&
+            !lf.endsWith('.lock') &&
+            !lf.endsWith('.json') &&
+            lf !== 'readme.md' &&
+            lf !== 'license');
+    });
+    result.notableFiles = keyFiles.slice(0, 12);
+    // Recurse into subdirectories
+    for (const dirName of dirs.sort()) {
+        const fullPath = path.join(dirPath, dirName);
+        const relPath = relativePath ? path.join(relativePath, dirName) : dirName;
+        const child = await scanDirectoryStructure(fullPath, relPath, depth + 1, options, ignorePatterns);
+        result.children.push(child);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Architecture detection
+// ---------------------------------------------------------------------------
+async function detectArchitecture(rootPath, structure) {
+    // Check for monorepo structure
+    if (await pathExists(path.join(rootPath, 'packages')) ||
+        await pathExists(path.join(rootPath, 'apps'))) {
+        return 'monorepo';
+    }
+    // Check for microservices
+    if (await pathExists(path.join(rootPath, 'docker-compose.yml'))) {
+        const dc = await safeReadFile(path.join(rootPath, 'docker-compose.yml'));
+        if (dc) {
+            const serviceCount = (dc.match(/^\s{2}\w+:[ \t]*$/gm) || []).length;
+            if (serviceCount >= 3)
+                return 'microservices';
+        }
+    }
+    // Check for serverless
+    if (await pathExists(path.join(rootPath, 'serverless.yml')) ||
+        await pathExists(path.join(rootPath, 'serverless.ts')) ||
+        await pathExists(path.join(rootPath, 'template.yaml'))) {
+        return 'serverless';
+    }
+    // Check for MVC pattern
+    const hasControllers = structure.some((n) => n.purpose === 'controllers');
+    const hasModels = structure.some((n) => n.purpose === 'models');
+    const hasRoutes = structure.some((n) => n.purpose === 'routes');
+    if (hasControllers && (hasModels || hasRoutes))
+        return 'mvc';
+    // Check for layered architecture
+    const hasServices = structure.some((n) => n.purpose === 'services');
+    const hasLib = structure.some((n) => n.purpose === 'utilities');
+    if (hasServices && hasLib)
+        return 'layered';
+    return 'monolith';
+}
+// ---------------------------------------------------------------------------
+// Key pattern detection
+// ---------------------------------------------------------------------------
+async function detectKeyPatterns(rootPath, language, deps, structure) {
+    const patterns = new Set();
+    const depNames = new Set(deps.map((d) => d.name.toLowerCase()));
+    // Collect all files across the structure
+    function collectFiles(nodes) {
+        const files = [];
+        for (const node of nodes) {
+            files.push(...node.notableFiles, ...node.notableFiles.map((f) => node.path + '/' + f));
+            files.push(...collectFiles(node.children));
+        }
+        return files;
+    }
+    const allFiles = collectFiles(structure);
+    const fileSet = new Set(allFiles.map((f) => f.toLowerCase()));
+    for (const rule of KEY_PATTERN_RULES) {
+        let detected = false;
+        // Check file names
+        if (rule.files) {
+            for (const fileName of rule.files) {
+                for (const f of allFiles) {
+                    if (f.toLowerCase().includes(fileName.toLowerCase())) {
+                        detected = true;
+                        break;
+                    }
+                }
+                if (detected)
+                    break;
+            }
+        }
+        // Check dependencies
+        if (!detected && rule.deps) {
+            for (const depName of rule.deps) {
+                if (depNames.has(depName.toLowerCase())) {
+                    detected = true;
+                    break;
+                }
+            }
+        }
+        // Check content in key files (sample only)
+        if (!detected && rule.contentRegex) {
+            // Sample a few known config/auth/middleware files
+            const sampleFiles = ['middleware.ts', 'auth.ts', 'config.ts', 'api.ts', 'app.ts', 'main.ts', 'server.ts'];
+            for (const sf of sampleFiles) {
+                const content = await safeReadFile(path.join(rootPath, sf));
+                if (content && rule.contentRegex.test(content)) {
+                    detected = true;
+                    break;
+                }
+                if (await pathExists(path.join(rootPath, 'src', sf))) {
+                    const srcContent = await safeReadFile(path.join(rootPath, 'src', sf));
+                    if (srcContent && rule.contentRegex.test(srcContent)) {
+                        detected = true;
+                        break;
+                    }
+                }
+            }
+        }
+        if (detected) {
+            patterns.add(rule.label);
+        }
+    }
+    return Array.from(patterns);
+}
+// ---------------------------------------------------------------------------
+// File & test counting
+// ---------------------------------------------------------------------------
+async function countFiles(rootPath, options, ignorePatterns) {
+    let fileCount = 0;
+    let testCount = 0;
+    async function walk(dirPath, relativePath, depth) {
+        if (depth > 10)
+            return;
+        let entries;
+        try {
+            entries = await fsp.readdir(dirPath);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(dirPath, entry);
+            const relPath = relativePath ? path.join(relativePath, entry) : entry;
+            if (shouldIgnorePath(relPath, ignorePatterns, options))
+                continue;
+            try {
+                const stat = await fsp.stat(fullPath);
+                if (stat.isDirectory()) {
+                    await walk(fullPath, relPath, depth + 1);
+                }
+                else if (stat.isFile()) {
+                    fileCount++;
+                    if (isTestFile(entry))
+                        testCount++;
+                }
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    await walk(rootPath, '', 0);
+    return { fileCount, testCount };
+}
+// ---------------------------------------------------------------------------
+// Main scan function
+// ---------------------------------------------------------------------------
+/**
+ * Scan a codebase directory and produce a compressed schema image.
+ *
+ * The schema image captures language, framework, package manager, database,
+ * ORM, test framework, entry points, project structure, dependencies,
+ * architecture pattern, and key patterns — everything an LLM needs to
+ * understand a codebase without reading all the files.
+ *
+ * @param rootPath - Absolute or relative path to the project root.
+ * @returns A SchemaImage with all detected information.
+ */
+export async function scanCodebase(rootPath) {
+    const resolvedPath = path.resolve(rootPath);
+    const cached = getCached(resolvedPath);
+    if (cached)
+        return cached;
+    if (!(await pathExists(resolvedPath))) {
+        throw new Error(`Path does not exist: ${resolvedPath}`);
+    }
+    const options = {
+        maxDepth: MAX_SCAN_DEPTH,
+        maxFileSize: MAX_FILE_SIZE,
+        ignoreDirs: IGNORE_DIRS,
+    };
+    // Parse .gitignore
+    let ignorePatterns = [];
+    const gitignore = await safeReadFile(path.join(resolvedPath, '.gitignore'));
+    if (gitignore) {
+        ignorePatterns = parseGitignore(gitignore);
+    }
+    // Also read .dockerignore for additional patterns
+    const dkrignore = await safeReadFile(path.join(resolvedPath, '.dockerignore'));
+    if (dkrignore) {
+        ignorePatterns = ignorePatterns.concat(parseGitignore(dkrignore));
+    }
+    // Detect language, package manager
+    const lang = await detectLanguageAndPackageManager(resolvedPath);
+    let languageLabel = lang.language;
+    if (lang.version) {
+        const displayMap = {
+            typescript: `TypeScript ^${lang.version.replace(/\^|~/g, '')}`,
+            javascript: 'JavaScript',
+            python: `Python ${lang.version}`,
+            rust: `Rust (${lang.version})`,
+            go: lang.version,
+            ruby: `Ruby ${lang.version}`,
+            java: 'Java',
+            kotlin: 'Kotlin',
+        };
+        languageLabel = displayMap[lang.language] || lang.language;
+    }
+    else {
+        const simpleMap = {
+            typescript: 'TypeScript',
+            javascript: 'JavaScript',
+            python: 'Python',
+            rust: 'Rust',
+            go: 'Go',
+            ruby: 'Ruby',
+            java: 'Java',
+            kotlin: 'Kotlin',
+        };
+        languageLabel = simpleMap[lang.language] || lang.language;
+    }
+    // Project name
+    let projectName = path.basename(resolvedPath);
+    const pkg = lang.configFile === 'package.json'
+        ? await safeReadJson(path.join(resolvedPath, 'package.json'))
+        : null;
+    if (pkg && typeof pkg.name === 'string') {
+        projectName = pkg.name;
+    }
+    // Framework
+    const framework = await detectFramework(resolvedPath, lang.language);
+    // Database & ORM
+    const dbOrm = await detectDatabaseAndORM(resolvedPath, lang.language);
+    // Test framework
+    const testFramework = await detectTestFramework(resolvedPath, lang.language);
+    // Entry points
+    const entryPoints = await detectEntryPoints(resolvedPath);
+    // Structure — rootNode.children gives top-level dirs as DirectoryNode[]
+    const rootNode = await scanDirectoryStructure(resolvedPath, '', 0, options, ignorePatterns);
+    const structure = rootNode.children;
+    // Dependencies
+    const dependencies = await extractDependencies(resolvedPath, lang.language);
+    // File counts
+    const { fileCount, testCount } = await countFiles(resolvedPath, options, ignorePatterns);
+    // Architecture
+    const architecture = await detectArchitecture(resolvedPath, rootNode.children);
+    // Key patterns
+    const keyPatterns = await detectKeyPatterns(resolvedPath, lang.language, dependencies, rootNode.children);
+    const image = {
+        projectName,
+        rootPath: resolvedPath,
+        language: languageLabel,
+        framework: framework || languageLabel,
+        packageManager: lang.packageManager,
+        database: dbOrm.database,
+        orm: dbOrm.orm,
+        testFramework,
+        entryPoints,
+        structure,
+        dependencies,
+        architecture,
+        keyPatterns,
+        fileCount,
+        testCount,
+        lastScan: new Date().toISOString(),
+    };
+    setCached(resolvedPath, image);
+    return image;
+}
+// ---------------------------------------------------------------------------
+// Schema image → text compression
+// ---------------------------------------------------------------------------
+/**
+ * Compress a SchemaImage into a human-readable text block optimized for LLM
+ * context windows. This is the "schema image" text that should be injected
+ * into system prompts to eliminate cold starts.
+ *
+ * @param image - The schema image from {@link scanCodebase}.
+ * @returns A compressed text block describing the codebase.
+ */
+export function schemaImageToText(image) {
+    const lines = [];
+    lines.push('[CODEBASE SCHEMA — auto-detected]');
+    lines.push(`Project: ${image.projectName}`);
+    lines.push(`Language: ${image.language}`);
+    if (image.framework && image.framework !== image.language) {
+        lines.push(`Framework: ${image.framework}`);
+    }
+    lines.push(`Package: ${image.packageManager}`);
+    if (image.database)
+        lines.push(`Database: ${image.database}${image.orm ? ` (via ${image.orm})` : ''}`);
+    else if (image.orm)
+        lines.push(`ORM: ${image.orm}`);
+    if (image.testFramework) {
+        const testLabel = image.testCount > 0
+            ? `${image.testFramework} (${image.testCount} test files)`
+            : image.testFramework;
+        lines.push(`Tests: ${testLabel}`);
+    }
+    const epDisplay = image.entryPoints.slice(0, 5);
+    if (epDisplay.length > 0)
+        lines.push(`Entry: ${epDisplay.join(', ')}`);
+    // Structure — flatten to readable format
+    if (image.structure.length > 0) {
+        lines.push('');
+        lines.push('Structure:');
+        const PURPOSE_LABELS = {
+            routes: 'routes',
+            components: 'components',
+            utilities: 'utilities',
+            services: 'services',
+            hooks: 'hooks',
+            models: 'models',
+            controllers: 'controllers',
+            middleware: 'middleware',
+            store: 'state',
+            types: 'types',
+            config: 'config',
+            styles: 'styles',
+            assets: 'static assets',
+            tests: 'tests',
+            'e2e-tests': 'e2e tests',
+            docs: 'docs',
+            scripts: 'scripts',
+            migrations: 'migrations',
+            infrastructure: 'infra',
+            prisma: 'Prisma schema',
+            api: 'API handlers',
+            db: 'database',
+            root: '',
+        };
+        function flattenStructure(nodes, indent, maxDepth, depth, maxChildren) {
+            if (depth > maxDepth)
+                return;
+            const sorted = nodes
+                .filter((n) => n.name !== '.' && n.name !== 'node_modules' && !n.name.startsWith('.'))
+                .slice(0, depth === 0 ? 15 : 6);
+            for (const node of sorted) {
+                const purposeLabel = PURPOSE_LABELS[node.purpose] || '';
+                const purposeStr = purposeLabel ? ` — ${purposeLabel}` : '';
+                const fileSample = node.notableFiles
+                    .filter((f) => f.length < 40)
+                    .slice(0, 3)
+                    .join(', ');
+                const itemStr = fileSample
+                    ? `${node.itemCount} items (${fileSample}${node.notableFiles.length > 3 ? ', ...' : ''})`
+                    : `${node.itemCount} items`;
+                lines.push(`${indent}  ${node.name}/${purposeStr} — ${itemStr}`);
+                const children = node.children.filter((c) => !c.name.startsWith('.')).slice(0, maxChildren);
+                if (children.length > 0) {
+                    flattenStructure(children, indent + '  ', maxDepth - 1, depth + 1, Math.max(2, maxChildren - 2));
+                }
+            }
+        }
+        flattenStructure(image.structure, '', 3, 0, 6);
+    }
+    // Key patterns
+    if (image.keyPatterns.length > 0) {
+        lines.push('');
+        lines.push('Key patterns:');
+        for (const pat of image.keyPatterns.slice(0, 10)) {
+            lines.push(`  - ${pat}`);
+        }
+    }
+    // Dependencies summary
+    if (image.dependencies.length > 0) {
+        const notable = filterNotableDeps(image.dependencies, image.language);
+        if (notable.length > 0) {
+            lines.push('');
+            lines.push(`Dependencies: ${notable.join(', ')}`);
+        }
+    }
+    lines.push('');
+    const archLabel = {
+        mvc: 'MVC',
+        microservices: 'Microservices',
+        monolith: 'Monolith',
+        monorepo: 'Monorepo',
+        layered: 'Layered',
+        serverless: 'Serverless',
+        unknown: 'Unknown',
+    };
+    lines.push(`Files: ${image.fileCount} total${image.testCount > 0 ? `, ${image.testCount} test files` : ''}`);
+    lines.push(`Architecture: ${archLabel[image.architecture] || image.architecture}`);
+    return lines.join('\n');
+}
+/**
+ * Filter dependencies to only the notable ones (framework, db, auth, etc.)
+ * to keep the output compact.
+ */
+function filterNotableDeps(deps, language) {
+    const notableNames = new Set([
+        'next', 'nuxt', 'react', 'react-dom', 'vue', 'angular',
+        'express', 'fastify', 'koa', 'nest', '@nestjs/core',
+        'prisma', '@prisma/client', 'typeorm', 'sequelize', 'mongoose', 'drizzle-orm',
+        'pg', 'mysql2', 'mongodb', 'redis', 'ioredis',
+        'jsonwebtoken', 'jose', 'next-auth', '@auth/core',
+        'zod', 'yup', 'joi',
+        'stripe', '@stripe/stripe-js',
+        'tailwindcss', '@tailwindcss/typography',
+        'jest', 'vitest', '@playwright/test', 'cypress',
+        'zustand', 'jotai', 'redux', '@reduxjs/toolkit',
+        'socket.io', 'ws',
+        'fastapi', 'django', 'flask',
+        'axum', 'actix-web', 'rocket',
+        'gin', 'echo', 'fiber',
+        'rails',
+    ]);
+    const result = [];
+    for (const dep of deps) {
+        const baseName = dep.name.replace(/^@/, '').split('/')[0];
+        if (notableNames.has(dep.name) || notableNames.has(baseName)) {
+            const ver = dep.version.replace(/^\^|~/, '');
+            result.push(`${dep.name}@${ver}`);
+        }
+    }
+    return result.slice(0, 15);
+}
+// ---------------------------------------------------------------------------
+// File watcher
+// ---------------------------------------------------------------------------
+/**
+ * Watch a codebase directory for changes and re-scan automatically.
+ *
+ * Uses Node.js built-in `fs.watch` with a 500ms debounce. If chokidar is
+ * available as an optional dependency, it will be preferred automatically
+ * (more reliable cross-platform watching).
+ *
+ * @param rootPath - Absolute or relative path to the project root.
+ * @param onChange - Callback invoked with the updated SchemaImage on changes.
+ * @returns An object with a `stop()` method to stop watching.
+ */
+export function watchCodebase(rootPath, onChange) {
+    const resolvedPath = path.resolve(rootPath);
+    let watcher = null;
+    let debounceTimer;
+    let stopped = false;
+    const handleChange = () => {
+        if (stopped)
+            return;
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(async () => {
+            if (stopped)
+                return;
+            try {
+                clearCache(); // invalidate cache to force fresh scan
+                const image = await scanCodebase(resolvedPath);
+                onChange(image);
+            }
+            catch {
+                // Silently ignore scan errors during watch
+            }
+        }, 500);
+    };
+    // Try to require chokidar optionally
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let chokidar;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        chokidar = require('chokidar');
+    }
+    catch {
+        // chokidar not available, fall back to fs.watch
+    }
+    if (chokidar) {
+        const cw = chokidar.watch(resolvedPath, {
+            ignored: [
+                /(^|[\/\\])\./,
+                '**/node_modules/**',
+                '**/.git/**',
+                '**/dist/**',
+                '**/build/**',
+                '**/target/**',
+            ],
+            persistent: true,
+            ignoreInitial: true,
+        });
+        cw.on('add', handleChange);
+        cw.on('change', handleChange);
+        cw.on('unlink', handleChange);
+        cw.on('addDir', handleChange);
+        cw.on('unlinkDir', handleChange);
+        return {
+            stop: () => {
+                stopped = true;
+                cw.close();
+                if (debounceTimer)
+                    clearTimeout(debounceTimer);
+            },
+        };
+    }
+    // Fallback to fs.watch
+    try {
+        watcher = fsWatch(resolvedPath, { recursive: true }, (_eventType, _filename) => {
+            handleChange();
+        });
+    }
+    catch {
+        // Some systems don't support recursive fs.watch
+        try {
+            watcher = fsWatch(resolvedPath, (_eventType, _filename) => {
+                handleChange();
+            });
+        }
+        catch {
+            // Fallback: poll every 10 seconds
+            const interval = setInterval(() => handleChange(), 10_000);
+            return {
+                stop: () => {
+                    stopped = true;
+                    clearInterval(interval);
+                    if (debounceTimer)
+                        clearTimeout(debounceTimer);
+                },
+            };
+        }
+    }
+    return {
+        stop: () => {
+            stopped = true;
+            if (watcher)
+                watcher.close();
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Project size estimation
+// ---------------------------------------------------------------------------
+/**
+ * Estimate the size of a project (file count and total lines of code).
+ *
+ * Attempts to use `cloc` if available on the system, otherwise falls back
+ * to a manual line count via Node.js built-in `fs` operations. The manual
+ * fallback caps at 10,000 files for performance.
+ *
+ * @param rootPath - Absolute or relative path to the project root.
+ * @returns A ProjectSize with file count and approximate line count.
+ */
+export async function estimateProjectSize(rootPath) {
+    const resolvedPath = path.resolve(rootPath);
+    // Try cloc first (fast, accurate)
+    try {
+        const output = execSync(`cloc --json "${resolvedPath}" 2>/dev/null`, {
+            timeout: 30_000,
+            encoding: 'utf-8',
+        });
+        const data = JSON.parse(output);
+        if (data?.SUM) {
+            return { files: data.SUM.nFiles || 0, lines: data.SUM.code || 0 };
+        }
+    }
+    catch {
+        // cloc not available, fall back to manual count
+    }
+    // Manual fallback
+    const options = {
+        maxDepth: 20,
+        maxFileSize: MAX_FILE_SIZE,
+        ignoreDirs: IGNORE_DIRS,
+    };
+    let ignorePatterns = [];
+    const gitignore = await safeReadFile(path.join(resolvedPath, '.gitignore'));
+    if (gitignore)
+        ignorePatterns = parseGitignore(gitignore);
+    let files = 0;
+    let lines = 0;
+    async function walk(dirPath, relPath, depth) {
+        if (depth > 12 || files > 10_000)
+            return;
+        let entries;
+        try {
+            entries = await fsp.readdir(dirPath);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (files > 10_000)
+                return;
+            const full = path.join(dirPath, entry);
+            const rel = relPath ? path.join(relPath, entry) : entry;
+            if (shouldIgnorePath(rel, ignorePatterns, options))
+                continue;
+            try {
+                const stat = await fsp.stat(full);
+                if (stat.isDirectory()) {
+                    await walk(full, rel, depth + 1);
+                }
+                else if (stat.isFile()) {
+                    files++;
+                    const content = await safeReadFile(full);
+                    if (content) {
+                        lines += content.split('\n').length;
+                    }
+                }
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    await walk(resolvedPath, '', 0);
+    return { files, lines };
+}
+//# sourceMappingURL=codebase-scanner.js.map