Spec inconsistency around trace/location/other_locations (or maybe I'm just confused)

[srenatus]

Issues claims that an example output would look like this:

{
  "type": "issue",
  "check_name": "Bug Risk/Unused Variable",
  "description": "Unused local variable `foo`",
  "content": Content,
  "categories": ["Complexity"],
  "location": Location,
  "other_locations": [Location],  # <<< note that
  "remediation_points": 50000,
  "severity": Severity,
  "fingerprint": "abcd1234"
}

while the text below explains trace (which isn't part of the JSON blob):

trace -- Optional. A Trace object representing other interesting source code locations related to this issue.

Further down we find an explanation of the location key, that's explaining that (I've highlighted what I'm confused about):

Locations refer to ranges of a source code file. A Location contains a path, a source range, (expressed as lines or positions), and an optional array of other_locations.

What is correct, where does other_locations go? 😃

Thanks,
Stephan

[ABaldwinHunter]

Hi Stephan,

Thanks for your question!

The location object usually looks like the examples given here:

• there's always a path
• the source code position can be expressed with begin / end lines, or with line and column positions

{
  "path": "path/to/file.css",
  "lines": {
    "begin": 13,
    "end": 14
  }
}

{
  "path": "path/to/file.css",
  "positions": {
    "begin": {
      "line": 3,
      "column": 10
    },
    "end": {
      "line": 4,
      "column": 12
    }
  }
}

The part you noted about other_locations seems confusing to me - as I think the example output is correct- other_locations should be a top level key (that's optional).

Historically, it's been used with our duplication engine to reference the locations of similar code.

Going to go ahead and open a PR to clarify.

Thanks!

[srenatus]

@ABaldwinHunter Thank you 😃

[ABaldwinHunter]

@srenatus updated documentation in #57.

Thanks for the heads up.

Going to close this issue for now but please feel free to reopen if anything related comes up.