@akanjs/cli 3.0.0-alpha.9 → 3.0.0-alpha.90

package/{quality.command-0cs2z92d.js → quality.command-gpe2vqb5.js}

@@ -1,21 +1,20 @@
 // @bun
-import {
-  AbstractDoc
-} from "./index-0wae5ebk.js";
 import {
   Workspace,
-  command,
   runner,
-  script
-} from "./index-kdh76j26.js";
+  script,
+  command
+} from "./index-cezy7yb3.js";
+import"./index-q0y2jq9j.js";
+import {
+  rootAllowedFiles,
+  rootAllowedDirs,
+  isAllowedLibFacetRootFile
+} from "./index-q8sn827n.js";
+import"./index-6wwzs1bc.js";
 import {
-  appRootAllowedFiles,
-  libFacetRootAllowedFiles
-} from "./index-z8ptfkzv.js";
-import"./index-mxvakhsm.js";
-import"./index-1577bej2.js";
-import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+  AbstractDoc
+} from "./index-meh558jy.js";
 
 // pkgs/@akanjs/devkit/qualityScanner.ts
 import { createHash } from "crypto";
@@ -23,10 +22,79 @@ import { readdir, readFile, stat } from "fs/promises";
 import path from "path";
 import { RESERVED_ROUTE_CONFIG_EXPORTS } from "akanjs/common";
 import ignore from "ignore";
-import ts2 from "typescript";
+import ts3 from "typescript";
 
-// pkgs/@akanjs/devkit/ssrScanner.ts
+// pkgs/@akanjs/devkit/formSetterScanner.ts
 import ts from "typescript";
+
+class FormSetterScanner {
+  static #fieldSetter = /^set[A-Za-z0-9_$]*On[A-Za-z0-9_$]*$/;
+  scan(sourceFiles) {
+    return sourceFiles.filter((sourceFile) => sourceFile.file.endsWith(".tsx")).flatMap((f) => this.#scanFile(f));
+  }
+  #scanFile({ file, sourceFile }) {
+    const wrapped = [];
+    const visit = (node) => {
+      if (ts.isJsxAttribute(node)) {
+        const setter = FormSetterScanner.#wrappedSetterOf(node);
+        if (setter)
+          wrapped.push({ setter, line: FormSetterScanner.#lineOf(sourceFile, node) });
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    if (!wrapped.length)
+      return [];
+    const setters = [...new Set(wrapped.map((entry) => entry.setter))].sort();
+    return [
+      {
+        rule: "akan.agent.unpublished-form-setter",
+        scope: "agent",
+        severity: "warning",
+        message: setters.length === 1 ? `${setters[0]} is reached through a wrapper, so that field publishes no agent tool and carries no data-akan-action.` : `${setters.length} field setters are reached through a wrapper, so those fields publish no agent tool and carry no data-akan-action: ${setters.join(", ")}.`,
+        file,
+        line: wrapped[0]?.line,
+        locations: wrapped.map(({ line }) => ({ file, line }))
+      }
+    ];
+  }
+  static #wrappedSetterOf(attribute) {
+    if (!ts.isIdentifier(attribute.name) || !/^on[A-Z]/.test(attribute.name.text))
+      return null;
+    const initializer = attribute.initializer;
+    if (!initializer || !ts.isJsxExpression(initializer) || !initializer.expression)
+      return null;
+    const handler = initializer.expression;
+    if (!ts.isArrowFunction(handler) && !ts.isFunctionExpression(handler))
+      return null;
+    if (!handler.parameters.length)
+      return null;
+    return FormSetterScanner.#setterCallIn(handler.body);
+  }
+  static #setterCallIn(node) {
+    let found = null;
+    const visit = (current) => {
+      if (found)
+        return;
+      if (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression)) {
+        const { expression, name } = current.expression;
+        if (ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.expression) && expression.expression.text === "st" && expression.name.text === "do" && FormSetterScanner.#fieldSetter.test(name.text)) {
+          found = name.text;
+          return;
+        }
+      }
+      ts.forEachChild(current, visit);
+    };
+    visit(node);
+    return found;
+  }
+  static #lineOf(sourceFile, node) {
+    return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+  }
+}
+
+// pkgs/@akanjs/devkit/ssrScanner.ts
+import ts2 from "typescript";
 var STATIC_COMPONENT_MIN_MASS = 4;
 var MIXED_COMPONENT_MIN_MASS = 10;
 var MIXED_COMPONENT_MAX_TOUCHES = 2;
