Свой аудитор зависимостей: реестр, загрузки, возраст — и что из этого врёт

/*
 * Аудитор зависимостей сервера: вопросы package-health, заданные машиной про
 * каждую строку раздела dependencies одного пакета монорепозитория.
 *
 * Два источника: registry.npmjs.org (packument — dist-tags, time, maintainers,
 * peerDependencies последней версии) и api.npmjs.org (загрузки за неделю).
 * Установленную версию берём из pnpm-lock.yaml, а не из package.json: там
 * диапазон, а стоит на диске одно.
 *
 *   node audit.mjs                                живые запросы
 *   node audit.mjs --save snapshot.json           живые запросы и снимок в файл
 *   node audit.mjs --snapshot snapshot.json --today ГГГГ-ММ-ДД    по снимку
 *
 * Коды выхода разведены нарочно: 0 — находок нет, 1 — есть, 2 — упал сам
 * аудитор. Без третьего кода обрыв сети посреди проверки читался бы как находка.
 */
import { readFileSync, writeFileSync } from 'node:fs';

process.on('uncaughtException', (err) => {
  console.error(`аудит не доведён до конца: ${err?.stack ?? err}`);
  process.exit(2);
});

// путь пакета в монорепозитории — им же он назван в importers замка
const ИМПОРТЕР = 'apps/api';
// по чьему мажору сверяем peer: каркас задаёт версию всем, кто к нему цепляется
const КАРКАС = '@nestjs/core';
// часть пакетов объявляет peer только на @nestjs/common, а мажор у них с core общий
const КАРКАС_КЛЮЧИ = ['@nestjs/core', '@nestjs/common'];
// во сколько раз за год выросли недельные загрузки у середины реестра
const МЕДИАНА_РОСТА = 2.69;
const ТИШИНА_МЕСЯЦЕВ = 12;
const РОСТ_НИША = 1.2;

const флаги = { snapshot: null, save: null, today: null };
for (let i = 2; i < process.argv.length; i += 1) {
  const имя = process.argv[i].replace(/^--/, '');
  if (!Object.hasOwn(флаги, имя)) throw new Error(`неизвестный аргумент ${process.argv[i]}`);
  флаги[имя] = process.argv[i + 1];
  i += 1;
}

const день = (метка) => new Date(метка).toISOString().slice(0, 10);
const сдвиг = (день_, дней) => new Date(new Date(`${день_}T00:00:00Z`).getTime() + дней * 86400000).toISOString().slice(0, 10);

/*
 * Неделя загрузок кончается позавчера: api.npmjs.org досчитывает сутки не
 * сразу, и «вчера» отдаёт то полную неделю, то неполную. Год назад — ровно
 * 364 дня, чтобы неделя легла на те же дни недели: у недельных загрузок
 * будни и выходные различаются в разы.
 */
const СЕГОДНЯ = флаги.today ?? день(Date.now());
const НЕДЕЛЯ = [сдвиг(СЕГОДНЯ, -8), сдвиг(СЕГОДНЯ, -2)];
const НЕДЕЛЯ_ГОД_НАЗАД = [сдвиг(НЕДЕЛЯ[0], -364), сдвиг(НЕДЕЛЯ[1], -364)];

// -------------------------------------------------------------- проект

/*
 * Замок читается своим разбором по отступам, а не парсером YAML: аудитору
 * нужны четыре уровня одного раздела, и лишний пакет в таком скрипте — сам
 * предмет разговора. Чужой формат за это мстит, поэтому разбор узкий: не
 * увидел importers или пакета — говорит об этом, а не возвращает пустоту.
 */
