Module map

Fledge is one flat package, latexprep, of about two hundred modules. This page assigns every module to exactly one layer and states what it is responsible for. Look here before adding a module, to decide where it belongs and what it may import.

presentation     the command line and every output format
     |
orchestration    the job workflow: tasks, builds, staging, verification, publication
     |
checks           checks, transformations and policies
     |
adapters         tool execution, PDF tools, builds, HTTP, project import and archives
     |
domain           findings, report, rules, options, readers and helpers

A module imports from its own layer and from the layers below it, never from a layer above. Only the presentation layer imports click or rich. The import graph has no cycles. These rules are checked by tests/test_module_boundaries.py, which reads the assignment from tests/module_layers.py and fails when a module is missing from it, listed twice, imports upward, or disagrees with the tables below. Edit the mapping and this page together; a new module needs one line in each.

Module docstrings state each responsibility in more detail. The development notes describe how the modules work together.

Domain and support

The vocabulary and the pure logic everything else shares: findings, the report, errors, the catalogue of check codes and its data-only *_rules.py modules, settings choices and option schemas, the bounded TeX and BibTeX readers, the literal source graph, text, path and file helpers, and the cancellation and resource-budget primitives. None starts a process or opens a network connection, and each imports only other modules of this layer. (79 modules)

Module	Responsibility
__init__	Package marker: the version number and the silent library logger
analysed_source	One project’s literal source analysis, built once and shared by the checks that read it
bibliography_check_rules	Data-only catalogue entries for configurable offline bibliography checks
bibliography_options	Settings of the offline bibliography checks, validated when they are constructed
bibliography_transform_rules	Data-only catalogue entries for explicit, atomic bibliography transformations
bibtex_layout	Where the pieces of a parsed .bib entry sit in its text, and edits that cut them out
bibtex_names	Family names in a BibTeX author field, read with BibTeX’s own name syntax
bibtex_syntax	Bounded BibTeX syntax reader shared by bibliography checks, transformations and lookups
build_check_rules	Data-only catalogue for checks over build and recorder evidence
cancellation	Cooperative cancellation helpers: owned workers that finish before a cancellation propagates
check_selection	Validated public check selectors, independent of checker configuration
citation_graph	Literal citations, bibliography declarations and styles of one selected manuscript
comment_markers	Words that mark unfinished work or a private note in manuscript text and comments
core_rules	Data-only catalogue for the original source, packaging, build, PDF and comparison checks
defects	Telling expected failures from defects, and describing a defect without any paths
documentation_links	Where the hosted documentation lives, for messages that send a researcher to it
errors	Expected failures that carry an actionable message, and the kinds callers tell apart
execution_records	Typed records of the Report.execution entries that jobs write and renderers show
expanded_document	The selected literal source graph read as one expanded document
file_safety	Bounded, link-safe file helpers shared by tool execution, builds and packaging
file_scan	Bounded scans of supplied project files: an inventory and a byte budget for reading them
finding_text	Wording and bookkeeping shared by the checks that build findings
finding_weight	How hard a check hits when it does not pass: one mapping from outcome to severity
findings	The Finding: one check’s result, and the constructors for findings that no check produces
limits	Unit constants and the limits that more than one module shares
literal_text	Literal TeX text without expansion: shared command tables and plain-text reading
loaded_options_rules	Data-only catalogue for actual post-document kernel option evidence
manuscript_check_options	The [manuscript_checks] settings: which opt-in manuscript policies run
manuscript_check_rules	Data-only catalogue for explicitly selected manuscript structure checks
manuscript_vocabulary	The command and environment vocabularies the opt-in manuscript policies share
measurement_findings	Findings for configured PDF measurements: three-state outcomes that never pass by omission
metadata_privacy	Options of the metadata privacy checks: selected source edits and identity terms
metadata_privacy_rules	Data-only privacy entries for selected metadata edits and image metadata scans
online_check_rules	Data-only catalogue entries for explicitly selected remote reference checks
online_options	Settings of the online checks, and the vocabulary that every online module shares
option_config	Strict TOML conversion for grouped, immutable checker options, and the checks they share
package_headers	Literal release metadata of the class and package files a build loaded
path_safety	Relative-path validation and containment checks for paths from settings, archives and tools
pdf_artwork_options	Artwork policy options and the rules they switch on (no measurement code)
pdf_artwork_rules	Data-only catalogue for explicit artwork measurements and review candidates
pdf_check_options	The option schema of the configured PDF measurements, and which checks it enables
pdf_check_rules	Data-only catalogue for optional PDF measurements and object policies
pdf_geometry	Page geometry, colour and render-size arithmetic shared by the PDF measurements
pdf_previews	Optional, bounded PNG previews kept outside serializable job reports
pdf_rule_names	The names of the pdf.* rules reported for the manuscript PDF and its input figures
pdf_tool_output	Parsers for the text and XML that Poppler and MuPDF print about a PDF
png_support	PNG framing shared by the encoder, the validator and the two readers
project_files	The files of a project as the source graph inventories them, and how their names compare
project_names	Names inside a project: normalization, collisions, portability and excluded metadata
raster_pixels	Bounded PNM raster reading and pixel analysis in C-speed standard-library byte operations
redaction	Bounded credential redaction for complete, JSON/asdict-shaped report trees
report	The Report a job produces, with its outcome, changes and sanitized serialization
reporting_rules	Data-only entries for explicit review and diagnostic reporting safeguards
resource_budget	Atomic CPU, memory and tool-class reservations shared by every expensive job operation
rule_definition	The shape of one catalogued check; data-only *_rules.py modules build these
rules	Stable public check codes, descriptions and the behavioural tests associated with them
runtime_rules	Data-only catalogue for explicit build backend verification
setting_choices	Closed sets of values that settings accept
source_command_checks	Judging the commands of one parsed source: which ones the literal subset cannot follow
source_file_commands	Which LaTeX commands read a project file, and how each names its file
source_findings	Where the source graph records what it could not establish, and the wording it shares
source_graph	Literal dependency graph of a LaTeX project, built on the bounded lexical subset
source_graph_rules	Data-only catalogue for the literal source graph
source_loading	Reading one project source and lexing it, within the byte and command budgets
source_resolution	Turning the file name in a command into the project file TeX would read
source_transform_rules	Data-only diagnostic catalogue for explicitly selected source preparation
structure_rules	Data-only catalogue for explicit author and PDF structure checks
submission_check_rules	Data-only catalogue entries for configurable local submission checks
submission_options	The [submission_checks] settings: what to scan a submission bundle for, and how
submission_readiness_rules	Data-only catalogue for cheap submission-readiness advisories and their opt-in policies
tex_commands	TeX source vocabularies: file suffixes, math markers and command families
tex_comments	Comments of a TeX source with their line numbers, and the private notes among them
tex_lexer	Bounded lexical subset of LaTeX shared by source inspection, checks and transformations
tex_protected_regions	Regions of TeX source that a tool must leave exactly as written
text_edits	Offset-based text edits, byte-order-mark restoration and unified diffs of proposals
text_safety	Making untrusted text harmless for one output channel
uncertainty_reasons	Why a literal declaration may not take effect where it is written
workflow_options	Options for packaging several documents and for comparing PDFs, independent of any publisher
workflow_rules	Data-only catalogue for document packages and repeat builds

