feat(error): add typed errors + source-span diagnostics

src/span.c

@@ -0,0 +1,33 @@
+#include "span.h"
+
+/* C23 only: ISO/IEC 9899:2024. */
+#define ST_SPAN_CARET_PAD_CAP 60
+
+void
+st_span_print(FILE *out, const struct st_span *span, const char *message)
+{
+    size_t pad;
+
+    if (out == NULL || span == NULL || span->file == NULL ||
+        message == NULL) {
+        return;
+    }
+    fprintf(out, "%s:%zu:%zu: %s\n", span->file, span->line, span->col,
+            message);
+    /*
+     * Caret line: 4-space indent, "..." elision, caret. The caret sits
+     * three cells past the reported column (the elision marker occupies
+     * those cells), so col 5 renders exactly "    ...^". Columns below
+     * 5 collapse onto the elision; columns above 5 push the caret right,
+     * capped to keep the line bounded.
+     */
+    fputs("    ...", out);
+    pad = span->col > 5 ? span->col - 5 : 0;
+    if (pad > ST_SPAN_CARET_PAD_CAP) {
+        pad = ST_SPAN_CARET_PAD_CAP;
+    }
+    while (pad-- > 0) {
+        fputc(' ', out);
+    }
+    fputs("^\n", out);
+}