@hyperfixi/server-bridge 2.0.0

package/src/__tests__/conflict-detector.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from 'vitest';
+import { detectConflicts, formatConflicts } from '../scanner/conflict-detector.js';
+import type { RouteDescriptor } from '../types.js';
+
+function makeRoute(overrides: Partial<RouteDescriptor>): RouteDescriptor {
+  return {
+    path: '/api/users',
+    method: 'GET',
+    responseFormat: 'json',
+    source: { file: 'test.html', line: 1, kind: 'fetch', raw: 'fetch /api/users' },
+    pathParams: [],
+    handlerName: 'getApiUsers',
+    notes: [],
+    ...overrides,
+  };
+}
+
+describe('detectConflicts', () => {
+  it('returns empty array when no conflicts', () => {
+    const routes = [
+      makeRoute({ path: '/api/users', method: 'GET' }),
+      makeRoute({ path: '/api/posts', method: 'GET' }),
+    ];
+    expect(detectConflicts(routes)).toEqual([]);
+  });
+
+  it('returns empty array for single-occurrence routes', () => {
+    const routes = [makeRoute({})];
+    expect(detectConflicts(routes)).toEqual([]);
+  });
+
+  it('returns empty array when duplicates have same expectations', () => {
+    const routes = [
+      makeRoute({
+        responseFormat: 'json',
+        source: { file: 'a.html', line: 1, kind: 'fetch', raw: '' },
+      }),
+      makeRoute({
+        responseFormat: 'json',
+        source: { file: 'b.html', line: 2, kind: 'hx-attr', raw: '' },
+      }),
+    ];
+    expect(detectConflicts(routes)).toEqual([]);
+  });
+
+  it('detects responseFormat conflict', () => {
+    const routes = [
+      makeRoute({
+        responseFormat: 'json',
+        source: { file: 'a.html', line: 1, kind: 'fetch', raw: '' },
+      }),
+      makeRoute({
+        responseFormat: 'html',
+        source: { file: 'b.html', line: 2, kind: 'hx-attr', raw: '' },
+      }),
+    ];
+    const conflicts = detectConflicts(routes);
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0].routeKey).toBe('GET:/api/users');
+    expect(conflicts[0].conflicts[0].field).toBe('responseFormat');
+    expect(conflicts[0].sources).toHaveLength(2);
+  });
+
+  it('detects requestBody conflict on POST routes', () => {
+    const routes = [
+      makeRoute({
+        method: 'POST',
+        requestBody: [{ name: 'name', type: 'string', required: true }],
+        source: { file: 'a.html', line: 1, kind: 'fetch', raw: '' },
+      }),
+      makeRoute({
+        method: 'POST',
+        requestBody: [{ name: 'email', type: 'string', required: true }],
+        source: { file: 'b.html', line: 2, kind: 'hx-attr', raw: '' },
+      }),
+    ];
+    const conflicts = detectConflicts(routes);
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0].conflicts[0].field).toBe('requestBody');
+  });
+
+  it('detects queryParams conflict', () => {
+    const routes = [
+      makeRoute({
+        queryParams: [{ name: 'q', type: 'string', required: true }],
+        source: { file: 'a.html', line: 1, kind: 'fetch', raw: '' },
+      }),
+      makeRoute({
+        queryParams: [{ name: 'search', type: 'string', required: true }],
+        source: { file: 'b.html', line: 2, kind: 'hx-attr', raw: '' },
+      }),
+    ];
+    const conflicts = detectConflicts(routes);
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0].conflicts[0].field).toBe('queryParams');
+  });
+
+  it('ignores requestBody conflicts on GET routes', () => {
+    const routes = [
+      makeRoute({ method: 'GET', source: { file: 'a.html', line: 1, kind: 'fetch', raw: '' } }),
+      makeRoute({ method: 'GET', source: { file: 'b.html', line: 2, kind: 'hx-attr', raw: '' } }),
+    ];
+    expect(detectConflicts(routes)).toEqual([]);
+  });
+});
+
+describe('formatConflicts', () => {
+  it('formats conflict warnings for CLI output', () => {
+    const routes = [
+      makeRoute({
+        responseFormat: 'json',
+        source: { file: 'a.html', line: 1, kind: 'fetch', raw: '' },
+      }),
+      makeRoute({
+        responseFormat: 'html',
+        source: { file: 'b.html', line: 2, kind: 'hx-attr', raw: '' },
+      }),
+    ];
+    const conflicts = detectConflicts(routes);
+    const output = formatConflicts(conflicts);
+    expect(output).toContain('GET:/api/users');
+    expect(output).toContain('json vs html');
+    expect(output).toContain('a.html:1');
+    expect(output).toContain('b.html:2');
+  });
+});

