@kernhq/module-tracker 0.7.3 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernhq/module-tracker",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "description": "Kern tracker module: projects, work item types, custom fields, workflows, issues, KQL, cycles, views, reports, intake, time tracking (server + client skeleton)",
   "license": "AGPL-3.0-only",
   "type": "module",

package/src/client/index.ts

@@ -57,4 +57,5 @@ export {
   rankForIndex,
   rankSequence,
 } from './rank.js'
+export { describeApprovers, describeRule, type RuleDescription } from './rules.js'
 export type * from './types.js'

package/src/client/rules.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import { describeApprovers, describeRule } from './rules.js'
+
+const say = (type: string, config?: unknown) => describeRule({ type, config }).text
+
+describe('describeRule', () => {
+  it('says who may do it', () => {
+    expect(say('user.isAssignee')).toBe('Only the assignee')
+    expect(say('user.hasPermission', { permission: 'tracker.issue.transition' })).toBe(
+      'Only somebody with “tracker.issue.transition”',
+    )
+  })
+
+  it('says what has to be true first', () => {
+    expect(say('subtasks.allDone')).toBe('Only when every sub-issue is done')
+    expect(say('field.equals', { field: 'priority', value: 'urgent' })).toBe('Only when priority is “urgent”')
+  })
+
+  it('says what has to be filled in', () => {
+    expect(say('comment.required')).toBe('A comment is required')
+    expect(say('field.required', { field: 'resolution' })).toBe('resolution must be filled in')
+  })
+
+  it('says what happens afterwards, in the terms the config uses', () => {
+    expect(say('assign.to', { to: 'currentUser' })).toBe('Assigns it to whoever moved it')
+    expect(say('assign.to', { to: 'unassigned' })).toBe('Assigns it to nobody')
+    expect(say('resolution.set', { value: 'done' })).toBe('Sets the resolution to “done”')
+    expect(say('resolution.set', { value: null })).toBe('Clears the resolution')
+    expect(say('notify', { subjects: [{ kind: 'assignee' }, { kind: 'reporter' }] })).toBe(
+      'Notifies the assignee, the reporter',
+    )
+  })
+
+  it('copes with a rule that arrives without its configuration', () => {
+    // A definition written by hand, or one from an older server.
+    expect(say('field.required')).toBe('A field must be filled in')
+    expect(say('webhook')).toBe('Calls a webhook')
+  })
+
+  it('names a rule it does not know rather than guessing', () => {
+    // A rule from a newer server, or one an extension added.
+    const described = describeRule({ type: 'acme.custom_check' })
+    expect(described.text).toBe('acme.custom_check')
+    expect(described.unknown).toBe(true)
+  })
+})
+
+describe('describeApprovers', () => {
+  it('says how many and from whom', () => {
+    expect(describeApprovers([{ kind: 'role', id: 'admin' }], 1)).toBe(
+      'Approval from anyone with the admin role',
+    )
+    expect(describeApprovers([{ kind: 'projectLead' }], 2)).toBe('2 approvals from the project lead')
+  })
+
+  it('says nobody when the list is empty, which is a workflow that can never proceed', () => {
+    expect(describeApprovers([], 1)).toBe('Approval from nobody')
+  })
+})

package/src/client/rules.ts

