From 9393b3724aeb797657c8c958bc2c5ab98cb8e627 Mon Sep 17 00:00:00 2001
From: Gonzalo Riestra <gonzalo.riestra@shopify.com>
Date: Thu, 24 Sep 2026 11:15:11 +0200
Subject: [PATCH] Add typed JSON output to theme check

---
 .../generated/generated_docs_data_v2.json     |  11 +-
 packages/cli/README.md                        | 135 +++++++++++++++++-
 packages/cli/oclif.manifest.json              |  17 ++-
 .../rules/json-output-command-exceptions.js   |   1 -
 .../src/cli/commands/theme/check-json.test.ts | 116 +++++++++++++++
 .../theme/src/cli/commands/theme/check.ts     |  84 +++++------
 packages/theme/src/cli/services/check.ts      |  38 +++--
 .../theme/src/cli/services/check/result.ts    |  51 +++++++
 .../theme/src/cli/services/check/types.ts     |  34 +++++
 9 files changed, 408 insertions(+), 79 deletions(-)
 create mode 100644 packages/theme/src/cli/commands/theme/check-json.test.ts
 create mode 100644 packages/theme/src/cli/services/check/result.ts
 create mode 100644 packages/theme/src/cli/services/check/types.ts

diff --git a/docs-shopify.dev/generated/generated_docs_data_v2.json b/docs-shopify.dev/generated/generated_docs_data_v2.json
index b1fcb9fd440..f8403b2a3b0 100644
--- a/docs-shopify.dev/generated/generated_docs_data_v2.json
+++ b/docs-shopify.dev/generated/generated_docs_data_v2.json
@@ -7070,6 +7070,15 @@
           "isOptional": true,
           "environmentValue": "SHOPIFY_FLAG_ENVIRONMENT"
         },
+        {
+          "filePath": "docs-shopify.dev/commands/interfaces/theme-check.interface.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "-j, --json",
+          "value": "''",
+          "description": "Output the result as JSON. Automatically disables color output.",
+          "isOptional": true,
+          "environmentValue": "SHOPIFY_FLAG_JSON"
+        },
         {
           "filePath": "docs-shopify.dev/commands/interfaces/theme-check.interface.ts",
           "syntaxKind": "PropertySignature",
@@ -7089,7 +7098,7 @@
           "environmentValue": "SHOPIFY_FLAG_VERSION"
         }
       ],
