@gaonjs/cli 0.4.0 → 0.10.0

package/dist/dev/vite.js

@@ -0,0 +1,126 @@
+/**
+ * @gaonjs/cli · dev/vite — Vite dev server 프로그램적 기동 (M3-runtime)
+ *
+ * 정본 정합:
+ *   · §6.4 Vue 어댑터 인터페이스 — `vite: () => [vuePlugin()]` 은 서버 배선
+ *     시 프론트엔드 어댑터가 제공한다. 이 파일은 그 배선을 CLI 측에서
+ *     쉽게 부를 수 있는 최소 래퍼일 뿐이다.
+ *   · The One Way (§CLAUDE.md 6) — Vite 를 middlewareMode 로 띄운다. Fastify
+ *     한 포트로 API 와 프론트가 함께 서빙된다 — 두 포트·프록시 규칙 X.
+ *
+ * 이 파일은 `dev.ts` 에 배선되지 않는다(사용자 지침) — M1 세션이 통합
+ * 커밋에서 배선한다. 여기서는 함수만 노출한다.
+ *
+ * 참고: vite 는 이 파일을 실행하는 환경에 이미 설치돼 있어야 한다
+ * (packages/cli/package.json 에 dep 등록). vite 가 없으면 명확한 에러를
+ * 던져 사용자에게 설치 안내를 준다(§7.5.3 에러=수리 안내서).
+ */
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+/**
+ * Vite dev server 를 middleware 모드로 띄운다. Fastify 에 붙여 하나의
+ * 포트로 API + 프론트를 함께 서빙한다(The One Way).
+ *
+ * 파일이 존재하지 않는 경우(초기 프로젝트에 apps/web/index.html 이 없는
+ * 순간)에는 명확한 에러를 던진다 — dev.ts 가 이 예외를 잡아 사용자에게
+ * "→ apps/<앱>/index.html 을 만들거나 gaon new 로 새 프로젝트를 만드세요"
+ * 라고 알린다.
+ */
+export async function createGaonViteServer(opts) {
+    if (opts.enabled === false)
+        return undefined;
+    const cwd = resolve(opts.cwd);
+    const appRoot = resolve(cwd, opts.appRoot ?? 'apps/web');
+    const indexHtml = join(appRoot, 'index.html');
+    if (!existsSync(indexHtml)) {
+        throw new Error(`[gaon dev · vite] 프론트 진입 HTML 이 없습니다: ${indexHtml}\n` +
+            `→ 다음 중 하나를 하세요:\n` +
+            `   · gaon new <name> 으로 새 프로젝트를 만들거나\n` +
+            `   · 위 경로에 index.html 을 만들고 <script type="module" src="/main.ts"></script> 를 넣거나\n` +
+            `   · gaon dev 를 --no-vite 로 실행해 프론트 핫리로드를 비활성화하세요.`);
+    }
+    const vite = await loadVite();
+    const server = await vite.createServer({
+        root: appRoot,
+        configFile: findViteConfig(cwd, appRoot),
+        server: {
+            middlewareMode: true,
+            // hmr 는 middleware 모드에서도 Vite 가 자체 ws 서버로 처리한다.
+            // Fastify 는 이 ws 를 별도 upgrade 핸들러로 얹으면 되며(§ dev.ts 배선),
+            // 이 파일은 서버 옵션만 정한다.
+            hmr: true,
+        },
+        appType: 'custom',
+        // Vite 는 stderr 에 색상 있는 로그를 낸다 — 통합 콘솔에서 그대로 흘린다.
+        logLevel: 'info',
+        customLogger: opts.onLog
+            ? makeConnectLogger(opts.onLog)
+            : undefined,
+    });
+    return {
+        middlewares: server.middlewares,
+        async transformIndexHtml(url, html) {
+            return server.transformIndexHtml(url, html);
+        },
+        async ssrLoadModule(id) {
+            return (await server.ssrLoadModule(id));
+        },
+        async close() {
+            await server.close();
+        },
+        root: appRoot,
+    };
+}
+/** vite.config.ts 를 프로젝트 루트 · 앱 루트 순으로 찾는다(있으면 반환). */
+function findViteConfig(cwd, appRoot) {
+    for (const dir of [appRoot, cwd]) {
+        for (const name of ['vite.config.ts', 'vite.config.js', 'vite.config.mts', 'vite.config.mjs']) {
+            const p = join(dir, name);
+            if (existsSync(p))
+                return p;
+        }
+    }
+    return undefined;
+}
+/**
+ * vite 를 lazy 하게 로드한다. 없으면 명확한 에러 — 사용자에게 설치 명령을
+ * 알려주고, dev.ts 가 다시 던져 통합 콘솔로 표시한다.
+ */
+async function loadVite() {
+    try {
+        return await import('vite');
+    }
+    catch (err) {
+        throw new Error(`[gaon dev · vite] vite 모듈을 찾을 수 없습니다.\n` +
+            `→ 프로젝트 루트에서 다음 명령으로 설치하세요: pnpm add -D vite @vitejs/plugin-vue\n` +
+            `  (또는 gaon dev --no-vite 로 프론트 핫리로드를 비활성화)\n` +
+            `원인: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function makeConnectLogger(onLog) {
+    let hasWarned = false;
+    const errorsSeen = new WeakSet();
+    return {
+        info: (msg) => onLog(stripAnsi(msg), 'info'),
+        warn: (msg) => {
+            hasWarned = true;
+            onLog(stripAnsi(msg), 'warn');
+        },
+        warnOnce: (msg) => {
+            hasWarned = true;
+            onLog(stripAnsi(msg), 'warn');
+        },
+        error: (msg) => onLog(stripAnsi(msg), 'error'),
+        // clearScreen 은 통합 콘솔에서는 무시한다(다른 자식 로그가 지워지면 안 됨).
+        clearScreen: () => { },
+        hasErrorLogged: (err) => errorsSeen.has(err),
+        get hasWarned() {
+            return hasWarned;
+        },
+    };
+}
+// vite 로거는 원문 ANSI 를 그대로 낸다 — 통합 콘솔이 자체 색상을 붙이므로 벗긴다.
+function stripAnsi(s) {
+    // ESC [ ... m 시퀀스 제거. 라이브러리 미의존 정책상 정규식으로 처리.
+    return s.replace(/\x1b\[[0-9;]*m/g, '');
+}

package/dist/dev.d.ts

@@ -40,5 +40,23 @@ export interface DevHandle {
  * .gaon 파일을 재생성한다. 반환 핸들의 close() 로 멈춘다.
  */
 export declare function startDev(deps: DevDeps): Promise<DevHandle>;
+/** 워처 없이 .gaon 타입 브리지를 1회 재생성할 때 필요한 생성기 주입. */
+export interface RegenDeps {
+    regenerateTables(schemaDir: string, out: string): Promise<unknown>;
+    regenerateRoutes(appDir: string, out: string): Promise<unknown>;
+}
+export interface RegenResult {
+    /** tables.d.ts 를 재생성했는가(domain/schema 존재 시에만). */
+    readonly tables: boolean;
+    /** routes.d.ts 를 재생성한 앱 이름. */
+    readonly apps: readonly string[];
+}
+/**
+ * 워처 없이 .gaon 타입 브리지를 1회 전체 재생성한다. `gaon check` 처럼
+ * 개발 서버를 띄우지 않는 진입점(CI · AI 에이전트)이 검사 직전에 최신
+ * 타입 체인을 확보하기 위해 쓴다(§13.4-5). startDev 의 초기 재생성 단계와
+ * 동일한 순서(tables → 앱별 routes)를 공유한다.
+ */
+export declare function regenerateGaonOnce(layout: DevLayout, deps: RegenDeps): Promise<RegenResult>;
 /** cwd 관례로 프로젝트 레이아웃을 해석한다(존재하는 것만 포함). */
 export declare function resolveDevLayout(cwd: string): DevLayout;

package/dist/dev.js

@@ -67,6 +67,21 @@ export async function startDev(deps) {
         },
     };
 }
+/**
+ * 워처 없이 .gaon 타입 브리지를 1회 전체 재생성한다. `gaon check` 처럼
+ * 개발 서버를 띄우지 않는 진입점(CI · AI 에이전트)이 검사 직전에 최신
+ * 타입 체인을 확보하기 위해 쓴다(§13.4-5). startDev 의 초기 재생성 단계와
+ * 동일한 순서(tables → 앱별 routes)를 공유한다.
+ */
+export async function regenerateGaonOnce(layout, deps) {
+    if (layout.schemaDir) {
+        await deps.regenerateTables(layout.schemaDir, layout.tablesOut);
+    }
+    for (const app of layout.apps) {
+        await deps.regenerateRoutes(app.appDir, app.routesOut);
+    }
+    return { tables: !!layout.schemaDir, apps: layout.apps.map((a) => a.name) };
+}
 /** cwd 관례로 프로젝트 레이아웃을 해석한다(존재하는 것만 포함). */
 export function resolveDevLayout(cwd) {
     const root = resolve(cwd);

package/dist/doctor/agents-doc-index.d.ts

@@ -0,0 +1,4 @@
+import type { RuleReport } from './types.js';
+/** AGENTS.md 본문에서 `agents/<이름>.md` 참조를 전부 뽑는다(중복 제거·정렬). */
+export declare function extractAgentDocRefs(source: string): string[];
+export declare function checkAgentsDocIndex(cwd: string): Promise<RuleReport>;

package/dist/doctor/agents-doc-index.js

@@ -0,0 +1,80 @@
+// @gaonjs/cli · doctor · AGENTS 2층 문서 색인 정합 (결정 40 · 2026-07-25)
+//
+// 관례 문서는 2층 구조다: 루트 AGENTS.md(코어)의 색인이 agents/*.md
+// (카테고리 정본)를 가리키고, 에이전트는 색인 지시대로 작업 전에 카테고리
+// 파일을 읽는다. 색인과 실 파일이 어긋나면 두 방향 모두 관례가 깨진다:
+//   · 색인이 가리키는 파일이 없다 → 에이전트가 읽을 정본이 없다 (error)
+//   · 파일은 있는데 색인에 없다 → 아무도 읽지 않는 죽은 문서 (warning)
+//
+// 2층 구조를 쓰지 않는 프로젝트(agents/ 없음 · 색인 참조 없음)는 검사할
+// 것이 없으므로 통과 — 기존 프로젝트에 소급 강제하지 않는다.
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+/** AGENTS.md 본문에서 `agents/<이름>.md` 참조를 전부 뽑는다(중복 제거·정렬). */
+export function extractAgentDocRefs(source) {
+    const out = new Set();
+    for (const m of source.matchAll(/\bagents\/([A-Za-z0-9_-]+\.md)\b/g)) {
+        out.add(m[1]);
+    }
+    return [...out].sort();
+}
+export async function checkAgentsDocIndex(cwd) {
+    const issues = [];
+    let core;
+    try {
+        core = await readFile(join(cwd, 'AGENTS.md'), 'utf8');
+    }
+    catch {
+        core = undefined;
+    }
+    let files = [];
+    try {
+        files = (await readdir(join(cwd, 'agents'))).filter((f) => f.endsWith('.md')).sort();
+    }
+    catch {
+        files = [];
+    }
+    const refs = core ? extractAgentDocRefs(core) : [];
+    // 2층 구조 미사용 프로젝트 — 검사 대상 없음.
+    if (refs.length === 0 && files.length === 0) {
+        return { rule: 'agents-doc-index', issues };
+    }
+    if (!core && files.length > 0) {
+        issues.push({
+            rule: 'agents-doc-index',
+            level: 'error',
+            file: 'AGENTS.md',
+            message: `agents/*.md 카테고리 문서(${files.length}개)가 있는데 루트 AGENTS.md 가 없습니다.\n` +
+                `→ 루트에 AGENTS.md(코어)를 두고 색인에 agents/${files[0]} 등 카테고리 파일을 등재하세요 (결정 40).`,
+            detail: { files },
+        });
+        return { rule: 'agents-doc-index', issues };
+    }
+    const fileSet = new Set(files);
+    for (const ref of refs) {
+        if (!fileSet.has(ref)) {
+            issues.push({
+                rule: 'agents-doc-index',
+                level: 'error',
+                file: 'AGENTS.md',
+                message: `AGENTS.md 색인이 agents/${ref} 를 가리키는데 실 파일이 없습니다.\n` +
+                    `→ agents/${ref} 를 만들거나, AGENTS.md 색인에서 해당 행을 지우세요.`,
+                detail: { ref },
+            });
+        }
+    }
+    const refSet = new Set(refs);
+    for (const f of files) {
+        if (!refSet.has(f)) {
+            issues.push({
+                rule: 'agents-doc-index',
+                level: 'warning',
+                file: `agents/${f}`,
+                message: `agents/${f} 가 루트 AGENTS.md 색인에 없습니다 — 색인에 없는 문서는 에이전트가 읽지 않습니다.\n` +
+                    `→ AGENTS.md §색인 표에 'agents/${f}' 행을 추가하거나, 불필요하면 파일을 지우세요.`,
+                detail: { file: f },
+            });
+        }
+    }
+    return { rule: 'agents-doc-index', issues };
+}

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

@@ -0,0 +1,9 @@
+import type { DoctorCheck } from '../types.js';
+import type { FixerPlan } from './types.js';
+/** 한 파일 안에서 지정 라인의 import 를 type-only 로 바꾼다(순수 계산). */
+export declare function fixDomainToSharedTypeOnly(file: string, source: string, targetLines: readonly number[]): {
+    after: string;
+    changedLines: number[];
+};
+/** DoctorCheck 목록에서 domain → shared(값) 위반만 골라 FixerPlan 을 낸다. */
+export declare function fixDependencyDirection(issues: readonly DoctorCheck[], cwd: string): Promise<readonly FixerPlan[]>;

package/dist/doctor/fixers/dependency-direction.js

@@ -0,0 +1,98 @@
+// @gaonjs/cli · doctor · fixer · 의존 방향 (M9-fix · CLAUDE.md §5 · 규칙 4)
+//
+// 대상 위반: domain 소스가 shared/ 를 값(runtime) 으로 import 하는 경우.
+// 정본은 이 방향을 type-only 로만 허용한다. 자동 정정은 안전하다 — 원본
+// `import { X } from '../shared/x.js'` 를 `import type { X } from '../shared/x.js'`
+// 로 바꾸기만 한다. 값이 실제로 필요했다면 컴파일이 즉시 실패해 사용자가
+// 발견한다(우회 X · 근본 원인 안내).
+//
+// 다른 방향의 위반(domain → app · app → app · shared → app)은 기계적
+// 정정이 불가능하다(파일을 어디로 옮길지 사람 판단). 이 fixer 는 그런
+// 케이스를 무시하고 상위가 "수동 수정 필요" 로 보고한다.
+//
+// 방법: 각 파일을 TS AST 로 파싱해 문제 라인의 ImportDeclaration 을 찾고,
+// `import` 다음에 `type` 키워드가 없으면 삽입한다. 문자열 스캔이 아닌
+// AST 기반 편집이라 주석·공백·복합 import(`import x, { a, b }`) 등 엣지
+// 케이스에 안전하다.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import ts from 'typescript';
+/** 한 파일 안에서 지정 라인의 import 를 type-only 로 바꾼다(순수 계산). */
+export function fixDomainToSharedTypeOnly(file, source, targetLines) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    // 라인 → 편집 대상 ImportDeclaration 노드 매핑.
+    const targets = new Set(targetLines);
+    const edits = [];
+    const changed = [];
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) &&
+            ts.isStringLiteral(node.moduleSpecifier) &&
+            node.importClause &&
+            !node.importClause.isTypeOnly) {
+            const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+            const oneBased = line + 1;
+            if (!targets.has(oneBased)) {
+                ts.forEachChild(node, visit);
+                return;
+            }
+            // 편집: `import ` 바로 뒤에 `type ` 을 삽입한다. 노드의 시작 위치
+            // (leading comment 뒤) 를 기준으로 첫 `import` 토큰 다음 공백까지를
+            // 잡아 재작성한다.
+            const nodeStart = node.getStart(sf);
+            const original = source.slice(nodeStart, node.end);
+            // `import` 로 시작하지 않으면(예상 밖) 스킵.
+            if (!original.startsWith('import')) {
+                ts.forEachChild(node, visit);
+                return;
+            }
+            const rewritten = 'import type' + original.slice('import'.length);
+            edits.push({ start: nodeStart, end: node.end, replacement: rewritten });
+            changed.push(oneBased);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    if (edits.length === 0) {
+        return { after: source, changedLines: [] };
+    }
+    // 뒤에서부터 치환 — 앞 위치를 밀지 않도록.
+    edits.sort((a, b) => b.start - a.start);
+    let out = source;
+    for (const e of edits) {
+        out = out.slice(0, e.start) + e.replacement + out.slice(e.end);
+    }
+    return { after: out, changedLines: changed.sort((a, b) => a - b) };
+}
+/** DoctorCheck 목록에서 domain → shared(값) 위반만 골라 FixerPlan 을 낸다. */
+export async function fixDependencyDirection(issues, cwd) {
+    // 파일별로 라인 모음.
+    const byFile = new Map();
+    for (const issue of issues) {
+        const from = issue.detail?.from ?? '';
+        const to = issue.detail?.to ?? '';
+        const typeOnly = issue.detail?.typeOnly === true;
+        if (from !== 'domain' || to !== 'shared' || typeOnly)
+            continue;
+        if (!issue.file || !issue.line)
+            continue;
+        const arr = byFile.get(issue.file) ?? [];
+        arr.push(issue.line);
+        byFile.set(issue.file, arr);
+    }
+    const plans = [];
+    for (const [rel, lines] of byFile) {
+        const abs = join(cwd, rel);
+        const before = await readFile(abs, 'utf8');
+        const { after, changedLines } = fixDomainToSharedTypeOnly(abs, before, lines);
+        if (changedLines.length === 0 || after === before)
+            continue;
+        plans.push({
+            file: rel,
+            before,
+            after,
+            summary: `domain → shared · line ${changedLines.join(', ')}: 'import ...' → 'import type ...' (${changedLines.length}건)\n` +
+                `  근거: CLAUDE.md §5 규칙 4 · domain 은 shared 를 type-only 로만 참조합니다.`,
+        });
+    }
+    return plans;
+}

package/dist/doctor/fixers/index.d.ts

@@ -0,0 +1,15 @@
+import type { DoctorRule } from '../types.js';
+import type { Fixer, FixerCapability } from './types.js';
+export type { Fixer, FixerCapability, FixerPlan, RewriteFixerPlan, RenameFixerPlan, RefEdit, } from './types.js';
+export { fixDependencyDirection, fixDomainToSharedTypeOnly, } from './dependency-direction.js';
+export { fixSchemaFilename, rewriteSchemaImport } from './schema-filename.js';
+/**
+ * 규칙별 fixer 표. 없는 규칙(값 undefined)은 "수동 수정 필요" 로 리포트된다.
+ * 새 fixer 를 만들면 이 표에만 추가하면 된다(runDoctorFix 는 표를 순회).
+ */
+export declare const FIXERS: Partial<Record<DoctorRule, Fixer>>;
+/**
+ * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
+ * 수동 · 이유는 무엇인지 표시하는 데 쓴다(진단 = 수리 안내서 · §7.5.3).
+ */
+export declare const FIXER_CAPABILITIES: readonly FixerCapability[];

package/dist/doctor/fixers/index.js

@@ -0,0 +1,66 @@
+// @gaonjs/cli · doctor · fixer 레지스트리 (M9-fix · v0.16 §7.5.3)
+//
+// 규칙별 fixer 를 여기서 하나로 묶어 상위(runDoctorCommand)에 넘긴다.
+// 규칙 하나 = fixer 하나(또는 없음). 없으면 `hasFixer: false` 로 노출되고,
+// --fix 리포트가 "수동 수정 필요" 라벨을 붙인다.
+//
+// 각 fixer 는 순수 함수(입력 → 출력)로 유지한다. 파일 쓰기·백업은 상위
+// runDoctorFix 가 관장 — fixer 는 테스트가 fs 없이 계산만으로 검증된다.
+import { fixDependencyDirection } from './dependency-direction.js';
+import { fixSchemaFilename } from './schema-filename.js';
+export { fixDependencyDirection, fixDomainToSharedTypeOnly, } from './dependency-direction.js';
+export { fixSchemaFilename, rewriteSchemaImport } from './schema-filename.js';
+/**
+ * 규칙별 fixer 표. 없는 규칙(값 undefined)은 "수동 수정 필요" 로 리포트된다.
+ * 새 fixer 를 만들면 이 표에만 추가하면 된다(runDoctorFix 는 표를 순회).
+ */
+export const FIXERS = {
+    'dependency-direction': fixDependencyDirection,
+    'schema-filename': fixSchemaFilename,
+};
+/**
+ * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
+ * 수동 · 이유는 무엇인지 표시하는 데 쓴다(진단 = 수리 안내서 · §7.5.3).
+ */
+export const FIXER_CAPABILITIES = [
+    {
+        rule: 'response-mixing',
+        hasFixer: false,
+        note: '수동 · 액션을 두 개로 분리하거나 JSON 분기를 예외/redirect 로 재편(설계 결정).',
+    },
+    {
+        rule: 'n-plus-one',
+        hasFixer: false,
+        note: '수동 · include() 도입 · Query.eager() 재작성(성능 튜닝은 코드 리팩터링).',
+    },
+    {
+        rule: 'dependency-direction',
+        hasFixer: true,
+        note: 'domain → shared 값 import 를 type-only 로 자동 정정(다른 방향 위반은 파일 이동이 필요해 수동).',
+    },
+    {
+        rule: 'connections',
+        hasFixer: false,
+        note: '수동 · cross-DB belongsTo 는 도메인 재설계가 필요합니다.',
+    },
+    {
+        rule: 'migration-diff',
+        hasFixer: false,
+        note: '수동 · `gaon db diff` → 리뷰 → `gaon db migrate` (SQL 은 사람이 확인).',
+    },
+    {
+        rule: 'shared-composable-purity',
+        hasFixer: false,
+        note: '수동 · 컴포저블에 든 앱 종속 로직을 앱 쪽으로 옮겨야 합니다(E-5 §2.2).',
+    },
+    {
+        rule: 'no-auto-import',
+        hasFixer: false,
+        note: '수동 · 자동 import 플러그인을 제거하고 명시 import 로 전환(빌드 구성 검토).',
+    },
+    {
+        rule: 'schema-filename',
+        hasFixer: true,
+        note: '스키마 파일을 camelCase(테이블명) 로 자동 rename + 이 스키마를 import 하는 곳의 경로를 함께 갱신(결정 38).',
+    },
+];

package/dist/doctor/fixers/schema-filename.d.ts

@@ -0,0 +1,14 @@
+import type { DoctorCheck } from '../types.js';
+import type { RenameFixerPlan } from './types.js';
+/**
+ * 한 importer 소스에서 `.../schema/<oldStem>(.js)?` 참조를 `<newStem>` 로 바꾼다.
+ * `schema/` 접두 + 따옴표/`.js` 경계로 못박아 오탐(우연한 부분 문자열)을 막는다.
+ * 바뀐 게 없으면 undefined 를 돌려준다(그 importer 는 편집 대상 아님).
+ */
+export declare function rewriteSchemaImport(source: string, oldStem: string, newStem: string): string | undefined;
+/**
+ * schema-filename 위반 목록을 받아 RenameFixerPlan 을 낸다. 위반마다:
+ *  1) 스키마 파일을 camelCase 이름으로 이동(내용 불변).
+ *  2) 프로젝트 전체(.ts)에서 그 스키마를 import 하는 곳의 경로를 갱신.
+ */
+export declare function fixSchemaFilename(issues: readonly DoctorCheck[], cwd: string): Promise<readonly RenameFixerPlan[]>;

package/dist/doctor/fixers/schema-filename.js

@@ -0,0 +1,104 @@
+// @gaonjs/cli · doctor · fixer · 스키마 파일명 (M9-fix · 결정 38 · §1.1)
+//
+// 대상 위반: 스키마 파일명이 camelCase(테이블명) 관례와 어긋남(스네이크·케밥·
+// Pascal). 예: 조인 테이블 `posts_tags` 의 스키마가 `domain/schema/posts_tags.ts`
+// 로 저장돼 있으면 → `domain/schema/postsTags.ts` 로 이름을 바꾸고, 이 스키마를
+// import 하는 곳(모델 등)의 경로도 함께 고친다.
+//
+// 이 fixer 는 내용 재작성이 아니라 **파일 이동 + 참조 갱신**이라 RenameFixerPlan
+// 을 낸다. 파일 I/O(이동·백업·쓰기)는 상위 runDoctorFix 가 관장 — 이 함수는 순수
+// 계산(어떤 파일을 어디로 옮기고, 어떤 importer 의 어느 문자열을 어떻게 바꿀지)만
+// 한다(테스트가 fs 없이 검증 가능 · dependency-direction fixer 와 같은 원칙).
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+/** 정규식 리터럴에서 특수문자를 이스케이프한다. */
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * 한 importer 소스에서 `.../schema/<oldStem>(.js)?` 참조를 `<newStem>` 로 바꾼다.
+ * `schema/` 접두 + 따옴표/`.js` 경계로 못박아 오탐(우연한 부분 문자열)을 막는다.
+ * 바뀐 게 없으면 undefined 를 돌려준다(그 importer 는 편집 대상 아님).
+ */
+export function rewriteSchemaImport(source, oldStem, newStem) {
+    // import ... from '.../schema/posts_tags.js'  ·  import('.../schema/posts_tags')
+    const re = new RegExp(`(schema/)${escapeRe(oldStem)}(\\.js)?(['"\\\`])`, 'g');
+    const after = source.replace(re, `$1${newStem}$2$3`);
+    return after === source ? undefined : after;
+}
+/**
+ * schema-filename 위반 목록을 받아 RenameFixerPlan 을 낸다. 위반마다:
+ *  1) 스키마 파일을 camelCase 이름으로 이동(내용 불변).
+ *  2) 프로젝트 전체(.ts)에서 그 스키마를 import 하는 곳의 경로를 갱신.
+ */
+export async function fixSchemaFilename(issues, cwd) {
+    const plans = [];
+    // importer 후보를 한 번만 수집(위반이 여러 개여도 재사용).
+    let sources;
+    for (const issue of issues) {
+        const detail = issue.detail;
+        if (!issue.file || !detail?.actual || !detail?.expected)
+            continue;
+        const oldStem = detail.actual.replace(/\.ts$/, '');
+        const newStem = detail.expected.replace(/\.ts$/, '');
+        if (oldStem === newStem)
+            continue;
+        const oldRel = issue.file;
+        const newRel = oldRel.replace(/[^/]+\.ts$/, `${newStem}.ts`);
+        const before = await readFile(join(cwd, oldRel), 'utf8');
+        // importer 스캔(최초 1회). node_modules·.gaon·dist·.git 제외.
+        if (!sources)
+            sources = await collectSources(cwd);
+        const refEdits = [];
+        for (const s of sources) {
+            if (s.rel === oldRel)
+                continue; // 이동 대상 자신은 제외
+            const after = rewriteSchemaImport(s.text, oldStem, newStem);
+            if (after !== undefined)
+                refEdits.push({ file: s.rel, before: s.text, after });
+        }
+        const refSummary = refEdits.length > 0
+            ? `참조 ${refEdits.length}곳 경로 갱신(${refEdits.map((r) => r.file).join(', ')})`
+            : '참조 갱신 없음(이 스키마를 import 하는 곳을 찾지 못함)';
+        plans.push({
+            kind: 'rename',
+            file: oldRel,
+            to: newRel,
+            before,
+            refEdits,
+            summary: `스키마 파일명 관례(§1.1 · camelCase) 정정: '${oldRel}' → '${newRel}'. ${refSummary}.\n` +
+                `  근거: 결정 38 · 스키마 파일명 = 테이블명을 camelCase 로. 테이블명 문자열은 그대로 둡니다.`,
+        });
+    }
+    return plans;
+}
+/** 프로젝트 .ts(선언·테스트 제외) 소스를 수집. importer 참조 스캔용. */
+async function collectSources(cwd) {
+    const out = [];
+    const skip = new Set(['node_modules', '.gaon', 'dist', '.git']);
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = (await readdir(dir, { withFileTypes: true }));
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (skip.has(e.name))
+                    continue;
+                await walk(p);
+            }
+            else if (e.isFile() && e.name.endsWith('.ts') && !e.name.endsWith('.d.ts')) {
+                const s = await stat(p);
+                if (!s.isFile())
+                    continue;
+                out.push({ rel: relative(cwd, p).split('\\').join('/'), text: await readFile(p, 'utf8') });
+            }
+        }
+    }
+    await walk(cwd);
+    return out;
+}

