@grafema/util 0.3.0-beta

package/src/schema/GraphSchemaExtractor.ts

@@ -0,0 +1,177 @@
+/**
+ * GraphSchemaExtractor - Extracts graph node/edge type schemas
+ *
+ * Usage:
+ *   const extractor = new GraphSchemaExtractor(backend);
+ *   const schema = await extractor.extract();
+ *
+ * When to use:
+ *   - Export graph schema for contract tracking
+ *   - Track node/edge type changes via checksum
+ *   - Generate graph documentation
+ */
+
+import { createHash } from 'crypto';
+import { NODE_TYPE, NAMESPACED_TYPE, EDGE_TYPE } from '@grafema/types';
+import type { RFDBServerBackend } from '../storage/backends/RFDBServerBackend.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface NodeTypeSchema {
+  category: 'base' | 'namespaced';
+  namespace?: string;
+  count: number;
+}
+
+export interface EdgeTypeSchema {
+  count: number;
+}
+
+export interface GraphSchema {
+  $schema: 'grafema-graph-v1';
+  extractedAt: string;
+  nodeTypes: Record<string, NodeTypeSchema>;
+  edgeTypes: Record<string, EdgeTypeSchema>;
+  statistics: {
+    totalNodes: number;
+    totalEdges: number;
+    nodeTypeCount: number;
+    edgeTypeCount: number;
+  };
+  checksum: string;
+}
+
+// ============================================================================
+// Extractor
+// ============================================================================
+
+export interface GraphExtractOptions {
+  /** Include all defined types, not just used ones (default: false) */
+  includeAll?: boolean;
+}
+
+export class GraphSchemaExtractor {
+  constructor(private backend: RFDBServerBackend) {}
+
+  /**
+   * Extract graph schema from current database
+   *
+   * @param options.includeAll - If true, include all defined types even with count=0
+   */
+  async extract(options?: GraphExtractOptions): Promise<GraphSchema> {
+    const includeAll = options?.includeAll ?? false;
+    // Get actual counts from graph
+    const nodeCounts = await this.backend.countNodesByType();
+    const edgeCounts = await this.backend.countEdgesByType();
+
+    // Build node types from definitions + counts
+    const nodeTypes: Record<string, NodeTypeSchema> = {};
+
+    // Base node types
+    for (const [_key, value] of Object.entries(NODE_TYPE)) {
+      nodeTypes[value] = {
+        category: 'base',
+        count: nodeCounts[value] || 0,
+      };
+    }
+
+    // Namespaced node types
+    for (const [_key, value] of Object.entries(NAMESPACED_TYPE)) {
+      const namespace = value.split(':')[0];
+      nodeTypes[value] = {
+        category: 'namespaced',
+        namespace,
+        count: nodeCounts[value] || 0,
+      };
+    }
+
+    // Add any additional types found in the graph but not in definitions
+    for (const [type, count] of Object.entries(nodeCounts)) {
+      if (!nodeTypes[type]) {
+        const namespace = type.includes(':') ? type.split(':')[0] : undefined;
+        nodeTypes[type] = {
+          category: namespace ? 'namespaced' : 'base',
+          namespace,
+          count,
+        };
+      }
+    }
+
+    // Build edge types from definitions + counts
+    const edgeTypes: Record<string, EdgeTypeSchema> = {};
+
+    for (const [_key, value] of Object.entries(EDGE_TYPE)) {
+      edgeTypes[value] = {
+        count: edgeCounts[value] || 0,
+      };
+    }
+
+    // Add any additional edge types found in the graph
+    for (const [type, count] of Object.entries(edgeCounts)) {
+      if (!edgeTypes[type]) {
+        edgeTypes[type] = { count };
+      }
+    }
+
+    // Calculate totals
+    const totalNodes = Object.values(nodeCounts).reduce((sum, n) => sum + n, 0);
+    const totalEdges = Object.values(edgeCounts).reduce((sum, n) => sum + n, 0);
+
+    // Filter out types with count=0 unless includeAll is true
+    const filteredNodeTypes: Record<string, NodeTypeSchema> = {};
+    for (const [type, info] of Object.entries(nodeTypes)) {
+      if (includeAll || info.count > 0) {
+        filteredNodeTypes[type] = info;
+      }
+    }
+
+    const filteredEdgeTypes: Record<string, EdgeTypeSchema> = {};
+    for (const [type, info] of Object.entries(edgeTypes)) {
+      if (includeAll || info.count > 0) {
+        filteredEdgeTypes[type] = info;
+      }
+    }
+
+    // Sort for deterministic output
+    const sortedNodeTypes = this.sortObject(filteredNodeTypes);
+    const sortedEdgeTypes = this.sortObject(filteredEdgeTypes);
+
+    // Compute checksum from normalized content (based on filtered types)
+    const checksumContent = {
+      nodeTypes: Object.keys(sortedNodeTypes).sort(),
+      edgeTypes: Object.keys(sortedEdgeTypes).sort(),
+    };
+
+    const checksum = createHash('sha256')
+      .update(JSON.stringify(checksumContent))
+      .digest('hex');
+
+    return {
+      $schema: 'grafema-graph-v1',
+      extractedAt: new Date().toISOString(),
+      nodeTypes: sortedNodeTypes,
+      edgeTypes: sortedEdgeTypes,
+      statistics: {
+        totalNodes,
+        totalEdges,
+        nodeTypeCount: Object.keys(sortedNodeTypes).length,
+        edgeTypeCount: Object.keys(sortedEdgeTypes).length,
+      },
+      checksum: `sha256:${checksum}`,
+    };
+  }
+
+  /**
+   * Sort object keys alphabetically for deterministic output
+   */
+  private sortObject<T>(obj: Record<string, T>): Record<string, T> {
+    const sorted: Record<string, T> = {};
+    const keys = Object.keys(obj).sort();
+    for (const key of keys) {
+      sorted[key] = obj[key];
+    }
+    return sorted;
+  }
+}

