Diagnostics

A diagnostic is a problem with the user’s design or input, explained in the user’s terms, with a stable code. Diagnostics are values: the engine collects them and keeps planning whatever it can. Errors in the Rust sense (Result) are reserved for failures to do the work at all (architecture).

pub struct Diagnostic {
    pub code: Code,                  // SC-W0702
    pub severity: Severity,          // Error | Warning | Info
    pub element: Option<ElementId>,  // which object
    pub at: Option<Point>,           // where on the canvas (mm)
    pub message: String,             // one sentence, specific: "Design is 162 × 148 mm; …"
    pub fix: Option<Fix>,            // a hint, or a machine-applicable fix
}

Codes

SC- + E (error: this element, or the design, cannot be stitched), W (warning: stitched, but probably not what you want) or I (info) + four digits grouped by area:

Codes are never reused. A retired code keeps its page with “retired in vX”.

The registry

All codes live in one table in stitchcraft-core: the registry! block in src/diag.rs, which defines the Code enum. Each entry is one line — variant, id, severity, title — and its doc comment is the long explanation (Markdown: what it means, why it matters for the sew-out, how to fix it), so the text users read is also the code’s rustdoc. Tests reject an entry whose id is malformed or duplicated, whose letter disagrees with its severity, or whose explanation is missing. From that table:

• cargo xtask docs generates the diagnostics index (one page per code, like rustc’s error index);
• stitch explain SC-W0702 prints the explanation in the terminal;
• in VectorCraft, the plug-in shows each message after its code, for the user to look up in the index or with stitch explain;
• cargo xtask conformance fails when a code has no diag_sc_<code>_<what> test that produces it from real input and checks the text a user reads, or when such a test names a code that is not registered (conformance); the registry’s own tests fail when a code has no explanation.

That last rule is what keeps error paths alive: a message that no test ever renders can ship with a typo in its formatting and nobody sees it until a user does.

Writing good messages

• Say what is wrong and by how much: “Rows are 0.25 mm apart but the region is only 0.18 mm tall.”
• Name the object and point at the place.
• Offer the fix in embroidery terms: “Use a running stitch for parts this thin, or widen the shape.”
• No blame, no internal names (LineString, GEOS), no stack traces.

As text

A diagnostic reads the same wherever StitchCraft prints it. Its Display is the severity, the code and the message: warning SC-W0702: Design is 190.0 × 150.0 mm; …. Diagnostic::headline adds the object it is about, as in warning SC-W0307 (svg:patch:fill): The area falls into 2 parts., and the command line prints that, with the fix on the line below. Diagnostic::one_line puts the fix after the headline, for a host that shows each diagnostic as one line of text, as VectorCraft shows an export’s warnings.

Fixes

Fix::Hint(String) is advice. Fix::Apply(Edit) is a change the host can apply with one click and undo (for example “rotate the design 90°” for SC-W0702 when the rotated bounds fit, or “drop the dangling rung” for SC-W0203). Applied fixes go through the host’s command system so they are undoable.

Initial codes

Codes referenced by the design docs; each is registered in the milestone that implements it. A registered code must keep its row here, with the same severity and a title that starts with the registry’s (cargo xtask docs --check), so a code allocated for one thing cannot be registered for another.