@akanjs/devkit 3.0.0-alpha.76 → 3.0.0-alpha.78

package/libSource.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Executor, LibExecutor, WorkspaceExecutor } from "./executors";
+import { formatLibStatuses, LibSource } from "./libSource";
+
+const tempRoots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+const write = async (filePath: string, content: string) => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content);
+};
+
+// `LibExecutor.from` memoises by name, so each fixture needs a name no other test has used.
+const makeLib = async (libName: string) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-libsource-"));
+  tempRoots.push(root);
+  await write(path.join(root, "package.json"), '{ "name": "hub", "version": "0.0.1", "description": "hub" }\n');
+  await write(path.join(root, ".gitignore"), "node_modules\n");
+  await write(path.join(root, `libs/${libName}/package.json`), `{ "name": "@${libName}", "version": "0.0.1" }\n`);
+  await write(path.join(root, `libs/${libName}/common/helper.ts`), "export const helper = 1;\n");
+  await write(path.join(root, `libs/${libName}/env/env.server.testing.ts`), "export const env = { key: 1 };\n");
+
+  const git = new Executor("fixture", root);
+  await git.spawn("git", ["init", "--quiet"]);
+
+  const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: `hub-${libName}` });
+  const lib = LibExecutor.from(workspace, libName);
+  return { root, lib, source: new LibSource(lib) };
+};
+
+describe("LibSource", () => {
+  test("reports an unstamped library", async () => {
+    const { source } = await makeLib("plain-lib");
+    const status = await source.status();
+
+    expect(status.drift).toBe("unstamped");
+    expect(status.stamp).toBeNull();
+    expect(status.hash).toMatch(/^[0-9a-f]{32}$/);
+  });
+
+  test("stamps the origin into package.json and reads back clean", async () => {
+    const { lib, source } = await makeLib("stamped-lib");
+    const stamp = await source.write({ origin: "akanjs", sha: "3.0.0" });
+
+    expect(stamp.origin).toBe("akanjs");
+    expect(await source.read()).toEqual(stamp);
+    expect((await source.status()).drift).toBe("clean");
+
+    const manifest = await lib.getPackageJson();
+    expect(manifest.name).toBe("@stamped-lib");
+    expect((manifest.akan as { source: { sha: string } }).source.sha).toBe("3.0.0");
+  });
+
+  test("detects an edit to library source as drift", async () => {
+    const { root, source } = await makeLib("drift-lib");
+    await source.write({ origin: "akanjs", sha: "3.0.0" });
+    await write(path.join(root, "libs/drift-lib/common/helper.ts"), "export const helper = 2;\n");
+
+    expect((await source.status()).drift).toBe("drifted");
+  });
+
+  test("survives every other akan write to the manifest", async () => {
+    const { lib, source } = await makeLib("merge-lib");
+    const stamp = await source.write({ origin: "akanjs", sha: "3.0.0" });
+    const manifest = await lib.getPackageJson();
+    await lib.setPackageJson({ ...manifest, dependencies: { lodash: "4.0.0" } });
+
+    expect(await source.read()).toEqual(stamp);
+    expect((await source.status()).drift).toBe("drifted");
+  });
+
+  test("leaves env values out of the hash — they belong to the installing workspace", async () => {
+    const { root, source } = await makeLib("env-lib");
+    await source.write({ origin: "akanjs", sha: "3.0.0" });
+    await write(path.join(root, "libs/env-lib/env/env.server.testing.ts"), "export const env = { key: 999 };\n");
+
+    expect((await source.status()).drift).toBe("clean");
+  });
+});
+
+describe("formatLibStatuses", () => {
+  test("marks drifted libraries and counts them", () => {
+    const text = formatLibStatuses([
+      {
+        lib: "util",
+        drift: "clean",
+        hash: "a".repeat(32),
+        stamp: { origin: "akanjs", sha: "3.0.0", hash: "a".repeat(32), syncedAt: "now" },
+      },
+      {
+        lib: "shared",
+        drift: "drifted",
+        hash: "b".repeat(32),
+        stamp: { origin: "akanjs", sha: "3.0.0", hash: "a".repeat(32), syncedAt: "now" },
+      },
+      { lib: "local", drift: "unstamped", hash: "c".repeat(32), stamp: null },
+    ]);
+
+    expect(text).toContain("DRIFTED   libs/shared  akanjs@3.0.0");
+    expect(text).toContain("unstamped libs/local  no akan.source in package.json");
+    expect(text).toContain("drifted: 1 / 3");
+  });
+});