function изЗамка(текст, импортер) {
  const версии = new Map();
  let вImporters = false;
  let свой = false;
  let вDependencies = false;
  let имя = null;
  for (const строка of текст.split('\n')) {
    if (/^\S/.test(строка)) { вImporters = строка.startsWith('importers:'); свой = false; continue; }
    if (!вImporters || !строка.trim() || строка.trimStart().startsWith('#')) continue;
    const отступ = строка.length - строка.trimStart().length;
    const тело = строка.trim();
    if (отступ === 2) { свой = тело === `${импортер}:`; вDependencies = false; continue; }
    if (!свой) continue;
    if (отступ === 4) { вDependencies = тело === 'dependencies:'; continue; }
    if (!вDependencies) continue;
    if (отступ === 6) { имя = тело.replace(/:$/, '').replace(/^'|'$/g, ''); continue; }
    // version: 11.2.2(reflect-metadata@0.2.2)(rxjs@7.8.2) — в скобках подобранные peer'ы,
    // аудитору нужна голова до первой скобки
    if (отступ === 8 && тело.startsWith('version:') && имя) версии.set(имя, тело.slice('version:'.length).trim().split('(')[0]);
  }
  if (версии.size === 0) throw new Error(`в замке нет пакета ${импортер} с разделом dependencies`);
  return версии;
}

const проект = JSON.parse(readFileSync('project/package.json', 'utf8'));
const замок = изЗамка(readFileSync('project/pnpm-lock.yaml', 'utf8'), ИМПОРТЕР);
const диапазоны = проект.dependencies ?? {};
const свои = Object.keys(диапазоны).filter((имя) => диапазоны[имя].startsWith('workspace:'));
const имена = Object.keys(диапазоны).filter((имя) => !свои.includes(имя)).sort();
const пропало = имена.filter((имя) => !замок.has(имя));
if (пропало.length) throw new Error(`в замке нет версий: ${пропало.join(', ')} — package.json и pnpm-lock.yaml разошлись`);

// -------------------------------------------------------------- источники

const пауза = (мс) => new Promise((готово) => setTimeout(готово, мс));
const ПОВТОРЫ = [5000, 15000, 45000];
const первый = new Set();

async function спросить(адрес) {
  const хост = new URL(адрес).host;
  for (let попытка = 0; ; попытка += 1) {
    const ответ = await fetch(адрес, { headers: { 'user-agent': 'jsp-deps-audit' } });
    // первый запрос к каждому хосту называет себя: иначе «ничего не нашлось» и
    // «нас не пустили» выглядят одинаково, а страница входа Wi-Fi отвечает 200 и не тем
    if (!первый.has(хост)) { первый.add(хост); console.log(`${адрес} → ${ответ.status} ${ответ.headers.get('content-type')?.split(';')[0]}`); }
    if (ответ.ok) return ответ.json();
    // 429 приходит уже на третьем десятке запросов подряд: это не отказ, а просьба подождать
    if (ответ.status !== 429 || попытка >= ПОВТОРЫ.length) throw new Error(`${адрес} ответил ${ответ.status}`);
    console.log(`  ${хост} ответил 429, жду ${ПОВТОРЫ[попытка] / 1000} с`);
    await пауза(ПОВТОРЫ[попытка]);
  }
}

async function живьём(имена_) {
  const снимок = { снято: СЕГОДНЯ, неделя: НЕДЕЛЯ, годНазад: НЕДЕЛЯ_ГОД_НАЗАД, пакеты: {} };
  for (const имя of имена_) {
    // в адресе packument косая черта области экранируется, у загрузок — нет
    const пакет = await спросить(`https://registry.npmjs.org/${имя.replace('/', '%2f')}`);
    const latest = пакет['dist-tags']?.latest;
    const выпуск = пакет.versions?.[latest] ?? {};
    await пауза(1200);
    const неделя = await спросить(`https://api.npmjs.org/downloads/point/${НЕДЕЛЯ.join(':')}/${имя}`);
    await пауза(1200);
    const год = await спросить(`https://api.npmjs.org/downloads/point/${НЕДЕЛЯ_ГОД_НАЗАД.join(':')}/${имя}`);
    снимок.пакеты[имя] = {
      latest,
      // возраст считают по времени выпуска САМОЙ версии latest; time.modified
      // двигает любая публикация, в том числе чужой предварительной ветки
      выпущена: пакет.time?.[latest] ?? null,
      правлен: пакет.time?.modified ?? null,
      deprecated: выпуск.deprecated ?? null,
      сопровождают: (пакет.maintainers ?? []).map((м) => м.name),
      peer: выпуск.peerDependencies ?? null,
      неделя: неделя.downloads,
      неделяГодНазад: год.downloads,
    };
  }
  return снимок;
}

// -------------------------------------------------------------- вопросы

/** Полных календарных месяцев между двумя днями — как в health() части I. */
function месяцевМежду(от, до) {
  const а = new Date(от);
  const б = new Date(до);
  const месяцев = (б.getUTCFullYear() - а.getUTCFullYear()) * 12 + б.getUTCMonth() - а.getUTCMonth();
  return б.getUTCDate() < а.getUTCDate() ? месяцев - 1 : месяцев;
}

const мажор = (версия) => Number(версия.split('.')[0]);
const предварительная = (версия) => версия.includes('-');

/*
 * Какие мажоры пускает строка peer. Разбор нарочно узкий: «^11.0.0 || ^12.0.0»
 * и голая версия. Всё остальное — не молчаливое «не пускает», а null: аудитор,
 * который принял непонятую строку за отказ, врал бы уверенным голосом.
 */
function мажорыPeer(строка) {
  const части = строка.split('||').map((ч) => ч.trim());
  const итог = [];
  for (const часть of части) {
    const совпало = /^\^?(\d+)\.\d+\.\d+$/.exec(часть);
    if (!совпало) return null;
    итог.push(Number(совпало[1]));
  }
  return итог;
}

function здоровье(п, сегодня) {
  if (п.deprecated) return `снят автором: ${п.deprecated}`;
  if (предварительная(п.latest)) return `latest — предварительная версия ${п.latest}`;
  const тишина = месяцевМежду(п.выпущена, сегодня);
  if (тишина > ТИШИНА_МЕСЯЦЕВ) return `без выпуска ${тишина} мес. — законченный или брошенный, решает человек`;
  const рост = п.неделя / п.неделяГодНазад;
  if (рост <= РОСТ_НИША) return `рост ×${рост.toFixed(2)} при медиане ×${МЕДИАНА_РОСТА} — ниша уходит`;
  return null;
}

/** «1 мажор», «2 мажора», «8 мажоров» — иначе отчёт читается как черновик. */
const мажоров = (n) => `${n} ${n % 10 === 1 && n % 100 !== 11 ? 'мажор' : n % 10 >= 2 && n % 10 <= 4 && (n % 100 < 12 || n % 100 > 14) ? 'мажора' : 'мажоров'}`;

/** Пускает ли пакет мажор каркаса: null — peer про каркас ничего не говорит. */
function держит(имя, п, мажорКаркаса) {
  if (КАРКАС_КЛЮЧИ.includes(имя)) return null;
  for (const ключ of КАРКАС_КЛЮЧИ) {
    const peer = п.peer?.[ключ];
    if (!peer) continue;
    const пускает = мажорыPeer(peer);
    if (пускает === null) return `peer ${ключ} «${peer}» не разобран — смотреть глазами`;
    if (!пускает.includes(мажорКаркаса)) return `peer ${ключ} ${пускает.join(', ')} — мажора ${мажорКаркаса} среди них нет`;
  }
  return null;
}

// -------------------------------------------------------------- отчёт

const снимок = флаги.snapshot
  ? JSON.parse(readFileSync(флаги.snapshot, 'utf8'))
  : await живьём(имена);
if (флаги.save) {
  // по пакету на строку: снимок читают глазами рядом с отчётом, а JSON.stringify
  // с отступом растягивает двадцать пакетов на три сотни строк
  const строки = Object.entries(снимок.пакеты).map(([имя, п]) => `  ${JSON.stringify(имя)}: ${JSON.stringify(п)}`);
  const шапка = Object.entries(снимок).filter(([ключ]) => ключ !== 'пакеты').map(([ключ, з]) => ` ${JSON.stringify(ключ)}: ${JSON.stringify(з)}`);
  writeFileSync(флаги.save, `{\n${шапка.join(',\n')},\n "пакеты": {\n${строки.join(',\n')}\n }\n}\n`);
  console.log(`снимок записан: ${флаги.save}`);
}

