stackpin

Prevent Node and package-manager config drift before CI breaks.

Русская документация: перейти к разделу

stackpin checks the contract around a Node project and keeps the same runtime and package-manager intent aligned across package metadata, local version files, container images, and CI setup.

What It Checks

Node runtime sources:

• package.json#engines.node
• package.json#devEngines.runtime
• package.json#volta.node
• .nvmrc
• .node-version
• devDependencies["@types/node"]
• Dockerfile*
• docker-compose*.yml and docker-compose*.yaml
• .github/workflows/*.yml and .github/workflows/*.yaml with actions/setup-node

Package manager sources:

• package.json#devEngines.packageManager
• package.json#packageManager
• package.json#volta.<npm|pnpm|yarn|bun>

With --monorepo, the tool also walks workspace package.json files and checks their engines.node, devEngines, volta, and @types/node entries when present.

Commands

npx stackpin check
npx stackpin fix --source devEngines
npx stackpin doctor --monorepo
npx stackpin check --format json

• check reports drift, conflicts, and missing contract pieces.
• fix rewrites secondary files to match the selected source of truth.
• doctor explains why each issue matters.

Source Selection

Use --source to pin the source of truth explicitly.

Supported selectors:

• devEngines
• package.json#devEngines.runtime
• package.json#devEngines.packageManager
• package.json#engines.node
• package.json#packageManager
• package.json#volta.node
• .nvmrc
• .node-version
• @types/node

If --source is omitted, stackpin infers a root source by priority:

1. package.json#devEngines.runtime
2. .nvmrc
3. .node-version
4. package.json#volta.node
5. package.json#engines.node

For package managers, the priority is:

1. package.json#devEngines.packageManager
2. package.json#packageManager
3. package.json#volta.<manager>

Fix Rules

fix is intentionally conservative.

• It will create or update root engines.node, devEngines, .nvmrc, and .node-version when it can derive a concrete value.
• It updates existing Docker, docker-compose, and GitHub Actions files in place.
• In monorepos it updates workspace engines.node, and workspace devEngines.packageManager when that field already exists.
• It updates @types/node only when the dependency already exists.
• It skips exact-pin targets such as volta.node or package.json#packageManager when the chosen source is too ambiguous, and reports that as skipped instead of guessing.

Output

Text output is designed for local use.

--format json returns machine-readable results for CI. The report includes:

• inferred or explicit source of truth per domain
• every finding with status, selector, actual, and expected
• notes when only one domain was selected explicitly

Документация на русском

Не допускает drift в конфигурации Node.js и package manager до того, как CI начнет падать.

stackpin проверяет контракт вокруг Node.js-проекта и удерживает в синхроне одно и то же намерение по runtime и package manager между метаданными пакета, локальными version-файлами, контейнерными образами и настройкой CI.

Что проверяет

Источники версии Node.js:

• package.json#engines.node
• package.json#devEngines.runtime
• package.json#volta.node
• .nvmrc
• .node-version
• devDependencies["@types/node"]
• Dockerfile*
• docker-compose*.yml и docker-compose*.yaml
• .github/workflows/*.yml и .github/workflows/*.yaml с actions/setup-node

Источники package manager:

• package.json#devEngines.packageManager
• package.json#packageManager
• package.json#volta.<npm|pnpm|yarn|bun>

С флагом --monorepo инструмент также проходит по workspace package.json и проверяет их engines.node, devEngines, volta и @types/node, если эти поля присутствуют.

Команды

npx stackpin check
npx stackpin fix --source devEngines
npx stackpin doctor --monorepo
npx stackpin check --format json

• check показывает drift, конфликты и отсутствующие части контракта.
• fix переписывает вторичные файлы так, чтобы они совпадали с выбранным source of truth.
• doctor объясняет, что именно не так и почему это важно.

Выбор источника

Используй --source, чтобы явно указать source of truth.

Поддерживаемые селекторы:

• devEngines
• package.json#devEngines.runtime
• package.json#devEngines.packageManager
• package.json#engines.node
• package.json#packageManager
• package.json#volta.node
• .nvmrc
• .node-version
• @types/node

Если --source не указан, stackpin выбирает корневой источник по приоритету:

1. package.json#devEngines.runtime
2. .nvmrc
3. .node-version
4. package.json#volta.node
5. package.json#engines.node

Для package manager приоритет такой:

1. package.json#devEngines.packageManager
2. package.json#packageManager
3. package.json#volta.<manager>

Правила fix

fix намеренно сделан консервативным.

• Он создает или обновляет корневые engines.node, devEngines, .nvmrc и .node-version, когда может вывести конкретное значение.
• Он обновляет существующие Docker-, docker-compose- и GitHub Actions-файлы на месте.
• В монорепах он обновляет workspace engines.node, а также workspace devEngines.packageManager, если это поле уже существует.
• Он обновляет @types/node только в том случае, если зависимость уже есть.
• Он пропускает exact-pin цели, такие как volta.node или package.json#packageManager, когда выбранный источник слишком неоднозначен, и помечает это как skipped, а не угадывает.

Вывод

Текстовый вывод предназначен для локального использования.

--format json возвращает машинно-читаемый результат для CI. Отчет включает:

• выбранный явно или выведенный автоматически source of truth для каждого домена
• каждую проблему с status, selector, actual и expected
• заметки в случаях, когда явно был выбран только один домен