Infrastructure adapters

The boundary to the outside world: restricted tool execution and its sandboxes, the PDF tool sessions, the build with latexmk and its evidence, the HTTP client for online lookups, project import and the submission archive, and settings discovery. They import the domain layer and each other, never a check, the job workflow or an output format. (34 modules)

Module	Responsibility
biber_toolchain	A sealed single-architecture Biber that macOS Seatbelt may execute
bibliography_controls	Which bibliography backend a build’s fresh control files require
build_bibliography	Bibliography backends in one build: when to prepare Biber, and what the controls require
build_dependencies	Bounded fresh build evidence: the recorder trace and latexmk’s rule database
build_log	Findings from the bounded final-pass log of a LaTeX build
build_recorder	What the TeX recorder shows one build read, judged for build checks
build_result	What one isolated build returns: its findings, evidence and the report entries
build_workspace	The disposable workspace of one build: a bounded copy of the source and an output folder
command_runner	The port that checks use to run external tools, and the values it exchanges
config_discovery	Finding and reading the settings file of a job
crossref	The Crossref REST API as the online checks use it: request URLs and typed replies
formatting	Explicit tex-fmt adapter; computes patches without modifying the input
import_budget	The limits that bound a project import, and the running count of what an import has used
latexmk_build	Isolated latexmk builds of one main file, with fresh and bounded build evidence
latexmk_command	The latexmk command line of one build and the fixed Perl configuration it carries
loaded_options	Bounded post-document LaTeX kernel option evidence from disposable builds
online_http_session	Bounded requests to public hosts: connection, pacing, budget, redirects and caching
online_http_wire	The HTTP/1.1 bytes of one request and its bounded response
pdf_qpdf_graph	Read access to a PDF’s objects through qpdf’s JSON version 2 output
pdf_tools	Running PDF tools: argument builders, frozen inputs, sessions and measurements
pinned_dns	Resolving a host name to public addresses without letting a slow resolver stall a job
presets	Opt-in example settings files shipped as package data
process_control	Starting and stopping child processes so that none outlives a cancelled launcher
process_table	How the platform lists processes, and which registered command each one belongs to
project	Copy a project folder or ZIP archive into a new, bounded, link-free snapshot
project_archive	Write a staged project folder as a reproducible submission ZIP archive
public_url	Which URLs and network addresses an online check may request, and how they are shown
resource_monitor	Process, memory and storage accounting for restricted tool commands
runtime	Fail-closed local tool execution: the sandboxed ToolRunner
sandbox	Restricted execution backends: macOS Seatbelt and Linux Bubblewrap
tool_launch	What every tool command starts with: resource-limit wrapper, environment and refusal check
toolchain	Locate installed tools and the system and distribution resources they may read
toolchain_help	Installation guidance when the TeX toolchain a build needs is missing
zip_validation	Checks that make a ZIP archive safe to extract, before and while its entries are read

