@eventcatalog/core 3.25.5 → 3.26.0

package/eventcatalog/src/components/FieldsExplorer/FieldsTable.tsx

@@ -0,0 +1,236 @@
+import { useState } from 'react';
+import { SearchX, Copy, Check, AlertTriangle } from 'lucide-react';
+import { BoltIcon, ChatBubbleLeftIcon, MagnifyingGlassIcon } from '@heroicons/react/24/solid';
+import { buildUrl } from '@utils/url-builder';
+
+export interface FieldResult {
+  path: string;
+  type: string;
+  description: string;
+  required: boolean;
+  schemaFormat: string;
+  messageId: string;
+  messageVersion: string;
+  messageType: string;
+  messageName?: string;
+  messageSummary?: string;
+  messageOwners?: string[];
+  producers: { id: string; version: string; name?: string; summary?: string; owners?: string[] }[];
+  consumers: { id: string; version: string; name?: string; summary?: string; owners?: string[] }[];
+  usedInCount?: number;
+  conflicts?: { type: string; count: number }[];
+}
+
+export interface FieldsTableProps {
+  fields: FieldResult[];
+  onSelectField: (fieldPath: string) => void;
+  isLoading: boolean;
+  isScaleEnabled?: boolean;
+}
+
+const colorClasses: Record<string, string> = {
+  orange: 'text-orange-500',
+  blue: 'text-blue-500',
+  green: 'text-green-500',
+  gray: 'text-gray-500',
+};
+
+const getColorAndIconForMessageType = (type: string) => {
+  switch (type) {
+    case 'event':
+      return { color: 'orange', Icon: BoltIcon };
+    case 'command':
+      return { color: 'blue', Icon: ChatBubbleLeftIcon };
+    case 'query':
+      return { color: 'green', Icon: MagnifyingGlassIcon };
+    default:
+      return { color: 'gray', Icon: ChatBubbleLeftIcon };
+  }
+};
+
+function MessageBadge({ id, name, version, type }: { id: string; name?: string; version: string; type: string }) {
+  const { color, Icon } = getColorAndIconForMessageType(type);
+  const collection = type === 'query' ? 'queries' : `${type}s`;
+  const messageUrl = buildUrl(`/docs/${collection}/${id}/${version}`);
+  return (
+    <a
+      href={messageUrl}
+      onClick={(e) => e.stopPropagation()}
+      className="group/msg inline-flex items-center gap-1.5 text-xs hover:text-[rgb(var(--ec-accent))] transition-colors"
+    >
+      <Icon className={`h-3.5 w-3.5 ${colorClasses[color] || 'text-gray-500'} flex-shrink-0`} />
+      <span className="truncate max-w-[160px] text-[rgb(var(--ec-page-text))] group-hover/msg:text-[rgb(var(--ec-accent))]">
+        {name || id}
+      </span>
+      <span className="text-[rgb(var(--ec-icon-color))]">v{version}</span>
+    </a>
+  );
+}
+
+function FieldPathCell({ path }: { path: string }) {
+  const [copied, setCopied] = useState(false);
+
+  return (
+    <span className="inline-flex items-center gap-1 font-mono text-[rgb(var(--ec-page-text))]">
+      {path}
+      <button
+        className={`opacity-0 group-hover:opacity-100 transition-opacity p-0.5 rounded hover:bg-[rgb(var(--ec-content-hover))]`}
+        onClick={(e) => {
+          e.stopPropagation();
+          navigator.clipboard.writeText(path);
+          setCopied(true);
+          setTimeout(() => setCopied(false), 1500);
+        }}
+        title="Copy field path"
+      >
+        {copied ? <Check className="w-3 h-3 text-green-500" /> : <Copy className="w-3 h-3 text-[rgb(var(--ec-icon-color))]" />}
+      </button>
+    </span>
+  );
+}
+
+export default function FieldsTable({ fields, onSelectField, isLoading, isScaleEnabled = false }: FieldsTableProps) {
+  if (isLoading) {
+    return (
+      <div className="flex-1 flex items-center justify-center">
+        <div className="flex flex-col items-center gap-3">
+          <div className="w-8 h-8 border-2 border-[rgb(var(--ec-accent))] border-t-transparent rounded-full animate-spin" />
+          <span className="text-sm text-[rgb(var(--ec-page-text-muted))]">Loading fields...</span>
+        </div>
+      </div>
+    );
+  }
+
+  if (fields.length === 0) {
+    return (
+      <div className="flex-1 flex items-center justify-center">
+        <div className="flex flex-col items-center justify-center text-[rgb(var(--ec-page-text-muted))]">
+          <SearchX className="w-10 h-10 text-[rgb(var(--ec-icon-color))] mb-3 opacity-50" />
+          <p className="text-sm font-medium text-[rgb(var(--ec-page-text-muted))]">No schema fields found</p>
+          <p className="text-xs text-[rgb(var(--ec-icon-color))] mt-1 max-w-xs text-center">
+            Add <code className="px-1 py-0.5 rounded bg-[rgb(var(--ec-content-hover))] font-mono text-[11px]">schemaPath</code> to
+            your events, commands, or queries to get started.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex-1 overflow-auto px-6">
+      <table className="min-w-full divide-y divide-[rgb(var(--ec-page-border))]">
+        <thead className="sticky top-0 z-10 bg-[rgb(var(--ec-page-bg))]">
+          <tr>
+            <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+              Field Path
+            </th>
+            <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+              Type
+            </th>
+            <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+              Message
+            </th>
+            <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+              Format
+            </th>
+            <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+              Required
+            </th>
+            {isScaleEnabled && (
+              <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+                Consistency
+              </th>
+            )}
+            {isScaleEnabled && (
+              <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+                Used In
+              </th>
+            )}
+            <th className="px-4 py-2.5 text-left text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] uppercase tracking-wider">
+              Owners
+            </th>
+          </tr>
+        </thead>
+        <tbody className="divide-y divide-[rgb(var(--ec-page-border)/0.5)]">
+          {fields.map((field, index) => {
+            const rowKey = `${field.path}-${field.messageId}-${field.messageVersion}-${index}`;
+            const owners = field.messageOwners || [];
+
+            return (
+              <tr
+                key={rowKey}
+                className="group cursor-pointer transition-colors hover:bg-[rgb(var(--ec-content-hover))]"
+                onClick={() => onSelectField(field.path)}
+              >
+                <td className="px-4 py-3 text-sm">
+                  <FieldPathCell path={field.path} />
+                </td>
+                <td className="px-4 py-3 text-sm font-mono text-[rgb(var(--ec-page-text-muted))]">{field.type}</td>
+                <td className="px-4 py-3 text-sm">
+                  <MessageBadge
+                    id={field.messageId}
+                    name={field.messageName}
+                    version={field.messageVersion}
+                    type={field.messageType}
+                  />
+                </td>
+                <td className="px-4 py-3 text-sm text-[rgb(var(--ec-page-text-muted))]">{field.schemaFormat}</td>
+                <td className="px-4 py-3 text-sm">
+                  {field.required && (
+                    <span className="inline-flex items-center px-1.5 py-0.5 rounded text-[10px] font-semibold bg-red-500/10 text-red-500 border border-red-500/20">
+                      Required
+                    </span>
+                  )}
+                </td>
+                {isScaleEnabled && (
+                  <td className="px-4 py-3 text-sm">
+                    {field.conflicts && field.conflicts.length > 1 ? (
+                      <div
+                        className="flex items-center gap-1.5"
+                        title={field.conflicts.map((c) => `${c.type} (${c.count})`).join(', ')}
+                      >
+                        <AlertTriangle className="w-3.5 h-3.5 text-amber-500 flex-shrink-0" />
+                        <span className="inline-flex items-center px-1.5 py-0.5 rounded text-[10px] font-semibold bg-amber-500/10 text-amber-600 border border-amber-500/20">
+                          {field.conflicts.length} types
+                        </span>
+                      </div>
+                    ) : (
+                      <span className="text-[10px] text-green-500 font-medium">Consistent</span>
+                    )}
+                  </td>
+                )}
+                {isScaleEnabled && (
+                  <td className="px-4 py-3 text-sm">
+                    <span className="inline-flex items-center px-2 py-0.5 rounded-full text-[11px] font-medium bg-[rgb(var(--ec-accent)/0.1)] text-[rgb(var(--ec-accent))]">
+                      {field.usedInCount || 1} {(field.usedInCount || 1) === 1 ? 'schema' : 'schemas'}
+                    </span>
+                  </td>
+                )}
+                <td className="px-4 py-3 text-sm">
+                  {owners.length > 0 ? (
+                    <div className="flex items-center gap-1 flex-wrap">
+                      {owners.slice(0, 2).map((owner) => (
+                        <span
+                          key={owner}
+                          className="inline-flex items-center px-1.5 py-0.5 rounded text-[10px] font-medium bg-[rgb(var(--ec-accent)/0.1)] text-[rgb(var(--ec-accent))] truncate max-w-[100px]"
+                          title={owner}
+                        >
+                          {owner}
+                        </span>
+                      ))}
+                      {owners.length > 2 && (
+                        <span className="text-[10px] text-[rgb(var(--ec-page-text-muted))]">+{owners.length - 2}</span>
+                      )}
+                    </div>
+                  ) : (
+                    <span className="text-[rgb(var(--ec-page-text-muted))] text-xs">-</span>
+                  )}
+                </td>
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/eventcatalog/src/enterprise/fields/field-extractor.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect } from 'vitest';
+import { extractSchemaFieldsDeep } from './field-extractor';
+
+describe('extractSchemaFieldsDeep', () => {
+  describe('JSON Schema', () => {
+    it('extracts top-level properties with their types', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          orderId: { type: 'string', description: 'The order ID' },
+          amount: { type: 'number' },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields).toEqual([
+        { path: 'orderId', type: 'string', description: 'The order ID', required: false },
+        { path: 'amount', type: 'number', description: '', required: false },
+      ]);
+    });
+
+    it('marks fields as required when listed in the JSON Schema required array', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        required: ['orderId'],
+        properties: {
+          orderId: { type: 'string' },
+          notes: { type: 'string' },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields[0].required).toBe(true);
+      expect(fields[1].required).toBe(false);
+    });
+
+    it('extracts nested object fields with dot-notation paths', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          address: {
+            type: 'object',
+            properties: {
+              street: { type: 'string' },
+              city: { type: 'string' },
+            },
+          },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields.map((f) => f.path)).toEqual(['address', 'address.street', 'address.city']);
+    });
+
+    it('uses bracket notation for array item fields', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          items: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                productId: { type: 'string' },
+                quantity: { type: 'integer' },
+              },
+            },
+          },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields.map((f) => f.path)).toEqual(['items', 'items[].productId', 'items[].quantity']);
+    });
+
+    it('resolves local $ref references within the same schema', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          billing: { $ref: '#/definitions/Address' },
+        },
+        definitions: {
+          Address: {
+            type: 'object',
+            properties: {
+              street: { type: 'string' },
+              zip: { type: 'string' },
+            },
+          },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields.map((f) => f.path)).toEqual(['billing', 'billing.street', 'billing.zip']);
+    });
+
+    it('skips external $ref references and returns only local fields', () => {
+      const schema = JSON.stringify({
+        type: 'object',
+        properties: {
+          orderId: { type: 'string' },
+          customer: { $ref: './common.json#/definitions/Customer' },
+        },
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields).toHaveLength(2);
+      expect(fields[0].path).toBe('orderId');
+      expect(fields[1].path).toBe('customer');
+      expect(fields[1].type).toBe('$ref');
+    });
+
+    it('merges allOf schemas and extracts combined properties', () => {
+      const schema = JSON.stringify({
+        allOf: [
+          { type: 'object', properties: { id: { type: 'string' } } },
+          { type: 'object', properties: { name: { type: 'string' } } },
+        ],
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'json-schema');
+      expect(fields.map((f) => f.path)).toEqual(['id', 'name']);
+    });
+
+    it('returns empty array when schema content is malformed JSON', () => {
+      const fields = extractSchemaFieldsDeep('not valid json{{{', 'json-schema');
+      expect(fields).toEqual([]);
+    });
+
+    it('returns empty array when schema content is empty', () => {
+      const fields = extractSchemaFieldsDeep('', 'json-schema');
+      expect(fields).toEqual([]);
+    });
+  });
+
+  describe('Avro', () => {
+    it('extracts fields from a simple Avro record', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Order',
+        fields: [
+          { name: 'orderId', type: 'string', doc: 'The order identifier' },
+          { name: 'amount', type: 'double' },
+        ],
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'avro');
+      expect(fields).toEqual([
+        { path: 'orderId', type: 'string', description: 'The order identifier', required: true },
+        { path: 'amount', type: 'double', description: '', required: true },
+      ]);
+    });
+
+    it('handles Avro union types containing null as optional fields', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Customer',
+        fields: [
+          { name: 'id', type: 'string' },
+          { name: 'nickname', type: ['null', 'string'] },
+        ],
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'avro');
+      expect(fields[0].required).toBe(true);
+      expect(fields[1].required).toBe(false);
+      expect(fields[1].type).toBe('null | string');
+    });
+
+    it('extracts nested record fields with dot-notation paths', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Order',
+        fields: [
+          {
+            name: 'customer',
+            type: {
+              type: 'record',
+              name: 'Customer',
+              fields: [
+                { name: 'name', type: 'string' },
+                { name: 'email', type: 'string' },
+              ],
+            },
+          },
+        ],
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'avro');
+      expect(fields.map((f) => f.path)).toEqual(['customer', 'customer.name', 'customer.email']);
+    });
+
+    it('uses bracket notation for Avro array items', () => {
+      const schema = JSON.stringify({
+        type: 'record',
+        name: 'Order',
+        fields: [
+          {
+            name: 'items',
+            type: {
+              type: 'array',
+              items: {
+                type: 'record',
+                name: 'Item',
+                fields: [
+                  { name: 'productId', type: 'string' },
+                  { name: 'qty', type: 'int' },
+                ],
+              },
+            },
+          },
+        ],
+      });
+      const fields = extractSchemaFieldsDeep(schema, 'avro');
+      expect(fields.map((f) => f.path)).toEqual(['items', 'items[].productId', 'items[].qty']);
+    });
+  });
+
+  describe('Protobuf', () => {
+    it('extracts fields from a simple proto3 message', () => {
+      const proto = `
+        syntax = "proto3";
+        message Order {
+          string order_id = 1;
+          double amount = 2; // total amount
+        }
+      `;
+      const fields = extractSchemaFieldsDeep(proto, 'proto');
+      expect(fields).toEqual([
+        { path: 'order_id', type: 'string', description: '', required: false },
+        { path: 'amount', type: 'double', description: 'total amount', required: false },
+      ]);
+    });
+
+    it('marks repeated fields with their modifier in the type', () => {
+      const proto = `
+        syntax = "proto3";
+        message Order {
+          repeated string tags = 1;
+        }
+      `;
+      const fields = extractSchemaFieldsDeep(proto, 'proto');
+      expect(fields[0].type).toBe('repeated string');
+    });
+
+    it('returns empty array for empty proto content', () => {
+      const fields = extractSchemaFieldsDeep('', 'proto');
+      expect(fields).toEqual([]);
+    });
+  });
+});

