Express batch item references with oneOf

Model node, numeric, and issue references as closed schema variants while retaining runtime validation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7ae767ff-c1d0-46a9-b126-2e91403993a0

Author: zwick

README.md

@@ -1119,7 +1119,7 @@ The following sets of tools are available:
   - `item_owner`: The owner (user or organization) of the repository containing the issue or pull request. Required for 'add_project_item' method. Also accepted by 'update_project_item' when resolving the item by issue number. (string, optional)
   - `item_repo`: The name of the repository containing the issue or pull request. Required for 'add_project_item' method. Also accepted by 'update_project_item' when resolving the item by issue number. (string, optional)
   - `item_type`: The item's type, either issue or pull_request. Required for 'add_project_item' method. (string, optional)
-  - `items`: The set of items to update. Required for 'update_project_items'. Each entry references an existing item by exactly one of: 'node_id' (the item's GraphQL node ID, e.g. as returned by 'list_project_items' or 'add_project_item'), 'item_id' (the numeric project item ID), or (item_owner + item_repo + issue_number). Each entry may optionally include its own 'updated_field'; if omitted, the top-level 'updated_field' is applied. Limit: 100 items per call. (object[], optional)
+  - `items`: The items to update. Required for 'update_project_items'. Each entry must match exactly one reference variant: 'node_id', numeric 'item_id', or 'item_owner' + 'item_repo' + 'issue_number'. Each entry may include 'updated_field'; otherwise the top-level 'updated_field' applies. Limit: 100 items per call. (object[], optional)
   - `iteration_duration`: Duration in days for iterations of the field (e.g. 7 for weekly, 14 for bi-weekly). Required for 'create_iteration_field' method. (number, optional)
   - `iterations`: Custom iterations for 'create_iteration_field' method. Only set this when you need iterations with varying durations, breaks between them, or specific titles. Otherwise omit it: GitHub auto-creates three iterations of 'iteration_duration' days starting on 'start_date', which is the right choice for most cases. (object[], optional)
   - `method`: The method to execute (string, required)

pkg/github/__toolsnaps__/projects_write.snap

@@ -41,35 +41,71 @@
         "type": "string"
       },
       "items": {
-        "description": "The set of items to update. Required for 'update_project_items'. Each entry references an existing item by exactly one of: 'node_id' (the item's GraphQL node ID, e.g. as returned by 'list_project_items' or 'add_project_item'), 'item_id' (the numeric project item ID), or (item_owner + item_repo + issue_number). Each entry may optionally include its own 'updated_field'; if omitted, the top-level 'updated_field' is applied. Limit: 100 items per call.",
+        "description": "The items to update. Required for 'update_project_items'. Each entry must match exactly one reference variant: 'node_id', numeric 'item_id', or 'item_owner' + 'item_repo' + 'issue_number'. Each entry may include 'updated_field'; otherwise the top-level 'updated_field' applies. Limit: 100 items per call.",
         "items": {
-          "additionalProperties": false,
-          "properties": {
-            "issue_number": {
-              "description": "Issue number used to resolve the project item together with item_owner and item_repo.",
-              "type": "integer"
-            },
-            "item_id": {
-              "description": "The project item ID. Provide exactly one of node_id, item_id, or (item_owner + item_repo + issue_number).",
-              "type": "integer"
-            },
-            "item_owner": {
-              "description": "Owner of the repository containing the issue. Combine with item_repo and issue_number to resolve the item.",
-              "type": "string"
-            },
-            "item_repo": {
-              "description": "Repository containing the issue. Combine with item_owner and issue_number to resolve the item.",
-              "type": "string"
+          "oneOf": [
+            {
+              "additionalProperties": false,
+              "properties": {
+                "node_id": {
+                  "description": "The project item's GraphQL node ID, as returned by 'list_project_items' or 'add_project_item'.",
+                  "type": "string"
+                },
+                "updated_field": {
+                  "description": "Per-item field update. Overrides the top-level 'updated_field'. Same shape as the top-level 'updated_field'.",
+                  "type": "object"
+                }
+              },
+              "required": [
+                "node_id"
+              ],
+              "type": "object"
             },
-            "node_id": {
-              "description": "The project item's GraphQL node ID. Provide exactly one of node_id, item_id, or (item_owner + item_repo + issue_number).",
-              "type": "string"
+            {
+              "additionalProperties": false,
+              "properties": {
+                "item_id": {
+                  "description": "The numeric project item ID.",
+                  "type": "integer"
+                },
+                "updated_field": {
+                  "description": "Per-item field update. Overrides the top-level 'updated_field'. Same shape as the top-level 'updated_field'.",
+                  "type": "object"
+                }
+              },
+              "required": [
+                "item_id"
+              ],
+              "type": "object"
             },
-            "updated_field": {
-              "description": "Per-item field update. Overrides the top-level 'updated_field'. Same shape as the top-level 'updated_field'.",
+            {
+              "additionalProperties": false,
+              "properties": {
+                "issue_number": {
+                  "description": "Issue number used to resolve the project item.",
+                  "type": "integer"
+                },
+                "item_owner": {
+                  "description": "Owner of the repository containing the issue.",
+                  "type": "string"
+                },
+                "item_repo": {
+                  "description": "Repository containing the issue.",
+                  "type": "string"
+                },
+                "updated_field": {
+                  "description": "Per-item field update. Overrides the top-level 'updated_field'. Same shape as the top-level 'updated_field'.",
+                  "type": "object"
+                }
+              },
+              "required": [
+                "item_owner",
+                "item_repo",
+                "issue_number"
+              ],
               "type": "object"
             }
-          },
+          ],
           "type": "object"
         },
         "type": "array"

pkg/github/projects.go

@@ -32,10 +32,7 @@ const (
 	ProjectStatusUpdateCreateFailedError = "failed to create project status update"
 	ProjectResolveIDFailedError          = "failed to resolve project ID"
 	MaxProjectsPerPage                   = 50
-	// MaxProjectItemsPerBatch caps the number of items processed in a single
-	// update_project_items call. This keeps a batch bounded, prevents runaway
-	// resolution costs, and matches the practical scale of typical triage sweeps.
-	MaxProjectItemsPerBatch = 100
+	maxProjectItemsPerBatch              = 100
 )
 
 // Method constants for consolidated project tools
@@ -495,6 +492,54 @@ Use this tool to get details about individual projects, project fields, and proj
 	return tool
 }
 
+func updateProjectItemsItemSchema() *jsonschema.Schema {
+	updatedField := &jsonschema.Schema{
+		Type:        "object",
+		Description: "Per-item field update. Overrides the top-level 'updated_field'. Same shape as the top-level 'updated_field'.",
+	}
+	variant := func(required []string, properties map[string]*jsonschema.Schema) *jsonschema.Schema {
+		properties["updated_field"] = updatedField
+		return &jsonschema.Schema{
+			Type:                 "object",
+			AdditionalProperties: &jsonschema.Schema{Not: &jsonschema.Schema{}},
+			Properties:           properties,
+			Required:             required,
+		}
+	}
+
+	return &jsonschema.Schema{
+		Type: "object",
+		OneOf: []*jsonschema.Schema{
+			variant([]string{"node_id"}, map[string]*jsonschema.Schema{
+				"node_id": {
+					Type:        "string",
+					Description: "The project item's GraphQL node ID, as returned by 'list_project_items' or 'add_project_item'.",
+				},
+			}),
+			variant([]string{"item_id"}, map[string]*jsonschema.Schema{
+				"item_id": {
+					Type:        "integer",
+					Description: "The numeric project item ID.",
+				},
+			}),
+			variant([]string{"item_owner", "item_repo", "issue_number"}, map[string]*jsonschema.Schema{
+				"item_owner": {
+					Type:        "string",
+					Description: "Owner of the repository containing the issue.",
+				},
+				"item_repo": {
+					Type:        "string",
+					Description: "Repository containing the issue.",
+				},
+				"issue_number": {
+					Type:        "integer",
+					Description: "Issue number used to resolve the project item.",
+				},
+			}),
+		},
+	}
+}
+
 // ProjectsWrite returns the tool and handler for modifying GitHub Projects resources.
 func ProjectsWrite(t translations.TranslationHelperFunc) inventory.ServerTool {
 	tool := NewTool(
@@ -571,37 +616,8 @@ func ProjectsWrite(t translations.TranslationHelperFunc) inventory.ServerTool {
 					},
 					"items": {
 						Type:        "array",
-						Description: "The set of items to update. Required for 'update_project_items'. Each entry references an existing item by exactly one of: 'node_id' (the item's GraphQL node ID, e.g. as returned by 'list_project_items' or 'add_project_item'), 'item_id' (the numeric project item ID), or (item_owner + item_repo + issue_number). Each entry may optionally include its own 'updated_field'; if omitted, the top-level 'updated_field' is applied. Limit: " + strconv.Itoa(MaxProjectItemsPerBatch) + " items per call.",
-						Items: &jsonschema.Schema{
-							Type:                 "object",
-							AdditionalProperties: &jsonschema.Schema{Not: &jsonschema.Schema{}},
-							Properties: map[string]*jsonschema.Schema{
-								"node_id": {
-									Type:        "string",
-									Description: "The project item's GraphQL node ID. Provide exactly one of node_id, item_id, or (item_owner + item_repo + issue_number).",
-								},
-								"item_id": {
-									Type:        "integer",
-									Description: "The project item ID. Provide exactly one of node_id, item_id, or (item_owner + item_repo + issue_number).",
-								},
-								"item_owner": {
-									Type:        "string",
-									Description: "Owner of the repository containing the issue. Combine with item_repo and issue_number to resolve the item.",
-								},
-								"item_repo": {
-									Type:        "string",
-									Description: "Repository containing the issue. Combine with item_owner and issue_number to resolve the item.",
-								},
-								"issue_number": {
-									Type:        "integer",
-									Description: "Issue number used to resolve the project item together with item_owner and item_repo.",
-								},
-								"updated_field": {
-									Type:        "object",
-									Description: "Per-item field update. Overrides the top-level 'updated_field'. Same shape as the top-level 'updated_field'.",
-								},
-							},
-						},
+						Description: "The items to update. Required for 'update_project_items'. Each entry must match exactly one reference variant: 'node_id', numeric 'item_id', or 'item_owner' + 'item_repo' + 'issue_number'. Each entry may include 'updated_field'; otherwise the top-level 'updated_field' applies. Limit: " + strconv.Itoa(maxProjectItemsPerBatch) + " items per call.",
+						Items:       updateProjectItemsItemSchema(),
 					},
 					"body": {
 						Type:        "string",

pkg/github/projects_batch.go

@@ -81,8 +81,8 @@ func updateProjectItemsBatch(ctx context.Context, client *github.Client, gqlClie
 	if len(itemsRaw) == 0 {
 		return utils.NewToolResultError("items must contain at least one entry"), nil, nil
 	}
-	if len(itemsRaw) > MaxProjectItemsPerBatch {
-		return utils.NewToolResultError(fmt.Sprintf("items exceeds maximum of %d entries per call (got %d)", MaxProjectItemsPerBatch, len(itemsRaw))), nil, nil
+	if len(itemsRaw) > maxProjectItemsPerBatch {
+		return utils.NewToolResultError(fmt.Sprintf("items exceeds maximum of %d entries per call (got %d)", maxProjectItemsPerBatch, len(itemsRaw))), nil, nil
 	}
 
 	var sharedField map[string]any

pkg/github/projects_batch_e2e_test.go

@@ -57,7 +57,7 @@ func projectIDMatcher(owner string, projectNumber int, projectNodeID string) git
 }
 
 func Test_UpdateProjectItemsBatch_TopLevelGuards(t *testing.T) {
-	tooMany := make([]any, MaxProjectItemsPerBatch+1)
+	tooMany := make([]any, maxProjectItemsPerBatch+1)
 	validItem := map[string]any{
 		"node_id":       "PVTI_item1",
 		"updated_field": map[string]any{"name": "Notes", "value": "hello"},

pkg/github/projects_batch_mutation.go

@@ -11,7 +11,7 @@ import (
 )
 
 // batchMutationWireChunkSize bounds how many aliased mutations are sent per
-// GraphQL request. It is smaller than MaxProjectItemsPerBatch (100 items/call)
+// GraphQL request. It is smaller than maxProjectItemsPerBatch (100 items/call)
 // to leave headroom under typical ~10s gateway/client timeouts. This value is
 // provisional, not derived from a measured benchmark against the live API.
 const batchMutationWireChunkSize = 20

pkg/github/projects_test.go

@@ -888,6 +888,42 @@ func Test_ProjectsWrite(t *testing.T) {
 	assert.True(t, *toolDef.Tool.Annotations.DestructiveHint)
 }
 
+func Test_ProjectsWrite_UpdateProjectItemsItemSchema(t *testing.T) {
+	inputSchema := ProjectsWrite(translations.NullTranslationHelper).Tool.InputSchema.(*jsonschema.Schema)
+	itemSchema := inputSchema.Properties["items"].Items
+
+	assert.Equal(t, "object", itemSchema.Type)
+	assert.Empty(t, itemSchema.Properties, "item references should be modeled by oneOf, not flattened properties")
+	require.Len(t, itemSchema.OneOf, 3)
+
+	expectedRequired := [][]string{
+		{"node_id"},
+		{"item_id"},
+		{"item_owner", "item_repo", "issue_number"},
+	}
+	expectedProperties := [][]string{
+		{"node_id", "updated_field"},
+		{"item_id", "updated_field"},
+		{"item_owner", "item_repo", "issue_number", "updated_field"},
+	}
+	for i, variant := range itemSchema.OneOf {
+		properties := make([]string, 0, len(variant.Properties))
+		for name := range variant.Properties {
+			properties = append(properties, name)
+		}
+		assert.Equal(t, "object", variant.Type)
+		assert.ElementsMatch(t, expectedRequired[i], variant.Required)
+		assert.ElementsMatch(t, expectedProperties[i], properties)
+		assert.Contains(t, variant.Properties, "updated_field")
+		for _, property := range variant.Properties {
+			assert.NotEmpty(t, property.Type)
+			assert.NotEmpty(t, property.Description)
+		}
+		require.NotNil(t, variant.AdditionalProperties)
+		assert.NotNil(t, variant.AdditionalProperties.Not, "variant must reject additional properties")
+	}
+}
+
 func Test_ProjectsWrite_AddProjectItem(t *testing.T) {
 	toolDef := ProjectsWrite(translations.NullTranslationHelper)