@hyperfixi/server-bridge 2.0.0

package/src/generators/openapi-generator.ts

@@ -0,0 +1,259 @@
+import type { RouteDescriptor, GeneratorOptions, GenerateResult, GeneratedFile } from '../types.js';
+import type { RouteGenerator } from './types.js';
+
+export class OpenAPIGenerator implements RouteGenerator {
+  readonly framework = 'openapi';
+
+  generate(routes: RouteDescriptor[], options: GeneratorOptions): GenerateResult {
+    const files: GeneratedFile[] = [];
+    const warnings: string[] = [];
+
+    if (routes.length === 0) {
+      warnings.push('No routes to generate');
+      return { files, preserved: [], warnings };
+    }
+
+    const spec = this.buildSpec(routes);
+    const yaml = this.toYaml(spec);
+
+    files.push({
+      path: 'openapi.yaml',
+      content: yaml,
+      isNew: true,
+    });
+
+    return { files, preserved: [], warnings };
+  }
+
+  private buildSpec(routes: RouteDescriptor[]): OpenAPISpec {
+    const paths: Record<string, Record<string, OpenAPIOperation>> = {};
+
+    for (const route of routes) {
+      // Convert :param to {param} for OpenAPI
+      const oaPath = route.path.replace(/:(\w+)/g, '{$1}');
+      const method = route.method.toLowerCase();
+
+      if (!paths[oaPath]) {
+        paths[oaPath] = {};
+      }
+
+      paths[oaPath][method] = this.buildOperation(route);
+    }
+
+    return {
+      openapi: '3.1.0',
+      info: {
+        title: 'ServerBridge Generated API',
+        version: '0.1.0',
+        description: 'Auto-extracted from hyperscript/htmx attributes',
+      },
+      paths,
+    };
+  }
+
+  private buildOperation(route: RouteDescriptor): OpenAPIOperation {
+    const op: OpenAPIOperation = {
+      operationId: route.handlerName,
+      summary: `Source: ${route.source.file}${route.source.line ? ':' + route.source.line : ''} (${route.source.kind})`,
+      responses: {
+        '200': this.buildResponse(route),
+      },
+    };
+
+    // Path parameters
+    if (route.pathParams.length > 0) {
+      op.parameters = route.pathParams.map(name => ({
+        name,
+        in: 'path' as const,
+        required: true,
+        schema: { type: inferParamType(name) },
+      }));
+    }
+
+    // Query parameters
+    if (route.queryParams && route.queryParams.length > 0) {
+      const queryParamSpecs = route.queryParams.map(param => ({
+        name: param.name,
+        in: 'query' as const,
+        required: param.required,
+        schema: { type: 'string' as const },
+      }));
+      if (op.parameters) {
+        op.parameters.push(...queryParamSpecs);
+      } else {
+        op.parameters = queryParamSpecs;
+      }
+    }
+
+    // Request body
+    if (
+      route.requestBody &&
+      route.requestBody.length > 0 &&
+      ['POST', 'PUT', 'PATCH'].includes(route.method)
+    ) {
+      const required = route.requestBody.filter(f => f.required).map(f => f.name);
+      const properties: Record<string, { type: string; format?: string }> = {};
+
+      for (const field of route.requestBody) {
+        properties[field.name] = fieldToSchema(field.type);
+      }
+
+      op.requestBody = {
+        required: required.length > 0,
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              ...(required.length > 0 ? { required } : {}),
+              properties,
+            },
+          },
+        },
+      };
+    }
+
+    return op;
+  }
+
+  private buildResponse(route: RouteDescriptor): OpenAPIResponse {
+    const contentType =
+      route.responseFormat === 'json'
+        ? 'application/json'
+        : route.responseFormat === 'html'
+          ? 'text/html'
+          : 'text/plain';
+
+    return {
+      description: 'Success',
+      content: {
+        [contentType]: {
+          schema: route.responseFormat === 'json' ? { type: 'object' } : { type: 'string' },
+        },
+      },
+    };
+  }
+
+  /**
+   * Minimal YAML serializer — avoids adding a yaml dependency.
+   * Handles the specific nested structure of OpenAPI specs.
+   */
+  toYaml(obj: unknown, indent: number = 0): string {
+    const pad = '  '.repeat(indent);
+
+    if (obj === null || obj === undefined) {
+      return 'null';
+    }
+
+    if (typeof obj === 'string') {
+      // Quote strings that could be ambiguous
+      if (
+        obj === '' ||
+        obj.includes(':') ||
+        obj.includes('#') ||
+        obj.includes("'") ||
+        /^\d/.test(obj) ||
+        obj === 'true' ||
+        obj === 'false'
+      ) {
+        return `'${obj.replace(/'/g, "''")}'`;
+      }
+      return obj;
+    }
+
+    if (typeof obj === 'number' || typeof obj === 'boolean') {
+      return String(obj);
+    }
+
+    if (Array.isArray(obj)) {
+      if (obj.length === 0) return '[]';
+
+      // For simple string/number arrays, use inline format
+      if (obj.every(item => typeof item === 'string' || typeof item === 'number')) {
+        return `[${obj.map(item => (typeof item === 'string' ? `'${item}'` : String(item))).join(', ')}]`;
+      }
+
+      return obj
+        .map(item => {
+          if (typeof item === 'object' && item !== null) {
+            const inner = this.toYaml(item, indent + 1).trimStart();
+            return `${pad}- ${inner}`;
+          }
+          return `${pad}- ${this.toYaml(item)}`;
+        })
+        .join('\n');
+    }
+
+    if (typeof obj === 'object') {
+      const entries = Object.entries(obj as Record<string, unknown>);
+      if (entries.length === 0) return '{}';
+
+      return entries
+        .map(([key, value]) => {
+          if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            const inner = this.toYaml(value, indent + 1);
+            return `${pad}${key}:\n${inner}`;
+          }
+          if (Array.isArray(value) && value.length > 0 && value.some(v => typeof v === 'object')) {
+            const inner = this.toYaml(value, indent + 1);
+            return `${pad}${key}:\n${inner}`;
+          }
+          return `${pad}${key}: ${this.toYaml(value, indent + 1)}`;
+        })
+        .join('\n');
+    }
+
+    return String(obj);
+  }
+}
+
+// --- Helper types (not exported) ---
+
+interface OpenAPISpec {
+  openapi: string;
+  info: { title: string; version: string; description: string };
+  paths: Record<string, Record<string, OpenAPIOperation>>;
+}
+
+interface OpenAPIOperation {
+  operationId: string;
+  summary: string;
+  parameters?: OpenAPIParameter[];
+  requestBody?: OpenAPIRequestBody;
+  responses: Record<string, OpenAPIResponse>;
+}
+
+interface OpenAPIParameter {
+  name: string;
+  in: 'path' | 'query';
+  required: boolean;
+  schema: { type: string };
+}
+
+interface OpenAPIRequestBody {
+  required: boolean;
+  content: Record<string, { schema: Record<string, unknown> }>;
+}
+
+interface OpenAPIResponse {
+  description: string;
+  content: Record<string, { schema: { type: string } }>;
+}
+
+function inferParamType(name: string): string {
+  if (name === 'id' || name.endsWith('Id')) return 'string';
+  if (name === 'page' || name === 'limit' || name === 'offset') return 'integer';
+  return 'string';
+}
+
+function fieldToSchema(type: string): { type: string; format?: string } {
+  switch (type) {
+    case 'number':
+      return { type: 'number' };
+    case 'boolean':
+      return { type: 'boolean' };
+    case 'file':
+      return { type: 'string', format: 'binary' };
+    default:
+      return { type: 'string' };
+  }
+}

