structx 1.0.0 → 2.1.0

package/README.md

@@ -0,0 +1,72 @@
+# StructX
+
+Graph-powered code intelligence for TypeScript. Drop into any project and let AI agents (Claude Code, Cursor, Copilot) use a function-level knowledge graph instead of reading raw files.
+
+## Quick Start
+
+Two commands to set up any TypeScript project:
+
+```bash
+# 1. Install AI agent instruction files into your project
+npx structx install .
+
+# 2. Bootstrap the function graph (init + ingest + analyze)
+ANTHROPIC_API_KEY=your-key npx structx setup .
+```
+
+That's it. Your AI agent will now automatically use StructX when it reads the instruction files.
+
+## What Happens
+
+**Step 1 — `npx structx install .`** creates these files in your project:
+
+| File | For |
+|------|-----|
+| `CLAUDE.md` | Claude Code |
+| `.cursorrules` | Cursor |
+| `.github/copilot-instructions.md` | GitHub Copilot |
+
+If any of these files already exist, StructX appends its section instead of overwriting.
+
+**Step 2 — `npx structx setup .`** does three things in one shot:
+
+1. **Init** — creates `.structx/` directory with a SQLite database
+2. **Ingest** — parses all TypeScript files into a function graph (signatures, call relationships, exports)
+3. **Analyze** — enriches each function with semantic metadata via LLM (purpose, behavior, tags)
+
+## Requirements
+
+- Node.js >= 18
+- An Anthropic API key (set as `ANTHROPIC_API_KEY` environment variable)
+
+## How AI Agents Use It
+
+Once installed, the instruction files tell your AI agent to:
+
+1. Run `npx structx status` on session start to check the graph
+2. Run `npx structx ask "question" --repo .` before answering code questions
+3. Run `npx structx ingest .` after making code changes
+4. Run `npx structx analyze . --yes` after ingestion queues new functions
+5. Run `npx structx ask "what breaks if I change X" --repo .` for impact analysis
+
+## All Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx structx install .` | Drop instruction files into your project |
+| `npx structx setup .` | One-step bootstrap (init + ingest + analyze) |
+| `npx structx status` | Show graph stats |
+| `npx structx ingest .` | Re-parse codebase after changes |
+| `npx structx analyze . --yes` | Run semantic analysis on new/changed functions |
+| `npx structx ask "question" --repo .` | Query the function graph |
+| `npx structx doctor` | Validate environment and configuration |
+
+## .gitignore
+
+Add this to your `.gitignore`:
+
+```
+.structx/
+```
+
+The `.structx/` directory contains the SQLite database and is local to each developer.

package/dist/cli.js

@@ -42,10 +42,6 @@ const config_1 = require("./config");
 const connection_1 = require("./db/connection");
 const queries_1 = require("./db/queries");
 const logger_1 = require("./utils/logger");
-const scanner_1 = require("./ingest/scanner");
-const parser_1 = require("./ingest/parser");
-const relationships_1 = require("./ingest/relationships");
-const differ_1 = require("./ingest/differ");
 const analyzer_1 = require("./semantic/analyzer");
 const cost_1 = require("./semantic/cost");
 const queries_2 = require("./db/queries");
@@ -55,11 +51,12 @@ const context_builder_1 = require("./query/context-builder");
 const answerer_1 = require("./query/answerer");
 const runner_1 = require("./benchmark/runner");
 const reporter_1 = require("./benchmark/reporter");
+const ingester_1 = require("./ingest/ingester");
 const program = new commander_1.Command();
 program
     .name('structx')
     .description('Graph-powered code intelligence CLI for TypeScript')
