@gaonjs/cli 0.2.0 → 0.4.0

package/dist/doctor/n-plus-one.js

@@ -0,0 +1,242 @@
+// @gaonjs/cli · doctor · N+1 감지 (M9-E · errata E-4 (e))
+//
+// 컨트롤러 액션에서 belongsTo 관계 접근이 loop 안에 있고, 같은 액션에서
+// `.include(<relation>)` 로 eager 로딩을 걸어 두지 않았으면 N+1 이다.
+// 예: posts.map(p => p.author()) — 각 반복마다 DB 왕복 = N+1 쿼리.
+//
+// 정확도(spec): false positive 최소 · 애매하면 information warning.
+//  - AST 기반 · 스키마 로드 없이 순수 소스 분석
+//  - 위 패턴에 정확히 맞을 때만 warning(에러 아님)
+//  - 액션 내 어디서든 `.include('<name>')` 가 있으면 통과 (개발자 인지)
+//
+// 감지 대상 loop:
+//  - for (const p of items)
+//  - items.forEach(p => ...)  ·  items.map(async p => ...)  ·  .filter · .reduce
+// loop 안 감지 대상 호출:
+//  - await p.<name>()   (property access call · 인자 없음 · await 있음)
+//  - p.<name>()         (문장 노드로 존재 · await 없어도 catch 가능)
+//
+// 감지 대상 아님(false positive 방지):
+//  - 문자열 리터럴만 있는 호출  · 정적 프로퍼티 접근  · 인자 있는 호출
+//  - 액션이 이미 `.include(<name>)` 를 사용한 경우
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import ts from 'typescript';
+/** 소스 하나를 검사해 N+1 위반 목록을 낸다(단위 테스트 진입점). */
+export function inspectControllerForNPlusOne(file, source, cwd) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const actions = [];
+    // 컨트롤러 액션 수집
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && isControllerCall(node)) {
+            const arg = node.arguments[0];
+            if (arg && ts.isObjectLiteralExpression(arg)) {
+                for (const prop of arg.properties) {
+                    const nm = actionName(prop);
+                    if (!nm)
+                        continue;
+                    const body = actionBody(prop);
+                    if (!body || !ts.isBlock(body))
+                        continue;
+                    const { line } = sf.getLineAndCharacterOfPosition(prop.getStart(sf));
+                    actions.push({ name: nm, line: line + 1, body });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    const issues = [];
+    const rel = relative(cwd, file);
+    for (const a of actions) {
+        const includedRelations = collectIncludes(a.body);
+        const violations = findNPlusOneInBlock(a.body, includedRelations, sf);
+        for (const v of violations) {
+            issues.push({
+                rule: 'n-plus-one',
+                level: 'warning',
+                file: rel,
+                line: v.line,
+                message: `N+1 감지: ${rel}:${v.line} · 액션 '${a.name}' 의 loop 안에서 ` +
+                    `'${v.iter}.${v.rel}()' 를 호출합니다. 각 반복마다 DB 왕복이 발생합니다.\n` +
+                    `→ loop 이전 쿼리에 '.include(\\'${v.rel}\\')' 를 붙여 eager 로딩하세요 (errata E-4 (e)).\n` +
+                    `→ 예: const posts = await Post.include('${v.rel}').all()`,
+                detail: { action: a.name, relation: v.rel, iter: v.iter },
+            });
+        }
+    }
+    return issues;
+}
+/** 액션 본문 안의 모든 `.include('<name>')` 인자 이름을 수집한다. */
+function collectIncludes(root) {
+    const names = new Set();
+    const visit = (node) => {
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            node.expression.name.text === 'include') {
+            for (const arg of node.arguments) {
+                if (ts.isStringLiteral(arg) || ts.isNoSubstitutionTemplateLiteral(arg))
+                    names.add(arg.text);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(root);
+    return names;
+}
+/** 블록 안의 loop 를 순회해 loop 반복 변수의 belongsTo 호출을 감지한다. */
+function findNPlusOneInBlock(block, included, sf) {
+    const out = [];
+    const scan = (node) => {
+        // for (const p of items)
+        if (ts.isForOfStatement(node)) {
+            const iter = forOfIterName(node);
+            if (iter)
+                scanLoopBody(node.statement, iter, included, out, sf);
+        }
+        // items.forEach / map / filter / reduce 등 · 콜백 첫 인자 = iter
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+            const m = node.expression.name.text;
+            if (m === 'forEach' || m === 'map' || m === 'filter' || m === 'reduce') {
+                const cb = node.arguments[0];
+                if (cb && (ts.isArrowFunction(cb) || ts.isFunctionExpression(cb))) {
+                    const p0 = cb.parameters[0];
+                    if (p0 && ts.isIdentifier(p0.name)) {
+                        const iter = p0.name.text;
+                        const body = cb.body;
+                        if (ts.isBlock(body))
+                            scanLoopBody(body, iter, included, out, sf);
+                        else
+                            scanExpr(body, iter, included, out, sf);
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, scan);
+    };
+    scan(block);
+    return out;
+}
+function forOfIterName(node) {
+    const init = node.initializer;
+    if (ts.isVariableDeclarationList(init) && init.declarations.length === 1) {
+        const d = init.declarations[0];
+        if (ts.isIdentifier(d.name))
+            return d.name.text;
+    }
+    return undefined;
+}
+function scanLoopBody(body, iter, included, out, sf) {
+    const visit = (node) => {
+        // 중첩 함수는 스코프 다름 — 파고들지 않음(false positive 방지).
+        if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node))
+            return;
+        const matched = scanExpr(node, iter, included, out, sf);
+        // await x.y() 를 한 번 매치했으면 안쪽 CallExpression 을 다시 매치해
+        // 이중 리포트 하지 않도록 여기서 멈춘다.
+        if (matched)
+            return;
+        ts.forEachChild(node, visit);
+    };
+    visit(body);
+}
+function scanExpr(node, iter, included, out, sf) {
+    // await x.rel() 또는 x.rel() 두 형태 모두 catch.
+    // 인자가 없는 호출만 대상으로 삼는다(true belongsTo 시그니처).
+    const call = ts.isAwaitExpression(node) && ts.isCallExpression(node.expression)
+        ? node.expression
+        : ts.isCallExpression(node)
+            ? node
+            : undefined;
+    if (!call)
+        return false;
+    if (call.arguments.length !== 0)
+        return false;
+    const e = call.expression;
+    if (!ts.isPropertyAccessExpression(e))
+        return false;
+    if (!ts.isIdentifier(e.expression))
+        return false;
+    if (e.expression.text !== iter)
+        return false;
+    const relName = e.name.text;
+    // include 로 미리 로드했으면 통과.
+    if (included.has(relName))
+        return true;
+    // 알려진 배열/이터레이션 원시 메서드는 제외(map/filter 등이 iter 위에 다시 걸리는 케이스).
+    if (BUILTIN_ITER_METHODS.has(relName))
+        return true;
+    const { line } = sf.getLineAndCharacterOfPosition(call.getStart(sf));
+    out.push({ iter, rel: relName, line: line + 1 });
+    return true;
+}
+const BUILTIN_ITER_METHODS = new Set([
+    'toString',
+    'valueOf',
+    'toJSON',
+    'toLocaleString',
+    'hasOwnProperty',
+]);
+function isControllerCall(node) {
+    const e = node.expression;
+    if (ts.isIdentifier(e) && e.text === 'controller')
+        return true;
+    if (ts.isPropertyAccessExpression(e) && e.name.text === 'controller')
+        return true;
+    return false;
+}
+function actionName(prop) {
+    if (ts.isMethodDeclaration(prop) && ts.isIdentifier(prop.name))
+        return prop.name.text;
+    if (ts.isPropertyAssignment(prop) &&
+        ts.isIdentifier(prop.name) &&
+        (ts.isArrowFunction(prop.initializer) || ts.isFunctionExpression(prop.initializer))) {
+        return prop.name.text;
+    }
+    return undefined;
+}
+function actionBody(prop) {
+    if (ts.isMethodDeclaration(prop))
+        return prop.body;
+    if (ts.isPropertyAssignment(prop)) {
+        if (ts.isArrowFunction(prop.initializer))
+            return prop.initializer.body;
+        if (ts.isFunctionExpression(prop.initializer))
+            return prop.initializer.body;
+    }
+    return undefined;
+}
+/** apps/ 를 스캔해 N+1 검사를 돌린다. */
+export async function checkNPlusOne(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const app of await safeListDirs(appsDir)) {
+        const ctrlDir = join(appsDir, app, 'controllers');
+        for (const file of await safeListFiles(ctrlDir)) {
+            if (!file.endsWith('.ts') || file.endsWith('.d.ts') || file.endsWith('.test.ts'))
+                continue;
+            const full = join(ctrlDir, file);
+            const source = await readFile(full, 'utf8');
+            issues.push(...inspectControllerForNPlusOne(full, source, cwd));
+        }
+    }
+    return { rule: 'n-plus-one', issues };
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+async function safeListFiles(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isFile()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/doctor/reporter.d.ts

@@ -0,0 +1,5 @@
+import type { DoctorResult } from './types.js';
+/** JSON 출력 문자열(끝 개행 없음). fatal 이 있으면 그대로 포함된다. */
+export declare function renderJson(result: DoctorResult): string;
+/** 사람이 읽는 요약(끝 개행 없음). */
+export declare function renderHuman(result: DoctorResult): string;

package/dist/doctor/reporter.js

@@ -0,0 +1,41 @@
+// @gaonjs/cli · doctor · 출력 포맷 (human / JSON) — M9-E · M9-E-Fix
+//
+// human: 사람이 읽는 요약 + 규칙별 이슈 목록.
+// JSON: 자동화(CI)용 · {passed, warnings, errors, fatal?} 그대로 직렬화
+// · 파싱 안정.
+//
+// fatal 이 있으면 규칙 실행 자체가 불가능한 상황 — 크래시 대신 우아한
+// 안내(§7.5.3 · 에러 = 수리 안내서)를 출력한다.
+/** JSON 출력 문자열(끝 개행 없음). fatal 이 있으면 그대로 포함된다. */
+export function renderJson(result) {
+    return JSON.stringify(result);
+}
+/** 사람이 읽는 요약(끝 개행 없음). */
+export function renderHuman(result) {
+    if (result.fatal) {
+        const lines = [];
+        lines.push(`  ✗ gaon doctor · 시작 불가 (${result.fatal.code})`);
+        for (const ln of result.fatal.message.split('\n')) {
+            lines.push(`    ${ln}`);
+        }
+        lines.push(`    ${result.fatal.hint}`);
+        return lines.join('\n');
+    }
+    const lines = [];
+    const passN = result.passed.length;
+    const warnN = result.warnings.length;
+    const errN = result.errors.length;
+    lines.push(`  gaon doctor · 통과 ${passN} · 경고 ${warnN} · 오류 ${errN}`);
+    for (const p of result.passed) {
+        lines.push(`  ✓ ${p.rule} — ${p.message}`);
+    }
+    for (const w of result.warnings) {
+        lines.push(``);
+        lines.push(`  ! [${w.rule}] ${w.message}`);
+    }
+    for (const e of result.errors) {
+        lines.push(``);
+        lines.push(`  ✗ [${e.rule}] ${e.message}`);
+    }
+    return lines.join('\n');
+}

package/dist/doctor/response-mixing.d.ts

@@ -0,0 +1,12 @@
+import type { RuleReport } from './types.js';
+export type ResponseKind = 'render' | 'redirect' | 'json' | 'plain';
+export interface ActionUsage {
+    readonly file: string;
+    readonly action: string;
+    readonly line: number;
+    readonly kinds: readonly ResponseKind[];
+}
+/** 소스 문자열 하나에서 액션별 응답 종류를 수집한다(단위 테스트 진입점). */
+export declare function inspectControllerSource(file: string, source: string): ActionUsage[];
+/** apps/ 를 훑어 응답 혼용 위반을 모두 낸다. */
+export declare function checkResponseMixing(cwd: string): Promise<RuleReport>;

package/dist/doctor/response-mixing.js

@@ -0,0 +1,158 @@
+// @gaonjs/cli · doctor · 응답 혼용 검사 (M3 · errata E-3 §C · M9-E 로 이관)
+//
+// 한 컨트롤러 액션은 render/JSON/redirect 중 한 가지 응답 형태만 낸다.
+// 조건 분기로 섞이면 "이 라우트가 무엇을 돌려주는지" 를 코드를 읽어야
+// 알게 돼 AI 첫 시도 성공률이 떨어진다.
+//
+// 정적 분석: apps/<app>/controllers/*.ts 를 TS AST 로 파싱, 액션마다
+// return 노드에서 최종 응답 형태를 분류(render | redirect | json | plain).
+// 서로 다른 형태가 두 종류 이상이면 위반(error 등급).
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import ts from 'typescript';
+/** 소스 문자열 하나에서 액션별 응답 종류를 수집한다(단위 테스트 진입점). */
+export function inspectControllerSource(file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const usages = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && isControllerCall(node)) {
+            const arg = node.arguments[0];
+            if (arg && ts.isObjectLiteralExpression(arg)) {
+                for (const prop of arg.properties) {
+                    const action = actionName(prop);
+                    if (!action)
+                        continue;
+                    const body = actionBody(prop);
+                    if (!body)
+                        continue;
+                    const kinds = classifyReturns(body);
+                    const { line } = sf.getLineAndCharacterOfPosition(prop.getStart(sf));
+                    usages.push({ file, action, line: line + 1, kinds });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return usages;
+}
+function isControllerCall(node) {
+    const e = node.expression;
+    if (ts.isIdentifier(e) && e.text === 'controller')
+        return true;
+    if (ts.isPropertyAccessExpression(e) && e.name.text === 'controller')
+        return true;
+    return false;
+}
+function actionName(prop) {
+    if (ts.isMethodDeclaration(prop) && ts.isIdentifier(prop.name))
+        return prop.name.text;
+    if (ts.isPropertyAssignment(prop) &&
+        ts.isIdentifier(prop.name) &&
+        (ts.isArrowFunction(prop.initializer) || ts.isFunctionExpression(prop.initializer))) {
+        return prop.name.text;
+    }
+    return undefined;
+}
+function actionBody(prop) {
+    if (ts.isMethodDeclaration(prop))
+        return prop.body;
+    if (ts.isPropertyAssignment(prop)) {
+        if (ts.isArrowFunction(prop.initializer))
+            return prop.initializer.body;
+        if (ts.isFunctionExpression(prop.initializer))
+            return prop.initializer.body;
+    }
+    return undefined;
+}
+function classifyReturns(body) {
+    const kinds = new Set();
+    const classify = (expr) => {
+        if (ts.isAwaitExpression(expr))
+            return classify(expr.expression);
+        if (ts.isCallExpression(expr)) {
+            const c = expr.expression;
+            if (ts.isPropertyAccessExpression(c) && c.expression.kind === ts.SyntaxKind.ThisKeyword) {
+                if (c.name.text === 'render')
+                    return 'render';
+                if (c.name.text === 'redirect')
+                    return 'redirect';
+                if (c.name.text === 'json')
+                    return 'json';
+            }
+            return 'plain';
+        }
+        if (ts.isConditionalExpression(expr)) {
+            kinds.add(classify(expr.whenTrue));
+            kinds.add(classify(expr.whenFalse));
+            return classify(expr.whenTrue);
+        }
+        return 'plain';
+    };
+    const visit = (node) => {
+        if (ts.isReturnStatement(node)) {
+            if (node.expression)
+                kinds.add(classify(node.expression));
+            else
+                kinds.add('plain');
+            return;
+        }
+        if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node))
+            return;
+        ts.forEachChild(node, visit);
+    };
+    if (ts.isBlock(body))
+        visit(body);
+    else
+        kinds.add(classify(body));
+    return [...kinds];
+}
+/** apps/ 를 훑어 응답 혼용 위반을 모두 낸다. */
+export async function checkResponseMixing(cwd) {
+    const appsDir = join(cwd, 'apps');
+    const issues = [];
+    for (const app of await safeListDirs(appsDir)) {
+        const ctrlDir = join(appsDir, app, 'controllers');
+        for (const file of await safeListFiles(ctrlDir)) {
+            if (!file.endsWith('.ts') || file.endsWith('.d.ts') || file.endsWith('.test.ts'))
+                continue;
+            const full = join(ctrlDir, file);
+            const source = await readFile(full, 'utf8');
+            const usages = inspectControllerSource(full, source);
+            for (const u of usages) {
+                if (u.kinds.length < 2)
+                    continue;
+                const rel = relative(cwd, full);
+                issues.push({
+                    rule: 'response-mixing',
+                    level: 'error',
+                    file: rel,
+                    line: u.line,
+                    message: `응답 혼용 감지: ${rel}:${u.line} · 액션 '${u.action}' 이 서로 다른 응답 형태를 섞습니다 (${u.kinds.join(', ')}).\n` +
+                        `→ 한 액션은 한 응답 형태만 유지하세요 (render | JSON | redirect · errata E-3 §C).\n` +
+                        `→ 조건 분기가 필요하면 액션을 둘로 나누거나, JSON 반환에는 예외를 던져 상태 코드를 표현하세요.`,
+                    detail: { action: u.action, kinds: [...u.kinds] },
+                });
+            }
+        }
+    }
+    return { rule: 'response-mixing', issues };
+}
+async function safeListDirs(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+async function safeListFiles(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        return entries.filter((e) => e.isFile()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/doctor/setup.d.ts

@@ -0,0 +1,26 @@
+import type { DoctorFatal } from './types.js';
+export type { DoctorFatal, DoctorFatalCode } from './types.js';
+/**
+ * 프로젝트 마커 4종: gaon.config.ts · domain/ · apps/ · shared/.
+ * 하나라도 있으면 gaon 프로젝트로 인정한다. 모두 없으면 검사할 대상이
+ * 없으므로 우아한 안내 후 종료한다.
+ */
+export declare function detectProject(cwd: string): boolean;
+/**
+ * typescript 모듈이 doctor 가 필요로 하는 compiler API 를 노출하는지
+ * 검사한다. 예: 사용자 프로젝트가 typescript@7 을 받아 오면 default
+ * export 가 `{ version, versionMajorMinor }` 스텁만 담아
+ * `ts.ScriptTarget` 이 undefined → `ts.createSourceFile` 호출 시 크래시.
+ *
+ * 인자 tsMod 는 테스트에서 스텁을 주입하기 위해 기본값을 실 ts 로 둔다.
+ */
+export declare function checkTypeScriptApi(tsMod?: {
+    readonly ScriptTarget?: {
+        readonly ES2022?: number;
+    };
+    readonly createSourceFile?: unknown;
+}): boolean;
+/** 프로젝트 마커 없음 · 우아한 안내. */
+export declare function fatalNoProject(cwd: string): DoctorFatal;
+/** typescript compiler API 미노출 · 우아한 안내. */
+export declare function fatalTsApiMissing(installedVersion: string | undefined): DoctorFatal;

package/dist/doctor/setup.js

@@ -0,0 +1,52 @@
+// @gaonjs/cli · doctor · 사전 검사 (M9-E-Fix · 크래시 하드닝)
+//
+// doctor 는 사용자 프로젝트의 TS 소스를 AST 로 파싱한다. 두 가지 전제:
+//   1) 실제로 gaon 프로젝트여야 한다 (검사 대상이 존재)
+//   2) typescript 컴파일러 API 를 불러올 수 있어야 한다
+// 전제가 깨지면 규칙 실행 중 크래시("Cannot read properties of undefined
+// (reading 'ES2022')" 등) 대신 우아한 안내 메시지 + exit 2 로 대체한다
+// (CLAUDE.md §7.5.3 · 에러 = 수리 안내서).
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import ts from 'typescript';
+/**
+ * 프로젝트 마커 4종: gaon.config.ts · domain/ · apps/ · shared/.
+ * 하나라도 있으면 gaon 프로젝트로 인정한다. 모두 없으면 검사할 대상이
+ * 없으므로 우아한 안내 후 종료한다.
+ */
+export function detectProject(cwd) {
+    const markers = ['gaon.config.ts', 'domain', 'apps', 'shared'];
+    return markers.some((m) => existsSync(join(cwd, m)));
+}
+/**
+ * typescript 모듈이 doctor 가 필요로 하는 compiler API 를 노출하는지
+ * 검사한다. 예: 사용자 프로젝트가 typescript@7 을 받아 오면 default
+ * export 가 `{ version, versionMajorMinor }` 스텁만 담아
+ * `ts.ScriptTarget` 이 undefined → `ts.createSourceFile` 호출 시 크래시.
+ *
+ * 인자 tsMod 는 테스트에서 스텁을 주입하기 위해 기본값을 실 ts 로 둔다.
+ */
+export function checkTypeScriptApi(tsMod = ts) {
+    return (typeof tsMod.createSourceFile === 'function' &&
+        tsMod.ScriptTarget !== undefined &&
+        tsMod.ScriptTarget.ES2022 !== undefined);
+}
+/** 프로젝트 마커 없음 · 우아한 안내. */
+export function fatalNoProject(cwd) {
+    return {
+        code: 'no-project',
+        message: `gaon 프로젝트를 찾지 못했습니다 (cwd: ${cwd}).\n` +
+            `마커(gaon.config.ts · domain/ · apps/ · shared/) 중 하나도 없습니다.`,
+        hint: `→ 'gaon new <name>' 으로 새 프로젝트를 만들거나 실 프로젝트 경로로 이동한 뒤 다시 실행하세요.`,
+    };
+}
+/** typescript compiler API 미노출 · 우아한 안내. */
+export function fatalTsApiMissing(installedVersion) {
+    const v = installedVersion ?? '(알 수 없음)';
+    return {
+        code: 'ts-api-missing',
+        message: `typescript 컴파일러 API 를 불러올 수 없습니다 (설치된 typescript: ${v}).\n` +
+            `doctor 는 typescript 5.x 의 AST 파서(createSourceFile · ScriptTarget)를 사용합니다.`,
+        hint: `→ 프로젝트에 typescript 5.x 를 설치하세요: 'npm i -D typescript@^5.9'.`,
+    };
+}

package/dist/doctor/types.d.ts

@@ -0,0 +1,37 @@
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff';
+export type DoctorLevel = 'passed' | 'warning' | 'error';
+export interface DoctorCheck {
+    readonly rule: DoctorRule;
+    readonly level: DoctorLevel;
+    readonly message: string;
+    /** 위반이 발생한 소스 파일(cwd 기준 상대). passed 는 undefined. */
+    readonly file?: string;
+    /** 1-기반 라인 번호. */
+    readonly line?: number;
+    /** 규칙별 부가 정보(응답 종류 목록 · 관계 이름 · 위반 방향 등). */
+    readonly detail?: Record<string, unknown>;
+}
+export interface DoctorResult {
+    readonly passed: readonly DoctorCheck[];
+    readonly warnings: readonly DoctorCheck[];
+    readonly errors: readonly DoctorCheck[];
+    /**
+     * 사전 검사 실패(프로젝트 없음 · TS API 미노출) 시에만 채워진다.
+     * 존재하면 runCli 는 exit 2 로 종료한다(사용자 오류 · 크래시 아님).
+     */
+    readonly fatal?: DoctorFatal;
+}
+/** 사전 검사 실패 원인 코드. */
+export type DoctorFatalCode = 'no-project' | 'ts-api-missing';
+/** 규칙 실행이 시작될 수 없는 상황. runCli 는 exit 2 로 매핑. */
+export interface DoctorFatal {
+    readonly code: DoctorFatalCode;
+    readonly message: string;
+    readonly hint: string;
+}
+/** 하위 검사 모듈이 상위에서 조립되도록 반환하는 결과 묶음. */
+export interface RuleReport {
+    readonly rule: DoctorRule;
+    readonly issues: readonly DoctorCheck[];
+}
+export declare function makeResult(reports: readonly RuleReport[]): DoctorResult;

package/dist/doctor/types.js

@@ -0,0 +1,34 @@
+// @gaonjs/cli · doctor 공용 타입 (M9-E · M9-E-Fix)
+//
+// 5 검사(response-mixing · n-plus-one · dependency-direction · connections
+// · migration-diff)가 모두 이 DoctorCheck 를 낸다. 상위(runDoctorCommand)는
+// level 로 passed/warnings/errors 로 갈라 담는다. 자동화(CI)는 JSON 을
+// 파싱해 errors.length > 0 이면 fail 로 판단한다.
+//
+// 사전 검사 실패(프로젝트 마커 없음 · TS API 미노출)는 규칙 실행 자체가
+// 불가능한 상황이므로 별도 `fatal` 필드로 표현한다 — runCli 는 이 경우
+// exit 2(사용자 오류)로 매핑한다(M9-E-Fix · CLAUDE.md §7.5.3).
+export function makeResult(reports) {
+    const passed = [];
+    const warnings = [];
+    const errors = [];
+    for (const r of reports) {
+        if (r.issues.length === 0) {
+            passed.push({
+                rule: r.rule,
+                level: 'passed',
+                message: `${r.rule} · 통과`,
+            });
+            continue;
+        }
+        for (const i of r.issues) {
+            if (i.level === 'error')
+                errors.push(i);
+            else if (i.level === 'warning')
+                warnings.push(i);
+            else
+                passed.push(i);
+        }
+    }
+    return { passed, warnings, errors };
+}