@basementuniverse/kanbn 1.1.1 → 2.1.0

package/src/parse-index.js

@@ -24,6 +24,23 @@ function validateOptions(options) {
         type: 'array',
         items: { type: 'string' }
       },
+      '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: {

package/src/parse-markdown.js

@@ -26,7 +26,9 @@ module.exports = function parseMarkdown(markdown) {
     parsed[headings[i].title] = {
       heading: headings[i].heading,
       content: markdown.slice(
-        headings[i].index + headings[i].heading.length + 1,
+        // The + 1 skips the newline that ends the heading line; the synthetic 'raw' entry for
+        // content before the first heading has no heading line, so it starts at index 0
+        headings[i].index + headings[i].heading.length + (headings[i].heading ? 1 : 0),
         i < headings.length - 1
           ? headings[i + 1].index
           : undefined

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' }
@@ -239,6 +241,11 @@ function validateHistoryFromJSON(history) {
 
 /**
  * Validate required fields in a history event
+ *
+ * An event with an unrecognised type is left alone rather than rejected: a task file written by a
+ * newer version of kanbn may contain event types this version doesn't know about, and refusing to
+ * parse the whole task would make the file unreadable. Unknown events are preserved on write and
+ * ignored when history is replayed.
  * @param {object} historyEvent
  */
 function validateHistoryEvent(historyEvent) {
@@ -254,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');
@@ -275,10 +289,25 @@ function validateHistoryEvent(historyEvent) {
       }
       break;
     default:
-      throw new Error(`unsupported history event type "${historyEvent.type}"`);
+      break;
   }
 }
 
+/**
+ * History event keys that this version understands, in the order they should be written
+ */
+const KNOWN_HISTORY_EVENT_KEYS = [
+  'type',
+  'date',
+  'column',
+  'fromColumn',
+  'toColumn',
+  'board',
+  'fromProgress',
+  'toProgress',
+  'author'
+];
+
 module.exports = {
 
   /**
@@ -651,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}`);
               }
@@ -660,6 +695,14 @@ module.exports = {
               if ('author' in historyEvent && historyEvent.author) {
                 historyEventOutput.push(`author: ${historyEvent.author}`);
               }
+
+              // Write back any keys this version doesn't recognise, so that a file written by a
+              // newer version of kanbn survives a read/write cycle here without losing data
+              for (const key of Object.keys(historyEvent)) {
+                if (KNOWN_HISTORY_EVENT_KEYS.indexOf(key) === -1 && historyEvent[key] !== undefined) {
+                  historyEventOutput.push(`${key}: ${historyEvent[key]}`);
+                }
+              }
               return `- ${historyEventOutput.map((v, i) => i > 0 ? `  ${v}` : v).join('\n')}`;
             }).join('\n')
           );

package/src/utility.js

@@ -19,6 +19,155 @@ 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);
+      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] });
+        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}`));
+    },
+
+    /**
+     * 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
+     * @param {object[]} drift Drift entries from kanbn.getDateDrift()
+     * @param {boolean} show False to suppress the hint
+     */
+    showDateDriftHint(drift, show = true) {
+      if (!show || !drift.length) {
+        return;
+      }
+      const fixable = drift.filter(d => d.fixable).length;
+      const summary =
+        `${drift.length} ${drift.length === 1 ? 'task has' : 'tasks have'} dates that don't match ` +
+        `${drift.length === 1 ? 'its' : 'their'} column`;
+      console.log(this.replaceTags(
+        `\n{d}${summary}${fixable ? ' - run{d} {b}kanbn validate --fix{b}' : '{d}'}` +
+        (fixable ? ` {d}to fill in the missing ${fixable === 1 ? 'date' : 'dates'}{d}` : '')
+      ));
+    },
+
     /**
      * Convert a string to simplified paramcase, e.g:
      *  PascalCase -> pascalcase
@@ -34,7 +183,12 @@ module.exports = (() => {
         )
         .split(/[\s!?.,@:;|\\/"'`£$%\^&*{}[\]()<>~#+\-=_¬]+/g)
         .join('-')
-        .replace(/(^-|-$)/g, '');
+        .replace(/(^-|-$)/g, '')
+        // The word-boundary replacement above only matches an uppercase run that is followed by
+        // another character, so a trailing capital ("Task A" -> "task-A") and any non-ASCII capital
+        // ("Ünïcodé" -> "Ünïcodé") would otherwise survive. Board slugs use this function, so ids
+        // must be lowercase throughout.
+        .toLowerCase();
     },
 
     /**
@@ -141,6 +295,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

package/PLANS.md

@@ -1,9 +0,0 @@
-# Future plans
-
-* multiple boards
-* epics / stories
-* swimlanes
-* list of contributors in index config
-    * dropdown in vsce taskeditor
-    * optional autopopulate from git user
-* web UI