@fuzdev/fuz_ui 0.194.0 → 0.195.0

package/dist/tsdoc_helpers.d.ts

@@ -1,119 +0,0 @@
-/**
- * TSDoc/JSDoc parsing helpers using the TypeScript Compiler API.
- *
- * Provides `tsdoc_parse()` for extracting JSDoc/TSDoc from TypeScript nodes.
- * Primarily designed for build-time code generation but can be used at runtime.
- *
- * ## Design
- *
- * Pure extraction approach: extracts documentation as-is with minimal transformation,
- * preserving source intent. Works around TypeScript Compiler API quirks where needed.
- *
- * Supports both regular TypeScript and Svelte components (via svelte2tsx output).
- *
- * ## Tag support
- *
- * Supports a subset of standard TSDoc tags:
- * `@param`, `@returns`, `@throws`, `@example`, `@deprecated`, `@see`, `@since`, `@nodocs`.
- *
- * The `@nodocs` tag excludes exports from documentation and flat namespace validation.
- * The declaration is still exported and usable, just not documented.
- *
- * Also supports `@mutates` (non-standard) for documenting mutations to parameters or external state.
- * Use format: `@mutates paramName - description of mutation`.
- *
- * Only `@returns` is supported (not `@return`).
- *
- * The `@see` tag supports multiple formats: plain URLs (`https://...`), `{@link}` syntax, and module names.
- * Relative/absolute path support in `@see` is TBD.
- *
- * ## Behavioral notes
- *
- * Due to TS Compiler API limitations:
- * - `@param` and `@mutates` descriptions have leading `- ` stripped for visual consistency
- *   (TSDoc spec uses `@param name - description` but the separator is aesthetic)
- * - `@throws` tags have `{Type}` stripped by TS API; fallback regex extracts first word as error type
- * - 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';
-/**
- * Parsed JSDoc/TSDoc comment with structured metadata.
- */
-export interface TsdocParsedComment {
-    /** Comment text (excluding comment markers) */
-    text: string;
-    /** Parameter descriptions mapped by parameter name */
-    params: Map<string, string>;
-    /** Return value description from `@returns` */
-    returns?: string;
-    /** Thrown errors from `@throws` */
-    throws?: Array<{
-        type?: string;
-        description: string;
-    }>;
-    /** Code examples from `@example` */
-    examples?: Array<string>;
-    /** Deprecation message from `@deprecated` */
-    deprecated_message?: string;
-    /** Related references from `@see` */
-    see_also?: Array<string>;
-    /** Version information from `@since` */
-    since?: string;
-    /** Mutation documentation from `@mutates` (non-standard) */
-    mutates?: Array<string>;
-    /** Whether to exclude from documentation. From `@nodocs` tag. */
-    nodocs?: boolean;
-}
-/**
- * Parse JSDoc comment from a TypeScript node.
- *
- * Extracts and parses all JSDoc tags including:
- *
- * - `@param` - parameter descriptions
- * - `@returns` - return value description
- * - `@throws` - error documentation
- * - `@example` - code examples
- * - `@deprecated` - deprecation warnings
- * - `@see` - related references
- * - `@since` - version information
- * - `@mutates` - mutation documentation (non-standard)
- *
- * @param node - the TypeScript node to extract JSDoc from
- * @param source_file - source file (used for extracting full ` @see` tag text)
- */
-export declare const tsdoc_parse: (node: ts.Node, source_file: ts.SourceFile) => TsdocParsedComment | undefined;
-/**
- * Apply parsed TSDoc metadata to a declaration.
- *
- * Consolidates the common pattern of assigning TSDoc fields to declarations,
- * with conditional assignment for array fields (only if non-empty).
- *
- * @param declaration - declaration object to update
- * @param tsdoc - parsed TSDoc comment (if available)
- * @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;
-/**
- * Concatenates a JSDoc comment (string or node array) into plain text, preserving `{@link ...}`.
- *
- * `JSDocLink` / `JSDocLinkCode` / `JSDocLinkPlain` nodes have empty `.text` — the identifier
- * lives on `.name`, not `.text`. Using `.text` alone silently drops link content; we fall back
- * to the source-text representation for link nodes so `{@link Foo}` survives intact for downstream
- * renderers (see `tsdoc_mdz.ts`).
- */
-export declare const tsdoc_comment_to_text: (comment: string | ts.NodeArray<ts.JSDocComment>, source_file: ts.SourceFile) => string;
-/**
- * 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 +0,0 @@
-{"version":3,"file":"tsdoc_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;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,SAoFvB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GACtC,aAAa,eAAe,EAC5B,OAAO,kBAAkB,GAAG,SAAS,KACnC,IAmBF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,MAAM,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,YAAY,CAAC,EAC/C,aAAa,EAAE,CAAC,UAAU,KACxB,MAGF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAI,cAAc,MAAM,KAAG,MAAM,GAAG,SAUnE,CAAC"}

package/dist/tsdoc_helpers.js

@@ -1,207 +0,0 @@
-/**
- * TSDoc/JSDoc parsing helpers using the TypeScript Compiler API.
- *
- * Provides `tsdoc_parse()` for extracting JSDoc/TSDoc from TypeScript nodes.
- * Primarily designed for build-time code generation but can be used at runtime.
- *
- * ## Design
- *
- * Pure extraction approach: extracts documentation as-is with minimal transformation,
- * preserving source intent. Works around TypeScript Compiler API quirks where needed.
- *
- * Supports both regular TypeScript and Svelte components (via svelte2tsx output).
- *
- * ## Tag support
- *
- * Supports a subset of standard TSDoc tags:
- * `@param`, `@returns`, `@throws`, `@example`, `@deprecated`, `@see`, `@since`, `@nodocs`.
- *
- * The `@nodocs` tag excludes exports from documentation and flat namespace validation.
- * The declaration is still exported and usable, just not documented.
- *
- * Also supports `@mutates` (non-standard) for documenting mutations to parameters or external state.
- * Use format: `@mutates paramName - description of mutation`.
- *
- * Only `@returns` is supported (not `@return`).
- *
- * The `@see` tag supports multiple formats: plain URLs (`https://...`), `{@link}` syntax, and module names.
- * Relative/absolute path support in `@see` is TBD.
- *
- * ## Behavioral notes
- *
- * Due to TS Compiler API limitations:
- * - `@param` and `@mutates` descriptions have leading `- ` stripped for visual consistency
- *   (TSDoc spec uses `@param name - description` but the separator is aesthetic)
- * - `@throws` tags have `{Type}` stripped by TS API; fallback regex extracts first word as error type
- * - 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';
-/**
- * Parse JSDoc comment from a TypeScript node.
- *
- * Extracts and parses all JSDoc tags including:
- *
- * - `@param` - parameter descriptions
- * - `@returns` - return value description
- * - `@throws` - error documentation
- * - `@example` - code examples
- * - `@deprecated` - deprecation warnings
- * - `@see` - related references
- * - `@since` - version information
- * - `@mutates` - mutation documentation (non-standard)
- *
- * @param node - the TypeScript node to extract JSDoc from
- * @param source_file - source file (used for extracting full ` @see` tag text)
- */
-export const tsdoc_parse = (node, source_file) => {
-    const tsdoc_comments = ts.getJSDocCommentsAndTags(node);
-    if (tsdoc_comments.length === 0)
-        return undefined;
-    let full_text = '';
-    const params = new Map();
-    let returns;
-    const throws = [];
-    const examples = [];
-    let deprecated_message;
-    const see_also = [];
-    let since;
-    const mutates = [];
-    let nodocs = false;
-    // Extract main comment text
-    for (const comment of tsdoc_comments) {
-        if (ts.isJSDoc(comment) && comment.comment) {
-            full_text += tsdoc_comment_to_text(comment.comment, source_file) + '\n';
-        }
-    }
-    // Extract tags
-    const tags = ts.getJSDocTags(node);
-    for (const tag of tags) {
-        const tag_text = tag.comment ? tsdoc_comment_to_text(tag.comment, source_file) : undefined;
-        const tag_name = tag.tagName.text;
-        if (tag_name === 'param' && ts.isJSDocParameterTag(tag)) {
-            // Extract parameter name and description
-            const param_name = ts.isIdentifier(tag.name) ? tag.name.text : tag.name.getText();
-            if (param_name && tag_text) {
-                params.set(param_name, tag_text.trim().replace(/^-\s+/, ''));
-            }
-        }
-        else if (tag_name === 'returns' && tag_text) {
-            returns = tag_text.trim();
-        }
-        else if (tag_name === 'throws' && tag_text) {
-            // Try to extract error type and description
-            const match = /^\{?(\w+)\}?\s+(.+)/.exec(tag_text);
-            if (match) {
-                throws.push({ type: match[1], description: match[2].trim() });
-            }
-            else {
-                throws.push({ description: tag_text.trim() });
-            }
-        }
-        else if (tag_name === 'example' && tag_text) {
-            examples.push(tag_text.trim());
-        }
-        else if (tag_name === 'deprecated' && tag_text) {
-            deprecated_message = tag_text.trim();
-        }
-        else if (tag_name === 'see') {
-            // The TS API strips 'https' from URLs in @see tags, so get full text from source
-            const full_tag_text = tag.getText(source_file);
-            // Extract content after @see, handling JSDoc formatting artifacts
-            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) {
-                see_also.push(see_content);
-            }
-        }
-        else if (tag_name === 'since' && tag_text) {
-            since = tag_text.trim();
-        }
-        else if (tag_name === 'mutates' && tag_text) {
-            mutates.push(tag_text.trim().replace(/^-\s+/, ''));
-        }
-        else if (tag_name === 'nodocs') {
-            nodocs = true;
-        }
-    }
-    full_text = full_text.trim();
-    return {
-        text: full_text,
-        params,
-        returns,
-        ...(throws.length && { throws }),
-        ...(examples.length && { examples }),
-        deprecated_message,
-        ...(see_also.length && { see_also }),
-        since,
-        ...(mutates.length && { mutates }),
-        ...(nodocs && { nodocs }),
-    };
-};
-/**
- * Apply parsed TSDoc metadata to a declaration.
- *
- * Consolidates the common pattern of assigning TSDoc fields to declarations,
- * with conditional assignment for array fields (only if non-empty).
- *
- * @param declaration - declaration object to update
- * @param tsdoc - parsed TSDoc comment (if available)
- * @mutates declaration - adds doc_comment, deprecated_message, examples, see_also, throws, since fields
- */
-export const tsdoc_apply_to_declaration = (declaration, tsdoc) => {
-    if (!tsdoc)
-        return;
-    declaration.doc_comment = tsdoc.text;
-    declaration.deprecated_message = tsdoc.deprecated_message;
-    // Only assign arrays if they have content
-    if (tsdoc.examples?.length) {
-        declaration.examples = tsdoc.examples;
-    }
-    if (tsdoc.see_also?.length) {
-        declaration.see_also = tsdoc.see_also;
-    }
-    if (tsdoc.throws?.length) {
-        declaration.throws = tsdoc.throws;
-    }
-    if (tsdoc.since) {
-        declaration.since = tsdoc.since;
-    }
-};
-/**
- * Concatenates a JSDoc comment (string or node array) into plain text, preserving `{@link ...}`.
- *
- * `JSDocLink` / `JSDocLinkCode` / `JSDocLinkPlain` nodes have empty `.text` — the identifier
- * lives on `.name`, not `.text`. Using `.text` alone silently drops link content; we fall back
- * to the source-text representation for link nodes so `{@link Foo}` survives intact for downstream
- * renderers (see `tsdoc_mdz.ts`).
- */
-export const tsdoc_comment_to_text = (comment, source_file) => {
-    if (typeof comment === 'string')
-        return comment;
-    return comment.map((c) => (ts.isJSDocLinkLike(c) ? c.getText(source_file) : c.text)).join('');
-};
-/**
- * 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/src/lib/analysis_context.ts

@@ -1,254 +0,0 @@
-/**
- * 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
- * ```ts
- * 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
- * ```ts
- * 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 `DiagnosticKind`.
-	 */
-	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}`;
-};