Software Engineering Metrics

Тестирование: набор проверок

Запуск

just test
# or
python3 tests/validate.py

Запускается откуда угодно и требует только Python 3 (никаких сторонних пакетов, никакой сети). Печатает одну строку на проверку и завершается с ненулевым кодом, если какая-либо проверка не прошла, поэтому подходит для CI и как pre-commit-хук.

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

  • Ожидаемое число тем (константа в начале скрипта).
  • Сплошная нумерация внутри каждой части, начиная с N.0.
  • H1 совпадает с десятичным номером в имени файла для каждой темы.
  • Заголовок H1 совпадает с spec/structure.md посимвольно, а не только ведущий десятичный номер.
  • Обязательные разделы присутствуют в каждой содержательной теме (части 1 до 8, темы N.1 и выше), в точности в порядке шаблона.
  • Минимальное число слов для каждой содержательной темы (1500 слов), со списком разрешённых исключений в скрипте для намеренных случаев.
  • Нет длинных тире ни в одном файле Markdown.
  • Средние тире только между цифрами, так что «2.1–2.8» проходит, а остальные нет.
  • Нет запрещённых выражений («not only», «but also», «load-bearing»).
  • Все внутренние ссылки .md разрешаются.
  • Перекрёстные ссылки в прозе указывают на настоящие темы: ссылка на номер темы без соответствующего файла на диске падает, используя тот же шаблон ссылок, что и автоматическая подстановка ссылок на темы на опубликованном сайте.
  • Ссылки на Википедию имеют верную форму (https://en.wikipedia.org/wiki/...).
  • spec/structure.md соответствует файлам на диске в обе стороны.
  • README, главная страница и страницы содержания ссылаются на каждую тему.

Когда проверка не проходит

Упавшая строка называет файл и проблему. Типичные исправления:

  • Найдено длинное тире: перепишите предложение, чтобы убрать «—». Не просто удаляйте его.
  • Отсутствует раздел: добавьте недостающий раздел ## из шаблона темы.
  • Несовпадение структуры: вы добавили или переименовали тему, не обновив spec/structure.md, или наоборот. Выровняйте их.
  • Битая ссылка: исправьте путь или обновите его после переименования.
  • Пропуск в нумерации: перенумеруйте, чтобы часть шла подряд от N.0.

Помимо набора проверок

  • just spell запускает codespell по репозиторию. Конфигурация, включая список игнорируемых ложных срабатываний, находится в разделе [tool.codespell] файла pyproject.toml.
  • just stats печатает отчёт в Markdown (число слов по темам, тонкие темы, ссылки на Википедию, записи источников) из tools/stats.py.

Непрерывная интеграция

  • .github/workflows/test.yml запускается на каждый pull request и на push в ветки, кроме main: набор проверок и codespell. Этот репозиторий не собирает и не развёртывает сайт; рендеринг происходит в отдельном репозитории software-engineering-metrics.github.io.
  • .github/workflows/links.yml еженедельно проверяет внешние ссылки с помощью lychee (шаблоны игнорирования в .lycheeignore) и хранит результат в одном issue «Link checker report». Внешние ссылки намеренно держатся вне пути PR.

Что тесты не покрывают

Набор проверяет структуру и стиль, а не истину. Он не может знать, настоящий ли источник или точна ли проза. Проверяйте цитаты и факты вручную или в ходе исследования. Существование ссылки на Википедию (в отличие от её формы) тоже требует сетевой проверки, которую набор намеренно опускает, чтобы работать офлайн.