@basementuniverse/kanbn 2.1.0 → 2.5.0

package/src/controller/move.js

@@ -50,6 +50,7 @@ function moveTask(taskId, columnName, position = null, relative = false, add = f
   .moveTask(taskId, columnName, position, relative, add)
   .then(taskId => {
     console.log(`Moved task "${taskId}" to column "${columnName}"`);
+    utility.showActionWarnings(kanbn);
   })
   .catch(error => {
     utility.error(error);
@@ -72,6 +73,42 @@ async function addTaskToBoard(taskId, columnName, boardSlug, verbose) {
       ));
     }
     console.log(`Moved task "${taskId}" to column "${columnName}"`);
+    utility.showActionWarnings(kanbn);
+  } catch (error) {
+    utility.error(error);
+  }
+}
+
+/**
+ * Move a simple task to another column on the board it's on
+ * @param {object} boardKanbn The board-scoped Kanbn instance
+ * @param {string} input
+ * @param {?string} columnName The column to move to, or null to leave it where it is
+ * @param {?number} position
+ */
+async function moveSimpleTask(boardKanbn, input, columnName, position) {
+  try {
+    const moved = await boardKanbn.moveSimpleTask(input, columnName, position);
+    console.log(`Moved simple task "${moved.text}" to column "${moved.toColumn}"`);
+  } catch (error) {
+    utility.error(error);
+  }
+}
+
+/**
+ * Move a simple task onto another board
+ * @param {object} sourceKanbn The board the simple task is on
+ * @param {string} input
+ * @param {string} targetSlug
+ * @param {?string} columnName
+ * @param {?number} position
+ */
+async function moveSimpleTaskToBoard(sourceKanbn, input, targetSlug, columnName, position) {
+  try {
+    const moved = await sourceKanbn.moveSimpleTaskToBoard(input, targetSlug, columnName, position);
+    console.log(
+      `Moved simple task "${moved.text}" to column "${moved.toColumn}" on board "${moved.toBoard}"`
+    );
   } catch (error) {
     utility.error(error);
   }
@@ -107,6 +144,53 @@ module.exports = async args => {
     return;
   }
 
+  // Re-use sprint option for position
+  let newPosition = args.position || args.p;
+  if (newPosition) {
+    newPosition = parseInt(utility.trimLeftEscapeCharacters(newPosition));
+    if (isNaN(newPosition)) {
+      utility.error('Position value must be numeric');
+      return;
+    }
+  } else {
+    newPosition = null;
+  }
+
+  // A task file always wins, so a simple task - a line in a column that isn't a task link - is only
+  // looked for when nothing has this task id. Falling through leaves every existing error unchanged
+  if (!(await kanbn.taskFileExists(taskId))) {
+    const targetColumn = args.column ? utility.strArg(args.column) : null;
+    const matches = await kanbn.findSimpleTasks(taskId);
+    if (matches.length) {
+      const simpleTask = await utility.resolveSimpleTask(kanbn, taskId, null, matches);
+      if (simpleTask !== null) {
+        await moveSimpleTask(
+          kanbn,
+          taskId,
+          targetColumn === null ? simpleTask.column : targetColumn,
+          newPosition
+        );
+      }
+      return;
+    }
+
+    // A simple task lives in one board file rather than in a shared task file, so `-b` names the
+    // board it is moving to rather than the board it is on
+    if (args.board) {
+      const sourceKanbn = await workspace.boardFromArgs({});
+      if ((await sourceKanbn.findSimpleTasks(taskId)).length) {
+        await moveSimpleTaskToBoard(
+          sourceKanbn,
+          taskId,
+          await kanbn.resolveBoardSlug(),
+          targetColumn,
+          newPosition
+        );
+        return;
+      }
+    }
+  }
+
   // Moving a task on a board it isn't on yet adds it there, so that pulling work onto a board is one
   // command rather than two. --no-add turns that back into an error. The main board is unaffected:
   // moving an untracked task there has always been an error and still is
@@ -157,16 +241,6 @@ module.exports = async args => {
 
   // Re-use sprint option for position
   const currentPosition = index.columns[currentColumnName].indexOf(taskId);
-  let newPosition = args.position || args.p;
-  if (newPosition) {
-    newPosition = parseInt(utility.trimLeftEscapeCharacters(newPosition));
-    if (isNaN(newPosition)) {
-      utility.error('Position value must be numeric');
-      return;
-    }
-  } else {
-    newPosition = null;
-  }
 
   // Get a list of sorted columns
   const sortedColumnNames = 'columnSorting' in index.options ? Object.keys(index.options.columnSorting) : [];

package/src/controller/remove.js

@@ -5,6 +5,34 @@ const inquirer = require('inquirer');
 // The board this command targets - set from --board before anything else runs
 let kanbn = workspace;
 
+/**
+ * Remove a simple task - a line in a column that isn't a task link. There is no file to delete and
+ * nothing to archive: the line is the whole of it
+ * @param {string} input
+ * @param {boolean} force True to skip the confirmation prompt
+ */
+async function removeSimpleTask(input, force) {
+  if (!force) {
+    const answers = await inquirer.prompt([
+      {
+        type: 'confirm',
+        message: 'Are you sure you want to remove this simple task?',
+        name: 'sure',
+        default: false
+      }
+    ]);
+    if (!answers.sure) {
+      return;
+    }
+  }
+  try {
+    const removed = await kanbn.deleteSimpleTask(input);
+    console.log(`Removed simple task "${removed.text}" from column "${removed.column}"`);
+  } catch (error) {
+    utility.error(error);
+  }
+}
+
 /**
  * Remove a task
  * @param {string} taskId
@@ -21,6 +49,7 @@ function removeTask(taskId, removeFile, allBoards, boardSlug, secondaryBoard) {
       `Removed task "${taskId}"${removeFile ? ' file and index entry' : ' from the index'}` +
       (secondaryBoard && !allBoards ? ` on board "${boardSlug}"` : '')
     );
+    utility.showActionWarnings(kanbn);
   })
   .catch(error => {
 
@@ -50,11 +79,19 @@ module.exports = async args => {
     return;
   }
 
-  // Make sure the task exists
+  // Make sure the task exists. A task file always wins, so a simple task is only looked for when
+  // nothing has this task id
   try {
     await kanbn.taskExists(taskId);
   } catch (error) {
-    utility.error(error);
+    if (await kanbn.taskFileExists(taskId)) {
+      utility.error(error);
+      return;
+    }
+    const simpleTask = await utility.resolveSimpleTask(kanbn, taskId, error);
+    if (simpleTask !== null) {
+      await removeSimpleTask(taskId, !!args.force);
+    }
     return;
   }
 

package/src/controller/restore.js

@@ -14,6 +14,7 @@ function restoreTask(taskId, columnName, singleBoard) {
   .restoreTask(taskId, columnName, singleBoard)
   .then(taskId => {
     console.log(`Restored task "${taskId}" from the archive`);
+    utility.showActionWarnings(kanbn);
 
     // A task is restored to every board it was on when it was archived. A board that has since been
     // deleted is skipped rather than failing the restore, but the user should hear about it

package/src/controller/sort.js

@@ -181,6 +181,46 @@ const sorterFields = [
       '--assigned'
     ],
     filterable: true
+  },
+  {
+    name: 'Overdue',
+    field: 'overdue',
+    options: [
+      '--overdue'
+    ],
+    filterable: false
+  },
+  {
+    name: 'Is started',
+    field: 'isStarted',
+    options: [
+      '--is-started'
+    ],
+    filterable: false
+  },
+  {
+    name: 'Is completed',
+    field: 'isCompleted',
+    options: [
+      '--is-completed'
+    ],
+    filterable: false
+  },
+  {
+    name: 'In started column',
+    field: 'inStartedColumn',
+    options: [
+      '--in-started-column'
+    ],
+    filterable: false
+  },
+  {
+    name: 'In completed column',
+    field: 'inCompletedColumn',
+    options: [
+      '--in-completed-column'
+    ],
+    filterable: false
   }
 ];
 

package/src/controller/task.js

@@ -53,10 +53,21 @@ module.exports = async (args) => {
     return;
   }
 
-  // Make sure the task exists
+  // Make sure the task exists. A line in a column that isn't a task link has no task file to show,
+  // so say what it is and how to turn it into one rather than reporting a missing file
   try {
     await kanbn.taskExists(taskId);
   } catch (error) {
+    if (!(await kanbn.taskFileExists(taskId))) {
+      const matches = await kanbn.findSimpleTasks(taskId);
+      if (matches.length === 1) {
+        utility.error(
+          `"${matches[0].text}" is a simple task in column "${matches[0].column}" - it has no task file\n` +
+          `Run {b}kanbn edit "${matches[0].text}"{b} to promote it to a task`
+        );
+        return;
+      }
+    }
     utility.error(error);
     return;
   }

package/src/controller/validate.js

@@ -30,6 +30,97 @@ function showDrift(drift, json) {
   }
 }
 
+/**
+ * Show lines in columns that aren't task links. These are preserved and ignored, so this is
+ * information rather than a problem - except for a line that looks like a task link with a typo in
+ * it, which is the one way a task can silently stop being tracked
+ * @param {object[]} warnings
+ */
+function showColumnContentWarnings(warnings) {
+  if (!warnings.length) {
+    return;
+  }
+  const malformed = warnings.filter(w => w.type === 'malformed-task-link');
+  const untracked = warnings.filter(w => w.type === 'untracked-task-line');
+  const other = warnings.filter(w => w.type === 'non-task-line');
+  if (malformed.length) {
+    console.log(utility.replaceTags(
+      `${malformed.length} ${malformed.length === 1 ? 'line looks' : 'lines look'} like a ` +
+      `{b}malformed task link{b} and ${malformed.length === 1 ? 'is' : 'are'} not being tracked:`
+    ));
+    for (const warning of malformed) {
+      console.log(`  ${warning.column}: ${warning.text}`);
+    }
+  }
+  if (untracked.length) {
+    console.log(utility.replaceTags(
+      `${untracked.length} ${untracked.length === 1 ? 'line names' : 'lines name'} a task file that ` +
+      `exists but ${untracked.length === 1 ? 'is' : 'are'} {b}not written as a link{b}, so ` +
+      `${untracked.length === 1 ? 'it isn\'t' : 'they aren\'t'} tracked:`
+    ));
+    for (const warning of untracked) {
+      console.log(`  ${warning.column}: ${warning.text}`);
+    }
+  }
+  if (other.length) {
+    console.log(
+      other.length === 1
+        ? "1 line in a column isn't a task link (preserved, but ignored):"
+        : `${other.length} lines in columns aren't task links (preserved, but ignored):`
+    );
+    for (const warning of other) {
+      console.log(`  ${warning.column}: ${warning.text}`);
+    }
+  }
+}
+
+/**
+ * Show tasks whose assigned user or comment author isn't a known contributor. These are advisory:
+ * contributors are a convenience list, not an enum, and every one of these tasks works exactly as it
+ * always has
+ * @param {object[]} warnings
+ */
+function showContributorWarnings(warnings) {
+  if (!warnings.length) {
+    return;
+  }
+
+  // One line per name rather than per task, because "Gordon appears in 12 tasks" is the useful shape
+  const byValue = new Map();
+  for (const warning of warnings) {
+    if (!byValue.has(warning.value)) {
+      byValue.set(warning.value, []);
+    }
+    byValue.get(warning.value).push(warning.task);
+  }
+  console.log(utility.replaceTags(
+    `${byValue.size} ${byValue.size === 1 ? 'name is' : 'names are'} used in tasks but ` +
+    `${byValue.size === 1 ? "isn't" : "aren't"} a {b}known contributor{b}:`
+  ));
+  for (const [value, tasks] of byValue) {
+    console.log(`  ${value}: ${tasks.join(', ')}`);
+  }
+  console.log(utility.replaceTags('Run {b}kanbn contributors --usage{b} for more detail.'));
+}
+
+/**
+ * Show rules that are legal but probably not what their author meant. A rule that is wrong in the
+ * file is an error rather than a warning, and is reported with the rest of them
+ * @param {object[]} warnings
+ */
+function showActionWarnings(warnings) {
+  if (!warnings.length) {
+    return;
+  }
+  console.log(utility.replaceTags(
+    `${warnings.length} ${warnings.length === 1 ? 'action rule needs' : 'action rules need'} ` +
+    'a {b}second look{b}:'
+  ));
+  for (const warning of warnings) {
+    console.log(`  ${warning.message}`);
+  }
+}
+
 /**
  * Show warnings about a multi-board workspace
  * @param {object[]} warnings
@@ -89,6 +180,35 @@ module.exports = async args => {
     }
   }
 
+  // Report lines in columns that aren't task links. Unlike the warnings above these apply to any
+  // workspace, so they're gathered whether or not it has more than one board
+  let columnContentWarnings = [];
+  try {
+    columnContentWarnings = await kanbn.findColumnContentWarnings();
+  } catch (error) {
+    utility.error(error);
+    return;
+  }
+
+  // Report action rules that work but probably don't do what their author meant
+  let actionWarnings = [];
+  try {
+    actionWarnings = await kanbn.findActionWarnings();
+  } catch (error) {
+    utility.error(error);
+    return;
+  }
+
+  // Report names used in tasks that the contributors list doesn't know about. A workspace with no
+  // contributors declared has none of these, so its output is exactly what it always was
+  let contributorWarnings = [];
+  try {
+    contributorWarnings = await kanbn.findContributorWarnings();
+  } catch (error) {
+    utility.error(error);
+    return;
+  }
+
   // Backfill missing started and completed dates
   if (args.fix) {
     let fixed;
@@ -99,6 +219,12 @@ module.exports = async args => {
       return;
     }
     if (!fixed.length) {
+      if (!args.json && (columnContentWarnings.length || contributorWarnings.length || actionWarnings.length)) {
+        showColumnContentWarnings(columnContentWarnings);
+        showContributorWarnings(contributorWarnings);
+        showActionWarnings(actionWarnings);
+        return;
+      }
       console.log('Everything OK, nothing to fix');
       return;
     }
@@ -124,9 +250,11 @@ module.exports = async args => {
   if (args.json) {
 
     // A multi-board workspace has warnings to report as well as drift, so JSON output carries both.
-    // With a single board it stays the bare drift list it has always been
-    if (multiBoard) {
-      console.log(JSON.stringify({ drift, warnings: boardWarnings }, null, 2));
+    // With a single board it stays the bare drift list it has always been - unless there are
+    // warnings, which have nowhere to go in a bare drift list and are worth more than the shape
+    const warnings = [...boardWarnings, ...columnContentWarnings, ...contributorWarnings, ...actionWarnings];
+    if (multiBoard || warnings.length) {
+      console.log(JSON.stringify({ drift, warnings }, null, 2));
       return;
     }
     if (drift.length) {
@@ -139,8 +267,17 @@ module.exports = async args => {
   if (drift.length) {
     showDrift(drift, false);
   }
+  showColumnContentWarnings(columnContentWarnings);
+  showContributorWarnings(contributorWarnings);
+  showActionWarnings(actionWarnings);
   showBoardWarnings(boardWarnings);
-  if (drift.length || boardWarnings.length) {
+  if (
+    drift.length ||
+    boardWarnings.length ||
+    columnContentWarnings.length ||
+    contributorWarnings.length ||
+    actionWarnings.length
+  ) {
     return;
   }
   console.log('Everything OK');

package/src/git-user-name.js

@@ -1,19 +1,9 @@
-const { execFileSync } = require('child_process');
+const gitUser = require('./git-user');
 
 /**
- * Get the git username of the current user, or null if it can't be found. This replaces the
- * git-user-name package, which depends on a version of parse-git-config with an unpatched
- * prototype pollution vulnerability
+ * Get the git username of the current user, or null if it can't be found
+ *
+ * Kept as a named module because it was the public entry point before git-user.js existed
  * @return {string|null} The git username, or null if git isn't available or no username is set
  */
-module.exports = () => {
-  try {
-    const username = execFileSync('git', ['config', 'user.name'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore']
-    }).trim();
-    return username || null;
-  } catch (error) {
-    return null;
-  }
-};
+module.exports = () => gitUser.name();

package/src/git-user.js

@@ -0,0 +1,55 @@
+const { execFileSync } = require('child_process');
+
+// Reading a git config value means spawning a process, and the current user is resolved from prompt
+// defaults that run in loops. The values can't change while a command is running, so they're read at
+// most once each per process
+const memo = {};
+
+/**
+ * Read a value from git config, or null if it can't be read. This replaces the git-user-name
+ * package, which depends on a version of parse-git-config with an unpatched prototype pollution
+ * vulnerability
+ * @param {string} key The git config key
+ * @return {?string} The value, or null if git isn't available or the value isn't set
+ */
+function gitConfig(key) {
+  if (!(key in memo)) {
+    try {
+      memo[key] = execFileSync('git', ['config', key], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore']
+      }).trim() || null;
+    } catch (error) {
+      memo[key] = null;
+    }
+  }
+  return memo[key];
+}
+
+module.exports = {
+
+  /**
+   * Get the git username of the current user, or null if it can't be found
+   * @return {?string} The git username
+   */
+  name() {
+    return gitConfig('user.name');
+  },
+
+  /**
+   * Get the git email address of the current user, or null if it can't be found
+   * @return {?string} The git email address
+   */
+  email() {
+    return gitConfig('user.email');
+  },
+
+  /**
+   * Forget the memoized values. Only useful in tests, where git config is faked per case
+   */
+  clearCache() {
+    for (const key of Object.keys(memo)) {
+      delete memo[key];
+    }
+  }
+};