package/eventcatalog/src/enterprise/fields/field-extractor.ts

@@ -0,0 +1,183 @@
+export interface DeepSchemaField {
+  path: string;
+  type: string;
+  description: string;
+  required: boolean;
+}
+
+export function extractSchemaFieldsDeep(content: string, format: string): DeepSchemaField[] {
+  if (!content) return [];
+
+  if (format === 'json-schema') {
+    return extractJsonSchemaFields(content);
+  }
+
+  if (format === 'avro') {
+    return extractAvroFields(content);
+  }
+
+  if (format === 'proto') {
+    return extractProtoFields(content);
+  }
+
+  return [];
+}
+
+function extractProtoFields(content: string): DeepSchemaField[] {
+  if (!content) return [];
+  const fields: DeepSchemaField[] = [];
+  const fieldRegex = /^\s*(repeated\s+|optional\s+|required\s+)?(\w+)\s+(\w+)\s*=\s*\d+\s*;(?:\s*\/\/\s*(.*))?/gm;
+  let match;
+  while ((match = fieldRegex.exec(content)) !== null) {
+    const modifier = (match[1] || '').trim();
+    const type = modifier ? `${modifier} ${match[2]}` : match[2];
+    fields.push({
+      path: match[3],
+      type,
+      description: match[4]?.trim() || '',
+      required: modifier === 'required',
+    });
+  }
+  return fields;
+}
+
+function extractAvroFields(content: string): DeepSchemaField[] {
+  try {
+    const schema = JSON.parse(content);
+    const fields: DeepSchemaField[] = [];
+    walkAvroRecord(schema, '', fields);
+    return fields;
+  } catch {
+    return [];
+  }
+}
+
+function getAvroTypeName(type: any): string {
+  if (typeof type === 'string') return type;
+  if (Array.isArray(type)) {
+    return type.map((t) => (typeof t === 'string' ? t : t.type || 'complex')).join(' | ');
+  }
+  if (typeof type === 'object' && type !== null) {
+    if (type.type === 'array' && type.items) return `array<${getAvroTypeName(type.items)}>`;
+    if (type.type === 'record') return type.name || 'record';
+    return type.type || 'complex';
+  }
+  return 'unknown';
+}
+
+function walkAvroRecord(schema: any, prefix: string, fields: DeepSchemaField[]): void {
+  if (!schema.fields || !Array.isArray(schema.fields)) return;
+
+  for (const field of schema.fields) {
+    const path = prefix ? `${prefix}.${field.name}` : field.name;
+    const isOptional = Array.isArray(field.type) && field.type.includes('null');
+    const typeName = getAvroTypeName(field.type);
+
+    fields.push({
+      path,
+      type: typeName,
+      description: field.doc || '',
+      required: !isOptional,
+    });
+
+    // Recurse into nested records
+    const innerType = Array.isArray(field.type)
+      ? field.type.find((t: any) => typeof t === 'object' && t.type === 'record')
+      : typeof field.type === 'object' && field.type.type === 'record'
+        ? field.type
+        : null;
+
+    if (innerType) {
+      walkAvroRecord(innerType, path, fields);
+    }
+
+    // Recurse into array items that are records
+    const arrayType = Array.isArray(field.type)
+      ? field.type.find((t: any) => typeof t === 'object' && t.type === 'array')
+      : typeof field.type === 'object' && field.type.type === 'array'
+        ? field.type
+        : null;
+
+    if (arrayType && typeof arrayType.items === 'object' && arrayType.items.type === 'record') {
+      walkAvroRecord(arrayType.items, `${path}[]`, fields);
+    }
+  }
+}
+
+function extractJsonSchemaFields(content: string): DeepSchemaField[] {
+  try {
+    const schema = JSON.parse(content);
+    const fields: DeepSchemaField[] = [];
+    walkJsonSchema(schema, '', schema.required || [], schema, fields);
+    return fields;
+  } catch {
+    return [];
+  }
+}
+
+function walkJsonSchema(node: any, prefix: string, requiredList: string[], rootSchema: any, fields: DeepSchemaField[]): void {
+  // Handle allOf by merging (resolve $ref entries first)
+  if (node.allOf && Array.isArray(node.allOf)) {
+    const merged: any = { type: 'object', properties: {}, required: [] };
+    for (let sub of node.allOf) {
+      if (sub.$ref) {
+        const resolved = resolveLocalRef(sub.$ref, rootSchema);
+        if (resolved) sub = resolved;
+        else continue;
+      }
+      Object.assign(merged.properties, sub.properties || {});
+      merged.required.push(...(sub.required || []));
+    }
+    walkJsonSchema(merged, prefix, merged.required, rootSchema, fields);
+    return;
+  }
+
+  if (!node.properties) return;
+
+  for (const [name, prop] of Object.entries(node.properties) as [string, any][]) {
+    const path = prefix ? `${prefix}.${name}` : name;
+    const isRequired = requiredList.includes(name);
+
+    // Resolve $ref
+    if (prop.$ref) {
+      const resolved = resolveLocalRef(prop.$ref, rootSchema);
+      if (resolved) {
+        const type = resolved.type || 'object';
+        fields.push({ path, type, description: resolved.description || '', required: isRequired });
+        if (resolved.properties) {
+          walkJsonSchema(resolved, path, resolved.required || [], rootSchema, fields);
+        }
+      } else {
+        // External ref — add as-is
+        fields.push({ path, type: '$ref', description: '', required: isRequired });
+      }
+      continue;
+    }
+
+    const type = prop.type || (prop.enum ? 'enum' : prop.$ref ? '$ref' : 'object');
+    fields.push({ path, type, description: prop.description || '', required: isRequired });
+
+    // Recurse into nested objects
+    if (prop.type === 'object' && prop.properties) {
+      walkJsonSchema(prop, path, prop.required || [], rootSchema, fields);
+    }
+
+    // Recurse into array items
+    if (prop.type === 'array' && prop.items) {
+      if (prop.items.type === 'object' && prop.items.properties) {
+        walkJsonSchema(prop.items, `${path}[]`, prop.items.required || [], rootSchema, fields);
+      }
+    }
+  }
+}
+
+function resolveLocalRef(ref: string, rootSchema: any): any {
+  if (!ref.startsWith('#/')) return null;
+  const parts = ref.replace('#/', '').split('/');
+  let current = rootSchema;
+  for (const part of parts) {
+    current = current?.[part];
+    if (!current) return null;
+  }
+  return current;
+}