# API設計書

## 概要

本ドキュメントは、Prettier（コードフォーマッター）のプログラマブルAPIについて記述します。PrettierはNode.jsライブラリとして提供され、JavaScriptコードから直接呼び出すことができます。RESTful APIではなく、ESM/CommonJSモジュールとしてエクスポートされる関数群を提供します。

## 共通仕様

### モジュールインポート

```javascript
// ESM
import * as prettier from "prettier";

// CommonJS
const prettier = require("prettier");

// Standalone（ブラウザ用）
import * as prettier from "prettier/standalone";
```

### エクスポート形式

| エクスポート | 説明 |
| --- | --- |
| `prettier` (default) | メインAPI（Node.js用） |
| `prettier/standalone` | ブラウザ用スタンドアロン版 |
| `prettier/plugins/*` | 各言語用プラグイン |

### 共通オプション型（Options）

すべてのフォーマット関連APIは以下のオプションを受け付けます:

| オプション名 | 型 | デフォルト | 説明 |
| --- | --- | --- | --- |
| parser | string | - | 使用するパーサー名（"babel", "typescript", "css"等） |
| filepath | string | - | ファイルパス（パーサー推論用） |
| plugins | Array<string \| Plugin> | [] | 追加プラグイン |
| tabWidth | number | 2 | インデント幅 |
| useTabs | boolean | false | タブを使用するか |
| semi | boolean | true | セミコロンを付けるか |
| singleQuote | boolean | false | シングルクォートを使用するか |
| jsxSingleQuote | boolean | false | JSXでシングルクォートを使用するか |
| trailingComma | "none" \| "es5" \| "all" | "all" | 末尾カンマ |
| bracketSpacing | boolean | true | オブジェクトリテラルのスペース |
| bracketSameLine | boolean | false | 複数行要素の>を同一行に配置 |
| arrowParens | "avoid" \| "always" | "always" | アロー関数の引数括弧 |
| rangeStart | number | 0 | フォーマット範囲開始位置 |
| rangeEnd | number | Infinity | フォーマット範囲終了位置 |
| requirePragma | boolean | false | プラグマ必須モード |
| insertPragma | boolean | false | プラグマ挿入 |
| proseWrap | "always" \| "never" \| "preserve" | "preserve" | マークダウン折り返し |
| htmlWhitespaceSensitivity | "css" \| "strict" \| "ignore" | "css" | HTML空白感度 |
| endOfLine | "auto" \| "lf" \| "crlf" \| "cr" | "lf" | 改行文字 |
| quoteProps | "as-needed" \| "consistent" \| "preserve" | "as-needed" | オブジェクトプロパティのクォート |
| vueIndentScriptAndStyle | boolean | false | Vue script/styleインデント |
| embeddedLanguageFormatting | "auto" \| "off" | "auto" | 埋め込み言語フォーマット |
| singleAttributePerLine | boolean | false | 属性を1行1つに |
| experimentalOperatorPosition | "start" \| "end" | "end" | 演算子位置（実験的） |
| experimentalTernaries | boolean | false | 三項演算子フォーマット（実験的） |

## API一覧

| カテゴリ | API | 型 | 説明 |
| --- | --- | --- | --- |
| フォーマット | format | async (text, options) => string | テキストをフォーマット |
| フォーマット | formatWithCursor | async (text, options) => CursorResult | カーソル位置を保持してフォーマット |
| フォーマット | check | async (text, options) => boolean | フォーマット済みか確認 |
| 設定 | resolveConfig | async (filePath, options) => Options \| null | 設定ファイルを解決 |
| 設定 | resolveConfigFile | async (filePath?) => string \| null | 設定ファイルパスを取得 |
| 設定 | clearConfigCache | async () => void | 設定キャッシュをクリア |
| ファイル情報 | getFileInfo | async (file, options) => FileInfoResult | ファイル情報を取得 |
| サポート情報 | getSupportInfo | async (options?) => SupportInfo | サポート言語・オプション一覧 |
| メタ情報 | version | string | Prettierバージョン |
| ユーティリティ | util | object | ユーティリティ関数群 |
| ドキュメント | doc | object | ドキュメントビルダー |

## 各APIエンドポイント定義

### フォーマット

#### 1. format

テキストをPrettierでフォーマットします。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `format(source: string, options?: Options): Promise<string>` |
| 非同期 | はい |
| スタンドアロン | 利用可能 |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| source | string | はい | フォーマット対象のソースコード |
| options | Options | いいえ | フォーマットオプション |

**戻り値**

```typescript
Promise<string>  // フォーマット済みテキスト
```

**使用例**

```javascript
import * as prettier from "prettier";

const code = "const x={a:1,b:2}";
const formatted = await prettier.format(code, {
  parser: "babel",
  semi: true,
  singleQuote: true,
});
// => "const x = { a: 1, b: 2 };\n"
```

