@akanjs/cli 3.0.0-beta.9 → 3.0.1

package/{quality.command-6gsna0a3.js → quality.command-8122axq3.js}

@@ -1,29 +1,89 @@
 // @bun
 import {
   Workspace,
-  runner,
   script,
   command
-} from "./index-0g7r8xz3.js";
-import"./index-q0y2jq9j.js";
+} from "./index-a37by9hn.js";
+import"./index-52w0fvh8.js";
 import {
   rootAllowedFiles,
   rootAllowedDirs,
-  isAllowedLibFacetRootFile
-} from "./index-2tv3fdx4.js";
-import"./index-6wwzs1bc.js";
-import {
-  AbstractDoc
-} from "./index-meh558jy.js";
+  isAllowedLibFacetRootFile,
+  rootEntryHintOf
+} from "./index-150s07n8.js";
 
 // pkgs/@akanjs/devkit/qualityScanner.ts
 import { createHash } from "crypto";
 import { readdir, readFile, stat } from "fs/promises";
-import path from "path";
+import path2 from "path";
 import { RESERVED_ROUTE_CONFIG_EXPORTS } from "akanjs/common";
 import ignore from "ignore";
 import ts3 from "typescript";
 
+// pkgs/@akanjs/devkit/abstractDoc.ts
+import path from "path";
+
+class AbstractDoc {
+  path;
+  content;
+  siblingFiles;
+  static suffix = ".abstract.md";
+  static maxLines = 300;
+  static #facetRoots = "{lib,ui,webkit,srvkit,common,plugin}";
+  static isAbstractPath(filePath) {
+    return filePath.endsWith(AbstractDoc.suffix);
+  }
+  static lineCountOf(content) {
+    return content.split(/\r?\n/).length;
+  }
+  static kindOf(filePath) {
+    const [root, folder, ...rest] = filePath.split("/");
+    if (root !== "lib" || !folder)
+      return "other";
+    if (folder === "__scalar")
+      return rest.length === 2 ? "scalar" : "other";
+    if (rest.length !== 1)
+      return "other";
+    return folder.startsWith("_") ? "service" : "domain";
+  }
+  static async findAll(sys, { module } = {}) {
+    const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`)).map((filePath) => filePath.split(path.sep).join("/")).sort();
+    const docs = await Promise.all(filePaths.map((filePath) => AbstractDoc.read(sys, filePath)));
+    if (!module)
+      return docs;
+    return docs.filter((doc) => doc.moduleName === module || doc.folderName === module);
+  }
+  static async read(sys, filePath) {
+    const dirPath = filePath.split("/").slice(0, -1).join("/");
+    const [content, folderFiles] = await Promise.all([sys.readFile(filePath), sys.readdir(dirPath)]);
+    return new AbstractDoc(filePath, content, folderFiles.filter((fileName) => !AbstractDoc.isAbstractPath(fileName)));
+  }
+  constructor(path2, content, siblingFiles) {
+    this.path = path2;
+    this.content = content;
+    this.siblingFiles = siblingFiles;
+  }
+  get kind() {
+    return AbstractDoc.kindOf(this.path);
+  }
+  get folderName() {
+    return this.path.split("/").at(-2) ?? "";
+  }
+  get moduleName() {
+    return (this.path.split("/").at(-1) ?? "").slice(0, -AbstractDoc.suffix.length);
+  }
+  get lineCount() {
+    return AbstractDoc.lineCountOf(this.content);
+  }
+  canReplaceWith(candidate) {
+    const next = candidate.trim();
+    if (!next.startsWith("#"))
+      return false;
+    const lineCount = AbstractDoc.lineCountOf(next);
+    return lineCount >= 3 && lineCount < this.lineCount;
+  }
+}
+
 // pkgs/@akanjs/devkit/formSetterScanner.ts
 import ts from "typescript";
 
@@ -99,25 +159,11 @@ var STATIC_COMPONENT_MIN_MASS = 4;
 var MIXED_COMPONENT_MIN_MASS = 10;
 var MIXED_COMPONENT_MAX_TOUCHES = 2;
 var MODULE_SERVER_VIEW_MIN_CLIENT_MASS = 12;
+var fileWarning = (rule, scope, file, message, line) => line === undefined ? { rule, scope, severity: "warning", file, message } : { rule, scope, severity: "warning", file, line, message };
 
 class SsrScanner {
   static #serverSafeCalls = new Set(["usePage", "getSelf", "useServer"]);
-  static #clientGlobals = new Set([
-    "window",
-    "document",
-    "navigator",
-    "localStorage",
-    "sessionStorage",
-    "location",
-    "history",
-    "screen",
-    "matchMedia",
-    "IntersectionObserver",
-    "ResizeObserver",
-    "MutationObserver",
-    "requestAnimationFrame",
-    "WebSocket"
-  ]);
+  static #clientGlobals = new Set("window document navigator localStorage sessionStorage location history screen matchMedia IntersectionObserver".split(" ").concat("ResizeObserver MutationObserver requestAnimationFrame WebSocket".split(" ")));
   static #clientRuntimeImports = new Set(["st", "fetch"]);
   scan(sourceFiles) {
     const componentFiles = sourceFiles.filter((sourceFile) => this.#isBalancedFile(sourceFile.file));
@@ -138,38 +184,17 @@ class SsrScanner {
     const components = this.#getComponents(sourceFile, vendorNames);
     const warnings = [];
     if (!hasVendorImport && !importsClientRuntime && this.#getTouches(sourceFile.sourceFile, sourceFile.sourceFile).length === 0 && !this.#isConventionClientFile(sourceFile.file)) {
-      warnings.push({
-        rule: "akan.ssr.unnecessary-use-client",
-        scope: "ssr",
-        severity: "warning",
-        file: sourceFile.file,
-        line: 1,
-        message: `"use client" is declared but the file uses no client-only capability (hook, event handler, store, or browser API).`
-      });
+      warnings.push(fileWarning("akan.ssr.unnecessary-use-client", "ssr", sourceFile.file, `"use client" is declared but the file uses no client-only capability (hook, event handler, store, or browser API).`, 1));
     }
     for (const component of components) {
       if (component.vendorTags)
         continue;
       if (component.touches.length === 0 && component.mass >= STATIC_COMPONENT_MIN_MASS) {
-        warnings.push({
-          rule: "akan.ssr.client-static-component",
-          scope: "ssr",
-          severity: "warning",
-          file: sourceFile.file,
-          line: component.line,
-          message: `Client component "${component.name}" renders ${component.mass} JSX elements with no client-only capability. It is server-renderable markup sitting in the client bundle.`
-        });
+        warnings.push(fileWarning("akan.ssr.client-static-component", "ssr", sourceFile.file, `Client component "${component.name}" renders ${component.mass} JSX elements with no client-only capability. It is server-renderable markup sitting in the client bundle.`, component.line));
         continue;
       }
       if (component.touches.length >= 1 && component.touches.length <= MIXED_COMPONENT_MAX_TOUCHES && component.mass >= MIXED_COMPONENT_MIN_MASS) {
-        warnings.push({
-          rule: "akan.ssr.client-static-markup",
-          scope: "ssr",
-          severity: "warning",
-          file: sourceFile.file,
-          line: component.line,
-          message: `Client component "${component.name}" renders ${component.mass} JSX elements around only ${component.touches.length} client-only touch (${[...new Set(component.touches)].join(", ")}). Most of this subtree does not need the client bundle.`
-        });
+        warnings.push(fileWarning("akan.ssr.client-static-markup", "ssr", sourceFile.file, `Client component "${component.name}" renders ${component.mass} JSX elements around only ${component.touches.length} client-only touch (${[...new Set(component.touches)].join(", ")}). Most of this subtree does not need the client bundle.`, component.line));
       }
     }
     warnings.push(...this.#getMountLoadWarnings(sourceFile));
@@ -189,32 +214,16 @@ class SsrScanner {
         entry.serverFiles += 1;
       modules.set(moduleDir, entry);
     }
-    return [...modules].filter(([, entry]) => entry.serverFiles === 0 && entry.clientMass >= MODULE_SERVER_VIEW_MIN_CLIENT_MASS).map(([moduleDir, entry]) => ({
-      rule: "akan.ssr.module-missing-server-view",
-      scope: "ssr",
-      severity: "warning",
-      file: entry.line,
-      message: `Module "${moduleDir}" renders ${entry.clientMass} JSX elements from client files only; it declares no Unit or View server component.`
-    }));
+    return [...modules].filter(([, entry]) => entry.serverFiles === 0 && entry.clientMass >= MODULE_SERVER_VIEW_MIN_CLIENT_MASS).map(([moduleDir, entry]) => fileWarning("akan.ssr.module-missing-server-view", "ssr", entry.line, `Module "${moduleDir}" renders ${entry.clientMass} JSX elements from client files only; it declares no Unit or View server component.`));
   }
   #getMountLoadWarnings(sourceFile) {
     const warnings = [];
-    const visit = (node) => {
-      if (this.#isMountEffect(sourceFile.sourceFile, node)) {
-        for (const load of this.#getLoadCalls(sourceFile.sourceFile, node)) {
-          warnings.push({
-            rule: "akan.ssr.client-mount-load",
-            scope: "ssr",
-            severity: "warning",
-            file: sourceFile.file,
-            line: this.#getLine(sourceFile.sourceFile, load.node),
-            message: `Mount-only effect loads server data with ${load.callee}(). The route can fetch this before the first byte instead.`
-          });
-        }
-      }
-      ts2.forEachChild(node, visit);
-    };
-    ts2.forEachChild(sourceFile.sourceFile, visit);
+    SsrScanner.#walk(sourceFile.sourceFile, (node) => {
+      if (!this.#isMountEffect(sourceFile.sourceFile, node))
+        return;
+      for (const load of this.#getLoadCalls(sourceFile.sourceFile, node))
+        warnings.push(fileWarning("akan.ssr.client-mount-load", "ssr", sourceFile.file, `Mount-only effect loads server data with ${load.callee}(). The route can fetch this before the first byte instead.`, this.#getLine(sourceFile.sourceFile, load.node)));
+    });
     return warnings;
   }
   #isMountEffect(sourceFile, node) {
@@ -228,35 +237,23 @@ class SsrScanner {
   }
   #getLoadCalls(sourceFile, node) {
     const calls = [];
-    const visit = (child) => {
-      if (ts2.isCallExpression(child)) {
-        const callee = child.expression.getText(sourceFile);
-        if (/^fetch\.[a-z]/.test(callee) || /^st\.do\.(init|get|view|load|list|count|insight)[A-Z]/.test(callee))
-          calls.push({ callee, node: child });
-      }
-      ts2.forEachChild(child, visit);
-    };
-    ts2.forEachChild(node, visit);
+    SsrScanner.#walk(node, (child) => {
+      if (!ts2.isCallExpression(child))
+        return;
+      const callee = child.expression.getText(sourceFile);
+      if (/^fetch\.[a-z]/.test(callee) || /^st\.do\.(init|get|view|load|list|count|insight)[A-Z]/.test(callee))
+        calls.push({ callee, node: child });
+    });
     return calls;
   }
   #getTemplateStateWarnings(sourceFile) {
     if (!sourceFile.file.endsWith(".Template.tsx"))
       return [];
     const warnings = [];
-    const visit = (node) => {
-      if (ts2.isCallExpression(node) && node.expression.getText(sourceFile.sourceFile) === "useState") {
-        warnings.push({
-          rule: "akan.ssr.template-client-state",
-          scope: "ssr",
-          severity: "warning",
-          file: sourceFile.file,
-          line: this.#getLine(sourceFile.sourceFile, node),
-          message: "Template holds form state in useState. Templates are store-driven and carry no local state."
-        });
-      }
-      ts2.forEachChild(node, visit);
-    };
-    ts2.forEachChild(sourceFile.sourceFile, visit);
+    SsrScanner.#walk(sourceFile.sourceFile, (node) => {
+      if (ts2.isCallExpression(node) && node.expression.getText(sourceFile.sourceFile) === "useState")
+        warnings.push(fileWarning("akan.ssr.template-client-state", "ssr", sourceFile.file, "Template holds form state in useState. Templates are store-driven and carry no local state.", this.#getLine(sourceFile.sourceFile, node)));
+    });
     return warnings;
   }
   #measureBalance(sourceFiles) {
@@ -311,7 +308,7 @@ class SsrScanner {
   }
   #getTouches(sourceFile, node) {
     const touches = [];
-    const visit = (child) => {
+    SsrScanner.#walk(node, (child) => {
       if (ts2.isCallExpression(child)) {
         const callee = child.expression.getText(sourceFile);
         const bareName = callee.split(".").pop() ?? callee;
@@ -329,31 +326,32 @@ class SsrScanner {
         else if (SsrScanner.#clientGlobals.has(root))
           touches.push(root);
       }
-      ts2.forEachChild(child, visit);
-    };
-    ts2.forEachChild(node, visit);
+    });
     return touches;
   }
   #getTagNames(sourceFile, node) {
     const tags = new Set;
-    const visit = (child) => {
+    SsrScanner.#walk(node, (child) => {
       if (ts2.isJsxOpeningElement(child) || ts2.isJsxSelfClosingElement(child))
         tags.add(child.tagName.getText(sourceFile).split(".")[0]);
-      ts2.forEachChild(child, visit);
-    };
-    ts2.forEachChild(node, visit);
+    });
     return tags;
   }
   #getMass(node) {
     let mass = 0;
-    const visit = (child) => {
+    SsrScanner.#walk(node, (child) => {
       if (ts2.isJsxOpeningElement(child) || ts2.isJsxSelfClosingElement(child))
         mass += 1;
-      ts2.forEachChild(child, visit);
-    };
-    ts2.forEachChild(node, visit);
+    });
     return mass;
   }
+  static #walk(node, visit) {
+    const walk = (child) => {
+      visit(child);
+      ts2.forEachChild(child, walk);
+    };
+    ts2.forEachChild(node, walk);
+  }
   #hasUseClient(sourceFile) {
     const first = sourceFile.statements[0];
     if (!first || !ts2.isExpressionStatement(first) || !ts2.isStringLiteral(first.expression))
@@ -491,7 +489,7 @@ var RULE_FIXES = {
   "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.abstract-max-lines": "Run `akan compact <app-or-lib>` to rewrite the abstract with the AI editor, keeping only the invariants and workflows the source files cannot show.",
+  "akan.file.abstract-max-lines": "Trim the abstract by hand to a title, one sentence naming what the module owns, a `## Rules` list of the invariants the source cannot show, and an optional workflow chain.",
   "akan.file.placeholder-export": "Remove the placeholder export; generated indexes should only re-export real modules.",
   "akan.file.bang-comment-in-client": "Rewrite the marker as `// FIXME:` or `// TODO:`. Keep the bang form for server, srvkit, and CLI files.",
   "akan.file.dictionary-stale-text": "Replace the scaffold text with real localized copy for this dictionary entry.",
@@ -549,7 +547,7 @@ class AkanQualityScanner {
     const ignoreFilter = ignore().add(await this.#readGitIgnore(workspaceRoot));
     const files = [];
     for (const targetRoot of ["apps", "libs"]) {
-      const absoluteTargetRoot = path.join(workspaceRoot, targetRoot);
+      const absoluteTargetRoot = path2.join(workspaceRoot, targetRoot);
       if (!await isDirectory(absoluteTargetRoot))
         continue;
       await this.#walkTargetFiles(workspaceRoot, absoluteTargetRoot, ignoreFilter, files);
@@ -557,7 +555,7 @@ class AkanQualityScanner {
     return files.sort();
   }
   async#readGitIgnore(workspaceRoot) {
-    const gitIgnorePath = path.join(workspaceRoot, ".gitignore");
+    const gitIgnorePath = path2.join(workspaceRoot, ".gitignore");
     if (!await Bun.file(gitIgnorePath).exists())
       return [];
     return (await readFile(gitIgnorePath, "utf8")).split(/\r?\n/);
@@ -565,8 +563,8 @@ class AkanQualityScanner {
   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));
+      const absolutePath = path2.join(currentPath, entry.name);
+      const relativePath = toPosix(path2.relative(workspaceRoot, absolutePath));
       if (shouldSkipPath(relativePath, entry.isDirectory(), ignoreFilter))
         continue;
       if (entry.isDirectory()) {
@@ -581,7 +579,7 @@ class AkanQualityScanner {
     }
   }
   async#readSourceFile(workspaceRoot, file) {
-    const absolutePath = path.join(workspaceRoot, file);
+    const absolutePath = path2.join(workspaceRoot, file);
     const content = await readFile(absolutePath, "utf8");
     return {
       file,
@@ -591,7 +589,7 @@ class AkanQualityScanner {
     };
   }
   async#readTextFile(workspaceRoot, file) {
-    return { file, content: await readFile(path.join(workspaceRoot, file), "utf8") };
+    return { file, content: await readFile(path2.join(workspaceRoot, file), "utf8") };
   }
   #scanGlobalQuality(sourceFiles) {
     const exportedFunctionLikes = sourceFiles.flatMap((sourceFile) => getExportedFunctionLikes(sourceFile));
@@ -627,24 +625,10 @@ class AkanQualityScanner {
     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.`
-      });
-    }
+    if (recommendedLineLimit && lineCount > recommendedLineLimit)
+      warnings.push(fileWarning("akan.file.recommended-max-lines", "file", sourceFile.file, `File has ${lineCount} lines. Recommended limit for this file type is ${recommendedLineLimit} lines.`));
+    if (lineCount > MAX_FILE_LINES)
+      warnings.push(fileWarning("akan.file.max-lines", "file", sourceFile.file, `File has ${lineCount} lines. Keep single files under ${MAX_FILE_LINES} lines.`));
     warnings.push(...getBangCommentWarnings(sourceFile));
     warnings.push(...getPlaceholderExportWarnings(sourceFile));
     warnings.push(...getDictionaryTextWarnings(sourceFile));
@@ -658,14 +642,7 @@ class AkanQualityScanner {
         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.`
-      });
+      warnings.push(fileWarning("akan.file.class-export-global-declaration", "file", sourceFile.file, `Class export files should not declare top-level ${declaration.kind} "${declaration.name}". Move helpers to another file and import them.`, declaration.line));
     }
     return warnings;
   }
