@diagrammo/dgmo 0.34.0 → 0.36.0

package/src/map/legend-band.ts

@@ -97,3 +97,31 @@ export function mapLegendBand(
     mapLegendTop(opts.hasTitle, opts.hasSubtitle) + height + LEGEND_BOTTOM_GAP
   );
 }
+
+/** The legend's actual centred bounding box (top-centre overlay), or null when no
+ *  legend is drawn. Used to feed the legend into the on-map label collision set so
+ *  a region / context name never lands under it. Mirrors `mapLegendBand` but keeps
+ *  the width + x rather than collapsing to a band height. */
+export function mapLegendBox(
+  legend: MapLayoutLegend | null,
+  opts: {
+    width: number;
+    mode: LegendMode;
+    hasTitle: boolean;
+    hasSubtitle: boolean;
+  }
+): { x: number; y: number; width: number; height: number } | null {
+  if (!legend) return null;
+  const groups = mapLegendGroups(legend);
+  if (groups.length === 0) return null;
+  const config = mapLegendConfig(groups, opts.mode);
+  const state: LegendState = { activeGroup: legend.activeGroup };
+  const { width, height } = computeLegendLayout(config, state, opts.width);
+  if (height <= 0 || width <= 0) return null;
+  return {
+    x: (opts.width - width) / 2,
+    y: mapLegendTop(opts.hasTitle, opts.hasSubtitle),
+    width,
+    height,
+  };
+}

package/src/map/parser.ts

