@basementuniverse/kanbn 2.1.0 → 2.5.0

package/src/board.js

@@ -55,6 +55,23 @@ module.exports = (() => {
     }
   }
 
+  /**
+   * Render the simple tasks in a column - lines in the board file that aren't task links. They have
+   * no fields to interpolate and take no part in filtering or sorting, so they're shown dimmed at
+   * the end of the column, and only in the default layout where the columns on screen are the
+   * columns in the file
+   * @param {object} index
+   * @param {string} columnName
+   * @return {string[]} The rendered simple tasks
+   */
+  function getSimpleTaskStrings(index, columnName) {
+    return ((index.columnContent || {})[columnName] || [])
+      .filter(entry => !entry.block && !!entry.text && entry.text.indexOf('\n') === -1)
+
+      // A caret starts a markup sequence in terminal-kit, so any in the user's own text are escaped
+      .map(entry => `^-${entry.text.replace(/\^/g, '^^')}^:`);
+  }
+
   /**
    * Get a column heading with icons
    * @param {object} index
@@ -166,7 +183,13 @@ module.exports = (() => {
       table.push(board.headings.map(heading => heading.heading));
       board.lanes.forEach(lane => table.push(
         [lane.name],
-        lane.columns.map(column => column.map(task => getTaskString(index, task)).join(TASK_SEPARATOR))
+        lane.columns.map((column, i) => {
+          const cell = column.map(task => getTaskString(index, task));
+          if (view === null) {
+            cell.push(...getSimpleTaskStrings(index, board.headings[i].name));
+          }
+          return cell.join(TASK_SEPARATOR);
+        })
       ));
 
       // Display as a table

package/src/controller/add.js

@@ -3,7 +3,6 @@ const utility = require('../utility');
 const inquirer = require('inquirer');
 const fuzzy = require('fuzzy');
 const chrono = require('chrono-node');
-const getGitUsername = require('../git-user-name');
 
 // The boards this command targets - set from --board before anything else runs
 let kanbn = workspace;
@@ -19,9 +18,11 @@ inquirer.registerPrompt('autocomplete', require('inquirer-autocomplete-prompt'))
  * @param {string[]} taskIds
  * @param {string} columnName
  * @param {string[]} columnNames
+ * @param {?string} currentUser
+ * @param {object[]} contributors
  * @return {Promise<any>}
  */
