@linxiraos/pi-utils 1.0.0

package/src/marked.ts

@@ -0,0 +1,2 @@
+/** Behavior-compatible reimplementation of marked's used surface. */
+export * from "./marked/core";

package/src/mermaid-ascii.ts

@@ -0,0 +1,31 @@
+import { type AsciiRenderOptions, renderMermaidASCII } from "./vendor/mermaid-ascii";
+
+export type { AsciiRenderOptions as MermaidAsciiRenderOptions };
+
+export function renderMermaidAscii(source: string, options?: AsciiRenderOptions): string {
+	return renderMermaidASCII(source, options);
+}
+
+export function renderMermaidAsciiSafe(source: string, options?: AsciiRenderOptions): string | null {
+	try {
+		return renderMermaidASCII(source, options);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Extract mermaid code blocks from markdown text.
+ */
+export function extractMermaidBlocks(markdown: string): { source: string; hash: bigint | number }[] {
+	const blocks: { source: string; hash: bigint | number }[] = [];
+	const regex = /```mermaid\s*\n([\s\S]*?)```/g;
+
+	for (let match = regex.exec(markdown); match !== null; match = regex.exec(markdown)) {
+		const source = match[1].trim();
+		const hash = Bun.hash(source);
+		blocks.push({ source, hash });
+	}
+
+	return blocks;
+}

package/src/mime.ts

@@ -0,0 +1,159 @@
+import { peekFile, peekFileSync } from "./peek-file";
+
+const DEFAULT_IMAGE_METADATA_HEADER_BYTES = 256 * 1024;
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const JPEG_MAGIC = Buffer.from([0xff, 0xd8, 0xff]);
+const WEBP_RIFF_MAGIC = Buffer.from([0x52, 0x49, 0x46, 0x46]);
+const WEBP_MAGIC = Buffer.from([0x57, 0x45, 0x42, 0x50]);
+const PNG_IHDR = Buffer.from("IHDR");
+const GIF87A = Buffer.from("GIF87a");
+const GIF89A = Buffer.from("GIF89a");
+const WEBP_VP8X = Buffer.from("VP8X");
+const WEBP_VP8L = Buffer.from("VP8L");
+const WEBP_VP8 = Buffer.from("VP8 ");
+
+export const SUPPORTED_IMAGE_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+
+export type ImageMetadata =
+	| { mimeType: "image/png"; width?: number; height?: number; channels?: number; hasAlpha?: boolean }
+	| { mimeType: "image/jpeg"; width?: number; height?: number; channels?: number; hasAlpha?: false }
+	| { mimeType: "image/gif"; width?: number; height?: number; channels?: 3; hasAlpha?: never }
+	| { mimeType: "image/webp"; width?: number; height?: number; channels?: number; hasAlpha?: boolean };
+
+function magicEquals(header: Uint8Array, offset: number, magic: Buffer): boolean {
+	if (header.length < offset + magic.length) {
+		return false;
+	}
+	return magic.equals(header.subarray(offset, offset + magic.length));
+}
+
+function parsePngMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, PNG_MAGIC)) return null;
+	if (!magicEquals(header, 12, PNG_IHDR)) return { mimeType: "image/png" };
+	if (header.length < 26) return { mimeType: "image/png" };
+
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	const width = view.getUint32(16, false);
+	const height = view.getUint32(20, false);
+	const colorType = view.getUint8(25);
+	if (colorType === 0) return { mimeType: "image/png", width, height, channels: 1, hasAlpha: false };
+	if (colorType === 2) return { mimeType: "image/png", width, height, channels: 3, hasAlpha: false };
+	if (colorType === 3) return { mimeType: "image/png", width, height, channels: 3 };
+	if (colorType === 4) return { mimeType: "image/png", width, height, channels: 2, hasAlpha: true };
+	if (colorType === 6) return { mimeType: "image/png", width, height, channels: 4, hasAlpha: true };
+	return { mimeType: "image/png", width, height };
+}
+
+function parseJpegMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, JPEG_MAGIC)) return null;
+	if (header.length < 4) return { mimeType: "image/jpeg" };
+
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	let offset = 2;
+	while (offset + 9 < header.length) {
+		if (header[offset] !== 0xff) {
+			offset += 1;
+			continue;
+		}
+
+		let markerOffset = offset + 1;
+		while (markerOffset < header.length && header[markerOffset] === 0xff) {
+			markerOffset += 1;
+		}
+		if (markerOffset >= header.length) break;
+
+		const marker = header[markerOffset];
+		const segmentOffset = markerOffset + 1;
+		if (marker === 0xd8 || marker === 0xd9 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+			offset = segmentOffset;
+			continue;
+		}
+		if (segmentOffset + 1 >= header.length) break;
+
+		const segmentLength = view.getUint16(segmentOffset, false);
+		if (segmentLength < 2) break;
+
+		const isStartOfFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+		if (isStartOfFrame) {
+			if (segmentOffset + 7 >= header.length) break;
+			const height = view.getUint16(segmentOffset + 3, false);
+			const width = view.getUint16(segmentOffset + 5, false);
+			const channels = header[segmentOffset + 7];
+			return {
+				mimeType: "image/jpeg",
+				width,
+				height,
+				channels: Number.isFinite(channels) ? channels : undefined,
+				hasAlpha: false,
+			};
+		}
+
+		offset = segmentOffset + segmentLength;
+	}
+
+	return { mimeType: "image/jpeg" };
+}
+
+function parseGifMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, GIF87A) && !magicEquals(header, 0, GIF89A)) return null;
+	if (header.length < 10) return { mimeType: "image/gif" };
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	return {
+		mimeType: "image/gif",
+		width: view.getUint16(6, true),
+		height: view.getUint16(8, true),
+		channels: 3,
+	};
+}
+
+function parseWebpMetadata(header: Uint8Array): ImageMetadata | null {
+	if (!magicEquals(header, 0, WEBP_RIFF_MAGIC)) return null;
+	if (!magicEquals(header, 8, WEBP_MAGIC)) return null;
+	if (header.length < 30) return { mimeType: "image/webp" };
+
+	if (magicEquals(header, 12, WEBP_VP8X)) {
+		const hasAlpha = (header[20] & 0x10) !== 0;
+		const width = (header[24] | (header[25] << 8) | (header[26] << 16)) + 1;
+		const height = (header[27] | (header[28] << 8) | (header[29] << 16)) + 1;
+		return { mimeType: "image/webp", width, height, channels: hasAlpha ? 4 : 3, hasAlpha };
+	}
+
+	const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+	if (magicEquals(header, 12, WEBP_VP8L)) {
+		if (header.length < 25) return { mimeType: "image/webp" };
+		const bits = view.getUint32(21, true);
+		const width = (bits & 0x3fff) + 1;
+		const height = ((bits >> 14) & 0x3fff) + 1;
+		const hasAlpha = ((bits >> 28) & 0x1) === 1;
+		return { mimeType: "image/webp", width, height, channels: hasAlpha ? 4 : 3, hasAlpha };
+	}
+
+	if (magicEquals(header, 12, WEBP_VP8)) {
+		const width = view.getUint16(26, true) & 0x3fff;
+		const height = view.getUint16(28, true) & 0x3fff;
+		return { mimeType: "image/webp", width, height, channels: 3, hasAlpha: false };
+	}
+
+	return { mimeType: "image/webp" };
+}
+
+export function parseImageMetadata(header: Uint8Array): ImageMetadata | null {
+	return (
+		parsePngMetadata(header) ?? parseJpegMetadata(header) ?? parseGifMetadata(header) ?? parseWebpMetadata(header)
+	);
+}
+
+export function readImageMetadataSync(
+	filePath: string,
+	maxBytes = DEFAULT_IMAGE_METADATA_HEADER_BYTES,
+): ImageMetadata | null {
+	return peekFileSync(filePath, maxBytes, parseImageMetadata);
+}
+
+export function readImageMetadata(
+	filePath: string,
+	maxBytes = DEFAULT_IMAGE_METADATA_HEADER_BYTES,
+): Promise<ImageMetadata | null> {
+	return peekFile(filePath, maxBytes, parseImageMetadata);
+}

