@goodandready/dsh-kanban 0.2.18 → 0.2.20

package/lib/filters.js

@@ -1,58 +1,53 @@
-// Отборы доски: репозиторий и пространства меток.
+// Board filters: repository and label namespaces.
 //
-// Пространства не зашиты списком. Метки живут в Gitea и меняются без нашего
-// участия — набор уже менялся дважды за час, — поэтому пространства собираются
-// из того, что реально пришло на карточки. Зашитый список начал бы врать при
-// первой же правке разметки.
+// Namespaces are dynamically collected from task cards rather than hardcoded,
+// as Gitea labels may evolve independently without requiring code changes.
 
-/** Отбор по репозиторию стоит в одном ряду с метками, но метка ему не нужна. */
+/** Repository filter sits alongside labels without requiring a label tag. */
 export const REPO = 'repo'
 
-/** Автор задачи — такое же измерение отбора, как метка, но живёт своим полем. */
+/** Task author — filter dimension stored in its own field. */
 export const AUTHOR = 'author'
 
-/** Ответственный: кто взял задачу, а не кто её завёл. */
+/** Assignee: who is working on the task, distinct from author. */
 export const ASSIGNEE = 'assignee'
 
-/** Выпуск, к которому задача отнесена в Gitea. */
+/** Milestone assigned in Gitea. */
 export const MILESTONE = 'milestone'
 
-/** Приоритет — локальное свойство доски, своё измерение отбора. */
+/** Priority — local board property and filter dimension. */
 export const PRIORITY = 'priority'
 
 /**
- * Значение для задач без автора.
+ * Value for tasks without an author.
  *
- * Свои задачи заводятся на доске и автора не имеют. Выбросить их из отбора
- * значило бы отвечать на вопрос «кто завёл» неполным списком: «никто» — тоже
- * ответ, и по нему тоже отбирают.
+ * Local board tasks have no author. Keeping an explicit placeholder ensures
+ * filtering covers all tasks rather than silently omitting authorless items.
  */
 export const NO_AUTHOR = '—'
 
 /**
- * Значение для задач без ответственного.
+ * Value for unassigned tasks.
  *
- * «Никто не взял» — самый нужный отбор на доске: именно эти задачи ищут, когда
- * спрашивают «что свободно».
+ * Filtering by unassigned is a primary board workflow for finding available work.
  */
 export const NOBODY = '—'
 
-/** Значение для задач вне выпусков: «когда-нибудь» — тоже ответ. */
+/** Value for tasks not assigned to any milestone. */
 export const NO_MILESTONE = '—'
 
-/** Порядок приоритетов в отборе: срочное сверху. */
+/** Priority ordering in filter UI: urgent at the top. */
 const PRIORITY_ORDER = ['critical', 'high', 'medium', 'low']
 
 /**
- * Порядок известных пространств.
+ * Preferred namespace ordering.
  *
- * Алфавит поставил бы `priority` перед `type`, а смотрят в первую очередь на
- * тип и срочность. Незнакомые пространства дописываются в конец по алфавиту:
- * заведут в Gitea новое — оно появится само, без правки кода.
+ * Prioritizes type and urgency over raw alphabetical order. Unknown namespaces
+ * are appended in alphabetical order.
  */
 export const KNOWN_ORDER = ['type', 'priority', 'status', 'scope', 'risk', 'signal', 'release']
 