-      "value": "export interface themecheck {\n  /**\n   * Alias of the Shopify account to use for authentication.\n   * @environment SHOPIFY_FLAG_AUTH_ALIAS\n   */\n  '--auth-alias <value>'?: string\n\n  /**\n   * Automatically fix offenses\n   * @environment SHOPIFY_FLAG_AUTO_CORRECT\n   */\n  '-a, --auto-correct'?: ''\n\n  /**\n   * Use the config provided, overriding .theme-check.yml if present\n      Supports all theme-check: config values, e.g., theme-check:theme-app-extension,\n      theme-check:recommended, theme-check:all\n      For backwards compatibility, :theme_app_extension is also supported \n   * @environment SHOPIFY_FLAG_CONFIG\n   */\n  '-C, --config <value>'?: string\n\n  /**\n   * The environment to apply to the current command.\n   * @environment SHOPIFY_FLAG_ENVIRONMENT\n   */\n  '-e, --environment <value>'?: string\n\n  /**\n   * Minimum severity for exit with error code\n   * @environment SHOPIFY_FLAG_FAIL_LEVEL\n   */\n  '--fail-level <value>'?: string\n\n  /**\n   * Generate a .theme-check.yml file\n   * @environment SHOPIFY_FLAG_INIT\n   */\n  '--init'?: ''\n\n  /**\n   * Print the command's JSON schemas.\n   * @environment SHOPIFY_FLAG_JSON_SCHEMA\n   */\n  '--json-schema'?: ''\n\n  /**\n   * List enabled checks\n   * @environment SHOPIFY_FLAG_LIST\n   */\n  '--list'?: ''\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * The output format to use\n   * @environment SHOPIFY_FLAG_OUTPUT\n   */\n  '-o, --output <value>'?: string\n\n  /**\n   * The path where you want to run the command. Defaults to the current working directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Output active config to STDOUT\n   * @environment SHOPIFY_FLAG_PRINT\n   */\n  '--print'?: ''\n\n  /**\n   * Increase the verbosity of the output. May include sensitive data.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n\n  /**\n   * Print Theme Check version\n   * @environment SHOPIFY_FLAG_VERSION\n   */\n  '-v, --version'?: ''\n}"
+      "value": "export interface themecheck {\n  /**\n   * Alias of the Shopify account to use for authentication.\n   * @environment SHOPIFY_FLAG_AUTH_ALIAS\n   */\n  '--auth-alias <value>'?: string\n\n  /**\n   * Automatically fix offenses\n   * @environment SHOPIFY_FLAG_AUTO_CORRECT\n   */\n  '-a, --auto-correct'?: ''\n\n  /**\n   * Use the config provided, overriding .theme-check.yml if present\n      Supports all theme-check: config values, e.g., theme-check:theme-app-extension,\n      theme-check:recommended, theme-check:all\n      For backwards compatibility, :theme_app_extension is also supported \n   * @environment SHOPIFY_FLAG_CONFIG\n   */\n  '-C, --config <value>'?: string\n\n  /**\n   * The environment to apply to the current command.\n   * @environment SHOPIFY_FLAG_ENVIRONMENT\n   */\n  '-e, --environment <value>'?: string\n\n  /**\n   * Minimum severity for exit with error code\n   * @environment SHOPIFY_FLAG_FAIL_LEVEL\n   */\n  '--fail-level <value>'?: string\n\n  /**\n   * Generate a .theme-check.yml file\n   * @environment SHOPIFY_FLAG_INIT\n   */\n  '--init'?: ''\n\n  /**\n   * Output the result as JSON. Automatically disables color output.\n   * @environment SHOPIFY_FLAG_JSON\n   */\n  '-j, --json'?: ''\n\n  /**\n   * Print the command's JSON schemas.\n   * @environment SHOPIFY_FLAG_JSON_SCHEMA\n   */\n  '--json-schema'?: ''\n\n  /**\n   * List enabled checks\n   * @environment SHOPIFY_FLAG_LIST\n   */\n  '--list'?: ''\n\n  /**\n   * Disable color output.\n   * @environment SHOPIFY_FLAG_NO_COLOR\n   */\n  '--no-color'?: ''\n\n  /**\n   * The output format to use\n   * @environment SHOPIFY_FLAG_OUTPUT\n   */\n  '-o, --output <value>'?: string\n\n  /**\n   * The path where you want to run the command. Defaults to the current working directory.\n   * @environment SHOPIFY_FLAG_PATH\n   */\n  '--path <value>'?: string\n\n  /**\n   * Output active config to STDOUT\n   * @environment SHOPIFY_FLAG_PRINT\n   */\n  '--print'?: ''\n\n  /**\n   * Increase the verbosity of the output. May include sensitive data.\n   * @environment SHOPIFY_FLAG_VERBOSE\n   */\n  '--verbose'?: ''\n\n  /**\n   * Print Theme Check version\n   * @environment SHOPIFY_FLAG_VERSION\n   */\n  '-v, --version'?: ''\n}"
     }
   },
   "themeconsole": {
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 80748ac75ce..3e4f7b11695 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -7509,8 +7509,8 @@ Validate the theme.
 ```
 USAGE
   $ shopify theme check [--auth-alias <value>] [-a] [-C <value>] [-e <value>...] [--fail-level
-    crash|error|suggestion|style|warning|info] [--init] [--json-schema] [--list] [--no-color] [-o text|json] [--path
-    <value>] [--print] [--verbose] [-v]
+    crash|error|suggestion|style|warning|info] [-j | --init | -v | --print | --list] [--json-schema] [--no-color] [-o
+    text|json] [--path <value>] [--verbose]
 
 FLAGS
   -C, --config=<value>
@@ -7528,6 +7528,10 @@ FLAGS
       The environment to apply to the current command.
       [env: SHOPIFY_FLAG_ENVIRONMENT]
 
+  -j, --json
+      Output the result as JSON. Automatically disables color output.
+      [env: SHOPIFY_FLAG_JSON]
+
   -o, --output=<option>
       [default: text] The output format to use
       [env: SHOPIFY_FLAG_OUTPUT]
@@ -7580,6 +7584,133 @@ DESCRIPTION
   Calls and runs "Theme Check" (https://shopify.dev/docs/themes/tools/theme-check) to analyze your theme code for errors
   and to ensure that it follows theme and Liquid best practices. "Learn more about the checks that Theme Check runs."
   (https://shopify.dev/docs/themes/tools/theme-check/checks)
+
+  Use `--json-schema` to print the result, error, and event schemas.
+
+  Output from `--json` conforms to the `ThemeCheckResult` schema.
+
+  ```json
+  {
+    "anyOf": [
+      {
+        "$ref": "#/definitions/ThemeCheckEnvironment/properties/result"
+      },
+      {
+        "type": "object",
+        "properties": {
+          "environments": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/ThemeCheckEnvironment"
+            }
+          }
+        },
+        "required": [
+          "environments"
+        ],
+        "additionalProperties": false
+      }
+    ],
+    "title": "ThemeCheckResult",
+    "definitions": {
+      "ThemeCheckOffense": {
+        "type": "object",
+        "properties": {
+          "check": {
+            "type": "string"
+          },
+          "severity": {
+            "type": "string",
+            "enum": [
+              "error",
+              "warning",
+              "info"
+            ]
+          },
+          "start_row": {
+            "type": "number"
+          },
+          "start_column": {
+            "type": "number"
+          },
+          "end_row": {
+            "type": "number"
+          },
+          "end_column": {
+            "type": "number"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "check",
+          "severity",
+          "start_row",
+          "start_column",
+          "end_row",
+          "end_column",
+          "message"
+        ],
+        "additionalProperties": false
+      },
+      "ThemeCheckFile": {
+        "type": "object",
+        "properties": {
+          "environment": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          },
+          "offenses": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/ThemeCheckOffense"
+            }
+          },
+          "errorCount": {
+            "type": "number"
+          },
+          "warningCount": {
+            "type": "number"
+          },
+          "infoCount": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "path",
+          "offenses",
+          "errorCount",
+          "warningCount",
+          "infoCount"
+        ],
+        "additionalProperties": false
+      },
+      "ThemeCheckEnvironment": {
+        "type": "object",
+        "properties": {
+          "environment": {
+            "type": "string"
+          },
+          "result": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/ThemeCheckFile"
+            }
+          }
+        },
+        "required": [
+          "environment",
+          "result"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "$schema": "http://json-schema.org/draft-07/schema#"
+  }
+  ```
 ```
 
 ## `shopify theme console`
