@akanjs/devkit 3.0.0-alpha.71 → 3.0.0-alpha.72

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."]);
+  });
+});

package/transforms/barrelImportsPlugin.ts

@@ -223,7 +223,7 @@ const resolveNodePackageExport = async (workspaceRoot: string, specifier: string
     const subpath = specifier === packageName ? "." : `.${specifier.slice(packageName.length)}`;
     const exported = resolvePackageExport(pkgJson.exports, subpath);
     const rel = exported ?? (subpath === "." ? (pkgJson.module ?? pkgJson.main ?? "index.js") : null);
-    if (!rel || !rel.startsWith(".")) return null;
+    if (!rel?.startsWith(".")) return null;
     const entryFile = await resolveFileCandidate(path.resolve(pkgDir, rel));
     if (!entryFile) return null;
     const pkgEntryName = specifier;

package/transforms/transforms.test.ts

@@ -104,7 +104,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
           ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],
           ["Bee", { subpath: "@scope/pkg/leaf", originalName: "B" }],
         ]),
-    } as BarrelAnalyzer;
+    } as unknown as BarrelAnalyzer;
 
     const rewritten = await rewriteBarrelImports(
       'import DefaultExport, { A, Bee as LocalBee, type Shape, Missing } from "@scope/pkg";\nconsole.log(A);',
@@ -128,7 +128,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
   test("preserves generated client barrel side effects when flattening app client imports", async () => {
     const analyzer = {
       analyze: async () => new Map([["st", { subpath: "@apps/demo/lib/st", originalName: "st" }]]),
-    } as BarrelAnalyzer;
+    } as unknown as BarrelAnalyzer;
 
     const rewritten = await rewriteBarrelImports(
       'import { st } from "@apps/demo/client";\nvoid st;\n',
@@ -144,7 +144,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
   test("does not rewrite import-looking code inside template literals", async () => {
     const analyzer = {
       analyze: async () => new Map([["AkanApp", { subpath: "akanjs/server/akanApp", originalName: "AkanApp" }]]),
-    } as BarrelAnalyzer;
+    } as unknown as BarrelAnalyzer;
 
     const source = [
       'import { Code } from "@apps/docs/ui";',
@@ -170,7 +170,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
           ["AkanOption", { subpath: "akanjs/server/akanOption", originalName: "AkanOption" }],
           ["Try", { subpath: "akanjs/server/decorators", originalName: "Try" }],
         ]),
-    } as BarrelAnalyzer;
+    } as unknown as BarrelAnalyzer;
 
     const rewritten = await rewriteBarrelImports(
       'import { AkanOption, Try } from "akanjs/server";\nexport const option = new AkanOption();\n',
@@ -191,7 +191,7 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     const analyzer = {
       analyze: async () =>
         new Map([["BottomInset", { subpath: "akanjs/ui/Layout/BottomInset", originalName: "BottomInset" }]]),
-    } as BarrelAnalyzer;
+    } as unknown as BarrelAnalyzer;
 
     const rewritten = await rewriteBarrelImports('import { BottomInset } from "akanjs/ui";\n', ["akanjs/ui"], analyzer);
 

package/transforms/tsconfigPackageResolver.test.ts

@@ -0,0 +1,230 @@
+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 { createTsconfigPackageResolver } from "./barrelImportsPlugin";
+
+const tempRoots: string[] = [];
+
+const makeTempRoot = async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-resolver-"));
+  tempRoots.push(root);
+  return root;
+};
+
+const write = async (root: string, relPath: string, content = "export const value = 1;\n") => {
+  const filePath = path.join(root, relPath);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, content);
+  return filePath;
+};
+
+const resolverFor = async (root: string, paths: Record<string, string[]>) =>
+  await createTsconfigPackageResolver({
+    workspace: { workspaceRoot: root },
+    getTsConfig: async () => ({ compilerOptions: { paths } }),
+  } as never);
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("createTsconfigPackageResolver — exact tsconfig mapping", () => {
+  test("resolves a package barrel and keeps the specifier", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "libs/util/index.ts");
+    const resolve = await resolverFor(root, { "@libs/util": ["./libs/util/index.ts"] });
+
+    expect(await resolve("@libs/util")).toEqual({
+      pkgName: "@libs/util",
+      entryFile,
+      pkgDir: path.join(root, "libs/util"),
+    });
+  });
+
+  test("collapses a facet specifier to its parent package", async () => {
+    // `@libs/util/server` maps to the sibling file `libs/util/server.ts`, not to a package directory, so a
+    // leaf rewritten under the raw specifier would become `@libs/util/server/lib/sig` — a path that does
+    // not exist. The parent specifier is what the `@libs/*` wildcard can actually resolve.
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "libs/util/server.ts");
+    const resolve = await resolverFor(root, { "@libs/util/server": ["./libs/util/server.ts"] });
+
+    expect(await resolve("@libs/util/server")).toEqual({
+      pkgName: "@libs/util",
+      entryFile,
+      pkgDir: path.join(root, "libs/util"),
+    });
+  });
+
+  test("keeps the specifier when the entry file name does not match the facet", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "libs/util/clientEntry.ts");
+    const resolve = await resolverFor(root, { "@libs/util/client": ["./libs/util/clientEntry.ts"] });
+
+    expect(await resolve("@libs/util/client")).toEqual({
+      pkgName: "@libs/util/client",
+      entryFile,
+      pkgDir: path.join(root, "libs/util"),
+    });
+  });
+
+  test("returns null when the mapped file is missing", async () => {
+    const root = await makeTempRoot();
+    const resolve = await resolverFor(root, { "@libs/util": ["./libs/util/index.ts"] });
+    expect(await resolve("@libs/util")).toBeNull();
+  });
+
+  test("returns null for an empty mapping", async () => {
+    const root = await makeTempRoot();
+    await write(root, "libs/util/index.ts");
+    const resolve = await resolverFor(root, { "@libs/util": [""] });
+    expect(await resolve("@libs/util")).toBeNull();
+  });
+});
+
+describe("createTsconfigPackageResolver — wildcard tsconfig mapping", () => {
+  test("prefers the longer prefix", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "custom/ui/index.ts");
+    await write(root, "libs/util/ui/index.ts");
+    const resolve = await resolverFor(root, {
+      "@libs/*": ["./libs/*"],
+      "@libs/util/*": ["./custom/*"],
+    });
+
+    expect(await resolve("@libs/util/ui")).toEqual({
+      pkgName: "@libs/util/ui",
+      entryFile,
+      pkgDir: path.join(root, "custom/ui"),
+    });
+  });
+
+  test("collapses a sibling facet file to its parent package", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "apps/minimal/client.ts");
+    const resolve = await resolverFor(root, { "@apps/*": ["./apps/*"] });
+
+    expect(await resolve("@apps/minimal/client")).toEqual({
+      pkgName: "@apps/minimal",
+      entryFile,
+      pkgDir: path.join(root, "apps/minimal"),
+    });
+  });
+
+  test("resolves a directory barrel and keeps the specifier", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "apps/minimal/index.tsx");
+    const resolve = await resolverFor(root, { "@apps/*": ["./apps/*"] });
+
+    expect(await resolve("@apps/minimal")).toEqual({
+      pkgName: "@apps/minimal",
+      entryFile,
+      pkgDir: path.join(root, "apps/minimal"),
+    });
+  });
+
+  test("prefers a sibling facet file over a same-named directory barrel", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "apps/minimal/client.ts");
+    await write(root, "apps/minimal/client/index.ts");
+    const resolve = await resolverFor(root, { "@apps/*": ["./apps/*"] });
+
+    expect((await resolve("@apps/minimal/client"))?.entryFile).toBe(entryFile);
+  });
+
+  test("stops at the matched prefix instead of falling through to a shorter one", async () => {
+    // Falling through would resolve `@libs/util/ui` against `./libs/*`, silently loading an unrelated
+    // directory that happens to sit at the same subpath under a different root.
+    const root = await makeTempRoot();
+    await write(root, "libs/util/ui/index.ts");
+    const resolve = await resolverFor(root, {
+      "@libs/*": ["./libs/*"],
+      "@libs/util/*": ["./custom/*"],
+    });
+
+    expect(await resolve("@libs/util/ui")).toBeNull();
+  });
+
+  test("tries every replacement of a matched prefix", async () => {
+    const root = await makeTempRoot();
+    const entryFile = await write(root, "second/util/index.ts");
+    const resolve = await resolverFor(root, { "@libs/*": ["./first/*", "./second/*"] });
+
+    expect((await resolve("@libs/util"))?.entryFile).toBe(entryFile);
+  });
+});
+
+describe("createTsconfigPackageResolver — node_modules fallback", () => {
+  const writePackageJson = async (root: string, pkgName: string, pkgJson: unknown) =>
+    await write(root, `node_modules/${pkgName}/package.json`, JSON.stringify(pkgJson));
+
+  test("resolves an exports subpath and preserves the file path", async () => {
+    const root = await makeTempRoot();
+    await writePackageJson(root, "akanjs", { exports: { "./ui": { source: "./ui/index.ts" } } });
+    const entryFile = await write(root, "node_modules/akanjs/ui/index.ts");
+    const resolve = await resolverFor(root, {});
+
+    expect(await resolve("akanjs/ui")).toEqual({
+      pkgName: "akanjs/ui",
+      entryFile,
+      pkgDir: path.join(root, "node_modules/akanjs/ui"),
+      preserveFilePath: true,
+    });
+  });
+
+  test("resolves an exports wildcard subpath", async () => {
+    const root = await makeTempRoot();
+    await writePackageJson(root, "akanjs", { exports: { "./*": "./dist/*.js" } });
+    const entryFile = await write(root, "node_modules/akanjs/dist/signal.js");
+    const resolve = await resolverFor(root, {});
+
+    expect((await resolve("akanjs/signal"))?.entryFile).toBe(entryFile);
+  });
+
+  test("resolves a scoped package subpath", async () => {
+    // A scoped name is two path segments, so the package boundary cannot be found by splitting on the
+    // first slash. Kept vendor-neutral on purpose: `packageExports.test.ts` reads every
+    // `"@akanjs/devkit/<x>"` literal under this package as a subpath the monorepo imports.
+    const root = await makeTempRoot();
+    await writePackageJson(root, "@vendor/kit", { exports: { "./lint": "./lint/index.ts" } });
+    const entryFile = await write(root, "node_modules/@vendor/kit/lint/index.ts");
+    const resolve = await resolverFor(root, {});
+
+    expect((await resolve("@vendor/kit/lint"))?.entryFile).toBe(entryFile);
+  });
+
+  test("falls back to module/main when exports resolution declines the specifier", async () => {
+    // `main: "index.js"` has no leading `./`, which the exports resolver rejects — the last fallback
+    // resolves it against the package directory, and it is the one path that does not preserve the file.
+    const root = await makeTempRoot();
+    await writePackageJson(root, "plainpkg", { main: "index.js" });
+    const entryFile = await write(root, "node_modules/plainpkg/index.js");
+    const resolve = await resolverFor(root, {});
+
+    expect(await resolve("plainpkg")).toEqual({
+      pkgName: "plainpkg",
+      entryFile,
+      pkgDir: path.join(root, "node_modules/plainpkg"),
+    });
+  });
+
+  test("returns null when the package is not installed", async () => {
+    const root = await makeTempRoot();
+    expect(await resolverFor(root, {}).then((resolve) => resolve("missingpkg"))).toBeNull();
+  });
+
+  test("returns null when the package.json is unparseable", async () => {
+    const root = await makeTempRoot();
+    await write(root, "node_modules/brokenpkg/package.json", "{ not json");
+    const resolve = await resolverFor(root, {});
+    expect(await resolve("brokenpkg")).toBeNull();
+  });
+
+  test("returns null when the resolved entry file is missing", async () => {
+    const root = await makeTempRoot();
+    await writePackageJson(root, "ghostpkg", { module: "./dist/index.js" });
+    const resolve = await resolverFor(root, {});
+    expect(await resolve("ghostpkg")).toBeNull();
+  });
+});

