Skip to content

Commit 4089866

Browse files
mbaludambaluda
committed
Introduce support for agentic autofix
1 parent 3abe064 commit 4089866

2 files changed

Lines changed: 158 additions & 0 deletions

File tree

‎docs/copilot-instructions.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
[//]: # "Include this file in the repository to provide instructions to GitHub Copilot AUtofix. For more information, see https://docs.github.com/copilot/copilot-for-business/copilot-instructions."
2+
# GitHub Copilot instructions
3+
4+
This file contains repository-wide guidance for GitHub Copilot. Each top-level
5+
section below configures Copilot for a specific use case in this repository.
6+
Add further top-level sections as needed (general coding conventions, review
7+
guidance, etc.).
8+
9+
## Agentic autofix for CodeQL Coding Standards
10+
11+
This section configures GitHub Copilot (in particular, Copilot **agentic
12+
autofix**) when it generates pull requests to remediate alerts produced by the
13+
[CodeQL Coding Standards](https://github.com/github/codeql-coding-standards/)
14+
project. It applies to alerts for any of the supported standards (MISRA C,
15+
MISRA C++, AUTOSAR C++, CERT C, CERT C++).
16+
17+
### 1. Reference material — where to learn each rule
18+
19+
Before proposing a fix, consult the rule’s authoritative implementation as well as the corresponding compliant and non-compliant code patterns available as test cases in the CodeQL Coding Standards [`github/codeql-coding-standards`](https://github.com/github/codeql-coding-standards/)
20+
repository. That repository is the single source of truth for what the query
21+
detects and what compliant code looks like.
22+
23+
Project layout (per language / standard):
24+
25+
```
26+
<language>/<standard>/src/rules/<rule-id>/ # query source (.ql) and rule help (.md, .qhelp)
27+
<language>/<standard>/test/rules/<rule-id>/ # test cases, with COMPLIANT / NON_COMPLIANT markers
28+
```
29+
30+
When generating a fix:
31+
32+
1. Locate the rule directory matching the alert’s rule id / query id.
33+
2. Read the `.md` / `.qhelp` help file in `src/rules/<rule-id>/` to understand
34+
the intent and the recommended remediation.
35+
3. Read the files in `test/rules/<rule-id>/`. Lines (or blocks) annotated with
36+
`// COMPLIANT` show patterns that pass the query; lines annotated with
37+
`// NON_COMPLIANT` show patterns that trigger the query. Use these as the
38+
ground truth for what the fixed code must look like.
39+
40+
The full list of supported rules per standard is published as
41+
`supported_rules_list_<version>.csv` / `.md` in each
42+
[release](https://github.com/github/codeql-coding-standards/releases).
43+
44+
### 2. Fix discipline — keep changes minimal and standards-compliant
45+
46+
- **Minimum diff.** Modify the smallest possible amount of code that
47+
eliminates the alert. Do not refactor surrounding code, rename symbols,
48+
reformat unrelated lines, or change public APIs unless strictly required to
49+
satisfy the rule.
50+
- **No drive-by changes.** Do not add features, fix unrelated warnings, change
51+
build flags, update dependencies, or “improve” code that the alert does not
52+
point at.
53+
- **New code must comply with the same standard.** Any code introduced by the
54+
fix must itself satisfy the coding standard being verified (e.g. MISRA C++
55+
2023). Cross-check the inserted code against the COMPLIANT examples in the
56+
corresponding `test/rules/<rule-id>/` directory and against neighbouring
57+
rules that are obviously relevant (e.g. don’t fix an integer-conversion rule
58+
by introducing a cast that violates a different MISRA rule).
59+
- **Match the project’s existing style.** Follow the conventions visible in
60+
the surrounding source files (naming, headers, namespaces, C++ standard
61+
level, use of `enum class`, etc.).
62+
- **Preserve behaviour.** A coding-standards fix is a refactor at the source
63+
level, not a functional change. The fix must not alter observable runtime
64+
behaviour unless the rule explicitly targets undefined or implementation-
65+
defined behaviour that has to change.
66+
67+
### 3. Do not touch build outputs, generated files, or `.gitignore`
68+
69+
Autofix pull requests must only change source files that are part of the
70+
checked-in project. They must **not** include:
71+
72+
- Build directories or files generated during compilation.
73+
- Editor / IDE state (`.vscode/`, `.idea/`, `.DS_Store`, etc.).
74+
- **`.gitignore` itself.** Do not add, remove, or reorder entries in
75+
`.gitignore` as part of an autofix.
76+
- The CodeQL workflow files under `.github/workflows/` (e.g. `codeql.yml`).
77+
Suppression or scope changes must use the deviation mechanism (see §4),
78+
not workflow edits.
79+
80+
### 4. Deviations — respect project policy and reference it in fixes
81+
82+
A project under analysis may declare that a rule, file, region, or specific
83+
construct is intentionally exempt from a coding standard. Such deviations are
84+
not always expressed through the same mechanism: a project may use the
85+
**standard CodeQL Coding Standards deviation mechanism**, a **custom
86+
annotation or attribute** convention, **in-source line / block comments**,
87+
or a **separate documentation file** (for example a `DEVIATIONS.md`,
88+
`MISRA-deviations.md`, compliance matrix, or similar).
89+
90+
The fix proposal must take what is found into account and treat it as an existing deviation if it clearly covers the alert location and rule.
91+
92+
If the alert location is covered by an existing deviation:
93+
94+
- **Still propose a code fix** that would make the location compliant by
95+
default. Authors may have left the deviation in place pragmatically and
96+
may prefer a real fix.
97+
- **In the pull request description, explicitly state** that a matching
98+
deviation already exists in the project, citing the file path and the
99+
relevant `rule-id` / `query-id` / `permit-id` / `code-identifier` / scope
100+
(paths or markers) so reviewers can decide whether to accept the fix or
101+
keep the deviation.
102+
- Do not silently delete or weaken an existing deviation, permit, or
103+
re-categorization entry as part of the fix.
104+
105+
### 5. False positives — propose a deviation, do not stay silent
106+
107+
Copilot autofix normally refrains from opening a pull request when it
108+
considers an alert to be a false positive. For CodeQL Coding Standards alerts
109+
this behaviour is **overridden**: a false-positive determination must still
110+
result in a pull request, and that pull request must record the decision
111+
using the project’s deviation mechanism.
112+
113+
The CodeQL Coding Standards project supports an explicit deviation mechanism,
114+
fully documented in
115+
[`docs/user_manual.md`](https://github.com/github/codeql-coding-standards/blob/main/docs/user_manual.md)
116+
(sections “Applying deviations”, “Deviation records”, “Deviation permits”,
117+
“Guideline re-categorization plan”).
118+
When an alert is judged to be a false positive, the autofix PR must:
119+
120+
1. **Not modify the flagged code** to “work around” the alert.
121+
2. **Add or update a deviation record** that scopes precisely to the alert.
122+
Prefer the narrowest scope that is appropriate:
123+
- a `code-identifier` deviation referenced from the exact line, statement,
124+
function, or block, via an attribute
125+
(`[[codeql::<standard>_deviation("...")]]`) or a comment marker
126+
(`// codeql::<standard>_deviation(...)`,
127+
`// codeql::<standard>_deviation_next_line(...)`, or a
128+
`..._deviation_begin` / `..._deviation_end` pair); or
129+
- a `paths:`-scoped deviation in `coding-standards.yml` when a whole file
130+
or directory is affected;
131+
- a project-wide deviation only when the rule is genuinely inapplicable to
132+
the project.
133+
Use `<standard>` ∈ {`misra`, `autosar`, `cert`} as appropriate for the
134+
alert.
135+
3. **Populate the deviation record** with at least:
136+
- `rule-id` matching the alert’s rule identifier;
137+
- `query-id` matching the alert’s `@id` (when the deviation is meant to
138+
cover a single sub-query of the rule);
139+
- a clear `justification` explaining why the alert is a false positive
140+
(what the query missed, why the code is in fact compliant or safe);
141+
- `scope`, `background`, and `requirements` when they help a reviewer
142+
audit the decision;
143+
- a `raised-by` entry (and leave `approved-by` for a human reviewer).
144+
4. **Place the deviation entry** in an existing `coding-standards.yml` if one
145+
exists in an appropriate directory; otherwise create one at the most
146+
specific directory whose subtree is affected. When using a `permit-id`,
147+
reference an existing permit if one matches; do not invent new permit IDs
148+
unless necessary.
149+
5. **In the PR description**, explicitly state that the alert is being
150+
handled as a false positive via a deviation (not by code change), link to
151+
the
152+
[deviation mechanism documentation](https://github.com/github/codeql-coding-standards/blob/main/docs/user_manual.md#applying-deviations),
153+
and summarise the justification so a reviewer can approve or reject it.
154+
155+
A false-positive PR should therefore contain **only** the deviation entry
156+
and/or the in-source deviation marker — no changes to logic, no edits to
157+
build outputs, and no edits to `.gitignore`.

‎docs/user_manual.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -646,6 +646,7 @@ The only use cases that will be certified under ISO 26262 are those listed above
646646

647647
- Creating databases and running the CodeQL Coding Standards queries with the [CodeQL Action](https://github.com/github/codeql-action) (for GitHub Actions CI/CD system).
648648
- Uploading the SARIF results files for a CodeQL Coding Standards analysis to the GitHub [Code Scanning](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning) feature.
649+
- Using [Agentic Autofix in Code Scanning](https://docs.github.com/en/code-security/concepts/code-scanning/copilot-autofix-for-code-scanning) (use the reference [copilot-instructions.md](copilot-instructions.md) file provided).
649650

650651
### Hazard and risk analysis
651652

0 commit comments

Comments
 (0)