@grafema/api 0.2.5-beta

package/src/resolvers/query.ts

@@ -0,0 +1,307 @@
+/**
+ * Query Resolvers
+ *
+ * Implements all Query type fields.
+ */
+
+import type { BaseNodeRecord } from '@grafema/types';
+import type { GraphQLContext } from '../context.js';
+import { paginateArray } from '../pagination.js';
+
+export interface NodeFilter {
+  type?: string | null;
+  name?: string | null;
+  file?: string | null;
+  exported?: boolean | null;
+}
+
+export const queryResolvers = {
+  /**
+   * Get node by ID.
+   *
+   * Complexity: O(1)
+   */
+  async node(
+    _: unknown,
+    args: { id: string },
+    context: GraphQLContext
+  ) {
+    return context.loaders.node.load(args.id);
+  },
+
+  /**
+   * Find nodes matching criteria with cursor-based pagination.
+   *
+   * Complexity: O(n) where n = nodes matching type filter
+   * This is acceptable because:
+   * - We filter by type first (uses RFDB's type index)
+   * - Results are paginated
+   */
+  async nodes(
+    _: unknown,
+    args: {
+      filter?: NodeFilter | null;
+      first?: number | null;
+      after?: string | null;
+    },
+    context: GraphQLContext
+  ) {
+    const filter = args.filter || {};
+
+    // Build query for backend
+    const query: Record<string, unknown> = {};
+    if (filter.type) query.type = filter.type;
+    if (filter.name) query.name = filter.name;
+    if (filter.file) query.file = filter.file;
+
+    // Get all matching nodes
+    const nodes = await context.backend.getAllNodes(query);
+
+    // Apply exported filter (not supported by backend query)
+    let filteredNodes = nodes;
+    if (filter.exported !== null && filter.exported !== undefined) {
+      filteredNodes = nodes.filter((n) => n.exported === filter.exported);
+    }
+
+    return paginateArray(
+      filteredNodes,
+      args.first,
+      args.after,
+      (n: BaseNodeRecord) => n.id
+    );
+  },
+
+  /**
+   * BFS traversal.
+   *
+   * Complexity: O(V + E) for reachable subgraph
+   * Bounded by maxDepth parameter.
+   */
+  async bfs(
+    _: unknown,
+    args: { startIds: string[]; maxDepth: number; edgeTypes: string[] },
+    context: GraphQLContext
+  ) {
+    return context.backend.bfs(args.startIds, args.maxDepth, args.edgeTypes);
+  },
+
+  /**
+   * DFS traversal.
+   *
+   * Complexity: O(V + E) for reachable subgraph
+   */
+  async dfs(
+    _: unknown,
+    args: { startIds: string[]; maxDepth: number; edgeTypes?: string[] | null },
+    context: GraphQLContext
+  ) {
+    return context.backend.dfs(
+      args.startIds,
+      args.maxDepth,
+      args.edgeTypes || []
+    );
+  },
+
+  /**
+   * Reachability check.
+   *
+   * Complexity: O(V + E) worst case, often O(d) with early termination
+   */
+  async reachability(
+    _: unknown,
+    args: {
+      from: string;
+      to: string;
+      edgeTypes?: string[] | null;
+      maxDepth?: number | null;
+    },
+    context: GraphQLContext
+  ) {
+    const maxDepth = args.maxDepth ?? 10;
+    const reachable = await context.backend.bfs(
+      [args.from],
+      maxDepth,
+      args.edgeTypes || []
+    );
+    return reachable.includes(args.to);
+  },
+
+  /**
+   * Execute Datalog query.
+   *
+   * Complexity: Depends on query, bounded by RFDB's timeout
+   */
+  async datalog(
+    _: unknown,
+    args: { query: string; limit?: number | null; offset?: number | null },
+    context: GraphQLContext
+  ) {
+    const limit = args.limit ?? 50;
+    const offset = args.offset ?? 0;
+
+    try {
+      const results = await context.backend.checkGuarantee(args.query);
+      const total = results.length;
+      const paginatedResults = results.slice(offset, offset + limit);
+
+      // Enrich with node data
+      const enrichedResults = await Promise.all(
+        paginatedResults.map(async (r) => {
+          const bindings = r.bindings || [];
+          const xBinding = bindings.find((b) => b.name === 'X');
+          const nodeId = xBinding?.value;
+          const node = nodeId
+            ? await context.loaders.node.load(String(nodeId))
+            : null;
+          return {
+            bindings: Object.fromEntries(
+              bindings.map((b) => [b.name, b.value])
+            ),
+            node,
+          };
+        })
+      );
+
+      return {
+        success: true,
+        count: total,
+        results: enrichedResults,
+        error: null,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        success: false,
+        count: 0,
+        results: [],
+        error: message,
+      };
+    }
+  },
+
+  /**
+   * Get graph statistics.
+   *
+   * Complexity: O(1) - cached in backend
+   */
+  async stats(_: unknown, _args: unknown, context: GraphQLContext) {
+    return context.backend.getStats();
+  },
+
+  /**
+   * Get analysis status.
+   * Placeholder - actual implementation depends on analysis state tracking.
+   */
+  async analysisStatus(_: unknown, _args: unknown, _context: GraphQLContext) {
+    // Placeholder - would need to track analysis state
+    return {
+      running: false,
+      phase: null,
+      message: null,
+      servicesDiscovered: 0,
+      servicesAnalyzed: 0,
+      error: null,
+    };
+  },
+
+  /**
+   * List all guarantees.
+   * Placeholder - actual implementation depends on GuaranteeManager.
+   */
+  async guarantees(_: unknown, _args: unknown, _context: GraphQLContext) {
+    // Placeholder - would need GuaranteeManager integration
+    return [];
+  },
+
+  /**
+   * Get guarantee by ID.
+   * Placeholder.
+   */
+  async guarantee(
+    _: unknown,
+    _args: { id: string },
+    _context: GraphQLContext
+  ) {
+    return null;
+  },
+
+  /**
+   * Find calls to a function/method.
+   * Placeholder - would reuse MCP handler logic.
+   */
+  async findCalls(
+    _: unknown,
+    _args: {
+      target: string;
+      className?: string | null;
+      limit?: number | null;
+      offset?: number | null;
+    },
+    _context: GraphQLContext
+  ) {
+    // Placeholder - would reuse MCP find_calls handler
+    return [];
+  },
+
+  /**
+   * Get function details.
+   * Placeholder - would reuse MCP handler logic.
+   */
+  async getFunctionDetails(
+    _: unknown,
+    _args: {
+      name: string;
+      file?: string | null;
+      transitive?: boolean | null;
+    },
+    _context: GraphQLContext
+  ) {
+    // Placeholder - would reuse MCP get_function_details handler
+    return null;
+  },
+
+  /**
+   * Find guards protecting a node.
+   * Placeholder.
+   */
+  async findGuards(
+    _: unknown,
+    _args: { nodeId: string },
+    _context: GraphQLContext
+  ) {
+    return [];
+  },
+
+  /**
+   * Trace alias chain.
+   * Placeholder.
+   */
+  async traceAlias(
+    _: unknown,
+    _args: {
+      variableName: string;
+      file: string;
+      maxDepth?: number | null;
+    },
+    _context: GraphQLContext
+  ) {
+    return [];
+  },
+
+  /**
+   * Trace data flow.
+   * Placeholder.
+   */
+  async traceDataFlow(
+    _: unknown,
+    _args: {
+      source: string;
+      file?: string | null;
+      direction?: string | null;
+      maxDepth?: number | null;
+    },
+    _context: GraphQLContext
+  ) {
+    return [];
+  },
+};

