@akanjs/devkit 3.0.0-alpha.5 → 3.0.0-alpha.51

package/lint/no-async-component-in-ui.grit

@@ -0,0 +1,35 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// React has no async client component: an async body is a server-only shape, so a `ui/` component that
+// awaits stops rendering the moment any client parent imports it — and `ui/` is written to be reachable
+// from both sides. It also moves the load below the route, where the framework can no longer start it
+// before the first byte. Awaiting belongs to `page/**`, which passes the resolved data down as props.
+//
+// Component-ness is a PascalCase regex on the binding, the same test `no-model-type-in-util-zone.grit`
+// uses. The declarator regex anchors `async` to the initializer position (`[^=]*` cannot cross an `=`),
+// so an async handler declared inside a synchronous component is not read as the component's own body;
+// `not within JsFunctionBody()` drops every nested declaration for the same reason. Out of scope by
+// construction, since neither is a named binding at statement level: an inline `onClick={async () => …}`
+// and an async member of an object literal.
+JsIdentifierBinding() as $name where {
+  $name <: r"[A-Z][A-Za-z0-9_$]*",
+  not $name <: within JsFunctionBody(),
+  not $name <: within JsFormalParameter(),
+  or {
+    $name <: within JsVariableDeclarator() as $decl where {
+      $decl <: r"[A-Z][A-Za-z0-9_$]*\s*(?::[^=]*)?=\s*async[\s\S]*"
+    },
+    $name <: within JsFunctionDeclaration() as $fn where {
+      $fn <: r"(?:export\s+)?(?:default\s+)?async\s+function[\s\S]*"
+    },
+    $name <: within JsFunctionExportDefaultDeclaration() as $default where {
+      $default <: r"(?:export\s+)?(?:default\s+)?async\s+function[\s\S]*"
+    }
+  },
+  register_diagnostic(
+    span = $name,
+    message = "An async component belongs in page/. React has no async client component, so a ui/ component that awaits breaks as soon as a client parent renders it, and the route can no longer start the load before the first byte. Await in the page — or hand an unawaited fetch.* to a Zone as an init / view prop — and take the resolved data as a prop.",
+    severity = "error"
+  )
+}

package/lint/no-daisyui-legacy-class.grit

@@ -2,19 +2,36 @@ engine biome(1.0)
 language js(typescript, jsx)
 
 // daisyUI was removed from the UI system; its component classes (`btn-primary`, `card-body`,
-// `mockup-code`, ...) no longer have any CSS behind them and silently render unstyled. Grit
-// port of styleGuard's `daisyui-legacy` rule (frontendBuild/styleGuard.ts) — keep in sync.
+// `mockup-code`, ...) and its colour slots (`bg-base-100`, `text-base-content`, `bg-error`)
+// no longer have any CSS behind them and silently render unstyled. Grit port of styleGuard's
+// `daisyui-legacy` rule (frontendBuild/styleGuard.ts) — keep in sync.
 // Only high-signal compound names are matched; bare ambiguous words that collide with
