feat(routing): add route groups

[imdhemy]

Q	A
License	GPLv3
Issue	Closes #140

Summary

This PR adds RouteGroup(...) to the function-first routing API.

Route groups make it possible to compose routes with shared path prefixes, name prefixes, middleware, and route-level configuration while keeping the routing model explicit and function-first. They also provide a clean way to enrich named helper routes without expanding the HTTP verb helper signatures.

Documentation

Documentation updates are covered in the docs PR:

koala-ts/koala-ts.github.io#12

[Copilot]

Pull request overview

Adds route grouping support to the function-first routing API by introducing RouteGroup(...) and a normalization step that flattens grouped routes into concrete RouteDefinitions before registration/validation.

Changes:

• Introduce RouteGroup / RouteSource and normalize grouped/nested routes (prefixes, name prefixes, middleware, and per-route overlays).
• Refactor route registration pipeline into normalization → expansion → validation.
• Add unit + integration/e2e tests covering grouped routing behavior and duplicate detection.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/function-first-routing.e2e.test.ts	Adds E2E coverage for grouped routes, middleware order, overlays, nesting, and duplicate detection.
src/routing/validate-route-definitions.ts	Centralizes duplicate name/signature validation.
src/routing/validate-route-definitions.test.ts	Adds unit tests for validation behavior.
src/routing/route-source.ts	Introduces RouteSource union (route or group).
src/routing/route-registration.ts	Defines the expanded registration shape used for router registration + signature validation.
src/routing/route-group.ts	Adds RouteGroup definition + options (prefix/namePrefix/middleware/routeConfig).
src/routing/route-group.test.ts	Unit tests for route group definition creation.
src/routing/resolve-route-options.ts	Extracts/centralizes route options resolution + merging for overlays.
src/routing/resolve-route-options.test.ts	Unit tests for resolving/merging route options.
src/routing/register-routes.ts	Updates registrar to accept RouteSource[] and use normalize/expand/validate pipeline.
src/routing/register-routes.test.ts	Adds grouped-route registration test and grouped-duplicate signature test.
src/routing/normalize-route-sources.ts	Implements flattening/normalization of route groups (path/name/middleware + overlays).
src/routing/normalize-route-sources.test.ts	Comprehensive tests for normalization, nesting, overlays, and path edge cases.
src/routing/index.ts	Exports RouteGroup and new public types.
src/routing/expand-route-definitions.ts	Extracts route expansion (methods + body parsing middleware).
src/routing/expand-route-definitions.test.ts	Unit tests for expansion behavior.
src/routing/create-route-definition.ts	Refactors to use resolveRouteOptions helper.
src/application/create-application.test.ts	Adds create-app test that uses grouped routes.
src/Config/types.ts	Widens KoalaConfig.routes from RouteDefinition[] to RouteSource[].