Module documents 

The document read: one file from a session’s tree, bounded, as bytes with a kind.

Resolution is against the session’s own working directory, and nothing outside that tree reads unless it sits under one of the project’s configured document roots - the check is on the canonicalized path, so a .. walk, an absolute path and a symlink pointing out are all refused the same way, and a spell the filesystem will not resolve is refused rather than read through its lexical collapse. The read is bounded by a ceiling and detects the kind by extension. Every refusal is a sentence naming its reason, because the reason is what a viewer draws and what a hand-off returns.

Re-exports

use std::fs::File; 🔒

use std::io::Read as _; 🔒

use std::path::Path; 🔒

use std::path::PathBuf; 🔒

use forge_primitives::document::DocumentKind; 🔒

use forge_primitives::document::DocumentRead; 🔒

Enums

DocumentRefusal

Why a document could not be read. Every arm is a sentence a viewer draws and a hand-off returns, so the reason travels with the refusal.

Landed 🔒

What a requested path resolved to under root.

Constants

TEXT_EXTENSIONS 🔒

The extensions whose files the hand-off can carry a review on.

Functions

kind_of 🔒

The kind by extension, lowercased; an extension the list does not know is kept as itself.

lexical 🔒

path with . dropped and .. popped, filesystem untouched. Popping past the root is a no-op, as it is for the OS.

mib 🔒

A byte count as a refusal writes it: whole MiB bare, otherwise one decimal. Tenths in integer space, so no float rounding enters a sentence a reader acts on.

read

Read one document out of cwd’s tree, or under one of document_roots.

resolve 🔒

Where path lands under root. A missing file has no canonical path, so its PARENT is canonicalized instead - what keeps the prefix check honest for a path whose directory is a symlink out. A path that canonicalizes neither way and needs no rewriting is Walked as the spelled path itself; one the collapse rewrites is Collapsed, so a .. climbing past the root is still an escape when the chain it climbs through is not on disk, and a spell that collapses onto a symlink out is never read through the rewrite.

reviewable_kind 🔒

Whether a kind can carry a review at all: markdown, text and the code kinds draw as comment targets (the hand-off’s comments ride a document read), and a PDF or an unrecognised kind opens read-only.

under_any_root 🔒

Whether resolved sits under one of the document roots. The comparison is by path component - Path::starts_with - so MadnessX is not under a Madness root.