@akanjs/cli 2.4.0 → 2.4.1-rc.1

package/quality.command-es67wvdp.js

@@ -0,0 +1,809 @@
+// @bun
+import {
+  Workspace,
+  command,
+  runner,
+  script
+} from "./index-hdqztm58.js";
+import"./index-a6sbyy0b.js";
+import"./index-61keag0s.js";
+import"./index-6pz1j0zj.js";
+import"./index-r24hmh0q.js";
+
+// pkgs/@akanjs/devkit/qualityScanner.ts
+import { createHash } from "crypto";
+import { readdir, readFile, stat } from "fs/promises";
+import path from "path";
+import ignore from "ignore";
+import ts from "typescript";
+var MAX_FILE_LINES = 2000;
+var PLACEHOLDER_EXPORT_NAMES = new Set([
+  "aa",
+  "dumb",
+  "dumb2",
+  "someBaseLogic",
+  "someCommonLogic",
+  "someFrontendLogic",
+  "someBackendLogic"
+]);
+var SUGGESTED_RULES = [
+  "Keep generated scanSync index files out of hand-written changes; generated indexes should only contain one-depth export statements.",
+  "Generated Akan index files should not contain placeholder exports such as aa, dumb, dumb2, or some*Logic.",
+  "Dictionary text should not contain scaffold wording, misspellings, or stale copied domain nouns.",
+  "Warn earlier on very long Akan files: 500 lines for services, 800 lines for Template/Zone files, and 1000 lines for Util files.",
+  "Global declarations, Window augmentation, and prototype mutation should stay in explicitly approved low-level integration files.",
+  "Keep app root folders small and conventional: application code belongs under common, env, lib, page, plugin, private, public, script, srvkit, ui, or webkit.",
+  "Keep apps/*/lib and libs/*/lib root files limited to generated support facets such as cnst.ts, db.ts, dict.ts, sig.ts, srv.ts, st.ts, useClient.ts, and useServer.ts.",
+  "Use domain module folders consistently: lib/<model> for database modules, lib/_<service> for service modules, and lib/__scalar/<scalar> for scalar modules.",
+  "Keep module UI filenames predictable: database modules use <Model>.Template/Unit/Util/View/Zone.tsx, service modules use <Service>.Util/Zone.tsx, and scalar modules use <Scalar>.Template/Unit.tsx.",
+  "Move shared app utilities to apps/*/common instead of creating apps/*/base.",
+  "Avoid large mixed-purpose class files; class export files should import helpers from neighboring utility files instead of declaring them inline."
+];
+var APP_ROOT_FILES = new Set([
+  "akan.app.json",
+  "akan.config.ts",
+  "capacitor.config.ts",
+  "client.ts",
+  "main.ts",
+  "package.json",
+  "server.ts",
+  "tsconfig.json"
+]);
+var LIB_ROOT_FILES = new Set([
+  "cnst.ts",
+  "db.ts",
+  "dict.ts",
+  "option.ts",
+  "sig.ts",
+  "srv.ts",
+  "st.ts",
+  "useClient.ts",
+  "useServer.ts"
+]);
+var CONVENTION_SUFFIXES = [
+  ".constant.ts",
+  ".dictionary.ts",
+  ".document.ts",
+  ".service.ts",
+  ".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) {
+    const targetFiles = await this.#collectTargetFiles(workspaceRoot);
+    const sourceFiles = await Promise.all(targetFiles.map((file) => this.#readSourceFile(workspaceRoot, file)));
+    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))
+    ];
+    return {
+      workspaceRoot,
+      scannedFiles: sourceFiles.length,
+      warnings: warnings.map((warning) => ({ ...warning, fix: warning.fix ?? getRuleFix(warning.rule) })).sort(compareWarnings),
+      suggestedRules: SUGGESTED_RULES
+    };
+  }
+  async#collectTargetFiles(workspaceRoot) {
+    const ignoreFilter = ignore().add(await this.#readGitIgnore(workspaceRoot));
+    const files = [];
+    for (const targetRoot of ["apps", "libs"]) {
+      const absoluteTargetRoot = path.join(workspaceRoot, targetRoot);
+      if (!await isDirectory(absoluteTargetRoot))
+        continue;
+      await this.#walkTargetFiles(workspaceRoot, absoluteTargetRoot, ignoreFilter, files);
+    }
+    return files.sort();
+  }
+  async#readGitIgnore(workspaceRoot) {
+    const gitIgnorePath = path.join(workspaceRoot, ".gitignore");
+    if (!await Bun.file(gitIgnorePath).exists())
+      return [];
+    return (await readFile(gitIgnorePath, "utf8")).split(/\r?\n/);
+  }
+  async#walkTargetFiles(workspaceRoot, currentPath, ignoreFilter, files) {
+    const entries = await readdir(currentPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolutePath = path.join(currentPath, entry.name);
+      const relativePath = toPosix(path.relative(workspaceRoot, absolutePath));
+      if (shouldSkipPath(relativePath, entry.isDirectory(), ignoreFilter))
+        continue;
+      if (entry.isDirectory()) {
+        await this.#walkTargetFiles(workspaceRoot, absolutePath, ignoreFilter, files);
+        continue;
+      }
+      if ((relativePath.endsWith(".ts") || relativePath.endsWith(".tsx")) && !relativePath.endsWith(".d.ts")) {
+        files.push(relativePath);
+      }
+    }
+  }
+  async#readSourceFile(workspaceRoot, file) {
+    const absolutePath = path.join(workspaceRoot, file);
+    const content = await readFile(absolutePath, "utf8");
+    return {
+      file,
+      absolutePath,
+      content,
+      sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, getScriptKind(file))
+    };
+  }
+  #scanGlobalQuality(sourceFiles) {
+    const exportedFunctionLikes = sourceFiles.flatMap((sourceFile) => getExportedFunctionLikes(sourceFile));
+    const warnings = [];
+    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",
+        scope: "global",
+        severity: "warning",
+        message: `Exported function or class name "${name}" is declared in ${declarations.length} files.`,
+        locations: declarations.map(({ file, line }) => ({ file, line }))
+      });
+    }
+    const declarationsWithBody = exportedFunctionLikes.filter((declaration) => declaration.bodyFingerprint);
+    for (const [fingerprint, declarations] of groupBy(declarationsWithBody, (declaration) => declaration.bodyFingerprint ?? "")) {
+      const uniqueNames = new Set(declarations.map((declaration) => declaration.name));
+      if (declarations.length < 2 || uniqueNames.size < 2 || fingerprint === "")
+        continue;
+      warnings.push({
+        rule: "akan.global.duplicate-exported-function-body",
+        scope: "global",
+        severity: "warning",
+        message: `Exported functions/classes share the same implementation body: ${declarations.map((declaration) => declaration.name).join(", ")}.`,
+        locations: declarations.map(({ file, line }) => ({ file, line }))
+      });
+    }
+    return warnings;
+  }
+  #scanSingleFileQuality(sourceFile) {
+    const warnings = [];
+    const lineCount = sourceFile.content.split(/\r?\n/).length;
+    const recommendedLineLimit = getRecommendedLineLimit(sourceFile.file);
+    if (recommendedLineLimit && lineCount > recommendedLineLimit) {
+      warnings.push({
+        rule: "akan.file.recommended-max-lines",
+        scope: "file",
+        severity: "warning",
+        file: sourceFile.file,
+        message: `File has ${lineCount} lines. Recommended limit for this file type is ${recommendedLineLimit} lines.`
+      });
+    }
+    if (lineCount > MAX_FILE_LINES) {
+      warnings.push({
+        rule: "akan.file.max-lines",
+        scope: "file",
+        severity: "warning",
+        file: sourceFile.file,
+        message: `File has ${lineCount} lines. Keep single files under ${MAX_FILE_LINES} lines.`
+      });
+    }
+    warnings.push(...getPlaceholderExportWarnings(sourceFile));
+    warnings.push(...getDictionaryTextWarnings(sourceFile));
+    warnings.push(...getGlobalMutationWarnings(sourceFile));
+    const exportedClassNames = getExportedClassNames(sourceFile.sourceFile);
+    if (exportedClassNames.length === 0)
+      return warnings;
+    const allowedInterfaceNames = new Set(exportedClassNames.map((name) => `${name}Options`));
+    for (const declaration of getTopLevelDeclarations(sourceFile)) {
+      if (declaration.kind === "class" && exportedClassNames.includes(declaration.name))
+        continue;
+      if (declaration.kind === "interface" && allowedInterfaceNames.has(declaration.name))
+        continue;
+      warnings.push({
+        rule: "akan.file.class-export-global-declaration",
+        scope: "file",
+        severity: "warning",
+        file: sourceFile.file,
+        line: declaration.line,
+        message: `Class export files should not declare top-level ${declaration.kind} "${declaration.name}". Move helpers to another file and import them.`
+      });
+    }
+    return warnings;
+  }
+  #scanComponentQuality(sourceFile) {
+    if (!isComponentDeclarationFile(sourceFile.file))
+      return [];
+    const isPage = isPageRouteFile(sourceFile.file);
+    const declarations = getComponentFileDeclarations(sourceFile.sourceFile);
+    const compoundComponentNames = getCompoundComponentNames(sourceFile.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 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;
+      }
+      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) {
+    const suffix = CONVENTION_SUFFIXES.find((candidate) => sourceFile.file.endsWith(candidate));
+    if (!suffix)
+      return [];
+    const modelName = toPascalCase(path.basename(sourceFile.file, suffix));
+    const warnings = [];
+    for (const declaration of getTopLevelDeclarations(sourceFile)) {
+      if (isAllowedConventionDeclaration(suffix, modelName, declaration))
+        continue;
+      warnings.push({
+        rule: `akan.convention${suffix.replace(".ts", "")}`,
+        scope: "convention",
+        severity: "warning",
+        file: sourceFile.file,
+        line: declaration.line,
+        message: `${path.basename(sourceFile.file)} should not declare top-level ${declaration.kind} "${declaration.name}". Allowed declarations: ${getConventionDescription(suffix, modelName)}.`
+      });
+    }
+    return warnings;
+  }
+  #scanLayoutQuality(sourceFile) {
+    const segments = sourceFile.file.split("/");
+    const warnings = [];
+    if (segments[0] === "apps" && segments.length === 3 && !APP_ROOT_FILES.has(segments[2])) {
+      warnings.push({
+        rule: "akan.layout.app-root-file",
+        scope: "layout",
+        severity: "warning",
+        file: sourceFile.file,
+        message: `Unexpected app root file "${segments[2]}". Keep application code in conventional app folders.`
+      });
+    }
+    const libRootFile = getLibRootFile(sourceFile.file);
+    if (libRootFile && !LIB_ROOT_FILES.has(libRootFile)) {
+      warnings.push({
+        rule: "akan.layout.lib-root-file",
+        scope: "layout",
+        severity: "warning",
+        file: sourceFile.file,
+        message: `Unexpected lib root file "${libRootFile}". Keep direct lib root files limited to generated support facets.`
+      });
+    }
+    const moduleUiWarning = getModuleUiWarning(sourceFile.file);
+    if (moduleUiWarning)
+      warnings.push(moduleUiWarning);
+    return warnings;
+  }
+}
+function formatQualityScanResult(result) {
+  const sections = [
+    "Akan Code Quality Scan",
+    `workspace: ${result.workspaceRoot}`,
+    `scanned files: ${result.scannedFiles}`,
+    `warnings: ${result.warnings.length}`,
+    "",
+    "Warnings:",
+    "",
+    ...formatQualityWarnings(result.warnings),
+    "",
+    "Suggested quality rules:",
+    "",
+    ...result.suggestedRules.map((rule) => `  - ${rule}`)
+  ];
+  return sections.join(`
+`);
+}
+function formatQualityWarnings(warnings) {
+  if (warnings.length === 0)
+    return ["No warnings found."];
+  return warnings.flatMap((warning) => {
+    const location = formatQualityLocation(warning.file, warning.line);
+    const lines = [`${location} - warning ${warning.rule}: ${warning.message}`];
+    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;
+  });
+}
+function formatQualityLocation(file, line) {
+  return `${file ?? "<global>"}:${line ?? 1}:1`;
+}
+function getExportedFunctionLikes(sourceFile) {
+  const declarations = [];
+  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({
+        name: statement.name.text,
+        kind: "function",
+        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)) {
+      declarations.push({
+        name: statement.name.text,
+        kind: "class",
+        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)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name) || !isFunctionLikeInitializer(declaration.initializer))
+          continue;
+        declarations.push({
+          name: declaration.name.text,
+          kind: "function-variable",
+          file: sourceFile.file,
+          line: getLine(sourceFile.sourceFile, declaration),
+          bodyFingerprint: getBodyFingerprint(sourceFile.sourceFile, declaration.initializer),
+          duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile.file, false)
+        });
+      }
+    }
+  }
+  return declarations;
+}
+function isPageRouteFile(file) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "page";
+}
+function isUiComponentFile(file) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "ui";
+}
+function isConventionDuplicateNameExempt(file, isEnumClass) {
+  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;
+  if (file.endsWith(".constant.ts"))
+    return !isEnumClass;
+  return false;
+}
+function isInLibModule(file) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments.includes("lib");
+}
+function isEnumClassStatement(sourceFile, 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) {
+  return sourceFile.statements.filter((statement) => ts.isClassDeclaration(statement) && !!statement.name).filter((statement) => isExported(statement)).map((statement) => statement.name.text);
+}
+function isComponentDeclarationFile(file) {
+  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) {
+  const reExportedNames = new Set;
+  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 = [];
+  for (const statement of sourceFile.statements) {
+    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 (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;
+}
+function getCompoundComponentNames(sourceFile) {
+  const names = new Set;
+  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) {
+  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 (ts.isExportAssignment(statement))
+    return !statement.isExportEquals;
+  return !!(ts.getCombinedModifierFlags(statement) & ts.ModifierFlags.Default);
+}
+function getPlaceholderExportWarnings(sourceFile) {
+  if (!sourceFile.file.endsWith("/index.ts") && !sourceFile.file.endsWith("/index.tsx"))
+    return [];
+  return getTopLevelDeclarations(sourceFile).filter((declaration) => declaration.exported && PLACEHOLDER_EXPORT_NAMES.has(declaration.name)).map((declaration) => ({
+    rule: "akan.file.placeholder-export",
+    scope: "file",
+    severity: "warning",
+    file: sourceFile.file,
+    line: declaration.line,
+    message: `Generated or barrel index file should not export placeholder "${declaration.name}".`
+  }));
+}
+function getDictionaryTextWarnings(sourceFile) {
+  if (!sourceFile.file.endsWith(".dictionary.ts"))
+    return [];
+  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",
+    scope: "file",
+    severity: "warning",
+    file: sourceFile.file,
+    line,
+    message: `Dictionary text appears to contain ${label}.`
+  })));
+}
+function getGlobalMutationWarnings(sourceFile) {
+  const warnings = [];
+  for (const statement of sourceFile.sourceFile.statements) {
+    if (ts.isModuleDeclaration(statement) && statement.name.getText(sourceFile.sourceFile) === "global") {
+      warnings.push({
+        rule: "akan.file.global-declaration",
+        scope: "file",
+        severity: "warning",
+        file: sourceFile.file,
+        line: getLine(sourceFile.sourceFile, statement),
+        message: "Global declarations require an explicit low-level integration allowlist."
+      });
+    }
+    if (ts.isInterfaceDeclaration(statement) && statement.name.text === "Window") {
+      warnings.push({
+        rule: "akan.file.window-augmentation",
+        scope: "file",
+        severity: "warning",
+        file: sourceFile.file,
+        line: getLine(sourceFile.sourceFile, statement),
+        message: "Window augmentation should be isolated to approved browser integration files."
+      });
+    }
+    if (ts.isExpressionStatement(statement) && statement.expression.getText(sourceFile.sourceFile).includes(".prototype.")) {
+      warnings.push({
+        rule: "akan.file.prototype-mutation",
+        scope: "file",
+        severity: "warning",
+        file: sourceFile.file,
+        line: getLine(sourceFile.sourceFile, statement),
+        message: "Prototype mutation should be avoided or isolated to approved low-level integration files."
+      });
+    }
+  }
+  return warnings;
+}
+function getTopLevelDeclarations(sourceFile) {
+  return sourceFile.sourceFile.statements.flatMap((statement) => getTopLevelDeclaration(sourceFile.sourceFile, statement));
+}
+function getTopLevelDeclaration(sourceFile, statement) {
+  const line = getLine(sourceFile, statement);
+  if (ts.isClassDeclaration(statement) && statement.name) {
+    return [{ name: statement.name.text, kind: "class", line, exported: isExported(statement), node: statement }];
+  }
+  if (ts.isFunctionDeclaration(statement) && statement.name) {
+    return [{ name: statement.name.text, kind: "function", line, exported: isExported(statement), node: statement }];
+  }
+  if (ts.isInterfaceDeclaration(statement)) {
+    return [{ name: statement.name.text, kind: "interface", line, exported: isExported(statement), node: statement }];
+  }
+  if (ts.isTypeAliasDeclaration(statement)) {
+    return [{ name: statement.name.text, kind: "type", line, exported: isExported(statement), node: statement }];
+  }
+  if (ts.isEnumDeclaration(statement)) {
+    return [{ name: statement.name.text, kind: "enum", line, exported: isExported(statement), node: statement }];
+  }
+  if (ts.isVariableStatement(statement)) {
+    return statement.declarationList.declarations.filter((declaration) => ts.isIdentifier(declaration.name)).map((declaration) => ({
+      name: declaration.name.text,
+      kind: "variable",
+      line: getLine(sourceFile, declaration),
+      exported: isExported(statement),
+      node: statement
+    }));
+  }
+  if (ts.isExportDeclaration(statement)) {
+    return [{ name: "export declaration", kind: "export", line, exported: true, node: statement }];
+  }
+  return [];
+}
+function isAllowedConventionDeclaration(suffix, modelName, declaration) {
+  if (suffix === ".dictionary.ts")
+    return isExportedConst(declaration) && declaration.name === "dictionary";
+  if (suffix === ".constant.ts")
+    return isAllowedConstantDeclaration(modelName, declaration);
+  if (suffix === ".document.ts")
+    return declaration.kind === "class" && [`${modelName}Filter`, modelName, `${modelName}Model`].includes(declaration.name);
+  if (suffix === ".service.ts")
+    return declaration.kind === "class" && declaration.name === `${modelName}Service`;
+  if (suffix === ".signal.ts")
+    return declaration.kind === "class" && [`${modelName}Internal`, `${modelName}Slice`, `${modelName}Endpoint`].includes(declaration.name);
+  if (suffix === ".store.ts")
+    return declaration.kind === "class" && declaration.name === `${modelName}Store`;
+  return false;
+}
+function isAllowedConstantDeclaration(modelName, declaration) {
+  if (declaration.kind !== "class")
+    return false;
+  if ([`${modelName}Input`, `${modelName}Object`, modelName, `Light${modelName}`, `${modelName}Insight`].includes(declaration.name))
+    return true;
+  if (!ts.isClassDeclaration(declaration.node))
+    return false;
+  const heritageClause = declaration.node.heritageClauses?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword);
+  const expression = heritageClause?.types[0]?.expression;
+  return !!expression && expression.getText().startsWith("enumOf(");
+}
+function getConventionDescription(suffix, modelName) {
+  if (suffix === ".dictionary.ts")
+    return "export const dictionary";
+  if (suffix === ".constant.ts")
+    return `${modelName}Input, ${modelName}Object, ${modelName}, Light${modelName}, ${modelName}Insight, or enumOf classes`;
+  if (suffix === ".document.ts")
+    return `${modelName}Filter, ${modelName}, or ${modelName}Model`;
+  if (suffix === ".service.ts")
+    return `${modelName}Service`;
+  if (suffix === ".signal.ts")
+    return `${modelName}Internal, ${modelName}Slice, or ${modelName}Endpoint`;
+  return `${modelName}Store`;
+}
+function getLibRootFile(file) {
+  const segments = file.split("/");
+  if ((segments[0] === "libs" || segments[0] === "apps") && segments.length === 4 && segments[2] === "lib")
+    return segments[3];
+  return null;
+}
+function getModuleUiWarning(file) {
+  if (!file.endsWith(".tsx"))
+    return null;
+  const moduleInfo = getModuleInfo(file);
+  if (!moduleInfo)
+    return null;
+  const { moduleName, fileName, kind } = moduleInfo;
+  const pascalName = toPascalCase(moduleName.replace(/^_+/, ""));
+  const allowedSuffixes = kind === "database" ? ["Template", "Unit", "Util", "View", "Zone"] : kind === "service" ? ["Util", "Zone"] : ["Template", "Unit"];
+  const allowedFileNames = new Set(allowedSuffixes.map((suffix) => `${pascalName}.${suffix}.tsx`));
+  if (allowedFileNames.has(fileName) || fileName.endsWith(".test.tsx") || fileName.endsWith(".spec.tsx"))
+    return null;
+  return {
+    rule: "akan.layout.module-ui-file",
+    scope: "layout",
+    severity: "warning",
+    file,
+    message: `Unexpected ${kind} module UI filename "${fileName}". Expected one of: ${[...allowedFileNames].join(", ")}.`
+  };
+}
+function getModuleInfo(file) {
+  const segments = file.split("/");
+  const libIndex = segments.indexOf("lib");
+  if (libIndex < 0)
+    return null;
+  const moduleName = segments[libIndex + 1];
+  if (moduleName === "__scalar") {
+    if (segments.length !== libIndex + 4)
+      return null;
+    return { moduleName: segments[libIndex + 2], fileName: segments[libIndex + 3], kind: "scalar" };
+  }
+  if (segments.length !== libIndex + 3)
+    return null;
+  const fileName = segments[libIndex + 2];
+  if (moduleName.startsWith("__")) {
+    const scalarName = moduleName === "__scalar" ? segments[libIndex + 2] : moduleName;
+    return { moduleName: scalarName, fileName, kind: "scalar" };
+  }
+  if (moduleName.startsWith("_"))
+    return { moduleName, fileName, kind: "service" };
+  return { moduleName, fileName, kind: "database" };
+}
+function isExportedConst(declaration) {
+  return declaration.exported && ts.isVariableStatement(declaration.node) && (declaration.node.declarationList.flags & ts.NodeFlags.Const) !== 0;
+}
+function isExported(node) {
+  return !!ts.getCombinedModifierFlags(node) && !!(ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Export);
+}
+function isFunctionLikeInitializer(node) {
+  return !!node && (ts.isArrowFunction(node) || ts.isFunctionExpression(node));
+}
+function getBodyFingerprint(sourceFile, node) {
+  if (!node)
+    return;
+  const normalizedBody = node.getText(sourceFile).replace(/\s+/g, " ").trim();
+  if (normalizedBody.length < 80)
+    return;
+  return createHash("sha256").update(normalizedBody).digest("hex");
+}
+function shouldSkipPath(relativePath, isDirectory, ignoreFilter) {
+  const ignorePath = isDirectory ? `${relativePath}/` : relativePath;
+  return relativePath === ".git" || relativePath.includes("/.git/") || relativePath.includes("/node_modules/") || ignoreFilter.ignores(relativePath) || ignoreFilter.ignores(ignorePath);
+}
+async function isDirectory(absolutePath) {
+  try {
+    return (await stat(absolutePath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function getScriptKind(file) {
+  return file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+}
+function getLine(sourceFile, node) {
+  return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+}
+function getRecommendedLineLimit(file) {
+  if (file.endsWith(".service.ts"))
+    return 500;
+  if (file.endsWith(".Template.tsx") || file.endsWith(".Zone.tsx"))
+    return 800;
+  if (file.endsWith(".Util.tsx"))
+    return 1000;
+  return null;
+}
+function findPatternLines(content, pattern) {
+  return content.split(/\r?\n/).flatMap((line, index) => pattern.test(line) ? [index + 1] : []);
+}
+function toPascalCase(value) {
+  return value.replace(/(^|[-_./])([a-zA-Z0-9])/g, (_, __, char) => char.toUpperCase()).replace(/[-_./]/g, "");
+}
+function toPosix(value) {
+  return value.split(path.sep).join("/");
+}
+function groupBy(items, getKey) {
+  const grouped = new Map;
+  for (const item of items) {
+    const key = getKey(item);
+    grouped.set(key, [...grouped.get(key) ?? [], item]);
+  }
+  return grouped;
+}
+function compareWarnings(a, b) {
+  return a.scope.localeCompare(b.scope) || (a.file ?? "").localeCompare(b.file ?? "") || (a.line ?? 0) - (b.line ?? 0) || a.rule.localeCompare(b.rule);
+}
+
+// pkgs/@akanjs/cli/quality/quality.script.ts
+import { Logger } from "akanjs/common";
+
+// pkgs/@akanjs/cli/quality/quality.runner.ts
+class QualityRunner extends runner("quality") {
+  async scan(workspace) {
+    return await new AkanQualityScanner().scan(workspace.workspaceRoot);
+  }
+}
+
+// pkgs/@akanjs/cli/quality/quality.script.ts
+class QualityScript extends script("quality", [QualityRunner]) {
+  async scan(workspace, format = "text") {
+    const spinner = workspace.spinning("Scanning Akan code quality...");
+    const result = await this.qualityRunner.scan(workspace);
+    spinner.succeed(`Quality scan completed (${result.scannedFiles} files, ${result.warnings.length} warnings)`);
+    Logger.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatQualityScanResult(result));
+  }
+}
+
+// pkgs/@akanjs/cli/quality/quality.command.ts
+class QualityCommand extends command("quality", [QualityScript], ({ public: target }) => ({
+  quality: target({ desc: "Scan apps and libs for Akan code quality warnings" }).arg("action", String, {
+    desc: "quality action",
+    default: "scan",
+    enum: ["scan"]
+  }).option("format", String, {
+    desc: "output format",
+    default: "text",
+    enum: ["text", "json"]
+  }).with(Workspace).exec(async function(action, format, workspace) {
+    if (action !== "scan")
+      throw new Error(`Unknown quality action: ${action}. Use "scan".`);
+    await this.qualityScript.scan(workspace, format);
+  })
+})) {
+}
+export {
+  QualityCommand
+};