@diagrammo/dgmo 0.6.0 → 0.6.2

package/src/d3.ts

@@ -184,6 +184,19 @@ import { makeDgmoError, formatDgmoError, suggest } from './diagnostics';
 import { collectIndentedValues, extractColor, parsePipeMetadata } from './utils/parsing';
 import { matchTagBlockHeading, validateTagValues, resolveTagColor } from './utils/tag-groups';
 import type { TagGroup } from './utils/tag-groups';
+import {
+  LEGEND_HEIGHT as TL_LEGEND_HEIGHT,
+  LEGEND_PILL_PAD as TL_LEGEND_PILL_PAD,
+  LEGEND_PILL_FONT_SIZE as TL_LEGEND_PILL_FONT_SIZE,
+  LEGEND_PILL_FONT_W as TL_LEGEND_PILL_FONT_W,
+  LEGEND_CAPSULE_PAD as TL_LEGEND_CAPSULE_PAD,
+  LEGEND_DOT_R as TL_LEGEND_DOT_R,
+  LEGEND_ENTRY_FONT_SIZE as TL_LEGEND_ENTRY_FONT_SIZE,
+  LEGEND_ENTRY_FONT_W as TL_LEGEND_ENTRY_FONT_W,
+  LEGEND_ENTRY_DOT_GAP as TL_LEGEND_ENTRY_DOT_GAP,
+  LEGEND_ENTRY_TRAIL as TL_LEGEND_ENTRY_TRAIL,
+  LEGEND_GROUP_GAP as TL_LEGEND_GROUP_GAP,
+} from './utils/legend-constants';
 
 // ============================================================
 // Shared Rendering Helpers
@@ -3047,7 +3060,7 @@ export function renderTimeline(
     }
   }
 
-  // Reserve space for tag legend between title and chart content
+  // Reserve space for tag legend at the bottom of chart content
   const tagLegendReserve = parsed.timelineTagGroups.length > 0 ? 36 : 0;
 
   // ================================================================