Checks, transforms and policies

The checks and the transformations: bibliography, manuscript, build, PDF, online, submission and source checks, the planners that edit a staged copy (source and bibliography transformations, flat layout, cleanup, metadata edits), and the two policies that decide which checks run and which findings a review accepts. They import the domain and adapter layers, never the job workflow or an output format. (61 modules)

Module	Responsibility
author_records	Explicit, user-configured author-record contracts in the literal preamble
bbl_checks	Shipped generated bibliography (.bbl): presence, citation coverage and biblatex format
bibliography_checks	Offline citation coverage and field checks over a manuscript’s declared bibliography
bibliography_duplicates	Search for entries that probably describe the same work
bibliography_edits	Operations of a bibliography proposal that need only the .bib files
bibliography_field_checks	Checks of the fields inside each bibliography entry
bibliography_files	Finding and reading the .bib files of a project, within byte and count budgets
bibliography_index	The entries of a set of .bib documents: their keys, aliases, relationships and reach
bibliography_integrity	Offline integrity checks of the .bib files themselves
bibliography_keys	Operations of a bibliography proposal that depend on the manuscript’s citations
bibliography_proposal	What a bibliography proposal is, and the helpers that its operations share
bibliography_results	How the offline bibliography checks word and order their findings
bibliography_styles	The string macros that BibTeX styles define, so that they are not reported as undefined
bibliography_transform	Explicit, atomic bibliography proposals for a supported literal source graph
build_checks	Explicit checks over complete build evidence, including transitive packages
check_policy	Maps the selected checks onto the options that activate them before dispatch
figure_color_space	The colour space of raster figures against the family a venue requires (PDF313)
flat_layout	Planning a flat layout: every shipped file at the top level, references rewritten to match
image_metadata	Bounded scan of PNG and JPEG metadata for configured identity terms
manuscript	Configurable constraints on the literal declarations of one selected source graph
manuscript_abstract_checks	Citations and uppercase abbreviations in the abstract (MAN003, MAN004)
manuscript_checks	Opt-in, publisher-neutral checks of literal manuscript structures
manuscript_float_checks	Captions, labels, references and descriptions of figures and tables (MAN011 to MAN016)
manuscript_heading_checks	Heading depth, empty sections and required declarations (MAN005, MAN006, MAN010)
manuscript_layout_checks	Layout override candidates (MAN002) and required or forbidden line numbers (MAN017)
manuscript_metadata_checks	Required literal metadata and ORCID identifiers (MAN008, MAN009), and the reader
manuscript_package_checks	The direct package inventory and the allowlist policy (MAN001)
manuscript_policy_kernel	What every opt-in manuscript policy shares: the reading, the outcome and the finding
manuscript_reference_checks	Hard-coded figure, table, section and equation numbers in prose (MAN007)
manuscript_scan	Literal declarations collected from the selected source graph, and the counts made of them
metadata_source_edits	Explicit literal metadata edits in copied TeX sources, and the final PDF recheck
online_checks	Explicit, bounded online reference checks; no rewriting or implicit networking
online_comparison	Comparing a bibliography entry with the Crossref record of its DOI
online_inputs	What an online check may send: bibliography entries and source links, bounded
package_inputs	Select project inputs for one observed build, without modifying the source tree
package_inventory	Reconcile selection evidence with observed package files and existing ZIP sizes
pdf_artwork	Opt-in advisory artwork measurements of one PDF, composed from the artwork modules
pdf_artwork_drawings	Artwork findings measured from the MuPDF trace of painted drawings
pdf_artwork_rendered	Rendered-pixel artwork measurements: figure whitespace, edge ink, previews and contrast
pdf_artwork_trace	MuPDF trace geometry: painted drawings with their placement, extent and active clip
pdf_check_pipeline	Run the configured PDF check groups together, for a source project or a lone PDF
pdf_checks	Optional, bounded PDF measurements with explicit evidence boundaries
pdf_comparison	Bounded rendered and extracted-text comparison of two PDFs, with optional previews
pdf_inspection	Bounded single-PDF inspection and explicitly configured acceptance policies
pdf_object_checks	Catalog-language, annotation and action policies read from qpdf’s object data
pdf_paint_checks	Stroke-width, color-space, text-contrast and grayscale-separation measurements
pdf_printer_marks	Printer-mark candidates: short crop and registration strokes outside a trim region
pdf_sparse_page_checks	Sparse-page measurement: how much of each rendered page carries ink
pdf_structure_checks	Bounded tagged-PDF structure observations and the structure option schema
pdf_structure_tree	The tagged structure tree of a PDF, read from qpdf’s object data
pdf_text_geometry_checks	Text-size, printable-bounds and overlap measurements from Poppler’s text boxes
pdf_type3_glyphs	Type 3 glyph programs: do declared glyphs paint images, vector shapes, or both?
project_cleanup	Propose the debris of a staged project that a submission should not contain
review_policy	Explicit scoped review decisions: accepted exceptions and suppressed advisories
source_analysis	Inspecting a project’s sources without editing them: roots, dependencies and lint
source_transform	Opt-in, copy-only source transformations for a bounded literal TeX subset
submission_checks	Bounded, local submission-policy checks; never edit sources or execute TeX
submission_content_scan	The single pass over every supplied file that finds identity terms, secrets and notes
submission_readiness_checks	Cheap, deterministic submission-readiness advisories over the literal source graph
submission_scan_findings	Findings for the matches of a submission scan, and the wording they share
submission_text	Bounded, source-only submission fields; unresolved content remains visible