@@ -687,28 +664,13 @@ class AkanQualityScanner {
       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" : ""}.`
-        });
+        warnings.push(fileWarning("akan.file.component-export", "file", sourceFile.file, `Component file exports ${declaration.kind} "${declaration.name}", which is not a PascalCase component${isPage ? " or reserved route export" : ""}.`, declaration.line));
         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.`
-        });
-      }
+      if (isRestrictedInternalKind(declaration.kind))
+        warnings.push(fileWarning("akan.file.component-internal-declaration", "file", sourceFile.file, `Component file declares non-exported ${declaration.kind} "${declaration.name}". Only "interface <Component>Props" may stay internal.`, declaration.line));
     }
     return warnings;
   }
@@ -716,34 +678,15 @@ class AkanQualityScanner {
     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;
+    const modelName = toPascalCase(path2.basename(sourceFile.file, suffix));
+    return getTopLevelDeclarations(sourceFile).filter((declaration) => !isAllowedConventionDeclaration(suffix, modelName, declaration)).map((declaration) => fileWarning(`akan.convention${suffix.replace(".ts", "")}`, "convention", sourceFile.file, `${path2.basename(sourceFile.file)} should not declare top-level ${declaration.kind} "${declaration.name}". Allowed declarations: ${getConventionDescription(suffix, modelName)}.`, declaration.line));
   }
   #scanAbstractQuality({ file, content }) {
     const lineCount = AbstractDoc.lineCountOf(content);
     if (lineCount <= AbstractDoc.maxLines)
       return [];
     return [
-      {
-        rule: "akan.file.abstract-max-lines",
-        scope: "file",
-        severity: "warning",
-        file,
-        message: `Abstract has ${lineCount} lines. Keep abstracts under ${AbstractDoc.maxLines} lines and compact them periodically.`
-      }
+      fileWarning("akan.file.abstract-max-lines", "file", file, `Abstract has ${lineCount} lines. Keep abstracts under ${AbstractDoc.maxLines} lines and compact them periodically.`)
     ];
   }
   #scanLayoutQuality(sourceFile) {
@@ -753,26 +696,12 @@ class AkanQualityScanner {
       const { type, name, isDir } = rootEntry;
       const allowed = isDir ? rootAllowedDirs[type].has(name) : rootAllowedFiles[type].has(name);
       const kind = isDir ? "folder" : "file";
-      if (!allowed) {
-        warnings.push({
-          rule: `akan.layout.${type}-root-${kind}`,
-          scope: "layout",
-          severity: "warning",
-          file: sourceFile.file,
-          message: `Unexpected ${type} root ${kind} "${name}". Keep ${type} code in conventional ${type} folders.`
-        });
-      }
+      if (!allowed)
+        warnings.push(fileWarning(`akan.layout.${type}-root-${kind}`, "layout", sourceFile.file, `Unexpected ${type} root ${kind} "${name}". ${rootEntryHintOf(type, name) ?? `Keep ${type} code in conventional ${type} folders.`}`));
     }
     const libFacetFile = getLibFacetRootFile(sourceFile.file);
-    if (libFacetFile && !isAllowedLibFacetRootFile(libFacetFile)) {
-      warnings.push({
-        rule: "akan.layout.lib-facet-file",
-        scope: "layout",
-        severity: "warning",
-        file: sourceFile.file,
-        message: `Unexpected lib facet root file "${libFacetFile}". Keep direct lib/ root files limited to generated support facets.`
-      });
-    }
+    if (libFacetFile && !isAllowedLibFacetRootFile(libFacetFile))
+      warnings.push(fileWarning("akan.layout.lib-facet-file", "layout", sourceFile.file, `Unexpected lib facet root file "${libFacetFile}". Keep direct lib/ root files limited to generated support facets.`));
     const moduleUiWarning = getModuleUiWarning(sourceFile.file);
     if (moduleUiWarning)
       warnings.push(moduleUiWarning);
@@ -839,67 +768,48 @@ function formatQualityLocation(file, line) {
 function getExportedFunctionLikes(sourceFile) {
   const declarations = [];
   const nameExempt = isPageRouteFile(sourceFile.file) || isUiComponentFile(sourceFile.file);
+  const add = (name, kind, node, body, isEnumClass = false) => declarations.push({
+    name,
+    kind,
+    file: sourceFile.file,
+    line: getLine(sourceFile.sourceFile, node),
+    bodyFingerprint: getBodyFingerprint(sourceFile.sourceFile, body),
+    duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile.file, isEnumClass)
+  });
   for (const statement of sourceFile.sourceFile.statements) {
-    if (ts3.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 (ts3.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 (ts3.isFunctionDeclaration(statement) && statement.name && isExported(statement))
+      add(statement.name.text, "function", statement, statement.body);
+    if (ts3.isClassDeclaration(statement) && statement.name && isExported(statement))
+      add(statement.name.text, "class", statement, statement, isEnumClassStatement(sourceFile.sourceFile, statement));
     if (ts3.isVariableStatement(statement) && isExported(statement)) {
       for (const declaration of statement.declarationList.declarations) {
         if (!ts3.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)
-        });
+        add(declaration.name.text, "function-variable", declaration, declaration.initializer);
       }
     }
   }
   return declarations;
 }
-function isPageRouteFile(file) {
+function sysSegments(file) {
   const segments = file.split("/");
-  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "page";
+  return segments[0] === "apps" || segments[0] === "libs" ? segments : null;
+}
+function isPageRouteFile(file) {
+  return sysSegments(file)?.[2] === "page";
 }
 function isUiComponentFile(file) {
-  const segments = file.split("/");
-  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "ui";
+  return sysSegments(file)?.[2] === "ui";
 }
 function isConventionDuplicateNameExempt(file, isEnumClass) {
-  if (!isInLibModule(file))
+  if (!sysSegments(file)?.includes("lib"))
     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"))
+  if (file.endsWith(".tsx") || /\.(document|service|signal|store)\.ts$/.test(file))
     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 (!ts3.isClassDeclaration(statement))
     return false;
@@ -995,14 +905,7 @@ function isDefaultExportStatement(statement) {
 function getBangCommentWarnings(sourceFile) {
   if (!isClientReachableFile(sourceFile.file))
     return [];
-  return findPatternLines(sourceFile.content, /(?:^|[^\s/][ \t]+)\/[*/]!/).map((line) => ({
-    rule: "akan.file.bang-comment-in-client",
-    scope: "file",
-    severity: "warning",
-    file: sourceFile.file,
-    line,
-    message: "A `//!` or `/*!` marker survives minification and ships to the browser."
-  }));
+  return findPatternLines(sourceFile.content, /(?:^|[^\s/][ \t]+)\/[*/]!/).map((line) => fileWarning("akan.file.bang-comment-in-client", "file", sourceFile.file, "A `//!` or `/*!` marker survives minification and ships to the browser.", line));
 }
 function isClientReachableFile(file) {
   if (/\.(test|spec)\.tsx?$/.test(file))
@@ -1021,61 +924,24 @@ function isClientReachableFile(file) {
 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}".`
-  }));
+  return getTopLevelDeclarations(sourceFile).filter((declaration) => declaration.exported && PLACEHOLDER_EXPORT_NAMES.has(declaration.name)).map((declaration) => fileWarning("akan.file.placeholder-export", "file", sourceFile.file, `Generated or barrel index file should not export placeholder "${declaration.name}".`, declaration.line));
 }
 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}.`
-  })));
+  return stalePatterns.flatMap(({ pattern, label }) => findPatternLines(sourceFile.content, pattern).map((line) => fileWarning("akan.file.dictionary-stale-text", "file", sourceFile.file, `Dictionary text appears to contain ${label}.`, line)));
 }
 function getGlobalMutationWarnings(sourceFile) {
   const warnings = [];
   for (const statement of sourceFile.sourceFile.statements) {
-    if (ts3.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 (ts3.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 (ts3.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."
-      });
-    }
+    const warn = (rule, message) => warnings.push(fileWarning(rule, "file", sourceFile.file, message, getLine(sourceFile.sourceFile, statement)));
+    if (ts3.isModuleDeclaration(statement) && statement.name.getText(sourceFile.sourceFile) === "global")
+      warn("akan.file.global-declaration", "Global declarations require an explicit low-level integration allowlist.");
+    if (ts3.isInterfaceDeclaration(statement) && statement.name.text === "Window")
+      warn("akan.file.window-augmentation", "Window augmentation should be isolated to approved browser integration files.");
+    if (ts3.isExpressionStatement(statement) && statement.expression.getText(sourceFile.sourceFile).includes(".prototype."))
+      warn("akan.file.prototype-mutation", "Prototype mutation should be avoided or isolated to approved low-level integration files.");
   }
   return warnings;
 }
@@ -1084,73 +950,59 @@ function getTopLevelDeclarations(sourceFile) {
 }
 function getTopLevelDeclaration(sourceFile, statement) {
   const line = getLine(sourceFile, statement);
-  if (ts3.isClassDeclaration(statement) && statement.name) {
-    return [{ name: statement.name.text, kind: "class", line, exported: isExported(statement), node: statement }];
-  }
-  if (ts3.isFunctionDeclaration(statement) && statement.name) {
-    return [{ name: statement.name.text, kind: "function", line, exported: isExported(statement), node: statement }];
-  }
-  if (ts3.isInterfaceDeclaration(statement)) {
-    return [{ name: statement.name.text, kind: "interface", line, exported: isExported(statement), node: statement }];
-  }
-  if (ts3.isTypeAliasDeclaration(statement)) {
-    return [{ name: statement.name.text, kind: "type", line, exported: isExported(statement), node: statement }];
-  }
-  if (ts3.isEnumDeclaration(statement)) {
-    return [{ name: statement.name.text, kind: "enum", line, exported: isExported(statement), node: statement }];
-  }
-  if (ts3.isVariableStatement(statement)) {
-    return statement.declarationList.declarations.filter((declaration) => ts3.isIdentifier(declaration.name)).map((declaration) => ({
-      name: declaration.name.text,
-      kind: "variable",
-      line: getLine(sourceFile, declaration),
-      exported: isExported(statement),
-      node: statement
-    }));
-  }
-  if (ts3.isExportDeclaration(statement)) {
+  const declared = (name, kind, at = line) => ({
+    name,
+    kind,
+    line: at,
+    exported: isExported(statement),
+    node: statement
+  });
+  if (ts3.isClassDeclaration(statement) && statement.name)
+    return [declared(statement.name.text, "class")];
+  if (ts3.isFunctionDeclaration(statement) && statement.name)
+    return [declared(statement.name.text, "function")];
+  if (ts3.isInterfaceDeclaration(statement))
+    return [declared(statement.name.text, "interface")];
+  if (ts3.isTypeAliasDeclaration(statement))
+    return [declared(statement.name.text, "type")];
+  if (ts3.isEnumDeclaration(statement))
+    return [declared(statement.name.text, "enum")];
+  if (ts3.isVariableStatement(statement))
+    return statement.declarationList.declarations.filter((declaration) => ts3.isIdentifier(declaration.name)).map((declaration) => declared(declaration.name.text, "variable", getLine(sourceFile, declaration)));
+  if (ts3.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";
+function getConventionClassNames(suffix, model) {
   if (suffix === ".constant.ts")
-    return isAllowedConstantDeclaration(modelName, declaration);
+    return [`${model}Input`, `${model}Object`, model, `Light${model}`, `${model}Insight`];
   if (suffix === ".document.ts")
-    return declaration.kind === "class" && [`${modelName}Filter`, modelName, `${modelName}Model`].includes(declaration.name);
+    return [`${model}Filter`, model, `${model}Model`];
   if (suffix === ".service.ts")
-    return declaration.kind === "class" && declaration.name === `${modelName}Service`;
+    return [`${model}Service`];
   if (suffix === ".signal.ts")
-    return declaration.kind === "class" && [`${modelName}Internal`, `${modelName}Slice`, `${modelName}Endpoint`].includes(declaration.name);
+    return [`${model}Internal`, `${model}Slice`, `${model}Endpoint`];
   if (suffix === ".store.ts")
-    return declaration.kind === "class" && declaration.name === `${modelName}Store`;
-  return false;
+    return [`${model}Store`];
+  return [];
 }
-function isAllowedConstantDeclaration(modelName, declaration) {
+function isAllowedConventionDeclaration(suffix, modelName, declaration) {
+  if (suffix === ".dictionary.ts")
+    return isExportedConst(declaration) && declaration.name === "dictionary";
   if (declaration.kind !== "class")
     return false;
-  if ([`${modelName}Input`, `${modelName}Object`, modelName, `Light${modelName}`, `${modelName}Insight`].includes(declaration.name))
+  if (getConventionClassNames(suffix, modelName).includes(declaration.name))
     return true;
-  if (!ts3.isClassDeclaration(declaration.node))
-    return false;
-  const heritageClause = declaration.node.heritageClauses?.find((clause) => clause.token === ts3.SyntaxKind.ExtendsKeyword);
-  const expression = heritageClause?.types[0]?.expression;
-  return !!expression && expression.getText().startsWith("enumOf(");
+  return suffix === ".constant.ts" && isEnumClassStatement(declaration.node.getSourceFile(), declaration.node);
 }
 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`;
