Deviations: Switch to new deviations format

Author: lcartey

cpp/common/src/codingstandards/cpp/deviations/CodeIdentifierDeviation.qll

@@ -1,14 +1,24 @@
 /**
- * A module for identifying comment markers in code that trigger deviations.
+ * A module for identifying in code markers in code that trigger deviations.
  *
- * Each comment marker consists of a `code-identifier` with some optional annotations. A deviation will be applied to
+ * This module supports two different code identifier markers:
+ *  - A C/C++ attribute based syntax
+ *  - A comment-based format
+ *
+ * The C/C++ attribute based syntax uses the following format:
+ * ```
+ * [[codeql::<standard>_deviation("code-identifier")]]
+ * ```
+ * The deviation will be applied to the selected program element, and any syntactically nested children of that program element.
+ *
+ * For the comment format the marker consists of a `code-identifier` with some optional annotations. A deviation will be applied to
  * some range of lines in the file containing the comment based on the annotation. The supported marker annotation
  * formats are:
  *  - `<code-identifier>` - the deviation applies to results on the current line.
- *  - `[[codingstandards::deviation(<code-identifier>)]]` - same as above.
- *  - `[[codingstandards::deviation_next_line(<code-identifier>)]]` - this deviation applies to results on the next line.
- *  - `[[codingstandards::deviation_begin(<code-identifier>)]]` - marks the beginning of a range of lines where the deviation applies.
- *  - `[[codingstandards::deviation_end(<code-identifier>)]]` - marks the end of a range of lines where the deviation applies.
+ *  - `codeql::<standard>_deviation(<code-identifier>)` - same as above.
+ *  - `codeql::<standard>_deviation_next_line(<code-identifier>)` - this deviation applies to results on the next line.
+ *  - `codeql::<standard>_deviation_begin(<code-identifier>)` - marks the beginning of a range of lines where the deviation applies.
+ *  - `codeql::<standard>_deviation_end(<code-identifier>)` - marks the end of a range of lines where the deviation applies.
  *
  * The valid `code-identifier`s are specified in deviation records, which also specify the query whose results are
  * suppressed by the deviation.
@@ -23,6 +33,8 @@
 import cpp
 import Deviations
 
+string supportedStandard() { result = ["misra", "autosar", "cert"] }
+
 /**
  * Holds if the given comment contains the code identifier.
  */
