mos/

main.rs

//! `mos`: command-line interface for the Mosaic typesetting engine.
//!
//! Subcommands mirror manifest §15.1. `mos check` (read source → parse →
//! lower → resolve → report diagnostics) and `mos build` (the same, then
//! layout → PDF) are wired end-to-end; every other subcommand exits with an
//! error until its slice lands.

#![doc(
    html_logo_url = "https://mosaiclang.dev/assets/A4.svg",
    html_favicon_url = "https://mosaiclang.dev/assets/A4.svg"
)]
#![allow(
    clippy::print_stderr,
    clippy::print_stdout,
    reason = "CLI boundary intentionally writes user output directly"
)]

use std::path::{Component, Path, PathBuf};
use std::process::{Command as ProcessCommand, ExitCode};

use clap::{Parser, Subcommand};
use mos_core::{
    Diagnostic, DiagnosticAnnotation, DiagnosticResult, DiagnosticSink, Severity, SourceSpan,
    Suggestion, display_path, linecol,
};

/// Cap on resolve↔layout rounds for page references before the engine gives up
/// and reports `MOS0047` (issue #72). Stable documents settle in one or two
/// rounds; the cap bounds pathological oscillation so the build always
/// terminates.
const MAX_PAGE_FIXPOINT_ITERATIONS: u32 = 8;

#[derive(Parser, Debug)]
#[command(
    name = "mos",
    bin_name = "mos",
    version,
    about = "Mosaic: semantic, incremental typesetting compiler",
    long_about = "Mosaic compiles `.mos` source files to PDF.\n\
                  See manifest.md in the repository root for the full design."
)]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand, Debug)]
enum Command {
    /// Initialise a new Mosaic project in the current directory.
    Init {
        #[arg(default_value = ".")]
        path: PathBuf,
    },

    /// Build the project to its declared outputs.
    Build {
        #[arg(value_name = "PATH")]
        entries: Vec<PathBuf>,
        /// Open the generated PDF after a successful build.
        ///
        /// Use `--open` for the platform default, or `--open=PROGRAM`
        /// to invoke a specific viewer.
        #[arg(
            long,
            value_name = "PROGRAM",
            num_args = 0..=1,
            default_missing_value = "",
            require_equals = true
        )]
        open: Option<String>,
        /// Write a .layout.pdf with boxes/baselines and a .layout.json report beside each PDF.
        #[arg(long)]
        debug_layout: bool,
        /// Refuse to update dependencies (manifest §15.3).
        #[arg(long)]
        frozen: bool,
        /// Make the build deterministic (manifest §24).
        #[arg(long)]
        reproducible: bool,
    },

    /// Watch sources and rebuild on change (manifest §8).
    Watch {
        #[arg(default_value = "main.mos")]
        entry: PathBuf,
    },

    /// Type-check and validate without producing output.
    Check {
        #[arg(value_name = "PATH")]
        entries: Vec<PathBuf>,
    },

    /// Format `.mos` sources (manifest §18).
    Fmt {
        #[arg(default_value = ".")]
        path: PathBuf,
    },

    /// Run document and package tests (manifest §28).
    Test,

    /// Profile a build and report layout hot spots (manifest §16).
    Profile {
        #[arg(default_value = "main.mos")]
        entry: PathBuf,
    },

    /// Remove build artefacts and the local cache.
    Clean,

    /// Bundle a project into a `.mosaicbundle` archive (manifest §15.3).
    Package {
        #[arg(default_value = "main.mos")]
        entry: PathBuf,
    },
}

fn main() -> ExitCode {
    let cli = Cli::parse();

    match cli.command {
        Command::Check { entries } => run_checks(&entries),
        Command::Build {
            entries,
            open,
            debug_layout,
            frozen: _,
            reproducible: _,
        } => run_builds(&entries, PdfOpen::from_cli(open.as_deref()), debug_layout),
        Command::Init { .. } => unimplemented_subcommand("init"),
        Command::Watch { .. } => unimplemented_subcommand("watch"),
        Command::Fmt { .. } => unimplemented_subcommand("fmt"),
        Command::Test => unimplemented_subcommand("test"),
        Command::Profile { .. } => unimplemented_subcommand("profile"),
        Command::Clean => unimplemented_subcommand("clean"),
        Command::Package { .. } => unimplemented_subcommand("package"),
    }
}

