okf_validator/lib.rs
1//! # okf-validator: conformance checking and linting for OKF bundles
2//!
3//! Companion to [`okf-core`](https://docs.rs/okf-core), the pure-Rust
4//! implementation of the [Open Knowledge Format (OKF) v0.2][spec]. This crate
5//! judges bundles; okf-core models them.
6//!
7//! - [`validate`] checks conformance: [`validate_bundle`] reports true spec
8//! violations as [`Severity::Error`], and material data integrity issues,
9//! temporal checks, broken references, contract discrepancies, and script syntax
10//! errors as [`Severity::Warning`] or [`Severity::Info`].
11//! - [`lint`] is the opinionated companion: [`lint_bundle`] evaluates 12
12//! bundle formatting, structure, and authoring hygiene rules, each finding tagged with a stable rule code (`L1`..`L12`).
13//! - [`syntax`] provides in-process syntax checking for Python,
14//! JavaScript, TypeScript, Rust, SQL, JSON, YAML, and Bash.
15//!
16//! # Cargo features
17//!
18//! The four third-party language parsers are optional and on by default:
19//! `python` (`rustpython-parser`), `javascript` (`oxc_parser`, also covers
20//! TypeScript), `rust` (`syn`), and `sql` (`sqlparser`). Conformance
21//! validation and linting need none of them; only the two syntax checks do.
22//! Disable a feature and [`check_syntax`] accepts that language unchecked,
23//! exactly as it does for an unknown tag. This matters most for `python`,
24//! whose parser depends on the LGPL-3.0-only `malachite` crates: a consumer
25//! under an allow-list licence policy can take
26//! `default-features = false, features = ["sql"]` and keep everything else.
27//! JSON, YAML, and Bash checking is built in.
28//!
29//! Staleness checks depend on the wall clock, so they are opt-in via
30//! [`validate_bundle_at`] and [`lint_bundle_at`], which take the date to
31//! compare against; the plain variants are deterministic.
32//!
33//! Most users get this crate through the [`okf`](https://docs.rs/okf) crate,
34//! which re-exports it alongside okf-core and ships the `okf` CLI.
35//!
36//! ```no_run
37//! use okf_core::Bundle;
38//! use okf_validator::validate_bundle;
39//!
40//! let bundle = Bundle::load("./my_bundle")?;
41//! let report = validate_bundle(&bundle);
42//! if report.is_conformant() {
43//! println!("conformant OKF v0.2 bundle");
44//! }
45//! # Ok::<(), okf_core::BundleError>(())
46//! ```
47//!
48//! [spec]: https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md
49
50#![forbid(unsafe_code)]
51#![warn(missing_docs)]
52// Pedantic and nursery lints keep the published crate tidy; the few cases
53// where a lint is genuinely wrong for this codebase are silenced inline with a
54// justification.
55#![warn(clippy::pedantic, clippy::nursery)]
56
57pub mod lint;
58pub mod syntax;
59pub mod validate;
60
61#[doc(inline)]
62pub use lint::{lint_bundle, lint_bundle_at};
63#[doc(inline)]
64pub use syntax::{
65 FencedCodeBlock, Language, SyntaxError, check_syntax, extract_fenced_code_blocks,
66};
67#[doc(inline)]
68pub use validate::{
69 Diagnostic, ParseSeverityError, Report, Severity, validate_bundle, validate_bundle_at,
70};