@akanjs/devkit 3.0.0-alpha.1 → 3.0.0-alpha.10

package/lint/no-return-in-store-action.grit

@@ -0,0 +1,35 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Every prototype method of a `store(...)` class is registered as an action
+// (StoreRegistry.register) and reaches callers only as `st.do.<action>`, which re-wraps it
+// (StoreInstance.#extendAccessors) and is typed void by `VoidActions` in
+// pkgs/akanjs/store/types.ts. A returned value is therefore unreachable from every call
+// site — it reads like a contract while being dead code. Write the result into state with
+// `this.set({ ... })` instead.
+//
+// Deliberately not flagged, because none of these are actions: a bare `return;` guard, a
+// `return` belonging to a nested callback, a getter, a `static` helper, and a class-property
+// arrow (an instance field, so `register` never sees it).
+`return $value;` as $return where {
+  not $value <: r"",
+  $return <: within JsClassDeclaration() as $storeClass where {
+    $storeClass <: contains JsExtendsClause() as $extends where {
+      $extends <: r"extends\s+store\([\s\S]*"
+    }
+  },
+  $return <: within JsMethodClassMember() as $action where {
+    not $action <: r"static[\s\S]*"
+  },
+  not $return <: within JsArrowFunctionExpression(),
+  not $return <: within JsFunctionExpression(),
+  not $return <: within JsFunctionDeclaration(),
+  not $return <: within JsMethodObjectMember(),
+  not $return <: within JsGetterObjectMember(),
+  not $return <: within JsSetterObjectMember(),
+  register_diagnostic(
+    span = $return,
+    message = "Store actions dispatch as void — st.do.<action>() never exposes this value. Write the result into state with this.set({ ... }) and drop the returned value; a bare 'return;' guard clause is fine.",
+    severity = "error"
+  )
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.10",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -23,6 +23,7 @@
       "default": "./index.ts"
     },
     "./package.json": "./package.json",
+    "./biome.base.json": "./biome.base.json",
     "./akanApp": "./akanApp/index.ts",
     "./akanConfig": "./akanConfig/index.ts",
     "./artifact": "./artifact/index.ts",
@@ -44,7 +45,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.1",
+    "akanjs": "3.0.0-alpha.10",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/qualityScanner.test.ts

@@ -183,3 +183,17 @@ describe("AkanQualityScanner ssr rules", () => {
     expect(ssrBalance[2]).toMatchObject({ scope: "workspace", serverMass: 3, clientMass: 1 });
   });
 });
+
+describe("AkanQualityScanner layout rules", () => {
+  test("flags an unknown app root file but not a facet entrypoint", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/client.ts": "export const client = 1;\n",
+      "apps/demo/helper.ts": "export const helper = 1;\n",
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.app-root-file");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("apps/demo/helper.ts");
+  });
+});

package/qualityScanner.ts

