@fuzdev/fuz_ui 0.190.0 → 0.191.1

package/src/lib/mdz.ts

@@ -62,6 +62,8 @@ import {
 	is_at_absolute_path,
 	is_at_relative_path,
 	extract_single_tag,
+	mdz_heading_id,
+	mdz_is_url,
 } from './mdz_helpers.js';
 
 // TODO design incremental parsing or some system that preserves Svelte components across re-renders when possible
@@ -141,6 +143,7 @@ export interface MdzHrNode extends MdzBaseNode {
 export interface MdzHeadingNode extends MdzBaseNode {
 	type: 'Heading';
 	level: 1 | 2 | 3 | 4 | 5 | 6;
+	id: string; // slugified heading text for fragment links
 	children: Array<MdzNode>; // inline formatting allowed
 }
 
@@ -490,9 +493,9 @@ export class MdzParser {
 	 * - Empty content (e.g., `__` or `~~`)
 	 * - Paragraph break interrupts before closing delimiter
 	 *
-	 * @param delimiter - The delimiter character (`_` for italic, `~` for strikethrough)
-	 * @param node_type - The node type to create ('Italic' or 'Strikethrough')
-	 * @returns Formatted node or text node if validation fails
+	 * @param delimiter - the delimiter character (`_` for italic, `~` for strikethrough)
+	 * @param node_type - the node type to create ('Italic' or 'Strikethrough')
+	 * @returns formatted node or text node if validation fails
 	 */
 	#parse_single_delimiter_formatting(
 		delimiter: '_',
@@ -718,107 +721,41 @@ export class MdzParser {
 	#parse_tag(): MdzElementNode | MdzComponentNode | MdzTextNode {
 		const start = this.#index;
 
-		// Save parent accumulation state to avoid polluting component children with parent's accumulated text
-		const saved_state = this.#save_accumulation_state();
-
-		// Clear accumulation state for parsing component children
-		this.#accumulated_text = '';
-		this.#nodes.length = 0;
-
-		// Consume <
-		if (!this.#match('<')) {
-			// Restore parent state before returning
-			this.#restore_accumulation_state(saved_state);
-
-			const content = this.#template[this.#index]!;
-			this.#index++;
-			return {
-				type: 'Text',
-				content,
-				start,
-				end: this.#index,
-			};
-		}
-		this.#index++;
-
-		// Parse tag name
-		const tag_name_start = this.#index;
-		let tag_name_end = this.#index;
+		// Phase 1: Validate tag structure using a local scan index.
+		// Avoids save/restore of accumulation state on the fast path
+		// (most `<` characters are not valid tags).
+		let i = start + 1; // skip <
 
 		// Tag name must start with a letter
-		if (this.#index >= this.#template.length) {
-			// Just a `<` at EOF - restore parent state
-			this.#restore_accumulation_state(saved_state);
-			return {
-				type: 'Text',
-				content: '<',
-				start,
-				end: this.#index,
-			};
-		}
-
-		const first_char = this.#template.charCodeAt(this.#index);
-		if (!is_letter(first_char)) {
-			// Not a valid tag, treat as text - restore parent state
-			this.#restore_accumulation_state(saved_state);
-			return {
-				type: 'Text',
-				content: '<',
-				start,
-				end: start + 1,
-			};
+		if (i >= this.#template.length || !is_letter(this.#template.charCodeAt(i))) {
+			this.#index = start + 1;
+			return this.#make_text_node('<', start);
 		}
 
 		// Collect tag name (letters, numbers, hyphens, underscores)
-		while (this.#index < this.#template.length) {
-			const char_code = this.#template.charCodeAt(this.#index);
-			if (is_tag_name_char(char_code)) {
-				this.#index++;
-			} else {
-				break;
-			}
-		}
-
-		tag_name_end = this.#index;
-		const tag_name = this.#template.slice(tag_name_start, tag_name_end);
-
-		if (tag_name.length === 0) {
-			// Empty tag name - restore parent state
-			this.#restore_accumulation_state(saved_state);
-			return {
-				type: 'Text',
-				content: '<',
-				start,
-				end: start + 1,
-			};
+		while (i < this.#template.length && is_tag_name_char(this.#template.charCodeAt(i))) {
+			i++;
 		}
 
-		// Determine if this is a Component (uppercase) or Element (lowercase)
+		const tag_name = this.#template.slice(start + 1, i);
 		const first_char_code = tag_name.charCodeAt(0);
-		const is_component = first_char_code >= A_UPPER && first_char_code <= Z_UPPER;
-		const node_type: 'Component' | 'Element' = is_component ? 'Component' : 'Element';
+		const node_type: 'Component' | 'Element' =
+			first_char_code >= A_UPPER && first_char_code <= Z_UPPER ? 'Component' : 'Element';
 
 		// Skip whitespace after tag name (for future attribute support)
-		while (
-			this.#index < this.#template.length &&
-			this.#template.charCodeAt(this.#index) === SPACE
-		) {
-			this.#index++;
+		while (i < this.#template.length && this.#template.charCodeAt(i) === SPACE) {
+			i++;
 		}
 
 		// TODO: Parse attributes here
 
 		// Check for self-closing />
 		if (
-			this.#index + 1 < this.#template.length &&
-			this.#template.charCodeAt(this.#index) === SLASH &&
-			this.#template.charCodeAt(this.#index + 1) === RIGHT_ANGLE
+			i + 1 < this.#template.length &&
+			this.#template.charCodeAt(i) === SLASH &&
+			this.#template.charCodeAt(i + 1) === RIGHT_ANGLE
 		) {
-			this.#index += 2;
-
-			// Restore parent state before returning
-			this.#restore_accumulation_state(saved_state);
-
+			this.#index = i + 2;
 			return {
 				type: node_type,
 				name: tag_name,
@@ -828,41 +765,44 @@ export class MdzParser {
 			};
 		}
 
-		// Check for closing >
-		if (
-			this.#index >= this.#template.length ||
-			this.#template.charCodeAt(this.#index) !== RIGHT_ANGLE
-		) {
-			// Unclosed opening tag, treat as text - restore parent state
-			this.#restore_accumulation_state(saved_state);
-
+		// Must have closing >
+		if (i >= this.#template.length || this.#template.charCodeAt(i) !== RIGHT_ANGLE) {
 			this.#index = start + 1;
-			return {
-				type: 'Text',
-				content: '<',
-				start,
-				end: this.#index,
-			};
+			return this.#make_text_node('<', start);
 		}
 
-		// Consume >
-		this.#index++;
+		const content_start = i + 1; // past >
 
-		// Parse children until closing tag
+		// Bail early if closing tag is missing, past a paragraph break,
+		// or past the search boundary (e.g. heading line end)
 		const closing_tag = `</${tag_name}>`;
+		const search_limit = Math.min(this.#max_search_index, this.#template.length);
+		const close_tag_index = this.#template.indexOf(closing_tag, content_start);
+		if (close_tag_index === -1 || close_tag_index >= search_limit) {
+			this.#index = start + 1;
+			return this.#make_text_node('<', start);
+		}
+		const para_break = this.#template.indexOf('\n\n', content_start);
+		if (para_break !== -1 && para_break < close_tag_index) {
+			this.#index = start + 1;
+			return this.#make_text_node('<', start);
+		}
+
+		// Phase 2: Tag validated — save accumulation state and parse children.
+		const saved_state = this.#save_accumulation_state();
+		this.#accumulated_text = '';
+		this.#nodes.length = 0;
+		this.#index = content_start;
+
 		const children: Array<MdzNode> = [];
 
 		while (this.#index < this.#template.length) {
-			// Check for closing tag
 			if (this.#match(closing_tag)) {
-				// Flush any accumulated text from children
 				this.#flush_text();
 				children.push(...this.#nodes);
 				this.#nodes.length = 0;
 
 				this.#index += closing_tag.length;
-
-				// Restore parent state before returning
 				this.#restore_accumulation_state(saved_state);
 
 				return {
@@ -885,17 +825,10 @@ export class MdzParser {
 			}
 		}
 
-		// Unclosed tag - reached EOF without finding closing tag
-		// Treat the opening tag as text - restore parent state
+		// Defensive: pre-check guarantees closing tag exists, but handle EOF gracefully
 		this.#restore_accumulation_state(saved_state);
-
 		this.#index = start + 1;
-		return {
-			type: 'Text',
-			content: '<',
-			start,
-			end: this.#index,
-		};
+		return this.#make_text_node('<', start);
 	}
 
 	/**
@@ -930,7 +863,7 @@ export class MdzParser {
 	/**
 	 * Restore previously saved text accumulation state.
 	 * Used to restore parent state when exiting nested structure parsing.
-	 * @param state - State object returned from `#save_accumulation_state()`
+	 * @param state - state object returned from `#save_accumulation_state()`
 	 */
 	#restore_accumulation_state(state: {
 		accumulated_text: string;
@@ -948,9 +881,9 @@ export class MdzParser {
 	 * Word boundary = not surrounded by word characters (A-Z, a-z, 0-9).
 	 * Used to prevent intraword emphasis for underscores and tildes.
 	 *
-	 * @param index - Position to check
-	 * @param check_before - Whether to check the character before this position
-	 * @param check_after - Whether to check the character after this position
+	 * @param index - position to check
+	 * @param check_before - whether to check the character before this position
+	 * @param check_after - whether to check the character after this position
 	 */
 	#is_at_word_boundary(index: number, check_before: boolean, check_after: boolean): boolean {
 		if (check_before && index > 0) {
@@ -1173,9 +1106,9 @@ export class MdzParser {
 	 * - Paragraph break (double newline) is encountered (allows block elements to interrupt inline formatting)
 	 * - `end_index` boundary is reached
 	 *
-	 * @param delimiter - The delimiter string to stop at (e.g., '**', '_', ']')
-	 * @param end_index - Optional maximum index to parse up to (for greedy/bounded parsing)
-	 * @returns Array of parsed nodes (may be empty if delimiter found immediately)
+	 * @param delimiter - the delimiter string to stop at (e.g., '**', '_', ']')
+	 * @param end_index - optional maximum index to parse up to (for greedy/bounded parsing)
+	 * @returns array of parsed nodes (may be empty if delimiter found immediately)
 	 */
 	#parse_nodes_until(delimiter: string, end_index?: number): Array<MdzNode> {
 		const nodes: Array<MdzNode> = [];
@@ -1354,31 +1287,29 @@ export class MdzParser {
 		// Consume the space after hashes (already verified to exist)
 		this.#index++;
 
-		// Parse inline content until newline
-		const content_nodes: Array<MdzNode> = [];
+		// Find end-of-line to bound nested parsers (prevents tag scanner from scanning past heading)
+		let eol = this.#template.indexOf('\n', this.#index);
+		if (eol === -1) eol = this.#template.length;
 
-		while (this.#index < this.#template.length) {
-			const char_code = this.#template.charCodeAt(this.#index);
+		const saved_max_search_index = this.#max_search_index;
+		this.#max_search_index = eol;
 
-			if (char_code === NEWLINE) {
-				break;
-			}
+		// Parse inline content until end of line
+		const content_nodes: Array<MdzNode> = [];
 
+		while (this.#index < eol) {
 			const node = this.#parse_node();
 			if (node.type === 'Text') {
-				// Check if text node includes a newline (since #parse_text doesn't stop at single newlines)
-				// If so, trim it and move index back
-				const newline_index = node.content.indexOf('\n');
-				if (newline_index !== -1) {
-					const trimmed_content = node.content.slice(0, newline_index);
+				// Trim if #parse_text overshot past the newline
+				if (node.end > eol) {
+					const trimmed_content = node.content.slice(0, eol - node.start);
 					if (trimmed_content) {
 						this.#accumulate_text(trimmed_content, node.start);
 					}
-					this.#index = node.start + newline_index;
+					this.#index = eol;
 					break;
-				} else {
-					this.#accumulate_text(node.content, node.start);
 				}
+				this.#accumulate_text(node.content, node.start);
 			} else {
 				this.#flush_text();
 				content_nodes.push(...this.#nodes);
@@ -1387,6 +1318,8 @@ export class MdzParser {
 			}
 		}
 
+		this.#max_search_index = saved_max_search_index;
+
 		this.#flush_text();
 		content_nodes.push(...this.#nodes);
 		this.#nodes.length = 0;
@@ -1396,6 +1329,7 @@ export class MdzParser {
 		return {
 			type: 'Heading',
 			level: level as 1 | 2 | 3 | 4 | 5 | 6,
+			id: mdz_heading_id(content_nodes),
 			children: content_nodes,
 			start,
 			end: this.#index,
@@ -1587,41 +1521,3 @@ export class MdzParser {
 		throw Error('Code block not properly closed');
 	}
 }
-
-/**
- * Check if a string is a URL (`https://` or `http://`).
- * Requires at least one valid character after the protocol.
- * Rejects whitespace and characters that can't start a valid hostname.
- */
-const URL_PATTERN = /^https?:\/\/[^\s)\]}<>.,:/?#!]/;
-export const mdz_is_url = (s: string): boolean => URL_PATTERN.test(s);
-
-/**
- * Resolves a relative path (`./` or `../`) against a base path.
- * The base is treated as a directory regardless of trailing slash
- * (`'/docs/mdz'` and `'/docs/mdz/'` behave identically).
- * Handles embedded `.` and `..` segments within the reference
- * (e.g., `'./a/../b'` → navigates up then down).
- * Clamps at root — excess `..` segments stop at `/` rather than escaping.
- *
- * @param reference A relative path starting with `./` or `../`.
- * @param base An absolute base path (e.g., `'/docs/mdz/'`). Empty string is treated as root.
- * @returns An absolute resolved path (e.g., `'/docs/mdz/grammar'`).
- */
-export const resolve_relative_path = (reference: string, base: string): string => {
-	const segments = base.split('/');
-	// Remove trailing empty from split (e.g., '/docs/mdz/' → ['', 'docs', 'mdz', ''])
-	// but keep the root segment ([''] from '' base or ['', ''] from '/').
-	if (segments.length > 1 && segments.at(-1) === '') segments.pop();
-	const trailing = reference.endsWith('/');
-	for (const segment of reference.split('/')) {
-		if (segment === '.' || segment === '') continue;
-		if (segment === '..') {
-			if (segments.length > 1) segments.pop(); // clamp at root
-		} else {
-			segments.push(segment);
-		}
-	}
-	if (trailing) segments.push('');
-	return segments.join('/');
-};

package/src/lib/mdz_helpers.ts

@@ -8,6 +8,7 @@
  */
 
 import type {MdzNode, MdzComponentNode, MdzElementNode} from './mdz.js';
+import {slugify} from '@fuzdev/fuz_util/path.js';
 
 // Character codes for performance
 export const BACKTICK = 96; // `
@@ -187,7 +188,7 @@ export const trim_trailing_punctuation = (url: string): string => {
 /**
  * Check if position in text is the start of an absolute path (starts with `/`).
  * Must be preceded by whitespace or be at the start of the string.
- * Rejects `//` (comments/protocol-relative) and `/ ` (bare slash).
+ * Rejects `//` (comments/protocol-relative) and slash followed by whitespace.
  */
 export const is_at_absolute_path = (text: string, index: number): boolean => {
 	if (text.charCodeAt(index) !== SLASH) return false;
@@ -197,13 +198,13 @@ export const is_at_absolute_path = (text: string, index: number): boolean => {
 	}
 	if (index + 1 >= text.length) return false;
 	const next_char = text.charCodeAt(index + 1);
-	return next_char !== SLASH && next_char !== SPACE && next_char !== NEWLINE;
+	return next_char !== SLASH && next_char !== SPACE && next_char !== NEWLINE && next_char !== TAB;
 };
 
 /**
  * Check if position in text is the start of a relative path (`./` or `../`).
  * Must be preceded by whitespace or be at the start of the string.
- * Requires at least one path character after the prefix.
+ * Rejects prefix followed by whitespace, slash, or end of string.
  */
 export const is_at_relative_path = (text: string, index: number): boolean => {
 	if (text.charCodeAt(index) !== PERIOD) return false;
@@ -219,16 +220,70 @@ export const is_at_relative_path = (text: string, index: number): boolean => {
 		text.charCodeAt(index + 2) === SLASH
 	) {
 		const after = text.charCodeAt(index + 3);
-		return after !== SPACE && after !== NEWLINE && after !== SLASH;
+		return after !== SPACE && after !== NEWLINE && after !== TAB && after !== SLASH;
 	}
 	// Check for ./ (at least 3 chars: ./x)
 	if (remaining >= 3 && text.charCodeAt(index + 1) === SLASH) {
 		const after = text.charCodeAt(index + 2);
-		return after !== SPACE && after !== NEWLINE && after !== SLASH;
+		return after !== SPACE && after !== NEWLINE && after !== TAB && after !== SLASH;
 	}
 	return false;
 };
 
+/**
+ * Extracts plain text content from an array of mdz nodes, recursing into children.
+ */
+export const mdz_text_content = (nodes: Array<MdzNode>): string =>
+	nodes
+		.map((n) => ('children' in n ? mdz_text_content(n.children) : 'content' in n ? n.content : ''))
+		.join('');
+
+/**
+ * Generates a lowercase slug id for a heading from its child nodes.
+ * Follows standard markdown conventions (GitHub, etc.) where heading IDs are lowercased.
+ * For case-preserving IDs (e.g. API declarations), see `docs_slugify` in `docs_helpers.svelte.ts`.
+ */
+export const mdz_heading_id = (nodes: Array<MdzNode>): string =>
+	slugify(mdz_text_content(nodes), false);
+
+/**
+ * Check if a string is a URL (`https://` or `http://`).
+ * Requires at least one valid character after the protocol.
+ * Rejects whitespace and characters that can't start a valid hostname.
+ */
+const URL_PATTERN = /^https?:\/\/[^\s)\]}<>.,:/?#!]/;
+export const mdz_is_url = (s: string): boolean => URL_PATTERN.test(s);
+
+/**
+ * Resolves a relative path (`./` or `../`) against a base path.
+ * The base is treated as a directory regardless of trailing slash
+ * (`'/docs/mdz'` and `'/docs/mdz/'` behave identically).
+ * Handles embedded `.` and `..` segments within the reference
+ * (e.g., `'./a/../b'` → navigates up then down).
+ * Clamps at root — excess `..` segments stop at `/` rather than escaping.
+ *
+ * @param reference - a relative path starting with `./` or `../`
+ * @param base - An absolute base path (e.g., `'/docs/mdz/'`). Empty string is treated as root.
+ * @returns an absolute resolved path (e.g., `'/docs/mdz/grammar'`)
+ */
+export const resolve_relative_path = (reference: string, base: string): string => {
+	const segments = base.split('/');
+	// Remove trailing empty from split (e.g., '/docs/mdz/' → ['', 'docs', 'mdz', ''])
+	// but keep the root segment ([''] from '' base or ['', ''] from '/').
+	if (segments.length > 1 && segments.at(-1) === '') segments.pop();
+	const trailing = reference.endsWith('/');
+	for (const segment of reference.split('/')) {
+		if (segment === '.' || segment === '') continue;
+		if (segment === '..') {
+			if (segments.length > 1) segments.pop(); // clamp at root
+		} else {
+			segments.push(segment);
+		}
+	}
+	if (trailing) segments.push('');
+	return segments.join('/');
+};
+
 export const extract_single_tag = (
 	nodes: Array<MdzNode>,
 ): MdzComponentNode | MdzElementNode | null => {

package/src/lib/mdz_lexer.ts

@@ -7,8 +7,8 @@
  * @module
  */
 
-import {mdz_is_url} from './mdz.js';
 import {
+	mdz_is_url,
 	is_letter,
 	is_tag_name_char,
 	is_word_char,
@@ -276,14 +276,17 @@ export class MdzLexer {
 			end: this.#index, // end of "## " prefix
 		});
 
+		// Find end-of-line to bound nested tokenizers (prevents tag scanner from scanning past heading)
+		let eol = this.#text.indexOf('\n', this.#index);
+		if (eol === -1) eol = this.#text.length;
+
+		const saved_max = this.#max_search_index;
+		this.#max_search_index = eol;
+
 		// Tokenize inline content until newline or EOF
 		// tokenize_text may consume a newline as part of block-element lookahead,
 		// so we check emitted text tokens for embedded newlines and trim.
-		while (this.#index < this.#text.length) {
-			if (this.#text.charCodeAt(this.#index) === NEWLINE) {
-				break;
-			}
-
+		while (this.#index < eol) {
 			const token_count_before = this.#tokens.length;
 			this.#tokenize_inline();
 
@@ -307,6 +310,8 @@ export class MdzLexer {
 			}
 		}
 
+		this.#max_search_index = saved_max;
+
 		// Emit heading_end marker so the token parser knows where heading content stops
 		this.#tokens.push({type: 'heading_end', start: this.#index, end: this.#index});
 
@@ -798,11 +803,17 @@ export class MdzLexer {
 		}
 		this.#index++; // consume >
 
-		// Check for closing tag existence before committing
+		// Check for closing tag existence before committing —
+		// must exist within search boundary and before any paragraph break
 		const closing_tag = `</${tag_name}>`;
+		const search_limit = Math.min(this.#max_search_index, this.#text.length);
 		const closing_tag_pos = this.#text.indexOf(closing_tag, this.#index);
-		if (closing_tag_pos === -1) {
-			// No closing tag - revert
+		if (closing_tag_pos === -1 || closing_tag_pos >= search_limit) {
+			this.#index = start + 1;
+			this.#emit_text('<', start);
+			return;
+		}
+		if (this.#has_paragraph_break_between(this.#index, closing_tag_pos)) {
 			this.#index = start + 1;
 			this.#emit_text('<', start);
 			return;

package/src/lib/mdz_to_svelte.ts

@@ -12,7 +12,8 @@ import {UnreachableError} from '@fuzdev/fuz_util/error.js';
 import {escape_svelte_text} from '@fuzdev/fuz_util/svelte_preprocess_helpers.js';
 import {escape_js_string} from '@fuzdev/fuz_util/string.js';
 
-import {type MdzNode, resolve_relative_path} from './mdz.js';
+import type {MdzNode} from './mdz.js';
+import {resolve_relative_path} from './mdz_helpers.js';
 
 /**
  * Result of converting `MdzNode` arrays to Svelte markup.
@@ -34,12 +35,12 @@ export interface MdzToSvelteResult {
  * Each node type produces output matching what `MdzNodeView.svelte` renders at runtime.
  * Collects required imports and flags unconfigured component/element references.
  *
- * @param nodes Parsed mdz nodes to render.
- * @param components Component name to import path mapping (e.g., `{Alert: '$lib/Alert.svelte'}`).
+ * @param nodes - parsed mdz nodes to render
+ * @param components - Component name to import path mapping (e.g., `{Alert: '$lib/Alert.svelte'}`)
  *   If content references a component not in this map, `has_unconfigured_tags` is set.
- * @param elements Allowed HTML element names (e.g., `new Set(['aside', 'details'])`).
+ * @param elements - Allowed HTML element names (e.g., `new Set(['aside', 'details'])`)
  *   If content references an element not in this set, `has_unconfigured_tags` is set.
- * @param base Base path for resolving relative links (e.g., `'/docs/mdz/'`).
+ * @param base - Base path for resolving relative links (e.g., `'/docs/mdz/'`)
  *   When provided, relative references (`./`, `../`) are resolved to absolute paths
  *   and passed through `resolve()`. Trailing slash recommended.
  */

package/src/lib/mdz_token_parser.ts

@@ -18,7 +18,7 @@ import type {
 	MdzElementNode,
 	MdzComponentNode,
 } from './mdz.js';
-import {extract_single_tag} from './mdz_helpers.js';
+import {extract_single_tag, mdz_heading_id} from './mdz_helpers.js';
 import {
 	MdzLexer,
 	type MdzToken,
@@ -124,9 +124,10 @@ class MdzTokenParser {
 			if (node) children.push(node);
 		}
 
-		const end = children.length > 0 ? children[children.length - 1]!.end : start + level + 1;
+		const merged = this.#merge_adjacent_text(children);
+		const end = merged.length > 0 ? merged[merged.length - 1]!.end : start + level + 1;
 
-		return {type: 'Heading', level, children, start, end};
+		return {type: 'Heading', level, id: mdz_heading_id(merged), children: merged, start, end};
 	}
 
 	#parse_inline(): MdzNode | null {

package/src/lib/module_helpers.ts

@@ -174,8 +174,8 @@ export const MODULE_SOURCE_PARTIAL: ModuleSourcePartial = {
 /**
  * Create complete source options from project root and optional overrides.
  *
- * @param project_root Absolute path to project root (typically `process.cwd()`)
- * @param overrides Optional overrides for default options
+ * @param project_root - absolute path to project root (typically `process.cwd()`)
+ * @param overrides - optional overrides for default options
  *
  * @example
  * ```ts
@@ -348,8 +348,8 @@ export const module_get_source_root = (options: ModuleSourceOptions): string =>
  *
  * Uses proper path semantics: strips `project_root/source_root/` prefix.
  *
- * @param source_id Absolute path to the source file
- * @param options Module source options for path extraction
+ * @param source_id - absolute path to the source file
+ * @param options - module source options for path extraction
  *
  * @example
  * ```ts
@@ -430,9 +430,9 @@ export const module_is_test = (path: string): boolean => path.endsWith('.test.ts
  * `project_root/source_path/`. No heuristics needed - nested directories
  * are correctly excluded by the prefix check.
  *
- * @param path Full absolute path to check
- * @param options Module source options for filtering
- * @returns True if the path is an analyzable source file
+ * @param path - full absolute path to check
+ * @param options - module source options for filtering
+ * @returns true if the path is an analyzable source file
  *
  * @example
  * ```ts
@@ -465,8 +465,8 @@ export const module_is_source = (path: string, options: ModuleSourceOptions): bo
  * Filters to only include source modules (excludes external packages, node_modules, tests).
  * Returns sorted arrays of module paths (relative to source_root) for deterministic output.
  *
- * @param source_file The source file info to extract dependencies from
- * @param options Module source options for filtering and path extraction
+ * @param source_file - the source file info to extract dependencies from
+ * @param options - module source options for filtering and path extraction
  */
 export const module_extract_dependencies = (
 	source_file: SourceFileInfo,