an.tsouchlos/brittle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clean up architecture

Browse Source
This commit is contained in:
Andreas Tsouchlos
2026-03-25 17:53:44 +01:00
parent 17ddf9071e
commit d4872a1a04
31 changed files with 1490 additions and 1104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
brittle-core/Cargo.toml
View File

@@ -4,19 +4,15 @@ version = "0.1.0"
edition = "2024"
[dependencies]
brittle-model = { path = "../brittle-model" }
chrono = { version = "0.4", features = ["serde"] }
git2 = { version = "0.20", features = ["vendored-libgit2"] }
serde = { version = "1", features = ["derive"] }
sha2 = "0.10"
thiserror = "2"
toml = "0.8"
ureq = "2"
uuid = { version = "1", features = ["v7", "serde"] }
[[bin]]
name = "brittle-seed"
path = "src/bin/seed.rs"
[dev-dependencies]
serde_json = "1"
tempfile = "3"

286
brittle-core/src/bin/seed.rs
View File

@@ -1,286 +0,0 @@
//! Creates an example Brittle repository with realistic academic references.
//!
//! For references that have freely available PDFs (arXiv preprints and open
//! author copies), the script downloads the PDF and attaches it to the
//! reference. Downloads that fail are skipped with a warning so the seed
//! always completes even without network access.
//!
//! Usage:
//! brittle-seed [PATH]
//!
//! PATH defaults to `~/brittle-example`. The directory must not already
//! contain a git repository.
use std::io::Read;
use std::path::PathBuf;
use brittle_core::{Brittle, EntryType, FsStore, Person, ReferenceId};
fn main() {
let path = match std::env::args().nth(1) {
Some(p) => PathBuf::from(p),
None => {
let home = std::env::var("HOME").expect("HOME not set");
PathBuf::from(home).join("brittle-example")
}
};
if path.join(".git").exists() {
eprintln!("error: {} already contains a git repository", path.display());
std::process::exit(1);
}
std::fs::create_dir_all(&path).expect("could not create directory");
println!("Creating repository at {} …", path.display());
let mut b = Brittle::create(&path).expect("create repository");
// ── Libraries ─────────────────────────────────────────────────────────────
let cs = b.create_library("Computer Science", None).unwrap();
let ml = b.create_library("Machine Learning", Some(cs.id)).unwrap();
let sys = b.create_library("Systems", Some(cs.id)).unwrap();
let math = b.create_library("Mathematics", None).unwrap();
let pl = b.create_library("Programming Languages", Some(cs.id)).unwrap();
// ── References ────────────────────────────────────────────────────────────
// -- Machine Learning --
let mut r = b.create_reference("lecun1998gradient", EntryType::Article).unwrap();
r.authors = vec![
person("LeCun", "Yann"),
person("Bottou", "Léon"),
person("Bengio", "Yoshua"),
person("Haffner", "Patrick"),
];
r.fields.insert("title".into(), "Gradient-based learning applied to document recognition".into());
r.fields.insert("journal".into(), "Proceedings of the IEEE".into());
r.fields.insert("volume".into(), "86".into());
r.fields.insert("number".into(), "11".into());
r.fields.insert("pages".into(), "2278--2324".into());
r.fields.insert("year".into(), "1998".into());
let id = r.id;
b.update_reference(r).unwrap();
b.add_to_library(ml.id, id).unwrap();
attach_pdf(&mut b, id, "http://yann.lecun.com/exdb/publis/pdf/lecun-01a.pdf");
let mut r = b.create_reference("vaswani2017attention", EntryType::InProceedings).unwrap();
r.authors = vec![
person("Vaswani", "Ashish"),
person("Shazeer", "Noam"),
person("Parmar", "Niki"),
person("Uszkoreit", "Jakob"),
person("Jones", "Llion"),
person("Gomez", "Aidan N."),
person("Kaiser", "Łukasz"),
person("Polosukhin", "Illia"),
];
r.fields.insert("title".into(), "Attention Is All You Need".into());
r.fields.insert("booktitle".into(), "Advances in Neural Information Processing Systems".into());
r.fields.insert("volume".into(), "30".into());
r.fields.insert("year".into(), "2017".into());
let id = r.id;
b.update_reference(r).unwrap();
b.add_to_library(ml.id, id).unwrap();
attach_pdf(&mut b, id, "https://arxiv.org/pdf/1706.03762");
let mut r = b.create_reference("goodfellow2016deep", EntryType::Book).unwrap();
r.authors = vec![
person("Goodfellow", "Ian"),
person("Bengio", "Yoshua"),
person("Courville", "Aaron"),
];
r.fields.insert("title".into(), "Deep Learning".into());
r.fields.insert("publisher".into(), "MIT Press".into());
r.fields.insert("year".into(), "2016".into());
r.fields.insert("url".into(), "http://www.deeplearningbook.org".into());
let id = r.id;
b.update_reference(r).unwrap();
b.add_to_library(ml.id, id).unwrap();
// No freely available PDF for this book.
let mut r = b.create_reference("ho2020denoising", EntryType::InProceedings).unwrap();
r.authors = vec![
person("Ho", "Jonathan"),
person("Jain", "Ajay"),
person("Abbeel", "Pieter"),
];
r.fields.insert("title".into(), "Denoising Diffusion Probabilistic Models".into());
r.fields.insert("booktitle".into(), "Advances in Neural Information Processing Systems".into());
r.fields.insert("volume".into(), "33".into());
r.fields.insert("pages".into(), "6840--6851".into());
r.fields.insert("year".into(), "2020".into());
let id = r.id;
b.update_reference(r).unwrap();
b.add_to_library(ml.id, id).unwrap();
attach_pdf(&mut b, id, "https://arxiv.org/pdf/2006.11239");
// -- Systems --
let mut r = b.create_reference("lamport1978time", EntryType::Article).unwrap();
r.authors = vec![person("Lamport", "Leslie")];
r.fields.insert("title".into(), "Time, Clocks, and the Ordering of Events in a Distributed System".into());
r.fields.insert("journal".into(), "Communications of the ACM".into());
r.fields.insert("volume".into(), "21".into());
r.fields.insert("number".into(), "7".into());
r.fields.insert("pages".into(), "558--565".into());
r.fields.insert("year".into(), "1978".into());
let id = r.id;
b.update_reference(r).unwrap();
b.add_to_library(sys.id, id).unwrap();
attach_pdf(&mut b, id, "https://lamport.azurewebsites.net/pubs/time-clocks.pdf");
let mut r = b.create_reference("rosenblum1992lfs", EntryType::Article).unwrap();
r.authors = vec![
person("Rosenblum", "Mendel"),
person("Ousterhout", "John K."),
];
r.fields.insert("title".into(), "The Design and Implementation of a Log-Structured File System".into());
r.fields.insert("journal".into(), "ACM Transactions on Computer Systems".into());
r.fields.insert("volume".into(), "10".into());
r.fields.insert("number".into(), "1".into());
r.fields.insert("pages".into(), "26--52".into());
r.fields.insert("year".into(), "1992".into());
let id = r.id;
b.update_reference(r).unwrap();
b.add_to_library(sys.id, id).unwrap();
// Paywalled; no freely available PDF.
let mut r = b.create_reference("dean2004mapreduce", EntryType::InProceedings).unwrap();
r.authors = vec![
person("Dean", "Jeffrey"),
person("Ghemawat", "Sanjay"),
];
r.fields.insert("title".into(), "MapReduce: Simplified Data Processing on Large Clusters".into());
r.fields.insert("booktitle".into(), "OSDI".into());
r.fields.insert("pages".into(), "137--150".into());
r.fields.insert("year".into(), "2004".into());
let id = r.id;
b.update_reference(r).unwrap();
b.add_to_library(sys.id, id).unwrap();
attach_pdf(&mut b, id, "https://static.googleusercontent.com/media/research.google.com/en//archive/mapreduce-osdi04.pdf");
// -- Programming Languages --
let mut r = b.create_reference("milner1978polymorphism", EntryType::Article).unwrap();
r.authors = vec![person("Milner", "Robin")];
r.fields.insert("title".into(), "A Theory of Type Polymorphism in Programming".into());
r.fields.insert("journal".into(), "Journal of Computer and System Sciences".into());
r.fields.insert("volume".into(), "17".into());
r.fields.insert("number".into(), "3".into());
r.fields.insert("pages".into(), "348--375".into());
r.fields.insert("year".into(), "1978".into());
let id = r.id;
b.update_reference(r).unwrap();
b.add_to_library(pl.id, id).unwrap();
// Paywalled; no freely available PDF.
let mut r = b.create_reference("matsakis2014rust", EntryType::InProceedings).unwrap();
r.authors = vec![
person("Matsakis", "Nicholas D."),
person("Klock", "Felix S."),
];
r.fields.insert("title".into(), "The Rust Language".into());
r.fields.insert("booktitle".into(), "ACM SIGAda Annual Conference on High Integrity Language Technology".into());
r.fields.insert("pages".into(), "103--104".into());
r.fields.insert("year".into(), "2014".into());
let id = r.id;
b.update_reference(r).unwrap();
b.add_to_library(pl.id, id).unwrap();
// Paywalled; no freely available PDF.
// -- Mathematics --
let mut r = b.create_reference("turing1936computable", EntryType::Article).unwrap();
r.authors = vec![person("Turing", "Alan M.")];
r.fields.insert("title".into(), "On Computable Numbers, with an Application to the Entscheidungsproblem".into());
r.fields.insert("journal".into(), "Proceedings of the London Mathematical Society".into());
r.fields.insert("volume".into(), "42".into());
r.fields.insert("number".into(), "1".into());
r.fields.insert("pages".into(), "230--265".into());
r.fields.insert("year".into(), "1936".into());
let id = r.id;
b.update_reference(r).unwrap();
b.add_to_library(math.id, id).unwrap();
// No freely available PDF.
let mut r = b.create_reference("knuth1984texbook", EntryType::Book).unwrap();
r.authors = vec![person("Knuth", "Donald E.")];
r.fields.insert("title".into(), "The TeXbook".into());
r.fields.insert("publisher".into(), "Addison-Wesley".into());
r.fields.insert("year".into(), "1984".into());
r.fields.insert("series".into(), "Computers and Typesetting".into());
r.fields.insert("volume".into(), "A".into());
let id = r.id;
b.update_reference(r).unwrap();
b.add_to_library(math.id, id).unwrap();
// Copyrighted book; no freely available PDF.
// A reference in both ML and Mathematics (cross-library membership).
let mut r = b.create_reference("cybenko1989approximation", EntryType::Article).unwrap();
r.authors = vec![person("Cybenko", "George")];
r.fields.insert("title".into(), "Approximation by Superpositions of a Sigmoidal Function".into());
r.fields.insert("journal".into(), "Mathematics of Control, Signals, and Systems".into());
r.fields.insert("volume".into(), "2".into());
r.fields.insert("number".into(), "4".into());
r.fields.insert("pages".into(), "303--314".into());
r.fields.insert("year".into(), "1989".into());
let id = r.id;
b.update_reference(r).unwrap();
b.add_to_library(ml.id, id).unwrap();
b.add_to_library(math.id, id).unwrap();
// Paywalled; no freely available PDF.
println!();
println!("Done.");
println!();
println!(" Libraries : Computer Science (Machine Learning, Systems, Programming Languages), Mathematics");
println!(" References: 12 across all libraries");
println!();
println!("Open the repository in Brittle with: :open {}", path.display());
}
// ── PDF download ──────────────────────────────────────────────────────────────
/// Download the PDF at `url` and attach it to `id`. Prints progress and
/// skips silently on any error so the seed always completes.
fn attach_pdf(b: &mut Brittle<FsStore>, id: ReferenceId, url: &str) {
let label = url.rsplit('/').next().unwrap_or(url);
print!(" ↓ {label} … ");
std::io::Write::flush(&mut std::io::stdout()).ok();
match download(url) {
Err(e) => println!("skipped ({e})"),
Ok(bytes) => {
let tmp = std::env::temp_dir().join(format!("{id}.pdf"));
if let Err(e) = std::fs::write(&tmp, &bytes) {
println!("skipped (write: {e})");
return;
}
match b.attach_pdf(id, &tmp) {
Ok(_) => println!("{} KB", bytes.len() / 1024),
Err(e) => println!("skipped (attach: {e})"),
}
let _ = std::fs::remove_file(&tmp);
}
}
}
fn download(url: &str) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
let resp = ureq::get(url).call()?;
let mut buf = Vec::new();
resp.into_reader().read_to_end(&mut buf)?;
Ok(buf)
}
// ── Helpers ───────────────────────────────────────────────────────────────────
fn person(family: &str, given: &str) -> Person {
Person {
family: family.into(),
given: Some(given.into()),
prefix: None,
suffix: None,
}
}

