@gaonjs/cli 0.2.0 → 0.3.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 출력 문자열(끝 개행 없음). */
+export declare function renderJson(result: DoctorResult): string;
+/** 사람이 읽는 요약(끝 개행 없음). */
+export declare function renderHuman(result: DoctorResult): string;

package/dist/doctor/reporter.js

@@ -0,0 +1,28 @@
+// @gaonjs/cli · doctor · 출력 포맷 (human / JSON) — M9-E
+//
+// human: 사람이 읽는 요약 + 규칙별 이슈 목록.
+// JSON: 자동화(CI)용 · {passed, warnings, errors} 그대로 직렬화 · 파싱 안정.
+/** JSON 출력 문자열(끝 개행 없음). */
+export function renderJson(result) {
+    return JSON.stringify(result);
+}
+/** 사람이 읽는 요약(끝 개행 없음). */
+export function renderHuman(result) {
+    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/types.d.ts

@@ -0,0 +1,24 @@
+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[];
+}
+/** 하위 검사 모듈이 상위에서 조립되도록 반환하는 결과 묶음. */
+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,30 @@
+// @gaonjs/cli · doctor 공용 타입 (M9-E)
+//
+// 5 검사(response-mixing · n-plus-one · dependency-direction · connections
+// · migration-diff)가 모두 이 DoctorCheck 를 낸다. 상위(runDoctorCommand)는
+// level 로 passed/warnings/errors 로 갈라 담는다. 자동화(CI)는 JSON 을
+// 파싱해 errors.length > 0 이면 fail 로 판단한다.
+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 };
+}

package/dist/doctor.d.ts

@@ -1,36 +1,39 @@
-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 DoctorLevel, type DoctorResult, type DoctorRule, type RuleReport } from './doctor/types.js';
+export type { DoctorCheck, 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 interface DoctorCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+    readonly checks?: readonly DoctorRule[];
 }
+/**
+ * `gaon doctor` 진입점 (M9-E · 확장).
+ *
+ * 반환: DoctorResult({passed, warnings, errors}).
+ * exit code 는 진입점(runCli)이 errors.length 로 결정한다.
+ */
+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>;