diff --git a/packages/cli/oclif.manifest.json b/packages/cli/oclif.manifest.json
index 743dc1502ac..54047683870 100644
--- a/packages/cli/oclif.manifest.json
+++ b/packages/cli/oclif.manifest.json
@@ -9359,7 +9359,7 @@
       "args": {
       },
       "customPluginName": "@shopify/theme",
-      "description": "Calls and runs \"Theme Check\" (https://shopify.dev/docs/themes/tools/theme-check) to analyze your theme code for errors and to ensure that it follows theme and Liquid best practices. \"Learn more about the checks that Theme Check runs.\" (https://shopify.dev/docs/themes/tools/theme-check/checks)",
+      "description": "Calls and runs \"Theme Check\" (https://shopify.dev/docs/themes/tools/theme-check) to analyze your theme code for errors and to ensure that it follows theme and Liquid best practices. \"Learn more about the checks that Theme Check runs.\" (https://shopify.dev/docs/themes/tools/theme-check/checks)\n\nUse `--json-schema` to print the result, error, and event schemas.\n\nOutput from `--json` conforms to the `ThemeCheckResult` schema.\n\n```json\n{\n  \"anyOf\": [\n    {\n      \"$ref\": \"#/definitions/ThemeCheckEnvironment/properties/result\"\n    },\n    {\n      \"type\": \"object\",\n      \"properties\": {\n        \"environments\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"$ref\": \"#/definitions/ThemeCheckEnvironment\"\n          }\n        }\n      },\n      \"required\": [\n        \"environments\"\n      ],\n      \"additionalProperties\": false\n    }\n  ],\n  \"title\": \"ThemeCheckResult\",\n  \"definitions\": {\n    \"ThemeCheckOffense\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"check\": {\n          \"type\": \"string\"\n        },\n        \"severity\": {\n          \"type\": \"string\",\n          \"enum\": [\n            \"error\",\n            \"warning\",\n            \"info\"\n          ]\n        },\n        \"start_row\": {\n          \"type\": \"number\"\n        },\n        \"start_column\": {\n          \"type\": \"number\"\n        },\n        \"end_row\": {\n          \"type\": \"number\"\n        },\n        \"end_column\": {\n          \"type\": \"number\"\n        },\n        \"message\": {\n          \"type\": \"string\"\n        }\n      },\n      \"required\": [\n        \"check\",\n        \"severity\",\n        \"start_row\",\n        \"start_column\",\n        \"end_row\",\n        \"end_column\",\n        \"message\"\n      ],\n      \"additionalProperties\": false\n    },\n    \"ThemeCheckFile\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"environment\": {\n          \"type\": \"string\"\n        },\n        \"path\": {\n          \"type\": \"string\"\n        },\n        \"offenses\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"$ref\": \"#/definitions/ThemeCheckOffense\"\n          }\n        },\n        \"errorCount\": {\n          \"type\": \"number\"\n        },\n        \"warningCount\": {\n          \"type\": \"number\"\n        },\n        \"infoCount\": {\n          \"type\": \"number\"\n        }\n      },\n      \"required\": [\n        \"path\",\n        \"offenses\",\n        \"errorCount\",\n        \"warningCount\",\n        \"infoCount\"\n      ],\n      \"additionalProperties\": false\n    },\n    \"ThemeCheckEnvironment\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"environment\": {\n          \"type\": \"string\"\n        },\n        \"result\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"$ref\": \"#/definitions/ThemeCheckFile\"\n          }\n        }\n      },\n      \"required\": [\n        \"environment\",\n        \"result\"\n      ],\n      \"additionalProperties\": false\n    }\n  },\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```",
       "descriptionWithMarkdown": "Calls and runs [Theme Check](https://shopify.dev/docs/themes/tools/theme-check) to analyze your theme code for errors and to ensure that it follows theme and Liquid best practices. [Learn more about the checks that Theme Check runs.](https://shopify.dev/docs/themes/tools/theme-check/checks)",
       "enableJsonFlag": false,
       "flags": {
@@ -9425,6 +9425,21 @@
           "required": false,
           "type": "boolean"
         },
