update devDependencies, fix lint issues

[squeep-log-helper] / lib / file-scope.js

diff --git a/lib/file-scope.js b/lib/file-scope.js
index 57421a42e810954884efadd182e235d664f6b013..a42ba1518e45b49e51872e18bf5e08fb76f3ad08 100644 (file)
--- a/lib/file-scope.js
+++ b/lib/file-scope.js
@@ -23,16 +23,21 @@ class FileScopeError extends Error {
 }
 
 
+/**
+ * @typedef {object} PackageDetails
+ * @property {string} name - package name
+ * @property {string} version - package version
+ */
 /**
  * Read and parse package.json from a path.
- * @param {String} packagePath
- * @returns {Object}
+ * @param {string} packagePath - path to package.json
+ * @returns {PackageDetails} selected details from package.json
  */
 function readPackageJSON(packagePath) {
   try {
     const content = fs.readFileSync(path.join(packagePath, 'package.json')); // eslint-disable-line security/detect-non-literal-fs-filename
     return JSON.parse(content);
-  } catch (e) {
+  } catch (e) { // eslint-disable-line no-unused-vars
     return {
       name: '(unknown)',
       version: '(unknown)',
@@ -43,8 +48,8 @@ function readPackageJSON(packagePath) {
 
 /**
  * Returns whether path p exists.
- * @param {String} p
- * @returns {Boolean}
+ * @param {string} p path
+ * @returns {boolean} exists
  */
 function pathExists(p) {
   try {
@@ -62,15 +67,15 @@ function pathExists(p) {
 /**
  * Walk up the path of provided filename until directory with
  * package.json is located.  We assume this is the package root.
- * @param {String} filename
- * @returns {String}
+ * @param {string} filename path to file
+ * @returns {string} path to package root
  */
 function locatePackageBase(filename) {
   let currentPath = filename;
   do {
     const d = path.dirname(currentPath);
     try {
-      fs.statSync(path.join(d, 'package.json'));  // eslint-disable-line security/detect-non-literal-fs-filename
+      fs.statSync(path.join(d, 'package.json')); // eslint-disable-line security/detect-non-literal-fs-filename
       return d + '/';
     } catch (e) {
       if (e.code !== 'ENOENT') {
@@ -85,8 +90,8 @@ function locatePackageBase(filename) {
 
 /**
  * Get default options based on package directory structure.
- * @param {String} packageBase
- * @returns {Object}
+ * @param {string} packageBase path to package root
+ * @returns {object} options
  */
 function defaultOptions(packageBase) {
   const options = {
@@ -109,7 +114,7 @@ function defaultOptions(packageBase) {
       } else if (pathExists(path.join(packageBase, 'src'))) {
         options.leftTrim = 4;
       }
-    } catch (e) {
+    } catch (e) { // eslint-disable-line no-unused-vars
       options._errorEncountered = true;
       options.includePath = false;
     }
@@ -122,23 +127,23 @@ function defaultOptions(packageBase) {
 /**
  * Returns a function suitable for decorating a function name with
  * package information and details of the source file.
- * @param {String} filepath full path from __filename
- * @param {Object=} options
- * @param {Boolean=} options.includePackage
- * @param {Boolean=} options.includeVersion
- * @param {Boolean=} options.includePath
- * @param {String=} options.prefix
- * @param {Number=} options.leftTrim
- * @param {String=} options.errorPrefix
- * @param {String=} options.delimiter
- * @returns {Function}
+ * @param {string} filepath full path from __filename
+ * @param {object=} options controlling component inclusion
+ * @param {boolean=} options.includePackage full package name
+ * @param {boolean=} options.includeVersion package version
+ * @param {boolean=} options.includePath when indicating filename
+ * @param {string=} options.prefix static string to include
+ * @param {number=} options.leftTrim characters to omit from start of path/filename
+ * @param {string=} options.errorPrefix string to include at start if an error was encountered
+ * @param {string=} options.delimiter joining selected components
+ * @returns {Function} marks up provided string with selected components
  */
 function fileScope(filepath, options) {
   let errorEncountered = false;
   let packageBase = '';
   try {
     packageBase = locatePackageBase(filepath);
-  } catch (e) {
+  } catch (e) { // eslint-disable-line no-unused-vars
     errorEncountered = true;
   }
   const defaults = defaultOptions(packageBase);
@@ -159,7 +164,7 @@ function fileScope(filepath, options) {
   let packageIdentifier;
   if (includePackage || includeVersion) {
     const { name: packageName, version: packageVersion } = readPackageJSON(packageBase);
-    // including version implies including package
+    // Including version implies including package
     packageIdentifier = includeVersion ? `${packageName}@${packageVersion}` : packageName;
   }