From ac87714269de7f9f40f10565e52a805925c44884 Mon Sep 17 00:00:00 2001 From: jaesong Date: Sun, 3 Aug 2025 11:52:21 +0900 Subject: [PATCH 1/6] docs: translate Korean JSDoc to English --- lib/config/readPackageJson.ts | 18 +++--- lib/dsl/adapters/TestFramework.ts | 2 +- lib/dsl/adapters/UserTestInterface.ts | 4 +- lib/dsl/adapters/index.ts | 28 +++++----- lib/dsl/generator/OpenAPIGenerator.ts | 22 ++++---- lib/dsl/generator/TestEventManager.ts | 26 ++++----- lib/dsl/generator/TestResultCollector.ts | 16 +++--- lib/dsl/generator/builders/SchemaBuilder.ts | 20 +++---- .../builders/operation/ParameterBuilder.ts | 38 ++++++------- .../builders/operation/RequestBodyBuilder.ts | 14 ++--- .../builders/operation/ResponseBuilder.ts | 20 +++---- .../builders/operation/SecurityBuilder.ts | 12 ++-- .../builders/operation/UtilityBuilder.ts | 24 ++++---- .../builders/operation/interfaces.ts | 22 ++++---- .../builders/schema/BaseSchemaGenerator.ts | 14 ++--- .../builders/schema/SchemaFactory.ts | 24 ++++---- .../generator/builders/schema/constants.ts | 2 +- .../schema/generators/ArraySchemaGenerator.ts | 14 ++--- .../generators/BooleanSchemaGenerator.ts | 14 ++--- .../generators/DSLFieldSchemaGenerator.ts | 22 ++++---- .../generators/NumberSchemaGenerator.ts | 10 ++-- .../generators/ObjectSchemaGenerator.ts | 14 ++--- .../generators/StringSchemaGenerator.ts | 10 ++-- lib/dsl/generator/builders/schema/index.ts | 22 ++++---- .../generator/builders/schema/interfaces.ts | 26 ++++----- lib/dsl/generator/commands.ts | 16 +++--- lib/dsl/generator/index.ts | 6 +- lib/dsl/generator/types/OpenAPITypes.ts | 20 +++---- lib/dsl/generator/types/TestResult.ts | 36 ++++++------ lib/dsl/interface/ItdocBuilderEntry.ts | 10 ++-- lib/dsl/interface/describeAPI.ts | 12 ++-- lib/dsl/interface/field.ts | 20 +++---- lib/dsl/interface/itDoc.ts | 4 +- lib/dsl/interface/testContext.ts | 4 +- lib/dsl/test-builders/AbstractTestBuilder.ts | 2 +- lib/dsl/test-builders/RequestBuilder.ts | 8 +-- lib/dsl/test-builders/ResponseBuilder.ts | 2 +- lib/dsl/test-builders/RootBuilder.ts | 4 +- lib/dsl/test-builders/TestCaseConfig.ts | 4 +- lib/dsl/test-builders/validateResponse.ts | 28 +++++----- lib/utils/pathResolver.ts | 14 ++--- lib/utils/specParser.ts | 12 ++-- script/llm/loader/index.ts | 8 +-- script/llm/parser/analyzer/branchAnalyzer.ts | 16 +++--- .../llm/parser/analyzer/responseAnalyzer.ts | 42 +++++++------- .../parser/analyzer/returnValueExtractor.ts | 36 ++++++------ .../llm/parser/analyzer/variableAnalyzer.ts | 14 ++--- script/llm/parser/collector/routeCollector.ts | 30 +++++----- script/llm/parser/index.ts | 8 +-- script/llm/parser/utils/extractValue.ts | 56 +++++++++---------- script/llm/parser/utils/fileParser.ts | 32 +++++------ script/llm/prompt/index.ts | 45 +++++++-------- script/makedocs/index.ts | 26 ++++----- 53 files changed, 477 insertions(+), 476 deletions(-) diff --git a/lib/config/readPackageJson.ts b/lib/config/readPackageJson.ts index 870f74ca..1cf69aee 100644 --- a/lib/config/readPackageJson.ts +++ b/lib/config/readPackageJson.ts @@ -19,11 +19,11 @@ import * as path from "path" import logger from "./logger" /** - * package.json의 "itdoc" 항목 내에서 특정 인자를 읽어옵니다. - * 만약 해당 인자가 존재하지 않으면, 기본값을 반환합니다. - * @param key 조회할 인자명 (.으로 depth 추가 가능) - * @param defaultValue 기본값 - * @returns itdoc[key] 값 또는 defaultValue + * Reads a specific argument from the "itdoc" section in package.json. + * If the argument does not exist, returns the default value. + * @param key Argument name to query (depth can be added with .) + * @param defaultValue Default value + * @returns itdoc[key] value or defaultValue */ export function readItdocConfig(key: string, defaultValue: string): string { const packageJson = readPackageJson() @@ -51,10 +51,10 @@ export function readItdocConfig(key: string, defaultValue: string): string { } /** - * 현재 작업 디렉토리의 `package.json`을 읽어 파싱된 객체를 반환합니다. + * Reads and returns the parsed object of `package.json` from the current working directory. * - * 읽기 또는 파싱 중 오류가 발생하면 null을 반환하며, 에러 로그를 출력합니다. - * @returns {object | null} 파싱된 package.json 객체 또는 null + * Returns null and outputs error logs if an error occurs during reading or parsing. + * @returns {object | null} Parsed package.json object or null */ function readPackageJson(): any { const packageJsonPath = path.resolve(process.cwd(), "package.json") @@ -62,7 +62,7 @@ function readPackageJson(): any { const packageJsonData = fs.readFileSync(packageJsonPath, "utf8") return JSON.parse(packageJsonData) } catch (error) { - logger.error("package.json을 읽는 중 오류 발생.", error) + logger.error("Error occurred while reading package.json.", error) return null } } diff --git a/lib/dsl/adapters/TestFramework.ts b/lib/dsl/adapters/TestFramework.ts index 039e304a..8453a06e 100644 --- a/lib/dsl/adapters/TestFramework.ts +++ b/lib/dsl/adapters/TestFramework.ts @@ -15,7 +15,7 @@ */ /** - * 지원하는 테스트 프레임워크에 대한 Enum + * Enum for supported test frameworks */ export enum TestFramework { Jest = "JEST", diff --git a/lib/dsl/adapters/UserTestInterface.ts b/lib/dsl/adapters/UserTestInterface.ts index e4d6f78b..1fb77583 100644 --- a/lib/dsl/adapters/UserTestInterface.ts +++ b/lib/dsl/adapters/UserTestInterface.ts @@ -17,8 +17,8 @@ import { TestFramework } from "./TestFramework" /** - * 공통 DSL 인터페이스를 정의합니다. - * 실제 테스트 프레임워크의 함수들을 감싸서 동일한 인터페이스를 제공할 수 있도록 합니다. + * Defines common DSL interface. + * Wraps actual test framework functions to provide a unified interface. */ export interface UserTestInterface { name: TestFramework diff --git a/lib/dsl/adapters/index.ts b/lib/dsl/adapters/index.ts index 2eb581fb..4205dccf 100644 --- a/lib/dsl/adapters/index.ts +++ b/lib/dsl/adapters/index.ts @@ -19,7 +19,7 @@ import { TestFramework } from "./TestFramework" import type { UserTestInterface } from "./UserTestInterface" /** - * 테스트 프레임워크를 감지하는 동기 함수 + * Synchronous function that detects test framework */ function detectTestFramework(): TestFramework { const isJest = @@ -44,7 +44,7 @@ function detectTestFramework(): TestFramework { } /** - * 동기 방식으로 어댑터를 초기화하는 함수 + * Function that initializes adapter synchronously */ function initializeAdapterSync(): UserTestInterface { const framework = detectTestFramework() @@ -52,9 +52,9 @@ function initializeAdapterSync(): UserTestInterface { switch (framework) { case TestFramework.Jest: { /* - 참고: Jest의 경우, 반드시 사용할 때만 동적으로 import 해야 합니다. - 그렇지 않으면 "Do not import `@jest/globals` outside of the Jest test environment" - 에러가 발생하게 됩니다. + Note: For Jest, dynamic imports must only be used when needed. + Otherwise, "Do not import `@jest/globals` outside of the Jest test environment" + error will occur. */ const { JestAdapter } = require("./JestAdapter") return new JestAdapter() @@ -73,15 +73,15 @@ function initializeAdapterSync(): UserTestInterface { } /** - * 어댑터를 초기화하고 필요한 테스트 메서드들을 반환하는 함수 - * 동기 방식으로 동작합니다. - * @returns {object} 테스트 프레임워크의 공통 메서드들 - * @property {Function} describeCommon 테스트 스위트를 정의하는 함수 - * @property {Function} itCommon 테스트 케이스를 정의하는 함수 - * @property {Function} beforeAllCommon 전체 테스트 전에 실행되는 함수 - * @property {Function} afterAllCommon 전체 테스트 후에 실행되는 함수 - * @property {Function} beforeEachCommon 각 테스트 전에 실행되는 함수 - * @property {Function} afterEachCommon 각 테스트 후에 실행되는 함수 + * Function that initializes adapter and returns necessary test methods + * Operates synchronously. + * @returns {object} Common methods of test framework + * @property {Function} describeCommon Function that defines test suite + * @property {Function} itCommon Function that defines test case + * @property {Function} beforeAllCommon Function executed before all tests + * @property {Function} afterAllCommon Function executed after all tests + * @property {Function} beforeEachCommon Function executed before each test + * @property {Function} afterEachCommon Function executed after each test */ export function getTestAdapterExports(): { describeCommon: (name: string, fn: () => void) => void diff --git a/lib/dsl/generator/OpenAPIGenerator.ts b/lib/dsl/generator/OpenAPIGenerator.ts index 25e314fb..812e403f 100644 --- a/lib/dsl/generator/OpenAPIGenerator.ts +++ b/lib/dsl/generator/OpenAPIGenerator.ts @@ -34,7 +34,7 @@ interface OpenAPIInfo { } /** - * OpenAPI Specification 생성기 + * OpenAPI Specification generator */ export class OpenAPIGenerator implements IOpenAPIGenerator { private testResults: TestResult[] = [] @@ -47,7 +47,7 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { private utilityBuilder = new UtilityBuilder() /** - * 생성자 - 싱글톤 패턴을 위해 private으로 설정 + * Constructor - set as private for singleton pattern */ private constructor() { this.servers.push({ @@ -57,8 +57,8 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 싱글톤 인스턴스를 반환합니다. - * @returns {OpenAPIGenerator} OpenAPIGenerator의 싱글톤 인스턴스 + * Returns the singleton instance. + * @returns {OpenAPIGenerator} Singleton instance of OpenAPIGenerator */ public static getInstance(): OpenAPIGenerator { if (!instance) { @@ -68,16 +68,16 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 테스트가 통과했을 때 결과를 수집합니다. - * @param {TestResult} result 테스트 결과 객체 + * Collects results when tests pass. + * @param {TestResult} result Test result object */ public collectTestResult(result: TestResult): void { this.testResults.push(result) } /** - * 수집된 테스트 결과를 OpenAPI Specification으로 변환합니다. - * @returns {object} OpenAPI Specification 객체 + * Converts collected test results to OpenAPI Specification. + * @returns {object} OpenAPI Specification object */ public generateOpenAPISpec(): Record { // 테스트 결과를 그룹화 @@ -94,7 +94,7 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 테스트 결과를 경로, 메서드, 상태 코드별로 그룹화합니다. + * Groups test results by path, method, and status code. */ private groupTestResults(): Map>> { const groupedResults: Map>> = new Map() @@ -124,7 +124,7 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 그룹화된 테스트 결과로부터 경로 객체를 생성합니다. + * Generates path objects from grouped test results. * @param groupedResults */ private generatePaths( @@ -145,7 +145,7 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 특정 경로와 메서드에 대한 작업 객체를 생성합니다. + * Generates an operation object for a specific path and method. * @param path * @param method * @param statusCodes diff --git a/lib/dsl/generator/TestEventManager.ts b/lib/dsl/generator/TestEventManager.ts index 6ee1c9e5..0848bd5f 100644 --- a/lib/dsl/generator/TestEventManager.ts +++ b/lib/dsl/generator/TestEventManager.ts @@ -21,13 +21,13 @@ import { getOutputPath } from "../../config/getOutputPath" import * as path from "path" import { generateDocs } from "../../../script/makedocs" /** - * TestEventManager는 테스트 이벤트를 관리하고 테스트 상태를 추적하는 싱글톤 클래스입니다. + * TestEventManager is a singleton class that manages test events and tracks test status. * - * 이 클래스는 다음과 같은 역할을 합니다: - * - 테스트 등록: 새로운 테스트가 시작될 때 테스트 개수를 증가시킵니다. - * - 테스트 완료 추적: 테스트가 성공 또는 실패할 때마다 완료된 테스트 수를 업데이트합니다. - * - 모든 테스트가 완료되면, 실패한 테스트가 없는 경우 자동으로 OpenAPI 스펙(OAS)을 생성합니다. - * OAS는 JSON 형식으로 파일에 저장되며, 이후 문서(Markdown, HTML) 생성 작업이 실행됩니다. + * This class performs the following roles: + * - Test registration: Increases test count when new tests start. + * - Test completion tracking: Updates completed test count whenever tests succeed or fail. + * - When all tests are completed, automatically generates OpenAPI spec (OAS) if there are no failed tests. + * OAS is saved to a file in JSON format, followed by document (Markdown, HTML) generation tasks. * @class TestEventManager * @singleton */ @@ -48,13 +48,13 @@ export class TestEventManager { public registerTest(): void { this.testCount++ - logger.debug(`테스트 등록: 현재 총 ${this.testCount}개 테스트`) + logger.debug(`Test registered: Currently ${this.testCount} tests total`) } public completeTestSuccess(): void { this.completedTests++ logger.debug( - `테스트 완료: ${this.completedTests}/${this.testCount} (실패: ${this.failedTests})`, + `Test completed: ${this.completedTests}/${this.testCount} (failed: ${this.failedTests})`, ) this.checkAllTestsCompleted() } @@ -62,9 +62,9 @@ export class TestEventManager { public completeTestFailure(): void { this.completedTests++ this.failedTests++ - logger.debug(`테스트 실패: 현재 ${this.failedTests}개 실패`) + logger.debug(`Test failed: Currently ${this.failedTests} failures`) logger.debug( - `테스트 완료: ${this.completedTests}/${this.testCount} (실패: ${this.failedTests})`, + `Test completed: ${this.completedTests}/${this.testCount} (failed: ${this.failedTests})`, ) this.checkAllTestsCompleted() } @@ -80,13 +80,13 @@ export class TestEventManager { } private onAllTestsCompleted(): void { if (this.failedTests > 0) { - logger.error(`[OAS_GENERATION_SKIPPED] 실패한 테스트 수: ${this.failedTests}`) + logger.error(`[OAS_GENERATION_SKIPPED] Number of failed tests: ${this.failedTests}`) return } try { this.generateOAS() } catch (error) { - logger.error("OAS 생성 중 오류 발생:", error) + logger.error("Error occurred during OAS generation:", error) } } @@ -100,7 +100,7 @@ export class TestEventManager { const oasGenerator = OpenAPIGenerator.getInstance() exportOASToJSON(oasGenerator, oasPath) this.oasAlreadyGenerated = true - logger.info(`OAS 생성 완료: ${oasPath}`) + logger.info(`OAS generation completed: ${oasPath}`) generateDocs(oasPath, outputPath) } } diff --git a/lib/dsl/generator/TestResultCollector.ts b/lib/dsl/generator/TestResultCollector.ts index c5685c30..cb556904 100644 --- a/lib/dsl/generator/TestResultCollector.ts +++ b/lib/dsl/generator/TestResultCollector.ts @@ -17,26 +17,26 @@ import { TestResult, IOpenAPIGenerator } from "./types/TestResult" import { OpenAPIGenerator } from "./OpenAPIGenerator" -// 싱글톤 인스턴스를 저장할 변수 +// Variable to store singleton instance let instance: TestResultCollector | null = null /** - * 테스트 결과 수집기 클래스 + * Test result collector class */ export class TestResultCollector { private generator: IOpenAPIGenerator /** - * 생성자 - 싱글톤 패턴을 위해 private으로 설정 - * @param {IOpenAPIGenerator} generator OpenAPI 생성기 + * Constructor - set as private for singleton pattern + * @param {IOpenAPIGenerator} generator OpenAPI generator */ private constructor(generator: IOpenAPIGenerator) { this.generator = generator } /** - * 싱글톤 인스턴스를 반환합니다. - * @returns {TestResultCollector} TestResultCollector의 싱글톤 인스턴스 + * Returns the singleton instance. + * @returns {TestResultCollector} Singleton instance of TestResultCollector */ public static getInstance(): TestResultCollector { if (!instance) { @@ -47,8 +47,8 @@ export class TestResultCollector { } /** - * 테스트 결과를 수집합니다 - * @param {TestResult} result 테스트 결과 + * Collects test results + * @param {TestResult} result Test result */ public collectResult(result: TestResult): void { this.generator.collectTestResult(result) diff --git a/lib/dsl/generator/builders/SchemaBuilder.ts b/lib/dsl/generator/builders/SchemaBuilder.ts index e5770dc1..755fd7f8 100644 --- a/lib/dsl/generator/builders/SchemaBuilder.ts +++ b/lib/dsl/generator/builders/SchemaBuilder.ts @@ -18,29 +18,29 @@ import { SchemaFactory } from "./schema" import logger from "../../../config/logger" /** - * OpenAPI Schema 객체를 생성하기 위한 빌더 클래스 - * 이 클래스는 복잡한 스키마 생성 로직을 추상화하여 사용자가 쉽게 스키마를 생성할 수 있도록 합니다. + * Builder class for creating OpenAPI Schema objects + * This class abstracts complex schema generation logic to enable users to easily create schemas. */ export class SchemaBuilder { private schemaFactory = new SchemaFactory() /** - * 주어진 값에 대한 OpenAPI Schema를 생성합니다. - * 값의 타입에 따라 적절한 스키마 생성기를 선택하여 사용합니다. - * @param value 스키마를 생성할 값 (객체, 배열, 원시값 등) - * @returns 생성된 OpenAPI Schema 객체 + * Generates OpenAPI Schema for the given value. + * Selects and uses appropriate schema generator based on the value type. + * @param value Value to generate schema from (object, array, primitive values, etc.) + * @returns Generated OpenAPI Schema object */ public createSchema(value: unknown): Record { try { const schema = this.schemaFactory.createSchema(value) return schema as Record } catch (error) { - logger.error("스키마 생성 중 오류 발생:", error) - // 오류 발생 시 기본 스키마 반환 - return { type: "object", description: "스키마 생성 실패" } + logger.error("Error occurred during schema generation:", error) + // Return default schema when error occurs + return { type: "object", description: "Schema generation failed" } } } } -// 스키마 관련 타입 및 인터페이스 내보내기 +// Export schema-related types and interfaces export * from "./schema" diff --git a/lib/dsl/generator/builders/operation/ParameterBuilder.ts b/lib/dsl/generator/builders/operation/ParameterBuilder.ts index d07e12d4..ee43d5a3 100644 --- a/lib/dsl/generator/builders/operation/ParameterBuilder.ts +++ b/lib/dsl/generator/builders/operation/ParameterBuilder.ts @@ -22,15 +22,15 @@ import { SchemaBuilder } from "../schema" import { UtilityBuilder } from "./UtilityBuilder" /** - * OpenAPI Parameter 객체 생성을 담당하는 빌더 클래스 + * Builder class responsible for creating OpenAPI Parameter objects */ export class ParameterBuilder implements ParameterBuilderInterface { private utilityBuilder = new UtilityBuilder() /** - * 테스트 결과에서 파라미터를 추출합니다. - * @param result 테스트 결과 - * @returns 파라미터 객체 배열 + * Extracts parameters from test results. + * @param result Test result + * @returns Array of parameter objects */ public extractParameters(result: TestResult): ParameterObject[] { const parameters: ParameterObject[] = [] @@ -51,15 +51,15 @@ export class ParameterBuilder implements ParameterBuilderInterface { } /** - * 경로 파라미터를 추출합니다. - * @param pathParams 경로 파라미터 객체 - * @returns 파라미터 객체 배열 + * Extracts path parameters. + * @param pathParams Path parameter object + * @returns Array of parameter objects */ private extractPathParameters(pathParams: Record): ParameterObject[] { const parameters: ParameterObject[] = [] for (const [name, value] of Object.entries(pathParams)) { - // 기본 파라미터 객체 생성 + // Create basic parameter object const parameter: ParameterObject = { name, in: "path", @@ -69,16 +69,16 @@ export class ParameterBuilder implements ParameterBuilderInterface { }, } - // DSL 필드인 경우 메타데이터 추출 (description 및 example) + // Extract metadata for DSL fields (description and example) if (isDSLField(value)) { if (value.description) { parameter.description = value.description } - // example 값 직접 설정 (DSL 필드의 example 값 자체가 필요) + // Set example value directly (the example value of DSL field itself is needed) if (value.example !== undefined && value.example !== null) { if (isDSLField(value.example)) { - // example이 다시 DSL 필드인 경우 재귀적으로 처리 + // Process recursively if example is again a DSL field parameter.example = this.utilityBuilder.extractSimpleExampleValue( value.example, ) @@ -87,13 +87,13 @@ export class ParameterBuilder implements ParameterBuilderInterface { } } - // 스키마 생성 시 example 제외하고 생성 + // Generate schema excluding example when creating schema parameter.schema = SchemaBuilder.inferSchema(value.example, false) as Record< string, any > } else { - // 일반 값인 경우 + // For regular values parameter.schema = SchemaBuilder.inferSchema(value, false) as Record parameter.example = value } @@ -105,9 +105,9 @@ export class ParameterBuilder implements ParameterBuilderInterface { } /** - * 쿼리 파라미터를 추출합니다. - * @param queryParams 쿼리 파라미터 객체 - * @returns 파라미터 객체 배열 + * Extracts query parameters. + * @param queryParams Query parameter object + * @returns Array of parameter objects */ private extractQueryParameters(queryParams: Record): ParameterObject[] { const parameters: ParameterObject[] = [] @@ -142,9 +142,9 @@ export class ParameterBuilder implements ParameterBuilderInterface { } /** - * 헤더 파라미터를 추출합니다. - * @param headers 헤더 객체 - * @returns 파라미터 객체 배열 + * Extracts header parameters. + * @param headers Header object + * @returns Array of parameter objects */ private extractHeaderParameters(headers: Record): ParameterObject[] { const parameters: ParameterObject[] = [] diff --git a/lib/dsl/generator/builders/operation/RequestBodyBuilder.ts b/lib/dsl/generator/builders/operation/RequestBodyBuilder.ts index c86427aa..92d97e31 100644 --- a/lib/dsl/generator/builders/operation/RequestBodyBuilder.ts +++ b/lib/dsl/generator/builders/operation/RequestBodyBuilder.ts @@ -22,15 +22,15 @@ import { UtilityBuilder } from "./UtilityBuilder" import { isDSLField } from "../../../interface/field" /** - * OpenAPI RequestBody 객체 생성을 담당하는 빌더 클래스 + * Builder class responsible for creating OpenAPI RequestBody objects */ export class RequestBodyBuilder implements RequestBodyBuilderInterface { private utilityBuilder = new UtilityBuilder() /** - * 요청 본문을 생성합니다. - * @param result 테스트 결과 - * @returns 요청 본문 객체 또는 undefined + * Generates request body. + * @param result Test result + * @returns Request body object or undefined */ public generateRequestBody(result: TestResult): RequestBodyObject | undefined { if (!result.request.body) { @@ -58,9 +58,9 @@ export class RequestBodyBuilder implements RequestBodyBuilderInterface { } /** - * 요청의 Content-Type을 가져옵니다. - * @param request 요청 객체 - * @returns Content-Type 값 + * Gets the Content-Type of the request. + * @param request Request object + * @returns Content-Type value */ private getContentType(request: TestResult["request"]): string { if (request.headers && "content-type" in request.headers) { diff --git a/lib/dsl/generator/builders/operation/ResponseBuilder.ts b/lib/dsl/generator/builders/operation/ResponseBuilder.ts index 6f2a4f6c..aec293fc 100644 --- a/lib/dsl/generator/builders/operation/ResponseBuilder.ts +++ b/lib/dsl/generator/builders/operation/ResponseBuilder.ts @@ -21,15 +21,15 @@ import { SchemaBuilder } from "../schema" import { UtilityBuilder } from "./UtilityBuilder" /** - * OpenAPI Response 객체 생성을 담당하는 빌더 클래스 + * Builder class responsible for creating OpenAPI Response objects */ export class ResponseBuilder implements ResponseBuilderInterface { private utilityBuilder = new UtilityBuilder() /** - * 응답을 생성합니다. - * @param result 테스트 결과 - * @returns 응답 객체 맵 + * Generates responses. + * @param result Test result + * @returns Response object map */ public generateResponses(result: TestResult): Record { const responses: Record = {} @@ -44,7 +44,7 @@ export class ResponseBuilder implements ResponseBuilderInterface { if (result.response.headers && Object.keys(result.response.headers).length > 0) { const headers: Record = {} - // 필터링할 기본 HTTP 헤더 목록 + // List of default HTTP headers to filter const skipHeaders = [ "x-powered-by", "content-type", @@ -62,7 +62,7 @@ export class ResponseBuilder implements ResponseBuilderInterface { ] for (const [name, value] of Object.entries(result.response.headers)) { - // 기본 헤더는 스킵 + // Skip default headers if (skipHeaders.includes(name.toLowerCase())) { continue } @@ -72,7 +72,7 @@ export class ResponseBuilder implements ResponseBuilderInterface { } } - // 헤더가 하나라도 있는 경우에만 추가 + // Add only when there is at least one header if (Object.keys(headers).length > 0) { responses[statusCode].headers = headers } @@ -106,9 +106,9 @@ export class ResponseBuilder implements ResponseBuilderInterface { } /** - * 요청 메서드에 따라 적절한 기본 응답을 추가합니다. - * @param responses 현재 응답 맵 - * @param method HTTP 메서드 + * Adds appropriate default responses based on request method. + * @param responses Current response map + * @param method HTTP method */ private addDefaultResponses(responses: Record, method: string): void { const has4xx = Object.keys(responses).some((status) => status.startsWith("4")) diff --git a/lib/dsl/generator/builders/operation/SecurityBuilder.ts b/lib/dsl/generator/builders/operation/SecurityBuilder.ts index aa98b5e7..69df803c 100644 --- a/lib/dsl/generator/builders/operation/SecurityBuilder.ts +++ b/lib/dsl/generator/builders/operation/SecurityBuilder.ts @@ -19,15 +19,15 @@ import { SecurityBuilderInterface } from "./interfaces" import { isDSLField } from "../../../interface/field" /** - * OpenAPI Security 요구사항 생성을 담당하는 빌더 클래스 + * Builder class responsible for generating OpenAPI Security requirements */ export class SecurityBuilder implements SecurityBuilderInterface { private securitySchemes: Record = {} /** - * 테스트 결과에서 보안 요구사항을 추출합니다. - * @param result 테스트 결과 - * @returns 보안 요구사항 배열 + * Extracts security requirements from test results. + * @param result Test result + * @returns Array of security requirements */ public extractSecurityRequirements(result: TestResult): Array> { const security: Array> = [] @@ -85,8 +85,8 @@ export class SecurityBuilder implements SecurityBuilderInterface { } /** - * 보안 스키마를 가져옵니다. - * @returns 현재 등록된 보안 스키마 맵 + * Gets security schemas. + * @returns Currently registered security schema map */ public getSecuritySchemes(): Record { return this.securitySchemes diff --git a/lib/dsl/generator/builders/operation/UtilityBuilder.ts b/lib/dsl/generator/builders/operation/UtilityBuilder.ts index 2e750903..2b92e4df 100644 --- a/lib/dsl/generator/builders/operation/UtilityBuilder.ts +++ b/lib/dsl/generator/builders/operation/UtilityBuilder.ts @@ -19,20 +19,20 @@ import { UtilityBuilderInterface } from "./interfaces" import { isDSLField } from "../../../interface/field" /** - * OpenAPI Operation 유틸리티 함수 클래스 + * OpenAPI Operation utility function class */ export class UtilityBuilder implements UtilityBuilderInterface { /** - * 테스트 결과로부터 operationId를 생성합니다. - * @param result 테스트 결과 - * @returns 생성된 operationId + * Generates operationId from test results. + * @param result Test result + * @returns Generated operationId */ public generateOperationId(result: TestResult): string { const method = result.method.toLowerCase() const pathSegments = result.url.split("/").filter(Boolean) const processedSegments = pathSegments.map((segment) => { if (segment.startsWith(":")) { - const paramName = segment.slice(1) // ":" 이후의 문자열 + const paramName = segment.slice(1) // String after ":" return "By" + paramName.charAt(0).toUpperCase() + paramName.slice(1) } return segment @@ -55,9 +55,9 @@ export class UtilityBuilder implements UtilityBuilderInterface { } /** - * 경로에서 기본 태그를 생성합니다. - * @param path API 경로 - * @returns 기본 태그 + * Generates default tag from path. + * @param path API path + * @returns Default tag */ public generateDefaultTag(path: string): string { const firstSegment = path.split("/").filter(Boolean)[0] @@ -67,13 +67,13 @@ export class UtilityBuilder implements UtilityBuilderInterface { } /** - * 중첩된 DSL 필드에서 실제 예제 값을 추출합니다. - * @param value 값 - * @returns 추출된 단순 예제 값 + * Extracts actual example values from nested DSL fields. + * @param value Value + * @returns Extracted simple example value */ public extractSimpleExampleValue(value: any): any { if (isDSLField(value)) { - // DSL 필드의 example 값이 또 다른 DSL 필드인 경우 재귀적으로 처리 + // Process recursively if the example value of DSL field is another DSL field if (isDSLField(value.example)) { return this.extractSimpleExampleValue(value.example) } diff --git a/lib/dsl/generator/builders/operation/interfaces.ts b/lib/dsl/generator/builders/operation/interfaces.ts index 93747cbb..73e715ba 100644 --- a/lib/dsl/generator/builders/operation/interfaces.ts +++ b/lib/dsl/generator/builders/operation/interfaces.ts @@ -18,36 +18,36 @@ import { TestResult } from "../../types/TestResult" import { ParameterObject, RequestBodyObject, ResponseObject } from "../../types/OpenAPITypes" /** - * OpenAPI Operation 객체 생성을 위한 인터페이스 + * Interface for creating OpenAPI Operation objects */ export interface OperationBuilderInterface { /** - * 테스트 결과로부터 OpenAPI Operation 객체를 생성합니다. - * @param result 테스트 결과 - * @returns OpenAPI Operation 객체 + * Creates OpenAPI Operation object from test results. + * @param result Test result + * @returns OpenAPI Operation object */ generateOperation(result: TestResult): Record } /** - * 파라미터 생성을 위한 인터페이스 + * Interface for parameter generation */ export interface ParameterBuilderInterface { /** - * 테스트 결과에서 파라미터를 추출합니다. - * @param result 테스트 결과 - * @returns 파라미터 객체 배열 + * Extracts parameters from test results. + * @param result Test result + * @returns Array of parameter objects */ extractParameters(result: TestResult): ParameterObject[] } /** - * 보안 요구사항 처리를 위한 인터페이스 + * Interface for handling security requirements */ export interface SecurityBuilderInterface { /** - * 테스트 결과에서 보안 요구사항을 추출합니다. - * @param result 테스트 결과 + * Extracts security requirements from test results. + * @param result Test result * @returns 보안 요구사항 배열 */ extractSecurityRequirements(result: TestResult): Array> diff --git a/lib/dsl/generator/builders/schema/BaseSchemaGenerator.ts b/lib/dsl/generator/builders/schema/BaseSchemaGenerator.ts index 3a7f6eb0..f13d803d 100644 --- a/lib/dsl/generator/builders/schema/BaseSchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/BaseSchemaGenerator.ts @@ -18,20 +18,20 @@ import { SchemaGenerator } from "./interfaces" import { FORMAT_PATTERNS } from "./constants" /** - * 스키마 생성기의 기본 기능을 제공하는 추상 클래스 + * Abstract class that provides basic functionality for schema generators */ export abstract class BaseSchemaGenerator implements SchemaGenerator { /** - * 값으로부터 스키마를 생성합니다. - * @param value 스키마를 생성할 값 - * @returns 생성된 OpenAPI 스키마 객체 + * Generates schema from value. + * @param value Value to generate schema from + * @returns Generated OpenAPI schema object */ public abstract generateSchema(value: unknown): Record /** - * 문자열 값의 포맷을 감지합니다. - * @param value 검사할 문자열 값 - * @returns 감지된 포맷 또는 undefined + * Detects the format of string values. + * @param value String value to check + * @returns Detected format or undefined */ protected detectStringFormat(value: string): string | undefined { if (FORMAT_PATTERNS.UUID.test(value)) { diff --git a/lib/dsl/generator/builders/schema/SchemaFactory.ts b/lib/dsl/generator/builders/schema/SchemaFactory.ts index beddde8a..bc82bad0 100644 --- a/lib/dsl/generator/builders/schema/SchemaFactory.ts +++ b/lib/dsl/generator/builders/schema/SchemaFactory.ts @@ -24,22 +24,22 @@ import { DSLFieldSchemaGenerator } from "./generators/DSLFieldSchemaGenerator" import { isDSLField } from "../../../interface/field" /** - * 스키마 제너레이터 팩토리 클래스 - * 타입에 따라 적절한 스키마 제너레이터를 선택하여 스키마를 생성합니다. + * Schema generator factory class + * Selects appropriate schema generator based on type to generate schema. */ export class SchemaFactory implements ISchemaFactory { private generators: Record = {} /** - * 팩토리 생성자 - * 기본 스키마 제너레이터들을 등록합니다. + * Factory constructor + * Registers default schema generators. */ public constructor() { this.registerDefaultGenerators() } /** - * 기본 스키마 제너레이터들을 등록합니다. + * Registers default schema generators. */ private registerDefaultGenerators(): void { this.generators["string"] = new StringSchemaGenerator() @@ -51,19 +51,19 @@ export class SchemaFactory implements ISchemaFactory { } /** - * 스키마 타입에 따른 제너레이터를 등록합니다. - * @param type 값의 타입 - * @param generator 스키마 제너레이터 인스턴스 + * Registers generator according to schema type. + * @param type Value type + * @param generator Schema generator instance */ public registerGenerator(type: string, generator: SchemaGenerator): void { this.generators[type] = generator } /** - * 값의 타입에 따라 적절한 스키마 제너레이터를 선택하여 스키마를 생성합니다. - * @param value 스키마를 생성할 값 - * @param includeExample 스키마에 example 포함 여부 (기본값: true) - * @returns 생성된 OpenAPI 스키마 + * Selects appropriate schema generator based on value type and generates schema. + * @param value Value to generate schema from + * @param includeExample Whether to include example in schema (default: true) + * @returns Generated OpenAPI schema */ public createSchema(value: unknown, includeExample: boolean = true): unknown { if (value === undefined || value === null) { diff --git a/lib/dsl/generator/builders/schema/constants.ts b/lib/dsl/generator/builders/schema/constants.ts index 8b257c76..e4b35895 100644 --- a/lib/dsl/generator/builders/schema/constants.ts +++ b/lib/dsl/generator/builders/schema/constants.ts @@ -15,7 +15,7 @@ */ /** - * 포맷 검출을 위한 정규식 패턴 + * Regular expression patterns for format detection */ export const FORMAT_PATTERNS = { UUID: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, diff --git a/lib/dsl/generator/builders/schema/generators/ArraySchemaGenerator.ts b/lib/dsl/generator/builders/schema/generators/ArraySchemaGenerator.ts index b46dc9b1..b50b74b2 100644 --- a/lib/dsl/generator/builders/schema/generators/ArraySchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/generators/ArraySchemaGenerator.ts @@ -18,14 +18,14 @@ import { BaseSchemaGenerator } from "../BaseSchemaGenerator" import { SchemaFactory } from "../interfaces" /** - * 배열 값의 스키마를 생성하는 클래스 + * Class that generates schema for array values */ export class ArraySchemaGenerator extends BaseSchemaGenerator { private schemaFactory: SchemaFactory /** - * 생성자 - * @param schemaFactory 스키마 팩토리 + * Constructor + * @param schemaFactory Schema factory */ public constructor(schemaFactory: SchemaFactory) { super() @@ -33,10 +33,10 @@ export class ArraySchemaGenerator extends BaseSchemaGenerator { } /** - * 배열 값으로부터 스키마를 생성합니다. - * @param value 배열 값 - * @param includeExample 스키마에 example 포함 여부 (기본값: true) - * @returns 생성된 스키마 + * Generates schema from array values. + * @param value Array value + * @param includeExample Whether to include example in schema (default: true) + * @returns Generated schema */ public generateSchema(value: unknown, includeExample: boolean = true): Record { const array = value as unknown[] diff --git a/lib/dsl/generator/builders/schema/generators/BooleanSchemaGenerator.ts b/lib/dsl/generator/builders/schema/generators/BooleanSchemaGenerator.ts index 5f04e1c2..b68d38d7 100644 --- a/lib/dsl/generator/builders/schema/generators/BooleanSchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/generators/BooleanSchemaGenerator.ts @@ -17,17 +17,17 @@ import { BaseSchemaGenerator } from "../BaseSchemaGenerator" /** - * 불리언 값의 스키마를 생성하는 클래스 + * Class that generates schema for boolean values */ export class BooleanSchemaGenerator extends BaseSchemaGenerator { /** - * 불리언 값으로부터 스키마를 생성합니다. - * @param value 불리언 값 - * @param includeExample 스키마에 example 포함 여부 (기본값: true) - * @returns 생성된 스키마 + * Generates schema from boolean values. + * @param value Boolean value + * @param includeExample Whether to include example in schema (default: true) + * @returns Generated schema */ public generateSchema(value: unknown, includeExample: boolean = true): Record { - // 불리언 값이 아닌 경우 기본 불리언 스키마 반환 + // Return default boolean schema if not a boolean value if (typeof value !== "boolean") { return { type: "boolean" } } @@ -36,7 +36,7 @@ export class BooleanSchemaGenerator extends BaseSchemaGenerator { type: "boolean", } - // 예제 값 설정 (선택적) + // Set example value (optional) if (includeExample) { schema.example = value } diff --git a/lib/dsl/generator/builders/schema/generators/DSLFieldSchemaGenerator.ts b/lib/dsl/generator/builders/schema/generators/DSLFieldSchemaGenerator.ts index fa9278c3..87088cdf 100644 --- a/lib/dsl/generator/builders/schema/generators/DSLFieldSchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/generators/DSLFieldSchemaGenerator.ts @@ -19,14 +19,14 @@ import { SchemaFactory } from "../interfaces" import { DSLField, FIELD_TYPES } from "../../../../interface/field" /** - * DSL 필드로부터 스키마를 생성하는 제너레이터 + * Generator that creates schema from DSL fields */ export class DSLFieldSchemaGenerator extends BaseSchemaGenerator { private factory: SchemaFactory /** - * 생성자 - * @param factory 스키마 팩토리 인스턴스 + * Constructor + * @param factory Schema factory instance */ public constructor(factory: SchemaFactory) { super() @@ -34,10 +34,10 @@ export class DSLFieldSchemaGenerator extends BaseSchemaGenerator { } /** - * DSL 필드로부터 스키마를 생성합니다. - * @param value DSL 필드 객체 - * @param includeExample 스키마에 example 포함 여부 (기본값: true) - * @returns 생성된 스키마 + * Generates schema from DSL fields. + * @param value DSL field object + * @param includeExample Whether to include example in schema (default: true) + * @returns Generated schema */ public generateSchema(value: unknown, includeExample: boolean = true): Record { const field = value as DSLField @@ -50,10 +50,10 @@ export class DSLFieldSchemaGenerator extends BaseSchemaGenerator { } /** - * 필드의 메타데이터로 스키마를 보강합니다. - * @param schema 보강할 스키마 - * @param field DSL 필드 - * @param includeExample example 필드 포함 여부 + * Enriches schema with field metadata. + * @param schema Schema to enrich + * @param field DSL field + * @param includeExample Whether to include example field */ private enrichSchemaWithMetadata( schema: Record, diff --git a/lib/dsl/generator/builders/schema/generators/NumberSchemaGenerator.ts b/lib/dsl/generator/builders/schema/generators/NumberSchemaGenerator.ts index c566908d..6b239f1e 100644 --- a/lib/dsl/generator/builders/schema/generators/NumberSchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/generators/NumberSchemaGenerator.ts @@ -17,14 +17,14 @@ import { BaseSchemaGenerator } from "../BaseSchemaGenerator" /** - * 숫자 값의 스키마를 생성하는 클래스 + * Class that generates schema for number values */ export class NumberSchemaGenerator extends BaseSchemaGenerator { /** - * 숫자 값으로부터 스키마를 생성합니다. - * @param value 숫자 값 - * @param includeExample 스키마에 example 포함 여부 (기본값: true) - * @returns 생성된 스키마 + * Generates schema from number values. + * @param value Number value + * @param includeExample Whether to include example in schema (default: true) + * @returns Generated schema */ public generateSchema(value: unknown, includeExample: boolean = true): Record { if (typeof value !== "number") { diff --git a/lib/dsl/generator/builders/schema/generators/ObjectSchemaGenerator.ts b/lib/dsl/generator/builders/schema/generators/ObjectSchemaGenerator.ts index 3ce676fc..0757c883 100644 --- a/lib/dsl/generator/builders/schema/generators/ObjectSchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/generators/ObjectSchemaGenerator.ts @@ -19,14 +19,14 @@ import { BaseSchemaGenerator } from "../BaseSchemaGenerator" import { SchemaFactory } from "../interfaces" /** - * 객체 값의 스키마를 생성하는 클래스 + * Class that generates schema for object values */ export class ObjectSchemaGenerator extends BaseSchemaGenerator { private factory: SchemaFactory /** - * 생성자 - * @param factory 스키마 팩토리 + * Constructor + * @param factory Schema factory */ public constructor(factory: SchemaFactory) { super() @@ -34,10 +34,10 @@ export class ObjectSchemaGenerator extends BaseSchemaGenerator { } /** - * 객체 값으로부터 스키마를 생성합니다. - * @param value 객체 값 - * @param includeExample 스키마에 example 포함 여부 (기본값: true) - * @returns 생성된 스키마 + * Generates schema from object values. + * @param value Object value + * @param includeExample Whether to include example in schema (default: true) + * @returns Generated schema */ public generateSchema(value: unknown, includeExample: boolean = true): Record { const obj = value as Record diff --git a/lib/dsl/generator/builders/schema/generators/StringSchemaGenerator.ts b/lib/dsl/generator/builders/schema/generators/StringSchemaGenerator.ts index d6141549..32db4029 100644 --- a/lib/dsl/generator/builders/schema/generators/StringSchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/generators/StringSchemaGenerator.ts @@ -17,14 +17,14 @@ import { BaseSchemaGenerator } from "../BaseSchemaGenerator" /** - * 문자열 값의 스키마를 생성하는 클래스 + * Class that generates schema for string values */ export class StringSchemaGenerator extends BaseSchemaGenerator { /** - * 문자열 값으로부터 스키마를 생성합니다. - * @param value 문자열 값 - * @param includeExample 스키마에 example 포함 여부 (기본값: true) - * @returns 생성된 스키마 + * Generates schema from string values. + * @param value String value + * @param includeExample Whether to include example in schema (default: true) + * @returns Generated schema */ public generateSchema(value: unknown, includeExample: boolean = true): Record { if (typeof value !== "string") { diff --git a/lib/dsl/generator/builders/schema/index.ts b/lib/dsl/generator/builders/schema/index.ts index 7a12b3c6..aaaae3e6 100644 --- a/lib/dsl/generator/builders/schema/index.ts +++ b/lib/dsl/generator/builders/schema/index.ts @@ -17,12 +17,12 @@ import { SchemaFactory } from "./SchemaFactory" import { SchemaGenerator } from "./interfaces" -// 인터페이스 및 기본 클래스 내보내기 +// Export interfaces and base classes export * from "./interfaces" export * from "./constants" export * from "./BaseSchemaGenerator" -// 스키마 생성기 내보내기 +// Export schema generators export * from "./generators/StringSchemaGenerator" export * from "./generators/NumberSchemaGenerator" export * from "./generators/BooleanSchemaGenerator" @@ -30,29 +30,29 @@ export * from "./generators/ArraySchemaGenerator" export * from "./generators/ObjectSchemaGenerator" export * from "./generators/DSLFieldSchemaGenerator" -// 팩토리 내보내기 +// Export factory export { SchemaFactory } from "./SchemaFactory" /** - * OpenAPI 스키마 생성을 담당하는 빌더 클래스 + * Builder class responsible for OpenAPI schema generation */ export class SchemaBuilder { private static schemaFactory: SchemaFactory = new SchemaFactory() /** - * 값으로부터 스키마를 추론합니다. - * @param value 스키마를 생성할 값 - * @param includeExample 스키마에 example 포함 여부 (기본값: true) - * @returns 생성된 OpenAPI 스키마 + * Infers schema from value. + * @param value Value to generate schema from + * @param includeExample Whether to include example in schema (default: true) + * @returns Generated OpenAPI schema */ public static inferSchema(value: unknown, includeExample: boolean = true): unknown { return this.schemaFactory.createSchema(value, includeExample) } /** - * 스키마 타입에 따른 제너레이터를 등록합니다. - * @param type 값의 타입 - * @param generator 스키마 제너레이터 인스턴스 + * Registers generator according to schema type. + * @param type Value type + * @param generator Schema generator instance */ public static registerGenerator(type: string, generator: SchemaGenerator): void { this.schemaFactory.registerGenerator(type, generator) diff --git a/lib/dsl/generator/builders/schema/interfaces.ts b/lib/dsl/generator/builders/schema/interfaces.ts index a3c07224..8629b648 100644 --- a/lib/dsl/generator/builders/schema/interfaces.ts +++ b/lib/dsl/generator/builders/schema/interfaces.ts @@ -15,34 +15,34 @@ */ /** - * 스키마 생성 인터페이스 + * Schema generation interface */ export interface SchemaGenerator { /** - * 값으로부터 스키마를 생성합니다. - * @param value 스키마를 생성할 값 - * @param includeExample 스키마에 example 필드 포함 여부 - * @returns 생성된 스키마 + * Generates schema from value. + * @param value Value to generate schema from + * @param includeExample Whether to include example field in schema + * @returns Generated schema */ generateSchema(value: unknown, includeExample?: boolean): Record } /** - * 스키마 팩토리 인터페이스 + * Schema factory interface */ export interface SchemaFactory { /** - * 값의 타입에 따라 적절한 스키마 제너레이터를 선택하여 스키마를 생성합니다. - * @param value 스키마를 생성할 값 - * @param includeExample 스키마에 example 포함 여부 (기본값: true) - * @returns 생성된 스키마 + * Selects appropriate schema generator based on value type and generates schema. + * @param value Value to generate schema from + * @param includeExample Whether to include example in schema (default: true) + * @returns Generated schema */ createSchema(value: unknown, includeExample?: boolean): unknown /** - * 스키마 타입에 따른 제너레이터를 등록합니다. - * @param type 값의 타입 - * @param generator 스키마 제너레이터 인스턴스 + * Registers generator according to schema type. + * @param type Value type + * @param generator Schema generator instance */ registerGenerator(type: string, generator: SchemaGenerator): void } diff --git a/lib/dsl/generator/commands.ts b/lib/dsl/generator/commands.ts index b714c32c..e5e99a3a 100644 --- a/lib/dsl/generator/commands.ts +++ b/lib/dsl/generator/commands.ts @@ -20,22 +20,22 @@ import { IOpenAPIGenerator } from "./types/TestResult" import logger from "../../config/logger" import _ from "lodash" /** - * 테스트 결과를 기반으로 OpenAPI Specification을 JSON 파일로 내보냅니다. - * @param {IOpenAPIGenerator} generator OAS 생성기 인스턴스 - * @param {string} outputPath 출력 파일 경로 + * Exports OpenAPI Specification to JSON file based on test results. + * @param {IOpenAPIGenerator} generator OAS generator instance + * @param {string} outputPath Output file path */ export const exportOASToJSON = (generator: IOpenAPIGenerator, outputPath: string): void => { try { if (!generator) { - throw new Error("유효한 OpenAPI 생성기가 제공되지 않았습니다.") + throw new Error("A valid OpenAPI generator was not provided.") } if (!outputPath) { - throw new Error("유효한 출력 경로가 제공되지 않았습니다.") + throw new Error("A valid output path was not provided.") } const spec = generator.generateOpenAPISpec() if (!spec) { - throw new Error("OpenAPI 스펙 생성에 실패했습니다.") + throw new Error("Failed to generate OpenAPI specification.") } const outputDir = path.dirname(path.resolve(outputPath)) if (!fs.existsSync(outputDir)) { @@ -67,7 +67,7 @@ export const exportOASToJSON = (generator: IOpenAPIGenerator, outputPath: string fs.writeFileSync(filePath, JSON.stringify(finalSpec, null, 2), "utf8") logger.debug(`OpenAPI Specification exported to ${outputPath}`) } catch (error) { - const errorMessage = error instanceof Error ? error.message : "알 수 없는 오류 발생" - logger.error(`OpenAPI Specification 내보내기 실패: ${errorMessage}`) + const errorMessage = error instanceof Error ? error.message : "Unknown error occurred" + logger.error(`Failed to export OpenAPI Specification: ${errorMessage}`) } } diff --git a/lib/dsl/generator/index.ts b/lib/dsl/generator/index.ts index 9d3f242a..74e8e076 100644 --- a/lib/dsl/generator/index.ts +++ b/lib/dsl/generator/index.ts @@ -30,10 +30,10 @@ export const resultCollector = TestResultCollector.getInstance() export const testEventManager = TestEventManager.getInstance() /** - * 테스트 실패를 기록합니다. - * 한 번이라도 호출되면 OAS 자동 생성을 건너뜁니다. + * Records test failure. + * If called even once, automatic OAS generation will be skipped. */ export const recordTestFailure = (): void => { testEventManager.completeTestFailure() - logger.debug("테스트 실패가 기록되어 OAS 생성이 건너뛰어집니다.") + logger.debug("Test failure recorded, OAS generation will be skipped.") } diff --git a/lib/dsl/generator/types/OpenAPITypes.ts b/lib/dsl/generator/types/OpenAPITypes.ts index 749baa67..ae2522cc 100644 --- a/lib/dsl/generator/types/OpenAPITypes.ts +++ b/lib/dsl/generator/types/OpenAPITypes.ts @@ -15,27 +15,27 @@ */ /** - * OpenAPI 타입 정의 + * OpenAPI type definitions */ -// 미디어 타입 객체 +// Media type object export interface MediaTypeObject { schema?: Record example?: any examples?: ExamplesObject } -// 예제 객체 +// Example object export interface ExamplesObject { [name: string]: any } -// 콘텐트 객체 +// Content object export interface Content { [mediaType: string]: MediaTypeObject } -// 파라미터 객체 +// Parameter object export interface ParameterObject { name: string in: string // "query", "header", "path", "cookie" @@ -45,31 +45,31 @@ export interface ParameterObject { example?: any } -// 헤더 객체 +// Header object export interface HeaderObject { description?: string schema?: Record example?: any } -// 요청 본문 객체 +// Request body object export interface RequestBodyObject { description?: string content: Content required?: boolean } -// 응답 객체 +// Response object export interface ResponseObject { description?: string headers?: Record content?: Content } -// 보안 스키마 타입 +// Security scheme type export type SecuritySchemeType = "apiKey" | "http" | "oauth2" | "openIdConnect" -// 보안 스키마 객체 +// Security scheme object export interface SecuritySchemeObject { type: SecuritySchemeType description?: string diff --git a/lib/dsl/generator/types/TestResult.ts b/lib/dsl/generator/types/TestResult.ts index 7ff203ab..1bdf0c3e 100644 --- a/lib/dsl/generator/types/TestResult.ts +++ b/lib/dsl/generator/types/TestResult.ts @@ -18,23 +18,23 @@ import { HttpMethod } from "../../enums" import { ApiDocOptions } from "../../interface" /** - * 테스트 결과 인터페이스 + * Test result interface * - * 이 인터페이스는 API 테스트 결과를 캡처하기 위한 정보를 담습니다. - * @property {HttpMethod} method - HTTP 메소드 (예: GET, POST 등). - * @property {string} url - 요청 URL. - * @property {ApiDocOptions} options - API 문서 생성 옵션. - * @property {object} request - 요청 관련 정보. - * @property {unknown} [request.body] - 요청 바디 (선택 사항). - * @property {Record} [request.headers] - 요청 헤더 (선택 사항). - * @property {Record} [request.queryParams] - URL 쿼리 파라미터 (선택 사항). - * @property {Record} [request.pathParams] - URL 경로 파라미터 (선택 사항). - * @property {object} response - 응답 관련 정보. - * @property {number} response.status - HTTP 응답 상태 코드. - * @property {unknown} [response.body] - 응답 바디 (선택 사항). - * @property {Record} [response.headers] - 응답 헤더 (선택 사항). - * @property {string} [testSuiteDescription] - 테스트 컨텍스트 설명. 예를 들어, - * itDoc("테스트 컨텍스트", () => { ... })에서 "테스트 컨텍스트"에 해당하는 부분. + * This interface contains information for capturing API test results. + * @property {HttpMethod} method - HTTP method (e.g., GET, POST, etc.). + * @property {string} url - Request URL. + * @property {ApiDocOptions} options - API documentation generation options. + * @property {object} request - Request-related information. + * @property {unknown} [request.body] - Request body (optional). + * @property {Record} [request.headers] - Request headers (optional). + * @property {Record} [request.queryParams] - URL query parameters (optional). + * @property {Record} [request.pathParams] - URL path parameters (optional). + * @property {object} response - Response-related information. + * @property {number} response.status - HTTP response status code. + * @property {unknown} [response.body] - Response body (optional). + * @property {Record} [response.headers] - Response headers (optional). + * @property {string} [testSuiteDescription] - Test context description. For example, + * the "test context" part in itDoc("test context", () => { ... }). */ export interface TestResult { method: HttpMethod @@ -55,9 +55,9 @@ export interface TestResult { } /** - * OpenAPI Specification 생성기 인터페이스 + * OpenAPI Specification generator interface * - * 이 인터페이스는 테스트 결과를 기반으로 OpenAPI 문서를 생성하는 부분을 담당합니다. + * This interface is responsible for generating OpenAPI documents based on test results. * @interface IOpenAPIGenerator */ export interface IOpenAPIGenerator { diff --git a/lib/dsl/interface/ItdocBuilderEntry.ts b/lib/dsl/interface/ItdocBuilderEntry.ts index f6c476a1..5fb7aa16 100644 --- a/lib/dsl/interface/ItdocBuilderEntry.ts +++ b/lib/dsl/interface/ItdocBuilderEntry.ts @@ -19,7 +19,7 @@ import { TestCaseConfig } from "../test-builders/TestCaseConfig" import { RootBuilder } from "../test-builders/RootBuilder" /** - * Describe API에 넘길 옵션 인터페이스 + * Option interface to pass to Describe API */ export class ItdocBuilderEntry { public readonly method: HttpMethod @@ -44,10 +44,10 @@ export class ItdocBuilderEntry { } /** - * Describe API에 넘길 옵션 인터페이스 - * @param name API 이름 (한줄 설명) - * @param tag API 태그 - * @param description API 상세 설명 + * Option interface to pass to Describe API + * @param name API name (one-line description) + * @param tag API tag + * @param description API detailed description */ export interface ApiDocOptions { summary?: string diff --git a/lib/dsl/interface/describeAPI.ts b/lib/dsl/interface/describeAPI.ts index f6c35d38..aa61b518 100644 --- a/lib/dsl/interface/describeAPI.ts +++ b/lib/dsl/interface/describeAPI.ts @@ -18,18 +18,18 @@ import { HttpMethod } from "../enums" import { getTestAdapterExports } from "../adapters" import { ItdocBuilderEntry, ApiDocOptions } from "./ItdocBuilderEntry" /** - * API 명세를 위한 describe 함수 - * @param method {HttpMethod} HTTP 메서드 + * Describe function for API specification + * @param method {HttpMethod} HTTP method * @param url {string} API URL - * @param options {ApiDocOptions} API 문서 옵션 - * @param app Express 앱 인스턴스 (supertest 생성에 사용) - * @param callback API 테스트 함수 + * @param options {ApiDocOptions} API documentation options + * @param app Express app instance (used for supertest creation) + * @param callback API test function */ export const describeAPI = ( method: HttpMethod, url: string, options: ApiDocOptions, - app: unknown, // TODO: 이거 타입지정 + app: unknown, // TODO: Type specification for this callback: (apiDoc: ItdocBuilderEntry) => void, ): void => { if (!options.summary) { diff --git a/lib/dsl/interface/field.ts b/lib/dsl/interface/field.ts index 367f8813..108ce7f5 100644 --- a/lib/dsl/interface/field.ts +++ b/lib/dsl/interface/field.ts @@ -23,8 +23,8 @@ export type FIELD_TYPES = | FIELD_TYPES[] /** - * DSL Field 인터페이스 - * - example은 값 또는 값 검증 함수일 수 있습니다. + * DSL Field interface + * - example can be a value or value validation function. */ export interface DSLField { readonly description: string @@ -34,11 +34,11 @@ export interface DSLField { /** * DSL Helper Functions - * - DSLField 생성 함수 - * @param description {string} 문서에 표시될 필드 설명 - * @param example {object | function} 필드의 예시 값 또는 검증 함수 - * @param required {boolean} 필드가 필수인지 여부 - * @returns {DSLField} DSL Field 인터페이스 + * - DSL Field creation function + * @param description {string} Field description to be displayed in documentation + * @param example {object | function} Example value or validation function for the field + * @param required {boolean} Whether the field is required + * @returns {DSLField} DSL Field interface */ export function field( description: string, @@ -49,11 +49,11 @@ export function field( } /** - * DSL Field 타입 가드 + * DSL Field type guard * @description * @param obj - * 값이 DSL Field 타입인지 확인합니다. - * @returns {boolean} DSL Field 여부 + * Checks if the value is of DSL Field type. + * @returns {boolean} Whether it is a DSL Field */ export const isDSLField = (obj: any): obj is DSLField => obj && typeof obj === "object" && "example" in obj && "description" in obj diff --git a/lib/dsl/interface/itDoc.ts b/lib/dsl/interface/itDoc.ts index 4cf1acfa..827d76b4 100644 --- a/lib/dsl/interface/itDoc.ts +++ b/lib/dsl/interface/itDoc.ts @@ -23,11 +23,11 @@ export const itDoc = ( testFn: () => Promise | Promise | void | TestResult, ): void => { if (!description) { - throw new Error("테스트 설명이 itDoc에 필요합니다.") + throw new Error("Test description is required for itDoc.") } if (!testFn) { - throw new Error("테스트 함수가 itDoc에 필요합니다.") + throw new Error("Test function is required for itDoc.") } testEventManager.registerTest() diff --git a/lib/dsl/interface/testContext.ts b/lib/dsl/interface/testContext.ts index 264cdeb9..76f0cb3b 100644 --- a/lib/dsl/interface/testContext.ts +++ b/lib/dsl/interface/testContext.ts @@ -19,9 +19,9 @@ import { AsyncLocalStorage } from "async_hooks" const asyncLocalStorage = new AsyncLocalStorage<{ description: string }>() /** - * itDoc("패스워드가 8자 미만이면 에러가 발생한다", () => { + * itDoc("Error occurs when password is less than 8 characters", () => { * - * 에서 "패스워드가 8자 미만이면 에러가 발생한다" 같은 테스트 설명을 기록/공유하기 위한 유틸입니다. + * Utility for recording/sharing test descriptions like "Error occurs when password is less than 8 characters". */ export const testContext = { run(description: string, fn: () => Promise | T): Promise | T { diff --git a/lib/dsl/test-builders/AbstractTestBuilder.ts b/lib/dsl/test-builders/AbstractTestBuilder.ts index a58b4bee..d7c4d525 100644 --- a/lib/dsl/test-builders/AbstractTestBuilder.ts +++ b/lib/dsl/test-builders/AbstractTestBuilder.ts @@ -18,7 +18,7 @@ import { TestCaseConfig } from "./TestCaseConfig" import { HttpMethod } from "../enums" /** - * test-builders 하위 빌더 클래스들의 공통 설정이 포함된 추상 클래스입니다. + * Abstract class containing common settings for builder classes under test-builders. * @see https://github.com/do-pa/itdoc/issues/10 */ export abstract class AbstractTestBuilder { diff --git a/lib/dsl/test-builders/RequestBuilder.ts b/lib/dsl/test-builders/RequestBuilder.ts index 43110ac8..d01c5292 100644 --- a/lib/dsl/test-builders/RequestBuilder.ts +++ b/lib/dsl/test-builders/RequestBuilder.ts @@ -21,11 +21,11 @@ import { FIELD_TYPES } from "../interface/field" import { AbstractTestBuilder } from "./AbstractTestBuilder" /** - * API 요청 정보를 설정하는 빌더 클래스입니다. + * Builder class for setting API request information. */ export class RequestBuilder extends AbstractTestBuilder { /** - * 요청시 사용할 헤더를 설정합니다. + * Sets headers to be used in requests. * @param headers */ public header(headers: Record>): this { @@ -34,7 +34,7 @@ export class RequestBuilder extends AbstractTestBuilder { } /** - * 요청 바디를 설정합니다. + * Sets the request body. * @param body */ public body(body: Record | FIELD_TYPES>): this { @@ -43,7 +43,7 @@ export class RequestBuilder extends AbstractTestBuilder { } /** - * 요청시 사용할 쿼리 파라미터를 설정합니다. + * Sets query parameters to be used in requests. * @param params */ public queryParam(params: Record): this { diff --git a/lib/dsl/test-builders/ResponseBuilder.ts b/lib/dsl/test-builders/ResponseBuilder.ts index 7795b8f6..75f3a173 100644 --- a/lib/dsl/test-builders/ResponseBuilder.ts +++ b/lib/dsl/test-builders/ResponseBuilder.ts @@ -25,7 +25,7 @@ import logger from "../../config/logger" import { testContext } from "../interface/testContext" /** - * API 응답을 검증하기 위한 결과값을 설정하는 빌더 클래스입니다. + * Builder class for setting result values to validate API responses. */ export class ResponseBuilder extends AbstractTestBuilder { public status(status: HttpStatus | number): this { diff --git a/lib/dsl/test-builders/RootBuilder.ts b/lib/dsl/test-builders/RootBuilder.ts index 6e1352c1..a83c90eb 100644 --- a/lib/dsl/test-builders/RootBuilder.ts +++ b/lib/dsl/test-builders/RootBuilder.ts @@ -18,11 +18,11 @@ import { RequestBuilder } from "./RequestBuilder" import { AbstractTestBuilder } from "./AbstractTestBuilder" /** - * RootBuilder 클래스는 API 테스트의 시작점입니다. + * The RootBuilder class is the starting point for API testing. */ export class RootBuilder extends AbstractTestBuilder { /** - * prettyPrint 설정값을 true로 설정합니다. + * Sets the prettyPrint configuration value to true. */ public prettyPrint(): this { this.config.prettyPrint = true diff --git a/lib/dsl/test-builders/TestCaseConfig.ts b/lib/dsl/test-builders/TestCaseConfig.ts index 0744db2f..97a6ec46 100644 --- a/lib/dsl/test-builders/TestCaseConfig.ts +++ b/lib/dsl/test-builders/TestCaseConfig.ts @@ -23,11 +23,11 @@ export type PATH_PARAM_TYPES = string | number export type QUERY_PARAM_TYPES = string | number | boolean /** - * 각 testcase 마다 설정하는 설정값을 정의합니다. + * Defines configuration values set for each test case. */ export interface TestCaseConfig { /** - * API 문서화를 위한 옵션 + * Options for API documentation */ apiOptions?: ApiDocOptions pathParams?: Record | PATH_PARAM_TYPES> diff --git a/lib/dsl/test-builders/validateResponse.ts b/lib/dsl/test-builders/validateResponse.ts index 431107cc..ce22af0b 100644 --- a/lib/dsl/test-builders/validateResponse.ts +++ b/lib/dsl/test-builders/validateResponse.ts @@ -17,11 +17,11 @@ import { isDSLField } from "../interface/field" /** - * 응답에 대한 expect가 field일 경우 검증을 수행하는 함수입니다. - * @param expectedDSL - 예상되는 DSL 필드 - * @param actualVal - 실제 응답 값 - * @param path - 현재 검증 중인 경로 (재귀 호출 시 사용) - * @throws {Error} 검증 실패 시 에러를 발생시킵니다. + * Function that performs validation when the expected response is a field. + * @param expectedDSL - Expected DSL field + * @param actualVal - Actual response value + * @param path - Current path being validated (used in recursive calls) + * @throws {Error} Throws an error when validation fails. * @see {@link import('../interface/field.ts').field} */ const validateDSLField = (expectedDSL: any, actualVal: any, path: string): void => { @@ -56,10 +56,10 @@ const validateDSLField = (expectedDSL: any, actualVal: any, path: string): void } /** - * 배열 타입의 응답을 검증하는 함수 - * @param {Array} expectedArr - 예상한 응답 값 (배열) - * @param {Array} actualArr - 실제 응답 값 (배열) - * @param {string} path - 현재 검증 중인 경로 (재귀 호출 시 사용) + * Function that validates array-type responses + * @param {Array} expectedArr - Expected response value (array) + * @param {Array} actualArr - Actual response value (array) + * @param {string} path - Current path being validated (used in recursive calls) */ const validateArray = (expectedArr: any[], actualArr: any[], path: string): void => { if (!Array.isArray(actualArr)) { @@ -76,11 +76,11 @@ const validateArray = (expectedArr: any[], actualArr: any[], path: string): void } /** - * `ResponseBuilder`에서 정의한 API 응답 값의 **실질적인 검증**을 수행하는 함수입니다. - * 배열, 객체 등등 다양한 타입에 대해 분기하여 검증을 수행합니다. - * @param expected - 예상되는 응답 값 - * @param actual - 실제 응답 값 - * @param path - 현재 검증 중인 경로 (재귀 호출 시 사용) + * Function that performs **actual validation** of API response values defined in `ResponseBuilder`. + * Performs validation by branching for various types such as arrays, objects, etc. + * @param expected - Expected response value + * @param actual - Actual response value + * @param path - Current path being validated (used in recursive calls) * @see {ResponseBuilder} */ export const validateResponse = (expected: any, actual: any, path: string = ""): void => { diff --git a/lib/utils/pathResolver.ts b/lib/utils/pathResolver.ts index 268a4b0a..ed1241cc 100644 --- a/lib/utils/pathResolver.ts +++ b/lib/utils/pathResolver.ts @@ -18,10 +18,10 @@ import path from "path" import fs from "fs" /** - * "@/..." 형식의 경로를 프로젝트 루트경로를 기준으로 절대 경로로 변환합니다. - * @param inputPath - 해석할 경로 (@/path/to/file 형식) - * @param baseDir - 기준 디렉토리 (기본값: process.cwd()) - * @returns 해석된 절대 경로 + * Converts "@/..." format paths to absolute paths based on the project root path. + * @param inputPath - Path to resolve (@/path/to/file format) + * @param baseDir - Base directory (default: process.cwd()) + * @returns Resolved absolute path */ export function resolvePath(inputPath: string, baseDir: string = process.cwd()): string { if (inputPath.startsWith("@/")) { @@ -37,9 +37,9 @@ export function resolvePath(inputPath: string, baseDir: string = process.cwd()): } /** - * 프로젝트 루트 디렉토리를 찾습니다 (package.json이 있는 곳) - * @param startDir - 검색을 시작할 디렉토리 - * @returns 프로젝트 루트 디렉토리 경로 + * Finds the project root directory (where package.json exists) + * @param startDir - Directory to start the search from + * @returns Project root directory path */ function findProjectRoot(startDir: string): string { let currentDir = startDir diff --git a/lib/utils/specParser.ts b/lib/utils/specParser.ts index 94790a2b..227cf0fd 100644 --- a/lib/utils/specParser.ts +++ b/lib/utils/specParser.ts @@ -25,9 +25,9 @@ export interface ParsedSpec { } /** - * testspec.md 파일의 YAML front matter를 파싱합니다. - * @param specContent - testspec.md 파일의 전체 내용 - * @returns 파싱된 메타데이터와 콘텐츠 + * Parses the YAML front matter of the testspec.md file. + * @param specContent - Full content of the testspec.md file + * @returns Parsed metadata and content */ export function parseSpecFile(specContent: string): ParsedSpec { const frontMatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/ @@ -50,9 +50,9 @@ export function parseSpecFile(specContent: string): ParsedSpec { } /** - * 간단한 YAML 파서 (키-값 쌍만 지원) - * @param yamlContent - YAML 내용 - * @returns 파싱된 객체 + * Simple YAML parser (supports only key-value pairs) + * @param yamlContent - YAML content + * @returns Parsed object */ function parseYaml(yamlContent: string): SpecMetadata { const result: SpecMetadata = {} diff --git a/script/llm/loader/index.ts b/script/llm/loader/index.ts index 6c153493..4c4e57e5 100644 --- a/script/llm/loader/index.ts +++ b/script/llm/loader/index.ts @@ -21,11 +21,11 @@ import logger from "../../../lib/config/logger" type FileType = "spec" | "app" | "env" /** - * 주어진 타입에 따라 경로를 확인하고 파일 경로 또는 내용을 반환합니다. + * Checks the path according to the given type and returns the file path or content. * @param type "spec" | "app" | "env" - * @param filePath 입력된 경로 (상대 또는 절대) - * @param readContent true일 경우 파일 내용을 string으로 반환, false면 경로만 반환 - * @returns string (파일 내용 또는 경로) + * @param filePath Input path (relative or absolute) + * @param readContent If true, returns file content as string; if false, returns only the path + * @returns string (file content or path) */ export function loadFile(type: FileType, filePath?: string, readContent: boolean = false): string { const defaultPaths: Record = { diff --git a/script/llm/parser/analyzer/branchAnalyzer.ts b/script/llm/parser/analyzer/branchAnalyzer.ts index 60cc0afe..0b569c01 100644 --- a/script/llm/parser/analyzer/branchAnalyzer.ts +++ b/script/llm/parser/analyzer/branchAnalyzer.ts @@ -19,10 +19,10 @@ import * as t from "@babel/types" import { BranchDetail } from "../type/interface" /** - * 조건문 브랜치 키를 결정합니다 - * @param {NodePath} callPath - 호출 표현식 노드 - * @param {string} source - 소스 코드 - * @returns {string} 브랜치 키 + * Determines the conditional branch key + * @param {NodePath} callPath - Call expression node + * @param {string} source - Source code + * @returns {string} Branch key */ export function determineBranchKey(callPath: NodePath, source: string): string { const ifParent = callPath.findParent((p: any) => p.isIfStatement()) @@ -48,10 +48,10 @@ export function determineBranchKey(callPath: NodePath, source: } /** - * 응답 브랜치 세부사항을 가져오거나 생성합니다. - * @param {string} branchKey - 브랜치 키 - * @param {any} ret - 분석 결과 저장 객체 - * @returns {BranchDetail} 브랜치 세부사항 + * Gets or creates response branch details. + * @param {string} branchKey - Branch key + * @param {any} ret - Analysis result storage object + * @returns {BranchDetail} Branch details */ export function getBranchDetail(branchKey: string, ret: any): BranchDetail { if (branchKey === "default") { diff --git a/script/llm/parser/analyzer/responseAnalyzer.ts b/script/llm/parser/analyzer/responseAnalyzer.ts index ca8f4b4f..b1dfa6e3 100644 --- a/script/llm/parser/analyzer/responseAnalyzer.ts +++ b/script/llm/parser/analyzer/responseAnalyzer.ts @@ -21,9 +21,9 @@ import { extractValue } from "../utils/extractValue" import { BranchDetail } from "../type/interface" /** - * 응답 상태 코드를 처리합니다. - * @param {t.CallExpression} call - 호출 표현식 노드 - * @param {BranchDetail} target - 브랜치 세부사항 + * Handles response status codes. + * @param {t.CallExpression} call - Call expression node + * @param {BranchDetail} target - Branch details */ function handleResponseStatus(call: t.CallExpression, target: BranchDetail) { if (t.isNumericLiteral(call.arguments[0])) { @@ -32,12 +32,12 @@ function handleResponseStatus(call: t.CallExpression, target: BranchDetail) { } /** - * JSON 응답을 처리합니다. - * @param {t.CallExpression} call - 호출 표현식 노드 - * @param {BranchDetail} target - 브랜치 세부사항 - * @param {Record} localArrays - 로컬 배열 저장 객체 - * @param {Record} variableMap - 변수명과 데이터 구조 매핑 - * @param {t.File} ast - 파일 AST + * Handles JSON responses. + * @param {t.CallExpression} call - Call expression node + * @param {BranchDetail} target - Branch details + * @param {Record} localArrays - Local array storage object + * @param {Record} variableMap - Variable name to data structure mapping + * @param {t.File} ast - File AST */ function handleJsonResponse( call: t.CallExpression, @@ -57,12 +57,12 @@ function handleJsonResponse( } /** - * 헤더 설정을 처리합니다. - * @param {t.CallExpression} call - 호출 표현식 노드 - * @param {BranchDetail} target - 브랜치 세부사항 - * @param {Record} localArrays - 로컬 배열 저장 객체 - * @param {Record} variableMap - 변수명과 데이터 구조 매핑 - * @param {t.File} ast - 파일 AST + * Handles header settings. + * @param {t.CallExpression} call - Call expression node + * @param {BranchDetail} target - Branch details + * @param {Record} localArrays - Local array storage object + * @param {Record} variableMap - Variable name to data structure mapping + * @param {t.File} ast - File AST */ function handleHeaderResponse( call: t.CallExpression, @@ -98,12 +98,12 @@ function handleHeaderResponse( } /** - * 응답 호출을 분석합니다. - * @param {NodePath} callPath - 호출 표현식 노드 - * @param {string} source - 소스 코드 - * @param {any} ret - 분석 결과 저장 객체 - * @param {Record} localArrays - 로컬 배열 저장 객체 - * @param {t.File} ast - 파일 AST + * Analyzes response calls. + * @param {NodePath} callPath - Call expression node + * @param {string} source - Source code + * @param {any} ret - Analysis result storage object + * @param {Record} localArrays - Local array storage object + * @param {t.File} ast - File AST */ export function analyzeResponseCall( callPath: NodePath, diff --git a/script/llm/parser/analyzer/returnValueExtractor.ts b/script/llm/parser/analyzer/returnValueExtractor.ts index 13b4e402..5f5a5c20 100644 --- a/script/llm/parser/analyzer/returnValueExtractor.ts +++ b/script/llm/parser/analyzer/returnValueExtractor.ts @@ -23,10 +23,10 @@ import traversePkg from "@babel/traverse" const traverse = traversePkg.default /** - * 프로젝트 전체에서 관련 서비스 메서드를 동적으로 찾아 실제 리턴값을 추출합니다. - * @param {string} methodName - 찾을 메서드명 (예: getAllProducts) - * @param {string} projectRoot - 프로젝트 루트 경로 - * @returns {any} 추출된 실제 리턴값 또는 null + * Dynamically finds related service methods across the project and extracts actual return values. + * @param {string} methodName - Method name to find (e.g., getAllProducts) + * @param {string} projectRoot - Project root path + * @returns {any} Extracted actual return value or null */ export function extractActualReturnValue(methodName: string, projectRoot: string): any { try { @@ -48,9 +48,9 @@ export function extractActualReturnValue(methodName: string, projectRoot: string } /** - * 객체에 null 값이 포함되어 있는지 확인합니다. - * @param {any} obj - 확인할 객체 - * @returns {boolean} null 값 포함 여부 + * Checks if an object contains null values. + * @param {any} obj - Object to check + * @returns {boolean} Whether null values are included */ export function hasPartialNullValues(obj: any): boolean { if (obj === null || obj === undefined) return true @@ -62,10 +62,10 @@ export function hasPartialNullValues(obj: any): boolean { } /** - * AST에서 특정 메서드의 리턴값을 동적으로 추출합니다. - * @param {t.File} ast - 파일 AST - * @param {string} methodName - 메서드명 - * @returns {any} 리턴값 구조 + * Dynamically extracts return values of specific methods from AST. + * @param {t.File} ast - File AST + * @param {string} methodName - Method name + * @returns {any} Return value structure */ export function extractReturnValueFromAST(ast: t.File, methodName: string): any { let returnValue: any = null @@ -116,17 +116,17 @@ export function extractReturnValueFromAST(ast: t.File, methodName: string): any } /** - * 함수/메서드에서 리턴 구조를 추출합니다 - * @param {t.Function} func - 함수 노드 - * @param {t.File} ast - 전체 파일 AST (변수 찾기용) - * @returns {any} 리턴값 구조 + * Extracts return structure from function/method + * @param {t.Function} func - Function node + * @param {t.File} ast - Complete file AST (for variable finding) + * @returns {any} Return value structure */ export function extractReturnFromFunction(func: t.Function, ast?: t.File): any { let returnValue: any = null const visitedVariables = new Set() /** - * 재귀적으로 노드를 탐색하여 모든 ReturnStatement를 찾습니다. + * Recursively traverses nodes to find all ReturnStatements. * @param node */ function findAllReturnStatements(node: t.Node): t.ReturnStatement[] { @@ -153,8 +153,8 @@ export function extractReturnFromFunction(func: t.Function, ast?: t.File): any { } /** - * 가장 의미있는 ReturnStatement를 선택합니다. - * undefined나 null보다는 실제 값을 우선적으로 선택합니다. + * Selects the most meaningful ReturnStatement. + * Prioritizes actual values over undefined or null. * @param returnStatements */ function selectBestReturnStatement( diff --git a/script/llm/parser/analyzer/variableAnalyzer.ts b/script/llm/parser/analyzer/variableAnalyzer.ts index a9096520..fceb9757 100644 --- a/script/llm/parser/analyzer/variableAnalyzer.ts +++ b/script/llm/parser/analyzer/variableAnalyzer.ts @@ -19,10 +19,10 @@ import * as t from "@babel/types" import { createFunctionIdentifier } from "../utils/extractValue" /** - * 변수 선언에서 요청 매개변수와 함수 호출 결과를 분석합니다. - * @param {NodePath} varPath - 변수 선언 노드 - * @param {any} ret - 분석 결과 저장 객체 - * @param {Record} localArrays - 로컬 배열 저장 객체 + * Analyzes request parameters and function call results from variable declarations. + * @param {NodePath} varPath - Variable declaration node + * @param {any} ret - Analysis result storage object + * @param {Record} localArrays - Local array storage object */ export function analyzeVariableDeclarator( varPath: NodePath, @@ -84,9 +84,9 @@ export function analyzeVariableDeclarator( } /** - * 멤버 표현식에서 요청 매개변수를 분석합니다. - * @param {NodePath} memPath - 멤버 표현식 노드 - * @param {any} ret - 분석 결과 저장 객체 + * Analyzes request parameters from member expressions. + * @param {NodePath} memPath - Member expression node + * @param {any} ret - Analysis result storage object */ export function analyzeMemberExpression(memPath: NodePath, ret: any) { const mm = memPath.node diff --git a/script/llm/parser/collector/routeCollector.ts b/script/llm/parser/collector/routeCollector.ts index 3c1dd5a9..7ea37307 100644 --- a/script/llm/parser/collector/routeCollector.ts +++ b/script/llm/parser/collector/routeCollector.ts @@ -22,9 +22,9 @@ import { RoutePrefix } from "../type/interface" import { parseFile } from "../utils/fileParser" /** - * app.use() 호출을 찾아 라우트 프리픽스를 수집합니다. - * @param {string[]} files - 분석할 파일 목록 - * @returns {RoutePrefix[]} 라우트 프리픽스 목록 + * Finds app.use() calls and collects route prefixes. + * @param {string[]} files - List of files to analyze + * @returns {RoutePrefix[]} List of route prefixes */ export function collectRoutePrefixes(files: string[]): RoutePrefix[] { const routePrefixes: RoutePrefix[] = [] @@ -73,9 +73,9 @@ export function collectRoutePrefixes(files: string[]): RoutePrefix[] { } /** - * 파일에서 내보낸 라우터 정보를 수집합니다. - * @param {t.File} ast - 파일 AST - * @returns {Record} 내보낸 라우터 정보 + * Collects exported router information from a file. + * @param {t.File} ast - File AST + * @returns {Record} Exported router information */ export function collectExportedRouters(ast: t.File): Record { const exportedRouters: Record = {} @@ -97,11 +97,11 @@ export function collectExportedRouters(ast: t.File): Record { } /** - * 라우트 프리픽스를 결정합니다. - * @param {string} obj - 객체 이름 - * @param {Record} exportedRouters - 내보낸 라우터 정보 - * @param {RoutePrefix[]} routePrefixes - 라우트 프리픽스 목록 - * @returns {string} 라우트 프리픽스 + * Determines the route prefix. + * @param {string} obj - Object name + * @param {Record} exportedRouters - Exported router information + * @param {RoutePrefix[]} routePrefixes - List of route prefixes + * @returns {string} Route prefix */ export function determineRoutePrefix( obj: string, @@ -125,10 +125,10 @@ export function determineRoutePrefix( } /** - * 전체 경로를 구성합니다. - * @param {string} prefix - 라우트 프리픽스 - * @param {string} routePath - 라우트 경로 - * @returns {string} 전체 경로 + * Builds the full path. + * @param {string} prefix - Route prefix + * @param {string} routePath - Route path + * @returns {string} Full path */ export function buildFullPath(prefix: string, routePath: string): string { if (!prefix) return routePath diff --git a/script/llm/parser/index.ts b/script/llm/parser/index.ts index 850e5f03..5e087dbc 100644 --- a/script/llm/parser/index.ts +++ b/script/llm/parser/index.ts @@ -21,10 +21,10 @@ import { analyzeFileRoutes } from "./analyzer/routeAnalyzer" import logger from "../../../lib/config/logger" /** - * 주어진 Express 앱 파일을 시작점으로 - * 전체 라우트를 분석해 JSON으로 반환합니다. - * @param {string} appPath - 분석할 Express 앱 파일 경로 - * @returns {Promise} 라우트 분석 결과 + * Analyzes all routes starting from the given Express app file + * and returns the results as JSON. + * @param {string} appPath - Path to the Express app file to analyze + * @returns {Promise} Route analysis results */ export async function analyzeRoutes(appPath: string): Promise { const files = getProjectFiles(appPath) diff --git a/script/llm/parser/utils/extractValue.ts b/script/llm/parser/utils/extractValue.ts index 82773905..1a20d0a2 100644 --- a/script/llm/parser/utils/extractValue.ts +++ b/script/llm/parser/utils/extractValue.ts @@ -21,9 +21,9 @@ const traverse = traversePkg.default import { NodePath } from "@babel/traverse" /** - * 함수 호출에 대한 식별자 정보를 생성합니다. - * @param {t.CallExpression} callExpression - 함수 호출 표현식 - * @returns {object} 식별자 정보 + * Creates identifier information for function calls. + * @param {t.CallExpression} callExpression - Function call expression + * @returns {object} Identifier information */ export function createFunctionIdentifier(callExpression: t.CallExpression): object { if (t.isMemberExpression(callExpression.callee)) { @@ -52,7 +52,7 @@ export function createFunctionIdentifier(callExpression: t.CallExpression): obje } /** - * 기본 리터럴 값들을 처리합니다 + * Handles basic literal values * @param node */ function extractLiteralValue(node: t.Node): any { @@ -63,7 +63,7 @@ function extractLiteralValue(node: t.Node): any { } /** - * 객체 표현식을 처리합니다 + * Handles object expressions * @param node * @param localArrays * @param variableMap @@ -131,7 +131,7 @@ function extractObjectValue( } /** - * 배열 표현식을 처리합니다 + * Handles array expressions * @param node * @param localArrays * @param variableMap @@ -177,7 +177,7 @@ function extractArrayValue( } /** - * 식별자를 처리합니다 + * Handles identifiers * @param node * @param localArrays * @param variableMap @@ -208,13 +208,13 @@ function extractIdentifierValue( } /** - * 값 추출 함수 - * @param {t.Node} node - 추출할 AST 노드 - * @param {Record} localArrays - 로컬에서 정의된 배열 변수 맵 - * @param {Record} variableMap - 변수명과 데이터 구조 매핑 - * @param {t.File} ast - 전체 파일 AST (변수 추적용) - * @param {Set} visitedVariables - 순환 참조 방지용 - * @returns {any} 추출된 실제 값 또는 식별자 정보 + * Value extraction function + * @param {t.Node} node - AST node to extract + * @param {Record} localArrays - Map of locally defined array variables + * @param {Record} variableMap - Variable name to data structure mapping + * @param {t.File} ast - Complete file AST (for variable tracking) + * @param {Set} visitedVariables - For preventing circular references + * @returns {any} Extracted actual value or identifier information */ export function extractValue( node: t.Node, @@ -246,13 +246,13 @@ export function extractValue( } /** - * 스프레드 연산자에서 참조하는 값을 해결합니다 - * @param {t.Node} node - 스프레드 대상 노드 - * @param {Record} localArrays - 로컬 배열 맵 - * @param {Record} variableMap - 변수 맵 - * @param {t.File} ast - 파일 AST - * @param {Set} visitedVariables - 방문한 변수들 - * @returns {any} 해결된 값 또는 null + * Resolves values referenced by spread operators + * @param {t.Node} node - Spread target node + * @param {Record} localArrays - Local array map + * @param {Record} variableMap - Variable map + * @param {t.File} ast - File AST + * @param {Set} visitedVariables - Visited variables + * @returns {any} Resolved value or null */ function resolveSpreadValue( node: t.Node, @@ -334,13 +334,13 @@ function resolveSpreadValue( } /** - * AST에서 변수의 실제 값을 찾습니다 - * @param {string} variableName - 찾을 변수명 - * @param {t.File} ast - 파일 AST - * @param {Set} visitedVariables - 방문한 변수들 (순환 참조 방지) - * @param {Record} localArrays - 로컬 배열 - * @param {Record} variableMap - 변수 맵 - * @returns {any} 변수의 실제 값 또는 null + * Finds the actual value of a variable from AST + * @param {string} variableName - Variable name to find + * @param {t.File} ast - File AST + * @param {Set} visitedVariables - Visited variables (to prevent circular references) + * @param {Record} localArrays - Local arrays + * @param {Record} variableMap - Variable map + * @returns {any} Actual value of the variable or null */ function findVariableValue( variableName: string, diff --git a/script/llm/parser/utils/fileParser.ts b/script/llm/parser/utils/fileParser.ts index 39a29cb3..86e4ac20 100644 --- a/script/llm/parser/utils/fileParser.ts +++ b/script/llm/parser/utils/fileParser.ts @@ -21,10 +21,10 @@ import dependencyTree from "dependency-tree" import * as t from "@babel/types" /** - * 주어진 의존성 트리 객체를 재귀적으로 플래트닝하여 - * 모든 파일 경로를 문자열 배열로 반환합니다. - * @param {Record} tree - dependency-tree 라이브러리로 생성된 트리 객체 - * @returns {string[]} 모든 파일 경로를 담은 문자열 배열 + * Recursively flattens the given dependency tree object + * and returns all file paths as a string array. + * @param {Record} tree - Tree object generated by the dependency-tree library + * @returns {string[]} String array containing all file paths */ function flattenTree(tree: Record): string[] { return Object.keys(tree).reduce( @@ -33,9 +33,9 @@ function flattenTree(tree: Record): string[] { ) } /** - * 프로젝트 루트로부터 모든 관련 파일을 가져옵니다. - * @param {string} projectRoot - 프로젝트 루트 경로 - * @returns {string[]} 분석 가능한 파일 목록 + * Gets all related files from the project root. + * @param {string} projectRoot - Project root path + * @returns {string[]} List of analyzable files */ export function getProjectFiles(projectRoot: string): string[] { try { @@ -56,9 +56,9 @@ export function getProjectFiles(projectRoot: string): string[] { } /** - * 파일 내용을 읽고 AST로 파싱합니다. - * @param {string} filePath - 파일 경로 - * @returns {{ source: string; ast: t.File } | null} 파일 내용과 AST + * Reads file content and parses it into AST. + * @param {string} filePath - File path + * @returns {{ source: string; ast: t.File } | null} File content and AST */ export function parseFile(filePath: string): { source: string; ast: t.File } | null { let source: string @@ -82,9 +82,9 @@ export function parseFile(filePath: string): { source: string; ast: t.File } | n } /** - * 여러 파일을 파싱하여 유효한 결과만 반환합니다. - * @param {string[]} filePaths - 파일 경로 배열 - * @returns {Array<{ filePath: string; source: string; ast: t.File }>} 파싱된 파일 정보 배열 + * Parses multiple files and returns only valid results. + * @param {string[]} filePaths - Array of file paths + * @returns {Array<{ filePath: string; source: string; ast: t.File }>} Array of parsed file information */ export function parseMultipleFiles( filePaths: string[], @@ -106,9 +106,9 @@ export function parseMultipleFiles( } /** - * 파일이 존재하고 분석 가능한지 확인합니다. - * @param {string} filePath - 파일 경로 - * @returns {boolean} 분석 가능 여부 + * Checks if a file exists and is analyzable. + * @param {string} filePath - File path + * @returns {boolean} Whether the file is analyzable */ export function isAnalyzableFile(filePath: string): boolean { return fs.existsSync(filePath) && /\.(ts|js)$/.test(filePath) diff --git a/script/llm/prompt/index.ts b/script/llm/prompt/index.ts index 4d6da275..16c3b83b 100644 --- a/script/llm/prompt/index.ts +++ b/script/llm/prompt/index.ts @@ -16,16 +16,17 @@ import { itdocExampleJs, itdocExampleTs } from "../examples/index" /** - * 주어진 테스트 내용과 언어 설정에 따라, API 문서 및 테스트 케이스를 생성하기 위한 - * itdoc함수를 출력하기 위한 프롬프트 메시지를 반환합니다. + * Returns a prompt message for generating itdoc functions to create API documentation + * and test cases based on the given test content and language settings. * - * 이 함수는 지정된 예제 파일(예: express 테스트 파일)을 읽어와 함수 예시로 포함하며, - * 입력된 테스트 내용(content)와 언어 설정(isEn)에 따라 추가 메시지를 덧붙입니다. - * @param {string} content - 테스트 내용(테스트 케이스에 대한 설명)을 담은 문자열. - * @param {boolean} isEn - true일 경우 결과물을 영어로, false일 경우 한글로 출력하도록 추가 메시지를 설정. - * @param {number} part - 여러 출력으로 나누어질 경우 현재 부분 번호 - * @param {boolean} isTypeScript - true일 경우 TypeScript로, false일 경우 JavaScript로 출력 - * @returns {string} - 생성된 프롬프트 메시지 문자열. + * This function reads specified example files (e.g., Express test files) and includes them + * as function examples, then appends additional messages according to the input test content + * and language settings. + * @param {string} content - String containing test content (description of test cases). + * @param {boolean} isEn - If true, sets additional messages to output in English; if false, in Korean. + * @param {number} part - Current part number when output is divided into multiple parts + * @param {boolean} isTypeScript - If true, outputs in TypeScript; if false, in JavaScript + * @returns {string} - Generated prompt message string. */ export function getItdocPrompt( content: string, @@ -62,9 +63,9 @@ export function getItdocPrompt( - 모든 라우터에 대한 테스트를 포함해야 합니다. - field는 field("a", "b") 처럼 2개의 매개변수를 반드시 포함해야 합니다. field로만 나오면 안됩니다. - 중복되는 설명은 없어야 합니다. -- HTTP 헤더와 같이 하이픈(-)이 포함된 키는 반드시 큰따옴표로 감싸야 합니다. - 올바른 예시: "Cache-Control", "Last-Modified" - 잘못된 예시: Cache-Control, Last-Modified (no) +- HTTP 헤더와 같이 하이픈(-)이 포함된 키는 반드시 큰따옴표로 감싸야 합니다. + 올바른 예시: "Cache-Control", "Last-Modified" + 잘못된 예시: Cache-Control, Last-Modified (no) - 코드 설명 없이 코드만 출력해야 하며, \`(1/10)\` 같은 자동 분할 제목은 넣지 마세요. - 출력은 ${codeMessage}로만 구성되어야 하며, 백틱 블록(\`\`\`)도 사용하지 않습니다. - ${partGuide} @@ -90,33 +91,33 @@ header({ } /** - * JSON 기반 API 명세서를 마크다운 형태로 만들기 위한 프롬프트를 반환합니다. - * @param {any} content - API 정의를 담은 JSON 객체. + * Returns a prompt for creating JSON-based API specifications in Markdown format. + * @param {any} content - JSON object containing API definitions. * @param part - * @returns {string} - Markdown 생성용 프롬프트 메시지. + * @returns {string} - Prompt message for Markdown generation. */ export function getMDPrompt(content: any, part?: number): string { const partNote = part ? ` (이 문서는 ${part}번째 요청입니다)` : "" return `다음 JSON을 바탕으로 API 테스트 케이스만 Markdown 형식으로 작성하세요${partNote}. -입력 JSON: -${JSON.stringify(content, null, 2)} +입력 JSON: +${JSON.stringify(content, null, 2)} 출력 포맷 (각 항목만): - 엔드포인트 (예: GET /api/products) - 테스트 이름 (간결하게) - 요청 조건 (필요 시 요청 바디·경로 매개변수 등 자세하게 표현할 것) - 예상 응답 (상태 코드 및 반환되는 객체 또는 메시지 등 자세하게 표현할 것) -예시) +예시) PUT /api/products/:id - 테스트 이름: 제품 업데이트 성공 - 요청 조건: 유효한 제품 ID와 name, price, category 제공 - 예상 응답: 상태 코드 500, "message"가 "Server is running"인 JSON 응답, "data"에 "timestamp", "uptime", "memoryUsage" 정보 포함 지켜야 할 사항: -1. 제목·개요·요약·결론 등의 부가 설명은 절대 포함하지 마세요. -2. 일반 지침 문구(“정상 흐름과 오류 흐름을 모두 포함” 등)도 쓰지 않습니다. -3. 마크다운 강조(**), 코드 블록 안의 별도 스타일링은 사용 금지입니다. -4. 출력이 길어지면 (1 / 3), (2 / 3)처럼 순서 표기하여 분할하세요. +1. 제목·개요·요약·결론 등의 부가 설명은 절대 포함하지 마세요. +2. 일반 지침 문구(“정상 흐름과 오류 흐름을 모두 포함” 등)도 쓰지 않습니다. +3. 마크다운 강조(**), 코드 블록 안의 별도 스타일링은 사용 금지입니다. +4. 출력이 길어지면 (1 / 3), (2 / 3)처럼 순서 표기하여 분할하세요. 5. 오직 테스트 케이스 목록만, 항목별로 구분해 나열합니다. 6. DELETE, PUT, GET, POST, PATCH 앞에 - 를 붙이지 않습니다. ` diff --git a/script/makedocs/index.ts b/script/makedocs/index.ts index be5727b0..365f0cb1 100644 --- a/script/makedocs/index.ts +++ b/script/makedocs/index.ts @@ -21,35 +21,35 @@ import { join } from "path" import logger from "../../lib/config/logger" /** - * OpenAPI 파일을 Markdown 및 HTML 문서로 변환합니다. - * @param {string} oasOutputPath 변환할 OpenAPI 파일 경로 (YAML 또는 JSON) - * @param {string} outputDir 생성된 문서를 저장할 출력 디렉터리 경로 - * @returns {Promise} 변환 작업이 완료되면 해결되는 Promise + * Converts OpenAPI files to Markdown and HTML documents. + * @param {string} oasOutputPath Path to the OpenAPI file to convert (YAML or JSON) + * @param {string} outputDir Path to the output directory where generated documents will be saved + * @returns {Promise} Promise that resolves when the conversion operation is completed */ export async function generateDocs(oasOutputPath: string, outputDir: string): Promise { if (!outputDir) { - throw new Error("유효한 출력 경로가 제공되지 않았습니다.") + throw new Error("A valid output path was not provided.") } try { const markdownPath = join(outputDir, "api.md") const htmlPath = join(outputDir, "redoc.html") - logger.info(`OAS 파일 경로: ${oasOutputPath}`) - logger.info(`Markdown 경로: ${markdownPath}`) - logger.info(`HTML 경로: ${htmlPath}`) + logger.info(`OAS file path: ${oasOutputPath}`) + logger.info(`Markdown path: ${markdownPath}`) + logger.info(`HTML path: ${htmlPath}`) const config = await loadConfig({}) - logger.info("Step 1: Redocly 구성 로드 완료") + logger.info("Step 1: Redocly configuration loaded") const bundleResult = await bundle({ ref: oasOutputPath, config }) const api = bundleResult.bundle.parsed - logger.info("Step 2: OpenAPI 번들링 완료") + logger.info("Step 2: OpenAPI bundling completed") const widdershinsOpts = { headings: 2, summary: true } console.log = () => {} const markdown = await widdershins.convert(api, widdershinsOpts) await fs.writeFile(markdownPath, markdown, "utf-8") - logger.info("Step 3: Markdown 생성 완료") + logger.info("Step 3: Markdown generation completed") const safeSpec = JSON.stringify(api).replace(/ @@ -69,9 +69,9 @@ export async function generateDocs(oasOutputPath: string, outputDir: string): Pr ` await fs.writeFile(htmlPath, htmlContent, "utf-8") - logger.info("Step 4: HTML 생성 완료") + logger.info("Step 4: HTML generation completed") } catch (error: unknown) { - logger.error("문서 생성 중 오류 발생:", error) + logger.error("Error occurred during document generation:", error) process.exit(1) } } From fe1b8dc92b0175a0173a9086a7be6d72699bedd2 Mon Sep 17 00:00:00 2001 From: jaesong Date: Wed, 6 Aug 2025 01:50:05 +0900 Subject: [PATCH 2/6] docs: translate Korean JSDoc to English --- lib/dsl/generator/builders/operation/index.ts | 20 ++++------- .../builders/operation/interfaces.ts | 36 +++++++++---------- 2 files changed, 24 insertions(+), 32 deletions(-) diff --git a/lib/dsl/generator/builders/operation/index.ts b/lib/dsl/generator/builders/operation/index.ts index 8c1ed911..77a901af 100644 --- a/lib/dsl/generator/builders/operation/index.ts +++ b/lib/dsl/generator/builders/operation/index.ts @@ -14,17 +14,14 @@ * limitations under the License. */ -// 기본 인터페이스 및 상수 내보내기 export * from "./interfaces" -// 각 빌더 클래스 내보내기 export * from "./UtilityBuilder" export * from "./ParameterBuilder" export * from "./SecurityBuilder" export * from "./RequestBodyBuilder" export * from "./ResponseBuilder" -// 주요 클래스들 가져오기 import { TestResult } from "../../types/TestResult" import { OperationBuilderInterface } from "./interfaces" import { ParameterBuilder } from "./ParameterBuilder" @@ -34,7 +31,7 @@ import { ResponseBuilder } from "./ResponseBuilder" import { UtilityBuilder } from "./UtilityBuilder" /** - * OpenAPI Operation 객체 생성을 담당하는 빌더 클래스 + * Builder class responsible for creating OpenAPI Operation objects */ export class OperationBuilder implements OperationBuilderInterface { private parameterBuilder = new ParameterBuilder() @@ -44,41 +41,36 @@ export class OperationBuilder implements OperationBuilderInterface { private utilityBuilder = new UtilityBuilder() /** - * 테스트 결과로부터 OpenAPI Operation 객체를 생성합니다. - * @param result 테스트 결과 - * @returns OpenAPI Operation 객체 + * Generates an OpenAPI Operation object from test results. + * @param {TestResult} result Test result + * @returns {Record} OpenAPI Operation object */ public generateOperation(result: TestResult): Record { const operation: Record = { tags: [result.options.tag || this.utilityBuilder.generateDefaultTag(result.url)], } - // operationId 생성 및 추가 operation.operationId = this.utilityBuilder.generateOperationId(result) if (result.options.description) { operation.description = result.options.description } - // 파라미터 추출 및 설정 const parameters = this.parameterBuilder.extractParameters(result) if (parameters.length > 0) { operation.parameters = parameters } - // 보안 요구사항 추출 const security = this.securityBuilder.extractSecurityRequirements(result) if (security.length > 0) { operation.security = security } - // 요청 본문 생성 const requestBody = this.requestBodyBuilder.generateRequestBody(result) if (requestBody) { operation.requestBody = requestBody } - // 응답 생성 const responses = this.responseBuilder.generateResponses(result) operation.responses = responses @@ -86,8 +78,8 @@ export class OperationBuilder implements OperationBuilderInterface { } /** - * 보안 스키마를 가져옵니다. - * @returns 현재 등록된 보안 스키마 맵 + * Gets the security schemas. + * @returns {Record} Currently registered security schema map */ public getSecuritySchemes(): Record { return this.securityBuilder.getSecuritySchemes() diff --git a/lib/dsl/generator/builders/operation/interfaces.ts b/lib/dsl/generator/builders/operation/interfaces.ts index 73e715ba..ffe9c34e 100644 --- a/lib/dsl/generator/builders/operation/interfaces.ts +++ b/lib/dsl/generator/builders/operation/interfaces.ts @@ -48,56 +48,56 @@ export interface SecurityBuilderInterface { /** * Extracts security requirements from test results. * @param result Test result - * @returns 보안 요구사항 배열 + * @returns Array of security requirements */ extractSecurityRequirements(result: TestResult): Array> /** - * 보안 스키마를 가져옵니다. - * @returns 현재 등록된 보안 스키마 맵 + * Gets the security schemas. + * @returns Currently registered security schema map */ getSecuritySchemes(): Record } /** - * 요청 본문 생성을 위한 인터페이스 + * Interface for request body generation */ export interface RequestBodyBuilderInterface { /** - * 요청 본문을 생성합니다. - * @param result 테스트 결과 - * @returns 요청 본문 객체 또는 undefined + * Generates the request body. + * @param result Test result + * @returns Request body object or undefined */ generateRequestBody(result: TestResult): RequestBodyObject | undefined } /** - * 응답 객체 생성을 위한 인터페이스 + * Interface for response object generation */ export interface ResponseBuilderInterface { /** - * 응답을 생성합니다. - * @param result 테스트 결과 - * @returns 응답 객체 맵 + * Generates responses. + * @param result Test result + * @returns Response object map */ generateResponses(result: TestResult): Record } /** - * 유틸리티 함수를 위한 인터페이스 + * Interface for utility functions */ export interface UtilityBuilderInterface { /** - * 테스트 결과로부터 operationId를 생성합니다. - * @param result 테스트 결과 - * @returns 생성된 operationId + * Generates operationId from test results. + * @param result Test result + * @returns Generated operationId */ generateOperationId(result: TestResult): string /** - * 경로에서 기본 태그를 생성합니다. - * @param path API 경로 - * @returns 기본 태그 + * Generates default tag from path. + * @param path API path + * @returns Default tag */ generateDefaultTag(path: string): string } From 4e1b499301c4f9cf213cf6010a85aec168a8ca19 Mon Sep 17 00:00:00 2001 From: jaesong Date: Wed, 6 Aug 2025 13:15:10 +0900 Subject: [PATCH 3/6] docs: Add JSDoc type annotations and complete English translation --- lib/dsl/generator/OpenAPIGenerator.ts | 141 ++++++++---------- lib/dsl/generator/builders/SchemaBuilder.ts | 4 +- .../builders/operation/ParameterBuilder.ts | 16 +- .../builders/operation/ResponseBuilder.ts | 8 +- .../builders/operation/SecurityBuilder.ts | 6 +- .../builders/operation/UtilityBuilder.ts | 12 +- .../builders/operation/interfaces.ts | 30 ++-- .../builders/schema/BaseSchemaGenerator.ts | 8 +- .../builders/schema/SchemaFactory.ts | 10 +- .../schema/generators/ArraySchemaGenerator.ts | 8 +- .../generators/BooleanSchemaGenerator.ts | 6 +- .../generators/DSLFieldSchemaGenerator.ts | 14 +- .../generators/NumberSchemaGenerator.ts | 6 +- .../generators/ObjectSchemaGenerator.ts | 8 +- .../generators/StringSchemaGenerator.ts | 6 +- lib/dsl/generator/builders/schema/index.ts | 10 +- .../generator/builders/schema/interfaces.ts | 16 +- lib/dsl/interface/ItdocBuilderEntry.ts | 6 +- lib/dsl/interface/describeAPI.ts | 12 +- lib/dsl/interface/field.ts | 8 +- lib/dsl/test-builders/RequestBuilder.ts | 18 ++- lib/dsl/test-builders/validateResponse.ts | 20 +-- lib/utils/pathResolver.ts | 10 +- lib/utils/specParser.ts | 8 +- script/llm/loader/index.ts | 8 +- script/llm/parser/analyzer/branchAnalyzer.ts | 8 +- .../parser/analyzer/returnValueExtractor.ts | 6 +- script/llm/parser/utils/extractValue.ts | 36 +++-- script/llm/prompt/index.ts | 2 +- 29 files changed, 227 insertions(+), 224 deletions(-) diff --git a/lib/dsl/generator/OpenAPIGenerator.ts b/lib/dsl/generator/OpenAPIGenerator.ts index 812e403f..d7d9d5dd 100644 --- a/lib/dsl/generator/OpenAPIGenerator.ts +++ b/lib/dsl/generator/OpenAPIGenerator.ts @@ -24,7 +24,6 @@ import { getOpenAPITitle, } from "../../config/getOpenAPIConfig" -// 싱글톤 인스턴스를 저장할 변수 let instance: OpenAPIGenerator | null = null interface OpenAPIInfo { @@ -80,26 +79,22 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { * @returns {object} OpenAPI Specification object */ public generateOpenAPISpec(): Record { - // 테스트 결과를 그룹화 const groupedResults = this.groupTestResults() - // 경로 객체 생성 const paths = this.generatePaths(groupedResults) - // 경로 파라미터 검증 및 수정 this.validatePathParameters(paths) - // 최종 OpenAPI 문서 생성 return this.createFinalOpenAPIDocument(paths) } /** * Groups test results by path, method, and status code. + * @returns {Map>>} Grouped test results */ private groupTestResults(): Map>> { const groupedResults: Map>> = new Map() - // 테스트 결과를 그룹화 for (const result of this.testResults) { const path = result.url const method = result.method.toLowerCase() @@ -125,14 +120,14 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { /** * Generates path objects from grouped test results. - * @param groupedResults + * @param {Map>>} groupedResults Grouped test results + * @returns {Record>} Path objects */ private generatePaths( groupedResults: Map>>, ): Record> { const paths: Record> = {} - // 그룹화된 테스트 결과를 처리 for (const [path, methods] of groupedResults) { paths[path] = {} @@ -146,26 +141,23 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { /** * Generates an operation object for a specific path and method. - * @param path - * @param method - * @param statusCodes + * @param {string} path Path + * @param {string} method Method + * @param {Map} statusCodes Status codes + * @returns {Record} Operation object */ private generateOperationObject( path: string, method: string, statusCodes: Map, ): Record { - // 각 경로/메서드에 대한 작업 생성 const operationObj: Record = {} const responses: Record = {} - // 대표 테스트 결과 선택 (상태 코드 우선순위 무관) - // 이 결과는 기본 작업 정보(요약, 태그 등)를 위해 사용됨 const representativeResult = this.selectRepresentativeResult( Array.from(statusCodes.values()).flat(), ) - // 기본 작업 정보 설정 operationObj.summary = representativeResult.options?.summary || `${method.toUpperCase()} ${path} 요청` @@ -173,27 +165,20 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { operationObj.tags = [representativeResult.options.tag] } - // description 설정 추가 if (representativeResult.options?.description) { operationObj.description = representativeResult.options.description } operationObj.operationId = this.utilityBuilder.generateOperationId(representativeResult) - // 요청 본문, 파라미터 등 공통 작업 정보 this.setRequestInformation(operationObj, representativeResult) - // 각 상태 코드별 응답 처리 this.processStatusCodes(statusCodes, responses) - // 응답 정보 설정 operationObj.responses = responses - // 보안 요구사항 추출 const security = this.operationBuilder.generateOperation(representativeResult).security - // Authorization 헤더가 있으면 보안 요구사항 적용, 없으면 기본값 사용 - // security가 비어있거나 [{}]인 경우는 제외 const hasBearerAuth = security && Array.isArray(security) && @@ -206,9 +191,9 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 각 상태 코드별 응답 처리 - * @param statusCodes 상태 코드별 테스트 결과 맵 - * @param responses 응답 객체 + * Processes responses for each status code. + * @param {Map} statusCodes Status codes + * @param {Record} responses Response object */ private processStatusCodes( statusCodes: Map, @@ -239,10 +224,10 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 응답 본문이 없는 응답을 추가합니다. - * @param responses 응답 객체 - * @param statusCode 상태 코드 - * @param result 테스트 결과 + * Adds a response without content. + * @param {Record} responses Response object + * @param {string} statusCode Status code + * @param {TestResult} result Test result */ private addResponseWithoutContent( responses: Record, @@ -255,11 +240,11 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 응답 본문이 있는 경우 처리합니다. - * @param responses 응답 객체 - * @param statusCode 상태 코드 - * @param results 테스트 결과 배열 - * @param isErrorStatus 에러 상태 여부 + * Processes responses with content. + * @param {Record} responses Response object + * @param {string} statusCode Status code + * @param {TestResult[]} results Test results + * @param {boolean} isErrorStatus Whether the status code is an error status */ private processResponsesWithContent( responses: Record, @@ -281,11 +266,11 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 통합된 응답 컨텐츠를 생성합니다. - * @param results 테스트 결과 배열 - * @param statusCode 상태 코드 - * @param isErrorStatus 에러 상태 여부 - * @returns 통합된 응답 컨텐츠 + * Creates combined content. + * @param {TestResult[]} results Test results + * @param {string} statusCode Status code + * @param {boolean} isErrorStatus Whether the status code is an error status + * @returns {Record} Combined content */ private createCombinedContent( results: TestResult[], @@ -321,9 +306,9 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 기본 스키마를 생성합니다. - * @param isErrorStatus 에러 상태 여부 - * @returns 기본 스키마 객체 + * Creates a base schema. + * @param {boolean} isErrorStatus Whether the status code is an error status + * @returns {Record} Base schema object */ private createBaseSchema(isErrorStatus: boolean): Record { return isErrorStatus @@ -345,13 +330,13 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 각 컨텐츠 타입을 처리합니다. - * @param combinedContent 통합된 컨텐츠 객체 - * @param resContent 응답 컨텐츠 - * @param result 테스트 결과 - * @param statusCode 상태 코드 - * @param baseSchema 기본 스키마 - * @param isErrorStatus 에러 상태 여부 + * Processes each content type. + * @param {Record} combinedContent Combined content object + * @param {Record} resContent Response content + * @param {TestResult} result Test result + * @param {string} statusCode Status code + * @param {Record} baseSchema Base schema + * @param {boolean} isErrorStatus Whether the status code is an error status */ private processContentTypes( combinedContent: Record, @@ -393,18 +378,18 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 상태 코드가 No Content 응답인지 확인합니다. - * @param numericStatusCode 숫자 상태 코드 - * @returns No Content 응답이면 true, 그렇지 않으면 false + * Checks if the status code is No Content response. + * @param {number} numericStatusCode Numeric status code + * @returns {boolean} Whether the status code is No Content response */ private isNoContentStatusCode(numericStatusCode: number): boolean { return numericStatusCode === 204 || numericStatusCode === 304 || numericStatusCode === 100 } /** - * 응답 본문이 비어있는지 확인합니다. - * @param result 테스트 결과 객체 - * @returns {boolean} 응답 본문이 비어있으면 true, 그렇지 않으면 false + * Checks if the response body is empty. + * @param {TestResult} result Test result object + * @returns {boolean} Whether the response body is empty */ private hasEmptyResponseBody(result: TestResult): boolean { if (!result.response) { @@ -425,9 +410,9 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 테스트 케이스에서 응답 본문이 명시적으로 정의되었는지 확인합니다. - * @param result 테스트 결과 객체 - * @returns {boolean} 응답 본문이 명시적으로 정의되었으면 true, 그렇지 않으면 false + * Checks if the response body is explicitly defined in the test case. + * @param {TestResult} result Test result object + * @returns {boolean} Whether the response body is explicitly defined */ private hasResponseBodyExplicitlyDefined(result: TestResult): boolean { return ( @@ -446,8 +431,9 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 최종 OpenAPI 문서를 생성합니다. - * @param paths + * Creates the final OpenAPI document. + * @param {Record>} paths Paths + * @returns {Record} Final OpenAPI document */ private createFinalOpenAPIDocument( paths: Record>, @@ -482,12 +468,12 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * Components 섹션을 생성합니다. + * Creates the Components section. + * @returns {Record} Components section */ private createComponentsSection(): Record { const components: Record = {} - // 보안 스키마가 있으면 추가 const securitySchemes = this.operationBuilder.getSecuritySchemes() if (Object.keys(securitySchemes).length > 0) { components.securitySchemes = securitySchemes @@ -497,23 +483,20 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 여러 테스트 결과 중에서 대표 결과를 선택합니다. - * @param results 테스트 결과 배열 - * @returns 선택된 대표 테스트 결과 + * Selects the representative result from multiple test results. + * @param {TestResult[]} results Test results array + * @returns {TestResult} Representative test result */ private selectRepresentativeResult(results: TestResult[]): TestResult { - // 먼저 Authorization 헤더가 있는 테스트 케이스를 찾습니다 const authTestCase = results.find( (result) => result.request.headers && "Authorization" in result.request.headers, ) - // Authorization 헤더가 있는 테스트 케이스가 있으면 반환 if (authTestCase) { - logger.debug(`선택된 대표 테스트 케이스: Authorization 헤더 있음`) + logger.debug(`Selected representative test case: Authorization header exists`) return authTestCase } - // 그렇지 않으면 옵션 정보가 가장 많은 결과 선택 (요약, 태그 등) return results.reduce((best, current) => { const bestOptionsCount = Object.keys(best.options || {}).length const currentOptionsCount = Object.keys(current.options || {}).length @@ -522,12 +505,11 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 작업에 요청 정보를 설정합니다. - * @param operation 작업 객체 - * @param result 테스트 결과 + * Sets request information for an operation. + * @param {Record} operation Operation object + * @param {TestResult} result Test result */ private setRequestInformation(operation: Record, result: TestResult): void { - // 요청 객체 생성 - OperationBuilder가 올바르게 파라미터를 처리하도록 함 const requestObj = this.operationBuilder.generateOperation(result) if (requestObj.parameters) { @@ -538,15 +520,14 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { operation.requestBody = requestObj.requestBody } - // 보안 요구사항이 있으면 설정 if (requestObj.security) { operation.security = requestObj.security } } /** - * 경로 파라미터가 올바르게 정의되었는지 확인하고 수정합니다. - * @param {Record>} paths 경로 객체 + * Validates and modifies path parameters. + * @param {Record>} paths Path object */ private validatePathParameters(paths: Record>): void { for (const [path, pathItem] of Object.entries(paths)) { @@ -589,10 +570,10 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } /** - * 스키마에 맞게 예제를 정규화 - * @param example 예제 값 - * @param schema 스키마 정의 - * @returns 정규화된 예제 + * Normalizes examples according to the schema. + * @param {any} example Example value + * @param {Record} schema Schema definition + * @returns {any} Normalized example */ private normalizeExample(example: any, schema: Record): any { if (example === null || example === undefined || !schema) { diff --git a/lib/dsl/generator/builders/SchemaBuilder.ts b/lib/dsl/generator/builders/SchemaBuilder.ts index 755fd7f8..d4e30072 100644 --- a/lib/dsl/generator/builders/SchemaBuilder.ts +++ b/lib/dsl/generator/builders/SchemaBuilder.ts @@ -27,8 +27,8 @@ export class SchemaBuilder { /** * Generates OpenAPI Schema for the given value. * Selects and uses appropriate schema generator based on the value type. - * @param value Value to generate schema from (object, array, primitive values, etc.) - * @returns Generated OpenAPI Schema object + * @param {unknown} value Value to generate schema from (object, array, primitive values, etc.) + * @returns {Record} Generated OpenAPI Schema object */ public createSchema(value: unknown): Record { try { diff --git a/lib/dsl/generator/builders/operation/ParameterBuilder.ts b/lib/dsl/generator/builders/operation/ParameterBuilder.ts index ee43d5a3..7a07c02c 100644 --- a/lib/dsl/generator/builders/operation/ParameterBuilder.ts +++ b/lib/dsl/generator/builders/operation/ParameterBuilder.ts @@ -29,8 +29,8 @@ export class ParameterBuilder implements ParameterBuilderInterface { /** * Extracts parameters from test results. - * @param result Test result - * @returns Array of parameter objects + * @param {TestResult} result Test result + * @returns {ParameterObject[]} Array of parameter objects */ public extractParameters(result: TestResult): ParameterObject[] { const parameters: ParameterObject[] = [] @@ -52,8 +52,8 @@ export class ParameterBuilder implements ParameterBuilderInterface { /** * Extracts path parameters. - * @param pathParams Path parameter object - * @returns Array of parameter objects + * @param {Record} pathParams Path parameter object + * @returns {ParameterObject[]} Array of parameter objects */ private extractPathParameters(pathParams: Record): ParameterObject[] { const parameters: ParameterObject[] = [] @@ -106,8 +106,8 @@ export class ParameterBuilder implements ParameterBuilderInterface { /** * Extracts query parameters. - * @param queryParams Query parameter object - * @returns Array of parameter objects + * @param {Record} queryParams Query parameter object + * @returns {ParameterObject[]} Array of parameter objects */ private extractQueryParameters(queryParams: Record): ParameterObject[] { const parameters: ParameterObject[] = [] @@ -143,8 +143,8 @@ export class ParameterBuilder implements ParameterBuilderInterface { /** * Extracts header parameters. - * @param headers Header object - * @returns Array of parameter objects + * @param {Record} headers Header object + * @returns {ParameterObject[]} Array of parameter objects */ private extractHeaderParameters(headers: Record): ParameterObject[] { const parameters: ParameterObject[] = [] diff --git a/lib/dsl/generator/builders/operation/ResponseBuilder.ts b/lib/dsl/generator/builders/operation/ResponseBuilder.ts index aec293fc..4a78f615 100644 --- a/lib/dsl/generator/builders/operation/ResponseBuilder.ts +++ b/lib/dsl/generator/builders/operation/ResponseBuilder.ts @@ -28,8 +28,8 @@ export class ResponseBuilder implements ResponseBuilderInterface { /** * Generates responses. - * @param result Test result - * @returns Response object map + * @param {TestResult} result Test result + * @returns {Record} Response object map */ public generateResponses(result: TestResult): Record { const responses: Record = {} @@ -107,8 +107,8 @@ export class ResponseBuilder implements ResponseBuilderInterface { /** * Adds appropriate default responses based on request method. - * @param responses Current response map - * @param method HTTP method + * @param {Record} responses Current response map + * @param {string} method HTTP method */ private addDefaultResponses(responses: Record, method: string): void { const has4xx = Object.keys(responses).some((status) => status.startsWith("4")) diff --git a/lib/dsl/generator/builders/operation/SecurityBuilder.ts b/lib/dsl/generator/builders/operation/SecurityBuilder.ts index 69df803c..5bad9e3b 100644 --- a/lib/dsl/generator/builders/operation/SecurityBuilder.ts +++ b/lib/dsl/generator/builders/operation/SecurityBuilder.ts @@ -26,8 +26,8 @@ export class SecurityBuilder implements SecurityBuilderInterface { /** * Extracts security requirements from test results. - * @param result Test result - * @returns Array of security requirements + * @param {TestResult} result Test result + * @returns {Array>} Array of security requirements */ public extractSecurityRequirements(result: TestResult): Array> { const security: Array> = [] @@ -86,7 +86,7 @@ export class SecurityBuilder implements SecurityBuilderInterface { /** * Gets security schemas. - * @returns Currently registered security schema map + * @returns {Record} Currently registered security schema map */ public getSecuritySchemes(): Record { return this.securitySchemes diff --git a/lib/dsl/generator/builders/operation/UtilityBuilder.ts b/lib/dsl/generator/builders/operation/UtilityBuilder.ts index 2b92e4df..61d9cbd0 100644 --- a/lib/dsl/generator/builders/operation/UtilityBuilder.ts +++ b/lib/dsl/generator/builders/operation/UtilityBuilder.ts @@ -24,8 +24,8 @@ import { isDSLField } from "../../../interface/field" export class UtilityBuilder implements UtilityBuilderInterface { /** * Generates operationId from test results. - * @param result Test result - * @returns Generated operationId + * @param {TestResult} result Test result + * @returns {string} Generated operationId */ public generateOperationId(result: TestResult): string { const method = result.method.toLowerCase() @@ -56,8 +56,8 @@ export class UtilityBuilder implements UtilityBuilderInterface { /** * Generates default tag from path. - * @param path API path - * @returns Default tag + * @param {string} path API path + * @returns {string} Default tag */ public generateDefaultTag(path: string): string { const firstSegment = path.split("/").filter(Boolean)[0] @@ -68,8 +68,8 @@ export class UtilityBuilder implements UtilityBuilderInterface { /** * Extracts actual example values from nested DSL fields. - * @param value Value - * @returns Extracted simple example value + * @param {any} value Value + * @returns {any} Extracted simple example value */ public extractSimpleExampleValue(value: any): any { if (isDSLField(value)) { diff --git a/lib/dsl/generator/builders/operation/interfaces.ts b/lib/dsl/generator/builders/operation/interfaces.ts index ffe9c34e..30833232 100644 --- a/lib/dsl/generator/builders/operation/interfaces.ts +++ b/lib/dsl/generator/builders/operation/interfaces.ts @@ -23,8 +23,8 @@ import { ParameterObject, RequestBodyObject, ResponseObject } from "../../types/ export interface OperationBuilderInterface { /** * Creates OpenAPI Operation object from test results. - * @param result Test result - * @returns OpenAPI Operation object + * @param {TestResult} result Test result + * @returns {Record} OpenAPI Operation object */ generateOperation(result: TestResult): Record } @@ -35,8 +35,8 @@ export interface OperationBuilderInterface { export interface ParameterBuilderInterface { /** * Extracts parameters from test results. - * @param result Test result - * @returns Array of parameter objects + * @param {TestResult} result Test result + * @returns {ParameterObject[]} Array of parameter objects */ extractParameters(result: TestResult): ParameterObject[] } @@ -47,14 +47,14 @@ export interface ParameterBuilderInterface { export interface SecurityBuilderInterface { /** * Extracts security requirements from test results. - * @param result Test result - * @returns Array of security requirements + * @param {TestResult} result Test result + * @returns {Array>} Array of security requirements */ extractSecurityRequirements(result: TestResult): Array> /** * Gets the security schemas. - * @returns Currently registered security schema map + * @returns {Record} Currently registered security schema map */ getSecuritySchemes(): Record } @@ -65,8 +65,8 @@ export interface SecurityBuilderInterface { export interface RequestBodyBuilderInterface { /** * Generates the request body. - * @param result Test result - * @returns Request body object or undefined + * @param {TestResult} result Test result + * @returns {RequestBodyObject | undefined} Request body object or undefined */ generateRequestBody(result: TestResult): RequestBodyObject | undefined } @@ -77,8 +77,8 @@ export interface RequestBodyBuilderInterface { export interface ResponseBuilderInterface { /** * Generates responses. - * @param result Test result - * @returns Response object map + * @param {TestResult} result Test result + * @returns {Record} Response object map */ generateResponses(result: TestResult): Record } @@ -89,15 +89,15 @@ export interface ResponseBuilderInterface { export interface UtilityBuilderInterface { /** * Generates operationId from test results. - * @param result Test result - * @returns Generated operationId + * @param {TestResult} result Test result + * @returns {string} Generated operationId */ generateOperationId(result: TestResult): string /** * Generates default tag from path. - * @param path API path - * @returns Default tag + * @param {string} path API path + * @returns {string} Default tag */ generateDefaultTag(path: string): string } diff --git a/lib/dsl/generator/builders/schema/BaseSchemaGenerator.ts b/lib/dsl/generator/builders/schema/BaseSchemaGenerator.ts index f13d803d..7e8ea591 100644 --- a/lib/dsl/generator/builders/schema/BaseSchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/BaseSchemaGenerator.ts @@ -23,15 +23,15 @@ import { FORMAT_PATTERNS } from "./constants" export abstract class BaseSchemaGenerator implements SchemaGenerator { /** * Generates schema from value. - * @param value Value to generate schema from - * @returns Generated OpenAPI schema object + * @param {unknown} value Value to generate schema from + * @returns {Record} Generated OpenAPI schema object */ public abstract generateSchema(value: unknown): Record /** * Detects the format of string values. - * @param value String value to check - * @returns Detected format or undefined + * @param {string} value String value to check + * @returns {string | undefined} Detected format or undefined */ protected detectStringFormat(value: string): string | undefined { if (FORMAT_PATTERNS.UUID.test(value)) { diff --git a/lib/dsl/generator/builders/schema/SchemaFactory.ts b/lib/dsl/generator/builders/schema/SchemaFactory.ts index bc82bad0..a9c38ba3 100644 --- a/lib/dsl/generator/builders/schema/SchemaFactory.ts +++ b/lib/dsl/generator/builders/schema/SchemaFactory.ts @@ -52,8 +52,8 @@ export class SchemaFactory implements ISchemaFactory { /** * Registers generator according to schema type. - * @param type Value type - * @param generator Schema generator instance + * @param {string} type Value type + * @param {SchemaGenerator} generator Schema generator instance */ public registerGenerator(type: string, generator: SchemaGenerator): void { this.generators[type] = generator @@ -61,9 +61,9 @@ export class SchemaFactory implements ISchemaFactory { /** * Selects appropriate schema generator based on value type and generates schema. - * @param value Value to generate schema from - * @param includeExample Whether to include example in schema (default: true) - * @returns Generated OpenAPI schema + * @param {unknown} value Value to generate schema from + * @param {boolean} includeExample Whether to include example in schema (default: true) + * @returns {unknown} Generated OpenAPI schema */ public createSchema(value: unknown, includeExample: boolean = true): unknown { if (value === undefined || value === null) { diff --git a/lib/dsl/generator/builders/schema/generators/ArraySchemaGenerator.ts b/lib/dsl/generator/builders/schema/generators/ArraySchemaGenerator.ts index b50b74b2..0cd38e6a 100644 --- a/lib/dsl/generator/builders/schema/generators/ArraySchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/generators/ArraySchemaGenerator.ts @@ -25,7 +25,7 @@ export class ArraySchemaGenerator extends BaseSchemaGenerator { /** * Constructor - * @param schemaFactory Schema factory + * @param {SchemaFactory} schemaFactory Schema factory */ public constructor(schemaFactory: SchemaFactory) { super() @@ -34,9 +34,9 @@ export class ArraySchemaGenerator extends BaseSchemaGenerator { /** * Generates schema from array values. - * @param value Array value - * @param includeExample Whether to include example in schema (default: true) - * @returns Generated schema + * @param {unknown} value Array value + * @param {boolean} includeExample Whether to include example in schema (default: true) + * @returns {Record} Generated schema */ public generateSchema(value: unknown, includeExample: boolean = true): Record { const array = value as unknown[] diff --git a/lib/dsl/generator/builders/schema/generators/BooleanSchemaGenerator.ts b/lib/dsl/generator/builders/schema/generators/BooleanSchemaGenerator.ts index b68d38d7..646573b6 100644 --- a/lib/dsl/generator/builders/schema/generators/BooleanSchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/generators/BooleanSchemaGenerator.ts @@ -22,9 +22,9 @@ import { BaseSchemaGenerator } from "../BaseSchemaGenerator" export class BooleanSchemaGenerator extends BaseSchemaGenerator { /** * Generates schema from boolean values. - * @param value Boolean value - * @param includeExample Whether to include example in schema (default: true) - * @returns Generated schema + * @param {unknown} value Boolean value + * @param {boolean} includeExample Whether to include example in schema (default: true) + * @returns {Record} Generated schema */ public generateSchema(value: unknown, includeExample: boolean = true): Record { // Return default boolean schema if not a boolean value diff --git a/lib/dsl/generator/builders/schema/generators/DSLFieldSchemaGenerator.ts b/lib/dsl/generator/builders/schema/generators/DSLFieldSchemaGenerator.ts index 87088cdf..cfc30aa2 100644 --- a/lib/dsl/generator/builders/schema/generators/DSLFieldSchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/generators/DSLFieldSchemaGenerator.ts @@ -26,7 +26,7 @@ export class DSLFieldSchemaGenerator extends BaseSchemaGenerator { /** * Constructor - * @param factory Schema factory instance + * @param {SchemaFactory} factory Schema factory instance */ public constructor(factory: SchemaFactory) { super() @@ -35,9 +35,9 @@ export class DSLFieldSchemaGenerator extends BaseSchemaGenerator { /** * Generates schema from DSL fields. - * @param value DSL field object - * @param includeExample Whether to include example in schema (default: true) - * @returns Generated schema + * @param {unknown} value DSL field object + * @param {boolean} includeExample Whether to include example in schema (default: true) + * @returns {Record} Generated schema */ public generateSchema(value: unknown, includeExample: boolean = true): Record { const field = value as DSLField @@ -51,9 +51,9 @@ export class DSLFieldSchemaGenerator extends BaseSchemaGenerator { /** * Enriches schema with field metadata. - * @param schema Schema to enrich - * @param field DSL field - * @param includeExample Whether to include example field + * @param {Record} schema Schema to enrich + * @param {DSLField} field DSL field + * @param {boolean} includeExample Whether to include example field */ private enrichSchemaWithMetadata( schema: Record, diff --git a/lib/dsl/generator/builders/schema/generators/NumberSchemaGenerator.ts b/lib/dsl/generator/builders/schema/generators/NumberSchemaGenerator.ts index 6b239f1e..bc8c59fe 100644 --- a/lib/dsl/generator/builders/schema/generators/NumberSchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/generators/NumberSchemaGenerator.ts @@ -22,9 +22,9 @@ import { BaseSchemaGenerator } from "../BaseSchemaGenerator" export class NumberSchemaGenerator extends BaseSchemaGenerator { /** * Generates schema from number values. - * @param value Number value - * @param includeExample Whether to include example in schema (default: true) - * @returns Generated schema + * @param {unknown} value Number value + * @param {boolean} includeExample Whether to include example in schema (default: true) + * @returns {Record} Generated schema */ public generateSchema(value: unknown, includeExample: boolean = true): Record { if (typeof value !== "number") { diff --git a/lib/dsl/generator/builders/schema/generators/ObjectSchemaGenerator.ts b/lib/dsl/generator/builders/schema/generators/ObjectSchemaGenerator.ts index 0757c883..e8e4c4ac 100644 --- a/lib/dsl/generator/builders/schema/generators/ObjectSchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/generators/ObjectSchemaGenerator.ts @@ -26,7 +26,7 @@ export class ObjectSchemaGenerator extends BaseSchemaGenerator { /** * Constructor - * @param factory Schema factory + * @param {SchemaFactory} factory Schema factory */ public constructor(factory: SchemaFactory) { super() @@ -35,9 +35,9 @@ export class ObjectSchemaGenerator extends BaseSchemaGenerator { /** * Generates schema from object values. - * @param value Object value - * @param includeExample Whether to include example in schema (default: true) - * @returns Generated schema + * @param {unknown} value Object value + * @param {boolean} includeExample Whether to include example in schema (default: true) + * @returns {Record} Generated schema */ public generateSchema(value: unknown, includeExample: boolean = true): Record { const obj = value as Record diff --git a/lib/dsl/generator/builders/schema/generators/StringSchemaGenerator.ts b/lib/dsl/generator/builders/schema/generators/StringSchemaGenerator.ts index 32db4029..184902e5 100644 --- a/lib/dsl/generator/builders/schema/generators/StringSchemaGenerator.ts +++ b/lib/dsl/generator/builders/schema/generators/StringSchemaGenerator.ts @@ -22,9 +22,9 @@ import { BaseSchemaGenerator } from "../BaseSchemaGenerator" export class StringSchemaGenerator extends BaseSchemaGenerator { /** * Generates schema from string values. - * @param value String value - * @param includeExample Whether to include example in schema (default: true) - * @returns Generated schema + * @param {unknown} value String value + * @param {boolean} includeExample Whether to include example in schema (default: true) + * @returns {Record} Generated schema */ public generateSchema(value: unknown, includeExample: boolean = true): Record { if (typeof value !== "string") { diff --git a/lib/dsl/generator/builders/schema/index.ts b/lib/dsl/generator/builders/schema/index.ts index aaaae3e6..bef9411e 100644 --- a/lib/dsl/generator/builders/schema/index.ts +++ b/lib/dsl/generator/builders/schema/index.ts @@ -41,9 +41,9 @@ export class SchemaBuilder { /** * Infers schema from value. - * @param value Value to generate schema from - * @param includeExample Whether to include example in schema (default: true) - * @returns Generated OpenAPI schema + * @param {unknown} value Value to generate schema from + * @param {boolean} includeExample Whether to include example in schema (default: true) + * @returns {unknown} Generated OpenAPI schema */ public static inferSchema(value: unknown, includeExample: boolean = true): unknown { return this.schemaFactory.createSchema(value, includeExample) @@ -51,8 +51,8 @@ export class SchemaBuilder { /** * Registers generator according to schema type. - * @param type Value type - * @param generator Schema generator instance + * @param {string} type Value type + * @param {SchemaGenerator} generator Schema generator instance */ public static registerGenerator(type: string, generator: SchemaGenerator): void { this.schemaFactory.registerGenerator(type, generator) diff --git a/lib/dsl/generator/builders/schema/interfaces.ts b/lib/dsl/generator/builders/schema/interfaces.ts index 8629b648..cce8a7a3 100644 --- a/lib/dsl/generator/builders/schema/interfaces.ts +++ b/lib/dsl/generator/builders/schema/interfaces.ts @@ -20,9 +20,9 @@ export interface SchemaGenerator { /** * Generates schema from value. - * @param value Value to generate schema from - * @param includeExample Whether to include example field in schema - * @returns Generated schema + * @param {unknown} value Value to generate schema from + * @param {boolean} includeExample Whether to include example field in schema + * @returns {Record} Generated schema */ generateSchema(value: unknown, includeExample?: boolean): Record } @@ -33,16 +33,16 @@ export interface SchemaGenerator { export interface SchemaFactory { /** * Selects appropriate schema generator based on value type and generates schema. - * @param value Value to generate schema from - * @param includeExample Whether to include example in schema (default: true) - * @returns Generated schema + * @param {unknown} value Value to generate schema from + * @param {boolean} includeExample Whether to include example in schema (default: true) + * @returns {unknown} Generated schema */ createSchema(value: unknown, includeExample?: boolean): unknown /** * Registers generator according to schema type. - * @param type Value type - * @param generator Schema generator instance + * @param {string} type Value type + * @param {SchemaGenerator} generator Schema generator instance */ registerGenerator(type: string, generator: SchemaGenerator): void } diff --git a/lib/dsl/interface/ItdocBuilderEntry.ts b/lib/dsl/interface/ItdocBuilderEntry.ts index 5fb7aa16..87230163 100644 --- a/lib/dsl/interface/ItdocBuilderEntry.ts +++ b/lib/dsl/interface/ItdocBuilderEntry.ts @@ -45,9 +45,9 @@ export class ItdocBuilderEntry { /** * Option interface to pass to Describe API - * @param name API name (one-line description) - * @param tag API tag - * @param description API detailed description + * @param summary One-line API summary + * @param tag API tag + * @param description Detailed API description */ export interface ApiDocOptions { summary?: string diff --git a/lib/dsl/interface/describeAPI.ts b/lib/dsl/interface/describeAPI.ts index aa61b518..07377257 100644 --- a/lib/dsl/interface/describeAPI.ts +++ b/lib/dsl/interface/describeAPI.ts @@ -19,11 +19,13 @@ import { getTestAdapterExports } from "../adapters" import { ItdocBuilderEntry, ApiDocOptions } from "./ItdocBuilderEntry" /** * Describe function for API specification - * @param method {HttpMethod} HTTP method - * @param url {string} API URL - * @param options {ApiDocOptions} API documentation options - * @param app Express app instance (used for supertest creation) - * @param callback API test function + * @param {HttpMethod} method HTTP method + * @param {string} url API URL + * @param {ApiDocOptions} options API documentation options + * @param {unknown} app Express app instance (used for supertest creation) + * @param {Function} callback API test function + * @returns {void} + * @throws {Error} When required parameters are missing */ export const describeAPI = ( method: HttpMethod, diff --git a/lib/dsl/interface/field.ts b/lib/dsl/interface/field.ts index 108ce7f5..cbfbddb6 100644 --- a/lib/dsl/interface/field.ts +++ b/lib/dsl/interface/field.ts @@ -35,10 +35,10 @@ export interface DSLField { /** * DSL Helper Functions * - DSL Field creation function - * @param description {string} Field description to be displayed in documentation - * @param example {object | function} Example value or validation function for the field - * @param required {boolean} Whether the field is required - * @returns {DSLField} DSL Field interface + * @param {string} description Field description to be displayed in documentation + * @param {T | (value: T) => void} example Example value, or a validator that receives the value + * @param {boolean} required Whether the field is required + * @returns {DSLField} DSL Field interface */ export function field( description: string, diff --git a/lib/dsl/test-builders/RequestBuilder.ts b/lib/dsl/test-builders/RequestBuilder.ts index d01c5292..0cdf3c5e 100644 --- a/lib/dsl/test-builders/RequestBuilder.ts +++ b/lib/dsl/test-builders/RequestBuilder.ts @@ -26,7 +26,8 @@ import { AbstractTestBuilder } from "./AbstractTestBuilder" export class RequestBuilder extends AbstractTestBuilder { /** * Sets headers to be used in requests. - * @param headers + * @param {Record>} headers Headers to be used in requests + * @returns {this} Request builder instance */ public header(headers: Record>): this { this.config.requestHeaders = headers @@ -35,7 +36,8 @@ export class RequestBuilder extends AbstractTestBuilder { /** * Sets the request body. - * @param body + * @param {Record | FIELD_TYPES>} body Request body + * @returns {this} Request builder instance */ public body(body: Record | FIELD_TYPES>): this { this.config.requestBody = body @@ -44,18 +46,28 @@ export class RequestBuilder extends AbstractTestBuilder { /** * Sets query parameters to be used in requests. - * @param params + * @param {Record} params Query parameters to be used in requests + * @returns {this} Request builder instance */ public queryParam(params: Record): this { this.config.queryParams = params return this } + /** + * Sets path parameters to be used in requests. + * @param {Record} params Path parameters to be used in requests + * @returns {this} Request builder instance + */ public pathParam(params: Record): this { this.config.pathParams = params return this } + /** + * Creates a ResponseBuilder instance. + * @returns {ResponseBuilder} Response builder instance + */ public res(): ResponseBuilder { return new ResponseBuilder(this.config, this.method, this.url, this.app) } diff --git a/lib/dsl/test-builders/validateResponse.ts b/lib/dsl/test-builders/validateResponse.ts index ce22af0b..681f4f99 100644 --- a/lib/dsl/test-builders/validateResponse.ts +++ b/lib/dsl/test-builders/validateResponse.ts @@ -18,9 +18,9 @@ import { isDSLField } from "../interface/field" /** * Function that performs validation when the expected response is a field. - * @param expectedDSL - Expected DSL field - * @param actualVal - Actual response value - * @param path - Current path being validated (used in recursive calls) + * @param {any} expectedDSL Expected DSL field + * @param {any} actualVal Actual response value + * @param {string} path Current path being validated (used in recursive calls) * @throws {Error} Throws an error when validation fails. * @see {@link import('../interface/field.ts').field} */ @@ -57,9 +57,10 @@ const validateDSLField = (expectedDSL: any, actualVal: any, path: string): void /** * Function that validates array-type responses - * @param {Array} expectedArr - Expected response value (array) - * @param {Array} actualArr - Actual response value (array) - * @param {string} path - Current path being validated (used in recursive calls) + * @param {any[]} expectedArr Expected response value (array) + * @param {any[]} actualArr Actual response value (array) + * @param {string} path Current path being validated (used in recursive calls) + * @throws {Error} Throws an error when validation fails. */ const validateArray = (expectedArr: any[], actualArr: any[], path: string): void => { if (!Array.isArray(actualArr)) { @@ -78,9 +79,10 @@ const validateArray = (expectedArr: any[], actualArr: any[], path: string): void /** * Function that performs **actual validation** of API response values defined in `ResponseBuilder`. * Performs validation by branching for various types such as arrays, objects, etc. - * @param expected - Expected response value - * @param actual - Actual response value - * @param path - Current path being validated (used in recursive calls) + * @param {any} expected Expected response value + * @param {any} actual Actual response value + * @param {string} path Current path being validated (used in recursive calls) + * @throws {Error} Throws an error when validation fails. * @see {ResponseBuilder} */ export const validateResponse = (expected: any, actual: any, path: string = ""): void => { diff --git a/lib/utils/pathResolver.ts b/lib/utils/pathResolver.ts index ed1241cc..1ace455e 100644 --- a/lib/utils/pathResolver.ts +++ b/lib/utils/pathResolver.ts @@ -19,9 +19,9 @@ import fs from "fs" /** * Converts "@/..." format paths to absolute paths based on the project root path. - * @param inputPath - Path to resolve (@/path/to/file format) - * @param baseDir - Base directory (default: process.cwd()) - * @returns Resolved absolute path + * @param {string} inputPath Path to resolve (@/path/to/file format) + * @param {string} baseDir Base directory (default: process.cwd()) + * @returns {string} Resolved absolute path */ export function resolvePath(inputPath: string, baseDir: string = process.cwd()): string { if (inputPath.startsWith("@/")) { @@ -38,8 +38,8 @@ export function resolvePath(inputPath: string, baseDir: string = process.cwd()): /** * Finds the project root directory (where package.json exists) - * @param startDir - Directory to start the search from - * @returns Project root directory path + * @param {string} startDir Directory to start the search from + * @returns {string} Project root directory path */ function findProjectRoot(startDir: string): string { let currentDir = startDir diff --git a/lib/utils/specParser.ts b/lib/utils/specParser.ts index 227cf0fd..bef52558 100644 --- a/lib/utils/specParser.ts +++ b/lib/utils/specParser.ts @@ -26,8 +26,8 @@ export interface ParsedSpec { /** * Parses the YAML front matter of the testspec.md file. - * @param specContent - Full content of the testspec.md file - * @returns Parsed metadata and content + * @param {string} specContent Full content of the testspec.md file + * @returns {ParsedSpec} Parsed metadata and content */ export function parseSpecFile(specContent: string): ParsedSpec { const frontMatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/ @@ -51,8 +51,8 @@ export function parseSpecFile(specContent: string): ParsedSpec { /** * Simple YAML parser (supports only key-value pairs) - * @param yamlContent - YAML content - * @returns Parsed object + * @param {string} yamlContent YAML content + * @returns {SpecMetadata} Parsed object */ function parseYaml(yamlContent: string): SpecMetadata { const result: SpecMetadata = {} diff --git a/script/llm/loader/index.ts b/script/llm/loader/index.ts index 4c4e57e5..412ed21c 100644 --- a/script/llm/loader/index.ts +++ b/script/llm/loader/index.ts @@ -22,10 +22,10 @@ type FileType = "spec" | "app" | "env" /** * Checks the path according to the given type and returns the file path or content. - * @param type "spec" | "app" | "env" - * @param filePath Input path (relative or absolute) - * @param readContent If true, returns file content as string; if false, returns only the path - * @returns string (file content or path) + * @param {FileType} type "spec" | "app" | "env" + * @param {string} filePath Input path (relative or absolute) + * @param {boolean} readContent If true, returns file content as string; if false, returns only the path + * @returns {string} (file content or path) */ export function loadFile(type: FileType, filePath?: string, readContent: boolean = false): string { const defaultPaths: Record = { diff --git a/script/llm/parser/analyzer/branchAnalyzer.ts b/script/llm/parser/analyzer/branchAnalyzer.ts index 0b569c01..70bd263d 100644 --- a/script/llm/parser/analyzer/branchAnalyzer.ts +++ b/script/llm/parser/analyzer/branchAnalyzer.ts @@ -20,8 +20,8 @@ import { BranchDetail } from "../type/interface" /** * Determines the conditional branch key - * @param {NodePath} callPath - Call expression node - * @param {string} source - Source code + * @param {NodePath} callPath Call expression node + * @param {string} source Source code * @returns {string} Branch key */ export function determineBranchKey(callPath: NodePath, source: string): string { @@ -49,8 +49,8 @@ export function determineBranchKey(callPath: NodePath, source: /** * Gets or creates response branch details. - * @param {string} branchKey - Branch key - * @param {any} ret - Analysis result storage object + * @param {string} branchKey Branch key + * @param {any} ret Analysis result storage object * @returns {BranchDetail} Branch details */ export function getBranchDetail(branchKey: string, ret: any): BranchDetail { diff --git a/script/llm/parser/analyzer/returnValueExtractor.ts b/script/llm/parser/analyzer/returnValueExtractor.ts index 5f5a5c20..c8a0c7b8 100644 --- a/script/llm/parser/analyzer/returnValueExtractor.ts +++ b/script/llm/parser/analyzer/returnValueExtractor.ts @@ -127,7 +127,8 @@ export function extractReturnFromFunction(func: t.Function, ast?: t.File): any { /** * Recursively traverses nodes to find all ReturnStatements. - * @param node + * @param {t.Node} node Node to traverse + * @returns {t.ReturnStatement[]} All ReturnStatements */ function findAllReturnStatements(node: t.Node): t.ReturnStatement[] { const returns: t.ReturnStatement[] = [] @@ -155,7 +156,8 @@ export function extractReturnFromFunction(func: t.Function, ast?: t.File): any { /** * Selects the most meaningful ReturnStatement. * Prioritizes actual values over undefined or null. - * @param returnStatements + * @param {t.ReturnStatement[]} returnStatements Return statements + * @returns {t.ReturnStatement | null} The most meaningful ReturnStatement */ function selectBestReturnStatement( returnStatements: t.ReturnStatement[], diff --git a/script/llm/parser/utils/extractValue.ts b/script/llm/parser/utils/extractValue.ts index 1a20d0a2..2f0d6835 100644 --- a/script/llm/parser/utils/extractValue.ts +++ b/script/llm/parser/utils/extractValue.ts @@ -53,7 +53,8 @@ export function createFunctionIdentifier(callExpression: t.CallExpression): obje /** * Handles basic literal values - * @param node + * @param {t.Node} node Node to extract value from + * @returns {any} Extracted actual value or null */ function extractLiteralValue(node: t.Node): any { if (t.isStringLiteral(node)) return node.value @@ -64,11 +65,12 @@ function extractLiteralValue(node: t.Node): any { /** * Handles object expressions - * @param node - * @param localArrays - * @param variableMap - * @param ast - * @param visitedVariables + * @param {t.ObjectExpression} node Object expression node + * @param {Record} localArrays Local array map + * @param {Record} variableMap Variable map + * @param {t.File} ast Complete file AST (for variable tracking) + * @param {Set} visitedVariables Visited variables (to prevent circular references) + * @returns {any} Extracted actual value or null */ function extractObjectValue( node: t.ObjectExpression, @@ -132,11 +134,12 @@ function extractObjectValue( /** * Handles array expressions - * @param node - * @param localArrays - * @param variableMap - * @param ast - * @param visitedVariables + * @param {t.ArrayExpression} node Array expression node + * @param {Record} localArrays Local array map + * @param {Record} variableMap Variable map + * @param {t.File} ast Complete file AST (for variable tracking) + * @param {Set} visitedVariables Visited variables (to prevent circular references) + * @returns {any} Extracted actual value or null */ function extractArrayValue( node: t.ArrayExpression, @@ -178,11 +181,12 @@ function extractArrayValue( /** * Handles identifiers - * @param node - * @param localArrays - * @param variableMap - * @param ast - * @param visitedVariables + * @param {t.Identifier} node Identifier node + * @param {Record} localArrays Local array map + * @param {Record} variableMap Variable map + * @param {t.File} ast Complete file AST (for variable tracking) + * @param {Set} visitedVariables Visited variables (to prevent circular references) + * @returns {any} Extracted actual value or null */ function extractIdentifierValue( node: t.Identifier, diff --git a/script/llm/prompt/index.ts b/script/llm/prompt/index.ts index 16c3b83b..08cd404c 100644 --- a/script/llm/prompt/index.ts +++ b/script/llm/prompt/index.ts @@ -93,7 +93,7 @@ header({ /** * Returns a prompt for creating JSON-based API specifications in Markdown format. * @param {any} content - JSON object containing API definitions. - * @param part + * @param {number} part - Current part number when output is divided into multiple parts * @returns {string} - Prompt message for Markdown generation. */ export function getMDPrompt(content: any, part?: number): string { From 381ef929b612b5b6d56948655d1677e44a9d1991 Mon Sep 17 00:00:00 2001 From: jaesong Date: Wed, 6 Aug 2025 13:21:26 +0900 Subject: [PATCH 4/6] fix: edit logger text --- lib/dsl/generator/OpenAPIGenerator.ts | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/lib/dsl/generator/OpenAPIGenerator.ts b/lib/dsl/generator/OpenAPIGenerator.ts index d7d9d5dd..c2f55ecf 100644 --- a/lib/dsl/generator/OpenAPIGenerator.ts +++ b/lib/dsl/generator/OpenAPIGenerator.ts @@ -159,7 +159,7 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { ) operationObj.summary = - representativeResult.options?.summary || `${method.toUpperCase()} ${path} 요청` + representativeResult.options?.summary || `${method.toUpperCase()} ${path} request` if (representativeResult.options?.tag) { operationObj.tags = [representativeResult.options.tag] @@ -357,7 +357,8 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { } const exampleKey = - result.testSuiteDescription || (isErrorStatus ? "에러 응답" : "성공 응답") + result.testSuiteDescription || + (isErrorStatus ? "Error Response" : "Success Response") const exampleValue = contentObj.example || result.response.body || null if (isErrorStatus && exampleValue) { @@ -561,7 +562,7 @@ export class OpenAPIGenerator implements IOpenAPIGenerator { schema: { type: "string", }, - description: `${param} 파라미터`, + description: `${param} parameter`, }) } } From 9c02da6e6982c1ea1747213971cc13adab8019f0 Mon Sep 17 00:00:00 2001 From: jaesong Date: Wed, 6 Aug 2025 13:24:49 +0900 Subject: [PATCH 5/6] chore: update test result parameter --- examples/express/expected/oas.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/express/expected/oas.json b/examples/express/expected/oas.json index c0ecf512..9a51277f 100644 --- a/examples/express/expected/oas.json +++ b/examples/express/expected/oas.json @@ -407,7 +407,7 @@ "schema": { "type": "string" }, - "description": "friendName 파라미터" + "description": "friendName parameter" } ], "security": [{}], From a8b08d4b111178516c1aefb2d70000fdb0d89243 Mon Sep 17 00:00:00 2001 From: jaesong Date: Wed, 6 Aug 2025 13:40:03 +0900 Subject: [PATCH 6/6] docs: schemas -> schemes --- lib/dsl/generator/builders/operation/index.ts | 2 +- lib/dsl/generator/builders/operation/interfaces.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/dsl/generator/builders/operation/index.ts b/lib/dsl/generator/builders/operation/index.ts index 77a901af..27c7a48b 100644 --- a/lib/dsl/generator/builders/operation/index.ts +++ b/lib/dsl/generator/builders/operation/index.ts @@ -78,7 +78,7 @@ export class OperationBuilder implements OperationBuilderInterface { } /** - * Gets the security schemas. + * Gets the security schemes. * @returns {Record} Currently registered security schema map */ public getSecuritySchemes(): Record { diff --git a/lib/dsl/generator/builders/operation/interfaces.ts b/lib/dsl/generator/builders/operation/interfaces.ts index 30833232..cc5dd12b 100644 --- a/lib/dsl/generator/builders/operation/interfaces.ts +++ b/lib/dsl/generator/builders/operation/interfaces.ts @@ -53,7 +53,7 @@ export interface SecurityBuilderInterface { extractSecurityRequirements(result: TestResult): Array> /** - * Gets the security schemas. + * Gets the security schemes. * @returns {Record} Currently registered security schema map */ getSecuritySchemes(): Record