fn default_entries(entries: &[PathBuf]) -> Vec<PathBuf> {
    if entries.is_empty() {
        vec![PathBuf::from("main.mos")]
    } else {
        entries.to_owned()
    }
}

fn run_checks(entries: &[PathBuf]) -> ExitCode {
    run_many(entries, run_check)
}

fn run_builds(entries: &[PathBuf], open: PdfOpen<'_>, debug_layout: bool) -> ExitCode {
    run_many(entries, |entry| run_build(entry, open, debug_layout))
}

fn run_many(entries: &[PathBuf], mut run_one: impl FnMut(&Path) -> ExitCode) -> ExitCode {
    let entries = default_entries(entries);
    let many = entries.len() > 1;
    let mut ran = false;
    let mut failed = false;

    for entry in &entries {
        if should_skip_glob_file(entry, many) {
            continue;
        }
        ran = true;
        if run_one(entry) != ExitCode::SUCCESS {
            failed = true;
        }
    }

    if failed || !ran {
        ExitCode::FAILURE
    } else {
        ExitCode::SUCCESS
    }
}

fn should_skip_glob_file(entry: &Path, many: bool) -> bool {
    many && entry.is_file() && !is_mos_source(entry)
}

fn is_mos_source(entry: &Path) -> bool {
    entry.extension().is_some_and(|ext| ext == "mos")
}

fn unimplemented_subcommand(name: &str) -> ExitCode {
    eprintln!("mos {name}: not yet implemented (see manifest §30 MVP roadmap)");
    ExitCode::FAILURE
}

/// `mos check`: parse + lower the entry file and report diagnostics.
/// Exits 0 if no errors (warnings still print); 1 otherwise.
fn run_check(entry: &Path) -> ExitCode {
    let Ok(entry) = resolve_entry("check", entry).map(|entry| entry.source) else {
        return ExitCode::FAILURE;
    };
    let src = match std::fs::read_to_string(&entry) {
        Ok(s) => s,
        Err(err) => {
            eprintln!("mos check: cannot read `{}`: {err}", display_path(&entry));
            return ExitCode::FAILURE;
        }
    };

    let mut sink = RenderingSink::new(&src);

    // Parse phase. A parse error stops the pipeline before lowering, so
    // the evaluator never runs on a structurally broken tree and the
    // user sees every recoverable syntax diagnostic in one pass.
    let Ok(tree) = mos_parse::parse(&src, &entry, &mut sink) else {
        return ExitCode::FAILURE;
    };
    if sink.had_error() {
        eprintln!(
            "mos check: {} error(s), {} warning(s)",
            sink.errors, sink.warnings
        );
        return ExitCode::FAILURE;
    }

    // Lower + resolve phase.
    let result = mos_eval::lower_tree(&tree);
    let node_count = result.document.len();
    sink.render_all(result.diagnostics);

    if sink.had_error() {
        eprintln!(
            "mos check: {} error(s), {} warning(s)",
            sink.errors, sink.warnings
        );
        ExitCode::FAILURE
    } else {
        println!("ok: {node_count} node(s), {} warning(s)", sink.warnings);
        ExitCode::SUCCESS
    }
}

