Skip to main content

SourceAdapter

ta_submit::adapter

Trait SourceAdapter 

Source 
pub trait SourceAdapter: Send + Sync {

Show 17 methods    // Required methods
    fn prepare(&self, goal: &GoalRun, config: &SubmitConfig) -> Result<()>;
    fn commit(
        &self,
        goal: &GoalRun,
        pr: &DraftPackage,
        message: &str,
    ) -> Result<CommitResult>;
    fn push(&self, goal: &GoalRun) -> Result<PushResult>;
    fn open_review(
        &self,
        goal: &GoalRun,
        pr: &DraftPackage,
    ) -> Result<ReviewResult>;
    fn name(&self) -> &str;

    // Provided methods
    fn sync_upstream(&self) -> Result<SyncResult> { ... }
    fn exclude_patterns(&self) -> Vec<String> { ... }
    fn save_state(&self) -> Result<Option<SavedVcsState>> { ... }
    fn restore_state(&self, _state: Option<SavedVcsState>) -> Result<()> { ... }
    fn current_branch(&self) -> Result<String> { ... }
    fn revision_id(&self) -> Result<String> { ... }
    fn check_review(&self, _review_id: &str) -> Result<Option<ReviewStatus>> { ... }
    fn merge_review(&self, _review_id: &str) -> Result<MergeResult> { ... }
    fn detect(project_root: &Path) -> bool
       where Self: Sized { ... }
    fn protected_submit_targets(&self) -> Vec<String> { ... }
    fn verify_not_on_protected_target(&self) -> Result<()> { ... }
    fn stage_env(
        &self,
        _staging_dir: &Path,
        _config: &VcsAgentConfig,
    ) -> Result<HashMap<String, String>> { ... }

}
Expand description

Pluggable adapter for source control operations (submit + sync).

The staging->review->apply loop is VCS-agnostic. This trait allows different implementations for Git, Perforce, SVN, or custom workflows.

Renamed from SubmitAdapter in v0.11.1 to reflect the unified scope (submit + sync). The old name is available as a type alias.

Required Methods§

Source

fn prepare(&self, goal: &GoalRun, config: &SubmitConfig) -> Result<()>

Create a working branch/changelist/workspace for this goal

For Git: creates a feature branch For Perforce: creates a changelist For “none”: no-op

Source

fn commit( &self, goal: &GoalRun, pr: &DraftPackage, message: &str, ) -> Result<CommitResult>

Commit the approved changes from staging

For Git: git add + git commit For Perforce: shelve files For “none”: no-op

Source

fn push(&self, goal: &GoalRun) -> Result<PushResult>

Push the committed changes

For Git: git push For Perforce: submit changelist For “none”: no-op

Source

fn open_review(&self, goal: &GoalRun, pr: &DraftPackage) -> Result<ReviewResult>

Open a review request

For Git: create GitHub/GitLab PR via API or gh pr create For Perforce: create Swarm review For “none”: no-op

Source

fn name(&self) -> &str

Adapter display name (for CLI output)

Provided Methods§

Source

fn sync_upstream(&self) -> Result<SyncResult>

Sync the local workspace with upstream changes.

For Git: git fetch + merge/rebase/ff per source.git.sync_strategy For SVN: svn update For Perforce: p4 sync For “none”: no-op (always returns updated=false)

Returns a SyncResult describing what happened. If conflicts are detected, SyncResult.conflicts is non-empty but the method still returns Ok — the caller decides how to handle conflicts. Only returns Err for infrastructure failures (network, permissions).

Source

fn exclude_patterns(&self) -> Vec<String>

Patterns to exclude from staging copy (VCS metadata dirs, etc.)

Returns patterns in .taignore format: “dirname/”, “*.ext”, “name”. These are merged with user .taignore patterns and built-in defaults during overlay workspace creation and diffing.

Source

fn save_state(&self) -> Result<Option<SavedVcsState>>

Save working state before apply operations.

Git: saves the current branch name so it can be restored after commit. Perforce: saves the current changelist context. Default: no-op (returns None).

Source

fn restore_state(&self, _state: Option<SavedVcsState>) -> Result<()>

Restore working state after apply operations.

Git: switches back to the original branch. Perforce: reverts to saved client state. Default: no-op.

Source

fn current_branch(&self) -> Result<String>

Get the current branch or workspace name.

Git: current branch name (e.g., “main”, “feature/abc-def”) SVN: working copy URL path Perforce: current client/workspace name Default: “unknown”

Source

fn revision_id(&self) -> Result<String>

Get the current revision identifier for the working directory.

Git: short commit hash (e.g., “abc1234”) SVN: revision number (e.g., “r1234”) Perforce: changelist number (e.g., “@1234”) Default: “unknown”

Source

fn check_review(&self, _review_id: &str) -> Result<Option<ReviewStatus>>

Check the status of a review/PR by its review ID (e.g., PR number).

Git: uses gh pr view --json state to check PR status. Returns the current state as a string: “open”, “merged”, “closed”. Default: returns None (not supported).

Source

fn merge_review(&self, _review_id: &str) -> Result<MergeResult>

Merge a review/PR into the target branch and sync the local workspace.

Git: calls gh pr merge to merge the PR immediately. Perforce: calls p4 submit -c <CL> to submit the shelved changelist. SVN: no-op (SVN commits directly; no separate merge step). Default: no-op, returns a guidance message telling the user what to do.

Returns a MergeResult describing what happened. merged = true means the merge was completed immediately; merged = false means auto-merge is pending (CI must pass first).

Source

fn detect(project_root: &Path) -> bool
where Self: Sized,

Auto-detect whether this adapter applies to the given project root.

Git: checks for .git/ directory SVN: checks for .svn/ directory Perforce: checks for P4CONFIG env var or .p4config

Source

fn protected_submit_targets(&self) -> Vec<String>

Protected submit targets for this adapter (§15 VCS Submit Invariant).

Returns the list of refs/branches/paths that agents must never commit directly to. prepare() must create an isolation mechanism (feature branch, shelved CL, etc.) before verify_not_on_protected_target() is called.

Default: empty list (no protected targets — applies to adapters that handle isolation entirely through their prepare() implementation).

Source

fn verify_not_on_protected_target(&self) -> Result<()>

Assert the post-prepare() invariant: the adapter must not be positioned to commit directly to a protected target (§15).

Called immediately after prepare() succeeds, before any commit or push. Hard failure aborts the apply workflow.

Default implementation: if protected_submit_targets() returns a non-empty list, subclasses should override this to check the current position. The base implementation is a no-op (safe for adapters whose prepare() guarantees isolation without needing an extra check).

Source

fn stage_env( &self, _staging_dir: &Path, _config: &VcsAgentConfig, ) -> Result<HashMap<String, String>>

Produce environment variables to inject into the agent process so it operates on the staging directory instead of the developer’s real VCS workspace (v0.13.17.3).

Called by ta run before spawning the agent. The returned vars are merged into the agent’s process environment.

Default: no-op (returns empty map). VCS adapters that support isolation should override this method.

Implementors§