package/src/schema/enums.graphql

@@ -0,0 +1,27 @@
+"""
+Direction for graph traversal.
+"""
+enum TraversalDirection {
+  FORWARD
+  BACKWARD
+  BOTH
+}
+
+"""
+Severity levels for guarantees.
+"""
+enum Severity {
+  ERROR
+  WARNING
+  INFO
+}
+
+"""
+Priority levels for contract guarantees.
+"""
+enum Priority {
+  CRITICAL
+  IMPORTANT
+  OBSERVED
+  TRACKED
+}

package/src/schema/mutations.graphql

@@ -0,0 +1,53 @@
+type Mutation {
+  # ============================================================================
+  # Analysis
+  # ============================================================================
+
+  """
+  Run project analysis.
+  Blocks until complete (with timeout).
+  """
+  analyzeProject(
+    """Optional: analyze only this service"""
+    service: String
+
+    """Force re-analysis even if already analyzed"""
+    force: Boolean
+  ): AnalysisResult!
+
+  # ============================================================================
+  # Guarantees
+  # ============================================================================
+
+  """
+  Create a new guarantee.
+
+  For Datalog-based: provide name + rule
+  For contract-based: provide name + type + priority
+  """
+  createGuarantee(input: CreateGuaranteeInput!): Guarantee!
+
+  """
+  Delete a guarantee by name.
+  """
+  deleteGuarantee(name: String!): Boolean!
+
+  """
+  Check all guarantees or specific ones.
+  """
+  checkGuarantees(
+    """Specific guarantee names to check (null = all)"""
+    names: [String!]
+  ): GuaranteeCheckResult!
+
+  """
+  Check a single ad-hoc invariant without persisting.
+  """
+  checkInvariant(
+    """Datalog rule"""
+    rule: String!
+
+    """Description for error messages"""
+    description: String
+  ): GuaranteeResult!
+}

