prov_graph/
lib.rs

1//! # prov-graph
2//!
3//! The read core of a [prov](https://docs.rs/prov) workspace: plaintext
4//! documents, the links declared in their own embedded metadata, and the
5//! traversal over them.
6//!
7//! ## What this crate is for
8//!
9//! A prov workspace describes itself. Follow the links in a document's
10//! frontmatter and body and the whole structure unfolds — no index to trust
11//! instead of the documents, no sidecar folder that has to be kept in step.
12//! This crate is that unfolding, and *only* that.
13//!
14//! Everything here reads. The filesystem port it asks for
15//! ([`fs::ReadStorage`]) has no method that writes a byte; the id index it asks
16//! for ([`index::IdIndex`]) has no method that changes a registration. Nor is
17//! the vocabulary for writing merely unused — it is *absent*, declared a layer
18//! up in `prov-store` instead. So a consumer that must not modify a workspace —
19//! a language server, a static renderer, a browser viewer — can depend on this
20//! crate and be *unable* to, rather than merely intending not to. That is the
21//! whole reason the split exists, and it is why the write halves are not here
22//! behind a feature flag someone could leave switched on.
23//!
24//! The write surface is `prov-store`: `Storage`, the metadata editor, and the
25//! `IndexStore` registries. The verbs are `prov`: creating, renaming, deleting,
26//! attaching, the change/journal machinery that makes a mutation crash-atomic,
27//! the version history, the config layer, the validation and repair passes.
28//! `prov` owns one [`Graph`] and forwards every read to it, so the two are the
29//! same traversal — not a reimplementation that can drift.
30//!
31//! `prov-views` is what that promise looks like taken up: a whole view engine —
32//! parse a declared view, resolve its scope by walking the spanning relation,
33//! group the documents it reaches — built on this crate and nothing else, and
34//! therefore unable to modify a byte of what it reads.
35//!
36//! ## The shape of it
37//!
38//! - [`Document`] — a plaintext file split into its embedded metadata block and
39//!   its body.
40//! - [`relation::RelationSet`] — which metadata fields are links. Exactly one
41//!   may be **spanning**: the single-parent tree that gives a workspace its
42//!   discovery spine. Every other relation may be many-to-many, so the tree is a
43//!   backbone, never a ceiling.
44//! - [`Graph`] — a root, a [`fs::ReadStorage`], an [`index::IdIndex`], and the
45//!   [`graph::ReadSettings`] that say how links are spelled. Its two walks are
46//!   the [`census`](Graph::census) (every forward link, flat, each tagged with
47//!   where it is written and how it resolves) and the [`tree`](Graph::tree)
48//!   (the spanning relation only, as a materialized outline).
49//!
50//! The census is ground truth. Reachability, the backlinks map, and prov's own
51//! validation findings are all views over it, and any stored index heals
52//! *toward* it, never the reverse.
53
54// At least one embedded-metadata format backend must be compiled in, otherwise
55// nothing here can parse a document at all. The format features (`yaml`,
56// `json`, `toml`, `fig-lang`) forward to the matching `fig` parser.
57#[cfg(not(any(
58    feature = "yaml",
59    feature = "json",
60    feature = "toml",
61    feature = "fig-lang"
62)))]
63compile_error!(
64    "prov-graph needs at least one metadata-format feature enabled: \
65     `yaml` (the default), `json`, `toml`, or `fig-lang`. \
66     You have disabled the default feature without selecting a replacement."
67);
68
69pub mod content;
70pub mod document;
71pub mod error;
72pub mod exec;
73pub mod fs;
74pub mod graph;
75pub mod identity;
76pub mod index;
77pub mod link;
78pub mod manifest;
79pub mod memo;
80pub mod meta;
81pub mod peer;
82pub mod relation;
83pub mod title;
84
85pub use content::{ContentFormat, code_spans, render_html};
86pub use document::{
87    Document, EmbedStyle, EmbedType, MetaCarrier, embed_carrier, embed_style_of, is_opaque_payload,
88    require_whole_file,
89};
90pub use error::{Error, Result};
91pub use exec::block_on;
92pub use fig::ExtKind;
93pub use fig::Format;
94pub use fs::{DirEntry, FileType, Metadata, ReadStorage, StdFs};
95pub use graph::{
96    Backlink, CensusEntry, Graph, LinkSite, Node, NodeKind, ReadSettings, Resolution,
97    StructuralFact, Target, TreeOptions, Walk, reachable_set,
98};
99pub use identity::{Id, IdStorage};
100pub use index::{Collision, IdIndex, NoIndex};
101pub use link::{
102    Addressing, BodyLink, Link, LinkStyle, Notation, PathStyle, ReferenceStyle, Wikilink, Wrapper,
103    escapes_root, format_link, is_valid_workspace_id, path_to_title,
104};
105pub use manifest::{Manifest, ManifestEntry, manifest_sibling};
106pub use memo::ReadScope;
107pub use meta::{Mapping, Value};
108pub use peer::{NoPeers, PeerLocation, PeerLookup, PeerResolver, Unconfirmed};
109pub use relation::{Cardinality, Edge, Relation, RelationSet};
110pub use title::{TitleIndex, TitleMatch};
prov_graph/lib.rs

prov_graph/
lib.rs
