Crate onevcs

Expand description

Version control and its remote host behind one host-neutral vocabulary.

The review unit is a ChangeRequest — GitHub maps it to a pull request, and a later host maps it to whatever it calls the same thing. Vcs owns the repository side (identities, sessions, preserved work) and RemoteHost owns the host side (opening a change, reading its checks, merging it). A rules file decides, per repository, how a change is published and whether it needs an approval. Everything a process does along the way is emitted as an Envelope.

§The shape of one change

session open  →  a --shared clone and one worktree, occupancy-leased: a warm
                  pool slot where the host keeps one, else cut for this run
   →  work happens in the worktree
   →  publish   →  fetch and merge the current base  (bounded resolve-and-requeue)
                →  the repository's own merge path verifies it: its pre-push
                   hook, or the host's required checks on the change request
                →  local-direct squash, or a change request the host lands
   →  session close  →  the branch is copied out and stays; a slot is returned
                        warm, a per-run worktree goes

Everything durable lives under one state root (ONEVCS_HOME, otherwise ~/.onevcs): the registry document, the advisory locks and merge-queue state, the per-session workspaces, the event streams, and their artifacts.

§Two surfaces over one decision

run is the command line: it answers a process, with an exit code and a line of prose. A caller embedding this crate wants the decision itself, so the same operations answer values — publish hands back a Publication, close_session the session it released, session what the repository side recorded, preserve what putting a branch on its origin did, recoverable the branches that still hold unpublished work, and EventStream the envelopes one session wrote. The command line is a rendering of those rather than a second path through them.

Every command is: registered_identities and repositories are what onevcs repos prints, register_checkout, resolve_repository, publish_branch, recover, work_status, import_branch, integrate, sync, sweep, rules_check, read_artifact and EventLines are the rest, and a command with no such operation fails this crate’s own contract suite.

Re-exports§

pub use declaration::Declaration;
pub use declaration::DeclaredTarget;
pub use declaration::InstructionTemplate;
pub use declaration::RegistryId;
pub use declaration::RetiredArtifact;
pub use registry::Identity;
pub use releases::Acknowledgement;
pub use releases::Adoption;
pub use releases::Baseline;
pub use releases::BaselineRecord;
pub use releases::DeclarationPolicy;
pub use releases::DeclarationSource;
pub use releases::Discovery;
pub use releases::Probe;
pub use releases::ReleaseAnswer;
pub use releases::ReleaseDefault;
pub use releases::ReleaseMethod;
pub use releases::ReleaseRule;
pub use releases::ReleaseSource;
pub use releases::ReleaseStatus;
pub use releases::ReleaseStyle;
pub use releases::ReleaseTarget;
pub use releases::ReleasesFile;
pub use releases::RepositoryReleases;
pub use releases::SupersededRelease;
pub use releases::TargetName;
pub use releases::TargetRelease;
pub use releases::TargetSource;
pub use rules::MergePolicy;
pub use workspaces::first_matching;
pub use workspaces::Bound;
pub use workspaces::Span;

Modules§

branches: The branch prefix: one string this host puts in front of every branch onevcs cuts, and the sanitizer that turns a caller’s proposed name into one git accepts.
cli: The command-line argument surface.
declaration: The producer’s own release declaration: what one repository publishes.
provenance: What a branch records about how its work came to be there.
registry: The registry document: which repository identities exist, which checkouts belong to each, and where the rules file lives.
releases: The release-targets file: what each repository releases, and how a release of it is learned about.
rules: The rules file: how each repository publishes a change.
workspaces: The workspaces file: how many warm worktree slots each repository keeps on this host, and how many sessions it admits past them.

Structs§