-// Tailwind or app classes (`card`, `input`, `badge`, `btn`) are deliberately not flagged.
+// Tailwind or app classes (`card`, `input`, `badge`, `btn`, `divider`) are deliberately not
+// flagged, and colour slots that survived into the semantic vocabulary (`primary`, `info`,
+// `success`, `warning`, `neutral`) are not either — only the slots the vocabulary dropped.
+// Biome keeps only the first diagnostic a single plugin registers on a node, so a string
+// carrying both halves reports the component one and surfaces the colour one on the next run.
 or {
   JsxString() as $s,
   JsStringLiteralExpression() as $s,
   JsTemplateChunkElement() as $s
 } where {
-  $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:btn-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|link|outline|square|circle|wide|block|xs|sm|md|lg)|badge-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|outline)|alert-(?:info|success|warning|error)|input-(?:bordered|primary|secondary|accent|ghost|error)|select-(?:bordered|primary|ghost)|textarea-(?:bordered|primary|ghost)|checkbox-(?:primary|secondary|accent)|toggle-(?:primary|secondary|accent)|loading-(?:spinner|dots|ring|ball|bars|infinity)|card-(?:body|title|actions)|modal-(?:box|action|backdrop)|collapse-(?:title|content|arrow|plus)|dropdown-(?:content|end|start|hover)|stat-(?:title|value|desc)|tabs-(?:boxed|lifted|bordered)|tab-active|menu-(?:title|dropdown)|steps-(?:horizontal|vertical)|join-item|mockup-(?:code|phone|browser|window)|drawer-(?:side|content|toggle))(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
-  register_diagnostic(
-    span = $s,
-    message = "daisyUI legacy class - daisyUI was removed, so this renders unstyled. Use akanjs/ui components and recipes (Button, buttonRecipe, badgeRecipe, ...) with semantic tokens instead.",
-    severity = "error"
-  )
+  any {
+    and {
+      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:btn-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|link|outline|square|circle|wide|block|xs|sm|md|lg)|badge-(?:primary|secondary|accent|neutral|info|success|warning|error|ghost|outline)|alert-(?:info|success|warning|error)|input-(?:bordered|primary|secondary|accent|ghost|error)|select-(?:bordered|primary|ghost)|textarea-(?:bordered|primary|ghost)|checkbox-(?:primary|secondary|accent)|toggle-(?:primary|secondary|accent)|loading-(?:spinner|dots|ring|ball|bars|infinity)|card-(?:body|title|actions)|modal-(?:box|action|backdrop)|collapse-(?:title|content|arrow|plus)|dropdown-(?:content|end|start|hover)|stat-(?:title|value|desc)|tabs-(?:boxed|lifted|bordered)|tab-active|menu-(?:title|dropdown)|steps-(?:horizontal|vertical)|join-item|mockup-(?:code|phone|browser|window)|drawer-(?:side|content|toggle))(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
+      register_diagnostic(
+        span = $s,
+        message = "daisyUI legacy class - daisyUI was removed, so this renders unstyled. Use akanjs/ui components and recipes (Button, buttonRecipe, badgeRecipe, ...) with semantic tokens instead.",
+        severity = "error"
+      )
+    },
+    and {
+      $s <: r"[\s\S]*(?:^|[\s\"'`{(\[:!])(?:bg|text|border(?:-[tblrxy])?(?:-[se])?|ring(?:-offset)?|fill|stroke|shadow|from|to|via|divide|outline|decoration|placeholder|caret|accent)-(?:base-(?:100|200|300|content)|(?:primary|secondary|accent|neutral|info|success|warning|error)-content|error)(?:[\s\"'`})\]:/!,]|$)[\s\S]*",
+      register_diagnostic(
+        span = $s,
+        message = "daisyUI colour slot - the closed colour vocabulary has no CSS for it, so this renders unstyled. base-100/200/300 -> background/muted/border, base-content -> foreground, <colour>-content -> <colour>-foreground, error -> destructive.",
+        severity = "error"
+      )
+    }
+  }
 }

package/lint/no-import-client-in-server.grit

