@diagrammo/dgmo 0.8.22 → 0.8.25

package/dist/internal.d.cts

@@ -0,0 +1,267 @@
+type DgmoSeverity = 'error' | 'warning';
+interface DgmoError {
+    line: number;
+    column?: number;
+    message: string;
+    severity: DgmoSeverity;
+    /**
+     * Optional stable diagnostic code (e.g. 'E_ARROW_SUBSTRING_IN_LABEL').
+     * Additive; pre-existing diagnostics omit this field and existing
+     * substring-on-`.message` assertions keep working unchanged.
+     */
+    code?: string;
+}
+
+/**
+ * Parse a data row line: everything before the last numeric token(s) is the label,
+ * numeric tokens at the end are the values. Supports comma-separated multi-values,
+ * space-separated multi-values, and comma-grouped numbers (e.g., "1,087").
+ *
+ * Examples:
+ *   "Jan 120"             → { label: "Jan", values: [120] }
+ *   "North America 250"   → { label: "North America", values: [250] }
+ *   "Q1 10, 20, 30"       → { label: "Q1", values: [10, 20, 30] }
+ *   "Q1 10 20 30"         → { label: "Q1", values: [10, 20, 30] }
+ *   "Revenue 1,200"       → { label: "Revenue", values: [1200] }
+ *   "Revenue 3,984,078.65"→ { label: "Revenue", values: [3984078.65] }
+ *
+ * Returns null if the line has no numeric value at the end.
+ */
+declare function parseDataRowValues(line: string, options?: {
+    multiValue?: boolean;
+    expectedValues?: number;
+}): {
+    label: string;
+    values: number[];
+} | null;
+
+/** A single entry inside a tag group: `Value(color)` */
+interface TagEntry {
+    value: string;
+    color: string;
+    lineNumber: number;
+}
+/** A tag group block: heading + entries */
+interface TagGroup {
+    name: string;
+    alias?: string;
+    entries: TagEntry[];
+    /** Default value for nodes without explicit metadata. First entry unless another is marked `default`. */
+    defaultValue?: string;
+    lineNumber: number;
+}
+
+/** @deprecated Use `TagGroup` from `utils/tag-groups` */
+type KanbanTagGroup = TagGroup;
+interface KanbanCard {
+    id: string;
+    title: string;
+    tags: Record<string, string>;
+    details: string[];
+    lineNumber: number;
+    endLineNumber: number;
+    color?: string;
+}
+interface KanbanColumn {
+    id: string;
+    name: string;
+    wipLimit?: number;
+    color?: string;
+    metadata?: Record<string, string>;
+    cards: KanbanCard[];
+    lineNumber: number;
+}
+interface ParsedKanban {
+    type: 'kanban';
+    title?: string;
+    titleLineNumber?: number;
+    columns: KanbanColumn[];
+    tagGroups: KanbanTagGroup[];
+    options: Record<string, string>;
+    diagnostics: DgmoError[];
+    error: string | null;
+}
+
+/**
+ * Compute new file content after moving a card to a different position.
+ *
+ * @param content     - original file content string
+ * @param parsed      - parsed kanban board
+ * @param cardId      - id of the card to move
+ * @param targetColumnId - id of the destination column
+ * @param targetIndex - position within target column (0 = first card)
+ * @returns new content string, or null if move is invalid
+ */
+declare function computeCardMove(content: string, parsed: ParsedKanban, cardId: string, targetColumnId: string, targetIndex: number): string | null;
+/**
+ * Move a card to the Archive section at the end of the file.
+ * Creates `== Archive ==` if it doesn't exist.
+ *
+ * @returns new content string, or null if the card is not found
+ */
+declare function computeCardArchive(content: string, parsed: ParsedKanban, cardId: string): string | null;
+/** Check if a column name is the archive column (case-insensitive). */
+declare function isArchiveColumn(name: string): boolean;
+
+/**
+ * Participant types that can be declared via "Name is a type" syntax.
+ */
+type ParticipantType = 'default' | 'service' | 'database' | 'actor' | 'queue' | 'cache' | 'gateway' | 'external' | 'networking' | 'frontend';
+/**
+ * A declared or inferred participant in the sequence diagram.
+ */
+interface SequenceParticipant {
+    /** Internal identifier (e.g. "AuthService") */
+    id: string;
+    /** Display label — uses aka alias if provided, otherwise id */
+    label: string;
+    /** Participant shape type */
+    type: ParticipantType;
+    /** Source line number (1-based) */
+    lineNumber: number;
+    /** Explicit layout position override (0-based from left, negative from right) */
+    position?: number;
+    /** Pipe-delimited tag metadata (e.g. `| role: Gateway`) */
+    metadata?: Record<string, string>;
+}
+/**
+ * A message between two participants.
+ */
+interface SequenceMessage {
+    from: string;
+    to: string;
+    label: string;
+    lineNumber: number;
+    async?: boolean;
+    /** Pipe-delimited tag metadata (e.g. `| c: Caching`) */
+    metadata?: Record<string, string>;
+}
+/**
+ * A conditional or loop block in the sequence diagram.
+ */
+interface ElseIfBranch {
+    label: string;
+    children: SequenceElement[];
+    lineNumber: number;
+}
+interface SequenceBlock {
+    kind: 'block';
+    type: 'if' | 'loop' | 'parallel';
+    label: string;
+    children: SequenceElement[];
+    elseChildren: SequenceElement[];
+    elseIfBranches?: ElseIfBranch[];
+    elseLineNumber?: number;
+    lineNumber: number;
+}
+/**
+ * A labeled horizontal divider between message phases.
+ */
+interface SequenceSection {
+    kind: 'section';
+    label: string;
+    lineNumber: number;
+}
+/**
+ * An annotation attached to a message, rendered as a folded-corner box.
+ */
+interface SequenceNote {
+    kind: 'note';
+    text: string;
+    position: 'right' | 'left';
+    participantId: string;
+    lineNumber: number;
+    endLineNumber: number;
+}
+type SequenceElement = SequenceMessage | SequenceBlock | SequenceSection | SequenceNote;
+/**
+ * A named group of participants rendered as a labeled box.
+ */
+interface SequenceGroup {
+    name: string;
+    participantIds: string[];
+    lineNumber: number;
+    /** Pipe-delimited tag metadata (e.g. `[Backend | t: Product]`) */
+    metadata?: Record<string, string>;
+    /** Whether this group is collapsed by default */
+    collapsed?: boolean;
+}
+
+interface SectionMessageGroup {
+    section: SequenceSection;
+    messageIndices: number[];
+}
+/**
+ * Group messages by the top-level section that precedes them.
+ * Messages before the first section are ungrouped (always visible).
+ * Only top-level sections are collapsible — sections inside blocks are excluded.
+ */
+declare function groupMessagesBySection(elements: SequenceElement[], messages: SequenceMessage[]): SectionMessageGroup[];
+interface RenderStep {
+    type: 'call' | 'return';
+    from: string;
+    to: string;
+    label: string;
+    messageIndex: number;
+    async?: boolean;
+}
+/**
+ * Build an ordered render sequence from flat messages.
+ * Uses a call stack to infer where returns should be placed:
+ * returns appear after all nested sub-calls complete.
+ */
+declare function buildRenderSequence(messages: SequenceMessage[]): RenderStep[];
+interface Activation {
+    participantId: string;
+    startStep: number;
+    endStep: number;
+    depth: number;
+}
+/**
+ * Compute activation rectangles from render steps.
+ * Each call pushes onto the callee's stack; each return pops it.
+ */
+declare function computeActivations(steps: RenderStep[]): Activation[];
+/**
+ * Reorder participants based on explicit `position` overrides.
+ * Positive positions are 0-based from the left; negative positions count from the right (-1 = last).
+ * Unpositioned participants maintain their relative order, filling remaining slots.
+ */
+declare function applyPositionOverrides(participants: SequenceParticipant[]): SequenceParticipant[];
+/**
+ * Reorder participants so that members of the same group are adjacent.
+ * Groups are positioned at the point where their first member would naturally
+ * appear based on message order (first-occurrence positioning). This prevents
+ * groups declared at the top of the file from being placed before participants
+ * that appear in messages earlier.
+ *
+ * Explicit `position` overrides are handled separately by `applyPositionOverrides`.
+ */
+declare function applyGroupOrdering(participants: SequenceParticipant[], groups: SequenceGroup[], messages?: SequenceMessage[]): SequenceParticipant[];
+/**
+ * Build a mapping from each note's lineNumber to the lineNumber of its
+ * associated message (the last message before the note in document order).
+ * Used by the app to highlight the associated message when cursor is on a note.
+ */
+declare function buildNoteMessageMap(elements: SequenceElement[]): Map<number, number>;
+
+interface ArcLink {
+    source: string;
+    target: string;
+    value: number;
+    color: string | null;
+    lineNumber: number;
+}
+type ArcOrder = 'appearance' | 'name' | 'group' | 'degree';
+interface ArcNodeGroup {
+    name: string;
+    nodes: string[];
+    color: string | null;
+    lineNumber: number;
+}
+/**
+ * Orders arc diagram nodes based on the selected ordering strategy.
+ */
+declare function orderArcNodes(links: ArcLink[], order: ArcOrder, groups: ArcNodeGroup[]): string[];
+
+export { applyGroupOrdering, applyPositionOverrides, buildNoteMessageMap, buildRenderSequence, computeActivations, computeCardArchive, computeCardMove, groupMessagesBySection, isArchiveColumn, orderArcNodes, parseDataRowValues };