ArtifactId: The id of a stored artifact.
ArtifactRef: Evidence too large for a payload: stored by the producing library and referenced by id, to be read back through that library.
BranchHolder: One place a copy of a branch is.
BranchOutcome: What one candidate of the train did.
BranchPublishRequest: What to publish, for the branch-keyed verb that takes completed work.
BranchRef: One branch of one identity: the pair a pass is told to leave alone by.
ChangeChecks: What a host reports about a change request’s checks, and where it looked.
ChangeDescription: What a caller writes to a change request’s description.
ChangeId: A host’s identifier for a change request.
ChangeRequest: An open change request on the host.
ChangeSpec: What to open a change request for.
Check: One check the host reports on a change request.
CheckoutAudit: What the gate audit found about one checkout.
Description: A change request’s description as the host holds it.
Dimensions: The envelope’s reserved top-level dimensions: phase, optional and omitted from the wire when absent.
EventLine: One line of a session’s event stream, as its writer left it.
EventLines: A reader over one session’s event stream as text, which is what onevcs events prints.
EventStream: A reader over one session’s event stream, as values rather than as text.
FailedHolder: A place a deletion did not reach, and why.
Git: The git implementation of Vcs.
GitHub: The GitHub implementation of RemoteHost, driven through gh.
HeldBy: What still holds a preserved branch: a live session, or a publication of it running right now.
IdentityMaintenance: One identity, and what maintaining it came to.
ImportRequest: Which branch to make reachable from an identity’s registered checkouts.
Imported: What one import did.
IntegrateRequest: Which branches to merge into their base, in order.
Integration: What the whole train did.
Labels: The reserved label keys, plus whatever else a producer stamped.
LineChange: The lines a branch would land, as git counts them against the commit it forked from.
MaintainReport: What pool maintain did: every identity in scope, and what became of each.
MatchFields: What a matcher may name beside source and kind: phase and the reserved labels, each by exact equality against what the envelope carries. round is deliberately not among them, as the grammar says.
MatchedRule: The rule a repository matched, and what it matched on.
NetNegative: A LineChange that removes more than it adds, and the only thing that can be one.
OnOrigin: Where a branch was last put on its identity’s origin without being published.
OpenConflict: A merge left in progress in a session’s worktree, for the session to conclude.
PoolStatus: What pool status reports: the capacity, and every slot.
PreserveRequest: What to preserve, and where to look for it.
Preserved: What preserving one branch did.
PreservedBranch: A branch that holds work outside its session.
Providers: The repository side and the remote-host side of one run.
PruneReport: What pool prune did: which slots it removed, and which it kept and why.
Publication: What one publication did.
PublishRequest: What one publication was asked for beyond the session it publishes.
RecoverRequest: What to recover, for the branch-keyed verb that takes work a step left behind.
Recoverable: Preserved work, whether it reached its base, and what would land it.
RegisteredCheckout: One registered checkout of an identity.
RegisteredRepository: One registered repository identity, as onevcs repos lists it.
Registration: What onevcs register recorded, and what the identity it recorded publishes under.
RequiredChecks: What a host requires before a merge into a branch, and how much of the host that answer covers.
ResolvedPolicy: The publication policy a repository resolves to, and where each half of it came from.
ResolvedRepository: What one repository argument resolves to.
RetirePass: The automatic pass over every finished branch in scope.
RetireRequest: One retirement asked for by name.
Retired: One branch’s retirement: its classification, and what was done about it.
Retirement: What a branch is, and everything that says so.
RetirementPassReport: What one automatic pass examined, and what became of each branch.
RetirementQuery: Which branch to classify.
RulesCheck: How one repository resolves against this host’s rules.
Selection: Which of the preserved work in scope a report is asked to answer with.
Session: An open session: a per-run shared clone plus a worktree, held under an occupancy lease.
SessionChange: A session’s change request, as the host holds it right now.
SessionHolder: One session that holds a repository’s workspace, as an enumeration reports it.
SessionRecord: Everything the implementation that opened a session records about it.
SessionRequest: What to open a session over.
SessionToken: The handle a session is adopted, published, and closed by.
Sha: A commit hash.
SlotMaintenance: One slot, and what became of it.
SlotStatus: One slot, as pool status reports it.
Source: An open source word: whatever produced the event, by name.
StatusReport: Everything this host knows about one piece of work, as onevcs status answers it.
Subject: A title that can be the subject of the commit a publication lands.
SupersededBy: The retry that superseded a branch, as its record says.
Supersession: A record that a branch was superseded by a retry that landed.
SweepReport: What one sweep examined, reclaimed, and retained.
Synced: What one fast-forward of a publication checkout did.
UnknownCause: The read that failed, for a branch kept as KeepReason::Unknown: which read it was, what it read, and the error it got — so a kept branch says what to look at rather than only that something could not be read.
Url: A parsed absolute URL, re-exported so a caller needs no direct dependency on the parser this crate validates change-request URLs with. A parsed URL record.
VcsEvents: This crate’s vocabulary: what Envelope, EventFilter and EventMatcher are the bus core’s generic types over.
WorkspaceCapacity: How many sessions one identity can admit right now, and whether one request would be placed.

