@hyperfrontend/project-scope 0.2.0 → 0.2.2

package/core/index.d.ts

@@ -1,9 +1,486 @@
-export * from './fs';
-export * from './path';
-export * from './encoding';
-export * from './platform';
-export * from './errors/structured-errors';
-export * from './patterns/glob';
-export * from './logger';
-export * from './cache';
-//# sourceMappingURL=index.d.ts.map
+export { BINARY_SIGNATURES, EncodingInfo, UTF16_BE_BOM_BYTES, UTF16_LE_BOM_BYTES, UTF8_BOM, UTF8_BOM_BYTES, addBom, bufferToString, detectEncoding, detectEncodingInfo, hasBom, isTextFile, stripBom, toUtf8 } from './encoding';
+export { DirectoryEntry, FileStats, FileSystemErrorCode, FileSystemErrorContext, ReadJsonFileOptions, RecursiveOptions, WriteFileOptions, WriteJsonOptions, createDirectory, createFileSystemError, ensureDir, exists, findUpwardWhere, getFileStat, isDirectory, isFile, isSymlink, locateByMarkers, readDirectory, readDirectoryRecursive, readFileBuffer, readFileContent, readFileIfExists, readJsonFile, readJsonFileIfExists, removeDirectory, traverseUpward, writeFileBuffer, writeFileContent, writeJsonFile } from './fs';
+import { LogLevel } from '../_dependencies/@hyperfrontend/logging/index.js';
+export { LogLevel } from '../_dependencies/@hyperfrontend/logging/index.js';
+export { ParsedPath, ensureTrailingSlash, getBasename, getDirname, getExtension, getFileNameWithoutExtension, isAbsolute, join, joinPath, joinPosix, normalizePath, normalizeToForwardSlashes, normalizeToNative, offsetFromRoot, parsePath, pathSegments, relativePath, removeTrailingSlash, resolveFromWorkspace, resolvePath, resolveRealPath } from './path';
+export { CRLF, DetectedLineEnding, LF, LineEndingStyle, PlatformInfo, detectCaseSensitivity, detectLineEnding, detectPlatform, getLineEnding, getPathSeparator, getPlatformInfo, isCaseSensitiveFs, isWindows, normalizeLineEndings, pathsEqual } from './platform';
+
+/**
+ * Options for cache creation.
+ */
+interface CacheOptions {
+    /**
+     * Time to live in milliseconds.
+     * Entries older than this will be considered expired.
+     */
+    ttl?: number;
+    /**
+     * Maximum number of entries in cache.
+     * When exceeded, oldest entries are evicted (FIFO).
+     */
+    maxSize?: number;
+}
+/**
+ * Cache interface for storing key-value pairs with optional TTL and size limits.
+ */
+interface Cache<K, V> {
+    /**
+     * Get a value from the cache.
+     *
+     * @param key - Cache key
+     * @returns Cached value or undefined if not found or expired
+     */
+    get(key: K): V | undefined;
+    /**
+     * Set a value in the cache.
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     */
+    set(key: K, value: V): void;
+    /**
+     * Check if a key exists in the cache (and is not expired).
+     *
+     * @param key - Cache key
+     * @returns True if key exists and is not expired
+     */
+    has(key: K): boolean;
+    /**
+     * Delete a key from the cache.
+     *
+     * @param key - Cache key
+     * @returns True if the key was deleted
+     */
+    delete(key: K): boolean;
+    /**
+     * Clear all entries from the cache.
+     */
+    clear(): void;
+    /**
+     * Get the current number of entries in the cache.
+     *
+     * @returns Number of entries
+     */
+    size(): number;
+    /**
+     * Get all keys in the cache.
+     *
+     * @returns Array of keys
+     */
+    keys(): K[];
+}
+/**
+ * Create a cache with optional TTL and size limits.
+ *
+ * The cache provides a simple key-value store with:
+ * - Optional TTL (time-to-live) for automatic expiration
+ * - Optional maxSize for limiting cache size with FIFO eviction
+ * - Lazy expiration (entries are checked on access)
+ *
+ * @param options - Cache configuration options
+ * @returns Cache instance
+ *
+ * @example Creating caches with different options
+ * ```typescript
+ * // Basic cache
+ * const cache = createCache<string, number>()
+ * cache.set('answer', 42)
+ * cache.get('answer') // 42
+ *
+ * // Cache with TTL (expires after 60 seconds)
+ * const ttlCache = createCache<string, object>({ ttl: 60000 })
+ *
+ * // Cache with max size (evicts oldest when full)
+ * const lruCache = createCache<string, object>({ maxSize: 100 })
+ *
+ * // Combined options
+ * const configCache = createCache<string, object>({
+ *   ttl: 30000,
+ *   maxSize: 50
+ * })
+ * ```
+ */
+declare function createCache<K, V>(options?: CacheOptions): Cache<K, V>;
+/**
+ * Clear all registered caches.
+ *
+ * Useful for testing or when a global state reset is needed.
+ * This clears all caches created via `createCache()`.
+ *
+ * @example Clearing caches in tests
+ * ```typescript
+ * // In tests
+ * afterEach(() => {
+ *   clearAllCaches()
+ * })
+ * ```
+ */
+declare function clearAllCaches(): void;
+/**
+ * Get the number of registered caches.
+ *
+ * Primarily used for testing.
+ *
+ * @returns Number of registered caches
+ *
+ * @example Getting the number of active caches
+ * ```typescript
+ * const count = getCacheCount()
+ * // => 3 (number of active caches)
+ * ```
+ */
+declare function getCacheCount(): number;
+/**
+ * Unregister a cache from the global registry.
+ *
+ * Useful for cleanup in tests or when a cache is no longer needed.
+ *
+ * @param cache - Cache to unregister
+ * @returns True if cache was unregistered
+ *
+ * @example Unregistering a cache from the registry
+ * ```typescript
+ * const myCache = createCache<string, number>({ name: 'temp-cache' })
+ * const wasRemoved = unregisterCache(myCache)
+ * // => true
+ * ```
+ */
+declare function unregisterCache<K, V>(cache: Cache<K, V>): boolean;
+/**
+ * Adds a `cache` accessor to a memoized function, exposing the underlying cache
+ * for direct inspection or invalidation.
+ *
+ * @template K - Cache key type
+ * @template V - Cached value type
+ */
+type WithCache<K, V> = {
+    /** Underlying cache instance for direct access and control */
+    cache: Cache<K, V>;
+};
+/**
+ * Function returned by {@link memoize}: behaves like the original function but
+ * exposes a `cache` for direct manipulation.
+ *
+ * @template K - Cache key type
+ * @template V - Cached value type
+ */
+type MemoizedFunction<K, V> = ((key: K) => V) & WithCache<K, V>;
+/**
+ * Create a memoized version of a function with caching.
+ *
+ * The memoized function caches results based on the first argument (key).
+ * If additional arguments are needed, use the options.keyFn parameter.
+ *
+ * @param fn - Function to memoize
+ * @param options - Cache options for the underlying cache
+ * @returns Memoized function with cache control methods
+ *
+ * @example Memoizing an expensive function
+ * ```typescript
+ * // Memoize a detection function
+ * const detectTechStackMemo = memoize(
+ *   (path: string) => expensiveDetection(path),
+ *   { ttl: 60000 }
+ * )
+ *
+ * const result1 = detectTechStackMemo('/path/to/project')
+ * const result2 = detectTechStackMemo('/path/to/project') // Returns cached
+ *
+ * // Clear the cache
+ * detectTechStackMemo.cache.clear()
+ * ```
+ */
+declare function memoize<K, V>(fn: (key: K) => V, options?: CacheOptions): MemoizedFunction<K, V>;
+
+/**
+ * Structured error with code and context.
+ */
+interface StructuredError extends Error {
+    /** Machine-readable error code for programmatic handling */
+    code: string;
+    /** Additional contextual information about the error */
+    context?: Record<string, unknown>;
+}
+/**
+ * Create a structured error with code and optional context.
+ *
+ * @param message - The human-readable error message
+ * @param code - The machine-readable error code for programmatic handling
+ * @param context - Additional contextual information about the error
+ * @returns Structured error instance with code and context properties
+ *
+ * @example Creating a structured error with context
+ * ```typescript
+ * import { createStructuredError } from '@hyperfrontend/project-scope'
+ *
+ * throw createStructuredError(
+ *   'Configuration file not found',
+ *   'CONFIG_NOT_FOUND',
+ *   { path: './config.json', searched: ['./config.json', './settings.json'] }
+ * )
+ * ```
+ */
+declare function createStructuredError(message: string, code: string, context?: Record<string, unknown>): StructuredError;
+/**
+ * Create a configuration-related error.
+ *
+ * @param message - The human-readable error message
+ * @param code - The machine-readable error code for programmatic handling
+ * @param context - Additional contextual information (e.g., file path, config key)
+ * @returns Structured error instance tagged with type 'config'
+ *
+ * @example Creating a configuration error
+ * ```typescript
+ * throw createConfigError(
+ *   'Invalid port number',
+ *   'CONFIG_INVALID_PORT',
+ *   { configFile: './app.config.json', value: -1 }
+ * )
+ * ```
+ */
+declare function createConfigError(message: string, code: string, context?: Record<string, unknown>): StructuredError;
+/**
+ * Create a filesystem-related error.
+ *
+ * @param message - The human-readable error message
+ * @param code - The filesystem error code (e.g., ENOENT for not found, EACCES for access denied)
+ * @param context - Additional contextual information (e.g., file path, operation attempted)
+ * @returns Structured error instance tagged with type 'fs'
+ *
+ * @example Creating a filesystem error
+ * ```typescript
+ * throw createFsError(
+ *   'Configuration file not found',
+ *   'ENOENT',
+ *   { path: './missing.json', operation: 'read' }
+ * )
+ * ```
+ */
+declare function createFsError(message: string, code: string, context?: Record<string, unknown>): StructuredError;
+/**
+ * Create a parsing-related error.
+ *
+ * @param message - The human-readable error message
+ * @param code - The machine-readable error code for programmatic handling
+ * @param context - Additional contextual information (e.g., file path, line/column numbers, expected format)
+ * @returns Structured error instance tagged with type 'parse'
+ *
+ * @example Creating a parse error
+ * ```typescript
+ * throw createParseError(
+ *   'Invalid JSON syntax',
+ *   'JSON_PARSE_ERROR',
+ *   { file: './config.json', line: 42, column: 15 }
+ * )
+ * ```
+ */
+declare function createParseError(message: string, code: string, context?: Record<string, unknown>): StructuredError;
+/**
+ * Create a validation-related error.
+ *
+ * @param message - The human-readable error message
+ * @param code - The machine-readable error code for programmatic handling
+ * @param context - Additional contextual information (e.g., field name, actual vs expected values)
+ * @returns Structured error instance tagged with type 'validation'
+ *
+ * @example Creating a validation error
+ * ```typescript
+ * throw createValidationError(
+ *   'Email format is invalid',
+ *   'INVALID_EMAIL',
+ *   { field: 'email', value: 'not-an-email' }
+ * )
+ * ```
+ */
+declare function createValidationError(message: string, code: string, context?: Record<string, unknown>): StructuredError;
+
+/**
+ * Set the log level for all registered scoped loggers.
+ * This is useful for enabling verbose logging across the entire library.
+ *
+ * @param level - The log level to set globally
+ *
+ * @example Enabling debug logging globally
+ * ```typescript
+ * import { setGlobalLogLevel } from '@hyperfrontend/project-scope/core'
+ *
+ * // Enable debug logging for all project-scope modules
+ * setGlobalLogLevel('debug')
+ * ```
+ */
+declare function setGlobalLogLevel(level: LogLevel): void;
+/**
+ * Get the current global log level.
+ *
+ * @returns The global log level, or null if not set
+ *
+ * @example Getting current log level
+ * ```typescript
+ * setGlobalLogLevel('debug')
+ * const level = getGlobalLogLevel()
+ * // => 'debug'
+ * ```
+ */
+declare function getGlobalLogLevel(): LogLevel | null;
+/**
+ * Reset the global log level override.
+ * Each logger will retain its current level but new loggers will use their default.
+ *
+ * @example Resetting the global log level
+ * ```typescript
+ * setGlobalLogLevel('debug')
+ * // ... perform debugging ...
+ * resetGlobalLogLevel()
+ * // Global override removed, loggers use individual levels
+ * ```
+ */
+declare function resetGlobalLogLevel(): void;
+/**
+ * Sanitizes an object by replacing sensitive values with REDACTED.
+ * This function recursively processes nested objects and arrays.
+ *
+ * @param obj - Object to sanitize
+ * @returns New object with sensitive values redacted
+ *
+ * @example Sanitizing sensitive data
+ * ```typescript
+ * const config = { apiKey: 'secret123', endpoint: 'https://api.example.com' }
+ * const safe = sanitize(config)
+ * // => { apiKey: '[REDACTED]', endpoint: 'https://api.example.com' }
+ * ```
+ */
+declare function sanitize(obj: unknown): unknown;
+/**
+ * Options for creating a scoped logger.
+ */
+interface ScopedLoggerOptions {
+    /**
+     * Initial log level.
+     * Messages below this level will not be logged.
+     *
+     * @default 'error'
+     */
+    level?: LogLevel;
+    /**
+     * Whether to sanitize sensitive data in metadata.
+     *
+     * @default true
+     */
+    sanitizeSecrets?: boolean;
+}
+/**
+ * A scoped logger instance with namespace prefix and secret sanitization.
+ */
+interface ScopedLogger {
+    /** Log at error level */
+    error: (message: string, meta?: object) => void;
+    /** Log at warn level */
+    warn: (message: string, meta?: object) => void;
+    /** Log at log level */
+    log: (message: string, meta?: object) => void;
+    /** Log at info level */
+    info: (message: string, meta?: object) => void;
+    /** Log at debug level */
+    debug: (message: string, meta?: object) => void;
+    /** Set the current log level */
+    setLogLevel: (level: LogLevel) => void;
+    /** Get the current log level */
+    getLogLevel: () => LogLevel;
+}
+/**
+ * Creates a scoped logger with namespace prefix and optional secret sanitization.
+ * All log messages will be prefixed with [namespace] and sensitive metadata
+ * values will be automatically redacted.
+ *
+ * @param namespace - Logger namespace (e.g., 'project-scope', 'analyze')
+ * @param options - Logger configuration options
+ * @returns A configured scoped logger instance
+ *
+ * @example Creating a scoped logger
+ * ```typescript
+ * const logger = createScopedLogger('project-scope')
+ * logger.setLogLevel('debug')
+ *
+ * // Basic logging
+ * logger.info('Starting analysis', { path: './project' })
+ *
+ * // Sensitive data is automatically redacted
+ * logger.debug('Config loaded', { apiKey: 'secret123' })
+ * // Output: [project-scope] Config loaded {"apiKey":"[REDACTED]"}
+ * ```
+ */
+declare function createScopedLogger(namespace: string, options?: ScopedLoggerOptions): ScopedLogger;
+/**
+ * Default logger instance for the project-scope library.
+ * Use this for general logging within the library.
+ *
+ * @example Using the default logger
+ * ```typescript
+ * import { logger } from '@hyperfrontend/project-scope/core'
+ *
+ * logger.setLogLevel('debug')
+ * logger.debug('Analyzing project', { path: './src' })
+ * ```
+ */
+declare const logger: ScopedLogger;
+
+/**
+ * Match path against glob pattern using safe character iteration.
+ * Avoids regex to prevent ReDoS attacks.
+ *
+ * Supported patterns:
+ * - * matches any characters except /
+ * - ** matches any characters including /
+ * - ? matches exactly one character except /
+ * - {a,b,c} matches any of the alternatives
+ *
+ * @param path - The filesystem path to test against the pattern
+ * @param pattern - The glob pattern to match against
+ * @returns True if path matches pattern
+ *
+ * @example Matching paths against glob patterns
+ * ```typescript
+ * import { matchGlobPattern } from '@hyperfrontend/project-scope'
+ *
+ * matchGlobPattern('src/utils/helper.ts', '\*\*\/*.ts')     // true
+ * matchGlobPattern('test.spec.ts', '\*.spec.ts')          // true
+ * matchGlobPattern('config.json', '\*.{json,yaml}')       // true
+ * matchGlobPattern('src/index.ts', 'src/\*.ts')           // true
+ * ```
+ */
+declare function matchGlobPattern(path: string, pattern: string): boolean;
+/**
+ * Test if path matches any of the patterns.
+ *
+ * @param path - Path to test
+ * @param patterns - Array of glob patterns
+ * @returns True if path matches any pattern
+ *
+ * @example Checking path against multiple patterns
+ * ```typescript
+ * const ignorePatterns = ['*.log', 'node_modules/**', '*.tmp']
+ * const shouldIgnore = matchesAnyPattern('debug.log', ignorePatterns)
+ * // => true
+ * ```
+ */
+declare function matchesAnyPattern(path: string, patterns: readonly string[]): boolean;
+/**
+ * Test if path exactly matches the pattern (no glob).
+ *
+ * @param path - Path to test
+ * @param pattern - Exact pattern to match
+ * @returns True if path equals pattern
+ *
+ * @example Exact path matching
+ * ```typescript
+ * matchesExact('package.json', 'package.json')
+ * // => true
+ *
+ * matchesExact('src/package.json', 'package.json')
+ * // => false
+ * ```
+ */
+declare function matchesExact(path: string, pattern: string): boolean;
+
+export { clearAllCaches, createCache, createConfigError, createFsError, createParseError, createScopedLogger, createStructuredError, createValidationError, getCacheCount, getGlobalLogLevel, logger, matchGlobPattern, matchesAnyPattern, matchesExact, memoize, resetGlobalLogLevel, sanitize, setGlobalLogLevel, unregisterCache };
+export type { Cache, CacheOptions, ScopedLogger, ScopedLoggerOptions, StructuredError };

