@diagrammo/dgmo 0.34.0 → 0.35.0

package/src/cycle/parser.ts

@@ -352,7 +352,10 @@ export function parseCycle(content: string): ParsedCycle {
       }
 
       // Indented line with no context
-      warn(lineNum, `Unexpected indented line: "${trimmed}".`);
+      warn(
+        lineNum,
+        `Indented line "${trimmed}" has no step above it — add a step on a non-indented line first, then indent its details. (§21)`
+      );
       continue;
     }
   }

package/src/dgmo-router.ts

@@ -14,7 +14,7 @@ import { looksLikePert } from './pert/parser';
 // part of the derived chartTypeParsers, which come from the registry).
 import { parseVisualization } from './visualizations/parse';
 import { parseFirstLine } from './utils/parsing';
-import { makeDgmoError, suggest } from './diagnostics';
+import { makeDgmoError, suggest, dedupeDiagnostics } from './diagnostics';
 import type { DgmoError } from './diagnostics';
 import { chartTypes } from './chart-types';
 import {
@@ -145,7 +145,7 @@ export function getAllChartTypes(): string[] {
 /**
  * Canonical descriptions for every supported chart type. Derived from
  * `chartTypes` so there is exactly one place to update when adding a new
- * type. Consumed by the CLI `--chart-types` flag, the editor autocomplete
+ * type. Consumed by the CLI `dgmo types` command, the editor autocomplete
  * popup, and the MCP `list_chart_types` tool.
  */
 export const CHART_TYPE_DESCRIPTIONS: Record<string, string> =
@@ -185,6 +185,20 @@ const ALL_KNOWN_TYPES: ReadonlySet<string> = new Set(knownChartTypeIds);
 export function parseDgmo(content: string): {
   diagnostics: DgmoError[];
   chartType: string | null;
+} {
+  // Dedupe at the parse boundary so one offending line never reports the same
+  // problem N times — keeps the fix-loop signal clean for the CLI, the editor,
+  // and the MCP `validate_diagram` tool.
+  const result = parseDgmoUndeduped(content);
+  return {
+    diagnostics: dedupeDiagnostics(result.diagnostics),
+    chartType: result.chartType,
+  };
+}
+
+function parseDgmoUndeduped(content: string): {
+  diagnostics: DgmoError[];
+  chartType: string | null;
 } {
   const chartType = parseDgmoChartType(content);
 

package/src/echarts.ts

@@ -964,7 +964,11 @@ function parseExtendedChartFull(
 
     // Catch-all: nothing matched this line
     result.diagnostics.push(
-      makeDgmoError(lineNumber, `Unexpected line: '${trimmed}'.`, 'warning')
+      makeDgmoError(
+        lineNumber,
+        `Unexpected line: '${trimmed}'. Expected a data row ('Label value', space-separated) or a known option.`,
+        'warning'
+      )
     );
   }
 

package/src/er/parser.ts

@@ -572,7 +572,11 @@ export function parseERDiagram(
 
     // Catch-all: nothing matched this line
     result.diagnostics.push(
-      makeDgmoError(lineNumber, `Unexpected line: '${trimmed}'.`, 'warning')
+      makeDgmoError(
+        lineNumber,
+        `Unexpected line: '${trimmed}'. A table is a bare name at indent 0 ('users'); columns are indented and SPACE-separated, no colon ('id int pk'); relationships are indented ('1--* orders'). (§9)`,
+        'warning'
+      )
     );
   }
 

package/src/gantt/parser.ts

@@ -382,7 +382,10 @@ export function parseGantt(
         // Skip comments inside holidays
         if (COMMENT_RE.test(line)) continue;
 
-        warn(lineNumber, `Unrecognized holiday entry: "${line}"`);
+        warn(
+          lineNumber,
+          `Unrecognized holiday entry: "${line}". Use a date '2024-02-19 Presidents Day' or a range '2024-05-27 -> 2024-05-29 Memorial Weekend'. (§13.3)`
+        );
         continue;
       }
     }
@@ -413,7 +416,10 @@ export function parseGantt(
             lineNumber,
           });
         } else {
-          warn(lineNumber, `Unrecognized era entry: "${line}"`);
+          warn(
+            lineNumber,
+            `Unrecognized era entry: "${line}". Use 'YYYY-MM-DD -> YYYY-MM-DD Label [color]' (e.g. '2026-04-06 -> 2026-04-10 Conference purple'). (§13.5)`
+          );
         }
         continue;
       }
