@grafema/cli 0.3.24 → 0.3.27

package/src/commands/export.ts

@@ -0,0 +1,102 @@
+/**
+ * `grafema export` — emit a multi-format spec from the feature graph
+ * (REG-1116, REG-1118).
+ *
+ * Modes shipped:
+ *   --as openapi-3.1  → http:route features only
+ *   --as docs-md      → all FEATURE categories (single + bulk)
+ *
+ * Phase 2 formats (mcp-schema, asyncapi, json-schema, ts-declarations,
+ * mermaid) plug in by adding renderers to packages/util/src/exporters; the
+ * CLI surface here doesn't change.
+ */
+import { Command } from 'commander';
+import { resolve, join, dirname } from 'path';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+
+import { RFDBServerBackend, RFDBClient, RENDERERS, type ExportBackendLike } from '@grafema/util';
+import { exitWithError } from '../utils/errorFormatter.js';
+import { runExport } from './exportAction.js';
+
+interface ExportCliOptions {
+  feature?: string;
+  as?: string;
+  output?: string;
+  project: string;
+}
+
+const KNOWN_FORMATS = Object.keys(RENDERERS).sort().join(', ');
+
+export const exportCommand = new Command('export')
+  .description('Export FEATURE entries from the graph in a chosen format')
+  .requiredOption('--feature <pattern>', "Feature glob (e.g. 'cli:*', 'http:*', \"cli:command:'analyze'\")")
+  .requiredOption('--as <format>', `Output format (${KNOWN_FORMATS})`)
+  .option('-o, --output <path>', 'Write output to <path> instead of stdout')
+  .option('-p, --project <path>', 'Project path', '.')
+  .addHelpText('after', `
+Examples:
+  grafema export --feature 'http:*' --as openapi-3.1 --output api.yaml
+  grafema export --feature 'cli:*' --as docs-md
+  grafema export --feature "cli:command:'analyze'" --as docs-md
+
+Phase 1 supports two formats: openapi-3.1 (http:route only) and
+docs-md (all categories). Other formats — mcp-schema, asyncapi,
+json-schema, ts-declarations, mermaid — are tracked separately.
+`)
+  .action(async (options: ExportCliOptions) => {
+    if (!options.feature || !options.as) {
+      exitWithError('Both --feature and --as are required', [
+        'See: grafema export --help',
+      ]);
+    }
+    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']);
+    }
+
+    // RFDBServerBackend negotiates protocol v3, which returns semantic edge
+    // dst values that don't resolve via getNode(). Connect with a plain
+    // RFDBClient (protocol v2) so edges preserve raw numeric ids end-to-end.
+    // Still use RFDBServerBackend for its auto-start side effect.
+    const server = new RFDBServerBackend({ dbPath, clientName: 'cli-bootstrap' });
+    await server.connect();
+    const socketPath = (server as unknown as { socketPath: string }).socketPath;
+    const rawClient = new RFDBClient(socketPath, 'export');
+    await rawClient.connect();
+
+    try {
+      await runExport(
+        {
+          feature: options.feature,
+          as: options.as,
+          output: options.output,
+        },
+        {
+          backend: rawClient as unknown as ExportBackendLike,
+          writeText: writeOutput,
+          warn: (msg) => console.error(msg),
+          fail: (msg, code) => {
+            console.error(`✗ ${msg}`);
+            process.exit(code);
+          },
+        },
+      );
+    } finally {
+      rawClient.close();
+      await server.close();
+    }
+  });
+
+/** Default writer: stdout when path == null, otherwise file. */
+function writeOutput(path: string | null, text: string): void {
+  if (path === null) {
+    process.stdout.write(text);
+    return;
+  }
+  const dir = dirname(path);
+  if (dir && !existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, text, 'utf8');
+}

package/src/commands/exportAction.ts

