feat(node): add a Node.js API

[Aghassi]

Description

This package is really great, but it would be nice for it to run sort of like a linter in that it should report to you the lines in the package.json that are impacted. This is mostly so that there may be a way to more easily identify which files need editing or updating for a given dependency.

Suggested Solution

For a given scan:

• Return an array of objects
• Each object has a package name
• Each object also has an array of paths that represent the files that are mis aligned
• Each object contains a message with the version that are skewd

Help Needed

At this point I just want to know if you are open to this feature, or if this is not the intent of the tool.

[JamieMason]

Thanks @Aghassi, I'm curious about this idea but I need to know a bit more about what you're trying to do.

It could be that the output from syncpack list-mismatches is too vague and needs improving? Or maybe you're working on some tooling so that's why you mentioned JSON? to drive that?

This sounds interesting but I need a bit more context to get up to speed, thanks a lot David.

[Aghassi]

Sure thing. My current situation is I'm writing a linter for arcanist https://secure.phabricator.com/book/phabricator/article/arcanist/.

The way arcanist is structured, it passes affected files into the linter and each file is linted with actionable information provided back to the user. Each lint message contains the line in the current file as well as the character that the error is located at. Unfortunately, this shape is different from how syncpack runs currently, which is fine. I just want a way to validate and align package.json. Ideally, it would be nice to be able to use list-mismatches to in such a way that given a path (which I can do with --source today) it returns a payload that has the line number of the affected package in the current package.json. That would be step one so that it's easier for users to know where in a given file there is a mismatched.

Here is an example of how I'm currently formatting the output for Arcanist

      // Create an array of errors splitting on a character syncpack provides
      $errors = explode("✕", $stdout);

      // For each error, create an error message
      foreach ($errors as $error) {
        // Report the error for each package
        $message = new ArcanistLintMessage();
        $message->setPath($path);
        $message->setName('package.json Alignment Check');
        $message->setCode($this->getLinterName());
        $message->setDescription("Error, package mismatch found: \nx $error");
        $message->setSeverity(ArcanistLintSeverity::SEVERITY_ERROR);
        $messages[] = $message;
      }
      // Return the array of errors to be presented individually
      return $messages;

In terms of "why json", I just like JSON. No reason in particular.

[JamieMason]

The library code and the CLI are separate in syncpack, so you could use it as a node module. It would be a small job to add a main entry and to make a nice API you can import from the root of the package.

A little refactoring would be needed plus it's not a nice DX right now, but you can access the core functionality like so:

const { list } = require('syncpack/dist/commands/list')

You can see the code for the CLI and Library portions of the list command as an example.

To make this more useful as a library some changes would be needed, eg. the list() function would need modifying to return an array of messages instead of writing to the console etc, but they're not huge refactors.

Let me know if something like this would work for you.

[Aghassi]

I'm currently just returning from a vacation, but I'd be happy to look at this. It sounds promising!

[JamieMason]

The refactoring is now done, this feature shouldn't be too far off now.

[pastelsky]

Hi, I see that the PR for this was declined. Is there still a plan to expose a Node API for this?

[JamieMason]

Hey @pastelsky, eventually that would be nice but for now I have closed it because:

1. The internals of syncpack have had huge changes, multiple times, to support new feature requests that have come in (this is the main reason). So I want to wait for things to have settled for a while before exposing this.
2. I don't have any good use cases from anyone for what they would want and what they would use it for, nothing concrete, so it's not clear yet who would use it, what for, and what best to give them to help them do whatever that is.

So I would say Shubham that this is on a medium to long term pause, but not dead 👍🏻

EDIT: hey, you made bundlephobia.com 👏🏻 I use it all the time

[duytan-hoang-eurostar]

Hi @JamieMason, is an Node API still in the backlog?

I have a rather unconventional use case where I want to be able to (temporarily) set dependency package versions to * when any dependent package/s have changed version. This is only when a PR is raised (which triggers an alpha release of that package) to be tested. Once tested and all is fine, all * versions will then be updated to the exact latest version upon merging to master.

I'm aware this doesn't fully follow the goal of syncpack, which is why an exposed API where I utilise the list-mismatches to get the affected packages would be great.

So the workflow I'm looking to achieve is (monorepo project):

• Update package-a version
• package-a is a dep in packages:
  • package-b
  • package-d
• Use list-mismatches and change package-a version in package-b and package-d to *
• package-b and package-d versions will then be semver patched
• Upon raising a PR from the monorepo of the above changes, alpha releases will be made for package-a, package-b and package-d
• Consumer app (outside of the monorepo) can then test these changes by installing all of these alpha releases
  • Ensures there are no multiple versions of package-a, package-b and package-d installed on the consumer app
• Once all tested and ready to be merged (from the monorepo)
  • Run fix-mismatches to replace the * versions to the exact latest versions
  • Run at some point (e.g. merge queue or merge to master)