@diagrammo/dgmo 0.8.21 → 0.8.23

package/src/tech-radar/layout.ts

@@ -0,0 +1,190 @@
+import type {
+  ParsedTechRadar,
+  TechRadarLayoutPoint,
+  QuadrantPosition,
+} from './types';
+
+/** Clockwise quadrant order matching global numbering. */
+const POSITION_ORDER: readonly QuadrantPosition[] = [
+  'top-left',
+  'top-right',
+  'bottom-right',
+  'bottom-left',
+];
+
+/**
+ * Maps quadrant position to its angular arc range (in radians).
+ * 0° = right (3 o'clock), counter-clockwise:
+ *   top-right    →  0° to  90° (π/2)
+ *   top-left     → 90° to 180° (π)
+ *   bottom-left  → 180° to 270° (3π/2)
+ *   bottom-right → 270° to 360° (2π)
+ */
+function getQuadrantArc(position: QuadrantPosition): {
+  startAngle: number;
+  endAngle: number;
+} {
+  switch (position) {
+    case 'top-right':
+      return { startAngle: 0, endAngle: Math.PI / 2 };
+    case 'top-left':
+      return { startAngle: Math.PI / 2, endAngle: Math.PI };
+    case 'bottom-left':
+      return { startAngle: Math.PI, endAngle: (3 * Math.PI) / 2 };
+    case 'bottom-right':
+      return { startAngle: (3 * Math.PI) / 2, endAngle: 2 * Math.PI };
+  }
+}
+
+/** Blip circle radius in pixels — scales down when slices are dense. */
+const BASE_BLIP_RADIUS = 12;
+const MIN_BLIP_RADIUS = 7;
+
+/**
+ * Compute deterministic, non-overlapping blip positions for a tech radar.
+ *
+ * Each blip is positioned within its ring+quadrant slice using polar coordinates,
+ * then converted to cartesian. The algorithm is:
+ * - Stable: changes in one slice don't affect other slices
+ * - Deterministic: same input always produces same output
+ * - Collision-avoiding: nudges overlapping blips radially within their ring band
+ */
+export function computeRadarLayout(
+  parsed: ParsedTechRadar,
+  width: number,
+  height: number
+): TechRadarLayoutPoint[] {
+  const points: TechRadarLayoutPoint[] = [];
+
+  if (parsed.rings.length === 0 || parsed.quadrants.length === 0) return points;
+
+  const cx = width / 2;
+  const cy = height / 2;
+  const maxRadius = Math.min(cx, cy) * 0.88; // leave margin for labels
+  const ringCount = parsed.rings.length;
+  const ringBandWidth = maxRadius / ringCount;
+  const ringOrder = parsed.rings.map((r) => r.name);
+
+  // Padding from ring/quadrant boundaries (fraction of band)
+  const radialPadding = ringBandWidth * 0.12;
+  const angularPadding = 0.05; // radians from quadrant dividers
+
+  for (const quadrant of parsed.quadrants) {
+    const quadrantIndex = POSITION_ORDER.indexOf(quadrant.position);
+    const { startAngle, endAngle } = getQuadrantArc(quadrant.position);
+    const usableArcStart = startAngle + angularPadding;
+    const usableArcEnd = endAngle - angularPadding;
+
+    // Group blips by ring
+    const blipsByRing = new Map<string, typeof quadrant.blips>();
+    for (const blip of quadrant.blips) {
+      const list = blipsByRing.get(blip.ring) ?? [];
+      list.push(blip);
+      blipsByRing.set(blip.ring, list);
+    }
+
+    const blipRadius = Math.max(
+      MIN_BLIP_RADIUS,
+      Math.min(BASE_BLIP_RADIUS, (ringBandWidth - 2 * radialPadding) / 3)
+    );
+
+    for (const [ringName, blips] of blipsByRing) {
+      const ringIndex = ringOrder.indexOf(ringName);
+      if (ringIndex < 0) continue;
+
+      const rInner = ringIndex * ringBandWidth + radialPadding;
+      const rOuter = (ringIndex + 1) * ringBandWidth - radialPadding;
+      const rMid = (rInner + rOuter) / 2;
+      const usableRadial = rOuter - rInner - blipRadius * 2;
+
+      // Distribute blips evenly across the arc
+      const arcSpan = usableArcEnd - usableArcStart;
+      const placedPoints: { angle: number; radius: number }[] = [];
+
+      for (let bi = 0; bi < blips.length; bi++) {
+        const blip = blips[bi];
+
+        // Spread across arc evenly
+        let angle: number;
+        if (blips.length === 1) {
+          angle = (usableArcStart + usableArcEnd) / 2;
+        } else {
+          angle = usableArcStart + ((bi + 0.5) / blips.length) * arcSpan;
+        }
+
+        // Stagger radially to avoid overlap in dense slices
+        let radius: number;
+        if (blips.length <= 3) {
+          radius = rMid;
+        } else {
+          // Alternate between inner and outer portions
+          const radialSlots = Math.min(3, Math.ceil(blips.length / 3));
+          const slot = bi % radialSlots;
+          radius =
+            rInner +
+            blipRadius +
+            (slot / Math.max(1, radialSlots - 1)) * usableRadial;
+        }
+
+        // Collision detection: nudge if overlapping with already-placed blips
+        let attempts = 0;
+        while (attempts < 20) {
+          const x = cx + radius * Math.cos(angle);
+          const y = cy - radius * Math.sin(angle); // SVG y is inverted
+          const overlapping = placedPoints.some((p) => {
+            const px = cx + p.radius * Math.cos(p.angle);
+            const py = cy - p.radius * Math.sin(p.angle);
+            const dx = x - px;
+            const dy = y - py;
+            return Math.sqrt(dx * dx + dy * dy) < blipRadius * 2.2;
+          });
+          if (!overlapping) break;
+          // Nudge: try different radial position within band
+          radius += blipRadius * 0.8;
+          if (radius > rOuter - blipRadius) {
+            radius = rInner + blipRadius;
+            angle += arcSpan * 0.05; // small angular shift
+            // Clamp angle to stay within this quadrant's arc
+            if (angle > usableArcEnd) angle = usableArcEnd;
+          }
+          attempts++;
+        }
+
+        placedPoints.push({ angle, radius });
+
+        points.push({
+          blip,
+          x: cx + radius * Math.cos(angle),
+          y: cy - radius * Math.sin(angle),
+          quadrantIndex,
+          ringIndex,
+        });
+      }
+    }
+  }
+
+  return points;
+}
+
+/**
+ * Get the center and max radius for a radar at the given dimensions.
+ * Useful for renderers that need these values independently.
+ */
+export function getRadarGeometry(
+  width: number,
+  height: number,
+  ringCount: number
+): {
+  cx: number;
+  cy: number;
+  maxRadius: number;
+  ringBandWidth: number;
+} {
+  const cx = width / 2;
+  const cy = height / 2;
+  const maxRadius = Math.min(cx, cy) * 0.88;
+  return { cx, cy, maxRadius, ringBandWidth: maxRadius / ringCount };
+}
+
+/** Exported for testing. */
+export { POSITION_ORDER, getQuadrantArc, BASE_BLIP_RADIUS, MIN_BLIP_RADIUS };