@@ -444,7 +450,10 @@ export function parseGantt(
             lineNumber,
           });
         } else {
-          warn(lineNumber, `Unrecognized marker entry: "${line}"`);
+          warn(
+            lineNumber,
+            `Unrecognized marker entry: "${line}". Use 'YYYY-MM-DD Label [color]' (e.g. '2026-03-27 Board Review' or '2026-06-15 Release green'). (§13.6)`
+          );
         }
         continue;
       }
@@ -664,7 +673,7 @@ export function parseGantt(
           } else {
             softError(
               lineNumber,
-              `Arrow reference "${content.name}" has no parent task context.`
+              `Arrow '-> ${content.name}' has no source task — indent it under the task it follows (e.g. 'Design 5bd' then indented '-> ${content.name} 3bd'). (§13)`
             );
           }
         }

package/src/graph/flowchart-parser.ts

@@ -629,7 +629,11 @@ export function parseFlowchart(
 
         if (key === 'no-color') {
           result.diagnostics.push(
-            makeDgmoError(lineNumber, '"no-color" has been removed.', 'warning')
+            makeDgmoError(
+              lineNumber,
+              '"no-color" was removed — node colors are assigned automatically by shape; delete this line.',
+              'warning'
+            )
           );
           continue;
         }

package/src/graph/state-parser.ts

@@ -389,7 +389,11 @@ export function parseState(
 
         if (key === 'no-color') {
           result.diagnostics.push(
-            makeDgmoError(lineNumber, '"no-color" has been removed.', 'warning')
+            makeDgmoError(
+              lineNumber,
+              '"no-color" was removed — state colors are assigned automatically; delete this line.',
+              'warning'
+            )
           );
           continue;
         }

package/src/infra/parser.ts

@@ -560,7 +560,7 @@ export function parseInfra(content: string): ParsedInfra {
       }
       warn(
         lineNumber,
-        `Invalid tag value '${trimmed}' in tag group '${currentTagGroup.name}'.`
+        `Invalid tag value '${trimmed}' in tag group '${currentTagGroup.name}' — a value is a bare word with an optional trailing color (e.g. 'Production red'); no ':' or '|'.`
       );
       continue;
     }
@@ -654,7 +654,7 @@ export function parseInfra(content: string): ParsedInfra {
         const n = deprecatedFanout[1];
         setError(
           lineNumber,
-          `'x${n}' fanout syntax is no longer supported — use '| fanout: ${n}' instead`
+          `'x${n}' fanout syntax is no longer supported — use 'fanout: ${n}' instead`
         );
         continue;
       }
@@ -869,8 +869,12 @@ export function parseInfra(content: string): ParsedInfra {
           const valueLooksNumeric = /^[\d.]+%?$/.test(rawVal);
           if (hint || valueLooksNumeric) {
             // Likely a typo — warn
-            let msg = `Unknown property '${key}'.`;
+            let msg = `Unknown infra property '${key}'.`;
             if (hint) msg += ` ${hint}`;
+            else
+              msg +=
+                ` Properties are colon-keyed 'key: value' from the known schema` +
+                ` (e.g. latency-ms, max-rps, cache-hit, instances, concurrency).`;
             warn(lineNumber, msg);
           } else if (!currentNode.isEdge) {
             // Likely prose — collect as description
@@ -884,7 +888,7 @@ export function parseInfra(content: string): ParsedInfra {
         if (EDGE_ONLY_KEYS.has(key) && !currentNode.isEdge) {
           warn(
             lineNumber,
-            `Property '${key}' is only valid on the entry point (Edge/Internet).`
+            `Property '${key}' belongs on the entry point — declare it indented under an 'internet' or 'edge' node, not on '${currentNode.label}'.`
           );
         }
 
@@ -1014,8 +1018,8 @@ export function parseInfra(content: string): ParsedInfra {
     warn(
       lineNumber,
       currentGroup
-        ? `Unexpected line: '${trimmed}'. Expected an indented component name.`
-        : `Unexpected line: '${trimmed}'. Expected a component name, [Group Name], tag group, or option.`
+        ? `Unexpected line: '${trimmed}'. Inside a group, indent a component name under the '[Group]'.`
+        : `Unexpected line: '${trimmed}'. Expected a node ('Api Gateway'), a group ('[Backend]'), a tag group ('tag Tier as t'), or an option ('default-rps 100'); node properties go indented under a node as 'key: value'.`
     );
   }
 

package/src/journey-map/parser.ts

@@ -378,7 +378,7 @@ export function parseJourneyMap(
       if (trimmed.includes('|') || !PHASE_RE.test(trimmed)) {
         warn(
           lineNumber,
-          'Steps outside phases will be ignored when phases are present'
+          `Step "${trimmed}" sits outside any phase and is ignored — indent it under a '[Phase]' header (per §22).`
         );
         continue;
       }
@@ -450,7 +450,10 @@ export function parseJourneyMap(
 
     // Unrecognized line
     if (indent > 0 && !currentPhase && hasPhases) {
-      warn(lineNumber, `Unexpected indented line outside of a phase`);
+      warn(
+        lineNumber,
+        `Indented line outside any phase — add a '[Phase]' header above it, or unindent it to a top-level step. (§22)`
+      );
     }
   }
 

package/src/kanban/parser.ts

@@ -58,7 +58,8 @@ const KNOWN_OPTIONS = new Set(['hide', 'active-tag']);
 /** Known kanban boolean options (bare keyword = on). */
 const KNOWN_BOOLEANS = new Set<string>(['solid-fill', 'no-title']);
 const REMOVED_BOOLEANS: Record<string, string> = {
-  'no-auto-color': '"no-auto-color" has been removed.',
+  'no-auto-color':
+    '"no-auto-color" was removed — colors are always auto-assigned from the palette; delete this line.',
 };
 
 // ============================================================
@@ -364,7 +365,10 @@ export function parseKanban(
     }
 
     if (!currentColumn) {
-      warn(lineNumber, 'Card line found before any column');
+      warn(
+        lineNumber,
+        'Card line found before any column. Declare a column first with \'[Column Name]\', then indent cards beneath it. (§11)'
+      );
       continue;
     }
 

package/src/map/context-labels.ts

@@ -51,6 +51,14 @@ export interface ContextLabelArgs {
   readonly height: number;
   readonly waterBodies?: WaterBodies | undefined;
   readonly countries: readonly CountryCandidate[];
+  /** Muted, contrast-floored land tone for country labels — computed in layout
+   *  against the neutral basemap and shared with the orientation backdrop so a
+   *  context country and an orientation region read identically. Absent ⇒ the
+   *  legacy `palette.textMuted`. */
+  readonly countryTone?: string | undefined;
+  /** Muted, contrast-floored tone for water labels (against the water fill).
+   *  Absent ⇒ the legacy `mix(blue, textMuted, 50)`. */
+  readonly waterTone?: string | undefined;
   readonly palette: PaletteColors;
   readonly project: (lon: number, lat: number) => [number, number] | null;
   /** Collision test against every committed data/region/POI/route obstacle. */
@@ -80,15 +88,15 @@ const EDGE_CLAMP_MARGIN = 8; // px inset for edge-clamped ocean labels
 const EDGE_CLAMP_OVERSHOOT = 0.35; // max off-frame overshoot (× dim) to still clamp
 
 // Country labels scale with their projected footprint: a big landmass (Canada,
-// Mexico on a US view) reads as a large, FADED backdrop name; a small one stays
-// at the base font, fully muted. Size metric is the footprint's linear extent
-// (√bbox-area) as a fraction of the canvas's linear extent (√canvas-area), so
-// the ramp is resolution-independent. Below MIN ⇒ base font / no extra fade;
-// at/above MAX ⇒ max font / max fade; linear between.
+// Mexico on a US view) reads as a larger backdrop name; a small one stays at the
+// base font. Size metric is the footprint's linear extent (√bbox-area) as a
+// fraction of the canvas's linear extent (√canvas-area), so the ramp is
+// resolution-independent. Below MIN ⇒ base font; at/above MAX ⇒ max font; linear
+// between. Colour does NOT change with size — subordination is by muting (the
+// contrast-floored tone) + size only, never by fading toward bg (Phase 1).
 const COUNTRY_FONT_MAX = 22; // px ceiling for the largest footprint
 const COUNTRY_SIZE_FRAC_MIN = 0.06; // footprint linear-frac at base font
 const COUNTRY_SIZE_FRAC_MAX = 0.32; // footprint linear-frac at max font
-const COUNTRY_FADE_MAX = 45; // % blend toward bg at max font (subdue big names)
 
 // Multi-position country dodging (map-context-neighbor-labels). A country gets
 // several interior on-its-own-land positions so its label can dodge a colliding
@@ -287,6 +295,8 @@ export function placeContextLabels(args: ContextLabelArgs): PlacedLabel[] {
     waterBodies,
     countries,
     palette,
+    countryTone,
+    waterTone,
     project,
     collides,
     contentPoints,
@@ -306,10 +316,14 @@ export function placeContextLabels(args: ContextLabelArgs): PlacedLabel[] {
   const budget = labelBudget(width, height, band);
   if (budget <= 0) return [];
 
-  // Subordinate cartographic colours (palette-derived, no hex; resvg-safe via
-  // pre-computed mix()). Water = muted blue-gray italic; country = muted gray.
-  const waterColor = mix(palette.colors.blue, palette.textMuted, 50);
-  const countryColor = palette.textMuted;
+  // Subordinate cartographic colours. Both are muted but CONTRAST-FLOORED in the
+  // caller (layout) against the substrate they sit on, and shared with the
+  // orientation backdrop so a context country and an orientation region match.
+  // Water stays the blue-gray italic convention; country = the muted land tone.
+  // Fallbacks keep the pre-floor behaviour for unit tests that omit the tones.
+  const waterColor =
+    waterTone ?? mix(palette.colors.blue, palette.textMuted, 50);
+  const countryColor = countryTone ?? palette.textMuted;
   const haloColor = palette.bg;
 
   type Candidate = {
@@ -475,15 +489,11 @@ export function placeContextLabels(args: ContextLabelArgs): PlacedLabel[] {
       )
     );
     const fontSize = Math.round(FONT + t * (COUNTRY_FONT_MAX - FONT));
-    const fade = Math.round(t * COUNTRY_FADE_MAX);
-    // Blend `fade`% TOWARD the bg (subdue big names). `mix(a,b,pct)` weights `a` by
-    // `pct`, so the bg fraction must be `100 - fade` — i.e. a small country (fade≈0)
-    // stays fully muted/dark and only a big landmass fades to a soft backdrop. (The
-    // earlier `mix(countryColor, bg, fade)` was inverted: it lightened the SMALL
-    // names toward white instead, which read as illegible once proximity started
-    // surfacing small neighbours like Belarus/Georgia.)
-    const color =
-      fade > 0 ? mix(countryColor, palette.bg, 100 - fade) : countryColor;
+    // No fade. Subordination is by MUTING (the floored tone) + smaller size, not
+    // by fading toward bg — fading a floored tone toward the background would
+    // re-break the contrast it was floored to guarantee (the old behaviour washed
+    // big names like Canada toward illegibility). Footprint still drives font size.
+    const color = countryColor;
     // Always the full country name — never an ISO abbreviation. If the name
     // doesn't fit the footprint, drop the label rather than abbreviate.
     const text = c.name;