# Oleafly への貢献

Oleafly をより良くしたいと考えてくださり、ありがとうございます。このガイドでは、クローンしたばかりの状態から動作する開発ビルドまでの手順と、変更をどのようにレビューして取り込むかを説明します。

Oleafly をより良くしたいと考えてくださり、ありがとうございます。このガイドでは、クローンしたばかりの状態から動作する開発ビルドまでの手順と、変更をどのようにレビューして取り込むかを説明します。

## 貢献の方法

- バグを報告する：[バグ報告](https://github.com/Oleafly/Oleafly/issues/new/choose)の Issue を作成します。
- 機能を要望する：[機能リクエスト](https://github.com/Oleafly/Oleafly/issues/new/choose)の Issue を作成します。
- 脆弱性を非公開で報告する：[SECURITY.md](https://github.com/Oleafly/Oleafly/blob/main/SECURITY.md) の手順に従います。
- プルリクエストを送る：以下を参照してください。

小さな修正より大きな変更の場合は、時間をかける前に方針を合意できるよう、先に Issue を作成してください。

## 前提条件

| ツール | バージョン | 備考 |
| --- | --- | --- |
| [Node.js](https://nodejs.org) | 22.13+ | pnpm 11 に必要 |
| [pnpm](https://pnpm.io) | 11.9+ | Corepack を有効にするか、`package.json` で宣言されているバージョンをインストールしてください |
| [Rust](https://rustup.rs) | stable (1.77+) | `cargo` を含みます |
| プラットフォームの依存関係 | - | お使いの OS 向けの [Tauri v2 の前提条件](https://v2.tauri.app/start/prerequisites/)を参照してください（Linux では `libwebkit2gtk-4.1-dev`、`librsvg2-dev`、`patchelf` など） |

## 始め方

```bash
git clone https://github.com/Oleafly/Oleafly.git
cd Oleafly
pnpm install

# Find your target with `rustc -vV | grep host`.
bash scripts/fetch-tectonic.sh aarch64-apple-darwin   # or your host triple
bash scripts/fetch-typst.sh aarch64-apple-darwin

# Run the app in dev mode (hot-reloads the frontend, rebuilds Rust on change):
pnpm tauri dev
```

> Tectonic、Biber、Typst のバイナリは**意図的に git の管理対象外**にしています。コミットしないでください。取得スクリプトは、これらを `src-tauri/binaries/` に置きます。`bundle.externalBin` が期待する場所です。

### 本番用バンドルをローカルでビルドする

```bash
pnpm tauri build
```

インストーラーは `src-tauri/target/release/bundle/` に出力されます。

## プロジェクトの構成

```
src/                 React + TypeScript app shell
  components/         UI (editor, pdf, ai, layout, files, …)
  lib/               framework-agnostic helpers (ai-providers, github, …)
  store/             Zustand state slices
packages/            @oleafly/* engine packages, consumed as TypeScript source
src-tauri/src/       Rust backend (Tauri commands)
  commands.rs        Tauri command handlers and compile entry points
  latex_engine.rs    Tectonic and latexmk selection
  mcp/               local MCP server, routing, and native tools
  project.rs         project/file CRUD (path-sandboxed - see `resolve`)
  git.rs             git integration
  github.rs          GitHub OAuth device flow
  paths.rs           path helpers + project-id validation
docs/                user-facing documentation
scripts/             sidecar fetchers, language servers, release checks, icon generation
```

## テスト

```bash
pnpm test                    # frontend unit tests (Vitest)
cd src-tauri && cargo test --lib   # Rust backend tests
```

ファイルシステム、Git、ユーザーのパスに触れるバックエンドのロジックには、テストが**必須**です。パスのサンドボックス化を担うヘルパー（`resolve_within`、`validate_project_id`）と、ログや URL のパーサーは、`#[cfg(test)]` モジュールでカバーされています。そのコードを変更するときは、テストも拡張してください。フロントエンドでは、スペルチェックと文法チェックが何を見るかを決める LaTeX のマスキングは純粋関数で、`src/components/editor/cm/latex-mask.test.ts` で単体テストされています。何を文章として扱うかを変更するときは、そこにケースを追加してください。

## コードスタイル

- **TypeScript**：フロントエンドは型チェックとビルドを通す必要があります（`pnpm build`）。また、Biome の lint ゲートも通す必要があります（`pnpm lint`。安全に直せるものは `pnpm lint:fix` で自動修正できます）。このゲートは、正しさに関するエラーで**ブロック**されます。既存のアクセシビリティやスタイルの積み残しは、ブロックしない警告として報告されます（`biome.json` を参照）。新しい警告は増やさないようにしてください。
- **Rust**：バックエンドは `cargo fmt` と `cargo clippy` をクリーンに通す必要があります。どちらも CI では**ブロック**されます（`clippy` は `-D warnings` 付きで実行されます）。プッシュする前に `cargo fmt` と `cargo clippy --all-targets --fix` を実行してください。
- 周囲のコードに合わせてください。コメントの量、命名、書き方です。

## プルリクエスト

1. `main` からフォークしてブランチを作ります（`git checkout -b fix/short-description`）。
2. 変更は絞ってください。関係のないリファクタリングは別の PR にしてください。
3. `pnpm lint`、`pnpm build`、`cargo test --lib` がローカルで通ることを確認してください。
4. PR テンプレートに記入してください。Issue へのリンク、変更内容の説明、テスト方法を書きます。
5. CI がグリーンである必要があります（フロントエンドのビルドと Rust のテストが必須チェックです）。

スカッシュマージするため、整った PR タイトルがそのままコミットメッセージになります。Conventional Commits の形式だと助かりますが、必須ではありません（例：`fix: reject absolute paths in resolve`）。

## リリース（メンテナー向け）

リリースは、バージョンタグをプッシュして作成します。[`Release` ワークフロー](https://github.com/Oleafly/Oleafly/blob/main/.github/workflows/release.yml)が、macOS Apple Silicon、Windows x64、Linux x64、Linux ARM64 のインストーラーをビルドし、レビュー用のドラフトに添付します。公開するには、同じタグに対してガード付きの 2 つ目のワークフローを実行する必要があります。

```bash
# Bump the version everywhere it's declared (package.json, Cargo.toml,
# Cargo.lock, tauri.conf.json) in one shot, so the tag can't drift:
./scripts/bump-version.sh 0.3.6

git commit -am "chore: release v0.2.0"
git tag v0.2.0 && git push origin v0.2.0
```

貢献することで、あなたの貢献がプロジェクトの [GNU Affero General Public License v3.0 以降](https://github.com/Oleafly/Oleafly/blob/main/LICENSE)のもとでライセンスされることに同意したものとみなされます。