package/src/__tests__/convention-engine.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import { inferConventions } from '../conventions/convention-engine.js';
+
+describe('inferConventions', () => {
+  it('defaults to GET + json', () => {
+    const result = inferConventions('/api/users');
+    expect(result.method).toBe('GET');
+    expect(result.responseFormat).toBe('json');
+    expect(result.handlerName).toBe('getApiUsers');
+  });
+
+  it('uses explicit method from hx-post', () => {
+    const result = inferConventions('/api/users', { explicitMethod: 'POST' });
+    expect(result.method).toBe('POST');
+    expect(result.handlerName).toBe('postApiUsers');
+  });
+
+  it('infers POST from form context', () => {
+    const result = inferConventions('/api/users', { elementTag: 'form' });
+    expect(result.method).toBe('POST');
+    expect(result.notes).toContain('Inferred POST from <form> context');
+  });
+
+  it('explicit method overrides form context', () => {
+    const result = inferConventions('/api/users', {
+      elementTag: 'form',
+      explicitMethod: 'PUT',
+    });
+    expect(result.method).toBe('PUT');
+  });
+
+  it('uses explicit response type from hyperscript', () => {
+    const result = inferConventions('/api/users', { fetchResponseType: 'html' });
+    expect(result.responseFormat).toBe('html');
+  });
+
+  it('infers html from URL pattern', () => {
+    const result = inferConventions('/pages/dashboard');
+    expect(result.responseFormat).toBe('html');
+    expect(result.notes).toContain('Inferred html response from URL pattern');
+  });
+
+  it('infers html from partials URL', () => {
+    const result = inferConventions('/partials/user-card');
+    expect(result.responseFormat).toBe('html');
+  });
+
+  it('handles unknown response type', () => {
+    const result = inferConventions('/api/data', { fetchResponseType: 'blob' });
+    expect(result.responseFormat).toBe('json');
+    expect(result.notes[0]).toMatch(/Unknown response type/);
+  });
+
+  it('generates correct handler name with params', () => {
+    const result = inferConventions('/api/users/:id', { explicitMethod: 'DELETE' });
+    expect(result.handlerName).toBe('deleteApiUsersById');
+  });
+});