-    .version('1.0.0')
+    .version('2.1.0')
     .option('--verbose', 'Enable verbose logging')
     .hook('preAction', (thisCommand) => {
     if (thisCommand.opts().verbose) {
@@ -71,7 +68,8 @@ program
     .command('setup')
     .description('One-step bootstrap: init + ingest + analyze')
     .argument('[repo-path]', 'Path to TypeScript repository', '.')
-    .action(async (repoPath) => {
+    .option('--api-key <key>', 'Anthropic API key (overrides ANTHROPIC_API_KEY env var)')
+    .action(async (repoPath, opts) => {
     const resolved = path.resolve(repoPath);
     const structxDir = (0, config_1.getStructXDir)(resolved);
     // Step 1: Init
@@ -87,102 +85,14 @@ program
     }
     // Step 2: Ingest
     const config = (0, config_1.loadConfig)(structxDir);
+    if (opts.apiKey)
+        config.anthropicApiKey = opts.apiKey;
     const db = (0, connection_1.openDatabase)(dbPath);
-    const project = (0, parser_1.createProject)(resolved);
     console.log(`\nScanning ${resolved} for TypeScript files...`);
-    const files = (0, scanner_1.scanDirectory)(resolved);
-    console.log(`Found ${files.length} TypeScript files.`);
-    let newFiles = 0;
-    let changedFiles = 0;
-    let unchangedFiles = 0;
-    let totalFunctions = 0;
-    let totalRelationships = 0;
-    let queued = 0;
-    for (const filePath of files) {
-        const relativePath = path.relative(resolved, filePath);
-        const content = fs.readFileSync(filePath, 'utf-8');
-        const contentHash = (0, parser_1.hashFileContent)(content);
-        const existingFile = (0, queries_1.getFileByPath)(db, relativePath);
-        if (existingFile && existingFile.content_hash === contentHash) {
-            unchangedFiles++;
-            continue;
-        }
-        const isNew = !existingFile;
-        if (isNew)
-            newFiles++;
-        else
-            changedFiles++;
-        const fileId = (0, queries_1.upsertFile)(db, relativePath, contentHash);
-        const oldFunctions = isNew ? [] : (0, queries_1.getFunctionsByFileId)(db, fileId);
-        const oldFunctionMap = new Map(oldFunctions.map(f => [f.name, f]));
-        if (!isNew) {
-            for (const oldFn of oldFunctions) {
-                (0, queries_1.deleteRelationshipsByCallerFunctionId)(db, oldFn.id);
-            }
-            (0, queries_1.deleteFunctionsByFileId)(db, fileId);
-        }
-        let functions;
-        try {
-            functions = (0, parser_1.parseFile)(project, filePath);
-        }
-        catch (err) {
-            logger_1.logger.warn(`Failed to parse ${relativePath}: ${err.message}`);
-            continue;
-        }
-        const functionIdMap = new Map();
-        for (const fn of functions) {
-            const fnId = (0, queries_1.insertFunction)(db, {
-                file_id: fileId,
-                name: fn.name,
-                signature: fn.signature,
-                body: fn.body,
-                code_hash: fn.codeHash,
-                start_line: fn.startLine,
-                end_line: fn.endLine,
-                is_exported: fn.isExported,
-                is_async: fn.isAsync,
-            });
-            functionIdMap.set(fn.name, fnId);
-            totalFunctions++;
-            const oldFn = oldFunctionMap.get(fn.name);
-            if (!oldFn) {
-                (0, queries_1.enqueueForAnalysis)(db, fnId, 'new', (0, differ_1.getPriority)('new', fn.isExported));
-                queued++;
-            }
-            else {
-                const { reanalyze, reason } = (0, differ_1.shouldReanalyze)(oldFn, fn.signature, fn.codeHash, fn.body, config.diffThreshold);
-                if (reanalyze) {
-                    (0, queries_1.enqueueForAnalysis)(db, fnId, reason, (0, differ_1.getPriority)(reason, fn.isExported));
-                    queued++;
-                }
-            }
-        }
-        try {
-            const calls = (0, relationships_1.extractCallsFromFile)(project, filePath);
-            for (const call of calls) {
-                if (call.callerName === '__file__')
-                    continue;
-                const callerId = functionIdMap.get(call.callerName);
-                if (!callerId)
-                    continue;
-                const callee = (0, queries_1.getFunctionByName)(db, call.calleeName);
-                (0, queries_1.insertRelationship)(db, callerId, call.calleeName, call.relationType, callee?.id);
-                totalRelationships++;
-            }
-        }
-        catch (err) {
-            logger_1.logger.warn(`Failed to extract calls from ${relativePath}: ${err.message}`);
-        }
-    }
-    console.log(`\nIngestion complete:`);
-    console.log(`  New files:       ${newFiles}`);
-    console.log(`  Changed files:   ${changedFiles}`);
-    console.log(`  Unchanged:       ${unchangedFiles}`);
-    console.log(`  Functions:       ${totalFunctions}`);
-    console.log(`  Relationships:   ${totalRelationships}`);
-    console.log(`  Queued:          ${queued} functions for semantic analysis`);
+    const ingestResult = (0, ingester_1.ingestDirectory)(db, resolved, config.diffThreshold);
+    (0, ingester_1.printIngestResult)(ingestResult);
     // Step 3: Analyze (auto-confirm)
-    if (queued > 0 && config.anthropicApiKey) {
+    if (ingestResult.queued > 0 && config.anthropicApiKey) {
         const pendingCount = (0, queries_2.getPendingAnalysisCount)(db);
         const estimate = (0, cost_1.estimateAnalysisCost)(pendingCount, config.batchSize, config.analysisModel);
         console.log('\n' + (0, cost_1.formatCostEstimate)(estimate));
@@ -209,19 +119,47 @@ program
             totalOutputTokens += batchResult.totalOutputTokens;
             totalCost += batchResult.totalCost;
         }
+        // Analyze types, routes, and file summaries
+        console.log('\n  Analyzing types, routes, and file summaries...');
+        const typeResult = await (0, analyzer_1.analyzeTypes)(db, config.analysisModel, config.anthropicApiKey);
+        const routeResult = await (0, analyzer_1.analyzeRoutes)(db, config.analysisModel, config.anthropicApiKey);
+        const fileResult = await (0, analyzer_1.analyzeFileSummaries)(db, config.analysisModel, config.anthropicApiKey);
+        totalAnalyzed += typeResult.analyzed + routeResult.analyzed + fileResult.analyzed;
+        totalFailed += typeResult.failed + routeResult.failed + fileResult.failed;
+        totalInputTokens += typeResult.totalInputTokens + routeResult.totalInputTokens + fileResult.totalInputTokens;
+        totalOutputTokens += typeResult.totalOutputTokens + routeResult.totalOutputTokens + fileResult.totalOutputTokens;
+        totalCost += typeResult.totalCost + routeResult.totalCost + fileResult.totalCost;
         (0, analyzer_1.rebuildSearchIndex)(db);
         console.log(`\nAnalysis complete:`);
-        console.log(`  Analyzed:       ${totalAnalyzed}`);
+        console.log(`  Functions:      ${totalAnalyzed - typeResult.analyzed - routeResult.analyzed - fileResult.analyzed}`);
+        console.log(`  Types:          ${typeResult.analyzed}`);
+        console.log(`  Routes:         ${routeResult.analyzed}`);
+        console.log(`  Files:          ${fileResult.analyzed}`);
         console.log(`  From cache:     ${totalCached}`);
         console.log(`  Failed:         ${totalFailed}`);
         console.log(`  Input tokens:   ${totalInputTokens.toLocaleString()}`);
         console.log(`  Output tokens:  ${totalOutputTokens.toLocaleString()}`);
         console.log(`  Total cost:     $${totalCost.toFixed(4)}`);
     }
-    else if (queued > 0) {
+    else if (ingestResult.queued > 0) {
         console.log('\nSkipping analysis: ANTHROPIC_API_KEY not set.');
         console.log('Set the key and run "structx analyze . --yes" to enrich functions.');
     }
+    else if (config.anthropicApiKey) {
+        // Still analyze types/routes/files even if no new functions
+        console.log('\nAnalyzing types, routes, and file summaries...');
+        const typeResult = await (0, analyzer_1.analyzeTypes)(db, config.analysisModel, config.anthropicApiKey);
+        const routeResult = await (0, analyzer_1.analyzeRoutes)(db, config.analysisModel, config.anthropicApiKey);
+        const fileResult = await (0, analyzer_1.analyzeFileSummaries)(db, config.analysisModel, config.anthropicApiKey);
+        const entityCount = typeResult.analyzed + routeResult.analyzed + fileResult.analyzed;
+        if (entityCount > 0) {
+            (0, analyzer_1.rebuildSearchIndex)(db);
+            console.log(`  Analyzed ${entityCount} entities (${typeResult.analyzed} types, ${routeResult.analyzed} routes, ${fileResult.analyzed} files)`);
+        }
+        else {
+            console.log('No entities to analyze.');
+        }
+    }
     else {
         console.log('\nNo functions to analyze.');
     }
@@ -303,6 +241,25 @@ program
         console.log('  .github/copilot-instructions.md — created.');
         installed++;
     }
+    // AGENTS.md (OpenAI Codex)
+    const agentsMdPath = path.join(resolved, 'AGENTS.md');
+    const codexContent = fs.readFileSync(path.join(instructionsDir, 'codex.md'), 'utf-8');
+    if (fs.existsSync(agentsMdPath)) {
+        const existing = fs.readFileSync(agentsMdPath, 'utf-8');
+        if (existing.includes('StructX')) {
+            console.log('  AGENTS.md — already contains StructX section, skipping.');
+        }
+        else {
+            fs.appendFileSync(agentsMdPath, '\n\n' + codexContent, 'utf-8');
+            console.log('  AGENTS.md — appended StructX section.');
+            installed++;
+        }
+    }
+    else {
+        fs.writeFileSync(agentsMdPath, codexContent, 'utf-8');
+        console.log('  AGENTS.md — created.');
+        installed++;
+    }
     console.log(`\nInstalled ${installed} instruction file(s) into ${resolved}`);
 });
 // ── init ──
@@ -350,11 +307,105 @@ program
     console.log('──────────────────────────');
     console.log(`  Files:           ${stats.totalFiles}`);
     console.log(`  Functions:       ${stats.totalFunctions}`);
+    console.log(`  Types:           ${stats.totalTypes}`);
+    console.log(`  Routes:          ${stats.totalRoutes}`);
+    console.log(`  Constants:       ${stats.totalConstants}`);
     console.log(`  Relationships:   ${stats.totalRelationships}`);
     console.log(`  Analyzed:        ${stats.analyzedFunctions} / ${stats.totalFunctions}`);
     console.log(`  Pending:         ${stats.pendingAnalysis}`);
     console.log(`  QA Runs:         ${stats.totalQaRuns}`);
 });
+// ── overview ──
+program
+    .command('overview')
+    .description('Full codebase summary in one shot — shows all files, functions, types, routes, and constants')
+    .option('--repo <path>', 'Path to TypeScript repository', '.')
+    .action((opts) => {
+    const resolved = path.resolve(opts.repo);
+    const structxDir = (0, config_1.getStructXDir)(resolved);
+    const dbPath = (0, connection_1.getDbPath)(structxDir);
+    if (!fs.existsSync(dbPath)) {
+        console.log('StructX not initialized. Run "structx setup ." first.');
+        return;
+    }
+    const db = (0, connection_1.openDatabase)(dbPath);
+    const overview = (0, queries_1.getFullOverview)(db);
+    db.close();
+    const { stats, files, functions, types, routes, constants } = overview;
+    // Header
+    console.log('StructX Codebase Overview');
+    console.log('═'.repeat(60));
+    console.log(`  Files: ${stats.totalFiles} | Functions: ${stats.totalFunctions} | Types: ${stats.totalTypes} | Routes: ${stats.totalRoutes} | Constants: ${stats.totalConstants}`);
+    console.log(`  Relationships: ${stats.totalRelationships} | Analyzed: ${stats.analyzedFunctions}/${stats.totalFunctions}`);
+    console.log('');
+    // Files section
+    if (files.length > 0) {
+        console.log('── Files ──');
+        for (const f of files) {
+            const purpose = f.summary?.purpose ? ` — ${f.summary.purpose}` : '';
+            const counts = [];
+            if (f.summary) {
+                if (f.summary.function_count > 0)
+                    counts.push(`${f.summary.function_count} fns`);
+                if (f.summary.type_count > 0)
+                    counts.push(`${f.summary.type_count} types`);
+                if (f.summary.route_count > 0)
+                    counts.push(`${f.summary.route_count} routes`);
+                counts.push(`${f.summary.loc} LOC`);
+            }
+            const countsStr = counts.length > 0 ? ` (${counts.join(', ')})` : '';
+            console.log(`  ${f.path}${countsStr}${purpose}`);
+        }
+        console.log('');
+    }
+    // Routes section
+    if (routes.length > 0) {
+        console.log('── Routes / Endpoints ──');
+        for (const r of routes) {
+            const purpose = r.purpose ? ` — ${r.purpose}` : '';
+            const file = r.filePath.split(/[/\\]/).slice(-1)[0];
+            console.log(`  ${r.method.toUpperCase().padEnd(7)} ${r.path}  [${file}:${r.start_line}]${purpose}`);
+        }
+        console.log('');
+    }
+    // Types section
+    if (types.length > 0) {
+        console.log('── Types & Interfaces ──');
+        for (const t of types) {
+            const purpose = t.purpose ? ` — ${t.purpose}` : '';
+            const exported = t.is_exported ? '(exported) ' : '';
+            const file = t.filePath.split(/[/\\]/).slice(-1)[0];
+            console.log(`  ${t.kind.padEnd(12)} ${t.name} ${exported}[${file}:${t.start_line}]${purpose}`);
+        }
+        console.log('');
+    }
+    // Functions section
+    if (functions.length > 0) {
+        console.log('── Functions ──');
+        for (const fn of functions) {
+            const purpose = fn.purpose ? ` — ${fn.purpose}` : '';
+            const exported = fn.is_exported ? '(exported) ' : '';
+            const asyncStr = fn.is_async ? 'async ' : '';
+            const file = fn.filePath.split(/[/\\]/).slice(-1)[0];
+            console.log(`  ${asyncStr}${fn.name} ${exported}[${file}:${fn.start_line}]${purpose}`);
+        }
+        console.log('');
+    }
+    // Exported constants section
+    if (constants.length > 0) {
+        console.log('── Exported Constants ──');
+        for (const c of constants) {
+            const typeStr = c.type_annotation ? `: ${c.type_annotation}` : '';
+            const valStr = c.value_text ? ` = ${c.value_text.substring(0, 60)}${c.value_text.length > 60 ? '...' : ''}` : '';
+            const file = c.filePath.split(/[/\\]/).slice(-1)[0];
+            console.log(`  ${c.name}${typeStr}${valStr}  [${file}:${c.start_line}]`);
+        }
+        console.log('');
+    }
+    if (stats.totalFunctions === 0 && stats.totalTypes === 0 && stats.totalRoutes === 0) {
+        console.log('Knowledge graph is empty. Run "structx setup ." to populate it.');
+    }
+});
 // ── doctor ──
 program
     .command('doctor')
@@ -430,112 +481,11 @@ program
     }
     const config = (0, config_1.loadConfig)(structxDir);
     const db = (0, connection_1.openDatabase)(dbPath);
-    const project = (0, parser_1.createProject)(resolved);
     console.log(`Scanning ${resolved} for TypeScript files...`);
-    const files = (0, scanner_1.scanDirectory)(resolved);
-    console.log(`Found ${files.length} TypeScript files.`);
-    let newFiles = 0;
-    let changedFiles = 0;
-    let unchangedFiles = 0;
-    let totalFunctions = 0;
-    let totalRelationships = 0;
-    let queued = 0;
-    for (const filePath of files) {
-        const relativePath = path.relative(resolved, filePath);
-        const content = fs.readFileSync(filePath, 'utf-8');
-        const contentHash = (0, parser_1.hashFileContent)(content);
-        // Check if file changed
-        const existingFile = (0, queries_1.getFileByPath)(db, relativePath);
-        if (existingFile && existingFile.content_hash === contentHash) {
-            unchangedFiles++;
-            continue;
-        }
-        const isNew = !existingFile;
-        if (isNew)
-            newFiles++;
-        else
-            changedFiles++;
-        // Upsert file record
-        const fileId = (0, queries_1.upsertFile)(db, relativePath, contentHash);
-        // Get old functions for diff comparison
-        const oldFunctions = isNew ? [] : (0, queries_1.getFunctionsByFileId)(db, fileId);
-        const oldFunctionMap = new Map(oldFunctions.map(f => [f.name, f]));
-        // Clear old data for this file
-        if (!isNew) {
-            // Delete relationships for all old functions in this file
-            for (const oldFn of oldFunctions) {
-                (0, queries_1.deleteRelationshipsByCallerFunctionId)(db, oldFn.id);
-            }
-            (0, queries_1.deleteFunctionsByFileId)(db, fileId);
-        }
-        // Parse functions
-        let functions;
-        try {
-            functions = (0, parser_1.parseFile)(project, filePath);
-        }
-        catch (err) {
-            logger_1.logger.warn(`Failed to parse ${relativePath}: ${err.message}`);
-            continue;
-        }
-        // Insert functions and check for re-analysis needs
-        const functionIdMap = new Map();
-        for (const fn of functions) {
-            const fnId = (0, queries_1.insertFunction)(db, {
-                file_id: fileId,
-                name: fn.name,
-                signature: fn.signature,
-                body: fn.body,
-                code_hash: fn.codeHash,
-                start_line: fn.startLine,
-                end_line: fn.endLine,
-                is_exported: fn.isExported,
-                is_async: fn.isAsync,
-            });
-            functionIdMap.set(fn.name, fnId);
-            totalFunctions++;
-            // Determine if we need semantic re-analysis
-            const oldFn = oldFunctionMap.get(fn.name);
-            if (!oldFn) {
-                // New function — queue for analysis
-                (0, queries_1.enqueueForAnalysis)(db, fnId, 'new', (0, differ_1.getPriority)('new', fn.isExported));
-                queued++;
-            }
-            else {
-                const { reanalyze, reason } = (0, differ_1.shouldReanalyze)(oldFn, fn.signature, fn.codeHash, fn.body, config.diffThreshold);
-                if (reanalyze) {
-                    (0, queries_1.enqueueForAnalysis)(db, fnId, reason, (0, differ_1.getPriority)(reason, fn.isExported));
-                    queued++;
-                }
-            }
-        }
-        // Extract and insert relationships
-        try {
-            const calls = (0, relationships_1.extractCallsFromFile)(project, filePath);
-            for (const call of calls) {
-                if (call.callerName === '__file__')
-                    continue; // Skip file-level imports for now
-                const callerId = functionIdMap.get(call.callerName);
-                if (!callerId)
-                    continue;
-                // Try to resolve callee to a function ID
-                const callee = (0, queries_1.getFunctionByName)(db, call.calleeName);
-                (0, queries_1.insertRelationship)(db, callerId, call.calleeName, call.relationType, callee?.id);
-                totalRelationships++;
-            }
-        }
-        catch (err) {
-            logger_1.logger.warn(`Failed to extract calls from ${relativePath}: ${err.message}`);
-        }
-    }
+    const ingestResult = (0, ingester_1.ingestDirectory)(db, resolved, config.diffThreshold);
+    (0, ingester_1.printIngestResult)(ingestResult);
     db.close();
-    console.log(`\nIngestion complete:`);
-    console.log(`  New files:       ${newFiles}`);
-    console.log(`  Changed files:   ${changedFiles}`);
-    console.log(`  Unchanged:       ${unchangedFiles}`);
-    console.log(`  Functions:       ${totalFunctions}`);
-    console.log(`  Relationships:   ${totalRelationships}`);
-    console.log(`  Queued:          ${queued} functions for semantic analysis`);
-    if (queued > 0) {
+    if (ingestResult.queued > 0) {
         console.log(`\nNext: run 'structx analyze' to enrich functions with semantic metadata.`);
     }
 });
