зеркало из https://github.com/github/codeql.git
Docs: Use GitHub links for guides, improve formatting
This commit is contained in:
Marcono1234
Родитель
5bcf810a7c
Коммит
ab90fe18fd
|
|
@ -3,7 +3,7 @@
|
|||
## Introduction
|
||||
|
||||
This document describes how to format the code you contribute to this repository. It covers aspects such as layout, white-space, naming, and documentation. Adhering to consistent standards makes code easier to read and maintain. Of course, these are only guidelines, and can be overridden as the need arises on a case-by-case basis. Where existing code deviates from these guidelines, prefer consistency with the surrounding code.
|
||||
Note, if you use [CodeQL for Visual Studio Code](https://help.semmle.com/codeql/codeql-for-vscode/procedures/about-codeql-for-vscode.html), you can autoformat your query in the editor.
|
||||
Note, if you use [CodeQL for Visual Studio Code](https://codeql.github.com/docs/codeql-for-visual-studio-code/about-codeql-for-visual-studio-code/), you can autoformat your query in the editor.
|
||||
|
||||
Words in *italic* are defined in the [Glossary](#glossary).
|
||||
|
||||
|
|
@ -166,7 +166,7 @@ private predicate foo(Expr e, Expr p) {
|
|||
```
|
||||
|
||||
## Naming
|
||||
1. Use [PascalCase](http://wiki.c2.com/?PascalCase) for:
|
||||
1. Use [PascalCase](https://wiki.c2.com/?PascalCase) for:
|
||||
- `class` names
|
||||
- `module` names
|
||||
- `newtype` names
|
||||
|
|
@ -249,7 +249,7 @@ For more information about documenting the code that you contribute to this repo
|
|||
1. The `and` and `else` keywords *may* be placed on the same line as the closing parenthesis.
|
||||
1. The `and` and `else` keywords *may* be "cuddled": `) else (`
|
||||
1. *Always* qualify *calls* to predicates of the same class with `this`.
|
||||
2. *Prefer* postfix casts `a.(Expr)` to prefix casts `(Expr)a`.
|
||||
1. *Prefer* postfix casts `a.(Expr)` to prefix casts `(Expr)a`.
|
||||
|
||||
### Examples
|
||||
|
||||
|
|
@ -350,16 +350,16 @@ For more information about documenting the code that you contribute to this repo
|
|||
|
||||
| Phrase | Meaning |
|
||||
|-------------|----------|
|
||||
| *[annotation](https://help.semmle.com/QL/ql-handbook/language.html#annotations)* | An additional specifier used to modify a declaration, such as `private`, `override`, `deprecated`, `pragma`, `bindingset`, or `cached`. |
|
||||
| *[annotation](https://codeql.github.com/docs/ql-language-reference/ql-language-specification/#annotations)* | An additional specifier used to modify a declaration, such as `private`, `override`, `deprecated`, `pragma`, `bindingset`, or `cached`. |
|
||||
| *body* | The text inside `{ }`, `( )`, or each section of an `if`-`then`-`else` or `from`-`where`-`select`. |
|
||||
| *binary operator* | An operator with two operands, such as comparison operators, `and`, `or`, `implies`, or arithmetic operators. |
|
||||
| *call* | A *formula* that invokes a predicate, e.g. `this.isStatic()` or `calls(a,b)`. |
|
||||
| *[conjunct](https://help.semmle.com/QL/ql-handbook/language.html#conjunctions)* | A formula that is an operand to an `and`. |
|
||||
| *[conjunct](https://codeql.github.com/docs/ql-language-reference/ql-language-specification/#conjunctions)* | A formula that is an operand to an `and`. |
|
||||
| *declaration* | A class, module, predicate, field or newtype. |
|
||||
| *[disjunct](https://help.semmle.com/QL/ql-handbook/language.html#disjunctions)* | A formula that is an operand to an `or`. |
|
||||
| *[formula](https://help.semmle.com/QL/ql-handbook/language.html#formulas)* | A logical expression, such as `A = B`, a *call*, a *quantifier*, `and`, `or`, `not`, `in` or `instanceof`. |
|
||||
| *[disjunct](https://codeql.github.com/docs/ql-language-reference/ql-language-specification/#disjunctions)* | A formula that is an operand to an `or`. |
|
||||
| *[formula](https://codeql.github.com/docs/ql-language-reference/ql-language-specification/#formulas)* | A logical expression, such as `A = B`, a *call*, a *quantifier*, `and`, `or`, `not`, `in` or `instanceof`. |
|
||||
| *should/should not/avoid/prefer* | Adhere to this rule wherever possible, where it makes sense. |
|
||||
| *may/can* | This is a reasonable alternative, to be used with discretion. |
|
||||
| *must/always/do not* | Always adhere to this rule. |
|
||||
| *[quantifier/aggregation](https://help.semmle.com/QL/ql-handbook/language.html#aggregations)* | `exists`, `count`, `strictcount`, `any`, `forall`, `forex` and so on. |
|
||||
| *[quantifier/aggregation](https://codeql.github.com/docs/ql-language-reference/ql-language-specification/#aggregations)* | `exists`, `count`, `strictcount`, `any`, `forall`, `forex` and so on. |
|
||||
| *variable* | A parameter to a predicate, a field, a from variable, or a variable introduced by a *quantifier* or *aggregation*. |
|
||||
|
|
|
|||
|
|
@ -124,11 +124,12 @@ Certain special predicates should be documented consistently.
|
|||
* The location spans column `startcolumn` of line `startline` to
|
||||
* column `endcolumn` of line `endline` in file `filepath`.
|
||||
* For more information, see
|
||||
* [Locations](https://help.semmle.com/QL/learn-ql/locations.html).
|
||||
* [Locations](https://codeql.github.com/docs/writing-codeql-queries/providing-locations-in-codeql-queries/).
|
||||
*/
|
||||
|
||||
predicate hasLocationInfo(string filepath, int startline, int startcolumn, int endline, int endcolumn) { ... }
|
||||
```
|
||||
|
||||
## QLDoc for classes
|
||||
|
||||
1. Document classes using a noun phrase of the form `A <domain element> that <has property>.`
|
||||
|
|
|
|||
|
|
@ -4,11 +4,12 @@
|
|||
|
||||
When you contribute a new [supported query](supported-queries.md) to this repository, or add a custom query for analysis in LGTM, you should also write a query help file. This file provides detailed information about the purpose and use of the query, which is available to users in LGTM (for example [here](https://lgtm.com/rules/1506093386171/)) and on the query homepages:
|
||||
|
||||
* [C/C++ queries](https://help.semmle.com/wiki/display/CCPPOBJ/)
|
||||
* [C# queries](https://help.semmle.com/wiki/display/CSHARP/)
|
||||
* [Java queries](https://help.semmle.com/wiki/display/JAVA/)
|
||||
* [JavaScript queries](https://help.semmle.com/wiki/display/JS/)
|
||||
* [Python queries](https://help.semmle.com/wiki/display/PYTHON/)
|
||||
* [C/C++ queries](https://codeql.github.com/codeql-query-help/cpp/)
|
||||
* [C# queries](https://codeql.github.com/codeql-query-help/csharp/)
|
||||
* [Go queries](https://codeql.github.com/codeql-query-help/go/)
|
||||
* [Java queries](https://codeql.github.com/codeql-query-help/java/)
|
||||
* [JavaScript queries](https://codeql.github.com/codeql-query-help/javascript/)
|
||||
* [Python queries](https://codeql.github.com/codeql-query-help/python/)
|
||||
|
||||
### Location and file name
|
||||
|
||||
|
|
@ -18,57 +19,57 @@ Query help files must have the same base name as the query they describe and mus
|
|||
|
||||
Query help files are written using a custom XML format, and stored in a file with a `.qhelp` extension. The basic structure is as follows:
|
||||
|
||||
```
|
||||
```xml
|
||||
<!DOCTYPE qhelp SYSTEM "qhelp.dtd">
|
||||
<qhelp>
|
||||
CONTAINS one or more section-level elements
|
||||
</qhelp>
|
||||
```
|
||||
|
||||
The header and single top-level `<qhelp>` element are both mandatory.
|
||||
The header and single top-level `<qhelp>` element are both mandatory.
|
||||
|
||||
### Section-level elements
|
||||
|
||||
Section-level elements are used to group the information within the query help file. All query help files should include at least the following section elements, in the order specified:
|
||||
|
||||
1. `overview`—a short summary of the issue that the query identifies, including an explanation of how it could affect the behavior of the program.
|
||||
2. `recommendation`—information on how to fix the issue highlighted by the query.
|
||||
3. `example`—an example of code showing the problem. Where possible, this section should also include a solution to the issue.
|
||||
4. `references`—relevant references, such as authoritative sources on language semantics and best practice.
|
||||
1. `overview`—a short summary of the issue that the query identifies, including an explanation of how it could affect the behavior of the program.
|
||||
2. `recommendation`—information on how to fix the issue highlighted by the query.
|
||||
3. `example`—an example of code showing the problem. Where possible, this section should also include a solution to the issue.
|
||||
4. `references`—relevant references, such as authoritative sources on language semantics and best practice.
|
||||
|
||||
For further information about the other section-level, block, list and table elements supported by query help files, see [Query help files](https://help.semmle.com/QL/learn-ql/ql/writing-queries/query-help.html) on help.semmle.com.
|
||||
For further information about the other section-level, block, list and table elements supported by query help files, see [Query help files](https://codeql.github.com/docs/writing-codeql-queries/query-help-files/) on codeql.github.com.
|
||||
|
||||
|
||||
## English style
|
||||
|
||||
You should write the overview and recommendation elements in simple English that is easy to follow. You should:
|
||||
|
||||
* Use simple sentence structures and avoid complex or academic language.
|
||||
* Avoid colloquialisms and contractions.
|
||||
* Use US English spelling throughout.
|
||||
* Use words that are in common usage.
|
||||
* Use simple sentence structures and avoid complex or academic language.
|
||||
* Avoid colloquialisms and contractions.
|
||||
* Use US English spelling throughout.
|
||||
* Use words that are in common usage.
|
||||
|
||||
## Code examples
|
||||
|
||||
Whenever possible, you should include a code example that helps to explain the issue you are highlighting. Any code examples that you include should adhere to the following guidelines:
|
||||
|
||||
* The example should be less than 20 lines, but it should still clearly illustrate the issue that the query identifies. If appropriate, then the example may also be runnable.
|
||||
* Put the code example after the recommendation element where possible. Only include an example in the description element if absolutely necessary.
|
||||
* If you are using an example to illustrate the solution to a problem, and the change required is minor, avoid repeating the whole example. It is preferable to either describe the change required or to include a smaller snippet of the corrected code.
|
||||
* Clearly indicate which of the samples is an example of bad coding practice and which is recommended practice.
|
||||
* Define the code examples in `src` files. The language is inferred from the file extension:
|
||||
* The example should be less than 20 lines, but it should still clearly illustrate the issue that the query identifies. If appropriate, then the example may also be runnable.
|
||||
* Put the code example after the recommendation element where possible. Only include an example in the description element if absolutely necessary.
|
||||
* If you are using an example to illustrate the solution to a problem, and the change required is minor, avoid repeating the whole example. It is preferable to either describe the change required or to include a smaller snippet of the corrected code.
|
||||
* Clearly indicate which of the samples is an example of bad coding practice and which is recommended practice.
|
||||
* Define the code examples in `src` files. The language is inferred from the file extension:
|
||||
|
||||
```
|
||||
<example>
|
||||
<p>This example highlights poor coding practice</p>
|
||||
```xml
|
||||
<example>
|
||||
<p>This example highlights poor coding practice</p>
|
||||
|
||||
<sample src = "example-code-bad.java" />
|
||||
<sample src = "example-code-bad.java" />
|
||||
|
||||
<p>This example shows how to fix the code</p>
|
||||
<p>This example shows how to fix the code</p>
|
||||
|
||||
<sample src = "example-code-fixed.java" />
|
||||
</example>
|
||||
```
|
||||
<sample src = "example-code-fixed.java" />
|
||||
</example>
|
||||
```
|
||||
|
||||
Note, if any code words are included in the `overview` and `recommendation` sections, they should be formatted with `<code> ... </code>` for emphasis.
|
||||
|
||||
|
|
@ -90,7 +91,7 @@ Note, & symbols need to be replaced by \&. The symbol will be displayed corr
|
|||
|
||||
### Academic papers
|
||||
|
||||
If you are citing an academic paper, we recommend adopting the reference style of the journal that you are citing. For example:
|
||||
If you are citing an academic paper, we recommend adopting the reference style of the journal that you are citing. For example:
|
||||
|
||||
>S. R. Chidamber and C. F. Kemerer, _A metrics suite for object-oriented design_. IEEE Transactions on Software Engineering, 20(6):476-493, 1994.
|
||||
|
||||
|
|
@ -109,11 +110,11 @@ For example:
|
|||
|
||||
If your query checks code for a CWE weakness, you should use the `@tags` element in the query file to reference the associated CWEs, as explained [here](query-metadata-style-guide.md). When you use these tags, a link to the appropriate entry from the [MITRE.org](https://cwe.mitre.org/scoring/index.html) site will automatically appear as a reference in the output HTML file.
|
||||
|
||||
## Query help example
|
||||
## Query help example
|
||||
|
||||
The following example is a query help file for a query from the standard query suite for Java:
|
||||
The following example is a query help file for a query from the standard query suite for Java:
|
||||
|
||||
```
|
||||
```xml
|
||||
<!DOCTYPE qhelp PUBLIC
|
||||
"-//Semmle//qhelp//EN"
|
||||
"qhelp.dtd">
|
||||
|
|
|
|||
|
|
@ -8,27 +8,27 @@ This document outlines the structure of CodeQL query files. You should adopt thi
|
|||
|
||||
Query files have the extension `.ql`. Each file has two distinct areas:
|
||||
|
||||
* Metadata area–displayed at the top of the file, contains the metadata that defines how results for the query are interpreted and gives a brief description of the purpose of the query.
|
||||
* Query definition–defined using QL. The query includes a select statement, which defines the content and format of the results. For further information about writing QL, see the following topics:
|
||||
* [Learning CodeQL](https://help.semmle.com/QL/learn-ql/index.html)
|
||||
* [QL language reference](https://help.semmle.com/QL/ql-handbook/index.html)
|
||||
* [CodeQL style guide](https://github.com/github/codeql/blob/main/docs/ql-style-guide.md)
|
||||
* Metadata area–displayed at the top of the file, contains the metadata that defines how results for the query are interpreted and gives a brief description of the purpose of the query.
|
||||
* Query definition–defined using QL. The query includes a select statement, which defines the content and format of the results. For further information about writing QL, see the following topics:
|
||||
* [CodeQL documentation](https://codeql.github.com/docs/)
|
||||
* [QL language reference](https://codeql.github.com/docs/ql-language-reference/)
|
||||
* [CodeQL style guide](ql-style-guide.md)
|
||||
|
||||
|
||||
For examples of query files for the languages supported by CodeQL, visit the following links:
|
||||
For examples of query files for the languages supported by CodeQL, visit the following links:
|
||||
|
||||
* [C/C++ queries](https://help.semmle.com/wiki/display/CCPPOBJ/)
|
||||
* [C# queries](https://help.semmle.com/wiki/display/CSHARP/)
|
||||
* [Go queries](https://help.semmle.com/wiki/display/GO/)
|
||||
* [Java queries](https://help.semmle.com/wiki/display/JAVA/)
|
||||
* [JavaScript queries](https://help.semmle.com/wiki/display/JS/)
|
||||
* [Python queries](https://help.semmle.com/wiki/display/PYTHON/)
|
||||
* [C/C++ queries](https://codeql.github.com/codeql-query-help/cpp/)
|
||||
* [C# queries](https://codeql.github.com/codeql-query-help/csharp/)
|
||||
* [Go queries](https://codeql.github.com/codeql-query-help/go/)
|
||||
* [Java queries](https://codeql.github.com/codeql-query-help/java/)
|
||||
* [JavaScript queries](https://codeql.github.com/codeql-query-help/javascript/)
|
||||
* [Python queries](https://codeql.github.com/codeql-query-help/python/)
|
||||
|
||||
## Metadata area
|
||||
|
||||
Query file metadata contains important information that defines the identifier and purpose of the query. The metadata is included as the content of a valid [QLDoc](https://codeql.github.com/docs/ql-language-reference/ql-language-specification/#qldoc) comment, on lines with leading whitespace followed by `*`, between an initial `/**` and a trailing `*/`. For example:
|
||||
|
||||
```
|
||||
```ql
|
||||
/**
|
||||
* @name Useless assignment to local variable
|
||||
* @description An assignment to a local variable that is not used later on, or whose value is always
|
||||
|
|
@ -42,7 +42,7 @@ Query file metadata contains important information that defines the identifier a
|
|||
*/
|
||||
```
|
||||
|
||||
To help others use your query, and to ensure that the query works correctly on LGTM, you should include all of the required information outlined below in the metadata, and as much of the optional information as possible. For further information on query metadata see [Metadata for CodeQL queries](https://help.semmle.com/QL/learn-ql/ql/writing-queries/query-metadata.html) on help.semmle.com.
|
||||
To help others use your query, and to ensure that the query works correctly on LGTM, you should include all of the required information outlined below in the metadata, and as much of the optional information as possible. For further information on query metadata see [Metadata for CodeQL queries](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/) on codeql.github.com.
|
||||
|
||||
|
||||
|
||||
|
|
@ -51,10 +51,10 @@ To help others use your query, and to ensure that the query works correctly on L
|
|||
|
||||
You must specify an `@name` property for your query. This property defines the display name for the query. Query names should use sentence capitalization, but not include a full stop. For example:
|
||||
|
||||
* `@name Access to variable in enclosing class`
|
||||
* `@name Array argument size mismatch`
|
||||
* `@name Reference equality test on strings`
|
||||
* `@name Return statement outside function`
|
||||
* `@name Access to variable in enclosing class`
|
||||
* `@name Array argument size mismatch`
|
||||
* `@name Reference equality test on strings`
|
||||
* `@name Return statement outside function`
|
||||
|
||||
|
||||
### Query descriptions `@description`
|
||||
|
|
@ -62,38 +62,38 @@ You must specify an `@name` property for your query. This property defines the d
|
|||
You must define an `@description` property for your query. This property defines a short help message. Query descriptions should be written as a sentence or short-paragraph of plain prose, with sentence capitalization and full stop. The preferred pattern for alert queries is "Syntax X causes behavior Y." Any code elements included in the description should be enclosed in single quotes. For example:
|
||||
|
||||
|
||||
* `@description Using a format string with an incorrect format causes a 'System.FormatException'.`
|
||||
* `@description Commented-out code makes the remaining code more difficult to read.`
|
||||
* `@description Using a format string with an incorrect format causes a 'System.FormatException'.`
|
||||
* `@description Commented-out code makes the remaining code more difficult to read.`
|
||||
|
||||
### Query ID `@id`
|
||||
|
||||
You must specify an `@id` property for your query. It must be unique and should follow the standard CodeQL convention. That is, it should begin with the 'language code' for the language that the query analyzes followed by a forward slash. The following language codes are supported:
|
||||
|
||||
* C and C++: `cpp`
|
||||
* C#: `cs`
|
||||
* Go: `go`
|
||||
* Java: `java`
|
||||
* JavaScript and TypeScript: `js`
|
||||
* Python: `py`
|
||||
* C and C++: `cpp`
|
||||
* C#: `cs`
|
||||
* Go: `go`
|
||||
* Java: `java`
|
||||
* JavaScript and TypeScript: `js`
|
||||
* Python: `py`
|
||||
|
||||
The `@id` should consist of a short noun phrase that identifies the issue that the query highlights. For example:
|
||||
|
||||
|
||||
|
||||
* `@id cs/command-line-injection`
|
||||
* `@id java/string-concatenation-in-loop`
|
||||
* `@id cs/command-line-injection`
|
||||
* `@id java/string-concatenation-in-loop`
|
||||
|
||||
Further terms can be added to the `@id` to group queries that, for example, highlight similar issues or are of particular relevance to a certain framework. For example:
|
||||
|
||||
* `@id js/angular-js/missing-explicit-injection`
|
||||
* `@id js/angular-js/duplicate-dependency`
|
||||
* `@id js/angular-js/missing-explicit-injection`
|
||||
* `@id js/angular-js/duplicate-dependency`
|
||||
|
||||
Note, `@id` properties should be consistent for queries that highlight the same issue for different languages. For example, the following queries identify format strings that contain unsanitized input in Java and C++ code respectively:
|
||||
|
||||
|
||||
|
||||
* `@id java/tainted-format-string`
|
||||
* `@id cpp/tainted-format-string`
|
||||
* `@id java/tainted-format-string`
|
||||
* `@id cpp/tainted-format-string`
|
||||
|
||||
|
||||
### Query type `@kind`
|
||||
|
|
@ -102,48 +102,48 @@ Note, `@id` properties should be consistent for queries that highlight the same
|
|||
|
||||
|
||||
|
||||
* alerts (`@kind problem`)
|
||||
* alerts containing path information (`@kind path-problem`)
|
||||
* alerts (`@kind problem`)
|
||||
* alerts containing path information (`@kind path-problem`)
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
* `@precision`–broadly indicates the proportion of query results that are true positives, while also considering their context and relevance:
|
||||
* `low `
|
||||
* `medium `
|
||||
* `high `
|
||||
* `very-high`
|
||||
* `@problem.severity`–defines the level of severity of the alert:
|
||||
* `error`–an issue that is likely to cause incorrect program behavior, for example a crash or vulnerability.
|
||||
* `warning`–an issue that indicates a potential problem in the code, or makes the code fragile if another (unrelated) part of code is changed.
|
||||
* `recommendation`–an issue where the code behaves correctly, but it could be improved.
|
||||
* `@precision`–broadly indicates the proportion of query results that are true positives, while also considering their context and relevance:
|
||||
* `low`
|
||||
* `medium`
|
||||
* `high`
|
||||
* `very-high`
|
||||
* `@problem.severity`–defines the level of severity of the alert:
|
||||
* `error`–an issue that is likely to cause incorrect program behavior, for example a crash or vulnerability.
|
||||
* `warning`–an issue that indicates a potential problem in the code, or makes the code fragile if another (unrelated) part of code is changed.
|
||||
* `recommendation`–an issue where the code behaves correctly, but it could be improved.
|
||||
|
||||
The values of `@precision` and `@problem.severity` assigned to a query that is part of the standard set determine how the results are displayed by LGTM. See [About alerts](https://help.semmle.com/lgtm-enterprise/user/help/about-alerts.html) and [Alert interest](https://lgtm.com/help/lgtm/alert-interest) for further information. For information about using custom queries in LGTM on a 'per-project' basis, see [Writing custom queries to include in LGTM analysis](https://lgtm.com/help/lgtm/writing-custom-queries) and [About adding custom queries](https://help.semmle.com/lgtm-enterprise/admin/help/about-adding-custom-queries.html).
|
||||
The values of `@precision` and `@problem.severity` assigned to a query that is part of the standard set determine how the results are displayed by LGTM. See [About alerts](https://help.semmle.com/lgtm-enterprise/user/help/about-alerts.html) and [Alert interest](https://lgtm.com/help/lgtm/alert-interest) for further information. For information about using custom queries in LGTM on a 'per-project' basis, see [Writing custom queries to include in LGTM analysis](https://lgtm.com/help/lgtm/writing-custom-queries) and [About adding custom queries](https://help.semmle.com/lgtm-enterprise/admin/help/about-adding-custom-queries.html).
|
||||
|
||||
## 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:
|
||||
|
||||
* `@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.
|
||||
* `@tags readability`–for queries that detect confusing patterns that make it harder for developers to read the code.
|
||||
* `@tags security`–for queries that detect security weaknesses. See below for further information.
|
||||
* `@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.
|
||||
* `@tags readability`–for queries that detect confusing patterns that make it harder for developers to read the code.
|
||||
* `@tags security`–for queries that detect security weaknesses. See below for further information.
|
||||
|
||||
There are also more specific `@tags` that can be added. See, the following pages for examples of the low-level tags:
|
||||
|
||||
* [C/C++ queries](https://help.semmle.com/wiki/display/CCPPOBJ/)
|
||||
* [C# queries](https://help.semmle.com/wiki/display/CSHARP/)
|
||||
* [Go queries](https://help.semmle.com/wiki/display/GO/)
|
||||
* [Java queries](https://help.semmle.com/wiki/display/JAVA/)
|
||||
* [JavaScript queries](https://help.semmle.com/wiki/display/JS/)
|
||||
* [Python queries](https://help.semmle.com/wiki/display/PYTHON/)
|
||||
* [C/C++ queries](https://codeql.github.com/codeql-query-help/cpp/)
|
||||
* [C# queries](https://codeql.github.com/codeql-query-help/csharp/)
|
||||
* [Go queries](https://codeql.github.com/codeql-query-help/go/)
|
||||
* [Java queries](https://codeql.github.com/codeql-query-help/java/)
|
||||
* [JavaScript queries](https://codeql.github.com/codeql-query-help/javascript/)
|
||||
* [Python queries](https://codeql.github.com/codeql-query-help/python/)
|
||||
|
||||
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.
|
||||
* 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`.
|
||||
* Use a single-word `@tags` name. Multiple words, separated with hyphens, can be used for clarity if necessary.
|
||||
* Use all lower-case letters, including for acronyms and proper nouns, with no spaces. All characters apart from * and @ are accepted.
|
||||
* 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`.
|
||||
* Use a single-word `@tags` name. Multiple words, separated with hyphens, can be used for clarity if necessary.
|
||||
|
||||
#### Security query `@tags`
|
||||
|
||||
|
|
@ -155,7 +155,7 @@ If your query is a security query, use one or more `@tags` to associate it with
|
|||
||`external/cwe/cwe-036` |
|
||||
||`external/cwe/cwe-073` |
|
||||
|
||||
When you tag a query like this, the associated CWE pages from [MITRE.org](http://cwe.mitre.org/index.html) will automatically appear in the reference section of its associated qhelp file.
|
||||
When you tag a query like this, the associated CWE pages from [MITRE.org](https://cwe.mitre.org/index.html) will automatically appear in the reference section of its associated qhelp file.
|
||||
|
||||
## QL area
|
||||
|
||||
|
|
@ -163,20 +163,20 @@ When you tag a query like this, the associated CWE pages from [MITRE.org](http:/
|
|||
|
||||
The select clause of each alert query defines the alert message that is displayed for each result found by the query. Alert messages are strings that concisely describe the problem that the alert is highlighting and, if possible, also provide some context. For consistency, alert messages should adhere to the following guidelines:
|
||||
|
||||
* Each message should be a complete, standalone sentence. That is, it should be capitalized and have proper punctuation, including a full stop.
|
||||
* The message should factually describe the problem that is being highlighted–it should not contain recommendations about how to fix the problem or value judgements.
|
||||
* Program element references should be in 'single quotes' to distinguish them from ordinary words. Quotes are not needed around substitutions ($@).
|
||||
* Avoid constant alert message strings and include some context, if possible. For example, `The class 'Foo' is duplicated as 'Bar'.` is preferable to `This class is duplicated here.`
|
||||
* Where you reference another program element, link to it if possible using a substitution (`$@`). Links should be used inline in the sentence, rather than as parenthesised lists or appositions.
|
||||
* When a message contains multiple links, construct a sentence that has the most variable link (that is, the link with most targets) last. For further information, see [Defining the results of a query](https://help.semmle.com/QL/learn-ql/ql/writing-queries/select-statement.html).
|
||||
* Each message should be a complete, standalone sentence. That is, it should be capitalized and have proper punctuation, including a full stop.
|
||||
* The message should factually describe the problem that is being highlighted–it should not contain recommendations about how to fix the problem or value judgements.
|
||||
* Program element references should be in 'single quotes' to distinguish them from ordinary words. Quotes are not needed around substitutions (`$@`).
|
||||
* Avoid constant alert message strings and include some context, if possible. For example, `The class 'Foo' is duplicated as 'Bar'.` is preferable to `This class is duplicated here.`
|
||||
* Where you reference another program element, link to it if possible using a substitution (`$@`). Links should be used inline in the sentence, rather than as parenthesised lists or appositions.
|
||||
* When a message contains multiple links, construct a sentence that has the most variable link (that is, the link with most targets) last. For further information, see [Defining the results of a query](https://codeql.github.com/docs/writing-codeql-queries/defining-the-results-of-a-query/).
|
||||
|
||||
For examples of select clauses and alert messages, see the query source files at the following pages:
|
||||
|
||||
* [C/C++ queries](https://help.semmle.com/wiki/display/CCPPOBJ/)
|
||||
* [C# queries](https://help.semmle.com/wiki/display/CSHARP/)
|
||||
* [Go queries](https://help.semmle.com/wiki/display/GO/)
|
||||
* [Java queries](https://help.semmle.com/wiki/display/JAVA/)
|
||||
* [JavaScript queries](https://help.semmle.com/wiki/display/JS/)
|
||||
* [Python queries](https://help.semmle.com/wiki/display/PYTHON/)
|
||||
* [C/C++ queries](https://codeql.github.com/codeql-query-help/cpp/)
|
||||
* [C# queries](https://codeql.github.com/codeql-query-help/csharp/)
|
||||
* [Go queries](https://codeql.github.com/codeql-query-help/go/)
|
||||
* [Java queries](https://codeql.github.com/codeql-query-help/java/)
|
||||
* [JavaScript queries](https://codeql.github.com/codeql-query-help/javascript/)
|
||||
* [Python queries](https://codeql.github.com/codeql-query-help/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).
|
||||
For further information on query writing, see [CodeQL queries](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/). For more information on learning CodeQL, see [CodeQL documentation](https://codeql.github.com/docs/).
|
||||
|
|
|
|||
|
|
@ -27,8 +27,8 @@ The process must begin with the first step and must conclude with the final step
|
|||
|
||||
Add one or more unit tests for the query (and for any library changes you make) to the `ql/<language>/ql/test/experimental` directory. Tests for library changes go into the `library-tests` subdirectory, and tests for queries go into `query-tests` with their relative path mirroring the query's location under `ql/<language>/ql/src/experimental`.
|
||||
|
||||
- See the section on [Testing custom queries](https://help.semmle.com/codeql/codeql-cli/procedures/test-queries.html) in the [CodeQL documentation](https://help.semmle.com/codeql/) for more information.
|
||||
- See [C/C++ CodeQL tests](/cpp/ql/test/README.md) for more information about contributing tests for C/C++ queries in particular.
|
||||
- See the section on [Testing custom queries](https://help.semmle.com/codeql/codeql-cli/procedures/test-queries.html) in the [CodeQL documentation](https://codeql.github.com/docs/) for more information.
|
||||
- See [C/C++ CodeQL tests](/cpp/ql/test/README.md) for more information about contributing tests for C/C++ queries in particular.
|
||||
|
||||
4. **Test for correctness on real-world code**
|
||||
|
||||
|
|
@ -46,10 +46,10 @@ The process must begin with the first step and must conclude with the final step
|
|||
|
||||
QL performance profiling and tuning is an advanced topic, and some tasks will require assistance from GitHub employees. With that said, there are several things you can do.
|
||||
|
||||
- Understand [the evaluation model of QL](https://help.semmle.com/QL/ql-handbook/evaluation.html). It's more similar to SQL than to any mainstream programming language.
|
||||
- Understand [the evaluation model of QL](https://codeql.github.com/docs/ql-language-reference/evaluation-of-ql-programs/). It's more similar to SQL than to any mainstream programming language.
|
||||
- Most performance tuning in QL boils down to computing as few tuples (rows of data) as possible. As a mental model, think of predicate evaluation as enumerating all combinations of parameters that satisfy the predicate body. This includes the implicit parameters `this` and `result`.
|
||||
- The major libraries in CodeQL are _cached_ and will only be computed once for the entire suite of queries. The first query that needs a cached _stage_ will trigger its evaluation. This means that query authors should usually only look at the run time of the last stage of evaluation.
|
||||
- In [the settings for the VSCode extension](https://help.semmle.com/codeql/codeql-for-vscode/reference/settings.html), check the box "Running Queries: Debug" (`codeQL.runningQueries.debug`). Then find "CodeQL Query Server" in the VSCode Output panel (View -> Output) and capture the output when running the query. That output contains timing and tuple counts for all computed predicates.
|
||||
- In [the settings for the VSCode extension](https://codeql.github.com/docs/codeql-for-visual-studio-code/customizing-settings/), check the box "Running Queries: Debug" (`codeQL.runningQueries.debug`). Then find "CodeQL Query Server" in the VSCode Output panel (View -> Output) and capture the output when running the query. That output contains timing and tuple counts for all computed predicates.
|
||||
- To clear the entire cache, invoke "CodeQL: Clear Cache" from the VSCode command palette.
|
||||
|
||||
6. **Make sure your query has the correct metadata**
|
||||
|
|
@ -78,4 +78,4 @@ The process must begin with the first step and must conclude with the final step
|
|||
- The structure of an `experimental` subdirectory mirrors the structure of its parent directory, so this step may just be a matter of removing the `experimental/` prefix of the query and test paths. Be sure to also edit any references to the query path in tests.
|
||||
- Add the query to one of the legacy suite files in `ql/<language>/config/suites/<language>/` if it exists. Note that there are separate suite directories for C and C++, `c` and `cpp` respectively, and the query should be added to one or both as appropriate.
|
||||
- Add a release note to `change-notes/<next-version>/analysis-<language>.md`.
|
||||
- Your pull request will be flagged automatically for a review by the documentation team to ensure that the query help file is ready for wider use.
|
||||
- Your pull request will be flagged automatically for a review by the documentation team to ensure that the query help file is ready for wider use.
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче