@eventcatalog/core 4.10.13 → 4.10.14

package/eventcatalog/src/components/SchemaExplorer/ProtobufSchemaViewer.tsx

@@ -1,5 +1,12 @@
 import { useState, useEffect, useRef, useMemo } from 'react';
 import type { ProtobufSchema, ProtobufMessage, ProtobufEnum, ProtobufField } from '@utils/protobuf-schema';
+import {
+  formatProtobufOptionValue,
+  formatProtovalidateRule,
+  getCustomFieldAnnotations,
+  getProtovalidateRules,
+  isProtovalidateRequired,
+} from './protobuf-validation';
 
 interface ProtobufSchemaViewerProps {
   schema: ProtobufSchema;
@@ -63,9 +70,21 @@ function lookupType<T>(map: Map<string, T>, typeName: string, packageName?: stri
   return undefined;
 }
 
-function formatProtobufType(field: ProtobufField): string {
-  if (field.map) return field.type;
-  return field.label ? `${field.label} ${field.type}` : field.type;
+function compactTypeName(typeName: string): string {
+  const normalized = typeName.startsWith('.') ? typeName.slice(1) : typeName;
+  return normalized.split('.').pop() ?? normalized;
+}
+
+function formatProtobufType(field: ProtobufField, compact = false): string {
+  const type = field.map
+    ? compact
+      ? `map<${field.map.keyType}, ${compactTypeName(field.map.valueType)}>`
+      : field.type
+    : compact
+      ? compactTypeName(field.type)
+      : field.type;
+
+  return field.label ? `${field.label} ${type}` : type;
 }
 
 function countFields(messages: ProtobufMessage[]): number {
@@ -92,7 +111,27 @@ const ProtobufFieldRow = ({ field, level, expand, showRequired, registry, packag
   const nestedEnum = nestedMessage ? undefined : lookupType(registry.enums, targetTypeName, packageName);
   const isCyclic = nestedMessage ? ancestors.includes(nestedMessage.name) : false;
   const hasNested = !!nestedMessage && nestedMessage.fields.length > 0 && !isCyclic;
-  const isRequired = field.label === 'required';
+  const hasRequiredAnnotation = isProtovalidateRequired(field);
+  const isRequired = hasRequiredAnnotation || field.label === 'required';
+  const validationRules = getProtovalidateRules(field).filter((rule) => rule.path !== 'required');
+  const customAnnotations = getCustomFieldAnnotations(field);
+  const fullType = formatProtobufType(field);
+  const displayType = formatProtobufType(field, true);
+  const enumRuleScope = field.map ? 'map.values.enum' : field.label === 'repeated' ? 'repeated.items.enum' : 'enum';
+  const enumConstant = validationRules.find((rule) => rule.path === `${enumRuleScope}.const`);
+  const enumIncludes = validationRules.find((rule) => rule.path === `${enumRuleScope}.in`);
+  const enumExcludes = validationRules.find((rule) => rule.path === `${enumRuleScope}.not_in`);
+  const normalizeRuleValues = (value: unknown) => (Array.isArray(value) ? value : value === undefined ? [] : [value]);
+  const includedEnumValues = normalizeRuleValues(enumIncludes?.value);
+  const excludedEnumValues = normalizeRuleValues(enumExcludes?.value);
+  const displayedEnumValues = nestedEnum?.values.filter((value) => {
+    const matches = (candidate: unknown) => String(candidate) === String(value.value) || candidate === value.name;
+    return (
+      (!enumConstant || matches(enumConstant.value)) &&
+      (includedEnumValues.length === 0 || includedEnumValues.some(matches)) &&
+      !excludedEnumValues.some(matches)
+    );
+  });
 
   useEffect(() => {
     setIsExpanded(expand);
@@ -116,40 +155,83 @@ const ProtobufFieldRow = ({ field, level, expand, showRequired, registry, packag
         )}
 
         <div className="flex-grow">
-          <div className="flex justify-between items-baseline">
-            <div>
-              <span className="proto-field-name font-semibold text-[rgb(var(--ec-page-text))] text-sm">{field.name}</span>
-              <span className="ml-1.5 text-[rgb(var(--ec-accent))] font-mono text-xs">{formatProtobufType(field)}</span>
-              {field.number !== undefined && (
-                <span className="ml-1.5 text-[rgb(var(--ec-page-text-muted))] font-mono text-xs">= {field.number}</span>
-              )}
-              {field.oneof && (
-                <span className="ml-1.5 text-[rgb(var(--ec-page-text-muted))] text-xs bg-[rgb(var(--ec-content-hover))] px-1 rounded">
-                  oneof {field.oneof}
+          <div className="-mx-1 rounded px-1 transition-colors hover:bg-[rgb(var(--ec-content-hover))]">
+            <div className="flex justify-between items-baseline">
+              <div>
+                <span className="proto-field-name font-semibold text-[rgb(var(--ec-page-text))] text-sm">{field.name}</span>
+                <span
+                  className="ml-1.5 text-[rgb(var(--ec-accent))] font-mono text-xs"
+                  title={displayType === fullType ? undefined : fullType}
+                >
+                  {displayType}
                 </span>
+                {field.number !== undefined && (
+                  <span className="ml-1.5 text-[rgb(var(--ec-page-text-muted))] font-mono text-xs">= {field.number}</span>
+                )}
+                {field.oneof && (
+                  <span className="ml-1.5 text-[rgb(var(--ec-page-text-muted))] text-xs bg-[rgb(var(--ec-content-hover))] px-1 rounded">
+                    oneof {field.oneof}
+                  </span>
+                )}
+              </div>
+              {(hasRequiredAnnotation || (showRequired && isRequired)) && (
+                <span className="text-red-600 dark:text-red-400 text-xs ml-3 flex-shrink-0">required</span>
               )}
             </div>
-            {showRequired && isRequired && (
-              <span className="text-red-600 dark:text-red-400 text-xs ml-3 flex-shrink-0">required</span>
+
+            {field.doc && <p className="text-[rgb(var(--ec-page-text-muted))] text-xs mt-0.5">{field.doc}</p>}
+
+            {validationRules.length > 0 && (
+              <div className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-0.5 space-y-0">
+                {validationRules.map((rule, index) => {
+                  const display = formatProtovalidateRule(rule);
+                  return (
+                    <div key={`${rule.path}-${index}`}>
+                      {display.label}
+                      {display.value !== undefined && (
+                        <>
+                          :{' '}
+                          <code className="bg-[rgb(var(--ec-content-hover))] px-1 rounded text-[rgb(var(--ec-page-text))] font-thin py-0.5">
+                            {display.value}
+                          </code>
+                        </>
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
             )}
-          </div>
 
-          {field.doc && <p className="text-[rgb(var(--ec-page-text-muted))] text-xs mt-0.5">{field.doc}</p>}
-
-          {/* Show enum values if the field type resolves to an enum */}
-          {nestedEnum && nestedEnum.values.length > 0 && (
-            <div className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-0.5">
-              <span className="text-xs inline-block">Allowed values:</span>
-              {nestedEnum.values.map((value) => (
-                <span key={value.name} className="text-xs">
-                  {' '}
-                  <code className="bg-[rgb(var(--ec-content-hover))] px-1 rounded text-[rgb(var(--ec-page-text))] font-thin py-0.5">
-                    {value.name}
-                  </code>
-                </span>
-              ))}
-            </div>
-          )}
+            {customAnnotations.length > 0 && (
+              <div className="mt-0.5 space-y-0 text-xs text-gray-400 dark:text-gray-500">
+                {customAnnotations.map((annotation, index) => (
+                  <div key={`${annotation.name}-${index}`} className="flex max-w-full flex-wrap items-baseline gap-x-1">
+                    <span>Annotation:</span>
+                    <code className="break-all font-mono text-gray-500 dark:text-gray-400">{annotation.name}</code>
+                    <span>=</span>
+                    <code className="font-medium text-gray-500 dark:text-gray-400">
+                      {formatProtobufOptionValue(annotation.value)}
+                    </code>
+                  </div>
+                ))}
+              </div>
+            )}
+
+            {/* Show enum values if the field type resolves to an enum */}
+            {nestedEnum && displayedEnumValues && displayedEnumValues.length > 0 && (
+              <div className="text-xs text-[rgb(var(--ec-page-text-muted))] mt-0.5">
+                <span className="text-xs inline-block">Allowed values:</span>
+                {displayedEnumValues.map((value) => (
+                  <span key={value.name} className="text-xs">
+                    {' '}
+                    <code className="bg-[rgb(var(--ec-content-hover))] px-1 rounded text-[rgb(var(--ec-page-text))] font-thin py-0.5">
+                      {value.name}
+                    </code>
+                  </span>
+                ))}
+              </div>
+            )}
+          </div>
 
           {/* Nested fields for message types */}
           {hasNested && nestedMessage && (

package/eventcatalog/src/components/SchemaExplorer/SchemaViewerHover.test.tsx

@@ -0,0 +1,33 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { parseProtobufSchema } from '@utils/protobuf-schema';
+import AvroSchemaViewer from './AvroSchemaViewer';
+import JSONSchemaViewer from './JSONSchemaViewer';
+import ProtobufSchemaViewer from './ProtobufSchemaViewer';
+
+const PROPERTY_HOVER_CLASS = 'hover:bg-[rgb(var(--ec-content-hover))]';
+
+describe('schema viewer property hover states', () => {
+  it('adds a hover background to JSON Schema properties', () => {
+    const html = renderToStaticMarkup(
+      <JSONSchemaViewer schema={{ type: 'object', properties: { id: { type: 'string' } } }} search={false} />
+    );
+
+    expect(html).toContain(PROPERTY_HOVER_CLASS);
+  });
+
+  it('adds a hover background to Avro fields', () => {
+    const html = renderToStaticMarkup(
+      <AvroSchemaViewer schema={{ type: 'record', name: 'Example', fields: [{ name: 'id', type: 'string' }] }} search={false} />
+    );
+
+    expect(html).toContain(PROPERTY_HOVER_CLASS);
+  });
+
+  it('adds a hover background to Protobuf fields', () => {
+    const schema = parseProtobufSchema('syntax = "proto3"; message Example { string id = 1; }');
+    const html = renderToStaticMarkup(<ProtobufSchemaViewer schema={schema} search={false} />);
+
+    expect(html).toContain(PROPERTY_HOVER_CLASS);
+  });
+});

package/eventcatalog/src/components/SchemaExplorer/protobuf-validation.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import type { ProtobufField } from '@utils/protobuf-schema';
+import {
+  formatProtobufOptionValue,
+  formatProtovalidateRule,
+  getCustomFieldAnnotations,
+  getProtovalidateRules,
+  isProtovalidateRequired,
+} from './protobuf-validation';
+
+describe('protobuf validation helpers', () => {
+  it('flattens direct and aggregate Protovalidate options', () => {
+    const field: ProtobufField = {
+      name: 'status',
+      type: 'Status',
+      options: [
+        { name: '(buf.validate.field).required', value: true },
+        {
+          name: '(buf.validate.field).enum',
+          value: { defined_only: true, not_in: [0] },
+        },
+      ],
+    };
+
+    expect(getProtovalidateRules(field)).toEqual([
+      { path: 'required', value: true },
+      { path: 'enum.defined_only', value: true },
+      { path: 'enum.not_in', value: [0] },
+    ]);
+    expect(isProtovalidateRequired(field)).toBe(true);
+  });
+
+  it('ignores non-Protovalidate custom options', () => {
+    const field: ProtobufField = {
+      name: 'description',
+      type: 'string',
+      options: [{ name: '(datahub.v1.gdpr_rule).string', value: true }],
+    };
+
+    expect(getProtovalidateRules(field)).toEqual([]);
+    expect(isProtovalidateRequired(field)).toBe(false);
+    expect(getCustomFieldAnnotations(field)).toEqual([{ name: '(datahub.v1.gdpr_rule).string', value: true }]);
+  });
+
+  it('only treats extension options as custom annotations and formats aggregate values', () => {
+    const field: ProtobufField = {
+      name: 'description',
+      type: 'string',
+      options: [
+        { name: 'deprecated', value: true },
+        { name: '(buf.validate.field).string.min_len', value: 1 },
+        { name: '(datahub.v1.classification)', value: { level: 'personal', encrypted: true } },
+      ],
+    };
+
+    expect(getCustomFieldAnnotations(field)).toEqual([
+      {
+        name: '(datahub.v1.classification)',
+        value: { level: 'personal', encrypted: true },
+      },
+    ]);
+    expect(formatProtobufOptionValue(getCustomFieldAnnotations(field)[0].value)).toBe('{"level":"personal","encrypted":true}');
+  });
+
+  it('formats common rules for display', () => {
+    expect(formatProtovalidateRule({ path: 'string.email', value: true })).toEqual({ label: 'Format', value: 'Email' });
+    expect(formatProtovalidateRule({ path: 'uint32.gte', value: 1 })).toEqual({ label: 'Minimum', value: '1' });
+    expect(formatProtovalidateRule({ path: 'enum.defined_only', value: true })).toEqual({
+      label: 'Defined enum values only',
+    });
+    expect(formatProtovalidateRule({ path: 'enum.not_in', value: [0] })).toEqual({
+      label: 'Excluded values',
+      value: '0',
+    });
+    expect(formatProtovalidateRule({ path: 'repeated.items.string.min_len', value: 3 })).toEqual({
+      label: 'Item minimum length',
+      value: '3',
+    });
+    expect(formatProtovalidateRule({ path: 'map.values.string.max_len', value: 100 })).toEqual({
+      label: 'Value maximum length',
+      value: '100',
+    });
+  });
+});

package/eventcatalog/src/components/SchemaExplorer/protobuf-validation.ts

@@ -0,0 +1,149 @@
+import type { ProtobufField, ProtobufOptionValue } from '@utils/protobuf-schema';
+
+const PROTOVALIDATE_FIELD_OPTION = '(buf.validate.field)';
+
+export interface ProtovalidateRule {
+  path: string;
+  value: ProtobufOptionValue;
+}
+
+export interface ProtovalidateRuleDisplay {
+  label: string;
+  value?: string;
+}
+
+export interface ProtobufCustomAnnotation {
+  name: string;
+  value: ProtobufOptionValue;
+}
+
+const isOptionObject = (value: ProtobufOptionValue): value is { [key: string]: ProtobufOptionValue } =>
+  typeof value === 'object' && !Array.isArray(value);
+
+const flattenOptionValue = (path: string, value: ProtobufOptionValue): ProtovalidateRule[] => {
+  if (!isOptionObject(value)) return [{ path, value }];
+
+  return Object.entries(value).flatMap(([name, nestedValue]) => flattenOptionValue(path ? `${path}.${name}` : name, nestedValue));
+};
+
+export const getProtovalidateRules = (field: ProtobufField): ProtovalidateRule[] =>
+  (field.options ?? []).flatMap((option) => {
+    if (option.name !== PROTOVALIDATE_FIELD_OPTION && !option.name.startsWith(`${PROTOVALIDATE_FIELD_OPTION}.`)) return [];
+
+    const path = option.name.slice(PROTOVALIDATE_FIELD_OPTION.length).replace(/^\./, '');
+    return flattenOptionValue(path, option.value);
+  });
+
+export const isProtovalidateRequired = (field: ProtobufField) =>
+  getProtovalidateRules(field).some((rule) => rule.path === 'required' && rule.value === true);
+
+export const getCustomFieldAnnotations = (field: ProtobufField): ProtobufCustomAnnotation[] =>
+  (field.options ?? [])
+    .filter(
+      (option) =>
+        option.name.startsWith('(') &&
+        option.name !== PROTOVALIDATE_FIELD_OPTION &&
+        !option.name.startsWith(`${PROTOVALIDATE_FIELD_OPTION}.`)
+    )
+    .map(({ name, value }) => ({ name, value }));
+
+export const formatProtobufOptionValue = (value: ProtobufOptionValue): string => {
+  if (Array.isArray(value)) return value.map(formatProtobufOptionValue).join(', ');
+  if (isOptionObject(value)) return JSON.stringify(value);
+  return String(value);
+};
+
+const humanize = (value: string) => value.replace(/_/g, ' ').replace(/\b\w/g, (character) => character.toUpperCase());
+
+const FORMAT_NAMES: Record<string, string> = {
+  address: 'Address',
+  email: 'Email',
+  hostname: 'Hostname',
+  ip: 'IP',
+  ipv4: 'IPv4',
+  ipv6: 'IPv6',
+  protobuf_fqn: 'Protobuf FQN',
+  tuuid: 'TUUID',
+  uri: 'URI',
+  uri_ref: 'URI reference',
+  uuid: 'UUID',
+};
+
+const getRuleScope = (path: string) => {
+  if (path.includes('repeated.items')) return 'Item';
+  if (path.includes('map.keys')) return 'Key';
+  if (path.includes('map.values')) return 'Value';
+  return '';
+};
+
+const withScope = (scope: string, label: string) =>
+  scope ? `${scope} ${label.charAt(0).toLowerCase()}${label.slice(1)}` : label;
+
+export const formatProtovalidateRule = ({ path, value }: ProtovalidateRule): ProtovalidateRuleDisplay => {
+  const name = path.split('.').pop() ?? path;
+  const scope = getRuleScope(path);
+  const formattedValue = formatProtobufOptionValue(value);
+
+  switch (name) {
+    case 'required':
+      return value === true ? { label: 'Required' } : { label: 'Required', value: formattedValue };
+    case 'const':
+      return { label: withScope(scope, 'Constant'), value: formattedValue };
+    case 'len':
+      return { label: withScope(scope, 'Length'), value: formattedValue };
+    case 'min_len':
+      return { label: withScope(scope, 'Minimum length'), value: formattedValue };
+    case 'max_len':
+      return { label: withScope(scope, 'Maximum length'), value: formattedValue };
+    case 'len_bytes':
+      return { label: withScope(scope, 'Byte length'), value: formattedValue };
+    case 'min_bytes':
+      return { label: withScope(scope, 'Minimum byte length'), value: formattedValue };
+    case 'max_bytes':
+      return { label: withScope(scope, 'Maximum byte length'), value: formattedValue };
+    case 'pattern':
+      return { label: withScope(scope, 'Match pattern'), value: formattedValue };
+    case 'gt':
+      return { label: withScope(scope, 'Greater than'), value: formattedValue };
+    case 'gte':
+      return { label: withScope(scope, 'Minimum'), value: formattedValue };
+    case 'lt':
+      return { label: withScope(scope, 'Less than'), value: formattedValue };
+    case 'lte':
+      return { label: withScope(scope, 'Maximum'), value: formattedValue };
+    case 'in':
+      return { label: withScope(scope, 'Allowed values'), value: formattedValue };
+    case 'not_in':
+      return { label: withScope(scope, 'Excluded values'), value: formattedValue };
+    case 'defined_only':
+      return value === true
+        ? { label: 'Defined enum values only' }
+        : { label: 'Defined enum values only', value: formattedValue };
+    case 'min_items':
+      return { label: 'Minimum items', value: formattedValue };
+    case 'max_items':
+      return { label: 'Maximum items', value: formattedValue };
+    case 'unique':
+      return value === true ? { label: 'Unique items' } : { label: 'Unique items', value: formattedValue };
+    case 'min_pairs':
+      return { label: 'Minimum map entries', value: formattedValue };
+    case 'max_pairs':
+      return { label: 'Maximum map entries', value: formattedValue };
+    case 'email':
+    case 'hostname':
+    case 'ip':
+    case 'ipv4':
+    case 'ipv6':
+    case 'uri':
+    case 'uri_ref':
+    case 'address':
+    case 'uuid':
+    case 'tuuid':
+    case 'protobuf_fqn':
+      return value === true
+        ? { label: withScope(scope, 'Format'), value: FORMAT_NAMES[name] }
+        : { label: withScope(scope, humanize(name)), value: formattedValue };
+    default:
+      return { label: withScope(scope, humanize(name)), value: formattedValue };
+  }
+};