Orchestration

The job workflow: validating a request and settings, scheduling the tasks of one document or of several, importing, building, staging, verifying and publishing, and turning the results into a report. It uses everything below it and knows nothing of terminals, HTML or the command line. (19 modules)

Module	Responsibility
config	Validated settings: the Settings schema, layered from preset, file and command line
core	Application workflow entry point: validates a job request, dispatches its command and publishes the result
coverage_hints	Opt-in checks that a run did not perform because its settings left them off
doctor	Bounded setup diagnostics using application-owned sources and normal isolation
document_builds	The builds of one document beyond the scheduled baseline: staged rebuilds and repeats
document_run	One project’s run: import, analysis, baseline, staged transformations and a verified package
document_tasks	Scheduled tasks of one document and the build and comparison adapters they share
documents	Several explicitly selected documents of one project, each checked and packaged independently
job_context	The request, settings and resources every stage of one job shares
job_execution	The resource budget, restricted runner, private workspace and deadline of one job
job_report	How a job’s findings become its outcome: stage tags, blocking, check selection and review
main_selection	Choosing the main file of a project: the configured one, else the only candidate root
package_verification	The last steps of preparation: archive the sources, rebuild from the ZIP, run final checks
publication	Publish verified packages, previews and reports into new directories outside the input
scheduler	Dependency scheduling of job tasks under the shared resource budget
staging	Staging copies of an imported project: document selection, transformations and flattening
standalone_checks	Checks of one aspect without the build workflow: a PDF, the bibliography or formatting
task_findings	The findings that say how a scheduled task ended, and the contract readers rely on
task_reporting	How the tasks, builds and input selections of one document enter its report

Presentation

Everything a person or a script sees: the fledge command line and its option helpers, the renderers for the terminal, compact, JSON, HTML and CI output, the progress display and the diagnostic log. These are the only modules that import click or rich. (21 modules)

Module	Responsibility
__main__	Entry point for python -m latexprep; runs the command line
ci_annotations	GitHub Actions workflow annotations for a report, one escaped command per line
cli	The fledge command line: commands, options, settings layering and exit codes
command_options	Click option helpers and failure handling shared by the command adapters
compact_report	The compact report: short plain records for scripts and coding agents
diagnostic_bundle	Explicitly unverified diagnostic ZIP exports of sanitized reports and diffs
diagnostic_logging	Opt-in diagnostic log lines on stderr (--debug); the library itself emits nothing
doctor_command	CLI adapter for bounded local setup diagnostics
finding_view	One display view per finding, shared by every report renderer
html_report	The offline HTML report: escaped evidence and no executable or remote resources
html_report_previews	The PDF-differences section of the HTML report: before and after page images
html_report_regions	SVG diagrams of the page regions a PDF finding reports, for the HTML report
html_text	Escaping of report values for the HTML renderers
init_command	fledge init: write a starter or preset fledge.toml without prompting
report_files	Saving the report files a command was asked for
report_formats	Report output formats and the one dispatch commands use to write a final report
rule_catalogue_view	Terminal views of the check catalogue: the list of checks and the explanation of one
submission_text_command	CLI adapter for source-only submission text export
terminal_console	The Rich consoles every command prints through
terminal_progress	Transient progress on a terminal, plain stages when stderr is redirected
terminal_report	The Rich terminal report, and plain rendering of it for tests and embedding