@grafema/cli 0.1.1-alpha → 0.2.1-beta

package/dist/commands/get.js

@@ -16,6 +16,13 @@ export const getCommand = new Command('get')
     .argument('<semantic-id>', 'Semantic ID of the node (e.g., "file.js->scope->TYPE->name")')
     .option('-p, --project <path>', 'Project path', '.')
     .option('-j, --json', 'Output as JSON')
+    .addHelpText('after', `
+Examples:
+  grafema get "src/auth.js->authenticate->FUNCTION"      Get function node
+  grafema get "src/models/User.js->User->CLASS"          Get class node
+  grafema get "src/api.js->config->VARIABLE"             Get variable node
+  grafema get "src/auth.js->authenticate->FUNCTION" -j   Output as JSON with edges
+`)
     .action(async (semanticId, options) => {
     const projectPath = resolve(options.project);
     const grafemaDir = join(projectPath, '.grafema');
@@ -54,12 +61,12 @@ export const getCommand = new Command('get')
 async function outputJSON(backend, node, incomingEdges, outgoingEdges) {
     // Fetch target node names for all edges
     const incomingWithNames = await Promise.all(incomingEdges.map(async (edge) => ({
-        edgeType: edge.edgeType || edge.type || 'UNKNOWN',
+        edgeType: edge.type || 'UNKNOWN',
         targetId: edge.src,
         targetName: await getNodeName(backend, edge.src),
     })));
     const outgoingWithNames = await Promise.all(outgoingEdges.map(async (edge) => ({
-        edgeType: edge.edgeType || edge.type || 'UNKNOWN',
+        edgeType: edge.type || 'UNKNOWN',
         targetId: edge.dst,
         targetName: await getNodeName(backend, edge.dst),
     })));
@@ -93,6 +100,9 @@ async function outputText(backend, node, incomingEdges, outgoingEdges, projectPa
         name: node.name || '',
         file: node.file || '',
         line: node.line,
+        method: node.method,
+        path: node.path,
+        url: node.url,
     };
     // Display node details
     console.log(formatNodeDisplay(nodeInfo, { projectPath }));
@@ -124,7 +134,7 @@ async function displayEdges(backend, direction, edges, getTargetId) {
     // Group edges by type
     const byType = new Map();
     for (const edge of edges) {
-        const edgeType = edge.edgeType || edge.type || 'UNKNOWN';
+        const edgeType = edge.type || 'UNKNOWN';
         const targetId = getTargetId(edge);
         const targetName = await getNodeName(backend, targetId);
         if (!byType.has(edgeType)) {
@@ -173,11 +183,13 @@ async function getNodeName(backend, nodeId) {
     return '';
 }
 /**
- * Extract metadata fields (exclude standard fields)
+ * Extract metadata fields (exclude standard and display fields)
  */
 function getMetadataFields(node) {
     const standardFields = new Set([
         'id', 'type', 'nodeType', 'name', 'file', 'line',
+        // Display fields shown in primary line for HTTP nodes
+        'method', 'path', 'url',
     ]);
     const metadata = {};
     for (const [key, value] of Object.entries(node)) {

package/dist/commands/impact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"impact.d.ts","sourceRoot":"","sources":["../../src/commands/impact.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8BpC,eAAO,MAAM,aAAa,SAqDtB,CAAC"}
+{"version":3,"file":"impact.d.ts","sourceRoot":"","sources":["../../src/commands/impact.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8BpC,eAAO,MAAM,aAAa,SA6DtB,CAAC"}

package/dist/commands/impact.js

@@ -9,7 +9,7 @@ import { Command } from 'commander';
 import { resolve, join, dirname } from 'path';
 import { relative } from 'path';
 import { existsSync } from 'fs';
-import { RFDBServerBackend } from '@grafema/core';
+import { RFDBServerBackend, findContainingFunction as findContainingFunctionCore } from '@grafema/core';
 import { formatNodeDisplay, formatNodeInline } from '../utils/formatNode.js';
 import { exitWithError } from '../utils/errorFormatter.js';
 export const impactCommand = new Command('impact')
@@ -18,6 +18,14 @@ export const impactCommand = new Command('impact')
     .option('-p, --project <path>', 'Project path', '.')
     .option('-j, --json', 'Output as JSON')
     .option('-d, --depth <n>', 'Max traversal depth', '10')
+    .addHelpText('after', `
+Examples:
+  grafema impact "authenticate"          Analyze impact of changing authenticate
+  grafema impact "function login"        Impact of specific function
+  grafema impact "class UserService"     Impact of class changes
+  grafema impact "validate" -d 3         Limit analysis depth to 3 levels
+  grafema impact "auth" --json           Output impact analysis as JSON
+`)
     .action(async (pattern, options) => {
     const projectPath = resolve(options.project);
     const grafemaDir = join(projectPath, '.grafema');
@@ -107,10 +115,21 @@ async function analyzeImpact(backend, target, maxDepth, projectPath) {
     const affectedModules = new Map();
     const callChains = [];
     const visited = new Set();
+    // If target is a CLASS, aggregate callers from all methods
+    let targetIds;
+    if (target.type === 'CLASS') {
+        const methodIds = await getClassMethods(backend, target.id);
+        targetIds = [target.id, ...methodIds];
+    }
+    else {
+        targetIds = [target.id];
+    }
     // BFS to find all callers
-    const queue = [
-        { id: target.id, depth: 0, chain: [target.name] }
-    ];
+    const queue = targetIds.map(id => ({
+        id,
+        depth: 0,
+        chain: [target.name]
+    }));
     while (queue.length > 0) {
         const { id, depth, chain } = queue.shift();
         if (visited.has(id))
@@ -124,13 +143,17 @@ async function analyzeImpact(backend, target, maxDepth, projectPath) {
             const containingCalls = await findCallsToNode(backend, id);
             for (const callNode of containingCalls) {
                 // Find the function containing this call
-                const container = await findContainingFunction(backend, callNode.id);
+                const container = await findContainingFunctionCore(backend, callNode.id);
                 if (container && !visited.has(container.id)) {
+                    // Filter out internal callers (methods of the same class)
+                    if (target.type === 'CLASS' && targetIds.includes(container.id)) {
+                        continue;
+                    }
                     const caller = {
                         id: container.id,
                         type: container.type,
                         name: container.name,
-                        file: container.file,
+                        file: container.file || '',
                         line: container.line,
                     };
                     if (depth === 0) {
@@ -166,6 +189,25 @@ async function analyzeImpact(backend, target, maxDepth, projectPath) {
         callChains,
     };
 }
+/**
+ * Get method IDs for a class
+ */
+async function getClassMethods(backend, classId) {
+    const methods = [];
+    try {
+        const edges = await backend.getOutgoingEdges(classId, ['CONTAINS']);
+        for (const edge of edges) {
+            const node = await backend.getNode(edge.dst);
+            if (node && node.type === 'FUNCTION') {
+                methods.push(node.id);
+            }
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return methods;
+}
 /**
  * Find CALL nodes that reference a target
  */
@@ -192,50 +234,6 @@ async function findCallsToNode(backend, targetId) {
     }
     return calls;
 }
-/**
- * Find the function that contains a call node
- *
- * Path: CALL → CONTAINS → SCOPE → CONTAINS → SCOPE → HAS_SCOPE → FUNCTION
- */
-async function findContainingFunction(backend, nodeId, maxDepth = 15) {
-    const visited = new Set();
-    const queue = [{ id: nodeId, depth: 0 }];
-    while (queue.length > 0) {
-        const { id, depth } = queue.shift();
-        if (visited.has(id) || depth > maxDepth)
-            continue;
-        visited.add(id);
-        try {
-            // Get incoming edges: CONTAINS, HAS_SCOPE
-            const edges = await backend.getIncomingEdges(id, null);
-            for (const edge of edges) {
-                const edgeType = edge.edgeType || edge.type;
-                // Only follow structural edges
-                if (!['CONTAINS', 'HAS_SCOPE', 'DECLARES'].includes(edgeType))
-                    continue;
-                const parent = await backend.getNode(edge.src);
-                if (!parent || visited.has(parent.id))
-                    continue;
-                const parentType = parent.type;
-                // FUNCTION, CLASS, or MODULE (for top-level calls)
-                if (parentType === 'FUNCTION' || parentType === 'CLASS' || parentType === 'MODULE') {
-                    return {
-                        id: parent.id,
-                        type: parentType,
-                        name: parent.name || '',
-                        file: parent.file || '',
-                        line: parent.line,
-                    };
-                }
-                queue.push({ id: parent.id, depth: depth + 1 });
-            }
-        }
-        catch {
-            // Ignore
-        }
-    }
-    return null;
-}
 /**
  * Get module path relative to project
  */

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4CpC,eAAO,MAAM,WAAW,SA+DpB,CAAC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAyGpC,eAAO,MAAM,WAAW,SAyFpB,CAAC"}

package/dist/commands/init.js

@@ -4,9 +4,12 @@
 import { Command } from 'commander';
 import { resolve, join } from 'path';
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
-import { exitWithError } from '../utils/errorFormatter.js';
+import { spawn } from 'child_process';
+import { createInterface } from 'readline';
+import { fileURLToPath } from 'url';
 import { stringify as stringifyYAML } from 'yaml';
 import { DEFAULT_CONFIG } from '@grafema/core';
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
 /**
  * Generate config.yaml content with commented future features.
  * Only includes implemented features (plugins).
@@ -26,21 +29,79 @@ function generateConfigYAML() {
 # Documentation: https://github.com/grafema/grafema#configuration
 
 ${yaml}
-# Future: File discovery patterns (not yet implemented)
-# Grafema currently uses entrypoint-based discovery (follows imports from package.json main field)
-# Glob-based include/exclude patterns will be added in a future release
+# File filtering patterns (optional)
+# By default, Grafema follows imports from package.json entry points.
+# Use these patterns to control which files are analyzed:
 #
-# include:
+# include:  # Only analyze files matching these patterns
 #   - "src/**/*.{ts,js,tsx,jsx}"
-# exclude:
+#
+# exclude:  # Skip files matching these patterns (takes precedence over include)
 #   - "**/*.test.ts"
-#   - "node_modules/**"
+#   - "**/__tests__/**"
+#   - "**/node_modules/**"
 `;
 }
+/**
+ * Ask user a yes/no question. Returns true for yes (default), false for no.
+ */
+function askYesNo(question) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            // Default yes (empty answer or 'y' or 'yes')
+            const normalized = answer.toLowerCase().trim();
+            resolve(normalized !== 'n' && normalized !== 'no');
+        });
+    });
+}
+/**
+ * Run grafema analyze in the given project path.
+ * Returns the exit code of the analyze process.
+ */
+function runAnalyze(projectPath) {
+    return new Promise((resolve) => {
+        const cliPath = join(__dirname, '..', 'cli.js');
+        const child = spawn('node', [cliPath, 'analyze', projectPath], {
+            stdio: 'inherit', // Pass through all I/O for user to see progress
+        });
+        child.on('close', (code) => resolve(code ?? 1));
+        child.on('error', () => resolve(1));
+    });
+}
+/**
+ * Print next steps after init.
+ */
+function printNextSteps() {
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. Review config:  code .grafema/config.yaml');
+    console.log('  2. Build graph:    grafema analyze');
+    console.log('  3. Explore:        grafema overview');
+}
+/**
+ * Check if running in interactive mode.
+ * Interactive if stdin is TTY and --yes flag not provided.
+ */
+function isInteractive(options) {
+    return options.yes !== true && process.stdin.isTTY === true;
+}
 export const initCommand = new Command('init')
     .description('Initialize Grafema in current project')
     .argument('[path]', 'Project path', '.')
     .option('-f, --force', 'Overwrite existing config')
+    .option('-y, --yes', 'Skip prompts (non-interactive mode)')
+    .addHelpText('after', `
+Examples:
+  grafema init                   Initialize in current directory
+  grafema init ./my-project      Initialize in specific directory
+  grafema init --force           Overwrite existing configuration
+  grafema init --yes             Skip prompts, auto-run analyze
+`)
     .action(async (path, options) => {
     const projectPath = resolve(path);
     const grafemaDir = join(projectPath, '.grafema');
@@ -49,10 +110,15 @@ export const initCommand = new Command('init')
     const tsconfigPath = join(projectPath, 'tsconfig.json');
     // Check package.json
     if (!existsSync(packageJsonPath)) {
-        exitWithError('No package.json found', [
-            'Initialize a project: npm init',
-            'Or check you are in the right directory'
-        ]);
+        console.error('✗ Grafema currently supports JavaScript/TypeScript projects only.');
+        console.error(`  No package.json found in ${projectPath}`);
+        console.error('');
+        console.error('  Supported: Node.js, React, Express, Next.js, Vue, Angular, etc.');
+        console.error('  Coming soon: Python, Go, Rust');
+        console.error('');
+        console.error('  If this IS a JS/TS project, create package.json first:');
+        console.error('    npm init -y');
+        process.exit(1);
     }
     console.log('✓ Found package.json');
     // Detect TypeScript
@@ -68,8 +134,7 @@ export const initCommand = new Command('init')
         console.log('');
         console.log('✓ Grafema already initialized');
         console.log('  → Use --force to overwrite config');
-        console.log('');
-        console.log('Next: Run "grafema analyze" to build the code graph');
+        printNextSteps();
         return;
     }
     // Create .grafema directory
@@ -89,6 +154,19 @@ export const initCommand = new Command('init')
             console.log('✓ Updated .gitignore');
         }
     }
-    console.log('');
-    console.log('Next: Run "grafema analyze" to build the code graph');
+    printNextSteps();
+    // Prompt to run analyze in interactive mode
+    if (isInteractive(options)) {
+        console.log('');
+        const runNow = await askYesNo('Run analysis now? [Y/n] ');
+        if (runNow) {
+            console.log('');
+            console.log('Starting analysis...');
+            console.log('');
+            const exitCode = await runAnalyze(projectPath);
+            if (exitCode !== 0) {
+                process.exit(exitCode);
+            }
+        }
+    }
 });

package/dist/commands/ls.d.ts

@@ -0,0 +1,14 @@
+/**
+ * List command - List nodes by type
+ *
+ * Unix-style listing of nodes in the graph. Similar to `ls` for files,
+ * but for code graph nodes.
+ *
+ * Use cases:
+ * - "Show me all HTTP routes in this project"
+ * - "List all functions" (with limit for large codebases)
+ * - "What Socket.IO events are defined?"
+ */
+import { Command } from 'commander';
+export declare const lsCommand: Command;
+//# sourceMappingURL=ls.d.ts.map

package/dist/commands/ls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ls.d.ts","sourceRoot":"","sources":["../../src/commands/ls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0BpC,eAAO,MAAM,SAAS,SA2FlB,CAAC"}

package/dist/commands/ls.js

@@ -0,0 +1,132 @@
+/**
+ * List command - List nodes by type
+ *
+ * Unix-style listing of nodes in the graph. Similar to `ls` for files,
+ * but for code graph nodes.
+ *
+ * Use cases:
+ * - "Show me all HTTP routes in this project"
+ * - "List all functions" (with limit for large codebases)
+ * - "What Socket.IO events are defined?"
+ */
+import { Command } from 'commander';
+import { resolve, join, relative } from 'path';
+import { existsSync } from 'fs';
+import { RFDBServerBackend } from '@grafema/core';
+import { exitWithError } from '../utils/errorFormatter.js';
+export const lsCommand = new Command('ls')
+    .description('List nodes by type')
+    .requiredOption('-t, --type <nodeType>', 'Node type to list (required)')
+    .option('-p, --project <path>', 'Project path', '.')
+    .option('-j, --json', 'Output as JSON')
+    .option('-l, --limit <n>', 'Limit results (default: 50)', '50')
+    .addHelpText('after', `
+Examples:
+  grafema ls --type FUNCTION              List functions (up to 50)
+  grafema ls --type http:route            List all HTTP routes
+  grafema ls --type http:request          List all HTTP requests (fetch/axios)
+  grafema ls -t socketio:event            List Socket.IO events
+  grafema ls --type CLASS -l 100          List up to 100 classes
+  grafema ls --type jsx:component --json  Output as JSON
+
+Discover available types:
+  grafema types                           List all types with counts
+`)
+    .action(async (options) => {
+    const projectPath = resolve(options.project);
+    const grafemaDir = join(projectPath, '.grafema');
+    const dbPath = join(grafemaDir, 'graph.rfdb');
+    if (!existsSync(dbPath)) {
+        exitWithError('No graph database found', ['Run: grafema analyze']);
+    }
+    const backend = new RFDBServerBackend({ dbPath });
+    await backend.connect();
+    try {
+        const limit = parseInt(options.limit, 10);
+        const nodeType = options.type;
+        // Check if type exists in graph
+        const typeCounts = await backend.countNodesByType();
+        if (!typeCounts[nodeType]) {
+            const availableTypes = Object.keys(typeCounts).sort();
+            exitWithError(`No nodes of type "${nodeType}" found`, [
+                'Available types:',
+                ...availableTypes.slice(0, 10).map(t => `  ${t}`),
+                availableTypes.length > 10 ? `  ... and ${availableTypes.length - 10} more` : '',
+                '',
+                'Run: grafema types    to see all types with counts',
+            ].filter(Boolean));
+        }
+        // Collect nodes
+        const nodes = [];
+        for await (const node of backend.queryNodes({ nodeType: nodeType })) {
+            nodes.push({
+                id: node.id,
+                type: node.type || nodeType,
+                name: node.name || '',
+                file: node.file || '',
+                line: node.line,
+                method: node.method,
+                path: node.path,
+                url: node.url,
+                event: node.event,
+            });
+            if (nodes.length >= limit)
+                break;
+        }
+        const totalCount = typeCounts[nodeType];
+        const showing = nodes.length;
+        if (options.json) {
+            console.log(JSON.stringify({
+                type: nodeType,
+                nodes,
+                showing,
+                total: totalCount,
+            }, null, 2));
+        }
+        else {
+            console.log(`[${nodeType}] (${showing}${showing < totalCount ? ` of ${totalCount}` : ''}):`);
+            console.log('');
+            for (const node of nodes) {
+                const display = formatNodeForList(node, nodeType, projectPath);
+                console.log(`  ${display}`);
+            }
+            if (showing < totalCount) {
+                console.log('');
+                console.log(`  ... ${totalCount - showing} more. Use --limit ${totalCount} to see all.`);
+            }
+        }
+    }
+    finally {
+        await backend.close();
+    }
+});
+/**
+ * Format a node for list display based on its type.
+ * Different types show different fields.
+ */
+function formatNodeForList(node, nodeType, projectPath) {
+    const relFile = node.file ? relative(projectPath, node.file) : '';
+    const loc = node.line ? `${relFile}:${node.line}` : relFile;
+    // HTTP routes: METHOD PATH (location)
+    if (nodeType === 'http:route' && node.method && node.path) {
+        return `${node.method.padEnd(6)} ${node.path}  (${loc})`;
+    }
+    // HTTP requests: METHOD URL (location)
+    if (nodeType === 'http:request') {
+        const method = (node.method || 'GET').padEnd(6);
+        const url = node.url || 'dynamic';
+        return `${method} ${url}  (${loc})`;
+    }
+    // Socket.IO events: event_name
+    if (nodeType === 'socketio:event') {
+        return node.name || node.id;
+    }
+    // Socket.IO emit/on: event (location)
+    if (nodeType === 'socketio:emit' || nodeType === 'socketio:on') {
+        const event = node.event || node.name || 'unknown';
+        return `${event}  (${loc})`;
+    }
+    // Default: name (location)
+    const name = node.name || node.id;
+    return loc ? `${name}  (${loc})` : name;
+}

package/dist/commands/overview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overview.d.ts","sourceRoot":"","sources":["../../src/commands/overview.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,eAAO,MAAM,eAAe,SA4FxB,CAAC"}
+{"version":3,"file":"overview.d.ts","sourceRoot":"","sources":["../../src/commands/overview.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,eAAO,MAAM,eAAe,SAyGxB,CAAC"}

package/dist/commands/overview.js

@@ -10,6 +10,12 @@ export const overviewCommand = new Command('overview')
     .description('Show project overview and statistics')
     .option('-p, --project <path>', 'Project path', '.')
     .option('-j, --json', 'Output as JSON')
+    .addHelpText('after', `
+Examples:
+  grafema overview               Show project dashboard
+  grafema overview --json        Output statistics as JSON
+  grafema overview -p ./app      Overview for specific project
+`)
     .action(async (options) => {
     const projectPath = resolve(options.project);
     const grafemaDir = join(projectPath, '.grafema');
@@ -46,6 +52,7 @@ export const overviewCommand = new Command('overview')
         console.log('External Interactions:');
         const httpRoutes = stats.nodesByType['http:route'] || 0;
         const dbQueries = stats.nodesByType['db:query'] || 0;
+        const socketEvents = stats.nodesByType['socketio:event'] || 0;
         const socketEmit = stats.nodesByType['socketio:emit'] || 0;
         const socketOn = stats.nodesByType['socketio:on'] || 0;
         const events = stats.nodesByType['event:listener'] || 0;
@@ -53,15 +60,21 @@ export const overviewCommand = new Command('overview')
             console.log(`├─ HTTP routes: ${httpRoutes}`);
         if (dbQueries > 0)
             console.log(`├─ Database queries: ${dbQueries}`);
-        if (socketEmit + socketOn > 0)
+        if (socketEvents > 0) {
+            // New format showing event count prominently
+            console.log(`├─ Socket.IO: ${socketEvents} events (${socketEmit} emit, ${socketOn} listeners)`);
+        }
+        else if (socketEmit + socketOn > 0) {
+            // Fallback for graphs analyzed before REG-209
             console.log(`├─ Socket.IO: ${socketEmit} emit, ${socketOn} listeners`);
+        }
         if (events > 0)
             console.log(`├─ Event listeners: ${events}`);
         // Check for external module refs
         const externalModules = stats.nodesByType['EXTERNAL_MODULE'] || 0;
         if (externalModules > 0)
             console.log(`└─ External modules: ${externalModules}`);
-        if (httpRoutes + dbQueries + socketEmit + socketOn + events + externalModules === 0) {
+        if (httpRoutes + dbQueries + socketEvents + socketEmit + socketOn + events + externalModules === 0) {
             console.log('└─ (none detected)');
         }
         console.log('');

package/dist/commands/query.d.ts

@@ -9,5 +9,103 @@
  * For raw Datalog queries, use --raw flag
  */
 import { Command } from 'commander';
+/**
+ * Parsed query with optional scope constraints.
+ *
+ * Supports patterns like:
+ *   "response" -> { name: "response" }
+ *   "variable response" -> { type: "VARIABLE", name: "response" }
+ *   "response in fetchData" -> { name: "response", scopes: ["fetchData"] }
+ *   "response in src/app.ts" -> { name: "response", file: "src/app.ts" }
+ *   "response in catch in fetchData" -> { name: "response", scopes: ["fetchData", "catch"] }
+ */
+export interface ParsedQuery {
+    /** Node type (e.g., "FUNCTION", "VARIABLE") or null for any */
+    type: string | null;
+    /** Node name to search (partial match) */
+    name: string;
+    /** File scope - filter to nodes in this file */
+    file: string | null;
+    /** Scope chain - filter to nodes inside these scopes (function/class/block names) */
+    scopes: string[];
+}
 export declare const queryCommand: Command;
+/**
+ * Parse search pattern with scope support.
+ *
+ * Grammar:
+ *   query := [type] name [" in " scope]*
+ *   type  := "function" | "class" | "variable" | etc.
+ *   scope := <filename> | <functionName>
+ *
+ * File scope detection: contains "/" or ends with .ts/.js/.tsx/.jsx
+ * Function scope detection: anything else
+ *
+ * IMPORTANT: Only split on " in " (space-padded) to avoid matching names like "signin"
+ *
+ * Examples:
+ *   "response" -> { type: null, name: "response", file: null, scopes: [] }
+ *   "variable response in fetchData" -> { type: "VARIABLE", name: "response", file: null, scopes: ["fetchData"] }
+ *   "response in src/app.ts" -> { type: null, name: "response", file: "src/app.ts", scopes: [] }
+ *   "error in catch in fetchData in src/app.ts" -> { type: null, name: "error", file: "src/app.ts", scopes: ["fetchData", "catch"] }
+ */
+export declare function parseQuery(pattern: string): ParsedQuery;
+/**
+ * Detect if a scope string looks like a file path.
+ *
+ * Heuristics:
+ * - Contains "/" -> file path
+ * - Ends with .ts, .js, .tsx, .jsx, .mjs, .cjs -> file path
+ *
+ * Examples:
+ *   "src/app.ts" -> true
+ *   "app.js" -> true
+ *   "fetchData" -> false
+ *   "UserService" -> false
+ *   "catch" -> false
+ */
+export declare function isFileScope(scope: string): boolean;
+/**
+ * Check if a semantic ID matches the given scope constraints.
+ *
+ * Uses parseSemanticId from @grafema/core for robust ID parsing.
+ *
+ * Scope matching rules:
+ * - File scope: semantic ID must match the file path (full or basename)
+ * - Function/class scope: semantic ID must contain the scope in its scopePath
+ * - Multiple scopes: ALL must match (AND logic)
+ * - Scope order: independent - all scopes just need to be present
+ *
+ * Examples:
+ *   ID: "src/app.ts->fetchData->try#0->VARIABLE->response"
+ *   Matches: scopes=["fetchData"] -> true
+ *   Matches: scopes=["try"] -> true (matches "try#0")
+ *   Matches: scopes=["fetchData", "try"] -> true (both present)
+ *   Matches: scopes=["processData"] -> false (not in ID)
+ *
+ * @param semanticId - The full semantic ID to check
+ * @param file - File scope (null for any file)
+ * @param scopes - Array of scope names to match
+ * @returns true if ID matches all constraints
+ */
+export declare function matchesScope(semanticId: string, file: string | null, scopes: string[]): boolean;
+/**
+ * Extract human-readable scope context from a semantic ID.
+ *
+ * Parses the ID and returns a description of the scope chain.
+ *
+ * Examples:
+ *   "src/app.ts->fetchData->try#0->VARIABLE->response"
+ *   -> "inside fetchData, inside try block"
+ *
+ *   "src/app.ts->UserService->login->VARIABLE->token"
+ *   -> "inside UserService, inside login"
+ *
+ *   "src/app.ts->global->FUNCTION->main"
+ *   -> null (no interesting scope)
+ *
+ * @param semanticId - The semantic ID to parse
+ * @returns Human-readable scope context or null
+ */
+export declare function extractScopeContext(semanticId: string): string | null;
 //# sourceMappingURL=query.d.ts.map