Add typed multi-file fragment refs and Maven IT coverage for bundling

[bascunansalvador]

This PR expands and stabilizes multi-file $ref handling across parsing, validation, bundling, and Maven plugin integration tests.

Why

We hit real-world multi-file contract scenarios that were only partially supported:

• Plain YAML fragments (no top-level asyncapi) were being treated as invalid AsyncAPI docs.
• Fragment refs for schema properties worked only partially and exposed internal fields in bundled output.
• External channel fragment refs needed to be supported consistently.
• Existing bundler expectations in tests diverged from updated fixture behavior.
• We needed end-to-end plugin IT coverage to prevent regressions outside core unit tests.

The goal was to support practical multi-file authoring while preserving existing full AsyncAPI behavior.

Key changes

1. External loading supports fragment files (not only full AsyncAPI docs)

• External file loading now branches by content:
  • If top-level asyncapi is present -> parse/validate as full AsyncAPI document.
  • Otherwise -> process as external fragment using typed parser/validator flow.
• This enables refs like:
  • properties.yaml#/id
  • channels.yaml#/testChannel
  • in addition to standard #/components/... references.

2. Typed reference categories were introduced and propagated

• References now carry referenceCategoryKey so external fragment processing knows expected target type.
• Parsers now set category metadata in created references (schema, channel, message, operation, traits, bindings, etc.).
• This removes ambiguity during fragment processing and avoids brittle path guessing.

3. External fragment processing now includes validation

• Added ExternalFragmentProcessor to parse and validate fragment content according to reference category.
• This gives earlier and clearer failures for invalid fragment shape/type mismatch.
• Validation/references remain consistent with existing validator/resolver behaviour.

4. Bundler behavior and expectations were aligned for new multi-file shapes

• For updated fixtures where channels.testChannel is an external $ref, bundled model is expected as ChannelReference with resolved model.
• Test dataset and assertions were updated to reflect actual bundled semantics and inline-vs-reference structure from current YAML fixtures.
• Internal processing field leakage (defaultSet) is not expected in bundled YAML.

5. Sanitization and resolution robustness was reviewed

• We validated that quote/prefix handling is a sensitive path in reference normalization/resolution.
• Current behavior is stable for the implemented test matrix; broader sanitization hardening is intentionally deferred to planned refactor work.

New Maven plugin integration tests (IT)

Added two new invoker IT projects under asyncapi-generator-maven-plugin/src/test/it/:

1. bundle-multifile-schema-fragment

• Main spec references plain properties.yaml fragments from schema properties.
• Verifies bundled output is generated and contains inlined fragment content.
• Verifies no leftover external fragment refs and no defaultSet field leakage.
• Verifies no codegen output when packages are not configured (bundle-only intent).

2. bundle-multifile-channel-fragment

• Main spec references external channel fragment via channels.yaml#/testChannel.
• External channel includes nested schema property fragment refs (properties.yaml#/id).
• Verifies channel + nested fragment content are bundled correctly.
• Verifies no leftover external refs and no defaultSet field leakage.
• Verifies no generated code in bundle-only mode.

Commands used to validate

Core:

• mvn -pl asyncapi-generator-core test
  Maven plugin IT (targeted):
• mvn -pl asyncapi-generator-maven-plugin -Dinvoker.test=bundle-multifile-schema-fragment,bundle-multifile-channel-fragment invoker:install invoker:run

Practical outcome

You can now author contracts with a cleaner multi-file structure where shared content can live in plain YAML fragments and be referenced from AsyncAPI documents, including channel-level fragment references, and get correct bundled output with regression coverage at plugin IT level.

Follow-up (planned refactor)

Deferred intentionally to keep this PR focused and safe:

• Unified reference sanitization/normalization hardening.
• Reducing remaining generic REFERENCE paths by making all reference creation sites category-explicit.
• Potentially separating parse-time graph loading from validation phases more explicitly.