---

#### 2. formatWithCursor

カーソル位置を保持しながらテキストをフォーマットします。エディタ統合に有用です。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `formatWithCursor(source: string, options: CursorOptions): Promise<CursorResult>` |
| 非同期 | はい |
| スタンドアロン | 利用可能 |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| source | string | はい | フォーマット対象のソースコード |
| options | CursorOptions | はい | cursorOffsetを含むオプション |

**CursorOptions（追加フィールド）**

| フィールド名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| cursorOffset | number | はい | フォーマット前のカーソル位置 |

**戻り値**

```typescript
interface CursorResult {
  formatted: string;    // フォーマット済みテキスト
  cursorOffset: number; // フォーマット後のカーソル位置
}
```

**使用例**

```javascript
import * as prettier from "prettier";

const result = await prettier.formatWithCursor("const x=1|", {
  parser: "babel",
  cursorOffset: 10,
});
// => { formatted: "const x = 1;\n", cursorOffset: 12 }
```

---

#### 3. check

テキストがすでにPrettierでフォーマット済みかを確認します。CI/CDでの使用に適しています。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `check(source: string, options?: Options): Promise<boolean>` |
| 非同期 | はい |
| スタンドアロン | 利用可能 |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| source | string | はい | 確認対象のソースコード |
| options | Options | いいえ | フォーマットオプション |

**戻り値**

```typescript
Promise<boolean>  // true: フォーマット済み, false: 未フォーマット
```

**使用例**

```javascript
import * as prettier from "prettier";

const isFormatted = await prettier.check("const x = 1;\n", {
  parser: "babel",
});
// => true
```

---

### 設定

#### 4. resolveConfig

指定ファイルパスに適用される設定を解決します。`.prettierrc`などの設定ファイルを探索します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `resolveConfig(fileUrlOrPath: string \| URL, options?: ResolveConfigOptions): Promise<Options \| null>` |
| 非同期 | はい |
| スタンドアロン | 利用不可（Node.js専用） |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| fileUrlOrPath | string \| URL | はい | 設定を解決するファイルパス |
| options | ResolveConfigOptions | いいえ | 解決オプション |

**ResolveConfigOptions**

| フィールド名 | 型 | デフォルト | 説明 |
| --- | --- | --- | --- |
| useCache | boolean | true | キャッシュを使用するか |
| config | string \| URL | - | 設定ファイルパスを直接指定 |
| editorconfig | boolean | false | .editorconfigを読み込むか |

**戻り値**

```typescript
Promise<Options | null>  // 設定オブジェクト、見つからない場合はnull
```

**使用例**

```javascript
import * as prettier from "prettier";

const config = await prettier.resolveConfig("/path/to/file.js");
// => { semi: false, singleQuote: true, ... }

const formatted = await prettier.format(code, {
  ...config,
  parser: "babel",
});
```

---

#### 5. resolveConfigFile

Prettier設定ファイルのパスを取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `resolveConfigFile(fileUrlOrPath?: string \| URL): Promise<string \| null>` |
| 非同期 | はい |
| スタンドアロン | 利用不可（Node.js専用） |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| fileUrlOrPath | string \| URL | いいえ | 検索開始ディレクトリ |

**戻り値**

```typescript
Promise<string | null>  // 設定ファイルパス、見つからない場合はnull
```

**使用例**

```javascript
import * as prettier from "prettier";

const configPath = await prettier.resolveConfigFile("/path/to/project/");
// => "/path/to/project/.prettierrc"
```

---

#### 6. clearConfigCache

設定ファイルとプラグインのキャッシュをクリアします。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `clearConfigCache(): Promise<void>` |
| 非同期 | はい |
| スタンドアロン | 利用不可（Node.js専用） |

**パラメータ**

なし

**戻り値**

```typescript
Promise<void>
```

**使用例**

```javascript
import * as prettier from "prettier";

await prettier.clearConfigCache();
```

---

### ファイル情報

#### 7. getFileInfo

ファイルに関する情報を取得します。無視されるべきか、どのパーサーを使用すべきかを判定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `getFileInfo(file: string \| URL, options?: FileInfoOptions): Promise<FileInfoResult>` |
| 非同期 | はい |
| スタンドアロン | 利用不可（Node.js専用） |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| file | string \| URL | はい | 対象ファイルパス |
| options | FileInfoOptions | いいえ | オプション |

**FileInfoOptions**

| フィールド名 | 型 | デフォルト | 説明 |
| --- | --- | --- | --- |
| ignorePath | string \| URL \| (string \| URL)[] | - | .prettierignoreのパス |
| withNodeModules | boolean | false | node_modules内も対象にするか |
| plugins | Array<string \| Plugin> | - | プラグイン |
| resolveConfig | boolean | true | 設定ファイルを解決するか |