package/src/schema/queries.graphql

@@ -0,0 +1,213 @@
+type Query {
+  # ============================================================================
+  # Node Lookups
+  # ============================================================================
+
+  """
+  Get a single node by ID.
+  Returns null if not found.
+  """
+  node(id: ID!): Node
+
+  """
+  Find nodes matching filter criteria.
+  Uses cursor-based pagination (Relay spec).
+  """
+  nodes(
+    """Filter criteria"""
+    filter: NodeFilter
+
+    """Number of items to return (default: 50, max: 250)"""
+    first: Int
+
+    """Cursor to start after"""
+    after: String
+  ): NodeConnection!
+
+  # ============================================================================
+  # Graph Traversal
+  # ============================================================================
+
+  """
+  BFS traversal from starting nodes.
+  Returns all node IDs reachable within maxDepth.
+
+  Complexity: O(V + E) where V = reachable nodes, E = traversed edges
+  """
+  bfs(
+    """Starting node IDs"""
+    startIds: [ID!]!
+
+    """Maximum traversal depth"""
+    maxDepth: Int!
+
+    """Edge types to traverse (empty = all)"""
+    edgeTypes: [String!]!
+  ): [ID!]!
+
+  """
+  DFS traversal from starting nodes.
+  Returns all node IDs reachable within maxDepth.
+
+  Complexity: O(V + E) where V = reachable nodes, E = traversed edges
+  """
+  dfs(
+    """Starting node IDs"""
+    startIds: [ID!]!
+
+    """Maximum traversal depth"""
+    maxDepth: Int!
+
+    """Edge types to traverse (null = all)"""
+    edgeTypes: [String!]
+  ): [ID!]!
+
+  """
+  Check if a path exists between two nodes.
+  Uses BFS internally with early termination.
+
+  Complexity: O(V + E) worst case, often much faster with early termination
+  """
+  reachability(
+    """Source node ID"""
+    from: ID!
+
+    """Target node ID"""
+    to: ID!
+
+    """Edge types to traverse (null = all)"""
+    edgeTypes: [String!]
+
+    """Maximum depth to search (default: 10)"""
+    maxDepth: Int
+  ): Boolean!
+
+  # ============================================================================
+  # Datalog Queries
+  # ============================================================================
+
+  """
+  Execute a Datalog query on the code graph.
+
+  The query must define a violation/1 predicate.
+
+  Available predicates:
+  - node(Id, Type) - match nodes by type
+  - edge(Src, Dst, Type) - match edges
+  - attr(Id, Name, Value) - match node attributes
+
+  Example: violation(X) :- node(X, "FUNCTION"), attr(X, "async", true).
+  """
+  datalog(
+    """Datalog query defining violation/1"""
+    query: String!
+
+    """Maximum results (default: 50)"""
+    limit: Int
+
+    """Results to skip (for simple pagination)"""
+    offset: Int
+  ): DatalogResult!
+
+  # ============================================================================
+  # High-Level Queries (from MCP handlers)
+  # ============================================================================
+
+  """
+  Find all calls to a function/method.
+  """
+  findCalls(
+    """Function or method name"""
+    target: String!
+
+    """Optional class name for method calls"""
+    className: String
+
+    """Maximum results"""
+    limit: Int
+
+    """Results to skip"""
+    offset: Int
+  ): [CallInfo!]!
+
+  """
+  Get comprehensive function details including calls and callers.
+  """
+  getFunctionDetails(
+    """Function name"""
+    name: String!
+
+    """File path for disambiguation"""
+    file: String
+
+    """Follow transitive call chains"""
+    transitive: Boolean
+  ): FunctionDetails
+
+  """
+  Find guards (conditional scopes) protecting a node.
+  """
+  findGuards(
+    """Node ID to find guards for"""
+    nodeId: ID!
+  ): [GuardInfo!]!
+
+  """
+  Trace variable alias chain to original source.
+  """
+  traceAlias(
+    """Variable name"""
+    variableName: String!
+
+    """File where variable is defined"""
+    file: String!
+
+    """Maximum trace depth (default: 20)"""
+    maxDepth: Int
+  ): [Node!]!
+
+  """
+  Trace data flow from/to a node.
+  """
+  traceDataFlow(
+    """Source node ID or variable name"""
+    source: String!
+
+    """File path"""
+    file: String
+
+    """Direction of trace"""
+    direction: TraversalDirection
+
+    """Maximum depth (default: 10)"""
+    maxDepth: Int
+  ): [[String!]!]!
+
+  # ============================================================================
+  # Guarantees
+  # ============================================================================
+
+  """
+  List all defined guarantees.
+  """
+  guarantees: [Guarantee!]!
+
+  """
+  Get a specific guarantee by ID.
+  """
+  guarantee(id: ID!): Guarantee
+
+  # ============================================================================
+  # Statistics
+  # ============================================================================
+
+  """
+  Get graph statistics.
+  """
+  stats: GraphStats!
+
+  """
+  Get current analysis status.
+  """
+  analysisStatus: AnalysisStatus!
+}

