storymaps 1.2.3 → 1.2.5

package/lib/core/constants.js

@@ -21,6 +21,28 @@ export const isValidUrl = (url) => {
     }
 };
 
+// Slice goal and target date are optional. The date is stored as YYYY-MM-DD; YAML can parse an
+// unquoted date as a Date, so accept that too. Anything else is dropped.
+export const SLICE_GOAL_MAX_LENGTH = 200;
+
+export const normalizeSliceGoal = (value) =>
+    typeof value === 'string' ? value.trim().slice(0, SLICE_GOAL_MAX_LENGTH) : '';
+
+export const normalizeSliceDate = (value) => {
+    if (value instanceof Date && !isNaN(value)) return value.toISOString().slice(0, 10);
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return '';
+    return isNaN(new Date(`${value}T00:00:00Z`)) ? '' : value;
+};
+
+// Copies a slice's goal and target date from one object to another, leaving out empty values
+export const copySliceDetails = (from, to) => {
+    const goal = normalizeSliceGoal(from.goal);
+    const targetDate = normalizeSliceDate(from.targetDate);
+    if (goal) to.goal = goal;
+    if (targetDate) to.targetDate = targetDate;
+    return to;
+};
+
 export const CARD_COLORS = {
     red: '#fca5a5',
     rose: '#fecdd3',

package/lib/core/yaml.js

@@ -2,7 +2,7 @@
 // YAML ↔ JSON transform + validation
 
 import jsyaml from 'js-yaml';
-import { generateId } from './constants.js';
+import { generateId, copySliceDetails } from './constants.js';
 
 const DEFAULT_STEP_COLOR = '#86efac';
 const DEFAULT_STORY_COLOR = '#fef08a';
@@ -54,10 +54,12 @@ export function jsonToYamlObj(data) {
         partialSlugMap[pm.id] = slugify(pm.name) || pm.id;
     });
 
-    // Classify each step
-    const stepTypes = steps.map(step => {
+    // Classify each step. A hidden step with a name or cards is written as a normal step so its
+    // cards survive (only empty, unnamed hidden steps are spacers).
+    const hasCards = (i) => !!(usersArr[i]?.length || activitiesArr[i]?.length || slices.some(s => s.stories?.[i]?.length));
+    const stepTypes = steps.map((step, i) => {
         if (step.partialMapId) return 'partial';
-        if (step.hidden) return 'spacer';
+        if (step.hidden && !step.name && !hasCards(i)) return 'spacer';
         return 'step';
     });
 
@@ -70,42 +72,18 @@ export function jsonToYamlObj(data) {
     });
     const duplicateNames = new Set(Object.keys(nameCounts).filter(n => nameCounts[n] > 1));
 
-    // Resolve names — namespace duplicates with nearest activity/user
+    // Number duplicate names (Confirm[0], Confirm[1]) so cards point at the right step.
+    // Import strips the number, so the names come back unchanged.
+    const counters = {};
     const resolvedNames = steps.map((step, i) => {
         if (stepTypes[i] !== 'step') return null;
         const name = step.name || '';
         if (!duplicateNames.has(name)) return name;
-        for (let j = i; j >= 0; j--) {
-            if (activitiesArr[j]?.length) return `${activitiesArr[j][0].name}: ${name}`;
-        }
-        for (let j = i; j >= 0; j--) {
-            if (usersArr[j]?.length) return `${usersArr[j][0].name}: ${name}`;
-        }
-        return name;
+        const idx = counters[name] || 0;
+        counters[name] = idx + 1;
+        return `${name}[${idx}]`;
     });
 
-    // Second pass: add :[N] suffix to any still-duplicate resolved names
-    const resolvedCounts = {};
-    resolvedNames.forEach(n => {
-        if (n != null) resolvedCounts[n] = (resolvedCounts[n] || 0) + 1;
-    });
-    const stillDuplicate = new Set(Object.keys(resolvedCounts).filter(n => resolvedCounts[n] > 1));
-    if (stillDuplicate.size) {
-        const counters = {};
-        for (let i = 0; i < resolvedNames.length; i++) {
-            const n = resolvedNames[i];
-            if (n == null || !stillDuplicate.has(n)) continue;
-            const idx = counters[n] || 0;
-            counters[n] = idx + 1;
-            const colonPos = n.indexOf(': ');
-            if (colonPos >= 0) {
-                resolvedNames[i] = n.slice(0, colonPos + 1) + `[${idx}]` + n.slice(colonPos + 1);
-            } else {
-                resolvedNames[i] = `${n}[${idx}]`;
-            }
-        }
-    }
-
     // Build YAML object
     const result = {};
     result.name = data.name || '';
@@ -175,14 +153,16 @@ export function jsonToYamlObj(data) {
         if (stepTypes[i] === 'partial') return { partial: partialSlugMap[step.partialMapId] };
         const name = resolvedNames[i];
         const hasExtra = (step.color && step.color !== DEFAULT_STEP_COLOR)
-            || step.url || step.body || step.points != null;
+            || step.body || step.url || step.status || step.points != null || step.tags?.length;
         if (!hasExtra) return name;
-        const obj = { name };
-        if (step.color && step.color !== DEFAULT_STEP_COLOR) obj.color = step.color;
-        if (step.body) obj.body = step.body;
-        if (step.url) obj.url = step.url;
-        if (step.points != null) obj.points = step.points;
-        return obj;
+        const s = { name };
+        if (step.color && step.color !== DEFAULT_STEP_COLOR) s.color = step.color;
+        if (step.body) s.body = step.body;
+        if (step.url) s.url = step.url;
+        if (step.status) s.status = step.status;
+        if (step.points != null) s.points = step.points;
+        if (step.tags?.length) s.tags = step.tags;
+        return s;
     });
 
     // Legend
