openapi-multitarget-codegen 0.1.1 → 0.1.2

package/README.md

@@ -108,8 +108,9 @@ openapi-multitarget-codegen check-spec --input <spec>
 
 ### `check-spec` 범위
 
-- `check-spec`은 전체 OpenAPI 스키마 검증이 아니라, 파일 존재 여부와 기본 구조(`openapi`, `paths`)를 확인하는 최소 검사입니다.
-- 즉, 정식 lint/validation을 대체하지는 않습니다.
+- `check-spec`은 파일 존재 여부와 기본 구조(`openapi`, `paths`) 확인에 더해, OpenAPI 문서를 실제로 parse/validate 합니다.
+- unresolved `$ref`, 잘못된 스키마 구조, 문서 수준의 OpenAPI 오류를 조기에 잡는 용도입니다.
+- 다만 **target별 생성기 호환성까지 전부 보장하는 것은 아닙니다.** 즉, `kubb`, `python`, `langgraph` 각각의 세부 제약은 실제 generate 단계에서 추가 확인이 필요할 수 있습니다.
 
 ### 추가 옵션
 
@@ -119,6 +120,12 @@ openapi-multitarget-codegen check-spec --input <spec>
   - 기본값: `<output>/kubb`
   - 상대 경로는 `--output` 기준으로 해석됩니다.
   - `--kubb-config`와 함께 사용할 수 없습니다.
+- `--kubb-format <mode>`
+  - 기본값: `false`
+  - preset 모드에서만 사용합니다.
+  - 허용값: `auto`, `prettier`, `biome`, `oxfmt`, `false`
+  - 기본값 `false`는 Kubb 생성은 유지하되 formatter 미설치로 인한 혼란스러운 메시지를 피하기 위한 설정입니다.
+  - `--kubb-config`와 함께 사용할 수 없습니다.
 - `--python-output-file <path>`
   - 기본값: `<output>/python/models.py`
   - 상대 경로는 `--output` 기준으로 해석됩니다.
@@ -150,6 +157,8 @@ openapi-multitarget-codegen check-spec --input <spec>
 
 1. **기본 preset 모드**
    - 이 패키지에 포함된 기본 Kubb 구성으로 생성합니다.
+   - 기본 formatter 설정은 `false`입니다.
+   - formatter를 켜고 싶다면 `--kubb-format auto` 또는 `--kubb-format prettier` 같은 식으로 명시합니다.
    - 현재 포함된 핵심 의존성:
      - `@kubb/cli`
      - `@kubb/core`
@@ -158,10 +167,10 @@ openapi-multitarget-codegen check-spec --input <spec>
      - `@kubb/plugin-client`
 2. **native config pass-through 모드**
    - `--kubb-config`를 주면 사용자의 기존 Kubb config를 그대로 사용합니다.
-   - Kubb의 실제 입력/출력/플러그인 설정은 config 파일 내용을 따릅니다.
+   - Kubb의 실제 입력/출력/플러그인/formatter 설정은 config 파일 내용을 따릅니다.
    - 다만 이 래퍼 CLI는 `--input`, `--output`을 계속 요구합니다.
    - `--input`은 OpenAPI 파일 사전 검증에 사용되고, `--output`은 `--clean` 기준 루트입니다.
-   - 이 모드에서는 `--kubb-output-dir`, `--kubb-client`를 함께 사용할 수 없습니다.
+   - 이 모드에서는 `--kubb-output-dir`, `--kubb-client`, `--kubb-format`을 함께 사용할 수 없습니다.
    - 이 경우 추가 Kubb 플러그인은 소비자 프로젝트에서 직접 설치/관리하는 것을 권장합니다.
 
 즉, 이 패키지는 **기본 preset에 필요한 핵심 Kubb 플러그인만 포함**하고, 나머지 Kubb 생태계는 **기존 Kubb CLI/config를 그대로 통과시키는 방향**을 따릅니다.
@@ -376,8 +385,11 @@ npx openapi-multitarget-codegen check-spec --input ./specs/openapi.yaml
 
 이 명령은 다음을 검사합니다.
 - 파일 존재 여부
-- `openapi` 필드 존재 여부
-- `paths` 객체 존재 여부
+- 기본 구조(`openapi`, `paths`) 존재 여부
+- OpenAPI 문서 parse/validate
+- unresolved `$ref`, 잘못된 스키마 구조 등 문서 수준 오류
+
+다만 이 단계가 `kubb`, `python`, `langgraph` 각 타깃 생성기의 세부 호환성까지 모두 보장하는 것은 아닙니다. 타깃별 제약은 실제 `generate` 단계에서 추가 확인이 필요할 수 있습니다.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-multitarget-codegen",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "OpenAPI-based multi-target code generation CLI for Kubb, Python types, and LangGraph tools",
   "license": "MIT",
@@ -26,6 +26,7 @@
   },
   "scripts": {
     "clean": "rimraf .tmp-output",
+    "test": "node --test tests/*.test.mjs",
     "check:example-spec": "node ./src/cli.mjs check-spec --input ./openapi/openapi.example.yaml",
     "generate:example:kubb": "node ./src/cli.mjs generate --input ./openapi/openapi.example.yaml --output ./.tmp-output --target kubb --clean",
     "generate:example:python": "node ./src/cli.mjs generate --input ./openapi/openapi.example.yaml --output ./.tmp-output --target python --clean",
@@ -33,6 +34,7 @@
     "generate:example:all": "node ./src/cli.mjs generate --input ./openapi/openapi.example.yaml --output ./.tmp-output --target kubb --target python --target langgraph --clean"
   },
   "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
     "@kubb/cli": "^4.37.2",
     "@kubb/core": "^4.37.2",
     "@kubb/plugin-client": "^4.37.2",

