@cavuno/board 1.41.0 → 1.43.0

package/dist/route-contract.d.ts

@@ -0,0 +1,257 @@
+import { R as RouteEntry, a as RouteRole, C as ClassifyResult, b as CompileResult, V as ValidateManifestError, c as ValidateManifestResult, M as ManifestV1 } from './roles-vY0AXhoc.js';
+export { A as ALL_ROLES, d as Ambiguity, e as CANONICAL_MANIFEST, f as REQUIRED_ROLES, g as ROLE_PARAM_REGISTRY, i as isRouteRole } from './roles-vY0AXhoc.js';
+
+/**
+ * Classify routes into role assignments. Markers (keyed by `sourcePath`)
+ * always win and remove the route from inference. Two markers claiming the
+ * same role is an ambiguity (never silent first-wins). Ambiguities never
+ * guess.
+ */
+declare function classifyRoutes(routes: RouteEntry[], markers?: ReadonlyMap<string, RouteRole>): ClassifyResult;
+
+/**
+ * Classify routes and emit a ManifestV1 plus publish-gate signals.
+ * Assigned templates are self-validated via checkRoleTemplate (F1);
+ * failing required roles land in blockingMissing; failing optionals warn.
+ */
+declare function compileManifest(routes: RouteEntry[], markers?: ReadonlyMap<string, RouteRole>): CompileResult;
+
+/**
+ * LNK-06 — compile a ManifestV1 from a workspace file tree already in
+ * memory (candidate verification). Pure: no IO.
+ */
+
+type TreeFile = {
+    path: string;
+    contents: string;
+};
+/**
+ * Enumerate routes from file paths, harvest cavunoPage markers from every
+ * file body, run compileManifest. Marker harvest is intentionally broad
+ * (all files, not just ambiguous) — cheap string scan, correct for renames.
+ */
+declare function compileManifestFromTree(files: ReadonlyArray<TreeFile>): CompileResult;
+
+/**
+ * Tolerant parse of `export const cavunoPage = '<role>'` (single or double
+ * quotes; optional `as const`). Accepts camelCase roles and their kebab-case
+ * aliases (`job-detail` → `jobDetail`). Returns null when absent or when the
+ * string is not a known RouteRole (ADR-0090 D6 escape hatch).
+ */
+declare function extractCavunoPageMarker(contents: string): RouteRole | null;
+
+/**
+ * Extract `:param` token names from a URLPattern-style template string.
+ * Order-insensitive consumers should sort / set-compare the result.
+ */
+declare function extractParamNames(template: string): string[];
+/** Order-insensitive equality of two param-name lists. */
+declare function sameParamSet(a: readonly string[], b: readonly string[]): boolean;
+
+/**
+ * Per-role template checks shared by validateManifest and compileManifest.
+ * Never throws — returns zero or more typed errors.
+ *
+ * Rules (v1):
+ * - non-empty string
+ * - must start with '/' but NOT '//'; no '//' anywhere
+ * - no '.' or '..' path segments
+ * - no '?', '#', or whitespace
+ * - charset limited to [A-Za-z0-9\-_/:.]
+ * - params referenced by a template must be in ROLE_PARAM_REGISTRY[role]
+ * - static / empty-registry roles must have zero `:` tokens
+ * - parameterized roles must retain at least one registry param
+ */
+declare function checkRoleTemplate(role: RouteRole, template: string): ValidateManifestError[];
+/**
+ * Structural + registry validation of an unknown value as ManifestV1.
+ * Never throws — returns typed errors.
+ */
+declare function validateManifest(value: unknown): ValidateManifestResult;
+
+/**
+ * Platform resolution overlay (ADR-0090 D3 / LNK-07).
+ *
+ * Pure + isomorphic: role + params + precedence layers → board path.
+ * Imports only sibling route-contract / paths modules.
+ */
+
+/** One precedence layer supplied by the caller (declared / wellKnown / inferred). */
+type ManifestLayer = {
+    source: 'declared' | 'wellKnown' | 'inferred';
+    manifest: ManifestV1;
+};
+type ResolvedBoardPath = {
+    path: string;
+    source: 'declared' | 'wellKnown' | 'inferred' | 'canonical';
+    /** Set when the winning path came from falling through a broken template. */
+    fallback?: 'missing-param';
+};
+declare function createBoardLinkResolver(layers: readonly ManifestLayer[]): {
+    pathFor(role: RouteRole, params?: Record<string, string>): ResolvedBoardPath;
+};
+
+/**
+ * LNK-10 — pure history path matching for hosted rename 301s (ADR-0090 D7).
+ *
+ * Segment-wise matcher (no RegExp construction from templates). Templates
+ * are validated at write time but stay defensive here: any segment that
+ * does not start with ':' is a literal.
+ */
+
+/**
+ * Degrade target per role when captured params no longer resolve against
+ * the current template (302-class temporary redirect, never 404-from-history).
+ */
+declare const ROLE_INDEX_PATHS: Record<RouteRole, string>;
+/**
+ * Segment-wise match of `pathname` against a URLPattern-style `:param` template.
+ * Returns captured params or null.
+ *
+ * Contract: path segments arrive ALREADY decoded (Next.js `params.rest`,
+ * URL routers). This function does NOT call decodeURIComponent — a second
+ * decode would turn a once-decoded `%2F` into a literal `/` and enable
+ * open-redirect targets when substituted into param-leading templates.
+ *
+ * Defense in depth: any capture containing `/` or `\` is rejected (null).
+ */
+declare function matchPathToTemplate(template: string, pathname: string): Record<string, string> | null;
+type HistoryMatchEntry = {
+    role: RouteRole;
+    template: string;
+};
+type HistoryMatchResult = {
+    role: RouteRole;
+    template: string;
+    params: Record<string, string>;
+};
+/**
+ * First match wins — caller orders entries newest-first.
+ */
+declare function matchPathAgainstHistory(entries: readonly HistoryMatchEntry[], pathname: string): HistoryMatchResult | null;
+
+/**
+ * LNK-02 — shared types for the route-derivation adapter registry.
+ */
+type DerivedRoute = {
+    path: string;
+    navigable: boolean;
+    /**
+     * Originating file when the parser tracked it (worker compile path).
+     * Omitted from the navigator public contract via deriveRoutes strip.
+     */
+    sourcePath?: string;
+};
+type FrameworkId = 'tanstack' | 'next' | 'astro' | 'sveltekit' | 'nuxt' | 'react-router';
+
+/**
+ * Marker-file framework detection. Specificity order (first match wins):
+ * Explicit TanStack markers → Next → Astro → SvelteKit → Nuxt →
+ * marker-less TanStack fallback → react-router candidates → null.
+ *
+ * The marker-less TanStack heuristic (any src/routes/*.tsx|jsx) runs LAST
+ * among framework checks so a Next/Astro/SvelteKit/Nuxt repo with a stray
+ * src/routes helper is never misclassified (F1).
+ */
+
+declare function detectFramework(paths: string[]): FrameworkId | null;
+
+/**
+ * react-router pure parsers over provided FILE CONTENTS.
+ *
+ * Content-fetch is intentionally NOT wired into the navigator UI —
+ * LNK-02 only exposes these functions; UI wiring is a later ticket.
+ */
+
+/**
+ * Candidate source files that typically declare react-router routes.
+ * Matches App.* / *routes*.* / router.* (basename-based).
+ */
+declare function getReactRouterCandidatePaths(paths: string[]): string[];
+/**
+ * Extract routes from react-router source contents via tolerant regex.
+ * Supports `<Route path="...">` and `{ path: "..." }` object entries
+ * (createBrowserRouter form). Skips `*`. Dynamic segments → navigable false.
+ */
+declare function parseReactRouterRoutes(contents: string[]): DerivedRoute[];
+
+/**
+ * TanStack Start / TanStack Router file-based route conventions under
+ * `src/routes/`. Behavior preserved exactly from the CHR-03 parser.
+ *
+ *   - `index` → parent path (`src/routes/index.tsx` → `/`)
+ *   - dots nest (`jobs.index.tsx` → `/jobs`)
+ *   - `$param` → dynamic segment (`jobs.$jobId.tsx` → `/jobs/:jobId`)
+ *   - `__root` is layout only (skipped)
+ *   - `-` prefix excludes the file/folder
+ *   - `_` prefix is a pathless layout segment (stripped from the URL)
+ *
+ * Dynamic patterns are listed but not navigable in v1.
+ */
+
+declare function parseTanStackRoutes(paths: string[]): DerivedRoute[];
+
+/**
+ * Next.js app router + pages router parsers over a path listing.
+ *
+ * App: app/.../page.* (+ src/app), strip (group) and @slot,
+ * [param]→:param, [...slug]→*, skip app/api/... and _private.
+ *
+ * Pages: pages/... (+ src/pages), skip api + _app/_document/_error,
+ * index collapses, [param]→:param.
+ */
+
+declare function parseNextRoutes(paths: string[]): DerivedRoute[];
+
+/**
+ * Astro file-based routing under src/pages/ (default) or pages/
+ * when the tree has astro.config.* and no src/pages/ (srcDir-customized).
+ * Page extensions: .astro / .md / .mdx / .html.
+ * Skip _-prefixed and .../api/. Index collapses.
+ * [param]→:param, [...slug]→*, [[...slug]]→* (F5).
+ */
+
+declare function parseAstroRoutes(paths: string[]): DerivedRoute[];
+
+/**
+ * SvelteKit file-based routing: src/routes/.../+page.svelte
+ * and layout-reset +page@*.svelte only.
+ * (group) stripped, [param]→:param, [[...rest]]→*, dynamic ⇒ navigable false.
+ * +page.ts / +page.server.ts are load modules and derive nothing (F4).
+ */
+
+declare function parseSvelteKitRoutes(paths: string[]): DerivedRoute[];
+
+/**
+ * Nuxt file-based routing under pages/ (and src/pages/).
+ * [param]→:param, [[...slug]]→*, [[slug]]→:slug, index collapses.
+ * Dynamic ⇒ navigable false.
+ */
+
+declare function parseNuxtRoutes(paths: string[]): DerivedRoute[];
+
+/**
+ * LNK-02 — framework adapter registry entry.
+ *
+ * Detects the framework from a path listing, dispatches to the matching
+ * pure parser, returns DerivedRoute[] (path + navigable). Unknown → [].
+ *
+ * react-router content parsers are exported for later UI wiring; the
+ * path-only deriveRoutes entry returns [] for react-router-only trees.
+ *
+ * LNK-06: enumerateRouteEntries keeps sourcePath for marker harvest +
+ * compileManifest; deriveRoutes strips it so the navigator contract is
+ * unchanged (path + navigable only).
+ */
+
+/**
+ * Navigator contract: path + navigable only (CHR-03 / LNK-02 stable).
+ * sourcePath is intentionally stripped so existing equality fixtures hold.
+ */
+declare function deriveRoutes(paths: string[]): DerivedRoute[];
+/**
+ * LNK-06 compile path: URL template + sourcePath for marker harvest.
+ */
+declare function enumerateRouteEntries(paths: string[]): RouteEntry[];
+
+export { ClassifyResult, CompileResult, type DerivedRoute, type FrameworkId, type HistoryMatchEntry, type HistoryMatchResult, type ManifestLayer, ManifestV1, ROLE_INDEX_PATHS, type ResolvedBoardPath, RouteEntry, RouteRole, type TreeFile, ValidateManifestError, ValidateManifestResult, checkRoleTemplate, classifyRoutes, compileManifest, compileManifestFromTree, createBoardLinkResolver, deriveRoutes, detectFramework, enumerateRouteEntries, extractCavunoPageMarker, extractParamNames, getReactRouterCandidatePaths, matchPathAgainstHistory, matchPathToTemplate, parseAstroRoutes, parseNextRoutes, parseNuxtRoutes, parseReactRouterRoutes, parseSvelteKitRoutes, parseTanStackRoutes, sameParamSet, validateManifest };