/// `mos build`: read source, parse, lower, lay out, and emit a PDF to
/// `build/<entry-stem>.pdf` or the project's `[output].pdf`. Paper size and
/// margins come from `#set page(...)`; text uses the Base-14 fonts with the
/// bundled Noto Sans embedded and subset for glyphs they lack. Layout
/// warnings print but don't fail the build.
fn run_build(entry: &Path, open: PdfOpen<'_>, debug_layout: bool) -> ExitCode {
    let Ok(resolved) = resolve_entry("build", entry) else {
        return ExitCode::FAILURE;
    };
    let entry = resolved.source;
    let src = match std::fs::read_to_string(&entry) {
        Ok(s) => s,
        Err(err) => {
            eprintln!("mos build: cannot read `{}`: {err}", display_path(&entry));
            return ExitCode::FAILURE;
        }
    };

    let started = std::time::Instant::now();
    let mut sink = RenderingSink::new(&src);

    // Each phase runs to completion, then the barrier below stops the
    // build before the next phase if any error was collected, so a
    // broken document never reaches PDF emission and writes garbage.
    let Ok(tree) = mos_parse::parse(&src, &entry, &mut sink) else {
        return ExitCode::FAILURE;
    };
    if sink.had_error() {
        return ExitCode::FAILURE;
    }

    let result = mos_eval::lower_tree(&tree);
    sink.render_all(result.diagnostics);
    if sink.had_error() {
        return ExitCode::FAILURE;
    }

    // Resolve `@page(...)` references by iterating layout until the page
    // numbers stabilize (issue #72). Each round lays the document out and feeds
    // the resulting label→page map back into the resolver; layout is the
    // injected closure so the fixpoint logic itself lives in `mos-eval`. A
    // document with no page references settles in one round.
    let mut document = result.document;
    let (page_outcome, layout) = mos_eval::resolve_page_reference_fixpoint(
        &mut document,
        |doc| {
            let engine = mos_layout::LayoutEngine::new();
            let layout = if debug_layout {
                engine.layout_with_debug(doc)
            } else {
                engine.layout(doc)
            };
            (layout.label_pages.clone(), layout)
        },
        MAX_PAGE_FIXPOINT_ITERATIONS,
    );
    if let mos_eval::PageFixpointOutcome::NotConverged { iterations } = page_outcome {
        let _ = sink.emit(Diagnostic::simple(
            &mos_core::codes::MOS0047,
            None,
            format!(
                "page references did not converge after {iterations} layout iterations; \
                 using the last computed page numbers"
            ),
        ));
    }

    // Layout can produce real errors (MOS0017 unknown paper, MOS0023
    // geometrically invalid margin/leading). Don't ship a PDF with
    // broken config under a success exit code. Only the final layout's
    // diagnostics are rendered, so iterating does not duplicate them.
    sink.render_all(layout.diagnostics);
    if sink.had_error() {
        return ExitCode::FAILURE;
    }

    let stem = entry.file_stem().map_or_else(
        || std::ffi::OsString::from("out"),
        std::ffi::OsStr::to_os_string,
    );
    let out = resolved.output.unwrap_or_else(|| {
        let mut path = resolved.output_base.join("build");
        path.push(format!("{}.pdf", stem.to_string_lossy()));
        path
    });

    let metadata = mos_pdf::PdfMetadata {
        title: result.metadata.title.clone(),
        author: result.metadata.author.clone(),
        language: result.metadata.language,
    };
    match mos_pdf::emit(&layout.graph, &metadata, &out) {
        Ok(pdf_diagnostics) => {
            sink.render_all(pdf_diagnostics);
            if sink.had_error() {
                return ExitCode::FAILURE;
            }
        }
        Err(err) => {
            match err {
                mos_core::CoreError::Diagnostic(d) => {
                    let _ = sink.emit(*d);
                }
                mos_core::CoreError::Unimplemented(msg) => {
                    eprintln!("mos build: {msg}");
                }
            }
            return ExitCode::FAILURE;
        }
    }

    let mut viewer_out = out.clone();
    if let Some(report) = &layout.debug {
        let debug_out = out.with_extension("layout.json");
        let data = match serde_json::to_vec_pretty(report) {
            Ok(mut data) => {
                data.push(b'\n');
                data
            }
            Err(err) => {
                eprintln!("mos build: cannot encode layout debug report: {err}");
                return ExitCode::FAILURE;
            }
        };
        if let Err(err) = std::fs::write(&debug_out, data) {
            eprintln!(
                "mos build: cannot write layout debug report to {}: {err}",
                display_path(&debug_out)
            );
            return ExitCode::FAILURE;
        }
        println!("wrote {}", display_path(&debug_out));
        viewer_out = out.with_extension("layout.pdf");
        if let Err(err) = mos_pdf::emit_debug(&layout.graph, report, &metadata, &viewer_out) {
            // Font diagnostics were already rendered for the identical graph
            // above; only a new emission failure needs reporting here.
            match err {
                mos_core::CoreError::Diagnostic(d) => {
                    let _ = sink.emit(*d);
                }
                mos_core::CoreError::Unimplemented(msg) => eprintln!("mos build: {msg}"),
            }
            return ExitCode::FAILURE;
        }
        println!("wrote {}", display_path(&viewer_out));
    }

    println!(
        "wrote {} in {} ms",
        display_path(&out),
        started.elapsed().as_millis()
    );
    if open.should_open() {
        match open_pdf(&viewer_out, open) {
            Ok(()) => println!("opened {}", display_path(&viewer_out)),
            Err(err) => {
                eprintln!("mos build: {err}");
                return ExitCode::FAILURE;
            }
        }
    }
    ExitCode::SUCCESS
}

