@svadmin/core 0.0.3 → 0.3.0

package/src/inferencer-openapi.ts

@@ -0,0 +1,290 @@
+/**
+ * OpenAPI Schema → ResourceDefinition converter
+ *
+ * Parses an OpenAPI 3.x JSON schema and generates ResourceDefinition[]
+ * by analyzing the schema's paths and components.
+ */
+import type { FieldDefinition, ResourceDefinition } from './types';
+
+// ─── OpenAPI Types (subset) ──────────────────────────────────
+
+interface OpenAPISchema {
+  openapi?: string;
+  info?: { title?: string; version?: string };
+  paths?: Record<string, OpenAPIPathItem>;
+  components?: {
+    schemas?: Record<string, OpenAPISchemaObject>;
+  };
+}
+
+interface OpenAPIPathItem {
+  get?: OpenAPIOperation;
+  post?: OpenAPIOperation;
+  put?: OpenAPIOperation;
+  patch?: OpenAPIOperation;
+  delete?: OpenAPIOperation;
+}
+
+interface OpenAPIOperation {
+  operationId?: string;
+  tags?: string[];
+  parameters?: OpenAPIParameter[];
+  requestBody?: {
+    content?: Record<string, { schema?: OpenAPISchemaObject | OpenAPIRef }>;
+  };
+  responses?: Record<string, {
+    content?: Record<string, { schema?: OpenAPISchemaObject | OpenAPIRef }>;
+  }>;
+}
+
+interface OpenAPIParameter {
+  name: string;
+  in: string;
+  required?: boolean;
+  schema?: OpenAPISchemaObject;
+}
+
+interface OpenAPISchemaObject {
+  type?: string;
+  format?: string;
+  properties?: Record<string, OpenAPISchemaObject | OpenAPIRef>;
+  items?: OpenAPISchemaObject | OpenAPIRef;
+  required?: string[];
+  enum?: (string | number)[];
+  $ref?: string;
+  description?: string;
+  nullable?: boolean;
+}
+
+interface OpenAPIRef {
+  $ref: string;
+}
+
+function isRef(obj: unknown): obj is OpenAPIRef {
+  return obj !== null && typeof obj === 'object' && '$ref' in obj && typeof (obj as OpenAPIRef).$ref === 'string';
+}
+
+// ─── Schema Resolution ───────────────────────────────────────
+
+function resolveRef(ref: string, root: OpenAPISchema): OpenAPISchemaObject | null {
+  // $ref format: "#/components/schemas/Post"
+  const parts = ref.replace('#/', '').split('/');
+  let current: unknown = root;
+  for (const part of parts) {
+    if (current === null || typeof current !== 'object') return null;
+    current = (current as Record<string, unknown>)[part];
+    if (!current) return null;
+  }
+  return current as OpenAPISchemaObject;
+}
+
+function resolveSchema(schemaOrRef: OpenAPISchemaObject | OpenAPIRef, root: OpenAPISchema): OpenAPISchemaObject | null {
+  if (isRef(schemaOrRef)) {
+    return resolveRef(schemaOrRef.$ref, root);
+  }
+  return schemaOrRef;
+}
+
+// ─── Type Mapping ────────────────────────────────────────────
+
+function mapOpenAPITypeToFieldType(
+  key: string,
+  schema: OpenAPISchemaObject,
+  root: OpenAPISchema
+): FieldDefinition['type'] {
+  const { type, format } = schema;
+
+  // Enum → select
+  if (schema.enum && schema.enum.length > 0) return 'select';
+
+  // Array types
+  if (type === 'array') {
+    if (schema.items) {
+      const itemSchema = resolveSchema(schema.items, root);
+      if (itemSchema?.type === 'string') {
+        const lk = key.toLowerCase();
+        if (lk.includes('image') || lk.includes('photo')) return 'images';
+        return 'tags';
+      }
+    }
+    return 'tags';
+  }
+
+  // Object → json
+  if (type === 'object') return 'json';
+
+  // Boolean
+  if (type === 'boolean') return 'boolean';
+
+  // Number/Integer
+  if (type === 'number' || type === 'integer') return 'number';
+
+  // String with format
+  if (type === 'string') {
+    if (format === 'date' || format === 'date-time') return 'date';
+    if (format === 'email') return 'email';
+    if (format === 'uri' || format === 'url') return 'url';
+    if (format === 'binary' || format === 'byte') return 'image';
+
+    // Heuristic from key name
+    const lk = key.toLowerCase();
+    if (lk.includes('email')) return 'email';
+    if (lk.includes('phone') || lk.includes('tel')) return 'phone';
+    if (lk.includes('url') || lk.includes('link') || lk.includes('website')) return 'url';
+    if (lk.includes('avatar') || lk.includes('image') || lk.includes('photo') || lk.includes('logo')) return 'image';
+    if (lk.includes('color') || lk.includes('colour')) return 'color';
+    if (lk.includes('description') || lk.includes('content') || lk.includes('body') || lk.includes('bio')) return 'textarea';
+    if (lk === 'created_at' || lk === 'updated_at' || lk.endsWith('_at') || lk.endsWith('_date')) return 'date';
+
+    return 'text';
+  }
+
+  return 'text';
+}
+
+// ─── Core: Parse OpenAPI Schema ──────────────────────────────
+
+export interface InferFromOpenAPIOptions {
+  /** Only infer resources matching these schema names */
+  include?: string[];
+  /** Exclude these schema names */
+  exclude?: string[];
+  /** Custom primary key (default: 'id') */
+  primaryKey?: string;
+}
+
+/**
+ * Parse an OpenAPI 3.x JSON schema and produce ResourceDefinition[].
+ */
+export function inferFromOpenAPI(
+  spec: OpenAPISchema,
+  options: InferFromOpenAPIOptions = {}
+): ResourceDefinition[] {
+  const { primaryKey = 'id', include, exclude } = options;
+  const schemas = spec.components?.schemas ?? {};
+  const resources: ResourceDefinition[] = [];
+
+  // Detect which schemas have CRUD paths
+  const resourcePaths = detectResourcePaths(spec);
+
+  for (const [schemaName, schemaObj] of Object.entries(schemas)) {
+    // Apply include/exclude filters
+    if (include && !include.includes(schemaName)) continue;
+    if (exclude && exclude.includes(schemaName)) continue;
+
+    const resolved = resolveSchema(schemaObj as OpenAPISchemaObject | OpenAPIRef, spec);
+    if (!resolved || resolved.type !== 'object' || !resolved.properties) continue;
+
+    const fields: FieldDefinition[] = [];
+    const requiredFields = new Set(resolved.required ?? []);
+
+    for (const [propName, propSchemaOrRef] of Object.entries(resolved.properties)) {
+      const propSchema = resolveSchema(propSchemaOrRef, spec);
+      if (!propSchema) continue;
+
+      const fieldType = mapOpenAPITypeToFieldType(propName, propSchema, spec);
+
+      // Detect relation from $ref or _id suffix
+      let relatedResource: string | null = null;
+      if (isRef(propSchemaOrRef)) {
+        const refName = propSchemaOrRef.$ref.split('/').pop() ?? '';
+        relatedResource = refName.toLowerCase() + 's';
+      } else if (propName.endsWith('_id') || propName.endsWith('Id')) {
+        const base = propName.replace(/_id$|Id$/, '');
+        relatedResource = base.endsWith('s') ? base : base + 's';
+      }
+
+      const field: FieldDefinition = {
+        key: propName,
+        label: humanize(propName),
+        type: relatedResource ? 'relation' : fieldType,
+        required: requiredFields.has(propName),
+        sortable: ['text', 'number', 'date'].includes(fieldType),
+        searchable: ['text', 'email'].includes(fieldType),
+        showInList: propName !== primaryKey && fieldType !== 'textarea' && fieldType !== 'json',
+        showInForm: propName !== primaryKey,
+      };
+
+      if (relatedResource) {
+        field.resource = relatedResource;
+        field.optionLabel = 'name';
+        field.optionValue = 'id';
+      }
+
+      if (propSchema.enum) {
+        field.options = propSchema.enum.map(v => ({
+          label: String(v).charAt(0).toUpperCase() + String(v).slice(1),
+          value: v as string | number,
+        }));
+      }
+
+      fields.push(field);
+    }
+
+    // Sort: primaryKey first
+    fields.sort((a, b) => {
+      if (a.key === primaryKey) return -1;
+      if (b.key === primaryKey) return 1;
+      return 0;
+    });
+
+    // Check path-based CRUD capabilities
+    const pathInfo = resourcePaths.get(schemaName.toLowerCase()) ??
+                     resourcePaths.get(schemaName.toLowerCase() + 's');
+
+    resources.push({
+      name: schemaName.toLowerCase() + 's',
+      label: schemaName,
+      primaryKey,
+      fields,
+      canCreate: pathInfo?.hasPost ?? true,
+      canEdit: pathInfo?.hasPut ?? true,
+      canDelete: pathInfo?.hasDelete ?? true,
+      canShow: pathInfo?.hasGet ?? true,
+    });
+  }
+
+  return resources;
+}
+
+// ─── Path Detection ──────────────────────────────────────────
+
+interface PathInfo {
+  hasGet: boolean;
+  hasPost: boolean;
+  hasPut: boolean;
+  hasDelete: boolean;
+}
+
+function detectResourcePaths(spec: OpenAPISchema): Map<string, PathInfo> {
+  const result = new Map<string, PathInfo>();
+  if (!spec.paths) return result;
+
+  for (const [path, methods] of Object.entries(spec.paths)) {
+    // Extract resource name from path like /api/posts or /posts/{id}
+    const segments = path.split('/').filter(Boolean);
+    const resourceSegment = segments.find(s => !s.startsWith('{') && s !== 'api' && s !== 'v1' && s !== 'v2');
+    if (!resourceSegment) continue;
+
+    const name = resourceSegment.toLowerCase();
+    const existing = result.get(name) ?? { hasGet: false, hasPost: false, hasPut: false, hasDelete: false };
+
+    if (methods.get) existing.hasGet = true;
+    if (methods.post) existing.hasPost = true;
+    if (methods.put || methods.patch) existing.hasPut = true;
+    if (methods.delete) existing.hasDelete = true;
+
+    result.set(name, existing);
+  }
+
+  return result;
+}
+
+// ─── Utilities ───────────────────────────────────────────────
+
+function humanize(key: string): string {
+  return key
+    .replace(/_/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/\b\w/g, c => c.toUpperCase());
+}

