vgi_forge/lib.rs
1//! Forge-neutral adapter layer for VGI git namespaces.
2//!
3//! A VTC governs who may create, own, maintain and commit to repositories in
4//! a namespace; the forge (GitHub, Forgejo, …) is where that is *enforced*.
5//! This crate is the seam between the two: the [`Forge`] trait an adapter
6//! implements, the [`ForgeHooks`] it may add, and the data both sides
7//! exchange — [`Resource`]s, [`EffectiveRights`], [`Capabilities`],
8//! bootstrap plans, [`ForgeEvent`]s and [`Drift`].
9//!
10//! Nothing here talks to a forge. Adapters live in their own crates
11//! (`vgi-forge-github` first), so the core compiles without any forge's
12//! HTTP stack, and a forge's limitations reach the core only as
13//! [`Capabilities`] — never as a branch on which forge it is.
14//!
15//! Three rules hold across every adapter:
16//!
17//! - **Resources are forge-qualified and normalised** by the one grammar in
18//! [`vgi_core::resource`], so a grant, a registry tuple and a verify-trust
19//! query name a repository with the same bytes.
20//! - **Roles round down.** A forge with fewer role levels gives less than
21//! the community asked for, never more ([`collapse_to_ladder`]).
22//! - **Accounts are numeric ids.** Logins are display-only; a renamed and
23//! re-registered login must never inherit a role.
24
25mod bootstrap;
26mod error;
27mod event;
28mod forge;
29mod hooks;
30mod model;
31mod pulls;
32mod resource;
33mod rights;
34
35pub use bootstrap::{
36 BootstrapComponent, BootstrapReport, BootstrapStep, DEFAULT_REQUIRED_CHECK, ExtraFile,
37 MergeMethod, ProtectionSpec, RepoSettings, StepAction, StepOutcome, VerifyTransport, VgiConfig,
38 run_plan, validate_repo_path,
39};
40pub use error::{ForgeError, Result};
41pub use event::{
42 Drift, ForgeEvent, ForgeEventKind, InstallationChange, MemberChange, ProtectionGap,
43 default_diff, protection_gaps,
44};
45pub use forge::Forge;
46pub use hooks::{ForgeHooks, HookDecision, NoHooks};
47pub use model::{
48 AccessSource, ApplyReport, BindCallback, BindRequest, BindStep, Capabilities, CheckSourceGuard,
49 Collaborator, ForgeAccount, ForgeKind, IndirectAccess, LinkCallback, LinkMethod, LinkStep,
50 Namespace, NamespaceBinding, NamespaceKind, Projection, ProtectionState, RepoSpec, RepoState,
51 RequiredCheckKind, RoleAssignment, RoleChange, RoleOutcome, Unlisted, Visibility,
52};
53pub use pulls::{PullRequest, PullRequestState, Reopen};
54pub use resource::{OWNER_REPO_DEPTH, Resource};
55pub use rights::{EffectiveRights, ForgeRole, Right, RoleMap, collapse_to_ladder};
56
57// Re-exported so adapters and callers name one `async_trait`.
58pub use async_trait::async_trait;