feat(json): add helper metadata to output

[robinvw1]

Description

Feature request: machine-readable output of affected file paths for fix and format

First of all: @JamieMason this is a great tool!

Problem

When integrating syncpack into a programmatic workflow (e.g. an Nx conformance generator or a CI
script), there's no way to know which package.json files were actually modified after running
syncpack fix or syncpack format - short of doing a full before/after content diff yourself.

The current --dry-run output is human-readable only:

• fix --dry-run reports dependency names and version mismatches, with no file paths.
• format --dry-run reports the package name field (e.g. integration at package.json), not
  the file path — so resolving it back to a path requires a secondary lookup across all
  package.json files.

Proposed solution

Add a --json (or --reporter json) flag to fix and format that emits a structured JSON
summary to stdout, including at minimum the list of file paths that were (or would be, with
--dry-run) written to disk.

Example output:

{
  "changedFiles": [
    "apps/service-a/package.json",
    "libs/shared/package.json"
  ]
}

Usecase

Without this, tools that wrap syncpack must snapshot all package.json contents before running,
then re-read every file from disk afterwards to detect what changed. This is wasteful as syncpack
already has this information internally during execution.

Exposing it via structured output would allow wrappers to skip the before/after diff entirely and
trust syncpack's own change tracking.

Suggested Solution

CLI usage

# Apply fixes and get a JSON summary of what changed
syncpack fix --reporter json

# Preview what would change without writing to disk
syncpack fix --dry-run --reporter json

# Compose with format in one pipeline
syncpack fix --reporter json && syncpack format --reporter json

CLI output

Normal (human-readable) output currently goes to stdout. With --reporter json, stdout becomes machine-parseable and stderr retains any warnings/errors:

syncpack fix --reporter json

{
  "command": "fix",
  "changedFiles": [
    "apps/billing/package.json",
    "apps/invoicing/package.json"
  ],
  "changes": [
    {
      "file": "apps/billing/package.json",
      "dependency": "kleur",
      "from": "4.1.4",
      "to": "4.1.5"
    },
    {
      "file": "apps/invoicing/package.json",
      "dependency": "kleur",
      "from": "4.1.4",
      "to": "4.1.5"
    }
  ]
}

syncpack format --reporter json

{
  "command": "format",
  "changedFiles": [
    "apps/integration/package.json"
  ],
  "changes": [
    {
      "file": "apps/integration/package.json",
      "reason": "PropertyIsNotSortedAz",
      "property": ".dependencies"
    }
  ]
}

syncpack fix --dry-run --reporter json — identical shape, but nothing is written to disk and a dryRun: true flag is included:

{
  "command": "fix",
  "dryRun": true,
  "changedFiles": [
    "apps/billing/package.json"
  ],
  "changes": [...]
}

Config file

A reporter option in .syncpackrc.json sets the default, so CI pipelines don't need to pass the flag every time:

{
  "$schema": "./node_modules/syncpack/schema.json",
  "reporter": "json",
  "sortFirst": ["name", "version", "..."],
  "versionGroups": [...]
}

Multiple reporter targets would also be useful (e.g. human output to stderr, JSON to stdout):

{
  "reporter": ["pretty", "json"]
}

Optional comments

No response

Code of Conduct

• I agree to follow the Code of Conduct

[JamieMason]

Hey @robinvw1, thanks for raising this.

The data output by syncpack json could use some extra properties to help here, because this is way too long, but running...

syncpack json | jq 'select(.statusCode | IN("IsHighestOrLowestSemver", "IsIdenticalToLocal", "IsIdenticalToPin", "IsIdenticalToSnapTarget", "IsIgnored", "IsLocalAndValid", "IsNonSemverButIdentical", "SatisfiesHighestOrLowestSemver", "SatisfiesLocal", "SatisfiesSameMinorGroup", "SatisfiesSameRangeGroup", "SatisfiesSnapTarget") | not)'

...before you run syncpack fix will tell you which files did not have one of the Valid status codes.

It's long and ugly, but reliable.

Notes

• If there are any invalid instances, syncpack json will exit with code 1.
• If there are any unfixable instances remaining, syncpack fix will exit with code 1.

Alternative

This might work, but I'd need to check for edge cases:

syncpack json | jq 'select(.actual.raw != .expected.raw)'

[robinvw1]

Hi Jamie, thanks for the quick response and the syncpack json tip, really appreciated!

We tried it and it works well for fix: instead of snapshotting all package.json files upfront,
you run syncpack json first, parse the NDJSON to find entries where actual.raw !== expected.raw,
and only read those files back from disk after fix runs to detect what changed. In let's say a 200-package
monorepo where fix typically touches 3 files, that's a significant reduction.

However, format is still a problem. Since there's no machine-readable equivalent for formatting
issues, we have to read all N package.json files from disk after format runs and compare them
against the in-memory tree to detect changes. That N-read loop dominates the cost regardless of the
fix improvement.

We also had to introduce an extra syncpack json invocation just to get the fix candidates. It
would be cleaner if fix and format could emit that information themselves. A --reporter json
flag on both commands would cover all of this in one go: each command would output a
machine-readable summary of which files it changed, with no extra pre-flight call needed and no
before/after comparison in userland at all.

[JamieMason]

That all makes sense, I'll leave this issue open to track:

• Helper metadata to make filtering easier
• Expose formatting statuses as JSON
• Allow commands to output as JSON

[JamieMason]

Can you summarise the workflow(s) you're working on that are using these changes?

[robinvw1]

Happy to elaborate the workflow.

We're using syncpack as part of an Nx sync generator.

Sync generators run automatically before nx build, nx test, etc. to ensure the workspace is in a consistent state. Ours runs syncpack fix and syncpack format to keep dependency versions and package.json formatting aligned across all packages in the monorepo.

The generator receives an Nx Tree (an in-memory virtual filesystem), runs both syncpack commands against disk, and then needs to report back which files were modified so Nx can write them back through the tree and prompt the developer to confirm the changes. That's the bit that currently requires the before/after disk comparison, which is wasted compute and could be completely removed if syncpack would report it back in a machine-readable output (e.g. JSON).