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

src/span.h

@@ -0,0 +1,33 @@
+#ifndef ST_SPAN_H
+#define ST_SPAN_H
+
+#include <stddef.h>
+#include <stdio.h>
+
+/*
+ * A source span: 1-based line/column into a source file.
+ * `file` is borrowed (never freed); typically points into stable
+ * storage such as a file-name arena or a string literal.
+ */
+struct st_span {
+    const char *file;
+    size_t line;
+    size_t col;
+};
+
+/*
+ * Renders the canonical two-line diagnostic:
+ *
+ *   <file>:<line>:<col>: <message>
+ *       ...^
+ *
+ * The caret line is a fixed 4-space indent followed by a "..."
+ * elision marker and the caret. For the canonical span (col 5)
+ * this is exactly "    ...^"; the caret shifts right for larger
+ * columns and is capped so hostile spans cannot force unbounded
+ * output. NULL arguments are tolerated and render nothing.
+ */
+void st_span_print(FILE *out, const struct st_span *span,
+                   const char *message);
+
+#endif