@gaonjs/cli 0.47.0 → 0.52.0

package/dist/commands/check.d.ts

@@ -52,7 +52,7 @@ export interface CheckReport {
 /**
  * `gaon check` 진입점. 검사 전에 .gaon 을 재생성(규칙 3)한 뒤 각 단계를
  * 순서대로 실행하고, 하나라도 실패하면 exit 1. --only 지정 시 그 단계만
- * 실행. --include-doctor 시 doctor 추가.
+ * 실행. doctor 는 기본 포함(결정 157) — --no-doctor 로만 뺀다.
  *
  * §9 실 인프라 · 목업 X — 실 spawn 으로 검증한다.
  */

package/dist/commands/check.js

@@ -271,7 +271,7 @@ async function regenerateGaon(cwd) {
 /**
  * `gaon check` 진입점. 검사 전에 .gaon 을 재생성(규칙 3)한 뒤 각 단계를
  * 순서대로 실행하고, 하나라도 실패하면 exit 1. --only 지정 시 그 단계만
- * 실행. --include-doctor 시 doctor 추가.
+ * 실행. doctor 는 기본 포함(결정 157) — --no-doctor 로만 뺀다.
  *
  * §9 실 인프라 · 목업 X — 실 spawn 으로 검증한다.
  */

package/dist/commands/test.js

@@ -106,7 +106,11 @@ async function provisionTestDatabases(cwd, json, onOutput) {
                 connectionOverride: testCfg,
             });
             if (res.exitCode !== 0) {
-                if (!json)
+                // 결정 360: json 모드도 구조화 에러를 낸다 — 이전엔 이 분기만 0 바이트로
+                // exit 1 이라 자동화가 실패 원인을 전혀 못 받았다(catch 분기와 비대칭).
+                if (json)
+                    writeOut(JSON.stringify({ ok: false, kind: 'provision', db: key, error: res.text }) + '\n');
+                else
                     writeErr(`  ✗ 테스트 DB '${key}' 마이그레이션 실패\n${res.text}\n`);
                 return false;
             }
@@ -211,18 +215,27 @@ export async function runTestCommand(args = [], opts = {}) {
     else {
         writeOut(`  gaon test · ${cmd} ${spawnArgs.join(' ')} (scope=${scope})\n`);
     }
+    // 결정 360: --json 은 stdout 이 순수 JSON 라인이어야 한다(결정 269 check 와 대칭).
+    // 이전엔 json 모드도 stdio:'inherit' 라 vitest 사람용 출력이 JSON 라인 사이에 섞여
+    // `gaon test --json | jq` 류 자동화가 깨졌다. 자식 출력은 {kind:'output'} 라인으로 감싼다.
+    const jsonPipe = json && !capture;
     const exitCode = await new Promise((resolvePromise) => {
         // capture(MCP) 모드는 자식 출력을 파이프로 모아 싱크로 흘린다(도구 응답에 담기).
-        // CLI 경로(미지정)는 vitest 컬러 출력·리포터를 그대로 보이게 stdio 를 상속한다.
+        // CLI 사람 경로(미지정)는 vitest 컬러 출력·리포터를 그대로 보이게 stdio 를 상속한다.
         const child = spawn(cmd, spawnArgs, {
             cwd,
             env: testEnv,
-            stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+            stdio: capture || jsonPipe ? ['ignore', 'pipe', 'pipe'] : 'inherit',
         });
         if (capture) {
             child.stdout?.on('data', (d) => opts.onOutput(d.toString('utf8')));
             child.stderr?.on('data', (d) => opts.onOutput(d.toString('utf8')));
         }
+        else if (jsonPipe) {
+            const emit = (stream) => (d) => writeOut(JSON.stringify({ kind: 'output', stream, chunk: d.toString('utf8') }) + '\n');
+            child.stdout?.on('data', emit('stdout'));
+            child.stderr?.on('data', emit('stderr'));
+        }
         child.on('error', (err) => {
             writeErr(`  ✗ gaon test spawn 실패: ${String(err)}\n`);
             resolvePromise(127);

package/dist/db/journal.d.ts

@@ -1,4 +1,5 @@
 import { type Kysely } from 'kysely';
+import { type AdapterName } from '@gaonjs/data';
 export type MigrationKind = 'file' | 'schema';
 export interface JournalEntry {
     readonly id: string;
@@ -17,7 +18,7 @@ export interface JournalEntry {
  * pg 는 count 를 bigint(문자열)로, mysql 은 number 로 돌려주므로 `Number()` 로 통일한다
  * (양 방언 공통 · 결정 268).
  */
-export declare function journalExists(db: Kysely<any>): Promise<boolean>;
+export declare function journalExists(db: Kysely<any>, adapter?: AdapterName): Promise<boolean>;
 /**
  * _gaon_migrations 를 만든다(존재하면 no-op). id/kind/applied_at/db_key/
  * statements/summary/down_sql — text·varchar·timestamp·integer 는 postgres·
@@ -35,7 +36,7 @@ export interface RecordArgs {
 /** 이력 한 행을 남긴다. 호출자가 트랜잭션(trx)을 넘기면 그 안에서 실행된다. */
 export declare function recordEntry(db: Kysely<any>, e: RecordArgs): Promise<void>;
 /** 가장 최근 적용된 이력(롤백 대상). 원장 미존재 시 undefined. */
-export declare function latestEntry(db: Kysely<any>): Promise<JournalEntry | undefined>;
+export declare function latestEntry(db: Kysely<any>, adapter?: AdapterName): Promise<JournalEntry | undefined>;
 /** kind='file' 로 적용된 파일명 집합. 원장 미존재 시 빈 집합. */
-export declare function appliedFileMigrations(db: Kysely<any>): Promise<Set<string>>;
+export declare function appliedFileMigrations(db: Kysely<any>, adapter?: AdapterName): Promise<Set<string>>;
 export declare function deleteEntry(db: Kysely<any>, id: string): Promise<void>;

package/dist/db/journal.js

@@ -17,12 +17,23 @@ import { MIGRATIONS_TABLE } from '@gaonjs/data';
  * pg 는 count 를 bigint(문자열)로, mysql 은 number 로 돌려주므로 `Number()` 로 통일한다
  * (양 방언 공통 · 결정 268).
  */
-export async function journalExists(db) {
-    const rows = await sql `
-    select count(*) as n
-    from information_schema.tables
-    where table_name = ${MIGRATIONS_TABLE}
-  `.execute(db);
+export async function journalExists(db, adapter = 'postgres') {
+    // 결정 326: mysql/mariadb 의 information_schema.tables 는 **서버 전체(모든 database)** 를
+    // 보므로 같은 서버 다른 DB 의 _gaon_migrations 에 오탐했다 — 존재 오판 뒤
+    // appliedFileMigrations 가 없는 테이블을 select 해 migrate/status 가 죽는다(공유 dev 서버
+    // 현실 시나리오) → database() 로 현재 DB 에 한정한다. pg 는 카탈로그가 database 단위라
+    // 종전대로 둔다(스키마('public') 한정은 커스텀 search_path 프로젝트를 깨서 안 한다).
+    const rows = adapter === 'mysql'
+        ? await sql `
+          select count(*) as n
+          from information_schema.tables
+          where table_name = ${MIGRATIONS_TABLE} and table_schema = database()
+        `.execute(db)
+        : await sql `
+          select count(*) as n
+          from information_schema.tables
+          where table_name = ${MIGRATIONS_TABLE}
+        `.execute(db);
     const first = rows.rows[0];
     return first ? Number(first.n) > 0 : false;
 }
@@ -53,8 +64,8 @@ export async function recordEntry(db, e) {
   `.execute(db);
 }
 /** 가장 최근 적용된 이력(롤백 대상). 원장 미존재 시 undefined. */
-export async function latestEntry(db) {
-    if (!(await journalExists(db)))
+export async function latestEntry(db, adapter = 'postgres') {
+    if (!(await journalExists(db, adapter)))
         return undefined;
     const rows = await sql `
     select id, kind, db_key, statements, summary, down_sql, applied_at
@@ -65,8 +76,8 @@ export async function latestEntry(db) {
     return rows.rows[0];
 }
 /** kind='file' 로 적용된 파일명 집합. 원장 미존재 시 빈 집합. */
-export async function appliedFileMigrations(db) {
-    if (!(await journalExists(db)))
+export async function appliedFileMigrations(db, adapter = 'postgres') {
+    if (!(await journalExists(db, adapter)))
         return new Set();
     const rows = await sql `
     select id from ${sql.ref(MIGRATIONS_TABLE)} where kind = 'file'

package/dist/db/migrate.d.ts

@@ -1,4 +1,4 @@
-import { type ConnectionConfig } from '@gaonjs/data';
+import { type MigrationOp, type ConnectionConfig } from '@gaonjs/data';
 import { listMigrationFiles } from './replay.js';
 export interface DbMigrateOptions {
     readonly cwd: string;
@@ -16,6 +16,8 @@ export interface DbMigrateResult {
     readonly text: string;
     readonly json: unknown;
 }
+/** drop 계열 부속 op 을 사람이 읽는 한 줄로 — 크게 알리는 note 용(status 도 재사용 · 결정 326). */
+export declare function describeDeferred(op: MigrationOp): string;
 /**
  * `gaon db migrate` — 진짜 apply(합성형: replay → schema-diff). 실 DB 필요(§9).
  */

package/dist/db/migrate.js

@@ -17,8 +17,8 @@ import { computeMigration, renderUp, renderDown, summarizeOp, DEFERRED_DROP_KIND
 import { resolveDbTarget } from './resolve.js';
 import { ensureJournal, journalExists, recordEntry } from './journal.js';
 import { listMigrationFiles, replayPending, rollbackLast } from './replay.js';
-/** drop 계열 부속 op 을 사람이 읽는 한 줄로 — 크게 알리는 note 용. */
-function describeDeferred(op) {
+/** drop 계열 부속 op 을 사람이 읽는 한 줄로 — 크게 알리는 note 용(status 도 재사용 · 결정 326). */
+export function describeDeferred(op) {
     switch (op.kind) {
         case 'dropUnique':
             return `unique(${op.name}: ${op.columns.join(', ')})`;
@@ -116,7 +116,7 @@ export async function runDbMigrate(opts) {
             };
         }
         // baseline 감지 — journal 이 없는데 createTable 이 포함 → 안내(§7.5.3).
-        const hadJournal = await journalExists(target.db);
+        const hadJournal = await journalExists(target.db, target.adapter);
         const hasCreate = plan.ops.some((o) => o.kind === 'createTable');
         const baselineNote = !hadJournal && hasCreate
             ? `  ℹ 최초 마이그레이션(_gaon_migrations 미존재) — 이 배치가 baseline 이 됩니다.\n` +

package/dist/db/replay.js

@@ -66,7 +66,7 @@ export async function replayPending(opts) {
     const all = listMigrationFiles(opts.cwd);
     if (all.length === 0)
         return { applied: [], pending: [], all: [] };
-    const done = await appliedFileMigrations(opts.db);
+    const done = await appliedFileMigrations(opts.db, opts.adapter);
     const pending = all.filter((f) => !done.has(f));
     if (opts.dryRun || pending.length === 0) {
         return { applied: [], pending, all };
@@ -104,7 +104,7 @@ export async function replayPending(opts) {
  * 되돌린 뒤 이력 행을 지운다. --dry-run 은 대상만 보고 실행하지 않는다.
  */
 export async function rollbackLast(opts) {
-    const entry = await latestEntry(opts.db);
+    const entry = await latestEntry(opts.db, opts.adapter);
     if (!entry)
         return { rolledBack: null, kind: null };
     if (opts.dryRun)

package/dist/db/status.js

@@ -2,9 +2,10 @@
 //
 // db/migrations/*.ts 각각의 적용/미적용과, 스키마↔DB 사이에 아직 반영 안 된
 // 변경(schema drift) 수를 함께 보여준다. 아무것도 실행하지 않는다.
-import { computeMigration } from '@gaonjs/data';
+import { computeMigration, summarizeOp, DEFERRED_DROP_KINDS } from '@gaonjs/data';
 import { resolveDbTarget } from './resolve.js';
 import { appliedFileMigrations } from './journal.js';
+import { describeDeferred } from './migrate.js';
 import { listMigrationFiles } from './replay.js';
 export async function runDbStatus(opts) {
     const target = await resolveDbTarget({
@@ -14,7 +15,7 @@ export async function runDbStatus(opts) {
     });
     try {
         const files = listMigrationFiles(opts.cwd);
-        const done = await appliedFileMigrations(target.db);
+        const done = await appliedFileMigrations(target.db, target.adapter);
         const migrations = files.map((f) => ({ file: `db/migrations/${f}`, applied: done.has(f) }));
         const pendingFiles = migrations.filter((m) => !m.applied).length;
         // migrate 는 스키마에 없는 테이블을 자동 DROP 하지 않으므로(결정 39 · §4.8)
@@ -23,7 +24,11 @@ export async function runDbStatus(opts) {
         const extraTables = plan.ops
             .filter((o) => o.kind === 'dropTable')
             .map((o) => o.name);
-        const schemaChanges = plan.ops.length - extraTables.length;
+        // 결정 326: deferred aux drop(제약·인덱스·기본값 제거)도 migrate 가 자동 적용하지
+        // 않는다(결정 220) — drift 로 세면 "'gaon db migrate' 로 반영하세요" 가 영원히 안
+        // 지워지는 거짓 안내가 된다. dropTable 과 같은 축의 참고 항목으로 분리한다.
+        const deferredDrops = plan.ops.filter((o) => o.kind !== 'dropTable' && DEFERRED_DROP_KINDS.has(o.kind));
+        const schemaChanges = plan.ops.length - extraTables.length - deferredDrops.length;
         const lines = [];
         if (migrations.length === 0) {
             lines.push(`  [${opts.dbKey}] 마이그레이션 파일 없음 (db/migrations/).`);
@@ -42,6 +47,10 @@ export async function runDbStatus(opts) {
         if (extraTables.length > 0) {
             lines.push(`  참고: 스키마에 없는 테이블 ${extraTables.length}개(자동 DROP 안 함): ${extraTables.join(', ')}`);
         }
+        if (deferredDrops.length > 0) {
+            lines.push(`  참고: 스키마에서 사라진 제약·인덱스·기본값 ${deferredDrops.length}개(자동 제거 안 함 — ` +
+                `'gaon db diff' 의 down SQL 로 손작성 마이그): ${deferredDrops.map(describeDeferred).join(', ')}`);
+        }
         return {
             exitCode: 0,
             text: lines.join('\n'),
@@ -52,6 +61,7 @@ export async function runDbStatus(opts) {
                 pendingFiles,
                 schemaChanges,
                 extraTables,
+                deferredDrops: deferredDrops.map(summarizeOp),
             },
         };
     }

package/dist/dev.d.ts

@@ -13,6 +13,8 @@ export interface DevLayout {
     readonly apps: readonly DevApp[];
     /** locales/ (없으면 undefined — messages 축 생략 · 결정 158 · W2). */
     readonly localesDir?: string;
+    /** 기준 로케일 = config i18n.fallbackLng (정적 분석 · 결정 352 · 못 읽으면 undefined). */
+    readonly messagesBaseLng?: string;
     /** .gaon/messages.d.ts */
     readonly messagesOut: string;
     /** 프론트 진입(index.html)이 있는 앱이 하나라도 있는가 — env 축 적용 조건(결정 198). */
@@ -26,8 +28,8 @@ export interface DevDeps {
     readonly layout: DevLayout;
     regenerateTables(schemaDir: string, out: string): Promise<unknown>;
     regenerateRoutes(appDir: string, out: string): Promise<unknown>;
-    /** locales/ → .gaon/messages.d.ts (결정 158 · W2). i18n 축을 쓰는 호출자만 준다. */
-    regenerateMessages?(localesDir: string, out: string): unknown;
+    /** locales/ → .gaon/messages.d.ts (결정 158 · W2 · 기준 로케일 = 결정 352). i18n 축을 쓰는 호출자만 준다. */
+    regenerateMessages?(localesDir: string, out: string, baseLng?: string): unknown;
     /** `.env` → .gaon/env.d.ts (결정 198 · F-9 ②). env 축을 쓰는 호출자만 준다. */
     regenerateEnv?(envFile: string, out: string): unknown;
     watch(dir: string, opts: WatchOptions): WatchHandle;
@@ -58,8 +60,8 @@ export declare function startDev(deps: DevDeps): Promise<DevHandle>;
 export interface RegenDeps {
     regenerateTables(schemaDir: string, out: string): Promise<unknown>;
     regenerateRoutes(appDir: string, out: string): Promise<unknown>;
-    /** locales/ → .gaon/messages.d.ts (결정 158 · W2). i18n 축을 쓰는 호출자만 준다. */
-    regenerateMessages?(localesDir: string, out: string): unknown;
+    /** locales/ → .gaon/messages.d.ts (결정 158 · W2 · 기준 로케일 = 결정 352). i18n 축을 쓰는 호출자만 준다. */
+    regenerateMessages?(localesDir: string, out: string, baseLng?: string): unknown;
     /** `.env` → .gaon/env.d.ts (결정 198 · F-9 ②). env 축을 쓰는 호출자만 준다. */
     regenerateEnv?(envFile: string, out: string): unknown;
 }

package/dist/dev.js

@@ -13,6 +13,7 @@
  */
 import { readdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { analyzeProjectI18n } from './i18n-config.js';
 /** locales/*.json 변경(메시지 카탈로그) — messages.d.ts 재생성 트리거. */
 const isMessagesChange = (f) => !f.includes('.gaon') && f.endsWith('.json');
 const isSchemaChange = (f) => f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.test.ts') && !f.includes('.gaon');
@@ -39,7 +40,7 @@ export async function startDev(deps) {
     }
     // 결정 158(W2): locales/ → messages.d.ts.
     if (layout.localesDir && deps.regenerateMessages) {
-        await deps.regenerateMessages(layout.localesDir, layout.messagesOut);
+        await deps.regenerateMessages(layout.localesDir, layout.messagesOut, layout.messagesBaseLng);
         deps.log({ kind: 'regen', target: 'messages' });
     }
     // 결정 198(F-9 ②): 프론트 앱이 있으면 .env → env.d.ts(VITE_* 타입 브리지). `.env` 부재는
@@ -79,7 +80,7 @@ export async function startDev(deps) {
         handles.push(deps.watch(localesDir, {
             filter: isMessagesChange,
             onChange: async () => {
-                await regenerateMessages(localesDir, layout.messagesOut);
+                await regenerateMessages(localesDir, layout.messagesOut, layout.messagesBaseLng);
                 deps.log({ kind: 'regen', target: 'messages' });
             },
             onError: deps.onError,
@@ -110,7 +111,7 @@ export async function regenerateGaonOnce(layout, deps) {
     // 결정 158(W2): locales/ 가 있으면 messages.d.ts 도 재생성한다(i18n 키 타입 브리지).
     let messages = false;
     if (layout.localesDir && deps.regenerateMessages) {
-        messages = (await deps.regenerateMessages(layout.localesDir, layout.messagesOut)) === true;
+        messages = (await deps.regenerateMessages(layout.localesDir, layout.messagesOut, layout.messagesBaseLng)) === true;
     }
     // 결정 198(F-9 ②): 프론트 앱이 있으면 .env → env.d.ts. `.env` 부재는 throw(수리 안내).
     let env = false;
@@ -144,12 +145,16 @@ export function resolveDevLayout(cwd) {
             });
         }
     }
-    const localesDirPath = join(root, 'locales');
+    // 결정 352: 카탈로그 위치·기준 로케일은 gaon.config.ts 의 i18n 블록을 따른다
+    // (정적 분석 · 하드코딩 'locales' 는 dir 커스텀 프로젝트에서 타입 축을 무소음으로 껐다).
+    const i18nCfg = analyzeProjectI18n(root);
+    const localesDirPath = join(root, i18nCfg.dir ?? 'locales');
     return {
         schemaDir: existsSync(schemaDirPath) ? schemaDirPath : undefined,
         tablesOut: join(root, '.gaon', 'tables.d.ts'),
         apps: apps.sort((a, b) => a.name.localeCompare(b.name)),
         localesDir: existsSync(localesDirPath) ? localesDirPath : undefined,
+        messagesBaseLng: i18nCfg.fallbackLng,
         messagesOut: join(root, '.gaon', 'messages.d.ts'),
         hasFrontendApps,
         envFile: join(root, '.env'),

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

@@ -14,7 +14,7 @@ export declare const FIXERS: Partial<Record<DoctorRule, Fixer>>;
  * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
  * 수동 · 이유는 무엇인지 표시하는 데 쓴다(진단 = 수리 안내서 · §7.5.3).
  *
- * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 27종을 **빠짐없이** 담는다 —
+ * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 28종을 **빠짐없이** 담는다 —
  * fixer 가 없는 규칙도 `hasFixer:false` + 구체적 수동 안내로 명시한다. 항목이
  * 빠지면 --fix 리포트가 그 규칙 위반에 대해 일반 문구("수동 수정 필요")만 내
  * 사용자가 왜 자동이 안 되는지 알 수 없다. 전수성은 테스트가 고정한다

package/dist/doctor/fixers/index.js

@@ -28,7 +28,7 @@ export const FIXERS = {
  * 규칙별 fix 지원 여부 카탈로그. 리포트가 사용자에게 무엇이 자동 · 무엇이
  * 수동 · 이유는 무엇인지 표시하는 데 쓴다(진단 = 수리 안내서 · §7.5.3).
  *
- * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 27종을 **빠짐없이** 담는다 —
+ * **정직성 규약(결정 241)**: 이 배열은 `ALL_RULES` 28종을 **빠짐없이** 담는다 —
  * fixer 가 없는 규칙도 `hasFixer:false` + 구체적 수동 안내로 명시한다. 항목이
  * 빠지면 --fix 리포트가 그 규칙 위반에 대해 일반 문구("수동 수정 필요")만 내
  * 사용자가 왜 자동이 안 되는지 알 수 없다. 전수성은 테스트가 고정한다
@@ -165,6 +165,11 @@ export const FIXER_CAPABILITIES = [
         hasFixer: false,
         note: '수동 · .vue 의 import.meta.env(TS1470)는 env 접근자로 전환하세요 — 접근자 도입은 코드 편집이 필요합니다(결정 198).',
     },
+    {
+        rule: 'render-return',
+        hasFixer: false,
+        note: '수동 · this.render/redirect/json 호출 앞에 return 을 붙이세요 — 반환값이 곧 응답입니다(결정 340 · 의도된 204 는 응답 호출 없이 return).',
+    },
     {
         rule: 'locale-parity',
         hasFixer: false,

package/dist/doctor/locale-parity.js

@@ -11,6 +11,7 @@
 import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { loadLocales, flattenKeys } from '@gaonjs/i18n';
+import { analyzeProjectI18n } from '../i18n-config.js';
 // 경고 한 줄이 폭주하지 않게 나열 상한 — 넘으면 "…외 N개" 로 접는다(detail 에는 전량).
 const MAX_KEYS_SHOWN = 20;
 // i18next 복수형 접미사(결정 181 · generator.ts 와 동일 규약). 로케일마다 필요한 접미사만
@@ -26,7 +27,9 @@ function pluralBase(key) {
  * 비교 대상이 없어 건너뛴다(i18n 미사용·단일 로케일 프로젝트는 무소음).
  */
 export async function checkLocaleParity(cwd) {
-    const localesDir = join(cwd, 'locales');
+    // 결정 352: 카탈로그 위치는 config i18n.dir 을 따른다(정적 분석 · 하드코딩이던
+    // 'locales' 는 dir 커스텀 프로젝트에서 이 검사를 무소음으로 껐다).
+    const localesDir = join(cwd, analyzeProjectI18n(cwd).dir ?? 'locales');
     if (!existsSync(localesDir))
         return { rule: 'locale-parity', issues: [] };
     const resources = loadLocales(localesDir);

package/dist/doctor/render-return.d.ts

@@ -0,0 +1,11 @@
+import type { RuleReport } from './types.js';
+export interface DiscardedResponse {
+    readonly file: string;
+    readonly action: string;
+    readonly method: string;
+    readonly line: number;
+}
+/** 소스 문자열 하나에서 "버려진 응답 호출" 을 수집한다(단위 테스트 진입점). */
+export declare function inspectDiscardedResponses(file: string, source: string): DiscardedResponse[];
+/** apps/ 를 훑어 버려진 응답 호출(무신호 204)을 모두 낸다(경고 등급). */
+export declare function checkRenderReturn(cwd: string): Promise<RuleReport>;

package/dist/doctor/render-return.js

@@ -0,0 +1,143 @@
+// @gaonjs/cli · doctor · render-return 검사 (결정 340)
+//
+// 액션 본문이 `this.render(...)` / `this.redirect(...)` / `this.json(...)` 을
+// **호출만 하고 return 하지 않으면** 반환값(=응답)이 버려져 액션이 void 로 끝나고,
+// 디스패처는 조용히 204 No Content 를 낸다 — 컴파일은 통과하고 페이지는 백지다
+// (무신호 파손 클래스 · agents/web.md 함정 "return 누락 = 204").
+//
+// 정적 분석: 컨트롤러 액션 안에서 위 3종 호출이 ExpressionStatement(또는
+// `await` 만 감싼 문장)로 서 있으면 경고. return · 변수 대입 · 인자 전달 등
+// 값이 소비되는 위치는 오탐 방지로 제외한다. notFound/requireAuth 는 throw
+// 기반 가드라 대상이 아니다(response-mixing 의 GUARD_METHODS 와 정합).
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import ts from 'typescript';
+const RESPONSE_METHODS = new Set(['render', 'redirect', 'json']);
+/** 소스 문자열 하나에서 "버려진 응답 호출" 을 수집한다(단위 테스트 진입점). */
+export function inspectDiscardedResponses(file, source) {
+    const sf = ts.createSourceFile(file, source, ts.ScriptTarget.ES2022, true);
+    const found = [];
+    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);
+                    const body = actionBody(prop);
+                    if (!action || !body || !ts.isBlock(body))
+                        continue;
+                    collectDiscarded(sf, body, action, file, found);
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sf);
+    return found;
+}
+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;
+}
+/** 문장 위치에 버려진 this.render/redirect/json 호출이 있으면 수집한다. */
+function collectDiscarded(sf, body, action, file, out) {
+    const visit = (node) => {
+        if (ts.isExpressionStatement(node)) {
+            const method = responseCallName(node.expression);
+            if (method) {
+                const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+                out.push({ file, action, method, line: line + 1 });
+                return; // 이 문장은 판정 완료 — 내부 재방문 불요.
+            }
+        }
+        // 중첩 함수(콜백) 안의 호출은 반환 의미가 달라 제외(오탐 방지).
+        if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node))
+            return;
+        ts.forEachChild(node, visit);
+    };
+    visit(body);
+}
+/** 식이 (await 를 벗긴) this.render/redirect/json 호출이면 메서드 이름을 돌려준다. */
+function responseCallName(expr) {
+    const inner = ts.isAwaitExpression(expr) ? expr.expression : expr;
+    if (!ts.isCallExpression(inner))
+        return undefined;
+    const c = inner.expression;
+    if (ts.isPropertyAccessExpression(c) &&
+        c.expression.kind === ts.SyntaxKind.ThisKeyword &&
+        RESPONSE_METHODS.has(c.name.text)) {
+        return c.name.text;
+    }
+    return undefined;
+}
+/** apps/ 를 훑어 버려진 응답 호출(무신호 204)을 모두 낸다(경고 등급). */
+export async function checkRenderReturn(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');
+            for (const d of inspectDiscardedResponses(full, source)) {
+                const rel = relative(cwd, full);
+                issues.push({
+                    rule: 'render-return',
+                    level: 'warning',
+                    file: rel,
+                    line: d.line,
+                    message: `버려진 응답 호출: ${rel}:${d.line} · 액션 '${d.action}' 이 this.${d.method}(...) 를 호출만 하고 return 하지 않습니다.\n` +
+                        `→ 반환값이 곧 응답입니다(errata E-3) — return 이 없으면 액션이 void 로 끝나 조용히 204 No Content(백지)가 나갑니다.\n` +
+                        `→ \`return this.${d.method}(...)\` 로 고치세요. (의도된 204 는 아무 응답 호출 없이 그냥 return 합니다.)`,
+                    detail: { action: d.action, method: d.method },
+                });
+            }
+        }
+    }
+    return { rule: 'render-return', 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

@@ -1,4 +1,4 @@
-export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env' | 'locale-parity';
+export type DoctorRule = 'response-mixing' | 'n-plus-one' | 'dependency-direction' | 'connections' | 'migration-diff' | 'shared-purity' | 'no-auto-import' | 'schema-filename' | 'agents-doc-index' | 'column-casing' | 'model-filename' | 'page-filename' | 'auth-wiring' | 'ui-kit-wiring' | 'route-registration' | 'static-collision' | 'method-override' | 'csrf-wiring' | 'internal-anchor' | 'pageprops-destructure' | 'async-offload' | 'page-layout-breakpoint' | 'link-button-nesting' | 'seal-security' | 'schema-relations' | 'no-import-meta-env' | 'locale-parity' | 'render-return';
 export type DoctorLevel = 'passed' | 'warning' | 'error';
 export interface DoctorCheck {
     readonly rule: DoctorRule;

package/dist/doctor.d.ts

@@ -2,6 +2,7 @@ import { type DoctorCheck, type DoctorFatal, type DoctorFatalCode, type DoctorLe
 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 { inspectDiscardedResponses, checkRenderReturn } from './doctor/render-return.js';
 export { inspectControllerForNPlusOne, checkNPlusOne } from './doctor/n-plus-one.js';
 export { extractRelativeImports, checkDependencyDirection } from './doctor/dependency-direction.js';
 export { extractConfigDbKeys, analyzeConfigDb, extractKeyUses, checkConnections, } from './doctor/connections.js';
@@ -26,10 +27,10 @@ export { checkLocaleParity } from './doctor/locale-parity.js';
 export { renderHuman, renderJson } from './doctor/reporter.js';
 export { checkTypeScriptApi, detectProject, fatalNoProject, fatalTsApiMissing, } from './doctor/setup.js';
 /**
- * 실행할 검사 이름. 지정 없음(undefined) = 27개 모두.
+ * 실행할 검사 이름. 지정 없음(undefined) = 28개 모두.
  */
 /**
- * doctor 정적 검사 27종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
+ * doctor 정적 검사 28종의 정본 목록(§2.2). `--check=` 필터의 인정 집합도
  * 이 배열을 단일 출처로 삼는다(parseDoctorChecks) — 새 규칙 추가 시 여기만
  * 늘리면 실행·필터·타입이 함께 정합된다(손유지 중복 리스트 표류 방지).
  */