eslint-plugin-sonarjs/types/helpers/files.d.ts

SonarJS rules for ESLint

/**
 * Branded types for Unix-style paths (forward slashes, normalized).
 *
 * We use phantom branding here (declare const + type intersection) rather than
 * runtime branding (like in tsconfig/options.ts with actual Symbol properties).
 * This is because:
 * - Paths are primitive strings, not objects that can hold extra properties
 * - We only need compile-time safety, not runtime verification
 * - No runtime overhead - branded paths are just regular strings at runtime
 *
 * @see tsconfig/options.ts for runtime branding of objects via Symbol properties
 */
declare const NormalizedPathBrand: unique symbol;
declare const NormalizedAbsolutePathBrand: unique symbol;
export type NormalizedPath = string & {
    readonly [NormalizedPathBrand]: never;
};
export type NormalizedAbsolutePath = string & {
    readonly [NormalizedAbsolutePathBrand]: never;
};
/**
 * Root path constant for Unix filesystem
 */
export declare const ROOT_PATH: NormalizedAbsolutePath;
export type File = {
    readonly path: NormalizedAbsolutePath;
    readonly content: Buffer | string;
};
/**
 * Removes any Byte Order Marker (BOM) from a string's head
 *
 * A string's head is nothing else but its first character.
 *
 * @param str the input string
 * @returns the stripped string
 */
export declare function stripBOM(str: string): string;
/**
 * Normalizes a path to Unix format (forward slashes).
 * For absolute paths on Windows, resolves them to ensure they have a drive letter.
 * For relative paths, only converts slashes without resolving.
 * Cross-platform behavior:
 * - On Windows: all absolute paths are resolved with win32 to add drive letter
 * - On Linux: paths are only converted (slashes), no resolution needed
 * @param filePath the path to normalize
 * @returns the normalized path as a branded UnixPath type
 */
export declare function normalizePath(filePath: string): NormalizedPath;
/**
 * Normalizes a path to an absolute Unix format.
 * Guarantees the returned path is absolute.
 * @param filePath the path to normalize
 * @param baseDir base directory to resolve relative paths against
 * @returns the normalized path as a branded AbsoluteUnixPath type
 */
export declare function normalizeToAbsolutePath(filePath: string, baseDir?: NormalizedAbsolutePath): NormalizedAbsolutePath;
export declare function isRoot(file: string): boolean;
export declare function isAbsolutePath(path: string): boolean;
/**
 * Type-safe dirname that preserves the NormalizedAbsolutePath brand.
 * The dirname of an absolute path is always absolute.
 * @param filePath the absolute path to get the directory of
 * @returns the parent directory as a branded NormalizedAbsolutePath
 */
export declare function dirnamePath(filePath: NormalizedAbsolutePath): NormalizedAbsolutePath;
/**
 * Type-safe path join that preserves the NormalizedAbsolutePath brand.
 * Joins path segments using posix separators.
 * @param base the base absolute path
 * @param segments additional path segments to join
 * @returns the joined path as a branded NormalizedAbsolutePath
 */
export declare function joinPaths(base: NormalizedAbsolutePath, ...segments: string[]): NormalizedAbsolutePath;
/**
 * Type-safe basename that extracts the filename from a path.
 * @param filePath the path to extract the basename from
 * @returns the filename (last segment of the path)
 */
export declare function basenamePath(filePath: NormalizedPath | NormalizedAbsolutePath): string;
export {};