@gaonjs/cli 0.2.0 → 0.4.0

package/dist/dev.d.ts

@@ -1,4 +1,4 @@
-import { type WatchHandle, type WatchOptions } from '@gaonjs/data';
+import type { WatchHandle, WatchOptions } from '@gaonjs/data';
 export interface DevApp {
     readonly name: string;
     readonly appDir: string;
@@ -42,18 +42,3 @@ export interface DevHandle {
 export declare function startDev(deps: DevDeps): Promise<DevHandle>;
 /** cwd 관례로 프로젝트 레이아웃을 해석한다(존재하는 것만 포함). */
 export declare function resolveDevLayout(cwd: string): DevLayout;
-export interface DevCommandOptions {
-    readonly cwd?: string;
-    readonly json?: boolean;
-    /** 프로세스 시그널 등록·해제(테스트에서 주입 가능). 기본 process. */
-    readonly signals?: {
-        on(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
-        off(sig: 'SIGINT' | 'SIGTERM', fn: () => void): void;
-    };
-}
-/**
- * `gaon dev` 진입점. cwd 관례로 레이아웃을 엮고 워치 루프를 띄운 뒤
- * SIGINT/SIGTERM 에 graceful stop. 프로세스는 워처가 살아 있는 동안
- * 유지된다(활성 핸들). 반환 프라미스는 종료 시 resolve.
- */
-export declare function runDevCommand(opts?: DevCommandOptions): Promise<void>;

package/dist/dev.js

@@ -1,19 +1,18 @@
 /**
- * @gaonjs/cli · `gaon dev` — .gaon 갱신 파이프라인 (M3)
+ * @gaonjs/cli · dev — .gaon 갱신 파이프라인 (M3 · v0.15 §6.3)
  *
  * 파일 워처(@gaonjs/data watchDir) → 재생성(tables.d.ts·routes.d.ts) →
- * 디스크 mtime 갱신 → 편집기 tsserver 자동 반영(§6.3, 열린 질문 3).
+ * 디스크 mtime 갱신 → 편집기 tsserver 자동 반영. 오케스트레이션은
+ * 주입(deps)으로 순수하게 유지하고(테스트 용이 · dbCli 패턴 동일),
+ * 상위(gaon dev 오케스트레이터 · commands/dev.ts)가 이 startDev 를 재사용한다.
  *
- * 오케스트레이션은 주입(deps)으로 순수하게 유지하고(테스트 용이·dbCli
- * 패턴과 동일), CLI 진입점이 cwd 관례로 실제 경로·재생성기를 엮는다.
- * 실제 웹 서버·Vite·Docker 인프라 기동은 후속 마일스톤이다 — M3 는
- * 타입 브리지 갱신 루프만 담당한다.
+ * M9-C 이전에는 이 파일이 gaon dev 진입점(runDevCommand)도 겸했으나,
+ * M9-C 에서 인프라·서버·타입 검사기를 통합하는 새 진입점이 commands/dev.ts
+ * 로 이동했다. 이 파일은 .gaon 재생성 코어(startDev · resolveDevLayout) 만
+ * 유지한다.
  */
 import { readdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { generateTablesDts, watchDir } from '@gaonjs/data';
-import { generateRoutesDts } from '@gaonjs/web';
-import { registerTsResolve } from './tsResolve.js';
 const isSchemaChange = (f) => f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts') && !f.includes('.gaon');
 const isRoutesChange = (f) => !f.includes('.gaon') &&
     f.endsWith('.ts') &&
@@ -94,60 +93,5 @@ export function resolveDevLayout(cwd) {
         apps: apps.sort((a, b) => a.name.localeCompare(b.name)),
     };
 }
-/** 사람이 읽는 이벤트 텍스트. */
-function humanEvent(e) {
-    switch (e.kind) {
-        case 'ready': {
-            const parts = [];
-            if (e.schema)
-                parts.push('schema→tables.d.ts');
-            for (const a of e.apps)
-                parts.push(`${a}→routes.d.ts`);
-            const what = parts.length ? parts.join(', ') : '(감시 대상 없음 — domain/schema·apps/* 확인)';
-            return `  gaon dev · 워치 시작 — ${what}\n  파일을 저장하면 .gaon 이 재생성되고 편집기가 자동 반영합니다. (Ctrl+C 종료)`;
-        }
-        case 'regen':
-            return e.target === 'tables'
-                ? '  ↻ tables.d.ts 재생성'
-                : `  ↻ ${e.app}/.gaon/routes.d.ts 재생성`;
-        case 'stopped':
-            return '  gaon dev · 종료';
-    }
-}
-/**
- * `gaon dev` 진입점. cwd 관례로 레이아웃을 엮고 워치 루프를 띄운 뒤
- * SIGINT/SIGTERM 에 graceful stop. 프로세스는 워처가 살아 있는 동안
- * 유지된다(활성 핸들). 반환 프라미스는 종료 시 resolve.
- */
-export async function runDevCommand(opts = {}) {
-    const cwd = opts.cwd ?? process.cwd();
-    const json = opts.json ?? false;
-    const signals = opts.signals ?? process;
-    registerTsResolve(); // 사용자 .ts 의 `.js` 상대 import 를 런타임에 해석
-    const layout = resolveDevLayout(cwd);
-    const emit = (e) => {
-        if (json)
-            process.stdout.write(JSON.stringify(e) + '\n');
-        else
-            process.stdout.write(humanEvent(e) + '\n');
-    };
-    const deps = {
-        layout,
-        regenerateTables: generateTablesDts,
-        regenerateRoutes: generateRoutesDts,
-        watch: watchDir,
-        log: emit,
-        onError: (err) => process.stderr.write(`  ✗ ${err.message}\n`),
-    };
-    const handle = await startDev(deps);
-    await new Promise((resolvePromise) => {
-        const stop = () => {
-            signals.off('SIGINT', stop);
-            signals.off('SIGTERM', stop);
-            handle.close();
-            resolvePromise();
-        };
-        signals.on('SIGINT', stop);
-        signals.on('SIGTERM', stop);
-    });
-}
+// runDevCommand · DevCommandOptions 는 M9-C 에서 commands/dev.ts 로 이동.
+// 이 파일은 .gaon 재생성 코어(startDev · resolveDevLayout)만 유지한다.

package/dist/doctor/connections.d.ts

@@ -0,0 +1,14 @@
+import type { RuleReport } from './types.js';
+interface KeyUse {
+    readonly key: string;
+    readonly file: string;
+    readonly line: number;
+    readonly kind: 'table' | 'getConnection';
+}
+/** gaon.config.ts 를 정적 AST 로 파싱해 db 커넥션 키 목록을 뽑는다. */
+export declare function extractConfigDbKeys(source: string): string[];
+/** 소스에서 table(name, defs, { db: 'X' }) 와 getConnection('X') 호출을 추출한다. */
+export declare function extractKeyUses(cwd: string, file: string, source: string): KeyUse[];
+/** 프로젝트 전체를 훑어 커넥션 키 정합을 검사한다. */
+export declare function checkConnections(cwd: string): Promise<RuleReport>;
+export {};

package/dist/doctor/connections.js

@@ -0,0 +1,168 @@
+// @gaonjs/cli · doctor · 커넥션 검사 (M9-E · v0.15 §4.5)
+//
+// 사용자 프로젝트의 커넥션 키 정합을 정적으로 검사한다:
+//   1) domain/schema/*.ts 의 table(..., { db: '<key>' }) 가 지목한 키가
+//      gaon.config.ts 의 db 에 등록돼 있는가?
+//   2) 사용자 코드의 getConnection('<key>') 호출이 등록된 키인가?
+// 미등록이면 error — 배포 후 first request 에서 죽는 대신 doctor 에서 잡는다.
+//
+// 방법: gaon.config.ts 를 정적 AST 로 훑어 `db: { <keys>... }` 를 뽑고,
+// 사용자 소스에서 위 두 호출 지점을 훑는다. 'main' 은 스키마 기본값이자
+// 정본 관례 — 등록 키가 하나도 없어도(=config 없음) 'main' 은 항상 허용.
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import ts from 'typescript';
+/** gaon.config.ts 를 정적 AST 로 파싱해 db 커넥션 키 목록을 뽑는다. */
+export function extractConfigDbKeys(source) {
+    const sf = ts.createSourceFile('gaon.config.ts', source, ts.ScriptTarget.ES2022, true);
+    const keys = [];
+    const visit = (node) => {
+        // defineConfig({ db: { main: {...}, legacy: {...} } })
+        if (ts.isCallExpression(node) && isDefineConfig(node.expression)) {
+            const arg = node.arguments[0];
+            if (arg && ts.isObjectLiteralExpression(arg)) {
+                for (const p of arg.properties) {
+                    if (ts.isPropertyAssignment(p) && propNameText(p.name) === 'db') {
+                        if (ts.isObjectLiteralExpression(p.initializer)) {
+                            for (const dp of p.initializer.properties) {
+                                if (ts.isPropertyAssignment(dp)) {
+                                    const n = propNameText(dp.name);
+                                    if (n)
+                                        keys.push(n);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return keys;
+}
+function isDefineConfig(e) {
+    if (ts.isIdentifier(e) && e.text === 'defineConfig')
+        return true;
+    if (ts.isPropertyAccessExpression(e) && e.name.text === 'defineConfig')
+        return true;
+    return false;
+}
+function propNameText(n) {
+    if (ts.isIdentifier(n))
+        return n.text;
+    if (ts.isStringLiteral(n))
+        return n.text;
+    return undefined;
+}
+/** 소스에서 table(name, defs, { db: 'X' }) 와 getConnection('X') 호출을 추출한다. */
+export function extractKeyUses(cwd, file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const uses = [];
+    const rel = relative(cwd, file);
+    const visit = (node) => {
+        if (ts.isCallExpression(node)) {
+            const e = node.expression;
+            // table(name, defs, { db: '...' })
+            if (isNamedCall(e, 'table') && node.arguments.length >= 3) {
+                const opts = node.arguments[2];
+                if (opts && ts.isObjectLiteralExpression(opts)) {
+                    for (const p of opts.properties) {
+                        if (ts.isPropertyAssignment(p) && propNameText(p.name) === 'db') {
+                            const v = p.initializer;
+                            if (ts.isStringLiteral(v) || ts.isNoSubstitutionTemplateLiteral(v)) {
+                                const { line } = sf.getLineAndCharacterOfPosition(v.getStart(sf));
+                                uses.push({ key: v.text, file: rel, line: line + 1, kind: 'table' });
+                            }
+                        }
+                    }
+                }
+            }
+            // getConnection('X')
+            if (isNamedCall(e, 'getConnection') && node.arguments.length >= 1) {
+                const a = node.arguments[0];
+                if (ts.isStringLiteral(a) || ts.isNoSubstitutionTemplateLiteral(a)) {
+                    const { line } = sf.getLineAndCharacterOfPosition(a.getStart(sf));
+                    uses.push({ key: a.text, file: rel, line: line + 1, kind: 'getConnection' });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return uses;
+}
+function isNamedCall(e, name) {
+    if (ts.isIdentifier(e) && e.text === name)
+        return true;
+    if (ts.isPropertyAccessExpression(e) && e.name.text === name)
+        return true;
+    return false;
+}
+/** 프로젝트 전체를 훑어 커넥션 키 정합을 검사한다. */
+export async function checkConnections(cwd) {
+    const issues = [];
+    const registered = new Set(['main']); // main 은 항상 허용(정본 §4.5)
+    const configPath = findConfigPath(cwd);
+    if (configPath) {
+        const src = await readFile(configPath, 'utf8');
+        for (const k of extractConfigDbKeys(src))
+            registered.add(k);
+    }
+    const files = [];
+    await collectTsFiles(join(cwd, 'domain'), files);
+    await collectTsFiles(join(cwd, 'apps'), files);
+    await collectTsFiles(join(cwd, 'shared'), files);
+    for (const f of files) {
+        const src = await readFile(f, 'utf8');
+        for (const u of extractKeyUses(cwd, f, src)) {
+            if (registered.has(u.key))
+                continue;
+            const site = u.kind === 'table'
+                ? `스키마 table(...) 의 { db: '${u.key}' }`
+                : `getConnection('${u.key}')`;
+            const configHint = configPath
+                ? `gaon.config.ts 의 db 에 '${u.key}' 커넥션을 등록하세요.`
+                : `gaon.config.ts 를 만들고 db.${u.key} 를 등록하세요.`;
+            issues.push({
+                rule: 'connections',
+                level: 'error',
+                file: u.file,
+                line: u.line,
+                message: `커넥션 미등록: ${u.file}:${u.line} · ${site} 는 gaon.config.ts 에 없는 키입니다.\n` +
+                    `등록된 키: ${[...registered].sort().join(', ')}\n` +
+                    `→ ${configHint}`,
+                detail: { key: u.key, kind: u.kind, registered: [...registered].sort() },
+            });
+        }
+    }
+    return { rule: 'connections', issues };
+}
+function findConfigPath(cwd) {
+    for (const nm of ['gaon.config.ts', 'gaon.config.mjs', 'gaon.config.js']) {
+        const p = join(cwd, nm);
+        if (existsSync(p))
+            return p;
+    }
+    return undefined;
+}
+async function collectTsFiles(root, out) {
+    let entries;
+    try {
+        entries = (await readdir(root, { withFileTypes: true }));
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        const name = e.name;
+        if (name === 'node_modules' || name === 'dist' || name === '.gaon')
+            continue;
+        const full = join(root, name);
+        if (e.isDirectory())
+            await collectTsFiles(full, out);
+        else if (e.isFile() && name.endsWith('.ts') && !name.endsWith('.d.ts') && !name.endsWith('.test.ts'))
+            out.push(full);
+    }
+}

package/dist/doctor/dependency-direction.d.ts

@@ -0,0 +1,11 @@
+import type { RuleReport } from './types.js';
+interface ImportUse {
+    readonly line: number;
+    readonly typeOnly: boolean;
+    readonly resolvedAbs: string;
+}
+/** 소스 하나에서 상대 import 를 추출한다(단위 테스트 진입점). */
+export declare function extractRelativeImports(file: string, source: string): ImportUse[];
+/** 프로젝트 전체 의존 방향 검사. */
+export declare function checkDependencyDirection(cwd: string): Promise<RuleReport>;
+export {};

package/dist/doctor/dependency-direction.js

@@ -0,0 +1,186 @@
+// @gaonjs/cli · doctor · 의존 방향 검사 (M9-E · CLAUDE.md 절대 규칙 5)
+//
+// 사용자 프로젝트의 4 규칙(§1-5):
+//   1. app → domain: 허용 (검사 X)
+//   2. domain → app: 금지 → error
+//   3. app → app: 금지 (앱 간 상호 참조 · 자기 앱은 허용) → error
+//   4. app → shared: 허용 / shared → app: 금지 → error /
+//      domain → shared: type-only import 만 허용 → error(값 import 시)
+//
+// 방법: 프로젝트 루트에서 domain/·apps/·shared/ 아래 .ts/.vue 를 훑고
+// import 선언의 module specifier 를 상대 경로로 해석 · 규칙 위반 여부 검사.
+// 절대 import(node:xxx · @gaonjs/xxx · npm 패키지)는 대상 아님.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative, resolve, dirname } from 'node:path';
+import ts from 'typescript';
+/** 소스 하나에서 상대 import 를 추출한다(단위 테스트 진입점). */
+export function extractRelativeImports(file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const uses = [];
+    const baseDir = dirname(file);
+    const record = (specifierText, node, typeOnly) => {
+        if (!isRelativeSpecifier(specifierText))
+            return;
+        const abs = resolve(baseDir, specifierText);
+        const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+        uses.push({ line: line + 1, typeOnly, resolvedAbs: abs });
+    };
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+            const typeOnly = !!node.importClause?.isTypeOnly;
+            record(node.moduleSpecifier.text, node, typeOnly);
+        }
+        if (ts.isExportDeclaration(node) &&
+            node.moduleSpecifier &&
+            ts.isStringLiteral(node.moduleSpecifier)) {
+            record(node.moduleSpecifier.text, node, node.isTypeOnly);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return uses;
+}
+function isRelativeSpecifier(s) {
+    return s.startsWith('./') || s.startsWith('../');
+}
+function zoneOf(cwd, absFile) {
+    const rel = relative(cwd, absFile).split(/[\\/]/).filter(Boolean);
+    if (rel[0] === 'domain')
+        return { kind: 'domain' };
+    if (rel[0] === 'shared')
+        return { kind: 'shared' };
+    if (rel[0] === 'apps' && rel[1])
+        return { kind: 'app', app: rel[1] };
+    return { kind: 'other' };
+}
+/**
+ * import 대상의 확장자를 넓혀 실 존재하는 파일을 하나 잡는다.
+ * TS ESM 관례: 소스 코드에서 `.js` 로 import 해도 실제 파일은 `.ts` 다
+ * (nodenext moduleResolution). 확장자를 벗기고 후보를 넓힌다.
+ */
+async function resolveTargetFile(abs) {
+    const base = stripJsLikeExt(abs);
+    const candidates = [
+        abs, // 원본 그대로(정확 매치)
+        base + '.ts',
+        base + '.tsx',
+        base + '.js',
+        base + '.vue',
+        join(base, 'index.ts'),
+        join(base, 'index.js'),
+    ];
+    for (const c of candidates) {
+        try {
+            const s = await stat(c);
+            if (s.isFile())
+                return c;
+        }
+        catch {
+            // 무시
+        }
+    }
+    return undefined;
+}
+function stripJsLikeExt(p) {
+    for (const ext of ['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx']) {
+        if (p.endsWith(ext))
+            return p.slice(0, -ext.length);
+    }
+    return p;
+}
+/** 프로젝트 전체 의존 방향 검사. */
+export async function checkDependencyDirection(cwd) {
+    const issues = [];
+    const files = [];
+    await collectSourceFiles(join(cwd, 'domain'), files);
+    await collectSourceFiles(join(cwd, 'apps'), files);
+    await collectSourceFiles(join(cwd, 'shared'), files);
+    for (const file of files) {
+        const from = zoneOf(cwd, file);
+        if (from.kind === 'other')
+            continue;
+        const source = await readFile(file, 'utf8');
+        const uses = extractRelativeImports(file, source);
+        for (const u of uses) {
+            const target = await resolveTargetFile(u.resolvedAbs);
+            if (!target)
+                continue;
+            const to = zoneOf(cwd, target);
+            const violation = classify(from, to, u.typeOnly);
+            if (!violation)
+                continue;
+            const relFile = relative(cwd, file);
+            const relTarget = relative(cwd, target);
+            issues.push({
+                rule: 'dependency-direction',
+                level: 'error',
+                file: relFile,
+                line: u.line,
+                message: `의존 방향 위반: ${relFile}:${u.line} · ${violation.reason}\n` +
+                    `  대상: ${relTarget}\n` +
+                    `→ ${violation.fix}`,
+                detail: {
+                    from: from.kind === 'app' ? `app:${from.app}` : from.kind,
+                    to: to.kind === 'app' ? `app:${to.app}` : to.kind,
+                    typeOnly: u.typeOnly,
+                    target: relTarget,
+                },
+            });
+        }
+    }
+    return { rule: 'dependency-direction', issues };
+}
+function classify(from, to, typeOnly) {
+    // domain → app : 금지
+    if (from.kind === 'domain' && to.kind === 'app') {
+        return {
+            reason: 'domain 은 apps/ 를 import 할 수 없습니다 (역방향).',
+            fix: 'domain 은 앱을 몰라야 합니다 · 공통 로직은 shared/ 로 옮기고 앱이 참조하세요.',
+        };
+    }
+    // domain → shared : type-only 만 허용
+    if (from.kind === 'domain' && to.kind === 'shared' && !typeOnly) {
+        return {
+            reason: 'domain → shared 는 type-only import 만 허용됩니다 (CLAUDE.md §5).',
+            fix: `'import type { ... } from ...' 형태로 바꾸거나, 값이 필요하면 로직을 domain/ 안으로 옮기세요.`,
+        };
+    }
+    // app → 다른 app : 금지
+    if (from.kind === 'app' && to.kind === 'app' && from.app !== to.app) {
+        return {
+            reason: `apps/${from.app} 이 apps/${to.app} 를 import 합니다 (앱 간 참조 금지).`,
+            fix: '공통 코드는 shared/ 또는 domain/ 으로 옮기고 양쪽 앱이 참조하세요.',
+        };
+    }
+    // shared → app : 금지
+    if (from.kind === 'shared' && to.kind === 'app') {
+        return {
+            reason: 'shared 는 apps/ 를 import 할 수 없습니다 (역방향).',
+            fix: 'shared 는 앱을 몰라야 합니다 · 필요하면 shared 에 인터페이스를 두고 앱에서 구현을 주입하세요.',
+        };
+    }
+    return undefined;
+}
+async function collectSourceFiles(root, out) {
+    let entries;
+    try {
+        entries = (await readdir(root, { withFileTypes: true }));
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        const name = e.name;
+        if (name === 'node_modules' || name === 'dist' || name === '.gaon')
+            continue;
+        const full = join(root, name);
+        if (e.isDirectory()) {
+            await collectSourceFiles(full, out);
+        }
+        else if (e.isFile()) {
+            if (name.endsWith('.ts') && !name.endsWith('.d.ts') && !name.endsWith('.test.ts'))
+                out.push(full);
+            // .vue 는 SFC — 이번 M9-E 는 .ts 만 (Vue 컴파일러 도입은 후속).
+        }
+    }
+}

package/dist/doctor/migration-diff.d.ts

@@ -0,0 +1,11 @@
+import type { RuleReport } from './types.js';
+interface SchemaInfo {
+    readonly files: readonly string[];
+    readonly tables: readonly string[];
+    readonly latestMtimeMs: number;
+}
+/** domain/schema 를 스캔해 table 선언 수·최신 mtime 을 수집한다. */
+export declare function scanSchema(cwd: string): Promise<SchemaInfo>;
+/** 프로젝트에서 마이그 diff 최소 감지를 돌린다. */
+export declare function checkMigrationDiff(cwd: string): Promise<RuleReport>;
+export {};

package/dist/doctor/migration-diff.js

@@ -0,0 +1,109 @@
+// @gaonjs/cli · doctor · 마이그 diff 최소 감지 (M9-E · 상세 로직은 M9-D)
+//
+// 배포 전 게이트: 스키마가 편집됐는데 `gaon check`(=`.gaon/tables.d.ts`
+// 재생성)가 뒤처져 있으면 정본과 타입 브리지가 어긋난 상태다. 실제 DB
+// 대비 diff 는 커넥션이 필요하므로 M9-D `gaon db diff` 가 담당한다 —
+// 여기서는 스태틱 게이트(스키마 vs 타입 브리지 신선도)만 잡는다.
+//
+// 검사:
+//  1) domain/schema/*.ts 를 훑어 table(...) 선언을 센다.
+//  2) 스키마 파일의 최신 mtime 을 .gaon/tables.d.ts 의 mtime 과 비교한다.
+//     - .gaon/tables.d.ts 없음 · 스키마가 더 최신  →  warning
+//  3) 그 외에는 정보성 안내(passed): `gaon db diff` 로 DB 대비 확인.
+import { existsSync } from 'node:fs';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import ts from 'typescript';
+/** domain/schema 를 스캔해 table 선언 수·최신 mtime 을 수집한다. */
+export async function scanSchema(cwd) {
+    const schemaDir = join(cwd, 'domain', 'schema');
+    const files = [];
+    await collectTsFiles(schemaDir, files);
+    const tables = [];
+    let latest = 0;
+    for (const f of files) {
+        const src = await readFile(f, 'utf8');
+        tables.push(...extractTableNames(src));
+        const st = await stat(f);
+        if (st.mtimeMs > latest)
+            latest = st.mtimeMs;
+    }
+    return { files, tables, latestMtimeMs: latest };
+}
+function extractTableNames(source) {
+    const sf = ts.createSourceFile('schema.ts', source, ts.ScriptTarget.ES2022, true);
+    const names = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === 'table' &&
+            node.arguments.length >= 1) {
+            const a = node.arguments[0];
+            if (ts.isStringLiteral(a) || ts.isNoSubstitutionTemplateLiteral(a))
+                names.push(a.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return names;
+}
+/** 프로젝트에서 마이그 diff 최소 감지를 돌린다. */
+export async function checkMigrationDiff(cwd) {
+    const info = await scanSchema(cwd);
+    if (info.tables.length === 0)
+        return { rule: 'migration-diff', issues: [] };
+    const tablesDts = join(cwd, '.gaon', 'tables.d.ts');
+    const dtsExists = existsSync(tablesDts);
+    let dtsMtimeMs = 0;
+    if (dtsExists) {
+        const st = await stat(tablesDts);
+        dtsMtimeMs = st.mtimeMs;
+    }
+    const issues = [];
+    if (!dtsExists) {
+        issues.push({
+            rule: 'migration-diff',
+            level: 'warning',
+            file: relative(cwd, join(cwd, 'domain', 'schema')),
+            message: `타입 브리지 미생성: .gaon/tables.d.ts 가 없습니다 · 스키마 ${info.tables.length}개 테이블 감지.\n` +
+                `→ 'gaon check' 를 실행해 .gaon 을 재생성하고 'gaon db diff' 로 DB 대비를 확인하세요 (상세 diff 는 M9-D).`,
+            detail: { tables: [...info.tables], dtsExists },
+        });
+        return { rule: 'migration-diff', issues };
+    }
+    if (info.latestMtimeMs > dtsMtimeMs + 1) {
+        // 1ms 여유 — 파일시스템 mtime 해상도 대응
+        issues.push({
+            rule: 'migration-diff',
+            level: 'warning',
+            file: relative(cwd, tablesDts),
+            message: `타입 브리지 뒤처짐: 스키마가 .gaon/tables.d.ts 보다 최신입니다 (${info.tables.length}개 테이블).\n` +
+                `→ 'gaon check' 로 재생성한 뒤 'gaon db diff' 로 DB 대비 변경 여부를 확인하세요 (상세 diff 는 M9-D).`,
+            detail: {
+                tables: [...info.tables],
+                schemaLatestMs: info.latestMtimeMs,
+                dtsMtimeMs,
+            },
+        });
+    }
+    return { rule: 'migration-diff', issues };
+}
+async function collectTsFiles(root, out) {
+    let entries;
+    try {
+        entries = (await readdir(root, { withFileTypes: true }));
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        const name = e.name;
+        if (name === 'node_modules' || name === 'dist' || name === '.gaon')
+            continue;
+        const full = join(root, name);
+        if (e.isDirectory())
+            await collectTsFiles(full, out);
+        else if (e.isFile() && name.endsWith('.ts') && !name.endsWith('.d.ts') && !name.endsWith('.test.ts'))
+            out.push(full);
+    }
+}

package/dist/doctor/n-plus-one.d.ts

@@ -0,0 +1,5 @@
+import type { DoctorCheck, RuleReport } from './types.js';
+/** 소스 하나를 검사해 N+1 위반 목록을 낸다(단위 테스트 진입점). */
+export declare function inspectControllerForNPlusOne(file: string, source: string, cwd: string): DoctorCheck[];
+/** apps/ 를 스캔해 N+1 검사를 돌린다. */
+export declare function checkNPlusOne(cwd: string): Promise<RuleReport>;