Module api 

The supported, semver-covered library API. See the module docs. The supported library API.

Why this module exists

GH-240: forjar exports seven top-level modules and roughly 1,844 pub items across 195 pub modules, with nothing distinguishing the supported API from an implementation detail that happens to be reachable. Not one item was marked doc(hidden). The CLI implementation is public. In that state forjar cannot make a semver promise it is able to keep: any internal rename is a breaking change for somebody, and nobody — including us — can say which ones.

GH-245 is the constructive half: a real consumer (rmedia, building course assets against paiml/catalogue) wants forjar’s build-staleness logic inline in a Rust pipeline rather than shelled out to the CLI and re-parsed. They named the exact surface they need, compiled it against this tree, and asked only that we say it is supported so they need not pin =1.13.2 and diff every bump by hand.

This module is that promise, and it is deliberately small.

The promise

Everything re-exported here follows semver. A breaking change to any of these items requires a major version bump and a changelog entry.

Nothing else does. The rest of the crate is reachable, documented, and useful — and it may be renamed, moved or removed in a patch release. If you depend on an item that is not re-exported here, you are depending on an internal, and that is fine as long as you know it. Pin an exact version.

This is a narrow promise on purpose. A promise over 1,844 items would be one we break by accident within a release, which is worse than no promise at all because it reads as a guarantee.

Deliberately absent

crate::tripwire::hasher::composite_hash is not here. It is now injective (GH-235), but the fix changed every digest it produces, so it has no stability history yet. hash_inputs and hash_outputs_in funnel through it, which is why they are documented below as content-identity signals whose values are not stable across major versions — their comparison semantics are.

Example

Deciding whether a build artifact needs regenerating:

use forjar::api::{hash_file, probe_resource, staleness_reason, Resource};
use std::path::Path;

let content_id = hash_file(Path::new("lesson.srt"))?;
println!("srt identity: {content_id}");

let resource = Resource::default();
if let Some(probe) = probe_resource(&resource) {
    // `None` recorded hash deliberately means "re-run once to establish a
    // baseline", not "nothing to compare, therefore fresh".
    match staleness_reason(&probe, None, None) {
        Some(why) => println!("rebuild: {why}"),
        None => println!("fresh"),
    }
}

Re-exports

pub use crate::tripwire::hasher::hash_file;

pub use crate::core::task::probe::probe_all;

pub use crate::core::task::probe::probe_resource;

pub use crate::core::task::probe::staleness_reason;

pub use crate::core::task::probe::IoDigest;

pub use crate::core::task::hash_inputs;

pub use crate::core::task::hash_outputs_in;

pub use crate::core::planner::propagation::propagate_changes;

pub use crate::core::types::PlanAction;

pub use crate::core::types::PlannedChange;

pub use crate::core::types::Resource;