package/src/schema/scalars.graphql

@@ -0,0 +1,2 @@
+"""Custom JSON scalar for arbitrary metadata."""
+scalar JSON

package/src/schema/subscriptions.graphql

@@ -0,0 +1,84 @@
+type Subscription {
+  """
+  Stream nodes matching filter as they're found.
+  Useful for UI visualization of large datasets.
+  """
+  nodesStream(
+    """Filter criteria"""
+    filter: NodeFilter
+
+    """Batch size for streaming (default: 100)"""
+    batchSize: Int
+  ): NodeBatch!
+
+  """
+  Stream BFS traversal results level by level.
+  Each batch contains all nodes at one depth level.
+  """
+  bfsStream(
+    """Starting node IDs"""
+    startIds: [ID!]!
+
+    """Maximum traversal depth"""
+    maxDepth: Int!
+
+    """Edge types to traverse"""
+    edgeTypes: [String!]!
+  ): TraversalBatch!
+
+  """
+  Stream analysis progress events.
+  """
+  analysisProgress(
+    """Optional: filter to specific service"""
+    service: String
+  ): AnalysisEvent!
+}
+
+"""
+Batch of nodes for streaming responses.
+"""
+type NodeBatch {
+  """Nodes in this batch"""
+  nodes: [Node!]!
+
+  """Progress from 0.0 to 1.0"""
+  progress: Float!
+
+  """Whether streaming is complete"""
+  done: Boolean!
+}
+
+"""
+Batch of traversal results at a specific depth.
+"""
+type TraversalBatch {
+  """Current depth level"""
+  depth: Int!
+
+  """Node IDs at this depth"""
+  nodeIds: [ID!]!
+
+  """Whether traversal is complete"""
+  done: Boolean!
+}
+
+"""
+Analysis progress event.
+"""
+type AnalysisEvent {
+  """Current phase name"""
+  phase: String!
+
+  """Human-readable message"""
+  message: String!
+
+  """Progress from 0.0 to 1.0"""
+  progress: Float!
+
+  """Number of services completed"""
+  servicesCompleted: Int!
+
+  """Total number of services"""
+  servicesTotal: Int!
+}