Add GraphQL Operation Validation for Bulk Operations CLI

[ericlee878]

Resolves: https://github.com/orgs/shop/projects/208/views/34?pane=issue&itemId=139461468&issue=shop%7Cissues-api-foundations%7C1114 and https://github.com/orgs/shop/projects/208/views/34?pane=issue&itemId=139446074&issue=shop%7Cissues-api-foundations%7C1112

Why are these changes introduced?

Improves the validation and error handling for GraphQL operations in the bulk operations service.

Implementation Details

• Enhances GraphQL document validation to ensure exactly one operation definition is present (error handling for cases that don't have exactly one operation)
• Additional unit tests added that prove core automatically rejects malformed documents (we don't have to do this).
• Created new validateGraphQLDocument() function that consolidates all GraphQL validation in one place:
  • Validates exactly one operation definition exists
  • Validates --variables flag is only used with mutations
  • Checks if the operation is a mutation (returns boolean that is used later). This replaces the previous isMutation() function.

Testing

Unit tests in execute-bulk-operation.test.ts

[ericlee878]

• Use ensureAuthenticatedAdminAsApp in shopify app execute #6643 : 2 dependent PRs (#6663 , #6667 )
• Add --variable-file flag for bulk operation mutations #6636
• Add GraphQL Operation Validation for Bulk Operations CLI #6632 👈 (View in Graphite)
• Add erroring for when variables are given for a BulkOps query #6622
• Implement mutation support for BulkOps CLI command #6596
• Initial Setup: Bulk Operations Infrastructure for Shopify CLI  #6588 : 1 other dependent PR (#6595 )
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

We detected some changes at packages/*/src and there are no updates in the .changeset.
If the changes are user-facing, run pnpm changeset add to track your changes and include them in the next release CHANGELOG.

Caution

DO NOT create changesets for features which you do not wish to be included in the public changelog of the next CLI release.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	79.2% (-0.03% 🔻)	13652/17237
🟡	Branches	73.09% (-0.02% 🔻)	6651/9100
🟡	Functions	79.35% (-0.02% 🔻)	3520/4436
🟡	Lines	79.56% (-0.02% 🔻)	12894/16207

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / bulk-operation-run-mutation.ts	100%	100%	100%	100%
🟢	... / bulk-operation-run-query.ts	100%	100%	100%	100%
🟢	... / staged-uploads-create.ts	100%	100%	100%	100%
🟢	... / execute-bulk-operation.ts	96.15%	87.5%	100%	95.83%
🟢	... / run-mutation.ts	100%	100%	100%	100%
🟢	... / run-query.ts	100%	100%	100%	100%
🟡	... / stage-file.ts	74.29%	53.33%	85.71%	73.53%

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🟢	... / ConcurrentOutput.tsx	98.36% (-1.64% 🔻)	92% (-4% 🔻)	100%	98.33% (-1.67% 🔻)
🔴	... / ui.tsx	50.82% (-0.79% 🔻)	42.86% (-5.53% 🔻)	54.55% (+1.42% 🔼)	50% (-0.82% 🔻)
🟡	... / theme-environment.ts	69.57% (-1.86% 🔻)	50%	55.56% (-3.27% 🔻)	69.57% (-1.86% 🔻)

Test suite run success

3371 tests passing in 1380 suites.

Report generated by 🧪jest coverage report action from c316242

[github-actions]

Differences in type declarations

We detected differences in the type declarations generated by Typescript for this branch compared to the baseline ('main' branch). Please, review them to ensure they are backward-compatible. Here are some important things to keep in mind:

• Some seemingly private modules might be re-exported through public modules.
• If the branch is behind main you might see odd diffs, rebase main into this branch.

New type declarations

We found no new type declarations in this PR

Existing type declarations

packages/cli-kit/dist/public/node/ui.d.ts

@@ -1,5 +1,4 @@
 import { FatalError as Fatal } from './error.js';
-import { TokenizedString } from './output.js';
 import { ConcurrentOutputProps } from '../../private/node/ui/components/ConcurrentOutput.js';
 import { handleCtrlC, render } from '../../private/node/ui.js';
 import { AlertOptions } from '../../private/node/ui/alert.js';
@@ -332,23 +331,21 @@ interface RenderTasksOptions {
  * Installing dependencies ...
  */
 export declare function renderTasks<TContext>(tasks: Task<TContext>[], { renderOptions, noProgressBar }?: RenderTasksOptions): Promise<TContext>;
-export interface RenderSingleTaskOptions<T> {
-    title: TokenizedString;
-    task: (updateStatus: (status: TokenizedString) => void) => Promise<T>;
-    renderOptions?: RenderOptions;
-}
 /**
- * Awaits a single task and displays a loading bar while it's in progress. The task's result is returned.
+ * Awaits a single promise and displays a loading bar while it's in progress. The promise's result is returned.
  * @param options - Configuration object
- * @param options.title - The initial title to display with the loading bar
- * @param options.task - The async task to execute. Receives an updateStatus callback to change the displayed title.
- * @param options.renderOptions - Optional render configuration
- * @returns The result of the task
+ * @param options.title - The title to display with the loading bar
+ * @param options.taskPromise - The promise to track
+ * @param renderOptions - Optional render configuration
+ * @returns The result of the promise
  * @example
  * ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  * Loading app ...
  */
-export declare function renderSingleTask<T>({ title, task, renderOptions }: RenderSingleTaskOptions<T>): Promise<T>;
+export declare function renderSingleTask<T>({ title, taskPromise }: {
+    title: string;
+    taskPromise: Promise<T> | (() => Promise<T>);
+}, { renderOptions }?: RenderTasksOptions): Promise<T>;
 export interface RenderTextPromptOptions extends Omit<TextPromptProps, 'onSubmit'> {
     renderOptions?: RenderOptions;
 }

packages/cli-kit/dist/private/node/ui/components/SingleTask.d.ts

@@ -1,9 +1,8 @@
-import { TokenizedString } from '../../../../public/node/output.js';
-interface SingleTaskProps<T> {
-    title: TokenizedString;
-    task: (updateStatus: (status: TokenizedString) => void) => Promise<T>;
-    onComplete?: (result: T) => void;
+import React from 'react';
+interface SingleTaskProps {
+    title: string;
+    taskPromise: Promise<unknown>;
     noColor?: boolean;
 }
-declare const SingleTask: <T>({ task, title, onComplete, noColor }: SingleTaskProps<T>) => JSX.Element | null;
+declare const SingleTask: ({ taskPromise, title, noColor }: React.PropsWithChildren<SingleTaskProps>) => JSX.Element | null;
 export { SingleTask };
\ No newline at end of file

[isaacroldan]

I find it weird that validateGraphQLDocument returns a boolean that doesn't represent if the graphql is valid or not, but if its a mutation. Someone reading just the signature of this function wouldn't understand that.

I see two options here:

• Split in two: validateGraphQLDocument that returns nothing, just throws if invalid, and isMutation returns a boolean. Is ok to parse the document twice, is not a heavy operation afaik.
• Type the return of validateGraphQLDocument to be something like:

type ValidationResult =
  | {
      result: 'ok'
      type: 'mutation' | 'query'
    }
  | {
      result: 'error'
      message: TokenItem | OutputMessage
    }

I'm ok with both, I think the first option would be cleaner.

[ericlee878]

Good point. Refactored to the first option!