Enums§

BasePush: What the train does with the base once it has advanced it.
BranchHolderKind: Which kind of place holds a copy of a branch.
CheckSource: One place a host’s answer about a change request’s checks was read from.
CheckState: Which of five states one check is in, as Check::state classifies it.
Derivation: Whether a pass derived a branch’s verdict or reused one it recorded earlier.
DraftReason: Why a change request is a draft, in the shape a machine reads it.
Error: Everything an onevcs operation can fail with.
EventKind: What an event says happened.
FailureKind: Which failure ended a publication, and therefore which exit code says so.
GateAudit: Whether a listing carries the gate audit, which is what --audit-gates asks for.
Holding: How a host can tell that something still holds a branch.
IdentityOutcome: What became of one identity.
ImportSource: Where an import read the branch from.
IntegrationEnding: Where the train left the base.
IntegrationStatus: What happened to one candidate of the train.
KeepReason: Why a branch is kept.
Landed: Whether the work reached the base, and — where it did — what says so.
LandingEvidence: Which tier decided a landing, and the commit that is its evidence.
Lifecycle: Where a session is in its life.
Liveness: Whether a session’s owner is still running, which is what makes its lease real.
MaintenanceOutcome: How a maintenance run ended.
MergeOutcome: What merging a change request did.
MergePathCoverage: What runs a gate on an identity’s merge path.
Mergeability: Whether a change request can merge into its base, as RemoteHost::mergeability answers it.
Phase: Which part of a change’s life an event belongs to.
Preservation: What preserving one branch found to do.
ProtectionSource: One of the ways a host protects a branch, each of which may name required checks.
Provenance: Why a branch was preserved, and therefore what recovering it must do.
PublishOutcome: How a publication ended.
RequiredChecksAnswer: What an identity’s host says it requires before a merge.
Retention: What became of a branch whose publication did not land.
RetireMode: Which classes a retirement may act on.
RetireOutcome: What a retirement did.
RetirementClass: What a branch is, for the question of whether it may be deleted.
RetirementProof: What proves a branch holds no work beyond its base.
Scope: Which preserved work to look for.
SlotOutcome: What became of one slot.
SlotState: Where one slot is in its life, as pool status reports it.
Sweeping: Whether a sweep performs what it decided, which is what --dry-run asks.
TrailerPrefixSource: What decided the provenance trailer prefix.
Wrote: What one import did to the name it wrote.

Constants§

DIMENSIONS: The reserved top-level dimensions: phase alone.
HOST_PREREQUISITE_MARKER: How a merge-path hook begins the one line saying a refusal is this host’s rather than the work’s: a tool or a credential it needs is missing, and what follows the marker says which and how to install it.
RESERVED_LABELS: The reserved label keys, in the order the wire lists them.
SOURCE_WORD: The word this crate stamps as the source of every event it writes.

Traits§

