Documentation
¶
Overview ¶
Package engine provides the core concurrency and execution logic for Corral.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
func Run(ctx context.Context, opts RunOptions)
Run executes the core Corral workflow, orchestrating GitHub API fetches, legacy layout migrations, concurrent Git operations, and orphaned repository detection.
Example ¶
ExampleRun demonstrates a complete run: clone and organise every public Go and Rust repository for an owner over SSH using shallow single-branch clones, syncing existing checkouts, reporting orphaned local repositories, and emitting a machine-readable JSON summary.
package main
import (
"context"
"github.com/sebastienrousseau/corral/internal/engine"
"github.com/sebastienrousseau/corral/internal/git"
"github.com/sebastienrousseau/corral/internal/github"
)
func main() {
ctx := context.Background()
engine.Run(ctx, engine.RunOptions{
Owner: "sebastienrousseau",
BaseDir: "/home/me/Code",
Concurrency: 8,
DoSync: true,
Orphans: true,
Protocol: "ssh",
Output: engine.OutputJSON,
Fetch: github.FetchOptions{
Limit: 500,
Visibility: "public",
IncludeLanguages: []string{"go", "rust"},
AuthMode: github.AuthModeAuto,
},
Clone: git.CloneOptions{
SingleBranch: true,
Depth: 1,
},
})
}
Output:
Example (DryRun) ¶
ExampleRun_dryRun demonstrates previewing actions without making any changes, streaming one NDJSON record per repository.
package main
import (
"context"
"github.com/sebastienrousseau/corral/internal/engine"
"github.com/sebastienrousseau/corral/internal/github"
)
func main() {
ctx := context.Background()
engine.Run(ctx, engine.RunOptions{
Owner: "sebastienrousseau",
BaseDir: "/home/me/Code",
Concurrency: 1,
DryRun: true,
Protocol: "https",
Output: engine.OutputNDJSON,
Fetch: github.FetchOptions{Limit: 1000},
})
}
Output:
Types ¶
type Job ¶
type Job struct {
// Repo is the GitHub repository to be processed.
Repo github.Repo
// Target is the destination directory for the repository under the new layout.
Target string
// Legacy is the directory where the repository may exist under the old layout.
Legacy string
}
Job encapsulates a repository to be processed along with its target directories.
type OutputFormat ¶ added in v0.0.3
type OutputFormat string
OutputFormat controls how operation results are emitted.
const ( // OutputText emits human-readable, line-oriented progress output. OutputText OutputFormat = "text" // OutputJSON emits a single aggregated JSON document at the end of the run. OutputJSON OutputFormat = "json" // OutputNDJSON emits one JSON object per result as a stream of newline-delimited records. OutputNDJSON OutputFormat = "ndjson" )
type RepoResult ¶ added in v0.0.3
type RepoResult struct {
// RepoName is the name of the processed repository.
RepoName string `json:"repo"`
// Action is the outcome verb, such as CLONE, SYNC, SKIP, ERROR, or DRY-RUN.
Action string `json:"action"`
// Message is a human-readable description of the outcome.
Message string `json:"message"`
// Target is the destination directory for the repository.
Target string `json:"target"`
// Visibility is the repository visibility (e.g. Public or Private).
Visibility string `json:"visibility"`
// Language is the normalized primary language directory name.
Language string `json:"language"`
// DryRun indicates whether the run was performed in dry-run mode.
DryRun bool `json:"dry_run"`
// Protocol is the clone transport used (https or ssh).
Protocol string `json:"protocol"`
// ClonedURL is the URL used for cloning, if a clone was attempted.
ClonedURL string `json:"clone_url,omitempty"`
// SyncAttempt indicates whether a sync (pull) was attempted.
SyncAttempt bool `json:"sync_attempt"`
}
RepoResult represents the final status of processing a repository.
type RunOptions ¶ added in v0.0.3
type RunOptions struct {
// Owner is the GitHub user or organization whose repositories are processed.
Owner string
// BaseDir is the root directory under which repositories are laid out.
BaseDir string
// Concurrency is the number of worker goroutines processing repositories; must be >= 1.
Concurrency int
// DryRun, when true, reports intended actions without performing clone or pull operations.
DryRun bool
// Orphans, when true, enables detection of local repositories no longer present upstream.
Orphans bool
// Protocol selects the clone transport and must be either "https" or "ssh".
Protocol string
// DoSync, when true, pulls updates into existing repositories.
DoSync bool
// Output selects the result emission format (text, json, or ndjson).
Output OutputFormat
// Fetch holds the options passed to the GitHub repository listing call.
Fetch github.FetchOptions
// Clone holds the options passed to each Git clone operation.
Clone git.CloneOptions
}
RunOptions contains all execution controls for a run.
type Summary ¶ added in v0.0.3
type Summary struct {
// Total is the number of repositories scheduled for processing.
Total int `json:"total"`
// Cloned is the number of repositories successfully cloned.
Cloned int `json:"cloned"`
// Synced is the number of repositories successfully synced.
Synced int `json:"synced"`
// Skipped is the number of repositories skipped.
Skipped int `json:"skipped"`
// Failed is the number of repositories that failed to process.
Failed int `json:"failed"`
}
Summary tracks aggregate run outcomes.
Source Files
Click to show internal directories.
Click to hide internal directories.