@akanjs/devkit 3.0.0-alpha.80 → 3.0.0-alpha.82

package/libSource.test.ts

@@ -20,7 +20,10 @@ const write = async (filePath: string, content: string) => {
 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, "package.json"),
+    '{ "name": "workspace", "version": "0.0.1", "description": "workspace" }\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");
@@ -29,7 +32,7 @@ const makeLib = async (libName: string) => {
   const git = new Executor("fixture", root);
   await git.spawn("git", ["init", "--quiet"]);
 
-  const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: `hub-${libName}` });
+  const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: `workspace-${libName}` });
   const lib = LibExecutor.from(workspace, libName);
   return { root, lib, source: new LibSource(lib) };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.80",
+  "version": "3.0.0-alpha.82",
   "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.80",
+    "akanjs": "3.0.0-alpha.82",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/slicePlanner.test.ts

@@ -11,7 +11,7 @@ const originalEnv = { ...process.env };
 
 beforeEach(() => {
   process.env = { ...originalEnv };
-  process.env.AKAN_PUBLIC_REPO_NAME = "hub";
+  process.env.AKAN_PUBLIC_REPO_NAME = "workspace";
   process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
   process.env.AKAN_PUBLIC_ENV = "local";
 });
@@ -39,16 +39,27 @@ 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",
+    name: "workspace",
     version: "0.0.1",
-    description: "hub",
+    description: "workspace",
     workspaces: ["pkgs/*"],
-    dependencies: { lodash: "4.0.0", "unused-dep": "1.0.0" },
-    devDependencies: { typescript: "6.0.0" },
+    dependencies: { lodash: "4.0.0", "unused-dep": "1.0.0", ioredis: "5.0.0" },
+    devDependencies: { typescript: "6.0.0", "@types/lodash": "4.1.0", "@types/qrcode": "1.0.0" },
+    patchedDependencies: {
+      "lodash@4.0.0": "patches/lodash@4.0.0.patch",
+      "unused-dep@1.0.0": "patches/unused-dep@1.0.0.patch",
+    },
   };
   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");
+  //? The framework's peers are declared by akanjs, not by any import, so the planner reads them here.
+  await write(
+    path.join(root, "node_modules/akanjs/package.json"),
+    '{ "name": "akanjs", "version": "3.0.0", "peerDependencies": { "react": "19.0.0", "ioredis": "5.0.0" } }\n',
+  );
+  await write(path.join(root, "patches/lodash@4.0.0.patch"), "");
+  await write(path.join(root, "patches/unused-dep@1.0.0.patch"), "");
 
   await write(path.join(root, `apps/${appName}/akan.config.ts`), "export default {};\n");
   await write(path.join(root, `apps/${appName}/tsconfig.json`), "{}\n");
