Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -236,7 +236,7 @@ prism analyze <PR_URL> --provider github # Explicit provider
| Provider | Type | Status |
|----------|------|--------|
| GitHub | Built-in | Supported |
| AWS CodeCommit | Plugin | In progress (v0.2.0) |
| AWS CodeCommit | Plugin | Supported ([prism-provider-codecommit](https://github.com/hidetzu/prism-provider-codecommit)) |

### Provider selection

Expand Down
2 changes: 1 addition & 1 deletion cmd/prism/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import (
"github.com/hidetzu/prism/internal/usecase"
)

const version = "0.2.0-alpha.1"
const version = "0.2.0"

// Exit codes as defined in docs/spec.md.
const (
Expand Down
149 changes: 70 additions & 79 deletions docs/adr/0001-provider-plugin-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,135 +8,126 @@ Accepted

## Context

`prism` v0.2.0 では AWS CodeCommit の Pull Request 取得を追加したい。
ただし、`prism` 本体の責務は **Pull Request を構造化コンテキストへ分解すること** であり、
各ホスティングサービス固有の API 実装や認証処理を大量に抱え込むことではない。
prism v0.2.0 aims to add AWS CodeCommit Pull Request support.
However, prism's core responsibility is **decomposing Pull Requests into structured review context**, not absorbing API implementations and authentication mechanisms for every hosting service.

現状の懸念は次の2点である。
Two concerns drove this decision:

1. **プロバイダー検出の設計**
- 現在は GitHub 前提で実装されている
- GitHub / CodeCommit / 将来の Bitbucket などにどう拡張するかを整理する必要がある
1. **Provider detection design**
- The current implementation assumes GitHub
- Needs a strategy for extending to GitHub / CodeCommit / future Bitbucket, etc.

2. **認証と依存の違い**
- GitHub `GITHUB_TOKEN` を用いた Bearer 認証
- CodeCommit AWS credential chain / IAM / region を前提とする
- Go 本体に AWS SDK を直接組み込むと、依存と責務が膨らむ
2. **Authentication and dependency differences**
- GitHub uses `GITHUB_TOKEN` with Bearer authentication
- CodeCommit requires AWS credential chain / IAM / region
- Embedding the AWS SDK directly into prism would bloat dependencies and blur responsibilities

また、CodeCommit については既存資産として `ccpr` が存在している。
この資産を活用しつつ、`prism` 本体の責務を守る必要がある。
Additionally, an existing tool `ccpr` already handles CodeCommit PR retrieval. This asset should be leveraged while preserving prism's core responsibilities.

---

## Decision

v0.2.0 では、**Provider を外部バイナリプラグイン方式で拡張する**。
v0.2.0 extends providers via **external binary plugins**.

`prism` 本体は provider interface と plugin execution layer のみを持ち、
CodeCommit 対応は `ccpr` 系の別バイナリとして実装・連携する。
prism itself holds only the provider interface and plugin execution layer. CodeCommit support is implemented as a separate binary that wraps `ccpr`.

### 採用する方針
### Approach

- Provider 拡張は **外部バイナリ方式** を採用する
- `prism-provider-codecommit` のような実行可能バイナリを想定する
- `prism` はサブプロセスとして provider plugin を呼び出す
- provider plugin は PR データを共通 JSON 形式で返す
- `prism` は返却された共通 JSON `PullRequest` ドメインモデルへ変換して解析を続行する
- Provider extensibility uses the **external binary approach**
- Plugins are executable binaries such as `prism-provider-codecommit`
- prism invokes plugins as subprocesses
- Plugins return PR data in a standardized JSON format
- prism converts the returned JSON into `PullRequest` domain models and continues analysis

### GitHub provider の扱い
### GitHub provider handling

- v0.2.0 では **GitHub は本体内蔵(built-in)** とする
- `go install` だけで GitHub に対して即座に使えるユーザー体験を維持する
- ただし、内部的には plugin と同等の境界を保ち、将来的に plugin として外出し可能な構造にする
- CodeCommit 以降の外部 provider は plugin 方式とする
- In v0.2.0, **GitHub remains built-in**
- This preserves the user experience of working with GitHub immediately after `go install`
- Internally, the boundary is kept equivalent to plugins, allowing future extraction
- CodeCommit and subsequent providers use the plugin approach

### Provider 検出方針
### Provider detection strategy

- デフォルトは **URL からの自動判定**
- `--provider` が明示指定された場合は **URL による自動判定を行わない**
- URL 自動判定が難しいケースや GitHub Enterprise などでは `--provider` で明示できる
- Default: **auto-detect from URL**
- When `--provider` is explicitly specified, **URL-based auto-detection is skipped**
- `--provider` enables use with GitHub Enterprise and other hosts where URL auto-detection is insufficient

### 初期ルール
### Initial rules

- `github.com` を含む URL は GitHub provider
- CodeCommit URL パターンに一致するものは CodeCommit provider
- `--provider github` などが指定された場合はその provider を強制利用する
- 自動判定できない場合は、分かりやすいエラーメッセージで `--provider` の指定を促す
- URLs containing `github.com` use the GitHub provider
- URLs matching CodeCommit patterns use the CodeCommit provider
- `--provider github` etc. forces the specified provider
- When auto-detection fails, a clear error message suggests using `--provider`

---

## Rationale

この判断の理由は次の通り。
### 1. Preserves prism's responsibility
prism's essence is not fetching PRs, but **transforming fetched PRs into review context**. Absorbing provider-specific implementations would blur this responsibility.

### 1. `prism` の責務を保てる
`prism` の本質は PR の取得ではなく、**取得済み PR をレビュー用コンテキストへ変換すること** にある。
プロバイダー固有の実装を本体に抱え込むと、この責務が曖昧になる。
### 2. Leverages ccpr
For CodeCommit support, the existing `ccpr` tool can be reused. By wrapping it as an external provider rather than embedding the AWS SDK into prism, asset reuse and responsibility separation are achieved simultaneously.

### 2. `ccpr` を活かしやすい
CodeCommit 対応については既存の `ccpr` を活かせる。
`prism` に AWS SDK を直接入れず、外部 provider としてラップすることで、資産再利用と責務分離を両立できる。
### 3. Strong future extensibility
When considering future providers like Bitbucket, GitHub Enterprise, and GitLab, the plugin approach minimizes changes to prism itself.

### 3. 将来の拡張に強い
Bitbucket、GitHub Enterprise、GitLab など将来的な provider を想定したとき、
プラグイン方式のほうが `prism` 本体の変更を最小化しやすい。

### 4. 依存分離が明確
GitHub provider は軽量に保てる一方、CodeCommit provider は AWS 認証や SDK を独立して持てる。
これにより本体のビルド、保守、配布がシンプルになる。
### 4. Clear dependency separation
The GitHub provider remains lightweight, while the CodeCommit provider can independently manage AWS authentication and SDK dependencies. This keeps the core build, maintenance, and distribution simple.

---

## Alternatives Considered

## A. 外部バイナリ方式
採用。
## A. External binary approach
Adopted.

### メリット
- 依存が完全に分離できる
- `prism` 本体の責務が明確
- `ccpr` を活かしやすい
- 将来 provider を増やしやすい
### Advantages
- Complete dependency isolation
- Clear prism core responsibility
- Easy to leverage ccpr
- Easy to add future providers

### デメリット
- プラグインとの入出力仕様を安定させる必要がある
- サブプロセス実行とエラー処理が必要
- 配布方法を設計する必要がある
### Disadvantages
- Plugin input/output specification must be stabilized
- Subprocess execution and error handling required
- Distribution method must be designed

## B. Go internal 方式
不採用。
## B. Go internal approach
Rejected.

### 理由
- `prism` 本体に provider 固有依存が入りやすい
- AWS SDK などの依存が本体に混ざる
- `prism` の思想である責務分離が崩れやすい
### Reasons
- Provider-specific dependencies would leak into prism core
- AWS SDK and similar dependencies would mix into the core
- Violates prism's principle of responsibility separation

---

## Consequences

### Positive
- v0.2.0 で CodeCommit 対応を追加しつつ、本体をシンプルに保てる
- `ccpr` を provider plugin として再利用する道が開ける
- 将来の provider 拡張戦略が明確になる
- CodeCommit support added in v0.2.0 while keeping the core simple
- Path opened for reusing ccpr as a provider plugin
- Future provider extension strategy made explicit

### Negative
- plugin protocol を設計する必要がある
- plugin discovery の仕様が必要になる
- ユーザー向けにはインストール説明が少し増える
- Plugin protocol must be designed
- Plugin discovery specification required
- User-facing installation instructions become slightly more complex

---

## Plugin Protocol

plugin の呼び出し規約、JSON schema、discovery 仕様の詳細は [Provider Plugin Protocol](../provider-plugin-protocol.md) を参照。
See [Provider Plugin Protocol](../provider-plugin-protocol.md) for invocation conventions, JSON schema, and discovery specification.

---

## Implementation Status

- [x] plugin protocol JSON schema を定義する
- [x] provider registry を実装する
- [x] provider auto detection ロジックを実装する
- [x] `--provider` 優先ルールを実装する
- [ ] CodeCommit plugin の第一候補として `ccpr` ラップ方式を検討する
- [x] Define plugin protocol JSON schema
- [x] Implement provider registry
- [x] Implement provider auto-detection logic
- [x] Implement `--provider` override rule
- [x] Adopt ccpr wrapper approach for CodeCommit plugin → [prism-provider-codecommit](https://github.com/hidetzu/prism-provider-codecommit)
Loading
Loading