26
brittle-core/src/lib.rs
View File

@@ -8,6 +8,7 @@ pub mod error;
pub mod model;
pub mod store;
pub use brittle_model::ReferenceSummary;
pub use error::{BibtexError, BrittleError, StoreError, ValidationError};
pub use model::{
Annotation, AnnotationId, AnnotationSet, AnnotationType, Color, EntryType, Library, LibraryId,
@@ -18,33 +19,8 @@ pub use store::{FsStore, MemoryStore, Store};
use crate::bibtex::export_references;
use crate::error::EntityType;
use chrono::Utc;
use serde::Serialize;
use std::path::{Path, PathBuf};
/// A lightweight summary of a reference, suitable for list views.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct ReferenceSummary {
pub id: ReferenceId,
pub cite_key: String,
pub entry_type: EntryType,
pub title: Option<String>,
pub authors: Vec<Person>,
pub year: Option<String>,
}
impl From<&Reference> for ReferenceSummary {
fn from(r: &Reference) -> Self {
Self {
id: r.id,
cite_key: r.cite_key.clone(),
entry_type: r.entry_type.clone(),
title: r.title().map(str::to_owned),
authors: r.authors.clone(),
year: r.year().map(str::to_owned),
}
}
}
/// The main entry point for Brittle.
///
/// Generic over [`Store`] to allow testing with [`MemoryStore`] and production

