プラグイン開発

Spekta のプラグインシステムについて説明します。Annotator（テスト DSL の解析）と Exporter（ドキュメント出力）の2種類があり、npm パッケージとして独立して開発・配布できます。

以下のインターフェースを実装した default export を持つ npm パッケージとして公開します。

interface AnnotatorPlugin {
  name: string;
  filePatterns: string[];
  annotate(filePath: string, source: string, config: Record<string, unknown>): Annotation[];
}

name — プラグイン名（例: "rspec"）
filePatterns — 対象ファイルのパターン（例: ["*_spec.rb"]）
annotate — ソースコードを解析して Annotation 配列を返す関数

name, filePatterns, annotate を持つオブジェクトを作る
型ガードで AnnotatorPlugin として認識される

なぜ？

プラグインのロード時に型ガードで検証されるため、インターフェースに準拠していないオブジェクトは拒否されます。

Tip

commands を実装すると、spekta {name}:{command} の形式でカスタムコマンドを追加できます（例: spekta web:dev）。

以下のインターフェースを実装した default export を持つ npm パッケージとして公開します。

interface ExporterPlugin {
  name: string;
  defaultOutputDir: string;
  configSchema?: { parse(data: unknown): unknown };
  export(ir: IR, config: Record<string, unknown>, outputDir: string): void;
  commands?: Record<string, (config: SpektaConfig) => Promise<void>>;
}

name — プラグイン名（例: "web"）
defaultOutputDir — デフォルト出力ディレクトリ名（例: "web"）
export — IR を受け取りドキュメントを出力する関数
configSchema — （オプション）設定値のバリデーション用 Zod スキーマ
commands — （オプション）カスタム CLI コマンド（例: web:dev）

name, defaultOutputDir, export を持つオブジェクトを作る
型ガードで ExporterPlugin として認識される

commands フィールドを省略しても ExporterPlugin として有効です。カスタムコマンドが不要な場合は省略できます。

Spekta

プラグイン開発

Annotator プラグイン

AnnotatorPlugin インターフェース

必須フィールドが欠けている場合

Exporter プラグイン

ExporterPlugin インターフェース

commands はオプション