@@ -0,0 +1,107 @@
+/**
+ * `grafema export` action (REG-1116, REG-1118).
+ *
+ * Pure orchestration logic — connects feature glob → renderer, with all I/O
+ * surfaced as inputs (backend) and effects (writeText / log / exit). The
+ * Commander shell in `export.ts` plugs in concrete implementations; tests
+ * supply mocks.
+ */
+import {
+  collectFeatureSnapshots,
+  parseFeaturePattern,
+  resolveCategories,
+  RENDERERS,
+  type ExportBackendLike,
+  type FeatureExportSnapshot,
+  type Renderer,
+} from '@grafema/util';
+
+export interface ExportActionOptions {
+  /** Feature glob — required. */
+  feature: string;
+  /** Output format — required. Must be a key of RENDERERS. */
+  as: string;
+  /** Optional output file path. When unset, stdout. */
+  output?: string;
+}
+
+export interface ExportActionDeps {
+  backend: ExportBackendLike;
+  /** Write file/stdout content. Receives `null` for path → stdout. */
+  writeText: (path: string | null, text: string) => Promise<void> | void;
+  /** Print to stderr (for diagnostic notes that should not contaminate stdout). */
+  warn: (msg: string) => void;
+  /** Reported when an unrecoverable error happens — caller decides exit code. */
+  fail: (msg: string, code: number) => never;
+  /** Renderers map — defaults to the package-shipped RENDERERS. */
+  renderers?: Record<string, Renderer>;
+}
+
+/**
+ * Run the export action. Returns the rendered text on success — convenient
+ * for tests that don't want to mock writeText. The deps' writeText is also
+ * invoked so production callers don't need to handle the return value.
+ */
+export async function runExport(
+  options: ExportActionOptions,
+  deps: ExportActionDeps,
+): Promise<string> {
+  const renderers = deps.renderers ?? RENDERERS;
+  const renderer = renderers[options.as];
+  if (!renderer) {
+    const known = Object.keys(renderers).sort().join(', ');
+    deps.fail(
+      `Unknown format '${options.as}'. Known formats: ${known}.`,
+      2,
+    );
+  }
+
+  const parsed = parseFeaturePattern(options.feature);
+  if (!parsed) {
+    deps.fail(`Invalid --feature pattern: '${options.feature}'.`, 2);
+  }
+
+  // Validate format-category compatibility before doing any graph work.
+  const categories = resolveCategories(parsed.categoryGlob);
+  if (categories.length === 0) {
+    deps.fail(
+      `Feature pattern '${options.feature}' matches no known category.`,
+      2,
+    );
+  }
+  const unsupported = categories.filter(c => !renderer.supports(c));
+  if (unsupported.length > 0 && unsupported.length === categories.length) {
+    deps.fail(
+      `Format '${options.as}' does not support category '${unsupported[0]}'. ` +
+      `Try '--as docs-md' or narrow the pattern.`,
+      2,
+    );
+  }
+
+  const snapshots = await collectFeatureSnapshots(deps.backend, options.feature);
+
+  // If the renderer rejects some categories, drop those snapshots before
+  // rendering. Warn so the user sees the gap.
+  const accepted: FeatureExportSnapshot[] = [];
+  let droppedForCategory = 0;
+  for (const s of snapshots) {
+    if (renderer.supports(s.category)) accepted.push(s);
+    else droppedForCategory++;
+  }
+  if (droppedForCategory > 0) {
+    deps.warn(
+      `Skipping ${droppedForCategory} feature${droppedForCategory === 1 ? '' : 's'} ` +
+      `unsupported by --as ${options.as}.`,
+    );
+  }
+
+  if (accepted.length === 0) {
+    deps.warn(
+      `No features matched '${options.feature}' for format '${options.as}'.`,
+    );
+  }
+
+  const text = renderer.render(accepted);
+  await deps.writeText(options.output ?? null, text);
+  return text;
+}

package/src/commands/features.ts

