@eventcatalog/core 4.10.13 → 4.10.15

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 };
+  }
+};

package/eventcatalog/src/utils/collections/glob-loader.ts

@@ -1,4 +1,4 @@
-import { glob } from 'astro/loaders';
+import { glob, type Loader } from 'astro/loaders';
 import picomatch from 'picomatch';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -36,7 +36,7 @@ const matchesGlobPattern = (entry: string, patterns: string | string[]) => {
   return picomatch.isMatch(entry, positivePatterns) && !picomatch.isMatch(entry, negativePatterns);
 };
 
-export const globWithSafeWatcher = (options: GlobOptions) => {
+export const globWithSafeWatcher = (options: GlobOptions): Loader => {
   const loader = glob(options);
 
   return {

package/eventcatalog/src/utils/protobuf-schema.ts

@@ -17,6 +17,14 @@ export interface ProtobufField {
   map?: { keyType: string; valueType: string };
   oneof?: string;
   doc?: string;
+  options?: ProtobufOption[];
+}
+
+export type ProtobufOptionValue = string | number | boolean | ProtobufOptionValue[] | { [key: string]: ProtobufOptionValue };
+
+export interface ProtobufOption {
+  name: string;
+  value: ProtobufOptionValue;
 }
 
 export interface ProtobufEnumValue {
@@ -60,6 +68,81 @@ const isIdentifierChar = (char: string) => /[A-Za-z0-9_.]/.test(char);
 const isNumberStart = (char: string) => /[0-9-]/.test(char);
 const isNumberChar = (char: string) => /[0-9a-fA-FxX.+-]/.test(char);
 
+const UTF8_ENCODER = new TextEncoder();
+const UTF8_DECODER = new TextDecoder('utf-8', { fatal: true });
+
+const SIMPLE_STRING_ESCAPES: Record<string, number> = {
+  a: 0x07,
+  b: 0x08,
+  f: 0x0c,
+  n: 0x0a,
+  r: 0x0d,
+  t: 0x09,
+  v: 0x0b,
+  '?': 0x3f,
+  '\\': 0x5c,
+  "'": 0x27,
+  '"': 0x22,
+};
+
+function decodeStringEscape(content: string, start: number, line: number): { bytes: number[]; nextIndex: number } {
+  const escapeType = content[start + 1];
+  if (!escapeType) throw new Error(`Unterminated string escape at line ${line}`);
+
+  if (escapeType in SIMPLE_STRING_ESCAPES) {
+    return { bytes: [SIMPLE_STRING_ESCAPES[escapeType]], nextIndex: start + 2 };
+  }
+
+  if (escapeType === 'x' || escapeType === 'X') {
+    const digits = content.slice(start + 2).match(/^[0-9a-fA-F]{1,2}/)?.[0];
+    if (!digits) throw new Error(`Invalid hexadecimal string escape at line ${line}`);
+    return { bytes: [Number.parseInt(digits, 16)], nextIndex: start + 2 + digits.length };
+  }
+
+  if (/[0-7]/.test(escapeType)) {
+    const digits = content.slice(start + 1).match(/^[0-7]{1,3}/)![0];
+    const byte = Number.parseInt(digits, 8);
+    if (byte > 0xff) throw new Error(`Octal string escape is out of byte range at line ${line}`);
+    return { bytes: [byte], nextIndex: start + 1 + digits.length };
+  }
+
+  if (escapeType === 'u' || escapeType === 'U') {
+    const digitCount = escapeType === 'u' ? 4 : 8;
+    const digits = content.slice(start + 2, start + 2 + digitCount);
+    if (digits.length !== digitCount || !/^[0-9a-fA-F]+$/.test(digits)) {
+      throw new Error(`Invalid Unicode string escape at line ${line}`);
+    }
+
+    const codePoint = Number.parseInt(digits, 16);
+    if (codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)) {
+      throw new Error(`Unicode string escape is out of range at line ${line}`);
+    }
+    return { bytes: [...UTF8_ENCODER.encode(String.fromCodePoint(codePoint))], nextIndex: start + 2 + digitCount };
+  }
+
+  throw new Error(`Invalid string escape "\\${escapeType}" at line ${line}`);
+}
+
+function parseIntegerOptionValue(value: string): number | string | undefined {
+  const sign = value.startsWith('-') ? -1n : 1n;
+  const unsignedValue = value.startsWith('-') || value.startsWith('+') ? value.slice(1) : value;
+  let magnitude: bigint;
+
+  if (/^0[xX][0-9a-fA-F]+$/.test(unsignedValue)) {
+    magnitude = BigInt(unsignedValue);
+  } else if (/^0[0-7]*$/.test(unsignedValue)) {
+    magnitude = BigInt(`0o${unsignedValue.slice(1) || '0'}`);
+  } else if (/^[1-9][0-9]*$/.test(unsignedValue)) {
+    magnitude = BigInt(unsignedValue);
+  } else {
+    return undefined;
+  }
+
+  const parsedValue = sign * magnitude;
+  if (parsedValue < BigInt(Number.MIN_SAFE_INTEGER) || parsedValue > BigInt(Number.MAX_SAFE_INTEGER)) return value;
+  return Number(parsedValue);
+}
+
 function tokenize(content: string): { tokens: Token[]; trailingComments: Map<number, string> } {
   const tokens: Token[] = [];
   const trailingComments = new Map<number, string>();
@@ -128,18 +211,31 @@ function tokenize(content: string): { tokens: Token[]; trailingComments: Map<num
     // String literal
     if (char === '"' || char === "'") {
       const quote = char;
-      let value = '';
+      const bytes: number[] = [];
       i++;
+      const rawValueStart = i;
+      let plainTextStart = i;
       while (i < content.length && content[i] !== quote) {
         if (content[i] === '\\') {
-          value += content[i + 1];
-          i += 2;
+          bytes.push(...UTF8_ENCODER.encode(content.slice(plainTextStart, i)));
+          const decodedEscape = decodeStringEscape(content, i, line);
+          bytes.push(...decodedEscape.bytes);
+          i = decodedEscape.nextIndex;
+          plainTextStart = i;
           continue;
         }
         if (content[i] === '\n') line++;
-        value += content[i];
         i++;
       }
+      bytes.push(...UTF8_ENCODER.encode(content.slice(plainTextStart, i)));
+      if (i >= content.length) throw new Error(`Unterminated string literal at line ${line}`);
+      const rawValue = content.slice(rawValueStart, i);
+      let value: string;
+      try {
+        value = UTF8_DECODER.decode(Uint8Array.from(bytes));
+      } catch {
+        value = rawValue;
+      }
       i++;
       pushToken({ value, line, isString: true });
       continue;
@@ -164,6 +260,18 @@ function tokenize(content: string): { tokens: Token[]; trailingComments: Map<num
       continue;
     }
 
+    // Signed symbolic floating-point values used by protobuf options (for example +inf).
+    if ((char === '+' || char === '-') && isIdentifierStart(content[i + 1] || '')) {
+      let value = char;
+      i++;
+      while (i < content.length && isIdentifierChar(content[i])) {
+        value += content[i];
+        i++;
+      }
+      pushToken({ value, line });
+      continue;
+    }
+
     if (isNumberStart(char)) {
       let value = content[i];
       i++;
@@ -232,16 +340,101 @@ class ProtobufParser {
     }
   }
 
-  // Skip field options like [deprecated = true, (custom) = "value"]
-  private skipFieldOptions() {
-    if (this.peek()?.value !== '[') return;
-    let depth = 0;
-    while (this.pos < this.tokens.length) {
-      const token = this.next();
-      if (token.value === '[') depth++;
-      if (token.value === ']') depth--;
-      if (depth === 0) return;
+  private parseAggregateOptionKey(): string {
+    if (this.peek()?.value !== '[') return this.next().value;
+
+    this.next();
+    const nameParts: string[] = [];
+    while (this.peek() && this.peek()!.value !== ']') nameParts.push(this.next().value);
+    this.expect(']');
+    return `[${nameParts.join('')}]`;
+  }
+
+  private parseOptionValue(): ProtobufOptionValue {
+    const token = this.peek();
+    if (!token) throw new Error('Unexpected end of protobuf option');
+
+    if (token.value === '{' || token.value === '<') {
+      const openingToken = this.next().value;
+      const closingToken = openingToken === '{' ? '}' : '>';
+      const value: { [key: string]: ProtobufOptionValue } = {};
+
+      while (this.peek() && this.peek()!.value !== closingToken) {
+        if (this.peek()!.value === ',' || this.peek()!.value === ';') {
+          this.next();
+          continue;
+        }
+
+        const key = this.parseAggregateOptionKey();
+        if (this.peek()?.value === ':') this.next();
+        const entryValue = this.parseOptionValue();
+        const existingValue = value[key];
+        value[key] =
+          existingValue === undefined
+            ? entryValue
+            : Array.isArray(existingValue)
+              ? [...existingValue, entryValue]
+              : [existingValue, entryValue];
+      }
+
+      this.expect(closingToken);
+      return value;
     }
+
+    if (token.value === '[') {
+      this.next();
+      const values: ProtobufOptionValue[] = [];
+
+      while (this.peek() && this.peek()!.value !== ']') {
+        if (this.peek()!.value === ',' || this.peek()!.value === ';') {
+          this.next();
+          continue;
+        }
+        values.push(this.parseOptionValue());
+      }
+
+      this.expect(']');
+      return values;
+    }
+
+    const valueToken = this.next();
+    if (valueToken.isString) {
+      let value = valueToken.value;
+      while (this.peek()?.isString) value += this.next().value;
+      return value;
+    }
+    if (valueToken.value === 'true') return true;
+    if (valueToken.value === 'false') return false;
+
+    const integerValue = parseIntegerOptionValue(valueToken.value);
+    if (integerValue !== undefined) return integerValue;
+
+    const numericValue = Number(valueToken.value);
+    if (Number.isNaN(numericValue)) return valueToken.value;
+    if (Number.isInteger(numericValue) && !Number.isSafeInteger(numericValue)) return valueToken.value;
+    return numericValue;
+  }
+
+  private parseFieldOptions(): ProtobufOption[] {
+    if (this.peek()?.value !== '[') return [];
+
+    this.next();
+    const options: ProtobufOption[] = [];
+
+    while (this.peek() && this.peek()!.value !== ']') {
+      if (this.peek()!.value === ',') {
+        this.next();
+        continue;
+      }
+
+      const nameParts: string[] = [];
+      while (this.peek() && this.peek()!.value !== '=') nameParts.push(this.next().value);
+      this.expect('=');
+      options.push({ name: nameParts.join(''), value: this.parseOptionValue() });
+    }
+
+    this.expect(']');
+    return options;
   }
 
   private getTrailingDoc(line: number): string | undefined {
@@ -384,7 +577,7 @@ class ProtobufParser {
     const name = this.next().value;
     this.expect('=');
     const numberToken = this.next();
-    this.skipFieldOptions();
+    const options = this.parseFieldOptions();
     const terminator = this.expect(';');
 
     const parsedNumber = Number.parseInt(numberToken.value, 10);
@@ -396,6 +589,7 @@ class ProtobufParser {
       label,
       oneof,
       doc: firstToken.doc || typeToken.doc || this.getTrailingDoc(terminator.line),
+      ...(options.length > 0 ? { options } : {}),
     };
   }
 
@@ -409,7 +603,7 @@ class ProtobufParser {
     const name = this.next().value;
     this.expect('=');
     const numberToken = this.next();
-    this.skipFieldOptions();
+    const options = this.parseFieldOptions();
     const terminator = this.expect(';');
 
     const parsedNumber = Number.parseInt(numberToken.value, 10);
@@ -420,6 +614,7 @@ class ProtobufParser {
       map: { keyType, valueType },
       number: Number.isNaN(parsedNumber) ? undefined : parsedNumber,
       doc: keyword.doc || this.getTrailingDoc(terminator.line),
+      ...(options.length > 0 ? { options } : {}),
     };
   }
 
@@ -452,7 +647,7 @@ class ProtobufParser {
       const valueToken = this.next();
       this.expect('=');
       const numberToken = this.next();
-      this.skipFieldOptions();
+      this.parseFieldOptions();
       const terminator = this.expect(';');
 
       const parsedNumber = Number.parseInt(numberToken.value, 10);

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "4.10.13",
+  "version": "4.10.15",
   "publishConfig": {
     "access": "public"
   },
@@ -32,10 +32,10 @@
   ],
   "dependencies": {
     "@ai-sdk/react": "^3.0.17",
-    "@astrojs/markdown-remark": "^7.2.4",
-    "@astrojs/mdx": "^7.0.8",
-    "@astrojs/node": "^11.1.4",
-    "@astrojs/react": "^6.0.4",
+    "@astrojs/markdown-remark": "^7.3.1",
+    "@astrojs/mdx": "^8.0.1",
+    "@astrojs/node": "^11.1.6",
+    "@astrojs/react": "^6.0.6",
     "@astrojs/rss": "^4.0.19",
     "@asyncapi/avro-schema-parser": "3.0.24",
     "@asyncapi/parser": "^3.6.0",
@@ -61,7 +61,7 @@
     "@tanstack/react-table": "^8.17.3",
     "@xyflow/react": "^12.3.6",
     "ai": "^6.0.17",
-    "astro": "7.2.8",
+    "astro": "7.3.3",
     "astro-expressive-code": "^0.44.0",
     "astro-seo": "^0.8.4",
     "auth-astro": "^4.2.0",
@@ -120,8 +120,8 @@
     "uuid": "^11.1.1",
     "zod": "^4.3.6",
     "@eventcatalog/linter": "1.1.19",
-    "@eventcatalog/visualiser": "^4.1.4",
-    "@eventcatalog/sdk": "2.29.0"
+    "@eventcatalog/sdk": "2.29.0",
+    "@eventcatalog/visualiser": "^4.1.4"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",