@basementuniverse/kanbn 2.0.0 → 2.5.0

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

@@ -1,9 +1,11 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 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;
 
 inquirer.registerPrompt('datepicker', require('inquirer-datepicker'));
 inquirer.registerPrompt('recursive', require('inquirer-recursive'));
@@ -15,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 &&
@@ -223,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',
@@ -447,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);
@@ -455,25 +459,42 @@ function updateTask(taskId, taskData, columnName, unsetFields = []) {
 
 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}');
+  // Work out which board this command targets
+  const scoped = await utility.resolveBoard(workspace, args);
+  if (scoped === null) {
     return;
   }
+  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
@@ -578,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);
@@ -809,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

@@ -1,9 +1,12 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 const inquirer = require('inquirer');
 const chrono = require('chrono-node');
 const yaml = require('yamljs');
 
+// The board this command targets - set from --board before anything else runs
+let kanbn = workspace;
+
 inquirer.registerPrompt('recursive', require('inquirer-recursive'));
 
 const searchFields = [
@@ -111,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'
   }
 ];
 
@@ -213,12 +241,11 @@ async function interactive() {
  * @param {boolean} quiet
  * @param {boolean} json
  */
-function findTasks(filters, quiet, json) {
+function findTasks(filters, quiet, json, allBoards = false) {
   const removeEmptyProperties = o => Object.fromEntries(Object.entries(o).filter(
     ([k, v]) => !(Array.isArray(v) && v.length == 0) && !!v
   ));
-  kanbn
-  .search(filters, quiet)
+  (allBoards ? kanbn.searchAllBoards(filters, quiet) : kanbn.search(filters, quiet))
   .then(results => {
     if (quiet) {
       console.log(json ? JSON.stringify(results, null, 2) : results.join('\n'));
@@ -282,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
@@ -309,11 +354,12 @@ function convertDateFilters(filters, filterName) {
 
 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}');
+  // Work out which board this command targets
+  const scoped = await utility.resolveBoard(workspace, args);
+  if (scoped === null) {
     return;
   }
+  kanbn = scoped;
 
   // Get the index and make sure it has some columns
   let index;
@@ -340,12 +386,26 @@ 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
@@ -386,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')) {
@@ -487,7 +561,7 @@ module.exports = async args => {
             filter.value
           );
         }
-        findTasks(filters, !otherAnswers.nonquiet, otherAnswers.json);
+        findTasks(filters, !otherAnswers.nonquiet, otherAnswers.json, !!args['all-boards']);
       })
       .catch(error => {
         utility.error(error);
@@ -499,6 +573,6 @@ module.exports = async args => {
 
   // Otherwise create task non-interactively
   } else {
-    findTasks(filters, args.quiet, args.json);
+    findTasks(filters, args.quiet, args.json, !!args['all-boards']);
   }
 };

package/src/controller/gantt.js

@@ -1,8 +1,11 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 const formatDate = require('dateformat');
 const chrono = require('chrono-node');
 
+// The board this command targets - set from --board before anything else runs
+let kanbn = workspace;
+
 const NOW_MARKER = '┆';
 const ANSI_RESET = '\x1b[0m';
 const ANSI_FG_LINE = '\x1b[97m';
@@ -313,17 +316,21 @@ function truncateName(name, maxWidth) {
 
 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}');
+  // Work out which board this command targets
+  const scoped = await utility.resolveBoard(workspace, args);
+  if (scoped === null) {
     return;
   }
+  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

@@ -1,8 +1,11 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 const chrono = require('chrono-node');
 const formatDate = require('dateformat');
 
+// The board this command targets - set from --board before anything else runs
+let kanbn = workspace;
+
 function formatHistoryEvent(event) {
 	const details = [];
 	if ('column' in event.event) {
@@ -29,11 +32,12 @@ function formatMetadataEvent(event, 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}');
+	// Work out which board this command targets
+	const scoped = await utility.resolveBoard(workspace, args);
+	if (scoped === null) {
 		return;
 	}
+	kanbn = scoped;
 	const index = await kanbn.getIndex();
 
 	// Get sprint numbers or names
@@ -61,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

package/src/controller/init.js

@@ -1,8 +1,11 @@
 const kanbn_module = require('../main');
-const kanbn = new kanbn_module.Kanbn();
+const workspace = new kanbn_module.Kanbn();
 const utility = require('../utility');
 const inquirer = require('inquirer');
 
+// The board being initialised - set from --board before anything else runs
+let kanbn = workspace;
+
 inquirer.registerPrompt('recursive', require('inquirer-recursive'));
 
 /**
@@ -73,11 +76,20 @@ async function interactive(options, initialised) {
  * Initialise kanbn
  * @param {object} options
  * @param {boolean} initialised
+ * @param {?string} boardSlug The slug of the board being initialised, or null for the main board
  */
-async function initialise(options, initialised) {
+async function initialise(options, initialised, boardSlug = null) {
   const mainFolder = await kanbn.getMainFolder();
   kanbn.initialise(options)
   .then(() => {
+    if (boardSlug !== null) {
+      console.log(
+        initialised
+          ? `Updated board "${boardSlug}" in ${mainFolder}`
+          : `Created board "${boardSlug}" in ${mainFolder}`
+      );
+      return;
+    }
     if (initialised) {
       console.log(`Reinitialised existing kanbn board in ${mainFolder}`);
     } else {
@@ -92,6 +104,29 @@ async function initialise(options, initialised) {
 module.exports = async args => {
   let options = {};
 
+  // Work out which board we're initialising. Without --board this is the main board, i.e. the whole
+  // workspace, which is exactly what init has always done
+  let boardSlug = null;
+  if (args.board) {
+    boardSlug = utility.strArg(args.board);
+
+    // A secondary board lives beside the main board and shares its tasks, so the workspace has to
+    // exist first
+    if (!await workspace.initialised()) {
+      utility.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+      return;
+    }
+    try {
+      boardSlug = await workspace.validateBoardSlug(boardSlug);
+    } catch (error) {
+      utility.error(error);
+      return;
+    }
+    kanbn = workspace.board(boardSlug);
+  } else {
+    kanbn = workspace;
+  }
+
   // If this folder is already initialised, set the default name and description using the current values
   const initialised = await kanbn.initialised();
   if (initialised) {
@@ -129,7 +164,7 @@ module.exports = async args => {
       if ('columns' in answers) {
         answers.columns = answers.columns.map(column => column.columnName);
       }
-      await initialise(answers, initialised);
+      await initialise(answers, initialised, boardSlug);
     })
     .catch(error => {
       utility.error(error);
@@ -137,6 +172,6 @@ module.exports = async args => {
 
   // Non-interactive initialisation
   } else {
-    await initialise(options, initialised);
+    await initialise(options, initialised, boardSlug);
   }
 };