@dotflash/openapi-semantic-generator 0.1.0 → 0.1.2

package/README.md

@@ -1,4 +1,4 @@
-# OpenAPI-Agent-Sync (oas-agent-sync)
+# OpenAPI Semantic Generator (@dotflash/openapi-semantic-generator)
 
 [English](#english) | [한국어](#한국어)
 
@@ -41,13 +41,13 @@ It provides an index and guide that allows LLMs to understand large-scale API co
 ### Installation
 
 ```bash
-npm install -g oas-agent-sync
+npm install -g @dotflash/openapi-semantic-generator
 ```
 
 ### Usage
 
 ```bash
-npx oas-agent-sync <spec-url-or-path> -o <generated-code-dir> [options]
+npx openapi-semantic-generator <spec-url-or-path> -o <generated-code-dir> [options]
 ```
 
 #### Required Arguments
@@ -56,8 +56,30 @@ npx oas-agent-sync <spec-url-or-path> -o <generated-code-dir> [options]
 
 #### Options
 
-- `-o, --output <dir>`: Directory where the code is already generated (e.g., `./src/api`)
-- `--api-dir <path>`: Relative path to APIs within the output directory (e.g., `services`)
+- `-o, --output <dir>`: **Required.** Directory where the generated code is located. This tool will scan this directory to find API files.
+  - Example: `./src/api`, `./generated/client`
+  - **Important**: The generated TypeScript files must be inside this directory or its subdirectories.
+
+- `--api-dir <path>`: Optional. Relative path from the output directory where API files are located.
+  - Example: `services`, `api`, `client/apis`
+  - This path is **relative to the `-o` directory**, not the current working directory.
+  - If not specified, the tool searches in `api/`, `apis/`, and the output directory itself (in that order).
+
+#### Usage Examples
+
+```bash
+# Basic usage: API files are in ./src/api/
+npx openapi-semantic-generator spec.yaml -o ./src/api
+
+# API files are in ./generated/services/
+npx openapi-semantic-generator spec.yaml -o ./generated --api-dir services
+
+# Using a remote spec URL
+npx openapi-semantic-generator https://api.example.com/openapi.json -o ./src/api
+
+# API files are directly in the output directory
+npx openapi-semantic-generator spec.yaml -o ./dist/client
+```
 
 ### Generated Documents
 
@@ -91,13 +113,13 @@ OpenAPI Generator로 생성된 코드들을 분석하여 LLM 에이전트가 활
 ### 설치 방법
 
 ```bash
-npm install -g oas-agent-sync
+npm install -g @dotflash/openapi-semantic-generator
 ```
 
 ### 사용 방법
 
 ```bash
-npx oas-agent-sync <spec-url-or-path> -o <generated-code-dir> [options]
+npx openapi-semantic-generator <spec-url-or-path> -o <generated-code-dir> [options]
 ```
 
 #### 필수 인자
@@ -106,8 +128,30 @@ npx oas-agent-sync <spec-url-or-path> -o <generated-code-dir> [options]
 
 #### 옵션
 
-- `-o, --output <dir>`: 이미 생성된 코드가 위치한 디렉토리 (예: `./src/api`)
-- `--api-dir <path>`: 출력 디렉토리 내 API 파일이 위치한 상대 경로 (예: `services`)
+- `-o, --output <dir>`: **필수.** 생성된 코드가 위치한 디렉토리입니다. 이 도구는 해당 디렉토리를 스캔하여 API 파일을 찾습니다.
+  - 예시: `./src/api`, `./generated/client`
+  - **중요**: 생성된 TypeScript 파일이 반드시 이 디렉토리 또는 하위 디렉토리에 있어야 합니다.
+
+- `--api-dir <path>`: 선택사항. 출력 디렉토리 기준으로 API 파일이 위치한 상대 경로입니다.
+  - 예시: `services`, `api`, `client/apis`
+  - 이 경로는 **`-o` 디렉토리 기준의 상대 경로**이며, 현재 작업 디렉토리 기준이 아닙니다.
+  - 지정하지 않으면 `api/`, `apis/`, 출력 디렉토리 자체를 순서대로 검색합니다.
+
+#### 사용 예시
+
+```bash
+# 기본 사용: API 파일이 ./src/api/에 있는 경우
+npx openapi-semantic-generator spec.yaml -o ./src/api
+
+# API 파일이 ./generated/services/에 있는 경우
+npx openapi-semantic-generator spec.yaml -o ./generated --api-dir services
+
+# 원격 스펙 URL 사용
+npx openapi-semantic-generator https://api.example.com/openapi.json -o ./src/api
+
+# API 파일이 출력 디렉토리 바로 아래에 있는 경우
+npx openapi-semantic-generator spec.yaml -o ./dist/client
+```
 
 ### 생성되는 문서
 

package/dist/{chunk-JGV5ULAN.js → chunk-PLFFT6WD.js}

@@ -95,10 +95,20 @@ async function scanGeneratedFiles(outputDir, metadata, options = {}) {
   }
   if (metadata.operations) {
     for (const op of metadata.operations) {
-      if (apis.length > 0) {
-        op.className = apis[0].className;
-        op.sourceFile = apis[0].sourceFile;
+      if (apis.length === 0) continue;
+      let matchedApi = apis[0];
+      if (op.tags && op.tags.length > 0) {
+        const primaryTag = op.tags[0].toLowerCase();
+        const found = apis.find((api) => {
+          const fileName = api.className.toLowerCase();
+          return fileName.includes(primaryTag);
+        });
+        if (found) {
+          matchedApi = found;
+        }
       }
+      op.className = matchedApi.className;
+      op.sourceFile = matchedApi.sourceFile;
     }
   }
   return {
@@ -143,10 +153,20 @@ async function renderDocs(metadata, outputDir) {
   });
   const groupedOperations = Object.entries(operationsByTag).map(([tag, ops]) => ({
     tag,
-    ops: ops.map((op, index) => ({
-      ...op,
-      last: index === ops.length - 1
-    }))
+    ops: ops.map((op, index) => {
+      let relativePath = op.sourceFile;
+      if (path2.isAbsolute(op.sourceFile)) {
+        relativePath = path2.relative(outputDir, op.sourceFile);
+      }
+      if (!relativePath.startsWith("./") && !relativePath.startsWith("../")) {
+        relativePath = "./" + relativePath;
+      }
+      return {
+        ...op,
+        sourceFile: relativePath,
+        last: index === ops.length - 1
+      };
+    })
   }));
   const enrichedMetadata = {
     ...metadata,

package/dist/cli.cjs

@@ -133,10 +133,20 @@ async function scanGeneratedFiles(outputDir, metadata, options = {}) {
   }
   if (metadata.operations) {
     for (const op of metadata.operations) {
-      if (apis.length > 0) {
-        op.className = apis[0].className;
-        op.sourceFile = apis[0].sourceFile;
+      if (apis.length === 0) continue;
+      let matchedApi = apis[0];
+      if (op.tags && op.tags.length > 0) {
+        const primaryTag = op.tags[0].toLowerCase();
+        const found = apis.find((api) => {
+          const fileName = api.className.toLowerCase();
+          return fileName.includes(primaryTag);
+        });
+        if (found) {
+          matchedApi = found;
+        }
       }
+      op.className = matchedApi.className;
+      op.sourceFile = matchedApi.sourceFile;
     }
   }
   return {
@@ -181,10 +191,20 @@ async function renderDocs(metadata, outputDir) {
   });
   const groupedOperations = Object.entries(operationsByTag).map(([tag, ops]) => ({
     tag,
-    ops: ops.map((op, index) => ({
-      ...op,
-      last: index === ops.length - 1
-    }))
+    ops: ops.map((op, index) => {
+      let relativePath = op.sourceFile;
+      if (import_path2.default.isAbsolute(op.sourceFile)) {
+        relativePath = import_path2.default.relative(outputDir, op.sourceFile);
+      }
+      if (!relativePath.startsWith("./") && !relativePath.startsWith("../")) {
+        relativePath = "./" + relativePath;
+      }
+      return {
+        ...op,
+        sourceFile: relativePath,
+        last: index === ops.length - 1
+      };
+    })
   }));
   const enrichedMetadata = {
     ...metadata,

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   generateDocs
-} from "./chunk-JGV5ULAN.js";
+} from "./chunk-PLFFT6WD.js";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/index.cjs

@@ -142,10 +142,20 @@ async function scanGeneratedFiles(outputDir, metadata, options = {}) {
   }
   if (metadata.operations) {
     for (const op of metadata.operations) {
-      if (apis.length > 0) {
-        op.className = apis[0].className;
-        op.sourceFile = apis[0].sourceFile;
+      if (apis.length === 0) continue;
+      let matchedApi = apis[0];
+      if (op.tags && op.tags.length > 0) {
+        const primaryTag = op.tags[0].toLowerCase();
+        const found = apis.find((api) => {
+          const fileName = api.className.toLowerCase();
+          return fileName.includes(primaryTag);
+        });
+        if (found) {
+          matchedApi = found;
+        }
       }
+      op.className = matchedApi.className;
+      op.sourceFile = matchedApi.sourceFile;
     }
   }
   return {
@@ -190,10 +200,20 @@ async function renderDocs(metadata, outputDir) {
   });
   const groupedOperations = Object.entries(operationsByTag).map(([tag, ops]) => ({
     tag,
-    ops: ops.map((op, index) => ({
-      ...op,
-      last: index === ops.length - 1
-    }))
+    ops: ops.map((op, index) => {
+      let relativePath = op.sourceFile;
+      if (import_path2.default.isAbsolute(op.sourceFile)) {
+        relativePath = import_path2.default.relative(outputDir, op.sourceFile);
+      }
+      if (!relativePath.startsWith("./") && !relativePath.startsWith("../")) {
+        relativePath = "./" + relativePath;
+      }
+      return {
+        ...op,
+        sourceFile: relativePath,
+        last: index === ops.length - 1
+      };
+    })
   }));
   const enrichedMetadata = {
     ...metadata,

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   generateDocs,
   renderDocs,
   scanGeneratedFiles
-} from "./chunk-JGV5ULAN.js";
+} from "./chunk-PLFFT6WD.js";
 export {
   extractMetadata,
   generateDocs,

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@dotflash/openapi-semantic-generator",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Semantic mapping automation tool for LLM agents and OpenAPI generated code",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "bin": {
-    "oas-agent-sync": "dist/cli.js"
+    "openapi-semantic-generator": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -19,7 +19,8 @@
     "dev": "tsup src/index.ts src/cli.ts --format cjs,esm --watch --shims",
     "test": "vitest run",
     "test:watch": "vitest",
-    "gen:example": "openapi-generator-cli generate -i test/fixtures/petstore.yaml -g typescript-axios -o test/generated/petstore && node dist/cli.js test/fixtures/petstore.yaml -o test/generated/petstore --api-dir api"
+    "gen:example": "openapi-generator-cli generate -i https://petstore3.swagger.io/api/v3/openapi.json -g typescript-axios -o test/generated/petstore && node dist/cli.js https://petstore3.swagger.io/api/v3/openapi.json -o test/generated/petstore",
+    "gen:example:separate": "openapi-generator-cli generate -i https://petstore3.swagger.io/api/v3/openapi.json -g typescript-axios -o test/generated/petstore-separate --additional-properties=withSeparateModelsAndApi=true,apiPackage=apis,modelPackage=models && node dist/cli.js https://petstore3.swagger.io/api/v3/openapi.json -o test/generated/petstore-separate --api-dir apis"
   },
   "keywords": [
     "openapi",