Перейти к содержанию

Что делать, когда сломалось

Кому это? Тому, у кого прогон только что стал красным — или у кого проверка вообще не запускается. Когда читать? Сейчас, начиная с сообщения, которое вы получили. Если это не поломка, а вопрос — FAQ; чтобы разобраться с инструментом — гайд.

Каждый случай ниже — реальная поломка этого репозитория или одного из двух его потребителей. Написано то, что помогло, а не то, что должно было бы помочь.

release говорит, что в чекауте нет тегов

FAIL  release
  CHANGELOG.md:1  (no tags)
      this checkout has no tags, so whether the released versions are tagged cannot be checked
    fix:  fetch tags — actions/checkout needs fetch-depth: 0

С репозиторием всё в порядке. actions/checkout по умолчанию забирает один коммит и ни одного тега, поэтому проверке нечего сравнивать. Дайте джобе её вход:

- uses: actions/checkout@v5
  with:
    fetch-depth: 0

Это нужно каждой джобе, которая запускает harnessimo check, а не только той, где вы это заметили.

Proof-маркер падает, хотя файл очевидно на месте

Три причины, в порядке частоты:

  1. Путь считается от корня репозитория, а не от документа. Маркер в docs/GUIDE.md, указывающий на src/cli.ts, — верный; на ../src/cli.ts — нет.
  2. Символ переименовали или перенесли. <!-- proof: src/<module>.ts:<aSymbol> --> падает в тот момент, когда <aSymbol> переименовали. Это проверка работает: утверждение пережило то, на что ссылалось.
  3. У команды нет раннера. Для <!-- proof: make <target> --> нужно, чтобы docs.commands объяснял, что такое make — { "make": "Makefile" }. Без этого маркер не разрешается и честно об этом сообщает, а не проходит молча.

clean-exit говорит, что прогресс не записан

.harness/4-state/PROGRESS.md:1  (not updated)
    21 file(s) changed and this was not one of them

Сессия поменяла код и оставила файл, который следующая сессия читает первым, с описанием старого состояния. Либо обновите его, либо — если в этом репозитории «где я остановился» живёт в другом месте, например в хендоффе трека, — поставьте cleanExit.progressFile в null и напишите почему в $comment конфига. Осознанно выключить правило, в письменном виде, — это не то же самое, что его игнорировать.

locked отказывает коммиту, который тронул только CI

Это проверка делает свою работу: .github/workflows/ перечислен в locked.paths, а коммит агента не имеет права менять файлы, которые решают, прошла ли его работа.

Правильный путь — не ослабить правило. Внесите изменение, а затем сдвиньте baseline отдельным коммитом, который фиксирует почему:

# The fourteenth corrects the constraint count that file states about itself.
4a2726ae71df13b215b061744f084f9e08df959a

История файла baseline становится аудит-следом каждого сдвига защищённой поверхности.

Пре-коммит-хук отклоняет то, что check пропускает

Хук и ваш терминал запускают разные сборки. Сгенерированный хук ищет node_modules/.bin/harnessimo, затем src/cli.ts, затем dist/cli.js, затем PATH — так что протухший dist/ перекрывает исходники, из которых собран. Пересоберите или удалите dist/.

Если нужно срочно закоммитить, а хук неправ, — чините хук. --no-verify выключает гейт для всех, кто скопирует команду из вашей истории.

cold-start падает, хотя локально всё работает

Так и задумано. Проверка клонирует репозиторий в пустой каталог и запускает задокументированные команды без всего, что есть на вашей машине: без .env, без глобальных установок, без кешированных node_modules. Падение означает, что новый участник или свежий CI-раннер не сможет начать, — и это было правдой до появления проверки, просто невидимой.

Читайте, что она напечатала: отсутствующий файл — это отсутствующий файл, а падающая команда — это команда, которую обещает ваш README и не может выполнить репозиторий.

queue verify проходит локально и падает в CI

CI запускает check --reverify, то есть заново прогоняет верификацию каждого пункта со статусом passing, а не верит записанному состоянию. Пункт, который однажды позеленел, а потом был поправлен руками, здесь падает. Этот разрыв между «в файле написано passing» и «оно проходит» — вся причина, по которой очередь существует.

Ничего не запускается: «no harnessimo.config.json here»

Инструмент читает конфиг из текущего каталога. Запускайте из корня репозитория — или выполните harnessimo init, если репозиторий ещё не настроен.

doctor пишет «not set» у проверки, которую вы считали включённой

Проверка включается, когда есть её секция конфигурации: нет секции — нет проверки. doctor печатает честный список, и этот список и есть ответ на вопрос «что этот репозиторий реально гарантирует». Добавьте секцию, названную в таблице гайда, и запустите doctor снова.

Всё ещё не работает

Заводите issue с командой, которую запускали, и полным выводом: https://github.com/atamaniuc/Harnessimo/issues. Вывод называет файл, строку и способ починки; если не назвал — это баг в сообщении, и о нём стоит сообщить отдельно.