From a25334dde67e99d3b5e2b864b5d9f778316039bd Mon Sep 17 00:00:00 2001 From: Ches Martin Date: Sun, 19 Sep 2021 00:57:36 +0700 Subject: [PATCH 1/3] specs: Clarify trace vs. other_locations in analyzer spec It appears that #20 intended to remove `other_locations` as superseded by `trace`, but it left the old entry (only) in the example JSON object. An expanded section describing `other_locations` was put back in #57, that issue thread asserts that it is still valid and in use by Code Climate's duplication engine. These two fields certainly seem functionally redundant, hence #56. Under assumption that both are used/accepted in implementations of the current version of the spec, this change restores presence of both in the reference but proposes deprecating `other_locations` and hence de-emphasizes its documentation. --- spec/analyzers/SPEC.md | 20 ++------------------ 1 file changed, 2 insertions(+), 18 deletions(-) diff --git a/spec/analyzers/SPEC.md b/spec/analyzers/SPEC.md index f0bc0b7..a2f493c 100644 --- a/spec/analyzers/SPEC.md +++ b/spec/analyzers/SPEC.md @@ -153,6 +153,7 @@ An `issue` represents a single instance of a real or potential code problem, det "categories": ["Complexity"], "location": Location, "other_locations": [Location], + "trace": Trace, "remediation_points": 50000, "severity": Severity, "fingerprint": "abcd1234" @@ -165,6 +166,7 @@ An `issue` represents a single instance of a real or potential code problem, det * `content` -- **Optional**. A markdown snippet describing the issue, including deeper explanations and links to other resources. * `categories` -- **Required**. At least one category indicating the nature of the issue being reported. * `location` -- **Required**. A `Location` object representing the place in the source code where the issue was discovered. +* `other_locations` -- **Optional, deprecated.** Use `trace` instead. * `trace` -- **Optional.** A `Trace` object representing other interesting source code locations related to this issue. * `remediation_points` -- **Optional**. An integer indicating a rough estimate of how long it would take to resolve the reported issue. * `severity` -- **Optional**. A `Severity` string (`info`, `minor`, `major`, `critical`, or `blocker`) describing the potential impact of the issue found. @@ -267,23 +269,6 @@ line of the file. Offsets, however are 0-based. A Position of `{ "offset": 4 }` represents the _fifth_ character in the file. Importantly, the `offset` is from the beginning of the file, not the beginning of a line. Newline characters (and all characters) count when computing an offset. -### Other Locations - -Other locations is an optional array of [Location](#locations) objects: - -```json -"other_locations": [ - { - "path": "foo.rb", - "lines": { "begin": 25, "end": 55 } - }, - { - "path": "bar.rb", - "lines": { "begin": 20, "end": 50 } - } -] -``` - ### Contents Content gives more information about the issue's check, including a description of the issue, how to fix it, and relevant links. They are expressed as a hash with a `body` key. The value of this key should be a [Markdown](http://daringfireball.net/projects/markdown/) document. For example: @@ -320,7 +305,6 @@ An example trace: }], "stacktrace": true } - ``` From 73db926b895135b359a897db12c6837a0c84c0f7 Mon Sep 17 00:00:00 2001 From: Ches Martin Date: Sun, 19 Sep 2021 01:07:22 +0700 Subject: [PATCH 2/3] fixup: Remove other_locations ToC link --- spec/analyzers/SPEC.md | 1 - 1 file changed, 1 deletion(-) diff --git a/spec/analyzers/SPEC.md b/spec/analyzers/SPEC.md index a2f493c..726dc2d 100644 --- a/spec/analyzers/SPEC.md +++ b/spec/analyzers/SPEC.md @@ -29,7 +29,6 @@ We welcome your participation and appreciate your patience as we finalize the pl - [Remediation points](#remediation-points) - [Locations](#locations) - [Positions](#positions) - - [Other Locations](#other-locations) - [Contents](#contents) - [Source code traces](#source-code-traces) - [Packaging](#packaging) From a6ce1badcc1e249502f7e486e7e97b650494e748 Mon Sep 17 00:00:00 2001 From: Ches Martin Date: Sun, 19 Sep 2021 01:16:13 +0700 Subject: [PATCH 3/3] fixup: Retain minimal but technically specific description of other_locations --- spec/analyzers/SPEC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/analyzers/SPEC.md b/spec/analyzers/SPEC.md index 726dc2d..6aec564 100644 --- a/spec/analyzers/SPEC.md +++ b/spec/analyzers/SPEC.md @@ -165,7 +165,7 @@ An `issue` represents a single instance of a real or potential code problem, det * `content` -- **Optional**. A markdown snippet describing the issue, including deeper explanations and links to other resources. * `categories` -- **Required**. At least one category indicating the nature of the issue being reported. * `location` -- **Required**. A `Location` object representing the place in the source code where the issue was discovered. -* `other_locations` -- **Optional, deprecated.** Use `trace` instead. +* `other_locations` -- **Optional, deprecated.** _Use `trace` instead._ Other locations is an optional array of [`Location`](#locations) objects. * `trace` -- **Optional.** A `Trace` object representing other interesting source code locations related to this issue. * `remediation_points` -- **Optional**. An integer indicating a rough estimate of how long it would take to resolve the reported issue. * `severity` -- **Optional**. A `Severity` string (`info`, `minor`, `major`, `critical`, or `blocker`) describing the potential impact of the issue found.