opencode-gitlab-plugin 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.1.0](https://gitlab.com/vglafirov/opencode-gitlab-plugin/compare/v3.0.1...v3.1.0) (2026-10-13)
+
+
+### ✨ Features
+
+* **orbit:** derive neighbors default rel_types from the schema ([567a114](https://gitlab.com/vglafirov/opencode-gitlab-plugin/commit/567a114be061e6fc5e6d59984c497f8621a9a582))
+
+## [3.0.1](https://gitlab.com/vglafirov/opencode-gitlab-plugin/compare/v3.0.0...v3.0.1) (2026-10-06)
+
+
+### 🐛 Bug Fixes
+
+* **orbit:** update tools to current Knowledge Graph query DSL ([a62c60b](https://gitlab.com/vglafirov/opencode-gitlab-plugin/commit/a62c60bc195b63928868424cb5412bf579f23597))
+
 ## [3.0.0](https://gitlab.com/vglafirov/opencode-gitlab-plugin/compare/v2.8.2...v3.0.0) (2026-09-21)
 
 

package/dist/index.js

@@ -5450,6 +5450,109 @@ Examples:
 // src/tools/orbit.ts
 import { tool as tool18 } from "@opencode-ai/plugin";
 var z18 = tool18.schema;
+var MAX_REL_TYPES = 10;
+var SCHEMA_CACHE_TTL_MS = 10 * 60 * 1e3;
+var schemaCache = /* @__PURE__ */ new Map();
+var schemaInflight = /* @__PURE__ */ new Map();
+async function loadOrbitSchema(client) {
+  const key = process.env["GITLAB_INSTANCE_URL"] || "https://gitlab.com";
+  const cached = schemaCache.get(key);
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.schema;
+  }
+  const inflight = schemaInflight.get(key);
+  if (inflight) {
+    return inflight;
+  }
+  const request = (async () => {
+    try {
+      const schema = await client.fetch("GET", "/orbit/schema");
+      if (!schema || !Array.isArray(schema.edges)) {
+        return void 0;
+      }
+      schemaCache.set(key, { schema, expiresAt: Date.now() + SCHEMA_CACHE_TTL_MS });
+      return schema;
+    } catch {
+      return void 0;
+    }
+  })();
+  schemaInflight.set(key, request);
+  void request.finally(() => {
+    if (schemaInflight.get(key) === request) {
+      schemaInflight.delete(key);
+    }
+  });
+  return request;
+}
+function deriveRelTypes(schema, entityType, preferred) {
+  const touching = /* @__PURE__ */ new Set();
+  for (const edge of schema.edges ?? []) {
+    const touchesEntity = (edge.variants ?? []).some(
+      (variant) => variant.source_type === entityType || variant.target_type === entityType
+    );
+    if (touchesEntity) {
+      touching.add(edge.name);
+    }
+  }
+  const rank = (name) => {
+    const index = preferred.indexOf(name);
+    return index === -1 ? preferred.length : index;
+  };
+  return [...touching].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b)).slice(0, MAX_REL_TYPES);
+}
+async function defaultRelTypes(client, entityType) {
+  const fallback = orbitRelTypes(entityType);
+  const schema = await loadOrbitSchema(client);
+  if (!schema) {
+    return fallback;
+  }
+  const derived = deriveRelTypes(schema, entityType, fallback);
+  return derived.length > 0 ? derived : fallback;
+}
+function orbitRelTypes(entityType) {
+  switch (entityType) {
+    case "MergeRequest":
+      return [
+        "AUTHORED",
+        "REVIEWER",
+        "ASSIGNED",
+        "CLOSES",
+        "MENTIONS",
+        "IN_PROJECT",
+        "HAS_HEAD_PIPELINE",
+        "TRIGGERED",
+        "IN_MILESTONE",
+        "HAS_LABEL"
+      ];
+    case "WorkItem":
+      return [
+        "AUTHORED",
+        "ASSIGNED",
+        "CLOSES",
+        "MENTIONS",
+        "RELATED_TO",
+        "CONTAINS",
+        "IN_PROJECT",
+        "IN_GROUP",
+        "IN_MILESTONE",
+        "HAS_LABEL"
+      ];
+    case "User":
+      return ["AUTHORED", "ASSIGNED", "REVIEWER", "MEMBER_OF", "OWNER", "CREATOR"];
+    case "Project":
+      return ["CONTAINS", "IN_PROJECT", "MEMBER_OF", "CREATOR"];
+    case "Pipeline":
+      return ["HAS_HEAD_PIPELINE", "TRIGGERED", "IN_PROJECT", "HAS_JOB", "HAS_STAGE"];
+    case "File":
+      return ["CONTAINS", "IMPORTS", "DEFINES", "CALLS", "ON_BRANCH"];
+    case "Group":
+      return ["CONTAINS", "MEMBER_OF", "OWNER", "IN_GROUP"];
+    case "Commit":
+      return ["MERGED_AT_COMMIT"];
+    default:
+      return ["AUTHORED", "ASSIGNED", "REVIEWER", "CLOSES", "MENTIONS", "RELATED_TO", "IN_PROJECT"];
+  }
+}
 var orbitTools = {
   gitlab_orbit_status: tool18({
     description: `Check GitLab Orbit Knowledge Graph API availability and health.
@@ -5583,47 +5686,64 @@ Note: Requires Orbit API to be available (Premium/Ultimate tier).`,
     description: `Execute a query against the Orbit Knowledge Graph.
 
 Query types:
-- traversal: Walk the graph from a starting node
-- neighbors: Get immediate neighbors of a node
+- traversal: Fetch matching nodes or follow relationships between nodes
+- neighbors: Return nodes connected to one bounded node
+- aggregation: Count/sum/avg/group graph results
+- path_finding: Find a bounded path between two nodes
 
-IMPORTANT: The query format uses variable names for node references.
-- "id" in node definition is a VARIABLE NAME (alias), not the actual entity ID
-- Actual IDs go in "filters" with {"field": {"op": "eq", "value": X}} format
+QUERY SHAPE (current DSL, format_version 5.x):
+Every query has a "query_type" and a "nodes" array of node selectors (max 5).
+A node selector names an entity and is made SELECTIVE via "node_ids" (exact
+internal ids) or "filters" (natural properties). Relationships between selectors
+go in a "relationships" array referencing selector "id" aliases.
 
-Example neighbors query to get a project's connections:
+IMPORTANT changes from older docs:
+- Use a top-level "nodes" ARRAY, not a single "node" object.
+- Pin ids with "node_ids": [123], NOT filters:{id:{op:"eq",value:123}}.
+- Filters use {op: value}, e.g. {"state": "merged"} or {"created_at": {"gte": "2026-01-01"}}.
+- A "neighbors" query uses a 1-element "nodes" array plus a top-level
+  "neighbors": {direction, rel_types:[...]} object. rel_types is REQUIRED to
+  bound the lookup and is capped at 10 entries.
+
+Example neighbors query (an MR's graph neighbours):
 {
   "query_type": "neighbors",
-  "node": {
-    "entity": "Project",
-    "id": "p",
-    "filters": {"id": {"op": "eq", "value": 278964}}
+  "nodes": [{ "id": "mr", "entity": "MergeRequest", "node_ids": [507483917] }],
+  "neighbors": {
+    "direction": "both",
+    "rel_types": ["AUTHORED", "REVIEWER", "IN_PROJECT", "CLOSES", "HAS_HEAD_PIPELINE"]
   },
-  "neighbors": {"node": "p", "direction": "incoming"},
-  "aggregations": [],
-  "path": {"type": "shortest", "from": "p", "to": "p", "max_depth": 1}
+  "limit": 30
 }
 
-Example traversal query:
+Example traversal (merged MRs in a project):
 {
   "query_type": "traversal",
-  "node": {
-    "entity": "MergeRequest",
-    "id": "mr",
-    "filters": {"id": {"op": "eq", "value": 377844873}}
-  },
-  "neighbors": {"node": "mr", "direction": "both"},
-  "aggregations": [],
-  "path": {"type": "shortest", "from": "mr", "to": "mr", "max_depth": 1}
+  "nodes": [
+    { "id": "project", "entity": "Project", "filters": {"full_path": "gitlab-org/gitlab"} },
+    { "id": "mr", "entity": "MergeRequest", "filters": {"state": "merged"},
+      "columns": ["iid", "title", "merged_at"] }
+  ],
+  "relationships": [{ "type": "IN_PROJECT", "from": "mr", "to": "project" }],
+  "limit": 25
 }
 
-Note: Use gitlab_get_merge_request to get the internal ID from an IID.
-Returns nodes array and edges array with relationship types.`,
+Notes:
+- node_ids are GitLab *internal* numeric ids (not IIDs). For an MR, get it via
+  gitlab_get_merge_request (the "id" field). For epics, use work_item_id.
+- Traversal/aggregation queries must include at least one selective node.
+- aggregation adds an "aggregations" array (e.g. [{"count":"mr"}]) with optional
+  "group_by"; path_finding adds a "path":{from,to,max_depth} object between two
+  node selectors. Both use the same envelope; see gitlab_orbit_schema and the
+  Orbit query-language docs for the full grammar.
+- Use gitlab_orbit_schema to discover entities and relationship types.
+Returns nodes and edges arrays.`,
     args: {
       // Using a JSON string rather than a structured zod schema because the Orbit query
       // format is still evolving. This allows flexibility as the API changes without
       // requiring schema updates for each iteration.
       query: z18.string().describe(
-        "JSON string containing the full query object. Must include query_type, node, neighbors, aggregations, and path fields. See description for format details."
+        'JSON string containing the full query object. Must include "query_type" and a top-level "nodes" array of selectors (each pinned by "node_ids" or "filters"); add "relationships"/"neighbors"/"aggregations"/"path" per the query_type. See the tool description for the current DSL and worked examples.'
       ),
       limit: z18.number().optional().describe("Maximum number of results (default: 30)")
     },
@@ -5642,12 +5762,23 @@ Returns nodes array and edges array with relationship types.`,
           2
         );
       }
+      if (typeof queryObj !== "object" || queryObj === null || Array.isArray(queryObj)) {
+        return JSON.stringify(
+          {
+            error: "Invalid query parameter",
+            suggestion: 'The query must be a JSON object with a "query_type" and a "nodes" array.'
+          },
+          null,
+          2
+        );
+      }
+      if (args.limit !== void 0) {
+        queryObj.limit = args.limit;
+      }
       const requestBody = {
-        query: queryObj
+        query: queryObj,
+        response_format: "raw"
       };
-      if (args.limit) {
-        requestBody.limit = args.limit;
-      }
       try {
         const result = await client.fetch("POST", "/orbit/query", requestBody);
         if (result.code) {
@@ -5656,7 +5787,7 @@ Returns nodes array and edges array with relationship types.`,
               error: "Query compilation error",
               code: result.code,
               message: result.message,
-              suggestion: 'Check query structure. Node "id" is a variable name, actual IDs go in filters.'
+              suggestion: 'Check query structure against the current DSL: top-level "nodes" array, pin ids with "node_ids", filters use {op: value}, and a "neighbors" query needs neighbors:{direction, rel_types} (max 10 rel_types).'
             },
             null,
             2
@@ -5704,7 +5835,7 @@ Common use cases:
 
 Note: Use GitLab internal numeric IDs (not IIDs).
 Example: For MR !123 in gitlab-org/gitlab, first get the internal ID via gitlab_get_merge_request,
-then use that ID (e.g., 377844873).`,
+then use that ID (e.g., 377844873). For epics, use the work_item_id.`,
     args: {
       entity_type: z18.string().describe(
         "Type of the entity (e.g., Project, MergeRequest, User, Pipeline, Commit, WorkItem, Group)"
@@ -5713,33 +5844,38 @@ then use that ID (e.g., 377844873).`,
         "GitLab internal numeric ID (not IID). Get this from REST/GraphQL API responses."
       ),
       direction: z18.enum(["incoming", "outgoing", "both"]).optional().describe("Direction of relationships to traverse (default: both)"),
+      rel_types: z18.array(z18.string()).optional().describe(
+        'Relationship types to follow. Required by the API to bound the lookup; if omitted, up to 10 edge types that touch the entity type are taken from gitlab_orbit_schema (with a built-in default set as fallback if the schema is unavailable). The API caps this at 10 per selector, so more than 10 entries are truncated to the first 10 and the response includes a "warnings" field. See gitlab_orbit_schema for valid edge types.'
+      ),
       limit: z18.number().optional().describe("Maximum number of neighbors to return (default: 30)")
     },
     execute: async (args, _ctx) => {
       const client = getGitLabClient();
       const direction = args.direction || "both";
+      const requestedRelTypes = args.rel_types?.length ? args.rel_types : await defaultRelTypes(client, args.entity_type);
+      const relTypes = requestedRelTypes.slice(0, MAX_REL_TYPES);
+      const warnings = requestedRelTypes.length > relTypes.length ? [`rel_types truncated to 10 (got ${requestedRelTypes.length})`] : [];
       const queryObj = {
         query_type: "neighbors",
-        node: {
-          entity: args.entity_type,
-          id: "n",
-          filters: {
-            id: { op: "eq", value: args.entity_id }
+        nodes: [
+          {
+            id: "n",
+            entity: args.entity_type,
+            node_ids: [args.entity_id]
           }
-        },
+        ],
         neighbors: {
-          node: "n",
-          direction
-        },
-        aggregations: [],
-        path: { type: "shortest", from: "n", to: "n", max_depth: 1 }
+          direction,
+          rel_types: relTypes
+        }
       };
+      if (args.limit !== void 0) {
+        queryObj.limit = args.limit;
+      }
       const requestBody = {
-        query: queryObj
+        query: queryObj,
+        response_format: "raw"
       };
-      if (args.limit) {
-        requestBody.limit = args.limit;
-      }
       try {
         const result = await client.fetch("POST", "/orbit/query", requestBody);
         if (result.code) {
@@ -5749,13 +5885,14 @@ then use that ID (e.g., 377844873).`,
               code: result.code,
               message: result.message,
               entity_type: args.entity_type,
-              entity_id: args.entity_id
+              entity_id: args.entity_id,
+              ...warnings.length > 0 && { warnings }
             },
             null,
             2
           );
         }
-        return JSON.stringify(result, null, 2);
+        return JSON.stringify(warnings.length > 0 ? { ...result, warnings } : result, null, 2);
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         if (errorMessage.includes("404") || errorMessage.includes("not found")) {