package/src/tech-radar/parser.ts

@@ -0,0 +1,385 @@
+import { makeDgmoError, formatDgmoError, suggest } from '../diagnostics';
+import {
+  measureIndent,
+  parseFirstLine,
+  parsePipeMetadata,
+  OPTION_NOCOLON_RE,
+} from '../utils/parsing';
+import type {
+  ParsedTechRadar,
+  TechRadarQuadrant,
+  TechRadarBlip,
+  QuadrantPosition,
+  BlipTrend,
+} from './types';
+
+const VALID_POSITIONS: readonly QuadrantPosition[] = [
+  'top-left',
+  'top-right',
+  'bottom-left',
+  'bottom-right',
+];
+
+const VALID_TRENDS: readonly BlipTrend[] = ['new', 'up', 'down', 'stable'];
+
+/** Clockwise order for global numbering: TL, TR, BR, BL. */
+const POSITION_ORDER: readonly QuadrantPosition[] = [
+  'top-left',
+  'top-right',
+  'bottom-right',
+  'bottom-left',
+];
+
+/** Known tech-radar options (key-value). */
+const KNOWN_OPTIONS = new Set<string>([]);
+/** Known tech-radar boolean options (bare keyword). */
+const KNOWN_BOOLEANS = new Set<string>([]);
+
+export function parseTechRadar(content: string): ParsedTechRadar {
+  const result: ParsedTechRadar = {
+    type: 'tech-radar',
+    title: '',
+    titleLineNumber: 0,
+    rings: [],
+    quadrants: [],
+    options: {},
+    diagnostics: [],
+    error: null,
+  };
+
+  const fail = (line: number, message: string): ParsedTechRadar => {
+    const diag = makeDgmoError(line, message);
+    result.diagnostics.push(diag);
+    result.error = formatDgmoError(diag);
+    return result;
+  };
+
+  const warn = (line: number, message: string): void => {
+    result.diagnostics.push(makeDgmoError(line, message, 'warning'));
+  };
+
+  if (!content || !content.trim()) {
+    return fail(0, 'No content provided');
+  }
+
+  /** Check if a string matches a declared ring name or alias (case-insensitive). */
+  function isRingName(name: string): boolean {
+    const lower = name.toLowerCase();
+    return result.rings.some(
+      (r) =>
+        r.name.toLowerCase() === lower ||
+        (r.alias !== null && r.alias.toLowerCase() === lower)
+    );
+  }
+
+  /** Get the canonical ring name for a case-insensitive match (by name or alias). */
+  function canonicalRingName(name: string): string {
+    const lower = name.toLowerCase();
+    const ring = result.rings.find(
+      (r) =>
+        r.name.toLowerCase() === lower ||
+        (r.alias !== null && r.alias.toLowerCase() === lower)
+    );
+    return ring?.name ?? name;
+  }
+
+  const lines = content.split('\n');
+  let headerParsed = false;
+  let inRingsBlock = false;
+  let currentQuadrant: TechRadarQuadrant | null = null;
+  let currentBlip: TechRadarBlip | null = null;
+  let blipBaseIndent = 0;
+  let currentRing: string | null = null; // active ring section (new syntax)
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNumber = i + 1;
+    const trimmed = line.trim();
+    const indent = measureIndent(line);
+
+    // Skip empty lines
+    if (!trimmed) {
+      if (inRingsBlock && result.rings.length > 0) {
+        inRingsBlock = false;
+      }
+      continue;
+    }
+
+    // Skip comments
+    if (trimmed.startsWith('//')) continue;
+
+    // --- First line: chart type + title ---
+    if (!headerParsed) {
+      const firstLine = parseFirstLine(trimmed);
+      if (firstLine && firstLine.chartType === 'tech-radar') {
+        result.title = firstLine.title ?? '';
+        result.titleLineNumber = lineNumber;
+        headerParsed = true;
+        continue;
+      }
+      return fail(lineNumber, 'Expected "tech-radar" chart type declaration');
+    }
+
+    // --- Rings block ---
+    if (indent === 0 && trimmed.toLowerCase() === 'rings') {
+      if (result.rings.length > 0) {
+        warn(lineNumber, 'Duplicate "rings" block — using last one');
+        result.rings = [];
+      }
+      inRingsBlock = true;
+      currentBlip = null;
+      currentQuadrant = null;
+      currentRing = null;
+      continue;
+    }
+
+    if (inRingsBlock) {
+      if (indent > 0) {
+        // Parse ring declaration: `Name`, `Name alias a`, or `Name aka a`
+        const aliasMatch = trimmed.match(/^(.+?)\s+(?:alias|aka)\s+(\S+)\s*$/i);
+        if (aliasMatch) {
+          result.rings.push({
+            name: aliasMatch[1].trim(),
+            alias: aliasMatch[2].trim(),
+            lineNumber,
+          });
+        } else {
+          result.rings.push({ name: trimmed, alias: null, lineNumber });
+        }
+        continue;
+      }
+      inRingsBlock = false;
+    }
+
+    // --- Options (bare keyword or key value, top-level only) ---
+    if (indent === 0 && !trimmed.includes('|')) {
+      const optMatch = trimmed.match(OPTION_NOCOLON_RE);
+      if (optMatch) {
+        const key = optMatch[1].toLowerCase();
+        if (KNOWN_OPTIONS.has(key)) {
+          result.options[key] = optMatch[2].trim();
+          currentBlip = null;
+          continue;
+        }
+      }
+      if (KNOWN_BOOLEANS.has(trimmed.toLowerCase())) {
+        result.options[trimmed.toLowerCase()] = 'on';
+        currentBlip = null;
+        continue;
+      }
+    }
+
+    // --- Quadrant section header: `Name | quadrant: position` ---
+    if (indent === 0 && trimmed.includes('|')) {
+      const segments = trimmed.split('|');
+      const meta = parsePipeMetadata(segments);
+      const quadrantPos = meta['quadrant'];
+
+      if (quadrantPos) {
+        const position = quadrantPos.toLowerCase() as QuadrantPosition;
+        if (!VALID_POSITIONS.includes(position)) {
+          const hint = suggest(position, [...VALID_POSITIONS]);
+          let msg = `Invalid quadrant position "${quadrantPos}". Must be one of: ${VALID_POSITIONS.join(', ')}`;
+          if (hint) msg += `. ${hint}`;
+          result.diagnostics.push(makeDgmoError(lineNumber, msg));
+          continue;
+        }
+
+        const existing = result.quadrants.find((q) => q.position === position);
+        if (existing) {
+          result.diagnostics.push(
+            makeDgmoError(
+              lineNumber,
+              `Duplicate quadrant position "${position}" — already used by "${existing.name}"`
+            )
+          );
+          continue;
+        }
+
+        const name = segments[0].trim();
+        const color = meta['color'] ?? null;
+
+        currentQuadrant = {
+          name,
+          position,
+          color,
+          lineNumber,
+          blips: [],
+        };
+        result.quadrants.push(currentQuadrant);
+        currentBlip = null;
+        currentRing = null;
+        continue;
+      }
+    }
+
+    // --- Inside a quadrant ---
+    if (currentQuadrant && indent > 0) {
+      // --- Ring section header (new syntax): indented line matching a declared ring name ---
+      if (
+        !trimmed.includes('|') &&
+        result.rings.length > 0 &&
+        isRingName(trimmed)
+      ) {
+        currentRing = canonicalRingName(trimmed);
+        currentBlip = null;
+        continue;
+      }
+
+      // --- Description lines: indented deeper than current blip ---
+      if (currentBlip && indent > blipBaseIndent) {
+        currentBlip.description.push(trimmed);
+        continue;
+      }
+
+      // --- Blip with pipe metadata ---
+      if (trimmed.includes('|')) {
+        const segments = trimmed.split('|');
+        const meta = parsePipeMetadata(segments);
+
+        // Determine ring: explicit `ring:` metadata overrides section ring
+        const explicitRing = meta['ring'];
+        const effectiveRing = explicitRing
+          ? canonicalRingName(explicitRing)
+          : currentRing;
+
+        if (!effectiveRing) {
+          result.diagnostics.push(
+            makeDgmoError(
+              lineNumber,
+              `Blip "${segments[0].trim()}" has no ring assignment. Use a ring section header or add "ring: RingName" metadata.`
+            )
+          );
+          continue;
+        }
+
+        // Validate ring name
+        if (
+          explicitRing &&
+          result.rings.length > 0 &&
+          !isRingName(explicitRing)
+        ) {
+          const hint = suggest(
+            explicitRing,
+            result.rings.map((r) => r.name)
+          );
+          let msg = `Unknown ring "${explicitRing}" on blip "${segments[0].trim()}"`;
+          if (hint) msg += `. ${hint}`;
+          result.diagnostics.push(makeDgmoError(lineNumber, msg));
+          continue;
+        }
+
+        // Parse optional trend
+        let trend: BlipTrend | null = null;
+        if (meta['trend']) {
+          const trendVal = meta['trend'].toLowerCase() as BlipTrend;
+          if (!VALID_TRENDS.includes(trendVal)) {
+            const hint = suggest(meta['trend'], [...VALID_TRENDS]);
+            let msg = `Unknown trend "${meta['trend']}" on blip "${segments[0].trim()}". Must be one of: ${VALID_TRENDS.join(', ')}`;
+            if (hint) msg += `. ${hint}`;
+            result.diagnostics.push(makeDgmoError(lineNumber, msg, 'warning'));
+          } else {
+            trend = trendVal;
+          }
+        }
+
+        currentBlip = {
+          name: segments[0].trim(),
+          ring: effectiveRing,
+          trend,
+          description: [],
+          lineNumber,
+          globalNumber: 0,
+        };
+        blipBaseIndent = indent;
+        currentQuadrant.blips.push(currentBlip);
+        continue;
+      }
+
+      // --- Blip without pipe metadata (plain name, inherits ring from section) ---
+      if (currentRing) {
+        currentBlip = {
+          name: trimmed,
+          ring: currentRing,
+          trend: null,
+          description: [],
+          lineNumber,
+          globalNumber: 0,
+        };
+        blipBaseIndent = indent;
+        currentQuadrant.blips.push(currentBlip);
+        continue;
+      }
+
+      // No ring section and no pipe metadata — error
+      result.diagnostics.push(
+        makeDgmoError(
+          lineNumber,
+          `Blip "${trimmed}" has no ring assignment. Place it under a ring section header or use: ${trimmed} | ring: RingName`
+        )
+      );
+      continue;
+    }
+
+    // --- Unrecognized top-level line ---
+    if (indent === 0) {
+      if (!trimmed.includes('|') && headerParsed && result.rings.length > 0) {
+        warn(
+          lineNumber,
+          `Unrecognized line "${trimmed}". Quadrant headers require pipe metadata: ${trimmed} | quadrant: top-left`
+        );
+      }
+    }
+  }
+
+  // --- Validation ---
+
+  if (result.rings.length === 0) {
+    result.diagnostics.push(
+      makeDgmoError(
+        0,
+        'Missing "rings" block — declare ring names before quadrant sections'
+      )
+    );
+  }
+
+  if (result.quadrants.length !== 4) {
+    const msg =
+      result.quadrants.length === 0
+        ? 'No quadrants declared. Exactly 4 quadrants are required.'
+        : `Expected exactly 4 quadrants, found ${result.quadrants.length}. Each quadrant needs a unique position (top-left, top-right, bottom-left, bottom-right).`;
+    result.diagnostics.push(makeDgmoError(0, msg));
+  }
+
+  // --- Global numbering ---
+  assignGlobalNumbers(result);
+
+  return result;
+}
+
+/**
+ * Assign global blip numbers. Order:
+ * 1. Quadrants in clockwise order: top-left, top-right, bottom-right, bottom-left
+ * 2. Within each quadrant: rings from innermost to outermost
+ * 3. Within each ring: declaration order
+ */
+function assignGlobalNumbers(result: ParsedTechRadar): void {
+  const ringOrder = result.rings.map((r) => r.name);
+  let counter = 1;
+
+  for (const position of POSITION_ORDER) {
+    const quadrant = result.quadrants.find((q) => q.position === position);
+    if (!quadrant) continue;
+
+    const sortedBlips = [...quadrant.blips].sort((a, b) => {
+      const aRing = ringOrder.indexOf(a.ring);
+      const bRing = ringOrder.indexOf(b.ring);
+      if (aRing !== bRing) return aRing - bRing;
+      return a.lineNumber - b.lineNumber;
+    });
+
+    for (const blip of sortedBlips) {
+      blip.globalNumber = counter++;
+    }
+  }
+}