@akanjs/devkit 3.0.0-alpha.9 → 3.0.0-alpha.90

package/slicePlanner.ts

@@ -0,0 +1,235 @@
+import type { AppExecutor, WorkspaceExecutor } 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, with the dependencies it does not use pruned. */
+  packageJson: PackageJson;
+  /** 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[];
+}
+
+/**
+ * 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 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) {
+    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([
+      ...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 {
+      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)),
+    ];
+
+    return {
+      app: this.#app.name,
+      libs,
+      appFiles,
+      libFiles,
+      rootFiles,
+      packageJson,
+      requiredDependencies: [...required].sort(),
+      unusedDependencies: pruned,
+      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(", ")}`,
+    "",
+    `Root dependencies this slice does not use (${plan.unusedDependencies.length}) — 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");
+}

package/ssrScanner.test.ts

@@ -0,0 +1,301 @@
+import { describe, expect, test } from "bun:test";
+import ts from "typescript";
+import type { SourceFileInfo } from "./qualityScanner";
+import { formatSsrBalance, SSR_SERVER_SHARE_TARGET, SsrScanner } from "./ssrScanner";
+
+/**
+ * `SsrScanner` is a documented gate — `akan quality ssr` prints the server share and AGENTS.md names 50% as
+ * the floor — so both halves matter: a rule that stops firing lets the share rot, and a rule that
+ * over-reports is what makes developers stop reading the output. Every rule here gets a positive and the
+ * negative that must stay quiet.
+ */
+const fileOf = (file: string, content: string): SourceFileInfo => ({
+  file,
+  absolutePath: `/repo/${file}`,
+  content,
+  sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX),
+});
+
+const rulesOf = (...files: SourceFileInfo[]) => new SsrScanner().scan(files).warnings.map((warning) => warning.rule);
+
+const scanOne = (file: string, content: string) => rulesOf(fileOf(file, content));
+
+const UI = "apps/demo/ui/Thing.tsx";
+
+describe("akan.ssr.unnecessary-use-client", () => {
+  test("flags a directive with no client-only capability behind it", () => {
+    expect(scanOne(UI, `"use client";\nexport const Thing = () => <div />;\n`)).toContain(
+      "akan.ssr.unnecessary-use-client",
+    );
+  });
+
+  test("a hook, a handler, a store read and a browser global each justify the directive", () => {
+    const justified = [
+      `export const Thing = () => { const [open] = useState(false); return <div>{open}</div>; };`,
+      `export const Thing = () => <button onClick={save} />;`,
+      `export const Thing = () => <div>{st.use.task()}</div>;`,
+      `export const Thing = () => <div>{window.innerWidth}</div>;`,
+    ];
+    for (const body of justified)
+      expect(scanOne(UI, `"use client";\n${body}\n`)).not.toContain("akan.ssr.unnecessary-use-client");
+  });
+
+  test("a third-party import is a reason the AST cannot rule out", () => {
+    expect(scanOne(UI, `"use client";\nimport Chart from "recharts";\nexport const Thing = () => <div />;\n`)).toEqual(
+      [],
+    );
+  });
+
+  // `usePage`/`getSelf` read request-scoped server context, so they must not read as client evidence.
+  test("a server-safe call is not client evidence", () => {
+    expect(
+      scanOne(
+        UI,
+        `"use client";\nexport const Thing = () => { const { l } = usePage(); return <div>{l("a")}</div>; };\n`,
+      ),
+    ).toContain("akan.ssr.unnecessary-use-client");
+  });
+
+  test("importing st or fetch justifies the directive on its own", () => {
+    expect(
+      scanOne(UI, `"use client";\nimport { st } from "../lib/st";\nexport const Thing = () => <div />;\n`),
+    ).toEqual([]);
+  });
+
+  // Zone/Template/Util and the lazy() boundary carry the directive by role, not by accident.
+  test("every convention client file is exempt", () => {
+    const body = `"use client";\nexport const Card = () => <div />;\n`;
+    const exempt = [
+      "apps/demo/lib/task/Task.Zone.tsx",
+      "apps/demo/lib/task/Task.Template.tsx",
+      "apps/demo/lib/task/Task.Util.tsx",
+      "apps/demo/ui/Chart/index_.tsx",
+    ];
+    for (const file of exempt) expect(scanOne(file, body)).toEqual([]);
+  });
+
+  test("a Unit or View in the same module is not exempt", () => {
+    const body = `"use client";\nexport const Card = () => <div />;\n`;
+    expect(scanOne("apps/demo/lib/task/Task.Unit.tsx", body)).toContain("akan.ssr.unnecessary-use-client");
+    expect(scanOne("apps/demo/lib/task/Task.View.tsx", body)).toContain("akan.ssr.unnecessary-use-client");
+  });
+
+  test("a Zone outside a module folder is not exempt", () => {
+    expect(scanOne("apps/demo/ui/Task.Zone.tsx", `"use client";\nexport const Zone = () => <div />;\n`)).toContain(
+      "akan.ssr.unnecessary-use-client",
+    );
+  });
+
+  test("the directive has to be the first statement to count as one", () => {
+    expect(
+      scanOne(UI, `import { cn } from "akanjs/client";\n"use client";\nexport const Thing = () => <div />;\n`),
+    ).toEqual([]);
+  });
+});
+
+describe("akan.ssr.client-static-component", () => {
+  const four = "<div><span /><span /><span /></div>";
+
+  test("flags a static component once its subtree is worth moving", () => {
+    expect(
+      scanOne(UI, `"use client";\nimport { st } from "../lib/st";\nexport const Card = () => ${four};\n`),
+    ).toContain("akan.ssr.client-static-component");
+  });
+
+  test("stays quiet below the mass floor", () => {
+    expect(
+      scanOne(UI, `"use client";\nimport { st } from "../lib/st";\nexport const Card = () => <div><span /></div>;\n`),
+    ).toEqual([]);
+  });
+
+  test("a component with any client touch is not static", () => {
+    expect(
+      scanOne(UI, `"use client";\nexport const Card = () => <div onClick={save}><span /><span /><span /></div>;\n`),
+    ).not.toContain("akan.ssr.client-static-component");
+  });
+
+  // A vendor component's own tags may be client-only, so its subtree is not server-renderable markup.
+  test("a subtree rendering a vendor tag is exempt", () => {
+    expect(
+      scanOne(
+        UI,
+        `"use client";\nimport Chart from "recharts";\nexport const Card = () => <div><Chart /><span /><span /></div>;\n`,
+      ),
+    ).toEqual([]);
+  });
+
+  test("a lowercase binding is not a component", () => {
+    expect(scanOne(UI, `"use client";\nimport { st } from "../lib/st";\nexport const card = () => ${four};\n`)).toEqual(
+      [],
+    );
+  });
+});
+
+describe("akan.ssr.client-static-markup", () => {
+  const ten = `<div><p /><p /><p /><p /><p /><p /><p /><p /><button onClick={save} /></div>`;
+
+  test("flags a large subtree wrapping one interactive touch", () => {
+    expect(scanOne(UI, `"use client";\nexport const Panel = () => ${ten};\n`)).toContain(
+      "akan.ssr.client-static-markup",
+    );
+  });
+
+  test("stays quiet when the subtree is small enough that splitting buys nothing", () => {
+    expect(scanOne(UI, `"use client";\nexport const Panel = () => <div><button onClick={save} /></div>;\n`)).toEqual(
+      [],
+    );
+  });
+
+  test("stays quiet once the component is interactive throughout", () => {
+    const busy = `<div><button onClick={a} /><button onClick={b} /><button onClick={c} /><p /><p /><p /><p /><p /><p /></div>`;
+    expect(scanOne(UI, `"use client";\nexport const Panel = () => ${busy};\n`)).not.toContain(
+      "akan.ssr.client-static-markup",
+    );
+  });
+});
+
+describe("akan.ssr.client-mount-load", () => {
+  const mount = (body: string) =>
+    `"use client";\nexport const Thing = () => { useEffect(() => { ${body} }, []); return <div />; };\n`;
+
+  test("flags a fetch and a generated store load fired from a mount-only effect", () => {
+    expect(scanOne(UI, mount("void fetch.initTaskInOrg(orgId);"))).toContain("akan.ssr.client-mount-load");
+    expect(scanOne(UI, mount("void st.do.initTaskInOrg();"))).toContain("akan.ssr.client-mount-load");
+  });
+
+  test("useLayoutEffect is the same finding", () => {
+    const body = `"use client";\nexport const Thing = () => { useLayoutEffect(() => { void fetch.viewTask(id); }, []); return <div />; };\n`;
+    expect(scanOne(UI, body)).toContain("akan.ssr.client-mount-load");
+  });
+
+  // A reactive effect responds to client state and has no server-side equivalent.
+  test("a non-empty dependency array is not a mount load", () => {
+    const body = `"use client";\nexport const Thing = () => { useEffect(() => { void fetch.viewTask(id); }, [id]); return <div />; };\n`;
+    expect(scanOne(UI, body)).not.toContain("akan.ssr.client-mount-load");
+  });
+
+  test("a mount effect that loads nothing is not a finding", () => {
+    expect(scanOne(UI, mount("subscribe();"))).not.toContain("akan.ssr.client-mount-load");
+  });
+
+  test("a store action that is not a load is not a finding", () => {
+    expect(scanOne(UI, mount("void st.do.openModal();"))).not.toContain("akan.ssr.client-mount-load");
+  });
+});
+
+describe("akan.ssr.template-client-state", () => {
+  const template = "apps/demo/lib/task/Task.Template.tsx";
+
+  test("flags useState in a Template", () => {
+    const body = `"use client";\nexport const General = () => { const [draft, setDraft] = useState(""); return <input value={draft} />; };\n`;
+    expect(scanOne(template, body)).toContain("akan.ssr.template-client-state");
+  });
+
+  test("the same useState in a Zone is not a finding", () => {
+    const body = `"use client";\nexport const Card = () => { const [open, setOpen] = useState(false); return <div>{open}</div>; };\n`;
+    expect(scanOne("apps/demo/lib/task/Task.Zone.tsx", body)).not.toContain("akan.ssr.template-client-state");
+  });
+
+  test("a store-driven Template is clean", () => {
+    const body = `"use client";\nexport const General = () => <input value={st.use.taskForm().name} onChange={st.do.setNameOnTask} />;\n`;
+    expect(scanOne(template, body)).toEqual([]);
+  });
+});
+
+describe("akan.ssr.module-missing-server-view", () => {
+  const clientMass = `<div><p /><p /><p /><p /><p /><p /><p /><p /><p /><p /><p /></div>`;
+
+  test("flags a module that renders only from client files", () => {
+    const zone = fileOf(
+      "apps/demo/lib/task/Task.Zone.tsx",
+      `"use client";\nexport const Card = () => ${clientMass};\n`,
+    );
+    expect(rulesOf(zone)).toContain("akan.ssr.module-missing-server-view");
+  });
+
+  test("one Unit or View in the module answers it", () => {
+    const zone = fileOf(
+      "apps/demo/lib/task/Task.Zone.tsx",
+      `"use client";\nexport const Card = () => ${clientMass};\n`,
+    );
+    const unit = fileOf("apps/demo/lib/task/Task.Unit.tsx", `export const Card = () => <div />;\n`);
+    expect(rulesOf(zone, unit)).not.toContain("akan.ssr.module-missing-server-view");
+  });
+
+  test("a module too small to matter is not a finding", () => {
+    const zone = fileOf(
+      "apps/demo/lib/task/Task.Zone.tsx",
+      `"use client";\nexport const Card = () => <div><p /></div>;\n`,
+    );
+    expect(rulesOf(zone)).not.toContain("akan.ssr.module-missing-server-view");
+  });
+
+  // `lib/_<service>` folders are service modules, which own no model to render server-side.
+  test("a service module is not held to it", () => {
+    const zone = fileOf(
+      "apps/demo/lib/_upload/Upload.Zone.tsx",
+      `"use client";\nexport const Card = () => ${clientMass};\n`,
+    );
+    expect(rulesOf(zone)).not.toContain("akan.ssr.module-missing-server-view");
+  });
+});
+
+describe("scan scope", () => {
+  test("only apps/libs ui and lib .tsx files are measured", () => {
+    const outOfScope = [
+      "apps/demo/page/task/_index.tsx",
+      "apps/demo/webkit/useThing.tsx",
+      "apps/demo/ui/Thing.test.tsx",
+      "pkgs/akanjs/ui/Thing.tsx",
+      "apps/demo/ui/thing.ts",
+    ];
+    for (const file of outOfScope)
+      expect(new SsrScanner().scan([fileOf(file, `"use client";\nexport const Thing = () => <div />;\n`)])).toEqual({
+        warnings: [],
+        balance: [],
+      });
+  });
+});
+
+describe("balance", () => {
+  test("measures the share in JSX elements and not in files", () => {
+    const server = fileOf("apps/demo/ui/Server.tsx", `export const A = () => <div><p /><p /></div>;\n`);
+    const client = fileOf("apps/demo/ui/Client.tsx", `"use client";\nexport const B = () => <div onClick={a} />;\n`);
+    const [entry] = new SsrScanner().scan([server, client]).balance;
+    expect(entry).toEqual({ scope: "apps/demo", serverMass: 3, clientMass: 1, serverShare: 0.75 });
+  });
+
+  test("adds a workspace row only once a second scope exists", () => {
+    const demo = fileOf("apps/demo/ui/A.tsx", `export const A = () => <div />;\n`);
+    const shared = fileOf("libs/shared/ui/B.tsx", `"use client";\nexport const B = () => <div onClick={a} />;\n`);
+    expect(new SsrScanner().scan([demo]).balance.map((entry) => entry.scope)).toEqual(["apps/demo"]);
+    expect(new SsrScanner().scan([demo, shared]).balance.map((entry) => entry.scope)).toEqual([
+      "apps/demo",
+      "libs/shared",
+      "workspace",
+    ]);
+  });
+
+  // An empty scope reads as fully server-rendered rather than as a division by zero.
+  test("a scope with no JSX at all is 100% server", () => {
+    const empty = fileOf("apps/demo/ui/Empty.tsx", `export const value = 1;\n`);
+    expect(new SsrScanner().scan([empty]).balance[0].serverShare).toBe(1);
+  });
+});
+
+describe("formatSsrBalance", () => {
+  test("flags a scope under the target and leaves one above it unmarked", () => {
+    const lines = formatSsrBalance([
+      { scope: "apps/low", serverMass: 1, clientMass: 9, serverShare: 0.1 },
+      { scope: "apps/high", serverMass: 9, clientMass: 1, serverShare: 0.9 },
+    ]);
+    expect(lines[0]).toContain("10% server");
+    expect(lines[0]).toContain(`below the ${Math.round(SSR_SERVER_SHARE_TARGET * 100)}% target`);
+    expect(lines[1]).toContain("90% server");
+    expect(lines[1]).not.toContain("below the");
+  });
+
+  test("says so rather than printing an empty table", () => {
+    expect(formatSsrBalance([])).toEqual(["No component files found."]);
+  });
+});