@@ -0,0 +1,88 @@
+/**
+ * `grafema features` — surface FEATURE-level cross-modality insights.
+ *
+ * Currently exposes one mode:
+ *   --duplicates   List clusters of FEATUREs whose entry-points share an
+ *                  identical BEHAVIOR (same forward-slice hash).
+ *
+ * Other modes (--by-effect, --by-domain, …) are anticipated but not in scope
+ * for REG-1119.
+ */
+
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
+import { RFDBServerBackend } from '@grafema/util';
+import { exitWithError } from '../utils/errorFormatter.js';
+import {
+  findSharedBehaviorClusters,
+  formatSharedBehaviorClusters,
+  type FeaturesBackendLike,
+} from './featuresAction.js';
+
+interface FeaturesCliOptions {
+  project: string;
+  json?: boolean;
+  duplicates?: boolean;
+  minClusterSize?: string;
+  limit?: string;
+}
+
+export const featuresCommand = new Command('features')
+  .description('List FEATURE-level cross-modality insights (e.g. duplicate behaviors)')
+  .option('-p, --project <path>', 'Project path', '.')
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --duplicates', 'List clusters of FEATUREs that share a BEHAVIOR')
+  .option('--min-cluster-size <n>', 'Minimum features per cluster (default: 2)', '2')
+  .option('--limit <n>', 'Maximum clusters to return (default: 100)', '100')
+  .addHelpText('after', `
+Examples:
+  grafema features --duplicates             List FEATUREs with shared behaviors
+  grafema features --duplicates --json      Same, machine-readable JSON
+  grafema features -d --min-cluster-size 3  Only clusters with >=3 features
+`)
+  .action(async (options: FeaturesCliOptions) => {
+    if (!options.duplicates) {
+      exitWithError('No subcommand selected', [
+        'Try: grafema features --duplicates',
+        'See: grafema features --help',
+      ]);
+    }
+
+    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 minClusterSize = parsePositiveInt(options.minClusterSize, 2);
+    const limit = parsePositiveInt(options.limit, 100);
+
+    const backend = new RFDBServerBackend({ dbPath, clientName: 'cli' });
+    await backend.connect();
+
+    try {
+      // RFDBServerBackend matches FeaturesBackendLike at runtime.
+      const clusters = await findSharedBehaviorClusters(
+        backend as unknown as FeaturesBackendLike,
+        { minClusterSize, limit },
+      );
+
+      if (options.json) {
+        console.log(JSON.stringify(clusters, null, 2));
+      } else {
+        console.log(formatSharedBehaviorClusters(clusters));
+      }
+    } finally {
+      await backend.close();
+    }
+  });
+
+function parsePositiveInt(raw: string | undefined, fallback: number): number {
+  if (!raw) return fallback;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) return fallback;
+  return n;
+}

package/src/commands/featuresAction.ts

