Crate mant_engine

Expand description

§mant-engine

mant-engine is ManT’s document execution layer. It resolves local documents through mant-sources, lowers every source into the semantic center in mant-ir, builds in-memory and versioned protocol projections, and produces deterministic output without owning a terminal or command-line process.

§What this crate provides

Registered Markdown lookup through the read-only mant-sources boundary.
A conservative, source-positioned Markdown parser with explicit loss diagnostics and optional embedded tldr content.
Bounded native manual loading, explicit leaf-file symlink support, root-constrained .so alias resolution, and man(7)/mdoc(7) lowering on every supported platform.
Semantic outlines containing addressable sections and role-aware entries.
Excerpt selection and literal or regular-expression search with generated Markdown coordinates.
Markdown, text, man-style text, and JSON renderers over one normalized IR.
Installed-client and private tldr cache discovery. Explicit subprocess-backed updates are available only with the opt-in tldr-update feature.

Process argument parsing, MCP transport, and interactive presentation remain outside this crate.

The default feature set is read-only with respect to tldr data. The native mant composition root enables tldr-update; library consumers, renderers, and MCP-oriented embeddings do not receive subprocess update authority unless they request it explicitly.

§Execution pipeline

logical selector / physical input
              │
              v
DocumentResolver ──> Markdown parser or libmandoc lowering
              │
              v
      mant_ir::ResolvedContent
         ├─> outline / excerpt / search projections
         ├─> Markdown / text / man-style renderers
         └─> versioned mant-protocol responses

Need	Preferred API
Reuse one stable discovery snapshot	`DocumentResolver`
Resolve a complete typed request	`resolve_query_with_policy`
Resolve and project its requested view	`execute_query`
Parse in-memory Markdown without discovery	`parse_markdown` or `query_markdown_text`
Parse in-memory roff without discovery	`parse_manual_bytes` or `query_roff_bytes`
Build a focused result from existing content	`build_outline_with_detail`, `select_excerpt`, `search_query`
Produce human or JSON output	The `render_*` functions

§Basic use

The in-memory Markdown path is deterministic and works on every supported platform:

use mant_protocol::OutlineDetail;
use mant_engine::{
    build_outline_with_detail, query_markdown_text, render_outline_text,
};

let query = query_markdown_text(
    "# Demo\n\n## Options\n\n- `--verbose`: Show more detail.\n",
    Some("demo.md".to_owned()),
)?;
let outline = build_outline_with_detail(&query, OutlineDetail::Entries)?;

println!("{}", render_outline_text(&outline));

Use resolve_query or resolve_query_with_policy when a caller needs the full document bundle. Use execute_query to validate, resolve, and materialize the request’s view through one engine boundary. Use parse_markdown when the caller needs the parsed document and tldr preface without query composition. DocumentResolver can be reused when several operations must share one lazy filesystem snapshot; constructing a new resolver refreshes discovery.

Named resolution treats the full document and command quick reference as two orthogonal facets. A manual section selects an exact native full document; it does not by itself disable a compatible section 1 or 8 tldr attachment. QueryPolicy::ManualOnly excludes that facet, while TldrOnly requests it without requiring a full document. Dotted names are never split heuristically.

The engine returns mant_ir::ResolvedContent to direct semantic consumers and creates mant-protocol projections for every structured host or process boundary. A projection can stay in memory for a TUI callback or be serialized for CLI JSON and compact MCP presentation. Serializing the IR directly is not a supported substitute for those versioned DTOs.

§Platform behavior

Platform	Markdown engine	Native man/mdoc engine
Linux with glibc	Yes	Bundled `libmandoc-rs`
macOS	Yes	Bundled `libmandoc-rs`
Windows	Yes	Bundled `libmandoc-rs`

Every supported target compiles libmandoc-rs. Windows uses its memory-only C transport while Rust owns file I/O, decompression, paths, and .so redirects. Native root discovery is also Rust-owned: Linux reads man-db mappings or mandoc man.conf, macOS reads its PATH, active developer selection, and MANPATH/MANCONFIG configuration, and Windows optionally reads ManT’s own man.conf, all without spawning a host manual utility.

§Layering

mant-engine returns an owned mant_ir::ResolvedContent for direct semantic use and owned mant-protocol values at versioned integration boundaries. It does not expose libmandoc C structures. Applications that only need raw roff syntax should use libmandoc-rs directly. Applications that need the complete command or reader should install mant.

Architecture and source-resolution details are documented in the ManT native-engine reference.

§License

