@basementuniverse/kanbn 2.0.0 → 2.5.0

package/src/main.d.ts

@@ -4,14 +4,66 @@ declare type config = {
   mainFolder?: string,
   indexFile?: string,
   taskFolder?: string,
-  archiveFolder?: string
+  archiveFolder?: string,
+  defaultBoard?: string,
+  boards?: {
+    exclude?: string[],
+    order?: string[],
+    [slug: string]: any
+  }
+};
+
+declare type board = {
+  slug: string,
+  path: string,
+  name: string,
+  description: string,
+  main: boolean
+};
+
+declare type boardSummary = board & {
+  columns: number,
+  tasks: number,
+  completed: number,
+  completedPercentage: number,
+  modified: Date | null
+};
+
+declare type columnContentEntry = {
+  position: number,
+  text: string,
+  raw: string,
+  block?: boolean
 };
 
 declare type index = {
   name: string,
   description: string,
   options: Record<string, any>,
-  columns: Record<string, string[]>
+  columns: Record<string, string[]>,
+
+  // Lines in a column that aren't task links. Preserved verbatim and ignored by everything else
+  columnContent?: Record<string, columnContentEntry[]>
+};
+
+declare type missingTaskFile = {
+  task: string,
+  column: string
+};
+
+declare type simpleTask = {
+  column: string,
+  position: number,
+  text: string,
+  raw: string
+};
+
+declare type columnContentWarning = {
+  board: string,
+  column: string,
+  type: 'non-task-line' | 'untracked-task-line' | 'malformed-task-link',
+  text: string,
+  message: string
 };
 
 declare type subTask = {
@@ -58,12 +110,99 @@ declare type sprint = {
   description?: string
 };
 
+declare type contributor = {
+  name: string,
+  displayName: string,
+  aliases: string[],
+  email?: string,
+  colour?: string
+};
+
+declare type contributorSpelling = {
+  value: string,
+  assigned: number,
+  comments: number,
+  tasks: string[]
+};
+
+declare type contributorUsage = {
+  contributors: (contributor & {
+    assigned: number,
+    comments: number,
+    tasks: number,
+    spellings: contributorSpelling[]
+  })[],
+  unknown: contributorSpelling[]
+};
+
+declare type contributorWarning = {
+  task: string,
+  type: 'unknown-contributor',
+  value: string,
+  message: string
+};
+
+declare type actionRule = {
+  name?: string,
+  on: string,
+  when?: Record<string, any>,
+  for?: {
+    related?: string,
+    direction?: 'incoming' | 'outgoing',
+    where?: Record<string, any>
+  },
+  anyBoard?: boolean,
+  then: Record<string, any>[]
+};
+
+declare type actionWarning = {
+  type: 'conflicting-actions' | 'unresolvable-user',
+  message: string
+};
+
 export class Kanbn {
-  constructor(root?: any);
+  constructor(root?: any, options?: { board?: string, caches?: any, actions?: boolean });
   ROOT: string;
   CONFIG_YAML: string;
   CONFIG_JSON: string;
   configMemo: any;
+  /**
+   * The board this instance is scoped to, or null for the main board
+   */
+  boardSlug: string | null;
+  /**
+   * Rules that were skipped during the last operation, for the caller to report
+   */
+  lastActionWarnings: string[];
+  /**
+   * Whether scripted actions run for operations on this instance
+   */
+  actionsEnabled: boolean;
+  /**
+   * Get an instance that runs no actions
+   */
+  withoutActions(): Kanbn;
+  /**
+   * Get the action rules that apply to this board
+   */
+  getActionRules(index?: index | null): Promise<actionRule[]>;
+  /**
+   * Check whether actions should run at all
+   */
+  actionsAllowed(): boolean;
+  /**
+   * Find things about this board's action rules that are legal but probably not what the author meant
+   */
+  findActionWarnings(): Promise<actionWarning[]>;
+  /**
+   * Get a copy of this instance scoped to another board, sharing this one's cached config
+   * @param {?string} [slug=null] The board slug, or null/"main"/"default" for the main board
+   */
+  board(slug?: string | null): Kanbn;
+  /**
+   * Alias for board()
+   */
+  withBoard(slug?: string | null): Kanbn;
   /**
    * Check if a separate config file exists
    * @returns {Promise<boolean>} True if a config file exists
@@ -108,7 +247,25 @@ export class Kanbn {
    */
   getMainFolder(): Promise<string>;
   /**
-   * Get the index path
+   * Get the main board's slug, i.e. the index file name without its extension
+   * @return {Promise<string>} The main board slug
+   */
+  getMainBoardSlug(): Promise<string>;
+  /**
+   * Resolve a board slug, mapping the reserved aliases and an absent slug onto the main board
+   * @param {?string} [slug] The board slug, defaulting to this instance's board
+   */
+  resolveBoardSlug(slug?: string | null): Promise<string>;
+  /**
+   * Check if a slug refers to the main board
+   */
+  isMainBoard(slug?: string | null): Promise<boolean>;
+  /**
+   * Get the file path for a board
+   */
+  getBoardPath(slug?: string | null): Promise<string>;
+  /**
+   * Get the index path, i.e. the path of the board this instance is scoped to
    * @return {Promise<string>} The kanbn index path
    */
   getIndexPath(): Promise<string>;
@@ -154,6 +311,155 @@ export class Kanbn {
    * @param {object} indexData Index data to save
    */
   saveIndex(indexData: object): Promise<void>;
+  /**
+   * Get the workspace-scoped options, from the config file or the main board's front matter
+   */
+  getWorkspaceOptions(): Promise<Record<string, any>>;
+  /**
+   * Load the workspace options along with where they came from
+   */
+  loadWorkspaceOptions(): Promise<{ options: Record<string, any>, fromConfig: boolean }>;
+  /**
+   * Normalise a contributors option into a consistent object form
+   */
+  normaliseContributors(contributors: any): contributor[];
+  /**
+   * Get the workspace's contributors, normalised to the object form
+   */
+  getContributors(): Promise<contributor[]>;
+  /**
+   * Find the contributor a value refers to, matching name, display name and aliases
+   */
+  findContributor(value: string | null): Promise<contributor | null>;
+  /**
+   * Work out who the current user is: KANBN_USER, then a contributor matched by git email or git
+   * name, then the git username, then null
+   */
+  currentUser(): Promise<string | null>;
+  /**
+   * Collect every distinct `assigned` and comment `author` value used across the workspace's tasks
+   */
+  collectContributorValues(): Promise<Map<string, { value: string, assigned: number, comments: number, tasks: Set<string> }>>;
+  /**
+   * Report how contributors are used, and which names in use aren't known contributors
+   */
+  getContributorUsage(): Promise<contributorUsage>;
+  /**
+   * Find tasks whose assigned user or comment author isn't a known contributor
+   */
+  findContributorWarnings(): Promise<contributorWarning[]>;
+  /**
+   * Get the options a secondary board inherits from the workspace
+   */
+  getInheritedBoardOptions(): Promise<Record<string, any>>;
+  /**
+   * Get the per-board options declared for a board under the `boards` key in the config file
+   */
+  getBoardConfig(slug?: string | null): Promise<Record<string, any>>;
+  /**
+   * Layer a board's own front matter options over the workspace options
+   */
+  resolveBoardOptions(resolvedSlug: string, ownOptions: Record<string, any>): Promise<Record<string, any>>;
+  /**
+   * Work out which options belong in a secondary board's own front matter
+   */
+  getOwnBoardOptions(resolvedSlug: string, indexData: object): Promise<Record<string, any>>;
+  /**
+   * Overwrite a board file with the specified data
+   */
+  saveBoard(slug: string | null, indexData: object): Promise<void>;
+  /**
+   * Load a board file and parse it to an object
+   */
+  loadBoard(slug?: string | null): Promise<index>;
+  /**
+   * Work out which board a command should target: --board, then KANBN_BOARD, then defaultBoard
+   */
+  resolveTargetBoard(slug?: string | null): Promise<string | null>;
+  /**
+   * Get a Kanbn instance scoped to the board a command's arguments point at
+   */
+  boardFromArgs(args?: object): Promise<Kanbn>;
+  /**
+   * Find all boards in the workspace
+   */
+  listBoards(): Promise<board[]>;
+  /**
+   * List boards with column and task counts, completion percentage and last modified date
+   */
+  getBoardsSummary(): Promise<boardSummary[]>;
+  /**
+   * Get every task that appears on more than one board, with the column it occupies on each
+   */
+  getCrossBoardTasks(allTasks?: boolean): Promise<{ id: string, boards: Record<string, string> }[]>;
+  /**
+   * Check if a board exists
+   */
+  boardExists(slug: string): Promise<boolean>;
+  /**
+   * Get the value to record in a history event's `board` key, or null for the main board
+   */
+  historyBoard(): Promise<string | null>;
+  /**
+   * Add an existing task to this board
+   */
+  addTaskToBoard(taskId: string, columnName: string): Promise<string>;
+  /**
+   * Check if a task file exists, regardless of whether any board references it
+   */
+  taskFileExists(taskId: string): Promise<boolean>;
+  /**
+   * Boards named in an archived task's metadata that no longer existed when it was restored
+   */
+  lastRestoreWarnings: string[];
+  /**
+   * Create a new board
+   */
+  createBoard(slug: string, options?: object): Promise<string>;
+  /**
+   * Create a secondary board, or update an existing one
+   */
+  initialiseBoard(slug: string, options?: object): Promise<string>;
+  /**
+   * Delete a board file, returning the ids of tasks that are no longer on any board
+   */
+  deleteBoard(slug: string): Promise<string[]>;
+  /**
+   * Find the tasks that would become untracked if a board were deleted
+   */
+  findOrphanedTasks(slug: string): Promise<string[]>;
+  /**
+   * Rename a board
+   */
+  renameBoard(slug: string, newSlug: string, newName?: string | null): Promise<string>;
+  /**
+   * Find every board that references a task, and the column it occupies on each
+   */
+  findTaskBoards(taskId: string): Promise<Record<string, string>>;
+  /**
+   * Alias for findTaskBoards()
+   */
+  getTaskBoardColumns(taskId: string): Promise<Record<string, string>>;
+  /**
+   * Get the slugs that can't be used for a board
+   */
+  getReservedBoardSlugs(): Promise<string[]>;
+  /**
+   * Check that a slug can be used for a new board, throwing if it can't
+   */
+  validateBoardSlug(slug: string): Promise<string>;
+  /**
+   * Get the boards config from the config file, i.e. the exclude list and display order
+   */
+  getBoardsConfig(): Promise<{ exclude: string[], order: string[] }>;
+  /**
+   * Find tasks that no board references at all
+   */
+  findWorkspaceUntrackedTasks(): Promise<Set<string>>;
+  /**
+   * Find tasks that other boards track but this one doesn't
+   */
+  findTasksOnOtherBoards(): Promise<Record<string, Record<string, string>>>;
   /**
    * Load the index file and parse it to an object
    * @return {Promise<object>} The index object
@@ -172,12 +478,79 @@ export class Kanbn {
    */
   loadTask(taskId: string): Promise<object>;
   /**
-   * Load all tracked tasks and return an array of task objects
+   * Load all tracked tasks and return an array of task objects. A task the index references but
+   * which has no task file is skipped rather than throwing - see findMissingTaskFiles()
    * @param {object} index The index object
    * @param {?string} [columnName=null] The optional column name to filter tasks by
    * @return {Promise<object[]>} All tracked tasks
    */
   loadAllTrackedTasks(index: object, columnName?: string | null): Promise<object[]>;
+  /**
+   * Find tasks that this board references but which have no task file
+   * @param {?object} [index=null] The index object, or null to load it
+   * @return {Promise<missingTaskFile[]>} A list of the missing tasks and the columns they're in
+   */
+  findMissingTaskFiles(index?: object | null): Promise<missingTaskFile[]>;
+  /**
+   * Find lines in this board's columns that aren't task links
+   * @param {?object} [index=null] The index object, or null to load it
+   * @return {Promise<columnContentWarning[]>} A list of warnings
+   */
+  findColumnContentWarnings(index?: object | null): Promise<columnContentWarning[]>;
+  /**
+   * Get this board's simple tasks - lines in a column that aren't task links. Real tasks always win,
+   * so callers should resolve a task id first and only fall back to this when nothing matched
+   * @param {?string} [input=null] A title to match, or null for every simple task on this board
+   * @param {?object} [index=null] The index object, or null to load it
+   * @return {Promise<simpleTask[]>} The matching simple tasks
+   */
+  findSimpleTasks(input?: string | null, index?: object | null): Promise<simpleTask[]>;
+  /**
+   * Resolve a string to exactly one simple task on this board, or throw
+   * @param {string} input The title to match
+   * @param {?object} [index=null] The index object, or null to load it
+   * @return {Promise<simpleTask>} The matching simple task
+   */
+  getSimpleTask(input: string, index?: object | null): Promise<simpleTask>;
+  /**
+   * Move a simple task to another column on this board
+   * @param {string} input The title to match
+   * @param {string} columnName The column to move it to
+   * @param {?number} [position=null] The position in the target column, or the end of it if null
+   * @return {Promise<simpleTask & { toColumn: string }>} The simple task that was moved
+   */
+  moveSimpleTask(
+    input: string,
+    columnName: string,
+    position?: number | null
+  ): Promise<simpleTask & { toColumn: string }>;
+  /**
+   * Move a simple task from this board onto another one
+   * @param {string} input The title to match
+   * @param {string} targetSlug The board to move it to
+   * @param {?string} [columnName=null] The column on the target board, or its first column if null
+   * @param {?number} [position=null] The position in the target column, or the end of it if null
+   * @return {Promise<simpleTask & { toBoard: string, toColumn: string }>} The simple task that moved
+   */
+  moveSimpleTaskToBoard(
+    input: string,
+    targetSlug: string,
+    columnName?: string | null,
+    position?: number | null
+  ): Promise<simpleTask & { toBoard: string, toColumn: string }>;
+  /**
+   * Remove a simple task from this board
+   * @param {string} input The title to match
+   * @return {Promise<simpleTask>} The simple task that was removed
+   */
+  deleteSimpleTask(input: string): Promise<simpleTask>;
+  /**
+   * Turn a simple task into a real task file
+   * @param {string} input The title to match
+   * @param {?string} [columnName=null] The column to create the task in, or its own column if null
+   * @return {Promise<string>} The id of the task that was created
+   */
+  promoteSimpleTask(input: string, columnName?: string | null): Promise<string>;
   /**
    * Load a task file from the archive and parse it to an object
    * @param {string} taskId The task id
@@ -201,6 +574,11 @@ export class Kanbn {
    * @return {Promise<boolean>} True if the current working directory has been initialised, otherwise false
    */
   initialised(): Promise<boolean>;
+  /**
+   * Check if the workspace has been initialised, regardless of which board this instance is scoped to
+   * @return {Promise<boolean>} True if the main board exists
+   */
+  workspaceInitialised(): Promise<boolean>;
   /**
    * Initialise a kanbn board in the current working directory
    * @param {object} [options={}] Initial columns and other config options
@@ -265,14 +643,14 @@ export class Kanbn {
    * @param {boolean} [relative=false] Treat the position argument as relative instead of absolute
    * @return {Promise<string>} The id of the task that was moved
    */
-  moveTask(taskId: string, columnName: string, position?: number | null, relative?: boolean): Promise<string>;
+  moveTask(taskId: string, columnName: string, position?: number | null, relative?: boolean, add?: boolean): Promise<string>;
   /**
    * Remove a task from the index and optionally delete the task file as well
    * @param {string} taskId The id of the task to remove
    * @param {boolean} [removeFile=false] True if the task file should be removed
    * @return {Promise<string>} The id of the task that was deleted
    */
-  deleteTask(taskId: string, removeFile?: boolean): Promise<string>;
+  deleteTask(taskId: string, removeFile?: boolean, allBoards?: boolean): Promise<string>;
   /**
    * Search for indexed tasks
    * @param {object} [filters={}] The filters to apply
@@ -329,7 +707,7 @@ export class Kanbn {
    * @param {string} author The comment author
    * @return {Promise<string>} The task id
    */
-  comment(taskId: string, text: string, author: string): Promise<string>;
+  comment(taskId: string, text: string, author?: string): Promise<string>;
   /**
    * Return a list of archived tasks
    * @return {Promise<string[]>} A list of archived task ids
@@ -347,7 +725,7 @@ export class Kanbn {
    * @param {?string} [columnName=null] The column to restore the task to
    * @return {Promise<string>} The task id
    */
-  restoreTask(taskId: string, columnName?: string | null): Promise<string>;
+  restoreTask(taskId: string, columnName?: string | null, singleBoard?: boolean): Promise<string>;
   /**
    * Nuke it from orbit, it's the only way to be sure
    */