@backthread/extractor 0.1.0

package/dist/framework/routing/next-router.js

@@ -0,0 +1,378 @@
+// (closes  "≥ Next + Expo") — the Next.js file-based routing
+// convention parser, the SECOND convention on the shared route-tree model.
+//
+// Next.js encodes its page/navigation graph + API surface in the directory tree,
+// across TWO routers that can co-exist during a migration:
+//   * App Router  (`app/` | `src/app/`)   — only SPECIAL files are routes:
+//       page.{tsx,ts,jsx,js}     → role `page`      (routed UI; navigable)
+//       route.{ts,js}            → role `endpoint`  (Route Handler / API; not nav)
+//       layout.* / template.*    → role `layout`    (structural wrapper)
+//       (co-located components/helpers are NOT route nodes — unlike Expo Router,
+//        where every file under `app/` is a route)
+//     URL rules: route groups `(group)` + parallel slots `@slot` are STRIPPED from
+//     the URL; dynamic `[param]` / catch-all `[...slug]` / optional `[[...slug]]`
+//     segments are kept (the shared bracket resolver matches them).
+//   * Pages Router (`pages/` | `src/pages/`) — EVERY file is a route, except:
+//       _document            → not a route (the server doc shell)
+//       _app                 → role `layout` at `/` (the global wrapper)
+//       pages/api/**         → role `endpoint`
+//       everything else      → role `page`  (`index` → segment root)
+//
+// Mirrors expo-router.ts in style + discipline (LOCKED, ):
+//   * Nav edges are `calls`, nothing else (the adapter feeds navEdges through
+//     contribute-step). Route NESTING is parentFileId METADATA, never an edge.
+//   * Deterministic ids — every keyed value derives from the path/file id.
+//   * No silent caps — a dynamic/unresolvable nav target is LOGGED + skipped.
+// Never-store-source: reads the route dirs + file contents server-side, returns
+// only the derived tree/edges; the consuming adapter declares `scansSourcePath`.
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { SyntaxKind, } from 'ts-morph';
+import { buildExtractionProject, toId } from '../../graph/ts-morph-adapter.js';
+import { SOURCE_EXTENSIONS, EXCLUDE_DIRS } from '../../graph/file-graph.js';
+import { buildHrefResolver, } from './route-tree.js';
+export const NEXT_CONVENTION = 'next';
+const SOURCE_EXT_SET = new Set(SOURCE_EXTENSIONS);
+const EXCLUDE_SET = new Set(EXCLUDE_DIRS);
+// `router.<m>('…')` methods whose first arg is a navigation target (the
+// `useRouter()` result, conventionally bound to `router`, from next/navigation or
+// next/router). A different binding name isn't recognized — so it isn't a dropped
+// target either (matching the Expo parser's deliberate literal-name discipline).
+const ROUTER_NAV_METHODS = new Set(['push', 'replace', 'prefetch']);
+const ROUTER_RECEIVERS = new Set(['router']);
+// JSX components whose `href` prop is a navigation target.
+const NAV_COMPONENTS = new Set(['Link']);
+// Bare function nav (`redirect('/x')` / `permanentRedirect('/x')` from
+// next/navigation).
+const NAV_FUNCS = new Set(['redirect', 'permanentRedirect']);
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Locate the Next route dirs for a repo (or workspace package). Next uses EITHER
+ * the repo-root layout (`app` / `pages`) OR the `src/` layout (`src/app` /
+ * `src/pages`) — root takes precedence. Both routers can co-exist (a migration).
+ */
+export function findNextRouteDirs(repoDir, rootPath = '') {
+    const base = rootPath ? join(repoDir, rootPath) : repoDir;
+    const firstDir = (cands) => {
+        for (const c of cands) {
+            const abs = join(base, c);
+            if (isDir(abs))
+                return abs;
+        }
+        return null;
+    };
+    return {
+        appDirAbs: firstDir(['app', join('src', 'app')]),
+        pagesDirAbs: firstDir(['pages', join('src', 'pages')]),
+    };
+}
+/**
+ * Recursively collect repo-relative posix file ids of source files under a dir,
+ * skipping dot-entries + excluded dirs (mirror expo-router's walk). Sorted.
+ */
+export function walkNextSourceFiles(absDir, repoDir) {
+    const out = [];
+    const stack = [absDir];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith('.'))
+                continue;
+            const abs = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (EXCLUDE_SET.has(e.name))
+                    continue;
+                stack.push(abs);
+            }
+            else if (e.isFile()) {
+                const ext = e.name.split('.').pop();
+                if (ext && SOURCE_EXT_SET.has(ext))
+                    out.push(toId(repoDir, abs));
+            }
+        }
+    }
+    return out.sort();
+}
+function stripExt(name) {
+    return name.replace(/\.[^.]+$/, '');
+}
+// A URL-invisible directory segment: an App Router route group `(group)` or a
+// parallel-route slot `@slot` (both stripped from the path AND from the segment
+// key used for grouping).
+function isInvisibleSeg(seg) {
+    return (seg.startsWith('(') && seg.endsWith(')')) || seg.startsWith('@');
+}
+/**
+ * Derive role + URL-shaped route path from a route file's path relative to its
+ * route-root dir, or `null` when the file is NOT a route node (an App Router
+ * co-located component, or `pages/_document`). Pure — no content read.
+ */
+export function nextRouteInfo(relToRoot, router) {
+    const segments = relToRoot.split('/');
+    const fileName = segments.pop() ?? relToRoot;
+    const dirSegments = segments;
+    const stem = stripExt(fileName);
+    if (router === 'app') {
+        // App Router: ONLY the special files are route nodes.
+        let role;
+        if (stem === 'page')
+            role = 'page';
+        else if (stem === 'route')
+            role = 'endpoint';
+        else if (stem === 'layout' || stem === 'template')
+            role = 'layout';
+        else
+            return null; // co-located component/helper — not a route node
+        const visible = dirSegments.filter((s) => !isInvisibleSeg(s));
+        const routePath = visible.length > 0 ? `/${visible.join('/')}` : '/';
+        return { routePath, role };
+    }
+    // Pages Router: every file is a route, with three special cases.
+    if (stem === '_document')
+        return null; // the server doc shell — not a route
+    if (stem === '_app')
+        return { routePath: '/', role: 'layout' }; // global wrapper
+    const role = dirSegments[0] === 'api' ? 'endpoint' : 'page';
+    const urlSegments = stem === 'index' ? [...dirSegments] : [...dirSegments, stem];
+    const visible = urlSegments.filter((s) => !isInvisibleSeg(s));
+    const routePath = visible.length > 0 ? `/${visible.join('/')}` : '/';
+    return { routePath, role };
+}
+/**
+ * The top-level route SEGMENT key a file belongs to (for the route-segment
+ * grouping prior): the first URL-visible directory segment, or `''` (the root
+ * segment) for a file sitting directly in the route root (or only inside
+ * groups/slots). Pure — path only.
+ */
+export function nextSegmentKey(relToRoot, _router) {
+    const segments = relToRoot.split('/');
+    segments.pop(); // drop the filename
+    const visible = segments.filter((s) => !isInvisibleSeg(s));
+    return visible.length > 0 ? visible[0] : '';
+}
+// dir of a repo-relative file id ('app/blog/[slug]/page.tsx' → 'app/blog/[slug]').
+function dirOf(fileId) {
+    const i = fileId.lastIndexOf('/');
+    return i === -1 ? '' : fileId.slice(0, i);
+}
+// Ancestor dirs from `dir` up to (and including) `rootDir`, nearest first.
+function ancestorDirs(dir, rootDir) {
+    const out = [];
+    let cur = dir;
+    while (cur === rootDir || cur.startsWith(`${rootDir}/`)) {
+        out.push(cur);
+        if (cur === rootDir)
+            break;
+        cur = dirOf(cur);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Nav-target extraction (reads source content via ts-morph) — same shape as the
+// Expo parser, retargeted to Next's primitives (next/link <Link>, redirect()).
+function literalTarget(node) {
+    if (!node)
+        return null;
+    if (node.getKind() === SyntaxKind.StringLiteral)
+        return node.getLiteralValue();
+    if (node.getKind() === SyntaxKind.ObjectLiteralExpression) {
+        const pathname = node.getProperty('pathname');
+        if (pathname && pathname.getKind() === SyntaxKind.PropertyAssignment) {
+            const init = pathname.getInitializer();
+            if (init && init.getKind() === SyntaxKind.StringLiteral) {
+                return init.getLiteralValue();
+            }
+        }
+    }
+    return null;
+}
+// Pull nav targets from one source file: <Link href> + router.push|replace('…') +
+// redirect|permanentRedirect('…').
+function collectNavTargets(sf) {
+    const literals = [];
+    let dynamic = 0;
+    const jsxEls = [
+        ...sf.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
+        ...sf.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement),
+    ];
+    for (const el of jsxEls) {
+        const tag = el.getTagNameNode().getText();
+        const local = tag.split('.').pop() ?? tag; // `NextLink.Link`-style → `Link`
+        if (!NAV_COMPONENTS.has(local))
+            continue;
+        const hrefAttr = el.getAttribute('href');
+        if (!hrefAttr || hrefAttr.getKind() !== SyntaxKind.JsxAttribute)
+            continue;
+        const init = hrefAttr.getInitializer();
+        if (!init)
+            continue;
+        let target = null;
+        if (init.getKind() === SyntaxKind.StringLiteral) {
+            target = init.getLiteralValue();
+        }
+        else if (init.getKind() === SyntaxKind.JsxExpression) {
+            target = literalTarget(init.getExpression());
+        }
+        if (target !== null)
+            literals.push(target);
+        else
+            dynamic++;
+    }
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const callee = call.getExpression();
+        let isNav = false;
+        if (callee.getKind() === SyntaxKind.PropertyAccessExpression) {
+            const pae = callee;
+            const base = pae.getExpression();
+            isNav =
+                ROUTER_NAV_METHODS.has(pae.getName()) &&
+                    base.getKind() === SyntaxKind.Identifier &&
+                    ROUTER_RECEIVERS.has(base.getText());
+        }
+        else if (callee.getKind() === SyntaxKind.Identifier) {
+            isNav = NAV_FUNCS.has(callee.getText());
+        }
+        if (!isNav)
+            continue;
+        const arg = call.getArguments()[0];
+        if (!arg)
+            continue;
+        const target = literalTarget(arg);
+        if (target !== null)
+            literals.push(target);
+        else
+            dynamic++;
+    }
+    return { literals, dynamic };
+}
+/**
+ * Extract the Next route tree for a repo (or workspace package), spanning BOTH
+ * the App Router and Pages Router when present (a migration). Returns `null` when
+ * neither route dir exists or holds route files. Fully deterministic (routes
+ * sorted by fileId; navEdges deduped + sorted) — snapshot-stable by construction.
+ */
+export function extractNextRouteTree(opts) {
+    const { repoDir } = opts;
+    const rootPath = opts.rootPath ?? '';
+    const { appDirAbs, pagesDirAbs } = findNextRouteDirs(repoDir, rootPath);
+    const dirs = [];
+    if (appDirAbs)
+        dirs.push({ abs: appDirAbs, rootId: toId(repoDir, appDirAbs), router: 'app' });
+    if (pagesDirAbs)
+        dirs.push({ abs: pagesDirAbs, rootId: toId(repoDir, pagesDirAbs), router: 'pages' });
+    if (dirs.length === 0)
+        return null;
+    // --- route nodes (paths + roles) from file paths -------------------------
+    const routes = [];
+    const rootIdByFile = new Map(); // fileId → its route-root id (nesting scope)
+    const layoutByDir = new Map(); // dir → layout fileId (lexical-first)
+    const allFiles = []; // every source file under a route dir (for callers)
+    for (const spec of dirs) {
+        for (const fileId of walkNextSourceFiles(spec.abs, repoDir)) {
+            allFiles.push(fileId);
+            const relToRoot = fileId.slice(spec.rootId.length + 1);
+            const info = nextRouteInfo(relToRoot, spec.router);
+            if (!info)
+                continue; // co-located component / _document — not a route node
+            routes.push({ routePath: info.routePath, fileId, role: info.role });
+            rootIdByFile.set(fileId, spec.rootId);
+            if (info.role === 'layout') {
+                const dir = dirOf(fileId);
+                if (!layoutByDir.has(dir))
+                    layoutByDir.set(dir, fileId);
+            }
+        }
+    }
+    if (routes.length === 0)
+        return null;
+    // --- nesting (parentFileId = nearest enclosing layout, within the same root) -
+    for (const node of routes) {
+        const rootId = rootIdByFile.get(node.fileId);
+        const fileDir = dirOf(node.fileId);
+        // A layout's own dir-layout is itself → its parent must be a STRICT ancestor.
+        const searchDirs = node.role === 'layout'
+            ? ancestorDirs(fileDir, rootId).slice(1)
+            : ancestorDirs(fileDir, rootId);
+        for (const dir of searchDirs) {
+            const layoutId = layoutByDir.get(dir);
+            if (layoutId && layoutId !== node.fileId) {
+                node.parentFileId = layoutId;
+                break;
+            }
+        }
+    }
+    routes.sort((a, b) => (a.fileId < b.fileId ? -1 : a.fileId > b.fileId ? 1 : 0));
+    // --- nav edges (statically-resolvable targets; reads source content) -----
+    const resolve = buildHrefResolver(routes);
+    const project = buildExtractionProject(repoDir);
+    const sfById = new Map();
+    for (const fileId of allFiles) {
+        try {
+            sfById.set(fileId, project.addSourceFileAtPath(join(repoDir, fileId)));
+        }
+        catch {
+            // Unreadable/unparseable — its nav edges are skipped (no crash).
+        }
+    }
+    const edgeKeys = new Set();
+    const navEdges = [];
+    let dynamicTargets = 0;
+    const unresolvedTargets = new Set();
+    for (const fileId of allFiles) {
+        const sf = sfById.get(fileId);
+        if (!sf)
+            continue;
+        const { literals, dynamic } = collectNavTargets(sf);
+        dynamicTargets += dynamic;
+        for (const href of literals) {
+            const targetFile = resolve(href);
+            if (!targetFile) {
+                unresolvedTargets.add(href);
+                continue;
+            }
+            if (targetFile === fileId)
+                continue; // self-nav — not a route→route edge
+            const key = `${fileId}→${targetFile}`;
+            if (edgeKeys.has(key))
+                continue;
+            edgeKeys.add(key);
+            navEdges.push({ fromFileId: fileId, toFileId: targetFile });
+        }
+    }
+    navEdges.sort((a, b) => a.fromFileId < b.fromFileId
+        ? -1
+        : a.fromFileId > b.fromFileId
+            ? 1
+            : a.toFileId < b.toFileId
+                ? -1
+                : a.toFileId > b.toFileId
+                    ? 1
+                    : 0);
+    // No silent caps: log every dynamic + unresolvable nav target once.
+    if (dynamicTargets > 0 || unresolvedTargets.size > 0) {
+        const parts = [];
+        if (dynamicTargets > 0)
+            parts.push(`${dynamicTargets} dynamic target(s)`);
+        if (unresolvedTargets.size > 0) {
+            parts.push(`${unresolvedTargets.size} unresolvable target(s): ${[...unresolvedTargets].sort().join(', ')}`);
+        }
+        console.log(`  [next-router] skipped ${parts.join(' · ')} (logged, not silently dropped)`);
+    }
+    const rootDir = dirs[0].rootId; // informational; the first present route root
+    return { convention: NEXT_CONVENTION, rootDir, routes, navEdges };
+}
+//# sourceMappingURL=next-router.js.map