@@ -545,6 +495,7 @@ program
     .description('Run LLM semantic analysis on extracted functions')
     .argument('[repo-path]', 'Path to TypeScript repository', '.')
     .option('--yes', 'Skip cost confirmation prompt')
+    .option('--api-key <key>', 'Anthropic API key (overrides ANTHROPIC_API_KEY env var)')
     .action(async (repoPath, opts) => {
     const resolved = path.resolve(repoPath);
     const structxDir = (0, config_1.getStructXDir)(resolved);
@@ -554,8 +505,11 @@ program
         return;
     }
     const config = (0, config_1.loadConfig)(structxDir);
+    if (opts.apiKey)
+        config.anthropicApiKey = opts.apiKey;
     if (!config.anthropicApiKey) {
-        console.log('Anthropic API key not set. Set ANTHROPIC_API_KEY env var or add to .structx/config.json');
+        console.log('ERROR: Anthropic API key not set.');
+        console.log('Fix: Set ANTHROPIC_API_KEY env var, pass --api-key <key>, or add to .structx/config.json');
         return;
     }
     const db = (0, connection_1.openDatabase)(dbPath);
@@ -604,11 +558,21 @@ program
         totalOutputTokens += batchResult.totalOutputTokens;
         totalCost += batchResult.totalCost;
     }
