@reactra/vite-plugin 0.1.0-alpha.0

package/dist/walker.d.ts

@@ -0,0 +1,332 @@
+import { type GraphCache } from "./graph-cache.ts";
+/**
+ * One discovered route. The walker emits these; the emitter formats them
+ * into the generated TS module.
+ *
+ * `importSpecifier` is a relative path with NO extension, suitable for
+ * inclusion in an `import X from "..."` line. Vite/TS resolves the actual
+ * extension at compile time.
+ *
+ * `componentIdentifier` is a PascalCase identifier safe to use as a JS
+ * variable name (no brackets, dots, or hyphens).
+ */
+/**
+ * One discovered store binding sourced from the sidecar index. Day 19 /
+ * Day 20 (`#5c`): the route manifest now ALSO exports a `STORES` array
+ * so `main.tsx` can do `configureStores({ stores: STORES })` instead of
+ * hand-importing each binding. The walker reuses the existing per-file
+ * sidecars (Day 14b writer + Day 15 reader) — every Reactra source that
+ * declares a store has a sidecar on disk listing it.
+ *
+ * `name` is the source-level store identifier (e.g. `counterStore`).
+ * `importSpecifier` is a `./`-prefixed path relative to `src/` with no
+ * extension — suitable for an `import { name } from "..."` line in
+ * `routeManifest.generated.ts`.
+ */
+export interface DiscoveredStore {
+    readonly name: string;
+    readonly importSpecifier: string;
+    /** Absolute source path. Surfaced for diagnostics + dup detection. */
+    readonly sourcePath: string;
+}
+/**
+ * One discovered service binding sourced from a source-scan of `src/`.
+ * Phase 3 — mirrors {@link DiscoveredStore}.
+ *
+ * The compiler force-exports every container it processes (MVP rule — Pass 9
+ * emits `export const name = …` unconditionally), so ALL declared services are
+ * importable as `import { name }` regardless of whether the source carries the
+ * `export` keyword. Therefore all declared services are collected here.
+ *
+ * When the compiler stops force-exporting (a future coordinated change),
+ * re-introduce an `exported=true` filter here and add a "non-exported
+ * service consumed cross-file" diagnostic. For now, collect all.
+ *
+ * `name` is the source-level service identifier (e.g. `authService`).
+ * `importSpecifier` is a `./`-prefixed path relative to `src/` with no
+ * extension — suitable for an `import { name } from "..."` line.
+ * `serviceModifier` is `"scoped"` or `"server"` when present; undefined for
+ * plain `service X {}`.
+ */
+export interface DiscoveredService {
+    readonly name: string;
+    readonly importSpecifier: string;
+    /** Absolute source path. Surfaced for diagnostics + dup detection. */
+    readonly sourcePath: string;
+    /** `"scoped"` | `"server"` | undefined. */
+    readonly serviceModifier?: string;
+}
+export interface DiscoveredRoute {
+    readonly id: string;
+    readonly path: string;
+    readonly filePath: string;
+    readonly importSpecifier: string;
+    readonly componentIdentifier: string;
+    /**
+     * Wave 3 §2b — the page's directory relative to `src/pages/`, with all
+     * original segments preserved (route groups `(group)` INCLUDED). This is
+     * the chain-match key used by {@link chainsForRoutes} so a
+     * `_middleware.ts` inside a group only applies to pages physically
+     * located inside that group, even though the URLs of those pages don't
+     * carry the group segment. Empty string for files directly under
+     * `src/pages/`. Optional on the type so hand-built fixtures may omit it
+     * (chain resolution treats `undefined` like `""` — root).
+     */
+    readonly fileDirRelativeToPages?: string;
+    /**
+     * Source name of the page's `export component Foo` declaration, used as
+     * the lookup key for `RouterRegistry.registerRouteBindings("Foo", …)`.
+     * Undefined when the page has no DSL `export component` (e.g. a plain
+     * React TSX page or an empty placeholder). Day 16 / `#18b`.
+     */
+    readonly bindingsName?: string;
+    /**
+     * The page's `query` declarations, source-scanned for the typed
+     * `RouteQuery` map (`#5c-typed-query`). `scanPages` always sets this
+     * (empty array when the page declares no query); optional on the type so
+     * hand-built route objects (tests, external callers) may omit it — the
+     * emitter treats a missing value as "no query schema".
+     */
+    readonly queries?: readonly RouteQueryDecl[];
+    /**
+     * The page's declared `prefetch on <trigger>` policy (Router §5.5), source-
+     * scanned. Emitted to the manifest as `prefetch: { trigger }` so a `RouteLink`
+     * with no `prefetch` prop inherits the destination's declared trigger.
+     * Undefined when the page declares no `prefetch`.
+     */
+    readonly prefetch?: "hover" | "visible" | "mount" | "none";
+    /**
+     * The nearest ancestor `_loading.tsx` for this page (Router §2.3) — used by
+     * the runtime as the route's `<Suspense>` fallback in place of the global
+     * `configureRouter({ loadingFallback })`. Walks UP from the page's directory
+     * to `src/pages/`; undefined if no ancestor declares one. The walker emits
+     * this as an eager import (the fallback must render synchronously).
+     */
+    readonly loading?: {
+        readonly specifier: string;
+        readonly identifier: string;
+    };
+    /**
+     * The nearest ancestor `_error.tsx` for this page (Router §2.3) — used by the
+     * runtime as the route's `<RouteErrorBoundary>` fallback (`{ error, reset }`
+     * props). Same nearest-wins walk as `loading`; eagerly imported (a lazy error
+     * UI that itself suspends would surface as a loading state during the error).
+     */
+    readonly errorBoundary?: {
+        readonly specifier: string;
+        readonly identifier: string;
+    };
+    /**
+     * The full ancestor chain of `_layout.tsx` files for this page (Router §2.3),
+     * **outermost first** — the runtime nests them around the page so the root
+     * layout is the outermost wrapper. Eagerly imported so layouts persist while
+     * the page below them streams in (the per-route Suspense sits INSIDE the
+     * innermost layout, so only the page area shows the loading fallback). Empty
+     * array when no `_layout.tsx` exists between the page and `src/pages/`.
+     */
+    readonly layouts?: ReadonlyArray<{
+        readonly specifier: string;
+        readonly identifier: string;
+    }>;
+}
+/**
+ * Convert a path relative to `src/pages/` into the URL pattern the router
+ * registers. Returns `null` for Phase-1-unsupported features, special
+ * filenames, and unsupported extensions.
+ *
+ * Examples:
+ *   "index.tsx"                  → "/"
+ *   "about.tsx"                  → "/about"
+ *   "customers/index.tsx"        → "/customers"
+ *   "customers/[id].tsx"         → "/customers/:id"
+ *   "customers/[id]/edit.tsx"    → "/customers/:id/edit"
+ *   "(auth)/login.tsx"           → "/login"      (route group — Wave 3 §2b)
+ *   "(marketing)/index.tsx"      → "/"           (route group at root)
+ *   "(auth)/dashboard/index.tsx" → "/dashboard"  (route group + nested)
+ *   "blog/[...slug].tsx"         → "/blog/*slug" (catch-all — Wave 3 §2b)
+ *   "[...rest].tsx"              → "/*rest"      (root catch-all)
+ *   "_middleware.ts"             → null  (special — Wave 3 §2b)
+ *   "README.md"                  → null  (unsupported extension)
+ *
+ * Catch-all constraints:
+ *   - `[...name]` must be the LAST segment (a mid-path catch-all is
+ *     rejected with `null`).
+ *   - `index` filename + catch-all not allowed
+ *     (`[...slug]/index.tsx` rejected).
+ */
+export declare const deriveRoutePath: (relativePath: string) => string | null;
+/**
+ * One `query` declaration on a page component. `#5c-typed-query`: feeds the
+ * generated `RouteQuery` map so `navigate(route, { query: { … } })` is checked
+ * against the page's declared query schema.
+ *
+ * `tsType` is the verbatim TS type text from the DSL declaration (e.g.
+ * `"string"`, `"number"`, `'"active" | "archived"'`); it defaults to
+ * `"string"` when the declaration omits the annotation. It is emitted
+ * verbatim into the generated `.ts` manifest.
+ *
+ * Phase 3: type alias of `QueryDecl` from extract.ts so the shape is
+ * shared. Kept as a separate exported name here for backward compat.
+ */
+export interface RouteQueryDecl {
+    readonly name: string;
+    readonly tsType: string;
+}
+/**
+ * Recursively scan `<projectRoot>/src/pages/` for page files. Files that
+ * `deriveRoutePath` returns `null` for are skipped. Returns the routes
+ * sorted by `path` so the generated manifest is byte-stable across runs.
+ *
+ * Tolerates a missing `src/pages/` directory (returns `[]`) — useful during
+ * a fresh `dev` boot before pages exist.
+ */
+export declare const scanPages: (projectRoot: string, cache?: GraphCache) => DiscoveredRoute[];
+/**
+ * Discover every store binding declared anywhere under `<projectRoot>/src/`
+ * by source-regex via `preprocess()` (cold-start safe). Returns a deterministic
+ * name-sorted list so the manifest renderer's output is byte-stable.
+ *
+ * **Collect ALL declared stores regardless of the source `export` keyword.**
+ * The compiler force-exports every container it processes (Pass 9 emits
+ * `export const name = …` unconditionally), so `session store X {}` and
+ * `route store X {}` are BOTH importable as `import { X }` — the walker must
+ * collect them. When the compiler stops force-exporting (a future coordinated
+ * change), re-introduce an `exported=true` filter and a "non-exported store
+ * consumed cross-file" diagnostic. For now, collect all.
+ *
+ * Phase 3: replaced the hand-rolled `STORE_DECL_RE` regex with `preprocess()`
+ * for v1+v2 dual-accept grammar. The `exported` field from `extractStoreNames`
+ * is available for diagnostics but is NOT used to filter here.
+ *
+ * Tolerates a missing `src/` directory (returns []).
+ */
+export declare const scanStores: (projectRoot: string, cache?: GraphCache) => DiscoveredStore[];
+/**
+ * Discover every service binding declared anywhere under
+ * `<projectRoot>/src/` by source-regex via `preprocess()` (cold-start safe).
+ * Returns a deterministic name-sorted list so the manifest renderer's output
+ * is byte-stable.
+ *
+ * **Collect ALL declared services regardless of the source `export` keyword.**
+ * Same force-export rationale as {@link scanStores} — see its JSDoc for the
+ * full explanation and the re-introduction trigger.
+ *
+ * Tolerates a missing `src/` directory (returns []).
+ */
+export declare const scanServices: (projectRoot: string, cache?: GraphCache) => DiscoveredService[];
+/**
+ * One injection site for an undeclared service — surfaced by
+ * {@link collectServiceInjectionDiagnostics} as a `console.warn` during
+ * manifest regen. Phase 3 (warn-only; no minted error code yet — deferred
+ * to Phase 6 per the brief).
+ */
+export interface ServiceInjectionDiagnostic {
+    /** The service name used in `inject service X`. */
+    readonly service: string;
+    /** The absolute path of the file containing the injection site. */
+    readonly file: string;
+}
+/**
+ * Walk `<projectRoot>/src/` and collect every `inject service X` site where
+ * `X` is NOT declared anywhere under `src/` (i.e. no `service X {}` or
+ * `export service X {}` block exists). Returns one diagnostic per injection
+ * site that references an undeclared name.
+ *
+ * Decision (brief §Step 5): warn-only — no minted error code. An `inject
+ * service X` where `X` is declared but non-exported is NOT a diagnostic
+ * (it's declared = configurable via hand-listed `configureServices`).
+ * `inject baseUrl from config("X")` carries `source:"config"`, not
+ * `kind:"service"`, so it is never counted.
+ *
+ * Tolerates a missing `src/` directory (returns []).
+ */
+export declare const collectServiceInjectionDiagnostics: (projectRoot: string, cache?: GraphCache) => ServiceInjectionDiagnostic[];
+/**
+ * One discovered `_middleware.ts` file. The walker captures these in a
+ * separate pass from {@link scanPages} (which deliberately skips them via
+ * `isSpecialSegment`) so the existing page-tree walk stays simple.
+ *
+ * `dirRelativeToPages` is the path under `src/pages/` where the middleware
+ * lives, normalised to forward slashes and WITHOUT the filename — it's the
+ * URL-prefix the middleware applies to. Examples:
+ *   `src/pages/_middleware.ts`           → ""           (applies to all routes)
+ *   `src/pages/dashboard/_middleware.ts` → "dashboard"  (applies to /dashboard/**)
+ *   `src/pages/c/[id]/_middleware.ts`    → "c/[id]"     (applies to /c/:id/**)
+ *
+ * `identifier` is a unique JS-safe name for the default-import line in the
+ * generated module.
+ */
+export interface DiscoveredMiddleware {
+    /** Path under `src/pages/` with the filename stripped. Empty = root. */
+    readonly dirRelativeToPages: string;
+    /** Absolute filesystem path of the `_middleware.ts` file. */
+    readonly sourcePath: string;
+    /** Import specifier relative to `src/` (no extension). */
+    readonly importSpecifier: string;
+    /** Unique JS identifier for the default-import line. */
+    readonly identifier: string;
+}
+/**
+ * Walk `<projectRoot>/src/pages/` for `_middleware.ts` files. Skips
+ * Phase-1-unsupported directory shapes (route groups `(group)/`,
+ * catch-alls `[...slug]/`, parallel routes `@x/`) the same way
+ * {@link scanPages} does — a middleware inside a Phase-1-excluded
+ * subtree wouldn't be exercisable until those features land.
+ *
+ * Multiple `_middleware.ts` files in the same directory aren't a
+ * supported case (per spec — one per dir); but if both `_middleware.ts`
+ * and `_middleware.tsx` exist, only the `.ts` is recognised (the
+ * EXT_PRIORITY array drives the lookup).
+ *
+ * Tolerates a missing `src/pages/` directory (returns []).
+ */
+export declare const scanMiddleware: (projectRoot: string) => DiscoveredMiddleware[];
+/**
+ * For every route in `routes`, compute the ordered list of `_middleware.ts`
+ * files that apply, root-first → leaf-last (spec §5.7 example). Pure —
+ * given the same inputs, produces the same chains, so the generated
+ * `router-middleware.generated.ts` is byte-stable.
+ *
+ * A middleware at directory `D` applies to a route at file directory `R`
+ * iff `D` is a prefix of `R` (`D === ""` always applies; `D === "dashboard"`
+ * applies to `dashboard/**`). The match treats path components atomically
+ * — `dash` does NOT prefix `dashboard`.
+ *
+ * Wave-3 §2b — route groups: the match is on FILE-TREE location, not URL
+ * prefix. `pages/(auth)/_middleware.ts` (dir `(auth)`) applies to
+ * `pages/(auth)/login.tsx` (URL `/login`) because the file lives inside
+ * `(auth)/`, even though the URL doesn't carry the group segment. Hand-
+ * built `DiscoveredRoute` fixtures without `fileDirRelativeToPages` fall
+ * back to root (`""`), preserving prior test behaviour.
+ */
+export declare const chainsForRoutes: (routes: readonly DiscoveredRoute[], middleware: readonly DiscoveredMiddleware[]) => Map<string, DiscoveredMiddleware[]>;
+/**
+ * Format the `router-middleware.generated.ts` module text per spec §6.4.
+ * Empty input (no `_middleware.ts` files OR no routes have a chain) emits
+ * a stub module with an empty map — importers don't break on a fresh
+ * clone before any middleware exists.
+ *
+ * Deviation from the spec's illustrative `MiddlewareFn[]` shape: we emit
+ * `MiddlewareDef[]` so both `beforeEnter` AND `afterLeave` are reachable
+ * from a single map. The runtime (Stage 3) iterates the def's `.beforeEnter`
+ * and `.afterLeave` properties directly.
+ */
+export declare const emitRouterMiddleware: (middleware: readonly DiscoveredMiddleware[], chains: ReadonlyMap<string, readonly DiscoveredMiddleware[]>) => string;
+/**
+ * Format the routeManifest.generated.ts module text. The output is what the
+ * vite plugin writes to `<projectRoot>/src/routeManifest.generated.ts` on
+ * `buildStart` and on subsequent `src/pages/` watcher events.
+ *
+ * Phase-1 shape: an untyped `ROUTES: RouteConfig[]` array. Typed `RouteId`
+ * / `RouteParams` / `RouteQuery` / `TypedNavigate` exports per Router §5.1
+ * land with #5c (typed query coercion needs the compiler to surface the
+ * `query` declarations into the manifest).
+ *
+ * Import strategy: Day 21 / `#18` — the compiler now also emits
+ * `export default Foo` for `export component Foo` (Pass-9 auto-default-
+ * export), so the manifest uses clean default imports
+ * (`import PageX from "..."`) and references them directly in the
+ * ROUTES array. The Day-13 `pickPageComponent` runtime helper is gone.
+ */
+export declare const emitRouteManifest: (routes: readonly DiscoveredRoute[], stores?: readonly DiscoveredStore[], services?: readonly DiscoveredService[]) => string;
+//# sourceMappingURL=walker.d.ts.map

package/dist/walker.d.ts.map

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