@reliverse/pathkit 1.1.0 → 1.1.1

package/README.md

@@ -6,13 +6,13 @@
 
 ## Key Features
 
-- 🔹 **drop in** and replace `node:path` and `unjs/pathe` instantly.
-- ➕ **`unjs/pathe` on steroids** – alias resolution, import parsing, and more.
-- 🌀 **always `/`** – posix separators 100% of the time (buh‑bye `\\`).
-- ⚙️ **node.js api compatible** – familiar methods, no learning curve.
-- 🚀 **modern & fast** – typescript, pure esm, bun & node‑ready.
-- 🧠 **predictable & testable** – deterministic output across windows / macos / linux.
-- 🧼 **no dependencies** – just the path api + a couple of cool utilities.
+- 🔹 **drop in** and replace `node:path` and `unjs/pathe` instantly
+- ➕ **`unjs/pathe` on steroids** – alias resolution, import parsing, and more
+- 🌀 **always `/`** – posix separators 100% of the time (buh‑bye `\\`)
+- ⚙️ **node.js api compatible** – familiar methods, no learning curve
+- 🚀 **modern & fast** – typescript, pure esm, bun & node‑ready
+- 🧠 **predictable & testable** – deterministic output across windows / macos / linux
+- 🧼 **no dependencies** – just better path api + couple of cool utilities = [4.2 kB](https://bundlephobia.com/package/@reliverse/pathkit@latest)
 
 ## Installation
 
@@ -24,18 +24,18 @@ bun add @reliverse/pathkit
 **Migrate**:
 
 ```bash
-bun rm pathe
 # soon:
 # bun add -D @reliverse/dler
+# bun dler migrate --lib path-to-pathkit
 # bun dler migrate --lib pathe-to-pathkit
 ```
 
-### `pathe` vs `pathkit`
+### `unjs/pathe` vs `@reliverse/pathkit`
 
 | Package | What you get | When to use |
 |---------|--------------|-------------|
-| **`@reliverse/pathe`** | Core path API (POSIX everywhere) | You only need a drop‑in for `node:path` |
-| **`@reliverse/pathkit`** | Everything in `pathe` **+** advanced utilities | You need alias resolution, import transforms, etc. |
+| **`pathe`** | Path API only (with POSIX everywhere) | You only need a drop‑in for `node:path` |
+| **`pathkit`** | Everything in `pathe` **+** advanced utilities | You need alias resolution, import transforms, etc. |
 
 ## Why Pathkit? — The Problem with Native Paths
 
@@ -196,13 +196,11 @@ console.log(reverseResolveAlias("/src/utils", aliases));  // "@/utils"
 ```ts
 import {
   filename,               // Strip extension
-  extractPackageName,     // Get package name from import
   normalizeQuotes,        // Standardize quote style
   matchesGlob            // Test glob patterns
 } from "@reliverse/pathkit";
 
 console.log(filename("/path/component.vue"));     // "component"
-console.log(extractPackageName("@scope/pkg"));    // "@scope/pkg"
 console.log(normalizeQuotes("import 'pkg'"));     // 'import "pkg"'
 console.log(matchesGlob("file.ts", "**/*.ts"));  // true
 ```

package/bin/mod.d.ts

@@ -130,6 +130,68 @@ declare function convertImportsExt({ targetDir, extFrom, extTo, }: {
         to: string;
     }[];
 }[]>;
+/**
+ * strips a specified number of segments from the beginning of a path
+ * @param path - The path to strip segments from
+ * @param count - Number of segments to strip (default: 1)
+ * @param alias - Optional alias to preserve (e.g. "@", "~")
+ * @returns The path with the specified number of segments removed
+ */
+declare function stripPathSegments(path: string, count?: number, alias?: string): string;
+/**
+ * recursively processes files in a directory to strip path segments from their contents
+ * @param targetDir - The directory to process
+ * @param segmentsToStrip - Number of segments to strip from paths
+ * @param alias - Optional alias to preserve (e.g. "@", "~")
+ * @param extensionsToProcess - Array of file extensions to process (default: EXTENSIONS)
+ * @returns Array of processed files and their changes
+ */
+declare function stripPathSegmentsInDirectory({ targetDir, segmentsToStrip, alias, extensionsToProcess, }: {
+    targetDir: string;
+    segmentsToStrip: number;
+    alias?: string;
+    extensionsToProcess?: string[];
+}): Promise<{
+    file: string;
+    changes: {
+        from: string;
+        to: string;
+    }[];
+}[]>;
+/**
+ * attaches path segments to an existing path
+ * @param path - The base path to attach segments to
+ * @param segments - The segments to attach
+ * @param options - Configuration options
+ * @returns The path with segments attached
+ */
+declare function attachPathSegments(path: string, segments: string | string[], options?: {
+    position?: "before" | "after";
+    normalize?: boolean;
+    ensureSlash?: boolean;
+    preserveRoot?: boolean;
+    preserveAlias?: string;
+}): string;
+/**
+ * recursively processes files in a directory to attach path segments to import statements
+ * @param targetDir - The directory to process
+ * @param segments - The segments to attach
+ * @param options - Configuration options for path segment attachment
+ * @param extensionsToProcess - Array of file extensions to process (default: EXTENSIONS)
+ * @returns Array of processed files and their changes
+ */
+declare function attachPathSegmentsInDirectory({ targetDir, segments, options, extensionsToProcess, }: {
+    targetDir: string;
+    segments: string | string[];
+    options?: Parameters<typeof attachPathSegments>[2];
+    extensionsToProcess?: string[];
+}): Promise<{
+    file: string;
+    changes: {
+        from: string;
+        to: string;
+    }[];
+}[]>;
 declare const _pathBase: {
     sep: string;
     normalize: (path: string) => string;
@@ -166,5 +228,5 @@ declare const path: PlatformPath & {
 declare const win32: PlatformPath;
 declare const delimiter: string;
 export type { PlatformPath, PathExtFilter, ImportExtType };
-export { _pathBase as posix, win32, basename, delimiter, dirname, extname, filename, format, isAbsolute, join, normalize, parse, relative, resolve, sep, toNamespacedPath, normalizeAliases, resolveAlias, reverseResolveAlias, normalizeWindowsPath, cleanDirs, copyDir, convertStringAliasRelative, convertImportsAliasToRelative, convertImportsExt, };
+export { _pathBase as posix, win32, basename, delimiter, dirname, extname, filename, format, isAbsolute, join, normalize, parse, relative, resolve, sep, toNamespacedPath, normalizeAliases, resolveAlias, reverseResolveAlias, normalizeWindowsPath, cleanDirs, copyDir, convertStringAliasRelative, convertImportsAliasToRelative, convertImportsExt, stripPathSegments, stripPathSegmentsInDirectory, attachPathSegments, attachPathSegmentsInDirectory, };
 export default path;

package/bin/mod.js

@@ -1,4 +1,6 @@
 import fs from "node:fs/promises";
+const log = (msg) => console.log(`\x1B[2m${msg}\x1B[0m`);
+const logInternal = (msg) => console.log(`\x1B[36;2m${msg}\x1B[0m`);
 const EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
 const SLASH = "/";
 const BACK_SLASH = "\\";
@@ -13,13 +15,12 @@ const IS_ABSOLUTE_RE = /^[/\\](?![/\\])|^[/\\]{2}(?!\.)|^[A-Za-z]:[/\\]/;
 const ROOT_FOLDER_RE = /^\/([A-Za-z]:)?$/;
 const PATH_ROOT_RE = /^[/\\]|^[a-zA-Z]:[/\\]/;
 const IMPORT_REGEX = /(?:import\s+(?:[\s\S]*?)\s+from\s+|import\s*\(\s*)\s*(['"])((?:@)[^'"]+)\1/g;
-const log = (msg) => console.log(`\x1B[2m${msg}\x1B[0m`);
 async function cleanDirs(dirs) {
   await Promise.all(
     dirs.map(async (d) => {
       try {
         await fs.rm(d, { recursive: true, force: true });
-        log(`\u2713 cleaned: ${d}`);
+        logInternal(`\u2713 cleaned: ${d}`);
       } catch (error) {
         log(
           `\u2717 error cleaning ${d}: ${error instanceof Error ? error.message : String(error)}`
@@ -29,7 +30,7 @@ async function cleanDirs(dirs) {
   );
 }
 async function copyDir(src, dest) {
-  log(`\u2713 copying: ${src} \u2192 ${dest}`);
+  logInternal(`\u2713 copying: ${src} \u2192 ${dest}`);
   try {
     await fs.mkdir(dest, { recursive: true });
     const entries = await fs.readdir(src, { withFileTypes: true });
@@ -41,7 +42,7 @@ async function copyDir(src, dest) {
           return copyDir(srcPath, destPath);
         }
         await fs.copyFile(srcPath, destPath);
-        log(`  copied: ${srcPath} \u2192 ${destPath}`);
+        logInternal(`  copied: ${srcPath} \u2192 ${destPath}`);
       })
     );
   } catch (error) {
@@ -499,7 +500,7 @@ async function processFile(filePath, aliasToReplace, targetDir, pathExtFilter) {
   }
   if (content !== updated) {
     await fs.writeFile(filePath, updated);
-    log(`\u2713 processed: ${filePath}`);
+    logInternal(`\u2713 processed: ${filePath}`);
   }
   return changes;
 }
@@ -537,6 +538,8 @@ async function processAllFiles({
           if (changes.length > 0) {
             results.push({ file: fullPath, changes });
           }
+        } else {
+          logInternal(`  - skipping non-matching file: ${entry.name}`);
         }
       })
     );
@@ -559,7 +562,7 @@ async function convertImportsAliasToRelative({
     `Converting aliased imports starting with '${aliasToReplace}' to relative paths in "${targetDir}"...`
   );
   log(`   (Assuming "${normalizedAlias}" resolves relative to "${targetDir}")`);
-  log(`   (Using extension mode: ${pathExtFilter})`);
+  logInternal(`   (Using extension mode: ${pathExtFilter})`);
   const results = await processAllFiles({
     srcDir: targetDir,
     aliasToReplace: normalizedAlias,
@@ -586,6 +589,9 @@ async function convertImportsExt({
   extFrom,
   extTo
 }) {
+  logInternal(
+    `Converting import extensions from '${extFrom}' to '${extTo}' in "${targetDir}"...`
+  );
   const fromExtStr = extFrom === "none" ? "" : `.${extFrom}`;
   const toExtStr = extTo === "none" ? "" : `.${extTo}`;
   const importRegex = new RegExp(
@@ -632,11 +638,13 @@ async function convertImportsExt({
           }
           if (content !== updated) {
             await fs.writeFile(fullPath, updated);
-            log(`\u2713 processed: ${fullPath}`);
+            logInternal(`\u2713 processed: ${fullPath}`);
             if (changes.length > 0) {
               results.push({ file: fullPath, changes });
             }
           }
+        } else {
+          logInternal(`  - skipping non-matching file: ${entry.name}`);
         }
       })
     );
@@ -651,6 +659,266 @@ async function convertImportsExt({
       }
     } else {
     }
+    logInternal("Extension conversion complete.");
+    return results;
+  } catch (error) {
+    log(
+      `error processing directory ${targetDir}: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return [];
+  }
+}
+function stripPathSegments(path2, count = 1, alias = "") {
+  if (typeof path2 !== "string" || path2.length === 0) return path2;
+  if (count <= 0) return path2;
+  logInternal(`[stripPathSegments] Processing path: ${path2}`);
+  logInternal(`  - count: ${count}, alias: ${alias}`);
+  const normalizedPath = normalizeWindowsPath(path2);
+  logInternal(`  - normalized: ${normalizedPath}`);
+  const parsed = parse(normalizedPath);
+  logInternal(`  - parsed: ${JSON.stringify(parsed)}`);
+  let pathSegments = [];
+  if (parsed.dir && parsed.dir !== parsed.root) {
+    let dirRelativeToRoot = parsed.dir;
+    if (parsed.root && parsed.dir.startsWith(parsed.root)) {
+      dirRelativeToRoot = parsed.dir.substring(parsed.root.length);
+    }
+    pathSegments.push(...dirRelativeToRoot.split(SLASH));
+  }
+  if (parsed.base) {
+    pathSegments.push(parsed.base);
+  }
+  pathSegments = pathSegments.filter(Boolean);
+  logInternal(`  - initial segments: ${JSON.stringify(pathSegments)}`);
+  const leadingPreservedSegments = [];
+  if (alias && pathSegments.length > 0 && pathSegments[0].startsWith(alias)) {
+    const preserved = pathSegments.shift();
+    leadingPreservedSegments.push(preserved);
+    logInternal(`  - preserved alias segment: ${preserved}`);
+  }
+  while (pathSegments.length > 0 && (pathSegments[0] === DOT || pathSegments[0] === DOUBLE_DOT)) {
+    const preserved = pathSegments.shift();
+    leadingPreservedSegments.push(preserved);
+    logInternal(`  - preserved relative segment: ${preserved}`);
+  }
+  const numToStrip = Math.min(count, pathSegments.length);
+  const remainingBodySegments = pathSegments.slice(numToStrip);
+  logInternal(
+    `  - stripping ${numToStrip} segments from: ${JSON.stringify(pathSegments)}`
+  );
+  logInternal(
+    `  - remaining body segments: ${JSON.stringify(remainingBodySegments)}`
+  );
+  const pathRoot = parsed.root;
+  const effectiveSegments = [
+    ...leadingPreservedSegments,
+    ...remainingBodySegments
+  ];
+  logInternal(`  - effective segments: ${JSON.stringify(effectiveSegments)}`);
+  let result;
+  if (effectiveSegments.length === 0) {
+    result = normalize(pathRoot || DOT);
+  } else if (pathRoot) {
+    result = join(pathRoot, ...effectiveSegments);
+  } else {
+    result = join(...effectiveSegments);
+  }
+  logInternal(`  - final result: ${result}`);
+  return result;
+}
+async function stripPathSegmentsInDirectory({
+  targetDir,
+  segmentsToStrip,
+  alias = "",
+  extensionsToProcess = EXTENSIONS
+}) {
+  log(`[stripPathSegmentsInDirectory] Processing directory: ${targetDir}`);
+  log(`  - segmentsToStrip: ${segmentsToStrip}, alias: ${alias}`);
+  logInternal(`  - extensions: ${JSON.stringify(extensionsToProcess)}`);
+  try {
+    const entries = await fs.readdir(targetDir, { withFileTypes: true });
+    const results = [];
+    await Promise.all(
+      entries.map(async (entry) => {
+        const fullPath = join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+          if (entry.name === "node_modules" || entry.name.startsWith(".")) {
+            logInternal(`  - skipping directory: ${entry.name}`);
+            return;
+          }
+          logInternal(`  - recursing into directory: ${entry.name}`);
+          const subdirResults = await stripPathSegmentsInDirectory({
+            targetDir: fullPath,
+            segmentsToStrip,
+            alias,
+            extensionsToProcess
+          });
+          results.push(...subdirResults);
+        } else if (extensionsToProcess.includes(extname(entry.name))) {
+          logInternal(`  Processing file: ${entry.name}`);
+          const content = await fs.readFile(fullPath, "utf-8");
+          let updated = content;
+          const changes = [];
+          const matches = Array.from(content.matchAll(IMPORT_REGEX));
+          logInternal(`  - found ${matches.length} import statements`);
+          for (const match of matches) {
+            const originalQuote = match[1];
+            const importPath = match[2];
+            if (!importPath.includes(SLASH)) {
+              logInternal(`  - skipping non-path import: ${importPath}`);
+              continue;
+            }
+            logInternal(`  Processing import: ${importPath}`);
+            const strippedPath = stripPathSegments(
+              importPath,
+              segmentsToStrip,
+              alias
+            );
+            if (importPath === strippedPath) {
+              logInternal("  - no changes needed");
+              continue;
+            }
+            changes.push({ from: importPath, to: strippedPath });
+            logInternal(`  - transformed: ${importPath} \u2192 ${strippedPath}`);
+            const searchStr = `${originalQuote}${importPath}${originalQuote}`;
+            const replaceStr = `${originalQuote}${strippedPath}${originalQuote}`;
+            updated = replaceAllInString(updated, searchStr, replaceStr);
+          }
+          if (content !== updated) {
+            await fs.writeFile(fullPath, updated);
+            logInternal("  \u2713 wrote changes to file");
+            if (changes.length > 0) {
+              results.push({ file: fullPath, changes });
+            }
+          } else {
+            logInternal("  - no changes made to file");
+          }
+        } else {
+          logInternal(`  - skipping non-matching file: ${entry.name}`);
+        }
+      })
+    );
+    if (results.length > 0) {
+      log("[stripPathSegmentsInDirectory] Summary of changes:");
+      for (const { file, changes } of results) {
+        const displayPath = relative(targetDir, file) || basename(file);
+        log(`  in ${displayPath}:`);
+        for (const { from, to } of changes) {
+          log(`    - ${from} \u2192 ${to}`);
+        }
+      }
+    } else {
+      logInternal("  No changes were made in any files");
+    }
+    return results;
+  } catch (error) {
+    log(
+      `error processing directory ${targetDir}: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return [];
+  }
+}
+function attachPathSegments(path2, segments, options = {}) {
+  if (typeof path2 !== "string" || path2.length === 0) return path2;
+  const {
+    position = "after",
+    normalize: shouldNormalize = true,
+    ensureSlash = true,
+    preserveRoot = true,
+    preserveAlias
+  } = options;
+  const segmentsArray = Array.isArray(segments) ? segments : [segments];
+  const validSegments = segmentsArray.filter((s) => s.length > 0);
+  if (validSegments.length === 0) return path2;
+  const basePath = shouldNormalize ? normalizeWindowsPath(path2) : path2;
+  let alias = "";
+  let pathWithoutAlias = basePath;
+  if (preserveAlias && position === "before") {
+    const aliasMatch = new RegExp(`^${preserveAlias.replace("*", ".*")}`).exec(
+      basePath
+    );
+    if (aliasMatch) {
+      alias = aliasMatch[0];
+      pathWithoutAlias = basePath.slice(alias.length);
+    }
+  }
+  const isAbsolute2 = IS_ABSOLUTE_RE.test(pathWithoutAlias);
+  const root = preserveRoot && isAbsolute2 ? SLASH : "";
+  const pathWithoutRoot = isAbsolute2 ? pathWithoutAlias.slice(1) : pathWithoutAlias;
+  const joinedSegments = validSegments.join(SLASH);
+  let result;
+  if (position === "before") {
+    result = ensureSlash ? `${alias}${root}${joinedSegments}${SLASH}${pathWithoutRoot}` : `${alias}${root}${joinedSegments}${pathWithoutRoot}`;
+  } else {
+    result = ensureSlash ? `${alias}${root}${pathWithoutRoot}${SLASH}${joinedSegments}` : `${alias}${root}${pathWithoutRoot}${joinedSegments}`;
+  }
+  return shouldNormalize ? normalize(result) : result;
+}
+async function attachPathSegmentsInDirectory({
+  targetDir,
+  segments,
+  options = {},
+  extensionsToProcess = EXTENSIONS
+}) {
+  try {
+    const entries = await fs.readdir(targetDir, { withFileTypes: true });
+    const results = [];
+    await Promise.all(
+      entries.map(async (entry) => {
+        const fullPath = join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+          if (entry.name === "node_modules" || entry.name.startsWith(".")) {
+            return;
+          }
+          const subdirResults = await attachPathSegmentsInDirectory({
+            targetDir: fullPath,
+            segments,
+            options,
+            extensionsToProcess
+          });
+          results.push(...subdirResults);
+        } else if (extensionsToProcess.includes(extname(entry.name))) {
+          const content = await fs.readFile(fullPath, "utf-8");
+          let updated = content;
+          const changes = [];
+          const matches = Array.from(content.matchAll(IMPORT_REGEX));
+          for (const match of matches) {
+            const originalQuote = match[1];
+            const importPath = match[2];
+            if (!importPath.includes(SLASH)) continue;
+            const modifiedPath = attachPathSegments(
+              importPath,
+              segments,
+              options
+            );
+            if (importPath === modifiedPath) continue;
+            changes.push({ from: importPath, to: modifiedPath });
+            const searchStr = `${originalQuote}${importPath}${originalQuote}`;
+            const replaceStr = `${originalQuote}${modifiedPath}${originalQuote}`;
+            updated = replaceAllInString(updated, searchStr, replaceStr);
+          }
+          if (content !== updated) {
+            await fs.writeFile(fullPath, updated);
+            logInternal(`\u2713 processed: ${fullPath}`);
+            if (changes.length > 0) {
+              results.push({ file: fullPath, changes });
+            }
+          }
+        } else {
+          logInternal(`  - skipping non-matching file: ${entry.name}`);
+        }
+      })
+    );
+    if (results.length > 0) {
+      log("\n[attachPathSegmentsInDirectory] Summary of changes:");
+      for (const { file, changes } of results) {
+        const displayPath = relative(targetDir, file) || basename(file);
+        log(`  in ${displayPath}:`);
+        for (const { from, to } of changes) {
+          log(`    - ${from} \u2192 ${to}`);
+        }
+      }
+    }
     return results;
   } catch (error) {
     log(
@@ -743,6 +1011,10 @@ export {
   copyDir,
   convertStringAliasRelative,
   convertImportsAliasToRelative,
-  convertImportsExt
+  convertImportsExt,
+  stripPathSegments,
+  stripPathSegmentsInDirectory,
+  attachPathSegments,
+  attachPathSegmentsInDirectory
 };
 export default path;

package/package.json

@@ -5,7 +5,7 @@
   "license": "MIT",
   "name": "@reliverse/pathkit",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
     "@eslint/js": "^9.27.0",
@@ -19,7 +19,7 @@
     "eslint": "^9.27.0",
     "eslint-plugin-no-relative-import-paths": "^1.6.1",
     "eslint-plugin-perfectionist": "^4.13.0",
-    "knip": "^5.57.0",
+    "knip": "^5.57.1",
     "magic-string": "^0.30.17",
     "p-map": "^7.0.3",
     "typescript": "^5.8.3",