@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { optimize } from "@tailwindcss/node";
+import type { AkanNativeAppId, AkanWebConfig } from "akanjs";
 import type { BaseBuildArtifact } from "akanjs/server";
 import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import { computeRouteSeedIndex, type RouteSeedIndex, saveRouteSeedIndex } from "../artifact/routeSeedIndex";
@@ -36,6 +37,12 @@ export class SsrBaseArtifactBuilder {
     this.#absArtifactDir = path.resolve(this.#artifactDir);
   }
 
+  //? The web router reads this, so `akan start` writes the whole surface: a native shell asks the dev server for the
+  //? CSR page even when the app ships none, and a narrowed dev artifact hands it the SSR page, which cannot run there.
+  static servedWeb(command: "build" | "start", web: AkanWebConfig): AkanWebConfig {
+    return command === "start" ? { ssr: true, csr: true } : web;
+  }
+
   async build(): Promise<BuildSsrBaseArtifactResult> {
     const akanConfig = await this.#app.getConfig();
     const { rscClientUrl, rscRuntimeClientManifest, rscRuntimeSsrManifest, vendorMap } =
@@ -77,15 +84,16 @@ export class SsrBaseArtifactBuilder {
       branches: [...akanConfig.branches],
       i18n: akanConfig.i18n,
       imageConfig: akanConfig.images,
-      web: akanConfig.web,
-      deepLinkAssociations: Object.values(akanConfig.mobile.targets)
+      web: SsrBaseArtifactBuilder.servedWeb(this.#command, akanConfig.web),
+      deepLinkAssociations: Object.values(akanConfig.native.targets)
         .filter((target) => (target.deepLinks?.domains?.length ?? 0) > 0)
         .map((target) => ({
           targetName: target.name,
-          appId: target.appId,
+          iosAppId: SsrBaseArtifactBuilder.#appIdOn(target.appId, "ios"),
+          androidAppId: SsrBaseArtifactBuilder.#appIdOn(target.appId, "android"),
           domains: target.deepLinks?.domains ?? [],
-          iosTeamId: target.deepLinks?.ios?.teamId,
-          androidSha256CertFingerprints: target.deepLinks?.android?.sha256CertFingerprints,
+          iosTeamId: target.ios?.teamId,
+          androidSha256CertFingerprints: target.android?.sha256CertFingerprints,
         })),
     };
     await Bun.write(path.join(this.#absArtifactDir, "base-artifact.json"), `${JSON.stringify(artifact, null, 2)}\n`);
@@ -185,8 +193,7 @@ export class SsrBaseArtifactBuilder {
   }> {
     const cssCompiler = new CssCompiler(this.#app);
     const cssByBasePath = await cssCompiler.getCssByBasePath();
-    // 스타일 계약(어휘 폐쇄 + WCAG)은 빌드가 아니라 lint 가 강제한다: 어휘 폐쇄는 biome grit 플러그인
-    // (devkit/lint/no-raw-palette-class.grit 외 3종), 콘트라스트는 `akan lint` 의 themeValidator.
+    // The style contract (vocabulary closure, WCAG contrast) is enforced by `akan lint`, not by the build.
     const optimizedFonts = await new FontOptimizer(this.#app, this.#command).optimize();
     const cssAssets = Object.fromEntries(
       await Promise.all(
@@ -216,12 +223,11 @@ export class SsrBaseArtifactBuilder {
     return [basePath, { cssUrl, cssRelPath }] as const;
   }
 
-  /**
-   * Checked against the file written here rather than against the compiled text, because this is the stylesheet
-   * `base-artifact.json` points at and therefore the only one an SSR render serves. A declaration can survive
-   * the compile and still be missing from the asset — a build that ships CSS to the CSR bundle and not to the
-   * server is indistinguishable, in the browser, from a theme that was never written.
-   */
+  // Checked against the written asset, not the compiled text: it is the only stylesheet an SSR render serves.
+  static #appIdOn(appId: AkanNativeAppId, platform: "ios" | "android"): string | null {
+    return typeof appId === "string" ? appId : (appId[platform] ?? appId.default ?? null);
+  }
+
   static #warnDroppedImports(app: App, cssRelPath: string, css: string, imported: ImportedStylesheet[]) {
     for (const { cssPath, declaredNames } of imported) {
       if (declaredNames.length === 0 || declaredNames.some((name) => css.includes(`${name}:`))) continue;

package/frontendBuild/ssrDevBundler.ts

@@ -0,0 +1,85 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { SSR_DEV_DIRNAME, SSR_DEV_ROUTE_PREFIX } from "akanjs/server/hmr/csrDevManifest";
+import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
+import { computeRouteSeedIndex } from "../artifact/routeSeedIndex";
+import type { App } from "../commandDecorators";
+import { bundleDefine } from "./bundleDefine";
+import type { ClientEntryDiscovery } from "./clientBuildTypes";
+import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
+import { CsrDevPaths } from "./csrDevPaths";
+import type { CsrDevContext } from "./csrDevTypes";
+import { DevRegistryBundler } from "./devRegistryBundler";
+import { VENDOR_SPECIFIERS } from "./vendorSpecifiers";
+
+//* Dev-only client code of SSR pages as a module registry, under `.akan/artifact/ssr-dev`. Its roots are a bootstrap
+//* (the app's client runtime) and every `"use client"` entry; React and the akanjs vendor facets stay the import map's,
+//* so the page keeps one React and one store registry.
+export class SsrDevBundler extends DevRegistryBundler {
+  static readonly #formatVersion = 2;
+  static readonly bootstrapKey = "";
+  readonly reloadsOnEntryChange = false;
+  #discovery: ClientEntryDiscovery | null = null;
+  readonly #sharedDiscovery: (() => ClientEntryDiscovery) | null;
+
+  /** `discovery` is the resident builder's, which it keeps current with every save; a worker discovers afresh. */
+  constructor(app: App, { discovery }: { discovery?: () => ClientEntryDiscovery } = {}) {
+    super(app, { dirName: SSR_DEV_DIRNAME, routePrefix: SSR_DEV_ROUTE_PREFIX, library: true });
+    this.#sharedDiscovery = discovery ?? null;
+  }
+
+  async context(): Promise<CsrDevContext> {
+    const akanConfig = await this.app.getConfig();
+    const define = bundleDefine(this.app, "start", "ssr");
+    const optimizeImports = [...akanConfig.optimizeImports];
+    const configKey = Bun.hash(
+      JSON.stringify(["ssr", SsrDevBundler.#formatVersion, Bun.version, define, optimizeImports, VENDOR_SPECIFIERS]),
+    ).toString(36);
+    return {
+      pageEntries: [],
+      basePaths: [...akanConfig.basePaths],
+      htmlBasePaths: [],
+      define,
+      optimizeImports,
+      configKey,
+      refreshFile: null,
+      externals: VENDOR_SPECIFIERS,
+    };
+  }
+
+  //? The client runtime of an SSR page inlines no dictionary (`useClient.ts` reads one only when rendering csr), so
+  //? a dictionary save is none of this registry's business.
+  override isMetadataFile(file: string): boolean {
+    return super.isMetadataFile(file) && !file.endsWith(".dictionary.ts") && path.basename(file) !== "dict.ts";
+  }
+
+  // Run first in the tab, before any client module the payload names: the store registry must exist by then.
+  async writeEntries(): Promise<{ files: Record<string, string>; changed: string[] }> {
+    await mkdir(this.entryDir, { recursive: true });
+    const file = path.join(this.entryDir, "bootstrap.ts");
+    const hasStore = await Bun.file(path.join(this.app.cwdPath, "lib", "st.ts")).exists();
+    const source = hasStore ? `import ${JSON.stringify(`@apps/${this.app.name}/client`)};\n` : "export {};\n";
+    const unchanged = (await Bun.file(file).exists()) && (await Bun.file(file).text()) === source;
+    if (!unchanged) await Bun.write(file, source);
+    const entryFile = CsrDevPaths.realpath(file);
+    return { files: { [SsrDevBundler.bootstrapKey]: entryFile }, changed: unchanged ? [] : [entryFile] };
+  }
+
+  /** Every `"use client"` entry the app's routes reach, the ones a route build names in its manifest. */
+  async clientEntries(): Promise<string[]> {
+    const pageEntries = await resolveSsrPageEntriesForApp(this.app, await this.app.getPageKeys());
+    const seedIndex = computeRouteSeedIndex(pageEntries);
+    const seeds = [...new Set([...seedIndex.globalLayoutFiles, ...seedIndex.entries.flatMap((entry) => entry.seeds)])];
+    const discovery = this.#sharedDiscovery?.() ?? (await this.#ownDiscovery());
+    return (await discovery.discover(seeds)).map((file) => CsrDevPaths.realpath(file));
+  }
+
+  async #ownDiscovery(): Promise<ClientEntryDiscovery> {
+    this.#discovery ??= await GraphClientEntryDiscovery.create(this.app);
+    return this.#discovery;
+  }
+
+  protected async rootFiles(entryFiles: string[]): Promise<string[]> {
+    return [...entryFiles, ...(await this.clientEntries())];
+  }
+}

package/frontendBuild/styleContract.ts

@@ -1,11 +1,4 @@
-/**
- * Reports the style contract that `akan lint` enforces, in the shape build/dev/lint share.
- *
- * Only contrast lives here. The vocabulary closure — raw palette classes, arbitrary colors, dropped
- * daisyUI slots, inline color literals, interpolated arbitrary values — is enforced by the grit plugins
- * in `lint/*.grit` during the biome run, so it is not re-scanned. Contrast cannot be a lint rule at all:
- * it is arithmetic over resolved token *values*, which no syntactic pattern can reach.
- */
+// Only contrast: `lint/*.grit` enforces the vocabulary closure, and contrast is arithmetic no syntactic rule can do.
 import type { ThemeContrastViolation } from "./themeValidator";
 
 export interface StyleContractViolations {

package/frontendBuild/themeValidator.ts

@@ -1,18 +1,4 @@
-/**
- * WCAG contrast checking over the semantic token pairs. No dependencies, pure functions, and no akanjs
- * runtime import — it has to run inside the lint path.
- *
- * The `--x` / `--x-foreground` pairing is what makes the check possible at all: it says which two values
- * are going to end up on top of each other. That is the guard against a generated palette shipping a site
- * nobody can read.
- *
- * Thresholds (WCAG 2.1):
- *   - body and primary surfaces (background, primary, secondary, accent, neutral, card, popover): 4.5:1,
- *     the AA floor for normal text
- *   - status and secondary pairs (info, success, warning, destructive, open, muted): 3:1, the AA floor for
- *     UI components and large text
- * The shipped light/dark palette in styles.css clears all of them.
- */
+// No akanjs runtime import: this runs inside the lint path.
 
 export interface ThemeContrastViolation {
   scope: string;
@@ -30,6 +16,7 @@ interface PairDef {
   threshold: number;
 }
 
+// WCAG 2.1 AA: 4.5:1 is the floor for normal text, 3:1 for UI components and large text.
 const PAIRS: PairDef[] = [
   { base: "background", fg: "foreground", threshold: 4.5 },
   { base: "primary", fg: "primary-foreground", threshold: 4.5 },
@@ -46,13 +33,11 @@ const PAIRS: PairDef[] = [
   { base: "open", fg: "open-foreground", threshold: 3 },
 ];
 
-// Only these scopes are paired up; tokens scoped to something else (`.campaign-x`, …) are left alone.
 const THEME_SCOPES = new Set([":root", '[data-theme="dark"]', '[data-theme="light"]']);
 
 export type ThemeTokensByScope = Record<string, Record<string, string>>;
 
 export class ThemeValidator {
-  /** Extracts tokens from the css text and checks every scope it recognizes. */
   validate(css: string): ThemeContrastViolation[] {
     const tokensByScope = ThemeValidator.parseThemeTokens(css);
     const violations: ThemeContrastViolation[] = [];
@@ -71,7 +56,7 @@ export class ThemeValidator {
       if (!bg || !front) continue;
       const bgRgb = ThemeValidator.parseHex(bg);
       const fgRgb = ThemeValidator.parseHex(front);
-      if (!bgRgb || !fgRgb) continue; // a var() or non-hex value has no ratio to compute
+      if (!bgRgb || !fgRgb) continue;
       const ratio = ThemeValidator.contrastRatio(bgRgb, fgRgb);
       if (ratio >= threshold) continue;
       violations.push({
@@ -87,15 +72,9 @@ export class ThemeValidator {
     return violations;
   }
 
-  /**
-   * Reads `--token: value` out of `:root` / `[data-theme="…"]` blocks. A grouped selector
-   * (`:root, [data-theme="dark"] { … }`) distributes the same tokens to each selector, and a scope that
-   * appears twice keeps the later value — so passing framework css first and the app's second reflects the
-   * app's overrides.
-   */
+  /** A scope declared twice keeps the later value, so pass the framework css before the app's. */
   static parseThemeTokens(css: string): ThemeTokensByScope {
     const result: ThemeTokensByScope = {};
-    // Flat rule blocks only; an at-rule (@theme, @keyframes) carries `@` in the selector and is skipped.
     const blockRe = /(?:^|})\s*([^{}@]+?)\s*\{([^{}]*)\}/g;
     for (const block of css.matchAll(blockRe)) {
       const selectors = block[1].split(",").map((s) => s.trim());
@@ -114,7 +93,6 @@ export class ThemeValidator {
   }
 
   static #normalizeScope(selector: string): string {
-    // Quote normalization: [data-theme=dark] / [data-theme='dark'] -> [data-theme="dark"]
     return selector.replace(/\[data-theme=['"]?([\w-]+)['"]?\]/g, '[data-theme="$1"]').trim();
   }
 

package/frontendBuild/watchRootResolver.test.ts

@@ -1,15 +1,14 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import type { App } from "../commandDecorators";
+import { tempDirs } from "../testHelpers";
 import { WatchRootResolver } from "./watchRootResolver";
 
-const roots: string[] = [];
+const tempRoot = tempDirs("akan-watch-roots-");
 
 const makeWorkspace = async (dirs: string[]) => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-watch-roots-"));
-  roots.push(root);
+  const root = await tempRoot();
   await Promise.all(dirs.map((dir) => mkdir(path.join(root, dir), { recursive: true })));
   return root;
 };
@@ -25,24 +24,18 @@ interface AppStub {
   libDeps?: string[] | null;
 }
 
-const makeApp = (workspaceRoot: string, name: string, { paths = {}, libDeps = null }: AppStub = {}) =>
-  ({
-    cwdPath: path.join(workspaceRoot, "apps", name),
+const resolveRoots = (workspaceRoot: string, { paths = {}, libDeps = null }: AppStub = {}) =>
+  new WatchRootResolver({
+    cwdPath: path.join(workspaceRoot, "apps", "app1"),
     workspace: { workspaceRoot },
     getTsConfig: async () => ({ compilerOptions: { paths } }),
     getScanInfo: () => (libDeps ? { type: "app", libDeps } : null),
-  }) as unknown as App;
-
-afterEach(async () => {
-  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
+  } as unknown as App).resolve();
 
 describe("WatchRootResolver", () => {
   test("narrows the apps container to the app being served", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page", "apps/app2/page", "libs/util"]);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", { paths: { "@apps/*": ["./apps/*"], "@libs/*": ["./libs/*"] } }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, { paths: { "@apps/*": ["./apps/*"], "@libs/*": ["./libs/*"] } });
 
     expect(resolved).toContain(path.join(workspaceRoot, "apps/app1"));
     expect(resolved).not.toContain(path.join(workspaceRoot, "apps"));
@@ -51,9 +44,7 @@ describe("WatchRootResolver", () => {
 
   test("narrows the libs container to the app's own dependencies", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util", "libs/shared"]);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] }, libDeps: ["util"] }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, { paths: { "@libs/*": ["./libs/*"] }, libDeps: ["util"] });
 
     expect(resolved).toContain(path.join(workspaceRoot, "libs/util"));
     expect(resolved).not.toContain(path.join(workspaceRoot, "libs"));
@@ -63,9 +54,7 @@ describe("WatchRootResolver", () => {
   test("drops the libs container entirely when the app depends on no lib", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util"]);
     await writeManifest(workspaceRoot, "apps/app1", []);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] } }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, { paths: { "@libs/*": ["./libs/*"] } });
 
     expect(resolved).toEqual([path.join(workspaceRoot, "apps/app1/page")]);
   });
@@ -76,9 +65,7 @@ describe("WatchRootResolver", () => {
     await writeManifest(workspaceRoot, "libs/shared", ["util"]);
     await writeManifest(workspaceRoot, "libs/util", []);
     await writeManifest(workspaceRoot, "libs/unused", []);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] } }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, { paths: { "@libs/*": ["./libs/*"] } });
 
     expect(resolved).toContain(path.join(workspaceRoot, "libs/shared"));
     expect(resolved).toContain(path.join(workspaceRoot, "libs/util"));
@@ -87,9 +74,7 @@ describe("WatchRootResolver", () => {
 
   test("keeps the libs container whole when the app manifest is missing", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util", "libs/shared"]);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] } }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, { paths: { "@libs/*": ["./libs/*"] } });
 
     expect(resolved).toContain(path.join(workspaceRoot, "libs"));
   });
@@ -97,24 +82,20 @@ describe("WatchRootResolver", () => {
   test("keeps the libs container whole when a dependency lib is unsynced", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page", "libs/util", "libs/shared"]);
     await writeManifest(workspaceRoot, "apps/app1", ["shared"]);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", { paths: { "@libs/*": ["./libs/*"] } }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, { paths: { "@libs/*": ["./libs/*"] } });
 
     expect(resolved).toContain(path.join(workspaceRoot, "libs"));
   });
 
   test("resolves a package alias to its own directory, filename and glob stripped", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page", "pkgs/akanjs/base"]);
-    const resolved = await new WatchRootResolver(
-      makeApp(workspaceRoot, "app1", {
-        paths: {
-          akanjs: ["./pkgs/akanjs/index.ts"],
-          "akanjs/*": ["./pkgs/akanjs/*"],
-          missing: ["./pkgs/nothing/index.ts"],
-        },
-      }),
-    ).resolve();
+    const resolved = await resolveRoots(workspaceRoot, {
+      paths: {
+        akanjs: ["./pkgs/akanjs/index.ts"],
+        "akanjs/*": ["./pkgs/akanjs/*"],
+        missing: ["./pkgs/nothing/index.ts"],
+      },
+    });
 
     expect(resolved).toContain(path.join(workspaceRoot, "pkgs/akanjs"));
     expect(resolved).not.toContain(path.join(workspaceRoot, "pkgs/nothing"));
@@ -122,7 +103,7 @@ describe("WatchRootResolver", () => {
 
   test("always watches the app's page tree", async () => {
     const workspaceRoot = await makeWorkspace(["apps/app1/page"]);
-    const resolved = await new WatchRootResolver(makeApp(workspaceRoot, "app1")).resolve();
+    const resolved = await resolveRoots(workspaceRoot);
 
     expect(resolved).toEqual([path.join(workspaceRoot, "apps/app1/page")]);
   });

package/frontendBuild/watchRootResolver.ts

@@ -3,23 +3,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import type { App } from "../commandDecorators";
 
-/**
- * The directories one app's dev watcher follows, resolved from its tsconfig `paths`.
- *
- * Two aliases strip down to a workspace container rather than a package, and taking either verbatim puts
- * code the app never imports under the watcher — where a save rebuilds, restarts and reloads it for
- * nothing, and both builders rewrite the same generated barrels:
- *
- * - `@apps/*` becomes the `apps/` container. Apps are leaves of the workspace graph — never one another's
- *   dependencies — so it is replaced by this app's own directory.
- * - `@libs/*` becomes the `libs/` container. A lib is a dependency only if the app reaches it, so it is
- *   replaced by the app's own lib dependencies, transitively. The set is resolved once, at watcher
- *   install: a lib that becomes a dependency mid-session needs a fresh `akan start` anyway, because the
- *   import that made it one also needs a `sync`.
- *
- * Failing to resolve that set keeps the container whole, because a wrong narrowing is a dev server that
- * silently ignores edits.
- */
+/** Watch roots from tsconfig paths: `@apps/*` narrows to this app, `@libs/*` to its lib deps (whole when unknown). */
 export class WatchRootResolver {
   #app: App;
 
@@ -32,14 +16,15 @@ export class WatchRootResolver {
     const appDir = path.resolve(this.#app.cwdPath);
     const appsContainer = path.dirname(appDir);
     const libsContainer = path.resolve(this.#app.workspace.workspaceRoot, "libs");
-    const libRoots = await this.#resolveLibRoots(libsContainer);
+    const libRoots = (await this.#resolveLibDeps(libsContainer))
+      ?.map((name) => path.join(libsContainer, name))
+      .filter((dir) => fs.existsSync(dir));
     const set = new Set<string>();
     set.add(path.resolve(`${this.#app.cwdPath}/page`));
     for (const targets of Object.values(tsconfig.compilerOptions.paths ?? {})) {
       for (const target of targets) {
         if (!target) continue;
         if (path.isAbsolute(target)) continue;
-        // Strip the trailing filename and glob so we watch the package root dir.
         const cleaned = target.replace(/\/?\*+.*$/, "").replace(/\/[^/]+\.[^/]+$/, "");
         const resolved = path.resolve(this.#app.workspace.workspaceRoot, cleaned);
         if (resolved === libsContainer && libRoots) {
@@ -53,16 +38,9 @@ export class WatchRootResolver {
     return [...set];
   }
 
-  async #resolveLibRoots(libsContainer: string): Promise<string[] | null> {
-    const libDeps = await this.#resolveLibDeps(libsContainer);
-    if (!libDeps) return null;
-    return libDeps.map((name) => path.join(libsContainer, name)).filter((dir) => fs.existsSync(dir));
-  }
-
   async #resolveLibDeps(libsContainer: string): Promise<string[] | null> {
     const scanInfo = this.#app.getScanInfo({ allowEmpty: true });
-    // Already transitive, and present whenever this runs in a process that scanned. The builder and the
-    // idle watcher run in processes that did not, so they take the manifests `scan` wrote instead.
+    // Transitive, but only in a process that scanned; the builder and idle watcher read the synced manifests.
     if (scanInfo?.type === "app") return scanInfo.libDeps;
     const direct = await WatchRootResolver.#readManifestLibDeps(path.join(this.#app.cwdPath, "akan.app.json"));
     if (!direct) return null;

package/getRelatedCnsts.ts

@@ -40,9 +40,6 @@ const scanModuleSpecifiers = (source: string, filePath: string, includeExports:
   return importSpecifiers;
 };
 
-/**
- * TypeScript 설정 파일을 읽고 파싱하는 함수
- */
 export const parseTsConfig = (tsConfigPath: string = "./tsconfig.json") => {
   const configFile = ts.readConfigFile(tsConfigPath, (path) => {
     return ts.sys.readFile(path);
@@ -51,85 +48,36 @@ export const parseTsConfig = (tsConfigPath: string = "./tsconfig.json") => {
   return ts.parseJsonConfigFileContent(configFile.config, ts.sys, realpathSync(tsConfigPath).replace(/[^/\\]+$/, ""));
 };
 
-/**
- * 파일 내의 임포트를 기반으로 관련 파일을 수집하는 함수
- */
-export const collectImportedFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine) => {
+const collectFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine, includeExports: boolean) => {
   const allFilesToAnalyze = new Set<string>([constantFilePath]);
   const analyzedFiles = new Set<string>();
-  const spinner = ora("Collecting related files...");
+  const spinner = ora(includeExports ? "Collecting files from exports..." : "Collecting related files...");
   spinner.start();
-
-  function collectImported(filePath: string) {
+  const collect = (filePath: string) => {
     if (analyzedFiles.has(filePath)) return;
     analyzedFiles.add(filePath);
-
     const source = readFileSync(filePath, "utf-8");
-    for (const importPath of scanModuleSpecifiers(source, filePath, false)) {
+    for (const importPath of scanModuleSpecifiers(source, filePath, includeExports)) {
       if (!importPath.startsWith(".")) continue;
-
       const resolved = ts.resolveModuleName(importPath, filePath, parsedConfig.options, ts.sys).resolvedModule
         ?.resolvedFileName;
-
       if (resolved && !allFilesToAnalyze.has(resolved)) {
         allFilesToAnalyze.add(resolved);
-        // 재귀적으로 임포트된 파일의 임포트도 수집
-        collectImported(resolved);
+        collect(resolved);
       }
     }
-  }
-
-  // 임포트 기반 관련 파일 수집 실행
-  collectImported(constantFilePath);
-  spinner.succeed(`Found ${allFilesToAnalyze.size} related files.`);
-
-  return {
-    allFilesToAnalyze,
-    analyzedFiles,
   };
+  collect(constantFilePath);
+  spinner.succeed(`Found ${allFilesToAnalyze.size} related files${includeExports ? " from exports" : ""}.`);
+  return { allFilesToAnalyze, analyzedFiles };
 };
 
-/**
- * export 선언을 기반으로 관련 파일을 수집하는 함수
- */
-export const collectExportedFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine) => {
-  const allFilesToAnalyze = new Set<string>([constantFilePath]);
-  const analyzedFiles = new Set<string>();
-  const spinner = ora("Collecting files from exports...");
-  spinner.start();
-
-  function collectExported(filePath: string) {
-    if (analyzedFiles.has(filePath)) return;
-    analyzedFiles.add(filePath);
+export const collectImportedFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine) =>
+  collectFiles(constantFilePath, parsedConfig, false);
 
-    const source = readFileSync(filePath, "utf-8");
-    for (const importPath of scanModuleSpecifiers(source, filePath, true)) {
-      if (!importPath.startsWith(".")) continue;
+export const collectExportedFiles = (constantFilePath: string, parsedConfig: ts.ParsedCommandLine) =>
+  collectFiles(constantFilePath, parsedConfig, true);
 
-      const resolved = ts.resolveModuleName(importPath, filePath, parsedConfig.options, ts.sys).resolvedModule
-        ?.resolvedFileName;
-
-      if (resolved && !allFilesToAnalyze.has(resolved)) {
-        allFilesToAnalyze.add(resolved);
-        // 재귀적으로 export/import 연결 파일도 확인
-        collectExported(resolved);
-      }
-    }
-  }
-
-  // export 기반 관련 파일 수집 실행
-  collectExported(constantFilePath);
-  spinner.succeed(`Found ${allFilesToAnalyze.size} related files from exports.`);
-
-  return {
-    allFilesToAnalyze,
-    analyzedFiles,
-  };
-};
-
-/**
- * TypeScript 프로그램 생성 함수
- */
 export const createTsProgram = (filePaths: Set<string>, options: ts.CompilerOptions) => {
   const spinner = ora("Creating TypeScript program for all files...");
   spinner.start();
@@ -145,9 +93,6 @@ export const createTsProgram = (filePaths: Set<string>, options: ts.CompilerOpti
   };
 };
 
-/**
- * 심볼 캐싱 및 조회 함수 생성기
- */
 export const createSymbolCache = (checker: ts.TypeChecker) => {
   const symbolCache = new Map<string, ts.Symbol | undefined>();
 
@@ -162,9 +107,6 @@ export const createSymbolCache = (checker: ts.TypeChecker) => {
   };
 };
 
-/**
- * 파일 속성 분석 함수
- */
 export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Program, checker: ts.TypeChecker) => {
   const propertyMap = new Map<
     string,
@@ -185,7 +127,6 @@ export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Progr
   const spinner = ora("Analyzing property relationships...");
   spinner.start();
 
-  // 파일 내 속성 분석 함수
   function analyzeFileProperties(filePath: string) {
     if (analyzedFiles.has(filePath)) return;
     analyzedFiles.add(filePath);
@@ -193,23 +134,19 @@ export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Progr
     const source = program.getSourceFile(filePath);
     if (!source) return;
 
-    // 소스 라인 캐싱 (한 번만 분할)
     if (!sourceLineCache.has(filePath)) {
       sourceLineCache.set(filePath, source.getFullText().split("\n"));
     }
     const sourceLines = sourceLineCache.get(filePath);
 
-    // 속성 분석 함수
     function visit(node: ts.Node) {
       if (!source) return;
 
-      // 프로퍼티 접근 표현식 처리
       if (ts.isPropertyAccessExpression(node)) {
         const left = node.expression;
         const right = node.name;
         const { line } = ts.getLineAndCharacterOfPosition(source, node.getStart());
 
-        // 패턴 검색 로직 - 기존 문자열 기반 검색 유지
         if (
           ts.isIdentifier(left) &&
           sourceLines &&
@@ -219,14 +156,12 @@ export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Progr
           (sourceLines[line]?.includes(`@Field.Prop(() => ${left.text}.${right.text}`) ||
             sourceLines[line].includes(`base.Filter(${left.text}.${right.text},`))
         ) {
-          // 캐싱된 심볼 사용
           const symbol = getCachedSymbol(right);
 
           if (symbol?.declarations && symbol.declarations.length > 0) {
             const key = symbol.declarations[0]?.getSourceFile().fileName.split("/").pop()?.split(".")[0] ?? "";
             const property = propertyMap.get(key);
             const isScalar = symbol.declarations[0]?.getSourceFile().fileName.includes("_") ?? false;
-            // 현재 작업 중인 디렉토리 이전은 제거
             const symbolFilePath = symbol.declarations[0]
               ?.getSourceFile()
               .fileName.replace(`${ts.sys.getCurrentDirectory()}/`, "");
@@ -254,7 +189,6 @@ export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Progr
           }
         }
       } else if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
-        // 모듈 선언 표현식 처리
         const importPath = node.moduleSpecifier.text;
 
         if (importPath.startsWith(".")) {
@@ -276,15 +210,12 @@ export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Progr
         }
       }
 
-      // 모든 자식 노드 처리
       ts.forEachChild(node, visit);
     }
 
-    // 파일 분석 시작
     visit(source);
   }
 
-  // 모든 파일의 속성 관계 분석
   for (const filePath of filesToAnalyze) {
     analyzeFileProperties(filePath);
   }
@@ -294,21 +225,10 @@ export const analyzeProperties = (filesToAnalyze: Set<string>, program: ts.Progr
   return propertyMap;
 };
 
-/**
- * 메인 함수: 상수 파일 관련 요소 분석
- */
 export const getRelatedCnsts = (constantFilePath: string) => {
-  // 1. TypeScript 설정 파일 읽기 및 파싱
   const parsedConfig = parseTsConfig();
-
-  // 2. 상수 파일 관련 파일 수집 (임포트 기반)
   const { allFilesToAnalyze } = collectImportedFiles(constantFilePath, parsedConfig);
-  // 3. TypeScript 프로그램 생성 및 타입 체커 설정
   const { program, checker } = createTsProgram(allFilesToAnalyze, parsedConfig.options);
-
-  // 4. 파일 속성 분석
   const propertyMap = analyzeProperties(allFilesToAnalyze, program, checker);
-
-  // 5. 결과 반환
   return Array.from(propertyMap.entries()).map(([key, value]) => ({ key, ...value }));
 };