230
brittle-core/src/model/annotation.rs
View File

@@ -1,229 +1 @@
use crate::model::ids::{AnnotationId, ReferenceId};
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
/// A point in PDF coordinate space.
/// Origin is bottom-left; units are points (1/72 inch), matching ISO 32000.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct Point {
pub x: f64,
pub y: f64,
}
/// A rectangle in PDF coordinate space.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct Rect {
pub x: f64,
pub y: f64,
pub width: f64,
pub height: f64,
}
/// A quadrilateral for text markup annotations (highlight, underline, etc.).
/// Four points define one region, typically one line of text.
/// Matches the PDF spec QuadPoints representation (4 vertices per quad).
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct Quad {
pub points: [Point; 4],
}
/// RGBA color.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct Color {
pub r: u8,
pub g: u8,
pub b: u8,
pub a: u8,
}
impl Color {
pub const YELLOW: Color = Color {
r: 255,
g: 255,
b: 0,
a: 128,
};
pub const RED: Color = Color {
r: 255,
g: 0,
b: 0,
a: 128,
};
pub const GREEN: Color = Color {
r: 0,
g: 255,
b: 0,
a: 128,
};
}
/// The four text markup annotation types defined in ISO 32000.
/// All share the same QuadPoints-based geometry.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum TextMarkupType {
Highlight,
Underline,
Squiggly,
StrikeOut,
}
/// The kind of annotation and its type-specific geometry/data.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "lowercase")]
pub enum AnnotationType {
/// Text markup (highlight, underline, squiggly, strikeout).
/// Uses QuadPoints per PDF spec for precise multi-line region selection.
TextMarkup {
markup_type: TextMarkupType,
quads: Vec<Quad>,
color: Color,
/// The selected text, stored for search and export without re-reading the PDF.
selected_text: Option<String>,
},
/// Sticky note (popup comment).
Note { position: Point },
/// Inline text box.
FreeText { rect: Rect },
/// Freehand ink drawing (e.g., circling a diagram).
Ink {
/// Multiple strokes, each a sequence of connected points.
paths: Vec<Vec<Point>>,
color: Color,
/// Stroke width in points.
width: f64,
},
/// Area/image selection for extracting figures from PDFs.
Area { rect: Rect },
}
/// A single annotation on a PDF page.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Annotation {
pub id: AnnotationId,
pub reference_id: ReferenceId,
/// 0-indexed physical page number.
pub page: u32,
/// Display page label (e.g., "iv", "23") — may differ from the physical page index.
pub page_label: Option<String>,
pub annotation_type: AnnotationType,
/// Free-form text: note body, comment on a highlight, etc.
pub content: Option<String>,
pub created_at: DateTime<Utc>,
pub modified_at: DateTime<Utc>,
}
impl Annotation {
pub fn new(reference_id: ReferenceId, page: u32, annotation_type: AnnotationType) -> Self {
let now = Utc::now();
Self {
id: AnnotationId::new(),
reference_id,
page,
page_label: None,
annotation_type,
content: None,
created_at: now,
modified_at: now,
}
}
}
/// All annotations for a single reference, stored as one file.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AnnotationSet {
pub reference_id: ReferenceId,
pub annotations: Vec<Annotation>,
}
impl AnnotationSet {
pub fn new(reference_id: ReferenceId) -> Self {
Self {
reference_id,
annotations: Vec::new(),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn make_highlight() -> AnnotationType {
AnnotationType::TextMarkup {
markup_type: TextMarkupType::Highlight,
quads: vec![Quad {
points: [
Point { x: 10.0, y: 20.0 },
Point { x: 100.0, y: 20.0 },
Point { x: 10.0, y: 30.0 },
Point { x: 100.0, y: 30.0 },
],
}],
color: Color::YELLOW,
selected_text: Some("important text".into()),
}
}
#[test]
fn annotation_serde_round_trip_highlight() {
let ref_id = ReferenceId::new();
let set = AnnotationSet {
reference_id: ref_id,
annotations: vec![Annotation::new(ref_id, 3, make_highlight())],
};
let toml_str = toml::to_string(&set).expect("serialize");
let set2: AnnotationSet = toml::from_str(&toml_str).expect("deserialize");
assert_eq!(set.reference_id, set2.reference_id);
assert_eq!(set.annotations.len(), set2.annotations.len());
assert_eq!(set.annotations[0].page, set2.annotations[0].page);
}
#[test]
fn annotation_serde_round_trip_ink() {
let ref_id = ReferenceId::new();
let ink = AnnotationType::Ink {
paths: vec![vec![Point { x: 0.0, y: 0.0 }, Point { x: 10.0, y: 10.0 }]],
color: Color::RED,
width: 2.0,
};
let set = AnnotationSet {
reference_id: ref_id,
annotations: vec![Annotation::new(ref_id, 0, ink)],
};
let toml_str = toml::to_string(&set).expect("serialize");
let set2: AnnotationSet = toml::from_str(&toml_str).expect("deserialize");
assert_eq!(set, set2);
}
#[test]
fn all_markup_types_serialize() {
let ref_id = ReferenceId::new();
for markup_type in [
TextMarkupType::Highlight,
TextMarkupType::Underline,
TextMarkupType::Squiggly,
TextMarkupType::StrikeOut,
] {
let ann = Annotation::new(
ref_id,
0,
AnnotationType::TextMarkup {
markup_type,
quads: vec![],
color: Color::GREEN,
selected_text: None,
},
);
let set = AnnotationSet {
reference_id: ref_id,
annotations: vec![ann],
};
let toml_str = toml::to_string(&set).expect("serialize");
let _: AnnotationSet = toml::from_str(&toml_str).expect("deserialize");
}
}
}
pub use brittle_model::annotation::*;

68
brittle-core/src/model/ids.rs
View File

@@ -1,67 +1 @@
use serde::{Deserialize, Serialize};
use std::fmt;
use uuid::Uuid;
macro_rules! define_id {
($name:ident) => {
#[derive(
Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize,
)]
pub struct $name(pub Uuid);
impl $name {
pub fn new() -> Self {
Self(Uuid::now_v7())
}
}
impl Default for $name {
fn default() -> Self {
Self::new()
}
}
impl From<Uuid> for $name {
fn from(uuid: Uuid) -> Self {
Self(uuid)
}
}
impl fmt::Display for $name {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}", self.0)
}
}
};
}
define_id!(ReferenceId);
define_id!(LibraryId);
define_id!(AnnotationId);
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn new_generates_unique_ids() {
let a = ReferenceId::new();
let b = ReferenceId::new();
assert_ne!(a, b);
}
#[test]
fn display_is_uuid_format() {
let id = ReferenceId::new();
let s = id.to_string();
assert_eq!(s.len(), 36); // UUID hyphenated format
}
#[test]
fn serde_round_trip() {
let id = LibraryId::new();
let json = serde_json::to_string(&id).unwrap();
let id2: LibraryId = serde_json::from_str(&json).unwrap();
assert_eq!(id, id2);
}
}
pub use brittle_model::ids::*;