package/src/module-timer.ts

@@ -0,0 +1,148 @@
+/**
+ * Module-load timing preload.
+ *
+ * `bun --preload .../module-timer.ts <entry>` installs Bun plugin hooks (only
+ * when `PI_TIMING` is set) that record an inclusive module window plus resolved
+ * static child edges:
+ *
+ *   onLoad start → appended end marker after the module's top-level body
+ *
+ * Events are pushed into a process-global buffer that {@link logger.printTimings}
+ * drains and renders as a module DAG/tree. Each module row can therefore show
+ * both total time and `self` time after subtracting child module intervals.
+ *
+ * Why a preload (and not a normal import): Bun reads the *entire* statically
+ * reachable graph before evaluating any module, so hooks installed from inside
+ * that graph cannot observe its own loading — they only catch later dynamically
+ * loaded modules. A preload runs first, so it sees the static-import phase that
+ * dominates startup.
+ *
+ * Kept dependency-free on purpose: the sole import is Bun's `plugin`, so this is
+ * cheap to preload before pi-utils (and winston) exist. The buffer is shared with
+ * the logger via a registry Symbol so neither side needs to import the other.
+ *
+ * **What is measured:** an inclusive per-module window. `onLoad` stamps the
+ * start before reading source; the returned source has a tiny marker appended at
+ * the end of the module. That marker runs after Bun parses/transpiles the module
+ * and after any top-level await in that module completes, so the duration
+ * includes read + parse/transpile + dependency wait + top-level execution/TLA.
+ * If a module throws before its final statement, no end marker is recorded.
+ *
+ * **Tree shape:** `onResolve` observes importer → specifier edges and resolves
+ * them with `Bun.resolveSync` without taking over Bun's real resolution. The
+ * logger renders these edges as a DAG/tree and computes module `self` time by
+ * subtracting the union of child intervals, avoiding misleading flat inclusive
+ * totals.
+ *
+ * **Coverage limits:**
+ * - TS/TSX only — intercepting `node_modules` CJS `.js`/`.cjs` and forcing ESM
+ *   breaks their default-export detection, so they are left to Bun's default path.
+ * - **Dev runs only.** In the compiled `omp` binary every module is pre-bundled
+ *   into bunfs, so `onLoad` never fires; profile with a `bun --preload` dev run.
+ */
+import { plugin } from "bun";
+import { moduleLoadBuffer } from "./timing-buffer";
+
+// Restrict to TS/TSX only. node_modules ships CommonJS `.js`/`.cjs` that Bun
+// auto-detects when loaded via its default path; if we intercept and return
+// `{ contents, loader: "js" }`, Bun forces ESM and CJS modules fail to load
+// (e.g. `Missing 'default' export`). Our own source tree (where the interesting
+// timing lives) is uniformly TypeScript, so a TS-only filter is both safe and
+// sufficient.
+const MODULE_LOADER_FILTER = /\.[mc]?tsx?$/;
+const MODULE_COMPLETE_KEY: symbol = Symbol.for("omp.moduleLoadComplete");
+const MODULE_BODY_START_KEY: symbol = Symbol.for("omp.moduleBodyStart");
+const STATIC_IMPORT_PATTERN =
+	/\b(?:import|export)\s+(?:type\s+)?(?:[^"']*?\s+from\s+)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+
+type CompleteStore = Record<symbol, ((path: string) => void) | undefined>;
+
+function bodyStartMarker(path: string): string {
+	return `;globalThis[Symbol.for("omp.moduleBodyStart")]?.(${JSON.stringify(path)});\n`;
+}
+
+function completionMarker(path: string): string {
+	return `\n;globalThis[Symbol.for("omp.moduleLoadComplete")]?.(${JSON.stringify(path)});\n`;
+}
+
+function instrumentContents(path: string, contents: string): string {
+	const start = bodyStartMarker(path);
+	const end = completionMarker(path);
+	if (!contents.startsWith("#!")) return `${start}${contents}${end}`;
+	const newline = contents.indexOf("\n");
+	if (newline === -1) return `${contents}\n${start}${end}`;
+	return `${contents.slice(0, newline + 1)}${start}${contents.slice(newline + 1)}${end}`;
+}
+function importerDir(importer: string): string {
+	const slash = importer.lastIndexOf("/");
+	if (slash === -1) return ".";
+	return importer.slice(0, slash);
+}
+
+function childSetFor(importsByPath: Map<string, Set<string>>, path: string): Set<string> {
+	let children = importsByPath.get(path);
+	if (!children) {
+		children = new Set<string>();
+		importsByPath.set(path, children);
+	}
+	return children;
+}
+
+function addImportEdges(importsByPath: Map<string, Set<string>>, importer: string, contents: string): void {
+	STATIC_IMPORT_PATTERN.lastIndex = 0;
+	for (const match of contents.matchAll(STATIC_IMPORT_PATTERN)) {
+		const specifier = match[1] ?? match[2];
+		if (!specifier) continue;
+		try {
+			const resolved = Bun.resolveSync(specifier, importerDir(importer));
+			if (MODULE_LOADER_FILTER.test(resolved) && resolved !== importer) {
+				childSetFor(importsByPath, importer).add(resolved);
+			}
+		} catch {
+			// Leave Bun's real resolver/runtime to surface any error. This scanner is only an observer.
+		}
+	}
+}
+
+if (process.env.PI_TIMING) {
+	const buffer = moduleLoadBuffer();
+	const starts = new Map<string, number>();
+	const bodyStarts = new Map<string, number>();
+	const importsByPath = new Map<string, Set<string>>();
+	const store = globalThis as unknown as CompleteStore;
+	store[MODULE_BODY_START_KEY] = (path: string): void => {
+		bodyStarts.set(path, performance.now());
+	};
+	store[MODULE_COMPLETE_KEY] = (path: string): void => {
+		const start = starts.get(path);
+		if (start === undefined) return;
+		starts.delete(path);
+		const end = performance.now();
+		const bodyStart = bodyStarts.get(path);
+		bodyStarts.delete(path);
+		const imports = importsByPath.get(path);
+		buffer.push({
+			path,
+			start,
+			durationMs: end - start,
+			bodyMs: bodyStart === undefined ? undefined : end - bodyStart,
+			imports: imports ? [...imports] : [],
+		});
+	};
+
+	plugin({
+		name: "pi-module-load-timer",
+		setup(build) {
+			build.onLoad({ filter: MODULE_LOADER_FILTER }, async args => {
+				starts.set(args.path, performance.now());
+				childSetFor(importsByPath, args.path);
+				const contents = await Bun.file(args.path).text();
+				addImportEdges(importsByPath, args.path, contents);
+				return {
+					contents: instrumentContents(args.path, contents),
+					loader: args.path.endsWith(".tsx") ? "tsx" : "ts",
+				};
+			});
+		},
+	});
+}

package/src/path-tree.ts

@@ -0,0 +1,147 @@
+/**
+ * Multi-level path tree shared by grouped file listings (find / grep / ast tools)
+ * and compaction file-operation lists.
+ *
+ * Flat path lists used to group by the *immediate* parent directory and print the
+ * full directory path in every header. For results spread across a deep tree — or
+ * rooted outside cwd, where paths stay absolute — that repeated the shared prefix
+ * on every line. The tree below folds single-child directory chains (so the common
+ * prefix collapses into one header) and nests the rest, charging the model one
+ * token per path segment instead of one per file.
+ */
+
+const URL_LIKE_PATH_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+/** True for `scheme://…` entries that have no meaningful directory structure. */
+export function isUrlLikePath(filePath: string): boolean {
+	return URL_LIKE_PATH_RE.test(filePath);
+}
+
+export interface PathTreeNode {
+	/** Direct file leaves, in first-seen order. */
+	files: Array<{ name: string; key: string }>;
+	/** Dedup set for `files` (a glob can surface the same path twice on retry). */
+	fileNames: Set<string>;
+	/** Child directories, in first-seen order. */
+	subdirs: Array<{ name: string; node: PathTreeNode }>;
+	/** Dedup index for `subdirs`. */
+	dirIndex: Map<string, PathTreeNode>;
+}
+
+export interface PathTreeInput {
+	/** Path string; absolute, cwd-relative, or url-like. Backslashes are normalized. */
+	path: string;
+	/** Whether the leaf itself is a directory (trailing-slash match from find). */
+	isDir: boolean;
+	/** Opaque key carried onto file events for section lookup. Defaults to `path`. */
+	key?: string;
+}
+
+/** One node emitted while walking the tree: a folded directory or a file leaf. */
+export interface GroupedTreeEvent {
+	kind: "dir" | "file";
+	/** 0-based nesting depth (root children are depth 0). */
+	depth: number;
+	/** Folded chain for dirs (e.g. `a/b/c`, no trailing slash); basename for files. */
+	name: string;
+	/** File key for `kind === "file"`; empty string for directories. */
+	key: string;
+}
+
+function createNode(): PathTreeNode {
+	return { files: [], fileNames: new Set(), subdirs: [], dirIndex: new Map() };
+}
+
+function addFile(node: PathTreeNode, name: string, key: string): void {
+	if (node.fileNames.has(name)) return;
+	node.fileNames.add(name);
+	node.files.push({ name, key });
+}
+
+/**
+ * Build a directory tree from a flat list of paths. URL-like entries are kept
+ * whole as root-level file leaves (they have no meaningful directory structure).
+ * Absolute paths carry a leading empty segment so they share a common `/` root
+ * and fold like any other prefix.
+ */
+export function buildPathTree(entries: Iterable<PathTreeInput>): PathTreeNode {
+	const root = createNode();
+	for (const { path: rawPath, isDir, key } of entries) {
+		const normalized = rawPath.replace(/\\/g, "/");
+		const fileKey = key ?? rawPath;
+		if (isUrlLikePath(normalized)) {
+			addFile(root, normalized, fileKey);
+			continue;
+		}
+		const trimmed = normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+		if (trimmed.length === 0) continue;
+		const segments = trimmed.split("/");
+		const dirCount = isDir ? segments.length : segments.length - 1;
+		let node = root;
+		for (let i = 0; i < dirCount; i++) {
+			const segment = segments[i]!;
+			let child = node.dirIndex.get(segment);
+			if (!child) {
+				child = createNode();
+				node.dirIndex.set(segment, child);
+				node.subdirs.push({ name: segment, node: child });
+			}
+			node = child;
+		}
+		if (!isDir) {
+			addFile(node, segments[segments.length - 1]!, fileKey);
+		}
+	}
+	return root;
+}
+
+/**
+ * Depth-first walk yielding directory and file events. Directories collapse their
+ * single-child chains (`a` → `a/b` → `a/b/c`) so a shared prefix becomes one
+ * header. Each node's direct files are emitted before its subdirectories, keeping
+ * a file unambiguously attached to the header above it.
+ */
+export function* walkPathTree(node: PathTreeNode, depth = 0): Generator<GroupedTreeEvent> {
+	for (const file of node.files) {
+		yield { kind: "file", depth, name: file.name, key: file.key };
+	}
+	for (const subdir of node.subdirs) {
+		let dirNode = subdir.node;
+		const parts = [subdir.name];
+		while (dirNode.files.length === 0 && dirNode.subdirs.length === 1) {
+			const only = dirNode.subdirs[0]!;
+			parts.push(only.name);
+			dirNode = only.node;
+		}
+		yield { kind: "dir", depth, name: parts.join("/"), key: "" };
+		yield* walkPathTree(dirNode, depth + 1);
+	}
+}
+
+/**
+ * Render a flat path list as a grouped, prefix-folded directory tree without
+ * per-file bodies (find-tool output shape, also used by compaction `<files>`
+ * lists). Single-child directory chains fold into one header (`# a/b/c/`),
+ * each level adds one `#`, and files are listed bare under the deepest
+ * directory header that owns them. Trailing-slash entries are directory
+ * leaves and keep their slash in the header.
+ *
+ * `annotate` receives each file's full original path and its return value is
+ * appended verbatim to the file line (e.g. ` (RW)`).
+ *
+ * Order follows the input: a directory appears when its first member is
+ * emitted, and a node's own files precede its subdirectories.
+ */
+export function formatGroupedPaths(paths: readonly string[], annotate?: (path: string) => string): string {
+	if (paths.length === 0) return "";
+	const tree = buildPathTree(paths.map(entry => ({ path: entry, isDir: entry.endsWith("/") })));
+	const lines: string[] = [];
+	for (const event of walkPathTree(tree)) {
+		if (event.kind === "dir") {
+			lines.push(`${"#".repeat(event.depth + 1)} ${event.name}/`);
+		} else {
+			lines.push(annotate ? `${event.name}${annotate(event.key)}` : event.name);
+		}
+	}
+	return lines.join("\n");
+}

package/src/path.ts

@@ -0,0 +1,28 @@
+const WINDOWS_DRIVE_EXTENDED_PREFIX = /^\\\\[?]\\([A-Za-z]:[\\/].*)$/;
+const WINDOWS_UNC_EXTENDED_PREFIX = /^\\\\[?]\\UNC[\\/]([^\\/]+)[\\/](.+)$/i;
+const WINDOWS_DRIVE_EXTENDED_FORWARD_PREFIX = /^\/\/[?]\/([A-Za-z]:\/.*)$/;
+const WINDOWS_UNC_EXTENDED_FORWARD_PREFIX = /^\/\/[?]\/UNC\/([^/]+)\/(.+)$/i;
+const WINDOWS_DRIVE_NT_PREFIX = /^\\\\[?][?]\\([A-Za-z]:[\\/].*)$/;
+const WINDOWS_UNC_NT_PREFIX = /^\\\\[?][?]\\UNC[\\/]([^\\/]+)[\\/](.+)$/i;
+
+/** Removes Win32 extended-length prefixes before passing paths to Bun APIs. */
+export function stripWindowsExtendedLengthPathPrefix(
+	filePath: string,
+	platform: NodeJS.Platform = process.platform,
+): string {
+	if (platform !== "win32") return filePath;
+
+	const uncMatch = WINDOWS_UNC_EXTENDED_PREFIX.exec(filePath) ?? WINDOWS_UNC_NT_PREFIX.exec(filePath);
+	if (uncMatch) return `\\\\${uncMatch[1]}\\${uncMatch[2]}`;
+
+	const driveMatch = WINDOWS_DRIVE_EXTENDED_PREFIX.exec(filePath) ?? WINDOWS_DRIVE_NT_PREFIX.exec(filePath);
+	if (driveMatch) return driveMatch[1];
+
+	const forwardUncMatch = WINDOWS_UNC_EXTENDED_FORWARD_PREFIX.exec(filePath);
+	if (forwardUncMatch) return `//${forwardUncMatch[1]}/${forwardUncMatch[2]}`;
+
+	const forwardDriveMatch = WINDOWS_DRIVE_EXTENDED_FORWARD_PREFIX.exec(filePath);
+	if (forwardDriveMatch) return forwardDriveMatch[1];
+
+	return filePath;
+}