@diagrammo/dgmo 0.47.0 → 0.48.0

package/src/infra/roles.ts

@@ -1,75 +0,0 @@
-// ============================================================
-// 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';
-import type { InfraLayoutEdge } from './layout';
-
-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;
-}
-
-/** The Fan-Out role, assigned to nodes with at least one outgoing fanout edge. */
-export const FANOUT_ROLE: InfraRole = { name: 'Fan-Out', color: '#f97316' };
-
-/**
- * Return the set of sourceIds that have at least one outgoing edge with fanout.
- */
-export function collectFanoutSourceIds(edges: InfraLayoutEdge[]): Set<string> {
-  const ids = new Set<string>();
-  for (const e of edges) {
-    if (e.fanout != null) ids.add(e.sourceId);
-  }
-  return ids;
-}
-
-/**
- * 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/types.ts

@@ -1,216 +0,0 @@
-// ============================================================
-// Infra Chart Types
-// ============================================================
-
-import type { DgmoError } from '../diagnostics';
-import {
-  INFRA_BEHAVIOR_KEY_SET,
-  INFRA_EDGE_ONLY_KEY_SET,
-} from '../directives-registry';
-
-/** 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). Derived from the
- * single-source directives registry — do NOT re-list literals here.
- */
-export const INFRA_BEHAVIOR_KEYS: ReadonlySet<string> = INFRA_BEHAVIOR_KEY_SET;
-
-/** The `rps` key is only valid on the `edge` component. */
-export const EDGE_ONLY_KEYS: ReadonlySet<string> = INFRA_EDGE_ONLY_KEY_SET;
-
-export interface InfraProperty {
-  readonly key: string;
-  readonly value: string | number;
-  readonly lineNumber: number;
-}
-
-export interface InfraNode {
-  readonly id: string;
-  readonly label: string;
-  readonly properties: readonly InfraProperty[];
-  readonly groupId: string | null;
-  readonly tags: Readonly<Record<string, string>>; // tagGroup -> tagValue
-  readonly isEdge: boolean; // true for the `edge` entry-point component
-  readonly description?: readonly string[];
-  readonly lineNumber: number;
-}
-
-export interface InfraEdge {
-  readonly sourceId: string;
-  readonly targetId: string;
-  readonly label: string;
-  readonly async: boolean;
-  readonly split: number | null; // percentage 0-100, or null if not declared
-  readonly fanout: number | null; // request multiplier: target receives inbound * (split/100) * fanout RPS
-  readonly lineNumber: number;
-}
-
-export interface InfraGroup {
-  readonly id: string;
-  readonly label: string;
-  /** Number of instances (or auto-scaling range "N-M") of this group as a unit. */
-  readonly instances?: number | string;
-  /** Whether this group should be collapsed by default in the source. */
-  readonly collapsed?: boolean;
-  /** Pipe metadata on the group header, cascaded to children. */
-  readonly metadata?: Readonly<Record<string, string>>;
-  readonly lineNumber: number;
-}
-
-export interface InfraTagValue {
-  readonly name: string;
-  readonly color?: string;
-}
-
-export interface InfraTagGroup {
-  readonly name: string;
-  readonly alias: string | null;
-  readonly values: readonly InfraTagValue[];
-  /** Value of the entry marked `default` (nodes without this tag get it automatically). */
-  readonly defaultValue?: string;
-  readonly lineNumber: number;
-}
-
-export interface ParsedInfra {
-  readonly type: 'infra';
-  readonly title: string | null;
-  readonly titleLineNumber: number | null;
-  readonly direction: 'LR' | 'TB';
-  readonly nodes: readonly InfraNode[];
-  readonly edges: readonly InfraEdge[];
-  readonly groups: readonly InfraGroup[];
-  readonly tagGroups: readonly InfraTagGroup[];
-  readonly options: Readonly<Record<string, string>>;
-  readonly diagnostics: readonly DgmoError[];
-  readonly error: string | null;
-}
-
-// ============================================================
-// Computed Model Types
-// ============================================================
-
-export interface InfraComputeParams {
-  rps?: number; // override edge rps (for slider)
-  instanceOverrides?: Record<string, number>; // nodeId -> instance count override
-  /** Per-node property overrides: nodeId -> { propertyKey: numericValue }. */
-  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>;
-  description?: string[];
-  lineNumber: number;
-}
-
-export interface ComputedInfraEdge {
-  sourceId: string;
-  targetId: string;
-  label: string;
-  async: boolean;
-  computedRps: number;
-  split: number; // resolved split (always 0-100)
-  fanout: number | null;
-  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

@@ -1,201 +0,0 @@
-// ============================================================
-// 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,
-  InfraEdge,
-} 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, InfraEdge[]>();
-  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',
-          // In-bounds: declared.length === edges.length > 1 here.
-          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',
-          // In-bounds: declared.length > 0 here.
-          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;
-}