@akanjs/devkit 2.3.9-rc.9 → 2.3.10-rc.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @akanjs/devkit
 
+## 2.3.9
+
+### Patch Changes
+
+- f518afd: Improve dictionary type inference and lint coverage for generated workspaces.
+- 6bc2209: auto-select app when the workspace has only one app
+- Updated dependencies [f518afd]
+- Updated dependencies [f518afd]
+  - akanjs@2.3.9
+
 ## 2.3.6
 
 ### Patch Changes

package/akanConfig/akanConfig.test.ts

@@ -281,11 +281,17 @@ describe("AkanAppConfig", () => {
           targets: {
             admin: {
               basePath: "admin",
+              indexPath: "/admin/home/",
               appName: "Portal Admin",
               appId: "com.portal.admin",
               buildNum: 8,
               permissions: ["camera"],
-              links: { schemes: ["portal-admin"] },
+              deepLinks: {
+                schemes: ["portal-admin", "portal-admin"],
+                domains: ["https://Portal.Admin/"],
+                ios: { teamId: " TEAMID " },
+                android: { sha256CertFingerprints: ["AA:BB", "AA:BB"] },
+              },
             },
           },
         },
@@ -296,12 +302,18 @@ describe("AkanAppConfig", () => {
     expect(config.mobile.targets.admin).toMatchObject({
       name: "admin",
       basePath: "admin",
+      indexPath: "/admin/home",
       appName: "Portal Admin",
       appId: "com.portal.admin",
       version: "1.0.0",
       buildNum: 8,
       permissions: ["camera"],
-      links: { schemes: ["portal-admin"] },
+      deepLinks: {
+        schemes: ["portal-admin"],
+        domains: ["portal.admin"],
+        ios: { teamId: "TEAMID" },
+        android: { sha256CertFingerprints: ["AA:BB"] },
+      },
     });
 
     expect(

package/akanConfig/akanConfig.ts

@@ -76,6 +76,47 @@ const DEFAULT_AKAN_IMAGE_CONFIG: AkanImageConfig = {
   maxRemoteBytes: 25 * 1024 * 1024,
 };
 
+const normalizeIndexPath = (indexPath: string | undefined): string | undefined => {
+  const normalized = indexPath?.trim();
+  if (!normalized) return undefined;
+  const path = `/${normalized.replace(/^\/+|\/+$/g, "")}`;
+  return path === "/" ? "/" : path;
+};
+
+const normalizeStringList = (values: string[] | undefined) => {
+  const normalized = values?.map((value) => value.trim()).filter(Boolean) ?? [];
+  return normalized.length > 0 ? [...new Set(normalized)] : undefined;
+};
+
+const normalizeDeepLinkDomain = (domain: string) => {
+  const normalized = domain.trim();
+  if (!normalized) return "";
+  try {
+    const url = new URL(normalized.includes("://") ? normalized : `https://${normalized}`);
+    return url.host.toLowerCase();
+  } catch {
+    return normalized
+      .replace(/^https?:\/\//, "")
+      .replace(/\/+$/g, "")
+      .toLowerCase();
+  }
+};
+
+const normalizeDeepLinks = (deepLinks: DeepPartial<AkanMobileTargetConfig["deepLinks"]> | undefined) => {
+  if (!deepLinks) return undefined;
+  const schemes = normalizeStringList(deepLinks.schemes as string[] | undefined);
+  const domains = normalizeStringList((deepLinks.domains as string[] | undefined)?.map(normalizeDeepLinkDomain));
+  const teamId = (deepLinks.ios?.teamId as string | undefined)?.trim();
+  const sha256CertFingerprints = normalizeStringList(deepLinks.android?.sha256CertFingerprints as string[] | undefined);
+  if (!schemes && !domains && !teamId && !sha256CertFingerprints) return undefined;
+  return {
+    ...(schemes ? { schemes } : {}),
+    ...(domains ? { domains } : {}),
+    ...(teamId ? { ios: { teamId } } : {}),
+    ...(sha256CertFingerprints ? { android: { sha256CertFingerprints } } : {}),
+  } satisfies AkanMobileTargetConfig["deepLinks"];
+};
+
 export class AkanAppConfig implements AppConfigResult {
   app: App;
   rootPackageJson: PackageJson;
@@ -88,6 +129,7 @@ export class AkanAppConfig implements AppConfigResult {
   i18n: AkanI18nConfig;
   publicEnv: string[];
   mobile: AkanMobileConfig;
+  secrets: string[];
   baseDevEnv: BaseDevEnv;
   libs: string[];
   domains = new Set<string>();
@@ -120,11 +162,18 @@ export class AkanAppConfig implements AppConfigResult {
     process.env.AKAN_PUBLIC_DEFAULT_LOCALE = this.i18n.defaultLocale;
     process.env.AKAN_PUBLIC_LOCALES = this.i18n.locales.join(",");
     this.publicEnv = (config?.publicEnv as string[] | undefined) ?? ([] as string[]);
+    this.secrets = (config?.secrets as string[] | undefined) ?? ([] as string[]);
     this.mobile = this.#resolveMobileConfig(config.mobile);
     this.docker = this.#makeDockerContent(config?.docker ?? {});
   }
   #resolveMobileConfig(mobile: DeepPartial<AkanMobileConfig> | undefined): AkanMobileConfig {
-    const { targets: rawTargets, ...rawMobile } = mobile ?? {};
+    const {
+      targets: rawTargets,
+      indexPath: _indexPath,
+      ...rawMobile
+    } = (mobile ?? {}) as DeepPartial<AkanMobileConfig> & {
+      indexPath?: unknown;
+    };
     const appName = rawMobile.appName ?? this.app.name;
     const appId = rawMobile.appId ?? `com.${this.app.name}.app`;
     const version = rawMobile.version ?? "0.0.1";
@@ -140,6 +189,8 @@ export class AkanAppConfig implements AppConfigResult {
         const target = rawTarget as DeepPartial<AkanMobileTargetConfig>;
         const fallbackBasePath = !rawTargets && this.basePaths.has(name) ? name : undefined;
         const basePath = (target.basePath ?? fallbackBasePath)?.replace(/^\/+|\/+$/g, "") || undefined;
+        const indexPath = normalizeIndexPath(target.indexPath as string | undefined);
+        const deepLinks = normalizeDeepLinks(target.deepLinks);
         if (basePath && !this.basePaths.has(basePath)) {
           throw new Error(
             `Mobile target '${name}' uses unknown basePath '${basePath}' in apps/${this.app.name}/akan.config.ts`,
@@ -150,6 +201,8 @@ export class AkanAppConfig implements AppConfigResult {
           ...target,
           name,
           basePath,
+          indexPath,
+          deepLinks,
           appName: target.appName ?? appName,
           appId: target.appId ?? appId,
           version: target.version ?? version,

package/applicationReleasePackager.ts

@@ -1,4 +1,5 @@
 import { cp, mkdir, rm } from "node:fs/promises";
+import path from "node:path";
 import type { App } from "./commandDecorators";
 import { FileSys } from "./fileSys";
 import { uploadRelease } from "./uploadRelease";
@@ -61,13 +62,14 @@ export class ApplicationReleasePackager {
     await cp(this.#app.dist.cwdPath, buildRoot, { recursive: true });
     await rm(`${buildRoot}/frontend/.next`, { recursive: true, force: true });
 
-    await this.#app.workspace.spawn("tar", [
-      "-zcf",
-      `${this.#app.workspace.workspaceRoot}/releases/builds/${this.#app.name}-release.tar.gz`,
-      "-C",
-      buildRoot,
-      "./",
-    ]);
+    const releaseRoot = this.#app.workspace.workspaceRoot;
+    // Pass a path relative to cwd so tar never sees a Windows drive letter (e.g. "C:\...")
+    // which GNU tar would interpret as a remote "host:file" spec.
+    const releaseArchivePath = path
+      .relative(releaseRoot, `${releaseRoot}/releases/builds/${this.#app.name}-release.tar.gz`)
+      .split(path.sep)
+      .join("/");
+    await this.#app.workspace.spawn("tar", ["-zcf", releaseArchivePath, "-C", buildRoot, "./"], { cwd: releaseRoot });
     await this.#writeCsrZipIfPresent();
     return { platformVersion };
   }
@@ -109,13 +111,14 @@ export class ApplicationReleasePackager {
     );
     await this.#writeSourceTsconfig(sourceRoot, libDeps);
     await Bun.write(`${sourceRoot}/README.md`, readme);
-    await this.#app.workspace.spawn("tar", [
-      "-zcf",
-      `${this.#app.workspace.cwdPath}/releases/sources/${this.#app.name}-source.tar.gz`,
-      "-C",
-      sourceRoot,
-      "./",
-    ]);
+    const sourceCwd = this.#app.workspace.cwdPath;
+    // Pass a path relative to cwd so tar never sees a Windows drive letter (e.g. "C:\...")
+    // which GNU tar would interpret as a remote "host:file" spec.
+    const sourceArchivePath = path
+      .relative(sourceCwd, `${sourceCwd}/releases/sources/${this.#app.name}-source.tar.gz`)
+      .split(path.sep)
+      .join("/");
+    await this.#app.workspace.spawn("tar", ["-zcf", sourceArchivePath, "-C", sourceRoot, "./"], { cwd: sourceCwd });
   }
 
   async #resetSourceRoot(sourceRoot: string): Promise<void> {

package/capacitorApp.test.ts

@@ -34,9 +34,10 @@ const baseTarget: AkanMobileTargetConfig = {
   version: "1.2.3",
   buildNum: 7,
   basePath: "admin",
+  indexPath: "/dashboard",
   assets: { icon: "mobile/icon.png" },
   permissions: ["camera"],
-  links: { schemes: ["minimal"] },
+  deepLinks: { schemes: ["minimal"], domains: ["minimal.app"] },
   files: { android: { "app/google-services.json": "private/google-services.json" } },
 };
 
@@ -74,11 +75,12 @@ describe("materializeCapacitorConfig", () => {
     });
     expect(config).not.toHaveProperty("name");
     expect(config).not.toHaveProperty("basePath");
+    expect(config).not.toHaveProperty("indexPath");
     expect(config).not.toHaveProperty("version");
     expect(config).not.toHaveProperty("buildNum");
     expect(config).not.toHaveProperty("assets");
     expect(config).not.toHaveProperty("permissions");
-    expect(config).not.toHaveProperty("links");
+    expect(config).not.toHaveProperty("deepLinks");
     expect(config).not.toHaveProperty("files");
     expect(config).not.toHaveProperty("server");
   });

package/capacitorApp.ts

@@ -1,4 +1,4 @@
-import { cp, mkdir, rm } from "node:fs/promises";
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import type { CapacitorConfig } from "@capacitor/cli";
@@ -463,11 +463,12 @@ export function materializeCapacitorConfig(
   const {
     name,
     basePath: _basePath,
+    indexPath: _indexPath,
     version: _version,
     buildNum: _buildNum,
     assets: _assets,
     permissions: _permissions,
-    links: _links,
+    deepLinks: _deepLinks,
     files: _files,
     appId,
     appName,
@@ -587,7 +588,7 @@ export class CapacitorApp {
     await this.#prepareExternalFiles("ios");
     await this.#applyIosMetadata();
     await this.#applyPermissions();
-    await this.#applyLinks();
+    await this.#applyDeepLinks("ios", { operation, env });
     await this.project.commit();
     await this.#generateAssets({ operation, env });
     this.app.verbose(`syncing iOS`);
@@ -749,12 +750,13 @@ export class CapacitorApp {
     await this.#prepareExternalFiles("android");
     await this.#applyAndroidMetadata();
     await this.#applyPermissions();
-    await this.#applyLinks();
+    await this.#applyDeepLinks("android", { operation, env });
     await this.project.commit();
     await this.#generateAssets({ operation, env });
     await this.#ensureAndroidAssetsDir();
     await this.#ensureAndroidDebugKeystore();
     await this.#spawnMobile("npx", ["cap", "sync", "android"], { operation, env });
+    await this.#setDeepLinksInAndroid(this.target.deepLinks?.schemes ?? [], this.target.deepLinks?.domains ?? []);
   }
 
   async #updateAndroidBuildTypes() {
@@ -898,7 +900,11 @@ export class CapacitorApp {
   }
   #injectMobileTargetMeta(html: string) {
     const basePath = this.target.basePath?.replace(/^\/+|\/+$/g, "") ?? "";
-    const script = `<script>window.__AKAN_MOBILE_TARGET__=${JSON.stringify({ name: this.target.name, basePath })};</script>`;
+    const script = `<script>window.__AKAN_MOBILE_TARGET__=${JSON.stringify({
+      name: this.target.name,
+      basePath,
+      indexPath: this.target.indexPath,
+    })};</script>`;
     if (html.includes("window.__AKAN_MOBILE_TARGET__")) return html;
     return html.replace(/<\/head\s*>/i, `${script}\n</head>`);
   }
@@ -977,14 +983,23 @@ export class CapacitorApp {
       else if (permission === "push") await this.addPush();
     }
   }
-  async #applyLinks() {
-    const links = this.target.links;
-    if (!links) return;
-    const schemes = links.schemes ?? [];
-    if (schemes.length > 0) {
-      await this.#setPermissionInIos({
-        appTransportSecurity: "",
-      });
+  async #applyDeepLinks(platform: "ios" | "android", { operation, env }: Pick<RunConfig, "operation" | "env">) {
+    const deepLinks = this.target.deepLinks;
+    if (!deepLinks) return;
+    const schemes = deepLinks.schemes ?? [];
+    const domains = deepLinks.domains ?? [];
+    if (domains.length > 0) this.#assertDeepLinkVerificationConfig(platform, { operation, env });
+    if (platform === "ios") {
+      if (schemes.length > 0) {
+        await this.#setPermissionInIos({
+          appTransportSecurity: "",
+        });
+        await this.#setUrlSchemesInIos(schemes);
+      }
+      if (domains.length > 0) await this.#setAssociatedDomainsInIos(domains);
+      return;
+    }
+    if (platform === "android") {
       for (const scheme of schemes) {
         this.project.android
           .getAndroidManifest()
@@ -993,18 +1008,30 @@ export class CapacitorApp {
             `<intent-filter><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /><category android:name="android.intent.category.BROWSABLE" /><data android:scheme="${scheme}" /></intent-filter>`,
           );
       }
+      for (const domain of domains) {
+        const pathPrefix = resolveMobilePath(this.target, "/");
+        this.project.android
+          .getAndroidManifest()
+          .injectFragment(
+            "activity",
+            `<intent-filter android:autoVerify="true"><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /><category android:name="android.intent.category.BROWSABLE" /><data android:scheme="https" android:host="${domain}" android:pathPrefix="${pathPrefix}" /></intent-filter>`,
+          );
+      }
+      await this.#setDeepLinksInAndroid(schemes, domains);
     }
-    for (const domain of links.associatedDomains ?? []) {
-      this.app.logger.info(`Configure iOS associated domain manually if needed: ${domain}`);
+  }
+  #assertDeepLinkVerificationConfig(platform: "ios" | "android", { operation, env }: Pick<RunConfig, "operation" | "env">) {
+    const deepLinks = this.target.deepLinks;
+    if (!deepLinks?.domains?.length) return;
+    if (platform === "ios" && !deepLinks.ios?.teamId) {
+      throw new Error(
+        `Mobile target '${this.target.name}' uses deepLinks.domains but is missing deepLinks.ios.teamId in apps/${this.app.name}/akan.config.ts`,
+      );
     }
-    for (const host of links.androidHosts ?? []) {
-      const pathPrefix = resolveMobilePath(this.target, "/");
-      this.project.android
-        .getAndroidManifest()
-        .injectFragment(
-          "activity",
-          `<intent-filter android:autoVerify="true"><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /><category android:name="android.intent.category.BROWSABLE" /><data android:scheme="https" android:host="${host}" android:pathPrefix="${pathPrefix}" /></intent-filter>`,
-        );
+    if (platform === "android" && !deepLinks.android?.sha256CertFingerprints?.length) {
+      const message = `Mobile target '${this.target.name}' uses deepLinks.domains but is missing deepLinks.android.sha256CertFingerprints in apps/${this.app.name}/akan.config.ts`;
+      if (operation === "release" || env === "main") throw new Error(message);
+      this.app.logger.warn(message);
     }
   }
   async #commandEnv(operation: "local" | "release", env: "local" | "debug" | "develop" | "main") {
@@ -1024,6 +1051,7 @@ export class CapacitorApp {
     const port = commandEnv.AKAN_PUBLIC_CLIENT_PORT ?? commandEnv.PORT ?? "8282";
     const params = new URLSearchParams({ csr: "true", akanMobileTarget: this.target.name });
     if (basePath) params.set("akanMobileBasePath", basePath);
+    if (this.target.indexPath) params.set("akanMobileIndexPath", this.target.indexPath);
     return `http://${ip}:${port}/${pathname}?${params}`;
   }
   async #clearRootCapacitorConfigs() {
@@ -1090,6 +1118,96 @@ export class CapacitorApp {
       this.project.ios.updateInfoPlist(this.iosTargetName, "Release", updateNs),
     ]);
   }
+  async #setUrlSchemesInIos(schemes: string[]) {
+    const urlTypes = schemes.map((scheme) => ({
+      CFBundleURLName: this.target.appId,
+      CFBundleURLSchemes: [scheme],
+    }));
+    await Promise.all([
+      this.project.ios.updateInfoPlist(this.iosTargetName, "Debug", { CFBundleURLTypes: urlTypes }),
+      this.project.ios.updateInfoPlist(this.iosTargetName, "Release", { CFBundleURLTypes: urlTypes }),
+    ]);
+  }
+  async #setAssociatedDomainsInIos(domains: string[]) {
+    const entitlementsRelPath = "App/App.entitlements";
+    const entitlementsPath = path.join(this.app.cwdPath, this.iosProjectPath, entitlementsRelPath);
+    const values = domains.map((domain) => `applinks:${domain}`);
+    const body = [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+      '<plist version="1.0">',
+      "<dict>",
+      "  <key>com.apple.developer.associated-domains</key>",
+      "  <array>",
+      ...values.map((value) => `    <string>${value}</string>`),
+      "  </array>",
+      "</dict>",
+      "</plist>",
+      "",
+    ].join("\n");
+    await writeFile(entitlementsPath, body);
+    await this.#setCodeSignEntitlementsInIos(entitlementsRelPath);
+  }
+  async #setCodeSignEntitlementsInIos(entitlementsRelPath: string) {
+    const pbxprojPath = path.join(this.app.cwdPath, this.iosProjectPath, "App.xcodeproj/project.pbxproj");
+    const lines = (await readFile(pbxprojPath, "utf8")).split("\n");
+    let changed = false;
+    for (let index = 0; index < lines.length; index++) {
+      const line = lines[index] ?? "";
+      if (!line.includes(`PRODUCT_BUNDLE_IDENTIFIER = ${this.target.appId};`)) continue;
+      let start = index;
+      while (start >= 0 && !lines[start]?.includes("buildSettings = {")) start--;
+      let end = index;
+      while (end < lines.length && !/^\s*\};\s*$/.test(lines[end] ?? "")) end++;
+      const settings = lines.slice(start, end + 1);
+      if (settings.some((setting) => setting.includes("CODE_SIGN_ENTITLEMENTS"))) continue;
+      const indent = line.match(/^\s*/)?.[0] ?? "";
+      lines.splice(index, 0, `${indent}CODE_SIGN_ENTITLEMENTS = ${entitlementsRelPath};`);
+      index++;
+      changed = true;
+    }
+    if (changed) await writeFile(pbxprojPath, lines.join("\n"));
+  }
+  async #setUrlSchemesInAndroid(schemes: string[]) {
+    const manifestPath = path.join(this.app.cwdPath, this.androidRootPath, "app/src/main/AndroidManifest.xml");
+    let manifest = await readFile(manifestPath, "utf8");
+    let changed = false;
+    for (const scheme of schemes) {
+      if (manifest.includes(`android:scheme="${scheme}"`)) continue;
+      const filter = [
+        "            <intent-filter>",
+        '                <action android:name="android.intent.action.VIEW" />',
+        '                <category android:name="android.intent.category.DEFAULT" />',
+        '                <category android:name="android.intent.category.BROWSABLE" />',
+        `                <data android:scheme="${scheme}" />`,
+        "            </intent-filter>",
+      ].join("\n");
+      manifest = manifest.replace(/(\s*<\/activity>)/, `\n${filter}$1`);
+      changed = true;
+    }
+    if (changed) await writeFile(manifestPath, manifest);
+  }
+  async #setDeepLinksInAndroid(schemes: string[], domains: string[]) {
+    await this.#setUrlSchemesInAndroid(schemes);
+    const manifestPath = path.join(this.app.cwdPath, this.androidRootPath, "app/src/main/AndroidManifest.xml");
+    let manifest = await readFile(manifestPath, "utf8");
+    let changed = false;
+    const pathPrefix = resolveMobilePath(this.target, "/");
+    for (const domain of domains) {
+      if (manifest.includes(`android:host="${domain}"`) && manifest.includes('android:scheme="https"')) continue;
+      const filter = [
+        '            <intent-filter android:autoVerify="true">',
+        '                <action android:name="android.intent.action.VIEW" />',
+        '                <category android:name="android.intent.category.DEFAULT" />',
+        '                <category android:name="android.intent.category.BROWSABLE" />',
+        `                <data android:scheme="https" android:host="${domain}" android:pathPrefix="${pathPrefix}" />`,
+        "            </intent-filter>",
+      ].join("\n");
+      manifest = manifest.replace(/(\s*<\/activity>)/, `\n${filter}$1`);
+      changed = true;
+    }
+    if (changed) await writeFile(manifestPath, manifest);
+  }
   #setFeaturesInAndroid(features: string[]) {
     for (const feature of features) {
       if (this.#hasFeatureInAndroid(feature)) {

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -77,6 +77,15 @@ export class SsrBaseArtifactBuilder {
       branches: [...akanConfig.branches],
       i18n: akanConfig.i18n,
       imageConfig: akanConfig.images,
+      deepLinkAssociations: Object.values(akanConfig.mobile.targets)
+        .filter((target) => (target.deepLinks?.domains?.length ?? 0) > 0)
+        .map((target) => ({
+          targetName: target.name,
+          appId: target.appId,
+          domains: target.deepLinks?.domains ?? [],
+          iosTeamId: target.deepLinks?.ios?.teamId,
+          androidSha256CertFingerprints: target.deepLinks?.android?.sha256CertFingerprints,
+        })),
     };
     await Bun.write(path.join(this.#absArtifactDir, "base-artifact.json"), `${JSON.stringify(artifact, null, 2)}\n`);
     this.#app.verbose(`[base-artifact] complete in ${Date.now() - this.#started}ms`);

package/index.ts

@@ -27,6 +27,7 @@ export * from "./guideline";
 export * from "./incrementalBuilder";
 export * from "./mobile";
 export * from "./prompter";
+export * from "./qualityScanner";
 export * from "./scanInfo";
 export * from "./selectModel";
 export * from "./spinner";

package/package.json

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

package/qualityScanner.ts

@@ -0,0 +1,687 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import ignore from "ignore";
+import ts from "typescript";
+
+type QualitySeverity = "warning";
+type QualityScope = "global" | "file" | "convention" | "layout";
+
+export interface QualityWarning {
+  rule: string;
+  scope: QualityScope;
+  severity: QualitySeverity;
+  message: string;
+  file?: string;
+  line?: number;
+  locations?: Array<{ file: string; line: number }>;
+}
+
+export interface QualityScanResult {
+  workspaceRoot: string;
+  scannedFiles: number;
+  warnings: QualityWarning[];
+  suggestedRules: string[];
+}
+
+interface SourceFileInfo {
+  file: string;
+  absolutePath: string;
+  content: string;
+  sourceFile: ts.SourceFile;
+}
+
+interface ExportedFunctionLike {
+  name: string;
+  kind: "class" | "function" | "function-variable";
+  file: string;
+  line: number;
+  bodyFingerprint?: string;
+}
+
+interface TopLevelDeclaration {
+  name: string;
+  kind: string;
+  line: number;
+  exported: boolean;
+  node: ts.Statement;
+}
+
+const MAX_FILE_LINES = 2000;
+const PLACEHOLDER_EXPORT_NAMES = new Set([
+  "aa",
+  "dumb",
+  "dumb2",
+  "someBaseLogic",
+  "someCommonLogic",
+  "someFrontendLogic",
+  "someBackendLogic",
+]);
+
+const 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, 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.",
+];
+
+const APP_ROOT_FILES = new Set([
+  "akan.app.json",
+  "akan.config.ts",
+  "capacitor.config.ts",
+  "client.ts",
+  "main.ts",
+  "package.json",
+  "server.ts",
+  "tsconfig.json",
+]);
+
+const LIB_ROOT_FILES = new Set([
+  "cnst.ts",
+  "db.ts",
+  "dict.ts",
+  "option.ts",
+  "sig.ts",
+  "srv.ts",
+  "st.ts",
+  "useClient.ts",
+  "useServer.ts",
+]);
+
+const CONVENTION_SUFFIXES = [
+  ".constant.ts",
+  ".dictionary.ts",
+  ".document.ts",
+  ".service.ts",
+  ".signal.ts",
+  ".store.ts",
+] as const;
+
+export class AkanQualityScanner {
+  async scan(workspaceRoot: string): Promise<QualityScanResult> {
+    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.#scanConventionQuality(sourceFile)),
+      ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
+    ];
+
+    return {
+      workspaceRoot,
+      scannedFiles: sourceFiles.length,
+      warnings: warnings.sort(compareWarnings),
+      suggestedRules: SUGGESTED_RULES,
+    };
+  }
+
+  async #collectTargetFiles(workspaceRoot: string) {
+    const ignoreFilter = ignore().add(await this.#readGitIgnore(workspaceRoot));
+    const files: string[] = [];
+    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: string) {
+    const gitIgnorePath = path.join(workspaceRoot, ".gitignore");
+    if (!(await Bun.file(gitIgnorePath).exists())) return [];
+    return (await readFile(gitIgnorePath, "utf8")).split(/\r?\n/);
+  }
+
+  async #walkTargetFiles(
+    workspaceRoot: string,
+    currentPath: string,
+    ignoreFilter: ReturnType<typeof ignore>,
+    files: string[],
+  ) {
+    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: string, file: string): Promise<SourceFileInfo> {
+    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: SourceFileInfo[]): QualityWarning[] {
+    const exportedFunctionLikes = sourceFiles.flatMap((sourceFile) => getExportedFunctionLikes(sourceFile));
+    const warnings: QualityWarning[] = [];
+
+    for (const [name, declarations] of groupBy(exportedFunctionLikes, (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: SourceFileInfo): QualityWarning[] {
+    const warnings: QualityWarning[] = [];
+    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;
+  }
+
+  #scanConventionQuality(sourceFile: SourceFileInfo): QualityWarning[] {
+    const suffix = CONVENTION_SUFFIXES.find((candidate) => sourceFile.file.endsWith(candidate));
+    if (!suffix) return [];
+
+    const modelName = toPascalCase(path.basename(sourceFile.file, suffix));
+    const warnings: QualityWarning[] = [];
+    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: SourceFileInfo): QualityWarning[] {
+    const segments = sourceFile.file.split("/");
+    const warnings: QualityWarning[] = [];
+    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;
+  }
+}
+
+export function formatQualityScanResult(result: QualityScanResult) {
+  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("\n");
+}
+
+export function formatQualityWarnings(warnings: QualityWarning[]) {
+  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)}`),
+      );
+    }
+    return lines;
+  });
+}
+
+function formatQualityLocation(file: string | undefined, line: number | undefined) {
+  return `${file ?? "<global>"}:${line ?? 1}:1`;
+}
+
+function getExportedFunctionLikes(sourceFile: SourceFileInfo): ExportedFunctionLike[] {
+  const declarations: ExportedFunctionLike[] = [];
+  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),
+      });
+    }
+    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),
+      });
+    }
+    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),
+        });
+      }
+    }
+  }
+  return declarations;
+}
+
+function getExportedClassNames(sourceFile: ts.SourceFile) {
+  return sourceFile.statements
+    .filter((statement): statement is ts.ClassDeclaration => ts.isClassDeclaration(statement) && !!statement.name)
+    .filter((statement) => isExported(statement))
+    .map((statement) => statement.name!.text);
+}
+
+function getPlaceholderExportWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
+  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: SourceFileInfo): QualityWarning[] {
+  if (!sourceFile.file.endsWith(".dictionary.ts")) return [];
+  const stalePatterns = [
+    { pattern: /\b[A-Z][A-Za-z0-9]* description\b/, label: "scaffold description text" },
+    { pattern: /settting/, label: "misspelling: settting" },
+    { pattern: /배너 수/, label: "stale copied Korean domain noun: 배너 수" },
+  ];
+  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: SourceFileInfo): QualityWarning[] {
+  const warnings: QualityWarning[] = [];
+  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: SourceFileInfo): TopLevelDeclaration[] {
+  return sourceFile.sourceFile.statements.flatMap((statement) =>
+    getTopLevelDeclaration(sourceFile.sourceFile, statement),
+  );
+}
+
+function getTopLevelDeclaration(sourceFile: ts.SourceFile, statement: ts.Statement): TopLevelDeclaration[] {
+  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 as ts.Identifier).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: (typeof CONVENTION_SUFFIXES)[number],
+  modelName: string,
+  declaration: TopLevelDeclaration,
+) {
+  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: string, declaration: TopLevelDeclaration) {
+  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: (typeof CONVENTION_SUFFIXES)[number], modelName: string) {
+  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: string) {
+  const segments = file.split("/");
+  if (segments[0] === "libs" && segments.length === 4 && segments[2] === "lib") return segments[3];
+  if (segments[0] === "apps" && segments.length === 5 && segments[2] === "lib") return segments[4];
+  return null;
+}
+
+function getModuleUiWarning(file: string): QualityWarning | null {
+  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: string) {
+  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" as const };
+  }
+  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" as const };
+  }
+  if (moduleName.startsWith("_")) return { moduleName, fileName, kind: "service" as const };
+  return { moduleName, fileName, kind: "database" as const };
+}
+
+function isExportedConst(declaration: TopLevelDeclaration) {
+  return (
+    declaration.exported &&
+    ts.isVariableStatement(declaration.node) &&
+    (declaration.node.declarationList.flags & ts.NodeFlags.Const) !== 0
+  );
+}
+
+function isExported(node: ts.Node) {
+  return (
+    !!ts.getCombinedModifierFlags(node as ts.Declaration) &&
+    !!(ts.getCombinedModifierFlags(node as ts.Declaration) & ts.ModifierFlags.Export)
+  );
+}
+
+function isFunctionLikeInitializer(node: ts.Expression | undefined) {
+  return !!node && (ts.isArrowFunction(node) || ts.isFunctionExpression(node));
+}
+
+function getBodyFingerprint(sourceFile: ts.SourceFile, node: ts.Node | undefined) {
+  if (!node) return undefined;
+  const normalizedBody = node.getText(sourceFile).replace(/\s+/g, " ").trim();
+  if (normalizedBody.length < 80) return undefined;
+  return createHash("sha256").update(normalizedBody).digest("hex");
+}
+
+function shouldSkipPath(relativePath: string, isDirectory: boolean, ignoreFilter: ReturnType<typeof ignore>) {
+  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: string) {
+  try {
+    return (await stat(absolutePath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function getScriptKind(file: string) {
+  return file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+}
+
+function getLine(sourceFile: ts.SourceFile, node: ts.Node) {
+  return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+}
+
+function getRecommendedLineLimit(file: string) {
+  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: string, pattern: RegExp) {
+  return content.split(/\r?\n/).flatMap((line, index) => (pattern.test(line) ? [index + 1] : []));
+}
+
+function toPascalCase(value: string) {
+  return value.replace(/(^|[-_./])([a-zA-Z0-9])/g, (_, __, char: string) => char.toUpperCase()).replace(/[-_./]/g, "");
+}
+
+function toPosix(value: string) {
+  return value.split(path.sep).join("/");
+}
+
+function groupBy<T>(items: T[], getKey: (item: T) => string) {
+  const grouped = new Map<string, T[]>();
+  for (const item of items) {
+    const key = getKey(item);
+    grouped.set(key, [...(grouped.get(key) ?? []), item]);
+  }
+  return grouped;
+}
+
+function compareWarnings(a: QualityWarning, b: QualityWarning) {
+  return (
+    a.scope.localeCompare(b.scope) ||
+    (a.file ?? "").localeCompare(b.file ?? "") ||
+    (a.line ?? 0) - (b.line ?? 0) ||
+    a.rule.localeCompare(b.rule)
+  );
+}