spectrum-cli 3.1.1 → 3.2.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 🚀 [3.2.0] - 2026-10-01
+
+### 🆕 Added
+
+- Добавлена команда `spectrum changelog write`: выравнивает заголовки релизов и хотфиксов и форматирует `CHANGELOG.md` через Prettier.
+- Добавлена команда `spectrum upgrade` для глобального обновления CLI через npm.
+- Перед выполнением команд CLI проверяет наличие новой версии в npm с таймаутом 200 мс и выводит версии и команду обновления; ошибка проверки не прерывает команду.
+
+### 🪲 Fixed
+
+- `spectrum hotfix start` собирает все текущие фрагменты из `.changelog/` независимо от истории Git.
+
 ## 🚀 [3.1.1] - 2026-09-24
 
 ### 🪲 Fixed

package/README.md

@@ -14,6 +14,12 @@ npm install -g spectrum-cli
 spectrum --help
 ```
 
+Перед выполнением каждой команды CLI проверяет опубликованную версию `spectrum-cli`
+в npm Registry. Если доступна новая версия, показывает текущую и новую версии и
+команду `spectrum upgrade`. Она запускает `npm install -g spectrum-cli`.
+Проверка ограничена 200 мс; недоступность Registry не влияет на выполнение
+команды и не выводит ошибку.
+
 ### 🔧 Из исходников
 
 ```bash
@@ -57,6 +63,7 @@ spectrum chart verify ~/repo  # Сравнить ingress paths AS IS vs TO BE д
 # 📝 Управление changelog
 spectrum changelog append "Сообщение"  # Создать fragment в .changelog/
 spectrum changelog check               # Проверить CHANGELOG.md и все fragments
+spectrum changelog write               # Выравнять заголовки CHANGELOG.md и запустить Prettier
 
 # 🔑 GitLab токены
 spectrum token rotate  # Пролить GITLAB_PRIVATE_TOKEN в CI variables
@@ -197,6 +204,12 @@ spectrum-cli/
 
 1. **`spectrum hotfix start`** обновляет сведения об origin и выбирает опубликованный
    stable-тег, достижимый из production. Цель — этот stable плюс один patch.
+   Как и `release start`, команда читает все файлы текущей `.changelog/` независимо
+   от того, когда они попали в Git. Проверяет их общими правилами changelog и
+   допускает только patch-типы; файлы `added` и `breaking` требуют обычного релиза.
+   Формат CHANGELOG.md проверяется только в текущей ветке. История может отличаться
+   от stable-тега: её исправления не блокируют хотфикс. Снимок production используется
+   для сохранения записей уже подготовленного хотфикса, без строгой проверки старых заголовков.
    Команда формирует верхний раздел `## 🩹 [X.Y.Z] - YYYY-MM-DD` и удаляет только
    собранные fragments. Она не делает commit, staging, push, merge или tag,
    не меняет файлы версий и сохраняет посторонние локальные изменения.
@@ -206,7 +219,7 @@ spectrum-cli/
    читаются без переписывания опубликованной истории. Без новых fragments подготовленный раздел
    остаётся без изменений. Например, от `v6.35.0` первый и повторные запуски
    готовят `6.35.1`; только после публикации `hotfix/6.35.1` следующий хотфикс получит
-   `6.35.2`. Унаследованные от production fragments не собираются и не меняются.
+   `6.35.2`.
 3. Проверьте diff, закоммитьте и отправьте исправление по правилам проекта.
    **В MR из hotfix в production уже должны быть верхний patch-раздел и удаления
    использованных fragments.** Merge выполняется отдельно после ревью. Если
@@ -215,7 +228,7 @@ spectrum-cli/
 4. После доставки подготовленного исправления в production через MR или
    разрешённый проектом push и проверки RC выполните **`spectrum hotfix deploy`** на чистом
    `main/master`, точно совпадающем с origin. Команда проверяет следующий patch,
-   неизменность опубликованной истории и отсутствие несобранных hotfix fragments,
+   отсутствие несобранных hotfix fragments,
    создаёт `hotfix/X.Y.Z` на проверенном SHA и отправляет **только этот тег**.
    Повтор после ошибки push допускает существующий локальный тег лишь на том же
    SHA; опубликованный тег не перемещается. Ветки не сливаются.
