@shipfox/client-shell 0.2.0

package/src/vite/evaluate-features.test.ts

@@ -0,0 +1,34 @@
+import {mkdtemp, realpath, rm, writeFile} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {evaluateFeatures, invalidateFeatures} from './evaluate-features.js';
+
+describe('evaluateFeatures', () => {
+  let directory: string;
+
+  beforeEach(async () => {
+    directory = await mkdtemp(join(tmpdir(), 'shipfox-client-shell-vite-'));
+  });
+
+  afterEach(async () => {
+    await rm(directory, {recursive: true, force: true});
+  });
+
+  test('returns dependencies that were cached before the manifest reload', async () => {
+    const features = join(directory, 'features.ts');
+    const contribution = join(directory, 'contribution.ts');
+    await writeFile(
+      features,
+      `import {feature} from './contribution.ts';
+export const features = [feature];`,
+    );
+    await writeFile(contribution, `export const feature = {id: 'acme.projects'};`);
+
+    await evaluateFeatures(features);
+    invalidateFeatures([await realpath(features)]);
+
+    const evaluated = await evaluateFeatures(features);
+
+    expect(evaluated.loadedFiles).toContain(await realpath(contribution));
+  });
+});

package/src/vite/evaluate-features.ts

@@ -0,0 +1,93 @@
+import {readFile, realpath} from 'node:fs/promises';
+import {createRequire} from 'node:module';
+import {resolve} from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {createJiti} from 'jiti';
+import type {ClientFeature} from '#contract.js';
+
+const require = createRequire(import.meta.url);
+const importPattern =
+  /(?:\b(?:import|export)\s+(?:[^'"]*?\s+from\s+)?|\bimport\s*\(\s*)['"]([^'"]+)['"]/g;
+const nodeModulesPathPattern = /[\\/]node_modules[\\/]/;
+
+export interface EvaluatedFeatures {
+  features: readonly ClientFeature[];
+  loadedFiles: readonly string[];
+}
+
+export function invalidateFeatures(loadedFiles: Iterable<string>): void {
+  for (const file of loadedFiles) delete require.cache[file];
+}
+
+function loadedModuleGraph(entry: string): string[] {
+  const files = new Set<string>();
+
+  function visit(file: string): void {
+    if (files.has(file)) return;
+    files.add(file);
+    for (const child of require.cache[file]?.children ?? []) visit(child.filename);
+  }
+
+  visit(entry);
+  return [...files];
+}
+
+async function staticallyImportedModules(
+  entry: string,
+  jiti: ReturnType<typeof createJiti>,
+): Promise<string[]> {
+  const files = new Set<string>();
+
+  async function visit(file: string): Promise<void> {
+    const path = file.startsWith('file:') ? fileURLToPath(file) : file;
+    if (path.startsWith('node:') || nodeModulesPathPattern.test(path) || files.has(path)) return;
+    const resolvedPath = await realpath(path).catch(() => path);
+    files.add(resolvedPath);
+    const source = await readFile(resolvedPath, 'utf8').catch(() => undefined);
+    if (!source) return;
+
+    for (const match of source.matchAll(importPattern)) {
+      const specifier = match[1];
+      if (!specifier) continue;
+      const dependency = jiti.esmResolve(specifier, {
+        parentURL: pathToFileURL(resolvedPath),
+        try: true,
+      });
+      if (dependency) await visit(dependency);
+    }
+  }
+
+  await visit(entry);
+  return [...files];
+}
+
+export async function evaluateFeatures(featuresModule: string): Promise<EvaluatedFeatures> {
+  const resolvedFeaturesModule = await realpath(resolve(featuresModule));
+  const jiti = createJiti(resolvedFeaturesModule, {interopDefault: false, tsconfigPaths: true});
+  let module: {default?: unknown; features?: unknown};
+  let loadedFiles: string[];
+  try {
+    module = jiti(resolvedFeaturesModule) as {default?: unknown; features?: unknown};
+    loadedFiles = [
+      ...new Set([
+        ...loadedModuleGraph(resolvedFeaturesModule),
+        ...(await staticallyImportedModules(resolvedFeaturesModule, jiti)),
+      ]),
+    ];
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to evaluate features module "${resolvedFeaturesModule}". Features modules must be Node-safe: ${message}`,
+      {cause: error},
+    );
+  }
+
+  const features = module.features ?? module.default;
+  if (!Array.isArray(features)) {
+    throw new TypeError(
+      `Features module "${resolvedFeaturesModule}" must export a features array.`,
+    );
+  }
+
+  return {features: features as readonly ClientFeature[], loadedFiles};
+}

package/src/vite/generate.test.ts

@@ -0,0 +1,22 @@
+import {readFile} from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+import {composeRoutes} from '#compose/compose-routes.js';
+import {navigationEntries, settingsEntries} from '#runtime/registries.js';
+import {features} from '#test/fixtures/features.js';
+import {generateAppModule} from './generate.js';
+
+const goldenFile = fileURLToPath(
+  new URL('../../test/typecheck/shipfox-app.gen.ts', import.meta.url),
+);
+
+describe('generateAppModule', () => {
+  test('matches the checked composition fixture', async () => {
+    const generated = generateAppModule({
+      routes: composeRoutes(features),
+      navigation: navigationEntries(features),
+      settingsSections: settingsEntries(features),
+    });
+
+    await expect(readFile(goldenFile, 'utf8')).resolves.toBe(generated);
+  });
+});

package/src/vite/generate.ts

@@ -0,0 +1,99 @@
+import type {ComposedRoute} from '#compose/compose-routes.js';
+import type {NavTabEntry, SettingsSectionEntry} from '#contract.js';
+import {routePathForAnchor} from '#runtime/anchor-paths.js';
+
+export interface GenerateAppModuleOptions {
+  routes: readonly ComposedRoute[];
+  navigation: readonly NavTabEntry[];
+  settingsSections: readonly SettingsSectionEntry[];
+}
+
+function literal(value: unknown): string {
+  return JSON.stringify(value, undefined, 2);
+}
+
+function indentedLiteral(value: unknown, indentation: number): string {
+  return literal(value).replaceAll('\n', `\n${' '.repeat(indentation)}`);
+}
+
+function routeNames(routes: readonly ComposedRoute[], parent: ComposedRoute['parent']): string {
+  return routes
+    .map((route, index) => ({route, index}))
+    .filter(({route}) => route.parent === parent)
+    .map(({index}) => `route${index}`)
+    .join(', ');
+}
+
+export function generateAppModule({
+  routes,
+  navigation,
+  settingsSections,
+}: GenerateAppModuleOptions): string {
+  const generatedRoutes = routes.map((route) => ({
+    ...route,
+    routePath: routePathForAnchor(route.parent, route.path),
+  }));
+  const imports = routes
+    .map((route, index) => `import route${index}Impl from ${literal(route.impl)};`)
+    .join('\n');
+  const routeDeclarations = generatedRoutes
+    .map(
+      (route, index) => `const route${index} = createRoute({
+  getParentRoute: () => ${route.parent === 'root' ? 'skeleton.rootRoute' : `skeleton.${route.parent}`},
+  path: ${literal(route.routePath)},
+  ...routeOptions(route${index}Impl, ${literal(route.impl)}, ${literal(route.path)}),
+});`,
+    )
+    .join('\n\n');
+  const rootRoutes = routeNames(generatedRoutes, 'root');
+  const workspaceLayoutRoutes = routeNames(generatedRoutes, 'workspaceLayout');
+  const projectLayoutRoutes = routeNames(generatedRoutes, 'projectLayout');
+  const workspaceSettingsRoutes = routeNames(generatedRoutes, 'workspaceSettings');
+  const rootChildren = [rootRoutes, 'workspaceLayout'].filter(Boolean).join(',\n  ');
+
+  return `// GENERATED by @shipfox/client-shell/vite. Do not edit.
+// biome-ignore-all format: generated code has stable, reviewable output.
+// biome-ignore-all assist/source/organizeImports: generated imports follow route order.
+import {createRoute, createRouter} from '@tanstack/react-router';
+import {buildAnchorSkeleton, isRouteImpl, type RouteImpl, type RouterContext} from '@shipfox/client-shell/runtime';
+${imports}
+
+function routeOptions<T extends RouteImpl>(routeImpl: T, impl: string, path: string): T['options'] {
+  if (!isRouteImpl(routeImpl)) {
+    throw new TypeError(\`Route implementation "\${impl}" for "\${path}" must export default defineRoute(...).\`);
+  }
+  return routeImpl.options;
+}
+
+const skeleton = buildAnchorSkeleton({
+  navigation: ${indentedLiteral(navigation, 2)},
+  settingsSections: ${indentedLiteral(settingsSections, 2)},
+});
+
+${routeDeclarations}
+
+const projectLayout = skeleton.projectLayout.addChildren([${projectLayoutRoutes}]);
+const workspaceSettings = skeleton.workspaceSettings.addChildren([${workspaceSettingsRoutes}]);
+const workspaceLayout = skeleton.workspaceLayout.addChildren([
+  ${workspaceLayoutRoutes}${workspaceLayoutRoutes ? ',' : ''}
+  projectLayout,
+  workspaceSettings,
+]);
+
+export const routeTree = skeleton.rootRoute.addChildren([
+  ${rootChildren},
+]);
+
+export const router = createRouter({
+  routeTree,
+  context: {auth: undefined, queryClient: undefined} satisfies RouterContext,
+  scrollRestoration: true,
+});
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router;
+  }
+}
+`;
+}

package/src/vite/generated-router.test.tsx

@@ -0,0 +1,58 @@
+import {QueryClient} from '@tanstack/react-query';
+import {createMemoryHistory, Outlet, RouterProvider} from '@tanstack/react-router';
+import {render, screen} from '@testing-library/react';
+import {createStore} from 'jotai';
+import {authStateAtom} from '#runtime/auth.js';
+import {type AuthStateValue, ChromeProvider, type ChromeSlots} from '#runtime/index.js';
+import {ShellProviderStack} from '#runtime/provider-stack.js';
+import {router} from '#test/typecheck/shipfox-app.gen.js';
+
+describe('generated composition router', () => {
+  test('renders added and overridden routes', async () => {
+    const auth: AuthStateValue = {
+      status: 'authenticated',
+      workspaces: [{id: 'workspace', name: 'Workspace', membershipId: 'membership'}],
+      isLoading: false,
+      isAuthenticated: true,
+      hasWorkspace: true,
+    };
+    const chrome: ChromeSlots = {
+      ProjectBreadcrumb: () => null,
+      ProjectLayoutGuard: Outlet,
+    };
+    const queryClient = new QueryClient();
+    const store = createStore();
+    store.set(authStateAtom, auth);
+    router.update({
+      history: createMemoryHistory({initialEntries: ['/workspaces/workspace/insights']}),
+      context: {
+        auth,
+        queryClient,
+        workspaceSetup: async () => ({hideProjectNavigation: false}),
+      },
+    });
+
+    render(
+      <ChromeProvider chrome={chrome}>
+        <ShellProviderStack
+          features={[]}
+          queryClient={queryClient}
+          store={store}
+          auth={{effects: false}}
+        >
+          <RouterProvider router={router} />
+        </ShellProviderStack>
+      </ChromeProvider>,
+    );
+
+    expect(await screen.findByText('Named route')).toBeVisible();
+
+    await router.navigate({
+      to: '/workspaces/$wid/projects/$pid/overview',
+      params: {wid: 'workspace', pid: 'project'},
+      search: {tab: 'overview'},
+    });
+
+    expect(await screen.findByText('Search route')).toBeVisible();
+  });
+});

package/src/vite/index.ts

@@ -0,0 +1 @@
+export {shipfoxClientComposition} from './plugin.js';

package/src/vite/plugin.test.ts

@@ -0,0 +1,181 @@
+import {mkdtemp, readFile, realpath, rm, writeFile} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import type {Plugin, ResolvedConfig} from 'vite';
+import {shipfoxClientComposition} from './plugin.js';
+
+const fixtureFeatures = fileURLToPath(new URL('../../test/fixtures/features.ts', import.meta.url));
+const testDirectory = fileURLToPath(new URL('../../test', import.meta.url));
+
+type HookHandler<T> = T extends {handler: infer Handler} ? Handler : T;
+type BuildStartOptions = Parameters<HookHandler<NonNullable<Plugin['buildStart']>>>[0];
+type ConfigResolvedHandler = (config: ResolvedConfig) => void | Promise<void>;
+
+function hookHandler<T>(hook: T): HookHandler<T> {
+  return (
+    typeof hook === 'object' && hook !== null && 'handler' in hook ? hook.handler : hook
+  ) as HookHandler<T>;
+}
+
+function configResolvedHandler(hook: NonNullable<Plugin['configResolved']>): ConfigResolvedHandler {
+  return hookHandler(hook) as ConfigResolvedHandler;
+}
+
+function configure(plugin: Plugin): void {
+  if (!plugin.configResolved) {
+    throw new Error('Expected the composition plugin to implement configResolved.');
+  }
+  configResolvedHandler(plugin.configResolved)({
+    root: process.cwd(),
+  } as ResolvedConfig);
+}
+
+function resolveRouteImplementation(source: string): string | undefined {
+  const files: Record<string, string> = {
+    '#test/default-route-impl.js': join(testDirectory, 'default-route-impl.tsx'),
+    '#test/named-route-impl.js': join(testDirectory, 'named-route-impl.tsx'),
+    '#test/not-route-impl.js': join(testDirectory, 'not-route-impl.ts'),
+    '#test/search-route-impl.js': join(testDirectory, 'search-route-impl.tsx'),
+  };
+  return files[source];
+}
+
+function pluginContext() {
+  const watchedFiles: string[] = [];
+  return {
+    watchedFiles,
+    addWatchFile(file: string) {
+      watchedFiles.push(file);
+    },
+    resolve(source: string) {
+      const id = resolveRouteImplementation(source);
+      return Promise.resolve(id ? {id} : null);
+    },
+    environment: {
+      pluginContainer: {
+        resolveId(source: string) {
+          const id = resolveRouteImplementation(source);
+          return Promise.resolve(id ? {id} : null);
+        },
+      },
+    },
+  };
+}
+
+async function build(plugin: Plugin, context: ReturnType<typeof pluginContext>): Promise<void> {
+  if (!plugin.buildStart) {
+    throw new Error('Expected the composition plugin to implement buildStart.');
+  }
+  await (
+    hookHandler(plugin.buildStart) as unknown as (
+      this: typeof context,
+      options: BuildStartOptions,
+    ) => Promise<void>
+  ).call(context, {} as BuildStartOptions);
+}
+
+describe('shipfoxClientComposition', () => {
+  let directory: string;
+
+  beforeEach(async () => {
+    directory = await mkdtemp(join(tmpdir(), 'shipfox-client-shell-vite-'));
+  });
+
+  afterEach(async () => {
+    await rm(directory, {recursive: true, force: true});
+  });
+
+  test('generates a static route tree and watches the manifest module graph', async () => {
+    const out = join(directory, 'shipfox-app.gen.ts');
+    const plugin = shipfoxClientComposition({features: fixtureFeatures, out});
+    const context = pluginContext();
+    configure(plugin);
+
+    await build(plugin, context);
+
+    await expect(readFile(out, 'utf8')).resolves.toContain(
+      'import route0Impl from "#test/search-route-impl.js";',
+    );
+    expect(context.watchedFiles).toContain(fixtureFeatures);
+  });
+
+  test('fails the Vite build with the shared collision message', async () => {
+    const features = join(directory, 'features.ts');
+    await writeFile(
+      features,
+      `export const features = [
+  {id: 'shipfox.projects', routes: [{path: '/projects', parent: 'root', impl: '#test/default-route-impl.js'}]},
+  {id: 'acme.projects', routes: [{path: '/projects', parent: 'root', impl: '#test/default-route-impl.js'}]},
+];`,
+    );
+    const plugin = shipfoxClientComposition({features, out: join(directory, 'shipfox-app.gen.ts')});
+    const context = pluginContext();
+    configure(plugin);
+
+    await expect(build(plugin, context)).rejects.toThrow(
+      'Route "/projects" is contributed by both features "shipfox.projects" and "acme.projects". Set override: true to replace it explicitly.',
+    );
+  });
+
+  test('rejects route implementations without a default export', async () => {
+    const features = join(directory, 'features.ts');
+    await writeFile(
+      features,
+      `export const features = [{id: 'acme.projects', routes: [{path: '/projects', parent: 'root', impl: '#test/not-route-impl.js'}]}];`,
+    );
+    const plugin = shipfoxClientComposition({features, out: join(directory, 'shipfox-app.gen.ts')});
+    const context = pluginContext();
+    configure(plugin);
+
+    await expect(build(plugin, context)).rejects.toThrow(
+      'Route implementation "#test/not-route-impl.js" for "/projects" must export default defineRoute(...).',
+    );
+  });
+
+  test('regenerates when a watched manifest changes', async () => {
+    const features = join(directory, 'features.ts');
+    const contribution = join(directory, 'contribution.ts');
+    const out = join(directory, 'shipfox-app.gen.ts');
+    await writeFile(
+      features,
+      `import {feature} from './contribution.ts';
+export const features = [feature];`,
+    );
+    await writeFile(
+      contribution,
+      `export const feature = {id: 'acme.insights', routes: [{path: '/insights', parent: 'root', impl: '#test/default-route-impl.js'}]};`,
+    );
+    const plugin = shipfoxClientComposition({features, out});
+    const context = pluginContext();
+    configure(plugin);
+
+    await build(plugin, context);
+    expect(context.watchedFiles).toContain(await realpath(contribution));
+    await writeFile(
+      contribution,
+      `export const feature = {id: 'acme.reports', routes: [{path: '/reports', parent: 'root', impl: '#test/default-route-impl.js'}]};`,
+    );
+    const hotUpdateContext = {environment: context.environment};
+    await (
+      plugin.hotUpdate as unknown as (
+        this: typeof hotUpdateContext,
+        options: {
+          file: string;
+          server: {watcher: {add(file: string): void}};
+        },
+      ) => Promise<void>
+    ).call(hotUpdateContext, {
+      file: contribution,
+      server: {
+        watcher: {
+          add(file: string) {
+            context.watchedFiles.push(file);
+          },
+        },
+      },
+    });
+
+    await expect(readFile(out, 'utf8')).resolves.toContain('path: "/reports"');
+  });
+});

package/src/vite/plugin.ts

@@ -0,0 +1,114 @@
+import {mkdir, readFile, realpath, writeFile} from 'node:fs/promises';
+import {dirname, resolve} from 'node:path';
+import type {Plugin, ResolvedConfig} from 'vite';
+import {composeRoutes} from '#compose/compose-routes.js';
+import {mergeConfigShapes} from '#compose/merge-config.js';
+import {validateProviderIds} from '#compose/validate-providers.js';
+import {validateNavigation, validateSettingsSections} from '#compose/validate-registries.js';
+import {navigationEntries, settingsEntries} from '#runtime/registries.js';
+import {evaluateFeatures, invalidateFeatures} from './evaluate-features.js';
+import {generateAppModule} from './generate.js';
+
+const defaultExportPattern = /\bexport\s+default\b|\bexport\s*\{[\s\S]*?\bas\s+default\b[\s\S]*?\}/;
+
+export interface ShipfoxClientCompositionOptions {
+  features: string;
+  out?: string;
+}
+
+type RouteResolver = (source: string, importer?: string) => Promise<{id: string} | null>;
+
+function hasDefaultExport(source: string): boolean {
+  return defaultExportPattern.test(source);
+}
+
+export function shipfoxClientComposition({
+  features,
+  out = './src/shipfox-app.gen.ts',
+}: ShipfoxClientCompositionOptions): Plugin {
+  let config: ResolvedConfig | undefined;
+  let watchedFiles = new Set<string>();
+
+  const outputPath = () => resolve(config?.root ?? process.cwd(), out);
+  const featuresPath = () => resolve(config?.root ?? process.cwd(), features);
+
+  async function assertDefaultRouteExports(
+    resolveRoute: RouteResolver,
+    routes: ReturnType<typeof composeRoutes>,
+  ): Promise<void> {
+    for (const route of routes) {
+      const resolvedRoute = await resolveRoute(route.impl, outputPath());
+      if (!resolvedRoute) {
+        throw new Error(
+          `Could not resolve route implementation "${route.impl}" for "${route.path}".`,
+        );
+      }
+      const source = await readFile(resolvedRoute.id, 'utf8');
+      if (!hasDefaultExport(source)) {
+        throw new Error(
+          `Route implementation "${route.impl}" for "${route.path}" must export default defineRoute(...).`,
+        );
+      }
+    }
+  }
+
+  async function generate({
+    addWatchFile,
+    resolveRoute,
+  }: {
+    addWatchFile(file: string): void;
+    resolveRoute: RouteResolver;
+  }): Promise<void> {
+    invalidateFeatures(watchedFiles);
+    const evaluated = await evaluateFeatures(featuresPath());
+    const routes = composeRoutes(evaluated.features);
+    validateProviderIds(evaluated.features);
+    validateNavigation(
+      evaluated.features,
+      routes.map((route) => route.path),
+    );
+    validateSettingsSections(
+      evaluated.features,
+      routes.map((route) => route.path),
+    );
+    mergeConfigShapes(evaluated.features);
+    await assertDefaultRouteExports(resolveRoute, routes);
+
+    watchedFiles = new Set(evaluated.loadedFiles);
+    for (const file of watchedFiles) addWatchFile(file);
+
+    const output = generateAppModule({
+      routes,
+      navigation: navigationEntries(evaluated.features),
+      settingsSections: settingsEntries(evaluated.features),
+    });
+    const path = outputPath();
+    const existing = await readFile(path, 'utf8').catch(() => undefined);
+    if (existing === output) return;
+    await mkdir(dirname(path), {recursive: true});
+    await writeFile(path, output);
+  }
+
+  return {
+    name: 'shipfox-client-composition',
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+    },
+    async buildStart() {
+      await generate({
+        addWatchFile: this.addWatchFile.bind(this),
+        resolveRoute: this.resolve.bind(this),
+      });
+    },
+    async hotUpdate({file, server}) {
+      const resolvedFile = await realpath(file).catch(() => resolve(file));
+      if (!watchedFiles.has(resolvedFile)) return;
+      await generate({
+        addWatchFile: server.watcher.add.bind(server.watcher),
+        resolveRoute: this.environment.pluginContainer.resolveId.bind(
+          this.environment.pluginContainer,
+        ),
+      });
+    },
+  };
+}