@diagrammo/dgmo 0.2.5 → 0.2.7

package/src/sequence/parser.ts

@@ -63,12 +63,18 @@ export interface SequenceMessage {
 /**
  * A conditional or loop block in the sequence diagram.
  */
+export interface ElseIfBranch {
+  label: string;
+  children: SequenceElement[];
+}
+
 export interface SequenceBlock {
   kind: 'block';
   type: 'if' | 'loop' | 'parallel';
   label: string;
   children: SequenceElement[];
   elseChildren: SequenceElement[];
+  elseIfBranches?: ElseIfBranch[];
   lineNumber: number;
 }
 
@@ -82,7 +88,22 @@ export interface SequenceSection {
   lineNumber: number;
 }
 
-export type SequenceElement = SequenceMessage | SequenceBlock | SequenceSection;
+/**
+ * An annotation attached to a message, rendered as a folded-corner box.
+ */
+export interface SequenceNote {
+  kind: 'note';
+  text: string;
+  position: 'right' | 'left';
+  participantId: string;
+  lineNumber: number;
+}
+
+export type SequenceElement =
+  | SequenceMessage
+  | SequenceBlock
+  | SequenceSection
+  | SequenceNote;
 
 export function isSequenceBlock(el: SequenceElement): el is SequenceBlock {
   return 'kind' in el && (el as SequenceBlock).kind === 'block';
@@ -92,6 +113,10 @@ export function isSequenceSection(el: SequenceElement): el is SequenceSection {
   return 'kind' in el && (el as SequenceSection).kind === 'section';
 }
 
+export function isSequenceNote(el: SequenceElement): el is SequenceNote {
+  return 'kind' in el && (el as SequenceNote).kind === 'note';
+}
+
 /**
  * A named group of participants rendered as a labeled box.
  */
@@ -123,11 +148,11 @@ const IS_A_PATTERN = /^(\S+)\s+is\s+an?\s+(\w+)(?:\s+(.+))?$/i;
 // Standalone "Name position N" pattern — e.g. "DB position -1"
 const POSITION_ONLY_PATTERN = /^(\S+)\s+position\s+(-?\d+)$/i;
 
-// Group heading pattern — "## Backend" or "## Backend(blue)"
-const GROUP_HEADING_PATTERN = /^##\s+(\S+?)(?:\((\w+)\))?$/;
+// Group heading pattern — "## Backend", "## API Services(blue)", "## Backend(#hex)"
+const GROUP_HEADING_PATTERN = /^##\s+(.+?)(?:\(([^)]+)\))?\s*$/;
 
-// Section divider pattern — "== Label ==" or "== Label(color) =="
-const SECTION_PATTERN = /^==\s+(.+?)\s*==$/;
+// Section divider pattern — "== Label ==", "== Label(color) ==", or "== Label" (trailing == optional)
+const SECTION_PATTERN = /^==\s+(.+?)(?:\s*==)?\s*$/;
 
 // Arrow pattern for sequence inference — "A -> B: message" or "A ~> B: message"
 const ARROW_PATTERN = /\S+\s*(?:->|~>)\s*\S+/;
@@ -138,6 +163,10 @@ const ARROW_RETURN_PATTERN = /^(.+?)\s*<-\s*(.+)$/;
 // UML method(args): returnType syntax: "getUser(id): UserObj"
 const UML_RETURN_PATTERN = /^(\w+\([^)]*\))\s*:\s*(.+)$/;
 
+// Note patterns — "note: text", "note right of API: text", "note left of User"
+const NOTE_SINGLE = /^note(?:\s+(right|left)\s+of\s+(\S+))?\s*:\s*(.+)$/i;
+const NOTE_MULTI = /^note(?:\s+(right|left)\s+of\s+(\S+))?\s*$/i;
+
 /**
  * Extract return label from a message label string.
  * Priority: `<-` syntax first, then UML `method(): return` syntax,
@@ -161,13 +190,17 @@ function parseReturnLabel(rawLabel: string): {
     return { label: umlReturn[1].trim(), returnLabel: umlReturn[2].trim() };
   }
 
-  // Shorthand request : response syntax (split on last " : ")
-  const lastSep = rawLabel.lastIndexOf(' : ');
-  if (lastSep > 0) {
-    const reqPart = rawLabel.substring(0, lastSep).trim();
-    const resPart = rawLabel.substring(lastSep + 3).trim();
-    if (reqPart && resPart) {
-      return { label: reqPart, returnLabel: resPart };
+  // Shorthand colon return syntax (split on last ":")
+  // Skip if the colon is part of a URL scheme (followed by //)
+  const lastColon = rawLabel.lastIndexOf(':');
+  if (lastColon > 0 && lastColon < rawLabel.length - 1) {
+    const afterColon = rawLabel.substring(lastColon + 1);
+    if (!afterColon.startsWith('//')) {
+      const reqPart = rawLabel.substring(0, lastColon).trim();
+      const resPart = afterColon.trim();
+      if (reqPart && resPart) {
+        return { label: reqPart, returnLabel: resPart };
+      }
     }
   }
 
@@ -209,22 +242,31 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
 
   const lines = content.split('\n');
   let hasExplicitChart = false;
+  let contentStarted = false;
 
   // Group parsing state — tracks the active ## group heading
   let activeGroup: SequenceGroup | null = null;
 
+  // Track participant → group name for duplicate membership detection
+  const participantGroupMap = new Map<string, string>();
+
   // Block parsing state
   const blockStack: {
     block: SequenceBlock;
     indent: number;
     inElse: boolean;
+    activeElseIfBranch?: ElseIfBranch;
   }[] = [];
   const currentContainer = (): SequenceElement[] => {
     if (blockStack.length === 0) return result.elements;
     const top = blockStack[blockStack.length - 1];
+    if (top.activeElseIfBranch) return top.activeElseIfBranch.children;
     return top.inElse ? top.block.elseChildren : top.block.children;
   };
 
+  // Track last message sender for default note positioning
+  let lastMsgFrom: string | null = null;
+
   for (let i = 0; i < lines.length; i++) {
     const raw = lines[i];
     const trimmed = raw.trim();
@@ -239,9 +281,15 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
     // Parse group heading — must be checked before comment skip since ## starts with #
     const groupMatch = trimmed.match(GROUP_HEADING_PATTERN);
     if (groupMatch) {
+      const groupColor = groupMatch[2]?.trim();
+      if (groupColor && groupColor.startsWith('#')) {
+        result.error = `Line ${lineNumber}: Use a named color instead of hex (e.g., blue, red, teal)`;
+        return result;
+      }
+      contentStarted = true;
       activeGroup = {
-        name: groupMatch[1],
-        color: groupMatch[2] || undefined,
+        name: groupMatch[1].trim(),
+        color: groupColor || undefined,
         participantIds: [],
         lineNumber,
       };
@@ -254,8 +302,14 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
       activeGroup = null;
     }
 
-    // Skip comments
-    if (trimmed.startsWith('#') || trimmed.startsWith('//')) continue;
+    // Skip comments — only // is supported
+    if (trimmed.startsWith('//')) continue;
+
+    // Reject # as comment syntax (## is for group headings, handled above)
+    if (trimmed.startsWith('#') && !trimmed.startsWith('##')) {
+      result.error = `Line ${lineNumber}: Use // for comments. # is reserved for group headings (##)`;
+      return result;
+    }
 
     // Parse section dividers — "== Label ==" or "== Label(color) =="
     // Close blocks first — sections at indent 0 should not nest inside blocks
@@ -268,11 +322,16 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
         blockStack.pop();
       }
       const labelRaw = sectionMatch[1].trim();
-      const colorMatch = labelRaw.match(/^(.+?)\((\w+)\)$/);
+      const colorMatch = labelRaw.match(/^(.+?)\(([^)]+)\)$/);
+      if (colorMatch && colorMatch[2].trim().startsWith('#')) {
+        result.error = `Line ${lineNumber}: Use a named color instead of hex (e.g., blue, red, teal)`;
+        return result;
+      }
+      contentStarted = true;
       const section: SequenceSection = {
         kind: 'section',
         label: colorMatch ? colorMatch[1].trim() : labelRaw,
-        color: colorMatch ? colorMatch[2] : undefined,
+        color: colorMatch ? colorMatch[2].trim() : undefined,
         lineNumber,
       };
       result.sections.push(section);
@@ -281,9 +340,13 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
     }
 
     // Parse header key: value lines (always top-level)
+    // Skip 'note' lines — parsed in the indent-aware section below
     const colonIndex = trimmed.indexOf(':');
     if (colonIndex > 0 && !trimmed.includes('->') && !trimmed.includes('~>')) {
       const key = trimmed.substring(0, colonIndex).trim().toLowerCase();
+      if (key === 'note' || key.startsWith('note ')) {
+        // Fall through to indent-aware note parsing below
+      } else {
       const value = trimmed.substring(colonIndex + 1).trim();
 
       if (key === 'chart') {
@@ -295,6 +358,12 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
         continue;
       }
 
+      // Enforce headers-before-content
+      if (contentStarted) {
+        result.error = `Line ${lineNumber}: Options like '${key}: ${value}' must appear before the first message or declaration`;
+        return result;
+      }
+
       if (key === 'title') {
         result.title = value;
         continue;
@@ -303,11 +372,13 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
       // Store other options
       result.options[key] = value;
       continue;
+      }
     }
 
     // Parse "Name is a type [aka Alias]" declarations (always top-level)
     const isAMatch = trimmed.match(IS_A_PATTERN);
     if (isAMatch) {
+      contentStarted = true;
       const id = isAMatch[1];
       const typeStr = isAMatch[2].toLowerCase();
       const remainder = isAMatch[3]?.trim() || '';
@@ -338,7 +409,13 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
       }
       // Track group membership
       if (activeGroup && !activeGroup.participantIds.includes(id)) {
+        const existingGroup = participantGroupMap.get(id);
+        if (existingGroup) {
+          result.error = `Line ${lineNumber}: Participant '${id}' is already in group '${existingGroup}' — participants can only belong to one group`;
+          return result;
+        }
         activeGroup.participantIds.push(id);
+        participantGroupMap.set(id, activeGroup.name);
       }
       continue;
     }
@@ -346,6 +423,7 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
     // Parse standalone "Name position N" (no "is a" type)
     const posOnlyMatch = trimmed.match(POSITION_ONLY_PATTERN);
     if (posOnlyMatch) {
+      contentStarted = true;
       const id = posOnlyMatch[1];
       const position = parseInt(posOnlyMatch[2], 10);
 
@@ -360,13 +438,20 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
       }
       // Track group membership
       if (activeGroup && !activeGroup.participantIds.includes(id)) {
+        const existingGroup = participantGroupMap.get(id);
+        if (existingGroup) {
+          result.error = `Line ${lineNumber}: Participant '${id}' is already in group '${existingGroup}' — participants can only belong to one group`;
+          return result;
+        }
         activeGroup.participantIds.push(id);
+        participantGroupMap.set(id, activeGroup.name);
       }
       continue;
     }
 
     // Bare participant name inside an active group (single identifier on an indented line)
     if (activeGroup && measureIndent(raw) > 0 && /^\S+$/.test(trimmed)) {
+      contentStarted = true;
       const id = trimmed;
       if (!result.participants.some((p) => p.id === id)) {
         result.participants.push({
@@ -377,7 +462,13 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
         });
       }
       if (!activeGroup.participantIds.includes(id)) {
+        const existingGroup = participantGroupMap.get(id);
+        if (existingGroup) {
+          result.error = `Line ${lineNumber}: Participant '${id}' is already in group '${existingGroup}' — participants can only belong to one group`;
+          return result;
+        }
         activeGroup.participantIds.push(id);
+        participantGroupMap.set(id, activeGroup.name);
       }
       continue;
     }
@@ -389,38 +480,41 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
     while (blockStack.length > 0) {
       const top = blockStack[blockStack.length - 1];
       if (indent > top.indent) break;
+      // Keep block on stack when 'else' or 'else if' matches current indent — handled below
       if (
         indent === top.indent &&
-        trimmed.toLowerCase() === 'else' &&
-        top.block.type === 'if'
-      )
-        break;
+        (top.block.type === 'if' || top.block.type === 'parallel')
+      ) {
+        const lower = trimmed.toLowerCase();
+        if (lower === 'else' || lower.startsWith('else if ')) break;
+      }
       blockStack.pop();
     }
 
     // Parse message lines first — arrows take priority over keywords
-    // Detect async prefix: "async A -> B: msg"
-    let isAsync = false;
-    let arrowLine = trimmed;
+    // Reject "async" keyword prefix — use ~> instead
     const asyncPrefixMatch = trimmed.match(/^async\s+(.+)$/i);
-    if (asyncPrefixMatch) {
-      isAsync = true;
-      arrowLine = asyncPrefixMatch[1];
+    if (asyncPrefixMatch && ARROW_PATTERN.test(asyncPrefixMatch[1])) {
+      result.error = `Line ${lineNumber}: Use ~> for async messages: A ~> B: message`;
+      return result;
     }
 
     // Match ~> (async arrow) or -> (sync arrow)
-    const asyncArrowMatch = arrowLine.match(
+    let isAsync = false;
+    const asyncArrowMatch = trimmed.match(
       /^(\S+)\s*~>\s*([^\s:]+)\s*(?::\s*(.+))?$/
     );
-    const syncArrowMatch = arrowLine.match(
+    const syncArrowMatch = trimmed.match(
       /^(\S+)\s*->\s*([^\s:]+)\s*(?::\s*(.+))?$/
     );
     const arrowMatch = asyncArrowMatch || syncArrowMatch;
     if (asyncArrowMatch) isAsync = true;
 
     if (arrowMatch) {
+      contentStarted = true;
       const from = arrowMatch[1];
       const to = arrowMatch[2];
+      lastMsgFrom = from;
       const rawLabel = arrowMatch[3]?.trim() || '';
 
       // Extract return label — skip for async messages
@@ -462,6 +556,7 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
     // Parse 'if <label>' block keyword
     const ifMatch = trimmed.match(/^if\s+(.+)$/i);
     if (ifMatch) {
+      contentStarted = true;
       const block: SequenceBlock = {
         kind: 'block',
         type: 'if',
@@ -478,6 +573,7 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
     // Parse 'loop <label>' block keyword
     const loopMatch = trimmed.match(/^loop\s+(.+)$/i);
     if (loopMatch) {
+      contentStarted = true;
       const block: SequenceBlock = {
         kind: 'block',
         type: 'loop',
@@ -494,6 +590,7 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
     // Parse 'parallel [label]' block keyword
     const parallelMatch = trimmed.match(/^parallel(?:\s+(.+))?$/i);
     if (parallelMatch) {
+      contentStarted = true;
       const block: SequenceBlock = {
         kind: 'block',
         type: 'parallel',
@@ -507,15 +604,110 @@ export function parseSequenceDgmo(content: string): ParsedSequenceDgmo {
       continue;
     }
 
+    // Parse 'else if <label>' keyword (must come before bare 'else')
+    const elseIfMatch = trimmed.match(/^else\s+if\s+(.+)$/i);
+    if (elseIfMatch) {
+      if (blockStack.length > 0 && blockStack[blockStack.length - 1].indent === indent) {
+        const top = blockStack[blockStack.length - 1];
+        if (top.block.type === 'parallel') {
+          result.error = `Line ${lineNumber}: parallel blocks don't support else if — list all concurrent messages directly inside the block`;
+          return result;
+        }
+        if (top.block.type === 'if') {
+          const branch: ElseIfBranch = { label: elseIfMatch[1].trim(), children: [] };
+          if (!top.block.elseIfBranches) top.block.elseIfBranches = [];
+          top.block.elseIfBranches.push(branch);
+          top.activeElseIfBranch = branch;
+          top.inElse = false;
+        }
+      }
+      continue;
+    }
+
     // Parse 'else' keyword (only applies to 'if' blocks)
     if (trimmed.toLowerCase() === 'else') {
-      if (
-        blockStack.length > 0 &&
-        blockStack[blockStack.length - 1].indent === indent &&
-        blockStack[blockStack.length - 1].block.type === 'if'
-      ) {
-        blockStack[blockStack.length - 1].inElse = true;
+      if (blockStack.length > 0 && blockStack[blockStack.length - 1].indent === indent) {
+        const top = blockStack[blockStack.length - 1];
+        if (top.block.type === 'parallel') {
+          result.error = `Line ${lineNumber}: parallel blocks don't support else — list all concurrent messages directly inside the block`;
+          return result;
+        }
+        if (top.block.type === 'if') {
+          top.inElse = true;
+          top.activeElseIfBranch = undefined;
+        }
+      }
+      continue;
+    }
+
+    // Parse single-line note — "note: text" or "note right of API: text"
+    const noteSingleMatch = trimmed.match(NOTE_SINGLE);
+    if (noteSingleMatch) {
+      const notePosition =
+        (noteSingleMatch[1]?.toLowerCase() as 'right' | 'left') || 'right';
+      let noteParticipant = noteSingleMatch[2] || null;
+      if (!noteParticipant) {
+        if (!lastMsgFrom) {
+          result.error = `Line ${lineNumber}: note requires a preceding message`;
+          return result;
+        }
+        noteParticipant = lastMsgFrom;
       }
+      if (!result.participants.some((p) => p.id === noteParticipant)) {
+        result.error = `Line ${lineNumber}: note references unknown participant '${noteParticipant}'`;
+        return result;
+      }
+      const note: SequenceNote = {
+        kind: 'note',
+        text: noteSingleMatch[3].trim(),
+        position: notePosition,
+        participantId: noteParticipant,
+        lineNumber,
+      };
+      currentContainer().push(note);
+      continue;
+    }
+
+    // Parse multi-line note — "note" or "note right of API" (no colon, body indented below)
+    const noteMultiMatch = trimmed.match(NOTE_MULTI);
+    if (noteMultiMatch) {
+      const notePosition =
+        (noteMultiMatch[1]?.toLowerCase() as 'right' | 'left') || 'right';
+      let noteParticipant = noteMultiMatch[2] || null;
+      if (!noteParticipant) {
+        if (!lastMsgFrom) {
+          result.error = `Line ${lineNumber}: note requires a preceding message`;
+          return result;
+        }
+        noteParticipant = lastMsgFrom;
+      }
+      if (!result.participants.some((p) => p.id === noteParticipant)) {
+        result.error = `Line ${lineNumber}: note references unknown participant '${noteParticipant}'`;
+        return result;
+      }
+      // Collect indented body lines
+      const noteLines: string[] = [];
+      while (i + 1 < lines.length) {
+        const nextRaw = lines[i + 1];
+        const nextTrimmed = nextRaw.trim();
+        if (!nextTrimmed) break;
+        const nextIndent = measureIndent(nextRaw);
+        if (nextIndent <= indent) break;
+        noteLines.push(nextTrimmed);
+        i++;
+      }
+      if (noteLines.length === 0) {
+        result.error = `Line ${lineNumber}: multi-line note has no content — add indented lines or use 'note: text'`;
+        return result;
+      }
+      const note: SequenceNote = {
+        kind: 'note',
+        text: noteLines.join('\n'),
+        position: notePosition,
+        participantId: noteParticipant,
+        lineNumber,
+      };
+      currentContainer().push(note);
       continue;
     }
   }
@@ -543,7 +735,7 @@ export function looksLikeSequence(content: string): boolean {
   const lines = content.split('\n');
   return lines.some((line) => {
     const trimmed = line.trim();
-    if (trimmed.startsWith('#') || trimmed.startsWith('//')) return false;
+    if (trimmed.startsWith('//')) return false;
     return ARROW_PATTERN.test(trimmed);
   });
 }