package/dist/framework/routing/next-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next-router.js","sourceRoot":"","sources":["../../../src/framework/routing/next-router.ts"],"names":[],"mappings":"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"}

package/dist/framework/routing/route-tree.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The role a route file plays. METADATA, not a Module-kind — the locked
+ * discipline ("fix the classifier, never weaken the Module-kind enum") holds:
+ * an adapter maps these onto an existing ModuleKind (a screen/page → `frontend`,
+ * an endpoint → `gateway`/`service`). The finer role is carried for the label.
+ *
+ *  - `page`     — a screen/file that renders UI for a concrete URL.
+ *  - `route`    — a routable node we recognize but can't confirm as page vs
+ *                 endpoint (the generic fallback; conventions that always know
+ *                 the answer, like Expo Router, don't emit it).
+ *  - `layout`   — wraps child routes (Expo `_layout`, Next `layout`, SvelteKit
+ *                 `+layout`). Its nesting is the parent pointer, never an edge.
+ *  - `endpoint` — a server/API handler with no UI (Expo `+api`, Next `route.ts`,
+ *                 SvelteKit `+server`).
+ */
+export type RouteRole = 'route' | 'page' | 'layout' | 'endpoint';
+export declare const ROUTE_ROLES: readonly RouteRole[];
+/**
+ * One route file. `fileId` is the repo-relative posix path — the same file-id
+ * space the NormalizedGraph + contribute-step's `fileModuleMap` key on (so a
+ * consuming adapter resolves it to a module for free). `routePath` is the
+ * URL-shaped label (dynamic segments kept as `[id]`/`[...rest]`, route groups
+ * stripped). `parentFileId` is the nearest enclosing layout — the STRUCTURAL
+ * nesting pointer (NOT an edge); absent on the root layout / un-nested routes.
+ */
+export interface RouteNode {
+    routePath: string;
+    fileId: string;
+    role: RouteRole;
+    parentFileId?: string;
+}
+/**
+ * A statically-resolvable navigation between two route files (a `<Link href>`,
+ * `router.push('…')`, `<Redirect href>`, `redirect('…')` whose target resolves
+ * to a route file). `from`/`to` are repo-relative posix file ids. Every navEdge
+ * becomes a `calls` edge when an adapter feeds it through contribute-step.
+ */
+export interface RouteNavEdge {
+    fromFileId: string;
+    toFileId: string;
+}
+/**
+ * A repo's (or workspace package's) file-based route tree for one convention.
+ */
+export interface RouteTree {
+    /** The convention that produced this tree (e.g. 'expo-router'). */
+    convention: string;
+    /** The repo-relative posix dir the routes were read from (e.g. 'app'). */
+    rootDir: string;
+    /** Route nodes, sorted by fileId (deterministic). */
+    routes: RouteNode[];
+    /** Resolvable nav edges, deduped + sorted by (from, to) (deterministic). */
+    navEdges: RouteNavEdge[];
+}
+/**
+ * Normalize an href to an absolute, query/hash-free, single-slash path — or
+ * `null` when it isn't statically resolvable as an absolute URL.
+ *
+ * RELATIVE hrefs (`./x`, `../x`, bare `x`) return `null` (resolved against the
+ * current route — a Slice-2 refinement; logged + skipped for now, never guessed).
+ */
+export declare function normalizeHref(raw: string): string | null;
+/**
+ * Build a deterministic href→fileId resolver over a route tree's navigable
+ * nodes (roles `page` / `route` — layouts + endpoints are never `<Link>`
+ * targets). Resolution order: exact route-path match first (covers literal
+ * `/profile/[id]` and static `/home`), then the most-specific dynamic-pattern
+ * match (covers a concrete `/profile/42` → `/profile/[id]`). Unresolvable ⇒
+ * `null`. Specificity tiebreak: fewest dynamic segments, then non-catch-all,
+ * then lexical fileId — so the choice never depends on input order.
+ */
+export declare function buildHrefResolver(routes: RouteNode[]): (href: string) => string | null;
+//# sourceMappingURL=route-tree.d.ts.map

package/dist/framework/routing/route-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-tree.d.ts","sourceRoot":"","sources":["../../../src/framework/routing/route-tree.ts"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEjE,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAAqD,CAAC;AAElG;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAgBD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQxD;AAoBD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAkCtF"}

