@basementuniverse/kanbn 2.1.0 → 2.5.0

package/src/parse-index.js

@@ -112,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: {
@@ -171,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
@@ -198,7 +378,7 @@ module.exports = {
    * @return {object}
    */
   md2json(data) {
-    let name = '', description = '', options = {}, columns = {};
+    let name = '', description = '', options = {}, columns = {}, columnContent = {};
     try {
 
       // Check data type
@@ -256,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;
   },
 
   /**
@@ -323,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/utility.js

@@ -1,3 +1,5 @@
+const fuzzy = require('fuzzy');
+
 module.exports = (() => {
   const tags = {
     b: 'bold',
@@ -38,6 +40,12 @@ module.exports = (() => {
         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;
@@ -75,7 +83,7 @@ module.exports = (() => {
 
       const targets = [];
       for (let i = 0; i < slugs.length; i++) {
-        const kanbn = await this.resolveBoard(workspace, { board: slugs[i] });
+        const kanbn = await this.resolveBoard(workspace, { board: slugs[i], actions: args.actions });
         if (kanbn === null) {
           return null;
         }
@@ -148,6 +156,76 @@ module.exports = (() => {
       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
@@ -168,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