@visulima/vis 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/packem_chunks/handler21.js

@@ -0,0 +1,222 @@
+import { readLastRunSummary } from '@visulima/task-runner';
+import { p as pail } from './bin.js';
+import { l as listRunSummaries, r as readRunSummaryById } from '../packem_shared/run-summary-utils-PVMl4aIh.js';
+
+const VALID_FORMATS = /* @__PURE__ */ new Set(["json", "table"]);
+const resolveWorkspaceRoot = (workspaceRoot) => workspaceRoot ?? process.cwd();
+const formatDuration = (ms) => {
+  if (ms === void 0) {
+    return "-";
+  }
+  if (ms < 1e3) {
+    return `${String(ms)}ms`;
+  }
+  return `${(ms / 1e3).toFixed(2)}s`;
+};
+const formatStatus = (task) => {
+  if (task.exitCode === void 0) {
+    return task.cacheStatus;
+  }
+  if (task.exitCode === 0) {
+    return task.cacheStatus === "MISS" ? "OK" : task.cacheStatus;
+  }
+  return `FAIL(${String(task.exitCode)})`;
+};
+const padCell = (value, width) => {
+  if (value.length >= width) {
+    return value;
+  }
+  return value + " ".repeat(width - value.length);
+};
+const isFailedTask = (task) => task.exitCode !== void 0 && task.exitCode !== 0;
+const renderRunHeader = (summary, logger) => {
+  logger.info(`Run ${summary.id}`);
+  logger.info(`  start:    ${summary.startTime}`);
+  logger.info(`  end:      ${summary.endTime}`);
+  logger.info(`  duration: ${formatDuration(summary.duration)}`);
+  logger.info(
+    `  totals:   ${String(summary.stats.total)} total · ${String(summary.stats.succeeded)} ok · ${String(summary.stats.cached)} cached · ${String(summary.stats.skipped)} skipped · ${String(summary.stats.failed)} failed`
+  );
+  logger.info(`  env:      node ${summary.environment.nodeVersion} · ${summary.environment.platform}/${summary.environment.arch}`);
+  logger.info("");
+};
+const renderTaskTable = (tasks, logger) => {
+  if (tasks.length === 0) {
+    logger.info("(no tasks match the current filter)");
+    return;
+  }
+  const rows = tasks.map((task) => ({
+    duration: formatDuration(task.duration),
+    hash: task.hash ? task.hash.slice(0, 12) : "-",
+    status: formatStatus(task),
+    taskId: task.taskId
+  }));
+  const widths = {
+    duration: Math.max("duration".length, ...rows.map((r) => r.duration.length)),
+    hash: Math.max("hash".length, ...rows.map((r) => r.hash.length)),
+    status: Math.max("status".length, ...rows.map((r) => r.status.length)),
+    taskId: Math.max("task".length, ...rows.map((r) => r.taskId.length))
+  };
+  logger.info(
+    `  ${padCell("task", widths.taskId)}  ${padCell("status", widths.status)}  ${padCell("duration", widths.duration)}  ${padCell("hash", widths.hash)}`
+  );
+  logger.info(`  ${"-".repeat(widths.taskId)}  ${"-".repeat(widths.status)}  ${"-".repeat(widths.duration)}  ${"-".repeat(widths.hash)}`);
+  for (const row of rows) {
+    logger.info(
+      `  ${padCell(row.taskId, widths.taskId)}  ${padCell(row.status, widths.status)}  ${padCell(row.duration, widths.duration)}  ${padCell(row.hash, widths.hash)}`
+    );
+  }
+};
+const renderTaskDetail = (summary, task, logger) => {
+  renderRunHeader(summary, logger);
+  logger.info(`Task ${task.taskId}`);
+  logger.info(`  status:    ${formatStatus(task)}`);
+  logger.info(`  cache:     ${task.cacheStatus}`);
+  logger.info(`  duration:  ${formatDuration(task.duration)}`);
+  logger.info(`  exit:      ${task.exitCode === void 0 ? "-" : String(task.exitCode)}`);
+  logger.info(`  hash:      ${task.hash ?? "(none)"}`);
+  logger.info(`  start:     ${task.startTime ?? "-"}`);
+  logger.info(`  end:       ${task.endTime ?? "-"}`);
+  if (task.dependencies.length > 0) {
+    logger.info(`  deps:      ${task.dependencies.join(", ")}`);
+  }
+  logger.info("");
+  pail.info(`Drill into hash inputs with: vis cache why ${task.taskId} --run ${summary.id}`);
+};
+const renderListJson = (entries) => {
+  process.stdout.write(
+    `${JSON.stringify(
+      entries.map((entry) => ({
+        id: entry.id,
+        mtime: new Date(entry.mtimeMs).toISOString(),
+        path: entry.path
+      })),
+      void 0,
+      2
+    )}
+`
+  );
+};
+const renderListTable = (entries, logger) => {
+  if (entries.length === 0) {
+    pail.info("No recorded runs found in .task-runner/runs/. Run with --summarize to record a run.");
+    return;
+  }
+  const widths = {
+    id: Math.max("id".length, ...entries.map((entry) => entry.id.length)),
+    mtime: 24
+  };
+  logger.info(`  ${padCell("id", widths.id)}  ${padCell("mtime", widths.mtime)}`);
+  logger.info(`  ${"-".repeat(widths.id)}  ${"-".repeat(widths.mtime)}`);
+  for (const entry of entries) {
+    logger.info(`  ${padCell(entry.id, widths.id)}  ${new Date(entry.mtimeMs).toISOString()}`);
+  }
+};
+const filterTasks = (summary, options) => {
+  let tasks = summary.tasks;
+  if (options.task !== void 0) {
+    tasks = tasks.filter((t) => t.taskId === options.task);
+  }
+  if (options.failed) {
+    tasks = tasks.filter((t) => isFailedTask(t));
+  }
+  return tasks;
+};
+const runReplay = async (options, logger) => {
+  const { failed, format, runId, task: taskFilter, workspaceRoot } = options;
+  const summary = runId === void 0 ? await readLastRunSummary(workspaceRoot) : await readRunSummaryById(workspaceRoot, runId);
+  if (!summary) {
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify({ error: "no-summary", runId: runId ?? null }, void 0, 2)}
+`);
+      process.exitCode = 1;
+      return;
+    }
+    if (runId === void 0) {
+      pail.error("No previous run summary found. Run a task first to populate `.task-runner/last-summary.json`.");
+    } else {
+      pail.error(`Run summary "${runId}" not found in .task-runner/runs/.`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const filteredTasks = filterTasks(summary, { failed, task: taskFilter });
+  if (taskFilter !== void 0 && filteredTasks.length === 0) {
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify({ error: "task-not-in-summary", runId: summary.id, taskId: taskFilter }, void 0, 2)}
+`);
+      process.exitCode = 1;
+      return;
+    }
+    pail.error(`Task "${taskFilter}" was not part of run ${summary.id}.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (summary.stats.failed > 0) {
+    process.exitCode = 1;
+  }
+  if (format === "json") {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          duration: summary.duration,
+          endTime: summary.endTime,
+          environment: summary.environment,
+          runId: summary.id,
+          startTime: summary.startTime,
+          stats: summary.stats,
+          tasks: filteredTasks.map((t) => ({
+            cacheStatus: t.cacheStatus,
+            dependencies: t.dependencies,
+            duration: t.duration,
+            endTime: t.endTime,
+            exitCode: t.exitCode,
+            hash: t.hash ?? null,
+            startTime: t.startTime,
+            taskId: t.taskId
+          }))
+        },
+        void 0,
+        2
+      )}
+`
+    );
+    return;
+  }
+  if (taskFilter !== void 0) {
+    renderTaskDetail(summary, filteredTasks[0], logger);
+    return;
+  }
+  renderRunHeader(summary, logger);
+  renderTaskTable(filteredTasks, logger);
+};
+const replayExecute = async ({ logger, options, workspaceRoot: wsRoot }) => {
+  const workspaceRoot = resolveWorkspaceRoot(wsRoot);
+  const format = options.format ?? "table";
+  if (!VALID_FORMATS.has(format)) {
+    pail.error(`Invalid --format: ${format}. Expected "table" or "json".`);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.list === true) {
+    const entries = await listRunSummaries(workspaceRoot);
+    if (format === "json") {
+      renderListJson(entries);
+      return;
+    }
+    renderListTable(entries, logger);
+    return;
+  }
+  await runReplay(
+    {
+      failed: options.failed === true,
+      format,
+      runId: options.run,
+      task: options.task,
+      workspaceRoot
+    },
+    logger
+  );
+};
+
+export { replayExecute as default, replayExecute, runReplay };

