@fuzdev/fuz_util 0.55.0 → 0.56.0

package/dist/source_json.d.ts

@@ -5,7 +5,7 @@
  * extracted at build time via TypeScript compiler analysis.
  * Used for generating API documentation and enabling code search.
  *
- * Hierarchy: SourceJson → ModuleJson → DeclarationJson
+ * Hierarchy: `SourceJson` → `ModuleJson` → `DeclarationJson`
  *
  * @module
  */
@@ -39,7 +39,7 @@ export type GenericParamInfo = z.infer<typeof GenericParamInfo>;
 /**
  * Parameter information for functions and methods.
  *
- * Kept distinct from ComponentPropInfo despite structural similarity.
+ * Kept distinct from `ComponentPropInfo` despite structural similarity.
  * Function parameters form a tuple with positional semantics:
  * calling order matters (`fn(a, b)` vs `fn(b, a)`),
  * may include rest parameters and destructuring patterns.
@@ -55,7 +55,7 @@ export type ParameterInfo = z.infer<typeof ParameterInfo>;
 /**
  * Component prop information for Svelte components.
  *
- * Kept distinct from ParameterInfo despite structural similarity.
+ * Kept distinct from `ParameterInfo` despite structural similarity.
  * Component props are named attributes with different semantics:
  * no positional order when passing (`<Foo {a} {b} />` = `<Foo {b} {a} />`),
  * support two-way binding via `$bindable` rune.

package/dist/source_json.js

@@ -5,7 +5,7 @@
  * extracted at build time via TypeScript compiler analysis.
  * Used for generating API documentation and enabling code search.
  *
- * Hierarchy: SourceJson → ModuleJson → DeclarationJson
+ * Hierarchy: `SourceJson` → `ModuleJson` → `DeclarationJson`
  *
  * @module
  */
