AuxFlow

A compiler and static analyzer for LaTeX documents.

AuxFlow checks LaTeX cross-references and citations before the typesetting engine runs. It builds a dependency graph of all labels and references, detects cyclic loops, and calculates the exact compile passes the document needs.

For complete technical specifications, compiler architecture, and evaluation reports, visit the Documentation Website.

Installation

Install with the automated script (installs the package and sets your PATH):

curl -sSL https://auxflow.upayan.dev/install.sh | bash

Or install manually with pipx:

pipx install auxflow
pipx ensurepath

Or with pip:

pip install --user auxflow

AuxFlow requires Python 3.12 or newer.

Quick Start

Check a LaTeX document:

auxflow check document.tex

Find the number of required compilation passes:

auxflow classify document.tex

Build the document with automatic runtime checks:

auxflow run document.tex

Show all commands and options:

auxflow help

How It Works

LaTeX documents write labels, tables of contents, and citations to helper files (.aux, .toc, .bbl). Standard build tools repeat the compile process until these files stop changing.

AuxFlow analyzes your source code directly:

1. Scans and parses your LaTeX files into an Abstract Syntax Tree.
2. Builds a dependency graph of all references, lists, and citations.
3. Finds feedback cycles and calculates whether values affect document length.
4. Assigns a convergence state:
   • CERTIFIED: Clean document with a fixed pass count.
   • BENIGN_CYCLIC: Safe cycles that settle without changing length.
   • AMPLIFYING: Loops that cause endless page expansion. Refused by default.
   • UNKNOWN: Unrecognized packages or commands. Uses safe default runs.
5. Creates an optimized build plan that skips redundant runs and unnecessary tool calls.

Documentation

Full documentation is available at auxflow.upayan.dev:

• Technical Reference: Architecture, Compiler Pipeline, Intermediate Representation, and Static Analysis.
• Project Details: Formal Specifications, Research Questions, and Literature Review.
• Evaluation & Benchmarks: 15-document Benchmark Corpus, Methodology, and Verification Reports.
• Course Reviews: Review Notes, Presentations, and Downloadable Documents.

License

MIT License. See LICENSE.