@compass-ai/nova 1.0.73 → 1.0.74

package/dist/utils/path.d.ts

@@ -0,0 +1,406 @@
+/**
+ * Path utilities for Compass directory management and path sanitization.
+ *
+ * This module provides utilities for:
+ * - Resolving global (~/.compass/) and project-level (./.compass/) directories
+ * - Sanitizing paths to prevent directory traversal attacks
+ * - Cross-platform path handling and normalization
+ * - Pattern matching for file filtering
+ */
+import path from 'path';
+/**
+ * Gets the global Compass directory path (~/.compass/).
+ * This directory stores user-wide configuration, credentials, and usage data.
+ *
+ * @returns Absolute path to the global Compass directory
+ *
+ * @example
+ * ```typescript
+ * const globalDir = getGlobalCompassDir();
+ * // Returns: '/home/user/.compass' (Linux/macOS)
+ * // Returns: 'C:\\Users\\user\\.compass' (Windows)
+ * ```
+ */
+export declare function getGlobalCompassDir(): string;
+/**
+ * Gets the project-level Compass directory path (./.compass/).
+ * This directory stores project-specific session data, backups, and indexes.
+ *
+ * @param projectRoot - Optional project root path. Defaults to current working directory.
+ * @returns Absolute path to the project Compass directory
+ *
+ * @example
+ * ```typescript
+ * const projectDir = getProjectCompassDir();
+ * // Returns: '/path/to/project/.compass'
+ *
+ * const customDir = getProjectCompassDir('/custom/path');
+ * // Returns: '/custom/path/.compass'
+ * ```
+ */
+export declare function getProjectCompassDir(projectRoot?: string): string;
+/**
+ * Resolves a path relative to the global Compass directory.
+ *
+ * @param segments - Path segments to join with the global directory
+ * @returns Absolute path within the global Compass directory
+ *
+ * @example
+ * ```typescript
+ * const configPath = resolveGlobalPath('config.json');
+ * // Returns: '/home/user/.compass/config.json'
+ *
+ * const logsPath = resolveGlobalPath('logs', '2024-01.log');
+ * // Returns: '/home/user/.compass/logs/2024-01.log'
+ * ```
+ */
+export declare function resolveGlobalPath(...segments: string[]): string;
+/**
+ * Resolves a path relative to the project Compass directory.
+ *
+ * @param projectRoot - The project root directory
+ * @param segments - Path segments to join with the project directory
+ * @returns Absolute path within the project Compass directory
+ *
+ * @example
+ * ```typescript
+ * const sessionPath = resolveProjectPath('/my/project', 'session.json');
+ * // Returns: '/my/project/.compass/session.json'
+ *
+ * const backupPath = resolveProjectPath('/my/project', 'backups', 'file.bak');
+ * // Returns: '/my/project/.compass/backups/file.bak'
+ * ```
+ */
+export declare function resolveProjectPath(projectRoot: string, ...segments: string[]): string;
+/**
+ * Sanitizes a path to prevent directory traversal attacks.
+ * Returns null if the path would escape the base directory.
+ *
+ * @param inputPath - The user-provided path to sanitize
+ * @param basePath - The base directory that the path must stay within
+ * @returns Sanitized absolute path, or null if path is invalid/unsafe
+ *
+ * @example
+ * ```typescript
+ * // Valid paths
+ * sanitizePath('src/index.ts', '/project');
+ * // Returns: '/project/src/index.ts'
+ *
+ * sanitizePath('./utils/helper.ts', '/project');
+ * // Returns: '/project/utils/helper.ts'
+ *
+ * // Invalid paths (directory traversal attempts)
+ * sanitizePath('../../../etc/passwd', '/project');
+ * // Returns: null
+ *
+ * sanitizePath('/etc/passwd', '/project');
+ * // Returns: null (absolute path outside base)
+ * ```
+ */
+export declare function sanitizePath(inputPath: string, basePath: string): string | null;
+/**
+ * Checks if a target path is within a given base directory.
+ *
+ * @param targetPath - The path to check
+ * @param basePath - The base directory
+ * @returns True if the target path is within the base directory
+ *
+ * @example
+ * ```typescript
+ * isPathWithin('/project/src/index.ts', '/project');
+ * // Returns: true
+ *
+ * isPathWithin('/project', '/project');
+ * // Returns: true
+ *
+ * isPathWithin('/other/path', '/project');
+ * // Returns: false
+ * ```
+ */
+export declare function isPathWithin(targetPath: string, basePath: string): boolean;
+/**
+ * Gets the relative path from a base directory to a target path.
+ *
+ * @param targetPath - The target path
+ * @param basePath - The base directory
+ * @returns Relative path from base to target
+ *
+ * @example
+ * ```typescript
+ * getRelativePath('/project/src/index.ts', '/project');
+ * // Returns: 'src/index.ts'
+ *
+ * getRelativePath('/project', '/project');
+ * // Returns: ''
+ * ```
+ */
+export declare function getRelativePath(targetPath: string, basePath: string): string;
+/**
+ * Normalizes path separators for cross-platform compatibility.
+ * Replaces multiple consecutive separators with a single platform-specific separator.
+ *
+ * @param inputPath - The path to normalize
+ * @returns Path with normalized separators
+ *
+ * @example
+ * ```typescript
+ * normalizeSeparators('src//utils\\\\helper.ts');
+ * // Returns: 'src/utils/helper.ts' (on Unix)
+ * // Returns: 'src\\utils\\helper.ts' (on Windows)
+ * ```
+ */
+export declare function normalizeSeparators(inputPath: string): string;
+/**
+ * Converts a path to use forward slashes (for display, storage, or cross-platform consistency).
+ *
+ * @param inputPath - The path to convert
+ * @returns Path with forward slashes
+ *
+ * @example
+ * ```typescript
+ * toForwardSlashes('src\\utils\\helper.ts');
+ * // Returns: 'src/utils/helper.ts'
+ *
+ * toForwardSlashes('src/utils/helper.ts');
+ * // Returns: 'src/utils/helper.ts'
+ * ```
+ */
+export declare function toForwardSlashes(inputPath: string): string;
+/**
+ * Converts a path to use the platform-specific separator.
+ *
+ * @param inputPath - The path to convert
+ * @returns Path with platform-specific separators
+ *
+ * @example
+ * ```typescript
+ * toPlatformSeparators('src/utils/helper.ts');
+ * // Returns: 'src/utils/helper.ts' (on Unix)
+ * // Returns: 'src\\utils\\helper.ts' (on Windows)
+ * ```
+ */
+export declare function toPlatformSeparators(inputPath: string): string;
+/**
+ * Gets the file extension without the leading dot.
+ *
+ * @param filePath - The file path
+ * @returns File extension without dot, or empty string if no extension
+ *
+ * @example
+ * ```typescript
+ * getExtension('src/index.ts');
+ * // Returns: 'ts'
+ *
+ * getExtension('Makefile');
+ * // Returns: ''
+ *
+ * getExtension('.gitignore');
+ * // Returns: 'gitignore'
+ * ```
+ */
+export declare function getExtension(filePath: string): string;
+/**
+ * Gets the filename without its extension.
+ *
+ * @param filePath - The file path
+ * @returns Filename without extension
+ *
+ * @example
+ * ```typescript
+ * getBasename('src/index.ts');
+ * // Returns: 'index'
+ *
+ * getBasename('config.json');
+ * // Returns: 'config'
+ * ```
+ */
+export declare function getBasename(filePath: string): string;
+/**
+ * Gets the filename with extension.
+ *
+ * @param filePath - The file path
+ * @returns Filename with extension
+ *
+ * @example
+ * ```typescript
+ * getFilename('src/utils/helper.ts');
+ * // Returns: 'helper.ts'
+ * ```
+ */
+export declare function getFilename(filePath: string): string;
+/**
+ * Gets the directory name from a file path.
+ *
+ * @param filePath - The file path
+ * @returns Directory path
+ *
+ * @example
+ * ```typescript
+ * getDirname('src/utils/helper.ts');
+ * // Returns: 'src/utils'
+ * ```
+ */
+export declare function getDirname(filePath: string): string;
+/**
+ * Checks if a path matches any of the given glob patterns.
+ *
+ * @param filePath - The file path to check
+ * @param patterns - Array of glob patterns to match against
+ * @returns True if the path matches any pattern
+ *
+ * @example
+ * ```typescript
+ * matchesPattern('src/index.ts', ['*.ts', '*.js']);
+ * // Returns: true
+ *
+ * matchesPattern('node_modules/pkg/index.js', ['node_modules/**']);
+ * // Returns: true
+ *
+ * matchesPattern('src/index.ts', ['*.json']);
+ * // Returns: false
+ * ```
+ */
+export declare function matchesPattern(filePath: string, patterns: string[]): boolean;
+/**
+ * Joins path segments and normalizes the result.
+ *
+ * @param segments - Path segments to join
+ * @returns Joined and normalized path
+ *
+ * @example
+ * ```typescript
+ * joinPath('src', 'utils', 'helper.ts');
+ * // Returns: 'src/utils/helper.ts' (on Unix)
+ * ```
+ */
+export declare function joinPath(...segments: string[]): string;
+/**
+ * Resolves a sequence of paths to an absolute path.
+ *
+ * @param segments - Path segments to resolve
+ * @returns Absolute path
+ *
+ * @example
+ * ```typescript
+ * resolvePath('src', 'utils', 'helper.ts');
+ * // Returns: '/current/working/dir/src/utils/helper.ts'
+ * ```
+ */
+export declare function resolvePath(...segments: string[]): string;
+/**
+ * Checks if a path is absolute.
+ *
+ * @param inputPath - The path to check
+ * @returns True if the path is absolute
+ *
+ * @example
+ * ```typescript
+ * isAbsolutePath('/home/user/project');
+ * // Returns: true
+ *
+ * isAbsolutePath('src/index.ts');
+ * // Returns: false
+ * ```
+ */
+export declare function isAbsolutePath(inputPath: string): boolean;
+/**
+ * Ensures a path ends with a trailing separator.
+ *
+ * @param inputPath - The path to process
+ * @returns Path with trailing separator
+ *
+ * @example
+ * ```typescript
+ * ensureTrailingSeparator('/home/user');
+ * // Returns: '/home/user/'
+ *
+ * ensureTrailingSeparator('/home/user/');
+ * // Returns: '/home/user/'
+ * ```
+ */
+export declare function ensureTrailingSeparator(inputPath: string): string;
+/**
+ * Removes trailing separator from a path.
+ *
+ * @param inputPath - The path to process
+ * @returns Path without trailing separator
+ *
+ * @example
+ * ```typescript
+ * removeTrailingSeparator('/home/user/');
+ * // Returns: '/home/user'
+ *
+ * removeTrailingSeparator('/home/user');
+ * // Returns: '/home/user'
+ * ```
+ */
+export declare function removeTrailingSeparator(inputPath: string): string;
+/**
+ * Gets the common base path from an array of paths.
+ *
+ * @param paths - Array of paths to find common base for
+ * @returns Common base path, or empty string if no common base
+ *
+ * @example
+ * ```typescript
+ * getCommonBasePath([
+ *   '/project/src/index.ts',
+ *   '/project/src/utils/helper.ts',
+ *   '/project/tests/test.ts'
+ * ]);
+ * // Returns: '/project'
+ * ```
+ */
+export declare function getCommonBasePath(paths: string[]): string;
+/**
+ * Checks if a filename matches common hidden file patterns.
+ *
+ * @param filePath - The file path to check
+ * @returns True if the file is hidden
+ *
+ * @example
+ * ```typescript
+ * isHiddenFile('.gitignore');
+ * // Returns: true
+ *
+ * isHiddenFile('src/index.ts');
+ * // Returns: false
+ * ```
+ */
+export declare function isHiddenFile(filePath: string): boolean;
+/**
+ * Parses a path into its components.
+ *
+ * @param filePath - The path to parse
+ * @returns Object containing path components
+ *
+ * @example
+ * ```typescript
+ * parsePath('/home/user/project/src/index.ts');
+ * // Returns: {
+ * //   root: '/',
+ * //   dir: '/home/user/project/src',
+ * //   base: 'index.ts',
+ * //   ext: '.ts',
+ * //   name: 'index'
+ * // }
+ * ```
+ */
+export declare function parsePath(filePath: string): path.ParsedPath;
+/**
+ * Formats path components into a path string.
+ *
+ * @param pathObject - Object containing path components
+ * @returns Formatted path string
+ *
+ * @example
+ * ```typescript
+ * formatPath({
+ *   dir: '/home/user/project/src',
+ *   base: 'index.ts'
+ * });
+ * // Returns: '/home/user/project/src/index.ts'
+ * ```
+ */
+export declare function formatPath(pathObject: path.FormatInputPathObject): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/utils/path.d.ts.map

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