@fuzdev/fuz_ui 0.175.0 → 0.176.0

package/dist/tsdoc_helpers.d.ts

@@ -35,6 +35,8 @@
  * - TS API strips URL protocols from `@see` tag text; we use `getText()` to preserve original format including `{@link}` syntax
  *
  * All functions are prefixed with `tsdoc_` for clarity.
+ *
+ * @module
  */
 import ts from 'typescript';
 import type { DeclarationJson } from '@fuzdev/fuz_util/source_json.js';
@@ -95,4 +97,13 @@ export declare const tsdoc_parse: (node: ts.Node, source_file: ts.SourceFile) =>
  * @mutates declaration - adds doc_comment, deprecated_message, examples, see_also, throws, since fields
  */
 export declare const tsdoc_apply_to_declaration: (declaration: DeclarationJson, tsdoc: TsdocParsedComment | undefined) => void;
+/**
+ * Clean raw JSDoc comment text by removing comment markers and leading asterisks.
+ *
+ * Transforms `/** ... *\/` style comments into clean text.
+ *
+ * @param comment_text The raw comment text including `/**` and `*\/` markers
+ * @returns Cleaned comment text, or undefined if empty after cleaning
+ */
+export declare const tsdoc_clean_comment: (comment_text: string) => string | undefined;
 //# sourceMappingURL=tsdoc_helpers.d.ts.map

package/dist/tsdoc_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tsdoc_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IACrD,oCAAoC;IACpC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAiDD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,GACvB,MAAM,EAAE,CAAC,IAAI,EACb,aAAa,EAAE,CAAC,UAAU,KACxB,kBAAkB,GAAG,SAyFvB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GACtC,aAAa,eAAe,EAC5B,OAAO,kBAAkB,GAAG,SAAS,KACnC,IAmBF,CAAC"}
+{"version":3,"file":"tsdoc_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IACrD,oCAAoC;IACpC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,GACvB,MAAM,EAAE,CAAC,IAAI,EACb,aAAa,EAAE,CAAC,UAAU,KACxB,kBAAkB,GAAG,SAyFvB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GACtC,aAAa,eAAe,EAC5B,OAAO,kBAAkB,GAAG,SAAS,KACnC,IAmBF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAI,cAAc,MAAM,KAAG,MAAM,GAAG,SAUnE,CAAC"}

package/dist/tsdoc_helpers.js

@@ -35,53 +35,10 @@
  * - TS API strips URL protocols from `@see` tag text; we use `getText()` to preserve original format including `{@link}` syntax
  *
  * All functions are prefixed with `tsdoc_` for clarity.
- */
-import ts from 'typescript';
-/**
- * Convert TSDoc link syntax to mdz-compatible format.
  *
- * Conversions:
- * - `{@link url|text}` → `[text](url)` (markdown link)
- * - `{@link https://...}` → `https://...` (bare URL)
- * - `{@link identifier}` → `` `identifier` `` (backticks)
- * - `@see` variants follow same rules
- *
- * @param content The @see tag content to convert
+ * @module
  */
-const tsdoc_convert_link_to_mdz = (content) => {
-    // Check for {@link ...} or {@see ...} syntax
-    const link_match = /^\{@(?:link|see)\s+([^}]+)\}$/.exec(content.trim());
-    if (link_match) {
-        const inner = link_match[1].trim();
-        // Check for pipe separator (custom display text)
-        const pipe_index = inner.indexOf('|');
-        if (pipe_index !== -1) {
-            const reference = inner.slice(0, pipe_index).trim();
-            const display_text = inner.slice(pipe_index + 1).trim();
-            // Convert to markdown link: [text](url)
-            return `[${display_text}](${reference})`;
-        }
-        // No pipe - check if it's a URL or declaration
-        if (inner.startsWith('https://') || inner.startsWith('http://')) {
-            // Bare URL - return as-is
-            return inner;
-        }
-        else {
-            // Declaration or module - wrap in backticks
-            return `\`${inner}\``;
-        }
-    }
-    // No {@link} or {@see} syntax - check if it's a bare URL or declaration
-    const trimmed = content.trim();
-    if (trimmed.startsWith('https://') || trimmed.startsWith('http://')) {
-        // Already a bare URL - return as-is
-        return trimmed;
-    }
-    else {
-        // Declaration or module - wrap in backticks
-        return `\`${trimmed}\``;
-    }
-};
+import ts from 'typescript';
 /**
  * Parse JSDoc comment from a TypeScript node.
  *
@@ -160,10 +117,10 @@ export const tsdoc_parse = (node, source_file) => {
             const see_content = full_tag_text
                 .replace(/^@see\s+/, '') // remove @see prefix
                 .replace(/\n\s*\*\s*/g, ' ') // remove JSDoc line continuations
