@akanjs/devkit 2.3.11-rc.1 → 2.3.11-rc.10

package/firebaseMessagingSw.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createFirebaseMessagingServiceWorker,
+  normalizeFirebaseClientConfig,
+} from "./firebaseMessagingSw";
+
+describe("normalizeFirebaseClientConfig", () => {
+  test("whitelists client fields and drops secrets / vapidKey", () => {
+    const normalized = normalizeFirebaseClientConfig({
+      apiKey: "public-api-key",
+      authDomain: "example.firebaseapp.com",
+      projectId: "public-project",
+      storageBucket: "public-project.appspot.com",
+      messagingSenderId: "1234567890",
+      appId: "public-app-id",
+      vapidKey: "public-vapid-key",
+      private_key: "SERVER_PRIVATE_KEY_MUST_NOT_LEAK",
+    });
+    expect(normalized).toEqual({
+      apiKey: "public-api-key",
+      authDomain: "example.firebaseapp.com",
+      projectId: "public-project",
+      storageBucket: "public-project.appspot.com",
+      messagingSenderId: "1234567890",
+      appId: "public-app-id",
+    });
+    expect(normalized).not.toHaveProperty("vapidKey");
+    expect(normalized).not.toHaveProperty("private_key");
+  });
+
+  test("returns null when required fields are missing or input is not an object", () => {
+    expect(normalizeFirebaseClientConfig(undefined)).toBe(null);
+    expect(normalizeFirebaseClientConfig(null)).toBe(null);
+    expect(normalizeFirebaseClientConfig("nope")).toBe(null);
+    expect(normalizeFirebaseClientConfig({ apiKey: "only-key" })).toBe(null);
+  });
+});
+
+describe("createFirebaseMessagingServiceWorker", () => {
+  test("inlines client config and imports firebase compat SDK, without leaking secrets", () => {
+    const config = normalizeFirebaseClientConfig({
+      apiKey: "public-api-key",
+      projectId: "public-project",
+      messagingSenderId: "1234567890",
+      appId: "public-app-id",
+      private_key: "SERVER_PRIVATE_KEY_MUST_NOT_LEAK",
+    });
+    const body = createFirebaseMessagingServiceWorker(config);
+    expect(body).toContain("public-api-key");
+    expect(body).toContain("public-project");
+    expect(body).toContain("firebase-messaging-compat.js");
+    expect(body).toContain("onBackgroundMessage");
+    expect(body).toContain("notificationclick");
+    expect(body).not.toContain("SERVER_PRIVATE_KEY_MUST_NOT_LEAK");
+    expect(body).not.toContain("private_key");
+  });
+
+  test("produces a no-op worker (config null) that still registers notificationclick", () => {
+    const body = createFirebaseMessagingServiceWorker(null);
+    // config is null → the importScripts/onBackgroundMessage block is gated by `if (firebaseConfig)` at runtime,
+    // but notificationclick is always registered.
+    expect(body).toContain("const firebaseConfig = null");
+    expect(body).toContain("notificationclick");
+    expect(body).toContain("if (firebaseConfig)");
+  });
+});

package/firebaseMessagingSw.ts

