@akanjs/devkit 3.0.1 → 3.0.2

package/scanInfo.ts

@@ -10,7 +10,14 @@ import type {
 } from "./akanConfig";
 import { AkanAppConfig } from "./akanConfig";
 import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "./executors";
-import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles, rootEntryHintOf } from "./workspaceLayout";
+import {
+  barrelFacetDirs,
+  facetIndexShadowOf,
+  isAllowedLibFacetRootFile,
+  rootAllowedDirs,
+  rootAllowedFiles,
+  rootEntryHintOf,
+} from "./workspaceLayout";
 
 const scalarFileTypes = ["constant", "dictionary", "document", "template", "unit", "util", "view", "zone"] as const;
 type ScalarFileType = (typeof scalarFileTypes)[number];
@@ -74,6 +81,11 @@ async function assertScanConvention(exec: AppExecutor | LibExecutor, libRoot: {
   for (const dirname of dirs)
     if (!allowedRootDirs.has(dirname))
       addViolation(dirname, rootEntryHintOf(exec.type, dirname) ?? `unsupported ${exec.type} root folder`);
+  for (const facet of barrelFacetDirs)
+    for (const filename of await exec.readdir(facet)) {
+      const shadow = facetIndexShadowOf(`${facet}/${filename}`);
+      if (shadow) addViolation(path.join(facet, filename), shadow);
+    }
 
   //* A lib has no `getPageKeys`, so its own route files are validated here.
   if (exec.type === "lib")
@@ -275,7 +287,7 @@ class ScanInfo {
   }
 }
 
-const isAkanFrameworkDependency = (dep: string) => dep === "akanjs" || dep.startsWith("akanjs/");
+export const isAkanFrameworkDependency = (dep: string) => dep === "akanjs" || dep.startsWith("akanjs/");
 export class AppInfo extends ScanInfo {
   readonly type = "app";
   readonly exec: AppExecutor;

package/testHelpers.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach } from "bun:test";
+import { existsSync } from "node:fs";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -122,6 +123,22 @@ export const writeJson = async (filePath: string, value: object) => {
   await writeText(filePath, `${JSON.stringify(value, null, 2)}\n`);
 };
 
+const repoRoot = path.resolve(import.meta.dir, "../../..");
+const biomeBin = path.join(repoRoot, "node_modules", ".bin", process.platform === "win32" ? "biome.exe" : "biome");
+export const hasBiome = existsSync(biomeBin);
+
+//? Through stdin under a repo-relative name, so the repo's own Biome config and overrides judge content kept elsewhere.
+export const formatWithBiome = async (content: string, repoPath: string) => {
+  const proc = Bun.spawn([biomeBin, "check", "--write", `--stdin-file-path=${repoPath}`], {
+    cwd: repoRoot,
+    stdin: new Blob([content]),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [output] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+  return output;
+};
+
 const tsconfigJson = { compilerOptions: { target: "ESNext", paths: {} } };
 
 export const createTempApp = async (appName = "demo", parentDir?: string) => {

package/transforms/transforms.test.ts

@@ -230,6 +230,19 @@ describe("BarrelAnalyzer and rewriteBarrelImports", () => {
     expect(secondMap?.get("b2")).toEqual({ subpath: "second/b2", originalName: "b2" });
   });
 
+  test("an empty facet barrel maps no name, so an import from it is left as written", async () => {
+    const root = await makeTempRoot();
+    const pkgDir = path.join(root, "common");
+    await write(path.join(pkgDir, "index.ts"), "export {};\n");
+    const analyzer = new BarrelAnalyzer({
+      resolvePackage: async () => ({ pkgName: "@libs/util/common", entryFile: path.join(pkgDir, "index.ts"), pkgDir }),
+    });
+
+    expect(await analyzer.analyze("@libs/util/common")).toEqual(new Map());
+    const source = 'import { pad } from "@libs/util/common";\n';
+    expect(await rewriteBarrelImports(source, ["@libs/util/common"], analyzer)).toBeNull();
+  });
+
   test("rewrites flattenable named imports and preserves default, type, and unknown imports", async () => {
     const analyzer = fakeAnalyzer([
       ["A", { subpath: "@scope/pkg/leaf", originalName: "A" }],

package/tsconfig.json

@@ -1,17 +1,12 @@
 {
   "compilerOptions": {
-    "lib": [
-      "ESNext",
-      "DOM"
-    ],
+    "lib": ["ESNext", "DOM"],
     "target": "ESNext",
     "module": "esnext",
     "moduleDetection": "force",
     "jsx": "react-jsx",
     "allowJs": true,
-    "types": [
-      "bun"
-    ],
+    "types": ["bun"],
     "moduleResolution": "bundler",
     "allowImportingTsExtensions": true,
     "verbatimModuleSyntax": true,
@@ -30,12 +25,6 @@
   },
   "extends": "../../../tsconfig.json",
   "files": [],
-  "include": [
-    "**/*.ts",
-    "**/*.tsx",
-    "../../akanjs/server/types/*.d.ts"
-  ],
-  "exclude": [
-    "lint/__fixtures__"
-  ]
+  "include": ["**/*.ts", "**/*.tsx", "../../akanjs/server/types/*.d.ts"],
+  "exclude": ["lint/__fixtures__"]
 }

package/workspaceLayout.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, test } from "bun:test";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
 import {
   appRootAllowedDirs,
   appRootAllowedFiles,
+  facetIndexShadowOf,
   isAllowedLibFacetRootFile,
   isScannedRootEntry,
   libRootAllowedDirs,
@@ -34,7 +37,7 @@ describe("app root layout allowlist", () => {
   test("names what a Capacitor app kept in its root as a leftover, not an unknown entry", () => {
     for (const name of ["android", "ios", "mobile", "capacitor.config.ts", "capacitor.config.json"]) {
       expect(appRootAllowedFiles.has(name) || appRootAllowedDirs.has(name)).toBe(false);
-      expect(rootEntryHintOf("app", name)).toContain(".akan/native/<target>");
+      expect(rootEntryHintOf("app", name)).toContain("dist/native/<app>/<target>");
     }
     expect(rootEntryHintOf("app", "base")).toBeNull();
     expect(rootEntryHintOf("lib", "ios")).toBeNull();
@@ -78,6 +81,28 @@ describe("lib root layout allowlist", () => {
   });
 });
 
+describe("hand-written facet index", () => {
+  test("flags every index Bun resolves ahead of the generated barrel, at the root of each barrel facet", () => {
+    for (const facet of ["ui", "webkit", "srvkit", "common", "plugin"])
+      for (const filename of ["index.tsx", "index.jsx", "index.mts"])
+        expect(facetIndexShadowOf(`${facet}/${filename}`)).toContain(`shadows the generated ${facet}/index.ts`);
+    expect(facetIndexShadowOf("ui/index.tsx")).toContain("Delete it");
+  });
+
+  test("leaves the generated barrel, a folder namespace, and folders without a barrel alone", () => {
+    for (const relativePath of [
+      "ui/index.ts",
+      "ui/index.js",
+      "ui/Chat/index.tsx",
+      "ui/Chat/index_.tsx",
+      "page/index.tsx",
+      "lib/index.tsx",
+      "index.tsx",
+    ])
+      expect(facetIndexShadowOf(relativePath)).toBeNull();
+  });
+});
+
 describe("lib facet root allowlist", () => {
   test("admits the generated support facets and a root signal test", () => {
     expect(isAllowedLibFacetRootFile("cnst.ts")).toBe(true);
@@ -91,3 +116,55 @@ describe("lib facet root allowlist", () => {
     expect(isAllowedLibFacetRootFile("user.test.ts")).toBe(false);
   });
 });
+
+const templatesDir = path.join(import.meta.dir, "..", "cli", "templates");
+
+type TsConfig = { references?: { path: string }[] };
+
+const loadRootTemplate = async (dir: string): Promise<TsConfig> =>
+  JSON.parse(await Bun.file(path.join(templatesDir, dir, "tsconfig.json.template")).text());
+
+const templateDirsWithRootTsconfig = async (): Promise<string[]> => {
+  const entries = await readdir(templatesDir, { withFileTypes: true });
+  const dirs: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (await Bun.file(path.join(templatesDir, entry.name, "tsconfig.json.template")).exists()) dirs.push(entry.name);
+  }
+  return dirs.sort((a, b) => a.localeCompare(b));
+};
+
+describe("cli root tsconfig templates vs workspace scan allowlists", () => {
+  test("only the app and libRoot root templates may declare references", async () => {
+    const dirs = await templateDirsWithRootTsconfig();
+    for (const dir of ["app", "libRoot", "pkgRoot", "workspaceRoot"]) expect(dirs).toContain(dir);
+    for (const dir of dirs) {
+      const tsconfig = await loadRootTemplate(dir);
+      if (!tsconfig.references) continue;
+      expect(["app", "libRoot"], `${dir} template declares references`).toContain(dir);
+    }
+  });
+
+  test("app template references stay inside appRootAllowedFiles", async () => {
+    const tsconfig = await loadRootTemplate("app");
+    for (const reference of tsconfig.references ?? []) {
+      const filename = path.basename(reference.path);
+      expect(appRootAllowedFiles.has(filename), `app template references "${reference.path}"`).toBe(true);
+    }
+  });
+
+  test("libRoot template references stay inside libRootAllowedFiles", async () => {
+    const tsconfig = await loadRootTemplate("libRoot");
+    for (const reference of tsconfig.references ?? []) {
+      const filename = path.basename(reference.path);
+      expect(libRootAllowedFiles.has(filename), `libRoot template references "${reference.path}"`).toBe(true);
+    }
+  });
+
+  test("pkgRoot and workspaceRoot templates declare no references", async () => {
+    for (const dir of ["pkgRoot", "workspaceRoot"]) {
+      const tsconfig = await loadRootTemplate(dir);
+      expect(tsconfig.references, `${dir} template must not declare references`).toBeUndefined();
+    }
+  });
+});

package/workspaceLayout.ts

@@ -84,7 +84,24 @@ const libFacetRootTestPattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(
 export const isAllowedLibFacetRootFile = (filename: string) =>
   libFacetRootAllowedFiles.has(filename) || libFacetRootTestPattern.test(filename);
 
-//* What a Capacitor app kept in its root. The native runtime generates its projects under `.akan/native/<target>`, so
+export const barrelFacetDirs = ["ui", "webkit", "srvkit", "common", "plugin"] as const;
+
+//* Bun resolves a folder import to `index.tsx`, `index.jsx` or `index.mts` ahead of `index.ts`, and TypeScript to
+//* `index.ts` first, so one of these beside the generated barrel typechecks every name the barrel adds and serves none.
+const barrelShadowingIndexFiles = new Set(["index.tsx", "index.jsx", "index.mts"]);
+
+export const facetIndexShadowOf = (sysRelativePath: string) => {
+  const [facet, filename = "", ...nested] = sysRelativePath.split("/");
+  if (nested.length || !barrelShadowingIndexFiles.has(filename) || !barrelFacetDirs.some((dir) => dir === facet))
+    return null;
+  return (
+    `shadows the generated ${facet}/index.ts: Bun loads ${filename} and TypeScript checks index.ts, so a name only ` +
+    `the generated barrel exports typechecks and is undefined at runtime. Delete it, since the generated barrel ` +
+    `re-exports every file and folder in ${facet}/; a namespace it builds belongs in ${facet}/<Folder>/index.tsx`
+  );
+};
+
+//* What a Capacitor app kept in its root. The native runtime generates its projects under `dist/native/<app>/<target>`, so
 //* these are named as leftovers instead of as unknown entries.
 const retiredAppRootEntries = new Set([
   "android",
@@ -97,7 +114,7 @@ const retiredAppRootEntries = new Set([
 
 export const rootEntryHintOf = (type: SysType, name: string) =>
   type === "app" && retiredAppRootEntries.has(name)
-    ? "a Capacitor-era entry; the native runtime generates its projects under .akan/native/<target>, so delete it"
+    ? "a Capacitor-era entry; the native runtime generates its projects under dist/native/<app>/<target>, so delete it"
     : null;
 
 // scanSync reads roots through `Bun.Glob("*")`, which skips dotfiles, so doctor skips them the same way.