@prometheus-ai/utils 0.5.0

package/src/tab-spacing.ts

@@ -0,0 +1,342 @@
+/**
+ * Default tab width (display / tab expansion) and per-file width from `.editorconfig`.
+ * Mirrors former `prometheus-natives` `indent` + `text` default-tab-width behavior (no N-API).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isFsError } from "./fs-error";
+
+export const MIN_TAB_WIDTH = 1;
+export const MAX_TAB_WIDTH = 16;
+export const DEFAULT_TAB_WIDTH = 3;
+
+/**
+ * Per-component path length cap on common filesystems (`NAME_MAX = 255` on
+ * Linux ext4 / macOS APFS / Windows NTFS). Paths with components longer than
+ * this cannot be opened at all, so editorconfig discovery short-circuits to
+ * the default instead of running into `ENAMETOOLONG` from `readFileSync`.
+ */
+const NAME_MAX_BYTES = 255;
+
+const EDITORCONFIG_NAME = ".editorconfig";
+
+let defaultTabWidth = DEFAULT_TAB_WIDTH;
+
+const editorConfigCache = new Map<string, ParsedEditorConfig | null>();
+const editorConfigChainCache = new Map<string, ChainEntry[]>();
+const indentationCache = new Map<string, number>();
+
+interface EditorConfigSection {
+	pattern: string;
+	properties: Map<string, string>;
+}
+
+interface ParsedEditorConfig {
+	root: boolean;
+	sections: EditorConfigSection[];
+}
+
+interface ChainEntry {
+	dir: string;
+	parsed: ParsedEditorConfig;
+}
+
+const enum IndentStyle {
+	Space,
+	Tab,
+}
+
+type IndentSize = { kind: "spaces"; n: number } | { kind: "tab" };
+
+interface EditorConfigMatch {
+	indentStyle?: IndentStyle;
+	indentSize?: IndentSize;
+	tabWidth?: number;
+}
+
+function clampTabWidth(value: number): number {
+	return Math.min(MAX_TAB_WIDTH, Math.max(MIN_TAB_WIDTH, Math.trunc(value)));
+}
+
+function parsePositiveInteger(raw: string | undefined): number | undefined {
+	if (raw === undefined) return undefined;
+	if (!/^\d+$/.test(raw)) return undefined;
+	const parsed = Number.parseInt(raw, 10);
+	if (parsed === 0) return undefined;
+	return clampTabWidth(parsed);
+}
+
+function fixUnclosedBraces(pattern: string): string {
+	const opens = [...pattern].filter(c => c === "{").length;
+	const closes = [...pattern].filter(c => c === "}").length;
+	if (opens > closes) {
+		return pattern + "}".repeat(opens - closes);
+	}
+	return pattern;
+}
+
+/** Match `crates/prometheus-natives/src/glob_util.rs` `build_glob_pattern`. */
+function buildGlobPattern(globStr: string, recursive: boolean): string {
+	const normalized = globStr.replace(/\\/g, "/");
+	const pattern =
+		!recursive || normalized.includes("/") || normalized.startsWith("**") ? normalized : `**/${normalized}`;
+	return fixUnclosedBraces(pattern);
+}
+
+function globMatches(pattern: string, relativePath: string): boolean {
+	try {
+		const g = new Bun.Glob(pattern);
+		return g.match(relativePath);
+	} catch {
+		return false;
+	}
+}
+
+function matchesEditorConfigPattern(pattern: string, relativePath: string): boolean {
+	const normalized = pattern.replace(/^\/+/, "");
+	if (!normalized) {
+		return false;
+	}
+
+	const candidates = normalized.includes("/")
+		? [buildGlobPattern(normalized, false)]
+		: [buildGlobPattern(normalized, false), buildGlobPattern(normalized, true)];
+
+	for (const p of candidates) {
+		if (globMatches(p, relativePath)) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function parseEditorConfigFile(content: string): ParsedEditorConfig {
+	const parsed: ParsedEditorConfig = { root: false, sections: [] };
+	let currentSectionIdx: number | undefined;
+
+	for (const rawLine of content.split(/\n/)) {
+		const line = rawLine.trim();
+		if (line === "") continue;
+		if (line.startsWith("#") || line.startsWith(";")) continue;
+
+		if (line.startsWith("[") && line.endsWith("]") && line.length >= 2) {
+			const secPattern = line.slice(1, -1).trim();
+			if (secPattern === "") {
+				currentSectionIdx = undefined;
+				continue;
+			}
+			parsed.sections.push({ pattern: secPattern, properties: new Map() });
+			currentSectionIdx = parsed.sections.length - 1;
+			continue;
+		}
+
+		const eq = line.indexOf("=");
+		if (eq === -1) continue;
+		const key = line.slice(0, eq).trim().toLowerCase();
+		const value = line
+			.slice(eq + 1)
+			.trim()
+			.toLowerCase();
+		if (key === "") continue;
+
+		if (currentSectionIdx !== undefined) {
+			parsed.sections[currentSectionIdx]!.properties.set(key, value);
+		} else if (key === "root") {
+			parsed.root = value === "true";
+		}
+	}
+
+	return parsed;
+}
+
+function parseCachedEditorConfig(configPath: string): ParsedEditorConfig | undefined {
+	const key = path.resolve(configPath);
+	const hit = editorConfigCache.get(key);
+	if (hit !== undefined) {
+		return hit ?? undefined;
+	}
+
+	let content: string;
+	try {
+		content = fs.readFileSync(key, "utf8");
+	} catch (err) {
+		// editorconfig discovery is best-effort. Any filesystem error
+		// (`ENOENT`, `ENAMETOOLONG`, `ENOTDIR`, `EACCES`, `ELOOP`, `EINVAL`,
+		// …) means "no usable config at this path" — never a fatal condition
+		// for callers like the edit renderer that hand us arbitrary strings.
+		if (isFsError(err)) return undefined;
+		throw err;
+	}
+	const parsed = parseEditorConfigFile(content);
+	editorConfigCache.set(key, parsed);
+	return parsed;
+}
+
+function resolveFilePath(projectDir: string, file: string): string {
+	if (path.isAbsolute(file)) {
+		return path.normalize(path.resolve(file));
+	}
+	return path.normalize(path.resolve(projectDir, file));
+}
+
+/** Like `pathdiff::diff_paths` + forward slashes (see `indent.rs`). */
+function relativePathUnified(baseDir: string, absoluteFile: string): string {
+	const base = path.resolve(baseDir);
+	const file = path.resolve(absoluteFile);
+	const rel = path.relative(base, file);
+	if (rel.startsWith("..") || path.isAbsolute(rel)) {
+		return ".";
+	}
+	return rel.replace(/\\/g, "/");
+}
+
+function collectEditorConfigChain(startDir: string): ChainEntry[] {
+	const key = path.resolve(startDir);
+	const cached = editorConfigChainCache.get(key);
+	if (cached !== undefined) {
+		return cached;
+	}
+
+	const chain: ChainEntry[] = [];
+	let cursor = key;
+	for (;;) {
+		const configPath = path.join(cursor, EDITORCONFIG_NAME);
+		const parsed = parseCachedEditorConfig(configPath);
+		if (parsed !== undefined) {
+			chain.push({ dir: cursor, parsed });
+			if (parsed.root) {
+				break;
+			}
+		}
+
+		const parent = path.dirname(cursor);
+		if (parent === cursor) {
+			break;
+		}
+		cursor = parent;
+	}
+
+	chain.reverse();
+	editorConfigChainCache.set(key, chain);
+	return chain;
+}
+
+function resolveEditorConfigMatch(absoluteFile: string): EditorConfigMatch | undefined {
+	const fileDir = path.dirname(absoluteFile);
+	const chain = collectEditorConfigChain(fileDir);
+	if (chain.length === 0) {
+		return undefined;
+	}
+
+	const match: EditorConfigMatch = {};
+	for (const { dir, parsed } of chain) {
+		const relativePath = relativePathUnified(dir, absoluteFile);
+		for (const section of parsed.sections) {
+			if (!matchesEditorConfigPattern(section.pattern, relativePath)) {
+				continue;
+			}
+
+			const style = section.properties.get("indent_style");
+			if (style === "space") {
+				match.indentStyle = IndentStyle.Space;
+			} else if (style === "tab") {
+				match.indentStyle = IndentStyle.Tab;
+			}
+
+			const rawSize = section.properties.get("indent_size");
+			if (rawSize === "tab") {
+				match.indentSize = { kind: "tab" };
+			} else if (rawSize !== undefined) {
+				const n = parsePositiveInteger(rawSize);
+				if (n !== undefined) {
+					match.indentSize = { kind: "spaces", n };
+				}
+			}
+
+			const tw = parsePositiveInteger(section.properties.get("tab_width"));
+			if (tw !== undefined) {
+				match.tabWidth = tw;
+			}
+		}
+	}
+
+	if (match.indentStyle === undefined && match.indentSize === undefined && match.tabWidth === undefined) {
+		return undefined;
+	}
+	return match;
+}
+
+function resolveEditorConfigTabWidth(match: EditorConfigMatch | undefined, fallback: number): number | undefined {
+	if (match === undefined) return undefined;
+
+	if (match.indentSize?.kind === "spaces") {
+		return match.indentSize.n;
+	}
+
+	if (match.indentSize?.kind === "tab") {
+		if (match.tabWidth !== undefined) {
+			return match.tabWidth;
+		}
+		return fallback;
+	}
+
+	if (match.tabWidth !== undefined) {
+		return match.tabWidth;
+	}
+
+	if (match.indentStyle === IndentStyle.Tab) {
+		return fallback;
+	}
+
+	return undefined;
+}
+
+function hasOverlongPathComponent(filePath: string): boolean {
+	for (const part of filePath.split(/[\\/]/)) {
+		if (part.length > 0 && Buffer.byteLength(part) > NAME_MAX_BYTES) {
+			return true;
+		}
+	}
+	return false;
+}
+
+export function getDefaultTabWidth(): number {
+	return defaultTabWidth;
+}
+
+export function setDefaultTabWidth(width: number): void {
+	defaultTabWidth = clampTabWidth(width);
+}
+
+/**
+ * Visible tab width in columns for `file` (from `.editorconfig` + default), or the default when `file` is omitted.
+ */
+export function getIndentation(file?: string | null, projectDir?: string | null): number {
+	const fallback = defaultTabWidth;
+	if (file === undefined || file === null || file === "") {
+		return fallback;
+	}
+
+	const cwd = projectDir ?? process.cwd();
+	const absoluteFile = resolveFilePath(cwd, file);
+
+	// Renderers can hand us arbitrary strings (e.g. a malformed edit tool
+	// call whose `file_path` is gibberish). Reject paths whose normalized
+	// absolute form still has any component longer than `NAME_MAX_BYTES` —
+	// the editorconfig chain would only trip `ENAMETOOLONG` from
+	// `readFileSync` and escape.
+	if (hasOverlongPathComponent(absoluteFile)) {
+		return fallback;
+	}
+	const absKey = absoluteFile;
+	const cached = indentationCache.get(absKey);
+	if (cached !== undefined) {
+		return cached;
+	}
+
+	const editorMatch = resolveEditorConfigMatch(absoluteFile);
+	const resolved = resolveEditorConfigTabWidth(editorMatch, fallback) ?? fallback;
+	const clamped = clampTabWidth(resolved);
+	indentationCache.set(absKey, clamped);
+	return clamped;
+}

package/src/temp.ts

@@ -0,0 +1,77 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export class TempDir {
+	#path: string;
+	private constructor(path: string) {
+		this.#path = path;
+	}
+
+	static createSync(prefix?: string): TempDir {
+		return new TempDir(fs.mkdtempSync(normalizePrefix(prefix)));
+	}
+
+	static async create(prefix?: string): Promise<TempDir> {
+		return new TempDir(await fs.promises.mkdtemp(normalizePrefix(prefix)));
+	}
+
+	#removePromise: Promise<void> | null = null;
+
+	path(): string {
+		return this.#path;
+	}
+
+	absolute(): string {
+		return path.resolve(this.#path);
+	}
+
+	remove(): Promise<void> {
+		if (this.#removePromise) {
+			return this.#removePromise;
+		}
+		const removePromise = fs.promises.rm(this.#path, { recursive: true, force: true });
+		this.#removePromise = removePromise;
+		return removePromise;
+	}
+
+	removeSync(): void {
+		fs.rmSync(this.#path, { recursive: true, force: true });
+		this.#removePromise = Promise.resolve();
+	}
+
+	toString(): string {
+		return this.#path;
+	}
+
+	join(...paths: string[]): string {
+		return path.join(this.#path, ...paths);
+	}
+
+	async [Symbol.asyncDispose](): Promise<void> {
+		try {
+			await this.remove();
+		} catch {
+			// Ignore cleanup errors
+		}
+	}
+
+	[Symbol.dispose](): void {
+		try {
+			this.removeSync();
+		} catch {
+			// Ignore cleanup errors
+		}
+	}
+}
+
+const kTempDir = os.tmpdir();
+
+function normalizePrefix(prefix?: string): string {
+	if (!prefix) {
+		return `${kTempDir}${path.sep}pi-temp-`;
+	} else if (prefix.startsWith("@")) {
+		return path.join(kTempDir, prefix.slice(1));
+	}
+	return prefix;
+}

package/src/type-guards.ts

@@ -0,0 +1,11 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function asRecord(value: unknown): Record<string, unknown> | null {
+	return isRecord(value) ? value : null;
+}
+
+export function toError(value: unknown): Error {
+	return value instanceof Error ? value : new Error(String(value));
+}

package/src/which.ts

@@ -0,0 +1,232 @@
+// OS-agnostic "which" helper with robust macOS toolchain lookup and flexible cache control.
+//
+// - Falls back to macOS Xcode/CLT toolchain directories if standard `Bun.which()` fails on Darwin.
+//   Resolves the active developer directory via $DEVELOPER_DIR / /var/db/xcode_select_link symlink
+//   to avoid spawning xcrun subprocesses.
+// - Supports four cache modes (`none`, `fresh`, `ro`, `cached`) for control over discovery cost and determinism.
+// - Computes a stable cache key from command + options to avoid redundant lookups within a process.
+// - Returns path to resolved binary or null if not found.
+//
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+type CacheKey = string | bigint | number;
+
+// Tools shipped by Xcode / Command Line Tools that callers actually look up.
+// Keeps the set small so darwinWhich can fast-reject non-Xcode commands without
+// touching the filesystem.  Only needs entries for binaries that live *exclusively*
+// in toolchain dirs (not on a typical $PATH).
+const XCODE_BINS = new Set([
+	// Compilers & driver aliases
+	"clang",
+	"clang++",
+	"gcc",
+	"g++",
+	"cc",
+	"c++",
+	"cpp",
+	"c89",
+	"c99",
+	"swift",
+	"swiftc",
+	"swift-frontend",
+	// Language servers (LSP)
+	"clangd",
+	"sourcekit-lsp",
+	// Linker & archive tools
+	"ld",
+	"ld-classic",
+	"ar",
+	"ranlib",
+	"libtool",
+	"as",
+	"lipo",
+	"install_name_tool",
+	"codesign_allocate",
+	// Build utilities
+	"make",
+	"gnumake",
+	"m4",
+	"flex",
+	"bison",
+	"yacc",
+	"lex",
+	// VCS (CLT ships git)
+	"git",
+	"git-receive-pack",
+	"git-upload-pack",
+	"git-upload-archive",
+	"git-shell",
+	"scalar",
+	// Debugger
+	"lldb",
+	"lldb-dap",
+	// Binary inspection
+	"nm",
+	"otool",
+	"objdump",
+	"strings",
+	"strip",
+	"size",
+	"dsymutil",
+	"dwarfdump",
+	"lipo",
+	"vtool",
+	// Clang tooling
+	"clang-format",
+	"swift-format",
+]);
+
+// Prefixes for versioned binaries (e.g. python3.9, pip3.12, pydoc3.9, 2to3-3.9)
+const XCODE_BIN_PREFIXES = ["python", "pip", "pydoc", "2to3"];
+
+function isXcodeBin(command: string): boolean {
+	if (XCODE_BINS.has(command)) return true;
+	for (const prefix of XCODE_BIN_PREFIXES) {
+		if (command.startsWith(prefix)) return true;
+	}
+	return false;
+}
+
+// Resolve the active Xcode developer directory once, without spawning any process.
+// Priority: $DEVELOPER_DIR env → /var/db/xcode_select_link symlink → common fallback paths.
+function getDeveloperDirs(): string | null {
+	// 1. Explicit env override
+	const envDir = process.env.DEVELOPER_DIR;
+	if (envDir && fs.existsSync(envDir)) {
+		return envDir;
+	}
+
+	// 2. xcode-select stores the active path as a symlink
+	try {
+		return fs.readlinkSync("/var/db/xcode_select_link");
+	} catch {
+		// symlink may not exist on minimal installs
+	}
+	// 3. Common locations
+	for (const candidate of ["/Applications/Xcode.app/Contents/Developer", "/Library/Developer/CommandLineTools"]) {
+		if (fs.existsSync(candidate)) {
+			return candidate;
+		}
+	}
+	return null;
+}
+
+// Build the list of extra toolchain bin directories to check on macOS.
+// Computed lazily once from the resolved developer directory.
+let macosToolPaths: Map<string, string> | undefined;
+function getMacosToolPaths(): Map<string, string> {
+	if (macosToolPaths) return macosToolPaths;
+	const paths: string[] = [
+		// Always check Command Line Tools (may be independent of Xcode)
+		"/Library/Developer/CommandLineTools/usr/bin",
+	];
+	const devDir = getDeveloperDirs();
+	if (devDir) {
+		paths.push(path.join(devDir, "usr/bin"), path.join(devDir, "Toolchains/XcodeDefault.xctoolchain/usr/bin"));
+	}
+
+	// Deduplicate (e.g. devDir may already be CommandLineTools)
+	macosToolPaths = new Map<string, string>();
+	for (const dir of Array.from(new Set(paths))) {
+		try {
+			for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+				if (entry.isFile() || entry.isSymbolicLink()) {
+					if (macosToolPaths.has(entry.name)) {
+						continue;
+					}
+					macosToolPaths.set(entry.name, path.join(dir, entry.name));
+				}
+			}
+		} catch {
+			// dir doesn't exist or isn't readable
+		}
+	}
+	return macosToolPaths;
+}
+
+// Map: cache key -> resolved binary path or null (not found)
+const toolCache = new Map<CacheKey, string | null>();
+
+/**
+ * Cache policy for which lookups.
+ */
+export const enum WhichCachePolicy {
+	/**
+	 * Use cached result if available.
+	 */
+	Cached = 0,
+	/**
+	 * Bypass cache and perform a new lookup.
+	 */
+	Bypass,
+	/**
+	 * Always update cache.
+	 */
+	Fresh,
+	/**
+	 * Read-only, serves from cache if present, but doesn't write.
+	 */
+	ReadOnly,
+}
+
+// Extension: additional cache policy for tool path lookup
+export interface WhichOptions extends Bun.WhichOptions {
+	/**
+	 * Cache policy for the lookup.
+	 * Defaults to `WhichCachePolicy.Fresh`.
+	 */
+	cache?: WhichCachePolicy;
+}
+
+// Darwin-specific "which" shim: consult Xcode/CLT toolchain directories after $PATH.
+// Uses cached directory listings instead of per-command existsSync or xcrun subprocesses.
+function darwinWhich(command: string, _options?: Bun.WhichOptions): string | null {
+	const regular = Bun.which(command);
+	if (regular) return regular;
+	if (isXcodeBin(command)) {
+		return getMacosToolPaths().get(command) ?? null;
+	}
+	return null;
+}
+
+// Which function that incorporates Darwin Xcode logic if platform reports as 'darwin'
+export const whichFresh = os.platform() === "darwin" ? darwinWhich : Bun.which;
+
+// Derive stable cache key from command and lookup options
+function cacheKey(command: string, options?: Bun.WhichOptions): CacheKey {
+	if (!options) return command;
+	if (!options.cwd && !options.PATH) return command;
+	let h = Bun.hash(command);
+	if (options.cwd) h = Bun.hash(options.cwd, h);
+	if (options.PATH) h = Bun.hash(options.PATH, h);
+	return h;
+}
+
+/**
+ * Locate binary on PATH (with flexible caching).
+ *
+ * @param command - Binary name to resolve
+ * @param options - Bun.WhichOptions plus `cache` control
+ * @returns Filesystem path if found, else null
+ */
+export function $which(command: string, options?: WhichOptions): string | null {
+	const cachePolicy = options?.cache ?? WhichCachePolicy.Cached;
+	let key: CacheKey | undefined;
+
+	if (cachePolicy !== WhichCachePolicy.Bypass) {
+		key = cacheKey(command, options);
+		if (cachePolicy !== WhichCachePolicy.Fresh) {
+			const cached = toolCache.get(key);
+			if (cached !== undefined) return cached;
+		}
+	}
+
+	const result = whichFresh(command, options);
+	if (key != null && cachePolicy !== WhichCachePolicy.ReadOnly) {
+		toolCache.set(key, result);
+	}
+	return result;
+}