@@ -0,0 +1,74 @@
+ const FIREBASE_WEB_SDK_VERSION = "12.13.0";
+
+export interface FirebaseClientEnvConfig {
+  apiKey: string;
+  authDomain?: string;
+  projectId: string;
+  storageBucket?: string;
+  messagingSenderId: string;
+  appId: string;
+  vapidKey?: string;
+}
+
+//* env.client 의 firebase 설정을 검증하고, 서비스워커에 필요한 필드만 화이트리스트한다.
+//* vapidKey/서버 시크릿 등 나머지 필드는 의도적으로 제외한다(SW 본문에 유출 방지).
+export function normalizeFirebaseClientConfig(config: unknown): FirebaseClientEnvConfig | null {
+  if (!config || typeof config !== "object") return null;
+  const value = config as Partial<Record<keyof FirebaseClientEnvConfig, unknown>>;
+  if (
+    typeof value.apiKey !== "string" ||
+    typeof value.projectId !== "string" ||
+    typeof value.messagingSenderId !== "string" ||
+    typeof value.appId !== "string"
+  ) {
+    return null;
+  }
+  return {
+    apiKey: value.apiKey,
+    ...(typeof value.authDomain === "string" ? { authDomain: value.authDomain } : {}),
+    projectId: value.projectId,
+    ...(typeof value.storageBucket === "string" ? { storageBucket: value.storageBucket } : {}),
+    messagingSenderId: value.messagingSenderId,
+    appId: value.appId,
+  };
+}
+
+//* firebase-messaging-sw.js 생성 코드
+export function createFirebaseMessagingServiceWorker(config: FirebaseClientEnvConfig | null): string {
+  const configJson = JSON.stringify(config);
+  return `/* Generated by Akan.js. Do not edit. */
+const firebaseConfig = ${configJson};
+
+if (firebaseConfig) {
+  importScripts("https://www.gstatic.com/firebasejs/${FIREBASE_WEB_SDK_VERSION}/firebase-app-compat.js");
+  importScripts("https://www.gstatic.com/firebasejs/${FIREBASE_WEB_SDK_VERSION}/firebase-messaging-compat.js");
+
+  firebase.initializeApp(firebaseConfig);
+  const messaging = firebase.messaging();
+
+  const notificationUrl = (payload) =>
+    payload?.data?.url || payload?.fcmOptions?.link || payload?.notification?.click_action;
+
+  messaging.onBackgroundMessage((payload) => {
+    const title = payload?.notification?.title || "";
+    const options = {
+      body: payload?.notification?.body,
+      icon: payload?.notification?.icon,
+      image: payload?.notification?.image,
+      data: {
+        url: notificationUrl(payload),
+        FCM_MSG: payload,
+      },
+    };
+    self.registration.showNotification(title, options);
+  });
+}
+
+self.addEventListener("notificationclick", (event) => {
+  const url = event.notification?.data?.url || event.notification?.data?.FCM_MSG?.data?.url;
+  event.notification?.close();
+  if (!url) return;
+  event.waitUntil(clients.openWindow(url));
+});
+`;
+}

package/index.ts

@@ -18,6 +18,7 @@ export * from "./dependencyScanner";
 export * from "./executors";
 export * from "./extractDeps";
 export * from "./fileSys";
+export * from "./firebaseMessagingSw";
 export * from "./frontendBuild";
 export * from "./getCredentials";
 export * from "./getDirname";

package/lint/no-deep-internal-import.grit

@@ -21,5 +21,15 @@ or {
       span = $source,
       message = "Module files should not import from two or more parent directories."
     )
+  },
+  JsModuleSource() as $source where {
+    $source <: within JsImport(),
+    not $filename <: r".*\.(?:test|spec)\.tsx?",
+    $filename <: r".*/lib/.+\.tsx",
+    $source <: r"\"\.\./.*\"",
+    register_diagnostic(
+      span = $source,
+      message = "Module UI (.tsx) files under lib must not use internal relative imports like ../cnst. Import from the package client/server entrypoint instead."
+    )
   }
 }

package/lint/no-redeclare-predefined-endpoint.grit

@@ -0,0 +1,28 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Every model already gets auto-generated CRUD endpoints in its slice fetch
+// contract (see pkgs/akanjs/fetch/fetchType/sliceFetch.type.ts and
+// pkgs/akanjs/fetch/client/fetchClient.ts):
+//   <refName>, light<Model>, create<Model>, update<Model>, remove<Model>,
+//   view<Model>, edit<Model>, merge<Model>.
+// Re-declaring one of them inside the `endpoint(...)` block of a
+// `<model>.signal.ts` file shadows the framework contract and can pass
+// sync/typecheck/build while failing at runtime, so flag it here.
+`$key: $value` as $prop where {
+  $prop <: within `class $className extends $base {}` where {
+    $base <: contains `endpoint`,
+    $className <: r"([A-Z][a-zA-Z0-9]*)Endpoint"($Cap)
+  },
+  $filename <: r".*/([a-z][a-zA-Z0-9]*)\.signal\.ts"($model),
+  or {
+    $key <: $model,
+    $key <: r"(?:light|create|update|remove|view|edit|merge)([A-Z][a-zA-Z0-9]*)"($keyCap) where {
+      $keyCap <: $Cap
+    }
+  },
+  register_diagnostic(
+    span = $key,
+    message = "This endpoint name collides with an auto-generated CRUD endpoint (<model>, light/create/update/remove/view/edit/merge<Model>). Rename it or move the logic into the service; do not re-declare predefined endpoints."
+  )
+}

