@diagrammo/dgmo 0.4.1 → 0.4.3

package/src/sitemap/types.ts

@@ -0,0 +1,42 @@
+// ============================================================
+// Sitemap Diagram Types
+// ============================================================
+
+import type { DgmoError } from '../diagnostics';
+import type { TagGroup } from '../utils/tag-groups';
+
+export interface SitemapNode {
+  id: string;
+  label: string;
+  metadata: Record<string, string>;
+  children: SitemapNode[];
+  parentId: string | null;
+  /** True for [Group Name] container nodes */
+  isContainer: boolean;
+  lineNumber: number;
+  color?: string;
+}
+
+export interface SitemapEdge {
+  sourceId: string;
+  targetId: string;
+  label?: string;
+  color?: string;
+  lineNumber: number;
+}
+
+export type SitemapDirection = 'TB' | 'LR';
+
+export interface ParsedSitemap {
+  title: string | null;
+  titleLineNumber: number | null;
+  direction: SitemapDirection;
+  /** Top-level nodes (roots of the hierarchy) */
+  roots: SitemapNode[];
+  /** All cross-link edges */
+  edges: SitemapEdge[];
+  tagGroups: TagGroup[];
+  options: Record<string, string>;
+  diagnostics: DgmoError[];
+  error: string | null;
+}

package/src/utils/tag-groups.ts

@@ -49,6 +49,125 @@ export function isTagBlockHeading(trimmed: string): boolean {
  * Parse a tag block heading line into structured data.
  * Returns `null` if the line is not a tag block heading.
  */
+// ── Tag Resolution ────────────────────────────────────────
+
+/**
+ * Resolve a tag color for an entity given its metadata, available tag groups,
+ * and the currently active group.
+ *
+ * Returns the hex color from the matching tag entry, `'#999999'` for
+ * untagged/unknown values, or `undefined` when no group is active.
+ *
+ * @param metadata  The entity's key-value metadata (keys already lowercased)
+ * @param tagGroups All declared tag groups
+ * @param activeGroupName The currently selected tag group (null = no group active)
+ * @param isContainer When true, `defaultValue` is NOT applied (containers are structural, not data)
+ */
+export function resolveTagColor(
+  metadata: Record<string, string>,
+  tagGroups: TagGroup[],
+  activeGroupName: string | null,
+  isContainer?: boolean
+): string | undefined {
+  if (!activeGroupName) return undefined;
+
+  const group = tagGroups.find(
+    (g) => g.name.toLowerCase() === activeGroupName.toLowerCase()
+  );
+  if (!group) return undefined;
+
+  const metaValue =
+    metadata[group.name.toLowerCase()] ??
+    (isContainer ? undefined : group.defaultValue);
+  if (!metaValue) return '#999999';
+
+  return (
+    group.entries.find(
+      (e) => e.value.toLowerCase() === metaValue.toLowerCase()
+    )?.color ?? '#999999'
+  );
+}
+
+// ── Tag Validation ────────────────────────────────────────
+
+/**
+ * Validate tag metadata values on a collection of entities against declared
+ * tag groups. Emits warnings (via `pushWarning`) for unknown values with
+ * did-you-mean suggestions.
+ *
+ * @param entities  Objects with `metadata` and `lineNumber`
+ * @param tagGroups Declared tag groups to validate against
+ * @param pushWarning Callback to emit a warning at a given line
+ * @param suggestFn Optional did-you-mean suggestion function
+ */
+export function validateTagValues(
+  entities: ReadonlyArray<{ metadata: Record<string, string>; lineNumber: number }>,
+  tagGroups: ReadonlyArray<TagGroup>,
+  pushWarning: (lineNumber: number, message: string) => void,
+  suggestFn?: (input: string, candidates: readonly string[]) => string | null
+): void {
+  if (tagGroups.length === 0) return;
+
+  const groupMap = new Map<string, TagGroup>();
+  for (const g of tagGroups) groupMap.set(g.name.toLowerCase(), g);
+
+  for (const entity of entities) {
+    for (const [key, value] of Object.entries(entity.metadata)) {
+      const group = groupMap.get(key);
+      if (!group) continue;
+      const match = group.entries.some(
+        (e) => e.value.toLowerCase() === value.toLowerCase()
+      );
+      if (!match) {
+        const defined = group.entries.map((e) => e.value);
+        let msg = `Unknown value '${value}' for tag group '${group.name}'`;
+        const hint = suggestFn?.(value, defined);
+        if (hint) {
+          msg += `. ${hint}`;
+        } else {
+          msg += ` — defined values: ${defined.join(', ')}`;
+        }
+        pushWarning(entity.lineNumber, msg);
+      }
+    }
+  }
+}
+
+// ── Default Metadata Injection ────────────────────────────
+
+/**
+ * Inject default tag group values into entity metadata.
+ * Only sets keys not already present. Idempotent.
+ *
+ * @param entities  Objects with mutable `metadata`
+ * @param tagGroups Tag groups (only those with `defaultValue` matter)
+ * @param skip Optional predicate — entities matching this are skipped (e.g. containers)
+ */
+export function injectDefaultTagMetadata(
+  entities: Array<{ metadata: Record<string, string> }>,
+  tagGroups: ReadonlyArray<TagGroup>,
+  skip?: (entity: { metadata: Record<string, string> }) => boolean
+): void {
+  const defaults: { key: string; value: string }[] = [];
+  for (const group of tagGroups) {
+    if (group.defaultValue) {
+      defaults.push({ key: group.name.toLowerCase(), value: group.defaultValue });
+    }
+  }
+  if (defaults.length === 0) return;
+
+  for (const entity of entities) {
+    if (skip?.(entity)) continue;
+    for (const { key, value } of defaults) {
+      if (!(key in entity.metadata)) {
+        entity.metadata[key] = value;
+      }
+    }
+  }
+}
+
+// ── Matchers ────────────────────────────────────────────────
+
 export function matchTagBlockHeading(trimmed: string): TagBlockMatch | null {
   // Try new syntax first
   const tagMatch = trimmed.match(TAG_BLOCK_RE);