@akanjs/cli 2.3.11-rc.9 → 2.3.11

package/incrementalBuilder.proc.js

@@ -2691,6 +2691,31 @@ function validateRouteSourceExports(source, filePath, kind, options = {}) {
     throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
   }
 }
+function validateOverridesSourceExports(source, filePath) {
+  const sourceFile = ts3.createSourceFile(filePath, source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
+  const fail = (message) => {
+    throw new Error(`[route-convention] ${message}: ${filePath}`);
+  };
+  let defaultOverride = null;
+  for (const statement of sourceFile.statements) {
+    if (ts3.isExpressionStatement(statement) && ts3.isStringLiteral(statement.expression))
+      continue;
+    if (ts3.isImportDeclaration(statement))
+      continue;
+    if (ts3.isInterfaceDeclaration(statement) || ts3.isTypeAliasDeclaration(statement))
+      continue;
+    if (ts3.isExportAssignment(statement) && !statement.isExportEquals) {
+      defaultOverride = statement;
+      continue;
+    }
+    fail(`_overrides.tsx may only contain imports and a single "export default override({ ... })"`);
+  }
+  if (!defaultOverride)
+    fail(`_overrides.tsx must "export default override({ ... })"`);
+  const expression = defaultOverride.expression;
+  if (!ts3.isCallExpression(expression) || !ts3.isIdentifier(expression.expression) || expression.expression.text !== "override")
+    fail(`_overrides.tsx default export must be a call to "override", e.g. "export default override({ Modal: BrandModal })"`);
+}
 
 class Executor {
   static verbose = false;
@@ -3714,7 +3739,11 @@ class AppExecutor extends SysExecutor {
         throw new Error(`[route-convention] __root_layout is reserved for Akan.js generated root layout: ${absPath}`);
       }
       const isRootLayout = parsed.kind === "layout" && parsed.moduleSegments.at(-1) === "_layout";
-      validateRouteSourceExports(await Bun.file(absPath).text(), absPath, parsed.kind, { rootLayout: isRootLayout });
+      const routeSource = await Bun.file(absPath).text();
+      if (parsed.kind === "overrides")
+        validateOverridesSourceExports(routeSource, absPath);
+      else
+        validateRouteSourceExports(routeSource, absPath, parsed.kind, { rootLayout: isRootLayout });
       pageKeys.push(key);
     }
     pageKeys.sort();
@@ -8822,6 +8851,25 @@ async function appHasStModule(appCwdPath) {
 }
 var IMPLICIT_LAYOUT_DIR = path13.join(".akan", "generated", "root-layouts");
 var IMPLICIT_DICT_DIR = path13.join(".akan", "generated", "dict");
+var IMPLICIT_OVERRIDES_DIR = path13.join(".akan", "generated", "overrides");
+var OVERRIDES_KEY_RE = /^\.\/(.+\/)?_overrides\.(tsx|ts|jsx|js)$/;
+async function writeGeneratedOverridesLayoutFile(opts) {
+  const filename = `${opts.key.replace(/^\.\//, "").replace(/[^a-zA-Z0-9]+/g, "_")}.tsx`;
+  const absPath = path13.join(path13.resolve(opts.appCwdPath), IMPLICIT_OVERRIDES_DIR, filename);
+  const userRel = path13.relative(path13.dirname(absPath), opts.userAbsPath).split(path13.sep).join("/");
+  const userSpecifier = userRel.startsWith(".") ? userRel : `./${userRel}`;
+  const source2 = `"use client";
+import { UiOverrideProvider } from "akanjs/ui";
+import { createElement, type ReactNode } from "react";
+import value from ${JSON.stringify(userSpecifier)};
+
+export default function AkanUiOverridesLayout({ children }: { children?: ReactNode }) {
+  return createElement(UiOverrideProvider, { value }, children);
+}
+`;
+  await Bun.write(absPath, source2);
+  return absPath;
+}
 function getRootBoundarySegments(key) {
   const match = LAYOUT_KEY_RE.exec(key);
   if (!match)
@@ -9014,9 +9062,17 @@ async function resolveSsrPageEntries(opts) {
     const segments = getRootBoundarySegments(key);
     return segments !== null && isRootBoundarySegments(segments, basePaths);
   }));
