@gaonjs/cli 0.4.0 → 0.10.0

package/dist/doctor/no-auto-import.js

@@ -0,0 +1,158 @@
+// @gaonjs/cli · doctor · 자동 import 감지 (M9-E 확장 · errata E-5 §2.4)
+//
+// Nuxt 식 자동 import(컴포넌트·컴포저블을 import 문 없이 사용)는 넣지
+// 않는다. 출처가 코드에 보이지 않는 마법은 AI 가 "이 심볼이 어디서
+// 왔는지"를 추측하게 만들어 v0.15 §1.2 (관례로 추측을 없앤다) 와 정면
+// 충돌한다. 모든 컴포넌트·컴포저블은 명시적으로 import 한다.
+//
+// 검사 대상 (E-5 §2.4 · v0.15 §1.2):
+//  1) 프로젝트 루트의 대표 config 파일 안의 import 선언에서
+//     'unplugin-auto-import' · 'unplugin-vue-components' · 'unimport'
+//     발견 시 error.
+//  2) package.json 의 dependencies · devDependencies · peerDependencies
+//     · optionalDependencies 에 위 3종이 있으면 error.
+//
+// 방법: config 는 TS AST 로 import 선언만 훑고 · package.json 은 JSON
+// 파싱 + 라인 검색(에러 메시지에 라인을 붙이기 위해 원문에서 재검색).
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import ts from 'typescript';
+/** 금지 플러그인 목록 — 자동 import 를 도입하는 대표 3종. */
+const FORBIDDEN_PLUGINS = [
+    'unplugin-auto-import',
+    'unplugin-vue-components',
+    'unimport',
+];
+/**
+ * 검사할 config 파일. Vite/Nuxt/Vue-CLI 관례 파일명을 모두 훑는다.
+ * 존재하지 않는 파일은 스킵.
+ */
+const CONFIG_FILES = [
+    'vite.config.ts',
+    'vite.config.js',
+    'vite.config.mjs',
+    'nuxt.config.ts',
+    'nuxt.config.js',
+    'vue.config.js',
+    'vue.config.ts',
+];
+/**
+ * config 파일 하나의 소스에서 자동 import 플러그인 import 를 잡는다
+ * (단위 테스트 진입점).
+ */
+export function inspectConfigForAutoImport(file, source, cwd) {
+    const issues = [];
+    const rel = relative(cwd, file);
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+            const spec = node.moduleSpecifier.text;
+            const plugin = matchForbidden(spec);
+            if (plugin) {
+                const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+                issues.push({
+                    rule: 'no-auto-import',
+                    level: 'error',
+                    file: rel,
+                    line: line + 1,
+                    message: `${rel} (line ${line + 1})\n` +
+                        `  '${plugin}' 발견 · v0.15 §1.2 (관례로 추측 없앤다) 정합 X\n` +
+                        `→ 자동 import 플러그인 제거 · 명시 import 사용`,
+                    detail: { plugin, source: 'config-import', module: spec },
+                });
+            }
+        }
+        // require('unplugin-...') 형태(CJS config)도 잡는다.
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'require') {
+            const arg = node.arguments[0];
+            if (arg && ts.isStringLiteral(arg)) {
+                const plugin = matchForbidden(arg.text);
+                if (plugin) {
+                    const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+                    issues.push({
+                        rule: 'no-auto-import',
+                        level: 'error',
+                        file: rel,
+                        line: line + 1,
+                        message: `${rel} (line ${line + 1})\n` +
+                            `  '${plugin}' 발견 · v0.15 §1.2 (관례로 추측 없앤다) 정합 X\n` +
+                            `→ 자동 import 플러그인 제거 · 명시 import 사용`,
+                        detail: { plugin, source: 'config-require', module: arg.text },
+                    });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return issues;
+}
+/** 지정한 모듈 이름이 금지 목록에 걸리면 해당 플러그인 이름을 낸다. */
+function matchForbidden(spec) {
+    return FORBIDDEN_PLUGINS.find((p) => spec === p || spec.startsWith(p + '/'));
+}
+/** package.json 안의 deps 4종을 훑어 자동 import 플러그인 유무를 낸다. */
+export function inspectPackageJson(file, source, cwd) {
+    const issues = [];
+    const rel = relative(cwd, file);
+    let pkg;
+    try {
+        pkg = JSON.parse(source);
+    }
+    catch {
+        // JSON 파싱 실패 시 이 규칙은 아무 것도 하지 않는다 — 다른 규칙 도구가
+        // 잡을 문제(예: gaon check 의 tsconfig 파싱)이지 자동 import 검사의 몫이 아님.
+        return [];
+    }
+    const allDeps = {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+        ...(pkg.peerDependencies ?? {}),
+        ...(pkg.optionalDependencies ?? {}),
+    };
+    for (const plugin of FORBIDDEN_PLUGINS) {
+        if (!(plugin in allDeps))
+            continue;
+        const line = findLineForKey(source, plugin);
+        const loc = line ? ` (line ${line})` : '';
+        issues.push({
+            rule: 'no-auto-import',
+            level: 'error',
+            file: rel,
+            line: line,
+            message: `${rel}${loc}\n` +
+                `  package.json 에 '${plugin}' 발견 · v0.15 §1.2 (관례로 추측 없앤다) 정합 X\n` +
+                `→ 자동 import 플러그인 제거 · 명시 import 사용 · 'pnpm remove ${plugin}' 후 vite/nuxt config 도 정리`,
+            detail: { plugin, source: 'package-json' },
+        });
+    }
+    return issues;
+}
+/** package.json 원문에서 `"<key>"` 가 처음 나오는 1-기반 라인 번호. */
+function findLineForKey(source, key) {
+    const lines = source.split(/\r?\n/);
+    const needle = `"${key}"`;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].includes(needle))
+            return i + 1;
+    }
+    return undefined;
+}
+/** 프로젝트 루트를 훑어 자동 import 설정·의존을 잡는다. */
+export async function checkNoAutoImport(cwd) {
+    const issues = [];
+    for (const cfg of CONFIG_FILES) {
+        const full = join(cwd, cfg);
+        if (!existsSync(full))
+            continue;
+        const src = await readFile(full, 'utf8');
+        issues.push(...inspectConfigForAutoImport(full, src, cwd));
+    }
+    const pkgPath = join(cwd, 'package.json');
+    if (existsSync(pkgPath)) {
+        const src = await readFile(pkgPath, 'utf8');
+        issues.push(...inspectPackageJson(pkgPath, src, cwd));
+    }
+    return { rule: 'no-auto-import', issues };
+}

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