@@ -67,7 +79,8 @@ abstract class CommentDeviationMarker extends Comment {
  */
 class DeviationEndOfLineMarker extends CommentDeviationMarker {
   DeviationEndOfLineMarker() {
-    commentMatches(this, "[[codingstandards::deviation(" + record.getCodeIdentifier() + ")]]")
+    commentMatches(this,
+      "codeql::" + supportedStandard() + "_deviation(" + record.getCodeIdentifier() + ")")
   }
 }
 
@@ -77,7 +90,7 @@ class DeviationEndOfLineMarker extends CommentDeviationMarker {
 class DeviationNextLineMarker extends CommentDeviationMarker {
   DeviationNextLineMarker() {
     commentMatches(this,
-      "[[codingstandards::deviation_next_line(" + record.getCodeIdentifier() + ")]]")
+      "codeql::" + supportedStandard() + "_deviation_next_line(" + record.getCodeIdentifier() + ")")
   }
 }
 
@@ -91,7 +104,8 @@ abstract class CommentDeviationRangeMarker extends CommentDeviationMarker { }
  */
 class DeviationBegin extends CommentDeviationRangeMarker {
   DeviationBegin() {
-    commentMatches(this, "[[codingstandards::deviation_begin(" + record.getCodeIdentifier() + ")]]")
+    commentMatches(this,
+      "codeql::" + supportedStandard() + "_deviation_begin(" + record.getCodeIdentifier() + ")")
   }
 }
 
@@ -100,7 +114,8 @@ class DeviationBegin extends CommentDeviationRangeMarker {
  */
 class DeviationEnd extends CommentDeviationRangeMarker {
   DeviationEnd() {
-    commentMatches(this, "[[codingstandards::deviation_end(" + record.getCodeIdentifier() + ")]]")
+    commentMatches(this,
+      "codeql::" + supportedStandard() + "_deviation_end(" + record.getCodeIdentifier() + ")")
   }
 }
 
@@ -184,7 +199,7 @@ class DeviationAttribute extends StdAttribute {
   DeviationRecord record;
 
   DeviationAttribute() {
-    this.hasQualifiedName("codingstandards", "deviation") and
+    this.hasQualifiedName("codeql", supportedStandard() + "_deviation") and
     // Support multiple argument deviations
     "\"" + record.getCodeIdentifier() + "\"" = this.getAnArgument().getValueText()
   }

cpp/common/test/deviations/deviations_basic_test/TypeLongDoubleUsed.expected

@@ -1,7 +1,7 @@
 | attribute_syntax.cpp:6:15:6:17 | dd1 | Use of long double type. |
-| attribute_syntax.cpp:22:15:22:17 | d10 | Use of long double type. |
-| attribute_syntax.cpp:30:15:30:17 | d14 | Use of long double type. |
-| attribute_syntax.cpp:34:20:34:22 | d16 | Use of long double type. |
+| attribute_syntax.cpp:21:15:21:17 | d10 | Use of long double type. |
+| attribute_syntax.cpp:29:15:29:17 | d14 | Use of long double type. |
+| attribute_syntax.cpp:33:20:33:22 | d16 | Use of long double type. |
 | main.cpp:13:15:13:16 | d1 | Use of long double type. |
 | main.cpp:18:15:18:16 | d4 | Use of long double type. |
 | main.cpp:21:15:21:16 | d6 | Use of long double type. |

cpp/common/test/deviations/deviations_basic_test/UnusedReturnValue.expected

@@ -1,10 +1,10 @@
 | attribute_syntax.cpp:5:3:5:6 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
-| attribute_syntax.cpp:17:5:17:8 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
-| attribute_syntax.cpp:19:5:19:8 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
-| attribute_syntax.cpp:25:5:25:8 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
-| attribute_syntax.cpp:27:5:27:8 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
-| attribute_syntax.cpp:31:3:31:6 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
-| attribute_syntax.cpp:42:3:42:6 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
+| attribute_syntax.cpp:16:5:16:8 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
+| attribute_syntax.cpp:18:5:18:8 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
+| attribute_syntax.cpp:24:5:24:8 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
+| attribute_syntax.cpp:26:5:26:8 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
+| attribute_syntax.cpp:30:3:30:6 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
+| attribute_syntax.cpp:41:3:41:6 | call to getZ | Return value from call to $@ is unused. | attribute_syntax.cpp:1:5:1:8 | getZ | getZ |
 | main.cpp:12:3:12:6 | call to getX | Return value from call to $@ is unused. | main.cpp:8:5:8:8 | getX | getX |
 | main.cpp:25:3:25:6 | call to getX | Return value from call to $@ is unused. | main.cpp:8:5:8:8 | getX | getX |
 | main.cpp:27:3:27:6 | call to getX | Return value from call to $@ is unused. | main.cpp:8:5:8:8 | getX | getX |

cpp/common/test/deviations/deviations_basic_test/attribute_syntax.cpp

@@ -5,22 +5,21 @@ int alt() {
   getZ();          // NON_COMPLIANT
   long double dd1; // NON_COMPLIANT (A0-4-2)
 
-  long double [[codingstandards::deviation(
-      "a-0-4-2-deviation")]] dd3;                       // COMPLIANT[DEVIATED]
-  long double [[codingstandards::deviation("a")]] dd3a; // NON_COMPLIAT
+  long double [[codeql::autosar_deviation(
+      "a-0-4-2-deviation")]] dd3; // COMPLIANT[DEVIATED]
 
-  [[codingstandards::deviation(
+  [[codeql::autosar_deviation(
       "a-0-4-2-deviation")]] long double dd4; // COMPLIANT[DEVIATED]
 
-  [[codingstandards::deviation("a-0-4-2-deviation")]] {
+  [[codeql::autosar_deviation("a-0-4-2-deviation")]] {
     long double d7; // COMPLIANT[DEVIATED]
     getZ();         // NON_COMPLIANT (A0-1-2)
     long double d8; // COMPLIANT[DEVIATED]
     getZ();         // NON_COMPLIANT (A0-1-2)
     long double d9; // COMPLIANT[DEVIATED]
   }
   long double d10; // NON_COMPLIANT (A0-4-2)
-  [[codingstandards::deviation("a-0-4-2-deviation")]] {
+  [[codeql::autosar_deviation("a-0-4-2-deviation")]] {
     long double d11; // COMPLIANT[DEVIATED]
     getZ();          // NON_COMPLIANT (A0-1-2)
     long double d12; // COMPLIANT[DEVIATED]
@@ -29,16 +28,18 @@ int alt() {
   }
   long double d14; // NON_COMPLIANT (A0-4-2)
   getZ();          // NON_COMPLIANT (A0-1-2)
-  [[codingstandards::deviation("a-0-4-2-deviation")]]
+  [[codeql::autosar_deviation("a-0-4-2-deviation")]]
   for (long double d15 = 0.0; true;) {} // COMPLIANT[DEVIATED]
   for (long double d16 = 0.0; true;) {  // NON_COMPLIANT (A0-4-2)
   }
   return 0;
 }
 
-[[codingstandards::deviation("a-0-4-2-deviation")]]
+[[codeql::autosar_deviation("a-0-4-2-deviation")]]
 int alt2() {
   int x = 0;       // COMPLIANT[DEVIATED]
   getZ();          // NON_COMPLIANT
   long double dd1; // COMPLIANT[DEVIATED]
+  [[codeql::autosar_deviation(
+      "a-0-4-2-deviation")]] long double dd2; // COMPLIANT[DEVIATED]
 }

cpp/common/test/deviations/deviations_basic_test/main.cpp

@@ -13,28 +13,28 @@ int main(int argc, char **argv) {
   long double d1; // NON_COMPLIANT (A0-4-2)
   long double d2; // a-0-4-2-deviation COMPLIANT[DEVIATED]
 
-  long double d3; // [[codingstandards::deviation(a-0-4-2-deviation)]]
+  long double d3; // codeql::autosar_deviation(a-0-4-2-deviation)
                   // COMPLIANT[DEVIATED]
   long double d4; // NON_COMPLIANT (A0-4-2)
-  // [[codingstandards::deviation_next_line(a-0-4-2-deviation)]]
+  // codeql::autosar_deviation_next_line(a-0-4-2-deviation)
   long double d5; // COMPLIANT[DEVIATED]
   long double d6; // NON_COMPLIANT (A0-4-2)
 
-  // [[codingstandards::deviation_begin(a-0-4-2-deviation)]]
+  // codeql::autosar_deviation_begin(a-0-4-2-deviation)
   long double d7; // COMPLIANT[DEVIATED]
   getX();         // NON_COMPLIANT (A0-1-2)
   long double d8; // COMPLIANT[DEVIATED]
   getX();         // NON_COMPLIANT (A0-1-2)
   long double d9; // COMPLIANT[DEVIATED]
-  // [[codingstandards::deviation_end(a-0-4-2-deviation)]]
+  // codeql::autosar_deviation_end(a-0-4-2-deviation)
   long double d10; // NON_COMPLIANT (A0-4-2)
-  // [[codingstandards::deviation_begin(a-0-4-2-deviation)]]
+  // codeql::autosar_deviation_begin(a-0-4-2-deviation)
   long double d11; // COMPLIANT[DEVIATED]
   getX();          // NON_COMPLIANT (A0-1-2)
   long double d12; // COMPLIANT[DEVIATED]
   getX();          // NON_COMPLIANT (A0-1-2)
   long double d13; // COMPLIANT[DEVIATED]
-  // [[codingstandards::deviation_end(a-0-4-2-deviation)]]
+  // codeql::autosar_deviation_end(a-0-4-2-deviation)
   long double d14; // NON_COMPLIANT (A0-4-2)
   getX();          // NON_COMPLIANT (A0-1-2)
   return 0;

docs/user_manual.md

@@ -426,10 +426,13 @@ The `process_coding_standards_config.py` has a dependency on the package `pyyaml
 A code identifier specified in a deviation record can be applied to certain results in the code by adding a C or C++ attribute of the following format:
 
 ```
-[[codingstandards::deviation("code-identifier")]]
+[[codeql::<standard>_deviation("code-identifier")]]
 ```
 
+For example `[[codeql::misra_deviation("a1-2-4")]]` would apply a deviation of a rule in a MISRA standard, using the code identifier `a1-2-4`. The supported standard names are `misra`, `autosar` and `cert`.
+
 This attribute may be added to the following program elements:
+
  * Functions
  * Statements
  * Variables
@@ -440,7 +443,7 @@ Deviation attributes are inherited from parents in the code structure. For examp
 Multiple code identifiers may be passed in a single attribute to apply multiple deviations, for example:
 
 ```
-[[codingstandards::deviation("code-identifier-1", "code-identifier-2")]]
+[[codeql::misra_deviation("code-identifier-1", "code-identifier-2")]]
 ```
 
 Note - considation should be taken to ensure the use of custom attributes for deviations is compatible with your chosen language version, compiler, compiler configuration and coding standard.
@@ -461,10 +464,10 @@ If you cannot satisfy these condition, please use the deviation code identifier
 As an alternative to attributes, a code identifier specified in a deviation record can be applied to certain results in the code by adding a comment marker consisting of a `code-identifier` with some optional annotations. The supported marker annotation formats are:
 
  - `<code-identifier>` - the deviation applies to results on the current line.
- - `codingstandards::deviation(<code-identifier>)` - the deviation applies to results on the current line.
- - `codingstandards::deviation_next_line(<code-identifier>)` - this deviation applies to results on the next line.
- - `codingstandards::deviation_begin(<code-identifier>)` - marks the beginning of a range of lines where the deviation applies.
- - `codingstandards::deviation_end(<code-identifier>)` - marks the end of a range of lines where the deviation applies.
+ - `codeql::<standard>_deviation(<code-identifier>)` - the deviation applies to results on the current line.
+ - `codeql::<standard>_deviation_next_line(<code-identifier>)` - this deviation applies to results on the next line.
+ - `codeql::<standard>_deviation_begin(<code-identifier>)` - marks the beginning of a range of lines where the deviation applies.
+ - `codeql::<standard>_deviation_end(<code-identifier>)` - marks the end of a range of lines where the deviation applies.
 
 Here are some examples, using the deviation record with the `a-0-4-2-deviation` code-identifier specified above:
 ```cpp
@@ -473,32 +476,32 @@ Here are some examples, using the deviation record with the `a-0-4-2-deviation`
   long double x2; // a-0-4-2-deviation - COMPLIANT
   long double x3; // COMPLIANT - a-0-4-2-deviation
 
-  long double x4; // [[codingstandards::deviation(a-0-4-2-deviation)]] - COMPLIANT
-  long double x5; // COMPLIANT - [[codingstandards::deviation(a-0-4-2-deviation)]]
+  long double x4; // codeql::<standard>_deviation(a-0-4-2-deviation) - COMPLIANT
+  long double x5; // COMPLIANT - codeql::<standard>_deviation(a-0-4-2-deviation)
 
-  // [[codingstandards::deviation_next_line(a-0-4-2-deviation)]]
+  // codeql::<standard>_deviation_next_line(a-0-4-2-deviation)
   long double x6; // COMPLIANT
 
-  // [[codingstandards::deviation_begin(a-0-4-2-deviation)]]
+  // codeql::<standard>_deviation_begin(a-0-4-2-deviation)
   long double x7; // COMPLIANT
-  // [[codingstandards::deviation_end(a-0-4-2-deviation)]]
+  // codeql::<standard>_deviation_end(a-0-4-2-deviation)
 ```
 
-`codingstandards::deviation_end` markers will pair with the closest unmatched `codingstandards::deviation_begin` for the same `code-identifier`. Consider this example:
+`codeql::<standard>_deviation_end` markers will pair with the closest unmatched `codeql::<standard>_deviation_begin` for the same `code-identifier`. Consider this example:
 ```cpp
-1 | // [[codingstandards::deviation_begin(a-0-4-2-deviation)]]
+1 | // codeql::<standard>_deviation_begin(a-0-4-2-deviation)
 2 |
-3 | // [[codingstandards::deviation_begin(a-0-4-2-deviation)]]
+3 | // codeql::<standard>_deviation_begin(a-0-4-2-deviation)
 4 |
-5 | // [[codingstandards::deviation_end(a-0-4-2-deviation)]]
+5 | // codeql::<standard>_deviation_end(a-0-4-2-deviation)
 6 |
-7 | // [[codingstandards::deviation_end(a-0-4-2-deviation)]]
+7 | // codeql::<standard>_deviation_end(a-0-4-2-deviation)
 ```
 Here, Line 1 will pair with Line 7, and Line 3 will pair with Line 8.
 
-A `codingstandards::deviation_end` without a matching `codingstandards::deviation_begin`, or `codingstandards::deviation_begin` without a matching `codingstandards::deviation_end` is invalid and will be ignored.
+A `codeql::<standard>_deviation_end` without a matching `codeql::<standard>_deviation_begin`, or `codeql::<standard>_deviation_begin` without a matching `codeql::<standard>_deviation_end` is invalid and will be ignored.
 
-`codingstandards::deviation_begin` and `codingstandards::deviation_end` markers only apply within a single file. Markers cannot be paired across files, and deviations do not apply to included files.
+`codeql::<standard>_deviation_begin` and `ccodeql::<standard>_deviation_end` markers only apply within a single file. Markers cannot be paired across files, and deviations do not apply to included files.
 
 Note: deviation markers cannot be applied to the body of a macro. Please apply the deviation to macro expansion, or use the attribute deviation format.