const нетВСнимке = имена.filter((имя) => !снимок.пакеты[имя]);
if (нетВСнимке.length) throw new Error(`в снимке нет: ${нетВСнимке.join(', ')}`);

const мажорКаркаса = мажор(снимок.пакеты[КАРКАС].latest);
console.log(`\n${ИМПОРТЕР}: зависимостей из реестра ${имена.length}, своих пропущено ${свои.length}, devDependencies (${Object.keys(проект.devDependencies ?? {}).length}) в этот раз не берём`);
console.log(`снимок за ${снимок.снято}, загрузки за ${снимок.неделя.join('..')} против ${снимок.годНазад.join('..')}, медиана роста ×${МЕДИАНА_РОСТА}, сегодня ${СЕГОДНЯ}`);
console.log(`каркас ${КАРКАС}: установлен ${замок.get(КАРКАС)}, latest ${снимок.пакеты[КАРКАС].latest}\n`);

const больные = [];
const держат = [];
const отстали = [];
const одиночки = [];
for (const имя of имена) {
  const п = снимок.пакеты[имя];
  const установлено = замок.get(имя);
  const диагноз = здоровье(п, СЕГОДНЯ);
  const преграда = держит(имя, п, мажорКаркаса);
  const рост = `×${(п.неделя / п.неделяГодНазад).toFixed(1)}`;
  console.log(`${диагноз ? '!' : '·'} ${имя.padEnd(26)}${`${установлено} → ${п.latest}`.padEnd(22)}${рост.padEnd(7)}${диагноз ?? 'жив'}`);
  if (диагноз) больные.push(`${имя}: ${диагноз}`);
  if (преграда) держат.push(`${имя}: ${преграда}`);
  if (п.сопровождают.length === 1) одиночки.push(имя);
  const отстал = мажор(п.latest) - мажор(установлено);
  if (отстал > 0) отстали.push(`${имя}: ${установлено} при latest ${п.latest} — ${мажоров(отстал)} позади`);
}

console.log(`\nжив ли (вопросы 1 и 2) — находок ${больные.length}:`);
for (const строка of больные) console.log(`  ${строка}`);
console.log(`\nдержит мажор ${КАРКАС} — ${держат.length}:`);
for (const строка of держат) console.log(`  ${строка}`);
console.log(`\nотстало от latest на мажор и больше — ${отстали.length}:`);
for (const строка of отстали) console.log(`  ${строка}`);
console.log(`\nв реестре сопровождает один человек — ${одиночки.length} из ${имена.length}:`);
console.log(`  ${одиночки.join(', ')}`);
console.log(`\nвопросы 0, 3, 4 и 5 реестр не знает: на них отвечает человек и пишет ответ на полку`);

process.exit(больные.length + держат.length ? 1 : 0);

apps/api: зависимостей из реестра 21, своих пропущено 2, devDependencies (19) в этот раз не берём
снимок за 2026-09-29, загрузки за 2026-09-21..2026-09-27 против 2025-09-22..2025-09-28, медиана роста ×2.69, сегодня 2026-09-29
каркас @nestjs/core: установлен 11.2.2, latest 12.1.1

