@hyperfrontend/project-scope 0.2.1 → 0.2.3

package/core/path/index.cjs.js

@@ -1,238 +1,12 @@
 'use strict';
 
-var node_path = require('node:path');
-var node_fs = require('node:fs');
-
-/**
- * Join path segments.
- * Uses platform-specific separators (e.g., / or \).
- *
- * @param paths - Path segments to join
- * @returns Joined path
- */
-function join(...paths) {
-    return node_path.join(...paths);
-}
-/**
- * Join path segments using POSIX separators (/).
- * Always uses forward slashes regardless of platform.
- *
- * @param paths - Path segments to join
- * @returns Joined path with forward slashes
- */
-function joinPosix(...paths) {
-    return node_path.posix.join(...paths);
-}
-
-/**
- * Normalize path separators to forward slashes.
- *
- * @param filePath - Path to normalize
- * @returns Normalized path with forward slashes
- */
-function normalizePath(filePath) {
-    if (!filePath)
-        return '';
-    const normalized = node_path.normalize(filePath);
-    return node_path.sep === '\\' ? normalized.replace(/\\/g, '/') : normalized;
-}
-/**
- * Convert path separators to forward slashes using POSIX style.
- * Resolves `.` and `..` segments for cross-platform configuration.
- *
- * @param filePath - The input path to convert
- * @returns Path with forward slashes and resolved segments
- */
-function normalizeToForwardSlashes(filePath) {
-    if (!filePath)
-        return '';
-    return node_path.normalize(filePath).split(node_path.sep).join('/');
-}
-/**
- * Convert path to use the operating system's native separator.
- *
- * @param filePath - The input path to convert
- * @returns Path with native separators (backslash on Windows, forward slash elsewhere)
- */
-function normalizeToNative(filePath) {
-    if (!filePath)
-        return '';
-    return node_path.normalize(filePath.replace(/[/\\]/g, node_path.sep));
-}
-/**
- * Strip any trailing forward or back slashes from a path.
- *
- * @param filePath - Path that may have trailing slashes
- * @returns Path with trailing slashes removed
- */
-function removeTrailingSlash(filePath) {
-    let i = filePath.length;
-    while (i > 0 && (filePath[i - 1] === '/' || filePath[i - 1] === '\\')) {
-        i--;
-    }
-    return filePath.slice(0, i);
-}
-/**
- * Append a forward slash to the path if not already present.
- *
- * @param filePath - Path to process
- * @returns Path with trailing forward slash
- */
-function ensureTrailingSlash(filePath) {
-    const normalized = removeTrailingSlash(filePath);
-    return normalized + '/';
-}
-
-/**
- * Check if path exists.
- *
- * @param filePath - Path to check
- * @returns True if path exists
- */
-function exists(filePath) {
-    return node_fs.existsSync(filePath);
-}
-
-/**
- * Resolve path segments to an absolute path.
- *
- * @param segments - Path segments to resolve
- * @returns Resolved absolute path with normalized separators
- */
-function resolvePath(...segments) {
-    return normalizePath(node_path.resolve(...segments));
-}
-/**
- * Resolve path relative to workspace root.
- *
- * @param workspaceRoot - Workspace root directory
- * @param segments - Path segments relative to workspace
- * @returns Resolved absolute path with normalized separators
- */
-function resolveFromWorkspace(workspaceRoot, ...segments) {
-    return normalizePath(node_path.resolve(workspaceRoot, ...segments));
-}
-/**
- * Resolve symlinks to real path.
- *
- * @param filePath - Path to resolve
- * @returns Real path or null if path doesn't exist
- */
-function resolveRealPath(filePath) {
-    if (!exists(filePath)) {
-        return null;
-    }
-    try {
-        return normalizePath(node_fs.realpathSync(filePath));
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Compute the normalized path from source directory to target.
- *
- * @param from - Source path (base directory)
- * @param to - Target path to reach
- * @returns Relative path from source to target with forward slashes
- */
-function relativePath(from, to) {
-    return normalizePath(node_path.relative(from, to));
-}
-/**
- * Join path segments.
- *
- * @param segments - Path segments to join
- * @returns Joined path with normalized separators
- */
-function joinPath(...segments) {
-    return normalizePath(node_path.join(...segments));
-}
-/**
- * Check if path is absolute.
- *
- * @param filePath - Path to check
- * @returns True if path is absolute
- */
-function isAbsolute(filePath) {
-    return node_path.isAbsolute(filePath);
-}
-/**
- * Calculate offset from root (e.g., "../../../").
- *
- * @param filePath - Path to calculate offset for
- * @returns Relative offset path (e.g., "../../")
- */
-function offsetFromRoot(filePath) {
-    const segments = normalizePath(filePath).split('/').filter(Boolean);
-    if (segments.length === 0)
-        return '';
-    return segments.map(() => '..').join('/') + '/';
-}
-
-/**
- * Split path into segments.
- *
- * @param filePath - Path to split
- * @returns Array of path segments
- */
-function pathSegments(filePath) {
-    return filePath.split(/[/\\]/).filter((segment) => segment.length > 0);
-}
-/**
- * Get basename of path.
- *
- * @param filePath - Path to extract basename from
- * @param ext - Optional extension to strip
- * @returns Basename of path
- */
-function getBasename(filePath, ext) {
-    return node_path.basename(filePath, ext);
-}
-/**
- * Get directory name of path.
- *
- * @param filePath - Path to extract directory from
- * @returns Directory name
- */
-function getDirname(filePath) {
-    return normalizePath(node_path.dirname(filePath));
-}
-/**
- * Get file extension (including dot).
- *
- * @param filePath - Path to extract extension from
- * @returns Extension including dot (e.g., '.ts')
- */
-function getExtension(filePath) {
-    return node_path.extname(filePath);
-}
-/**
- * Get filename without extension.
- *
- * @param filePath - Path to extract name from
- * @returns Filename without extension
- */
-function getFileNameWithoutExtension(filePath) {
-    const parsed = node_path.parse(filePath);
-    return parsed.name;
-}
-/**
- * Parse path into components.
- *
- * @param filePath - Path to parse
- * @returns Parsed path components
- */
-function parsePath(filePath) {
-    const parsed = node_path.parse(filePath);
-    return {
-        root: parsed.root,
-        dir: normalizePath(parsed.dir),
-        base: parsed.base,
-        ext: parsed.ext,
-        name: parsed.name,
-    };
-}
+const node_fs = require('node:fs');
+const node_path = require('node:path');
+const { normalizePath, normalizeToForwardSlashes, normalizeToNative, removeTrailingSlash, ensureTrailingSlash } = require('../../_shared/core/path/normalize/index.cjs.js');
+const { isWithinRoot } = require('../../_shared/core/path/confine/index.cjs.js');
+const { join, joinPosix } = require('../../_shared/core/path/join/index.cjs.js');
+const { resolvePath, resolveFromWorkspace, resolveRealPath, relativePath, joinPath, isAbsolute, offsetFromRoot } = require('../../_shared/core/path/resolve/index.cjs.js');
+const { pathSegments, getBasename, getDirname, getExtension, getFileNameWithoutExtension, parsePath } = require('../../_shared/core/path/segments/index.cjs.js');
 
 exports.ensureTrailingSlash = ensureTrailingSlash;
 exports.getBasename = getBasename;
@@ -240,6 +14,7 @@ exports.getDirname = getDirname;
 exports.getExtension = getExtension;
 exports.getFileNameWithoutExtension = getFileNameWithoutExtension;
 exports.isAbsolute = isAbsolute;
+exports.isWithinRoot = isWithinRoot;
 exports.join = join;
 exports.joinPath = joinPath;
 exports.joinPosix = joinPosix;
@@ -254,4 +29,3 @@ exports.removeTrailingSlash = removeTrailingSlash;
 exports.resolveFromWorkspace = resolveFromWorkspace;
 exports.resolvePath = resolvePath;
 exports.resolveRealPath = resolveRealPath;
-//# sourceMappingURL=index.cjs.js.map

package/core/path/index.d.ts

@@ -1,5 +1,327 @@
-export * from './join';
-export * from './normalize';
-export * from './resolve';
-export * from './segments';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * Parsed path components.
+ */
+interface ParsedPath {
+    /** Root of the path (e.g., "/" or "C:\\") */
+    root: string;
+    /** Directory name */
+    dir: string;
+    /** Base name with extension */
+    base: string;
+    /** File extension including dot */
+    ext: string;
+    /** File name without extension */
+    name: string;
+}
+/**
+ * Split path into segments.
+ *
+ * @param filePath - Path to split
+ * @returns Array of path segments
+ *
+ * @example Splitting path into segments
+ * ```typescript
+ * pathSegments('src/components/Button.tsx')
+ * // => ['src', 'components', 'Button.tsx']
+ * ```
+ */
+declare function pathSegments(filePath: string): string[];
+/**
+ * Get basename of path.
+ *
+ * @param filePath - Path to extract basename from
+ * @param ext - Optional extension to strip
+ * @returns Basename of path
+ *
+ * @example Getting basename
+ * ```typescript
+ * getBasename('src/components/Button.tsx')
+ * // => 'Button.tsx'
+ *
+ * getBasename('src/components/Button.tsx', '.tsx')
+ * // => 'Button'
+ * ```
+ */
+declare function getBasename(filePath: string, ext?: string): string;
+/**
+ * Get directory name of path.
+ *
+ * @param filePath - Path to extract directory from
+ * @returns Directory name
+ *
+ * @example Getting directory name
+ * ```typescript
+ * getDirname('src/components/Button.tsx')
+ * // => 'src/components'
+ * ```
+ */
+declare function getDirname(filePath: string): string;
+/**
+ * Get file extension (including dot).
+ *
+ * @param filePath - Path to extract extension from
+ * @returns Extension including dot (e.g., '.ts')
+ *
+ * @example Getting file extension
+ * ```typescript
+ * getExtension('src/utils/helpers.ts')
+ * // => '.ts'
+ *
+ * getExtension('package.json')
+ * // => '.json'
+ * ```
+ */
+declare function getExtension(filePath: string): string;
+/**
+ * Get filename without extension.
+ *
+ * @param filePath - Path to extract name from
+ * @returns Filename without extension
+ *
+ * @example Getting filename without extension
+ * ```typescript
+ * getFileNameWithoutExtension('src/utils/helpers.ts')
+ * // => 'helpers'
+ * ```
+ */
+declare function getFileNameWithoutExtension(filePath: string): string;
+/**
+ * Parse path into components.
+ *
+ * @param filePath - Path to parse
+ * @returns Parsed path components
+ *
+ * @example Parsing path components
+ * ```typescript
+ * const parsed = parsePath('/workspace/src/index.ts')
+ * // => { root: '/', dir: '/workspace/src', base: 'index.ts', ext: '.ts', name: 'index' }
+ * ```
+ */
+declare function parsePath(filePath: string): ParsedPath;
+
+/**
+ * Reports whether `candidate` resolves to a location inside `root`.
+ *
+ * The lexical check runs first and rejects `..` traversal and absolute escapes
+ * with no filesystem access at all, so a hostile path is never stat-ed. Only a
+ * path that is already lexically contained is then resolved through symlinks, so
+ * an in-tree link cannot tunnel outside the root — and that realpath touches
+ * only paths the caller would legitimately read anyway.
+ *
+ * @param root - The directory the candidate must stay within.
+ * @param candidate - The path to validate (resolved relative to the cwd if not absolute).
+ * @returns True when the candidate is the root or contained within it.
+ *
+ * @example Confining a resolved import target
+ * ```typescript
+ * isWithinRoot('/project', '/project/src/index.ts') // true
+ * isWithinRoot('/project', '/project/../etc/passwd') // false
+ * ```
+ */
+declare function isWithinRoot(root: string, candidate: string): boolean;
+
+/**
+ * Join path segments.
+ * Uses platform-specific separators (e.g., / or \).
+ *
+ * @param paths - Path segments to join
+ * @returns Joined path
+ *
+ * @example Joining path segments
+ * ```typescript
+ * const fullPath = join('src', 'components', 'Button.tsx')
+ * // => 'src/components/Button.tsx' (or 'src\\components\\Button.tsx' on Windows)
+ * ```
+ */
+declare function join(...paths: string[]): string;
+/**
+ * Join path segments using POSIX separators (/).
+ * Always uses forward slashes regardless of platform.
+ *
+ * @param paths - Path segments to join
+ * @returns Joined path with forward slashes
+ *
+ * @example Joining paths with forward slashes
+ * ```typescript
+ * const configPath = joinPosix('config', 'settings', 'app.json')
+ * // => 'config/settings/app.json'
+ * ```
+ */
+declare function joinPosix(...paths: string[]): string;
+
+/**
+ * Normalize path separators to forward slashes.
+ *
+ * @param filePath - Path to normalize
+ * @returns Normalized path with forward slashes
+ *
+ * @example Normalizing path separators
+ * ```typescript
+ * const path = normalizePath('src\\components\\Button.tsx')
+ * // => 'src/components/Button.tsx'
+ * ```
+ */
+declare function normalizePath(filePath: string): string;
+/**
+ * Convert path separators to forward slashes using POSIX style.
+ * Resolves `.` and `..` segments for cross-platform configuration.
+ *
+ * @param filePath - The input path to convert
+ * @returns Path with forward slashes and resolved segments
+ *
+ * @example Converting to forward slashes
+ * ```typescript
+ * const path = normalizeToForwardSlashes('./src/../lib/utils')
+ * // => 'lib/utils'
+ * ```
+ */
+declare function normalizeToForwardSlashes(filePath: string): string;
+/**
+ * Convert path to use the operating system's native separator.
+ *
+ * @param filePath - The input path to convert
+ * @returns Path with native separators (backslash on Windows, forward slash elsewhere)
+ *
+ * @example Converting to native separators
+ * ```typescript
+ * const path = normalizeToNative('src/components/Button.tsx')
+ * // => 'src\\components\\Button.tsx' on Windows
+ * // => 'src/components/Button.tsx' on Unix
+ * ```
+ */
+declare function normalizeToNative(filePath: string): string;
+/**
+ * Strip any trailing forward or back slashes from a path.
+ *
+ * @param filePath - Path that may have trailing slashes
+ * @returns Path with trailing slashes removed
+ *
+ * @example Removing trailing slashes
+ * ```typescript
+ * removeTrailingSlash('src/components/')
+ * // => 'src/components'
+ *
+ * removeTrailingSlash('path\\to\\dir\\')
+ * // => 'path\\to\\dir'
+ * ```
+ */
+declare function removeTrailingSlash(filePath: string): string;
+/**
+ * Append a forward slash to the path if not already present.
+ *
+ * @param filePath - Path to process
+ * @returns Path with trailing forward slash
+ *
+ * @example Ensuring trailing slash
+ * ```typescript
+ * ensureTrailingSlash('src/components')
+ * // => 'src/components/'
+ *
+ * ensureTrailingSlash('already/has/')
+ * // => 'already/has/'
+ * ```
+ */
+declare function ensureTrailingSlash(filePath: string): string;
+
+/**
+ * Resolve path segments to an absolute path.
+ *
+ * @param segments - Path segments to resolve
+ * @returns Resolved absolute path with normalized separators
+ *
+ * @example Resolving to absolute path
+ * ```typescript
+ * const absPath = resolvePath('src', 'components', 'Button.tsx')
+ * // => '/workspace/project/src/components/Button.tsx'
+ * ```
+ */
+declare function resolvePath(...segments: string[]): string;
+/**
+ * Resolve path relative to workspace root.
+ *
+ * @param workspaceRoot - Workspace root directory
+ * @param segments - Path segments relative to workspace
+ * @returns Resolved absolute path with normalized separators
+ *
+ * @example Resolving from workspace root
+ * ```typescript
+ * const configPath = resolveFromWorkspace('/workspace', 'config', 'app.json')
+ * // => '/workspace/config/app.json'
+ * ```
+ */
+declare function resolveFromWorkspace(workspaceRoot: string, ...segments: string[]): string;
+/**
+ * Resolve symlinks to real path.
+ *
+ * @param filePath - Path to resolve
+ * @returns Real path or null if path doesn't exist
+ *
+ * @example Resolving symlinks
+ * ```typescript
+ * const realPath = resolveRealPath('./node_modules/.bin/tsc')
+ * // => '/workspace/node_modules/typescript/bin/tsc'
+ * ```
+ */
+declare function resolveRealPath(filePath: string): string | null;
+/**
+ * Compute the normalized path from source directory to target.
+ *
+ * @param from - Source path (base directory)
+ * @param to - Target path to reach
+ * @returns Relative path from source to target with forward slashes
+ *
+ * @example Computing relative path
+ * ```typescript
+ * relativePath('/workspace/src/utils', '/workspace/lib/helpers')
+ * // => '../../lib/helpers'
+ * ```
+ */
+declare function relativePath(from: string, to: string): string;
+/**
+ * Join path segments.
+ *
+ * @param segments - Path segments to join
+ * @returns Joined path with normalized separators
+ *
+ * @example Joining path segments
+ * ```typescript
+ * joinPath('src', 'components', 'Button.tsx')
+ * // => 'src/components/Button.tsx'
+ * ```
+ */
+declare function joinPath(...segments: string[]): string;
+/**
+ * Check if path is absolute.
+ *
+ * @param filePath - Path to check
+ * @returns True if path is absolute
+ *
+ * @example Checking absolute path
+ * ```typescript
+ * isAbsolute('/workspace/src/index.ts')
+ * // => true
+ *
+ * isAbsolute('./src/index.ts')
+ * // => false
+ * ```
+ */
+declare function isAbsolute(filePath: string): boolean;
+/**
+ * Calculate offset from root (e.g., "../../../").
+ *
+ * @param filePath - Path to calculate offset for
+ * @returns Relative offset path (e.g., "../../")
+ *
+ * @example Calculating offset from root
+ * ```typescript
+ * offsetFromRoot('libs/utils/src')
+ * // => '../../../'
+ *
+ * offsetFromRoot('apps')
+ * // => '../'
+ * ```
+ */
+declare function offsetFromRoot(filePath: string): string;
+
+export { ensureTrailingSlash, getBasename, getDirname, getExtension, getFileNameWithoutExtension, isAbsolute, isWithinRoot, join, joinPath, joinPosix, normalizePath, normalizeToForwardSlashes, normalizeToNative, offsetFromRoot, parsePath, pathSegments, relativePath, removeTrailingSlash, resolveFromWorkspace, resolvePath, resolveRealPath };
+export type { ParsedPath };

package/core/path/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/project-scope/src/core/path/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA;AACtB,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/project-scope/src/core/path/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACnI,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAClI,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,2BAA2B,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA"}