@grafema/api 0.2.5-beta

package/dist/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!
+}

package/dist/schema/types.graphql

@@ -0,0 +1,440 @@
+"""
+A node in the code graph representing a code entity.
+"""
+type Node {
+  """Unique identifier for the node (e.g., "fn:src/api.ts:login:42")"""
+  id: ID!
+
+  """Node type (e.g., FUNCTION, CLASS, MODULE, http:route)"""
+  type: String!
+
+  """Human-readable name"""
+  name: String!
+
+  """Source file path (relative to project root)"""
+  file: String
+
+  """Line number in source file (1-indexed)"""
+  line: Int
+
+  """Column number in source file (1-indexed)"""
+  column: Int
+
+  """Whether this entity is exported from its module"""
+  exported: Boolean
+
+  """Arbitrary metadata as JSON object"""
+  metadata: JSON
+
+  # Relationship fields
+
+  """
+  Outgoing edges from this node.
+  Optional filter by edge types.
+  """
+  outgoingEdges(
+    types: [String!]
+    first: Int
+    after: String
+  ): GraphEdgeConnection!
+
+  """
+  Incoming edges to this node.
+  Optional filter by edge types.
+  """
+  incomingEdges(
+    types: [String!]
+    first: Int
+    after: String
+  ): GraphEdgeConnection!
+
+  """
+  Child nodes (via CONTAINS edges).
+  For hierarchical traversal: SERVICE -> MODULE -> FUNCTION -> SCOPE
+  """
+  children(first: Int, after: String): NodeConnection!
+
+  """
+  Parent node (via incoming CONTAINS edge).
+  Returns null for root nodes (SERVICE, PROJECT).
+  """
+  parent: Node
+}
+
+"""
+An edge in the code graph representing a relationship between nodes.
+"""
+type Edge {
+  """Source node"""
+  src: Node!
+
+  """Destination node"""
+  dst: Node!
+
+  """Edge type (e.g., CALLS, CONTAINS, IMPORTS)"""
+  type: String!
+
+  """Ordering index for ordered relationships"""
+  index: Int
+
+  """Arbitrary metadata as JSON object"""
+  metadata: JSON
+}
+
+# ============================================================================
+# Pagination Types (Relay Connection Spec)
+# ============================================================================
+
+"""
+Connection type for paginated node results (Relay spec).
+"""
+type NodeConnection {
+  """Edges containing nodes and cursors"""
+  edges: [NodeEdge!]!
+
+  """Pagination info"""
+  pageInfo: PageInfo!
+
+  """Total count of matching nodes"""
+  totalCount: Int!
+}
+
+"""
+Edge wrapper for cursor-based pagination.
+"""
+type NodeEdge {
+  """The node"""
+  node: Node!
+
+  """Cursor for this node (use with after/before args)"""
+  cursor: String!
+}
+
+"""
+Connection type for paginated graph edge results.
+"""
+type GraphEdgeConnection {
+  """Edges containing graph edges and cursors"""
+  edges: [GraphEdgeEdge!]!
+
+  """Pagination info"""
+  pageInfo: PageInfo!
+
+  """Total count of matching edges"""
+  totalCount: Int!
+}
+
+"""
+Edge wrapper for graph edges.
+"""
+type GraphEdgeEdge {
+  """The graph edge"""
+  node: Edge!
+
+  """Cursor for this edge"""
+  cursor: String!
+}
+
+"""
+Pagination info (Relay spec).
+"""
+type PageInfo {
+  """Has more items after endCursor"""
+  hasNextPage: Boolean!
+
+  """Has more items before startCursor"""
+  hasPreviousPage: Boolean!
+
+  """Cursor of first item in current page"""
+  startCursor: String
+
+  """Cursor of last item in current page"""
+  endCursor: String
+}
+
+# ============================================================================
+# Query Result Types
+# ============================================================================
+
+"""
+Result of a Datalog query.
+"""
+type DatalogResult {
+  """Whether the query executed successfully"""
+  success: Boolean!
+
+  """Number of results"""
+  count: Int!
+
+  """Query results with variable bindings"""
+  results: [DatalogBinding!]!
+
+  """Error message if query failed"""
+  error: String
+}
+
+"""
+Variable bindings from a Datalog query result.
+"""
+type DatalogBinding {
+  """Map of variable names to values"""
+  bindings: JSON!
+
+  """Enriched node data if X binding is a node ID"""
+  node: Node
+}
+
+"""
+Function details including call graph information.
+"""
+type FunctionDetails {
+  """The function node"""
+  function: Node!
+
+  """Functions/methods this function calls"""
+  calls: [CallInfo!]!
+
+  """Functions that call this function"""
+  calledBy: [CallerInfo!]!
+}
+
+"""
+Information about a call made by a function.
+"""
+type CallInfo {
+  """The CALL node"""
+  call: Node!
+
+  """Name of the called function/method"""
+  name: String!
+
+  """Object name for method calls (e.g., "console" in console.log)"""
+  object: String
+
+  """Whether the target was resolved"""
+  resolved: Boolean!
+
+  """Target function if resolved"""
+  target: Node
+
+  """Call type: CALL or METHOD_CALL"""
+  callType: String!
+
+  """Depth in transitive call chain (0 = direct)"""
+  depth: Int!
+}
+
+"""
+Information about a function that calls another function.
+"""
+type CallerInfo {
+  """The calling function"""
+  function: Node!
+
+  """File containing the caller"""
+  file: String!
+
+  """Line number of the call"""
+  line: Int!
+}
+
+"""
+Guard (conditional scope) protecting a node.
+"""
+type GuardInfo {
+  """The SCOPE node ID"""
+  scopeId: ID!
+
+  """Type of conditional (if_statement, else_statement, etc.)"""
+  scopeType: String!
+
+  """Raw condition text"""
+  condition: String
+
+  """Parsed constraints as JSON"""
+  constraints: JSON
+
+  """Source file"""
+  file: String!
+
+  """Line number"""
+  line: Int!
+}
+
+"""
+Guarantee definition.
+"""
+type Guarantee {
+  """Unique identifier"""
+  id: ID!
+
+  """Human-readable name"""
+  name: String!
+
+  """Datalog rule or contract condition"""
+  rule: String
+
+  """Severity level"""
+  severity: String
+
+  """Guarantee type for contract-based"""
+  type: String
+
+  """Priority level"""
+  priority: String
+
+  """Lifecycle status"""
+  status: String
+
+  """Description"""
+  description: String
+}
+
+"""
+Result of checking guarantees.
+"""
+type GuaranteeCheckResult {
+  """Total guarantees checked"""
+  total: Int!
+
+  """Number that passed"""
+  passed: Int!
+
+  """Number that failed"""
+  failed: Int!
+
+  """Individual results"""
+  results: [GuaranteeResult!]!
+}
+
+"""
+Result of checking a single guarantee.
+"""
+type GuaranteeResult {
+  """Guarantee ID"""
+  guaranteeId: ID!
+
+  """Whether the guarantee passed"""
+  passed: Boolean!
+
+  """Number of violations (for Datalog guarantees)"""
+  violationCount: Int
+
+  """Sample violations"""
+  violations: [Violation!]
+}
+
+"""
+A violation of a guarantee.
+"""
+type Violation {
+  """Node that violated the guarantee"""
+  node: Node
+
+  """File containing the violation"""
+  file: String
+
+  """Line number"""
+  line: Int
+}
+
+"""
+Graph statistics.
+"""
+type GraphStats {
+  """Total node count"""
+  nodeCount: Int!
+
+  """Total edge count"""
+  edgeCount: Int!
+
+  """Nodes grouped by type"""
+  nodesByType: JSON!
+
+  """Edges grouped by type"""
+  edgesByType: JSON!
+}
+
+"""
+Analysis status.
+"""
+type AnalysisStatus {
+  """Whether analysis is currently running"""
+  running: Boolean!
+
+  """Current phase"""
+  phase: String
+
+  """Status message"""
+  message: String
+
+  """Number of services discovered"""
+  servicesDiscovered: Int!
+
+  """Number of services analyzed"""
+  servicesAnalyzed: Int!
+
+  """Error message if analysis failed"""
+  error: String
+}
+
+"""
+Result of analyze mutation.
+"""
+type AnalysisResult {
+  """Whether analysis succeeded"""
+  success: Boolean!
+
+  """Status after analysis"""
+  status: AnalysisStatus!
+}
+
+# ============================================================================
+# Input Types
+# ============================================================================
+
+"""
+Filter for node queries.
+"""
+input NodeFilter {
+  """Filter by node type"""
+  type: String
+
+  """Filter by name (exact match)"""
+  name: String
+
+  """Filter by file path (partial match)"""
+  file: String
+
+  """Filter by exported status"""
+  exported: Boolean
+}
+
+"""
+Input for creating a guarantee.
+"""
+input CreateGuaranteeInput {
+  """Unique name"""
+  name: String!
+
+  """Datalog rule defining violation/1"""
+  rule: String
+
+  """Severity: error, warning, info"""
+  severity: Severity
+
+  """Type: guarantee:queue, guarantee:api, guarantee:permission"""
+  type: String
+
+  """Priority: critical, important, observed, tracked"""
+  priority: Priority
+
+  """Description"""
+  description: String
+
+  """Owner (team or person)"""
+  owner: String
+
+  """Node IDs this guarantee governs"""
+  governs: [String!]
+}

