@mikitasazan/notify 1.4.5 → 1.6.0

package/dist/cli.js

@@ -348,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/index.d.ts

@@ -2,4 +2,5 @@ export type { EventType, NotifyEvent, Project } from './events.ts';
 export { severity } from './events.ts';
 export { notify, sendReport } from './send.ts';
 export { render } from './render.ts';
+export { trend } from './trend.ts';
 export type { SendResult } from './send.ts';

package/dist/index.js

@@ -1,6 +1,10 @@
 export { severity } from "./events.js";
 export { notify, sendReport } from "./send.js";
-// `render` наружу — чтобы отправитель мог положить на диск РОВНО ту карточку,
-// которая уехала, а не свою вторую версию текста. Сборка копии вручную уже
-// расходилась с отправленным.
+// `render` is exported so a sender can put on disk EXACTLY the card that was
+// sent rather than its own second version of the text. A hand-built copy had
+// already drifted from what went out.
 export { render } from "./render.js";
+// `trend` is exported for the same reason one floor down: the shape of a
+// number is the package's, not each sender's. Two report senders had grown two
+// dialects for one thing.
+export { trend } from "./trend.js";

package/dist/render.js

@@ -345,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` — это имя было в пакете раньше и осталось в вызовах. Рендер читал
@@ -386,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)])
     ]);
 };
@@ -436,22 +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),
-            // Строки БЕЗ группы идут вплотную к шапке, а не отдельным куском под
-            // пустой строкой: это факты про сам отчёт — период, номер, — а не про
-            // то, о чём он. Владелец: «number отдельно и период отдельно, непонятно,
-            // куда их относить». `labelled` сам ставит пустую строку перед первой
-            // группой, поэтому её здесь больше нет.
+            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
@@ -461,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
@@ -478,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,
@@ -544,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/dist/trend.d.ts

@@ -0,0 +1,23 @@
+/**
+ * One number, written the one way every card writes a number.
+ *
+ * Two report senders each grew their own dialect: one printed `485 ▲207` and
+ * `0 =`, the other printed `210 +3` for a real comparison and `+37` for a
+ * plain count of what happened today — a plus sign in front of a number that
+ * was never compared to anything. Inside a single group `Removed: 3` stood
+ * next to `Added: +6`, the same kind of fact in two shapes.
+ *
+ * So the shape is not a sender's business any more. It lives here, one
+ * implementation, and every report calls it:
+ *
+ *   trend(210, 207)        → '210 ▲3'
+ *   trend(202, 207)        → '202 ▼5'
+ *   trend(0, 0)            → '0 ='
+ *   trend(37)              → '37'          nothing to compare to, so no mark
+ *   trend(4.4, 3.6, '%')   → '4.4% ▲0.8'   the mark is in the unit left of it
+ *
+ * The rule the owner asked for, in one line: where there is data to compare
+ * against, the arrow is printed; where there is none, nothing is printed —
+ * never a sign that only looks like a comparison.
+ */
+export declare const trend: (now: number, was?: number, unit?: string) => string;

package/dist/trend.js

@@ -0,0 +1,39 @@
+/**
+ * One number, written the one way every card writes a number.
+ *
+ * Two report senders each grew their own dialect: one printed `485 ▲207` and
+ * `0 =`, the other printed `210 +3` for a real comparison and `+37` for a
+ * plain count of what happened today — a plus sign in front of a number that
+ * was never compared to anything. Inside a single group `Removed: 3` stood
+ * next to `Added: +6`, the same kind of fact in two shapes.
+ *
+ * So the shape is not a sender's business any more. It lives here, one
+ * implementation, and every report calls it:
+ *
+ *   trend(210, 207)        → '210 ▲3'
+ *   trend(202, 207)        → '202 ▼5'
+ *   trend(0, 0)            → '0 ='
+ *   trend(37)              → '37'          nothing to compare to, so no mark
+ *   trend(4.4, 3.6, '%')   → '4.4% ▲0.8'   the mark is in the unit left of it
+ *
+ * The rule the owner asked for, in one line: where there is data to compare
+ * against, the arrow is printed; where there is none, nothing is printed —
+ * never a sign that only looks like a comparison.
+ */
+/** Integers stay integers; anything else keeps one decimal. */
+const fmt = (n) => (Number.isInteger(n) ? String(n) : n.toFixed(1));
+/**
+ * Two values that round to the same first decimal are equal: `4.42%` against
+ * `4.44%` is not movement, it is noise, and `▲0.0` reads as a lie.
+ */
+const same = (a, b) => Math.abs(a - b) < 0.05;
+export const trend = (now, was, unit = '') => {
+    const head = `${fmt(now)}${unit}`;
+    if (was === undefined || !Number.isFinite(was)) {
+        return head;
+    }
+    if (same(now, was)) {
+        return `${head} =`;
+    }
+    return now > was ? `${head} ▲${fmt(now - was)}` : `${head} ▼${fmt(was - now)}`;
+};

package/package.json

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