@@ -0,0 +1,48 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Server files (*.document.ts, *.dictionary.ts, *.service.ts, *.signal.ts, srvkit/) and shared files
+// (common/, *.constant.ts) run in Bun with no DOM and no bundler, and every CLI command, worker, and
+// migration that loads a service loads whatever the service imports. Reaching into the client graph
+// pulls React, the store, and the browser globals they touch into that process, and it runs the
+// dependency backwards: the client entrypoint is built on top of cnst and sig, not the other way round.
+//
+// `import type` is erased before bundling and stays legal. A mixed value-and-type import is not exempt.
+or {
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: or {
+      r"\".*\.store\"",
+      r"\".*\.(?:Template|Unit|Util|View|Zone)\""
+    },
+    register_diagnostic(
+      span = $source,
+      message = "Client module. A server or shared file must not import a *.store or a module component (*.Template, *.Unit, *.Util, *.View, *.Zone) — server code reaches the model through cnst and db, never through client state or JSX.",
+      severity = "error"
+    )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: or {
+      r"\"(?:.*/)?(?:ui|webkit)(?:/.*)?\"",
+      r"\".*/client(?:/.*)?\""
+    },
+    register_diagnostic(
+      span = $source,
+      message = "Client entrypoint. A server or shared file must not import ui/, webkit/, or a package client entrypoint such as '@libs/<lib>/client' or 'akanjs/client' — import the server entrypoint or a common/ helper instead.",
+      severity = "error"
+    )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: r"\"(?:.*/)?(?:st|store|useClient)\"",
+    register_diagnostic(
+      span = $source,
+      message = "Client barrel. A server or shared file must not import st, store, or useClient — server code holds no client state, and Err comes from dict on the server.",
+      severity = "error"
+    )
+  }
+}

package/lint/no-import-server-in-client.grit

@@ -0,0 +1,45 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Client files (ui/, webkit/, page/, *.store.ts, every .tsx) and shared files (common/, *.constant.ts)
+// are compiled into the browser bundle, so a single value import of a server module drags its whole
+// graph along — the database driver, node:crypto, a secret resolved from process.env. The boundary has
+// to hold at the import statement, because by the call site the module is already bundled.
+//
+// `import type` is erased before bundling and stays legal, so a shared file may still name a server-side
+// type. A mixed value-and-type import is not exempt: it emits a real edge.
+or {
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: r"\".*\.(?:document|dictionary|service|signal)\"",
+    register_diagnostic(
+      span = $source,
+      message = "Server module. A client or shared file must not import a *.document, *.dictionary, *.service, or *.signal file — take the model from the package client entrypoint ('@libs/<lib>/client') or from its *.constant instead. Write 'import type' if only the type is needed.",
+      severity = "error"
+    )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: or {
+      r"\"(?:.*/)?srvkit(?:/.*)?\"",
+      r"\".*/server(?:/.*)?\""
+    },
+    register_diagnostic(
+      span = $source,
+      message = "Server entrypoint. A client or shared file must not import srvkit/ or a package server entrypoint such as '@apps/<app>/server' or 'akanjs/server' — import the matching client entrypoint instead.",
+      severity = "error"
+    )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport() as $import,
+    not $import <: r"import\s+type[\s\S]*",
+    $source <: r"\"(?:.*/)?(?:db|srv|sig|dict|option|useServer)\"",
+    register_diagnostic(
+      span = $source,
+      message = "Server barrel. A client or shared file must not import db, srv, sig, dict, option, or useServer — read models from cnst, state from st, and Err from the package client entrypoint.",
+      severity = "error"
+    )
+  }
+}

package/lint/no-model-type-in-util-zone.grit