67
brittle-core/src/model/library.rs
View File

@@ -1,66 +1 @@
use crate::model::ids::{LibraryId, ReferenceId};
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use std::collections::BTreeSet;
/// A named collection of references. Forms a tree via `parent_id`.
///
/// References are not "owned" by a library — they exist in a flat pool.
/// A reference can appear in multiple libraries (multi-membership).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Library {
pub id: LibraryId,
pub name: String,
/// `None` means this is a root library (no parent).
pub parent_id: Option<LibraryId>,
/// The set of references that are members of this library.
/// BTreeSet for deterministic serialization order.
pub members: BTreeSet<ReferenceId>,
pub created_at: DateTime<Utc>,
pub modified_at: DateTime<Utc>,
}
impl Library {
pub fn new(name: impl Into<String>, parent_id: Option<LibraryId>) -> Self {
let now = Utc::now();
Self {
id: LibraryId::new(),
name: name.into(),
parent_id,
members: BTreeSet::new(),
created_at: now,
modified_at: now,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn library_serde_round_trip() {
let mut lib = Library::new("Machine Learning", None);
let ref_id = ReferenceId::new();
lib.members.insert(ref_id);
let toml_str = toml::to_string(&lib).expect("serialize to TOML");
let lib2: Library = toml::from_str(&toml_str).expect("deserialize from TOML");
assert_eq!(lib.id, lib2.id);
assert_eq!(lib.name, lib2.name);
assert_eq!(lib.members, lib2.members);
assert_eq!(lib.parent_id, lib2.parent_id);
}
#[test]
fn nested_library_serde_round_trip() {
let parent = Library::new("Science", None);
let child = Library::new("Physics", Some(parent.id));
let toml_str = toml::to_string(&child).expect("serialize to TOML");
let child2: Library = toml::from_str(&toml_str).expect("deserialize from TOML");
assert_eq!(child2.parent_id, Some(parent.id));
}
}
pub use brittle_model::library::*;

67
brittle-core/src/model/mod.rs
View File

@@ -11,3 +11,70 @@ pub use ids::{AnnotationId, LibraryId, ReferenceId};
pub use library::Library;
pub use reference::{EntryType, PdfAttachment, Person, Reference};
pub use snapshot::Snapshot;
/// TOML round-trip tests for model types used in on-disk storage.
///
/// These live in brittle-core (not brittle-model) because TOML is a
/// brittle-core persistence concern — brittle-model itself is TOML-agnostic.
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn reference_toml_round_trip() {
let mut r = Reference::new("doe2024", EntryType::Article);
r.authors.push(Person {
family: "Doe".into(),
given: Some("Jane".into()),
prefix: None,
suffix: None,
});
r.fields.insert("title".into(), "A Great Paper".into());
r.fields.insert("year".into(), "2024".into());
let toml_str = toml::to_string(&r).expect("serialize to TOML");
let r2: Reference = toml::from_str(&toml_str).expect("deserialize from TOML");
assert_eq!(r.id, r2.id);
assert_eq!(r.cite_key, r2.cite_key);
assert_eq!(r.authors, r2.authors);
assert_eq!(r.fields, r2.fields);
}
#[test]
fn library_toml_round_trip() {
let mut lib = Library::new("Machine Learning", None);
lib.members.insert(ReferenceId::new());
let toml_str = toml::to_string(&lib).expect("serialize to TOML");
let lib2: Library = toml::from_str(&toml_str).expect("deserialize from TOML");
assert_eq!(lib.id, lib2.id);
assert_eq!(lib.name, lib2.name);
assert_eq!(lib.members, lib2.members);
}
#[test]
fn annotation_toml_round_trip() {
let ref_id = ReferenceId::new();
let set = AnnotationSet {
reference_id: ref_id,
annotations: vec![Annotation::new(
ref_id,
3,
AnnotationType::TextMarkup {
markup_type: TextMarkupType::Highlight,
quads: vec![],
color: Color::YELLOW,
selected_text: Some("key phrase".into()),
},
)],
};
let toml_str = toml::to_string(&set).expect("serialize to TOML");
let set2: AnnotationSet = toml::from_str(&toml_str).expect("deserialize from TOML");
assert_eq!(set.reference_id, set2.reference_id);
assert_eq!(set.annotations[0].page, set2.annotations[0].page);
}
}

242
brittle-core/src/model/reference.rs
View File

@@ -1,241 +1 @@
use crate::model::ids::ReferenceId;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;
use std::fmt;
use std::path::PathBuf;
/// A person (author, editor, translator, etc.).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Person {
pub family: String,
pub given: Option<String>,
/// Name prefix: "von", "de", "van der", etc.
pub prefix: Option<String>,
/// Name suffix: "Jr.", "III", etc.
pub suffix: Option<String>,
}
impl Person {
pub fn new(family: impl Into<String>) -> Self {
Self {
family: family.into(),
given: None,
prefix: None,
suffix: None,
}
}
/// Format for display: "Given prefix Family, Suffix" — natural reading order.
pub fn display_name(&self) -> String {
let mut parts = Vec::new();
if let Some(given) = &self.given {
parts.push(given.as_str());
}
if let Some(prefix) = &self.prefix {
parts.push(prefix.as_str());
}
parts.push(self.family.as_str());
let mut name = parts.join(" ");
if let Some(suffix) = &self.suffix {
name.push_str(", ");
name.push_str(suffix);
}
name
}
/// Format as BibTeX expects: "{prefix} {family}, {suffix}, {given}".
/// Falls back gracefully when optional parts are absent.
pub fn to_bibtex(&self) -> String {
let mut family_part = String::new();
if let Some(prefix) = &self.prefix {
family_part.push_str(prefix);
family_part.push(' ');
}
family_part.push_str(&self.family);
match (&self.suffix, &self.given) {
(Some(suffix), Some(given)) => {
format!("{family_part}, {suffix}, {given}")
}
(Some(suffix), None) => format!("{family_part}, {suffix}"),
(None, Some(given)) => format!("{family_part}, {given}"),
(None, None) => family_part,
}
}
}
impl fmt::Display for Person {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}", self.display_name())
}
}
/// Standard BibTeX and common BibLaTeX entry types.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum EntryType {
Article,
Book,
Booklet,
InBook,
InCollection,
InProceedings,
Manual,
MastersThesis,
Misc,
PhdThesis,
Proceedings,
TechReport,
Unpublished,
Online,
}
impl EntryType {
/// The BibTeX entry type name as it appears in `.bib` files.
pub fn bibtex_name(&self) -> &'static str {
match self {
EntryType::Article => "article",
EntryType::Book => "book",
EntryType::Booklet => "booklet",
EntryType::InBook => "inbook",
EntryType::InCollection => "incollection",
EntryType::InProceedings => "inproceedings",
EntryType::Manual => "manual",
EntryType::MastersThesis => "mastersthesis",
EntryType::Misc => "misc",
EntryType::PhdThesis => "phdthesis",
EntryType::Proceedings => "proceedings",
EntryType::TechReport => "techreport",
EntryType::Unpublished => "unpublished",
EntryType::Online => "online",
}
}
}
/// A PDF file stored inside the Brittle repository.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PdfAttachment {
/// Path relative to the repository root (e.g., `"pdfs/550e8400-....pdf"`).
pub stored_path: PathBuf,
/// SHA-256 hex digest of the file contents for integrity verification.
pub content_hash: String,
}
/// A citable work. The core entity of Brittle.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Reference {
pub id: ReferenceId,
/// The BibTeX cite key (e.g., `"knuth1984texbook"`). User-facing and mutable.
pub cite_key: String,
pub entry_type: EntryType,
/// Authors listed in order.
pub authors: Vec<Person>,
/// Editors (for edited books, proceedings, etc.).
pub editors: Vec<Person>,
/// All other fields (title, year, journal, volume, etc.) as plain strings.
/// BTreeMap for deterministic serialization order (important for git diffs).
pub fields: BTreeMap<String, String>,
pub pdf: Option<PdfAttachment>,
pub created_at: DateTime<Utc>,
pub modified_at: DateTime<Utc>,
}
impl Reference {
pub fn new(cite_key: impl Into<String>, entry_type: EntryType) -> Self {
let now = Utc::now();
Self {
id: ReferenceId::new(),
cite_key: cite_key.into(),
entry_type,
authors: Vec::new(),
editors: Vec::new(),
fields: BTreeMap::new(),
pdf: None,
created_at: now,
modified_at: now,
}
}
/// Returns the value of the `title` field, if present.
pub fn title(&self) -> Option<&str> {
self.fields.get("title").map(String::as_str)
}
/// Returns the value of the `year` field, if present.
pub fn year(&self) -> Option<&str> {
self.fields.get("year").map(String::as_str)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn person_bibtex_full() {
let p = Person {
family: "Dijkstra".into(),
given: Some("Edsger W.".into()),
prefix: None,
suffix: None,
};
assert_eq!(p.to_bibtex(), "Dijkstra, Edsger W.");
}
#[test]
fn person_bibtex_with_prefix() {
let p = Person {
family: "Beethoven".into(),
given: Some("Ludwig".into()),
prefix: Some("van".into()),
suffix: None,
};
assert_eq!(p.to_bibtex(), "van Beethoven, Ludwig");
}
#[test]
fn person_bibtex_with_suffix() {
let p = Person {
family: "King".into(),
given: Some("Martin Luther".into()),
prefix: None,
suffix: Some("Jr.".into()),
};
assert_eq!(p.to_bibtex(), "King, Jr., Martin Luther");
}
#[test]
fn person_bibtex_family_only() {
let p = Person::new("Aristotle");
assert_eq!(p.to_bibtex(), "Aristotle");
}
#[test]
fn reference_serde_round_trip() {
let mut r = Reference::new("doe2024", EntryType::Article);
r.authors.push(Person {
family: "Doe".into(),
given: Some("Jane".into()),
prefix: None,
suffix: None,
});
r.fields.insert("title".into(), "A Great Paper".into());
r.fields.insert("year".into(), "2024".into());
let toml_str = toml::to_string(&r).expect("serialize to TOML");
let r2: Reference = toml::from_str(&toml_str).expect("deserialize from TOML");
assert_eq!(r.id, r2.id);
assert_eq!(r.cite_key, r2.cite_key);
assert_eq!(r.authors, r2.authors);
assert_eq!(r.fields, r2.fields);
}
#[test]
fn entry_type_bibtex_names() {
assert_eq!(EntryType::Article.bibtex_name(), "article");
assert_eq!(EntryType::InProceedings.bibtex_name(), "inproceedings");
assert_eq!(EntryType::PhdThesis.bibtex_name(), "phdthesis");
}
}
pub use brittle_model::reference::*;

13
brittle-core/src/model/snapshot.rs
View File

@@ -1,12 +1 @@
use chrono::{DateTime, Utc};
use serde::Serialize;
/// Metadata about a stored snapshot (git commit).
/// Not serialized to files — read directly from git history.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct Snapshot {
/// Git commit SHA (hex string).
pub id: String,
pub message: String,
pub timestamp: DateTime<Utc>,
}
pub use brittle_model::snapshot::*;