okf 0.1.0-alpha.1

//! # okf — the Open Knowledge Format, in pure Rust
//!
//! A dependency-free implementation of the [Open Knowledge Format (OKF)
//! v0.1][spec], Google's open, human- and agent-friendly format for
//! representing knowledge as a directory of markdown files with YAML
//! frontmatter.
//!
//! OKF is intentionally minimal — "if you can `cat` a file, you can read OKF;
//! if you can `git clone` a repo, you can ship it" — so this crate implements
//! it with the standard library alone: its own [YAML-subset parser](yaml), a
//! markdown [link scanner](links), a directory walker, and (in the binary) CLI
//! argument parsing. There are **no third-party dependencies**.
//!
//! ## Model
//!
//! - A [`Bundle`] is a directory tree of markdown files (§3).
//! - A [`Concept`] is one markdown [`Document`] = YAML [`Frontmatter`] + body
//!   (§4).
//! - A [`ConceptId`] is a concept's path within the bundle, minus `.md` (§2).
//! - Concepts relate via markdown [`links`] (§5); the bundle exposes the
//!   resulting graph and backlinks.
//! - `index.md` directory listings (§6) are generated by [`index`].
//! - `log.md` histories (§7) are parsed by [`log`].
//! - [`validate_bundle`] checks §9 conformance.
//!
//! ## Example
//!
//! ```no_run
//! use okf::{Bundle, validate_bundle};
//!
//! let bundle = Bundle::load("./my_bundle")?;
//! println!("{} concepts", bundle.len());
//!
//! let report = validate_bundle(&bundle);
//! if report.is_conformant() {
//!     println!("conformant OKF v0.1 bundle");
//! }
//! # Ok::<(), okf::BundleError>(())
//! ```
//!
//! Parsing a single document:
//!
//! ```
//! use okf::Document;
//!
//! let doc = Document::parse("---\ntype: Metric\ntitle: DAU\n---\n\n# Body\n").unwrap();
//! assert_eq!(doc.frontmatter.type_().as_deref(), Some("Metric"));
//! assert!(doc.validate_conformance().is_ok());
//! ```
//!
//! [spec]: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md

#![forbid(unsafe_code)]
#![warn(missing_docs)]

pub mod bundle;
pub mod concept_id;
pub mod document;
pub mod error;
pub mod frontmatter;
pub mod index;
pub mod links;
pub mod log;
pub mod validate;
pub mod yaml;

/// The OKF specification version this crate implements.
pub const OKF_VERSION: &str = "0.1";

#[doc(inline)]
pub use bundle::{Bundle, Concept, ResolvedLink, RESERVED_FILENAMES};
#[doc(inline)]
pub use concept_id::{ConceptId, ConceptIdError};
#[doc(inline)]
pub use document::Document;
#[doc(inline)]
pub use error::{BundleError, DocumentError};
#[doc(inline)]
pub use frontmatter::{Frontmatter, REQUIRED_FRONTMATTER_KEYS};
#[doc(inline)]
pub use links::{Citation, Link, LinkKind};
#[doc(inline)]
pub use log::Log;
#[doc(inline)]
pub use validate::{validate_bundle, Diagnostic, Report, Severity};
#[doc(inline)]
pub use yaml::{Mapping, Value};