-  const base = opts.pageKeys.filter((key) => !rootLayoutKeys.has(key)).map((key) => ({
-    key,
-    moduleAbsPath: path13.resolve(absPageDir, key)
+  const base = await Promise.all(opts.pageKeys.filter((key) => !rootLayoutKeys.has(key)).map(async (key) => {
+    const userAbsPath = path13.resolve(absPageDir, key);
+    if (OVERRIDES_KEY_RE.test(key)) {
+      const moduleAbsPath = await writeGeneratedOverridesLayoutFile({
+        appCwdPath: opts.appCwdPath,
+        key,
+        userAbsPath
+      });
+      return { key, moduleAbsPath, seedAbsPaths: [userAbsPath] };
+    }
+    return { key, moduleAbsPath: userAbsPath };
   }));
   const generated = await Promise.all(rootBoundaries.map(async (boundary) => ({
     key: implicitRootLayoutKey(boundary.segments),
@@ -9048,7 +9104,7 @@ function computeRouteSeedIndex(pageEntries) {
   for (const { key, moduleAbsPath, seedAbsPaths } of pageEntries) {
     const parsed = parseRouteModuleKey2(key);
     const files = [path14.resolve(moduleAbsPath), ...(seedAbsPaths ?? []).map((seed) => path14.resolve(seed))];
-    if (parsed.kind === "layout") {
+    if (parsed.kind === "layout" || parsed.kind === "overrides") {
       const prefix = parsed.routeSegments.join("/");
       const prev = layoutsByPrefix.get(prefix) ?? [];
       layoutsByPrefix.set(prefix, [...prev, ...files]);
@@ -15698,6 +15754,42 @@ var CONVENTION_SUFFIXES = [
   ".signal.ts",
   ".store.ts"
 ];
+var PAGE_RESERVED_EXPORTS = new Set([
+  "pageConfig",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "fonts",
+  "manifest",
+  "theme",
+  "reconnect",
+  "wsConnect",
+  "layoutStyle",
+  "gaTrackingId"
+]);
+var RULE_FIXES = {
+  "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 \u2014 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 \u2014 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) {
+  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];
+}
 
 class AkanQualityScanner {
   async scan(workspaceRoot) {
@@ -15713,7 +15805,7 @@ 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
     };
   }
@@ -15838,22 +15930,43 @@ class AkanQualityScanner {
   #scanComponentQuality(sourceFile2) {
     if (!isComponentDeclarationFile(sourceFile2.file))
       return [];
-    const exportedNames = getExportedDeclarationNames(sourceFile2.sourceFile);
-    const allowedInternalInterfaces = new Set([...exportedNames].map((name) => `${name}Props`));
+    const isPage = isPageRouteFile(sourceFile2.file);
+    const declarations = getComponentFileDeclarations(sourceFile2.sourceFile);
+    const compoundComponentNames = getCompoundComponentNames(sourceFile2.sourceFile);
+    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 = [];
-    for (const declaration of getInternalTypeOrFunctionDeclarations(sourceFile2.sourceFile)) {
-      if (exportedNames.has(declaration.name))
+    for (const declaration of declarations) {
+      if (declaration.isDefaultExport)
         continue;
-      if (declaration.kind === "interface" && allowedInternalInterfaces.has(declaration.name))
+      if (declaration.kind === "interface" && allowedPropsInterfaces.has(declaration.name))
         continue;
-      warnings.push({
-        rule: "akan.file.component-internal-declaration",
-        scope: "file",
-        severity: "warning",
-        file: sourceFile2.file,
-        line: declaration.line,
-        message: `Component file should not declare non-exported ${declaration.kind} "${declaration.name}". Only a "<Component>Props" interface may stay internal; move other types or helpers to a separate file in ui/, webkit/, or common/ by purpose.`
-      });
+      if (declaration.exported) {
+        if (isAllowedComponentExport(declaration, isPage))
+          continue;
+        warnings.push({
+          rule: "akan.file.component-export",
+          scope: "file",
+          severity: "warning",
+          file: sourceFile2.file,
+          line: declaration.line,
+          message: `Component file exports ${declaration.kind} "${declaration.name}", which is not a PascalCase component${isPage ? " or reserved route export" : ""}.`
+        });
+        continue;
+      }
+      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: sourceFile2.file,
+          line: declaration.line,
+          message: `Component file declares non-exported ${declaration.kind} "${declaration.name}". Only "interface <Component>Props" may stay internal.`
+        });
+      }
     }
     return warnings;
   }
@@ -15932,6 +16045,8 @@ function formatQualityWarnings(warnings) {
     if (warning.locations?.length) {
       lines.push(...warning.locations.map(({ file, line }) => `  note: related location ${formatQualityLocation(file, line)}`));
     }
+    if (warning.fix)
+      lines.push(`  fix: ${warning.fix}`);
     return lines;
   });
 }
@@ -16023,61 +16138,75 @@ function isComponentDeclarationFile(file) {
     return true;
   return root === "apps" && area === "page";
 }
-function getExportedDeclarationNames(sourceFile2) {
-  const names = new Set;
+function getComponentFileDeclarations(sourceFile2) {
+  const reExportedNames = new Set;
   for (const statement of sourceFile2.statements) {
     if (ts11.isExportDeclaration(statement) && statement.exportClause && ts11.isNamedExports(statement.exportClause)) {
-      for (const element of statement.exportClause.elements) {
-        names.add(element.name.text);
-        if (element.propertyName)
-          names.add(element.propertyName.text);
-      }
-      continue;
+      for (const element of statement.exportClause.elements)
+        reExportedNames.add((element.propertyName ?? element.name).text);
     }
-    if (!isExported(statement))
-      continue;
-    for (const name of getStatementDeclarationNames(statement))
-      names.add(name);
-  }
-  return names;
-}
-function getStatementDeclarationNames(statement) {
-  if (ts11.isFunctionDeclaration(statement) && statement.name)
-    return [statement.name.text];
-  if (ts11.isClassDeclaration(statement) && statement.name)
-    return [statement.name.text];
-  if (ts11.isInterfaceDeclaration(statement))
-    return [statement.name.text];
-  if (ts11.isTypeAliasDeclaration(statement))
-    return [statement.name.text];
-  if (ts11.isEnumDeclaration(statement))
-    return [statement.name.text];
-  if (ts11.isVariableStatement(statement)) {
-    return statement.declarationList.declarations.filter((declaration) => ts11.isIdentifier(declaration.name)).map((declaration) => declaration.name.text);
   }
-  return [];
-}
-function getInternalTypeOrFunctionDeclarations(sourceFile2) {
   const declarations = [];
   for (const statement of sourceFile2.statements) {
-    if (isExported(statement))
-      continue;
-    if (ts11.isInterfaceDeclaration(statement)) {
-      declarations.push({ name: statement.name.text, kind: "interface", line: getLine(sourceFile2, statement) });
-    } else if (ts11.isTypeAliasDeclaration(statement)) {
-      declarations.push({ name: statement.name.text, kind: "type", line: getLine(sourceFile2, statement) });
-    } else if (ts11.isFunctionDeclaration(statement) && statement.name) {
-      declarations.push({ name: statement.name.text, kind: "function", line: getLine(sourceFile2, statement) });
-    } else if (ts11.isVariableStatement(statement)) {
+    const isDefaultExport = isDefaultExportStatement(statement);
+    const inlineExported = isExported(statement);
+    const add = (name, kind, line) => declarations.push({ name, kind, line, exported: inlineExported || reExportedNames.has(name), isDefaultExport });
+    if (ts11.isInterfaceDeclaration(statement))
+      add(statement.name.text, "interface", getLine(sourceFile2, statement));
+    else if (ts11.isTypeAliasDeclaration(statement))
+      add(statement.name.text, "type", getLine(sourceFile2, statement));
+    else if (ts11.isEnumDeclaration(statement))
+      add(statement.name.text, "enum", getLine(sourceFile2, statement));
+    else if (ts11.isFunctionDeclaration(statement) && statement.name)
+      add(statement.name.text, "function", getLine(sourceFile2, statement));
+    else if (ts11.isClassDeclaration(statement) && statement.name)
+      add(statement.name.text, "class", getLine(sourceFile2, statement));
+    else if (ts11.isVariableStatement(statement)) {
       for (const declaration of statement.declarationList.declarations) {
-        if (!ts11.isIdentifier(declaration.name) || !isFunctionLikeInitializer(declaration.initializer))
+        if (!ts11.isIdentifier(declaration.name))
           continue;
-        declarations.push({ name: declaration.name.text, kind: "function", line: getLine(sourceFile2, declaration) });
+        const kind = isFunctionLikeInitializer(declaration.initializer) ? "function" : "variable";
+        add(declaration.name.text, kind, getLine(sourceFile2, declaration));
       }
     }
   }
   return declarations;
 }
+function getCompoundComponentNames(sourceFile2) {
+  const names = new Set;
+  for (const statement of sourceFile2.statements) {
+    if (!ts11.isExpressionStatement(statement))
+      continue;
+    const { expression } = statement;
+    if (!ts11.isBinaryExpression(expression) || expression.operatorToken.kind !== ts11.SyntaxKind.EqualsToken)
+      continue;
+    if (!ts11.isPropertyAccessExpression(expression.left) || !isPascalCaseName(expression.left.name.text))
+      continue;
+    names.add(expression.left.name.text);
+    if (ts11.isIdentifier(expression.right) && isPascalCaseName(expression.right.text))
+      names.add(expression.right.text);
+  }
+  return names;
+}
+function isComponentValueKind(kind) {
+  return kind === "variable" || kind === "function" || kind === "class";
+}
+function isRestrictedInternalKind(kind) {
+  return kind === "interface" || kind === "type" || kind === "function";
+}
+function isAllowedComponentExport(declaration, isPage) {
+  if (isComponentValueKind(declaration.kind) && isPascalCaseName(declaration.name))
+    return true;
+  return isPage && PAGE_RESERVED_EXPORTS.has(declaration.name);
+}
+function isPascalCaseName(name) {
+  return /^[A-Z]/.test(name) && !/^[A-Z0-9_]+$/.test(name);
+}
+function isDefaultExportStatement(statement) {
+  if (ts11.isExportAssignment(statement))
+    return !statement.isExportEquals;
+  return !!(ts11.getCombinedModifierFlags(statement) & ts11.ModifierFlags.Default);
+}
 function getPlaceholderExportWarnings(sourceFile2) {
   if (!sourceFile2.file.endsWith("/index.ts") && !sourceFile2.file.endsWith("/index.tsx"))
     return [];

package/index.js

@@ -2689,6 +2689,31 @@ function validateRouteSourceExports(source, filePath, kind, options = {}) {
     throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
   }
 }
+function validateOverridesSourceExports(source, filePath) {
+  const sourceFile = ts3.createSourceFile(filePath, source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
+  const fail = (message) => {
+    throw new Error(`[route-convention] ${message}: ${filePath}`);
+  };
+  let defaultOverride = null;
+  for (const statement of sourceFile.statements) {
+    if (ts3.isExpressionStatement(statement) && ts3.isStringLiteral(statement.expression))
+      continue;
+    if (ts3.isImportDeclaration(statement))
+      continue;
+    if (ts3.isInterfaceDeclaration(statement) || ts3.isTypeAliasDeclaration(statement))
+      continue;
+    if (ts3.isExportAssignment(statement) && !statement.isExportEquals) {
+      defaultOverride = statement;
+      continue;
+    }
+    fail(`_overrides.tsx may only contain imports and a single "export default override({ ... })"`);
+  }
+  if (!defaultOverride)
+    fail(`_overrides.tsx must "export default override({ ... })"`);
+  const expression = defaultOverride.expression;
+  if (!ts3.isCallExpression(expression) || !ts3.isIdentifier(expression.expression) || expression.expression.text !== "override")
+    fail(`_overrides.tsx default export must be a call to "override", e.g. "export default override({ Modal: BrandModal })"`);
+}
 
 class Executor {
   static verbose = false;
@@ -3712,7 +3737,11 @@ class AppExecutor extends SysExecutor {
         throw new Error(`[route-convention] __root_layout is reserved for Akan.js generated root layout: ${absPath}`);
       }
       const isRootLayout = parsed.kind === "layout" && parsed.moduleSegments.at(-1) === "_layout";
-      validateRouteSourceExports(await Bun.file(absPath).text(), absPath, parsed.kind, { rootLayout: isRootLayout });
+      const routeSource = await Bun.file(absPath).text();
+      if (parsed.kind === "overrides")
+        validateOverridesSourceExports(routeSource, absPath);
+      else
+        validateRouteSourceExports(routeSource, absPath, parsed.kind, { rootLayout: isRootLayout });
       pageKeys.push(key);
     }
     pageKeys.sort();
@@ -8820,6 +8849,25 @@ async function appHasStModule(appCwdPath) {
 }
 var IMPLICIT_LAYOUT_DIR = path13.join(".akan", "generated", "root-layouts");
 var IMPLICIT_DICT_DIR = path13.join(".akan", "generated", "dict");
+var IMPLICIT_OVERRIDES_DIR = path13.join(".akan", "generated", "overrides");
+var OVERRIDES_KEY_RE = /^\.\/(.+\/)?_overrides\.(tsx|ts|jsx|js)$/;
+async function writeGeneratedOverridesLayoutFile(opts) {
+  const filename = `${opts.key.replace(/^\.\//, "").replace(/[^a-zA-Z0-9]+/g, "_")}.tsx`;
+  const absPath = path13.join(path13.resolve(opts.appCwdPath), IMPLICIT_OVERRIDES_DIR, filename);
+  const userRel = path13.relative(path13.dirname(absPath), opts.userAbsPath).split(path13.sep).join("/");
+  const userSpecifier = userRel.startsWith(".") ? userRel : `./${userRel}`;
+  const source2 = `"use client";
+import { UiOverrideProvider } from "akanjs/ui";
+import { createElement, type ReactNode } from "react";
+import value from ${JSON.stringify(userSpecifier)};
+
+export default function AkanUiOverridesLayout({ children }: { children?: ReactNode }) {
+  return createElement(UiOverrideProvider, { value }, children);
+}
+`;
+  await Bun.write(absPath, source2);
+  return absPath;
+}
 function getRootBoundarySegments(key) {
   const match = LAYOUT_KEY_RE.exec(key);
   if (!match)
@@ -9012,9 +9060,17 @@ async function resolveSsrPageEntries(opts) {
     const segments = getRootBoundarySegments(key);
     return segments !== null && isRootBoundarySegments(segments, basePaths);
   }));
-  const base = opts.pageKeys.filter((key) => !rootLayoutKeys.has(key)).map((key) => ({
-    key,
-    moduleAbsPath: path13.resolve(absPageDir, key)
+  const base = await Promise.all(opts.pageKeys.filter((key) => !rootLayoutKeys.has(key)).map(async (key) => {
+    const userAbsPath = path13.resolve(absPageDir, key);
+    if (OVERRIDES_KEY_RE.test(key)) {
+      const moduleAbsPath = await writeGeneratedOverridesLayoutFile({
+        appCwdPath: opts.appCwdPath,
+        key,
+        userAbsPath
+      });
+      return { key, moduleAbsPath, seedAbsPaths: [userAbsPath] };
+    }
+    return { key, moduleAbsPath: userAbsPath };
   }));
   const generated = await Promise.all(rootBoundaries.map(async (boundary) => ({
     key: implicitRootLayoutKey(boundary.segments),
@@ -9046,7 +9102,7 @@ function computeRouteSeedIndex(pageEntries) {
   for (const { key, moduleAbsPath, seedAbsPaths } of pageEntries) {
     const parsed = parseRouteModuleKey2(key);
     const files = [path14.resolve(moduleAbsPath), ...(seedAbsPaths ?? []).map((seed) => path14.resolve(seed))];
-    if (parsed.kind === "layout") {
+    if (parsed.kind === "layout" || parsed.kind === "overrides") {
       const prefix = parsed.routeSegments.join("/");
       const prev = layoutsByPrefix.get(prefix) ?? [];
       layoutsByPrefix.set(prefix, [...prev, ...files]);
@@ -15696,6 +15752,42 @@ var CONVENTION_SUFFIXES = [
   ".signal.ts",
   ".store.ts"
 ];
+var PAGE_RESERVED_EXPORTS = new Set([
+  "pageConfig",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "fonts",
+  "manifest",
+  "theme",
+  "reconnect",
+  "wsConnect",
+  "layoutStyle",
+  "gaTrackingId"
+]);
+var RULE_FIXES = {
+  "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 \u2014 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 \u2014 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) {
+  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];
+}
 
 class AkanQualityScanner {
   async scan(workspaceRoot) {
@@ -15711,7 +15803,7 @@ 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
     };
   }
@@ -15836,22 +15928,43 @@ class AkanQualityScanner {
   #scanComponentQuality(sourceFile2) {
     if (!isComponentDeclarationFile(sourceFile2.file))
       return [];
-    const exportedNames = getExportedDeclarationNames(sourceFile2.sourceFile);
-    const allowedInternalInterfaces = new Set([...exportedNames].map((name) => `${name}Props`));
+    const isPage = isPageRouteFile(sourceFile2.file);
+    const declarations = getComponentFileDeclarations(sourceFile2.sourceFile);
+    const compoundComponentNames = getCompoundComponentNames(sourceFile2.sourceFile);
+    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 = [];
-    for (const declaration of getInternalTypeOrFunctionDeclarations(sourceFile2.sourceFile)) {
-      if (exportedNames.has(declaration.name))
+    for (const declaration of declarations) {
+      if (declaration.isDefaultExport)
         continue;
-      if (declaration.kind === "interface" && allowedInternalInterfaces.has(declaration.name))
+      if (declaration.kind === "interface" && allowedPropsInterfaces.has(declaration.name))
         continue;
-      warnings.push({
-        rule: "akan.file.component-internal-declaration",
-        scope: "file",
-        severity: "warning",
-        file: sourceFile2.file,
-        line: declaration.line,
-        message: `Component file should not declare non-exported ${declaration.kind} "${declaration.name}". Only a "<Component>Props" interface may stay internal; move other types or helpers to a separate file in ui/, webkit/, or common/ by purpose.`
-      });
+      if (declaration.exported) {
+        if (isAllowedComponentExport(declaration, isPage))
+          continue;
+        warnings.push({
+          rule: "akan.file.component-export",
+          scope: "file",
+          severity: "warning",
+          file: sourceFile2.file,
+          line: declaration.line,
+          message: `Component file exports ${declaration.kind} "${declaration.name}", which is not a PascalCase component${isPage ? " or reserved route export" : ""}.`
+        });
+        continue;
+      }
+      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: sourceFile2.file,
+          line: declaration.line,
+          message: `Component file declares non-exported ${declaration.kind} "${declaration.name}". Only "interface <Component>Props" may stay internal.`
+        });
+      }
     }
     return warnings;
   }
@@ -15930,6 +16043,8 @@ function formatQualityWarnings(warnings) {
     if (warning.locations?.length) {
       lines.push(...warning.locations.map(({ file, line }) => `  note: related location ${formatQualityLocation(file, line)}`));
     }
+    if (warning.fix)
+      lines.push(`  fix: ${warning.fix}`);
     return lines;
   });
 }
@@ -16021,61 +16136,75 @@ function isComponentDeclarationFile(file) {
     return true;
   return root === "apps" && area === "page";
 }
-function getExportedDeclarationNames(sourceFile2) {
-  const names = new Set;
+function getComponentFileDeclarations(sourceFile2) {
+  const reExportedNames = new Set;
   for (const statement of sourceFile2.statements) {
     if (ts11.isExportDeclaration(statement) && statement.exportClause && ts11.isNamedExports(statement.exportClause)) {
-      for (const element of statement.exportClause.elements) {
-        names.add(element.name.text);
-        if (element.propertyName)
-          names.add(element.propertyName.text);
-      }
-      continue;
+      for (const element of statement.exportClause.elements)
+        reExportedNames.add((element.propertyName ?? element.name).text);
     }
-    if (!isExported(statement))
-      continue;
-    for (const name of getStatementDeclarationNames(statement))
-      names.add(name);
-  }
-  return names;
-}
-function getStatementDeclarationNames(statement) {
-  if (ts11.isFunctionDeclaration(statement) && statement.name)
-    return [statement.name.text];
-  if (ts11.isClassDeclaration(statement) && statement.name)
-    return [statement.name.text];
-  if (ts11.isInterfaceDeclaration(statement))
-    return [statement.name.text];
-  if (ts11.isTypeAliasDeclaration(statement))
-    return [statement.name.text];
-  if (ts11.isEnumDeclaration(statement))
-    return [statement.name.text];
-  if (ts11.isVariableStatement(statement)) {
-    return statement.declarationList.declarations.filter((declaration) => ts11.isIdentifier(declaration.name)).map((declaration) => declaration.name.text);
   }
-  return [];
-}
-function getInternalTypeOrFunctionDeclarations(sourceFile2) {
   const declarations = [];
   for (const statement of sourceFile2.statements) {
-    if (isExported(statement))
-      continue;
-    if (ts11.isInterfaceDeclaration(statement)) {
-      declarations.push({ name: statement.name.text, kind: "interface", line: getLine(sourceFile2, statement) });
-    } else if (ts11.isTypeAliasDeclaration(statement)) {
-      declarations.push({ name: statement.name.text, kind: "type", line: getLine(sourceFile2, statement) });
-    } else if (ts11.isFunctionDeclaration(statement) && statement.name) {
-      declarations.push({ name: statement.name.text, kind: "function", line: getLine(sourceFile2, statement) });
-    } else if (ts11.isVariableStatement(statement)) {
+    const isDefaultExport = isDefaultExportStatement(statement);
+    const inlineExported = isExported(statement);
+    const add = (name, kind, line) => declarations.push({ name, kind, line, exported: inlineExported || reExportedNames.has(name), isDefaultExport });
+    if (ts11.isInterfaceDeclaration(statement))
+      add(statement.name.text, "interface", getLine(sourceFile2, statement));
+    else if (ts11.isTypeAliasDeclaration(statement))
+      add(statement.name.text, "type", getLine(sourceFile2, statement));
+    else if (ts11.isEnumDeclaration(statement))
+      add(statement.name.text, "enum", getLine(sourceFile2, statement));
+    else if (ts11.isFunctionDeclaration(statement) && statement.name)
+      add(statement.name.text, "function", getLine(sourceFile2, statement));
+    else if (ts11.isClassDeclaration(statement) && statement.name)
+      add(statement.name.text, "class", getLine(sourceFile2, statement));
+    else if (ts11.isVariableStatement(statement)) {
       for (const declaration of statement.declarationList.declarations) {
-        if (!ts11.isIdentifier(declaration.name) || !isFunctionLikeInitializer(declaration.initializer))
+        if (!ts11.isIdentifier(declaration.name))
           continue;
-        declarations.push({ name: declaration.name.text, kind: "function", line: getLine(sourceFile2, declaration) });
+        const kind = isFunctionLikeInitializer(declaration.initializer) ? "function" : "variable";
+        add(declaration.name.text, kind, getLine(sourceFile2, declaration));
       }
     }
   }
   return declarations;
 }
+function getCompoundComponentNames(sourceFile2) {
+  const names = new Set;
+  for (const statement of sourceFile2.statements) {
+    if (!ts11.isExpressionStatement(statement))
+      continue;
+    const { expression } = statement;
+    if (!ts11.isBinaryExpression(expression) || expression.operatorToken.kind !== ts11.SyntaxKind.EqualsToken)
+      continue;
+    if (!ts11.isPropertyAccessExpression(expression.left) || !isPascalCaseName(expression.left.name.text))
+      continue;
+    names.add(expression.left.name.text);
+    if (ts11.isIdentifier(expression.right) && isPascalCaseName(expression.right.text))
+      names.add(expression.right.text);
+  }
+  return names;
+}
+function isComponentValueKind(kind) {
+  return kind === "variable" || kind === "function" || kind === "class";
+}
+function isRestrictedInternalKind(kind) {
+  return kind === "interface" || kind === "type" || kind === "function";
+}
+function isAllowedComponentExport(declaration, isPage) {
+  if (isComponentValueKind(declaration.kind) && isPascalCaseName(declaration.name))
+    return true;
+  return isPage && PAGE_RESERVED_EXPORTS.has(declaration.name);
+}
+function isPascalCaseName(name) {
+  return /^[A-Z]/.test(name) && !/^[A-Z0-9_]+$/.test(name);
+}
+function isDefaultExportStatement(statement) {
+  if (ts11.isExportAssignment(statement))
+    return !statement.isExportEquals;
+  return !!(ts11.getCombinedModifierFlags(statement) & ts11.ModifierFlags.Default);
+}
 function getPlaceholderExportWarnings(sourceFile2) {
   if (!sourceFile2.file.endsWith("/index.ts") && !sourceFile2.file.endsWith("/index.tsx"))
     return [];

package/package.json

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

package/templates/workspaceRoot/.cursor/rules/application-test-commands.mdc.template

@@ -10,7 +10,7 @@ alwaysApply: true
 - To test a built artifact locally, run it from the generated app directory with the required Akan runtime environment variables.
 
 ```bash
-cd dist/apps/<appName> && USE_AKANJS_PKGS=true AKAN_PUBLIC_REPO_NAME=akansoft AKAN_PUBLIC_SERVE_DOMAIN="akamir.com" AKAN_PUBLIC_APP_NAME=seon AKAN_PUBLIC_ENV=local AKAN_PUBLIC_OPERATION_MODE=local SERVER_MODE=federation AKAN_PUBLIC_BASE_PATHS=neul,apptest,seon bun main.js
+cd dist/apps/<appName> && USE_AKANJS_PKGS=true AKAN_PUBLIC_REPO_NAME=akansoft AKAN_PUBLIC_SERVE_DOMAIN="akanjs.com" AKAN_PUBLIC_APP_NAME=seon AKAN_PUBLIC_ENV=local AKAN_PUBLIC_OPERATION_MODE=local SERVER_MODE=federation AKAN_PUBLIC_BASE_PATHS=operator,office,homepage bun main.js
 ```
 
 - Adjust `<appName>`, `AKAN_PUBLIC_APP_NAME`, and `AKAN_PUBLIC_BASE_PATHS` to match the app being tested.

package/templates/workspaceRoot/.cursor/rules/typescript-imports.mdc.template

@@ -9,5 +9,5 @@ alwaysApply: false
 - Use Bun and ESM assumptions from the root `tsconfig.json`.
 - Prefer path aliases over deep relative imports when crossing package boundaries.
 - Use `akanjs/*` for framework facets, `@apps/*` for apps, `@libs/*` for shared libs, and `@contract/*` for contract code.
-- Respect existing client/server entrypoints such as `@libs/shared/client`, `@libs/shared/server`, `@apps/puffinplace/client`, and `@apps/puffinplace/server`.
+- Respect existing client/server entrypoints such as `@libs/shared/client`, `@libs/shared/server`, `@apps/<% appName %>/client`, and `@apps/<% appName %>/server`.
 - Let Biome organize imports instead of manually reshuffling unrelated imports.