Alert suppressions are defined by special QL queries with @kind alert-suppression . You can define a custom alert-suppression query that finds the annotations you need.

Okay - is there documentation on this style of query? From what I can tell, the existing queries select, for example, "lgtm[cpp/windows/drivers/queries/extended-deprecated-apis]" as part of the result they return, which suggests to me that CodeQL internally takes that text and strips it to get the ID "cpp/windows/drivers/queries/extended-deprecated-apis" and matches that to suppress any violations with that query ID.

For our purposes, we would like to have, for example, a query where the ID in the CodeQL query might be "cpp/windows/drivers/queries/extended-deprecated-apis" but we could still suppress it with existing VS-style suppressions, which would use a numerical ID (1234) instead of the new CodeQL text ID.

I don't think there is any documentation for that type of query. The query needs to have @kind alert-suppression and a select with 4 columns:

1. the annotation itself , type Location or any element with a getLocation/hasLocation predicate.
2. the text of the annotation, type string
3. a suppression "instruction" of the form lgtm or lgtm[queryID], type string
4. the target area (or target AST element) affected by the suppression, type Location or any element with a getLocation/hasLocation predicate.

Thanks for the additional detail! I think with this we should be able to construct a suppression query that can take the old format and convert it into a CodeQL-suppression-readable format.

An additional question for you: do you know if this mechanism and syntax are expected to be supported for the foreseeable future, or are there plans in the pipeline to change or deprecate any part of this?

I really appreciate your help in all this.

You're welcome. There are no plans to change or remove this mechanism for now. However, I can't make any promises.