package/libSource.ts

@@ -0,0 +1,126 @@
+import type { LibExecutor } from "./executors";
+import type { PackageJson } from "./types";
+
+export interface LibSourceStamp {
+  /** Where the copy came from: a git remote URL, or `akanjs` for the published package. */
+  origin: string;
+  /** The origin's commit sha, or the package version when the origin is a registry. */
+  sha: string;
+  /** Content hash of the library as installed, so a later edit is detectable without the origin. */
+  hash: string;
+  syncedAt: string;
+}
+
+export type LibDrift = "clean" | "drifted" | "unstamped";
+
+export interface LibStatus {
+  lib: string;
+  drift: LibDrift;
+  stamp: LibSourceStamp | null;
+  hash: string;
+}
+
+/**
+ * A library's origin, recorded in its own `package.json` under an `akan.source` key.
+ *
+ * The key rides `package.json` rather than a file of its own because every akan write to a library's
+ * manifest is a spread of the existing object (`LibExecutor.syncPackageJson`), so an unknown top-level
+ * key survives — while a new root file would have to be added to `libRootAllowedFiles` before
+ * `akan sync` stopped rejecting it.
+ */
+export class LibSource {
+  static readonly manifestKey = "akan";
+  /**
+   * Left out of the hash. `env/` holds per-deployment values that belong to the workspace the library
+   * was installed into, not to the origin, so an env edit is not drift.
+   */
+  static readonly unhashedDirs = ["env"];
+
+  #lib: LibExecutor;
+  constructor(lib: LibExecutor) {
+    this.#lib = lib;
+  }
+
+  get #prefix() {
+    return `libs/${this.#lib.name}/`;
+  }
+
+  #isHashed(file: string) {
+    const relative = file.slice(this.#prefix.length);
+    return !LibSource.unhashedDirs.includes(relative.split("/")[0] ?? "");
+  }
+
+  /** `package.json` cannot hash the stamp it carries, so the key comes off before hashing. */
+  async #hashableContent(file: string) {
+    const content = await this.#lib.workspace.readFile(file);
+    if (file !== `${this.#prefix}package.json`) return content;
+    const manifest = JSON.parse(content) as PackageJson;
+    delete manifest[LibSource.manifestKey];
+    return JSON.stringify(manifest);
+  }
+
+  /**
+   * Hash over the library's own files. Untracked files count: a freshly copied library is not committed
+   * yet, and its hash has to be the same one a later `status` recomputes.
+   */
+  async computeHash() {
+    const files = (await this.#lib.workspace.listGitFiles([`libs/${this.#lib.name}`], { untracked: true })).filter(
+      (file) => this.#isHashed(file),
+    );
+    const hasher = new Bun.CryptoHasher("sha256");
+    for (const file of files) {
+      hasher.update(file);
+      hasher.update("\0");
+      hasher.update(await this.#hashableContent(file));
+      hasher.update("\0");
+    }
+    return hasher.digest("hex").slice(0, 32);
+  }
+
+  async read(): Promise<LibSourceStamp | null> {
+    const manifest = await this.#lib.getPackageJson();
+    const akan = manifest[LibSource.manifestKey] as { source?: LibSourceStamp } | undefined;
+    return akan?.source ?? null;
+  }
+
+  async write({ origin, sha }: Pick<LibSourceStamp, "origin" | "sha">) {
+    const [manifest, hash] = await Promise.all([this.#lib.getPackageJson(), this.computeHash()]);
+    const akan = (manifest[LibSource.manifestKey] ?? {}) as Record<string, unknown>;
+    const stamp: LibSourceStamp = { origin, sha, hash, syncedAt: new Date().toISOString() };
+    await this.#lib.setPackageJson({ ...manifest, [LibSource.manifestKey]: { ...akan, source: stamp } });
+    return stamp;
+  }
+
+  /**
+   * Writes the stamp only when it would change. `syncedAt` moves on every write, so an unconditional
+   * write leaves the manifest dirty and defeats an idempotent caller — the hash is computed with the
+   * stamp removed, so comparing it first is sound.
+   */
+  async syncStamp({ origin, sha }: Pick<LibSourceStamp, "origin" | "sha">) {
+    const [current, hash] = await Promise.all([this.read(), this.computeHash()]);
+    if (current?.origin === origin && current.sha === sha && current.hash === hash)
+      return { stamp: current, changed: false };
+    return { stamp: await this.write({ origin, sha }), changed: true };
+  }
+
+  async status(): Promise<LibStatus> {
+    const [stamp, hash] = await Promise.all([this.read(), this.computeHash()]);
+    const drift = !stamp ? "unstamped" : stamp.hash === hash ? "clean" : "drifted";
+    return { lib: this.#lib.name, drift, stamp, hash };
+  }
+}
+
+export function formatLibStatuses(statuses: LibStatus[]) {
+  const marks = { clean: "clean    ", drifted: "DRIFTED  ", unstamped: "unstamped" } as const;
+  const sections = [
+    "Akan Library Source Status",
+    "",
+    ...statuses.map((status) => {
+      const origin = status.stamp ? `${status.stamp.origin}@${status.stamp.sha}` : "no akan.source in package.json";
+      return `  ${marks[status.drift]} libs/${status.lib}  ${origin}`;
+    }),
+    "",
+    `drifted: ${statuses.filter((status) => status.drift === "drifted").length} / ${statuses.length}`,
+  ];
+  return sections.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.76",
+  "version": "3.0.0-alpha.78",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -45,7 +45,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.76",
+    "akanjs": "3.0.0-alpha.78",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/semver.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { compareSemver } from "./semver";
+
+describe("compareSemver", () => {
+  test("orders plain versions", () => {
+    expect(compareSemver("1.4.0", "1.3.13")).toBe(1);
+    expect(compareSemver("1.3.13", "1.4.0")).toBe(-1);
+    expect(compareSemver("19.2.7", "19.2.7")).toBe(0);
+  });
+
+  test("compares the version behind a range operator, not the range", () => {
+    expect(compareSemver("^3.1049.0", "^3.721.0")).toBe(1);
+    expect(compareSemver("~1.2.0", "^1.10.0")).toBe(-1);
+    expect(compareSemver(">=1.3.13", "1.4.0")).toBe(-1);
+  });
+
+  test("sorts a prerelease below its release", () => {
+    expect(compareSemver("1.0.0-alpha", "1.0.0")).toBe(-1);
+    expect(compareSemver("0.0.0-experimental-603e6108-20241029", "0.0.0")).toBe(-1);
+  });
+
+  test("falls back to numeric comparison for specs that are not versions", () => {
+    expect(compareSemver("workspace:*", "0.0.0")).toBe(0);
+    expect(compareSemver("workspace:*", "1.0.0")).toBe(-1);
+  });
+});

package/semver.ts

@@ -0,0 +1,31 @@
+// `Bun.semver.order` compares range strings loosely — `^3.1049.0` vs `^3.721.0` answers 0 — so the
+// operator prefix has to come off before it sees the version.
+const stripRangeOperator = (version: string) => version.replace(/^[\s^~>=<v]+/, "").trim();
+
+const parseVersion = (version: string): number[] => {
+  return version
+    .replace(/^[^\d]*/, "")
+    .split(/[.-]/)
+    .map((part) => Number.parseInt(part, 10))
+    .map((part) => (Number.isFinite(part) ? part : 0));
+};
+
+const compareNumeric = (a: string, b: string): number => {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  const length = Math.max(left.length, right.length);
+  for (let i = 0; i < length; i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+};
+
+export const compareSemver = (a: string, b: string): number => {
+  try {
+    return Bun.semver.order(stripRangeOperator(a), stripRangeOperator(b));
+  } catch {
+    // Not every dependency spec is a version — `workspace:*`, a git URL, a tarball path.
+    return compareNumeric(a, b);
+  }
+};

package/slicePlanner.test.ts

@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { AppExecutor, Executor, WorkspaceExecutor } from "./executors";
+import { formatSlicePlan, SlicePlanner } from "./slicePlanner";
+import type { PackageJson } from "./types";
+
+const tempRoots: string[] = [];
+const originalEnv = { ...process.env };
+
+beforeEach(() => {
+  process.env = { ...originalEnv };
+  process.env.AKAN_PUBLIC_REPO_NAME = "hub";
+  process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+  process.env.AKAN_PUBLIC_ENV = "local";
+});
+
+afterEach(async () => {
+  process.env = { ...originalEnv };
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+const write = async (filePath: string, content: string) => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content);
+};
+
+const gitignore = [
+  "node_modules",
+  "apps/*/lib/cnst.ts",
+  "libs/*/common/index.ts",
+  "**/env.server.local.ts",
+  "**/akan.app.json",
+].join("\n");
+
+// `AppExecutor.from` and `AppInfo.fromExecutor` both memoise by name, so each fixture needs a fresh one.
+const makeWorkspace = async (appName: string, libName: string) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-slice-"));
+  tempRoots.push(root);
+  const rootPackageJson: PackageJson = {
+    name: "hub",
+    version: "0.0.1",
+    description: "hub",
+    workspaces: ["pkgs/*"],
+    dependencies: { lodash: "4.0.0", "unused-dep": "1.0.0" },
+    devDependencies: { typescript: "6.0.0" },
+  };
+  await write(path.join(root, "package.json"), `${JSON.stringify(rootPackageJson, null, 2)}\n`);
+  await write(path.join(root, ".gitignore"), `${gitignore}\n`);
+  await write(path.join(root, "biome.json"), "{}\n");
+
+  await write(path.join(root, `apps/${appName}/akan.config.ts`), "export default {};\n");
+  await write(path.join(root, `apps/${appName}/tsconfig.json`), "{}\n");
+  await write(
+    path.join(root, `apps/${appName}/lib/task/task.constant.ts`),
+    [
+      `import { helper } from "@libs/${libName}/common";`,
+      'import lodash from "lodash";',
+      "",
+      "export { helper, lodash };",
+      "",
+    ].join("\n"),
+  );
+  await write(path.join(root, `apps/${appName}/lib/cnst.ts`), "export {};\n");
+  await write(path.join(root, `apps/${appName}/env/env.server.local.ts`), "export const env = {};\n");
+
+  await write(path.join(root, `libs/${libName}/akan.config.ts`), "export default {};\n");
+  await write(path.join(root, `libs/${libName}/tsconfig.json`), "{}\n");
+  await mkdir(path.join(root, `libs/${libName}/lib`), { recursive: true });
+  await write(path.join(root, `libs/${libName}/common/helper.ts`), "export const helper = 1;\n");
+  await write(path.join(root, `libs/${libName}/common/index.ts`), 'export * from "./helper";\n');
+
+  await write(path.join(root, "pkgs/in-tree/package.json"), '{ "name": "in-tree" }\n');
+
+  const git = new Executor("fixture", root);
+  await git.spawn("git", ["init", "--quiet"]);
+  await git.spawn("git", ["add", "-A"]);
+  await git.spawn("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "--quiet", "-m", "fixture"]);
+
+  const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: `hub-${appName}` });
+  return { root, plan: async () => await new SlicePlanner(AppExecutor.from(workspace, appName)).plan() };
+};
+
+describe("SlicePlanner", () => {
+  test("resolves the lib closure and lists only git-tracked slice files", async () => {
+    const { plan } = await makeWorkspace("slice-app", "slice-lib");
+    const result = await plan();
+
+    expect(result.app).toBe("slice-app");
+    expect(result.libs).toEqual(["slice-lib"]);
+    expect(result.appFiles).toContain("apps/slice-app/lib/task/task.constant.ts");
+    expect(result.libFiles["slice-lib"]).toContain("libs/slice-lib/common/helper.ts");
+  });
+
+  test("leaves out generated barrels, env values and every other workspace member", async () => {
+    const { plan } = await makeWorkspace("ignore-app", "ignore-lib");
+    const result = await plan();
+
+    expect(result.appFiles).not.toContain("apps/ignore-app/lib/cnst.ts");
+    expect(result.appFiles).not.toContain("apps/ignore-app/env/env.server.local.ts");
+    expect(result.libFiles["ignore-lib"]).not.toContain("libs/ignore-lib/common/index.ts");
+    expect(result.rootFiles).toEqual(expect.arrayContaining(["package.json", ".gitignore", "biome.json"]));
+    expect(result.rootFiles.filter((file) => file.startsWith("pkgs/"))).toEqual([]);
+    expect(result.rootFiles.filter((file) => /^(apps|libs)\//.test(file))).toEqual([]);
+  });
+
+  test("drops `workspaces` from the slice manifest and reports it", async () => {
+    const { plan } = await makeWorkspace("manifest-app", "manifest-lib");
+    const result = await plan();
+
+    expect(result.packageJson.workspaces).toBeUndefined();
+    expect(result.packageJson.dependencies).toEqual({ lodash: "4.0.0", "unused-dep": "1.0.0" });
+    expect(result.warnings.join("\n")).toContain("workspaces");
+  });
+
+  test("reports unused root dependencies without pruning the toolchain", async () => {
+    const { plan } = await makeWorkspace("deps-app", "deps-lib");
+    const result = await plan();
+
+    expect(result.unusedDependencies).toContain("unused-dep");
+    expect(result.unusedDependencies).not.toContain("typescript");
+  });
+
+  test("warns about untracked files under the slice paths", async () => {
+    const { root, plan } = await makeWorkspace("untracked-app", "untracked-lib");
+    await write(path.join(root, "apps/untracked-app/lib/task/task.service.ts"), "export {};\n");
+    const result = await plan();
+
+    expect(result.warnings.join("\n")).toContain("apps/untracked-app/lib/task/task.service.ts");
+  });
+});
+
+describe("formatSlicePlan", () => {
+  test("collapses the workspace shell to its top-level entries", () => {
+    const text = formatSlicePlan({
+      app: "demo",
+      libs: ["util"],
+      appFiles: ["apps/demo/main.ts"],
+      libFiles: { util: ["libs/util/index.ts"] },
+      rootFiles: ["package.json", "infra/app/values/main.yaml", "infra/app/templates/app.yaml"],
+      packageJson: { name: "demo", version: "0.0.1", description: "demo" },
+      unusedDependencies: [],
+      warnings: [],
+    });
+
+    expect(text).toContain("app: demo (apps/demo: 1 files)");
+    expect(text).toContain("3 files across infra, package.json");
+    expect(text).toContain("(none)");
+  });
+});

package/slicePlanner.ts

@@ -0,0 +1,157 @@
+import type { AppExecutor } from "./executors";
+import { AppInfo } from "./scanInfo";
+import type { PackageJson } from "./types";
+
+export interface SlicePlan {
+  app: string;
+  /** Transitive lib closure, in mount order. */
+  libs: string[];
+  appFiles: string[];
+  libFiles: Record<string, string[]>;
+  rootFiles: string[];
+  /** Root manifest for a workspace holding only this slice. */
+  packageJson: PackageJson;
+  /** Root dependencies nothing in the slice imports — prune candidates for a human, never pruned here. */
+  unusedDependencies: string[];
+  warnings: string[];
+}
+
+/**
+ * The exact file set a single app needs to live in a workspace of its own: the app, its transitive lib
+ * closure, the workspace shell around them, and a root manifest for the result.
+ *
+ * Consumed by `akan plan-slice`, and by anything that moves an app or a lib between workspaces.
+ */
+export class SlicePlanner {
+  /** Root entries owned by an app, a lib or an in-tree package rather than by the workspace shell. */
+  static readonly memberDirs = ["apps", "libs", "pkgs"];
+  /** Never reported unused: the toolchain a workspace needs whether or not app code imports it. */
+  static readonly toolchainDependencies = [
+    "@akanjs/cli",
+    "@akanjs/devkit",
+    "@biomejs/biome",
+    "@types/bun",
+    "akanjs",
+    "typescript",
+  ];
+
+  #app: AppExecutor;
+  constructor(app: AppExecutor) {
+    this.#app = app;
+  }
+
+  async #trackedFiles(paths: string[]) {
+    return await this.#app.workspace.listGitFiles(paths);
+  }
+
+  async #untrackedFiles(paths: string[]) {
+    const [tracked, all] = await Promise.all([
+      this.#app.workspace.listGitFiles(paths),
+      this.#app.workspace.listGitFiles(paths, { untracked: true }),
+    ]);
+    const trackedSet = new Set(tracked);
+    return all.filter((file) => !trackedSet.has(file));
+  }
+
+  #isMemberFile(file: string) {
+    return SlicePlanner.memberDirs.includes(file.split("/")[0] ?? "");
+  }
+
+  static #requiredDependencies(appInfo: AppInfo) {
+    const scanResults = [
+      appInfo.getScanResult(),
+      ...[...appInfo.getLibInfos().values()].map((lib) => lib.getScanResult()),
+    ];
+    return new Set([
+      ...SlicePlanner.toolchainDependencies,
+      ...scanResults.flatMap((scanResult) => [
+        ...scanResult.dependencies,
+        ...scanResult.devDependencies,
+        ...scanResult.pkgDeps,
+      ]),
+    ]);
+  }
+
+  async #patchWarnings(packageJson: PackageJson) {
+    const patchedDependencies = (packageJson.patchedDependencies ?? {}) as Record<string, string>;
+    const missing = (
+      await Promise.all(
+        Object.entries(patchedDependencies).map(async ([spec, patchPath]) =>
+          (await this.#app.workspace.exists(patchPath)) ? null : `${spec} -> ${patchPath}`,
+        ),
+      )
+    ).filter((entry): entry is string => !!entry);
+    return missing.length ? [`patchedDependencies references a missing patch file: ${missing.join(", ")}`] : [];
+  }
+
+  async plan(): Promise<SlicePlan> {
+    const appInfo = await AppInfo.fromExecutor(this.#app);
+    const libs = appInfo.getLibs();
+    const slicePaths = [`apps/${this.#app.name}`, ...libs.map((lib) => `libs/${lib}`)];
+
+    const [appFiles, allTracked, untracked, rootPackageJson] = await Promise.all([
+      this.#trackedFiles([`apps/${this.#app.name}`]),
+      this.#trackedFiles(["."]),
+      this.#untrackedFiles(slicePaths),
+      this.#app.workspace.getPackageJson(),
+    ]);
+
+    const libFiles = Object.fromEntries(
+      await Promise.all(libs.map(async (lib) => [lib, await this.#trackedFiles([`libs/${lib}`])] as const)),
+    );
+    const rootFiles = allTracked.filter((file) => !this.#isMemberFile(file));
+
+    const required = SlicePlanner.#requiredDependencies(appInfo);
+    const rootDependencies = { ...rootPackageJson.dependencies, ...rootPackageJson.devDependencies };
+    const unusedDependencies = Object.keys(rootDependencies)
+      .filter((dep) => !required.has(dep))
+      .sort();
+
+    //* `workspaces` names in-tree packages, and a slice never carries `pkgs/` — it consumes akanjs from
+    //* the registry. Dependencies are copied whole rather than pruned: the root of a hub is a superset of
+    //* every slice, so carrying it always installs, while a wrong prune produces a repo that does not.
+    const { workspaces: _workspaces, ...slicePackageJson } = rootPackageJson;
+
+    const warnings = [
+      ...(untracked.length
+        ? [`${untracked.length} untracked file(s) under the slice paths: ${untracked.join(", ")}`]
+        : []),
+      ...(rootPackageJson.workspaces ? ["root `workspaces` dropped — a slice consumes akanjs from the registry"] : []),
+      ...(await this.#patchWarnings(rootPackageJson)),
+    ];
+
+    return {
+      app: this.#app.name,
+      libs,
+      appFiles,
+      libFiles,
+      rootFiles,
+      packageJson: slicePackageJson as PackageJson,
+      unusedDependencies,
+      warnings,
+    };
+  }
+}
+
+/** Top-level entry each path sits under, so a long tree (`infra/**`) reads as one line. */
+const rootEntriesOf = (rootFiles: string[]) => [...new Set(rootFiles.map((file) => file.split("/")[0] ?? file))].sort();
+
+export function formatSlicePlan(plan: SlicePlan) {
+  const libCounts = Object.entries(plan.libFiles).map(([lib, files]) => `  - libs/${lib}: ${files.length} files`);
+  const sections = [
+    "Akan Slice Plan",
+    `app: ${plan.app} (apps/${plan.app}: ${plan.appFiles.length} files)`,
+    `libs: ${plan.libs.length ? plan.libs.join(", ") : "(none)"}`,
+    ...libCounts,
+    `workspace shell: ${plan.rootFiles.length} files across ${rootEntriesOf(plan.rootFiles).join(", ")}`,
+    "",
+    `Unused root dependencies (${plan.unusedDependencies.length}) — prune candidates, not pruned:`,
+    "",
+    ...(plan.unusedDependencies.length ? plan.unusedDependencies.map((dep) => `  - ${dep}`) : ["  (none)"]),
+    "",
+    `Warnings (${plan.warnings.length}):`,
+    "",
+    ...(plan.warnings.length ? plan.warnings.map((warning) => `  - ${warning}`) : ["  (none)"]),
+  ];
+  return sections.join("\n");
+}