@@ -0,0 +1,58 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// `Util` and `Zone` are always client components, so a *prop* typed as a `cnst` model is a hydrated
+// class instance the server has to hand across the boundary — the methods are stripped on the way and
+// what arrives is a plain object wearing the model's type.
+//
+// Only prop positions are reported: the component's `*Props` interface / type alias, or the inline
+// object type on its parameter. A `cnst` type anywhere else in the file never crosses the boundary and
+// stays legal — a local annotation, a callback parameter the framework already types with the model
+// (`renderItem`, `renderList`), a module-scope helper, a non-`Props` local shape, and the props of a
+// component nested inside another one. A function-typed prop is client-internal too: a closure cannot
+// cross the RSC boundary at all, so whoever passes it already holds the value it takes.
+//
+// The exempt generics are the framework props types whose model parameter never lands on a prop as
+// data: `ClientInit` / `ClientView` / `ClientEdit` (mapped to plain `GetStateObject`) and `ModelsProps`,
+// whose only use of the model is `onClickItem?: (model: M) => unknown` — a callback, so the caller
+// already holds the value. `ModelProps<"x", cnst.LightX>` is *not* exempt: it spreads the model onto
+// the props themselves.
+TsReferenceType() as $ref where {
+  $ref <: r"cnst\.[A-Za-z_$][A-Za-z0-9_$]*",
+  not $ref <: within TsIndexedAccessType() as $indexed where {
+    $indexed <: r"cnst\.[A-Za-z_$][A-Za-z0-9_$]*\[.value.\][\s\S]*"
+  },
+  not $ref <: within TsReferenceType() as $wrapper where {
+    $wrapper <: r"(?:(?:Client|Server)(?:Init|View|Edit)|ModelsProps)<[\s\S]*"
+  },
+  not $ref <: within TsFunctionType(),
+  or {
+    $ref <: within TsInterfaceDeclaration() as $propsInterface where {
+      $propsInterface <: r"interface\s+[A-Za-z0-9_$]*Props[\s\S]*"
+    },
+    $ref <: within TsTypeAliasDeclaration() as $propsAlias where {
+      $propsAlias <: r"type\s+[A-Za-z0-9_$]*Props[\s\S]*"
+    },
+    and {
+      $ref <: within JsFormalParameter(),
+      // A parameter is a sibling of the body, so this only drops the ones belonging to a function
+      // declared *inside* a component — a nested component or a local callback.
+      not $ref <: within JsFunctionBody(),
+      // Same for a callback handed straight to a call, which an expression-bodied component leaves
+      // outside every function body: `rows.map((row: cnst.LightTicket) => …)`.
+      not $ref <: within JsCallArguments(),
+      or {
+        $ref <: within JsVariableDeclarator() as $component where {
+          $component <: r"[A-Z][A-Za-z0-9_$]*[\s\S]*"
+        },
+        $ref <: within JsFunctionDeclaration() as $componentFn where {
+          $componentFn <: r"(?:async\s+)?function\s+[A-Z][A-Za-z0-9_$]*[\s\S]*"
+        }
+      }
+    }
+  },
+  register_diagnostic(
+    span = $ref,
+    message = "Util and Zone are client components, so a cnst model type on a prop is a class instance crossing the server boundary. Take an id instead (bannerId: string), or hand server data across as ClientInit / ClientView. An enum union such as cnst.AdminRole['value'] is allowed, and so is a cnst type that stays inside the file — a local annotation or a callback parameter."
+  )
+}

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/lint/no-unpublished-form-setter.grit

