p-backlog 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +47 -0
  3. package/README.ru.md +47 -0
  4. package/package.json +3 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.3
4
+
5
+ - README: screenshots of the task list, a task card and statistics (English UI in README.md, Russian UI in README.ru.md), generated from fictional demo data with `npm run screenshots`. No code changes.
6
+
7
+ ## 0.2.2 (not published to npm; its changes ship in 0.2.3)
8
+
9
+ - README: npm, CI, Node and license badges; a section on using p-backlog together with code-review-graph (re-check by symbol). No code changes.
10
+
3
11
  ## 0.2.1
4
12
 
5
13
  - npm keywords match the GitHub topics, so the package is easier to find in npm search. No code changes.
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # p-backlog
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/p-backlog)](https://www.npmjs.com/package/p-backlog) [![downloads](https://img.shields.io/npm/dm/p-backlog)](https://www.npmjs.com/package/p-backlog) [![CI](https://github.com/expatriate/p-backlog/actions/workflows/ci.yml/badge.svg)](https://github.com/expatriate/p-backlog/actions/workflows/ci.yml) [![node](https://img.shields.io/node/v/p-backlog)](https://nodejs.org) [![license](https://img.shields.io/npm/l/p-backlog)](LICENSE)
4
+
3
5
  **[Русская версия](README.ru.md)**
4
6
 
5
7
  A task backlog that lives as markdown files: an AI agent creates them while working on code, and a human
@@ -11,6 +13,23 @@ triages them in a local web app.
11
13
  - **Backlog hygiene** — the agent re-checks tasks whose code changed and closes the ones no longer needed;
12
14
  closed tasks are deleted after 7 days.
13
15
 
16
+ ## Screenshots
17
+
18
+ ![Task list across three projects: the sidebar with project checkboxes and task counts, status, priority and type filters, and open tasks with tags, status, priority and creation date](https://raw.githubusercontent.com/expatriate/p-backlog/main/docs/screenshots/en/tasks.png)
19
+
20
+ ![Task card of a bug in progress: status, priority, category and epic fields, the source file:line, a description with a half-done checklist, the task that blocked it and a related task](https://raw.githubusercontent.com/expatriate/p-backlog/main/docs/screenshots/en/task.png)
21
+
22
+ <details>
23
+ <summary>Statistics: overview, effect, code</summary>
24
+
25
+ ![Statistics overview: alerts about stale urgent and low-priority tasks, tasks created and closed today and this week, debt by week and tasks created by day](https://raw.githubusercontent.com/expatriate/p-backlog/main/docs/screenshots/en/stats.png)
26
+
27
+ ![Effect tab: lines deferred to the backlog next to lines in pull requests, week by week, with the share of unrelated edits kept out of pull requests](https://raw.githubusercontent.com/expatriate/p-backlog/main/docs/screenshots/en/effect.png)
28
+
29
+ ![Code tab of one project: open debt in frequently changed folders ranked by commits times task weight, and debt density per 1000 lines](https://raw.githubusercontent.com/expatriate/p-backlog/main/docs/screenshots/en/code.png)
30
+
31
+ </details>
32
+
14
33
  ## Getting started
15
34
 
16
35
  1. **Install** (needs Node.js 22.13 or newer):
@@ -112,6 +131,33 @@ requires typing the project id to confirm.
112
131
  the backlog still has unprocessed files) — the countdown then shows "deletion delayed" instead.
113
132
  Deleted task numbers are never reused.
114
133
 
134
+ ## Works well with code-review-graph
135
+
136
+ [code-review-graph](https://github.com/tirth8205/code-review-graph) builds a local graph of your code (functions,
137
+ classes, their lines) in `.code-review-graph/graph.db` at the repository root. p-backlog doesn't need it, but uses
138
+ it when it's there — read-only:
139
+
140
+ - **Re-check by symbol.** A task's `source` (`file:line`) is matched to the function or class that contains it. The
141
+ Stop hook and `backlog check` then flag the task only when that symbol changed, not when any line of the file
142
+ moved — fewer needless re-checks. Without the graph the check falls back to the task's source lines, then to the
143
+ whole file.
144
+ - **Duplicates by symbol.** Two tasks pointing into the same function are offered as possible duplicates.
145
+ - **Graph state in the web UI.** The sidebar warns when a project has no graph, when it's stale, or when it can't be
146
+ read (built by a different version or for a different path), with the command that fixes it.
147
+ - **Check precision.** The Quality tab in statistics shows how often each check method (by symbol, by source lines,
148
+ by file) was right.
149
+
150
+ Setup, once per repository (Python tool; `pipx install code-review-graph` works too):
151
+
152
+ ```bash
153
+ uv tool install code-review-graph
154
+ code-review-graph build # in the repository root
155
+ code-review-graph install --platform claude-code # optional: its MCP server and instructions for Claude Code
156
+ ```
157
+
158
+ Keep the graph fresh with `code-review-graph watch`, or run `code-review-graph update` after changes. Tested with
159
+ code-review-graph 2.3.
160
+
115
161
  ## Web app
116
162
 
117
163
  ```bash
@@ -209,6 +255,7 @@ npx playwright install chromium # once, before the first e2e run
209
255
  npm run test:e2e # Playwright: live list update
210
256
 
211
257
  npm run test:package # the tarball install path end to end on this OS (slow)
258
+ npm run screenshots # README screenshots on demo data, into docs/screenshots
212
259
  ```
213
260
 
214
261
  To try a build the way a published package would install, without publishing it:
package/README.ru.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # p-backlog
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/p-backlog)](https://www.npmjs.com/package/p-backlog) [![downloads](https://img.shields.io/npm/dm/p-backlog)](https://www.npmjs.com/package/p-backlog) [![CI](https://github.com/expatriate/p-backlog/actions/workflows/ci.yml/badge.svg)](https://github.com/expatriate/p-backlog/actions/workflows/ci.yml) [![node](https://img.shields.io/node/v/p-backlog)](https://nodejs.org) [![license](https://img.shields.io/npm/l/p-backlog)](LICENSE)
4
+
3
5
  **[English version](README.md)**
4
6
 
5
7
  Беклог задач, который живёт markdown-файлами: их создаёт ИИ-агент во время работы над кодом, а человек
@@ -11,6 +13,23 @@
11
13
  - **Порядок в беклоге** — агент перепроверяет задачи, чей код изменился, и закрывает ненужные; закрытые
12
14
  задачи удаляются через 7 дней.
13
15
 
16
+ ## Скриншоты
17
+
18
+ ![Список задач трёх проектов: боковая панель с галочками проектов и числом задач, фильтры по статусу, приоритету и типу, открытые задачи с тегами, статусом, приоритетом и датой создания](https://raw.githubusercontent.com/expatriate/p-backlog/main/docs/screenshots/ru/tasks.png)
19
+
20
+ ![Карточка бага в работе: поля статуса, приоритета, категории и эпика, источник файл:строка, описание с наполовину выполненным чеклистом, задача-блокер и связанная задача](https://raw.githubusercontent.com/expatriate/p-backlog/main/docs/screenshots/ru/task.png)
21
+
22
+ <details>
23
+ <summary>Статистика: обзор, эффект, код</summary>
24
+
25
+ ![Обзор статистики: тревоги о застоявшихся срочных и низкоприоритетных задачах, задачи за сегодня и за неделю, долг по неделям и созданные задачи по дням](https://raw.githubusercontent.com/expatriate/p-backlog/main/docs/screenshots/ru/stats.png)
26
+
27
+ ![Вкладка «Эффект»: строки, вынесенные в беклог, рядом со строками в пулреквестах по неделям и доля посторонних правок, не попавших в пулреквесты](https://raw.githubusercontent.com/expatriate/p-backlog/main/docs/screenshots/ru/effect.png)
28
+
29
+ ![Вкладка «Код» одного проекта: открытый долг в часто меняемых папках, ранжированный по коммитам и весу задач, и плотность долга на 1000 строк](https://raw.githubusercontent.com/expatriate/p-backlog/main/docs/screenshots/ru/code.png)
30
+
31
+ </details>
32
+
14
33
  ## Как начать
15
34
 
16
35
  1. **Установка** (нужен Node.js 22.13 или новее):
@@ -107,6 +126,33 @@
107
126
  - Любая закрытая задача удаляется через 7 дней вместе с файлом: это делает сервер при старте и раз в час. Задачу завершённого эпика сервер держит, пока эпик не закроется (например, пока в беклоге есть неразобранные файлы), — тогда вместо отсчёта видно «удаление задержано».
108
127
  Номера удалённых задач повторно не выдаются.
109
128
 
129
+ ## В паре с code-review-graph
130
+
131
+ [code-review-graph](https://github.com/tirth8205/code-review-graph) строит локальный граф кода (функции, классы, их
132
+ строки) в `.code-review-graph/graph.db` в корне репозитория. p-backlog без него работает, но если граф есть —
133
+ использует его, только на чтение:
134
+
135
+ - **Перепроверка по символу.** `source` задачи (`файл:строка`) сопоставляется с функцией или классом, в которых
136
+ стоит. Stop-хук и `backlog check` предлагают перепроверить задачу, только когда изменился этот символ, а не
137
+ любая строка файла, — лишних перепроверок меньше. Без графа проверка опирается на строки `source`, затем на весь
138
+ файл.
139
+ - **Дубли по символу.** Две задачи, указывающие в одну функцию, предлагаются как возможные дубли.
140
+ - **Состояние графа в вебе.** Боковая панель предупреждает, если у проекта нет графа, он устарел или не читается
141
+ (собран другой версией или для другого пути), и подсказывает команду, которая это исправит.
142
+ - **Точность проверки.** Вкладка «Качество» в статистике показывает, как часто был прав каждый способ проверки: по
143
+ символу, по строкам `source`, по файлу.
144
+
145
+ Настройка, один раз на репозиторий (инструмент на Python; подойдёт и `pipx install code-review-graph`):
146
+
147
+ ```bash
148
+ uv tool install code-review-graph
149
+ code-review-graph build # в корне репозитория
150
+ code-review-graph install --platform claude-code # по желанию: его MCP-сервер и инструкции для Claude Code
151
+ ```
152
+
153
+ Чтобы граф не устаревал, держите запущенным `code-review-graph watch` или выполняйте `code-review-graph update`
154
+ после изменений. Проверено с code-review-graph 2.3.
155
+
110
156
  ## Веб-приложение
111
157
 
112
158
  ```bash
@@ -204,6 +250,7 @@ npx playwright install chromium # один раз, перед первым з
204
250
  npm run test:e2e # Playwright: живое обновление списка
205
251
 
206
252
  npm run test:package # весь путь установки из tarball на этой ОС (медленный)
253
+ npm run screenshots # скриншоты для README на демо-данных, в docs/screenshots
207
254
  ```
208
255
 
209
256
  Чтобы попробовать сборку так, будто это опубликованный пакет, без публикации:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "p-backlog",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "description": "Personal developer backlog for Claude Code: tasks as Markdown files, CLI, Stop hook and a local web UI",
5
5
  "keywords": [
6
6
  "claude-code",
@@ -50,6 +50,7 @@
50
50
  "start": "npm run build && node dist/server.js",
51
51
  "dev": "concurrently -k -n server,web \"tsx watch src/server/main.ts\" \"vite\"",
52
52
  "test:e2e": "playwright test",
53
+ "screenshots": "npm run build && tsx scripts/screenshots/make.ts",
53
54
  "test:package": "vitest run --config vitest.package.config.ts",
54
55
  "prepare": "npm run build",
55
56
  "test:coverage": "vitest run --coverage",
@@ -88,6 +89,7 @@
88
89
  "react-router": "^8.4.0",
89
90
  "recharts": "^3.10.1",
90
91
  "remark-gfm": "^4.0.1",
92
+ "sharp": "^0.35.4",
91
93
  "tsx": "^4.23.15",
92
94
  "typescript": "~6.0.3",
93
95
  "typescript-eslint": "^8.70.0",