Add optional Reference root field to Bjoern spec files

[Copilot]

Adds a new optional Reference field at the root of .zgr spec files to associate tickets or external references with a spec. Supports plain text or markdown link syntax ([text](url)), which is automatically converted to appropriate hyperlinks in generated outputs.

Spec format

Feature: My Feature
Reference: "[TICKET-123](https://example.com/TICKET-123)"
Scenarios:
  - Scenario: ...

Changes

• Parser model (BjoernZGRModell, Bjoern) — Added Reference field. Bjoern exposes getReferenceAsJavadoc() and getReferenceAsAsciidoc() which convert markdown links to <a href> and link:[] syntax respectively; plain text passes through unchanged. Link text and URLs are sanitized: HTML-escaped for Javadoc output, bracket-encoded for AsciiDoc URLs, and only http/https URL schemes are converted to hyperlinks (others fall back to plain text).
• Code generation (BjoernFeatureTestClassBuilder) — Appends @see <reference> to the generated abstract class Javadoc when a reference is present. Uses addJavadoc("$L", ...) literal to prevent JavaPoet from interpreting $ characters in URLs as format specifiers.
• Doc generation (asciidoc.ftlh) — Renders Reference: <link or text> below the feature title; omitted entirely when not set or blank (has_content check).
• Validator (BjoernKeywords, MissingNameValidation) — Added Reference: as a recognised root-level keyword; a Reference: line without a value is now rejected with a validation error (consistent with Feature: and - Scenario:).
• Documentation (README.md, .github/copilot-instructions.md) — Updated spec format examples, generated Java/AsciiDoc output examples, and added description of Reference field behaviour (plain text and markdown link support).
• Tests (AsciiDocBuildTest, BjoernValidatorTest, BjoernParserTest) — testDocGenerationWithReference asserts the generated file exists and contains the expected feature title and AsciiDoc hyperlink; missingReferenceValue verifies that an empty Reference: line fails validation; new tests cover HTML-escaping, AsciiDoc URL passthrough, and non-http URL scheme fallback to plain text.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Neues RootElement "Reference"</issue_title>
<issue_description>### Anforderung

Auf root Ebene im Bjoern Projekt soll ein neues Feld "Reference" ergänzt werden. Der Zweck von diesem Feld ist es Tickets oder andere Referenzen angeben zu können um so eine bessere Nachvollziehbarkeit zu schaffen.

Umsetzung

1. Neues optionales Feld "reference" im Root einer Bjoern spec einführen
2. Dieses Feld nimmt einen Text entgegen
3. Im Code wird die Referenz lediglich im der generieten Klasse im Javadoc als reference hinterlegt
4. Im generieten Doc wird die Referenz nach dem Feature mit angegeben.
5. Der Text kann auch wie ein Markdown Link aufgebaut sein. Dies sorgt dann dafür dass im Code im Javadoc ein passendes href generiert wird als Link und in den Docs ebenfalls ein hyperlink angezeigt wird.

</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Neues RootElement "Reference" #88

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[Copilot]

Pull request overview

Adds a new optional root-level Reference: field to .zgr spec files and propagates it through parsing, validation, code generation (Javadoc), and AsciiDoc documentation generation.

Changes:

• Extend the YAML model + domain model to include Reference, with helpers to convert Markdown link syntax to Javadoc/AsciiDoc links.
• Include Reference: in keyword validation and update relevant tests/spec fixtures.
• Render the reference in generated Javadoc (@see …) and in the AsciiDoc template.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/test/resources/reference.zgr	Adds a fixture spec containing a Reference: Markdown link.
src/test/java/de/mehtrick/bjoern/parser/BjoernValidatorTest.java	Updates expected allowed-keyword list to include Reference:.
src/test/java/de/mehtrick/bjoern/generator/builder/BjoernFeatureTestClassBuilderTest.java	Adds a test asserting @see and HTML anchor appear in generated class Javadoc.
src/test/java/de/mehtrick/bjoern/asciidoc/AsciiDocBuildTest.java	Adds a smoke test for doc generation with a reference spec.
src/test/java/de/mehtrick/bjoern/BjoernParserTest.java	Adds tests for parsing and converting reference values (markdown, plain text, malformed, null).
src/main/resources/asciidoc.ftlh	Renders Reference: block in generated AsciiDoc.
src/main/java/de/mehtrick/bjoern/parser/validator/validations/BjoernKeywords.java	Adds REFERENCE("Reference:") to the validator keyword list.
src/main/java/de/mehtrick/bjoern/parser/modell/BjoernZGRModell.java	Adds Reference field mapping in the YAML POJO.
src/main/java/de/mehtrick/bjoern/parser/modell/Bjoern.java	Adds reference plus conversion helpers for Javadoc and AsciiDoc link formats.
src/main/java/de/mehtrick/bjoern/generator/builder/BjoernFeatureTestClassBuilder.java	Appends @see <reference> to generated abstract class Javadoc when present.

[Copilot]

Now that Reference: is an allowed keyword, the validator should also reject an empty Reference: line (similar to Feature: / - Scenario:). Currently MissingNameValidation only checks FEATURE and SCENARIO, so Reference: with no value would pass validation. Add validation + a test case to ensure Reference: requires a non-empty value.

[Mehtrick]

@copilot apply changes based on this feedback

[Copilot]

Done in commit 260c458. MissingNameValidation now also checks Reference: — if the keyword is present but has no value after the colon, it throws the same validation error as Feature: and - Scenario:. Added missingReferenceValue() test to BjoernValidatorTest to cover this case.

[Mehtrick]

passe auch die README und ggf Copilot Instructions entsprechend an um den neuen Parameter

[Copilot]

passe auch die README und ggf Copilot Instructions entsprechend an um den neuen Parameter

Done in commit 70940da. Updated both README.md (spec format example, generated Java/AsciiDoc output examples) and .github/copilot-instructions.md (BDD spec format section) to document the new Reference field and its markdown link support.