· @aws-sdk/client-s3        3.887.0 → 3.1142.0    ×4.4   жив
· @fastify/multipart        9.2.1 → 10.1.2        ×7.2   жив
· @fastify/static           10.1.3 → 10.1.5       ×4.4   жив
· @nestjs/common            11.2.2 → 12.1.1       ×3.3   жив
· @nestjs/config            4.0.4 → 12.0.1        ×3.1   жив
· @nestjs/core              11.2.2 → 12.1.1       ×3.3   жив
· @nestjs/platform-fastify  11.1.29 → 12.1.1      ×4.3   жив
· @nestjs/swagger           11.4.7 → 12.0.2       ×3.2   жив
· @nestjs/throttler         6.5.0 → 6.7.1         ×7.6   жив
· @trpc/server              11.5.1 → 11.19.0      ×4.2   жив
· bcryptjs                  3.0.3 → 3.0.3         ×3.2   жив
· drizzle-orm               0.44.7 → 0.45.3       ×13.5  жив
· fastify                   5.11.0 → 5.12.5       ×5.3   жив
· jsonwebtoken              9.0.3 → 9.0.3         ×2.8   жив
· nestjs-trpc               2.13.0 → 2.13.0       ×4.6   жив
· nodemailer                8.0.11 → 10.0.12      ×3.9   жив
· pg                        8.16.3 → 8.23.0       ×6.1   жив
! reflect-metadata          0.2.2 → 0.2.2         ×2.9   без выпуска 30 мес. — законченный или брошенный, решает человек
! rxjs                      7.8.2 → 7.8.2         ×2.0   без выпуска 19 мес. — законченный или брошенный, решает человек
· superjson                 1.13.3 → 2.2.6        ×3.0   жив
· zod                       4.1.13 → 4.6.5        ×7.8   жив

жив ли (вопросы 1 и 2) — находок 2:
  reflect-metadata: без выпуска 30 мес. — законченный или брошенный, решает человек
  rxjs: без выпуска 19 мес. — законченный или брошенный, решает человек

держит мажор @nestjs/core — 1:
  nestjs-trpc: peer @nestjs/core 9, 10, 11 — мажора 12 среди них нет

отстало от latest на мажор и больше — 8:
  @fastify/multipart: 9.2.1 при latest 10.1.2 — 1 мажор позади
  @nestjs/common: 11.2.2 при latest 12.1.1 — 1 мажор позади
  @nestjs/config: 4.0.4 при latest 12.0.1 — 8 мажоров позади
  @nestjs/core: 11.2.2 при latest 12.1.1 — 1 мажор позади
  @nestjs/platform-fastify: 11.1.29 при latest 12.1.1 — 1 мажор позади
  @nestjs/swagger: 11.4.7 при latest 12.0.2 — 1 мажор позади
  nodemailer: 8.0.11 при latest 10.0.12 — 2 мажора позади
  superjson: 1.13.3 при latest 2.2.6 — 1 мажор позади

в реестре сопровождает один человек — 9 из 21:
  @nestjs/common, @nestjs/core, bcryptjs, jsonwebtoken, nestjs-trpc, nodemailer, pg, reflect-metadata, zod

вопросы 0, 3, 4 и 5 реестр не знает: на них отвечает человек и пишет ответ на полку

/*
 * Один пакет, два адреса, живой ответ: ровно те поля, которые читает аудитор.
 * Каждый запрос называет себя адресом и кодом ответа — проверка обязана
 * доказать, что спрашивала то, что собиралась, а не страницу входа в Wi-Fi.
 */
const ИМЯ = '@nestjs/throttler';
const КАРКАС = '@nestjs/core';
// установленная версия и latest: один и тот же вопрос, заданный двум выпускам
const УСТАНОВЛЕНО = '6.5.0';

async function спросить(адрес) {
  const ответ = await fetch(адрес, { headers: { 'user-agent': 'jsp-deps-audit' } });
  console.log(`${адрес}\n  → ${ответ.status} ${ответ.headers.get('content-type')?.split(';')[0]}`);
  if (!ответ.ok) throw new Error(`${адрес} ответил ${ответ.status}`);
  return ответ.json();
}

// косая черта области в адресе packument экранируется, у загрузок — нет
const пакет = await спросить(`https://registry.npmjs.org/${ИМЯ.replace('/', '%2f')}`);
const загрузки = await спросить(`https://api.npmjs.org/downloads/point/last-week/${ИМЯ}`);

const latest = пакет['dist-tags'].latest;
const день = (метка) => метка.slice(0, 10);
// toLocaleString ставит между разрядами узкий неразрывный пробел — в вывод он
// уезжает невидимкой, поэтому разряды разделены обычным пробелом
const разряды = (число) => String(число).replace(/\B(?=(\d{3})+$)/g, ' ');

