@akanjs/devkit 2.4.2-rc.3 → 3.0.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.4.2-rc.3",
+  "version": "3.0.0-alpha.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -44,10 +44,9 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.2-rc.3",
+    "akanjs": "3.0.0-alpha.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
-    "daisyui": "5.5.23",
     "dayjs": "^1.11.20",
     "fontaine": "^0.8.0",
     "fonteditor-core": "^2.6.3",

package/recipeScanner.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { collectRecipeSources, findInlineRecipeDuplicates, type RecipeInfo, scanRecipes } from "./recipeScanner";
+
+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";
+export const buttonRecipe = recipe(
+  tv({
+    base: "inline-flex items-center",
+    variants: {
+      variant: { primary: "bg-primary", ghost: "bg-transparent", link: "underline" },
+      size: { sm: "h-8", md: "h-10", lg: "h-12" },
+    },
+    defaultVariants: { variant: "primary", size: "md" },
+  }),
+);
+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";
+/** 전체 화면 배경/전경. 페이지 루트 컨테이너. */
+export const appScreen = recipe(tv({ base: "min-h-screen bg-background text-foreground" }));
+/** 챗 버블 — 수신/발신 방향에 따라 정렬·색을 바꾼다. */
+export const chatBubbleRecipe = recipe(
+  tv({ base: "max-w-[78%] rounded-3xl", variants: { side: { incoming: "bg-muted", outgoing: "ml-auto bg-primary" } }, defaultVariants: { side: "incoming" } }),
+);
+`;
+
+// A docs page: the ONLY real code is a layout div; a recipe "definition" lives inside a template-literal code sample.
+const DOCS_TSX = `
+import { Code } from "akanjs/ui";
+export default function Page() {
+  return (
+    <div>
+      <Code.Snippet code={\`export const fakeRecipe = recipe(tv({ base: "bg-primary", variants: { tone: { a: "x" } } }));\`} />
+    </div>
+  );
+}
+`;
+
+describe("scanRecipes", () => {
+  test("detects framework recipes with full variant surface", () => {
+    const recipes = scanRecipes([{ path: "recipe.ts", content: FRAMEWORK, importFrom: "akanjs/ui" }]);
+    expect(recipes.map((r) => r.name).sort()).toEqual(["badgeRecipe", "buttonRecipe"]);
+
+    const button = byName(recipes, "buttonRecipe");
+    expect(button?.importFrom).toBe("akanjs/ui");
+    expect(button?.variants.variant).toEqual(["primary", "ghost", "link"]);
+    expect(button?.variants.size).toEqual(["sm", "md", "lg"]);
+    expect(button?.defaultVariants).toEqual({ variant: "primary", size: "md" });
+
+    const badge = byName(recipes, "badgeRecipe");
+    expect(badge?.variants.variant).toEqual(["default", "info"]);
+    expect(badge?.defaultVariants).toBeUndefined();
+  });
+
+  test("handles base-only recipes and captures the JSDoc one-liner", () => {
+    const recipes = scanRecipes([{ path: "Recipe.ts", content: APP, importFrom: "@apps/minimal/ui" }]);
+
+    const screen = byName(recipes, "appScreen");
+    expect(screen?.variants).toEqual({}); // base-only → empty variant surface
+    expect(screen?.doc).toBe("전체 화면 배경/전경. 페이지 루트 컨테이너.");
+    expect(screen?.importFrom).toBe("@apps/minimal/ui");
+
+    const bubble = byName(recipes, "chatBubbleRecipe");
+    expect(bubble?.variants.side).toEqual(["incoming", "outgoing"]);
+    expect(bubble?.doc).toBe("챗 버블 — 수신/발신 방향에 따라 정렬·색을 바꾼다.");
+  });
+
+  test("does NOT match recipe definitions inside string/template literals (docs code samples)", () => {
+    const recipes = scanRecipes([{ path: "ui-recipe.tsx", content: DOCS_TSX, importFrom: "@apps/akan/ui" }]);
+    expect(recipes).toEqual([]);
+  });
+
+  test("skips recipe() calls whose argument is not tv(...)", () => {
+    const src = `export const x = recipe(buildStyles());\nexport const y = recipe(tv({ base: "a" }));`;
+    const recipes = scanRecipes([{ path: "f.ts", content: src, importFrom: "@x" }]);
+    expect(recipes.map((r) => r.name)).toEqual(["y"]);
+  });
+
+  test("ignores non-exported recipe consts and merges multiple sources", () => {
+    const src = `const hidden = recipe(tv({ base: "a" }));\nexport const shown = recipe(tv({ base: "b" }));`;
+    const recipes = scanRecipes([
+      { path: "a.ts", content: src, importFrom: "@a" },
+      { path: "b.ts", content: `export const other = recipe(tv({ base: "c" }));`, importFrom: "@b" },
+    ]);
+    expect(recipes.map((r) => `${r.name}@${r.importFrom}`).sort()).toEqual(["other@@b", "shown@@a"]);
+  });
+});
+
+// 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.
+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" }));`;
+  const THREE = `export const gridRecipe = recipe(tv({ base: "grid gap-3 xl:grid-cols-2" }));`;
+  const recipesOf = (src: string) => scanRecipes([{ path: "Recipe.ts", content: src, importFrom: "@apps/x/ui" }]);
+  const hits = (src: string, jsx: string) =>
+    findInlineRecipeDuplicates(recipesOf(src), [{ path: "Page.tsx", content: jsx }]).map((d) => d.recipe);
+
+  test("flags a verbatim re-author of the whole base", () => {
+    const jsx = `<div className="flex rounded-box border border-border bg-card p-4 text-card-foreground shadow-sm" />`;
+    expect(hits(EIGHT, jsx)).toEqual(["cardRecipe"]);
+  });
+
+  test("flags a near-copy that drops two tokens — the case the exact-match rule missed", () => {
+    const jsx = `<div className="flex rounded-box border border-border bg-card p-4" />`;
+    expect(hits(EIGHT, jsx)).toEqual(["cardRecipe"]);
+  });
+
+  test("ignores a className that merely shares a few generic utilities", () => {
+    expect(hits(EIGHT, `<div className="flex border p-4" />`)).toEqual([]);
+  });
+
+  test("still requires every token of a minimum-length fingerprint", () => {
+    expect(hits(THREE, `<div className="grid gap-3 xl:grid-cols-2" />`)).toEqual(["gridRecipe"]);
+    expect(hits(THREE, `<div className="grid gap-3" />`)).toEqual([]);
+  });
+
+  test("does not flag a className that consumes the recipe", () => {
+    expect(hits(EIGHT, `<div className={cardRecipe({}, "w-full")} />`)).toEqual([]);
+  });
+});
+
+describe("collectRecipeSources", () => {
+  const seed = async (files: Record<string, string>) => {
+    const root = await mkdtemp(path.join(tmpdir(), "akan-recipe-"));
+    for (const [rel, content] of Object.entries(files)) {
+      const abs = path.join(root, rel);
+      await Bun.write(abs, content);
+    }
+    return root;
+  };
+  const recipeSrc = (name: string) => `export const ${name} = recipe(tv({ base: "a" }));`;
+
+  test("reads every recipe file in the folder, skipping index and tests", async () => {
+    const root = await seed({
+      "ui/Recipe/index.ts": `export * from "./appCard";`,
+      "ui/Recipe/appCard.ts": recipeSrc("appCard"),
+      "ui/Recipe/appBox.ts": recipeSrc("appBox"),
+      "ui/Recipe/appBox.test.ts": recipeSrc("shouldBeSkipped"),
+      "ui/Recipe/notes.md": "ignored",
+    });
+    const sources = await collectRecipeSources(path.join(root, "ui"), "@apps/x/ui");
+    expect(sources).toHaveLength(2);
+    expect(
+      scanRecipes(sources)
+        .map((r) => r.name)
+        .sort(),
+    ).toEqual(["appBox", "appCard"]);
+  });
+
+  test("still reads a flat Recipe.ts so an unmigrated app keeps working", async () => {
+    const root = await seed({ "ui/Recipe.ts": recipeSrc("legacy") });
+    const sources = await collectRecipeSources(path.join(root, "ui"), "@apps/x/ui");
+    expect(scanRecipes(sources).map((r) => r.name)).toEqual(["legacy"]);
+  });
+
+  test("honours the framework's lowercase basename", async () => {
+    const root = await seed({ "ui/recipe/buttonRecipe.ts": recipeSrc("buttonRecipe") });
+    const sources = await collectRecipeSources(path.join(root, "ui"), "akanjs/ui", "recipe");
+    expect(scanRecipes(sources).map((r) => r.name)).toEqual(["buttonRecipe"]);
+  });
+
+  test("returns nothing when neither shape exists, without throwing", async () => {
+    const root = await mkdtemp(path.join(tmpdir(), "akan-recipe-"));
+    await writeFile(path.join(root, "placeholder"), "");
+    expect(await collectRecipeSources(path.join(root, "ui"), "@apps/x/ui")).toEqual([]);
+  });
+});

package/recipeScanner.ts

@@ -0,0 +1,233 @@
+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`).
+ */
+export interface RecipeInfo {
+  name: string;
+  importFrom: string;
+  variants: Record<string, string[]>;
+  defaultVariants?: Record<string, string>;
+  doc?: string;
+  /** The recipe's `base` class string when it is a plain string literal — the SSOT fingerprint. */
+  base?: string;
+}
+
+export interface RecipeSource {
+  path: string;
+  content: string;
+  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.
+ */
+export const collectRecipeSources = async (
+  uiDirPath: string,
+  importFrom: string,
+  basename = "Recipe",
+): Promise<RecipeSource[]> => {
+  const read = async (filePath: string): Promise<RecipeSource | null> => {
+    const content = await Bun.file(filePath)
+      .text()
+      .catch(() => "");
+    return content ? { path: filePath, content, importFrom } : null;
+  };
+  const flat = await read(`${uiDirPath}/${basename}.ts`);
+  const dirEntries = await readdir(`${uiDirPath}/${basename}`).catch(() => [] as string[]);
+  const fromDir = await Promise.all(
+    dirEntries
+      .filter((entry) => entry.endsWith(".ts") && entry !== "index.ts" && !/\.(test|spec)\.ts$/.test(entry))
+      .sort()
+      .map((entry) => read(`${uiDirPath}/${basename}/${entry}`)),
+  );
+  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).
+ */
+export const scanRecipes = (sources: RecipeSource[]): RecipeInfo[] => {
+  const recipes: RecipeInfo[] = [];
+  for (const source of sources) {
+    const sourceFile = ts.createSourceFile(
+      source.path,
+      source.content,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TSX,
+    );
+    for (const statement of sourceFile.statements) {
+      if (!ts.isVariableStatement(statement) || !isExported(statement)) continue;
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name) || !declaration.initializer) continue;
+        const parsed = parseRecipeCall(declaration.initializer);
+        if (!parsed) continue;
+        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) } : {}),
+          ...(parsed.base ? { base: parsed.base } : {}),
+        });
+      }
+    }
+  }
+  return recipes;
+};
+
+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 => {
+  if (!ts.isCallExpression(initializer)) return null;
+  if (!ts.isIdentifier(initializer.expression) || initializer.expression.text !== "recipe") return null;
+  const tvCall = initializer.arguments[0];
+  if (!tvCall || !ts.isCallExpression(tvCall)) return null;
+  if (!ts.isIdentifier(tvCall.expression) || tvCall.expression.text !== "tv") return null;
+  const config = tvCall.arguments[0];
+  if (!config || !ts.isObjectLiteralExpression(config)) return null;
+  return extractVariants(config);
+};
+
+const extractVariants = (config: ts.ObjectLiteralExpression) => {
+  const variants: Record<string, string[]> = {};
+  let defaultVariants: Record<string, string> | undefined;
+  let base: string | undefined;
+  for (const property of config.properties) {
+    if (!ts.isPropertyAssignment(property) || !isNamed(property.name)) continue;
+    const key = propName(property.name);
+    if (key === "base" && ts.isStringLiteral(property.initializer)) {
+      base = property.initializer.text;
+    } else if (key === "variants" && ts.isObjectLiteralExpression(property.initializer)) {
+      for (const variant of property.initializer.properties) {
+        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))
+          .map((option) => propName(option.name));
+      }
+    } else if (key === "defaultVariants" && ts.isObjectLiteralExpression(property.initializer)) {
+      defaultVariants = {};
+      for (const preset of property.initializer.properties) {
+        if (!ts.isPropertyAssignment(preset) || !isNamed(preset.name)) continue;
+        defaultVariants[propName(preset.name)] = ts.isStringLiteral(preset.initializer)
+          ? preset.initializer.text
+          : preset.initializer.getText();
+      }
+    }
+  }
+  return { variants, defaultVariants, base };
+};
+
+const isNamed = (name: ts.PropertyName): name is ts.Identifier | ts.StringLiteral =>
+  ts.isIdentifier(name) || ts.isStringLiteral(name);
+const propName = (name: ts.Identifier | ts.StringLiteral): string => name.text;
+
+export interface RecipeDuplicate {
+  recipe: string;
+  path: string;
+  line: number;
+  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.
+ */
+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.
+ */
+export const findInlineRecipeDuplicates = (
+  recipes: RecipeInfo[],
+  files: { path: string; content: string }[],
+): RecipeDuplicate[] => {
+  const fingerprints = recipes
+    .map((recipe) => ({ recipe: recipe.name, tokens: (recipe.base ?? "").split(/\s+/).filter(Boolean) }))
+    .filter((fingerprint) => fingerprint.tokens.length >= MIN_FINGERPRINT_TOKENS)
+    // Ceil so the threshold never rounds below the minimum: a 3-token base still needs 3 of 3.
+    .map((fingerprint) => ({ ...fingerprint, needed: Math.ceil(fingerprint.tokens.length * DUPLICATE_TOKEN_RATIO) }));
+  if (fingerprints.length === 0) return [];
+  const duplicates: RecipeDuplicate[] = [];
+  for (const file of files) {
+    const sourceFile = ts.createSourceFile(file.path, file.content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const visit = (node: ts.Node) => {
+      if (ts.isJsxAttribute(node) && node.name.getText(sourceFile) === "className" && node.initializer) {
+        for (const value of stringValuesIn(node.initializer)) {
+          const classSet = new Set(value.split(/\s+/));
+          for (const fingerprint of fingerprints) {
+            const matched = fingerprint.tokens.filter((token) => classSet.has(token)).length;
+            if (matched >= fingerprint.needed) {
+              const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+              duplicates.push({ recipe: fingerprint.recipe, path: file.path, line: line + 1, className: value });
+            }
+          }
+        }
+      }
+      node.forEachChild(visit);
+    };
+    visit(sourceFile);
+  }
+  return duplicates;
+};
+
+const stringValuesIn = (node: ts.Node): string[] => {
+  const values: string[] = [];
+  const visit = (child: ts.Node) => {
+    if (
+      ts.isStringLiteral(child) ||
+      ts.isNoSubstitutionTemplateLiteral(child) ||
+      ts.isTemplateHead(child) ||
+      ts.isTemplateMiddle(child) ||
+      ts.isTemplateTail(child)
+    )
+      values.push(child.text);
+    child.forEachChild(visit);
+  };
+  visit(node);
+  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;
+  const { pos, end } = ranges[ranges.length - 1];
+  const line = fullText
+    .slice(pos, end)
+    .replace(/^\/\*\*?/, "")
+    .replace(/\*\/\s*$/, "")
+    .replace(/^\/\/+/gm, "")
+    .split("\n")
+    .map((row) => row.replace(/^\s*\*\s?/, "").trim())
+    .find((row) => row.length > 0);
+  return line || undefined;
+};

package/scanInfo.ts

@@ -44,6 +44,9 @@ type DatabaseFileType = (typeof databaseFileTypes)[number];
 type ModuleKind = "database" | "service" | "scalar";
 
 const appRootAllowedFiles = new Set([
+  // 스코프 에이전트 가이드 — scan(write) 이 유지하는 색인 + 마커 밖 hand-written 내용 (agentsIndex.ts)
+  "AGENTS.md",
+  "CLAUDE.md",
   "akan.app.json",
   "akan.config.ts",
   "capacitor.config.ts",

package/transforms/externalizeFrameworkPlugin.ts

@@ -11,7 +11,7 @@ import type { App } from "../commandDecorators";
  *   - `packages: "external"` externalizes every bare specifier, including
  *     `@apps/*` / `@libs/*` — workspace packages that must stay bundled
  *     so the `"use client"` plugin can rewrite their exports — and ordinary
- *     npm dependencies like `dayjs` / `clsx`, which the production runtime
+ *     npm dependencies like `dayjs` / `tailwind-merge`, which the production runtime
  *     package.json does not install for the SSR pages artifact.
  *   - Top-level `external: [...]` applies to macro-time module resolution
  *     too; any `with { type: "macro" }` import chain that transitively
@@ -169,7 +169,7 @@ export async function createExternalizeFrameworkPlugin(options: ExternalizeFrame
           // that case directly.
           return undefined;
         }
-        // Everything else (ordinary npm dependencies like dayjs / clsx /
+        // Everything else (ordinary npm dependencies like dayjs / tailwind-merge /
         // immer) is bundled into the pages artifact.
         return undefined;
       });