+        "json": {
+          "allowNo": false,
+          "char": "j",
+          "description": "Output the result as JSON. Automatically disables color output.",
+          "env": "SHOPIFY_FLAG_JSON",
+          "exclusive": [
+            "init",
+            "version",
+            "print",
+            "list"
+          ],
+          "hidden": false,
+          "name": "json",
+          "type": "boolean"
+        },
         "json-schema": {
           "allowNo": false,
           "description": "Print the command's JSON schemas.",
diff --git a/packages/eslint-plugin-cli/rules/json-output-command-exceptions.js b/packages/eslint-plugin-cli/rules/json-output-command-exceptions.js
index 7c092b1483d..63be3b4b0c2 100644
--- a/packages/eslint-plugin-cli/rules/json-output-command-exceptions.js
+++ b/packages/eslint-plugin-cli/rules/json-output-command-exceptions.js
@@ -43,7 +43,6 @@ const commandExceptions = [
   'packages/plugin-did-you-mean/src/commands/config/autocorrect/off.ts',
   'packages/plugin-did-you-mean/src/commands/config/autocorrect/on.ts',
   'packages/plugin-did-you-mean/src/commands/config/autocorrect/status.ts',
-  'packages/theme/src/cli/commands/theme/check.ts',
   'packages/theme/src/cli/commands/theme/init.ts',
   'packages/theme/src/cli/commands/theme/metafields/pull.ts',
   'packages/theme/src/cli/commands/theme/package.ts',
diff --git a/packages/theme/src/cli/commands/theme/check-json.test.ts b/packages/theme/src/cli/commands/theme/check-json.test.ts
new file mode 100644
index 00000000000..135a20643f7
--- /dev/null
+++ b/packages/theme/src/cli/commands/theme/check-json.test.ts
@@ -0,0 +1,116 @@
+import Check from './check.js'
+import {checkTheme, formatOffensesJson, sortOffenses} from '../../services/check.js'
+import {themeCheckJsonOutputSchema} from '../../services/check/types.js'
+import {encodeThemeCheckResult} from '../../services/check/result.js'
+import {expect, test, vi} from 'vitest'
+import {withCapturedStandardStreams} from '@shopify/cli-kit/node/testing/output'
+import {themeCheckRun, Severity, SourceCodeType, path as pathUtils} from '@shopify/theme-check-node'
+import {inTemporaryDirectory} from '@shopify/cli-kit/node/fs'
+
+vi.mock('@shopify/theme-check-node', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@shopify/theme-check-node')>()),
+  themeCheckRun: vi.fn(),
+}))
+
+vi.mock('@shopify/cli-kit/node/environments')
+
+const offense = {
+  type: SourceCodeType.LiquidHtml,
+  check: 'ExampleCheck',
+  severity: Severity.ERROR,
+  uri: 'file:///theme/templates/index.liquid',
+  start: {index: 0, line: 0, character: 0},
+  end: {index: 1, line: 0, character: 1},
+  message: 'Example offense',
+}
+
+test('exposes the contract and preserves compact JSON, environment omission and counts', async () => {
+  expect(Check.jsonOutputSchema).toBe(themeCheckJsonOutputSchema)
+  vi.mocked(themeCheckRun).mockResolvedValue({offenses: [offense], theme: [], config: {} as never})
+  const {result} = await checkTheme('/theme')
+  expect(result).toEqual(formatOffensesJson(sortOffenses([offense])))
+  expect(encodeThemeCheckResult(result)).toBe(
+    JSON.stringify([
+      {
+        path: pathUtils.fsPath(offense.uri),
+        offenses: [
+          {
+            check: 'ExampleCheck',
+            severity: 'error',
+            start_row: 0,
+            start_column: 0,
+            end_row: 0,
+            end_column: 1,
+            message: 'Example offense',
+          },
+        ],
+        errorCount: 1,
+        warningCount: 0,
+        infoCount: 0,
+      },
+    ]),
+  )
+  expect(encodeThemeCheckResult([])).toBe('[]')
+  expect(() => themeCheckJsonOutputSchema.validate([{...result[0], errorCount: '1'}])).toThrow()
+  expect(() =>
+    themeCheckJsonOutputSchema.validate([{...result[0], offenses: [{...result[0]!.offenses[0], severity: 'fatal'}]}]),
+  ).toThrow()
+})
+
+test.each(['--json', '--output=json'])('writes compact JSON and preserves unsuccessful exit with %s', async (flag) => {
+  await inTemporaryDirectory(async (directory) => {
+    const {default: StreamCheck} = await import('./check.js')
+    const {themeCheckRun: check} = await import('@shopify/theme-check-node')
+    const {Config} = await import('@oclif/core')
+    const config = new Config({root: __dirname})
+    await config.load()
+    vi.mocked(check).mockResolvedValue({offenses: [offense], theme: [], config: {} as never})
+    const exit = vi.spyOn(process, 'exit').mockImplementation(() => undefined as never)
+    await withCapturedStandardStreams(async ({stdout, stderr}) => {
+      await new StreamCheck([`--path=${directory}`, flag], config).run()
+      expect(stdout()).toBe(`${JSON.stringify(formatOffensesJson(sortOffenses([offense])))}\n`)
+      expect(stderr()).toBe('')
+    })
+    expect(exit).toHaveBeenCalledWith(1)
+  })
+})
+
+test.each(['init', 'version', 'print', 'list'])('rejects --json with --%s before execution', async (mode) => {
+  const {Config} = await import('@oclif/core')
+  const config = new Config({root: __dirname})
+  await config.load()
+  await expect(new Check(['--json', `--${mode}`], config).run()).rejects.toThrow()
+  expect(themeCheckRun).not.toHaveBeenCalled()
+})
+
+test.each(['success', 'partial failure', 'total failure'])(
+  'collects multiple environments into one document on %s',
+  async (mode) => {
+    await inTemporaryDirectory(async (directory) => {
+      const {default: StreamCheck} = await import('./check.js')
+      const {themeCheckRun: check} = await import('@shopify/theme-check-node')
+      const {Config} = await import('@oclif/core')
+      const config = new Config({root: __dirname})
+      await config.load()
+      vi.mocked(check).mockResolvedValue({offenses: [], theme: [], config: {} as never})
+      if (mode === 'partial failure') vi.mocked(check).mockRejectedValueOnce(new Error('Check failed'))
+      if (mode === 'total failure') vi.mocked(check).mockRejectedValue(new Error('Check failed'))
+      const exit = vi.spyOn(process, 'exit').mockImplementation(() => undefined as never)
+      const {loadEnvironment} = await import('@shopify/cli-kit/node/environments')
+      vi.mocked(loadEnvironment).mockResolvedValue({path: directory})
+      const {runWithCommandEventsForCommand} = await import('@shopify/cli-kit/node/command-events')
+      await withCapturedStandardStreams(async ({stdout, stderr}) => {
+        const argv = ['--environment=first', '--environment=second', '--json']
+        await runWithCommandEventsForCommand(argv, () => new StreamCheck(argv, config).run())
+        let names = ['first', 'second']
+        if (mode === 'partial failure') names = ['second']
+        if (mode === 'total failure') names = []
+        expect(JSON.parse(stdout())).toEqual({
+          environments: names.map((environment) => ({environment, result: []})),
+        })
+        if (mode.includes('failure')) expect(stderr()).toContain('Check failed')
+      })
+      expect(exit).not.toHaveBeenCalled()
+    })
+  },
+)
diff --git a/packages/theme/src/cli/commands/theme/check.ts b/packages/theme/src/cli/commands/theme/check.ts
index 5921f6ba370..fb9a56a9bb1 100644
--- a/packages/theme/src/cli/commands/theme/check.ts
+++ b/packages/theme/src/cli/commands/theme/check.ts
@@ -1,24 +1,20 @@
 import ThemeCommand, {RequiredFlags} from '../../utilities/theme-command.js'
 import {
-  formatOffensesJson,
-  formatSummary,
+  checkTheme,
   initConfig,
   outputActiveChecks,
   outputActiveConfig,
   performAutoFixes,
-  renderOffensesText,
-  sortOffenses,
-  isExtendedWriteStream,
   handleExit,
-  withThemeCheckConfigErrorHandling,
   type FailLevel,
 } from '../../services/check.js'
