C++ overlay: Tweak dbsheme

[igfoo]

Adds @tag, @trap_or_tag, source_file_name, trap_uses_tag and renames in_trap to in_trap_or_tag.

[Copilot]

Pull request overview

Updates the C++ CodeQL database schema to better support overlay databases by introducing explicit @source_file and @tag entities, adding supporting relations, and renaming the old in_trap relation to a more general in_trap_or_tag.

Changes:

• Add new dbscheme relations/types: @tag, @trap_or_tag, tag_name, source_file_name, and trap_uses_tag.
• Change source_file_uses_trap to key by @source_file instead of a raw string filename.
• Replace in_trap with in_trap_or_tag, including upgrade/downgrade scripts to migrate relation data.

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
cpp/ql/lib/semmlecode.cpp.dbscheme	Introduces new overlay-related entities/relations and updates existing relation signatures.
cpp/ql/lib/upgrades/7e7c2f55670f8123d514cf542ccb1938118ac561/upgrade.properties	Declares upgrade actions for new/renamed relations and type changes.
cpp/ql/lib/upgrades/7e7c2f55670f8123d514cf542ccb1938118ac561/source_files.ql	Upgrade logic to map legacy string source files into @source_file entities and populate new relations.
cpp/ql/lib/upgrades/7e7c2f55670f8123d514cf542ccb1938118ac561/in_trap_or_tag.ql	Upgrade logic to populate in_trap_or_tag from legacy in_trap.
cpp/ql/lib/upgrades/7e7c2f55670f8123d514cf542ccb1938118ac561/old.dbscheme	Captures the pre-upgrade schema snapshot for the upgrade step.
cpp/downgrades/770002bb02322e04fa25345838ce6e82af285a0b/upgrade.properties	Declares downgrade actions to revert the schema changes.
cpp/downgrades/770002bb02322e04fa25345838ce6e82af285a0b/source_file_uses_trap.ql	Downgrade logic to reconstruct legacy source_file_uses_trap(string, trap) from @source_file + source_file_name.
cpp/downgrades/770002bb02322e04fa25345838ce6e82af285a0b/in_trap.ql	Downgrade logic to reconstruct legacy in_trap from in_trap_or_tag and tag usage.
cpp/downgrades/770002bb02322e04fa25345838ce6e82af285a0b/semmlecode.dbscheme	Captures the target (older) schema snapshot for the downgrade step.
cpp/downgrades/770002bb02322e04fa25345838ce6e82af285a0b/old.dbscheme	Captures the pre-downgrade schema snapshot for the downgrade step.

Comments suppressed due to low confidence (4)

cpp/ql/lib/semmlecode.cpp.dbscheme:293

• The parameter name t in in_trap_or_tag is very non-descriptive for a public dbscheme relation. Consider renaming it to something like trap_or_tag (or trapOrTag) to make the API self-explanatory.

This issue also appears on line 262 of the same file.

in_trap_or_tag(
    int element: @element ref,
    int t: @trap_or_tag ref
);

cpp/ql/lib/upgrades/7e7c2f55670f8123d514cf542ccb1938118ac561/upgrade.properties:6

• The upgrade description only mentions source_file_name, but this upgrade also deletes in_trap and introduces in_trap_or_tag. Updating the description to summarize all schema changes would make the upgrade history easier to understand.

description: Add source_file_name
compatibility: backwards
source_file_uses_trap.rel: run source_files.ql mk_source_file_uses_trap
source_file_name.rel: run source_files.ql mk_source_file_name
in_trap.rel: delete
in_trap_or_tag.rel: run in_trap_or_tag.ql

cpp/downgrades/770002bb02322e04fa25345838ce6e82af285a0b/upgrade.properties:8

• The downgrade step’s description only mentions source_file_name, but this downgrade also removes tag_name, trap_uses_tag, and in_trap_or_tag and reintroduces in_trap. Consider updating the description to reflect the full set of schema changes for easier maintenance.

description: Add source_file_name
compatibility: backwards
source_file_uses_trap.rel: run source_file_uses_trap.ql
source_file_name.rel: delete
tag_name.rel: delete
trap_uses_tag.rel: delete
in_trap.rel: run in_trap.ql
in_trap_or_tag.rel: delete

cpp/ql/lib/semmlecode.cpp.dbscheme:265

• The source_file_name relation uses the parameter name sf, which is an abbreviation and makes the schema harder to read (especially since related relations use source_file). Consider renaming the parameter to source_file for consistency/clarity.

source_file_name(
    int sf: @source_file,
    string name: string ref
);

[Copilot]

The source_file_uses_trap doc comment still implies source_file is the literal path ("(/path/to/foo.c)"). Since the column is now an @source_file id, the comment should be updated to reflect that callers should use source_file_name to obtain the path/name.

See below for a potential fix:

 * In `build-mode: none` overlay mode, indicates that the source file
 * identified by `source_file` (an `@source_file` id, for example for
 * `/path/to/foo.c`, whose name/path can be obtained via `source_file_name`)
 * uses the TRAP file `trap_file`; i.e. it is the TRAP file corresponding to
 * that source file, something it transitively includes, or a template
 * instantiation it transitively uses.

[IdrissRio]

Just to double check that I’m understanding this correctly.
We have an old database and we want to read it using the new CodeQL version.
We tell the engine that, to construct the source_file_name relation, it should run mk_source_file_predicate in source_files.ql and store the result as a table.

Then, since in the old database source_file_uses_trap stored the actual name as a raw string

source_file_uses_trap(
    string source_file: string ref,
    int trap_file: @trap ref
);

in source_files.ql we effectively promote that string into a standalone entity. Is that right?

And we follow the same approach to reconstruct the other relations as well.

[igfoo]

Yes, exactly.

[jketema]

LGTM