+  const names = [
+    ...getConventionClassNames(suffix, modelName),
+    ...suffix === ".constant.ts" ? ["enumOf classes"] : []
+  ];
+  return names.length > 1 ? `${names.slice(0, -1).join(", ")}, or ${names.at(-1)}` : names[0];
 }
 var sysRootTypes = { apps: "app", libs: "lib" };
 function getSysRootEntry(file) {
@@ -1182,13 +1034,7 @@ function getModuleUiWarning(file) {
   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(", ")}.`
-  };
+  return fileWarning("akan.layout.module-ui-file", "layout", file, `Unexpected ${kind} module UI filename "${fileName}". Expected one of: ${[...allowedFileNames].join(", ")}.`);
 }
 function getModuleInfo(file) {
   const segments = file.split("/");
@@ -1204,10 +1050,8 @@ function getModuleInfo(file) {
   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: "scalar" };
   if (moduleName.startsWith("_"))
     return { moduleName, fileName, kind: "service" };
   return { moduleName, fileName, kind: "database" };
@@ -1216,7 +1060,7 @@ function isExportedConst(declaration) {
   return declaration.exported && ts3.isVariableStatement(declaration.node) && (declaration.node.declarationList.flags & ts3.NodeFlags.Const) !== 0;
 }
 function isExported(node) {
-  return !!ts3.getCombinedModifierFlags(node) && !!(ts3.getCombinedModifierFlags(node) & ts3.ModifierFlags.Export);
+  return !!(ts3.getCombinedModifierFlags(node) & ts3.ModifierFlags.Export);
 }
 function isFunctionLikeInitializer(node) {
   return !!node && (ts3.isArrowFunction(node) || ts3.isFunctionExpression(node));
@@ -1262,7 +1106,7 @@ 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("/");
+  return value.split(path2.sep).join("/");
 }
 function groupBy(items, getKey) {
   const grouped = new Map;
@@ -1279,24 +1123,16 @@ function compareWarnings(a, b) {
 // 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]) {
+class QualityScript extends script("quality") {
   async scan(workspace, format = "text") {
     const spinner = workspace.spinning("Scanning Akan code quality...");
-    const result = await this.qualityRunner.scan(workspace);
+    const result = await new AkanQualityScanner().scan(workspace.workspaceRoot);
     spinner.succeed(`Quality scan completed (${result.scannedFiles} files, ${result.warnings.length} warnings)`);
     Logger.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatQualityScanResult(result));
   }
   async ssr(workspace, format = "text") {
     const spinner = workspace.spinning("Measuring Akan server/client render balance...");
-    const scanned = await this.qualityRunner.scan(workspace);
+    const scanned = await new AkanQualityScanner().scan(workspace.workspaceRoot);
     const result = { ...scanned, warnings: scanned.warnings.filter((warning) => warning.scope === "ssr") };
     spinner.succeed(`SSR scan completed (${result.scannedFiles} files, ${result.warnings.length} warnings)`);
     Logger.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatSsrScanResult(result));
@@ -1305,15 +1141,7 @@ class QualityScript extends script("quality", [QualityRunner]) {
 
 // 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", "ssr"]
-  }).option("format", String, {
-    desc: "output format",
-    default: "text",
-    enum: ["text", "json"]
-  }).with(Workspace).exec(async function(action, format, workspace) {
+  quality: target({ desc: "Scan apps and libs for Akan code quality warnings" }).arg("action", String, { desc: "quality action", default: "scan", enum: ["scan", "ssr"] }).option("format", String, { desc: "output format", default: "text", enum: ["text", "json"] }).with(Workspace).exec(async function(action, format, workspace) {
     if (action === "scan")
       await this.qualityScript.scan(workspace, format);
     else if (action === "ssr")