From b8316d893333d6958e981919eccdf392ce780f21 Mon Sep 17 00:00:00 2001 From: Jeff Williams Date: Sun, 8 Dec 2019 14:09:59 -0800 Subject: [PATCH] refactor(jsdoc): remove `jsdoc/fs` BREAKING CHANGE: Removed `jsdoc/fs`. Use `@jsdoc/core.util.fs` and other packages instead. --- packages/jsdoc/cli.js | 2 +- packages/jsdoc/lib/jsdoc/fs.js | 110 ------------------ packages/jsdoc/lib/jsdoc/readme.js | 2 +- packages/jsdoc/lib/jsdoc/src/parser.js | 2 +- packages/jsdoc/lib/jsdoc/src/scanner.js | 8 +- packages/jsdoc/lib/jsdoc/template.js | 2 +- packages/jsdoc/lib/jsdoc/tutorial/resolver.js | 7 +- packages/jsdoc/plugins/partial.js | 2 +- packages/jsdoc/templates/default/publish.js | 43 ++++--- packages/jsdoc/test/helpers/jsdoc.js | 2 +- packages/jsdoc/test/specs/jsdoc/src/parser.js | 2 +- 11 files changed, 41 insertions(+), 141 deletions(-) delete mode 100644 packages/jsdoc/lib/jsdoc/fs.js diff --git a/packages/jsdoc/cli.js b/packages/jsdoc/cli.js index 6f5644f0..c241d6bd 100644 --- a/packages/jsdoc/cli.js +++ b/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') ); diff --git a/packages/jsdoc/lib/jsdoc/fs.js b/packages/jsdoc/lib/jsdoc/fs.js deleted file mode 100644 index d300963f..00000000 --- a/packages/jsdoc/lib/jsdoc/fs.js +++ /dev/null @@ -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]; - } -}); - diff --git a/packages/jsdoc/lib/jsdoc/readme.js b/packages/jsdoc/lib/jsdoc/readme.js index 8da87c32..5205d544 100644 --- a/packages/jsdoc/lib/jsdoc/readme.js +++ b/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'); /** diff --git a/packages/jsdoc/lib/jsdoc/src/parser.js b/packages/jsdoc/lib/jsdoc/src/parser.js index d91ea9ee..cb8b5e25 100644 --- a/packages/jsdoc/lib/jsdoc/src/parser.js +++ b/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'); diff --git a/packages/jsdoc/lib/jsdoc/src/scanner.js b/packages/jsdoc/lib/jsdoc/src/scanner.js index 4467e4f8..d28eaa60 100644 --- a/packages/jsdoc/lib/jsdoc/src/scanner.js +++ b/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)); } }); diff --git a/packages/jsdoc/lib/jsdoc/template.js b/packages/jsdoc/lib/jsdoc/template.js index 3eb20778..4d7ff79c 100644 --- a/packages/jsdoc/lib/jsdoc/template.js +++ b/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'); /** diff --git a/packages/jsdoc/lib/jsdoc/tutorial/resolver.js b/packages/jsdoc/lib/jsdoc/tutorial/resolver.js index f5dd92fc..eed4203f 100644 --- a/packages/jsdoc/lib/jsdoc/tutorial/resolver.js +++ b/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; diff --git a/packages/jsdoc/plugins/partial.js b/packages/jsdoc/plugins/partial.js index 83c84f20..e3ea0ccd 100644 --- a/packages/jsdoc/plugins/partial.js +++ b/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 = { diff --git a/packages/jsdoc/templates/default/publish.js b/packages/jsdoc/templates/default/publish.js index 2b3a0def..e5880558 100644 --- a/packages/jsdoc/templates/default/publish.js +++ b/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 . @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); - fs.copyFileSync(fileName, toDir); + mkdirpSync(path.dirname(toPath)); + 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); - fs.copyFileSync(fileName, toDir); + mkdirpSync(path.dirname(toPath)); + 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 toDir = fs.toDir( fileName.replace(sourcePath, outdir) ); + const toPath = sourceToDestination(fromDir, fileName, outdir); - fs.mkPath(toDir); - fs.copyFileSync(fileName, toDir); + mkdirpSync(path.dirname(toPath)); + fs.copyFileSync(fileName, toPath); }); }); } diff --git a/packages/jsdoc/test/helpers/jsdoc.js b/packages/jsdoc/test/helpers/jsdoc.js index 7a926d27..24f5420c 100644 --- a/packages/jsdoc/test/helpers/jsdoc.js +++ b/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'); diff --git a/packages/jsdoc/test/specs/jsdoc/src/parser.js b/packages/jsdoc/test/specs/jsdoc/src/parser.js index b605920b..92153da6 100644 --- a/packages/jsdoc/test/specs/jsdoc/src/parser.js +++ b/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');