struct ResolvedEntry {
    source: PathBuf,
    output_base: PathBuf,
    output: Option<PathBuf>,
}

fn resolve_entry(command: &str, entry: &Path) -> Result<ResolvedEntry, ()> {
    if !entry.is_dir() {
        let output_base = entry
            .parent()
            .unwrap_or_else(|| Path::new("."))
            .to_path_buf();
        return Ok(ResolvedEntry {
            source: entry.to_path_buf(),
            output_base,
            output: None,
        });
    }

    let manifest_path = entry.join("mosaic.toml");
    if manifest_path.is_file() {
        let manifest = match mos_packages::ProjectManifest::load(&manifest_path) {
            Ok(manifest) => manifest,
            Err(err) => {
                eprintln!("mos {command}: {err}");
                return Err(());
            }
        };
        let source = mos_core::resolve_relative(entry, &manifest.project.entry).map_err(|err| {
            eprintln!(
                "mos {command}: invalid project entry path `{}`: {err}",
                manifest.project.entry
            );
        })?;
        return Ok(ResolvedEntry {
            source,
            output_base: entry.to_path_buf(),
            output: match manifest.output.pdf.as_deref() {
                Some(path) => Some(resolve_manifest_output(command, entry, path)?),
                None => None,
            },
        });
    }

    Ok(ResolvedEntry {
        source: entry.join("main.mos"),
        output_base: entry.to_path_buf(),
        output: None,
    })
}

fn resolve_manifest_output(command: &str, project_dir: &Path, output: &str) -> Result<PathBuf, ()> {
    let output_path = Path::new(output);
    if output_path.as_os_str().is_empty()
        || output_path.components().any(|component| {
            matches!(
                component,
                Component::ParentDir | Component::RootDir | Component::Prefix(_)
            )
        })
    {
        eprintln!(
            "mos {command}: invalid PDF output path `{output}`; use a relative path inside the project"
        );
        return Err(());
    }
    mos_core::resolve_relative(project_dir, output).map_err(|err| {
        eprintln!("mos {command}: invalid PDF output path `{output}`: {err}");
    })
}

#[derive(Debug, Clone, Copy)]
enum PdfOpen<'a> {
    No,
    Default,
    Program(&'a str),
}

impl<'a> PdfOpen<'a> {
    const fn from_cli(open: Option<&'a str>) -> Self {
        match open {
            None => Self::No,
            Some(program) => {
                if program.is_empty() {
                    Self::Default
                } else {
                    Self::Program(program)
                }
            }
        }
    }

    const fn should_open(self) -> bool {
        !matches!(self, Self::No)
    }
}

fn open_pdf(path: &Path, request: PdfOpen<'_>) -> Result<(), String> {
    match request {
        PdfOpen::No => Ok(()),
        PdfOpen::Default => opener::open(path.as_os_str())
            .map_err(|err| format!("could not open `{}`: {err}", display_path(path))),
        PdfOpen::Program(program) => {
            let mut command = ProcessCommand::new(program);
            command.arg(path);
            let status = command.status().map_err(|err| {
                format!(
                    "could not open `{}` with `{program}`: {err}",
                    display_path(path)
                )
            })?;
            if status.success() {
                Ok(())
            } else {
                Err(format!(
                    "opener `{program}` failed for `{}` with {status}",
                    display_path(path)
                ))
            }
        }
    }
}

/// A [`DiagnosticSink`] that renders each diagnostic to stderr as it
/// arrives and tracks error/warning counts. The CLI drives one of these
/// across every phase and checks [`Self::had_error`] at each phase
/// barrier; that, not `Severity::Error` itself, is what stops the build.
struct RenderingSink<'a> {
    src: &'a str,
    errors: usize,
    warnings: usize,
}

