@linxiraos/pi-utils 1.1.26 → 1.2.0

package/src/json-lexer.ts

@@ -32,6 +32,16 @@ export const LBRACKET = 0x5b;
 export const RBRACKET = 0x5d;
 const U = 0x75;
 
+/**
+ * Minimum remaining string length for bulk-skipping ordinary characters in
+ * {@link JsonLexer.string} with two engine `indexOf` scans (nearest quote or
+ * backslash) instead of one `charCodeAt` per character. Below this the
+ * `indexOf` setup costs more than the per-char loop on quote-dense input;
+ * long string runs — the multi-KB tool-argument payloads that dominate
+ * streaming re-parses — scan several times faster above it.
+ */
+const STRING_BULK_SCAN_MIN = 32;
+
 /** Valid chars after `\` in a strict JSON escape: `" \ / b f n r t u`. */
 export const VALID_ESCAPE_CHAR = new Uint8Array(128);
 for (const ch of '"\\/bfnrtu') VALID_ESCAPE_CHAR[ch.charCodeAt(0)] = 1;
@@ -176,6 +186,17 @@ const enum QuoteLook {
  */
 export class JsonLexer {
 	pos: number;
+	/**
+	 * Shared across {@link string} calls: `src` has no backslash in
+	 * `[#backslashFrom, #backslashAt)` and `#backslashAt` is a backslash or
+	 * `src.length`. An escape-free run can extend past its string's closing
+	 * quote to the end of the document, so searching per string would rescan
+	 * the same tail for every sibling string (quadratic on objects with many
+	 * short values). `src` is immutable, so the range never goes stale; a
+	 * cursor outside it (e.g. a rollback) re-searches.
+	 */
+	#backslashFrom = 0;
+	#backslashAt = -1;
 
 	constructor(
 		readonly src: string,
@@ -218,7 +239,40 @@ export class JsonLexer {
 		// malformed structure fails loudly instead of silently swallowing
 		// commas/colons or sibling members.
 		const lenient = quote === SQUOTE || this.mode === "streaming";
+		// Any delimiter code unit, not just `"`/`'`; a value above 0xFFFF matches
+		// no code unit, so such a string never closes.
+		const quoteChar = String.fromCharCode(quote);
+		// Next quote / backslash at or after the cursor, cached across iterations
+		// and re-searched only once the cursor passes them, so every character is
+		// scanned at most once per kind and the bulk path stays linear even on
+		// escape-dense input (re-searching the far closing quote after each
+		// escape would be quadratic). `n` means "none before end of input". The
+		// backslash search result is shared across calls via `#backslashAt`.
+		let nextQuote = quoteChar.charCodeAt(0) === quote ? -1 : n;
+		let nextBackslash = -1;
 		while (i < n) {
+			// Bulk-skip a run of ordinary characters: jump to the nearest quote or
+			// backslash instead of one `charCodeAt` per character. Only entered on
+			// an ordinary character, so back-to-back escapes never pay an `indexOf`;
+			// short tails keep the per-char loop. Landing on a special char falls
+			// through to the unchanged handling below, so tokens are identical.
+			const c0 = s.charCodeAt(i);
+			if (c0 !== BACKSLASH && c0 !== quote && n - i > STRING_BULK_SCAN_MIN) {
+				if (nextQuote < i) {
+					const q = s.indexOf(quoteChar, i);
+					nextQuote = q === -1 ? n : q;
+				}
+				if (nextBackslash < i) {
+					if (i < this.#backslashFrom || i > this.#backslashAt) {
+						const b = s.indexOf("\\", i);
+						this.#backslashFrom = i;
+						this.#backslashAt = b === -1 ? n : b;
+					}
+					nextBackslash = this.#backslashAt;
+				}
+				i = nextQuote < nextBackslash ? nextQuote : nextBackslash;
+				if (i >= n) break;
+			}
 			const cc = s.charCodeAt(i);
 			if (cc !== BACKSLASH && cc !== quote) {
 				i++;

package/src/json-parse.ts

@@ -309,15 +309,30 @@ export function parseJsonWithRepair<T>(json: string): T {
 export function parseStreamingJson<T = Record<string, unknown>>(partialJson: string | undefined): T {
 	const trimmed = partialJson?.trimStart();
 	if (!trimmed) return {} as T;
+	// A container can only be strict JSON once its closer arrived; skip the
+	// doomed full-buffer JSON.parse (and its SyntaxError) while it streams.
+	const first = trimmed.charCodeAt(0);
+	if ((first !== 0x7b && first !== 0x5b) || canCloseContainer(trimmed)) {
+		try {
+			return JSON.parse(trimmed) as T;
+		} catch {}
+	}
 	try {
-		return JSON.parse(trimmed) as T;
+		return (new RelaxedJson(trimmed, true).parse() ?? {}) as T;
 	} catch {
-		try {
-			return (new RelaxedJson(trimmed, true).parse() ?? {}) as T;
-		} catch {
-			return {} as T;
-		}
+		return {} as T;
+	}
+}
+
+/** True when the last non-whitespace character is `}` or `]`. */
+function canCloseContainer(text: string): boolean {
+	for (let i = text.length - 1; i >= 0; i--) {
+		const code = text.charCodeAt(i);
+		// JSON whitespace: space, \t, \n, \r
+		if (code === 0x20 || code === 0x09 || code === 0x0a || code === 0x0d) continue;
+		return code === 0x7d || code === 0x5d;
 	}
+	return false;
 }
 
 /**

package/src/logger/rotating-file.ts

@@ -109,11 +109,13 @@ export class RotatingFileSink {
 	/**
 	 * Append one already-formatted log record. A batching sink buffers it unless
 	 * `flushNow` is set or the buffer reached its size threshold; either way the
-	 * whole buffer, this record included, is then written in order.
+	 * whole buffer, this record included, is then written in order. `day` is the
+	 * record's `localDay` key, so callers that already took the record's `Date`
+	 * reuse it.
 	 */
-	write(line: string, flushNow = false): void {
+	write(line: string, flushNow = false, day = localDay(new Date())): void {
 		if (this.#closed) return;
-		this.#selectFile(localDay(new Date()));
+		this.#selectFile(day);
 		const record = `${line}${os.EOL}`;
 		const bytes = Buffer.byteLength(record, "utf8");
 		this.#pending += record;

package/src/logger.ts

@@ -209,9 +209,28 @@ function jsonReplacer(_key: string, value: unknown): unknown {
 	return value;
 }
 
-interface NormalizedLogInfo extends Record<string, unknown> {
-	level: LogLevel;
-	message: unknown;
+// Values visited by the Error pre-scan before falling back to the replacer.
+const ERROR_SCAN_BUDGET = 128;
+
+/**
+ * Whether `value` may contain an {@link Error} that {@link jsonReplacer} must
+ * unwrap. Walks what `JSON.stringify` serializes (arrays and own enumerable
+ * keys); objects with a `toJSON` other than `Date` may return an Error, and an
+ * exhausted budget answers true.
+ */
+function mayContainError(root: unknown): boolean {
+	const stack: unknown[] = [root];
+	let budget = ERROR_SCAN_BUDGET;
+	while (stack.length > 0) {
+		const value = stack.pop();
+		if (value === null || typeof value !== "object") continue;
+		if (value instanceof Error) return true;
+		if (--budget < 0) return true;
+		if (value instanceof Date) continue;
+		if ("toJSON" in value && typeof value.toJSON === "function") return true;
+		for (const child of Object.values(value)) stack.push(child);
+	}
+	return false;
 }
 
 function padTimestampPart(value: number, width = 2): string {
@@ -232,33 +251,30 @@ function formatLocalTimestamp(date: Date): string {
 
 const FORMAT_TOKEN_PATTERN = /%[scdjifoO%]/;
 
-function normalizeLogInfo(
+/** Serialize one log record: timestamp, level, pid, message, then context fields. */
+function formatLogRecord(
 	level: LogLevel,
 	message: string,
 	context: Record<string, unknown> | undefined,
-): NormalizedLogInfo {
+	timestamp: string,
+): string {
 	const metadata =
 		!FORMAT_TOKEN_PATTERN.test(message) && context !== null && typeof context === "object" ? context : undefined;
-	const info = Object.assign({}, metadata, { level, message }) as NormalizedLogInfo;
-	if (metadata?.message) info.message = `${message} ${metadata.message}`;
-	if (metadata?.stack) info.stack = metadata.stack;
-	if (metadata?.cause) info.cause = metadata.cause;
-	return info;
-}
-
-function formatLogInfo(info: NormalizedLogInfo): string {
-	const timestamp = formatLocalTimestamp(new Date());
-	info.timestamp = timestamp;
 	const entry: Record<string, unknown> = {
 		timestamp,
-		level: info.level,
+		level,
 		pid: process.pid,
-		message: info.message,
+		message: metadata?.message ? `${message} ${metadata.message}` : message,
 	};
-	for (const [key, value] of Object.entries(info)) {
-		if (key !== "level" && key !== "timestamp" && key !== "message") entry[key] = value;
+	if (metadata) {
+		for (const key of Object.keys(metadata)) {
+			if (key !== "level" && key !== "timestamp" && key !== "message") entry[key] = metadata[key];
+		}
+		// An Error passed as the context carries these as non-enumerable fields.
+		if (metadata.stack) entry.stack = metadata.stack;
+		if (metadata.cause) entry.cause = metadata.cause;
 	}
-	return JSON.stringify(entry, jsonReplacer) as string;
+	return mayContainError(entry) ? JSON.stringify(entry, jsonReplacer) : JSON.stringify(entry);
 }
 
 /** Longest a buffered file record waits before it is written. */
@@ -361,9 +377,9 @@ function emitLocally(level: LogLevel, message: string, context: Record<string, u
 	const rank = LOG_LEVEL_RANK[level];
 	const file = rank <= transports.fileLevelRank ? transports.file : undefined;
 	if (!file && !transports.console) return;
-	const info = normalizeLogInfo(level, message, context);
-	const line = formatLogInfo(info);
-	file?.write(line, rank <= IMMEDIATE_FLUSH_RANK || exiting);
+	const now = new Date();
+	const line = formatLogRecord(level, message, context, formatLocalTimestamp(now));
+	file?.write(line, rank <= IMMEDIATE_FLUSH_RANK || exiting, localDay(now));
 	if (transports.console) fs.writeSync(1, `${line}${os.EOL}`);
 }
 

package/src/loop-phase.ts

@@ -1,8 +1,16 @@
+/** A label and its exclusive in-window time, as named by {@link takeLoopPhaseAttribution}. */
+export interface LoopPhaseAttribution {
+	readonly label: string;
+	/** Total time this label was the innermost active phase inside the late window [start, end]. */
+	readonly ms: number;
+}
+
 /**
- * Live event-loop phase breadcrumb. Hot synchronous paths push a short label
- * before running and pop it after (via `try`/`finally`); the loop watchdog
- * reads {@link takeRecentLoopPhase} when it detects a block, so a stall is
- * logged with the work that caused it instead of an opaque "unknown".
+ * Process-global synchronous loop phases. The watchdog arms a late window and
+ * reads attribution via {@link takeLoopPhaseAttribution}; attribution totals
+ * only the innermost label's time inside that window. A label is named only
+ * when its total outweighs all unlabeled time, otherwise the block remains
+ * "unknown". Disarmed push/pop do not read the clock.
  *
  * This is deliberately a process-global stack and not part of the logger span
  * machinery: `main.ts` ends timing spans before the interactive TUI starts, so
@@ -16,19 +24,31 @@
  * work, push/pop around each synchronous chunk, not across the await.
  */
 const stack: string[] = [];
-// The most recent label pushed, retained after it is popped. A hot path pushes
-// and pops a phase entirely within one synchronous macrotask, so by the time
-// the watchdog's delayed tick runs the stack is already empty; this slot keeps
-// the culprit available for that one tick. Consumed (cleared) on read so it
-// only attributes the just-elapsed interval.
-let recentPhase: string | undefined;
+const defaultClock = () => performance.now();
+let windowStart = Number.POSITIVE_INFINITY;
+let segmentStart = windowStart;
+let clock = defaultClock;
+const totals = new Map<string, number>();
+let labeledMs = 0;
+
+function boundary(t: number): void {
+	const ms = Math.max(0, t - Math.max(segmentStart, windowStart));
+	const label = stack[stack.length - 1];
+	if (label !== undefined && ms > 0) {
+		totals.set(label, (totals.get(label) ?? 0) + ms);
+		labeledMs += ms;
+	}
+	segmentStart = t;
+}
 
 export function pushLoopPhase(label: string): void {
+	if (windowStart !== Number.POSITIVE_INFINITY) boundary(clock());
 	stack.push(label);
-	recentPhase = label;
 }
 
 export function popLoopPhase(): void {
+	if (stack.length === 0) return;
+	if (windowStart !== Number.POSITIVE_INFINITY) boundary(clock());
 	stack.pop();
 }
 
@@ -36,14 +56,39 @@ export function currentLoopPhase(): string | undefined {
 	return stack[stack.length - 1];
 }
 
-/**
- * Phase to blame for a just-detected loop block: the live top phase if one is
- * still held, else the most recent phase pushed since the last call. Clears the
- * recent slot so a block in a later, phase-less interval is not misattributed
- * to a phase that already finished.
- */
-export function takeRecentLoopPhase(): string | undefined {
-	const phase = stack[stack.length - 1] ?? recentPhase;
-	recentPhase = undefined;
-	return phase;
+/** Run `fn` under `label`. For an async `fn`, only its synchronous prefix (up to its first await) is labeled; label each continuation separately. */
+export function withLoopPhase<T>(label: string, fn: () => T): T {
+	pushLoopPhase(label);
+	try {
+		return fn();
+	} finally {
+		popLoopPhase();
+	}
+}
+
+/** Arm an attribution window starting at `start` (a deadline on `now`'s clock). Called with no arguments it disarms and clears. */
+export function resetLoopPhaseWindow(start = Number.POSITIVE_INFINITY, now: () => number = defaultClock): void {
+	windowStart = segmentStart = start;
+	clock = now;
+	totals.clear();
+	labeledMs = 0;
+}
+
+/** Attribute the window [start, end] and disarm it. Returns undefined when no window is armed or no label outweighs unlabeled time. */
+export function takeLoopPhaseAttribution(end?: number): LoopPhaseAttribution | undefined {
+	if (windowStart === Number.POSITIVE_INFINITY) return undefined;
+	const t = end ?? clock();
+	boundary(t);
+	const unknownMs = Math.max(0, t - windowStart - labeledMs);
+	let winner: string | undefined;
+	let winnerMs = 0;
+	for (const [label, ms] of totals) {
+		if (ms >= winnerMs) {
+			winner = label;
+			winnerMs = ms;
+		}
+	}
+	const result = winner !== undefined && winnerMs > unknownMs ? { label: winner, ms: winnerMs } : undefined;
+	resetLoopPhaseWindow();
+	return result;
 }

package/src/marked/core.ts

@@ -248,14 +248,15 @@ export type TokensList = Token[] & { links: Links };
 export interface TokenizerThis {
 	lexer: Lexer;
 	/**
-	 * For an inline tokenizer, the whole inline source, such as a paragraph's text. The `src` it receives is the part
-	 * of it before `end` that starts at `end - src.length`: inside a link label or the text of emphasis, `end` is where
-	 * that text ends, right before its closer, and a token there must not reach past it. Inline tokenizers get one
-	 * context object per inline source, the same for every call while the lexer works through it and the labels and
-	 * emphasis inside it, so a tokenizer can keep state for it in a `WeakMap`.
+	 * The whole source the lexer works through. The `src` a tokenizer receives is the part of it before `end` that
+	 * starts at `end - src.length`. For a block tokenizer, `source` is the text passed to one `blockTokens` call and
+	 * `end` its length. For an inline tokenizer, it is the inline source, such as a paragraph's text: inside a link
+	 * label or the text of emphasis, `end` is where that text ends, right before its closer, and a token there must
+	 * not reach past it. Tokenizers get one context object per source, the same for every call while the lexer works
+	 * through it (and, inline, the labels and emphasis inside it), so a tokenizer can keep state for it in a `WeakMap`.
 	 */
 	source?: string;
-	/** For an inline tokenizer, where the text the lexer works through ends in `source` (see `source`). */
+	/** Where the text the lexer works through ends in `source` (see `source`). */
 	end?: number;
 }
 /** A tokenizer extension callback. */
@@ -820,8 +821,10 @@ function isBlockStart(lines: string[], index: number): boolean {
 	return false;
 }
 
+// `[^\n]`, not `.`: `.` stops at U+2028 and U+2029, which end no Markdown line,
+// and the match then skips the text in front of them.
 function lineArray(src: string): string[] {
-	return src.match(/.*(?:\n|$)/g)?.filter((line, index, all) => line !== "" || index < all.length - 1) ?? [];
+	return src.match(/[^\n]*(?:\n|$)/g)?.filter((line, index, all) => line !== "" || index < all.length - 1) ?? [];
 }
 function stripFinalNewline(value: string): string {
 	return value.endsWith("\n") ? value.slice(0, -1) : value;
@@ -969,13 +972,30 @@ function parseList(lines: string[], index: number, lexer: Lexer): { token: Token
 
 function blockTokens(src: string, lexer: Lexer, output: Token[]): Token[] {
 	const lines = lineArray(src);
+	// `lines` tiles `src` exactly, so the unconsumed source at line `i` is
+	// `src.slice(lineStarts[i])`. Only block extensions and an lheading override
+	// read it; computing offsets once keeps the loop linear.
+	const blockExtensions = lexer.extensions.block;
+	const context: TokenizerThis = { lexer, source: src, end: src.length };
+	const lheadingOverride = lexer.tokenizerOverrides.lheading;
+	let lineStarts: number[] | undefined;
+	if (blockExtensions.length > 0 || lheadingOverride) {
+		lineStarts = [];
+		let offset = 0;
+		for (let index = 0; index < lines.length; index++) {
+			lineStarts.push(offset);
+			offset += lines[index]!.length;
+		}
+	}
 	let i = 0;
 	while (i < lines.length) {
-		const remaining = lines.slice(i).join("");
 		let custom: Tokens.Generic | undefined;
-		for (const extension of lexer.extensions.block) {
-			custom = extension.tokenizer.call({ lexer }, remaining, output);
-			if (custom?.raw) break;
+		if (blockExtensions.length > 0) {
+			const remaining = src.slice(lineStarts![i]);
+			for (const extension of blockExtensions) {
+				custom = extension.tokenizer.call(context, remaining, output);
+				if (custom?.raw) break;
+			}
 		}
 		if (custom?.raw) {
 			output.push(custom);
@@ -1004,9 +1024,10 @@ function blockTokens(src: string, lexer: Lexer, output: Token[]): Token[] {
 			let raw = line;
 			let text = "";
 			i++;
+			const closer = new RegExp(`^ {0,3}${marker[0]}{${marker.length},}[ \\t]*(?:\\n|$)$`);
 			while (i < lines.length) {
 				const next = lines[i++]!;
-				if (new RegExp(`^ {0,3}${marker[0]}{${marker.length},}[ \\t]*(?:\\n|$)$`).test(next)) {
+				if (closer.test(next)) {
 					raw += next;
 					break;
 				}
@@ -1088,10 +1109,16 @@ function blockTokens(src: string, lexer: Lexer, output: Token[]): Token[] {
 			i++;
 			if (line.trimStart().startsWith("<!--")) {
 				while (!raw.includes("-->") && i < lines.length) raw += lines[i++]!;
-			} else if (tag && !new RegExp(`</${tag}>`, "i").test(raw)) {
-				while (i < lines.length) {
-					raw += lines[i++]!;
-					if (new RegExp(`</${tag}>`, "i").test(raw)) break;
+			} else if (tag) {
+				// A closing tag never spans lines, so testing each appended line is
+				// equivalent to re-testing the accumulated block.
+				const closeTag = new RegExp(`</${tag}>`, "i");
+				if (!closeTag.test(raw)) {
+					while (i < lines.length) {
+						const next = lines[i++]!;
+						raw += next;
+						if (closeTag.test(next)) break;
+					}
 				}
 			}
 			const value = i < lines.length && /^\s*\n$/.test(lines[i]!) ? stripFinalNewline(raw) : raw;
@@ -1127,9 +1154,8 @@ function blockTokens(src: string, lexer: Lexer, output: Token[]): Token[] {
 		}
 		if (i + 1 < lines.length && /^ {0,3}(=+|-+)[ \t]*(?:\n|$)$/.test(lines[i + 1]!)) {
 			let fallback: Tokens.Heading | undefined | false;
-			const override = lexer.tokenizerOverrides.lheading;
-			if (override) fallback = override.call(lexer.tokenizer, remaining);
-			if (!override || fallback === false) {
+			if (lheadingOverride) fallback = lheadingOverride.call(lexer.tokenizer, src.slice(lineStarts![i]));
+			if (!lheadingOverride || fallback === false) {
 				const raw = line + lines[i + 1]!;
 				const text = stripFinalNewline(line);
 				const tokens: Token[] = [];

package/src/marked-list.ts

@@ -0,0 +1,73 @@
+/**
+ * List-continuation grammar of `@linxiraos/pi-utils/marked`, for streaming
+ * renderers that freeze a lexed prefix at blank-line boundaries (TUI and
+ * collab web).
+ *
+ * marked's list tokenizer (Tokenizer.list, marked v18) continues a list across
+ * blank lines only when the remaining source matches
+ * `listItemRegex(marker)` = `^( {0,3}${marker})((?:[\t ][^\n]*)?(?:\n|$))`,
+ * where `marker` is the exact bullet char for unordered lists (`\${char}`) or
+ * 1-9 digits plus the exact delimiter for ordered lists (`\d{1,9}\${delim}`).
+ * The marker is derived from the list's FIRST item (`n = t[1].trim()`), which
+ * sits at the start of a top-level list token's raw.
+ */
+
+/** A list's marker, read from the start of its raw: bullet in group 1, ordered delimiter in group 2. */
+const LIST_MARKER_RE = /^ {0,3}(?:([*+-])|\d{1,9}([.)]))/;
+
+/**
+ * Whether a same-marker item could still continue the list `listRaw` at
+ * `tailStart` (directly after the blank line ending the list), now or after
+ * any append to `text`.
+ *
+ * Streaming-freeze equivalence invariant: lex(prefix) ++ lex(tail) must equal
+ * lex(full text) for the current text and every append-only extension of it,
+ * because a frozen prefix is sticky. At a blank-line cut directly after a
+ * top-level `list` token, the only construct that can straddle the cut is a
+ * continuation item of that list: marked consumed the blank line into the last
+ * item's raw and re-ran `listItemRegex` at exactly `tailStart`, merging a
+ * same-marker item into one renumbered loose list. The cut is safe only when
+ * that regex can NEVER match at `tailStart`, no matter what is appended later.
+ *
+ * Append-only growth means "closed" may only be concluded from a present
+ * character that contradicts every possible continuation (tail "1x" can never
+ * grow into an ordered item, but tail "1" can become "1. c"). Running out of
+ * text mid-marker therefore answers "may continue".
+ *
+ * Returns true when the tail could still continue the list (or the list's
+ * marker is unrecognizable) — the conservative "don't freeze" answer. marked
+ * may break the list anyway when the matching line is also an hr (`- - -`);
+ * treating that as "may continue" merely skips a freeze, never corrupts one.
+ */
+export function listMayContinueAt(text: string, tailStart: number, listRaw: string): boolean {
+	const marker = LIST_MARKER_RE.exec(listRaw);
+	if (marker === null) return true; // unrecognized list shape — stay conservative
+	const n = text.length;
+	let i = tailStart;
+	// `listItemRegex` allows up to 3 leading spaces.
+	while (i < n && i - tailStart < 3 && text.charCodeAt(i) === 0x20 /* space */) i++;
+	if (i >= n) return true;
+	const bullet = marker[1];
+	if (bullet !== undefined) {
+		if (text[i] !== bullet) return false; // wrong marker char — closed forever
+		i++;
+	} else {
+		// Ordered: 1-9 digits, then the same `.`/`)` delimiter.
+		let digits = 0;
+		while (i < n && digits < 10) {
+			const c = text.charCodeAt(i);
+			if (c < 0x30 /* 0 */ || c > 0x39 /* 9 */) break;
+			digits++;
+			i++;
+		}
+		if (digits === 0 || digits > 9) return false; // no digit run / too long — closed forever
+		if (i >= n) return true; // delimiter (or more digits) may still arrive
+		if (text[i] !== marker[2]) return false; // wrong delimiter — closed forever
+		i++;
+	}
+	// After the marker: `(?:[\t ][^\n]*)?(?:\n|$)` — tab/space + anything, a
+	// bare newline, or end-of-input (which appends can still extend).
+	if (i >= n) return true;
+	const after = text.charCodeAt(i);
+	return after === 0x20 /* space */ || after === 0x09 /* tab */ || after === 0x0a; /* \n */
+}