Breaking: Improve symlink/junction behaviour

Author: erikkemperman

README.md

@@ -211,10 +211,11 @@ Default: `false`
 ##### `options.useJunctions`
 
 When creating a symlink, whether or not a directory symlink should be created as a `junction`.
+This option is only relevant on Windows and ignored elsewhere.
 
 Type: `Boolean`
 
-Default: `true` on Windows, `false` on all other platforms
+Default: `true`
 
 ### `symlink(folder[, options])`
 
@@ -239,14 +240,6 @@ Type: `String`
 
 Default: `process.cwd()`
 
-##### `options.mode`
-
-The mode the symlinks should be created with.
-
-Type: `Number`
-
-Default: The `mode` of the input file (`file.stat.mode`) if any, or the process mode if the input file has no `mode` property.
-
 ##### `options.dirMode`
 
 The mode the directory should be created with.
@@ -274,10 +267,11 @@ Default: `false`
 ##### `options.useJunctions`
 
 Whether or not a directory symlink should be created as a `junction`.
+This option is only relevant on Windows and ignored elsewhere.
 
 Type: `Boolean`
 
-Default: `true` on Windows, `false` on all other platforms
+Default: `true`
 
 [glob-stream]: https://github.com/gulpjs/glob-stream
 [node-glob]: https://github.com/isaacs/node-glob

lib/dest/options.js

@@ -1,9 +1,5 @@
 'use strict';
 