**戻り値**

```typescript
interface FileInfoResult {
  ignored: boolean;           // 無視されるべきファイルか
  inferredParser: string | null;  // 推論されたパーサー名
}
```

**使用例**

```javascript
import * as prettier from "prettier";

const info = await prettier.getFileInfo("/path/to/file.ts");
// => { ignored: false, inferredParser: "typescript" }
```

---

### サポート情報

#### 8. getSupportInfo

Prettierがサポートする言語とオプションの情報を取得します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `getSupportInfo(options?: SupportInfoOptions): Promise<SupportInfo>` |
| 非同期 | はい |
| スタンドアロン | 利用可能 |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| options | SupportInfoOptions | いいえ | オプション |

**SupportInfoOptions**

| フィールド名 | 型 | デフォルト | 説明 |
| --- | --- | --- | --- |
| plugins | Array<string \| Plugin> | - | プラグイン |
| showDeprecated | boolean | false | 非推奨オプションを含めるか |

**戻り値**

```typescript
interface SupportInfo {
  languages: SupportLanguage[];  // サポート言語一覧
  options: SupportOption[];      // サポートオプション一覧
}
```

**使用例**

```javascript
import * as prettier from "prettier";

const info = await prettier.getSupportInfo();
// => { languages: [...], options: [...] }
```

---

### メタ情報

#### 9. version

Prettierのバージョン文字列。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 型 | `string` |
| スタンドアロン | 利用可能 |

**使用例**

```javascript
import * as prettier from "prettier";

console.log(prettier.version);
// => "3.9.0-dev"
```

---

### ユーティリティ

#### 10. util

プラグイン開発者向けのユーティリティ関数群。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 型 | `object` |
| スタンドアロン | 利用可能 |

**主要な関数**

| 関数名 | シグネチャ | 説明 |
| --- | --- | --- |
| getMaxContinuousCount | (text, searchString) => number | 連続出現の最大数 |
| getStringWidth | (text) => number | 文字列の表示幅 |
| getAlignmentSize | (text, tabWidth, startIndex?) => number | アラインメントサイズ |
| getIndentSize | (value, tabWidth) => number | インデントサイズ |
| skipNewline | (text, startIndex, options?) => number \| false | 改行をスキップ |
| skipSpaces | (text, startIndex, options?) => number \| false | スペースをスキップ |
| skipWhitespace | (text, startIndex, options?) => number \| false | 空白をスキップ |
| hasNewline | (text, startIndex, options?) => boolean | 改行の存在確認 |
| hasNewlineInRange | (text, startIndex, endIndex) => boolean | 範囲内の改行確認 |
| hasSpaces | (text, startIndex, options?) => boolean | スペースの存在確認 |
| makeString | (rawText, enclosingQuote, unescapeUnnecessaryEscapes?) => string | 文字列生成 |
| getPreferredQuote | (text, preferredQuote) => Quote | 推奨クォート取得 |
| addLeadingComment | (node, comment) => void | 先行コメント追加 |
| addDanglingComment | (node, comment, marker) => void | ダングリングコメント追加 |
| addTrailingComment | (node, comment) => void | 末尾コメント追加 |
| isNextLineEmpty | (text, startIndex) => boolean | 次行が空か確認 |
| isPreviousLineEmpty | (text, startIndex) => boolean | 前行が空か確認 |

---

### ドキュメント

#### 11. doc

IR（中間表現）ドキュメントを構築するためのビルダーとユーティリティ。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 型 | `{ builders, printer, utils }` |
| スタンドアロン | 利用可能 |

**doc.builders（ドキュメントビルダー）**

| ビルダー | 説明 |
| --- | --- |
| join | ドキュメントを区切り文字で結合 |
| line | ソフト改行（グループ内で折り返し可能） |
| softline | 折り返し時のみ改行 |
| hardline | 強制改行 |
| literalline | リテラル改行（インデントなし） |
| group | 折り返しグループ |
| conditionalGroup | 条件付きグループ |
| fill | テキスト折り返し |
| lineSuffix | 行末に追加 |
| lineSuffixBoundary | 行末追加の境界 |
| cursor | カーソル位置マーカー |
| breakParent | 親グループを折り返し |
| ifBreak | 折り返し時の条件分岐 |
| trim | 末尾空白を削除 |
| indent | インデント |
| indentIfBreak | 折り返し時のみインデント |
| align | アラインメント |
| dedent | インデント解除 |
| dedentToRoot | ルートまでインデント解除 |
| markAsRoot | ルートとしてマーク |
| label | ラベル付け |

**doc.printer**

| 関数 | 説明 |
| --- | --- |
| printDocToString | ドキュメントを文字列に変換 |

