Как мы плавно перешли с JS на TS благодаря Github Action

Примечание. Этот пост написан в соавторстве с Грегори Улье, создателем Github Action.

Стабильность приложений стала существенной. Хотя автоматические тесты обеспечивают повышенную безопасность, мы приветствуем добавление ввода в наш существующий код.

Поэтому переход с Javascript на Typescript стал обычной задачей для большинства компаний, и Swile не является исключением.

Вот почему мы разработали инструмент, который позволяет нам отслеживать, измерять и анализировать покрытие типов любого проекта, который мы решили перенести в наш стек.

Почему мы разработали этот инструмент?

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

Путь миграции средней/большой кодовой базы

TypeScript можно постепенно внедрять с помощью JSDoc, параметров checkJS и allowJs. Эти параметры позволяют tsc (т. е. компилятору TypeScript) сообщать об ошибках ввода в чистом коде JavaScript.

{
  "compilerOptions": {
    "checkJs": true,
    "allowJs": true
  }
}

Принятие TypeScript без нарушения нашего CI

Включение проверки типов в кодовой базе может привести к возникновению большого количества проблем, и их исправление за один раз не всегда возможно.

В этом контексте мы выбираем отслеживание ошибок и включаем цель улучшения типизации в наш процесс проверки запросов на вытягивание.

Вот соответствующие слайды о путешествии по миграции TypeScript

Как это работает

В Swile в компаниях мы используем Github в качестве платформы контроля версий кода для всех наших активов. Нет необходимости подробно описывать многие функции, которые предлагает Github. Тем не менее, один из самых интересных для нас, разработчиков, называется Github Actions.

Действия Github позволяют автоматизировать почти все, имея доступ к API Github непосредственно в нашем рабочем процессе разработки.

Итак, мы решили создать настраиваемое действие Github. Как описано на схеме ниже, процесс использования довольно прост.

Как видите, единственная роль действия Github «ts-migration-companion», описанного в этой статье, состоит в том, чтобы превратить текстовый вывод команды сборки «tsc» в отчет об ошибке.

Примечание. Мы могли бы интегрировать шаги сборки непосредственно в наше действие. Однако это означает потерю свободы в реализации, и это противоречило бы философии Unix, которую я так люблю: «Делайте одно и делайте это хорошо»

В результате комментарий, размещенный на соответствующем PR, имеет следующий вид.

Как реализовать

Основное преимущество Github Actions заключается в том, что мы можем легко делиться ими. Кстати, на данный момент существует даже специализированный маркетплейс с более чем 15 тысячами действий.

Разработанное нами действие доступно здесь под названием ts-migration-companion-action.

Вот пример реализации, он просто следует алгоритму, описанному выше.

name: TS Migration Companion

on:
  pull_request:
    branches:
      - master

permissions:
      contents: read
      packages: read
      pull-requests: write
      issues: write

jobs:
  typescript-migration-companion:
    runs-on: ubuntu-latest
    steps:
      - name: Create tsc-output directory
        run: mkdir /tmp/tsc-output
      - name: Checkout main branch
        uses: actions/checkout@v3
        with:
          clean: false
          ref: main
      - name: Run npm install on main branch
        run: npm ci
      - name: Typecheck dependencies on main branch 
        run: npm run build > /tmp/tsc-output/main.txt
        continue-on-error: true
      - name: Checkout PR branch
        uses: actions/checkout@v3
      - name: Run npm install on PR branch
        run: npm ci
      - name: Typecheck dependencies on pr branch
        run: npm run build > /tmp/tsc-output/pr.txt
        continue-on-error: true
      - uses: swile/ts-migration-companion-action
        with:
          master_tsc_output_path: /tmp/tsc-output/main.txt
          pr_tsc_output_path: /tmp/tsc-output/pr.txt
          tsc_rootdir: src

Есть 3 параметра, которые могут быть предоставлены действию, вот описание ниже.

• master_tsc_output_path: абсолютный путь к выводу tsc главной ветки.
• pr_tsc_output_path: абсолютный путь к выходу tsc ветки PR.
• tsc_rootdir: «базовый путь», который мы используем для анализа выходных данных (обычно «src»).

Более подробную информацию об акции можно найти в соответствующем репозитории действий. Не стесняйтесь вносить свой вклад! ;)