package/src/schema/InterfaceSchemaExtractor.ts

@@ -0,0 +1,173 @@
+/**
+ * InterfaceSchemaExtractor - Extracts interface schemas from graph
+ *
+ * Usage:
+ *   const extractor = new InterfaceSchemaExtractor(backend);
+ *   const schema = await extractor.extract('ConfigSchema');
+ *
+ * When to use:
+ *   - Export interface contracts for documentation
+ *   - Track interface changes via checksum
+ *   - Generate API documentation from graph
+ */
+
+import { createHash } from 'crypto';
+import type { RFDBServerBackend } from '../storage/backends/RFDBServerBackend.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PropertySchema {
+  type: string;
+  required: boolean;
+  readonly: boolean;
+}
+
+export interface InterfaceSchema {
+  $schema: 'grafema-interface-v1';
+  name: string;
+  source: {
+    file: string;
+    line: number;
+    column: number;
+  };
+  typeParameters?: string[];
+  properties: Record<string, PropertySchema>;
+  extends: string[];
+  checksum: string;
+}
+
+export interface ExtractOptions {
+  /** Specific file path if multiple interfaces have same name */
+  file?: string;
+}
+
+export interface InterfaceNodeRecord {
+  id: string;
+  type: 'INTERFACE';
+  name: string;
+  file: string;
+  line: number;
+  column: number;
+  extends: string[];
+  properties: Array<{
+    name: string;
+    type?: string;
+    optional?: boolean;
+    readonly?: boolean;
+  }>;
+  typeParameters?: string[];
+}
+
+// ============================================================================
+// Extractor
+// ============================================================================
+
+export class InterfaceSchemaExtractor {
+  constructor(private backend: RFDBServerBackend) {}
+
+  /**
+   * Extract schema for interface by name
+   *
+   * @param interfaceName - Name of the interface (e.g., 'ConfigSchema')
+   * @param options - Optional filters
+   * @returns InterfaceSchema or null if not found
+   * @throws Error if multiple interfaces match and no file specified
+   */
+  async extract(interfaceName: string, options?: ExtractOptions): Promise<InterfaceSchema | null> {
+    const interfaces = await this.findInterfaces(interfaceName);
+
+    if (interfaces.length === 0) {
+      return null;
+    }
+
+    // Filter by file if specified
+    let match: InterfaceNodeRecord;
+    if (options?.file) {
+      const fileFilter = options.file;
+      const filtered = interfaces.filter(i => i.file === fileFilter || i.file.endsWith(fileFilter));
+      if (filtered.length === 0) {
+        return null;
+      }
+      match = filtered[0];
+    } else if (interfaces.length > 1) {
+      const locations = interfaces.map(i => `  - ${i.file}:${i.line}`).join('\n');
+      throw new Error(
+        `Multiple interfaces named "${interfaceName}" found:\n${locations}\n` +
+        `Use --file option to specify which one.`
+      );
+    } else {
+      match = interfaces[0];
+    }
+
+    return this.buildSchema(match);
+  }
+
+  /**
+   * Find all interfaces with given name
+   */
+  async findInterfaces(name: string): Promise<InterfaceNodeRecord[]> {
+    const result: InterfaceNodeRecord[] = [];
+
+    for await (const node of this.backend.queryNodes({ nodeType: 'INTERFACE' })) {
+      if (node.name === name) {
+        result.push(node as unknown as InterfaceNodeRecord);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Build InterfaceSchema from node record
+   */
+  private buildSchema(node: InterfaceNodeRecord): InterfaceSchema {
+    // Sort properties alphabetically for deterministic output
+    const sortedProperties = [...(node.properties || [])].sort((a, b) =>
+      a.name.localeCompare(b.name)
+    );
+
+    const properties: Record<string, PropertySchema> = {};
+    for (const prop of sortedProperties) {
+      properties[prop.name] = {
+        type: prop.type || 'unknown',
+        required: !prop.optional,
+        readonly: prop.readonly || false
+      };
+    }
+
+    // Compute checksum from normalized content
+    const checksumContent = {
+      name: node.name,
+      properties: sortedProperties.map(p => ({
+        name: p.name,
+        type: p.type,
+        optional: p.optional,
+        readonly: p.readonly
+      })),
+      extends: [...(node.extends || [])].sort(),
+      typeParameters: node.typeParameters
+    };
+
+    const checksum = createHash('sha256')
+      .update(JSON.stringify(checksumContent))
+      .digest('hex');
+
+    return {
+      $schema: 'grafema-interface-v1',
+      name: node.name,
+      source: {
+        file: node.file,
+        line: node.line,
+        column: node.column
+      },
+      ...(node.typeParameters && node.typeParameters.length > 0 && {
+        typeParameters: node.typeParameters
+      }),
+      properties,
+      extends: node.extends || [],
+      checksum: `sha256:${checksum}`
+    };
+  }
+}

package/src/schema/index.ts

@@ -0,0 +1,5 @@
+export { InterfaceSchemaExtractor } from './InterfaceSchemaExtractor.js';
+export type { InterfaceSchema, PropertySchema, ExtractOptions } from './InterfaceSchemaExtractor.js';
+
+export { GraphSchemaExtractor } from './GraphSchemaExtractor.js';
+export type { GraphSchema, NodeTypeSchema, EdgeTypeSchema, GraphExtractOptions } from './GraphSchemaExtractor.js';