package/dist/server.d.ts

@@ -0,0 +1,31 @@
+/**
+ * GraphQL API Server using graphql-yoga
+ *
+ * Provides a GraphQL endpoint on top of Grafema's graph database.
+ * Supports cursor-based pagination and query complexity limiting.
+ */
+import { createServer } from 'node:http';
+import type { RFDBServerBackend } from '@grafema/core';
+export interface GraphQLServerOptions {
+    /** Graph backend (RFDBServerBackend) */
+    backend: RFDBServerBackend;
+    /** Port to listen on (default: 4000) */
+    port?: number;
+    /** Hostname to bind to (default: localhost) */
+    hostname?: string;
+    /** Maximum query depth (default: 10) */
+    maxDepth?: number;
+    /** Maximum query complexity cost (default: 1000) */
+    maxComplexity?: number;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+}
+export declare function createGraphQLServer(options: GraphQLServerOptions): import("graphql-yoga").YogaServerInstance<{}, import("./context.js").GraphQLContext>;
+/**
+ * Start a standalone GraphQL server.
+ *
+ * @param options Server options
+ * @returns HTTP server instance
+ */
+export declare function startServer(options: GraphQLServerOptions): ReturnType<typeof createServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAwB,MAAM,WAAW,CAAC;AAQ/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AA6BvD,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,wFAuDhE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,oBAAoB,GAC5B,UAAU,CAAC,OAAO,YAAY,CAAC,CAejC"}