package/src/generators/template-helpers.ts

@@ -0,0 +1,77 @@
+import type { RouteDescriptor } from '../types.js';
+
+/** Marker comment indicating a serverbridge-generated route */
+export const ROUTE_MARKER = '// @serverbridge-route:';
+/** Marker for start of user-editable code */
+export const USER_START = '// @serverbridge-user-start';
+/** Marker for end of user-editable code */
+export const USER_END = '// @serverbridge-user-end';
+
+/**
+ * Generate a route comment header.
+ */
+export function routeMarker(route: RouteDescriptor): string {
+  return `${ROUTE_MARKER} ${route.method} ${route.path}`;
+}
+
+/**
+ * Generate a TODO comment block for an unimplemented route.
+ */
+export function todoBlock(route: RouteDescriptor, indent: string = '  '): string {
+  const lines: string[] = [];
+  lines.push(`${indent}// TODO: Implement ${route.method} ${route.path}`);
+
+  if (route.pathParams.length > 0) {
+    lines.push(`${indent}// Path params: ${route.pathParams.join(', ')}`);
+  }
+
+  if (route.queryParams && route.queryParams.length > 0) {
+    lines.push(`${indent}// Query params: ${route.queryParams.map(p => p.name).join(', ')}`);
+  }
+
+  if (route.requestBody && route.requestBody.length > 0) {
+    const fields = route.requestBody
+      .map(f => `${f.name}: ${f.type}${f.required ? '' : '?'}`)
+      .join(', ');
+    lines.push(`${indent}// Expected body: { ${fields} }`);
+  }
+
+  if (route.notes.length > 0) {
+    for (const note of route.notes) {
+      lines.push(`${indent}// Note: ${note}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Group routes by common path prefix for organizing into files.
+ * E.g., /api/users and /api/users/:id group under "api-users".
+ */
+export function groupRoutesByPrefix(routes: RouteDescriptor[]): Map<string, RouteDescriptor[]> {
+  const groups = new Map<string, RouteDescriptor[]>();
+
+  for (const route of routes) {
+    // Take first two segments as the group key
+    const segments = route.path.replace(/^\//, '').split('/');
+    const groupKey =
+      segments
+        .slice(0, Math.min(2, segments.length))
+        .filter(s => !s.startsWith(':'))
+        .join('-') || 'root';
+
+    const group = groups.get(groupKey) ?? [];
+    group.push(route);
+    groups.set(groupKey, group);
+  }
+
+  return groups;
+}
+
+/**
+ * Generate a safe filename from a group key.
+ */
+export function groupToFilename(groupKey: string, typescript: boolean): string {
+  return `${groupKey}.${typescript ? 'ts' : 'js'}`;
+}

package/src/generators/types.ts

@@ -0,0 +1,12 @@
+import type { RouteDescriptor, GeneratorOptions, GenerateResult } from '../types.js';
+
+/**
+ * A route generator renders RouteDescriptor[] into framework-specific route files.
+ * Follows the same pattern as TestRenderer in compilation-service.
+ */
+export interface RouteGenerator {
+  /** Target framework name */
+  readonly framework: string;
+  /** Generate route files */
+  generate(routes: RouteDescriptor[], options: GeneratorOptions): GenerateResult;
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+// Public API
+export type {
+  HttpMethod,
+  RouteDescriptor,
+  RouteSource,
+  RequestBodyField,
+  QueryParam,
+  ScanResult,
+  ScanError,
+  ConflictWarning,
+  ConflictDetail,
+  GeneratorOptions,
+  GeneratedFile,
+  GenerateResult,
+  ServerBridgeConfig,
+} from './types.js';
+
+export {
+  extractPathParams,
+  extractQueryParams,
+  normalizeUrl,
+  urlToHandlerName,
+} from './conventions/url-patterns.js';
+export { inferConventions } from './conventions/convention-engine.js';
+export type { ConventionContext, ConventionResult } from './conventions/convention-engine.js';
+export { extractHyperscriptRoutes } from './scanner/hyperscript-extractor.js';
+export { extractHtmxRoutes } from './scanner/htmx-extractor.js';
+export { extractFormFields, extractFormBodies } from './scanner/form-scanner.js';
+export { scanRoutes, scanDirectory } from './scanner/route-scanner.js';
+export { ExpressGenerator } from './generators/express-generator.js';
+export { HonoGenerator } from './generators/hono-generator.js';
+export { OpenAPIGenerator } from './generators/openapi-generator.js';
+export { DjangoGenerator } from './generators/django-generator.js';
+export { FastAPIGenerator } from './generators/fastapi-generator.js';
+export type { RouteGenerator } from './generators/types.js';
+export { selectGenerator } from './generators/index.js';
+export { createManifest, loadManifest, saveManifest, diffRoutes } from './generators/manifest.js';
+export { detectConflicts, formatConflicts } from './scanner/conflict-detector.js';
+
+// Convenience generate function for programmatic use (e.g., Vite plugin)
+export { generate } from './generate.js';
+export type { ProgrammaticGenerateOptions, GenerateFullResult } from './generate.js';

package/src/scanner/conflict-detector.ts

@@ -0,0 +1,92 @@
+import type { RouteDescriptor, ConflictWarning, ConflictDetail } from '../types.js';
+
+/**
+ * Detect conflicts between multiple declarations of the same route.
+ * Must be called on the pre-deduplicated route list (before first-wins dedup).
+ */
+export function detectConflicts(routes: RouteDescriptor[]): ConflictWarning[] {
+  const warnings: ConflictWarning[] = [];
+
+  // Group routes by method:path
+  const groups = new Map<string, RouteDescriptor[]>();
+  for (const route of routes) {
+    const key = `${route.method}:${route.path}`;
+    const existing = groups.get(key) ?? [];
+    existing.push(route);
+    groups.set(key, existing);
+  }
+
+  for (const [key, groupRoutes] of groups) {
+    if (groupRoutes.length < 2) continue;
+
+    const conflicts: ConflictDetail[] = [];
+
+    // Check responseFormat
+    const formats = [...new Set(groupRoutes.map(r => r.responseFormat))];
+    if (formats.length > 1) {
+      conflicts.push({
+        field: 'responseFormat',
+        values: formats,
+        message: `Conflicting response formats: ${formats.join(' vs ')}`,
+      });
+    }
+
+    // Check requestBody field names (for POST/PUT/PATCH)
+    if (['POST', 'PUT', 'PATCH'].includes(groupRoutes[0].method)) {
+      const bodySignatures = groupRoutes.map(r =>
+        JSON.stringify((r.requestBody ?? []).map(f => f.name).sort())
+      );
+      const uniqueSignatures = [...new Set(bodySignatures)];
+      if (uniqueSignatures.length > 1) {
+        conflicts.push({
+          field: 'requestBody',
+          values: uniqueSignatures,
+          message: 'Request body fields differ across declarations',
+        });
+      }
+    }
+
+    // Check queryParams
+    const querySignatures = groupRoutes.map(r =>
+      JSON.stringify((r.queryParams ?? []).map(p => p.name).sort())
+    );
+    const uniqueQuerySigs = [...new Set(querySignatures)];
+    if (uniqueQuerySigs.length > 1) {
+      conflicts.push({
+        field: 'queryParams',
+        values: uniqueQuerySigs,
+        message: 'Query parameters differ across declarations',
+      });
+    }
+
+    if (conflicts.length > 0) {
+      warnings.push({
+        routeKey: key,
+        conflicts,
+        sources: groupRoutes.map(r => r.source),
+      });
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Format conflict warnings for human-readable CLI output.
+ */
+export function formatConflicts(warnings: ConflictWarning[]): string {
+  const lines: string[] = [];
+
+  for (const warning of warnings) {
+    lines.push(`  ${warning.routeKey}:`);
+    for (const conflict of warning.conflicts) {
+      lines.push(`    - ${conflict.message}`);
+    }
+    lines.push(`    Sources:`);
+    for (const source of warning.sources) {
+      lines.push(`      ${source.file}:${source.line ?? '?'} (${source.kind})`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/scanner/form-scanner.ts

@@ -0,0 +1,126 @@
+import type { RequestBodyField } from '../types.js';
+
+/**
+ * Regex to match <form> blocks and capture inner content.
+ * Uses non-greedy matching to handle multiple forms.
+ */
+const FORM_BLOCK = /<form\b[^>]*>([\s\S]*?)<\/form>/gi;
+
+/**
+ * Regex to match input-like elements with a name attribute.
+ * Captures: tag name, full attributes string.
+ */
+const NAMED_FIELD = /<(input|select|textarea)\b([^>]*)\bname\s*=\s*["']([^"']+)["']([^>]*)>/gi;
+
+/** Regex for type attribute */
+const TYPE_ATTR = /\btype\s*=\s*["']([^"']+)["']/i;
+
+/** Regex for required attribute */
+const REQUIRED_ATTR = /\brequired\b/i;
+
+/** Map HTML input types to our field types */
+const TYPE_MAP: Record<string, RequestBodyField['type']> = {
+  text: 'string',
+  email: 'string',
+  password: 'string',
+  tel: 'string',
+  url: 'string',
+  search: 'string',
+  hidden: 'string',
+  color: 'string',
+  date: 'string',
+  'datetime-local': 'string',
+  month: 'string',
+  week: 'string',
+  time: 'string',
+  number: 'number',
+  range: 'number',
+  checkbox: 'boolean',
+  file: 'file',
+};
+
+/**
+ * Extract form fields from a <form> block's inner HTML.
+ */
+export function extractFormFields(formInnerHtml: string): RequestBodyField[] {
+  const fields: RequestBodyField[] = [];
+  const seen = new Set<string>();
+
+  NAMED_FIELD.lastIndex = 0;
+  let match;
+  while ((match = NAMED_FIELD.exec(formInnerHtml)) !== null) {
+    const tag = match[1].toLowerCase();
+    const attrsBefore = match[2];
+    const name = match[3];
+    const attrsAfter = match[4];
+    const allAttrs = attrsBefore + ' ' + attrsAfter;
+
+    if (seen.has(name)) continue;
+    seen.add(name);
+
+    let type: RequestBodyField['type'] = 'string';
+    if (tag === 'select' || tag === 'textarea') {
+      type = 'string';
+    } else {
+      const typeMatch = allAttrs.match(TYPE_ATTR);
+      const inputType = typeMatch ? typeMatch[1].toLowerCase() : 'text';
+      type = TYPE_MAP[inputType] ?? 'unknown';
+    }
+
+    const required = REQUIRED_ATTR.test(allAttrs);
+
+    fields.push({ name, type, required });
+  }
+
+  return fields;
+}
+
+/**
+ * Find all <form> blocks in HTML content that contain route-implying attributes
+ * (hx-post, hx-put, hx-patch, fx-action) and extract their fields.
+ *
+ * Returns a map from URL path to field list.
+ */
+export function extractFormBodies(content: string): Map<string, RequestBodyField[]> {
+  const result = new Map<string, RequestBodyField[]>();
+
+  FORM_BLOCK.lastIndex = 0;
+  let match;
+  while ((match = FORM_BLOCK.exec(content)) !== null) {
+    const formTag = content.slice(
+      match.index,
+      match.index + content.slice(match.index).indexOf('>') + 1
+    );
+    const formBody = match[1];
+
+    // Check for route-implying attributes in the form tag
+    const url = extractFormUrl(formTag);
+    if (!url) continue;
+
+    const fields = extractFormFields(formBody);
+    if (fields.length > 0) {
+      result.set(url, fields);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Extract URL from a form tag's route-implying attributes.
+ */
+function extractFormUrl(formTag: string): string | undefined {
+  // hx-post, hx-put, hx-patch
+  const hxMatch = formTag.match(/\bhx-(?:post|put|patch)\s*=\s*["']([^"']+)["']/i);
+  if (hxMatch) return hxMatch[1];
+
+  // fx-action
+  const fxMatch = formTag.match(/\bfx-action\s*=\s*["']([^"']+)["']/i);
+  if (fxMatch) return fxMatch[1];
+
+  // hyperscript with send form to
+  const hsMatch = formTag.match(/\bsend\s+(?:the\s+)?form\s+to\s+['"]?([^\s'"]+)['"]?/i);
+  if (hsMatch) return hsMatch[1];
+
+  return undefined;
+}