@neat.is/types 0.4.26-dev.20260702 → 0.4.26

package/dist/index.js

@@ -33,7 +33,46 @@ var NodeType = {
   // The primary node of the file-first graph (ADR-089). A source file owned
   // by a service; relationships originate from it. See
   // docs/contracts/file-awareness.md §1.
-  FileNode: "FileNode"
+  FileNode: "FileNode",
+  // A server route at (method, path-template) granularity (ADR-119). Extracted
+  // from a mainstream router (Express / Fastify / Next.js) so a client call
+  // site can be matched to the exact route it names, rather than only to the
+  // owning service. The node an OBSERVED server span lands on too, which is
+  // what makes a two-sided divergence possible at route grain. See
+  // docs/contracts/static-extraction.md.
+  RouteNode: "RouteNode",
+  // A named GraphQL operation — one query, mutation, or subscription — at
+  // (service, operationType, operationName) granularity (ADR-122). Every
+  // GraphQL request rides one HTTP endpoint (POST /graphql), so at HTTP grain
+  // the whole API collapses to a single edge; this node recovers the
+  // operation-level topology from the execution span's `graphql.operation.*`
+  // semconv. Minted observed-first from OTel; a future static GraphQL extractor
+  // fuses onto the same id. See docs/contracts/otel-ingest.md.
+  GraphQLOperationNode: "GraphQLOperationNode",
+  // A single gRPC method — one `rpc` in a `.proto` service — at
+  // (rpcService, rpcMethod) granularity (ADR-123). gRPC used to engage only at
+  // service grain: every method collapsed onto one service→service edge, so the
+  // per-method topology was invisible and one-sided. This node recovers the
+  // method-level shape from both sides: the OBSERVED execution span's
+  // `rpc.service` / `rpc.method` semconv and the static `.proto` service/method
+  // definitions. It keys on the fully-qualified `rpc.service` — the wire
+  // contract both sides carry verbatim — so a declared method and an observed
+  // one fuse onto the same node into a two-sided divergence. See
+  // docs/contracts/otel-ingest.md and docs/contracts/static-extraction.md.
+  GrpcMethodNode: "GrpcMethodNode",
+  // A live WebSocket channel — the path/channel a client connects to — at
+  // (service, channel) granularity (ADR-125). A WebSocket app used to produce no
+  // OBSERVED topology at all: only message-handler errors surfaced, as incidents,
+  // and the channels themselves stayed invisible. This node recovers the
+  // channel-level topology from the HTTP upgrade span that opens the connection —
+  // a SERVER `GET` carrying the WebSocket path. It is minted OBSERVED-only: a
+  // WebSocket channel is known from observation, never from static extraction, so
+  // there is no declared twin to fuse with. The edge onto it reuses the existing
+  // `CONNECTS_TO` (`service ──CONNECTS_TO──▶ ws-channel`) as an observed-liveness
+  // edge that carries `lastObserved` and decays OBSERVED → STALE on CONNECTS_TO's
+  // own staleness threshold when the channel goes quiet. See
+  // docs/contracts/otel-ingest.md.
+  WebSocketChannelNode: "WebSocketChannelNode"
 };
 var NodeTypeSchema = z.enum([
   NodeType.ServiceNode,
@@ -41,7 +80,11 @@ var NodeTypeSchema = z.enum([
   NodeType.ConfigNode,
   NodeType.InfraNode,
   NodeType.FrontierNode,
-  NodeType.FileNode
+  NodeType.FileNode,
+  NodeType.RouteNode,
+  NodeType.GraphQLOperationNode,
+  NodeType.GrpcMethodNode,
+  NodeType.WebSocketChannelNode
 ]);
 
 // src/nodes.ts
@@ -171,13 +214,60 @@ var FileNodeSchema = z2.object({
   // Absent when the call site was already source-grained.
   originalPath: z2.string().optional()
 });
+var RouteNodeSchema = z2.object({
+  id: z2.string(),
+  type: z2.literal(NodeType.RouteNode),
+  name: z2.string(),
+  service: z2.string(),
+  method: z2.string(),
+  pathTemplate: z2.string(),
+  path: z2.string(),
+  line: z2.number().int().nonnegative().optional(),
+  framework: z2.string().optional(),
+  discoveredVia: DiscoveredViaSchema.optional()
+});
+var GraphQLOperationNodeSchema = z2.object({
+  id: z2.string(),
+  type: z2.literal(NodeType.GraphQLOperationNode),
+  name: z2.string(),
+  service: z2.string(),
+  operationType: z2.string(),
+  operationName: z2.string(),
+  path: z2.string().optional(),
+  line: z2.number().int().nonnegative().optional(),
+  discoveredVia: DiscoveredViaSchema.optional()
+});
+var GrpcMethodNodeSchema = z2.object({
+  id: z2.string(),
+  type: z2.literal(NodeType.GrpcMethodNode),
+  name: z2.string(),
+  rpcService: z2.string(),
+  rpcMethod: z2.string(),
+  path: z2.string().optional(),
+  line: z2.number().int().nonnegative().optional(),
+  discoveredVia: DiscoveredViaSchema.optional()
+});
+var WebSocketChannelNodeSchema = z2.object({
+  id: z2.string(),
+  type: z2.literal(NodeType.WebSocketChannelNode),
+  name: z2.string(),
+  service: z2.string(),
+  channel: z2.string(),
+  path: z2.string().optional(),
+  line: z2.number().int().nonnegative().optional(),
+  discoveredVia: DiscoveredViaSchema.optional()
+});
 var GraphNodeSchema = z2.discriminatedUnion("type", [
   ServiceNodeSchema,
   DatabaseNodeSchema,
   ConfigNodeSchema,
   InfraNodeSchema,
   FrontierNodeSchema,
-  FileNodeSchema
+  FileNodeSchema,
+  RouteNodeSchema,
+  GraphQLOperationNodeSchema,
+  GrpcMethodNodeSchema,
+  WebSocketChannelNodeSchema
 ]);
 
 // src/edges.ts
@@ -202,7 +292,13 @@ var EdgeTypeSchema = z3.enum([
 var EdgeEvidenceSchema = z3.object({
   file: z3.string(),
   line: z3.number().int().nonnegative().optional(),
-  snippet: z3.string().optional()
+  snippet: z3.string().optional(),
+  // HTTP shape of a recognised client call site (ADR-119). Present on a
+  // client↔route CALLS edge so the edge records the method + path-template the
+  // client named, alongside the file:line it named them at. Absent on every
+  // other edge — a config or infra edge has no HTTP method.
+  method: z3.string().optional(),
+  pathTemplate: z3.string().optional()
 });
 var EdgeSignalSchema = z3.object({
   spanCount: z3.number().int().nonnegative(),
@@ -343,6 +439,10 @@ var CONFIG_PREFIX = "config:";
 var INFRA_PREFIX = "infra:";
 var FRONTIER_PREFIX = "frontier:";
 var FILE_PREFIX = "file:";
+var ROUTE_PREFIX = "route:";
+var GRAPHQL_OP_PREFIX = "graphql:";
+var GRPC_METHOD_PREFIX = "grpc:";
+var WEBSOCKET_CHANNEL_PREFIX = "ws:";
 var ENV_UNKNOWN = "unknown";
 function serviceId(name, env) {
   if (env === void 0 || env === ENV_UNKNOWN) return `${SERVICE_PREFIX}${name}`;
@@ -362,6 +462,9 @@ function databaseId(host) {
 function parseDatabaseId(id) {
   return id.startsWith(DATABASE_PREFIX) ? id.slice(DATABASE_PREFIX.length) : null;
 }
+function localDatabaseId(service, name) {
+  return `${DATABASE_PREFIX}${service}/${name}`;
+}
 function configId(relPath) {
   return `${CONFIG_PREFIX}${relPath}`;
 }
@@ -397,6 +500,68 @@ function parseFileId(id) {
   if (service.length === 0 || relPath.length === 0) return null;
   return { service, relPath };
 }
+function routeId(service, method, pathTemplate) {
+  return `${ROUTE_PREFIX}${service}:${method.toUpperCase()} ${pathTemplate}`;
+}
+function parseRouteId(id) {
+  if (!id.startsWith(ROUTE_PREFIX)) return null;
+  const rest = id.slice(ROUTE_PREFIX.length);
+  const colon = rest.indexOf(":");
+  if (colon === -1) return null;
+  const service = rest.slice(0, colon);
+  const tail = rest.slice(colon + 1);
+  const space = tail.indexOf(" ");
+  if (space === -1) return null;
+  const method = tail.slice(0, space);
+  const pathTemplate = tail.slice(space + 1);
+  if (service.length === 0 || method.length === 0 || pathTemplate.length === 0) return null;
+  return { service, method, pathTemplate };
+}
+function graphqlOperationId(service, operationType, operationName) {
+  return `${GRAPHQL_OP_PREFIX}${service}:${operationType.toLowerCase()} ${operationName}`;
+}
+function parseGraphqlOperationId(id) {
+  if (!id.startsWith(GRAPHQL_OP_PREFIX)) return null;
+  const rest = id.slice(GRAPHQL_OP_PREFIX.length);
+  const colon = rest.indexOf(":");
+  if (colon === -1) return null;
+  const service = rest.slice(0, colon);
+  const tail = rest.slice(colon + 1);
+  const space = tail.indexOf(" ");
+  if (space === -1) return null;
+  const operationType = tail.slice(0, space);
+  const operationName = tail.slice(space + 1);
+  if (service.length === 0 || operationType.length === 0 || operationName.length === 0) {
+    return null;
+  }
+  return { service, operationType, operationName };
+}
+function grpcMethodId(rpcService, rpcMethod) {
+  return `${GRPC_METHOD_PREFIX}${rpcService}/${rpcMethod}`;
+}
+function parseGrpcMethodId(id) {
+  if (!id.startsWith(GRPC_METHOD_PREFIX)) return null;
+  const rest = id.slice(GRPC_METHOD_PREFIX.length);
+  const slash = rest.indexOf("/");
+  if (slash === -1) return null;
+  const rpcService = rest.slice(0, slash);
+  const rpcMethod = rest.slice(slash + 1);
+  if (rpcService.length === 0 || rpcMethod.length === 0) return null;
+  return { rpcService, rpcMethod };
+}
+function websocketChannelId(service, channel) {
+  return `${WEBSOCKET_CHANNEL_PREFIX}${service}:${channel}`;
+}
+function parseWebsocketChannelId(id) {
+  if (!id.startsWith(WEBSOCKET_CHANNEL_PREFIX)) return null;
+  const rest = id.slice(WEBSOCKET_CHANNEL_PREFIX.length);
+  const colon = rest.indexOf(":");
+  if (colon === -1) return null;
+  const service = rest.slice(0, colon);
+  const channel = rest.slice(colon + 1);
+  if (service.length === 0 || channel.length === 0) return null;
+  return { service, channel };
+}
 var EDGE_ARROW = "->";
 function extractedEdgeId(source, target, type) {
   return `${type}:${source}${EDGE_ARROW}${target}`;
@@ -864,6 +1029,8 @@ export {
   GraphEdgesResponseSchema,
   GraphNodeResponseSchema,
   GraphNodeSchema,
+  GraphQLOperationNodeSchema,
+  GrpcMethodNodeSchema,
   HealthResponseSchema,
   HostMismatchDivergenceSchema,
   HypotheticalActionSchema,
@@ -892,6 +1059,7 @@ export {
   RegistryFileSchema,
   RegistryStatusSchema,
   RootCauseResultSchema,
+  RouteNodeSchema,
   SearchMatchSchema,
   SearchResponseSchema,
   SerializedGraphSchema,
@@ -904,6 +1072,7 @@ export {
   TransitiveDependenciesResultSchema,
   TransitiveDependencySchema,
   VersionMismatchDivergenceSchema,
+  WebSocketChannelNodeSchema,
   confidenceForExtracted,
   confidenceForObservedSignal,
   configId,
@@ -912,17 +1081,26 @@ export {
   extractedPrecisionFloor,
   fileId,
   frontierId,
+  graphqlOperationId,
+  grpcMethodId,
   inferredEdgeId,
   infraId,
+  localDatabaseId,
   observedEdgeId,
   parseConfigId,
   parseDatabaseId,
   parseEdgeId,
   parseFileId,
   parseFrontierId,
+  parseGraphqlOperationId,
+  parseGrpcMethodId,
   parseInfraId,
+  parseRouteId,
   parseServiceId,
+  parseWebsocketChannelId,
   passesExtractedFloor,
-  serviceId
+  routeId,
+  serviceId,
+  websocketChannelId
 };
 //# sourceMappingURL=index.js.map