homegraph 1.0.0 → 1.1.2

package/dist/utils.d.ts

@@ -0,0 +1,224 @@
+/**
+ * HomeGraph Utilities
+ *
+ * Common utility functions for memory management, concurrency, batching,
+ * and security validation.
+ *
+ * @module utils
+ *
+ * @example
+ * ```typescript
+ * import { Mutex, processInBatches, MemoryMonitor, validatePathWithinRoot } from 'homegraph';
+ *
+ * // Use mutex for concurrent safety
+ * const mutex = new Mutex();
+ * await mutex.withLock(async () => {
+ *   await performCriticalOperation();
+ * });
+ *
+ * // Process items in batches to manage memory
+ * const results = await processInBatches(items, 100, async (item) => {
+ *   return await processItem(item);
+ * });
+ *
+ * // Monitor memory usage
+ * const monitor = new MemoryMonitor(512, (usage) => {
+ *   console.warn(`Memory usage exceeded 512MB: ${usage / 1024 / 1024}MB`);
+ * });
+ * monitor.start();
+ * ```
+ */
+/**
+ * Config "languages" whose nodes are pure key/value DATA lifted from a config
+ * file (e.g. Spring `application.{yml,properties}`), not source code.
+ */
+export declare const CONFIG_LEAF_LANGUAGES: ReadonlySet<string>;
+/**
+ * A config-leaf node is a single key lifted out of a pure config/data file —
+ * `kind: 'constant'` in a {@link CONFIG_LEAF_LANGUAGES} language. Its on-disk
+ * line is `key = <value>`, and that value is routinely a secret (DB password,
+ * API key, JDBC URL with embedded creds). HomeGraph must surface the KEY only
+ * and never read/return the value, or it pushes secrets into agent context
+ * unbidden — the value isn't needed for resolution, and an agent that genuinely
+ * needs it can read the file directly. (#383)
+ */
+export declare function isConfigLeafNode(node: {
+    kind: string;
+    language?: string;
+}): boolean;
+/**
+ * Validate that a file path stays within the project root, resolving symlinks.
+ *
+ * Two layers: a cheap lexical check that catches `../` traversal, then a
+ * realpath check that catches symlink escapes — an in-repo symlink whose
+ * logical path is inside the root but whose real target points outside it
+ * (issue #527). A symlink that stays within the root is still allowed, so
+ * legitimate in-tree symlinks keep working. Both content-serving read sinks
+ * (homegraph_node `includeCode`, homegraph_explore source) go through here, so
+ * this is the chokepoint that keeps out-of-root file contents from leaking.
+ *
+ * `allowSymlinkEscape` waives **only** the realpath-escape rejection (the
+ * lexical `../` guard still applies) for the INDEXING read path. The directory
+ * walk deliberately descends into in-root symlinks whose targets live outside
+ * the root (e.g. a `game/` symlink in a Dota custom-game tree, #935); discovery
+ * and the reader must agree, or every file the walk enumerated fails to index.
+ * Indexing only reads paths it just discovered, into a local index — it never
+ * serves them to an agent, so this does not widen the #527 leak surface. The
+ * content-serving sinks must never pass this flag.
+ *
+ * @param projectRoot - The project root directory
+ * @param filePath - The (relative or absolute) file path to validate
+ * @param options.allowSymlinkEscape - Follow in-root symlinks out of the root
+ *   (indexing read path only); defaults to the strict, leak-safe behavior.
+ * @returns The resolved absolute path (realpath when it exists), or null if it
+ *   escapes the root
+ */
+export declare function validatePathWithinRoot(projectRoot: string, filePath: string, options?: {
+    allowSymlinkEscape?: boolean;
+}): string | null;
+/**
+ * Validate that a path is a safe project root directory.
+ *
+ * Rejects sensitive system directories and ensures the path is
+ * a real, existing directory. Used at MCP and API entry points
+ * to prevent arbitrary directory access.
+ *
+ * @param dirPath - The path to validate
+ * @returns An error message if invalid, or null if valid
+ */
+export declare function validateProjectPath(dirPath: string): string | null;
+/**
+ * Safely parse JSON with a fallback value.
+ * Prevents crashes from corrupted database metadata.
+ */
+export declare function safeJsonParse<T>(value: string, fallback: T): T;
+/**
+ * Clamp a numeric value to a range.
+ * Used to enforce sane limits on MCP tool inputs.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Normalize a file path to use forward slashes.
+ * Fixes Windows backslash paths so glob matching works consistently.
+ */
+export declare function normalizePath(filePath: string): string;
+/**
+ * Cross-process file lock using a lock file with PID tracking.
+ *
+ * Prevents multiple processes (e.g., git hooks, CLI, MCP server) from
+ * writing to the same database simultaneously.
+ */
+export declare class FileLock {
+    private lockPath;
+    private held;
+    /** Locks older than this are considered stale regardless of PID status */
+    private static readonly STALE_TIMEOUT_MS;
+    constructor(lockPath: string);
+    /**
+     * Acquire the lock. Throws if the lock is held by another live process.
+     */
+    acquire(): void;
+    /**
+     * Release the lock
+     */
+    release(): void;
+    /**
+     * Execute a function while holding the lock
+     */
+    withLock<T>(fn: () => T): T;
+    /**
+     * Execute an async function while holding the lock
+     */
+    withLockAsync<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Check if a process is still running
+     */
+    private isProcessAlive;
+}
+/**
+ * Process items in batches to manage memory
+ *
+ * @param items - Array of items to process
+ * @param batchSize - Number of items per batch
+ * @param processor - Function to process each item
+ * @param onBatchComplete - Optional callback after each batch
+ * @returns Array of results
+ */
+export declare function processInBatches<T, R>(items: T[], batchSize: number, processor: (item: T, index: number) => Promise<R>, onBatchComplete?: (completed: number, total: number) => void): Promise<R[]>;
+/**
+ * Simple mutex lock for preventing concurrent operations
+ */
+export declare class Mutex {
+    private locked;
+    private waitQueue;
+    /**
+     * Acquire the lock
+     *
+     * @returns A release function to call when done
+     */
+    acquire(): Promise<() => void>;
+    /**
+     * Execute a function while holding the lock
+     */
+    withLock<T>(fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * Check if the lock is currently held
+     */
+    isLocked(): boolean;
+}
+/**
+ * Chunked file reader for large files
+ *
+ * Reads a file in chunks to avoid loading entire file into memory.
+ */
+export declare function readFileInChunks(filePath: string, chunkSize?: number): AsyncGenerator<string, void, undefined>;
+/**
+ * Debounce a function
+ *
+ * @param fn - Function to debounce
+ * @param delay - Delay in milliseconds
+ * @returns Debounced function
+ */
+export declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Throttle a function
+ *
+ * @param fn - Function to throttle
+ * @param limit - Minimum time between calls in milliseconds
+ * @returns Throttled function
+ */
+export declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, limit: number): (...args: Parameters<T>) => void;
+/**
+ * Estimate memory usage of an object (rough approximation)
+ *
+ * @param obj - Object to measure
+ * @returns Approximate size in bytes
+ */
+export declare function estimateSize(obj: unknown): number;
+/**
+ * Memory monitor for tracking usage during operations
+ */
+export declare class MemoryMonitor {
+    private checkInterval;
+    private peakUsage;
+    private threshold;
+    private onThresholdExceeded?;
+    constructor(thresholdMB?: number, onThresholdExceeded?: (usage: number) => void);
+    /**
+     * Start monitoring memory usage
+     */
+    start(intervalMs?: number): void;
+    /**
+     * Stop monitoring
+     */
+    stop(): void;
+    /**
+     * Get peak memory usage in bytes
+     */
+    getPeakUsage(): number;
+    /**
+     * Get current memory usage in bytes
+     */
+    getCurrentUsage(): number;
+}
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}