@basementuniverse/kanbn 2.0.0 → 2.5.0

package/src/parse-index.js

@@ -27,6 +27,20 @@ function validateOptions(options) {
       'startedField': { type: 'string' },
       'completedField': { type: 'string' },
       'verbose': { type: 'boolean' },
+      'defaultBoard': { type: 'string' },
+      'boards': {
+        type: 'object',
+        properties: {
+          'exclude': {
+            type: 'array',
+            items: { type: 'string' }
+          },
+          'order': {
+            type: 'array',
+            items: { type: 'string' }
+          }
+        }
+      },
       'sprints': {
         type: 'array',
         items: {
@@ -98,6 +112,66 @@ function validateOptions(options) {
           required: ['name', 'type']
         }
       },
+      'contributors': {
+        type: 'array',
+        items: {
+          oneOf: [
+
+            // A bare name, which is all most workspaces ever need
+            { type: 'string' },
+            {
+              type: 'object',
+              properties: {
+                'name': { type: 'string' },
+                'displayName': { type: 'string' },
+                'email': { type: 'string' },
+                'aliases': {
+                  type: 'array',
+                  items: { type: 'string' }
+                },
+                'colour': { type: 'string' }
+              },
+              required: ['name']
+            }
+          ]
+        }
+      },
+      'actionsFile': { type: 'string' },
+
+      // The rules themselves are only shape-checked here: what they mean is checked by
+      // actions.findRuleErrors(), which knows the event names, the verbs and this board's columns and
+      // can say what is wrong rather than which sub-schema failed
+      'actions': {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            'name': { type: 'string' },
+            'on': { type: 'string' },
+            'when': { type: 'object' },
+            'for': {
+              type: 'object',
+              properties: {
+                'related': { type: 'string' },
+                'direction': {
+                  type: 'string',
+                  enum: [
+                    'incoming',
+                    'outgoing'
+                  ]
+                },
+                'where': { type: 'object' }
+              }
+            },
+            'anyBoard': { type: 'boolean' },
+            'then': {
+              type: 'array',
+              items: { type: 'object' }
+            }
+          },
+          required: ['on', 'then']
+        }
+      },
       'views': {
         type: 'array',
         items: {
@@ -157,6 +231,126 @@ function validateOptions(options) {
   }
 }
 
+/**
+ * Get the task id from a column list item, or null if the item isn't a task link
+ *
+ * A task link is a list item that begins with a markdown link, e.g. `- [task-id](tasks/task-id.md)`.
+ * Anything else - a bare title, a checkbox item, a note - is content that this file preserves but
+ * doesn't interpret
+ * @param {object} item A list item token
+ * @return {?string} The task id, or null if this item isn't a task link
+ */
+function taskIdFromListItem(item) {
+  const block = item.tokens && item.tokens[0];
+  const inline = block && block.tokens && block.tokens[0];
+  return inline && inline.type === 'link' ? inline.text : null;
+}
+
+/**
+ * Remove trailing whitespace from a markdown token's raw source, keeping any internal line breaks so
+ * that multi-line items survive a read/write cycle intact
+ * @param {string} raw
+ * @return {string}
+ */
+function trimRaw(raw) {
+  return String(raw).replace(/\s+$/, '');
+}
+
+/**
+ * Split a column's markdown into the task ids it references and everything else it contains
+ *
+ * Every top-level token is considered, not just the first list: a single line using a different
+ * bullet character splits one list into several, and reading only the first one silently dropped
+ * every task after it. Content that isn't a task link is recorded with the position it occupied so
+ * that it can be written back where the user put it
+ * @param {string} markdown The column's markdown content
+ * @return {{taskIds: string[], content: object[]}}
+ */
+function parseColumnContent(markdown) {
+  const taskIds = [], content = [];
+  if (!markdown) {
+    return { taskIds, content };
+  }
+  let position = 0;
+  for (const token of marked.lexer(markdown)) {
+    if (token.type === 'space') {
+      continue;
+    }
+    if (token.type === 'list') {
+      for (const item of token.items) {
+        const taskId = taskIdFromListItem(item);
+        if (taskId === null) {
+          content.push({ position, text: item.text.trim(), raw: trimRaw(item.raw) });
+        } else {
+          taskIds.push(taskId);
+        }
+        position++;
+      }
+      continue;
+    }
+
+    // A paragraph, quote, code block or anything else that isn't a list is content as well. It's
+    // written back surrounded by blank lines so that it doesn't merge into a neighbouring list
+    content.push({
+      position,
+      text: ('text' in token ? String(token.text) : trimRaw(token.raw)).trim(),
+      raw: trimRaw(token.raw),
+      block: true
+    });
+    position++;
+  }
+  return { taskIds, content };
+}
+
+/**
+ * Rebuild a column's markdown from its task ids and preserved content
+ * @param {string[]} taskIds
+ * @param {object[]} content
+ * @return {string} The column's markdown content
+ */
+function buildColumnContent(taskIds, content) {
+  const lines = taskIds.map(taskId => `- [${taskId}](tasks/${taskId}.md)`);
+
+  // Positions were recorded against the column as it was read. Tasks move, so a position can end up
+  // past the end of the column - clamping keeps the line in the column it was written in
+  for (const entry of [...content].sort((a, b) => a.position - b.position)) {
+    lines.splice(
+      Math.min(entry.position, lines.length),
+      0,
+      entry.block ? `\n${entry.raw}\n` : entry.raw
+    );
+  }
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+/**
+ * Validate the preserved column content object
+ * @param {object} columnContent
+ */
+function validateColumnContent(columnContent) {
+  const result = validate(columnContent, {
+    type: 'object',
+    patternProperties: {
+      '^[\w ]+$': {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            'position': { type: 'number' },
+            'text': { type: 'string' },
+            'raw': { type: 'string' },
+            'block': { type: 'boolean' }
+          },
+          required: ['position', 'raw']
+        }
+      }
+    }
+  });
+  if (result.errors.length) {
+    throw new Error(result.errors.map(error => `${error.property} ${error.message}`).join('\n'));
+  }
+}
+
 /**
  * Validate the columns object
  * @param {object} columns
@@ -184,7 +378,7 @@ module.exports = {
    * @return {object}
    */
   md2json(data) {
-    let name = '', description = '', options = {}, columns = {};
+    let name = '', description = '', options = {}, columns = {}, columnContent = {};
     try {
 
       // Check data type
@@ -242,26 +436,32 @@ module.exports = {
 
       // Parse columns
       const columnNames = Object.keys(index).filter(column => ['raw', 'Options', name].indexOf(column) === -1);
-      if (columnNames.length) {
-        columns = Object.fromEntries(columnNames.map(columnName => {
-          try {
-            return [
-              columnName,
-              index[columnName].content
-                ? marked.lexer(index[columnName].content)[0].items.map(item => item.tokens[0].tokens[0].text)
-                : []
-            ];
-          } catch (error) {
-            throw new Error(`column "${columnName}" must contain a list`);
-          }
-        }));
+      for (const columnName of columnNames) {
+        let parsed = null;
+        try {
+          parsed = parseColumnContent(index[columnName].content);
+        } catch (error) {
+          throw new Error(`unable to parse column "${columnName}" (${error.message})`);
+        }
+        columns[columnName] = parsed.taskIds;
+
+        // Anything in the column that isn't a task link is kept verbatim rather than rejected, so
+        // that a hand-written note or a mistyped link is preserved instead of being thrown away the
+        // next time the board is saved. Nothing else in kanbn reads it
+        if (parsed.content.length) {
+          columnContent[columnName] = parsed.content;
+        }
       }
     } catch (error) {
       throw new Error(`Unable to parse index: ${error.message}`);
     }
 
     // Assemble index object
-    return { name, description, options, columns };
+    const result = { name, description, options, columns };
+    if (Object.keys(columnContent).length) {
+      result.columnContent = columnContent;
+    }
+    return result;
   },
 
   /**
@@ -309,11 +509,13 @@ module.exports = {
       }
       validateColumns(data.columns);
 
-      // Add columns
+      // Add columns, putting any preserved non-task content back where it was found
+      const columnContent = 'columnContent' in data && data.columnContent !== null ? data.columnContent : {};
+      validateColumnContent(columnContent);
       for (let column in data.columns) {
         result.push(
           `## ${column}`,
-          data.columns[column].map(task => `- [${task}](tasks/${task}.md)`).join('\n')
+          buildColumnContent(data.columns[column], column in columnContent ? columnContent[column] : [])
         );
       }
     } catch (error) {

package/src/parse-task.js

@@ -200,6 +200,7 @@ function validateHistoryFromMarkdown(history) {
         'column': { type: 'string' },
         'fromColumn': { type: 'string' },
         'toColumn': { type: 'string' },
+        'board': { type: 'string' },
         'author': { type: 'string' },
         'fromProgress': { oneOf: [{ type: 'number' }, { type: 'string' }] },
         'toProgress': { oneOf: [{ type: 'number' }, { type: 'string' }] }
@@ -226,6 +227,7 @@ function validateHistoryFromJSON(history) {
         'column': { type: 'string' },
         'fromColumn': { type: 'string' },
         'toColumn': { type: 'string' },
+        'board': { type: 'string' },
         'author': { type: 'string' },
         'fromProgress': { type: 'number' },
         'toProgress': { type: 'number' }
@@ -259,6 +261,13 @@ function validateHistoryEvent(historyEvent) {
         throw new Error('created history event is missing column');
       }
       break;
+    case 'added':
+      if (!historyEvent.column) {
+        throw new Error('added history event is missing column');
+      }
+      break;
+    case 'removed':
+      break;
     case 'moved':
       if (!historyEvent.fromColumn || !historyEvent.toColumn) {
         throw new Error('moved history event is missing fromColumn or toColumn');
@@ -293,6 +302,7 @@ const KNOWN_HISTORY_EVENT_KEYS = [
   'column',
   'fromColumn',
   'toColumn',
+  'board',
   'fromProgress',
   'toProgress',
   'author'
@@ -670,6 +680,12 @@ module.exports = {
               if ('toColumn' in historyEvent) {
                 historyEventOutput.push(`toColumn: ${historyEvent.toColumn}`);
               }
+
+              // Events on the main board carry no board key, so existing task files - and files
+              // written by single-board workspaces - are byte-identical to what they always were
+              if ('board' in historyEvent && historyEvent.board) {
+                historyEventOutput.push(`board: ${historyEvent.board}`);
+              }
               if ('fromProgress' in historyEvent) {
                 historyEventOutput.push(`fromProgress: ${historyEvent.fromProgress}`);
               }

package/src/utility.js

@@ -1,3 +1,5 @@
+const fuzzy = require('fuzzy');
+
 module.exports = (() => {
   const tags = {
     b: 'bold',
@@ -19,6 +21,211 @@ module.exports = (() => {
       !dontExit && process.env.KANBN_ENV !== 'test' && process.exit(1);
     },
 
+    /**
+     * Resolve the board a command targets and return a Kanbn instance scoped to it, printing an
+     * error and returning null if the workspace or the board doesn't exist
+     * @param {object} workspace The workspace-scoped Kanbn instance
+     * @param {object} args The parsed command arguments
+     * @return {Promise<object|null>} A board-scoped Kanbn instance, or null if it can't be resolved
+     */
+    async resolveBoard(workspace, args) {
+
+      // Sprint numbers and names are relative to one board's list, so an aggregate across boards
+      // can't resolve them. Refuse rather than guess
+      if (args['all-boards'] && args.sprint) {
+        this.error(
+          '{b}--sprint{b} and {b}--all-boards{b} cannot be used together, because sprint numbers ' +
+          'and names are relative to a single board'
+        );
+        return null;
+      }
+      const kanbn = await workspace.boardFromArgs(args);
+
+      // Actions are declarative rules with no code execution, so this is a way around a misbehaving
+      // rule rather than a safety control
+      if (args.actions === false || args['no-actions'] === true) {
+        kanbn.actionsEnabled = false;
+      }
+      if (!await kanbn.workspaceInitialised()) {
+        this.error('Kanbn has not been initialised in this folder\nTry running: {b}kanbn init{b}');
+        return null;
+      }
+      if (!await kanbn.initialised()) {
+        this.error(
+          `Board "${await kanbn.resolveBoardSlug()}" doesn't exist\n` +
+          'Try running: {b}kanbn boards{b}'
+        );
+        return null;
+      }
+      return kanbn;
+    },
+
+    /**
+     * Resolve the boards a command targets, along with the column to use on each. `-b` is repeatable
+     * and pairs positionally with `-c`: board i uses the i-th `-c` if there is one, otherwise the
+     * first `-c`, otherwise that board's first column (Q5). Prints an error and returns null if any
+     * board can't be resolved
+     * @param {object} workspace The workspace-scoped Kanbn instance
+     * @param {object} args The parsed command arguments
+     * @return {Promise<object[]|null>} One entry per target board, or null on error
+     */
+    async resolveBoardTargets(workspace, args) {
+      const boardArgs = args.board === undefined
+        ? []
+        : this.arrayArg(args.board).filter(slug => slug !== undefined && slug !== '');
+      const columnArgs = args.column === undefined ? [] : this.arrayArg(args.column);
+      const slugs = boardArgs.length ? boardArgs : [await workspace.resolveTargetBoard(null)];
+
+      // With a single target board an unknown column is an error, exactly as it has always been.
+      // Falling back only makes sense when several boards are targeted at once, where a column can
+      // legitimately exist on one and not another
+      const allowFallback = slugs.length > 1;
+
+      const targets = [];
+      for (let i = 0; i < slugs.length; i++) {
+        const kanbn = await this.resolveBoard(workspace, { board: slugs[i], actions: args.actions });
+        if (kanbn === null) {
+          return null;
+        }
+        let index;
+        try {
+          index = await kanbn.getIndex();
+        } catch (error) {
+          this.error(error);
+          return null;
+        }
+        const columnNames = Object.keys(index.columns);
+        if (!columnNames.length) {
+          this.error('No columns defined in the index\nTry running {b}kanbn init -c "column name"{b}');
+          return null;
+        }
+
+        const requestedColumn = columnArgs.length
+          ? (columnArgs[i] !== undefined ? columnArgs[i] : columnArgs[0])
+          : null;
+        let columnName = requestedColumn === null ? columnNames[0] : requestedColumn;
+        let fallback = false;
+        if (!(columnName in index.columns)) {
+          if (!allowFallback) {
+            this.error(`Column "${columnName}" doesn't exist`);
+            return null;
+          }
+          columnName = columnNames[0];
+          fallback = true;
+        }
+        targets.push({
+          kanbn,
+          index,
+          slug: await kanbn.resolveBoardSlug(),
+          columnName,
+          requestedColumn,
+          fallback
+        });
+      }
+      return targets;
+    },
+
+    /**
+     * Tell the user when a target board didn't have the column that was asked for, so that a task
+     * quietly landing somewhere else is never a surprise
+     * @param {object[]} targets Targets from resolveBoardTargets()
+     * @param {boolean} show False to suppress the notice
+     */
+    showColumnFallbackNotices(targets, show = true) {
+      if (!show) {
+        return;
+      }
+      for (const target of targets.filter(t => t.fallback)) {
+        console.log(this.replaceTags(
+          `{d}Board "${target.slug}" has no column "${target.requestedColumn}" - using "${target.columnName}"{d}`
+        ));
+      }
+    },
+
+    /**
+     * Show a hint about how many boards this workspace has, so that a command showing one board
+     * doesn't look like it's showing everything. Suppressed for machine-readable output and when the
+     * board sets verbose to false
+     * @param {object[]} boards The list of boards
+     * @param {boolean} show False to suppress the hint
+     */
+    showBoardCountHint(boards, show = true) {
+      if (!show || boards.length < 2) {
+        return;
+      }
+      console.log(this.replaceTags(`\n{d}${boards.length} boards available -{d} {b}kanbn boards{b}`));
+    },
+
+    /**
+     * Resolve a string to exactly one simple task on a board, for the commands that accept one.
+     * Real tasks always win, so this should only be called once no task has matched
+     * @param {object} kanbn The board-scoped Kanbn instance
+     * @param {string} input The title to match
+     * @param {Error|string} taskError The error to report if nothing matches, i.e. the error the
+     * command would have printed before simple tasks existed
+     * @param {?object[]} [matches=null] Matches already found, to save looking them up again
+     * @return {Promise<?object>} The matching simple task, or null if the error has been reported
+     */
+    async resolveSimpleTask(kanbn, input, taskError, matches = null) {
+      if (matches === null) {
+        try {
+          matches = await kanbn.findSimpleTasks(input);
+        } catch (error) {
+          this.error(error);
+          return null;
+        }
+      }
+      if (!matches.length) {
+        this.error(taskError);
+        return null;
+      }
+
+      // Two lines with the same title are two different lines. Picking one of them silently would
+      // eventually move or delete the wrong one
+      if (matches.length > 1) {
+        this.error(
+          `"${input}" matches ${matches.length} simple tasks:\n` +
+          matches.map(match => `  "${match.text}" in column "${match.column}"`).join('\n') +
+          '\nEdit the board file directly, or rename one of them'
+        );
+        return null;
+      }
+      return matches[0];
+    },
+
+    /**
+     * Report rules that were skipped during an operation
+     *
+     * A rule that quietly stops working is worse than no rule, so these go to stderr and aren't
+     * suppressed by verbose - the operation itself succeeded, which is why they aren't errors
+     * @param {object} kanbn The board-scoped Kanbn instance the operation ran on
+     */
+    showActionWarnings(kanbn) {
+      const warnings = (kanbn && kanbn.lastActionWarnings) || [];
+      if (!warnings.length) {
+        return;
+      }
+      for (const warning of warnings) {
+        console.error(this.replaceTags(`{d}action:{d} ${warning}`));
+      }
+    },
+
+    /**
+     * Show a hint about tasks that a board references but which have no task file. These are skipped
+     * rather than fatal, so the hint is the only sign that the board is showing less than it lists
+     * @param {object[]} missing Missing task entries from kanbn.findMissingTaskFiles()
+     * @param {boolean} show False to suppress the hint
+     */
+    showMissingTaskFilesHint(missing, show = true) {
+      if (!show || !missing.length) {
+        return;
+      }
+      const summary =
+        `${missing.length} ${missing.length === 1 ? 'task has' : 'tasks have'} no task file and ` +
+        `${missing.length === 1 ? 'was' : 'were'} skipped`;
+      console.log(this.replaceTags(`\n{d}${summary} - run{d} {b}kanbn validate{b} {d}for details{d}`));
+    },
+
     /**
      * Show a hint about tasks whose dates don't match the column they're in. Hints are suppressed
      * for machine-readable output and when the board sets verbose to false
@@ -39,6 +246,62 @@ module.exports = (() => {
       ));
     },
 
+    /**
+     * Build the prompt definition for a task's assigned user
+     *
+     * With contributors configured this is an autocomplete over the list, which is where the typo
+     * mitigation comes from; without them it's the free-text input it has always been. Free text is
+     * accepted either way - contributors are advisory, never an enum, so a name that isn't in the
+     * list is still a perfectly good answer
+     * @param {object} options The prompt properties to merge in, i.e. name, message, default, when
+     * @param {object[]} contributors The workspace's normalised contributors
+     * @return {object} A prompt definition
+     */
+    assignedPrompt(options, contributors) {
+      if (!contributors.length) {
+        return { type: 'input', ...options };
+      }
+
+      // Suggestions are the canonical names, because that's the value written into the task file
+      const names = contributors.map(contributor => contributor.name);
+      return {
+        type: 'autocomplete',
+        suggestOnly: true,
+        source: (answers, input) => Promise.resolve(
+          fuzzy.filter(input || '', names).map(result => result.string)
+        ),
+        ...options
+      };
+    },
+
+    /**
+     * Expand "@me" in a filter value to the current user
+     *
+     * The substitution is kept here, at the argument-parsing boundary: "@me" means something when
+     * filtering and nothing at all when setting a value, and a literal "@me" in a task file is
+     * nonsense nobody needs supported
+     * @param {object} kanbn The board-scoped Kanbn instance
+     * @param {string|string[]} value The filter value from the arguments
+     * @return {Promise<string|string[]|null>} The expanded value, or null if "@me" can't be resolved
+     */
+    async expandCurrentUser(kanbn, value) {
+      const isMe = v => typeof v === 'string' && v.trim() === '@me';
+      const values = this.arrayArg(value);
+      if (!values.some(isMe)) {
+        return value;
+      }
+      const currentUser = await kanbn.currentUser();
+      if (!currentUser) {
+        this.error(
+          "Unable to work out who you are, so {b}@me{b} can't be resolved\n" +
+          'Set {b}KANBN_USER{b}, or set a git username with {b}git config user.name "your name"{b}'
+        );
+        return null;
+      }
+      const expanded = values.map(v => (isMe(v) ? currentUser : v));
+      return Array.isArray(value) ? expanded : expanded[0];
+    },
+
     /**
      * Convert a string to simplified paramcase, e.g:
      *  PascalCase -> pascalcase
@@ -166,6 +429,17 @@ module.exports = (() => {
       return s;
     },
 
+    /**
+     * Coerce a terminal width into a usable number. The terminal width is unavailable when stdout
+     * isn't a TTY (i.e. when the output is piped or redirected), so fall back to a default
+     * @param {any} width The reported terminal width
+     * @param {number} [fallback=80] The width to use when the reported width is unusable
+     * @return {number} A usable terminal width
+     */
+    terminalWidth(width, fallback = 80) {
+      return Number.isInteger(width) && width > 0 ? width : fallback;
+    },
+
     /**
      * Zip 2 arrays together, i.e. ([1, 2, 3], [a, b, c]) => [[1, a], [2, b], [3, c]]
      * @param {any[]} a