@@ -0,0 +1,218 @@
+/**
+ * Features command action — surface FEATURE-level cross-modality insights.
+ *
+ * Currently implements --duplicates: groups BEHAVIOR nodes by their
+ * `metadata.hash` and lists every cluster of size >= 2. Each cluster shows the
+ * feature ENTRY_POINTs (incoming `IMPLEMENTED_BY` edges) that share the
+ * implementation.
+ *
+ * Surfaces the data emitted by `behaviorEnricher` Pass 2: SHARES_BEHAVIOR_WITH
+ * edges already exist, but they're not user-facing. This subcommand makes the
+ * insight visible from the CLI ("this CLI command and that MCP tool are thin
+ * wrappers around the same library function").
+ *
+ * REG-1119.
+ */
+import type { EdgeType } from '@grafema/types';
+
+/**
+ * Minimal backend interface — matches the subset of RFDBServerBackend
+ * (and the graph-handlers' GraphBackendLike) that we need. Lets us test with
+ * a simple in-memory mock without requiring a live RFDB server.
+ */
+export interface FeaturesBackendLike {
+  queryNodes(query: { type?: string; nodeType?: string }): AsyncIterable<Record<string, unknown>>;
+  getNode(id: string): Promise<Record<string, unknown> | null>;
+  getIncomingEdges(
+    nodeId: string,
+    edgeTypes?: EdgeType[] | null,
+  ): Promise<Array<{ src: string; dst: string; type: string; metadata?: Record<string, unknown> | undefined }>>;
+}
+
+/** A FEATURE participating in a shared-behavior cluster. */
+export interface SharedFeatureRef {
+  /** Feature semantic id. */
+  id: string;
+  /** Feature node type — e.g. `cli:command`, `mcp:tool`, `vscode:command`. */
+  type: string;
+  /** Feature name (e.g. `analyze`). */
+  name: string;
+  /** Source file (may be empty for synthetic features). */
+  file: string;
+}
+
+/** A group of FEATUREs whose behavior hashes are identical. */
+export interface SharedBehaviorCluster {
+  /** sha256 hash from BEHAVIOR.metadata.hash — the cluster key. */
+  hash: string;
+  /** Effects array carried on the shared BEHAVIOR. */
+  effects: string[];
+  /** Forward-slice size of the shared behavior. */
+  coreNodeCount: number;
+  /** Features that implement the same behavior. */
+  features: SharedFeatureRef[];
+}
+
+export interface FindSharedBehaviorOptions {
+  /** Minimum cluster size to include. Default 2. */
+  minClusterSize?: number;
+  /** Maximum number of clusters to return. Default 100. */
+  limit?: number;
+}
+
+const DEFAULT_MIN_CLUSTER_SIZE = 2;
+const DEFAULT_LIMIT = 100;
+
+/**
+ * Core algorithm — testable, accepts any backend implementing
+ * `FeaturesBackendLike`.
+ *
+ * Steps:
+ * 1. Iterate every BEHAVIOR node, read its `hash` + `effects` + `coreNodeCount`.
+ * 2. Bucket behaviors by hash.
+ * 3. For each bucket of size >= minClusterSize, walk incoming `IMPLEMENTED_BY`
+ *    edges to enumerate the FEATUREs.
+ *
+ * Returns clusters sorted by size (desc), then by hash (asc, deterministic).
+ */
+export async function findSharedBehaviorClusters(
+  backend: FeaturesBackendLike,
+  options: FindSharedBehaviorOptions = {},
+): Promise<SharedBehaviorCluster[]> {
+  const minClusterSize = Math.max(2, options.minClusterSize ?? DEFAULT_MIN_CLUSTER_SIZE);
+  const limit = Math.max(1, options.limit ?? DEFAULT_LIMIT);
+
+  // 1. Collect all BEHAVIOR nodes.
+  interface BehaviorRow {
+    id: string;
+    hash: string;
+    effects: string[];
+    coreNodeCount: number;
+  }
+  const behaviors: BehaviorRow[] = [];
+  for await (const node of backend.queryNodes({ type: 'BEHAVIOR' })) {
+    const id = String(node.id ?? '');
+    if (!id) continue;
+    const hash = readString(node.hash);
+    if (!hash) continue;
+    const effects = readStringArray(node.effects);
+    const coreNodeCount = readNumber(node.coreNodeCount) ?? 0;
+    behaviors.push({ id, hash, effects, coreNodeCount });
+  }
+
+  // 2. Group by hash.
+  const byHash = new Map<string, BehaviorRow[]>();
+  for (const b of behaviors) {
+    let bucket = byHash.get(b.hash);
+    if (!bucket) {
+      bucket = [];
+      byHash.set(b.hash, bucket);
+    }
+    bucket.push(b);
+  }
+
+  // 3. For each multi-behavior bucket, expand incoming IMPLEMENTED_BY edges
+  //    into FEATURE refs.
+  const clusters: SharedBehaviorCluster[] = [];
+  for (const [hash, bucket] of byHash) {
+    if (bucket.length < minClusterSize) continue;
+
+    const features: SharedFeatureRef[] = [];
+    const seenFeatureIds = new Set<string>();
+
+    for (const beh of bucket) {
+      const edges = await backend.getIncomingEdges(beh.id, ['IMPLEMENTED_BY'] as EdgeType[]);
+      for (const edge of edges) {
+        const featureId = String(edge.src);
+        if (!featureId || seenFeatureIds.has(featureId)) continue;
+        seenFeatureIds.add(featureId);
+        const node = await backend.getNode(featureId);
+        if (!node) continue;
+        features.push({
+          id: featureId,
+          type: readString(node.type) ?? 'UNKNOWN',
+          name: readString(node.name) ?? '',
+          file: readString(node.file) ?? '',
+        });
+      }
+    }
+
+    // De-dup may have dropped behaviors back below threshold (e.g. multiple
+    // BEHAVIOR rows from the same FEATURE). Re-check on the resolved feature
+    // count.
+    if (features.length < minClusterSize) continue;
+
+    // Stable order of features within a cluster: by type then name.
+    features.sort((a, b) => (a.type === b.type ? a.name.localeCompare(b.name) : a.type.localeCompare(b.type)));
+
+    // Take effects + coreNodeCount from the first behavior — they're identical
+    // for behaviors with the same hash by construction.
+    clusters.push({
+      hash,
+      effects: bucket[0].effects,
+      coreNodeCount: bucket[0].coreNodeCount,
+      features,
+    });
+  }
+
+  // Sort clusters: largest first, hash ascending for tie-break (deterministic).
+  clusters.sort((a, b) => (b.features.length - a.features.length) || a.hash.localeCompare(b.hash));
+
+  return clusters.slice(0, limit);
+}
+
+/**
+ * Format clusters as a human-readable text report. Mirrors the symmetric MCP
+ * handler output: same field ordering, same labels. JSON output is the same
+ * structured array.
+ */
+export function formatSharedBehaviorClusters(clusters: SharedBehaviorCluster[]): string {
+  if (clusters.length === 0) {
+    return 'No FEATUREs share a BEHAVIOR (each entry-point has a unique implementation).';
+  }
+
+  const lines: string[] = [];
+  lines.push(`Shared-behavior clusters: ${clusters.length}`);
+  lines.push('='.repeat(40));
+  for (let i = 0; i < clusters.length; i++) {
+    const c = clusters[i];
+    lines.push('');
+    lines.push(`Cluster ${i + 1} — ${c.features.length} feature(s) share behavior`);
+    lines.push(`  hash:          ${c.hash.slice(0, 16)}…`);
+    lines.push(`  coreNodeCount: ${c.coreNodeCount}`);
+    lines.push(`  effects:       ${c.effects.length === 0 ? '(none)' : c.effects.join(', ')}`);
+    lines.push('  features:');
+    for (const f of c.features) {
+      const file = f.file ? ` [${f.file}]` : '';
+      lines.push(`    - ${f.type}  ${f.name}${file}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers — defensive parsers tolerating both string-encoded JSON
+// metadata (from raw client) and already-parsed values (from RFDBServerBackend
+// _parseNode).
+// ---------------------------------------------------------------------------
+
+function readString(v: unknown): string | undefined {
+  return typeof v === 'string' ? v : undefined;
+}
+
+function readNumber(v: unknown): number | undefined {
+  return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+
+function readStringArray(v: unknown): string[] {
+  if (Array.isArray(v)) return v.filter((x): x is string => typeof x === 'string');
+  if (typeof v === 'string') {
+    try {
+      const parsed = JSON.parse(v);
+      if (Array.isArray(parsed)) return parsed.filter((x): x is string => typeof x === 'string');
+    } catch {
+      // not JSON
+    }
+  }
+  return [];
+}