@diagrammo/dgmo 0.6.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "type": "module",
@@ -29,7 +29,8 @@
     ".claude/commands",
     ".github/copilot-instructions.md",
     ".cursorrules",
-    ".windsurfrules"
+    ".windsurfrules",
+    "AGENTS.md"
   ],
   "sideEffects": false,
   "scripts": {
@@ -40,6 +41,7 @@
     "test:watch": "vitest",
     "gallery": "pnpm build && node scripts/generate-gallery.mjs",
     "check:duplication": "jscpd ./src",
+    "check:deadcode": "knip",
     "postinstall": "node -e \"console.log('\\n💡 Claude Code user? Run: dgmo --install-claude-skill\\n')\""
   },
   "dependencies": {
@@ -64,9 +66,9 @@
     "@types/d3-scale": "^4.0.8",
     "@types/d3-selection": "^3.0.11",
     "@types/d3-shape": "^3.1.7",
-    "@types/dagre": "^0.7.54",
     "@types/jsdom": "^28.0.0",
     "jscpd": "^4.0.8",
+    "knip": "^6.0.1",
     "tsup": "^8.5.1",
     "typescript": "^5.7.3",
     "vitest": "^4.0.18"

package/src/c4/layout.ts

@@ -86,7 +86,6 @@ const DESC_LINE_HEIGHT = 16;
 const DESC_CHAR_WIDTH = 6.5;
 const CARD_V_PAD = 14;
 const CARD_H_PAD = 20;
-const TECH_LINE_HEIGHT = 16;
 const META_LINE_HEIGHT = 16;
 const META_CHAR_WIDTH = 6.5;
 const MARGIN = 40;
@@ -478,10 +477,6 @@ export function rollUpContextRelationships(parsed: ParsedC4): ContextRelationshi
   const allRels = collectAllRelationships(parsed.elements, ownerMap);
 
   // Also include orphan relationships
-  for (const rel of parsed.relationships) {
-    // Orphan rels have no source element name — skip them for context roll-up
-  }
-
   // Separate system-level (explicit) from nested (rolled-up)
   const topLevelNames = new Set(parsed.elements.map((e) => e.name));
   const explicitKeys = new Set<string>();

package/src/c4/parser.ts

@@ -3,7 +3,6 @@
 // ============================================================
 
 import type { PaletteColors } from '../palettes';
-import type { DgmoError } from '../diagnostics';
 import { makeDgmoError, formatDgmoError, suggest } from '../diagnostics';
 import type { TagGroup } from '../utils/tag-groups';
 import { matchTagBlockHeading } from '../utils/tag-groups';
@@ -751,21 +750,6 @@ function attachElement(
 // Post-parse validation
 // ============================================================
 
-function collectAllNames(result: ParsedC4): Map<string, number> {
-  const names = new Map<string, number>();
-  function walk(elements: C4Element[]) {
-    for (const el of elements) {
-      names.set(el.name.toLowerCase(), el.lineNumber);
-      walk(el.children);
-      for (const g of el.groups) {
-        walk(g.children);
-      }
-    }
-  }
-  walk(result.elements);
-  return names;
-}
-
 function validateRelationshipTargets(
   result: ParsedC4,
   knownNames: Map<string, number>,

package/src/c4/renderer.ts

@@ -9,8 +9,7 @@ import type { PaletteColors } from '../palettes';
 import { mix } from '../palettes/color-utils';
 import { renderInlineText } from '../utils/inline-markdown';
 import type { ParsedC4 } from './types';
-import type { C4Shape } from './types';
-import type { C4LayoutResult, C4LayoutNode, C4LayoutEdge, C4LayoutBoundary, C4LegendGroup } from './layout';
+import type { C4LayoutResult, C4LayoutEdge, C4LegendGroup } from './layout';
 import { parseC4 } from './parser';
 import { layoutC4Context, layoutC4Containers, layoutC4Components, layoutC4Deployment, collectCardMetadata } from './layout';
 import {
@@ -50,7 +49,6 @@ const CARD_V_PAD = 14;
 const TYPE_LABEL_HEIGHT = 18;
 const DIVIDER_GAP = 6;
 const NAME_HEIGHT = 20;
-const TECH_LINE_HEIGHT = 16;
 const META_FONT_SIZE = 11;
 const META_CHAR_WIDTH = 6.5;
 const META_LINE_HEIGHT = 16;
@@ -257,9 +255,8 @@ export function renderC4Context(
   const scale = Math.min(MAX_SCALE, scaleX, scaleY);
 
   const scaledW = diagramW * scale;
-  const scaledH = diagramH * scale;
   const offsetX = (width - scaledW) / 2;
-  const offsetY = titleHeight + DIAGRAM_PADDING;
+  const offsetY = titleHeight + DIAGRAM_PADDING + legendReserveH;
 
   const svg = d3Selection
     .select(container)
@@ -595,12 +592,12 @@ export function renderC4Context(
 
   // ── Legend ──
   if (hasLegend) {
-    // App mode: fixed overlay at SVG bottom so it's always readable regardless of scale.
+    // App mode: fixed overlay at SVG top so it's always readable regardless of scale.
     // Export mode: render inside scaled contentG at layout coordinates.
     const legendParent = fixedLegend
       ? svg.append('g')
           .attr('class', 'c4-legend-fixed')
-          .attr('transform', `translate(0, ${height - DIAGRAM_PADDING - LEGEND_HEIGHT})`)
+          .attr('transform', `translate(0, ${DIAGRAM_PADDING + titleHeight})`)
       : contentG.append('g').attr('class', 'c4-legend');
     if (activeTagGroup) {
       legendParent.attr('data-legend-active', activeTagGroup.toLowerCase());
@@ -1300,9 +1297,8 @@ export function renderC4Containers(
   const scale = Math.min(MAX_SCALE, scaleX, scaleY);
 
   const scaledW = diagramW * scale;
-  const scaledH = diagramH * scale;
   const offsetX = (width - scaledW) / 2;
-  const offsetY = titleHeight + DIAGRAM_PADDING;
+  const offsetY = titleHeight + DIAGRAM_PADDING + legendReserveH;
 
   const svg = d3Selection
     .select(container)
@@ -1711,12 +1707,12 @@ export function renderC4Containers(
 
   // ── Legend ──
   if (hasLegend) {
-    // App mode: fixed overlay at SVG bottom so it's always readable regardless of scale.
+    // App mode: fixed overlay at SVG top so it's always readable regardless of scale.
     // Export mode: render inside scaled contentG at layout coordinates.
     const legendParent = fixedLegend
       ? svg.append('g')
           .attr('class', 'c4-legend-fixed')
-          .attr('transform', `translate(0, ${height - DIAGRAM_PADDING - LEGEND_HEIGHT})`)
+          .attr('transform', `translate(0, ${DIAGRAM_PADDING + titleHeight})`)
       : contentG.append('g').attr('class', 'c4-legend');
     if (activeTagGroup) {
       legendParent.attr('data-legend-active', activeTagGroup.toLowerCase());

package/src/class/layout.ts

@@ -2,7 +2,6 @@ import dagre from '@dagrejs/dagre';
 import type {
   ParsedClassDiagram,
   ClassNode,
-  ClassRelationship,
   RelationshipType,
 } from './types';
 

package/src/class/parser.ts

@@ -383,3 +383,31 @@ export function looksLikeClassDiagram(content: string): boolean {
 
   return false;
 }
+
+// ============================================================
+// Symbol extraction (for completion API)
+// ============================================================
+
+import type { DiagramSymbols } from '../completion';
+
+/**
+ * Extract class names (entities) from class diagram document text.
+ * Used by the dgmo completion API for ghost hints and popup completions.
+ */
+export function extractSymbols(docText: string): DiagramSymbols {
+  const entities: string[] = [];
+  let inMetadata = true;
+  for (const rawLine of docText.split('\n')) {
+    const line = rawLine.trim();
+    if (inMetadata && /^[a-z-]+\s*:/i.test(line)) continue;
+    inMetadata = false;
+    if (line.length === 0 || /^\s/.test(rawLine)) continue;
+    const m = CLASS_DECL_RE.exec(line);
+    if (m && !entities.includes(m[1]!)) entities.push(m[1]!);
+  }
+  return {
+    kind: 'class',
+    entities,
+    keywords: ['extends', 'implements', 'abstract', 'interface', 'enum'],
+  };
+}

package/src/class/renderer.ts

@@ -5,10 +5,23 @@
 import * as d3Selection from 'd3-selection';
 import * as d3Shape from 'd3-shape';
 import { FONT_FAMILY } from '../fonts';
+import { runInExportContainer, extractExportSvg } from '../utils/export-container';
+import {
+  LEGEND_HEIGHT,
+  LEGEND_PILL_PAD,
+  LEGEND_PILL_FONT_SIZE,
+  LEGEND_PILL_FONT_W,
+  LEGEND_CAPSULE_PAD,
+  LEGEND_DOT_R,
+  LEGEND_ENTRY_FONT_SIZE,
+  LEGEND_ENTRY_FONT_W,
+  LEGEND_ENTRY_DOT_GAP,
+  LEGEND_ENTRY_TRAIL,
+} from '../utils/legend-constants';
 import type { PaletteColors } from '../palettes';
 import { mix } from '../palettes/color-utils';
 import type { ParsedClassDiagram, ClassModifier, RelationshipType } from './types';
-import type { ClassLayoutResult, ClassLayoutNode, ClassLayoutEdge } from './layout';
+import type { ClassLayoutResult } from './layout';
 import { parseClassDiagram } from './parser';
 import { layoutClassDiagram } from './layout';
 
@@ -50,6 +63,49 @@ function nodeStroke(palette: PaletteColors, modifier: ClassModifier | undefined,
   return nodeColor ?? modifierColor(modifier, palette, colorOff);
 }
 
+// ============================================================
+// Legend helpers
+// ============================================================
+
+interface ClassLegendEntry {
+  label: string;
+  colorKey: keyof PaletteColors['colors'];
+}
+
+const CLASS_TYPE_MAP: Record<string, ClassLegendEntry> = {
+  class:     { label: 'Class',     colorKey: 'teal' },
+  abstract:  { label: 'Abstract',  colorKey: 'purple' },
+  interface: { label: 'Interface', colorKey: 'blue' },
+  enum:      { label: 'Enum',      colorKey: 'yellow' },
+};
+
+const CLASS_TYPE_ORDER = ['class', 'abstract', 'interface', 'enum'];
+
+function collectClassTypes(parsed: ParsedClassDiagram): ClassLegendEntry[] {
+  if (parsed.options?.color === 'off') return [];
+
+  const present = new Set<string>();
+  for (const c of parsed.classes) {
+    if (c.color) continue; // explicit color override — skip
+    present.add(c.modifier ?? 'class');
+  }
+  return CLASS_TYPE_ORDER.filter((k) => present.has(k)).map((k) => CLASS_TYPE_MAP[k]);
+}
+
+const LEGEND_GROUP_NAME = 'Type';
+
+function legendEntriesWidth(entries: ClassLegendEntry[]): number {
+  let w = 0;
+  for (const e of entries) {
+    w += LEGEND_DOT_R * 2 + LEGEND_ENTRY_DOT_GAP + e.label.length * LEGEND_ENTRY_FONT_W + LEGEND_ENTRY_TRAIL;
+  }
+  return w;
+}
+
+function classTypeKey(modifier: ClassModifier | undefined): string {
+  return modifier ?? 'class';
+}
+
 // ============================================================
 // Visibility symbols
 // ============================================================
@@ -99,8 +155,6 @@ function isSourceMarker(type: RelationshipType): boolean {
 // Main renderer
 // ============================================================
 
-type GSelection = d3Selection.Selection<SVGGElement, unknown, null, undefined>;
-
 export function renderClassDiagram(
   container: HTMLDivElement,
   parsed: ParsedClassDiagram,
@@ -108,7 +162,8 @@ export function renderClassDiagram(
   palette: PaletteColors,
   isDark: boolean,
   onClickItem?: (lineNumber: number) => void,
-  exportDims?: { width?: number; height?: number }
+  exportDims?: { width?: number; height?: number },
+  legendActive?: boolean | null
 ): void {
   d3Selection.select(container).selectAll(':not([data-d3-tooltip])').remove();
 
@@ -116,18 +171,22 @@ export function renderClassDiagram(
   const height = exportDims?.height ?? container.clientHeight;
   if (width <= 0 || height <= 0) return;
 
+  const legendEntries = collectClassTypes(parsed);
+  const hasLegend = legendEntries.length > 1; // only show when multiple types present
+
   const titleHeight = parsed.title ? 40 : 0;
+  const LEGEND_FIXED_GAP = 8;
+  const legendReserve = hasLegend ? LEGEND_HEIGHT + LEGEND_FIXED_GAP : 0;
   const diagramW = layout.width;
   const diagramH = layout.height;
-  const availH = height - titleHeight;
+  const availH = height - titleHeight - legendReserve;
   const scaleX = (width - DIAGRAM_PADDING * 2) / diagramW;
   const scaleY = (availH - DIAGRAM_PADDING * 2) / diagramH;
   const scale = Math.min(MAX_SCALE, scaleX, scaleY);
 
   const scaledW = diagramW * scale;
-  const scaledH = diagramH * scale;
   const offsetX = (width - scaledW) / 2;
-  const offsetY = titleHeight + DIAGRAM_PADDING;
+  const offsetY = titleHeight + legendReserve + DIAGRAM_PADDING;
 
   const svg = d3Selection
     .select(container)
@@ -246,6 +305,114 @@ export function renderClassDiagram(
     }
   }
 
+  // ── Legend ──
+  // legendActive: true = expanded (default), false = collapsed pill only
+  const isLegendExpanded = legendActive !== false;
+  if (hasLegend) {
+    const groupBg = isDark
+      ? mix(palette.surface, palette.bg, 50)
+      : mix(palette.surface, palette.bg, 30);
+
+    const pillWidth = LEGEND_GROUP_NAME.length * LEGEND_PILL_FONT_W + LEGEND_PILL_PAD;
+    const pillH = LEGEND_HEIGHT - LEGEND_CAPSULE_PAD * 2;
+    const entriesW = legendEntriesWidth(legendEntries);
+
+    const totalW = isLegendExpanded
+      ? LEGEND_CAPSULE_PAD * 2 + pillWidth + LEGEND_ENTRY_TRAIL + entriesW
+      : pillWidth;
+
+    const legendX = (width - totalW) / 2;
+    const legendY = titleHeight;
+
+    const legendG = svg
+      .append('g')
+      .attr('class', 'cd-legend')
+      .attr('data-legend-group', 'type')
+      .attr('transform', `translate(${legendX}, ${legendY})`)
+      .style('cursor', 'pointer');
+
+    if (isLegendExpanded) {
+      // Outer capsule
+      legendG.append('rect')
+        .attr('width', totalW)
+        .attr('height', LEGEND_HEIGHT)
+        .attr('rx', LEGEND_HEIGHT / 2)
+        .attr('fill', groupBg);
+
+      // Inner pill
+      legendG.append('rect')
+        .attr('x', LEGEND_CAPSULE_PAD)
+        .attr('y', LEGEND_CAPSULE_PAD)
+        .attr('width', pillWidth)
+        .attr('height', pillH)
+        .attr('rx', pillH / 2)
+        .attr('fill', palette.bg);
+
+      legendG.append('rect')
+        .attr('x', LEGEND_CAPSULE_PAD)
+        .attr('y', LEGEND_CAPSULE_PAD)
+        .attr('width', pillWidth)
+        .attr('height', pillH)
+        .attr('rx', pillH / 2)
+        .attr('fill', 'none')
+        .attr('stroke', mix(palette.textMuted, palette.bg, 50))
+        .attr('stroke-width', 0.75);
+
+      legendG.append('text')
+        .attr('x', LEGEND_CAPSULE_PAD + pillWidth / 2)
+        .attr('y', LEGEND_HEIGHT / 2 + LEGEND_PILL_FONT_SIZE / 2 - 2)
+        .attr('font-size', LEGEND_PILL_FONT_SIZE)
+        .attr('font-weight', '500')
+        .attr('fill', palette.text)
+        .attr('text-anchor', 'middle')
+        .attr('font-family', FONT_FAMILY)
+        .text(LEGEND_GROUP_NAME);
+
+      // Entries
+      let entryX = LEGEND_CAPSULE_PAD + pillWidth + LEGEND_ENTRY_TRAIL;
+      for (const entry of legendEntries) {
+        const color = palette.colors[entry.colorKey];
+        const typeKey = CLASS_TYPE_ORDER.find((k) => CLASS_TYPE_MAP[k] === entry)!;
+
+        const entryG = legendG.append('g')
+          .attr('data-legend-entry', typeKey);
+
+        entryG.append('circle')
+          .attr('cx', entryX + LEGEND_DOT_R)
+          .attr('cy', LEGEND_HEIGHT / 2)
+          .attr('r', LEGEND_DOT_R)
+          .attr('fill', color);
+
+        entryG.append('text')
+          .attr('x', entryX + LEGEND_DOT_R * 2 + LEGEND_ENTRY_DOT_GAP)
+          .attr('y', LEGEND_HEIGHT / 2 + LEGEND_ENTRY_FONT_SIZE / 2 - 1)
+          .attr('font-size', LEGEND_ENTRY_FONT_SIZE)
+          .attr('fill', palette.textMuted)
+          .attr('font-family', FONT_FAMILY)
+          .text(entry.label);
+
+        entryX += LEGEND_DOT_R * 2 + LEGEND_ENTRY_DOT_GAP + entry.label.length * LEGEND_ENTRY_FONT_W + LEGEND_ENTRY_TRAIL;
+      }
+    } else {
+      // Collapsed: single muted pill
+      legendG.append('rect')
+        .attr('width', pillWidth)
+        .attr('height', LEGEND_HEIGHT)
+        .attr('rx', LEGEND_HEIGHT / 2)
+        .attr('fill', groupBg);
+
+      legendG.append('text')
+        .attr('x', pillWidth / 2)
+        .attr('y', LEGEND_HEIGHT / 2 + LEGEND_PILL_FONT_SIZE / 2 - 2)
+        .attr('font-size', LEGEND_PILL_FONT_SIZE)
+        .attr('font-weight', '500')
+        .attr('fill', palette.textMuted)
+        .attr('text-anchor', 'middle')
+        .attr('font-family', FONT_FAMILY)
+        .text(LEGEND_GROUP_NAME);
+    }
+  }
+
   // ── Content group ──
   const contentG = svg
     .append('g')
@@ -322,7 +489,8 @@ export function renderClassDiagram(
       .attr('transform', `translate(${node.x}, ${node.y})`)
       .attr('class', 'cd-class')
       .attr('data-line-number', String(node.lineNumber))
-      .attr('data-node-id', node.id);
+      .attr('data-node-id', node.id)
+      .attr('data-cd-type', classTypeKey(node.modifier));
 
     if (onClickItem) {
       nodeG.style('cursor', 'pointer').on('click', () => {
@@ -333,8 +501,11 @@ export function renderClassDiagram(
     const w = node.width;
     const h = node.height;
     const colorOff = parsed.options?.color === 'off';
-    const fill = nodeFill(palette, isDark, node.modifier, node.color, colorOff);
-    const stroke = nodeStroke(palette, node.modifier, node.color, colorOff);
+    // When legend is collapsed, use neutral color for nodes without explicit color
+    const neutralize = hasLegend && !isLegendExpanded && !node.color;
+    const effectiveColor = neutralize ? palette.primary : node.color;
+    const fill = nodeFill(palette, isDark, node.modifier, effectiveColor, colorOff);
+    const stroke = nodeStroke(palette, node.modifier, effectiveColor, colorOff);
 
     // Outer rectangle
     nodeG.append('rect')
@@ -506,16 +677,13 @@ export function renderClassDiagramForExport(
   const layout = layoutClassDiagram(parsed);
   const isDark = theme === 'dark';
 
-  const container = document.createElement('div');
+  const legendEntries = collectClassTypes(parsed);
+  const EXPORT_LEGEND_GAP = 8;
+  const legendReserve = legendEntries.length > 1 ? LEGEND_HEIGHT + EXPORT_LEGEND_GAP : 0;
   const exportWidth = layout.width + DIAGRAM_PADDING * 2;
-  const exportHeight = layout.height + DIAGRAM_PADDING * 2 + (parsed.title ? 40 : 0);
-  container.style.width = `${exportWidth}px`;
-  container.style.height = `${exportHeight}px`;
-  container.style.position = 'absolute';
-  container.style.left = '-9999px';
-  document.body.appendChild(container);
-
-  try {
+  const exportHeight = layout.height + DIAGRAM_PADDING * 2 + (parsed.title ? 40 : 0) + legendReserve;
+
+  return runInExportContainer(exportWidth, exportHeight, (container) => {
     renderClassDiagram(
       container,
       parsed,
@@ -525,19 +693,6 @@ export function renderClassDiagramForExport(
       undefined,
       { width: exportWidth, height: exportHeight }
     );
-
-    const svgEl = container.querySelector('svg');
-    if (!svgEl) return '';
-
-    if (theme === 'transparent') {
-      svgEl.style.background = 'none';
-    }
-
-    svgEl.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
-    svgEl.style.fontFamily = FONT_FAMILY;
-
-    return svgEl.outerHTML;
-  } finally {
-    document.body.removeChild(container);
-  }
+    return extractExportSvg(container, theme);
+  });
 }