package/dist/packem_chunks/handler22.js

@@ -0,0 +1,237 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  writeFileSync
+} = __cjs_getBuiltinModule("node:fs");
+import { readFileSync, isAccessibleSync } from '@visulima/fs';
+import { join, relative, basename, resolve } from '@visulima/path';
+import zeptomatch from 'zeptomatch';
+import { sortPackageJsonStringWithOptions } from '#native';
+import { p as pail, q as readPnpmWorkspacePatterns, o as resolveWorkspacePatterns } from './bin.js';
+import { e as errorMessage } from '../packem_shared/utils-CthVdBPS.js';
+
+const findPackageJsonFiles = (root) => {
+  const seen = /* @__PURE__ */ new Set();
+  const results = [];
+  const addFile = (filePath) => {
+    const resolved = resolve(filePath);
+    if (!seen.has(resolved) && isAccessibleSync(resolved)) {
+      seen.add(resolved);
+      results.push(resolved);
+    }
+  };
+  addFile(join(root, "package.json"));
+  const pnpmPatterns = readPnpmWorkspacePatterns(root);
+  if (pnpmPatterns) {
+    const projectDirectories = resolveWorkspacePatterns(root, pnpmPatterns);
+    for (const dir of projectDirectories) {
+      addFile(join(root, dir, "package.json"));
+    }
+  } else {
+    const rootPkgPath = join(root, "package.json");
+    if (isAccessibleSync(rootPkgPath)) {
+      const rootPkg = JSON.parse(readFileSync(rootPkgPath));
+      const patterns = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : rootPkg.workspaces?.packages;
+      if (patterns) {
+        const projectDirectories = resolveWorkspacePatterns(root, patterns);
+        for (const dir of projectDirectories) {
+          addFile(join(root, dir, "package.json"));
+        }
+      }
+    }
+  }
+  return results;
+};
+const detectIndent = (contents) => {
+  const match = /\n([ \t]+)/.exec(contents);
+  return match?.[1] ?? "  ";
+};
+const resolveIndentOverride = (raw) => {
+  if (raw === void 0 || raw === "") {
+    return void 0;
+  }
+  if (raw === "tab" || raw === String.raw`\t`) {
+    return "	";
+  }
+  if (/^\d+$/.test(raw)) {
+    return " ".repeat(Number.parseInt(raw, 10));
+  }
+  return raw;
+};
+const splitList = (raw) => {
+  if (raw === void 0) {
+    return [];
+  }
+  const items = Array.isArray(raw) ? raw : [raw];
+  return items.flatMap((item) => item.split(",")).map((item) => item.trim()).filter((item) => item.length > 0);
+};
+const detectLineEnding = (contents) => contents.includes("\r\n") ? "crlf" : "lf";
+const ALLOWED_LINE_ENDINGS = /* @__PURE__ */ new Set(["auto", "crlf", "lf"]);
+const validateLineEnding = (raw) => {
+  if (raw === void 0 || raw === "") {
+    return "auto";
+  }
+  if (ALLOWED_LINE_ENDINGS.has(raw)) {
+    return raw;
+  }
+  pail.error(`--line-ending must be one of: auto, lf, crlf (got "${raw}")`);
+  process.exit(2);
+};
+const filterByIgnore = (files, patterns, cwd) => {
+  if (patterns.length === 0) {
+    return files;
+  }
+  return files.filter((absolute) => {
+    const relPath = relative(cwd, absolute);
+    const base = basename(absolute);
+    return !patterns.some((pattern) => {
+      const target = pattern.includes("/") ? relPath : base;
+      return zeptomatch(pattern, target);
+    });
+  });
+};
+const applySortOrder = (object, sortOrder) => {
+  if (sortOrder.length === 0) {
+    return object;
+  }
+  const result = {};
+  const consumed = /* @__PURE__ */ new Set();
+  for (const key of sortOrder) {
+    if (Object.hasOwn(object, key)) {
+      result[key] = object[key];
+      consumed.add(key);
+    }
+  }
+  for (const key of Object.keys(object)) {
+    if (!consumed.has(key)) {
+      result[key] = object[key];
+    }
+  }
+  return result;
+};
+const restoreUnsortedSections = (sorted, original, unsorted) => {
+  if (unsorted.length === 0) {
+    return sorted;
+  }
+  const result = { ...sorted };
+  for (const key of unsorted) {
+    if (Object.hasOwn(original, key)) {
+      result[key] = original[key];
+    }
+  }
+  return result;
+};
+const sortContents = (contents, config) => {
+  const indent = config.indent ?? detectIndent(contents);
+  const lineEnding = config.lineEnding === "auto" ? detectLineEnding(contents) : config.lineEnding;
+  const compact = sortPackageJsonStringWithOptions(contents, {
+    pretty: false,
+    sortScripts: config.sortScripts
+  });
+  let parsed = JSON.parse(compact);
+  if (config.unsorted.length > 0) {
+    const original = JSON.parse(contents);
+    parsed = restoreUnsortedSections(parsed, original, config.unsorted);
+  }
+  parsed = applySortOrder(parsed, config.sortOrder);
+  let output = JSON.stringify(parsed, null, indent);
+  if (config.finalNewline) {
+    output += "\n";
+  }
+  if (lineEnding === "crlf") {
+    output = output.replaceAll("\n", "\r\n");
+  }
+  return output;
+};
+const execute = async ({ options, visConfig, workspaceRoot: wsRoot }) => {
+  const cwd = wsRoot ?? process.cwd();
+  const config = visConfig?.["sortPackageJson"];
+  const check = options.check || false;
+  const normalized = {
+    finalNewline: options.finalNewline ?? config?.finalNewline ?? true,
+    ignore: [...splitList(options.ignore), ...config?.ignore ?? []],
+    indent: resolveIndentOverride(options.indent ?? config?.indent),
+    lineEnding: validateLineEnding(options.lineEnding ?? config?.lineEnding),
+    sortOrder: [...splitList(options.sortOrder), ...config?.sortOrder ?? []],
+    sortScripts: options.sortScripts || config?.sortScripts || false,
+    unsorted: [...splitList(options.unsorted), ...config?.unsorted ?? []]
+  };
+  const allFiles = findPackageJsonFiles(cwd);
+  const files = filterByIgnore(allFiles, normalized.ignore, cwd);
+  if (files.length === 0) {
+    pail.info(allFiles.length === 0 ? "No package.json files found." : "All package.json files were excluded by --ignore.");
+    return;
+  }
+  let unsortedCount = 0;
+  let sortedCount = 0;
+  let errorCount = 0;
+  for (const filePath of files) {
+    try {
+      const contents = readFileSync(filePath);
+      let sorted;
+      try {
+        sorted = sortContents(contents, normalized);
+      } catch (error) {
+        pail.error(`${filePath}: ${errorMessage(error)}`);
+        errorCount++;
+        continue;
+      }
+      if (contents === sorted) {
+        sortedCount++;
+        continue;
+      }
+      unsortedCount++;
+      if (check) {
+        pail.warn(`${filePath} is not sorted`);
+      } else {
+        writeFileSync(filePath, sorted, "utf8");
+        pail.success(`Sorted ${filePath}`);
+      }
+    } catch (error) {
+      pail.error(`${filePath}: ${errorMessage(error)}`);
+      errorCount++;
+    }
+  }
+  if (check) {
+    if (unsortedCount > 0) {
+      pail.info(`${unsortedCount} file${unsortedCount === 1 ? "" : "s"} not sorted, ${sortedCount} already sorted`);
+      process.exitCode = 1;
+    } else {
+      pail.info(`All ${sortedCount} package.json file${sortedCount === 1 ? " is" : "s are"} sorted`);
+    }
+  } else {
+    const parts = [];
+    if (unsortedCount > 0) {
+      parts.push(`sorted ${unsortedCount} file${unsortedCount === 1 ? "" : "s"}`);
+    }
+    if (sortedCount > 0) {
+      parts.push(`${sortedCount} already sorted`);
+    }
+    if (errorCount > 0) {
+      parts.push(`${errorCount} error${errorCount === 1 ? "" : "s"}`);
+    }
+    pail.info(parts.join(", "));
+  }
+  if (errorCount > 0) {
+    process.exitCode = 1;
+  }
+};
+
+export { execute as default };

