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 resource;
32mod rights;
33
34pub use bootstrap::{
35 BootstrapComponent, BootstrapReport, BootstrapStep, DEFAULT_REQUIRED_CHECK, ExtraFile,
36 MergeMethod, ProtectionSpec, RepoSettings, StepAction, StepOutcome, VgiConfig, run_plan,
37 validate_repo_path,
38};
39pub use error::{ForgeError, Result};
40pub use event::{
41 Drift, ForgeEvent, ForgeEventKind, InstallationChange, MemberChange, ProtectionGap,
42 default_diff, protection_gaps,
43};
44pub use forge::Forge;
45pub use hooks::{ForgeHooks, HookDecision, NoHooks};
46pub use model::{
47 ApplyReport, BindCallback, BindRequest, BindStep, Capabilities, CheckSourceGuard, Collaborator,
48 ForgeAccount, ForgeKind, LinkCallback, LinkMethod, LinkStep, Namespace, NamespaceBinding,
49 NamespaceKind, Projection, ProtectionState, RepoSpec, RepoState, RequiredCheckKind,
50 RoleAssignment, RoleChange, RoleOutcome, Unlisted, Visibility,
51};
52pub use resource::{OWNER_REPO_DEPTH, Resource};
53pub use rights::{EffectiveRights, ForgeRole, Right, RoleMap, collapse_to_ladder};
54
55// Re-exported so adapters and callers name one `async_trait`.
56pub use async_trait::async_trait;