@gaonjs/cli 0.2.0 → 0.4.0

package/dist/doctor.d.ts

@@ -1,36 +1,53 @@
-export type ResponseKind = 'render' | 'redirect' | 'json' | 'plain';
-export interface ActionUsage {
-    readonly file: string;
-    readonly action: string;
-    readonly line: number;
-    readonly kinds: readonly ResponseKind[];
+import { type DoctorCheck, type DoctorFatal, type DoctorFatalCode, type DoctorLevel, type DoctorResult, type DoctorRule, type RuleReport } from './doctor/types.js';
+export type { DoctorCheck, DoctorFatal, DoctorFatalCode, DoctorLevel, DoctorResult, DoctorRule, RuleReport, };
+export type { ResponseKind, ActionUsage } from './doctor/response-mixing.js';
+export { inspectControllerSource, checkResponseMixing } from './doctor/response-mixing.js';
+export { inspectControllerForNPlusOne, checkNPlusOne } from './doctor/n-plus-one.js';
+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 { 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[];
 }
+/**
+ * `gaon doctor` 진입점 (M9-E · 확장 · M9-E-Fix 하드닝).
+ *
+ * 반환: DoctorResult({passed, warnings, errors, fatal?}).
+ * exit code 는 진입점(runCli)이 결정한다:
+ *  - result.fatal 이 있으면 → exit 2 (사용자 오류 · 크래시 아님)
+ *  - result.errors.length > 0 → exit 1
+ *  - 그 외 → exit 0
+ *
+ * 사전 검사 2 단계:
+ *  1) detectProject — gaon 프로젝트 마커가 하나도 없으면 fatal:no-project
+ *     로 종료(예: 사용자가 실수로 빈 폴더에서 실행).
+ *  2) checkTypeScriptApi — typescript 컴파일러 API 가 없으면(예: 사용자
+ *     프로젝트가 typescript@7 을 받았을 때 default export 가 스텁이라
+ *     ts.ScriptTarget 이 undefined) fatal:ts-api-missing 로 종료 —
+ *     "Cannot read properties of undefined (reading 'ES2022')" 크래시 대신.
+ * 규칙 실행 중 예외는 각 규칙 단위로 catch → 그 규칙만 error 로 리포트,
+ * 나머지 규칙은 계속 실행(부분 결과 확보).
+ */
+export declare function runDoctorCommand(opts?: DoctorCommandOptions): Promise<DoctorResult>;
 export interface DoctorIssue {
     readonly file: string;
     readonly line: number;
     readonly action: string;
-    readonly kinds: readonly ResponseKind[];
+    readonly kinds: readonly string[];
     readonly message: string;
 }
-export interface DoctorResult {
+export interface LegacyDoctorResult {
     readonly ok: boolean;
     readonly checked: number;
     readonly issues: readonly DoctorIssue[];
 }
-/** 컨트롤러 파일 하나를 검사한다. */
-export declare function inspectControllerSource(file: string, source: string): ActionUsage[];
 /**
- * apps/<app>/controllers/ 를 훑어 응답 혼용 액션을 찾는다. 액션 하나의 kinds
- * 배열이 2종 이상이면 위반(단, 'plain' 하나만 있는 것과 render 만 있는 것은 통과).
- *
- * 명시적 예외: 반환 없는 return(=undefined→204)만 있는 경우는 통과 — void 액션은
- * 흔히 혼용 없이 정상적으로 쓰인다.
+ * 하위 호환: 응답 혼용만 검사해 legacy shape 을 낸다.
+ * appsDir 은 프로젝트의 apps/ 절대 경로. 상위(진입점)는 runDoctorCommand
+ * 를 쓴다.
  */
-export declare function runDoctor(appsDir: string): Promise<DoctorResult>;
-export declare function fileExists(file: string): Promise<boolean>;
-export interface DoctorCommandOptions {
-    readonly cwd?: string;
-    readonly json?: boolean;
-}
-/** `gaon doctor` 진입점. */
-export declare function runDoctorCommand(opts?: DoctorCommandOptions): Promise<number>;
+export declare function runDoctor(appsDir: string): Promise<LegacyDoctorResult>;

package/dist/doctor.js

@@ -1,218 +1,147 @@
 /**
- * @gaonjs/cli · `gaon doctor` — 정적 검사 (M3 · errata E-3)
+ * @gaonjs/cli · `gaon doctor` — 정적 검사 (M9-E · CLI DX 완성)
  *
- * v1 첫 검사 항목: **응답 혼용 금지**. 한 컨트롤러 액션은 render/JSON/
- * redirect 중 한 가지 응답 형태만 낼 수 있다(§C · The One Way). 조건 분기로
- * 섞으면 "이 라우트가 무엇을 돌려주는지"가 코드를 읽어야 알게 돼 AI 첫 시도
- * 성공률이 떨어진다.
+ * 5 검사를 조립한다:
+ *  1) response-mixing (errata E-3 §C · 라이브)
+ *  2) n-plus-one (errata E-4 (e))
+ *  3) dependency-direction (CLAUDE.md §5 · 4 규칙)
+ *  4) connections (v0.15 §4.5)
+ *  5) migration-diff (최소 감지 · 상세는 M9-D)
  *
- * 검사 방법(정적 분석):
- *  · apps/<app>/controllers/*.ts 를 TS AST 로 파싱.
- *  · export default controller({ ... }) 의 액션 함수마다 return 노드에서
- *    최종 응답 형태를 분류(render | redirect | json | plain).
- *  · 서로 다른 형태가 두 종류 이상이면 위반.
- *  · this.render/this.redirect/this.json/평범한 객체 반환의 4종을 구별한다.
+ * 각 검사는 순수 함수(cwd → RuleReport). 상위 runDoctorCommand 가 조립해
+ * DoctorResult 로 낸다. --json 은 자동화(CI)를 위해 반드시 파싱 가능한
+ * 구조를 유지한다(CLAUDE.md §4 · 모든 명령 --json).
  *
- * 위반 시: 파일·라인·액션 이름 + 감지된 형태 목록 + "→ 한 액션은 한 응답
- * 형태만 유지하세요(errata E-3 §C)" 안내를 낸다.
- *
- * 나머지 doctor 검사(의존 방향 §1-5, 커넥션 §4.5 등)는 후속 마일스톤에서
- * 이 모듈에 규칙을 얹는다.
+ * 하위 호환: 기존 응답 혼용 API(`inspectControllerSource`·`runDoctor`)는
+ * 그대로 export — 기존 테스트가 계속 동작한다.
  */
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { join, relative, resolve } from 'node:path';
+import { resolve } 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;
-}
-/** 액션 본문의 모든 return 표현식을 응답 형태로 분류하고 중복을 제거해 반환한다. */
-function classifyReturns(body) {
-    const kinds = new Set();
-    const classify = (expr) => {
-        // await x → x 로 되짚어 본다.
-        if (ts.isAwaitExpression(expr))
-            return classify(expr.expression);
-        // this.render / this.redirect / this.json
-        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';
-            }
-            // 삼항·논리 연산 결과라도 호출식이 나오면 함수 반환값에 의존 — 보수적으로 plain.
-            return 'plain';
-        }
-        // 삼항 연산자 — 양쪽 각각 분류
-        if (ts.isConditionalExpression(expr)) {
-            kinds.add(classify(expr.whenTrue));
-            kinds.add(classify(expr.whenFalse));
-            return classify(expr.whenTrue); // 반환값(대표) — Set 에 이미 다 넣음
-        }
-        // 그 외(객체·배열·literal·식별자 등) → plain(JSON 액션)
-        return 'plain';
-    };
-    const visit = (node) => {
-        if (ts.isReturnStatement(node)) {
-            if (node.expression)
-                kinds.add(classify(node.expression));
-            else
-                kinds.add('plain'); // 빈 return 은 undefined → 204 (plain 으로 취급, 혼용 검사에서만 의미)
-            return; // return 안의 하위 함수는 다른 스코프 — 이 return 만 잡는다
-        }
-        // 중첩 함수/화살표는 다른 스코프 — 파고들지 않는다.
-        if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node))
-            return;
-        ts.forEachChild(node, visit);
-    };
-    // 표현식 본문 화살표(=> render(...))는 body 가 표현식.
-    if (ts.isBlock(body))
-        visit(body);
-    else
-        kinds.add(classify(body));
-    return [...kinds];
-}
+import { checkResponseMixing } from './doctor/response-mixing.js';
+import { checkNPlusOne } from './doctor/n-plus-one.js';
+import { checkDependencyDirection } from './doctor/dependency-direction.js';
+import { checkConnections } from './doctor/connections.js';
+import { checkMigrationDiff } from './doctor/migration-diff.js';
+import { renderHuman, renderJson } from './doctor/reporter.js';
+import { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
+import { makeResult, } from './doctor/types.js';
+export { inspectControllerSource, checkResponseMixing } from './doctor/response-mixing.js';
+export { inspectControllerForNPlusOne, checkNPlusOne } from './doctor/n-plus-one.js';
+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 { renderHuman, renderJson } from './doctor/reporter.js';
+export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
+/**
+ * 실행할 검사 이름. 지정 없음(undefined) = 5개 모두.
+ */
+const ALL_RULES = [
+    'response-mixing',
+    'n-plus-one',
+    'dependency-direction',
+    'connections',
+    'migration-diff',
+];
+const CHECKERS = {
+    'response-mixing': checkResponseMixing,
+    'n-plus-one': checkNPlusOne,
+    'dependency-direction': checkDependencyDirection,
+    connections: checkConnections,
+    'migration-diff': checkMigrationDiff,
+};
 /**
- * apps/<app>/controllers/ 를 훑어 응답 혼용 액션을 찾는다. 액션 하나의 kinds
- * 배열이 2종 이상이면 위반(단, 'plain' 하나만 있는 것과 render 만 있는 것은 통과).
+ * `gaon doctor` 진입점 (M9-E · 확장 · M9-E-Fix 하드닝).
+ *
+ * 반환: DoctorResult({passed, warnings, errors, fatal?}).
+ * exit code 는 진입점(runCli)이 결정한다:
+ *  - result.fatal 이 있으면 → exit 2 (사용자 오류 · 크래시 아님)
+ *  - result.errors.length > 0 → exit 1
+ *  - 그 외 → exit 0
  *
- * 명시적 예외: 반환 없는 return(=undefined→204)만 있는 경우는 통과 — void 액션은
- * 흔히 혼용 없이 정상적으로 쓰인다.
+ * 사전 검사 2 단계:
+ *  1) detectProject — gaon 프로젝트 마커가 하나도 없으면 fatal:no-project
+ *     로 종료(예: 사용자가 실수로 빈 폴더에서 실행).
+ *  2) checkTypeScriptApi — typescript 컴파일러 API 가 없으면(예: 사용자
+ *     프로젝트가 typescript@7 을 받았을 때 default export 가 스텁이라
+ *     ts.ScriptTarget 이 undefined) fatal:ts-api-missing 로 종료 —
+ *     "Cannot read properties of undefined (reading 'ES2022')" 크래시 대신.
+ * 규칙 실행 중 예외는 각 규칙 단위로 catch → 그 규칙만 error 로 리포트,
+ * 나머지 규칙은 계속 실행(부분 결과 확보).
  */
-export async function runDoctor(appsDir) {
-    const issues = [];
-    let checked = 0;
-    const apps = await safeListDirs(appsDir);
-    for (const app of apps) {
-        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);
-            checked += usages.length;
-            for (const u of usages) {
-                if (u.kinds.length < 2)
-                    continue;
-                // 'plain' 이 유일한 다른 형태이면서 실제 return 문에 undefined 만 있는 경우는 걸러야
-                // 하지만, 액션이 render|json 를 하다가 조건에 따라 undefined 반환하면 혼용이다. 유지.
-                const rel = relative(process.cwd(), full);
-                issues.push({
-                    file: rel,
-                    line: u.line,
-                    action: u.action,
-                    kinds: u.kinds,
-                    message: `[doctor] 응답 혼용 감지: ${rel}:${u.line} · 액션 '${u.action}' 이 서로 다른 응답 형태를 섞습니다 (${u.kinds.join(', ')}).\n` +
-                        `→ 한 액션은 한 응답 형태만 유지하세요 (render | JSON | redirect · errata E-3 §C).\n` +
-                        `→ 조건 분기가 필요하면 액션을 둘로 나누거나, JSON 반환에는 예외를 던져 상태 코드를 표현하세요.`,
-                });
-            }
-        }
-    }
-    return { ok: issues.length === 0, checked, 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 [];
-    }
-}
-// stat 은 API 표면 유지용 — 파일 존재 확인이 필요할 때 씀.
-export async function fileExists(file) {
-    try {
-        await stat(file);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/** `gaon doctor` 진입점. */
 export async function runDoctorCommand(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
-    const appsDir = resolve(cwd, 'apps');
-    const result = await runDoctor(appsDir);
-    if (opts.json) {
-        process.stdout.write(JSON.stringify(result) + '\n');
+    const root = resolve(cwd);
+    const json = opts.json ?? false;
+    // 1) 프로젝트 마커 검사
+    if (!detectProject(root)) {
+        const result = {
+            passed: [],
+            warnings: [],
+            errors: [],
+            fatal: fatalNoProject(root),
+        };
+        process.stdout.write((json ? renderJson(result) : renderHuman(result)) + '\n');
+        return result;
+    }
+    // 2) typescript compiler API 검사
+    if (!checkTypeScriptApi()) {
+        const installed = ts.version;
+        const result = {
+            passed: [],
+            warnings: [],
+            errors: [],
+            fatal: fatalTsApiMissing(installed),
+        };
+        process.stdout.write((json ? renderJson(result) : renderHuman(result)) + '\n');
+        return result;
     }
-    else {
-        process.stdout.write(`  검사한 액션: ${result.checked}개\n`);
-        if (result.ok) {
-            process.stdout.write(`  ✓ 응답 혼용 없음\n`);
+    const rules = opts.checks && opts.checks.length ? opts.checks : ALL_RULES;
+    const reports = [];
+    for (const rule of rules) {
+        const fn = CHECKERS[rule];
+        try {
+            reports.push(await fn(root));
         }
-        else {
-            process.stdout.write(`  ✗ 응답 혼용 ${result.issues.length}건\n`);
-            for (const i of result.issues)
-                process.stdout.write(i.message + '\n');
+        catch (err) {
+            // 규칙 하나가 크래시해도 나머지 규칙 실행은 계속한다. 사용자는
+            // 크래시 대신 어느 규칙이 왜 실패했는지 안내받는다.
+            const msg = err instanceof Error ? err.message : String(err);
+            reports.push({
+                rule,
+                issues: [
+                    {
+                        rule,
+                        level: 'error',
+                        message: `${rule} 검사 중 예외 발생: ${msg}\n` +
+                            `→ 나머지 규칙만 임시로 실행하려면 '--check=<다른 규칙>' 를 쓰세요.`,
+                        detail: { thrown: msg },
+                    },
+                ],
+            });
         }
     }
-    return result.ok ? 0 : 1;
+    const result = makeResult(reports);
+    const out = json ? renderJson(result) : renderHuman(result);
+    process.stdout.write(out + '\n');
+    return result;
+}
+/**
+ * 하위 호환: 응답 혼용만 검사해 legacy shape 을 낸다.
+ * appsDir 은 프로젝트의 apps/ 절대 경로. 상위(진입점)는 runDoctorCommand
+ * 를 쓴다.
+ */
+export async function runDoctor(appsDir) {
+    // apps/ 의 부모를 cwd 로 간주(관례).
+    const cwd = resolve(appsDir, '..');
+    const report = await checkResponseMixing(cwd);
+    const issues = report.issues.map((i) => ({
+        file: i.file ?? '',
+        line: i.line ?? 0,
+        action: String(i.detail?.action ?? ''),
+        kinds: i.detail?.kinds ?? [],
+        message: i.message,
+    }));
+    // checked 는 컨트롤러 액션 수 — 응답 혼용 검사가 순회한 액션 수와 정합.
+    // 하위 호환 목적으로 issues 수로 대체(정확한 checked 는 신규 API 를 쓰라).
+    return { ok: issues.length === 0, checked: issues.length, issues };
 }

package/dist/index.d.ts

@@ -1,11 +1,18 @@
-export { runDevCommand, startDev, resolveDevLayout, type DevDeps, type DevLayout, type DevApp, type DevEvent, type DevHandle, type DevCommandOptions, } from "./dev.js";
+import { type DoctorRule } from "./doctor.js";
+export { startDev, resolveDevLayout, type DevDeps, type DevLayout, type DevApp, type DevEvent, type DevHandle, } from "./dev.js";
+export { runDevCommand, type DevCommandOptions } from "./commands/dev.js";
+export { createDevConsole, findComposeFile, isDockerAvailable, inspectCompose, composeUp, composeDown, ensureInfra, startTscWatchers, killChild, startRestartWatcher, isRestartChange, resolveWatchRoots, type DevConsole, type DevConsoleOptions, type DevSource, type DevLevel, type ComposeStatus, type ComposeUpOptions, type EnsureInfraResult, type DockerLocateOptions, type TscWatcherOptions, type TscWatcherHandle, type RestartWatcherOptions, type RestartWatcherHandle, } from "./dev/index.js";
 export { runCheck, runCheckCommand, type CheckDeps, type CheckResult, type TypecheckResult, type CheckCommandOptions, } from "./check.js";
 export { writeAuthScaffold, authScaffoldFiles, patchRoutes, runGenerateAuthCommand, type AuthScaffoldOptions, type ScaffoldFile, type ScaffoldResult, type GenerateAuthOptions, } from "./generate.js";
+export { runGenerateCommand, planScaffold, parseGenerateArgs, type GenerateType, type GenerateOptions, type GenerateResult, } from "./commands/g.js";
 export { runHubCommand, type HubCommandOptions } from "./hub.js";
+export { runServeCommand, type ServeCommandOptions } from "./serve.js";
 export { runWorkCommand, type WorkCommandOptions } from "./work.js";
 export { runJobsCommand, type JobsCommandOptions } from "./jobs.js";
 export { runDbSeedCommand, loadSeed, type DbSeedOptions, type DbSeedResult } from "./db.js";
-export { runDoctorCommand, runDoctor, inspectControllerSource, type DoctorResult, type DoctorIssue, type ActionUsage, type ResponseKind, type DoctorCommandOptions, } from "./doctor.js";
+export { runDbCommand, type DbSubcommand, type DbCommandOptions, } from "./commands/db.js";
+export { runDbDiff, runDbMigrate, runDbReset, resolveDbTarget, type DbDiffOptions, type DbDiffResult, type DbMigrateOptions, type DbMigrateResult, type DbResetOptions, type DbResetResult, type ResolveDbOptions, type ResolvedDbTarget, } from "./db/index.js";
+export { runDoctorCommand, runDoctor, inspectControllerSource, checkResponseMixing, checkNPlusOne, checkDependencyDirection, checkConnections, checkMigrationDiff, renderHuman, renderJson, type DoctorResult, type DoctorCheck, type DoctorLevel, type DoctorRule, type RuleReport, type DoctorIssue, type LegacyDoctorResult, type ActionUsage, type ResponseKind, type DoctorCommandOptions, } from "./doctor.js";
 export { loadDomain, type LoadedDomain } from "./domain.js";
 export interface RoadmapReport {
     readonly name: "gaon";
@@ -27,5 +34,10 @@ export declare function renderRoadmap(version?: string): string;
 export interface RunOptions {
     readonly version?: string;
 }
+/**
+ * `gaon doctor --check=<이름>[,<이름>...]` 파싱(M9-E).
+ * 지정 없음(undefined) = 5 검사 모두 실행. 알 수 없는 이름은 무시(안전).
+ */
+export declare function parseDoctorChecks(argv: readonly string[]): DoctorRule[] | undefined;
 /** CLI 진입점. argv 는 실행 인자(process.argv.slice(2))를 받는다. */
 export declare function runCli(argv: readonly string[], opts?: RunOptions): void;