@goodandready/dsh-kanban 0.2.18 → 0.2.20

package/lib/gitea.js

@@ -1,28 +1,24 @@
-// Клиент Gitea для доски.
+// Gitea HTTP API client.
 //
-// Своего клиента канбан держит намеренно: токен всё равно живёт в службе
-// учётных данных ядра, а не в соседнем плагине, и шесть вызовов REST дешевле,
-// чем зависимость от чужого выпуска.
+// Standalone module without external dependencies, communicating directly with Gitea v1 API.
+// Network calls use injectable fetch (`fetchImpl`), and token resolution is provided via callback.
+// The client can be unit tested without making real network requests.
 //
-// Сеть приходит параметром (`fetchImpl`), токен — функцией разрешения.
-// Поэтому клиент проверяется без единого реального запроса.
-//
-// Токен в настройках не хранится: там только ИМЯ учётной записи. Наружу
-// значение не отдаётся никогда, включая сообщения об ошибках.
+// Secrets are not stored in settings; only the credential name is stored.
+// Token values are never emitted to logs or error messages.
 
-/** Убрать хвостовые слэши: адрес приходит из поля, куда человек пишет как хочет. */
+/** Strip trailing slashes from base URL. */
 export function normalizeBaseUrl(url) {
   return String(url || '').trim().replace(/\/+$/, '')
 }
 
 /**
- * Сегмент пути, пригодный для подстановки в URL.
+ * Path segment sanitized for URL interpolation.
  *
- * `owner`, `repo` и номер приходят из данных Gitea и из браузера, а не из
- * кода. Без проверки сюда подставится `..` или слэш, и запрос уйдёт не туда,
- * куда собирались.
+ * `owner`, `repo`, and issue index originate from external data or user input.
+ * Sanitization prevents directory traversal or path manipulation.
  *
- * @returns {string|undefined} закодированный сегмент либо undefined
+ * @returns {string|undefined} encoded segment or undefined if invalid
  */
 export function safeSegment(value) {
   const s = String(value ?? '').trim()
@@ -31,27 +27,23 @@ export function safeSegment(value) {
   return encodeURIComponent(s)
 }
 
-/** Имя учётной записи — имя переменной окружения, а не сам секрет. */
+/** Credential reference name (e.g. env var name), distinct from the raw secret. */
 export function isCredentialName(value) {
   const str = String(value || '')
   if (looksLikeSecret(str)) return false
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(str)
 }
 
-/** Похоже на сам токен, а не на его имя. */
+/** Check if value looks like a raw token secret rather than a credential reference name. */
 export function looksLikeSecret(value) {
   return /^[A-Za-z0-9_-]{32,}$/.test(String(value || '').trim())
 }
 
 /**
- * Упорядочить репозитории по актуальности.
- *
- * Сверху те, где работа идёт прямо сейчас. Признак «идёт» выбран самый честный
- * из доступных без лишних запросов: есть открытые задачи И репозиторий недавно
- * трогали. Архивные уходят вниз всегда — там работы не ведут по определению.
+ * Rank repositories by activity.
  *
- * Точного «ведётся прямо сейчас» инстанс не знает, и выдумывать его не из чего;
- * это приближение, а не истина.
+ * Places active repositories with open tasks and recent updates at the top.
+ * Archived repositories are sorted to the bottom.
  */
 export function rankRepos(repos) {
   const rank = (r) => {
@@ -69,12 +61,12 @@ export function rankRepos(repos) {
 }
 
 /**
- * Клиент Gitea.
+ * Gitea client factory.
  *
  * @param {object} options
- * @param {() => object} options.getConfig текущие настройки плагина
- * @param {(name: string) => Promise<string>} options.resolveToken разрешение учётной записи
- * @param {Function} [options.fetchImpl] реализация fetch
+ * @param {() => object} options.getConfig current plugin configuration
+ * @param {(name: string) => Promise<string>} options.resolveToken credential resolver callback
+ * @param {Function} [options.fetchImpl] fetch implementation
  * @param {number} [options.timeoutMs]
  */
 export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch, timeoutMs = 30_000 }) {
@@ -92,8 +84,7 @@ export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch,
       const res = await fetchImpl(`${baseUrl}/api/v1${path}`, {
         method,
         headers: {
-          // Заголовком, а не basic-авторизацией: на внутренних сетях basic
-          // отдаёт «Missing API key».
+          // Use header authorization rather than basic auth to avoid 'Missing API key' on private instances.
           'Authorization': `token ${token}`,
           'Content-Type': 'application/json',
           'Accept': 'application/json',
@@ -105,7 +96,7 @@ export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch,
       let payload
       try { payload = text.trim() === '' ? null : JSON.parse(text) } catch { payload = null }
       if (!res.ok) {
-        // Тело ответа наружу не выносим: в нём может быть эхо заголовков.
+        // Do not leak raw response body in error messages to prevent echoing sensitive headers.
         throw Object.assign(new Error(`Gitea HTTP error ${res.status}`), { code: 'http', status: res.status })
       }
       return payload
@@ -124,18 +115,13 @@ export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch,
   }
 
   /**
-   * Собрать голый массив со всех страниц.
-   *
-   * Gitea отдаёт списки порциями, и запрос без перелистывания молча теряет
-   * хвост. Признак конца — неполная страница: инстанс отдал меньше, чем
-   * просили, значит дальше пусто. Верхний предел стоит, чтобы очень большой
-   * ответ не превратил сверку в бесконечный поход.
+   * Paginate and collect all items from Gitea endpoints up to maxPages.
    *
    * @param {object} options
-   * @param {(page: number, size: number) => string} options.buildPath путь страницы
-   * @param {number} [options.limit] размер страницы
-   * @param {number} [options.maxPages] верхний предел страниц
-   * @returns {Promise<Array>} все строки со всех прочитанных страниц
+   * @param {(page: number, size: number) => string} options.buildPath page path builder
+   * @param {number} [options.limit] page size
+   * @param {number} [options.maxPages] maximum pages to retrieve
+   * @returns {Promise<Array>} concatenated results from all pages
    */
   async function collectPages({ buildPath, limit, maxPages = 10 }) {
     const size = Math.min(Math.max(Number(limit) || 50, 1), 50)
@@ -149,10 +135,8 @@ export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch,
     return out
   }
 
-  // Признак «настроено» кэшируется по ключу настроек. `isConfigured` стоит в
-  // горячем пути — его спрашивают на каждый запрос списка issue и поиска
-  // репозиториев, — а резолв токена это поход в хранилище учётных данных.
-  // Пока адрес и имя учётной записи не менялись, ответ не мог измениться.
+  // Cache configuration check result keyed on URL and token reference to avoid
+  // repeated credential lookups on hot paths.
   let configuredCache
   const configuredKey = () => {
     const config = getConfig()
@@ -160,7 +144,7 @@ export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch,
   }
 
   return {
-    /** Настроен ли доступ. Значение токена наружу не отдаётся. */
+    /** Check whether access is configured. Token value is never exposed. */
     async isConfigured() {
       const key = configuredKey()
       if (configuredCache?.key === key) return configuredCache.value
@@ -173,46 +157,38 @@ export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch,
     },
 
     async listIssues({ owner, repo, state = 'open', limit = 50 }) {
-      // API отдаёт issue и pull request одним списком; доске нужны только issue.
-      // Перелистываем до конца: при 50+ открытых issue хвост иначе теряется
-      // молча, и подхват задач смотрит на неполную картину.
+      // API returns issues and PRs together; filter out pull requests and paginate completely.
       const rows = await collectPages({
         limit,
         buildPath: (page, size) => repoPath(owner, repo,
-          `/issues?state=${encodeURIComponent(state)}&page=${page}&limit=${size}&sort=updated&direction=desc`),
+          `/issues?state=${encodeURIComponent(state)}&page=${page}&limit=${size}`),
       })
-      return rows.filter((r) => !r.pull_request)
+      return rows.filter((i) => i.pull_request === undefined)
     },
 
     async getIssue({ owner, repo, index }) {
       const n = safeSegment(index)
-      if (n === undefined) throw Object.assign(new Error('недопустимый номер issue'), { code: 'bad-segment' })
+      if (n === undefined) throw Object.assign(new Error('invalid issue number'), { code: 'bad-segment' })
       return request('GET', repoPath(owner, repo, `/issues/${n}`))
     },
 
     async comment({ owner, repo, index, body }) {
       const n = safeSegment(index)
-      if (n === undefined) throw Object.assign(new Error('недопустимый номер issue'), { code: 'bad-segment' })
+      if (n === undefined) throw Object.assign(new Error('invalid issue number'), { code: 'bad-segment' })
       return request('POST', repoPath(owner, repo, `/issues/${n}/comments`), { body })
     },
 
-    /** Завести issue. Метки не ставим: доска чужой разметкой не распоряжается. */
+    /** Create issue. Labels are omitted here to respect repository conventions. */
     async createIssue({ owner, repo, title, body }) {
       const name = String(title ?? '').trim()
-      if (name === '') throw Object.assign(new Error('пустой заголовок'), { code: 'bad-title' })
+      if (name === '') throw Object.assign(new Error('empty title'), { code: 'bad-title' })
       return request('POST', repoPath(owner, repo, '/issues'), { title: name, body: String(body ?? '') })
     },
 
-    /**
-     * Завести репозиторий в организации.
-     *
-     * Приватный и пустой — так решил владелец: расширить права потом дешевле,
-     * чем убирать лишнее из публичного, а пустой репозиторий честнее чужих
-     * заготовок.
-     */
+    /** Create private, empty repository in organization. */
     async createRepo({ owner, name, description = '' }) {
       const safe = safeSegment(name)
-      if (safe === undefined) throw Object.assign(new Error('недопустимое имя'), { code: 'bad-segment' })
+      if (safe === undefined) throw Object.assign(new Error('invalid name'), { code: 'bad-segment' })
       return request('POST', `/orgs/${safeSegment(owner)}/repos`, {
         name: safe, description, private: true, auto_init: false,
       })
@@ -220,39 +196,27 @@ export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch,
 
     async closeIssue({ owner, repo, index }) {
       const n = safeSegment(index)
-      if (n === undefined) throw Object.assign(new Error('недопустимый номер issue'), { code: 'bad-segment' })
+      if (n === undefined) throw Object.assign(new Error('invalid issue number'), { code: 'bad-segment' })
       return request('PATCH', repoPath(owner, repo, `/issues/${n}`), { state: 'closed' })
     },
 
-    /**
-     * Назначить ответственного за issue.
-     *
-     * Пустой список снимает назначение: Gitea понимает это как «никто», и
-     * доска обязана уметь то же самое — иначе снять с себя задачу можно было
-     * бы только руками в Gitea.
-     */
+    /** Set issue assignees. Empty array clears assignees. */
     async setAssignees({ owner, repo, index, logins }) {
       const n = safeSegment(index)
-      if (n === undefined) throw Object.assign(new Error('недопустимый номер issue'), { code: 'bad-segment' })
+      if (n === undefined) throw Object.assign(new Error('invalid issue number'), { code: 'bad-segment' })
       const list = (Array.isArray(logins) ? logins : [])
         .filter((one) => typeof one === 'string' && one !== '')
       return request('PATCH', repoPath(owner, repo, `/issues/${n}`), { assignees: list })
     },
 
-    /**
-     * Кто мы для Gitea.
-     *
-     * «Взять себе» на доске значит «назначить того, чьим токеном доска ходит»:
-     * своего понятия пользователя у харнесса нет, и выдумывать его вместо
-     * ответа сервера нельзя.
-     */
+    /** Authenticated user identity for the token. */
     async me() {
       const row = await request('GET', '/user')
       const login = row?.login
       return typeof login === 'string' ? login : ''
     },
 
-    /** Организации, доступные токену. Нужны, чтобы не спрашивать владельца лишний раз. */
+    /** List organizations accessible to the token. */
     async listOrgs() {
       const rows = await request('GET', '/user/orgs?limit=50')
       return (Array.isArray(rows) ? rows : [])
@@ -260,14 +224,7 @@ export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch,
         .filter((name) => name !== '')
     },
 
-    /**
-     * Репозитории организации с числом открытых задач.
-     *
-     * Число приходит в том же ответе, и по нему отсеиваются пустые: ходить за
-     * задачами в репозиторий, где их нет, — полсотни запросов впустую каждые
-     * две минуты. Перелистываем: при 100+ репозиториях одна страница теряла бы
-     * хвост, и доска смотрела бы на неполную организацию.
-     */
+    /** List organization repositories with open issue counts, paginating to handle large orgs. */
     async listOrgRepos({ owner, limit = 100 }) {
       const rows = await collectPages({
         limit,
@@ -280,7 +237,7 @@ export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch,
       })).filter((r) => r.name !== '')
     },
 
-    /** Pull request-ы репозитория. */
+    /** List pull requests for repository. */
     async listPulls({ owner, repo, state = 'all', limit = 50 }) {
       return collectPages({
         limit,
@@ -289,13 +246,13 @@ export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch,
       })
     },
 
-    /** Создать Pull Request в репозитории. */
+    /** Create pull request in repository. */
     async createPullRequest({ owner, repo, title, body, head, base = 'main' }) {
       const name = String(title ?? '').trim()
-      if (name === '') throw Object.assign(new Error('пустой заголовок'), { code: 'bad-title' })
+      if (name === '') throw Object.assign(new Error('empty title'), { code: 'bad-title' })
       const h = String(head ?? '').trim()
       const b = String(base ?? 'main').trim()
-      if (!h) throw Object.assign(new Error('ветка head обязательна'), { code: 'bad-head' })
+      if (!h) throw Object.assign(new Error('head branch required'), { code: 'bad-head' })
       return request('POST', repoPath(owner, repo, '/pulls'), {
         title: name,
         body: String(body ?? ''),
@@ -304,13 +261,7 @@ export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch,
       })
     },
 
-    /**
-     * Ветки репозитория: по ним видно, начата ли работа и сделан ли cleanup.
-     *
-     * Ветки перелистываются не ради полноты списка, а ради правды наблюдения:
-     * `branchOfTask` не найдёт ветку задачи на усечённой странице и сочтёт её
-     * отсутствующей — карточка уедет не туда на пустом месте.
-     */
+    /** List repository branches with pagination to avoid false negatives when detecting active branches. */
     async listBranches({ owner, repo, limit = 100 }) {
       const rows = await collectPages({
         limit,
@@ -319,16 +270,7 @@ export function createGiteaClient({ getConfig, resolveToken, fetchImpl = fetch,
       return rows.map((b) => ({ name: b?.name ?? '' })).filter((b) => b.name !== '')
     },
 
-    /**
-     * Репозитории инстанса, все страницы.
-     *
-     * Одной страницы не хватает: Gitea отдаёт их порциями, и запрос без
-     * перелистывания молча теряет хвост. Верхний предел стоит, чтобы очень
-     * большой инстанс не превратил открытие диалога в долгую загрузку.
-     *
-     * Число открытых задач и время правки приходят в том же ответе — считать
-     * их отдельными запросами не нужно.
-     */
+    /** Search repositories across instance with pagination up to maxPages. */
     async searchRepos({ query, limit = 50, maxPages = 10 }) {
       const q = encodeURIComponent(String(query || ''))
       const size = Math.min(Math.max(Number(limit) || 50, 1), 50)

package/lib/github.js

@@ -1,12 +1,8 @@
-// Клиент GitHub REST API v3.
-//
-// Выполняет те же операции, что и GiteaClient: чтение issues, pull requests,
-// веток, репозиториев, создание PR и комментирование.
-// Дополнительно поддерживает условные запросы с ETag (If-None-Match) для защиты
-// от исчерпания часового лимита запросов GitHub (5 000 req/hr).
-//
-// Модуль изолирован от файловой системы и DSH: токен и конфигурация
-// передаются фабрикой createGitHubClient.
+// GitHub REST API v3 client.
+// Equivalent functionality to GiteaClient: reading issues, pull requests,
+// branches, repositories, creating PRs and comments.
+// Supports conditional requests with ETag (If-None-Match) to avoid rate limits.
+// Isolated from filesystem and DSH: token and configuration injected via factory.
 
 const DEFAULT_BASE_URL = 'https://api.github.com'
 
@@ -32,16 +28,16 @@ export function isCredentialName(value) {
 }
 
 /**
- * Создать клиент GitHub API.
+ * Create GitHub API client.
  *
  * @param {object} options
- * @param {() => object} options.getConfig функция получения конфигурации
- * @param {(name: string) => Promise<string>} options.resolveToken получение токена
- * @param {typeof fetch} [options.fetchImpl] реализация fetch
- * @param {number} [options.timeoutMs] таймаут запроса в мс
+ * @param {() => object} options.getConfig config getter
+ * @param {(name: string) => Promise<string>} options.resolveToken token resolver
+ * @param {typeof fetch} [options.fetchImpl] fetch implementation
+ * @param {number} [options.timeoutMs] request timeout in ms
  */
 export function createGitHubClient({ getConfig, resolveToken, fetchImpl = fetch, timeoutMs = 30_000 }) {
-  // Кэш условных запросов ETag: url -> { etag, data }
+  // ETag conditional request cache: url -> { etag, data }
   const etagCache = new Map()
 
   async function request(method, path, body, { useEtag = false } = {}) {
@@ -144,7 +140,7 @@ export function createGitHubClient({ getConfig, resolveToken, fetchImpl = fetch,
   return {
     provider: 'github',
 
-    /** Проверен ли токен доступа. */
+    /** Whether access token is valid. */
     async isConfigured() {
       const key = configuredKey()
       if (configuredCache?.key === key) return configuredCache.value
@@ -156,12 +152,12 @@ export function createGitHubClient({ getConfig, resolveToken, fetchImpl = fetch,
       return value
     },
 
-    /** Очистить кэш ETag (например, при явном ручном обновлении). */
+    /** Clear ETag cache (e.g. on manual refresh). */
     clearCache() {
       etagCache.clear()
     },
 
-    /** Список issues репозитория (без PR). */
+    /** List repository issues (excluding PRs). */
     async listIssues({ owner, repo, state = 'open', limit = 50 }) {
       const rows = await collectPages({
         limit,
@@ -172,28 +168,28 @@ export function createGitHubClient({ getConfig, resolveToken, fetchImpl = fetch,
       return rows.filter((r) => !r.pull_request)
     },
 
-    /** Получить один issue по номеру. */
+    /** Get single issue by number. */
     async getIssue({ owner, repo, index }) {
       const n = safeSegment(index)
       if (n === undefined) throw Object.assign(new Error('invalid issue number'), { code: 'bad-segment' })
       return request('GET', repoPath(owner, repo, `/issues/${n}`))
     },
 
-    /** Оставить комментарий в issue. */
+    /** Post comment on issue. */
     async comment({ owner, repo, index, body }) {
       const n = safeSegment(index)
       if (n === undefined) throw Object.assign(new Error('invalid issue number'), { code: 'bad-segment' })
       return request('POST', repoPath(owner, repo, `/issues/${n}/comments`), { body })
     },
 
-    /** Создать новый issue. */
+    /** Create new issue. */
     async createIssue({ owner, repo, title, body }) {
       const name = String(title ?? '').trim()
       if (name === '') throw Object.assign(new Error('empty issue title'), { code: 'bad-title' })
       return request('POST', repoPath(owner, repo, '/issues'), { title: name, body: String(body ?? '') })
     },
 
-    /** Закрыть issue. */
+    /** Close issue. */
     async closeIssue({ owner, repo, index }) {
       const n = safeSegment(index)
       if (n === undefined) throw Object.assign(new Error('invalid issue number'), { code: 'bad-segment' })
@@ -201,8 +197,8 @@ export function createGitHubClient({ getConfig, resolveToken, fetchImpl = fetch,
     },
 
     /**
-     * Назначить ответственных за issue.
-     * В GitHub REST API PATCH /issues/{n} со свойством assignees заменяет ответственных целиком.
+     * Set assignees for issue.
+     * In GitHub REST API PATCH /issues/{n} with assignees replaces the entire list.
      */
     async setAssignees({ owner, repo, index, logins }) {
       const n = safeSegment(index)
@@ -212,14 +208,14 @@ export function createGitHubClient({ getConfig, resolveToken, fetchImpl = fetch,
       return request('PATCH', repoPath(owner, repo, `/issues/${n}`), { assignees: list })
     },
 
-    /** Логин текущего пользователя токена. */
+    /** Login of current token owner. */
     async me() {
       const row = await request('GET', '/user')
       const login = row?.login
       return typeof login === 'string' ? login : ''
     },
 
-    /** Организации, доступные токену. */
+    /** Organizations available to token. */
     async listOrgs() {
       const rows = await request('GET', '/user/orgs?per_page=50')
       return (Array.isArray(rows) ? rows : [])
@@ -227,7 +223,7 @@ export function createGitHubClient({ getConfig, resolveToken, fetchImpl = fetch,
         .filter((name) => name !== '')
     },
 
-    /** Репозитории организации с числом открытых задач. */
+    /** Organization repositories with open task count. */
     async listOrgRepos({ owner, limit = 100 }) {
       const rows = await collectPages({
         limit,
@@ -241,7 +237,7 @@ export function createGitHubClient({ getConfig, resolveToken, fetchImpl = fetch,
       })).filter((r) => r.name !== '')
     },
 
-    /** Pull requests репозитория. */
+    /** Repository pull requests. */
     async listPulls({ owner, repo, state = 'all', limit = 50 }) {
       return collectPages({
         limit,
@@ -251,7 +247,7 @@ export function createGitHubClient({ getConfig, resolveToken, fetchImpl = fetch,
       })
     },
 
-    /** Создать Pull Request. */
+    /** Create Pull Request. */
     async createPullRequest({ owner, repo, title, body, head, base = 'main' }) {
       const name = String(title ?? '').trim()
       if (name === '') throw Object.assign(new Error('empty PR title'), { code: 'bad-title' })
@@ -266,7 +262,7 @@ export function createGitHubClient({ getConfig, resolveToken, fetchImpl = fetch,
       })
     },
 
-    /** Список веток репозитория. */
+    /** List repository branches. */
     async listBranches({ owner, repo, limit = 100 }) {
       const rows = await collectPages({
         limit,
@@ -275,7 +271,7 @@ export function createGitHubClient({ getConfig, resolveToken, fetchImpl = fetch,
       return rows.map((b) => ({ name: String(b?.name ?? '') })).filter((b) => b.name !== '')
     },
 
-    /** Поиск репозиториев. */
+    /** Search repositories. */
     async searchRepos({ query, limit = 50, maxPages = 5 }) {
       const q = encodeURIComponent(String(query || ''))
       const size = Math.min(Math.max(Number(limit) || 50, 1), 50)