+                .replace(/\s*\*\s*$/, '') // remove trailing asterisk artifacts
                 .trim();
             if (see_content) {
-                // Convert TSDoc link syntax to mdz-compatible format
-                see_also.push(tsdoc_convert_link_to_mdz(see_content));
+                see_also.push(see_content);
             }
         }
         else if (tag_name === 'since' && tag_text) {
@@ -219,3 +176,21 @@ export const tsdoc_apply_to_declaration = (declaration, tsdoc) => {
         declaration.since = tsdoc.since;
     }
 };
+/**
+ * Clean raw JSDoc comment text by removing comment markers and leading asterisks.
+ *
+ * Transforms `/** ... *\/` style comments into clean text.
+ *
+ * @param comment_text The raw comment text including `/**` and `*\/` markers
+ * @returns Cleaned comment text, or undefined if empty after cleaning
+ */
+export const tsdoc_clean_comment = (comment_text) => {
+    const text = comment_text
+        .replace(/^\/\*\*/, '')
+        .replace(/\*\/$/, '')
+        .split('\n')
+        .map((line) => line.replace(/^\s*\*\s?/, ''))
+        .join('\n')
+        .trim();
+    return text || undefined;
+};

package/dist/tsdoc_mdz.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bridge between TSDoc format and mdz for rendering.
+ *
+ * This module converts raw TSDoc syntax (from the analysis library) to mdz format
+ * (Fuz's documentation rendering dialect). It lives in fuz_ui, not the extracted
+ * analysis library, to keep that library format-agnostic.
+ *
+ * @module
+ */
+/**
+ * Convert raw TSDoc `@see` content to mdz format for rendering.
+ *
+ * Handles TSDoc link syntax:
+ * - `{@link url|text}` → `[text](url)` (markdown link)
+ * - `{@link https://...}` → `https://...` (bare URL, auto-linked by mdz)
+ * - `{@link identifier}` → `` `identifier` `` (code formatting)
+ * - Bare URLs → returned as-is
+ * - Bare identifiers → wrapped in backticks
+ *
+ * @param content Raw `@see` tag content in TSDoc format
+ * @returns mdz-formatted string ready for `<Mdz>` component
+ *
+ * @example
+ * ```ts
+ * tsdoc_see_to_mdz('{@link https://fuz.dev|API Docs}')
+ * // → '[API Docs](https://fuz.dev)'
+ *
+ * tsdoc_see_to_mdz('{@link SomeType}')
+ * // → '`SomeType`'
+ *
+ * tsdoc_see_to_mdz('https://example.com')
+ * // → 'https://example.com'
+ * ```
+ */
+export declare const tsdoc_see_to_mdz: (content: string) => string;
+//# sourceMappingURL=tsdoc_mdz.d.ts.map

package/dist/tsdoc_mdz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsdoc_mdz.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc_mdz.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,KAAG,MAqBlD,CAAC"}

package/dist/tsdoc_mdz.js

@@ -0,0 +1,56 @@
+/**
+ * Bridge between TSDoc format and mdz for rendering.
+ *
+ * This module converts raw TSDoc syntax (from the analysis library) to mdz format
+ * (Fuz's documentation rendering dialect). It lives in fuz_ui, not the extracted
+ * analysis library, to keep that library format-agnostic.
+ *
+ * @module
+ */
+import { mdz_is_url } from './mdz.js';
+/** Format a reference as mdz: URLs pass through, identifiers get backticks. */
+const format_reference = (ref) => (mdz_is_url(ref) ? ref : `\`${ref}\``);
+/**
+ * Convert raw TSDoc `@see` content to mdz format for rendering.
+ *
+ * Handles TSDoc link syntax:
+ * - `{@link url|text}` → `[text](url)` (markdown link)
+ * - `{@link https://...}` → `https://...` (bare URL, auto-linked by mdz)
+ * - `{@link identifier}` → `` `identifier` `` (code formatting)
+ * - Bare URLs → returned as-is
+ * - Bare identifiers → wrapped in backticks
+ *
+ * @param content Raw `@see` tag content in TSDoc format
+ * @returns mdz-formatted string ready for `<Mdz>` component
+ *
+ * @example
+ * ```ts
+ * tsdoc_see_to_mdz('{@link https://fuz.dev|API Docs}')
+ * // → '[API Docs](https://fuz.dev)'
+ *
+ * tsdoc_see_to_mdz('{@link SomeType}')
+ * // → '`SomeType`'
+ *
+ * tsdoc_see_to_mdz('https://example.com')
+ * // → 'https://example.com'
+ * ```
+ */
+export const tsdoc_see_to_mdz = (content) => {
+    const trimmed = content.trim();
+    if (!trimmed)
+        return '';
+    // Check for {@link ...} or {@see ...} syntax
+    const link_match = /^\{@(?:link|see)\s+([^}]+)\}$/.exec(trimmed);
+    if (link_match) {
+        const inner = link_match[1].trim();
+        // Check for pipe separator (custom display text)
+        const pipe_index = inner.indexOf('|');
+        if (pipe_index !== -1) {
+            const reference = inner.slice(0, pipe_index).trim();
+            const display_text = inner.slice(pipe_index + 1).trim();
+            return `[${display_text}](${reference})`;
+        }
+        return format_reference(inner);
+    }
+    return format_reference(trimmed);
+};

