@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/recipeScanner.test.ts

@@ -1,12 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { writeFile } from "node:fs/promises";
 import path from "node:path";
 import { collectRecipeSources, findInlineRecipeDuplicates, type RecipeInfo, scanRecipes } from "./recipeScanner";
+import { tempDirs } from "./testHelpers";
 
 const byName = (recipes: RecipeInfo[], name: string) => recipes.find((recipe) => recipe.name === name);
 
-// Mirrors pkgs/akanjs/ui/recipe/ (framework) — two recipes in one source, variant + size surfaces.
 // The scanner is per-source, so a folder of one-recipe files and a legacy multi-recipe file both parse.
 const FRAMEWORK = `
 import { recipe, tv } from "./recipeFactory";
@@ -24,7 +23,6 @@ export type ButtonVariants = NonNullable<Parameters<typeof buttonRecipe>[0]>;
 export const badgeRecipe = recipe(tv({ base: "rounded-full", variants: { variant: { default: "bg-muted", info: "bg-info" } } }));
 `;
 
-// Mirrors apps/minimal/ui/Recipe/ shapes — base-only (no variants) + single-variant, with per-export JSDoc.
 const APP = `
 import { recipe, tv } from "akanjs/ui";
 /** 전체 화면 배경/전경. 페이지 루트 컨테이너. */
@@ -97,12 +95,7 @@ describe("scanRecipes", () => {
   });
 });
 
-// Recipes moved from a flat `ui/Recipe.ts` to a `ui/Recipe/` folder. Three consumers (the AGENTS.md recipe
-// index, the recipeGate lint, the MCP module context) go through collectRecipeSources, and every one of them
-// degrades silently — empty list, no error — if it stops finding sources. These tests are that alarm.
-// The advisory exists to catch a look being re-authored inline. Requiring every base token only matched a
-// verbatim copy of the whole base — the one shape that never occurs in practice — so it reported nothing on
-// the near-copies it was built for, and silently, being advisory. These tests pin the ratio behaviour.
+// Requiring every base token matched only a verbatim copy, which never occurs; these tests pin the ratio instead.
 describe("findInlineRecipeDuplicates", () => {
   // 8 tokens → ceil(8 * 0.7) = 6 must be reproduced.
   const EIGHT = `export const cardRecipe = recipe(tv({ base: "flex rounded-box border border-border bg-card p-4 text-card-foreground shadow-sm" }));`;
@@ -135,9 +128,11 @@ describe("findInlineRecipeDuplicates", () => {
   });
 });
 
+// The AGENTS.md index, the recipeGate lint and the MCP module context all degrade silently if this finds nothing.
 describe("collectRecipeSources", () => {
+  const makeTempRoot = tempDirs("akan-recipe-");
   const seed = async (files: Record<string, string>) => {
-    const root = await mkdtemp(path.join(tmpdir(), "akan-recipe-"));
+    const root = await makeTempRoot();
     for (const [rel, content] of Object.entries(files)) {
       const abs = path.join(root, rel);
       await Bun.write(abs, content);
@@ -176,7 +171,7 @@ describe("collectRecipeSources", () => {
   });
 
   test("returns nothing when neither shape exists, without throwing", async () => {
-    const root = await mkdtemp(path.join(tmpdir(), "akan-recipe-"));
+    const root = await makeTempRoot();
     await writeFile(path.join(root, "placeholder"), "");
     expect(await collectRecipeSources(path.join(root, "ui"), "@apps/x/ui")).toEqual([]);
   });

package/recipeScanner.ts

@@ -1,11 +1,7 @@
 import { readdir } from "node:fs/promises";
 import ts from "typescript";
 
-/**
- * A single Akan UI recipe discovered by scanning source. `variants` maps each variant key to its allowed option
- * names (e.g. `{ variant: ["primary", "ghost"], size: ["sm", "md"] }`); a base-only recipe has `variants: {}`.
- * `importFrom` is the module a consumer imports the recipe from (e.g. `@apps/minimal/ui`).
- */
+/** `variants` maps each key to its option names (`{}` for a base-only recipe); `importFrom` is the consumer's module. */
 export interface RecipeInfo {
   name: string;
   importFrom: string;
@@ -22,13 +18,8 @@ export interface RecipeSource {
   importFrom: string;
 }
 
-/**
- * Collects every recipe source under a `ui` folder. Recipes live one-per-file in a `Recipe/` folder
- * (`recipe/` for the framework), so this reads the whole folder; the flat `Recipe.ts` is still read for
- * apps that have not moved yet. Every consumer of `scanRecipes` must go through here — three call sites
- * (AGENTS.md recipe index, `recipeGate` lint, MCP module context) hardcoded the flat path before, and each
- * one fails silently (empty list, no error) when the file is absent.
- */
+// One recipe per file under `Recipe/` (`recipe/` for the framework), plus the legacy flat `Recipe.ts`. Every
+// `scanRecipes` consumer goes through here: a hardcoded path fails silently (an empty list) when the file is absent.
 export const collectRecipeSources = async (
   uiDirPath: string,
   importFrom: string,
@@ -51,12 +42,8 @@ export const collectRecipeSources = async (
   return [flat, ...fromDir].filter((source): source is RecipeSource => !!source);
 };
 
-/**
- * Statically finds every `export const <name> = recipe(tv({ ... }))` across the given sources and extracts its
- * variant surface + leading JSDoc one-liner. Detection is by the `recipe(tv(...))` call shape (not by name suffix,
- * since base-only recipes like `appScreen` omit the `Recipe` suffix). Being AST-based, it never matches recipe
- * definitions that appear only inside string/template literals (e.g. code examples in docs pages).
- */
+// Detected by the `recipe(tv(...))` call shape, not the name suffix (base-only recipes like `appScreen` omit it);
+// AST-based, so code examples inside string literals never match.
 export const scanRecipes = (sources: RecipeSource[]): RecipeInfo[] => {
   const recipes: RecipeInfo[] = [];
   for (const source of sources) {
@@ -73,12 +60,13 @@ export const scanRecipes = (sources: RecipeSource[]): RecipeInfo[] => {
         if (!ts.isIdentifier(declaration.name) || !declaration.initializer) continue;
         const parsed = parseRecipeCall(declaration.initializer);
         if (!parsed) continue;
+        const doc = getLeadingDoc(source.content, statement);
         recipes.push({
           name: declaration.name.text,
           importFrom: source.importFrom,
           variants: parsed.variants,
           ...(parsed.defaultVariants ? { defaultVariants: parsed.defaultVariants } : {}),
-          ...(getLeadingDoc(source.content, statement) ? { doc: getLeadingDoc(source.content, statement) } : {}),
+          ...(doc ? { doc } : {}),
           ...(parsed.base ? { base: parsed.base } : {}),
         });
       }
@@ -90,7 +78,6 @@ export const scanRecipes = (sources: RecipeSource[]): RecipeInfo[] => {
 const isExported = (statement: ts.VariableStatement): boolean =>
   statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ?? false;
 
-/** Matches `recipe( tv( <ObjectLiteral> ) )` and returns the variant surface, or null for anything else. */
 const parseRecipeCall = (
   initializer: ts.Expression,
 ): { variants: Record<string, string[]>; defaultVariants?: Record<string, string>; base?: string } | null => {
@@ -148,27 +135,12 @@ export interface RecipeDuplicate {
   className: string;
 }
 
-/**
- * Fraction of a recipe's base tokens an inline className must reproduce to count as a duplicate.
- *
- * Requiring *every* token (the original rule) only caught a verbatim copy of the whole base, which is the one
- * form of duplication that essentially never happens: someone re-authoring a look reproduces the gist, not all
- * eight tokens. So the check passed on exactly the near-duplicates it existed to find, and silently — it is an
- * advisory, so nothing went red. A ratio catches those; false positives are cheap here for the same reason.
- */
+// A re-authored look reproduces the gist, not every token, so a ratio (not all tokens) catches near-duplicates.
 const DUPLICATE_TOKEN_RATIO = 0.7;
 
-/** Minimum base tokens for a recipe to be worth fingerprinting at all. */
 const MIN_FINGERPRINT_TOKENS = 3;
 
-/**
- * SSOT advisory: finds JSX `className` string values that hand-rewrite a recipe's base fingerprint instead of
- * consuming the recipe. Only recipes whose base has 3+ distinctive tokens are checked — shorter fingerprints
- * (`grid gap-3` …) are generic utilities and would flood the report with false positives. A className counts as
- * a duplicate once it reproduces {@link DUPLICATE_TOKEN_RATIO} of those tokens, so a near-copy that drops or
- * swaps one still reports. AST-scoped to real `className` attributes, so class strings inside doc-example
- * template literals never match.
- */
+// Shorter fingerprints (`grid gap-3`) are generic utilities that would flood the report with false positives.
 export const findInlineRecipeDuplicates = (
   recipes: RecipeInfo[],
   files: { path: string; content: string }[],
@@ -219,7 +191,6 @@ const stringValuesIn = (node: ts.Node): string[] => {
   return values;
 };
 
-/** The first non-empty line of the JSDoc/line comment immediately preceding the statement, markers stripped. */
 const getLeadingDoc = (fullText: string, node: ts.Node): string | undefined => {
   const ranges = ts.getLeadingCommentRanges(fullText, node.getFullStart());
   if (!ranges?.length) return undefined;

package/repoIdentity.ts

@@ -24,15 +24,8 @@ const readRemoteName = (workspaceRoot: string): string | null => {
   }
 };
 
-/**
- * The repository's own name.
- *
- * Deriving it from the working directory made every generated file that names the repo — the AGENTS.md title, its
- * `- Repo:` line — depend on what each person happened to call the folder they cloned into, so one commit rendered
- * a different guide per developer and the diff never settled. The origin remote is the one identity every clone
- * shares. `AKAN_PUBLIC_REPO_NAME` is deliberately not consulted: that is a deployment namespace (queue prefixes,
- * cache keys, secret paths) which a monorepo hosting several products legitimately points somewhere else.
- */
+// The origin remote, not the clone's folder name, so generated files agree across clones. `AKAN_PUBLIC_REPO_NAME` is a
+// deployment namespace (queue prefixes, cache keys) and deliberately not consulted.
 export const resolveRepoName = (workspaceRoot: string): string => {
   const cached = resolved.get(workspaceRoot);
   if (cached) return cached;

package/routeSourceValidator.test.ts

@@ -15,7 +15,6 @@ describe("RouteSourceValidator", () => {
       "export const reconnect = true;",
       "export const wsConnect = true;",
       "export const layoutStyle = {};",
-      'export const gaTrackingId = "G-1";',
     ].join("\n");
 
     expect(() => validate(source, "layout", true)).not.toThrow();

package/routeSourceValidator.ts

@@ -24,15 +24,8 @@ interface ChainStage {
 
 const chainRoots = new Set(["page", "layout", "rootLayout"]);
 
-/**
- * Static enforcement of the `page/` route conventions, split out of `executors.ts` so that importing
- * an executor does not pull `typescript` (+65MB resident) into the module graph. Both validators need
- * a real AST — modifier inspection, `export *` rejection, statement-kind walking and call-expression
- * identity — so `Bun.Transpiler.scan()`, which only reports export names, cannot replace them.
- *
- * Import it dynamically (`await import("./routeSourceValidator")`) so long-lived processes that never
- * validate a route source stay lean.
- */
+// Import dynamically: it pulls in `typescript` (+65MB resident). `Bun.Transpiler.scan()` reports only export names,
+// too little for these checks.
 export class RouteSourceValidator {
   static validateRouteSourceExports(
     source: string,
@@ -86,18 +79,6 @@ export class RouteSourceValidator {
     if (exported.has("head") && exported.has("generateHead")) {
       throw new Error(`[route-convention] head and generateHead cannot both be exported in ${filePath}`);
     }
-    if (
-      !options.rootLayout &&
-      (exported.has("head") || exported.has("generateHead")) &&
-      (exported.has("metadata") || exported.has("generateMetadata"))
-    ) {
-      throw new Error(
-        `[route-convention] head/generateHead and metadata/generateMetadata cannot both be exported in ${filePath}`,
-      );
-    }
-    if (exported.has("metadata") && exported.has("generateMetadata")) {
-      throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
-    }
     const chain = RouteSourceValidator.#readChain(sourceFile, filePath);
     if (!chain) return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };
     const named = [...exported].filter((name) => name !== "default");
@@ -116,12 +97,7 @@ export class RouteSourceValidator {
     };
   }
 
-  /**
-   * The default export as a `page()` / `layout()` / `rootLayout()` chain, or null when the module is the legacy
-   * shape. Read off the source for the same reason `devOnly` is: the build enumerates routes without importing
-   * them, and `akan sync` should name a `[projectId]` folder whose page declares no `.param("projectId")` before
-   * the first request does.
-   */
+  // Null for the legacy shape. Read off the source because the build enumerates routes without importing them.
   static #readChain(sourceFile: ts.SourceFile, filePath: string) {
     for (const statement of sourceFile.statements) {
       if (!ts.isExportAssignment(statement) || statement.isExportEquals) continue;
@@ -185,12 +161,8 @@ export class RouteSourceValidator {
       );
   }
 
-  /**
-   * `devOnly` decides whether the route exists in the production build at all, so it is read from the
-   * source rather than from an evaluated module — the build never imports route files to enumerate them.
-   * That is why only a literal is accepted: anything the parser cannot settle would otherwise ship a
-   * route the author believed was excluded.
-   */
+  // Only a literal is accepted: the build reads it without importing the route, and a value the parser cannot settle
+  // would ship a route its author believed excluded.
   static #readDevOnly(sourceFile: ts.SourceFile, filePath: string): boolean {
     for (const statement of sourceFile.statements) {
       if (!ts.isVariableStatement(statement)) continue;
@@ -234,13 +206,7 @@ export class RouteSourceValidator {
     return current;
   }
 
-  /**
-   * Statically enforces that a `_overrides.tsx` route file is a logic-free activation manifest: a plain module
-   * (no `"use client"` — the framework generates the client wrapper) that only imports components and binds them
-   * to slots through a single `export default override({ Modal: BrandModal })`. It must not declare components
-   * inline or run logic — that keeps the override contract a thin binding layer rather than a second place to
-   * author UI. Slot names and value types are validated at compile time by `override`.
-   */
+  // A logic-free manifest: imports plus one `export default override({ ... })`; `override` types the slots.
   static validateOverridesSourceExports(source: string, filePath: string) {
     const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
     const fail = (message: string): never => {
@@ -248,9 +214,8 @@ export class RouteSourceValidator {
     };
     let defaultOverride: ts.ExportAssignment | null = null;
     for (const statement of sourceFile.statements) {
-      // A "use client" directive is unnecessary (the framework wraps the manifest) but harmless if present.
+      //? A "use client" directive is unnecessary (the framework wraps the manifest) but harmless.
       if (ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)) continue;
-      // The manifest imports the app components it binds; imports and type-only decls carry no runtime logic.
       if (ts.isImportDeclaration(statement)) continue;
       if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) continue;
       if (ts.isExportAssignment(statement) && !statement.isExportEquals) {