@fuzdev/mdz 0.8.1 → 0.10.0

package/src/lib/mdz_stream_parser_url.ts

@@ -18,8 +18,14 @@ import {
 	SPACE,
 	TAB,
 	PERIOD,
+	LEFT_PAREN,
+	RIGHT_PAREN,
 	SLASH,
 	ascii_to_lower,
+	is_bare_path_prefix,
+	is_italic_boundary_blocker,
+	scan_uri_chars_end,
+	is_path_boundary,
 	is_valid_path_char,
 	is_word_char,
 	match_url_prefix_case_insensitive,
@@ -33,7 +39,9 @@ import {
 	emit,
 	ensure_paragraph,
 	flush_text,
-	offset
+	is_run_boundary,
+	offset,
+	revert_failed_close
 } from './mdz_stream_parser_state.ts';
 
 const HTTPS_PREFIX = 'https://';
@@ -62,15 +70,8 @@ export const try_auto_url_forced = (state: MdzStreamParserState): TryResult => {
 
 /** @nodocs */
 export const try_auto_path_absolute = (state: MdzStreamParserState, forced = false): TryResult => {
-	// must be at word boundary (preceded by space/newline/start)
-	if (
-		state.prev_char !== -1 &&
-		state.prev_char !== SPACE &&
-		state.prev_char !== NEWLINE &&
-		state.prev_char !== TAB
-	) {
-		return 'not_match';
-	}
+	// must be at a path boundary (start, whitespace, or `(`)
+	if (!is_path_boundary(state.prev_char, state.before_prev_char)) return 'not_match';
 
 	// reject // and /space
 	if (state.pos + 1 >= state.buffer.length) return forced ? 'not_match' : 'need_more';
@@ -86,14 +87,8 @@ export const try_auto_path_absolute = (state: MdzStreamParserState, forced = fal
 
 /** @nodocs */
 export const try_auto_path_relative = (state: MdzStreamParserState, forced = false): TryResult => {
-	if (
-		state.prev_char !== -1 &&
-		state.prev_char !== SPACE &&
-		state.prev_char !== NEWLINE &&
-		state.prev_char !== TAB
-	) {
-		return 'not_match';
-	}
+	// must be at a path boundary (start, whitespace, or `(`)
+	if (!is_path_boundary(state.prev_char, state.before_prev_char)) return 'not_match';
 
 	// check for ./ or ../
 	const remaining = state.buffer.length - state.pos;
@@ -147,7 +142,9 @@ export const start_pending_url = (
 		link_type,
 		confirmed: true,
 		viable_https: false,
-		viable_http: false
+		viable_http: false,
+		// a path opened by `(` ends at the `)` matching it
+		paren_depth: state.prev_char === LEFT_PAREN ? 0 : -1
 	};
 	// don't advance pos — URL chars start at current position, handled by process_url_content
 };
@@ -169,7 +166,8 @@ export const start_speculative_url = (state: MdzStreamParserState): void => {
 		link_type: 'external',
 		confirmed: false,
 		viable_https: true,
-		viable_http: true
+		viable_http: true,
+		paren_depth: -1
 	};
 };
 
@@ -227,8 +225,9 @@ export const process_url_prefix = (state: MdzStreamParserState): void => {
 
 /**
  * Process URL/path chars in text-first mode. Scans path chars,
- * accumulates as visible text. Terminates on space/newline/non-path-char
- * and emits a `wrap` opcode.
+ * accumulates as visible text. Terminates on space/newline/non-path-char —
+ * or, for a path opened by `(`, on the `)` matching that opener — and emits
+ * a `wrap` opcode.
  *
  * @nodocs
  */
@@ -239,37 +238,108 @@ export const process_url_content = (state: MdzStreamParserState, forced: boolean
 		return;
 	}
 
-	const char_code = state.buffer.charCodeAt(state.pos);
-
-	// URL terminator
-	if (char_code === SPACE || char_code === NEWLINE || !is_valid_path_char(char_code)) {
-		flush_text(state);
-		complete_pending_url(state);
-		// don't consume terminator — outer loop handles it
-		return;
-	}
-
-	// scan URL chars
+	const pu = state.pending_url!;
 	const start = state.pos;
-	state.pos++;
 	while (state.pos < state.buffer.length) {
 		const c = state.buffer.charCodeAt(state.pos);
-		if (c === SPACE || c === NEWLINE || !is_valid_path_char(c)) break;
+		if (!is_valid_path_char(c)) break;
+		if (pu.paren_depth !== -1) {
+			if (c === LEFT_PAREN) pu.paren_depth++;
+			else if (c === RIGHT_PAREN) {
+				if (pu.paren_depth === 0) break;
+				pu.paren_depth--;
+			}
+		}
 		state.pos++;
 	}
-	const text = state.buffer.slice(start, state.pos);
-	accumulate_text(state, text, offset(state, start));
-	state.pending_url!.url_text += text;
-	state.prev_char = state.buffer.charCodeAt(state.pos - 1);
-	state.column += state.pos - start;
-
-	// at EOF in forced mode, finalize the URL
-	if (state.pos >= state.buffer.length && forced) {
+
+	if (state.pos > start) {
+		const text = state.buffer.slice(start, state.pos);
+		accumulate_text(state, text, offset(state, start));
+		pu.url_text += text;
+		state.prev_char = state.buffer.charCodeAt(state.pos - 1);
+		state.column += state.pos - start;
+	}
+
+	// a terminator in the buffer ends the URL (not consumed — the outer loop
+	// handles it); at EOF in forced mode the buffer end does
+	if (state.pos < state.buffer.length || forced) {
 		flush_text(state);
 		complete_pending_url(state);
 	}
 };
 
+// the char at the parse position, or `-1` at the end of the buffer
+const char_after_pos = (state: MdzStreamParserState): number =>
+	state.pos < state.buffer.length ? state.buffer.charCodeAt(state.pos) : -1;
+
+/**
+ * Resolve the open spans whose first closer candidate an auto-link swallowed,
+ * the way the one-shot parse does. The lexer pairs each `**`/`~~`/`_` opener
+ * with the first occurrence of its delimiter after it
+ * (`#tokenize_double_delimiter`, `#tokenize_italic`). Streaming resolves each
+ * open span's earlier candidates as they arrive, so a delimiter inside the
+ * link's reference is that first occurrence, and the lexer's outcome depends
+ * on the span:
+ *
+ * - `**` and `~~` pair with the occurrence unconditionally; the span's children
+ *   lex bounded by it, the link overruns it, and the opener stays literal —
+ *   as does every delimiter, tag, and code opener lexed inside the span (each
+ *   bounded by the swallowed closer). Markdown links aren't bounded by an
+ *   enclosing span, so Link frames survive.
+ * - `_` first checks the candidate's closing boundary (`is_italic_boundary_blocker`
+ *   on the char after it). A blocked candidate rejects only the opener — the
+ *   span's content then lexes unbounded, so inner spans survive — while a
+ *   valid one pairs and overruns like the doubled delimiters.
+ *
+ * So: the lowest span in the current run that pairs inside the reference is
+ * reverted along with every non-Link frame above it, and an italic below it
+ * with a blocked candidate is reverted alone (mid-stack, frames above it kept).
+ * Called after the link's `wrap`/`close` is emitted, so a pending wrap never
+ * outlives an enclosing revert.
+ *
+ * @param scanned - the scanned URL/path text, starting with `reference` and
+ *   including any trimmed tail
+ * @param after_scanned - the char code after `scanned`, or `-1` at end of input
+ */
+const revert_spans_closed_inside = (
+	state: MdzStreamParserState,
+	reference: string,
+	scanned: string,
+	after_scanned: number
+): void => {
+	let run_start = 0;
+	for (let i = state.stack.length - 1; i >= 0; i--) {
+		if (is_run_boundary(state.stack[i]!.node_type)) {
+			run_start = i + 1;
+			break;
+		}
+	}
+	let paired = -1; // lowest span pairing inside the reference
+	let rejected_italic = -1; // an italic whose candidate's boundary is blocked
+	for (let i = run_start; i < state.stack.length && paired === -1; i++) {
+		const entry = state.stack[i]!;
+		if (entry.node_type === 'Bold' || entry.node_type === 'Strikethrough') {
+			if (reference.includes(entry.delimiter)) paired = i;
+		} else if (entry.node_type === 'Italic') {
+			const k = reference.indexOf('_');
+			if (k === -1) continue;
+			const after = k + 1 < scanned.length ? scanned.charCodeAt(k + 1) : after_scanned;
+			if (after !== -1 && is_italic_boundary_blocker(after)) rejected_italic = i;
+			else paired = i;
+		}
+	}
+	if (paired !== -1) {
+		for (let i = state.stack.length - 1; i >= paired; i--) {
+			if (state.stack[i]!.node_type !== 'Link') revert_failed_close(state, i);
+		}
+	}
+	// below `paired` (or with nothing paired) — indices below it are unchanged
+	if (rejected_italic !== -1 && (paired === -1 || rejected_italic < paired)) {
+		revert_failed_close(state, rejected_italic);
+	}
+};
+
 /**
  * Complete a pending URL: compute reference with trimmed punctuation,
  * emit a `wrap` opcode to retroactively wrap the text node in a Link.
@@ -287,6 +357,8 @@ export const complete_pending_url = (state: MdzStreamParserState): void => {
 
 	const reference = mdz_trim_url_punctuation(pu.url_text);
 	if (reference.length === 0) return; // empty after trimming — text stays as plain text
+	// a bare path prefix (`./`, `/`) left after trimming isn't a path — text stays
+	if (pu.link_type === 'internal' && is_bare_path_prefix(reference)) return;
 
 	// for external URLs, must have content after protocol prefix
 	if (pu.link_type === 'external') {
@@ -316,6 +388,7 @@ export const complete_pending_url = (state: MdzStreamParserState): void => {
 			trim_id
 		});
 		state.active_text_id = trim_id;
+		revert_spans_closed_inside(state, reference, pu.url_text, char_after_pos(state));
 	} else {
 		emit(state, {
 			type: 'wrap',
@@ -328,6 +401,7 @@ export const complete_pending_url = (state: MdzStreamParserState): void => {
 			end: url_end
 		});
 		state.active_text_id = null;
+		revert_spans_closed_inside(state, reference, pu.url_text, char_after_pos(state));
 	}
 };
 
@@ -341,16 +415,17 @@ export const scan_auto_link_forced = (
 	state: MdzStreamParserState,
 	link_type: 'external' | 'internal'
 ): TryResult => {
-	let i = state.pos;
-	while (i < state.buffer.length) {
-		const c = state.buffer.charCodeAt(i);
-		if (c === SPACE || c === NEWLINE || !is_valid_path_char(c)) break;
-		i++;
-	}
+	// a path opened by `(` ends at the `)` matching it
+	const i = scan_uri_chars_end(
+		state.buffer,
+		state.pos,
+		link_type === 'internal' && state.prev_char === LEFT_PAREN
+	);
 
 	let reference = state.buffer.slice(state.pos, i);
 	reference = mdz_trim_url_punctuation(reference);
 	if (reference.length === 0) return 'not_match';
+	if (link_type === 'internal' && is_bare_path_prefix(reference)) return 'not_match';
 
 	// for external URLs, must have content after protocol prefix
 	if (link_type === 'external') {
@@ -382,5 +457,11 @@ export const scan_auto_link_forced = (
 	state.column += end_pos - state.pos;
 	state.prev_char = reference.charCodeAt(reference.length - 1);
 	state.pos = end_pos;
+	revert_spans_closed_inside(
+		state,
+		reference,
+		state.buffer.slice(link_start - state.base_offset, i),
+		i < state.buffer.length ? state.buffer.charCodeAt(i) : -1
+	);
 	return 'consumed';
 };

package/src/lib/svelte_preprocess_mdz.ts

@@ -397,9 +397,17 @@ const find_mdz_usages = (
 			const inline = inline_attr ? extract_static_boolean(inline_attr.value) : false;
 			if (inline === null) return; // dynamic inline — fall back to runtime
 
+			// precompiled markup carries no source offsets, so content that asks for
+			// them renders at runtime; a static `false` asks for nothing and is dropped
+			const source_offsets_attr = find_attribute(node, 'source_offsets');
+			if (source_offsets_attr && extract_static_boolean(source_offsets_attr.value) !== false) {
+				return;
+			}
+
 			// Collect attributes to exclude from precompiled output
 			const exclude_attrs: Set<AST.Attribute> = new Set([content_attr]);
 			if (base_attr) exclude_attrs.add(base_attr);
+			if (source_offsets_attr) exclude_attrs.add(source_offsets_attr);
 
 			// Extract static string value
 			const content_value = extract_static_string(content_attr.value, context.bindings);

package/src/lib/tsdoc_mdz.ts

@@ -20,11 +20,12 @@ const format_reference = (ref: string): string => (mdz_is_url(ref) ? ref : `\`${
  * - `{@link url|text}` → `[text](url)` (markdown link, TSDoc canonical form)
  * - `{@link url text}` → `[text](url)` (TS-lenient space-separated form)
  * - `{@link https://...}` → `https://...` (bare URL, auto-linked by mdz)
- * - `{@link identifier}` → `` `identifier` `` (code formatting)
+ * - `{@link identifier}` → the identifier as a code span
  * - Bare URLs → returned as-is
  * - Bare markdown links (`[text](url)` ...) → returned as-is
+ * - Content that opens with a backtick (a code span, then description text) → returned as-is
  * - Bare identifiers → wrapped in backticks
- * - `identifier description text` → `` `identifier` description text `` (first token is the reference)
+ * - `identifier description text` → the first token wrapped in backticks, the rest as written
  *
  * @param content - raw `@see` tag content in TSDoc format
  * @returns mdz-formatted string ready for `Mdz` component
@@ -40,11 +41,14 @@ const format_reference = (ref: string): string => (mdz_is_url(ref) ? ref : `\`${
  * mdz_from_tsdoc('https://fuz.dev')
  * // → 'https://fuz.dev'
  *
- * mdz_from_tsdoc('[svelte-docinfo](https://github.com/ryanatkn/svelte-docinfo) for the analysis library')
- * // → '[svelte-docinfo](https://github.com/ryanatkn/svelte-docinfo) for the analysis library'
+ * mdz_from_tsdoc('[svelte-docinfo](https://github.com/fuzdev/svelte-docinfo) for the analysis library')
+ * // → '[svelte-docinfo](https://github.com/fuzdev/svelte-docinfo) for the analysis library'
  *
  * mdz_from_tsdoc('tome.ts for the documentation system')
  * // → '`tome.ts` for the documentation system'
+ *
+ * mdz_from_tsdoc('`tome.ts` for the `Tome` type')
+ * // → '`tome.ts` for the `Tome` type'
  * ```
  */
 export const mdz_from_tsdoc = (content: string): string => {
@@ -85,6 +89,13 @@ export const mdz_from_tsdoc = (content: string): string => {
 		return trimmed;
 	}
 
+	// Pass through content that opens with a backtick: a leading code span is already mdz,
+	// and wrapping it again would leave both spans literal. An unclosed one is returned as
+	// written too, since adding a backtick the author didn't write can't make it a span.
+	if (trimmed.charCodeAt(0) === 96 /* ` */) {
+		return trimmed;
+	}
+
 	// Split at first whitespace: first token is the reference, rest is description
 	const space_index = trimmed.indexOf(' ');
 	if (space_index === -1) {