refactor: improve API ergonomics with builder pattern and method chaining (#165)

* refactor: add `borrow_self` to setters for various structs

* refactor: update method signatures to return mutable references for better chaining

* refactor: simplify job dependency management and streamline needs handling

* refactor: remove redundant `add_steps` method from `Job` struct

* revert borrow

* refactor: change methods to return self for better chaining in Cargo and workflow structs

* refactor: introduce Job and Step structures for GitHub workflow management

* refactor: add Concurrency and Permissions structures for workflow management

* feat: add Container configuration types for GitHub workflow jobs

* feat: add various structures for GitHub workflow management including artifacts, environment, defaults, and strategies

* refactor: update Step creation methods to use new constructor for better clarity and consistency

* refactor: enhance Toolchain structure and methods for improved clarity and functionality

* fix: update autofix action version to v1 for improved stability

* [autofix.ci] apply automated fixes

* fix: update autofix action version to v1 for improved stability

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: tusharmath

.github/workflows/autofix.yml

@@ -54,7 +54,8 @@ jobs:
       run: cargo +nightly fmt --all
     - name: Cargo Clippy
       run: cargo +nightly clippy --fix --allow-dirty --all-features --workspace -- -D warnings
-    - uses: autofix-ci/action@551dded8c6cc8a1054039c8bc0b8b48c51dfc6ef
+    - name: auto-fix
+      uses: autofix-ci/action@v1
     concurrency:
       group: autofix-${{github.ref}}
       cancel-in-progress: false

crates/gh-workflow-tailcall/src/standard.rs

@@ -26,6 +26,7 @@ pub enum TestRunner {
 }
 
 #[derive(Debug, Clone, Setters)]
+#[setters(strip_option, into)]
 pub struct StandardWorkflow {
     /// When enabled, a release job is added to the workflow.
     /// *IMPORTANT:* Ensure `secrets.CARGO_REGISTRY_TOKEN` is set for your
@@ -115,21 +116,19 @@ impl StandardWorkflow {
 
     /// Converts the workflow into a Github workflow.
     pub fn to_ci_workflow(&self) -> GHWorkflow {
-        GHWorkflow::new(self.name.clone())
+        let mut workflow = GHWorkflow::new(self.name.clone())
             .add_env(self.workflow_flags())
             .on(self.workflow_event())
             .add_job("build", self.test_job())
-            .add_job("lint", self.lint_job(false))
-            .add_job_when(
-                self.auto_release,
-                "release",
-                self.release_job(Command::Release),
-            )
-            .add_job_when(
-                self.auto_release,
-                "release-pr",
-                self.release_job(Command::ReleasePR),
-            )
+            .add_job("lint", self.lint_job(false));
+
+        if self.auto_release {
+            workflow = workflow
+                .add_job("release", self.release_job(Command::Release))
+                .add_job("release-pr", self.release_job(Command::ReleasePR));
+        }
+
+        workflow
     }
 
     fn release_job(&self, cmd: Command) -> Job {
@@ -139,8 +138,8 @@ impl StandardWorkflow {
                     .cancel_in_progress(false),
             )
             .cond(self.workflow_cond())
-            .add_needs(self.test_job())
-            .add_needs(self.lint_job(false))
+            .add_needs("build")
+            .add_needs("lint")
             .add_env(Env::github())
             .add_env(Env::new(
                 "CARGO_REGISTRY_TOKEN",
@@ -151,67 +150,71 @@ impl StandardWorkflow {
     }
 
     fn lint_job(&self, auto_fix: bool) -> Job {
-        let job = self.init_job(if auto_fix { "Lint Fix" } else { "Lint" });
+        let mut job = self.init_job(if auto_fix { "Lint Fix" } else { "Lint" });
 
-        let job = if auto_fix {
-            job.concurrency(
+        if auto_fix {
+            job = job.concurrency(
                 Concurrency::new(Expression::new("autofix-${{github.ref}}"))
                     .cancel_in_progress(false),
+            );
+        }
+
+        let mut fmt_step = Cargo::new("fmt")
+            .name("Cargo Fmt")
+            .nightly()
+            .add_args("--all");
+
+        if !auto_fix {
+            fmt_step = fmt_step.add_args("--check");
+        }
+
+        let mut clippy_step = Cargo::new("clippy").name("Cargo Clippy").nightly();
+
+        if auto_fix {
+            clippy_step = clippy_step.add_args("--fix").add_args("--allow-dirty");
+        }
+
+        clippy_step = clippy_step.add_args("--all-features --workspace -- -D warnings");
+
+        job = job
+            .add_step(
+                Toolchain::default()
+                    .add_nightly()
+                    .add_clippy()
+                    .add_fmt()
+                    .cache(true)
+                    .cache_directories(vec![
+                        "~/.cargo/registry".into(),
+                        "~/.cargo/git".into(),
+                        "target".into(),
+                    ]),
             )
-        } else {
-            job
-        };
-
-        job.add_step(
-            Toolchain::default()
-                .add_nightly()
-                .add_clippy()
-                .add_fmt()
-                .cache(true)
-                .cache_directories(vec![
-                    "~/.cargo/registry".into(),
-                    "~/.cargo/git".into(),
-                    "target".into(),
-                ]),
-        )
-        .add_step(
-            Cargo::new("fmt")
-                .name("Cargo Fmt")
-                .nightly()
-                .add_args("--all")
-                .add_args_when(!auto_fix, "--check"),
-        )
-        .add_step(
-            Cargo::new("clippy")
-                .name("Cargo Clippy")
-                .nightly()
-                .add_args_when(auto_fix, "--fix")
-                .add_args_when(auto_fix, "--allow-dirty")
-                .add_args("--all-features --workspace -- -D warnings"),
-        )
-        .add_step_when(
-            auto_fix,
-            Step::uses(
-                "autofix-ci",
-                "action",
-                "551dded8c6cc8a1054039c8bc0b8b48c51dfc6ef",
-            ),
-        )
+            .add_step(fmt_step)
+            .add_step(clippy_step);
+
+        if auto_fix {
+            job = job.add_step(Step::new("auto-fix").uses("autofix-ci", "action", "v1"));
+        }
+        job
     }
 
     /// Creates the "Build and Test" job for the workflow.
     fn test_job(&self) -> Job {
-        self.init_job("Build and Test")
-            .add_step(Toolchain::default().add_stable())
-            .add_step_when(
-                matches!(self.test_runner, TestRunner::Nextest),
+        let mut job = self
+            .init_job("Build and Test")
+            .add_step(Toolchain::default().add_stable());
+
+        if matches!(self.test_runner, TestRunner::Nextest) {
+            job = job.add_step(
                 Cargo::new("install")
                     .args("cargo-nextest --locked")
                     .name("Install nextest"),
-            )
+            );
+        }
+        job = job
             .add_step(
-                Step::uses("Swatinem", "rust-cache", "v2")
-                    .name("Cache Rust dependencies")
+                Step::new("Cache Rust dependencies")
+                    .uses("Swatinem", "rust-cache", "v2")
                     .add_with(("cache-all-crates", "true")),
             )
             .add_step(match self.test_runner {
@@ -221,11 +224,13 @@ impl StandardWorkflow {
                 TestRunner::Nextest => Cargo::new("nextest")
                     .args("run --all-features --workspace")
                     .name("Cargo Nextest"),
-            })
-            .add_step_when(
-                self.benchmarks,
-                Cargo::new("bench").args("--workspace").name("Cargo Bench"),
-            )
+            });
+
+        if self.benchmarks {
+            job = job.add_step(Cargo::new("bench").args("--workspace").name("Cargo Bench"));
+        }
+
+        job
     }
 
     fn write_permissions(&self) -> Permissions {

crates/gh-workflow-tailcall/tests/ci.rs

@@ -5,6 +5,7 @@ fn generate() {
     StandardWorkflow::default()
         .auto_release(true)
         .auto_fix(true)
+        .to_owned()
         .generate()
         .unwrap();
 }

crates/gh-workflow/src/artifacts.rs

@@ -0,0 +1,35 @@
+//!
+//! Artifact types for GitHub workflow job outputs and inputs.
+
+use derive_setters::Setters;
+use serde::{Deserialize, Serialize};
+
+/// Represents artifacts produced by jobs.
+#[derive(Debug, Setters, Serialize, Deserialize, Clone, Default, PartialEq, Eq)]
+#[serde(rename_all = "kebab-case")]
+#[setters(strip_option, into)]
+pub struct Artifacts {
+    /// Artifacts to upload after the job.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub upload: Option<Vec<Artifact>>,
+
+    /// Artifacts to download before the job.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub download: Option<Vec<Artifact>>,
+}
+
+/// Represents an artifact produced by a job.
+#[derive(Debug, Setters, Serialize, Deserialize, Clone, Default, PartialEq, Eq)]
+#[serde(rename_all = "kebab-case")]
+#[setters(strip_option, into)]
+pub struct Artifact {
+    /// The name of the artifact.
+    pub name: String,
+
+    /// The path to the artifact.
+    pub path: String,
+
+    /// The number of days to retain the artifact.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub retention_days: Option<u32>,
+}

crates/gh-workflow/src/cargo.rs

@@ -58,15 +58,6 @@ impl Cargo {
         );
         self
     }
-
-    /// Adds the arguments to the cargo command when a condition is met.
-    pub fn add_args_when<T: ToString>(self, when: bool, args: T) -> Self {
-        if when {
-            self.add_args(args)
-        } else {
-            self
-        }
-    }
 }
 
 impl From<Cargo> for Step<Run> {
@@ -77,7 +68,7 @@ impl From<Cargo> for Step<Run> {
             command.push(format!("+{toolchain}"));
         }
 
-        command.push(value.command);
+        command.push(value.command.clone());
 
         // Extend the command with non-empty arguments
         command.extend(
@@ -88,7 +79,7 @@ impl From<Cargo> for Step<Run> {
                 .filter(|arg| !arg.is_empty()),
         );
 
-        let mut step = Step::run(command.join(" "));
+        let mut step = Step::new(format!("Cargo {}", value.command)).run(command.join(" "));
 
         if let Some(id) = value.id {
             step = step.id(id);

crates/gh-workflow/src/concurrency.rs

@@ -0,0 +1,28 @@
+use derive_setters::Setters;
+use serde::{Deserialize, Serialize};
+
+use crate::expression::Expression;
+
+/// Represents concurrency settings for workflows.
+#[derive(Debug, Setters, Serialize, Deserialize, Clone, Default, PartialEq, Eq)]
+#[serde(rename_all = "kebab-case")]
+#[setters(strip_option, into)]
+pub struct Concurrency {
+    /// The group name for concurrency.
+    pub group: String,
+
+    /// Whether to cancel in-progress jobs.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cancel_in_progress: Option<bool>,
+
+    /// The limit on concurrent jobs.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub limit: Option<u32>,
+}
+
+impl Concurrency {
+    pub fn new(group: impl Into<Expression>) -> Self {
+        let expr: Expression = group.into();
+        Self { group: expr.0, ..Default::default() }
+    }
+}

crates/gh-workflow/src/container.rs

@@ -0,0 +1,89 @@
+//! Container configuration types for GitHub workflow jobs.
+
+use derive_setters::Setters;
+use serde::{Deserialize, Serialize};
+
+use crate::env::Env;
+
+/// Represents a container configuration for jobs.
+#[derive(Debug, Setters, Serialize, Deserialize, Clone, Default, PartialEq, Eq)]
+#[serde(rename_all = "kebab-case")]
+#[setters(strip_option, into)]
+pub struct Container {
+    /// The image to use for the container.
+    pub image: String,
+
+    /// Credentials for accessing the container.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub credentials: Option<Credentials>,
+
+    /// Environment variables for the container.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub env: Option<Env>,
+
+    /// Ports to expose from the container.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ports: Option<Vec<Port>>,
+
+    /// Volumes to mount in the container.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub volumes: Option<Vec<Volume>>,
+
+    /// Additional options for the container.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub options: Option<String>,
+
+    /// Hostname for the container.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub hostname: Option<String>,
+}
+
+/// Represents credentials for accessing a container.
+#[derive(Debug, Setters, Serialize, Deserialize, Clone, Default, PartialEq, Eq)]
+#[serde(rename_all = "kebab-case")]
+#[setters(strip_option, into)]
+pub struct Credentials {
+    /// The username for authentication.
+    pub username: String,
+
+    /// The password for authentication.
+    pub password: String,
+}
+
+/// Represents a network port.
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
+#[serde(rename_all = "kebab-case")]
+pub enum Port {
+    /// A port specified by its number.
+    Number(u16),
+
+    /// A port specified by its name.
+    Name(String),
+}
+
+/// Represents a volume configuration for containers.
+#[derive(Debug, Setters, Serialize, Deserialize, Clone, Default, PartialEq, Eq)]
+#[serde(rename_all = "kebab-case")]
+#[setters(strip_option, into)]
+pub struct Volume {
+    /// The source path of the volume.
+    pub source: String,
+
+    /// The destination path of the volume.
+    pub destination: String,
+}
+
+impl Volume {
+    /// Creates a new `Volume` from a string representation.
+    pub fn new(volume_str: &str) -> Option<Self> {
+        let parts: Vec<&str> = volume_str.split(':').collect();
+        if parts.len() == 2 {
+            Some(Volume {
+                source: parts[0].to_string(),
+                destination: parts[1].to_string(),
+            })
+        } else {
+            None
+        }
+    }
+}