Hosting: Where a RemoteHost for one repository comes from.
PhaseOf: The phase an event of one of this crate’s kinds belongs to, where the kind alone decides it.
PublicationCancellation: Whether the caller of a publication has asked it to stop.
RemoteHost: Everything onevcs asks of a repository’s remote host.
Vcs: Everything onevcs does to a repository, independent of which version control system is underneath.

Functions§

acknowledge_release: Record the release somebody says carries a landing.
adoption_for: Which rung of the adoption chain one repository resolves to.
classify_retirement: What one branch is, for the question of whether it may be deleted: retirable, superseded-with-changes, or keep with the one reason it is kept.
close_session: Release a session’s worktree and its occupancy lease, keeping its branch.
describe_change: Replace the description of the session’s own change request — its body, and its title when one is given — and report the change as it stands after the write.
import_branch: Make one branch reachable from an identity’s registered checkouts.
integrate: Merge finished branches into their base, in order.
landing_status: Whether one piece of work reached its base, and what says so.
pool_maintain: Maintain the idle slots of every identity in scope.
pool_prune: Remove every slot of one repository nobody is in — idle, or broken — whose clone retains no branch, and say why each other one was kept.
pool_status: The pool of one repository: its capacity with no per-open override, and every slot.
preserve: Put an unpublished branch on its identity’s origin, under its own name, without publishing it.
publish: Verify a session’s work and publish it, returning what the publication did.
publish_branch: Verify and publish a completed branch no session holds.
publish_with_cancellation: publish, stopping once cancellation says so.
read_artifact: Read one stored artifact.
read_release_declaration: What one repository declares that it publishes.
ready_change: Mark the session’s own change request ready for review, and report it as it stands.
record_supersession: Record that a branch was superseded by a retry that landed.
recover: Verify and publish a preserved branch that a step left behind, attesting it.
recoverable: Every preserved-but-unpublished branch in scope, and what would land each.
register_checkout: Register a checkout, resolving its origin to a repository identity.
registered_identities: Every repository identity this host has registered, in the order onevcs repos lists them.
release_discovery: Every target one repository has, and what each of them has released right now.
release_latest: What version of one target is released right now.
release_status: Whether the release that carries one landed change has happened yet.
release_targets: What one repository releases, and what it adopts.
render_release_declaration: Render a declaration back as the TOML document it declares.
repositories: Every registered repository, in the order onevcs repos lists them.
resolve_repository: Resolve a repository argument — an identity key, a registered alias, an origin URL, or a path — to the identity it selects.
retire: Delete one branch everywhere this host holds it, where its class permits.
retire_finished: Retire every branch in scope that provably holds no work beyond its base.
rules_check: Explain how one repository resolves against this host’s rules.
run: Run one parsed command line, returning the process exit code.
run_with: Run one parsed command line against supplied implementations of the two interfaces, returning the process exit code.
session: What the repository side recorded about a session.
session_change: The session’s own change request — the one publish would open or adopt for it, from its branch into the base its publication resolves — as the host holds it, or None when the host holds none.
session_holders: Every session recorded for one repository, live or not, in token order.
sweep: Reclaim the publication workspaces this host has finished with.
sync: Fast-forward a publication checkout to its origin.
validate_release_declaration: Validate one release declaration’s text, and answer what it declares.
work_status: Report everything this host knows about one piece of work.
workspace_capacity: How many sessions the request’s identity admits right now, and whether the request itself would be placed.

Type Aliases§

Envelope: One event of this crate: the bus core’s envelope over this vocabulary.
EventFilter: Which envelopes pass: the bus core’s filter over this vocabulary.
EventMatcher: One matcher of an EventFilter: source, kind, and the MatchFields — phase and the five reserved labels a matcher may name.
Result: The result type every fallible entry point in this crate returns.

Crate onevcs

Crate onevcs Copy item path

§The shape of one change

§Two surfaces over one decision

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate onevcs