@@ -0,0 +1,125 @@
+import type { RuleRef } from '@kernhq/workflow'
+
+/**
+ * A workflow rule, said the way an administrator thinks about it.
+ *
+ * A transition's conditions, validators and post-functions are stored as `{type, config}`, which is
+ * the right thing to store and the wrong thing to show: an editor that renders JSON asks somebody
+ * to read a data structure to answer "who is allowed to close this".
+ *
+ * This lives in the module that owns the rules, so a rule and the sentence describing it cannot
+ * drift into different repositories. Every rule type the registry defines has a case; an unknown
+ * one — a rule from a newer server, or one an extension added — says its type rather than
+ * pretending to know it.
+ */
+
+export interface RuleDescription {
+  /** the sentence to show */
+  text: string
+  /** true when nothing here understood the rule, so an interface can mark it as such */
+  unknown: boolean
+}
+
+type Config = Record<string, unknown>
+
+const str = (config: Config, key: string, fallback = '') => {
+  const value = config[key]
+  return typeof value === 'string' && value ? value : fallback
+}
+
+/** `{kind, id}` subjects, as a list somebody can read. */
+function describeSubjects(value: unknown): string {
+  if (!Array.isArray(value) || !value.length) return 'nobody'
+  return value
+    .map((entry) => {
+      const subject = (entry ?? {}) as { kind?: string; id?: string }
+      switch (subject.kind) {
+        case 'assignee':
+          return 'the assignee'
+        case 'reporter':
+          return 'the reporter'
+        case 'projectLead':
+          return 'the project lead'
+        case 'group':
+          return 'a group'
+        case 'role':
+          return subject.id ? `anyone with the ${subject.id} role` : 'a role'
+        case 'user':
+          return 'a named person'
+        case 'field':
+          return subject.id ? `whoever is in ${subject.id}` : 'a field'
+        default:
+          return subject.kind ?? 'somebody'
+      }
+    })
+    .join(', ')
+}
+
+export function describeRule(rule: RuleRef): RuleDescription {
+  const config = (rule.config ?? {}) as Config
+  const known = (text: string): RuleDescription => ({ text, unknown: false })
+
+  switch (rule.type) {
+    // conditions — who may do it, and when
+    case 'user.hasPermission':
+      return known(`Only somebody with “${str(config, 'permission', 'a permission')}”`)
+    case 'user.isAssignee':
+      return known('Only the assignee')
+    case 'user.isReporter':
+      return known('Only the reporter')
+    case 'user.inGroup':
+      return known('Only members of a particular group')
+    case 'field.equals':
+      return known(`Only when ${str(config, 'field', 'a field')} is “${String(config.value ?? '')}”`)
+    case 'field.notEmpty':
+      return known(`Only when ${str(config, 'field', 'a field')} has a value`)
+    case 'subtasks.allDone':
+      return known('Only when every sub-issue is done')
+
+    // validators — what has to be filled in first
+    case 'field.required':
+      return known(`${str(config, 'field', 'A field')} must be filled in`)
+    case 'comment.required':
+      return known('A comment is required')
+    case 'estimate.required':
+      return known('An estimate is required')
+
+    // post-functions — what happens afterwards
+    case 'field.set':
+      return known(`Sets ${str(config, 'field', 'a field')} to “${String(config.value ?? '')}”`)
+    case 'assign.to': {
+      const to = str(config, 'to')
+      const who =
+        to === 'currentUser'
+          ? 'whoever moved it'
+          : to === 'reporter'
+            ? 'the reporter'
+            : to === 'unassigned'
+              ? 'nobody'
+              : 'a named person'
+      return known(`Assigns it to ${who}`)
+    }
+    case 'resolution.set': {
+      const value = config.value
+      return known(value === null ? 'Clears the resolution' : `Sets the resolution to “${String(value)}”`)
+    }
+    case 'notify':
+      return known(`Notifies ${describeSubjects(config.subjects)}`)
+    case 'webhook':
+      return known(`Calls ${str(config, 'url', 'a webhook')}`)
+    case 'subitem.create':
+      return known(`Creates a sub-issue called “${str(config, 'title', 'something')}”`)
+    case 'run.automation':
+      return known('Runs an automation')
+
+    default:
+      // Naming the type is more use than a guess: somebody can search for it.
+      return { text: rule.type, unknown: true }
+  }
+}
+
+/** Who may approve, for a transition that needs sign-off. */
+export function describeApprovers(subjects: unknown, minApprovals: number): string {
+  const who = describeSubjects(subjects)
+  return minApprovals > 1 ? `${minApprovals} approvals from ${who}` : `Approval from ${who}`
+}

package/src/client/types.ts

@@ -32,6 +32,7 @@ export type {
   IssueQueryInput,
   IssueQueryResult,
   IssueSummary,
+  IssueTemplate,
   KqlFieldInfo,
   KqlParseResult,
   KqlSuggestion,
@@ -47,6 +48,8 @@ export type {
   ProjectTemplateBody,
   ProjectTemplateId,
   ReactionSummary,
+  RecurrenceRule,
+  RecurringIssue,
   RelationSummary,
   RelationType,
   RelationView,