package/src/__tests__/diff-command.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { diffRoutes, createManifest } from '../generators/manifest.js';
+import type { RouteDescriptor } from '../types.js';
+
+function makeRoute(overrides: Partial<RouteDescriptor>): RouteDescriptor {
+  return {
+    path: '/api/users',
+    method: 'GET',
+    responseFormat: 'json',
+    source: { file: 'test.html', line: 1, kind: 'fetch', raw: '' },
+    pathParams: [],
+    handlerName: 'getApiUsers',
+    notes: [],
+    ...overrides,
+  };
+}
+
+describe('diff command logic', () => {
+  it('detects added routes against empty manifest', () => {
+    const manifest = { version: 1, generatedAt: '2024-01-01', routes: {} };
+    const routes = [makeRoute({})];
+    const diff = diffRoutes(manifest, routes);
+    expect(diff.added).toHaveLength(1);
+    expect(diff.removed).toHaveLength(0);
+    expect(diff.changed).toHaveLength(0);
+    expect(diff.unchanged).toHaveLength(0);
+  });
+
+  it('detects removed routes', () => {
+    const routes = [makeRoute({})];
+    const manifest = createManifest(routes);
+    const diff = diffRoutes(manifest, []);
+    expect(diff.removed).toHaveLength(1);
+    expect(diff.added).toHaveLength(0);
+  });
+
+  it('detects changed routes (format changed)', () => {
+    const original = [makeRoute({ responseFormat: 'json' })];
+    const manifest = createManifest(original);
+    const updated = [makeRoute({ responseFormat: 'html' })];
+    const diff = diffRoutes(manifest, updated);
+    expect(diff.changed).toHaveLength(1);
+    expect(diff.unchanged).toHaveLength(0);
+  });
+
+  it('detects unchanged routes', () => {
+    const routes = [makeRoute({})];
+    const manifest = createManifest(routes);
+    const diff = diffRoutes(manifest, routes);
+    expect(diff.unchanged).toHaveLength(1);
+    expect(diff.added).toHaveLength(0);
+    expect(diff.changed).toHaveLength(0);
+    expect(diff.removed).toHaveLength(0);
+  });
+
+  it('handles null manifest (no previous generation)', () => {
+    const routes = [makeRoute({}), makeRoute({ path: '/api/posts' })];
+    const diff = diffRoutes(null, routes);
+    expect(diff.added).toHaveLength(2);
+  });
+
+  it('detects change when queryParams added', () => {
+    const original = [makeRoute({})];
+    const manifest = createManifest(original);
+    const updated = [makeRoute({ queryParams: [{ name: 'q', type: 'string', required: true }] })];
+    const diff = diffRoutes(manifest, updated);
+    expect(diff.changed).toHaveLength(1);
+  });
+});

