plankevm/plank-monorepo/frontend-diagnostics

Call site (business logic)
    |  calls emit_foo(index, span, ...)
    v
emit_ method (on pipeline struct)
    |  resolves names/spans via self
    |  builds Diagnostic via builder API
    v
Session::emit_diagnostic(diagnostic)

// BAD: formatting scattered in business logic
let name = self.resolve_name(ident_idx);
self.session.borrow_mut().emit_diagnostic(
    Diagnostic::error(format!("cannot find `{name}` in this scope"))
        .primary(self.source_id, self.span_of(ident_idx), "not found in this scope")
);

// Call site: passes only what it naturally has
self.emit_unresolved_ident(ident_idx);

// In a diagnostics impl block (typically diagnostics.rs):
impl BlockLowerer<'_> {
    fn emit_unresolved_ident(&self, ident: IdentIdx) {
        let name = self.resolve_name(ident);
        let span = self.span_of(ident);
        self.emit_diagnostic(
            Diagnostic::error(format!("cannot find `{name}` in this scope"))
                .primary(self.source_id, span, "not found in this scope")
        );
    }
 
    fn emit_diagnostic(&self, diagnostic: Diagnostic) {
        self.session.borrow_mut().emit_diagnostic(diagnostic);
    }
}

// Two annotations in ONE snippet (same source):
Diagnostic::error("variable not declared mutable")
    .element(
        Cause::new(self.source_id)
            .primary(assign_span, "assignment to immutable variable")
            .secondary(decl_span, "declared here")
    )
    .help("consider declaring it with `let mut`")
 
// Two annotations in SEPARATE snippets (different sources):
Diagnostic::error("unresolved import")
    .primary(self.source_id, span, "not found in target module")
    .add_claim(
        Claim::new(Level::Note, "target module")
            .element(Element::Origin { path: target_source })
    )

if self.source_id == prev_source_id {
    diagnostic = diagnostic.element(
        Cause::new(self.source_id)
            .primary(span, "conflicting import")
            .secondary(prev_span, prev_label),
    );
} else {
    diagnostic = diagnostic
        .primary(self.source_id, span, "conflicting import")
        .element(Cause::new(prev_source_id).secondary(prev_span, prev_label));
}

struct Pipeline {
    session: Session,
}
impl Pipeline {
    fn emit_some_error(&mut self, span: SourceSpan) {
        self.session.emit_diagnostic(
            Diagnostic::error("...").primary(self.source_id, span, "...")
        );
    }
}

struct BlockLowerer<'a> {
    session: RefCell<&'a mut Session>,
}
impl BlockLowerer<'_> {
    fn emit_diagnostic(&self, diagnostic: Diagnostic) {
        self.session.borrow_mut().emit_diagnostic(diagnostic);
    }
}