@basementuniverse/kanbn 2.5.0 → 2.5.3

package/docs/api.md

@@ -0,0 +1,227 @@
+# Library API
+
+This document is for programs that use `@basementuniverse/kanbn` as a dependency, rather than the `kanbn` CLI. For the file formats that the library
+reads and writes, see the [board](index-structure.md) and [task](task-structure.md) structure docs.
+
+## Installation
+
+```bash
+npm install @basementuniverse/kanbn
+```
+
+## Importing
+
+The package's default export is the CLI entry point (an async function with no return value), used
+by the `kanbn` executable. Library consumers should use the named `Kanbn` export instead:
+
+```js
+const { Kanbn } = require('@basementuniverse/kanbn');
+```
+
+```ts
+import { Kanbn } from '@basementuniverse/kanbn';
+```
+
+Every method on `Kanbn` is documented with its parameter and return types in the package's shipped
+type declarations (`src/main.d.ts`, referenced by the `types` field in `package.json`), so
+TypeScript consumers get full IntelliSense without any extra shim.
+
+## Creating an instance
+
+```js
+const kanbn = new Kanbn();
+```
+
+- The constructor takes an optional `root` (the directory to treat as the current working
+  directory, defaulting to `process.cwd()`) and an `options` object: `{ board?: string, caches?:
+  any, actions?: boolean }`.
+- `options.board` scopes the instance to a secondary board by slug; omit it (or pass `"main"` /
+  `"default"`) to target the main board. Use `kanbn.board(slug)` to get a scoped copy of an
+  existing instance instead of constructing a new one — this shares config caching.
+- `options.actions` defaults to `true`. Pass `false`, or call `kanbn.withoutActions()`, to get an
+  instance that never runs [action rules](actions.md) — useful for tooling that shouldn't trigger
+  side effects.
+- A workspace must be initialised before most methods will work. Check with `initialised()` and
+  set one up with `initialise()`:
+
+```js
+const kanbn = new Kanbn();
+if (!(await kanbn.initialised())) {
+  await kanbn.initialise({ name: 'My project' });
+}
+```
+
+Methods that operate on a workspace throw an `Error` (with a message such as `"Not initialised in
+this folder"`) rather than returning an error value, so wrap calls in `try`/`catch` or let promise
+rejections propagate.
+
+## Method reference
+
+Methods are grouped by what they operate on. See `src/main.d.ts` for full parameter and return
+types, including the shapes of `task`, `index`, `board`, `contributor` and other objects used
+below.
+
+### Workspace lifecycle
+
+| Method | Description |
+| --- | --- |
+| `initialised()` | Whether the current working directory has been initialised |
+| `workspaceInitialised()` | Whether the workspace has been initialised, regardless of which board this instance is scoped to |
+| `initialise(options?)` | Initialise a kanbn board in the current working directory |
+| `getMainFolder()` | The `.kanbn` folder path for the current working directory |
+| `removeAll()` | Delete the entire `.kanbn` folder |
+
+### Configuration
+
+| Method | Description |
+| --- | --- |
+| `configExists()` | Whether a separate config file exists |
+| `getConfig()` | Configuration settings from the config file, or `null` if there isn't one |
+| `saveConfig(config)` | Save configuration data to a separate config file |
+| `clearConfigCache()` | Clear cached config so the next read hits disk again |
+| `getWorkspaceOptions()` | Workspace-scoped options, from the config file or the main board's front matter |
+| `loadWorkspaceOptions()` | Workspace options along with whether they came from a config file |
+| `getFolderName()` / `getIndexFileName()` / `getTaskFolderName()` / `getArchiveFolderName()` | Configured folder and file names |
+
+### Boards
+
+A workspace can have one main board plus any number of secondary boards sharing the same pool of
+task files — see [Multiple Boards](multiple-boards.md).
+
+| Method | Description |
+| --- | --- |
+| `board(slug?)` | Get a copy of this instance scoped to another board (alias: `withBoard(slug?)`) |
+| `listBoards()` | Find all boards in the workspace |
+| `getBoardsSummary()` | List boards with column/task counts, completion percentage and last modified date |
+| `boardExists(slug)` | Whether a board exists |
+| `createBoard(slug, options?)` | Create a new secondary board |
+| `initialiseBoard(slug, options?)` | Create a secondary board, or update an existing one |
+| `deleteBoard(slug)` | Delete a board file; returns ids of tasks that are no longer on any board |
+| `renameBoard(slug, newSlug, newName?)` | Rename a board |
+| `findOrphanedTasks(slug)` | Tasks that would become untracked if a board were deleted |
+| `getCrossBoardTasks(allTasks?)` | Every task that appears on more than one board, with the column it occupies on each |
+| `findTaskBoards(taskId)` | Every board that references a task, and the column it occupies on each (alias: `getTaskBoardColumns(taskId)`) |
+| `getIndex()` | The index (board) this instance is scoped to, as an object |
+| `getBoardsConfig()` | The boards config from the config file: exclude list and display order |
+
+### Tasks
+
+| Method | Description |
+| --- | --- |
+| `getTask(taskId)` | Get a task as an object |
+| `createTask(taskData, columnName)` | Create a task file and add it to the index |
+| `updateTask(taskId, taskData, columnName?)` | Update an existing task, optionally moving it |
+| `renameTask(taskId, newTaskName)` | Rename a task (changes its id and file name) |
+| `moveTask(taskId, columnName, position?, relative?, add?)` | Move a task between columns |
+| `deleteTask(taskId, removeFile?, allBoards?)` | Remove a task from the index and optionally delete its file |
+| `taskExists(taskId)` | Throws unless the task file exists and is indexed |
+| `taskFileExists(taskId)` | Whether a task file exists, regardless of whether any board references it |
+| `findTaskColumn(taskId)` | The column a task is in, or throws if it doesn't exist / isn't indexed |
+| `findTrackedTasks(columnName?)` | Ids of tasks listed in the index, optionally filtered by column |
+| `findUntrackedTasks()` | Ids of markdown files in the tasks folder that aren't listed in the index |
+| `addUntrackedTaskToIndex(taskId, columnName)` | Add an untracked task to a column in the index |
+| `addTaskToBoard(taskId, columnName)` | Add an existing (already-tracked-elsewhere) task to this board |
+| `search(filters?, quiet?)` | Search for indexed tasks matching filters — see [Filtering and Sorting](filtering-and-sorting.md) |
+| `sort(columnName, sorters, save?)` | Sort a column using the shared sorter model |
+| `comment(taskId, text, author?)` | Add a comment to a task |
+
+### Simple tasks
+
+Simple tasks are plain lines in a column that aren't task links; see [Index Structure](index-structure.md).
+
+| Method | Description |
+| --- | --- |
+| `findSimpleTasks(input?, index?)` | Simple tasks matching a title, or all of them if no title given |
+| `getSimpleTask(input, index?)` | Resolve a title to exactly one simple task, or throw |
+| `moveSimpleTask(input, columnName, position?)` | Move a simple task to another column on this board |
+| `moveSimpleTaskToBoard(input, targetSlug, columnName?, position?)` | Move a simple task onto another board |
+| `deleteSimpleTask(input)` | Remove a simple task |
+| `promoteSimpleTask(input, columnName?)` | Turn a simple task into a real task file |
+
+### Archive
+
+| Method | Description |
+| --- | --- |
+| `listArchivedTasks()` | List archived task ids |
+| `archiveTask(taskId)` | Move a task to the archive |
+| `restoreTask(taskId, columnName?, singleBoard?)` | Restore a task from the archive |
+| `loadArchivedTask(taskId)` | Load an archived task file as an object |
+
+### Contributors
+
+See [Contributors](contributors.md).
+
+| Method | Description |
+| --- | --- |
+| `getContributors()` | The workspace's contributors, normalised to object form |
+| `findContributor(value)` | Find the contributor a name/alias/display-name value refers to |
+| `currentUser()` | Work out who the current user is (`KANBN_USER`, then git email/name, then git username, then `null`) |
+| `getContributorUsage()` | How contributors are used across tasks, and which names in use aren't known contributors |
+| `findContributorWarnings()` | Tasks whose assigned user or comment author isn't a known contributor |
+
+### Actions
+
+See [Actions](actions.md).
+
+| Method | Description |
+| --- | --- |
+| `withoutActions()` | Get a copy of this instance that runs no action rules |
+| `actionsAllowed()` | Whether actions should run at all for this instance |
+| `getActionRules(index?)` | The action rules that apply to this board |
+| `findActionWarnings()` | Action rules that are legal but probably not what the author meant |
+| `lastActionWarnings` | Property: rules that were skipped during the last operation |
+
+### Sprints, status and charts
+
+See [Sprints](sprints.md).
+
+| Method | Description |
+| --- | --- |
+| `sprint(name, description, start)` | Start a new sprint |
+| `status(quiet?, untracked?, due?, sprint?, dates?)` | Project status information |
+| `burndown(sprints?, dates?, assigned?, columns?, normalise?)` | Burndown chart data |
+
+### Validation
+
+| Method | Description |
+| --- | --- |
+| `validate(save?)` | Validate the index and task files; `true` on success, otherwise an array of errors |
+| `findMissingTaskFiles(index?)` | Tasks referenced by this board that have no task file |
+| `findColumnContentWarnings(index?)` | Lines in this board's columns that aren't task links |
+| `findWorkspaceUntrackedTasks()` | Tasks that no board references at all |
+| `findTasksOnOtherBoards()` | Tasks that other boards track but this one doesn't |
+
+## Error handling
+
+Kanbn methods reject/throw plain `Error` objects with human-readable messages (for example `"Task
+already exists"`, `"Column does not exist"`). There are no custom error classes or machine-readable
+error codes to switch on — match on `error.message` if you need to distinguish specific failures.
+
+## A worked example
+
+```js
+const { Kanbn } = require('@basementuniverse/kanbn');
+
+async function main() {
+  const kanbn = new Kanbn('/path/to/project');
+
+  if (!(await kanbn.initialised())) {
+    throw new Error('Not a kanbn project');
+  }
+
+  const taskId = await kanbn.createTask(
+    { name: 'Write documentation', description: 'Document the library API' },
+    'Todo'
+  );
+
+  await kanbn.moveTask(taskId, 'In Progress');
+
+  const status = await kanbn.status(false, true);
+  console.log(status);
+}
+
+main().catch(err => {
+  console.error(err.message);
+  process.exitCode = 1;
+});
+```