-async function interactiveCreateTask(taskData, taskIds, columnName, columnNames) {
+async function interactiveCreateTask(taskData, taskIds, columnName, columnNames, currentUser, contributors) {
   const dueDateExists = (
     'metadata' in taskData &&
     'due' in taskData.metadata &&
@@ -127,13 +128,12 @@ async function interactiveCreateTask(taskData, taskIds, columnName, columnNames)
       default: false,
       when: answers => !assignedExists
     },
-    {
-      type: 'input',
+    utility.assignedPrompt({
       name: 'assigned',
       message: 'Assigned to:',
-      default: assignedExists ? taskData.metadata.assigned : getGitUsername(),
+      default: assignedExists ? taskData.metadata.assigned : (currentUser || ''),
       when: answers => answers.setAssigned || assignedExists
-    },
+    }, contributors),
     {
       type: 'recursive',
       name: 'subTasks',
@@ -250,9 +250,11 @@ async function createTask(taskData, columnName) {
       `Created task "${taskId}" in column "${columnName}"` +
       (boardTargets.length > 1 || !first.main ? ` on board "${first.slug}"` : '')
     );
+    utility.showActionWarnings(first.kanbn);
     for (const target of rest) {
       await target.kanbn.addTaskToBoard(taskId, target.columnName);
       console.log(`Added task "${taskId}" to column "${target.columnName}" on board "${target.slug}"`);
+      utility.showActionWarnings(target.kanbn);
     }
   } catch (error) {
     utility.error(error);
@@ -400,10 +402,12 @@ module.exports = async args => {
 
   // Assigned
   if (args.assigned) {
-    const gitUsername = getGitUsername();
     if (args.assigned === true) {
-      if (gitUsername) {
-        taskData.metadata.assigned = gitUsername;
+
+      // A bare --assigned means "me", canonicalised against the contributors list if there is one
+      const currentUser = await kanbn.currentUser();
+      if (currentUser) {
+        taskData.metadata.assigned = currentUser;
       }
     } else {
       taskData.metadata.assigned = utility.strArg(args.assigned);
@@ -508,7 +512,14 @@ module.exports = async args => {
 
   // Create task interactively
   if (args.interactive) {
-    interactiveCreateTask(taskData, taskIds, columnName, columnNames)
+    interactiveCreateTask(
+      taskData,
+      taskIds,
+      columnName,
+      columnNames,
+      await kanbn.currentUser(),
+      await kanbn.getContributors()
+    )
     .then(answers => {
       taskData.name = answers.name;
       if ('description' in answers) {

package/src/controller/archive.js

@@ -13,6 +13,7 @@ function archiveTask(taskId) {
   .archiveTask(taskId)
   .then(taskId => {
     console.log(`Archived task "${taskId}"`);
+    utility.showActionWarnings(kanbn);
   })
   .catch(error => {
     utility.error(error);

package/src/controller/board.js

@@ -24,16 +24,25 @@ module.exports = async args => {
     return;
   }
 
-  // Load and hydrate all tracked tasks
-  const tasks = (await kanbn.loadAllTrackedTasks(index)).map(
-    task => kanbn.hydrateTask(index, task)
-  );
+  // Load and hydrate all tracked tasks. A task the board references but which has no task file is
+  // skipped rather than fatal, and reported by the hint below
+  let tasks, missingTaskFiles;
+  try {
+    tasks = (await kanbn.loadAllTrackedTasks(index)).map(
+      task => kanbn.hydrateTask(index, task)
+    );
+    missingTaskFiles = await kanbn.findMissingTaskFiles(index);
+  } catch (error) {
+    utility.error(error);
+    return;
+  }
 
   // Show the board
   board
   .show(index, tasks, args.view, args.json)
   .then(async () => {
     const verbose = !args.json && kanbn.isVerbose(index);
+    utility.showMissingTaskFilesHint(missingTaskFiles, verbose);
     utility.showDateDriftHint(kanbn.getDateDrift(index, tasks), verbose);
     utility.showBoardCountHint(await workspace.listBoards(), verbose);
   })

package/src/controller/burndown.js

@@ -98,10 +98,13 @@ module.exports = async args => {
     }
   }
 
-  // Get assigned
+  // Get assigned, expanding "@me" to the current user
   let assigned = null;
   if (args.assigned) {
-    assigned = utility.strArg(args.assigned);
+    assigned = await utility.expandCurrentUser(kanbn, utility.strArg(args.assigned));
+    if (assigned === null) {
+      return;
+    }
   }
 
   // Get columns

package/src/controller/comment.js

@@ -1,7 +1,6 @@
 const workspace = require('../main');
 const utility = require('../utility');
 const inquirer = require('inquirer');
-const getGitUsername = require('../git-user-name');
 
 // The board this command targets - set from --board before anything else runs
 let kanbn = workspace;
@@ -46,6 +45,7 @@ function addComment(taskId, text, author) {
   .comment(taskId, text, author)
   .then(taskId => {
     console.log(`Added comment to task "${taskId}"`);
+    utility.showActionWarnings(kanbn);
   })
   .catch(error => {
     utility.error(error);
@@ -88,7 +88,10 @@ module.exports = async args => {
   if (args.author && typeof args.author === 'string') {
     commentAuthor = utility.strArg(args.author);
   } else {
-    commentAuthor = getGitUsername();
+
+    // Nobody at all is a legitimate answer on a machine with no git identity, and an empty author is
+    // what a comment without one looks like
+    commentAuthor = (await kanbn.currentUser()) || '';
   }
 
   // Add comment interactively

package/src/controller/contributors.js

@@ -0,0 +1,166 @@
+const workspace = require('../main');
+const utility = require('../utility');
+
+/**
+ * Show the workspace's contributors
+ * @param {object[]} contributors
+ * @param {?string} currentUser
+ * @param {boolean} json
+ */
+function showContributors(contributors, currentUser, json) {
+  if (json) {
+    console.log(JSON.stringify({ contributors, currentUser }, null, 2));
+    return;
+  }
+  if (!contributors.length) {
+    console.log('No contributors are declared in this workspace');
+    console.log(utility.replaceTags(
+      `\n{d}Add a {d}{b}contributors{b}{d} list to your config file or the main board's front matter -{d} ` +
+      `{b}kanbn contributors --help{b}`
+    ));
+    showCurrentUser(currentUser);
+    return;
+  }
+  console.log(`${contributors.length} ${contributors.length === 1 ? 'contributor' : 'contributors'}:`);
+  for (const contributor of contributors) {
+    console.log(utility.replaceTags(
+      `\n{b}${contributor.name}{b}` +
+      (contributor.name === currentUser ? ' (you)' : '')
+    ));
+    if (contributor.displayName !== contributor.name) {
+      console.log(`  ${contributor.displayName}`);
+    }
+    if (contributor.email) {
+      console.log(`  ${contributor.email}`);
+    }
+    if (contributor.aliases.length) {
+      console.log(`  also known as ${contributor.aliases.map(alias => `"${alias}"`).join(', ')}`);
+    }
+    if (contributor.colour) {
+      console.log(`  ${contributor.colour}`);
+    }
+  }
+  showCurrentUser(currentUser, contributors);
+}
+
+/**
+ * Say who kanbn thinks the current user is, since that's what a bare --assigned and "@me" resolve to
+ * @param {?string} currentUser
+ * @param {object[]} [contributors=[]]
+ */
+function showCurrentUser(currentUser, contributors = []) {
+  if (currentUser === null) {
+    console.log(utility.replaceTags(
+      `\n{d}Kanbn can't work out who you are. Set {d}{b}KANBN_USER{b}{d}, or set a git username with{d} ` +
+      `{b}git config user.name "your name"{b}`
+    ));
+    return;
+  }
+  if (contributors.length && !contributors.some(contributor => contributor.name === currentUser)) {
+    console.log(utility.replaceTags(
+      `\n{d}You are{d} {b}${currentUser}{b}{d}, which isn't in the contributors list{d}`
+    ));
+    return;
+  }
+  console.log(utility.replaceTags(`\n{d}You are{d} {b}${currentUser}{b}`));
+}
+
+/**
+ * Show how contributors are used across the workspace's tasks, and which names are in use that the
+ * contributors list doesn't know about
+ * @param {object} usage
+ * @param {?string} currentUser
+ * @param {boolean} json
+ */
+function showUsage(usage, currentUser, json) {
+  if (json) {
+    console.log(JSON.stringify({ ...usage, currentUser }, null, 2));
+    return;
+  }
+  if (usage.contributors.length) {
+    console.log(`${usage.contributors.length} ${usage.contributors.length === 1 ? 'contributor' : 'contributors'}:`);
+    for (const contributor of usage.contributors) {
+      console.log(utility.replaceTags(
+        `\n{b}${contributor.name}{b}` +
+        (contributor.name === currentUser ? ' (you)' : '')
+      ));
+      console.log(
+        `  ${contributor.tasks} ${contributor.tasks === 1 ? 'task' : 'tasks'}, ` +
+        `assigned ${contributor.assigned}, ` +
+        `${contributor.comments} ${contributor.comments === 1 ? 'comment' : 'comments'}`
+      );
+
+      // A contributor matched through an alias or a different case is worth showing: it's a spelling
+      // that works today only because the alias is there to catch it
+      for (const spelling of contributor.spellings.filter(s => s.value !== contributor.name)) {
+        console.log(`  written as "${spelling.value}" in ${spelling.tasks.length} ${spelling.tasks.length === 1 ? 'task' : 'tasks'}`);
+      }
+    }
+  } else {
+    console.log('No contributors are declared in this workspace');
+  }
+
+  if (!usage.unknown.length) {
+    console.log(
+      usage.contributors.length
+        ? '\nEvery name used in a task matches a contributor'
+        : '\nNo names are used in any task'
+    );
+    return;
+  }
+  console.log(
+    `\n${usage.unknown.length} ${usage.unknown.length === 1 ? 'name is' : 'names are'} used in tasks ` +
+    `but ${usage.unknown.length === 1 ? "isn't" : "aren't"} a known contributor:`
+  );
+  for (const unknown of usage.unknown) {
+    console.log(utility.replaceTags(
+      `\n{b}${unknown.value}{b}` +
+      (unknown.value === currentUser ? ' (you)' : '')
+    ));
+    console.log(
+      `  ${unknown.tasks.length} ${unknown.tasks.length === 1 ? 'task' : 'tasks'}, ` +
+      `assigned ${unknown.assigned}, ` +
+      `${unknown.comments} ${unknown.comments === 1 ? 'comment' : 'comments'}`
+    );
+    console.log(`  ${unknown.tasks.join(', ')}`);
+  }
+  console.log(utility.replaceTags(
+    `\n{d}Add these to {d}{b}contributors{b}{d}, or as an {d}{b}alias{b}{d} of a contributor already ` +
+    `in the list. Nothing is rewritten either way - {d}{b}assigned{b}{d} and comment {d}{b}author{b}` +
+    `{d} are free text{d}`
+  ));
+}
+
+module.exports = async args => {
+
+  // Contributors are workspace-scoped, so this command isn't board-scoped either
+  if (!await workspace.workspaceInitialised()) {
+    utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+    return;
+  }
+
+  let currentUser;
+  try {
+    currentUser = await workspace.currentUser();
+  } catch (error) {
+    utility.error(error);
+    return;
+  }
+
+  // Show how the contributors are actually used across the workspace's tasks
+  if (args.usage) {
+    try {
+      showUsage(await workspace.getContributorUsage(), currentUser, args.json);
+    } catch (error) {
+      utility.error(error);
+    }
+    return;
+  }
+
+  // List contributors
+  try {
+    showContributors(await workspace.getContributors(), currentUser, args.json);
+  } catch (error) {
+    utility.error(error);
+  }
+};

package/src/controller/edit.js

@@ -3,7 +3,6 @@ const utility = require('../utility');
 const inquirer = require('inquirer');
 const fuzzy = require('fuzzy');
 const chrono = require('chrono-node');
-const getGitUsername = require('../git-user-name');
 
 // The board this command targets - set from --board before anything else runs
 let kanbn = workspace;
@@ -18,9 +17,11 @@ inquirer.registerPrompt('autocomplete', require('inquirer-autocomplete-prompt'))
  * @param {string[]} taskIds
  * @param {string} columnName
  * @param {string[]} columnNames
+ * @param {?string} currentUser
+ * @param {object[]} contributors
  * @return {Promise<any>}
  */
-async function interactive(taskData, taskIds, columnName, columnNames) {
+async function interactive(taskData, taskIds, columnName, columnNames, currentUser, contributors) {
   const dueDateExists = (
     'metadata' in taskData &&
     'due' in taskData.metadata &&
@@ -226,13 +227,12 @@ async function interactive(taskData, taskIds, columnName, columnNames) {
       default: false,
       when: answers => !assignedExists
     },
-    {
-      type: 'input',
+    utility.assignedPrompt({
       name: 'assigned',
       message: 'Assigned to:',
-      default: assignedExists ? taskData.metadata.assigned : getGitUsername(),
+      default: assignedExists ? taskData.metadata.assigned : (currentUser || ''),
       when: answers => answers.setAssigned || answers.editAssigned === 'edit'
-    },
+    }, contributors),
     {
       type: 'recursive',
       name: 'addSubTasks',
@@ -450,6 +450,7 @@ function updateTask(taskId, taskData, columnName, unsetFields = []) {
   .updateTask(taskId, taskData, columnName, unsetFields)
   .then(taskId => {
     console.log(`Updated task "${taskId}"`);
+    utility.showActionWarnings(kanbn);
   })
   .catch(error => {
     utility.error(error);
@@ -466,18 +467,34 @@ module.exports = async args => {
   kanbn = scoped;
 
   // Get the task that we're editing
-  const taskId = args._[1];
+  let taskId = args._[1];
   if (!taskId) {
     utility.error('No task id specified\nTry running {b}kanbn edit "task id"{b}');
     return;
   }
 
-  // Make sure the task exists
+  // Make sure the task exists. Editing a simple task is how it becomes a real one - there is nothing
+  // to edit until it has a file - so promote it first and then edit the task that produces
   try {
     await kanbn.taskExists(taskId);
   } catch (error) {
-    utility.error(error);
-    return;
+    if (await kanbn.taskFileExists(taskId)) {
+      utility.error(error);
+      return;
+    }
+    const simpleTask = await utility.resolveSimpleTask(kanbn, taskId, error);
+    if (simpleTask === null) {
+      return;
+    }
+    try {
+      taskId = await kanbn.promoteSimpleTask(taskId);
+      console.log(utility.replaceTags(
+        `{d}Promoted simple task "${simpleTask.text}" to task "${taskId}"{d}`
+      ));
+    } catch (promoteError) {
+      utility.error(promoteError);
+      return;
+    }
   }
 
   // Get the index and make sure it has some columns
@@ -582,10 +599,12 @@ module.exports = async args => {
     if (!('metadata' in taskData)) {
       taskData.metadata = {};
     }
-    const gitUsername = getGitUsername();
     if (args.assigned === true) {
-      if (gitUsername) {
-        taskData.metadata.assigned = gitUsername;
+
+      // A bare --assigned means "me", canonicalised against the contributors list if there is one
+      const currentUser = await kanbn.currentUser();
+      if (currentUser) {
+        taskData.metadata.assigned = currentUser;
       }
     } else {
       taskData.metadata.assigned = utility.strArg(args.assigned);
@@ -813,7 +832,14 @@ module.exports = async args => {
 
   // Update task interactively
   if (args.interactive) {
-    interactive(taskData, taskIds, columnName, columnNames)
+    interactive(
+      taskData,
+      taskIds,
+      columnName,
+      columnNames,
+      await kanbn.currentUser(),
+      await kanbn.getContributors()
+    )
     .then(answers => {
 
       // Name

package/src/controller/find.js

@@ -114,6 +114,31 @@ const searchFields = [
     name: 'Assigned',
     field: 'assigned',
     type: 'string'
+  },
+  {
+    name: 'Overdue',
+    field: 'overdue',
+    type: 'boolean'
+  },
+  {
+    name: 'Is started',
+    field: 'is-started',
+    type: 'boolean'
+  },
+  {
+    name: 'Is completed',
+    field: 'is-completed',
+    type: 'boolean'
+  },
+  {
+    name: 'In started column',
+    field: 'in-started-column',
+    type: 'boolean'
+  },
+  {
+    name: 'In completed column',
+    field: 'in-completed-column',
+    type: 'boolean'
   }
 ];
 
@@ -284,6 +309,24 @@ function convertNumericFilters(filters, filterName) {
   return true;
 }
 
+/**
+ * Check that a filter holds a boolean value. Repeating a boolean option is meaningless, so the last
+ * value wins
+ * @param {object} filters The current filter object
+ * @param {string} filterName The property name for the filter
+ * @return {boolean} True if the value is a boolean
+ */
+function convertBooleanFilters(filters, filterName) {
+  const value = Array.isArray(filters[filterName])
+    ? filters[filterName][filters[filterName].length - 1]
+    : filters[filterName];
+  if (typeof value !== 'boolean') {
+    return false;
+  }
+  filters[filterName] = value;
+  return true;
+}
+
 /**
  * Convert a filter or array of filters to date values
  * @param {object} filters The current filter object
@@ -343,14 +386,28 @@ module.exports = async args => {
     }
   }
 
-  // Get filters from args
+  // Get filters from args. Boolean filters are checked with "in" because false is a filter value in
+  // its own right - "--no-overdue" means "not overdue", not "no overdue filter"
   const filters = {};
-  for (let filterProperty of searchFields.map(s => s.field)) {
-    if (args[filterProperty]) {
-      filters[filterProperty] = args[filterProperty];
+  for (let searchField of searchFields) {
+    if (searchField.type === 'boolean') {
+      if (searchField.field in args) {
+        filters[searchField.field] = args[searchField.field];
+      }
+    } else if (args[searchField.field]) {
+      filters[searchField.field] = args[searchField.field];
     }
   }
 
+  // Expand "@me" in the assigned filter
+  if ('assigned' in filters) {
+    const assigned = await utility.expandCurrentUser(kanbn, filters.assigned);
+    if (assigned === null) {
+      return;
+    }
+    filters.assigned = assigned;
+  }
+
   // Check and convert numeric filters
   if ('count-sub-tasks' in filters) {
     if (!convertNumericFilters(filters, 'count-sub-tasks')) {
@@ -389,6 +446,20 @@ module.exports = async args => {
     }
   }
 
+  // Check computed boolean filters
+  for (const [filterName, label] of [
+    ['overdue', 'Overdue'],
+    ['is-started', 'Is started'],
+    ['is-completed', 'Is completed'],
+    ['in-started-column', 'In started column'],
+    ['in-completed-column', 'In completed column']
+  ]) {
+    if (filterName in filters && !convertBooleanFilters(filters, filterName)) {
+      utility.error(`${label} filter value must be a boolean`);
+      return;
+    }
+  }
+
   // Check date filters
   if ('created' in filters) {
     if (!convertDateFilters(filters, 'created')) {

package/src/controller/gantt.js

@@ -324,10 +324,13 @@ module.exports = async args => {
   kanbn = scoped;
   const index = await kanbn.getIndex();
 
-  // Get assigned
+  // Get assigned, expanding "@me" to the current user
   let assigned = null;
   if (args.assigned) {
-    assigned = utility.strArg(args.assigned);
+    assigned = await utility.expandCurrentUser(kanbn, utility.strArg(args.assigned));
+    if (assigned === null) {
+      return;
+    }
   }
 
   // Get columns

package/src/controller/history.js

@@ -65,10 +65,13 @@ module.exports = async args => {
 		}
 	}
 
-	// Get assigned
+	// Get assigned, expanding "@me" to the current user
 	let assigned = null;
 	if (args.assigned) {
-		assigned = utility.strArg(args.assigned);
+		assigned = await utility.expandCurrentUser(kanbn, utility.strArg(args.assigned));
+		if (assigned === null) {
+			return;
+		}
 	}
 
 	// Get task ids