[router]: Refactor getRoutes

[marklawlor]

Why

With the introduction of Platform Routes, the getRoutes function needs to be updated with additional rules/checks. This is a refactor before we start on that body of work.

Current bugs

• Expo Router v2 sitemap is missing full paths to routes #24788
• /page.tsx & /page+api.tsx will error as a duplicate route
• /folder/+html is a valid route
• Groups with no valid routes do not throw any error
• 'apple/(a,b)/_layout': () => 'apple/(a)/index': () => ` errors with a strange message

Closes ENG-8005

Current DX issues

The existing error messages are very vague. I've taking this as an opportunity to improve them

Duplicate Route errors

The difference is now it tells you which two files are in conflict and why they are in conflict. It also leaves out redundant information like route priority.

Previous

Higher priority Layout Route "./(a,c)/_layout" overriding redundant Layout Route "./(a,b)/_layout". Remove the Layout Route "./(a,b)/_layout" to fix this.

New

The layouts "./(a,c)/_layout" and "./(a,b)/_layout" conflict on the route "./(a,c)/_layout". Please remove or rename one of these files.

Deprecated _layout format

This format is now allowed.

Previous edit

This error is confusing as it can occur when your not trying to use `_layout`

I'm not sure if I like this. It means we're kinda heading into everything is page.tsx territory.

app/
├─ [a].js
├─ [a]/[b].js

Previous

Using deprecated Layout Route format: Move `./app/[a].js` to `./app/[a]/_layout.js`

New

The route file `./app/[a].js` should be renamed to `./app/[a]/index.js`
```</details>


### Unknown `initialRouteName`

// new error message
"Layout ./_layout.js has invalid initialRouteName 'c'. Valid options are: 'a', 'b'"

// new error message if using group syntax
"Layout ./(a,b)/_layout.js has invalid initialRouteName 'd' for group '(b)'. Valid options are: 'c'"

# How

`getRoutes` was previously a multi-pass algorithm that had three main phases.

1. Expand the `require.context.keys()` into a file system tree
2. Traverse the file system tree "hoisting" routes to the nearest `_layout`
3. Calculating initialRoutes and entry points

The new `getRoutes` removes the extra passes and performs all logic with the three phases mentioned above. It utilises `Set`/`Map` for faster look-ups.

## Specificity

The only new concept is "specificity". When we build the file system tree in the initial phase, a single "filepath" is now an array of `RouteNode` sorted by specificity (lowest to highest). **Currently specificity is hard-coded to 0**. When we add Platform Routes, these will have a high specificity and allow us to select the correct route and assert for fallback routes.

**Previous**

type TreeNode = {
name: string;
children: TreeNode[];
parents: string[];
/** null when there is no file in a folder. */
node: FileNode | null;
};

**New**

type DirectoryNode = {
layout?: RouteNode[];
subdirectories: Map<string, DirectoryNode>;
files: Map<string, RouteNode[]>; // Each file is an array of RouteNode sorted by specificity
};

# Test Plan

The test suite for `getRoutes` has been completely written.The existing tests were my biggest issue with `getRoutes` as they were very unclear **what** they were testing. This means certain behaviours of `getRoutes()` are unclear.

Instead of testing each phase individually, the tests for `getRoutes()` have been rewritten to work more like integration tests, where we provide a context and assert against the returned schema. This makes it much easier to visualise what is happening.

# Checklist

<!--
Please check the appropriate items below if they apply to your diff. This is required for changes to Expo modules.
-->

- [ ] Documentation is up to date to reflect these changes (eg: https://docs.expo.dev and README.md).
- [ ] Conforms with the [Documentation Writing Style Guide](https://github.com/expo/expo/blob/main/guides/Expo%20Documentation%20Writing%20Style%20Guide.md)
- [ ] This diff will work correctly for `npx expo prebuild` & EAS Build (eg: updated a module plugin).

[linear]

ENG-8005 Resolve duplicate route format issue (more in desc)

[EvanBacon]

contextKey is used as a unique identifier, it looks like it's possible for duplicates now?

[marklawlor]

contextKey is being used both as an ID and as a filename for various purposes.

The only place its used as an ID is the useContextKey() hook for the navigators. I don't think this breaks their functionality, but we so don't have great test coverage for this 🤔

I'll add an id attribute to RouteNode which was the previous contextKey value and update useContextKey to return the ID value.

[EvanBacon]

Generally seems fine, depending on tests for a number of the advanced cases.