@@ -37,7 +37,7 @@ export const GenericParamInfo = z.looseObject({
 /**
  * Parameter information for functions and methods.
  *
- * Kept distinct from ComponentPropInfo despite structural similarity.
+ * Kept distinct from `ComponentPropInfo` despite structural similarity.
  * Function parameters form a tuple with positional semantics:
  * calling order matters (`fn(a, b)` vs `fn(b, a)`),
  * may include rest parameters and destructuring patterns.
@@ -52,7 +52,7 @@ export const ParameterInfo = z.looseObject({
 /**
  * Component prop information for Svelte components.
  *
- * Kept distinct from ParameterInfo despite structural similarity.
+ * Kept distinct from `ParameterInfo` despite structural similarity.
  * Component props are named attributes with different semantics:
  * no positional order when passing (`<Foo {a} {b} />` = `<Foo {b} {a} />`),
  * support two-way binding via `$bindable` rune.

package/dist/stats.d.ts

@@ -26,8 +26,8 @@ export declare const stats_variance: (values: Array<number>, mean?: number) => n
  * Calculate a percentile of an array of numbers using linear interpolation.
  * Uses the "R-7" method (default in R, NumPy, Excel) which interpolates between
  * data points for more accurate percentile estimates, especially with smaller samples.
- * @param values - Array of numbers
- * @param p - Percentile (0-1, e.g., 0.95 for 95th percentile)
+ * @param values - array of numbers
+ * @param p - percentile (0-1, e.g., 0.95 for 95th percentile)
  */
 export declare const stats_percentile: (values: Array<number>, p: number) => number;
 /**
@@ -120,18 +120,18 @@ export interface StatsConfidenceIntervalOptions {
 }
 /**
  * Calculate confidence interval for the mean.
- * @param values - Array of numbers
- * @param options - Configuration options
+ * @param values - array of numbers
+ * @param options - configuration options
  * @returns [lower_bound, upper_bound]
  */
 export declare const stats_confidence_interval: (values: Array<number>, options?: StatsConfidenceIntervalOptions) => [number, number];
 /**
  * Calculate confidence interval from summary statistics (mean, std_dev, sample_size).
  * Useful when raw data is not available.
- * @param mean - Mean of the data
- * @param std_dev - Standard deviation of the data
- * @param sample_size - Number of samples
- * @param options - Configuration options
+ * @param mean - mean of the data
+ * @param std_dev - standard deviation of the data
+ * @param sample_size - number of samples
+ * @param options - configuration options
  * @returns [lower_bound, upper_bound]
  */
 export declare const stats_confidence_interval_from_summary: (mean: number, std_dev: number, sample_size: number, options?: StatsConfidenceIntervalOptions) => [number, number];
@@ -148,12 +148,12 @@ export interface StatsWelchTTestResult {
  * Calculate Welch's t-test statistic and degrees of freedom.
  * Welch's t-test is more robust than Student's t-test when variances are unequal.
  *
- * @param mean1 - Mean of first sample
- * @param std1 - Standard deviation of first sample
- * @param n1 - Size of first sample
- * @param mean2 - Mean of second sample
- * @param std2 - Standard deviation of second sample
- * @param n2 - Size of second sample
+ * @param mean1 - mean of first sample
+ * @param std1 - standard deviation of first sample
+ * @param n1 - size of first sample
+ * @param mean2 - mean of second sample
+ * @param std2 - standard deviation of second sample
+ * @param n2 - size of second sample
  */
 export declare const stats_welch_t_test: (mean1: number, std1: number, n1: number, mean2: number, std2: number, n2: number) => StatsWelchTTestResult;
 /**
@@ -174,9 +174,9 @@ export declare const stats_incomplete_beta: (x: number, a: number, b: number) =>
  * For large df (>100), uses normal approximation.
  * For smaller df, uses incomplete beta function.
  *
- * @param t - Absolute value of t-statistic
- * @param df - Degrees of freedom
- * @returns Two-tailed p-value
+ * @param t - absolute value of t-statistic
+ * @param df - degrees of freedom
+ * @returns two-tailed p-value
  */
 export declare const stats_t_distribution_p_value: (t: number, df: number) => number;
 //# sourceMappingURL=stats.d.ts.map

package/dist/stats.js

@@ -57,8 +57,8 @@ export const stats_variance = (values, mean) => {
  * Calculate a percentile of an array of numbers using linear interpolation.
  * Uses the "R-7" method (default in R, NumPy, Excel) which interpolates between
  * data points for more accurate percentile estimates, especially with smaller samples.
- * @param values - Array of numbers
- * @param p - Percentile (0-1, e.g., 0.95 for 95th percentile)
+ * @param values - array of numbers
+ * @param p - percentile (0-1, e.g., 0.95 for 95th percentile)
  */
 export const stats_percentile = (values, p) => {
     if (values.length === 0)
@@ -245,8 +245,8 @@ export const stats_confidence_level_to_z_score = (level) => {
 };
 /**
  * Calculate confidence interval for the mean.
- * @param values - Array of numbers
- * @param options - Configuration options
+ * @param values - array of numbers
+ * @param options - configuration options
  * @returns [lower_bound, upper_bound]
  */
 export const stats_confidence_interval = (values, options) => {
@@ -259,10 +259,10 @@ export const stats_confidence_interval = (values, options) => {
 /**
  * Calculate confidence interval from summary statistics (mean, std_dev, sample_size).
  * Useful when raw data is not available.
- * @param mean - Mean of the data
- * @param std_dev - Standard deviation of the data
- * @param sample_size - Number of samples
- * @param options - Configuration options
+ * @param mean - mean of the data
+ * @param std_dev - standard deviation of the data
+ * @param sample_size - number of samples
+ * @param options - configuration options
  * @returns [lower_bound, upper_bound]
  */
 export const stats_confidence_interval_from_summary = (mean, std_dev, sample_size, options) => {
@@ -282,12 +282,12 @@ export const stats_confidence_interval_from_summary = (mean, std_dev, sample_siz
  * Calculate Welch's t-test statistic and degrees of freedom.
  * Welch's t-test is more robust than Student's t-test when variances are unequal.
  *
- * @param mean1 - Mean of first sample
- * @param std1 - Standard deviation of first sample
- * @param n1 - Size of first sample
- * @param mean2 - Mean of second sample
- * @param std2 - Standard deviation of second sample
- * @param n2 - Size of second sample
+ * @param mean1 - mean of first sample
+ * @param std1 - standard deviation of first sample
+ * @param n1 - size of first sample
+ * @param mean2 - mean of second sample
+ * @param std2 - standard deviation of second sample
+ * @param n2 - size of second sample
  */
 export const stats_welch_t_test = (mean1, std1, n1, mean2, std2, n2) => {
     const var1 = std1 ** 2;
@@ -386,9 +386,9 @@ export const stats_incomplete_beta = (x, a, b) => {
  * For large df (>100), uses normal approximation.
  * For smaller df, uses incomplete beta function.
  *
- * @param t - Absolute value of t-statistic
- * @param df - Degrees of freedom
- * @returns Two-tailed p-value
+ * @param t - absolute value of t-statistic
+ * @param df - degrees of freedom
+ * @returns two-tailed p-value
  */
 export const stats_t_distribution_p_value = (t, df) => {
     // Use normal approximation for large df

package/dist/string.d.ts

@@ -39,7 +39,7 @@ export declare const plural: (count: number | undefined | null, suffix?: string)
  */
 export declare const count_graphemes: (str: string) => number;
 /**
- * Strips ANSI escape sequences from a string
+ * Strips ANSI escape sequences from a string.
  */
 export declare const strip_ansi: (str: string) => string;
 /**
@@ -65,9 +65,9 @@ export declare const pad_width: (str: string, target_width: number, align?: "lef
  * Calculates the Levenshtein distance between two strings.
  * Useful for typo detection and fuzzy matching.
  *
- * @param a - First string
- * @param b - Second string
- * @returns The edit distance between the strings
+ * @param a - first string
+ * @param b - second string
+ * @returns the edit distance between the strings
  */
 export declare const levenshtein_distance: (a: string, b: string) => number;
 /**
@@ -82,8 +82,8 @@ export declare const escape_js_string: (value: string) => string;
  *
  * Checks for null bytes in the first 8KB of content.
  *
- * @param content - Content to check.
- * @returns True if content appears to be binary.
+ * @param content - content to check
+ * @returns true if content appears to be binary
  */
 export declare const string_is_binary: (content: string) => boolean;
 //# sourceMappingURL=string.d.ts.map

package/dist/string.js

@@ -81,7 +81,7 @@ export const plural = (count, suffix = 's') => count === 1 ? '' : suffix;
  */
 export const count_graphemes = (str) => count_iterator(new Intl.Segmenter().segment(str));
 /**
- * Strips ANSI escape sequences from a string
+ * Strips ANSI escape sequences from a string.
  */
 export const strip_ansi = (str) => str.replaceAll(/\x1B\[[0-9;]*[a-zA-Z]/g, ''); // eslint-disable-line no-control-regex
 /**
@@ -152,9 +152,9 @@ export const pad_width = (str, target_width, align = 'left') => {
  * Calculates the Levenshtein distance between two strings.
  * Useful for typo detection and fuzzy matching.
  *
- * @param a - First string
- * @param b - Second string
- * @returns The edit distance between the strings
+ * @param a - first string
+ * @param b - second string
+ * @returns the edit distance between the strings
  */
 export const levenshtein_distance = (a, b) => {
     if (a.length === 0)
@@ -220,7 +220,7 @@ export const escape_js_string = (value) => value.replace(/[\\'\n\r\u2028\u2029]/
  *
  * Checks for null bytes in the first 8KB of content.
  *
- * @param content - Content to check.
- * @returns True if content appears to be binary.
+ * @param content - content to check
+ * @returns true if content appears to be binary
  */
 export const string_is_binary = (content) => content.slice(0, 8192).includes('\0');

package/dist/svelte_preprocess_helpers.d.ts

@@ -33,9 +33,9 @@ export interface ResolvedComponentImport {
  * Iterates the node's `attributes` array and returns the first `Attribute`
  * node whose `name` matches. Skips `SpreadAttribute`, directive, and other node types.
  *
- * @param node The component AST node to search.
- * @param name The attribute name to find.
- * @returns The matching `Attribute` node, or `undefined` if not found.
+ * @param node - the component AST node to search
+ * @param name - the attribute name to find
+ * @returns the matching `Attribute` node, or `undefined` if not found
  */
 export declare const find_attribute: (node: AST.Component, name: string) => AST.Attribute | undefined;
 /**
@@ -46,9 +46,9 @@ export declare const find_attribute: (node: AST.Component, name: string) => AST.
  * via an optional bindings map built by `build_static_bindings`.
  * Returns `null` for dynamic expressions, non-string literals, or unsupported node types.
  *
- * @param expr An ESTree expression AST node.
- * @param bindings Optional map of variable names to their resolved static string values.
- * @returns The resolved static string, or `null` if the expression is dynamic.
+ * @param expr - an ESTree expression AST node
+ * @param bindings - optional map of variable names to their resolved static string values
+ * @returns the resolved static string, or `null` if the expression is dynamic
  */
 export declare const evaluate_static_expr: (expr: Expression, bindings?: ReadonlyMap<string, string>) => string | null;
 /**
@@ -62,9 +62,9 @@ export declare const evaluate_static_expr: (expr: Expression, bindings?: Readonl
  *
  * Returns `null` for null literals, mixed arrays, dynamic expressions, and non-string values.
  *
- * @param value The attribute value from `AST.Attribute['value']`.
- * @param bindings Optional map of variable names to their resolved static string values.
- * @returns The resolved static string, or `null` if the value is dynamic.
+ * @param value - the attribute value from `AST.Attribute['value']`
+ * @param bindings - optional map of variable names to their resolved static string values
+ * @returns the resolved static string, or `null` if the value is dynamic
  */
 export declare const extract_static_string: (value: AST.Attribute["value"], bindings?: ReadonlyMap<string, string>) => string | null;
 /** A single branch in a conditional chain extracted from nested ternary expressions. */
@@ -88,10 +88,10 @@ export interface ConditionalChainBranch {
  *
  * A 2-branch result covers the simple ternary case (`a ? 'x' : 'y'`).
  *
- * @param value The attribute value from `AST.Attribute['value']`.
- * @param source The full source string (needed to slice test expression source text).
- * @param bindings Map of variable names to their resolved static string values.
- * @returns Array of conditional chain branches, or `null` if not extractable.
+ * @param value - the attribute value from `AST.Attribute['value']`
+ * @param source - the full source string (needed to slice test expression source text)
+ * @param bindings - map of variable names to their resolved static string values
+ * @returns array of conditional chain branches, or `null` if not extractable
  */
 export declare const try_extract_conditional_chain: (value: AST.Attribute["value"], source: string, bindings: ReadonlyMap<string, string>) => Array<ConditionalChainBranch> | null;
 /**
@@ -105,8 +105,8 @@ export declare const try_extract_conditional_chain: (value: AST.Attribute["value
  * Skips destructuring patterns, `let`/`var` declarations, and declarations
  * whose initializers reference dynamic values.
  *
- * @param ast The parsed Svelte AST root node.
- * @returns Map of variable names to their resolved static string values.
+ * @param ast - the parsed Svelte AST root node
+ * @returns map of variable names to their resolved static string values
  */
 export declare const build_static_bindings: (ast: AST.Root) => Map<string, string>;
 /**
@@ -117,9 +117,9 @@ export declare const build_static_bindings: (ast: AST.Root) => Map<string, strin
  * and `import type` declarations (both whole-declaration and per-specifier).
  * Returns import node references alongside names to support import removal.
  *
- * @param ast The parsed Svelte AST root node.
- * @param component_imports Array of import source paths to match against.
- * @returns Map of local names to their resolved import info.
+ * @param ast - the parsed Svelte AST root node
+ * @param component_imports - array of import source paths to match against
+ * @returns map of local names to their resolved import info
  */
 export declare const resolve_component_names: (ast: AST.Root, component_imports: Array<string>) => Map<string, ResolvedComponentImport>;
 /**
@@ -128,8 +128,8 @@ export declare const resolve_component_names: (ast: AST.Root, component_imports:
  * Returns the end position of the last `ImportDeclaration`, or the start
  * of the script body content if no imports exist.
  *
- * @param script The parsed `AST.Script` node.
- * @returns The character position where new imports should be inserted.
+ * @param script - the parsed `AST.Script` node
+ * @returns the character position where new imports should be inserted
  */
 export declare const find_import_insert_position: (script: AST.Script) => number;
 /**
@@ -138,9 +138,9 @@ export declare const find_import_insert_position: (script: AST.Script) => number
  * Default imports produce `import Name from 'path';` lines.
  * Named imports are grouped by path into `import {a, b} from 'path';` lines.
  *
- * @param imports Map of local names to their import info.
- * @param indent Indentation prefix for each line. @default '\t'
- * @returns A string of newline-separated import statements.
+ * @param imports - map of local names to their import info
+ * @param indent - indentation prefix for each line @default '\t'
+ * @returns a string of newline-separated import statements
  */
 export declare const generate_import_lines: (imports: Map<string, PreprocessImportInfo>, indent?: string) => string;
 /**
@@ -158,10 +158,10 @@ export declare const generate_import_lines: (imports: Map<string, PreprocessImpo
  * Safe for Svelte template ASTs: `Component.name` is a plain string property
  * (not an `Identifier` node), so `<Mdz>` tags do not produce false matches.
  *
- * @param node The AST subtree to search.
- * @param name The identifier name to look for.
- * @param skip Set of AST nodes to skip during traversal.
- * @returns `true` if a matching `Identifier` node is found.
+ * @param node - the AST subtree to search
+ * @param name - the identifier name to look for
+ * @param skip - set of AST nodes to skip during traversal
+ * @returns `true` if a matching `Identifier` node is found
  */
 export declare const has_identifier_in_tree: (node: unknown, name: string, skip?: Set<unknown>) => boolean;
 /**
@@ -188,9 +188,9 @@ export declare const escape_svelte_text: (text: string) => string;
  * blank lines. Only safe for single-declarator statements (`const x = 'val';`);
  * callers must verify `node.declarations.length === 1` before calling.
  *
- * @param s The MagicString instance to modify.
- * @param declaration_node The `VariableDeclaration` AST node with Svelte position data.
- * @param source The original source string.
+ * @param s - the MagicString instance to modify
+ * @param declaration_node - the `VariableDeclaration` AST node with Svelte position data
+ * @param source - the original source string
  */
 export declare const remove_variable_declaration: (s: {
     remove: (start: number, end: number) => unknown;
@@ -204,9 +204,9 @@ export declare const remove_variable_declaration: (s: {
  * Consumes leading whitespace (tabs/spaces) and trailing newline to avoid leaving
  * blank lines.
  *
- * @param s The MagicString instance to modify.
- * @param import_node The `ImportDeclaration` AST node with Svelte position data.
- * @param source The original source string.
+ * @param s - the MagicString instance to modify
+ * @param import_node - the `ImportDeclaration` AST node with Svelte position data
+ * @param source - the original source string
  */
 export declare const remove_import_declaration: (s: {
     remove: (start: number, end: number) => unknown;
@@ -225,11 +225,11 @@ export declare const remove_import_declaration: (s: {
  * - `import {default as Mdz, other} from '...'` → `import {other} from '...'`
  * - `import {Mdz, other} from '...'` → `import {other} from '...'`
  *
- * @param s The MagicString instance to modify.
- * @param node The positioned `ImportDeclaration` AST node.
- * @param specifier_to_remove The specifier to remove from the import.
- * @param source The original source string.
- * @param additional_lines Extra content appended after the reconstructed import
+ * @param s - the MagicString instance to modify
+ * @param node - the positioned `ImportDeclaration` AST node
+ * @param specifier_to_remove - the specifier to remove from the import
+ * @param source - the original source string
+ * @param additional_lines - extra content appended after the reconstructed import
  *   (used to bundle new imports into the overwrite to avoid MagicString boundary conflicts).
  */
 export declare const remove_import_specifier: (s: {
@@ -241,10 +241,10 @@ export declare const remove_import_specifier: (s: {
 /**
  * Handles errors during Svelte preprocessing with configurable behavior.
  *
- * @param error The caught error.
- * @param prefix Log prefix (e.g. `'[fuz-mdz]'`, `'[fuz-code]'`).
- * @param filename The file being processed.
- * @param on_error `'throw'` to re-throw as a new Error, `'log'` to console.error.
+ * @param error - the caught error
+ * @param prefix - log prefix (e.g. `'[fuz-mdz]'`, `'[fuz-code]'`)
+ * @param filename - the file being processed
+ * @param on_error - `'throw'` to re-throw as a new Error, `'log'` to console.error
  */
 export declare const handle_preprocess_error: (error: unknown, prefix: string, filename: string | undefined, on_error: "throw" | "log") => void;
 //# sourceMappingURL=svelte_preprocess_helpers.d.ts.map

package/dist/svelte_preprocess_helpers.js

@@ -17,9 +17,9 @@
  * Iterates the node's `attributes` array and returns the first `Attribute`
  * node whose `name` matches. Skips `SpreadAttribute`, directive, and other node types.
  *
- * @param node The component AST node to search.
- * @param name The attribute name to find.
- * @returns The matching `Attribute` node, or `undefined` if not found.
+ * @param node - the component AST node to search
+ * @param name - the attribute name to find
+ * @returns the matching `Attribute` node, or `undefined` if not found
  */
 export const find_attribute = (node, name) => {
     for (const attr of node.attributes) {
@@ -37,9 +37,9 @@ export const find_attribute = (node, name) => {
  * via an optional bindings map built by `build_static_bindings`.
  * Returns `null` for dynamic expressions, non-string literals, or unsupported node types.
  *
- * @param expr An ESTree expression AST node.
- * @param bindings Optional map of variable names to their resolved static string values.
- * @returns The resolved static string, or `null` if the expression is dynamic.
+ * @param expr - an ESTree expression AST node
+ * @param bindings - optional map of variable names to their resolved static string values
+ * @returns the resolved static string, or `null` if the expression is dynamic
  */
 export const evaluate_static_expr = (expr, bindings) => {
     if (expr.type === 'Literal' && typeof expr.value === 'string')
@@ -89,9 +89,9 @@ export const evaluate_static_expr = (expr, bindings) => {
  *
  * Returns `null` for null literals, mixed arrays, dynamic expressions, and non-string values.
  *
- * @param value The attribute value from `AST.Attribute['value']`.
- * @param bindings Optional map of variable names to their resolved static string values.
- * @returns The resolved static string, or `null` if the value is dynamic.
+ * @param value - the attribute value from `AST.Attribute['value']`
+ * @param bindings - optional map of variable names to their resolved static string values
+ * @returns the resolved static string, or `null` if the value is dynamic
  */
 export const extract_static_string = (value, bindings) => {
     // Boolean attribute (e.g., <Mdz inline />)
@@ -126,10 +126,10 @@ export const extract_static_string = (value, bindings) => {
  *
  * A 2-branch result covers the simple ternary case (`a ? 'x' : 'y'`).
  *
- * @param value The attribute value from `AST.Attribute['value']`.
- * @param source The full source string (needed to slice test expression source text).
- * @param bindings Map of variable names to their resolved static string values.
- * @returns Array of conditional chain branches, or `null` if not extractable.
+ * @param value - the attribute value from `AST.Attribute['value']`
+ * @param source - the full source string (needed to slice test expression source text)
+ * @param bindings - map of variable names to their resolved static string values
+ * @returns array of conditional chain branches, or `null` if not extractable
  */
 export const try_extract_conditional_chain = (value, source, bindings) => {
     if (value === true || Array.isArray(value))
@@ -178,8 +178,8 @@ export const try_extract_conditional_chain = (value, source, bindings) => {
  * Skips destructuring patterns, `let`/`var` declarations, and declarations
  * whose initializers reference dynamic values.
  *
- * @param ast The parsed Svelte AST root node.
- * @returns Map of variable names to their resolved static string values.
+ * @param ast - the parsed Svelte AST root node
+ * @returns map of variable names to their resolved static string values
  */
 export const build_static_bindings = (ast) => {
     const bindings = new Map();
@@ -211,9 +211,9 @@ export const build_static_bindings = (ast) => {
  * and `import type` declarations (both whole-declaration and per-specifier).
  * Returns import node references alongside names to support import removal.
  *
- * @param ast The parsed Svelte AST root node.
- * @param component_imports Array of import source paths to match against.
- * @returns Map of local names to their resolved import info.
+ * @param ast - the parsed Svelte AST root node
+ * @param component_imports - array of import source paths to match against
+ * @returns map of local names to their resolved import info
  */
 export const resolve_component_names = (ast, component_imports) => {
     const names = new Map();
@@ -247,8 +247,8 @@ export const resolve_component_names = (ast, component_imports) => {
  * Returns the end position of the last `ImportDeclaration`, or the start
  * of the script body content if no imports exist.
  *
- * @param script The parsed `AST.Script` node.
- * @returns The character position where new imports should be inserted.
+ * @param script - the parsed `AST.Script` node
+ * @returns the character position where new imports should be inserted
  */
 export const find_import_insert_position = (script) => {
     let last_import_end = -1;
@@ -269,9 +269,9 @@ export const find_import_insert_position = (script) => {
  * Default imports produce `import Name from 'path';` lines.
  * Named imports are grouped by path into `import {a, b} from 'path';` lines.
  *
- * @param imports Map of local names to their import info.
- * @param indent Indentation prefix for each line. @default '\t'
- * @returns A string of newline-separated import statements.
+ * @param imports - map of local names to their import info
+ * @param indent - indentation prefix for each line @default '\t'
+ * @returns a string of newline-separated import statements
  */
 export const generate_import_lines = (imports, indent = '\t') => {
     const default_imports = [];
@@ -333,10 +333,10 @@ const NON_REFERENCE_FIELDS = new Map([
  * Safe for Svelte template ASTs: `Component.name` is a plain string property
  * (not an `Identifier` node), so `<Mdz>` tags do not produce false matches.
  *
- * @param node The AST subtree to search.
- * @param name The identifier name to look for.
- * @param skip Set of AST nodes to skip during traversal.
- * @returns `true` if a matching `Identifier` node is found.
+ * @param node - the AST subtree to search
+ * @param name - the identifier name to look for
+ * @param skip - set of AST nodes to skip during traversal
+ * @returns `true` if a matching `Identifier` node is found
  */
 export const has_identifier_in_tree = (node, name, skip) => {
     if (node === null || node === undefined || typeof node !== 'object')
@@ -396,9 +396,9 @@ export const escape_svelte_text = (text) => text.replace(/[{}<&]/g, (ch) => {
  * blank lines. Only safe for single-declarator statements (`const x = 'val';`);
  * callers must verify `node.declarations.length === 1` before calling.
  *
- * @param s The MagicString instance to modify.
- * @param declaration_node The `VariableDeclaration` AST node with Svelte position data.
- * @param source The original source string.
+ * @param s - the MagicString instance to modify
+ * @param declaration_node - the `VariableDeclaration` AST node with Svelte position data
+ * @param source - the original source string
  */
 export const remove_variable_declaration = (s, declaration_node, source) => {
     remove_positioned_node(s, declaration_node, source);
@@ -409,9 +409,9 @@ export const remove_variable_declaration = (s, declaration_node, source) => {
  * Consumes leading whitespace (tabs/spaces) and trailing newline to avoid leaving
  * blank lines.
  *
- * @param s The MagicString instance to modify.
- * @param import_node The `ImportDeclaration` AST node with Svelte position data.
- * @param source The original source string.
+ * @param s - the MagicString instance to modify
+ * @param import_node - the `ImportDeclaration` AST node with Svelte position data
+ * @param source - the original source string
  */
 export const remove_import_declaration = (s, import_node, source) => {
     remove_positioned_node(s, import_node, source);
@@ -450,11 +450,11 @@ const remove_positioned_node = (s, node, source) => {
  * - `import {default as Mdz, other} from '...'` → `import {other} from '...'`
  * - `import {Mdz, other} from '...'` → `import {other} from '...'`
  *
- * @param s The MagicString instance to modify.
- * @param node The positioned `ImportDeclaration` AST node.
- * @param specifier_to_remove The specifier to remove from the import.
- * @param source The original source string.
- * @param additional_lines Extra content appended after the reconstructed import
+ * @param s - the MagicString instance to modify
+ * @param node - the positioned `ImportDeclaration` AST node
+ * @param specifier_to_remove - the specifier to remove from the import
+ * @param source - the original source string
+ * @param additional_lines - extra content appended after the reconstructed import
  *   (used to bundle new imports into the overwrite to avoid MagicString boundary conflicts).
  */
 export const remove_import_specifier = (s, node, specifier_to_remove, source, additional_lines = '') => {
@@ -501,10 +501,10 @@ const format_named_specifiers = (specs) => specs
 /**
  * Handles errors during Svelte preprocessing with configurable behavior.
  *
- * @param error The caught error.
- * @param prefix Log prefix (e.g. `'[fuz-mdz]'`, `'[fuz-code]'`).
- * @param filename The file being processed.
- * @param on_error `'throw'` to re-throw as a new Error, `'log'` to console.error.
+ * @param error - the caught error
+ * @param prefix - log prefix (e.g. `'[fuz-mdz]'`, `'[fuz-code]'`)
+ * @param filename - the file being processed
+ * @param on_error - `'throw'` to re-throw as a new Error, `'log'` to console.error
  */
 export const handle_preprocess_error = (error, prefix, filename, on_error) => {
     const message = `${prefix} Preprocessing failed${filename ? ` in ${filename}` : ''}: ${error instanceof Error ? error.message : String(error)}`;

package/dist/testing.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared test assertions for the `@fuzdev` ecosystem.
+ *
+ * Extends the fuz-stack testing conventions (`assert` from vitest, tests in `src/test/`,
+ * plain object mocks) with reusable helpers for patterns that appear across multiple repos.
+ * Only depends on vitest — safe for fuz_util's zero-runtime-deps constraint.
+ *
+ * @module
+ */
+import type { Logger } from './log.js';
+/**
+ * Asserts that `fn` rejects with an `Error`.
+ * Optionally matches the error message against `pattern`.
+ * Returns the caught `Error` for further assertions by the caller.
+ *
+ * `assert.fail` is placed after the catch block so that assertion failures
+ * from the test itself are not swallowed by the catch.
+ *
+ * @param fn - async function expected to reject
+ * @param pattern - optional regex to match against the error message
+ * @returns the caught `Error`
+ */
+export declare const assert_rejects: (fn: () => Promise<unknown>, pattern?: RegExp) => Promise<Error>;
+/**
+ * A mock `Logger` with `vi.fn()` methods and call tracking arrays.
+ * Assignable to `Logger` for use in code under test.
+ * Each tracking array captures the first argument of each call.
+ * For full call details, use `vi.fn()` introspection on the methods directly.
+ */
+export type MockLogger = Logger & {
+    error_calls: Array<unknown>;
+    warn_calls: Array<unknown>;
+    info_calls: Array<unknown>;
+    debug_calls: Array<unknown>;
+};
+/**
+ * Creates a mock `Logger` with `vi.fn()` on each logging method
+ * and tracking arrays for inspecting logged messages.
+ * Follows the fuz-stack convention of plain object mocks over mocking libraries.
+ *
+ * @returns a `MockLogger` assignable to `Logger`
+ */
+export declare const create_mock_logger: () => MockLogger;
+//# sourceMappingURL=testing.d.ts.map