@grafema/cli 0.1.1-alpha → 0.2.1-beta

package/dist/commands/schema.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Schema command - Export code schemas
+ *
+ * Usage:
+ *   grafema schema export --interface ConfigSchema
+ *   grafema schema export --interface ConfigSchema --format yaml
+ *   grafema schema export --interface ConfigSchema --file src/config/types.ts
+ *   grafema schema export --graph
+ *   grafema schema export --graph --format yaml
+ */
+import { Command } from 'commander';
+export declare const schemaCommand: Command;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/commands/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2UpC,eAAO,MAAM,aAAa,SAEK,CAAC"}

package/dist/commands/schema.js

@@ -0,0 +1,279 @@
+/**
+ * Schema command - Export code schemas
+ *
+ * Usage:
+ *   grafema schema export --interface ConfigSchema
+ *   grafema schema export --interface ConfigSchema --format yaml
+ *   grafema schema export --interface ConfigSchema --file src/config/types.ts
+ *   grafema schema export --graph
+ *   grafema schema export --graph --format yaml
+ */
+import { Command } from 'commander';
+import { resolve, join, relative } from 'path';
+import { existsSync, writeFileSync } from 'fs';
+import { RFDBServerBackend, InterfaceSchemaExtractor, GraphSchemaExtractor, } from '@grafema/core';
+import { exitWithError } from '../utils/errorFormatter.js';
+// ============================================================================
+// Interface Schema Formatters
+// ============================================================================
+function formatInterfaceJson(schema) {
+    return JSON.stringify(schema, null, 2);
+}
+function formatInterfaceYaml(schema) {
+    const lines = [];
+    lines.push(`$schema: ${schema.$schema}`);
+    lines.push(`name: ${schema.name}`);
+    lines.push('source:');
+    lines.push(`  file: ${schema.source.file}`);
+    lines.push(`  line: ${schema.source.line}`);
+    lines.push(`  column: ${schema.source.column}`);
+    if (schema.typeParameters && schema.typeParameters.length > 0) {
+        lines.push('typeParameters:');
+        for (const param of schema.typeParameters) {
+            lines.push(`  - "${param}"`);
+        }
+    }
+    lines.push('properties:');
+    for (const [name, prop] of Object.entries(schema.properties)) {
+        lines.push(`  ${name}:`);
+        lines.push(`    type: "${prop.type}"`);
+        lines.push(`    required: ${prop.required}`);
+        lines.push(`    readonly: ${prop.readonly}`);
+    }
+    if (schema.extends.length > 0) {
+        lines.push('extends:');
+        for (const ext of schema.extends) {
+            lines.push(`  - ${ext}`);
+        }
+    }
+    else {
+        lines.push('extends: []');
+    }
+    lines.push(`checksum: ${schema.checksum}`);
+    return lines.join('\n');
+}
+function formatInterfaceMarkdown(schema, projectPath) {
+    const lines = [];
+    const relPath = relative(projectPath, schema.source.file);
+    lines.push(`# Interface: ${schema.name}`);
+    lines.push('');
+    if (schema.typeParameters && schema.typeParameters.length > 0) {
+        lines.push(`**Type Parameters:** \`<${schema.typeParameters.join(', ')}>\``);
+        lines.push('');
+    }
+    lines.push(`**Source:** \`${relPath}:${schema.source.line}\``);
+    lines.push('');
+    if (schema.extends.length > 0) {
+        lines.push(`**Extends:** ${schema.extends.map(e => `\`${e}\``).join(', ')}`);
+        lines.push('');
+    }
+    lines.push('## Properties');
+    lines.push('');
+    lines.push('| Name | Type | Required | Readonly |');
+    lines.push('|------|------|----------|----------|');
+    for (const [name, prop] of Object.entries(schema.properties)) {
+        const required = prop.required ? 'Yes' : 'No';
+        const readonly = prop.readonly ? 'Yes' : 'No';
+        lines.push(`| \`${name}\` | \`${prop.type}\` | ${required} | ${readonly} |`);
+    }
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    lines.push(`*Checksum: \`${schema.checksum}\`*`);
+    return lines.join('\n');
+}
+/**
+ * Check if schema has method properties (type='function')
+ * Used to show Phase 1 limitation warning
+ */
+function hasMethodProperties(schema) {
+    return Object.values(schema.properties).some(p => p.type === 'function');
+}
+// ============================================================================
+// Graph Schema Formatters
+// ============================================================================
+function formatGraphJson(schema) {
+    return JSON.stringify(schema, null, 2);
+}
+function formatGraphYaml(schema) {
+    const lines = [];
+    lines.push(`$schema: ${schema.$schema}`);
+    lines.push(`extractedAt: ${schema.extractedAt}`);
+    lines.push('');
+    lines.push('statistics:');
+    lines.push(`  totalNodes: ${schema.statistics.totalNodes}`);
+    lines.push(`  totalEdges: ${schema.statistics.totalEdges}`);
+    lines.push(`  nodeTypeCount: ${schema.statistics.nodeTypeCount}`);
+    lines.push(`  edgeTypeCount: ${schema.statistics.edgeTypeCount}`);
+    lines.push('');
+    lines.push('nodeTypes:');
+    for (const [type, info] of Object.entries(schema.nodeTypes)) {
+        if (info.count > 0) {
+            lines.push(`  ${type}:`);
+            lines.push(`    category: ${info.category}`);
+            if (info.namespace) {
+                lines.push(`    namespace: ${info.namespace}`);
+            }
+            lines.push(`    count: ${info.count}`);
+        }
+    }
+    lines.push('');
+    lines.push('edgeTypes:');
+    for (const [type, info] of Object.entries(schema.edgeTypes)) {
+        if (info.count > 0) {
+            lines.push(`  ${type}:`);
+            lines.push(`    count: ${info.count}`);
+        }
+    }
+    lines.push('');
+    lines.push(`checksum: ${schema.checksum}`);
+    return lines.join('\n');
+}
+function formatGraphMarkdown(schema) {
+    const lines = [];
+    lines.push('# Graph Schema');
+    lines.push('');
+    lines.push(`**Extracted:** ${schema.extractedAt}`);
+    lines.push('');
+    lines.push('## Statistics');
+    lines.push('');
+    lines.push(`- Total Nodes: ${schema.statistics.totalNodes}`);
+    lines.push(`- Total Edges: ${schema.statistics.totalEdges}`);
+    lines.push(`- Node Types: ${schema.statistics.nodeTypeCount}`);
+    lines.push(`- Edge Types: ${schema.statistics.edgeTypeCount}`);
+    lines.push('');
+    lines.push('## Node Types');
+    lines.push('');
+    lines.push('| Type | Category | Count |');
+    lines.push('|------|----------|-------|');
+    for (const [type, info] of Object.entries(schema.nodeTypes)) {
+        if (info.count > 0) {
+            const cat = info.namespace ? `${info.category} (${info.namespace})` : info.category;
+            lines.push(`| \`${type}\` | ${cat} | ${info.count} |`);
+        }
+    }
+    lines.push('');
+    lines.push('## Edge Types');
+    lines.push('');
+    lines.push('| Type | Count |');
+    lines.push('|------|-------|');
+    for (const [type, info] of Object.entries(schema.edgeTypes)) {
+        if (info.count > 0) {
+            lines.push(`| \`${type}\` | ${info.count} |`);
+        }
+    }
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    lines.push(`*Checksum: \`${schema.checksum}\`*`);
+    return lines.join('\n');
+}
+// ============================================================================
+// Command
+// ============================================================================
+const exportSubcommand = new Command('export')
+    .description('Export interface or graph schema')
+    .option('--interface <name>', 'Interface name to export')
+    .option('--graph', 'Export graph node/edge type schema')
+    .option('--all', 'Include all defined types, not just used ones (with --graph)')
+    .option('--file <path>', 'File path filter (for multiple interfaces with same name)')
+    .option('-f, --format <type>', 'Output format: json, yaml, markdown', 'json')
+    .option('-p, --project <path>', 'Project path', '.')
+    .option('-o, --output <file>', 'Output file (default: stdout)')
+    .action(async (options) => {
+    // Validate: must have either --interface or --graph
+    if (!options.interface && !options.graph) {
+        exitWithError('Must specify either --interface <name> or --graph', [
+            'Examples:',
+            '  grafema schema export --interface ConfigSchema',
+            '  grafema schema export --graph',
+        ]);
+    }
+    if (options.interface && options.graph) {
+        exitWithError('Cannot specify both --interface and --graph', [
+            'Use one at a time.',
+        ]);
+    }
+    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 {
+        if (options.graph) {
+            // Graph schema export
+            const extractor = new GraphSchemaExtractor(backend);
+            const schema = await extractor.extract({ includeAll: options.all });
+            let output;
+            switch (options.format) {
+                case 'yaml':
+                    output = formatGraphYaml(schema);
+                    break;
+                case 'markdown':
+                    output = formatGraphMarkdown(schema);
+                    break;
+                case 'json':
+                default:
+                    output = formatGraphJson(schema);
+            }
+            if (options.output) {
+                writeFileSync(resolve(options.output), output + '\n');
+                console.log(`Graph schema written to ${options.output}`);
+            }
+            else {
+                console.log(output);
+            }
+        }
+        else {
+            // Interface schema export
+            const extractor = new InterfaceSchemaExtractor(backend);
+            const schema = await extractor.extract(options.interface, {
+                file: options.file,
+            });
+            if (!schema) {
+                exitWithError(`Interface not found: ${options.interface}`, [
+                    'Use "grafema query interface <name>" to search',
+                ]);
+            }
+            // Phase 1 limitation warning for methods
+            if (hasMethodProperties(schema)) {
+                console.warn('Note: Method signatures are shown as "function" type. ' +
+                    'Full signatures planned for v2.');
+            }
+            let output;
+            switch (options.format) {
+                case 'yaml':
+                    output = formatInterfaceYaml(schema);
+                    break;
+                case 'markdown':
+                    output = formatInterfaceMarkdown(schema, projectPath);
+                    break;
+                case 'json':
+                default:
+                    output = formatInterfaceJson(schema);
+            }
+            if (options.output) {
+                writeFileSync(resolve(options.output), output + '\n');
+                console.log(`Schema written to ${options.output}`);
+            }
+            else {
+                console.log(output);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            exitWithError(error.message);
+        }
+        throw error;
+    }
+    finally {
+        await backend.close();
+    }
+});
+export const schemaCommand = new Command('schema')
+    .description('Extract and manage code schemas')
+    .addCommand(exportSubcommand);

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/commands/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+FpC,eAAO,MAAM,aAAa,SACoB,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/commands/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+FpC,eAAO,MAAM,aAAa,SAQxB,CAAC"}

package/dist/commands/server.js

@@ -19,8 +19,8 @@ const __dirname = dirname(__filename);
 /**
  * Find RFDB server binary in order of preference:
  * 1. @grafema/rfdb npm package
- * 2. rust-engine/target/release (monorepo development)
- * 3. rust-engine/target/debug
+ * 2. packages/rfdb-server/target/release (monorepo development)
+ * 3. packages/rfdb-server/target/debug
  */
 function findServerBinary() {
     // 1. Check @grafema/rfdb npm package
@@ -47,15 +47,15 @@ function findServerBinary() {
     catch {
         // @grafema/rfdb not installed
     }
-    // 2. Check rust-engine in monorepo
+    // 2. Check packages/rfdb-server in monorepo
     // From packages/cli/dist/commands -> project root is 4 levels up
     const projectRoot = join(__dirname, '../../../..');
-    const releaseBinary = join(projectRoot, 'rust-engine/target/release/rfdb-server');
+    const releaseBinary = join(projectRoot, 'packages/rfdb-server/target/release/rfdb-server');
     if (existsSync(releaseBinary)) {
         return releaseBinary;
     }
     // 3. Check debug build
-    const debugBinary = join(projectRoot, 'rust-engine/target/debug/rfdb-server');
+    const debugBinary = join(projectRoot, 'packages/rfdb-server/target/debug/rfdb-server');
     if (existsSync(debugBinary)) {
         return debugBinary;
     }
@@ -94,7 +94,14 @@ function getProjectPaths(projectPath) {
 }
 // Create main server command with subcommands
 export const serverCommand = new Command('server')
-    .description('Manage RFDB server lifecycle');
+    .description('Manage RFDB server lifecycle')
+    .addHelpText('after', `
+Examples:
+  grafema server start           Start the RFDB server (detached)
+  grafema server stop            Stop the running server
+  grafema server status          Check if server is running
+  grafema server status --json   Server status as JSON
+`);
 // grafema server start
 serverCommand
     .command('start')

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

@@ -1 +1 @@
-{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../src/commands/stats.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,eAAO,MAAM,YAAY,SA+CrB,CAAC"}
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../src/commands/stats.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,eAAO,MAAM,YAAY,SAsDrB,CAAC"}

package/dist/commands/stats.js

@@ -11,6 +11,13 @@ export const statsCommand = new Command('stats')
     .option('-p, --project <path>', 'Project path', '.')
     .option('-j, --json', 'Output as JSON')
     .option('-t, --types', 'Show breakdown by type')
+    .addHelpText('after', `
+Examples:
+  grafema stats                  Show basic graph statistics
+  grafema stats --types          Show breakdown by node/edge types
+  grafema stats --json           Output statistics as JSON
+  grafema stats -p ./app         Statistics for specific project
+`)
     .action(async (options) => {
     const projectPath = resolve(options.project);
     const grafemaDir = join(projectPath, '.grafema');

package/dist/commands/trace.d.ts

@@ -4,7 +4,80 @@
  * Usage:
  *   grafema trace "userId from authenticate"
  *   grafema trace "config"
+ *   grafema trace --to "addNode#0.type"  (sink-based trace)
  */
 import { Command } from 'commander';
+import { RFDBServerBackend, type ValueSource } from '@grafema/core';
+/**
+ * Parsed sink specification from "fn#0.property.path" format
+ */
+export interface SinkSpec {
+    functionName: string;
+    argIndex: number;
+    propertyPath: string[];
+    raw: string;
+}
+/**
+ * Information about a call site
+ */
+export interface CallSiteInfo {
+    id: string;
+    calleeFunction: string;
+    file: string;
+    line: number;
+}
+/**
+ * Result of sink resolution
+ */
+export interface SinkResolutionResult {
+    sink: SinkSpec;
+    resolvedCallSites: CallSiteInfo[];
+    possibleValues: Array<{
+        value: unknown;
+        sources: ValueSource[];
+    }>;
+    statistics: {
+        callSites: number;
+        totalSources: number;
+        uniqueValues: number;
+        unknownElements: boolean;
+    };
+}
 export declare const traceCommand: Command;
+/**
+ * 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 declare function parseSinkSpec(spec: string): SinkSpec;
+/**
+ * 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 declare function findCallSites(backend: RFDBServerBackend, targetFunctionName: string): Promise<CallSiteInfo[]>;
+/**
+ * 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 declare function extractArgument(backend: RFDBServerBackend, callSiteId: string, argIndex: number): Promise<string | null>;
+/**
+ * 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 declare function resolveSink(backend: RFDBServerBackend, sink: SinkSpec): Promise<SinkResolutionResult>;
 //# sourceMappingURL=trace.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/commands/trace.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4BpC,eAAO,MAAM,YAAY,SAuFrB,CAAC"}
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/commands/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,iBAAiB,EAAgC,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAgBlG;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,iBAAiB,EAAE,YAAY,EAAE,CAAC;IAClC,cAAc,EAAE,KAAK,CAAC;QACpB,KAAK,EAAE,OAAO,CAAC;QACf,OAAO,EAAE,WAAW,EAAE,CAAC;KACxB,CAAC,CAAC;IACH,UAAU,EAAE;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,OAAO,CAAC;KAC1B,CAAC;CACH;AAiBD,eAAO,MAAM,YAAY,SAqHrB,CAAC;AAsOL;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAiDpD;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,iBAAiB,EAC1B,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,YAAY,EAAE,CAAC,CAoBzB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYxB;AAyED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,oBAAoB,CAAC,CAuE/B"}