jsdoc-builder 0.0.5 → 0.0.7

package/README.MD

@@ -1,105 +1,316 @@
 # JSDoc Builder
 
-JSDoc Builder is a CLI tool for automatically generating JSDoc comments for JavaScript and TypeScript files. It parses functions and variables to infer parameter types, return types, and descriptions, and then inserts JSDoc comments directly into the source code.
+[English](./README.MD) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
+
+JSDoc Builder is a CLI and library that adds JSDoc comments to JavaScript/TypeScript code automatically.
+It supports JavaScript, TypeScript, JSX, TSX, and Vue SFC files.
+
+## Table of Contents
+
+- [Why JSDoc Builder](#why-jsdoc-builder)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [CLI Usage](#cli-usage)
+- [Config File](#config-file)
+- [AI Providers (OpenAI and Gemini)](#ai-providers-openai-and-gemini)
+- [Language Support for Descriptions](#language-support-for-descriptions)
+- [Vite Plugin Usage](#vite-plugin-usage)
+- [Programmatic API](#programmatic-api)
+- [Behavior and Safety](#behavior-and-safety)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
+
+## Why JSDoc Builder
+
+- Reduces repetitive JSDoc writing.
+- Keeps function docs consistent across mixed JS/TS/Vue codebases.
+- Works as:
+  - CLI for one-off or script-based use
+  - Library API for custom tooling
+  - Vite plugin for on-the-fly transform during dev/build
 
 ## Features
 
-- Automatically generates JSDoc comments for:
+- Generates JSDoc for:
   - Function declarations
-  - Arrow functions
-  - TypeScript types and interfaces
-- Infers parameter and return types from TypeScript annotations.
-- Outputs clean and structured JSDoc comments.
+  - Arrow functions assigned to variables
+  - Function expressions assigned to variables
+- Supported file types:
+  - `.js`, `.mjs`, `.cjs`
+  - `.ts`
+  - `.jsx`
+  - `.tsx`
+  - `.vue` (updates only `<script>` content)
+- Skips nodes that already have JSDoc comments.
+- Tries to infer parameter and return types.
+- Supports custom JSDoc templates via config.
+- Supports AI-generated `@description` using OpenAI or Gemini.
+- Provides safe fallback when AI key/request is unavailable.
 
 ## Installation
 
-Install the library globally or locally via npm:
+Install globally:
 
 ```bash
-npm install jsdoc-builder -g
+npm install -g jsdoc-builder
 ```
 
-or
-
-```bash
-npm install jsdoc-builder --save-dev
-```
-
-## Usage
-
-### CLI Command
-
-Run the following command to generate JSDoc comments for a file:
+Or install in a project:
 
 ```bash
-jsdoc-builder <file-path>
+npm install --save-dev jsdoc-builder
 ```
 
-Replace `<file-path>` with the path to the JavaScript or TypeScript file you want to process.
-
-### Example
+## Quick Start
 
-#### Input File (`example.ts`):
+1. Create a source file:
 
-```typescript
+```ts
 function add(a: number, b: number) {
   return a + b;
 }
-
-const multiply = (a: number, b: number): number => {
-  return a * b;
-};
 ```
 
-#### Command:
+2. Run CLI:
 
 ```bash
-jsdoc-builder example.ts
+jsdoc-builder ./example.ts
 ```
 
-#### Output File (`example.ts`):
+3. Result:
 
-```typescript
+```ts
 /**
- * @description Press Your { Function add } Description
+ * @description add function
  * @param {number} a
  * @param {number} b
- * @returns {void}
+ * @returns {number}
  */
 function add(a: number, b: number) {
   return a + b;
 }
+```
 
-/**
- * @description Press Your { Function multiply } Description
- * @param {number} a
- * @param {number} b
- * @returns {number}
- */
-const multiply = (a: number, b: number): number => {
-  return a * b;
-};
+## CLI Usage
+
+Basic:
+
+```bash
+jsdoc-builder <file-path>
+```
+
+Options:
+
+```bash
+jsdoc-builder <file-path> --config ./jsdoc-builder.config.json
+jsdoc-builder <file-path> --no-ai
+```
+
+- `-c, --config <path>`: custom config file path.
+- `--no-ai`: force disable AI descriptions even if config enables AI.
+
+## Config File
+
+Default config location is `./jsdoc-builder.config.json`.
+
+Example:
+
+```json
+{
+  "template": {
+    "descriptionLine": "@description {{description}}",
+    "paramLine": "@param {${type}} ${name}",
+    "returnsLine": "@returns {${type}}"
+  },
+  "includeReturnsWhenVoid": true,
+  "ai": {
+    "enabled": true,
+    "provider": "openai",
+    "model": "gpt-4o-mini",
+    "apiKey": "YOUR_API_KEY",
+    "baseUrl": "https://api.openai.com/v1/chat/completions",
+    "timeoutMs": 12000,
+    "promptTemplate": "Write one concise sentence for '{{functionName}}'. Params: {{parameters}}. Return type: {{returnType}}. Source: {{sourceSnippet}}"
+  }
+}
+```
+
+### Config Fields
+
+- `template.descriptionLine`: template for description line.
+- `template.paramLine`: template for each parameter line.
+- `template.returnsLine`: template for returns line.
+- `includeReturnsWhenVoid`: when `false`, omits `@returns` for `void` functions.
+- `ai.enabled`: enables or disables AI generation.
+- `ai.provider`: `"openai"` or `"gemini"`.
+- `ai.model`: model name for selected provider.
+- `ai.apiKey`: provider API key.
+- `ai.baseUrl`: provider base endpoint.
+- `ai.timeoutMs`: request timeout in milliseconds.
+- `ai.promptTemplate`: prompt template used for the AI request.
+
+### Template Placeholders
+
+Supported placeholders in templates:
+
+- `{{functionName}}` or `${functionName}`
+- `{{description}}` or `${description}`
+- `{{type}}` or `${type}`
+- `{{name}}` or `${name}`
+- `{{returnType}}` or `${returnType}`
+- `{{paramsCount}}` or `${paramsCount}`
+
+## AI Providers (OpenAI and Gemini)
+
+### OpenAI
+
+- `ai.provider`: `"openai"`
+- Default model: `gpt-4o-mini`
+- Default endpoint: `https://api.openai.com/v1/chat/completions`
+- Env fallback key: `OPENAI_API_KEY`
+
+### Gemini
+
+- `ai.provider`: `"gemini"`
+- Default model: `gemini-1.5-flash`
+- Default base URL: `https://generativelanguage.googleapis.com/v1beta`
+- Env fallback key: `GEMINI_API_KEY` or `GOOGLE_API_KEY`
+
+Gemini config example:
+
+```json
+{
+  "ai": {
+    "enabled": true,
+    "provider": "gemini",
+    "model": "gemini-1.5-flash",
+    "apiKey": "YOUR_GEMINI_API_KEY"
+  }
+}
+```
+
+### Missing API Key Behavior
+
+If `ai.apiKey` is missing:
+
+1. JSDoc Builder checks environment variables based on provider.
+2. If still missing, AI is disabled automatically.
+3. `@description` falls back to `"<functionName> function"`.
+
+## Language Support for Descriptions
+
+JSDoc Builder can generate description text in Korean, English, Chinese, or Japanese by changing `ai.promptTemplate`.
+
+Korean prompt example:
+
+```json
+{
+  "ai": {
+    "enabled": true,
+    "provider": "openai",
+    "promptTemplate": "함수 '{{functionName}}'의 JSDoc 설명을 한국어 한 문장으로 작성해 주세요. 파라미터: {{parameters}}, 반환 타입: {{returnType}}"
+  }
+}
+```
+
+Chinese prompt example:
+
+```json
+{
+  "ai": {
+    "enabled": true,
+    "provider": "gemini",
+    "promptTemplate": "请用中文一句话编写函数 '{{functionName}}' 的 JSDoc 描述。参数: {{parameters}}，返回类型: {{returnType}}"
+  }
+}
+```
+
+Japanese prompt example:
+
+```json
+{
+  "ai": {
+    "enabled": true,
+    "provider": "openai",
+    "promptTemplate": "関数 '{{functionName}}' の JSDoc 説明を日本語で1文で作成してください。引数: {{parameters}}、戻り値型: {{returnType}}"
+  }
+}
+```
+
+## Vite Plugin Usage
+
+```ts
+import { defineConfig } from "vite";
+import { jsdocBuilderVitePlugin } from "jsdoc-builder/vite";
+
+export default defineConfig({
+  plugins: [
+    jsdocBuilderVitePlugin({
+      apply: "serve",
+      configPath: "./jsdoc-builder.config.json",
+      include: ["src/"],
+      exclude: [/node_modules/, /dist/],
+      extensions: [".js", ".jsx", ".ts", ".tsx", ".vue"]
+    })
+  ]
+});
+```
+
+Plugin options:
+
+- `apply`: `"serve" | "build" | "both"` (default `"both"`)
+- `include`: only process matching files (string includes or RegExp)
+- `exclude`: skip matching files
+- `extensions`: file extensions to process
+- Also supports all `GenerateJSDocOptions` (`configPath`, `config`, `disableAI`)
+
+## Programmatic API
+
+```ts
+import { generateJSDoc, generateJSDocFromCode } from "jsdoc-builder";
+
+await generateJSDoc("./src/utils.ts", {
+  configPath: "./jsdoc-builder.config.json"
+});
+
+const output = await generateJSDocFromCode(
+  "/virtual/example.ts",
+  "const sum = (a, b) => a + b;",
+  {
+    config: {
+      ai: { enabled: false }
+    }
+  }
+);
+
+console.log(output);
 ```
 
-## API
+### API Reference
 
-### `generateJSDoc(filePath: string): void`
+- `generateJSDoc(filePath, options?)`: reads a file, transforms it, writes result.
+- `generateJSDocFromCode(filePath, code, options?)`: returns transformed code string.
 
-- **Description**: Processes the specified file to add JSDoc comments.
-- **Parameters**:
-  - `filePath` (string): The path to the file to be processed.
-- **Returns**: `void`
+## Behavior and Safety
 
-## Contributing
+- Existing JSDoc is preserved.
+- If no transform target is found, content is unchanged.
+- Vue files keep template/style blocks untouched.
+- AI errors do not break processing; fallback description is used.
 
-Contributions are welcome! Please follow these steps:
+## Troubleshooting
 
-1. Fork the repository.
-2. Create a new branch: `git checkout -b feature-name`.
-3. Commit your changes: `git commit -m 'Add feature-name'`.
-4. Push to the branch: `git push origin feature-name`.
-5. Submit a pull request.
+- `Cannot find module ...` in TypeScript:
+  - Check `tsconfig.json` includes Node types.
+  - Use `module` and `moduleResolution` values compatible with your TS version.
+- AI descriptions are not generated:
+  - Confirm `ai.enabled: true`
+  - Confirm provider API key is set in config or env
+  - Confirm provider endpoint is reachable
+- Descriptions are in the wrong language:
+  - Update `ai.promptTemplate` with your target language instruction.
 
 ## License
 
-This project is licensed under the MIT License. See the LICENSE file for details.
+MIT. See [LICENSE](./LICENSE).

package/README.ja.md

@@ -0,0 +1,304 @@
+# JSDoc Builder
+
+[English](./README.MD) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md)
+
+JSDoc Builder は、JavaScript/TypeScript のコードに JSDoc コメントを自動生成する CLI/ライブラリです。
+JavaScript、TypeScript、JSX、TSX、Vue SFC をサポートします。
+
+## 目次
+
+- [概要](#概要)
+- [主な機能](#主な機能)
+- [インストール](#インストール)
+- [クイックスタート](#クイックスタート)
+- [CLI の使い方](#cli-の使い方)
+- [設定ファイル](#設定ファイル)
+- [AI プロバイダー (OpenAI / Gemini)](#ai-プロバイダー-openai--gemini)
+- [説明文の多言語対応（韓国語/英語/中国語/日本語）](#説明文の多言語対応韓国語英語中国語日本語)
+- [Vite プラグイン](#vite-プラグイン)
+- [プログラム API](#プログラム-api)
+- [挙動と安全性](#挙動と安全性)
+- [トラブルシューティング](#トラブルシューティング)
+- [ライセンス](#ライセンス)
+
+## 概要
+
+- JSDoc の繰り返し作業を減らします。
+- JS/TS/Vue 混在プロジェクトでもコメント形式を統一できます。
+- 以下の使い方に対応します。
+  - CLI
+  - ライブラリ API
+  - Vite プラグイン
+
+## 主な機能
+
+- 次の対象に JSDoc を生成:
+  - 関数宣言
+  - 変数に代入されたアロー関数
+  - 変数に代入された関数式
+- 対応拡張子:
+  - `.js`, `.mjs`, `.cjs`
+  - `.ts`
+  - `.jsx`
+  - `.tsx`
+  - `.vue`（`<script>` のみ更新）
+- 既存 JSDoc があるノードはスキップ。
+- 可能な範囲で引数型/戻り値型を推論。
+- テンプレートのカスタマイズに対応。
+- OpenAI/Gemini による `@description` 生成に対応。
+- API キーなし/AI 失敗時は安全にフォールバック。
+
+## インストール
+
+グローバル:
+
+```bash
+npm install -g jsdoc-builder
+```
+
+プロジェクト:
+
+```bash
+npm install --save-dev jsdoc-builder
+```
+
+## クイックスタート
+
+1. ファイルを用意:
+
+```ts
+function add(a: number, b: number) {
+  return a + b;
+}
+```
+
+2. 実行:
+
+```bash
+jsdoc-builder ./example.ts
+```
+
+3. 出力:
+
+```ts
+/**
+ * @description add function
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+function add(a: number, b: number) {
+  return a + b;
+}
+```
+
+## CLI の使い方
+
+基本:
+
+```bash
+jsdoc-builder <file-path>
+```
+
+オプション:
+
+```bash
+jsdoc-builder <file-path> --config ./jsdoc-builder.config.json
+jsdoc-builder <file-path> --no-ai
+```
+
+- `-c, --config <path>`: 設定ファイルパス
+- `--no-ai`: 設定で AI が有効でも強制的に無効化
+
+## 設定ファイル
+
+デフォルトパスは `./jsdoc-builder.config.json` です。
+
+```json
+{
+  "template": {
+    "descriptionLine": "@description {{description}}",
+    "paramLine": "@param {${type}} ${name}",
+    "returnsLine": "@returns {${type}}"
+  },
+  "includeReturnsWhenVoid": true,
+  "ai": {
+    "enabled": true,
+    "provider": "openai",
+    "model": "gpt-4o-mini",
+    "apiKey": "YOUR_API_KEY",
+    "baseUrl": "https://api.openai.com/v1/chat/completions",
+    "timeoutMs": 12000,
+    "promptTemplate": "Write one concise sentence for '{{functionName}}'. Params: {{parameters}}. Return type: {{returnType}}. Source: {{sourceSnippet}}"
+  }
+}
+```
+
+### 設定項目
+
+- `template.descriptionLine`: 説明行テンプレート
+- `template.paramLine`: 引数行テンプレート
+- `template.returnsLine`: 戻り値行テンプレート
+- `includeReturnsWhenVoid`: `false` の場合、`void` 関数の `@returns` を省略
+- `ai.enabled`: AI 生成の有効/無効
+- `ai.provider`: `"openai"` または `"gemini"`
+- `ai.model`: モデル名
+- `ai.apiKey`: API キー
+- `ai.baseUrl`: エンドポイントのベース URL
+- `ai.timeoutMs`: タイムアウト（ミリ秒）
+- `ai.promptTemplate`: AI プロンプトテンプレート
+
+### テンプレートのプレースホルダー
+
+- `{{functionName}}` / `${functionName}`
+- `{{description}}` / `${description}`
+- `{{type}}` / `${type}`
+- `{{name}}` / `${name}`
+- `{{returnType}}` / `${returnType}`
+- `{{paramsCount}}` / `${paramsCount}`
+
+## AI プロバイダー (OpenAI / Gemini)
+
+OpenAI:
+
+- `ai.provider`: `"openai"`
+- デフォルトモデル: `gpt-4o-mini`
+- デフォルト URL: `https://api.openai.com/v1/chat/completions`
+- 環境変数キー: `OPENAI_API_KEY`
+
+Gemini:
+
+- `ai.provider`: `"gemini"`
+- デフォルトモデル: `gemini-1.5-flash`
+- デフォルト URL: `https://generativelanguage.googleapis.com/v1beta`
+- 環境変数キー: `GEMINI_API_KEY` または `GOOGLE_API_KEY`
+
+Gemini 設定例:
+
+```json
+{
+  "ai": {
+    "enabled": true,
+    "provider": "gemini",
+    "model": "gemini-1.5-flash",
+    "apiKey": "YOUR_GEMINI_API_KEY"
+  }
+}
+```
+
+### API キーがない場合の挙動
+
+1. プロバイダーごとの環境変数を確認
+2. 取得できなければ AI を自動的に無効化
+3. `@description` は `"<functionName> function"` にフォールバック
+
+## 説明文の多言語対応（韓国語/英語/中国語/日本語）
+
+`ai.promptTemplate` を変更することで、説明文の言語を制御できます。
+
+韓国語例:
+
+```json
+{
+  "ai": {
+    "enabled": true,
+    "provider": "openai",
+    "promptTemplate": "함수 '{{functionName}}'의 JSDoc 설명을 한국어 한 문장으로 작성해 주세요. 파라미터: {{parameters}}, 반환 타입: {{returnType}}"
+  }
+}
+```
+
+中国語例:
+
+```json
+{
+  "ai": {
+    "enabled": true,
+    "provider": "gemini",
+    "promptTemplate": "请用中文一句话编写函数 '{{functionName}}' 的 JSDoc 描述。参数: {{parameters}}，返回类型: {{returnType}}"
+  }
+}
+```
+
+日本語例:
+
+```json
+{
+  "ai": {
+    "enabled": true,
+    "provider": "openai",
+    "promptTemplate": "関数 '{{functionName}}' の JSDoc 説明を日本語で1文で作成してください。引数: {{parameters}}、戻り値型: {{returnType}}"
+  }
+}
+```
+
+## Vite プラグイン
+
+```ts
+import { defineConfig } from "vite";
+import { jsdocBuilderVitePlugin } from "jsdoc-builder/vite";
+
+export default defineConfig({
+  plugins: [
+    jsdocBuilderVitePlugin({
+      apply: "serve",
+      configPath: "./jsdoc-builder.config.json",
+      include: ["src/"],
+      exclude: [/node_modules/, /dist/],
+      extensions: [".js", ".jsx", ".ts", ".tsx", ".vue"]
+    })
+  ]
+});
+```
+
+主なオプション:
+
+- `apply`: `"serve" | "build" | "both"`（既定値 `"both"`）
+- `include`: 処理対象のフィルター
+- `exclude`: 除外対象のフィルター
+- `extensions`: 対象拡張子
+- `GenerateJSDocOptions` も使用可（`configPath`, `config`, `disableAI`）
+
+## プログラム API
+
+```ts
+import { generateJSDoc, generateJSDocFromCode } from "jsdoc-builder";
+
+await generateJSDoc("./src/utils.ts", {
+  configPath: "./jsdoc-builder.config.json"
+});
+
+const output = await generateJSDocFromCode(
+  "/virtual/example.ts",
+  "const sum = (a, b) => a + b;",
+  {
+    config: {
+      ai: { enabled: false }
+    }
+  }
+);
+
+console.log(output);
+```
+
+## 挙動と安全性
+
+- 既存 JSDoc は保持されます。
+- 変換対象がない場合は内容を変更しません。
+- Vue はテンプレート/スタイルを変更しません。
+- AI エラー時も処理は継続し、フォールバック説明を使用します。
+
+## トラブルシューティング
+
+- TypeScript モジュール関連エラー:
+  - `tsconfig.json` の Node 型/モジュール解決設定を確認
+- AI 説明が生成されない:
+  - `ai.enabled: true` を確認
+  - API キー（設定または環境変数）を確認
+  - エンドポイントへの接続を確認
+- 言語が期待どおりでない:
+  - `ai.promptTemplate` の言語指示を修正
+
+## ライセンス
+
+MIT. [LICENSE](./LICENSE) を参照。