package/src/__tests__/django-generator.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import { DjangoGenerator } from '../generators/django-generator.js';
+import type { RouteDescriptor } from '../types.js';
+
+function makeRoute(overrides: Partial<RouteDescriptor> = {}): RouteDescriptor {
+  return {
+    path: '/api/users',
+    method: 'GET',
+    responseFormat: 'json',
+    source: { file: 'test.html', line: 5, kind: 'fetch', raw: 'fetch /api/users' },
+    pathParams: [],
+    handlerName: 'getApiUsers',
+    notes: [],
+    ...overrides,
+  };
+}
+
+describe('DjangoGenerator', () => {
+  const gen = new DjangoGenerator();
+
+  it('has correct framework name', () => {
+    expect(gen.framework).toBe('django');
+  });
+
+  it('generates views.py, urls.py, __init__.py, and root urls.py', () => {
+    const result = gen.generate([makeRoute()], { outputDir: '/out' });
+    const paths = result.files.map(f => f.path);
+    expect(paths).toContain('api-users/views.py');
+    expect(paths).toContain('api-users/urls.py');
+    expect(paths).toContain('api-users/__init__.py');
+    expect(paths).toContain('urls.py');
+  });
+
+  it('generates a view function with snake_case name', () => {
+    const result = gen.generate([makeRoute()], { outputDir: '/out' });
+    const views = result.files.find(f => f.path.endsWith('views.py'))!;
+    expect(views.content).toContain('def get_api_users(request):');
+    expect(views.content).toContain("return JsonResponse({'message': 'Not implemented'})");
+  });
+
+  it('converts :param to <str:param> in urls.py', () => {
+    const route = makeRoute({
+      path: '/api/users/:id',
+      pathParams: ['id'],
+      handlerName: 'getApiUsersById',
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const urls = result.files.find(f => f.path === 'api-users/urls.py')!;
+    expect(urls.content).toContain("path('api/users/<str:id>'");
+    expect(urls.content).toContain('views.get_api_users_by_id');
+  });
+
+  it('includes path params in view function signature', () => {
+    const route = makeRoute({
+      path: '/api/users/:id',
+      pathParams: ['id'],
+      handlerName: 'getApiUsersById',
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const views = result.files.find(f => f.path.endsWith('views.py'))!;
+    expect(views.content).toContain('def get_api_users_by_id(request, id):');
+  });
+
+  it('adds require_http_methods decorator for non-GET routes', () => {
+    const route = makeRoute({ method: 'POST', handlerName: 'postApiUsers' });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const views = result.files.find(f => f.path.endsWith('views.py'))!;
+    expect(views.content).toContain('@require_http_methods(["POST"])');
+    expect(views.content).toContain(
+      'from django.views.decorators.http import require_http_methods'
+    );
+  });
+
+  it('parses request body for POST routes', () => {
+    const route = makeRoute({
+      method: 'POST',
+      handlerName: 'postApiUsers',
+      requestBody: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'email', type: 'string', required: true },
+      ],
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const views = result.files.find(f => f.path.endsWith('views.py'))!;
+    expect(views.content).toContain('import json');
+    expect(views.content).toContain('data = json.loads(request.body)');
+    expect(views.content).toContain("name = data.get('name')");
+    expect(views.content).toContain("email = data.get('email')");
+  });
+
+  it('generates HTML response for html format', () => {
+    const route = makeRoute({ responseFormat: 'html' });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const views = result.files.find(f => f.path.endsWith('views.py'))!;
+    expect(views.content).toContain("return HttpResponse('<div>Not implemented</div>')");
+  });
+
+  it('generates root urls.py with include()', () => {
+    const result = gen.generate([makeRoute()], { outputDir: '/out' });
+    const rootUrls = result.files.find(f => f.path === 'urls.py')!;
+    expect(rootUrls.content).toContain('from django.urls import path, include');
+    expect(rootUrls.content).toContain("include('api-users.urls')");
+  });
+
+  it('generates query param extraction', () => {
+    const route = makeRoute({
+      path: '/api/search',
+      handlerName: 'getApiSearch',
+      queryParams: [{ name: 'q', type: 'string', required: true }],
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const views = result.files.find(f => f.path.endsWith('views.py'))!;
+    expect(views.content).toContain("q = request.GET.get('q')");
+  });
+
+  it('warns when no routes provided', () => {
+    const result = gen.generate([], { outputDir: '/out' });
+    expect(result.warnings).toContain('No routes to generate');
+    expect(result.files).toHaveLength(0);
+  });
+
+  it('includes serverbridge markers', () => {
+    const result = gen.generate([makeRoute()], { outputDir: '/out' });
+    const views = result.files.find(f => f.path.endsWith('views.py'))!;
+    expect(views.content).toContain('# @serverbridge-route: GET /api/users');
+    expect(views.content).toContain('# @serverbridge-user-start');
+    expect(views.content).toContain('# @serverbridge-user-end');
+  });
+});

package/src/__tests__/express-generator.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect } from 'vitest';
+import { ExpressGenerator } from '../generators/express-generator.js';
+import type { RouteDescriptor } from '../types.js';
+
+function makeRoute(overrides: Partial<RouteDescriptor> = {}): RouteDescriptor {
+  return {
+    path: '/api/users',
+    method: 'GET',
+    responseFormat: 'json',
+    source: { file: 'test.html', kind: 'fetch', raw: 'fetch /api/users' },
+    pathParams: [],
+    handlerName: 'getApiUsers',
+    notes: [],
+    ...overrides,
+  };
+}
+
+describe('ExpressGenerator', () => {
+  const gen = new ExpressGenerator();
+
+  it('has correct framework name', () => {
+    expect(gen.framework).toBe('express');
+  });
+
+  it('generates route files for a GET endpoint', () => {
+    const result = gen.generate([makeRoute()], { outputDir: '/out' });
+    expect(result.files.length).toBeGreaterThanOrEqual(2); // router file + index
+    const routerFile = result.files.find(f => f.path.includes('api-users'));
+    expect(routerFile).toBeDefined();
+    expect(routerFile!.content).toContain("router.get('/api/users'");
+    expect(routerFile!.content).toContain('// @serverbridge-route: GET /api/users');
+    expect(routerFile!.content).toContain('// @serverbridge-user-start');
+    expect(routerFile!.content).toContain('// @serverbridge-user-end');
+    expect(routerFile!.content).toContain("res.json({ message: 'Not implemented' })");
+  });
+
+  it('generates POST route with body destructuring', () => {
+    const route = makeRoute({
+      path: '/api/users',
+      method: 'POST',
+      handlerName: 'postApiUsers',
+      requestBody: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'email', type: 'string', required: true },
+      ],
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const routerFile = result.files.find(f => f.path.includes('api-users'));
+    expect(routerFile!.content).toContain("router.post('/api/users'");
+    expect(routerFile!.content).toContain('const { name, email } = req.body;');
+    expect(routerFile!.content).toContain('// Expected body: { name: string, email: string }');
+  });
+
+  it('generates route with path params', () => {
+    const route = makeRoute({
+      path: '/api/users/:id',
+      pathParams: ['id'],
+      handlerName: 'getApiUsersById',
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const routerFile = result.files.find(f => f.path.includes('api-users'));
+    expect(routerFile!.content).toContain('const { id } = req.params;');
+  });
+
+  it('generates html response for html format', () => {
+    const route = makeRoute({ responseFormat: 'html' });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const routerFile = result.files.find(f => f.path.includes('api-users'));
+    expect(routerFile!.content).toContain("res.send('<div>Not implemented</div>')");
+  });
+
+  it('generates index file that imports all routers', () => {
+    const routes = [
+      makeRoute({ path: '/api/users' }),
+      makeRoute({ path: '/api/products', handlerName: 'getApiProducts' }),
+    ];
+    const result = gen.generate(routes, { outputDir: '/out' });
+    const indexFile = result.files.find(f => f.path.endsWith('index.ts'));
+    expect(indexFile).toBeDefined();
+    expect(indexFile!.content).toContain("import apiUsersRouter from './api-users.js'");
+    expect(indexFile!.content).toContain("import apiProductsRouter from './api-products.js'");
+    expect(indexFile!.content).toContain('router.use(apiUsersRouter)');
+    expect(indexFile!.content).toContain('router.use(apiProductsRouter)');
+  });
+
+  it('generates query param destructuring', () => {
+    const route = makeRoute({
+      path: '/api/search',
+      handlerName: 'getApiSearch',
+      queryParams: [
+        { name: 'q', type: 'string', required: true },
+        { name: 'limit', type: 'string', required: true },
+      ],
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const routerFile = result.files.find(f => f.path.includes('api-search'));
+    expect(routerFile!.content).toContain('const { q, limit } = req.query;');
+  });
+
+  it('warns when no routes provided', () => {
+    const result = gen.generate([], { outputDir: '/out' });
+    expect(result.warnings).toContain('No routes to generate');
+    expect(result.files).toHaveLength(0);
+  });
+});

package/src/__tests__/fastapi-generator.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect } from 'vitest';
+import { FastAPIGenerator } from '../generators/fastapi-generator.js';
+import type { RouteDescriptor } from '../types.js';
+
+function makeRoute(overrides: Partial<RouteDescriptor> = {}): RouteDescriptor {
+  return {
+    path: '/api/users',
+    method: 'GET',
+    responseFormat: 'json',
+    source: { file: 'test.html', line: 5, kind: 'fetch', raw: 'fetch /api/users' },
+    pathParams: [],
+    handlerName: 'getApiUsers',
+    notes: [],
+    ...overrides,
+  };
+}
+
+describe('FastAPIGenerator', () => {
+  const gen = new FastAPIGenerator();
+
+  it('has correct framework name', () => {
+    expect(gen.framework).toBe('fastapi');
+  });
+
+  it('generates router files and main.py', () => {
+    const result = gen.generate([makeRoute()], { outputDir: '/out' });
+    const paths = result.files.map(f => f.path);
+    expect(paths).toContain('routers/api_users.py');
+    expect(paths).toContain('main.py');
+  });
+
+  it('generates async endpoint with snake_case name', () => {
+    const result = gen.generate([makeRoute()], { outputDir: '/out' });
+    const router = result.files.find(f => f.path.endsWith('api_users.py'))!;
+    expect(router.content).toContain("@router.get('/api/users')");
+    expect(router.content).toContain('async def get_api_users():');
+    expect(router.content).toContain("return {'message': 'Not implemented'}");
+  });
+
+  it('converts :param to {param} in paths', () => {
+    const route = makeRoute({
+      path: '/api/users/:id',
+      pathParams: ['id'],
+      handlerName: 'getApiUsersById',
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const router = result.files.find(f => f.path.endsWith('api_users.py'))!;
+    expect(router.content).toContain("@router.get('/api/users/{id}')");
+    expect(router.content).toContain('async def get_api_users_by_id(id: str):');
+  });
+
+  it('generates Pydantic model for POST routes with body', () => {
+    const route = makeRoute({
+      method: 'POST',
+      handlerName: 'postApiUsers',
+      requestBody: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'email', type: 'string', required: true },
+        { name: 'age', type: 'number', required: false },
+      ],
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+
+    // Should generate models.py
+    const models = result.files.find(f => f.path === 'models.py')!;
+    expect(models).toBeDefined();
+    expect(models.content).toContain('from pydantic import BaseModel');
+    expect(models.content).toContain('class PostApiUsersBody(BaseModel):');
+    expect(models.content).toContain('name: str');
+    expect(models.content).toContain('email: str');
+    expect(models.content).toContain('age: Optional[int] = None');
+
+    // Router should reference the model
+    const router = result.files.find(f => f.path.endsWith('api_users.py'))!;
+    expect(router.content).toContain('from ..models import PostApiUsersBody');
+    expect(router.content).toContain('body: PostApiUsersBody');
+  });
+
+  it('does not generate models.py when no routes have bodies', () => {
+    const result = gen.generate([makeRoute()], { outputDir: '/out' });
+    const models = result.files.find(f => f.path === 'models.py');
+    expect(models).toBeUndefined();
+  });
+
+  it('uses HTMLResponse for html format', () => {
+    const route = makeRoute({ responseFormat: 'html' });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const router = result.files.find(f => f.path.endsWith('api_users.py'))!;
+    expect(router.content).toContain('from fastapi.responses import HTMLResponse');
+    expect(router.content).toContain("return '<div>Not implemented</div>'");
+  });
+
+  it('generates main.py with include_router', () => {
+    const result = gen.generate([makeRoute()], { outputDir: '/out' });
+    const main = result.files.find(f => f.path === 'main.py')!;
+    expect(main.content).toContain('from fastapi import FastAPI');
+    expect(main.content).toContain('app = FastAPI()');
+    expect(main.content).toContain('app.include_router(api_users_router)');
+  });
+
+  it('generates Query() params in function signature', () => {
+    const route = makeRoute({
+      path: '/api/search',
+      handlerName: 'getApiSearch',
+      queryParams: [{ name: 'q', type: 'string', required: true }],
+    });
+    const result = gen.generate([route], { outputDir: '/out' });
+    const router = result.files.find(f => f.path.endsWith('api_search.py'))!;
+    expect(router.content).toContain('q: str = Query(...)');
+  });
+
+  it('warns when no routes provided', () => {
+    const result = gen.generate([], { outputDir: '/out' });
+    expect(result.warnings).toContain('No routes to generate');
+    expect(result.files).toHaveLength(0);
+  });
+
+  it('includes serverbridge markers', () => {
+    const result = gen.generate([makeRoute()], { outputDir: '/out' });
+    const router = result.files.find(f => f.path.endsWith('api_users.py'))!;
+    expect(router.content).toContain('# @serverbridge-route: GET /api/users');
+    expect(router.content).toContain('# @serverbridge-user-start');
+    expect(router.content).toContain('# @serverbridge-user-end');
+  });
+});