feat(FN-3234): refactor test-changed script and add workflow tests

This merge refactors the test-changed script and adds new CLI tests (FN-3234), keeping automation on the full-suite path. It includes a new test file for the root test command, updates to the CI workflow, and documentation improvements.

Fusion-Task-Id: FN-3234

.github/workflows/pr-checks.yml

@@ -38,5 +38,5 @@ jobs:
       - name: Typecheck
         run: pnpm typecheck
 
-      - name: Test
-        run: pnpm test
+      - name: Test (full suite)
+        run: pnpm test:full

docs/contributing.md

@@ -44,7 +44,8 @@ pnpm build:all  # full recursive build including desktop/mobile
 pnpm dev               # build + run CLI entrypoint in dev mode
 pnpm dev:ui            # dashboard dev server only
 pnpm lint              # lint all packages
-pnpm test              # workspace test suite (clean-worktree compatible)
+pnpm test              # changed-only workspace tests (falls back to full suite in safety contexts)
+pnpm test:full         # full workspace test suite (clean-worktree compatible)
 pnpm build             # workspace builds (excludes desktop/mobile)
 pnpm build:all         # full workspace build (includes desktop/mobile)
 pnpm verify:workspace  # canonical lint -> test -> build verification gate
@@ -56,15 +57,17 @@ pnpm typecheck         # workspace typechecks
 Fusion codifies workspace verification as a deterministic contract:
 
 - Use `pnpm install --frozen-lockfile` for clean bootstrap and dependency repair paths.
-- `pnpm test` must be runnable in a clean worktree without requiring a prior `pnpm build`.
+- `pnpm test:full` must be runnable in a clean worktree without requiring a prior `pnpm build`.
 - This includes clean states where `packages/core/dist`, `packages/engine/dist`, and `packages/dashboard/dist` are absent.
 - `pnpm verify:workspace` is the canonical pre-merge gate and runs in strict order:
   1. `pnpm lint`
-  2. `pnpm test`
+  2. `pnpm test:full`
   3. `pnpm build`
 
 CI uses `pnpm verify:workspace` directly, so changes that reintroduce hidden test pre-build dependencies fail fast.
 
+`pnpm test` now uses a changed-only entrypoint (`scripts/test-changed.mjs`) for faster local iteration. It resolves the comparison base from `.changeset/config.json` (`baseBranch`) and runs only affected package test scripts using safe package-first filtering (`pnpm --filter <pkg> test`). It automatically falls back to the full suite when the run is forced (CI / `--full`), the git comparison base or diff cannot be resolved, no changes are detected, or shared/root test infrastructure changes.
+
 ## Quality Gate Checklist
 
 Before submitting changes, verify:

package.json

@@ -22,15 +22,16 @@
     "sync:fusion-skill:check": "node scripts/sync-fusion-skill-tools.mjs --check",
     "build": "pnpm -r --filter=!@fusion/desktop --filter=!@fusion/mobile build",
     "build:all": "pnpm -r build",
-    "verify:workspace": "pnpm lint && pnpm test && pnpm build",
+    "verify:workspace": "pnpm lint && pnpm test:full && pnpm build",
     "build:exe": "pnpm build && pnpm --filter @runfusion/fusion build:exe",
     "build:exe:all": "pnpm build && pnpm --filter @runfusion/fusion build:exe:all",
-    "test": "pnpm sync:fusion-skill:check && FUSION_TEST_TOTAL_WORKERS=4 FUSION_TEST_CONCURRENCY=2 pnpm -r --workspace-concurrency=2 test",
+    "test": "node scripts/test-changed.mjs",
+    "test:full": "pnpm sync:fusion-skill:check && FUSION_TEST_TOTAL_WORKERS=4 FUSION_TEST_CONCURRENCY=2 pnpm -r --workspace-concurrency=2 test",
     "test:serial": "FUSION_TEST_TOTAL_WORKERS=4 FUSION_TEST_CONCURRENCY=1 pnpm -r --workspace-concurrency=1 test",
     "test:fast": "FUSION_TEST_TOTAL_WORKERS=4 FUSION_TEST_CONCURRENCY=4 pnpm -r --workspace-concurrency=4 test",
     "test:locked": "node scripts/test-with-lock.mjs",
     "test:build": "pnpm --filter @fusion/dashboard test:build",
