fix: schema version by commit (#7155)

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: jdolle

.changeset/late-feet-write.md

@@ -0,0 +1,6 @@
+---
+'@graphql-hive/cli': minor
+'hive': minor
+---
+
+add schemaVersionByCommit; update docs and cli; fix webhook commit reference

integration-tests/testkit/cli.ts

@@ -298,13 +298,13 @@ export function createCLI(tokens: { readwrite: string; readonly: string }) {
     ]);
   }
 
-  async function fetchCmd(input: { type: 'subgraphs' | 'supergraph' | 'sdl'; actionId?: string }) {
+  async function fetchCmd(input: { type: 'subgraphs' | 'supergraph' | 'sdl'; commit?: string }) {
     const cmd = schemaFetch([
       '--token',
       tokens.readwrite,
       '--type',
       input.type,
-      ...(input.actionId ? [input.actionId] : []),
+      ...(input.commit ? [input.commit] : []),
     ]);
 
     return cmd;

integration-tests/tests/api/schema/schema-version.spec.ts

@@ -1,12 +1,11 @@
-import { waitFor } from 'testkit/flow';
 import { ProjectType } from 'testkit/gql/graphql';
 import { graphql } from '../../../testkit/gql';
 import { execute } from '../../../testkit/graphql';
 import { initSeed } from '../../../testkit/seed';
 
-const SchemaByActionIdQuery = graphql(/* GraphQL */ `
-  query SchemaByActionIdQuery($actionId: ID!, $targetRef: TargetReferenceInput) {
-    schemaVersionForActionId(actionId: $actionId, target: $targetRef) {
+const SchemaByCommitQuery = graphql(/* GraphQL */ `
+  query SchemaByCommitQuery($commit: String!, $targetRef: TargetReferenceInput) {
+    schemaVersionByCommit(commit: $commit, target: $targetRef) {
       id
       sdl
       log {
@@ -20,9 +19,9 @@ const SchemaByActionIdQuery = graphql(/* GraphQL */ `
 `);
 
 test.concurrent(
-  'schema version by actionId returns latest schema for the actionId',
+  'schema version by commit returns latest schema for the commit',
   async ({ expect }) => {
-    const actionId = 'tiny-test-0';
+    const commit = 'tiny-test-0';
     const schema = /* GraphQL */ `
       type Query {
         ping: String
@@ -45,26 +44,26 @@ test.concurrent(
     await token
       .publishSchema({
         sdl: schema,
-        commit: actionId,
+        commit,
       })
       .then(r => r.expectNoGraphQLErrors());
 
     await token
       .publishSchema({
         sdl: latestSchema,
-        commit: actionId,
+        commit,
       })
       .then(r => r.expectNoGraphQLErrors());
 
     const result = await execute({
-      document: SchemaByActionIdQuery,
+      document: SchemaByCommitQuery,
       token: token.secret,
       variables: {
-        actionId,
+        commit,
         targetRef: { byId: target.id },
       },
     }).then(r => r.expectNoGraphQLErrors());
 
-    expect(result.schemaVersionForActionId?.sdl).toIncludeSubstringWithoutWhitespace(latestSchema);
+    expect(result.schemaVersionByCommit?.sdl).toIncludeSubstringWithoutWhitespace(latestSchema);
   },
 );

integration-tests/tests/cli/schema.spec.ts

@@ -503,7 +503,7 @@ describe.each([ProjectType.Stitching, ProjectType.Federation, ProjectType.Single
         const numSchemas = schema.latestVersion?.schemas.nodes.length;
         const fetchCmd = cli.fetch({
           type: 'subgraphs',
-          actionId: 'abc123',
+          commit: 'abc123',
         });
         const rHeader = `service\\s+url\\s+date`;
         const rUrl = `http:\\/\\/\\S+(:\\d+)?|n/a`;

packages/libraries/cli/README.md

@@ -47,7 +47,7 @@ curl -sSL https://graphql-hive.com/install.sh | sh
 - [`hive operations:check FILE`](#hive-operationscheck-file)
 - [`hive schema:check FILE`](#hive-schemacheck-file)
 - [`hive schema:delete SERVICE`](#hive-schemadelete-service)
-- [`hive schema:fetch [ACTIONID]`](#hive-schemafetch-actionid)
+- [`hive schema:fetch [COMMIT]`](#hive-schemafetch-commit)
 - [`hive schema:publish FILE`](#hive-schemapublish-file)
 - [`hive update [CHANNEL]`](#hive-update-channel)
 - [`hive whoami`](#hive-whoami)
@@ -355,17 +355,17 @@ DESCRIPTION
 _See code:
 [src/commands/schema/delete.ts](https://github.com/graphql-hive/platform/blob/v0.50.2/src/commands/schema/delete.ts)_
 
-## `hive schema:fetch [ACTIONID]`
+## `hive schema:fetch [COMMIT]`
 
 fetch a schema, supergraph, or list of subgraphs from the Hive API
 
 ```
 USAGE
-  $ hive schema:fetch [ACTIONID] [--debug] [--registry <value>] [--token <value>] [--registry.endpoint <value>]
+  $ hive schema:fetch [COMMIT] [--debug] [--registry <value>] [--token <value>] [--registry.endpoint <value>]
     [--registry.accessToken <value>] [--type <value>] [--write <value>] [--outputFile <value>] [--target <value>]
 
 ARGUMENTS
-  ACTIONID  action id (e.g. commit sha)
+  COMMIT  commit SHA (or optionally any other external identifier)
 
 FLAGS
   --debug                         Whether debug output for HTTP calls and similar should be enabled.

packages/libraries/cli/src/commands/schema/fetch.ts

@@ -16,15 +16,15 @@ import {
 import * as TargetInput from '../../helpers/target-input';
 import { Texture } from '../../helpers/texture/texture';
 
-const SchemaVersionForActionIdQuery = graphql(/* GraphQL */ `
-  query SchemaVersionForActionId(
-    $actionId: ID!
+const SchemaVersionByCommitQuery = graphql(/* GraphQL */ `
+  query SchemaVersionByCommit(
+    $commit: String!
     $includeSDL: Boolean!
     $includeSupergraph: Boolean!
     $includeSubgraphs: Boolean!
     $target: TargetReferenceInput
   ) {
-    schemaVersionForActionId(actionId: $actionId, target: $target) {
+    schemaVersionByCommit(commit: $commit, target: $target) {
       id
       isValid
       sdl @include(if: $includeSDL)
@@ -128,9 +128,9 @@ export default class SchemaFetch extends Command<typeof SchemaFetch> {
   };
 
   static args = {
-    actionId: Args.string({
-      name: 'actionId' as const,
-      description: 'action id (e.g. commit sha)',
+    commit: Args.string({
+      name: 'commit' as const,
+      description: 'commit SHA, or it can be any external ID that references the schema',
       hidden: false,
     }),
   };
@@ -163,7 +163,7 @@ export default class SchemaFetch extends Command<typeof SchemaFetch> {
       throw new MissingRegistryTokenError();
     }
 
-    const { actionId } = args;
+    const { commit } = args;
 
     const sdlType = this.ensure({
       // eslint-disable-next-line @typescript-eslint/ban-ts-comment
@@ -185,18 +185,18 @@ export default class SchemaFetch extends Command<typeof SchemaFetch> {
     }
 
     let schemaVersion;
-    if (actionId) {
+    if (commit) {
       const result = await this.registryApi(endpoint, accessToken).request({
-        operation: SchemaVersionForActionIdQuery,
+        operation: SchemaVersionByCommitQuery,
         variables: {
-          actionId,
+          commit,
           includeSDL: sdlType === 'sdl',
           includeSupergraph: sdlType === 'supergraph',
           includeSubgraphs: sdlType === 'subgraphs',
           target,
         },
       });
-      schemaVersion = result.schemaVersionForActionId;
+      schemaVersion = result.schemaVersionByCommit;
     } else {
       const result = await this.registryApi(endpoint, accessToken).request({
         operation: LatestSchemaVersionQuery,
@@ -211,11 +211,11 @@ export default class SchemaFetch extends Command<typeof SchemaFetch> {
     }
 
     if (schemaVersion == null) {
-      throw new SchemaNotFoundError(actionId);
+      throw new SchemaNotFoundError(commit);
     }
 
     if (schemaVersion.isValid === false) {
-      throw new InvalidSchemaError(actionId);
+      throw new InvalidSchemaError(commit);
     }
 
     if (schemaVersion.schemas) {
@@ -239,7 +239,7 @@ export default class SchemaFetch extends Command<typeof SchemaFetch> {
       const schema = schemaVersion.sdl ?? schemaVersion.supergraph;
 
       if (schema == null) {
-        throw new SchemaNotFoundError(actionId);
+        throw new SchemaNotFoundError(commit);
       }
 
       if (flags.write) {

packages/libraries/cli/src/commands/schema/publish.ts

@@ -111,7 +111,8 @@ export default class SchemaPublish extends Command<typeof SchemaPublish> {
       description: 'author of the change',
     }),
     commit: Flags.string({
-      description: 'associated commit sha',
+      description:
+        'The associated commit SHA, or optionally any external identifier that references the schema',
     }),
     github: Flags.boolean({
       description: 'Connect with GitHub Application',

packages/libraries/cli/src/helpers/errors.ts

@@ -397,21 +397,21 @@ export class InvalidTargetError extends HiveCLIError {
 }
 
 export class SchemaNotFoundError extends HiveCLIError {
-  constructor(actionId?: string) {
+  constructor(commit?: string) {
     super(
       ExitCode.ERROR,
       errorCode(ErrorCategory.ARTIFACT_FETCH, 0),
-      `No schema found${actionId ? ` for action id ${actionId}.` : '.'}`,
+      `No schema found${commit ? ` for commit ${commit}.` : '.'}`,
     );
   }
 }
 
 export class InvalidSchemaError extends HiveCLIError {
-  constructor(actionId?: string) {
+  constructor(commit?: string) {
     super(
       ExitCode.ERROR,
       errorCode(ErrorCategory.ARTIFACT_FETCH, 1),
-      `Schema is invalid${actionId ? ` for action id ${actionId}.` : '.'}`,
+      `Schema is invalid${commit ? ` for commit ${commit}.` : '.'}`,
     );
   }
 }

packages/services/api/src/modules/schema/module.graphql.ts

@@ -27,6 +27,12 @@ export default gql`
 
   extend type Query {
     schemaVersionForActionId(actionId: ID!, target: TargetReferenceInput): SchemaVersion
+      @deprecated(reason: "Use Query.schemaVersionByCommit")
+
+    """
+    Returns the latest SchemaVersion associated with a specific commit
+    """
+    schemaVersionByCommit(commit: String!, target: TargetReferenceInput): SchemaVersion
     latestValidVersion(target: TargetReferenceInput): SchemaVersion
     """
     Requires API Token

packages/services/api/src/modules/schema/providers/schema-manager.ts

@@ -977,8 +977,8 @@ export class SchemaManager {
     });
   }
 
-  async getSchemaVersionByActionId(args: {
-    actionId: string;
+  async getSchemaVersionByCommit(args: {
+    commit: string;
     target: GraphQLSchema.TargetReferenceInput | null;
   }) {
     const selector = await this.idTranslator.resolveTargetReference({
@@ -989,10 +989,10 @@ export class SchemaManager {
       this.session.raise('project:describe');
     }
 
-    this.logger.debug('Fetch schema version by action id. (args=%o)', {
+    this.logger.debug('Fetch schema version by commit. (args=%o)', {
       projectId: selector.projectId,
       targetId: selector.targetId,
-      actionId: args.actionId,
+      commit: args.commit,
     });
 
     await this.session.assertPerformAction({
@@ -1004,10 +1004,10 @@ export class SchemaManager {
       },
     });
 
-    const record = await this.storage.getSchemaVersionByActionId({
+    const record = await this.storage.getSchemaVersionByCommit({
       projectId: selector.projectId,
       targetId: selector.targetId,
-      actionId: args.actionId,
+      commit: args.commit,
     });
 
     if (!record) {