**doc.utils**

| 関数 | 説明 |
| --- | --- |
| willBreak | 折り返しが発生するか |
| traverseDoc | ドキュメントを走査 |
| findInDoc | ドキュメント内を検索 |
| mapDoc | ドキュメントをマップ |
| removeLines | 改行を削除 |
| stripTrailingHardline | 末尾のhardlineを削除 |
| replaceEndOfLine | 改行を置換 |
| canBreak | 折り返し可能か |

---

### デバッグAPI（__debug）

開発・テスト用の内部API。本番環境での使用は非推奨です。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| 型 | `object` |
| スタンドアロン | 利用可能 |

**関数一覧**

| 関数名 | シグネチャ | 説明 |
| --- | --- | --- |
| parse | async (text, options) => { ast, text } | テキストをパース |
| formatAST | async (ast, options) => { formatted } | ASTをフォーマット |
| formatDoc | async (doc, options) => string | IRドキュメントをフォーマット |
| printToDoc | async (text, options) => Doc | テキストをIRドキュメントに変換 |
| printDocToString | async (doc, options) => { formatted } | IRドキュメントを文字列に変換 |

---

## 型定義

### Plugin

プラグインのインターフェース定義。

```typescript
interface Plugin<T = any> {
  languages?: SupportLanguage[];
  parsers?: { [parserName: string]: Parser<T> };
  printers?: { [astFormat: string]: Printer<T> };
  options?: SupportOptions;
  defaultOptions?: Partial<RequiredOptions>;
}
```

### Parser

パーサーのインターフェース定義。

```typescript
interface Parser<T = any> {
  parse: (text: string, options: ParserOptions<T>) => T | Promise<T>;
  astFormat: string;
  hasPragma?: (text: string) => boolean;
  hasIgnorePragma?: (text: string) => boolean;
  locStart: (node: T) => number;
  locEnd: (node: T) => number;
  preprocess?: (text: string, options: ParserOptions<T>) => string | Promise<string>;
}
```

### Printer

プリンターのインターフェース定義。

```typescript
interface Printer<T = any> {
  print: (path: AstPath<T>, options: ParserOptions<T>, print: (path: AstPath<T>) => Doc, args?: unknown) => Doc;
  embed?: (path: AstPath, options: Options) => /* ... */;
  preprocess?: (ast: T, options: ParserOptions<T>) => T | Promise<T>;
  insertPragma?: (text: string) => string;
  massageAstNode?: (original: any, cloned: any, parent: any) => any;
  /* ... その他のオプショナルメソッド */
}
```

### AstPath

AST走査用のパスクラス。

```typescript
class AstPath<T = any> {
  constructor(value: T);

  get key(): string | null;
  get index(): number | null;
  get node(): T;
  get parent(): T | null;
  get grandparent(): T | null;
  get isInArray(): boolean;
  get siblings(): T[] | null;
  get next(): T | null;
  get previous(): T | null;
  get isFirst(): boolean;
  get isLast(): boolean;
  get isRoot(): boolean;
  get root(): T;
  get ancestors(): T[];

  call<U>(callback: CallCallback<T, U>, ...props: PropertyKey[]): U;
  each(callback: EachCallback<T>, ...props: PropertyKey[]): void;
  map<U>(callback: MapCallback<T, U>, ...props: PropertyKey[]): U[];
}
```

## 組み込みパーサー

| パーサー名 | 対象言語 |
| --- | --- |
| babel | JavaScript |
| babel-flow | JavaScript + Flow |
| babel-ts | JavaScript + TypeScript（Babel経由） |
| typescript | TypeScript |
| acorn | JavaScript（Acorn） |
| espree | JavaScript（ESLint用） |
| meriyah | JavaScript（Meriyah） |
| flow | Flow |
| css | CSS |
| less | Less |
| scss | SCSS |
| html | HTML |
| vue | Vue SFC |
| angular | Angular テンプレート |
| lwc | Lightning Web Components |
| glimmer | Glimmer/Handlebars |
| graphql | GraphQL |
| markdown | Markdown |
| mdx | MDX |
| yaml | YAML |
| json | JSON |
| json5 | JSON5 |
| jsonc | JSON with Comments |
| json-stringify | JSON（JSON.stringify形式） |

## 備考

- すべてのフォーマット関連APIは非同期（Promise）です
- スタンドアロン版ではファイルシステムにアクセスするAPI（resolveConfig, getFileInfo等）は利用できません
- プラグインを使用する場合は、options.pluginsに配列として渡します
- エディタ統合では、formatWithCursorを使用することでカーソル位置を保持できます
- 設定ファイルは`.prettierrc`、`.prettierrc.json`、`.prettierrc.yaml`、`.prettierrc.js`、`prettier.config.js`などがサポートされます
