Add typed JSON output to theme profile

Author: gonzaloriestra

.changeset/theme-profile-json-schema.md

@@ -0,0 +1,4 @@
+---
+'@shopify/cli': minor
+---
+Expose a discoverable Speedscope result schema for theme profile --json.

packages/cli/README.md

@@ -5709,6 +5709,207 @@ DESCRIPTION
 
   This command will open a web page with the Speedscope profiler detailing the time spent executing Liquid on the given
   page.
+
+  Output from `--json` conforms to the `ThemeProfileResult` schema.
+
+  Use `--json-schema` to print the result, error, and event schemas.
+
+  ```json
+  {
+    "type": "object",
+    "properties": {
+      "$schema": {
+        "type": "string",
+        "const": "https://www.speedscope.app/file-format-schema.json"
+      },
+      "shared": {
+        "$ref": "#/definitions/ProfileShared"
+      },
+      "profiles": {
+        "type": "array",
+        "items": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/EventedProfile"
+            },
+            {
+              "$ref": "#/definitions/SampledProfile"
+            }
+          ]
+        }
+      },
+      "name": {
+        "type": "string"
+      },
+      "exporter": {
+        "type": "string"
+      },
+      "activeProfileIndex": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "$schema",
+      "shared",
+      "profiles"
+    ],
+    "additionalProperties": true,
+    "title": "ThemeProfileResult",
+    "definitions": {
+      "ProfileFrame": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "file": {
+            "type": "string"
+          },
+          "line": {
+            "type": "number"
+          },
+          "col": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "name"
+        ],
+        "additionalProperties": true
+      },
+      "ProfileEvent": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "O",
+              "C"
+            ]
+          },
+          "at": {
+            "type": "number"
+          },
+          "frame": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "type",
+          "at",
+          "frame"
+        ],
+        "additionalProperties": true
+      },
+      "ProfileShared": {
+        "type": "object",
+        "properties": {
+          "frames": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/ProfileFrame"
+            }
+          }
+        },
+        "required": [
+          "frames"
+        ],
+        "additionalProperties": true
+      },
+      "EventedProfile": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "unit": {
+            "type": "string",
+            "enum": [
+              "bytes",
+              "microseconds",
+              "milliseconds",
+              "nanoseconds",
+              "none",
+              "seconds"
+            ]
+          },
+          "startValue": {
+            "type": "number"
+          },
+          "endValue": {
+            "type": "number"
+          },
+          "type": {
+            "type": "string",
+            "const": "evented"
+          },
+          "events": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/ProfileEvent"
+            }
+          }
+        },
+        "required": [
+          "name",
+          "unit",
+          "startValue",
+          "endValue",
+          "type",
+          "events"
+        ],
+        "additionalProperties": true
+      },
+      "SampledProfile": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "$ref": "#/definitions/EventedProfile/properties/name"
+          },
+          "unit": {
+            "$ref": "#/definitions/EventedProfile/properties/unit"
+          },
+          "startValue": {
+            "$ref": "#/definitions/EventedProfile/properties/startValue"
+          },
+          "endValue": {
+            "$ref": "#/definitions/EventedProfile/properties/endValue"
+          },
+          "type": {
+            "type": "string",
+            "const": "sampled"
+          },
+          "samples": {
+            "type": "array",
+            "items": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              }
+            }
+          },
+          "weights": {
+            "type": "array",
+            "items": {
+              "type": "number"
+            }
+          }
+        },
+        "required": [
+          "name",
+          "unit",
+          "startValue",
+          "endValue",
+          "type",
+          "samples",
+          "weights"
+        ],
+        "additionalProperties": true
+      }
+    },
+    "$schema": "http://json-schema.org/draft-07/schema#"
+  }
+  ```
 ```
 
 ## `shopify theme publish`

packages/cli/oclif.manifest.json

@@ -10625,7 +10625,7 @@
       "args": {
       },
       "customPluginName": "@shopify/theme",
-      "description": "Profile the Shopify Liquid on a given page.\n\n  This command will open a web page with the Speedscope profiler detailing the time spent executing Liquid on the given page.",
+      "description": "Profile the Shopify Liquid on a given page.\n\n  This command will open a web page with the Speedscope profiler detailing the time spent executing Liquid on the given page.\n\nOutput from `--json` conforms to the `ThemeProfileResult` schema.\n\nUse `--json-schema` to print the result, error, and event schemas.\n\n```json\n{\n  \"type\": \"object\",\n  \"properties\": {\n    \"$schema\": {\n      \"type\": \"string\",\n      \"const\": \"https://www.speedscope.app/file-format-schema.json\"\n    },\n    \"shared\": {\n      \"$ref\": \"#/definitions/ProfileShared\"\n    },\n    \"profiles\": {\n      \"type\": \"array\",\n      \"items\": {\n        \"anyOf\": [\n          {\n            \"$ref\": \"#/definitions/EventedProfile\"\n          },\n          {\n            \"$ref\": \"#/definitions/SampledProfile\"\n          }\n        ]\n      }\n    },\n    \"name\": {\n      \"type\": \"string\"\n    },\n    \"exporter\": {\n      \"type\": \"string\"\n    },\n    \"activeProfileIndex\": {\n      \"type\": \"number\"\n    }\n  },\n  \"required\": [\n    \"$schema\",\n    \"shared\",\n    \"profiles\"\n  ],\n  \"additionalProperties\": true,\n  \"title\": \"ThemeProfileResult\",\n  \"definitions\": {\n    \"ProfileFrame\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"name\": {\n          \"type\": \"string\"\n        },\n        \"file\": {\n          \"type\": \"string\"\n        },\n        \"line\": {\n          \"type\": \"number\"\n        },\n        \"col\": {\n          \"type\": \"number\"\n        }\n      },\n      \"required\": [\n        \"name\"\n      ],\n      \"additionalProperties\": true\n    },\n    \"ProfileEvent\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"type\": {\n          \"type\": \"string\",\n          \"enum\": [\n            \"O\",\n            \"C\"\n          ]\n        },\n        \"at\": {\n          \"type\": \"number\"\n        },\n        \"frame\": {\n          \"type\": \"number\"\n        }\n      },\n      \"required\": [\n        \"type\",\n        \"at\",\n        \"frame\"\n      ],\n      \"additionalProperties\": true\n    },\n    \"ProfileShared\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"frames\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"$ref\": \"#/definitions/ProfileFrame\"\n          }\n        }\n      },\n      \"required\": [\n        \"frames\"\n      ],\n      \"additionalProperties\": true\n    },\n    \"EventedProfile\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"name\": {\n          \"type\": \"string\"\n        },\n        \"unit\": {\n          \"type\": \"string\",\n          \"enum\": [\n            \"bytes\",\n            \"microseconds\",\n            \"milliseconds\",\n            \"nanoseconds\",\n            \"none\",\n            \"seconds\"\n          ]\n        },\n        \"startValue\": {\n          \"type\": \"number\"\n        },\n        \"endValue\": {\n          \"type\": \"number\"\n        },\n        \"type\": {\n          \"type\": \"string\",\n          \"const\": \"evented\"\n        },\n        \"events\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"$ref\": \"#/definitions/ProfileEvent\"\n          }\n        }\n      },\n      \"required\": [\n        \"name\",\n        \"unit\",\n        \"startValue\",\n        \"endValue\",\n        \"type\",\n        \"events\"\n      ],\n      \"additionalProperties\": true\n    },\n    \"SampledProfile\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"name\": {\n          \"$ref\": \"#/definitions/EventedProfile/properties/name\"\n        },\n        \"unit\": {\n          \"$ref\": \"#/definitions/EventedProfile/properties/unit\"\n        },\n        \"startValue\": {\n          \"$ref\": \"#/definitions/EventedProfile/properties/startValue\"\n        },\n        \"endValue\": {\n          \"$ref\": \"#/definitions/EventedProfile/properties/endValue\"\n        },\n        \"type\": {\n          \"type\": \"string\",\n          \"const\": \"sampled\"\n        },\n        \"samples\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"type\": \"array\",\n            \"items\": {\n              \"type\": \"number\"\n            }\n          }\n        },\n        \"weights\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"type\": \"number\"\n          }\n        }\n      },\n      \"required\": [\n        \"name\",\n        \"unit\",\n        \"startValue\",\n        \"endValue\",\n        \"type\",\n        \"samples\",\n        \"weights\"\n      ],\n      \"additionalProperties\": true\n    }\n  },\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```",
       "descriptionWithMarkdown": "Profile the Shopify Liquid on a given page.\n\n  This command will open a web page with the Speedscope profiler detailing the time spent executing Liquid on the given page.",
       "enableJsonFlag": false,
       "flags": {

packages/eslint-plugin-cli/rules/json-output-command-exceptions.js

@@ -85,7 +85,6 @@ const commandExceptions = [
   'packages/theme/src/cli/commands/theme/open.ts',
   'packages/theme/src/cli/commands/theme/package.ts',
   'packages/theme/src/cli/commands/theme/preview.ts',
-  'packages/theme/src/cli/commands/theme/profile.ts',
   'packages/theme/src/cli/commands/theme/publish.ts',
   'packages/theme/src/cli/commands/theme/pull.ts',
   'packages/theme/src/cli/commands/theme/push.ts',

packages/theme/src/cli/commands/theme/profile.test.ts

@@ -0,0 +1,101 @@
+import Profile from './profile.js'
+import {themeProfileJsonOutputSchema, type ThemeProfileResult} from '../../services/profile/types.js'
+import {captureStandardStreams} from '../../utilities/testing/streams.js'
+import {afterEach, expect, test, vi} from 'vitest'
+
+vi.mock('../../utilities/theme-selector.js')
+vi.mock('../../utilities/theme-environment/storefront-renderer.js')
+vi.mock('../../utilities/theme-environment/dev-server-session.js')
+vi.mock('../../utilities/theme-environment/storefront-session.js')
+vi.mock('@shopify/cli-kit/node/session')
+vi.mock('@shopify/cli-kit/node/system')
+
+const profile: ThemeProfileResult = {
+  $schema: 'https://www.speedscope.app/file-format-schema.json',
+  shared: {frames: [{name: 'layout', file: 'layout/theme.liquid', line: 1, col: 0, extension: false}]},
+  profiles: [
+    {
+      type: 'evented',
+      name: 'Liquid',
+      unit: 'microseconds',
+      startValue: 0,
+      endValue: 10,
+      events: [
+        {type: 'O', at: 0, frame: 0},
+        {type: 'C', at: 10, frame: 0},
+      ],
+    },
+  ],
+  extension: {value: null},
+}
+
+afterEach(() => vi.unstubAllEnvs())
+
+test('exposes Speedscope evented and sampled profiles while retaining extension fields', () => {
+  expect(Profile.jsonOutputSchema).toBe(themeProfileJsonOutputSchema)
+  expect(Profile.flags.json).toBeDefined()
+  expect(JSON.parse(themeProfileJsonOutputSchema.encode(profile))).toEqual(profile)
+  const sampled: ThemeProfileResult = {
+    ...profile,
+    profiles: [
+      {type: 'sampled', name: 'Liquid', unit: 'none', startValue: 0, endValue: 10, samples: [[0]], weights: [10]},
+    ],
+  }
+  expect(JSON.parse(themeProfileJsonOutputSchema.encode(sampled))).toEqual(sampled)
+  expect(() => themeProfileJsonOutputSchema.validate({...profile, shared: {frames: [{name: 123}]}})).toThrow()
+  expect(() =>
+    themeProfileJsonOutputSchema.validate({...profile, profiles: [{...profile.profiles[0], unit: 'invalid'}]}),
+  ).toThrow()
+})
+
+test.each(['profile', 'empty', 'failure', 'invalid result'])(
+  'keeps %s JSON on stdout and progress events on stderr',
+  async (mode) => {
+    vi.stubEnv('SHOPIFY_UNIT_TEST', 'false')
+    vi.resetModules()
+    const {default: StreamProfile} = await import('./profile.js')
+    const {findOrSelectTheme} = await import('../../utilities/theme-selector.js')
+    const {render} = await import('../../utilities/theme-environment/storefront-renderer.js')
+    const {ensureAuthenticatedThemes} = await import('@shopify/cli-kit/node/session')
+    const {openURL} = await import('@shopify/cli-kit/node/system')
+    const {runWithCommandEventsForCommand} = await import('@shopify/cli-kit/node/command-events')
+    const {Config} = await import('@oclif/core')
+    const config = new Config({root: __dirname})
+    await config.load()
+    vi.mocked(ensureAuthenticatedThemes).mockResolvedValue({storeFqdn: 'shop.myshopify.com', token: 'token'})
+    vi.mocked(findOrSelectTheme).mockResolvedValue({
+      id: 1,
+      name: 'Dawn',
+      role: 'live',
+      processing: false,
+      createdAtRuntime: false,
+    })
+    const result = mode === 'empty' ? {...profile, profiles: [], shared: {frames: []}} : profile
+    // Keep unusual whitespace and upstream field order to catch accidental reserialization.
+    const source = mode === 'invalid result' ? '{"profiles":false}' : ` ${JSON.stringify(result, null, 4)}\n`
+    vi.mocked(render).mockResolvedValue(new Response(source, {status: 200}))
+    if (mode === 'failure') vi.mocked(render).mockRejectedValue(new Error('Network error'))
+    const streams = captureStandardStreams()
+    try {
+      const operation = runWithCommandEventsForCommand(['--json'], () =>
+        new StreamProfile(['--store=shop.myshopify.com', '--json'], config).run(),
+      )
+      if (mode === 'failure') await expect(operation).rejects.toThrow('Network error')
+      else if (mode === 'invalid result') await expect(operation).rejects.toThrow()
+      else await operation
+    } finally {
+      streams.restore()
+    }
+    expect(openURL).not.toHaveBeenCalled()
+    const failed = mode === 'failure' || mode === 'invalid result'
+    expect(streams.stdout()).toBe(failed ? '' : `${source}\n`)
+    if (!failed) expect(JSON.parse(streams.stdout())).toEqual(result)
+    const events = streams
+      .stderr()
+      .trim()
+      .split('\n')
+      .map((line) => JSON.parse(line))
+    expect(events.map((event) => event.status)).toEqual(failed ? ['started'] : ['started', 'completed'])
+    expect(events.every((event) => event.type === 'progress')).toBe(true)
+  },
+)

packages/theme/src/cli/commands/theme/profile.ts

@@ -1,16 +1,23 @@
 import {themeFlags} from '../../flags.js'
 import ThemeCommand, {RequiredFlags} from '../../utilities/theme-command.js'
 import {profile} from '../../services/profile.js'
+import {renderThemeProfileResult} from '../../services/profile/result.js'
+import {themeProfileJsonOutputSchema} from '../../services/profile/types.js'
 import {findOrSelectTheme} from '../../utilities/theme-selector.js'
 import {renderTasksToStdErr} from '../../utilities/theme-ui.js'
 import {Flags} from '@oclif/core'
 import {globalFlags, jsonFlag} from '@shopify/cli-kit/node/cli'
-import {Task} from '@shopify/cli-kit/node/ui'
+import {renderSingleTask} from '@shopify/cli-kit/node/ui'
+import {outputContent} from '@shopify/cli-kit/node/output'
 import {InferredFlags} from '@oclif/core/interfaces'
 import {AdminSession} from '@shopify/cli-kit/node/session'
 
 type ProfileFlags = InferredFlags<typeof Profile.flags>
 export default class Profile extends ThemeCommand {
+  static get jsonOutputSchema() {
+    return themeProfileJsonOutputSchema
+  }
+
   static summary = 'Profile the Liquid rendering of a theme page.'
 
   static usage = ['theme profile', 'theme profile --url /products/classic-leather-jacket']
@@ -54,21 +61,21 @@ export default class Profile extends ThemeCommand {
     }
     const theme = await findOrSelectTheme(adminSession, filter)
 
-    const tasks: Task[] = [
-      {
-        title: `Generating Liquid profile for ${adminSession.storeFqdn} ${flags.url}`,
-        task: async () => {
-          await profile(
-            adminSession,
-            theme.id.toString(),
-            flags.url,
-            flags.json,
-            themeAccessPassword,
-            flags['store-password'],
-          )
-        },
-      },
-    ]
-    await renderTasksToStdErr(tasks)
+    const title = `Generating Liquid profile for ${adminSession.storeFqdn} ${flags.url}`
+    const task = async () => {
+      const result = await profile(
+        adminSession,
+        theme.id.toString(),
+        flags.url,
+        themeAccessPassword,
+        flags['store-password'],
+      )
+      await renderThemeProfileResult(result, flags.json ? 'json' : 'text')
+    }
+    if (flags.json) {
+      await renderSingleTask({title: outputContent`${title}`, task})
+    } else {
+      await renderTasksToStdErr([{title, task}])
+    }
   }
 }