package/dist/doctor/fixers/types.d.ts

@@ -0,0 +1,59 @@
+import type { DoctorCheck, DoctorRule } from '../types.js';
+/**
+ * 한 파일 안에서 fixer 가 계산한 내용 재작성 계획(가장 흔한 형태).
+ * `kind` 생략 = 'rewrite'(하위 호환 — 기존 fixer 는 이 필드를 안 쓴다).
+ */
+export interface RewriteFixerPlan {
+    readonly kind?: 'rewrite';
+    /** 프로젝트 루트 기준 상대 경로(reporter 와 정합). */
+    readonly file: string;
+    /** 편집 전 원본. rollback · diff 참조용. */
+    readonly before: string;
+    /** 편집 후 최종 소스. before 와 같으면 스킵(변경 없음). */
+    readonly after: string;
+    /** 사람용 요약(무엇을 왜 바꿨는지 · 리포트에 그대로 출력). */
+    readonly summary: string;
+}
+/**
+ * 파일 이름 변경 계획 — 파일을 옮기고, 그 파일을 import 하는 곳의 경로를 함께
+ * 고친다. 내용 재작성만으로는 표현할 수 없어(파일 이동 + 다중 파일 참조 갱신)
+ * 별도 종류로 둔다. 상위(runDoctorFix)가 이동·참조 편집·백업을 관장한다.
+ */
+export interface RenameFixerPlan {
+    readonly kind: 'rename';
+    /** 현재 경로(프로젝트 상대). 이동 후 삭제된다. */
+    readonly file: string;
+    /** 새 경로(프로젝트 상대). 내용은 file 과 동일하게 옮겨진다. */
+    readonly to: string;
+    /** 이동되는 파일의 원본 내용(내용은 바뀌지 않고 경로만 바뀐다). */
+    readonly before: string;
+    /** 사람용 요약(무엇을 왜 옮겼는지 · 참조 갱신 요약 포함). */
+    readonly summary: string;
+    /** 이 파일을 import 하는 곳의 경로 갱신(파일 이동에 딸린 참조 수정). */
+    readonly refEdits: readonly RefEdit[];
+}
+/** import 경로 갱신 — 한 importer 파일의 before → after. */
+export interface RefEdit {
+    /** 프로젝트 루트 기준 상대 경로. */
+    readonly file: string;
+    readonly before: string;
+    readonly after: string;
+}
+/** fixer 가 낸 계획 — 내용 재작성 또는 파일 이름 변경. */
+export type FixerPlan = RewriteFixerPlan | RenameFixerPlan;
+/**
+ * 규칙 검사가 낸 DoctorCheck 를 받아 파일별 수정 계획을 낸다. 파일 I/O 는
+ * 여기서 하지 않는다(테스트 편의 · 순수 함수). 아무 것도 못 고치면 빈
+ * 배열을 낸다.
+ *
+ * @param issues 규칙이 낸 error/warning check 목록(passed 는 제외됨).
+ * @param cwd    프로젝트 루트 절대 경로(파일 읽기용).
+ */
+export type Fixer = (issues: readonly DoctorCheck[], cwd: string) => Promise<readonly FixerPlan[]>;
+/** 규칙별 fixer 지원 여부. 리포트가 "수동 수정 필요" 를 판단하는 근거. */
+export interface FixerCapability {
+    readonly rule: DoctorRule;
+    readonly hasFixer: boolean;
+    /** 사람용 짧은 설명(리포트에 그대로). */
+    readonly note: string;
+}

