@diagrammo/dgmo 0.4.1 → 0.4.3

package/src/infra/roles.ts

@@ -0,0 +1,60 @@
+// ============================================================
+// Infra Chart Role Inference
+// ============================================================
+//
+// Infers component roles from declared behavior properties.
+// Each role maps to a specific color for badge rendering.
+
+import type { InfraProperty } from './types';
+
+export interface InfraRole {
+  name: string;
+  color: string; // hex color for badge
+}
+
+/** All recognized roles with their trigger keys. */
+const ROLE_RULES: { keys: string[]; role: InfraRole }[] = [
+  { keys: ['cache-hit'], role: { name: 'Cache', color: '#22c55e' } },
+  { keys: ['firewall-block'], role: { name: 'Firewall', color: '#ef4444' } },
+  { keys: ['ratelimit-rps'], role: { name: 'Rate Limiter', color: '#eab308' } },
+  { keys: ['max-rps'], role: { name: 'Service', color: '#3b82f6' } },
+  { keys: ['cb-error-threshold', 'cb-latency-threshold-ms'], role: { name: 'Circuit Breaker', color: '#a855f7' } },
+  { keys: ['concurrency'], role: { name: 'Serverless', color: '#06b6d4' } },
+  { keys: ['buffer'], role: { name: 'Queue', color: '#8b5cf6' } },
+];
+
+/**
+ * Infer roles from a component's properties.
+ * A component can have multiple roles (e.g., Cache + Rate Limiter).
+ */
+export function inferRoles(properties: InfraProperty[]): InfraRole[] {
+  const propKeys = new Set(properties.map((p) => p.key));
+  const roles: InfraRole[] = [];
+
+  for (const rule of ROLE_RULES) {
+    if (rule.keys.some((k) => propKeys.has(k))) {
+      roles.push(rule.role);
+    }
+  }
+
+  return roles;
+}
+
+/**
+ * Collect all unique roles present in the diagram (for legend).
+ */
+export function collectDiagramRoles(allProperties: InfraProperty[][]): InfraRole[] {
+  const seen = new Set<string>();
+  const roles: InfraRole[] = [];
+
+  for (const props of allProperties) {
+    for (const role of inferRoles(props)) {
+      if (!seen.has(role.name)) {
+        seen.add(role.name);
+        roles.push(role);
+      }
+    }
+  }
+
+  return roles;
+}

package/src/infra/serialize.ts

@@ -0,0 +1,67 @@
+// ============================================================
+// Infra Scenario Serializer
+// ============================================================
+//
+// Converts interactive overrides into a `scenario:` DSL block.
+// Only includes properties that differ from the base diagram.
+
+import type { ParsedInfra, InfraComputeParams } from './types';
+
+/**
+ * Serialize interactive overrides as a DSL `scenario:` block.
+ * Returns an empty string if nothing differs from the base diagram.
+ */
+export function serializeScenario(name: string, parsed: ParsedInfra, overrides: InfraComputeParams): string {
+  const lines: string[] = [];
+
+  // Edge RPS override
+  const edgeNode = parsed.nodes.find((n) => n.isEdge);
+  if (edgeNode && overrides.rps != null) {
+    const baseRps = edgeNode.properties.find((p) => p.key === 'rps');
+    const baseVal = baseRps ? (typeof baseRps.value === 'number' ? baseRps.value : parseFloat(String(baseRps.value)) || 0) : 0;
+    if (overrides.rps !== baseVal) {
+      lines.push(`  ${edgeNode.id}`);
+      lines.push(`    rps: ${overrides.rps}`);
+    }
+  }
+
+  // Instance overrides and property overrides per node
+  const instanceOv = overrides.instanceOverrides ?? {};
+  const propOv = overrides.propertyOverrides ?? {};
+
+  for (const node of parsed.nodes) {
+    if (node.isEdge) continue;
+
+    const nodeLines: string[] = [];
+
+    // Instance override
+    if (instanceOv[node.id] != null) {
+      const baseProp = node.properties.find((p) => p.key === 'instances');
+      const baseVal = baseProp ? (typeof baseProp.value === 'number' ? baseProp.value : parseFloat(String(baseProp.value)) || 1) : 1;
+      if (instanceOv[node.id] !== baseVal) {
+        nodeLines.push(`    instances: ${instanceOv[node.id]}`);
+      }
+    }
+
+    // Property overrides
+    const nodePropOv = propOv[node.id];
+    if (nodePropOv) {
+      for (const [key, val] of Object.entries(nodePropOv)) {
+        const baseProp = node.properties.find((p) => p.key === key);
+        const baseVal = baseProp ? (typeof baseProp.value === 'number' ? baseProp.value : parseFloat(String(baseProp.value)) || 0) : 0;
+        if (val !== baseVal) {
+          nodeLines.push(`    ${key}: ${val}`);
+        }
+      }
+    }
+
+    if (nodeLines.length > 0) {
+      lines.push(`  ${node.id}`);
+      lines.push(...nodeLines);
+    }
+  }
+
+  if (lines.length === 0) return '';
+
+  return `scenario: ${name}\n${lines.join('\n')}\n`;
+}