-var os = require('os');
-
-var isWindows = (os.platform() === 'win32');
-
 var config = {
   cwd: {
     type: 'string',
@@ -34,14 +30,15 @@ var config = {
     default: false,
   },
   // Symlink options
-  useJunctions: {
-    type: 'boolean',
-    default: isWindows,
-  },
   relativeSymlinks: {
     type: 'boolean',
     default: false,
   },
+  // This option is ignored on non-Windows platforms
+  useJunctions: {
+    type: 'boolean',
+    default: true,
+  },
 };
 
 module.exports = config;

lib/dest/prepare.js

@@ -11,22 +11,23 @@ function prepareWrite(folderResolver, optResolver) {
   }
 
   function normalize(file, enc, cb) {
-    var mode = optResolver.resolve('mode', file);
-    var cwd = path.resolve(optResolver.resolve('cwd', file));
-
     var outFolderPath = folderResolver.resolve('outFolder', file);
     if (!outFolderPath) {
       return cb(new Error('Invalid output folder'));
     }
+    var cwd = path.resolve(optResolver.resolve('cwd', file));
     var basePath = path.resolve(cwd, outFolderPath);
     var writePath = path.resolve(basePath, file.relative);
 
     // Wire up new properties
-    file.stat = (file.stat || new fs.Stats());
-    file.stat.mode = mode;
     file.cwd = cwd;
     file.base = basePath;
     file.path = writePath;
+    if (!file.isSymbolic()) {
+      var mode = optResolver.resolve('mode', file);
+      file.stat = (file.stat || new fs.Stats());
+      file.stat.mode = mode;
+    }
 
     cb(null, file);
   }

lib/dest/write-contents/write-symbolic-link.js

@@ -1,42 +1,74 @@
 'use strict';
 
+var os = require('os');
 var path = require('path');
 
 var fo = require('../../file-operations');
 
+var isWindows = (os.platform() === 'win32');
+
 function writeSymbolicLink(file, optResolver, onWritten) {
-  var isDirectory = file.isDirectory();
-
-  // This option provides a way to create a Junction instead of a
-  // Directory symlink on Windows. This comes with the following caveats:
-  // * NTFS Junctions cannot be relative.
-  // * NTFS Junctions MUST be directories.
-  // * NTFS Junctions must be on the same file system.
-  // * Most products CANNOT detect a directory is a Junction:
-  //    This has the side effect of possibly having a whole directory
-  //    deleted when a product is deleting the Junction directory.
-  //    For example, JetBrains product lines will delete the entire
-  //    contents of the TARGET directory because the product does not
-  //    realize it's a symlink as the JVM and Node return false for isSymlink.
-  var useJunctions = optResolver.resolve('useJunctions', file);
-
-  var symDirType =  useJunctions ? 'junction' : 'dir';
-  var symType = isDirectory ? symDirType : 'file';
+  if (!file.symlink) {
+    return onWritten(new Error('Missing symlink property on symbolic vinyl'));
+  }
+
   var isRelative = optResolver.resolve('relativeSymlinks', file);
+  var flag = optResolver.resolve('flag', file);
 
-  // This is done after prepare() to use the adjusted file.base property
-  if (isRelative && symType !== 'junction') {
-    file.symlink = path.relative(file.base, file.symlink);
+  if (!isWindows) {
+    // On non-Windows, just use 'file'
+    return createLinkWithType('file');
   }
 
-  var flag = optResolver.resolve('flag', file);
+  fo.reflectStat(file.symlink, file, onReflect);
+
+  function onReflect(statErr) {
+    if (statErr && statErr.code !== 'ENOENT') {
+      return onWritten(statErr);
+    }
+
+    // This option provides a way to create a Junction instead of a
+    // Directory symlink on Windows. This comes with the following caveats:
+    // * NTFS Junctions cannot be relative.
+    // * NTFS Junctions MUST be directories.
+    // * NTFS Junctions must be on the same file system.
+    // * Most products CANNOT detect a directory is a Junction:
+    //    This has the side effect of possibly having a whole directory
+    //    deleted when a product is deleting the Junction directory.
+    //    For example, JetBrains product lines will delete the entire contents
+    //    of the TARGET directory because the product does not realize it's
+    //    a symlink as the JVM and Node return false for isSymlink.
 
-  var opts = {
-    flag: flag,
-    type: symType,
-  };
+    // This function is Windows only, so we don't need to check again
+    var useJunctions = optResolver.resolve('useJunctions', file);
 
-  fo.symlink(file.symlink, file.path, opts, onWritten);
+    var dirType = useJunctions ? 'junction' : 'dir';
+    // Dangling links are always 'file'
+    var type = !statErr && file.isDirectory() ? dirType : 'file';
+
+    createLinkWithType(type);
+  }
+
+  function createLinkWithType(type) {
+    // This is done after prepare() to use the adjusted file.base property
+    if (isRelative && type !== 'junction') {
+      file.symlink = path.relative(file.base, file.symlink);
+    }
+
+    var opts = {
+      flag: flag,
+      type: type,
+    };
+    fo.symlink(file.symlink, file.path, opts, onSymlink);
+
+    function onSymlink(symlinkErr) {
+      if (symlinkErr) {
+        return onWritten(symlinkErr);
+      }
+
+      fo.reflectLinkStat(file.path, file, onWritten);
+    }
+  }
 }
 
 module.exports = writeSymbolicLink;

lib/file-operations.js

@@ -155,6 +155,34 @@ function isOwner(fsStat) {
   return true;
 }
 
+function reflectStat(path, file, callback) {
+  // Set file.stat to the reflect current state on disk
+  fs.stat(path, onStat);
+
+  function onStat(statErr, stat) {
+    if (statErr) {
+      return callback(statErr);
+    }
+
+    file.stat = stat;
+    callback();
+  }
+}
+
+function reflectLinkStat(path, file, callback) {
+  // Set file.stat to the reflect current state on disk
+  fs.lstat(path, onLstat);
+
+  function onLstat(lstatErr, stat) {
+    if (lstatErr) {
+      return callback(lstatErr);
+    }
+
+    file.stat = stat;
+    callback();
+  }
+}
+
 function updateMetadata(fd, file, callback) {
 
   fs.fstat(fd, onStat);
@@ -413,6 +441,8 @@ module.exports = {
   getTimesDiff: getTimesDiff,
   getOwnerDiff: getOwnerDiff,
   isOwner: isOwner,
+  reflectStat: reflectStat,
+  reflectLinkStat: reflectLinkStat,
   updateMetadata: updateMetadata,
   symlink: symlink,
   writeFile: writeFile,

lib/src/resolve-symlinks.js

@@ -1,23 +1,21 @@
 'use strict';
 
 var through = require('through2');
-var fs = require('graceful-fs');
+var fo = require('../file-operations');
 
 function resolveSymlinks(optResolver) {
 
   // A stat property is exposed on file objects as a (wanted) side effect
   function resolveFile(file, enc, callback) {
 
-    fs.lstat(file.path, onStat);
+    fo.reflectLinkStat(file.path, file, onReflect);
 
-    function onStat(statErr, stat) {
+    function onReflect(statErr) {
       if (statErr) {
         return callback(statErr);
       }
 
-      file.stat = stat;
-
-      if (!stat.isSymbolicLink()) {
+      if (!file.stat.isSymbolicLink()) {
         return callback(null, file);
       }
 
@@ -27,8 +25,8 @@ function resolveSymlinks(optResolver) {
         return callback(null, file);
       }
 
-      // Recurse to get real file stat
-      fs.stat(file.path, onStat);
+      // Get target's stats
+      fo.reflectStat(file.path, file, onReflect);
     }
   }
 

lib/symlink/link-file.js

@@ -1,52 +1,81 @@
 'use strict';
 
+var os = require('os');
 var path = require('path');
 
 var through = require('through2');
 
 var fo = require('../file-operations');
 
+var isWindows = (os.platform() === 'win32');
+
 function linkStream(optResolver) {
 
   function linkFile(file, enc, callback) {
-    var isDirectory = file.isDirectory();
-
-    // This option provides a way to create a Junction instead of a
-    // Directory symlink on Windows. This comes with the following caveats:
-    // * NTFS Junctions cannot be relative.
-    // * NTFS Junctions MUST be directories.
-    // * NTFS Junctions must be on the same file system.
-    // * Most products CANNOT detect a directory is a Junction:
-    //    This has the side effect of possibly having a whole directory
-    //    deleted when a product is deleting the Junction directory.
-    //    For example, JetBrains product lines will delete the entire
-    //    contents of the TARGET directory because the product does not
-    //    realize it's a symlink as the JVM and Node return false for isSymlink.
-    var useJunctions = optResolver.resolve('useJunctions', file);
-
-    var symDirType =  useJunctions ? 'junction' : 'dir';
-    var symType = isDirectory ? symDirType : 'file';
     var isRelative = optResolver.resolve('relativeSymlinks', file);
+    var flag = optResolver.resolve('flag', file);
 
-    // This is done after prepare() to use the adjusted file.base property
-    if (isRelative && symType !== 'junction') {
-      file.symlink = path.relative(file.base, file.symlink);
+    if (!isWindows) {
+      // On non-Windows, just use 'file'
+      return createLinkWithType('file');
     }
 
-    var flag = optResolver.resolve('flag', file);
+    fo.reflectStat(file.symlink, file, onReflectTarget);
+
+    function onReflectTarget(statErr) {
+      if (statErr && statErr.code !== 'ENOENT') {
+        return onWritten(statErr);
+      }
+      // If target doesn't exist, the vinyl will still carry the target stats.
+      // Let's use those to determine which kind of dangling link to create.
+
+      // This option provides a way to create a Junction instead of a
+      // Directory symlink on Windows. This comes with the following caveats:
+      // * NTFS Junctions cannot be relative.
+      // * NTFS Junctions MUST be directories.
+      // * NTFS Junctions must be on the same file system.
+      // * Most products CANNOT detect a directory is a Junction:
+      //    This has the side effect of possibly having a whole directory
+      //    deleted when a product is deleting the Junction directory.
+      //    For example, JetBrains product lines will delete the entire contents
+      //    of the TARGET directory because the product does not realize it's
+      //    a symlink as the JVM and Node return false for isSymlink.
+
+      // This function is Windows only, so we don't need to check again
+      var useJunctions = optResolver.resolve('useJunctions', file);
+
+      var dirType = useJunctions ? 'junction' : 'dir';
+      var type = !statErr && file.isDirectory() ? dirType : 'file';
 
-    var opts = {
-      flag: flag,
-      type: symType,
-    };
+      createLinkWithType(type);
+    }
+
+    function createLinkWithType(type) {
+      // This is done after prepare() to use the adjusted file.base property
+      if (isRelative && type !== 'junction') {
+        file.symlink = path.relative(file.base, file.symlink);
+      }
 
-    fo.symlink(file.symlink, file.path, opts, onSymlink);
+      var opts = {
+        flag: flag,
+        type: type,
+      };
+      fo.symlink(file.symlink, file.path, opts, onSymlink);
+    }
 
     function onSymlink(symlinkErr) {
       if (symlinkErr) {
         return callback(symlinkErr);
       }
 
+      fo.reflectLinkStat(file.path, file, onReflectLink);
+    }
+
+    function onReflectLink(reflectErr) {
+      if (reflectErr) {
+        return callback(reflectErr);
+      }
+
       callback(null, file);
     }
   }