package/src/inferencer.test.ts

@@ -0,0 +1,189 @@
+// Unit tests for Inferencer
+import { describe, test, expect } from 'bun:test';
+import { inferFieldType, inferResource } from './inferencer';
+
+describe('inferFieldType', () => {
+  test('detects boolean', () => {
+    expect(inferFieldType('active', true)).toBe('boolean');
+  });
+
+  test('detects number', () => {
+    expect(inferFieldType('age', 25)).toBe('number');
+  });
+
+  test('detects email', () => {
+    expect(inferFieldType('email', 'user@example.com')).toBe('email');
+  });
+
+  test('detects email from key name', () => {
+    expect(inferFieldType('user_email', 'test')).toBe('email');
+  });
+
+  test('detects URL', () => {
+    expect(inferFieldType('website', 'https://example.com')).toBe('url');
+  });
+
+  test('detects image URL', () => {
+    expect(inferFieldType('avatar', 'https://example.com/photo.jpg')).toBe('image');
+  });
+
+  test('detects image from key name', () => {
+    expect(inferFieldType('avatar', '/uploads/user.png')).toBe('image');
+  });
+
+  test('detects date ISO string', () => {
+    expect(inferFieldType('created', '2024-01-15T10:30:00Z')).toBe('date');
+  });
+
+  test('detects date from key name', () => {
+    expect(inferFieldType('created_at', 'some value')).toBe('date');
+  });
+
+  test('detects phone', () => {
+    expect(inferFieldType('phone', '+1 (555) 123-4567')).toBe('phone');
+  });
+
+  test('detects color hex', () => {
+    expect(inferFieldType('color', '#ff5533')).toBe('color');
+  });
+
+  test('detects textarea for long strings', () => {
+    expect(inferFieldType('content', 'a'.repeat(250))).toBe('textarea');
+  });
+
+  test('detects textarea from key name', () => {
+    expect(inferFieldType('description', 'short')).toBe('textarea');
+  });
+
+  test('detects tags array', () => {
+    expect(inferFieldType('tags', ['svelte', 'admin'])).toBe('tags');
+  });
+
+  test('detects images array', () => {
+    expect(inferFieldType('photos', ['https://x.com/a.png', 'https://x.com/b.jpg'])).toBe('images');
+  });
+
+  test('detects json object', () => {
+    expect(inferFieldType('meta', { foo: 'bar' })).toBe('json');
+  });
+
+  test('null defaults to text', () => {
+    expect(inferFieldType('unknown', null)).toBe('text');
+  });
+
+  test('plain string defaults to text', () => {
+    expect(inferFieldType('title', 'Hello World')).toBe('text');
+  });
+});
+
+describe('inferResource', () => {
+  const sampleData = [
+    {
+      id: 1,
+      title: 'First Post',
+      content: 'A very long description that is more than two hundred characters. '.repeat(4),
+      author_id: 5,
+      status: 'published',
+      views: 100,
+      is_featured: true,
+      created_at: '2024-01-15T10:00:00Z',
+      email: 'author@blog.com',
+      tags: ['svelte', 'admin'],
+    },
+    {
+      id: 2,
+      title: 'Second Post',
+      content: 'Another long body text that exceeds the 200 char limit easily. '.repeat(5),
+      author_id: 3,
+      status: 'draft',
+      views: 42,
+      is_featured: false,
+      created_at: '2024-02-20T14:30:00Z',
+      email: 'editor@blog.com',
+      tags: ['react'],
+    },
+  ];
+
+  test('returns correct resource name and label', () => {
+    const result = inferResource('posts', sampleData);
+    expect(result.resource.name).toBe('posts');
+    expect(result.resource.label).toBe('Posts');
+  });
+
+  test('infers correct number of fields', () => {
+    const result = inferResource('posts', sampleData);
+    expect(result.fields.length).toBe(10); // id, title, content, author_id, status, views, is_featured, created_at, email, tags
+  });
+
+  test('detects id as primary key', () => {
+    const result = inferResource('posts', sampleData);
+    const idField = result.fields.find(f => f.key === 'id');
+    expect(idField).toBeDefined();
+    expect(idField!.showInForm).toBe(false);
+  });
+
+  test('detects number type for views', () => {
+    const result = inferResource('posts', sampleData);
+    const viewsField = result.fields.find(f => f.key === 'views');
+    expect(viewsField!.type).toBe('number');
+  });
+
+  test('detects boolean type for is_featured', () => {
+    const result = inferResource('posts', sampleData);
+    const field = result.fields.find(f => f.key === 'is_featured');
+    expect(field!.type).toBe('boolean');
+  });
+
+  test('detects date for created_at', () => {
+    const result = inferResource('posts', sampleData);
+    const field = result.fields.find(f => f.key === 'created_at');
+    expect(field!.type).toBe('date');
+  });
+
+  test('detects relation for author_id', () => {
+    const result = inferResource('posts', sampleData);
+    const field = result.fields.find(f => f.key === 'author_id');
+    expect(field!.type).toBe('relation');
+    expect(field!.resource).toBe('authors');
+  });
+
+  test('detects email type', () => {
+    const result = inferResource('posts', sampleData);
+    const field = result.fields.find(f => f.key === 'email');
+    expect(field!.type).toBe('email');
+  });
+
+  test('detects tags array', () => {
+    const result = inferResource('posts', sampleData);
+    const field = result.fields.find(f => f.key === 'tags');
+    expect(field!.type).toBe('tags');
+  });
+
+  test('detects textarea for content', () => {
+    const result = inferResource('posts', sampleData);
+    const field = result.fields.find(f => f.key === 'content');
+    expect(field!.type).toBe('textarea');
+    expect(field!.showInList).toBe(false);
+  });
+
+  test('generates valid TypeScript code', () => {
+    const result = inferResource('posts', sampleData);
+    expect(result.code).toContain("name: 'posts'");
+    expect(result.code).toContain("import type { ResourceDefinition }");
+    expect(result.code).toContain("export const postsResource");
+  });
+
+  test('handles empty data gracefully', () => {
+    const result = inferResource('empty', []);
+    expect(result.fields.length).toBe(0);
+    expect(result.code).toContain('No data available');
+  });
+
+  test('custom primaryKey', () => {
+    const data = [{ _id: 'abc', name: 'Test' }];
+    const result = inferResource('items', data, { primaryKey: '_id' });
+    expect(result.resource.primaryKey).toBe('_id');
+    const pkField = result.fields.find(f => f.key === '_id');
+    expect(pkField!.showInForm).toBe(false);
+  });
+});