@grafema/cli 0.2.5-beta → 0.2.7

package/src/commands/query.ts

@@ -10,13 +10,23 @@
  */
 
 import { Command } from 'commander';
-import { resolve, join, relative, basename } from 'path';
+import { resolve, join, basename } from 'path';
+import { toRelativeDisplay } from '../utils/pathUtils.js';
 import { existsSync } from 'fs';
-import { RFDBServerBackend, parseSemanticId, findCallsInFunction as findCallsInFunctionCore, findContainingFunction as findContainingFunctionCore } from '@grafema/core';
+import { RFDBServerBackend, parseSemanticId, parseSemanticIdV2, findCallsInFunction as findCallsInFunctionCore, findContainingFunction as findContainingFunctionCore } from '@grafema/core';
 import { formatNodeDisplay, formatNodeInline, formatLocation } from '../utils/formatNode.js';
 import { exitWithError } from '../utils/errorFormatter.js';
 import { Spinner } from '../utils/spinner.js';
 
+// Node type constants to avoid magic string duplication
+const HTTP_ROUTE_TYPE = 'http:route';
+const HTTP_REQUEST_TYPE = 'http:request';
+const SOCKETIO_EVENT_TYPE = 'socketio:event';
+const SOCKETIO_EMIT_TYPE = 'socketio:emit';
+const SOCKETIO_ON_TYPE = 'socketio:on';
+const GRAFEMA_PLUGIN_TYPE = 'grafema:plugin';
+const PROPERTY_ACCESS_TYPE = 'PROPERTY_ACCESS';
+
 interface QueryOptions {
   project: string;
   json?: boolean;
@@ -76,6 +86,9 @@ export const queryCommand = new Command('query')
     '--raw',
     `Execute raw Datalog query
 
+Supports both direct queries and Datalog rules.
+Rules (containing ":-") define a violation predicate and return matching nodes.
+
 Predicates:
   type(Id, Type)        Find nodes by type or get type of node
   node(Id, Type)        Alias for type
@@ -84,10 +97,14 @@ Predicates:
   path(Src, Dst)        Check reachability between nodes
   incoming(Dst, Src, T) Find incoming edges
 
-Examples:
+Direct queries:
   grafema query --raw 'type(X, "FUNCTION")'
   grafema query --raw 'type(X, "FUNCTION"), attr(X, "name", "main")'
-  grafema query --raw 'edge(X, Y, "CALLS")'`
+  grafema query --raw 'edge(X, Y, "CALLS")'
+
+Rules (must define violation/1):
+  grafema query --raw 'violation(X) :- node(X, "FUNCTION").'
+  grafema query --raw 'violation(X) :- node(X, "http:route"), attr(X, "method", "POST").'`
   )
   .option(
     '-t, --type <nodeType>',
@@ -135,15 +152,19 @@ Examples:
     spinner.start();
 
     try {
+      const limit = parseInt(options.limit, 10);
+      if (isNaN(limit) || limit < 1) {
+        spinner.stop();
+        exitWithError('Invalid limit', ['Use a positive number, e.g.: --limit 10']);
+      }
+
       // Raw Datalog mode
       if (options.raw) {
         spinner.stop();
-        await executeRawQuery(backend, pattern, options);
+        await executeRawQuery(backend, pattern, limit, options.json);
         return;
       }
 
-      const limit = parseInt(options.limit, 10);
-
       // Parse query with scope support
       let query: ParsedQuery;
 
@@ -245,28 +266,31 @@ function parsePattern(pattern: string): { type: string | null; name: string } {
       fn: 'FUNCTION',
       func: 'FUNCTION',
       class: 'CLASS',
+      interface: 'INTERFACE',
+      type: 'TYPE',
+      enum: 'ENUM',
       module: 'MODULE',
       variable: 'VARIABLE',
       var: 'VARIABLE',
       const: 'CONSTANT',
       constant: 'CONSTANT',
       // HTTP route aliases
-      route: 'http:route',
-      endpoint: 'http:route',
+      route: HTTP_ROUTE_TYPE,
+      endpoint: HTTP_ROUTE_TYPE,
       // HTTP request aliases
-      request: 'http:request',
-      fetch: 'http:request',
-      api: 'http:request',
+      request: HTTP_REQUEST_TYPE,
+      fetch: HTTP_REQUEST_TYPE,
+      api: HTTP_REQUEST_TYPE,
       // Socket.IO aliases
-      event: 'socketio:event',
-      emit: 'socketio:emit',
-      on: 'socketio:on',
-      listener: 'socketio:on',
+      event: SOCKETIO_EVENT_TYPE,
+      emit: SOCKETIO_EMIT_TYPE,
+      on: SOCKETIO_ON_TYPE,
+      listener: SOCKETIO_ON_TYPE,
       // Grafema internal
-      plugin: 'grafema:plugin',
+      plugin: GRAFEMA_PLUGIN_TYPE,
       // Property access aliases (REG-395)
-      property: 'PROPERTY_ACCESS',
-      prop: 'PROPERTY_ACCESS',
+      property: PROPERTY_ACCESS_TYPE,
+      prop: PROPERTY_ACCESS_TYPE,
     };
 
     if (typeMap[typeWord]) {
@@ -370,6 +394,36 @@ export function isFileScope(scope: string): boolean {
  * @returns true if ID matches all constraints
  */
 export function matchesScope(semanticId: string, file: string | null, scopes: string[]): boolean {
+  // No constraints = everything matches (regardless of ID format)
+  if (file === null && scopes.length === 0) return true;
+
+  // Try v2 parsing first
+  const parsedV2 = parseSemanticIdV2(semanticId);
+  if (parsedV2) {
+    // File scope check (v2)
+    if (file !== null) {
+      if (parsedV2.file === file) {
+        // Exact match - OK
+      } else if (parsedV2.file.endsWith('/' + file)) {
+        // Partial path match - OK
+      } else if (basename(parsedV2.file) === file) {
+        // Basename exact match - OK
+      } else {
+        return false;
+      }
+    }
+
+    // Function/class scope check (v2): check namedParent
+    for (const scope of scopes) {
+      if (!parsedV2.namedParent || parsedV2.namedParent.toLowerCase() !== scope.toLowerCase()) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  // Fallback to v1 parsing
   const parsed = parseSemanticId(semanticId);
   if (!parsed) return false;
 
@@ -424,6 +478,17 @@ export function matchesScope(semanticId: string, file: string | null, scopes: st
  * @returns Human-readable scope context or null
  */
 export function extractScopeContext(semanticId: string): string | null {
+  // Try v2 parsing first
+  const parsedV2 = parseSemanticIdV2(semanticId);
+  if (parsedV2) {
+    if (parsedV2.namedParent) {
+      return `inside ${parsedV2.namedParent}`;
+    }
+    // v2 with no parent = top-level
+    return null;
+  }
+
+  // Fallback to v1 parsing
   const parsed = parseSemanticId(semanticId);
   if (!parsed) return null;
 
@@ -475,7 +540,7 @@ function matchesSearchPattern(
   const lowerPattern = pattern.toLowerCase();
 
   // HTTP routes: search method and path
-  if (nodeType === 'http:route') {
+  if (nodeType === HTTP_ROUTE_TYPE) {
     const method = (node.method || '').toLowerCase();
     const path = (node.path || '').toLowerCase();
 
@@ -501,7 +566,7 @@ function matchesSearchPattern(
   }
 
   // HTTP requests: search method and url
-  if (nodeType === 'http:request') {
+  if (nodeType === HTTP_REQUEST_TYPE) {
     const method = (node.method || '').toLowerCase();
     const url = (node.url || '').toLowerCase();
 
@@ -527,13 +592,13 @@ function matchesSearchPattern(
   }
 
   // Socket.IO event channels: search name field (standard)
-  if (nodeType === 'socketio:event') {
+  if (nodeType === SOCKETIO_EVENT_TYPE) {
     const nodeName = (node.name || '').toLowerCase();
     return nodeName.includes(lowerPattern);
   }
 
   // Socket.IO emit/on: search event field
-  if (nodeType === 'socketio:emit' || nodeType === 'socketio:on') {
+  if (nodeType === SOCKETIO_EMIT_TYPE || nodeType === SOCKETIO_ON_TYPE) {
     const eventName = (node.event || '').toLowerCase();
     return eventName.includes(lowerPattern);
   }
@@ -557,19 +622,22 @@ async function findNodes(
     : [
         'FUNCTION',
         'CLASS',
+        'INTERFACE',
+        'TYPE',
+        'ENUM',
         'MODULE',
         'VARIABLE',
         'CONSTANT',
-        'http:route',
-        'http:request',
-        'socketio:event',
-        'socketio:emit',
-        'socketio:on',
-        'PROPERTY_ACCESS'
+        HTTP_ROUTE_TYPE,
+        HTTP_REQUEST_TYPE,
+        SOCKETIO_EVENT_TYPE,
+        SOCKETIO_EMIT_TYPE,
+        SOCKETIO_ON_TYPE,
+        PROPERTY_ACCESS_TYPE,
       ];
 
   for (const nodeType of searchTypes) {
-    for await (const node of backend.queryNodes({ nodeType: nodeType as any })) {
+    for await (const node of backend.queryNodes({ nodeType })) {
       // Type-aware field matching (name)
       const nameMatches = matchesSearchPattern(node, nodeType, query.name);
       if (!nameMatches) continue;
@@ -590,24 +658,24 @@ async function findNodes(
       nodeInfo.scopeContext = extractScopeContext(node.id);
 
       // Include method and path for http:route nodes
-      if (nodeType === 'http:route') {
+      if (nodeType === HTTP_ROUTE_TYPE) {
         nodeInfo.method = node.method as string | undefined;
         nodeInfo.path = node.path as string | undefined;
       }
 
       // Include method and url for http:request nodes
-      if (nodeType === 'http:request') {
+      if (nodeType === HTTP_REQUEST_TYPE) {
         nodeInfo.method = node.method as string | undefined;
         nodeInfo.url = node.url as string | undefined;
       }
 
       // Include event field for Socket.IO nodes
-      if (nodeType === 'socketio:event' || nodeType === 'socketio:emit' || nodeType === 'socketio:on') {
+      if (nodeType === SOCKETIO_EVENT_TYPE || nodeType === SOCKETIO_EMIT_TYPE || nodeType === SOCKETIO_ON_TYPE) {
         nodeInfo.event = node.event as string | undefined;
       }
 
       // Include emit-specific fields
-      if (nodeType === 'socketio:emit') {
+      if (nodeType === SOCKETIO_EMIT_TYPE) {
         nodeInfo.room = node.room as string | undefined;
         nodeInfo.namespace = node.namespace as string | undefined;
         nodeInfo.broadcast = node.broadcast as boolean | undefined;
@@ -615,13 +683,13 @@ async function findNodes(
       }
 
       // Include listener-specific fields
-      if (nodeType === 'socketio:on') {
+      if (nodeType === SOCKETIO_ON_TYPE) {
         nodeInfo.objectName = node.objectName as string | undefined;
         nodeInfo.handlerName = node.handlerName as string | undefined;
       }
 
       // Include plugin-specific fields
-      if (nodeType === 'grafema:plugin') {
+      if (nodeType === GRAFEMA_PLUGIN_TYPE) {
         nodeInfo.phase = node.phase as string | undefined;
         nodeInfo.priority = node.priority as number | undefined;
         nodeInfo.builtin = node.builtin as boolean | undefined;
@@ -631,7 +699,7 @@ async function findNodes(
       }
 
       // Include objectName for PROPERTY_ACCESS nodes (REG-395)
-      if (nodeType === 'PROPERTY_ACCESS') {
+      if (nodeType === PROPERTY_ACCESS_TYPE) {
         nodeInfo.objectName = node.objectName as string | undefined;
       }
 
@@ -741,31 +809,31 @@ async function getCallees(
  */
 async function displayNode(node: NodeInfo, projectPath: string, backend: RFDBServerBackend): Promise<void> {
   // Special formatting for HTTP routes
-  if (node.type === 'http:route' && node.method && node.path) {
+  if (node.type === HTTP_ROUTE_TYPE && node.method && node.path) {
     console.log(formatHttpRouteDisplay(node, projectPath));
     return;
   }
 
   // Special formatting for HTTP requests
-  if (node.type === 'http:request') {
+  if (node.type === HTTP_REQUEST_TYPE) {
     console.log(formatHttpRequestDisplay(node, projectPath));
     return;
   }
 
   // Special formatting for Socket.IO event channels
-  if (node.type === 'socketio:event') {
+  if (node.type === SOCKETIO_EVENT_TYPE) {
     console.log(await formatSocketEventDisplay(node, projectPath, backend));
     return;
   }
 
   // Special formatting for Socket.IO emit/on
-  if (node.type === 'socketio:emit' || node.type === 'socketio:on') {
+  if (node.type === SOCKETIO_EMIT_TYPE || node.type === SOCKETIO_ON_TYPE) {
     console.log(formatSocketIONodeDisplay(node, projectPath));
     return;
   }
 
   // Special formatting for Grafema plugin nodes
-  if (node.type === 'grafema:plugin') {
+  if (node.type === GRAFEMA_PLUGIN_TYPE) {
     console.log(formatPluginDisplay(node, projectPath));
     return;
   }
@@ -793,7 +861,7 @@ function formatHttpRouteDisplay(node: NodeInfo, projectPath: string): string {
 
   // Line 2: Location
   if (node.file) {
-    const relPath = relative(projectPath, node.file);
+    const relPath = toRelativeDisplay(node.file, projectPath);
     const loc = node.line ? `${relPath}:${node.line}` : relPath;
     lines.push(`  Location: ${loc}`);
   }
@@ -818,7 +886,7 @@ function formatHttpRequestDisplay(node: NodeInfo, projectPath: string): string {
 
   // Line 2: Location
   if (node.file) {
-    const relPath = relative(projectPath, node.file);
+    const relPath = toRelativeDisplay(node.file, projectPath);
     const loc = node.line ? `${relPath}:${node.line}` : relPath;
     lines.push(`  Location: ${loc}`);
   }
@@ -905,7 +973,7 @@ function formatSocketIONodeDisplay(node: NodeInfo, projectPath: string): string
   }
 
   // Emit-specific fields
-  if (node.type === 'socketio:emit') {
+  if (node.type === SOCKETIO_EMIT_TYPE) {
     if (node.room) {
       lines.push(`  Room: ${node.room}`);
     }
@@ -918,7 +986,7 @@ function formatSocketIONodeDisplay(node: NodeInfo, projectPath: string): string
   }
 
   // Listener-specific fields
-  if (node.type === 'socketio:on' && node.handlerName) {
+  if (node.type === SOCKETIO_ON_TYPE && node.handlerName) {
     lines.push(`  Handler: ${node.handlerName}`);
   }
 
@@ -959,26 +1027,63 @@ function formatPluginDisplay(node: NodeInfo, projectPath: string): string {
   }
 
   if (node.file) {
-    const relPath = relative(projectPath, node.file);
+    const relPath = toRelativeDisplay(node.file, projectPath);
     lines.push(`  Source: ${relPath}`);
   }
 
   return lines.join('\n');
 }
 
+/** Built-in Datalog predicates supported by RFDB server */
+export const BUILTIN_PREDICATES = new Set([
+  'node', 'type', 'edge', 'incoming', 'path',
+  'attr', 'attr_edge',
+  'neq', 'starts_with', 'not_starts_with',
+]);
+
+/** Extract predicate names from a Datalog query string */
+export function extractPredicates(query: string): string[] {
+  const regex = /\b([a-z_][a-z0-9_]*)\s*\(/g;
+  const predicates = new Set<string>();
+  let match;
+  while ((match = regex.exec(query)) !== null) {
+    predicates.add(match[1]);
+  }
+  return [...predicates];
+}
+
+/** Extract predicate names defined as rule heads (word(...) :-) */
+export function extractRuleHeads(query: string): Set<string> {
+  const regex = /\b([a-z_][a-z0-9_]*)\s*\([^)]*\)\s*:-/g;
+  const heads = new Set<string>();
+  let match;
+  while ((match = regex.exec(query)) !== null) {
+    heads.add(match[1]);
+  }
+  return heads;
+}
+
+/** Find predicates in a query that are not built-in and not user-defined rule heads */
+export function getUnknownPredicates(query: string): string[] {
+  const predicates = extractPredicates(query);
+  const ruleHeads = extractRuleHeads(query);
+  return predicates.filter(p => !BUILTIN_PREDICATES.has(p) && !ruleHeads.has(p));
+}
+
 /**
- * Execute raw Datalog query (backwards compat)
+ * Execute raw Datalog query.
+ * Uses unified executeDatalog endpoint which auto-detects rules vs direct queries.
  */
 async function executeRawQuery(
   backend: RFDBServerBackend,
   query: string,
-  options: QueryOptions
+  limit: number,
+  json?: boolean
 ): Promise<void> {
-  const results = await backend.datalogQuery(query);
-  const limit = parseInt(options.limit, 10);
+  const results = await backend.executeDatalog(query);
   const limited = results.slice(0, limit);
 
-  if (options.json) {
+  if (json) {
     console.log(JSON.stringify(limited, null, 2));
   } else {
     if (limited.length === 0) {
@@ -992,4 +1097,14 @@ async function executeRawQuery(
       }
     }
   }
+
+  // Show warning for unknown predicates (on stderr, works in both text and JSON mode)
+  if (limited.length === 0) {
+    const unknown = getUnknownPredicates(query);
+    if (unknown.length > 0) {
+      const unknownList = unknown.map(p => `'${p}'`).join(', ');
+      const builtinList = [...BUILTIN_PREDICATES].join(', ');
+      console.error(`Note: unknown predicate ${unknownList}. Built-in predicates: ${builtinList}`);
+    }
+  }
 }

package/src/commands/schema.ts

@@ -10,7 +10,8 @@
  */
 
 import { Command } from 'commander';
-import { resolve, join, relative } from 'path';
+import { resolve, join } from 'path';
+import { toRelativeDisplay } from '../utils/pathUtils.js';
 import { existsSync, writeFileSync } from 'fs';
 import {
   RFDBServerBackend,
@@ -82,7 +83,7 @@ function formatInterfaceYaml(schema: InterfaceSchema): string {
 
 function formatInterfaceMarkdown(schema: InterfaceSchema, projectPath: string): string {
   const lines: string[] = [];
-  const relPath = relative(projectPath, schema.source.file);
+  const relPath = toRelativeDisplay(schema.source.file, projectPath);
 
   lines.push(`# Interface: ${schema.name}`);
   lines.push('');

package/src/commands/server.ts

@@ -9,84 +9,28 @@
  */
 
 import { Command } from 'commander';
-import { resolve, join, dirname } from 'path';
+import { resolve, join } from 'path';
 import { existsSync, unlinkSync, writeFileSync, readFileSync } from 'fs';
 import { spawn } from 'child_process';
-import { fileURLToPath } from 'url';
 import { setTimeout as sleep } from 'timers/promises';
-import { RFDBClient, loadConfig, RFDBServerBackend } from '@grafema/core';
+import { RFDBClient, loadConfig, RFDBServerBackend, findRfdbBinary } from '@grafema/core';
 import { exitWithError } from '../utils/errorFormatter.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
 // Extend config type for server settings
 interface ServerConfig {
   binaryPath?: string;
 }
 
 /**
- * Find RFDB server binary in order of preference:
- * 1. Explicit path (from --binary flag or config)
- * 2. Monorepo development (target/release, target/debug)
- * 3. @grafema/rfdb npm package (prebuilt binaries)
- * 4. ~/.local/bin/rfdb-server (user-installed)
+ * Find RFDB server binary using shared utility.
+ * Wraps findRfdbBinary() with CLI-specific error logging.
  */
 function findServerBinary(explicitPath?: string): string | null {
-  // 1. Explicit path from --binary flag or config
-  if (explicitPath) {
-    const resolved = resolve(explicitPath);
-    if (existsSync(resolved)) {
-      return resolved;
-    }
-    // Explicit path specified but not found - this is an error
-    console.error(`Specified binary not found: ${resolved}`);
-    return null;
+  const binaryPath = findRfdbBinary({ explicitPath });
+  if (!binaryPath && explicitPath) {
+    console.error(`Specified binary not found: ${explicitPath}`);
   }
-
-  // 2. Check packages/rfdb-server in monorepo (for development)
-  const projectRoot = join(__dirname, '../../../..');
-  const releaseBinary = join(projectRoot, 'packages/rfdb-server/target/release/rfdb-server');
-  if (existsSync(releaseBinary)) {
-    return releaseBinary;
-  }
-
-  const debugBinary = join(projectRoot, 'packages/rfdb-server/target/debug/rfdb-server');
-  if (existsSync(debugBinary)) {
-    return debugBinary;
-  }
-
-  // 3. Check @grafema/rfdb npm package
-  try {
-    const rfdbPkg = require.resolve('@grafema/rfdb');
-    const rfdbDir = dirname(rfdbPkg);
-    const platform = process.platform;
-    const arch = process.arch;
-
-    let platformDir: string;
-    if (platform === 'darwin') {
-      platformDir = arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
-    } else if (platform === 'linux') {
-      platformDir = arch === 'arm64' ? 'linux-arm64' : 'linux-x64';
-    } else {
-      platformDir = `${platform}-${arch}`;
-    }
-
-    const npmBinary = join(rfdbDir, 'prebuilt', platformDir, 'rfdb-server');
-    if (existsSync(npmBinary)) {
-      return npmBinary;
-    }
-  } catch {
-    // @grafema/rfdb not installed
-  }
-
-  // 4. Check ~/.local/bin (user-installed binary for unsupported platforms)
-  const homeBinary = join(process.env.HOME || '', '.local', 'bin', 'rfdb-server');
-  if (existsSync(homeBinary)) {
-    return homeBinary;
-  }
-
-  return null;
+  return binaryPath;
 }
 
 /**