package/dist/vite_plugin_library_well_known.js

@@ -51,19 +51,19 @@ export const vite_plugin_library_well_known = (options = {}) => {
         try {
             json_content = await readFile(resolved_path, 'utf-8');
         }
-        catch (err) {
+        catch (error) {
             throw new Error(`vite_plugin_library_well_known: failed to read library.json from "${library_path}"\n` +
                 `Resolved to: ${resolved_path}\n` +
                 `Make sure you've run \`gro gen\` to generate the library metadata.\n` +
-                `Error: ${err}`);
+                `Error: ${error}`);
         }
         let raw;
         try {
             raw = JSON.parse(json_content);
         }
-        catch (err) {
+        catch (error) {
             throw new Error(`vite_plugin_library_well_known: failed to parse library.json from "${library_path}"\n` +
-                `Error: ${err}`);
+                `Error: ${error}`);
         }
         // Basic structure validation (file is generated by library_gen)
         if (raw == null || typeof raw !== 'object') {
@@ -107,7 +107,7 @@ export const vite_plugin_library_well_known = (options = {}) => {
                         throw new Error('not initialized');
                     await ready_promise;
                 }
-                catch {
+                catch (_error) {
                     res.statusCode = 503;
                     respond_json(res, JSON.stringify({ error: 'Library not ready' }));
                     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_ui",
-  "version": "0.175.0",
+  "version": "0.176.0",
   "description": "Svelte UI library",
   "motto": "friendly user zystem",
   "glyph": "🧶",
@@ -37,6 +37,7 @@
     "@fuzdev/fuz_code": ">=0.37.0",
     "@fuzdev/fuz_css": ">=0.40.0",
     "@fuzdev/fuz_util": ">=0.42.0",
+    "@jridgewell/trace-mapping": "^0.3",
     "@ryanatkn/gro": ">=0.183.0",
     "@sveltejs/kit": "^2.47.3",
     "esm-env": "^1",
@@ -48,6 +49,9 @@
     "@fuzdev/fuz_code": {
       "optional": true
     },
+    "@jridgewell/trace-mapping": {
+      "optional": true
+    },
     "@ryanatkn/gro": {
       "optional": true
     },
@@ -60,6 +64,7 @@
     "@fuzdev/fuz_code": "^0.38.0",
     "@fuzdev/fuz_css": "^0.42.1",
     "@fuzdev/fuz_util": "^0.45.1",
+    "@jridgewell/trace-mapping": "^0.3.31",
     "@ryanatkn/eslint-config": "^0.9.0",
     "@ryanatkn/gro": "^0.183.0",
     "@sveltejs/adapter-static": "^3.0.10",
@@ -71,11 +76,11 @@
     "eslint-plugin-svelte": "^3.13.1",
     "esm-env": "^1.2.2",
     "jsdom": "^27.2.0",
-    "prettier": "^3.6.2",
-    "prettier-plugin-svelte": "^3.4.0",
-    "svelte": "^5.45.6",
-    "svelte-check": "^4.3.4",
-    "svelte2tsx": "^0.7.45",
+    "prettier": "^3.7.4",
+    "prettier-plugin-svelte": "^3.4.1",
+    "svelte": "^5.46.1",
+    "svelte-check": "^4.3.5",
+    "svelte2tsx": "^0.7.46",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.1",

package/src/lib/analysis_context.ts

@@ -0,0 +1,250 @@
+/**
+ * Diagnostic collection for source analysis.
+ *
+ * Provides structured error/warning collection during TypeScript and Svelte
+ * analysis, replacing silent catch blocks with actionable diagnostics.
+ *
+ * ## Error Handling Contract
+ *
+ * Analysis functions follow a two-tier error model:
+ *
+ * **Accumulated (non-fatal)** - Collected in AnalysisContext, analysis continues:
+ * - Type resolution failures (complex generics, circular refs)
+ * - Missing or unparseable JSDoc
+ * - Individual member/prop extraction failures
+ * - The return value is still valid but may have partial data
+ *
+ * **Thrown (fatal)** - Analysis cannot continue for this file:
+ * - File not found or unreadable
+ * - Syntax errors preventing parsing
+ * - svelte2tsx transformation failures
+ * - Svelte version incompatibility
+ *
+ * ## Usage Pattern
+ *
+ * ```ts
+ * const ctx = new AnalysisContext();
+ * const results = files.map(f => {
+ *   try {
+ *     return library_analyze_module(f, program, options, ctx);
+ *   } catch (e) {
+ *     // Fatal error - log and skip this file
+ *     console.error(`Failed to analyze ${f.id}: ${e}`);
+ *     return null;
+ *   }
+ * });
+ *
+ * // Results are valid even with accumulated errors
+ * // Check ctx for diagnostics to display to user
+ * if (ctx.has_errors()) {
+ *   for (const err of ctx.errors()) {
+ *     console.error(format_diagnostic(err));
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * const ctx = new AnalysisContext();
+ * // ... analysis functions add diagnostics via ctx.add(...)
+ * if (ctx.has_errors()) {
+ *   for (const err of ctx.errors()) {
+ *     console.error(`${err.file}:${err.line}: ${err.message}`);
+ *   }
+ * }
+ *
+ * @module
+ */
+
+/**
+ * Diagnostic severity levels.
+ *
+ * - `error`: Analysis failed, declaration may be incomplete or missing data
+ * - `warning`: Partial success, something seems off but analysis continued
+ */
+export type DiagnosticSeverity = 'error' | 'warning';
+
+/**
+ * Discriminant for diagnostic types.
+ */
+export type DiagnosticKind =
+	| 'type_extraction_failed'
+	| 'signature_analysis_failed'
+	| 'class_member_failed'
+	| 'svelte_prop_failed'
+	| 'module_skipped';
+
+/**
+ * Base diagnostic fields shared by all diagnostic types.
+ */
+export interface BaseDiagnostic {
+	kind: DiagnosticKind;
+	/** File path relative to project root (display with './' prefix). */
+	file: string;
+	/** Line number (1-based), or null if location unavailable. */
+	line: number | null;
+	/** Column number (1-based), or null if location unavailable. */
+	column: number | null;
+	/** Human-readable description of the issue. */
+	message: string;
+	severity: DiagnosticSeverity;
+}
+
+/**
+ * Type extraction failed (e.g., complex or recursive types).
+ */
+export interface TypeExtractionDiagnostic extends BaseDiagnostic {
+	kind: 'type_extraction_failed';
+	/** Name of the symbol whose type couldn't be extracted. */
+	symbol_name: string;
+}
+
+/**
+ * Function/method signature analysis failed.
+ */
+export interface SignatureAnalysisDiagnostic extends BaseDiagnostic {
+	kind: 'signature_analysis_failed';
+	/** Name of the function or method. */
+	function_name: string;
+}
+
+/**
+ * Class member analysis failed.
+ */
+export interface ClassMemberDiagnostic extends BaseDiagnostic {
+	kind: 'class_member_failed';
+	/** Name of the class. */
+	class_name: string;
+	/** Name of the member that failed. */
+	member_name: string;
+}
+
+/**
+ * Svelte prop type resolution failed.
+ */
+export interface SveltePropDiagnostic extends BaseDiagnostic {
+	kind: 'svelte_prop_failed';
+	/** Name of the component. */
+	component_name: string;
+	/** Name of the prop. */
+	prop_name: string;
+}
+
+/**
+ * Module was skipped during analysis.
+ * Could be due to missing source file in program or no analyzer available.
+ */
+export interface ModuleSkippedDiagnostic extends BaseDiagnostic {
+	kind: 'module_skipped';
+	/** Reason the module was skipped. */
+	reason: 'not_in_program' | 'no_analyzer';
+}
+
+/**
+ * Union of all diagnostic types.
+ */
+export type Diagnostic =
+	| TypeExtractionDiagnostic
+	| SignatureAnalysisDiagnostic
+	| ClassMemberDiagnostic
+	| SveltePropDiagnostic
+	| ModuleSkippedDiagnostic;
+
+/**
+ * Context for collecting diagnostics during source analysis.
+ *
+ * Thread an instance through analysis functions to collect errors and warnings
+ * without halting analysis. After analysis completes, check `has_errors()` and
+ * report collected diagnostics.
+ *
+ * @example
+ * const ctx = new AnalysisContext();
+ * ts_analyze_module_exports(source_file, checker, options, ctx);
+ * if (ctx.has_errors()) {
+ *   console.error('Analysis completed with errors:');
+ *   for (const d of ctx.errors()) {
+ *     console.error(format_diagnostic(d));
+ *   }
+ * }
+ */
+export class AnalysisContext {
+	readonly diagnostics: Array<Diagnostic> = [];
+
+	/**
+	 * Add a diagnostic to the collection.
+	 */
+	add(diagnostic: Diagnostic): void {
+		this.diagnostics.push(diagnostic);
+	}
+
+	/**
+	 * Check if any errors were collected.
+	 */
+	has_errors(): boolean {
+		return this.diagnostics.some((d) => d.severity === 'error');
+	}
+
+	/**
+	 * Check if any warnings were collected.
+	 */
+	has_warnings(): boolean {
+		return this.diagnostics.some((d) => d.severity === 'warning');
+	}
+
+	/**
+	 * Get all error diagnostics.
+	 */
+	errors(): Array<Diagnostic> {
+		return this.diagnostics.filter((d) => d.severity === 'error');
+	}
+
+	/**
+	 * Get all warning diagnostics.
+	 */
+	warnings(): Array<Diagnostic> {
+		return this.diagnostics.filter((d) => d.severity === 'warning');
+	}
+
+	/**
+	 * Get diagnostics of a specific kind.
+	 */
+	by_kind<K extends DiagnosticKind>(kind: K): Array<Extract<Diagnostic, {kind: K}>> {
+		return this.diagnostics.filter((d) => d.kind === kind) as Array<Extract<Diagnostic, {kind: K}>>;
+	}
+}
+
+/**
+ * Options for formatting diagnostics.
+ */
+export interface FormatDiagnosticOptions {
+	/** Prefix for file path (default: './'). */
+	prefix?: string;
+	/** Base path to strip from absolute file paths (e.g., process.cwd()). */
+	strip_base?: string;
+}
+
+/**
+ * Format a diagnostic for display.
+ *
+ * @param diagnostic The diagnostic to format
+ * @param options Formatting options
+ * @returns Formatted string like './file.ts:10:5: error: message'
+ */
+export const format_diagnostic = (
+	diagnostic: Diagnostic,
+	options?: FormatDiagnosticOptions,
+): string => {
+	const prefix = options?.prefix ?? './';
+	const strip_base = options?.strip_base;
+
+	let file = diagnostic.file;
+	if (strip_base && file.startsWith(strip_base)) {
+		file = file.slice(strip_base.length);
+		// Remove leading slash if present
+		if (file.startsWith('/')) file = file.slice(1);
+	}
+
+	const {line, column, severity, message} = diagnostic;
+	const location = line !== null ? (column !== null ? `${line}:${column}` : `${line}`) : '';
+	const file_part = location ? `${prefix}${file}:${location}` : `${prefix}${file}`;
+	return `${file_part}: ${severity}: ${message}`;
+};