@squeep/log-helper 1.0.0

package/.eslintrc.json

@@ -0,0 +1,89 @@
+{
+  "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

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

package/README.md

@@ -0,0 +1,40 @@
+# @squeep/log-helper
+
+Utilities for standardized logging.
+
+## API
+
+- `fileScope(filepath, options)`
+  Returns a function which will decorate function names with some combination of the source file path, package name, and package version.  If the filepath is `index.js`, it will be replaced by its containing directory.  Defaults for what is included are determined by Squeep opinions on package layouts.
+
+  Example:
+
+  ```javascript
+  // Assuming this file is located at 'project/lib/subdir/code.js'
+  // Assuming project/package.json defines 'name' as 'project'
+  const { fileScope } = require('@squeep/log-helper');
+  const _fileScope = fileScope(__filename, { includeVersion: false });
+
+  function example() {
+    const _scope = _fileScope('example');
+    console.log(_scope); // Will show 'project:subdir/code:example'
+  }
+   ```
+
+  Options:
+  - `includePackage` Package name from `package.json`.
+  - `includeVersion` Package version from `package.json`.  If this is `true`, `includePackage` will also become `true`.
+  - `includePath` The path to the file, relative to the `package.json` file.
+  - `leftTrim` How much of the beginning of the path to elide. (e.g. 3 would render `foo/bar` as `/bar`)
+  - `delimiter` Placed between fields, defaults to `:`.
+  - `prefix` A field included before the package name.
+
+  Defaults, based on directory existing in project:
+  |                | `src` | `lib` | other |
+  |----------------|-------|-------|-------|
+  | includePackage | false | true  | false |
+  | includeVersion | false | true  | false |
+  | includePath    | true  | true  | false |
+  | leftTrim       | 4     | 4     | 0     |
+
+  If any errors are encountered while trying to determine the path or package metadata, the scope will be prefixed with a '?'.

package/index.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const { fileScope } = require('./lib/file-scope.js');
+
+module.exports = {
+  fileScope,
+};

package/lib/file-scope.js

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * An opinionated way to gather a source identifier to include in logged
+ * messages, using possibly too much information.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+/**
+ * Internal exception
+ */
+class FileScopeError extends Error {
+  constructor(...args) {
+    super(...args);
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  get name() {
+    return this.constructor.name;
+  }
+}
+
+
+/**
+ * Read and parse package.json from a path.
+ * @param {String} packagePath
+ * @returns {Object}
+ */
+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) {
+    return {
+      name: '(unknown)',
+      version: '(unknown)',
+    };
+  }
+}
+
+
+/**
+ * Returns whether path p exists.
+ * @param {String} p
+ * @returns {Boolean}
+ */
+function pathExists(p) {
+  try {
+    fs.statSync(p); // eslint-disable-line security/detect-non-literal-fs-filename
+    return true;
+  } catch (e) {
+    if (e.code !== 'ENOENT') {
+      throw e;
+    }
+    return false;
+  }
+}
+
+
+/**
+ * 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}
+ */
+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
+      return d + '/';
+    } catch (e) {
+      if (e.code !== 'ENOENT') {
+        throw e;
+      }
+    }
+    currentPath = d;
+  } while (currentPath !== '/');
+  throw new FileScopeError('unable to find package root');
+}
+
+
+/**
+ * Get default options based on package directory structure.
+ * @param {String} packageBase
+ * @returns {Object}
+ */
+function defaultOptions(packageBase) {
+  const options = {
+    includePath: false,
+    includePackage: false,
+    includeVersion: false,
+    leftTrim: 0,
+    _errorEncountered: false,
+    errorPrefix: '?',
+    delimiter: ':',
+  };
+
+  if (packageBase) {
+    try {
+      options.includePath = true;
+      if (pathExists(path.join(packageBase, 'lib'))) {
+        options.leftTrim = 4;
+        options.includePackage = true;
+        options.includeVersion = true;
+      } else if (pathExists(path.join(packageBase, 'src'))) {
+        options.leftTrim = 4;
+      }
+    } catch (e) {
+      options._errorEncountered = true;
+      options.includePath = false;
+    }
+  }
+
+  return options;
+}
+
+
+/**
+ * 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}
+ */
+function fileScope(filepath, options) {
+  let errorEncountered = false;
+  let packageBase = '';
+  try {
+    packageBase = locatePackageBase(filepath);
+  } catch (e) {
+    errorEncountered = true;
+  }
+  const defaults = defaultOptions(packageBase);
+  errorEncountered |= defaults._errorEncountered;
+  const {
+    includePackage,
+    includeVersion,
+    includePath,
+    prefix,
+    leftTrim,
+    errorPrefix,
+    delimiter,
+  } = {
+    ...defaults,
+    ...options,
+  };
+
+  let packageIdentifier;
+  if (includePackage || includeVersion) {
+    const { name: packageName, version: packageVersion } = readPackageJSON(packageBase);
+    // including version implies including package
+    packageIdentifier = includeVersion ? `${packageName}@${packageVersion}` : packageName;
+  }
+
+  const { base, name, ext } = path.parse(filepath);
+  const isIndex = (name === 'index') && ['.js', '.ts', '.mjs', '.cjs'].includes(ext);
+
+  // If filepath is an index, trim off filename and last slash, otherwise just trim off extension
+  const rightTrim = 0 - (isIndex ? (base.length + 1) : ext.length);
+  // We can't trim both ends at once as dirname won't work when isIndex is true
+  const rightTrimmed = filepath.slice(0, rightTrim);
+
+  // Trim leading part of path
+  const trim = (includePath && packageBase) ? (leftTrim + packageBase.length) : (path.dirname(rightTrimmed).length + 1);
+  const trimmedFilename = rightTrimmed.slice(trim);
+
+  const components = [errorEncountered ? errorPrefix : '', prefix, packageIdentifier, trimmedFilename]
+    .filter((x) => x);
+
+  const scope = components.join(delimiter);
+
+  return (name) => `${scope}${delimiter}${name}`;
+}
+
+
+module.exports = {
+  FileScopeError,
+  readPackageJSON,
+  pathExists,
+  locatePackageBase,
+  defaultOptions,
+  fileScope,
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@squeep/log-helper",
+  "version": "1.0.0",
+  "description": "Simple helpers for standardized logging",
+  "main": "index.js",
+  "engines": {
+    "node": ">=14"
+  },
+  "directories": {
+    "lib": "lib",
+    "test": "test"
+  },
+  "scripts": {
+    "coverage": "nyc npm test",
+    "coverage-check": "nyc check-coverage",
+    "eslint": "eslint *.js lib test",
+    "test": "mocha --recursive"
+  },
+  "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"
+  }
+}

package/test/lib/file-scope.js

@@ -0,0 +1,282 @@
+/* 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