Apache-2.0. Native builds also contain the separately attributed vendored mandoc sources supplied by libmandoc-rs.

Structs§

AvailableDocument: One document discoverable by name through the ordinary query boundary.
DocumentResolver: One explicit local document-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.
ManualRequest: One validated manual lookup independent from CLI token syntax.
MarkdownOptions: Markdown serialization controls that do not alter the query IR.
ParsedMarkdown: Complete result of parsing one ManT-flavoured Markdown input.
ResolvedContent: One materialized document query before any versioned process projection.
SelectorCandidate: One stable qualification offered when a semantic alias is ambiguous.
TldrPageLocation: Source identity attached to a parsed tldr page.

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.
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.
MarkdownParseError: Invalid structure in ManT’s optional top-level Markdown extension.
ProjectionError: Failure to derive an addressable view from a complete query.
QueryError: A query cannot produce either authoritative manual content or a quick reference.
QueryExecutionError: A valid request could not be loaded or projected.
QueryPolicy: Closed content-resolution policy kept outside the serialized request contract.
QueryViewResult: Materialized result of the view carried by a QueryRequest.
ScopeQueryError: Invalid scope configuration or failure to resolve any initial document.
SearchError: Invalid search input or matcher construction.
SearchTextRole: Semantic roles in the grep-like search presentation.
TldrCacheError: Offline cache discovery or page-read failure.
TldrDirectiveError: Invalid structure in a document-owned tldr directive.
TldrParseError: A tldr page lacks the minimum structure required by the contract.
TldrUpdateError: Failure to refresh an installed client or ManT’s private checkout.

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§

build_outline: Build a block-free, addressable outline for one complete query.
build_outline_with_detail: Build an outline with optional semantic definition entries.
discover_documents: Load and query the current local document catalog.
discover_manual_roots: Discover effective manual hierarchy roots for the current host.
execute_query: Load and materialize the view encoded in one native request.
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.
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.
locate_manual_source_in: Locate a manual in an explicit immutable index.
lower_mandoc_document: Convert a completed low-level parse into the stable document contract.
native_api_version: Reports the native contract version through the engine layer.
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_markdown: Split ManT’s optional leading tldr preface from the Markdown document.
parse_tldr_command: Parse the tldr placeholder extension and choose the long option variant.
parse_tldr_page: Parse one tldr Markdown page without performing any I/O.
project_query_view: Materialize one view from an already loaded query.
query_available_documents: Filter the unified local catalog using one shared CLI, TUI, and MCP policy.
query_markdown_text: Parse in-memory Markdown for the direct mant - command.
query_roff_bytes: Parse one bounded roff stream without consulting MANPATH or following .so.
read_cached_tldr_page: Read one cached tldr page using current host conventions; never updates it.
render_excerpt_json: Serialize selected query nodes in compact or human-readable form.
render_excerpt_markdown: Render selected query nodes with their outline context.
render_excerpt_markdown_with_options: Render selected nodes using explicit presentation-only options.
render_excerpt_text: Render selected query nodes as unstyled text with outline context.
render_markdown: Render a complete query as clean Markdown without a trailing newline.
render_markdown_with_options: Render a complete query using explicit presentation-only options.
render_outline_json: Serialize a complete query outline in compact or human-readable form.
render_outline_markdown: Render a complete query outline as a nested CommonMark list.
render_outline_text: Render a complete query outline as a copyable Unicode tree.
render_query_json: Serialize a query contract in compact or human-readable form.
render_query_man: Render the manual as man(1)-faithful plain text.
render_query_text: Render a complete query without Markdown or terminal escape sequences.
render_search_json: Serialize structure-aware search results in compact or human-readable form.
render_search_markdown: Render a readable Markdown report whose coordinates target the full page.
render_search_text: Render grep-like results with stable Markdown coordinates and node paths.
render_search_text_with: Render grep-like search text through a semantic span decorator.
render_update_json: Serialize the explicit tldr update result for a process boundary.
resolve_query: Query the local man database and optional offline tldr caches.
resolve_query_with_policy: Query with an explicit input-resolution policy.
search_query: Search one complete query and report coordinates in its canonical Markdown.
select_excerpt: Select tldr, document-root content, or complete section subtrees by path or ID.
select_explanation: Select exactly one semantic entry by stable path, ID, or alias.
update_tldr_cache: Refresh tldr through an installed client or ManT’s private Git checkout.
validate_query_request: Validate all request and policy invariants before local I/O.
validate_scope_query_request: Validate the closed scope-query contract before document I/O.
validate_search_query: Validate search limits and compile its matcher without loading a manual.