package/src/cli.mjs

@@ -9,10 +9,11 @@ import { fileURLToPath } from 'node:url'
 import yaml from 'js-yaml'
 
 const require = createRequire(import.meta.url)
+const SwaggerParser = require('@apidevtools/swagger-parser')
 const CLI_FILE = fileURLToPath(import.meta.url)
 const PACKAGE_ROOT = path.resolve(path.dirname(CLI_FILE), '..')
 
-function main() {
+async function main() {
   const { command, options } = parseArgs(process.argv.slice(2))
 
   try {
@@ -23,7 +24,7 @@ function main() {
 
     if (command === 'check-spec') {
       const input = requireOption(options, 'input')
-      validateOpenApiFile(path.resolve(input))
+      await validateOpenApiSpec(path.resolve(input))
       console.log(`✓ valid OpenAPI spec: ${path.resolve(input)}`)
       process.exit(0)
     }
@@ -37,6 +38,7 @@ function main() {
     const kubbOutputDir = options['kubb-output-dir']
     const kubbConfigPath = options['kubb-config']
     const kubbArgs = Array.isArray(options['kubb-arg']) ? options['kubb-arg'] : []
+    const kubbFormat = normalizeKubbFormat(options['kubb-format'])
     const pythonOutputFile = options['python-output-file']
     const langgraphOutputDir = options['langgraph-output-dir']
     const langgraphFileName = options['langgraph-file'] || 'langgraph_tools.py'
@@ -67,6 +69,7 @@ function main() {
           client: kubbClient,
           configPath: kubbConfigPath,
           extraArgs: kubbArgs,
+          format: kubbFormat,
         })
       } else if (target === 'python') {
         runPython({ input, outputRoot: output, outputFile: pythonOutputFile, modelType: pythonModelType })
@@ -133,6 +136,20 @@ function normalizeTargets(targetValue) {
   return values
 }
 
+function normalizeKubbFormat(value) {
+  if (!value) {
+    return false
+  }
+
+  const normalized = String(value).toLowerCase()
+  const allowed = new Set(['auto', 'prettier', 'biome', 'oxfmt', 'false'])
+  if (!allowed.has(normalized)) {
+    throw new Error("--kubb-format must be one of: auto, prettier, biome, oxfmt, false")
+  }
+
+  return normalized === 'false' ? false : normalized
+}
+
 function requireOption(options, key) {
   const value = options[key]
   if (!value) {
@@ -146,6 +163,10 @@ function validateOpenApiFile(specPath) {
     throw new Error(`OpenAPI spec not found: ${specPath}`)
   }
 
+  return loadOpenApiFile(specPath)
+}
+
+function loadOpenApiFile(specPath) {
   const text = fs.readFileSync(specPath, 'utf8')
   let data
   try {
@@ -167,7 +188,30 @@ function validateOpenApiFile(specPath) {
   return data
 }
 
-function runKubb({ input, outputRoot, outputDir, client, configPath, extraArgs = [] }) {
+async function validateOpenApiSpec(specPath) {
+  validateOpenApiFile(specPath)
+
+  try {
+    await SwaggerParser.validate(specPath)
+  } catch (error) {
+    const details = []
+    const primaryMessage = error?.message || 'OpenAPI validation failed'
+    details.push(primaryMessage)
+
+    const parserDetails = Array.isArray(error?.details) ? error.details : []
+    for (const detail of parserDetails.slice(0, 5)) {
+      const pathText = detail?.path ? `${detail.path}: ` : ''
+      const messageText = detail?.message || detail?.toString?.() || ''
+      if (messageText) {
+        details.push(`${pathText}${messageText}`)
+      }
+    }
+
+    throw new Error(`OpenAPI validation failed:\n- ${details.join('\n- ')}`)
+  }
+}
+
+function runKubb({ input, outputRoot, outputDir, client, configPath, extraArgs = [], format }) {
   if (configPath) {
     const resolvedConfigPath = path.resolve(configPath)
     if (!fs.existsSync(resolvedConfigPath)) {
@@ -211,6 +255,7 @@ export default defineConfig({
   output: {
     path: ${JSON.stringify(kubbOutputDir)},
     clean: true,
+    format: ${format === false ? 'false' : JSON.stringify(format)},
   },
   plugins: [
     pluginOas(),
@@ -633,6 +678,7 @@ function validateKubbOptionCompatibility({ options, targets, kubbConfigPath, kub
   const conflicting = [
     ['kubb-client', options['kubb-client']],
     ['kubb-output-dir', options['kubb-output-dir']],
+    ['kubb-format', options['kubb-format']],
   ].filter(([, value]) => value)
 
   if (conflicting.length > 0) {
@@ -797,6 +843,7 @@ Options:
   --kubb-output-dir <path>      Kubb output directory (default: <output>/kubb)
   --kubb-config <path>          Use an existing Kubb config file as the source of truth
   --kubb-arg <value>            Pass an extra argument to 'kubb generate' (repeatable, requires --kubb-config)
+  --kubb-format <mode>          Kubb formatter for preset mode (default: false; auto|prettier|biome|oxfmt|false)
   --python-output-file <path>   Python output file (default: <output>/python/models.py)
   --langgraph-output-dir <path> LangGraph output directory (default: <output>/langgraph)
   --langgraph-file <name>       LangGraph output filename (default: langgraph_tools.py)