You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/query-metadata-style-guide.md
+53-23Lines changed: 53 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -125,29 +125,11 @@ Alert queries (`@kind problem` or `path-problem`) support two further properties
125
125
126
126
## Query tags `@tags`
127
127
128
-
The `@tags` property is used to define categories that the query relates to. Each alert query should belong to one (or more, if necessary) of the following four top-level categories:
128
+
The `@tags` property is used to define the high level category of problem that the query relates to. Each alert query should belong to one of the following two top-level categories, with additional sub-categories:
129
129
130
-
*`@tags correctness`–for queries that detect incorrect program behavior.
131
-
*`@tags maintainability`–for queries that detect patterns that make it harder for developers to make changes to the code.
132
-
*`@tags readability`–for queries that detect confusing patterns that make it harder for developers to read the code.
130
+
### High level category `@tags`
133
131
*`@tags security`–for queries that detect security weaknesses. See below for further information.
134
-
135
-
There are also more specific `@tags` that can be added. See, the following pages for examples of the low-level tags:
Metric queries (`@kind metric`) may have the `summary` tag. If SARIF output is used, the results of these queries can be found at `run[].properties.metricResults`.
145
-
146
-
If necessary, you can also define your own low-level tags to categorize the queries specific to your project or organization. When creating your own tags, you should:
147
-
148
-
* Use all lower-case letters, including for acronyms and proper nouns, with no spaces. All characters apart from * and @ are accepted.
149
-
* Use a forward slash / to indicate a hierarchical relationship between tags if necessary. For example, a query with tag `foo/bar` is also interpreted as also having tag `foo`, but not `bar`.
150
-
* Use a single-word `@tags` name. Multiple words, separated with hyphens, can be used for clarity if necessary.
132
+
*`@tags quality`–for queries that detect code quality issues. See below for further information.
151
133
152
134
#### Security query `@tags`
153
135
@@ -164,13 +146,61 @@ When you tag a query like this, the associated CWE pages from [MITRE.org](https:
164
146
> [!NOTE]
165
147
> The automatic addition of CWE reference links works only if the qhelp file already contains a `<references>` section.
166
148
167
-
#### Metric/summary`@tags`
149
+
#### Quality query sub-category`@tags`
168
150
169
-
Code Scanning may use tags to identify queries with specific meanings across languages. Currently, there is only one such tag: `lines-of-code`. The sum of the results for queries with this tag that return a single number column ([example for JavaScript](https://github.com/github/codeql/blob/c47d680d65f09a851e41d4edad58ffa7486b5431/java/ql/src/Metrics/Summaries/LinesOfCode.ql)) is interpreted by Code Scanning as the lines of code under the source root present in the database. Each language should have exactly one query of this form.
151
+
*`@tags maintainability`–for queries that detect patterns that make it harder for developers to make changes to the code.
152
+
*`@tags reliability`–for queries that detect issues that affect whether the code will perform as expected during execution.
170
153
154
+
Software quality doesn't have as universally-agreed categorization method as security issues like CWE, so we will do our own categorization instead of using tags like CWE.
155
+
156
+
We'll use two "top-level" categories of quality queries, with sub-categories beneath:
157
+
158
+
*`@tags maintainability`–for queries that detect patterns that make it harder for developers to make changes to the code.
159
+
*`@tags readability`–for queries that detect confusing patterns that make it harder for developers to read the code.
160
+
*`@tags useless-code`-for queries that detect functions that are never used and other instances of unused code
161
+
*`@tags complexity`-for queries that detect patterns in the code that lead to unnecesary complexity such as unclear control flow, or high cyclomatic complexity
162
+
163
+
164
+
*`@tags reliability`–for queries that detect issues that affect whether the code will perform as expected during execution.
165
+
*`@tags correctness`–for queries that detect incorrect program behavior or couse result in unintended outcomes.
166
+
*`@tags performance`-for queries that detect code that could impact performance through inefficient algorithms, unnecessary computation, etc
167
+
*`@tags concurrency`-for queries that detect concurrency related issues such as race conditions, deadlocks, thread safety, etc
168
+
*`@tags error-handling`-for queries that detect issues related to unsafe error handling such as uncaught exceptions, etc
169
+
170
+
171
+
There are also more specific `@tags` that can be added. See, the following pages for examples of the low-level tags:
Maintainers are expected to add a `@security-severity` tag to security relevant queries that will be run on Code Scanning. There is a documented internal process for generating these `@security-severity` values.
173
186
187
+
We will use the `problem.severity` attribute to handle the severity for quality-related queries.
188
+
189
+
### Metric/summary `@tags`
190
+
191
+
Code Scanning may use tags to identify queries with specific meanings across languages. Currently, there is only one such tag: `lines-of-code`. The sum of the results for queries with this tag that return a single number column ([example for JavaScript](https://github.com/github/codeql/blob/c47d680d65f09a851e41d4edad58ffa7486b5431/java/ql/src/Metrics/Summaries/LinesOfCode.ql)) is interpreted by Code Scanning as the lines of code under the source root present in the database. Each language should have exactly one query of this form.
192
+
193
+
Metric queries (`@kind metric`) may have the `summary` tag. If SARIF output is used, the results of these queries can be found at `run[].properties.metricResults`.
194
+
195
+
196
+
### Customizing tags
197
+
198
+
If necessary, you can also define your own low-level tags to categorize the queries specific to your project or organization, but if possible, please try to follow the above standards (or propose changes to this style guide). When creating your own tags, you should:
199
+
200
+
* Use all lower-case letters, including for acronyms and proper nouns, with no spaces. All characters apart from * and @ are accepted.
201
+
* Use a forward slash / to indicate a hierarchical relationship between tags if necessary. For example, a query with tag `foo/bar` is also interpreted as also having tag `foo`, but not `bar`.
202
+
* Use a single-word `@tags` name. Multiple words, separated with hyphens, can be used for clarity if necessary.
0 commit comments