@@ -0,0 +1,6 @@
+import type { RuleReport } from './types.js';
+/** 파일 stem 을 camelCase 로 정규화(`posts_tags`→`postsTags` · `Posts`→`posts` · `posts`→`posts`). */
+export declare function expectedSchemaStem(stem: string): string;
+/** 소스에서 첫 `table('<이름>', …)` 의 테이블명을 뽑는다(없으면 undefined). */
+export declare function extractTableName(source: string): string | undefined;
+export declare function checkSchemaFilename(cwd: string): Promise<RuleReport>;

package/dist/doctor/schema-filename.js

@@ -0,0 +1,81 @@
+// @gaonjs/cli · doctor · 스키마 파일명 관례 (결정 38 · 2026-07-25)
+//
+// 정본 §1.1: 스키마 파일명 = 테이블명을 **camelCase** 로 바꾼 것. 테이블명에
+// `_` 가 있어도 파일명엔 `_` 를 쓰지 않는다 — 조인 테이블 `posts_tags` →
+// `domain/schema/postsTags.ts` (파일 안 `table('posts_tags', …)` 는 스네이크
+// 유지). 소형 모델(haiku)이 다단어 테이블에서 파일명을 스네이크로 쓰는
+// 실측(feature-slice T4)이 있어, 잘못된 파일명을 검출해 §7.5.3 수리 안내를
+// 준다. `The One Way` — 두 형태 허용 없이 camelCase 하나로 못박는다.
+//
+// 판정 범위: **파일명이 camelCase 가 아닌 경우만**(스네이크·케밥·Pascal) 잡는다.
+// 단수/복수(`post.ts` vs `posts.ts`)는 이 결정의 대상이 아니라 건드리지 않는다
+// — 기존 fixture 가 단수 파일명(`post.ts`)을 쓰므로 그것까지 실격시키면 결정
+// 범위를 넘는다. 그래서 기대 파일명은 **실제 파일명 stem 을 camelCase 로 정규화**
+// 한 값이다(테이블명 단수화가 아님). 이미 camelCase 면 정규화해도 그대로라 통과.
+// table() 선언이 있는 파일만 대상으로 삼아 배럴·비스키마 파일 오탐을 막는다.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, join, relative } from 'node:path';
+import { toCamel, toPascal } from '../scaffold/inflect.js';
+/** 파일 stem 을 camelCase 로 정규화(`posts_tags`→`postsTags` · `Posts`→`posts` · `posts`→`posts`). */
+export function expectedSchemaStem(stem) {
+    return toCamel(toPascal(stem));
+}
+/** 소스에서 첫 `table('<이름>', …)` 의 테이블명을 뽑는다(없으면 undefined). */
+export function extractTableName(source) {
+    const m = source.match(/\btable\(\s*['"`]([^'"`]+)['"`]/);
+    return m ? m[1] : undefined;
+}
+export async function checkSchemaFilename(cwd) {
+    const schemaDir = join(cwd, 'domain', 'schema');
+    const files = [];
+    await collectTsFiles(schemaDir, files);
+    const issues = [];
+    for (const abs of files) {
+        const source = await readFile(abs, 'utf8');
+        const tableName = extractTableName(source);
+        if (!tableName)
+            continue; // table() 없음 = 스키마 테이블 파일 아님 · 건너뜀
+        const actualStem = basename(abs).replace(/\.ts$/, '');
+        const expected = expectedSchemaStem(actualStem);
+        if (actualStem === expected)
+            continue; // 이미 camelCase(단수/복수 무관) · 통과
+        const rel = relative(cwd, abs).split('\\').join('/');
+        const expectedRel = rel.replace(/[^/]+\.ts$/, `${expected}.ts`);
+        issues.push({
+            rule: 'schema-filename',
+            level: 'error',
+            file: rel,
+            message: `스키마 파일명이 관례(§1.1 · camelCase)와 어긋납니다: '${actualStem}.ts' ` +
+                `(테이블 '${tableName}' · 기대 파일명 '${expected}.ts').\n` +
+                `→ '${rel}' 를 '${expectedRel}' 로 이름을 바꾸고, 이 스키마를 import 하는 ` +
+                `모델(예: '../schema/${expected}.js')의 경로도 함께 고치세요. ` +
+                `테이블명 문자열('${tableName}')은 그대로 둡니다.`,
+            detail: { tableName, actual: `${actualStem}.ts`, expected: `${expected}.ts` },
+        });
+    }
+    return { rule: 'schema-filename', issues };
+}
+/** domain/schema/ 아래 .ts(선언·테스트 제외)를 재귀 수집. migration-diff 와 동일 패턴. */
+async function collectTsFiles(root, out) {
+    let entries;
+    try {
+        entries = (await readdir(root, { withFileTypes: true }));
+    }
+    catch {
+        return; // domain/schema/ 없음 = 검사할 것 없음
+    }
+    for (const e of entries) {
+        const p = join(root, e.name);
+        if (e.isDirectory()) {
+            await collectTsFiles(p, out);
+        }
+        else if (e.isFile() &&
+            e.name.endsWith('.ts') &&
+            !e.name.endsWith('.d.ts') &&
+            !e.name.endsWith('.test.ts')) {
+            const s = await stat(p);
+            if (s.isFile())
+                out.push(p);
+        }
+    }
+}

package/dist/doctor/shared-composable-purity.d.ts

@@ -0,0 +1,8 @@
+import type { DoctorCheck, RuleReport } from './types.js';
+/**
+ * 단일 shared 컴포저블 소스를 검사해 순수성 위반 목록을 낸다
+ * (단위 테스트 진입점).
+ */
+export declare function inspectSharedComposable(file: string, source: string, cwd: string): DoctorCheck[];
+/** shared/composables/ 를 훑어 순수성 위반을 모두 낸다. */
+export declare function checkSharedComposablePurity(cwd: string): Promise<RuleReport>;

package/dist/doctor/shared-composable-purity.js

@@ -0,0 +1,164 @@
+// @gaonjs/cli · doctor · shared 컴포저블 순수성 검사 (M9-E 확장 · errata E-5 §2.2)
+//
+// shared/composables/ 는 shared 컴포넌트의 "props 로만" 규칙과 정확히
+// 같은 구도를 따른다. 라우트를 몰라야 하고(api·pageProps 금지) · domain
+// 은 타입으로만 참조해야 한다. 필요한 데이터·호출 함수는 인자로 받는다.
+// 정본 근거: errata E-5 §2.2 (컴포저블·레이아웃 관례 · 결정 25).
+//
+// 검사 대상:
+//  1) 프레임웍 모듈(gaonjs · gaonjs/vue · @gaonjs/vue · @gaonjs/web) 에서
+//     'api' · 'pageProps' 를 value import 하면 error.
+//     - type-only 는 무해(구조 참조뿐 · 라우트 지식 필요 없음).
+//  2) domain 을 value import 하면 error.
+//     - type-only 는 허용(모델 Row 타입 등 · 순수 타입 참조).
+//
+// 방법: shared/composables/*.ts 를 TS AST 로 파싱해 import 선언만 훑는다.
+// 상대 import 는 실 파일까지 해석하지 않고 경로 접두사(domain/) 로 판정 —
+// 이 검사는 순수성 게이트라 정확도보다 재현성이 우선(false positive 는
+// 오히려 안전).
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, resolve, dirname } from 'node:path';
+import ts from 'typescript';
+/** 라우트 지식을 담은 심볼 — shared 는 참조할 수 없다. */
+const FORBIDDEN_FRAMEWORK_NAMES = new Set(['api', 'pageProps']);
+/**
+ * 프레임웍 모듈 패턴. 문서 표기(gaon/vue)는 실 패키지 이름의 짧은
+ * 별칭이며, 실 배포본은 gaonjs 파사드 subpath 와 @gaonjs 스코프를 쓴다.
+ * 하나만 잡으면 우회가 쉬우므로 알려진 표기 3종을 모두 매치한다.
+ */
+const FRAMEWORK_MODULE_PATTERNS = [
+    /^gaonjs$/,
+    /^gaonjs\/vue$/,
+    /^@gaonjs\/vue$/,
+    /^@gaonjs\/web$/,
+];
+/** import 선언에서 이름과 type-only 플래그를 추출한다. */
+function collectImportedNames(node) {
+    const out = [];
+    const clause = node.importClause;
+    if (!clause)
+        return out;
+    const clauseTypeOnly = clause.isTypeOnly;
+    if (clause.name)
+        out.push({ name: clause.name.text, typeOnly: clauseTypeOnly });
+    const bindings = clause.namedBindings;
+    if (bindings) {
+        if (ts.isNamespaceImport(bindings)) {
+            out.push({ name: bindings.name.text, typeOnly: clauseTypeOnly });
+        }
+        else if (ts.isNamedImports(bindings)) {
+            for (const el of bindings.elements) {
+                out.push({ name: el.name.text, typeOnly: clauseTypeOnly || el.isTypeOnly });
+            }
+        }
+    }
+    return out;
+}
+function isRelativeSpecifier(s) {
+    return s.startsWith('./') || s.startsWith('../');
+}
+function matchesFrameworkModule(spec) {
+    return FRAMEWORK_MODULE_PATTERNS.some((re) => re.test(spec));
+}
+/**
+ * 단일 shared 컴포저블 소스를 검사해 순수성 위반 목록을 낸다
+ * (단위 테스트 진입점).
+ */
+export function inspectSharedComposable(file, source, cwd) {
+    const issues = [];
+    const rel = relative(cwd, file);
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const baseDir = dirname(file);
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+            const spec = node.moduleSpecifier.text;
+            const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+            const names = collectImportedNames(node);
+            // 1) 프레임웍의 api/pageProps 를 value import → error
+            if (matchesFrameworkModule(spec)) {
+                for (const n of names) {
+                    if (n.typeOnly)
+                        continue; // type-only 는 라우트 실행 지식이 아님
+                    if (!FORBIDDEN_FRAMEWORK_NAMES.has(n.name))
+                        continue;
+                    issues.push({
+                        rule: 'shared-composable-purity',
+                        level: 'error',
+                        file: rel,
+                        line: line + 1,
+                        message: `${rel} (line ${line + 1})\n` +
+                            `  '${spec}' 의 '${n.name}' import 발견 · shared 는 라우트를 몰라야 함\n` +
+                            `→ 옵션: apps/<앱>/composables/ 로 옮기거나 · ${n.name} 호출을 인자로 받도록 바꾸라`,
+                        detail: {
+                            kind: 'framework-api',
+                            module: spec,
+                            name: n.name,
+                        },
+                    });
+                }
+            }
+            // 2) domain value import → error (type-only 는 허용)
+            if (isRelativeSpecifier(spec)) {
+                const abs = resolve(baseDir, spec);
+                const parts = relative(cwd, abs).split(/[\\/]/).filter(Boolean);
+                if (parts[0] === 'domain') {
+                    const valueNames = names.filter((n) => !n.typeOnly);
+                    if (valueNames.length > 0) {
+                        issues.push({
+                            rule: 'shared-composable-purity',
+                            level: 'error',
+                            file: rel,
+                            line: line + 1,
+                            message: `${rel} (line ${line + 1})\n` +
+                                `  domain 값 import 발견 · shared 컴포저블은 domain 을 타입으로만 참조해야 함\n` +
+                                `→ 'import type { ... } from ...' 형태로 바꾸거나 · 필요한 값은 인자로 받도록 바꾸라`,
+                            detail: {
+                                kind: 'domain-value',
+                                module: spec,
+                                names: valueNames.map((n) => n.name),
+                            },
+                        });
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return issues;
+}
+/** shared/composables/ 를 훑어 순수성 위반을 모두 낸다. */
+export async function checkSharedComposablePurity(cwd) {
+    const composablesDir = join(cwd, 'shared', 'composables');
+    const files = [];
+    await collectTsFiles(composablesDir, files);
+    const issues = [];
+    for (const file of files) {
+        const src = await readFile(file, 'utf8');
+        issues.push(...inspectSharedComposable(file, src, cwd));
+    }
+    return { rule: 'shared-composable-purity', 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/types.d.ts

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-composable-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor/types.js

@@ -1,9 +1,10 @@
-// @gaonjs/cli · doctor 공용 타입 (M9-E · M9-E-Fix)
+// @gaonjs/cli · doctor 공용 타입 (M9-E · M9-E-Fix · M9-E 확장 · E-5)
 //
-// 5 검사(response-mixing · n-plus-one · dependency-direction · connections
-// · migration-diff)가 모두 이 DoctorCheck 를 낸다. 상위(runDoctorCommand)는
-// level 로 passed/warnings/errors 로 갈라 담는다. 자동화(CI)는 JSON 을
-// 파싱해 errors.length > 0 이면 fail 로 판단한다.
+// 7 검사(response-mixing · n-plus-one · dependency-direction · connections
+// · migration-diff · shared-composable-purity · no-auto-import)가 모두
+// 이 DoctorCheck 를 낸다. 상위(runDoctorCommand)는 level 로 passed/
+// warnings/errors 로 갈라 담는다. 자동화(CI)는 JSON 을 파싱해
+// errors.length > 0 이면 fail 로 판단한다.
 //
 // 사전 검사 실패(프로젝트 마커 없음 · TS API 미노출)는 규칙 실행 자체가
 // 불가능한 상황이므로 별도 `fatal` 필드로 표현한다 — runCli 는 이 경우

package/dist/doctor.d.ts

@@ -6,12 +6,47 @@ export { inspectControllerForNPlusOne, checkNPlusOne } from './doctor/n-plus-one
 export { extractRelativeImports, checkDependencyDirection } from './doctor/dependency-direction.js';
 export { extractConfigDbKeys, extractKeyUses, checkConnections } from './doctor/connections.js';
 export { scanSchema, checkMigrationDiff } from './doctor/migration-diff.js';
+export { inspectSharedComposable, checkSharedComposablePurity, } from './doctor/shared-composable-purity.js';
+export { inspectConfigForAutoImport, inspectPackageJson, checkNoAutoImport, } from './doctor/no-auto-import.js';
+export { expectedSchemaStem, extractTableName, checkSchemaFilename, } from './doctor/schema-filename.js';
+export { extractAgentDocRefs, checkAgentsDocIndex } from './doctor/agents-doc-index.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 export interface DoctorCommandOptions {
     readonly cwd?: string;
     readonly json?: boolean;
     readonly checks?: readonly DoctorRule[];
+    /**
+     * 자동 정정 모드(v0.16 §7.5.3). true 면 각 규칙의 fixer 를 계획한다.
+     * `yes` 가 없으면 dry-run(계획만 보고 · 파일 편집 X), 있으면 실제 편집.
+     * 편집 전 원본은 `<파일>.bak-<타임스탬프>` 로 백업된다(--yes 여도 안전망).
+     */
+    readonly fix?: boolean;
+    /** 실제 파일 편집 승인. `fix` 와 함께 줘야 편집이 일어난다. */
+    readonly yes?: boolean;
+}
+/** --fix 리포트의 파일별 결과. FixerPlan 위에 dry/applied 상태를 얹는다. */
+export interface FixOutcome {
+    readonly rule: DoctorRule;
+    readonly file: string;
+    readonly summary: string;
+    /** true 이면 실제 편집됨, false 이면 dry-run(계획만 · --yes 없음). */
+    readonly applied: boolean;
+    /** 실제 편집 시 원본 백업 경로(프로젝트 상대). dry-run 은 undefined. */
+    readonly backup?: string;
+}
+/** --fix 실행 결과. runCli 는 fixesApplied · fixesPlanned 로 종료 코드 결정. */
+export interface DoctorFixReport {
+    /** fixer 가 있는 규칙별 계획·적용 결과. */
+    readonly outcomes: readonly FixOutcome[];
+    /** fixer 가 없어서 수동 수정이 필요한 규칙별 위반 수(요약). */
+    readonly manualRequired: readonly {
+        rule: DoctorRule;
+        issueCount: number;
+        note: string;
+    }[];
+    /** 실제로 편집이 일어났는지(--yes 여부). */
+    readonly applied: boolean;
 }
 /**
  * `gaon doctor` 진입점 (M9-E · 확장 · M9-E-Fix 하드닝).
@@ -33,6 +68,22 @@ export interface DoctorCommandOptions {
  * 나머지 규칙은 계속 실행(부분 결과 확보).
  */
 export declare function runDoctorCommand(opts?: DoctorCommandOptions): Promise<DoctorResult>;
+/**
+ * fixer 를 계획·(승인 시)실행한다. 파일 편집은 여기서만 일어난다 —
+ * fixer 자체는 순수 계산 함수.
+ *
+ * 안전:
+ *  1) apply=false(=--yes 없음) 면 dry-run — 파일을 만지지 않는다.
+ *  2) apply=true 면 원본을 `<파일>.bak-<타임스탬프>` 로 백업 후 편집.
+ *  3) 편집 중 예외가 나면 그 파일만 실패로 리포트하고 다음 파일을 계속.
+ */
+export declare function runDoctorFix(reports: readonly RuleReport[], cwd: string, apply: boolean): Promise<DoctorFixReport>;
+/** 리포트에 함께 실려 나가는 확장 결과. runCli 가 종료 코드를 결정하는 근거. */
+export interface DoctorResultWithFix extends DoctorResult {
+    readonly fix: DoctorFixReport;
+}
+/** 사람 친화 fix 리포트. json 은 상위 renderJson 이 그대로 직렬화. */
+export declare function renderFixHuman(report: DoctorFixReport): string;
 export interface DoctorIssue {
     readonly file: string;
     readonly line: number;