@fuzdev/fuz_util 0.55.0 → 0.56.0

package/src/lib/log.ts

@@ -12,7 +12,7 @@ import {DEV} from 'esm-env';
 export type LogLevel = 'off' | 'error' | 'warn' | 'info' | 'debug';
 
 /**
- * Console interface subset used by Logger for output.
+ * Console interface subset used by `Logger` for output.
  * Allows custom console implementations for testing.
  */
 export type LogConsole = Pick<typeof console, 'error' | 'warn' | 'log'>;
@@ -42,15 +42,15 @@ const LOG_LEVEL_VALUES: Record<LogLevel, number> = {
 /**
  * Converts a log level to its numeric value for comparison.
  * Higher numbers indicate more verbose logging.
- * @param level The log level to convert
- * @returns Numeric value (0-4)
+ * @param level - the log level to convert
+ * @returns numeric value (0-4)
  */
 export const log_level_to_number = (level: LogLevel): number => LOG_LEVEL_VALUES[level];
 
 /**
  * Parses and validates a log level string.
- * @param value The value to parse as a log level
- * @returns The validated log level, or undefined if value is undefined
+ * @param value - the value to parse as a log level
+ * @returns the validated log level, or undefined if value is undefined
  * @throws Error if value is provided but invalid
  */
 export const log_level_parse = (value: string | undefined): LogLevel | undefined => {
@@ -112,10 +112,10 @@ export class Logger {
 	/**
 	 * Creates a new Logger instance.
 	 *
-	 * @param label Optional label for this logger. Can be `undefined` for no label, or an
+	 * @param label - optional label for this logger. Can be `undefined` for no label, or an
 	 *   empty string `''` which is functionally equivalent (both produce no brackets in output).
 	 *   Note: Empty strings are only allowed for root loggers - child loggers cannot have empty labels.
-	 * @param options Optional configuration for level, colors, and console
+	 * @param options - optional configuration for level, colors, and console
 	 */
 	constructor(label?: string, options: LoggerOptions = {}) {
 		this.label = label;
@@ -205,7 +205,7 @@ export class Logger {
 	/**
 	 * Gets the root logger by walking up the parent chain.
 	 * Useful for setting global configuration that affects all child loggers.
-	 * @returns The root logger (the one without a parent)
+	 * @returns the root logger (the one without a parent)
 	 */
 	get root(): Logger {
 		let current: Logger = this; // eslint-disable-line consistent-this, @typescript-eslint/no-this-alias
@@ -360,11 +360,11 @@ export class Logger {
 	 * Creates a child logger with automatic label concatenation.
 	 * Children inherit parent configuration unless overridden.
 	 *
-	 * @param label Child label (will be concatenated with parent label using `:`).
+	 * @param label - child label (will be concatenated with parent label using `:`)
 	 *   Cannot be an empty string - empty labels would result in confusing output like `parent:`
 	 *   with a trailing colon. Use `undefined` or `''` only for root loggers.
-	 * @param options Optional configuration overrides
-	 * @returns New Logger instance with concatenated label
+	 * @param options - optional configuration overrides
+	 * @returns new `Logger` instance with concatenated label
 	 * @throws Error if label is an empty string
 	 *
 	 * @example
@@ -440,7 +440,7 @@ export class Logger {
 	 * Note: This method ignores the configured log level - it always outputs regardless of
 	 * whether the logger is set to 'off' or any other level.
 	 *
-	 * @param args Values to log directly to console
+	 * @param args - values to log directly to console
 	 */
 	raw(...args: Array<unknown>): void {
 		this.console.log(...args);

package/src/lib/map.ts

@@ -1,6 +1,6 @@
 /**
  * Sorts a map by `comparator`, a function that compares two entries,
- * defaulting to using `localCompare` and `>`.
+ * defaulting to using `localeCompare` and `>`.
  */
 export const sort_map = <T extends Map<any, any>>(
 	map: T,

package/src/lib/object.ts

@@ -61,7 +61,7 @@ export const pick_by = <T extends Record<K, any>, K extends string | number>(
  * `omit_undefined` is a commonly used form of `pick_by`.
  * See this issue for why it's used so much:
  * https://github.com/Microsoft/TypeScript/issues/13195
- * @param obj
+ * @param obj - the object to filter
  * @returns `obj` with all `undefined` properties removed
  */
 export const omit_undefined = <T extends Record<string | number, any>>(obj: T): T =>

package/src/lib/package_json.ts

@@ -66,7 +66,7 @@ export type PackageJsonExports = z.infer<typeof PackageJsonExports>;
 export const PackageJson = z.looseObject({
 	// according to the npm docs, `name` and `version` are the only required properties
 	name: z.string(),
-	version: z.string(),
+	version: z.string().optional(),
 	private: z
 		.boolean()
 		.meta({description: 'disallow publishing to the configured registry'})

package/src/lib/path.ts

@@ -106,9 +106,9 @@ export const parse_path_pieces = (raw_path: string): Array<PathPiece> => {
  * Returns `false` when `filename` is `undefined`, empty string, or `exclude` is empty.
  * String patterns use substring matching. RegExp patterns use `.test()`.
  *
- * @param filename The file path to check, or `undefined` for virtual files.
- * @param exclude Array of string or RegExp exclusion patterns.
- * @returns `true` if the file should be excluded from processing.
+ * @param filename - the file path to check, or `undefined` for virtual files
+ * @param exclude - array of string or RegExp exclusion patterns
+ * @returns `true` if the file should be excluded from processing
  */
 export const should_exclude_path = (
 	filename: string | undefined,
@@ -122,8 +122,8 @@ export const should_exclude_path = (
 
 /**
  * Converts a string into a URL-compatible slug.
- * @param str the string to convert
- * @param map_special_characters if `true`, characters like `ñ` are converted to their ASCII equivalents, runs around 5x faster when disabled
+ * @param str - the string to convert
+ * @param map_special_characters - if `true`, characters like `ñ` are converted to their ASCII equivalents, runs around 5x faster when disabled
  * @mutates special_char_mappers - calls `get_special_char_mappers()` which lazily initializes the module-level array if `map_special_characters` is true
  */
 export const slugify = (str: string, map_special_characters = true): string => {

package/src/lib/process.ts

@@ -250,10 +250,10 @@ export class ProcessRegistry {
 	 * Spawns a process and tracks it in this registry.
 	 * The process is automatically unregistered when it exits.
 	 *
-	 * @param command - The command to run
-	 * @param args - Arguments to pass to the command
-	 * @param options - Spawn options including `signal` and `timeout_ms`
-	 * @returns Handle with `child` process and `closed` promise
+	 * @param command - the command to run
+	 * @param args - arguments to pass to the command
+	 * @param options - spawn options including `signal` and `timeout_ms`
+	 * @returns handle with `child` process and `closed` promise
 	 */
 	spawn(
 		command: string,
@@ -295,10 +295,10 @@ export class ProcessRegistry {
 	 * Spawns a process and captures stdout/stderr as strings.
 	 * Sets `stdio: 'pipe'` automatically.
 	 *
-	 * @param command - The command to run
-	 * @param args - Arguments to pass to the command
-	 * @param options - Spawn options
-	 * @returns Result with captured `stdout` and `stderr`.
+	 * @param command - the command to run
+	 * @param args - arguments to pass to the command
+	 * @param options - spawn options
+	 * @returns result with captured `stdout` and `stderr`
 	 *   - `null` means spawn failed (ENOENT, etc.) or stream was unavailable
 	 *   - `''` (empty string) means process ran but produced no output
 	 *   - non-empty string contains the captured output
@@ -337,9 +337,9 @@ export class ProcessRegistry {
 	/**
 	 * Kills a child process and waits for it to exit.
 	 *
-	 * @param child - The child process to kill
-	 * @param options - Kill options including signal and timeout
-	 * @returns The spawn result after the process exits
+	 * @param child - the child process to kill
+	 * @param options - kill options including signal and timeout
+	 * @returns the spawn result after the process exits
 	 */
 	async despawn(child: ChildProcess, options?: DespawnOptions): Promise<SpawnResult> {
 		const {signal = 'SIGTERM', timeout_ms} = options ?? {};
@@ -382,8 +382,8 @@ export class ProcessRegistry {
 	/**
 	 * Kills all processes in this registry.
 	 *
-	 * @param options - Kill options applied to all processes
-	 * @returns Array of spawn results
+	 * @param options - kill options applied to all processes
+	 * @returns array of spawn results
 	 */
 	async despawn_all(options?: DespawnOptions): Promise<Array<SpawnResult>> {
 		return Promise.all([...this.processes].map((child) => this.despawn(child, options)));
@@ -401,14 +401,14 @@ export class ProcessRegistry {
 	 * graceful shutdown uses a blocking busy-wait. This may not be sufficient
 	 * for processes that need significant cleanup time.
 	 *
-	 * @param options - Configuration options
+	 * @param options - configuration options
 	 * @param options.to_error_label - Customize error label, return `null` for default
 	 * @param options.map_error_text - Customize error text, return `''` to silence
 	 * @param options.handle_error - Called after cleanup, defaults to `process.exit(1)`
 	 * @param options.graceful_timeout_ms - If set, sends SIGTERM first and waits this
 	 *   many ms before SIGKILL. Recommended: 100-500ms. If null/undefined, uses
 	 *   immediate SIGKILL (default).
-	 * @returns Cleanup function to remove the handler
+	 * @returns cleanup function to remove the handler
 	 */
 	attach_error_handler(options?: {
 		to_error_label?: (err: Error, origin: NodeJS.UncaughtExceptionOrigin) => string | null;
@@ -552,7 +552,7 @@ export const despawn_all = (options?: DespawnOptions): Promise<Array<SpawnResult
 /**
  * Attaches an `uncaughtException` handler to the default registry.
  *
- * @see ProcessRegistry.attach_error_handler
+ * @see `ProcessRegistry.attach_error_handler`
  */
 export const attach_process_error_handler = (
 	options?: Parameters<ProcessRegistry['attach_error_handler']>[0],
@@ -561,13 +561,13 @@ export const attach_process_error_handler = (
 /**
  * Spawns a detached process that continues after parent exits.
  *
- * Unlike other spawn functions, this is NOT tracked in any ProcessRegistry.
+ * Unlike other spawn functions, this is NOT tracked in any `ProcessRegistry`.
  * The spawned process is meant to outlive the parent (e.g., daemon processes).
  *
- * @param command - The command to run
- * @param args - Arguments to pass to the command
- * @param options - Spawn options (use `stdio` to redirect output to file descriptors)
- * @returns Result with pid on success, or error message on failure
+ * @param command - the command to run
+ * @param args - arguments to pass to the command
+ * @param options - spawn options (use `stdio` to redirect output to file descriptors)
+ * @returns result with pid on success, or error message on failure
  *
  * @example
  * ```ts
@@ -820,7 +820,7 @@ export const spawn_restartable_process = (
  * Checks if a process with the given PID is running.
  * Uses signal 0 which checks existence without sending a signal.
  *
- * @param pid - The process ID to check (must be a positive integer)
+ * @param pid - the process ID to check (must be a positive integer)
  * @returns `true` if the process exists (even without permission to signal it),
  *   `false` if the process doesn't exist or if pid is invalid (non-positive, non-integer, NaN, Infinity)
  */

package/src/lib/random.ts

@@ -2,8 +2,8 @@
  * Random helpers that accept an optional `random` parameter,
  * defaulting to `Math.random`. Pass a seeded PRNG for reproducible results:
  *
- * - {@link create_random_xoshiro} — fast, high-quality numeric seeding (recommended)
- * - {@link create_random_alea} — supports string and variadic seeds
+ * - `create_random_xoshiro` — fast, high-quality numeric seeding (recommended)
+ * - `create_random_alea` — supports string and variadic seeds
  *
  * @module
  */

package/src/lib/result.ts

@@ -21,9 +21,9 @@ export const NOT_OK = Object.freeze({ok: false} as const);
  * A helper that says,
  * "hey I know this is wrapped in a `Result`, but I expect it to be `ok`,
  * so if it's not, I understand it will throw an error that wraps the result".
- * @param result Some `Result` object.
- * @param message Optional custom error message.
- * @returns The wrapped value.
+ * @param result - some `Result` object
+ * @param message - optional custom error message
+ * @returns the wrapped value
  */
 export const unwrap = <TValue extends {value?: unknown}, TError extends {message?: string}>(
 	result: Result<TValue, TError>,
@@ -54,9 +54,9 @@ export class ResultError extends Error {
 /**
  * A helper that does the opposite of `unwrap`, throwing if the `Result` is ok.
  * Note that while `unwrap` returns the wrapped `value`, `unwrap_error` returns the entire result.
- * @param result Some `Result` object.
- * @param message Optional custom error message.
- * @returns The type-narrowed result.
+ * @param result - some `Result` object
+ * @param message - optional custom error message
+ * @returns the type-narrowed result
  */
 export const unwrap_error = <TError extends object>(
 	result: Result<object, TError>,

package/src/lib/sort.ts

@@ -28,9 +28,9 @@ export type TopologicalSortResult<T extends Sortable> =
  * Returns items ordered so that dependencies come before dependents.
  * If a cycle is detected, returns an error with the cycle path.
  *
- * @param items - Array of items to sort.
- * @param label - Label for error messages (e.g. "resource", "step").
- * @returns Sorted items or error if cycle detected.
+ * @param items - array of items to sort
+ * @param label - label for error messages (e.g. "resource", "step")
+ * @returns sorted items or error if cycle detected
  */
 export const topological_sort = <T extends Sortable>(
 	items: Array<T>,

package/src/lib/source_json.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
  */
@@ -43,7 +43,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.
@@ -60,7 +60,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/src/lib/stats.ts

@@ -59,8 +59,8 @@ export const stats_variance = (values: Array<number>, mean?: number): number =>
  * 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: Array<number>, p: number): number => {
 	if (values.length === 0) return NaN;
@@ -329,8 +329,8 @@ 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 const stats_confidence_interval = (
@@ -348,10 +348,10 @@ export const stats_confidence_interval = (
 /**
  * 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 = (
@@ -393,12 +393,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 const stats_welch_t_test = (
 	mean1: number,
@@ -516,9 +516,9 @@ export const stats_incomplete_beta = (x: number, a: number, b: number): 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 const stats_t_distribution_p_value = (t: number, df: number): number => {
 	// Use normal approximation for large df

package/src/lib/string.ts

@@ -86,7 +86,7 @@ export const count_graphemes = (str: string): number =>
 	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: string): string => str.replaceAll(/\x1B\[[0-9;]*[a-zA-Z]/g, ''); // eslint-disable-line no-control-regex
 
@@ -168,9 +168,9 @@ export const pad_width = (
  * 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: string, b: string): number => {
 	if (a.length === 0) return b.length;
@@ -240,7 +240,7 @@ export 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 const string_is_binary = (content: string): boolean => content.slice(0, 8192).includes('\0');

package/src/lib/svelte_preprocess_helpers.ts

@@ -44,9 +44,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 const find_attribute = (node: AST.Component, name: string): AST.Attribute | undefined => {
 	for (const attr of node.attributes) {
@@ -65,9 +65,9 @@ export const find_attribute = (node: AST.Component, name: string): AST.Attribute
  * 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: Expression,
@@ -116,9 +116,9 @@ export const evaluate_static_expr = (
  *
  * 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: AST.Attribute['value'],
@@ -165,10 +165,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 const try_extract_conditional_chain = (
 	value: AST.Attribute['value'],
@@ -223,8 +223,8 @@ export const try_extract_conditional_chain = (
  * 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: AST.Root): Map<string, string> => {
 	const bindings: Map<string, string> = new Map();
@@ -253,9 +253,9 @@ export const build_static_bindings = (ast: AST.Root): Map<string, string> => {
  * 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: AST.Root,
@@ -287,8 +287,8 @@ export const resolve_component_names = (
  * 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: AST.Script): number => {
 	let last_import_end = -1;
@@ -310,9 +310,9 @@ export 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 const generate_import_lines = (
 	imports: Map<string, PreprocessImportInfo>,
@@ -383,10 +383,10 @@ const NON_REFERENCE_FIELDS: 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: unknown,
@@ -449,9 +449,9 @@ export 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 const remove_variable_declaration = (
 	s: {remove: (start: number, end: number) => unknown},
@@ -467,9 +467,9 @@ export const remove_variable_declaration = (
  * 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: {remove: (start: number, end: number) => unknown},
@@ -520,11 +520,11 @@ const remove_positioned_node = (
  * - `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 = (
@@ -585,10 +585,10 @@ const format_named_specifiers = (specs: Array<ImportDeclaration['specifiers'][nu
 /**
  * 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: unknown,