@@ -194,6 +174,7 @@ export function jsonToYamlObj(data) {
             const obj = { name: slice.name || '' };
             if (slice.collapsed) obj.collapsed = true;
             if (slice.closedReason) obj.closedReason = slice.closedReason;
+            copySliceDetails(slice, obj);
             const stories = {};
             (slice.stories || []).forEach((cards, i) => {
                 if (!cards?.length) return;
@@ -271,6 +252,7 @@ export function validateYaml(obj) {
         const label = slice.name || `#${si}`;
         if (slice.stories) {
             for (const [stepName, cards] of Object.entries(slice.stories)) {
+                if (!stepName) continue;
                 if (!stepNameSet.has(stepName)) {
                     errors.push(`Slice "${label}" references unknown step "${stepName}"`);
                 }
@@ -330,9 +312,11 @@ export function yamlObjToJson(obj) {
         stepNameToIndex[rawName] = jsonSteps.length;
         const s = { name: displayName, color };
         if (typeof step === 'object' && step !== null) {
-            if (step.url) s.url = step.url;
             if (step.body) s.body = step.body;
+            if (step.url) s.url = step.url;
+            if (step.status) s.status = step.status;
             if (step.points != null) s.points = step.points;
+            if (step.tags?.length) s.tags = step.tags;
         }
         jsonSteps.push(s);
     });
@@ -364,6 +348,7 @@ export function yamlObjToJson(obj) {
         const s = { name: slice.name || '', stories };
         if (slice.collapsed) s.collapsed = true;
         if (slice.closedReason) s.closedReason = slice.closedReason;
+        copySliceDetails(slice, s);
         return s;
     });
 
@@ -422,7 +407,8 @@ export function yamlObjToJson(obj) {
     };
 
     if (obj.legend?.length) result.legend = obj.legend;
-    if (obj.notes) result.notes = obj.notes;
+    // Keep empty notes so a push with notes: "" clears them (no notes key leaves them alone)
+    if (typeof obj.notes === 'string') result.notes = obj.notes;
     if (jsonPartialMaps.length) result.partialMaps = jsonPartialMaps;
     if (obj.backups?.length) result.backups = obj.backups;
     return result;
@@ -442,6 +428,10 @@ function backboneToYaml(positionalArr, namesByIndex) {
             const obj = { name: card.name };
             if (card.body) obj.body = card.body;
             if (card.color) obj.color = card.color;
+            if (card.status) obj.status = card.status;
+            if (card.points != null) obj.points = card.points;
+            if (card.tags?.length) obj.tags = [...card.tags];
+            if (card.url) obj.url = card.url;
             obj.step = stepName;
             result.push(obj);
         });

package/lib/util/api.js

@@ -10,9 +10,18 @@ class ApiError extends Error {
     }
 }
 
+// The server sends errors as JSON ({"error": "..."}), so show just the message
+function errorMessage(body) {
+    try {
+        return JSON.parse(body).error || body;
+    } catch {
+        return body;
+    }
+}
+
 async function handleResponse(res) {
     if (res.ok) return;
-    const body = await res.text().catch(() => '');
+    const body = errorMessage(await res.text().catch(() => ''));
     switch (res.status) {
         case 404: throw new ApiError('Map not found', 404);
         case 409: throw new ApiError(body || 'Conflict — the remote map has changed. Pull first or use --force.', 409, { conflict: true });

package/lib/util/summary.js

@@ -3,6 +3,115 @@
 
 import chalk from 'chalk';
 import jsyaml from 'js-yaml';
+import { normalizeSliceGoal, normalizeSliceDate } from '../core/constants.js';
+
+// Fields compared on cards and steps that exist on both sides
+const FIELDS = ['body', 'color', 'url', 'status', 'points', 'tags'];
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+// Slice names can span lines (e.g. "V1:\nBasic House"); keep each summary entry on one line
+const oneLine = (s) => String(s ?? '').replace(/\s*\n\s*/g, ' ');
+
+const changedFields = (a, b) =>
+    FIELDS.filter(f => JSON.stringify(a?.[f] ?? null) !== JSON.stringify(b?.[f] ?? null));
+
+// True when the names both lists share appear in a different order
+const reordered = (oldNames, newNames) => {
+    const common = oldNames.filter(n => newNames.includes(n));
+    const commonNew = newNames.filter(n => oldNames.includes(n));
+    return common.join('\n') !== commonNew.join('\n');
+};
+
+// Compare located cards ({ card, group, at }) across the whole map. Cards are
+// paired by name in order, so a card that changes slice or step counts as moved
+// rather than removed and added. Returns per-group summary lines.
+function compareCards(oldItems, newItems) {
+    const stats = new Map();
+    const statsFor = (group) => {
+        if (!stats.has(group)) stats.set(group, { added: 0, removed: 0, moved: 0, updated: 0, fields: new Set() });
+        return stats.get(group);
+    };
+    // Report groups in their new order, then any that only exist on the old side
+    newItems.forEach(i => statsFor(i.group));
+    oldItems.forEach(i => statsFor(i.group));
+
+    const byName = (items) => {
+        const map = new Map();
+        for (const item of items) {
+            const name = item.card?.name ?? '';
+            if (!map.has(name)) map.set(name, []);
+            map.get(name).push(item);
+        }
+        return map;
+    };
+    const oldByName = byName(oldItems);
+    const newByName = byName(newItems);
+
+    for (const name of new Set([...oldByName.keys(), ...newByName.keys()])) {
+        const o = oldByName.get(name) || [];
+        const c = newByName.get(name) || [];
+        const paired = Math.min(o.length, c.length);
+        for (let i = 0; i < paired; i++) {
+            const s = statsFor(c[i].group);
+            if (o[i].group !== c[i].group || o[i].at !== c[i].at) s.moved++;
+            const fields = changedFields(o[i].card, c[i].card);
+            if (fields.length) {
+                s.updated++;
+                fields.forEach(f => s.fields.add(f));
+            }
+        }
+        c.slice(paired).forEach(item => statsFor(item.group).added++);
+        o.slice(paired).forEach(item => statsFor(item.group).removed++);
+    }
+
+    const lines = [];
+    for (const [group, s] of stats) {
+        // Equal numbers of unmatched adds and removes means the cards were renamed
+        if (s.added && s.added === s.removed) {
+            lines.push(chalk.yellow(`  ~ ${oneLine(group)}: ${plural(s.added, 'card')} renamed`));
+        } else {
+            if (s.added) lines.push(chalk.green(`  + ${oneLine(group)}: ${plural(s.added, 'card')}`));
+            if (s.removed) lines.push(chalk.red(`  - ${oneLine(group)}: ${plural(s.removed, 'card')}`));
+        }
+        if (s.moved) lines.push(chalk.yellow(`  ~ ${oneLine(group)}: ${plural(s.moved, 'card')} moved`));
+        if (s.updated) {
+            lines.push(chalk.yellow(`  ~ ${oneLine(group)}: ${plural(s.updated, 'card')} updated (${[...s.fields].join(', ')})`));
+        }
+    }
+    return lines;
+}
+
+function compareLegend(oldLegend, newLegend) {
+    const lines = [];
+    const key = e => `${e?.color ?? ''}\n${e?.label ?? ''}`;
+    const removed = [...oldLegend];
+    const added = [];
+    for (const entry of newLegend) {
+        const i = removed.findIndex(e => key(e) === key(entry));
+        if (i >= 0) removed.splice(i, 1);
+        else added.push(entry);
+    }
+    // Same color with a new label is a rename; same label with a new color is a recolor
+    for (const entry of [...added]) {
+        let i = removed.findIndex(e => e.color === entry.color);
+        if (i >= 0) {
+            lines.push(chalk.yellow(`  ~ legend: ${removed[i].label} → ${entry.label}`));
+        } else if ((i = removed.findIndex(e => e.label === entry.label)) >= 0) {
+            lines.push(chalk.yellow(`  ~ legend: ${entry.label} color changed`));
+        } else {
+            continue;
+        }
+        removed.splice(i, 1);
+        added.splice(added.indexOf(entry), 1);
+    }
+    for (const e of added) lines.push(chalk.green(`  + legend: ${e.label}`));
+    for (const e of removed) lines.push(chalk.red(`  - legend: ${e.label}`));
+    if (!lines.length && reordered(oldLegend.map(key), newLegend.map(key))) {
+        lines.push(chalk.yellow('  ~ legend reordered'));
+    }
+    return lines;
+}
 
 export function changeSummary(oldYaml, newYaml) {
     const old = jsyaml.load(oldYaml);
@@ -15,13 +124,15 @@ export function changeSummary(oldYaml, newYaml) {
     }
 
     // Steps (skip spacers and partial refs)
-    const stepName = s => {
-        if (typeof s === 'string' && s !== 'spacer') return s;
-        if (typeof s === 'object' && s?.name) return s.name;
+    const toStep = s => {
+        if (typeof s === 'string' && s !== 'spacer') return { name: s };
+        if (typeof s === 'object' && s?.name) return s;
         return null;
     };
-    const oldSteps = (old.steps || []).map(stepName).filter(Boolean);
-    const newSteps = (cur.steps || []).map(stepName).filter(Boolean);
+    const oldStepObjs = (old.steps || []).map(toStep).filter(Boolean);
+    const newStepObjs = (cur.steps || []).map(toStep).filter(Boolean);
+    const oldSteps = oldStepObjs.map(s => s.name);
+    const newSteps = newStepObjs.map(s => s.name);
     const addedSteps = newSteps.filter(s => !oldSteps.includes(s));
     const removedSteps = oldSteps.filter(s => !newSteps.includes(s));
     if (addedSteps.length || removedSteps.length) {
@@ -31,55 +142,84 @@ export function changeSummary(oldYaml, newYaml) {
         for (const s of addedSteps) lines.push(chalk.green(`    + ${s}`));
         for (const s of removedSteps) lines.push(chalk.red(`    - ${s}`));
     }
+    if (reordered(oldSteps, newSteps)) lines.push(chalk.yellow('  ~ steps reordered'));
+    const stepFields = new Set();
+    let updatedSteps = 0;
+    for (const step of newStepObjs) {
+        const before = oldStepObjs.find(s => s.name === step.name);
+        if (!before) continue;
+        const fields = changedFields(before, step);
+        if (fields.length) {
+            updatedSteps++;
+            fields.forEach(f => stepFields.add(f));
+        }
+    }
+    if (updatedSteps) {
+        lines.push(chalk.yellow(`  ~ steps: ${plural(updatedSteps, 'step')} updated (${[...stepFields].join(', ')})`));
+    }
 
     // Slices
     const oldSlices = (old.slices || []).map(s => s.name);
     const newSlices = (cur.slices || []).map(s => s.name);
-    for (const s of newSlices.filter(s => !oldSlices.includes(s))) {
-        lines.push(chalk.green(`  + slice: ${s}`));
+    // A slice whose name changed in the same position is a rename, so its cards aren't reported as moved
+    const sliceRenames = new Map();
+    oldSlices.forEach((name, i) => {
+        const newName = newSlices[i];
+        if (newName !== undefined && !newSlices.includes(name) && !oldSlices.includes(newName)) {
+            sliceRenames.set(name, newName);
+        }
+    });
+    const currentName = name => sliceRenames.get(name) ?? name;
+    for (const [from, to] of sliceRenames) {
+        lines.push(chalk.yellow(`  ~ slice: ${oneLine(from)} → ${oneLine(to)}`));
+    }
+    const renamedTo = new Set(sliceRenames.values());
+    for (const s of newSlices.filter(s => !oldSlices.includes(s) && !renamedTo.has(s))) {
+        lines.push(chalk.green(`  + slice: ${oneLine(s)}`));
     }
-    for (const s of oldSlices.filter(s => !newSlices.includes(s))) {
-        lines.push(chalk.red(`  - slice: ${s}`));
+    for (const s of oldSlices.filter(s => !newSlices.includes(s) && !sliceRenames.has(s))) {
+        lines.push(chalk.red(`  - slice: ${oneLine(s)}`));
+    }
+    if (reordered(oldSlices.map(currentName), newSlices)) lines.push(chalk.yellow('  ~ slices reordered'));
+    for (const slice of cur.slices || []) {
+        const before = (old.slices || []).find(s => currentName(s.name) === slice.name);
+        if (!before) continue;
+        if (!!before.collapsed !== !!slice.collapsed || before.closedReason !== slice.closedReason) {
+            const state = !slice.collapsed ? 'reopened' : slice.closedReason === 'closed' ? 'closed' : 'completed';
+            lines.push(chalk.yellow(`  ~ slice: ${oneLine(slice.name)} ${state}`));
+        }
+        const [oldGoal, newGoal] = [normalizeSliceGoal(before.goal), normalizeSliceGoal(slice.goal)];
+        if (oldGoal !== newGoal) {
+            const change = !oldGoal ? 'set' : !newGoal ? 'removed' : 'changed';
+            lines.push(chalk.yellow(`  ~ slice: ${oneLine(slice.name)} goal ${change}`));
+        }
+        const [oldDate, newDate] = [normalizeSliceDate(before.targetDate), normalizeSliceDate(slice.targetDate)];
+        if (oldDate !== newDate) {
+            const change = !oldDate ? `set to ${newDate}` : !newDate ? 'removed' : `moved to ${newDate}`;
+            lines.push(chalk.yellow(`  ~ slice: ${oneLine(slice.name)} target date ${change}`));
+        }
     }
 
-    // Detect card-level changes per slice (name-aware, handles renames)
-    const collectCardNames = (map) => {
-        const result = {};
-        for (const slice of (map.slices || [])) {
-            const names = [];
-            for (const cards of Object.values(slice.stories || {})) {
-                if (Array.isArray(cards)) names.push(...cards.map(c => c.name).filter(Boolean));
+    // Cards: users, activities and stories in every slice
+    const collectCards = (map, sliceName) => {
+        const items = [];
+        for (const group of ['users', 'activities']) {
+            for (const card of map[group] || []) items.push({ card, group, at: card.step });
+        }
+        for (const slice of map.slices || []) {
+            const group = sliceName(slice.name);
+            for (const [step, cards] of Object.entries(slice.stories || {})) {
+                if (Array.isArray(cards)) cards.forEach(card => items.push({ card, group, at: step }));
             }
-            result[slice.name] = names;
         }
-        return result;
+        return items;
     };
-    const oldCards = collectCardNames(old);
-    const newCards = collectCardNames(cur);
-    for (const sliceName of new Set([...Object.keys(oldCards), ...Object.keys(newCards)])) {
-        const oldNames = oldCards[sliceName] || [];
-        const newNames = newCards[sliceName] || [];
-        const oldCounts = new Map();
-        const newCounts = new Map();
-        for (const n of oldNames) oldCounts.set(n, (oldCounts.get(n) || 0) + 1);
-        for (const n of newNames) newCounts.set(n, (newCounts.get(n) || 0) + 1);
-        const allNames = new Set([...oldCounts.keys(), ...newCounts.keys()]);
-        let added = 0, removed = 0;
-        for (const n of allNames) {
-            const o = oldCounts.get(n) || 0;
-            const c = newCounts.get(n) || 0;
-            if (c > o) added += c - o;
-            if (o > c) removed += o - c;
-        }
-        if (added === 0 && removed === 0) continue;
-        const net = newNames.length - oldNames.length;
-        if (net === 0) {
-            const word = added === 1 ? 'card' : 'cards';
-            lines.push(chalk.yellow(`  ~ ${sliceName}: ${added} ${word} renamed`));
-        } else {
-            if (added) lines.push(chalk.green(`  + ${sliceName}: ${added} ${added === 1 ? 'card' : 'cards'}`));
-            if (removed) lines.push(chalk.red(`  - ${sliceName}: ${removed} ${removed === 1 ? 'card' : 'cards'}`));
-        }
+    lines.push(...compareCards(collectCards(old, currentName), collectCards(cur, name => name)));
+
+    lines.push(...compareLegend(old.legend || [], cur.legend || []));
+
+    if (JSON.stringify(old.partials ?? null) !== JSON.stringify(cur.partials ?? null)) {
+        lines.push(chalk.yellow('  ~ partials updated'));
     }
 
     // Notes
@@ -96,9 +236,12 @@ export function changeSummary(oldYaml, newYaml) {
 
 export function printChangeSummary(oldYaml, newYaml) {
     const lines = changeSummary(oldYaml, newYaml);
-    if (lines.length === 0) {
+    if (lines.length) {
+        lines.forEach(l => console.log(l));
+    } else if (oldYaml === newYaml) {
         console.log(chalk.dim('No changes.'));
     } else {
-        lines.forEach(l => console.log(l));
+        // Something differs that the summary doesn't describe (e.g. card order within a step)
+        console.log(chalk.yellow(`  ~ changes not shown in summary, run ${chalk.cyan('storymaps diff --full')} to see them`));
     }
 }

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "storymaps",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "CLI tool for storymaps.io - import, export, validate, and manage user story maps from the terminal",
   "type": "module",
   "bin": {
     "storymaps": "./bin/storymaps.js"
   },
+  "scripts": {
+    "test": "node --test 'test/unit/**/*.test.js'",
+    "test:integration": "node --test 'test/integration/**/*.test.js'"
+  },
   "keywords": [
     "story-mapping",
     "user-story",