chore: switch to 'npm workspaces' (#156)

Let's try npm workspaces for handling multiple packages.
The primary win is developing local changes to the helpers
package and having the others automatically linked.

Note that npm workspaces requires npm@7 or later, which
typically means node@16 or later. For earler Node.js versions
there are utils/run-* scripts to support install/test/lint.

.github/workflows/test.yml

@@ -21,8 +21,8 @@ jobs:
       - uses: actions/setup-node@v3
         with:
           node-version: 18
-      - run: .ci/run-install.sh
-      - run: .ci/run-lint.sh
+      - run: utils/run-install.sh
+      - run: utils/run-lint.sh
 
   test:
     runs-on: ubuntu-latest
@@ -36,6 +36,6 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
       - name: Install dependencies
-        run: .ci/run-install.sh
+        run: utils/run-install.sh
       - name: Test Node.js v${{ matrix.node-version }}
-        run: .ci/run-test.sh
+        run: utils/run-test.sh

CONTRIBUTING.md

@@ -1,53 +1,40 @@
 # Contributing to the ecs-logging-nodejs libraries
 
-The ecs-logging-nodejs libraries are open source and we love to receive contributions
-from our community — you!
+The ecs-logging-nodejs libraries are open source and all contributions
+(issues, comments, pull requests) are welcome.
 
-There are many ways to contribute,
-from writing tutorials or blog posts,
-improving the documentation,
-submitting bug reports and feature requests or writing code.
 
-## Repository structure
+## Developing for this repository
 
-This repository contains multiple packages, that you can find inside the `loggers/*`
-folder and inside the `helper` folder.
-Every package has its own `package.json` and `node_modules` folder, same for test
-and documentation.
+This repository contains multiple packages, in the "packages/" directory. It
+is using [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces)
+to manage multiple packages. The common tasks are:
 
-## Code contributions
+    npm --workspaces install
+    npm --workspaces test
+    npm --workspaces lint
+    npm --workspaces lint:fix
 
-If you have a bugfix or new feature that you would like to contribute,
-please find or open an issue about it first.
-Talk about what you would like to do.
-It may be that somebody is already working on it,
-or that there are particular issues that you should know about before implementing the change.
+Using npm workspaces requires npm@7 or later, which typically means Node.js
+v16 or later. However, these packages currently support back to Node.js v10.
+For earlier versions of Node.js, you can install and test using:
 
-### Submitting your changes
+    make all
+    make test
 
-Generally, we require that you test any code you are adding or modifying.
-Once your changes are ready to submit for review:
-
-1. Test your changes
 
-    Run the test suite to make sure that nothing is broken. For a single
-    package:
+## Pull requests
 
-        npm test
+Generally, we require that you test any code you are adding or modifying.
+Once your changes are ready to submit for review:
 
-    Or for all packages:
+1. Test your changes:
 
-        .ci/run_install.sh   # to install dependencies
-        .ci/run_test.sh
+        npm --workspaces test
 
 2. Submit a pull request
 
     Push your local changes to your forked copy of the repository and [submit a pull request](https://help.github.com/articles/using-pull-requests).
-    In the pull request,
-    choose a title which sums up the changes that you have made,
-    and in the body provide more details about what your changes do.
-    Also mention the number of the issue where discussion has taken place,
-    eg "Closes #123".
 
 3. Sign the Contributor License Agreement
 

Makefile

@@ -1,49 +1,28 @@
-# All development tasks are typically available via npm scripts, i.e.
-# `npm run <script> ...` or via CI scripts (".ci/*.sh"). This Makefile
-# exists as a convenience for some common tasks.
+# Common development tasks are typically available via npm scripts, e.g.:
+#	  npm --workspaces install
+#	  npm --workspaces test
+#	  npm --workspaces lint
+#	  npm --workspaces lint:fix
+#
+# This Makefile exists as a convenience, to support older Node.js versions
+# (which npm <=7 when workspaces support was added), and to support some less
+# common tasks.
 
 .PHONY: all
 all:
-	./.ci/run-install.sh
-	(cd utils && npm install)
+	./utils/run-install.sh
 
-.PHONY: clean
-clean:
-	(cd helpers && rm -rf node_modules)
-	(cd loggers/winston && rm -rf node_modules)
-	(cd loggers/morgan && rm -rf node_modules)
-	(cd loggers/pino && rm -rf node_modules)
-	(cd utils && rm -rf node_modules)
+.PHONY: test
+test:
+	./utils/run-test.sh
 
 .PHONY: lint
 lint: check-license-headers
-	./.ci/run-lint.sh
+	./utils/run-lint.sh
 
 .PHONY: fmt
 fmt:
-	(cd helpers && npm run lint:fix)
-	(cd loggers/winston && npm run lint:fix)
-	(cd loggers/morgan && npm run lint:fix)
-	(cd loggers/pino && npm run lint:fix)
-	(cd utils && npm run lint:fix)
-
-.PHONY: test
-test:
-	./.ci/run-test.sh
-
-# For local dev, setup each logger to use the local helpers, rather than
-# a version published to npm. Need to be careful to not *push* with that
-# tweak to each package.json.
-.PHONY: install-local-helpers undo-install-local-helpers
-install-local-helpers:
-	(cd loggers/winston && npm install ../../helpers)
-	(cd loggers/morgan && npm install ../../helpers)
-	(cd loggers/pino && npm install ../../helpers)
-undo-install-local-helpers:
-	export HELPERS_VER=$(shell cd helpers && npm info . version) && \
-		(cd loggers/winston && npm install @elastic/ecs-helpers@v$$HELPERS_VER) && \
-		(cd loggers/morgan && npm install @elastic/ecs-helpers@v$$HELPERS_VER) && \
-		(cd loggers/pino && npm install @elastic/ecs-helpers@v$$HELPERS_VER)
+	npm --workspaces lint:fix # requires npm>=7 (aka node>=16)
 
 # Build and open the rendered docs for testing.
 #
@@ -61,7 +40,7 @@ docs-and-open:
 # List licenses of prod deps.
 .PHONY: list-licenses
 list-licenses:
-	@for dir in helpers $(shell ls -d loggers/*); do \
+	@for dir in helpers $(shell ls -d packages/*); do \
 		(cd $$dir && npm ls --prod --parseable | while read subdir; do node -e "console.log(require('$$subdir/package.json').license)"; done) \
 	done | sort | uniq -c | sort -n
 

README.md

@@ -12,11 +12,11 @@ Please see the [Node.js ECS logging documentation](https://www.elastic.co/guide/
 
 ## Supported logging frameworks
 
-- [Morgan](https://github.com/expressjs/morgan) via [@elastic/ecs-morgan-format](./loggers/morgan)
+- [Morgan](https://github.com/expressjs/morgan) via [@elastic/ecs-morgan-format](./packages/ecs-morgan-format)
   ([docs](https://www.elastic.co/guide/en/ecs-logging/nodejs/current/morgan.html))
-- [Pino](https://getpino.io/#/) via [@elastic/ecs-pino-format](./loggers/pino)
+- [Pino](https://getpino.io/#/) via [@elastic/ecs-pino-format](./packages/ecs-pino-format)
   ([docs](https://www.elastic.co/guide/en/ecs-logging/nodejs/current/pino.html))
-- [Winston](https://github.com/winstonjs/winston) via [@elastic/ecs-winston-format](./loggers/winston)
+- [Winston](https://github.com/winstonjs/winston) via [@elastic/ecs-winston-format](./packages/ecs-winston-format)
   ([docs](https://www.elastic.co/guide/en/ecs-logging/nodejs/current/winston.html))
 
 ## Links

docs/morgan.asciidoc

@@ -75,7 +75,7 @@ app.listen(3000)
 ----
 <1> See available options <<morgan-ref,below>>.
 
-Running this script (the full example is https://github.com/elastic/ecs-logging-nodejs/blob/main/loggers/morgan/examples/express.js[here])
+Running this script (the full example is https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-morgan-format/examples/express.js[here])
 and making a request (via `curl -i localhost:3000/`) will produce log output
 similar to the following:
 
@@ -143,7 +143,7 @@ app.use(morgan(ecsFormat({ format: 'tiny' }))) <1>
 === log.level
 
 The `log.level` field will be "error" for response codes >= 500, otherwise
-"info". For example, running  https://github.com/elastic/ecs-logging-nodejs/blob/main/loggers/morgan/examples/express.js[examples/express.js]
+"info". For example, running  https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-morgan-format/examples/express.js[examples/express.js]
 again, a `curl -i localhost:3000/error` will yield:
 
 [source,cmd]
@@ -178,7 +178,7 @@ services or traces and logging data:
 - `event.dataset` enables {observability-guide}/inspect-log-anomalies.html[log
   rate anomaly detection] in the Elastic Observability app.
 
-For example, running https://github.com/elastic/ecs-logging-nodejs/blob/main/loggers/morgan/examples/express-with-apm.js[examples/express-with-apm.js] and `curl -i localhost:3000/` results in a log record with the following:
+For example, running https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-morgan-format/examples/express-with-apm.js[examples/express-with-apm.js] and `curl -i localhost:3000/` results in a log record with the following:
 
 [source,cmd]
 ----

docs/pino.asciidoc

@@ -196,10 +196,10 @@ For example:
 }
 ----
 
-The https://github.com/elastic/ecs-logging-nodejs/tree/main/loggers/pino/examples[examples/ directory]
+The https://github.com/elastic/ecs-logging-nodejs/tree/main/packages/ecs-pino-format/examples[examples/ directory]
 shows sample programs using request and response logging:
-https://github.com/elastic/ecs-logging-nodejs/tree/main/loggers/pino/examples/express-simple.js[with Express],
-https://github.com/elastic/ecs-logging-nodejs/tree/main/loggers/pino/examples/express-with-pino-http.js[with the pino-http middleware package],
+https://github.com/elastic/ecs-logging-nodejs/tree/main/packages/ecs-pino-format/examples/express-simple.js[with Express],
+https://github.com/elastic/ecs-logging-nodejs/tree/main/packages/ecs-pino-format/examples/express-with-pino-http.js[with the pino-http middleware package],
 etc.
 
 
@@ -221,7 +221,7 @@ services or traces and logging data:
 - `event.dataset` enables {observability-guide}/inspect-log-anomalies.html[log
   rate anomaly detection] in the Elastic Observability app.
 
-For example, running https://github.com/elastic/ecs-logging-nodejs/blob/main/loggers/pino/examples/http-with-elastic-apm.js[examples/http-with-elastic-apm.js] and `curl -i localhost:3000/` results in a log record with the following:
+For example, running https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-pino-format/examples/http-with-elastic-apm.js[examples/http-with-elastic-apm.js] and `curl -i localhost:3000/` results in a log record with the following:
 
 [source,cmd]
 ----

docs/winston.asciidoc

@@ -74,7 +74,7 @@ logger.error('oops there is a problem', { foo: 'bar' })
 ----
 <1> See available options <<winston-ref,below>>.
 
-Running this script (available https://github.com/elastic/ecs-logging-nodejs/blob/main/loggers/winston/examples/basic.js[here]) will produce log output similar to the following:
+Running this script (available https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-winston-format/examples/basic.js[here]) will produce log output similar to the following:
 
 [source,cmd]
 ----
@@ -95,7 +95,7 @@ the https://github.com/winstonjs/logform#timestamp[timestamp] formatter.
 
 By default, the formatter will convert an `err` meta field that is an Error instance
 to {ecs-ref}/ecs-error.html[ECS Error fields].
-For https://github.com/elastic/ecs-logging-nodejs/blob/main/loggers/winston/examples/error.js[example]:
+For https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-winston-format/examples/error.js[example]:
 
 [source,js]
 ----
@@ -181,7 +181,7 @@ function handler (req, res) {
 
 This will produce logs with request and response info using
 {ecs-ref}/ecs-http.html[ECS HTTP fields].
-For https://github.com/elastic/ecs-logging-nodejs/blob/main/loggers/winston/examples/http.js[example]:
+For https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-winston-format/examples/http.js[example]:
 
 [source,cmd]
 ----
@@ -243,7 +243,7 @@ services or traces and logging data:
 - `event.dataset` enables {observability-guide}/inspect-log-anomalies.html[log
   rate anomaly detection] in the Elastic Observability app.
 
-For example, running https://github.com/elastic/ecs-logging-nodejs/blob/main/loggers/winston/examples/http-with-elastic-apm.js[examples/http-with-elastic-apm.js] and `curl -i localhost:3000/` results in a log record with the following:
+For example, running https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-winston-format/examples/http-with-elastic-apm.js[examples/http-with-elastic-apm.js] and `curl -i localhost:3000/` results in a log record with the following:
 
 [source,cmd]
 ----

package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@elastic/ecs-logging-nodejs",
+  "workspaces": [
+    "packages/*"
+  ],
+  "license": "Apache-2.0",
+  "private": true
+}

helpers/README.md → packages/ecs-helpers/README.md

@@ -4,8 +4,8 @@
 
 [![Build Status](https://apm-ci.elastic.co/buildStatus/icon?job=apm-agent-nodejs%2Fecs-logging-nodejs-mbp%2Fmain)](https://apm-ci.elastic.co/job/apm-agent-nodejs/job/ecs-logging-nodejs-mbp/job/main/)  [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](http://standardjs.com/)
 
-A set of helpers for the ECS logging libraries. You should not directly used
-this package, but the [ECS logging libraries](../loggers) instead.
+A set of helpers for the other [ecs-logging-nodejs packages](../). You should
+not directly use this package.
 
 ## Install
 

helpers/package.json → packages/ecs-helpers/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elastic/ecs-helpers",
   "version": "1.1.0",
-  "description": "ECS loggers helpers",
+  "description": "ecs-logging-nodejs helpers",
   "main": "lib/index.js",
   "files": [
     "lib"

helpers/test/basic.test.js → packages/ecs-helpers/test/basic.test.js

@@ -25,7 +25,7 @@ const Ajv = require('ajv').default
 const semver = require('semver')
 const test = require('tap').test
 
-const { ecsLoggingValidate } = require('../../utils/lib/ecs-logging-validate')
+const { ecsLoggingValidate } = require('../../../utils/lib/ecs-logging-validate')
 
 const {
   version,
@@ -40,7 +40,7 @@ const ajv = new Ajv({
   verbose: true
 })
 addFormats(ajv)
-const validate = ajv.compile(require('../../utils/schema.json'))
+const validate = ajv.compile(require('../../../utils/schema.json'))
 
 test('stringify should return a valid ecs json', t => {
   const ecsFields = {

loggers/morgan/package.json → packages/ecs-morgan-format/package.json

@@ -27,7 +27,7 @@
   "bugs": {
     "url": "https://github.com/elastic/ecs-logging-nodejs/issues"
   },
-  "homepage": "https://github.com/elastic/ecs-logging-nodejs/blob/main/loggers/morgan/README.md",
+  "homepage": "https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-morgan-format/README.md",
   "scripts": {
     "lint": "standard",
     "lint:fix": "standard --fix",

loggers/pino/index.js → packages/ecs-pino-format/index.js

@@ -73,8 +73,8 @@ function createEcsPinoOptions (opts) {
   }
 
   let serviceVersion = opts.serviceVersion
+  // istanbul ignore next
   if (serviceVersion == null && apm) {
-    // istanbul ignore next
     serviceVersion = (apm.getServiceVersion
       ? apm.getServiceVersion() // added in elastic-apm-node@...
       : apm._conf.serviceVersion) // fallback to private `_conf`

loggers/pino/package.json → packages/ecs-pino-format/package.json

@@ -28,7 +28,7 @@
   "bugs": {
     "url": "https://github.com/elastic/ecs-logging-nodejs/issues"
   },
-  "homepage": "https://github.com/elastic/ecs-logging-nodejs/blob/main/loggers/pino/README.md",
+  "homepage": "https://github.com/elastic/ecs-logging-nodejs/blob/main/packages/ecs-pino-format/README.md",
   "scripts": {
     "lint": "standard",
     "lint:fix": "standard --fix",