package/lint/no-throw-raw-error.grit

@@ -0,0 +1,40 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Domain code in apps/ and libs/ must not throw a raw `Error`. Throw the typed
+// `Err` instead, which is generated per app/lib by `makeTrans`
+// (pkgs/akanjs/dictionary/trans.ts) and imported via `import { Err } from "../dict"`
+// (or the app/lib client entrypoint). `Err` carries a translatable error key,
+// a status code, and structured payload, so raw `Error` throws lose i18n and
+// HTTP-status handling.
+//
+// The `$msg` metavariable in the argument position leniently matches any arity,
+// so `throw new Error()`, `throw new Error("x")`, and
+// `throw new Error("x", { cause })` are all caught, as is the `new`-less
+// `throw Error(...)` call form. Only real throw statements match — a
+// `new Error(...)` inside a string literal or one that is not thrown is ignored.
+//
+// No autofix: `Err`'s first argument must be a typed dictionary error key
+// (e.g. throw new Err('model.errorKey')), so a mechanical rewrite of an
+// arbitrary message string would not typecheck. Each site must be migrated to a
+// real error key by hand.
+//
+// NOTE: the diagnostic messages below use single quotes in the example on
+// purpose. Escaped double quotes (\") inside a GritQL string trigger a
+// double-unescape bug in Biome 2.4.4 that corrupts the rendered message.
+or {
+  `throw new Error($msg)` as $throw where {
+    register_diagnostic(
+      span = $throw,
+      message = "Do not throw a raw `Error`. Throw the typed `Err` instead (import { Err } from the app/lib dict), e.g. throw new Err('model.errorKey').",
+      severity = "error"
+    )
+  },
+  `throw Error($msg)` as $throw where {
+    register_diagnostic(
+      span = $throw,
+      message = "Do not throw a raw `Error`. Throw the typed `Err` instead (import { Err } from the app/lib dict), e.g. throw new Err('model.errorKey').",
+      severity = "error"
+    )
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.11-rc.1",
+  "version": "2.3.11-rc.10",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.11-rc.1",
+    "akanjs": "2.3.11-rc.10",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/qualityScanner.ts

@@ -15,6 +15,7 @@ export interface QualityWarning {
   file?: string;
   line?: number;
   locations?: Array<{ file: string; line: number }>;
+  fix?: string;
 }
 
 export interface QualityScanResult {
@@ -37,6 +38,7 @@ interface ExportedFunctionLike {
   file: string;
   line: number;
   bodyFingerprint?: string;
+  duplicateNameExempt: boolean;
 }
 
 interface TopLevelDeclaration {
@@ -47,6 +49,14 @@ interface TopLevelDeclaration {
   node: ts.Statement;
 }
 
+interface ComponentFileDeclaration {
+  name: string;
+  kind: "interface" | "type" | "function" | "variable" | "class" | "enum";
+  line: number;
+  exported: boolean;
+  isDefaultExport: boolean;
+}
+
 const MAX_FILE_LINES = 2000;
 const PLACEHOLDER_EXPORT_NAMES = new Set([
   "aa",
@@ -104,6 +114,61 @@ const CONVENTION_SUFFIXES = [
   ".store.ts",
 ] as const;
 
+// Non-PascalCase exports the framework recognizes on page/layout route modules (see PageModule/LayoutModule
+// in pkgs/akanjs/client/csrTypes.ts). PascalCase route exports (Loading, NotFound, Error) pass the component
+// check, and the `default` export is handled separately.
+const PAGE_RESERVED_EXPORTS = new Set([
+  "pageConfig",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "fonts",
+  "manifest",
+  "theme",
+  "reconnect",
+  "wsConnect",
+  "layoutStyle",
+  "gaTrackingId",
+]);
+
+// How to remediate each rule, keyed by rule id. Surfaced as a `fix:` line per warning (text + JSON output)
+// so the scan result tells the reader what to do, not just what is wrong.
+const RULE_FIXES: Record<string, string> = {
+  "akan.global.duplicate-exported-function-name":
+    "Rename one of the exports, or if they are the same thing, extract it into one shared module and import it in both places.",
+  "akan.global.duplicate-exported-function-body":
+    "Extract the shared implementation into a single exported helper and import it, instead of copying the body.",
+  "akan.file.recommended-max-lines":
+    "Split the file by responsibility — move Zones, Utils, or subcomponents into sibling files.",
+  "akan.file.max-lines": "Break the file into smaller focused modules; keep one primary responsibility per file.",
+  "akan.file.placeholder-export":
+    "Remove the placeholder export; generated indexes should only re-export real modules.",
+  "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.",
+  "akan.file.window-augmentation":
+    "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.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.lib-root-file":
+    "Move the file into a domain module folder under lib/; keep lib 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.",
+};
+
+function getRuleFix(rule: string): string | undefined {
+  if (rule.startsWith("akan.convention"))
+    return "Keep only the model's allowed declarations in this file; move other logic to the matching domain file (service, document, store, etc.).";
+  return RULE_FIXES[rule];
+}
+
 export class AkanQualityScanner {
   async scan(workspaceRoot: string): Promise<QualityScanResult> {
     const targetFiles = await this.#collectTargetFiles(workspaceRoot);
@@ -111,6 +176,7 @@ export class AkanQualityScanner {
     const warnings = [
       ...this.#scanGlobalQuality(sourceFiles),
       ...sourceFiles.flatMap((sourceFile) => this.#scanSingleFileQuality(sourceFile)),
+      ...sourceFiles.flatMap((sourceFile) => this.#scanComponentQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
     ];
@@ -118,7 +184,9 @@ export class AkanQualityScanner {
     return {
       workspaceRoot,
       scannedFiles: sourceFiles.length,
-      warnings: warnings.sort(compareWarnings),
+      warnings: warnings
+        .map((warning) => ({ ...warning, fix: warning.fix ?? getRuleFix(warning.rule) }))
+        .sort(compareWarnings),
       suggestedRules: SUGGESTED_RULES,
     };
   }
@@ -177,7 +245,8 @@ export class AkanQualityScanner {
     const exportedFunctionLikes = sourceFiles.flatMap((sourceFile) => getExportedFunctionLikes(sourceFile));
     const warnings: QualityWarning[] = [];
 
-    for (const [name, declarations] of groupBy(exportedFunctionLikes, (declaration) => declaration.name)) {
+    const nameCheckedDeclarations = exportedFunctionLikes.filter((declaration) => !declaration.duplicateNameExempt);
+    for (const [name, declarations] of groupBy(nameCheckedDeclarations, (declaration) => declaration.name)) {
       if (declarations.length < 2) continue;
       warnings.push({
         rule: "akan.global.duplicate-exported-function-name",
@@ -254,6 +323,51 @@ export class AkanQualityScanner {
     return warnings;
   }
 
+  #scanComponentQuality(sourceFile: SourceFileInfo): QualityWarning[] {
+    if (!isComponentDeclarationFile(sourceFile.file)) return [];
+    const isPage = isPageRouteFile(sourceFile.file);
+    const declarations = getComponentFileDeclarations(sourceFile.sourceFile);
+    // Compound/namespaced components (e.g. `Like.WithDislike = WithDislike`) are valid without being exported.
+    const compoundComponentNames = getCompoundComponentNames(sourceFile.sourceFile);
+    // Components are the exported (or compound) PascalCase values; their "<Component>Props" interface may live here.
+    const componentNames = declarations
+      .filter((declaration) => declaration.exported && isComponentValueKind(declaration.kind))
+      .filter((declaration) => isPascalCaseName(declaration.name))
+      .map((declaration) => declaration.name);
+    const allowedComponentNames = new Set([...componentNames, ...compoundComponentNames]);
+    const allowedPropsInterfaces = new Set([...allowedComponentNames].map((name) => `${name}Props`));
+    const warnings: QualityWarning[] = [];
+    for (const declaration of declarations) {
+      if (declaration.isDefaultExport) continue;
+      if (declaration.kind === "interface" && allowedPropsInterfaces.has(declaration.name)) continue;
+      if (declaration.exported) {
+        if (isAllowedComponentExport(declaration, isPage)) continue;
+        warnings.push({
+          rule: "akan.file.component-export",
+          scope: "file",
+          severity: "warning",
+          file: sourceFile.file,
+          line: declaration.line,
+          message: `Component file exports ${declaration.kind} "${declaration.name}", which is not a PascalCase component${isPage ? " or reserved route export" : ""}.`,
+        });
+        continue;
+      }
+      // A non-exported PascalCase component attached as a compound member is an accepted pattern.
+      if (isComponentValueKind(declaration.kind) && compoundComponentNames.has(declaration.name)) continue;
+      if (isRestrictedInternalKind(declaration.kind)) {
+        warnings.push({
+          rule: "akan.file.component-internal-declaration",
+          scope: "file",
+          severity: "warning",
+          file: sourceFile.file,
+          line: declaration.line,
+          message: `Component file declares non-exported ${declaration.kind} "${declaration.name}". Only "interface <Component>Props" may stay internal.`,
+        });
+      }
+    }
+    return warnings;
+  }
+
   #scanConventionQuality(sourceFile: SourceFileInfo): QualityWarning[] {
     const suffix = CONVENTION_SUFFIXES.find((candidate) => sourceFile.file.endsWith(candidate));
     if (!suffix) return [];
@@ -335,6 +449,7 @@ export function formatQualityWarnings(warnings: QualityWarning[]) {
         ...warning.locations.map(({ file, line }) => `  note: related location ${formatQualityLocation(file, line)}`),
       );
     }
+    if (warning.fix) lines.push(`  fix: ${warning.fix}`);
     return lines;
   });
 }
@@ -345,6 +460,9 @@ function formatQualityLocation(file: string | undefined, line: number | undefine
 
 function getExportedFunctionLikes(sourceFile: SourceFileInfo): ExportedFunctionLike[] {
   const declarations: ExportedFunctionLike[] = [];
+  // UI component names (e.g. Card, Button) naturally repeat across apps/libs, so exempt ui files from the
+  // duplicate-exported-name check. This only relaxes the name check; the shared-body check still applies.
+  const nameExempt = isPageRouteFile(sourceFile.file) || isUiComponentFile(sourceFile.file);
   for (const statement of sourceFile.sourceFile.statements) {
     if (ts.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
       declarations.push({
@@ -353,6 +471,7 @@ function getExportedFunctionLikes(sourceFile: SourceFileInfo): ExportedFunctionL
         file: sourceFile.file,
         line: getLine(sourceFile.sourceFile, statement),
         bodyFingerprint: getBodyFingerprint(sourceFile.sourceFile, statement.body),
+        duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile.file, false),
       });
     }
     if (ts.isClassDeclaration(statement) && statement.name && isExported(statement)) {
@@ -362,6 +481,9 @@ function getExportedFunctionLikes(sourceFile: SourceFileInfo): ExportedFunctionL
         file: sourceFile.file,
         line: getLine(sourceFile.sourceFile, statement),
         bodyFingerprint: getBodyFingerprint(sourceFile.sourceFile, statement),
+        duplicateNameExempt:
+          nameExempt ||
+          isConventionDuplicateNameExempt(sourceFile.file, isEnumClassStatement(sourceFile.sourceFile, statement)),
       });
     }
     if (ts.isVariableStatement(statement) && isExported(statement)) {
@@ -373,6 +495,7 @@ function getExportedFunctionLikes(sourceFile: SourceFileInfo): ExportedFunctionL
           file: sourceFile.file,
           line: getLine(sourceFile.sourceFile, declaration),
           bodyFingerprint: getBodyFingerprint(sourceFile.sourceFile, declaration.initializer),
+          duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile.file, false),
         });
       }
     }
@@ -380,6 +503,43 @@ function getExportedFunctionLikes(sourceFile: SourceFileInfo): ExportedFunctionL
   return declarations;
 }
 
+function isPageRouteFile(file: string) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "page";
+}
+
+function isUiComponentFile(file: string) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "ui";
+}
+
+function isConventionDuplicateNameExempt(file: string, isEnumClass: boolean) {
+  if (!isInLibModule(file)) return false;
+  if (file.endsWith(".tsx")) return true;
+  if (
+    file.endsWith(".document.ts") ||
+    file.endsWith(".service.ts") ||
+    file.endsWith(".signal.ts") ||
+    file.endsWith(".store.ts")
+  )
+    return true;
+  // Model view classes may repeat across modules; enum classes must stay uniquely named.
+  if (file.endsWith(".constant.ts")) return !isEnumClass;
+  return false;
+}
+
+function isInLibModule(file: string) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments.includes("lib");
+}
+
+function isEnumClassStatement(sourceFile: ts.SourceFile, statement: ts.Statement) {
+  if (!ts.isClassDeclaration(statement)) return false;
+  const heritageClause = statement.heritageClauses?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword);
+  const expression = heritageClause?.types[0]?.expression;
+  return !!expression && expression.getText(sourceFile).startsWith("enumOf(");
+}
+
 function getExportedClassNames(sourceFile: ts.SourceFile) {
   return sourceFile.statements
     .filter((statement): statement is ts.ClassDeclaration => ts.isClassDeclaration(statement) && !!statement.name)
@@ -387,6 +547,86 @@ function getExportedClassNames(sourceFile: ts.SourceFile) {
     .map((statement) => statement.name!.text);
 }
 
+function isComponentDeclarationFile(file: string) {
+  if (!file.endsWith(".tsx")) return false;
+  const segments = file.split("/");
+  const [root, , area] = segments;
+  if (root !== "apps" && root !== "libs") return false;
+  if (area === "lib" || area === "ui") return true;
+  return root === "apps" && area === "page";
+}
+
+function getComponentFileDeclarations(sourceFile: ts.SourceFile): ComponentFileDeclaration[] {
+  const reExportedNames = new Set<string>();
+  for (const statement of sourceFile.statements) {
+    if (ts.isExportDeclaration(statement) && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+      for (const element of statement.exportClause.elements)
+        reExportedNames.add((element.propertyName ?? element.name).text);
+    }
+  }
+  const declarations: ComponentFileDeclaration[] = [];
+  for (const statement of sourceFile.statements) {
+    const isDefaultExport = isDefaultExportStatement(statement);
+    const inlineExported = isExported(statement);
+    const add = (name: string, kind: ComponentFileDeclaration["kind"], line: number) =>
+      declarations.push({ name, kind, line, exported: inlineExported || reExportedNames.has(name), isDefaultExport });
+    if (ts.isInterfaceDeclaration(statement)) add(statement.name.text, "interface", getLine(sourceFile, statement));
+    else if (ts.isTypeAliasDeclaration(statement)) add(statement.name.text, "type", getLine(sourceFile, statement));
+    else if (ts.isEnumDeclaration(statement)) add(statement.name.text, "enum", getLine(sourceFile, statement));
+    else if (ts.isFunctionDeclaration(statement) && statement.name)
+      add(statement.name.text, "function", getLine(sourceFile, statement));
+    else if (ts.isClassDeclaration(statement) && statement.name)
+      add(statement.name.text, "class", getLine(sourceFile, statement));
+    else if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name)) continue;
+        const kind = isFunctionLikeInitializer(declaration.initializer) ? "function" : "variable";
+        add(declaration.name.text, kind, getLine(sourceFile, declaration));
+      }
+    }
+  }
+  return declarations;
+}
+
+// Detects compound/namespaced component assignments like `Like.WithDislike = WithDislike`. The PascalCase
+// member is the public component name; when the right side is a PascalCase identifier it is the local
+// definition. Both are treated as valid components so the definition and its "<Component>Props" may stay local.
+function getCompoundComponentNames(sourceFile: ts.SourceFile): Set<string> {
+  const names = new Set<string>();
+  for (const statement of sourceFile.statements) {
+    if (!ts.isExpressionStatement(statement)) continue;
+    const { expression } = statement;
+    if (!ts.isBinaryExpression(expression) || expression.operatorToken.kind !== ts.SyntaxKind.EqualsToken) continue;
+    if (!ts.isPropertyAccessExpression(expression.left) || !isPascalCaseName(expression.left.name.text)) continue;
+    names.add(expression.left.name.text);
+    if (ts.isIdentifier(expression.right) && isPascalCaseName(expression.right.text)) names.add(expression.right.text);
+  }
+  return names;
+}
+
+function isComponentValueKind(kind: ComponentFileDeclaration["kind"]) {
+  return kind === "variable" || kind === "function" || kind === "class";
+}
+
+function isRestrictedInternalKind(kind: ComponentFileDeclaration["kind"]) {
+  return kind === "interface" || kind === "type" || kind === "function";
+}
+
+function isAllowedComponentExport(declaration: ComponentFileDeclaration, isPage: boolean) {
+  if (isComponentValueKind(declaration.kind) && isPascalCaseName(declaration.name)) return true;
+  return isPage && PAGE_RESERVED_EXPORTS.has(declaration.name);
+}
+
+function isPascalCaseName(name: string) {
+  // PascalCase component names start uppercase and are not SCREAMING_SNAKE_CASE constants.
+  return /^[A-Z]/.test(name) && !/^[A-Z0-9_]+$/.test(name);
+}
+
+function isDefaultExportStatement(statement: ts.Statement) {
+  if (ts.isExportAssignment(statement)) return !statement.isExportEquals;
+  return !!(ts.getCombinedModifierFlags(statement as ts.Declaration) & ts.ModifierFlags.Default);
+}
+
 function getPlaceholderExportWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
   if (!sourceFile.file.endsWith("/index.ts") && !sourceFile.file.endsWith("/index.tsx")) return [];
   return getTopLevelDeclarations(sourceFile)
