@reventlessdev/reventless-core 3.0.0-alpha.165 → 3.0.0-alpha.166

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.166 (2026-07-14)
+
+### Features
+
+* **api:** merge-path codegen — stitchStandalone subgraph SDL + [@canonical](https://github.com/canonical) stamping (Phase 2) ([02ae93b](https://github.com/ReventlessDev/reventless-core/commit/02ae93b1c84a116ae47fb656cab17858a5df2c97))
+
+
 # 3.0.0-alpha.165 (2026-07-13)
 
 **Note:** Version bump only for package @reventlessdev/reventless-core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.165",
+  "version": "3.0.0-alpha.166",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -31,14 +31,14 @@
     "@reventlessdev/rescript-effect": "0.1.0-alpha.27",
     "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.12",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.11",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.7",
     "@reventlessdev/rescript-node-streams": "1.1.0-alpha.11",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.7",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.15",
     "@reventlessdev/rescript-ssh2": "1.1.0-alpha.12",
     "@reventlessdev/rescript-uuid": "1.1.0-alpha.15",
     "@reventlessdev/reventless-infra": "3.0.0-alpha.98",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.76",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.26"
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.26",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.76"
   },
   "devDependencies": {
     "rescript": "^12.3.0",

package/src/components/Api/GraphQL_Stitcher.res

@@ -172,21 +172,23 @@ let relayBaseQueries = [
 ]
 
 /**
-Stitch a base fragment with plugin fragments into a complete GraphQL SDL string.
+Assemble fragments into a complete GraphQL SDL string.
 
-- Base fragment is always first (defines core types + Plugin mutations/queries).
-- Plugin fragments add their own types, mutations, and queries.
+- Fragments are processed in order (first wins on collisions).
 - Collision detection: duplicate type definitions and field names are logged and skipped.
-- Relay base types (Node interface, PageInfo) and node query are always injected.
+- Relay base types (Node interface, PageInfo) are always injected; the global
+  `node` query only when `includeGlobalNodeQuery` (stitched schemas yes,
+  standalone subgraph documents no).
 
 Returns the full SDL string ready for use with AppSync or graphql-yoga.
+Public entry points: `stitch` (base + plugins, the whole-schema path) and
+`stitchStandalone` (one fragment as a self-contained subgraph document).
 */
-let stitch = (
-  ~baseFragment: Reventless.Plugin.apiSchemaFragment,
-  ~pluginFragments: array<Reventless.Plugin.apiSchemaFragment>,
+let assembleSdl = (
+  ~fragments: array<Reventless.Plugin.apiSchemaFragment>,
+  ~includeGlobalNodeQuery: bool,
 ): string => {
-  let allFragments = Array.concat([baseFragment], pluginFragments)
-  let parts = allFragments->Array.map(decode)
+  let parts = fragments->Array.map(decode)
 
   // Collect all type definitions — detect collisions by type name
   // Start with Relay base types (Node interface, PageInfo)
@@ -229,14 +231,18 @@ let stitch = (
   )
 
   // Collect all query fields — detect collisions by field name
-  // Start with Relay node query
+  // Start with Relay node query (single-resolver-owned: omitted from
+  // standalone subgraph documents, where the platform's canonical source
+  // owns the global `node` field)
   let seenQueryFields: Set.t<string> = Set.make()
   let allQueries: array<string> = []
-  relayBaseQueries->Array.forEach(field => {
-    let fieldName = extractLeadingName(field)
-    seenQueryFields->Set.add(fieldName)
-    allQueries->Array.push(field)
-  })
+  if includeGlobalNodeQuery {
+    relayBaseQueries->Array.forEach(field => {
+      let fieldName = extractLeadingName(field)
+      seenQueryFields->Set.add(fieldName)
+      allQueries->Array.push(field)
+    })
+  }
 
   parts->Array.forEach(({queries}) =>
     queries->Array.forEach(field => {
@@ -291,6 +297,26 @@ let stitch = (
   sdlParts->Array.join("\n\n")
 }
 
+let stitch = (
+  ~baseFragment: Reventless.Plugin.apiSchemaFragment,
+  ~pluginFragments: array<Reventless.Plugin.apiSchemaFragment>,
+): string =>
+  assembleSdl(
+    ~fragments=Array.concat([baseFragment], pluginFragments),
+    ~includeGlobalNodeQuery=true,
+  )
+
+/**
+Render ONE fragment as a standalone schema document for merge-based
+composition (plugin = subgraph, platform = merge). The relay base types are
+included so the document is self-contained and valid on its own; the global
+`node(id: ID!)` root query is omitted — exactly one source (the platform's
+canonical one) may own that field's resolver, so only the canonical base
+document carries it (via `stitch`).
+*/
+let stitchStandalone = (~fragment: Reventless.Plugin.apiSchemaFragment): string =>
+  assembleSdl(~fragments=[fragment], ~includeGlobalNodeQuery=false)
+
 let isIdentStart = (line: string): bool =>
   switch line->String.codePointAt(0) {
   // A-Z (65-90), a-z (97-122), or `_` (95)

package/src/components/Api/GraphQL_Stitcher.res.mjs

@@ -132,9 +132,8 @@ let relayBaseTypes = [
 
 let relayBaseQueries = [`  node(id: ID!): Node`];
 
-function stitch(baseFragment, pluginFragments) {
-  let allFragments = [baseFragment].concat(pluginFragments);
-  let parts = allFragments.map(decode);
+function assembleSdl(fragments, includeGlobalNodeQuery) {
+  let parts = fragments.map(decode);
   let seenTypeNames = new Set();
   let allTypes = [];
   relayBaseTypes.forEach(typeDef => {
@@ -173,11 +172,13 @@ function stitch(baseFragment, pluginFragments) {
   });
   let seenQueryFields = new Set();
   let allQueries = [];
-  relayBaseQueries.forEach(field => {
-    let fieldName = extractLeadingName(field);
-    seenQueryFields.add(fieldName);
-    allQueries.push(field);
-  });
+  if (includeGlobalNodeQuery) {
+    relayBaseQueries.forEach(field => {
+      let fieldName = extractLeadingName(field);
+      seenQueryFields.add(fieldName);
+      allQueries.push(field);
+    });
+  }
   parts.forEach(param => {
     param.queries.forEach(field => {
       let fieldName = extractLeadingName(field);
@@ -217,6 +218,14 @@ function stitch(baseFragment, pluginFragments) {
   return sdlParts.join("\n\n");
 }
 
+function stitch(baseFragment, pluginFragments) {
+  return assembleSdl([baseFragment].concat(pluginFragments), true);
+}
+
+function stitchStandalone(fragment) {
+  return assembleSdl([fragment], false);
+}
+
 function isIdentStart(line) {
   let c = line.codePointAt(0);
   if (c !== undefined) {
@@ -308,7 +317,9 @@ export {
   extractLeadingName,
   relayBaseTypes,
   relayBaseQueries,
+  assembleSdl,
   stitch,
+  stitchStandalone,
   isIdentStart,
   rootTypeFieldNames,
   countRootTypeFields,

package/tests/api/GraphQL_StitcherTest.res

@@ -261,3 +261,35 @@ describe("GraphQL_Stitcher.subscriptionSources", () => {
     expect(fields->Array.includes("onPluginStatusChange"))->toBe(true)
   })
 })
+
+describe("GraphQL_Stitcher.stitchStandalone", () => {
+  let pluginFragment = encode({
+    types: [
+      `type Product implements Node {\n  id: ID!\n  name: String\n}`,
+      `union CommandResult = CommandAccepted | CommandRejected | CommandPending`,
+    ],
+    mutations: [`  Catalog_AddProduct(input: AddInput): CommandResult`],
+    queries: [`  Catalog_products: [Product]`],
+    subscriptions: [`  onCatalog_AddProduct(id: ID): CommandResult`],
+    subscriptionSources: [{field: "onCatalog_AddProduct", mutations: ["Catalog_AddProduct"]}],
+  })
+
+  testSync("renders a self-contained subgraph document with relay base types", () => {
+    let sdl = stitchStandalone(~fragment=pluginFragment)
+    expect(sdl)->toContain("interface Node {")
+    expect(sdl)->toContain("type PageInfo {")
+    expect(sdl)->toContain("type Product implements Node {")
+    expect(sdl)->toContain("Catalog_AddProduct(input: AddInput): CommandResult")
+    expect(sdl)->toContain("onCatalog_AddProduct(id: ID): CommandResult")
+  })
+
+  testSync("omits the global node query (the canonical base document owns it)", () => {
+    let sdl = stitchStandalone(~fragment=pluginFragment)
+    expect(sdl->String.includes("node(id: ID!): Node"))->toBe(false)
+  })
+
+  testSync("stitch keeps injecting the global node query (whole-schema path unchanged)", () => {
+    let sdl = stitch(~baseFragment=pluginFragment, ~pluginFragments=[])
+    expect(sdl)->toContain("node(id: ID!): Node")
+  })
+})

package/tests/api/GraphQL_StitcherTest.res.mjs

@@ -240,6 +240,38 @@ globalThis.describe("GraphQL_Stitcher.subscriptionSources", () => {
   });
 });
 
+globalThis.describe("GraphQL_Stitcher.stitchStandalone", () => {
+  let pluginFragment = GraphQL_Stitcher$ReventlessCore.encode({
+    types: [
+      `type Product implements Node {\n  id: ID!\n  name: String\n}`,
+      `union CommandResult = CommandAccepted | CommandRejected | CommandPending`
+    ],
+    mutations: [`  Catalog_AddProduct(input: AddInput): CommandResult`],
+    queries: [`  Catalog_products: [Product]`],
+    subscriptions: [`  onCatalog_AddProduct(id: ID): CommandResult`],
+    subscriptionSources: [{
+        field: "onCatalog_AddProduct",
+        mutations: ["Catalog_AddProduct"]
+      }]
+  });
+  globalThis.test("renders a self-contained subgraph document with relay base types", () => {
+    let sdl = GraphQL_Stitcher$ReventlessCore.stitchStandalone(pluginFragment);
+    globalThis.expect(sdl).toContain("interface Node {");
+    globalThis.expect(sdl).toContain("type PageInfo {");
+    globalThis.expect(sdl).toContain("type Product implements Node {");
+    globalThis.expect(sdl).toContain("Catalog_AddProduct(input: AddInput): CommandResult");
+    globalThis.expect(sdl).toContain("onCatalog_AddProduct(id: ID): CommandResult");
+  });
+  globalThis.test("omits the global node query (the canonical base document owns it)", () => {
+    let sdl = GraphQL_Stitcher$ReventlessCore.stitchStandalone(pluginFragment);
+    globalThis.expect(sdl.includes("node(id: ID!): Node")).toBe(false);
+  });
+  globalThis.test("stitch keeps injecting the global node query (whole-schema path unchanged)", () => {
+    let sdl = GraphQL_Stitcher$ReventlessCore.stitch(pluginFragment, []);
+    globalThis.expect(sdl).toContain("node(id: ID!): Node");
+  });
+});
+
 export {
   fullSchemaSdl,
   collapsedSchemaSdl,