hohn/codeql
1
0
Fork 0
mirror of https://github.com/github/codeql.git synced 2025-12-16 16:53:25 +01:00
Code Issues Packages Projects Releases Wiki Activity

Split up metric information across the doc

Browse Source
This commit is contained in:
Robin Neatherway
2021-07-13 11:25:15 +01:00
parent 2c14c982d8
commit fc38960795
1 changed files with 14 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/query-metadata-style-guide.md
View File

@@ -104,6 +104,7 @@ Note, `@id` properties should be consistent for queries that highlight the same
* alerts (`@kind problem`)
* alerts containing path information (`@kind path-problem`)
* metrics (`@kind metric`)
Alert queries (`@kind problem` or `path-problem`) support two further properties. These are added by GitHub staff after the query has been tested, prior to deployment to LGTM. The following information is for reference:
@@ -123,7 +124,7 @@ The values of `@precision` and `@problem.severity` assigned to a query that is p
## Query tags `@tags`
The `@tags` property is used to define categories that the query relates to. Each query should belong to one (or more, if necessary) of the following four top-level categories:
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:
* `@tags correctness`–for queries that detect incorrect program behavior.
* `@tags maintainability`–for queries that detect patterns that make it harder for developers to make changes to the code.
@@ -139,6 +140,8 @@ There are also more specific `@tags` that can be added. See, the following pages
* [JavaScript queries](https://help.semmle.com/wiki/display/JS/)
* [Python queries](https://help.semmle.com/wiki/display/PYTHON/)
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`.
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:
* Use all lower-case letters, including for acronyms and proper nouns, with no spaces. All characters apart from * and @ are accepted.
@@ -159,14 +162,9 @@ When you tag a query like this, the associated CWE pages from [MITRE.org](http:/
#### Metric/summary `@tags`
Queries with `@kind metric` and the `summary` tag represent metrics or other pieces of summary information. If SARIF output is used, the results of these queries can be found at `run[].properties.metricResults`.
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.
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 integer column ([example for JavaScript](https://github.com/github/codeql/blob/c47d680d65f09a851e41d4edad58ffa7486b5431/java/ql/src/Metrics/Summaries/LinesOfCode.ql)) is assumed by Code Scanning to be the lines of code under the source root present in the database. Each language should have exactly one query of this form.
The `select` clause of a summary metric query must have one of the following result patterns:
- Just a `number`
- This indicates a metric without a specific location in the codebase, for example the total lines of code in a codebase.
- A code `entity` followed by a `number`
- This indicates a metric with a specific location in the codebase, for example the lines of code within a file. The `entity` here must have a valid location in the source code.
## QL area
### Alert messages
@@ -190,3 +188,11 @@ For examples of select clauses and alert messages, see the query source files at
* [Python queries](https://help.semmle.com/wiki/display/PYTHON/)
For further information on query writing, see [CodeQL queries](https://help.semmle.com/QL/learn-ql/ql/writing-queries/writing-queries.html). For more information on learning CodeQL, see [Learning CodeQL](https://help.semmle.com/QL/learn-ql/index.html).
## Metric results
The `select` clause of a summary metric query must have one of the following result patterns:
- Just a `number`
- This indicates a metric without a specific location in the codebase, for example the total lines of code in a codebase.
- A code `entity` followed by a `number`
- This indicates a metric with a specific location in the codebase, for example the lines of code within a file. The `entity` here must have a valid location in the source code.