Add test to validate document order preservation for positional includes

[christiangoerdes]

Summary by CodeRabbit

• New Features

  • Positional YAML include: expansion now preserves document order, so routing priority follows each include’s location.
  • Added/extended the advanced “Includes” tutorial with inline endpoints, included route files, and a fallback returning 404.

• Documentation

  • Refreshed include documentation to clarify multi-include routing priority and in-place expansion behavior (with updated examples).

• Tests

  • Added integration tests for positional include ordering and for tutorial routes (including fallback behavior for unknown paths).

• Chores

  • Added Windows and POSIX launcher scripts for the tutorial.

[christiangoerdes]

/ok-to-test

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5c257406-0583-4724-8345-20b85f6d3247

📥 Commits

Reviewing files that changed from the base of the PR and between 362bb93 and 0ba0e73.

📒 Files selected for processing (3)

• distribution/src/test/java/com/predic8/membrane/tutorials/advanced/include/IncludeTutorialTest.java
• distribution/tutorials/advanced/include/10-Include.yaml
• distribution/tutorials/advanced/include/external/shop.apis.yaml

---

📝 Walkthrough

Walkthrough

The change documents in-place YAML includes, adds parser coverage for preserved document order, and introduces composed and positional-include tutorials with shell and Windows launchers plus HTTP integration tests.

Changes

Include Tutorials and Positional Routing

Layer / File(s)	Summary
Include ordering contract and validation annot/src/main/java/com/predic8/membrane/annot/generator/IncludeListClassGenerator.java, core/src/test/java/com/predic8/membrane/core/kubernetes/GenericYamlParserIncludeListTest.java	Generated Javadoc describes in-place expansion and multiple priority-controlled includes; parser tests verify included and inline definitions retain document order.
Base include tutorial configuration distribution/tutorials/advanced/include/10-Include.yaml, distribution/tutorials/advanced/include/external/shop.apis.yaml, distribution/src/test/java/com/predic8/membrane/tutorials/advanced/include/IncludeTutorialTest.java	The tutorial composes inline health, shop, transitive order, and fallback APIs, with integration tests covering successful and unknown routes.
Tutorial route configuration distribution/tutorials/advanced/include/20-Positional-Include.yaml, distribution/tutorials/advanced/include/external/*	The positional tutorial configures ordered inline and included routes for order lookup, order listing, shop status, and a 404 fallback.
Tutorial execution and integration validation distribution/tutorials/advanced/include/membrane.*, distribution/src/test/java/com/predic8/membrane/tutorials/advanced/include/PositionalIncludeTutorialTest.java	Launch wrappers locate the Membrane root, and integration tests validate the configured 200 responses and fallback 404 response.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Membrane
  participant IncludedAPI
  participant FallbackAPI
  Client->>Membrane: Request /shop/orders, /shop, or /unknown
  Membrane->>IncludedAPI: Apply positional route matching
  IncludedAPI-->>Membrane: Return configured 200 response
  Membrane->>FallbackAPI: Handle unmatched request
  FallbackAPI-->>Membrane: Return 404 response
  Membrane-->>Client: Send HTTP response

Loading

Suggested reviewers: rrayst

Poem

I’m a rabbit with routes in a row,
Includes hop where the documents flow.
Orders come first,
The shop quells the thirst,
And fallback says, “404, go!”

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title matches the main change: a new test for positional include document-order preservation.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch yaml-include-doc

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[membrane-ci-server]

This pull request needs "/ok-to-test" from an authorized committer.