dbmd_core/
lib.rs

1//! `dbmd-core` — the reference library for **db.md**, the open database in
2//! plain files.
3//!
4//! db.md is one directory: raw evidence in `sources/`, atomic typed data in
5//! `records/`, curator-synthesized narrative in `wiki/`, and a single `DB.md`
6//! config file at the root. Records are markdown files with YAML frontmatter;
7//! relationships are wiki-links; the index is the derived, write-through
8//! `index.md` / `index.jsonl` catalog plus embedded ripgrep.
9//!
10//! This crate owns **all** toolkit logic. The `dbmd` binary (`dbmd-cli`) is a
11//! thin wrapper that parses args, calls into here, and formats output. Any
12//! Rust tool wanting to be db.md-aware can `cargo add dbmd-core` and get the
13//! full library — the same shape as ripgrep, where the `grep`/`ignore` libs do
14//! the work and `rg` is a thin CLI.
15//!
16//! # Hard invariants this crate is built to uphold
17//!
18//! - **Zero AI/LLM dependencies.** No provider SDKs, no API keys, no model
19//!   calls, no embeddings, no vectors, no ANN — anywhere, ever. The agent
20//!   driving `dbmd` is the semantic layer; `dbmd` is a deterministic tool.
21//! - **The interactive loop is O(changed), never O(store).** Loop ops
22//!   ([`graph::backlinks`], [`validate::validate_working_set`],
23//!   [`index::Index::on_write`], …) never call [`store::Store::walk`] on a
24//!   non-empty changed set. The one documented exception is
25//!   [`validate::validate_working_set`], which falls back to a full sweep only
26//!   when handed an empty changed set (the vacuous-pass guard). Whole-store
27//!   walks otherwise belong only to SWEEP ops ([`validate::validate_all`],
28//!   [`index::Index::rebuild_all`], [`stats`]).
29//! - **Wiki-links are full store-relative paths.** A short-form wiki-link is a
30//!   validation error ([`validate`] code `WIKI_LINK_SHORT_FORM`).
31//! - **Embedded ripgrep.** Free-text body search uses the `grep` + `ignore`
32//!   crates in-process; the toolkit never bundles or shells out to `rg`.
33//!   Structured loop reads ([`graph::backlinks`], [`query::Query`]) ride the
34//!   `index.jsonl` sidecars instead, never a frontmatter tree scan.
35
36pub mod assets;
37pub mod extract;
38pub mod fsx;
39pub mod graph;
40pub mod index;
41pub mod log;
42pub mod parser;
43pub mod query;
44pub mod render;
45pub mod stats;
46pub mod store;
47pub mod summary;
48pub mod time;
49pub mod validate;
50
51// ── Shared public types, re-exported at the crate root ──────────────────────
52//
53// These are the locked interface every other crate and module builds against.
54
55pub use assets::{AssetRecord, Declaration, ScanReport, StatusReport, VerifyReport};
56pub use extract::{ExtractError, Extracted, Format, MetaValue};
57pub use fsx::{write_atomic, write_atomic_new};
58pub use graph::ContextSlice;
59pub use index::{Index, IndexLevel, IndexRecord};
60pub use log::{Log, LogEntry, LogKind};
61pub use parser::{
62    Config, FieldSpec, Frontmatter, MarkdownLink, ParseError, Schema, Section, Shape, WikiLink,
63};
64pub use query::Query;
65pub use render::{Outline, Tree};
66pub use store::{infer_type_from_path, layer_for_type, Layer, NotAStore, Store, StoreError};
67pub use time::now;
68pub use validate::{Issue, Severity};
69
70/// Crate-wide result alias over [`Error`].
71pub type Result<T> = std::result::Result<T, Error>;
72
73/// Top-level error for `dbmd-core` operations.
74///
75/// Module-specific errors ([`ParseError`], [`StoreError`], [`NotAStore`])
76/// convert into this so a CLI command can bubble a single error type while
77/// preserving the structured variant for `--json` rendering.
78#[derive(Debug, thiserror::Error)]
79pub enum Error {
80    /// The path is not a db.md store (no `DB.md` at the root). Surfaced as the
81    /// machine-parseable code `NOT_A_STORE` with a non-zero exit.
82    #[error(transparent)]
83    NotAStore(#[from] NotAStore),
84
85    /// A store-level operation failed (walk, locate, shard, sidecar read).
86    #[error(transparent)]
87    Store(#[from] StoreError),
88
89    /// A markdown / frontmatter / `DB.md` parse failed.
90    #[error(transparent)]
91    Parse(#[from] ParseError),
92
93    /// A write was refused by a `DB.md ## Policies` rule (e.g. a frozen page).
94    /// Carries the structured validation code so the CLI can emit it verbatim.
95    #[error("write refused by policy ({code}): {message}")]
96    Policy {
97        /// The structured issue code, e.g. `"POLICY_FROZEN_PAGE"`.
98        code: &'static str,
99        /// Human-readable explanation.
100        message: String,
101    },
102
103    /// An underlying I/O failure.
104    #[error(transparent)]
105    Io(#[from] std::io::Error),
106}
dbmd_core/lib.rs

dbmd_core/
lib.rs