@@ -144,31 +212,31 @@ class SsrScanner {
           });
         }
       }
-      ts.forEachChild(node, visit);
+      ts2.forEachChild(node, visit);
     };
-    ts.forEachChild(sourceFile.sourceFile, visit);
+    ts2.forEachChild(sourceFile.sourceFile, visit);
     return warnings;
   }
   #isMountEffect(sourceFile, node) {
-    if (!ts.isCallExpression(node))
+    if (!ts2.isCallExpression(node))
       return false;
     const callee = node.expression.getText(sourceFile);
     if (callee !== "useEffect" && callee !== "useLayoutEffect")
       return false;
     const deps = node.arguments[1];
-    return !!deps && ts.isArrayLiteralExpression(deps) && deps.elements.length === 0;
+    return !!deps && ts2.isArrayLiteralExpression(deps) && deps.elements.length === 0;
   }
   #getLoadCalls(sourceFile, node) {
     const calls = [];
     const visit = (child) => {
-      if (ts.isCallExpression(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 });
       }
-      ts.forEachChild(child, visit);
+      ts2.forEachChild(child, visit);
     };
-    ts.forEachChild(node, visit);
+    ts2.forEachChild(node, visit);
     return calls;
   }
   #getTemplateStateWarnings(sourceFile) {