+    // Analyze types, routes, and file summaries
+    console.log('\n  Analyzing types, routes, and file summaries...');
+    const typeResult = await (0, analyzer_1.analyzeTypes)(db, config.analysisModel, config.anthropicApiKey);
+    const routeResult = await (0, analyzer_1.analyzeRoutes)(db, config.analysisModel, config.anthropicApiKey);
+    const fileResult = await (0, analyzer_1.analyzeFileSummaries)(db, config.analysisModel, config.anthropicApiKey);
+    totalAnalyzed += typeResult.analyzed + routeResult.analyzed + fileResult.analyzed;
+    totalFailed += typeResult.failed + routeResult.failed + fileResult.failed;
+    totalInputTokens += typeResult.totalInputTokens + routeResult.totalInputTokens + fileResult.totalInputTokens;
+    totalOutputTokens += typeResult.totalOutputTokens + routeResult.totalOutputTokens + fileResult.totalOutputTokens;
+    totalCost += typeResult.totalCost + routeResult.totalCost + fileResult.totalCost;
     // Rebuild FTS index
     (0, analyzer_1.rebuildSearchIndex)(db);
     db.close();
     console.log(`\nAnalysis complete:`);
-    console.log(`  Analyzed:       ${totalAnalyzed}`);
+    console.log(`  Analyzed:       ${totalAnalyzed} (incl. ${typeResult.analyzed} types, ${routeResult.analyzed} routes, ${fileResult.analyzed} files)`);
     console.log(`  From cache:     ${totalCached}`);
     console.log(`  Failed:         ${totalFailed}`);
     console.log(`  Input tokens:   ${totalInputTokens.toLocaleString()}`);