@@ -78,7 +89,7 @@ const makeWorkspace = async (appName: string, libName: string) => {
   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}` });
+  const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: `workspace-${appName}` });
   return { root, plan: async () => await new SlicePlanner(AppExecutor.from(workspace, appName)).plan() };
 };
 
@@ -110,16 +121,35 @@ describe("SlicePlanner", () => {
     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 () => {
+  test("prunes what the slice does not import, keeping the toolchain and the type packages", 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");
+    expect(result.requiredDependencies).toContain("lodash");
+    //? `ioredis` is an akanjs peer: nothing imports it, and pruning it would break the server at runtime.
+    expect(result.packageJson.dependencies).toEqual({ lodash: "4.0.0", ioredis: "5.0.0" });
+    //? Nothing imports `@types/lodash` by name, so only its companion keeps it.
+    expect(result.packageJson.devDependencies).toEqual({ typescript: "6.0.0", "@types/lodash": "4.1.0" });
+    expect(result.packageJson.patchedDependencies).toEqual({ "lodash@4.0.0": "patches/lodash@4.0.0.patch" });
+    expect(result.unusedDependencies).toEqual(["@types/qrcode", "unused-dep"]);
+  });
+
+  test("carries the dependencies whole when there is no akanjs manifest to read the peers from", async () => {
+    const { root, plan } = await makeWorkspace("nopeer-app", "nopeer-lib");
+    await rm(path.join(root, "node_modules"), { recursive: true, force: true });
+    const result = await plan();
+
+    expect(result.unusedDependencies).toEqual([]);
+    expect(result.packageJson.dependencies).toEqual({ lodash: "4.0.0", "unused-dep": "1.0.0", ioredis: "5.0.0" });
+    expect(result.warnings.join("\n")).toContain("carried whole");
+  });
+
+  test("names a type package the way DefinitelyTyped does", () => {
+    expect(SlicePlanner.typesPackageOf("lodash")).toBe("@types/lodash");
+    expect(SlicePlanner.typesPackageOf("@capacitor/core")).toBe("@types/capacitor__core");
   });
 
   test("warns about untracked files under the slice paths", async () => {
@@ -140,6 +170,7 @@ describe("formatSlicePlan", () => {
       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" },
+      requiredDependencies: [],
       unusedDependencies: [],
       warnings: [],
     });

package/slicePlanner.ts

@@ -1,4 +1,4 @@
-import type { AppExecutor } from "./executors";
+import type { AppExecutor, WorkspaceExecutor } from "./executors";
 import { AppInfo } from "./scanInfo";
 import type { PackageJson } from "./types";
 
@@ -9,9 +9,11 @@ export interface SlicePlan {
   appFiles: string[];
   libFiles: Record<string, string[]>;
   rootFiles: string[];
-  /** Root manifest for a workspace holding only this slice. */
+  /** Root manifest for a workspace holding only this slice, with the dependencies it does not use pruned. */
   packageJson: PackageJson;
-  /** Root dependencies nothing in the slice imports — prune candidates for a human, never pruned here. */
+  /** What this slice imports, so a caller serving several apps can union them before pruning. */
+  requiredDependencies: string[];
+  /** Root dependencies nothing in the slice imports — left out of `packageJson`. */
   unusedDependencies: string[];
   warnings: string[];
 }
@@ -25,15 +27,94 @@ export interface SlicePlan {
 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. */
+  /** Never pruned: the toolchain a workspace runs on, which no source file imports. */
   static readonly toolchainDependencies = [
     "@akanjs/cli",
     "@akanjs/devkit",
     "@biomejs/biome",
     "@types/bun",
     "akanjs",
+    "tailwindcss",
     "typescript",
   ];
+  static readonly akanPackages = ["akanjs", "@akanjs/devkit", "@akanjs/cli"];
+
+  /**
+   * What the framework imports but does not install, so a workspace root has to declare it: `react`,
+   * `scheduler` and the RSC runtime, but also `ioredis`, `postgres` and `bullmq` the moment an app uses
+   * a database or a queue. No source file in the workspace names any of them, so no scan can find them
+   * — they are the akan packages' own `peerDependencies`, read wherever those are installed. Anything
+   * they declare as a plain dependency is installed with them and needs no root entry.
+   */
+  static async #frameworkPeers(workspace: WorkspaceExecutor) {
+    const peers = new Set<string>();
+    let found = false;
+    for (const akanPackage of SlicePlanner.akanPackages) {
+      for (const prefix of ["node_modules", "pkgs"]) {
+        const manifestPath = `${prefix}/${akanPackage}/package.json`;
+        if (!(await workspace.exists(manifestPath))) continue;
+        const manifest = (await workspace.readJson(manifestPath)) as PackageJson;
+        for (const peer of Object.keys(manifest.peerDependencies ?? {})) peers.add(peer);
+        found = true;
+        break;
+      }
+    }
+    return found ? peers : null;
+  }
+
+  /** DefinitelyTyped's name for a package: `lodash` -> `@types/lodash`, `@scope/x` -> `@types/scope__x`. */
+  static typesPackageOf(dependency: string) {
+    return dependency.startsWith("@") ? `@types/${dependency.slice(1).replace("/", "__")}` : `@types/${dependency}`;
+  }
+
+  /**
+   * The root manifest a workspace holding only these dependencies would carry, with the workspace's own
+   * version specs kept — that is what makes one branch resolve to one dependency tree everywhere.
+   *
+   * A `@types/x` package is kept alongside `x`: nothing imports it by name, so no scan can see it, and
+   * dropping it breaks the typecheck of every file that imports `x`. `workspaces` is dropped because it
+   * names in-tree packages, which a slice never carries — it consumes akanjs from the registry.
+   */
+  static async pruneDependencies(
+    workspace: WorkspaceExecutor,
+    rootPackageJson: PackageJson,
+    required: Iterable<string>,
+  ) {
+    const peers = await SlicePlanner.#frameworkPeers(workspace);
+    const { workspaces: _workspaces, ...rest } = rootPackageJson;
+    //* Without akanjs's peer list every peer looks unused, and pruning it produces an install that
+    //* succeeds and a server that fails at its first redis or postgres call. Carry the dependencies
+    //* whole instead and say why.
+    if (!peers)
+      return {
+        packageJson: rest as PackageJson,
+        pruned: [],
+        warnings: [`dependencies carried whole — none of ${SlicePlanner.akanPackages.join(", ")} is installed`],
+      };
+    const keep = new Set([...SlicePlanner.toolchainDependencies, ...peers, ...required]);
+    for (const dependency of [...keep]) keep.add(SlicePlanner.typesPackageOf(dependency));
+    const pick = (entries: Record<string, string> | undefined) =>
+      Object.fromEntries(Object.entries(entries ?? {}).filter(([name]) => keep.has(name)));
+    const patched = (rootPackageJson.patchedDependencies ?? {}) as Record<string, string>;
+    const packageJson = {
+      ...rest,
+      dependencies: pick(rootPackageJson.dependencies),
+      devDependencies: pick(rootPackageJson.devDependencies),
+      //? A key here is `name@version`, and bun fails the install when a patch names a package the
+      //? manifest no longer asks for.
+      ...(Object.keys(patched).length
+        ? {
+            patchedDependencies: Object.fromEntries(
+              Object.entries(patched).filter(([spec]) => keep.has(spec.slice(0, spec.lastIndexOf("@")))),
+            ),
+          }
+        : {}),
+    } as PackageJson;
+    const pruned = Object.keys({ ...rootPackageJson.dependencies, ...rootPackageJson.devDependencies })
+      .filter((name) => !keep.has(name))
+      .sort();
+    return { packageJson, pruned, warnings: [] as string[] };
+  }
 
   #app: AppExecutor;
   constructor(app: AppExecutor) {
@@ -63,7 +144,6 @@ export class SlicePlanner {
       ...[...appInfo.getLibInfos().values()].map((lib) => lib.getScanResult()),
     ];
     return new Set([
-      ...SlicePlanner.toolchainDependencies,
       ...scanResults.flatMap((scanResult) => [
         ...scanResult.dependencies,
         ...scanResult.devDependencies,
@@ -102,21 +182,18 @@ export class SlicePlanner {
     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 {
+      packageJson,
+      pruned,
+      warnings: manifestWarnings,
+    } = await SlicePlanner.pruneDependencies(this.#app.workspace, rootPackageJson, required);
 
     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"] : []),
+      ...manifestWarnings,
       ...(await this.#patchWarnings(rootPackageJson)),
     ];
 
@@ -126,8 +203,9 @@ export class SlicePlanner {
       appFiles,
       libFiles,
       rootFiles,
-      packageJson: slicePackageJson as PackageJson,
-      unusedDependencies,
+      packageJson,
+      requiredDependencies: [...required].sort(),
+      unusedDependencies: pruned,
       warnings,
     };
   }
@@ -145,7 +223,7 @@ export function formatSlicePlan(plan: SlicePlan) {
     ...libCounts,
     `workspace shell: ${plan.rootFiles.length} files across ${rootEntriesOf(plan.rootFiles).join(", ")}`,
     "",
-    `Unused root dependencies (${plan.unusedDependencies.length}) — prune candidates, not pruned:`,
+    `Root dependencies this slice does not use (${plan.unusedDependencies.length}) — pruned:`,
     "",
     ...(plan.unusedDependencies.length ? plan.unusedDependencies.map((dep) => `  - ${dep}`) : ["  (none)"]),
     "",