impl<'a> RenderingSink<'a> {
    const fn new(src: &'a str) -> Self {
        Self {
            src,
            errors: 0,
            warnings: 0,
        }
    }

    const fn had_error(&self) -> bool {
        self.errors > 0
    }

    /// Render every diagnostic in `diags`. Bridges phases that still
    /// return a `Vec<Diagnostic>` (layout, PDF emit) into the sink.
    fn render_all(&mut self, diags: impl IntoIterator<Item = Diagnostic>) {
        for diag in diags {
            let _ = self.emit(diag);
        }
    }
}

impl DiagnosticSink for RenderingSink<'_> {
    fn emit(&mut self, diagnostic: Diagnostic) -> DiagnosticResult<()> {
        match diagnostic.severity() {
            Severity::Error => self.errors += 1,
            Severity::Warning => self.warnings += 1,
            Severity::Notice => {}
        }
        render_diagnostic(&diagnostic, self.src);
        Ok(())
    }
}

const fn severity_label(s: Severity) -> &'static str {
    match s {
        Severity::Error => "error",
        Severity::Warning => "warning",
        Severity::Notice => "notice",
    }
}

fn render_diagnostic(diag: &Diagnostic, src: &str) {
    let label = severity_label(diag.severity());
    let code = format!("{} ({})", diag.def().id(), diag.def().code());
    if let Some(span) = diag.span() {
        let (line, col) = linecol(src, span.start());
        eprintln!(
            "{label}[{code}]: {msg}\n  --> {file}:{line}:{col}",
            msg = diag.message(),
            file = display_path(&span.file),
        );
        render_span_caret(src, span);
    } else {
        eprintln!("{label}[{code}]: {msg}", msg = diag.message());
    }
    for annotation in diag.annotations() {
        match annotation {
            DiagnosticAnnotation::Related { span, message } => {
                let (line, col) = linecol(src, span.start());
                eprintln!(
                    "  note: {message} ({file}:{line}:{col})",
                    file = display_path(&span.file),
                );
            }
            DiagnosticAnnotation::Note(message) => eprintln!("  note: {message}"),
            DiagnosticAnnotation::Help(message) => eprintln!("  help: {message}"),
            DiagnosticAnnotation::Hint(message) => eprintln!("  hint: {message}"),
        }
    }
    for suggestion in diag.suggestions() {
        render_suggestion(src, suggestion);
    }
}

fn render_suggestion(src: &str, suggestion: &Suggestion) {
    eprintln!("  help: {}", suggestion_help(src, suggestion));
}

fn suggestion_help(src: &str, suggestion: &Suggestion) -> String {
    let (line, col) = linecol(src, suggestion.span.start());
    let file = display_path(&suggestion.span.file);
    // The deletion arm carries an empty replacement, so the replacement text
    // is formatted only in the arms that actually print it.
    match suggestion_text(src, &suggestion.span) {
        Some("") => {
            let replacement = display_edit_text(&suggestion.replacement);
            format!("insert `{replacement}` at {file}:{line}:{col}")
        }
        Some(text) if suggestion.replacement.is_empty() => {
            let text = display_edit_text(text);
            format!("delete `{text}` at {file}:{line}:{col}")
        }
        Some(text) => {
            let text = display_edit_text(text);
            let replacement = display_edit_text(&suggestion.replacement);
            format!("replace `{text}` with `{replacement}` at {file}:{line}:{col}")
        }
        None => {
            let replacement = display_edit_text(&suggestion.replacement);
            format!("replace text with `{replacement}` at {file}:{line}:{col}")
        }
    }
}

fn suggestion_text<'a>(src: &'a str, span: &SourceSpan) -> Option<&'a str> {
    let start = clamp_to_char_boundary(src, span.start().min(src.len()));
    let end = clamp_to_char_boundary(src, span.end().min(src.len()));
    src.get(start..end)
}

