@mikitasazan/notify 1.4.4 → 1.5.0

package/dist/cli-flags.js

@@ -12,7 +12,8 @@ export const KNOWN_FLAGS = new Set([
     'action', 'actor', 'assignee', 'author', 'body', 'branch', 'commit',
     'id', 'opened', 'reason', 'workdir',
     'command', 'command-note', 'commit-body', 'commit-title', 'commit-url', 'detail',
-    'expected', 'filename', 'item', 'job', 'key', 'last-seen', 'line', 'logs', 'note',
+    'expected', 'filename', 'item',
+    'item-group', 'job', 'key', 'last-seen', 'line', 'logs', 'note',
     'number', 'path', 'period', 'project', 'reviewer', 'stat', 'status',
     'target', 'title', 'url', 'via', 'workflow-name', 'workflow-url',
     // Флаги без значения. Живут здесь же, чтобы разбор и список не разошлись.

package/dist/cli.js

@@ -101,11 +101,22 @@ const num = (key) => {
     }
     return n;
 };
-// --item "текст" или --item "текст|https://ссылка"
-const items = () => (flags.get('item') ?? []).map((raw) => {
-    const idx = raw.lastIndexOf('|');
-    return idx === -1 ? { text: raw } : { text: raw.slice(0, idx), url: raw.slice(idx + 1) };
-});
+/**
+ * `--item "текст"` или `--item "текст|https://ссылка"`.
+ *
+ * Имя группы у позиции нельзя передать так же, как у `--stat`: черта здесь
+ * уже занята ссылкой. Поэтому `--item-group "Red checks"` — одно имя на все
+ * позиции этого вызова. Списки у отправителей однородные (красные проверки,
+ * выключенные процессы), а разнородный список — это `--json`.
+ */
+const items = () => {
+    const name = flags.get('item-group')?.[0];
+    return (flags.get('item') ?? []).map((raw) => {
+        const idx = raw.lastIndexOf('|');
+        const base = idx === -1 ? { text: raw } : { text: raw.slice(0, idx), url: raw.slice(idx + 1) };
+        return name ? { ...base, group: name } : base;
+    });
+};
 /**
  * `--stat "label=value"`, и с 25.08.2026 — `--stat "Group | label=value"`:
  * имя группы, вертикальная черта, ярлык. Черта выбрана потому, что её нет ни
@@ -337,7 +348,7 @@ else {
                 type: 'report',
                 project: project(),
                 title: one('title') ?? '(no title)',
-                period: one('note'),
+                // A file card has no period; the caption is its title.
                 lines: []
             };
             break;

package/dist/render.js

@@ -164,7 +164,11 @@ const fieldCode = (label, value) => value ? `<b>${esc(cap(label))}:</b> <code>${
  */
 const fieldRun = (value, why) => {
     const explain = field('To do', why);
-    return value && explain !== null ? [explain, `▶ <code>${esc(value)}</code>`] : [];
+    // Без значка. `▶` был единственным символом такого рода на все двадцать
+    // видов карточек, и владелец справедливо спросил, что он значит: ничего,
+    // чего не сказала бы строка `To do:` над ним и моноширинный шрифт под ним —
+    // Telegram делает такую строку копируемой по нажатию сам.
+    return value && explain !== null ? [explain, `<code>${esc(value)}</code>`] : [];
 };
 /** Заголовок группы: курсив + подчёркивание, без жирности, без двоеточия. */
 const group = (name) => `<i><u>${esc(cap(name))}</u></i>`;
@@ -341,14 +345,21 @@ const twoBlocks = (run, change) => {
 // report and asked what "open" was — the answer is the report itself, which was
 // sitting three lines above as dead text. So line 2 takes an optional URL and
 // the action text becomes the link: `Report: <a>Analytics for 12.08</a>`.
-const typeLine = (icon, type, action, url) => {
-    // `field` возвращает null на пустом значении, а интерполяция null в шаблон
-    // печатает слово «null». Так вторая строка карточки становилась `ℹ️ null` —
-    // достижимо через `--json` и прямой вызов на JS, где типов нет.
+// `aside` is the one qualifier an identifier needs to be readable on its own —
+// which day a report covers, which day its arrows are measured against. It
+// rides in brackets ON the type line instead of taking a row of its own,
+// because a row of its own reads as another fact about the subject rather than
+// as part of the name.
+const typeLine = (icon, type, action, url, aside) => {
+    // `field` returns null on an empty value, and interpolating null into a
+    // template prints the word "null". That is how line 2 of a card became
+    // `ℹ️ null` — reachable through `--json` and through a direct call from JS,
+    // where there are no types.
     // `action || 'open'` in the linked case: an empty title must not swallow the
     // link, which would be the one thing the card cannot afford to lose.
     const line = url ? fieldLink(type, url, action || 'open') : field(type, action);
-    return line === null ? `${icon} <b>${esc(cap(type))}</b>` : `${icon} ${line}`;
+    const tail = aside ? ` (${esc(aside)})` : '';
+    return line === null ? `${icon} <b>${esc(cap(type))}</b>${tail}` : `${icon} ${line}${tail}`;
 };
 // `workflowUrl ?? url`: половина отправителей шлёт ссылку на прогон под именем
 // `--url` — это имя было в пакете раньше и осталось в вызовах. Рендер читал
@@ -382,8 +393,10 @@ const renderDeploy = (e) => {
     const icon = iconFor(e);
     const runUrl = e.workflowUrl ?? e.url;
     return join([
-        typeLine(icon, 'Deploy', e.status),
-        fieldLink('Via', runUrl, mechanism(e.workflowName, e.via, runUrl)),
+        // Имя того, чем выкатили, — на строке типа. Исход говорят значок и третий
+        // тег; повторять его словом нечего, и это тот же закон, что у задачи и у
+        // отчёта. Строки `Via` больше нет: она несла это имя этажом ниже.
+        typeLine(icon, 'Deploy', mechanism(e.workflowName, e.via, runUrl) ?? e.status, runUrl),
         ...twoBlocks([field('Target', e.target), field('Reason', e.note)], [fieldLink('Commit', e.commitUrl, e.commit), titleField(e.commitTitle), bodyQuote(e.commitBody)])
     ]);
 };
@@ -391,18 +404,23 @@ const renderJob = (e) => {
     const icon = iconFor(e);
     const hasItems = (e.items ?? []).length > 0;
     const disabledList = hasItems && e.status === 'disabled';
+    // The NAME goes on the type line, the way `Report:` and `Issue:` carry
+    // theirs. It used to sit a line below under a second label, `Task:`, and
+    // the owner asked what a task is doing on a card headed Job — nothing: they
+    // were two words for one thing, and the outcome that took the first line is
+    // already the icon, and now the third tag too.
+    //
+    // `disabled` and `silent` keep a word of their own. A red mark reads as
+    // "it broke", and neither of those is that: one was switched off on purpose
+    // and the other has not been heard from at all.
+    const state = e.status === 'disabled'
+        ? 'switched off, not broken'
+        : e.status === 'silent'
+            ? 'no word from it at all'
+            : undefined;
     return join([
-        typeLine(icon, 'Job', e.status),
-        '',
-        // The name is NOT the type line: line 2 is `Job: fail` by the format's own
-        // rule, so the name is its own field. Called `Task:` and not `Job:` because
-        // repeating the label of the line right above it reads as a mistake.
-        // Until now the name was dropped entirely — every caller passed it and the
-        // owner only ever saw it as the small grey instance tag.
-        // The run link rides on the task's own name. It used to sit at the bottom
-        // as `Workflow: open` — every job caller passes a URL and none passes a
-        // workflow name, so that row was the bare verb the owner objected to.
-        fieldLink('Task', e.workflowUrl ?? e.url, e.job),
+        typeLine(icon, 'Job', e.job, e.workflowUrl ?? e.url),
+        field('State', state),
         field('Reason', e.note),
         field('Expected', e.expected),
         // `Last run` when the task is alive, `Last seen` when it is not: the same
@@ -427,18 +445,15 @@ const renderJob = (e) => {
 const renderReport = (e) => {
     if (e.groups && e.groups.length > 0) {
         const body = e.groups.flatMap((g, i) => (i === 0 ? renderGroup(g) : ['', ...renderGroup(g)]));
-        // `lines` и `groups` вместе, а не «или»: раньше ветка с группами печатала
-        // ТОЛЬКО группы, и цифры отчёта молча исчезали. Поймано 25.08.2026 при
-        // переводе утреннего отчёта PlayHub на типизированное событие.
+        // `lines` AND `groups` together, not one or the other: the branch with
+        // groups used to print ONLY the groups, and the report's numbers vanished
+        // without a word.
         const numbers = labelled(e.lines);
         return join([
-            typeLine(iconFor(e), 'Report', e.title, e.url),
-            // Период стоит ВПЛОТНУЮ к названию, без пустой строки, по тому же
-            // закону, что `Via` у выкатки и `Check` у проверки: строка, которая
-            // уточняет вторую строку, живёт рядом с ней, а не в блоке фактов.
-            // Владелец: «период пошёл не туда, он же должен быть рядом с датой».
-            field('Period', e.period),
-            '',
+            typeLine(iconFor(e), 'Report', e.title, e.url, e.period),
+            // Rows with no group of their own sit flush against the header instead of
+            // forming a separate slab under a blank line. `labelled` puts the blank
+            // line before the first group itself, so there is none here.
             ...numbers,
             body.length > 0 ? '' : null,
             ...body
@@ -448,10 +463,8 @@ const renderReport = (e) => {
     return join([
         // Both analytics jobs send a link to the day's snapshot in docs/. It used to
         // hang off a trailing `Details: open` row; now it is the report's own name.
-        typeLine(iconFor(e), 'Report', e.title, e.url),
-        // Вплотную к названию — см. соседнюю ветку.
-        field('Period', e.period),
-        '',
+        typeLine(iconFor(e), 'Report', e.title, e.url, e.period),
+        // Flush against the header — see the branch above.
         ...labelled(e.lines),
         items.length > 0 ? '' : null,
         ...items
@@ -465,61 +478,54 @@ const renderCi = (e) => {
     const icon = iconFor(e);
     const runUrl = e.workflowUrl ?? e.url;
     return join([
-        typeLine(icon, 'CI', e.status),
-        fieldLink('Check', runUrl, mechanism(e.workflowName, undefined, runUrl)),
+        typeLine(icon, 'CI', mechanism(e.workflowName, undefined, runUrl) ?? e.status, runUrl),
         ...twoBlocks([field('Actor', e.actor), field('Reason', e.note)], [fieldLink('Commit', e.commitUrl, e.commit), titleField(e.commitTitle), bodyQuote(e.commitBody)])
     ]);
 };
+// A pull request and an issue are identified the way GitHub itself identifies
+// them: `#118 <title>`, one string, and it is the link. It used to take three
+// rows — the action on line 2, `Number:` under it, `Title:` under that — so
+// the thing the card is about could not be read without reading three lines.
+// The action is not repeated in words: the icon carries it, and no two actions
+// of one type share an icon.
+const named = (number, title) => title ? `#${number} ${title}` : `#${number}`;
 const renderPr = (e) => join([
-    typeLine(iconFor(e), 'PR', e.action),
-    '',
-    // Идентификатор первым, заголовок под ним: так вещь читается «#118, вот
-    // такая», а не «вот такая, кстати #118» — и так её пишет сам GitHub.
-    fieldLink('Number', e.url, `#${e.number}`),
-    titleField(e.title),
+    typeLine(iconFor(e), 'PR', named(e.number, e.title), e.url),
     bodyQuote(e.body),
-    // Без пустой строки перед автором: у задачи её нет, и одно и то же поле
-    // не должно стоять по-разному в двух соседних карточках. Пустая строка в
-    // этом формате означает «дальше указатель, куда пойти» — автор не он.
     field('Author', e.author),
     field('Reviewer', e.reviewer)
 ]);
 const renderIssue = (e) => join([
-    typeLine(iconFor(e), 'Issue', e.action),
-    '',
-    fieldLink('Number', e.url, `#${e.number}`),
-    titleField(e.title),
+    typeLine(iconFor(e), 'Issue', named(e.number, e.title), e.url),
     bodyQuote(e.body),
     field('Author', e.author),
     field('Assignee', e.assignee)
 ]);
+// The incident's own title IS line 2, exactly as an issue's is. It used to say
+// the word `open` there — which the 🚨 already says, and no other card repeats
+// its icon in words — with the real title one row below under a `Title:` label.
+//
+// `detail` is a diagnosis of several lines (vault greps three of them plus a
+// log path). It used to go through `field`, which keeps only the first line, so
+// every alarm this package ever sent arrived gutted. It is quoted now, the same
+// shape a commit body takes.
 const renderIncident = (e) => join([
-    typeLine(iconFor(e), 'Incident', 'open'),
-    '',
-    // `detail` is a diagnosis of several lines (vault greps three of them plus a
-    // log path). It used to go through `field`, which keeps only the first line,
-    // so every alarm this package ever sent arrived gutted. Same shape as a
-    // commit now: short label, full text quoted under it.
-    // Ярлык `Title`, а не `Reason`: у аварии заголовок — такой же заголовок,
-    // как у коммита и задачи, и называться в одной карточке он должен так же.
-    // Same rule as the report: the link rides on the incident's own title
-    // rather than on a trailing row whose only text is the word `open`.
-    fieldLink('Title', e.url, e.title),
+    typeLine(iconFor(e), 'Incident', e.title, e.url),
     e.detail && e.detail !== e.title ? note(e.detail) : null,
     e.logs ? '' : null,
     fieldCode('Logs', e.logs)
 ]);
-// Раньше всё это склеивалось в одну строку `Reason:` через тире: «имя — no
-// reports — expected X, last seen Y». Каждая другая карточка кладёт факт на
-// свою строку с ярлыком, и владелец справедливо спросил, зачем тут отдельный
-// формат. Отдельного формата больше нет.
 // A session in trouble. Same law as every other card: identifier first, then
 // the facts as fields, then his own words as a quote — never as a field, which
 // keeps one line and clipped the name of the very session the card is about.
+//
+// A session has no name, so line 2 says what happened to it. The 36-character
+// id is not printed: he cannot type it, cannot search it and cannot act on it.
+// It is still in the card — inside the `rm` command at the bottom, which is the
+// one place it is of any use.
 const renderSession = (e) => join([
     typeLine(iconFor(e), 'Session', e.action),
     '',
-    field('Id', e.id),
     field('Project', e.workdir),
     field('Reason', e.reason),
     e.opened ? '' : null,
@@ -531,9 +537,12 @@ const renderHeartbeatMiss = (e) => {
     const icon = iconFor(e);
     const action = e.recovered ? 'ok' : 'miss';
     return join([
-        typeLine(icon, 'Heartbeat', action),
-        '',
-        field('Task', e.job),
+        // The task's name on the type line, exactly as a job card carries it. The
+        // `Task:` row said the same thing a floor below. No sender in any
+        // repository builds this event any more — the silence watchdog sends an
+        // ordinary job with `--status silent` — but a machine still running the old
+        // copy of that watchdog can, and the card it gets must obey the template.
+        typeLine(icon, 'Heartbeat', e.job, undefined, action),
         field('Reason', e.note),
         field('Expected', e.expected),
         field(e.recovered ? 'Last run' : 'Last seen', e.lastSeen)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikitasazan/notify",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "description": "Единая типизированная отправка Telegram-уведомлений (форум-темы, маршрутизация, ретраи) для всех проектов",
   "type": "module",
   "license": "MIT",