@diagrammo/dgmo 0.47.0 → 0.48.0

package/src/tech-radar/layout.ts

@@ -1,197 +0,0 @@
-import type {
-  ParsedTechRadar,
-  TechRadarBlip,
-  TechRadarLayoutPoint,
-  QuadrantPosition,
-} from './types';
-import { ScaleContext } from '../utils/scaling';
-
-/** 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,
-  ctx?: ScaleContext
-): TechRadarLayoutPoint[] {
-  const points: TechRadarLayoutPoint[] = [];
-
-  if (parsed.rings.length === 0 || parsed.quadrants.length === 0) return points;
-
-  const sc = ctx ?? ScaleContext.identity();
-  const sBlipRadius = Math.max(
-    MIN_BLIP_RADIUS,
-    sc.structural(BASE_BLIP_RADIUS)
-  );
-
-  const cx = width / 2;
-  const cy = height / 2;
-  const maxRadius = Math.min(cx, cy) * 0.88;
-  const ringCount = parsed.rings.length;
-  const ringBandWidth = maxRadius / ringCount;
-  const ringOrder = parsed.rings.map((r) => r.name);
-
-  const radialPadding = ringBandWidth * 0.12;
-  const angularPadding = 0.05;
-
-  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;
-
-    const blipsByRing = new Map<string, TechRadarBlip[]>();
-    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(sBlipRadius, (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++) {
-        // In-bounds by loop guard (bi < blips.length).
-        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 };
-}
-
-export { POSITION_ORDER, getQuadrantArc };

package/src/tech-radar/parser.ts

@@ -1,436 +0,0 @@
-import { makeDgmoError, makeFail, suggest } from '../diagnostics';
-import { TECH_RADAR_REGISTRY } from '../utils/reserved-key-registry';
-import {
-  measureIndent,
-  parseFirstLine,
-  splitNameAndMeta,
-  OPTION_NOCOLON_RE,
-  warnUnknownMetaKeys,
-} from '../utils/parsing';
-import type { Writable } from '../utils/brand';
-import type {
-  ParsedTechRadar,
-  TechRadarQuadrant,
-  TechRadarBlip,
-  QuadrantPosition,
-  BlipTrend,
-} from './types';
-
-type WritableQuadrant = Omit<Writable<TechRadarQuadrant>, 'blips'> & {
-  blips: Writable<TechRadarBlip>[];
-};
-type WritableResult = Omit<
-  Writable<ParsedTechRadar>,
-  'quadrants' | 'options'
-> & {
-  quadrants: WritableQuadrant[];
-  options: Record<string, string>;
-};
-
-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>([
-  'show-blip-legend',
-  'solid-fill',
-  'no-title',
-]);
-
-export function parseTechRadar(content: string): ParsedTechRadar {
-  const result: WritableResult = {
-    type: 'tech-radar',
-    title: '',
-    titleLineNumber: 0,
-    rings: [],
-    quadrants: [],
-    options: {},
-    diagnostics: [],
-    error: null,
-  };
-
-  const fail = makeFail(result);
-
-  const warn = (line: number, message: string): void => {
-    result.diagnostics.push(makeDgmoError(line, message, 'warning'));
-  };
-
-  if (!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: WritableQuadrant | null = null;
-  let currentBlip: Writable<TechRadarBlip> | null = null;
-  let blipBaseIndent = 0;
-  let currentRing: string | null = null; // active ring section (new syntax)
-
-  for (let i = 0; i < lines.length; i++) {
-    // In-bounds by loop guard (i < lines.length).
-    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?.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 — only the last is kept; merge all ring names into one "rings" block.'
-        );
-        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({
-            // Capture groups [1] and [2] guaranteed by regex match.
-            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) {
-        // Capture groups [1] and [2] guaranteed by OPTION_NOCOLON_RE shape.
-        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` (§1.4) ---
-    if (indent === 0 && /\bquadrant\s*:/.test(trimmed)) {
-      const split = splitNameAndMeta(
-        trimmed,
-        TECH_RADAR_REGISTRY,
-        undefined,
-        undefined,
-        undefined,
-        undefined,
-        { peelAlias: false }
-      );
-      warnUnknownMetaKeys(
-        split.meta,
-        TECH_RADAR_REGISTRY,
-        (msg) => warn(lineNumber, msg),
-        split.name
-      );
-      const segments: string[] = [split.name];
-      const meta: Record<string, string> = split.meta;
-      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;
-        }
-
-        // In-bounds: split() always returns at least one element.
-        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 same-line metadata (§1.4) ---
-      if (/\b(?:ring|trend|color|description)\s*:/.test(trimmed)) {
-        const split = splitNameAndMeta(
-          trimmed,
-          TECH_RADAR_REGISTRY,
-          undefined,
-          undefined,
-          undefined,
-          undefined,
-          { peelAlias: false }
-        );
-        warnUnknownMetaKeys(
-          split.meta,
-          TECH_RADAR_REGISTRY,
-          (msg) => warn(lineNumber, msg),
-          split.name
-        );
-        const segments: string[] = [split.name];
-        const meta: Record<string, string> = split.meta;
-
-        // 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 = {
-          // In-bounds: split() always returns at least one element.
-          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. Put it under a ring section header, or add a colon-keyed ring — '${trimmed} ring: RingName' (per §20).`
-        )
-      );
-      continue;
-    }
-
-    // --- Unrecognized top-level line ---
-    if (indent === 0) {
-      if (!trimmed.includes('|') && headerParsed && result.rings.length > 0) {
-        warn(
-          lineNumber,
-          `Unrecognized line "${trimmed}". A quadrant header is 'Name quadrant: <top-left|top-right|bottom-left|bottom-right>' (per §20).`
-        );
-      }
-    }
-  }
-
-  // --- 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: WritableResult): 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++;
-    }
-  }
-}