@basementuniverse/kanbn 1.0.0 → 1.1.0

package/src/controller/add.js

@@ -23,10 +23,15 @@ async function interactiveCreateTask(taskData, taskIds, columnName, columnNames)
     'due' in taskData.metadata &&
     taskData.metadata.due != null
   );
-  const postponedDateExists = (
+  const plannedStartDateExists = (
     'metadata' in taskData &&
-    'postponed' in taskData.metadata &&
-    taskData.metadata.postponed != null
+    'plannedStart' in taskData.metadata &&
+    taskData.metadata.plannedStart != null
+  );
+  const plannedFinishDateExists = (
+    'metadata' in taskData &&
+    'plannedFinish' in taskData.metadata &&
+    taskData.metadata.plannedFinish != null
   );
   const assignedExists = (
     'metadata' in taskData &&
@@ -83,18 +88,33 @@ async function interactiveCreateTask(taskData, taskIds, columnName, columnNames)
     },
     {
       type: 'confirm',
-      name: 'setPostponed',
-      message: 'Set a postponed date?',
+      name: 'setPlannedStart',
+      message: 'Set a planned start date?',
       default: false,
-      when: answers => !postponedDateExists
+      when: answers => !plannedStartDateExists
     },
     {
       type: 'datepicker',
-      name: 'postponed',
-      message: 'Postponed date:',
-      default: postponedDateExists ? taskData.metadata.postponed : new Date(),
+      name: 'plannedStart',
+      message: 'Planned start date:',
+      default: plannedStartDateExists ? taskData.metadata.plannedStart : new Date(),
       format: ['Y', '/', 'MM', '/', 'DD'],
-      when: answers => answers.setPostponed,
+      when: answers => answers.setPlannedStart,
+    },
+    {
+      type: 'confirm',
+      name: 'setPlannedFinish',
+      message: 'Set a planned finish date?',
+      default: false,
+      when: answers => !plannedFinishDateExists
+    },
+    {
+      type: 'datepicker',
+      name: 'plannedFinish',
+      message: 'Planned finish date:',
+      default: plannedFinishDateExists ? taskData.metadata.plannedFinish : new Date(),
+      format: ['Y', '/', 'MM', '/', 'DD'],
+      when: answers => answers.setPlannedFinish,
     },
     {
       type: 'confirm',
@@ -343,11 +363,20 @@ module.exports = async args => {
     }
   }
 
-  // Postponed date
-  if (args.postponed) {
-    taskData.metadata.postponed = chrono.parseDate(utility.strArg(args.postponed));
-    if (taskData.metadata.postponed === null) {
-      utility.error('Unable to parse postponed date');
+  // Planned start date
+  if (args.plannedStart) {
+    taskData.metadata.plannedStart = chrono.parseDate(utility.strArg(args.plannedStart));
+    if (taskData.metadata.plannedStart === null) {
+      utility.error('Unable to parse plannedStart date');
+      return;
+    }
+  }
+
+  // Planned finish date
+  if (args.plannedFinish) {
+    taskData.metadata.plannedFinish = chrono.parseDate(utility.strArg(args.plannedFinish));
+    if (taskData.metadata.plannedFinish === null) {
+      utility.error('Unable to parse plannedFinish date');
       return;
     }
   }
@@ -481,8 +510,11 @@ module.exports = async args => {
       if ('due' in answers) {
         taskData.metadata.due = answers.due;
       }
-      if ('postponed' in answers) {
-        taskData.metadata.postponed = answers.postponed;
+      if ('plannedStart' in answers) {
+        taskData.metadata.plannedStart = answers.plannedStart;
+      }
+      if ('plannedFinish' in answers) {
+        taskData.metadata.plannedFinish = answers.plannedFinish;
       }
       if ('assigned' in answers) {
         taskData.metadata.assigned = answers.assigned;

package/src/controller/edit.js

@@ -23,10 +23,15 @@ async function interactive(taskData, taskIds, columnName, columnNames) {
     'due' in taskData.metadata &&
     taskData.metadata.due != null
   );
-  const postponedDateExists = (
+  const plannedStartDateExists = (
     'metadata' in taskData &&
-    'postponed' in taskData.metadata &&
-    taskData.metadata.postponed != null
+    'plannedStart' in taskData.metadata &&
+    taskData.metadata.plannedStart != null
+  );
+  const plannedFinishDateExists = (
+    'metadata' in taskData &&
+    'plannedFinish' in taskData.metadata &&
+    taskData.metadata.plannedFinish != null
   );
   const assignedExists = (
     'metadata' in taskData &&
@@ -108,10 +113,10 @@ async function interactive(taskData, taskIds, columnName, columnNames) {
     },
     {
       type: 'expand',
-      name: 'editPostponed',
-      message: 'Edit or remove postponed date?',
+      name: 'editPlannedStart',
+      message: 'Edit or remove planned start date?',
       default: 'none',
-      when: answers => postponedDateExists,
+      when: answers => plannedStartDateExists,
       choices: [
         {
           key: 'e',
@@ -133,18 +138,58 @@ async function interactive(taskData, taskIds, columnName, columnNames) {
     },
     {
       type: 'confirm',
-      name: 'setPostponed',
-      message: 'Set a postponed date?',
+      name: 'setPlannedStart',
+      message: 'Set a planned start date?',
       default: false,
-      when: answers => !postponedDateExists
+      when: answers => !plannedStartDateExists
     },
     {
       type: 'datepicker',
-      name: 'postponed',
-      message: 'Postponed date:',
-      default: postponedDateExists ? taskData.metadata.postponed : new Date(),
+      name: 'plannedStart',
+      message: 'Planned start date:',
+      default: plannedStartDateExists ? taskData.metadata.plannedStart : new Date(),
       format: ['Y', '/', 'MM', '/', 'DD'],
-      when: answers => answers.setPostponed || answers.editPostponed === 'edit'
+      when: answers => answers.setPlannedStart || answers.editPlannedStart === 'edit'
+    },
+    {
+      type: 'expand',
+      name: 'editPlannedFinish',
+      message: 'Edit or remove planned finish date?',
+      default: 'none',
+      when: answers => plannedFinishDateExists,
+      choices: [
+        {
+          key: 'e',
+          name: 'Edit',
+          value: 'edit'
+        },
+        {
+          key: 'r',
+          name: 'Remove',
+          value: 'remove'
+        },
+        new inquirer.Separator(),
+        {
+          key: 'n',
+          name: 'Do nothing',
+          value: 'none'
+        }
+      ]
+    },
+    {
+      type: 'confirm',
+      name: 'setPlannedFinish',
+      message: 'Set a planned finish date?',
+      default: false,
+      when: answers => !plannedFinishDateExists
+    },
+    {
+      type: 'datepicker',
+      name: 'plannedFinish',
+      message: 'Planned finish date:',
+      default: plannedFinishDateExists ? taskData.metadata.plannedFinish : new Date(),
+      format: ['Y', '/', 'MM', '/', 'DD'],
+      when: answers => answers.setPlannedFinish || answers.editPlannedFinish === 'edit'
     },
     {
       type: 'expand',
@@ -475,14 +520,26 @@ module.exports = async args => {
     }
   }
 
-  // Postponed date
-  if (args.postponed) {
+  // Planned start date
+  if (args.plannedStart) {
     if (!('metadata' in taskData)) {
       taskData.metadata = {};
     }
-    taskData.metadata.postponed = chrono.parseDate(utility.strArg(args.postponed));
-    if (taskData.metadata.postponed === null) {
-      utility.error('Unable to parse postponed date');
+    taskData.metadata.plannedStart = chrono.parseDate(utility.strArg(args.plannedStart));
+    if (taskData.metadata.plannedStart === null) {
+      utility.error('Unable to parse plannedStart date');
+      return;
+    }
+  }
+
+  // Planned finish date
+  if (args.plannedFinish) {
+    if (!('metadata' in taskData)) {
+      taskData.metadata = {};
+    }
+    taskData.metadata.plannedFinish = chrono.parseDate(utility.strArg(args.plannedFinish));
+    if (taskData.metadata.plannedFinish === null) {
+      utility.error('Unable to parse plannedFinish date');
       return;
     }
   }
@@ -720,14 +777,24 @@ module.exports = async args => {
         taskData.metadata.due = answers.due;
       }
 
-      // Remove postponed date
-      if ('editPostponed' in answers && answers.editPostponed === 'remove') {
-        delete taskData.metadata.postponed;
+      // Remove planned start date
+      if ('editPlannedStart' in answers && answers.editPlannedStart === 'remove') {
+        delete taskData.metadata.plannedStart;
+      }
+
+      // Planned start date
+      if ('plannedStart' in answers) {
+        taskData.metadata.plannedStart = answers.plannedStart;
+      }
+
+      // Remove planned finish date
+      if ('editPlannedFinish' in answers && answers.editPlannedFinish === 'remove') {
+        delete taskData.metadata.plannedFinish;
       }
 
-      // Postponed date
-      if ('postponed' in answers) {
-        taskData.metadata.postponed = answers.postponed;
+      // Planned finish date
+      if ('plannedFinish' in answers) {
+        taskData.metadata.plannedFinish = answers.plannedFinish;
       }
 
       // Remove assigned

package/src/controller/find.js

@@ -53,8 +53,13 @@ const searchFields = [
     type: 'date'
   },
   {
-    name: 'Postponed',
-    field: 'postponed',
+    name: 'Planned start',
+    field: 'plannedStart',
+    type: 'date'
+  },
+  {
+    name: 'Planned finish',
+    field: 'plannedFinish',
     type: 'date'
   },
   {
@@ -369,7 +374,7 @@ module.exports = async args => {
     }
   }
   if ('workload' in filters){
-    if (!convertNumericFilters(filters, 'workoad')) {
+    if (!convertNumericFilters(filters, 'workload')) {
       utility.error('Workload filter value must be numeric');
       return;
     }
@@ -412,6 +417,18 @@ module.exports = async args => {
       return;
     }
   }
+  if ('plannedStart' in filters) {
+    if (!convertDateFilters(filters, 'plannedStart')) {
+      utility.error('Unable to parse plannedStart date');
+      return;
+    }
+  }
+  if ('plannedFinish' in filters) {
+    if (!convertDateFilters(filters, 'plannedFinish')) {
+      utility.error('Unable to parse plannedFinish date');
+      return;
+    }
+  }
 
   // Check and add custom field filters
   if ('customFields' in index.options) {

package/src/controller/gantt.js

@@ -363,10 +363,9 @@ module.exports = async args => {
       });
 
       // Render x-axis
-      console.log('');
       const [ticks, labels] = renderXAxisLabels(data.from, data.to, barWidth, dateFormat);
-      console.log(`  ${''.padEnd(maxNameWidth)} │${renderTickRow(ticks, nowPosition)}│`);
-      console.log(`  ${''.padEnd(maxNameWidth)} │${labels}│`);
+      console.log(`  ${''.padEnd(maxNameWidth)}  ${renderTickRow(ticks, nowPosition)}`);
+      console.log(`  ${''.padEnd(maxNameWidth)}  ${labels}`);
     }
   })
   .catch(error => {

package/src/controller/history.js

@@ -0,0 +1,105 @@
+const kanbn = require('../main');
+const utility = require('../utility');
+const chrono = require('chrono-node');
+const formatDate = require('dateformat');
+
+function formatHistoryEvent(event) {
+	const details = [];
+	if ('column' in event.event) {
+		details.push(`column: ${event.event.column}`);
+	}
+	if ('fromColumn' in event.event || 'toColumn' in event.event) {
+		details.push(`column: ${event.event.fromColumn || '?'} -> ${event.event.toColumn || '?'}`);
+	}
+	if ('fromProgress' in event.event || 'toProgress' in event.event) {
+		details.push(`progress: ${event.event.fromProgress || 0} -> ${event.event.toProgress || 0}`);
+	}
+	if ('author' in event.event && event.event.author) {
+		details.push(`author: ${event.event.author}`);
+	}
+	return details.join(', ');
+}
+
+function formatMetadataEvent(event, dateFormat) {
+	if (!('field' in event.event) || !('value' in event.event) || !(event.event.value instanceof Date)) {
+		return '';
+	}
+	return `${event.event.field}: ${formatDate(event.event.value, dateFormat)}`;
+}
+
+module.exports = async args => {
+
+	// Make sure kanbn has been initialised
+	if (!await kanbn.initialised()) {
+		utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+		return;
+	}
+	const index = await kanbn.getIndex();
+
+	// Get sprint numbers or names
+	let sprints = null;
+	if (args.sprint) {
+		sprints = utility.arrayArg(args.sprint).map(s => {
+			const sprintNumber = parseInt(s);
+			return isNaN(sprintNumber) ? s : sprintNumber;
+		});
+	}
+
+	// Get dates
+	let dates = null;
+	if (args.date) {
+		dates = utility.arrayArg(args.date);
+		if (dates.length) {
+			for (let i = 0; i < dates.length; i++) {
+				const dateValue = chrono.parseDate(dates[i]);
+				if (dateValue === null) {
+					utility.error('Unable to parse date');
+					return;
+				}
+				dates[i] = dateValue;
+			}
+		}
+	}
+
+	// Get assigned
+	let assigned = null;
+	if (args.assigned) {
+		assigned = utility.strArg(args.assigned);
+	}
+
+	// Get task ids
+	let taskIds = null;
+	if (args.task) {
+		taskIds = utility.arrayArg(args.task).map((taskId) => utility.trimLeftEscapeCharacters(taskId));
+	}
+
+	kanbn
+	.history(sprints, dates, assigned, taskIds)
+	.then(data => {
+		if (args.json) {
+			console.log(JSON.stringify(data, null, 2));
+			return;
+		}
+
+		if (data.events.length === 0) {
+			console.log('No history events found');
+			return;
+		}
+
+		const dateFormat = kanbn.getDateFormat(index);
+		const lines = data.events.map((event) => {
+			const eventDetails = event.source === 'history'
+				? formatHistoryEvent(event)
+				: formatMetadataEvent(event, dateFormat);
+			const source = event.source === 'history' ? event.eventType : `metadata.${event.eventType}`;
+			const line = `${formatDate(event.date, dateFormat)} | ${event.task.id} | ${source}`;
+			return eventDetails
+				? `${line} | ${eventDetails}`
+				: line;
+		});
+		console.log(lines.join('\n'));
+	})
+	.catch(error => {
+		utility.error(error);
+	});
+};

package/src/controller/sort.js

@@ -123,10 +123,18 @@ const sorterFields = [
     filterable: false
   },
   {
-    name: 'Postponed date',
-    field: 'postponed',
+    name: 'Planned start date',
+    field: 'plannedStart',
     options: [
-      '--postponed'
+      '--plannedStart'
+    ],
+    filterable: false
+  },
+  {
+    name: 'Planned finish date',
+    field: 'plannedFinish',
+    options: [
+      '--plannedFinish'
     ],
     filterable: false
   },

package/src/main.js

@@ -266,7 +266,8 @@ function sortColumnInIndex(index, tasks, columnName, sorters) {
     started: "started" in task.metadata ? task.metadata.started : "",
     completed: "completed" in task.metadata ? task.metadata.completed : "",
     due: "due" in task.metadata ? task.metadata.due : "",
-    postponed: "postponed" in task.metadata ? task.metadata.postponed : "",
+    plannedStart: "plannedStart" in task.metadata ? task.metadata.plannedStart : "",
+    plannedFinish: "plannedFinish" in task.metadata ? task.metadata.plannedFinish : "",
     assigned: "assigned" in task.metadata ? task.metadata.assigned : "",
     countSubTasks: task.subTasks.length,
     subTasks: task.subTasks.map((subTask) => `[${subTask.completed ? "x" : ""}] ${subTask.text}`).join("\n"),
@@ -840,9 +841,10 @@ function endOfDay(date) {
  */
 function getTaskGanttAnchor(task) {
   return minDate([
-    task.metadata.postponed,
+    task.metadata.plannedStart,
     task.created,
     task.started,
+    task.metadata.plannedFinish,
     task.completed
   ]) || new Date(0);
 }
@@ -986,20 +988,47 @@ function buildGanttSchedule(index, tasks, now) {
         .filter((scheduledDependency) => scheduledDependency)
         .map((scheduledDependency) => scheduledDependency.end)
     );
-    const taskBaseDate = maxDate([
-      task.created,
-      task.started,
-      task.metadata.postponed,
-    ]);
+    const hasPlannedStart = task.metadata.plannedStart instanceof Date;
+    const hasPlannedFinish = task.metadata.plannedFinish instanceof Date;
+    const hasStarted = task.started instanceof Date;
+    const hasCompleted = task.completed instanceof Date;
+
+    const duration = hasPlannedStart && hasPlannedFinish
+      ? Math.max(DAY, task.metadata.plannedFinish.getTime() - task.metadata.plannedStart.getTime())
+      : hasStarted && hasCompleted
+        ? Math.max(DAY, task.completed.getTime() - task.started.getTime())
+        : Math.max(DAY, Math.ceil(Math.max(1, task.workload)) * DAY);
+
+    const preferredStart = hasPlannedStart
+      ? task.metadata.plannedStart
+      : hasStarted
+        ? task.started
+        : task.created;
+    const finishHint = hasPlannedFinish
+      ? task.metadata.plannedFinish
+      : hasCompleted
+        ? task.completed
+        : null;
+
+    const derivedStartFromFinish = finishHint instanceof Date
+      ? new Date(finishHint.getTime() - duration)
+      : null;
+    const taskBaseDate = hasPlannedStart || hasStarted
+      ? preferredStart
+      : (derivedStartFromFinish || preferredStart);
+
     const scheduleAnchor = maxDate([
       taskBaseDate,
       dependencyEnd
     ]) || new Date(0);
-    const duration = task.completed instanceof Date && task.started instanceof Date
-      ? Math.max(DAY, task.completed.getTime() - task.started.getTime())
-      : Math.max(DAY, Math.ceil(Math.max(1, task.workload)) * DAY);
+
     let start = new Date(scheduleAnchor.getTime());
-    let end = task.completed instanceof Date ? new Date(task.completed.getTime()) : new Date(start.getTime() + duration);
+    let end = hasPlannedFinish
+      ? new Date(task.metadata.plannedFinish.getTime())
+      : hasCompleted
+        ? new Date(task.completed.getTime())
+        : new Date(start.getTime() + duration);
+
     if (end.getTime() < start.getTime()) {
       end = new Date(start.getTime() + duration);
     }
@@ -1009,7 +1038,7 @@ function buildGanttSchedule(index, tasks, now) {
       dependencies,
       start,
       end,
-      blocked: dependencyEnd !== null && taskBaseDate !== null && dependencyEnd.getTime() > taskBaseDate.getTime()
+      blocked: dependencyEnd !== null && preferredStart instanceof Date && dependencyEnd.getTime() > preferredStart.getTime()
     };
     scheduleById.set(task.id, scheduledTask);
     scheduledTasks.push(scheduledTask);
@@ -2520,7 +2549,7 @@ class Kanbn {
         if (indexSprints === null) {
           throw new Error(`No sprints defined`);
         } else {
-          for (sprint of sprints) {
+          for (let sprint of sprints) {
             let sprintIndex = null;
 
             // Select sprint by number (1-based index)
@@ -2632,6 +2661,138 @@ class Kanbn {
     return { series };
   }
 
+  /**
+   * Get a chronological list of task events from metadata dates and structured task history
+   * @param {?string[]} [sprints=null] The sprint names or numbers to include, or null for no sprint filter
+   * @param {?Date[]} [dates=null] One or more dates to define a range filter, or null for no date filter
+   * @param {?string} [assigned=null] The assigned user to filter for, or null for no assigned filter
+   * @param {?string[]} [taskIds=null] One or more task ids to filter for, or null for no task id filter
+   * @return {Promise<object>} A list of chronological task history events
+   */
+  async history(sprints = null, dates = null, assigned = null, taskIds = null) {
+    // Check if this folder has been initialised
+    if (!(await this.initialised())) {
+      throw new Error("Not initialised in this folder");
+    }
+
+    const index = await this.loadIndex();
+    const selectedTaskIds = taskIds === null
+      ? null
+      : new Set(taskIds.map((taskId) => removeFileExtension(taskId)));
+
+    // Build date filter periods from sprints and/or dates
+    const periods = [];
+    const indexSprints = "sprints" in index.options && index.options.sprints.length ? index.options.sprints : null;
+    if (sprints !== null) {
+      if (indexSprints === null) {
+        throw new Error("No sprints defined");
+      }
+      for (let sprint of sprints) {
+        let sprintIndex = null;
+
+        // Select sprint by number (1-based index)
+        if (typeof sprint === "number") {
+          if (sprint < 1 || sprint > indexSprints.length) {
+            throw new Error(`Sprint ${sprint} does not exist`);
+          }
+          sprintIndex = sprint - 1;
+
+          // Or select sprint by name
+        } else if (typeof sprint === "string") {
+          sprintIndex = indexSprints.findIndex((s) => s.name === sprint);
+          if (sprintIndex === -1) {
+            throw new Error(`No sprint found with name "${sprint}"`);
+          }
+        }
+
+        if (sprintIndex === null) {
+          throw new Error(`Invalid sprint "${sprint}"`);
+        }
+
+        periods.push({
+          type: "sprint",
+          label: indexSprints[sprintIndex].name,
+          from: new Date(indexSprints[sprintIndex].start),
+          to: sprintIndex < indexSprints.length - 1
+            ? new Date(indexSprints[sprintIndex + 1].start)
+            : new Date(),
+        });
+      }
+    }
+
+    if (dates !== null) {
+      periods.push({
+        type: "date",
+        from: new Date(Math.min(...dates)),
+        to: dates.length === 1 ? new Date() : new Date(Math.max(...dates)),
+      });
+    }
+
+    const includeEventDate = (date) => {
+      if (!(date instanceof Date) || isNaN(date.getTime())) {
+        return false;
+      }
+      if (periods.length === 0) {
+        return true;
+      }
+      return periods.some((period) => date >= period.from && date <= period.to);
+    };
+
+    const buildBaseTask = (task) => ({
+      id: task.id,
+      name: task.name,
+      assigned: getTaskMetadata(task, "assigned") || null,
+      column: findTaskColumn(index, task.id),
+    });
+
+    const tasks = await this.loadAllTrackedTasks(index);
+    let events = tasks
+      .filter((task) => {
+        const assignedUser = getTaskMetadata(task, "assigned") || null;
+        return (
+          (assigned === null || assignedUser === assigned) &&
+          (selectedTaskIds === null || selectedTaskIds.has(task.id))
+        );
+      })
+      .map((task) => {
+        const taskBase = buildBaseTask(task);
+
+        const metadataEvents = Object.entries(task.metadata)
+          .filter(([, value]) => value instanceof Date)
+          .map(([field, value]) => ({
+            date: value,
+            source: "metadata",
+            eventType: field,
+            task: taskBase,
+            event: {
+              field,
+              value,
+            },
+          }));
+
+        const historyEvents = ("history" in task && Array.isArray(task.history) ? task.history : [])
+          .filter((historyEvent) => historyEvent.date instanceof Date)
+          .map((historyEvent) => {
+            const event = { ...historyEvent };
+            delete event.date;
+            return {
+              date: historyEvent.date,
+              source: "history",
+              eventType: historyEvent.type,
+              task: taskBase,
+              event,
+            };
+          });
+
+        return [...metadataEvents, ...historyEvents];
+      })
+      .flat()
+      .filter((event) => includeEventDate(event.date));
+
+    events.sort((a, b) => compareValues(a.date, b.date) || compareValues(a.task.id, b.task.id));
+    return { periods, events };
+  }
+
   /**
    * Output gantt chart data
    * @param {?string} [assigned=null] The assigned user to filter for, or null for no assigned filter
@@ -2659,7 +2820,8 @@ class Kanbn {
           created,
           started: "started" in task.metadata ? task.metadata.started : false,
           completed: "completed" in task.metadata ? task.metadata.completed : false,
-          postponed: "postponed" in task.metadata ? task.metadata.postponed : false,
+          plannedStart: "plannedStart" in task.metadata ? task.metadata.plannedStart : false,
+          plannedFinish: "plannedFinish" in task.metadata ? task.metadata.plannedFinish : false,
           workload: taskWorkload(index, task),
           progress: taskProgress(index, task),
           column: taskColumn,