package/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../libs/project-scope/src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,MAAM,CAAA;AACpB,cAAc,QAAQ,CAAA;AACtB,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,4BAA4B,CAAA;AAC1C,cAAc,iBAAiB,CAAA;AAC/B,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../libs/project-scope/src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAClD,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,YAAY,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AACjE,YAAY,EACV,cAAc,EACd,SAAS,EACT,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,MAAM,CAAA;AACb,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC3E,YAAY,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AACxC,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACnF,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC9F,OAAO,EACL,MAAM,EACN,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,MAAM,EACN,UAAU,EACV,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,SAAS,EACT,MAAM,EACN,eAAe,EACf,WAAW,EACX,WAAW,EACX,MAAM,EACN,SAAS,EACT,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,aAAa,GACd,MAAM,MAAM,CAAA;AACb,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAC1H,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,UAAU,EACV,YAAY,EACZ,2BAA2B,EAC3B,UAAU,EACV,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,aAAa,EACb,yBAAyB,EACzB,iBAAiB,EACjB,cAAc,EACd,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EACX,eAAe,GAChB,MAAM,QAAQ,CAAA;AACf,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACnF,OAAO,EACL,IAAI,EACJ,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,SAAS,EACT,EAAE,EACF,oBAAoB,EACpB,UAAU,GACX,MAAM,YAAY,CAAA"}