Add script to add overlay annotations

[kaspersv]

This PR adds a script to automatically add sensible default annotations to files without existing overlay annotations. The script uses naming heuristics to determine which files to annotate. The script adds a module-level overlay[local?] annotation and annotates all non-private inline predicates overlay[caller] for selected files. Maintenance of overlay annotations in already annotated files is not the responsibility of this script and will be handled using QL-for-QL queries. This is intended to allow QL authors to gradually take ownership of overlay annotations and manually add & remove automatically added overlay annotations.

A CI check will be added in a subsequent PR to enforce that the script is run for select languages.

The script is based on @ginsbach's annotation script. However, instead of removing existing overlay annotations, it only annotates files without existing annotations and offloads maintenance of annotated files to QL-for-QL queries.

For https://github.com/github/codeql-core/issues/4951.

[Copilot]

Pull Request Overview

Adds a new Python script to automatically insert default overlay annotations into .qll files that lack them, based on naming and content heuristics.

• Implements add-overlay-annotations.py to add module-level overlay[local?] and inline overlay[caller] annotations.
• Skips files with existing annotations, tests, dataflow configs, or empty content.
• Targets specified languages under <lang>/ql/lib and a shared directory.

Comments suppressed due to low confidence (1)

config/add-overlay-annotations.py:106

• New annotation logic isn't covered by any tests; consider adding unit tests for annotate_as_appropriate, insert_overlay_caller_annotations, and the top-level function to prevent regressions.

def annotate_as_appropriate(filename, lines):

[ginsbach]

I'm happy with this - but it is mostly my own code.
Maybe it would make sense to have a QL developer as additional reviewer. That way, we could already pass on knowledge about this code as a positive side effect.

[kaspersv]

Maybe it would make sense to have a QL developer as additional reviewer. That way, we could already pass on knowledge about this code as a positive side effect.

I have a kickoff meeting with Anders and Asger tomorrow for overlay-aware Java & JS where I will go through the tooling, including this script. I think that is preferable to having them review for now. If they actually end up having to frequently tweak this script to achieve the desired annotations, then I think we will have to rethink our approach anyway.

Looks like accepting your suggestion auto-dismissed your review. I don't remember that happening before ...

[ginsbach]

I have a kickoff meeting with Anders and Asger tomorrow for overlay-aware Java & JS where I will go through the tooling, including this script. I think that is preferable to having them review for now. If they actually end up having to frequently tweak this script to achieve the desired annotations, then I think we will have to rethink our approach anyway.

If you already have a meeting set up where you talk Anders and Asger through the script, wouldn't that make it quite convenient to then assign one of them to approve afterwards? It wouldn't take them much time to review right after havingt discussed it, and that way, the handoff of ownership would be explicit and somebody that didn't write the code had a look.

[kaspersv]

Good point. Let us do the same for the QL-for-QL query as well. Feel free to add review comments to the QL-for-QL query in the mean time.

[kaspersv]

Superseeded by #19778.