console.log(`\n${ИМЯ}`);
console.log(`  latest        ${latest}`);
console.log(`  time[latest]  ${день(пакет.time[latest])}`);
console.log(`  time.modified ${день(пакет.time.modified)}`);
console.log(`  сопровождают  ${пакет.maintainers.map((м) => м.name).join(', ')}`);
console.log(`  загрузок за ${загрузки.start}..${загрузки.end}: ${разряды(загрузки.downloads)}`);
for (const версия of [УСТАНОВЛЕНО, latest]) {
  console.log(`  peer ${КАРКАС} у ${версия}: ${пакет.versions[версия].peerDependencies[КАРКАС]}`);
}

https://registry.npmjs.org/@nestjs%2fthrottler
  → 200 application/json
https://api.npmjs.org/downloads/point/last-week/@nestjs/throttler
  → 200 application/json

@nestjs/throttler
  latest        6.7.1
  time[latest]  2026-09-24
  time.modified 2026-09-24
  сопровождают  nestjscore, kamilmysliwiec
  загрузок за 2026-09-21..2026-09-27: 4 891 139
  peer @nestjs/core у 6.5.0: ^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0
  peer @nestjs/core у 6.7.1: ^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0 || ^12.0.0

# запущено в apps/api учебника: кто на самом деле приводит пакет в node_modules
echo '$ pnpm why reflect-metadata'
pnpm why reflect-metadata
echo
echo '$ pnpm why find-my-way'
pnpm why find-my-way

$ pnpm why reflect-metadata
reflect-metadata@0.2.2
├── @jsp/api@0.0.0 (dependencies)
├─┬ @nestjs/common@11.2.2
│ ├── @jsp/api@0.0.0 (dependencies)
│ ├─┬ @nestjs/config@4.0.4
│ │ └── @jsp/api@0.0.0 (dependencies)
│ ├─┬ @nestjs/core@11.2.2
│ │ ├── @jsp/api@0.0.0 (dependencies)
│ │ ├─┬ @nestjs/platform-fastify@11.1.29
│ │ │ └── @jsp/api@0.0.0 (dependencies)
│ │ ├─┬ @nestjs/swagger@11.4.7
│ │ │ └── @jsp/api@0.0.0 (dependencies)
│ │ ├─┬ @nestjs/testing@11.2.2
│ │ │ └── @jsp/api@0.0.0 (devDependencies)
│ │ ├─┬ @nestjs/throttler@6.5.0
│ │ │ └── @jsp/api@0.0.0 (dependencies)
│ │ └─┬ nestjs-trpc@2.13.0
│ │   └── @jsp/api@0.0.0 (dependencies)
│ ├─┬ @nestjs/mapped-types@2.1.1
│ │ └── @nestjs/swagger@11.4.7 [deduped]
│ ├── @nestjs/platform-fastify@11.1.29 [deduped]
│ ├── @nestjs/swagger@11.4.7 [deduped]
│ ├── @nestjs/testing@11.2.2 [deduped]
│ ├── @nestjs/throttler@6.5.0 [deduped]
│ └── nestjs-trpc@2.13.0 [deduped]
├── @nestjs/core@11.2.2 [deduped]
├── @nestjs/mapped-types@2.1.1 [deduped]
├── @nestjs/swagger@11.4.7 [deduped]
├── @nestjs/throttler@6.5.0 [deduped]
└── nestjs-trpc@2.13.0 [deduped]

Found 1 version of reflect-metadata

$ pnpm why find-my-way
find-my-way@9.7.0
└─┬ @nestjs/platform-fastify@11.1.29
  └── @jsp/api@0.0.0 (dependencies)

find-my-way@9.9.0
└─┬ fastify@5.11.0
  ├── @jsp/api@0.0.0 (dependencies)
  └─┬ @nestjs/platform-fastify@11.1.29
    └── @jsp/api@0.0.0 (dependencies)

Found 2 versions of find-my-way