-    "test:isolated": "node scripts/check-test-isolation.mjs --before && pnpm test && node scripts/check-test-isolation.mjs",
+    "test:isolated": "node scripts/check-test-isolation.mjs --before && pnpm test:full && node scripts/check-test-isolation.mjs",
     "test:check-isolation": "node scripts/check-test-isolation.mjs",
     "test:coverage": "pnpm -r --workspace-concurrency=1 exec vitest run --silent=passed-only --reporter=dot --coverage",
     "test:coverage:core": "pnpm --filter @fusion/core exec vitest run --silent=passed-only --reporter=dot --coverage",

packages/cli/src/__tests__/ci-workflow.test.ts

@@ -103,11 +103,12 @@ describe("CI workflow (.github/workflows/ci.yml)", () => {
   });
 
   it("keeps contributing docs aligned with verification and slow-lane contracts", () => {
-    expect(contributingContent).toContain("pnpm test` must be runnable in a clean worktree without requiring a prior `pnpm build`.");
+    expect(contributingContent).toContain("pnpm test:full` must be runnable in a clean worktree without requiring a prior `pnpm build`.");
     expect(contributingContent).toContain("`pnpm verify:workspace` is the canonical pre-merge gate");
     expect(contributingContent).toContain("1. `pnpm lint`");
-    expect(contributingContent).toContain("2. `pnpm test`");
+    expect(contributingContent).toContain("2. `pnpm test:full`");
     expect(contributingContent).toContain("3. `pnpm build`");
+    expect(contributingContent).toContain("`pnpm test` now uses a changed-only entrypoint");
 
     expect(contributingContent).toContain("pnpm test:slow-cli");
     expect(contributingContent).toContain("test:pre-release");
@@ -154,6 +155,35 @@ describe("CI workflow (.github/workflows/ci.yml)", () => {
   });
 });
 
