@gesslar/toolkit 3.22.2 → 3.23.0

package/src/node/lib/DirectoryObject.js

@@ -13,10 +13,30 @@ import FileObject from "./FileObject.js"
 import FS from "./FileSystem.js"
 import Sass from "./Sass.js"
 import Valid from "./Valid.js"
-import VFileObject from "./VFileObject.js"
 
 /**
- * DirectoryObject encapsulates metadata and operations for a directory,
+ * @typedef {object} GeneratorType
+ * @property {function(): {value: DirectoryObject, done: boolean}} next
+ * @property {function(): GeneratorType} [Symbol.iterator]
+ */
+
+/**
+ * @typedef {object} DirectoryMeta
+ *
+ * @property {boolean} isDirectory - Always true for directories
+ * @property {string|null} extension - The directory extension (if any)
+ * @property {string|null} module - The directory name without extension
+ * @property {string|null} name - The directory name
+ * @property {DirectoryObject|undefined} parent - The parent DirectoryObject
+ * @property {string|null} parentPath - The parent directory path
+ * @property {string|null} path - The absolute directory path
+ * @property {string|null} sep - Path separator
+ * @property {string|null} supplied - User-supplied path
+ * @property {Array<string>|null} trail - Path segments
+ * @property {URL|null} url - The directory URL
+ */
+
+/** * DirectoryObject encapsulates metadata and operations for a directory,
  * providing immutable path resolution, existence checks, and content enumeration.
  *
  * Features:
@@ -37,7 +57,6 @@ import VFileObject from "./VFileObject.js"
  * @property {boolean} isDirectory - Always true
  * @property {DirectoryObject|null} parent - The parent directory (null if root)
  * @property {Promise<boolean>} exists - Whether the directory exists (async getter)
- * @property {Generator<DirectoryObject>} walkUp - Generator yielding parent directories up to root
  *
  * @example
  * // Basic usage
@@ -63,21 +82,15 @@ import VFileObject from "./VFileObject.js"
  */
 export default class DirectoryObject extends FS {
   /**
-   * @type {object}
-   * @private
-   * @property {string|null} supplied - User-supplied path
-   * @property {string|null} path - The absolute file path
-   * @property {URL|null} url - The file URL
-   * @property {string|null} name - The file name
-   * @property {string|null} module - The file name without extension
-   * @property {string|null} extension - The file extension
-   * @property {boolean} isDirectory - Always true
+   * @type {DirectoryMeta}
    */
   #meta = Object.seal({
     isDirectory: true,
+    extension: null,
+    module: null,
     name: null,
     parent: undefined,
-    parentPath: undefined,
+    parentPath: null,
     path: null,
     sep: null,
     supplied: null,
@@ -93,7 +106,6 @@ export default class DirectoryObject extends FS {
    * Constructs a DirectoryObject instance.
    *
    * @param {string?} [supplied="."] - The directory path (defaults to current directory)
-   * @param {DirectoryObject?} [parent] - Optional parent directory (ignored by DirectoryObject, used by subclasses)
    */
   constructor(supplied) {
     super()
@@ -104,17 +116,19 @@ export default class DirectoryObject extends FS {
 
     const normalizedDir = FS.fixSlashes(fixedDir)
     const resolved = FS.resolvePath(DirectoryObject.cwd, normalizedDir)
-    const {dir, name, root} = FS.pathParts(resolved)
+    const {dir, ext, name, root} = FS.pathParts(resolved)
     const url = new URL(FS.pathToUrl(resolved))
     const trail = resolved.split(path.sep)
 
-    this.#meta.name = name
+    this.#meta.extension = ext
+    this.#meta.module = name
+    this.#meta.name = name + ext
     this.#meta.parentPath = dir == root
       ? null
       : dir
     this.#meta.path = resolved
     this.#meta.sep = path.sep
-    this.#meta.supplied = supplied
+    this.#meta.supplied = supplied ?? null
     this.#meta.trail = trail
     this.#meta.url = url
 
@@ -141,9 +155,7 @@ export default class DirectoryObject extends FS {
    * @returns {string} string representation of the DirectoryObject
    */
   toString() {
-    return this.isVirtual
-      ?`[${this.constructor.name}: ${this.path} → ${this.real.path}]`
-      :`[${this.constructor.name}: ${this.path}]`
+    return `[${this.constructor.name}: ${this.path}]`
   }
 
   /**
@@ -192,7 +204,7 @@ export default class DirectoryObject extends FS {
   }
 
   /**
-   * Returns the directory name without the path or extension.
+   * Returns the directory name without extension.
    *
    * @returns {string} The directory name without extension
    */
@@ -201,9 +213,9 @@ export default class DirectoryObject extends FS {
   }
 
   /**
-   * Returns the directory extension. Will be an empty string if unavailable.
+   * Returns the directory extension (if any).
    *
-   * @returns {string} The directory extension
+   * @returns {string} The directory extension including the dot (e.g., '.git')
    */
   get extension() {
     return this.#meta.extension
@@ -274,7 +286,7 @@ export default class DirectoryObject extends FS {
    * @returns {Promise<boolean>} Whether the directory exists
    */
   async #directoryExists() {
-    const path = this.real?.path ?? this.path
+    const path = this.path
 
     try {
       (await opendir(path)).close()
@@ -289,11 +301,10 @@ export default class DirectoryObject extends FS {
    * Lists the contents of a directory, optionally filtered by a glob pattern.
    *
    * Returns FileObject and DirectoryObject instances for regular directories.
-   * Returns VFileObject and VDirectoryObject instances when called on virtual directories.
    *
    * @async
    * @param {string} [pat=""] - Optional glob pattern to filter results (e.g., "*.txt", "test-*")
-   * @returns {Promise<{files: Array<FileObject|VFileObject>, directories: Array<DirectoryObject|VDirectoryObject>}>} Object containing arrays of files and directories
+   * @returns {Promise<{files: Array<FileObject>, directories: Array<DirectoryObject>}>} Object containing arrays of files and directories
    * @example
    * const dir = new DirectoryObject("./src")
    * const {files, directories} = await dir.read()
@@ -306,9 +317,7 @@ export default class DirectoryObject extends FS {
    */
   async read(pat="") {
     const withFileTypes = true
-    const url = this.isVirtual
-      ? this.real?.url
-      : this.url
+    const url = this.url
 
     Valid.type(url, "URL")
     // const href = url.href
@@ -317,7 +326,7 @@ export default class DirectoryObject extends FS {
       ? await readdir(url, {withFileTypes})
       : await Array.fromAsync(
         glob(pat, {
-          cwd: this.isVirtual ? this.real?.path : this.path,
+          cwd: this.path,
           withFileTypes,
         })
       )
@@ -342,11 +351,10 @@ export default class DirectoryObject extends FS {
    * Unlike read(), this method searches recursively through subdirectories.
    *
    * Returns FileObject and DirectoryObject instances for regular directories.
-   * Returns VFileObject and VDirectoryObject instances when called on virtual directories.
    *
    * @async
    * @param {string} [pat=""] - Glob pattern to filter results
-   * @returns {Promise<{files: Array<FileObject|VFileObject>, directories: Array<DirectoryObject|VDirectoryObject>}>} Object containing arrays of matching files and directories
+   * @returns {Promise<{files: Array<FileObject|FileObject>, directories: Array<DirectoryObject>}>} Object containing arrays of matching files and directories
    * @throws {Sass} If an entry is neither a file nor directory
    * @example
    * const dir = new DirectoryObject("./src")
@@ -361,31 +369,26 @@ export default class DirectoryObject extends FS {
     const withFileTypes = true
     const found = await Array.fromAsync(
       glob(pat, {
-        cwd: this.isVirtual ? this.real?.path : this.path,
+        cwd: this.path,
         withFileTypes,
       })
     )
 
     const files = [], directories = []
-    const virtual = this.isVirtual
 
     for(const e of found) {
       if(e.isFile()) {
         const {name, parentPath} = e
         const resolved = FS.resolvePath(parentPath, name)
 
-        const file = virtual
-          ? new VFileObject(path.relative(this.real.path, resolved), this)
-          : new FileObject(resolved, this)
+        const file = new FileObject(resolved, this)
 
         files.push(file)
       } else if(e.isDirectory()) {
         const {name, parentPath} = e
         const resolved = FS.resolvePath(parentPath, name)
-        const relativePath = virtual
-          ? path.relative(this.real.path, resolved)
-          : resolved
-        const directory = new this.constructor(relativePath, this)
+        const relativePath = resolved
+        const directory = new this.constructor(relativePath)
 
         directories.push(directory)
       } else {
@@ -413,26 +416,26 @@ export default class DirectoryObject extends FS {
     if(await this.exists)
       return
 
-    const path = this.real?.path ?? this.path
+    const path = this.path
 
     try {
       await mkdir(path, options)
-    } catch(e) {
-      if(e.code === "EEXIST") {
+    } catch(error) {
+      if(error.code === "EEXIST") {
         // Directory already exists, ignore
         return
       }
 
-      throw Sass.new(`Unable to create directory '${path}': ${e.message}`)
+      throw Sass.new(`Unable to create directory '${path}': ${error.message}`)
     }
   }
 
   /**
    * Private generator that walks up the directory tree.
    *
-   * @private
    * @generator
    * @yields {DirectoryObject} Parent directory objects from current to root
+   * @returns {GeneratorType}
    */
   *#walkUp() {
     const {root, base, dir} = FS.pathParts(this.path)
@@ -445,7 +448,7 @@ export default class DirectoryObject extends FS {
       return yield this
 
     do
-      yield new this.constructor(path.join(root, ...trail), this.cap)
+      yield new this.constructor(path.join(root, ...trail))
 
     while(trail.pop())
   }
@@ -486,7 +489,7 @@ export default class DirectoryObject extends FS {
    * await dir.delete() // Only works if directory is empty
    */
   async delete() {
-    const dirPath = this.real?.path ?? this.path
+    const dirPath = this.path
 
     if(!dirPath)
       throw Sass.new("This object does not represent a valid resource.")
@@ -504,9 +507,7 @@ export default class DirectoryObject extends FS {
    * @returns {Promise<boolean>} True if the file exists, false otherwise
    */
   async hasFile(filename) {
-    const file = this.isVirtual
-      ? new VFileObject(filename, this)
-      : new FileObject(filename, this)
+    const file = new FileObject(filename, this)
 
     return await file.exists
   }
@@ -518,197 +519,84 @@ export default class DirectoryObject extends FS {
    * @returns {Promise<boolean>} True if the directory exists, false otherwise
    */
   async hasDirectory(dirname) {
-    const dir = FS.resolvePath(this.real?.path ?? this.path, dirname)
+    const dir = FS.resolvePath(this.path, dirname)
     const directory = new DirectoryObject(dir)
 
     return await directory.exists
   }
 
-  #isLocal = candidate => {
-    Valid.type(candidate, "String", {allowEmpty: false})
-
-    const {dir: candidateDir} = FS.pathParts(candidate)
-
-    return candidateDir === this.path
-  }
-
   /**
-   * Resolves an absolute virtual path from cap root and validates it stays within cap boundary.
+   * Creates a new DirectoryObject by extending this directory's path.
    *
-   * @private
-   * @param {string} absolutePath - Absolute virtual path starting with separator
-   * @returns {string} Normalized resolved virtual path
-   * @throws {Sass} If path would be out of bounds
-   */
-  #resolveAndValidateFromCap(absolutePath) {
-    const relativeFromCap = Data.chopLeft(absolutePath, this.sep)
-    const resolvedVirtualPath = FS.resolvePath(this.cap.path, relativeFromCap)
-    const normalized = FS.fixSlashes(resolvedVirtualPath)
-
-    // Validate cap boundary using real paths
-    const relativeFromCapForReal = normalized.startsWith(this.sep)
-      ? Data.chopLeft(normalized, this.sep)
-      : normalized
-    const resolvedRealPath = FS.resolvePath(
-      this.cap.real.path,
-      relativeFromCapForReal
-    )
-
-    if(!FS.pathContains(this.cap.real.path, resolvedRealPath)) {
-      throw Sass.new(`${normalized} would be out of bounds (cap: ${this.cap.path}).`)
-    }
-
-    return normalized
-  }
-
-  /**
-   * Gets the parent directory object for a given virtual path.
-   * Returns the cap if the path is at the cap root.
+   * Uses overlapping path segment detection to intelligently combine paths.
+   * Preserves the temporary flag from the current directory.
    *
-   * @private
-   * @param {string} virtualPath - The virtual path
-   * @returns {VDirectoryObject} The parent directory object
+   * @param {string} newPath - The path to append to this directory's path.
+   * @returns {DirectoryObject} A new DirectoryObject with the extended path.
+   * @example
+   * const dir = new DirectoryObject("/projects/git/toolkit")
+   * const subDir = dir.addDirectory("src/lib")
+   * console.log(subDir.path) // "/projects/git/toolkit/src/lib"
    */
-  #getParentDirectoryForPath(virtualPath) {
-    const {dir} = FS.pathParts(virtualPath)
+  getDirectory(newPath) {
+    Valid.type(newPath, "String", {allowEmpty: false})
 
-    // If at cap root, return cap
-    if(dir === this.cap.path || dir === this.sep) {
-      return this.cap
+    // Reject absolute paths
+    if(path.isAbsolute(newPath)) {
+      throw Sass.new(`Absolute paths not allowed: ${newPath}`)
     }
 
-    // Create parent directory object (recursive - it will get its own parent)
-    return new this.constructor(dir, this.cap)
-  }
-
-  /**
-   * Validates that a resolved virtual path stays within the cap boundary.
-   *
-   * @private
-   * @param {string} virtualPath - Resolved virtual path
-   * @returns {string} Normalized virtual path
-   * @throws {Sass} If path would be out of bounds
-   */
-  #validateCapBoundary(virtualPath) {
-    const normalized = FS.fixSlashes(virtualPath)
-    const relativeFromCap = normalized.startsWith(this.sep)
-      ? Data.chopLeft(normalized, this.sep)
-      : normalized
-    const resolvedRealPath = FS.resolvePath(
-      this.cap.real.path,
-      relativeFromCap
-    )
+    // Reject parent directory traversal
+    if(newPath.includes("..")) {
+      throw Sass.new(`Path traversal not allowed: ${newPath} contains '..'`)
+    }
 
-    // Check if resolved path is within cap (handles case where path equals cap root)
-    const capRealPath = this.cap.real.path
-    const isWithinCap = resolvedRealPath === capRealPath
-      || FS.pathContains(capRealPath, resolvedRealPath)
+    const thisPath = this.path
+    const merged = FS.mergeOverlappingPaths(thisPath, newPath)
+    const resolved = FS.resolvePath(thisPath, merged)
 
-    if(!isWithinCap) {
-      throw Sass.new(`${normalized} would be out of bounds (cap: ${this.cap.path}).`)
+    // Final safety check
+    if(!FS.pathContains(thisPath, resolved)) {
+      throw Sass.new(`Path resolves outside directory: ${newPath}`)
     }
 
-    return normalized
+    return new this.constructor(resolved)
   }
 
   /**
-   * Creates a new DirectoryObject by extending this directory's path.
+   * Creates a new FileObject by extending this directory's path.
    *
-   * Uses intelligent path merging that detects overlapping segments to avoid
-   * duplication (e.g., "/projects/toolkit" + "toolkit/src" = "/projects/toolkit/src").
-   * The temporary flag is preserved from the parent directory.
+   * Uses overlapping path segment detection to intelligently combine paths.
    *
-   * @param {string} dir - The subdirectory path to append (can be nested like "src/lib")
-   * @returns {DirectoryObject} A new DirectoryObject instance with the combined path
-   * @throws {Sass} If newPath is not a string
+   * @param {string} filename - The filename to append to this directory's path.
+   * @returns {FileObject} A new FileObject with the extended path.
    * @example
    * const dir = new DirectoryObject("/projects/git/toolkit")
-   * const subDir = dir.getDirectory("src/lib")
-   * console.log(subDir.path) // "/projects/git/toolkit/src/lib"
-   *
-   * @example
-   * // Handles overlapping segments intelligently
-   * const dir = new DirectoryObject("/projects/toolkit")
-   * const subDir = dir.getDirectory("toolkit/src")
-   * console.log(subDir.path) // "/projects/toolkit/src" (not /projects/toolkit/toolkit/src)
+   * const file = dir.addFile("package.json")
+   * console.log(file.path) // "/projects/git/toolkit/package.json"
    */
-  getDirectory(dir) {
-    Valid.type(dir, "String", {allowEmpty: false})
-
-    // Validate boundaries before passing raw input to constructor
-    if(this.isVirtual) {
-      // VDO: validate cap boundary, then pass raw input to constructor
-      if(dir.startsWith(this.sep)) {
-      // Absolute path: validate from cap root
-        this.#resolveAndValidateFromCap(dir)
-      } else {
-      // Relative path: resolve and validate stays within cap
-        const newPath = FS.resolvePath(this.path, dir)
-        this.#validateCapBoundary(newPath)
-      }
+  getFile(filename) {
+    Valid.type(filename, "String", {allowEmpty: false})
 
-      // Pass raw input; constructor handles resolution and parent determination
-      return new this.constructor(dir, this)
+    // Reject absolute paths
+    if(path.isAbsolute(filename)) {
+      throw Sass.new(`Absolute paths not allowed: ${filename}`)
     }
 
-    // Regular DO: validate local-only constraint
-    const newPath = FS.resolvePath(this.path, dir)
-    Valid.assert(this.#isLocal(newPath), `${newPath} would be out of bounds.`)
+    // Reject parent directory traversal
+    if(filename.includes("..")) {
+      throw Sass.new(`Path traversal not allowed: ${filename} contains '..'`)
+    }
 
-    // Pass raw input; constructor will resolve it to cwd
-    return new this.constructor(newPath)
-  }
+    const thisPath = this.path
+    const merged = FS.mergeOverlappingPaths(thisPath, filename)
+    const resolved = FS.resolvePath(thisPath, merged)
 
-  /**
-   * Creates a new FileObject by extending this directory's path.
-   *
-   * Uses intelligent path merging that detects overlapping segments to avoid
-   * duplication. The resulting FileObject can be used for reading, writing,
-   * and other file operations.
-   *
-   * For regular DirectoryObject: only allows direct children (local only).
-   * For VDirectoryObject: supports absolute virtual paths (starting with "/")
-   * which resolve from cap root, and relative paths from current directory.
-   *
-   * When called on a VDirectoryObject, returns a VFileObject to maintain
-   * virtual path semantics.
-   *
-   * @param {string} file - The filename to append
-   * @returns {FileObject|VFileObject} A new FileObject (or VFileObject if virtual)
-   * @throws {Sass} If filename is not a string
-   * @throws {Sass} If path would be out of bounds
-   * @example
-   * const dir = new DirectoryObject("/projects/git/toolkit")
-   * const file = dir.getFile("package.json")
-   * console.log(file.path) // "/projects/git/toolkit/package.json"
-   *
-   * @example
-   * // VDirectoryObject with absolute virtual path
-   * const vdo = new TempDirectoryObject("myapp")
-   * const file = vdo.getFile("/config/settings.json")
-   * // Virtual path: /config/settings.json, Real path: {vdo.real.path}/config/settings.json
-   */
-  getFile(file) {
-    Valid.type(file, "String", {allowEmpty: false})
-
-    // Validate boundaries - check what the resolved path would be
-    if(!this.isVirtual) {
-      // Regular DO: validate local-only constraint
-      const resolvedPath = FS.resolvePath(this.path, file)
-      Valid.assert(this.#isLocal(resolvedPath), `${resolvedPath} would be out of bounds.`)
-    } else {
-      // VDO: validate cap boundary
-      if(file.startsWith(this.sep)) {
-        this.#resolveAndValidateFromCap(file)
-      } else {
-        const resolvedPath = FS.resolvePath(this.path, file)
-        this.#validateCapBoundary(resolvedPath)
-      }
+    // Final safety check
+    if(!FS.pathContains(thisPath, resolved)) {
+      throw Sass.new(`Path resolves outside directory: ${filename}`)
     }
 
-    // Pass raw input to constructor - it handles resolution and parent determination
-    return this.isVirtual
-      ? new VFileObject(file, this)
-      : new FileObject(file, this)
+    return new FileObject(resolved)
   }
 }