feat(laverna): create laverna

[boneskull]

Laverna

Publish multiple workspaces (that's all)

If you're familiar with lerna, Laverna does this: lerna publish from-package.

If you're unfamiliar with it: Laverna publishes all workspaces that haven't yet been published.

Features

Laverna is a thin wrapper around npm publish which:

• Invokes npm publish for all workspaces that haven't yet been published
• Handles new packages (via a flag)
• Ignores private packages
• Requires a confirmation (by default)
• Provides a "dry-run" mode
• Prints all output from npm publish, including the output of npm pack, to enable review

Non-Features

Perhaps more importantly, Laverna:

• Builds nothing
• Bumps no versions
• Does not write to package.json
• Does not interact with git (no tags, no commits, no pushes)
• Does not interact with GitHub (no releases)
• Does not cache anything

Supported Environments

• Node.js v18.13.0+
• npm v8.19.3+

Install

It's recommended to install as a dev dependency:

npm install @lavamoat/laverna -D

Usage Summary

laverna [options..]

Publish multiple workspaces (that's all)

Options:

 --dryRun        - Enable dry-run mode
 --root=<path>   - Path to workspace root (default: current working dir)
 --newPkg=<name> - Workspace <name> has never been published (repeatable)
 --yes/-y        - Skip confirmation prompt

Problems? Visit https://github.com/LavaMoat/lavamoat/issues

Examples

Using Release Please or Similar

For a typical release workflow, you might:

1. Bump workspace versions (e.g. via release-please-action)
2. In your updated working copy's workspace root, run npm exec laverna (or npm exec laverna -- --dry-run first)
3. Bask in glory

Publishing a New Package

If you're publishing a package in a new workspace, you might:

1. Set the initial version of the new package (call it foo) in its package.json.
2. Run npm exec laverna -- --newPkg=foo (or npm exec laverna -- --newPkg=foo --dry-run first)
3. Profit

Automating Publishes

You'll need to figure out how to add --newPkg to your CI/CD pipeline. Otherwise, use the --yes flag when invoking laverna.

API

Laverna provides a programmable JavaScript API (for what it's worth).

Refer to the TypeScript definitions for details.

Notes

LavaMoat needed something that did this, but didn't need Lerna for anything else. So, here we are.

License

Copyright © 2023 Consensys, Inc. Licensed MIT

[boneskull]

Current dependencies on/for this PR:

• chore: use laverna for releasing #903
• feat(laverna): create laverna #836 👈
• main

This stack of pull requests is managed by Graphite.

[boneskull]

Note that this requires a minimum version of Node.js v18.13.0. The entire test suite cannot be run in an older version of Node.js. It's probably too painful to exempt testing just this package from the GHA matrix, so I've done this via a dynamic Ava config.

The reasoning is twofold:

1. We should probably not publish new packages which support on an EOL version of Node.js; that's unnecessary tech debt
2. I found myself re-implementing spies/mocks. But node:test exports a mock namespace-like object which provides exactly what I needed.

[boneskull]

Oh, and the reason I'm doing this in the first place is that it's absolutely a thing that other projects will find useful (including my own). So... yes, selfish reasons.

[boneskull]

REVIEWER(S)

This is mostly just a refactored scripts/publish.js which landed in #727. I wrote some more tests and cleaned it up for public consumption.

[boneskull]

@legobeat ping

[boneskull]

@legobeat I think I've got everything here...

[naugtur]

While we still want to avoid breaking older Node.js support for our users, none of us are using it.
We are the users of laverna. It's ok to skip testing it in old Node.js versions.

With the script testing cleanup moved to the other PR, I think this is ready to merge.

[naugtur]

I don't understand this and therefore fear it. I'm a simple man. Please help me understand why we want this here.

[boneskull]

heh, well, I would have explained myself, but it's package.json, so.

hosseinmd/prettier-plugin-jsdoc#226

[naugtur]

prettier went bonkers?

[boneskull]

hmm, changes to this file should not be in this PR. I'll pull that out

[naugtur]

TS errors in tests:

Error: packages/laverna/test/laverna.spec.js(24,44): error TS2694: Namespace '"node:test"' has no exported member 'Mock'.
Error: packages/laverna/test/laverna.spec.js(25,35): error TS2694: Namespace '"node:test"' has no exported member 'Mock'.
Error: packages/laverna/test/laverna.spec.js(419,6): error TS7006: Parameter 'call' implicitly has an 'any' type.
Error: packages/laverna/test/laverna.spec.js(422,16): error TS7006: Parameter 'arg' implicitly has an 'any' type.
Error: packages/laverna/test/laverna.spec.js(506,6): error TS7006: Parameter 'call' implicitly has an 'any' type.
Error: packages/laverna/test/laverna.spec.js(508,21): error TS7006: Parameter 'arg' implicitly has an 'any' type.
Error: packages/laverna/test/laverna.spec.js(530,6): error TS7006: Parameter 'call' implicitly has an 'any' type.
Error: packages/laverna/test/laverna.spec.js(532,21): error TS7006: Parameter 'arg' implicitly has an 'any' type.
Error: packages/laverna/test/laverna.spec.js(693,6): error TS7006: Parameter 'call' implicitly has an 'any' type.
Error: packages/laverna/test/laverna.spec.js(696,16): error TS7006: Parameter 'arg' implicitly has an 'any' type.
Error: packages/laverna/test/laverna.spec.js(756,6): error TS7006: Parameter 'call' implicitly has an 'any' type.
Error: packages/laverna/test/laverna.spec.js(758,21): error TS7006: Parameter 'arg' implicitly has an 'any' type.
Error: packages/laverna/test/laverna.spec.js(788,6): error TS7006: Parameter 'call' implicitly has an 'any' type.
Error: packages/laverna/test/laverna.spec.js(791,16): error TS7006: Parameter 'arg' implicitly has an 'any' type.
Error: Process completed with exit code 2.

This is marked as the change request blocking the merge and also as resolved. Should we consider it done?

.