+describe("PR checks workflow (.github/workflows/pr-checks.yml)", () => {
+  let workflow: any;
+  let content: string;
+  let steps: any[];
+
+  beforeAll(() => {
+    const result = loadWorkflow("pr-checks.yml");
+    workflow = result.parsed;
+    content = result.content;
+    steps = workflow.jobs?.checks?.steps ?? [];
+  });
+
+  it("is valid YAML", () => {
+    expect(workflow).toBeDefined();
+    expect(typeof workflow).toBe("object");
+  });
+
+  it("runs on pull requests targeting main", () => {
+    expect(workflow.on?.pull_request?.branches).toContain("main");
+  });
+
+  it("runs explicit full-suite tests (not changed-only root test)", () => {
+    const testStep = steps.find((step: any) => step.name?.includes("Test"));
+    expect(testStep).toBeDefined();
+    expect(testStep.run).toBe("pnpm test:full");
+    expect(content).not.toContain("run: pnpm test\n");
+  });
+});
+
 describe("Version & Release workflow (.github/workflows/version.yml)", () => {
   let workflow: any;
   let content: string;

packages/cli/src/__tests__/package-config.test.ts

@@ -114,19 +114,18 @@ describe("Scoped @fusion/* packages publishing config", () => {
 describe("Workspace bootstrap script contract", () => {
   const rootPkg = loadRootPackageJson();
 
-  it("keeps root test self-sufficient (no implicit pre-build dependency)", () => {
-    const testScript = rootPkg.scripts?.test;
-    expect(testScript).toBeDefined();
-    expect(testScript).toContain("pnpm -r");
-    expect(testScript).not.toContain("pnpm build");
+  it("makes root test changed-only while keeping explicit full-suite command", () => {
+    expect(rootPkg.scripts?.test).toBe("node scripts/test-changed.mjs");
+    expect(rootPkg.scripts?.["test:full"]).toContain("pnpm -r --workspace-concurrency=2 test");
+    expect(rootPkg.scripts?.["test:full"]).not.toContain("pnpm build");
   });
 
-  it("defines verify:workspace in lint -> test -> build order", () => {
+  it("defines verify:workspace in lint -> test:full -> build order", () => {
     const verifyScript = rootPkg.scripts?.["verify:workspace"];
-    expect(verifyScript).toBe("pnpm lint && pnpm test && pnpm build");
+    expect(verifyScript).toBe("pnpm lint && pnpm test:full && pnpm build");
 
     const lintIdx = verifyScript.indexOf("pnpm lint");
-    const testIdx = verifyScript.indexOf("pnpm test");
+    const testIdx = verifyScript.indexOf("pnpm test:full");
     const buildIdx = verifyScript.indexOf("pnpm build");
 
     expect(lintIdx).toBeGreaterThanOrEqual(0);

packages/cli/src/__tests__/root-test-command.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import {
+  decideExecutionPlan,
+  resolveAffectedPackages,
+  shouldForceFullSuite,
+} from "../../../../scripts/test-changed.mjs";
+
+describe("root test command changed-only planning", () => {
+  it("uses changed mode when package-only changes are detected", () => {
+    const packageMap = new Map([
+      ["core", "@fusion/core"],
+      ["engine", "@fusion/engine"],
+    ]);
+
+    const plan = decideExecutionPlan({
+      forceFullSuite: false,
+      comparisonBase: "abc123",
+      changedFiles: ["packages/core/src/store.ts", "packages/engine/src/index.ts"],
+      packageNameByDir: packageMap,
+    });
+
+    expect(plan).toEqual({ mode: "changed", packages: ["@fusion/core", "@fusion/engine"] });
+  });
+
+  it("falls back to full suite when shared test infra changes", () => {
+    const plan = decideExecutionPlan({
+      forceFullSuite: false,
+      comparisonBase: "abc123",
+      changedFiles: ["scripts/test-with-lock.mjs"],
+      packageNameByDir: new Map([["core", "@fusion/core"]]),
+    });
+
+    expect(plan).toEqual({ mode: "full", reason: "shared-infra-changed" });
+  });
+
+  it("falls back to full suite when comparison base cannot be resolved", () => {
+    const plan = decideExecutionPlan({
+      forceFullSuite: false,
+      comparisonBase: null,
+      changedFiles: null,
+      packageNameByDir: new Map(),
+    });
+
+    expect(plan).toEqual({ mode: "full", reason: "missing-comparison-base" });
+  });
+
+  it("treats unknown package directories as full-suite fallback", () => {
+    const resolved = resolveAffectedPackages(["packages/unknown/src/index.ts"], new Map());
+    expect(resolved).toBeNull();
+  });
+
+  it("marks root workflow/config changes as full-suite triggers", () => {
+    expect(shouldForceFullSuite([".github/workflows/ci.yml"])).toBe(true);
+    expect(shouldForceFullSuite(["package.json"])).toBe(true);
+    expect(shouldForceFullSuite(["packages/core/src/store.ts"])).toBe(false);
+  });
+});

scripts/test-changed.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const rootDir = process.cwd();
+
+function run(command, commandArgs, options = {}) {
+  const result = spawnSync(command, commandArgs, {
+    cwd: rootDir,
+    stdio: "inherit",
+    ...options,
+  });
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+function gitOutput(gitArgs) {
+  const result = spawnSync("git", gitArgs, {
+    cwd: rootDir,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  if (result.status !== 0) {
+    return null;
+  }
+
+  return result.stdout.trim();
+}
+
+function getBaseBranch() {
+  const changesetConfigPath = path.join(rootDir, ".changeset", "config.json");
+  const changesetConfig = JSON.parse(readFileSync(changesetConfigPath, "utf8"));
+  return changesetConfig.baseBranch || "main";
+}
+
+function listWorkspacePackages() {
+  const packagesDir = path.join(rootDir, "packages");
+  const packageDirs = readdirSync(packagesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+
+  const packageNameByDir = new Map();
+  for (const dir of packageDirs) {
+    try {
+      const packageJsonPath = path.join(packagesDir, dir, "package.json");
+      const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+      if (typeof pkg.name === "string") {
+        packageNameByDir.set(dir, pkg.name);
+      }
+    } catch {
+      // ignore directories without package.json
+    }
+  }
+
+  return packageNameByDir;
+}
+
+export function shouldForceFullSuite(changedFiles) {
+  const fullSuitePaths = [
+    "package.json",
+    "pnpm-lock.yaml",
+    "pnpm-workspace.yaml",
+    ".changeset/config.json",
+    "vitest.workspace.ts",
+    "eslint.config.mjs",
+    "tsconfig.base.json",
+    "scripts/test-with-lock.mjs",
+    "scripts/test-changed.mjs",
+  ];
+
+  return changedFiles.some((file) => {
+    if (fullSuitePaths.includes(file)) {
+      return true;
+    }
+
+    if (file.startsWith(".github/workflows/") || file.startsWith("scripts/test-") || file.startsWith("scripts/check-test-")) {
+      return true;
+    }
+
+    if (file.startsWith("packages/") && /vitest|test/.test(path.basename(file))) {
+      return false;
+    }
+
+    if (!file.startsWith("packages/") && !file.startsWith("docs/")) {
+      return true;
+    }
+
+    return false;
+  });
+}
+
+function detectComparisonBase(baseBranch) {
+  const candidates = [
+    `origin/${baseBranch}`,
+    `refs/remotes/origin/${baseBranch}`,
+    baseBranch,
+  ];
+
+  for (const candidate of candidates) {
+    const mergeBase = gitOutput(["merge-base", "HEAD", candidate]);
+    if (mergeBase) {
+      return mergeBase;
+    }
+  }
+
+  return null;
+}
+
+function changedFilesSince(baseSha) {
+  const diff = gitOutput(["diff", "--name-only", `${baseSha}...HEAD`]);
+  if (diff === null) {
+    return null;
+  }
+  if (!diff) {
+    return [];
+  }
+  return diff.split("\n").map((entry) => entry.trim()).filter(Boolean);
+}
+
+export function resolveAffectedPackages(changedFiles, packageNameByDir) {
+  const affected = new Set();
+
+  for (const file of changedFiles) {
+    if (!file.startsWith("packages/")) {
+      continue;
+    }
+
+    const [, dir] = file.split("/");
+    const packageName = packageNameByDir.get(dir);
+    if (!packageName) {
+      return null;
+    }
+    affected.add(packageName);
+  }
+
+  return [...affected];
+}
+
+const fullSuiteEnv = {
+  ...process.env,
+  FUSION_TEST_TOTAL_WORKERS: process.env.FUSION_TEST_TOTAL_WORKERS || "4",
+  FUSION_TEST_CONCURRENCY: process.env.FUSION_TEST_CONCURRENCY || "2",
+};
+
+function runFullSuite(forwardedArgs) {
+  run("pnpm", ["-r", "--workspace-concurrency=2", "test", ...forwardedArgs], { env: fullSuiteEnv });
+}
+
+export function decideExecutionPlan({
+  forceFullSuite,
+  comparisonBase,
+  changedFiles,
+  packageNameByDir,
+}) {
+  if (forceFullSuite) return { mode: "full", reason: "forced" };
+  if (!comparisonBase) return { mode: "full", reason: "missing-comparison-base" };
+  if (!changedFiles) return { mode: "full", reason: "diff-failed" };
+  if (changedFiles.length === 0) return { mode: "full", reason: "no-changes" };
+  if (shouldForceFullSuite(changedFiles)) return { mode: "full", reason: "shared-infra-changed" };
+
+  const affectedPackages = resolveAffectedPackages(changedFiles, packageNameByDir);
+  if (!affectedPackages || affectedPackages.length === 0) return { mode: "full", reason: "no-affected-package" };
+
+  return { mode: "changed", packages: affectedPackages };
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const forceFullSuite =
+    process.env.CI === "true" ||
+    process.env.FUSION_TEST_FULL === "1" ||
+    argv.includes("--full");
+
+  const forwardedArgs = argv.filter((arg) => arg !== "--full");
+
+  run("pnpm", ["sync:fusion-skill:check"]);
+
+  const baseBranch = getBaseBranch();
+  const comparisonBase = detectComparisonBase(baseBranch);
+  const changedFiles = comparisonBase ? changedFilesSince(comparisonBase) : null;
+  const packageNameByDir = listWorkspacePackages();
+
+  const plan = decideExecutionPlan({
+    forceFullSuite,
+    comparisonBase,
+    changedFiles,
+    packageNameByDir,
+  });
+
+  if (plan.mode === "full") {
+    if (plan.reason === "missing-comparison-base") {
+      console.log(`[test-changed] could not resolve merge-base with ${baseBranch}; running full suite.`);
+    } else if (plan.reason === "diff-failed") {
+      console.log("[test-changed] failed to read git diff; running full suite.");
+    } else if (plan.reason === "no-changes") {
+      console.log("[test-changed] no changes detected against base; running full suite.");
+    } else if (plan.reason === "shared-infra-changed") {
+      console.log("[test-changed] shared/root test infrastructure changed; running full suite.");
+    } else if (plan.reason === "no-affected-package") {
+      console.log("[test-changed] no affected workspace package resolved; running full suite.");
+    }
+
+    runFullSuite(forwardedArgs);
+    return;
+  }
+
+  const filterArgs = plan.packages.flatMap((pkg) => ["--filter", pkg]);
+  console.log(`[test-changed] running tests for changed packages: ${plan.packages.join(", ")}`);
+  run("pnpm", [...filterArgs, "test", ...forwardedArgs], { env: fullSuiteEnv });
+}
+
+const currentFilePath = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === currentFilePath) {
+  main();
+}

scripts/test-with-lock.mjs

@@ -2,7 +2,7 @@
 /**
  * test-with-lock.mjs
  *
- * Serializes `pnpm test` across concurrent git-worktree agent sessions so
+ * Serializes `pnpm test:full` across concurrent git-worktree agent sessions so
  * multiple Claude Code instances don't saturate the machine with vitest forks.
  *
  * Acquires an exclusive lock at ~/.fusion/test.lock (Darwin/Linux, O_EXLOCK)
@@ -10,7 +10,7 @@
  * While waiting it prints the PID and worktree path of the lock holder so
  * the developer knows who is blocking.
  *
- * Usage:  pnpm test:locked [extra args passed to pnpm test]
+ * Usage:  pnpm test:locked [extra args passed to pnpm test:full]
  * e.g.:   pnpm test:locked --filter @fusion/core
  */
 
@@ -154,11 +154,11 @@ for (const sig of ["exit", "SIGINT", "SIGTERM", "SIGHUP"]) {
 
 await acquireWithWait();
 
-// Forward all argv after the script name to `pnpm test`.
+// Forward all argv after the script name to `pnpm test:full`.
 const extraArgs = process.argv.slice(2);
 const child = spawn(
   "pnpm",
-  ["test", ...extraArgs],
+  ["test:full", ...extraArgs],
   { stdio: "inherit", shell: false },
 );