@grafema/cli 0.1.1-alpha → 0.2.1-beta

package/dist/commands/trace.js

@@ -4,19 +4,32 @@
  * Usage:
  *   grafema trace "userId from authenticate"
  *   grafema trace "config"
+ *   grafema trace --to "addNode#0.type"  (sink-based trace)
  */
 import { Command } from 'commander';
 import { resolve, join } from 'path';
 import { existsSync } from 'fs';
-import { RFDBServerBackend, parseSemanticId } from '@grafema/core';
+import { RFDBServerBackend, parseSemanticId, traceValues } from '@grafema/core';
 import { formatNodeDisplay, formatNodeInline } from '../utils/formatNode.js';
 import { exitWithError } from '../utils/errorFormatter.js';
 export const traceCommand = new Command('trace')
-    .description('Trace data flow for a variable')
-    .argument('<pattern>', 'Pattern: "varName from functionName" or just "varName"')
+    .description('Trace data flow for a variable or to a sink point')
+    .argument('[pattern]', 'Pattern: "varName from functionName" or just "varName"')
     .option('-p, --project <path>', 'Project path', '.')
     .option('-j, --json', 'Output as JSON')
     .option('-d, --depth <n>', 'Max trace depth', '10')
+    .option('-t, --to <sink>', 'Sink point: "fn#argIndex.property" (e.g., "addNode#0.type")')
+    .option('-r, --from-route <pattern>', 'Trace from route response (e.g., "GET /status" or "/status")')
+    .addHelpText('after', `
+Examples:
+  grafema trace "userId"                     Trace all variables named "userId"
+  grafema trace "userId from authenticate"   Trace userId within authenticate function
+  grafema trace "config" --depth 5           Limit trace depth to 5 levels
+  grafema trace "apiKey" --json              Output trace as JSON
+  grafema trace --to "addNode#0.type"        Trace values reaching sink point
+  grafema trace --from-route "GET /status"   Trace values from route response
+  grafema trace -r "/status"                 Trace by path only
+`)
     .action(async (pattern, options) => {
     const projectPath = resolve(options.project);
     const grafemaDir = join(projectPath, '.grafema');
@@ -27,6 +40,21 @@ export const traceCommand = new Command('trace')
     const backend = new RFDBServerBackend({ dbPath });
     await backend.connect();
     try {
+        // Handle sink-based trace if --to option is provided
+        if (options.to) {
+            await handleSinkTrace(backend, options.to, projectPath, options.json);
+            return;
+        }
+        // Handle route-based trace if --from-route option is provided
+        if (options.fromRoute) {
+            const maxDepth = parseInt(options.depth, 10);
+            await handleRouteTrace(backend, options.fromRoute, projectPath, options.json, maxDepth);
+            return;
+        }
+        // Regular trace requires pattern
+        if (!pattern) {
+            exitWithError('Pattern required', ['Provide a pattern, use --to for sink trace, or --from-route for route trace']);
+        }
         // Parse pattern: "varName from functionName" or just "varName"
         const { varName, scopeName } = parseTracePattern(pattern);
         const maxDepth = parseInt(options.depth, 10);
@@ -141,6 +169,7 @@ async function findVariables(backend, varName, scopeName) {
 async function traceBackward(backend, startId, maxDepth) {
     const trace = [];
     const visited = new Set();
+    const seenNodes = new Set();
     const queue = [{ id: startId, depth: 0 }];
     while (queue.length > 0) {
         const { id, depth } = queue.shift();
@@ -153,6 +182,9 @@ async function traceBackward(backend, startId, maxDepth) {
                 const targetNode = await backend.getNode(edge.dst);
                 if (!targetNode)
                     continue;
+                if (seenNodes.has(targetNode.id))
+                    continue;
+                seenNodes.add(targetNode.id);
                 const nodeInfo = {
                     id: targetNode.id,
                     type: targetNode.type || 'UNKNOWN',
@@ -163,7 +195,7 @@ async function traceBackward(backend, startId, maxDepth) {
                 };
                 trace.push({
                     node: nodeInfo,
-                    edgeType: edge.edgeType || edge.type,
+                    edgeType: edge.type,
                     depth: depth + 1,
                 });
                 // Continue tracing unless we hit a leaf
@@ -185,6 +217,7 @@ async function traceBackward(backend, startId, maxDepth) {
 async function traceForward(backend, startId, maxDepth) {
     const trace = [];
     const visited = new Set();
+    const seenNodes = new Set();
     const queue = [{ id: startId, depth: 0 }];
     while (queue.length > 0) {
         const { id, depth } = queue.shift();
@@ -198,6 +231,9 @@ async function traceForward(backend, startId, maxDepth) {
                 const sourceNode = await backend.getNode(edge.src);
                 if (!sourceNode)
                     continue;
+                if (seenNodes.has(sourceNode.id))
+                    continue;
+                seenNodes.add(sourceNode.id);
                 const nodeInfo = {
                     id: sourceNode.id,
                     type: sourceNode.type || 'UNKNOWN',
@@ -207,7 +243,7 @@ async function traceForward(backend, startId, maxDepth) {
                 };
                 trace.push({
                     node: nodeInfo,
-                    edgeType: edge.edgeType || edge.type,
+                    edgeType: edge.type,
                     depth: depth + 1,
                 });
                 // Continue forward
@@ -268,3 +304,462 @@ function displayTrace(trace, _projectPath, indent) {
         }
     }
 }
+// =============================================================================
+// SINK-BASED TRACE IMPLEMENTATION (REG-230)
+// =============================================================================
+/**
+ * Parse sink specification string into structured format
+ *
+ * Format: "functionName#argIndex.property.path"
+ * Examples:
+ *   - "addNode#0.type" -> {functionName: "addNode", argIndex: 0, propertyPath: ["type"]}
+ *   - "fn#0" -> {functionName: "fn", argIndex: 0, propertyPath: []}
+ *   - "add_node_v2#1.config.options" -> {functionName: "add_node_v2", argIndex: 1, propertyPath: ["config", "options"]}
+ *
+ * @throws Error if spec is invalid
+ */
+export function parseSinkSpec(spec) {
+    if (!spec || spec.trim() === '') {
+        throw new Error('Invalid sink spec: empty string');
+    }
+    const trimmed = spec.trim();
+    // Must contain # separator
+    const hashIndex = trimmed.indexOf('#');
+    if (hashIndex === -1) {
+        throw new Error('Invalid sink spec: missing # separator');
+    }
+    // Extract function name (before #)
+    const functionName = trimmed.substring(0, hashIndex);
+    if (!functionName || !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(functionName)) {
+        throw new Error('Invalid sink spec: invalid function name');
+    }
+    // Extract argument index and optional property path (after #)
+    const afterHash = trimmed.substring(hashIndex + 1);
+    if (!afterHash) {
+        throw new Error('Invalid sink spec: missing argument index');
+    }
+    // Split by first dot to separate argIndex from property path
+    const dotIndex = afterHash.indexOf('.');
+    const argIndexStr = dotIndex === -1 ? afterHash : afterHash.substring(0, dotIndex);
+    const propertyPathStr = dotIndex === -1 ? '' : afterHash.substring(dotIndex + 1);
+    // Parse argument index
+    if (!/^\d+$/.test(argIndexStr)) {
+        throw new Error('Invalid sink spec: argument index must be numeric');
+    }
+    const argIndex = parseInt(argIndexStr, 10);
+    if (argIndex < 0) {
+        throw new Error('Invalid sink spec: negative argument index');
+    }
+    // Parse property path (split by dots)
+    const propertyPath = propertyPathStr ? propertyPathStr.split('.').filter(p => p) : [];
+    return {
+        functionName,
+        argIndex,
+        propertyPath,
+        raw: trimmed,
+    };
+}
+/**
+ * Find all call sites for a function by name
+ *
+ * Handles both:
+ * - Direct calls: fn() where name === targetFunctionName
+ * - Method calls: obj.fn() where method attribute === targetFunctionName
+ */
+export async function findCallSites(backend, targetFunctionName) {
+    const callSites = [];
+    for await (const node of backend.queryNodes({ nodeType: 'CALL' })) {
+        const nodeName = node.name || '';
+        const nodeMethod = node.method || '';
+        // Match direct calls (name === targetFunctionName)
+        // Or method calls (method === targetFunctionName)
+        if (nodeName === targetFunctionName || nodeMethod === targetFunctionName) {
+            callSites.push({
+                id: node.id,
+                calleeFunction: targetFunctionName,
+                file: node.file || '',
+                line: node.line || 0,
+            });
+        }
+    }
+    return callSites;
+}
+/**
+ * Extract the argument node ID at a specific index from a call site
+ *
+ * Follows PASSES_ARGUMENT edges and matches by argIndex metadata
+ *
+ * @returns Node ID of the argument, or null if not found
+ */
+export async function extractArgument(backend, callSiteId, argIndex) {
+    const edges = await backend.getOutgoingEdges(callSiteId, ['PASSES_ARGUMENT']);
+    for (const edge of edges) {
+        // argIndex is stored in edge metadata
+        const edgeArgIndex = edge.metadata?.argIndex;
+        if (edgeArgIndex === argIndex) {
+            return edge.dst;
+        }
+    }
+    return null;
+}
+/**
+ * Extract a property from a node by following HAS_PROPERTY edges
+ *
+ * If node is a VARIABLE, first traces through ASSIGNED_FROM to find OBJECT_LITERAL
+ *
+ * @returns Node ID of the property value, or null if not found
+ */
+async function extractProperty(backend, nodeId, propertyName) {
+    const node = await backend.getNode(nodeId);
+    if (!node)
+        return null;
+    const nodeType = node.type || node.nodeType;
+    // If it's an OBJECT_LITERAL, follow HAS_PROPERTY directly
+    if (nodeType === 'OBJECT_LITERAL') {
+        const edges = await backend.getOutgoingEdges(nodeId, ['HAS_PROPERTY']);
+        for (const edge of edges) {
+            if (edge.metadata?.propertyName === propertyName) {
+                return edge.dst;
+            }
+        }
+        return null;
+    }
+    // If it's a VARIABLE, first trace to the object literal
+    if (nodeType === 'VARIABLE' || nodeType === 'CONSTANT') {
+        const assignedEdges = await backend.getOutgoingEdges(nodeId, ['ASSIGNED_FROM']);
+        for (const edge of assignedEdges) {
+            const result = await extractProperty(backend, edge.dst, propertyName);
+            if (result)
+                return result;
+        }
+    }
+    return null;
+}
+/**
+ * Trace a node to its literal values.
+ * Uses shared traceValues utility from @grafema/core (REG-244).
+ *
+ * @param backend - RFDBServerBackend for graph queries
+ * @param nodeId - Starting node ID
+ * @param _visited - Kept for API compatibility (internal cycle detection in shared utility)
+ * @param maxDepth - Maximum traversal depth
+ * @returns Array of traced values with sources
+ */
+async function traceToLiterals(backend, nodeId, _visited = new Set(), maxDepth = 10) {
+    // RFDBServerBackend implements TraceValuesGraphBackend interface
+    const traced = await traceValues(backend, nodeId, {
+        maxDepth,
+        followDerivesFrom: true,
+        detectNondeterministic: true,
+    });
+    // Map to expected format (strip reason field)
+    return traced.map(t => ({
+        value: t.value,
+        source: t.source,
+        isUnknown: t.isUnknown,
+    }));
+}
+/**
+ * Resolve a sink specification to all possible values
+ *
+ * This is the main entry point for sink-based trace.
+ * It finds all call sites, extracts the specified argument,
+ * optionally follows property path, and traces to literal values.
+ */
+export async function resolveSink(backend, sink) {
+    // Find all call sites for the function
+    const callSites = await findCallSites(backend, sink.functionName);
+    const resolvedCallSites = [];
+    const valueMap = new Map();
+    let hasUnknown = false;
+    let totalSources = 0;
+    for (const callSite of callSites) {
+        resolvedCallSites.push(callSite);
+        // Extract the argument at the specified index
+        const argNodeId = await extractArgument(backend, callSite.id, sink.argIndex);
+        if (!argNodeId) {
+            // Argument doesn't exist at this call site
+            continue;
+        }
+        // If property path specified, navigate to that property
+        let targetNodeId = argNodeId;
+        for (const propName of sink.propertyPath) {
+            const propNodeId = await extractProperty(backend, targetNodeId, propName);
+            if (!propNodeId) {
+                // Property not found, mark as unknown
+                hasUnknown = true;
+                targetNodeId = '';
+                break;
+            }
+            targetNodeId = propNodeId;
+        }
+        if (!targetNodeId)
+            continue;
+        // Trace to literal values
+        const literals = await traceToLiterals(backend, targetNodeId);
+        for (const lit of literals) {
+            if (lit.isUnknown) {
+                hasUnknown = true;
+                continue;
+            }
+            totalSources++;
+            const valueKey = JSON.stringify(lit.value);
+            if (valueMap.has(valueKey)) {
+                valueMap.get(valueKey).sources.push(lit.source);
+            }
+            else {
+                valueMap.set(valueKey, {
+                    value: lit.value,
+                    sources: [lit.source],
+                });
+            }
+        }
+    }
+    // Convert map to array
+    const possibleValues = Array.from(valueMap.values());
+    return {
+        sink,
+        resolvedCallSites,
+        possibleValues,
+        statistics: {
+            callSites: callSites.length,
+            totalSources,
+            uniqueValues: possibleValues.length,
+            unknownElements: hasUnknown,
+        },
+    };
+}
+/**
+ * Handle sink trace command (--to option)
+ */
+async function handleSinkTrace(backend, sinkSpec, projectPath, jsonOutput) {
+    // Parse the sink specification
+    const sink = parseSinkSpec(sinkSpec);
+    // Resolve the sink
+    const result = await resolveSink(backend, sink);
+    if (jsonOutput) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    // Human-readable output
+    console.log(`Sink: ${sink.raw}`);
+    console.log(`Resolved to ${result.statistics.callSites} call site(s)`);
+    console.log('');
+    if (result.possibleValues.length === 0) {
+        if (result.statistics.unknownElements) {
+            console.log('Possible values: <unknown> (runtime/parameter values)');
+        }
+        else {
+            console.log('No values found');
+        }
+        return;
+    }
+    console.log('Possible values:');
+    for (const pv of result.possibleValues) {
+        const sourcesCount = pv.sources.length;
+        console.log(`  - ${JSON.stringify(pv.value)} (${sourcesCount} source${sourcesCount === 1 ? '' : 's'})`);
+        for (const src of pv.sources.slice(0, 3)) {
+            const relativePath = src.file.startsWith(projectPath)
+                ? src.file.substring(projectPath.length + 1)
+                : src.file;
+            console.log(`    <- ${relativePath}:${src.line}`);
+        }
+        if (pv.sources.length > 3) {
+            console.log(`    ... and ${pv.sources.length - 3} more`);
+        }
+    }
+    if (result.statistics.unknownElements) {
+        console.log('');
+        console.log('Note: Some values could not be determined (runtime/parameter inputs)');
+    }
+}
+// =============================================================================
+// ROUTE-BASED TRACE IMPLEMENTATION (REG-326)
+// =============================================================================
+/**
+ * Find route by pattern.
+ *
+ * Supports:
+ * - "METHOD /path" format (e.g., "GET /status")
+ * - "/path" format (e.g., "/status")
+ *
+ * Matching strategy:
+ * 1. Try exact "METHOD PATH" match
+ * 2. Try "/PATH" only match (any method)
+ *
+ * @param backend - Graph backend
+ * @param pattern - Route pattern (with or without method)
+ * @returns Route node or null if not found
+ */
+async function findRouteByPattern(backend, pattern) {
+    const trimmed = pattern.trim();
+    for await (const node of backend.queryNodes({ type: 'http:route' })) {
+        const method = node.method || '';
+        const path = node.path || '';
+        // Match "METHOD /path"
+        if (`${method} ${path}` === trimmed) {
+            return {
+                id: node.id,
+                type: node.type || 'http:route',
+                name: `${method} ${path}`,
+                file: node.file || '',
+                line: node.line
+            };
+        }
+        // Match "/path" only (ignore method)
+        if (path === trimmed) {
+            return {
+                id: node.id,
+                type: node.type || 'http:route',
+                name: `${method} ${path}`,
+                file: node.file || '',
+                line: node.line
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Handle route-based trace (--from-route option).
+ *
+ * Flow:
+ * 1. Find route by pattern
+ * 2. Get RESPONDS_WITH edges from route
+ * 3. For each response node: call traceValues()
+ * 4. Format and display results grouped by response call
+ *
+ * @param backend - Graph backend
+ * @param pattern - Route pattern (e.g., "GET /status" or "/status")
+ * @param projectPath - Project root path
+ * @param jsonOutput - Whether to output as JSON
+ * @param maxDepth - Maximum trace depth (default 10)
+ */
+async function handleRouteTrace(backend, pattern, projectPath, jsonOutput, maxDepth = 10) {
+    // Find route
+    const route = await findRouteByPattern(backend, pattern);
+    if (!route) {
+        console.log(`Route not found: ${pattern}`);
+        console.log('');
+        console.log('Hint: Use "grafema query" to list available routes');
+        return;
+    }
+    // Get RESPONDS_WITH edges
+    const respondsWithEdges = await backend.getOutgoingEdges(route.id, ['RESPONDS_WITH']);
+    if (respondsWithEdges.length === 0) {
+        if (jsonOutput) {
+            console.log(JSON.stringify({
+                route: {
+                    name: route.name,
+                    file: route.file,
+                    line: route.line
+                },
+                responses: [],
+                message: 'No response data found'
+            }, null, 2));
+        }
+        else {
+            console.log(`Route: ${route.name} (${route.file}:${route.line || '?'})`);
+            console.log('');
+            console.log('No response data found for this route.');
+            console.log('');
+            console.log('Hint: Make sure ExpressResponseAnalyzer is in your config.');
+        }
+        return;
+    }
+    // Build response data
+    const responses = [];
+    // Trace each response
+    for (let i = 0; i < respondsWithEdges.length; i++) {
+        const edge = respondsWithEdges[i];
+        const responseNode = await backend.getNode(edge.dst);
+        if (!responseNode)
+            continue;
+        const responseMethod = edge.metadata?.responseMethod || 'unknown';
+        // Trace values from this response node
+        const traced = await traceValues(backend, responseNode.id, {
+            maxDepth,
+            followDerivesFrom: true,
+            detectNondeterministic: true
+        });
+        // Format traced values
+        const sources = await Promise.all(traced.map(async (t) => {
+            const relativePath = t.source.file.startsWith(projectPath)
+                ? t.source.file.substring(projectPath.length + 1)
+                : t.source.file;
+            if (t.isUnknown) {
+                return {
+                    type: 'UNKNOWN',
+                    reason: t.reason || 'runtime input',
+                    file: relativePath,
+                    line: t.source.line,
+                    id: t.source.id
+                };
+            }
+            else if (t.value !== undefined) {
+                return {
+                    type: 'LITERAL',
+                    value: t.value,
+                    file: relativePath,
+                    line: t.source.line,
+                    id: t.source.id
+                };
+            }
+            else {
+                // Look up node to get type and name
+                const sourceNode = await backend.getNode(t.source.id);
+                return {
+                    type: sourceNode?.type || 'VALUE',
+                    name: sourceNode?.name || '<unnamed>',
+                    file: relativePath,
+                    line: t.source.line,
+                    id: t.source.id
+                };
+            }
+        }));
+        responses.push({
+            index: i + 1,
+            method: responseMethod,
+            line: responseNode.line || 0,
+            sources: sources.length > 0 ? sources : []
+        });
+        if (!jsonOutput) {
+            // Display human-readable output
+            console.log(`Response ${i + 1} (res.${responseMethod} at line ${responseNode.line || '?'}):`);
+            if (sources.length === 0) {
+                console.log('  No data sources found (response may be external or complex)');
+            }
+            else {
+                console.log('  Data sources:');
+                for (const src of sources) {
+                    if (src.type === 'UNKNOWN') {
+                        console.log(`    [UNKNOWN] ${src.reason} at ${src.file}:${src.line}`);
+                    }
+                    else if (src.type === 'LITERAL') {
+                        console.log(`    [LITERAL] ${JSON.stringify(src.value)} at ${src.file}:${src.line}`);
+                    }
+                    else {
+                        console.log(`    [${src.type}] ${src.name} at ${src.file}:${src.line}`);
+                    }
+                }
+            }
+            console.log('');
+        }
+    }
+    // Output results
+    if (jsonOutput) {
+        console.log(JSON.stringify({
+            route: {
+                name: route.name,
+                file: route.file,
+                line: route.line
+            },
+            responses
+        }, null, 2));
+    }
+    else {
+        // Human-readable output header
+        if (responses.length > 0 && !jsonOutput) {
+            // Already printed above, just for clarity
+        }
+    }
+}

package/dist/commands/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Types command - List all node types in the graph
+ *
+ * Shows all node types present in the analyzed codebase with counts.
+ * Useful for:
+ * - Discovering what types exist (standard and custom)
+ * - Understanding graph composition
+ * - Finding types to use with --type flag
+ */
+import { Command } from 'commander';
+export declare const typesCommand: Command;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/commands/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,eAAO,MAAM,YAAY,SAuErB,CAAC"}

package/dist/commands/types.js

@@ -0,0 +1,79 @@
+/**
+ * Types command - List all node types in the graph
+ *
+ * Shows all node types present in the analyzed codebase with counts.
+ * Useful for:
+ * - Discovering what types exist (standard and custom)
+ * - Understanding graph composition
+ * - Finding types to use with --type flag
+ */
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
+import { RFDBServerBackend } from '@grafema/core';
+import { exitWithError } from '../utils/errorFormatter.js';
+export const typesCommand = new Command('types')
+    .description('List all node types in the graph')
+    .option('-p, --project <path>', 'Project path', '.')
+    .option('-j, --json', 'Output as JSON')
+    .option('-s, --sort <by>', 'Sort by: count (default) or name', 'count')
+    .addHelpText('after', `
+Examples:
+  grafema types                  List all node types with counts
+  grafema types --json           Output as JSON for scripting
+  grafema types --sort name      Sort alphabetically by type name
+  grafema types -s count         Sort by count (default, descending)
+
+Use with query --type:
+  grafema types                  # See available types
+  grafema query --type jsx:component "Button"   # Query specific type
+`)
+    .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 nodeCounts = await backend.countNodesByType();
+        const entries = Object.entries(nodeCounts);
+        if (entries.length === 0) {
+            console.log('No nodes in graph. Run: grafema analyze');
+            return;
+        }
+        // Sort entries
+        const sortedEntries = options.sort === 'name'
+            ? entries.sort((a, b) => a[0].localeCompare(b[0]))
+            : entries.sort((a, b) => b[1] - a[1]); // count descending
+        if (options.json) {
+            const result = {
+                types: sortedEntries.map(([type, count]) => ({ type, count })),
+                totalTypes: sortedEntries.length,
+                totalNodes: sortedEntries.reduce((sum, [, count]) => sum + count, 0),
+            };
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log('Node Types in Graph:');
+            console.log('');
+            // Calculate max type length for alignment
+            const maxTypeLen = Math.max(...sortedEntries.map(([type]) => type.length));
+            for (const [type, count] of sortedEntries) {
+                const paddedType = type.padEnd(maxTypeLen);
+                const formattedCount = count.toLocaleString();
+                console.log(`  ${paddedType}  ${formattedCount}`);
+            }
+            console.log('');
+            const totalNodes = sortedEntries.reduce((sum, [, count]) => sum + count, 0);
+            console.log(`Total: ${sortedEntries.length} types, ${totalNodes.toLocaleString()} nodes`);
+            console.log('');
+            console.log('Tip: Use grafema query --type <type> "pattern" to search within a type');
+        }
+    }
+    finally {
+        await backend.close();
+    }
+});

package/dist/utils/formatNode.d.ts

@@ -29,7 +29,20 @@ export interface DisplayableNode {
     file: string;
     /** Line number (optional) */
     line?: number;
+    /** HTTP method (for http:route, http:request) */
+    method?: string;
+    /** Path or URL (for http:route, http:request) */
+    path?: string;
+    /** URL (for http:request) */
+    url?: string;
 }
+/**
+ * Get the display name for a node based on its type.
+ *
+ * HTTP nodes use method + path/url instead of name.
+ * Other nodes use their name field.
+ */
+export declare function getNodeDisplayName(node: DisplayableNode): string;
 /**
  * Format a node for primary display (multi-line)
  *