refactor(jsdoc): remove jsdoc/fs

BREAKING CHANGE: Removed `jsdoc/fs`. Use `@jsdoc/core.util.fs` and other packages instead.

packages/jsdoc/cli.js

@@ -215,7 +215,7 @@ module.exports = (() => {
     };
 
     function readPackageJson(filepath) {
-        const fs = require('jsdoc/fs');
+        const fs = require('fs');
 
         try {
             return stripJsonComments( fs.readFileSync(filepath, 'utf8') );

packages/jsdoc/lib/jsdoc/fs.js

@@ -1,110 +0,0 @@
-/**
- * Extended version of the standard `fs` module.
- * @module jsdoc/fs
- */
-const fs = require('fs');
-const path = require('path');
-const mkdirp = require('mkdirp');
-
-const ls = exports.ls = (dir, recurse, _allFiles, _path) => {
-    let file;
-    let files;
-    let isFile;
-
-    // first pass
-    if (_path === undefined) {
-        _allFiles = [];
-        _path = [dir];
-    }
-
-    if (!_path.length) {
-        return _allFiles;
-    }
-
-    if (recurse === undefined) {
-        recurse = 1;
-    }
-
-    try {
-        isFile = fs.statSync(dir).isFile();
-    }
-    catch (e) {
-        isFile = false;
-    }
-    if (isFile) {
-        files = [dir];
-    }
-    else {
-        files = fs.readdirSync(dir);
-    }
-
-    for (let i = 0, l = files.length; i < l; i++) {
-        file = String(files[i]);
-
-        // skip dot files
-        if (file.match(/^\.[^./\\]/)) {
-            continue;
-        }
-
-        if ( fs.statSync(path.join(_path.join('/'), file)).isDirectory() ) {
-            // it's a directory
-            _path.push(file);
-
-            if (_path.length - 1 < recurse) {
-                ls(_path.join('/'), recurse, _allFiles, _path);
-            }
-            _path.pop();
-        }
-        else {
-            // it's a file
-            _allFiles.push( path.normalize(path.join(_path.join('/'), file)) );
-        }
-    }
-
-    return _allFiles;
-};
-
-exports.toDir = _path => {
-    let isDirectory;
-
-    _path = path.normalize(_path);
-
-    try {
-        isDirectory = fs.statSync(_path).isDirectory();
-    }
-    catch (e) {
-        isDirectory = false;
-    }
-
-    if (isDirectory) {
-        return _path;
-    } else {
-        return path.dirname(_path);
-    }
-};
-
-exports.mkPath = _path => {
-    if ( Array.isArray(_path) ) {
-        _path = _path.join('');
-    }
-
-    mkdirp.sync(_path);
-};
-
-exports.copyFileSync = (inFile, outDir, fileName) => {
-    outDir = outDir || '';
-    fileName = fileName || path.basename(inFile);
-
-    fs.copyFileSync(inFile, path.join(outDir, fileName));
-};
-
-const alwaysOverride = {
-    'copyFileSync': true
-};
-
-Object.keys(fs).forEach(member => {
-    if (!alwaysOverride[member]) {
-        exports[member] = fs[member];
-    }
-});
-

packages/jsdoc/lib/jsdoc/readme.js

@@ -3,7 +3,7 @@
  * @module jsdoc/readme
  */
 const env = require('jsdoc/env');
-const fs = require('jsdoc/fs');
+const fs = require('fs');
 const markdown = require('jsdoc/util/markdown');
 
 /**

packages/jsdoc/lib/jsdoc/src/parser.js

@@ -5,7 +5,7 @@ const _ = require('lodash');
 const astNode = require('jsdoc/src/astnode');
 const { conf } = require('jsdoc/env');
 const { EventEmitter } = require('events');
-const fs = require('jsdoc/fs');
+const fs = require('fs');
 const logger = require('jsdoc/util/logger');
 const name = require('jsdoc/name');
 const { Syntax } = require('jsdoc/src/syntax');

packages/jsdoc/lib/jsdoc/src/scanner.js

@@ -1,11 +1,11 @@
 /**
  * @module jsdoc/src/scanner
- * @requires module:jsdoc/fs
  */
 const { EventEmitter } = require('events');
-const fs = require('jsdoc/fs');
 const logger = require('jsdoc/util/logger');
+const { lsSync } = require('@jsdoc/core').util.fs;
 const path = require('path');
+const { statSync } = require('fs');
 
 /**
  * @extends module:events.EventEmitter
@@ -32,7 +32,7 @@ class Scanner extends EventEmitter {
             const filepath = path.resolve(process.cwd(), decodeURIComponent($));
 
             try {
-                currentFile = fs.statSync(filepath);
+                currentFile = statSync(filepath);
             }
             catch (e) {
                 logger.error('Unable to find the source file or directory %s', filepath);
@@ -44,7 +44,7 @@ class Scanner extends EventEmitter {
                 filePaths.push(filepath);
             }
             else {
-                filePaths = filePaths.concat( fs.ls(filepath, depth) );
+                filePaths = filePaths.concat(lsSync(filepath, depth));
             }
         });
 

packages/jsdoc/lib/jsdoc/template.js

@@ -3,7 +3,7 @@
  * @module jsdoc/template
  */
 const _ = require('lodash');
-const fs = require('jsdoc/fs');
+const fs = require('fs');
 const path = require('path');
 
 /**

packages/jsdoc/lib/jsdoc/tutorial/resolver.js

@@ -2,8 +2,9 @@
  * @module jsdoc/tutorial/resolver
  */
 const env = require('jsdoc/env');
-const fs = require('jsdoc/fs');
+const fs = require('fs');
 const logger = require('jsdoc/util/logger');
+const { lsSync } = require('@jsdoc/core').util.fs;
 const path = require('path');
 const stripBom = require('strip-bom');
 const tutorial = require('jsdoc/tutorial');
@@ -96,7 +97,9 @@ exports.addTutorial = current => {
 exports.load = filepath => {
     let content;
     let current;
-    const files = fs.ls(filepath, env.opts.recurse ? env.conf.recurseDepth : undefined);
+    const files = lsSync(filepath, {
+        depth: env.opts.recurse ? env.conf.recurseDepth : 0
+    });
     let name;
     let match;
     let type;

packages/jsdoc/plugins/partial.js

@@ -4,7 +4,7 @@
  * @module plugins/partial
  */
 const env = require('jsdoc/env');
-const fs = require('jsdoc/fs');
+const fs = require('fs');
 const path = require('path');
 
 exports.handlers = {

packages/jsdoc/templates/default/publish.js

@@ -1,9 +1,11 @@
 const _ = require('lodash');
 const commonPathPrefix = require('common-path-prefix');
 const env = require('jsdoc/env');
-const fs = require('jsdoc/fs');
+const fs = require('fs');
 const helper = require('jsdoc/util/templateHelper');
 const logger = require('jsdoc/util/logger');
+const { lsSync } = require('@jsdoc/core').util.fs;
+const mkdirpSync = require('mkdirp').sync;
 const path = require('path');
 const { taffy } = require('taffydb');
 const template = require('jsdoc/template');
@@ -407,6 +409,12 @@ function buildNav(members) {
     return nav;
 }
 
+function sourceToDestination(parentDir, sourcePath, destDir) {
+    const relativeSource = path.relative(parentDir, sourcePath);
+
+    return path.resolve(path.join(destDir, relativeSource));
+}
+
 /**
     @param {TAFFY} taffyData See <http://taffydb.com/>.
     @param {object} opts
@@ -510,44 +518,44 @@ exports.publish = (taffyData, opts, tutorials) => {
     if (packageInfo && packageInfo.name) {
         outdir = path.join( outdir, packageInfo.name, (packageInfo.version || '') );
     }
-    fs.mkPath(outdir);
+    mkdirpSync(outdir);
 
     // copy the template's static files to outdir
     fromDir = path.join(templatePath, 'static');
-    staticFiles = fs.ls(fromDir, 3);
+    staticFiles = lsSync(fromDir);
 
     staticFiles.forEach(fileName => {
-        const toDir = fs.toDir( fileName.replace(fromDir, outdir) );
+        const toPath = sourceToDestination(fromDir, fileName, outdir);
 
-        fs.mkPath(toDir);
+        mkdirpSync(path.dirname(toPath));
-        fs.copyFileSync(fileName, toDir);
+        fs.copyFileSync(fileName, toPath);
     });
 
     // copy the fonts used by the template to outdir
-    staticFiles = fs.ls(path.join(require.resolve('open-sans-fonts'), '..', 'open-sans'), 3);
+    staticFiles = lsSync(path.join(require.resolve('open-sans-fonts'), '..', 'open-sans'));
 
     staticFiles.forEach(fileName => {
-        const toDir = path.join(outdir, 'fonts');
+        const toPath = path.join(outdir, 'fonts', path.basename(fileName));
 
         if (FONT_NAMES.includes(path.parse(fileName).name)) {
-            fs.mkPath(toDir);
+            mkdirpSync(path.dirname(toPath));
-            fs.copyFileSync(fileName, toDir);
+            fs.copyFileSync(fileName, toPath);
         }
     });
 
     // copy the prettify script to outdir
     PRETTIFIER_SCRIPT_FILES.forEach(fileName => {
-        const toDir = path.join(outdir, 'scripts');
+        const toPath = path.join(outdir, 'scripts', path.basename(fileName));
 
         fs.copyFileSync(
             path.join(require.resolve('code-prettify'), '..', fileName),
-            toDir
+            toPath
         );
     });
 
     // copy the prettify CSS to outdir
     PRETTIFIER_CSS_FILES.forEach(fileName => {
-        const toDir = path.join(outdir, 'styles');
+        const toPath = path.join(outdir, 'styles', path.basename(fileName));
 
         fs.copyFileSync(
             // `require.resolve()` has trouble with this package, so we use an extra-hacky way to
@@ -562,7 +570,7 @@ exports.publish = (taffyData, opts, tutorials) => {
                 'themes',
                 fileName
             ),
-            toDir
+            toPath
         );
     });
 
@@ -584,11 +592,10 @@ exports.publish = (taffyData, opts, tutorials) => {
             extraStaticFiles = staticFileScanner.scan([filePath], 10, staticFileFilter);
 
             extraStaticFiles.forEach(fileName => {
-                const sourcePath = fs.toDir(filePath);
+                const toPath = sourceToDestination(fromDir, fileName, outdir);
-                const toDir = fs.toDir( fileName.replace(sourcePath, outdir) );
 
-                fs.mkPath(toDir);
+                mkdirpSync(path.dirname(toPath));
-                fs.copyFileSync(fileName, toDir);
+                fs.copyFileSync(fileName, toPath);
             });
         });
     }

packages/jsdoc/test/helpers/jsdoc.js

@@ -4,7 +4,7 @@ const { createParser } = require('jsdoc/src/parser');
 const { defineTags } = require('jsdoc/tag/dictionary/definitions');
 const dictionary = require('jsdoc/tag/dictionary');
 const env = require('jsdoc/env');
-const fs = require('jsdoc/fs');
+const fs = require('fs');
 const handlers = require('jsdoc/src/handlers');
 const path = require('path');
 

packages/jsdoc/test/specs/jsdoc/src/parser.js

@@ -3,7 +3,7 @@ describe('jsdoc/src/parser', () => {
     const _ = require('lodash');
     const { attachTo } = require('jsdoc/src/handlers');
     const { dirname } = require('jsdoc/env');
-    const fs = require('jsdoc/fs');
+    const fs = require('fs');
     const jsdocParser = require('jsdoc/src/parser');
     const logger = require('jsdoc/util/logger');
     const path = require('path');