[design] Cargo workspace の crate 分割と feature flag matrix

[sotashimozono]

Filed by Claude (Anthropic, AI agent operating under souta's GitHub auth) as a gap-fill discussion. Cross-references #14 §3 / #15 §1 / #5 §1 — crate decomposition is referenced but never specified as a normative spec.

Question

doiget の Cargo workspace 構造 (どの crate を作り、 どこに何を置くか、 dependency 方向と feature flag) を Phase 0 で normative spec として lock する。

これは:

• semver 約束 ([ux] User personas + 出力 mode 設計 (agent / researcher / CI / library) #14 §3 — doiget-core の API stability)
• compile-time gating ([legal] Legal posture, tool neutrality framing, and required safeguards #16 §6 — TDM source の物理隔離)
• distribution 戦略 ([design] APS / Elsevier / Springer TDM の実装優先度 #5 §1 — 1 binary + features)
• Phase 7 optional ([integration] Obsidian backend として使いやすい設計 #15 §1 — Obsidian crate の隔離)

を統一的に成立させる base layer。

提案する workspace 構造

doiget/                              # workspace root
├── Cargo.toml                       # workspace + shared dependencies
├── Cargo.lock
├── rust-toolchain.toml
├── deny.toml
├── .cargo/config.toml
│
├── crates/
│   ├── doiget-core/                 # ★ library crate, semver-stable
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── ref.rs               # Ref { Doi, Arxiv } — 入力 type
│   │       ├── safekey.rs           # safekey algorithm
│   │       ├── capability.rs        # CapabilityProfile
│   │       ├── store/               # Store trait + filesystem impl
│   │       ├── source/              # Source trait + Tier 1 impls
│   │       │   ├── crossref.rs
│   │       │   ├── unpaywall.rs
│   │       │   └── arxiv.rs
│   │       ├── source_tier2/        # Tier 2 (#[cfg(feature = "metadata")])
│   │       │   ├── openalex.rs
│   │       │   ├── s2.rs
│   │       │   └── doaj.rs
│   │       ├── source_tdm/          # Tier 3 (#[cfg(feature = "tdm-*")])
│   │       │   ├── elsevier.rs
│   │       │   ├── aps.rs
│   │       │   └── springer.rs
│   │       ├── provenance.rs        # log writer + hash chain
│   │       ├── citation.rs          # citation graph (#[cfg(feature = "citation")])
│   │       ├── cache.rs             # resolver / citation cache
│   │       ├── error.rs             # ErrorCode enum
│   │       └── config.rs            # Config struct
│   │
│   ├── doiget-cli/                  # binary `doiget`
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── main.rs
│   │       ├── cmd/
│   │       │   ├── fetch.rs
│   │       │   ├── batch.rs
│   │       │   ├── info.rs
│   │       │   ├── search.rs
│   │       │   ├── list_recent.rs
│   │       │   ├── bib.rs
│   │       │   ├── csl.rs
│   │       │   ├── audit_log.rs
│   │       │   └── serve.rs         # 内部で doiget-mcp を呼ぶ
│   │       └── output/              # human / json / quiet formatter
│   │
│   ├── doiget-mcp/                  # MCP server crate
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs               # Server type
│   │       ├── tools/
│   │       │   ├── resolve_paper.rs
│   │       │   ├── fetch_paper.rs
│   │       │   ├── batch_fetch.rs
│   │       │   ├── info.rs
│   │       │   ├── search_local.rs
│   │       │   ├── list_recent.rs
│   │       │   ├── paper_pdf_path.rs
│   │       │   ├── capability_profile.rs
│   │       │   └── health.rs
│   │       └── transport/           # stdio only
│   │
│   └── doiget-obsidian/             # Phase 7、 default 不依存
│       └── ...
│
├── examples/
│   ├── 01-basic-fetch/
│   ├── 02-batch/
│   └── 03-mcp-host-integration/
│
├── tests/
│   ├── cli_fetch.rs                 # assert_cmd e2e
│   ├── mcp_smoke.rs                 # MCP stdio smoke
│   ├── safekey_vectors.rs           # 100 reference vectors
│   ├── bibliofetch_roundtrip.rs     # cross-tool integration
│   └── fixtures/
│       ├── safekey/vectors.json
│       └── golden/
│
└── docs/                            # NORMATIVE + INFORMATIVE specs (#11)

1. Crate 別の役割と semver

Crate	役割	semver 厳格度
doiget-core	★ library API。 Source / Store / CapabilityProfile / Ref / safekey などの core type と impl	strict (breaking change で major bump)
doiget-cli	binary doiget。 CLI parsing + 各 subcommand impl	loose (CLI flag deprecation でも minor bump 可)
doiget-mcp	MCP server。 doiget-cli の serve から呼ばれる	strict (MCP tool spec は agent integration を割る)
doiget-obsidian	Phase 7 optional。 Obsidian sync	loose (Phase 7 自体が experimental)

doiget-core の pub API は docs/PUBLIC_API.md で normative に lock (#14 §3 と整合)。 PR で signature 変更があれば必ず ADR + CHANGELOG 反映を要求。

2. Dependency 方向

doiget-cli  ───────► doiget-core
             ───────► doiget-mcp ───► doiget-core
doiget-obsidian ───► doiget-core   (Phase 7、 default OFF)

[禁止] doiget-core ─/─► doiget-cli (lib が bin に依存しない)
[禁止] doiget-core ─/─► doiget-mcp (lib が server に依存しない)
[禁止] doiget-mcp ─/─► doiget-cli (server が CLI に依存しない)

これを CI で enforce: cargo deny check または手書き tools/check-deps.sh で Cargo.toml の deps を検査し、 上記禁止方向を含む PR は fail。

3. Feature flag matrix

# Cargo.toml (workspace root の doiget metapackage、 もしくは doiget-cli)

[features]
default = ["oa-only"]

oa-only = []                    # Tier 1: Crossref + Unpaywall + arXiv (always on)

metadata = []                   # Tier 2: OpenAlex + S2 + DOAJ
citation = ["metadata"]         # citation graph (Phase 4)

tdm-elsevier = ["dep:secrecy"]
tdm-aps      = ["dep:secrecy"]
tdm-springer = ["dep:secrecy"]
# 注: tdm-all は意図的に提供しない (#5 §3)

obsidian = ["dep:doiget-obsidian"]   # Phase 7 default OFF

CI matrix の build 対象 (再掲):

• --features oa-only (default test、 必須)
• --no-default-features (最小 build sanity)
• --all-features (compile only、 test 不要、 TDM source は wiremock で test 不可)

4. crates.io publish 戦略 (#5 §1 と整合)

1 binary + feature flags 路線。 crates.io に publish するのは:

• doiget-core (library、 Phase 1 完成後 publish 開始)
• doiget-cli (binary、 Phase 6 で publish)
• doiget-mcp (library、 Phase 6 で publish — mcp host integrator が再利用しうる)
• doiget-obsidian (Phase 7、 publish は任意)

published binary は default features = ["oa-only"] のみ。 TDM 込み binary を publish しない (#5 §1 Option 1)。

5. Workspace lints / formatting

# Cargo.toml workspace
[workspace.lints.rust]
unsafe_code = "forbid"
missing_docs = "warn"

[workspace.lints.clippy]
print_stdout = "deny"               # MCP mode 安全性 (#14 §2)
print_stderr = "warn"               # tracing 経由を推奨
unwrap_used = "warn"
expect_used = "warn"
panic = "warn"
todo = "warn"
unimplemented = "warn"

doiget-mcp crate は冒頭で:

#![deny(clippy::print_stdout)]
#![deny(clippy::print_stderr)]

を強制し、 MCP 経路で stdout / stderr を tracing-subscriber 経由のみに制限。

6. tests/ 配置

workspace 直下の tests/ は integration test 専用。 各 crate 内の #[cfg(test)] mod tests は unit test。

tests/
├── cli_fetch.rs              # assert_cmd で `doiget fetch`
├── cli_batch.rs
├── cli_info.rs
├── mcp_smoke.rs              # `doiget serve` を spawn、 JSON-RPC 検証
├── mcp_tools_schema.rs       # 各 tool の inputSchema validation
├── safekey_vectors.rs        # 100 vectors の deterministic 検証
├── bibliofetch_roundtrip.rs  # Julia + Rust cross-tool (CI で julia install 後)
├── provenance_log.rs         # hash chain 検証
└── fixtures/
    ├── safekey/vectors.json
    ├── golden/bib/           # BibTeX expected output
    ├── golden/csl/
    └── http/                 # wiremock recorded responses

7. examples/ の役割

Cargo.toml workspace member として個別 crate に:

examples/
├── 01-basic-fetch/        # doiget-core を library として直接使う
│   ├── Cargo.toml
│   └── src/main.rs
├── 02-batch/
└── 03-mcp-host-integration/   # doiget-mcp を別 process で叩く host 側コード

CI で cargo build --examples を強制し、 README 内 example の link rot を防ぐ (#11 §6)。

8. Phase 0 で commit する Cargo.toml の sketch

# /Cargo.toml (workspace root)
[workspace]
resolver = "2"
members = ["crates/doiget-core", "crates/doiget-cli", "crates/doiget-mcp"]
exclude = ["crates/doiget-obsidian"]   # Phase 7 着手まで除外

[workspace.package]
version = "0.0.0"
edition = "2021"
rust-version = "1.83"
license = "MIT"
repository = "https://github.com/sotashimozono/doiget"
authors = ["Sota Shimozono"]

[workspace.dependencies]
# ... (#13 review §1 確定 list)

[workspace.lints]
# ... (上記 §5)

[profile.release]
lto = "thin"
codegen-units = 1
strip = "symbols"        # binary size 削減
panic = "abort"          # MCP server で panic 時に host が cleanup しやすい

Open questions

1. doiget-core を 0.x 系で永久維持 (semver 0.x の breaking change を minor で許容) する戦略 vs 1.0 を Phase 6 で打つ 戦略。 reviewer 推奨: 0.x 維持 + Phase 6 で 1.0 打つ。 0.x 期間中に Public API を refine、 Phase 6 で freeze
2. tests/fixtures/http/ を wiremock の record mode で生成するか、 手書きで maintain するか。 reviewer 推奨: 手書き (response shape を明示的に control したい)
3. doiget-obsidian を crates/ 配下に置くが workspace exclude するか、 extras/ 等別 dir にするか。 reviewer 推奨: crates/ 配下 + exclude。 Phase 7 着手時に include に変更するだけで済む
4. examples/ の各 example crate を crates.io に publish するか? reviewer 推奨: publish しない (publish = false)。 example は doc / 学習用、 dependency として依存される必要がない

Decision proposal

本 Discussion で確定する内容を docs/ARCHITECTURE.md の "Workspace structure" 節 + ADR docs/DECISIONS/0008-crate-decomposition.md で永続化。

• 4 crate 体制 (doiget-core / doiget-cli / doiget-mcp / doiget-obsidian)
• Dependency 方向の禁止規則を CI で enforce
• Feature flag matrix を §3 で確定
• crates.io publish は default oa-only のみ、 TDM 込み binary 不公開
• semver: doiget-core strict、 他は loose
• workspace lints + clippy print_stdout deny を Phase 0 から
• 0.x 期間で API refine、 Phase 6 で 1.0 freeze

---

Reviewer: Claude (Anthropic). Filed 2026-05-05.