package/tsconfig.json

@@ -32,6 +32,10 @@
   "files": [],
   "include": [
     "**/*.ts",
-    "**/*.tsx"
+    "**/*.tsx",
+    "../../akanjs/server/types/*.d.ts"
+  ],
+  "exclude": [
+    "lint/__fixtures__"
   ]
 }

package/typeChecker.ts

@@ -208,7 +208,7 @@ export class TypeChecker {
     try {
       const { diagnostics } = this.check(filePath);
       return diagnostics.length === 0;
-    } catch (error) {
+    } catch (_error) {
       return false;
     }
   }

package/types.ts

@@ -15,6 +15,7 @@ export interface PackageJson {
   bun?: {
     platform?: "node" | "browser" | "bun";
   };
+  publishConfig?: { access?: "public" | "restricted"; registry?: string; tag?: string };
   [key: string]: unknown;
 }
 

package/ui/ScrollList.tsx

@@ -83,14 +83,12 @@ export const ScrollList = ({ list, ...props }: ScrollListProps) => {
               <Text backgroundColor="green">scrolling... + {scrollPos}</Text>
             </>
           ) : (
-            <>
-              {renderLogs.map((log, index) => (
-                <>
-                  <Text key={index}>{log}</Text>
-                  <Newline />
-                </>
-              ))}
-            </>
+            renderLogs.map((log, index) => (
+              <>
+                <Text key={index}>{log}</Text>
+                <Newline />
+              </>
+            ))
           )}
         </Text>
       </Box>

package/uploadRelease.ts

@@ -1,4 +1,4 @@
-import { HttpClient, Logger } from "akanjs/common";
+import { Logger, RestClient } from "akanjs/common";
 
 import { Spinner } from "./spinner";
 
@@ -26,7 +26,7 @@ export const uploadRelease = async (
 ) => {
   const logger = new Logger("uploadRelease");
   const basePath = local ? "http://localhost:8282/backend" : "https://cloud.akanjs.com/backend";
-  const httpClient = new HttpClient(basePath);
+  const httpClient = new RestClient(basePath);
   const buildPath = `${workspaceRoot}/releases/builds/${appName}-release.tar.gz`;
   const appBuildPath = `${workspaceRoot}/releases/builds/${appName}-appBuild.zip`;
   const sourcePath = `${workspaceRoot}/releases/sources/${appName}-source.tar.gz`;