@@ -1,10 +1,12 @@
 import { createHash } from "node:crypto";
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
+import { RESERVED_ROUTE_CONFIG_EXPORTS } from "akanjs/common";
 import ignore from "ignore";
 import ts from "typescript";
 import { AbstractDoc } from "./abstractDoc";
 import { formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
+import { appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
 
 type QualitySeverity = "warning";
 type QualityScope = "global" | "file" | "convention" | "layout" | "ssr";
@@ -90,29 +92,6 @@ const SUGGESTED_RULES = [
   "Avoid large mixed-purpose class files; class export files should import helpers from neighboring utility files instead of declaring them inline.",
 ];
 
-const APP_ROOT_FILES = new Set([
-  "akan.app.json",
-  "akan.config.ts",
-  "capacitor.config.ts",
-  "client.ts",
-  "main.ts",
-  "package.json",
-  "server.ts",
-  "tsconfig.json",
-]);
-
-const LIB_ROOT_FILES = new Set([
-  "cnst.ts",
-  "db.ts",
-  "dict.ts",
-  "option.ts",
-  "sig.ts",
-  "srv.ts",
-  "st.ts",
-  "useClient.ts",
-  "useServer.ts",
-]);
-
 const CONVENTION_SUFFIXES = [
   ".constant.ts",
   ".dictionary.ts",
@@ -122,24 +101,6 @@ const CONVENTION_SUFFIXES = [
   ".store.ts",
 ] as const;
 
-// Non-PascalCase exports the framework recognizes on page/layout route modules (see PageModule/LayoutModule
-// in pkgs/akanjs/client/csrTypes.ts). PascalCase route exports (Loading, NotFound, Error) pass the component
-// check, and the `default` export is handled separately.
-const PAGE_RESERVED_EXPORTS = new Set([
-  "pageConfig",
-  "head",
-  "metadata",
-  "generateHead",
-  "generateMetadata",
-  "fonts",
-  "manifest",
-  "theme",
-  "reconnect",
-  "wsConnect",
-  "layoutStyle",
-  "gaTrackingId",
-]);
-
 // How to remediate each rule, keyed by rule id. Surfaced as a `fix:` line per warning (text + JSON output)
 // so the scan result tells the reader what to do, not just what is wrong.
 const RULE_FIXES: Record<string, string> = {
@@ -449,7 +410,7 @@ export class AkanQualityScanner {
   #scanLayoutQuality(sourceFile: SourceFileInfo): QualityWarning[] {
     const segments = sourceFile.file.split("/");
     const warnings: QualityWarning[] = [];
-    if (segments[0] === "apps" && segments.length === 3 && !APP_ROOT_FILES.has(segments[2])) {
+    if (segments[0] === "apps" && segments.length === 3 && !appRootAllowedFiles.has(segments[2])) {
       warnings.push({
         rule: "akan.layout.app-root-file",
         scope: "layout",
@@ -460,7 +421,7 @@ export class AkanQualityScanner {
     }
 
     const libRootFile = getLibRootFile(sourceFile.file);
-    if (libRootFile && !LIB_ROOT_FILES.has(libRootFile)) {
+    if (libRootFile && !libFacetRootAllowedFiles.has(libRootFile)) {
       warnings.push({
         rule: "akan.layout.lib-root-file",
         scope: "layout",
@@ -691,7 +652,7 @@ function isRestrictedInternalKind(kind: ComponentFileDeclaration["kind"]) {
 
 function isAllowedComponentExport(declaration: ComponentFileDeclaration, isPage: boolean) {
   if (isComponentValueKind(declaration.kind) && isPascalCaseName(declaration.name)) return true;
-  return isPage && PAGE_RESERVED_EXPORTS.has(declaration.name);
+  return isPage && RESERVED_ROUTE_CONFIG_EXPORTS.has(declaration.name);
 }
 
 function isPascalCaseName(name: string) {

package/repoIdentity.ts

@@ -0,0 +1,42 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+
+// Resolved once per root: every CLI command builds a WorkspaceExecutor, and this would otherwise fork git on each.
+const resolved = new Map<string, string>();
+
+const readRemoteName = (workspaceRoot: string): string | null => {
+  try {
+    const url = execFileSync("git", ["config", "--get", "remote.origin.url"], {
+      cwd: workspaceRoot,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    // Both remote spellings end in the repository: git@host:owner/name.git and https://host/owner/name.git.
+    return (
+      url
+        .replace(/\.git$/, "")
+        .split(/[/:]/)
+        .pop() || null
+    );
+  } catch {
+    // No git, no origin, or no git binary — a fresh `akan workspace` before its first commit lands here.
+    return null;
+  }
+};
+
+/**
+ * The repository's own name.
+ *
+ * Deriving it from the working directory made every generated file that names the repo — the AGENTS.md title, its
+ * `- Repo:` line — depend on what each person happened to call the folder they cloned into, so one commit rendered
+ * a different guide per developer and the diff never settled. The origin remote is the one identity every clone
+ * shares. `AKAN_PUBLIC_REPO_NAME` is deliberately not consulted: that is a deployment namespace (queue prefixes,
+ * cache keys, secret paths) which a monorepo hosting several products legitimately points somewhere else.
+ */
+export const resolveRepoName = (workspaceRoot: string): string => {
+  const cached = resolved.get(workspaceRoot);
+  if (cached) return cached;
+  const repoName = readRemoteName(workspaceRoot) ?? path.basename(workspaceRoot);
+  resolved.set(workspaceRoot, repoName);
+  return repoName;
+};

package/routeSourceValidator.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+
+import { RouteSourceValidator } from "./routeSourceValidator";
+
+const validate = (source: string, kind: "page" | "layout", rootLayout = false) =>
+  RouteSourceValidator.validateRouteSourceExports(source, `page/_${kind}.tsx`, kind, { rootLayout });
+
+describe("RouteSourceValidator", () => {
+  test("accepts every root-layout config export the route tree honors", () => {
+    const source = [
+      "export default function Layout() { return null; }",
+      "export const fonts = [];",
+      "export const manifest = {};",
+      'export const theme = "dark";',
+      "export const reconnect = true;",
+      "export const wsConnect = true;",
+      "export const layoutStyle = {};",
+      'export const gaTrackingId = "G-1";',
+    ].join("\n");
+
+    expect(() => validate(source, "layout", true)).not.toThrow();
+  });
+
+  test("rejects root-layout-only exports on a nested layout and on a page", () => {
+    const source = ["export default function Layout() { return null; }", "export const wsConnect = true;"].join("\n");
+
+    expect(() => validate(source, "layout")).toThrow('unsupported export "wsConnect"');
+    expect(() => validate(source, "page")).toThrow('unsupported export "wsConnect"');
+  });
+
+  test("reads devOnly off pageConfig without evaluating the module", () => {
+    const source = [
+      "export default function Page() { return null; }",
+      "export const pageConfig = { devOnly: true };",
+    ].join("\n");
+
+    expect(RouteSourceValidator.validateRouteSourceExports(source, "page/_index.tsx", "page")).toEqual({
+      devOnly: true,
+    });
+  });
+});

package/routeSourceValidator.ts

@@ -1,3 +1,4 @@
+import { getRouteExports } from "akanjs/common";
 import ts from "typescript";
 
 /** What the build needs out of a route module without evaluating it. */
@@ -16,44 +17,6 @@ export interface RouteSourceInfo {
  * validate a route source stay lean.
  */
 export class RouteSourceValidator {
-  static readonly #pageExports = new Set([
-    "default",
-    "pageConfig",
-    "head",
-    "metadata",
-    "generateHead",
-    "generateMetadata",
-    "Loading",
-  ]);
-  static readonly #rootLayoutExports = new Set([
-    "default",
-    "pageConfig",
-    "head",
-    "metadata",
-    "generateHead",
-    "generateMetadata",
-    "fonts",
-    "manifest",
-    "theme",
-    "reconnect",
-    "layoutStyle",
-    "gaTrackingId",
-    "Loading",
-    "NotFound",
-    "Error",
-  ]);
-  static readonly #layoutExports = new Set([
-    "default",
-    "pageConfig",
-    "head",
-    "metadata",
-    "generateHead",
-    "generateMetadata",
-    "Loading",
-    "NotFound",
-    "Error",
-  ]);
-
   static validateRouteSourceExports(
     source: string,
     filePath: string,
@@ -61,12 +24,7 @@ export class RouteSourceValidator {
     options: { rootLayout?: boolean } = {},
   ): RouteSourceInfo {
     const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-    const allowed =
-      kind === "page"
-        ? RouteSourceValidator.#pageExports
-        : options.rootLayout
-          ? RouteSourceValidator.#rootLayoutExports
-          : RouteSourceValidator.#layoutExports;
+    const allowed = getRouteExports(kind, { rootLayout: options.rootLayout });
     const exported = new Set<string>();
     const assertExport = (name: string) => {
       if (!allowed.has(name)) {

package/scanInfo.ts

@@ -11,6 +11,7 @@ import type {
 } from "./akanConfig";
 
 import { AppExecutor, LibExecutor, PkgExecutor, WorkspaceExecutor } from "./executors";
+import { appRootAllowedDirs, appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
 
 const scalarFileTypes = ["constant", "dictionary", "document", "template", "unit", "util", "view", "zone"] as const;
 type ScalarFileType = (typeof scalarFileTypes)[number];
@@ -43,49 +44,7 @@ type DatabaseFileType = (typeof databaseFileTypes)[number];
 
 type ModuleKind = "database" | "service" | "scalar";
 
-const appRootAllowedFiles = new Set([
-  // 스코프 에이전트 가이드 — scan(write) 이 유지하는 색인 + 마커 밖 hand-written 내용 (agentsIndex.ts)
-  "AGENTS.md",
-  "CLAUDE.md",
-  "akan.app.json",
-  "akan.config.ts",
-  "capacitor.config.ts",
-  "client.ts",
-  "main.ts",
-  "package.json",
-  "server.ts",
-  "tsconfig.json",
-  "tsconfig.tsbuildinfo",
-]);
 const generatedRootCapacitorConfigFiles = ["capacitor.config.js", "capacitor.config.json"] as const;
-const appRootAllowedDirs = new Set([
-  ".akan",
-  "android",
-  "env",
-  "ios",
-  "lib",
-  "mobile",
-  "page",
-  "private",
-  "public",
-  "script",
-  "ui",
-  "srvkit",
-  "webkit",
-  "common",
-  "secrets",
-]);
-const libRootAllowedFiles = new Set([
-  "cnst.ts",
-  "db.ts",
-  "dict.ts",
-  "option.ts",
-  "sig.ts",
-  "srv.ts",
-  "st.ts",
-  "useClient.ts",
-  "useServer.ts",
-]);
 const internalLibDirs = new Set(["__lib", "__scalar"]);
 const moduleNonUiFileTypes = {
   database: new Set(["constant", "dictionary", "document", "service", "signal", "store"]),
@@ -107,7 +66,7 @@ const createDependencyScanner = async (exec: AppExecutor | LibExecutor | PkgExec
 
 const isAllowedTestFile = (filename: string) => testFilePattern.test(filename);
 const isAllowedLibRootFile = (filename: string) =>
-  libRootAllowedFiles.has(filename) || rootSignalTestFilePattern.test(filename);
+  libFacetRootAllowedFiles.has(filename) || rootSignalTestFilePattern.test(filename);
 const getScanPath = (exec: AppExecutor | LibExecutor, relativePath: string) =>
   path.posix.join(`${exec.type}s`, exec.name, relativePath.split(path.sep).join("/"));
 async function clearGeneratedRootCapacitorConfigs(exec: AppExecutor | LibExecutor) {

package/workspaceLayout.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { appRootAllowedDirs, appRootAllowedFiles, isScannedAppRootEntry } from "./workspaceLayout";
+
+describe("app root layout allowlist", () => {
+  test("admits the scoped agent guides sync writes into every app", () => {
+    expect(appRootAllowedFiles.has("AGENTS.md")).toBe(true);
+    expect(appRootAllowedFiles.has("CLAUDE.md")).toBe(true);
+  });
+
+  test("admits every documented app root folder", () => {
+    for (const dirname of ["mobile", "plugin", "secrets", "srvkit", "webkit"]) {
+      expect(appRootAllowedDirs.has(dirname)).toBe(true);
+    }
+  });
+
+  test("rejects an app root entry no facet owns", () => {
+    expect(appRootAllowedFiles.has("helper.ts")).toBe(false);
+    expect(appRootAllowedDirs.has("base")).toBe(false);
+  });
+
+  test("skips dotfile artifacts the sync glob never sees, but keeps .akan", () => {
+    expect(isScannedAppRootEntry(".DS_Store")).toBe(false);
+    expect(isScannedAppRootEntry(".akan")).toBe(true);
+    expect(isScannedAppRootEntry("lib")).toBe(true);
+  });
+});

package/workspaceLayout.ts

@@ -0,0 +1,60 @@
+/**
+ * App/lib 루트 레이아웃 허용 목록 — 단일 소스.
+ *
+ * 같은 규칙을 scanInfo(`akan sync`, hard error) · akanContext(`akan doctor`, diagnostic) ·
+ * qualityScanner(`akan quality scan`, warning) 세 곳이 각자 복사해 두면서 실제로 어긋났다
+ * (스코프 AGENTS.md/CLAUDE.md 는 sync 만 허용, `plugin` 은 문서에만, `secrets` 는 doctor 만 거부).
+ * 규칙을 추가할 때는 이 파일만 고치고, 루트 AGENTS.md 의 목록도 같이 갱신한다.
+ */
+
+export const appRootAllowedFiles = new Set([
+  // 스코프 에이전트 가이드 — scan(write) 이 유지하는 색인 + 마커 밖 hand-written 내용 (agentsIndex.ts)
+  "AGENTS.md",
+  "CLAUDE.md",
+  "akan.app.json",
+  "akan.config.ts",
+  "capacitor.config.ts",
+  "client.ts",
+  "main.ts",
+  "package.json",
+  "server.ts",
+  "tsconfig.json",
+  "tsconfig.tsbuildinfo",
+]);
+
+export const appRootAllowedDirs = new Set([
+  ".akan",
+  "android",
+  "common",
+  "env",
+  "ios",
+  "lib",
+  "mobile",
+  "page",
+  "plugin",
+  "private",
+  "public",
+  "script",
+  "secrets",
+  "srvkit",
+  "ui",
+  "webkit",
+]);
+
+export const libFacetRootAllowedFiles = new Set([
+  "cnst.ts",
+  "db.ts",
+  "dict.ts",
+  "option.ts",
+  "sig.ts",
+  "srv.ts",
+  "st.ts",
+  "useClient.ts",
+  "useServer.ts",
+]);
+
+/**
+ * scanSync 는 앱 루트를 `Bun.Glob("*")` 로 읽어 dotfile 을 아예 보지 못한다. 디렉터리를 직접 읽는
+ * doctor 가 그 차이만큼 `.DS_Store` 같은 툴 산출물을 에러로 올리므로 같은 기준으로 걸러낸다.
+ */
+export const isScannedAppRootEntry = (name: string) => !name.startsWith(".") || appRootAllowedDirs.has(name);