@@ -403,11 +643,7 @@ function getPlaceholderExportWarnings(sourceFile: SourceFileInfo): QualityWarnin
 
 function getDictionaryTextWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
   if (!sourceFile.file.endsWith(".dictionary.ts")) return [];
-  const stalePatterns = [
-    { pattern: /\b[A-Z][A-Za-z0-9]* description\b/, label: "scaffold description text" },
-    { pattern: /settting/, label: "misspelling: settting" },
-    { pattern: /배너 수/, label: "stale copied Korean domain noun: 배너 수" },
-  ];
+  const stalePatterns = [{ pattern: /\b[A-Z][A-Za-z0-9]* description\b/, label: "scaffold description text" }];
   return stalePatterns.flatMap(({ pattern, label }) =>
     findPatternLines(sourceFile.content, pattern).map((line) => ({
       rule: "akan.file.dictionary-stale-text",
@@ -549,8 +785,8 @@ function getConventionDescription(suffix: (typeof CONVENTION_SUFFIXES)[number],
 
 function getLibRootFile(file: string) {
   const segments = file.split("/");
-  if (segments[0] === "libs" && segments.length === 4 && segments[2] === "lib") return segments[3];
-  if (segments[0] === "apps" && segments.length === 5 && segments[2] === "lib") return segments[4];
+  if ((segments[0] === "libs" || segments[0] === "apps") && segments.length === 4 && segments[2] === "lib")
+    return segments[3];
   return null;
 }
 

package/scanInfo.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { rm } from "node:fs/promises";
 import type {
   AppConfigResult,
   AppScanResult,
@@ -52,7 +53,9 @@ const appRootAllowedFiles = new Set([
   "package.json",
   "server.ts",
   "tsconfig.json",
+  "tsconfig.tsbuildinfo",
 ]);
+const generatedRootCapacitorConfigFiles = ["capacitor.config.js", "capacitor.config.json"] as const;
 const appRootAllowedDirs = new Set([
   ".akan",
   "android",
@@ -99,12 +102,17 @@ const isAllowedLibRootFile = (filename: string) =>
   libRootAllowedFiles.has(filename) || rootSignalTestFilePattern.test(filename);
 const getScanPath = (exec: AppExecutor | LibExecutor, relativePath: string) =>
   path.posix.join(`${exec.type}s`, exec.name, relativePath.split(path.sep).join("/"));
+async function clearGeneratedRootCapacitorConfigs(exec: AppExecutor | LibExecutor) {
+  if (exec.type !== "app") return;
+  await Promise.all(generatedRootCapacitorConfigFiles.map((filename) => rm(exec.getPath(filename), { force: true })));
+}
 const getModuleNameFromPath = (kind: ModuleKind, modulePath: string) => {
   const dirname = path.basename(modulePath);
   return kind === "service" ? dirname.replace(/^_+/, "") : dirname;
 };
 
 async function assertScanConvention(exec: AppExecutor | LibExecutor, libRoot: { files: string[]; dirs: string[] }) {
+  await clearGeneratedRootCapacitorConfigs(exec);
   const violations: string[] = [];
   const addViolation = (relativePath: string, reason: string) => {
     violations.push(`${getScanPath(exec, relativePath)}: ${reason}`);

package/workflow/artifacts.ts

@@ -196,7 +196,6 @@ export const generatedFilePathsForTarget = (targetRoot: string, reason = "Genera
   [
     { path: `${targetRoot}/lib/cnst.ts`, action: "sync", reason },
     { path: `${targetRoot}/lib/dict.ts`, action: "sync", reason },
-    { path: `${targetRoot}/lib/option.ts`, action: "sync", reason },
     { path: `${targetRoot}/lib/index.ts`, action: "sync", reason },
   ] satisfies PrimitiveGeneratedFile[];