@akanjs/devkit 3.0.0-alpha.4 → 3.0.0-alpha.6

package/qualityScanner.test.ts

@@ -3,7 +3,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { AbstractDoc } from "./abstractDoc";
-import { AkanQualityScanner } from "./qualityScanner";
+import { AkanQualityScanner, type QualityScanResult } from "./qualityScanner";
 
 const tempRoots: string[] = [];
 
@@ -44,3 +44,156 @@ describe("AkanQualityScanner abstract rule", () => {
     expect(warnings[0]?.fix).toContain("akan compact");
   });
 });
+
+const staticMarkup = (elementNum: number) =>
+  Array.from({ length: elementNum }, (_, idx) => `      <p className="text-sm">row ${idx}</p>`).join("\n");
+
+const rulesOf = (result: QualityScanResult, rule: string) => result.warnings.filter((warning) => warning.rule === rule);
+
+describe("AkanQualityScanner ssr rules", () => {
+  test("flags a client file that uses no client-only capability", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Plain.tsx": `"use client";\nexport const Plain = () => <div>plain</div>;\n`,
+      "apps/demo/ui/Interactive.tsx": `"use client";\nexport const Interactive = () => <button onClick={() => null}>go</button>;\n`,
+      "apps/demo/ui/Hooked.tsx": `"use client";\nimport { useState } from "react";\nexport const Hooked = () => {\n  const [open] = useState(false);\n  return <div>{open ? "y" : "n"}</div>;\n};\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.unnecessary-use-client");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("apps/demo/ui/Plain.tsx");
+  });
+
+  test("keeps the directive on a third-party wrapper and on an index_ boundary", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Chart.tsx": `"use client";\nimport { Bar } from "react-chartjs-2";\nexport const Chart = () => <Bar data={{}} />;\n`,
+      "apps/demo/ui/Lazy/index_.tsx": `"use client";\nexport { Inner } from "./Inner";\n`,
+    });
+
+    expect(rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.unnecessary-use-client")).toHaveLength(0);
+  });
+
+  test("flags a static component and a mostly-static component inside a client file", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Panels.tsx": [
+        `"use client";`,
+        `import { useState } from "react";`,
+        `export const StaticPanel = () => (`,
+        `  <section>`,
+        staticMarkup(5),
+        `  </section>`,
+        `);`,
+        `export const MixedPanel = () => {`,
+        `  const [open, setOpen] = useState(false);`,
+        `  return (`,
+        `    <section>`,
+        staticMarkup(12),
+        `      <span>{open ? "open" : "shut"}</span>`,
+        `    </section>`,
+        `  );`,
+        `};`,
+        "",
+      ].join("\n"),
+    });
+
+    const result = await new AkanQualityScanner().scan(root);
+    const staticWarnings = rulesOf(result, "akan.ssr.client-static-component");
+    const mixedWarnings = rulesOf(result, "akan.ssr.client-static-markup");
+
+    expect(staticWarnings).toHaveLength(1);
+    expect(staticWarnings[0]?.message).toContain("StaticPanel");
+    expect(staticWarnings[0]?.fix).toContain("server file");
+    expect(mixedWarnings).toHaveLength(1);
+    expect(mixedWarnings[0]?.message).toContain("MixedPanel");
+  });
+
+  test("flags a mount-only load but not a reactive one", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/Post.Zone.tsx": [
+        `"use client";`,
+        `import { useEffect } from "react";`,
+        `export const List = ({ tag }: { tag: string }) => {`,
+        `  useEffect(() => {`,
+        `    void st.do.initPostInPublic();`,
+        `  }, []);`,
+        `  useEffect(() => {`,
+        `    void st.do.getPostListInTag(tag);`,
+        `  }, [tag]);`,
+        `  return <div>{tag}</div>;`,
+        `};`,
+        "",
+      ].join("\n"),
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.client-mount-load");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("st.do.initPostInPublic");
+    expect(warnings[0]?.fix).toContain("init/view");
+  });
+
+  test("flags useState in a Template", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/Post.Template.tsx": `"use client";\nimport { useState } from "react";\nexport const General = () => {\n  const [draft, setDraft] = useState("");\n  return <input value={draft} onChange={(e) => setDraft(e.target.value)} />;\n};\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.template-client-state");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.fix).toContain("st.do.setFieldOnX");
+  });
+
+  test("flags a module that renders only from client files", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/Post.Zone.tsx": [
+        `"use client";`,
+        `import { useState } from "react";`,
+        `export const Card = () => {`,
+        `  const [open] = useState(false);`,
+        `  return (`,
+        `    <section>`,
+        staticMarkup(14),
+        `      <span>{open ? "open" : "shut"}</span>`,
+        `    </section>`,
+        `  );`,
+        `};`,
+        "",
+      ].join("\n"),
+      "libs/shared/lib/user/User.Zone.tsx": `"use client";\nimport { st } from "@libs/shared/client";\nexport const Self = () => <User.View.General user={st.use.self()} />;\n`,
+      "libs/shared/lib/user/User.View.tsx": `export const General = ({ name }: { name: string }) => <div>{name}</div>;\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.module-missing-server-view");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("apps/demo/lib/post");
+  });
+
+  test("measures the server render share per scope and for the workspace", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Server.tsx": `export const Server = () => (\n  <section>\n    <p>a</p>\n    <p>b</p>\n  </section>\n);\n`,
+      "libs/shared/ui/Client.tsx": `"use client";\nexport const Client = () => <button onClick={() => null}>go</button>;\n`,
+    });
+
+    const { ssrBalance } = await new AkanQualityScanner().scan(root);
+
+    expect(ssrBalance.map((entry) => entry.scope)).toEqual(["apps/demo", "libs/shared", "workspace"]);
+    expect(ssrBalance[0]).toMatchObject({ serverMass: 3, clientMass: 0, serverShare: 1 });
+    expect(ssrBalance[1]).toMatchObject({ serverMass: 0, clientMass: 1 });
+    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

@@ -4,9 +4,11 @@ import path from "node:path";
 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";
+type QualityScope = "global" | "file" | "convention" | "layout" | "ssr";
 
 export interface QualityWarning {
   rule: string;
@@ -23,10 +25,11 @@ export interface QualityScanResult {
   workspaceRoot: string;
   scannedFiles: number;
   warnings: QualityWarning[];
+  ssrBalance: SsrBalanceEntry[];
   suggestedRules: string[];
 }
 
-interface SourceFileInfo {
+export interface SourceFileInfo {
   file: string;
   absolutePath: string;
   content: string;
@@ -88,29 +91,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",
@@ -169,6 +149,18 @@ const RULE_FIXES: Record<string, string> = {
     "Move the file into a domain module folder under lib/; keep lib root limited to generated support facets.",
   "akan.layout.module-ui-file":
     "Rename the file to an allowed module UI name, or move it to ui/ if it is not a module component.",
+  "akan.ssr.unnecessary-use-client":
+    'Delete the "use client" directive so the file renders on the server. If it exists only to wrap one client child, drop the wrapper and use the child directly.',
+  "akan.ssr.client-static-component":
+    "Move the component to a server file — a <Model>.Unit.tsx / <Model>.View.tsx for a module, or a ui/ file with no directive — and reference it from the client file.",
+  "akan.ssr.client-static-markup":
+    "Keep the interactive element in the client component and hoist the static subtree into a server component, then accept it as `children` or render it through a Unit/View reference.",
+  "akan.ssr.client-mount-load":
+    "Load the data in the route with `fetch.initX(...)` / `fetch.viewX(...)` and pass the init/view object down as a prop; the client store hydrates from it and the effect goes away.",
+  "akan.ssr.module-missing-server-view":
+    "Add a <Model>.Unit.tsx for list/card rendering and a <Model>.View.tsx for the detail surface, then have the Zone delegate to them.",
+  "akan.ssr.template-client-state":
+    "Bind the field to the store instead: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`.",
 };
 
 function getRuleFix(rule: string): string | undefined {
@@ -190,6 +182,7 @@ export class AkanQualityScanner {
         .filter((file) => AbstractDoc.isAbstractPath(file))
         .map((file) => this.#readTextFile(workspaceRoot, file)),
     );
+    const ssr = new SsrScanner().scan(sourceFiles);
     const warnings = [
       ...this.#scanGlobalQuality(sourceFiles),
       ...sourceFiles.flatMap((sourceFile) => this.#scanSingleFileQuality(sourceFile)),
@@ -197,6 +190,7 @@ export class AkanQualityScanner {
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
       ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
+      ...ssr.warnings,
     ];
 
     return {
@@ -205,6 +199,7 @@ export class AkanQualityScanner {
       warnings: warnings
         .map((warning) => ({ ...warning, fix: warning.fix ?? getRuleFix(warning.rule) }))
         .sort(compareWarnings),
+      ssrBalance: ssr.balance,
       suggestedRules: SUGGESTED_RULES,
     };
   }
@@ -432,7 +427,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",
@@ -443,7 +438,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",
@@ -470,6 +465,10 @@ export function formatQualityScanResult(result: QualityScanResult) {
     "",
     ...formatQualityWarnings(result.warnings),
     "",
+    "SSR balance (component files, JSX elements rendered per side):",
+    "",
+    ...formatSsrBalance(result.ssrBalance),
+    "",
     "Suggested quality rules:",
     "",
     ...result.suggestedRules.map((rule) => `  - ${rule}`),
@@ -477,6 +476,24 @@ export function formatQualityScanResult(result: QualityScanResult) {
   return sections.join("\n");
 }
 
+export function formatSsrScanResult(result: QualityScanResult) {
+  const sections = [
+    "Akan SSR Balance Scan",
+    `workspace: ${result.workspaceRoot}`,
+    `scanned files: ${result.scannedFiles}`,
+    `ssr warnings: ${result.warnings.length}`,
+    "",
+    "Server render share (component files, JSX elements rendered per side):",
+    "",
+    ...formatSsrBalance(result.ssrBalance),
+    "",
+    "Warnings:",
+    "",
+    ...formatQualityWarnings(result.warnings),
+  ];
+  return sections.join("\n");
+}
+
 export function formatQualityWarnings(warnings: QualityWarning[]) {
   if (warnings.length === 0) return ["No warnings found."];
   return warnings.flatMap((warning) => {

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/spinner.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { Spinner } from "./spinner";
+
+interface TtyStub {
+  restore: () => void;
+  rawModeCalls: boolean[];
+}
+
+/**
+ * ora only reaches for stdin when both streams look interactive, so the stub has to fake a tty on
+ * stderr (which decides `isEnabled`) as well as on stdin.
+ */
+const stubTty = (): TtyStub => {
+  const rawModeCalls: boolean[] = [];
+  const stdin = process.stdin as NodeJS.ReadStream & { setRawMode?: (mode: boolean) => unknown };
+  const previous = {
+    stdinIsTTY: stdin.isTTY,
+    stderrIsTTY: process.stderr.isTTY,
+    stderrColumns: process.stderr.columns,
+    setRawMode: stdin.setRawMode,
+    isPaused: stdin.isPaused,
+  };
+  stdin.isTTY = true;
+  process.stderr.isTTY = true;
+  process.stderr.columns = 120;
+  stdin.setRawMode = (mode: boolean) => {
+    rawModeCalls.push(mode);
+    return stdin;
+  };
+  stdin.isPaused = () => true;
+  return {
+    rawModeCalls,
+    restore: () => {
+      stdin.isTTY = previous.stdinIsTTY;
+      process.stderr.isTTY = previous.stderrIsTTY;
+      process.stderr.columns = previous.stderrColumns;
+      stdin.setRawMode = previous.setRawMode;
+      stdin.isPaused = previous.isPaused;
+    },
+  };
+};
+
+describe("Spinner", () => {
+  // A raw terminal at spawn time is what a Bun child snapshots and writes back when it exits, which is
+  // how `akan start` used to leave a terminal that no longer turns Ctrl+C into SIGINT.
+  test("never puts the terminal into raw mode while it spins", () => {
+    const tty = stubTty();
+    try {
+      const spinner = new Spinner("Preparing backend...").start();
+      expect(tty.rawModeCalls).toEqual([]);
+      spinner.succeed("prepared");
+      expect(tty.rawModeCalls).toEqual([]);
+    } finally {
+      tty.restore();
+    }
+  });
+
+  test("keeps ora's stdin discarder disabled", () => {
+    expect(Spinner.oraOptions.discardStdin).toBe(false);
+  });
+
+  // An unsized pty reports `isTTY: true` with `columns: 0`, which turns ora's clear loop into an
+  // infinite one — the process then writes cursor moves until it is SIGKILLed.
+  test("refuses to animate against a tty that reports no width", () => {
+    expect(Spinner.canAnimate({ isTTY: true, columns: 0 } as NodeJS.WriteStream)).toBe(false);
+    expect(Spinner.canAnimate({ isTTY: true, columns: 120 } as NodeJS.WriteStream)).toBe(true);
+    expect(Spinner.canAnimate({ isTTY: false, columns: 0 } as NodeJS.WriteStream)).toBe(true);
+  });
+
+  test("falls back to plain lines when the terminal has no width", () => {
+    const previous = { isTTY: process.stderr.isTTY, columns: process.stderr.columns };
+    process.stderr.isTTY = true;
+    process.stderr.columns = 0;
+    try {
+      expect(new Spinner("Preparing backend...").enableSpin).toBe(false);
+    } finally {
+      process.stderr.isTTY = previous.isTTY;
+      process.stderr.columns = previous.columns;
+    }
+  });
+});

package/spinner.ts

@@ -2,6 +2,26 @@ import ora, { type Ora } from "ora";
 
 export class Spinner {
   static padding = 12;
+  /**
+   * XXX: `discardStdin` must stay off. It makes ora put the terminal into raw mode for as long as the
+   * spinner runs, and a Bun child spawned in that window snapshots the raw termios and writes it back
+   * when it exits — long after the spinner restored the terminal. `akan start` spawns the builder and
+   * the backend under the "Preparing backend..." spinner, so the first builder recycle (a config or
+   * runtime-metadata change) SIGTERMs that child and silently turns the developer's terminal raw:
+   * `isig` goes off, Ctrl+C stops producing SIGINT at all, and the dev server looks unkillable.
+   */
+  static oraOptions = { discardStdin: false } as const;
+  /**
+   * ora sizes its clear loop as `ceil(lineWidth / stream.columns)`, so a tty that reports **0** columns
+   * makes it `Infinity` and `clear()` never returns. An unsized pty does exactly that (`isTTY: true`,
+   * `columns: 0`) — CI runners, `expect`/`script` harnesses, some detached panes. Measured: 750MB of
+   * cursor moves and 8.7GB RSS inside a minute, in a loop that no longer reaches the point where SIGINT
+   * or SIGTERM could be handled, so only SIGKILL ends it. A terminal with no width has nothing to
+   * animate anyway; fall back to plain lines.
+   */
+  static canAnimate(stream: NodeJS.WriteStream = process.stderr): boolean {
+    return !stream.isTTY || stream.columns > 0;
+  }
   spinner: Ora;
   stopWatch: NodeJS.Timeout | null = null;
   startAt: Date = new Date();
@@ -12,10 +32,10 @@ export class Spinner {
     Spinner.padding = Math.max(Spinner.padding, prefix.length);
     this.prefix = prefix;
     this.message = message;
-    this.spinner = ora(message);
+    this.spinner = ora({ ...Spinner.oraOptions, text: message });
     this.spinner.prefixText = prefix.padStart(Spinner.padding, " ");
     this.spinner.indent = indent;
-    this.enableSpin = enableSpin;
+    this.enableSpin = enableSpin && Spinner.canAnimate();
   }
   start() {
     this.startAt = new Date();