package/docs/index-structure.md

@@ -25,7 +25,7 @@ The index file can optionally begin with YAML front-matter containing project op
 
 There should be a single level-1 heading at the top of the markdown body containing the project name.
 
-The project description should appear below the title. The description can be of any length and can contain markdown, however it must not contain any headings.
+The project description should appear below the title. The description can be of any length and can contain markdown, however it must not contain any level-2 headings. Deeper headings (level 3 and below) are fine, as are level-2 headings inside a fenced code block.
 
 Below the description there should be one or more level-2 headings. The 'Options' name is reserved for project options.
 
@@ -223,7 +223,7 @@ Workspace-scoped. See [multiple boards](multiple-boards.md).
 
 ### `sprints`
 
-A list of sprints. Each sprint will have `start`, `name` and `description` properties.
+A list of sprints. Each sprint will have `start`, `name` and `description` properties. See [sprints](sprints.md).
 
 A board can declare its own `sprints` in its front matter, which **replaces** the workspace list for that board entirely. See [multiple boards](multiple-boards.md#per-board-sprints).
 

package/docs/index.md

@@ -7,12 +7,14 @@ To get started quickly, check out the [Quick Start](quick-start.md) guide.
 ## Contents
 
 - [Quick Start](quick-start.md)
+- [Library API](api.md) — using `@basementuniverse/kanbn` as a dependency instead of the CLI
 - [Index Structure](index-structure.md) — the board file and all project options
 - [Task Structure](task-structure.md) — task files, metadata, sub-tasks, relations, comments and history
 - [Multiple Boards](multiple-boards.md) — several boards over one shared pool of tasks
 - [Contributors](contributors.md) — an optional list of who works on a workspace, and who "you" are
 - [Actions](actions.md) — declarative rules that fire when a task is created, moved, updated or finished
 - [Views](views.md) — custom board layouts, columns and lanes
+- [Sprints](sprints.md) — named time windows that `status`, `burndown` and `history` report through
 - [Filtering and Sorting](filtering-and-sorting.md) — the filter and sorter model shared by `find`, `sort` and views
 - [Advanced Configuration](advanced-configuration.md)
 - [Migrating to 2.0.0](migration-2.0.md) — separate config files and custom folder locations

package/docs/sprints.md

@@ -0,0 +1,175 @@
+# Sprints
+
+A sprint in Kanbn is nothing more than **a named point in time**. Each sprint has a start date, and
+runs until the next sprint starts; the last sprint in the list is the current one, and runs up to
+now. Nothing stores an end date or a duration, and there is no way for a sprint to be "closed" -
+starting the next sprint is what ends the previous one, and any end date you see in reporting output
+is derived from the next sprint's start.
+
+Tasks are never assigned to a sprint. A sprint is a window that reporting commands measure through,
+so which sprint a task belongs to is worked out from its dates (`created`, `started`, `completed`,
+`due`) rather than being recorded anywhere on the task. This means sprints cost nothing to add
+retrospectively, and moving a boundary re-slices history rather than invalidating it.
+
+Sprints live in the [`sprints`](index-structure.md#sprints) index option:
+
+```yaml
+sprints:
+  -
+    start: 2026-07-01T09:00:00.000Z
+    name: 'Foundation Sprint'
+    description: 'Baseline product and infrastructure work.'
+  -
+    start: 2026-07-08T09:00:00.000Z
+    name: 'Workflow Sprint'
+```
+
+`start` and `name` are required, `description` is optional.
+
+## Starting a sprint
+
+```bash
+kanbn sprint --name "Workflow Sprint" --description "Core team workflow and onboarding features."
+```
+
+`kanbn sp` is the short alias. The sprint always starts *now* - there is no option to backdate one
+from the CLI, so a sprint that should have started last Monday is a front matter edit.
+
+| Option | Effect |
+| --- | --- |
+| `--name`, `-n` | Sprint name. If omitted, auto-named `Sprint {n}` from the number of existing sprints |
+| `--description`, `-d` | Optional description, shown in `kanbn status` output |
+| `--interactive`, `-i` | Prompt for name and (optionally) description |
+| `--board`, `-b` | Run from the context of another board (see [below](#sprints-and-multiple-boards)) |
+
+There is no command to rename, re-date or delete a sprint. All three are edits to the `sprints`
+list in the board's front matter, which is deliberate: the sprint list is a small hand-maintainable
+piece of history, and `kanbn sprint` only ever appends to it.
+
+## Reading a sprint
+
+Three commands take a `--sprint N|"name"` option (`-p` in every case). A sprint can be selected by
+1-based number or by exact name; an unknown number or name is an error, not an empty result.
+
+### `kanbn status --sprint`
+
+Adds a `sprint` section to the status output for the selected sprint, defaulting to the current one:
+
+```bash
+kanbn status --sprint 2
+kanbn status --sprint "Workflow Sprint"
+```
+
+```yaml
+sprint:
+  number: 2
+  name: 'Workflow Sprint'
+  start: 2026-07-08T09:00:00.000Z
+  end: 2026-07-15T09:00:00.000Z
+  current: 3
+  description: 'Core team workflow and onboarding features.'
+  durationDelta: 604800000
+  durationMessage: '1 week'
+  created:   # tasks created during the sprint, with their total workload
+  started:   # tasks started during the sprint
+  completed: # tasks completed during the sprint
+  due:       # tasks due during the sprint
+```
+
+Each of those four groups lists the matching task ids with their column and workload, plus a summed
+`workload`. Any [custom date fields](index-structure.md#customfields) you have declared get a group
+of their own too.
+
+`current` and `end` only appear when you're looking at a sprint other than the current one: `current`
+is the number of the sprint that is running now, and `end` is the moment the sprint you asked about
+stopped, which is the next sprint's `start`. The current sprint has no `end`, because it hasn't
+ended - its `durationDelta` and `durationMessage` are measured up to now, and will be larger every
+time you run the command until the next sprint starts.
+
+### `kanbn burndown --sprint`
+
+```bash
+kanbn burndown --sprint "Workflow Sprint"
+kanbn burndown --sprint 1 --sprint 2
+```
+
+Plots remaining workload across the sprint window. `--sprint` can be repeated to draw a chart per
+sprint. With no `--sprint` or `--date` at all, burndown uses the current sprint - and if no sprints
+are defined, it falls back to all time, from the earliest task date to now.
+
+### `kanbn history --sprint`
+
+```bash
+kanbn history --sprint 2
+```
+
+Filters the event listing down to events that fall inside the sprint window. Repeatable, and
+combinable with `--assigned`, `--task` and `--date`.
+
+Gantt charts don't use sprints at all.
+
+## Sprints and multiple boards
+
+Sprints are workspace-level by default: every board reads the workspace list, so one sprint cadence
+covers the whole workspace and `kanbn sprint -b design` appends to that shared list (and says so in
+verbose mode).
+
+A board that declares its own `sprints` in its front matter **replaces** the workspace list for
+itself entirely - it can no longer see workspace sprints, so `kanbn status -b design -p "Foundation
+Sprint"` will fail to find one that only exists at workspace level. Sprints started on such a board
+are auto-named `{Board name} Sprint {n}` so two boards' sprints can't be confused. Forking is never
+implicit; it stays a deliberate front matter edit. See
+[multiple boards](multiple-boards.md#per-board-sprints).
+
+`--sprint` can't be combined with `--all-boards`, because sprint numbers and names are relative to
+one board's list.
+
+## Keeping the list sane
+
+The "current sprint is the last one" and "a sprint runs until the next one starts" rules both assume
+the list is in chronological order. `kanbn validate` emits a `sprints-out-of-order` warning if it
+isn't - worth checking after hand-editing dates.
+
+## Example workflow
+
+A team working in weekly sprints, reviewing at the end of each one.
+
+Start the first sprint on the Monday:
+
+```bash
+kanbn sprint -n "Foundation Sprint" -d "Baseline product and infrastructure work."
+```
+
+Work the week normally - `kanbn add`, `kanbn move`, `kanbn comment`. Nothing needs to reference the
+sprint; the dates Kanbn stamps on tasks as they're created, started and completed are what the
+sprint reporting reads.
+
+Check progress mid-week:
+
+```bash
+kanbn status --due
+kanbn burndown --normalise auto
+```
+
+With no `--sprint`, both default to the current sprint, so this is the "how is this week going"
+view.
+
+On the following Monday, review what the week actually contained, then start the next sprint:
+
+```bash
+kanbn status --sprint "Foundation Sprint"
+kanbn history --sprint "Foundation Sprint"
+kanbn sprint -n "Workflow Sprint" -d "Core team workflow and onboarding features."
+```
+
+Starting the second sprint closes the first one at that moment, and the reports above stay valid
+for it forever - `kanbn status -p 1` and `kanbn burndown -p 1` will show the same window next month.
+
+Comparing two sprints later on:
+
+```bash
+kanbn burndown -p "Foundation Sprint" -p "Workflow Sprint"
+```
+
+The [`example/basic`](../example/basic) workspace ships with three sprints defined, so every command
+on this page can be run there as-is.

package/docs/task-structure.md

@@ -64,7 +64,9 @@ There should be a single level-1 heading at the top of the markdown body contain
 
 The task description should appear below the title. The description can be of any length and can contain markdown.
 
-The following level-2 headings are reserved for special purposes (`## Metadata`, `## Sub-tasks`, `## Relations`, `## Comments` and `## History`). Any other level-2 heading is treated as part of the description.
+The following level-2 headings are reserved for special purposes (`## Metadata`, `## Sub-tasks`, `## Relations`, `## Comments` and `## History`). Any other level-2 heading is treated as part of the description, as is a heading at any other level - a `### Sub-tasks` heading in a description is description content, not the task's sub-tasks.
+
+Headings inside fenced code blocks are ignored, so a shell or Python comment like `# install deps` in a ```` ```bash ```` block stays where you wrote it.
 
 ## Metadata
 

package/index.js

@@ -42,3 +42,5 @@ module.exports = async () => {
     route.id
   );
 };
+
+module.exports.Kanbn = require('./src/main').Kanbn;

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@basementuniverse/kanbn",
-  "version": "2.5.0",
+  "version": "2.5.3",
   "description": "A CLI Kanban application",
   "main": "index.js",
+  "types": "src/main.d.ts",
   "scripts": {
     "test": "KANBN_ENV=test qunit ./test/**/*.test.js",
     "coverage": "KANBN_ENV=test c8 --reporter=text --reporter=html --include=src/** --include=index.js qunit ./test/**/*.test.js"
@@ -38,6 +39,7 @@
     "dotenv": "^8.2.0",
     "front-matter": "^4.0.2",
     "fuzzy": "^0.1.3",
+    "glob": "^7.2.3",
     "glob-promise": "^3.4.0",
     "humanize-duration": "^3.25.0",
     "inquirer": "^7.3.3",

package/src/main.js

@@ -4426,7 +4426,7 @@ class Kanbn {
           start: sprints[sprintIndex].start,
         };
         if (currentSprint - 1 !== sprintIndex) {
-          if (sprintIndex === sprints.length - 1) {
+          if (sprintIndex !== sprints.length - 1) {
             result.sprint.end = sprints[sprintIndex + 1].start;
           }
           result.sprint.current = currentSprint;

package/src/parse-index.js

@@ -231,6 +231,46 @@ function validateOptions(options) {
   }
 }
 
+/**
+ * Check whether a parsed section is a level-2 heading
+ *
+ * The index format reserves level 2 for columns and for the Options section. A deeper heading is
+ * part of the project description: it used to be promoted into a column of its own, which put an
+ * empty phantom column on the board and rewrote the user's `###` as a `##`
+ * @param {object} section A section from parseMarkdown
+ * @return {boolean}
+ */
+function isLevel2(section) {
+  return /^## /.test(section.heading);
+}
+
+/**
+ * Compile the project name's section and any sub-headings below it into a project description
+ *
+ * The Options section and the columns have already been taken out of the index by this point, so
+ * everything left is description
+ * @param {object} index A parsed index
+ * @param {string} name The project name, i.e. the title of the level-1 heading at the top of the file
+ * @param {string[]} columnNames The headings that are columns
+ * @return {string}
+ */
+function compileDescription(index, name, columnNames) {
+  const description = [];
+  for (const heading in index) {
+    if (heading === 'raw' || columnNames.indexOf(heading) !== -1) {
+      continue;
+    }
+
+    // The project name's heading line is stored separately as the name, so it isn't repeated in the
+    // description. Every other heading keeps its line
+    description.push(
+      heading === name ? '' : index[heading].heading,
+      index[heading].content
+    );
+  }
+  return description.join('\n\n').trim();
+}
+
 /**
  * Get the task id from a column list item, or null if the item isn't a task link
  *
@@ -416,12 +456,9 @@ module.exports = {
       // Get name
       name = indexHeadings[0];
 
-      // Get description
-      description = name in index ? index[name].content.trim() : '';
-
       // Parse options
       // Options will be serialized back to front-matter, this check remains here for backwards-compatibility
-      if ('Options' in index) {
+      if ('Options' in index && isLevel2(index['Options'])) {
 
         // Get embedded options and make sure it's an object
         const embeddedOptions = yaml.parse(index['Options'].content.trim().replace(/```(yaml|yml)?/g, ''));
@@ -431,11 +468,15 @@ module.exports = {
 
         // Merge with front matter options
         options = Object.assign(options, embeddedOptions);
+        delete index['Options'];
       }
       validateOptions(options);
 
       // Parse columns
-      const columnNames = Object.keys(index).filter(column => ['raw', 'Options', name].indexOf(column) === -1);
+      // Only level-2 headings are columns, as documented - anything deeper belongs to the description
+      const columnNames = Object.keys(index).filter(
+        column => ['raw', name].indexOf(column) === -1 && isLevel2(index[column])
+      );
       for (const columnName of columnNames) {
         let parsed = null;
         try {
@@ -452,6 +493,10 @@ module.exports = {
           columnContent[columnName] = parsed.content;
         }
       }
+
+      // Get description
+      // Everything that isn't the Options section or a column is description, sub-headings included
+      description = compileDescription(index, name, columnNames);
     } catch (error) {
       throw new Error(`Unable to parse index: ${error.message}`);
     }

package/src/parse-markdown.js

@@ -1,3 +1,97 @@
+/**
+ * Match an ATX heading line, e.g. `## Title`
+ *
+ * The heading must start at column 0. CommonMark also allows up to 3 leading spaces, but kanbn has
+ * always required none, and loosening it now would start hoisting indented lines out of task files
+ * that parse correctly today
+ */
+const HEADING_REGEX = /^(#{1,6}) (.+)$/;
+
+/**
+ * Match the opening or closing line of a fenced code block
+ *
+ * Up to 3 leading spaces are allowed, as in CommonMark - at 4 spaces the line is part of an indented
+ * code block instead, which can't contain a heading anyway because a heading must start at column 0
+ */
+const FENCE_REGEX = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+
+/**
+ * Find the ATX headings in a markdown document, ignoring anything inside a fenced code block
+ *
+ * Tracking fences is the whole reason this isn't a single regex: `# install deps` inside a ```bash
+ * block is a shell comment, not a heading, and hoisting it out of the block destroys the user's code.
+ * The same goes for Python comments, Ruby comments, C preprocessor directives and so on
+ * @param {string} markdown
+ * @return {object[]} Each heading's line, title, start index and the index its content starts at
+ */
+function findHeadings(markdown) {
+  const headings = [];
+
+  // The fence currently open, as { char, length }, or null if we're not inside a code block
+  let fence = null;
+  let index = 0;
+  for (const rawLine of markdown.split('\n')) {
+
+    // Tolerate CRLF line endings: without this the trailing carriage return ends up inside the
+    // heading title, and from there inside task names and ids
+    const line = rawLine.replace(/\r$/, '');
+    const fenceMatch = line.match(FENCE_REGEX);
+    if (fence === null) {
+      if (fenceMatch && isFenceStart(fenceMatch)) {
+        fence = { char: fenceMatch[1][0], length: fenceMatch[1].length };
+      } else {
+        const headingMatch = line.match(HEADING_REGEX);
+        if (headingMatch) {
+          headings.push({
+            heading: headingMatch[0],
+            title: headingMatch[2],
+            index,
+
+            // Where this heading's content starts: the line after the heading line
+            contentIndex: index + rawLine.length + 1
+          });
+        }
+      }
+    } else if (isFenceEnd(fenceMatch, fence)) {
+      fence = null;
+    }
+
+    // + 1 for the newline that split() removed
+    index += rawLine.length + 1;
+  }
+  return headings;
+}
+
+/**
+ * Check if a fence line opens a code block
+ *
+ * A backtick fence's info string can't itself contain a backtick - ```` ```a`b ```` is a paragraph
+ * containing code spans, not a code block. Tilde fences have no such restriction
+ * @param {object} fenceMatch A FENCE_REGEX match
+ * @return {boolean}
+ */
+function isFenceStart(fenceMatch) {
+  return fenceMatch[1][0] !== '`' || fenceMatch[2].indexOf('`') === -1;
+}
+
+/**
+ * Check if a line closes the currently open code block
+ *
+ * A closing fence has to use the same character as the fence that opened the block, be at least as
+ * long, and carry no info string - so a ``` line doesn't close a ~~~ block, and neither does ```js
+ * @param {?object} fenceMatch A FENCE_REGEX match, or null if the line isn't a fence
+ * @param {object} fence The currently open fence
+ * @return {boolean}
+ */
+function isFenceEnd(fenceMatch, fence) {
+  return (
+    fenceMatch !== null &&
+    fenceMatch[1][0] === fence.char &&
+    fenceMatch[1].length >= fence.length &&
+    fenceMatch[2].trim() === ''
+  );
+}
+
 module.exports = function parseMarkdown(markdown) {
   if (!markdown) {
     throw new Error('data is null, undefined or empty');
@@ -9,30 +103,39 @@ module.exports = function parseMarkdown(markdown) {
   if (markdown === '') {
     throw new Error('data is an empty string');
   }
-  const headings = [...markdown.matchAll(/^#{1,6} (?<title>.+)/gm)].map(({ 0: heading, 1: title, index }) => ({
-    heading,
-    title,
-    index
-  }));
+  const headings = findHeadings(markdown);
   if (headings.length > 0 && headings[0].index > 0) {
     headings.unshift({
       heading: '',
       title: 'raw',
-      index: 0
+      index: 0,
+      contentIndex: 0
     });
   }
   const parsed = {};
   for (let i = 0; i < headings.length; i++) {
+    const content = markdown.slice(
+      headings[i].contentIndex,
+      i < headings.length - 1
+        ? headings[i + 1].index
+        : undefined
+    ).trim();
+
+    // A repeated heading title used to overwrite the earlier one, silently discarding everything
+    // written under it - two `## Todo` columns meant losing every task in the first one. Merging the
+    // sections keeps the content, and keeping the repeated heading line means the section still
+    // looks the way the user wrote it after a read/write cycle
+    if (headings[i].title in parsed) {
+      parsed[headings[i].title].content = [
+        parsed[headings[i].title].content,
+        headings[i].heading,
+        content
+      ].filter(part => part !== '').join('\n\n');
+      continue;
+    }
     parsed[headings[i].title] = {
       heading: headings[i].heading,
-      content: markdown.slice(
-        // 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
-      ).trim()
+      content
     };
   }
   return parsed;

package/src/parse-task.js

@@ -6,21 +6,44 @@ const chrono = require('chrono-node');
 const validate = require('jsonschema').validate;
 const parseMarkdown = require('./parse-markdown');
 
+/**
+ * Get a reserved section from a parsed task, or null if the task doesn't have one
+ *
+ * A section only counts as reserved if it's a level-2 heading, which is what the task format
+ * documents and what json2md writes. A `# Comments` or `### Sub-tasks` heading written into a
+ * description is description content, and used to hijack the section it happened to share a name
+ * with - turning a paragraph about comments into the task's comments, or failing the whole parse
+ * @param {object} task A parsed task
+ * @param {string} title A reserved section title
+ * @return {?object} The section, or null if the task doesn't have it at level 2
+ */
+function getReservedSection(task, title) {
+  return title in task && /^## /.test(task[title].heading) ? task[title] : null;
+}
+
 /**
  * Compile separate headings together into a task description
+ *
+ * Reserved sections have already been removed from the parsed task by this point, so everything
+ * left is description
  * @param {object} data
+ * @param {string} name The task name, i.e. the title of the level-1 heading at the top of the file
  */
-function compileDescription(data) {
+function compileDescription(data, name) {
   const description = [];
   if ('raw' in data) {
     description.push(data.raw.content.replace(/[\r\n]{3}/g, '\n\n').trim());
   }
   for (let heading in data) {
-    if (['raw', 'Metadata', 'Sub-tasks', 'Relations', 'History', 'Comments'].indexOf(heading) !== -1) {
+    if (heading === 'raw') {
       continue;
     }
+
+    // The task name's heading line is stored separately as the task name, so it isn't repeated in
+    // the description. Every other heading keeps its line: this used to drop the line from *every*
+    // level-1 heading, silently deleting the text of any `# Heading` written into a description
     description.push(
-      /^# (.*)/.test(data[heading].heading) ? '' : data[heading].heading,
+      heading === name ? '' : data[heading].heading,
       data[heading].content
     );
   }
@@ -359,10 +382,11 @@ module.exports = {
 
       // Parse metadata
       // Metadata will be serialized back to front-matter, this check remains here for backwards compatibility
-      if ('Metadata' in task) {
+      const metadataSection = getReservedSection(task, 'Metadata');
+      if (metadataSection !== null) {
 
         // Get embedded metadata and make sure it's an object
-        const embeddedMetadata = yaml.parse(task['Metadata'].content.trim().replace(/```(yaml|yml)?/g, ''));
+        const embeddedMetadata = yaml.parse(metadataSection.content.trim().replace(/```(yaml|yml)?/g, ''));
         if (typeof embeddedMetadata !== 'object') {
           throw new Error('invalid metadata content');
         }
@@ -434,9 +458,10 @@ module.exports = {
       }
 
       // Parse sub-tasks
-      if ('Sub-tasks' in task) {
+      const subTasksSection = getReservedSection(task, 'Sub-tasks');
+      if (subTasksSection !== null) {
         try {
-          subTasks = marked.lexer(task['Sub-tasks'].content)[0].items.map(item => ({
+          subTasks = marked.lexer(subTasksSection.content)[0].items.map(item => ({
             text: item.text.trim(),
             completed: item.checked || false
           }));
@@ -447,9 +472,10 @@ module.exports = {
       }
 
       // Parse relations
-      if ('Relations' in task) {
+      const relationsSection = getReservedSection(task, 'Relations');
+      if (relationsSection !== null) {
         try {
-          relations = marked.lexer(task['Relations'].content)[0].items.map(item => {
+          relations = marked.lexer(relationsSection.content)[0].items.map(item => {
             const parts = item.tokens[0].tokens[0].text.split(' ');
             return parts.length === 1
               ? {
@@ -468,7 +494,8 @@ module.exports = {
       }
 
       // Parse comments
-      if ('Comments' in task) {
+      const commentsSection = getReservedSection(task, 'Comments');
+      if (commentsSection !== null) {
         try {
           // const commentsHeading = '## Comments';
           // const start = data.indexOf(commentsHeading) + commentsHeading.length;
@@ -479,7 +506,7 @@ module.exports = {
           //   end = data.length;
           // }
           // const parsedComments = marked.lexer(data.slice(start, end).trim())[0].items;
-          const parsedComments = marked.lexer(task['Comments'].content)[0].items;
+          const parsedComments = marked.lexer(commentsSection.content)[0].items;
           for (let parsedComment of parsedComments) {
             const comment = { text: [] };
             const parts = parsedComment.text.split('\n');
@@ -506,9 +533,10 @@ module.exports = {
       }
 
       // Parse history
-      if ('History' in task) {
+      const historySection = getReservedSection(task, 'History');
+      if (historySection !== null) {
         try {
-          const parsedHistory = marked.lexer(task['History'].content)[0].items;
+          const parsedHistory = marked.lexer(historySection.content)[0].items;
           for (let parsedHistoryEvent of parsedHistory) {
             const historyEvent = {};
             const parts = parsedHistoryEvent.text.split('\n');
@@ -563,7 +591,7 @@ module.exports = {
 
       // Assemble description
       // const descriptionParts = [];
-      description = compileDescription(task);
+      description = compileDescription(task, name);
       // description = descriptionParts.join('\n\n');
     } catch (error) {
       throw new Error(`Unable to parse task: ${error.message}`);