@@ -369,7 +369,10 @@ export function parseMap(content: string, palette?: PaletteColors): ParsedMap {
   function handleTag(trimmed: string, line: number): void {
     const m = matchTagBlockHeading(trimmed);
     if (!m) {
-      pushError(line, `Malformed tag declaration: "${trimmed}".`);
+      pushError(
+        line,
+        `Malformed tag declaration: "${trimmed}" — write 'tag <Group>' (optionally 'tag <Group> as <alias>'), e.g. 'tag Market as m', with indented 'Value color' entries below.`
+      );
       return;
     }
     emitTagLegacyDiagnostic(m, line, diagnostics);
@@ -500,7 +503,7 @@ export function parseMap(content: string, palette?: PaletteColors): ParsedMap {
     if (!pos || (pos.kind === 'name' && !pos.name)) {
       pushError(
         line,
-        'route requires an origin: `route <origin> [style: arc]`.'
+        'route needs an origin place — `route <origin>` then indented legs (`-> dest`); origin may be a city name, IATA code, or `<lat> <lon>`. (§24B)'
       );
       return;
     }
@@ -579,7 +582,10 @@ export function parseMap(content: string, palette?: PaletteColors): ParsedMap {
     const parts = trimmed.split(ARROW_SPLIT);
     // parts = [ep0, tok0, ep1, tok1, ep2, ...]
     if (parts.length < 3) {
-      pushError(line, `Malformed edge: "${trimmed}".`);
+      pushError(
+        line,
+        `Malformed edge: "${trimmed}" — an edge is 'A -> B' (or 'A -label-> B', '~>' for arc, '--' undirected), both endpoints non-empty. (§24B)`
+      );
       return;
     }
     const endpoints: string[] = [];
@@ -609,7 +615,10 @@ export function parseMap(content: string, palette?: PaletteColors): ParsedMap {
       const from = endpoints[k]!;
       const to = endpoints[k + 1]!;
       if (!from || !to) {
-        pushError(line, `Edge has an empty endpoint: "${trimmed}".`);
+        pushError(
+          line,
+          `Edge has an empty endpoint: "${trimmed}" — both sides of the arrow need a place, e.g. 'Paris -> Berlin'. (§24B)`
+        );
         continue;
       }
       const isLast = k === links.length - 1;

package/src/map/renderer.ts

@@ -136,7 +136,8 @@ function coastlineOuterRings(
   const paths: string[] = [];
   for (const r of regions) {
     // Reuse the rings parsed once in layoutMap; fall back for older layouts.
-    const rings = (r.rings as Array<Array<[number, number]>>) ?? parsePathRings(r.d);
+    const rings =
+      (r.rings as Array<Array<[number, number]>>) ?? parsePathRings(r.d);
     for (let i = 0; i < rings.length; i++) {
       const ring = rings[i]!;
       if (ring.length < 3) continue;
@@ -684,10 +685,7 @@ export function renderMap(
       for (const r of layout.regions) {
         // bbox is precomputed once in layoutMap (roadmap #2); fall back to
         // parsing only for layouts predating that field.
-        let minX: number,
-          minY: number,
-          maxX: number,
-          maxY: number;
+        let minX: number, minY: number, maxX: number, maxY: number;
         if (r.bbox) {
           [minX, minY, maxX, maxY] = r.bbox;
         } else {
@@ -898,10 +896,67 @@ export function renderMap(
     .append('g')
     .attr('class', 'dgmo-map-legs')
     .attr('fill', 'none');
-  layout.legs.forEach((leg, i) => {
+  // Parse a single-segment leg path (`M…L…` or `M…Q…`) into its end point and the
+  // unit tangent arriving there. Returns null for anything unexpected (then the
+  // leg renders without the trimmed-arrow treatment).
+  const legEnd = (
+    d: string
+  ): { ex: number; ey: number; tx: number; ty: number } | null => {
+    const m =
+      /^M(-?[\d.]+),(-?[\d.]+)(?:L(-?[\d.]+),(-?[\d.]+)|Q(-?[\d.]+),(-?[\d.]+) (-?[\d.]+),(-?[\d.]+))$/.exec(
+        d
+      );
+    if (!m) return null;
+    const x0 = +m[1]!;
+    const y0 = +m[2]!;
+    let ex: number;
+    let ey: number;
+    let fromX: number;
+    let fromY: number;
+    if (m[3] !== undefined) {
+      ex = +m[3]!;
+      ey = +m[4]!;
+      fromX = x0;
+      fromY = y0;
+    } else {
+      ex = +m[7]!;
+      ey = +m[8]!;
+      fromX = +m[5]!; // quadratic control → tangent at the end
+      fromY = +m[6]!;
+    }
+    const dx = ex - fromX;
+    const dy = ey - fromY;
+    const len = Math.hypot(dx, dy);
+    if (!(len > 0)) return null;
+    return { ex, ey, tx: dx / len, ty: dy / len };
+  };
+  layout.legs.forEach((leg) => {
+    // A directed leg's stroke is TRIMMED back to the arrowhead base so a heavy
+    // weighted line doesn't run through (and bulge past) the narrowing arrowhead.
+    // The arrowhead itself is drawn as a filled triangle at the true endpoint,
+    // sized to always be a touch wider than the stroke so the stroke end is fully
+    // covered. Undirected (or unparseable) legs keep the full path.
+    const end = leg.arrow ? legEnd(leg.d) : null;
+    let drawD = leg.d;
+    let arrowTri: string | null = null;
+    if (end) {
+      const aLen = arrowSize(leg.width); // arrow depth along the line
+      const aHalf = Math.max(aLen * 0.5, leg.width * 0.6 + 1); // half base ≥ stroke
+      const bx = end.ex - end.tx * aLen; // base centre
+      const by = end.ey - end.ty * aLen;
+      const px = -end.ty; // perpendicular
+      const py = end.tx;
+      arrowTri = `M${bx + px * aHalf},${by + py * aHalf}L${end.ex},${end.ey}L${bx - px * aHalf},${by - py * aHalf}z`;
+      // Re-point the stroke's end at the arrow base (small along-tangent shift; for
+      // an arc leg the negligible end-curvature change is hidden by the arrowhead).
+      drawD = leg.d.replace(
+        /(-?[\d.]+),(-?[\d.]+)$/,
+        `${bx.toFixed(2)},${by.toFixed(2)}`
+      );
+    }
     const p = gLegs
       .append('path')
-      .attr('d', leg.d)
+      .attr('d', drawD)
       .attr('stroke', leg.color)
       .attr('stroke-width', leg.width)
       .attr('stroke-linecap', 'round')
@@ -918,23 +973,19 @@ export function renderMap(
     // A 0-width invisible leg path is hard to hit; pointer-events on the visible
     // stroke is enough for the line widths legs use.
     wireSync(p, leg.lineNumber);
-    if (leg.arrow) {
-      const id = nid(`dgmo-map-arrow-${i}`);
-      const s = arrowSize(leg.width);
-      defs
-        .append('marker')
-        .attr('id', id)
-        .attr('viewBox', '0 0 10 10')
-        .attr('refX', 10)
-        .attr('refY', 5)
-        .attr('markerUnits', 'userSpaceOnUse')
-        .attr('markerWidth', s)
-        .attr('markerHeight', s)
-        .attr('orient', 'auto-start-reverse')
+    if (arrowTri) {
+      // Filled arrowhead at the true endpoint — a flat triangle whose base sits
+      // where the trimmed stroke ends, so the line meets it cleanly with no
+      // show-through. Round join keeps the tip from looking spiky on thin legs.
+      gLegs
         .append('path')
-        .attr('d', 'M0,0L10,5L0,10z')
-        .attr('fill', leg.color);
-      p.attr('marker-end', `url(#${id})`);
+        .attr('d', arrowTri)
+        .attr('fill', leg.color)
+        .attr('stroke', leg.color)
+        .attr('stroke-width', 1)
+        .attr('stroke-linejoin', 'round')
+        .attr('data-from-id', leg.fromId)
+        .attr('data-to-id', leg.toId);
     }
     if (leg.label !== undefined && leg.labelX !== undefined) {
       // Text shade is contrast-picked in layout against the fill under the label

package/src/map/resolver.ts

@@ -420,7 +420,7 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
       const hint = suggest(r.name, allNames);
       err(
         r.lineNumber,
-        `Unknown subdivision "${r.name}".${hint ? ' ' + hint : ''}`,
+        `Unknown region "${r.name}" — not a known country or US state.${hint ? ' ' + hint : ''} Search the exact token with \`dgmo map-search "${r.name}"\` (or the lookup_map_location tool), use an ISO code (e.g. FR, US-CA), or coordinates.`,
         'E_MAP_UNKNOWN_SUBDIVISION'
       );
       continue;
@@ -527,7 +527,7 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
       const hint = suggest(name, cityNames);
       err(
         line,
-        `Unknown place "${name}" (not in the gazetteer; use coordinates).${hint ? ' ' + hint : ''}`,
+        `Unknown place "${name}" — not in the gazetteer.${hint ? ' ' + hint : ''} Search the exact token with \`dgmo map-search "${name}"\` (or the lookup_map_location tool), or use coordinates \`poi <lat> <lon>\`.`,
         'E_MAP_UNKNOWN_PLACE'
       );
       return { kind: 'miss' };

package/src/org/parser.ts

@@ -342,7 +342,10 @@ export function parseOrg(content: string, palette?: PaletteColors): ParsedOrg {
       // Find the parent node: top of stack (the most recent node)
       const parent = findMetadataParent(indent, indentStack);
       if (!parent) {
-        pushError(lineNumber, 'Metadata has no parent node');
+        pushError(
+          lineNumber,
+          "Metadata 'key: value' must be indented under a node — no node precedes it."
+        );
       } else {
         parent.metadata = { ...parent.metadata, [key]: value };
       }
@@ -364,7 +367,10 @@ export function parseOrg(content: string, palette?: PaletteColors): ParsedOrg {
         );
         attachNode(node, indent, indentStack, result);
       } else {
-        pushError(lineNumber, 'Metadata has no parent node');
+        pushError(
+          lineNumber,
+          "Metadata 'key: value' must be indented under a node — no node precedes it."
+        );
       }
     } else {
       // It's a node label — possibly with single-line metadata

package/src/pyramid/parser.ts

@@ -193,7 +193,10 @@ export function parsePyramid(content: string): ParsedPyramid {
 
     // ── Indented: description line under current layer ──
     if (!currentLayer) {
-      warn(lineNum, `Unexpected indented line: "${trimmed}".`);
+      warn(
+        lineNum,
+        `Indented description "${trimmed}" has no layer above it — add a layer name on a non-indented line first. (§23)`
+      );
       continue;
     }
     const descLine = trimmed.startsWith('- ')

package/src/raci/parser.ts

@@ -706,7 +706,10 @@ export function parseRaci(
 
     // ── Catch-all: stray content line in body ────────────────────
     if (bodyStarted) {
-      errorAt(lineNumber, `Unexpected line: '${trimmed}'.`);
+      errorAt(
+        lineNumber,
+        `Unexpected line: '${trimmed}'. In the body expect a '[Phase]' header, an indented task name, or an assignment 'Role: A R C I' under a task. (§24A)`
+      );
     } else {
       // Pre-body unrecognized line — likely a typo'd directive. Tolerate
       // by emitting a warning rather than failing the whole parse.

package/src/ring/parser.ts

@@ -205,7 +205,10 @@ export function parseRing(content: string): ParsedRing {
 
     // ── Indented: description line under current layer ──
     if (!currentLayer) {
-      warn(lineNum, `Unexpected indented line: "${trimmed}".`);
+      warn(
+        lineNum,
+        `Indented description "${trimmed}" has no layer above it — add a layer name on a non-indented line first. (§24)`
+      );
       continue;
     }
     const descLine = trimmed.startsWith('- ')

package/src/sequence/parser.ts

@@ -878,10 +878,13 @@ export function parseSequenceDgmo(
           .trim()
           .replace(/\([^)]*\)$/, '')
           .trim();
-        const metaPart = rawInside.substring(pipeIdx).trim();
+        const metaPart = rawInside
+          .substring(pipeIdx)
+          .replace(/^\|\s*/, '')
+          .trim();
         pushError(
           lineNumber,
-          `Pipe metadata must go outside brackets — use '[${cleanName}] ${metaPart}' instead of '[${rawInside.trim()}]'`
+          `Metadata goes after the bracket with no pipe — use '[${cleanName}] ${metaPart}' (e.g. '[Backend] t: Product'), not '[${rawInside.trim()}]'`
         );
         continue;
       }
@@ -1676,7 +1679,7 @@ export function parseSequenceDgmo(
     // Catch-all: nothing matched this line
     pushWarning(
       lineNumber,
-      `Unexpected line: '${trimmed}'. Expected a message (A -> B), participant, section (== Name ==), or block keyword (if/loop/parallel).`
+      `Unexpected line: '${trimmed}'. Expected a message ('A -> B' or 'A -label-> B'), participant ('Name' or 'Name is a actor'), note ('note right of A Text'), section ('== Name =='), or block ('if/loop/parallel <label>').`
     );
   }
 

package/src/sitemap/parser.ts

@@ -363,7 +363,10 @@ export function parseSitemap(
       // at a shallower indent (same pattern as metadata attachment)
       const source = findParentNode(indent, indentStack);
       if (!source) {
-        pushError(lineNumber, 'Arrow has no source node');
+        pushError(
+          lineNumber,
+          "Arrow '-> target' must be indented under its source page — no page precedes it."
+        );
       } else {
         deferredArrows.push({
           sourceNode: source,
@@ -455,7 +458,10 @@ export function parseSitemap(
 
       const parent = findParentNode(indent, indentStack);
       if (!parent) {
-        pushError(lineNumber, 'Metadata has no parent node');
+        pushError(
+          lineNumber,
+          "Metadata 'key: value' must be indented under a page — no page precedes it."
+        );
       } else {
         parent.metadata = { ...parent.metadata, [key]: value };
       }
@@ -476,7 +482,10 @@ export function parseSitemap(
         const key = normalizeName(node.label);
         labelToNode.set(key, node);
       } else {
-        pushError(lineNumber, 'Metadata has no parent node');
+        pushError(
+          lineNumber,
+          "Metadata 'key: value' must be indented under a page — no page precedes it."
+        );
       }
     } else {
       // Check if this is a description line for a parent node

package/src/tech-radar/parser.ts

@@ -144,7 +144,10 @@ export function parseTechRadar(content: string): ParsedTechRadar {
     // --- Rings block ---
     if (indent === 0 && trimmed.toLowerCase() === 'rings') {
       if (result.rings.length > 0) {
-        warn(lineNumber, 'Duplicate "rings" block — using last one');
+        warn(
+          lineNumber,
+          'Duplicate "rings" block — only the last is kept; merge all ring names into one "rings" block.'
+        );
         result.rings = [];
       }
       inRingsBlock = true;
@@ -410,7 +413,7 @@ export function parseTechRadar(content: string): ParsedTechRadar {
       result.diagnostics.push(
         makeDgmoError(
           lineNumber,
-          `Blip "${trimmed}" has no ring assignment. Place it under a ring section header or use: ${trimmed} | ring: RingName`
+          `Blip "${trimmed}" has no ring. Put it under a ring section header, or add a colon-keyed ring — '${trimmed} ring: RingName' (per §20).`
         )
       );
       continue;
@@ -421,7 +424,7 @@ export function parseTechRadar(content: string): ParsedTechRadar {
       if (!trimmed.includes('|') && headerParsed && result.rings.length > 0) {
         warn(
           lineNumber,
-          `Unrecognized line "${trimmed}". Quadrant headers require pipe metadata: ${trimmed} | quadrant: top-left`
+          `Unrecognized line "${trimmed}". A quadrant header is 'Name quadrant: <top-left|top-right|bottom-left|bottom-right>' (per §20).`
         );
       }
     }

package/src/utils/parsing.ts

@@ -564,9 +564,9 @@ export function peelRampColors(label: string): {
   return { label: second.rest, low: second.color, high: first.color };
 }
 
-/** Error message for multiple pipes on a single line. */
+/** Error message for stray pipe(s) where metadata used to go (0.18.0 removed `|`). */
 export const MULTIPLE_PIPE_ERROR =
-  'Use a single "|" to start metadata, then separate items with commas.';
+  "'|' is no longer metadata syntax — put metadata on the same line as 'key: value, key2: value2' (no pipes), per §1.4.";
 
 /**
  * Parse metadata from segments after the first (name) segment.

package/src/utils/tag-groups.ts

@@ -524,12 +524,12 @@ export function validateTagValues(
         );
         if (!isPrefix) {
           const defined = group.entries.map((e) => e.value);
-          let msg = `Unknown value '${value}' for tag group '${group.name}'`;
+          let msg =
+            `Unknown value '${value}' for tag group '${group.name}' — ` +
+            `use one of: ${defined.join(', ')}`;
           const hint = suggestFn?.(value, defined);
           if (hint) {
             msg += `. ${hint}`;
-          } else {
-            msg += ` — defined values: ${defined.join(', ')}`;
           }
           pushWarning(entity.lineNumber, msg);
         }

package/src/visualizations/parse.ts

@@ -452,7 +452,10 @@ function parseVisualizationFull(
             lineNumber,
           });
         } else {
-          warn(lineNumber, `Unrecognized era entry: "${line}"`);
+          warn(
+            lineNumber,
+            `Unrecognized era entry: "${line}" — use '<start> -> <end> Label [color]' (e.g. '1716 -> 1717 Reign').`
+          );
         }
         continue;
       }
@@ -486,7 +489,10 @@ function parseVisualizationFull(
             lineNumber,
           });
         } else {
-          warn(lineNumber, `Unrecognized marker entry: "${line}"`);
+          warn(
+            lineNumber,
+            `Unrecognized marker entry: "${line}" — use '<date> Label [color]' (e.g. '1776 Independence').`
+          );
         }
         continue;
       }
@@ -1411,7 +1417,7 @@ function parseVisualizationFull(
           result.diagnostics.push(
             makeDgmoError(
               ov.lineNumber,
-              `Intersection references unknown set or alias "${ref}"`
+              `Intersection references unknown set or alias "${ref}" — declare the set first on its own line ('Name [as <alias>] [color]', e.g. 'Navigation as nav blue'), then reference it by that name or alias. (§16.4)`
             )
           );
           if (!result.error)

package/src/migrate/data-comma.ts

@@ -1,117 +0,0 @@
-// Data-row comma migration for the `dgmo migrate` tool.
-//
-// 1.0 freeze: data-chart value separators are space-only and thousands
-// commas are dropped (see `dgmo-language-spec-decisions.md` §"Silently-accepted
-// dual forms" — Comma-row reconciliation). This module rewrites the VALUE
-// region of a data-chart row, stripping value-separator and thousands commas
-// while leaving everything else (label, trailing color word, arrow source/
-// target, alias) byte-identical.
-//
-// Surgery, not re-parse: we never reconstruct the line from parsed values, so
-// colors, aliases, and arrow endpoints survive verbatim. We only touch the
-// trailing run of numeric value tokens.
-
-import { RECOGNIZED_COLOR_NAMES } from '../colors';
-
-/** Data-chart types whose rows carry comma-separable numeric values. */
-export const DATA_COMMA_CHART_TYPES = new Set<string>([
-  // Simple charts (chart.ts)
-  'bar',
-  'line',
-  'multi-line',
-  'pie',
-  'doughnut',
-  'area',
-  'polar-area',
-  'radar',
-  'bar-stacked',
-  // Extended charts (echarts.ts)
-  'scatter',
-  'heatmap',
-  'sankey',
-  'chord',
-  'funnel',
-  // Visualizations (d3 / visualizations/parse.ts)
-  'quadrant',
-  'slope',
-  'arc',
-  'wordcloud',
-]);
-
-const COLOR_SET = new Set<string>(RECOGNIZED_COLOR_NAMES);
-
-/**
- * A token that is a numeric value, optionally carrying comma/underscore digit
- * grouping. Accepts an optional leading `-`, optional trailing comma (the
- * separator glued to the value, e.g. `400,`), and decimals.
- */
-const NUMERIC_VALUE_RE = /^-?\d[\d,_]*(?:\.\d+)?,?$/;
-
-/** True iff `tok` is a bare numeric value token (modulo grouping/separators). */
-function isNumericValueToken(tok: string): boolean {
-  if (!NUMERIC_VALUE_RE.test(tok)) return false;
-  // Must contain at least one digit (guards against `,` alone).
-  return /\d/.test(tok);
-}
-
-/**
- * Rewrite the value region of a single data-chart row, removing value-separator
- * and thousands commas. Returns the comma-free line plus whether it changed.
- * Lines without a comma in the value region are returned unchanged.
- *
- * The value region is the maximal trailing run of numeric value tokens
- * (whitespace-separated, each optionally comma-grouped or comma-suffixed),
- * optionally preceded — for the trailing-color-after-value forms — by nothing
- * (a trailing color word sits AFTER values and is preserved verbatim because it
- * is not numeric and stops the scan from the right).
- */
-export function migrateDataRowCommaLine(line: string): {
-  line: string;
-  changed: boolean;
-} {
-  // Preserve exact leading indentation.
-  const indentMatch = line.match(/^[ \t]*/);
-  const indent = indentMatch ? indentMatch[0] : '';
-  const body = line.substring(indent.length);
-  if (!body || body.startsWith('//')) return { line, changed: false };
-
-  // Split into whitespace tokens, keeping a simple structure. Commas may be
-  // glued to tokens (`400,`) or stand between number tokens after a comma-split
-  // — we normalize by splitting on whitespace then handling glued commas.
-  const tokens = body.split(/\s+/);
-  if (tokens.length < 2) return { line, changed: false };
-
-  // Walk from the right collecting the value region. A trailing color word is
-  // allowed as the very last token (sankey link color / data-point color) and
-  // is kept verbatim — we resume value collection before it.
-  let i = tokens.length - 1;
-
-  // Peel an optional trailing color word (kept as-is, not a value).
-  if (i >= 1 && COLOR_SET.has(tokens[i]!)) {
-    i--;
-  }
-
-  const valueStart = ((): number => {
-    let j = i;
-    while (j >= 1 && isNumericValueToken(tokens[j]!)) j--;
-    return j + 1; // first value-token index
-  })();
-
-  // No value region (need at least one numeric token, and a label before it).
-  if (valueStart > i || valueStart < 1) return { line, changed: false };
-
-  // The value tokens are tokens[valueStart..i]. Detect any comma among them.
-  const valueTokens = tokens.slice(valueStart, i + 1);
-  const hasComma = valueTokens.some((t) => t.includes(','));
-  if (!hasComma) return { line, changed: false };
-
-  // Strip commas: each numeric token loses its thousands/separator commas.
-  // A token like `400,` → `400`; `1,000` → `1000`; `1,234.56` → `1234.56`.
-  const cleaned = valueTokens.map((t) => t.replace(/,/g, ''));
-
-  // Rebuild: label (tokens before valueStart) + cleaned values + verbatim tail.
-  const labelPart = tokens.slice(0, valueStart);
-  const tail = tokens.slice(i + 1); // trailing color word(s), verbatim
-  const rebuiltBody = [...labelPart, ...cleaned, ...tail].join(' ');
-  return { line: indent + rebuiltBody, changed: rebuiltBody !== body };
-}