@@ -367,9 +380,18 @@ Fragment должен содержать только непустые Markdown-
 > Совет: Приведите файл к нужному формату командой:
 >
 > ```bash
-> npx --yes prettier --write CHANGELOG.md
+> spectrum changelog write
 > ```
 
+### `spectrum changelog write`
+
+Команда приводит все релизные заголовки `CHANGELOG.md` к виду `## 🚀 [X.Y.Z]`,
+`## 🩹 [X.Y.Z]` или `## [X.Y.Z]` с необязательной датой, затем запускает Prettier.
+Старые даты через точки и текст записей сохраняются. Неверный заголовок, включая
+`Unreleased`, останавливает команду без удаления записей. При ошибке Prettier
+исходный `CHANGELOG.md` восстанавливается. Файлы `.changelog/` команда не меняет;
+commit и push не выполняет.
+
 ## 🎯 Философия
 
 - **Простота** - минимум команд, максимум функциональности

package/index.js

@@ -8,9 +8,15 @@ const hotfix = require("./src/hotfix");
 const changelog = require("./src/changelog");
 const chart = require("./src/chart");
 const token = require("./src/token");
+const { checkForUpdates, upgrade } = require("./src/update-check");
 const { version: pkgVersion } = require("./package.json");
 
 async function runAction(action, ...args) {
+  try {
+    await checkForUpdates();
+  } catch {
+    // A failed update check must not affect the command.
+  }
   try {
     const result = await action(...args);
     if (!result) {
@@ -27,6 +33,11 @@ program
   .description("🚀 Spectrum CLI для процесса разработки")
   .version(pkgVersion, "-v, --version");
 
+program
+  .command("upgrade")
+  .description("Обновить Spectrum CLI через npm install -g spectrum-cli")
+  .action(() => runAction(upgrade));
+
 // Команды релиза
 const releaseCmd = program
   .command("release")
@@ -74,6 +85,11 @@ changelogCmd
   .description("Проверить CHANGELOG.md и changelog fragments")
   .action(() => runAction(changelog.changelogCheck));
 
+changelogCmd
+  .command("write")
+  .description("Привести заголовки CHANGELOG.md к формату релиза и запустить Prettier")
+  .action(() => runAction(changelog.changelogWrite));
+
 // Команды chart
 const chartCmd = program
   .command("chart")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectrum-cli",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "🚀 Modern CLI for development workflow automation - release management, versioning, and changelog generation",
   "main": "index.js",
   "bin": {

package/src/changelog.js

@@ -2,11 +2,12 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
-const { logSuccess, logError, execSilent, getCurrentBranch, colors } = require('./utils');
+const { logSuccess, logError, execSilent, execCommand, getCurrentBranch, colors } = require('./utils');
 const { runCommand } = require('./command-executor');
 const {
     requireGitRepo,
     requireFileExists,
+    requirePrettierAvailable,
     requireChangelogFormatted,
     requireChangelogFragments
 } = require('./preflight');
@@ -260,6 +261,65 @@ function changelogCheck() {
     });
 }
 
+function normalizeChangelogHeadings(text) {
+    const version = '(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)';
+    const date = '(\\d{4}-\\d{2}-\\d{2}|\\d{4}\\.\\d{2}\\.\\d{2}|\\d{2}\\.\\d{2}\\.\\d{4})';
+    const releaseHeading = new RegExp(`^##[ \\t]*(?:(🚀|🩹)[ \\t]*)?\\[${version}\\](?:[ \\t]+-[ \\t]+${date})?[ \\t]*\\r?$`);
+    return text.replace(/^##(?!#)[^\n]*$/gm, (heading) => {
+        const match = releaseHeading.exec(heading);
+        if (!match) throw new Error(`Некорректный заголовок ${CHANGELOG_FILE}: ${heading.trimEnd()}`);
+        const marker = match[1] ? `${match[1]} ` : '';
+        const releaseVersion = `${match[2]}.${match[3]}.${match[4]}`;
+        const releaseDate = match[5] ? ` - ${match[5]}` : '';
+        return `## ${marker}[${releaseVersion}]${releaseDate}${heading.endsWith('\r') ? '\r' : ''}`;
+    });
+}
+
+function writeCurrentChangelog(context) {
+    let original;
+    let mayHaveChanged = false;
+    try {
+        original = fs.readFileSync(CHANGELOG_FILE, 'utf8');
+        const normalized = normalizeChangelogHeadings(original);
+        if (normalized !== original) {
+            mayHaveChanged = true;
+            fs.writeFileSync(CHANGELOG_FILE, normalized);
+        }
+        mayHaveChanged = true;
+        if (!execCommand(`${context.prettierRunner} --write ${CHANGELOG_FILE}`) ||
+            !execCommand(`${context.prettierRunner} --check ${CHANGELOG_FILE}`)) {
+            throw new Error('Prettier не смог отформатировать CHANGELOG.md.');
+        }
+        const formatted = fs.readFileSync(CHANGELOG_FILE, 'utf8');
+        if (normalizeChangelogHeadings(formatted) !== formatted) {
+            throw new Error('После Prettier заголовки CHANGELOG.md не соответствуют формату релизов.');
+        }
+        return true;
+    } catch (error) {
+        if (mayHaveChanged && original !== undefined) {
+            try {
+                fs.writeFileSync(CHANGELOG_FILE, original);
+            } catch (restoreError) {
+                logError('❌', 'Не удалось восстановить %s: %s', CHANGELOG_FILE, restoreError.message);
+            }
+        }
+        logError('❌', 'Не удалось отформатировать %s: %s', CHANGELOG_FILE, error.message);
+        return false;
+    }
+}
+
+function changelogWrite() {
+    return runCommand({
+        name: 'changelog write',
+        checks: [
+            { name: 'git-repo', run: requireGitRepo },
+            { name: 'changelog-exists', run: () => requireFileExists(CHANGELOG_FILE) },
+            { name: 'prettier-available', run: requirePrettierAvailable }
+        ],
+        steps: [{ name: 'write-changelog', run: writeCurrentChangelog }]
+    });
+}
+
 function stripLegacyUnreleasedBlock(changelog) {
     const unreleasedMatch = /^## \[Unreleased\]\s*$/m.exec(changelog);
     if (!unreleasedMatch) return changelog;
@@ -339,6 +399,8 @@ function changelogRemoveFragments(context) {
 module.exports = {
     changelogAppend,
     changelogCheck,
+    changelogWrite,
+    normalizeChangelogHeadings,
     extractTaskFromBranch,
     getGitUser,
     formatMessage,

package/src/hotfix-changelog.js

@@ -2,20 +2,23 @@ const { FRAGMENT_TYPES, SECTION_TO_TYPE } = require('./changelog-config');
 const { renderReleaseBlock } = require('./changelog');
 
 // Parse release boundaries without rewriting any published text.
-function parseChangelog(text) {
+function parseChangelog(text, { validate = true } = {}) {
     const headings = [...text.matchAll(/^## .+$/gm)];
     const releases = headings.map((heading, index) => {
         const match = heading[0].match(/^##[ \t]+(?:(🚀|🩹)[ \t]*)?\[(\d+\.\d+\.\d+)\](?:[ \t]+-[ \t]+(\d{4}-\d{2}-\d{2}|\d{4}\.\d{2}\.\d{2}|\d{2}\.\d{2}\.\d{4}))?[ \t]*\r?$/);
         if (!match) {
+            // Production snapshots supply pending notes, not files to validate. Skip
+            // historical non-release sections (including their bodies).
+            if (!validate) return null;
             throw new Error(`Некорректный заголовок CHANGELOG.md: ${heading[0]}. Ожидается ## [X.Y.Z], дата необязательна.`);
         }
-        // Historical duplicates are preserved; callers validate the pending version and immutable history.
+        // Historical duplicates are preserved; callers validate the pending version.
         return {
             version: match[2], date: match[3] || null, marker: match[1] || '',
             text: text.slice(heading.index, headings[index + 1]?.index ?? text.length),
             body: text.slice(heading.index + heading[0].length, headings[index + 1]?.index ?? text.length),
         };
-    });
+    }).filter(Boolean);
     return { intro: text.slice(0, headings[0]?.index ?? text.length), releases };
 }
 
@@ -47,26 +50,18 @@ function normalizeLineEndings(text) {
     return text.replace(/\r\n/g, '\n');
 }
 
-function history(document) {
-    return document.releases.map((release) => normalizeLineEndings(release.text).trim()).join('\n\n');
-}
-
-function pendingDocument(text, stableText, target) {
-    const document = parseChangelog(text);
-    const stable = parseChangelog(stableText);
+function pendingDocument(text, target, { validate = true } = {}) {
+    const document = parseChangelog(text, { validate });
     const pending = document.releases[0]?.version === target ? document.releases.shift() : null;
     if (document.releases.some((release) => release.version === target)) {
         throw new Error('Новый patch-раздел должен быть единственным и находиться в начале CHANGELOG.md.');
     }
-    if (history(document) !== history(stable) || normalizeLineEndings(document.intro).trim() !== normalizeLineEndings(stable.intro).trim()) {
-        throw new Error('История CHANGELOG.md отличается от stable: допустим только верхний раздел следующего patch.');
-    }
     return { document, pending, entries: pending ? releaseEntries(pending, true) : [] };
 }
 
-function prepareChangelog({ text, stableText, productionText, target, fragments, date }) {
-    const current = pendingDocument(text, stableText, target);
-    const production = pendingDocument(productionText, stableText, target);
+function prepareChangelog({ text, productionText, target, fragments, date }) {
+    const current = pendingDocument(text, target);
+    const production = pendingDocument(productionText, target, { validate: false });
     const entryKey = (entry) => `${entry.type}:${entry.entries[0]}`;
     const currentKeys = new Set(current.entries.map(entryKey));
     if (production.entries.some((entry) => !currentKeys.has(entryKey(entry)))) {

package/src/hotfix.js

@@ -5,8 +5,8 @@ const preflight = require('./preflight');
 const { execCommand, logSuccess, logError } = require('./utils');
 const { upVersion, compareVersions } = require('./version');
 const { STABLE_TAG_PATTERNS, parseStableTag, stableTagNames } = require('./stable-tags');
-const { CHANGELOG_FILE, CHANGELOG_DIR, FRAGMENT_TYPES, getFragmentType } = require('./changelog-config');
-const { parseChangelog, pendingDocument, prepareChangelog, normalizeLineEndings } = require('./hotfix-changelog');
+const { CHANGELOG_FILE } = require('./changelog-config');
+const { parseChangelog, pendingDocument, prepareChangelog } = require('./hotfix-changelog');
 
 function git(...args) {
     try {
@@ -92,10 +92,9 @@ function context(mode) {
             throw new Error(`Конфликт stable-тегов версии ${stable}: разные commits.`);
         }
     }
-    const stableText = readAt(`refs/tags/${stableTag}`);
     const productionText = readAt(mainSha);
     const target = upVersion(stable, 'patch');
-    return { mainBranch, mainSha, head, remoteTags, stable, stableTag, stableText, productionText, target };
+    return { mainBranch, mainSha, head, remoteTags, stable, stableTag, productionText, target };
 }
 
 function assertTagAvailable(ctx, allowMatchingLocal = false) {
@@ -115,28 +114,14 @@ function assertOriginUnchanged(ctx) {
     }
 }
 
-function newFragments(baseRef) {
-    const inherited = git('ls-tree', '-r', '-z', '--name-only', baseRef, '--', `${CHANGELOG_DIR}/`)
-        .split('\0').filter(Boolean);
-    for (const file of inherited) {
-        if (!fs.existsSync(file) || normalizeLineEndings(fs.readFileSync(file, 'utf8')) !== normalizeLineEndings(readAt(baseRef, file))) {
-            throw new Error(`Нельзя изменять унаследованный fragment ${file} в хотфиксе.`);
-        }
-    }
-    if (!fs.existsSync(CHANGELOG_DIR)) return [];
-    return fs.readdirSync(CHANGELOG_DIR).sort().filter((name) => !name.startsWith('.'))
-        .map((name) => `${CHANGELOG_DIR}/${name}`).filter((file) => !inherited.includes(file))
-        .map((filePath) => {
-            const type = getFragmentType(filePath);
-            if (!type || !fs.lstatSync(filePath).isFile()) throw new Error(`Некорректный fragment ${filePath}.`);
-            const content = fs.readFileSync(filePath, 'utf8');
-            const entries = content.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
-            if (!entries.length || entries.some((line) => !line.startsWith('- ') || line.length > 120)) {
-                throw new Error(`Пустой или неверно оформленный fragment ${filePath}: записи «- …», до 120 символов.`);
-            }
-            if (FRAGMENT_TYPES[type].bump !== 'patch') throw new Error(`Хотфикс не допускает minor/major: ${filePath}.`);
-            return { filePath, content, type, ...FRAGMENT_TYPES[type], entries };
-        });
+function currentFragments() {
+    if (!preflight.findChangelogFragmentFiles().length) return [];
+    const result = preflight.requireChangelogFragments();
+    if (!result.ok) throw new Error(result.reason);
+    return result.data.changelogFragments.map((fragment) => {
+        if (fragment.bump !== 'patch') throw new Error(`Хотфикс не допускает minor/major: ${fragment.filePath}.`);
+        return { ...fragment, content: fs.readFileSync(fragment.filePath, 'utf8') };
+    });
 }
 
 function formatChangelog() {
@@ -160,7 +145,7 @@ function hotfixStart() {
     return run(() => {
         const ctx = context('start');
         assertTagAvailable(ctx);
-        const fragments = newFragments(ctx.mainSha);
+        const fragments = currentFragments();
         const original = fs.readFileSync(CHANGELOG_FILE, 'utf8');
         const updated = prepareChangelog({ text: original, ...ctx, fragments });
         assertOriginUnchanged(ctx);
@@ -168,7 +153,7 @@ function hotfixStart() {
             try {
                 fs.writeFileSync(CHANGELOG_FILE, updated);
                 formatChangelog();
-                // Formatting must not rewrite published history or lose merged notes.
+                // Validate the formatted current file and keep all merged hotfix notes.
                 prepareChangelog({ text: fs.readFileSync(CHANGELOG_FILE, 'utf8'), ...ctx, fragments: [] });
                 for (const fragment of fragments) fs.unlinkSync(fragment.filePath);
             } catch (error) {
@@ -184,9 +169,9 @@ function hotfixStart() {
 function hotfixDeploy() {
     return run(() => {
         const ctx = context('deploy');
-        const prepared = pendingDocument(ctx.productionText, ctx.stableText, ctx.target);
+        const prepared = pendingDocument(ctx.productionText, ctx.target);
         if (!prepared.pending) throw new Error(`В CHANGELOG.md нужен верхний подготовленный раздел ${ctx.target}.`);
-        if (newFragments(`refs/tags/${ctx.stableTag}`).length) throw new Error('В production остались несобранные hotfix fragments.');
+        if (currentFragments().length) throw new Error('В production остались несобранные hotfix fragments.');
         assertTagAvailable(ctx, true);
         assertOriginUnchanged(ctx);
         const tag = `hotfix/${ctx.target}`;

package/src/update-check.js

@@ -0,0 +1,45 @@
+const childProcess = require('child_process');
+const { name, version: currentVersion } = require('../package.json');
+const { compareVersions } = require('./version');
+
+const UPDATE_CHECK_TIMEOUT_MS = 200;
+
+async function checkForUpdates() {
+    const controller = new AbortController();
+    let timer;
+    try {
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                resolve(null);
+            }, UPDATE_CHECK_TIMEOUT_MS);
+        });
+        const request = (async () => {
+            const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(name)}/latest`, {
+                signal: controller.signal,
+                headers: { accept: 'application/json' }
+            });
+            if (!response.ok) return null;
+            return (await response.json()).version;
+        })();
+        const latestVersion = await Promise.race([request, timeout]);
+        if (compareVersions(latestVersion, currentVersion) > 0) {
+            console.log(`⚠️ Доступна новая версия Spectrum CLI: сейчас ${currentVersion}, доступна ${latestVersion}.\nОбновить: spectrum upgrade`);
+        }
+    } catch {
+        // Network and registry errors must never block a command.
+    } finally {
+        clearTimeout(timer);
+    }
+}
+
+function upgrade() {
+    const result = childProcess.spawnSync('npm', ['install', '-g', name], {
+        stdio: 'inherit',
+        shell: process.platform === 'win32'
+    });
+    if (result.error) throw result.error;
+    return result.status === 0;
+}
+
+module.exports = { checkForUpdates, upgrade, UPDATE_CHECK_TIMEOUT_MS };