C++ forward declarations (`class Foo;`) index as phantom class nodes, masking the real definition

[luoyxy]

What happens

In a large C++/Unreal-Engine codebase, codegraph_explore for a heavily used
class (e.g. APXCharacter) returns mostly forward-declaration sites and even
picks one as the blast-radius representative, while the real definition (with
members and callers) is crowded out.

Root cause

A class Foo; forward declaration parses as a bodiless class_specifier.
extractStruct (#831) and extractEnum skip their bodiless forms, but
extractClass does not — so every forward decl (repeated across dozens of
headers) mints a phantom bodiless class node that competes with the single
real definition.

Expected

Bodiless class specifiers in C/C++ should be skipped, exactly like bodiless
structs/enums, so only the real definition is indexed. Languages where a
bodiless class is a complete definition (Kotlin class Empty, Scala) must be
unaffected.

Repro

Index any C++ project where a class is forward-declared in many headers, then
codegraph_explore that class name — the results are dominated by
class Foo; sites instead of the definition.

[colbymchenry]

Fixed in #1095 (merged to main) — it'll ship in the next release.

Your root-cause analysis was exactly right: a class Foo; forward declaration parses as a bodiless class_specifier, and while extractStruct (#831) and extractEnum already skipped their bodiless forms, extractClass didn't — so each forward decl across your headers minted a phantom class node that competed with, and could even be picked as the blast-radius representative over, the single real definition. A probe reproduced it exactly: a class forward-declared twice then defined produced 3 class nodes instead of 1.

The fix mirrors the struct/enum skip, but scoped to C/C++ via an opt-in extractor flag so that languages where a bodiless class is a complete definition — Kotlin class Empty, Scala case object / trait — stay indexed. Post-fix, APXCharacter collapses to just its real definition (members and callers intact), with regression tests covering all of the above.

Thank you for the detailed report and the precise diagnosis — this is exactly the kind of feedback that makes CodeGraph better with every update. 🙏