@squeep/log-helper 1.0.0 → 1.0.2

package/README.md

@@ -30,10 +30,10 @@ Utilities for standardized logging.
   - `prefix` A field included before the package name.
 
   Defaults, based on directory existing in project:
-  |                | `src` | `lib` | other |
+  |  precedence -> | `lib` | `src` | other |
   |----------------|-------|-------|-------|
-  | includePackage | false | true  | false |
-  | includeVersion | false | true  | false |
+  | includePackage | true  | false | false |
+  | includeVersion | true  | false | false |
   | includePath    | true  | true  | false |
   | leftTrim       | 4     | 4     | 0     |
 

package/lib/file-scope.js

@@ -8,6 +8,32 @@
 const path = require('node:path');
 const fs = require('node:fs');
 
+
+/**
+ * @typedef {object} FileScopeOptions
+ * @property {boolean=} includePackage full package name
+ * @property {boolean=} includeVersion package version
+ * @property {boolean=} includePath when indicating filename
+ * @property {string=} prefix static string to include
+ * @property {number=} leftTrim characters to omit from start of path/filename
+ * @property {string=} errorPrefix string to include at start if an error was encountered
+ * @property {string=} delimiter joining selected components
+ */
+
+
+/**
+ * @typedef {FileScopeOptions} FileScopeOptionsInternal
+ * @property {boolean=} _errorEncountered flag if error while setting defaults
+ */
+
+
+/**
+ * @typedef {object} PackageDetails
+ * @property {string} name package name
+ * @property {string} version package version
+ */
+
+
 /**
  * Internal exception
  */