package/src/infra/types.ts

@@ -0,0 +1,221 @@
+// ============================================================
+// Infra Chart Types
+// ============================================================
+
+import type { DgmoError } from '../diagnostics';
+
+/** Namespaced behavior property keys recognized by the parser. */
+export type InfraBehaviorKey =
+  | 'cache-hit'
+  | 'firewall-block'
+  | 'ratelimit-rps'
+  | 'latency-ms'
+  | 'uptime'
+  | 'instances'
+  | 'max-rps'
+  | 'cb-error-threshold'
+  | 'cb-latency-threshold-ms'
+  | 'concurrency'
+  | 'duration-ms'
+  | 'cold-start-ms'
+  | 'buffer'
+  | 'drain-rate'
+  | 'retention-hours'
+  | 'partitions';
+
+/** All recognized property keys (behavior + structural). */
+export const INFRA_BEHAVIOR_KEYS = new Set<string>([
+  'cache-hit',
+  'firewall-block',
+  'ratelimit-rps',
+  'latency-ms',
+  'uptime',
+  'instances',
+  'max-rps',
+  'cb-error-threshold',
+  'cb-latency-threshold-ms',
+  'concurrency',
+  'duration-ms',
+  'cold-start-ms',
+  'buffer',
+  'drain-rate',
+  'retention-hours',
+  'partitions',
+]);
+
+/** The `rps` key is only valid on the `edge` component. */
+export const EDGE_ONLY_KEYS = new Set<string>(['rps']);
+
+export interface InfraProperty {
+  key: string;
+  value: string | number;
+  lineNumber: number;
+}
+
+export interface InfraNode {
+  id: string;
+  label: string;
+  properties: InfraProperty[];
+  groupId: string | null;
+  tags: Record<string, string>; // tagGroup -> tagValue
+  isEdge: boolean; // true for the `edge` entry-point component
+  lineNumber: number;
+}
+
+export interface InfraEdge {
+  sourceId: string;
+  targetId: string;
+  label: string;
+  split: number | null; // percentage 0-100, or null if not declared
+  lineNumber: number;
+}
+
+export interface InfraGroup {
+  id: string;
+  label: string;
+  /** Number of instances (or auto-scaling range "N-M") of this group as a unit. */
+  instances?: number | string;
+  /** Whether this group should be collapsed by default in the source. */
+  collapsed?: boolean;
+  lineNumber: number;
+}
+
+export interface InfraTagValue {
+  name: string;
+  color?: string;
+}
+
+export interface InfraTagGroup {
+  name: string;
+  alias: string | null;
+  values: InfraTagValue[];
+  /** Value of the entry marked `default` (nodes without this tag get it automatically). */
+  defaultValue?: string;
+  lineNumber: number;
+}
+
+export interface InfraScenario {
+  name: string;
+  /** Node property overrides: nodeId -> { key: value } */
+  overrides: Record<string, Record<string, string | number>>;
+  lineNumber: number;
+}
+
+export interface ParsedInfra {
+  type: 'infra';
+  title: string | null;
+  titleLineNumber: number | null;
+  direction: 'LR' | 'TB';
+  nodes: InfraNode[];
+  edges: InfraEdge[];
+  groups: InfraGroup[];
+  tagGroups: InfraTagGroup[];
+  scenarios: InfraScenario[];
+  options: Record<string, string>;
+  diagnostics: DgmoError[];
+  error: string | null;
+}
+
+// ============================================================
+// Computed Model Types
+// ============================================================
+
+export interface InfraComputeParams {
+  rps?: number; // override edge rps (for slider)
+  instanceOverrides?: Record<string, number>; // nodeId -> instance count override
+  scenario?: InfraScenario | null; // apply a named scenario's overrides
+  /** Per-node property overrides: nodeId -> { propertyKey: numericValue }.
+   *  Applied after scenario overrides. Lets sliders adjust cache-hit, etc. */
+  propertyOverrides?: Record<string, Record<string, number>>;
+  /** Set of group IDs that should be treated as collapsed (virtual nodes). */
+  collapsedGroups?: Set<string>;
+}
+
+export type InfraCbState = 'closed' | 'open' | 'half-open';
+
+export interface ComputedInfraNode {
+  id: string;
+  label: string;
+  groupId: string | null;
+  isEdge: boolean;
+  computedRps: number;
+  overloaded: boolean;
+  /** True when inbound RPS exceeds the node's ratelimit-rps and traffic is being shed. */
+  rateLimited: boolean;
+  /** Cumulative latency from edge to this node (ms). */
+  computedLatencyMs: number;
+  /** Latency percentiles from this node through all downstream paths (ms). */
+  computedLatencyPercentiles: InfraLatencyPercentiles;
+  /** Component uptime (product of uptimes along path, 0-1). */
+  computedUptime: number;
+  /** Local availability at this node (0-1), factoring in uptime, overload shed, and rate-limit reject. */
+  computedAvailability: number;
+  /** Availability percentiles through all downstream paths from this node (0-1 fractions). */
+  computedAvailabilityPercentiles: InfraAvailabilityPercentiles;
+  /** Circuit breaker state. */
+  computedCbState: InfraCbState;
+  /** Computed instance count for auto-scaling (min-max) ranges. */
+  computedInstances: number;
+  /** For serverless nodes: estimated concurrent invocations (Little's Law: RPS × duration_ms / 1000). */
+  computedConcurrentInvocations: number;
+  /** For collapsed group virtual nodes: worst health state of any child.
+   *  'overloaded' > 'warning' > 'normal'. Undefined for regular nodes. */
+  childHealthState?: 'normal' | 'warning' | 'overloaded';
+  /** Queue metrics — only present when buffer property exists. */
+  queueMetrics?: {
+    /** Messages per second filling the buffer (inbound - drain-rate, clamped to 0). */
+    fillRate: number;
+    /** Seconds until buffer overflow at sustained fill rate. Infinity if not filling. */
+    timeToOverflow: number;
+    /** Queue wait time in ms (pending_messages / drain_rate * 1000). */
+    waitTimeMs: number;
+  };
+  properties: InfraProperty[];
+  tags: Record<string, string>;
+  lineNumber: number;
+}
+
+export interface ComputedInfraEdge {
+  sourceId: string;
+  targetId: string;
+  label: string;
+  computedRps: number;
+  split: number; // resolved split (always 0-100)
+  lineNumber: number;
+}
+
+export interface InfraDiagnostic {
+  type: 'SPLIT_SUM' | 'CYCLE' | 'OVERLOAD' | 'RATE_LIMITED' | 'ORPHAN' | 'SYNTAX' | 'UPTIME';
+  line: number;
+  message: string;
+}
+
+export interface InfraLatencyPercentiles {
+  p50: number;
+  p90: number;
+  p99: number;
+}
+
+export interface InfraAvailabilityPercentiles {
+  p50: number;
+  p90: number;
+  p99: number;
+}
+
+export interface ComputedInfraModel {
+  nodes: ComputedInfraNode[];
+  edges: ComputedInfraEdge[];
+  groups: InfraGroup[];
+  tagGroups: InfraTagGroup[];
+  title: string | null;
+  direction: 'LR' | 'TB';
+  /** Diagram-level options (e.g., default-latency-ms, default-uptime). */
+  options: Record<string, string>;
+  /** Latency percentiles at the edge entry point (weighted by traffic probability). */
+  edgeLatency: InfraLatencyPercentiles;
+  /** System uptime at edge (weighted average across all paths). */
+  systemUptime: number;
+  /** System availability at edge (weighted average of compound availability across all paths). */
+  systemAvailability: number;
+  diagnostics: InfraDiagnostic[];
+}

