@basementuniverse/kanbn 2.0.0 → 2.5.0

package/src/controller/task.js

@@ -1,4 +1,4 @@
-const kanbn = require("../main");
+const workspace = require("../main");
 const utility = require("../utility");
 const parseTask = require("../parse-task");
 const marked = require("marked");
@@ -6,19 +6,31 @@ const markedTerminalRenderer = require("marked-terminal");
 
 /**
  * Show task information
+ * @param {object} kanbn The board-scoped kanbn instance
  * @param {string} taskId
+ * @param {Record<string, string>} boards The boards this task appears on, and the column on each
+ * @param {boolean} json
  */
-function showTask(taskId, json = false) {
+function showTask(kanbn, taskId, boards, json = false) {
   kanbn
     .getTask(taskId)
     .then((task) => {
       if (json) {
-        console.log(JSON.stringify(task, null, 2));
+        console.log(JSON.stringify({ ...task, boards }, null, 2));
       } else {
         marked.setOptions({
           renderer: new markedTerminalRenderer(),
         });
-        console.log(marked(parseTask.json2md(task)));
+
+        // Board membership isn't part of the task file - boards own membership, not tasks - so it's
+        // appended here rather than rendered from the task itself. Only worth showing once there is
+        // more than one board to be a member of
+        const boardSlugs = Object.keys(boards);
+        const boardsSection =
+          boardSlugs.length > 1
+            ? `\n## Boards\n\n${boardSlugs.map((slug) => `- ${slug}: ${boards[slug]}`).join("\n")}\n`
+            : "";
+        console.log(marked.parse(parseTask.json2md(task) + boardsSection));
       }
     })
     .catch((error) => {
@@ -27,9 +39,10 @@ function showTask(taskId, json = false) {
 }
 
 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 kanbn = await utility.resolveBoard(workspace, args);
+  if (kanbn === null) {
     return;
   }
 
@@ -40,14 +53,25 @@ 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;
   }
 
-  // Show the task
-  showTask(taskId, args.json);
+  // Show the task, along with the boards it appears on
+  showTask(kanbn, taskId, await workspace.findTaskBoards(taskId), args.json);
 };

package/src/controller/validate.js

@@ -1,7 +1,10 @@
-const kanbn = require('../main');
+const workspace = require('../main');
 const utility = require('../utility');
 const yaml = require('yamljs');
 
+// The board this command targets - set from --board before anything else runs
+let kanbn = workspace;
+
 /**
  * Show a list of tasks whose dates disagree with the column they're in
  * @param {object[]} drift
@@ -27,18 +30,127 @@ 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
+ */
+function showBoardWarnings(warnings) {
+  if (!warnings.length) {
+    return;
+  }
+  console.log(
+    `${warnings.length} ${warnings.length === 1 ? 'warning' : 'warnings'}:`
+  );
+  for (const warning of warnings) {
+    console.log(`  ${warning.board === null ? 'workspace' : warning.board}: ${warning.message}`);
+  }
+}
+
 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;
 
-  // Validate kanbn files
+  // Validate kanbn files, on this board or on every board in the workspace
+  const allBoards = !!args['all-boards'];
   let result;
   try {
-    result = await kanbn.validate(args.save);
+    result = allBoards ? await kanbn.validateAllBoards(args.save) : await kanbn.validate(args.save);
   } catch (error) {
     utility.error(error);
     return;
@@ -54,6 +166,49 @@ module.exports = async args => {
     return;
   }
 
+  // Report multi-board problems. These are warnings rather than errors: each one describes a
+  // workspace that still works, just not the way its author probably meant it to. A workspace with
+  // one board has none of these problems to have, and its output is exactly what it always was
+  const multiBoard = (await kanbn.listBoards()).length > 1;
+  let boardWarnings = [];
+  if (multiBoard) {
+    try {
+      boardWarnings = await kanbn.findBoardWarnings();
+    } catch (error) {
+      utility.error(error);
+      return;
+    }
+  }
+
+  // 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;
@@ -64,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;
     }
@@ -86,8 +247,37 @@ module.exports = async args => {
     utility.error(error);
     return;
   }
+  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 - 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) {
+      showDrift(drift, true);
+      return;
+    }
+    console.log('Everything OK');
+    return;
+  }
   if (drift.length) {
-    showDrift(drift, args.json);
+    showDrift(drift, false);
+  }
+  showColumnContentWarnings(columnContentWarnings);
+  showContributorWarnings(contributorWarnings);
+  showActionWarnings(actionWarnings);
+  showBoardWarnings(boardWarnings);
+  if (
+    drift.length ||
+    boardWarnings.length ||
+    columnContentWarnings.length ||
+    contributorWarnings.length ||
+    actionWarnings.length
+  ) {
     return;
   }
   console.log('Everything OK');

package/src/git-user-name.js

@@ -0,0 +1,9 @@
+const gitUser = require('./git-user');
+
+/**
+ * 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 = () => 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];
+    }
+  }
+};