Feature request: output diff

[maratori]

The current json output for --mode lint is not human-readable. It would be great to be able to print a diff instead of json.

It can be a new --diff flag, or --format json/diff, or --mode diff.

For example, instead of

[
  {
    "path": "separator.in",
    "lines": {
      "start": 4,
      "end": 6
    },
    "message": "These lines are out of order.",
    "fixes": [
      {
        "replacements": [
          {
            "lines": {
              "start": 4,
              "end": 6
            },
            "new_content": "  \"Bar\",\n  \"Baz\",\n  \"Foo\"\n"
          }
        ]
      }
    ]
  },
  {
    "path": "separator.in",
    "lines": {
      "start": 12,
      "end": 16
    },
    "message": "These lines are out of order.",
    "fixes": [
      {
        "replacements": [
          {
            "lines": {
              "start": 12,
              "end": 16
            },
            "new_content": "// Sticky comment\n\"Bar\",\n\"Baz\",\n\"Foo\"\n// Trailing comments\n"
          }
        ]
      }
    ]
  }
]

I'd like to see

--- goldens/separator.in
+++ goldens/separator.in
@@ -1,17 +1,17 @@
 Comma separator:
 static class Foo {
   // keep-sorted-test start
-  "Foo",
+  "Bar",
-  "Bar",
+  "Baz",
-  "Baz"
+  "Foo"
   // keep-sorted-test end
 }
 
 Comma separator with comments:
-// keep-sorted-test start sticky_comments=yes
-"Foo",
+// keep-sorted-test start sticky_comments=yes
 // Sticky comment
 "Bar",
-"Baz"
+"Baz",
+"Foo"
 // Trailing comments
 // keep-sorted-test end

[JeffFaer]

Could you expand more on your use case for this?

I agree that --mode lint isn't that human readable, but I also don't know that I've ever really needed to understand it. I would expect most folks to run --mode fix and rely on their VCS tooling to give them a diff if they were so inclined

[maratori]

All linters and formatters we use run on CI and block merge. All of them, except keep-sorted, produce a clear failure message explaining what's wrong and how to fix it. While --mode fix works well for local development, CI runs in lint-only mode, where a diff-style output would close this gap.

[JeffFaer]

Out of curiosity, what CI tooling are you using? I think this isn't something I've ever run into because I've mostly used pre-commit to run keep-sorted in my external projects, which would end up automatically applying the changes and giving you a diff with --show-diff-on-failure

---

I'm wondering if we might want to actually replace lint mode with diff mode. Diffs are easier for humans to understand, but they're also easy enough for machines to understand. The remaining difference would then be the lint warnings that don't provide suggestions, but I'm sure we could think of some way to represent those in a human and machine understandable format...

[maratori]

We have an in-house CI system. It heavily relies on Bazel, which we use to build and test all projects in a multilanguage monorepo. I created a custom rule to integrate keep-sorted into Bazel. Actually, I've already applied the patch from #112 (Bazel allows doing that without forks).

I think it's not so important, as any CI would benefit from the diff output. However, we can take one more step further and support different formats, as golangci-lint does (junit-xml, teamcity, ...).