fn display_edit_text(text: &str) -> String {
    let mut out = String::with_capacity(text.len());
    for ch in text.chars() {
        match ch {
            '\n' => out.push_str("\\n"),
            '\r' => out.push_str("\\r"),
            '\t' => out.push_str("\\t"),
            other if other.is_control() => out.extend(other.escape_unicode()),
            other => out.push(other),
        }
    }
    out
}

fn clamp_to_char_boundary(src: &str, mut offset: usize) -> usize {
    offset = offset.min(src.len());
    while offset > 0 && !src.is_char_boundary(offset) {
        offset -= 1;
    }
    offset
}

fn render_span_caret(src: &str, span: &SourceSpan) {
    let (line_no, col) = linecol(src, span.start());
    let span_start = clamp_to_char_boundary(src, span.start());
    let line_start = src[..span_start].rfind('\n').map_or(0, |p| p + 1);
    let raw_line_end = src[line_start..]
        .find('\n')
        .map_or(src.len(), |p| line_start + p);
    // CRLF sources keep the trailing `\r` inside `[line_start, '\n')`;
    // strip it so the caret line lines up with what stderr actually
    // prints.
    let line_end = if raw_line_end > line_start && src.as_bytes()[raw_line_end - 1] == b'\r' {
        raw_line_end - 1
    } else {
        raw_line_end
    };
    let line_text = &src[line_start..line_end];
    // Convert byte offsets into char counts so multibyte UTF-8
    // sequences (e.g. `µ`, `é`) line up with the source above. Clamp
    // both ends to char boundaries first; otherwise a span that
    // straddles a multibyte sequence would panic the slice below.
    let span_byte_end = clamp_to_char_boundary(src, span.end().min(line_end));
    let span_byte_start = clamp_to_char_boundary(src, span_start.min(span_byte_end));
    let caret_chars = src[span_byte_start..span_byte_end].chars().count().max(1);
    eprintln!("   |");
    eprintln!("{line_no:>3}| {line_text}");
    eprintln!(
        "   | {pad}{carets}",
        pad = " ".repeat(col.saturating_sub(1)),
        carets = "^".repeat(caret_chars),
    );
}

#[cfg(test)]
mod tests {
    use std::path::PathBuf;

    use mos_core::{SourceSpan, Suggestion};

    use super::{PdfOpen, display_edit_text, suggestion_help};

    #[test]
    fn display_edit_text_escapes_control_characters_and_keeps_backslashes() {
        assert_eq!(display_edit_text("a\u{1b}[31mb"), "a\\u{1b}[31mb");
        assert_eq!(display_edit_text("x\u{7f}\u{0}y"), "x\\u{7f}\\u{0}y");
        assert_eq!(display_edit_text("assets\\logo.png"), "assets\\logo.png");
        assert_eq!(display_edit_text("a\nb\tc\rd"), "a\\nb\\tc\\rd");
    }

    #[test]
    fn pdf_open_from_cli_distinguishes_absent_default_and_program() {
        assert!(matches!(PdfOpen::from_cli(None), PdfOpen::No));

        assert!(matches!(PdfOpen::from_cli(Some("")), PdfOpen::Default));

        assert!(matches!(
            PdfOpen::from_cli(Some("zathura")),
            PdfOpen::Program("zathura")
        ));
    }

    #[test]
    fn suggestion_help_formats_replace_delete_insert_and_stale_spans() {
        let file = PathBuf::from("main.mos");
        let src = "see @bad\n";

        assert_eq!(
            suggestion_help(
                src,
                &Suggestion::new(SourceSpan::new(file.clone(), 4, 8), "@good")
            ),
            "replace `@bad` with `@good` at main.mos:1:5"
        );
        assert_eq!(
            suggestion_help(
                src,
                &Suggestion::new(SourceSpan::new(file.clone(), 4, 8), "")
            ),
            "delete `@bad` at main.mos:1:5"
        );
        assert_eq!(
            suggestion_help(
                src,
                &Suggestion::new(SourceSpan::new(file.clone(), src.len(), src.len()), "!")
            ),
            "insert `!` at main.mos:2:1"
        );
        assert_eq!(
            suggestion_help(
                src,
                &Suggestion::new(SourceSpan::new(file, src.len() + 10, src.len() + 20), "!")
            ),
            "insert `!` at main.mos:2:1"
        );
    }
}