@@ -0,0 +1,41 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// A form control publishes its own setter by reading the action off the function it was handed
+// (`actionTagOf` in pkgs/akanjs/store/actionTag.ts). A setter passed by reference names the field it
+// writes, so the control emits `data-akan-action` and `useFieldTool` publishes the field to the in-page
+// agent. An arrow that only forwards its argument is a fresh anonymous closure carrying neither, so the
+// field silently becomes unreachable to the agent, to an E2E selector, and to the accessibility tree —
+// while looking identical to a reader. Generated field setters take exactly one value
+// (`makeFormSetter` in pkgs/akanjs/store/action.ts), so the wrapper never changes what runs.
+//
+// Only a pure forwarding body is reported: the argument reaches the setter unchanged, as the sole
+// statement. Each other shape has its own home, so none of them is reported here:
+//
+//   normalize  `(v) => set(formatPhone(v))`      -> the control's own `transform` prop, which every text and
+//                                                   number `Field.*` already takes. Keep `onChange` a reference.
+//   composite  `(v) => { set(v); other(v); }`    -> a `_postSet<Field>` method on the store, with the generated
+//                                                   setter left on the control. A generated action cannot be
+//                                                   overridden: mapped types make them properties (TS2425).
+//   nested     `(v) => writeOnX('a.3.b', v)`     -> unannotatable by design. An agent reaches an embedded row
+//                                                   through `fill<Model>Form`, which waves composites through.
+//
+// A typed parameter (`(v: string) => st.do.setVOnX(v)`) is not matched: the parameter and the argument
+// bind to different text, so the metavariable cannot unify them. Under-reporting, not a false positive.
+//
+JsxAttribute() as $attr where {
+  $attr <: contains JsArrowFunctionExpression() as $arrow,
+  $arrow <: `($p) => $body`,
+  // One bare parameter. A metavariable matches a whole parameter list leniently, so `(a, b)` binds the
+  // text "a, b" and is excluded here rather than by the snippet.
+  $p <: r"[A-Za-z_$][A-Za-z0-9_$]*",
+  $body <: contains `st.do.$action($p)` as $call,
+  $action <: r"set[A-Za-z0-9_$]*On[A-Za-z0-9_$]*",
+  // The body is that call and nothing else — `r"..."` is a full match, so an extra statement fails it.
+  $body <: r"\{?\s*(?:void\s+|await\s+)?st\.do\.[A-Za-z0-9_$]+\([A-Za-z_$][A-Za-z0-9_$]*\)\s*;?\s*\}?",
+  register_diagnostic(
+    span = $arrow,
+    message = "This arrow only forwards its argument, and an anonymous closure names no action — the control publishes no agent tool and emits no data-akan-action for the field. Pass the setter by reference: onChange={st.do.setTypeOnTicket}. A wrapper that does more is not reported: normalization belongs in the control's transform prop, a multi-write belongs in a _postSet<Field> hook on the store, and a nested path through writeOnX is reached by the agent through fill<Model>Form.",
+    severity = "error"
+  )
+}

package/linter.ts

@@ -58,19 +58,31 @@ interface LintResponse {
   warnings: LintMessage[];
 }
 
+/** Biome reads `biome.json` first and `biome.jsonc` second; only the latter may carry comments. */
+const BIOME_CONFIG_FILES = ["biome.json", "biome.jsonc"] as const;
+
 export class Linter {
   lintRoot: string;
+  configPath: string;
   #biomeBin: string;
 
   constructor(cwdPath: string) {
     this.lintRoot = this.#findBiomeRootPath(cwdPath);
+    this.configPath = Linter.#configPathIn(this.lintRoot) ?? path.join(this.lintRoot, "biome.json");
     const localBiomeBin = path.join(this.lintRoot, "node_modules/.bin/biome");
     this.#biomeBin = existsSync(localBiomeBin) ? localBiomeBin : "biome";
   }
 
+  static #configPathIn(dir: string): string | null {
+    for (const fileName of BIOME_CONFIG_FILES) {
+      const configPath = path.join(dir, fileName);
+      if (existsSync(configPath)) return configPath;
+    }
+    return null;
+  }
+
   #findBiomeRootPath(dir: string): string {
-    const configPath = path.join(dir, "biome.json");
-    if (existsSync(configPath)) return dir;
+    if (Linter.#configPathIn(dir)) return dir;
     const parentDir = path.dirname(dir);
     if (parentDir === dir) throw new Error(`biome.json not found from ${dir}`);
     return this.#findBiomeRootPath(parentDir);
@@ -193,7 +205,7 @@ export class Linter {
       "--max-diagnostics=none",
       "--no-errors-on-unmatched",
       "--config-path",
-      path.join(this.lintRoot, "biome.json"),
+      this.configPath,
       this.#toBiomePath(filePath),
     ]);
     const report = this.#parseBiomeReport(stdout || stderr);
