use async_trait::async_trait;
use chrono::{DateTime, Utc};
use gitflow_core::{
CoreError, DEFAULT_LIST_LIMIT, FetchStrategy, Paged, Result, fetch_capped,
label::{
CreateLabelArgs, CreateMilestoneArgs, LabelData, LabelProvider, MilestoneData,
MilestoneProvider,
},
types::State,
};
use serde::Deserialize;
use tracing::debug;
use crate::{
GITHUB_API_MAX_PER_PAGE,
error::parse_gh_error,
runner::{CommandRunner, RealCommandRunner},
};
#[derive(Debug, Clone)]
pub struct GitHubLabelProvider<R: CommandRunner = RealCommandRunner> {
repo: String,
runner: R,
}
impl GitHubLabelProvider<RealCommandRunner> {
#[must_use]
pub fn new(repo: impl Into<String>) -> Self {
Self {
repo: repo.into(),
runner: RealCommandRunner,
}
}
#[must_use]
pub fn with_session(session: &gitflow_core::Session) -> Self {
Self {
repo: session.repo.clone(),
runner: RealCommandRunner,
}
}
}
impl<R: CommandRunner> GitHubLabelProvider<R> {
#[must_use]
pub fn with_runner(repo: impl Into<String>, runner: R) -> Self {
Self {
repo: repo.into(),
runner,
}
}
}
const LABEL_FIELDS: &str = "name,color,description";
#[async_trait]
impl<R: CommandRunner + 'static> LabelProvider for GitHubLabelProvider<R> {
async fn create(&self, args: CreateLabelArgs) -> Result<LabelData> {
debug!(
repo = %self.repo,
name = %args.name,
color = %args.color,
"spawning `gh label create`"
);
let mut cmd_args: Vec<&str> = vec![
"label",
"create",
&args.name,
"--color",
&args.color,
"--repo",
&self.repo,
];
if let Some(ref desc) = args.description {
cmd_args.push("--description");
cmd_args.push(desc);
}
let output =
self.runner.run("gh", &cmd_args).await.map_err(|e| {
CoreError::Platform(format!("Failed to spawn gh label create: {e}"))
})?;
if !output.status.success() {
return Err(parse_gh_error(&output.stderr).into());
}
Ok(LabelData {
name: args.name,
color: Some(args.color),
description: args.description,
})
}
async fn list(&self, limit: Option<u32>) -> Result<Paged<LabelData>> {
let cap = limit.unwrap_or(DEFAULT_LIST_LIMIT);
let repo = &self.repo;
let runner = &self.runner;
debug!(repo = %self.repo, cap, "spawning `gh label list`");
fetch_capped(FetchStrategy::SingleShot, cap, |_page, want| async move {
let want_str = want.to_string();
let output = runner
.run(
"gh",
&[
"label",
"list",
"--repo",
repo,
"--json",
LABEL_FIELDS,
"--limit",
&want_str,
],
)
.await
.map_err(|e| CoreError::Platform(format!("Failed to spawn gh label list: {e}")))?;
if !output.status.success() {
return Err(parse_gh_error(&output.stderr).into());
}
let labels: Vec<LabelData> =
serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
Ok(labels)
})
.await
}
async fn edit(&self, name: &str, args: CreateLabelArgs) -> Result<LabelData> {
debug!(repo = %self.repo, name, "spawning `gh label edit`");
let mut cmd_args: Vec<&str> = vec![
"label",
"edit",
name,
"--repo",
&self.repo,
"--color",
&args.color,
];
if let Some(ref desc) = args.description {
cmd_args.push("--description");
cmd_args.push(desc);
}
let output = self
.runner
.run("gh", &cmd_args)
.await
.map_err(|e| CoreError::Platform(format!("Failed to spawn gh label edit: {e}")))?;
if !output.status.success() {
return Err(parse_gh_error(&output.stderr).into());
}
self.fetch_label(name).await
}
async fn delete(&self, name: &str) -> Result<()> {
debug!(repo = %self.repo, name, "spawning `gh label delete`");
let output = self
.runner
.run(
"gh",
&["label", "delete", name, "--yes", "--repo", &self.repo],
)
.await
.map_err(|e| CoreError::Platform(format!("Failed to spawn gh label delete: {e}")))?;
if !output.status.success() {
return Err(parse_gh_error(&output.stderr).into());
}
Ok(())
}
}
impl<R: CommandRunner> GitHubLabelProvider<R> {
async fn fetch_label(&self, name: &str) -> Result<LabelData> {
let api_path = format!(
"repos/{repo}/labels/{name}",
repo = self.repo,
name = encode_path_segment(name)
);
let output = self
.runner
.run("gh", &["api", &api_path])
.await
.map_err(|e| CoreError::Platform(format!("Failed to spawn gh api label: {e}")))?;
if !output.status.success() {
return Err(parse_gh_error(&output.stderr).into());
}
let label: LabelData =
serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
Ok(label)
}
}
#[must_use]
fn encode_path_segment(value: &str) -> String {
const HEX_DIGITS: &[u8; 16] = b"0123456789ABCDEF";
let mut out = String::with_capacity(value.len());
for b in value.bytes() {
match b {
b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => {
out.push(char::from(b));
}
_ => {
out.push('%');
out.push(char::from(HEX_DIGITS[usize::from(b >> 4)]));
out.push(char::from(HEX_DIGITS[usize::from(b & 0x0F)]));
}
}
}
out
}
#[derive(Debug, Clone)]
pub struct GitHubMilestoneProvider<R: CommandRunner = RealCommandRunner> {
repo: String,
runner: R,
}
impl GitHubMilestoneProvider<RealCommandRunner> {
#[must_use]
pub fn new(repo: impl Into<String>) -> Self {
Self {
repo: repo.into(),
runner: RealCommandRunner,
}
}
#[must_use]
pub fn with_session(session: &gitflow_core::Session) -> Self {
Self {
repo: session.repo.clone(),
runner: RealCommandRunner,
}
}
}
impl<R: CommandRunner> GitHubMilestoneProvider<R> {
#[must_use]
pub fn with_runner(repo: impl Into<String>, runner: R) -> Self {
Self {
repo: repo.into(),
runner,
}
}
}
#[derive(Debug, Clone, Deserialize)]
struct MilestoneApiResponse {
number: u64,
title: String,
#[serde(default)]
description: Option<String>,
state: String,
#[serde(default)]
due_on: Option<String>,
#[serde(default)]
closed_issues: u64,
#[serde(default)]
open_issues: u64,
}
impl From<MilestoneApiResponse> for MilestoneData {
fn from(api: MilestoneApiResponse) -> Self {
Self {
number: api.number,
title: api.title,
description: api.description,
state: if api.state == "closed" {
State::Closed
} else {
State::Open
},
due_on: api.due_on.and_then(|s| {
DateTime::parse_from_rfc3339(&s).map_or(None, |dt| Some(dt.with_timezone(&Utc)))
}),
closed_issues: api.closed_issues,
open_issues: api.open_issues,
}
}
}
#[async_trait]
impl<R: CommandRunner + 'static> MilestoneProvider for GitHubMilestoneProvider<R> {
async fn create(&self, args: CreateMilestoneArgs) -> Result<MilestoneData> {
debug!(repo = %self.repo, title = %args.title, "spawning `gh api milestones POST`");
let api_path = format!("repos/{repo}/milestones", repo = self.repo);
let mut cmd = tokio::process::Command::new("gh");
cmd.args(["api", &api_path, "-X", "POST"])
.arg("-f")
.arg(format!("title={}", args.title));
if let Some(ref desc) = args.description {
cmd.arg("-f").arg(format!("description={desc}"));
}
if let Some(ref due) = args.due_on {
cmd.arg("-f").arg(format!("due_on={}", due.to_rfc3339()));
}
let output = cmd
.output()
.await
.map_err(|e| CoreError::Platform(format!("Failed to spawn gh api milestones: {e}")))?;
if !output.status.success() {
return Err(parse_gh_error(&output.stderr).into());
}
let api_response: MilestoneApiResponse =
serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
Ok(api_response.into())
}
async fn list(&self, limit: Option<u32>) -> Result<Paged<MilestoneData>> {
let cap = limit.unwrap_or(DEFAULT_LIST_LIMIT);
let repo = &self.repo;
let runner = &self.runner;
debug!(repo = %self.repo, cap, "spawning `gh api` GET milestones");
fetch_capped(
FetchStrategy::Paged {
per_page: cap.saturating_add(1).min(GITHUB_API_MAX_PER_PAGE),
},
cap,
|page, per_page| async move {
let api_path = format!("repos/{repo}/milestones?per_page={per_page}&page={page}");
let output = runner.run("gh", &["api", &api_path]).await.map_err(|e| {
CoreError::Platform(format!("Failed to spawn gh api milestones: {e}"))
})?;
if !output.status.success() {
return Err(parse_gh_error(&output.stderr).into());
}
let milestones: Vec<MilestoneApiResponse> =
serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
Ok(milestones.into_iter().map(MilestoneData::from).collect())
},
)
.await
}
async fn edit(&self, number: u64, args: CreateMilestoneArgs) -> Result<MilestoneData> {
debug!(repo = %self.repo, number, "spawning `gh api milestones PATCH`");
let api_path = format!("repos/{repo}/milestones/{number}", repo = self.repo);
let mut cmd = tokio::process::Command::new("gh");
cmd.args(["api", &api_path, "-X", "PATCH"]);
cmd.arg("-f").arg(format!("title={}", args.title));
if let Some(ref desc) = args.description {
cmd.arg("-f").arg(format!("description={desc}"));
}
if let Some(ref due) = args.due_on {
cmd.arg("-f").arg(format!("due_on={}", due.to_rfc3339()));
}
let output = cmd.output().await.map_err(|e| {
CoreError::Platform(format!("Failed to spawn gh api milestone edit: {e}"))
})?;
if !output.status.success() {
return Err(parse_gh_error(&output.stderr).into());
}
let api_response: MilestoneApiResponse =
serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
Ok(api_response.into())
}
async fn close(&self, number: u64) -> Result<MilestoneData> {
debug!(repo = %self.repo, number, "spawning `gh api milestones close`");
let api_path = format!("repos/{repo}/milestones/{number}", repo = self.repo);
let output = tokio::process::Command::new("gh")
.args(["api", &api_path, "-X", "PATCH", "-f", "state=closed"])
.output()
.await
.map_err(|e| {
CoreError::Platform(format!("Failed to spawn gh api milestone close: {e}"))
})?;
if !output.status.success() {
return Err(parse_gh_error(&output.stderr).into());
}
let api_response: MilestoneApiResponse =
serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
Ok(api_response.into())
}
async fn reopen(&self, number: u64) -> Result<MilestoneData> {
debug!(repo = %self.repo, number, "spawning `gh api milestones reopen`");
let api_path = format!("repos/{repo}/milestones/{number}", repo = self.repo);
let output = tokio::process::Command::new("gh")
.args(["api", &api_path, "-X", "PATCH", "-f", "state=open"])
.output()
.await
.map_err(|e| {
CoreError::Platform(format!("Failed to spawn gh api milestone reopen: {e}"))
})?;
if !output.status.success() {
return Err(parse_gh_error(&output.stderr).into());
}
let api_response: MilestoneApiResponse =
serde_json::from_slice(&output.stdout).map_err(CoreError::Serialization)?;
Ok(api_response.into())
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::runner::{MockCommandRunner, SequencedMockCommandRunner};
#[test]
fn test_should_construct_github_label_provider() {
let provider = GitHubLabelProvider::new("octocat/hello-world");
assert_eq!(provider.repo, "octocat/hello-world");
}
#[test]
fn test_should_construct_github_label_provider_from_string() {
let repo = String::from("octocat/hello-world");
let provider = GitHubLabelProvider::new(repo);
assert_eq!(provider.repo, "octocat/hello-world");
}
#[test]
fn test_should_debug_format_label_provider() {
let provider = GitHubLabelProvider::new("owner/repo");
let debug = format!("{provider:?}");
assert!(debug.contains("GitHubLabelProvider"));
assert!(debug.contains("owner/repo"));
}
#[test]
fn test_should_clone_github_label_provider() {
let original = GitHubLabelProvider::new("owner/repo");
let cloned = original.clone();
assert_eq!(original.repo, cloned.repo);
}
#[tokio::test]
async fn test_should_fetch_label_via_gh_api() {
let runner = MockCommandRunner::success(
r#"{"name":"bug","color":"d73a4a","description":"Something isn't working"}"#,
);
let provider = GitHubLabelProvider::with_runner("octocat/hello-world", runner.clone());
let label = provider.fetch_label("bug").await.expect("should fetch");
assert_eq!(label.name, "bug");
assert_eq!(label.color.as_deref(), Some("d73a4a"));
assert_eq!(
runner.recorded_calls()[0].1,
vec!["api", "repos/octocat/hello-world/labels/bug"]
);
}
#[tokio::test]
async fn test_should_encode_label_name_in_api_path() {
let runner = MockCommandRunner::success(r#"{"name":"good first issue","color":"7057ff"}"#);
let provider = GitHubLabelProvider::with_runner("octocat/hello-world", runner.clone());
let label = provider
.fetch_label("good first issue")
.await
.expect("should fetch");
assert_eq!(label.name, "good first issue");
assert_eq!(
runner.recorded_calls()[0].1,
vec![
"api",
"repos/octocat/hello-world/labels/good%20first%20issue"
]
);
}
#[tokio::test]
async fn test_should_edit_label_and_refetch_via_gh_api() {
let runner =
MockCommandRunner::success(r#"{"name":"bug","color":"3344ff","description":"probe2"}"#);
let provider = GitHubLabelProvider::with_runner("byx-darwin/gitflow-cli", runner.clone());
let args = CreateLabelArgs {
name: "bug".to_string(),
color: "3344ff".to_string(),
description: Some("probe2".to_string()),
};
let label = provider.edit("bug", args).await.expect("should edit");
assert_eq!(label.color.as_deref(), Some("3344ff"));
let calls = runner.recorded_calls();
assert_eq!(calls.len(), 2);
assert_eq!(
calls[0].1,
vec![
"label",
"edit",
"bug",
"--repo",
"byx-darwin/gitflow-cli",
"--color",
"3344ff",
"--description",
"probe2"
]
);
assert_eq!(
calls[1].1,
vec!["api", "repos/byx-darwin/gitflow-cli/labels/bug"]
);
assert!(
calls
.iter()
.all(|(_, args)| args.first().is_some_and(|a| a != "view")),
"no `gh label view` call may remain"
);
}
#[tokio::test]
async fn test_should_fail_when_fetch_label_api_fails() {
let runner = MockCommandRunner::failure("HTTP 404", 1);
let provider = GitHubLabelProvider::with_runner("owner/repo", runner);
let err = provider
.fetch_label("missing")
.await
.expect_err("should fail");
assert!(err.to_string().contains("GitHub") || err.to_string().contains("执行失败"));
}
#[tokio::test]
async fn test_should_list_labels_with_limit_flag() {
let runner = MockCommandRunner::success("[]");
let provider = GitHubLabelProvider::with_runner("owner/repo", runner.clone());
let paged = provider.list(None).await.expect("should list");
assert!(paged.items.is_empty());
assert_eq!(runner.recorded_calls()[0].0, "gh");
assert_eq!(
runner.recorded_calls()[0].1,
vec![
"label",
"list",
"--repo",
"owner/repo",
"--json",
"name,color,description",
"--limit",
"1001"
]
);
}
#[tokio::test]
async fn test_should_create_label_via_runner() {
let runner = MockCommandRunner::success("");
let provider = GitHubLabelProvider::with_runner("owner/repo", runner.clone());
let args = CreateLabelArgs {
name: "bug".to_string(),
color: "d73a4a".to_string(),
description: None,
};
let label = provider.create(args).await.expect("should create");
assert_eq!(label.name, "bug");
assert_eq!(label.color.as_deref(), Some("d73a4a"));
assert_eq!(
runner.recorded_calls()[0].1,
vec![
"label",
"create",
"bug",
"--color",
"d73a4a",
"--repo",
"owner/repo"
]
);
}
#[tokio::test]
async fn test_should_delete_label_via_runner() {
let runner = MockCommandRunner::success("");
let provider = GitHubLabelProvider::with_runner("owner/repo", runner.clone());
provider.delete("bug").await.expect("should delete");
assert_eq!(
runner.recorded_calls()[0].1,
vec!["label", "delete", "bug", "--yes", "--repo", "owner/repo"]
);
}
#[tokio::test]
async fn test_should_route_milestone_list_through_runner() {
let runner = MockCommandRunner::success("[]");
let provider = GitHubMilestoneProvider::with_runner("owner/repo", runner.clone());
let paged = provider.list(None).await.expect("should list");
assert!(paged.items.is_empty());
let calls = runner.recorded_calls();
assert_eq!(calls.len(), 1);
assert_eq!(calls[0].0, "gh");
assert_eq!(calls[0].1[0], "api");
assert!(calls[0].1[1].contains("per_page=100"));
assert!(calls[0].1[1].contains("page=1"));
}
#[tokio::test]
async fn test_should_produce_complete_argv_for_milestone_list_with_default_limit() {
let runner = MockCommandRunner::success("[]");
let provider = GitHubMilestoneProvider::with_runner("owner/repo", runner.clone());
let paged = provider.list(None).await.expect("should list");
assert!(paged.items.is_empty());
assert_eq!(
runner.recorded_calls()[0].1,
vec!["api", "repos/owner/repo/milestones?per_page=100&page=1"]
);
}
#[tokio::test]
async fn test_should_increment_page_across_calls_for_milestone_list() {
let full_page: Vec<String> = (0..100)
.map(|i| {
format!(
r#"{{"number":{i},"title":"v{i}","state":"open","closed_issues":0,"open_issues":0}}"#
)
})
.collect();
let full_page_json = format!("[{}]", full_page.join(","));
let short_page: Vec<String> = (100..151)
.map(|i| {
format!(
r#"{{"number":{i},"title":"v{i}","state":"open","closed_issues":0,"open_issues":0}}"#
)
})
.collect();
let short_page_json = format!("[{}]", short_page.join(","));
let runner = SequencedMockCommandRunner::from_results(&[
(true, &full_page_json),
(true, &short_page_json),
]);
let provider = GitHubMilestoneProvider::with_runner("owner/repo", runner.clone());
let paged = provider
.list(Some(150))
.await
.expect("should list across two pages");
assert_eq!(paged.items.len(), 150);
assert!(
paged.truncated,
"100 + 51 = 151 条超出 cap=150,N+1 探测必须报告截断"
);
let calls = runner.recorded_calls();
assert_eq!(calls.len(), 2, "必须恰好翻两页");
assert_eq!(calls[0].0, "gh");
assert_eq!(calls[1].0, "gh");
assert!(
calls[0].1[1].contains("page=1"),
"第一次调用必须请求 page=1,实际: {:?}",
calls[0].1
);
assert!(
calls[1].1[1].contains("page=2"),
"第二次调用必须请求 page=2,实际: {:?}",
calls[1].1
);
}
#[test]
fn test_should_construct_github_milestone_provider() {
let provider = GitHubMilestoneProvider::new("octocat/hello-world");
assert_eq!(provider.repo, "octocat/hello-world");
}
#[test]
fn test_should_debug_format_milestone_provider() {
let provider = GitHubMilestoneProvider::new("owner/repo");
let debug = format!("{provider:?}");
assert!(debug.contains("GitHubMilestoneProvider"));
assert!(debug.contains("owner/repo"));
}
#[test]
fn test_should_clone_github_milestone_provider() {
let original = GitHubMilestoneProvider::new("owner/repo");
let cloned = original.clone();
assert_eq!(original.repo, cloned.repo);
}
#[test]
fn test_should_deserialize_label_data_from_gh_output() {
let json = br#"[
{"name": "bug", "color": "d73a4a", "description": "Something isn't working"},
{"name": "enhancement", "color": "a2eeef", "description": null}
]"#;
let labels: Vec<LabelData> = serde_json::from_slice(json).expect("valid LabelData list");
assert_eq!(labels.len(), 2);
assert_eq!(labels[0].name, "bug");
assert_eq!(labels[0].color.as_deref(), Some("d73a4a"));
assert_eq!(labels[1].description, None);
}
#[test]
fn test_should_deserialize_single_label_from_gh_output() {
let json = br#"{"name": "wip", "color": "ffff00", "description": "Work in progress"}"#;
let label: LabelData = serde_json::from_slice(json).expect("valid LabelData");
assert_eq!(label.name, "wip");
assert_eq!(label.color.as_deref(), Some("ffff00"));
assert_eq!(label.description.as_deref(), Some("Work in progress"));
}
#[test]
fn test_should_deserialize_empty_label_list() {
let json = b"[]";
let labels: Vec<LabelData> =
serde_json::from_slice(json).expect("valid empty LabelData list");
assert!(labels.is_empty());
}
#[test]
fn test_should_deserialize_milestone_api_response() {
let json = br#"{
"number": 1,
"title": "v1.0 Release",
"description": "First stable release",
"state": "open",
"due_on": "2026-06-01T00:00:00Z",
"closed_issues": 10,
"open_issues": 5
}"#;
let api: MilestoneApiResponse =
serde_json::from_slice(json).expect("valid MilestoneApiResponse");
let data: MilestoneData = api.into();
assert_eq!(data.number, 1);
assert_eq!(data.title, "v1.0 Release");
assert_eq!(data.description, Some("First stable release".into()));
assert_eq!(data.state, State::Open);
assert!(data.due_on.is_some());
assert_eq!(data.closed_issues, 10);
assert_eq!(data.open_issues, 5);
}
#[test]
fn test_should_deserialize_closed_milestone() {
let json = br#"{
"number": 2,
"title": "v0.9 Beta",
"description": null,
"state": "closed",
"due_on": null,
"closed_issues": 20,
"open_issues": 0
}"#;
let api: MilestoneApiResponse =
serde_json::from_slice(json).expect("valid MilestoneApiResponse");
let data: MilestoneData = api.into();
assert_eq!(data.state, State::Closed);
assert!(data.description.is_none());
assert!(data.due_on.is_none());
}
#[test]
fn test_should_deserialize_milestone_list() {
let json = br#"[
{"number": 1, "title": "v1.0", "description": null, "state": "open", "due_on": null, "closed_issues": 0, "open_issues": 3},
{"number": 2, "title": "v0.9", "description": "Beta", "state": "closed", "due_on": "2026-01-01T00:00:00Z", "closed_issues": 15, "open_issues": 0}
]"#;
let milestones: Vec<MilestoneApiResponse> =
serde_json::from_slice(json).expect("valid MilestoneApiResponse list");
assert_eq!(milestones.len(), 2);
assert_eq!(milestones[0].title, "v1.0");
assert_eq!(milestones[1].title, "v0.9");
}
#[test]
fn test_should_convert_milestone_api_to_data() {
let api = MilestoneApiResponse {
number: 42,
title: "Test Milestone".into(),
description: Some("A test".into()),
state: "open".into(),
due_on: Some("2026-12-01T00:00:00Z".into()),
closed_issues: 5,
open_issues: 10,
};
let data: MilestoneData = api.clone().into();
assert_eq!(data.number, api.number);
assert_eq!(data.title, api.title);
}
}