@grafema/api 0.2.5-beta

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@grafema/api",
+  "version": "0.2.5-beta",
+  "description": "GraphQL API server for Grafema code analysis toolkit",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "grafema",
+    "graphql",
+    "api",
+    "code-analysis"
+  ],
+  "license": "Apache-2.0",
+  "author": "Vadim Reshetnikov",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Disentinel/grafema.git",
+    "directory": "packages/api"
+  },
+  "dependencies": {
+    "dataloader": "^2.2.3",
+    "graphql": "^16.10.0",
+    "graphql-scalars": "^1.24.0",
+    "graphql-yoga": "^5.10.11",
+    "@grafema/core": "0.2.5-beta",
+    "@grafema/types": "0.2.5-beta"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc && pnpm run copy-schema",
+    "copy-schema": "mkdir -p dist/schema && cp src/schema/*.graphql dist/schema/",
+    "clean": "rm -rf dist",
+    "test": "node --import tsx --test test/*.test.ts",
+    "test:watch": "node --import tsx --test --watch test/*.test.ts"
+  }
+}

package/src/context.ts

@@ -0,0 +1,33 @@
+/**
+ * GraphQL Context
+ *
+ * Request-scoped context containing backend connection and DataLoaders.
+ */
+
+import type { IncomingMessage } from 'node:http';
+import type { RFDBServerBackend } from '@grafema/core';
+import { createDataLoaders, type DataLoaders } from './dataloaders/index.js';
+
+export interface GraphQLContext {
+  /** Graph backend connection */
+  backend: RFDBServerBackend;
+  /** DataLoaders for batching (per-request) */
+  loaders: DataLoaders;
+  /** Request start time for timeout tracking */
+  startTime: number;
+}
+
+/**
+ * Create context for a GraphQL request.
+ * Creates fresh DataLoaders to ensure no cross-request caching.
+ */
+export function createContext(
+  backend: RFDBServerBackend,
+  _req: IncomingMessage
+): GraphQLContext {
+  return {
+    backend,
+    loaders: createDataLoaders(backend),
+    startTime: Date.now(),
+  };
+}

package/src/dataloaders/index.ts

@@ -0,0 +1,24 @@
+/**
+ * DataLoader Factory
+ *
+ * Creates all DataLoaders for a request context.
+ * DataLoaders batch and cache database requests within a single GraphQL request.
+ */
+
+import type { RFDBServerBackend } from '@grafema/core';
+import { createNodeLoader } from './nodeLoader.js';
+
+export interface DataLoaders {
+  /** Batch node lookups by ID */
+  node: ReturnType<typeof createNodeLoader>;
+}
+
+/**
+ * Create all DataLoaders for a request.
+ * DataLoaders are per-request to prevent cross-request caching issues.
+ */
+export function createDataLoaders(backend: RFDBServerBackend): DataLoaders {
+  return {
+    node: createNodeLoader(backend),
+  };
+}

package/src/dataloaders/nodeLoader.ts