+import {renderThemeCheckResult, encodeThemeCheckResult} from '../../services/check/result.js'
+import {themeCheckJsonOutputSchema} from '../../services/check/types.js'
 import {themeFlags} from '../../flags.js'
 import {Flags} from '@oclif/core'
-import {globalFlags} from '@shopify/cli-kit/node/cli'
-import {outputResult, outputDebug} from '@shopify/cli-kit/node/output'
-import {renderInfo, renderSuccess} from '@shopify/cli-kit/node/ui'
-import {themeCheckRun, LegacyIdentifiers} from '@shopify/theme-check-node'
+import {globalFlags, jsonFlag} from '@shopify/cli-kit/node/cli'
+import {outputResult} from '@shopify/cli-kit/node/output'
+import {LegacyIdentifiers} from '@shopify/theme-check-node'
 import {findPathUp} from '@shopify/cli-kit/node/fs'
 import {moduleDirectory, joinPath} from '@shopify/cli-kit/node/path'
 import {getPackageVersion} from '@shopify/cli-kit/node/node-package-manager'
@@ -27,6 +23,10 @@ import {AdminSession} from '@shopify/cli-kit/node/session'
 
 type CheckFlags = InferredFlags<typeof Check.flags>
 export default class Check extends ThemeCommand {
+  static get jsonOutputSchema() {
+    return themeCheckJsonOutputSchema
+  }
+
   static summary = 'Validate the theme.'
 
   static descriptionWithMarkdown = `Calls and runs [Theme Check](https://shopify.dev/docs/themes/tools/theme-check) to analyze your theme code for errors and to ensure that it follows theme and Liquid best practices. [Learn more about the checks that Theme Check runs.](https://shopify.dev/docs/themes/tools/theme-check/checks)`
@@ -35,6 +35,8 @@ export default class Check extends ThemeCommand {
 
   static flags = {
     ...globalFlags,
+    ...jsonFlag,
+    json: Flags.boolean({...jsonFlag.json, env: 'SHOPIFY_FLAG_JSON', exclusive: ['init', 'version', 'print', 'list']}),
     path: themeFlags.path,
     'auto-correct': Flags.boolean({
       char: 'a',
@@ -92,7 +94,7 @@ export default class Check extends ThemeCommand {
 
   static multiEnvironmentsFlags: RequiredFlags = ['path']
 
-  async command(flags: CheckFlags, _session: AdminSession, multiEnvironment: boolean): Promise<void> {
+  async command(flags: CheckFlags, _session: AdminSession, multiEnvironment: boolean) {
     // Its not clear to typescript that path will always be defined
     const path = flags.path
     const environment = flags.environment?.[0]
@@ -139,7 +141,12 @@ export default class Check extends ThemeCommand {
       return
     }
 
-    const {offenses, theme} = await runThemeCheck(path, flags.output, config, environment)
+    const output = await checkTheme(path, config, environment)
+    const {offenses, theme} = output
+    const json = flags.json || flags.output === 'json'
+    if (!multiEnvironment || !json) {
+      renderThemeCheckResult(output, json ? 'json' : flags.output, path, environment)
+    }
 
     if (flags['auto-correct']) {
       await performAutoFixes(theme, offenses)
@@ -148,50 +155,23 @@ export default class Check extends ThemeCommand {
     if (!multiEnvironment) {
       return handleExit(offenses, flags['fail-level'] as FailLevel)
     }
+    if (json) return output.result
   }
-}
-
-export async function runThemeCheck(path: string, outputFormat: string, config?: string, environment?: string) {
-  const {offenses, theme} = await withThemeCheckConfigErrorHandling(config, () =>
-    themeCheckRun(path, config, (message) => {
-      if (process.env.SHOPIFY_TMP_FLAG_DEBUG) {
-        outputDebug(message)
-      }
-    }),
-  )
 
-  const offensesByFile = sortOffenses(offenses)
-
-  if (outputFormat === 'text') {
-    renderOffensesText(offensesByFile, path, theme, environment)
-
-    // Use renderSuccess when theres no offenses
-    const render = offenses.length ? renderInfo : renderSuccess
-
-    render({
-      headline: environment ? `[${environment}] Theme Check Summary.` : 'Theme Check Summary.',
-      body: formatSummary(offenses, offensesByFile, theme),
-    })
+  protected collectsEnvironmentResults(flags: Partial<CheckFlags>): boolean {
+    return (
+      !flags.init && !flags.version && !flags.print && !flags.list && (Boolean(flags.json) || flags.output === 'json')
+    )
   }
 
-  if (outputFormat === 'json') {
-    /**
-     * Workaround:
-     * Force stdout to be blocking so that the JSON output is not broken when piped to another process.
-     * ie: ` | jq .`
-     * It turns out that console.log is technically asynchronous, and when we call process.exit(),
-     * node doesn't wait on all the output being sent to stdout and instead closes the process immediately
-     *
-     * https://github.com/pnp/cli-microsoft365/issues/1266#issuecomment-727254264
-     *
-     */
-    const stdout = process.stdout
-    if (isExtendedWriteStream(stdout)) {
-      stdout._handle.setBlocking(true)
-    }
-
-    outputResult(JSON.stringify(formatOffensesJson(offensesByFile, environment)))
+  protected renderEnvironmentResults(environments: {environment: string; result: unknown}[]): void {
+    outputResult(encodeThemeCheckResult(themeCheckJsonOutputSchema.validate({environments})))
   }
+}
 
-  return {offenses, theme}
+// Compatibility adapter for theme push, which still presents check results as text.
+export async function runThemeCheck(path: string, outputFormat: string, config?: string, environment?: string) {
+  const result = await checkTheme(path, config, environment)
+  renderThemeCheckResult(result, outputFormat, path, environment)
+  return {offenses: result.offenses, theme: result.theme}
 }
diff --git a/packages/theme/src/cli/services/check.ts b/packages/theme/src/cli/services/check.ts
index 154ce4079da..38dbe9b186d 100644
--- a/packages/theme/src/cli/services/check.ts
+++ b/packages/theme/src/cli/services/check.ts
@@ -1,10 +1,12 @@
+import {ThemeCheckResult} from './check/types.js'
 import {fileExists, writeFile} from '@shopify/cli-kit/node/fs'
-import {outputResult, outputInfo, outputSuccess} from '@shopify/cli-kit/node/output'
+import {outputResult, outputInfo, outputSuccess, outputDebug} from '@shopify/cli-kit/node/output'
 import {joinPath, resolvePath} from '@shopify/cli-kit/node/path'
 import {renderInfo} from '@shopify/cli-kit/node/ui'
 import {uniq} from '@shopify/cli-kit/common/array'
 import {AbortError} from '@shopify/cli-kit/node/error'
 import {
+  themeCheckRun,
   Severity,
   applyFixToString,
   autofix,
@@ -21,24 +23,6 @@ type OffenseMap = Record<string, Offense[]>
 /** The contents of every theme file, keyed by its normalized uri. */
 type ThemeSourcesByUri = Map<string, string>
 
-interface TransformedOffense {
-  check: string
-  severity: string
-  start_row: number
-  start_column: number
-  end_row: number
-  end_column: number
-  message: string
-}
-
-interface TransformedOffenseMap {
-  path: string
-  offenses: TransformedOffense[]
-  errorCount: number
-  warningCount: number
-  infoCount: number
-}
-
 type SeverityCounts = Partial<{
   [Severity.ERROR]: number
   [Severity.WARNING]: number
@@ -58,7 +42,7 @@ function isMissingThemeCheckConfigFile(error: unknown, configPath: string) {
   )
 }
 
-export async function withThemeCheckConfigErrorHandling<T>(
+async function withThemeCheckConfigErrorHandling<T>(
   configPath: string | undefined,
   operation: () => Promise<T>,
 ): Promise<T> {
@@ -87,7 +71,7 @@ function failLevelToSeverity(failLevel: FailLevel): Severity | undefined {
   }
 }
 
-function severityToLabel(severity: Severity) {
+function severityToLabel(severity: Severity): 'error' | 'warning' | 'info' {
   switch (severity) {
     case Severity.ERROR:
       return 'error'
@@ -248,7 +232,7 @@ export function renderOffensesText(
   })
 }
 
-export function formatOffensesJson(offensesByFile: OffenseMap, environment?: string): TransformedOffenseMap[] {
+export function formatOffensesJson(offensesByFile: OffenseMap, environment?: string): ThemeCheckResult {
   return Object.entries(offensesByFile).map(([path, offenses]) => {
     const transformedOffenses = offenses.map((offense: Offense) => {
       return {
@@ -416,3 +400,13 @@ export function isExtendedWriteStream(stream: NodeJS.WriteStream): stream is Ext
     typeof (stream as HandleWithSetBlocking)._handle.setBlocking === 'function'
   )
 }
+
+export async function checkTheme(path: string, config?: string, environment?: string) {
+  const {offenses, theme} = await withThemeCheckConfigErrorHandling(config, () =>
+    themeCheckRun(path, config, (message) => {
+      if (process.env.SHOPIFY_TMP_FLAG_DEBUG) outputDebug(message)
+    }),
+  )
+  const result = formatOffensesJson(sortOffenses(offenses), environment)
+  return {result, offenses, theme}
+}
diff --git a/packages/theme/src/cli/services/check/result.ts b/packages/theme/src/cli/services/check/result.ts
new file mode 100644
index 00000000000..33a569ee96f
--- /dev/null
+++ b/packages/theme/src/cli/services/check/result.ts
@@ -0,0 +1,51 @@
+import {themeCheckJsonOutputSchema, type ThemeCheckResult} from './types.js'
+import {formatSummary, renderOffensesText, sortOffenses, isExtendedWriteStream} from '../check.js'
+import {outputResult} from '@shopify/cli-kit/node/output'
+import {renderInfo, renderSuccess} from '@shopify/cli-kit/node/ui'
+import {type Offense, type Theme} from '@shopify/theme-check-node'
+import {type InferJsonOutputSchema} from '@shopify/cli-kit/node/json-output-schema'
+
+export function encodeThemeCheckResult(result: InferJsonOutputSchema<typeof themeCheckJsonOutputSchema>): string {
+  // Theme Check's established JSON format is compact, unlike the shared encoder.
+  return JSON.stringify(JSON.parse(themeCheckJsonOutputSchema.encode(result)))
+}
+
+export function renderThemeCheckResult(
+  {result, offenses, theme}: {result: ThemeCheckResult; offenses: Offense[]; theme: Theme},
+  outputFormat: string,
+  path: string,
+  environment?: string,
+): void {
+  const offensesByFile = sortOffenses(offenses)
+
+  if (outputFormat === 'text') {
+    renderOffensesText(offensesByFile, path, theme, environment)
+
+    // Use renderSuccess when theres no offenses
+    const render = offenses.length ? renderInfo : renderSuccess
+
+    render({
+      headline: environment ? `[${environment}] Theme Check Summary.` : 'Theme Check Summary.',
+      body: formatSummary(offenses, offensesByFile, theme),
+    })
+  }
+
+  if (outputFormat === 'json') {
+    /**
+     * Workaround:
+     * Force stdout to be blocking so that the JSON output is not broken when piped to another process.
+     * ie: ` | jq .`
+     * It turns out that console.log is technically asynchronous, and when we call process.exit(),
+     * node doesn't wait on all the output being sent to stdout and instead closes the process immediately
+     *
+     * https://github.com/pnp/cli-microsoft365/issues/1266#issuecomment-727254264
+     *
+     */
+    const stdout = process.stdout
+    if (isExtendedWriteStream(stdout)) {
+      stdout._handle.setBlocking(true)
+    }
+
+    outputResult(encodeThemeCheckResult(result))
+  }
+}
diff --git a/packages/theme/src/cli/services/check/types.ts b/packages/theme/src/cli/services/check/types.ts
new file mode 100644
index 00000000000..cb645dd2664
--- /dev/null
+++ b/packages/theme/src/cli/services/check/types.ts
@@ -0,0 +1,34 @@
+import {defineJsonOutputSchema} from '@shopify/cli-kit/node/json-output-schema'
+import {zod} from '@shopify/cli-kit/node/schema'
+
+const ThemeCheckOffenseSchema = zod.object({
+  check: zod.string(),
+  severity: zod.enum(['error', 'warning', 'info']),
+  start_row: zod.number(),
+  start_column: zod.number(),
+  end_row: zod.number(),
+  end_column: zod.number(),
+  message: zod.string(),
+})
+const ThemeCheckFileSchema = zod.object({
+  environment: zod.string().optional(),
+  path: zod.string(),
+  offenses: zod.array(ThemeCheckOffenseSchema),
+  errorCount: zod.number(),
+  warningCount: zod.number(),
+  infoCount: zod.number(),
+})
+const ThemeCheckResultSchema = zod.array(ThemeCheckFileSchema)
+const ThemeCheckEnvironmentSchema = zod.object({environment: zod.string(), result: ThemeCheckResultSchema})
+
+export const themeCheckJsonOutputSchema = defineJsonOutputSchema({
+  name: 'ThemeCheckResult',
+  schema: zod.union([ThemeCheckResultSchema, zod.object({environments: zod.array(ThemeCheckEnvironmentSchema)})]),
+  definitions: {
+    ThemeCheckOffense: ThemeCheckOffenseSchema,
+    ThemeCheckFile: ThemeCheckFileSchema,
+    ThemeCheckEnvironment: ThemeCheckEnvironmentSchema,
+  },
+})
+
+export type ThemeCheckResult = zod.infer<typeof ThemeCheckResultSchema>