bug(windows): documentation link checks report existing routes as missing

[knqiufan]

Describe the bug

The website's link-checking gate reports valid routes as missing on Windows. The route index contains filesystem route groups and unexpanded dynamic segments, such as /(default)/api and /(localized)/[lang]/(documentation)/docs/[[...slug]], instead of the public routes that Markdown links use.

The project invokes the Next preset from locked next-validate-link 1.6.7 in website/scripts/validate-links.ts. That preset receives forward-slash paths from its glob but splits route directories using path.sep. On Windows, the separator is a backslash, so an entire multi-segment route is treated as one segment. Route-group removal and dynamic-route population consequently do not run on the intended segments.

Steps to reproduce

On Windows at master 80d618bd61432d1bb4eae85433fa22f2bbd50bce, install the locked development dependencies and run:

uv sync --frozen
pnpm --dir website install --frozen-lockfile
pnpm --dir website check:links

An independent reproduction isolates the route scanner from PowerContext's documents, Python API generation, and line endings. Save this in the website directory as probe-routes.mts and run it with pnpm exec tsx probe-routes.mts:

import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import { scanURLs } from 'next-validate-link';

const root = await mkdtemp(path.join(os.tmpdir(), 'pc-route-scan-'));
const page = path.join(root, 'app', '(group)', 'api', 'page.tsx');
await mkdir(path.dirname(page), { recursive: true });
await writeFile(page, 'export default function Page() { return null; }\n');

const discovered = await scanURLs({ preset: 'next', cwd: root });
console.log([...discovered.urls.keys()]);

const nativeInput = await scanURLs({
  preset: 'next', cwd: root, pages: ['(group)\\api\\page.tsx'],
});
console.log(nativeInput.urls.has('/api'));

Expected behavior

The discovered (group)/api/page.tsx route should yield /api. The full website route index should omit route groups and populate localized/dynamic routes from the provided configuration on Windows as it does on Linux.

Normalize discovered path separators before splitting into route segments, through a verified dependency fix or a project adapter. Keep validation of genuinely missing routes and anchors enabled. Add Windows coverage for a route group, localized dynamic route, and a real invalid link.

Actual behavior

The isolated Windows reproduction prints ['/(group)/api']; supplying the equivalent native-separated input makes /api appear. This establishes a scanner path-separator problem without involving the documents themselves.

For the real site, the index contains only 11 concrete entries, including /(default)/api, and does not contain /api or /en/docs/tutorials/agent-quickstart. Full link validation reports 458 errors in 122 files and exits 1, blocking pnpm build before Next runs. This count describes the observed output, not 458 independently confirmed broken documentation links.

This is separate from the homepage's CRLF frontmatter parsing problem: the minimal route fixture has no Markdown frontmatter, and the link gate runs earlier in the build pipeline.

Environment

• Upstream master: 80d618bd61432d1bb4eae85433fa22f2bbd50bce.
• Windows x64, Node.js 24.14.1, pnpm 11.13.1.
• Locked next-validate-link 1.6.7, Fumadocs dependencies, and Next.js 16.3.3.
• No corresponding open PowerContext issue or implementation PR was found. Open Windows-related items in the dependency repository were also checked without finding a matching fix.
• AI assistance: OpenAI Codex assisted with source inspection, the isolated scanner reproduction, and this report.

Are you willing to submit a PR to fix this bug?

• Yes, I would like to submit a PR.