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

package/biome.base.json

@@ -25,7 +25,7 @@
         "noArrayIndexKey": "off",
         "noShadowRestrictedNames": "off",
         "noUnnecessaryConditions": {
-          "level": "error"
+          "level": "warn"
         }
       },
       "correctness": {
@@ -117,7 +117,9 @@
         "libs/*/client.ts",
         "libs/*/server.ts",
         "libs/*/index.ts",
-        "libs/*/lib/*/index.tsx"
+        "libs/*/lib/*/index.tsx",
+        "apps/*/lib/__lib/**",
+        "libs/*/lib/__lib/**"
       ],
       "linter": { "enabled": false },
       "formatter": { "enabled": false },
@@ -140,26 +142,36 @@
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-throw-raw-error.grit"]
     },
     {
-      "includes": ["**/page/**/*.ts", "**/page/**/*.tsx", "**/*.Unit.tsx", "**/*.View.tsx"],
+      "includes": [
+        "{apps,libs}/**/page/**/*.ts",
+        "{apps,libs}/**/page/**/*.tsx",
+        "{apps,libs}/**/*.Unit.tsx",
+        "{apps,libs}/**/*.View.tsx"
+      ],
       "plugins": [
         "./node_modules/@akanjs/devkit/lint/no-import-client-functions.grit",
         "./node_modules/@akanjs/devkit/lint/no-use-client-in-server.grit"
       ]
     },
     {
-      "includes": ["**/page/**/*.ts", "**/page/**/*.tsx"],
+      "includes": ["{apps,libs}/**/page/**/*.ts", "{apps,libs}/**/page/**/*.tsx"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/non-scalar-props-restricted.grit"]
     },
     {
-      "includes": ["**/*.constant.ts", "**/*.document.ts", "**/*.service.ts", "**/*.store.ts"],
+      "includes": [
+        "{apps,libs}/**/*.constant.ts",
+        "{apps,libs}/**/*.document.ts",
+        "{apps,libs}/**/*.service.ts",
+        "{apps,libs}/**/*.store.ts"
+      ],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-js-private-class-method.grit"]
     },
     {
-      "includes": ["**/*.store.ts"],
+      "includes": ["{apps,libs}/**/*.store.ts"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-return-in-store-action.grit"]
     },
     {
-      "includes": ["**/*.signal.ts"],
+      "includes": ["{apps,libs}/**/*.signal.ts"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-redeclare-predefined-endpoint.grit"]
     },
     {
@@ -186,46 +198,46 @@
     },
     {
       "includes": [
-        "**/*.constant.ts",
-        "**/*.dictionary.ts",
-        "**/*.document.ts",
-        "**/*.service.ts",
-        "**/*.signal.ts",
-        "**/*.store.ts",
-        "**/*.Template.tsx",
-        "**/*.Unit.tsx",
-        "**/*.Util.tsx",
-        "**/*.View.tsx",
-        "**/*.Zone.tsx"
+        "{apps,libs}/**/*.constant.ts",
+        "{apps,libs}/**/*.dictionary.ts",
+        "{apps,libs}/**/*.document.ts",
+        "{apps,libs}/**/*.service.ts",
+        "{apps,libs}/**/*.signal.ts",
+        "{apps,libs}/**/*.store.ts",
+        "{apps,libs}/**/*.Template.tsx",
+        "{apps,libs}/**/*.Unit.tsx",
+        "{apps,libs}/**/*.Util.tsx",
+        "{apps,libs}/**/*.View.tsx",
+        "{apps,libs}/**/*.Zone.tsx"
       ],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-deep-internal-import.grit"]
     },
     {
       "includes": [
-        "**/page/**/*.ts",
-        "**/page/**/*.tsx",
-        "**/index.ts",
-        "**/index.tsx",
-        "**/cnst.ts",
-        "**/db.ts",
-        "**/dict.ts",
-        "**/option.ts",
-        "**/sig.ts",
-        "**/srv.ts",
-        "**/st.ts",
-        "**/*.constant.ts",
-        "**/*.dictionary.ts",
-        "**/*.document.ts",
-        "**/*.service.ts",
-        "**/*.signal.ts",
-        "**/*.signal.test.ts",
-        "**/*.service.test.ts",
-        "**/*.store.ts",
-        "**/*.Template.tsx",
-        "**/*.Unit.tsx",
-        "**/*.Util.tsx",
-        "**/*.View.tsx",
-        "**/*.Zone.tsx"
+        "{apps,libs}/**/page/**/*.ts",
+        "{apps,libs}/**/page/**/*.tsx",
+        "{apps,libs}/**/index.ts",
+        "{apps,libs}/**/index.tsx",
+        "{apps,libs}/**/cnst.ts",
+        "{apps,libs}/**/db.ts",
+        "{apps,libs}/**/dict.ts",
+        "{apps,libs}/**/option.ts",
+        "{apps,libs}/**/sig.ts",
+        "{apps,libs}/**/srv.ts",
+        "{apps,libs}/**/st.ts",
+        "{apps,libs}/**/*.constant.ts",
+        "{apps,libs}/**/*.dictionary.ts",
+        "{apps,libs}/**/*.document.ts",
+        "{apps,libs}/**/*.service.ts",
+        "{apps,libs}/**/*.signal.ts",
+        "{apps,libs}/**/*.signal.test.ts",
+        "{apps,libs}/**/*.service.test.ts",
+        "{apps,libs}/**/*.store.ts",
+        "{apps,libs}/**/*.Template.tsx",
+        "{apps,libs}/**/*.Unit.tsx",
+        "{apps,libs}/**/*.Util.tsx",
+        "{apps,libs}/**/*.View.tsx",
+        "{apps,libs}/**/*.Zone.tsx"
       ],
       "plugins": [
         "./node_modules/@akanjs/devkit/lint/no-import-external-library.grit",

package/frontendBuild/cssCompiler.ts

@@ -46,6 +46,10 @@ export class CssCompiler {
   #fileExistsCache = new Map<string, Promise<boolean>>();
   #resolvedFileCache = new Map<string, Promise<string | null>>();
   #resolvedSpecifierCache = new Map<string, Promise<string | null>>();
+  /** Every stylesheet this compile reached, entry points and `@import` targets alike. */
+  #discoveredCssPaths = new Set<string>();
+  /** `@import` targets of the compile in progress, by path, so the output can be checked against them. */
+  #importedStylesheets = new Map<string, string>();
 
   #fileExists(absPath: string): Promise<boolean> {
     let cached = this.#fileExistsCache.get(absPath);
@@ -76,13 +80,16 @@ export class CssCompiler {
   }
   async getCss({ refresh }: { refresh?: boolean } = {}) {
     if (this.#cssText !== null && !refresh) return this.#cssText;
+    this.#discoveredCssPaths.clear();
     const { cssPaths, sourcePaths } = await this.discoverCssAndSources({ refresh });
     this.#cssText = await this.compileCss(cssPaths, sourcePaths);
+    await this.#warnUnreachableStylesheets();
     return this.#cssText;
   }
 
   async getCssByBasePath({ refresh }: { refresh?: boolean } = {}): Promise<Record<string, string>> {
     if (this.#cssTextByBasePath !== null && !refresh) return this.#cssTextByBasePath;
+    this.#discoveredCssPaths.clear();
     const akanConfig = await this.#app.getConfig({ refresh });
     const pageKeys = await this.#app.getPageKeys({ refresh });
     const basePaths = [...akanConfig.basePaths];
@@ -111,9 +118,26 @@ export class CssCompiler {
       }),
     ]);
     this.#cssTextByBasePath = Object.fromEntries(cssEntries);
+    await this.#warnUnreachableStylesheets();
     return this.#cssTextByBasePath;
   }
 
+  /**
+   * A stylesheet under `page/` reaches the build only by being imported from a route source. One that nothing
+   * imports compiles to nothing and reports success, which is indistinguishable from an empty theme — so say it
+   * out loud once per compile rather than leaving it to be noticed as unstyled elements in the browser.
+   */
+  async #warnUnreachableStylesheets() {
+    const pageDir = path.join(this.#app.cwdPath, "page");
+    const glob = new Bun.Glob("**/*.css");
+    for await (const cssPath of glob.scan({ cwd: pageDir, absolute: true })) {
+      // `(libs)` is a link farm: the same file is discovered under its real path in `libs/`, never this one.
+      if (cssPath.includes(`${path.sep}(libs)${path.sep}`)) continue;
+      if (this.#discoveredCssPaths.has(cssPath)) continue;
+      this.#logger.warn(`css ${path.relative(this.#app.cwdPath, cssPath)} is imported by no route and never compiled`);
+    }
+  }
+
   async discoverCss({ refresh }: { refresh?: boolean } = {}): Promise<string[]> {
     const { cssPaths } = await this.discoverCssAndSources({ refresh });
     return cssPaths;
@@ -180,11 +204,38 @@ export class CssCompiler {
       }
     }
 
-    return { cssPaths: [...cssFiles], sourcePaths: [...sourceFiles] };
+    const tokenPaths = await this.#libTokenStylesheets(sourceFiles);
+    const cssPaths = [...new Set([...tokenPaths, ...cssFiles])];
+    for (const cssPath of cssPaths) this.#discoveredCssPaths.add(cssPath);
+    return { cssPaths, sourcePaths: [...sourceFiles] };
+  }
+
+  /**
+   * `libs/<lib>/ui/tokens.css` of every lib the page graph reached, so a lib can own the fixed colours its own
+   * components need instead of each consuming app re-declaring them. Ordered ahead of the app's stylesheets:
+   * the app is the last word on any variable both declare.
+   */
+  async #libTokenStylesheets(sourceFiles: Set<string>): Promise<string[]> {
+    const libsRoot = path.join(this.#app.workspace.workspaceRoot, "libs");
+    const libNames = new Set<string>();
+    for (const filePath of sourceFiles) {
+      const relPath = path.relative(libsRoot, filePath);
+      if (relPath.startsWith("..") || path.isAbsolute(relPath)) continue;
+      const [libName] = relPath.split(path.sep);
+      if (libName) libNames.add(libName);
+    }
+    const tokenPaths = await Promise.all(
+      [...libNames].sort().map(async (libName) => {
+        const tokensPath = path.join(libsRoot, libName, "ui/tokens.css");
+        return (await this.#fileExists(tokensPath)) ? tokensPath : null;
+      }),
+    );
+    return tokenPaths.filter((tokensPath): tokensPath is string => !!tokensPath);
   }
   async compileCss(cssPaths: string[], sourcePaths: string[]): Promise<string> {
     if (cssPaths.length === 0) return "";
 
+    this.#importedStylesheets.clear();
     const compileStarted = Date.now();
     const compilers = await Promise.all(
       cssPaths.map(async (cssPath) => {
@@ -217,17 +268,47 @@ export class CssCompiler {
     this.#logger.verbose(
       `css compiled paths=${cssPaths.length} candidates=${candidates.length} in ${Date.now() - compileStarted}ms`,
     );
-    return parts.join("\n");
+    const css = parts.join("\n");
+    this.#warnDroppedImports(css);
+    return css;
+  }
+
+  /**
+   * An `@import` can resolve, be read, and still contribute nothing — the one failure the existence check
+   * cannot see, and the one that reads as an unstyled component rather than as an error. Custom properties
+   * declared outside `@theme` are the tell: those pass through verbatim, so a stylesheet whose every
+   * declaration is missing from the build did not make it in.
+   */
+  #warnDroppedImports(css: string) {
+    for (const [cssPath, content] of this.#importedStylesheets) {
+      const names = declaredCustomProperties(content);
+      if (names.length === 0 || names.some((name) => css.includes(`${name}:`))) continue;
+      this.#logger.warn(
+        `css @import ${cssPath} was loaded but none of its ${names.length} declaration(s) reached the compiled CSS`,
+      );
+    }
   }
 
   async #loadStylesheet(id: string, fromBase: string) {
     const p = await this.#resolveCssImport(id, fromBase);
+    this.#discoveredCssPaths.add(p);
     const content = await Bun.file(p).text();
+    this.#importedStylesheets.set(p, content);
+    this.#logger.verbose(`css import "${id}" from ${fromBase} -> ${p} (${content.length} bytes)`);
     return { path: p, base: path.dirname(p), content };
   }
 
+  /**
+   * Every specifier is verified here, path-shaped ones included. An `@import` the pipeline cannot resolve is
+   * a build error and never a no-op: the vocabulary closure means a component whose token declaration failed
+   * to load renders unstyled, which nothing downstream can distinguish from a design choice.
+   */
   async #resolveCssImport(id: string, fromBase: string): Promise<string> {
-    if (id.startsWith(".") || id.startsWith("/")) return path.resolve(fromBase, id);
+    if (id.startsWith(".") || id.startsWith("/")) {
+      const filePath = path.resolve(fromBase, id);
+      if (await this.#fileExists(filePath)) return filePath;
+      throw new Error(`[css] failed to resolve stylesheet import "${id}" from ${fromBase} (no file at ${filePath})`);
+    }
     const resolver = await this.#getCssImportResolver();
     const resolved = await resolver.resolve(id, fromBase);
     if (resolved) return resolved;
@@ -330,6 +411,17 @@ export function isIgnoredNodeModuleSource(filePath: string): boolean {
   return NODE_MODULES_RE.test(filePath) && !AKANJS_NODE_MODULE_RE.test(filePath);
 }
 
+/**
+ * `@theme` blocks are stripped first: those variables are emitted only when a utility uses one, so their
+ * absence from a build says nothing about whether the stylesheet arrived.
+ */
+export function declaredCustomProperties(css: string): string[] {
+  const withoutThemeBlocks = css.replace(/@theme[^{]*\{[^}]*\}/g, "");
+  return [...new Set([...withoutThemeBlocks.matchAll(/(?:^|[\s;{])(--[\w-]+)\s*:/g)].map(([, name]) => name))].filter(
+    (name): name is string => !!name,
+  );
+}
+
 function getPageKeyBasePath(pageKey: string, basePaths: string[]): string | null {
   const normalized = pageKey.split(path.sep).join("/").replace(/^\.\//, "");
   const segments = normalized.split("/");

package/frontendBuild/cssImportResolver.ts

@@ -106,14 +106,15 @@ export class CssImportResolver {
       const pkg = await Bun.file(pkgPath).json();
       const subpath = id === pkgName ? "." : `.${id.slice(pkgName.length)}`;
       const exportValue = pkg.exports?.[subpath];
-      const styleEntry =
-        (typeof exportValue === "string"
+      const exportedEntry =
+        typeof exportValue === "string"
           ? exportValue
-          : exportValue?.style || exportValue?.import || exportValue?.default) ||
-        pkg.exports?.["."]?.style ||
-        pkg.style ||
-        "index.css";
-      return await this.#firstExisting(path.resolve(pkgDir, styleEntry));
+          : exportValue?.style || exportValue?.import || exportValue?.default;
+      if (exportedEntry) return await this.#firstExisting(path.resolve(pkgDir, exportedEntry));
+      //* A subpath names a file inside the package, so it resolves literally. Falling back to the package's own
+      //* style entry here would load a different stylesheet than the author asked for and report success.
+      if (subpath !== ".") return await this.#firstExisting(path.resolve(pkgDir, subpath));
+      return await this.#firstExisting(path.resolve(pkgDir, pkg.exports?.["."]?.style || pkg.style || "index.css"));
     } catch {
       return null;
     }

package/frontendBuild/frontendBuild.test.ts

@@ -5,7 +5,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { RoutesManifest } from "akanjs/server";
 import { CsrArtifactBuilder } from "./csrArtifactBuilder";
-import { CssCompiler, isIgnoredNodeModuleSource } from "./cssCompiler";
+import { CssCompiler, declaredCustomProperties, isIgnoredNodeModuleSource } from "./cssCompiler";
 import { CssImportResolver } from "./cssImportResolver";
 import { DevChangePlanner } from "./devChangePlanner";
 import { DevGeneratedIndexSync } from "./devGeneratedIndexSync";
@@ -391,6 +391,20 @@ describe("CssImportResolver", () => {
     expect(await resolver.resolve("@libs/ui/missing", root)).toBeNull();
   });
 
+  test("never substitutes the package stylesheet for a subpath that does not exist", async () => {
+    const root = await makeTempRoot();
+    await write(
+      path.join(root, "node_modules/vendor/package.json"),
+      JSON.stringify({ name: "vendor", style: "index.css" }),
+    );
+    await write(path.join(root, "node_modules/vendor/index.css"), ".vendor {}\n");
+
+    const resolver = new CssImportResolver(root, {});
+
+    expect(await resolver.resolve("vendor", root)).toBe(path.join(root, "node_modules/vendor/index.css"));
+    expect(await resolver.resolve("vendor/ui/tokens.css", root)).toBeNull();
+  });
+
   test("resolves css from single-package Akan workspace subpaths", async () => {
     const root = await makeTempRoot();
     await write(path.join(root, "pkgs/akanjs/ui/styles.css"), "body {}\n");
@@ -428,4 +442,55 @@ describe("CssCompiler", () => {
 
     expect(css).toContain(".text-fuchsia-500");
   });
+
+  test("reads declarations that prove a stylesheet arrived, ignoring theme variables that may not", () => {
+    expect(declaredCustomProperties(":root { --kakao: #fee500; --naver: #1ec800; }")).toEqual(["--kakao", "--naver"]);
+    expect(declaredCustomProperties("@theme inline {\n  --color-brand: var(--brand);\n}\n")).toEqual([]);
+    expect(declaredCustomProperties("@theme { --color-x: initial; }\n:root { --brand: #111; }")).toEqual(["--brand"]);
+    expect(declaredCustomProperties(".a { color: var(--kakao); }")).toEqual([]);
+    expect(declaredCustomProperties(":root{--a:#111}\n@media (min-width:1px){:root{--a:#222;--b:#333}}")).toEqual([
+      "--a",
+      "--b",
+    ]);
+  });
+
+  test("fails loudly on a stylesheet import that resolves to nothing", async () => {
+    const root = await makeTempRoot();
+    const cssPath = path.join(root, "apps/demo/page/styles.css");
+    await write(cssPath, '@import "../../../libs/shared/ui/tokens.css";\n');
+
+    const compiler = new CssCompiler({
+      workspace: { workspaceRoot: root },
+      cwdPath: path.join(root, "apps/demo"),
+      getTsConfig: async () => ({ compilerOptions: { paths: {} } }),
+    } as never);
+
+    await expect(compiler.compileCss([cssPath], [])).rejects.toThrow(
+      /failed to resolve stylesheet import "\.\.\/\.\.\/\.\.\/libs\/shared\/ui\/tokens\.css"/,
+    );
+  });
+
+  test("compiles lib-owned tokens ahead of the app stylesheets that may override them", async () => {
+    const root = await makeTempRoot();
+    const appDir = path.join(root, "apps/demo");
+    await write(
+      path.join(appDir, "page/_index.tsx"),
+      'import "./styles.css";\nimport { Card } from "@libs/shared/ui";\nexport default () => <Card />;\n',
+    );
+    await write(path.join(appDir, "page/styles.css"), ":root { --brand: #111111; }\n");
+    await write(path.join(root, "libs/shared/ui/index.ts"), "export const Card = () => null;\n");
+    await write(path.join(root, "libs/shared/ui/tokens.css"), ":root { --kakao: #fee500; }\n");
+    await write(path.join(root, "libs/unused/ui/tokens.css"), ":root { --unused: #000000; }\n");
+
+    const compiler = new CssCompiler({
+      workspace: { workspaceRoot: root },
+      cwdPath: appDir,
+      getPageKeys: async () => ["./_index.tsx"],
+      getConfig: async () => ({ barrelImports: [] }),
+      getTsConfig: async () => ({ compilerOptions: { paths: { "@libs/*": ["./libs/*"] } } }),
+    } as never);
+    const { cssPaths } = await compiler.discoverCssAndSources();
+
+    expect(cssPaths).toEqual([path.join(root, "libs/shared/ui/tokens.css"), path.join(appDir, "page/styles.css")]);
+  });
 });

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/mcpScanner.ts

@@ -0,0 +1,217 @@
+import path from "node:path";
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+
+interface ExposedDeclaration {
+  name: string;
+  kind: "endpoint" | "slice";
+  line: number;
+  /** `unknown` when the option object holds a spread, where a `guards` key may arrive from somewhere unreadable. */
+  guards: "declared" | "missing" | "unknown";
+}
+
+/**
+ * Checks the two things about an MCP exposure that source alone can answer: that it carries a description an agent
+ * can act on, and that somebody decided who may call it.
+ *
+ * A tool's name and argument names are the only other thing a model sees, and neither says what the tool is for
+ * or when to reach for it. An undescribed tool is not merely undocumented — it is a tool the model will either
+ * skip or call wrongly, so this rides with the exposure decision rather than with general dictionary hygiene.
+ *
+ * Guards are here because the omission is *syntactic*: the `guards` key sits in the same option literal as
+ * `mcp: { expose: true }`, and a named slice inherits nothing from the `slice()` call's own guards map. So the
+ * shape that publishes an unguarded read without anyone writing it down is visible in the file, with no resolved
+ * types needed — which is what makes it worth checking here rather than only in a boot log.
+ *
+ * The generated CRUD a slice opts in through `mcp: { get: true }` is checked by neither rule: none of those
+ * entries has text of its own to leave out, so each borrows the model's — the `.of()` label as a title, the model
+ * `.desc()` appended to the framework's "Get X" as a description — and each takes the `slice()` guards map, which
+ * is the one place those guards do reach.
+ *
+ * It reads source, so it finds `mcp: { expose: true }` only where an author writes it as a literal inside the
+ * `slice(` / `endpoint(` call — an option hoisted to a `const`, or an `expose: flag`, is invisible to it. Right
+ * for a warning that must not fire on something it merely failed to resolve, but it makes a clean scan "nothing
+ * obviously wrong" rather than "everything exposed is described and guarded". The complete answer is the boot log:
+ * `McpRouter.report()` holds the resolved catalogue and names every published entry with no description and every
+ * one with no guards, generated entries included — and the refusals, which turn on a resolved return type and so
+ * are the one class this file could never see.
+ */
+export class McpScanner {
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    const dictionaries = new Map(
+      sourceFiles
+        .filter((sourceFile) => sourceFile.file.endsWith(".dictionary.ts"))
+        .map((sourceFile) => [path.dirname(sourceFile.file), sourceFile]),
+    );
+    return sourceFiles
+      .filter((sourceFile) => sourceFile.file.endsWith(".signal.ts"))
+      .flatMap((sourceFile) => this.#scanSignal(sourceFile, dictionaries.get(path.dirname(sourceFile.file))));
+  }
+
+  #scanSignal(signal: SourceFileInfo, dictionary: SourceFileInfo | undefined): QualityWarning[] {
+    const exposed = McpScanner.#exposedDeclarations(signal);
+    if (!exposed.length) return [];
+    const refName = path.basename(signal.file, ".signal.ts").replace(/^_+/, "");
+    const described = dictionary ? McpScanner.#describedEntries(dictionary) : new Map<string, Set<string>>();
+    return [
+      ...exposed
+        .filter(({ name, kind }) => !McpScanner.#isDescribed(described, refName, name, kind))
+        .map(({ name, kind, line }) => ({
+          rule: "akan.mcp.missing-description",
+          scope: "mcp" as const,
+          severity: "warning" as const,
+          file: signal.file,
+          line,
+          message: `MCP-exposed ${kind} "${name}" has no dictionary .desc(); an agent sees its name and nothing else.`,
+        })),
+      ...exposed
+        .filter(({ guards }) => guards === "missing")
+        .map(({ name, kind, line }) => ({
+          rule: "akan.mcp.unguarded-exposure",
+          scope: "mcp" as const,
+          severity: "warning" as const,
+          file: signal.file,
+          line,
+          message: `MCP-exposed ${kind} "${name}" declares no guards; a slice's guards map never reaches a named slice.`,
+        })),
+    ];
+  }
+
+  static #isDescribed(described: Map<string, Set<string>>, refName: string, name: string, kind: string) {
+    if (described.get(kind)?.has(name)) return true;
+    // A slice may instead be described through the endpoint it generates, which is how a dictionary that wants
+    // separate wording for the list reads (`bannerListInPublic`).
+    return kind === "slice" && !!described.get("endpoint")?.has(`${refName}List${McpScanner.#capitalize(name)}`);
+  }
+
+  /** Names declared with `mcp: { expose: true }`, keyed by whether they sit in the slice or endpoint builder. */
+  static #exposedDeclarations(signal: SourceFileInfo): ExposedDeclaration[] {
+    const found: ExposedDeclaration[] = [];
+    const visit = (node: ts.Node) => {
+      if (McpScanner.#isExposeOption(node)) {
+        const declaration = McpScanner.#enclosingDeclaration(node, signal.sourceFile);
+        if (declaration) found.push(declaration);
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(signal.sourceFile);
+    return found;
+  }
+
+  static #isExposeOption(node: ts.Node) {
+    if (!ts.isPropertyAssignment(node) || McpScanner.#propertyName(node) !== "mcp") return false;
+    if (!ts.isObjectLiteralExpression(node.initializer)) return false;
+    return node.initializer.properties.some(
+      (property) =>
+        ts.isPropertyAssignment(property) &&
+        McpScanner.#propertyName(property) === "expose" &&
+        property.initializer.kind === ts.SyntaxKind.TrueKeyword,
+    );
+  }
+
+  /**
+   * The name is the property holding the builder chain the option sits in — `inCategory: init({ mcp })…` or
+   * `echoTitle: builder.query(String, { mcp })…` — and the kind is the factory that property is declared inside.
+   * Reading the kind from the factory rather than from the chain's first identifier keeps it right when a slice
+   * callback names its parameter something other than `init`.
+   */
+  static #enclosingDeclaration(option: ts.Node, sourceFile: ts.SourceFile): ExposedDeclaration | null {
+    let declaration: ts.PropertyAssignment | null = null;
+    for (let node = option.parent; node; node = node.parent) {
+      if (!declaration && ts.isPropertyAssignment(node)) {
+        declaration = node;
+        continue;
+      }
+      const kind = McpScanner.#factoryKind(node);
+      if (!kind || !declaration) continue;
+      const name = McpScanner.#propertyName(declaration);
+      if (!name) return null;
+      const line = sourceFile.getLineAndCharacterOfPosition(declaration.getStart(sourceFile)).line + 1;
+      return { name, kind, line, guards: McpScanner.#guardState(option) };
+    }
+    return null;
+  }
+
+  /**
+   * Read off the literal the `mcp` option sits in, which is the same literal `guards` belongs to — `init({ guards,
+   * mcp })`, `query(cnst.X, { guards, mcp })`. A spread in there makes the answer unreadable rather than missing,
+   * and a warning that fires on what it merely failed to resolve is worse than one that stays quiet.
+   */
+  static #guardState(option: ts.Node): ExposedDeclaration["guards"] {
+    const options = option.parent;
+    if (!ts.isObjectLiteralExpression(options)) return "unknown";
+    if (options.properties.some((property) => ts.isSpreadAssignment(property))) return "unknown";
+    return options.properties.some(
+      (property) => ts.isPropertyAssignment(property) && McpScanner.#propertyName(property) === "guards",
+    )
+      ? "declared"
+      : "missing";
+  }
+
+  static #factoryKind(node: ts.Node): ExposedDeclaration["kind"] | null {
+    if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return null;
+    const factory = node.expression.text;
+    return factory === "slice" || factory === "endpoint" ? factory : null;
+  }
+
+  /** Entry names that carry a `.desc()`, per dictionary stage. */
+  static #describedEntries(dictionary: SourceFileInfo): Map<string, Set<string>> {
+    const described = new Map<string, Set<string>>();
+    const visit = (node: ts.Node) => {
+      const stage = McpScanner.#dictionaryStage(node);
+      if (stage) {
+        for (const [name, chain] of McpScanner.#stageEntries(node as ts.CallExpression)) {
+          if (!chain.has("desc")) continue;
+          const names = described.get(stage) ?? new Set<string>();
+          names.add(name);
+          described.set(stage, names);
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(dictionary.sourceFile);
+    return described;
+  }
+
+  static #dictionaryStage(node: ts.Node) {
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return null;
+    const stage = node.expression.name.text;
+    return stage === "endpoint" || stage === "slice" ? stage : null;
+  }
+
+  static #stageEntries(stage: ts.CallExpression): Array<[string, Set<string>]> {
+    const callback = stage.arguments[0];
+    if (!callback || !ts.isArrowFunction(callback)) return [];
+    const body = ts.isParenthesizedExpression(callback.body) ? callback.body.expression : callback.body;
+    if (!ts.isObjectLiteralExpression(body)) return [];
+    return body.properties.flatMap((property) => {
+      if (!ts.isPropertyAssignment(property)) return [];
+      const name = McpScanner.#propertyName(property);
+      return name ? [[name, McpScanner.#chainCalls(property.initializer)] as [string, Set<string>]] : [];
+    });
+  }
+
+  /**
+   * Only the calls on the entry's own chain. A nested `.arg((t) => ({ x: t([…]).desc([…]) }))` describes an
+   * argument, not the entry, so a subtree walk would read every entry as described.
+   */
+  static #chainCalls(expression: ts.Expression): Set<string> {
+    const calls = new Set<string>();
+    let current: ts.Node = expression;
+    while (ts.isCallExpression(current) || ts.isPropertyAccessExpression(current)) {
+      if (ts.isPropertyAccessExpression(current)) calls.add(current.name.text);
+      current = current.expression;
+    }
+    return calls;
+  }
+
+  static #propertyName(property: ts.PropertyAssignment) {
+    const { name } = property;
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
+    return null;
+  }
+
+  static #capitalize(value: string) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.10",
+  "version": "3.0.0-alpha.12",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -45,7 +45,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.10",
+    "akanjs": "3.0.0-alpha.12",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/qualityScanner.test.ts

@@ -184,6 +184,184 @@ 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 mcp rules", () => {
+  test("flags an exposed endpoint whose dictionary entry carries no desc", 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"),
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.mcp.missing-description");
+
+    // `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(");
+  });
+
+  test("accepts a slice described on its own entry or on the endpoint it generates", 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"),
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.mcp.missing-description");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("inDraft");
+  });
+
+  test("flags an exposure that declares no guards, whatever the slice call declared", 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`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.mcp.unguarded-exposure");
+
+    // `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]");
+  });
+
+  test("stays silent on a module that exposes nothing to MCP", 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`,
+    });
+
+    expect(rulesOf(await new AkanQualityScanner().scan(root), "akan.mcp.missing-description")).toHaveLength(0);
+  });
+});
+
+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`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.agent.missing-store-description");
+
+    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()");
+  });
+
+  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"),
+      ),
+      "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");
+  });
+
+  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);
+  });
+});
+
 describe("AkanQualityScanner layout rules", () => {
   test("flags an unknown app root file but not a facet entrypoint", async () => {
     const root = await makeWorkspace({

package/qualityScanner.ts

@@ -5,11 +5,13 @@ 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 { formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
+import { StoreScanner } from "./storeScanner";
 import { appRootAllowedFiles, libFacetRootAllowedFiles } from "./workspaceLayout";
 
 type QualitySeverity = "warning";
-type QualityScope = "global" | "file" | "convention" | "layout" | "ssr";
+type QualityScope = "global" | "file" | "convention" | "layout" | "ssr" | "mcp" | "agent";
 
 export interface QualityWarning {
   rule: string;
@@ -144,6 +146,12 @@ 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 {
@@ -174,6 +182,8 @@ export class AkanQualityScanner {
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
       ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
       ...ssr.warnings,
+      ...new McpScanner().scan(sourceFiles),
+      ...new StoreScanner().scan(sourceFiles),
     ];
 
     return {

package/storeScanner.ts

@@ -0,0 +1,173 @@
+import path from "node:path";
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+
+interface CustomAction {
+  name: string;
+  line: number;
+  /** The endpoints this action calls as `fetch.<name>`. Empty means it never leaves the client. */
+  fetched: string[];
+}
+
+/**
+ * Checks that a store action an agent can reach says what it does, in the one place this codebase lets it.
+ *
+ * A store is the surface an in-page agent drives — it reads state through `st.use.*` and acts through `st.do.*` —
+ * and an action's name and argument types are the only other thing it sees. Unlike a signal, a store has no
+ * builder metadata and no room for prose: the house rules ban JSDoc, and every string a person reads goes through
+ * `l()`. So the dictionary's `.store()` stage is the only legal channel for the sentence, and this is the check
+ * that it exists where it is actually needed.
+ *
+ * Three kinds of action are deliberately quiet, because a warning nobody should act on teaches people to ignore
+ * the rest:
+ *
+ *  - **Generated actions** (`createX`, `setFieldOnX`, `initXInY`, …) are not in the file at all. Their wording is
+ *    derived from the model's own labels, so there is nothing for an author to write.
+ *  - **An action that calls no `fetch.*`** stays on the client and is not published, so its description would be
+ *    read by nobody.
+ *  - **An action named after the endpoint it calls** already reads as that endpoint's `.desc()`. That is most of
+ *    them, and not by accident — the naming rule is that `st.do.X` reads the same as `fetch.X`.
+ *
+ * What is left is the case where inheriting would be *wrong* rather than merely absent: nine `getSummaryListIn*`
+ * actions that all call one `summaryListInPeriod`, where the difference between them is the whole point of having
+ * nine; or `logout` over `signoutUser`, where the store name is the verb a user would say and the endpoint name is
+ * the verb the API has. Those are the ones a person has to write.
+ *
+ * It reads source, so an action that reaches its endpoint through anything but a literal `fetch.<name>` — a
+ * destructured `fetch`, a helper, a computed key — reads as calling none and stays quiet. Right for a warning that
+ * must not fire on what it merely failed to resolve.
+ */
+export class StoreScanner {
+  scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    const dictionaries = new Map(
+      sourceFiles
+        .filter((sourceFile) => sourceFile.file.endsWith(".dictionary.ts"))
+        .map((sourceFile) => [path.dirname(sourceFile.file), sourceFile]),
+    );
+    return sourceFiles
+      .filter((sourceFile) => sourceFile.file.endsWith(".store.ts"))
+      .flatMap((sourceFile) => this.#scanStore(sourceFile, dictionaries.get(path.dirname(sourceFile.file))));
+  }
+
+  #scanStore(store: SourceFileInfo, dictionary: SourceFileInfo | undefined): QualityWarning[] {
+    const actions = StoreScanner.#customActions(store);
+    if (!actions.length) return [];
+    const described = dictionary ? StoreScanner.#describedEntries(dictionary) : new Map<string, Set<string>>();
+    return actions
+      .filter(({ name, fetched }) => fetched.length && !fetched.includes(name))
+      .filter(({ name }) => !described.get("store")?.has(name) && !described.get("endpoint")?.has(name))
+      .map(({ name, line, fetched }) => ({
+        rule: "akan.agent.missing-store-description",
+        scope: "agent" as const,
+        severity: "warning" as const,
+        file: store.file,
+        line,
+        message: `Store action "${name}" calls ${fetched.map((key) => `${key}()`).join(", ")} under a different name and has no dictionary .store() entry, so an agent reading it has the name and nothing else.`,
+      }));
+  }
+
+  /** Methods written in the store class body. Generated actions never appear here, which is why they are exempt. */
+  static #customActions(store: SourceFileInfo): CustomAction[] {
+    const actions: CustomAction[] = [];
+    const visit = (node: ts.Node) => {
+      if (ts.isClassDeclaration(node) && StoreScanner.#extendsStore(node)) {
+        for (const member of node.members) {
+          // A getter computes rather than dispatches, and a static helper is not on `st.do` at all.
+          if (!ts.isMethodDeclaration(member)) continue;
+          if (member.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.StaticKeyword)) continue;
+          const name = StoreScanner.#memberName(member);
+          if (!name) continue;
+          const line = store.sourceFile.getLineAndCharacterOfPosition(member.getStart(store.sourceFile)).line + 1;
+          actions.push({ name, line, fetched: StoreScanner.#fetchedEndpoints(member) });
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(store.sourceFile);
+    return actions;
+  }
+
+  static #extendsStore(node: ts.ClassDeclaration) {
+    return !!node.heritageClauses?.some((clause) =>
+      clause.types.some((type) => ts.isCallExpression(type.expression) && StoreScanner.#isStoreCall(type.expression)),
+    );
+  }
+
+  static #isStoreCall(expression: ts.CallExpression) {
+    return ts.isIdentifier(expression.expression) && expression.expression.text === "store";
+  }
+
+  /** The `fetch.<name>` calls inside one action, which is what says whether it is reachable past the client. */
+  static #fetchedEndpoints(member: ts.MethodDeclaration): string[] {
+    const fetched = new Set<string>();
+    const visit = (node: ts.Node) => {
+      if (
+        ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        ts.isIdentifier(node.expression.expression) &&
+        node.expression.expression.text === "fetch"
+      )
+        fetched.add(node.expression.name.text);
+      ts.forEachChild(node, visit);
+    };
+    visit(member);
+    return [...fetched];
+  }
+
+  /** Entry names that carry a `.desc()`, per dictionary stage. */
+  static #describedEntries(dictionary: SourceFileInfo): Map<string, Set<string>> {
+    const described = new Map<string, Set<string>>();
+    const visit = (node: ts.Node) => {
+      const stage = StoreScanner.#dictionaryStage(node);
+      if (stage) {
+        for (const [name, chain] of StoreScanner.#stageEntries(node as ts.CallExpression)) {
+          if (!chain.has("desc")) continue;
+          const names = described.get(stage) ?? new Set<string>();
+          names.add(name);
+          described.set(stage, names);
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(dictionary.sourceFile);
+    return described;
+  }
+
+  static #dictionaryStage(node: ts.Node) {
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return null;
+    const stage = node.expression.name.text;
+    return stage === "store" || stage === "endpoint" ? stage : null;
+  }
+
+  static #stageEntries(stage: ts.CallExpression): Array<[string, Set<string>]> {
+    const callback = stage.arguments[0];
+    if (!callback || !ts.isArrowFunction(callback)) return [];
+    const body = ts.isParenthesizedExpression(callback.body) ? callback.body.expression : callback.body;
+    if (!ts.isObjectLiteralExpression(body)) return [];
+    return body.properties.flatMap((property) => {
+      if (!ts.isPropertyAssignment(property)) return [];
+      const name = StoreScanner.#memberName(property);
+      return name ? [[name, StoreScanner.#chainCalls(property.initializer)] as [string, Set<string>]] : [];
+    });
+  }
+
+  /**
+   * Only the calls on the entry's own chain. A nested `.arg((t) => ({ x: t([…]).desc([…]) }))` describes an
+   * argument, not the entry, so a subtree walk would read every entry as described.
+   */
+  static #chainCalls(expression: ts.Expression): Set<string> {
+    const calls = new Set<string>();
+    let current: ts.Node = expression;
+    while (ts.isCallExpression(current) || ts.isPropertyAccessExpression(current)) {
+      if (ts.isPropertyAccessExpression(current)) calls.add(current.name.text);
+      current = current.expression;
+    }
+    return calls;
+  }
+
+  static #memberName(member: ts.MethodDeclaration | ts.PropertyAssignment) {
+    const { name } = member;
+    if (!name || (!ts.isIdentifier(name) && !ts.isStringLiteral(name))) return null;
+    return name.text;
+  }
+}