package/dist/internal.d.ts

@@ -0,0 +1,267 @@
+type DgmoSeverity = 'error' | 'warning';
+interface DgmoError {
+    line: number;
+    column?: number;
+    message: string;
+    severity: DgmoSeverity;
+    /**
+     * Optional stable diagnostic code (e.g. 'E_ARROW_SUBSTRING_IN_LABEL').
+     * Additive; pre-existing diagnostics omit this field and existing
+     * substring-on-`.message` assertions keep working unchanged.
+     */
+    code?: string;
+}
+
+/**
+ * Parse a data row line: everything before the last numeric token(s) is the label,
+ * numeric tokens at the end are the values. Supports comma-separated multi-values,
+ * space-separated multi-values, and comma-grouped numbers (e.g., "1,087").
+ *
+ * Examples:
+ *   "Jan 120"             → { label: "Jan", values: [120] }
+ *   "North America 250"   → { label: "North America", values: [250] }
+ *   "Q1 10, 20, 30"       → { label: "Q1", values: [10, 20, 30] }
+ *   "Q1 10 20 30"         → { label: "Q1", values: [10, 20, 30] }
+ *   "Revenue 1,200"       → { label: "Revenue", values: [1200] }
+ *   "Revenue 3,984,078.65"→ { label: "Revenue", values: [3984078.65] }
+ *
+ * Returns null if the line has no numeric value at the end.
+ */
+declare function parseDataRowValues(line: string, options?: {
+    multiValue?: boolean;
+    expectedValues?: number;
+}): {
+    label: string;
+    values: number[];
+} | null;
+
+/** A single entry inside a tag group: `Value(color)` */
+interface TagEntry {
+    value: string;
+    color: string;
+    lineNumber: number;
+}
+/** A tag group block: heading + entries */
+interface TagGroup {
+    name: string;
+    alias?: string;
+    entries: TagEntry[];
+    /** Default value for nodes without explicit metadata. First entry unless another is marked `default`. */
+    defaultValue?: string;
+    lineNumber: number;
+}
+
+/** @deprecated Use `TagGroup` from `utils/tag-groups` */
+type KanbanTagGroup = TagGroup;
+interface KanbanCard {
+    id: string;
+    title: string;
+    tags: Record<string, string>;
+    details: string[];
+    lineNumber: number;
+    endLineNumber: number;
+    color?: string;
+}
+interface KanbanColumn {
+    id: string;
+    name: string;
+    wipLimit?: number;
+    color?: string;
+    metadata?: Record<string, string>;
+    cards: KanbanCard[];
+    lineNumber: number;
+}
+interface ParsedKanban {
+    type: 'kanban';
+    title?: string;
+    titleLineNumber?: number;
+    columns: KanbanColumn[];
+    tagGroups: KanbanTagGroup[];
+    options: Record<string, string>;
+    diagnostics: DgmoError[];
+    error: string | null;
+}
+
+/**
+ * Compute new file content after moving a card to a different position.
+ *
+ * @param content     - original file content string
+ * @param parsed      - parsed kanban board
+ * @param cardId      - id of the card to move
+ * @param targetColumnId - id of the destination column
+ * @param targetIndex - position within target column (0 = first card)
+ * @returns new content string, or null if move is invalid
+ */
+declare function computeCardMove(content: string, parsed: ParsedKanban, cardId: string, targetColumnId: string, targetIndex: number): string | null;
+/**
+ * Move a card to the Archive section at the end of the file.
+ * Creates `== Archive ==` if it doesn't exist.
+ *
+ * @returns new content string, or null if the card is not found
+ */
+declare function computeCardArchive(content: string, parsed: ParsedKanban, cardId: string): string | null;
+/** Check if a column name is the archive column (case-insensitive). */
+declare function isArchiveColumn(name: string): boolean;
+
+/**
+ * Participant types that can be declared via "Name is a type" syntax.
+ */
+type ParticipantType = 'default' | 'service' | 'database' | 'actor' | 'queue' | 'cache' | 'gateway' | 'external' | 'networking' | 'frontend';
+/**
+ * A declared or inferred participant in the sequence diagram.
+ */
+interface SequenceParticipant {
+    /** Internal identifier (e.g. "AuthService") */
+    id: string;
+    /** Display label — uses aka alias if provided, otherwise id */
+    label: string;
+    /** Participant shape type */
+    type: ParticipantType;
+    /** Source line number (1-based) */
+    lineNumber: number;
+    /** Explicit layout position override (0-based from left, negative from right) */
+    position?: number;
+    /** Pipe-delimited tag metadata (e.g. `| role: Gateway`) */
+    metadata?: Record<string, string>;
+}
+/**
+ * A message between two participants.
+ */
+interface SequenceMessage {
+    from: string;
+    to: string;
+    label: string;
+    lineNumber: number;
+    async?: boolean;
+    /** Pipe-delimited tag metadata (e.g. `| c: Caching`) */
+    metadata?: Record<string, string>;
+}
+/**
+ * A conditional or loop block in the sequence diagram.
+ */
+interface ElseIfBranch {
+    label: string;
+    children: SequenceElement[];
+    lineNumber: number;
+}
+interface SequenceBlock {
+    kind: 'block';
+    type: 'if' | 'loop' | 'parallel';
+    label: string;
+    children: SequenceElement[];
+    elseChildren: SequenceElement[];
+    elseIfBranches?: ElseIfBranch[];
+    elseLineNumber?: number;
+    lineNumber: number;
+}
+/**
+ * A labeled horizontal divider between message phases.
+ */
+interface SequenceSection {
+    kind: 'section';
+    label: string;
+    lineNumber: number;
+}
+/**
+ * An annotation attached to a message, rendered as a folded-corner box.
+ */
+interface SequenceNote {
+    kind: 'note';
+    text: string;
+    position: 'right' | 'left';
+    participantId: string;
+    lineNumber: number;
+    endLineNumber: number;
+}
+type SequenceElement = SequenceMessage | SequenceBlock | SequenceSection | SequenceNote;
+/**
+ * A named group of participants rendered as a labeled box.
+ */
+interface SequenceGroup {
+    name: string;
+    participantIds: string[];
+    lineNumber: number;
+    /** Pipe-delimited tag metadata (e.g. `[Backend | t: Product]`) */
+    metadata?: Record<string, string>;
+    /** Whether this group is collapsed by default */
+    collapsed?: boolean;
+}
+
+interface SectionMessageGroup {
+    section: SequenceSection;
+    messageIndices: number[];
+}
+/**
+ * Group messages by the top-level section that precedes them.
+ * Messages before the first section are ungrouped (always visible).
+ * Only top-level sections are collapsible — sections inside blocks are excluded.
+ */
+declare function groupMessagesBySection(elements: SequenceElement[], messages: SequenceMessage[]): SectionMessageGroup[];
+interface RenderStep {
+    type: 'call' | 'return';
+    from: string;
+    to: string;
+    label: string;
+    messageIndex: number;
+    async?: boolean;
+}
+/**
+ * Build an ordered render sequence from flat messages.
+ * Uses a call stack to infer where returns should be placed:
+ * returns appear after all nested sub-calls complete.
+ */
+declare function buildRenderSequence(messages: SequenceMessage[]): RenderStep[];
+interface Activation {
+    participantId: string;
+    startStep: number;
+    endStep: number;
+    depth: number;
+}
+/**
+ * Compute activation rectangles from render steps.
+ * Each call pushes onto the callee's stack; each return pops it.
+ */
+declare function computeActivations(steps: RenderStep[]): Activation[];
+/**
+ * Reorder participants based on explicit `position` overrides.
+ * Positive positions are 0-based from the left; negative positions count from the right (-1 = last).
+ * Unpositioned participants maintain their relative order, filling remaining slots.
+ */
+declare function applyPositionOverrides(participants: SequenceParticipant[]): SequenceParticipant[];
+/**
+ * Reorder participants so that members of the same group are adjacent.
+ * Groups are positioned at the point where their first member would naturally
+ * appear based on message order (first-occurrence positioning). This prevents
+ * groups declared at the top of the file from being placed before participants
+ * that appear in messages earlier.
+ *
+ * Explicit `position` overrides are handled separately by `applyPositionOverrides`.
+ */
+declare function applyGroupOrdering(participants: SequenceParticipant[], groups: SequenceGroup[], messages?: SequenceMessage[]): SequenceParticipant[];
+/**
+ * Build a mapping from each note's lineNumber to the lineNumber of its
+ * associated message (the last message before the note in document order).
+ * Used by the app to highlight the associated message when cursor is on a note.
+ */
+declare function buildNoteMessageMap(elements: SequenceElement[]): Map<number, number>;
+
+interface ArcLink {
+    source: string;
+    target: string;
+    value: number;
+    color: string | null;
+    lineNumber: number;
+}
+type ArcOrder = 'appearance' | 'name' | 'group' | 'degree';
+interface ArcNodeGroup {
+    name: string;
+    nodes: string[];
+    color: string | null;
+    lineNumber: number;
+}
+/**
+ * Orders arc diagram nodes based on the selected ordering strategy.
+ */
+declare function orderArcNodes(links: ArcLink[], order: ArcOrder, groups: ArcNodeGroup[]): string[];
+
+export { applyGroupOrdering, applyPositionOverrides, buildNoteMessageMap, buildRenderSequence, computeActivations, computeCardArchive, computeCardMove, groupMessagesBySection, isArchiveColumn, orderArcNodes, parseDataRowValues };