@@ -25,14 +51,14 @@ class FileScopeError extends Error {
 
 /**
  * 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)',
@@ -42,16 +68,16 @@ function readPackageJSON(packagePath) {
 
 
 /**
- * Returns whether path p exists.
- * @param {String} p
- * @returns {Boolean}
+ * Returns whether path p exists and is accessible.
+ * @param {string} p path
+ * @returns {boolean} exists
  */
 function pathExists(p) {
   try {
     fs.statSync(p); // eslint-disable-line security/detect-non-literal-fs-filename
     return true;
   } catch (e) {
-    if (e.code !== 'ENOENT') {
+    if (!(['ENOENT', 'EACCES'].includes(e.code))) {
       throw e;
     }
     return false;
@@ -62,20 +88,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
+    if (pathExists(path.join(d, 'package.json'))) {
       return d + '/';
-    } catch (e) {
-      if (e.code !== 'ENOENT') {
-        throw e;
-      }
     }
     currentPath = d;
   } while (currentPath !== '/');
@@ -85,8 +106,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 {FileScopeOptionsInternal} options
  */
 function defaultOptions(packageBase) {
   const options = {
@@ -109,7 +130,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 +143,16 @@ 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 {FileScopeOptions=} options controlling component inclusion
+ * @returns {(name: string) => string} 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 +173,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;
   }
 
@@ -176,7 +190,7 @@ function fileScope(filepath, options) {
   const trimmedFilename = rightTrimmed.slice(trim);
 
   const components = [errorEncountered ? errorPrefix : '', prefix, packageIdentifier, trimmedFilename]
-    .filter((x) => x);
+    .filter(Boolean);
 
   const scope = components.join(delimiter);
 

package/package.json

@@ -1,37 +1,30 @@
 {
   "name": "@squeep/log-helper",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Simple helpers for standardized logging",
   "main": "index.js",
   "engines": {
-    "node": ">=14"
-  },
-  "directories": {
-    "lib": "lib",
-    "test": "test"
+    "node": ">=20.13.0"
   },
+  "files": [
+    "lib/*.js"
+  ],
   "scripts": {
+    "audit": "npm audit",
     "coverage": "nyc npm test",
     "coverage-check": "nyc check-coverage",
-    "eslint": "eslint *.js lib test",
-    "test": "mocha --recursive"
+    "eslint": "eslint index.js lib test",
+    "test": "node --test",
+    "prepare": "husky"
   },
   "keywords": [],
   "author": "Justin Wind <jwind-npm@squeep.com>",
   "license": "ISC",
-  "pre-commit": [
-    "eslint",
-    "coverage",
-    "coverage-check"
-  ],
   "devDependencies": {
-    "eslint": "^8.53.0",
-    "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-security": "^1.7.1",
-    "eslint-plugin-sonarjs": "^0.23.0",
-    "mocha": "^10.2.0",
-    "nyc": "^15.1.0",
-    "pre-commit": "^1.2.2",
-    "sinon": "^17.0.1"
+    "@squeep/eslint-config": "^1",
+    "eslint": "^9",
+    "husky": "^9",
+    "nyc": "^17",
+    "sinon": "^21"
   }
 }

package/.eslintrc.json

@@ -1,89 +0,0 @@
-{
-  "env": {
-    "browser": false,
-    "es6": true,
-    "node": true
-  },
-  "extends": [
-    "eslint:recommended",
-    "plugin:node/recommended",
-    "plugin:security/recommended",
-    "plugin:sonarjs/recommended"
-  ],
-  "parserOptions": {
-    "ecmaVersion": "latest"
-  },
-  "plugins": [
-    "node",
-    "security",
-    "sonarjs"
-  ],
-  "rules": {
-    "array-element-newline": [
-      "error",
-      "consistent"
-    ],
-    "arrow-parens": [
-      "error",
-      "always"
-    ],
-    "arrow-spacing": [
-      "error",
-      {
-        "after": true,
-        "before": true
-      }
-    ],
-    "block-scoped-var": "error",
-    "block-spacing": "error",
-    "brace-style": "error",
-    "callback-return": "error",
-    "camelcase": "error",
-    "class-methods-use-this": "error",
-    "comma-dangle": [
-      "error",
-      "always-multiline"
-    ],
-    "comma-spacing": [
-      "error",
-      {
-        "after": true,
-        "before": false
-      }
-    ],
-    "comma-style": [
-      "error",
-      "last"
-    ],
-    "indent": [
-      "warn",
-      2,
-      {
-        "SwitchCase": 1
-      }
-    ],
-    "sonarjs/cognitive-complexity": "warn",
-    "sonarjs/no-duplicate-string": "warn",
-    "keyword-spacing": "error",
-    "linebreak-style": [
-      "error",
-      "unix"
-    ],
-    "no-unused-vars": [
-      "error", {
-        "varsIgnorePattern": "^_"
-      }
-    ],
-    "object-curly-spacing": [
-      "error",
-      "always"
-    ],
-    "prefer-const": "error",
-    "quotes": [
-      "warn",
-      "single"
-    ],
-    "strict": "error",
-    "vars-on-top": "error"
-  }
-}

package/.nycrc.json

@@ -1,6 +0,0 @@
-{
-  "reporter": [
-    "lcov",
-    "text"
-  ]
-}

package/test/lib/file-scope.js

@@ -1,282 +0,0 @@
-/* eslint-env mocha */
-'use strict';
-
-const assert = require('assert');
-const sinon = require('sinon'); // eslint-disable-line node/no-unpublished-require
-const fs = require('fs');
-const {
-  readPackageJSON,
-  fileScope,
-  locatePackageBase,
-  defaultOptions,
-  pathExists,
-  FileScopeError,
-} = require('../../lib/file-scope');
-
-describe('File Scope', function () {
-  let noentError;
-
-  before(function () {
-    noentError = new Error('ENOENT: no such file or directory');
-    Object.assign(noentError, {
-      errno: -2,
-      syscall: 'stat',
-      code: 'ENOENT',
-    });
-  });
-
-  afterEach(function () {
-    sinon.restore();
-  });
-
-  describe('FileScopeError', function () {
-    it('covers', function () {
-      const e = new FileScopeError('beep');
-      assert.strictEqual(e.name, 'FileScopeError');
-    });
-  }); // FileScopeError
-
-  describe('readPackageJSON', function () {
-    let filepath;
-    beforeEach(function () {
-      filepath = '/path/to/package.json';
-      sinon.stub(fs, 'readFileSync').returns(`{
-        "name": "@example/package",
-        "version": "3.1.4"
-      }`);
-    });
-    it('covers success', function () {
-      const result = readPackageJSON(filepath);
-      assert.strictEqual(result.name, '@example/package');
-      assert.strictEqual(result.version, '3.1.4');
-    });
-    it('covers failure', function () {
-      fs.readFileSync.throws();
-      const result = readPackageJSON(filepath);
-      assert.strictEqual(result.name, '(unknown)');
-      assert.strictEqual(result.version, '(unknown)');
-    });
-  }); // readJSONFile
-
-  describe('pathExists', function () {
-    let p;
-    beforeEach(function () {
-      p = '/path/to/package';
-      sinon.stub(fs, 'statSync').returns();
-    });
-    it('returns true when path exists', function () {
-      const result = pathExists(p);
-      assert.strictEqual(result, true);
-    });
-    it('returns false when path does not exist', function () {
-      fs.statSync.throws(noentError);
-      const result = pathExists(p);
-      assert.strictEqual(result, false);
-    });
-    it('raises other error', function () {
-      const expectedError = new Error('oh no');
-      fs.statSync.throws(expectedError);
-      assert.throws(() => pathExists(p), expectedError);
-    });
-  }); // pathExists
-
-  describe('locatePackageBase', function () {
-    let filepath;
-
-    beforeEach(function () {
-      filepath = '/path/to/package/lib/file.js';
-      sinon.stub(fs, 'statSync');
-    });
-
-    it('covers unstubbed result', function () {
-      sinon.restore();
-      locatePackageBase(__filename);
-    });
-
-    it('locates the package base', function () {
-      fs.statSync
-        .onCall(0).throws(noentError)
-        .onCall(1).returns()
-      ;
-      const result = locatePackageBase(filepath);
-      assert.strictEqual(result, '/path/to/package/');
-    });
-
-    it('cannot locate the package base', function () {
-      fs.statSync.throws(noentError);
-      assert.throws(() => locatePackageBase(filepath), FileScopeError);
-    });
-
-    it('propagates unknown error', function () {
-      const expectedException = new Error('oh no');
-      fs.statSync
-        .onCall(0).throws(noentError)
-        .onCall(1).throws(expectedException)
-      ;
-      assert.throws(() => locatePackageBase(filepath), expectedException);
-    });
-  }); // locatePackageBase
-
-  describe('defaultOptions', function () {
-    let packageBase, expected;
-    beforeEach(function () {
-      packageBase = '/path/to/package';
-      sinon.stub(fs, 'statSync').returns();
-      expected = {
-        includePath: false,
-        includePackage: false,
-        includeVersion: false,
-        leftTrim: 0,
-        _errorEncountered: false,
-        errorPrefix: '?',
-        delimiter: ':',
-      };
-    });
-    it('covers no path', function () {
-      const options = defaultOptions();
-      assert.deepStrictEqual(options, expected);
-    });
-    it('covers default', function () {
-      expected.includePath = true;
-      fs.statSync.throws(noentError);
-      const options = defaultOptions(packageBase);
-      assert.deepStrictEqual(options, expected);
-    });
-    it('covers lib package', function () {
-      expected.includePath = true;
-      expected.includePackage = true;
-      expected.includeVersion = true;
-      expected.leftTrim = 4;
-      const options = defaultOptions(packageBase);
-      assert.deepStrictEqual(options, expected);
-    });
-    it('covers src package', function () {
-      expected.includePath = true;
-      expected.leftTrim = 4;
-      fs.statSync.onCall(0).throws(noentError);
-      const options = defaultOptions(packageBase);
-      assert.deepStrictEqual(options, expected);
-    });
-    it('covers error', function () {
-      const expectedError = new Error('oh no');
-      fs.statSync.throws(expectedError);
-      expected._errorEncountered = true;
-      const options = defaultOptions(packageBase);
-      assert.deepStrictEqual(options, expected);
-    });
-  }); // defaultOptions
-
-  describe('fileScope', function () {
-    let filepath, options, method;
-    beforeEach(function () {
-      filepath = '/path/to/package/lib/deep/file.js';
-      sinon.stub(fs, 'statSync')
-        .onCall(0).throws(noentError) // deep
-        .onCall(1).throws(noentError) // lib
-        .onCall(2).returns() // packageBase
-      ;
-      sinon.stub(fs, 'readFileSync').returns(`{
-        "name": "@example/package",
-        "version": "3.1.4"
-      }`);
-      options = {
-        includePath: true,
-        includePackage: false,
-        includeVersion: false,
-      };
-      method = 'method';
-    });
-
-    it('defaults', function () {
-      filepath = '/path/to/package/code/module/file.js';
-      fs.statSync
-        .onCall(3).throws(noentError) // no lib
-        .onCall(4).throws(noentError) // no src
-      ;
-      const result = fileScope(filepath)(method);
-      assert.strictEqual(result, 'code/module/file:method');
-    });
-
-    it('everything', function () {
-      options.includePath = true;
-      options.includePackage = true;
-      options.includeVersion = true;
-      const result = fileScope(filepath, options)(method);
-      assert.strictEqual(result, '@example/package@3.1.4:deep/file:method');
-    });
-
-    it('minimal', function () {
-      options.includePath = false;
-      options.includePackage = false;
-      options.includeVersion = false;
-      const result = fileScope(filepath, options)(method);
-      assert.strictEqual(result, 'file:method');
-    });
-
-    it('package only', function () {
-      options.includePath = false;
-      options.includePackage = true;
-      options.includeVersion = false;
-      const result = fileScope(filepath, options)(method);
-      assert.strictEqual(result, '@example/package:file:method');
-    });
-
-    it('covers no package root', function () {
-      options.includePackage = true;
-      fs.statSync.restore()
-      sinon.stub(fs, 'statSync').throws(noentError);
-      fs.readFileSync.throws(noentError);
-      const result = fileScope(filepath, options)(method);
-      assert.strictEqual(result, '?:(unknown):file:method');
-    });
-
-    it('covers exception while finding package root', function () {
-      const expectedException = new Error('oh no');
-      options.includePackage = true;
-      fs.statSync.restore()
-      sinon.stub(fs, 'statSync').throws(expectedException);
-      fs.readFileSync.throws(noentError);
-      const result = fileScope(filepath, options)(method);
-      assert.strictEqual(result, '?:(unknown):file:method');
-    });
-
-    it('handles index.js', function () {
-      filepath = '/path/to/package/src/deep/index.js';
-      fs.statSync
-        .onCall(3).throws(noentError) // no lib
-        .onCall(4).returns() // src
-      ;
-      const result = fileScope(filepath)(method);
-      assert.strictEqual(result, 'deep:method');
-    });
-
-    it('handles index.js when including path', function () {
-      filepath = '/path/to/package/code/folder/deep/index.js';
-      fs.statSync.restore();
-      sinon.stub(fs, 'statSync')
-        .throws(noentError)
-        .onCall(3).returns() // packageBase found
-        // no lib
-        // no src
-      ;
-      const result = fileScope(filepath)(method);
-      assert.strictEqual(result, 'code/folder/deep:method');
-    });
-
-    it('handles index.js when not including path', function () {
-      filepath = '/path/to/package/code/folder/deep/index.ts';
-      fs.statSync.restore();
-      sinon.stub(fs, 'statSync')
-        .throws(noentError)
-        .onCall(3).returns() // packageBase found
-        // no lib
-        // no src
-      ;
-      const result = fileScope(filepath, { includePath: false })(method);
-      assert.strictEqual(result, 'deep:method');
-    });
-
-  }); // fileScope
-
-
-}); // File Scope