@@ -621,20 +585,88 @@ program
     .description('Ask a question about the codebase')
     .argument('<question>', 'The question to ask')
     .option('--repo <path>', 'Path to TypeScript repository', '.')
+    .option('--api-key <key>', 'Anthropic API key (overrides ANTHROPIC_API_KEY env var)')
     .action(async (question, opts) => {
     const resolved = path.resolve(opts.repo);
     const structxDir = (0, config_1.getStructXDir)(resolved);
     const dbPath = (0, connection_1.getDbPath)(structxDir);
+    // Auto-setup: if DB doesn't exist, run full setup automatically
     if (!fs.existsSync(dbPath)) {
-        console.log('StructX not initialized. Run "structx init" first.');
-        return;
+        console.log('StructX not initialized. Running automatic setup...\n');
+        const db = (0, connection_1.initializeDatabase)(dbPath);
+        (0, config_1.saveConfig)(structxDir, { repoPath: resolved });
+        const config = (0, config_1.loadConfig)(structxDir);
+        if (opts.apiKey)
+            config.anthropicApiKey = opts.apiKey;
+        const result = (0, ingester_1.ingestDirectory)(db, resolved, config.diffThreshold);
+        (0, ingester_1.printIngestResult)(result);
+        // Run semantic analysis if API key available
+        if (config.anthropicApiKey) {
+            console.log('\nRunning semantic analysis...');
+            const pending = (0, queries_2.getPendingAnalysis)(db, config.batchSize);
+            if (pending.length > 0) {
+                let batchNum = 0;
+                while (true) {
+                    const items = (0, queries_2.getPendingAnalysis)(db, config.batchSize);
+                    if (items.length === 0)
+                        break;
+                    batchNum++;
+                    console.log(`  Batch ${batchNum}: ${items.length} functions...`);
+                    await (0, analyzer_1.analyzeBatch)(db, items.map(p => ({ id: p.id, function_id: p.function_id })), config.analysisModel, config.anthropicApiKey);
+                }
+                await (0, analyzer_1.analyzeTypes)(db, config.analysisModel, config.anthropicApiKey);
+                await (0, analyzer_1.analyzeRoutes)(db, config.analysisModel, config.anthropicApiKey);
+                await (0, analyzer_1.analyzeFileSummaries)(db, config.analysisModel, config.anthropicApiKey);
+                (0, analyzer_1.rebuildSearchIndex)(db);
+            }
+            console.log('Setup complete. Now answering your question...\n');
+        }
+        else {
+            console.log('\nWARNING: ANTHROPIC_API_KEY not set. Semantic analysis skipped.');
+            console.log('Results will be limited. Set the key and run "structx analyze . --yes" for better answers.\n');
+        }
+        db.close();
     }
     const config = (0, config_1.loadConfig)(structxDir);
+    if (opts.apiKey)
+        config.anthropicApiKey = opts.apiKey;
     if (!config.anthropicApiKey) {
-        console.log('Anthropic API key not set. Set ANTHROPIC_API_KEY env var or add to .structx/config.json');
+        console.log('ERROR: Anthropic API key not set.');
+        console.log('Fix one of:');
+        console.log('  1. Set ANTHROPIC_API_KEY environment variable');
+        console.log('  2. Pass --api-key <key> to this command');
+        console.log('  3. Add "anthropicApiKey" to .structx/config.json');
+        console.log('\nNote: "structx overview --repo ." works without an API key to see the codebase structure.');
         return;
     }
     const db = (0, connection_1.openDatabase)(dbPath);
+    // Check if DB is empty — suggest re-ingesting
+    const stats = (0, queries_1.getStats)(db);
+    if (stats.totalFunctions === 0 && stats.totalTypes === 0 && stats.totalRoutes === 0) {
+        console.log('WARNING: The knowledge graph is empty (0 functions, 0 types, 0 routes).');
+        console.log('Running automatic re-ingestion...\n');
+        const result = (0, ingester_1.ingestDirectory)(db, resolved, config.diffThreshold);
+        (0, ingester_1.printIngestResult)(result);
+        if (result.queued > 0) {
+            console.log('\nRunning semantic analysis...');
+            while (true) {
+                const items = (0, queries_2.getPendingAnalysis)(db, config.batchSize);
+                if (items.length === 0)
+                    break;
+                await (0, analyzer_1.analyzeBatch)(db, items.map(p => ({ id: p.id, function_id: p.function_id })), config.analysisModel, config.anthropicApiKey);
+            }
+            await (0, analyzer_1.analyzeTypes)(db, config.analysisModel, config.anthropicApiKey);
+            await (0, analyzer_1.analyzeRoutes)(db, config.analysisModel, config.anthropicApiKey);
+            await (0, analyzer_1.analyzeFileSummaries)(db, config.analysisModel, config.anthropicApiKey);
+            (0, analyzer_1.rebuildSearchIndex)(db);
+        }
+        console.log('');
+    }
+    // Warn if semantic analysis hasn't been done
+    if (stats.totalFunctions > 0 && stats.analyzedFunctions === 0) {
+        console.log('WARNING: No functions have been semantically analyzed. Results may be limited.');
+        console.log('Run "structx analyze . --yes" to enrich the knowledge graph.\n');
+    }
     const startTime = Date.now();
     // Step 1: Classify the question
     console.log('Classifying question...');
@@ -660,6 +692,21 @@ program
         case 'impact':
             retrieved = (0, retriever_1.impactAnalysis)(db, classification.functionName || '');
             break;
+        case 'route':
+            retrieved = (0, retriever_1.routeQuery)(db, classification.routePath, classification.routeMethod);
+            break;
+        case 'type':
+            retrieved = (0, retriever_1.typeQuery)(db, classification.typeName || classification.keywords.join(' '));
+            break;
+        case 'file':
+            retrieved = (0, retriever_1.fileQuery)(db, classification.filePath);
+            break;
+        case 'list':
+            retrieved = (0, retriever_1.listQuery)(db, classification.listEntity);
+            break;
+        case 'pattern':
+            retrieved = (0, retriever_1.patternQuery)(db, classification.keywords);
+            break;
         default:
             retrieved = (0, retriever_1.semanticSearch)(db, classification.keywords);
     }
@@ -670,10 +717,12 @@ program
     console.log('Generating answer...\n');
     const answerResult = await (0, answerer_1.generateAnswer)(question, context, config.answerModel, config.anthropicApiKey);
     // Display answer
+    const entityCount = retrieved.functions.length + retrieved.types.length +
+        retrieved.routes.length + retrieved.files.length + retrieved.constants.length;
     console.log('─'.repeat(60));
     console.log(answerResult.answer);
     console.log('─'.repeat(60));
-    console.log(`\nStrategy: ${classification.strategy} | Functions: ${retrieved.functions.length} | Graph query: ${graphQueryTimeMs}ms`);
+    console.log(`\nStrategy: ${classification.strategy} | Entities: ${entityCount} | Graph query: ${graphQueryTimeMs}ms`);
     console.log(`Tokens: ${answerResult.inputTokens} in / ${answerResult.outputTokens} out | Cost: $${answerResult.cost.toFixed(4)} | Time: ${answerResult.responseTimeMs}ms`);
     // Save run to DB
     (0, queries_2.insertQaRun)(db, {