@@ -3087,9 +3100,9 @@ export function renderTimeline(
       const scaleMargin = timelineScale ? 40 : 0;
       const markerMargin = timelineMarkers.length > 0 ? 30 : 0;
       const margin = {
-        top: 104 + markerMargin + tagLegendReserve,
+        top: 104 + markerMargin,
         right: 40 + scaleMargin,
-        bottom: 40,
+        bottom: 40 + tagLegendReserve,
         left: 60 + scaleMargin,
       };
       const innerWidth = width - margin.left - margin.right;
@@ -3309,9 +3322,9 @@ export function renderTimeline(
       const scaleMargin = timelineScale ? 40 : 0;
       const markerMargin = timelineMarkers.length > 0 ? 30 : 0;
       const margin = {
-        top: 104 + markerMargin + tagLegendReserve,
+        top: 104 + markerMargin,
         right: 200,
-        bottom: 40,
+        bottom: 40 + tagLegendReserve,
         left: 60 + scaleMargin,
       };
       const innerWidth = width - margin.left - margin.right;
@@ -3590,9 +3603,9 @@ export function renderTimeline(
     // Group-sorted doesn't need legend space (group names shown on left)
     const baseTopMargin = title ? 50 : 20;
     const margin = {
-      top: baseTopMargin + (timelineScale ? 40 : 0) + markerMargin + tagLegendReserve,
+      top: baseTopMargin + (timelineScale ? 40 : 0) + markerMargin,
       right: 40,
-      bottom: 40 + scaleMargin,
+      bottom: 40 + scaleMargin + tagLegendReserve,
       left: dynamicLeftMargin,
     };
     const innerWidth = width - margin.left - margin.right;
@@ -3869,9 +3882,9 @@ export function renderTimeline(
     const scaleMargin = timelineScale ? 24 : 0;
     const markerMargin = timelineMarkers.length > 0 ? 30 : 0;
     const margin = {
-      top: 104 + (timelineScale ? 40 : 0) + markerMargin + tagLegendReserve,
+      top: 104 + (timelineScale ? 40 : 0) + markerMargin,
       right: 40,
-      bottom: 40 + scaleMargin,
+      bottom: 40 + scaleMargin + tagLegendReserve,
       left: 60,
     };
     const innerWidth = width - margin.left - margin.right;
@@ -4121,23 +4134,23 @@ export function renderTimeline(
 
   // ── Tag Legend (org-chart-style pills) ──
   if (parsed.timelineTagGroups.length > 0) {
-    const LG_HEIGHT = 28;
-    const LG_PILL_PAD = 16;
-    const LG_PILL_FONT_SIZE = 11;
-    const LG_PILL_FONT_W = LG_PILL_FONT_SIZE * 0.6;
-    const LG_CAPSULE_PAD = 4;
-    const LG_DOT_R = 4;
-    const LG_ENTRY_FONT_SIZE = 10;
-    const LG_ENTRY_FONT_W = LG_ENTRY_FONT_SIZE * 0.6;
-    const LG_ENTRY_DOT_GAP = 4;
-    const LG_ENTRY_TRAIL = 8;
-    const LG_GROUP_GAP = 12;
-    const LG_ICON_W = 20; // swimlane icon area (icon + surrounding space)
+    const LG_HEIGHT = TL_LEGEND_HEIGHT;
+    const LG_PILL_PAD = TL_LEGEND_PILL_PAD;
+    const LG_PILL_FONT_SIZE = TL_LEGEND_PILL_FONT_SIZE;
+    const LG_PILL_FONT_W = TL_LEGEND_PILL_FONT_W;
+    const LG_CAPSULE_PAD = TL_LEGEND_CAPSULE_PAD;
+    const LG_DOT_R = TL_LEGEND_DOT_R;
+    const LG_ENTRY_FONT_SIZE = TL_LEGEND_ENTRY_FONT_SIZE;
+    const LG_ENTRY_FONT_W = TL_LEGEND_ENTRY_FONT_W;
+    const LG_ENTRY_DOT_GAP = TL_LEGEND_ENTRY_DOT_GAP;
+    const LG_ENTRY_TRAIL = TL_LEGEND_ENTRY_TRAIL;
+    const LG_GROUP_GAP = TL_LEGEND_GROUP_GAP;
+    const LG_ICON_W = 20; // swimlane icon area (icon + surrounding space) — local
 
     const mainSvg = d3Selection.select(container).select<SVGSVGElement>('svg');
     const mainG = mainSvg.select<SVGGElement>('g');
     if (!mainSvg.empty() && !mainG.empty()) {
-      const legendY = title ? 50 : 10;
+      const legendY = height - LG_HEIGHT - 4;
 
       const groupBg = isDark
         ? mix(palette.surface, palette.bg, 50)
@@ -4212,6 +4225,7 @@ export function renderTimeline(
       function drawLegend() {
         // Remove previous legend
         mainSvg.selectAll('.tl-tag-legend-group').remove();
+        mainSvg.selectAll('.tl-tag-legend-container').remove();
 
         // Effective color source: explicit color group > swimlane group
         const effectiveColorKey = (currentActiveGroup ?? currentSwimlaneGroup)?.toLowerCase() ?? null;
@@ -4238,6 +4252,13 @@ export function renderTimeline(
 
         let cx = (width - totalW) / 2;
 
+        // Legend container for data-legend-active attribute
+        const legendContainer = mainSvg.append('g')
+          .attr('class', 'tl-tag-legend-container');
+        if (currentActiveGroup) {
+          legendContainer.attr('data-legend-active', currentActiveGroup.toLowerCase());
+        }
+
         for (const lg of visibleGroups) {
           const groupKey = lg.group.name.toLowerCase();
           const isActive = viewMode ||
@@ -4249,7 +4270,7 @@ export function renderTimeline(
           const pillLabel = lg.group.name;
           const pillWidth = pillLabel.length * LG_PILL_FONT_W + LG_PILL_PAD;
 
-          const gEl = mainSvg
+          const gEl = legendContainer
             .append('g')
             .attr('transform', `translate(${cx}, ${legendY})`)
             .attr('class', 'tl-tag-legend-group tl-tag-legend-entry')
@@ -5781,7 +5802,7 @@ export async function renderForExport(
     hiddenAttributes?: Set<string>;
     swimlaneTagGroup?: string | null;
   },
-  options?: { branding?: boolean; c4Level?: 'context' | 'containers' | 'components' | 'deployment'; c4System?: string; c4Container?: string; scenario?: string }
+  options?: { branding?: boolean; c4Level?: 'context' | 'containers' | 'components' | 'deployment'; c4System?: string; c4Container?: string; tagGroup?: string }
 ): Promise<string> {
   // Flowchart and org chart use their own parser pipelines — intercept before parseVisualization()
   const { parseDgmoChartType } = await import('./dgmo-router');
@@ -5801,7 +5822,7 @@ export async function renderForExport(
 
     // Apply interactive collapse state when provided
     const collapsedNodes = orgExportState?.collapsedNodes;
-    const activeTagGroup = orgExportState?.activeTagGroup ?? null;
+    const activeTagGroup = orgExportState?.activeTagGroup ?? options?.tagGroup ?? null;
     const hiddenAttributes = orgExportState?.hiddenAttributes;
 
     const { parsed: effectiveParsed, hiddenCounts } =
@@ -5841,7 +5862,7 @@ export async function renderForExport(
 
     // Apply interactive collapse state when provided
     const collapsedNodes = orgExportState?.collapsedNodes;
-    const activeTagGroup = orgExportState?.activeTagGroup ?? null;
+    const activeTagGroup = orgExportState?.activeTagGroup ?? options?.tagGroup ?? null;
     const hiddenAttributes = orgExportState?.hiddenAttributes;
 
     const { parsed: effectiveParsed, hiddenCounts } =
@@ -5881,7 +5902,7 @@ export async function renderForExport(
     container.style.left = '-9999px';
     document.body.appendChild(container);
 
-    renderKanban(container, kanbanParsed, effectivePalette, theme === 'dark');
+    renderKanban(container, kanbanParsed, effectivePalette, theme === 'dark', undefined, undefined, options?.tagGroup);
     return finalizeSvgExport(container, theme, effectivePalette, options);
   }
 
@@ -5921,7 +5942,7 @@ export async function renderForExport(
     const exportHeight = erLayout.height + PADDING * 2 + titleOffset;
     const container = createExportContainer(exportWidth, exportHeight);
 
-    renderERDiagram(container, erParsed, erLayout, effectivePalette, theme === 'dark', undefined, { width: exportWidth, height: exportHeight });
+    renderERDiagram(container, erParsed, erLayout, effectivePalette, theme === 'dark', undefined, { width: exportWidth, height: exportHeight }, options?.tagGroup);
     return finalizeSvgExport(container, theme, effectivePalette, options);
   }
 
@@ -5979,7 +6000,7 @@ export async function renderForExport(
       ? renderC4Containers
       : renderC4Context;
 
-    renderFn(container, c4Parsed, c4Layout, effectivePalette, theme === 'dark', undefined, { width: exportWidth, height: exportHeight });
+    renderFn(container, c4Parsed, c4Layout, effectivePalette, theme === 'dark', undefined, { width: exportWidth, height: exportHeight }, options?.tagGroup);
     return finalizeSvgExport(container, theme, effectivePalette, options);
   }
 
@@ -6009,11 +6030,9 @@ export async function renderForExport(
     const infraParsed = parseInfra(content);
     if (infraParsed.error || infraParsed.nodes.length === 0) return '';
 
-    const selectedScenario = options?.scenario
-      ? infraParsed.scenarios.find((s) => s.name.toLowerCase() === options.scenario!.toLowerCase()) ?? null
-      : null;
-    const infraComputed = computeInfra(infraParsed, selectedScenario ? { scenario: selectedScenario } : {});
+    const infraComputed = computeInfra(infraParsed);
     const infraLayout = layoutInfra(infraComputed);
+    const activeTagGroup = options?.tagGroup ?? null;
 
     const titleOffset = infraParsed.title ? 40 : 0;
     const legendGroups = computeInfraLegendGroups(infraLayout.nodes, infraParsed.tagGroups, effectivePalette);
@@ -6022,7 +6041,7 @@ export async function renderForExport(
     const exportHeight = infraLayout.height + titleOffset + legendOffset;
     const container = createExportContainer(exportWidth, exportHeight);
 
-    renderInfra(container, infraLayout, effectivePalette, theme === 'dark', infraParsed.title, infraParsed.titleLineNumber, infraParsed.tagGroups, null, false, null, null, true);
+    renderInfra(container, infraLayout, effectivePalette, theme === 'dark', infraParsed.title, infraParsed.titleLineNumber, infraParsed.tagGroups, activeTagGroup, false, null, null, true);
     // Restore explicit pixel dimensions for resvg (renderer uses 100%/viewBox for app scaling)
     const infraSvg = container.querySelector('svg');
     if (infraSvg) {
@@ -6079,6 +6098,7 @@ export async function renderForExport(
     if (seqParsed.error || seqParsed.participants.length === 0) return '';
     renderSequenceDiagram(container, seqParsed, effectivePalette, isDark, undefined, {
       exportWidth: EXPORT_WIDTH,
+      activeTagGroup: options?.tagGroup,
     });
   } else if (parsed.type === 'wordcloud') {
     await renderWordCloudAsync(container, parsed, effectivePalette, isDark, dims);
@@ -6086,7 +6106,7 @@ export async function renderForExport(
     renderArcDiagram(container, parsed, effectivePalette, isDark, undefined, dims);
   } else if (parsed.type === 'timeline') {
     renderTimeline(container, parsed, effectivePalette, isDark, undefined, dims,
-      orgExportState?.activeTagGroup, orgExportState?.swimlaneTagGroup);
+      orgExportState?.activeTagGroup ?? options?.tagGroup, orgExportState?.swimlaneTagGroup);
   } else if (parsed.type === 'venn') {
     renderVenn(container, parsed, effectivePalette, isDark, undefined, dims);
   } else if (parsed.type === 'quadrant') {

package/src/echarts.ts

@@ -1323,7 +1323,7 @@ function makeGridAxis(
   data?: string[],
   nameGapOverride?: number,
   chartWidthHint?: number,
-  intervalOverride?: (index: number, value: string) => boolean
+  intervalOverride?: number
 ): Record<string, unknown> {
   const defaultGap = type === 'value' ? 75 : 40;
 
@@ -1333,13 +1333,17 @@ function makeGridAxis(
   if (type === 'category' && data && data.length > 0) {
     const maxLabelLen = Math.max(...data.map((l) => l.length));
     const count = data.length;
+    // When interval skips labels, base sizing on visible count (≈ count / step)
+    const step = intervalOverride != null && intervalOverride > 0 ? intervalOverride + 1 : 1;
+    const visibleCount = Math.ceil(count / step);
     // Reduce font size based on density and label length
-    if (count > 10 || maxLabelLen > 20) catFontSize = 10;
-    else if (count > 5 || maxLabelLen > 14) catFontSize = 11;
+    if (visibleCount > 10 || maxLabelLen > 20) catFontSize = 10;
+    else if (visibleCount > 5 || maxLabelLen > 14) catFontSize = 11;
     else if (maxLabelLen > 8) catFontSize = 12;
 
-    // Constrain labels to their allotted slot width so ECharts wraps instead of hiding
-    if (chartWidthHint && count > 0) {
+    // Constrain labels to their allotted slot width so ECharts wraps instead of hiding.
+    // Skip when interval > 0 — visible labels are spread out and need no constraint.
+    if ((intervalOverride == null || intervalOverride === 0) && chartWidthHint && count > 0) {
       const availPerLabel = Math.floor((chartWidthHint * 0.85) / count);
       catLabelExtras = {
         width: availPerLabel,
@@ -1358,6 +1362,9 @@ function makeGridAxis(
       fontFamily: FONT_FAMILY,
       ...(type === 'category' && {
         interval: intervalOverride ?? 0,
+        // Prevent ECharts auto-rotation: it measures raw slot width (chartWidth/N),
+        // which is too narrow when an interval skips most labels, and rotates to 90°.
+        rotate: 0,
         formatter: (value: string) =>
           value.replace(/([a-z])([A-Z])/g, '$1\n$2'),
         ...catLabelExtras,
@@ -1477,24 +1484,17 @@ function buildBarOption(
 
 // ── Era band helpers ──────────────────────────────────────────
 
-function buildIntervalCallback(
-  labels: string[],
-  eras: ChartEra[]
-): (index: number, value: string) => boolean {
+// Returns an integer interval for ECharts axisLabel.interval.
+// interval: N means show label at index 0, N+1, 2*(N+1), ...
+// For a desired step S we return S-1.
+// Targets ~5 visible labels — conservative enough to prevent ECharts stagger.
+function buildIntervalStep(labels: string[]): number {
   const count = labels.length;
-  if (count <= 8) return () => true; // show all; not `0` (ECharts auto ≠ show all)
-  const snapSteps = [1, 2, 4, 5, 10, 20, 25, 50];
-  const raw = Math.ceil(count / 8);
+  if (count <= 6) return 0; // show all
+  const snapSteps = [1, 2, 5, 10, 25, 50, 100];
+  const raw = Math.ceil(count / 5); // target ~5 visible labels
   const N = [...snapSteps].reverse().find((s) => s <= raw) ?? 1; // snap down
-  const pinned = new Set<number>();
-  for (let i = 0; i < count; i += N) pinned.add(i);
-  for (const era of eras) {
-    const si = labels.indexOf(era.start);
-    const ei = labels.indexOf(era.end);
-    if (si >= 0) pinned.add(si);
-    if (ei >= 0) pinned.add(ei);
-  }
-  return (index: number) => pinned.has(index);
+  return N - 1; // ECharts shows labels at indices 0, N, 2N, ...
 }
 
 function buildMarkArea(
@@ -1548,7 +1548,7 @@ function buildLineOption(
   const labels = parsed.data.map((d) => d.label);
   const values = parsed.data.map((d) => d.value);
   const eras = parsed.eras ?? [];
-  const interval = buildIntervalCallback(labels, eras);
+  const interval = buildIntervalStep(labels);
   const markArea = buildMarkArea(eras, labels, textColor, palette.colors.blue);
 
   return {
@@ -1595,7 +1595,7 @@ function buildMultiLineOption(
   const seriesNames = parsed.seriesNames ?? [];
   const labels = parsed.data.map((d) => d.label);
   const eras = parsed.eras ?? [];
-  const interval = buildIntervalCallback(labels, eras);
+  const interval = buildIntervalStep(labels);
   const markArea = buildMarkArea(eras, labels, textColor, palette.colors.blue);
 
   const series = seriesNames.map((name, idx) => {
@@ -1654,7 +1654,7 @@ function buildAreaOption(
   const labels = parsed.data.map((d) => d.label);
   const values = parsed.data.map((d) => d.value);
   const eras = parsed.eras ?? [];
-  const interval = buildIntervalCallback(labels, eras);
+  const interval = buildIntervalStep(labels);
   const markArea = buildMarkArea(eras, labels, textColor, palette.colors.blue);
 
   return {

package/src/er/classify.ts

@@ -0,0 +1,206 @@
+// ============================================================
+// ER Diagram Entity Classification
+// ============================================================
+//
+// Classifies each ER entity into a structural role using heuristics
+// derived from column constraints, FK patterns, relationship in-degree,
+// and naming conventions.
+//
+// Only used when no explicit colors or tag groups are defined.
+
+import type { ERTable, ERRelationship } from './types';
+import type { PaletteColors } from '../palettes/types';
+
+export type EntityRole =
+  | 'core'
+  | 'dependent'
+  | 'junction'
+  | 'ambiguous'
+  | 'lookup'
+  | 'hub'
+  | 'self-referential'
+  | 'unclassified';
+
+/** Maps each role to a key in PaletteColors['colors'] */
+export const ROLE_COLORS: Record<EntityRole, keyof PaletteColors['colors']> = {
+  core: 'green',
+  dependent: 'blue',
+  junction: 'red',
+  ambiguous: 'purple',
+  lookup: 'yellow',
+  hub: 'orange',
+  'self-referential': 'teal',
+  unclassified: 'gray',
+};
+
+/** Human-readable legend labels per role */
+export const ROLE_LABELS: Record<EntityRole, string> = {
+  core: 'Core entity',
+  dependent: 'Dependent',
+  junction: 'Junction / M:M',
+  ambiguous: 'Bridge',
+  lookup: 'Lookup / Reference',
+  hub: 'Hub',
+  'self-referential': 'Self-referential',
+  unclassified: 'Unclassified',
+};
+
+/** Stable display order for the semantic legend */
+export const ROLE_ORDER: EntityRole[] = [
+  'core',
+  'dependent',
+  'junction',
+  'ambiguous',
+  'lookup',
+  'hub',
+  'self-referential',
+  'unclassified',
+];
+
+const LOOKUP_NAME_SUFFIXES = ['_type', '_status', '_code', '_category'];
+
+/**
+ * Classify each ER entity into a structural role.
+ *
+ * Returns a Map of tableId → EntityRole.
+ * Pure logic — no palette or DOM dependencies.
+ */
+export function classifyEREntities(
+  tables: ERTable[],
+  relationships: ERRelationship[]
+): Map<string, EntityRole> {
+  const result = new Map<string, EntityRole>();
+  if (tables.length === 0) return result;
+
+  // ── Pre-compute graph metrics ─────────────────────────────────────────────
+
+  // indegreeMap: how many other tables have FK references pointing to this table.
+  // A table's indegree increments when it is on the exclusive '1' side of a 1:* or 1:?
+  // relationship. 1:1 relationships are skipped on both sides to avoid double-counting.
+  const indegreeMap: Record<string, number> = {};
+  for (const t of tables) indegreeMap[t.id] = 0;
+  for (const rel of relationships) {
+    if (rel.source === rel.target) continue; // skip self-loops
+    if (rel.cardinality.from === '1' && rel.cardinality.to !== '1') {
+      indegreeMap[rel.source] = (indegreeMap[rel.source] ?? 0) + 1;
+    }
+    if (rel.cardinality.to === '1' && rel.cardinality.from !== '1') {
+      indegreeMap[rel.target] = (indegreeMap[rel.target] ?? 0) + 1;
+    }
+  }
+
+  // mmParticipants: tables with '*' cardinality connecting to 2+ distinct other tables.
+  // Catches wide junction tables (e.g. with surrogate PKs) that the FK-ratio alone misses.
+  const tableStarNeighbors = new Map<string, Set<string>>();
+  for (const rel of relationships) {
+    if (rel.source === rel.target) continue;
+    if (rel.cardinality.from === '*') {
+      if (!tableStarNeighbors.has(rel.source)) tableStarNeighbors.set(rel.source, new Set());
+      tableStarNeighbors.get(rel.source)!.add(rel.target);
+    }
+    if (rel.cardinality.to === '*') {
+      if (!tableStarNeighbors.has(rel.target)) tableStarNeighbors.set(rel.target, new Set());
+      tableStarNeighbors.get(rel.target)!.add(rel.source);
+    }
+  }
+  const mmParticipants = new Set<string>();
+  for (const [id, neighbors] of tableStarNeighbors) {
+    if (neighbors.size >= 2) mmParticipants.add(id);
+  }
+
+  // Hub outlier statistics
+  const indegreeValues = Object.values(indegreeMap);
+  const mean = indegreeValues.reduce((a, b) => a + b, 0) / indegreeValues.length;
+  const variance = indegreeValues.reduce((a, b) => a + (b - mean) ** 2, 0) / indegreeValues.length;
+  const stddev = Math.sqrt(variance);
+
+  // Median indegree (for lookup detection: table must be referenced above-median)
+  const sorted = [...indegreeValues].sort((a, b) => a - b);
+  const median =
+    sorted.length % 2 === 0
+      ? (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2
+      : sorted[Math.floor(sorted.length / 2)];
+
+  // ── Per-table classification ──────────────────────────────────────────────
+
+  for (const table of tables) {
+    const id = table.id;
+    const cols = table.columns;
+    const fkCols = cols.filter((c) => c.constraints.includes('fk'));
+    const pkFkCols = cols.filter(
+      (c) => c.constraints.includes('pk') && c.constraints.includes('fk')
+    );
+    const fkCount = fkCols.length;
+    const fkRatio = cols.length === 0 ? 0 : fkCount / cols.length;
+    const indegree = indegreeMap[id] ?? 0;
+    const nameLower = table.name.toLowerCase();
+
+    // External relationships (exclude self-loops)
+    const externalRels = relationships.filter(
+      (r) => (r.source === id || r.target === id) && r.source !== r.target
+    );
+    const hasSelfRef = relationships.some((r) => r.source === id && r.target === id);
+
+    // Distinct external tables this table relates to
+    const externalTargets = new Set<string>();
+    for (const rel of externalRels) {
+      externalTargets.add(rel.source === id ? rel.target : rel.source);
+    }
+
+    // ── Decision tree (priority order) ─────────────────────────────────────
+
+    // 1. Self-referential: has a self-loop relationship AND no external relationships
+    if (hasSelfRef && externalRels.length === 0) {
+      result.set(id, 'self-referential');
+      continue;
+    }
+
+    // 2. Junction: any one of three signals qualifies.
+    //    Inheritance exception: composite PK FKs all pointing to a single parent → skip ratio signal.
+    const isInheritancePattern = pkFkCols.length >= 2 && externalTargets.size === 1;
+    const junctionByRatio = fkRatio >= 0.6 && !isInheritancePattern;
+    const junctionByCompositePk = pkFkCols.length >= 2 && externalTargets.size >= 2;
+    const junctionByMm = mmParticipants.has(id);
+    if (junctionByRatio || junctionByCompositePk || junctionByMm) {
+      result.set(id, 'junction');
+      continue;
+    }
+
+    // 3. Ambiguous: FK ratio 0.4–0.59, no composite PK FKs, not M:M participant
+    if (fkRatio >= 0.4 && fkRatio < 0.6 && pkFkCols.length < 2 && !mmParticipants.has(id)) {
+      result.set(id, 'ambiguous');
+      continue;
+    }
+
+    // 4. Lookup: naming convention match + structural guards
+    //    Naming only applies when cols ≤ 6 AND fkCount ≤ 1; structure overrides for larger tables.
+    const nameMatchesLookup = LOOKUP_NAME_SUFFIXES.some((s) => nameLower.endsWith(s));
+    if (nameMatchesLookup && cols.length <= 6 && fkCount <= 1 && indegree > median) {
+      result.set(id, 'lookup');
+      continue;
+    }
+
+    // 5. Hub: in-degree outlier in a schema of ≥ 6 tables.
+    //    Dual condition: > mean + 1.5σ AND ≥ 2× mean (guards against near-zero mean edge cases).
+    if (
+      tables.length >= 6 &&
+      indegree > 0 &&
+      indegree > mean + 1.5 * stddev &&
+      indegree >= 2 * mean
+    ) {
+      result.set(id, 'hub');
+      continue;
+    }
+
+    // 6. Dependent: has FK columns
+    if (fkCount > 0) {
+      result.set(id, 'dependent');
+      continue;
+    }
+
+    // 7. Core: no FK columns (always true at this point)
+    result.set(id, 'core');
+  }
+
+  return result;
+}