@akanjs/devkit 3.0.0-alpha.8 → 3.0.0-alpha.80

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`;

package/workflow/executor.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from "bun:test";
+import { WorkflowExecutor, workflowStepKey } from "./executor";
+import type {
+  PrimitiveChangedFile,
+  WorkflowDiagnostic,
+  WorkflowPlan,
+  WorkflowStep,
+  WorkflowStepRegistry,
+  WorkflowStepResult,
+} from "./types";
+
+/**
+ * `WorkflowExecutor` takes its registry by constructor injection and its plan as data, so `apply` runs with
+ * no filesystem and no workspace — the `workspace` argument is what gates every post-apply check. These
+ * cover the ordering rules that `cli/workflow/workflow.test.ts` can only reach through a real scaffold.
+ */
+const step = (id: string, tool = `tool:${id}`): WorkflowStep => ({
+  id,
+  tool,
+  title: id,
+  description: id,
+});
+
+// Every field spelled out rather than cast through `unknown`: `apply` reads `validation` before the first
+// step runs, so a partial literal fails at runtime instead of at the type level.
+const planOf = (steps: WorkflowStep[], diagnostics: WorkflowDiagnostic[] = []): WorkflowPlan => ({
+  schemaVersion: 1,
+  workflow: "add-field",
+  mode: "plan",
+  inputs: {},
+  optionalSurfaces: {},
+  steps,
+  predictedChanges: [],
+  validation: [],
+  diagnostics,
+  recommendations: [],
+  requiresApproval: true,
+});
+
+/**
+ * A registry that records **which key** each call resolved through, not just that a step ran — the
+ * resolution order is the thing under test, and every candidate key would otherwise record the same step id.
+ */
+const changed = (path: string): PrimitiveChangedFile => ({ path, action: "modify", reason: "test" });
+
+const recordingRegistry = (results: Record<string, WorkflowStepResult | undefined> = {}) => {
+  const calls: string[] = [];
+  const registry: WorkflowStepRegistry = {};
+  const on = (key: string) => {
+    registry[key] = async () => {
+      calls.push(key);
+      return results[key];
+    };
+  };
+  return { calls, registry, on };
+};
+
+describe("WorkflowExecutor.apply", () => {
+  test("runs no step when the plan already carries an error diagnostic", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    on(workflowStepKey("add-field", "one"));
+    const plan = planOf([step("one")], [{ severity: "error", code: "plan-invalid", message: "bad inputs" }]);
+
+    const report = await new WorkflowExecutor(registry).apply(plan);
+
+    expect(calls).toEqual([]);
+    expect(report.diagnostics.map((diagnostic) => diagnostic.code)).toContain("plan-invalid");
+  });
+
+  test("a warning in the plan does not stop the steps", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    on(workflowStepKey("add-field", "one"));
+    const plan = planOf([step("one")], [{ severity: "warning", code: "plan-note", message: "heads up" }]);
+
+    await new WorkflowExecutor(registry).apply(plan);
+
+    expect(calls).toEqual([workflowStepKey("add-field", "one")]);
+  });
+
+  test("resolves a runner by workflow-scoped key first, then tool, then bare step id", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    // All three keys are registered for the same step, so only the winner records a call.
+    on(workflowStepKey("add-field", "scoped"));
+    on("tool:scoped");
+    on("scoped");
+    await new WorkflowExecutor(registry).apply(planOf([step("scoped")]));
+    expect(calls).toEqual([workflowStepKey("add-field", "scoped")]);
+
+    const byTool = recordingRegistry();
+    byTool.on("tool:viaTool");
+    byTool.on("viaTool");
+    await new WorkflowExecutor(byTool.registry).apply(planOf([step("viaTool")]));
+    expect(byTool.calls).toEqual(["tool:viaTool"]);
+
+    const byId = recordingRegistry();
+    byId.on("viaId");
+    await new WorkflowExecutor(byId.registry).apply(planOf([step("viaId")]));
+    expect(byId.calls).toEqual(["viaId"]);
+  });
+
+  test("an unsupported step is reported and abandons the rest of the plan", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    on(workflowStepKey("add-field", "first"));
+    on(workflowStepKey("add-field", "third"));
+
+    const report = await new WorkflowExecutor(registry).apply(planOf([step("first"), step("second"), step("third")]));
+
+    expect(calls).toEqual([workflowStepKey("add-field", "first")]);
+    expect(report.diagnostics.map((diagnostic) => diagnostic.code)).toContain("workflow-step-unsupported");
+    expect(report.nextActions.map((action) => action.command)).toContain("akan workflow explain add-field");
+  });
+
+  test("accumulates changed files and diagnostics across steps, and stops at the first error", async () => {
+    const key = (id: string) => workflowStepKey("add-field", id);
+    const { calls, registry, on } = recordingRegistry({
+      [key("a")]: { changedFiles: [changed("apps/demo/lib/task/task.constant.ts")] },
+      [key("b")]: {
+        changedFiles: [changed("apps/demo/lib/task/task.dictionary.ts")],
+        diagnostics: [{ severity: "error", code: "step-failed", message: "no such module" }],
+      },
+      [key("c")]: { changedFiles: [changed("never-reached.ts")] },
+    });
+    on(key("a"));
+    on(key("b"));
+    on(key("c"));
+
+    const report = await new WorkflowExecutor(registry).apply(planOf([step("a"), step("b"), step("c")]));
+
+    expect(calls).toEqual([key("a"), key("b")]);
+    expect(report.changedFiles.map((file) => file.path)).toEqual([
+      "apps/demo/lib/task/task.constant.ts",
+      "apps/demo/lib/task/task.dictionary.ts",
+    ]);
+    expect(report.diagnostics.map((diagnostic) => diagnostic.code)).toContain("step-failed");
+  });
+
+  test("a runner that answers nothing is not an error", async () => {
+    const { calls, registry, on } = recordingRegistry();
+    on(workflowStepKey("add-field", "silent"));
+    const report = await new WorkflowExecutor(registry).apply(planOf([step("silent")]));
+
+    expect(calls).toEqual([workflowStepKey("add-field", "silent")]);
+    expect(report.diagnostics.filter((diagnostic) => diagnostic.severity === "error")).toEqual([]);
+    expect(report.changedFiles).toEqual([]);
+  });
+});

package/workspaceLayout.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import { appRootAllowedDirs, appRootAllowedFiles, isScannedAppRootEntry } from "./workspaceLayout";
+import {
+  appRootAllowedDirs,
+  appRootAllowedFiles,
+  isAllowedLibFacetRootFile,
+  isScannedRootEntry,
+  libRootAllowedDirs,
+  libRootAllowedFiles,
+} from "./workspaceLayout";
 
 describe("app root layout allowlist", () => {
   test("admits the scoped agent guides sync writes into every app", () => {
@@ -19,8 +26,53 @@ describe("app root layout allowlist", () => {
   });
 
   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);
+    expect(isScannedRootEntry("app", ".DS_Store")).toBe(false);
+    expect(isScannedRootEntry("app", ".akan")).toBe(true);
+    expect(isScannedRootEntry("app", "lib")).toBe(true);
+  });
+});
+
+describe("lib root layout allowlist", () => {
+  test("admits what the libRoot template and scan write", () => {
+    for (const filename of ["AGENTS.md", "akan.config.ts", "akan.lib.json", "client.ts", "index.ts", "server.ts"]) {
+      expect(libRootAllowedFiles.has(filename)).toBe(true);
+    }
+    for (const dirname of ["common", "env", "lib", "page", "plugin", "private", "public", "srvkit", "ui", "webkit"]) {
+      expect(libRootAllowedDirs.has(dirname)).toBe(true);
+    }
+  });
+
+  test("rejects a lib root entry no facet owns", () => {
+    expect(libRootAllowedFiles.has("helper.ts")).toBe(false);
+    expect(libRootAllowedDirs.has("base")).toBe(false);
+  });
+
+  test("rejects the app-only run and mobile entries", () => {
+    for (const filename of ["main.ts", "capacitor.config.ts", "akan.app.json"]) {
+      expect(libRootAllowedFiles.has(filename)).toBe(false);
+    }
+    for (const dirname of [".akan", "android", "ios", "mobile", "script", "secrets"]) {
+      expect(libRootAllowedDirs.has(dirname)).toBe(false);
+    }
+  });
+
+  test("skips dotfile artifacts in a lib root too", () => {
+    expect(isScannedRootEntry("lib", ".gitignore")).toBe(false);
+    expect(isScannedRootEntry("lib", ".akan")).toBe(false);
+    expect(isScannedRootEntry("lib", "ui")).toBe(true);
+  });
+});
+
+describe("lib facet root allowlist", () => {
+  test("admits the generated support facets and a root signal test", () => {
+    expect(isAllowedLibFacetRootFile("cnst.ts")).toBe(true);
+    expect(isAllowedLibFacetRootFile("option.ts")).toBe(true);
+    expect(isAllowedLibFacetRootFile("user.signal.test.ts")).toBe(true);
+    expect(isAllowedLibFacetRootFile("user.signal.spec.ts")).toBe(true);
+  });
+
+  test("rejects a hand-written file beside the barrels", () => {
+    expect(isAllowedLibFacetRootFile("helper.ts")).toBe(false);
+    expect(isAllowedLibFacetRootFile("user.test.ts")).toBe(false);
   });
 });

package/workspaceLayout.ts

@@ -4,10 +4,11 @@
  * 같은 규칙을 scanInfo(`akan sync`, hard error) · akanContext(`akan doctor`, diagnostic) ·
  * qualityScanner(`akan quality scan`, warning) 세 곳이 각자 복사해 두면서 실제로 어긋났다
  * (스코프 AGENTS.md/CLAUDE.md 는 sync 만 허용, `plugin` 은 문서에만, `secrets` 는 doctor 만 거부).
- * 규칙을 추가할 때는 이 파일만 고치고, 루트 AGENTS.md 와 `.cursor/rules/akan-scan-conventions.mdc`
- * 의 목록도 같이 갱신한다.
+ * 규칙을 추가할 때는 이 파일만 고치고, 루트 AGENTS.md 의 목록도 같이 갱신한다.
  */
 
+export type SysType = "app" | "lib";
+
 export const appRootAllowedFiles = new Set([
   // 스코프 에이전트 가이드 — scan(write) 이 유지하는 색인 + 마커 밖 hand-written 내용 (agentsIndex.ts)
   "AGENTS.md",
@@ -42,6 +43,43 @@ export const appRootAllowedDirs = new Set([
   "webkit",
 ]);
 
+/**
+ * 라이브러리 루트는 앱 루트에서 실행/모바일 전용 항목(`main.ts`, `capacitor.config.ts`, `.akan`,
+ * `android`, `ios`, `mobile`, `script`, `secrets`)을 뺀 집합이다 — 라이브러리는 부팅되지도, 패키징되지도
+ * 않는다. `index.ts` 는 lib 에만 생성되고, `README.md` / `tsconfig.spec.json` 은 라이브러리가 패키지로
+ * 배포되기 때문에 남는다. `public` / `private` 은 syncAssets 가 앱으로 심링크하므로 라이브러리도 가진다.
+ */
+export const libRootAllowedFiles = new Set([
+  "AGENTS.md",
+  "CLAUDE.md",
+  "README.md",
+  "akan.config.ts",
+  "akan.lib.json",
+  "client.ts",
+  "index.ts",
+  "package.json",
+  "server.ts",
+  "tsconfig.json",
+  "tsconfig.spec.json",
+  "tsconfig.tsbuildinfo",
+]);
+
+export const libRootAllowedDirs = new Set([
+  "common",
+  "env",
+  "lib",
+  "page",
+  "plugin",
+  "private",
+  "public",
+  "srvkit",
+  "ui",
+  "webkit",
+]);
+
+export const rootAllowedFiles = { app: appRootAllowedFiles, lib: libRootAllowedFiles } as const;
+export const rootAllowedDirs = { app: appRootAllowedDirs, lib: libRootAllowedDirs } as const;
+
 export const libFacetRootAllowedFiles = new Set([
   "cnst.ts",
   "db.ts",
@@ -54,8 +92,15 @@ export const libFacetRootAllowedFiles = new Set([
   "useServer.ts",
 ]);
 
+/** `<model>.signal.test.ts` — lib 파싯 루트에 놓이는 유일한 비생성 파일 (테스트가 배럴 전체를 부팅한다). */
+const libFacetRootTestPattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(ts|tsx)$/;
+
+export const isAllowedLibFacetRootFile = (filename: string) =>
+  libFacetRootAllowedFiles.has(filename) || libFacetRootTestPattern.test(filename);
+
 /**
- * scanSync 는 앱 루트를 `Bun.Glob("*")` 로 읽어 dotfile 을 아예 보지 못한다. 디렉터리를 직접 읽는
+ * scanSync 는 루트를 `Bun.Glob("*")` 로 읽어 dotfile 을 아예 보지 못한다. 디렉터리를 직접 읽는
  * doctor 가 그 차이만큼 `.DS_Store` 같은 툴 산출물을 에러로 올리므로 같은 기준으로 걸러낸다.
  */
-export const isScannedAppRootEntry = (name: string) => !name.startsWith(".") || appRootAllowedDirs.has(name);
+export const isScannedRootEntry = (type: SysType, name: string) =>
+  !name.startsWith(".") || rootAllowedDirs[type].has(name);