From 11312b359b18c07911615656b95f48c7d8d82fea Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 29 Oct 2026 04:08:41 +0000
Subject: [PATCH] fix(cli): check says a lint error is why the browser pass was
 skipped (#6709)

* fix(cli): check says a lint error is why the browser pass was skipped

* style(cli): drop a doc comment the comment ratchet would count
---
 packages/cli/src/commands/check.test.ts | 22 ++++++++++++++++++++++
 packages/cli/src/commands/check.ts      | 11 ++++++++---
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/packages/cli/src/commands/check.test.ts b/packages/cli/src/commands/check.test.ts
index 4a35dc4232..1dc0f5be32 100644
--- a/packages/cli/src/commands/check.test.ts
+++ b/packages/cli/src/commands/check.test.ts
@@ -1567,6 +1567,28 @@ describe("check pipeline", () => {
     expect(report.contrast).toMatchObject({ ok: true, errorCount: 0, findings: [] });
   });
 
+  it("says in plain words that a lint error is why the browser pass was skipped", async () => {
+    const lint = lintWith(
+      "error",
+      "root_missing_composition_id",
+      "Root needs data-composition-id.",
+    );
+    const { report } = await runScenario(fakeDriver(), {}, { lint });
+    const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    const command = createCheckCommand({
+      resolveProject: () => PROJECT,
+      runPipeline: vi.fn(async () => report),
+      prepareMedia: vi.fn(async () => []),
+      withMeta: (value) => value,
+    });
+
+    await runViaCli(command, { rawArgs: [] });
+
+    const said = log.mock.calls.map((call) => String(call[0])).join("\n");
+    expect(said).toContain("Browser validation skipped because of the lint error above");
+    expect(said).not.toContain("Browser session never ran");
+  });
+
   it("marks browserSkipped true when the linter itself crashes", async () => {
     const { deps } = dependencies(fakeDriver());
     deps.lintProject = vi.fn(async () => {
diff --git a/packages/cli/src/commands/check.ts b/packages/cli/src/commands/check.ts
index 20cf1b98f9..3a402382eb 100644
--- a/packages/cli/src/commands/check.ts
+++ b/packages/cli/src/commands/check.ts
@@ -639,6 +639,13 @@ function nonNegativeNumber(value: unknown, fallback: number): number {
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
 }
 
+function browserSkippedLine(report: CheckReport): string {
+  const lintError = report.lint.findings.some((finding) => finding.severity === "error");
+  return lintError
+    ? "Browser validation skipped because of the lint error above: fix it and run check again. Layout, motion, and contrast were not checked, so this is not a clean pass."
+    : "Browser session never ran — layout, motion, and contrast below are empty placeholders, not a clean pass.";
+}
+
 function printHumanReport(report: CheckReport): void {
   if (report.scope) {
     console.log(
@@ -649,9 +656,7 @@ function printHumanReport(report: CheckReport): void {
   printSection("Lint", report.lint);
   if (report.browserSkipped) {
     console.log();
-    console.log(
-      `  ${c.warn("⚠")} Browser session never ran — layout, motion, and contrast below are empty placeholders, not a clean pass.`,
-    );
+    console.log(`  ${c.warn("⚠")} ${browserSkippedLine(report)}`);
   }
   printSection("Runtime", report.runtime);
   printLayoutSection("Layout", report.layout);