@goodandready/dsh-kanban 0.2.19 → 0.2.20

package/lib/import.js

@@ -1,20 +1,19 @@
-// Перенос issue Gitea в задачу доски.
+// Transfer Gitea issue to a board task.
 //
-// Синхронизация в 0.1 односторонняя: Gitea → канбан, в момент импорта и по
-// кнопке обновления. Двусторонняя синхронизация — отдельный выпуск, и тянуть
-// её сюда нельзя.
+// Synchronization in 0.1 is one-way: Gitea -> kanban, at import time and on
+// manual refresh. Two-way synchronization is handled separately.
 //
-// Клиент Gitea приходит параметром — его собирает `lib/gitea.js`. Здесь только
-// перенос полей и решение, что делать, когда доступ не настроен.
+// Gitea client is passed as a parameter — configured by `lib/gitea.js`. Here
+// we only map fields and handle cases where access is not configured.
 
 import { safeSegment } from './gitea.js'
 import { colorsOfIssue } from './filters.js'
 
 /**
- * Когда issue завели в Gitea.
+ * When the issue was created in Gitea.
  *
- * Без этого карточка показывала бы дату подхвата: задача годичной давности
- * выглядела бы заведённой сегодня, и по дате нельзя было бы понять ничего.
+ * Without this, the card would show the import timestamp: a year-old issue
+ * would appear created today, losing chronological context.
  */
 export function issueBornAt(issue) {
   const at = Date.parse(issue?.created_at ?? '')
@@ -22,11 +21,10 @@ export function issueBornAt(issue) {
 }
 
 /**
- * Кто завёл issue.
+ * Issue author.
  *
- * Берём `login`: он же стоит в Gitea под задачей и по нему её ищут. Полное
- * имя заполнено не у всех, и подставлять его вместо логина значило бы
- * показывать то одно, то другое.
+ * Uses `login`: matches what Gitea displays under the issue and search queries.
+ * Full name is not set for all users, so using it would cause inconsistencies.
  */
 export function issueAuthor(issue) {
   const login = issue?.user?.login
@@ -34,12 +32,11 @@ export function issueAuthor(issue) {
 }
 
 /**
- * Кто отвечает за issue.
+ * Issue assignee.
  *
- * Gitea отдаёт назначенного двумя способами: одиночным `assignee` и списком
- * `assignees`. Берём первого из списка, когда одиночного нет: доска показывает
- * ОДНОГО ответственного, потому что «отвечают все» означает «не отвечает
- * никто».
+ * Gitea returns assignees in two ways: single `assignee` and list `assignees`.
+ * Pick the first from the list if single is absent: board tracks a single
+ * responsible assignee.
  */
 export function issueAssignee(issue) {
   const one = issue?.assignee?.login
@@ -50,10 +47,10 @@ export function issueAssignee(issue) {
 }
 
 /**
- * К какому выпуску относится issue.
+ * Milestone the issue belongs to.
  *
- * Релизы ведут майлстоунами Gitea, а доска о них не знала: «что осталось до
- * 0.2.0» приходилось смотреть в другом месте, хотя карточки лежат здесь.
+ * Releases are tracked via Gitea milestones; board stores milestone title
+ * so release progress can be monitored directly on cards.
  */
 export function issueMilestone(issue) {
   const title = issue?.milestone?.title
@@ -61,13 +58,13 @@ export function issueMilestone(issue) {
 }
 
 /**
- * Поля задачи из issue.
+ * Map task fields from an issue.
  *
- * `owner` и `repo` берутся из запроса, а не из issue: API Gitea возвращает их
- * не во всех формах ответа, и полагаться на это нельзя.
+ * `owner` and `repo` come from request context, not the issue payload: Gitea API
+ * does not return them in all response shapes.
  *
- * Поля `branch`, `worktree`, `sessionId`, `model` НЕ заполняются: они
- * наблюдаются позже, когда работа начнётся. Плагин ветки не создаёт.
+ * Fields `branch`, `worktree`, `sessionId`, `model` are NOT populated here:
+ * they are assigned later when work begins. The plugin does not create branches on import.
  */
 export function issueToTask(issue, { board = 'main', column = 'backlog', owner, repo, provider }) {
   const p = provider || (typeof issue?.html_url === 'string' && issue.html_url.includes('github.com') ? 'github' : 'gitea')
@@ -80,8 +77,7 @@ export function issueToTask(issue, { board = 'main', column = 'backlog', owner,
     labels: Array.isArray(issue?.labels)
       ? issue.labels.map((l) => (typeof l === 'string' ? l : l?.name)).filter((n) => typeof n === 'string')
       : [],
-    // Цвета едут рядом с именами, а не вместо них: имена читают отборы,
-    // сверка, чип и поиск.
+    // Colors are kept alongside names for filters, reconciler, chip, and search.
     labelColors: colorsOfIssue(issue?.labels),
     owner,
     repo,
@@ -95,13 +91,10 @@ export function issueToTask(issue, { board = 'main', column = 'backlog', owner,
 }
 
 /**
- * Пометить issue, которые уже лежат на доске.
+ * Mark issues that already exist on the board.
  *
- * Сравнение идёт по тройке владелец–репозиторий–номер. Сравнение по одному
- * номеру пометило бы задачу №1 из чужого репозитория как уже импортированную.
- *
- * Помеченные не прячутся, а приглушаются: задачу иногда заводят второй раз
- * осознанно.
+ * Compared by owner-repo-number tuple to avoid colliding with issue #1 in another repo.
+ * Existing issues are dimmed rather than hidden, as re-importing may be intentional.
  */
 export function markImported(issues, existing, { owner, repo }) {
   const seen = new Set(
@@ -113,11 +106,10 @@ export function markImported(issues, existing, { owner, repo }) {
 }
 
 /**
- * Что переписать в задаче при обновлении из issue.
+ * Fields to overwrite when updating a task from an issue.
  *
- * Переписываются только поля, пришедшие из Gitea. Локальные — колонка,
- * позиция, сессия, модель — не трогаются: иначе обновление сбрасывало бы
- * работу, которая уже идёт.
+ * Only fields originating from Gitea are updated. Local fields (column,
+ * position, session, model) are preserved to avoid resetting active work.
  */
 export function refreshPatch(task, issue) {
   const patch = {}
@@ -134,24 +126,20 @@ export function refreshPatch(task, issue) {
   if (born !== undefined) patch.createdAt = born
   const author = issueAuthor(issue)
   if (author !== '') patch.author = author
-  // Снятие ответственного — тоже факт, поэтому пустое значение пишется наравне
-  // с именем: иначе доска показывала бы вчерашнего владельца задачи, с которой
-  // его уже сняли.
+  // Explicit empty assignee when cleared in Gitea so board does not retain stale assignee.
   if (issue?.assignee !== undefined || Array.isArray(issue?.assignees)) {
     patch.assignee = issueAssignee(issue)
   }
-  // Майлстоун снимают так же часто, как ставят, поэтому пустое значение —
-  // тоже новость, а не отсутствие новостей.
+  // Milestone removal is also explicitly recorded.
   if ('milestone' in (issue ?? {})) patch.milestone = issueMilestone(issue)
   return patch
 }
 
 /**
- * Клиент Gitea готов к работе. Отсутствие клиента и ненастроенный доступ —
- * разные беды, и человеку они говорят разное.
+ * Check if Gitea client is configured and ready.
  *
- * Проверка асинхронная, потому что готовность включает разрешение учётной
- * записи с токеном, а это обращение к службе учётных данных.
+ * Missing client vs unconfigured access are distinct error states.
+ * Async check includes token credential verification.
  */
 export async function giteaState(gitea) {
   if (gitea === undefined || gitea === null) return 'absent'
@@ -163,9 +151,7 @@ export async function giteaState(gitea) {
   }
 }
 
-/**
- * Список issue для диалога импорта: открытые, уже импортированные помечены.
- */
+/** List open issues for import dialog, marking already-imported ones. */
 export async function listImportable({ gitea, store, owner, repo, board = 'main' }) {
   const state = await giteaState(gitea)
   if (state !== 'ready') return { error: `gitea-${state}`, status: 409 }
@@ -174,20 +160,19 @@ export async function listImportable({ gitea, store, owner, repo, board = 'main'
   return { issues: markImported(issues, existing, { owner, repo }) }
 }
 
-/** Завести задачу из issue. */
+/** Create a task from an issue. */
 export async function importIssue({ gitea, store, owner, repo, issueNumber, board = 'main', column = 'backlog' }) {
   const state = await giteaState(gitea)
   if (state !== 'ready') return { error: `gitea-${state}`, status: 409 }
   if (typeof issueNumber !== 'number') return { error: 'issue-number-required', status: 400 }
-  // Простая доска — для задач без issue. Импорт на неё привёл бы задачу с
-  // веткой и PR в набор колонок, где их некуда показать.
+  // Simple board is for non-issue tasks. Importing here would bring branches/PRs into columns unable to display them.
   if (store.boardKind(board) !== 'project') return { error: 'board-not-for-issues', status: 400 }
   const issue = await gitea.getIssue({ owner, repo, index: issueNumber })
   if (issue === undefined || issue === null) return { error: 'issue-not-found', status: 404 }
   return { task: store.createTask(issueToTask(issue, { board, column, owner, repo })) }
 }
 
-/** Перечитать issue и обновить задачу, не трогая локальные поля. */
+/** Re-read issue and update task, preserving local state. */
 export async function refreshTask({ gitea, store, id }) {
   const state = await giteaState(gitea)
   if (state !== 'ready') return { error: `gitea-${state}`, status: 409 }
@@ -199,7 +184,7 @@ export async function refreshTask({ gitea, store, id }) {
   return { task: store.updateTask(id, refreshPatch(task, issue)) }
 }
 
-/** Поиск репозиториев для диалога импорта. */
+/** Search repositories for import dialog. */
 export async function searchRepos({ gitea, query, limit = 20 }) {
   const state = await giteaState(gitea)
   if (state !== 'ready') return { error: `gitea-${state}`, status: 409 }
@@ -207,16 +192,11 @@ export async function searchRepos({ gitea, query, limit = 20 }) {
 }
 
 /**
- * Завести проектную задачу: issue в Gitea плюс карточка, привязанная к нему.
- *
- * Репозиторий либо выбирается из существующих, либо заводится по имени.
- * Заводит его ЧЕЛОВЕК кнопкой: инструмента у агента для этого нет — он
- * пользуется `gitea_issue_create` из соседнего плагина, а карточка приезжает
- * подхватом.
+ * Create a project task: Gitea issue plus linked board card.
  *
- * Порядок неслучаен: сперва репозиторий, потом issue, потом карточка. Обрыв на
- * середине не должен оставить карточку привязанной к репозиторию без issue —
- * лучше не завести карточку вовсе и сказать об этом, чем завести полупустую.
+ * Repository is selected from existing list or created by name.
+ * Order of operations: repo first, then issue, then board card.
+ * Failure midway avoids leaving orphaned cards.
  */
 export async function createProjectTask({
   gitea, store, owner, repo, newRepo, title, body, board = 'main',
@@ -231,7 +211,7 @@ export async function createProjectTask({
   if (targetRepo === '') {
     const wanted = typeof newRepo === 'string' ? newRepo.trim() : ''
     if (wanted === '') return { error: 'repo-required', status: 400 }
-    // Имя проверяем ДО запроса: отказ Gitea пришёл бы позже и невнятнее.
+    // Validate repository name before API call.
     if (safeSegment(wanted) === undefined) return { error: 'bad-repo-name', status: 400 }
     try {
       await gitea.createRepo({ owner, name: wanted })
@@ -245,8 +225,7 @@ export async function createProjectTask({
   try {
     issue = await gitea.createIssue({ owner, repo: targetRepo, title: name, body })
   } catch (error) {
-    // Репозиторий, возможно, уже создан. Не удаляем его: удаление чужого
-    // добра из-за своей неудачи хуже лишнего пустого репозитория.
+    // Repository may have already been created; avoid deleting on issue creation failure.
     return { error: 'issue-not-created', status: 502, detail: String(error?.message ?? error) }
   }