This is very expensive - it forces every class-like to be loaded and parsed at least twice during the program runtime.

And also forces the second parsing to be again stored in memory.

Limiting this only to class-likes seems half done looking at the docs for that annotation: https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/package.html#description

I don't like the concept of mixing Ast Parsing (done in AST module) and collectors (done in Layer module). They are separate concerns and should be done in their respective places.

I agree. The collector should not be aware of the parser. I think this should be an extractor instead, which can then emit a reference. I am not sure, if it should be a class reference or maybe something else/new.

At the moment the TokenReferenceInterface only handles the Token and its filepath - could we add a more generic array of meta information, which we can then search later in collectors?

For example, if there was a new TokenReferenceMetaInterface, with an array of those in each TokenReferenceInterface, we could store a new PackageAnnotationMeta object in that array when we find the @package annotation, and then search for it in collectors.

This would prevent the TokenReferenceInterface gradually having more fields as more meta data is attached to it (if more collectors come along in the future).

The extractor you suggest could then add a TokenReferenceMeta to the TokenReference.

Sorry - I don't think I've explained this very well - I'll see if I can start to build it so you can see what I mean.

Can the test be done on some fixture class file instead of this synthetic doc-block? Those test then can serve as a documentation reference as well to show case how it should be used as well.