package/dist/framework/routing/route-tree.js

@@ -0,0 +1,120 @@
+// (Slice 1) — the CONVENTION-AGNOSTIC route-tree model.
+//
+// File-system routing frameworks (Expo Router, Next app/pages, Remix, Nuxt,
+// SvelteKit, TanStack) encode the page/navigation graph IN THE DIRECTORY TREE —
+// completely invisible to an import/call graph. This module is the shared shape
+// every per-convention parser targets: a flat list of route nodes (each with a
+// route-path label, a role, and a STRUCTURAL parent pointer) plus the
+// statically-resolvable navigation edges between them.
+//
+// LOCKED design calls (orchestrator-decided 2026-06-26 — see the  brief):
+//   * Navigation edges are `calls`, nothing else. A `navEdge` becomes a `calls`
+//     FrameworkEdge when an adapter feeds it through contribute-step (this module
+//     never emits FrameworkEdges itself — it stays decoupled from the framework
+//     contract so Next/Remix/… reuse it unchanged).
+//   * Route NESTING is NOT an edge. A layout wrapping a page has no taxonomy verb;
+//     nesting is carried as STRUCTURAL METADATA (routePath + parentFileId), never
+//     a graph edge — and there is NO "nesting"/"contains" verb anywhere.
+//   * Deterministic ids: every keyed value derives from the route path / file id,
+//     never an index — snapshots stay stable across re-ingest.
+//   * No silent caps: a dynamic/unresolvable nav target is LOGGED + skipped by the
+//     caller, never silently dropped.
+//
+// This module is PURE-ish: types + a reusable href→fileId resolver (the bracket
+// `[param]` / `[...rest]` dynamic-segment syntax shared by Expo Router AND Next).
+// It reads nothing and persists nothing.
+export const ROUTE_ROLES = ['route', 'page', 'layout', 'endpoint'];
+// ---------------------------------------------------------------------------
+// Shared href resolution (bracket dynamic-segment syntax: `[param]` / `[...rest]`).
+// Reused by Expo Router (this slice) and the Next.js adapter.
+function isDynamicSeg(seg) {
+    return seg.startsWith('[') && seg.endsWith(']');
+}
+function isCatchAllSeg(seg) {
+    // `[...rest]` (Expo) and `[[...rest]]` (Next optional catch-all) both carry the
+    // `...` marker inside the brackets.
+    return isDynamicSeg(seg) && seg.includes('...');
+}
+/**
+ * Normalize an href to an absolute, query/hash-free, single-slash path — or
+ * `null` when it isn't statically resolvable as an absolute URL.
+ *
+ * RELATIVE hrefs (`./x`, `../x`, bare `x`) return `null` (resolved against the
+ * current route — a Slice-2 refinement; logged + skipped for now, never guessed).
+ */
+export function normalizeHref(raw) {
+    let h = raw.trim();
+    h = h.split('?')[0].split('#')[0];
+    if (h === '')
+        return null;
+    if (!h.startsWith('/'))
+        return null; // relative / bare — deferred (logged + skipped)
+    h = h.replace(/\/{2,}/g, '/');
+    if (h.length > 1)
+        h = h.replace(/\/+$/, '');
+    return h === '' ? '/' : h;
+}
+function splitPath(routePath) {
+    return routePath === '/' ? [] : routePath.replace(/^\//, '').split('/');
+}
+// Does a dynamic-segment pattern match a concrete href's segments? A catch-all
+// (always last by convention) absorbs ≥1 trailing segment; a `[param]` matches
+// exactly one; a literal must equal.
+function segMatch(pattern, href) {
+    for (let i = 0; i < pattern.length; i++) {
+        const p = pattern[i];
+        if (isCatchAllSeg(p))
+            return href.length - i >= 1;
+        if (i >= href.length)
+            return false;
+        if (isDynamicSeg(p))
+            continue;
+        if (p !== href[i])
+            return false;
+    }
+    return href.length === pattern.length;
+}
+/**
+ * Build a deterministic href→fileId resolver over a route tree's navigable
+ * nodes (roles `page` / `route` — layouts + endpoints are never `<Link>`
+ * targets). Resolution order: exact route-path match first (covers literal
+ * `/profile/[id]` and static `/home`), then the most-specific dynamic-pattern
+ * match (covers a concrete `/profile/42` → `/profile/[id]`). Unresolvable ⇒
+ * `null`. Specificity tiebreak: fewest dynamic segments, then non-catch-all,
+ * then lexical fileId — so the choice never depends on input order.
+ */
+export function buildHrefResolver(routes) {
+    const navigable = routes
+        .filter((r) => r.role === 'page' || r.role === 'route')
+        .sort((a, b) => (a.fileId < b.fileId ? -1 : a.fileId > b.fileId ? 1 : 0));
+    const exact = new Map();
+    const patterns = [];
+    for (const r of navigable) {
+        if (!exact.has(r.routePath))
+            exact.set(r.routePath, r.fileId);
+        const segs = splitPath(r.routePath);
+        patterns.push({
+            segs,
+            fileId: r.fileId,
+            dyn: segs.filter(isDynamicSeg).length,
+            catchAll: segs.some(isCatchAllSeg),
+        });
+    }
+    return (href) => {
+        const norm = normalizeHref(href);
+        if (norm === null)
+            return null;
+        const hit = exact.get(norm);
+        if (hit)
+            return hit;
+        const hrefSegs = splitPath(norm);
+        const candidates = patterns.filter((p) => segMatch(p.segs, hrefSegs));
+        if (candidates.length === 0)
+            return null;
+        candidates.sort((a, b) => a.dyn - b.dyn ||
+            Number(a.catchAll) - Number(b.catchAll) ||
+            (a.fileId < b.fileId ? -1 : a.fileId > b.fileId ? 1 : 0));
+        return candidates[0].fileId;
+    };
+}
+//# sourceMappingURL=route-tree.js.map

package/dist/framework/routing/route-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-tree.js","sourceRoot":"","sources":["../../../src/framework/routing/route-tree.ts"],"names":[],"mappings":"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"}