package/src/infra/validation.ts

@@ -0,0 +1,192 @@
+// ============================================================
+// Infra Chart Validation
+// ============================================================
+//
+// Validates structural correctness of the parsed infra model:
+// - Split sums (FR19)
+// - DAG validation — no cycles (FR20)
+// - Orphan detection
+
+import type { ParsedInfra, InfraDiagnostic, ComputedInfraModel } from './types';
+
+// ============================================================
+// Cycle Detection
+// ============================================================
+
+function detectCycles(parsed: ParsedInfra): InfraDiagnostic[] {
+  const diagnostics: InfraDiagnostic[] = [];
+
+  // Build adjacency list
+  const adj = new Map<string, string[]>();
+  const edgeLines = new Map<string, number>(); // edge key -> lineNumber
+  for (const edge of parsed.edges) {
+    const list = adj.get(edge.sourceId) ?? [];
+    list.push(edge.targetId);
+    adj.set(edge.sourceId, list);
+    edgeLines.set(`${edge.sourceId}->${edge.targetId}`, edge.lineNumber);
+  }
+
+  // DFS with coloring: 0=white, 1=grey, 2=black
+  const color = new Map<string, number>();
+  const parent = new Map<string, string | null>();
+
+  function dfs(nodeId: string): boolean {
+    color.set(nodeId, 1); // grey
+    const neighbors = adj.get(nodeId) ?? [];
+    for (const next of neighbors) {
+      const c = color.get(next) ?? 0;
+      if (c === 1) {
+        // Back edge — cycle found
+        const lineKey = `${nodeId}->${next}`;
+        diagnostics.push({
+          type: 'CYCLE',
+          line: edgeLines.get(lineKey) ?? 0,
+          message: `Cycle detected: ${nodeId} -> ${next} creates a circular reference.`,
+        });
+        return true;
+      }
+      if (c === 0) {
+        parent.set(next, nodeId);
+        if (dfs(next)) return true;
+      }
+    }
+    color.set(nodeId, 2); // black
+    return false;
+  }
+
+  for (const node of parsed.nodes) {
+    if ((color.get(node.id) ?? 0) === 0) {
+      dfs(node.id);
+    }
+  }
+
+  return diagnostics;
+}
+
+// ============================================================
+// Split Validation
+// ============================================================
+
+function validateSplits(parsed: ParsedInfra): InfraDiagnostic[] {
+  const diagnostics: InfraDiagnostic[] = [];
+
+  // Group edges by source
+  const outbound = new Map<string, typeof parsed.edges>();
+  for (const edge of parsed.edges) {
+    const list = outbound.get(edge.sourceId) ?? [];
+    list.push(edge);
+    outbound.set(edge.sourceId, list);
+  }
+
+  for (const [sourceId, edges] of outbound) {
+    if (edges.length <= 1) continue;
+
+    const declared = edges.filter((e) => e.split !== null);
+    if (declared.length === edges.length) {
+      // All declared — validate sum
+      const sum = declared.reduce((s, e) => s + (e.split ?? 0), 0);
+      if (Math.abs(sum - 100) > 0.01) {
+        diagnostics.push({
+          type: 'SPLIT_SUM',
+          line: declared[0].lineNumber,
+          message: `Splits from '${sourceId}' sum to ${sum}%, expected 100%.`,
+        });
+      }
+    } else if (declared.length > 0) {
+      // Some declared — validate declared sum doesn't exceed 100
+      const declaredSum = declared.reduce((s, e) => s + (e.split ?? 0), 0);
+      if (declaredSum > 100) {
+        diagnostics.push({
+          type: 'SPLIT_SUM',
+          line: declared[0].lineNumber,
+          message: `Declared splits from '${sourceId}' sum to ${declaredSum}%, exceeding 100%.`,
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+// ============================================================
+// Orphan Detection
+// ============================================================
+
+function detectOrphans(parsed: ParsedInfra): InfraDiagnostic[] {
+  const diagnostics: InfraDiagnostic[] = [];
+
+  // Nodes reachable from edge
+  const edgeNode = parsed.nodes.find((n) => n.isEdge);
+  if (!edgeNode) return diagnostics;
+
+  const reachable = new Set<string>();
+  const adj = new Map<string, string[]>();
+  for (const edge of parsed.edges) {
+    const list = adj.get(edge.sourceId) ?? [];
+    list.push(edge.targetId);
+    adj.set(edge.sourceId, list);
+  }
+
+  const queue = [edgeNode.id];
+  while (queue.length > 0) {
+    const id = queue.shift()!;
+    if (reachable.has(id)) continue;
+    reachable.add(id);
+    for (const next of adj.get(id) ?? []) {
+      queue.push(next);
+    }
+  }
+
+  // Also mark group children as reachable if their group is reachable
+  for (const group of parsed.groups) {
+    if (reachable.has(group.id)) {
+      for (const node of parsed.nodes) {
+        if (node.groupId === group.id) reachable.add(node.id);
+      }
+    }
+  }
+
+  for (const node of parsed.nodes) {
+    if (!node.isEdge && !reachable.has(node.id)) {
+      diagnostics.push({
+        type: 'ORPHAN',
+        line: node.lineNumber,
+        message: `Component '${node.label}' is not reachable from the edge entry point.`,
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+// ============================================================
+// Main Validation
+// ============================================================
+
+export function validateInfra(parsed: ParsedInfra): InfraDiagnostic[] {
+  return [
+    ...detectCycles(parsed),
+    ...validateSplits(parsed),
+    ...detectOrphans(parsed),
+  ];
+}
+
+/**
+ * Validate computed model (post-computation warnings).
+ * Call after computeInfra() to get uptime/SLA warnings.
+ */
+export function validateComputed(computed: ComputedInfraModel): InfraDiagnostic[] {
+  const diagnostics: InfraDiagnostic[] = [];
+
+  // Uptime warning: if system uptime is below 99%
+  if (computed.systemUptime > 0 && computed.systemUptime < 0.99) {
+    const pct = (computed.systemUptime * 100).toFixed(2);
+    diagnostics.push({
+      type: 'UPTIME',
+      line: 1,
+      message: `System uptime is ${pct}%, below 99% SLA threshold.`,
+    });
+  }
+
+  return diagnostics;
+}