Crate mant_loader

Expand description

§mant-loader

Read-only local document discovery and bounded acquisition for ManT. The loader resolves logical document names, explicitly supplied files and typed linked document scopes into owned mant-ir content. It uses mant-codec for decoding and mant-sources for installed Markdown registration; it does not execute semantic queries, render reports or update sources.

§Features

The default feature set supports Markdown and installed tldr caches without libmandoc or a C compiler. Enable roff to load native manuals, including bounded gzip/zstd decompression and indexed .so redirects. Manual catalog discovery itself does not require a parser. A missing native capability is not permission to invoke a host formatter, download content or run an updater.

§Loading and ownership

DocumentLoader captures the host manual roots and lazily builds registered Markdown, native-manual and unified-catalog snapshots. Reuse the same loader when discovery and loading must share precedence; construct another to refresh local discovery. Snapshot reuse does not freeze external file contents or make the filesystem transactional.

For an on-demand host, prepare PreparedCatalogQuery before constructing the loader. It validates filters and compiles the matcher without discovery; DocumentLoader::discover_prepared then reuses that matcher and the loader’s snapshot. Applying a prepared query to an already materialized catalog also performs no IO. Neither preparation nor reuse refreshes the host environment.

LoadSpec borrows an explicit logical selector or input path. It carries no serialized query schema, search expression, output format or query view. Loading errors are separate from the application’s view-validation errors. Only the composition layer accepts a complete request and joins loading with semantic query execution.

use mant_loader::{DocumentLoader, LoadSpec, LoadPolicy};
use mant_protocol::InputFormat;

let loader = DocumentLoader::from_system();
let content = loader.load(
    LoadSpec::File { path: "notes.md", format: InputFormat::Markdown },
    LoadPolicy::Combined,
)?;
assert!(content.document.is_some());

§Boundaries

Registered documents and native manuals retain deterministic source priority, exact logical identities and explicit ambiguity. A failed logical selector never becomes a physical path.
Direct inputs are separately authorized by their caller. Source-byte and decoded-byte limits are enforced while reading, not inferred from file size.
Linked-document loading is bounded, breadth-first and source ordered. A single admission operation commits content, graph positions, traversal work and byte accounting together; failed candidates do not consume a document slot or leave half a graph node.
Negative resolution caching is request-local and qualified by policy, source and manual section. A frontier is a coverage boundary, not proof that a document does not exist.
Tldr cache discovery may inspect executable availability but never starts a program. Cache updates and host process execution belong to the application.

The source, configuration and metadata safety contracts are documented in the architecture and sources guide. ManT-authored code is Apache-2.0; optional native parsing remains in the separately licensed and attributed libmandoc-rs package.

Structs§

AvailableDocument: One document discoverable by name through the ordinary query boundary.
DocumentLoader: One explicit local document-environment snapshot.
ExecutableLookup: Read-only executable lookup against a caller-owned environment snapshot.
LoadedDocumentScope: A logical scope together with the loaded documents in matching order.
ManualIndex: Immutable index shared by discovery and exact manual lookup.
ManualPage: One effective local manual page after path and locale precedence.
ManualPathDiagnostic: One rejected entry in the host manual-path configuration.
ManualRequest: One validated manual lookup independent from CLI token syntax.
ManualRootDiscovery: Effective manual roots plus non-fatal host-configuration findings.
PreparedCatalogQuery: Validated filters and one compiled matcher, prepared without source discovery.
ResolvedContent: One materialized document query before any versioned process projection.

Enums§

AvailableDocumentKind: Source family used to resolve one available document.
AvailableDocumentOrigin: Precedence class and storage family for one available document.
CatalogError: Invalid document-catalog filter or regular expression.
HostPlatform: Native host families supported by ManT distributions.
LoadError: Invalid loading input or failure to acquire readable local content.
LoadPolicy: Closed content-resolution policy kept outside the serialized request contract.
LoadSpec: Borrowed loading input without a protocol schema or a query view.
LocateError: Expected source-discovery failures suitable for a user-facing CLI error.
ManualError: Failure produced by ManT’s source policy or by the underlying roff parser.
ManualErrorKind: Stable category for a native manual failure.
ManualLoadError: Native-manual resolution or lowering failed after candidate selection.
ScopeLoadError: Invalid loading scope or failure to acquire any initial document.
TldrCacheError: Offline cache discovery or page-read failure.

Constants§

MAX_MANUAL_BYTES: Upper bound on both the stored and decoded form of one manual source chain.
MAX_MARKDOWN_BYTES: Upper bound on a single Markdown source, shared by every input path.

Functions§

discover_documents: Load and query the current local document catalog.
discover_manual_roots: Discover effective manual hierarchy roots for the current host.
find_host_executable: Locate one directly runnable program using the current host’s PATH and native executable-suffix rules without spawning it.
get_system_tldr_cache_dirs: Return known installed-client cache roots in priority order.
get_tldr_cache_dir: Resolve the ManT-owned fallback checkout for an explicit environment.
get_tldr_languages: Resolve locale candidates, retaining first occurrence priority.
get_tldr_platforms: Resolve host, common, then cross-platform fallback page directories.
get_tldr_read_cache_dirs: Select installed-client caches followed by ManT’s private fallback.
inspect_manual_roots: Inspect effective native-manual roots without mutating host state.
is_command_manual_section: Return whether a manual section belongs to a command-page family.
is_manual_section: Return whether a value is a conventional native manual section.
list_available_documents: List every registered document candidate and locally indexed manual page.
load_markdown_text: Parse in-memory Markdown for the direct mant - command.
load_roff_bytes: Parse one bounded roff stream without consulting MANPATH or following .so.
locate_manual_source_in: Locate a manual in an explicit immutable index.
normalize_tldr_topic: Convert a multi-word query to the tldr filename convention.
parenthesized_manual_reference: Split the name(section) spelling accepted by manual readers.
parse_manual_bytes: Parse one already bounded, uncompressed standalone roff input.
parse_manual_page: Parse an indexed manual, resolving .so redirects against its discovered manual hierarchy without falling back to the process working directory.
parse_manual_source: Parse and normalize one standalone man or mdoc source file.
parse_manual_source_with_report: Parse through the production file pipeline, retaining its native witness.
query_available_documents: Filter the unified local catalog using one shared CLI, TUI, and MCP policy.
read_cached_tldr_page: Read one cached tldr page using current host conventions; never updates it.
validate_document_scope: Validate source selection and traversal bounds without inspecting a query view.
validate_load_spec: Validate source-selection constraints before any host access.