@basementuniverse/kanbn 2.1.0 → 2.5.1

package/src/main.d.ts

@@ -29,11 +29,41 @@ declare type boardSummary = board & {
   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 = {
@@ -80,8 +110,58 @@ 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, options?: { board?: string, caches?: any });
+  constructor(root?: any, options?: { board?: string, caches?: any, actions?: boolean });
   ROOT: string;
   CONFIG_YAML: string;
   CONFIG_JSON: string;
@@ -90,6 +170,30 @@ export class Kanbn {
    * 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
@@ -215,6 +319,35 @@ export class Kanbn {
    * 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
    */
@@ -345,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
@@ -507,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