@@ -176,7 +244,7 @@ class SsrScanner {
       return [];
     const warnings = [];
     const visit = (node) => {
-      if (ts.isCallExpression(node) && node.expression.getText(sourceFile.sourceFile) === "useState") {
+      if (ts2.isCallExpression(node) && node.expression.getText(sourceFile.sourceFile) === "useState") {
         warnings.push({
           rule: "akan.ssr.template-client-state",
           scope: "ssr",
@@ -186,9 +254,9 @@ class SsrScanner {
           message: "Template holds form state in useState. Templates are store-driven and carry no local state."
         });
       }
-      ts.forEachChild(node, visit);
+      ts2.forEachChild(node, visit);
     };
-    ts.forEachChild(sourceFile.sourceFile, visit);
+    ts2.forEachChild(sourceFile.sourceFile, visit);
     return warnings;
   }
   #measureBalance(sourceFiles) {
@@ -229,14 +297,14 @@ class SsrScanner {
     return components;
   }
   #getComponentNodes(statement) {
-    if (ts.isFunctionDeclaration(statement) && statement.body)
+    if (ts2.isFunctionDeclaration(statement) && statement.body)
       return [{ name: statement.name?.text ?? "default", node: statement.body }];
-    if (!ts.isVariableStatement(statement))
+    if (!ts2.isVariableStatement(statement))
       return [];
     return statement.declarationList.declarations.flatMap((declaration) => {
-      if (!ts.isIdentifier(declaration.name) || !declaration.initializer)
+      if (!ts2.isIdentifier(declaration.name) || !declaration.initializer)
         return [];
-      if (!ts.isArrowFunction(declaration.initializer) && !ts.isFunctionExpression(declaration.initializer))
+      if (!ts2.isArrowFunction(declaration.initializer) && !ts2.isFunctionExpression(declaration.initializer))
         return [];
       return [{ name: declaration.name.text, node: declaration.initializer }];
     });
@@ -244,7 +312,7 @@ class SsrScanner {
   #getTouches(sourceFile, node) {
     const touches = [];
     const visit = (child) => {
-      if (ts.isCallExpression(child)) {
+      if (ts2.isCallExpression(child)) {
         const callee = child.expression.getText(sourceFile);
         const bareName = callee.split(".").pop() ?? callee;
         if (callee === "createContext" || callee === "lazy")
@@ -252,60 +320,60 @@ class SsrScanner {
         else if (/^use[A-Z]/.test(bareName) && !SsrScanner.#serverSafeCalls.has(bareName))
           touches.push(bareName);
       }
-      if (ts.isJsxAttribute(child) && /^on[A-Z]/.test(child.name.getText(sourceFile)))
+      if (ts2.isJsxAttribute(child) && /^on[A-Z]/.test(child.name.getText(sourceFile)))
         touches.push(child.name.getText(sourceFile));
-      if (ts.isPropertyAccessExpression(child)) {
+      if (ts2.isPropertyAccessExpression(child)) {
         const root = getAccessRoot(child);
         if (root === "st")
           touches.push("st");
         else if (SsrScanner.#clientGlobals.has(root))
           touches.push(root);
       }
-      ts.forEachChild(child, visit);
+      ts2.forEachChild(child, visit);
     };
-    ts.forEachChild(node, visit);
+    ts2.forEachChild(node, visit);
     return touches;
   }
   #getTagNames(sourceFile, node) {
     const tags = new Set;
     const visit = (child) => {
-      if (ts.isJsxOpeningElement(child) || ts.isJsxSelfClosingElement(child))
+      if (ts2.isJsxOpeningElement(child) || ts2.isJsxSelfClosingElement(child))
         tags.add(child.tagName.getText(sourceFile).split(".")[0]);
-      ts.forEachChild(child, visit);
+      ts2.forEachChild(child, visit);
     };
-    ts.forEachChild(node, visit);
+    ts2.forEachChild(node, visit);
     return tags;
   }
   #getMass(node) {
     let mass = 0;
     const visit = (child) => {
-      if (ts.isJsxOpeningElement(child) || ts.isJsxSelfClosingElement(child))
+      if (ts2.isJsxOpeningElement(child) || ts2.isJsxSelfClosingElement(child))
         mass += 1;
-      ts.forEachChild(child, visit);
+      ts2.forEachChild(child, visit);
     };
-    ts.forEachChild(node, visit);
+    ts2.forEachChild(node, visit);
     return mass;
   }
   #hasUseClient(sourceFile) {
     const first = sourceFile.statements[0];
-    if (!first || !ts.isExpressionStatement(first) || !ts.isStringLiteral(first.expression))
+    if (!first || !ts2.isExpressionStatement(first) || !ts2.isStringLiteral(first.expression))
       return false;
     return first.expression.text === "use client";
   }
   #hasVendorImport(sourceFile) {
-    return sourceFile.statements.some((statement) => ts.isImportDeclaration(statement) && isVendorSpecifier(getSpecifier(statement)));
+    return sourceFile.statements.some((statement) => ts2.isImportDeclaration(statement) && isVendorSpecifier(getSpecifier(statement)));
   }
   #getVendorNames(sourceFile) {
     const names = new Set;
     for (const statement of sourceFile.statements) {
-      if (!ts.isImportDeclaration(statement) || !isVendorSpecifier(getSpecifier(statement)))
+      if (!ts2.isImportDeclaration(statement) || !isVendorSpecifier(getSpecifier(statement)))
         continue;
       const clause = statement.importClause;
       if (clause?.name)
         names.add(clause.name.text);
-      if (clause?.namedBindings && ts.isNamespaceImport(clause.namedBindings))
+      if (clause?.namedBindings && ts2.isNamespaceImport(clause.namedBindings))
         names.add(clause.namedBindings.name.text);
-      if (clause?.namedBindings && ts.isNamedImports(clause.namedBindings))
+      if (clause?.namedBindings && ts2.isNamedImports(clause.namedBindings))
         for (const element of clause.namedBindings.elements)
           names.add(element.name.text);
     }
@@ -313,10 +381,10 @@ class SsrScanner {
   }
   #importsClientRuntime(sourceFile) {
     for (const statement of sourceFile.statements) {
-      if (!ts.isImportDeclaration(statement))
+      if (!ts2.isImportDeclaration(statement))
         continue;
       const bindings = statement.importClause?.namedBindings;
-      if (!bindings || !ts.isNamedImports(bindings))
+      if (!bindings || !ts2.isNamedImports(bindings))
         continue;
       if (bindings.elements.some((element) => SsrScanner.#clientRuntimeImports.has(element.name.text)))
         return true;
@@ -367,7 +435,7 @@ function getShare(serverMass, clientMass) {
   return total === 0 ? 1 : serverMass / total;
 }
 function getSpecifier(statement) {
-  return ts.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : "";
+  return ts2.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : "";
 }
 function isVendorSpecifier(specifier) {
   if (specifier === "" || specifier.startsWith(".") || specifier.startsWith("/"))
@@ -380,9 +448,9 @@ function isVendorSpecifier(specifier) {
 }
 function getAccessRoot(node) {
   let current = node;
-  while (ts.isPropertyAccessExpression(current))
+  while (ts2.isPropertyAccessExpression(current))
     current = current.expression;
-  return ts.isIdentifier(current) ? current.text : "";
+  return ts2.isIdentifier(current) ? current.text : "";
 }
 
 // pkgs/@akanjs/devkit/qualityScanner.ts
@@ -406,7 +474,8 @@ var SUGGESTED_RULES = [
   "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.",
+  "Hand a form control its store setter by reference so the field publishes an agent tool; put normalization in the control's transform prop and a multi-write in a _postSet<Field> hook on the store.",
+  "Move shared app and lib utilities to common/ instead of creating apps/*/base or libs/*/base.",
   "Avoid large mixed-purpose class files; class export files should import helpers from neighboring utility files instead of declaring them inline."
 ];
 var CONVENTION_SUFFIXES = [
@@ -424,15 +493,20 @@ var RULE_FIXES = {
   "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.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.",
   "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.agent.unpublished-form-setter": "Pass the setter by reference where the wrapper only forwards (onChange={st.do.setTitleOnTask}); move normalization into the control's own transform prop; move a multi-write into a _postSet<Field> hook on the store, keeping the generated setter on the control.",
   "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.app-root-folder": "Move the folder's contents into a conventional app folder (common, env, lib, page, private, public, script, srvkit, ui, or webkit) and delete it.",
+  "akan.layout.lib-root-file": "Move the file into a conventional lib folder (common, env, lib, page, private, public, srvkit, ui, or webkit).",
+  "akan.layout.lib-root-folder": "Move the folder's contents into a conventional lib folder (common, env, lib, page, private, public, srvkit, ui, or webkit) and delete it.",
+  "akan.layout.lib-facet-file": "Move the file into a domain module folder under lib/; keep the lib facet 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.",
   "akan.ssr.unnecessary-use-client": 'Delete the "use client" directive so the file renders on the server. If it exists only to wrap one client child, drop the wrapper and use the child directly.',
   "akan.ssr.client-static-component": "Move the component to a server file \u2014 a <Model>.Unit.tsx / <Model>.View.tsx for a module, or a ui/ file with no directive \u2014 and reference it from the client file.",
@@ -460,6 +534,7 @@ class AkanQualityScanner {
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
       ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
+      ...new FormSetterScanner().scan(sourceFiles),
       ...ssr.warnings
     ];
     return {
@@ -512,7 +587,7 @@ class AkanQualityScanner {
       file,
       absolutePath,
       content,
-      sourceFile: ts2.createSourceFile(file, content, ts2.ScriptTarget.Latest, true, getScriptKind(file))
+      sourceFile: ts3.createSourceFile(file, content, ts3.ScriptTarget.Latest, true, getScriptKind(file))
     };
   }
   async#readTextFile(workspaceRoot, file) {
@@ -570,6 +645,7 @@ class AkanQualityScanner {
         message: `File has ${lineCount} lines. Keep single files under ${MAX_FILE_LINES} lines.`
       });
     }
+    warnings.push(...getBangCommentWarnings(sourceFile));
     warnings.push(...getPlaceholderExportWarnings(sourceFile));
     warnings.push(...getDictionaryTextWarnings(sourceFile));
     warnings.push(...getGlobalMutationWarnings(sourceFile));
@@ -671,25 +747,30 @@ class AkanQualityScanner {
     ];
   }
   #scanLayoutQuality(sourceFile) {
-    const segments = sourceFile.file.split("/");
     const warnings = [];
-    if (segments[0] === "apps" && segments.length === 3 && !appRootAllowedFiles.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 rootEntry = getSysRootEntry(sourceFile.file);
+    if (rootEntry) {
+      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.`
+        });
+      }
     }
-    const libRootFile = getLibRootFile(sourceFile.file);
-    if (libRootFile && !libFacetRootAllowedFiles.has(libRootFile)) {
+    const libFacetFile = getLibFacetRootFile(sourceFile.file);
+    if (libFacetFile && !isAllowedLibFacetRootFile(libFacetFile)) {
       warnings.push({
-        rule: "akan.layout.lib-root-file",
+        rule: "akan.layout.lib-facet-file",
         scope: "layout",
         severity: "warning",
         file: sourceFile.file,
-        message: `Unexpected lib root file "${libRootFile}". Keep direct lib root files limited to generated support facets.`
+        message: `Unexpected lib facet root file "${libFacetFile}". Keep direct lib/ root files limited to generated support facets.`
       });
     }
     const moduleUiWarning = getModuleUiWarning(sourceFile.file);
@@ -759,7 +840,7 @@ function getExportedFunctionLikes(sourceFile) {
   const declarations = [];
   const nameExempt = isPageRouteFile(sourceFile.file) || isUiComponentFile(sourceFile.file);
   for (const statement of sourceFile.sourceFile.statements) {
-    if (ts2.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
+    if (ts3.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
       declarations.push({
         name: statement.name.text,
         kind: "function",
@@ -769,7 +850,7 @@ function getExportedFunctionLikes(sourceFile) {
         duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile.file, false)
       });
     }
-    if (ts2.isClassDeclaration(statement) && statement.name && isExported(statement)) {
+    if (ts3.isClassDeclaration(statement) && statement.name && isExported(statement)) {
       declarations.push({
         name: statement.name.text,
         kind: "class",
@@ -779,9 +860,9 @@ function getExportedFunctionLikes(sourceFile) {
         duplicateNameExempt: nameExempt || isConventionDuplicateNameExempt(sourceFile.file, isEnumClassStatement(sourceFile.sourceFile, statement))
       });
     }
-    if (ts2.isVariableStatement(statement) && isExported(statement)) {
+    if (ts3.isVariableStatement(statement) && isExported(statement)) {
       for (const declaration of statement.declarationList.declarations) {
-        if (!ts2.isIdentifier(declaration.name) || !isFunctionLikeInitializer(declaration.initializer))
+        if (!ts3.isIdentifier(declaration.name) || !isFunctionLikeInitializer(declaration.initializer))
           continue;
         declarations.push({
           name: declaration.name.text,
@@ -820,14 +901,14 @@ function isInLibModule(file) {
   return (segments[0] === "apps" || segments[0] === "libs") && segments.includes("lib");
 }
 function isEnumClassStatement(sourceFile, statement) {
-  if (!ts2.isClassDeclaration(statement))
+  if (!ts3.isClassDeclaration(statement))
     return false;
-  const heritageClause = statement.heritageClauses?.find((clause) => clause.token === ts2.SyntaxKind.ExtendsKeyword);
+  const heritageClause = statement.heritageClauses?.find((clause) => clause.token === ts3.SyntaxKind.ExtendsKeyword);
   const expression = heritageClause?.types[0]?.expression;
   return !!expression && expression.getText(sourceFile).startsWith("enumOf(");
 }
 function getExportedClassNames(sourceFile) {
-  return sourceFile.statements.filter((statement) => ts2.isClassDeclaration(statement) && !!statement.name).filter((statement) => isExported(statement)).map((statement) => statement.name.text);
+  return sourceFile.statements.filter((statement) => ts3.isClassDeclaration(statement)).filter((statement) => isExported(statement)).map((statement) => statement.name?.text).filter((name) => !!name);
 }
 function isComponentDeclarationFile(file) {
   if (!file.endsWith(".tsx"))
@@ -843,7 +924,7 @@ function isComponentDeclarationFile(file) {
 function getComponentFileDeclarations(sourceFile) {
   const reExportedNames = new Set;
   for (const statement of sourceFile.statements) {
-    if (ts2.isExportDeclaration(statement) && statement.exportClause && ts2.isNamedExports(statement.exportClause)) {
+    if (ts3.isExportDeclaration(statement) && statement.exportClause && ts3.isNamedExports(statement.exportClause)) {
       for (const element of statement.exportClause.elements)
         reExportedNames.add((element.propertyName ?? element.name).text);
     }
@@ -853,19 +934,19 @@ function getComponentFileDeclarations(sourceFile) {
     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 (ts2.isInterfaceDeclaration(statement))
+    if (ts3.isInterfaceDeclaration(statement))
       add(statement.name.text, "interface", getLine(sourceFile, statement));
-    else if (ts2.isTypeAliasDeclaration(statement))
+    else if (ts3.isTypeAliasDeclaration(statement))
       add(statement.name.text, "type", getLine(sourceFile, statement));
-    else if (ts2.isEnumDeclaration(statement))
+    else if (ts3.isEnumDeclaration(statement))
       add(statement.name.text, "enum", getLine(sourceFile, statement));
-    else if (ts2.isFunctionDeclaration(statement) && statement.name)
+    else if (ts3.isFunctionDeclaration(statement) && statement.name)
       add(statement.name.text, "function", getLine(sourceFile, statement));
-    else if (ts2.isClassDeclaration(statement) && statement.name)
+    else if (ts3.isClassDeclaration(statement) && statement.name)
       add(statement.name.text, "class", getLine(sourceFile, statement));
-    else if (ts2.isVariableStatement(statement)) {
+    else if (ts3.isVariableStatement(statement)) {
       for (const declaration of statement.declarationList.declarations) {
-        if (!ts2.isIdentifier(declaration.name))
+        if (!ts3.isIdentifier(declaration.name))
           continue;
         const kind = isFunctionLikeInitializer(declaration.initializer) ? "function" : "variable";
         add(declaration.name.text, kind, getLine(sourceFile, declaration));
@@ -877,15 +958,15 @@ function getComponentFileDeclarations(sourceFile) {
 function getCompoundComponentNames(sourceFile) {
   const names = new Set;
   for (const statement of sourceFile.statements) {
-    if (!ts2.isExpressionStatement(statement))
+    if (!ts3.isExpressionStatement(statement))
       continue;
     const { expression } = statement;
-    if (!ts2.isBinaryExpression(expression) || expression.operatorToken.kind !== ts2.SyntaxKind.EqualsToken)
+    if (!ts3.isBinaryExpression(expression) || expression.operatorToken.kind !== ts3.SyntaxKind.EqualsToken)
       continue;
-    if (!ts2.isPropertyAccessExpression(expression.left) || !isPascalCaseName(expression.left.name.text))
+    if (!ts3.isPropertyAccessExpression(expression.left) || !isPascalCaseName(expression.left.name.text))
       continue;
     names.add(expression.left.name.text);
-    if (ts2.isIdentifier(expression.right) && isPascalCaseName(expression.right.text))
+    if (ts3.isIdentifier(expression.right) && isPascalCaseName(expression.right.text))
       names.add(expression.right.text);
   }
   return names;
@@ -905,9 +986,37 @@ function isPascalCaseName(name) {
   return /^[A-Z]/.test(name) && !/^[A-Z0-9_]+$/.test(name);
 }
 function isDefaultExportStatement(statement) {
-  if (ts2.isExportAssignment(statement))
+  if (ts3.isExportAssignment(statement))
     return !statement.isExportEquals;
-  return !!(ts2.getCombinedModifierFlags(statement) & ts2.ModifierFlags.Default);
+  if (!ts3.canHaveModifiers(statement))
+    return false;
+  return !!ts3.getModifiers(statement)?.some((modifier) => modifier.kind === ts3.SyntaxKind.DefaultKeyword);
+}
+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."
+  }));
+}
+function isClientReachableFile(file) {
+  if (/\.(test|spec)\.tsx?$/.test(file))
+    return false;
+  if (/\.(constant|store)\.ts$/.test(file))
+    return true;
+  if (/\.(Template|Unit|Util|View|Zone)\.tsx$/.test(file))
+    return true;
+  const segments = file.split("/");
+  if (segments.includes("ui") || segments.includes("webkit"))
+    return /\.tsx?$/.test(file);
+  if (segments.includes("common"))
+    return file.endsWith(".ts");
+  return segments.includes("page") && file.endsWith(".tsx");
 }
 function getPlaceholderExportWarnings(sourceFile) {
   if (!sourceFile.file.endsWith("/index.ts") && !sourceFile.file.endsWith("/index.tsx"))
@@ -937,7 +1046,7 @@ function getDictionaryTextWarnings(sourceFile) {
 function getGlobalMutationWarnings(sourceFile) {
   const warnings = [];
   for (const statement of sourceFile.sourceFile.statements) {
-    if (ts2.isModuleDeclaration(statement) && statement.name.getText(sourceFile.sourceFile) === "global") {
+    if (ts3.isModuleDeclaration(statement) && statement.name.getText(sourceFile.sourceFile) === "global") {
       warnings.push({
         rule: "akan.file.global-declaration",
         scope: "file",
@@ -947,7 +1056,7 @@ function getGlobalMutationWarnings(sourceFile) {
         message: "Global declarations require an explicit low-level integration allowlist."
       });
     }
-    if (ts2.isInterfaceDeclaration(statement) && statement.name.text === "Window") {
+    if (ts3.isInterfaceDeclaration(statement) && statement.name.text === "Window") {
       warnings.push({
         rule: "akan.file.window-augmentation",
         scope: "file",
@@ -957,7 +1066,7 @@ function getGlobalMutationWarnings(sourceFile) {
         message: "Window augmentation should be isolated to approved browser integration files."
       });
     }
-    if (ts2.isExpressionStatement(statement) && statement.expression.getText(sourceFile.sourceFile).includes(".prototype.")) {
+    if (ts3.isExpressionStatement(statement) && statement.expression.getText(sourceFile.sourceFile).includes(".prototype.")) {
       warnings.push({
         rule: "akan.file.prototype-mutation",
         scope: "file",
@@ -975,23 +1084,23 @@ function getTopLevelDeclarations(sourceFile) {
 }
 function getTopLevelDeclaration(sourceFile, statement) {
   const line = getLine(sourceFile, statement);
-  if (ts2.isClassDeclaration(statement) && statement.name) {
+  if (ts3.isClassDeclaration(statement) && statement.name) {
     return [{ name: statement.name.text, kind: "class", line, exported: isExported(statement), node: statement }];
   }
-  if (ts2.isFunctionDeclaration(statement) && statement.name) {
+  if (ts3.isFunctionDeclaration(statement) && statement.name) {
     return [{ name: statement.name.text, kind: "function", line, exported: isExported(statement), node: statement }];
   }
-  if (ts2.isInterfaceDeclaration(statement)) {
+  if (ts3.isInterfaceDeclaration(statement)) {
     return [{ name: statement.name.text, kind: "interface", line, exported: isExported(statement), node: statement }];
   }
-  if (ts2.isTypeAliasDeclaration(statement)) {
+  if (ts3.isTypeAliasDeclaration(statement)) {
     return [{ name: statement.name.text, kind: "type", line, exported: isExported(statement), node: statement }];
   }
-  if (ts2.isEnumDeclaration(statement)) {
+  if (ts3.isEnumDeclaration(statement)) {
     return [{ name: statement.name.text, kind: "enum", line, exported: isExported(statement), node: statement }];
   }
-  if (ts2.isVariableStatement(statement)) {
-    return statement.declarationList.declarations.filter((declaration) => ts2.isIdentifier(declaration.name)).map((declaration) => ({
+  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),
@@ -999,7 +1108,7 @@ function getTopLevelDeclaration(sourceFile, statement) {
       node: statement
     }));
   }
-  if (ts2.isExportDeclaration(statement)) {
+  if (ts3.isExportDeclaration(statement)) {
     return [{ name: "export declaration", kind: "export", line, exported: true, node: statement }];
   }
   return [];
@@ -1024,9 +1133,9 @@ function isAllowedConstantDeclaration(modelName, declaration) {
     return false;
   if ([`${modelName}Input`, `${modelName}Object`, modelName, `Light${modelName}`, `${modelName}Insight`].includes(declaration.name))
     return true;
-  if (!ts2.isClassDeclaration(declaration.node))
+  if (!ts3.isClassDeclaration(declaration.node))
     return false;
-  const heritageClause = declaration.node.heritageClauses?.find((clause) => clause.token === ts2.SyntaxKind.ExtendsKeyword);
+  const heritageClause = declaration.node.heritageClauses?.find((clause) => clause.token === ts3.SyntaxKind.ExtendsKeyword);
   const expression = heritageClause?.types[0]?.expression;
   return !!expression && expression.getText().startsWith("enumOf(");
 }
@@ -1043,7 +1152,19 @@ function getConventionDescription(suffix, modelName) {
     return `${modelName}Internal, ${modelName}Slice, or ${modelName}Endpoint`;
   return `${modelName}Store`;
 }
-function getLibRootFile(file) {
+var sysRootTypes = { apps: "app", libs: "lib" };
+function getSysRootEntry(file) {
+  const segments = file.split("/");
+  const root = segments[0];
+  const name = segments[2];
+  if (!root || !name || segments.length < 3)
+    return null;
+  const type = sysRootTypes[root];
+  if (!type)
+    return null;
+  return { type, name, isDir: segments.length > 3 };
+}
+function getLibFacetRootFile(file) {
   const segments = file.split("/");
   if ((segments[0] === "libs" || segments[0] === "apps") && segments.length === 4 && segments[2] === "lib")
     return segments[3];
@@ -1092,13 +1213,13 @@ function getModuleInfo(file) {
   return { moduleName, fileName, kind: "database" };
 }
 function isExportedConst(declaration) {
-  return declaration.exported && ts2.isVariableStatement(declaration.node) && (declaration.node.declarationList.flags & ts2.NodeFlags.Const) !== 0;
+  return declaration.exported && ts3.isVariableStatement(declaration.node) && (declaration.node.declarationList.flags & ts3.NodeFlags.Const) !== 0;
 }
 function isExported(node) {
-  return !!ts2.getCombinedModifierFlags(node) && !!(ts2.getCombinedModifierFlags(node) & ts2.ModifierFlags.Export);
+  return !!ts3.getCombinedModifierFlags(node) && !!(ts3.getCombinedModifierFlags(node) & ts3.ModifierFlags.Export);
 }
 function isFunctionLikeInitializer(node) {
-  return !!node && (ts2.isArrowFunction(node) || ts2.isFunctionExpression(node));
+  return !!node && (ts3.isArrowFunction(node) || ts3.isFunctionExpression(node));
 }
 function getBodyFingerprint(sourceFile, node) {
   if (!node)
@@ -1120,7 +1241,7 @@ async function isDirectory(absolutePath) {
   }
 }
 function getScriptKind(file) {
-  return file.endsWith(".tsx") ? ts2.ScriptKind.TSX : ts2.ScriptKind.TS;
+  return file.endsWith(".tsx") ? ts3.ScriptKind.TSX : ts3.ScriptKind.TS;
 }
 function getLine(sourceFile, node) {
   return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;