@akanjs/devkit 3.0.0-alpha.11 → 3.0.0-alpha.111

package/qualityScanner.test.ts

@@ -193,185 +193,123 @@ const signalOf = (entries: string) =>
     "",
   ].join("\n");
 
-describe("AkanQualityScanner mcp rules", () => {
-  test("flags an exposed endpoint whose dictionary entry carries no desc", async () => {
+describe("AkanQualityScanner layout rules", () => {
+  test("flags an unknown app root file but not a facet entrypoint", async () => {
     const root = await makeWorkspace({
-      "libs/shared/lib/post/post.signal.ts": [
-        `import { endpoint } from "akanjs/signal";`,
-        `export class PostEndpoint extends endpoint(srv.post, ({ query }) => ({`,
-        `  publishPost: query(Boolean, { guards: [Admin], mcp: { expose: true } }).exec(() => true),`,
-        `  archivePost: query(Boolean, { guards: [Admin], mcp: { expose: true } }).exec(() => true),`,
-        `  quietPost: query(Boolean, { guards: [Admin] }).exec(() => true),`,
-        `})) {}`,
-        "",
-      ].join("\n"),
-      "libs/shared/lib/post/post.dictionary.ts": [
-        `export const dictionary = modelDictionary(["en", "ko"]).endpoint((fn) => ({`,
-        `  publishPost: fn(["Publish", "게시"]).desc(["Publishes a post", "글을 게시합니다"]),`,
-        `  archivePost: fn(["Archive", "보관"]).arg((t) => ({`,
-        `    postId: t(["Post", "글"]).desc(["Post to archive", "보관할 글"]),`,
-        `  })),`,
-        `}));`,
-        "",
-      ].join("\n"),
+      "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.mcp.missing-description");
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.app-root-file");
 
-    // `archivePost` describes only its argument, which says nothing about when to reach for the tool.
     expect(warnings).toHaveLength(1);
-    expect(warnings[0]?.message).toContain("archivePost");
-    expect(warnings[0]?.line).toBe(4);
-    expect(warnings[0]?.fix).toContain(".desc(");
+    expect(warnings[0]?.file).toBe("apps/demo/helper.ts");
   });
 
-  test("accepts a slice described on its own entry or on the endpoint it generates", async () => {
+  test("flags an unknown lib root file but not a facet entrypoint", async () => {
     const root = await makeWorkspace({
-      "libs/shared/lib/post/post.signal.ts": signalOf(
-        [
-          `  inPublic: init({ mcp: { expose: true } }).exec(function () { return this.postService.queryInPublic(); }),`,
-          `  inTag: init({ mcp: { expose: true } }).exec(function () { return this.postService.queryInTag(); }),`,
-          `  inDraft: init({ mcp: { expose: true } }).exec(function () { return this.postService.queryInDraft(); }),`,
-        ].join("\n"),
-      ),
-      "libs/shared/lib/post/post.dictionary.ts": [
-        `export const dictionary = modelDictionary(["en", "ko"])`,
-        `  .slice((fn) => ({`,
-        `    inPublic: fn(["In Public", "공개"]).desc(["Public posts", "공개된 글"]),`,
-        `    inTag: fn(["In Tag", "태그"]),`,
-        `    inDraft: fn(["In Draft", "초안"]),`,
-        `  }))`,
-        `  .endpoint((fn) => ({`,
-        `    postListInTag: fn(["Post List In Tag", "태그별 글"]).desc(["Posts under a tag", "태그에 속한 글"]),`,
-        `  }));`,
-        "",
-      ].join("\n"),
+      "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.mcp.missing-description");
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.layout.lib-root-file");
 
     expect(warnings).toHaveLength(1);
-    expect(warnings[0]?.message).toContain("inDraft");
+    expect(warnings[0]?.file).toBe("libs/demo/helper.ts");
   });
 
-  test("flags an exposure that declares no guards, whatever the slice call declared", async () => {
+  test("flags a root folder no facet owns, on both sides", async () => {
     const root = await makeWorkspace({
-      "libs/shared/lib/post/post.signal.ts": signalOf(
-        [
-          `  inPublic: init({ guards: [Public], mcp: { expose: true } }).exec(function () { return this.postService.queryInPublic(); }),`,
-          `  inTag: init({ mcp: { expose: true } }).exec(function () { return this.postService.queryInTag(); }),`,
-          `  inDraft: init({ ...sharedOption, mcp: { expose: true } }).exec(function () { return this.postService.queryInDraft(); }),`,
-        ].join("\n"),
-      ),
-      "libs/shared/lib/post/post.dictionary.ts": `export const dictionary = modelDictionary(["en", "ko"]);\n`,
+      "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 warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.mcp.unguarded-exposure");
+    const result = await new AkanQualityScanner().scan(root);
 
-    // `inPublic` decided; `inDraft` may have inherited a `guards` from the spread, so it is unreadable, not missing.
-    expect(warnings).toHaveLength(1);
-    expect(warnings[0]?.message).toContain("inTag");
-    expect(warnings[0]?.fix).toContain("guards: [Public]");
+    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("stays silent on a module that exposes nothing to MCP", async () => {
+  test("keeps a root signal test out of the lib facet rule", async () => {
     const root = await makeWorkspace({
-      "libs/shared/lib/post/post.signal.ts": signalOf(
-        `  inPublic: init().exec(function () { return this.postService.queryInPublic(); }),`,
-      ),
-      "libs/shared/lib/post/post.dictionary.ts": `export const dictionary = modelDictionary(["en", "ko"]);\n`,
+      "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",
     });
 
-    expect(rulesOf(await new AkanQualityScanner().scan(root), "akan.mcp.missing-description")).toHaveLength(0);
+    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");
   });
 });
 
-describe("AkanQualityScanner agent rules", () => {
-  const storeOf = (body: string) =>
-    [
-      `import { store } from "akanjs/store";`,
-      `export class PostStore extends store(sig.post, () => ({})) {`,
-      body,
-      `}`,
-      "",
-    ].join("\n");
-
-  test("flags only the actions whose endpoint description would be the wrong one", async () => {
-    const root = await makeWorkspace({
-      "libs/shared/lib/post/post.store.ts": storeOf(
-        [
-          // Named after the endpoint it calls, so it already reads as that endpoint's `.desc()`.
-          `  async publishPost(id: string) { await fetch.publishPost(id); }`,
-          // Renamed: the store name is the verb a user would say, the endpoint name is the verb the API has.
-          `  async archive(id: string) { await fetch.archivePost(id); }`,
-          // Two endpoints behind one action, so neither one's description covers it.
-          `  async publishAndTag(id: string) { await fetch.publishPost(id); await fetch.tagPost(id); }`,
-          // Never leaves the client, so it is not published and its description would be read by nobody.
-          `  toggleDraft() { this.set({ draft: !this.get().draft }); }`,
-        ].join("\n"),
-      ),
-      "libs/shared/lib/post/post.dictionary.ts": `export const dictionary = modelDictionary(["en", "ko"]);\n`,
-    });
+describe("bang comments in browser-reachable files", () => {
+  const bangWarningsIn = async (files: Record<string, string>) => {
+    const result = await new AkanQualityScanner().scan(await makeWorkspace(files));
+    return rulesOf(result, "akan.file.bang-comment-in-client");
+  };
 
-    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.agent.missing-store-description");
+  test("flags the first and last line, which the grit rule cannot reach", async () => {
+    const warnings = await bangWarningsIn({
+      "apps/demo/ui/First.tsx": "//! FIXME: broken\nexport const First = () => null;\n",
+      "apps/demo/ui/Last.tsx": "export const Last = () => null;\n//! left behind\n",
+    });
 
-    expect(warnings.map((warning) => warning.message)).toHaveLength(2);
-    expect(warnings[0]?.message).toContain("archive");
-    expect(warnings[0]?.message).toContain("archivePost()");
-    expect(warnings[1]?.message).toContain("publishAndTag");
-    expect(warnings[0]?.fix).toContain(".store()");
+    expect(warnings.map((warning) => `${warning.file}:${warning.line}`).sort()).toEqual([
+      "apps/demo/ui/First.tsx:1",
+      "apps/demo/ui/Last.tsx:2",
+    ]);
+    expect(warnings[0]?.fix).toContain("// FIXME:");
   });
 
-  test("accepts an action described on its own store entry or on a same-named endpoint", async () => {
-    const root = await makeWorkspace({
-      "libs/shared/lib/post/post.store.ts": storeOf(
-        [
-          `  async archive(id: string) { await fetch.archivePost(id); }`,
-          `  async logout() { await fetch.signoutUser(); }`,
-          `  async retire(id: string) { await fetch.archivePost(id); }`,
-        ].join("\n"),
+  test("flags the block form and a marker trailing code", async () => {
+    const warnings = await bangWarningsIn({
+      "apps/demo/lib/task/Task.Zone.tsx": ["/*! keep me */", "export const Zone = () => null; //! and me", ""].join(
+        "\n",
       ),
-      "libs/shared/lib/post/post.dictionary.ts": [
-        `export const dictionary = modelDictionary(["en", "ko"])`,
-        `  .endpoint((fn) => ({`,
-        // Not the endpoint it calls — an entry under the action's own name describes the action.
-        `    logout: fn(["Log Out", "로그아웃"]).desc(["Ends the session", "세션을 종료합니다"]),`,
-        `  }))`,
-        `  .store((t) => ({`,
-        `    archive: t(["Archive", "보관"]).desc(["Files the post away", "글을 보관합니다"]),`,
-        `    retire: t(["Retire", "폐기"]),`,
-        `  }));`,
-        "",
-      ].join("\n"),
     });
 
-    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.agent.missing-store-description");
-
-    // `retire` has an entry but no `.desc()`, which is a label and not a sentence an agent can act on.
-    expect(warnings).toHaveLength(1);
-    expect(warnings[0]?.message).toContain("retire");
+    expect(warnings.map((warning) => warning.line)).toEqual([1, 2]);
   });
 
-  test("stays quiet on a store with no custom actions, which is most of them", async () => {
-    const root = await makeWorkspace({
-      "libs/shared/lib/post/post.store.ts": storeOf(`  // action`),
-      "libs/shared/lib/post/post.dictionary.ts": `export const dictionary = modelDictionary(["en", "ko"]);\n`,
-    });
-
-    expect(rulesOf(await new AkanQualityScanner().scan(root), "akan.agent.missing-store-description")).toHaveLength(0);
+  test("ignores a double slash inside a string literal", async () => {
+    expect(
+      await bangWarningsIn({ "apps/demo/ui/Url.tsx": 'export const url = "https://host//!path";\n' }),
+    ).toHaveLength(0);
   });
-});
 
-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");
+  test("stays out of server files and tests", async () => {
+    const body = "//! server-only marker\nexport const value = 1;\n";
+    expect(
+      await bangWarningsIn({
+        "apps/demo/srvkit/storage.ts": body,
+        "apps/demo/lib/task/task.service.ts": body,
+        "apps/demo/ui/Card.test.tsx": body,
+        "apps/demo/lib/task/task.signal.spec.ts": body,
+      }),
+    ).toHaveLength(0);
+  });
 
-    expect(warnings).toHaveLength(1);
-    expect(warnings[0]?.file).toBe("apps/demo/helper.ts");
+  test("covers every path role the grit rule is scoped to", async () => {
+    const body = "//! marker\nexport const value = 1;\n";
+    const files = [
+      "apps/demo/ui/Card.tsx",
+      "apps/demo/webkit/useThing.tsx",
+      "apps/demo/common/format.ts",
+      "apps/demo/page/task/_index.tsx",
+      "apps/demo/lib/task/task.constant.ts",
+      "apps/demo/lib/task/task.store.ts",
+      "apps/demo/lib/task/Task.Unit.tsx",
+    ];
+    const warnings = await bangWarningsIn(Object.fromEntries(files.map((file) => [file, body])));
+
+    expect(warnings.map((warning) => warning.file).sort()).toEqual([...files].sort());
   });
 });

package/qualityScanner.ts

@@ -5,13 +5,12 @@ import { RESERVED_ROUTE_CONFIG_EXPORTS } from "akanjs/common";
 import ignore from "ignore";
 import ts from "typescript";
 import { AbstractDoc } from "./abstractDoc";
-import { McpScanner } from "./mcpScanner";
+import { FormSetterScanner } from "./formSetterScanner";
 import { formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
-import { StoreScanner } from "./storeScanner";
-import { appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
+import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
 
 type QualitySeverity = "warning";
-type QualityScope = "global" | "file" | "convention" | "layout" | "ssr" | "mcp" | "agent";
+type QualityScope = "global" | "file" | "convention" | "layout" | "ssr" | "agent";
 
 export interface QualityWarning {
   rule: string;
@@ -90,7 +89,8 @@ const SUGGESTED_RULES = [
   "Keep apps/*/lib and libs/*/lib root files limited to generated support facets such as cnst.ts, db.ts, dict.ts, sig.ts, srv.ts, st.ts, useClient.ts, and useServer.ts.",
   "Use domain module folders consistently: lib/<model> for database modules, lib/_<service> for service modules, and lib/__scalar/<scalar> for scalar modules.",
   "Keep module UI filenames predictable: database modules use <Model>.Template/Unit/Util/View/Zone.tsx, service modules use <Service>.Util/Zone.tsx, and scalar modules use <Scalar>.Template/Unit.tsx.",
-  "Move shared app utilities to apps/*/common instead of creating apps/*/base.",
+  "Hand a form control its store setter by reference so the field publishes an agent tool; put normalization in the control's transform prop and a multi-write in a _postSet<Field> hook on the store.",
+  "Move shared app and lib utilities to common/ instead of creating apps/*/base or libs/*/base.",
   "Avoid large mixed-purpose class files; class export files should import helpers from neighboring utility files instead of declaring them inline.",
 ];
 
@@ -117,6 +117,8 @@ const RULE_FIXES: Record<string, string> = {
     "Run `akan compact <app-or-lib>` to rewrite the abstract with the AI editor, keeping only the invariants and workflows the source files cannot show.",
   "akan.file.placeholder-export":
     "Remove the placeholder export; generated indexes should only re-export real modules.",
+  "akan.file.bang-comment-in-client":
+    "Rewrite the marker as `// FIXME:` or `// TODO:`. Keep the bang form for server, srvkit, and CLI files.",
   "akan.file.dictionary-stale-text": "Replace the scaffold text with real localized copy for this dictionary entry.",
   "akan.file.global-declaration":
     "Move the global declaration into an approved low-level integration file (e.g. webkit) and keep it isolated.",
@@ -124,14 +126,22 @@ const RULE_FIXES: Record<string, string> = {
     "Move the Window augmentation into an approved browser integration file and keep it isolated.",
   "akan.file.prototype-mutation": "Avoid prototype mutation, or isolate it in an approved low-level integration file.",
   "akan.file.class-export-global-declaration": "Move the helper to a sibling file and import it into the class module.",
+  "akan.agent.unpublished-form-setter":
+    "Pass the setter by reference where the wrapper only forwards (onChange={st.do.setTitleOnTask}); move normalization into the control's own transform prop; move a multi-write into a _postSet<Field> hook on the store, keeping the generated setter on the control.",
   "akan.file.component-internal-declaration":
     "Move the type or helper to a type/util file in ui/, webkit/, or common/ by purpose. If it is the component's props, declare it as `interface <Component>Props`.",
   "akan.file.component-export":
     "Move the value or type to a util/constant/type file in ui/, webkit/, or common/ and import it. Adding `export` is not a valid fix — only PascalCase components and their `<Component>Props` interface belong here.",
   "akan.layout.app-root-file":
     "Move the file into a conventional app folder (common, env, lib, page, private, public, script, srvkit, ui, or webkit).",
+  "akan.layout.app-root-folder":
+    "Move the folder's contents into a conventional app folder (common, env, lib, page, private, public, script, srvkit, ui, or webkit) and delete it.",
   "akan.layout.lib-root-file":
-    "Move the file into a domain module folder under lib/; keep lib root limited to generated support facets.",
+    "Move the file into a conventional lib folder (common, env, lib, page, private, public, srvkit, ui, or webkit).",
+  "akan.layout.lib-root-folder":
+    "Move the folder's contents into a conventional lib folder (common, env, lib, page, private, public, srvkit, ui, or webkit) and delete it.",
+  "akan.layout.lib-facet-file":
+    "Move the file into a domain module folder under lib/; keep the lib facet 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":
@@ -146,12 +156,6 @@ const RULE_FIXES: Record<string, string> = {
     "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}`.",
-  "akan.mcp.missing-description":
-    "Add `.desc([en, ko])` to this entry in the module's dictionary — for a slice, either on the slice entry or on the `<model>List<Slice>` endpoint it generates. Describe when to reach for it, not what it is named.",
-  "akan.agent.missing-store-description":
-    "Add the action to the module dictionary's `.store()` stage with a `.desc([en, ko])` saying what it does for the user — not what the endpoint it calls does. That stage is optional everywhere else: an action named after its endpoint already reads as that endpoint's description.",
-  "akan.mcp.unguarded-exposure":
-    "Name the guards in the same option object as `mcp`: `init({ guards: [SignedIn], mcp: { expose: true } })`. Write `guards: [Public]` if anonymous reads are the intent — the access is the same, but only one of the two is a decision. The `slice()` call's guards map reaches the root slice and base CRUD, never a named slice.",
 };
 
 function getRuleFix(rule: string): string | undefined {
@@ -181,9 +185,8 @@ export class AkanQualityScanner {
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
       ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
+      ...new FormSetterScanner().scan(sourceFiles),
       ...ssr.warnings,
-      ...new McpScanner().scan(sourceFiles),
-      ...new StoreScanner().scan(sourceFiles),
     ];
 
     return {
@@ -313,6 +316,7 @@ export class AkanQualityScanner {
       });
     }
 
+    warnings.push(...getBangCommentWarnings(sourceFile));
     warnings.push(...getPlaceholderExportWarnings(sourceFile));
     warnings.push(...getDictionaryTextWarnings(sourceFile));
     warnings.push(...getGlobalMutationWarnings(sourceFile));
@@ -418,26 +422,31 @@ export class AkanQualityScanner {
   }
 
   #scanLayoutQuality(sourceFile: SourceFileInfo): QualityWarning[] {
-    const segments = sourceFile.file.split("/");
     const warnings: QualityWarning[] = [];
-    if (segments[0] === "apps" && segments.length === 3 && !appRootAllowedFiles.has(segments[2])) {
-      warnings.push({
-        rule: "akan.layout.app-root-file",
-        scope: "layout",
-        severity: "warning",
-        file: sourceFile.file,
-        message: `Unexpected app root file "${segments[2]}". Keep application code in conventional app folders.`,
-      });
+    const rootEntry = getSysRootEntry(sourceFile.file);
+    if (rootEntry) {
+      const { type, name, isDir } = rootEntry;
+      const allowed = isDir ? rootAllowedDirs[type].has(name) : rootAllowedFiles[type].has(name);
+      const kind = isDir ? "folder" : "file";
+      if (!allowed) {
+        warnings.push({
+          rule: `akan.layout.${type}-root-${kind}`,
+          scope: "layout",
+          severity: "warning",
+          file: sourceFile.file,
+          message: `Unexpected ${type} root ${kind} "${name}". Keep ${type} code in conventional ${type} folders.`,
+        });
+      }
     }
 
-    const libRootFile = getLibRootFile(sourceFile.file);
-    if (libRootFile && !libFacetRootAllowedFiles.has(libRootFile)) {
+    const libFacetFile = getLibFacetRootFile(sourceFile.file);
+    if (libFacetFile && !isAllowedLibFacetRootFile(libFacetFile)) {
       warnings.push({
-        rule: "akan.layout.lib-root-file",
+        rule: "akan.layout.lib-facet-file",
         scope: "layout",
         severity: "warning",
         file: sourceFile.file,
-        message: `Unexpected lib root file "${libRootFile}". Keep direct lib root files limited to generated support facets.`,
+        message: `Unexpected lib facet root file "${libFacetFile}". Keep direct lib/ root files limited to generated support facets.`,
       });
     }
 
@@ -590,9 +599,10 @@ function isEnumClassStatement(sourceFile: ts.SourceFile, statement: ts.Statement
 
 function getExportedClassNames(sourceFile: ts.SourceFile) {
   return sourceFile.statements
-    .filter((statement): statement is ts.ClassDeclaration => ts.isClassDeclaration(statement) && !!statement.name)
+    .filter((statement): statement is ts.ClassDeclaration => ts.isClassDeclaration(statement))
     .filter((statement) => isExported(statement))
-    .map((statement) => statement.name!.text);
+    .map((statement) => statement.name?.text)
+    .filter((name): name is string => !!name);
 }
 
 function isComponentDeclarationFile(file: string) {
@@ -672,7 +682,43 @@ function isPascalCaseName(name: string) {
 
 function isDefaultExportStatement(statement: ts.Statement) {
   if (ts.isExportAssignment(statement)) return !statement.isExportEquals;
-  return !!(ts.getCombinedModifierFlags(statement as ts.Declaration) & ts.ModifierFlags.Default);
+  if (!ts.canHaveModifiers(statement)) return false;
+  return !!ts.getModifiers(statement)?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+}
+
+/**
+ * Bun's bundler keeps `//!` and `/*!` through minification (it reads them as the `@license` class), so a
+ * bang marker in browser-reachable code ships verbatim to every visitor. `no-bang-comment-in-client.grit`
+ * is the build gate; this exists because that rule cannot see the whole file.
+ *
+ * A comment is trivia, which Biome's GritQL exposes to no node pattern, so the rule matches through
+ * `file($name, $body)` — and `$body` is the module's *token* span. A marker above the first statement or
+ * below the last one sits in leading or trailing trivia and is unreachable from GritQL at all. Reading the
+ * raw text here covers both, and re-reporting the markers grit already catches costs nothing: the two run
+ * from different commands, and a file with one is failing lint either way.
+ */
+function getBangCommentWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
+  if (!isClientReachableFile(sourceFile.file)) return [];
+  // Anchored to line start or to whitespace after code, so a literal like `"https://host//!path"` is not a hit.
+  return findPatternLines(sourceFile.content, /(?:^|[^\s/][ \t]+)\/[*/]!/).map((line) => ({
+    rule: "akan.file.bang-comment-in-client",
+    scope: "file" as const,
+    severity: "warning" as const,
+    file: sourceFile.file,
+    line,
+    message: "A `//!` or `/*!` marker survives minification and ships to the browser.",
+  }));
+}
+
+/** Mirrors the path scope of `no-bang-comment-in-client.grit` in `biome.base.json`. */
+function isClientReachableFile(file: string) {
+  if (/\.(test|spec)\.tsx?$/.test(file)) return false;
+  if (/\.(constant|store)\.ts$/.test(file)) return true;
+  if (/\.(Template|Unit|Util|View|Zone)\.tsx$/.test(file)) return true;
+  const segments = file.split("/");
+  if (segments.includes("ui") || segments.includes("webkit")) return /\.tsx?$/.test(file);
+  if (segments.includes("common")) return file.endsWith(".ts");
+  return segments.includes("page") && file.endsWith(".tsx");
 }
 
 function getPlaceholderExportWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
@@ -831,7 +877,19 @@ function getConventionDescription(suffix: (typeof CONVENTION_SUFFIXES)[number],
   return `${modelName}Store`;
 }
 
-function getLibRootFile(file: string) {
+const sysRootTypes = { apps: "app", libs: "lib" } as const;
+
+function getSysRootEntry(file: string) {
+  const segments = file.split("/");
+  const root = segments[0];
+  const name = segments[2];
+  if (!root || !name || segments.length < 3) return null;
+  const type = sysRootTypes[root as keyof typeof sysRootTypes];
+  if (!type) return null;
+  return { type, name, isDir: segments.length > 3 };
+}
+
+function getLibFacetRootFile(file: string) {
   const segments = file.split("/");
   if ((segments[0] === "libs" || segments[0] === "apps") && segments.length === 4 && segments[2] === "lib")
     return segments[3];

package/recipeScanner.ts

@@ -118,7 +118,10 @@ const extractVariants = (config: ts.ObjectLiteralExpression) => {
         if (!ts.isPropertyAssignment(variant) || !isNamed(variant.name)) continue;
         if (!ts.isObjectLiteralExpression(variant.initializer)) continue;
         variants[propName(variant.name)] = variant.initializer.properties
-          .filter((option): option is ts.PropertyAssignment => ts.isPropertyAssignment(option) && isNamed(option.name))
+          .filter(
+            (option): option is ts.PropertyAssignment & { name: ts.Identifier | ts.StringLiteral } =>
+              ts.isPropertyAssignment(option) && isNamed(option.name),
+          )
           .map((option) => propName(option.name));
       }
     } else if (key === "defaultVariants" && ts.isObjectLiteralExpression(property.initializer)) {

package/routeSourceValidator.test.ts

@@ -39,3 +39,66 @@ describe("RouteSourceValidator", () => {
     });
   });
 });
+
+describe("RouteSourceValidator route chains", () => {
+  const chain = (source: string, kind: "page" | "layout", pattern: string) =>
+    RouteSourceValidator.validateRouteSourceExports(source, `page/${kind}.tsx`, kind, { pattern });
+
+  test("reads params, prompt and devOnly off a page() chain without evaluating it", () => {
+    const source = [
+      'import { page } from "akanjs/client";',
+      "export default page()",
+      '  .param("projectId", ID, { desc: "The project." })',
+      '  .search("status", String)',
+      "  .config({ transition: 'stack', devOnly: true })",
+      '  .prompt("briefProject", "Brief one project.")',
+      "  .render(async ({ projectId }) => null);",
+    ].join("\n");
+    expect(chain(source, "page", "/:lang/project/:projectId")).toEqual({
+      devOnly: true,
+      chain: { kind: "page", params: ["projectId"], prompt: "briefProject" },
+    });
+  });
+
+  test("names a [segment] the page did not declare and a .param() the path lacks", () => {
+    expect(() => chain("export default page().render(() => null);", "page", "/:lang/org/:orgId")).toThrow(
+      'sits under [orgId] but declares no .param("orgId")',
+    );
+    expect(() => chain('export default page().param("orgId", ID).render(() => null);', "page", "/:lang/org")).toThrow(
+      'declares .param("orgId") but no [orgId] segment is in its path',
+    );
+    expect(() =>
+      chain('export default page().param("lang", String).render(() => null);', "page", "/:lang/org"),
+    ).toThrow('declares .param("lang"), which every route receives undeclared');
+    // A layout may leave a segment undeclared.
+    expect(() =>
+      chain("export default layout().render(({ children }) => children);", "layout", "/:lang/org/:orgId"),
+    ).not.toThrow();
+  });
+
+  test("refuses named exports beside a chain, a chain in the wrong file kind, and a computed name", () => {
+    expect(() =>
+      chain(["export default page().render(() => null);", "export const pageConfig = {};"].join("\n"), "page", "/"),
+    ).toThrow("exports pageConfig beside its page() chain");
+    expect(() => chain("export default layout().render(() => null);", "page", "/")).toThrow(
+      "is a page file but exports layout()",
+    );
+    expect(() => chain("export default page().render(() => null);", "layout", "/")).toThrow(
+      "is a layout file but exports page()",
+    );
+    expect(() => chain("export default page().param(name, ID).render(() => null);", "page", "/:lang/:x")).toThrow(
+      ".param() takes a string literal first",
+    );
+    expect(() => chain("export default page().config({ devOnly: flag }).render(() => null);", "page", "/")).toThrow(
+      "devOnly must be a literal true or false",
+    );
+  });
+
+  test("still reads the legacy shape as before", () => {
+    const source = [
+      "export default function Page() { return null; }",
+      "export const pageConfig = { devOnly: false };",
+    ].join("\n");
+    expect(chain(source, "page", "/")).toEqual({ devOnly: false });
+  });
+});