@@ -390,14 +402,7 @@ export class Linter {
 
     const source = readFileSync(resolvedFilePath, "utf8");
     const { stdout } = await this.#runBiome(
-      [
-        "check",
-        "--write",
-        "--config-path",
-        path.join(this.lintRoot, "biome.json"),
-        "--stdin-file-path",
-        this.#toBiomePath(resolvedFilePath),
-      ],
+      ["check", "--write", "--config-path", this.configPath, "--stdin-file-path", this.#toBiomePath(resolvedFilePath)],
       source,
     );
     const lintResult = await this.lintFile(resolvedFilePath);
@@ -412,7 +417,7 @@ export class Linter {
   async getConfigForFile(filePath: string): Promise<unknown> {
     const resolvedFilePath = this.#resolveFilePath(filePath);
     if (!existsSync(resolvedFilePath)) throw new Error(`File not found: ${filePath}`);
-    return JSON.parse(readFileSync(path.join(this.lintRoot, "biome.json"), "utf8")) as unknown;
+    return JSON.parse(readFileSync(this.configPath, "utf8")) as unknown;
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.5",
+  "version": "3.0.0-alpha.51",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -14,7 +14,7 @@
     "directory": "pkgs/@akanjs/devkit"
   },
   "engines": {
-    "bun": ">=1.3.13"
+    "bun": ">=1.4.0"
   },
   "exports": {
     ".": {
@@ -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.5",
+    "akanjs": "3.0.0-alpha.51",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",
@@ -52,7 +53,6 @@
     "fonteditor-core": "^2.6.3",
     "ignore": "^7.0.5",
     "ink": "^6.8.0",
-    "js-yaml": "^4.1.1",
     "ora": "^9.4.0",
     "ssh2": "^1.17.0",
     "subset-font": "^2.5.0",

package/qualityScanner.test.ts

@@ -184,6 +184,15 @@ describe("AkanQualityScanner ssr rules", () => {
   });
 });
 
+const signalOf = (entries: string) =>
+  [
+    `import { endpoint, slice } from "akanjs/signal";`,
+    `export class PostSlice extends slice(srv.post, { guards: {}, mcp: { get: true } }, (init) => ({`,
+    entries,
+    `})) {}`,
+    "",
+  ].join("\n");
+
 describe("AkanQualityScanner layout rules", () => {
   test("flags an unknown app root file but not a facet entrypoint", async () => {
     const root = await makeWorkspace({
@@ -196,4 +205,47 @@ describe("AkanQualityScanner layout rules", () => {
     expect(warnings).toHaveLength(1);
     expect(warnings[0]?.file).toBe("apps/demo/helper.ts");
   });
+
+  test("flags an unknown lib root file but not a facet entrypoint", async () => {
+    const root = await makeWorkspace({
+      "libs/demo/client.ts": "export const client = 1;\n",
+      "libs/demo/helper.ts": "export const helper = 1;\n",
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.lib-root-file");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("libs/demo/helper.ts");
+  });
+
+  test("flags a root folder no facet owns, on both sides", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/base/helper.ts": "export const helper = 1;\n",
+      "apps/demo/common/helper.ts": "export const helper = 1;\n",
+      "libs/demo/base/helper.ts": "export const helper = 1;\n",
+      "libs/demo/common/helper.ts": "export const helper = 1;\n",
+    });
+
+    const result = await new AkanQualityScanner().scan(root);
+
+    expect(rulesOf(result, "akan.layout.app-root-folder").map((warning) => warning.file)).toEqual([
+      "apps/demo/base/helper.ts",
+    ]);
+    expect(rulesOf(result, "akan.layout.lib-root-folder").map((warning) => warning.file)).toEqual([
+      "libs/demo/base/helper.ts",
+    ]);
+  });
+
+  test("keeps a root signal test out of the lib facet rule", async () => {
+    const root = await makeWorkspace({
+      "libs/demo/lib/cnst.ts": "export const cnst = 1;\n",
+      "libs/demo/lib/user.signal.test.ts": "export const test = 1;\n",
+      "libs/demo/lib/helper.ts": "export const helper = 1;\n",
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.lib-facet-file");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("libs/demo/lib/helper.ts");
+  });
 });