@grafema/cli 0.1.1-alpha

package/dist/commands/get.js

@@ -0,0 +1,189 @@
+/**
+ * Get command - Retrieve node by semantic ID
+ *
+ * Usage:
+ *   grafema get "file.js->scope->TYPE->name"
+ *   grafema get "file.js->scope->TYPE->name" --json
+ */
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
+import { RFDBServerBackend } from '@grafema/core';
+import { formatNodeDisplay } from '../utils/formatNode.js';
+import { exitWithError } from '../utils/errorFormatter.js';
+export const getCommand = new Command('get')
+    .description('Retrieve a node by its semantic ID')
+    .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')
+    .action(async (semanticId, 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 {
+        // Retrieve node by semantic ID
+        const node = await backend.getNode(semanticId);
+        if (!node) {
+            exitWithError('Node not found', [
+                `ID: ${semanticId}`,
+                'Try: grafema query "<name>" to search for nodes',
+            ]);
+        }
+        // Get incoming and outgoing edges
+        const incomingEdges = await backend.getIncomingEdges(semanticId, null);
+        const outgoingEdges = await backend.getOutgoingEdges(semanticId, null);
+        if (options.json) {
+            await outputJSON(backend, node, incomingEdges, outgoingEdges);
+        }
+        else {
+            await outputText(backend, node, incomingEdges, outgoingEdges, projectPath);
+        }
+    }
+    finally {
+        await backend.close();
+    }
+});
+/**
+ * Output node and edges as JSON
+ */
+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',
+        targetId: edge.src,
+        targetName: await getNodeName(backend, edge.src),
+    })));
+    const outgoingWithNames = await Promise.all(outgoingEdges.map(async (edge) => ({
+        edgeType: edge.edgeType || edge.type || 'UNKNOWN',
+        targetId: edge.dst,
+        targetName: await getNodeName(backend, edge.dst),
+    })));
+    const result = {
+        node: {
+            id: node.id,
+            type: node.type || 'UNKNOWN',
+            name: node.name || '',
+            file: node.file || '',
+            line: node.line,
+            ...getMetadataFields(node),
+        },
+        edges: {
+            incoming: incomingWithNames,
+            outgoing: outgoingWithNames,
+        },
+        stats: {
+            incomingCount: incomingEdges.length,
+            outgoingCount: outgoingEdges.length,
+        },
+    };
+    console.log(JSON.stringify(result, null, 2));
+}
+/**
+ * Output node and edges as formatted text
+ */
+async function outputText(backend, node, incomingEdges, outgoingEdges, projectPath) {
+    const nodeInfo = {
+        id: node.id,
+        type: node.type || 'UNKNOWN',
+        name: node.name || '',
+        file: node.file || '',
+        line: node.line,
+    };
+    // Display node details
+    console.log(formatNodeDisplay(nodeInfo, { projectPath }));
+    // Display metadata if present
+    const metadata = getMetadataFields(node);
+    if (Object.keys(metadata).length > 0) {
+        console.log('');
+        console.log('Metadata:');
+        for (const [key, value] of Object.entries(metadata)) {
+            console.log(`  ${key}: ${JSON.stringify(value)}`);
+        }
+    }
+    // Display edges
+    console.log('');
+    await displayEdges(backend, 'Incoming', incomingEdges, (edge) => edge.src);
+    console.log('');
+    await displayEdges(backend, 'Outgoing', outgoingEdges, (edge) => edge.dst);
+}
+/**
+ * Display edges grouped by type, limited to 20 in text mode
+ */
+async function displayEdges(backend, direction, edges, getTargetId) {
+    const totalCount = edges.length;
+    if (totalCount === 0) {
+        console.log(`${direction} edges (0):`);
+        console.log('  (none)');
+        return;
+    }
+    // Group edges by type
+    const byType = new Map();
+    for (const edge of edges) {
+        const edgeType = edge.edgeType || edge.type || 'UNKNOWN';
+        const targetId = getTargetId(edge);
+        const targetName = await getNodeName(backend, targetId);
+        if (!byType.has(edgeType)) {
+            byType.set(edgeType, []);
+        }
+        byType.get(edgeType).push({ edgeType, targetId, targetName });
+    }
+    // Display header with count
+    const limitApplied = totalCount > 20;
+    console.log(`${direction} edges (${totalCount}):`);
+    // Display edges, limited to 20 total
+    let displayed = 0;
+    const limit = 20;
+    for (const [edgeType, edgesOfType] of Array.from(byType.entries())) {
+        console.log(`  ${edgeType}:`);
+        for (const edge of edgesOfType) {
+            if (displayed >= limit)
+                break;
+            // Format: TYPE#name
+            const label = edge.targetName ? `${edge.edgeType}#${edge.targetName}` : edge.targetId;
+            console.log(`    ${label}`);
+            displayed++;
+        }
+        if (displayed >= limit)
+            break;
+    }
+    // Show "and X more" if we hit the limit
+    if (limitApplied) {
+        const remaining = totalCount - displayed;
+        console.log(`  ... and ${remaining} more (use --json to see all)`);
+    }
+}
+/**
+ * Get node name for display
+ */
+async function getNodeName(backend, nodeId) {
+    try {
+        const node = await backend.getNode(nodeId);
+        if (node) {
+            return node.name || '';
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return '';
+}
+/**
+ * Extract metadata fields (exclude standard fields)
+ */
+function getMetadataFields(node) {
+    const standardFields = new Set([
+        'id', 'type', 'nodeType', 'name', 'file', 'line',
+    ]);
+    const metadata = {};
+    for (const [key, value] of Object.entries(node)) {
+        if (!standardFields.has(key) && value !== undefined && value !== null) {
+            metadata[key] = value;
+        }
+    }
+    return metadata;
+}

package/dist/commands/impact.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Impact command - Change impact analysis
+ *
+ * Usage:
+ *   grafema impact "function authenticate"
+ *   grafema impact "class UserService"
+ */
+import { Command } from 'commander';
+export declare const impactCommand: Command;
+//# sourceMappingURL=impact.d.ts.map

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

@@ -0,0 +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"}

package/dist/commands/impact.js

@@ -0,0 +1,313 @@
+/**
+ * Impact command - Change impact analysis
+ *
+ * Usage:
+ *   grafema impact "function authenticate"
+ *   grafema impact "class UserService"
+ */
+import { Command } from 'commander';
+import { resolve, join, dirname } from 'path';
+import { relative } from 'path';
+import { existsSync } from 'fs';
+import { RFDBServerBackend } from '@grafema/core';
+import { formatNodeDisplay, formatNodeInline } from '../utils/formatNode.js';
+import { exitWithError } from '../utils/errorFormatter.js';
+export const impactCommand = new Command('impact')
+    .description('Analyze change impact for a function or class')
+    .argument('<pattern>', 'Target: "function X" or "class Y" or just "X"')
+    .option('-p, --project <path>', 'Project path', '.')
+    .option('-j, --json', 'Output as JSON')
+    .option('-d, --depth <n>', 'Max traversal depth', '10')
+    .action(async (pattern, 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 { type, name } = parsePattern(pattern);
+        const maxDepth = parseInt(options.depth, 10);
+        console.log(`Analyzing impact of changing ${name}...`);
+        console.log('');
+        // Find target node
+        const target = await findTarget(backend, type, name);
+        if (!target) {
+            console.log(`No ${type || 'node'} "${name}" found`);
+            return;
+        }
+        // Analyze impact
+        const impact = await analyzeImpact(backend, target, maxDepth, projectPath);
+        if (options.json) {
+            console.log(JSON.stringify({
+                target: impact.target,
+                directCallers: impact.directCallers.length,
+                transitiveCallers: impact.transitiveCallers.length,
+                affectedModules: Object.fromEntries(impact.affectedModules),
+                callChains: impact.callChains.slice(0, 5),
+            }, null, 2));
+            return;
+        }
+        // Display results
+        displayImpact(impact, projectPath);
+    }
+    finally {
+        await backend.close();
+    }
+});
+/**
+ * Parse pattern like "function authenticate"
+ */
+function parsePattern(pattern) {
+    const words = pattern.trim().split(/\s+/);
+    if (words.length >= 2) {
+        const typeWord = words[0].toLowerCase();
+        const name = words.slice(1).join(' ');
+        const typeMap = {
+            function: 'FUNCTION',
+            fn: 'FUNCTION',
+            class: 'CLASS',
+            module: 'MODULE',
+        };
+        if (typeMap[typeWord]) {
+            return { type: typeMap[typeWord], name };
+        }
+    }
+    return { type: null, name: pattern.trim() };
+}
+/**
+ * Find target node
+ */
+async function findTarget(backend, type, name) {
+    const searchTypes = type ? [type] : ['FUNCTION', 'CLASS'];
+    for (const nodeType of searchTypes) {
+        for await (const node of backend.queryNodes({ nodeType: nodeType })) {
+            const nodeName = node.name || '';
+            if (nodeName.toLowerCase() === name.toLowerCase()) {
+                return {
+                    id: node.id,
+                    type: node.type || nodeType,
+                    name: nodeName,
+                    file: node.file || '',
+                    line: node.line,
+                };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Analyze impact of changing a node
+ */
+async function analyzeImpact(backend, target, maxDepth, projectPath) {
+    const directCallers = [];
+    const transitiveCallers = [];
+    const affectedModules = new Map();
+    const callChains = [];
+    const visited = new Set();
+    // BFS to find all callers
+    const queue = [
+        { id: target.id, depth: 0, chain: [target.name] }
+    ];
+    while (queue.length > 0) {
+        const { id, depth, chain } = queue.shift();
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        if (depth > maxDepth)
+            continue;
+        try {
+            // Find what calls this node
+            // First, find CALL nodes that have this as target
+            const containingCalls = await findCallsToNode(backend, id);
+            for (const callNode of containingCalls) {
+                // Find the function containing this call
+                const container = await findContainingFunction(backend, callNode.id);
+                if (container && !visited.has(container.id)) {
+                    const caller = {
+                        id: container.id,
+                        type: container.type,
+                        name: container.name,
+                        file: container.file,
+                        line: container.line,
+                    };
+                    if (depth === 0) {
+                        directCallers.push(caller);
+                    }
+                    else {
+                        transitiveCallers.push(caller);
+                    }
+                    // Track affected modules
+                    const modulePath = getModulePath(caller.file, projectPath);
+                    affectedModules.set(modulePath, (affectedModules.get(modulePath) || 0) + 1);
+                    // Track call chain
+                    const newChain = [...chain, caller.name];
+                    if (newChain.length <= 4) {
+                        callChains.push(newChain);
+                    }
+                    // Continue BFS
+                    queue.push({ id: container.id, depth: depth + 1, chain: newChain });
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+    // Sort call chains by length
+    callChains.sort((a, b) => b.length - a.length);
+    return {
+        target,
+        directCallers,
+        transitiveCallers,
+        affectedModules,
+        callChains,
+    };
+}
+/**
+ * Find CALL nodes that reference a target
+ */
+async function findCallsToNode(backend, targetId) {
+    const calls = [];
+    try {
+        // Get incoming CALLS edges
+        const edges = await backend.getIncomingEdges(targetId, ['CALLS']);
+        for (const edge of edges) {
+            const callNode = await backend.getNode(edge.src);
+            if (callNode) {
+                calls.push({
+                    id: callNode.id,
+                    type: callNode.type || 'CALL',
+                    name: callNode.name || '',
+                    file: callNode.file || '',
+                    line: callNode.line,
+                });
+            }
+        }
+    }
+    catch {
+        // Ignore
+    }
+    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
+ */
+function getModulePath(file, projectPath) {
+    if (!file)
+        return '<unknown>';
+    const relPath = relative(projectPath, file);
+    const dir = dirname(relPath);
+    return dir === '.' ? relPath : `${dir}/*`;
+}
+/**
+ * Display impact analysis results with semantic IDs
+ */
+function displayImpact(impact, projectPath) {
+    console.log(formatNodeDisplay(impact.target, { projectPath }));
+    console.log('');
+    // Direct impact
+    console.log('Direct impact:');
+    console.log(`  ${impact.directCallers.length} direct callers`);
+    console.log(`  ${impact.transitiveCallers.length} transitive callers`);
+    console.log(`  ${impact.directCallers.length + impact.transitiveCallers.length} total affected`);
+    console.log('');
+    // Show direct callers
+    if (impact.directCallers.length > 0) {
+        console.log('Direct callers:');
+        for (const caller of impact.directCallers.slice(0, 10)) {
+            console.log(`  <- ${formatNodeInline(caller)}`);
+        }
+        if (impact.directCallers.length > 10) {
+            console.log(`  ... and ${impact.directCallers.length - 10} more`);
+        }
+        console.log('');
+    }
+    // Affected modules
+    if (impact.affectedModules.size > 0) {
+        console.log('Affected modules:');
+        const sorted = [...impact.affectedModules.entries()].sort((a, b) => b[1] - a[1]);
+        for (const [module, count] of sorted.slice(0, 5)) {
+            console.log(`  ├─ ${module} (${count} calls)`);
+        }
+        if (sorted.length > 5) {
+            console.log(`  └─ ... and ${sorted.length - 5} more modules`);
+        }
+        console.log('');
+    }
+    // Call chains
+    if (impact.callChains.length > 0) {
+        console.log('Call chains (sample):');
+        for (const chain of impact.callChains.slice(0, 3)) {
+            console.log(`  ${chain.join(' → ')}`);
+        }
+        console.log('');
+    }
+    // Risk assessment
+    const totalAffected = impact.directCallers.length + impact.transitiveCallers.length;
+    const moduleCount = impact.affectedModules.size;
+    let risk = 'LOW';
+    let color = '\x1b[32m'; // green
+    if (totalAffected > 20 || moduleCount > 5) {
+        risk = 'HIGH';
+        color = '\x1b[31m'; // red
+    }
+    else if (totalAffected > 5 || moduleCount > 2) {
+        risk = 'MEDIUM';
+        color = '\x1b[33m'; // yellow
+    }
+    console.log(`Risk level: ${color}${risk}\x1b[0m`);
+    if (risk === 'HIGH') {
+        console.log('');
+        console.log('Recommendation:');
+        console.log('  • Consider adding backward-compatible wrapper');
+        console.log('  • Update tests in affected modules');
+        console.log('  • Notify team about breaking change');
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Init command - Initialize Grafema in a project
+ */
+import { Command } from 'commander';
+export declare const initCommand: Command;
+//# sourceMappingURL=init.d.ts.map

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

@@ -0,0 +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"}

package/dist/commands/init.js

@@ -0,0 +1,94 @@
+/**
+ * Init command - Initialize Grafema in a project
+ */
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { exitWithError } from '../utils/errorFormatter.js';
+import { stringify as stringifyYAML } from 'yaml';
+import { DEFAULT_CONFIG } from '@grafema/core';
+/**
+ * Generate config.yaml content with commented future features.
+ * Only includes implemented features (plugins).
+ */
+function generateConfigYAML() {
+    // Start with working default config
+    const config = {
+        // Plugin list (fully implemented)
+        plugins: DEFAULT_CONFIG.plugins,
+    };
+    // Convert to YAML
+    const yaml = stringifyYAML(config, {
+        lineWidth: 0, // Don't wrap long lines
+    });
+    // Add header comment
+    return `# Grafema Configuration
+# 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
+#
+# include:
+#   - "src/**/*.{ts,js,tsx,jsx}"
+# exclude:
+#   - "**/*.test.ts"
+#   - "node_modules/**"
+`;
+}
+export const initCommand = new Command('init')
+    .description('Initialize Grafema in current project')
+    .argument('[path]', 'Project path', '.')
+    .option('-f, --force', 'Overwrite existing config')
+    .action(async (path, options) => {
+    const projectPath = resolve(path);
+    const grafemaDir = join(projectPath, '.grafema');
+    const configPath = join(grafemaDir, 'config.yaml');
+    const packageJsonPath = join(projectPath, 'package.json');
+    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.log('✓ Found package.json');
+    // Detect TypeScript
+    const isTypeScript = existsSync(tsconfigPath);
+    if (isTypeScript) {
+        console.log('✓ Detected TypeScript project');
+    }
+    else {
+        console.log('✓ Detected JavaScript project');
+    }
+    // Check existing config
+    if (existsSync(configPath) && !options.force) {
+        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');
+        return;
+    }
+    // Create .grafema directory
+    if (!existsSync(grafemaDir)) {
+        mkdirSync(grafemaDir, { recursive: true });
+    }
+    // Write config
+    const configContent = generateConfigYAML();
+    writeFileSync(configPath, configContent);
+    console.log('✓ Created .grafema/config.yaml');
+    // Add to .gitignore if exists
+    const gitignorePath = join(projectPath, '.gitignore');
+    if (existsSync(gitignorePath)) {
+        const gitignore = readFileSync(gitignorePath, 'utf-8');
+        if (!gitignore.includes('.grafema/graph.rfdb')) {
+            writeFileSync(gitignorePath, gitignore + '\n# Grafema\n.grafema/graph.rfdb\n.grafema/rfdb.sock\n');
+            console.log('✓ Updated .gitignore');
+        }
+    }
+    console.log('');
+    console.log('Next: Run "grafema analyze" to build the code graph');
+});

package/dist/commands/overview.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Overview command - Project dashboard
+ */
+import { Command } from 'commander';
+export declare const overviewCommand: Command;
+//# sourceMappingURL=overview.d.ts.map

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

@@ -0,0 +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"}