package/dist/packem_chunks/handler23.js

@@ -0,0 +1,101 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  readdirSync
+} = __cjs_getBuiltinModule("node:fs");
+import { dim, green, yellow, red } from '@visulima/colorize';
+import { isAccessibleSync, readJsonSync } from '@visulima/fs';
+import { join } from '@visulima/path';
+import { enforceProjectConstraints } from '@visulima/task-runner';
+import { d as discoverWorkspace, b as buildProjectGraph } from './bin.js';
+import { a as analyzeFlakiness } from '../packem_shared/flakiness-goTxXuCX.js';
+import { c as checkRuntimeVersions } from '../packem_shared/runtime-check-Cobi3p6l.js';
+
+const icon = (ok) => ok ? green("✓") : red("✗");
+const execute = async ({ logger, options, visConfig, workspaceRoot: wsRoot }) => {
+  if (!wsRoot) {
+    throw new Error("Could not determine workspace root.");
+  }
+  const { config, packageJsons, workspace } = discoverWorkspace(wsRoot, visConfig);
+  const projectGraph = buildProjectGraph(wsRoot, workspace, packageJsons);
+  const projectCount = Object.keys(workspace.projects).length;
+  const targetCount = new Set(Object.values(workspace.projects).flatMap((p) => Object.keys(p.targets ?? {}))).size;
+  const runtimeFindings = checkRuntimeVersions(wsRoot);
+  let constraintViolations = 0;
+  if (config.constraints) {
+    constraintViolations = enforceProjectConstraints(projectGraph, config.constraints).length;
+  }
+  const flakyStats = analyzeFlakiness(wsRoot, { minRuns: 2 });
+  let cacheHitRate;
+  const runsDir = join(wsRoot, ".task-runner", "runs");
+  if (isAccessibleSync(runsDir)) {
+    const files = readdirSync(runsDir).filter((f) => f.endsWith(".json")).sort();
+    let totalTasks = 0;
+    let cachedTasks = 0;
+    for (const file of files.slice(-20)) {
+      try {
+        const data = readJsonSync(join(runsDir, file));
+        if (data.stats) {
+          totalTasks += data.stats.total ?? 0;
+          cachedTasks += data.stats.cached ?? 0;
+        }
+      } catch {
+        continue;
+      }
+    }
+    if (totalTasks > 0) {
+      cacheHitRate = `${(cachedTasks / totalTasks * 100).toFixed(0)}%`;
+    }
+  }
+  if (options.json) {
+    logger.info(
+      JSON.stringify(
+        {
+          cacheHitRate: cacheHitRate ?? null,
+          constraintViolations,
+          flakyTasks: flakyStats.length,
+          projects: projectCount,
+          runtimeIssues: runtimeFindings.length,
+          targets: targetCount
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  logger.info("");
+  logger.info(`  ${dim("VIS STATUS")}`);
+  logger.info("");
+  logger.info(`  ${icon(true)} ${String(projectCount)} projects · ${String(targetCount)} unique targets`);
+  logger.info(
+    `  ${icon(runtimeFindings.length === 0)} Runtime: ${runtimeFindings.length === 0 ? green("OK") : yellow(`${String(runtimeFindings.length)} issue(s)`)}`
+  );
+  logger.info(
+    `  ${icon(constraintViolations === 0)} Constraints: ${constraintViolations === 0 ? green("OK") : red(`${String(constraintViolations)} violation(s)`)}`
+  );
+  logger.info(`  ${icon(flakyStats.length === 0)} Flaky tasks: ${flakyStats.length === 0 ? green("none") : yellow(String(flakyStats.length))}`);
+  if (cacheHitRate) {
+    logger.info(`  ${icon(true)} Cache hit rate: ${cacheHitRate} (last 20 runs)`);
+  }
+  logger.info("");
+};
+
+export { execute as default };

package/dist/packem_chunks/handler24.js

@@ -0,0 +1,110 @@
+import { createTaskGraph } from '@visulima/task-runner';
+import { d as discoverWorkspace, b as buildProjectGraph } from './bin.js';
+
+const findShortestPathToRoot = (graph, target) => {
+  const reverse = /* @__PURE__ */ new Map();
+  for (const [parent, deps] of Object.entries(graph.dependencies)) {
+    for (const dep of deps) {
+      const list = reverse.get(dep) ?? [];
+      list.push(parent);
+      reverse.set(dep, list);
+    }
+  }
+  if (!graph.tasks[target]) {
+    return void 0;
+  }
+  const visited = /* @__PURE__ */ new Set([target]);
+  const queue = [{ node: target, path: [target] }];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (graph.roots.includes(current.node)) {
+      return current.path;
+    }
+    for (const parent of reverse.get(current.node) ?? []) {
+      if (visited.has(parent)) {
+        continue;
+      }
+      visited.add(parent);
+      queue.push({ node: parent, path: [parent, ...current.path] });
+    }
+  }
+  return [target];
+};
+const collectParents = (graph, target) => {
+  const parents = [];
+  for (const [parent, deps] of Object.entries(graph.dependencies)) {
+    if (deps.includes(target)) {
+      parents.push(parent);
+    }
+  }
+  return parents.sort();
+};
+const execute = async ({ argument, logger, visConfig, workspaceRoot: wsRoot }) => {
+  if (!wsRoot) {
+    throw new Error("Could not determine workspace root.");
+  }
+  const taskId = argument[0];
+  if (!taskId) {
+    throw new Error("No task ID specified. Usage: vis task-why <project>:<target>");
+  }
+  if (!taskId.includes(":")) {
+    throw new Error(`Invalid task ID "${taskId}" — expected format "project:target".`);
+  }
+  const { packageJsons, workspace } = discoverWorkspace(wsRoot, visConfig);
+  const projectGraph = buildProjectGraph(wsRoot, workspace, packageJsons);
+  const [projectName, targetName] = taskId.split(":", 2);
+  const project = workspace.projects[projectName];
+  if (!project) {
+    throw new Error(`Unknown project "${projectName}".`);
+  }
+  if (!project.targets?.[targetName]) {
+    throw new Error(`Project "${projectName}" has no target "${targetName}".`);
+  }
+  const allInitialTasks = Object.entries(workspace.projects).flatMap(
+    ([name, proj]) => Object.keys(proj.targets ?? {}).map((t) => {
+      return {
+        id: `${name}:${t}`,
+        outputs: [],
+        overrides: {},
+        target: { project: name, target: t }
+      };
+    })
+  );
+  const graph = createTaskGraph(allInitialTasks, { projectGraph, workspace });
+  if (!graph.tasks[taskId]) {
+    throw new Error(`Task "${taskId}" is not reachable in the graph.`);
+  }
+  const path = findShortestPathToRoot(graph, taskId);
+  const parents = collectParents(graph, taskId);
+  logger.info("");
+  logger.info(`Why ${taskId}?`);
+  logger.info("");
+  if (path && path.length > 1) {
+    logger.info("Shortest path from a root to this task:");
+    for (const [index, node] of path.entries()) {
+      const prefix = index === 0 ? "  " : `${"  ".repeat(index + 1)}└─ `;
+      logger.info(`${prefix}${node}`);
+    }
+    logger.info("");
+  } else {
+    logger.info("  This task is itself a root — nothing upstream depends on it.");
+    logger.info("");
+  }
+  if (parents.length > 0) {
+    logger.info(`Directly depended on by ${parents.length} task(s):`);
+    for (const parent of parents) {
+      logger.info(`  - ${parent}`);
+    }
+    logger.info("");
+  }
+  const directDeps = graph.dependencies[taskId] ?? [];
+  if (directDeps.length > 0) {
+    logger.info(`This task depends on ${directDeps.length} task(s):`);
+    for (const dep of [...directDeps].sort()) {
+      logger.info(`  - ${dep}`);
+    }
+    logger.info("");
+  }
+};
+
+export { execute as default };