package/dist/server.js

@@ -0,0 +1,109 @@
+/**
+ * GraphQL API Server using graphql-yoga
+ *
+ * Provides a GraphQL endpoint on top of Grafema's graph database.
+ * Supports cursor-based pagination and query complexity limiting.
+ */
+import { createServer } from 'node:http';
+import { createYoga, createSchema } from 'graphql-yoga';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolvers } from './resolvers/index.js';
+import { createContext } from './context.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Load schema files
+function loadTypeDefs() {
+    const schemaDir = join(__dirname, 'schema');
+    const files = [
+        'scalars.graphql',
+        'enums.graphql',
+        'types.graphql',
+        'queries.graphql',
+        'mutations.graphql',
+        'subscriptions.graphql',
+    ];
+    return files
+        .map((file) => {
+        try {
+            return readFileSync(join(schemaDir, file), 'utf-8');
+        }
+        catch {
+            // File might not exist in dist yet, try src
+            const srcPath = join(__dirname, '..', 'src', 'schema', file);
+            return readFileSync(srcPath, 'utf-8');
+        }
+    })
+        .join('\n');
+}
+export function createGraphQLServer(options) {
+    const { backend } = options;
+    const typeDefs = loadTypeDefs();
+    const schema = createSchema({
+        typeDefs,
+        resolvers,
+    });
+    const yoga = createYoga({
+        schema,
+        context: ({ request }) => {
+            // Create a minimal request object for context
+            const req = {
+                headers: Object.fromEntries(request.headers.entries()),
+            };
+            return createContext(backend, req);
+        },
+        graphiql: {
+            title: 'Grafema GraphQL API',
+            defaultQuery: `# Welcome to Grafema GraphQL API
+#
+# Example queries:
+#
+# Get all functions:
+# query { nodes(filter: {type: "FUNCTION"}, first: 10) {
+#   edges { node { id name file line } }
+#   pageInfo { hasNextPage endCursor }
+#   totalCount
+# }}
+#
+# Find a specific node:
+# query { node(id: "your-node-id") { id name type file } }
+#
+# Execute Datalog:
+# query { datalog(query: "violation(X) :- node(X, \\"FUNCTION\\").") {
+#   count
+#   results { node { name } }
+# }}
+
+query Stats {
+  stats {
+    nodeCount
+    edgeCount
+    nodesByType
+  }
+}
+`,
+        },
+        // Subscriptions enabled for streaming
+        // (graphql-yoga uses SSE by default)
+    });
+    return yoga;
+}
+/**
+ * Start a standalone GraphQL server.
+ *
+ * @param options Server options
+ * @returns HTTP server instance
+ */
+export function startServer(options) {
+    const { port = 4000, hostname = 'localhost' } = options;
+    const yoga = createGraphQLServer(options);
+    const server = createServer((req, res) => {
+        yoga(req, res);
+    });
+    server.listen(port, hostname, () => {
+        console.log(`Grafema GraphQL API running at http://${hostname}:${port}/graphql`);
+        console.log(`GraphiQL IDE available at http://${hostname}:${port}/graphql`);
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}