@@ -0,0 +1,41 @@
+/**
+ * Node DataLoader
+ *
+ * Batches multiple getNode() calls into efficient parallel lookups.
+ * Critical for preventing N+1 queries in GraphQL.
+ */
+
+import DataLoader from 'dataloader';
+import type { BaseNodeRecord } from '@grafema/types';
+import type { RFDBServerBackend } from '@grafema/core';
+
+/**
+ * Create a DataLoader for batching node lookups.
+ *
+ * The loader batches all node ID requests made within a single tick
+ * and resolves them with parallel backend calls.
+ *
+ * Complexity: O(n) where n = unique node IDs requested
+ */
+export function createNodeLoader(
+  backend: RFDBServerBackend
+): DataLoader<string, BaseNodeRecord | null> {
+  return new DataLoader<string, BaseNodeRecord | null>(
+    async (ids: readonly string[]) => {
+      // Parallelize individual lookups
+      // Future optimization: add batch getNodes() to RFDB protocol
+      const results = await Promise.all(
+        ids.map((id) => backend.getNode(id).catch(() => null))
+      );
+      return results;
+    },
+    {
+      // Cache results within this request
+      cache: true,
+      // Use identity function for cache key
+      cacheKeyFn: (id) => id,
+      // Max batch size to prevent overwhelming backend
+      maxBatchSize: 100,
+    }
+  );
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @grafema/api - GraphQL API for Grafema code graph
+ *
+ * Provides a GraphQL endpoint for querying the code graph.
+ * Supports cursor-based pagination, subscriptions for streaming,
+ * and Datalog query passthrough.
+ */
+
+export { createGraphQLServer, startServer } from './server.js';
+export type { GraphQLServerOptions } from './server.js';
+export type { GraphQLContext } from './context.js';

package/src/pagination.ts

@@ -0,0 +1,109 @@
+/**
+ * Cursor-based Pagination Utilities
+ *
+ * Implements Relay Connection spec for cursor-based pagination.
+ */
+
+/**
+ * Encode a cursor from an ID.
+ * Format: base64("cursor:${id}")
+ */
+export function encodeCursor(id: string): string {
+  return Buffer.from(`cursor:${id}`).toString('base64');
+}
+
+/**
+ * Decode a cursor to get the ID.
+ * Returns null if cursor is invalid.
+ */
+export function decodeCursor(cursor: string): string | null {
+  try {
+    const decoded = Buffer.from(cursor, 'base64').toString('utf-8');
+    if (decoded.startsWith('cursor:')) {
+      return decoded.slice(7);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * PageInfo structure per Relay spec.
+ */
+export interface PageInfo {
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+  startCursor: string | null;
+  endCursor: string | null;
+}
+
+/**
+ * Edge structure for connections.
+ */
+export interface Edge<T> {
+  node: T;
+  cursor: string;
+}
+
+/**
+ * Connection structure per Relay spec.
+ */
+export interface Connection<T> {
+  edges: Edge<T>[];
+  pageInfo: PageInfo;
+  totalCount: number;
+}
+
+/**
+ * Apply cursor-based pagination to an array.
+ *
+ * @param items - All items (already filtered)
+ * @param first - Number of items to return (default: 50, max: 250)
+ * @param after - Cursor to start after
+ * @param getId - Function to get ID from item for cursor encoding
+ * @returns Connection structure
+ */
+export function paginateArray<T>(
+  items: T[],
+  first: number | null | undefined,
+  after: string | null | undefined,
+  getId: (item: T) => string
+): Connection<T> {
+  const limit = Math.min(first ?? 50, 250);
+
+  // Find start index based on cursor
+  let startIndex = 0;
+  if (after) {
+    const afterId = decodeCursor(after);
+    if (afterId) {
+      const afterIndex = items.findIndex((item) => getId(item) === afterId);
+      if (afterIndex !== -1) {
+        startIndex = afterIndex + 1;
+      }
+    }
+  }
+
+  // Slice items
+  const slicedItems = items.slice(startIndex, startIndex + limit);
+
+  // Build edges
+  const edges: Edge<T>[] = slicedItems.map((item) => ({
+    node: item,
+    cursor: encodeCursor(getId(item)),
+  }));
+
+  // Build pageInfo
+  const pageInfo: PageInfo = {
+    hasNextPage: startIndex + limit < items.length,
+    hasPreviousPage: startIndex > 0,
+    startCursor: edges.length > 0 ? edges[0].cursor : null,
+    endCursor: edges.length > 0 ? edges[edges.length - 1].cursor : null,
+  };
+
+  return {
+    edges,
+    pageInfo,
+    totalCount: items.length,
+  };
+}

package/src/resolvers/edge.ts

@@ -0,0 +1,39 @@
+/**
+ * Edge Type Resolvers
+ *
+ * Resolves fields on Edge type that require lookups.
+ */
+
+import type { EdgeRecord } from '@grafema/types';
+import type { GraphQLContext } from '../context.js';
+
+export const edgeResolvers = {
+  /**
+   * Resolve source node.
+   */
+  async src(parent: EdgeRecord, _args: unknown, context: GraphQLContext) {
+    return context.loaders.node.load(parent.src);
+  },
+
+  /**
+   * Resolve destination node.
+   */
+  async dst(parent: EdgeRecord, _args: unknown, context: GraphQLContext) {
+    return context.loaders.node.load(parent.dst);
+  },
+
+  /**
+   * Resolve metadata field.
+   */
+  metadata(parent: EdgeRecord) {
+    if (!parent.metadata) return null;
+    if (typeof parent.metadata === 'string') {
+      try {
+        return JSON.parse(parent.metadata);
+      } catch {
+        return null;
+      }
+    }
+    return parent.metadata;
+  },
+};

package/src/resolvers/index.ts

@@ -0,0 +1,24 @@
+/**
+ * GraphQL Resolver Map
+ *
+ * Combines all resolvers and adds custom scalar handlers.
+ */
+
+import { JSONResolver } from 'graphql-scalars';
+import { nodeResolvers } from './node.js';
+import { edgeResolvers } from './edge.js';
+import { queryResolvers } from './query.js';
+import { mutationResolvers } from './mutation.js';
+
+export const resolvers = {
+  // Custom scalars
+  JSON: JSONResolver,
+
+  // Type resolvers
+  Node: nodeResolvers,
+  Edge: edgeResolvers,
+
+  // Root resolvers
+  Query: queryResolvers,
+  Mutation: mutationResolvers,
+};

package/src/resolvers/mutation.ts

@@ -0,0 +1,108 @@
+/**
+ * Mutation Resolvers
+ *
+ * Implements all Mutation type fields.
+ */
+
+import type { GraphQLContext } from '../context.js';
+
+export const mutationResolvers = {
+  /**
+   * Run project analysis.
+   * Placeholder - would integrate with Orchestrator.
+   */
+  async analyzeProject(
+    _: unknown,
+    _args: { service?: string | null; force?: boolean | null },
+    _context: GraphQLContext
+  ) {
+    // Placeholder - would integrate with Orchestrator
+    return {
+      success: false,
+      status: {
+        running: false,
+        phase: null,
+        message: 'Analysis via GraphQL not yet implemented',
+        servicesDiscovered: 0,
+        servicesAnalyzed: 0,
+        error: 'Not implemented',
+      },
+    };
+  },
+
+  /**
+   * Create a new guarantee.
+   * Placeholder - would integrate with GuaranteeManager.
+   */
+  async createGuarantee(
+    _: unknown,
+    _args: { input: Record<string, unknown> },
+    _context: GraphQLContext
+  ) {
+    throw new Error('createGuarantee not yet implemented');
+  },
+
+  /**
+   * Delete a guarantee.
+   * Placeholder.
+   */
+  async deleteGuarantee(
+    _: unknown,
+    _args: { name: string },
+    _context: GraphQLContext
+  ) {
+    throw new Error('deleteGuarantee not yet implemented');
+  },
+
+  /**
+   * Check guarantees.
+   * Placeholder.
+   */
+  async checkGuarantees(
+    _: unknown,
+    _args: { names?: string[] | null },
+    _context: GraphQLContext
+  ) {
+    return {
+      total: 0,
+      passed: 0,
+      failed: 0,
+      results: [],
+    };
+  },
+
+  /**
+   * Check ad-hoc invariant.
+   */
+  async checkInvariant(
+    _: unknown,
+    args: { rule: string; description?: string | null },
+    context: GraphQLContext
+  ) {
+    try {
+      const results = await context.backend.checkGuarantee(args.rule);
+      const passed = results.length === 0;
+
+      return {
+        guaranteeId: 'adhoc',
+        passed,
+        violationCount: results.length,
+        violations: results.slice(0, 10).map((_r) => {
+          // Would need async resolution to populate node data
+          return {
+            node: null,
+            file: null,
+            line: null,
+          };
+        }),
+      };
+    } catch {
+      return {
+        guaranteeId: 'adhoc',
+        passed: false,
+        violationCount: 0,
+        violations: [],
+      };
+    }
+  },
+};

package/src/resolvers/node.ts

@@ -0,0 +1,118 @@
+/**
+ * Node Type Resolvers
+ *
+ * Resolves relationship fields on Node type.
+ */
+
+import type { BaseNodeRecord, EdgeRecord } from '@grafema/types';
+import type { GraphQLContext } from '../context.js';
+import { paginateArray } from '../pagination.js';
+
+export const nodeResolvers = {
+  /**
+   * Resolve outgoing edges with cursor-based pagination.
+   *
+   * Complexity: O(k) where k = number of outgoing edges from this node
+   */
+  async outgoingEdges(
+    parent: BaseNodeRecord,
+    args: { types?: string[] | null; first?: number | null; after?: string | null },
+    context: GraphQLContext
+  ) {
+    const edges = await context.backend.getOutgoingEdges(
+      parent.id,
+      args.types || null
+    );
+
+    return paginateArray(
+      edges,
+      args.first,
+      args.after,
+      (e: EdgeRecord) => `${e.src}:${e.dst}:${e.type}`
+    );
+  },
+
+  /**
+   * Resolve incoming edges with cursor-based pagination.
+   *
+   * Complexity: O(k) where k = number of incoming edges to this node
+   */
+  async incomingEdges(
+    parent: BaseNodeRecord,
+    args: { types?: string[] | null; first?: number | null; after?: string | null },
+    context: GraphQLContext
+  ) {
+    const edges = await context.backend.getIncomingEdges(
+      parent.id,
+      args.types || null
+    );
+
+    return paginateArray(
+      edges,
+      args.first,
+      args.after,
+      (e: EdgeRecord) => `${e.src}:${e.dst}:${e.type}`
+    );
+  },
+
+  /**
+   * Resolve child nodes (via CONTAINS edges) with cursor-based pagination.
+   *
+   * Complexity: O(c) where c = number of children
+   */
+  async children(
+    parent: BaseNodeRecord,
+    args: { first?: number | null; after?: string | null },
+    context: GraphQLContext
+  ) {
+    const edges = await context.backend.getOutgoingEdges(parent.id, ['CONTAINS']);
+
+    // Use DataLoader to batch child node lookups
+    const childIds = edges.map((e) => e.dst);
+    const children = await context.loaders.node.loadMany(childIds);
+
+    // Filter out errors and nulls
+    const validChildren = children.filter(
+      (c): c is BaseNodeRecord => c != null && !(c instanceof Error)
+    );
+
+    return paginateArray(
+      validChildren,
+      args.first,
+      args.after,
+      (n: BaseNodeRecord) => n.id
+    );
+  },
+
+  /**
+   * Resolve parent node (via incoming CONTAINS edge).
+   *
+   * Complexity: O(1) - single lookup
+   */
+  async parent(
+    parent: BaseNodeRecord,
+    _args: unknown,
+    context: GraphQLContext
+  ) {
+    const edges = await context.backend.getIncomingEdges(parent.id, ['CONTAINS']);
+    if (edges.length === 0) return null;
+
+    return context.loaders.node.load(edges[0].src);
+  },
+
+  /**
+   * Resolve metadata field.
+   * Parses JSON string if needed.
+   */
+  metadata(parent: BaseNodeRecord) {
+    if (!parent.metadata) return null;
+    if (typeof parent.metadata === 'string') {
+      try {
+        return JSON.parse(parent.metadata);
+      } catch {
+        return null;
+      }
+    }
+    return parent.metadata;
+  },
+};