package/dist/doctor/fixers/types.js

@@ -0,0 +1,15 @@
+// @gaonjs/cli · doctor · fixer 공용 타입 (M9-fix · v0.16 §7.5.3)
+//
+// v0.16 §7.5.3 "관례 위반 중 기계적으로 고칠 수 있는 것(파일 위치, 이름
+// 규칙)은 자동 수정한다" 정본에 따라, 각 doctor 규칙에 대응하는 fixer 를
+// 이 자리에 등록한다. 규칙 하나 = fixer 최대 하나. fixer 가 없는 규칙은
+// 리포트에 "수동 수정 필요" 로 표기된다(사용자가 우회 여부를 스스로 판단).
+//
+// 안전 원칙:
+//   1) --fix 는 파괴적 변경을 하지 않는다. 편집한 파일의 원본 백업을
+//      대상 파일 옆에 `<파일>.bak-YYYYMMDD-HHMMSS` 로 남긴다(overwrite X).
+//   2) --yes 없이 --fix 를 주면 dry-run 이다 — 무엇을 고칠지 리포트만.
+//      실 편집은 --fix --yes 조합에서만 일어난다.
+//   3) fixer 는 순수 계산(입력 소스 → 출력 소스)만 담당. 파일 I/O 는
+//      상위(runDoctorFix)가 백업·쓰기·롤백을 관장한다.
+export {};

package/dist/doctor/no-auto-import.d.ts

@@ -0,0 +1,10 @@
+import type { DoctorCheck, RuleReport } from './types.js';
+/**
+ * config 파일 하나의 소스에서 자동 import 플러그인 import 를 잡는다
+ * (단위 테스트 진입점).
+ */
+export declare function inspectConfigForAutoImport(file: string, source: string, cwd: string): DoctorCheck[];
+/** package.json 안의 deps 4종을 훑어 자동 import 플러그인 유무를 낸다. */
+export declare function inspectPackageJson(file: string, source: string, cwd: string): DoctorCheck[];
+/** 프로젝트 루트를 훑어 자동 import 설정·의존을 잡는다. */
+export declare function checkNoAutoImport(cwd: string): Promise<RuleReport>;