-/** Разбор метки на пространство и значение; без `/` — пространства нет. */
+/** Split label into namespace and value; returns undefined if no slash delimiter. */
 export function splitLabel(name) {
   const text = String(name ?? '')
   const at = text.indexOf('/')
@@ -61,15 +56,13 @@ export function splitLabel(name) {
 }
 
 /**
- * Из чего собрать отборы.
+ * Build available filter dimensions and value counts.
  *
- * Метки без пространства (`epic`, `hotfix`) своего отбора не получают: список
- * из двух значений ради двух меток — мебель. На карточках они видны и находятся
- * поиском.
+ * Bare labels without a namespace (e.g. epic, hotfix) do not generate separate
+ * filter groups; they remain visible on cards and searchable via text query.
  *
- * Считаем по ВСЕМ переданным задачам, а не по уже отобранным: счётчик рядом со
- * значением отвечает на вопрос «сколько там всего», а не «сколько осталось
- * после моего же выбора».
+ * Counts are calculated across all provided tasks rather than currently filtered
+ * tasks so the badge reflects the total pool size.
  *
  * @returns {Array<{ns: string, values: Array<{value: string, count: number}>}>}
  */
@@ -87,9 +80,7 @@ export function facetsOf(tasks) {
     add(ASSIGNEE, typeof task?.assignee === 'string' && task.assignee !== '' ? task.assignee : NOBODY)
     add(MILESTONE, typeof task?.milestone === 'string' && task.milestone !== '' ? task.milestone : NO_MILESTONE)
     add(AUTHOR, typeof task?.author === 'string' && task.author !== '' ? task.author : NO_AUTHOR)
-    // Приоритет живёт и полем (свои карточки), и меткой `priority/*` (задачи
-    // из Gitea). Оба попадают в одно измерение — отбор по срочности не должен
-    // зависеть от того, откуда пришло значение.
+    // Priority lives both in task.priority and in priority/* label: merge into one dimension.
     add(PRIORITY, typeof task?.priority === 'string' ? task.priority : '')
     for (const name of task?.labels ?? []) {
       const parsed = splitLabel(name)
@@ -107,14 +98,12 @@ export function facetsOf(tasks) {
     .sort((a, b) => rank(a.ns) - rank(b.ns) || a.ns.localeCompare(b.ns))
 }
 
-/** Репозиторий первым, затем известные пространства, затем всё прочее. */
+/** Repository first, followed by known namespaces, then alphabetical. */
 function rank(ns) {
   if (ns === REPO) return -3
-  // Ответственный идёт раньше автора: «кто делает» спрашивают чаще, чем «кто
-  // завёл».
+  // Assignee precedes author: users look for active owner more frequently than creator.
   if (ns === ASSIGNEE) return -2
-  // Выпуск идёт сразу за ответственным: «что осталось до релиза» спрашивают
-  // тогда же, когда «кто делает».
+  // Milestone immediately follows assignee.
   if (ns === MILESTONE) return -1.5
   if (ns === AUTHOR) return -1
   const at = KNOWN_ORDER.indexOf(ns)
@@ -122,10 +111,9 @@ function rank(ns) {
 }
 
 /**
- * Порядок значений внутри пространства.
+ * Value ordering within a namespace.
  *
- * Приоритет — «срочное сначала», а не алфавит: `critical` сперва, `low`
- * в самом низу. Для остальных — обычное сравнение строк.
+ * Priority uses urgency ordering (critical -> low); other namespaces use standard string comparison.
  */
 function valueRank(ns, value) {
   if (ns !== PRIORITY) return 0
@@ -134,14 +122,11 @@ function valueRank(ns, value) {
 }
 
 /**
- * Подходит ли задача под выбранное.
+ * Check whether a task satisfies the active filter selection.
  *
- * Между пространствами — И, внутри пространства — ИЛИ. «Срочные баги» это
- * `priority/high` И `type/bug`; а выбор `high` вместе с `critical` означает
- * «любая из двух», потому что срочность у задачи одна и «И» внутри
- * пространства всегда давало бы пусто.
+ * AND between namespaces, OR within each namespace.
  *
- * @param {object} selected карта пространство -> список выбранных значений
+ * @param {object} selected map of namespace -> array of selected values
  */
 export function matchesFilters(task, selected) {
   for (const [ns, values] of Object.entries(selected ?? {})) {
@@ -167,8 +152,7 @@ function hasAny(task, ns, wanted) {
     return wanted.includes(author)
   }
   if (ns === PRIORITY) {
-    // Приоритет и полем, и меткой `priority/*` — отбор по срочности не должен
-    // зависеть от источника значения.
+    // Check both field value and priority/* label.
     if (wanted.includes(typeof task?.priority === 'string' ? task.priority : '')) return true
     for (const name of task?.labels ?? []) {
       const parsed = splitLabel(name)
@@ -183,16 +167,15 @@ function hasAny(task, ns, wanted) {
   return false
 }
 
-/** Выбрано ли хоть что-нибудь: пустой набор отборов доску не сужает. */
+/** True if any filter value is currently selected. */
 export function anySelected(selected) {
   return Object.values(selected ?? {}).some((values) => (values ?? []).length > 0)
 }
 
 /**
- * Переключить одно значение.
+ * Toggle a single filter value.
  *
- * Возвращает новую карту, а не правит прежнюю: состояние отборов живёт в
- * React, и правка на месте не вызвала бы перерисовку.
+ * Returns a new object map for React state immutability.
  */
 export function toggleValue(selected, ns, value) {
   const current = (selected ?? {})[ns] ?? []
@@ -205,19 +188,17 @@ export function toggleValue(selected, ns, value) {
   return out
 }
 
-/** Снять всё разом. */
+/** Reset all active filters. */
 export function clearFilters() {
   return {}
 }
 
 /**
- * Метки задачи, разобранные по пространствам.
+ * Extract task labels grouped by namespace.
  *
- * Едет на карточке вместе с задачей: браузерная половина — отдельный бандл и
- * позвать этот модуль не может, а разбор, написанный там во второй раз,
- * однажды разойдётся с этим.
+ * Included on task payload so client bundle does not need to duplicate parsing logic.
  *
- * @returns {object} карта пространство -> список значений
+ * @returns {object} map of namespace -> array of values
  */
 export function facetsOfTask(task) {
   const out = {}
@@ -231,13 +212,12 @@ export function facetsOfTask(task) {
 }
 
 /**
- * Цвет метки из ответа Gitea.
+ * Validate hex color code from Gitea response.
  *
- * Приходит шестизначным кодом без решётки (`0e8a16`), но встречается и с ней.
- * Всё, что не похоже на шестнадцатеричный код, считаем отсутствием цвета:
- * значение попадает прямо в стиль, и пускать туда что попало нельзя.
+ * Accepts 6-character hex string with or without leading '#'.
+ * Rejects invalid strings to prevent arbitrary values in CSS styles.
  *
- * @returns {string|undefined} код без решётки
+ * @returns {string|undefined} lowercase 6-char hex code without '#'
  */
 export function labelColor(value) {
   const text = String(value ?? '').trim().replace(/^#/, '')
@@ -245,10 +225,9 @@ export function labelColor(value) {
 }
 
 /**
- * Карта имя метки -> цвет из списка меток issue.
+ * Map label name -> hex color from issue labels.
  *
- * Держим отдельно от имён: имена читают отборы, сверка, чип и поиск, и менять
- * их устройство ради оформления было бы дорого и ни к чему.
+ * Stored separately from label names to keep name parsing and matching clean.
  */
 export function colorsOfIssue(labels) {
   const out = {}
@@ -262,13 +241,10 @@ export function colorsOfIssue(labels) {
 }
 
 /**
- * Вес задачи при подъёме наверх колонки.
+ * Task rank for top-of-column sorting.
  *
- * Ждущие впереди идущих намеренно: идущая работа идёт сама, а ждущая стоит
- * из-за человека, и он должен увидеть её первой.
- *
- * Ручной порядок не переписывается — внутри каждой ступени он сохраняется, а
- * подъём работает поверх него.
+ * Waiting tasks take precedence over running tasks because waiting items require user action.
+ * Manual ordering within the same rank tier is preserved.
  */
 export function liveRank(task) {
   const state = task?.state
@@ -278,17 +254,18 @@ export function liveRank(task) {
   return 3
 }
 
-/** Вес приоритета при подъёме: срочное впереди тихого. */
+/** Priority weight for rank sorting: urgent precedes normal. */
 function priorityWeight(priority) {
   const at = PRIORITY_ORDER.indexOf(priority)
   return at === -1 ? PRIORITY_ORDER.length : at
 }
 
 /**
- * Поднять идущее наверх и приоритетное следом, не теряя прежнего порядка.
+ * Sort tasks by active state and priority while preserving relative manual order.
  *
- * Две независимые оси: сначала жизнь (ждёт/идёт/стоит), затем срочность
- * (critical → low). Ручной порядок внутри ступени сохраняется.
+ * Primary sort: lifecycle activity (waiting -> running -> stopped -> idle).
+ * Secondary sort: urgency (critical -> low).
+ * Tertiary sort: original array position.
  */
 export function sortByLife(tasks) {
   return (tasks ?? [])
@@ -300,11 +277,10 @@ export function sortByLife(tasks) {
 }
 
 /**
- * Разложить задачи по проектам.
+ * Group tasks by repository.
  *
- * Крупные группы впереди: проект с двадцатью задачами не должен теряться под
- * однозадачными. При равенстве — по имени, чтобы порядок не плясал между
- * обновлениями.
+ * Larger groups are placed first to keep active projects visible.
+ * Tied group sizes are sorted alphabetically by repo name.
  *
  * @returns {Array<{repo: string, tasks: Array<object>}>}
  */

package/lib/git-provider.js

@@ -1,9 +1,9 @@
-// Композитный маршрутизатор Git-провайдеров (Gitea и GitHub).
+// Composite router for Git providers (Gitea and GitHub).
 //
-// Предоставляет единый интерфейс к обеим системам:
-// - прозрачно направляет запросы задач в соответствующий провайдер (task.provider / issueUrl);
-// - в режиме 'auto' опрашивает настроенный провайдер или объединяет результаты поиска;
-// - позволяет доске бесшовно работать как только с Gitea, так и только с GitHub или с обоими сразу.
+// Exposes unified interface across both platforms:
+// - routes task queries to appropriate provider (task.provider / issueUrl);
+// - in 'auto' mode queries configured provider or merges search results;
+// - supports Gitea-only, GitHub-only, or simultaneous dual-forge operations.
 
 export function createGitProvider({ gitea, github, getConfig }) {
   async function resolveActiveProvider(hint) {
@@ -23,7 +23,7 @@ export function createGitProvider({ gitea, github, getConfig }) {
     if (mode === 'github') return github
     if (mode === 'gitea') return gitea
 
-    // В режиме 'auto': проверяем доступность провайдеров
+    // In 'auto' mode: check provider availability
     const giteaReady = await gitea.isConfigured()
     const githubReady = await github.isConfigured()
     if (githubReady && !giteaReady) return github
@@ -40,10 +40,10 @@ export function createGitProvider({ gitea, github, getConfig }) {
     gitea,
     github,
 
-    /** Определить провайдера для задачи или контекста. */
+    /** Resolve provider for task or context. */
     resolve: resolveActiveProvider,
 
-    /** Настроен ли хотя бы один или конкретный провайдер. */
+    /** Whether any or specific provider is configured. */
     async isConfigured(providerName) {
       if (providerName === 'github') return github.isConfigured()
       if (providerName === 'gitea') return gitea.isConfigured()
@@ -52,81 +52,81 @@ export function createGitProvider({ gitea, github, getConfig }) {
       return github.isConfigured()
     },
 
-    /** Логин текущего пользователя. */
+    /** Current user login. */
     async me(target) {
       const p = forTarget(target) || await resolveActiveProvider(target)
       return p.me()
     },
 
-    /** Список issues. */
+    /** List issues. */
     async listIssues(options) {
       const p = forTarget(options?.provider) || await resolveActiveProvider(options)
       return p.listIssues(options)
     },
 
-    /** Получить issue по номеру. */
+    /** Get issue by number. */
     async getIssue(options) {
       const p = forTarget(options?.provider) || await resolveActiveProvider(options)
       return p.getIssue(options)
     },
 
-    /** Создать issue. */
+    /** Create issue. */
     async createIssue(options) {
       const p = forTarget(options?.provider) || await resolveActiveProvider(options)
       return p.createIssue(options)
     },
 
-    /** Закрыть issue. */
+    /** Close issue. */
     async closeIssue(options) {
       const p = forTarget(options?.provider) || await resolveActiveProvider(options)
       return p.closeIssue(options)
     },
 
-    /** Комментарий в issue. */
+    /** Comment on issue. */
     async comment(options) {
       const p = forTarget(options?.provider) || await resolveActiveProvider(options)
       return p.comment(options)
     },
 
-    /** Назначить ответственных. */
+    /** Assign responsible users. */
     async setAssignees(options) {
       const p = forTarget(options?.provider) || await resolveActiveProvider(options)
       return p.setAssignees(options)
     },
 
-    /** Список Pull Requests. */
+    /** List Pull Requests. */
     async listPulls(options) {
       const p = forTarget(options?.provider) || await resolveActiveProvider(options)
       return p.listPulls(options)
     },
 
-    /** Создать Pull Request. */
+    /** Create Pull Request. */
     async createPullRequest(options) {
       const p = forTarget(options?.provider) || await resolveActiveProvider(options)
       return p.createPullRequest(options)
     },
 
-    /** Список веток репозитория. */
+    /** List repository branches. */
     async listBranches(options) {
       const p = forTarget(options?.provider) || await resolveActiveProvider(options)
       return p.listBranches(options)
     },
 
-    /** Список организаций. */
+    /** List organizations. */
     async listOrgs(target) {
       const p = forTarget(target) || await resolveActiveProvider(target)
       return p.listOrgs()
     },
 
-    /** Репозитории организации. */
+    /** Organization repositories. */
     async listOrgRepos(options) {
       const p = forTarget(options?.provider) || await resolveActiveProvider(options)
       return p.listOrgRepos(options)
     },
 
     /**
-     * Поиск репозиториев: ищет в целевом провайдере либо агрегирует результаты
-     * из обоих, если включены оба.
+     * Search repositories: queries target provider or aggregates results
+     * from both if enabled.
      */
     async searchRepos(options) {
       const target = forTarget(options?.provider)
@@ -138,7 +138,7 @@ export function createGitProvider({ gitea, github, getConfig }) {
       if (mode === 'github') return github.searchRepos(options)
       if (mode === 'gitea') return gitea.searchRepos(options)
 
-      // Если режим 'auto' / 'both', опрашиваем оба настроенных
+      // If 'auto' / 'both' mode, query both configured providers
       const [giteaConfigured, githubConfigured] = await Promise.all([
         gitea.isConfigured(),
         github.isConfigured(),